mbed_trace.h

00001 /*
00002  * Copyright (c) 2015 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /**
00018  * \file mbed_trace.h
00019  * Trace interface for MbedOS applications.
00020  * This file provide simple but flexible way to handle software traces.
00021  * Trace library are abstract layer, which use stdout (printf) by default,
00022  * but outputs can be easily redirect to custom function, for example to
00023  * store traces to memory or other interfaces.
00024  *
00025  *  usage example:
00026  * \code(main.c:)
00027  *      #include "mbed_trace.h"
00028  *      #define TRACE_GROUP  "main"
00029  *
00030  *      int main(void){
00031  *          mbed_trace_init();   // initialize trace library
00032  *          tr_debug("this is debug msg");  //print debug message to stdout: "[DBG]
00033  *          tr_info("this is info msg");
00034  *          tr_warn("this is warning msg");
00035  *          tr_err("this is error msg");
00036  *          return 0;
00037  *      }
00038  * \endcode
00039  * Activate with compiler flag: YOTTA_CFG_MBED_TRACE
00040  * Configure trace line buffer size with compiler flag: YOTTA_CFG_MBED_TRACE_LINE_LENGTH. Default length: 1024.
00041  * Limit the size of flash by setting MBED_TRACE_MAX_LEVEL value. Default is TRACE_LEVEL_DEBUG (all included)
00042  *
00043  */
00044 #ifndef MBED_TRACE_H_
00045 #define MBED_TRACE_H_
00046 
00047 #ifdef __cplusplus
00048 extern "C" {
00049 #endif
00050 
00051 #include <stdint.h>
00052 #include <stddef.h>
00053 #include <stdbool.h>
00054 #include <stdarg.h>
00055 #include <inttypes.h>
00056 
00057 #ifndef YOTTA_CFG_MBED_TRACE
00058 #define YOTTA_CFG_MBED_TRACE 0
00059 #endif
00060 
00061 #ifndef YOTTA_CFG_MBED_TRACE_FEA_IPV6
00062 #define YOTTA_CFG_MBED_TRACE_FEA_IPV6 1
00063 #else
00064 #warning YOTTA_CFG_MBED_TRACE_FEA_IPV6 is deprecated and will be removed in the future! Use MBED_CONF_MBED_TRACE_FEA_IPV6 instead.
00065 #define MBED_CONF_MBED_TRACE_FEA_IPV6 YOTTA_CFG_MBED_TRACE_FEA_IPV6
00066 #endif
00067 
00068 #ifndef MBED_CONF_MBED_TRACE_ENABLE
00069 #define MBED_CONF_MBED_TRACE_ENABLE 0
00070 #endif
00071 
00072 #ifndef MBED_CONF_MBED_TRACE_FEA_IPV6
00073 #define MBED_CONF_MBED_TRACE_FEA_IPV6 1
00074 #endif
00075 
00076 /** 3 upper bits are trace modes related,
00077     and 5 lower bits are trace level configuration */
00078 
00079 /** Config mask */
00080 #define TRACE_MASK_CONFIG         0xE0
00081 /** Trace level mask */
00082 #define TRACE_MASK_LEVEL          0x1F
00083 
00084 /** plain trace data instead of "headers" */
00085 #define TRACE_MODE_PLAIN          0x80
00086 /** color mode */
00087 #define TRACE_MODE_COLOR          0x40
00088 /** Use print CR before trace line */
00089 #define TRACE_CARRIAGE_RETURN     0x20
00090 
00091 /** used to activate all trace levels */
00092 #define TRACE_ACTIVE_LEVEL_ALL    0x1F
00093 /** print all traces same as above */
00094 #define TRACE_ACTIVE_LEVEL_DEBUG  0x1f
00095 /** print info,warn and error traces */
00096 #define TRACE_ACTIVE_LEVEL_INFO   0x0f
00097 /** print warn and error traces */
00098 #define TRACE_ACTIVE_LEVEL_WARN   0x07
00099 /** print only error trace */
00100 #define TRACE_ACTIVE_LEVEL_ERROR  0x03
00101 /** print only cmd line data */
00102 #define TRACE_ACTIVE_LEVEL_CMD    0x01
00103 /** trace nothing  */
00104 #define TRACE_ACTIVE_LEVEL_NONE   0x00
00105 
00106 /** this print is some deep information for debug purpose */
00107 #define TRACE_LEVEL_DEBUG         0x10
00108 /** Info print, for general purpose prints */
00109 #define TRACE_LEVEL_INFO          0x08
00110 /** warning prints, which shouldn't causes any huge problems */
00111 #define TRACE_LEVEL_WARN          0x04
00112 /** Error prints, which causes probably problems, e.g. out of mem. */
00113 #define TRACE_LEVEL_ERROR         0x02
00114 /** special level for cmdline. Behaviours like "plain mode" */
00115 #define TRACE_LEVEL_CMD           0x01
00116 
00117 #ifndef MBED_TRACE_MAX_LEVEL
00118 #define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_DEBUG
00119 #endif
00120 
00121 //usage macros:
00122 #if MBED_TRACE_MAX_LEVEL >= TRACE_LEVEL_DEBUG
00123 #define tr_debug(...)           mbed_tracef(TRACE_LEVEL_DEBUG,   TRACE_GROUP, __VA_ARGS__)   //!< Print debug message
00124 #else
00125 #define tr_debug(...)
00126 #endif
00127 
00128 #if MBED_TRACE_MAX_LEVEL >= TRACE_LEVEL_INFO
00129 #define tr_info(...)            mbed_tracef(TRACE_LEVEL_INFO,    TRACE_GROUP, __VA_ARGS__)   //!< Print info message
00130 #else
00131 #define tr_info(...)
00132 #endif
00133 
00134 #if MBED_TRACE_MAX_LEVEL >= TRACE_LEVEL_WARN
00135 #define tr_warning(...)         mbed_tracef(TRACE_LEVEL_WARN,    TRACE_GROUP, __VA_ARGS__)   //!< Print warning message
00136 #define tr_warn(...)            mbed_tracef(TRACE_LEVEL_WARN,    TRACE_GROUP, __VA_ARGS__)   //!< Alternative warning message
00137 #else
00138 #define tr_warning(...)
00139 #define tr_warn(...)
00140 #endif
00141 
00142 #if MBED_TRACE_MAX_LEVEL >= TRACE_LEVEL_ERROR
00143 #define tr_error(...)           mbed_tracef(TRACE_LEVEL_ERROR,   TRACE_GROUP, __VA_ARGS__)   //!< Print Error Message
00144 #define tr_err(...)             mbed_tracef(TRACE_LEVEL_ERROR,   TRACE_GROUP, __VA_ARGS__)   //!< Alternative error message
00145 #else
00146 #define tr_error(...)
00147 #define tr_err(...)
00148 #endif
00149 
00150 #define tr_cmdline(...)         mbed_tracef(TRACE_LEVEL_CMD,     TRACE_GROUP, __VA_ARGS__)   //!< Special print for cmdline. See more from TRACE_LEVEL_CMD -level
00151 
00152 //aliases for the most commonly used functions and the helper functions
00153 #define tracef(dlevel, grp, ...)                mbed_tracef(dlevel, grp, __VA_ARGS__)       //!< Alias for mbed_tracef()
00154 #define vtracef(dlevel, grp, fmt, ap)           mbed_vtracef(dlevel, grp, fmt, ap)          //!< Alias for mbed_vtracef()
00155 #define tr_array(buf, len)                      mbed_trace_array(buf, len)                  //!< Alias for mbed_trace_array()
00156 #define tr_ipv6(addr_ptr)                       mbed_trace_ipv6(addr_ptr)                   //!< Alias for mbed_trace_ipv6()
00157 #define tr_ipv6_prefix(prefix, prefix_len)      mbed_trace_ipv6_prefix(prefix, prefix_len)  //!< Alias for mbed_trace_ipv6_prefix()
00158 #define trace_array(buf, len)                   mbed_trace_array(buf, len)                  //!< Alias for mbed_trace_array()
00159 #define trace_ipv6(addr_ptr)                    mbed_trace_ipv6(addr_ptr)                   //!< Alias for mbed_trace_ipv6()
00160 #define trace_ipv6_prefix(prefix, prefix_len)   mbed_trace_ipv6_prefix(prefix, prefix_len)  //!< Alias for mbed_trace_ipv6_prefix()
00161 
00162 
00163 /**
00164  * Allow specification of default TRACE_GROUP to be used if not specified by application
00165  */
00166 
00167 #ifndef TRACE_GROUP
00168 #ifdef YOTTA_CFG_MBED_TRACE_GROUP
00169 #define TRACE_GROUP_STR_HELPER(x) #x
00170 #define TRACE_GROUP_STR(x) TRACE_GROUP_STR_HELPER(x)
00171 #define TRACE_GROUP TRACE_GROUP_STR(YOTTA_CFG_MBED_TRACE_GROUP)
00172 #endif
00173 #endif
00174 
00175 /**
00176  * Initialize trace functionality
00177  * @return 0 when all success, otherwise non zero
00178  */
00179 int mbed_trace_init(void);
00180 /**
00181  * Free trace memory
00182  */
00183 void mbed_trace_free(void);
00184 /**
00185  * Resize buffers (line / tmp ) sizes
00186  * @param lineLength    new maximum length for trace line (0 = do no resize)
00187  * @param tmpLength     new maximum length for trace tmp buffer (used for trace_array, etc) (0 = do no resize)
00188  */
00189 void mbed_trace_buffer_sizes(int lineLength, int tmpLength);
00190 /**
00191  *  Set trace configurations
00192  *  Possible parameters:
00193  *
00194  *   TRACE_MODE_COLOR
00195  *   TRACE_MODE_PLAIN (this exclude color mode)
00196  *   TRACE_CARRIAGE_RETURN (print CR before trace line)
00197  *
00198  *   TRACE_ACTIVE_LEVEL_ALL - to activate all trace levels
00199  *   or TRACE_ACTIVE_LEVEL_DEBUG (alternative)
00200  *   TRACE_ACTIVE_LEVEL_INFO
00201  *   TRACE_ACTIVE_LEVEL_WARN
00202  *   TRACE_ACTIVE_LEVEL_ERROR
00203  *   TRACE_ACTIVE_LEVEL_CMD
00204  *   TRACE_LEVEL_NONE - to deactivate all traces
00205  *
00206  * @param config  Byte size Bit-mask. Bits are descripted above.
00207  * usage e.g.
00208  * @code
00209  *  mbed_trace_config_set( TRACE_ACTIVE_LEVEL_ALL|TRACE_MODE_COLOR );
00210  * @endcode
00211  */
00212 void mbed_trace_config_set(uint8_t config);
00213 /** get trace configurations
00214  * @return trace configuration byte
00215  */
00216 uint8_t mbed_trace_config_get(void);
00217 /**
00218  * Set trace prefix function
00219  * pref_f -function return string with null terminated
00220  * Can be used for e.g. time string
00221  * e.g.
00222  *   char* trace_time(){ return "rtc-time-in-string"; }
00223  *   mbed_trace_prefix_function_set( &trace_time );
00224  */
00225 void mbed_trace_prefix_function_set(char *(*pref_f)(size_t));
00226 /**
00227  * Set trace suffix function
00228  * suffix -function return string with null terminated
00229  * Can be used for e.g. time string
00230  * e.g.
00231  *   char* trace_suffix(){ return " END"; }
00232  *   mbed_trace_suffix_function_set( &trace_suffix );
00233  */
00234 void mbed_trace_suffix_function_set(char *(*suffix_f)(void));
00235 /**
00236  * Set trace print function
00237  * By default, trace module print using printf() function,
00238  * but with this you can write own print function,
00239  * for e.g. to other IO device.
00240  */
00241 void mbed_trace_print_function_set(void (*print_f)(const char *));
00242 /**
00243  * Set trace print function for tr_cmdline()
00244  */
00245 void mbed_trace_cmdprint_function_set(void (*printf)(const char *));
00246 /**
00247  * Set trace mutex wait function
00248  * By default, trace calls are not thread safe.
00249  * If thread safety is required this can be used to set a callback function that will be called before each trace call.
00250  * The specific implementation is up to the application developer, but the mutex must count so it can
00251  * be acquired from a single thread repeatedly.
00252  */
00253 void mbed_trace_mutex_wait_function_set(void (*mutex_wait_f)(void));
00254 /**
00255  * Set trace mutex release function
00256  * By default, trace calls are not thread safe.
00257  * If thread safety is required this can be used to set a callback function that will be called before returning from
00258  * each trace call. The specific implementation is up to the application developer, but the mutex must count so it can
00259  * be acquired from a single thread repeatedly.
00260  */
00261 void mbed_trace_mutex_release_function_set(void (*mutex_release_f)(void));
00262 /**
00263  * When trace group contains text in filters,
00264  * trace print will be ignored.
00265  * e.g.:
00266  *  mbed_trace_exclude_filters_set("mygr");
00267  *  mbed_tracef(TRACE_ACTIVE_LEVEL_DEBUG, "ougr", "This is not printed");
00268  */
00269 void mbed_trace_exclude_filters_set(char *filters);
00270 /** get trace exclude filters
00271  */
00272 const char *mbed_trace_exclude_filters_get(void);
00273 /**
00274  * When trace group contains text in filter,
00275  * trace will be printed.
00276  * e.g.:
00277  *  set_trace_include_filters("mygr");
00278  *  mbed_tracef(TRACE_ACTIVE_LEVEL_DEBUG, "mygr", "Hi There");
00279  *  mbed_tracef(TRACE_ACTIVE_LEVEL_DEBUG, "grp2", "This is not printed");
00280  */
00281 void mbed_trace_include_filters_set(char *filters);
00282 /** get trace include filters
00283  */
00284 const char *mbed_trace_include_filters_get(void);
00285 /**
00286  * General trace function
00287  * This should be used every time when user want to print out something important thing
00288  * Usage e.g.
00289  *   mbed_tracef( TRACE_LEVEL_INFO, "mygr", "Hello world!");
00290  *
00291  * @param dlevel debug level
00292  * @param grp    trace group
00293  * @param fmt    trace format (like printf)
00294  * @param ...    variable arguments related to fmt
00295  */
00296 #if defined(__GNUC__) || defined(__CC_ARM)
00297 void mbed_tracef(uint8_t dlevel, const char *grp, const char *fmt, ...) __attribute__((__format__(__printf__, 3, 4)));
00298 #else
00299 void mbed_tracef(uint8_t dlevel, const char *grp, const char *fmt, ...);
00300 #endif
00301 /**
00302  * General trace function
00303  * This should be used every time when user want to print out something important thing
00304  * and vprintf functionality is desired
00305  * Usage e.g.
00306  *   va_list ap;
00307  *   va_start (ap, fmt);
00308  *   mbed_vtracef( TRACE_LEVEL_INFO, "mygr", fmt, ap );
00309  *   va_end (ap);
00310  *
00311  * @param dlevel debug level
00312  * @param grp    trace group
00313  * @param fmt    trace format (like vprintf)
00314  * @param ap     variable arguments list (like vprintf)
00315  */
00316 #if defined(__GNUC__) || defined(__CC_ARM)
00317 void mbed_vtracef(uint8_t dlevel, const char *grp, const char *fmt, va_list ap) __attribute__((__format__(__printf__, 3, 0)));
00318 #else
00319 void mbed_vtracef(uint8_t dlevel, const char *grp, const char *fmt, va_list ap);
00320 #endif
00321 
00322 
00323 /**
00324  *  Get last trace from buffer
00325  */
00326 const char *mbed_trace_last(void);
00327 #if MBED_CONF_MBED_TRACE_FEA_IPV6 == 1
00328 /**
00329  * mbed_tracef helping function for convert ipv6
00330  * table to human readable string.
00331  * usage e.g.
00332  * char ipv6[16] = {...}; // ! array length is 16 bytes !
00333  * mbed_tracef(TRACE_LEVEL_INFO, "mygr", "ipv6 addr: %s", mbed_trace_ipv6(ipv6));
00334  *
00335  * @param add_ptr  IPv6 Address pointer
00336  * @return temporary buffer where ipv6 is in string format
00337  */
00338 char *mbed_trace_ipv6(const void *addr_ptr);
00339 /**
00340  * mbed_tracef helping function for print ipv6 prefix
00341  * usage e.g.
00342  * char ipv6[16] = {...}; // ! array length is 16 bytes !
00343  * mbed_tracef(TRACE_LEVEL_INFO, "mygr", "ipv6 addr: %s", mbed_trace_ipv6_prefix(ipv6, 4));
00344  *
00345  * @param prefix        IPv6 Address pointer
00346  * @param prefix_len    prefix length
00347  * @return temporary buffer where ipv6 is in string format
00348  */
00349 char *mbed_trace_ipv6_prefix(const uint8_t *prefix, uint8_t prefix_len);
00350 #endif
00351 /**
00352  * mbed_tracef helping function for convert hex-array to string.
00353  * usage e.g.
00354  *  char myarr[] = {0x10, 0x20};
00355  *  mbed_tracef(TRACE_LEVEL_INFO, "mygr", "arr: %s", mbed_trace_array(myarr, 2));
00356  *
00357  * @param buf  hex array pointer
00358  * @param len  buffer length
00359  * @return temporary buffer where string copied
00360  * if array as string not fit to temp buffer, this function write '*' as last character,
00361  * which indicate that buffer is too small for array.
00362  */
00363 char *mbed_trace_array(const uint8_t *buf, uint16_t len);
00364 
00365 #ifdef __cplusplus
00366 }
00367 #endif
00368 
00369 #endif /* MBED_TRACE_H_ */
00370 
00371 /* These macros are outside the inclusion guard so they will be re-evaluated for every inclusion of the header.
00372  * If tracing is disabled, the dummies will hide the real functions. The real functions can still be reached by
00373  * surrounding the name of the function with brackets, e.g. "(mbed_tracef)(dlevel, grp, "like so");"
00374  * */
00375 #if defined(FEA_TRACE_SUPPORT) || MBED_CONF_MBED_TRACE_ENABLE || YOTTA_CFG_MBED_TRACE || (defined(YOTTA_CFG) && !defined(NDEBUG))
00376 // Make sure FEA_TRACE_SUPPORT is always set whenever traces are enabled.
00377 #ifndef FEA_TRACE_SUPPORT
00378 #define FEA_TRACE_SUPPORT
00379 #endif
00380 // undefine dummies, revealing the real functions
00381 #undef MBED_TRACE_DUMMIES_DEFINED
00382 #undef mbed_trace_init
00383 #undef mbed_trace_free
00384 #undef mbed_trace_buffer_sizes
00385 #undef mbed_trace_config_set
00386 #undef mbed_trace_config_get
00387 #undef mbed_trace_prefix_function_set
00388 #undef mbed_trace_suffix_function_set
00389 #undef mbed_trace_print_function_set
00390 #undef mbed_trace_cmdprint_function_set
00391 #undef mbed_trace_mutex_wait_function_set
00392 #undef mbed_trace_mutex_release_function_set
00393 #undef mbed_trace_exclude_filters_set
00394 #undef mbed_trace_exclude_filters_get
00395 #undef mbed_trace_include_filters_set
00396 #undef mbed_trace_include_filters_get
00397 #undef mbed_tracef
00398 #undef mbed_vtracef
00399 #undef mbed_trace_last
00400 #undef mbed_trace_ipv6
00401 #undef mbed_trace_ipv6_prefix
00402 #undef mbed_trace_array
00403 
00404 #elif !defined(MBED_TRACE_DUMMIES_DEFINED)
00405 // define dummies, hiding the real functions
00406 #define MBED_TRACE_DUMMIES_DEFINED
00407 #define mbed_trace_init(...)                        ((int) 0)
00408 #define mbed_trace_free(...)                        ((void) 0)
00409 #define mbed_trace_buffer_sizes(...)                ((void) 0)
00410 #define mbed_trace_config_set(...)                  ((void) 0)
00411 #define mbed_trace_config_get(...)                  ((uint8_t) 0)
00412 #define mbed_trace_prefix_function_set(...)         ((void) 0)
00413 #define mbed_trace_suffix_function_set(...)         ((void) 0)
00414 #define mbed_trace_print_function_set(...)          ((void) 0)
00415 #define mbed_trace_cmdprint_function_set(...)       ((void) 0)
00416 #define mbed_trace_mutex_wait_function_set(...)     ((void) 0)
00417 #define mbed_trace_mutex_release_function_set(...)  ((void) 0)
00418 #define mbed_trace_exclude_filters_set(...)         ((void) 0)
00419 #define mbed_trace_exclude_filters_get(...)         ((const char *) 0)
00420 #define mbed_trace_include_filters_set(...)         ((void) 0)
00421 #define mbed_trace_include_filters_get(...)         ((const char *) 0)
00422 #define mbed_trace_last(...)                        ((const char *) 0)
00423 #define mbed_tracef(...)                            ((void) 0)
00424 #define mbed_vtracef(...)                           ((void) 0)
00425 /**
00426  * These helper functions accumulate strings in a buffer that is only flushed by actual trace calls. Using these
00427  * functions outside trace calls could cause the buffer to overflow.
00428  */
00429 #define mbed_trace_ipv6(...)                dont_use_trace_helpers_outside_trace_calls
00430 #define mbed_trace_ipv6_prefix(...)         dont_use_trace_helpers_outside_trace_calls
00431 #define mbed_trace_array(...)               dont_use_trace_helpers_outside_trace_calls
00432 
00433 #endif /* FEA_TRACE_SUPPORT */