Kev Mann / mbed-dev-OS5_10_4

RTC auf true

features/frameworks/mbed-trace/README.md@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

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