sandbox / mbed-trace

Tracing Library

README.md@1:506ad37c6bd7, 2016-03-31 (annotated)

Committer:
Yogesh Pande
Date:
Thu Mar 31 18:10:53 2016 +0300
Revision:
1:506ad37c6bd7
mbed-trace v1.1.0

Who changed what in which revision?

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