4.7 KiB
Running Serenity on Raspberry Pi
NOTE
This is for development purposes only - Serenity doesn't currently boot on Raspberry Pi! Use this guide if you want to set up a development environment.
Currently only UART output is supported, no display.
64-bit only, so you need a Raspberry Pi 3 or newer.
Running in QEMU
Step 1: Set Up Serenity
Please follow build instructions to download and build Serenity. Make sure everything builds successfully for x86.
Step 2: Build Aarch64 toolchain
Use following the command to build the toolchain for Aarch64:
Meta/serenity.sh rebuild-toolchain aarch64
Step 3: Build and run in emulator
Use the following command to build and run the Aarch64 kernel:
Meta/serenity.sh run aarch64
It should build Serenity and open a QEMU window, similar to the x86 version. You should see some messages in the terminal.
You can also run it under gdb with:
Meta/serenity.sh gdb aarch64
Running on real hardware using an SD Card
Step 0: Download and run Raspberry Pi OS from an SD Card
This step is needed because the original firmware files need to be present on the SD Card when booting Serenity. It will also help with the UART setup.
Step 1: Connect your Raspberry Pi to your PC using a UART cable
Please follow one of the existing guides (for example here) and make sure UART is working on Raspberry Pi OS before proceeding.
If you're using a Raspberry Pi 4B and want to test if the UART is working correctly, you need to do a few extra steps.
UART0 (the one that SerenityOS uses) is used for bluetooth on these models, so for the OS to use it instead, ensure that you disable Bluetooth inside the config.txt:
dtoverlay=disable-bt
Step 2: Mount SD Card
If you use a Raspberry Pi 4, and your serenity kernel is called kernel8.img
(the default), and you don't have any other kernel*.img files on your SD
card, make sure config.txt is empty.
If you want to use filename that isn't kernel8.img or if you want to keep
other kernel*.img files on your SD card, put this in config.txt:
arm_64bit=1
kernel=myfilename.img
If you use a Raspberry Pi 3, put this in config.txt:
enable_uart=1
Step 3: Copy Serenity kernel to SD Card
kernel8.img can be found in Build/aarch64/Kernel/. Copy it to the main directory on the Boot/ partition, next to config.txt. You can either replace the original file or use another name (see above).
Step 4: Put the SD Card in the Raspberry Pi and power on
You should start seeing some messages in your UART terminal window.
Running on real hardware using network (Raspberry Pi 3)
Prerequisites
There are multiple ways to set up your network. The easiest way is a direct connection between the Raspberry Pi and your PC. To achieve this your PC has to have an Ethernet port.
Here's the Raspberry Pi Documentation on booting from the network.
Step 1: Make sure OTP mode is enabled on the board
This is enabled by default on Raspberry Pi 3+. For the previous boards please see the section Debugging Network Boot Mode of the Raspberry Pi documentation.
Step 2: Copy all files from the original SD Card to your PC
This directory will serve as a TFTP server, sending files to the Raspberry Pi when requested.
Step 2: Set up the network interface
Switch the network interface to static mode (static IP) and disable the firewall.
Step 3: Set up network services
Booting Raspberry Pi requires DHCP and TFTP servers.
On Windows, you can use the Tftpd32 program.
Example configuration for DHCP:
Make sure you disable the Ping address before assignment option.
Example configuration for TFTP:
The only option worth noting is Base Directory which should contain the files from the SD Card.
Step 4: Power up the Raspberry Pi
Remove the SD Card, connect an Ethernet cable between the Raspberry Pi and your PC and power on the board.
After 5-10 seconds you should see files being served by the TFTP server:
The system should boot normally as it would from the SD Card.
Step 5: Modify config.txt and copy Serenity kernel
Similarly to booting from SD Card (see above), modify config.txt and copy the Serenity kernel to the TFTP directory.
Step 6: Reset Raspberry Pi
You should start seeing some Serenity messages in your UART terminal window.