C++ APIs for assertions, invariants, and writing formatted debug messages to a UART. More...

#include <__debug.h>
#include <cheri.hh>
#include <compartment.h>
#include <cstddef>
#include <platform-uart.hh>
#include <string.h>
#include <switcher.h>
#include <timeout.h>
#include <string_view>
#include <type_traits>

Classes
struct	DebugWriter
	Abstract class for writing debug output. More...
struct	DebugFormatArgumentAdaptor< bool >
	Boolean specialisation, prints "true" or "false". More...
struct	DebugFormatArgumentAdaptor< char >
	Character specialisation, prints the character. More...
struct	DebugFormatArgumentAdaptor< uint8_t >
	Unsigned character specialisation, prints the character as a hex number. More...
struct	DebugFormatArgumentAdaptor< uint16_t >
	Unsigned 16-bit integer specialisation, prints the integer as a hex number. More...
struct	DebugFormatArgumentAdaptor< uint32_t >
	Unsigned 32-bit integer specialisation, prints the integer as a hex number. More...
struct	DebugFormatArgumentAdaptor< uint64_t >
	Unsigned 64-bit integer specialisation, prints the integer as a hex number. More...
struct	DebugFormatArgumentAdaptor< int8_t >
	Signed 8-bit integer specialisations, print the integer as a decimal number. More...
struct	DebugFormatArgumentAdaptor< int16_t >
	Signed 16-bit integer specialisations, print the integer as a decimal number. More...
struct	DebugFormatArgumentAdaptor< int32_t >
	Signed 32-bit integer specialisations, print the integer as a decimal number. More...
struct	DebugFormatArgumentAdaptor< int64_t >
	Signed 64-bit integer specialisations, print the integer as a decimal number. More...
struct	DebugFormatArgumentAdaptor< float >
struct	DebugFormatArgumentAdaptor< double >
struct	DebugFormatArgumentAdaptor< const char * >
	C string specialisation, prints the string as-is. More...
struct	DebugFormatArgumentAdaptor< std::string_view >
	String view specialisation, prints the string as-is. More...
struct	DebugFormatArgumentAdaptor< std::string >
	String view specialisation, use the C string handler. More...
struct	DebugFormatArgumentAdaptor< T >
	Enum specialisation, prints the enum as a string and then the numeric value. More...
struct	DebugFormatArgumentAdaptor< TimeoutArgument >
	Helper for printing timeouts. More...
struct	DebugFormatArgumentAdaptor< CHERI::PermissionSet >
	Permission set specialisation. More...
struct	DebugFormatArgumentAdaptor< std::nullptr_t >
	Null pointer specialisation. More...
struct	DebugFormatArgumentAdaptor< CHERI::Capability< T, Sealed > >
	Specialisation for the CHERI capability wrapper class, prints the capability in the same format as bare pointers. More...
struct	anonymous_namespace{debug.hh}::DebugContext< N >
	Helper class wrapping a string for use as a template argument. More...
struct	anonymous_namespace{debug.hh}::SourceLocation
	Our libc++ does not currently provide source_location, but our clang provides the necessary builtins for one. More...
struct	anonymous_namespace{debug.hh}::DebugLevelTemplateArgument
	Compatibility wrapper that can be constructed from a boolean or a DebugLevel. More...
class	anonymous_namespace{debug.hh}::ConditionalDebug< Threshold, Context, EnableAssertions, VerboseInvariants >
	Conditional debug class. More...
struct	anonymous_namespace{debug.hh}::ConditionalDebug< Threshold, Context, EnableAssertions, VerboseInvariants >::Invariant< Args >
	Function-like class for invariants that is expected to be used via the deduction guide as: More...
struct	anonymous_namespace{debug.hh}::ConditionalDebug< Threshold, Context, EnableAssertions, VerboseInvariants >::Assert< Args >
	Function-like class for assertions that is expected to be used via the deduction guide as: More...
