Update UART documentation for Raspberry Pi 5 #3294

nathan-contino · 2023-11-22T22:14:12Z

closes Need to update UART documentation for Pi5 #3239

@pelwell , I would appreciate a sanity check to make sure that these changes are correct. I am no UART expert.

pelwell

I found a few things. This may not be an exhaustive list, but I'll struggle to see more until these are fixed.

pelwell · 2023-11-23T09:46:54Z

documentation/asciidoc/computers/configuration/uart.adoc

@@ -4,6 +4,32 @@ There are two types of UART available on the Raspberry Pi -  http://infocenter.a

 All UARTs on the Raspberry Pi are 3.3V only - damage will occur if they are connected to 5V systems. An adaptor can be used to connect to 5V systems. Alternatively, low-cost USB to 3.3V serial adaptors are available from various third parties.

+=== Raspberry Pi 5
+
+On the Raspberry Pi 5, the primary UART is the mini UART port. The Raspberry Pi 5 also has an additional four PL011s, which are disabled by default:


No - on Pi 5 the default primary UART is UART10 (on the 3-pin Debug connector).

And there are 4 additional PL011 UARTs, disabled by default, but they are labelled UART1 to UART4.

pelwell · 2023-11-23T09:58:58Z

documentation/asciidoc/computers/configuration/uart.adoc

@@ -118,7 +148,14 @@ Linux devices on Raspberry Pi OS:
 | secondary 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`.


or /dev/ttyAMA10 on Pi 5.

pelwell · 2023-11-23T10:01:47Z

documentation/asciidoc/computers/configuration/uart.adoc

+
+| Raspberry Pi 5
+| secondary (Bluetooth)
+| primary
 |===

 NOTE: The mini UART is disabled by default, whether it is designated primary or secondary UART.


No - only if it is the primary, or if Bluetooth is disabled.

pelwell · 2023-11-23T10:05:27Z

documentation/asciidoc/computers/configuration/uart.adoc

@@ -96,6 +122,10 @@ The following table summarises the assignment of the first two UARTs:
 | Raspberry Pi 4
 | secondary (Bluetooth)
 | primary
+


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).

Change the column headings to "Primary/console" and "Secondary/Bluetooth". Drop the third column - it's all not needed (and mostly wrong).

pelwell · 2023-11-23T10:12:06Z

documentation/asciidoc/computers/configuration/uart.adoc

+[source,bash]
+----
+dtparam=krnbt=off
+----



However, this is not recommended, and the option may not work on all models in future.

pelwell · 2023-11-23T10:26:51Z

documentation/asciidoc/computers/configuration/uart.adoc

@@ -171,7 +208,7 @@ 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 4, 400 and Compute Module 4:
+For Raspberry Pi 5, 4, 400 and Compute Module 4:


No - Pi 5 is different. The earlycon output only appears on the 3-pin Debug connector, and the magic runes are:

earlycon=pl011,0x107d001000,115200n8

aallan · 2023-11-23T10:45:16Z

documentation/asciidoc/computers/configuration/uart.adoc

@@ -4,6 +4,32 @@ There are two types of UART available on the Raspberry Pi -  http://infocenter.a

 All UARTs on the Raspberry Pi are 3.3V only - damage will occur if they are connected to 5V systems. An adaptor can be used to connect to 5V systems. Alternatively, low-cost USB to 3.3V serial adaptors are available from various third parties.

+=== Raspberry Pi 5
+
+On the Raspberry Pi 5, the primary UART is the mini UART port. The Raspberry Pi 5 also has an additional four PL011s, which are disabled by default:


I don't think we've ever referred to this as "mini UART port" anywhere?

aallan · 2023-11-23T10:45:55Z

documentation/asciidoc/computers/configuration/uart.adoc

@@ -118,7 +148,14 @@ Linux devices on Raspberry Pi OS:
 | secondary 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`.


Again I don't think I've ever seen us use the term "mini UART"

It is a thing - the cut-down 8250 clone - and I'm sure some of my early documentation referred to it.

The 2711 datasheet refers to it as a mini UART. That's the terminology that we have always used.

Fascinating. I've never heard anyone refer to it like that. But then I haven't seen the 2711 datasheet.

See page 10 of https://datasheets.raspberrypi.com/bcm2711/bcm2711-peripherals.pdf

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.

The Pi 5 doesn't possess a mini UART, as I've already commented.

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").

Ah! I am indeed doing that.

nathan-contino · 2023-11-27T14:41:19Z

@pelwell I would appreciate a glance at the latest changes. In particular, the new UART table summarizing primary, secondary and Bluetooth. Given the new setup, I'm not sure if we have a good value to use for the Bluetooth column in the Pi 5 row -- maybe you can think of a reasonable value or a decent note.

pelwell

That's looking much better - just a few remaining issues.

pelwell · 2023-11-27T16:10:48Z

documentation/asciidoc/computers/configuration/uart.adoc

@@ -4,6 +4,30 @@ There are two types of UART available on the Raspberry Pi -  http://infocenter.a

 All UARTs on the Raspberry Pi are 3.3V only - damage will occur if they are connected to 5V systems. An adaptor can be used to connect to 5V systems. Alternatively, low-cost USB to 3.3V serial adaptors are available from various third parties.

