px-lib  0.9.3
Cross-platform embedded library and documentation for 8/16/32-bit microcontrollers
px_dbg.h : Debug module

Description

Outputs debug information to a serial console.

File(s):

An old school debugging technique which still works well is to add debug print statements in the source code to track program flow and check for coding mistakes during development. Afterwards the debug print statements are removed from the final release build to avoid the significant code and delay overhead.

This module allows one to easily add debug print macros to the source code and enable them by defining PX_DBG=1 or remove them from the build by defining PX_DBG=0 in the Makefile. There is no need to manually edit the source code afterwards for the release build.

px_dbg_test.png
Debug output on Tera Term

Set PX_DBG_CFG_COLOR to 1 to mark debug message level with color on an ANSI/VT100 terminal emulator for example Tera Term.

The following macros can be used:

PX_DBG_CFG_MSG_LEVEL is a bitmask that is used to select which debug messages are compiled into the source code: PX_DBG_ERR(), PX_DBG_WARN(), PX_DBG_INFO(), or other combinations including NONE or ALL. It does not affect PX_DBG_TRACE() or PX_DBG_ASSERT() macros.

The debug macros will report the file name / module name and line number as well as the user format string. To save code space, the file name / module name must be declared at the top of the C file using PX_DBG_DECL_NAME(). This is the correct way to declare the file name / module name:

#include "px_dbg.h"
PX_DBG_DECL_NAME("module name / file name"); // Or PX_DBG_DECL_NAME(__FILE__);

If PX_DBG_DECL_NAME() is not used, then the compiler will output the following error when debug output is enabled (PX_DBG=1):

error: '_px_dbg_name' undeclared (first use in this function)

The debug output can be redirected by using the PX_DBG_CFG_PUT_CHAR macro, for example to stderr, a different uart or to a log file on an SD card.

Example:

#include "px_defines.h"
#include "px_board.h"
#include "px_uart.h"
#include "px_uart_stdio.h"
#include "px_dbg.h"
PX_DBG_DECL_NAME("px_dbg_test")
// Declare UART handle structure
px_uart_handle_t px_uart_handle;
uint8_t calc(uint8_t val)
{
uint8_t answer;
// Report function call with parameter value
PX_DBG_INFO("calc(val = %u)", val);
// Is val equal to zero?
if(val == 0)
{
PX_DBG_ERR("val may not be equal to zero");
return 0;
}
// Calculate answer
answer = 100 / val;
// Report answer
PX_DBG_INFO("answer = %u", answer);
return answer;
}
int main(void)
{
uint8_t val;
uint8_t answer;
// Initialise modules
// Open UART1 @ 115200 BAUD, 8 data bits, no parity, 1 stop bit
px_uart_open2(&px_uart_handle,
PX_UART_NR_1,
115200,
PX_UART_DATA_BITS_8,
PX_UART_PARITY_NONE,
PX_UART_STOP_BITS_1);
// Direct stdio to UART0
px_uart_stdio_init(&px_uart_handle);
// Enable interrupts
px_interrupts_enable();
PX_DBG_WARN("Calculation started");
for(val = 0; val < 3; val++)
{
// Calculate answer
answer = calc(val);
}
PX_DBG_TRACE("Calculation finished. answer = %u\n", answer);
}

The project wide PX_DBG_CFG_MSG_LEVEL setting in the Makefile or "px_dbg_cfg.h" can be overriden for a specific C file as follows:

// PX_DBG_CFG_MSG_LEVEL defined in Makefile?
#ifdef PX_DBG_CFG_MSG_LEVEL
#undef PX_DBG_CFG_MSG_LEVEL
#endif
// Set output level to ALL (INFO, WARN and ERROR messages)
#define PX_DBG_CFG_MSG_LEVEL PX_DBG_CFG_MSG_LEVEL_ALL
#include "px_dbg.h"
PX_DBG_DECL_NAME("buggy_module");