class	anonymous_namespace{debug.hh}::StackUsageCheck< Mode, Expected, Fn >
	Check the (dynamic) stack usage of a function, including all of its callees. More...

Namespaces
namespace	DebugConcepts
	Concepts used for matching types in the debug code.

Concepts
concept	DebugConcepts::IsBool
	Helper concept for matching booleans.
concept	DebugConcepts::IsEnum
	Helper concept for matching enumerations.
concept	DebugConcepts::LazyAssertion
	Concept for something that can be lazily called to produce a bool.
concept	DebugConcepts::IsPointerButNotCString
	Helper for identifying pointers that are (probably) not C strings.
concept	DebugConcepts::IsConvertibleToAddress
	Helper concept for things that can be converted to addresses but are not enumerations.

Typedefs
using	DebugCallback = void (*)(uintptr_t, DebugWriter &)
	Callback for custom types in debug output.

Enumerations
enum class	anonymous_namespace{debug.hh}::DebugLevel { anonymous_namespace{debug.hh}::Information , anonymous_namespace{debug.hh}::Warning , anonymous_namespace{debug.hh}::Error , anonymous_namespace{debug.hh}::Critical , anonymous_namespace{debug.hh}::None }
	Debug level. More...
enum class	StackCheckMode { Disabled , LoggingMonotonic , Logging , AssertingMonotonic , Asserting }

Functions
template<typename T> requires DebugConcepts::IsEnum<T>
void	debug_enum_helper (uintptr_t value, DebugWriter &writer)
	Helper function for writing enumerations.
template<size_t I>
void	map_debug_argument (DebugFormatArgument *arguments, auto &&argumentTuple)
	Recursive helper that maps from a tuple representing the arguments into a type-erased array.
template<typename... Args>
void	make_debug_arguments_list (DebugFormatArgument *arguments, Args &...args)
	Convert args into a type-erased array of DebugFormatArguments in arguments.
__cheri_libcall void	debug_log_message_write (const char context, const char format, DebugFormatArgument *messages, size_t messageCount)
	Library function that writes a debug message.
__cheri_libcall void	debug_report_failure (const char kind, const char file, const char function, int line, const char fmt, DebugFormatArgument *arguments, size_t argumentCount)
consteval std::strong_ordering	anonymous_namespace{debug.hh}::operator<=> (const DebugLevel Level, const DebugLevel Threshold)
	Comparison operator to determine whether a provided debug level is above the threshold at which it should be reported.

Detailed Description

C++ APIs for assertions, invariants, and writing formatted debug messages to a UART.

When enabled (for template parameter) the implementations of these are in the debug library, which must be linked into the firmware image.

Most of the functionality in this file is exposed via the ConditionalDebug template.

Definition in file debug.hh.

Typedef Documentation

◆ DebugCallback

using DebugCallback = void (*)(uintptr_t, DebugWriter &)

Callback for custom types in debug output.

This should use the second argument to write the first argument to the debug output.

Definition at line 172 of file debug.hh.

Function Documentation

◆ debug_enum_helper()

template<typename T>
requires DebugConcepts::IsEnum<T>

void debug_enum_helper	(	uintptr_t	value,
		DebugWriter &	writer )

Helper function for writing enumerations.

Enumerations are written using magic_enum to provide a string and then a numeric value.

Definition at line 159 of file debug.hh.

◆ debug_log_message_write()

__cheri_libcall void debug_log_message_write	(	const char *	context,
		const char *	format,
		DebugFormatArgument *	messages,
		size_t	messageCount )

Library function that writes a debug message.

This runs with interrupts disabled (to avoid interleaving) and prints an array of debug messages. This is intended to allow a single call to print multiple format strings without requiring the format strings to be copied, so that the debugging APIs can wrap a user-provided format string.

Referenced by anonymous_namespace{debug.hh}::ConditionalDebug< Threshold, Context, EnableAssertions, VerboseInvariants >::log().