.. | |||
include/ mbed-trace | 2 years ago | ||
source | 3 years ago | ||
.gitignore | 3 years ago | ||
.mbedignore | 3 years ago | ||
CMakeLists.txt | 2 years ago | ||
CONTRIBUTING.md | 3 years ago | ||
Jenkinsfile | 3 years ago | ||
LICENSE | 3 years ago | ||
Makefile.nanomesh | 3 years ago | ||
README.md | 3 years ago | ||
mbed_lib.json | 3 years ago |
A general purpose tracing abstraction library for mbed devices.
The purpose of the library is to provide a light, simple and general tracing solution for mbed devices. By default, it prints traces to stdout
(usually, a serial port), but the output can also be redirected to other targets. The library was developed using ANSI C language, but it can be used with C++ as well. Currently, there is no C++ wrapper available, but it can be created easily on top of this library.
<level>
, <group>
and <message>
stdout
as the default output target because it goes directly to serial port in mbed-os.[<levl>][grp ]: msg
. This provides an easy way to detect trace prints and separate traces from normal prints (for example with regex).sprintf
implementation (stdio.h
). The memory consumption is pretty high, but it allows an efficient way to format traces.[DBG ][abc ]: This is a debug message from module abc<cr><lf> [INFO][br ]: Hi there.<cr><lf> [WARN][br ]: Oh no, br warning occurs!<cr><lf> [ERR ][abc ]: Something goes wrong in module abc<cr><lf>
stdout
works. You can verify that the serial port works using the printf()
function.
YOTTA_CFG_MBED_TRACE
to 1 or true. Setting the flag to 0 or false disables tracing.MBED_TRACE_LINE_LENGTH
to the desired value.YOTTA_CFG_MBED_TRACE_FEA_IPV6 = 0
.MBED_CONF_MBED_TRACE_FEA_IPV6 = 0
.mbed_trace_init
) once before using any other APIs. It allocates the trace buffer and initializes the internal variables.TRACE_GROUP
in your source code (not in the header) to use traces. It is a 1-4 characters long char-array (for example #define TRACE_GROUP "APPL"
). This will be printed on every trace line.MBED_CONF_MBED_TRACE_ENABLE
to 1 or trueTo do so, add the following to your mbed_app.json:
{ "target_overrides": { "*": { "mbed-trace.enable": 1 } } }
Do not forget to fulfill the other prerequisites!
(Click here for more information on the configuration system)
When you want to print traces, use the tr_<level>
macros. The macros behave like printf()
. For example, tr_debug("hello %s", "trace")
produces the following trace line: [DBG ][APPL] hello trace<cr><lf>
.
Available levels:
For the thread safety, set the mutex wait and release functions. You need do this before the initialization to have the functions available right away:
mbed_trace_mutex_wait_function_set(my_mutex_wait); mbed_trace_mutex_release_function_set(my_mutex_release);
Initialization (once in application's lifetime):
int mbed_trace_init(void);
Set the output function, printf
by default:
mbed_trace_print_function_set(printf)
Run time tracing level is set using mbed_trace_set_config()
function. Possible levels and examples how to set them is presented below.
//mbed_trace_config_set(TRACE_ACTIVE_LEVEL_ALL); //mbed_trace_config_set(TRACE_ACTIVE_LEVEL_DEBUG); // (same as ALL) mbed_trace_config_set(TRACE_ACTIVE_LEVEL_INFO); //mbed_trace_config_set(TRACE_ACTIVE_LEVEL_WARN); //mbed_trace_config_set(TRACE_ACTIVE_LEVEL_ERROR); //mbed_trace_config_set(TRACE_ACTIVE_LEVEL_CMD); //mbed_trace_config_set(TRACE_ACTIVE_LEVEL_NONE);
Build time optimization can be done with MBED_TRACE_MAX_LEVEL
definition. Setting max level to TRACE_LEVEL_DEBUG
includes all traces to the build. Setting max level to TRACE_LEVEL_INFO
includes all but tr_debug()
traces to the build. Other maximum tracing levels follow the same behavior and no messages above the selected level are included in the build.
#define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_DEBUG #define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_INFO #define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_WARN #define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_ERROR #define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_CMD
In Mbed OS, the build time maximum tracing level can be set through mbed_app.json
as shown below.
{ "target_overrides":{ "*":{ "mbed-trace.enable": true, "mbed-trace.max-level": "TRACE_LEVEL_INFO" } } }
When max-level is not set by the application, default level is INFO.
The purpose of the helping functions is to provide simple conversions, for example from an array to C string, so that you can print everything to single trace line. They must be called inside the actual trace calls, for example:
tr_debug("My IP6 address: %s", mbed_trace_ipv6(addr));
Available conversion functions:
char *mbed_trace_ipv6(const void *addr_ptr) char *mbed_trace_ipv6_prefix(const uint8_t *prefix, uint8_t prefix_len) char *mbed_trace_array(const uint8_t *buf, uint16_t len)
See more in mbed_trace.h.
#define MBED_CONF_MBED_TRACE_ENABLE 1 //this could be defined also in the mbed-cli configuration file mbed_app.json #include "mbed-trace/mbed_trace.h" #define TRACE_GROUP "main" // These are necessary only if thread safety is needed static Mutex MyMutex; static void my_mutex_wait() { MyMutex.lock(); } static void my_mutex_release() { MyMutex.unlock(); } int main(void){ mbed_trace_mutex_wait_function_set( my_mutex_wait ); // only if thread safety is needed mbed_trace_mutex_release_function_set( my_mutex_release ); // only if thread safety is needed mbed_trace_init(); // initialize the trace library tr_debug("this is debug msg"); //-> "[DBG ][main]: this is a debug msg" tr_info("this is info msg"); //-> "[INFO][main]: this is an info msg" tr_warn("this is warning msg"); //-> "[WARN][main]: this is a warning msg" tr_err("this is error msg"); //-> "[ERR ][main]: this is an error msg" char arr[] = {30, 31, 32}; tr_debug("printing array: %s", mbed_trace_array(arr, 3)); //-> "[DBG ][main]: printing array: 01:02:03" return 0; }
The trace groups you have defined using the TRACE_GROUP
macro in your .c/.cpp files can be used to control tracing at run-time.
Function | Explanation |
---|---|
mbed_trace_include_filters_get() |
Get the exclusion filter list string. |
mbed_trace_include_filters_set() |
Set trace list to include only the traces matching the list. |
mbed_trace_exclude_filters_get() |
Get the inclusion filter list string. |
mbed_trace_exclude_filters_set() |
Set trace list to exclude the traces matching the list. |
The filter list is a null terminated string of comma (,
) separated trace group names. The default maximum length of the string is 24 characters, including the terminating null. Length can be changed by defining the macro DEFAULT_TRACE_FILTER_LENGTH
. Exclude and include filters can be combined freely as they both have their own filtering list.
The matching is done simply using strstr()
from C standard libraries.
Assuming we have 4 modules called "MAIN", "HELP", "CALC" and "PRNT" we could use the filters in the following ways.
To include only "MAIN" and "CALC" traces to the trace prints, we can do:
mbed_trace_include_filters_set("MAIN,CALC");
This would print out only the traces from "MAIN" and "CALC", since they are the trace groups matching the filter list. Trace groups "HELP" and "PRNT" would not be printed out at all.
mbed_trace_exclude_filters_set("HELP,PRNT");
This would exclue trace groups "HELP" and "PRNT" out of trace printing, thus leaving only prints from "MAIN" and "CALC" visible in the tracing.
mbed_trace_include_filters_set(NULL);
This would reset the inclusion filters back to nothing and assuming no exclusion filter is in place either, all trace groups prints would get printed.
To run unit tests:
yotta target x86-linux-native yotta test mbed_trace_test
yotta target x86-osx-native yotta test mbed_trace_test
yotta target x86-windows-native yotta test mbed_trace_test