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

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

[Nariman Poushin]

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..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. 
+
+== 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
+
+Please see the root edk2/Readme.md for information on how to obtain the source
+
+== 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

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

[Leif Lindholm]

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

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

[Nariman Poushin]

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

[PATCH] Platform/ARM: Add Readme.md

[Nariman Poushin]

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

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Nariman Poushin <nariman.poushin@linaro.org>
---

Changes from v2:

	- Removed references to fetching source
	- Updated location of FVP
	- Removed instructions on configuring and building Linux
	- Entirely re-wrote section on running on the (now) Base FVP

Basically, it's a (much needed) re-write, to reflect Leif's comments, which were
very sensible.

I have not included running Linux at all, as I figure we can add that later (if
needed). For now, there instructions should yield a working development
environment for aarch64 running edk2 tianocore (edk2/edk2-platforms? not sure
which one is correct ... or if they both are).

Thanks
Nariman

 Platform/ARM/Readme.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++
 Readme.md              |  4 +---
 2 files changed, 63 insertions(+), 3 deletions(-)
 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..a4c840f
--- /dev/null
+++ b/Platform/ARM/Readme.md
@@ -0,0 +1,62 @@
+== Introduction ==
+
+These instructions explain how to get an edk2/edk2-platforms build running
+on the ARM Base FVP, which is a software model provided by ARM (for free)
+, which models a Cortex A core with various peripherals. More information
+can be found here:
+https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+<b>Requirement:</b>
+* A 32-bit or 64-bit Linux host machine.
+* Visual Studio is not officially supported, experimental support can be found here:
+[https://git.linaro.org/people/leif.lindholm/edk2.git/log/?h=aarch64-vs]
+
+== Build EDK2 Tianocore ==
+
+<pre>cd $(WORKSPACE)/edk2</pre>For the Foundation and Base FVPs (defined by the DSC file Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc):
+<pre>build -a AARCH64 -p Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc -t GCC5</pre>
+
+Once built, the edk2 image is the following file Build/ArmVExpress-FVP-AArch64/DEBUG_GCC5/FV/FVP_AARCH64_EFI.fd
+
+=== Run edk2/edk2-platforms on the ARM Base Platform FVP ===
+
+In order to run the binary we have just built there are a few steps we need to
+go through, we need to get a model, a set of prebuilts (where we will swap out
+the edk2 image with our own) and the tool with which we will swap out the
+prebuilt edk2 image.
+
+We will also rely on the "run_model" script that comes with the prebuilts, it
+is entirely possible to run the model without this but would require quite a bit
+of knowledge regarding the areguments ARM fastmodel (documentation can be found here:
+https://developer.arm.com/docs/100966/1101/programming-reference-for-base-fvps/base-platform-revc-features)
+however the manual set of the FVP is outside the scope of this document. If you are interested
+please consult the documentation.
+
+It's recommended you create a folder where you download the prebuilts and
+required tool and copy your edk2 image in to it, as the run script expects
+the binaries in the same directory.
+
+1) Download the Base FVP from here https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+	- Select Armv8-A Base Platform FVP based on Fast Models 11.4
+	- It has a click through license but is free.
+
+2) Download the 18.10 Linaro ARM Landing Team release for FVP booting UEFI
+https://releases.linaro.org/members/arm/platforms/18.10/fvp-uefi.zip
+
+3) Download the prebuilt fiptool from https://git.linaro.org/landing-teams/working/arm/prebuilt/tools
+
+4) Update the fip.bin image from fvp-uefi.zip by running the following command:
+
+	fiptool update --nt-fw=[path to binary built above] fip.bin
+
+5) Execute the FVP run_model.sh script from fvp-uefi.zip and provide a path to the FVP binaries
+downloaded in step 1):
+
+	MODEL=[path to FVP binary] ./run_model.sh
+
+This expects the contents of fvp-uefi.zip, the bl1.bin and fip.bin (which is
+the file we modify), to be in the same directory as the run_model.sh script.
+
+This should be sufficient to provide a build/run/debug environment for aarch64.
+<!-- [[Category:ARM]] -->
diff --git a/Readme.md b/Readme.md
index 6ad5953..6748826 100644
--- a/Readme.md
+++ b/Readme.md
@@ -206,9 +206,7 @@ they will be documented with the platform.
 * [Overdrive](Platform/AMD/OverdriveBoard)
 * [Overdrive 1000](Platform/SoftIron/Overdrive1000Board)
 
-## ARM
-* [Juno](Platform/ARM/JunoPkg)
-* [Versatile Express](Platform/ARM/VExpressPkg)
+## [ARM](Platform/ARM/Readme.md)
 
 ## Hisilicon
 * [D02](Platform/Hisilicon/D02)