The PX_DBG_CFG_MSG_LEVEL can easily be tested with the the PX_DBG_LEVEL_ERR, PX_DBG_LEVEL_WARN or PX_DBG_LEVEL_INFO macro to add code conditionally, for example:

void tx_data(void * data, size_t nr_of_bytes)
{
// PX_DBG=1 and PX_DBG_CFG_MSG_LEVEL includes INFO messages?
#if PX_DBG_LEVEL_INFO
// Report content of buffer
PX_DBG_TRACE_HEXDUMP(data, nr_of_bytes);
#endif
// Rest of function...
}

A naming convention is used to start a function, variable or macro name with an underscore ('_') to indicate that it is used internally by this C module and should not be used directly, for example _px_dbg_log_err() or _px_dbg_name[].

Macros

#define PX_DBG_CFG_MSG_LEVEL   PX_DBG_CFG_MSG_LEVEL_ALL
 Set global debug output level. More...
 
#define PX_DBG_CFG_COLOR   1
 Disable (0) or Enable (1) VT100 terminal color output. More...
 
#define PX_DBG_CFG_BUF_SIZE   64
 Debug output string buffer size. More...
 
#define PX_DBG_CFG_MSG_LEVEL   PX_DBG_CFG_MSG_LEVEL_ALL
 Set global debug output level. More...
 
#define PX_DBG_CFG_COLOR   1
 Disable (0) or Enable (1) VT100 terminal color output. More...
 
#define PX_DBG_CFG_BUF_SIZE   64
 Debug output string buffer size. More...
 
#define PX_DBG_CFG_MSG_LEVEL   PX_DBG_CFG_MSG_LEVEL_ALL
 Set global debug output level. More...
 
#define PX_DBG_CFG_COLOR   1
 Disable (0) or Enable (1) VT100 terminal color output. More...
 
#define PX_DBG_CFG_BUF_SIZE   64
 Debug output string buffer size. More...
 
#define PX_DBG   1
 Set flag to disable (PX_DBG=0) or enable (PX_DBG=1) debug. More...
 
#define PX_DBG_LEVEL_INFO   (PX_DBG && ((PX_DBG_CFG_MSG_LEVEL) & PX_DBG_CFG_MSG_LEVEL_INFO))
 Debug message level INFO enabled? More...
 
#define PX_DBG_LEVEL_WARN   (PX_DBG && ((PX_DBG_CFG_MSG_LEVEL) & PX_DBG_CFG_MSG_LEVEL_WARN))
 Debug message level WARN enabled? More...
 
#define PX_DBG_LEVEL_ERR   (PX_DBG && ((PX_DBG_CFG_MSG_LEVEL) & PX_DBG_CFG_MSG_LEVEL_ERR))
 Debug message level ERROR enabled? More...
 
#define PX_DBG_INFO(format, ...)   _px_dbg_log_info(_px_dbg_name, (uint16_t)__LINE__, PX_PGM_STR(format), ## __VA_ARGS__)
 Macro to display a formatted INFO message. More...
 
#define PX_DBG_WARN(format, ...)   _px_dbg_log_warn(_px_dbg_name, (uint16_t)__LINE__, PX_PGM_STR(format), ## __VA_ARGS__)
 Macro to display a formatted WARNING message. More...
 
#define PX_DBG_ERR(format, ...)   _px_dbg_log_err(_px_dbg_name, (uint16_t)__LINE__, PX_PGM_STR(format), ## __VA_ARGS__)
 Macro to display a formatted ERROR message. More...
 
#define PX_DBG_TRACE(format, ...)   _px_dbg_trace(PX_PGM_STR(format), ## __VA_ARGS__)
 Macro to output debug information if PX_DBG = 1. More...
 
#define PX_DBG_TRACE_DATA(data, nr_of_bytes)   _px_dbg_trace_data(data, nr_of_bytes)
 Macro to output the content of a buffer if PX_DBG = 1. More...
 
#define PX_DBG_TRACE_HEXDUMP(data, nr_of_bytes)   _px_dbg_trace_hexdump(data, nr_of_bytes)
 Macro to output the content of a buffer if PX_DBG = 1. More...
 
