[edk2-platforms: PATCH v2 0/1] Platform/RPi3: Add Debian 10 installation in Systems.md

[edk2-platforms: PATCH v2 0/1] Platform/RPi3: Add Debian 10 installation in Systems.md

[Pete Batard]

Sending a v2 that fixes a few typos:
"In that is the case" -> "If that is the case"
"that you can safely ignore it by selecting" -> "that you can safely ignore by selecting"
"prevents the same partition to be remounted" -> "prevents the same partition from being remounted"

Pete Batard (1):
  Platform/RPi3: Add Debian 10 installation in Systems.md

 Platform/RaspberryPi/RPi3/RPi3.fdf   |   2 +-
 Platform/RaspberryPi/RPi3/Readme.md  |   4 +-
 Platform/RaspberryPi/RPi3/Systems.md | 124 +++++++++++++++++++-
 3 files changed, 123 insertions(+), 7 deletions(-)

-- 
2.21.0.windows.1

[edk2-platforms: PATCH v2 1/1] Platform/RPi3: Add Debian 10 installation in Systems.md

[Pete Batard]

This documents the installation of vanilla Debian 10.0 ARM64 (netinst),
which we validated for both Model B and Model B+.
Also fix an erroneous reference in an RPi3.fdf comment.

Signed-off-by: Pete Batard <pete@akeo.ie>
---
 Platform/RaspberryPi/RPi3/RPi3.fdf   |   2 +-
 Platform/RaspberryPi/RPi3/Readme.md  |   4 +-
 Platform/RaspberryPi/RPi3/Systems.md | 124 +++++++++++++++++++-
 3 files changed, 123 insertions(+), 7 deletions(-)

diff --git a/Platform/RaspberryPi/RPi3/RPi3.fdf b/Platform/RaspberryPi/RPi3/RPi3.fdf
index c7c3f7a2ab8c..c62d649834c7 100644
--- a/Platform/RaspberryPi/RPi3/RPi3.fdf
+++ b/Platform/RaspberryPi/RPi3/RPi3.fdf
@@ -300,7 +300,7 @@ [FV.FvMain]
   INF Platform/RaspberryPi/$(PLATFORM_NAME)/Drivers/LogoDxe/LogoDxe.inf
 
   #
-  # FDT (GUID matches mRaspberryPiFfsFileGuid in RaspberryPiPlatformDxe)
+  # FDT (GUID matches gRaspberryPiFdtFileGuid in FdtDxe)
   #
   FILE FREEFORM = DF5DA223-1D27-47C3-8D1B-9A41B55A18BC {
     SECTION RAW = Platform/RaspberryPi/$(PLATFORM_NAME)/DeviceTree/bcm2710-rpi-3-b.dtb
diff --git a/Platform/RaspberryPi/RPi3/Readme.md b/Platform/RaspberryPi/RPi3/Readme.md
index 624f3a8d287a..797da1bab4a9 100644
--- a/Platform/RaspberryPi/RPi3/Readme.md
+++ b/Platform/RaspberryPi/RPi3/Readme.md
@@ -18,8 +18,8 @@ Raspberry Pi is a trademark of the [Raspberry Pi Foundation](http://www.raspberr
 
 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).
+should be able to boot Linux (Debian, Ubuntu, SUSE), 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)).
 
diff --git a/Platform/RaspberryPi/RPi3/Systems.md b/Platform/RaspberryPi/RPi3/Systems.md
index f6410eb25f0d..4a0c6f3e4de3 100644
--- a/Platform/RaspberryPi/RPi3/Systems.md
+++ b/Platform/RaspberryPi/RPi3/Systems.md
@@ -1,5 +1,125 @@
 # Tested Operating Systems
 
