Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
mbed_mem_trace.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2019 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef __MBED_MEM_TRACE_H__
19 #define __MBED_MEM_TRACE_H__
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 #include <stdint.h>
26 #include <stddef.h>
27 
28 /** \addtogroup platform-public-api */
29 /** @{*/
30 
31 /**
32  * enum Memory operation types for tracer
33  */
34 enum {
35  MBED_MEM_TRACE_MALLOC, /**< Identifier for malloc operation */
36  MBED_MEM_TRACE_REALLOC, /**< Identifier for realloc operation */
37  MBED_MEM_TRACE_CALLOC, /**< Identifier for calloc operation */
38  MBED_MEM_TRACE_FREE /**< Identifier for free operation */
39 };
40 
41 /**
42  * \defgroup platform_mem_trace mem_trace functions
43  * @{
44  */
45 
46 /* Prefix for the output of the default tracer */
47 #define MBED_MEM_DEFAULT_TRACER_PREFIX "#"
48 
49 /**
50  * Type of the callback used by the memory tracer. This callback is called when a memory
51  * allocation operation (malloc, realloc, calloc, free) is called and tracing is enabled
52  * for that memory allocation function.
53  *
54  * @param op the ID of the operation (MBED_MEM_TRACE_MALLOC, MBED_MEM_TRACE_REALLOC,
55  * MBED_MEM_TRACE_CALLOC or MBED_MEM_TRACE_FREE).
56  * @param res the result that the memory operation returned (NULL for 'free').
57  * @param caller the caller of the memory operation. Note that the value of 'caller' might be
58  * unreliable.
59  *
60  * The rest of the parameters passed 'mbed_mem_trace_cb_t' are the same as the memory operations
61  * that triggered its call (see 'man malloc' for details):
62  *
63  * - for malloc: cb(MBED_MEM_TRACE_MALLOC, res, caller, size).
64  * - for realloc: cb(MBED_MEM_TRACE_REALLOC, res, caller, ptr, size).
65  * - for calloc: cb(MBED_MEM_TRACE_CALLOC, res, caller, nmemb, size).
66  * - for free: cb(MBED_MEM_TRACE_FREE, NULL, caller, ptr).
67  */
68 typedef void (*mbed_mem_trace_cb_t)(uint8_t op, void *res, void *caller, ...);
69 
70 /**
71  * Set the callback used by the memory tracer (use NULL for disable tracing).
72  *
73  * @param cb the callback to call on each memory operation.
74  */
75 void mbed_mem_trace_set_callback(mbed_mem_trace_cb_t cb);
76 
77 /**
78  * Disable the memory trace output by disabling the callback function
79  */
80 void mbed_mem_trace_disable();
81 
82 /**
83  * Re-enable the memory trace output with the cb in use when disable was called
84  */
85 void mbed_mem_trace_enable();
86 
87 /**
88  * Trace lock.
89  * @note Locking prevent recursive tracing of malloc/free inside realloc/calloc
90  */
91 void mbed_mem_trace_lock();
92 
93 /**
94  * Trace unlock.
95  */
96 void mbed_mem_trace_unlock();
97 
98 /**
99  * Trace a call to 'malloc'.
100  * @param res the result of running 'malloc'.
101  * @param size the 'size' argument given to 'malloc'.
102  * @param caller the caller of the memory operation.
103  * @return 'res' (the first argument).
104  */
105 void *mbed_mem_trace_malloc(void *res, size_t size, void *caller);
106 
107 /**
108  * Trace a call to 'realloc'.
109  * @param res the result of running 'realloc'.
110  * @param ptr the 'ptr' argument given to 'realloc'.
111  * @param size the 'size' argument given to 'realloc'.
112  * @param caller the caller of the memory operation.
113  * @return 'res' (the first argument).
114  */
115 void *mbed_mem_trace_realloc(void *res, void *ptr, size_t size, void *caller);
116 
117 /**
118  * Trace a call to 'calloc'.
119  * @param res the result of running 'calloc'.
120  * @param num the 'nmemb' argument given to 'calloc'.
121  * @param size the 'size' argument given to 'calloc'.
122  * @param caller the caller of the memory operation.
123  * @return 'res' (the first argument).
124  */
125 void *mbed_mem_trace_calloc(void *res, size_t num, size_t size, void *caller);
126 
127 /**
128  * Trace a call to 'free'.
129  * @param ptr the 'ptr' argument given to 'free'.
130  * @param caller the caller of the memory operation.
131  */
132 void mbed_mem_trace_free(void *ptr, void *caller);
133 
134 /**
135  * Default memory trace callback. DO NOT CALL DIRECTLY. It is meant to be used
136  * as the second argument of 'mbed_mem_trace_setup'.
137  *
138  * The default callback outputs trace data using 'printf', in a format that's
139  * easily parsable by an external tool. For each memory operation, the callback
140  * outputs a line that begins with "#<op>:<0xresult>;<0xcaller>-":
141  *
142  * @param op identifies the memory operation ('m' for 'malloc', 'r' for 'realloc',
143  * 'c' for 'calloc' and 'f' for 'free').
144  * @param res (base 16) is the result of the memory operation. This is always NULL
145  * for 'free', since 'free' doesn't return anything.
146  * @param caller (base 16) is the caller of the memory operation. Note that the value
147  * of 'caller' might be unreliable.
148  *
149  * The rest of the output depends on the operation being traced:
150  *
151  * - for 'malloc': 'size', where 'size' is the original argument to 'malloc'.
152  * - for 'realloc': '0xptr;size', where 'ptr' (base 16) and 'size' are the original arguments to 'realloc'.
153  * - for 'calloc': 'nmemb;size', where 'nmemb' and 'size' are the original arguments to 'calloc'.
154  * - for 'free': '0xptr', where 'ptr' (base 16) is the original argument to 'free'.
155  *
156  * Examples:
157  *
158  * - "#m:0x20003240;0x600d-50" encodes a 'malloc' that returned 0x20003240, was called
159  * by the instruction at 0x600D with a the 'size' argument equal to 50.
160  * - "#f:0x0;0x602f-0x20003240" encodes a 'free' that was called by the instruction at
161  * 0x602f with the 'ptr' argument equal to 0x20003240.
162  */
163 void mbed_mem_trace_default_callback(uint8_t op, void *res, void *caller, ...);
164 
165 /** @}*/
166 
167 #ifdef __cplusplus
168 }
169 #endif
170 
171 #endif// #ifndef __MBED_MEM_TRACE_H__
172 
173 
174 /** @}*/
MBED_MEM_TRACE_FREE
Identifier for free operation.
Definition: mbed_mem_trace.h:38
mbed_mem_trace_unlock
void mbed_mem_trace_unlock()
Trace unlock.
mbed_mem_trace_set_callback
void mbed_mem_trace_set_callback(mbed_mem_trace_cb_t cb)
Set the callback used by the memory tracer (use NULL for disable tracing).
MBED_MEM_TRACE_REALLOC
Identifier for realloc operation.
Definition: mbed_mem_trace.h:36
mbed_mem_trace_enable
void mbed_mem_trace_enable()
Re-enable the memory trace output with the cb in use when disable was called.
mbed_mem_trace_lock
void mbed_mem_trace_lock()
Trace lock.
mbed_mem_trace_calloc
void * mbed_mem_trace_calloc(void *res, size_t num, size_t size, void *caller)
Trace a call to &#39;calloc&#39;.
mbed_mem_trace_malloc
void * mbed_mem_trace_malloc(void *res, size_t size, void *caller)
Trace a call to &#39;malloc&#39;.
mbed_mem_trace_default_callback
void mbed_mem_trace_default_callback(uint8_t op, void *res, void *caller,...)
Default memory trace callback.
mbed_mem_trace_disable
void mbed_mem_trace_disable()
Disable the memory trace output by disabling the callback function.
MBED_MEM_TRACE_CALLOC
Identifier for calloc operation.
Definition: mbed_mem_trace.h:37
MBED_MEM_TRACE_MALLOC
Identifier for malloc operation.
Definition: mbed_mem_trace.h:35
mbed_mem_trace_free
void mbed_mem_trace_free(void *ptr, void *caller)
Trace a call to &#39;free&#39;.
mbed_mem_trace_cb_t
void(* mbed_mem_trace_cb_t)(uint8_t op, void *res, void *caller,...)
Type of the callback used by the memory tracer.
Definition: mbed_mem_trace.h:68
mbed_mem_trace_realloc
void * mbed_mem_trace_realloc(void *res, void *ptr, size_t size, void *caller)
Trace a call to &#39;realloc&#39;.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.