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  * This stream port provides trace streaming using the Amazon FreeRTOS sockets
9  * layer and is intended for streaming over Wifi directly to a computer on the
10  * local Wifi network.
11  *
12  * Note that this does NOT use the TLS encryption available in Amazon
13  * FreeRTOS, due to performance and memory usage concerns. However, it does not
14  * use any AWS services either, and is intended for your local network only.
15  *
16  * This should be started using vTraceEnable(TRC_START) and this call should be
17  * made AFTER the kernel has started and the Wifi interface is ready.
18  *
19  * In the Tracealyzer setting -> "PSF Streaming Settings" make sure that the
20  * "Target Connection" setting is "TCP (Target Initiated)".
21  *
22  * To use this, make sure to start the trace recording in Tracealyzer before
23  * you start your target system. This ensures that Tracealyzer is ready when
24  * the target system connects.
25  *
26  * And don't forget to enter the IP address of the Tracealyzer host computer
27  * in trcStreamPort.h.
28  *
29  * NOTES:
30  *
31  * 1: The tracing will increase the stack usage of you application, so you
32  * may want to increase configMINIMAL_STACK_SIZE in your FreeRTOSConfig.h.
33  *
34  * 2: To reduce the amount of trace data, we recommend disabling the tracing
35  * of OS Ticks and memory allocation events.
36  * See TRC_CFG_INCLUDE_OSTICK_EVENTS in trcConfig.h.
37  *
38  * 3: The transmission of trace data is done in the TzCtrl task. To avoid that
39  * the trace streaming is blocked during the (long) MQTT connection phase,
40  * make sure the scheduling priority of TzCtrl is higher than the MQTT task.
41  * Otherwise, if you prefer to run the TzCtrl task at lower priority to avoid
42  * interfering with your application, wait with the vTraceEnable call until
43  * after the MQTT connection is established.
44  * See TRC_CFG_CTRL_TASK_PRIORITY in trcStreamingConfig.h.
45  *
46  * 4: The Wifi transmission of trace data often uses FreeRTOS functions, that
47  * are traced and thus produce additional trace data. This may cause a fast
48  * increase in trace data rate, that may saturate the trace buffer and cause
49  * data loss (i.e. incomplete traces).
50  * To eliminate this effect and reduce the amount of trace data produced, we
51  * recommend excluding all FreeRTOS objects that are used by Wifi stack.
52  * This is done using vTraceSetFilterGroup and vTraceSetFilterMask:
53  *
54  * // Just before wifi initialization:
55  *
56  * // All objects created after this point are assigned to group 15.
57  * vTraceSetFilterGroup(FilterGroup15);
58  *
59  * // Only trace objects assigned to group 0 (the default group).
60  * vTraceSetFilterMask(FilterGroup0);
61  *
62  * // The wifi stack initialization... (creates semaphores etc.)
63  * if ( eWifi_Connected == prvWifiConnect() )
64  * {
65  * yMainState = eMain_StartApplication;
66  *
67  * // When connected, restore the FilterGroup setting to Group 0, so
68  * // that later created objects are included, like the TzCtrl task
69  * // created in vTraceEnable. Excluding tasks is not recommended!
70  * vTraceSetFilterGroup(FilterGroup0);
71  *
72  * // Then call vTraceEnable to start the tracing.
73  * vTraceEnable(TRC_START);
74  * }
75  *
76  * 5: If you still get "red sections" in Tracealyzer (lost data), you need
77  * to adjust the other settings in trcStreamingConfig.h.
78  *
79  * - TRC_CFG_PAGED_EVENT_BUFFER_PAGE_COUNT
80  * Increase this, as long as you have memory to spare.
81  *
82  * - TRC_CFG_PAGED_EVENT_BUFFER_PAGE_SIZE
83  * Increase this, as long as you have memory to spare.
84  * But don't exceed the maximum payload size of the Wifi chip, which
85  * is often limited to 1000-1500 bytes. Some chips crash if you try to
86  * send to large chunks...
87  *
88  * - TRC_CFG_CTRL_TASK_DELAY
89  * Decrease this to flush the trace buffer more frequently.
90  *
91  * See also http://percepio.com/2016/10/05/rtos-tracing
92  * and https://percepio.com/2018/10/11/tuning-your-custom-trace-streaming/
93  */
94 
95 #ifndef TRC_STREAM_PORT_H
96 #define TRC_STREAM_PORT_H
97 
98 #ifdef __cplusplus
99 extern "C" {
100 #endif
101 
102 
103 #define HOST_IPADDRESS_0 192
104 #define HOST_IPADDRESS_1 168
105 #define HOST_IPADDRESS_2 10
106 #define HOST_IPADDRESS_3 116
107 #define HOST_PORT 12000
108 
109 void prvInitSocket(void);
110 int32_t prvReadFromSocket(void* ptrData, uint32_t size, int32_t* ptrBytesRead);
111 int32_t prvWriteToSocket(void* ptrData, uint32_t size, int32_t* ptrBytesWritten);
112 
113 #define TRC_STREAM_PORT_INIT() \
114  TRC_STREAM_PORT_MALLOC(); \
115  prvInitSocket();
116 
117 #define TRC_STREAM_PORT_USE_INTERNAL_BUFFER 1
118 
119 #define TRC_STREAM_PORT_WRITE_DATA(_ptrData, _size, _ptrBytesWritten) prvWriteToSocket(_ptrData, _size, _ptrBytesWritten)
120 
121 #define TRC_STREAM_PORT_READ_DATA(_ptrData, _size, _ptrBytesRead) prvReadFromSocket(_ptrData, _size, _ptrBytesRead)
122 
123 #ifdef __cplusplus
124 }
125 #endif
126 
127 #endif /* TRC_STREAM_PORT_H */