xref: /btstack/3rd-party/segger-rtt/SEGGER_RTT.h (revision ce6f85e79d1d141c1b45dfa16b2671762457cbb4)
17dc86dfdSMatthias Ringwald /*********************************************************************
2779af47bSMatthias Ringwald *                    SEGGER Microcontroller GmbH                     *
3779af47bSMatthias Ringwald *                        The Embedded Experts                        *
47dc86dfdSMatthias Ringwald **********************************************************************
57dc86dfdSMatthias Ringwald *                                                                    *
6779af47bSMatthias Ringwald *            (c) 1995 - 2019 SEGGER Microcontroller GmbH             *
77dc86dfdSMatthias Ringwald *                                                                    *
87dc86dfdSMatthias Ringwald *       www.segger.com     Support: [email protected]               *
97dc86dfdSMatthias Ringwald *                                                                    *
107dc86dfdSMatthias Ringwald **********************************************************************
117dc86dfdSMatthias Ringwald *                                                                    *
127dc86dfdSMatthias Ringwald *       SEGGER RTT * Real Time Transfer for embedded targets         *
137dc86dfdSMatthias Ringwald *                                                                    *
147dc86dfdSMatthias Ringwald **********************************************************************
157dc86dfdSMatthias Ringwald *                                                                    *
167dc86dfdSMatthias Ringwald * All rights reserved.                                               *
177dc86dfdSMatthias Ringwald *                                                                    *
187dc86dfdSMatthias Ringwald * SEGGER strongly recommends to not make any changes                 *
197dc86dfdSMatthias Ringwald * to or modify the source code of this software in order to stay     *
207dc86dfdSMatthias Ringwald * compatible with the RTT protocol and J-Link.                       *
217dc86dfdSMatthias Ringwald *                                                                    *
227dc86dfdSMatthias Ringwald * Redistribution and use in source and binary forms, with or         *
237dc86dfdSMatthias Ringwald * without modification, are permitted provided that the following    *
24*ce6f85e7SMatthias Ringwald * condition is met:                                                  *
257dc86dfdSMatthias Ringwald *                                                                    *
267dc86dfdSMatthias Ringwald * o Redistributions of source code must retain the above copyright   *
27*ce6f85e7SMatthias Ringwald *   notice, this condition and the following disclaimer.             *
287dc86dfdSMatthias Ringwald *                                                                    *
297dc86dfdSMatthias Ringwald * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND             *
307dc86dfdSMatthias Ringwald * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,        *
317dc86dfdSMatthias Ringwald * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF           *
327dc86dfdSMatthias Ringwald * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE           *
337dc86dfdSMatthias Ringwald * DISCLAIMED. IN NO EVENT SHALL SEGGER Microcontroller BE LIABLE FOR *
347dc86dfdSMatthias Ringwald * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR           *
357dc86dfdSMatthias Ringwald * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT  *
367dc86dfdSMatthias Ringwald * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;    *
377dc86dfdSMatthias Ringwald * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF      *
387dc86dfdSMatthias Ringwald * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT          *
397dc86dfdSMatthias Ringwald * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE  *
407dc86dfdSMatthias Ringwald * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH   *
417dc86dfdSMatthias Ringwald * DAMAGE.                                                            *
427dc86dfdSMatthias Ringwald *                                                                    *
437dc86dfdSMatthias Ringwald **********************************************************************
447dc86dfdSMatthias Ringwald ---------------------------END-OF-HEADER------------------------------
457dc86dfdSMatthias Ringwald File    : SEGGER_RTT.h
467dc86dfdSMatthias Ringwald Purpose : Implementation of SEGGER real-time transfer which allows
477dc86dfdSMatthias Ringwald           real-time communication on targets which support debugger
487dc86dfdSMatthias Ringwald           memory accesses while the CPU is running.
49*ce6f85e7SMatthias Ringwald Revision: $Rev: 25842 $
507dc86dfdSMatthias Ringwald ----------------------------------------------------------------------
517dc86dfdSMatthias Ringwald */
527dc86dfdSMatthias Ringwald 
537dc86dfdSMatthias Ringwald #ifndef SEGGER_RTT_H
547dc86dfdSMatthias Ringwald #define SEGGER_RTT_H
557dc86dfdSMatthias Ringwald 
567dc86dfdSMatthias Ringwald #include "SEGGER_RTT_Conf.h"
577dc86dfdSMatthias Ringwald 
58779af47bSMatthias Ringwald /*********************************************************************
59779af47bSMatthias Ringwald *
60779af47bSMatthias Ringwald *       Defines, defaults
61779af47bSMatthias Ringwald *
62779af47bSMatthias Ringwald **********************************************************************
63779af47bSMatthias Ringwald */
64*ce6f85e7SMatthias Ringwald 
65779af47bSMatthias Ringwald #ifndef RTT_USE_ASM
66*ce6f85e7SMatthias Ringwald   //
67*ce6f85e7SMatthias Ringwald   // Some cores support out-of-order memory accesses (reordering of memory accesses in the core)
68*ce6f85e7SMatthias Ringwald   // For such cores, we need to define a memory barrier to guarantee the order of certain accesses to the RTT ring buffers.
69*ce6f85e7SMatthias Ringwald   // Needed for:
70*ce6f85e7SMatthias Ringwald   //   Cortex-M7 (ARMv7-M)
71*ce6f85e7SMatthias Ringwald   //   Cortex-M23 (ARM-v8M)
72*ce6f85e7SMatthias Ringwald   //   Cortex-M33 (ARM-v8M)
73*ce6f85e7SMatthias Ringwald   //   Cortex-A/R (ARM-v7A/R)
74*ce6f85e7SMatthias Ringwald   //
75*ce6f85e7SMatthias Ringwald   // We do not explicitly check for "Embedded Studio" as the compiler in use determines what we support.
76*ce6f85e7SMatthias Ringwald   // You can use an external toolchain like IAR inside ES. So there is no point in checking for "Embedded Studio"
77*ce6f85e7SMatthias Ringwald   //
78*ce6f85e7SMatthias Ringwald   #if (defined __CROSSWORKS_ARM)                  // Rowley Crossworks
79779af47bSMatthias Ringwald     #define _CC_HAS_RTT_ASM_SUPPORT 1
80*ce6f85e7SMatthias Ringwald     #if (defined __ARM_ARCH_7M__)                 // Cortex-M3
81*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
82*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_7EM__)              // Cortex-M4/M7
83*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
84*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
85*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
86*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_8M_BASE__)          // Cortex-M23
87*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 0
88*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
89*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
90*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_8M_MAIN__)          // Cortex-M33
91*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
92*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
93*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
94*ce6f85e7SMatthias Ringwald     #else
95*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 0
96*ce6f85e7SMatthias Ringwald     #endif
97*ce6f85e7SMatthias Ringwald   #elif (defined __ARMCC_VERSION)
98*ce6f85e7SMatthias Ringwald     //
99*ce6f85e7SMatthias Ringwald     // ARM compiler
100*ce6f85e7SMatthias Ringwald     // ARM compiler V6.0 and later is clang based.
101*ce6f85e7SMatthias Ringwald     // Our ASM part is compatible to clang.
102*ce6f85e7SMatthias Ringwald     //
103*ce6f85e7SMatthias Ringwald     #if (__ARMCC_VERSION >= 6000000)
104779af47bSMatthias Ringwald       #define _CC_HAS_RTT_ASM_SUPPORT 1
105779af47bSMatthias Ringwald     #else
106779af47bSMatthias Ringwald       #define _CC_HAS_RTT_ASM_SUPPORT 0
107779af47bSMatthias Ringwald     #endif
108*ce6f85e7SMatthias Ringwald     #if (defined __ARM_ARCH_6M__)                 // Cortex-M0 / M1
109*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 0         // No ASM support for this architecture
110*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_7M__)               // Cortex-M3
111779af47bSMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
112*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_7EM__)              // Cortex-M4/M7
113779af47bSMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
114*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
115*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
116*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_8M_BASE__)          // Cortex-M23
117*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 0
118*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
119*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
120779af47bSMatthias Ringwald     #elif (defined __ARM_ARCH_8M_MAIN__)          // Cortex-M33
121779af47bSMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
122*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
123*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
124*ce6f85e7SMatthias Ringwald     #elif ((defined __ARM_ARCH_7A__) || (defined __ARM_ARCH_7R__))  // Cortex-A/R 32-bit ARMv7-A/R
125*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
126*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
127779af47bSMatthias Ringwald     #else
128779af47bSMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 0
129779af47bSMatthias Ringwald     #endif
130*ce6f85e7SMatthias Ringwald   #elif ((defined __GNUC__) || (defined __clang__))
131*ce6f85e7SMatthias Ringwald     //
132*ce6f85e7SMatthias Ringwald     // GCC / Clang
133*ce6f85e7SMatthias Ringwald     //
134*ce6f85e7SMatthias Ringwald     #define _CC_HAS_RTT_ASM_SUPPORT 1
135*ce6f85e7SMatthias Ringwald     // ARM 7/9: __ARM_ARCH_5__ / __ARM_ARCH_5E__ / __ARM_ARCH_5T__ / __ARM_ARCH_5T__ / __ARM_ARCH_5TE__
136*ce6f85e7SMatthias Ringwald     #if (defined __ARM_ARCH_7M__)                 // Cortex-M3
137779af47bSMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
138*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_7EM__)              // Cortex-M4/M7
139*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
140*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1         // Only Cortex-M7 needs a DMB but we cannot distinguish M4 and M7 here...
141*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
142*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_8M_BASE__)          // Cortex-M23
143*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 0
144*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
145*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
146*ce6f85e7SMatthias Ringwald     #elif (defined __ARM_ARCH_8M_MAIN__)          // Cortex-M33
147*ce6f85e7SMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 1
148*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
149*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
150*ce6f85e7SMatthias Ringwald     #elif ((defined __ARM_ARCH_7A__) || (defined __ARM_ARCH_7R__))  // Cortex-A/R 32-bit ARMv7-A/R
151*ce6f85e7SMatthias Ringwald       #define _CORE_NEEDS_DMB           1
152*ce6f85e7SMatthias Ringwald       #define RTT__DMB() __asm volatile ("dmb\n" : : :);
153779af47bSMatthias Ringwald     #else
154779af47bSMatthias Ringwald       #define _CORE_HAS_RTT_ASM_SUPPORT 0
155779af47bSMatthias Ringwald     #endif
156*ce6f85e7SMatthias Ringwald   #elif ((defined __IASMARM__) || (defined __ICCARM__))
157*ce6f85e7SMatthias Ringwald     //
158*ce6f85e7SMatthias Ringwald     // IAR assembler/compiler
159*ce6f85e7SMatthias Ringwald     //
160*ce6f85e7SMatthias Ringwald     #define _CC_HAS_RTT_ASM_SUPPORT 1
161*ce6f85e7SMatthias Ringwald     #if (__VER__ < 6300000)
162*ce6f85e7SMatthias Ringwald       #define VOLATILE
163779af47bSMatthias Ringwald     #else
164*ce6f85e7SMatthias Ringwald       #define VOLATILE volatile
165*ce6f85e7SMatthias Ringwald     #endif
166*ce6f85e7SMatthias Ringwald     #if (defined __ARM7M__)                            // Needed for old versions that do not know the define yet
167*ce6f85e7SMatthias Ringwald       #if (__CORE__ == __ARM7M__)                      // Cortex-M3
168*ce6f85e7SMatthias Ringwald         #define _CORE_HAS_RTT_ASM_SUPPORT 1
169*ce6f85e7SMatthias Ringwald       #endif
170*ce6f85e7SMatthias Ringwald     #endif
171*ce6f85e7SMatthias Ringwald     #if (defined __ARM7EM__)
172*ce6f85e7SMatthias Ringwald       #if (__CORE__ == __ARM7EM__)                     // Cortex-M4/M7
173*ce6f85e7SMatthias Ringwald         #define _CORE_HAS_RTT_ASM_SUPPORT 1
174*ce6f85e7SMatthias Ringwald         #define _CORE_NEEDS_DMB 1
175*ce6f85e7SMatthias Ringwald         #define RTT__DMB() asm VOLATILE ("DMB");
176*ce6f85e7SMatthias Ringwald       #endif
177*ce6f85e7SMatthias Ringwald     #endif
178*ce6f85e7SMatthias Ringwald     #if (defined __ARM8M_BASELINE__)
179*ce6f85e7SMatthias Ringwald       #if (__CORE__ == __ARM8M_BASELINE__)             // Cortex-M23
180*ce6f85e7SMatthias Ringwald         #define _CORE_HAS_RTT_ASM_SUPPORT 0
181*ce6f85e7SMatthias Ringwald         #define _CORE_NEEDS_DMB 1
182*ce6f85e7SMatthias Ringwald         #define RTT__DMB() asm VOLATILE ("DMB");
183*ce6f85e7SMatthias Ringwald       #endif
184*ce6f85e7SMatthias Ringwald     #endif
185*ce6f85e7SMatthias Ringwald     #if (defined __ARM8M_MAINLINE__)
186*ce6f85e7SMatthias Ringwald       #if (__CORE__ == __ARM8M_MAINLINE__)             // Cortex-M33
187*ce6f85e7SMatthias Ringwald         #define _CORE_HAS_RTT_ASM_SUPPORT 1
188*ce6f85e7SMatthias Ringwald         #define _CORE_NEEDS_DMB 1
189*ce6f85e7SMatthias Ringwald         #define RTT__DMB() asm VOLATILE ("DMB");
190*ce6f85e7SMatthias Ringwald       #endif
191*ce6f85e7SMatthias Ringwald     #endif
192*ce6f85e7SMatthias Ringwald     #if (defined __ARM8EM_MAINLINE__)
193*ce6f85e7SMatthias Ringwald       #if (__CORE__ == __ARM8EM_MAINLINE__)            // Cortex-???
194*ce6f85e7SMatthias Ringwald         #define _CORE_HAS_RTT_ASM_SUPPORT 1
195*ce6f85e7SMatthias Ringwald         #define _CORE_NEEDS_DMB 1
196*ce6f85e7SMatthias Ringwald         #define RTT__DMB() asm VOLATILE ("DMB");
197*ce6f85e7SMatthias Ringwald       #endif
198*ce6f85e7SMatthias Ringwald     #endif
199*ce6f85e7SMatthias Ringwald     #if (defined __ARM7A__)
200*ce6f85e7SMatthias Ringwald       #if (__CORE__ == __ARM7A__)                      // Cortex-A 32-bit ARMv7-A
201*ce6f85e7SMatthias Ringwald         #define _CORE_NEEDS_DMB 1
202*ce6f85e7SMatthias Ringwald         #define RTT__DMB() asm VOLATILE ("DMB");
203*ce6f85e7SMatthias Ringwald       #endif
204*ce6f85e7SMatthias Ringwald     #endif
205*ce6f85e7SMatthias Ringwald     #if (defined __ARM7R__)
206*ce6f85e7SMatthias Ringwald       #if (__CORE__ == __ARM7R__)                      // Cortex-R 32-bit ARMv7-R
207*ce6f85e7SMatthias Ringwald         #define _CORE_NEEDS_DMB 1
208*ce6f85e7SMatthias Ringwald         #define RTT__DMB() asm VOLATILE ("DMB");
209*ce6f85e7SMatthias Ringwald       #endif
210*ce6f85e7SMatthias Ringwald     #endif
211*ce6f85e7SMatthias Ringwald // TBD: __ARM8A__ => Cortex-A 64-bit ARMv8-A
212*ce6f85e7SMatthias Ringwald // TBD: __ARM8R__ => Cortex-R 64-bit ARMv8-R
213*ce6f85e7SMatthias Ringwald   #else
214*ce6f85e7SMatthias Ringwald     //
215*ce6f85e7SMatthias Ringwald     // Other compilers
216*ce6f85e7SMatthias Ringwald     //
217*ce6f85e7SMatthias Ringwald     #define _CC_HAS_RTT_ASM_SUPPORT   0
218779af47bSMatthias Ringwald     #define _CORE_HAS_RTT_ASM_SUPPORT 0
219779af47bSMatthias Ringwald   #endif
220779af47bSMatthias Ringwald   //
221779af47bSMatthias Ringwald   // If IDE and core support the ASM version, enable ASM version by default
222779af47bSMatthias Ringwald   //
223*ce6f85e7SMatthias Ringwald   #ifndef _CORE_HAS_RTT_ASM_SUPPORT
224*ce6f85e7SMatthias Ringwald     #define _CORE_HAS_RTT_ASM_SUPPORT 0              // Default for unknown cores
225*ce6f85e7SMatthias Ringwald   #endif
226779af47bSMatthias Ringwald   #if (_CC_HAS_RTT_ASM_SUPPORT && _CORE_HAS_RTT_ASM_SUPPORT)
227779af47bSMatthias Ringwald     #define RTT_USE_ASM                           (1)
228779af47bSMatthias Ringwald   #else
229779af47bSMatthias Ringwald     #define RTT_USE_ASM                           (0)
230779af47bSMatthias Ringwald   #endif
231779af47bSMatthias Ringwald #endif
232779af47bSMatthias Ringwald 
233*ce6f85e7SMatthias Ringwald #ifndef _CORE_NEEDS_DMB
234*ce6f85e7SMatthias Ringwald   #define _CORE_NEEDS_DMB 0
235*ce6f85e7SMatthias Ringwald #endif
236*ce6f85e7SMatthias Ringwald 
237*ce6f85e7SMatthias Ringwald #ifndef RTT__DMB
238*ce6f85e7SMatthias Ringwald   #if _CORE_NEEDS_DMB
239*ce6f85e7SMatthias Ringwald     #error "Don't know how to place inline assembly for DMB"
240*ce6f85e7SMatthias Ringwald   #else
241*ce6f85e7SMatthias Ringwald     #define RTT__DMB()
242*ce6f85e7SMatthias Ringwald   #endif
243*ce6f85e7SMatthias Ringwald #endif
244*ce6f85e7SMatthias Ringwald 
245*ce6f85e7SMatthias Ringwald #ifndef SEGGER_RTT_CPU_CACHE_LINE_SIZE
246*ce6f85e7SMatthias Ringwald   #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
247*ce6f85e7SMatthias Ringwald #endif
248*ce6f85e7SMatthias Ringwald 
249*ce6f85e7SMatthias Ringwald #ifndef SEGGER_RTT_UNCACHED_OFF
250*ce6f85e7SMatthias Ringwald   #if SEGGER_RTT_CPU_CACHE_LINE_SIZE
251*ce6f85e7SMatthias Ringwald     #error "SEGGER_RTT_UNCACHED_OFF must be defined when setting SEGGER_RTT_CPU_CACHE_LINE_SIZE != 0"
252*ce6f85e7SMatthias Ringwald   #else
253*ce6f85e7SMatthias Ringwald     #define SEGGER_RTT_UNCACHED_OFF (0)
254*ce6f85e7SMatthias Ringwald   #endif
255*ce6f85e7SMatthias Ringwald #endif
256*ce6f85e7SMatthias Ringwald #if RTT_USE_ASM
257*ce6f85e7SMatthias Ringwald   #if SEGGER_RTT_CPU_CACHE_LINE_SIZE
258*ce6f85e7SMatthias Ringwald     #error "RTT_USE_ASM is not available if SEGGER_RTT_CPU_CACHE_LINE_SIZE != 0"
259*ce6f85e7SMatthias Ringwald   #endif
260*ce6f85e7SMatthias Ringwald #endif
261*ce6f85e7SMatthias Ringwald 
262779af47bSMatthias Ringwald #ifndef SEGGER_RTT_ASM  // defined when SEGGER_RTT.h is included from assembly file
263779af47bSMatthias Ringwald #include <stdlib.h>
264779af47bSMatthias Ringwald #include <stdarg.h>
265779af47bSMatthias Ringwald 
2667dc86dfdSMatthias Ringwald /*********************************************************************
2677dc86dfdSMatthias Ringwald *
2687dc86dfdSMatthias Ringwald *       Defines, fixed
2697dc86dfdSMatthias Ringwald *
2707dc86dfdSMatthias Ringwald **********************************************************************
2717dc86dfdSMatthias Ringwald */
2727dc86dfdSMatthias Ringwald 
273*ce6f85e7SMatthias Ringwald //
274*ce6f85e7SMatthias Ringwald // Determine how much we must pad the control block to make it a multiple of a cache line in size
275*ce6f85e7SMatthias Ringwald // Assuming: U8 = 1B
276*ce6f85e7SMatthias Ringwald //           U16 = 2B
277*ce6f85e7SMatthias Ringwald //           U32 = 4B
278*ce6f85e7SMatthias Ringwald //           U8/U16/U32* = 4B
279*ce6f85e7SMatthias Ringwald //
280*ce6f85e7SMatthias Ringwald #if SEGGER_RTT_CPU_CACHE_LINE_SIZE    // Avoid division by zero in case we do not have any cache
281*ce6f85e7SMatthias Ringwald   #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)
282*ce6f85e7SMatthias Ringwald #else
283*ce6f85e7SMatthias Ringwald   #define SEGGER_RTT__ROUND_UP_2_CACHE_LINE_SIZE(NumBytes) (NumBytes)
284*ce6f85e7SMatthias Ringwald #endif
285*ce6f85e7SMatthias Ringwald #define SEGGER_RTT__CB_SIZE                              (16 + 4 + 4 + (SEGGER_RTT_MAX_NUM_UP_BUFFERS * 24) + (SEGGER_RTT_MAX_NUM_DOWN_BUFFERS * 24))
286*ce6f85e7SMatthias Ringwald #define SEGGER_RTT__CB_PADDING                           (SEGGER_RTT__ROUND_UP_2_CACHE_LINE_SIZE(SEGGER_RTT__CB_SIZE) - SEGGER_RTT__CB_SIZE)
287*ce6f85e7SMatthias Ringwald 
2887dc86dfdSMatthias Ringwald /*********************************************************************
2897dc86dfdSMatthias Ringwald *
2907dc86dfdSMatthias Ringwald *       Types
2917dc86dfdSMatthias Ringwald *
2927dc86dfdSMatthias Ringwald **********************************************************************
2937dc86dfdSMatthias Ringwald */
2947dc86dfdSMatthias Ringwald 
2957dc86dfdSMatthias Ringwald //
2967dc86dfdSMatthias Ringwald // Description for a circular buffer (also called "ring buffer")
2977dc86dfdSMatthias Ringwald // which is used as up-buffer (T->H)
2987dc86dfdSMatthias Ringwald //
2997dc86dfdSMatthias Ringwald typedef struct {
3007dc86dfdSMatthias Ringwald   const     char*    sName;         // Optional name. Standard names so far are: "Terminal", "SysView", "J-Scope_t4i4"
3017dc86dfdSMatthias Ringwald             char*    pBuffer;       // Pointer to start of buffer
3027dc86dfdSMatthias Ringwald             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.
3037dc86dfdSMatthias Ringwald             unsigned WrOff;         // Position of next item to be written by either target.
3047dc86dfdSMatthias Ringwald   volatile  unsigned RdOff;         // Position of next item to be read by host. Must be volatile since it may be modified by host.
305*ce6f85e7SMatthias Ringwald             unsigned Flags;         // Contains configuration flags. Flags[31:24] are used for validity check and must be zero. Flags[23:2] are reserved for future use. Flags[1:0] = RTT operating mode.
3067dc86dfdSMatthias Ringwald } SEGGER_RTT_BUFFER_UP;
3077dc86dfdSMatthias Ringwald 
3087dc86dfdSMatthias Ringwald //
3097dc86dfdSMatthias Ringwald // Description for a circular buffer (also called "ring buffer")
3107dc86dfdSMatthias Ringwald // which is used as down-buffer (H->T)
3117dc86dfdSMatthias Ringwald //
3127dc86dfdSMatthias Ringwald typedef struct {
3137dc86dfdSMatthias Ringwald   const     char*    sName;         // Optional name. Standard names so far are: "Terminal", "SysView", "J-Scope_t4i4"
3147dc86dfdSMatthias Ringwald             char*    pBuffer;       // Pointer to start of buffer
3157dc86dfdSMatthias Ringwald             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.
3167dc86dfdSMatthias Ringwald   volatile  unsigned WrOff;         // Position of next item to be written by host. Must be volatile since it may be modified by host.
3177dc86dfdSMatthias Ringwald             unsigned RdOff;         // Position of next item to be read by target (down-buffer).
318*ce6f85e7SMatthias Ringwald             unsigned Flags;         // Contains configuration flags. Flags[31:24] are used for validity check and must be zero. Flags[23:2] are reserved for future use. Flags[1:0] = RTT operating mode.
3197dc86dfdSMatthias Ringwald } SEGGER_RTT_BUFFER_DOWN;
3207dc86dfdSMatthias Ringwald 
3217dc86dfdSMatthias Ringwald //
3227dc86dfdSMatthias Ringwald // RTT control block which describes the number of buffers available
3237dc86dfdSMatthias Ringwald // as well as the configuration for each buffer
3247dc86dfdSMatthias Ringwald //
3257dc86dfdSMatthias Ringwald //
3267dc86dfdSMatthias Ringwald typedef struct {
3277dc86dfdSMatthias Ringwald   char                    acID[16];                                 // Initialized to "SEGGER RTT"
3287dc86dfdSMatthias Ringwald   int                     MaxNumUpBuffers;                          // Initialized to SEGGER_RTT_MAX_NUM_UP_BUFFERS (type. 2)
3297dc86dfdSMatthias Ringwald   int                     MaxNumDownBuffers;                        // Initialized to SEGGER_RTT_MAX_NUM_DOWN_BUFFERS (type. 2)
3307dc86dfdSMatthias Ringwald   SEGGER_RTT_BUFFER_UP    aUp[SEGGER_RTT_MAX_NUM_UP_BUFFERS];       // Up buffers, transferring information up from target via debug probe to host
3317dc86dfdSMatthias Ringwald   SEGGER_RTT_BUFFER_DOWN  aDown[SEGGER_RTT_MAX_NUM_DOWN_BUFFERS];   // Down buffers, transferring information down from host via debug probe to target
332*ce6f85e7SMatthias Ringwald #if SEGGER_RTT__CB_PADDING
333*ce6f85e7SMatthias Ringwald   unsigned char           aDummy[SEGGER_RTT__CB_PADDING];
334*ce6f85e7SMatthias Ringwald #endif
3357dc86dfdSMatthias Ringwald } SEGGER_RTT_CB;
3367dc86dfdSMatthias Ringwald 
3377dc86dfdSMatthias Ringwald /*********************************************************************
3387dc86dfdSMatthias Ringwald *
3397dc86dfdSMatthias Ringwald *       Global data
3407dc86dfdSMatthias Ringwald *
3417dc86dfdSMatthias Ringwald **********************************************************************
3427dc86dfdSMatthias Ringwald */
3437dc86dfdSMatthias Ringwald extern SEGGER_RTT_CB _SEGGER_RTT;
3447dc86dfdSMatthias Ringwald 
3457dc86dfdSMatthias Ringwald /*********************************************************************
3467dc86dfdSMatthias Ringwald *
3477dc86dfdSMatthias Ringwald *       RTT API functions
3487dc86dfdSMatthias Ringwald *
3497dc86dfdSMatthias Ringwald **********************************************************************
3507dc86dfdSMatthias Ringwald */
3517dc86dfdSMatthias Ringwald #ifdef __cplusplus
3527dc86dfdSMatthias Ringwald   extern "C" {
3537dc86dfdSMatthias Ringwald #endif
3547dc86dfdSMatthias Ringwald int          SEGGER_RTT_AllocDownBuffer         (const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags);
3557dc86dfdSMatthias Ringwald int          SEGGER_RTT_AllocUpBuffer           (const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags);
3567dc86dfdSMatthias Ringwald int          SEGGER_RTT_ConfigUpBuffer          (unsigned BufferIndex, const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags);
3577dc86dfdSMatthias Ringwald int          SEGGER_RTT_ConfigDownBuffer        (unsigned BufferIndex, const char* sName, void* pBuffer, unsigned BufferSize, unsigned Flags);
3587dc86dfdSMatthias Ringwald int          SEGGER_RTT_GetKey                  (void);
3597dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_HasData                 (unsigned BufferIndex);
3607dc86dfdSMatthias Ringwald int          SEGGER_RTT_HasKey                  (void);
361779af47bSMatthias Ringwald unsigned     SEGGER_RTT_HasDataUp               (unsigned BufferIndex);
3627dc86dfdSMatthias Ringwald void         SEGGER_RTT_Init                    (void);
3637dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_Read                    (unsigned BufferIndex,       void* pBuffer, unsigned BufferSize);
3647dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_ReadNoLock              (unsigned BufferIndex,       void* pData,   unsigned BufferSize);
3657dc86dfdSMatthias Ringwald int          SEGGER_RTT_SetNameDownBuffer       (unsigned BufferIndex, const char* sName);
3667dc86dfdSMatthias Ringwald int          SEGGER_RTT_SetNameUpBuffer         (unsigned BufferIndex, const char* sName);
3677dc86dfdSMatthias Ringwald int          SEGGER_RTT_SetFlagsDownBuffer      (unsigned BufferIndex, unsigned Flags);
3687dc86dfdSMatthias Ringwald int          SEGGER_RTT_SetFlagsUpBuffer        (unsigned BufferIndex, unsigned Flags);
3697dc86dfdSMatthias Ringwald int          SEGGER_RTT_WaitKey                 (void);
3707dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_Write                   (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes);
3717dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_WriteNoLock             (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes);
3727dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_WriteSkipNoLock         (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes);
373779af47bSMatthias Ringwald unsigned     SEGGER_RTT_ASM_WriteSkipNoLock     (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes);
3747dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_WriteString             (unsigned BufferIndex, const char* s);
3757dc86dfdSMatthias Ringwald void         SEGGER_RTT_WriteWithOverwriteNoLock(unsigned BufferIndex, const void* pBuffer, unsigned NumBytes);
3767dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_PutChar                 (unsigned BufferIndex, char c);
3777dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_PutCharSkip             (unsigned BufferIndex, char c);
3787dc86dfdSMatthias Ringwald unsigned     SEGGER_RTT_PutCharSkipNoLock       (unsigned BufferIndex, char c);
379a20be900SMatthias Ringwald unsigned     SEGGER_RTT_GetAvailWriteSpace      (unsigned BufferIndex);
380*ce6f85e7SMatthias Ringwald unsigned     SEGGER_RTT_GetBytesInBuffer        (unsigned BufferIndex);
3817dc86dfdSMatthias Ringwald //
3827dc86dfdSMatthias Ringwald // Function macro for performance optimization
3837dc86dfdSMatthias Ringwald //
384*ce6f85e7SMatthias Ringwald #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)
3857dc86dfdSMatthias Ringwald 
386779af47bSMatthias Ringwald #if RTT_USE_ASM
387779af47bSMatthias Ringwald   #define SEGGER_RTT_WriteSkipNoLock  SEGGER_RTT_ASM_WriteSkipNoLock
388779af47bSMatthias Ringwald #endif
389779af47bSMatthias Ringwald 
3907dc86dfdSMatthias Ringwald /*********************************************************************
3917dc86dfdSMatthias Ringwald *
392*ce6f85e7SMatthias Ringwald *       RTT transfer functions to send RTT data via other channels.
393*ce6f85e7SMatthias Ringwald *
394*ce6f85e7SMatthias Ringwald **********************************************************************
395*ce6f85e7SMatthias Ringwald */
396*ce6f85e7SMatthias Ringwald unsigned     SEGGER_RTT_ReadUpBuffer            (unsigned BufferIndex, void* pBuffer, unsigned BufferSize);
397*ce6f85e7SMatthias Ringwald unsigned     SEGGER_RTT_ReadUpBufferNoLock      (unsigned BufferIndex, void* pData, unsigned BufferSize);
398*ce6f85e7SMatthias Ringwald unsigned     SEGGER_RTT_WriteDownBuffer         (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes);
399*ce6f85e7SMatthias Ringwald unsigned     SEGGER_RTT_WriteDownBufferNoLock   (unsigned BufferIndex, const void* pBuffer, unsigned NumBytes);
400*ce6f85e7SMatthias Ringwald 
401*ce6f85e7SMatthias Ringwald #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
402*ce6f85e7SMatthias Ringwald 
403*ce6f85e7SMatthias Ringwald /*********************************************************************
404*ce6f85e7SMatthias Ringwald *
4057dc86dfdSMatthias Ringwald *       RTT "Terminal" API functions
4067dc86dfdSMatthias Ringwald *
4077dc86dfdSMatthias Ringwald **********************************************************************
4087dc86dfdSMatthias Ringwald */
409779af47bSMatthias Ringwald int     SEGGER_RTT_SetTerminal        (unsigned char TerminalId);
410779af47bSMatthias Ringwald int     SEGGER_RTT_TerminalOut        (unsigned char TerminalId, const char* s);
4117dc86dfdSMatthias Ringwald 
4127dc86dfdSMatthias Ringwald /*********************************************************************
4137dc86dfdSMatthias Ringwald *
4147dc86dfdSMatthias Ringwald *       RTT printf functions (require SEGGER_RTT_printf.c)
4157dc86dfdSMatthias Ringwald *
4167dc86dfdSMatthias Ringwald **********************************************************************
4177dc86dfdSMatthias Ringwald */
4187dc86dfdSMatthias Ringwald int SEGGER_RTT_printf(unsigned BufferIndex, const char * sFormat, ...);
419779af47bSMatthias Ringwald int SEGGER_RTT_vprintf(unsigned BufferIndex, const char * sFormat, va_list * pParamList);
420779af47bSMatthias Ringwald 
4217dc86dfdSMatthias Ringwald #ifdef __cplusplus
4227dc86dfdSMatthias Ringwald   }
4237dc86dfdSMatthias Ringwald #endif
4247dc86dfdSMatthias Ringwald 
425779af47bSMatthias Ringwald #endif // ifndef(SEGGER_RTT_ASM)
426779af47bSMatthias Ringwald 
4277dc86dfdSMatthias Ringwald /*********************************************************************
4287dc86dfdSMatthias Ringwald *
4297dc86dfdSMatthias Ringwald *       Defines
4307dc86dfdSMatthias Ringwald *
4317dc86dfdSMatthias Ringwald **********************************************************************
4327dc86dfdSMatthias Ringwald */
4337dc86dfdSMatthias Ringwald 
4347dc86dfdSMatthias Ringwald //
4357dc86dfdSMatthias Ringwald // Operating modes. Define behavior if buffer is full (not enough space for entire message)
4367dc86dfdSMatthias Ringwald //
437779af47bSMatthias Ringwald #define SEGGER_RTT_MODE_NO_BLOCK_SKIP         (0)     // Skip. Do not block, output nothing. (Default)
438779af47bSMatthias Ringwald #define SEGGER_RTT_MODE_NO_BLOCK_TRIM         (1)     // Trim: Do not block, output as much as fits.
439779af47bSMatthias Ringwald #define SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL    (2)     // Block: Wait until there is space in the buffer.
440779af47bSMatthias Ringwald #define SEGGER_RTT_MODE_MASK                  (3)
4417dc86dfdSMatthias Ringwald 
4427dc86dfdSMatthias Ringwald //
4437dc86dfdSMatthias Ringwald // Control sequences, based on ANSI.
4447dc86dfdSMatthias Ringwald // Can be used to control color, and clear the screen
4457dc86dfdSMatthias Ringwald //
446779af47bSMatthias Ringwald #define RTT_CTRL_RESET                "\x1B[0m"         // Reset to default colors
447779af47bSMatthias Ringwald #define RTT_CTRL_CLEAR                "\x1B[2J"         // Clear screen, reposition cursor to top left
4487dc86dfdSMatthias Ringwald 
449779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BLACK           "\x1B[2;30m"
450779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_RED             "\x1B[2;31m"
451779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_GREEN           "\x1B[2;32m"
452779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_YELLOW          "\x1B[2;33m"
453779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BLUE            "\x1B[2;34m"
454779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_MAGENTA         "\x1B[2;35m"
455779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_CYAN            "\x1B[2;36m"
456779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_WHITE           "\x1B[2;37m"
4577dc86dfdSMatthias Ringwald 
458779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BRIGHT_BLACK    "\x1B[1;30m"
459779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BRIGHT_RED      "\x1B[1;31m"
460779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BRIGHT_GREEN    "\x1B[1;32m"
461779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BRIGHT_YELLOW   "\x1B[1;33m"
462779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BRIGHT_BLUE     "\x1B[1;34m"
463779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BRIGHT_MAGENTA  "\x1B[1;35m"
464779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BRIGHT_CYAN     "\x1B[1;36m"
465779af47bSMatthias Ringwald #define RTT_CTRL_TEXT_BRIGHT_WHITE    "\x1B[1;37m"
4667dc86dfdSMatthias Ringwald 
467779af47bSMatthias Ringwald #define RTT_CTRL_BG_BLACK             "\x1B[24;40m"
468779af47bSMatthias Ringwald #define RTT_CTRL_BG_RED               "\x1B[24;41m"
469779af47bSMatthias Ringwald #define RTT_CTRL_BG_GREEN             "\x1B[24;42m"
470779af47bSMatthias Ringwald #define RTT_CTRL_BG_YELLOW            "\x1B[24;43m"
471779af47bSMatthias Ringwald #define RTT_CTRL_BG_BLUE              "\x1B[24;44m"
472779af47bSMatthias Ringwald #define RTT_CTRL_BG_MAGENTA           "\x1B[24;45m"
473779af47bSMatthias Ringwald #define RTT_CTRL_BG_CYAN              "\x1B[24;46m"
474779af47bSMatthias Ringwald #define RTT_CTRL_BG_WHITE             "\x1B[24;47m"
4757dc86dfdSMatthias Ringwald 
476779af47bSMatthias Ringwald #define RTT_CTRL_BG_BRIGHT_BLACK      "\x1B[4;40m"
477779af47bSMatthias Ringwald #define RTT_CTRL_BG_BRIGHT_RED        "\x1B[4;41m"
478779af47bSMatthias Ringwald #define RTT_CTRL_BG_BRIGHT_GREEN      "\x1B[4;42m"
479779af47bSMatthias Ringwald #define RTT_CTRL_BG_BRIGHT_YELLOW     "\x1B[4;43m"
480779af47bSMatthias Ringwald #define RTT_CTRL_BG_BRIGHT_BLUE       "\x1B[4;44m"
481779af47bSMatthias Ringwald #define RTT_CTRL_BG_BRIGHT_MAGENTA    "\x1B[4;45m"
482779af47bSMatthias Ringwald #define RTT_CTRL_BG_BRIGHT_CYAN       "\x1B[4;46m"
483779af47bSMatthias Ringwald #define RTT_CTRL_BG_BRIGHT_WHITE      "\x1B[4;47m"
4847dc86dfdSMatthias Ringwald 
4857dc86dfdSMatthias Ringwald 
4867dc86dfdSMatthias Ringwald #endif
4877dc86dfdSMatthias Ringwald 
4887dc86dfdSMatthias Ringwald /*************************** End of file ****************************/
489