-- 
2.7.4

[PATCH] Platform/ARM: Add Readme.md

[Nariman Poushin]

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

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Nariman Poushin <nariman.poushin@linaro.org>
---

Changes from v2:

	- Removed references to fetching source
	- Updated location of FVP
	- Removed instructions on configuring and building Linux
	- Entirely re-wrote section on running on the (now) Base FVP

Basically, it's a (much needed) re-write, to reflect Leif's comments, which were
very sensible.

I have not included running Linux at all, as I figure we can add that later (if
needed). For now, there instructions should yield a working development
environment for aarch64 running edk2 tianocore (edk2/edk2-platforms? not sure
which one is correct ... or if they both are).

Thanks
Nariman

 Platform/ARM/Readme.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++
 Readme.md              |  4 +---
 2 files changed, 63 insertions(+), 3 deletions(-)
 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..a4c840f
--- /dev/null
+++ b/Platform/ARM/Readme.md
@@ -0,0 +1,62 @@
+== Introduction ==
+
+These instructions explain how to get an edk2/edk2-platforms build running
+on the ARM Base FVP, which is a software model provided by ARM (for free)
+, which models a Cortex A core with various peripherals. More information
+can be found here:
+https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+<b>Requirement:</b>
+* A 32-bit or 64-bit Linux host machine.
+* Visual Studio is not officially supported, experimental support can be found here:
+[https://git.linaro.org/people/leif.lindholm/edk2.git/log/?h=aarch64-vs]
+
+== Build EDK2 Tianocore ==
+
+<pre>cd $(WORKSPACE)/edk2</pre>For the Foundation and Base FVPs (defined by the DSC file Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc):
+<pre>build -a AARCH64 -p Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc -t GCC5</pre>
+
+Once built, the edk2 image is the following file Build/ArmVExpress-FVP-AArch64/DEBUG_GCC5/FV/FVP_AARCH64_EFI.fd
+
+=== Run edk2/edk2-platforms on the ARM Base Platform FVP ===
+
+In order to run the binary we have just built there are a few steps we need to
+go through, we need to get a model, a set of prebuilts (where we will swap out
+the edk2 image with our own) and the tool with which we will swap out the
+prebuilt edk2 image.
+
+We will also rely on the "run_model" script that comes with the prebuilts, it
+is entirely possible to run the model without this but would require quite a bit
+of knowledge regarding the areguments ARM fastmodel (documentation can be found here:
+https://developer.arm.com/docs/100966/1101/programming-reference-for-base-fvps/base-platform-revc-features)
+however the manual set of the FVP is outside the scope of this document. If you are interested
+please consult the documentation.
+
+It's recommended you create a folder where you download the prebuilts and
+required tool and copy your edk2 image in to it, as the run script expects
+the binaries in the same directory.
+
+1) Download the Base FVP from here https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+	- Select Armv8-A Base Platform FVP based on Fast Models 11.4
+	- It has a click through license but is free.
+
+2) Download the 18.10 Linaro ARM Landing Team release for FVP booting UEFI
+https://releases.linaro.org/members/arm/platforms/18.10/fvp-uefi.zip
+
+3) Download the prebuilt fiptool from https://git.linaro.org/landing-teams/working/arm/prebuilt/tools
+
+4) Update the fip.bin image from fvp-uefi.zip by running the following command:
+
+	fiptool update --nt-fw=[path to binary built above] fip.bin
+
+5) Execute the FVP run_model.sh script from fvp-uefi.zip and provide a path to the FVP binaries
+downloaded in step 1):
+
+	MODEL=[path to FVP binary] ./run_model.sh
+
+This expects the contents of fvp-uefi.zip, the bl1.bin and fip.bin (which is
+the file we modify), to be in the same directory as the run_model.sh script.
+
+This should be sufficient to provide a build/run/debug environment for aarch64.
+<!-- [[Category:ARM]] -->
diff --git a/Readme.md b/Readme.md
index 6ad5953..6748826 100644
--- a/Readme.md
+++ b/Readme.md
@@ -206,9 +206,7 @@ they will be documented with the platform.
 * [Overdrive](Platform/AMD/OverdriveBoard)
 * [Overdrive 1000](Platform/SoftIron/Overdrive1000Board)
 
-## ARM
-* [Juno](Platform/ARM/JunoPkg)
-* [Versatile Express](Platform/ARM/VExpressPkg)
+## [ARM](Platform/ARM/Readme.md)
 
 ## Hisilicon
 * [D02](Platform/Hisilicon/D02)
-- 
2.7.4

