Serial Debugging

From 15h.org
Jump to navigation Jump to search
Pinouts for the RS-232 serial port

If you are developing or debugging coreboot, it is helpful to receive coreboot's console logs from the system as early as possible. Where available, the best option for this is serial debugging, using an RS-232 serial port - this is generally reliable and can become available very early in the boot process (in most cases, the only earlier diagnostic tool available will be POST codes). If you do not have a serial port, you can consider EHCI Debugging instead.

Tools

A serial slot bracket adapter

You will need:

  • The system you wish to debug
  • If your device has only an internal serial header, an appropriate serial breakout
  • A null modem serial cable, OR a straight-through serial cable and a null modem adapter. You cannot use a null modem cable AND a null modem adapter together.
  • Another device on which to view your logs (commonly a laptop)
  • If your other device does not have a built-in serial port, a USB-to-Serial adapter
  • A coreboot build configured to use a serial console. coreboot-15h builds and default configurations do this by default.

Usage

Begin with your console machine running and the system you are testing powered off.

If necessary, install your serial slot bracket adapter in your chassis. Many boards have housings around their headers which will prevent you from connecting the cable backwards. If your board does not have this, note that one edge of the adapter's cable should be colored red - that edge signifies Pin 1. Connect the header, covering all 9/10 pins, with the red edge pointing towards the header's Pin 1 (likely marked with a white box or dot printed on the board beside the pin, on the opposite end from the missing 10th pin in the corner). Plug the IDC connector onto the motherboard's lowest-numbered COM header (usually labeled COM or COM1).

Connect the serial cable from the system you are testing's serial port to your other device's serial port (or to your USB-to-serial adapter). Ordinarily, you can do this using a single female-to-female DE-9 null modem cable and no additional adapters, or a single female-to-female DE-9 straight-through cable and a null-modem adapter. If for some reason this is not practical, in theory, you can use any combination of serial cables and adapters that includes any odd number of null modems. Connect your USB-to-serial adapter to your console machine if needed.

Find out the path of your serial port. For USB serial devices, typically this will be something like /dev/ttyUSB0. For onboard serial ports, typically this will be something like /dev/ttyS1.

Start a serial console application. tio is a good command-line serial console tool, available on Linux and many other platforms. In the case of tio, you can launch it using, for example: 

tio /dev/ttyUSB0 -b 115200

This means connect to /dev/ttyUSB0, at 115,200 bits per second (the default bitrate used by coreboot console and many other things). Other serial port parameters (8 data bits/no parity/1 stop bit) should be correct by default.

You should see e.g. 

[15:10:51.502] tio 3.9
[15:10:51.502] Press ctrl-t q to quit
[15:10:51.503] Connected to /dev/ttyUSB0

Start the system you are testing. If your setup is configured correctly, you should see coreboot logs begin to appear on the console, e.g. 

coreboot-57e26bdcd9 Wed May 27 19:45:28 UTC 2026 romstage starting (log level: 6)...
...WARM RESET...


board_reset() called!
system_reset() called!


coreboot-57e26bdcd9 Wed May 27 19:45:28 UTC 2026 romstage starting (log level: 6)...
SPD: Socket 0, Channel 0, Dimm 0
SPD: Socket 0, Channel 0, Dimm 1
...

Internal Serial Headers

The DTK/Intel and AT/Everex serial header pinouts

If your machine has an external serial port, it virtually certainly uses the DE-9 Male DTE-side connector shown above (left, blue). If you have an internal serial port, you can use an adapter (typically in place of an an unused PCI slot's slot cover) to add one of these external connectors to your system. Unfortunately, while the external connector is standard, there are two incompatible common internal header pinouts - DTK/Intel and AT/Everex both using the same 10-pin 2.54mm-pitch IDC connector. You will need an adapter wired properly for the connector on your motherboard - most boards supported in coreboot-15h are AT/Everex, but you should check your manual before connecting an adapter to a motherboard of unknown pinout.

If you are purchasing an adapter, make sure the seller specifies which type it is, and that it matches which one you need. A seemingly-"defective" adapter, sold without a clearly-specified pinout, is sometimes simply the wrong pinout for your board.

But what IS a Null Modem?

A null modem adapter

RS-232 is a standard from the 1960s, and it was primarily designed for connecting communications equipment which would carry data a long distance (primarily modems) to the terminal equipment which the user operated (such as teletypes, terminals, and computers). As such, RS-232 defines two types of device - Data Communications Equipment (DCE) and Data Terminal Equipment (DTE), and ordinarily assumes you are using it to connect a DTE (like your computer) to a DCE (like a modem). Because they were intended to connect to computers (DTEs), RS-232 peripherals which were not "communications" devices (serial mice, printers, cameras, etc) were also wired as DCEs.

Any two RS-232 devices - DCE or DTE - can communicate, provided one's RX (Receive) pin is wired to the other's TX (Transmit) pin, and vice-versa. The difference between DCE and DTE is simply that where a DCE's connector has its TX pin, the DTE's connector has its RX pin, and vice-versa. This means that a simple straight-through cable (pin 1 to pin 1, pin 2 to pin 2, etc.) will work to connect a DCE to a DTE.

You, however, are not connecting a modem to your computer - you're connecting a computer (running coreboot, to debug) to your computer (where you will view the logs). Since these are both DTEs, this will not work with a straight-through cable - you need a null modem, which is simply an adapter that swaps the RX and TX pins, allowing two DTEs or two DCEs to communicate with eachother despite their RX/TX wiring. The adapter is a "modem" in the sense that RS-232 assumes that a pair of DTEs (computers) will always communicate through a pair of DCEs (their respective modems, via the network connecting the modems), and the adapter's wiring provides the RX/TX swap that these back-to-back modems would.

To add to the confusion, some cables are themselves wired as a null modem, and serial cables are frequently not labelled as either straight-through or null-modem. Two null modems in a row acts as a straight-through cable - if you have a null modem cable, you should NOT use a null modem adapter between two DTEs (i.e. for coreboot debugging). Some null modem adapters and cables also cross the hardware flow control pins of the serial ports. Hardware flow control is generally unused in coreboot debugging, and the presence or lack of this functionality can generally be ignored.

External RS-232 ports on "modern" (post-1996-ish) PCs are typically male DE-9 connectors, but DCE and DTE have nothing to do with male and female connectors - either device can have either type of connector, and cables and adapters are available in all combinations.

Compatibility

Serial debugging can be used on most motherboards with a serial port in their rear I/O, or on a serial header. However, on some motherboards (particularly those with BMCs), the external serial port(s) may not be usable for coreboot console, or may work only when the BMC is enabled and running.

The following boards are known to have WORKING serial coreboot console:

The following boards are known to have BROKEN serial coreboot console:

If your board is not listed here, find it on the Motherboards page and consult its own wiki page. In general, motherboards which have an officially-documented serial port (external or internal), which do not have a BMC, and which use an ordinary Super I/O (as opposed to a laptop-style EC), will almost always have a working serial console.

Retrieved from "https://15h.org/index.php?title=Serial_Debugging&oldid=3149"