Document format module

srv/debug.c

@@ -11,6 +11,8 @@
 #include "dma_mbuf.h"
 #include "format.h"
 
+#if DEBUG_TRACE || DEBUG_WARN || DEBUG_ERROR
+
 
 //--local definitions-----------------------------------------------------------
 
@@ -27,8 +29,6 @@ static uint8_t tx_buffer[BUFFER_SIZE];
 
 //--public functions------------------------------------------------------------
 
-#if DEBUG_TRACE || DEBUG_WARN || DEBUG_ERROR
-
 void _debug_init(enum UsartPeriph usart, enum GpioPort tx_port,
 		enum GpioPin tx_pin)
 {
@@ -45,16 +45,12 @@ void _debug_init(enum UsartPeriph usart, enum GpioPort tx_port,
 	debug_trace("------------------------------------------------------------------------------\n");
 }
 
-#endif
-
-#if DEBUG_TRACE
-
-void _debug_trace(char* format, ...)
+void _debug_print(const char* restrict header,
+		const char* restrict format, ...)
 {
-	write_debug('T', nullptr);
-	write_debug(':', nullptr);
 	va_list va;
 	va_start(va, format);
+	format_vfctprintf(write_debug, nullptr, header, va);
 	format_vfctprintf(write_debug, nullptr, format, va);
 	va_end(va);
 	write_debug('\n', nullptr);
@@ -63,40 +59,16 @@ void _debug_trace(char* format, ...)
 	while (dma_mbuf_switch(&mbuf)) {}
 }
 
-#endif
-
-#if DEBUG_WARN
-
-void _debug_warn(char* format, ...)
-{
-	print_debug("W:");
-	print_debug(format);
-
-	//ensure everything is written when done
-	while (dma_mbuf_switch(&mbuf)) {}
-}
-
-#endif
-
-#if DEBUG_ERROR
-
-void _debug_error(char* format, ...)
-{
-	print_debug("E:");
-	print_debug(format);
-
-	//ensure everything is written when done
-	while (dma_mbuf_switch(&mbuf)) {}
-}
-
-#endif
 
 //--local functions-------------------------------------------------------------
 
-#if DEBUG_TRACE || DEBUG_WARN || DEBUG_ERROR
-
+/**
+ * Callback to use with format_vfctprintf() to print caracters to the debug port
+ */
 static uint32_t write_debug(uint8_t c, void* arg)
 {
+	(void)arg; //unused, required because of FormatCallback
+
 	while (dma_mbuf_write_byte(&mbuf, c))
 	{
 		//buffer is full, wait until transfer started
@@ -106,5 +78,5 @@ static uint32_t write_debug(uint8_t c, void* arg)
 	return 0;
 }
 
-#endif
+#endif //DEBUG_TRACE || DEBUG_WARN || DEBUG_ERROR
 

srv/debug.h

@@ -14,8 +14,8 @@
 #include "../drv/gpio.h"
 
 #define DEBUG_TRACE 1
-#define DEBUG_WARN 0
-#define DEBUG_ERROR 0
+#define DEBUG_WARN 1
+#define DEBUG_ERROR 1
 
 
 //--type definitions------------------------------------------------------------
@@ -27,19 +27,40 @@
 #endif
 
 #if DEBUG_TRACE
-#define debug_trace(format, ...) _debug_trace(format __VA_OPT__(,) __VA_ARGS__)
+/**
+ * Prints a trace message on the debug port. This function should return
+ * immediately, provided that the message's length doesn't exceed 80 caracters
+ * and that it isn't called in very quick succession. Otherwise, it will block
+ * until the internal buffering system is ready to accept the message
+ */
+#define debug_trace(format, ...) _debug_print("T:", \
+		format __VA_OPT__(,) __VA_ARGS__)
 #else
 #define debug_trace(format, ...) do {} while (0)
 #endif
 
 #if DEBUG_WARN
-#define debug_warn(format, ...) _debug_warn(format __VA_OPT__(,) __VA_ARGS__)
+/**
+ * Prints a warning message on the debug port. This function should return
+ * immediately, provided that the message's length doesn't exceed 80 caracters
+ * and that it isn't called in very quick succession. Otherwise, it will block
+ * until the internal buffering system is ready to accept the message
+ */
+#define debug_warn(format, ...) _debug_print("W:", \
+		format __VA_OPT__(,) __VA_ARGS__)
 #else
 #define debug_warn(format, ...) do {} while (0)
 #endif
 
 #if DEBUG_ERROR
-#define debug_error(format, ...) _debug_error(format __VA_OPT__(,) __VA_ARGS__)
+/**
+ * Prints an error message on the debug port. This function should return
+ * immediately, provided that the message's length doesn't exceed 80 caracters
+ * and that it isn't called in very quick succession. Otherwise, it will block
+ * until the internal buffering system is ready to accept the message
+ */
+#define debug_error(format, ...) _debug_print("E:", \
+		format __VA_OPT__(,) __VA_ARGS__)
 #else
 #define debug_error(format, ...) do {} while (0)
 #endif