+## Debian
+
+[Debian 10](https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/) netinst has been
+tested and confirmed to work, both on the Model B and Model B+, including installation in
+either wired or wireless mode.
+
+Below are steps you can follow to install Debian 10 onto an SD card:
+* Partition the media as MBR and create a ~300 MB partition on it with MBR type `0x0e`.
+  __Note:__ Make sure that the partition scheme is MBR (not GPT) and the type `0x0e` (not
+  `0xef` for instance), as the ondie Broadcom bootloader supports neither the GPT scheme nor
+  the ESP MBR type.
+* Set the partition as active/bootable. This is needed as the Debian partition manager can
+  not detect it as ESP otherwise, which we need for GRUB installation. If using `fdisk` on
+  Linux, you can use the `a` command to set a partition as active. On Windows, you can use
+  `DISKPART` and then type `active` after selecting the relevant disk and partition.
+* Format the partition as FAT. Here again you should make sure that you use FAT rather than
+  FAT32 else the Debian partition manager will not detect the partition as ESP. If you
+  are using Windows `DISKPART` then `format fs=fat quick` should do it. On Linux, `mkfs.vfat`
+  with the default options should do the same as long as the partition isn't too large.
+* Copy the UEFI firmware files (`RPI_EFI.fd`, `bootcode.bin`, `fixup.dat` and `start.elf`)
+  as well as an appropriate `config.txt` onto the FAT partition. If needed you can download
+  the non UEFI binary files from https://github.com/raspberrypi/firmware/tree/master/boot.
+* (Optional) If you plan to install through WiFi, you will need to download relevant non-free
+   WLAN firmware binaries from your WLAN interface (`brcmfmac43430-sdio.txt` and
+  `brcmfmac43430-sdio.bin` for a Raspberry Pi 3 Model B, `brcmfmac43455-sdio.txt` and
+  `brcmfmac43455-sdio.bin` for a Raspberry Pi 3 Model B+). You may also want to obtain the
+  relevant `.clm_blob` (`brcmfmac43430-sdio.clm_blob` or `brcmfmac43455-sdio.clm_blob`),
+  though wireless networking should work even if you do not provide these files. Copy these
+  files either at the root of your FAT partition or into a `firmware/` directory there.
+* Download the latest `debian-##.#.#-arm64-netinst.iso` from
+  https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/
+* Extract the full content of the ISO onto the FAT partition you created.
+* Insert the media and power up the Raspberry Pi device.
+* On the GRUB menu select `Install` and let the Debian Installer process start.
+  __Note:__ In case anything goes wrong during the install process, you can use
+  <kbd>Alt</kbd>-<kbd>F4</kbd> to check the installation log.
+* Select your Language, Country and Keyboard and let the installer proceed until it reports
+  that `No Common CD-ROM drive was detected.`
+* On `Load CD-ROM drivers from removable media` select `No`.
+* On `Manually select a CD-ROM module and device` select `Yes`.
+* On `Module needed for accessing the CD-ROM` select `none`.
+* On `Device file for accessing the CD-ROM` type the following exactly:
+  ```
+  -t vfat -o rw /dev/mmcblk0p1
+  ```
+* (Optional) If you have copied the non-free WLAN firmware binaries, and plan to install
+  through wireless, you can let the installer select the firmware files. Please be mindful
+  that you may be asked multiple times as there are multiple files to provide.
+* If requested by the installer, set up your network by choosing the network interface you
+  want to use for installation and (optionally) your access point and credentials.
+* Go through the hostname, user/password set up and customize those as you see fit.
+* Let the installer continue until you get to the `Partition disks` screen. There, for
+  `Partitioning method` select `Manual`. You __should__ see something like this:
+  ```
+  MMC/SD card #1 (mmcblk0) - 16.0 GB SD 2WCGO
+       #1  primary  314.6 MB  B  K  ESP
+           pri/log                  FREE SPACE
+  ```
+  In other words, the partition manager should already detect your existing partition as
+  `ESP`, with the `B` (bootable) and `K` (keep data) flags. If that is not the case, (e.g.
+  if it says `fat16` or `fat32` instead of `ESP`) then it probably means you either didn't
+  format the partition to FAT or you forgot to set the bootable flag. If that is the case,
+  refer to the _Additional Notes:_ below.
+* Select `FREE SPACE` &rarr; `Create a new partition` and create a `1 GB` primary `swap`
+  partition.
+* Select `FREE SPACE` &rarr; `Create a new partition` and allocate the rest to a primary
+ `ext4` root partition (mountpoint = `/`)
+* After doing the above, your partition report should look like this:
+  ```
+  MMC/SD card #1 (mmcblk0) - 16.0 GB SD 2WCGO
+       #1  primary  314.6 MB  B  K  ESP
+       #2  primary    1.0 GB     f  swap    swap
+       #3  primary   14.7 GB     f  ext4    /
+  ```
+* Select `Finish partitioning and write changes to disk` and then `Yes` and let the
+  installer continue with the base system installation.
+* After a while, the installer should produce a message that states:
+  ```
+  [!!] Configure the package manager
+
+  apt-configuration problem
+  An attempt to configure apt to install additional packages from the CD failed.
+  ```
+  This is a __benign__ message that you can safely ignore by selecting `Continue` (The
+  reason it is benign is we are running a net install and won't need to access the "CD-ROM"
+  files post install).
+* Once you have dimissed the message above, pick the mirror closest to your geographical
+  location and let the installer proceed with some more software installation.
+* Finally, at the `Software selection` screen, choose any additional software package you
+  wish to install. `Debian desktop environment` should work out of the box if you choose to
+  install it.
+* Let the process finalize the software and GRUB bootloader installation and, provided you
+  didn't run into the partition manager issue described above (installation partition not
+  seen as `ESP`) you can reboot your machine when prompted, which, once completed, should
+  bring you to your newly installed Debian environment.
+
+### Additional Notes for Debian
+
+The reason we use `-t vfat -o rw /dev/mmcblk0p1` for the source media (i.e. "CD-ROM" device)
+is because, whereas the first partition on the SD card is indeed `/dev/mmcblk0p1`, we also
+need to provide additional parameters for the `mount` command that the installer invokes
+behind the scenes. For instance, if we don't use `-t vfat`, then ISO-9660 is forced as the
+file system, and if we don't use `-o rw` then the partition will be mounted as read-only
+which then prevents the same partition from being remounted when locating the non-free
+firmware files or when setting up `/efi/boot`.
+
+With regards to fixing the partitioning if you don't see `B  K  ESP` when entering the
+partition manager, what you need to do is:
+* Before you create the additional partitions, select the first partition and change its
+  type to `ESP`. Note however that doing this will change the type of the partition to `0xef`
+  which is precisely what we're trying to avoid by having the partition manager already
+  detect it as ESP, as type `0xef` is __unbootable__ by the Broadcom CPU.
+* To fix this then, before you choose `Continue` on the `Installation complete` prompt you
+  need to open a new console (<kbd>Alt</kbd>-<kbd>F2</kbd>) and then type:
+  ```
+  chroot /target fdisk /dev/mmcblk0
+  ```
+  Then press <kbd>t</kbd>, <kbd>1</kbd>, <kbd>e</kbd> <kbd>w</kbd>, to reset the partition
+  to type `0x0e` (FAT16 LBA).
+
 ## Ubuntu
 
 [Ubuntu 18.04 LTS](http://releases.ubuntu.com/18.04/) has been tested and confirmed to work,
@@ -35,10 +155,6 @@ 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
-- 
2.21.0.windows.1

Re: [edk2-platforms: PATCH v2 1/1] Platform/RPi3: Add Debian 10 installation in Systems.md

[Leif Lindholm]

Minor suggestions inline:

On Thu, Jul 25, 2019 at 04:22:48PM +0100, Pete Batard wrote:
> This documents the installation of vanilla Debian 10.0 ARM64 (netinst),
> which we validated for both Model B and Model B+.
> Also fix an erroneous reference in an RPi3.fdf comment.
> 
> Signed-off-by: Pete Batard <pete@akeo.ie>
> ---
>  Platform/RaspberryPi/RPi3/RPi3.fdf   |   2 +-
>  Platform/RaspberryPi/RPi3/Readme.md  |   4 +-
>  Platform/RaspberryPi/RPi3/Systems.md | 124 +++++++++++++++++++-
>  3 files changed, 123 insertions(+), 7 deletions(-)
> 
> diff --git a/Platform/RaspberryPi/RPi3/RPi3.fdf b/Platform/RaspberryPi/RPi3/RPi3.fdf
> index c7c3f7a2ab8c..c62d649834c7 100644
> --- a/Platform/RaspberryPi/RPi3/RPi3.fdf
> +++ b/Platform/RaspberryPi/RPi3/RPi3.fdf
> @@ -300,7 +300,7 @@ [FV.FvMain]
>    INF Platform/RaspberryPi/$(PLATFORM_NAME)/Drivers/LogoDxe/LogoDxe.inf
>  
>    #
> -  # FDT (GUID matches mRaspberryPiFfsFileGuid in RaspberryPiPlatformDxe)
> +  # FDT (GUID matches gRaspberryPiFdtFileGuid in FdtDxe)
>    #
>    FILE FREEFORM = DF5DA223-1D27-47C3-8D1B-9A41B55A18BC {
>      SECTION RAW = Platform/RaspberryPi/$(PLATFORM_NAME)/DeviceTree/bcm2710-rpi-3-b.dtb
> diff --git a/Platform/RaspberryPi/RPi3/Readme.md b/Platform/RaspberryPi/RPi3/Readme.md
> index 624f3a8d287a..797da1bab4a9 100644
> --- a/Platform/RaspberryPi/RPi3/Readme.md
> +++ b/Platform/RaspberryPi/RPi3/Readme.md
> @@ -18,8 +18,8 @@ Raspberry Pi is a trademark of the [Raspberry Pi Foundation](http://www.raspberr
>  
>  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).
> +should be able to boot Linux (Debian, Ubuntu, SUSE), 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)).
>  
> diff --git a/Platform/RaspberryPi/RPi3/Systems.md b/Platform/RaspberryPi/RPi3/Systems.md
> index f6410eb25f0d..4a0c6f3e4de3 100644
> --- a/Platform/RaspberryPi/RPi3/Systems.md
> +++ b/Platform/RaspberryPi/RPi3/Systems.md
> @@ -1,5 +1,125 @@
>  # Tested Operating Systems
>  
> +## Debian
> +
> +[Debian 10](https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/) netinst has been
> +tested and confirmed to work, both on the Model B and Model B+, including installation in
> +either wired or wireless mode.
> +
> +Below are steps you can follow to install Debian 10 onto an SD card:
> +* Partition the media as MBR and create a ~300 MB partition on it with MBR type `0x0e`.
> +  __Note:__ Make sure that the partition scheme is MBR (not GPT) and the type `0x0e` (not
> +  `0xef` for instance), as the ondie Broadcom bootloader supports neither the GPT scheme nor

