git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-Plus-Trace/streamports/Jlink_RTT/include/trcStreamingPort.h

   1 /*******************************************************************************\r
   2  * Trace Recorder Library for Tracealyzer v4.1.5\r
   3  * Percepio AB, www.percepio.com\r
   4  *\r
   5  * trcStreamingPort.h\r
   6  *\r
   7  * The interface definitions for trace streaming ("stream ports").\r
   8  * This "stream port" sets up the recorder to use SEGGER RTT as streaming channel.\r
   9  *\r
  10  * Note that this stream port is more complex than the typical case, since\r
  11  * the J-Link interface uses a separate RAM buffer in SEGGER_RTT.c, instead\r
  12  * of the default buffer included in the recorder core. The other stream ports \r
  13  * offer more typical examples of how to define a custom streaming interface.\r
  14  *\r
  15  * Terms of Use\r
  16  * This file is part of the trace recorder library (RECORDER), which is the \r
  17  * intellectual property of Percepio AB (PERCEPIO) and provided under a\r
  18  * license as follows.\r
  19  * The RECORDER may be used free of charge for the purpose of recording data\r
  20  * intended for analysis in PERCEPIO products. It may not be used or modified\r
  21  * for other purposes without explicit permission from PERCEPIO.\r
  22  * You may distribute the RECORDER in its original source code form, assuming\r
  23  * this text (terms of use, disclaimer, copyright notice) is unchanged. You are\r
  24  * allowed to distribute the RECORDER with minor modifications intended for\r
  25  * configuration or porting of the RECORDER, e.g., to allow using it on a \r
  26  * specific processor, processor family or with a specific communication\r
  27  * interface. Any such modifications should be documented directly below\r
  28  * this comment block.  \r
  29  *\r
  30  * Disclaimer\r
  31  * The RECORDER is being delivered to you AS IS and PERCEPIO makes no warranty\r
  32  * as to its use or performance. PERCEPIO does not and cannot warrant the \r
  33  * performance or results you may obtain by using the RECORDER or documentation.\r
  34  * PERCEPIO make no warranties, express or implied, as to noninfringement of\r
  35  * third party rights, merchantability, or fitness for any particular purpose.\r
  36  * In no event will PERCEPIO, its technology partners, or distributors be liable\r
  37  * to you for any consequential, incidental or special damages, including any\r
  38  * lost profits or lost savings, even if a representative of PERCEPIO has been\r
  39  * advised of the possibility of such damages, or for any claim by any third\r
  40  * party. Some jurisdictions do not allow the exclusion or limitation of\r
  41  * incidental, consequential or special damages, or the exclusion of implied\r
  42  * warranties or limitations on how long an implied warranty may last, so the\r
  43  * above limitations may not apply to you.\r
  44  *\r
  45  * Tabs are used for indent in this file (1 tab = 4 spaces)\r
  46  *\r
  47  * Copyright Percepio AB, 2018.\r
  48  * www.percepio.com\r
  49  ******************************************************************************/\r
  50 \r
  51 #ifndef TRC_STREAMING_PORT_H\r
  52 #define TRC_STREAMING_PORT_H\r
  53 \r
  54 #ifdef __cplusplus\r
  55 extern "C" {\r
  56 #endif\r
  57 \r
  58 \r
  59 /*******************************************************************************\r
  60  * Configuration Macro: TRC_CFG_RTT_BUFFER_SIZE_UP\r
  61  *\r
  62  * Defines the size of the "up" RTT buffer (target -> host) to use for writing\r
  63  * the trace data, for RTT buffer 1 or higher.\r
  64  *\r
  65  * This setting is ignored for RTT buffer 0, which can't be reconfigured\r
  66  * in runtime and therefore hard-coded to use the defines in SEGGER_RTT_Conf.h.\r
  67  *\r
  68  * Default buffer size for Tracealyzer is 5000 bytes. \r
  69  *\r
  70  * If you have a stand-alone J-Link probe, the can be decreased to around 1 KB.\r
  71  * But integrated J-Link OB interfaces are slower and needs about 5-10 KB, \r
  72  * depending on the amount of data produced.\r
  73  ******************************************************************************/\r
  74 #define TRC_CFG_RTT_BUFFER_SIZE_UP 5000\r
  75 \r
  76 /*******************************************************************************\r
  77  * Configuration Macro: TRC_CFG_RTT_BUFFER_SIZE_DOWN\r
  78  *\r
  79  * Defines the size of the "down" RTT buffer (host -> target) to use for reading\r
  80  * commands from Tracealyzer, for RTT buffer 1 or higher.\r
  81  *\r
  82  * Default buffer size for Tracealyzer is 32 bytes.\r
  83  *\r
  84  * This setting is ignored for RTT buffer 0, which can't be reconfigured\r
  85  * in runtime and therefore hard-coded to use the defines in SEGGER_RTT_Conf.h.\r
  86  ******************************************************************************/\r
  87 #define TRC_CFG_RTT_BUFFER_SIZE_DOWN 32\r
  88 \r
  89 /*******************************************************************************\r
  90  * Configuration Macro: TRC_CFG_RTT_UP_BUFFER_INDEX\r
  91  *\r
  92  * Defines the RTT buffer to use for writing the trace data. Make sure that\r
  93  * the PC application has the same setting (File->Settings).\r
  94  *\r
  95  * Default: 1\r
  96  *\r
  97  * We don't recommend using RTT buffer 0, since mainly intended for terminals.\r
  98  * If you prefer to use buffer 0, it must be configured in SEGGER_RTT_Conf.h. \r
  99  ******************************************************************************/\r
 100 #define TRC_CFG_RTT_UP_BUFFER_INDEX 1\r
 101 \r
 102 /*******************************************************************************\r
 103  * Configuration Macro: TRC_CFG_RTT_DOWN_BUFFER_INDEX\r
 104  *\r
 105  * Defines the RTT buffer to use for reading the trace data. Make sure that\r
 106  * the PC application has the same setting (File->Settings).\r
 107  *\r
 108  * Default: 1\r
 109  *\r
 110  * We don't recommend using RTT buffer 0, since mainly intended for terminals.\r
 111  * If you prefer to use buffer 0, it must be configured in SEGGER_RTT_Conf.h. \r
 112  ******************************************************************************/\r
 113 #define TRC_CFG_RTT_DOWN_BUFFER_INDEX 1\r
 114 \r
 115 /*******************************************************************************\r
 116  * TRC_CFG_RTT_MODE\r
 117  * This stream port for J-Link streaming relies on SEGGER RTT, that contains an\r
 118  * internal RAM buffer read by the J-Link probes during execution.\r
 119  *\r
 120  * Possible values:\r
 121  * - SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL \r
 122  * - SEGGER_RTT_MODE_NO_BLOCK_SKIP (default)\r
 123  *\r
 124  * Using SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL ensure that you get a\r
 125  * complete and valid trace. This may however cause blocking if your streaming\r
 126  * interface isn't fast enough, which may disturb the real-time behavior.\r
 127  * \r
 128  * We therefore recommend SEGGER_RTT_MODE_NO_BLOCK_SKIP. In this mode, \r
 129  * Tracealyzer will report lost events if the transfer is not\r
 130  * fast enough. In that case, try increasing the size of the "up buffer".\r
 131  ******************************************************************************/\r
 132 #define TRC_CFG_RTT_MODE SEGGER_RTT_MODE_NO_BLOCK_SKIP\r
 133 \r
 134 #include "SEGGER_RTT_Conf.h"\r
 135 #include "SEGGER_RTT.h"\r
 136 \r
 137 #if (TRC_CFG_RTT_UP_BUFFER_INDEX >= SEGGER_RTT_MAX_NUM_UP_BUFFERS)\r
 138 #error "TRC_CFG_RTT_UP_BUFFER_INDEX must be smaller than SEGGER_RTT_MAX_NUM_UP_BUFFERS"\r
 139 #endif\r
 140 \r
 141 #if (TRC_CFG_RTT_DOWN_BUFFER_INDEX >= SEGGER_RTT_MAX_NUM_DOWN_BUFFERS)\r
 142 #error "TRC_CFG_RTT_DOWN_BUFFER_INDEX must be smaller than SEGGER_RTT_MAX_NUM_DOWN_BUFFERS"\r
 143 #endif\r
 144 \r
 145 /* If index is defined as 0, the internal RTT buffers will be used instead of this. */\r
 146 #if TRC_CFG_RTT_UP_BUFFER_INDEX == 0\r
 147 #define TRC_RTT_ALLOC_UP() static char* _TzTraceData = NULL;    /* Not actually used. Ignore allocation method. */\r
 148 #define TRC_STREAM_PORT_MALLOC() /* Static allocation. Not used. */\r
 149 #else\r
 150 #if TRC_CFG_RECORDER_BUFFER_ALLOCATION == TRC_RECORDER_BUFFER_ALLOCATION_STATIC\r
 151 #define TRC_RTT_ALLOC_UP() char _TzTraceData[TRC_CFG_RTT_BUFFER_SIZE_UP];    /* Static allocation */\r
 152 #define TRC_STREAM_PORT_MALLOC() /* Static allocation. Not used. */\r
 153 #endif\r
 154 #if TRC_CFG_RECORDER_BUFFER_ALLOCATION == TRC_RECORDER_BUFFER_ALLOCATION_DYNAMIC\r
 155 #define TRC_RTT_ALLOC_UP() char* _TzTraceData = NULL;    /* Dynamic allocation */\r
 156 #define TRC_STREAM_PORT_MALLOC() _TzTraceData = TRC_PORT_MALLOC(TRC_CFG_RTT_BUFFER_SIZE_UP);\r
 157 #endif\r
 158 #if TRC_CFG_RECORDER_BUFFER_ALLOCATION == TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM\r
 159 #define TRC_RTT_ALLOC_UP() char* _TzTraceData = NULL;                                   /* Custom allocation, user needs to call vTraceSetRecorderDataBuffer before vTraceEnable, to assign this */ \r
 160 #define TRC_STREAM_PORT_MALLOC()                                                                                /* Not used in custom mode */\r
 161 #endif\r
 162 #endif\r
 163 \r
 164 /* Down-buffer. If index is defined as 0, the internal RTT buffers will be used instead of this. */ \\r
 165 #if TRC_CFG_RTT_DOWN_BUFFER_INDEX == 0\r
 166 #define TRC_RTT_ALLOC_DOWN() static char* _TzCtrlData = NULL;           /* Not actually used. Ignore allocation method. */\r
 167 #else\r
 168 #define TRC_RTT_ALLOC_DOWN() static char _TzCtrlData[TRC_CFG_RTT_BUFFER_SIZE_DOWN]; /* Always static allocation, since usually small. */\r
 169 #endif\r
 170   \r
 171 #define TRC_STREAM_PORT_ALLOCATE_FIELDS() \\r
 172         TRC_RTT_ALLOC_UP() /* Macro that will result in proper UP buffer allocation */ \\r
 173         TRC_RTT_ALLOC_DOWN() /* Macro that will result in proper DOWN buffer allocation */\r
 174 \r
 175 int32_t readFromRTT(void* ptrData, uint32_t size, int32_t* ptrBytesRead);\r
 176 \r
 177 int32_t writeToRTT(void* ptrData, uint32_t size, int32_t* ptrBytesWritten);\r
 178 \r
 179 \r
 180 #define TRC_STREAM_PORT_INIT() \\r
 181         TRC_STREAM_PORT_MALLOC(); /*Dynamic allocation or empty if static */ \\r
 182         SEGGER_RTT_ConfigUpBuffer(TRC_CFG_RTT_UP_BUFFER_INDEX, "TzData", _TzTraceData, TRC_CFG_RTT_BUFFER_SIZE_UP, TRC_CFG_RTT_MODE ); \\r
 183         SEGGER_RTT_ConfigDownBuffer(TRC_CFG_RTT_DOWN_BUFFER_INDEX, "TzCtrl", _TzCtrlData, TRC_CFG_RTT_BUFFER_SIZE_DOWN, TRC_CFG_RTT_MODE);\r
 184 \r
 185 /* Important for the J-Link port, in most other ports this can be skipped (default is 1) */\r
 186 #define TRC_STREAM_PORT_USE_INTERNAL_BUFFER 0\r
 187   \r
 188 #define TRC_STREAM_PORT_WRITE_DATA(_ptrData, _size, _ptrBytesWritten) writeToRTT(_ptrData, _size, _ptrBytesWritten)\r
 189 \r
 190 #define TRC_STREAM_PORT_READ_DATA(_ptrData, _size, _ptrBytesRead) readFromRTT(_ptrData, _size, _ptrBytesRead)\r
 191 \r
 192 #ifdef __cplusplus\r
 193 }\r
 194 #endif\r
 195 \r
 196 #endif /* TRC_STREAMING_PORT_H */\r