-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update UART documentation for Raspberry Pi 5 #3294
Changes from 7 commits
f884ee7
b84cc86
ba6bac5
cdb2cbe
cf102db
5650fea
4e4f944
20b5f9e
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||
---|---|---|---|---|---|---|---|---|
|
@@ -18,9 +18,9 @@ The Raspberry Pi Zero, 1, 2, and 3 each contain two UARTs as follows: | |||||||
| mini UART | ||||||||
|=== | ||||||||
|
||||||||
=== Raspberry Pi 4 and 400 | ||||||||
=== Raspberry Pi 4 and 400 | ||||||||
|
||||||||
The Raspberry Pi 4B and 400 have an additional four PL011s, which are disabled by default: | ||||||||
The Raspberry Pi 4 Model B and 400 have an additional four PL011s, which are disabled by default: | ||||||||
|
||||||||
|=== | ||||||||
| Name | Type | ||||||||
|
@@ -44,6 +44,32 @@ The Raspberry Pi 4B and 400 have an additional four PL011s, which are disabled b | |||||||
| PL011 | ||||||||
|=== | ||||||||
|
||||||||
=== Raspberry Pi 5 | ||||||||
|
||||||||
The Raspberry Pi 5 has an additional four PL011s, which are disabled by default: | ||||||||
|
||||||||
|=== | ||||||||
| Name | Type | ||||||||
|
||||||||
| UART0 | ||||||||
| PL011 | ||||||||
|
||||||||
| UART1 | ||||||||
| PL011 | ||||||||
|
||||||||
| UART2 | ||||||||
| PL011 | ||||||||
|
||||||||
| UART3 | ||||||||
| PL011 | ||||||||
|
||||||||
| UART4 | ||||||||
| PL011 | ||||||||
|
||||||||
|=== | ||||||||
|
||||||||
The Raspberry Pi 5 does not have mini UART. | ||||||||
|
||||||||
=== CM1, CM3, CM3+ and CM4 | ||||||||
|
||||||||
The first generation Compute Module, together with Compute Module 3 and Compute Module 3+ each have two UARTs, while Compute Module 4 has six UARTs as described above. | ||||||||
|
@@ -58,47 +84,51 @@ dtoverlay=uart1,txd1_pin=32,rxd1_pin=33 | |||||||
|
||||||||
On the Raspberry Pi, one UART is selected to be present on GPIO 14 (transmit) and 15 (receive) - this is the primary UART. By default, this will also be the UART on which a Linux console may be present. Note that GPIO 14 is pin 8 on the GPIO header, while GPIO 15 is pin 10. | ||||||||
|
||||||||
On the Raspberry Pi 5, the primary UART appears on the Debug header. | ||||||||
|
||||||||
=== Secondary UART | ||||||||
|
||||||||
The secondary UART is not normally present on the GPIO connector. By default, the secondary UART is connected to the Bluetooth side of the combined wireless LAN/Bluetooth controller, on models which contain this controller. | ||||||||
|
||||||||
=== Primary and Secondary UART | ||||||||
|
||||||||
The following table summarises the assignment of the first two UARTs: | ||||||||
The following table summarises the assignment of UARTs on various Raspberry Pi devices: | ||||||||
|
||||||||
|=== | ||||||||
| Model | first PL011 (UART0) | mini UART | ||||||||
| Model | Primary/console | Secondary/Bluetooth | ||||||||
|
||||||||
| Raspberry Pi Zero | ||||||||
| primary | ||||||||
| secondary | ||||||||
| UART0 | ||||||||
| UART1 | ||||||||
|
||||||||
| Raspberry Pi Zero W / Raspberry Pi Zero 2 W | ||||||||
| secondary (Bluetooth) | ||||||||
| primary | ||||||||
| UART1 | ||||||||
| UART0 | ||||||||
|
||||||||
| Raspberry Pi 1 | ||||||||
| primary | ||||||||
| secondary | ||||||||
| UART0 | ||||||||
| UART1 | ||||||||
|
||||||||
| Raspberry Pi 2 | ||||||||
| primary | ||||||||
| secondary | ||||||||
| UART0 | ||||||||
| UART1 | ||||||||
|
||||||||
| Raspberry Pi 3 | ||||||||
| secondary (Bluetooth) | ||||||||
| primary | ||||||||
| UART1 | ||||||||
| UART0 | ||||||||
|
||||||||
| Compute Module 3 & 3+ | ||||||||
| primary | ||||||||
| secondary | ||||||||
| UART0 | ||||||||
| UART1 | ||||||||
|
||||||||
| Raspberry Pi 4 | ||||||||
| secondary (Bluetooth) | ||||||||
| primary | ||||||||
|=== | ||||||||
| UART1 | ||||||||
| UART0 | ||||||||
|
||||||||
NOTE: The mini UART is disabled by default, whether it is designated primary or secondary UART. | ||||||||
| Raspberry Pi 5 | ||||||||
| UART10 | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What is UART10? it is not mentioned in the table of UART0 -> UART4 above. This isn't super clear. Nor is it clear how this relates to settings like /boot/cmdline.txt - is this table defaults? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The information is there, just spread across multiple sections:
and:
and:
and:
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ok maybe to explain my confusion a bit more. I think firstly it's not clear that /dev/ttyAMAx refers to UARTx. And I'm still not clear which UART from the PL011 is being used for UART10 - or is it another UART altogether? "Raspberry Pi 5 has an additional four PL011s, which are disabled by default:" doesn't mention UART10 so it might be handy to do that? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. All the Pi 5 UARTs we use are PL011s. UARTs 0-4 are in the RP1 I/O chip, UART10 is in the BCM2712 SoC. |
||||||||
| <dedicated UART> | ||||||||
|=== | ||||||||
|
||||||||
Linux devices on Raspberry Pi OS: | ||||||||
|
||||||||
|
@@ -116,12 +146,26 @@ Linux devices on Raspberry Pi OS: | |||||||
|
||||||||
| `/dev/serial1` | ||||||||
| secondary UART | ||||||||
|
||||||||
| `/dev/ttyAMA10` | ||||||||
| Raspberry Pi 5 Debug UART | ||||||||
|=== | ||||||||
|
||||||||
NOTE: `/dev/serial0` and `/dev/serial1` are symbolic links which point to either `/dev/ttyS0` or `/dev/ttyAMA0`. | ||||||||
`/dev/serial0` and `/dev/serial1` are symbolic links which point to either `/dev/ttyS0` or `/dev/ttyAMA0`. | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. or There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Again I don't think I've ever seen us use the term "mini UART" There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It is a thing - the cut-down 8250 clone - and I'm sure some of my early documentation referred to it. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The 2711 datasheet refers to it as a mini UART. That's the terminology that we have always used. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fascinating. I've never heard anyone refer to it like that. But then I haven't seen the 2711 datasheet. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Okay. 🤷♂️ We're still not referring to it in the Pi 5 documentation as the mini UART though. Most people who read the Pi 5 online documentation have not read the BCM2711 datasheet. We've been referring to it as "the dedicated debug UART connector" so far. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The Pi 5 doesn't possess a mini UART, as I've already commented. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think Alasdair might be confusing what Phil and James are calling the "mini UART" (the cut-down 8250 clone in the SoCs for Pi0-4) which is also mentioned in https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-uarts , with the 3-pin debug UART connector on the Pi 5? (which I agree shouldn't be called a "mini UART"). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ah! I am indeed doing that. |
||||||||
|
||||||||
On the Raspberry Pi 5, `/dev/serial0` is a symbolic link that points to `/dev/ttyAMA10`. Due to changes in Bookworm, `/dev/serial1` does not exist by default on the Raspberry Pi 5. You can re-enable `serial1` by setting the following values in `config.txt`: | ||||||||
nathan-contino marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
|
||||||||
[source,bash] | ||||||||
---- | ||||||||
dtparam=krnbt=off | ||||||||
---- | ||||||||
|
||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||||||||
TIP: This option may not work on all models in the future. Only use this option if there is no other alternative for your use case. | ||||||||
|
||||||||
=== Mini-UART and CPU Core Frequency | ||||||||
|
||||||||
NOTE: The mini UART is disabled by default if it is the primary or when Bluetooth is disabled. | ||||||||
|
||||||||
In order to use the mini UART, you need to configure the Raspberry Pi to use a fixed VPU core clock frequency. This is because the mini UART clock is linked to the VPU core clock, so that when the core clock frequency changes, the UART baud rate will also change. The `enable_uart` and `core_freq` settings can be added to `config.txt` to change the behaviour of the mini UART. The following table summarises the possible combinations: | ||||||||
|
||||||||
|=== | ||||||||
|
@@ -171,6 +215,12 @@ By default, the primary UART is assigned to the Linux console. If you wish to us | |||||||
|
||||||||
Although the Linux kernel starts the UARTs relatively early in the boot process, it is still long after some critical bits of infrastructure have been set up. A failure in those early stages can be hard to diagnose without access to the kernel log messages from that time. To enable `earlycon` support for one of the UARTs, add one of the following options to `cmdline.txt`, depending on which UART is the primary: | ||||||||
|
||||||||
For Raspberry Pi 5, `earlycon` output only appears on the 3-pin debug connector with the following configuration: | ||||||||
|
||||||||
---- | ||||||||
earlycon=pl011,0x107d001000,115200n8 | ||||||||
---- | ||||||||
|
||||||||
For Raspberry Pi 4, 400 and Compute Module 4: | ||||||||
|
||||||||
---- | ||||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would take Pi 5 out of this table - it's Bluetooth is controlled by yet another UART, not previously discussed. It can't be used for anything else, and with the latest kernels it doesn't get a
/dev/tty*
entry, so it's almost as if it doesn't exist.Alternatively, change the table column headings to be Model, Primary, Secondary and put the UART numbers in each row (with a special note for Pi 5).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Change the column headings to "Primary/console" and "Secondary/Bluetooth". Drop the third column - it's all not needed (and mostly wrong).