1 /* 2 * Trace Recorder for Tracealyzer v4.5.1 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_STREAMING_PORT_H 58 #define TRC_STREAMING_PORT_H 59 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 64 65 int32_t itm_write(void* ptrData, uint32_t size, int32_t* ptrBytesWritten); 66 int32_t read_from_host(void* ptrData, uint32_t size, int32_t* ptrBytesRead); 67 68 /******************************************************************************* 69 * TRC_CFG_ITM_PORT 70 * 71 * Possible values: 0 - 31 72 * 73 * What ITM port to use for the ITM software events. Make sure the IDE is 74 * configured for the same channel. 75 * 76 * Default: 1 (0 is typically terminal output and 31 is used by Keil) 77 * 78 ******************************************************************************/ 79 #define TRC_CFG_ITM_PORT 1 80 81 #if (TRC_CFG_ITM_PORT < 0) || (TRC_CFG_ITM_PORT > 31) 82 #error "Bad ITM port selected." 83 #endif 84 85 // Not used for ITM - no RAM buffer... 86 #define TRC_STREAM_PORT_ALLOCATE_FIELDS() 87 88 // Not used for ITM - assume the IDE configures the ITM setup 89 #define TRC_STREAM_PORT_INIT() 90 91 /* Important for the ITM port - no RAM buffer, direct writes. In most other ports this can be skipped (default is 1) */ 92 #define TRC_STREAM_PORT_USE_INTERNAL_BUFFER 0 93 94 #define TRC_STREAM_PORT_WRITE_DATA(_ptrData, _size, _ptrBytesWritten) itm_write(_ptrData, _size, _ptrBytesWritten) 95 96 #define TRC_STREAM_PORT_READ_DATA(_ptrData, _size, _ptrBytesRead) read_from_host(_ptrData, _size, _ptrBytesRead) 97 98 #ifdef __cplusplus 99 } 100 #endif 101 102 #endif /* TRC_STREAMING_PORT_H */ 103