ondie -> on-die (or on-SoC may be even more clear to civilians).

> +  the ESP MBR type.
> +* Set the partition as active/bootable. This is needed as the Debian partition manager can
> +  not detect it as ESP otherwise, which we need for GRUB installation. If using `fdisk` on
> +  Linux, you can use the `a` command to set a partition as active. On Windows, you can use
> +  `DISKPART` and then type `active` after selecting the relevant disk and partition.
> +* Format the partition as FAT. Here again you should make sure that you use FAT rather than
> +  FAT32 else the Debian partition manager will not detect the partition as ESP. If you
> +  are using Windows `DISKPART` then `format fs=fat quick` should do it. On Linux, `mkfs.vfat`
> +  with the default options should do the same as long as the partition isn't too large.

It would be preferable if we could have an actual number here - the
12-bit, 16-bit and 32-bit fat size switchover points are known. I
assume it is the 32-bit breakpoint (2 or 4Gb?) we want to avoid?

/
    Leif

> +* Copy the UEFI firmware files (`RPI_EFI.fd`, `bootcode.bin`, `fixup.dat` and `start.elf`)
> +  as well as an appropriate `config.txt` onto the FAT partition. If needed you can download
> +  the non UEFI binary files from https://github.com/raspberrypi/firmware/tree/master/boot.
> +* (Optional) If you plan to install through WiFi, you will need to download relevant non-free
> +   WLAN firmware binaries from your WLAN interface (`brcmfmac43430-sdio.txt` and
> +  `brcmfmac43430-sdio.bin` for a Raspberry Pi 3 Model B, `brcmfmac43455-sdio.txt` and
> +  `brcmfmac43455-sdio.bin` for a Raspberry Pi 3 Model B+). You may also want to obtain the
> +  relevant `.clm_blob` (`brcmfmac43430-sdio.clm_blob` or `brcmfmac43455-sdio.clm_blob`),
> +  though wireless networking should work even if you do not provide these files. Copy these
> +  files either at the root of your FAT partition or into a `firmware/` directory there.
> +* Download the latest `debian-##.#.#-arm64-netinst.iso` from
> +  https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/
> +* Extract the full content of the ISO onto the FAT partition you created.
> +* Insert the media and power up the Raspberry Pi device.
> +* On the GRUB menu select `Install` and let the Debian Installer process start.
> +  __Note:__ In case anything goes wrong during the install process, you can use
> +  <kbd>Alt</kbd>-<kbd>F4</kbd> to check the installation log.
> +* Select your Language, Country and Keyboard and let the installer proceed until it reports
> +  that `No Common CD-ROM drive was detected.`
> +* On `Load CD-ROM drivers from removable media` select `No`.
> +* On `Manually select a CD-ROM module and device` select `Yes`.
> +* On `Module needed for accessing the CD-ROM` select `none`.
> +* On `Device file for accessing the CD-ROM` type the following exactly:
> +  ```
> +  -t vfat -o rw /dev/mmcblk0p1
> +  ```
> +* (Optional) If you have copied the non-free WLAN firmware binaries, and plan to install
> +  through wireless, you can let the installer select the firmware files. Please be mindful
> +  that you may be asked multiple times as there are multiple files to provide.
> +* If requested by the installer, set up your network by choosing the network interface you
> +  want to use for installation and (optionally) your access point and credentials.
> +* Go through the hostname, user/password set up and customize those as you see fit.
> +* Let the installer continue until you get to the `Partition disks` screen. There, for
> +  `Partitioning method` select `Manual`. You __should__ see something like this:
> +  ```
> +  MMC/SD card #1 (mmcblk0) - 16.0 GB SD 2WCGO
> +       #1  primary  314.6 MB  B  K  ESP
> +           pri/log                  FREE SPACE
> +  ```
> +  In other words, the partition manager should already detect your existing partition as
> +  `ESP`, with the `B` (bootable) and `K` (keep data) flags. If that is not the case, (e.g.
> +  if it says `fat16` or `fat32` instead of `ESP`) then it probably means you either didn't
> +  format the partition to FAT or you forgot to set the bootable flag. If that is the case,
> +  refer to the _Additional Notes:_ below.
> +* Select `FREE SPACE` &rarr; `Create a new partition` and create a `1 GB` primary `swap`
> +  partition.
> +* Select `FREE SPACE` &rarr; `Create a new partition` and allocate the rest to a primary
> + `ext4` root partition (mountpoint = `/`)
> +* After doing the above, your partition report should look like this:
> +  ```
> +  MMC/SD card #1 (mmcblk0) - 16.0 GB SD 2WCGO
> +       #1  primary  314.6 MB  B  K  ESP
> +       #2  primary    1.0 GB     f  swap    swap
> +       #3  primary   14.7 GB     f  ext4    /
> +  ```
> +* Select `Finish partitioning and write changes to disk` and then `Yes` and let the
> +  installer continue with the base system installation.
> +* After a while, the installer should produce a message that states:
> +  ```
> +  [!!] Configure the package manager
> +
> +  apt-configuration problem
> +  An attempt to configure apt to install additional packages from the CD failed.
> +  ```
> +  This is a __benign__ message that you can safely ignore by selecting `Continue` (The
> +  reason it is benign is we are running a net install and won't need to access the "CD-ROM"
> +  files post install).
> +* Once you have dimissed the message above, pick the mirror closest to your geographical
> +  location and let the installer proceed with some more software installation.
> +* Finally, at the `Software selection` screen, choose any additional software package you
> +  wish to install. `Debian desktop environment` should work out of the box if you choose to
> +  install it.
> +* Let the process finalize the software and GRUB bootloader installation and, provided you
> +  didn't run into the partition manager issue described above (installation partition not
> +  seen as `ESP`) you can reboot your machine when prompted, which, once completed, should
> +  bring you to your newly installed Debian environment.
> +
> +### Additional Notes for Debian
> +
> +The reason we use `-t vfat -o rw /dev/mmcblk0p1` for the source media (i.e. "CD-ROM" device)
> +is because, whereas the first partition on the SD card is indeed `/dev/mmcblk0p1`, we also
> +need to provide additional parameters for the `mount` command that the installer invokes
> +behind the scenes. For instance, if we don't use `-t vfat`, then ISO-9660 is forced as the
> +file system, and if we don't use `-o rw` then the partition will be mounted as read-only
> +which then prevents the same partition from being remounted when locating the non-free
> +firmware files or when setting up `/efi/boot`.
> +
> +With regards to fixing the partitioning if you don't see `B  K  ESP` when entering the
> +partition manager, what you need to do is:
> +* Before you create the additional partitions, select the first partition and change its
> +  type to `ESP`. Note however that doing this will change the type of the partition to `0xef`
> +  which is precisely what we're trying to avoid by having the partition manager already
> +  detect it as ESP, as type `0xef` is __unbootable__ by the Broadcom CPU.
> +* To fix this then, before you choose `Continue` on the `Installation complete` prompt you
> +  need to open a new console (<kbd>Alt</kbd>-<kbd>F2</kbd>) and then type:
> +  ```
> +  chroot /target fdisk /dev/mmcblk0
> +  ```
> +  Then press <kbd>t</kbd>, <kbd>1</kbd>, <kbd>e</kbd> <kbd>w</kbd>, to reset the partition
> +  to type `0x0e` (FAT16 LBA).
> +
>  ## Ubuntu
>  
>  [Ubuntu 18.04 LTS](http://releases.ubuntu.com/18.04/) has been tested and confirmed to work,
> @@ -35,10 +155,6 @@ 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
> -- 
> 2.21.0.windows.1
> 

Re: [edk2-platforms: PATCH v2 1/1] Platform/RPi3: Add Debian 10 installation in Systems.md

[Pete Batard]

Hi Leif,

On 2019.08.06 18:25, Leif Lindholm wrote:
> Minor suggestions inline:
> 
> On Thu, Jul 25, 2019 at 04:22:48PM +0100, Pete Batard wrote:
>> This documents the installation of vanilla Debian 10.0 ARM64 (netinst),
>> which we validated for both Model B and Model B+.
>> Also fix an erroneous reference in an RPi3.fdf comment.
>>
>> Signed-off-by: Pete Batard <pete@akeo.ie>
>> ---
>>   Platform/RaspberryPi/RPi3/RPi3.fdf   |   2 +-
>>   Platform/RaspberryPi/RPi3/Readme.md  |   4 +-
>>   Platform/RaspberryPi/RPi3/Systems.md | 124 +++++++++++++++++++-
>>   3 files changed, 123 insertions(+), 7 deletions(-)
>>
>> diff --git a/Platform/RaspberryPi/RPi3/RPi3.fdf b/Platform/RaspberryPi/RPi3/RPi3.fdf
>> index c7c3f7a2ab8c..c62d649834c7 100644
>> --- a/Platform/RaspberryPi/RPi3/RPi3.fdf
>> +++ b/Platform/RaspberryPi/RPi3/RPi3.fdf
>> @@ -300,7 +300,7 @@ [FV.FvMain]
>>     INF Platform/RaspberryPi/$(PLATFORM_NAME)/Drivers/LogoDxe/LogoDxe.inf
>>   
>>     #
>> -  # FDT (GUID matches mRaspberryPiFfsFileGuid in RaspberryPiPlatformDxe)
>> +  # FDT (GUID matches gRaspberryPiFdtFileGuid in FdtDxe)
>>     #
>>     FILE FREEFORM = DF5DA223-1D27-47C3-8D1B-9A41B55A18BC {
>>       SECTION RAW = Platform/RaspberryPi/$(PLATFORM_NAME)/DeviceTree/bcm2710-rpi-3-b.dtb
>> diff --git a/Platform/RaspberryPi/RPi3/Readme.md b/Platform/RaspberryPi/RPi3/Readme.md
>> index 624f3a8d287a..797da1bab4a9 100644
>> --- a/Platform/RaspberryPi/RPi3/Readme.md
>> +++ b/Platform/RaspberryPi/RPi3/Readme.md
>> @@ -18,8 +18,8 @@ Raspberry Pi is a trademark of the [Raspberry Pi Foundation](http://www.raspberr
>>   
>>   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).
>> +should be able to boot Linux (Debian, Ubuntu, SUSE), 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)).
>>   
>> diff --git a/Platform/RaspberryPi/RPi3/Systems.md b/Platform/RaspberryPi/RPi3/Systems.md
>> index f6410eb25f0d..4a0c6f3e4de3 100644
>> --- a/Platform/RaspberryPi/RPi3/Systems.md
>> +++ b/Platform/RaspberryPi/RPi3/Systems.md
>> @@ -1,5 +1,125 @@
>>   # Tested Operating Systems
>>   
>> +## Debian
>> +
>> +[Debian 10](https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/) netinst has been
>> +tested and confirmed to work, both on the Model B and Model B+, including installation in
>> +either wired or wireless mode.
>> +
>> +Below are steps you can follow to install Debian 10 onto an SD card:
>> +* Partition the media as MBR and create a ~300 MB partition on it with MBR type `0x0e`.
>> +  __Note:__ Make sure that the partition scheme is MBR (not GPT) and the type `0x0e` (not
>> +  `0xef` for instance), as the ondie Broadcom bootloader supports neither the GPT scheme nor
> 
> ondie -> on-die (or on-SoC may be even more clear to civilians).

