doc: document serial port usage for debugging

doc/debug/serial.rst

@@ -0,0 +1,41 @@
+SERIAL PORT DEBUGGING
+=====================
+
+On x86_64 machines, the kernel writes all printk messages to the COM1 serial port as well as
+the VGA display. The serial port baud rate is set in `arch/x86_64/init.c` with a call to
+`serialcon_init()`. Right now, the default baud rate for the serial console is 115200.
+
+
+VIRTUAL MACHINE
+---------------
+
+When running under QEMU, you can redirect the serial output in the following ways.
+
+1. To standard out: `-serial stdio`
+2. To a file: `-serial file:<PATH>`
+
+
+REAL MACHINE
+------------
+
+If your test machine has a serial port, you can connect to it to get kernel log messages.
+On your monitoring machine (a machine running something Linux-like, connected to the test machine
+via serial cable), you can use `screen` to communicate two-way with the test machine over serial.
+
+If your monitoring machine *also* has a serial port, and the two machines are connected via their
+builtin serial ports, you can use the following command on the monitoring machine to establish
+a connection:
+
+`screen /dev/ttySxxx <BAUD RATE>`
+
+If you are using a USB-to-serial adapter on the monitoring machine, you should use this command
+instead:
+
+`screen /dev/ttyUSBxxx <BAUD RATE>`
+
+Notes:
+ * `xxx` is the ID of the serial port tty.
+ * <BAUD RATE> needs to be the same as that being used by the kernel (see above),
+   otherwise you will get garbage data.
+ * Your user account needs to be a member of the `dialout` group, otherwise you
+   will need to use `sudo`.