takashi kadono / Mbed OS Nucleo_446

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   ssd1331

mbed-os/features/frameworks/mbed-trace/README.md@3:f3764f852aa8, 2018-10-11 (annotated)

Committer:
kadonotakashi
Date:
Thu Oct 11 02:27:46 2018 +0000
Revision:
3:f3764f852aa8
Parent:
0:8fdf9a60065b 
Nucreo 446 + SSD1331 test version;

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kadonotakashi 0:8fdf9a60065b 1 # mbed-trace
kadonotakashi 0:8fdf9a60065b 2
kadonotakashi 0:8fdf9a60065b 3 A general purpose tracing abstraction library for mbed devices.
kadonotakashi 0:8fdf9a60065b 4
kadonotakashi 0:8fdf9a60065b 5 ## Description
kadonotakashi 0:8fdf9a60065b 6
kadonotakashi 0:8fdf9a60065b 7 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.
kadonotakashi 0:8fdf9a60065b 8
kadonotakashi 0:8fdf9a60065b 9 ## Philosophy
kadonotakashi 0:8fdf9a60065b 10
kadonotakashi 0:8fdf9a60065b 11 * The library needs to be light, fast, simple and abstract.
kadonotakashi 0:8fdf9a60065b 12 * Dependencies must be minimal.
kadonotakashi 0:8fdf9a60065b 13 * The memory space required by the library is allocated at the initialization only once during the application lifetime.
kadonotakashi 0:8fdf9a60065b 14 * No new malloc/free are needed when running the library.
kadonotakashi 0:8fdf9a60065b 15 * The trace methods must be as fast as possible.
kadonotakashi 0:8fdf9a60065b 16 * After a trace method call, the trace function needs to release the required resources.
kadonotakashi 0:8fdf9a60065b 17 * A trace method call produces a single line containing `<level>`, `<group>` and `<message>`
kadonotakashi 0:8fdf9a60065b 18 * It must be possible to filter messages on the fly. Compile time filtering is not fully supported yet.
kadonotakashi 0:8fdf9a60065b 19
kadonotakashi 0:8fdf9a60065b 20 ## Compromises
kadonotakashi 0:8fdf9a60065b 21
kadonotakashi 0:8fdf9a60065b 22 * The traces are stored as ASCII arrays in the flash memory (pretty high memory consumption). Therefore, it is not necessary to:
kadonotakashi 0:8fdf9a60065b 23 * encode/decode the trace messages on the fly (this may take too much CPU time) or
kadonotakashi 0:8fdf9a60065b 24 * have external dev-env dependencies to encode the traces compile time and an external application to decode the traces.
kadonotakashi 0:8fdf9a60065b 25 * The group name length is limited to four characters. This makes the lines cleaner and it is enough for most use cases for separating the module names. The group name length may not be suitable for a clean human readable format, but still four characters is enough for unique module names.
kadonotakashi 0:8fdf9a60065b 26 * The trace function uses `stdout` as the default output target because it goes directly to serial port when initialized.
kadonotakashi 0:8fdf9a60065b 27 * The trace function produces traces like: `[<levl>][grp ]: msg`. This provides an easy way to detect trace prints and separate traces from normal prints (for example with _regex_).
kadonotakashi 0:8fdf9a60065b 28 * This approach requires a `sprintf` implementation (`stdio.h`). The memory consumption is pretty high, but it allows an efficient way to format traces.
kadonotakashi 0:8fdf9a60065b 29 * The solution is not Interrupt safe. (PRs are more than welcome.)
kadonotakashi 0:8fdf9a60065b 30 * The solution is not Thread safe by default. Thread safety for the actual trace calls can be enabled by providing wait and release callback functions that use mutexes defined by the application.
kadonotakashi 0:8fdf9a60065b 31
kadonotakashi 0:8fdf9a60065b 32 ## Examples of traces
kadonotakashi 0:8fdf9a60065b 33
kadonotakashi 0:8fdf9a60065b 34 ```
kadonotakashi 0:8fdf9a60065b 35 [DBG ][abc ]: This is a debug message from module abc<cr><lf>
kadonotakashi 0:8fdf9a60065b 36 [INFO][br ]: Hi there.<cr><lf>
kadonotakashi 0:8fdf9a60065b 37 [WARN][br ]: Oh no, br warning occurs!<cr><lf>
kadonotakashi 0:8fdf9a60065b 38 [ERR ][abc ]: Something goes wrong in module abc<cr><lf>
kadonotakashi 0:8fdf9a60065b 39 ```
kadonotakashi 0:8fdf9a60065b 40
kadonotakashi 0:8fdf9a60065b 41 ## Usage
kadonotakashi 0:8fdf9a60065b 42
kadonotakashi 0:8fdf9a60065b 43 ### Prerequisites
kadonotakashi 0:8fdf9a60065b 44
kadonotakashi 0:8fdf9a60065b 45 * Initialize the serial port so that `stdout` works. You can verify that the serial port works using the `printf()` function.
kadonotakashi 0:8fdf9a60065b 46 * if you want to redirect the traces somewhere else, see the [trace API](https://github.com/ARMmbed/mbed-trace/blob/master/mbed-trace/mbed_trace.h#L170).
kadonotakashi 0:8fdf9a60065b 47 * To enable the tracing API:
kadonotakashi 0:8fdf9a60065b 48 * With yotta: set `YOTTA_CFG_MBED_TRACE` to 1 or true. Setting the flag to 0 or false disables tracing.
kadonotakashi 0:8fdf9a60065b 49 * [With mbed OS 5](#enabling-the-tracing-api-in-mbed-os-5)
kadonotakashi 0:8fdf9a60065b 50 * By default, trace uses 1024 bytes buffer for trace lines, but you can change it by setting the configuration macro `MBED_TRACE_LINE_LENGTH` to the desired value.
kadonotakashi 0:8fdf9a60065b 51 * To disable the IPv6 conversion:
kadonotakashi 0:8fdf9a60065b 52 * With yotta: set `YOTTA_CFG_MBED_TRACE_FEA_IPV6 = 0`.
kadonotakashi 0:8fdf9a60065b 53 * With mbed OS 5: set `MBED_CONF_MBED_TRACE_FEA_IPV6 = 0`.
kadonotakashi 0:8fdf9a60065b 54 * If thread safety is needed, configure the wait and release callback functions before initialization to enable the protection. Usually, this needs to be done only once in the application's lifetime.
kadonotakashi 0:8fdf9a60065b 55 * If [helping functions](#helping-functions) are used the mutex must be **recursive** (counting) so it can be acquired from a single thread repeatedly.
kadonotakashi 0:8fdf9a60065b 56 * Call the trace initialization (`mbed_trace_init`) once before using any other APIs. It allocates the trace buffer and initializes the internal variables.
kadonotakashi 0:8fdf9a60065b 57 * Define `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.
kadonotakashi 0:8fdf9a60065b 58
kadonotakashi 0:8fdf9a60065b 59 ### Enabling the tracing API in mbed OS 5
kadonotakashi 0:8fdf9a60065b 60
kadonotakashi 0:8fdf9a60065b 61 * Set `MBED_CONF_MBED_TRACE_ENABLE` to 1 or true
kadonotakashi 0:8fdf9a60065b 62
kadonotakashi 0:8fdf9a60065b 63 To do so, add the following to your mbed_app.json:
kadonotakashi 0:8fdf9a60065b 64
kadonotakashi 0:8fdf9a60065b 65 ```json
kadonotakashi 0:8fdf9a60065b 66 {
kadonotakashi 0:8fdf9a60065b 67 "target_overrides": {
kadonotakashi 0:8fdf9a60065b 68 "*": {
kadonotakashi 0:8fdf9a60065b 69 "mbed-trace.enable": 1
kadonotakashi 0:8fdf9a60065b 70 }
kadonotakashi 0:8fdf9a60065b 71 }
kadonotakashi 0:8fdf9a60065b 72 }
kadonotakashi 0:8fdf9a60065b 73 ```
kadonotakashi 0:8fdf9a60065b 74
kadonotakashi 0:8fdf9a60065b 75 Don't forget to fulfill the other [prerequisites](#prerequisites)!
kadonotakashi 0:8fdf9a60065b 76
kadonotakashi 0:8fdf9a60065b 77 ([Click here for more information on the configuration system](https://docs.mbed.com/docs/mbed-os-api/en/latest/config_system/))
kadonotakashi 0:8fdf9a60065b 78
kadonotakashi 0:8fdf9a60065b 79 ### Traces
kadonotakashi 0:8fdf9a60065b 80
kadonotakashi 0:8fdf9a60065b 81 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>`.
kadonotakashi 0:8fdf9a60065b 82
kadonotakashi 0:8fdf9a60065b 83 Available levels:
kadonotakashi 0:8fdf9a60065b 84
kadonotakashi 0:8fdf9a60065b 85 * debug
kadonotakashi 0:8fdf9a60065b 86 * info
kadonotakashi 0:8fdf9a60065b 87 * warning
kadonotakashi 0:8fdf9a60065b 88 * error
kadonotakashi 0:8fdf9a60065b 89 * cmdline (special behavior, should not be used)
kadonotakashi 0:8fdf9a60065b 90
kadonotakashi 0:8fdf9a60065b 91 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:
kadonotakashi 0:8fdf9a60065b 92
kadonotakashi 0:8fdf9a60065b 93 ```c
kadonotakashi 0:8fdf9a60065b 94 mbed_trace_mutex_wait_function_set(my_mutex_wait);
kadonotakashi 0:8fdf9a60065b 95 mbed_trace_mutex_release_function_set(my_mutex_release);
kadonotakashi 0:8fdf9a60065b 96 ```
kadonotakashi 0:8fdf9a60065b 97
kadonotakashi 0:8fdf9a60065b 98 Initialization (once in application's lifetime):
kadonotakashi 0:8fdf9a60065b 99
kadonotakashi 0:8fdf9a60065b 100 ```c
kadonotakashi 0:8fdf9a60065b 101 int mbed_trace_init(void);
kadonotakashi 0:8fdf9a60065b 102 ```
kadonotakashi 0:8fdf9a60065b 103
kadonotakashi 0:8fdf9a60065b 104 Set the output function, `printf` by default:
kadonotakashi 0:8fdf9a60065b 105
kadonotakashi 0:8fdf9a60065b 106 ```c
kadonotakashi 0:8fdf9a60065b 107 mbed_trace_print_function_set(printf)
kadonotakashi 0:8fdf9a60065b 108 ```
kadonotakashi 0:8fdf9a60065b 109
kadonotakashi 0:8fdf9a60065b 110 ### Helping functions
kadonotakashi 0:8fdf9a60065b 111
kadonotakashi 0:8fdf9a60065b 112 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:
kadonotakashi 0:8fdf9a60065b 113
kadonotakashi 0:8fdf9a60065b 114 ```
kadonotakashi 0:8fdf9a60065b 115 tr_debug("My IP6 address: %s", mbed_trace_ipv6(addr));
kadonotakashi 0:8fdf9a60065b 116 ```
kadonotakashi 0:8fdf9a60065b 117
kadonotakashi 0:8fdf9a60065b 118 Available conversion functions:
kadonotakashi 0:8fdf9a60065b 119
kadonotakashi 0:8fdf9a60065b 120 ```
kadonotakashi 0:8fdf9a60065b 121 char *mbed_trace_ipv6(const void *addr_ptr)
kadonotakashi 0:8fdf9a60065b 122 char *mbed_trace_ipv6_prefix(const uint8_t *prefix, uint8_t prefix_len)
kadonotakashi 0:8fdf9a60065b 123 char *mbed_trace_array(const uint8_t *buf, uint16_t len)
kadonotakashi 0:8fdf9a60065b 124 ```
kadonotakashi 0:8fdf9a60065b 125
kadonotakashi 0:8fdf9a60065b 126 See more in [mbed_trace.h](https://github.com/ARMmbed/mbed-trace/blob/master/mbed-trace/mbed_trace.h).
kadonotakashi 0:8fdf9a60065b 127
kadonotakashi 0:8fdf9a60065b 128
kadonotakashi 0:8fdf9a60065b 129 ## Usage example:
kadonotakashi 0:8fdf9a60065b 130
kadonotakashi 0:8fdf9a60065b 131 ```c++
kadonotakashi 0:8fdf9a60065b 132 #define MBED_CONF_MBED_TRACE_ENABLE 1 //this could be defined also in the mbed-cli configuration file mbed_app.json
kadonotakashi 0:8fdf9a60065b 133 #include "mbed-trace/mbed_trace.h"
kadonotakashi 0:8fdf9a60065b 134 #define TRACE_GROUP "main"
kadonotakashi 0:8fdf9a60065b 135
kadonotakashi 0:8fdf9a60065b 136 // These are necessary only if thread safety is needed
kadonotakashi 0:8fdf9a60065b 137 static Mutex MyMutex;
kadonotakashi 0:8fdf9a60065b 138 static void my_mutex_wait()
kadonotakashi 0:8fdf9a60065b 139 {
kadonotakashi 0:8fdf9a60065b 140 MyMutex.lock();
kadonotakashi 0:8fdf9a60065b 141 }
kadonotakashi 0:8fdf9a60065b 142 static void my_mutex_release()
kadonotakashi 0:8fdf9a60065b 143 {
kadonotakashi 0:8fdf9a60065b 144 MyMutex.unlock();
kadonotakashi 0:8fdf9a60065b 145 }
kadonotakashi 0:8fdf9a60065b 146
kadonotakashi 0:8fdf9a60065b 147 int main(void){
kadonotakashi 0:8fdf9a60065b 148 mbed_trace_mutex_wait_function_set( my_mutex_wait ); // only if thread safety is needed
kadonotakashi 0:8fdf9a60065b 149 mbed_trace_mutex_release_function_set( my_mutex_release ); // only if thread safety is needed
kadonotakashi 0:8fdf9a60065b 150 mbed_trace_init(); // initialize the trace library
kadonotakashi 0:8fdf9a60065b 151 tr_debug("this is debug msg"); //-> "[DBG ][main]: this is a debug msg"
kadonotakashi 0:8fdf9a60065b 152 tr_info("this is info msg"); //-> "[INFO][main]: this is an info msg"
kadonotakashi 0:8fdf9a60065b 153 tr_warn("this is warning msg"); //-> "[WARN][main]: this is a warning msg"
kadonotakashi 0:8fdf9a60065b 154 tr_err("this is error msg"); //-> "[ERR ][main]: this is an error msg"
kadonotakashi 0:8fdf9a60065b 155 char arr[] = {30, 31, 32};
kadonotakashi 0:8fdf9a60065b 156 tr_debug("printing array: %s", mbed_trace_array(arr, 3)); //-> "[DBG ][main]: printing array: 01:02:03"
kadonotakashi 0:8fdf9a60065b 157 return 0;
kadonotakashi 0:8fdf9a60065b 158 }
kadonotakashi 0:8fdf9a60065b 159 ```
kadonotakashi 0:8fdf9a60065b 160
kadonotakashi 0:8fdf9a60065b 161 ## Unit tests
kadonotakashi 0:8fdf9a60065b 162
kadonotakashi 0:8fdf9a60065b 163 To run unit tests:
kadonotakashi 0:8fdf9a60065b 164
kadonotakashi 0:8fdf9a60065b 165 * In Linux
kadonotakashi 0:8fdf9a60065b 166
kadonotakashi 0:8fdf9a60065b 167 ```
kadonotakashi 0:8fdf9a60065b 168 yotta target x86-linux-native
kadonotakashi 0:8fdf9a60065b 169 yotta test mbed_trace_test
kadonotakashi 0:8fdf9a60065b 170 ```
kadonotakashi 0:8fdf9a60065b 171
kadonotakashi 0:8fdf9a60065b 172 * In Mac
kadonotakashi 0:8fdf9a60065b 173
kadonotakashi 0:8fdf9a60065b 174 ```
kadonotakashi 0:8fdf9a60065b 175 yotta target x86-osx-native
kadonotakashi 0:8fdf9a60065b 176 yotta test mbed_trace_test
kadonotakashi 0:8fdf9a60065b 177 ```
kadonotakashi 0:8fdf9a60065b 178
kadonotakashi 0:8fdf9a60065b 179 * In Windows
kadonotakashi 0:8fdf9a60065b 180
kadonotakashi 0:8fdf9a60065b 181 ```
kadonotakashi 0:8fdf9a60065b 182 yotta target x86-windows-native
kadonotakashi 0:8fdf9a60065b 183 yotta test mbed_trace_test
kadonotakashi 0:8fdf9a60065b 184 ```