I think I'll use "on-CPU" then, as this should be even more explicit.

>> +  the ESP MBR type.
>> +* Set the partition as active/bootable. This is needed as the Debian partition manager can
>> +  not detect it as ESP otherwise, which we need for GRUB installation. If using `fdisk` on
>> +  Linux, you can use the `a` command to set a partition as active. On Windows, you can use
>> +  `DISKPART` and then type `active` after selecting the relevant disk and partition.
>> +* Format the partition as FAT. Here again you should make sure that you use FAT rather than
>> +  FAT32 else the Debian partition manager will not detect the partition as ESP. If you
>> +  are using Windows `DISKPART` then `format fs=fat quick` should do it. On Linux, `mkfs.vfat`
>> +  with the default options should do the same as long as the partition isn't too large.
> 
> It would be preferable if we could have an actual number here - the
> 12-bit, 16-bit and 32-bit fat size switchover points are known. I
> assume it is the 32-bit breakpoint (2 or 4Gb?) we want to avoid?

The switchover point actually depends of the utility, since there is 
overlap between 12, 16 and 32. But that's not actually a problem with 
diskpart on Windows as 'fs=fat' does force FAT16 so you'll get an error 
if the partition is too large and can only accommodate FAT32 (which 
should usually occur past the 2 GB point).