#define PX_DBG_ASSERT(expression)
 Macro that will test an expression, and block indefinitely if false. More...
 
#define PX_DBG_CFG_MSG_LEVEL   PX_DBG_CFG_MSG_LEVEL_ALL
 Set global debug output level. More...
 
#define PX_DBG_CFG_COLOR   0
 Disable (0) or Enable (1) VT100 terminal color output. More...
 
#define PX_DBG_CFG_BUF_SIZE   64
 Debug output string buffer size. More...
 

Functions

void _px_dbg_log_info (const char *name, uint16_t line, const char *format,...)
 Output info debug information: module name, line and variable argument user format string. More...
 
void _px_dbg_log_warn (const char *name, uint16_t line, const char *format,...)
 Output warning debug information: module name, line and variable argument user format string. More...
 
void _px_dbg_log_err (const char *name, uint16_t line, const char *format,...)
 Output error debug information: module name, line and variable argument user format string. More...
 
void _px_dbg_assert (const char *name, uint16_t line, const char *expression) PX_ATTR_NORETURN
 Report that an assertion has failed and block indefinitely. More...
 
void _px_dbg_trace (const char *format,...)
 Output debug information: variable argument user format string. More...
 
void _px_dbg_trace_data (const void *data, size_t nr_of_bytes)
 Output debug information: content of a buffer as an array of HEX values. More...
 
void _px_dbg_trace_hexdump (const void *data, size_t nr_of_bytes)
 Output debug information: content of a buffer as a spaced table of HEX values and ASCII characters. More...
 

Debug message level bitmask definitions

#define PX_DBG_CFG_MSG_LEVEL_NONE   0
 None. More...
 
#define PX_DBG_CFG_MSG_LEVEL_INFO   (1<<0)
 Info. More...
 
#define PX_DBG_CFG_MSG_LEVEL_WARN   (1<<1)
 Warnings. More...
 
#define PX_DBG_CFG_MSG_LEVEL_ERR   (1<<2)
 Errors. More...
 
#define PX_DBG_CFG_MSG_LEVEL_ALL   (PX_DBG_CFG_MSG_LEVEL_INFO | PX_DBG_CFG_MSG_LEVEL_WARN | PX_DBG_CFG_MSG_LEVEL_ERR)
 All. More...
 

Macro Definition Documentation

◆ PX_DBG_CFG_MSG_LEVEL [1/4]

#define PX_DBG_CFG_MSG_LEVEL   PX_DBG_CFG_MSG_LEVEL_ALL

Set global debug output level.

It is a bitmask that sets which debug info will be emitted. E.g.

  • PX_DBG_CFG_MSG_LEVEL = PX_DBG_CFG_MSG_LEVEL_ERR : Report errors only
  • PX_DBG_CFG_MSG_LEVEL = (PX_DBG_CFG_MSG_LEVEL_ERR | PX_DBG_CFG_MSG_LEVEL_WARN) : Report errors + warnings
  • PX_DBG_CFG_MSG_LEVEL = (PX_DBG_CFG_MSG_LEVEL_ERR | PX_DBG_CFG_MSG_LEVEL_WARN | PX_DBG_CFG_MSG_LEVEL_INFO) : Report errors + warnings + info

Definition at line 48 of file px_dbg_cfg.h.

◆ PX_DBG_CFG_COLOR [1/4]

#define PX_DBG_CFG_COLOR   1

Disable (0) or Enable (1) VT100 terminal color output.

Definition at line 52 of file px_dbg_cfg.h.

◆ PX_DBG_CFG_BUF_SIZE [1/4]

#define PX_DBG_CFG_BUF_SIZE   64

Debug output string buffer size.

Definition at line 55 of file px_dbg_cfg.h.

◆ PX_DBG_CFG_MSG_LEVEL [2/4]

#define PX_DBG_CFG_MSG_LEVEL   PX_DBG_CFG_MSG_LEVEL_ALL

Set global debug output level.

