src/rtt/rtt.h

   1 /*
   2  * Copyright (C) 2016-2020 by Marc Schink <dev@zapb.de>
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #ifndef OPENOCD_RTT_RTT_H
  19 #define OPENOCD_RTT_RTT_H
  20
  21 #include <stdint.h>
  22 #include <stdbool.h>
  23
  24 #include <helper/command.h>
  25 #include <target/target.h>
  26
  27 /**
  28  * Control block ID length in bytes, including the trailing null-terminator.
  29  */
  30 #define RTT_CB_MAX_ID_LENGTH    16
  31
  32 /* Control block size in bytes. */
  33 #define RTT_CB_SIZE             (RTT_CB_MAX_ID_LENGTH + 2 * sizeof(uint32_t))
  34
  35 /* Channel structure size in bytes. */
  36 #define RTT_CHANNEL_SIZE        24
  37
  38 /* Minimal channel buffer size in bytes. */
  39 #define RTT_CHANNEL_BUFFER_MIN_SIZE     2
  40
  41 /** RTT control block. */
  42 struct rtt_control {
  43         /** Control block address on the target. */
  44         target_addr_t address;
  45         /** Control block identifier, including trailing null-terminator. */
  46         char id[RTT_CB_MAX_ID_LENGTH];
  47         /** Maximum number of up-channels. */
  48         uint32_t num_up_channels;
  49         /** Maximum number of down-channels. */
  50         uint32_t num_down_channels;
  51 };
  52
  53 /** RTT channel. */
  54 struct rtt_channel {
  55         /** Channel structure address on the target. */
  56         target_addr_t address;
  57         /** Channel name address on the target. */
  58         uint32_t name_addr;
  59         /** Buffer address on the target. */
  60         uint32_t buffer_addr;
  61         /** Channel buffer size in bytes. */
  62         uint32_t size;
  63         /**  Write position within the buffer in bytes. */
  64         uint32_t write_pos;
  65         /** Read position within the buffer in bytes. */
  66         uint32_t read_pos;
  67         /**
  68          * Buffer flags.
  69          *
  70          * @note: Not used at the moment.
  71          */
  72         uint32_t flags;
  73 };
  74
  75 /** RTT channel information. */
  76 struct rtt_channel_info {
  77         /** Channel name. */
  78         char *name;
  79         /** Length of the name in bytes, including the trailing null-terminator. */
  80         size_t name_length;
  81         /** Buffer size in bytes. */
  82         uint32_t size;
  83         /**
  84          * Buffer flags.
  85          *
  86          * @note: Not used at the moment.
  87          */
  88         uint32_t flags;
  89 };
  90
  91 typedef int (*rtt_sink_read)(unsigned int channel, const uint8_t *buffer,
  92                 size_t length, void *user_data);
  93
  94 struct rtt_sink_list {
  95         rtt_sink_read read;
  96         void *user_data;
  97
  98         struct rtt_sink_list *next;
  99 };
 100
 101 /** Channel type. */
 102 enum rtt_channel_type {
 103         /** Up channel (target to host). */
 104         RTT_CHANNEL_TYPE_UP,
 105         /** Down channel (host to target). */
 106         RTT_CHANNEL_TYPE_DOWN
 107 };
 108
 109 typedef int (*rtt_source_find_ctrl_block)(struct target *target,
 110                 target_addr_t *address, size_t size, const char *id, bool *found,
 111                 void *user_data);
 112 typedef int (*rtt_source_read_ctrl_block)(struct target *target,
 113                 target_addr_t address, struct rtt_control *ctrl_block,
 114                 void *user_data);
 115 typedef int (*rtt_source_read_channel_info)(struct target *target,
 116                 const struct rtt_control *ctrl, unsigned int channel,
 117                 enum rtt_channel_type type, struct rtt_channel_info *info,
 118                 void *user_data);
 119 typedef int (*rtt_source_start)(struct target *target,
 120                 const struct rtt_control *ctrl, void *user_data);
 121 typedef int (*rtt_source_stop)(struct target *target, void *user_data);
 122 typedef int (*rtt_source_read)(struct target *target,
 123                 const struct rtt_control *ctrl, struct rtt_sink_list **sinks,
 124                 size_t num_channels, void *user_data);
 125 typedef int (*rtt_source_write)(struct target *target,
 126                 struct rtt_control *ctrl, unsigned int channel,
 127                 const uint8_t *buffer, size_t *length, void *user_data);
 128
 129 /** RTT source. */
 130 struct rtt_source {
 131         rtt_source_find_ctrl_block find_cb;
 132         rtt_source_read_ctrl_block read_cb;
 133         rtt_source_read_channel_info read_channel_info;
 134         rtt_source_start start;
 135         rtt_source_stop stop;
 136         rtt_source_read read;
 137         rtt_source_write write;
 138 };
 139
 140 /**
 141  * Initialize Real-Time Transfer (RTT).
 142  *
 143  * @returns ERROR_OK on success, an error code on failure.
 144  */
 145 int rtt_init(void);
 146
 147 /**
 148  * Shutdown Real-Time Transfer (RTT).
 149  *
 150  * @returns ERROR_OK on success, an error code on failure.
 151  */
 152 int rtt_exit(void);
 153
 154 /**
 155  * Register an RTT source for a target.
 156  *
 157  * @param[in] source RTT source.
 158  * @param[in,out] target Target.
 159  *
 160  * @returns ERROR_OK on success, an error code on failure.
 161  */
 162 int rtt_register_source(const struct rtt_source source,
 163                 struct target *target);
 164
 165 /**
 166  * Setup RTT.
 167  *
 168  * @param[in] address Start address to search for the control block.
 169  * @param[in] size Size of the control block search area.
 170  * @param[in] id Identifier of the control block. Must be null-terminated.
 171  *
 172  * @returns ERROR_OK on success, an error code on failure.
 173  */
 174 int rtt_setup(target_addr_t address, size_t size, const char *id);
 175
 176 /**
 177  * Start Real-Time Transfer (RTT).
 178  *
 179  * @returns ERROR_OK on success, an error code on failure.
 180  */
 181 int rtt_start(void);
 182
 183 /**
 184  * Stop Real-Time Transfer (RTT).
 185  *
 186  * @returns ERROR_OK on success, an error code on failure.
 187  */
 188 int rtt_stop(void);
 189
 190 /**
 191  * Get the polling interval.
 192  *
 193  * @param[out] interval Polling interval in milliseconds.
 194  *
 195  * @returns ERROR_OK on success, an error code on failure.
 196  */
 197 int rtt_get_polling_interval(unsigned int *interval);
 198
 199 /**
 200  * Set the polling interval.
 201  *
 202  * @param[in] interval Polling interval in milliseconds.
 203  *
 204  * @returns ERROR_OK on success, an error code on failure.
 205  */
 206 int rtt_set_polling_interval(unsigned int interval);
 207
 208 /**
 209  * Get whether RTT is started.
 210  *
 211  * @returns Whether RTT is started.
 212  */
 213 bool rtt_started(void);
 214
 215 /**
 216  * Get whether RTT is configured.
 217  *
 218  * @returns Whether RTT is configured.
 219  */
 220 bool rtt_configured(void);
 221
 222 /**
 223  * Get whether RTT control block was found.
 224  *
 225  * @returns Whether RTT was found.
 226  */
 227 bool rtt_found_cb(void);
 228
 229 /**
 230  * Get the RTT control block.
 231  *
 232  * @returns The RTT control block.
 233  */
 234 const struct rtt_control *rtt_get_control(void);
 235
 236 /**
 237  * Read channel information.
 238  *
 239  * @param[in] channel_index Channel index.
 240  * @param[in] type Channel type.
 241  * @param[out] info Channel information.
 242  *
 243  * @returns ERROR_OK on success, an error code on failure.
 244  */
 245 int rtt_read_channel_info(unsigned int channel_index,
 246         enum rtt_channel_type type, struct rtt_channel_info *info);
 247
 248 /**
 249  * Register an RTT sink.
 250  *
 251  * @param[in] channel_index Channel index.
 252  * @param[in] read Read callback function.
 253  * @param[in,out] user_data User data to be passed to the callback function.
 254  *
 255  * @returns ERROR_OK on success, an error code on failure.
 256  */
 257 int rtt_register_sink(unsigned int channel_index, rtt_sink_read read,
 258                 void *user_data);
 259
 260 /**
 261  * Unregister an RTT sink.
 262  *
 263  * @param[in] channel_index Channel index.
 264  * @param[in] read Read callback function.
 265  * @param[in,out] user_data User data to be passed to the callback function.
 266  *
 267  * @returns ERROR_OK on success, an error code on failure.
 268  */
 269 int rtt_unregister_sink(unsigned int channel_index, rtt_sink_read read,
 270                 void *user_data);
 271
 272 /**
 273  * Write to an RTT channel.
 274  *
 275  * @param[in] channel_index Channel index.
 276  * @param[in] buffer Buffer with data that should be written to the channel.
 277  * @param[in,out] length Number of bytes to write. On success, the argument gets
 278  *                       updated with the actual number of written bytes.
 279  *
 280  * @returns ERROR_OK on success, an error code on failure.
 281  */
 282 int rtt_write_channel(unsigned int channel_index, const uint8_t *buffer,
 283                 size_t *length);
 284
 285 extern const struct command_registration rtt_target_command_handlers[];
 286
 287 #endif /* OPENOCD_RTT_RTT_H */