Re: [PATCH v2 2/2] Platform/ARM: Add Readme.md

[Leif Lindholm <leif.lindholm@linaro.org>]

On Mon, Nov 26, 2018 at 01:17:48PM +0000, Nariman Poushin wrote:
> This covers the bulk of the information originally present in
> https://github.com/tianocore/tianocore.github.io/wiki/ArmPlatformPkg-AArch64
> regarding building and running the Foundation/Base FVP Platforms.
> 
> The sections on fetching source have been delegated to the root Readme.md
> 
> Signed-off-by: Nariman Poushin <nariman.poushin@linaro.org>

Detailed comments below.
Overall, the feedback is pretty much all either
- Please refer to top-level Readme.md for generic operations (and
  improve that if needed.).
or
- The wiki page is horribly outdated, so it's great you're taking this
  step and placing the instructions with the code, but you're basing
  it on something horribly outdated.

+Mark (Since he may actually have some links to less outdated
information on one of ARM's sites.)

(Apologies if reading the below feels like someone throwing bricks at you.)

> ---
>  Platform/ARM/Readme.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 102 insertions(+)
>  create mode 100644 Platform/ARM/Readme.md
> 
> diff --git a/Platform/ARM/Readme.md b/Platform/ARM/Readme.md
> new file mode 100644
> index 0000000..f6b97d3
> --- /dev/null
> +++ b/Platform/ARM/Readme.md
> @@ -0,0 +1,102 @@
> +== Introduction ==
> +These instructions are to build and run UEFI on the AArch64 Foundation or Base FVPs (Fixed Virtual Platforms). FVPs are fixed configurations of ARM Fast Models; they are also known as RTSMs (Real Time System Models). The Base FVP is an evolution of the VE (Versatile Express) RTSM.<br/>
> +While the AArch64 Foundation FVP is free to download, the Base FVP requires an ARM license. The Base FVP has additional debugging and configuration features.
> +
> +<b>Requirement:</b>
> +* A 32-bit or 64-bit Linux host machine. Support for MS
>    Windows-based toolchains has not been added to the EDK2
>    BaseTools.

(This is actually no longer true - although we are lacking certain
assembler files required to build most full platforms: my w-i-p can be
found at
https://git.linaro.org/people/leif.lindholm/edk2.git/log/?h=aarch64-vs
and lets you build several platforms with large bits of critical
assembler functionality stubbed out :)

"Building these platforms with Visual Studio is not yet supported."
would be a more accurate statement.

> +
> +== Getting the EDK2 Source with AArch64 support (ARM 64-bit architecture) ==
> +1) Get the requirements
> +
> +A Universally Unique Id (UUID) header. Needed to build the EDK2
> BaseTools. On Ubuntu: sudo apt-get install uuid-dev

This is mentioned in the top-level Readme.md (without the specific
commands). Please add to the text there if necessary.

> +
> +2) Download the sources
> +
> +Please see the root edk2/Readme.md for information on how to obtain the source

[Readme.md](../../Readme.md)

> +
> +== Build EDK2 Tianocore ==
> +
> +1) Install AArch64 GNU toolchain:
> +<pre>sudo apt install gcc-aarch64-linux-gnu</pre>

More like sudo apt-install gcc.
But still, this and the esoterics of cross compilation (for those that
prefer to faff around) is covered in the top-level Readme.md.

> +
> +2) Build EDK2:
> +
> +<pre>cd $(WORKSPACE)/edk2</pre>
> +* For the Foundation and Base FVPs (defined by the DSC file
>    ArmPlatformPkg?/ArmVExpressPkg/ArmVExpress-RTSM-AEMv8Ax4-foundation.dsc):

Yikes. That file hasn't existed for quite some time.
(edk2-platforms/)Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc
is what you want.

> +<pre>GCC5_AARCH64_PREFIX=aarch64-linux-gnu- build -a AARCH64 -p
> Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc -t GCC5</pre>

Skip the cross compilation scaffolding, it's covered in the root
Readme.md for those who need it. Just give a simple example command
line as a sneaky way to point out the .dsc.

> +
> +Once built, the UEFI Firmware is the following file Build/ArmVExpress-FVP-AArch64/DEBUG_GCC5/FV/FVP_AARCH64_EFI.fd
> +
> +<b>Note 1:</b> To build the release build, add '-b RELEASE'. Here's an example with the Foundation FVP:
> +<pre>GCC5_AARCH64_PREFIX=aarch64-linux-gnu- build -a AARCH64 -p Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc -t GCC5 -b RELEASE</pre>

Again, I'd leave the generic build instructions out of this.

> +
> +== Start Linux from UEFI on the FVPs ==
> +
> +=== Build AArch64 Linux ===
> +1) Get the AArch64 Linux sources
> +<pre>git clone git://git.kernel.org/pub/scm/linux/kernel/git/cmarinas/linux-aarch64.git -b soc-armv8-model
> +cd linux-aarch64</pre>
> +
> +2) Build the AArch64 kernel with Virtio support
> +<pre>make ARCH=arm64 mrproper
> +make ARCH=arm64 defconfig</pre>
> +
> +Enable Virtio Disk and Ext4 support in the kernel. The Linaro disk file-system uses Ext4.
> +<pre>make ARCH=arm64 menuconfig
> +Device Drivers  ---> Virtio drivers  ---> <*> Platform bus driver for memory mapped virtio devices
> +Device Drivers  ---> [*] Block devices  --->  <*> Virtio block driver
> +File systems  ---> <*> The Extended 4 (ext4) filesystem</pre>
> +
> +Build the kernel.
> +<pre>make -j4 ARCH=arm64 CROSS_COMPILE=<path-to-aarch64-gcc>/gcc-linaro-aarch64-linux-gnu-4.8-2013.06_linux/bin/aarch64-linux-gnu-</pre>

