erkin yucel / mbed-os

mbed os with nrf51 internal bandgap enabled to read battery level

Dependents:   BLE_file_test BLE_Blink ExternalEncoder

features/FEATURE_COMMON_PAL/mbed-trace/README.md@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

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