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