• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Trace Debugging<a name="EN-US_TOPIC_0000001162019075"></a>
2
3-   [Basic Concepts](#section44851752123712)
4-   [Working Principles](#section5282148123813)
5-   [Available APIs](#section16304193215387)
6-   [Development Guidelines](#section498695853819)
7    -   [How to Develop](#section1875652316393)
8    -   [Development Example](#section0403134913395)
9    -   [Sample Code](#section1492711418400)
10    -   [Verification](#section869613984012)
11
12
13## Basic Concepts<a name="section44851752123712"></a>
14
15Trace debugging 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.
16
17## Working Principles<a name="section5282148123813"></a>
18
19The kernel provides a framework to embed hooks in main processes of modules. You can register callback functions at the required hooks. When the kernel runs the corresponding process, the kernel proactively calls the  **Hook**  function to transfer key data of the current process to you.
20
21## Available APIs<a name="section16304193215387"></a>
22
23The following table describes APIs available for the OpenHarmony trace module. For more details about the APIs, see the API reference.
24
25**Table  1**  Trace module APIs
26
27<a name="table208266479117"></a>
28<table><thead align="left"><tr id="row19826947121114"><th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.1"><p id="p16415637105612"><a name="p16415637105612"></a><a name="p16415637105612"></a>Category</p>
29</th>
30<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.2"><p id="p11415163718562"><a name="p11415163718562"></a><a name="p11415163718562"></a>API</p>
31</th>
32<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.3"><p id="p1641533755612"><a name="p1641533755612"></a><a name="p1641533755612"></a>Description</p>
33</th>
34</tr>
35</thead>
36<tbody><tr id="row082617478118"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p1082624717117"><a name="p1082624717117"></a><a name="p1082624717117"></a>Registering a hook</p>
37</td>
38<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p1182654713112"><a name="p1182654713112"></a><a name="p1182654713112"></a>LOS_HookReg</p>
39</td>
40<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p1582614474114"><a name="p1582614474114"></a><a name="p1582614474114"></a>Registers a callback function at a specified hook.</p>
41</td>
42</tr>
43<tr id="row19470201017154"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.1 "><p id="p1747021015152"><a name="p1747021015152"></a><a name="p1747021015152"></a>Unregistering a hook</p>
44</td>
45<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.2 "><p id="p16470410201517"><a name="p16470410201517"></a><a name="p16470410201517"></a>LOS_HookUnReg</p>
46</td>
47<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p147021017155"><a name="p147021017155"></a><a name="p147021017155"></a>Unregisters the callback function at the current hook.</p>
48</td>
49</tr>
50</tbody>
51</table>
52
53## Development Guidelines<a name="section498695853819"></a>
54
55### How to Develop<a name="section1875652316393"></a>
56
57The typical process for enabling trace debugging is as follows:
58
591.  Configure the macros related to the trace module.
60
61    Modify the configuration in the  **target\_config.h**  file.
62
63    <a name="table1078714915105"></a>
64    <table><thead align="left"><tr id="row1280518971010"><th class="cellrowborder" valign="top" width="27.24%" id="mcps1.1.4.1.1"><p id="p1380510912104"><a name="p1380510912104"></a><a name="p1380510912104"></a>Parameter</p>
65    </th>
66    <th class="cellrowborder" valign="top" width="30.330000000000002%" id="mcps1.1.4.1.2"><p id="p08051291106"><a name="p08051291106"></a><a name="p08051291106"></a>Description</p>
67    </th>
68    <th class="cellrowborder" valign="top" width="42.43%" id="mcps1.1.4.1.3"><p id="p12805149151012"><a name="p12805149151012"></a><a name="p12805149151012"></a>Value</p>
69    </th>
70    </tr>
71    </thead>
72    <tbody><tr id="row168052913104"><td class="cellrowborder" valign="top" width="27.24%" headers="mcps1.1.4.1.1 "><p id="p180618915101"><a name="p180618915101"></a><a name="p180618915101"></a>LOSCFG_DEBUG_HOOK</p>
73    </td>
74    <td class="cellrowborder" valign="top" width="30.330000000000002%" headers="mcps1.1.4.1.2 "><p id="p198061196105"><a name="p198061196105"></a><a name="p198061196105"></a>Setting of the trace function</p>
75    </td>
76    <td class="cellrowborder" valign="top" width="42.43%" headers="mcps1.1.4.1.3 "><p id="p1980609121010"><a name="p1980609121010"></a><a name="p1980609121010"></a><strong id="b263016731715"><a name="b263016731715"></a><a name="b263016731715"></a>0</strong>: disable; <strong id="b632420116171"><a name="b632420116171"></a><a name="b632420116171"></a>1</strong>: enable</p>
77    </td>
78    </tr>
79    </tbody>
80    </table>
81
822.  Select the hooks for registering callback functions. For details about the hook types, see  **liteos\_m/utils/internal/los\_hook\_types.h**.
833.  Call  **LOS\_HookReg**  to register functions.
84
85### Development Example<a name="section0403134913395"></a>
86
87This example invokes the malloc and free APIs to allocate and release memory of different sizes and records the malloc and free behavior and time sequence.
88
89### Sample Code<a name="section1492711418400"></a>
90
91The sample code is as follows:
92
93```
94#include "stdio.h"
95#include "stdlib.h"
96#include "string.h"
97#include "los_hook.h"
98
99#define SIZE_512        512
100#define SIZE_1K         1024
101#define SIZE_2K         2048
102
103/* Print the size of malloc when the callback function is invoked. */
104void MallocRecord(void *pool, unsigned int size)
105{
106    printf("malloc size = %u\n", size);
107    return;
108}
109
110/* Print the free pointer address when the callback function is invoked. */
111void FreeRecord(void *pool, void *ptr)
112{
113    printf("free pool = 0x%x ptr = 0x%x\n", pool, ptr);
114    return;
115}
116
117void TestTrace(void)
118{
119    char *pool1 = NULL;
120    char *pool2 = NULL;
121    char *pool3 = NULL;
122    char *retptr = NULL;
123    /* Allocate memory of different sizes to pool1, pool2, and pool3. */
124    pool1 = (char *)malloc(SIZE_512);
125    if (pool1 == NULL) {
126        printf("pool1 malloc failed!\n");
127        return;
128    }
129    retptr = memset(pool1, 'a', SIZE_512);
130    if (retptr == NULL) {
131        printf("pool1 memset failed!\n");
132        return;
133    }
134    printf("pool1 addr = 0x%x *pool1[0] = %c\n", pool1, *pool1);
135
136    pool2 = (char *)malloc(SIZE_1K);
137    if (pool2 == NULL) {
138        printf("pool2 malloc failed!\n");
139        return;
140    }
141    retptr = memset(pool2, 'b', SIZE_1K);
142    if (retptr == NULL) {
143        printf("pool2 memset failed!\n");
144        return;
145    }
146    printf("pool2 addr = 0x%x *pool2[0] = %c\n", pool2, *pool2);
147
148    pool3 = (char *)malloc(SIZE_2K);
149    if (pool3 == NULL) {
150        printf("pool3 malloc failed!\n");
151        return;
152    }
153    retptr = memset(pool3, 'c', SIZE_2K);
154    if (retptr == NULL) {
155        printf("pool3 memset failed!\n");
156        return;
157    }
158    printf("pool3 addr = 0x%x *pool3[0] = %c\n", pool3, *pool3);
159
160    /* Release pool3, pool1, and pool2 in sequence to check the time sequence of the callback functions. */
161    free(pool3);
162    free(pool1);
163    free(pool2);
164
165    return;
166}
167/* Before the trace module is used, callback functions are registered. Note that the return value of the callback functions is void. */
168void InitTest(void)
169{
170    printf("init hook\n");
171    /* Register the hook based on the trace information to be obtained. For details about the hook types, see liteos_m/utils/internal/los_hook_types.h. */.
172    LOS_HookReg(LOS_HOOK_TYPE_MEM_ALLOC, MallocRecord);
173    LOS_HookReg(LOS_HOOK_TYPE_MEM_FREE, FreeRecord);
174    return;
175}
176```
177
178### Verification<a name="section869613984012"></a>
179
180The output is as follows:
181
182```
183init hook
184malloc size = 512
185pool1 addr = 0x20002f44 *pool1[0] = a
186malloc size = 1024
187pool2 addr = 0x2000314c *pool2[0] = b
188malloc size = 2048
189pool3 addr = 0x20003554 *pool3[0] = c
190free pool = 0x200002a4 ptr = 0x20003554
191free pool = 0x200002a4 ptr = 0x20002f44
192free pool = 0x200002a4 ptr = 0x2000314c
193```
194
195According to the address information, the sequence of free is pool3, pool1, and pool2.
196
197