[PATCH v5 edk2-platforms 22/22] Platform/RaspberryPi/RPi3: Add platform readme's

[Pete Batard <pete@akeo.ie>]

Documentation is split between general plaform data and OS testing
and installation details.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Pete Batard <pete@akeo.ie>
---
 Platform/RaspberryPi/RPi3/Readme.md  | 167 ++++++++++++++++++++
 Platform/RaspberryPi/RPi3/Systems.md |  65 ++++++++
 Readme.md                            |   3 +
 3 files changed, 235 insertions(+)

diff --git a/Platform/RaspberryPi/RPi3/Readme.md b/Platform/RaspberryPi/RPi3/Readme.md
new file mode 100644
index 000000000000..7434233df0fb
--- /dev/null
+++ b/Platform/RaspberryPi/RPi3/Readme.md
@@ -0,0 +1,167 @@
+Raspberry Pi Platform
+=====================
+
+# Summary
+
+This is a port of 64-bit Tiano Core UEFI firmware for the Raspberry Pi 3/3B+ platforms,
+based on [Ard Bisheuvel's 64-bit](http://www.workofard.com/2017/02/uefi-on-the-pi/)
+and [Microsoft's 32-bit](https://github.com/ms-iot/RPi-UEFI/tree/ms-iot/Pi3BoardPkg)
+implementations, as maintained by [Andrei Warkentin](https://github.com/andreiw/RaspberryPiPkg).
+
+This is meant as a generally useful 64-bit ATF + UEFI implementation for the Raspberry
+Pi 3/3B+ which should be good enough for most kind of UEFI development, as well as for
+running consummer Operating Systems in such as Linux or Windows.
+
+Raspberry Pi is a trademark of the [Raspberry Pi Foundation](http://www.raspberrypi.org).
+
+# Status
+
+This firmware, that has been validated to compile against the current
+[edk2](https://github.com/tianocore/edk2)/[edk2-platforms](https://github.com/tianocore/edk2-platforms),
+should be able to boot Linux (SUSE, Ubuntu), NetBSD, FreeBSD as well as Windows 10 ARM64
+(full GUI version).
+
+It also provides support for ATF ([Arm Trusted Platform](https://github.com/ARM-software/arm-trusted-firmware)).
+
+HDMI and the mini-UART serial port can be used for output devices, with mirrored output.
+USB keyboards and the mini-UART serial port can be used as input.
+
+On a freshly built firmware, the default is to boot the UEFI shell.
+To change the default boot order (for instance to boot uSD media by default) you
+will need to edit the preferences in _Boot Maintenance Manager_.
+
+For additional information about the tested systems and how to set them up,
+please see [Systems.md](./Systems.md).
+
+# Building
+
+Build instructions from the top level edk2-platforms Readme.md apply.
+
+# Booting the firmware
+
+1. Format a uSD card as FAT32
+2. Copy the generated `RPI_EFI.fd` firmware onto the partition
+3. Download and copy the following files from https://github.com/raspberrypi/firmware/tree/master/boot
+  - `bootcode.bin`
+  - `fixup.dat`
+  - `start.elf`
+4. Create a `config.txt` with the following content:
+  ```
+  arm_control=0x200
+  enable_uart=1
+  armstub=RPI_EFI.fd
+  disable_commandline_tags=1
+  ```
+5. Insert the uSD card and power up the Pi.
+
+Note that if you have a model 3+ or a model 3 where you enabled USB boot through OTP
+(see [here](https://www.raspberrypi.org/documentation/hardware/raspberrypi/bootmodes/msd.md))
+you may also be able to boot from a FAT32 USB driver rather than uSD.
+
+# Notes
+
+## ARM Trusted Firmware (ATF)
+
+The ATF binaries being used were compiled from the latest ATF source.
+No aleration to the official source have been applied.
+
+For more details on the ATF compilation, see the [Readme](./TrustedFirmware/Readme.md)
+in the `TrustedFirmware/` directory.
+
+## Custom Device Tree
+
+The default Device Tree included in the firmware is the one for a Raspberry Pi 3 Model B (not B+).
+If you want to use a different Device Tree, to boot a Pi 3 Model B+ for instance (for which a
+DTB is also provided under `DeviceTree/`), you should copy the relevant `.dtb` into the root of
+the SD or USB, and then edit your `config.txt` so that it looks like:
+
+```
+(...)
+disable_commandline_tags=2
+device_tree_address=0x10000
+device_tree_end=0x20000
+device_tree=bcm2710-rpi-3-b-plus.dtb
+```
+
+Note: the address range **must** be `[0x10000:0x20000]`.
+`dtoverlay` and `dtparam` parameters are also supported **when** providing a Device Tree`.
+
+## Custom `bootargs`
+
+This firmware will honor the command line passed by the GPU via `cmdline.txt`.
+
+Note, that the ultimate contents of `/chosen/bootargs` are a combination of several pieces:
+- Original `/chosen/bootargs` if using the internal DTB. Seems to be completely discarded by GPU when booting with a custom device tree.
+- GPU-passed hardware configuration. This one is always present.
+- Additional boot options passed via `cmdline.txt`.
+
+# Limitations
+
+## HDMI
+
+The UEFI HDMI video support relies on the VC (that's the GPU)
+firmware to correctly detect and configure the attached screen.
+Some screens are slow, and this detection may not occur fast
+enough. Finally, you may wish to be able to boot your Pi
+headless, yet be able to attach a display to it later for
+debugging.
+
+To accommodate these issues, the following extra lines
+are recommended for your `config.txt`:
+- `hdmi_force_hotplug=1` to allow plugging in video after system is booted.
+- `hdmi_group=1` and `hdmi_mode=4` to force a specific mode, both to accommodate
+   late-plugged screens or buggy/slow screens. See [official documentation](https://www.raspberrypi.org/documentation/configuration/config-txt/video.md)
+   to make sense of these parameters (example above sets up 720p 60Hz).
+
+## NVRAM
+
+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 made from a High Level
+Operating System (HLOS) aren't.
+
+## RTC
+
+The Rasberry Pi has no RTC.
+
+An `RtcEpochSeconds` NVRAM variable is used to store the boot time.
+This should allow you to set whatever date/time you want using the Shell date and
+time commands. While in UEFI or HLOS, the time will tick forward.
+`RtcEpochSeconds` is not updated on reboots.
+
+## uSD
+
+UEFI supports both the Arasan SDHCI and the Broadcom SDHost controllers to access the uSD slot.
+You can use either. The other controller gets routed to the SDIO card. The choice made will
+impact ACPI OSes booted (e.g. Windows 10). Arasan, being an SDIO controller, is usually used
+with the WiFi adapter where available. SDHost cannot be used with SDIO. In UEFI setup screen:
+- go to `Device Manager`
+- go to `Raspberry Pi Configuration`
+- go to `Chipset`
+- configure `Boot uSD Routing`
+
+Known issues:
+- Arasan HS/4bit support is missing.
+- No 8 bit mode support for (e)MMC (irrelevant for the Pi 3).
+- Hacky (e)MMC support (no HS).
+- No card removal/replacement detection, tons of timeouts and slow down during boot without an uSD card present.
+
+## USB
+
+- USB1 BBB mass storage devices untested (USB2 and USB3 devices are fine).
+- USB1 CBI mass storage devices don't work (e.g. HP FD-05PUB floppy).
+
+## ACPI
+
+Both Arasan and SDHost SD controllers are exposed.
+
+Note that the ACPI tables were derived or copied from the MS-IoT one. This means that they
+are not truly ACPI compliant, especially when it comes to their descriptors, and therefore
+not suitable for Linux environments. If you want to use a Linux HLOS, you are encouraged to
+install a kernel that relies on Device Tree rather than ACPI.
+
+## Missing Functionality
+
+- Network booting via onboard NIC.
+- Ability to switch UART use to PL011.
diff --git a/Platform/RaspberryPi/RPi3/Systems.md b/Platform/RaspberryPi/RPi3/Systems.md
new file mode 100644
index 000000000000..f6410eb25f0d
--- /dev/null
+++ b/Platform/RaspberryPi/RPi3/Systems.md
@@ -0,0 +1,65 @@
+# Tested Operating Systems
+
+## Ubuntu
+
+[Ubuntu 18.04 LTS](http://releases.ubuntu.com/18.04/) has been tested and confirmed to work,
+on a Raspberry 3 Model B, including the installation process. Note however that network
+installation and networking may not work on the Model B+, due to the `lan78xx` Linux driver
+still requiring some support.
+
+Below are the steps you can follow to install Ubuntu LTS onto SD/USB:
+* Download the latest Ubuntu LTS ARM64 [`mini.iso`](http://ports.ubuntu.com/ubuntu-ports/dists/bionic/main/installer-arm64/current/images/netboot/mini.iso).
+* Partition the media as MBR and create a ~200 MB FAT32 partition on it with MBR type `0x0c`.
+  Note: Do not be tempted to use GPT partition scheme or `0xef` (EFI System Partition) for the
+  type, as none of these are supported by the Raspberry Pi's internal boot rom.
+* Extract the full content of the ISO onto the partition you created.
+* Also extract the GRUB EFI bootloader `bootaa64.efi` from `/boot/grub/efi.img` to `/boot/grub/`.
+  Note: Do not be tempted to copy this file to another directory (such as `/efi/boot/`) as GRUB looks for its
+  modules and configuration data in the same directory as the EFI loader and also, the installation
+  process will create a `bootaa64.efi` into `/efi/boot/`.
+* If needed, copy the UEFI firmware files (`RPI_EFI.fd`, `bootcode.bin`, `fixup.dat` and `start.elf`)
+  onto the FAT partition.
+* Boot the pi and let it go into the UEFI shell.
+* Navigate to `fs0:` then `/boot/grub/` and launch the GRUB efi loader.
+* Follow the Ubuntu installation process.
+
+Note: Because Ubuntu operates in quiet mode by default (no boot messages), you may think the system is frozen
+on first reboot after installation. However, if you wait long enough you **will** get to a login prompt.
+
+Once Linux is running, if desired, you can disable quiet boot, as well as force the display
+of the GRUB selector, by editing `/etc/default/grub` and changing:
+* `GRUB_TIMEOUT_STYLE=hidden` &rarr; `GRUB_TIMEOUT_STYLE=menu`
+* `GRUB_CMDLINE_LINUX_DEFAULT="splash quiet"` &rarr; `GRUB_CMDLINE_LINUX_DEFAULT=""`
+
+Then, to have your changes applied run `update-grub` and reboot.
+
+## Other Linux distributions
+
+* Debian ARM64 does not currently work, most likely due to missing required module support
+  in its kernel. However its installation process works, so it may be possible to get it
+  running with a custom kernel.
+
+* OpenSUSE Leap 42.3 has been reported to work on Raspberry 3 Model B.
+
+* Other ARM64 Linux releases, that support UEFI boot and have the required hardware support
+  for Pi hardware are expected to run, though their installation process might require some
+  cajoling.
+
+## Windows
+
+Windows 10 1809 for ARM64 (build 17763) has been tested and confirmed to work (after replacing
+`C:\Windows\System32\Drivers\WppRecorder.sys` with an older version, since the one from 1809
+appears to be buggy across all archs, and results in a similar BSOD when trying to run Windows
+To Go on x64 with native drivers for instance).
+
+Windows 10 1803 for ARM64 and earlier do not work due to the presence of a hardware ASSERT check
+in the Windows kernel, that was removed in later versions.
+
+You probably want to look at https://www.worproject.ml/ as well as the
+[Windows thread in the original RaspberryPiPkg](https://github.com/andreiw/RaspberryPiPkg/issues/12)
+for installation details.
+
+## Other platforms
+
+Details you may need to run other platforms, including FreeBSD, is provided in the
+[Readme from the original RaspberryPiPkg](https://github.com/andreiw/RaspberryPiPkg).
diff --git a/Readme.md b/Readme.md
index 384b1d3c5e2b..95c0c145224b 100644
--- a/Readme.md
+++ b/Readme.md
@@ -217,6 +217,9 @@ they will be documented with the platform.
 ## Marvell
 * [Armada 70x0](Platform/Marvell/Armada)
 
+## Raspberry Pi
+* [Pi 3](Platform/RaspberryPi/RPi3)
+
 ## Socionext
 * [SynQuacer](Platform/Socionext/DeveloperBox)
 
-- 
2.17.0.windows.1