+=== Raspberry Pi 5


The "additional" comment makes more sense after the Pi 0-3 section (and after Pi 4 is more logical), and we should mention that the mini-UART has gone.

And this comment?

I moved the section and added a note about the mini UART.

pelwell · 2023-11-27T16:14:38Z

documentation/asciidoc/computers/configuration/uart.adoc

@@ -96,6 +122,10 @@ The following table summarises the assignment of the first two UARTs:
 | Raspberry Pi 4
 | secondary (Bluetooth)
 | primary
+


Change the column headings to "Primary/console" and "Secondary/Bluetooth". Drop the third column - it's all not needed (and mostly wrong).

documentation/asciidoc/computers/configuration/uart.adoc

pelwell · 2023-11-27T16:17:00Z

documentation/asciidoc/computers/configuration/uart.adoc

+dtparam=krnbt=off
+----
+
+TIP: This option may not work on all models in the future.


"This option is almost certainly not what you really want, and may not work on all models in the future."

aallan · 2023-11-27T16:41:31Z

Ready to merge @nathan-contino @pelwell ?

pelwell · 2023-11-27T16:49:00Z

Not yet - the Primary/Secondary table still has a Bluetooth column, for a start.

nathan-contino · 2023-11-27T16:49:20Z

Updated as per your recommendations. Check again -- I just pushed it a minute ago.

pelwell · 2023-11-27T17:48:56Z

Sorry - 3 more changes, then I think we're done:

The initial description of the Primary UART has to mention that it appears on the Debug header on Pi 5.
The Pi 5 line in the Model/Primary/Secondory table should say something like:
```
Raspberry Pi 5 | UART10 | <dedicated UART>
```
In the Linux device/Description table, add ttyAMA10 as the Pi 5 Debug UART

nathan-contino · 2023-11-27T17:55:12Z

Thanks @pelwell, updated!

documentation/asciidoc/computers/configuration/uart.adoc

nathan-contino · 2023-11-28T13:28:22Z

@aallan should be good to go now.

aallan · 2023-11-29T10:40:00Z

Thanks @pelwell !

samskiter · 2024-02-28T09:53:46Z

documentation/asciidoc/computers/configuration/uart.adoc


-NOTE: The mini UART is disabled by default, whether it is designated primary or secondary UART.
+| Raspberry Pi 5
+| UART10


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?

The information is there, just spread across multiple sections:

On the Raspberry Pi 5, the primary UART appears on the Debug header.

and:

Model Primary Secondary

Raspberry Pi 5 UART10 dedicated UART

and:

/dev/ttyAMA10 | Raspberry Pi 5 Debug UART

and:

On the Raspberry Pi 5, /dev/serial0 is a symbolic link that points to /dev/ttyAMA10

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?

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.

Update UART documentation for Raspberry Pi 5

f884ee7

aallan added enhancement documentation labels Nov 22, 2023

pelwell suggested changes Nov 23, 2023

View reviewed changes

aallan reviewed Nov 23, 2023

View reviewed changes

leon-anavi mentioned this pull request Nov 23, 2023

Add Raspberry Pi 5 agherzan/meta-raspberrypi#1237

Merged

nathan-contino added the pi5 5️⃣ It's the everything computer. optimised. label Nov 23, 2023

nathan-contino added 2 commits November 27, 2023 09:39

Implemented feedback

b84cc86

Updated introduction for new table

ba6bac5

pelwell reviewed Nov 27, 2023

View reviewed changes

Update documentation/asciidoc/computers/configuration/uart.adoc

cdb2cbe

nathan-contino added 2 commits November 27, 2023 11:44

Reorder sections, add mini UART removal sentence

cf102db

Implemented last remaining feedback

5650fea

Implemented last round of phil feedback

4e4f944

pelwell reviewed Nov 27, 2023

View reviewed changes

documentation/asciidoc/computers/configuration/uart.adoc Outdated Show resolved Hide resolved

Update documentation/asciidoc/computers/configuration/uart.adoc

20b5f9e

pelwell approved these changes Nov 28, 2023

View reviewed changes

aallan approved these changes Nov 29, 2023

View reviewed changes

aallan merged commit 6f3b8e9 into develop Nov 29, 2023
1 check passed

aallan deleted the update-uart-for-pi5 branch November 29, 2023 10:40

samskiter reviewed Feb 28, 2024

View reviewed changes

		@@ -4,6 +4,30 @@ There are two types of UART available on the Raspberry Pi - http://infocenter.a

		All UARTs on the Raspberry Pi are 3.3V only - damage will occur if they are connected to 5V systems. An adaptor can be used to connect to 5V systems. Alternatively, low-cost USB to 3.3V serial adaptors are available from various third parties.

		=== Raspberry Pi 5

Update UART documentation for Raspberry Pi 5 #3294

Update UART documentation for Raspberry Pi 5 #3294

Conversation

nathan-contino commented Nov 22, 2023

pelwell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nathan-contino commented Nov 27, 2023

pelwell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aallan commented Nov 27, 2023

pelwell commented Nov 27, 2023

nathan-contino commented Nov 27, 2023

pelwell commented Nov 27, 2023

nathan-contino commented Nov 27, 2023

nathan-contino commented Nov 28, 2023

aallan commented Nov 29, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment