Ctrlk
VitePress 镜像站QQ 群 787969044视频教程Ⅰ视频教程Ⅱ
discord
For the complete documentation index, see llms.txt. This page is also available as Markdown.

23.1 Installing FreeBSD on Raspberry Pi

Raspberry Pi Overview

Technical Background of the Raspberry Pi

The ARM architecture dominates the embedded and mobile computing fields due to its low power consumption and high integration.

The Raspberry Pi is a Single-Board Computer (SBC) based on the ARM architecture, characterized by rich interfaces that support various peripheral expansions. Standard interfaces include: HDMI video output, I²C serial bus, USB 2.0/3.0 host interfaces, I²S audio interface, CSI camera interface, GPIO (General Purpose Input/Output) pins, UART serial port, RTC (Real-Time Clock) interface, PWM (Pulse Width Modulation) fan control, DSI display interface, PCIe high-speed interface (requires an adapter board), and POE (Power over Ethernet) module interface.

In terms of computing performance, the overall performance of the Raspberry Pi is roughly comparable to a contemporary mid-range smartphone (such as the Redmi series with Qualcomm processors).

Application Areas of the Raspberry Pi

The Raspberry Pi is primarily used in embedded system development, with typical applications including robot control, home router construction, and video surveillance system setup.

Origins of the Raspberry Pi

Eben Upton, then Director of Studies in Computer Science at St John's College, Cambridge, identified that the lack of affordable and openly architected computing devices for young people to learn and practice with was a major cause of the teaching difficulties in the University of Cambridge's Department of Computer Science and Technology. This was precisely the initial motivation behind the Raspberry Pi project, which was closely related to addressing this teaching challenge.

"To protect the department we love most — all we can do is develop a circuit board that everyone can afford!!"

While the school idols in LoveLive! failed to achieve their goal, the Raspberry Pi project ultimately achieved tremendous success, claiming to be the world's third best-selling general-purpose computer according to Raspberry Pi Ltd.

Storage Media Performance Testing and Selection

Necessity of Testing USB Drive/SD Card 4K Read/Write Speed

Before system installation, it is recommended to test the 4K random read/write performance of the USB drive or SD card you intend to use. For specific testing methods, refer to Appendix I (microSD Card Parameters Overview) of this book.

Starting from the Raspberry Pi 3B+ model, the system natively supports booting from USB drives without additional hardware or software modifications. Testing has confirmed that FreeBSD versions 12, 13, and 14 all support this feature. The performance bottleneck primarily stems from two factors: first, the Raspberry Pi hardware itself is limited by bus speed, imposing an upper limit on interface performance; second, some USB drive products have actual performance that falls significantly short of their rated specifications. As a result, system boot speeds are relatively slow.

The SD card bus modes for each Raspberry Pi model are as follows:

Model
SD Card Bus Mode
Description

Raspberry Pi 5

SDR104 (UHS-I)

High-speed mode

Raspberry Pi 4

DDR50 (UHS-I)

High-speed mode

Raspberry Pi 3

High Speed (approx. 20–22 MB/s)

The SD card controller theoretically supports UHS-I, but has known reliability issues

Raspberry Pi 1/2

High Speed (approx. 20–22 MB/s)

Does not support UHS-I

Key Indicators for Storage Media Selection

The Raspberry Pi's SD card interface imposes hardware-level limitations on card transfer speeds. Using SD cards with rated sequential read/write speeds exceeding 100 MB/s will not significantly improve the user experience. Unless using specially designed overclocked card readers, consumer-grade devices can hardly achieve the manufacturer's rated sequential read/write speeds.

For embedded systems like the Raspberry Pi, 4K random read/write performance is the key metric affecting system responsiveness. When selecting an SD card, prioritize products that meet the A2 performance class, which specifies: random read no less than 4000 IOPS, random write no less than 2000 IOPS. Note that the full performance of A2 class depends on the host device's support for Command Queueing (CQ) and cache management. The Raspberry Pi 4 and 5 support the CQ extension, while earlier models do not. The actual performance of A2 cards on older models differs little from A1 cards.

Typical USB Drive Performance Case Study

Some USB drive products have 4K random write performance even lower than ordinary A2 class SD cards.

A representative case is the Kingston DataTraveler 100 G3 USB 3.0 flash drive (market abbreviation DT100 G3). According to test data, this product's 4K random write speed is close to 0 IOPS (the testing tool could not obtain valid results), which will cause severe response delays during system use.

