ns_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 ns_trace.h
00019  * Trace interface for NanoStack library as well as application.
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 "ns_trace.h"
00028  *      #define TRACE_GROUP  "main"
00029  *
00030  *      int main(void){
00031  *          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  *
00040  */
00041 #ifndef NS_TRACE_H_
00042 #define NS_TRACE_H_
00043 #include "ns_types.h"
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif
00048 
00049 #define NS_TRACE_USE_MBED_TRACE
00050 #if defined(NS_TRACE_USE_MBED_TRACE)
00051 
00052 #if defined(HAVE_DEBUG) && !defined(FEA_TRACE_SUPPORT)
00053 #define FEA_TRACE_SUPPORT
00054 #endif
00055 
00056 #include "mbed-trace/mbed_trace.h"
00057 
00058 
00059 /* Convert libTrace calls to mbed-trace calls */
00060 #define trace_init()                        mbed_trace_init()
00061 #define trace_free()                        mbed_trace_free()
00062 #define set_trace_config(config)            mbed_trace_config_set(config)
00063 #define get_trace_config()                  mbed_trace_config_get()
00064 #define set_trace_prefix_function(pref_f)   mbed_trace_prefix_function_set(pref_f)
00065 #define set_trace_suffix_function(suffix_f) mbed_trace_suffix_function_set(suffix_f)
00066 #define set_trace_print_function(print_f)   mbed_trace_print_function_set(print_f)
00067 #define set_trace_cmdprint_function(printf) mbed_trace_cmdprint_function_set(printf)
00068 #define set_trace_exclude_filters(filters)  mbed_trace_exclude_filters_set(filters)
00069 #define set_trace_include_filters(filters)  mbed_trace_include_filters_set(filters)
00070 #define get_trace_exclude_filters()         mbed_trace_exclude_filters_get()
00071 #define get_trace_include_filters()         mbed_trace_include_filters_get()
00072 #define trace_last()                        mbed_trace_last()
00073 
00074 
00075 /* Definitions for the old functions with no equivalents in mbed-trace. These work without any special init.
00076  * */
00077 #if defined(FEA_TRACE_SUPPORT) || defined(HAVE_DEBUG) || (defined(YOTTA_CFG) && !defined(NDEBUG)) /*backward compatible*/
00078 #if defined  __GNUC__ || defined __CC_ARM
00079 /** obsolete function */
00080 void debugf(const char *fmt, ...) __attribute__ ((__format__(__printf__, 1, 2)));   //!< obsolete function
00081 void debug(const char *s);                                                          //!< obsolete function
00082 void debug_put(char c);                                                             //!< obsolete function
00083 void debug_hex(uint8_t x);                                                          //!< obsolete function
00084 void debug_int(int i);                                                              //!< obsolete function
00085 void printf_array(const void *buf, uint16_t len);                                   //!< obsolete function
00086 void printf_string(const void *buf, uint16_t len);                                  //!< obsolete function
00087 void printf_ipv6_address(const void *addr);                                         //!< obsolete function
00088 #else //__GNUC__ || __CC_ARM
00089 //obsolete functions:
00090 void debugf(const char *fmt, ...);
00091 void debug(const char *s);
00092 void debug_put(char c);
00093 void debug_hex(uint8_t x);
00094 void debug_int(int i);
00095 void printf_array(const void *buf, uint16_t len);
00096 void printf_string(const void *buf, uint16_t len);
00097 void printf_ipv6_address(const void *addr);
00098 #endif
00099 #else /*FEA_TRACE_SUPPORT*/
00100 // trace functionality not supported
00101 //obsolete
00102 #define debugf(...)                    ((void) 0)
00103 #define debug(s)                       ((void) 0)
00104 #define debug_put(c)                   ((void) 0)
00105 #define debug_hex(x)                   ((void) 0)
00106 #define debug_int(i)                   ((void) 0)
00107 #define printf_array(buf, len)         ((void) 0)
00108 #define printf_string(buf, len)        ((void) 0)
00109 #define printf_ipv6_address(addr)      ((void) 0)
00110 
00111 #endif /*FEA_TRACE_SUPPORT*/
00112 
00113 #else /* NS_TRACE_USE_MBED_TRACE */
00114 
00115 /** 3 upper bits are trace modes related,
00116     and 5 lower bits are trace level configuration */
00117 
00118 /** Config mask */
00119 #define TRACE_MASK_CONFIG         0xE0
00120 /** Trace level mask */
00121 #define TRACE_MASK_LEVEL          0x1F
00122 
00123 /** plain trace data instead of "headers" */
00124 #define TRACE_MODE_PLAIN          0x80
00125 /** color mode */
00126 #define TRACE_MODE_COLOR          0x40
00127 /** Use print CR before trace line */
00128 #define TRACE_CARRIAGE_RETURN     0x20
00129 
00130 /** used to activate all trace levels */
00131 #define TRACE_ACTIVE_LEVEL_ALL    0x1F
00132 /** print all traces same as above */
00133 #define TRACE_ACTIVE_LEVEL_DEBUG  0x1f
00134 /** print info,warn and error traces */
00135 #define TRACE_ACTIVE_LEVEL_INFO   0x0f
00136 /** print warn and error traces */
00137 #define TRACE_ACTIVE_LEVEL_WARN   0x07
00138 /** print only error trace */
00139 #define TRACE_ACTIVE_LEVEL_ERROR  0x03
00140 /** print only cmd line data */
00141 #define TRACE_ACTIVE_LEVEL_CMD    0x01
00142 /** trace nothing  */
00143 #define TRACE_ACTIVE_LEVEL_NONE   0x00
00144 
00145 /** this print is some deep information for debug purpose */
00146 #define TRACE_LEVEL_DEBUG         0x10
00147 /** Info print, for general purpose prints */
00148 #define TRACE_LEVEL_INFO          0x08
00149 /** warning prints, which shouldn't causes any huge problems */
00150 #define TRACE_LEVEL_WARN          0x04
00151 /** Error prints, which causes probably problems, e.g. out of mem. */
00152 #define TRACE_LEVEL_ERROR         0x02
00153 /** special level for cmdline. Behaviours like "plain mode" */
00154 #define TRACE_LEVEL_CMD           0x01
00155 
00156 //usage macros:
00157 #define tr_info(...)            tracef(TRACE_LEVEL_INFO,    TRACE_GROUP, __VA_ARGS__)   //!< Print info message
00158 #define tr_debug(...)           tracef(TRACE_LEVEL_DEBUG,   TRACE_GROUP, __VA_ARGS__)   //!< Print debug message
00159 #define tr_warning(...)         tracef(TRACE_LEVEL_WARN,    TRACE_GROUP, __VA_ARGS__)   //!< Print warning message
00160 #define tr_warn(...)            tracef(TRACE_LEVEL_WARN,    TRACE_GROUP, __VA_ARGS__)   //!< Alternative warning message
00161 #define tr_error(...)           tracef(TRACE_LEVEL_ERROR,   TRACE_GROUP, __VA_ARGS__)   //!< Print Error Message
00162 #define tr_err(...)             tracef(TRACE_LEVEL_ERROR,   TRACE_GROUP, __VA_ARGS__)   //!< Alternative error message
00163 #define tr_cmdline(...)         tracef(TRACE_LEVEL_CMD,     TRACE_GROUP, __VA_ARGS__)   //!< Special print for cmdline. See more from TRACE_LEVEL_CMD -level
00164 
00165 /** Possible to skip all traces in compile time */
00166 #if defined(FEA_TRACE_SUPPORT) || defined(HAVE_DEBUG) || (defined(YOTTA_CFG) && !defined(NDEBUG)) /*backward compatible*/
00167 
00168 #if defined  __GNUC__ || defined __CC_ARM
00169 /**
00170  * Initialize trace functionality. This method must be called from application process.
00171  * @return 0 when all success, otherwise non zero
00172  */
00173 int trace_init( void );
00174 /**
00175  * Free trace memory. This method must be called from application process.
00176  */
00177 void trace_free( void );
00178 /**
00179  *  Set trace configurations
00180  *  Possible parameters:
00181  *
00182  *   TRACE_MODE_COLOR
00183  *   TRACE_MODE_PLAIN (this exclude color mode)
00184  *   TRACE_CARRIAGE_RETURN (print CR before trace line)
00185  *
00186  *   TRACE_ACTIVE_LEVEL_ALL - to activate all trace levels
00187  *   or TRACE_ACTIVE_LEVEL_DEBUG (alternative)
00188  *   TRACE_ACTIVE_LEVEL_INFO
00189  *   TRACE_ACTIVE_LEVEL_WARN
00190  *   TRACE_ACTIVE_LEVEL_ERROR
00191  *   TRACE_ACTIVE_LEVEL_CMD
00192  *   TRACE_LEVEL_NONE - to deactivate all traces
00193  *
00194  * @param config  Byte size Bit-mask. Bits are descripted above.
00195  * usage e.g.
00196  * @code
00197  *  set_trace_config( TRACE_ACTIVE_LEVEL_ALL|TRACE_MODE_COLOR );
00198  * @endcode
00199  */
00200 void set_trace_config(uint8_t config);
00201 /** get trace configurations 
00202  * @return trace configuration byte
00203  */
00204 uint8_t get_trace_config(void);
00205 /**
00206  * Set trace prefix function
00207  * pref_f -function return string with null terminated
00208  * Can be used for e.g. time string
00209  * e.g.
00210  *   char* trace_time(){ return "rtc-time-in-string"; }
00211  *   set_trace_prefix_function( &trace_time );
00212  */
00213 void set_trace_prefix_function( char* (*pref_f)(size_t) );
00214 /**
00215  * Set trace suffix function
00216  * suffix -function return string with null terminated
00217  * Can be used for e.g. time string
00218  * e.g.
00219  *   char* trace_suffix(){ return " END"; }
00220  *   set_trace_suffix_function( &trace_suffix );
00221  */
00222 void set_trace_suffix_function(char* (*suffix_f)(void) );
00223 /**
00224  * Set trace print function
00225  * By default, trace module print using printf() function,
00226  * but with this you can write own print function,
00227  * for e.g. to other IO device.
00228  */
00229 void set_trace_print_function( void (*print_f)(const char*) );
00230 /**
00231  * Set trace print function for tr_cmdline()
00232  */
00233 void set_trace_cmdprint_function( void (*printf)(const char*) );
00234 /**
00235  * When trace group contains text in filters,
00236  * trace print will be ignored.
00237  * e.g.: 
00238  *  set_trace_exclude_filters("mygr");
00239  *  tracef(TRACE_ACTIVE_LEVEL_DEBUG, "ougr", "This is not printed");
00240  */
00241 void set_trace_exclude_filters(char* filters);
00242 /** get trace exclude filters
00243  */
00244 const char* get_trace_exclude_filters(void);
00245 /**
00246  * When trace group contains text in filter,
00247  * trace will be printed.
00248  * e.g.:
00249  *  set_trace_include_filters("mygr");
00250  *  tracef(TRACE_ACTIVE_LEVEL_DEBUG, "mygr", "Hi There");
00251  *  tracef(TRACE_ACTIVE_LEVEL_DEBUG, "grp2", "This is not printed");
00252  */
00253 void set_trace_include_filters(char* filters);
00254 /** get trace include filters
00255  */
00256 const char* get_trace_include_filters(void);
00257 /**
00258  * General trace function
00259  * This should be used every time when user want to print out something important thing
00260  * Usage e.g.
00261  *   tracef( TRACE_LEVEL_INFO, "mygr", "Hello world!");
00262  *
00263  * @param dlevel debug level
00264  * @param grp    trace group
00265  * @param fmt    trace format (like printf)
00266  * @param ...    variable arguments related to fmt
00267  */
00268 void tracef(uint8_t dlevel, const char* grp, const char *fmt, ...) __attribute__ ((__format__(__printf__, 3, 4)));
00269 /**
00270  *  Get last trace from buffer
00271  */
00272 const char* trace_last(void);
00273 /**
00274  * tracef helping function for convert ipv6
00275  * table to human readable string.
00276  * usage e.g.
00277  * char ipv6[16] = {...}; // ! array length is 16 bytes !
00278  * tracef(TRACE_LEVEL_INFO, "mygr", "ipv6 addr: %s", trace_ipv6(ipv6));
00279  *
00280  * @param add_ptr  IPv6 Address pointer
00281  * @return temporary buffer where ipv6 is in string format
00282  */
00283 char* trace_ipv6(const void *addr_ptr);
00284 /**
00285  * tracef helping function for print ipv6 prefix
00286  * usage e.g.
00287  * char ipv6[16] = {...}; // ! array length is 16 bytes !
00288  * tracef(TRACE_LEVEL_INFO, "mygr", "ipv6 addr: %s", trace_ipv6_prefix(ipv6, 4));
00289  *
00290  * @param prefix        IPv6 Address pointer
00291  * @param prefix_len    prefix length
00292  * @return temporary buffer where ipv6 is in string format
00293  */
00294 char* trace_ipv6_prefix(const uint8_t *prefix, uint8_t prefix_len);
00295 /**
00296  * tracef helping function for convert hex-array to string.
00297  * usage e.g.
00298  *  char myarr[] = {0x10, 0x20};
00299  *  tracef(TRACE_LEVEL_INFO, "mygr", "arr: %s", trace_array(myarr, 2));
00300  *
00301  * @param buf  hex array pointer
00302  * @param len  buffer length
00303  * @return temporary buffer where string copied
00304  */
00305 char* trace_array(const uint8_t* buf, uint16_t len);
00306 
00307 
00308 /*
00309  * obsolete - only because of backward compatible reason
00310  * As soon as all these functions are replaced by new tracef() function, these can be removed.
00311  */
00312 
00313 /** obsolete function */
00314 void debugf(const char *fmt, ...) __attribute__ ((__format__(__printf__, 1, 2)));   //!< obsolete function
00315 void debug(const char *s);                                                          //!< obsolete function
00316 void debug_put(char c);                                                             //!< obsolete function
00317 void debug_hex(uint8_t x);                                                          //!< obsolete function
00318 void debug_int(int i);                                                              //!< obsolete function
00319 void printf_array(const void *buf, uint16_t len);                                   //!< obsolete function
00320 void printf_string(const void *buf, uint16_t len);                                  //!< obsolete function
00321 void printf_ipv6_address(const void *addr);                                         //!< obsolete function
00322 
00323 #else //__GNUC__ || __CC_ARM
00324 int trace_init( void );
00325 void trace_free( void );
00326 void set_trace_config(uint8_t config);
00327 void set_trace_prefix_function( char* (*pref_f)(size_t) );
00328 void set_trace_print_function( void (*print_f)(const char*) );
00329 void set_trace_cmdprint_function( void (*printf)(const char*) );
00330 void set_trace_exclude_filters(char* filters);
00331 const char* get_trace_exclude_filters(void);
00332 void set_trace_include_filters(char* filters);
00333 const char* get_trace_include_filters(void);
00334 void tracef(uint8_t dlevel, const char* grp, const char *fmt, ...);
00335 char* trace_ipv6(const void *addr_ptr);
00336 char* trace_array(const uint8_t* buf, uint16_t len);
00337 char* trace_ipv6_prefix(const uint8_t *prefix, uint8_t prefix_len);
00338 
00339 //obsolete functions:
00340 void debugf(const char *fmt, ...);
00341 void debug(const char *s);
00342 void debug_put(char c);
00343 void debug_hex(uint8_t x);
00344 void debug_int(int i);
00345 void printf_array(const void *buf, uint16_t len);
00346 void printf_string(const void *buf, uint16_t len);
00347 void printf_ipv6_address(const void *addr);
00348 
00349 #endif
00350 
00351 
00352 #else /*FEA_TRACE_SUPPORT*/
00353 
00354 // trace functionality not supported
00355 #define trace_init(...)                ((int) 0)
00356 #define trace_free(...)                ((void) 0)
00357 #define set_trace_config(...)          ((void) 0)
00358 #define set_trace_prefix_function(...) ((void) 0)
00359 #define set_trace_print_function(...)  ((void) 0)
00360 #define set_trace_cmdprint_function(...)  ((void) 0)
00361 #define set_trace_exclude_filters(...) ((void) 0)
00362 #define set_trace_include_filters(...) ((void) 0)
00363 #define get_trace_exclude_filters(...) ((const char*) 0)
00364 #define get_trace_include_filters(...) ((const char*) 0)
00365 
00366 #define tracef(...)                    ((void) 0)
00367 #define trace_ipv6(...)                ((char*) 0)
00368 #define trace_array(...)               ((char*) 0)
00369 #define trace_ipv6_prefix(...)         ((char*) 0)
00370 
00371 //obsolete
00372 #define debugf(...)                    ((void) 0)
00373 #define debug(s)                       ((void) 0)
00374 #define debug_put(c)                   ((void) 0)
00375 #define debug_hex(x)                   ((void) 0)
00376 #define debug_int(i)                   ((void) 0)
00377 #define printf_array(buf, len)         ((void) 0)
00378 #define printf_string(buf, len)        ((void) 0)
00379 #define printf_ipv6_address(addr)      ((void) 0)
00380 
00381 #endif /*FEA_TRACE_SUPPORT*/
00382 #endif /* NS_TRACE_USE_MBED_TRACE */
00383 
00384 #ifdef __cplusplus
00385 }
00386 #endif
00387 #endif /* NS_TRACE_H_ */