Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
mbed_trace.h
Go to the documentation of this file.
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 */
Generated on Tue Jul 12 2022 19:01:35 by 1.7.2