BA / SerialCom

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 Gustav Atmel

mbed-os/features/FEATURE_COMMON_PAL/mbed-trace/mbed-trace/mbed_trace.h@2:798925c9e4a8, 2018-05-01 (annotated)

Committer:
gustavatmel
Date:
Tue May 01 15:55:34 2018 +0000
Revision:
2:798925c9e4a8
Parent:
1:9c5af431a1f1 
bluetooth

Who changed what in which revision?

UserRevisionLine numberNew contents of line
gustavatmel 1:9c5af431a1f1 1 /*
gustavatmel 1:9c5af431a1f1 2 * Copyright (c) 2015 ARM Limited. All rights reserved.
gustavatmel 1:9c5af431a1f1 3 * SPDX-License-Identifier: Apache-2.0
gustavatmel 1:9c5af431a1f1 4 * Licensed under the Apache License, Version 2.0 (the License); you may
gustavatmel 1:9c5af431a1f1 5 * not use this file except in compliance with the License.
gustavatmel 1:9c5af431a1f1 6 * You may obtain a copy of the License at
gustavatmel 1:9c5af431a1f1 7 *
gustavatmel 1:9c5af431a1f1 8 * http://www.apache.org/licenses/LICENSE-2.0
gustavatmel 1:9c5af431a1f1 9 *
gustavatmel 1:9c5af431a1f1 10 * Unless required by applicable law or agreed to in writing, software
gustavatmel 1:9c5af431a1f1 11 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
gustavatmel 1:9c5af431a1f1 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
gustavatmel 1:9c5af431a1f1 13 * See the License for the specific language governing permissions and
gustavatmel 1:9c5af431a1f1 14 * limitations under the License.
gustavatmel 1:9c5af431a1f1 15 */
gustavatmel 1:9c5af431a1f1 16
gustavatmel 1:9c5af431a1f1 17 /**
gustavatmel 1:9c5af431a1f1 18 * \file mbed_trace.h
gustavatmel 1:9c5af431a1f1 19 * Trace interface for MbedOS applications.
gustavatmel 1:9c5af431a1f1 20 * This file provide simple but flexible way to handle software traces.
gustavatmel 1:9c5af431a1f1 21 * Trace library are abstract layer, which use stdout (printf) by default,
gustavatmel 1:9c5af431a1f1 22 * but outputs can be easily redirect to custom function, for example to
gustavatmel 1:9c5af431a1f1 23 * store traces to memory or other interfaces.
gustavatmel 1:9c5af431a1f1 24 *
gustavatmel 1:9c5af431a1f1 25 * usage example:
gustavatmel 1:9c5af431a1f1 26 * \code(main.c:)
gustavatmel 1:9c5af431a1f1 27 * #include "mbed_trace.h"
gustavatmel 1:9c5af431a1f1 28 * #define TRACE_GROUP "main"
gustavatmel 1:9c5af431a1f1 29 *
gustavatmel 1:9c5af431a1f1 30 * int main(void){
gustavatmel 1:9c5af431a1f1 31 * mbed_trace_init(); // initialize trace library
gustavatmel 1:9c5af431a1f1 32 * tr_debug("this is debug msg"); //print debug message to stdout: "[DBG]
gustavatmel 1:9c5af431a1f1 33 * tr_info("this is info msg");
gustavatmel 1:9c5af431a1f1 34 * tr_warn("this is warning msg");
gustavatmel 1:9c5af431a1f1 35 * tr_err("this is error msg");
gustavatmel 1:9c5af431a1f1 36 * return 0;
gustavatmel 1:9c5af431a1f1 37 * }
gustavatmel 1:9c5af431a1f1 38 * \endcode
gustavatmel 1:9c5af431a1f1 39 * Activate with compiler flag: YOTTA_CFG_MBED_TRACE
gustavatmel 1:9c5af431a1f1 40 * Configure trace line buffer size with compiler flag: YOTTA_CFG_MBED_TRACE_LINE_LENGTH. Default length: 1024.
gustavatmel 1:9c5af431a1f1 41 * Limit the size of flash by setting MBED_TRACE_MAX_LEVEL value. Default is TRACE_LEVEL_DEBUG (all included)
gustavatmel 1:9c5af431a1f1 42 *
gustavatmel 1:9c5af431a1f1 43 */
gustavatmel 1:9c5af431a1f1 44 #ifndef MBED_TRACE_H_
gustavatmel 1:9c5af431a1f1 45 #define MBED_TRACE_H_
gustavatmel 1:9c5af431a1f1 46
gustavatmel 1:9c5af431a1f1 47 #ifdef __cplusplus
gustavatmel 1:9c5af431a1f1 48 extern "C" {
gustavatmel 1:9c5af431a1f1 49 #endif
gustavatmel 1:9c5af431a1f1 50
gustavatmel 1:9c5af431a1f1 51 #ifdef YOTTA_CFG
gustavatmel 1:9c5af431a1f1 52 #include <stdint.h>
gustavatmel 1:9c5af431a1f1 53 #include <stddef.h>
gustavatmel 1:9c5af431a1f1 54 #include <stdbool.h>
gustavatmel 1:9c5af431a1f1 55 #else
gustavatmel 1:9c5af431a1f1 56 #include "ns_types.h"
gustavatmel 1:9c5af431a1f1 57 #endif
gustavatmel 1:9c5af431a1f1 58
gustavatmel 1:9c5af431a1f1 59 #include <stdarg.h>
gustavatmel 1:9c5af431a1f1 60
gustavatmel 1:9c5af431a1f1 61 #ifndef YOTTA_CFG_MBED_TRACE
gustavatmel 1:9c5af431a1f1 62 #define YOTTA_CFG_MBED_TRACE 0
gustavatmel 1:9c5af431a1f1 63 #endif
gustavatmel 1:9c5af431a1f1 64
gustavatmel 1:9c5af431a1f1 65 #ifndef YOTTA_CFG_MBED_TRACE_FEA_IPV6
gustavatmel 1:9c5af431a1f1 66 #define YOTTA_CFG_MBED_TRACE_FEA_IPV6 1
gustavatmel 1:9c5af431a1f1 67 #else
gustavatmel 1:9c5af431a1f1 68 #warning YOTTA_CFG_MBED_TRACE_FEA_IPV6 is deprecated and will be removed in the future! Use MBED_CONF_MBED_TRACE_FEA_IPV6 instead.
gustavatmel 1:9c5af431a1f1 69 #define MBED_CONF_MBED_TRACE_FEA_IPV6 YOTTA_CFG_MBED_TRACE_FEA_IPV6
gustavatmel 1:9c5af431a1f1 70 #endif
gustavatmel 1:9c5af431a1f1 71
gustavatmel 1:9c5af431a1f1 72 #ifndef MBED_CONF_MBED_TRACE_ENABLE
gustavatmel 1:9c5af431a1f1 73 #define MBED_CONF_MBED_TRACE_ENABLE 0
gustavatmel 1:9c5af431a1f1 74 #endif
gustavatmel 1:9c5af431a1f1 75
gustavatmel 1:9c5af431a1f1 76 #ifndef MBED_CONF_MBED_TRACE_FEA_IPV6
gustavatmel 1:9c5af431a1f1 77 #define MBED_CONF_MBED_TRACE_FEA_IPV6 1
gustavatmel 1:9c5af431a1f1 78 #endif
gustavatmel 1:9c5af431a1f1 79
gustavatmel 1:9c5af431a1f1 80 /** 3 upper bits are trace modes related,
gustavatmel 1:9c5af431a1f1 81 and 5 lower bits are trace level configuration */
gustavatmel 1:9c5af431a1f1 82
gustavatmel 1:9c5af431a1f1 83 /** Config mask */
gustavatmel 1:9c5af431a1f1 84 #define TRACE_MASK_CONFIG 0xE0
gustavatmel 1:9c5af431a1f1 85 /** Trace level mask */
gustavatmel 1:9c5af431a1f1 86 #define TRACE_MASK_LEVEL 0x1F
gustavatmel 1:9c5af431a1f1 87
gustavatmel 1:9c5af431a1f1 88 /** plain trace data instead of "headers" */
gustavatmel 1:9c5af431a1f1 89 #define TRACE_MODE_PLAIN 0x80
gustavatmel 1:9c5af431a1f1 90 /** color mode */
gustavatmel 1:9c5af431a1f1 91 #define TRACE_MODE_COLOR 0x40
gustavatmel 1:9c5af431a1f1 92 /** Use print CR before trace line */
gustavatmel 1:9c5af431a1f1 93 #define TRACE_CARRIAGE_RETURN 0x20
gustavatmel 1:9c5af431a1f1 94
gustavatmel 1:9c5af431a1f1 95 /** used to activate all trace levels */
gustavatmel 1:9c5af431a1f1 96 #define TRACE_ACTIVE_LEVEL_ALL 0x1F
gustavatmel 1:9c5af431a1f1 97 /** print all traces same as above */
gustavatmel 1:9c5af431a1f1 98 #define TRACE_ACTIVE_LEVEL_DEBUG 0x1f
gustavatmel 1:9c5af431a1f1 99 /** print info,warn and error traces */
gustavatmel 1:9c5af431a1f1 100 #define TRACE_ACTIVE_LEVEL_INFO 0x0f
gustavatmel 1:9c5af431a1f1 101 /** print warn and error traces */
gustavatmel 1:9c5af431a1f1 102 #define TRACE_ACTIVE_LEVEL_WARN 0x07
gustavatmel 1:9c5af431a1f1 103 /** print only error trace */
gustavatmel 1:9c5af431a1f1 104 #define TRACE_ACTIVE_LEVEL_ERROR 0x03
gustavatmel 1:9c5af431a1f1 105 /** print only cmd line data */
gustavatmel 1:9c5af431a1f1 106 #define TRACE_ACTIVE_LEVEL_CMD 0x01
gustavatmel 1:9c5af431a1f1 107 /** trace nothing */
gustavatmel 1:9c5af431a1f1 108 #define TRACE_ACTIVE_LEVEL_NONE 0x00
gustavatmel 1:9c5af431a1f1 109
gustavatmel 1:9c5af431a1f1 110 /** this print is some deep information for debug purpose */
gustavatmel 1:9c5af431a1f1 111 #define TRACE_LEVEL_DEBUG 0x10
gustavatmel 1:9c5af431a1f1 112 /** Info print, for general purpose prints */
gustavatmel 1:9c5af431a1f1 113 #define TRACE_LEVEL_INFO 0x08
gustavatmel 1:9c5af431a1f1 114 /** warning prints, which shouldn't causes any huge problems */
gustavatmel 1:9c5af431a1f1 115 #define TRACE_LEVEL_WARN 0x04
gustavatmel 1:9c5af431a1f1 116 /** Error prints, which causes probably problems, e.g. out of mem. */
gustavatmel 1:9c5af431a1f1 117 #define TRACE_LEVEL_ERROR 0x02
gustavatmel 1:9c5af431a1f1 118 /** special level for cmdline. Behaviours like "plain mode" */
gustavatmel 1:9c5af431a1f1 119 #define TRACE_LEVEL_CMD 0x01
gustavatmel 1:9c5af431a1f1 120
gustavatmel 1:9c5af431a1f1 121 #ifndef MBED_TRACE_MAX_LEVEL
gustavatmel 1:9c5af431a1f1 122 #define MBED_TRACE_MAX_LEVEL TRACE_LEVEL_DEBUG
gustavatmel 1:9c5af431a1f1 123 #endif
gustavatmel 1:9c5af431a1f1 124
gustavatmel 1:9c5af431a1f1 125 //usage macros:
gustavatmel 1:9c5af431a1f1 126 #if MBED_TRACE_MAX_LEVEL >= TRACE_LEVEL_DEBUG
gustavatmel 1:9c5af431a1f1 127 #define tr_debug(...) mbed_tracef(TRACE_LEVEL_DEBUG, TRACE_GROUP, __VA_ARGS__) //!< Print debug message
gustavatmel 1:9c5af431a1f1 128 #else
gustavatmel 1:9c5af431a1f1 129 #define tr_debug(...)
gustavatmel 1:9c5af431a1f1 130 #endif
gustavatmel 1:9c5af431a1f1 131
gustavatmel 1:9c5af431a1f1 132 #if MBED_TRACE_MAX_LEVEL >= TRACE_LEVEL_INFO
gustavatmel 1:9c5af431a1f1 133 #define tr_info(...) mbed_tracef(TRACE_LEVEL_INFO, TRACE_GROUP, __VA_ARGS__) //!< Print info message
gustavatmel 1:9c5af431a1f1 134 #else
gustavatmel 1:9c5af431a1f1 135 #define tr_info(...)
gustavatmel 1:9c5af431a1f1 136 #endif
gustavatmel 1:9c5af431a1f1 137
gustavatmel 1:9c5af431a1f1 138 #if MBED_TRACE_MAX_LEVEL >= TRACE_LEVEL_WARN
gustavatmel 1:9c5af431a1f1 139 #define tr_warning(...) mbed_tracef(TRACE_LEVEL_WARN, TRACE_GROUP, __VA_ARGS__) //!< Print warning message
gustavatmel 1:9c5af431a1f1 140 #define tr_warn(...) mbed_tracef(TRACE_LEVEL_WARN, TRACE_GROUP, __VA_ARGS__) //!< Alternative warning message
gustavatmel 1:9c5af431a1f1 141 #else
gustavatmel 1:9c5af431a1f1 142 #define tr_warning(...)
gustavatmel 1:9c5af431a1f1 143 #define tr_warn(...)
gustavatmel 1:9c5af431a1f1 144 #endif
gustavatmel 1:9c5af431a1f1 145
gustavatmel 1:9c5af431a1f1 146 #if MBED_TRACE_MAX_LEVEL >= TRACE_LEVEL_ERROR
gustavatmel 1:9c5af431a1f1 147 #define tr_error(...) mbed_tracef(TRACE_LEVEL_ERROR, TRACE_GROUP, __VA_ARGS__) //!< Print Error Message
gustavatmel 1:9c5af431a1f1 148 #define tr_err(...) mbed_tracef(TRACE_LEVEL_ERROR, TRACE_GROUP, __VA_ARGS__) //!< Alternative error message
gustavatmel 1:9c5af431a1f1 149 #else
gustavatmel 1:9c5af431a1f1 150 #define tr_error(...)
gustavatmel 1:9c5af431a1f1 151 #define tr_err(...)
gustavatmel 1:9c5af431a1f1 152 #endif
gustavatmel 1:9c5af431a1f1 153
gustavatmel 1:9c5af431a1f1 154 #define tr_cmdline(...) mbed_tracef(TRACE_LEVEL_CMD, TRACE_GROUP, __VA_ARGS__) //!< Special print for cmdline. See more from TRACE_LEVEL_CMD -level
gustavatmel 1:9c5af431a1f1 155
gustavatmel 1:9c5af431a1f1 156 //aliases for the most commonly used functions and the helper functions
gustavatmel 1:9c5af431a1f1 157 #define tracef(dlevel, grp, ...) mbed_tracef(dlevel, grp, __VA_ARGS__) //!< Alias for mbed_tracef()
gustavatmel 1:9c5af431a1f1 158 #define vtracef(dlevel, grp, fmt, ap) mbed_vtracef(dlevel, grp, fmt, ap) //!< Alias for mbed_vtracef()
gustavatmel 1:9c5af431a1f1 159 #define tr_array(buf, len) mbed_trace_array(buf, len) //!< Alias for mbed_trace_array()
gustavatmel 1:9c5af431a1f1 160 #define tr_ipv6(addr_ptr) mbed_trace_ipv6(addr_ptr) //!< Alias for mbed_trace_ipv6()
gustavatmel 1:9c5af431a1f1 161 #define tr_ipv6_prefix(prefix, prefix_len) mbed_trace_ipv6_prefix(prefix, prefix_len) //!< Alias for mbed_trace_ipv6_prefix()
gustavatmel 1:9c5af431a1f1 162 #define trace_array(buf, len) mbed_trace_array(buf, len) //!< Alias for mbed_trace_array()
gustavatmel 1:9c5af431a1f1 163 #define trace_ipv6(addr_ptr) mbed_trace_ipv6(addr_ptr) //!< Alias for mbed_trace_ipv6()
gustavatmel 1:9c5af431a1f1 164 #define trace_ipv6_prefix(prefix, prefix_len) mbed_trace_ipv6_prefix(prefix, prefix_len) //!< Alias for mbed_trace_ipv6_prefix()
gustavatmel 1:9c5af431a1f1 165
gustavatmel 1:9c5af431a1f1 166
gustavatmel 1:9c5af431a1f1 167 /**
gustavatmel 1:9c5af431a1f1 168 * Allow specification of default TRACE_GROUP to be used if not specified by application
gustavatmel 1:9c5af431a1f1 169 */
gustavatmel 1:9c5af431a1f1 170
gustavatmel 1:9c5af431a1f1 171 #ifndef TRACE_GROUP
gustavatmel 1:9c5af431a1f1 172 #ifdef YOTTA_CFG_MBED_TRACE_GROUP
gustavatmel 1:9c5af431a1f1 173 #define TRACE_GROUP_STR_HELPER(x) #x
gustavatmel 1:9c5af431a1f1 174 #define TRACE_GROUP_STR(x) TRACE_GROUP_STR_HELPER(x)
gustavatmel 1:9c5af431a1f1 175 #define TRACE_GROUP TRACE_GROUP_STR(YOTTA_CFG_MBED_TRACE_GROUP)
gustavatmel 1:9c5af431a1f1 176 #endif
gustavatmel 1:9c5af431a1f1 177 #endif
gustavatmel 1:9c5af431a1f1 178
gustavatmel 1:9c5af431a1f1 179 /**
gustavatmel 1:9c5af431a1f1 180 * Initialize trace functionality
gustavatmel 1:9c5af431a1f1 181 * @return 0 when all success, otherwise non zero
gustavatmel 1:9c5af431a1f1 182 */
gustavatmel 1:9c5af431a1f1 183 int mbed_trace_init( void );
gustavatmel 1:9c5af431a1f1 184 /**
gustavatmel 1:9c5af431a1f1 185 * Free trace memory
gustavatmel 1:9c5af431a1f1 186 */
gustavatmel 1:9c5af431a1f1 187 void mbed_trace_free( void );
gustavatmel 1:9c5af431a1f1 188 /**
gustavatmel 1:9c5af431a1f1 189 * Resize buffers (line / tmp ) sizes
gustavatmel 1:9c5af431a1f1 190 * @param lineLength new maximum length for trace line (0 = do no resize)
gustavatmel 1:9c5af431a1f1 191 * @param tmpLength new maximum length for trace tmp buffer (used for trace_array, etc) (0 = do no resize)
gustavatmel 1:9c5af431a1f1 192 */
gustavatmel 1:9c5af431a1f1 193 void mbed_trace_buffer_sizes(int lineLength, int tmpLength);
gustavatmel 1:9c5af431a1f1 194 /**
gustavatmel 1:9c5af431a1f1 195 * Set trace configurations
gustavatmel 1:9c5af431a1f1 196 * Possible parameters:
gustavatmel 1:9c5af431a1f1 197 *
gustavatmel 1:9c5af431a1f1 198 * TRACE_MODE_COLOR
gustavatmel 1:9c5af431a1f1 199 * TRACE_MODE_PLAIN (this exclude color mode)
gustavatmel 1:9c5af431a1f1 200 * TRACE_CARRIAGE_RETURN (print CR before trace line)
gustavatmel 1:9c5af431a1f1 201 *
gustavatmel 1:9c5af431a1f1 202 * TRACE_ACTIVE_LEVEL_ALL - to activate all trace levels
gustavatmel 1:9c5af431a1f1 203 * or TRACE_ACTIVE_LEVEL_DEBUG (alternative)
gustavatmel 1:9c5af431a1f1 204 * TRACE_ACTIVE_LEVEL_INFO
gustavatmel 1:9c5af431a1f1 205 * TRACE_ACTIVE_LEVEL_WARN
gustavatmel 1:9c5af431a1f1 206 * TRACE_ACTIVE_LEVEL_ERROR
gustavatmel 1:9c5af431a1f1 207 * TRACE_ACTIVE_LEVEL_CMD
gustavatmel 1:9c5af431a1f1 208 * TRACE_LEVEL_NONE - to deactivate all traces
gustavatmel 1:9c5af431a1f1 209 *
gustavatmel 1:9c5af431a1f1 210 * @param config Byte size Bit-mask. Bits are descripted above.
gustavatmel 1:9c5af431a1f1 211 * usage e.g.
gustavatmel 1:9c5af431a1f1 212 * @code
gustavatmel 1:9c5af431a1f1 213 * mbed_trace_config_set( TRACE_ACTIVE_LEVEL_ALL|TRACE_MODE_COLOR );
gustavatmel 1:9c5af431a1f1 214 * @endcode
gustavatmel 1:9c5af431a1f1 215 */
gustavatmel 1:9c5af431a1f1 216 void mbed_trace_config_set(uint8_t config);
gustavatmel 1:9c5af431a1f1 217 /** get trace configurations
gustavatmel 1:9c5af431a1f1 218 * @return trace configuration byte
gustavatmel 1:9c5af431a1f1 219 */
gustavatmel 1:9c5af431a1f1 220 uint8_t mbed_trace_config_get(void);
gustavatmel 1:9c5af431a1f1 221 /**
gustavatmel 1:9c5af431a1f1 222 * Set trace prefix function
gustavatmel 1:9c5af431a1f1 223 * pref_f -function return string with null terminated
gustavatmel 1:9c5af431a1f1 224 * Can be used for e.g. time string
gustavatmel 1:9c5af431a1f1 225 * e.g.
gustavatmel 1:9c5af431a1f1 226 * char* trace_time(){ return "rtc-time-in-string"; }
gustavatmel 1:9c5af431a1f1 227 * mbed_trace_prefix_function_set( &trace_time );
gustavatmel 1:9c5af431a1f1 228 */
gustavatmel 1:9c5af431a1f1 229 void mbed_trace_prefix_function_set( char* (*pref_f)(size_t) );
gustavatmel 1:9c5af431a1f1 230 /**
gustavatmel 1:9c5af431a1f1 231 * Set trace suffix function
gustavatmel 1:9c5af431a1f1 232 * suffix -function return string with null terminated
gustavatmel 1:9c5af431a1f1 233 * Can be used for e.g. time string
gustavatmel 1:9c5af431a1f1 234 * e.g.
gustavatmel 1:9c5af431a1f1 235 * char* trace_suffix(){ return " END"; }
gustavatmel 1:9c5af431a1f1 236 * mbed_trace_suffix_function_set( &trace_suffix );
gustavatmel 1:9c5af431a1f1 237 */
gustavatmel 1:9c5af431a1f1 238 void mbed_trace_suffix_function_set(char* (*suffix_f)(void) );
gustavatmel 1:9c5af431a1f1 239 /**
gustavatmel 1:9c5af431a1f1 240 * Set trace print function
gustavatmel 1:9c5af431a1f1 241 * By default, trace module print using printf() function,
gustavatmel 1:9c5af431a1f1 242 * but with this you can write own print function,
gustavatmel 1:9c5af431a1f1 243 * for e.g. to other IO device.
gustavatmel 1:9c5af431a1f1 244 */
gustavatmel 1:9c5af431a1f1 245 void mbed_trace_print_function_set( void (*print_f)(const char*) );
gustavatmel 1:9c5af431a1f1 246 /**
gustavatmel 1:9c5af431a1f1 247 * Set trace print function for tr_cmdline()
gustavatmel 1:9c5af431a1f1 248 */
gustavatmel 1:9c5af431a1f1 249 void mbed_trace_cmdprint_function_set( void (*printf)(const char*) );
gustavatmel 1:9c5af431a1f1 250 /**
gustavatmel 1:9c5af431a1f1 251 * Set trace mutex wait function
gustavatmel 1:9c5af431a1f1 252 * By default, trace calls are not thread safe.
gustavatmel 1:9c5af431a1f1 253 * If thread safety is required this can be used to set a callback function that will be called before each trace call.
gustavatmel 1:9c5af431a1f1 254 * The specific implementation is up to the application developer, but the mutex must count so it can
gustavatmel 1:9c5af431a1f1 255 * be acquired from a single thread repeatedly.
gustavatmel 1:9c5af431a1f1 256 */
gustavatmel 1:9c5af431a1f1 257 void mbed_trace_mutex_wait_function_set(void (*mutex_wait_f)(void));
gustavatmel 1:9c5af431a1f1 258 /**
gustavatmel 1:9c5af431a1f1 259 * Set trace mutex release function
gustavatmel 1:9c5af431a1f1 260 * By default, trace calls are not thread safe.
gustavatmel 1:9c5af431a1f1 261 * If thread safety is required this can be used to set a callback function that will be called before returning from
gustavatmel 1:9c5af431a1f1 262 * each trace call. The specific implementation is up to the application developer, but the mutex must count so it can
gustavatmel 1:9c5af431a1f1 263 * be acquired from a single thread repeatedly.
gustavatmel 1:9c5af431a1f1 264 */
gustavatmel 1:9c5af431a1f1 265 void mbed_trace_mutex_release_function_set(void (*mutex_release_f)(void));
gustavatmel 1:9c5af431a1f1 266 /**
gustavatmel 1:9c5af431a1f1 267 * When trace group contains text in filters,
gustavatmel 1:9c5af431a1f1 268 * trace print will be ignored.
gustavatmel 1:9c5af431a1f1 269 * e.g.:
gustavatmel 1:9c5af431a1f1 270 * mbed_trace_exclude_filters_set("mygr");
gustavatmel 1:9c5af431a1f1 271 * mbed_tracef(TRACE_ACTIVE_LEVEL_DEBUG, "ougr", "This is not printed");
gustavatmel 1:9c5af431a1f1 272 */
gustavatmel 1:9c5af431a1f1 273 void mbed_trace_exclude_filters_set(char* filters);
gustavatmel 1:9c5af431a1f1 274 /** get trace exclude filters
gustavatmel 1:9c5af431a1f1 275 */
gustavatmel 1:9c5af431a1f1 276 const char* mbed_trace_exclude_filters_get(void);
gustavatmel 1:9c5af431a1f1 277 /**
gustavatmel 1:9c5af431a1f1 278 * When trace group contains text in filter,
gustavatmel 1:9c5af431a1f1 279 * trace will be printed.
gustavatmel 1:9c5af431a1f1 280 * e.g.:
gustavatmel 1:9c5af431a1f1 281 * set_trace_include_filters("mygr");
gustavatmel 1:9c5af431a1f1 282 * mbed_tracef(TRACE_ACTIVE_LEVEL_DEBUG, "mygr", "Hi There");
gustavatmel 1:9c5af431a1f1 283 * mbed_tracef(TRACE_ACTIVE_LEVEL_DEBUG, "grp2", "This is not printed");
gustavatmel 1:9c5af431a1f1 284 */
gustavatmel 1:9c5af431a1f1 285 void mbed_trace_include_filters_set(char* filters);
gustavatmel 1:9c5af431a1f1 286 /** get trace include filters
gustavatmel 1:9c5af431a1f1 287 */
gustavatmel 1:9c5af431a1f1 288 const char* mbed_trace_include_filters_get(void);
gustavatmel 1:9c5af431a1f1 289 /**
gustavatmel 1:9c5af431a1f1 290 * General trace function
gustavatmel 1:9c5af431a1f1 291 * This should be used every time when user want to print out something important thing
gustavatmel 1:9c5af431a1f1 292 * Usage e.g.
gustavatmel 1:9c5af431a1f1 293 * mbed_tracef( TRACE_LEVEL_INFO, "mygr", "Hello world!");
gustavatmel 1:9c5af431a1f1 294 *
gustavatmel 1:9c5af431a1f1 295 * @param dlevel debug level
gustavatmel 1:9c5af431a1f1 296 * @param grp trace group
gustavatmel 1:9c5af431a1f1 297 * @param fmt trace format (like printf)
gustavatmel 1:9c5af431a1f1 298 * @param ... variable arguments related to fmt
gustavatmel 1:9c5af431a1f1 299 */
gustavatmel 1:9c5af431a1f1 300 #if defined(__GNUC__) || defined(__CC_ARM)
gustavatmel 1:9c5af431a1f1 301 void mbed_tracef(uint8_t dlevel, const char* grp, const char *fmt, ...) __attribute__ ((__format__(__printf__, 3, 4)));
gustavatmel 1:9c5af431a1f1 302 #else
gustavatmel 1:9c5af431a1f1 303 void mbed_tracef(uint8_t dlevel, const char* grp, const char *fmt, ...);
gustavatmel 1:9c5af431a1f1 304 #endif
gustavatmel 1:9c5af431a1f1 305 /**
gustavatmel 1:9c5af431a1f1 306 * General trace function
gustavatmel 1:9c5af431a1f1 307 * This should be used every time when user want to print out something important thing
gustavatmel 1:9c5af431a1f1 308 * and vprintf functionality is desired
gustavatmel 1:9c5af431a1f1 309 * Usage e.g.
gustavatmel 1:9c5af431a1f1 310 * va_list ap;
gustavatmel 1:9c5af431a1f1 311 * va_start (ap, fmt);
gustavatmel 1:9c5af431a1f1 312 * mbed_vtracef( TRACE_LEVEL_INFO, "mygr", fmt, ap );
gustavatmel 1:9c5af431a1f1 313 * va_end (ap);
gustavatmel 1:9c5af431a1f1 314 *
gustavatmel 1:9c5af431a1f1 315 * @param dlevel debug level
gustavatmel 1:9c5af431a1f1 316 * @param grp trace group
gustavatmel 1:9c5af431a1f1 317 * @param fmt trace format (like vprintf)
gustavatmel 1:9c5af431a1f1 318 * @param ap variable arguments list (like vprintf)
gustavatmel 1:9c5af431a1f1 319 */
gustavatmel 1:9c5af431a1f1 320 #if defined(__GNUC__) || defined(__CC_ARM)
gustavatmel 1:9c5af431a1f1 321 void mbed_vtracef(uint8_t dlevel, const char* grp, const char *fmt, va_list ap) __attribute__ ((__format__(__printf__, 3, 0)));
gustavatmel 1:9c5af431a1f1 322 #else
gustavatmel 1:9c5af431a1f1 323 void mbed_vtracef(uint8_t dlevel, const char* grp, const char *fmt, va_list ap);
gustavatmel 1:9c5af431a1f1 324 #endif
gustavatmel 1:9c5af431a1f1 325
gustavatmel 1:9c5af431a1f1 326
gustavatmel 1:9c5af431a1f1 327 /**
gustavatmel 1:9c5af431a1f1 328 * Get last trace from buffer
gustavatmel 1:9c5af431a1f1 329 */
gustavatmel 1:9c5af431a1f1 330 const char* mbed_trace_last(void);
gustavatmel 1:9c5af431a1f1 331 #if MBED_CONF_MBED_TRACE_FEA_IPV6 == 1
gustavatmel 1:9c5af431a1f1 332 /**
gustavatmel 1:9c5af431a1f1 333 * mbed_tracef helping function for convert ipv6
gustavatmel 1:9c5af431a1f1 334 * table to human readable string.
gustavatmel 1:9c5af431a1f1 335 * usage e.g.
gustavatmel 1:9c5af431a1f1 336 * char ipv6[16] = {...}; // ! array length is 16 bytes !
gustavatmel 1:9c5af431a1f1 337 * mbed_tracef(TRACE_LEVEL_INFO, "mygr", "ipv6 addr: %s", mbed_trace_ipv6(ipv6));
gustavatmel 1:9c5af431a1f1 338 *
gustavatmel 1:9c5af431a1f1 339 * @param add_ptr IPv6 Address pointer
gustavatmel 1:9c5af431a1f1 340 * @return temporary buffer where ipv6 is in string format
gustavatmel 1:9c5af431a1f1 341 */
gustavatmel 1:9c5af431a1f1 342 char* mbed_trace_ipv6(const void *addr_ptr);
gustavatmel 1:9c5af431a1f1 343 /**
gustavatmel 1:9c5af431a1f1 344 * mbed_tracef helping function for print ipv6 prefix
gustavatmel 1:9c5af431a1f1 345 * usage e.g.
gustavatmel 1:9c5af431a1f1 346 * char ipv6[16] = {...}; // ! array length is 16 bytes !
gustavatmel 1:9c5af431a1f1 347 * mbed_tracef(TRACE_LEVEL_INFO, "mygr", "ipv6 addr: %s", mbed_trace_ipv6_prefix(ipv6, 4));
gustavatmel 1:9c5af431a1f1 348 *
gustavatmel 1:9c5af431a1f1 349 * @param prefix IPv6 Address pointer
gustavatmel 1:9c5af431a1f1 350 * @param prefix_len prefix length
gustavatmel 1:9c5af431a1f1 351 * @return temporary buffer where ipv6 is in string format
gustavatmel 1:9c5af431a1f1 352 */
gustavatmel 1:9c5af431a1f1 353 char* mbed_trace_ipv6_prefix(const uint8_t *prefix, uint8_t prefix_len);
gustavatmel 1:9c5af431a1f1 354 #endif
gustavatmel 1:9c5af431a1f1 355 /**
gustavatmel 1:9c5af431a1f1 356 * mbed_tracef helping function for convert hex-array to string.
gustavatmel 1:9c5af431a1f1 357 * usage e.g.
gustavatmel 1:9c5af431a1f1 358 * char myarr[] = {0x10, 0x20};
gustavatmel 1:9c5af431a1f1 359 * mbed_tracef(TRACE_LEVEL_INFO, "mygr", "arr: %s", mbed_trace_array(myarr, 2));
gustavatmel 1:9c5af431a1f1 360 *
gustavatmel 1:9c5af431a1f1 361 * @param buf hex array pointer
gustavatmel 1:9c5af431a1f1 362 * @param len buffer length
gustavatmel 1:9c5af431a1f1 363 * @return temporary buffer where string copied
gustavatmel 1:9c5af431a1f1 364 * if array as string not fit to temp buffer, this function write '*' as last character,
gustavatmel 1:9c5af431a1f1 365 * which indicate that buffer is too small for array.
gustavatmel 1:9c5af431a1f1 366 */
gustavatmel 1:9c5af431a1f1 367 char* mbed_trace_array(const uint8_t* buf, uint16_t len);
gustavatmel 1:9c5af431a1f1 368
gustavatmel 1:9c5af431a1f1 369 #ifdef __cplusplus
gustavatmel 1:9c5af431a1f1 370 }
gustavatmel 1:9c5af431a1f1 371 #endif
gustavatmel 1:9c5af431a1f1 372
gustavatmel 1:9c5af431a1f1 373 #endif /* MBED_TRACE_H_ */
gustavatmel 1:9c5af431a1f1 374
gustavatmel 1:9c5af431a1f1 375 /* These macros are outside the inclusion guard so they will be re-evaluated for every inclusion of the header.
gustavatmel 1:9c5af431a1f1 376 * If tracing is disabled, the dummies will hide the real functions. The real functions can still be reached by
gustavatmel 1:9c5af431a1f1 377 * surrounding the name of the function with brackets, e.g. "(mbed_tracef)(dlevel, grp, "like so");"
gustavatmel 1:9c5af431a1f1 378 * */
gustavatmel 1:9c5af431a1f1 379 #if defined(FEA_TRACE_SUPPORT) || MBED_CONF_MBED_TRACE_ENABLE || YOTTA_CFG_MBED_TRACE || (defined(YOTTA_CFG) && !defined(NDEBUG))
gustavatmel 1:9c5af431a1f1 380 // Make sure FEA_TRACE_SUPPORT is always set whenever traces are enabled.
gustavatmel 1:9c5af431a1f1 381 #ifndef FEA_TRACE_SUPPORT
gustavatmel 1:9c5af431a1f1 382 #define FEA_TRACE_SUPPORT
gustavatmel 1:9c5af431a1f1 383 #endif
gustavatmel 1:9c5af431a1f1 384 // undefine dummies, revealing the real functions
gustavatmel 1:9c5af431a1f1 385 #undef MBED_TRACE_DUMMIES_DEFINED
gustavatmel 1:9c5af431a1f1 386 #undef mbed_trace_init
gustavatmel 1:9c5af431a1f1 387 #undef mbed_trace_free
gustavatmel 1:9c5af431a1f1 388 #undef mbed_trace_buffer_sizes
gustavatmel 1:9c5af431a1f1 389 #undef mbed_trace_config_set
gustavatmel 1:9c5af431a1f1 390 #undef mbed_trace_config_get
gustavatmel 1:9c5af431a1f1 391 #undef mbed_trace_prefix_function_set
gustavatmel 1:9c5af431a1f1 392 #undef mbed_trace_suffix_function_set
gustavatmel 1:9c5af431a1f1 393 #undef mbed_trace_print_function_set
gustavatmel 1:9c5af431a1f1 394 #undef mbed_trace_cmdprint_function_set
gustavatmel 1:9c5af431a1f1 395 #undef mbed_trace_mutex_wait_function_set
gustavatmel 1:9c5af431a1f1 396 #undef mbed_trace_mutex_release_function_set
gustavatmel 1:9c5af431a1f1 397 #undef mbed_trace_exclude_filters_set
gustavatmel 1:9c5af431a1f1 398 #undef mbed_trace_exclude_filters_get
gustavatmel 1:9c5af431a1f1 399 #undef mbed_trace_include_filters_set
gustavatmel 1:9c5af431a1f1 400 #undef mbed_trace_include_filters_get
gustavatmel 1:9c5af431a1f1 401 #undef mbed_tracef
gustavatmel 1:9c5af431a1f1 402 #undef mbed_vtracef
gustavatmel 1:9c5af431a1f1 403 #undef mbed_trace_last
gustavatmel 1:9c5af431a1f1 404 #undef mbed_trace_ipv6
gustavatmel 1:9c5af431a1f1 405 #undef mbed_trace_ipv6_prefix
gustavatmel 1:9c5af431a1f1 406 #undef mbed_trace_array
gustavatmel 1:9c5af431a1f1 407
gustavatmel 1:9c5af431a1f1 408 #elif !defined(MBED_TRACE_DUMMIES_DEFINED)
gustavatmel 1:9c5af431a1f1 409 // define dummies, hiding the real functions
gustavatmel 1:9c5af431a1f1 410 #define MBED_TRACE_DUMMIES_DEFINED
gustavatmel 1:9c5af431a1f1 411 #define mbed_trace_init(...) ((int) 0)
gustavatmel 1:9c5af431a1f1 412 #define mbed_trace_free(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 413 #define mbed_trace_buffer_sizes(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 414 #define mbed_trace_config_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 415 #define mbed_trace_config_get(...) ((uint8_t) 0)
gustavatmel 1:9c5af431a1f1 416 #define mbed_trace_prefix_function_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 417 #define mbed_trace_suffix_function_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 418 #define mbed_trace_print_function_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 419 #define mbed_trace_cmdprint_function_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 420 #define mbed_trace_mutex_wait_function_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 421 #define mbed_trace_mutex_release_function_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 422 #define mbed_trace_exclude_filters_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 423 #define mbed_trace_exclude_filters_get(...) ((const char *) 0)
gustavatmel 1:9c5af431a1f1 424 #define mbed_trace_include_filters_set(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 425 #define mbed_trace_include_filters_get(...) ((const char *) 0)
gustavatmel 1:9c5af431a1f1 426 #define mbed_trace_last(...) ((const char *) 0)
gustavatmel 1:9c5af431a1f1 427 #define mbed_tracef(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 428 #define mbed_vtracef(...) ((void) 0)
gustavatmel 1:9c5af431a1f1 429 /**
gustavatmel 1:9c5af431a1f1 430 * These helper functions accumulate strings in a buffer that is only flushed by actual trace calls. Using these
gustavatmel 1:9c5af431a1f1 431 * functions outside trace calls could cause the buffer to overflow.
gustavatmel 1:9c5af431a1f1 432 */
gustavatmel 1:9c5af431a1f1 433 #define mbed_trace_ipv6(...) dont_use_trace_helpers_outside_trace_calls
gustavatmel 1:9c5af431a1f1 434 #define mbed_trace_ipv6_prefix(...) dont_use_trace_helpers_outside_trace_calls
gustavatmel 1:9c5af431a1f1 435 #define mbed_trace_array(...) dont_use_trace_helpers_outside_trace_calls
gustavatmel 1:9c5af431a1f1 436
gustavatmel 1:9c5af431a1f1 437 #endif /* FEA_TRACE_SUPPORT */