Maxim nexpaq / nexpaq_dev

Preliminary main mbed library for nexpaq development

features/FEATURE_COMMON_PAL/mbed-trace/README.md@0:6c56fb4bc5f0, 2016-11-04 (annotated)

Committer:
nexpaq
Date:
Fri Nov 04 20:27:58 2016 +0000
Revision:
0:6c56fb4bc5f0
Moving to library for sharing updates

Who changed what in which revision?

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