It is a bitmask that sets which debug info will be emitted. E.g.

  • PX_DBG_CFG_MSG_LEVEL = PX_DBG_CFG_MSG_LEVEL_ERR : Report errors only
  • PX_DBG_CFG_MSG_LEVEL = (PX_DBG_CFG_MSG_LEVEL_ERR | PX_DBG_CFG_MSG_LEVEL_WARN) : Report errors + warnings
  • PX_DBG_CFG_MSG_LEVEL = (PX_DBG_CFG_MSG_LEVEL_ERR | PX_DBG_CFG_MSG_LEVEL_WARN | PX_DBG_CFG_MSG_LEVEL_INFO) : Report errors + warnings + info

Definition at line 48 of file px_dbg_cfg.h.

◆ PX_DBG_CFG_COLOR [2/4]

#define PX_DBG_CFG_COLOR   1

Disable (0) or Enable (1) VT100 terminal color output.

Definition at line 52 of file px_dbg_cfg.h.

◆ PX_DBG_CFG_BUF_SIZE [2/4]

#define PX_DBG_CFG_BUF_SIZE   64

Debug output string buffer size.

Definition at line 55 of file px_dbg_cfg.h.

◆ PX_DBG_CFG_MSG_LEVEL [3/4]

#define PX_DBG_CFG_MSG_LEVEL   PX_DBG_CFG_MSG_LEVEL_ALL

Set global debug output level.

It is a bitmask that sets which debug info will be emitted. E.g.

  • PX_DBG_CFG_MSG_LEVEL = PX_DBG_CFG_MSG_LEVEL_ERR : Report errors only
  • PX_DBG_CFG_MSG_LEVEL = (PX_DBG_CFG_MSG_LEVEL_ERR | PX_DBG_CFG_MSG_LEVEL_WARN) : Report errors + warnings
  • PX_DBG_CFG_MSG_LEVEL = (PX_DBG_CFG_MSG_LEVEL_ERR | PX_DBG_CFG_MSG_LEVEL_WARN | PX_DBG_CFG_MSG_LEVEL_INFO) : Report errors + warnings + info

Definition at line 48 of file px_dbg_cfg.h.

◆ PX_DBG_CFG_COLOR [3/4]

#define PX_DBG_CFG_COLOR   1

Disable (0) or Enable (1) VT100 terminal color output.

Definition at line 52 of file px_dbg_cfg.h.

◆ PX_DBG_CFG_BUF_SIZE [3/4]

#define PX_DBG_CFG_BUF_SIZE   64

Debug output string buffer size.

Definition at line 55 of file px_dbg_cfg.h.

◆ PX_DBG

#define PX_DBG   1

Set flag to disable (PX_DBG=0) or enable (PX_DBG=1) debug.

Definition at line 135 of file px_dbg.h.

◆ PX_DBG_CFG_MSG_LEVEL_NONE

#define PX_DBG_CFG_MSG_LEVEL_NONE   0

None.

Definition at line 165 of file px_dbg.h.

◆ PX_DBG_CFG_MSG_LEVEL_INFO

#define PX_DBG_CFG_MSG_LEVEL_INFO   (1<<0)

Info.

Definition at line 167 of file px_dbg.h.

◆ PX_DBG_CFG_MSG_LEVEL_WARN

#define PX_DBG_CFG_MSG_LEVEL_WARN   (1<<1)

Warnings.

Definition at line 169 of file px_dbg.h.

◆ PX_DBG_CFG_MSG_LEVEL_ERR

#define PX_DBG_CFG_MSG_LEVEL_ERR   (1<<2)

Errors.

Definition at line 171 of file px_dbg.h.

◆ PX_DBG_CFG_MSG_LEVEL_ALL

All.

Definition at line 173 of file px_dbg.h.

◆ PX_DBG_LEVEL_INFO

#define PX_DBG_LEVEL_INFO   (PX_DBG && ((PX_DBG_CFG_MSG_LEVEL) & PX_DBG_CFG_MSG_LEVEL_INFO))

