Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of OmniWheels by
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 */
Generated on Fri Jul 22 2022 04:53:56 by