@@ -47,12 +68,30 @@
 
 //--functions-------------------------------------------------------------------
 
+#if DEBUG_TRACE || DEBUG_WARN || DEBUG_ERROR
+
+/**
+ * Initializes the debug system to use the given usart peripheral on the given
+ * tx port, printing a banner if traces are enabled.
+ * The usart doesn't need to be configured, neither does the tx port.
+ *
+ * This function shouldn't be called directly. Instead, use the debug_init macro
+ */
 void _debug_init(enum UsartPeriph usart, enum GpioPort tx_port,
 		enum GpioPin tx_pin);
-void _debug_trace(char* format, ...);
-void _debug_warn(char* format, ...);
-void _debug_error(char* format, ...);
 
+/**
+ * Prints a debug message on the debug port with the given header. This function
+ * should return immediately, provided that the message's length doesn't exceed
+ * 80 caracters and that it isn't called in very quick succession. Otherwise, it
+ * will block until the internal buffering system is ready to accept the message
+ *
+ * This function shouldn't be called directly. Instead, use the debug macros
+ */
+void _debug_print(const char* restrict header,
+		const char* restrict format, ...);
+
+#endif
 
 #endif //_DEBUG_H_
 

srv/format.c

@@ -57,8 +57,15 @@ uint32_t format_vfctprintf(FormatCallback callback, void* arg,
 	return render_format(callback, arg, format, va);
 }
 
+
 //--local functions-------------------------------------------------------------
 
+/**
+ * FormatCallback to write into a regular buffer. A pointer to BufferArg shall
+ * be passed as arg.
+ *
+ * Returns 0 if everything went as expected, 1 otherwise
+ */
 static uint32_t buffer_write(uint8_t byte, void* arg)
 {
 	struct BufferArg* buffer_arg = (struct BufferArg*)arg;
@@ -71,6 +78,12 @@ static uint32_t buffer_write(uint8_t byte, void* arg)
 	return 0;
 }
 
+/**
+ * Renders the given format to the output defined by the provided callback,
+ * formatting accordingly the provided arguments
+ *
+ * Returns 0 if everything went as expected, 1 otherwise
+ */
 static uint32_t render_format(FormatCallback callback, void* arg,
 		const char* restrict format, va_list va)
 {
@@ -157,6 +170,12 @@ static uint32_t render_format(FormatCallback callback, void* arg,
 	return 0;
 }
 
+/**
+ * Formats a signed integer and renders it to the output defined by the provided
+ * callback
+ *
+ * Returns 0 if everything went as expected, 1 otherwise
+ */
 static uint32_t render_signed(FormatCallback callback, void* arg,
 		int32_t number, uint8_t base, uint8_t width)
 {
@@ -195,6 +214,12 @@ static uint32_t render_signed(FormatCallback callback, void* arg,
 	return render_unsigned(callback, arg, (uint32_t)number, base, 0, false);
 }
 
+/**
+ * Formats an unsigned integer and renders it to the output defined by the
+ * provided callback
+ *
+ * Returns 0 if everything went as expected, 1 otherwise
+ */
 static uint32_t render_unsigned(FormatCallback callback, void* arg,
 		 uint32_t number, uint8_t base, uint8_t width, bool zero_padding)
 {
@@ -237,3 +262,4 @@ static uint32_t render_unsigned(FormatCallback callback, void* arg,
 
 	return 0;
 }
+

srv/format.h

@@ -20,12 +20,36 @@ typedef uint32_t (*FormatCallback)(uint8_t byte, void* arg);
 
 //--functions-------------------------------------------------------------------
 
+/**
+ * Custom implementation of snprintf. Print the given format into the given
+ * buffer with the attached arguments properly formated.
+ *
+ * This function only provided a minimal subset of the standard library's
+ * snprintf : %c, %s, %i, %d, %x as well as right-justified padding for %d and
+ * %x
+ *
+ * Returns 0 if everything went as expected, 1 otherwise
+ */
 uint32_t format_snprintf(char* restrict buffer, uint32_t buffer_size,
 		const char* restrict format, ...);
 
+/**
+ * Custom implementation of fprintf using a callback instead of a file pointer.
+ * Print the given format using the given callback with the attached arguments
+ * properly formated.
+ *
+ * This function only provided a minimal subset of the standard library's
+ * snprintf : %c, %s, %i, %d, %x as well as right-justified padding for %d and
+ * %x
+ *
+ * Returns 0 if everything went as expected, 1 otherwise
+ */
 uint32_t format_fctprintf(FormatCallback callback, void* arg,
 		const char* restrict format, ...);
 
+/**
+ * Variadic variation of format_fctprintf(), see the later for more information
+ */
 uint32_t format_vfctprintf(FormatCallback callback, void* arg,
 		const char* restrict format, va_list va);