Debug message level INFO enabled?

Definition at line 276 of file px_dbg.h.

◆ PX_DBG_LEVEL_WARN

#define PX_DBG_LEVEL_WARN   (PX_DBG && ((PX_DBG_CFG_MSG_LEVEL) & PX_DBG_CFG_MSG_LEVEL_WARN))

Debug message level WARN enabled?

Definition at line 278 of file px_dbg.h.

◆ PX_DBG_LEVEL_ERR

#define PX_DBG_LEVEL_ERR   (PX_DBG && ((PX_DBG_CFG_MSG_LEVEL) & PX_DBG_CFG_MSG_LEVEL_ERR))

Debug message level ERROR enabled?

Definition at line 280 of file px_dbg.h.

◆ PX_DBG_INFO

#define PX_DBG_INFO (   format,
  ... 
)    _px_dbg_log_info(_px_dbg_name, (uint16_t)__LINE__, PX_PGM_STR(format), ## __VA_ARGS__)

Macro to display a formatted INFO message.

Definition at line 287 of file px_dbg.h.

◆ PX_DBG_WARN

#define PX_DBG_WARN (   format,
  ... 
)    _px_dbg_log_warn(_px_dbg_name, (uint16_t)__LINE__, PX_PGM_STR(format), ## __VA_ARGS__)

Macro to display a formatted WARNING message.

Definition at line 294 of file px_dbg.h.

◆ PX_DBG_ERR

#define PX_DBG_ERR (   format,
  ... 
)    _px_dbg_log_err(_px_dbg_name, (uint16_t)__LINE__, PX_PGM_STR(format), ## __VA_ARGS__)

Macro to display a formatted ERROR message.

Definition at line 301 of file px_dbg.h.

◆ PX_DBG_TRACE

#define PX_DBG_TRACE (   format,
  ... 
)    _px_dbg_trace(PX_PGM_STR(format), ## __VA_ARGS__)

Macro to output debug information if PX_DBG = 1.

This macro does not append a new line character ('\n') so that multiple strings can be sent on the same line.

Parameters
[in]formatFormat string following by a variable list of arguments.

Definition at line 327 of file px_dbg.h.

◆ PX_DBG_TRACE_DATA

#define PX_DBG_TRACE_DATA (   data,
  nr_of_bytes 
)    _px_dbg_trace_data(data, nr_of_bytes)

Macro to output the content of a buffer if PX_DBG = 1.

The data is displayed as an array of HEX values.

Parameters
dataPointer to buffer containing data to display
nr_of_bytesSize of buffer (in bytes)

Definition at line 338 of file px_dbg.h.

◆ PX_DBG_TRACE_HEXDUMP

#define PX_DBG_TRACE_HEXDUMP (   data,
  nr_of_bytes 
)    _px_dbg_trace_hexdump(data, nr_of_bytes)

Macro to output the content of a buffer if PX_DBG = 1.

The data is displayed as a spaced table of HEX values and ASCII characters.

Parameters
dataPointer to buffer containing data to display
nr_of_bytesSize of buffer (in bytes)

Definition at line 349 of file px_dbg.h.

◆ PX_DBG_ASSERT