[edk2-platforms] [PATCH v4 2/2] Platform/ARM: Add Readme.md

[Nariman Poushin]

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

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Nariman Poushin <nariman.poushin@linaro.org>
---

Changes since v3 (subject line omitted in previous mail):

	- Fixed up link to Linaro ARM Landing Team prebuilt tools repo
	- Fixed up subject line

 Platform/ARM/Readme.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++
 Readme.md              |  4 +---
 2 files changed, 63 insertions(+), 3 deletions(-)
 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..a4c840f
--- /dev/null
+++ b/Platform/ARM/Readme.md
@@ -0,0 +1,62 @@
+== Introduction ==
+
+These instructions explain how to get an edk2/edk2-platforms build running
+on the ARM Base FVP, which is a software model provided by ARM (for free)
+, which models a Cortex A core with various peripherals. More information
+can be found here:
+https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+<b>Requirement:</b>
+* A 32-bit or 64-bit Linux host machine.
+* Visual Studio is not officially supported, experimental support can be found here:
+[https://git.linaro.org/people/leif.lindholm/edk2.git/log/?h=aarch64-vs]
+
+== Build EDK2 Tianocore ==
+
+<pre>cd $(WORKSPACE)/edk2</pre>For the Foundation and Base FVPs (defined by the DSC file Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc):
+<pre>build -a AARCH64 -p Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc -t GCC5</pre>
+
+Once built, the edk2 image is the following file Build/ArmVExpress-FVP-AArch64/DEBUG_GCC5/FV/FVP_AARCH64_EFI.fd
+
+=== Run edk2/edk2-platforms on the ARM Base Platform FVP ===
+
+In order to run the binary we have just built there are a few steps we need to
+go through, we need to get a model, a set of prebuilts (where we will swap out
+the edk2 image with our own) and the tool with which we will swap out the
+prebuilt edk2 image.
+
+We will also rely on the "run_model" script that comes with the prebuilts, it
+is entirely possible to run the model without this but would require quite a bit
+of knowledge regarding the areguments ARM fastmodel (documentation can be found here:
+https://developer.arm.com/docs/100966/1101/programming-reference-for-base-fvps/base-platform-revc-features)
+however the manual set of the FVP is outside the scope of this document. If you are interested
+please consult the documentation.
+
+It's recommended you create a folder where you download the prebuilts and
+required tool and copy your edk2 image in to it, as the run script expects
+the binaries in the same directory.
+
+1) Download the Base FVP from here https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+	- Select Armv8-A Base Platform FVP based on Fast Models 11.4
+	- It has a click through license but is free.
+
+2) Download the 18.10 Linaro ARM Landing Team release for FVP booting UEFI
+https://releases.linaro.org/members/arm/platforms/18.10/fvp-uefi.zip
+
+3) Download the prebuilt fiptool from https://git.linaro.org/landing-teams/working/arm/prebuilt/tools
+
+4) Update the fip.bin image from fvp-uefi.zip by running the following command:
+
+	fiptool update --nt-fw=[path to binary built above] fip.bin
+
+5) Execute the FVP run_model.sh script from fvp-uefi.zip and provide a path to the FVP binaries
+downloaded in step 1):
+
+	MODEL=[path to FVP binary] ./run_model.sh
+
+This expects the contents of fvp-uefi.zip, the bl1.bin and fip.bin (which is
+the file we modify), to be in the same directory as the run_model.sh script.
+
+This should be sufficient to provide a build/run/debug environment for aarch64.
+<!-- [[Category:ARM]] -->
diff --git a/Readme.md b/Readme.md
index 6ad5953..6748826 100644
--- a/Readme.md
+++ b/Readme.md
@@ -206,9 +206,7 @@ they will be documented with the platform.
 * [Overdrive](Platform/AMD/OverdriveBoard)
 * [Overdrive 1000](Platform/SoftIron/Overdrive1000Board)
 
-## ARM
-* [Juno](Platform/ARM/JunoPkg)
-* [Versatile Express](Platform/ARM/VExpressPkg)
+## [ARM](Platform/ARM/Readme.md)
 
 ## Hisilicon
 * [D02](Platform/Hisilicon/D02)
-- 
2.7.4

[edk2-platforms] [PATCH v5 2/2] Platform/ARM: Add Readme.md

[Nariman Poushin]

This Readme.md file covers building an aarch64 edk2 image and the instructions
on how to obtain and run the ARM Base FVP software model in order to get
an aarch64 build/debug environment.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Nariman Poushin <nariman.poushin@linaro.org>
---

Changes v1->v2

	- Added Contributed-under tag

Changes v2->v3 (subject line omitted in previous mail):

	- Updated the "Download the Sources" section to have the correct path

