src/rtt/rtt.h

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