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_secure_sockets.
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_SECURE_SOCKETS_TZEXT_H
28 #define _AWS_SECURE_SOCKETS_TZEXT_H
29
30 /***** Extension Definitions *****/
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_SOCKETS_NAME "aws_secure_sockets"
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_SOCKETS_VERSION_MAJOR 1
68
69 #define TRC_EXT_SOCKETS_VERSION_MINOR 0
70
71 #define TRC_EXT_SOCKETS_VERSION_PATCH 0
72
73
74 /******************************************************************************
75 * <EXTENSIONPREFIX>_<EVENTCODE>
76 * The event codes used in the trace wrapper functions. Important that these
77 * are relative to <PREFIX>_FIRST.
78 *****************************************************************************/
79 #define EVENTCODE_SOCKETS_Connect (TRC_EXT_BASECODE + 0)
80
81 #define EVENTCODE_SOCKETS_Send (TRC_EXT_BASECODE + 1)
82
83 #define EVENTCODE_SOCKETS_Recv (TRC_EXT_BASECODE + 2)
84
85 /******************************************************************************
86 * <EXTENSIONPREFIX>_COUNT
87 * The number of event codes used by this extension. Should be at least 1.
88 * Tracealyzer allows for events codes up to 4095.
89 *****************************************************************************/
90 #define TRC_EXT_SOCKETS_COUNT 2
91
92
93 /***** Trace Wrappers *****/
94
95 #include "aws_secure_sockets.h" /* Including the original header file, so that custom data types are understood. */
96
SOCKETS_Connect__trace(Socket_t xSocket,SocketsSockaddr_t * pxAddress,Socklen_t xAddressLength)97 static inline int32_t SOCKETS_Connect__trace( Socket_t xSocket, SocketsSockaddr_t * pxAddress, Socklen_t xAddressLength )
98 {
99 int32_t ret = SOCKETS_Connect(xSocket, pxAddress, xAddressLength);
100
101 // Note: The host-side xml file assumes that ret == 0 means OK, otherwise timeout/error.
102 prvTraceStoreEvent3(EVENTCODE_SOCKETS_Connect, (uint32_t)xSocket, (uint32_t)pxAddress->ulAddress, (uint32_t)ret);
103
104 return ret;
105 }
106
SOCKETS_Send__trace(Socket_t xSocket,const void * pvBuffer,size_t xDataLength,uint32_t ulFlags)107 static inline int32_t SOCKETS_Send__trace( Socket_t xSocket, const void * pvBuffer, size_t xDataLength, uint32_t ulFlags )
108 {
109 int32_t ret = SOCKETS_Send(xSocket, pvBuffer, xDataLength, ulFlags);
110
111 // Note: The host-side xml file assumes that ret == 0 means OK, otherwise timeout/error.
112 prvTraceStoreEvent2(EVENTCODE_SOCKETS_Send, (uint32_t)xSocket, (uint32_t)ret);
113
114 return ret;
115 }
116
117
SOCKETS_Recv__trace(Socket_t xSocket,void * pvBuffer,size_t xBufferLength,uint32_t ulFlags)118 static inline int32_t SOCKETS_Recv__trace( Socket_t xSocket, void * pvBuffer, size_t xBufferLength, uint32_t ulFlags )
119 {
120 int32_t ret = SOCKETS_Recv(xSocket, pvBuffer, xBufferLength, ulFlags);
121
122 // Note: The host-side xml file assumes that ret == 0 means OK, otherwise timeout/error.
123 prvTraceStoreEvent2(EVENTCODE_SOCKETS_Recv, (uint32_t)xSocket, (uint32_t)ret);
124
125 return ret;
126 }
127
128 /***** Function Redefinitions *****/
129
130 #define SOCKETS_Connect SOCKETS_Connect__trace
131
132 #define SOCKETS_Send SOCKETS_Send__trace
133
134 #define SOCKETS_Recv SOCKETS_Recv__trace
135
136 #endif /* _AWS_SECURE_SOCKETS_TZEXT_H */
137