If people need a cross compiler, they already have one installed if
they got this far.

But actually, I think this whole section can go. This shouldn't be a
page talking about how to build a Linux kernel. And those virtio
options are actually the default in upstream Linux these days.

> +
> +You should get the binaries:
> +* arch/arm64/boot/Image
> +* arch/arm64/boot/dts/foundation-v8.dtb
> +* arch/arm64/boot/dts/rtsm_ve-aemv8a.dtb 

This isn't really up to date. There's separate gicv2/gicv3 blobs. And
another one for PSCI (I think).

> +
> +=== Run Linux from UEFI on the Foundation FVP ===
> +
> +1) Download the Foundation FVP: http://www.arm.com/fvp>

Maybe change to
https://developer.arm.com/products/system-design/fixed-virtual-platforms
? (This is where I get redirected these days.)

+
> +Decompress the AArch64 Foundation FVP
> +<pre>tar xf ~/FM000-KT-00035-r0p8-48rel5.tgz</pre>
> +


Pretty sure we want to nuke everything from here:

> +2) The current version of the Foundation FVP can only start an ELF image. To workaround this limitation, we use the 'uefi-aarch64-bootstrap' to start the UEFI image on this model.
> +
> +To build the 'uefi-aarch64-bootstrap':
> +<pre>pushd ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/
> +CROSS_COMPILE=<path-to-aarch64-gcc>/gcc-linaro-aarch64-linux-gnu-4.8-2013.06_linux/bin/aarch64-linux-gnu- make
> +popd</pre>
> +
> +3) The Foundation FVP takes an option for an ELF file to be loaded as well as an option to load a binary data blob into RAM.
> +
> +Linux kernel (filename = 'Image') and the Device Tree Binary (filename = 'foundation-v8.dtb') are expected to be found in the directory where the model is started from.
> +
> +A file system example can be downloaded from Linaro:
> +<pre>wget http://releases.linaro.org/13.06/openembedded/aarch64/vexpress64-openembedded_minimal-armv8_20130623-376.img.gz
> +gunzip vexpress64-openembedded_minimal-armv8_20130623-376.img.gz</pre>
> +
> +The file-system needs some minimal preparation:
> +<pre>mkdir tmp
> +fdisk -lu vexpress64-openembedded_minimal-armv8_20130623-376.img
> +sudo mount -o loop,offset=$((106496 * 512)) vexpress64-openembedded_minimal-armv8_20130623-376.img tmp/
> +cd tmp
> +sudo ln -s S35mountall.sh etc/rcS.d/S03mountall.sh
> +sudo sh -c "echo 'devtmpfs /dev devtmpfs mode=0755,nosuid 0 0' >> etc/fstab"
> +cd ..
> +sudo umount tmp/</pre>
> +
> +The following command line can be used to run UEFI in the following manner:
> +<pre>$AARCH64_FOUNDATION_MODEL_ROOT/Foundation_v8 --cores=2 --image=ArmPlatformPkg/ArmVExpressPkg/Scripts/uefi-aarch64-bootstrap/uefi-bootstrap-el3-foundation.axf --nsdata=Build/ArmVExpress-RTSM-AEMv8Ax4-foundation/DEBUG_GCC47/FV/RTSM_VE_FOUNDATIONV8_EFI.fd@0xA0000000 --block-device=<path/to>/vexpress64-openembedded_minimal-armv8_20130623-376.img</pre>
> +
> +<b>Note:</b> Do not use a symbolic link to the file-system image. The model will not be able to read the image file.
> +
> +=== Run Linux from UEFI on the Base FVP ===
> +
> +The Linux kernel (filename = 'Image') and the Device Tree Binary (filename = 'rtsm_ve-aemv8a.dtb') are expected to be found in the directory where the model is started from.
> +<pre>export PATH=ARM_BASE_AEMV8_ROOT:$PATH
> +export LD_LIBRARY_PATH=ARM_BASE_AEMV8_ROOT:$LD_LIBRARY_PATH
> +FVP_VE_AEMv8A -C motherboard.flashloader0.fname=Build/ArmVExpress-RTSM-AEMv8Ax4/DEBUG_GCC47/FV/RTSM_VE_AEMV8_EFI.fd</pre>
> +
> +<!-- [[Category:ARM]] -->

To here.
Everything of the above that isn't incorrect these days is ... unhelpful.

Not that it wouldn't be useful to have instructions ... just not
these.

Ideally, there would be some link here to how to bundle this with ARM
trusted firmware and run a Linux installer, or a (modern) filesystem
available from somewhere.

But I'd take no information over the outdated content above.

Finally, a more simple request:
Could you add a link to this file from top-level Readme.md?
Towards the very end, there is an
## ARM
that could (probably?) become
## [ARM](Platforms/ARM/Readme.md)
And you could then nuke the Juno/VExpress links currently located
under that header.

Regards,

Leif