Kingston DataTraveler 100 G3 USB 3.0 Flash Drive (i.e., DT100 G3) read/write speed test
Kingston DataTraveler 100 G3 USB 3.0 Flash Drive (i.e., DT100 G3) read/write speed test

References

ARM Architecture Support

FreeBSD uses a tiered support system for different hardware architectures. Currently, AArch64 (ARM64) is a Tier 1 architecture, receiving core support from the FreeBSD project. However, in terms of software ecosystem completeness, AArch64 still slightly lags behind AMD64 (x86-64), and some packages cannot yet be successfully built from source via FreeBSD Ports.

Pre-Installation Preparation

Hardware and Software Preparation Checklist

Before starting the installation, prepare the following hardware devices and software tools:

Hardware devices:

  • A Raspberry Pi development board (any specific model);

  • A standard Ethernet cable for network connectivity;

  • An SD card that meets performance requirements (A2 class recommended);

  • A CH340-chip USB-to-serial cable, or a monitor with a resolution of at least 1080P (choose one of the two for system monitoring and debugging);

  • A standard home router (internet connection is not required; only used for LAN device interconnection).

Software tools (Windows 10/11 environment):

  • XShell: SSH terminal emulation software for remote login;

  • WinSCP: SFTP file transfer software for file management.

Basic Installation Process Overview

Installation Steps Overview

The basic procedure for installing FreeBSD on a Raspberry Pi is as follows:

  1. Visit the FreeBSD official website and download the FreeBSD system image matching your Raspberry Pi hardware model;

  2. After downloading, extract the image file;

  3. Use a tool such as Rufus to write the image to the SD card, creating a bootable medium;

  4. Complete the necessary hardware connections: connect a USB Ethernet adapter and network cable, connect an HDMI monitor (if using video output);

  5. Insert the prepared SD card into the Raspberry Pi's SD card slot;

  6. Power on and wait for the system to complete initialization (typically about five minutes);

  7. Log into the router's management interface and check the IP address assigned to the Raspberry Pi;

  8. Connect remotely to the Raspberry Pi running FreeBSD via SSH.

Note

After writing, you need to mount the FAT partition and replace all files in it, otherwise display anomalies (such as screen corruption, rainbow screen) may occur during boot. The replacement files can be found at:

https://github.com/FreeBSD-Ask/FreeBSD-rpi4-firmware

FreeBSD ZFS and Raspberry Pi (for Raspberry Pi 4 and 5)

Before using the ZFS file system on a Raspberry Pi, ensure the firmware is up to date. The steps are as follows:

Note

The default IMG image provided by FreeBSD uses the UFS file system. Users who need ZFS can first write the img image to the SD card and boot normally, then insert a USB drive, load the ZFS module, and run the bsdinstall command to install (selecting the USB drive as the installation target). In the bsdinstall interface, select the target disk, set the partition scheme, and configure the ZFS pool. If you need to use ZFS on the SD card, you can reverse the process by using the USB drive as the boot disk for installation.

Pre-installation notes:

mmcsd0 is the SD card, da0 is the USB drive.

The following steps will create a Raspberry Pi FreeBSD system using ZFS on a USB drive. Write the standard image to the SD card, boot it, then insert a blank USB drive. The USB drive must maintain a FAT32 file system and MBR partition table.

View the system disk partition table information:

You must load the ZFS module first, otherwise partition errors such as sysctl: unknown oid 'vfs.zfs.min_auto_ashift' will occur.

Start the installation program to install FreeBSD:

After installation, display the system disk partition table information again:

Raspberry Pi 5

The test environment is as follows:

  • Raspberry Pi 5 8 GB

  • FreeBSD 15.0-CURRENT

  • External RTL 8156B network adapter

  • Boot drive: 256 GB NVMe SSD

  • UEFI: rpi5-uefi v0.3

Warning

This section does not apply to the D0 stepping version or the 16 GB memory version. For details, see https://rpicn.bsdcn.org. If using a newer firmware version, you may need to downgrade the firmware to use the methods in this section.

