doc: Add documentation for the Arm vexpress board configs

Create a new documentation section for Arm Ltd boards with a sub-page
for the vexpress board (FVP-A, FVP-R and Juno).

Document how the armv8_switch_to_el1 environment variable can be used
to switch between booting from S-EL2/S-EL1 at runtime on the BASER_FVP.

Signed-off-by: Peter Hoyes <Peter.Hoyes@arm.com>

4 files changed, 69 insertions, 1 deletions

diff --git a/doc/arch/arm64.rst b/doc/arch/arm64.rst
index 80498f6f6b..f20eb8f1b2 100644
--- a/doc/arch/arm64.rst
+++ b/doc/arch/arm64.rst
@@ -18,7 +18,8 @@ Notes
    classical firmware (like initial hardware setup, CPU errata workarounds
    or SMP bringup). U-Boot can be entered in EL2 when its main purpose is
    that of a boot loader. It can drop to lower exception levels before
-   entering the OS.
+   entering the OS. For ARMv8-R it is recommened to enter at S-EL2, as for this
+   architecture there is no S-EL3.
 
 2. U-Boot for arm64 is compiled with AArch64-gcc. AArch64-gcc
    use rela relocation format, a tool(tools/relocate-rela) by Scott Wood
diff --git a/doc/board/armltd/index.rst b/doc/board/armltd/index.rst
new file mode 100644
index 0000000000..b6786c114f
--- /dev/null
+++ b/doc/board/armltd/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Arm Ltd
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   vexpress64.rst
diff --git a/doc/board/armltd/vexpress64.rst b/doc/board/armltd/vexpress64.rst
new file mode 100644
index 0000000000..37ef564110
--- /dev/null
+++ b/doc/board/armltd/vexpress64.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Arm Versatile Express
+=====================
+
+The vexpress_* board configuration supports the following platforms:
+
+ * FVP_Base_RevC-2xAEMvA
+ * FVP_BaseR_AEMv8R
+ * Juno development board
+
+Fixed Virtual Platforms
+-----------------------
+
+The Fixed Virtual Platforms (FVP) are complete simulations of an Arm system,
+including processor, memory and peripherals. They are set out in a "programmer's
+view", which gives a comprehensive model on which to build and test software.
+
+The supported FVPs are available free of charge and can be downloaded from the
+Arm developer site [1]_ (user registration might be required).
+
+Supported features:
+
+ * GICv3
+ * Generic timer
+ * PL011 UART
+ * SMC91111 network interface
+
+The default configuration assumes that U-Boot is boostrapped from the start of
+the DRAM (address 0x80000000 for AEMvA; 0x00000000 for AEMv8R) using a suitable
+bootloader. Alternatively, U-Boot can be launched directly by mapping the binary
+to the same address (using the FVP's --data argument).
+
+The FVPs can be debugged using Arm Development Studio [2]_.
+
+FVP_BaseR
+^^^^^^^^^
+
+On Armv8r64 platforms (such as the FVP_BaseR), U-Boot runs at S-EL2, so
+CONFIG_ARMV8_SWITCH_TO_EL1 is defined so that the next stage boots at S-EL1. If
+S-EL2 is desired instead, the *armv8_switch_to_el1* environment variable is
+available. This can be set to *n* to override the config flag and boot the next
+stage at S-EL2 instead.
+
+Juno
+----
+
+The Juno development board is an open, vendor-neutral Armv8-A development
+platform that supports an out-of-the-box Linux software package. A range of
+plug-in expansion options enables hardware and software applications to be
+developed and debugged.
+
+References
+----------
+
+.. [1] https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms
+.. [2] https://developer.arm.com/tools-and-software/embedded/arm-development-studio
diff --git a/doc/board/index.rst b/doc/board/index.rst
index 8588e453d5..827f0866bd 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -10,6 +10,7 @@ Board-specific doc
    advantech/index
    AndesTech/index
    amlogic/index
+   armltd/index
    atmel/index
    congatec/index
    coreboot/index