Squashed 'features/frameworks/mbed-trace/' changes from 6df2572..9eaf0d1

9eaf0d1 Add documentation on how to change trace level. (ARMmbed#85)

git-subtree-dir: features/frameworks/mbed-trace
git-subtree-split: 9eaf0d146f0804a700aafbbd896f02c1acaaae66

README.md

@@ -109,6 +109,43 @@ Set the output function, `printf` by default:
 mbed_trace_print_function_set(printf)
 ```
 
+### Tracing level
+
+Run time tracing level is set using `mbed_trace_set_config()` function. Possible levels and examples how to set them is presented below.
+
+```c
+//mbed_trace_config_set(TRACE_ACTIVE_LEVEL_ALL);
+//mbed_trace_config_set(TRACE_ACTIVE_LEVEL_DEBUG); // (same as ALL)
+mbed_trace_config_set(TRACE_ACTIVE_LEVEL_INFO);
+//mbed_trace_config_set(TRACE_ACTIVE_LEVEL_WARN);
+//mbed_trace_config_set(TRACE_ACTIVE_LEVEL_ERROR);
+//mbed_trace_config_set(TRACE_ACTIVE_LEVEL_CMD);
+//mbed_trace_config_set(TRACE_ACTIVE_LEVEL_NONE);
+```
+
+Build time optimization can be done with `MBED_TRACE_MAX_LEVEL` definition. Setting max level to `TRACE_LEVEL_DEBUG` includes all traces to the build. Setting max level to `TRACE_LEVEL_INFO` includes all but `tr_debug()` traces to the build. Other maximum tracing levels follow the same behavior and no messages above the selected level are included in the build.
+
+```c
+#define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_DEBUG
+#define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_INFO
+#define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_WARN
+#define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_ERROR
+#define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_CMD
+```
+
+In Mbed OS, the build time maximum tracing level can be set through `mbed_app.json` as shown below.
+
+```
+{
+   "target_overrides":{
+      "*":{
+         "mbed-trace.enable": true,
+         "mbed-trace.max-level": "TRACE_LEVEL_INFO"
+      }
+   }
+}
+```
+
 ### Helping functions
 
 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:

mbed_lib.json

@@ -5,6 +5,12 @@
             "help": "Used to globally enable traces.",
             "value": null
         },
+        "max-level": {
+            "help": "This flag is used to optimize the code size. For example, setting trace optimization level to TRACE_LEVEL_INFO will define all tr_debug() macros empty, which reduces the binary size. The possible optimization levels are TRACE_LEVEL_DEBUG, TRACE_LEVEL_INFO, TRACE_LEVEL_WARN, TRACE_LEVEL_ERROR and TRACE_LEVEL_CMD. To set the output tracing level, please use mbed_trace_config_set(TRACE_ACTIVE_LEVEL_INFO). The possible tracing levels for mbed_trace_config_set() are TRACE_ACTIVE_LEVEL_ALL, TRACE_ACTIVE_LEVEL_DEBUG (same as ALL), TRACE_ACTIVE_LEVEL_INFO, TRACE_ACTIVE_LEVEL_WARN, TRACE_ACTIVE_LEVEL_ERROR, TRACE_ACTIVE_LEVEL_CMD and TRACE_LEVEL_NONE.",
+            "value": null,
+            "macro_name": "MBED_TRACE_MAX_LEVEL"
+
+        },
         "fea-ipv6": {
             "help": "Used to globally disable ipv6 tracing features.",
             "value": null

test/Test.cpp

@@ -239,6 +239,9 @@ TEST(trace, config_change)
 TEST(trace, active_level_all_color)
 {
   mbed_trace_config_set(TRACE_MODE_COLOR|TRACE_ACTIVE_LEVEL_ALL);
+  // unknown debug level
+  mbed_tracef(TRACE_LEVEL_DEBUG+1, "mygr", "hep");
+  STRCMP_EQUAL("              hep", buf);
   mbed_tracef(TRACE_LEVEL_DEBUG, "mygr", "hello");
   STRCMP_EQUAL("\x1b[90m[DBG ][mygr]: hello\x1b[0m", buf);
   mbed_tracef(TRACE_LEVEL_INFO, "mygr", "to one");
@@ -268,6 +271,10 @@ TEST(trace, change_levels)
 TEST(trace, active_level_debug)
 {
   mbed_trace_config_set(TRACE_ACTIVE_LEVEL_DEBUG);
+
+  // unknown debug level
+  mbed_tracef(TRACE_LEVEL_DEBUG+1, "mygr", "hep");
+  STRCMP_EQUAL("              hep", buf);
 
   mbed_tracef(TRACE_LEVEL_DEBUG, "mygr", "hep");
   STRCMP_EQUAL("[DBG ][mygr]: hep", buf);