sdk/core/loader/debug.hh - 3p/cheriot-rtos - Git at Google

 // Copyright Microsoft and CHERIoT Contributors.
 // SPDX-License-Identifier: MIT

 #pragma once
 #include <cheri.hh>
 #include <compartment.h>
 #include <platform-uart.hh>

 #include <array>

 namespace
 {
 	/**
 	 * Is the loader being debugged?
 	 */
 	static constexpr bool DebugLoader = DEBUG_LOADER;

 	namespace DebugConcepts
 	{
 		/// Helper concept for matching booleans
 		template<typename T>
 		concept IsBool = std::is_same_v<T, bool>;

 		/// Helper concept for matching enumerations.
 		template<typename T>
 		concept IsEnum = std::is_enum_v<T>;

 		/// Concept for something that can be lazily called to produce a bool.
 		template<typename T>
 		concept LazyAssertion = requires(T v)
 		{
 			{
 				v()
 				} -> IsBool;
 		};
 	} // namespace DebugConcepts

 	/**
 	 * Helper class for writing debug output to the UART.  This performs no
 	 * internal buffering and assumes interrupts are disabled for the duration
 	 * to avoid interference.
 	 *
 	 * This is based on snmalloc's class of the same name.
 	 */
 	class LoaderWriter
 	{
 		/**
 		 * The capability to the UART device.
 		 */
 		static inline volatile Uart *uart16550;

 		/**
 		 * Append a character, delegating to `Output`.
 		 */
 		void append_char(char c)
 		{
 			uart16550->blocking_write(c);
 		}

 		/**
 		 * Append a null-terminated C string.
 		 */
 		void append(const char *str)
 		{
 			for (; *str; ++str)
 			{
 				append_char(*str);
 			}
 		}

 		/**
 		 * Append a string view.
 		 */
 		void append(std::string_view str)
 		{
 			for (char c : str)
 			{
 				append_char(c);
 			}
 		}

 		void append(char c)
 		{
 			append_char(c);
 		}

 		/**
 		 * Outputs the permission set using the format G RWcgml Xa SU0 as
 		 * described in [/docs/Debugging.md].
 		 */
 		void append(CHERI::PermissionSet permissions)
 		{
 			using namespace CHERI;
 			auto perm = [&](Permission p, char c) -> char {
 				if (permissions.contains(p))
 				{
 					return c;
 				}
 				return '-';
 			};
 			format("{} {}{}{}{}{}{} {}{} {}{}{}",
 			       perm(Permission::Global, 'G'),
 			       perm(Permission::Load, 'R'),
 			       perm(Permission::Store, 'W'),
 			       perm(Permission::LoadStoreCapability, 'c'),
 			       perm(Permission::LoadGlobal, 'g'),
 			       perm(Permission::LoadMutable, 'm'),
 			       perm(Permission::StoreLocal, 'l'),
 			       perm(Permission::Execute, 'X'),
 			       perm(Permission::AccessSystemRegisters, 'a'),
 			       perm(Permission::Seal, 'S'),
 			       perm(Permission::Unseal, 'U'),
 			       perm(Permission::User0, '0'));
 		}

 		/**
 		 * Append a raw pointer as a hex string.
 		 */
 		__noinline void append(const void *ptr)
 		{
 			const CHERI::Capability C{ptr};

 			format("{} (v:{} {}-{} l:{} o:{} p: {})",
 			       C.address(),
 			       C.is_valid(),
 			       C.base(),
 			       C.top(),
 			       C.length(),
 			       C.type(),
 			       C.permissions());
 		}

 		/**
 		 * Append a capability.
 		 */
 		template<typename T>
 		__always_inline void append(CHERI::Capability<T> capability)
 		{
 			append(static_cast<const void *>(capability.get()));
 		}

 		/**
 		 * Append a signed integer, as a decimal string.
 		 */
 		__noinline void append(int32_t s)
 		{
 			if (s < 0)
 			{
 				append_char('-');
 				s = 0 - s;
 			}
 			std::array<char, 10> buf;
 			const char           Digits[] = "0123456789";
 			for (int i = int(buf.size() - 1); i >= 0; i--)
 			{
 				buf.at(static_cast<size_t>(i)) = Digits[s % 10];
 				s /= 10;
 			}
 			bool skipZero = true;
 			for (auto c : buf)
 			{
 				if (skipZero && (c == '0'))
 				{
 					continue;
 				}
 				skipZero = false;
 				append_char(c);
 			}
 			if (skipZero)
 			{
 				append_char('0');
 			}
 		}

 		/**
 		 * Append a 32-bit unsigned integer to the buffer as hex with no prefix.
 		 */
 		__attribute__((noinline)) void append_hex_word(uint32_t s)
 		{
 			std::array<char, 8> buf;
 			const char          Hexdigits[] = "0123456789abcdef";
 			// Length of string including null terminator
 			static_assert(sizeof(Hexdigits) == 0x11);
 			for (long i = long(buf.size() - 1); i >= 0; i--)
 			{
 				buf.at(static_cast<size_t>(i)) = Hexdigits[s & 0xf];
 				s >>= 4;
 			}
 			bool skipZero = true;
 			for (auto c : buf)
 			{
 				if (skipZero && (c == '0'))
 				{
 					continue;
 				}
 				skipZero = false;
 				append_char(c);
 			}
 			if (skipZero)
 			{
 				append_char('0');
 			}
 		}

 		/**
 		 * Append a 32-bit unsigned integer to the buffer as hex.
 		 */
 		__attribute__((noinline)) void append(uint32_t s)
 		{
 			append_char('0');
 			append_char('x');
 			append_hex_word(s);
 		}

 		/**
 		 * Append a 64-bit unsigned integer to the buffer as hex.
 		 */
 		__attribute__((noinline)) void append(uint64_t s)
 		{
 			append_char('0');
 			append_char('x');
 			uint32_t hi = static_cast<uint32_t>(s >> 32);
 			uint32_t lo = static_cast<uint32_t>(s);
 			if (hi != 0)
 			{
 				append_hex_word(hi);
 			}
 			append_hex_word(lo);
 		}

 		/**
 		 * Append a 16-bit unsigned integer to the buffer as hex.
 		 */
 		__always_inline void append(uint16_t s)
 		{
 			append(static_cast<uint32_t>(s));
 		}

 		/**
 		 * Append an 8-bit unsigned integer to the buffer as hex.
 		 */
 		__always_inline void append(uint8_t s)
 		{
 			append(static_cast<uint32_t>(s));
 		}

 		/**
 		 * Append an enumerated type value.
 		 */
 		template<typename T>
 		requires DebugConcepts::IsEnum<T>
 		void append(T e)
 		{
 			// `magic_enum::enum_name` requires cap relocs, so don't use it in
 			// components that want or need to avoid them.
 			append(static_cast<int32_t>(e));
 		}

 		public:
 		/**
 		 * Base case for formatting: no format-string arguments.
 		 */
 		void format(const char *fmt)
 		{
 			append(fmt);
 		}

 		/**
 		 * Inductive case for formatting.  Writes up to the instruction to
 		 * output the first argument, writes that argument, and then recurses.
 		 */
 		template<typename T, typename... Args>
 		void format(const char *fmt, T firstArg, Args... args)
 		{
 			for (const char *s = fmt; *s != 0; ++s)
 			{
 				if (s[0] == '{' && s[1] == '}')
 				{
 					append(firstArg);
 					return format(s + 2, args...);
 				}

 				append_char(*s);
 			}
 		}

 		/**
 		 * Set the UART memory pointer.
 		 */
 		static void set_uart(volatile Uart *theUART)
 		{
 			uart16550 = theUART;
 		}
 	};

 	/**
 	 * Our libc++ does not currently provide source_location, but our clang
 	 * provides the necessary builtins for one.
 	 */
 	struct SourceLocation
 	{
 		/**
 		 * Explicitly construct a source location.
 		 */
 		constexpr SourceLocation(int         lineNumber,
 		                         int         columnNumber,
 		                         const char *fileName,
 		                         const char *functionName)
 		  : lineNumber(lineNumber),
 		    columnNumber(columnNumber),
 		    fileName(fileName),
 		    functionName(functionName)
 		{
 		}

 		/**
 		 * Construct a source location for the caller.
 		 */
 		static constexpr SourceLocation __always_inline
 		current(int         lineNumber   = __builtin_LINE(),
 		        int         columnNumber = __builtin_COLUMN(),
 		        const char *fileName     = __builtin_FILE(),
 		        const char *functionName = __builtin_FUNCTION()) noexcept
 		{
 			return {lineNumber, columnNumber, fileName, functionName};
 		}

 		/// Returns the line number for this source location.
 		[[nodiscard]] __always_inline constexpr int line() const noexcept
 		{
 			return lineNumber;
 		}
 		/// Returns the column number for this source location.
 		[[nodiscard]] __always_inline constexpr int column() const noexcept
 		{
 			return columnNumber;
 		}
 		/// Returns the file name for this source location.
 		[[nodiscard]] __always_inline constexpr const char *
 		file_name() const noexcept
 		{
 			return fileName;
 		}
 		/// Returns the function name for this source location.
 		[[nodiscard]] __always_inline constexpr const char *
 		function_name() const noexcept
 		{
 			return functionName;
 		}

 		private:
 		/// The line number of this source location.
 		int lineNumber;
 		/// The column number of this source location.
 		int columnNumber;
 		/// The file name of this source location.
 		const char *fileName;
 		/// The function name of this source location.
 		const char *functionName;
 	};

 	/**
 	 * Conditional debug class.  Used to control conditional output and
 	 * assertion checking.  Enables debug log messages and assertions if
 	 * `Enabled` is true.  Uses `Context` to print additional detail on debug
 	 * lines.  Writes output using `Writer`.
 	 *
 	 * If `DisableInterrupts` is true then this disables interrupts while
 	 * printing the message to avoid accidental interleaving.
 	 *
 	 * This class is expected to be used as a type alias, something like:
 	 *
 	 * ```c++
 	 * constexpr bool DebugFoo = DEBUG_FOO;
 	 * using Debug = ConditionalDebug<DebugFoo, "Foo">;
 	 * ```
 	 */
 	template<bool Enabled>
 	class LoaderDebug
 	{
 		public:
 		/// The (singleton) writer used for output.
 		static inline LoaderWriter writer;

 		/**
 		 * Log a message.
 		 *
 		 * This function does nothing if the `Enabled` condition is false.
 		 */
 		template<typename... Args>
 		static void log(const char *fmt, Args... args)
 		{
 			if constexpr (Enabled)
 			{
 				// Ensure that the compiler does not reorder messages.
 				asm volatile("" ::: "memory");
 				writer.format("\x1b[35mloader\033[0m");
 				writer.format(": ");
 				writer.format(fmt, args...);
 				writer.format("\n");
 				asm volatile("" ::: "memory");
 			}
 		}

 		/**
 		 * Helper to report failure.
 		 *
 		 * This must not take the `SourceLocation` directly because doing so
 		 * prevents the compiler from decomposing and subsequently
 		 * constant-propagating its fields in the caller, resulting in 24 bytes
 		 * of stack space consumed for every assert or invariant.
 		 */
 		template<typename... Args>
 		__noinline static void report_failure(const char *kind,
 		                                      const char *file,
 		                                      const char *function,
 		                                      int         line,
 		                                      const char *fmt,
 		                                      Args... args)
 		{
 			// Ensure that the compiler does not reorder messages.
 			asm volatile("" ::: "memory");
 			writer.format(
 			  "\x1b[35m{}:{} \x1b[31m{} failure\x1b[35m in {}\x1b[36m\n",
 			  file,
 			  line,
 			  kind,
 			  function);
 			writer.format(fmt, args...);
 			writer.format("\033[0m\n");
 			asm volatile("" ::: "memory");
 		}

 		/**
 		 * Function-like class for invariants that is expected to be used via
 		 * the deduction guide as:
 		 *
 		 * ConditionalDebug::Invariant(someCondition, "A message...", ...);
 		 *
 		 * Invariants are checked unconditionally but will log a verbose
 		 * message only if `Enabled` is true.
 		 */
 		template<typename... Args>
 		struct Invariant
 		{
 			/**
 			 * Constructor, performs the invariant check.
 			 */
 			__always_inline
 			Invariant(bool        condition,
 			          const char *fmt,
 			          Args... args,
 			          SourceLocation loc = SourceLocation::current())
 			{
 				if (!condition)
 				{
 					if constexpr (Enabled)
 					{
 						report_failure("Invariant",
 						               loc.file_name(),
 						               loc.function_name(),
 						               loc.line(),
 						               fmt,
 						               std::forward<Args>(args)...);
 					}
 					__builtin_trap();
 				}
 			}
 		};
 		/**
 		 * Function-like class for assertions that is expected to be used via
 		 * the deduction guide as:
 		 *
 		 * ConditionalDebug::Assert(someCondition, "A message...", ...);
 		 *
 		 * Assertions are checked only if `Enabled` is true.
 		 */
 		template<typename... Args>
 		struct Assert
 		{
 			/**
 			 * Constructor, performs the assertion check.
 			 */
 			template<typename T>
 			requires DebugConcepts::IsBool<T> __always_inline
 			Assert(T           condition,
 			       const char *fmt,
 			       Args... args,
 			       SourceLocation loc = SourceLocation::current())
 			{
 				if constexpr (Enabled)
 				{
 					if (!condition)
 					{
 						report_failure("Assertion",
 						               loc.file_name(),
 						               loc.function_name(),
 						               loc.line(),
 						               fmt,
 						               std::forward<Args>(args)...);
 						__builtin_trap();
 					}
 				}
 			}

 			/**
 			 * Constructor, performs an assertion check.
 			 *
 			 * This version is passed a lambda that returns a bool, rather than
 			 * a boolean condition.  This allows the compiler to completely
 			 * elide the contents of the lambda in builds where this component
 			 * is not being debugged.  This version should be used for places
 			 * where the assertion condition has side effects.
 			 */
 			template<typename T>
 			requires DebugConcepts::LazyAssertion<T> __always_inline
 			Assert(T         &&condition,
 			       const char *fmt,
 			       Args... args,
 			       SourceLocation loc = SourceLocation::current())
 			{
 				if constexpr (Enabled)
 				{
 					if (!condition())
 					{
 						report_failure("Assertion",
 						               loc.file_name(),
 						               loc.function_name(),
 						               loc.line(),
 						               fmt,
 						               std::forward<Args>(args)...);
 						__builtin_trap();
 					}
 				}
 			}
 		};

 		/**
 		 * Deduction guide, allows `Invariant` to be used as if it were a
 		 * function.
 		 */
 		template<typename T, typename... Ts>
 		Invariant(T, const char *, Ts &&...) -> Invariant<Ts...>;

 		/**
 		 * Deduction guide, allows `Assert` to be used as if it were a
 		 * function.
 		 */
 		template<typename... Ts>
 		Assert(bool, const char *, Ts &&...) -> Assert<Ts...>;

 		/**
 		 * Deduction guide, allows `Assert` to be used as if it were a
 		 * function with a lambda argument.
 		 */
 		template<typename... Ts>
 		Assert(auto, const char *, Ts &&...) -> Assert<Ts...>;
 	};

 	/**
 	 * Debug interface for the loader.  Enables verbose debugging if
 	 * `DebugLoader` is true and requires that the loader explicitly
 	 * initialises the UART.
 	 */
 	using Debug = LoaderDebug<DebugLoader>;
 } // namespace
	// Copyright Microsoft and CHERIoT Contributors.
	// SPDX-License-Identifier: MIT

	#pragma once
	#include <cheri.hh>
	#include <compartment.h>
	#include <platform-uart.hh>

	#include <array>

	namespace
	{
	/**
	* Is the loader being debugged?
	*/
	static constexpr bool DebugLoader = DEBUG_LOADER;

	namespace DebugConcepts
	{
	/// Helper concept for matching booleans
	template<typename T>
	concept IsBool = std::is_same_v<T, bool>;

	/// Helper concept for matching enumerations.
	template<typename T>
	concept IsEnum = std::is_enum_v<T>;

	/// Concept for something that can be lazily called to produce a bool.
	template<typename T>
	concept LazyAssertion = requires(T v)
	{
	{
	v()
	} -> IsBool;
	};
	} // namespace DebugConcepts

	/**
	* Helper class for writing debug output to the UART. This performs no
	* internal buffering and assumes interrupts are disabled for the duration
	* to avoid interference.
	*
	* This is based on snmalloc's class of the same name.
	*/
	class LoaderWriter
	{
	/**
	* The capability to the UART device.
	*/
	static inline volatile Uart *uart16550;

	/**
	* Append a character, delegating to `Output`.
	*/
	void append_char(char c)
	{
	uart16550->blocking_write(c);
	}

	/**
	* Append a null-terminated C string.
	*/
	void append(const char *str)
	{
	for (; *str; ++str)
	{
	append_char(*str);
	}
	}

	/**
	* Append a string view.
	*/
	void append(std::string_view str)
	{
	for (char c : str)
	{
	append_char(c);
	}
	}

	void append(char c)
	{
	append_char(c);
	}

	/**
	* Outputs the permission set using the format G RWcgml Xa SU0 as
	* described in [/docs/Debugging.md].
	*/
	void append(CHERI::PermissionSet permissions)
	{
	using namespace CHERI;
	auto perm = [&](Permission p, char c) -> char {
	if (permissions.contains(p))
	{
	return c;
	}
	return '-';
	};
	format("{} {}{}{}{}{}{} {}{} {}{}{}",
	perm(Permission::Global, 'G'),
	perm(Permission::Load, 'R'),
	perm(Permission::Store, 'W'),
	perm(Permission::LoadStoreCapability, 'c'),
	perm(Permission::LoadGlobal, 'g'),
	perm(Permission::LoadMutable, 'm'),
	perm(Permission::StoreLocal, 'l'),
	perm(Permission::Execute, 'X'),
	perm(Permission::AccessSystemRegisters, 'a'),
	perm(Permission::Seal, 'S'),
	perm(Permission::Unseal, 'U'),
	perm(Permission::User0, '0'));
	}

	/**
	* Append a raw pointer as a hex string.
	*/
	__noinline void append(const void *ptr)
	{
	const CHERI::Capability C{ptr};

	format("{} (v:{} {}-{} l:{} o:{} p: {})",
	C.address(),
	C.is_valid(),
	C.base(),
	C.top(),
	C.length(),
	C.type(),
	C.permissions());
	}

	/**
	* Append a capability.
	*/
	template<typename T>
	__always_inline void append(CHERI::Capability<T> capability)
	{
	append(static_cast<const void *>(capability.get()));
	}

	/**
	* Append a signed integer, as a decimal string.
	*/
	__noinline void append(int32_t s)
	{
	if (s < 0)
	{
	append_char('-');
	s = 0 - s;
	}
	std::array<char, 10> buf;
	const char Digits[] = "0123456789";
	for (int i = int(buf.size() - 1); i >= 0; i--)
	{
	buf.at(static_cast<size_t>(i)) = Digits[s % 10];
	s /= 10;
	}
	bool skipZero = true;
	for (auto c : buf)
	{
	if (skipZero && (c == '0'))
	{
	continue;
	}
	skipZero = false;
	append_char(c);
	}
	if (skipZero)
	{
	append_char('0');
	}
	}

	/**
	* Append a 32-bit unsigned integer to the buffer as hex with no prefix.
	*/
	__attribute__((noinline)) void append_hex_word(uint32_t s)
	{
	std::array<char, 8> buf;
	const char Hexdigits[] = "0123456789abcdef";
	// Length of string including null terminator
	static_assert(sizeof(Hexdigits) == 0x11);
	for (long i = long(buf.size() - 1); i >= 0; i--)
	{
	buf.at(static_cast<size_t>(i)) = Hexdigits[s & 0xf];
	s >>= 4;
	}
	bool skipZero = true;
	for (auto c : buf)
	{
	if (skipZero && (c == '0'))
	{
	continue;
	}
	skipZero = false;
	append_char(c);
	}
	if (skipZero)
	{
	append_char('0');
	}
	}

	/**
	* Append a 32-bit unsigned integer to the buffer as hex.
	*/
	__attribute__((noinline)) void append(uint32_t s)
	{
	append_char('0');
	append_char('x');
	append_hex_word(s);
	}

	/**
	* Append a 64-bit unsigned integer to the buffer as hex.
	*/
	__attribute__((noinline)) void append(uint64_t s)
	{
	append_char('0');
	append_char('x');
	uint32_t hi = static_cast<uint32_t>(s >> 32);
	uint32_t lo = static_cast<uint32_t>(s);
	if (hi != 0)
	{
	append_hex_word(hi);
	}
	append_hex_word(lo);
	}

	/**
	* Append a 16-bit unsigned integer to the buffer as hex.
	*/
	__always_inline void append(uint16_t s)
	{
	append(static_cast<uint32_t>(s));
	}

	/**
	* Append an 8-bit unsigned integer to the buffer as hex.
	*/
	__always_inline void append(uint8_t s)
	{
	append(static_cast<uint32_t>(s));
	}

	/**
	* Append an enumerated type value.
	*/
	template<typename T>
	requires DebugConcepts::IsEnum<T>
	void append(T e)
	{
	// `magic_enum::enum_name` requires cap relocs, so don't use it in
	// components that want or need to avoid them.
	append(static_cast<int32_t>(e));
	}

	public:
	/**
	* Base case for formatting: no format-string arguments.
	*/
	void format(const char *fmt)
	{
	append(fmt);
	}

	/**
	* Inductive case for formatting. Writes up to the instruction to
	* output the first argument, writes that argument, and then recurses.
	*/
	template<typename T, typename... Args>
	void format(const char *fmt, T firstArg, Args... args)
	{
	for (const char s = fmt; s != 0; ++s)
	{
	if (s[0] == '{' && s[1] == '}')
	{
	append(firstArg);
	return format(s + 2, args...);
	}

	append_char(*s);
	}
	}

	/**
	* Set the UART memory pointer.
	*/
	static void set_uart(volatile Uart *theUART)
	{
	uart16550 = theUART;
	}
	};

	/**
	* Our libc++ does not currently provide source_location, but our clang
	* provides the necessary builtins for one.
	*/
	struct SourceLocation
	{
	/**
	* Explicitly construct a source location.
	*/
	constexpr SourceLocation(int lineNumber,
	int columnNumber,
	const char *fileName,
	const char *functionName)
	: lineNumber(lineNumber),
	columnNumber(columnNumber),
	fileName(fileName),
	functionName(functionName)
	{
	}

	/**
	* Construct a source location for the caller.
	*/
	static constexpr SourceLocation __always_inline
	current(int lineNumber = __builtin_LINE(),
	int columnNumber = __builtin_COLUMN(),
	const char *fileName = __builtin_FILE(),
	const char *functionName = __builtin_FUNCTION()) noexcept
	{
	return {lineNumber, columnNumber, fileName, functionName};
	}

	/// Returns the line number for this source location.
	[[nodiscard]] __always_inline constexpr int line() const noexcept
	{
	return lineNumber;
	}
	/// Returns the column number for this source location.
	[[nodiscard]] __always_inline constexpr int column() const noexcept
	{
	return columnNumber;
	}
	/// Returns the file name for this source location.
	[[nodiscard]] __always_inline constexpr const char *
	file_name() const noexcept
	{
	return fileName;
	}
	/// Returns the function name for this source location.
	[[nodiscard]] __always_inline constexpr const char *
	function_name() const noexcept
	{
	return functionName;
	}

	private:
	/// The line number of this source location.
	int lineNumber;
	/// The column number of this source location.
	int columnNumber;
	/// The file name of this source location.
	const char *fileName;
	/// The function name of this source location.
	const char *functionName;
	};

	/**
	* Conditional debug class. Used to control conditional output and
	* assertion checking. Enables debug log messages and assertions if
	* `Enabled` is true. Uses `Context` to print additional detail on debug
	* lines. Writes output using `Writer`.
	*
	* If `DisableInterrupts` is true then this disables interrupts while
	* printing the message to avoid accidental interleaving.
	*
	* This class is expected to be used as a type alias, something like:
	*
	* ```c++
	* constexpr bool DebugFoo = DEBUG_FOO;
	* using Debug = ConditionalDebug<DebugFoo, "Foo">;
	* ```
	*/
	template<bool Enabled>
	class LoaderDebug
	{
	public:
	/// The (singleton) writer used for output.
	static inline LoaderWriter writer;

	/**
	* Log a message.
	*
	* This function does nothing if the `Enabled` condition is false.
	*/
	template<typename... Args>
	static void log(const char *fmt, Args... args)
	{
	if constexpr (Enabled)
	{
	// Ensure that the compiler does not reorder messages.
	asm volatile("" ::: "memory");
	writer.format("\x1b[35mloader\033[0m");
	writer.format(": ");
	writer.format(fmt, args...);
	writer.format("\n");
	asm volatile("" ::: "memory");
	}
	}

	/**
	* Helper to report failure.
	*
	* This must not take the `SourceLocation` directly because doing so
	* prevents the compiler from decomposing and subsequently
	* constant-propagating its fields in the caller, resulting in 24 bytes
	* of stack space consumed for every assert or invariant.
	*/
	template<typename... Args>
	__noinline static void report_failure(const char *kind,
	const char *file,
	const char *function,
	int line,
	const char *fmt,
	Args... args)
	{
	// Ensure that the compiler does not reorder messages.
	asm volatile("" ::: "memory");
	writer.format(
	"\x1b[35m{}:{} \x1b[31m{} failure\x1b[35m in {}\x1b[36m\n",
	file,
	line,
	kind,
	function);
	writer.format(fmt, args...);
	writer.format("\033[0m\n");
	asm volatile("" ::: "memory");
	}

	/**
	* Function-like class for invariants that is expected to be used via
	* the deduction guide as:
	*
	* ConditionalDebug::Invariant(someCondition, "A message...", ...);
	*
	* Invariants are checked unconditionally but will log a verbose
	* message only if `Enabled` is true.
	*/
	template<typename... Args>
	struct Invariant
	{
	/**
	* Constructor, performs the invariant check.
	*/
	__always_inline
	Invariant(bool condition,
	const char *fmt,
	Args... args,
	SourceLocation loc = SourceLocation::current())
	{
	if (!condition)
	{
	if constexpr (Enabled)
	{
	report_failure("Invariant",
	loc.file_name(),
	loc.function_name(),
	loc.line(),
	fmt,
	std::forward<Args>(args)...);
	}
	__builtin_trap();
	}
	}
	};
	/**
	* Function-like class for assertions that is expected to be used via
	* the deduction guide as:
	*
	* ConditionalDebug::Assert(someCondition, "A message...", ...);
	*
	* Assertions are checked only if `Enabled` is true.
	*/
	template<typename... Args>
	struct Assert
	{
	/**
	* Constructor, performs the assertion check.
	*/
	template<typename T>
	requires DebugConcepts::IsBool<T> __always_inline
	Assert(T condition,
	const char *fmt,
	Args... args,
	SourceLocation loc = SourceLocation::current())
	{
	if constexpr (Enabled)
	{
	if (!condition)
	{
	report_failure("Assertion",
	loc.file_name(),
	loc.function_name(),
	loc.line(),
	fmt,
	std::forward<Args>(args)...);
	__builtin_trap();
	}
	}
	}

	/**
	* Constructor, performs an assertion check.
	*
	* This version is passed a lambda that returns a bool, rather than
	* a boolean condition. This allows the compiler to completely
	* elide the contents of the lambda in builds where this component
	* is not being debugged. This version should be used for places
	* where the assertion condition has side effects.
	*/
	template<typename T>
	requires DebugConcepts::LazyAssertion<T> __always_inline
	Assert(T &&condition,
	const char *fmt,
	Args... args,
	SourceLocation loc = SourceLocation::current())
	{
	if constexpr (Enabled)
	{
	if (!condition())
	{
	report_failure("Assertion",
	loc.file_name(),
	loc.function_name(),
	loc.line(),
	fmt,
	std::forward<Args>(args)...);
	__builtin_trap();
	}
	}
	}
	};

	/**
	* Deduction guide, allows `Invariant` to be used as if it were a
	* function.
	*/
	template<typename T, typename... Ts>
	Invariant(T, const char *, Ts &&...) -> Invariant<Ts...>;

	/**
	* Deduction guide, allows `Assert` to be used as if it were a
	* function.
	*/
	template<typename... Ts>
	Assert(bool, const char *, Ts &&...) -> Assert<Ts...>;

	/**
	* Deduction guide, allows `Assert` to be used as if it were a
	* function with a lambda argument.
	*/
	template<typename... Ts>
	Assert(auto, const char *, Ts &&...) -> Assert<Ts...>;
	};

	/**
	* Debug interface for the loader. Enables verbose debugging if
	* `DebugLoader` is true and requires that the loader explicitly
	* initialises the UART.
	*/
	using Debug = LoaderDebug<DebugLoader>;
	} // namespace