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