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

[Nariman Poushin <nariman.poushin@linaro.org>]

On Mon, Nov 26, 2018 at 06:38:37PM +0000, Leif Lindholm wrote:
> 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.)

Absolutely no problems, really appreciate the feedback!

> 
> > ---
> >  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 :)
cgty68ooih vv gee "Building these platforms with Visual Studio is not yet supported."
> would be a more accurate statement.

Updated to refer to your experimental tree.

> 
> > +
> > +== 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)

Dropped this section, it's unlikely you have obtained the edk2-platforms
source without being entirely unaware of the edk2 source?

> 
> > +
> > +== 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).

Dropped this whole section as per your comment above, makes sense. I am sorting
out this section to refer to up to date models, and drop the reference to Linux
for now. I will include a section on how to get up and running using the
edk2/edk2-platforms build just built with the pre-builts from the Linaro 18.10
release (which date it, but is a damn sight more recent than the current instructions).

Sound ok?

> 
> > +
> > +=== 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.)

Done.

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

It feels like people should know how to use tar if they got this far,
and by dropping this we avoid assuming a version. Is it fair to
just say "Download the Foundation FVP" with the updated URL and expect
Reasonable People to Do the Right Thing?

> 
> 
> 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.

Sure thing, will fix that up.

> 
> Regards,
> 
> Leif