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