micro_os_plus::trace Namespace Reference

Tracing support namespace. More...

Namespaces
namespace	detail
	Implementation details namespace.

Functions
void	dump_args (int argc, char *argv[], const char *name="main") noexcept
	Send the argv[] array to the trace output channel.
void	flush (void) noexcept
	Flush the trace output channel.
void	initialise (void) noexcept
	Initialise the trace output channel.
int	printf (const char *format,...) noexcept
	Write a formatted string to the trace output channel.
int	putchar (int c) noexcept
	Write the single character to the trace output channel.
int	puts (const char *s="") noexcept
	Write the string and a line terminator to the trace output channel.
int	vprintf (const char *format, std::va_list arguments) noexcept
	Write a formatted variable arguments list to the trace output channel.
ssize_t	write (const void *buf, std::size_t nbyte) noexcept
	Write the given number of bytes to the trace output channel.

Detailed Description

The trace channel functions as a standalone output device designed specifically for diagnostic purposes.

The API is straightforward and emulates the standard C output calls:

• micro_os_plus::trace::printf() / micro_os_plus_trace_printf()
• micro_os_plus::trace::puts() / micro_os_plus_trace_puts()
• micro_os_plus::trace::putchar() / micro_os_plus_trace_putchar()

The C++ API is implemented as a class template, micro_os_plus::trace::detail::tracer, parameterised on a policy class that supplies the low-level primitives. One such policy class is declared here: micro_os_plus::trace::detail::implementation for production use. tracer<implementation> is an independent class instantiation: it is already instantiated and is used internally; it shares no mutable state.

The free functions (micro_os_plus::trace::printf() etc.) are a thin alias for tracer<implementation>, so existing call sites do not need to change.

The user is required to provide implementations of the following static methods, once per policy class actually used:

• micro_os_plus::trace::detail::implementation::initialise()
• micro_os_plus::trace::detail::implementation::write()
• micro_os_plus::trace::detail::implementation::flush()

Trace support is activated by adding the MICRO_OS_PLUS_TRACE macro definition to the compiler line.

When MICRO_OS_PLUS_TRACE is not defined, all functions are inlined to empty bodies. This approach eliminates the need for trace calls to be conditionally compiled using #if defined(MICRO_OS_PLUS_TRACE) and #endif. However, the drawback is that the associated header file must always be included.