arm_fpga: Add platform documentation
As the Arm Ltd. FPGA port is now working for all existing images, add
some documentation file.
Change-Id: I9e2c532ed15bbc121bb54b3dfc1bdfee8f1443a6
Signed-off-by: Andre Przywara <andre.przywara@arm.com>
diff --git a/docs/plat/arm/arm_fpga/index.rst b/docs/plat/arm/arm_fpga/index.rst
new file mode 100644
index 0000000..5427c1d
--- /dev/null
+++ b/docs/plat/arm/arm_fpga/index.rst
@@ -0,0 +1,97 @@
+Arm FPGA Platform
+=================
+
+This platform supports FPGA images used internally in Arm Ltd., for
+testing and bringup of new cores. With that focus, peripheral support is
+minimal: there is no mass storage or display output, for instance. Also
+this port ignores any power management features of the platform.
+Some interconnect setup is done internally by the platform, so the TF-A code
+just needs to setup UART and GIC.
+
+The FPGA platform requires to pass on a DTB for the non-secure payload
+(mostly Linux), so we let TF-A use information from the DTB for dynamic
+configuration: the UART and GIC base addresses are read from there.
+
+As a result this port is a fairly generic BL31-only port, which can serve
+as a template for a minimal new (and possibly DT-based) platform port.
+
+The aim of this port is to support as many FPGA images as possible with
+a single build. Image specific data must be described in the DTB or should
+be auto-detected at runtime.
+
+As the number and topology layout of the CPU cores differs significantly
+across the various images, this is detected at runtime by BL31.
+The /cpus node in the DT will be added and filled accordingly, as long as
+it does not exist already.
+
+Platform-specific build options
+-------------------------------
+
+- ``SUPPORT_UNKNOWN_MPID`` : Boolean option to allow unknown MPIDR registers.
+ Normally TF-A panics if it encounters a MPID value not matched to its
+ internal list, but for new or experimental cores this creates a lot of
+ churn. With this option, the code will fall back to some basic CPU support
+ code (only architectural system registers, and no errata).
+ Default value of this flag is 1.
+
+- ``PRELOADED_BL33_BASE`` : Physical address of the BL33 non-secure payload.
+ It must have been loaded into DRAM already, typically this is done by
+ the script that also loads BL31 and the DTB.
+ It defaults to 0x80080000, which is the traditional load address for an
+ arm64 Linux kernel.
+
+- ``FPGA_PRELOADED_DTB_BASE`` : Physical address of the flattened device
+ tree blob (DTB). This DT will be used by TF-A for dynamic configuration,
+ so it must describe at least the UART and a GICv3 interrupt controller.
+ The DT gets amended by the code, to potentially add a command line and
+ fill the CPU topology nodes. It will also be passed on to BL33, by
+ putting its address into the x0 register before jumping to the entry
+ point (following the Linux kernel boot protocol).
+ It defaults to 0x80070000, which is 64KB before the BL33 load address.
+
+- ``FPGA_PRELOADED_CMD_LINE`` : Physical address of the command line to
+ put into the devicetree blob. Due to the lack of a proper bootloader,
+ a command line can be put somewhere into memory, so that BL31 will
+ detect it and copy it into the DTB passed on to BL33.
+ To avoid random garbage, there needs to be a "CMD:" signature before the
+ actual command line.
+ Defaults to 0x1000, which is normally in the "ROM" space of the typical
+ FPGA image (which can be written by the FPGA payload uploader, but is
+ read-only to the CPU). The FPGA payload tool should be given a text file
+ containing the desired command line, prefixed by the "CMD:" signature.
+
+Building the TF-A image
+-----------------------
+
+ .. code:: shell
+
+ make PLAT=arm_fgpa DEBUG=1
+
+ This will use the default load addresses as described above. When those
+ addresses need to differ for a certain setup, they can be passed on the
+ make command line:
+
+ .. code:: shell
+
+ make PLAT=arm_fgpa DEBUG=1 PRELOADED_BL33_BASE=0x80200000 FPGA_PRELOADED_DTB_BASE=0x80180000 bl31
+
+Running the TF-A image
+----------------------
+
+After building TF-A, the actual TF-A code will be located in ``bl31.bin`` in
+the build directory.
+Additionally there is a ``bl31.axf`` ELF file, which contains BL31, as well
+as some simple ROM trampoline code (required by the Arm FPGA boot flow) and
+a generic DTB to support most of the FPGA images. This can be simply handed
+over to the FPGA payload uploader, which will take care of loading the
+components at their respective load addresses. In addition to this file
+you need at least a BL33 payload (typically a Linux kernel image), optionally
+a Linux initrd image file and possibly a command line:
+
+ .. code:: shell
+
+ fpga-run ... -m bl31.axf -l auto -m Image -l 0x80080000 -m initrd.gz -l 0x84000000 -m cmdline.txt -l 0x1000
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/plat/arm/index.rst b/docs/plat/arm/index.rst
index 1afe475..9c2fcb1 100644
--- a/docs/plat/arm/index.rst
+++ b/docs/plat/arm/index.rst
@@ -9,6 +9,7 @@
fvp/index
fvp-ve/index
tc0/index
+ arm_fpga/index
arm-build-options
This chapter holds documentation related to Arm's development platforms,