Skip to content

Latest commit

 

History

History
140 lines (79 loc) · 4.72 KB

RunningOnRaspberryPi.md

File metadata and controls

140 lines (79 loc) · 4.72 KB
Raw

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.