Percepio Trace Recorder  v4.6.6
trcStreamPort.h
1 /*
2  * Trace Recorder for Tracealyzer v4.6.6
3  * Copyright 2021 Percepio AB
4  * www.percepio.com
5  *
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * The interface definitions for trace streaming ("stream ports").
9  * This "stream port" sets up the recorder to use ARM ITM as streaming channel.
10  *
11  * To setup Keil uVision for ITM tracing with a Keil ULINKpro (or ULINKplus),
12  * see Percepio Application Note PA-021, available at
13  * https://percepio.com/2018/05/04/keil-itm-support/
14  *
15  * To setup IAR Embedded Workbench for ITM tracing with an IAR I-Jet,
16  * see Percepio Application Note PA-023, https://percepio.com/iar
17  *
18  * NOTE: This stream port may block the application in case the ITM port
19  * is not ready for more data (the TPIU FIFO has become full). This is
20  * necessary to avoid data loss, as the TPIU FIFO is often quite small.
21  *
22  * --- Direct vs. Indirect ITM streaming ---
23  * Direct streaming: By default, this stream port writes directly to the ITM
24  * register mode without any RAM buffer. This assumes you have a fast debug
25  * probe, like aKeil ULINKpro or IAR I-Jet, to avoid excessive blocking.
26  * In case the ITM blocking appears to disturb your application, make sure your
27  * debugger is configured for maximum performance, as described in the above
28  * Application Nodes.
29  *
30  * Indirect streaming: If direct streaming gives too much overhead, you may
31  * instead try indirect ITM streaming. This is done by enabling the internal
32  * RAM buffer, like below. This reconfigures the recorder to store the events
33  * in the internal RAM buffer instead of writing them directly to the ITM port.
34  *
35  * Set TRC_STREAM_PORT_USE_INTERNAL_BUFFER to 1 to use the indirect mode.
36  *
37  * This increases RAM usage but eliminates peaks in the trace data rate.
38  * Moreover, the ITM writes are then performed in a separate task (TzCtrl).
39  * You find relevant settings (buffer size etc.) in trcStreamingConfig.h.
40  *
41  * See also https://percepio.com/2018/10/11/tuning-your-custom-trace-streaming
42  *
43  * --- One-way vs. Two-way Communication ---
44  * The ITM port only provides one-way communication, from target to host.
45  * This is sufficient if you start the tracing from the target application,
46  * using vTraceEnable(TRC_START). Just make sure to start the Tracealyzer
47  * recording before you start the target system.
48  *
49  * In case you prefer to interactively start and stop the tracing from the host
50  * computer, you need two-way communication to send commands to the recorder.
51  * This is possible by writing such "start" and "stop" commands to a special
52  * buffer, monitored by the recorder library, using the debugger IDE.
53  * See trcStreamingPort.c and also the example macro for Keil uVision
54  * (Keil-uVision-Tracealyzer-ITM-Exporter.ini).
55  */
56 
57 #ifndef TRC_STREAM_PORT_H
58 #define TRC_STREAM_PORT_H
59 
60 #if (TRC_USE_TRACEALYZER_RECORDER == 1)
61 
62 #if (TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)
63 
64 #include <stdint.h>
65 #include <trcTypes.h>
66 #include <trcStreamPortConfig.h>
67 
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71 
72 #if (!defined(TRC_CFG_STREAM_PORT_ITM_PORT) || (TRC_CFG_STREAM_PORT_ITM_PORT) < 0) || ((TRC_CFG_STREAM_PORT_ITM_PORT) > 31)
73 #error "Invalid ITM port defined in trcStreamPortConfig.h."
74 #endif
75 
76 /* Important for the ITM port - no RAM buffer, direct writes. In most other ports this can be skipped (default is 1) */
77 #define TRC_USE_INTERNAL_BUFFER 0
78 
79 typedef struct TraceStreamPortBuffer
80 {
81  uint8_t buffer[sizeof(TraceUnsignedBaseType_t)];
83 
84 traceResult prvTraceItmWrite(void* ptrData, uint32_t size, int32_t* ptrBytesWritten);
85 traceResult prvTraceItmRead(void* ptrData, uint32_t uiSize, int32_t* piBytesRead);
86 
87 traceResult xTraceStreamPortInitialize(TraceStreamPortBuffer_t* pxBuffer);
88 
89 #define xTraceStreamPortAllocate(uiSize, ppvData) ((void)uiSize, xTraceStaticBufferGet(ppvData))
90 
91 #define xTraceStreamPortCommit(pvData, uiSize, piBytesCommitted) prvTraceItmWrite(pvData, uiSize, piBytesCommitted)
92 
93 #define xTraceStreamPortWriteData(pvData, uiSize, piBytesWritten) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_4((void)pvData, (void)uiSize, (void)piBytesWritten, TRC_SUCCESS)
94 
95 #define xTraceStreamPortReadData(pvData, uiSize, piBytesRead) prvTraceItmRead(pvData, uiSize, piBytesRead)
96 
97 #define xTraceStreamPortOnEnable(uiStartOption) TRC_COMMA_EXPR_TO_STATEMENT_EXPR_2((void)(uiStartOption), TRC_SUCCESS)
98 
99 #define xTraceStreamPortOnDisable() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS)
100 
101 #define xTraceStreamPortOnTraceBegin() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS)
102 
103 #define xTraceStreamPortOnTraceEnd() TRC_COMMA_EXPR_TO_STATEMENT_EXPR_1(TRC_SUCCESS)
104 
105 #ifdef __cplusplus
106 }
107 #endif
108 
109 #endif /*(TRC_CFG_RECORDER_MODE == TRC_RECORDER_MODE_STREAMING)*/
110 
111 #endif /*(TRC_USE_TRACEALYZER_RECORDER == 1)*/
112 
113 #endif /* TRC_STREAM_PORT_H */
TraceStreamPortBuffer
A structure representing the trace stream port buffer.
Definition: trcStreamPort.h:80