> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-23-embedded-platforms-and-development-environments/di-23.1-jie-shu-mei-pai-freebsd-an-zhuang.md). # 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](https://www.kingston.com/cn/blog/personal-storage/microsd-sd-memory-card-naming-conventions), 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](/files/Nj5TnaP2eF0qQRE5fVwO) ![Kingston DataTraveler 100 G3 USB 3.0 Flash Drive (i.e., DT100 G3) read/write speed test](/files/cdT6Jr5rfKwug2bAVrZ7) ### References * Heath N. Inside the Raspberry Pi: The story of the $35 computer that changed the world\[EB/OL]. \[2026-03-25]. . Chronicles the Raspberry Pi's journey from an educational project to a globally bestselling single-board computer. * Chinese FreeBSD Community (CFC). Raspberry Pi Chinese Documentation\[EB/OL]. \[2026-03-25]. . A guide for daily installation, configuration, and use of the Raspberry Pi. * Taiwan Raspberry Pi. \[Tutorial/Basic] Testing SD Card Performance on Raspberry Pi 5\[EB/OL]. (2024-06-02)\[2026-03-25]. . Actual testing of SD card read/write performance and differences on the Raspberry Pi 5. * GR-Thunderstorm. Default Setting for the UHSMODE?\[EB/OL]. (2024-04-23)\[2026-03-25]. . Discussion of default configuration and performance optimization for Raspberry Pi SD card UHS mode. * Kingston Technology. DataTraveler 100 G3 USB 3.0 Flash Drive - Technical Support\[EB/OL]. \[2026-03-25]. . Technical specifications and support documentation for the Kingston DT100G3 USB drive. * wintelguy.com. IOPS-MB Online Converter: IOPS, MB/s, GB/day Converter\[EB/OL]. \[2026-03-25]. . Online conversion tool for storage performance units such as IOPS and MB/s. * Raspberry Pi Ltd. Raspberry Pi SD Cards\[EB/OL]. (2024-10)\[2026-04-17]. . Official Raspberry Pi A2 SD card product brief, documenting DDR50/SDR104 bus speeds and Command Queueing (CQ) extension support. ## ARM Architecture Support FreeBSD uses a tiered support system for different hardware architectures. Currently, AArch64 (ARM64) is a [Tier 1 architecture](https://www.freebsd.org/platforms/), 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](https://rufus.ie/) 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: > > ## 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: ```sh # gpart show => 63 246947777 mmcsd0 MBR (118G) 63 1985 - free - (993K) 2048 102400 1 fat16 [active] (50M) 104448 246835200 2 freebsd (118G) 246939648 8192 - free - (4.0M) => 0 246835200 mmcsd0s2 BSD (118G) 0 128 - free - (64K) 128 230057856 1 freebsd-ufs (110G) 230057984 16777216 2 freebsd-swap (8.0G) => 63 60088257 da0 MBR (29G) 63 4033 - free - (2.0M) 4096 60084224 1 fat32lba [active] (29G) ``` You must load the ZFS module first, otherwise partition errors such as `sysctl: unknown oid 'vfs.zfs.min_auto_ashift'` will occur. ```sh # kldload zfs # Load the ZFS kernel module ``` Start the installation program to install FreeBSD: ```sh # bsdinstall ``` After installation, display the system disk partition table information again: ```sh $ gpart show => 34 60088253 da0 GPT (29G) 34 6 - free - (3.0K) 40 532480 1 ms-basic-data (260M) 532520 2008 - free - (1.0M) 534528 4194304 2 freebsd-swap (2.0G) 4728832 55357440 3 freebsd-zfs (26G) 60086272 2015 - free - (1.0M) ``` ## 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](https://github.com/worproject/rpi5-uefi) > **Warning** > > This section does not apply to the D0 stepping version or the 16 GB memory version. For details, see . 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+](https://www.waveshare.com/wiki/PCIe_TO_M.2_HAT+)) using [UEFI](https://github.com/worproject/rpi5-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](https://cgit.freebsd.org/src/commit/?id=fef0e39f64a1db796ded8777dbee71fc287f6107), with all default parameters. Display the current Git repository freebsd-src commit hash: ```sh root@ykla:/usr/src # git rev-parse HEAD fef0e39f64a1db796ded8777dbee71fc287f6107 ``` * Building world (userland) took approximately 6 hours. ```sh --- buildworld_epilogue --- -------------------------------------------------------------- >>> World build completed on Tue Aug 6 04:01:22 CST 2024 >>> World built in 21438 seconds, ncpu: 4, make -j4 -------------------------------------------------------------- ``` * Building the kernel took approximately 26 minutes. ```sh -------------------------------------------------------------- >>> Kernel build for GENERIC completed on Tue Aug 6 07:22:22 CST 2024 -------------------------------------------------------------- >>> Kernel(s) GENERIC built in 1564 seconds, ncpu: 4, make -j4 -------------------------------------------------------------- ``` ### 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: ## 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 . Modify the `config.txt` file to the following content: ```ini arm_64bit=1 # Enable 64-bit ARM architecture mode dtoverlay=disable-bt # Disable Bluetooth device tree overlay dtoverlay=mmc # Enable MMC device tree overlay device_tree_address=0x4000 # Specify the device tree address in memory kernel=u-boot.bin # Specify the kernel file to use armstub=armstub8-gic.bin # ARM boot stub file path hdmi_safe=0 # Disable HDMI safe mode force_turbo=0 # Retain dynamic frequency scaling (default safe mode) arm_freq=2000 # Set ARM CPU frequency to 2000 MHz (overclocking) over_voltage=6 # Set CPU voltage boost value (overclocking) ``` ### References * Raspberry Pi Foundation. The config.txt file\[EB/OL]. \[2026-04-16]. . 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". --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://book.bsdcn.org/ask/flat/chapter-23-embedded-platforms-and-development-environments/di-23.1-jie-shu-mei-pai-freebsd-an-zhuang.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.