Daiki Kato / mbed-os-lychee

mbed-os for GR-LYCHEE

Dependents:   mbed-os-example-blinky-gr-lychee GR-Boads_Camera_sample GR-Boards_Audio_Recoder GR-Boads_Camera_DisplayApp ... more

features/FEATURE_COMMON_PAL/mbed-trace/README.md@0:f782d9c66c49, 2018-02-02 (annotated)

Committer:
dkato
Date:
Fri Feb 02 05:42:23 2018 +0000
Revision:
0:f782d9c66c49
mbed-os for GR-LYCHEE

Who changed what in which revision?

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