[PATCH v2 0/2] Arm Juno board documentation

[PATCH v2 0/2] Arm Juno board documentation

[Andre Przywara]

Hi,

The Arm Ltd. Juno development board is an open, vendor-neutral, Armv8-A
development platform. U-Boot is one of the two supported normal world
payloads in the firmware design, though U-Boot never really described
the process of building or installing it.

Fix that by adding documentation for the board in the doc/board
directory.

Cheers,
Andre

Changelog:
v1 ... v2:
- fvp64: RST improvements (links, make command line)
- fvp64: use most common platform name in TF-A build command
- juno: use more precise naming for Juno development *platform*
- juno: fix wrong naming of MCC management controller
- juno: mention and link to Juno TRM
- juno: simplify SD card connection instructions
- juno: use fiptool update instead of complicated explicit re-packaging
- juno: describe devicetree selection more precisely

Andre Przywara (1):
  doc: add Arm Juno board documentation

Peter Hoyes (1):
  doc: Add documentation for the Arm VExpress64 board configs

 doc/board/armltd/fvp64.rst |  30 ++++++++++
 doc/board/armltd/index.rst |  11 ++++
 doc/board/armltd/juno.rst  | 114 +++++++++++++++++++++++++++++++++++++
 doc/board/index.rst        |   1 +
 4 files changed, 156 insertions(+)
 create mode 100644 doc/board/armltd/fvp64.rst
 create mode 100644 doc/board/armltd/index.rst
 create mode 100644 doc/board/armltd/juno.rst

-- 
2.25.1

[PATCH v2 1/2] doc: Add documentation for the Arm VExpress64 board configs

[Andre Przywara]

From: Peter Hoyes <Peter.Hoyes@arm.com>

Create a new documentation section for Arm Ltd boards with a sub-page
for the FVP VExpress64 system.

Signed-off-by: Peter Hoyes <Peter.Hoyes@arm.com>
[Andre: remove Juno stub, RSTify]
Signed-off-by: Andre Przywara <andre.przywara@arm.com>
---
 doc/board/armltd/fvp64.rst | 30 ++++++++++++++++++++++++++++++
 doc/board/armltd/index.rst | 10 ++++++++++
 doc/board/index.rst        |  1 +
 3 files changed, 41 insertions(+)
 create mode 100644 doc/board/armltd/fvp64.rst
 create mode 100644 doc/board/armltd/index.rst

