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

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

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>
---
 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..1ef11a6
--- /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. 
+
+== 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 
+
+2) Download the sources 
+<pre>git clone git@github.com:tianocore/edk2.git
+git clone https://github.com/tianocore/edk2-platforms.git</pre>
+
+== Build EDK2 Tianocore ==
+
+1) Install AArch64 GNU toolchain:
+<pre>sudo apt install gcc-aarch64-linux-gnu</pre>
+
+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):
+<pre>GCC5_AARCH64_PREFIX=aarch64-linux-gnu- build -a AARCH64 -p Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc -t GCC5</pre>
+
+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>
+
+== 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>
+
+You should get the binaries:
+* arch/arm64/boot/Image
+* arch/arm64/boot/dts/foundation-v8.dtb
+* arch/arm64/boot/dts/rtsm_ve-aemv8a.dtb 
+
+=== Run Linux from UEFI on the Foundation FVP ===
+
+1) Download the Foundation FVP: http://www.arm.com/fvp
+
+Decompress the AArch64 Foundation FVP
+<pre>tar xf ~/FM000-KT-00035-r0p8-48rel5.tgz</pre>
+
+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]] -->
-- 
2.7.4