Testing has confirmed that the Raspberry Pi 5 8 GB can boot from an SD card, USB device, or M.2 NVMe SSD on an M.2 expansion board (Waveshare's PCIe_TO_M.2_HAT+) using UEFI and FreeBSD 15.0 (test image FreeBSD-15.0-CURRENT-arm64-aarch64-20240628-14fee5324a9b-270986-memstick.img.xz). The latter is compatible with PCIe 3.0 devices; the Raspberry Pi 5 runs in PCIe 2.0 x1 mode by default and can enable PCIe 3.0 speed via the firmware parameter dtparam=pciex1_gen=3, but stability depends on signal integrity.

The built-in network adapter and other hardware currently lack drivers (a USB network adapter can be used instead). The fan is controlled by firmware and runs continuously by default. HDMI display works normally, and both USB 2.0 and 3.0 interfaces function properly. Testing shows that the KDE Plasma 5 desktop environment can output normally to an HDMI monitor.

Raspberry Pi 5 and HAT+

When purchasing a Raspberry Pi 5 expansion board, please confirm that it complies with the HAT+ standard. Expansion boards that do not meet this standard typically can only obtain power through the PCIe FPC. To comply with relevant specifications, the expansion board's power requirement should be 5 V 2 A, i.e., 10 W.

The Raspberry Pi 5 does not provide a standard PCIe interface, but rather a custom-designed FPC interface, so an adapter is required to connect PCIe devices to the Raspberry Pi 5.

According to the Raspberry Pi 5's ribbon cable specification, this interface can provide a maximum of 5 V 1 A, i.e., a maximum of 5 W of power. Therefore, the Raspberry Pi's HAT+ specification requires the expansion board to also draw power from the GPIO interface.

Building and Installing World and Kernel on Raspberry Pi 5 8 GB

The example uses FreeBSD 15.0-CURRENT, with all default parameters.

Display the current Git repository freebsd-src commit hash:

  • Building world (userland) took approximately 6 hours.

  • Building the kernel took approximately 26 minutes.

Troubleshooting and Unresolved Issues

  • newfs_msdos /dev/gpt/efiboot0: operation not permitted

This issue primarily occurs when installing the system to a USB drive using a ZFS SD card. There is currently no solution; you can only use another USB boot drive with a UFS file system to install the USB drive system.

Commands that may be useful:

Warning

gpart destroy -F will forcibly destroy the partition table of the specified disk. All data on the disk will be permanently lost. Confirm that da2 is the correct target disk.

gpart destroy -F da2 is used to destroy the file system incorrectly created in this step, to prevent the system from failing to recognize it.

Appendix: Using the Serial Port

It is recommended to connect an external monitor or use a CH340 USB serial cable, in case system processes hang and you cannot determine the status.

If using a USB serial cable, it is recommended to purchase a model with a CH340 chip. Otherwise, you may encounter issues such as process hanging, no output, inability to input, driver installation failure, or incompatibility with Windows 10.

If using a monitor, the screen resolution should be no less than 1080P (1920 x 1080), and the screen size should be no smaller than 8 inches. Otherwise, even with a monitor connected, you will only see the screen light up but will not be able to clearly read the text.

If a monitor is connected, ensure that the Raspberry Pi and the monitor are powered on simultaneously. The monitor can be powered on after the Raspberry Pi, but should not be delayed too long.

CH340 USB-to-serial official driver download link: https://www.wch.cn/downloads/CH341SER_EXE.html

Appendix: FreeBSD and Raspberry Pi 4B 8 GB Boot Failure Issue (Workaround)

If a rainbow screen appears and prevents booting, you can download a FreeBSD 14 image, write it to the SD card, and then replace the contents of the FAT partition. On Windows, the default partition is hidden; you can use tools like DiskGenius to activate it and assign a drive letter for access. On FreeBSD, you can directly mount the FAT partition using the mount_msdosfs command.

Firmware files can be obtained from https://github.com/FreeBSD-Ask/FreeBSD-rpi4-firmware.

Modify the config.txt file to the following content:

References

  • Raspberry Pi Foundation. The config.txt file[EB/OL]. [2026-04-16]. https://www.raspberrypi.com/documentation/computers/config_txt.html. States "By default (force_turbo=0) the on-demand CPU frequency driver will raise clocks to their maximum frequencies when the Arm cores are busy, and will lower them to the minimum frequencies when the Arm cores are idle".

Previous22.4 DTraceNext23.2 Using FreeBSD on Raspberry Pi

Last updated