Changes v3->v4

        - Removed references to fetching source
        - Updated location of FVP
        - Removed instructions on configuring and building Linux
        - Entirely re-wrote section on running on the (now) Base FVP

Changes v4->v5

	- Fixed up link to Linaro ARM Landing Team prebuilt tools repo
	- Fixed up subject line


Basically, it's a (much needed) re-write, to reflect Leif's comments, which were
very sensible.

I have not included running Linux at all, as I figure we can add that later (if
needed). For now, there instructions should yield a working development
environment for aarch64 running edk2 tianocore (edk2/edk2-platforms? not sure
which one is correct ... or if both are).

Thanks
Nariman

ps. Apologies for the slew of patch sets, will have more coffee next time

 Platform/ARM/Readme.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++
 Readme.md              |  4 +---
 2 files changed, 63 insertions(+), 3 deletions(-)
 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..a4c840f
--- /dev/null
+++ b/Platform/ARM/Readme.md
@@ -0,0 +1,62 @@
+== Introduction ==
+
+These instructions explain how to get an edk2/edk2-platforms build running
+on the ARM Base FVP, which is a software model provided by ARM (for free)
+, which models a Cortex A core with various peripherals. More information
+can be found here:
+https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+<b>Requirement:</b>
+* A 32-bit or 64-bit Linux host machine.
+* Visual Studio is not officially supported, experimental support can be found here:
+[https://git.linaro.org/people/leif.lindholm/edk2.git/log/?h=aarch64-vs]
+
+== Build EDK2 Tianocore ==
+
+<pre>cd $(WORKSPACE)/edk2</pre>For the Foundation and Base FVPs (defined by the DSC file Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc):
+<pre>build -a AARCH64 -p Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc -t GCC5</pre>
+
+Once built, the edk2 image is the following file Build/ArmVExpress-FVP-AArch64/DEBUG_GCC5/FV/FVP_AARCH64_EFI.fd
+
+=== Run edk2/edk2-platforms on the ARM Base Platform FVP ===
+
+In order to run the binary we have just built there are a few steps we need to
+go through, we need to get a model, a set of prebuilts (where we will swap out
+the edk2 image with our own) and the tool with which we will swap out the
+prebuilt edk2 image.
+
+We will also rely on the "run_model" script that comes with the prebuilts, it
+is entirely possible to run the model without this but would require quite a bit
+of knowledge regarding the areguments ARM fastmodel (documentation can be found here:
+https://developer.arm.com/docs/100966/1101/programming-reference-for-base-fvps/base-platform-revc-features)
+however the manual set of the FVP is outside the scope of this document. If you are interested
+please consult the documentation.
+
+It's recommended you create a folder where you download the prebuilts and
+required tool and copy your edk2 image in to it, as the run script expects
+the binaries in the same directory.
+
+1) Download the Base FVP from here https://developer.arm.com/products/system-design/fixed-virtual-platforms
+
+	- Select Armv8-A Base Platform FVP based on Fast Models 11.4
+	- It has a click through license but is free.
+
+2) Download the 18.10 Linaro ARM Landing Team release for FVP booting UEFI
+https://releases.linaro.org/members/arm/platforms/18.10/fvp-uefi.zip
+
+3) Download the prebuilt fiptool from https://git.linaro.org/landing-teams/working/arm/prebuilt/tools
+
+4) Update the fip.bin image from fvp-uefi.zip by running the following command:
+
+	fiptool update --nt-fw=[path to binary built above] fip.bin
+
+5) Execute the FVP run_model.sh script from fvp-uefi.zip and provide a path to the FVP binaries
+downloaded in step 1):
+
+	MODEL=[path to FVP binary] ./run_model.sh
+
+This expects the contents of fvp-uefi.zip, the bl1.bin and fip.bin (which is
+the file we modify), to be in the same directory as the run_model.sh script.
+
+This should be sufficient to provide a build/run/debug environment for aarch64.
+<!-- [[Category:ARM]] -->
diff --git a/Readme.md b/Readme.md
index 6ad5953..6748826 100644
--- a/Readme.md
+++ b/Readme.md
@@ -206,9 +206,7 @@ they will be documented with the platform.
 * [Overdrive](Platform/AMD/OverdriveBoard)
 * [Overdrive 1000](Platform/SoftIron/Overdrive1000Board)
 
-## ARM
-* [Juno](Platform/ARM/JunoPkg)
-* [Versatile Express](Platform/ARM/VExpressPkg)
+## [ARM](Platform/ARM/Readme.md)
 
 ## Hisilicon
 * [D02](Platform/Hisilicon/D02)
-- 
2.7.4