[PATCH V2 10/10] Platform/RaspberryPi: Update RPi4 Readme

Jeremy Linton

Replace the paragraph about NVRAM/UEFI variables, with
something that explains the situation a bit better.

Update the UEFI settings table.

Tweak the DT overlay list, and note support for
CM4 and RPi400.

Update the missing block to describe some higher level
goals and point users at the github issues page.

Signed-off-by: Jeremy Linton <jeremy.linton@...>
Platform/RaspberryPi/RPi4/Readme.md | 63 +++++++++++++++++++++++++++++++=
1 file changed, 53 insertions(+), 10 deletions(-)

diff --git a/Platform/RaspberryPi/RPi4/Readme.md b/Platform/RaspberryPi/R=
index 80899f4ca4..38ae0372fb 100644
--- a/Platform/RaspberryPi/RPi4/Readme.md
+++ b/Platform/RaspberryPi/RPi4/Readme.md
@@ -16,6 +16,8 @@ Raspberry Pi is a trademark of the [Raspberry Pi Founda=
The RPi4 target supports Pi revisions based on the BCM2711 SoC:
- Raspberry Pi 4B
+- Raspberry Compute Module 4
+- Raspberry Pi 400
Please see the RPi3 target for the BCM2837-based variants, such as the R=
Pi 3B.
@@ -44,10 +46,11 @@ Build instructions from the top level edk2-platforms =
Readme.md apply.
1. Format a uSD card as FAT16 or FAT32
2. Copy the generated `RPI_EFI.fd` firmware onto the partition
3. Download and copy the following files from https://github.com/raspber=
- - `bcm2711-rpi-4-b.dtb`
+ - `bcm2711-rpi-4-b.dtb`, `bcm2711-rpi-cm4.dtb`, or `bcm2711-rpi-400.dt=
- `fixup4.dat`
- `start4.elf`
- `overlays/miniuart-bt.dbto` or `overlays/disable-bt.dtbo` (Optional)
+ - `overlays/upstream-pi4.dtbo` (Optional)
4. Create a `config.txt` with the following content:
@@ -62,7 +65,12 @@ Build instructions from the top level edk2-platforms R=
eadme.md apply.
- Note: doing so requires `miniuart-bt.dbto` to have been copied into =
an `overlays/`
+ Additionally, if you want to use linux in DT mode
+ ```
+ dtoverlay=3Dupstream-pi4
+ ```
+ Note: doing so requires `miniuart-bt.dbto` or `upstream-pi4.dtbo` to=
have been copied into an `overlays/`
directory on the uSD card. Alternatively, you may use `disable-bt` i=
nstead of
`miniuart-bt` if you don't require Bluetooth.
5. Insert the uSD card and power up the Pi.
@@ -84,6 +92,8 @@ By default, UEFI will use the device tree loaded by the=
VideoCore firmware. This
depends on the model/variant, and relies on the presence on specific fil=
es on your boot media.
- `bcm2711-rpi-4-b.dtb` (for Pi 4B)
+ - `bcm2711-rpi-cm4.dtb` (for CM4)
+ - `bcm2711-rpi-400.dtb` (for Pi 400)
You can override the DTB and provide a custom one. Copy the relevant `.d=
tb` into the root of
the SD or USB, and then edit your `config.txt` so that it looks like:
@@ -110,11 +120,36 @@ Note, that the ultimate contents of `/chosen/bootar=
gs` are a combination of seve
-The Raspberry Pi has no NVRAM.
-NVRAM is emulated, with the non-volatile store backed by the UEFI image =
itself. This
-means that any changes made in UEFI proper are persisted, but changes ma=
de from within
-an Operating System aren't.
+The Raspberry Pi doesn't have NVRAM dedicated for UEFI.
+While UEFI variables and associated functions will appear to work correc=
+changes made while the OS is active won't persist over reboot except whe=
+three conditions are true. Those conditions are:
+- The OS must be running in ACPI mode.
+- The GPIO controller is not exported to the OS.
+- There must be sufficient free space on the SPI flash.
+In explanation, there are two different methods used to persist firmware
+configurations. The firmware first attempts to find 128K of free space o=
n the
+SPI flash utilized by the SoC for early boot. If that fails, updates are
+written directly to the RPI_EFI.fd image, but only when two conditions a=
+true. Those conditions are:
+- The OS is not yet booted.
+- The RPI_EFI.fd image is stored on media that the firmware can rewrite.
+The SPI is generally a better choice, but it only works if the firmware
+controls the GPIO pin muxing (since it shares pins with the PWM Audio) a=
nd the
+associated SPI controller while the OS is running. That is where the DT =
+GPIO restrictions come in.
+Finally, since the variables store utilizes free space on an SPI flash d=
+reserved for early boot/low-level firmware functions, future versions of=
+RPi foundation firmware may consume more of the available free space. Th=
+flash may be upgraded/downgraded using the official
+[RPi imager](https://github.com/raspberrypi/rpi-imager) update flash too=
l. That
+tool writes an SD disk image that, when placed in the RPi, will erase an=
+reprogram the entire SPI flash, thereby wiping out the UEFI variable sto=
re in
+the process.
## RTC
@@ -141,9 +176,12 @@ all functionality may be available.
## Missing Functionality
-- Network booting via onboard NIC.
-- SPCR hardcodes type to PL011, and thus will not expose correct
- (miniUART) UART if DT overlays to switch UART are used on Pi 4B.
+- Capsule update
+- CPPC (in progress)
+- External RTC support and CM4 IO Board RTC
+- Support more HATs in ACPI mode
+- Various OS drivers for onboard devices (GPU in linux, etc)
+- Other stuff, check https://github.com/pftf/RPi4/issues
# Configuration Settings
The Raspberry Pi UEFI configuration settings can be viewed and changed u=
sing both the UI configuration menu (under `Device Manager` -> `Raspberry=
Pi Configuration`), as well as the UEFI Shell. To configure using the UE=
FI Shell, use `setvar` command to read/write the UEFI variables with GUID=
=3D `CD7CC258-31DB-22E6-9F22-63B0B8EED6B5`.
@@ -179,6 +217,11 @@ Screenshot support | `DisplayEnableSShot` =
| Control-Alt-F12 =3D `0x00000
**Advanced Configuration** |
Limit RAM to 3 GB | `RamLimitTo3GB` | Disable =3D `0x00000000=
` <br> Enabled=3D `0x00000001` (default)
System Table Selection | `SystemTableMode`| ACPI =3D `0x00000000` =
(default)<br> ACPI + Devicetree =3D `0x00000001` <br> Devicetree =3D `0x0=
+ACPI fan control | `FanOnGpio` | Disable =3D `0x00000000` <b=
r> Otherwise numeric GPIO pin
+ACPI fan temperature | `FanTemp` | Hex numeric value degrees C
+ACPI XHCI/PCIe | `XhciPci` | Xhci =3D `0x00000000` <br> PC=
Ie =3D `0x00000001` <br> always PCIe `0x00000002`
+DT Reload XHCI firmware | `XhciReload` | Disable =3D `0x00000000` <=
br> Enabled=3D `0x00000001`
+Export GPIO devices to OS | `EnableGpio` | Disable =3D `0x00000000` <=
br> Enabled=3D `0x00000001`
Asset Tag | `AssetTag` | String, 32 characters or les=
s (e.g. `L"ABCD123"`)<br> (default `L""`)
**SD/MMC Configuration** |
uSD/eMMC Routing | `SdIsArasan` | Arasan SDHC =3D `0x0000000=
1` <br> eMMC2 SDHCI =3D `0x00000000` (default)

Join {devel@edk2.groups.io to automatically receive all group messages.