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