ITM.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2020-2021, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /*!*****************************************************************************
33  * @file ITM.h
34  * @brief ITM driver header
35  *
36  * @anchor ti_drivers_ITM_Overview
37  * <h3> Overview </h3>
38  * This driver implements APIs to configure and control the ARM Instrumentation
39  * Trace Macrocell (ITM), Debug Watchpoint and Trace (DWT), and Trace Port
40  * Instrumentation Unit (TPIU) IPs to realize non-intrusive software logging
41  * and runtime trace.
42  *
43  * # Overview <a name="overview"></a>
44  * The ITM software module provides application level APIs for the non-invasive
45  * debug capabilities of the ARM Cortex-M family. This includes the following
46  * hardware modules:
47  *
48  * - Instrumentation Trace Macrocell (ITM)
49  * - Debug Watchpoint and Trace (DWT)
50  * - Trace Port Instrumentation Unit (TPIU)
51  *
52  * At a high level, the DWT provides watchpoint, data trace, and program
53  * counter sampling. The ITM provides memory mapped registers for low-intrusion
54  * software profiling. The TPIU provides an external interface for the ITM and
55  * DWT. Further details can be found in the
56  * [ARMv7-M Architecture Reference Manual](https://static.docs.arm.com/ddi0403/e/DDI0403E_d_armv7m_arm.pdf)
57  *
58  * <h3> Limitations and Constraints </h3>
59  * The driver is is designed with the following constraints in mind:
60  * - ITM is designed as a singleton. This means that a single instance is
61  * shared across all clients
62  * - The parallel TracePort mode of the TPIU is not supported, only
63  * serial protocols are considered
64  * - The ITM hardware is configured via firmware on the DUT.
65  * Log records can be read independent of any IDE or debugger configuration.
66  * This means that if the IDE debug system configures the ITM, it should
67  * be turned off.
68  * - In Code Composer Studio, it is not currently possible to disable
69  * the debugger configuration mentioned above. No ITM output will be visible
70  * while the IDE's debugger is connected. Please flash your firmware, then
71  * disconnect and reset the device to see ITM data on the serial port.
72  *
73  * @anchor ti_drivers_ITM_Setup
74  * <h3> Setup </h3>
75  * The ITM is configured via hardware attributes stored in the hardware
76  * attributes structure. This structure contains a common portion that is used
77  * for all drivers. This structure may be extended for some devices such as
78  * CC26XX.
79  *
80  * <h3> Opening the driver </h3>
81  * Unlike other drivers, the ITM is intended to be a singleton.
82  * This means that @ref ITM_open can be called multiple times.
83  * The ITM will only be configured the first time open is called.
84  *
85  * Furthermore, helper functions for features such as PC sampling must coherent
86  * across clients. The driver offers no protection against mismatched
87  * configuration.
88  *
89  * The open call will enable ITM as well as the necessary stimulus ports.
90  * It will setup the TPIU for necessary baudrate and serial format.
91  *
92  * @anchor ti_drivers_ITM_PinMux
93  * <h3> Pin Muxing </h3>
94  * As the ITM driver is primarily interfacing to ARM defined IP, it is almost
95  * entirely common across all supported devices. The only specifics are pin
96  * muxing of the SWO pin. See the table below for some notes
97 
98  * | Device Family | Debug Protocol | Muxing | Configurable? |
99  * |---------------|----------------|-----------------|---------------|
100  * | CC32XX | SWD | Shared with TDO | N |
101  * | CC13XX/CC26XX | JTAG/cJTAG | Any pin | Y |
102  *
103  * Device specific pin muxing is done by the device specific ITM backend
104  * implementation.
105  *
106  * @anchor ti_drivers_ITM_SwMessages
107  * <h3> Software Messages </h3>
108  * The ITM stimulus ports enable serialization of application data with low
109  * overhead. There are multiple ports available, they are selectable via
110  * software.
111  *
112  * Data written to the software stimulus ports is serialized by the TPIU
113  * and wrapped in the SWIT packet format. This packet format is standardized
114  * by ARM and described in [ARMv7-M Architecture Reference
115  Manual](https://static.docs.arm.com/ddi0403/e/DDI0403E_d_armv7m_arm.pdf)
116  *
117  * There are three tiers of access to the stimulus ports. In the table below,
118  * polled access means that the API/macro will poll the port's busy flag
119  * before writing. This is done to prevent silent data loss that
120  * occurs when writing to a port that is not ready. Actual serialization of the
121  * data will occur later inside the TPIU.
122  *
123  * - ITM_PortX - Macro to write or read to the port, doesn't poll before
124  * - ITM_sendXPolling - Macro that polls and writes to the port
125  * - ITM_sendXAtomic - Function that calls ITM_sendXPolling with interrupts
126  * disabled
127  *
128  * It is up the the application writer to understand the tradeoff associated
129  * with each of these and select the correct one.
130  *
131  * <h3> DWT Features </h3>
132  * The Data Watchpoint and Trace (DWT) module is capable of many
133  * instrumentation features such as
134  *
135  * | Feature | ITM API |
136  * |--------------------------|-------------------------------------|
137  * | Exception trace | @ref ITM_enableExceptionTrace |
138  * | Program Counter sampling | @ref ITM_enablePCSampling |
139  * | Event counting | @ref ITM_enableEventCounter |
140  * | Synchronization packets | @ref ITM_enableSyncPackets |
141  *
142  *
143  * Data generated by the DWT is serialized via the TPIU. DWT packet formats
144  * are defined in the ARMv7-M Architecture Reference Manual referenced above
145  *
146  * <h3>Flush </h3>
147  * The ITM/DWT/TPIU hardware resides in the CPU power domain. This means that
148  * whenever the CPU domain is powered down, ITM will power down.
149  * Powering down when data is inside in the TPIU can result in lost data.
150  * In order to prevent dataloss, the device's power policy will flush the
151  * ITM before powering down the CPU domain. When returning from sleep, the
152  * power policy will restore the ITM. This is achieved using the
153  * @ref ITM_flush and @ref ITM_restore.
154  *
155  * These functions are weakly defined as empty functions. This reduces the
156  * overhead in the power policy when ITM is not enabled. These weak functions
157  * are overridden by syscfg when ITM is enabled.
158  *
159  */
160 
161 #ifndef ti_drivers_ITM__include
162 #define ti_drivers_ITM__include
163 
164 #include <stddef.h>
165 #include <stdbool.h>
166 #include <stdint.h>
167 
168 #ifdef __cplusplus
169 extern "C" {
170 #endif
171 
176 #define ITM_BASE_ADDR (0xE0000000)
177 
182 #define ITM_DWT_BASE_ADDR (0xE0001000)
183 
188 #define ITM_SCS_BASE_ADDR (0xE000E000)
189 
194 #define ITM_TPIU_BASE_ADDR (0xE0040000)
195 
202 #define ITM_LAR_UNLOCK (0xC5ACCE55)
203 
210 #define ITM_port32(n) (*((volatile unsigned int *)(ITM_BASE_ADDR + 4 * n)))
211 
212 /* The do {} while() loops below are to protect the macros so that they're
213  * evaluated correctly regardless of the call site. They do not have any
214  * function besides ensuring that the syntax is preserved correctly by the pre
215  * processor.
216  */
223 #define ITM_send32Polling(n, x) \
224  do \
225  { \
226  while (0 == ITM_port32(n)) \
227  ; \
228  ITM_port32(n) = x; \
229  } while (0)
230 
236 #define ITM_port16(n) (*((volatile unsigned short *)(ITM_BASE_ADDR + 4 * n)))
237 
244 #define ITM_send16Polling(n, x) \
245  do \
246  { \
247  while (0 == ITM_port16(n)) \
248  ; \
249  ITM_port16(n) = x; \
250  } while (0)
251 
257 #define ITM_port8(n) (*((volatile unsigned char *)(ITM_BASE_ADDR + 4 * n)))
258 
265 #define ITM_send8Polling(n, x) \
266  do \
267  { \
268  while (0 == ITM_port8(n)) \
269  ; \
270  ITM_port8(n) = x; \
271  } while (0)
272 
273 typedef enum
274 {
275  ITM_TPIU_SWO_MANCHESTER = 0x00000001,
276  ITM_TPIU_SWO_UART = 0x00000002,
278 
280 /* This enables a common defintion of the hwAttrs structure that can be easily
281  * extended by the device specific implementations. This structure defintion
282  * must be the first line of any device specific structure
283  */
284 #define ITM_BASE_HWATTRS \
285  ITM_TPIU_PortFormat format; /* Wire interface used by TPIU */ \
286  uint32_t traceEnable; /* Bitmask of enabled stimulus ports */ \
287  uint32_t tpiuPrescaler; /* Baudrate to be used by the TPIU */ \
288  uint32_t fullPacketInCycles; /* Cycles in a full word */ \
289 
297 typedef struct
298 {
299  ITM_BASE_HWATTRS
300 } ITM_HWAttrs;
301 
305 typedef enum
306 {
307  ITM_Disabled = 0x0,
308  ITM_EmitPc = 0x1,
316 
321 typedef enum
322 {
333 typedef enum
334 {
340 
348 extern bool ITM_open(void);
349 
357 extern void ITM_close(void);
358 
370 extern void ITM_sendBufferAtomic(const uint8_t port, const char *msg, size_t length);
371 
379 extern void ITM_send32Atomic(uint8_t port, uint32_t value);
380 
388 extern void ITM_send16Atomic(uint8_t port, uint16_t value);
389 
397 extern void ITM_send8Atomic(uint8_t port, uint8_t value);
398 
406 extern void ITM_enableExceptionTrace(void);
407 
414 extern void ITM_disableExceptionTrace(void);
415 
430 extern void ITM_enablePCSampling(bool prescale1024, uint8_t postReset);
431 
444 extern void ITM_enableEventCounter(bool prescale1024, uint8_t postReset);
445 
452 extern void ITM_disablePCAndEventSampling(void);
453 
465 extern void ITM_enableTimestamps(ITM_TimeStampPrescaler tsPrescale, bool asyncMode);
466 
477 extern void ITM_enableSyncPackets(ITM_SyncPacketRate syncPacketRate);
478 
489 extern bool ITM_enableWatchpoint(ITM_WatchpointAction function, const uintptr_t address);
490 
505 extern void __attribute__((weak)) ITM_flush(void);
506 
518 extern void __attribute__((weak)) ITM_restore(void);
519 
520 #ifdef __cplusplus
521 }
522 #endif
523 
524 #endif /* ti_drivers_ITM__include */
void ITM_enableEventCounter(bool prescale1024, uint8_t postReset)
Enable generation of event counter packets using the DWT POSTCNT timer.
bool ITM_open(void)
Open and configure the ITM, DWT, and TPIU. This includes muxing pins as needed.
void ITM_send16Atomic(uint8_t port, uint16_t value)
Write a 16-bit short to the given stimulus port, polling to ensure the port is available.
Definition: ITM.h:335
void ITM_enableSyncPackets(ITM_SyncPacketRate syncPacketRate)
Enable the generation of synchronization packets from the ITM based on the CYCCNT counter...
void ITM_enableTimestamps(ITM_TimeStampPrescaler tsPrescale, bool asyncMode)
Enable the generation of local timestamp packets from the ITM module These are packets sent form the ...
ITM Hardware Attributes.
Definition: ITM.h:297
void ITM_enableExceptionTrace(void)
Enable exception tracing This will trigger the DWT to generate packets when the device enters or leav...
Definition: ITM.h:314
Definition: ITM.h:323
ITM_SyncPacketRate
Synchronous packet generation rate based on cycles of CYCCNT This controls how often sync packets wil...
Definition: ITM.h:333
Definition: ITM.h:337
Definition: ITM.h:324
void ITM_send8Atomic(uint8_t port, uint8_t value)
Write an 8-bit byte to the given stimulus port, polling to ensure the port is available.
ITM_TPIU_PortFormat
Definition: ITM.h:273
void ITM_disableExceptionTrace(void)
Disable exception tracing.
bool ITM_enableWatchpoint(ITM_WatchpointAction function, const uintptr_t address)
Enable the watchpoint functionality using a DWT comparator.
void ITM_enablePCSampling(bool prescale1024, uint8_t postReset)
Enable periodic sampling of the program counter using the DWT POSTCNT timer.
Definition: ITM.h:336
Definition: ITM.h:326
Definition: ITM.h:307
Definition: ITM.h:325
Definition: ITM.h:275
ITM_WatchpointAction
Control the action taken by the DWT on comparator match.
Definition: ITM.h:305
void ITM_close(void)
Definition: ITM.h:308
ITM_TimeStampPrescaler
Prescaler for ITM timestamp generation based on the trace packet reference clock. ...
Definition: ITM.h:321
Definition: ITM.h:276
Definition: ITM.h:313
void ITM_restore(void)
Prepare the ITM hardware to return from power off of CPU domain This will reenable DWT features...
Definition: ITM.h:312
void ITM_flush(void)
Flush the ITM in preparation for power off of CPU domain.
Definition: ITM.h:309
Definition: ITM.h:338
void ITM_disablePCAndEventSampling(void)
Disable program counter and event sampling in the DWT.
void ITM_sendBufferAtomic(const uint8_t port, const char *msg, size_t length)
Write the contents of a buffer to the stimulus port, polling to ensure the port is available...
void ITM_send32Atomic(uint8_t port, uint32_t value)
Write a 32-bit word to the given stimulus port, polling to ensure the port is available.
Definition: ITM.h:311
© Copyright 1995-2022, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale