diff --git a/configuration/uart.md b/configuration/uart.md index 3e29d1588..d214f7f64 100644 --- a/configuration/uart.md +++ b/configuration/uart.md @@ -1,99 +1,96 @@ # UART configuration -There are two types of UART available on the Raspberry Pi - [PL011](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0183g/index.html) and mini UART. The PL011 is a capable, broadly 16550-compatible UART, while the mini UART has a reduced feature set. +## Hardware -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. +All Raspberry Pi computers have at least two UARTs. The Raspberry Pi 4 family (BCM2711) has six UARTs. -## Pi Zero, 1, 2 and 3 - two UARTs +There are two different types of UART devices available on the Raspberry Pi: +* [PL011](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0183g/index.html), patterned on the [16550 UART](https://en.wikipedia.org/wiki/16550_UART) chip. +* mini UART, patterned on the [8250 UART](https://en.wikipedia.org/wiki/8250_UART) chip. -The Raspberry Pi Zero, 1, 2, and 3 each contain two UARTs as follows: +The naming and numbering of the UARTs can be confusing because they use different names and numbers in different contexts. These names from Broadcom are authoritative: -| Name | Type | -|------|------| -|UART0 |PL011 | -|UART1 |mini UART | +| SoC | UART0 | UART1 | UART2 | UART3 | UART4 | UART5 | +| --- | --- | --- | --- | --- | --- | --- | +| BCM2835 | PL011 | mini UART | +| BCM2836 | PL011 | mini UART | +| BCM2837 | PL011 | mini UART | +| BCM2711 | PL011 | mini UART | PL011 | PL011 | PL011 | PL011 | -## Pi 4 - six UARTS +Inside the Raspberry Pi, the UARTs are able to connect in several ways. UART0 and UART1 can connect to either the GPIO header, or the onboard Bluetooth module, if there is one. UARTs two through five can be enabled and disabled, but have no alternate connections. -The Raspberry Pi 4 has four additional PL011s, which are disabled by default. The full list of UARTs on the Pi 4 is: +See the [Raspberry Pi 4 Model B Datasheet](../hardware/raspberrypi/bcm2711/rpi_DATA_2711_1p0_preliminary.pdf) section _5.1.2 GPIO Alternate Functions_, for pinout details. Earlier models are similar but with only the first two UARTs. -| Name | Type | -|------|------| -|UART0 |PL011 | -|UART1 |mini UART | -|UART2 |PL011 | -|UART3 |PL011 | -|UART4 |PL011 | -|UART5 |PL011 | +### Voltages -## Primary UART +All the onboard Raspberry Pi UARTs are made for 3.3V [logic levels](https://en.wikipedia.org/wiki/Logic_level)). Do not connect Raspberry Pi to any devices that output 5V signals, because they will damage the Raspberry Pi. -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. +## Software support -## Secondary UART +Raspberry Pi OS has built-in drivers for the onboard UARTs. -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. +If either of the UARTs is enabled and internally connected to the GPIO header, that UART is called `/dev/serial0`. Similarly, the UART connected to the Bluetooth module is `/dev/serial1`. -## Configuration +The `/dev/serial*` files are symbolic links created by the Linux device management system, [udev](https://en.wikipedia.org/wiki/Udev). udev reads configuration from the device tree and creates the appropriate files. For each enabled PL011, a file like `/dev/ttyAMA*` is created. Their numbers will be in the same order as in the Broadcom hardware documentation, but given consecutive numbers starting at zero. -By default, only UART0 is enabled. The following table summarises the assignment of the first two UARTs: +The mini UART is always `/dev/ttyS0` if it is enabled. -| Model | first PL011 (UART0)| mini UART | -|-------|-----------|-------| -| Raspberry Pi Zero | primary | secondary | -| Raspberry Pi Zero W | secondary (Bluetooth) | primary | -| Raspberry Pi 1 | primary | secondary | -| Raspberry Pi 2 | primary | secondary | -| Raspberry Pi 3 | secondary (Bluetooth) | primary | -| Raspberry Pi 4 | secondary (Bluetooth) | primary | +## Using the UARTs -Note: the mini UART is disabled by default, whether it is designated primary or secondary UART. +### Configuring the hardware -Linux devices on Raspberry Pi OS: +On most devices, only UART0 is enabled by default. On compute modules, the UARTs are all disabled by default and must be explicitly enabled using a device tree overlay. You must also specify which GPIO pins to use for the interface, for example: -| Linux device | Description | -|--------------|-------------| -|`/dev/ttyS0` |mini UART | -|`/dev/ttyAMA0`|first PL011 (UART0) | -|`/dev/serial0` |primary UART | -|`/dev/serial1` |secondary UART | +``` +dtoverlay=uart1,txd1_pin=32,rxd1_pin=33 +``` -Note: `/dev/serial0` and `/dev/serial1` are symbolic links which point to either `/dev/ttyS0` or `/dev/ttyAMA0`. +#### raspi-config -## Mini UART and CPU core frequency +1. Start [raspi-config](raspi-config.md): `sudo raspi-config`. +1. Select option 3 - Interface Options. +1. Select option P6 - Serial Port. +1. Answer the prompts according to your needs. +1. Exit raspi-config and reboot the Pi for changes to take effect. -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: +#### config.txt -| Mini UART set to | core clock | Result | -|------------------|------------|--------| -| primary UART | variable | mini UART disabled | -| primary UART | fixed by setting `enable_uart=1` | mini UART enabled, core clock fixed to 250MHz, or if `force_turbo=1` is set, the VPU turbo frequency | -| secondary UART | variable | mini UART disabled | -| secondary UART | fixed by setting `core_freq=250` | mini UART enabled | +On most devices, adding `enable-uart=1` to `/boot/config.txt` should ensure that a UART is available on the GPIO header. On compute modules, you must also add a device-tree overlay to enable the particular UART you want to use. -The default state of the `enable_uart` flag depends on which UART is the primary UART: +See [config.txt](config-txt/README.md) for more information. -| Primary UART | Default state of enable_uart flag | -|--------------|-----------------------------------| -| mini UART | 0 | -| first PL011 (UART0) | 1 | +#### Device tree overlays -## Disable Linux serial console +Device tree overlays are also typically added in `/boot/config.txt` with lines like: +``` +dtoverlay=disable-bt +``` +However, device overlays are defined in the open-source [Linux source code](https://github.com/raspberrypi/linux). See [this page](device-tree.md). for further detail. -By default, the primary UART is assigned to the Linux console. If you wish to use the primary UART for other purposes, you must reconfigure Raspberry Pi OS. This can be done by using [raspi-config](raspi-config.md): +These device-tree overlays are of interest: -1. Start raspi-config: `sudo raspi-config`. -1. Select option 3 - Interface Options. -1. Select option P6 - Serial Port. -1. At the prompt `Would you like a login shell to be accessible over serial?` answer 'No' -1. At the prompt `Would you like the serial port hardware to be enabled?` answer 'Yes' -1. Exit raspi-config and reboot the Pi for changes to take effect. +| Name | Purpose | +|---|---| +| disable-bt | Disable onboard Bluetooth, making UART0 available. | +| miniuart-bt | Switch the onboard Bluetooth to UART1, making UART0 available. | +| uart0 | Enable and set the pin usage of UART0 | +| uart1 | Enable and set the pin usage of UART1 | +| uart2 | Enable UART2 | +| uart3 | Enable UART3 | +| uart4 | Enable UART4 | +| uart5 | Enable UART5 | + +### Serial console + +Raspberry Pi OS can present a [serial console](https://en.wikipedia.org/wiki/System_console) on `/dev/serial0` and the related GPIO header pins, 8 and 10. -## Enabling early console (earlycon) for Linux +The serial console can be enabled by answering "Yes" to raspi-config's prompt: `Would you like a login shell to be accessible over serial?` + +#### Enabling early console (earlycon) for Linux 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. That's the problem that the "earlycon" mechanism was created to work around. Consoles that support earlycon usage present an additional interface to the kernel that allows for simple, synchronous output - printk won't return until the characters have been output to the UART. -Enable earlycon with a kernel command line parameter - add one of the following to `cmdline.txt`, depending on which UART is the primary: +Enable earlycon with a kernel command line parameter - add one of the following to `cmdline.txt`, depending on which UART is being used as the console: ``` # For Pi 4 and Compute Module 4 (BCM2711) earlycon=uart8250,mmio32,0xfe215040 @@ -111,24 +108,22 @@ The baudrate is set to 115200. N.B. Selecting the wrong early console can prevent the Pi from booting. -## UARTs and Device Tree - -Various UART Device Tree overlay definitions can be found in the [kernel GitHub tree](https://github.com/raspberrypi/linux). The two most useful overlays are [`disable-bt`](https://github.com/raspberrypi/linux/blob/rpi-5.4.y/arch/arm/boot/dts/overlays/disable-bt-overlay.dts) and [`miniuart-bt`](https://github.com/raspberrypi/linux/blob/rpi-5.4.y/arch/arm/boot/dts/overlays/miniuart-bt-overlay.dts). +### Raspberry Pi as terminal -`disable-bt` disables the Bluetooth device and makes the first PL011 (UART0) the primary UART. You must also disable the system service that initialises the modem, so it does not connect to the UART, using `sudo systemctl disable hciuart`. +A Raspberry Pi can also use the onboard UARTs to act as a serial terminal, which can be used to connect to another Raspberry Pi's serial console, a modem, or other device. You'll need to disable the serial console to make the UART available for use. -`miniuart-bt` switches the Bluetooth function to use the mini UART, and makes the first PL011 (UART0) the primary UART. Note that this may reduce the maximum usable baud rate (see mini UART limitations below). You must also set the VPU core clock to a fixed frequency using either `force_turbo=1` or `core_freq=250`. +To use a Raspberry Pi as a serial terminal, you can use `sudo raspi-config`, answering 'No' to the question: `Would you like a login shell to be accessible over serial?` and 'Yes' to `Would you like the serial port hardware to be enabled?` -The overlays `uart2`, `uart3`, `uart4`, and `uart5` are used to enable the four additional UARTs on the Pi 4. There are other UART-specific overlays in the folder. Refer to `/boot/overlays/README` for details on Device Tree overlays, or run `dtoverlay -h overlay-name` for descriptions and usage information. +Alternatively, you can manually enable the UARTs and edit `/boot/cmdline.txt` to remove the portion like `console=serial0,115200`. -For full instructions on how to use Device Tree overlays see [this page](device-tree.md). In brief, add a line to the `config.txt` file to apply a Device Tree overlay. Note that the `-overlay.dts` part of the filename is removed. For example: -``` -dtoverlay=disable-bt -``` ## Relevant differences between PL011 and mini UART -The mini UART has smaller FIFOs. Combined with the lack of flow control, this makes it more prone to losing characters at higher baudrates. It is also generally less capable than a PL011, mainly due to its baud rate link to the VPU clock speed. +The mini UART measures time based on the VPU's core clock. If the core clock frequency is allowed to change, the mini UART's baud rate will change with it, and will not be what was intended. + +Therefore, using the mini UART requires configuring the Raspberry Pi to use a fixed VPU core clock frequency. There are several ways to fix the VPU core frequency. Either setting `enable_uart=1` or `core_freq=250` in `config.txt` will work. + +The mini UART also has smaller [FIFO buffers](https://en.wikipedia.org/wiki/Data_buffer#Telecommunication_buffer) than the PL011. Combined with the lack of flow control, this makes it more prone to losing characters at higher baud rates. It is also generally less capable than a PL011, mainly due to its baud rate link to the VPU clock speed. The particular deficiencies of the mini UART compared to a PL011 are : - No break detection