From 6f7e4bf16a01c38b03d41d09e3e6d9b615ecee0c Mon Sep 17 00:00:00 2001
From: Calascibetta Romain <romain.calascibetta@gmail.com>
Date: Sun, 12 Jan 2025 12:30:33 +0100
Subject: [PATCH] Add some docs

---
 doc/dev.md               | 93 ++++++++++++++++++++++++++++++++++++++++
 doc.txt => doc/memory.md |  3 ++
 2 files changed, 96 insertions(+)
 create mode 100644 doc/dev.md
 rename doc.txt => doc/memory.md (97%)

diff --git a/doc/dev.md b/doc/dev.md
new file mode 100644
index 0000000..830d596
--- /dev/null
+++ b/doc/dev.md
@@ -0,0 +1,93 @@
+The best way to iterate and try gilbraltar is to use the netboot and an
+ethernet cable to update a folder containing everything needed for the
+RaspBerry Pi 5 and restart the RaspBerry Pi to download this new version of the
+Gilbraltar kernel.
+
+At least, this method is quicker than plugging and unplugging the SD card with
+the new version of the kernel.
+
+This document explains how to test Gilbraltar directly on the RaspBerry Pi 5
+with the netboot.
+
+## Configuring the RaspBerry Pi 5
+
+The first thing to do is to get an SD card and install another version of the
+firmware that allows netboot. So you need to install `rpi-imager` and "Network
+Book" ("Choose OS" -> "Misc Utility Images" -> "Bootloader (Pi 5 family)" ->
+Network Boot").
+
+Once installed on the SD card, you need to put the card on the RaspBerry Pi 5
+and plug in the power supply. The firmware will then be modified (to activate
+the netboot) and if all goes well, the LED on the RaspBerry Pi 5 should blink
+green.
+
+At this point, you no longer need the SD card. All you need now is an ethernet
+cable. This needs to be connected between your RaspBerry Pi 5 and your computer
+(directly, without going through a router).
+
+### Dnsmasq and Ethernet
+
+On your PC, you need to configure a `dnsmasq` service so that it is mounted on
+the Ethernet interface and can communicate with the RaspBerry Pi 5. To mount
+`dnsmasq` on the Ethernet interface, you need a properly configured virtual
+bridge and "plug" your Ethernet interface into this bridge:
+```shell
+$ sudo ip link add name raspberrypi type bridge
+$ sudo ip addr add 192.168.42.1/24 dev raspberrypi
+$ sudo ip link set eth0 master raspberrypi
+$ cat >>/etc/dnsmasq.conf <<EOF
+port=0
+dhcp-range=192.168.42.16,192.168.42.64,12h
+dhcp-option=1,255.255.255.0
+dhcp-option=3,192.168.42.1
+interface=raspberrypi
+domain=raspberrypi.local
+bind-interfaces
+except-interface=lo
+log-dhcp
+log-queries
+log-async
+log-facility=/var/log/dnsmasq.log
+enable-tftp
+tftp-root=/srv/tftp
+pxe-service=0,"Raspberry Pi Boot"
+no-resolv
+EOF
+$ sudo ip link set dev raspberrypi up
+$ sudo ip link set dev eth0 up
+```
+
+At this point, we've configured your `eth0` Ethernet interface (where your
+ethernet cable is plugged into your computer) on a bridge `raspberrypi` running
+a `dnsmasq` service. This is configured to transmit what's in the `/srv/tfpd`
+folder to the RaspBerry Pi 5.
+
+### Files required
+
+In this folder, you should essentially have 3 files:
+- bcm2712-rpi-5-b.dtb (available [here][bcm2712])
+- config.txt
+- kernel_2712.img
+
+The `kernel_2712.img` is available via `make kernel_2712.img`. It's a mini
+kernel that initializes a whole range of elements, particularly UART,
+interrupts and memory.
+
+The `config.txt` should contain this:
+```shell
+$ cat >/srv/tftp/config.txt <<EOF
+arm_64bit=1
+kernel_address=0x80000
+kernel=kernel_2712.img
+EOF
+```
+
+### UART
+
+To communicate with the Raspberry Pi 5, you need a “Waveshare USB to UART
+Debugger Module for Raspberry Pi 5”. This connects the RaspBerry Pi 5 debugger
+to your computer via USB. This way, you'll be able to see your RaspBerry Pi
+boot via the command:
+```shell
+$ sudo minicom -D /dev/ttyACM0
+```
diff --git a/doc.txt b/doc/memory.md
similarity index 97%
rename from doc.txt
rename to doc/memory.md
index 6cbacca..5976eec 100644
--- a/doc.txt
+++ b/doc/memory.md
@@ -10,6 +10,9 @@ BCM2712 is the Broadcom chip used by Raspberry Pi 5
 
 # Memory layout
 
+Gilbraltar has a fairly precise memory layout. Here are the different zones
+(heap, stacks, etc.).
+
 | Base       | Size                 | Contents                   | Remarks |
 |------------|----------------------|----------------------------|---------|
 | 00000000   | 32 KByte             | ARM Trusted Firmware       | BL31    |