diff --git a/doc/board/armltd/fvp64.rst b/doc/board/armltd/fvp64.rst
new file mode 100644
index 0000000000..4dc341bf2a
--- /dev/null
+++ b/doc/board/armltd/fvp64.rst
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Fixed Virtual Platforms
+=======================
+
+The Fixed Virtual Platforms (FVP) are complete software 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`_ (user registration might be required).
+
+Supported features:
+
+ * GICv3
+ * Generic timer
+ * PL011 UART
+
+The default configuration assumes that U-Boot is bootstrapped using a suitable
+bootloader, such as `Trusted Firmware-A`_. The U-Boot binary can be passed
+into the TF-A build::
+
+    make PLAT=fvp all fip BL33=/path/to/u-boot.bin
+
+The FVPs can be debugged using `Arm Development Studio`_.
+
+.. _`Arm developer site`: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms
+.. _`Trusted Firmware-A`: https://www.trustedfirmware.org/projects/tf-a/
+.. _`Arm Development Studio`: https://developer.arm.com/tools-and-software/embedded/arm-development-studio
diff --git a/doc/board/armltd/index.rst b/doc/board/armltd/index.rst
new file mode 100644
index 0000000000..caa6fd2bb0
--- /dev/null
+++ b/doc/board/armltd/index.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. Copyright (C) 2021 Arm Ltd.
+
+ARM Ltd. boards and emulated systems
+====================================
+
+.. toctree::
+   :maxdepth: 2
+
+   fvp64
diff --git a/doc/board/index.rst b/doc/board/index.rst
index 13f4db848e..d0a7838550 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -11,6 +11,7 @@ Board-specific doc
    AndesTech/index
    amlogic/index
    apple/index
+   armltd/index
    atmel/index
    congatec/index
    coreboot/index
-- 
2.25.1

[PATCH v2 2/2] doc: add Arm Juno board documentation

[Andre Przywara]

The Juno Arm development board is an open, vendor-neutral, Armv8-A
development platform.
Add documentation that briefly outlines the hardware, and describes
building and installation of U-Boot.

Signed-off-by: Andre Przywara <andre.przywara@arm.com>
---
 doc/board/armltd/index.rst |   1 +
 doc/board/armltd/juno.rst  | 114 +++++++++++++++++++++++++++++++++++++
 2 files changed, 115 insertions(+)
 create mode 100644 doc/board/armltd/juno.rst

diff --git a/doc/board/armltd/index.rst b/doc/board/armltd/index.rst
index caa6fd2bb0..68d938c647 100644
--- a/doc/board/armltd/index.rst
+++ b/doc/board/armltd/index.rst
@@ -8,3 +8,4 @@ ARM Ltd. boards and emulated systems
    :maxdepth: 2
 
    fvp64
+   juno
diff --git a/doc/board/armltd/juno.rst b/doc/board/armltd/juno.rst
new file mode 100644
index 0000000000..3d20ff129c
--- /dev/null
+++ b/doc/board/armltd/juno.rst
@@ -0,0 +1,114 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. Copyright (C) 2021 Arm Ltd.
+
+Arm Juno development platform
+=============================
+
+The `Juno development board`_ is an open, vendor-neutral, Armv8-A development
+platform, made by Arm Ltd. It is part of the Versatile Express family.
+There are three revisions of the board:
+
+* Juno r0, with two Cortex-A57 and four Cortex-A53 cores, without PCIe.
+* Juno r1, with two Cortex-A57 and four Cortex-A53 cores, in later silicon
+  revisions, and with PCIe slots, Gigabit Ethernet and two SATA ports.
+* Juno r2, with two Cortex-A72 and four Cortex-A53 cores, otherwise the
+  same as r1.
+
+Among other things, the motherboard contains a management controller (MCC),
+an FPGA providing I/O interfaces (IOFPGA) and 64MB of NOR flash. The provided
+platform devices resemble the VExpress peripherals.
+The actual SoC also contains a Cortex-M3 based System Control Processor (SCP).
+The `V2M-Juno TRM`_ contains more technical details.
+
+U-Boot build
+------------
+There is only one defconfig and one binary build that covers all three board
+revisions, so to generate the needed ``u-boot.bin``:
+
+.. code-block:: bash
+
+    $ make vexpress_aemv8a_juno_defconfig
+    $ make
+
+The automatic distro boot sequence looks for UEFI boot applications and
+``boot.scr`` scripts on various boot media, starting with USB, then on disks
+connected to the two SATA ports, PXE, DHCP and eventually on the NOR flash.
+
+U-Boot installation
+-------------------
+This assumes there is some firmware on the SD card or NOR flash (see below
+for more details). The U-Boot binary is included in the Trusted Firmware
+FIP image, so after building U-Boot, this needs to be repackaged or recompiled.
+
+The NOR flash will be updated by the MCC, based on the content of a micro-SD
+card, which is exported as a USB mass storage device via the rear USB-B
+socket. So to access that SD card, connect a cable to some host computer, and
+mount the FAT16 partition of the UMS device.
+If there is no device, check the upper serial port for a prompt, and
+explicitly enable the USB interface::
+
+    Cmd> usb_on
+    Enabling debug USB...
+
+Repackaging an existing FIP image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To prevent problems, it is probably a good idea to backup the existing firmware,
+for instance by just copying the entire ``SOFTWARE/`` directory, or at least
+the current ``fip.bin``, beforehand.
+
+To just replace the BL33 image in the exising FIP image, you can use
+`fiptool`_ from the Trusted Firmware repository, on the image file:
+
+.. code-block:: bash
+
+    $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+    $ cd trusted-firmware-a
+    $ make fiptool
+    $ tools/fiptool/fiptool update --nt-fw=/path/to/your/u-boot.bin /mnt/juno/SOFTWARE/fip.bin
+
+Unmount the USB mass storage device and reboot the board, the new ``fip.bin``
+will be automatically written to the NOR flash and then used.
+
+Rebuilding Trusted Firmware
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can also generate a new FIP image by compiling Arm Trusted Firmware,
+and providing ``u-boot.bin`` as the BL33 file. For that you can either build
+the required `SCP firmware`_ yourself, or just extract the existing
+version from your ``fip.bin``, using `fiptool`_ (see above):
+
+.. code-block:: bash
+
+    $ mkdir /tmp/juno; cd /tmp/juno
+    $ fiptool unpack /mnt/juno/SOFTWARE/fip.bin
+
+Then build TF-A:
+
+.. code-block:: bash
+
+    $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+    $ cd trusted-firmware-a
+    $ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=juno DEBUG=1 \
+      SCP_BL2=/tmp/juno/scp-fw.bin BL33=/path/to/your/u-boot.bin fiptool all fip
+    $ cp build/juno/debug/bl1.bin build/juno/debug/fip.bin /mnt/juno/SOFTWARE
+
+Then umount the USB device, and reboot, as above.
+
+Device trees
+------------
+The device tree files for the boards are maintained in the Linux kernel
+repository. They end up in the ``SOFTWARE/`` directory of the SD card, as
+``juno.dtb``, ``juno-r1.dtb``, and ``juno-r2.dtb``, respectively. The MCC
+firmware will look into the images.txt file matching the board revision, from
+the ``SITE1/`` directory. Each version there will reference its respective DTB
+file in ``SOFTWARE/``, and so the correct version will end in the NOR flash, in
+the ``board.dtb`` partition. U-Boot picks its control DTB from there, you can
+pass this on to a kernel using ``$fdtcontroladdr``.
+
+You can update the DTBs anytime, by building them using the ``dtbs`` make
+target from a Linux kernel tree, then just copying the generated binaries
+to the ``SOFTWARE/`` directory of the SD card.
+
+.. _`Juno development board`: https://developer.arm.com/tools-and-software/development-boards/juno-development-board
+.. _`V2M-Juno TRM`: https://developer.arm.com/documentation/100113/latest
+.. _`fiptool`: https://github.com/ARM-software/arm-trusted-firmware/tree/master/tools/fiptool
+.. _`SCP firmware`: https://github.com/ARM-software/SCP-firmware.git
-- 
2.25.1

Re: [PATCH v2 1/2] doc: Add documentation for the Arm VExpress64 board configs

[Sudeep Holla]

On Mon, Dec 20, 2021 at 06:12:03PM +0000, Andre Przywara wrote:
> From: Peter Hoyes <Peter.Hoyes@arm.com>
> 
> Create a new documentation section for Arm Ltd boards with a sub-page
> for the FVP VExpress64 system.
>

Reviewed-by: Sudeep Holla <sudeep.holla@arm.com>

-- 
Regards,
Sudeep

Re: [PATCH v2 2/2] doc: add Arm Juno board documentation

[Sudeep Holla]

On Mon, Dec 20, 2021 at 06:12:04PM +0000, Andre Przywara wrote:
> The Juno Arm development board is an open, vendor-neutral, Armv8-A
> development platform.
> Add documentation that briefly outlines the hardware, and describes
> building and installation of U-Boot.
> 

Reviewed-by: Sudeep Holla <sudeep.holla@arm.com>

-- 
Regards,
Sudeep

Re: [PATCH v2 2/2] doc: add Arm Juno board documentation

[Linus Walleij]

On Mon, Dec 20, 2021 at 7:12 PM Andre Przywara <andre.przywara@arm.com> wrote:

> The Juno Arm development board is an open, vendor-neutral, Armv8-A
> development platform.
> Add documentation that briefly outlines the hardware, and describes
> building and installation of U-Boot.
>
> Signed-off-by: Andre Przywara <andre.przywara@arm.com>

This is excellent and much needed documentation.
Thank you so much for doing this Andre!
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij

Re: [PATCH v2 1/2] doc: Add documentation for the Arm VExpress64 board configs

[Linus Walleij]

On Mon, Dec 20, 2021 at 7:12 PM Andre Przywara <andre.przywara@arm.com> wrote:

> From: Peter Hoyes <Peter.Hoyes@arm.com>
>
> Create a new documentation section for Arm Ltd boards with a sub-page
> for the FVP VExpress64 system.
>
> Signed-off-by: Peter Hoyes <Peter.Hoyes@arm.com>
> [Andre: remove Juno stub, RSTify]
> Signed-off-by: Andre Przywara <andre.przywara@arm.com>

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij

Re: [PATCH v2 2/2] doc: add Arm Juno board documentation

[Simon Glass]

On Mon, 20 Dec 2021 at 11:12, Andre Przywara <andre.przywara@arm.com> wrote:
>
> The Juno Arm development board is an open, vendor-neutral, Armv8-A
> development platform.
> Add documentation that briefly outlines the hardware, and describes
> building and installation of U-Boot.
>
> Signed-off-by: Andre Przywara <andre.przywara@arm.com>
> ---
>  doc/board/armltd/index.rst |   1 +
>  doc/board/armltd/juno.rst  | 114 +++++++++++++++++++++++++++++++++++++
>  2 files changed, 115 insertions(+)
>  create mode 100644 doc/board/armltd/juno.rst

Missing change log

Reviewed-by: Simon Glass <sjg@chromium.org>

Re: [PATCH v2 1/2] doc: Add documentation for the Arm VExpress64 board configs

[Simon Glass]

On Mon, 20 Dec 2021 at 11:12, Andre Przywara <andre.przywara@arm.com> wrote:
>
> From: Peter Hoyes <Peter.Hoyes@arm.com>
>
> Create a new documentation section for Arm Ltd boards with a sub-page
> for the FVP VExpress64 system.
>
> Signed-off-by: Peter Hoyes <Peter.Hoyes@arm.com>
> [Andre: remove Juno stub, RSTify]
> Signed-off-by: Andre Przywara <andre.przywara@arm.com>
> ---
>  doc/board/armltd/fvp64.rst | 30 ++++++++++++++++++++++++++++++
>  doc/board/armltd/index.rst | 10 ++++++++++
>  doc/board/index.rst        |  1 +
>  3 files changed, 41 insertions(+)
>  create mode 100644 doc/board/armltd/fvp64.rst
>  create mode 100644 doc/board/armltd/index.rst

Reviewed-by: Simon Glass <sjg@chromium.org>
Missing change log