rt-thread/bsp/raspberry-pi/raspi5/README_en.md

Raspberry Pi 5 BSP User Guide

中文

1. Introduction

This BSP provides 64-bit RT-Thread support for Raspberry Pi 5. It targets the Broadcom BCM2712 SoC, which contains four Cortex-A76 cores, and uses the RT-Thread Device Model to manage on-board devices and RP1 southbridge peripherals.

The current boot flow is: Raspberry Pi firmware loads U-Boot, U-Boot loads rtthread.bin, and the firmware-provided device tree is passed to RT-Thread. SMP is enabled by default, and the default console device is uart10 from the device tree.

2. Prerequisites

2.1 Hardware

• Raspberry Pi 5;
• A microSD card and card reader;
• A 3.3 V TTL serial adapter;
• Optional: a wired network for TFTP boot.

The serial interface must use 3.3 V levels. Do not connect an RS-232 or 5 V serial adapter directly. The default serial settings are 115200 8N1, with hardware and software flow control disabled.

2.2 Software

• Python 3;
• SCons and the RT-Thread Env tools;
• An AArch64 bare-metal GCC toolchain;
• A Raspberry Pi 5-compatible U-Boot image;
• Optional: a TFTP server.

The default toolchain prefix is aarch64-none-elf-. The default search path in rtconfig.py is:

/opt/gcc-arm-8.3-2019.03-x86_64-aarch64-elf/bin/

Using environment variables is recommended so that repository files do not need to be modified:

export RTT_EXEC_PATH=/path/to/aarch64-toolchain/bin
export RTT_CC_PREFIX=aarch64-none-elf-

The build script prefers -mtune=cortex-a76. If an older compiler does not support it, the script falls back to cortex-a73 and then generic.

3. Configuration and Build

Enter the BSP directory:

cd bsp/raspberry-pi/raspi5

To change the default configuration, open menuconfig first:

scons --menuconfig

Build the BSP:

scons -j$(nproc)

On Windows, run scons directly or replace $(nproc) with a suitable number of parallel jobs.

A successful build produces:

File	Description
rtthread.elf	ELF image with symbols for debugging and disassembly
rtthread.bin	Raw binary image loaded by U-Boot
rtthread.map	Linker map
rtt.asm	Disassembly output

The load address of rtthread.bin is 0x210000, matching ARCH_TEXT_OFFSET in the default configuration. Do not change this address in the boot commands without updating the BSP configuration accordingly.

4. Preparing the Boot Media

4.1 Preparing U-Boot

Prepare a microSD card that can be recognized by the Raspberry Pi 5 firmware. Place a Raspberry Pi 5-compatible U-Boot image in the root of the FAT boot partition and name it:

u-boot.bin

The tools/config.txt file contains the minimum firmware configuration required by this BSP:

kernel=u-boot.bin
dtparam=pciex1

If the boot partition already contains a config.txt, merge these settings into it. Do not overwrite display, serial, or other board-specific settings that are still required.

4.2 Copying the RT-Thread Image

For SD card boot, copy the generated rtthread.bin to the root of the first FAT partition:

<boot partition>/rtthread.bin

The default commands use U-Boot device and partition mmc 0:1. If your SD controller or partition number differs, inspect it first:

mmc list
mmc dev 0
part list mmc 0
fatls mmc 0:1

5. Booting from U-Boot

5.1 Common Boot Arguments

Set the RT-Thread boot arguments at the U-Boot console:

setenv bootargs_rtt 'earlycon cma=8M coherent_pool=2M'
saveenv

The boot commands copy the live device tree provided by the firmware and update /chosen/bootargs. Do not replace it with a static DTB for another board revision or Raspberry Pi model, because RP1, PCIe, and on-board peripheral information may be incomplete.

5.2 Booting from the SD Card