In other words, the only potential issue here is with Linux' mkfs.vfat. 
But there too we can add a switch (-F 16) to force FAT16, so I'll alter 
the documentation to have that, plus a note that mentions that the 
partition should be under 2 GB.

I'll also take this opportunity to stress out that the only reason we 
are trying to force FAT16 here is because the Debian installer's 
partition manager is very temperamental with regards to its detection of 
an ESP that doesn't have either the relevant GUID for GPT or type 0xef 
for MBR, none of which can be used on a Pi. There are actually cases 
where I have seen that utility also detect a FAT32 MBR partition without 
type 0xef as an ESP. However, I have found out that, in most cases, the 
presence of FAT32 vs FAT16 acts as a switch to demote the partition from 
ESP, which is the reason why the notes promote the use of FAT16 over 
FAT32. But as mentioned in the additional notes however, it's still 
relatively easy to fix the ESP issue if you use FAT32 and/or if the 
Debian partition manager fails to detect it as ESP.

Now, one can only wish that Broadcom had anticipated UEFI usage for 
their hardcoded boot loader, as they'd only needed to have added 0xef, 
alongside the other FAT based MBR partition types they recognize for 
this whole annoyance to be avoided...

I'll send a v3 when I get a chance.

Regards,

/Pete

> 
> /
>      Leif
> 
>> +* Copy the UEFI firmware files (`RPI_EFI.fd`, `bootcode.bin`, `fixup.dat` and `start.elf`)
>> +  as well as an appropriate `config.txt` onto the FAT partition. If needed you can download
>> +  the non UEFI binary files from https://github.com/raspberrypi/firmware/tree/master/boot.
>> +* (Optional) If you plan to install through WiFi, you will need to download relevant non-free
>> +   WLAN firmware binaries from your WLAN interface (`brcmfmac43430-sdio.txt` and
>> +  `brcmfmac43430-sdio.bin` for a Raspberry Pi 3 Model B, `brcmfmac43455-sdio.txt` and
>> +  `brcmfmac43455-sdio.bin` for a Raspberry Pi 3 Model B+). You may also want to obtain the
>> +  relevant `.clm_blob` (`brcmfmac43430-sdio.clm_blob` or `brcmfmac43455-sdio.clm_blob`),
>> +  though wireless networking should work even if you do not provide these files. Copy these
>> +  files either at the root of your FAT partition or into a `firmware/` directory there.
>> +* Download the latest `debian-##.#.#-arm64-netinst.iso` from
>> +  https://cdimage.debian.org/debian-cd/current/arm64/iso-cd/
>> +* Extract the full content of the ISO onto the FAT partition you created.
>> +* Insert the media and power up the Raspberry Pi device.
>> +* On the GRUB menu select `Install` and let the Debian Installer process start.
>> +  __Note:__ In case anything goes wrong during the install process, you can use
>> +  <kbd>Alt</kbd>-<kbd>F4</kbd> to check the installation log.
>> +* Select your Language, Country and Keyboard and let the installer proceed until it reports
>> +  that `No Common CD-ROM drive was detected.`
>> +* On `Load CD-ROM drivers from removable media` select `No`.
>> +* On `Manually select a CD-ROM module and device` select `Yes`.
>> +* On `Module needed for accessing the CD-ROM` select `none`.
>> +* On `Device file for accessing the CD-ROM` type the following exactly:
>> +  ```
>> +  -t vfat -o rw /dev/mmcblk0p1
>> +  ```
>> +* (Optional) If you have copied the non-free WLAN firmware binaries, and plan to install
>> +  through wireless, you can let the installer select the firmware files. Please be mindful
>> +  that you may be asked multiple times as there are multiple files to provide.
>> +* If requested by the installer, set up your network by choosing the network interface you
>> +  want to use for installation and (optionally) your access point and credentials.
>> +* Go through the hostname, user/password set up and customize those as you see fit.
>> +* Let the installer continue until you get to the `Partition disks` screen. There, for
>> +  `Partitioning method` select `Manual`. You __should__ see something like this:
>> +  ```
>> +  MMC/SD card #1 (mmcblk0) - 16.0 GB SD 2WCGO
>> +       #1  primary  314.6 MB  B  K  ESP
>> +           pri/log                  FREE SPACE
>> +  ```
>> +  In other words, the partition manager should already detect your existing partition as
>> +  `ESP`, with the `B` (bootable) and `K` (keep data) flags. If that is not the case, (e.g.
>> +  if it says `fat16` or `fat32` instead of `ESP`) then it probably means you either didn't
>> +  format the partition to FAT or you forgot to set the bootable flag. If that is the case,
>> +  refer to the _Additional Notes:_ below.
>> +* Select `FREE SPACE` &rarr; `Create a new partition` and create a `1 GB` primary `swap`
>> +  partition.
>> +* Select `FREE SPACE` &rarr; `Create a new partition` and allocate the rest to a primary
>> + `ext4` root partition (mountpoint = `/`)
>> +* After doing the above, your partition report should look like this:
>> +  ```
>> +  MMC/SD card #1 (mmcblk0) - 16.0 GB SD 2WCGO
>> +       #1  primary  314.6 MB  B  K  ESP
>> +       #2  primary    1.0 GB     f  swap    swap
>> +       #3  primary   14.7 GB     f  ext4    /
>> +  ```
>> +* Select `Finish partitioning and write changes to disk` and then `Yes` and let the
>> +  installer continue with the base system installation.
>> +* After a while, the installer should produce a message that states:
>> +  ```
>> +  [!!] Configure the package manager
>> +
>> +  apt-configuration problem
>> +  An attempt to configure apt to install additional packages from the CD failed.
>> +  ```
>> +  This is a __benign__ message that you can safely ignore by selecting `Continue` (The
>> +  reason it is benign is we are running a net install and won't need to access the "CD-ROM"
>> +  files post install).
>> +* Once you have dimissed the message above, pick the mirror closest to your geographical
>> +  location and let the installer proceed with some more software installation.
>> +* Finally, at the `Software selection` screen, choose any additional software package you
>> +  wish to install. `Debian desktop environment` should work out of the box if you choose to
>> +  install it.
>> +* Let the process finalize the software and GRUB bootloader installation and, provided you
>> +  didn't run into the partition manager issue described above (installation partition not
>> +  seen as `ESP`) you can reboot your machine when prompted, which, once completed, should
>> +  bring you to your newly installed Debian environment.
>> +
>> +### Additional Notes for Debian
>> +
>> +The reason we use `-t vfat -o rw /dev/mmcblk0p1` for the source media (i.e. "CD-ROM" device)
>> +is because, whereas the first partition on the SD card is indeed `/dev/mmcblk0p1`, we also
>> +need to provide additional parameters for the `mount` command that the installer invokes
>> +behind the scenes. For instance, if we don't use `-t vfat`, then ISO-9660 is forced as the
>> +file system, and if we don't use `-o rw` then the partition will be mounted as read-only
>> +which then prevents the same partition from being remounted when locating the non-free
>> +firmware files or when setting up `/efi/boot`.
>> +
>> +With regards to fixing the partitioning if you don't see `B  K  ESP` when entering the
>> +partition manager, what you need to do is:
>> +* Before you create the additional partitions, select the first partition and change its
>> +  type to `ESP`. Note however that doing this will change the type of the partition to `0xef`
>> +  which is precisely what we're trying to avoid by having the partition manager already
>> +  detect it as ESP, as type `0xef` is __unbootable__ by the Broadcom CPU.
>> +* To fix this then, before you choose `Continue` on the `Installation complete` prompt you
>> +  need to open a new console (<kbd>Alt</kbd>-<kbd>F2</kbd>) and then type:
>> +  ```
>> +  chroot /target fdisk /dev/mmcblk0
>> +  ```
>> +  Then press <kbd>t</kbd>, <kbd>1</kbd>, <kbd>e</kbd> <kbd>w</kbd>, to reset the partition
>> +  to type `0x0e` (FAT16 LBA).
>> +
>>   ## Ubuntu
>>   
>>   [Ubuntu 18.04 LTS](http://releases.ubuntu.com/18.04/) has been tested and confirmed to work,
>> @@ -35,10 +155,6 @@ 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
>> -- 
>> 2.21.0.windows.1
>>

Re: [edk2-platforms: PATCH v2 1/1] Platform/RPi3: Add Debian 10 installation in Systems.md

[Leif Lindholm]

Hi Pete,

On Wed, Aug 07, 2019 at 03:24:10PM +0100, Pete Batard wrote:
> > > +Below are steps you can follow to install Debian 10 onto an SD card:
> > > +* Partition the media as MBR and create a ~300 MB partition on it with MBR type `0x0e`.
> > > +  __Note:__ Make sure that the partition scheme is MBR (not GPT) and the type `0x0e` (not
> > > +  `0xef` for instance), as the ondie Broadcom bootloader supports neither the GPT scheme nor
> > 
> > ondie -> on-die (or on-SoC may be even more clear to civilians).
> 
> I think I'll use "on-CPU" then, as this should be even more explicit.

Works for me.

> > > +  the ESP MBR type.
> > > +* Set the partition as active/bootable. This is needed as the Debian partition manager can
> > > +  not detect it as ESP otherwise, which we need for GRUB installation. If using `fdisk` on
> > > +  Linux, you can use the `a` command to set a partition as active. On Windows, you can use
> > > +  `DISKPART` and then type `active` after selecting the relevant disk and partition.
> > > +* Format the partition as FAT. Here again you should make sure that you use FAT rather than
> > > +  FAT32 else the Debian partition manager will not detect the partition as ESP. If you
> > > +  are using Windows `DISKPART` then `format fs=fat quick` should do it. On Linux, `mkfs.vfat`
> > > +  with the default options should do the same as long as the partition isn't too large.
> > 
> > It would be preferable if we could have an actual number here - the
> > 12-bit, 16-bit and 32-bit fat size switchover points are known. I
> > assume it is the 32-bit breakpoint (2 or 4Gb?) we want to avoid?
> 
> The switchover point actually depends of the utility, since there is overlap
> between 12, 16 and 32. But that's not actually a problem with diskpart on
> Windows as 'fs=fat' does force FAT16 so you'll get an error if the partition
> is too large and can only accommodate FAT32 (which should usually occur past
> the 2 GB point).
> 
> In other words, the only potential issue here is with Linux' mkfs.vfat. But
> there too we can add a switch (-F 16) to force FAT16, so I'll alter the
> documentation to have that, plus a note that mentions that the partition
> should be under 2 GB.

Sure, this is fine.

> I'll also take this opportunity to stress out that the only reason we are
> trying to force FAT16 here is because the Debian installer's partition
> manager is very temperamental with regards to its detection of an ESP that
> doesn't have either the relevant GUID for GPT or type 0xef for MBR, none of
> which can be used on a Pi. There are actually cases where I have seen that
> utility also detect a FAT32 MBR partition without type 0xef as an ESP.

Yeah, well. This is pretty much stacking ice cubes next to a furnace,
trying to create an ABI where there is none. Which is fine, because we
do need to provide documentation for non-experts - but this is also why
it needs to be precise, so we don't mislead experts.

> However, I have found out that, in most cases, the presence of FAT32 vs
> FAT16 acts as a switch to demote the partition from ESP, which is the reason
> why the notes promote the use of FAT16 over FAT32. But as mentioned in the
> additional notes however, it's still relatively easy to fix the ESP issue if
> you use FAT32 and/or if the Debian partition manager fails to detect it as
> ESP.

Sure. May be worth adding a forward-pointer to the additional notes
from here then?

> Now, one can only wish that Broadcom had anticipated UEFI usage for their
> hardcoded boot loader, as they'd only needed to have added 0xef, alongside
> the other FAT based MBR partition types they recognize for this whole
> annoyance to be avoided...

In my most optimistic hours, I sometimes dare to hope that the EBBR
explicitly stating these requirements will at some point in the future
start to make a difference.

> I'll send a v3 when I get a chance.

Thanks!

Regards.

Leif