user/bsps/arm: Add documentation for ZynqMP R5 BSP

This adds basic user documentation for running RTEMS on the Cortex-R5
processor on Xilinx Zynq Ultrascale+ MPSoC chips.

1 files changed, 66 insertions, 0 deletions

diff --git a/user/bsps/arm/xilinx-zynqmp-rpu.rst b/user/bsps/arm/xilinx-zynqmp-rpu.rst
new file mode 100644
index 0000000..01f9f23
--- /dev/null
+++ b/user/bsps/arm/xilinx-zynqmp-rpu.rst
@@ -0,0 +1,66 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2024 On-Line Applications Research Corporation (OAR)
+
+.. _BSP_arm_xilinx_zynqmp_rpu:
+
+Xilinx ZynqMP RPU
+=================
+
+This BSP supports the Cortex-R5 processor on the Xilinx Zynq UltraScale+ MPSoC
+platform. Basic hardware initialization is performed by the Cortex-R5 FSBL and
+the BSP. This BSP supports the GICv2 interrupt controller available to the
+Cortex-R5 subsystem. Since the Cortex-R5 subsystem only varies in speed, this
+BSP should be functional across all chip variants as well as on Xilinx's QEMU
+branch. SMP operation is not currently supported.
+
+Clock Driver
+------------
+
+The clock driver uses one of the available triple timer counters (TTCs) as the
+timer interrupt source.
+
+Console Driver
+--------------
+
+The console driver supports the default Qemu emulated ARM PL011 PrimeCell UART
+as well as the physical ARM PL011 PrimeCell UART in the ZynqMP hardware.
+
+Boot on ZynqMP Hardware
+-----------------------
+
+On the ZynqMP RPU, RTEMS can be started by Cortes-R5 u-boot, Cortex-A53 u-boot,
+via JTAG, or directly as part of BOOT.bin. For quick turnaround during testing,
+it is recommended to use Cortex-R5 u-boot to avoid repeated BOOT.bin generation
+and to ensure that the Cortex-R5 FSBL is run.
+
+Hardware Boot Image Generation
+------------------------------
+
+When generating BOOT.bin from components, the BIF file should include at least
+entries for the Cortex-R5 FSBL ([bootloader,destination_cpu=r5-0]) and the
+Cortex-R5 application ([destination_cpu=r5-0]). The Cortex-R5 application should
+be either a u-boot or RTEMS ELF binary. The Cortex-R5 u-boot binary can be
+obtained by building it from Xilinx's u-boot repository. The Cortex-R5 FSBL can
+be obtained setting up an appropriate platform project in Xilinx's current
+development system.
+
+Boot on QEMU
+------------
+The executable image is booted by Qemu in ELF format.
+
+Running Executables on QEMU
+---------------------------
+
+Xilinx's qemu-devicetrees repository must be used in conjunction with the Xilinx
+QEMU available via RSB. Executables generated by this BSP can be run using the
+following command:
+
+.. code-block:: shell
+
+  qemu-system-aarch64 -no-reboot -nographic -M arm-generic-fdt -serial null \
+   -serial mon:stdio -device loader,file=example.exe,cpu-num=4 \
+   -device loader,addr=0xff5e023c,data=0x80088fde,data-len=4 \
+   -device loader,addr=0xff9a0000,data=0x80000218,data-len=4 \
+   -hw-dtb /xlnx-qemu-devtrees-path/LATEST/SINGLE_ARCH/board-zynqmp-zcu102.dtb \
+   -m 4096 -display none