setenv bootrtt 'mmc dev 0; fatload mmc 0:1 0x210000 rtthread.bin; fdt addr ${fdtcontroladdr}; fdt move ${fdt_addr_r} 0x20000; fdt addr ${fdt_addr_r}; fdt resize 8192; setenv bootargs ${bootargs_rtt}; fdt set /chosen bootargs ${bootargs}; booti 0x210000 - ${fdt_addr_r}'
saveenv
run bootrtt

After manual boot has been verified, enable automatic boot if desired:

setenv bootcmd 'run bootrtt'
saveenv

5.3 Booting over TFTP

Place rtthread.bin in the TFTP server root. The addresses below are examples and must be adjusted for your network:

setenv bootrtt_tftp 'setenv ethprime eth0; setenv ipaddr 192.168.10.2; setenv serverip 192.168.10.1; setenv netmask 255.255.255.0; ping 192.168.10.1; tftp 0x210000 rtthread.bin; fdt addr ${fdtcontroladdr}; fdt move ${fdt_addr_r} 0x20000; fdt addr ${fdt_addr_r}; fdt resize 8192; setenv bootargs ${bootargs_rtt}; fdt set /chosen bootargs ${bootargs}; booti 0x210000 - ${fdt_addr_r}'
saveenv
run bootrtt_tftp

If the U-Boot Ethernet device is not named eth0, inspect printenv ethact ethprime or bdinfo and adjust ethprime.

6. Expected Output

After a successful boot, the serial console should display the RT-Thread banner and SMP initialization messages before entering MSH:

 \ | /
- RT -     Thread Operating System
 / | \
 2006 - 2026 Copyright by RT-Thread team
Hi, this is RT-Thread!!
msh />

The exact version, build time, and device initialization messages depend on the active configuration.

7. Default Configuration

The default rtconfig.h enables the major features listed below. Whether a particular device is detected still depends on the Raspberry Pi firmware version, live device tree, expansion boards, and connected peripherals.

Category	Major features enabled by default
CPU	AArch64, four-core SMP, MMU, cache, and ASID
Console	PL011/8250 serial drivers; uart10 is the default console
Storage	SDHCI/MMC, FatFs, and NVMe over PCIe
Networking	RP1 Ethernet, PHY support, lwIP, and DHCP
Buses	PCIe, I2C, SPI, SDIO, and Device Tree/OFW
RP1 peripherals	ADC, PWM, GPIO/pinctrl, clocks, and MFD
System services	RTC, watchdog, DMA, thermal control, DVFS, and mailbox
Multimedia and input	I2S audio, framebuffer, touchscreen, joystick, and keyboard
User space	RT-Smart, DFS, POSIX, LWP, and dynamic linking

8. Troubleshooting

8.1 U-Boot Cannot Find rtthread.bin

Run:

fatls mmc 0:1

Check the filename, device number, and partition number. Linux filenames are case-sensitive.

8.2 Bad Linux ARM64 Image magic! or No Output After Jumping

• Make sure rtthread.bin, not rtthread.elf, was loaded;
• Make sure both the load and boot addresses are 0x210000;
• Make sure the command is booti 0x210000 - ${fdt_addr_r};
• Check the serial settings and stdout-path in the device tree.

8.3 Device Tree or RP1 Peripheral Initialization Fails

• Make sure the Raspberry Pi firmware and U-Boot support Raspberry Pi 5;
• Make sure config.txt contains dtparam=pciex1;
• Preserve and pass the live device tree provided by the firmware;
• Do not replace it in U-Boot with a DTB for another Raspberry Pi model.

8.4 TFTP Download Fails

Check ipaddr, serverip, netmask, the TFTP root, the host firewall, and the Ethernet connection. Run ping ${serverip} in U-Boot before downloading the image.

9. Notes After Reconfiguration

After running scons --menuconfig, the active configuration may differ from the default rtconfig.h documented here. Before submitting BSP configuration changes, inspect the generated rtconfig.h and verify newly enabled drivers on Raspberry Pi 5 hardware.