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.