1 /********************************************************************* 2 * SEGGER Microcontroller GmbH * 3 * The Embedded Experts * 4 ********************************************************************** 5 * * 6 * (c) 1995 - 2021 SEGGER Microcontroller GmbH * 7 * * 8 * www.segger.com Support: support@segger.com * 9 * * 10 ********************************************************************** 11 * * 12 * SEGGER RTT * Real Time Transfer for embedded targets * 13 * * 14 ********************************************************************** 15 * * 16 * All rights reserved. * 17 * * 18 * SEGGER strongly recommends to not make any changes * 19 * to or modify the source code of this software in order to stay * 20 * compatible with the RTT protocol and J-Link. * 21 * * 22 * Redistribution and use in source and binary forms, with or * 23 * without modification, are permitted provided that the following * 24 * condition is met: * 25 * * 26 * o Redistributions of source code must retain the above copyright * 27 * notice, this condition and the following disclaimer. * 28 * * 29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND * 30 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, * 31 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF * 32 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * 33 * DISCLAIMED. IN NO EVENT SHALL SEGGER Microcontroller BE LIABLE FOR * 34 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * 35 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT * 36 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; * 37 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF * 38 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * 39 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE * 40 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH * 41 * DAMAGE. * 42 * * 43 ********************************************************************** 44 * * 45 * RTT version: 7.22 * 46 * * 47 ********************************************************************** 48 49 ---------------------------END-OF-HEADER------------------------------ 50 File : SEGGER_RTT.h 51 Purpose : Implementation of SEGGER real-time transfer which allows 52 real-time communication on targets which support debugger 53 memory accesses while the CPU is running. 54 Revision: $Rev: 20869 $ 55 ---------------------------------------------------------------------- 56 */ 57 58 #ifndef SEGGER_RTT_H 59 #define SEGGER_RTT_H 60 61 #include "SEGGER_RTT_Conf.h" 62 63 /********************************************************************* 64 * 65 * Defines, defaults 66 * 67 ********************************************************************** 68 */ 69 #ifndef RTT_USE_ASM 70 #if (defined __SES_ARM) // SEGGER Embedded Studio 71 #define _CC_HAS_RTT_ASM_SUPPORT 1 72 #elif (defined __CROSSWORKS_ARM) // Rowley Crossworks 73 #define _CC_HAS_RTT_ASM_SUPPORT 1 74 #elif (defined __ARMCC_VERSION) // ARM compiler 75 #if (__ARMCC_VERSION >= 6000000) // ARM compiler V6.0 and later is clang based 76 #define _CC_HAS_RTT_ASM_SUPPORT 1 77 #else 78 #define _CC_HAS_RTT_ASM_SUPPORT 0 79 #endif 80 #elif (defined __GNUC__) // GCC 81 #define _CC_HAS_RTT_ASM_SUPPORT 1 82 #elif (defined __clang__) // Clang compiler 83 #define _CC_HAS_RTT_ASM_SUPPORT 1 84 #elif ((defined __IASMARM__) || (defined __ICCARM__)) // IAR assembler/compiler 85 #define _CC_HAS_RTT_ASM_SUPPORT 1 86 #else 87 #define _CC_HAS_RTT_ASM_SUPPORT 0 88 #endif 89 #if ((defined __IASMARM__) || (defined __ICCARM__)) // IAR assembler/compiler 90 // 91 // IAR assembler / compiler 92 // 93 #if (__VER__ < 6300000) 94 #define VOLATILE 95 #else 96 #define VOLATILE volatile 97 #endif 98 #if (defined __ARM7M__) // Needed for old versions that do not know the define yet 99 #if (__CORE__ == __ARM7M__) // Cortex-M3 100 #define _CORE_HAS_RTT_ASM_SUPPORT 1 101 #endif 102 #endif 103 #if (defined __ARM7EM__) // Needed for old versions that do not know the define yet 104 #if (__CORE__ == __ARM7EM__) // Cortex-M4/M7 105 #define _CORE_HAS_RTT_ASM_SUPPORT 1 106 #define _CORE_NEEDS_DMB 1 107 #define RTT__DMB() asm VOLATILE ("DMB"); 108 #endif 109 #endif 110 #if (defined __ARM8M_BASELINE__) // Needed for old versions that do not know the define yet 111 #if (__CORE__ == __ARM8M_BASELINE__) // Cortex-M23 112 #define _CORE_HAS_RTT_ASM_SUPPORT 0 113 #define _CORE_NEEDS_DMB 1 114 #define RTT__DMB() asm VOLATILE ("DMB"); 115 #endif 116 #endif 117 #if (defined __ARM8M_MAINLINE__) // Needed for old versions that do not know the define yet 118 #if (__CORE__ == __ARM8M_MAINLINE__) // Cortex-M33 119 #define _CORE_HAS_RTT_ASM_SUPPORT 1 120 #define _CORE_NEEDS_DMB 1 121 #define RTT__DMB() asm VOLATILE ("DMB"); 122 #endif 123 #endif 124 #else 125 // 126 // GCC / Clang 127 // 128 #if (defined __ARM_ARCH_7M__) // Cortex-M3 129 #define _CORE_HAS_RTT_ASM_SUPPORT 1 130 #elif (defined __ARM_ARCH_7EM__) // Cortex-M4/M7 131 #define _CORE_HAS_RTT_ASM_SUPPORT 1 132 #define _CORE_NEEDS_DMB 1 133 #define RTT__DMB() __asm volatile ("dmb\n" : : :); 134 #elif (defined __ARM_ARCH_8M_BASE__) // Cortex-M23 135 #define _CORE_HAS_RTT_ASM_SUPPORT 0 136 #define _CORE_NEEDS_DMB 1 137 #define RTT__DMB() __asm volatile ("dmb\n" : : :); 138 #elif (defined __ARM_ARCH_8M_MAIN__) // Cortex-M33 139 #define _CORE_HAS_RTT_ASM_SUPPORT 1 140 #define _CORE_NEEDS_DMB 1 141 #define RTT__DMB() __asm volatile ("dmb\n" : : :); 142 #else 143 #define _CORE_HAS_RTT_ASM_SUPPORT 0 144 #endif 145 #endif 146 // 147 // If IDE and core support the ASM version, enable ASM version by default 148 // 149 #ifndef _CORE_HAS_RTT_ASM_SUPPORT 150 #define _CORE_HAS_RTT_ASM_SUPPORT 0 // Default for unknown cores 151 #endif 152 #if (_CC_HAS_RTT_ASM_SUPPORT && _CORE_HAS_RTT_ASM_SUPPORT) 153 #define RTT_USE_ASM (1) 154 #else 155 #define RTT_USE_ASM (0) 156 #endif 157 #endif 158 159 // 160 // We need to know if a DMB is needed to make sure that on Cortex-M7 etc. 161 // the order of accesses to the ring buffers is guaranteed 162 // Needed for: Cortex-M7, Cortex-M23, Cortex-M33 163 // 164 #ifndef _CORE_NEEDS_DMB 165 #define _CORE_NEEDS_DMB 0 166 #endif 167 168 #ifndef RTT__DMB 169 #if _CORE_NEEDS_DMB 170 #error "Don't know how to place inline assembly for DMB" 171 #else 172 #define RTT__DMB() 173 #endif 174 #endif 175 176 #ifndef SEGGER_RTT_CPU_CACHE_LINE_SIZE 177 #define SEGGER_RTT_CPU_CACHE_LINE_SIZE (0) // On most target systems where RTT is used, we do not have a CPU cache, therefore 0 is a good default here 178 #endif 179 180 #ifndef SEGGER_RTT_UNCACHED_OFF 181 #if SEGGER_RTT_CPU_CACHE_LINE_SIZE 182 #error "SEGGER_RTT_UNCACHED_OFF must be defined when setting SEGGER_RTT_CPU_CACHE_LINE_SIZE != 0" 183 #else 184 #define SEGGER_RTT_UNCACHED_OFF (0) 185 #endif 186 #endif 187 #if RTT_USE_ASM 188 #if SEGGER_RTT_CPU_CACHE_LINE_SIZE 189 #error "RTT_USE_ASM is not available if SEGGER_RTT_CPU_CACHE_LINE_SIZE != 0" 190 #endif 191 #endif 192 193 #ifndef SEGGER_RTT_ASM // defined when SEGGER_RTT.h is included from assembly file 194 #include <stdlib.h> 195 #include <stdarg.h> 196 197 /********************************************************************* 198 * 199 * Defines, fixed 200 * 201 ********************************************************************** 202 */ 203 204 // 205 // Determine how much we must pad the control block to make it a multiple of a cache line in size 206 // Assuming: U8 = 1B 207 // U16 = 2B 208 // U32 = 4B 209 // U8/U16/U32* = 4B 210 // 211 #if SEGGER_RTT_CPU_CACHE_LINE_SIZE // Avoid division by zero in case we do not have any cache 212 #define SEGGER_RTT__ROUND_UP_2_CACHE_LINE_SIZE(NumBytes) (((NumBytes + SEGGER_RTT_CPU_CACHE_LINE_SIZE - 1) / SEGGER_RTT_CPU_CACHE_LINE_SIZE) * SEGGER_RTT_CPU_CACHE_LINE_SIZE) 213 #else 214 #define SEGGER_RTT__ROUND_UP_2_CACHE_LINE_SIZE(NumBytes) (NumBytes) 215 #endif 216 #define SEGGER_RTT__CB_SIZE (16 + 4 + 4 + (SEGGER_RTT_MAX_NUM_UP_BUFFERS * 24) + (SEGGER_RTT_MAX_NUM_DOWN_BUFFERS * 24)) 217 #define SEGGER_RTT__CB_PADDING (SEGGER_RTT__ROUND_UP_2_CACHE_LINE_SIZE(SEGGER_RTT__CB_SIZE) - SEGGER_RTT__CB_SIZE) 218 219 /********************************************************************* 220 * 221 * Types 222 * 223 ********************************************************************** 224 */ 225 226 // 227 // Description for a circular buffer (also called "ring buffer") 228 // which is used as up-buffer (T->H) 229 // 230 typedef struct { 231 const char* sName; // Optional name. Standard names so far are: "Terminal", "SysView", "J-Scope_t4i4" 232 char* pBuffer; // Pointer to start of buffer 233 unsigned SizeOfBuffer; // Buffer size in bytes. Note that one byte is lost, as this implementation does not fill up the buffer in order to avoid the problem of being unable to distinguish between full and empty. 234 unsigned WrOff; // Position of next item to be written by either target. 235 volatile unsigned RdOff; // Position of next item to be read by host. Must be volatile since it may be modified by host. 236 unsigned Flags; // Contains configuration flags 237 } SEGGER_RTT_BUFFER_UP; 238 239 // 240 // Description for a circular buffer (also called "ring buffer") 241 // which is used as down-buffer (H->T) 242 // 243 typedef struct { 244 const char* sName; // Optional name. Standard names so far are: "Terminal", "SysView", "J-Scope_t4i4" 245 char* pBuffer; // Pointer to start of buffer 246 unsigned SizeOfBuffer; // Buffer size in bytes. Note that one byte is lost, as this implementation does not fill up the buffer in order to avoid the problem of being unable to distinguish between full and empty. 247 volatile unsigned WrOff; // Position of next item to be written by host. Must be volatile since it may be modified by host. 248 unsigned RdOff; // Position of next item to be read by target (down-buffer). 249 unsigned Flags; // Contains configuration flags 250 } SEGGER_RTT_BUFFER_DOWN; 251 252 // 253 // RTT control block which describes the number of buffers available 254 // as well as the configuration for each buffer 255 // 256 // 257 typedef struct { 258 char acID[16]; // Initialized to "SEGGER RTT" 259 int MaxNumUpBuffers; // Initialized to SEGGER_RTT_MAX_NUM_UP_BUFFERS (type. 2) 260 int MaxNumDownBuffers; // Initialized to SEGGER_RTT_MAX_NUM_DOWN_BUFFERS (type. 2) 261 SEGGER_RTT_BUFFER_UP aUp[SEGGER_RTT_MAX_NUM_UP_BUFFERS]; // Up buffers, transferring information up from target via debug probe to host 262 SEGGER_RTT_BUFFER_DOWN aDown[SEGGER_RTT_MAX_NUM_DOWN_BUFFERS]; // Down buffers, transferring information down from host via debug probe to target 263 #if SEGGER_RTT__CB_PADDING 264 unsigned char aDummy[SEGGER_RTT__CB_PADDING]; 265 #endif 266 } SEGGER_RTT_CB; 267 268 /********************************************************************* 269 * 270 * Global data 271 * 272 ********************************************************************** 273 */ 274 extern SEGGER_RTT_CB _SEGGER_RTT; 275 276 /********************************************************************* 277 * 278 * RTT API functions 279 * 280 ********************************************************************** 281 */ 282 #ifdef __cplusplus 283 extern "C" { 284 #endif 285 int SEGGER_RTT_AllocDownBuffer (const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags); 286 int SEGGER_RTT_AllocUpBuffer (const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags); 287 int SEGGER_RTT_ConfigUpBuffer (unsigned BufferIndex, const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags); 288 int SEGGER_RTT_ConfigDownBuffer (unsigned BufferIndex, const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags); 289 int SEGGER_RTT_GetKey (void); 290 unsigned SEGGER_RTT_HasData (unsigned BufferIndex); 291 int SEGGER_RTT_HasKey (void); 292 unsigned SEGGER_RTT_HasDataUp (unsigned BufferIndex); 293 void SEGGER_RTT_Init (void); 294 unsigned SEGGER_RTT_Read (unsigned BufferIndex, void* pBuffer, unsigned BufferSize); 295 unsigned SEGGER_RTT_ReadNoLock (unsigned BufferIndex, void* pData, unsigned BufferSize); 296 int SEGGER_RTT_SetNameDownBuffer (unsigned BufferIndex, const char* sName); 297 int SEGGER_RTT_SetNameUpBuffer (unsigned BufferIndex, const char* sName); 298 int SEGGER_RTT_SetFlagsDownBuffer (unsigned BufferIndex, unsigned Flags); 299 int SEGGER_RTT_SetFlagsUpBuffer (unsigned BufferIndex, unsigned Flags); 300 int SEGGER_RTT_WaitKey (void); 301 unsigned SEGGER_RTT_Write (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes); 302 unsigned SEGGER_RTT_WriteNoLock (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes); 303 unsigned SEGGER_RTT_WriteSkipNoLock (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes); 304 unsigned SEGGER_RTT_ASM_WriteSkipNoLock (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes); 305 unsigned SEGGER_RTT_WriteString (unsigned BufferIndex, const char* s); 306 void SEGGER_RTT_WriteWithOverwriteNoLock(unsigned BufferIndex, const void* pBuffer, unsigned NumBytes); 307 unsigned SEGGER_RTT_PutChar (unsigned BufferIndex, char c); 308 unsigned SEGGER_RTT_PutCharSkip (unsigned BufferIndex, char c); 309 unsigned SEGGER_RTT_PutCharSkipNoLock (unsigned BufferIndex, char c); 310 unsigned SEGGER_RTT_GetAvailWriteSpace (unsigned BufferIndex); 311 unsigned SEGGER_RTT_GetBytesInBuffer (unsigned BufferIndex); 312 // 313 // Function macro for performance optimization 314 // 315 #define SEGGER_RTT_HASDATA(n) (((SEGGER_RTT_BUFFER_DOWN*)((char*)&_SEGGER_RTT.aDown[n] + SEGGER_RTT_UNCACHED_OFF))->WrOff - ((SEGGER_RTT_BUFFER_DOWN*)((char*)&_SEGGER_RTT.aDown[n] + SEGGER_RTT_UNCACHED_OFF))->RdOff) 316 317 #if RTT_USE_ASM 318 #define SEGGER_RTT_WriteSkipNoLock SEGGER_RTT_ASM_WriteSkipNoLock 319 #endif 320 321 /********************************************************************* 322 * 323 * RTT transfer functions to send RTT data via other channels. 324 * 325 ********************************************************************** 326 */ 327 unsigned SEGGER_RTT_ReadUpBuffer (unsigned BufferIndex, void* pBuffer, unsigned BufferSize); 328 unsigned SEGGER_RTT_ReadUpBufferNoLock (unsigned BufferIndex, void* pData, unsigned BufferSize); 329 unsigned SEGGER_RTT_WriteDownBuffer (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes); 330 unsigned SEGGER_RTT_WriteDownBufferNoLock (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes); 331 332 #define SEGGER_RTT_HASDATA_UP(n) (((SEGGER_RTT_BUFFER_UP*)((char*)&_SEGGER_RTT.aUp[n] + SEGGER_RTT_UNCACHED_OFF))->WrOff - ((SEGGER_RTT_BUFFER_UP*)((char*)&_SEGGER_RTT.aUp[n] + SEGGER_RTT_UNCACHED_OFF))->RdOff) // Access uncached to make sure we see changes made by the J-Link side and all of our changes go into HW directly 333 334 /********************************************************************* 335 * 336 * RTT "Terminal" API functions 337 * 338 ********************************************************************** 339 */ 340 int SEGGER_RTT_SetTerminal (unsigned char TerminalId); 341 int SEGGER_RTT_TerminalOut (unsigned char TerminalId, const char* s); 342 343 /********************************************************************* 344 * 345 * RTT printf functions (require SEGGER_RTT_printf.c) 346 * 347 ********************************************************************** 348 */ 349 int SEGGER_RTT_printf(unsigned BufferIndex, const char * sFormat, ...); 350 int SEGGER_RTT_vprintf(unsigned BufferIndex, const char * sFormat, va_list * pParamList); 351 352 #ifdef __cplusplus 353 } 354 #endif 355 356 #endif // ifndef(SEGGER_RTT_ASM) 357 358 /********************************************************************* 359 * 360 * Defines 361 * 362 ********************************************************************** 363 */ 364 365 // 366 // Operating modes. Define behavior if buffer is full (not enough space for entire message) 367 // 368 #define SEGGER_RTT_MODE_NO_BLOCK_SKIP (0) // Skip. Do not block, output nothing. (Default) 369 #define SEGGER_RTT_MODE_NO_BLOCK_TRIM (1) // Trim: Do not block, output as much as fits. 370 #define SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL (2) // Block: Wait until there is space in the buffer. 371 #define SEGGER_RTT_MODE_MASK (3) 372 373 // 374 // Control sequences, based on ANSI. 375 // Can be used to control color, and clear the screen 376 // 377 #define RTT_CTRL_RESET "\x1B[0m" // Reset to default colors 378 #define RTT_CTRL_CLEAR "\x1B[2J" // Clear screen, reposition cursor to top left 379 380 #define RTT_CTRL_TEXT_BLACK "\x1B[2;30m" 381 #define RTT_CTRL_TEXT_RED "\x1B[2;31m" 382 #define RTT_CTRL_TEXT_GREEN "\x1B[2;32m" 383 #define RTT_CTRL_TEXT_YELLOW "\x1B[2;33m" 384 #define RTT_CTRL_TEXT_BLUE "\x1B[2;34m" 385 #define RTT_CTRL_TEXT_MAGENTA "\x1B[2;35m" 386 #define RTT_CTRL_TEXT_CYAN "\x1B[2;36m" 387 #define RTT_CTRL_TEXT_WHITE "\x1B[2;37m" 388 389 #define RTT_CTRL_TEXT_BRIGHT_BLACK "\x1B[1;30m" 390 #define RTT_CTRL_TEXT_BRIGHT_RED "\x1B[1;31m" 391 #define RTT_CTRL_TEXT_BRIGHT_GREEN "\x1B[1;32m" 392 #define RTT_CTRL_TEXT_BRIGHT_YELLOW "\x1B[1;33m" 393 #define RTT_CTRL_TEXT_BRIGHT_BLUE "\x1B[1;34m" 394 #define RTT_CTRL_TEXT_BRIGHT_MAGENTA "\x1B[1;35m" 395 #define RTT_CTRL_TEXT_BRIGHT_CYAN "\x1B[1;36m" 396 #define RTT_CTRL_TEXT_BRIGHT_WHITE "\x1B[1;37m" 397 398 #define RTT_CTRL_BG_BLACK "\x1B[24;40m" 399 #define RTT_CTRL_BG_RED "\x1B[24;41m" 400 #define RTT_CTRL_BG_GREEN "\x1B[24;42m" 401 #define RTT_CTRL_BG_YELLOW "\x1B[24;43m" 402 #define RTT_CTRL_BG_BLUE "\x1B[24;44m" 403 #define RTT_CTRL_BG_MAGENTA "\x1B[24;45m" 404 #define RTT_CTRL_BG_CYAN "\x1B[24;46m" 405 #define RTT_CTRL_BG_WHITE "\x1B[24;47m" 406 407 #define RTT_CTRL_BG_BRIGHT_BLACK "\x1B[4;40m" 408 #define RTT_CTRL_BG_BRIGHT_RED "\x1B[4;41m" 409 #define RTT_CTRL_BG_BRIGHT_GREEN "\x1B[4;42m" 410 #define RTT_CTRL_BG_BRIGHT_YELLOW "\x1B[4;43m" 411 #define RTT_CTRL_BG_BRIGHT_BLUE "\x1B[4;44m" 412 #define RTT_CTRL_BG_BRIGHT_MAGENTA "\x1B[4;45m" 413 #define RTT_CTRL_BG_BRIGHT_CYAN "\x1B[4;46m" 414 #define RTT_CTRL_BG_BRIGHT_WHITE "\x1B[4;47m" 415 416 417 #endif 418 419 /*************************** End of file ****************************/ 420