#define PX_DBG_ASSERT (   expression)
Value:
do \
{ \
if(!(expression)) \
{ \
_px_dbg_assert(_px_dbg_name, (uint16_t)__LINE__, PX_PGM_STR(#expression)); \
} \
} while(0)

Macro that will test an expression, and block indefinitely if false.

This macro will perform the test and if false, will output the filename and line number with the test appended. The macro will then block indefinitely.

For supported architectures, it will generate a debug breakpoint.

Parameters
[in]expressionExpression that evaluates to a boolean value (true or false)

Definition at line 362 of file px_dbg.h.

◆ PX_DBG_CFG_MSG_LEVEL [4/4]

#define PX_DBG_CFG_MSG_LEVEL   PX_DBG_CFG_MSG_LEVEL_ALL

Set global debug output level.

It is a bitmask that sets which debug info will be emitted. E.g.

  • PX_DBG_CFG_MSG_LEVEL = PX_DBG_CFG_MSG_LEVEL_ERR : Report errors only
  • PX_DBG_CFG_MSG_LEVEL = (PX_DBG_CFG_MSG_LEVEL_ERR | PX_DBG_CFG_MSG_LEVEL_WARN) : Report errors + warnings
  • PX_DBG_CFG_MSG_LEVEL = (PX_DBG_CFG_MSG_LEVEL_ERR | PX_DBG_CFG_MSG_LEVEL_WARN | PX_DBG_CFG_MSG_LEVEL_INFO) : Report errors + warnings + info

Definition at line 48 of file px_dbg_cfg_template.h.

◆ PX_DBG_CFG_COLOR [4/4]

#define PX_DBG_CFG_COLOR   0

Disable (0) or Enable (1) VT100 terminal color output.

Definition at line 52 of file px_dbg_cfg_template.h.

◆ PX_DBG_CFG_BUF_SIZE [4/4]

#define PX_DBG_CFG_BUF_SIZE   64

Debug output string buffer size.

Definition at line 55 of file px_dbg_cfg_template.h.

Function Documentation

◆ _px_dbg_log_info()

void _px_dbg_log_info ( const char *  name,
uint16_t  line,
const char *  format,
  ... 
)

Output info debug information: module name, line and variable argument user format string.

The line is automatically appended with a new line character ('\n'), except if the format string ends with a tab character ('\t'). The tab character at the end of the string is discarded.

Parameters
nameModule / file name
lineLine number
formatUser format string
...Variable number of arguments

Definition at line 238 of file px_dbg.c.

◆ _px_dbg_log_warn()

void _px_dbg_log_warn ( const char *  name,
uint16_t  line,
const char *  format,
  ... 
)

Output warning debug information: module name, line and variable argument user format string.

The line is automatically appended with a new line character ('\n'), except if the format string ends with a tab character ('\t'). The tab character at the end of the string is discarded.

Parameters
nameModule / file name
lineLine number
formatUser format string
...Variable number of arguments

Definition at line 258 of file px_dbg.c.

◆ _px_dbg_log_err()

void _px_dbg_log_err ( const char *  name,
uint16_t  line,
const char *  format,
  ... 
)

Output error debug information: module name, line and variable argument user format string.

The line is automatically appended with a new line character ('\n'), except if the format string ends with a tab character ('\t'). The tab character at the end of the string is discarded.

Parameters
nameModule / file name
lineLine number
formatUser format string
...Variable number of arguments

Definition at line 278 of file px_dbg.c.

◆ _px_dbg_assert()

void _px_dbg_assert ( const char *  name,
uint16_t  line,
const char *  expression 
)

Report that an assertion has failed and block indefinitely.

For supported architectures it will also generate a debug breakpoint.

Parameters
nameModule / file name
lineLine number
expressionTest expression string for assertion

Definition at line 298 of file px_dbg.c.

◆ _px_dbg_trace()

void _px_dbg_trace ( const char *  format,
  ... 
)

Output debug information: variable argument user format string.

This function does not automatically append a new line character ('\n') so that multiple strings can be sent on the same line.

Parameters
formatUser format string
...Variable number of arguments

Definition at line 325 of file px_dbg.c.

◆ _px_dbg_trace_data()

void _px_dbg_trace_data ( const void *  data,
size_t  nr_of_bytes 
)

Output debug information: content of a buffer as an array of HEX values.

Parameters
dataPointer to buffer containing data to display
nr_of_bytesSize of buffer (in bytes)

Definition at line 339 of file px_dbg.c.

◆ _px_dbg_trace_hexdump()

void _px_dbg_trace_hexdump ( const void *  data,
size_t  nr_of_bytes 
)

Output debug information: content of a buffer as a spaced table of HEX values and ASCII characters.

Parameters
dataPointer to buffer containing data to display
nr_of_bytesSize of buffer (in bytes)

Definition at line 351 of file px_dbg.c.