jcs.org
Serenity Operating System
1# Running Serenity on Raspberry Pi
2
3## NOTE
4
5This is for development purposes only - Serenity doesn't currently boot on Rasperry Pi! Use this guide if you want to set up a development environment.
6
7Currently only UART output is supported, no display.
8
964-bit only, so you need a Rasperry Pi 3 or newer.
10
11## Running in QEMU
12
13### Step 1: Set Up Serenity
14
15Please follow [build instructions](BuildInstructions.md) to download and build Serenity. Make sure everything builds successfully for x86.
16
17### Step 2: Build Aarch64 toolchain
18
19Use following the command to build the toolchain for Aarch64:
20
21```console
22Meta/serenity.sh rebuild-toolchain aarch64
23```
24
25### Step 3: Build and run in emulator
26
27Use the following command to build and run the Aarch64 kernel:
28
29```console
30Meta/serenity.sh run aarch64
31```
32
33It should build Serenity and open a QEMU window, similar to the x86 version. You should see some messages in the terminal.
34
35You can also run it under gdb with:
36
37```console
38Meta/serenity.sh gdb aarch64
39```
40
41## Running on real hardware using an SD Card
42
43### Step 0: Download and run Raspberry Pi OS from an SD Card
44
45This 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.
46
47### Step 1: Connect your Raspberry Pi to your PC using a UART cable
48
49Please follow one of the existing guides (for example [here](https://scribles.net/setting-up-serial-communication-between-raspberry-pi-and-pc)) and make sure UART is working on Raspberry Pi OS before proceeding.
50
51### Step 2: Mount SD Card
52
53If you use a Raspberry Pi 4, and your serenity kernel is called `kernel8.img`
54(the default), and you don't have any other `kernel*.img` files on your SD
55card, make sure `config.txt` is empty.
56
57If you want to use filename that isn't `kernel8.img` or if you want to keep
58other `kernel*.img` files on your SD card, put this in config.txt:
59
60```
61arm_64bit=1
62kernel=myfilename.img
63```
64
65If you use a Raspberry Pi 3, put this in config.txt:
66
67```
68enable_uart=1
69```
70
71### Step 3: Copy Serenity kernel to SD Card
72
73`kernel8.img` can be found in `Build/aarch64/Kernel/Prekernel/`. 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).
74
75### Step 4: Put the SD Card in the Raspberry Pi and power on
76
77You should start seeing some messages in your UART terminal window.
78
79## Running on real hardware using network (Raspberry Pi 3)
80
81### Prerequisites
82
83There 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.
84
85Here's the [Raspberry Pi Documentation](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#debugging-network-boot-mode) on booting from the network.
86
87### Step 1: Make sure OTP mode is enabled on the board
88
89This is enabled by default on Raspberry Pi 3+. For the previous boards please see the section [Debugging Network Boot Mode](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#debugging-network-boot-mode) of the Raspberry Pi documentation.
90
91### Step 2: Copy all files from the original SD Card to your PC
92
93This directory will serve as a TFTP server, sending files to the Raspberry Pi when requested.
94
95### Step 2: Set up the network interface
96
97Switch the network interface to static mode (static IP) and disable the firewall.
98
99### Step 3: Set up network services
100
101Booting Raspberry Pi requires DHCP and TFTP servers.
102
103On Windows, you can use the [Tftpd32](https://bitbucket.org/phjounin/tftpd64/src/master/) program.
104
105Example configuration for DHCP:
106
107
108
109Make sure you **disable** the `Ping address before assignment` option.
110
111Example configuration for TFTP:
112
113
114
115The only option worth noting is `Base Directory` which should contain the files from the SD Card.
116
117### Step 4: Power up the Raspberry Pi
118
119Remove the SD Card, connect an Ethernet cable between the Raspberry Pi and your PC and power on the board.
120
121After 5-10 seconds you should see files being served by the TFTP server:
122
123
124
125The system should boot normally as it would from the SD Card.
126
127### Step 5: Modify config.txt and copy Serenity kernel
128
129Similarly to booting from SD Card (see above), modify `config.txt` and copy the Serenity kernel to the TFTP directory.
130
131### Step 6: Reset Raspberry Pi
132
133You should start seeing some Serenity messages in your UART terminal window.