Need to update UART documentation for Pi5

[metachip]

The existing documentation makes no mention of Pi5 or how it differs in terms of UART usage and we've reported at least one new bug (affecting older models but introduced by code changes to support Pi5). While we get the big picture apropos the new connector (all good!) it appears the logical meaning or intended usage of the alias names (serial0 and serial1) and the confounding bluetooth complexities of the past may be changed in Pi5, or there are unresolved bugs, or both?

For example, on Pi4 with bullseye, specifying console=serial0,115200 in cmdline.txt when uart_enable=1 and/or dtoverlay=disable-bt is asserted in config.txt results in serial0 being linked as primary (i.e. ttyAMA0) and the console being enabled on pins 14/15 on J8 enabling firmware boot and kernel messages on boot and the system console via the J8 pins. In terms of aliases we have /dev/serial0 -> ttyAMA0 and /dev/serial1 -> ttyS0. All good.

Not so on Pi5.

Instead on Pi5 with bookworm this configuration seems to enable all this on new UART connector. A different setup is needed to replicate backward compatible behaviour which setup seems to be: specify console=ttyAMA0,115200 in cmdline.txt when dtparam=uart0=on is asserted in config.txt. All good, but confusing as now /dev/serial0 -> ttyAMA10 where (I'm guessing ttyAMA10 is the new port) and /dev/serial1 is not assigned at all? If we also assert dtoverlay=disable-bt in config.txt we get aliases /dev/serial0 -> ttyAMA10 and /dev/serial1 -> ttyS0.

So there are changes and bugs here and we're having difficulty disambiguating between them.

Bottom line: updated documentation so we know what the intended behaviour is, even if bugs may get in the way :)

[aallan]

You can expect the documentation to be updated to cover Pi 5 over the next few months. If you're interested you can keep track of what's going on by looking at the project milestone.

[pelwell]

It's unfortunate that Bookworm launched with a bug in the serial port alias handling, but it should be fixed now - there is no need to document it.

As to the main questions:

• serial0 is meant to be an alias for the "main" UART. On all Pis before Pi 5 this is obviously the UART enabled on GPIOs 14 & 15 (pins 8 & 10). This is the UART that a serial console would be enabled on (if wanted) by the console=serial0,115200 in cmdline.txt. Pi 5 changes this by making the UART on the 3-pin debug header the default for serial0 - /dev/ttyAMA10. You can override this behaviour with dtparam=uart0_console, which enables UART0 and makes serial0 an alias for it.
• serial1 is an alias for the UART used for Bluetooth, which is not accessible on the 40-pin header. However, on Bookworm (more accurately, since the newer 6.1 kernels) the kernel configures the UART for Bluetooth in a way that it has no /dev/tty... entry. As a result there is no /dev/serial1. N.B. It is still possible to revert to the old behaviour using dtparam=krnbt=off, but this isn't guaranteed to work forever.

[pfrankw]

Hi,

sorry to bump this but there is no trace of these directives on the documentation as of today and I found the documentation to be confusing as pointed out by other users.

I recently bought a Raspberry Pi 5 and had to install RPi OS and to run raspi-config in order to see that dtparam=uart0=on was needed to enable UART0 (GPIO's UART). I was not able to find this on the documentation.

Finally I had to modify the cmdline.txt by adding console=ttyAMA0,115200 in order to interact with the Pi's console via GPIO's UART.

From reading the documentation I thought it was only needed enable_uart=1 on the config.txt to enable the UART:

I don't often install Raspberry Pi OS and had to rely heavily on documentation, which took me hours to figure out the correct directive for config.txt. I shared the whole process to save others time.

Thank you.

[pelwell]

You're partially correct in that, if you want to use the UART on the 40-pin GPIO header (pins 8 & 10) on a Pi 5 then you do need to add dtparam=uart0 to config.txt. If you also want to log in using that UART then use dtparam=uart0_console (either as well as or instead of dtparam=uart0).

Where you're not quite correct is that cmdline.txt should really have console=serial0,115200, which is better than console=ttyAMA0,115200 because it also works with the debug UART. The instructions already mention console=serial0, but they should be amended to include the explicit baudrate so that they work in all cases.

[nathan-contino]

Thanks for bumping this, @pfrankw, and thanks for the info, @pelwell. I'll get this info into the docs today.

[nathan-contino]

Added the baudrate. If anyone requires additional changes to the UART docs for Pi 5, please open a separate issue with your request.

[hnamtran]

You're partially correct in that, if you want to use the UART on the 40-pin GPIO header (pins 8 & 10) on a Pi 5 then you do need to add dtparam=uart0 to config.txt. If you also want to log in using that UART then use dtparam=uart0_console (either as well as or instead of dtparam=uart0).

Where you're not quite correct is that cmdline.txt should really have console=serial0,115200, which is better than console=ttyAMA0,115200 because it also works with the debug UART. The instructions already mention console=serial0, but they should be amended to include the explicit baudrate so that they work in all cases.

Hello, I have bought a Raspberry Pi 5 recently and I had exactly the same issue mentioned by @pfrankw. I only got it resolved when I put "console=ttyAMA0,115200" in cmdline.txt. The same configuration did not work with "console=serial0,115200"

[lurch]

@hnamtran I think that if you upgrade your Pi 5 to the latest rpi-eeprom firmware, then console=serial0,115200 will work?

The way I understand it (and I'm sure that @pelwell will correct me if I'm wrong) is that on "older" versions of the Pi 5 firmware, serial0 pointed at the UART connected to the 3-pin debug-header on the Pi 5. But with newer versions of the firmware, if no connection is detected on the debug-header then serial0 will be relocated to GPIO14 and GPIO15 on the 40-pin header, for compatibility with earlier models of Raspberry Pi (that didn't have a 3-pin debug header).

[pelwell]

if no connection is detected on the debug-header then serial0 will be relocated to GPIO14 and GPIO15 on the 40-pin header

No - that's only with enable_uart=1 in config.txt.