From 36834c26b87ad6dcae1f5cc204aa32d699f2e89b Mon Sep 17 00:00:00 2001 From: Max Wash Date: Sun, 7 May 2023 12:37:39 +0100 Subject: [PATCH] doc: document serial port usage for debugging --- doc/debug/serial.rst | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 doc/debug/serial.rst diff --git a/doc/debug/serial.rst b/doc/debug/serial.rst new file mode 100644 index 0000000..82dcf09 --- /dev/null +++ b/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:` + + +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 ` + +If you are using a USB-to-serial adapter on the monitoring machine, you should use this command +instead: + +`screen /dev/ttyUSBxxx ` + +Notes: + * `xxx` is the ID of the serial port tty. + * 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`.