Document amd64 platform-specific code

kernel/amd64/debug.c

@@ -6,21 +6,29 @@
 #include <sync/spin_lock.h>
 #include <sys/debug.h>
 
-#define PORT_COM1   0x03F8
+/// Port for printing to serial
+#define PORT_COM1 0x03F8
+/// \ref debugprintf buffer size
 #define BUFFER_SIZE 1024
+/// Lock, which ensures that prints to the serial port are atomic
+static spin_lock_t serial_lock = SPIN_LOCK_INIT;
 
-spin_lock_t serial_lock = SPIN_LOCK_INIT;
-
+/// Block until TX buffer is empty
 static bool amd64_debug_serial_tx_empty (void) {
   return (bool)(amd64_io_inb (PORT_COM1 + 5) & 0x20);
 }
 
+/// Write a single character to serial
 static void amd64_debug_serial_write (char x) {
   while (!amd64_debug_serial_tx_empty ())
     ;
   amd64_io_outb (PORT_COM1, (uint8_t)x);
 }
 
+/**
+ * @brief Formatted printing to serial. \ref serial_lock ensures that
+ * all prints are atomic.
+ */
 void debugprintf (const char* fmt, ...) {
   char buffer[BUFFER_SIZE];
   memset (buffer, 0, sizeof (buffer));
@@ -44,6 +52,7 @@ void debugprintf (const char* fmt, ...) {
   spin_unlock (&serial_lock);
 }
 
+/// Initialize serial
 void amd64_debug_init (void) {
   amd64_io_outb (PORT_COM1 + 1, 0x00);
   amd64_io_outb (PORT_COM1 + 3, 0x80);