1# Trace 2 3## Basic Concepts<a name="section531482192018"></a> 4 5Trace helps you learn about the kernel running process and the execution sequence of modules and tasks. With the information, you can better understand the code running process of the kernel and locate time sequence problems. 6 7## Working Principles<a name="section5125124532010"></a> 8 9The kernel provides a hook framework to embed hooks in the main process of each module. In the initial startup phase of the kernel, the trace function is initialized and the trace handlers are registered with the hooks. 10 11When a hook is triggered, the trace module encapsulates the input information and adds the trace frame header information, including the event type, ID of the running CPU, ID of the running task, and relative timestamp. 12 13The trace module provides two working modes: offline mode and online mode. 14 15In offline mode, trace frames are stored in a circular buffer. If too many frames are stored in the circular buffer, earlier frames will be overwritten to ensure that the information in the buffer is always the latest. Data in the circular buffer can be exported by running the shell command for further analysis. The exported information is sorted by timestamp. 16 17 18 19The online mode must be used with the integrated development environment \(IDE\). Trace frames are sent to the IDE in real time. The IDE parses the records and displays them in a visualized manner. 20 21## **Available APIs**<a name="section17747184017458"></a> 22 23### Kernel Mode<a name="section104473014465"></a> 24 25The trace module of the OpenHarmony LiteOS-A kernel provides the following functions. For details about the APIs, see the [API](https://gitee.com/openharmony/kernel_liteos_a/blob/master/kernel/include/los_trace.h) reference. 26 27**Table 1** Trace module APIs 28 29<a name="table1290750144615"></a> 30<table><thead align="left"><tr id="row92916507464"><th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.1"><p id="p1429185074615"><a name="p1429185074615"></a><a name="p1429185074615"></a>Function</p> 31</th> 32<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.2"><p id="p1729115010467"><a name="p1729115010467"></a><a name="p1729115010467"></a>API</p> 33</th> 34<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.3"><p id="p12911501463"><a name="p12911501463"></a><a name="p12911501463"></a>Description</p> 35</th> 36</tr> 37</thead> 38<tbody><tr id="row9287279472"><td class="cellrowborder" rowspan="2" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p12191827104720"><a name="p12191827104720"></a><a name="p12191827104720"></a>Starting and stopping trace</p> 39</td> 40<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p1519152774719"><a name="p1519152774719"></a><a name="p1519152774719"></a>LOS_TraceStart</p> 41</td> 42<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p619102714475"><a name="p619102714475"></a><a name="p619102714475"></a>Starts trace.</p> 43</td> 44</tr> 45<tr id="row17281727204713"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p519162715477"><a name="p519162715477"></a><a name="p519162715477"></a>LOS_TraceStop</p> 46</td> 47<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p12191827164710"><a name="p12191827164710"></a><a name="p12191827164710"></a>Stops trace.</p> 48</td> 49</tr> 50<tr id="row428102714719"><td class="cellrowborder" rowspan="3" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p1019327194717"><a name="p1019327194717"></a><a name="p1019327194717"></a>Managing trace records</p> 51</td> 52<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p1319142714474"><a name="p1319142714474"></a><a name="p1319142714474"></a>LOS_TraceRecordDump</p> 53</td> 54<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p0192275474"><a name="p0192275474"></a><a name="p0192275474"></a>Exports data in the trace buffer.</p> 55</td> 56</tr> 57<tr id="row192852794713"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1419827104715"><a name="p1419827104715"></a><a name="p1419827104715"></a>LOS_TraceRecordGet</p> 58</td> 59<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1619162715479"><a name="p1619162715479"></a><a name="p1619162715479"></a>Obtains the start address of the trace buffer.</p> 60</td> 61</tr> 62<tr id="row172882764719"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1019527134714"><a name="p1019527134714"></a><a name="p1019527134714"></a>LOS_TraceReset</p> 63</td> 64<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1619192720473"><a name="p1619192720473"></a><a name="p1619192720473"></a>Clears events in the trace buffer.</p> 65</td> 66</tr> 67<tr id="row82715275472"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p1419122716473"><a name="p1419122716473"></a><a name="p1419122716473"></a>Filtering trace records</p> 68</td> 69<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p121917278472"><a name="p121917278472"></a><a name="p121917278472"></a>LOS_TraceEventMaskSet</p> 70</td> 71<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p1419927154711"><a name="p1419927154711"></a><a name="p1419927154711"></a>Sets the event mask to trace only events of the specified modules.</p> 72</td> 73</tr> 74<tr id="row827827174718"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p9201275471"><a name="p9201275471"></a><a name="p9201275471"></a>Masking events of specified interrupt IDs</p> 75</td> 76<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p720112717476"><a name="p720112717476"></a><a name="p720112717476"></a>LOS_TraceHwiFilterHookReg</p> 77</td> 78<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p192042713475"><a name="p192042713475"></a><a name="p192042713475"></a>Registers a hook to filter out events of specified interrupt IDs.</p> 79</td> 80</tr> 81<tr id="row42714279476"><td class="cellrowborder" rowspan="2" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p172011270476"><a name="p172011270476"></a><a name="p172011270476"></a>Performing function instrumentation</p> 82</td> 83<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p1120122754714"><a name="p1120122754714"></a><a name="p1120122754714"></a>LOS_TRACE_EASY</p> 84</td> 85<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p12032714717"><a name="p12032714717"></a><a name="p12032714717"></a>Performs simple instrumentation.</p> 86</td> 87</tr> 88<tr id="row1927122734715"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p52062712478"><a name="p52062712478"></a><a name="p52062712478"></a>LOS_TRACE</p> 89</td> 90<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p182062734713"><a name="p182062734713"></a><a name="p182062734713"></a>Performs standard instrumentation.</p> 91</td> 92</tr> 93</tbody> 94</table> 95 96- You can perform function instrumentation in the source code to trace specific events. The system provides the following APIs for instrumentation: 97 - **LOS\_TRACE\_EASY\(TYPE, IDENTITY, params...\)** for simple instrumentation 98 - You only need to insert this API into the source code. 99 - **TYPE** specifies the event type. The value range is 0 to 0xF. The meaning of each value is user-defined. 100 - **IDENTITY** specifies the object of the event operation. The value is of the **UIntPtr** type. 101 - **Params** specifies the event parameters. The value is of the **UIntPtr** type. 102 103 Example: 104 105 ``` 106 Perform simple instrumentation for reading and writing files fd1 and fd2. 107 Set TYPE to 1 for read operations and 2 for write operations. 108 Insert the following to the position where the fd1 file is read: 109 LOS_TRACE_EASY(1, fd1, flag, size); 110 Insert the following to the position where the fd2 file is read: 111 LOS_TRACE_EASY(1, fd2, flag, size); 112 Insert the following to the position where the fd1 file is written: 113 LOS_TRACE_EASY(2, fd1, flag, size); 114 Insert the following in the position where the fd2 file is written: 115 LOS_TRACE_EASY(2, fd2, flag, size); 116 ``` 117 118 - **LOS\_TRACE\(TYPE, IDENTITY, params...\)** for standard instrumentation. 119 - Compared with simple instrumentation, standard instrumentation supports dynamic event filtering and parameter tailoring. However, you need to extend the functions based on rules. 120 - **TYPE** specifies the event type. You can define the event type in **enum LOS\_TRACE\_TYPE** in the header file **los\_trace.h**. For details about methods and rules for defining events, see other event types. 121 - The **IDENTITY** and **Params** are the same as those of simple instrumentation. 122 123 Example: 124 125 ``` 126 1. Set the event mask (module-level event type) in enum LOS_TRACE_MASK. 127 Format: TRACE_#MOD#_FLAG (MOD indicates the module name) 128 Example: 129 TRACE_FS_FLAG = 0x4000 130 2. Define the event type in enum LOS_TRACE_TYPE. 131 Format: #TYPE# = TRACE_#MOD#_FLAG | NUMBER 132 Example: 133 FS_READ = TRACE_FS_FLAG | 0; // Read files 134 FS_WRITE = TRACE_FS_FLAG | 1; // Write files 135 3. Set event parameters in the #TYPE#_PARAMS(IDENTITY, parma1...) IDENTITY, ... format. 136 #TYPE# is the #TYPE# defined in step 2. 137 Example: 138 #define FS_READ_PARAMS(fp, fd, flag, size) fp, fd, flag, size 139 The parameters defined by the macro correspond to the event parameters recorded in the trace buffer. You can modify the parameters as required. 140 If no parameter is specified, events of this type are not traced. 141 #define FS_READ_PARAMS(fp, fd, flag, size) // File reading events are not traced. 142 4. Insert a code stub in a proper position. 143 Format: LOS_TRACE(#TYPE#, #TYPE#_PARAMS(IDENTITY, parma1...)) 144 LOS_TRACE(FS_READ, fp, fd, flag, size); // Code stub for reading files 145 The parameters following #TYPE# are the input parameter of the FS_READ_PARAMS function in step 3. 146 ``` 147 148 > **NOTE:** 149 >The trace event types and parameters can be modified as required. For details about the parameters, see **kernel\\include\\los\_trace.h**. 150 151 152 153- For **LOS\_TraceEventMaskSet\(UINT32 mask\)**, only the most significant 28 bits \(corresponding to the enable bit of the module in **LOS\_TRACE\_MASK**\) of the mask take effect and are used only for module-based tracing. Currently, fine-grained event-based tracing is not supported. For example, in **LOS\_TraceEventMaskSet\(0x202\)**, the effective mask is **0x200 \(TRACE\_QUE\_FLAG\)** and all events of the QUE module are collected. The recommended method is **LOS\_TraceEventMaskSet\(TRACE\_EVENT\_FLAG | TRACE\_MUX\_FLAG | TRACE\_SEM\_FLAG | TRACE\_QUE\_FLAG\);**. 154- To enable trace of only simple instrumentation events, set **Trace Mask** to **TRACE\_MAX\_FLAG**. 155- The trace buffer has limited capacity. When the trace buffer is full, events will be overwritten. You can use **LOS\_TraceRecordDump** to export data from the trace buffer and locate the latest records by **CurEvtIndex**. 156- The typical trace operation process includes **LOS\_TraceStart**, **LOS\_TraceStop**, and **LOS\_TraceRecordDump**. 157- You can filter out interrupt events by interrupt ID to prevent other events from being overwritten due to frequent triggering of a specific interrupt in some scenarios. You can customize interrupt filtering rules. 158 159 The sample code is as follows: 160 161 ``` 162 BOOL Example_HwiNumFilter(UINT32 hwiNum) 163 { 164 if ((hwiNum == TIMER_INT) || (hwiNum == DMA_INT)) { 165 return TRUE; 166 } 167 return FALSE; 168 } 169 LOS_TraceHwiFilterHookReg(Example_HwiNumFilter); 170 ``` 171 172 173The interrupt events with interrupt ID of **TIMER\_INT** or **DMA\_INT** are not traced. 174 175### User Mode<a name="section1996920294531"></a> 176 177The trace character device is added in **/dev/trace**. You can use **read\(\)**, **write\(\)**, and **ioctl\(\)** on the device node to read, write, and control trace in user mode. 178 179- **read\(\)**: reads the trace data in user mode. 180- **write\(\)**: writes an event in user mode. 181- **ioctl\(\)**: performs user-mode trace operations, including: 182 183``` 184#define TRACE_IOC_MAGIC 'T' 185#define TRACE_START _IO(TRACE_IOC_MAGIC, 1) 186#define TRACE_STOP _IO(TRACE_IOC_MAGIC, 2) 187#define TRACE_RESET _IO(TRACE_IOC_MAGIC, 3) 188#define TRACE_DUMP _IO(TRACE_IOC_MAGIC, 4) 189#define TRACE_SET_MASK _IO(TRACE_IOC_MAGIC, 5) 190``` 191 192The operations specified by the input parameter of **ioctl\(\)** correspond to **LOS\_TraceStart**, **LOS\_TraceStop**, **LOS\_TraceReset**, **LOS\_TraceRecordDump**, and **LOS\_TraceEventMaskSet**, respectively. 193 194For more details, see [User-mode Programming Example](https://gitee.com/openharmony/docs/blob/70744e1e0e34d66e11108a00c8db494eea49dd02/en/device-dev/kernel/kernel-small-debug-trace.md#section4.2.2). 195 196## Development Guidelines<a name="section10302175017543"></a> 197 198### Kernel-mode Development Process<a name="section04021008552"></a> 199 200The typical trace process is as follows: 201 2021. Configure the macro related to the trace module. 203 204 Configure the trace macro **LOSCFG\_KERNEL\_TRACE**, which is disabled by default. Run the **make update\_config** command in the **kernel/liteos\_a** directory, choose **Kernel** \> **Enable Hook Feature**, and set **Enable Trace Feature** to **YES**. 205 206 <a name="table16145182665619"></a> 207 <table><thead align="left"><tr id="row16145192611566"><th class="cellrowborder" valign="top" width="25%" id="mcps1.1.5.1.1"><p id="p18145726175614"><a name="p18145726175614"></a><a name="p18145726175614"></a>Configuration</p> 208 </th> 209 <th class="cellrowborder" valign="top" width="25%" id="mcps1.1.5.1.2"><p id="p15145162613562"><a name="p15145162613562"></a><a name="p15145162613562"></a>menuconfig Option</p> 210 </th> 211 <th class="cellrowborder" valign="top" width="25%" id="mcps1.1.5.1.3"><p id="p111451263569"><a name="p111451263569"></a><a name="p111451263569"></a>Description</p> 212 </th> 213 <th class="cellrowborder" valign="top" width="25%" id="mcps1.1.5.1.4"><p id="p12145112616562"><a name="p12145112616562"></a><a name="p12145112616562"></a>Value</p> 214 </th> 215 </tr> 216 </thead> 217 <tbody><tr id="row5318402576"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.1 "><p id="p330560125717"><a name="p330560125717"></a><a name="p330560125717"></a>LOSCFG_KERNEL_TRACE</p> 218 </td> 219 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.2 "><p id="p83051406576"><a name="p83051406576"></a><a name="p83051406576"></a>Enable Trace Feature</p> 220 </td> 221 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.3 "><p id="p1530512018572"><a name="p1530512018572"></a><a name="p1530512018572"></a>Specifies whether to enable the trace feature.</p> 222 </td> 223 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.4 "><p id="p123051600573"><a name="p123051600573"></a><a name="p123051600573"></a>YES/NO</p> 224 </td> 225 </tr> 226 <tr id="row1731810085715"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.1 "><p id="p1930514019579"><a name="p1930514019579"></a><a name="p1930514019579"></a>LOSCFG_RECORDER_MODE_OFFLINE</p> 227 </td> 228 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.2 "><p id="p1830511011573"><a name="p1830511011573"></a><a name="p1830511011573"></a>Trace work mode ->Offline mode</p> 229 </td> 230 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.3 "><p id="p23051509577"><a name="p23051509577"></a><a name="p23051509577"></a>Specifies whether to enable the online trace mode.</p> 231 </td> 232 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.4 "><p id="p630514085717"><a name="p630514085717"></a><a name="p630514085717"></a>YES/NO</p> 233 </td> 234 </tr> 235 <tr id="row13189005711"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.1 "><p id="p1305110165716"><a name="p1305110165716"></a><a name="p1305110165716"></a>LOSCFG_RECORDER_MODE_ONLINE</p> 236 </td> 237 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.2 "><p id="p9305709579"><a name="p9305709579"></a><a name="p9305709579"></a>Trace work mode ->Online mode</p> 238 </td> 239 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.3 "><p id="p1330610175717"><a name="p1330610175717"></a><a name="p1330610175717"></a>Specifies whether to enable the offline trace mode.</p> 240 </td> 241 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.4 "><p id="p18306180185715"><a name="p18306180185715"></a><a name="p18306180185715"></a>YES/NO</p> 242 </td> 243 </tr> 244 <tr id="row3318603579"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.1 "><p id="p1830616035713"><a name="p1830616035713"></a><a name="p1830616035713"></a>LOSCFG_TRACE_CLIENT_INTERACT</p> 245 </td> 246 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.2 "><p id="p230613005719"><a name="p230613005719"></a><a name="p230613005719"></a>Enable Trace Client Visualization and Control</p> 247 </td> 248 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.3 "><p id="p19306200125711"><a name="p19306200125711"></a><a name="p19306200125711"></a>Specifies whether to enable interaction with Trace IDE (dev tools), including data visualization and process control.</p> 249 </td> 250 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.4 "><p id="p16306130155720"><a name="p16306130155720"></a><a name="p16306130155720"></a>YES/NO</p> 251 </td> 252 </tr> 253 <tr id="row23181607578"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.1 "><p id="p83064095720"><a name="p83064095720"></a><a name="p83064095720"></a>LOSCFG_TRACE_FRAME_CORE_MSG</p> 254 </td> 255 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.2 "><p id="p730611075711"><a name="p730611075711"></a><a name="p730611075711"></a>Enable Record more extended content ->Record cpuid, hardware interrupt status, task lock status</p> 256 </td> 257 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.3 "><p id="p83061018576"><a name="p83061018576"></a><a name="p83061018576"></a>Specifies whether to enable recording of the CPU ID, interruption state, and lock task state.</p> 258 </td> 259 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.4 "><p id="p19306805574"><a name="p19306805574"></a><a name="p19306805574"></a>YES/NO</p> 260 </td> 261 </tr> 262 <tr id="row8318904574"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.1 "><p id="p430617095718"><a name="p430617095718"></a><a name="p430617095718"></a>LOSCFG_TRACE_FRAME_EVENT_COUNT</p> 263 </td> 264 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.2 "><p id="p13064013576"><a name="p13064013576"></a><a name="p13064013576"></a>Enable Record more extended content ->Record event count, which indicate the sequence of happend events</p> 265 </td> 266 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.3 "><p id="p133061203576"><a name="p133061203576"></a><a name="p133061203576"></a>Specifies whether to enables recording of the event sequence number.</p> 267 </td> 268 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.4 "><p id="p13306190105710"><a name="p13306190105710"></a><a name="p13306190105710"></a>YES/NO</p> 269 </td> 270 </tr> 271 <tr id="row4318406577"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.1 "><p id="p183068010574"><a name="p183068010574"></a><a name="p183068010574"></a>LOSCFG_TRACE_FRAME_MAX_PARAMS</p> 272 </td> 273 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.2 "><p id="p7306160125716"><a name="p7306160125716"></a><a name="p7306160125716"></a>Record max params</p> 274 </td> 275 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.3 "><p id="p030610020572"><a name="p030610020572"></a><a name="p030610020572"></a>Specifies the maximum number of parameters for event recording.</p> 276 </td> 277 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.4 "><p id="p93065012570"><a name="p93065012570"></a><a name="p93065012570"></a>INT</p> 278 </td> 279 </tr> 280 <tr id="row17317102571"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.1 "><p id="p330616014570"><a name="p330616014570"></a><a name="p330616014570"></a>LOSCFG_TRACE_BUFFER_SIZE</p> 281 </td> 282 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.2 "><p id="p03061903577"><a name="p03061903577"></a><a name="p03061903577"></a>Trace record buffer size</p> 283 </td> 284 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.3 "><p id="p14306120115713"><a name="p14306120115713"></a><a name="p14306120115713"></a>Specifies the trace buffer size.</p> 285 </td> 286 <td class="cellrowborder" valign="top" width="25%" headers="mcps1.1.5.1.4 "><p id="p230613012578"><a name="p230613012578"></a><a name="p230613012578"></a>INT</p> 287 </td> 288 </tr> 289 </tbody> 290 </table> 291 2922. \(Optional\) Preset event parameters and stubs \(or use the default event parameter settings and event stubs\). 2933. \(Optional\) Call **LOS\_TraceStop** to stop trace and call **LOS\_TraceReset** to clear the trace buffer. \(Trace is started by default.\) 2944. \(Optional\) Call **LOS\_TraceEventMaskSet** to set the event mask for trace \(only the interrupts and task events are enabled by default\). For details about the event mask, see **LOS\_TRACE\_MASK** in **los\_trace.h**. 2955. Call **LOS\_TraceStart** at the start of the code where the event needs to be traced. 2966. Call **LOS\_TraceStop** at the end of the code where the event needs to be traced. 2977. Call **LOS\_TraceRecordDump** to output the data in the buffer. \(The input parameter of the function is of the Boolean type. The value **FALSE** means to output data in the specified format, and the value **TRUE** means to output data to Trace IDE.\) 298 299The methods in steps 3 to 7 are encapsulated with shell commands. After the shell is enabled, the corresponding commands can be executed. The mapping is as follows: 300 301- LOS\_TraceReset —— trace\_reset 302- LOS\_TraceEventMaskSet —— trace\_mask 303- LOS\_TraceStart —— trace\_start 304- LOS\_TraceStop —— trace\_stop 305- LOS\_TraceRecordDump —— trace\_dump 306 307## Kernel-mode Programming Example<a name="section112034213583"></a> 308 309This example implements the following: 310 3111. Create a trace task. 3122. Set the event mask. 3133. Start trace. 3144. Stop trace. 3155. Output trace data in the specified format. 316 317## Kernel-mode Sample Code<a name="section10348549155812"></a> 318 319The code is as follows: 320 321``` 322#include "los_trace.h" 323UINT32 g_traceTestTaskId; 324VOID Example_Trace(VOID) 325{ 326 UINT32 ret; 327 LOS_TaskDelay(10); 328 /* Start trace. */ 329 ret = LOS_TraceStart(); 330 if (ret != LOS_OK) { 331 dprintf("trace start error\n"); 332 return; 333 } 334 /* Trigger a task switching event.*/ 335 LOS_TaskDelay(1); 336 LOS_TaskDelay(1); 337 LOS_TaskDelay(1); 338 /* Stop trace.*/ 339 LOS_TraceStop(); 340 LOS_TraceRecordDump(FALSE); 341} 342UINT32 Example_Trace_test(VOID){ 343 UINT32 ret; 344 TSK_INIT_PARAM_S traceTestTask; 345 /* Create a trace task. */ 346 memset(&traceTestTask, 0, sizeof(TSK_INIT_PARAM_S)); 347 traceTestTask.pfnTaskEntry = (TSK_ENTRY_FUNC)Example_Trace; 348 traceTestTask.pcName = "TestTraceTsk"; /* Trace task name*/ 349 traceTestTask.uwStackSize = 0x800; 350 traceTestTask.usTaskPrio = 5; 351 traceTestTask.uwResved = LOS_TASK_STATUS_DETACHED; 352 ret = LOS_TaskCreate(&g_traceTestTaskId, &traceTestTask); 353 if(ret != LOS_OK){ 354 dprintf("TraceTestTask create failed .\n"); 355 return LOS_NOK; 356 } 357 /* Trace is started by default. Therefore, you can stop trace, clear the buffer, and then restart trace. */ 358 LOS_TraceStop(); 359 LOS_TraceReset(); 360 /* Enable trace of the Task module events. */ 361 LOS_TraceEventMaskSet(TRACE_TASK_FLAG); 362 return LOS_OK; 363} 364LOS_MODULE_INIT(Example_Trace_test, LOS_INIT_LEVEL_KMOD_EXTENDED); 365``` 366 367## Verification<a name="section8601444165916"></a> 368 369The output is as follows: 370 371``` 372*******TraceInfo begin******* 373clockFreq = 50000000 374CurEvtIndex = 7 375Index Time(cycles) EventType CurTask Identity params 3760 0x366d5e88 0x45 0x1 0x0 0x1f 0x4 0x0 3771 0x366d74ae 0x45 0x0 0x1 0x0 0x8 0x1f 3782 0x36940da6 0x45 0x1 0xc 0x1f 0x4 0x9 3793 0x3694337c 0x45 0xc 0x1 0x9 0x8 0x1f 3804 0x36eea56e 0x45 0x1 0xc 0x1f 0x4 0x9 3815 0x36eec810 0x45 0xc 0x1 0x9 0x8 0x1f 3826 0x3706f804 0x45 0x1 0x0 0x1f 0x4 0x0 3837 0x37070e59 0x45 0x0 0x1 0x0 0x8 0x1f 384*******TraceInfo end******* 385``` 386 387The output event information includes the occurrence time, event type, task in which the event occurs, object of the event operation, and other parameters of the event. 388 389- **EventType**: event type. For details, see **enum LOS\_TRACE\_TYPE** in the header file **los\_trace.h**. 390- **CurrentTask**: ID of the running task. 391- **Identity**: object of the event operation. For details, see **\#TYPE\#\_PARAMS** in the header file **los\_trace.h**. 392- **params**: event parameters. For details, see **\#TYPE\#\_PARAMS** in the header file **los\_trace.h**. 393 394The following uses output No. 0 as an example. 395 396``` 397Index Time(cycles) EventType CurTask Identity params 3980 0x366d5e88 0x45 0x1 0x0 0x1f 0x4 399``` 400 401- **Time \(cycles\)** can be converted into time \(in seconds\) by dividing the cycles by clockFreq. 402- **0x45** indicates the task switching event. **0x1** is the ID of the task in running. 403- For details about the meanings of **Identity** and **params**, see the **TASK\_SWITCH\_PARAMS** macro. 404 405``` 406#define TASK_SWITCH_PARAMS(taskId, oldPriority, oldTaskStatus, newPriority, newTaskStatus) \ 407taskId, oldPriority, oldTaskStatus, newPriority, newTaskStatus 408``` 409 410Because of **\#TYPE\#\_PARAMS\(IDENTITY, parma1...\) IDENTITY, ...**, **Identity** is **taskId \(0x0\)** and the first parameter is **oldPriority \(0x1f\)**. 411 412> **NOTE:** 413>The number of **param**s is specified by the **LOSCFG\_TRACE\_FRAME\_MAX\_PARAMS** parameter. The default value is **3**. Excess parameters are not recorded. You need to set **LOSCFG\_TRACE\_FRAME\_MAX\_PARAMS** based on service requirements. 414 415Task 0x1 is switched to Task 0x0. The priority of task 0x1 is **0x1f**, and the state is **0x4**. The priority of the task 0x0 is **0x0**. 416 417
