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 * An example of a Tracealyzer extension for tracing API calls, in this case
9 * for tracing selected functions in Amazon FreeRTOS/aws_wifi.
10 * See trcExtensions.h for information on how to use this.
11 *
12 * To create your own extension, first make sure to read the documentation
13 * in trcExtensions.h. Then, to create an extension header file like this
14 * one, you need to provide:
15 *
16 * - Extension Definitions - name and event codes of the extensions.
17 *
18 * - Trace Wrappers - calls the original function and traces the event.
19 *
20 * - Function Redefinitions - changes the function calls to the trace wrappers.
21 *
22 * See the below comments for details about these definitions. Note that you
23 * also need a matching .xml file for Tracealyzer to understand the data.
24 * See trcExtensions.h for further information.
25 */
26
27 #ifndef _AWS_WIFI_TZEXT_H
28 #define _AWS_WIFI_TZEXT_H
29
30 /***** Extension Definitions (must use the same prefix!) *****/
31
32 /******************************************************************************
33 * <EXTENSIONPREFIX>_NAME
34 * The name of the extension as a string constant. This name is used by the
35 * Tracealyzer host application to find the right XML file for interpreting
36 * the events. Assuming the extension name is "aws_secure_sockets", Tracealyzer
37 * will look for an XML file named "aws_secure_sockets-<VERSION>.xml", first in
38 * the folder of the current trace file, next in the Tracealyzer 4/cfg folder.
39 * For the VERSION part, see the TRC_EXT_<ExtName>_VERSION macros below.
40 *
41 * Note: The extension name displayed in Tracealyzer is defined in the XML file
42 * in the EventGroup element (e.g. <EventGroup name="SOCKETS">)
43 *
44 *****************************************************************************/
45 #define TRC_EXT_WIFI_NAME "aws_wifi"
46
47 /******************************************************************************
48 * <EXTENSIONPREFIX>_VERSION_MAJOR
49 * <EXTENSIONPREFIX>_VERSION_MINOR
50 * <EXTENSIONPREFIX>_VERSION_PATCH
51 *
52 * The version code of the extension (MAJOR.MINOR.PATCH)
53 *
54 * If you increment the version code when modifying an extension, you can still
55 * show old traces recorded using an earlier version of the extension.
56 *
57 * Assuming the extension name is "aws_secure_sockets", and the below version
58 * codes are 1 (MAJOR), 2 (MINOR), 3 (PATCH), Tracealyzer will assume the
59 * corresponding XML file is named "aws_secure_sockets-v1.2.3.xml". So if then
60 * view a trace recorded with extension version 1.2.2, those traces will look
61 * for "aws_secure_sockets-v1.2.2.xml" instead.
62 *
63 * Note that major and minor are stored as 8 bit values, while patch is stored
64 * using 16 bits. They are treated as unsigned integers, so the maximum values
65 * are 256, 256 and 65535.
66 *****************************************************************************/
67 #define TRC_EXT_WIFI_VERSION_MAJOR 1
68
69 #define TRC_EXT_WIFI_VERSION_MINOR 0
70
71 #define TRC_EXT_WIFI_VERSION_PATCH 0
72
73 /******************************************************************************
74 * <EXTENSIONPREFIX>_<EVENTCODE>
75 * The event codes used in the trace wrapper functions. Important that these
76 * are relative to <PREFIX>_FIRST.
77 *****************************************************************************/
78 #define EVENTCODE_WIFI_On (TRC_EXT_BASECODE + 0)
79
80 #define EVENTCODE_WIFI_Off (TRC_EXT_BASECODE + 1)
81
82 #define EVENTCODE_WIFI_ConnectAP (TRC_EXT_BASECODE + 2)
83
84 /******************************************************************************
85 * <EXTENSIONPREFIX>_COUNT
86 * The number of event codes used by this extension. Should be at least 1.
87 * Tracealyzer allows for events codes up to 4095.
88 *****************************************************************************/
89 #define TRC_EXT_WIFI_COUNT 3
90
91
92 /***** Trace Wrappers *****/
93
94 #include "aws_wifi.h" /* Including the original header file, so that custom data types are understood. */
95
WIFI_On__trace(void)96 static inline WIFIReturnCode_t WIFI_On__trace( void )
97 {
98 WIFIReturnCode_t ret = WIFI_On();
99
100 // Note: The host-side xml file assumes that ret == 0 means OK, otherwise timeout/error.
101 prvTraceStoreEvent1(EVENTCODE_WIFI_On, (uint32_t)ret);
102
103 return ret;
104 }
105
WIFI_Off__trace(void)106 static inline WIFIReturnCode_t WIFI_Off__trace( void )
107 {
108 WIFIReturnCode_t ret = WIFI_Off();
109
110 // Note: The host-side xml file assumes that ret == 0 means OK, otherwise timeout/error.
111 prvTraceStoreEvent1(EVENTCODE_WIFI_Off, (uint32_t)ret);
112
113 return ret;
114 }
115
WIFI_ConnectAP__trace(const WIFINetworkParams_t * const pxNetworkParams)116 static inline WIFIReturnCode_t WIFI_ConnectAP__trace( const WIFINetworkParams_t * const pxNetworkParams )
117 {
118 WIFIReturnCode_t ret = WIFI_ConnectAP(pxNetworkParams);
119
120 // Note: The host-side xml file assumes that ret == 0 means OK, otherwise timeout/error.
121
122 prvTraceStoreStringEvent(2, EVENTCODE_WIFI_ConnectAP, pxNetworkParams->pcSSID, pxNetworkParams->xSecurity, ret);
123
124 return ret;
125 }
126
127 /***** Function Redefinitions *****/
128
129 #define WIFI_On WIFI_On__trace
130
131 #define WIFI_Off WIFI_Off__trace
132
133 #define WIFI_ConnectAP WIFI_ConnectAP__trace
134
135 #endif /* _AWS_SECURE_SOCKETS2_TZEXT_H */
136
