[PATCH 0/2] Arm Juno board documentation

[PATCH 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

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  | 117 +++++++++++++++++++++++++++++++++++++
 doc/board/index.rst        |   1 +
 4 files changed, 159 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 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]
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..9817b0aa3f
--- /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 [1]_ (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 [4]_. The u-boot binary can be passed
+into the TF-A build: ``make PLAT=<platform> all fip BL33=u-boot.bin``
+
+The FVPs can be debugged using Arm Development Studio [2]_.
+
+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/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 74ea33e081..78b486538b 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 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  | 117 +++++++++++++++++++++++++++++++++++++
 2 files changed, 118 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..f37bc2c78e
--- /dev/null
+++ b/doc/board/armltd/juno.rst
@@ -0,0 +1,117 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. Copyright (C) 2021 Arm Ltd.
+
+Arm Juno board
+==============
+
+The `Juno development board`_ is an open, vendor-neutral, Armv8-A
+development platform, made by Arm Ltd. It is based on the former Versatile
+Express series.
+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 (MCP),
+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).
+
+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 MCP, based on the content of a micro-SD
+card, which will be exported as a USB mass storage device via the rear USB-B
+socket. So to access that SD card, connect a USB-A->USB-B cable between some
+host computer and the board, and mount the FAT partition on 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 beforehand.
+
+To just repackage with an updated U-Boot, first extract the current FIP image:
+
+.. code-block:: bash
+
+    $ mkdir /tmp/juno; cd /tmp/juno
+    $ fiptool unpack /mnt/juno/SOFTWARE/fip.bin
+
+Then, re-assemble the FIP image, replacing the "``nt-fw``" component with
+your newly compiled ``u-boot.bin``. To find the right command line, look at the
+output of "``fiptool info``", then use the given command line option for each
+file:
+
+.. code-block:: bash
+
+    $ fiptool info /mnt/juno/SOFTWARE/fip.bin
+    $ fiptool create --scp-fw scp-fw.bin --soc-fw soc-fw.bin \
+      --hw-config hw-config.bin ... --nt-fw /path/to/your/u-boot.bin fip.bin
+    $ cp fip.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`` (as 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 root of the SD card, as ``juno.dtb``,
+``juno-r1.dtb``, and ``juno-r2.dtb``, respectively. The MCP firmware will copy
+the one matching the board revision into the NOR flash, into 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 SD card.
+
+.. _`Juno development board`: https://developer.arm.com/tools-and-software/development-boards/juno-development-board
+.. _`SCP firmware`: https://github.com/ARM-software/SCP-firmware.git
-- 
2.25.1

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

[Sudeep Holla]

On Tue, Dec 14, 2021 at 05:55:39PM +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.
> 
> Signed-off-by: Andre Przywara <andre.przywara@arm.com>
> ---
>  doc/board/armltd/index.rst |   1 +
>  doc/board/armltd/juno.rst  | 117 +++++++++++++++++++++++++++++++++++++
>  2 files changed, 118 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..f37bc2c78e
> --- /dev/null
> +++ b/doc/board/armltd/juno.rst
> @@ -0,0 +1,117 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. Copyright (C) 2021 Arm Ltd.
> +
> +Arm Juno board
> +==============
> +
> +The `Juno development board`_ is an open, vendor-neutral, Armv8-A
> +development platform, made by Arm Ltd. It is based on the former Versatile
> +Express series.
> +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 (MCP),

IIRC the MCP is new and inside the SoC. You may refer [1], [2] and use the
terminologies from there to be consistent with the documentation. IIRC this
one is referred as MCC. So I would prefer s/MCP/MCC or MB throughout this
document.

> +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).
> +
> +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 MCP, based on the content of a micro-SD
> +card, which will be exported as a USB mass storage device via the rear USB-B
> +socket. So to access that SD card, connect a USB-A->USB-B cable between some
> +host computer and the board, and mount the FAT partition on 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...
> +

Not sure if you need these details(above one paragraph) here if we can direct
to one of the pages I have pointed out or specifically [3]. I guess you can
add other topics from there and links to those subsections if you need more
details. I am fine either way.

Otherwise looks good. Thanks for doing this.

-- 
Regards,
Sudeep

[1] https://developer.arm.com/documentation/100113/0000
[2] https://developer.arm.com/documentation/dui0928/e/firmware/firmware-components
[3] https://developer.arm.com/documentation/dui0928/e/configuration/connecting-to-a-host-computer?lang=en

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

[Sudeep Holla]

On Tue, Dec 14, 2021 at 05:55:38PM +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.
> 
> Signed-off-by: Peter Hoyes <Peter.Hoyes@arm.com>
> [Andre: remove Juno stub]
> Signed-off-by: Andre Przywara <andre.przywara@arm.com>

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

-- 
Regards,
Sudeep

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

[Robin Murphy]

Hi Andre,

On 2021-12-14 17:55, 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.
> 
> Signed-off-by: Andre Przywara <andre.przywara@arm.com>
> ---
>   doc/board/armltd/index.rst |   1 +
>   doc/board/armltd/juno.rst  | 117 +++++++++++++++++++++++++++++++++++++
>   2 files changed, 118 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..f37bc2c78e
> --- /dev/null
> +++ b/doc/board/armltd/juno.rst
> @@ -0,0 +1,117 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. Copyright (C) 2021 Arm Ltd.
> +
> +Arm Juno board
> +==============
> +
> +The `Juno development board`_ is an open, vendor-neutral, Armv8-A

Nit: I believe its official name (or at least the closest thing to one) 
is "Juno ARM Development Platform", although that's admittedly not how 
the hardware product page being cross-referenced here is titled. Maybe 
that's just one for the commit message.

> +development platform, made by Arm Ltd. It is based on the former Versatile

Arguably not so much "based on" as "part of" ;)

> +Express series.
> +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 (MCP),

Note that "MCP" is a standard name for something else not relevant to 
Juno - the correct name for this thing is "MCC" (Motherboard 
Configuration Controller).

> +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).
> +
> +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 MCP, based on the content of a micro-SD
> +card, which will be exported as a USB mass storage device via the rear USB-B
> +socket. So to access that SD card, connect a USB-A->USB-B cable between some
> +host computer and the board, and mount the FAT partition on the UMS device.

This sentence feels a little prejudiced against those of us with only 
USB-C host ports :P

If you want to get into this much detail it could be worth noting that 
it's also viable (and often faster with large images) to power off the 
board completely and pop the card out from behind the front panel. But 
for a simple guide I reckon the mere mention of the USB-B socket and 
FAT16-formatted card implies enough already.

> +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 beforehand.
> +
> +To just repackage with an updated U-Boot, first extract the current FIP image:

There should be a `fiptool update` command that allows replacing one or 
more components in a FIP image directly, which is probably less daunting 
for the casual user.

> +
> +.. code-block:: bash
> +
> +    $ mkdir /tmp/juno; cd /tmp/juno
> +    $ fiptool unpack /mnt/juno/SOFTWARE/fip.bin
> +
> +Then, re-assemble the FIP image, replacing the "``nt-fw``" component with
> +your newly compiled ``u-boot.bin``. To find the right command line, look at the
> +output of "``fiptool info``", then use the given command line option for each
> +file:
> +
> +.. code-block:: bash
> +
> +    $ fiptool info /mnt/juno/SOFTWARE/fip.bin
> +    $ fiptool create --scp-fw scp-fw.bin --soc-fw soc-fw.bin \
> +      --hw-config hw-config.bin ... --nt-fw /path/to/your/u-boot.bin fip.bin
> +    $ cp fip.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`` (as 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 root of the SD card, as ``juno.dtb``,
> +``juno-r1.dtb``, and ``juno-r2.dtb``, respectively. The MCP firmware will copy
> +the one matching the board revision into the NOR flash, into the ``board.dtb``

While this is technically not untrue for the typical case, I wonder if 
it might be a slightly misleading oversimplification. AFAIK the MCC 
doesn't have any awareness beyond looking for configuration files in one 
of the \SITE1\HBI0262[BCD] directories based on the board ID. It is the 
images.txt files in there wherein in the stock firmware configuration 
plays the trick of associating different DTB filenames with the same NOR 
address. This might matter if anyone's tinkered with that configuration 
already, or possibly still has a really ancient firmware setup (I have a 
vague memory of something wacky with both r0 and r1 DTBs present and 
EDK2 deciding which one to pass to Linux).

Also I believe the stock setup assumes DTBs in \SOFTWARE, rather than 
the root directory. At least that's how my r2 here seems to be (not that 
I've ever actually used it without loading a custom one from GRUB...)

Thanks,
Robin.

> +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 SD card.
> +
> +.. _`Juno development board`: https://developer.arm.com/tools-and-software/development-boards/juno-development-board
> +.. _`SCP firmware`: https://github.com/ARM-software/SCP-firmware.git

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

[Andre Przywara]

On Wed, 15 Dec 2021 12:44:16 +0000
Sudeep Holla <sudeep.holla@arm.com> wrote:

Hi Sudeep,

> On Tue, Dec 14, 2021 at 05:55:39PM +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.
> > 
> > Signed-off-by: Andre Przywara <andre.przywara@arm.com>
> > ---
> >  doc/board/armltd/index.rst |   1 +
> >  doc/board/armltd/juno.rst  | 117 +++++++++++++++++++++++++++++++++++++
> >  2 files changed, 118 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..f37bc2c78e
> > --- /dev/null
> > +++ b/doc/board/armltd/juno.rst
> > @@ -0,0 +1,117 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +.. Copyright (C) 2021 Arm Ltd.
> > +
> > +Arm Juno board
> > +==============
> > +
> > +The `Juno development board`_ is an open, vendor-neutral, Armv8-A
> > +development platform, made by Arm Ltd. It is based on the former Versatile
> > +Express series.
> > +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 (MCP),  
> 
> IIRC the MCP is new and inside the SoC. You may refer [1], [2] and use the
> terminologies from there to be consistent with the documentation. IIRC this
> one is referred as MCC. So I would prefer s/MCP/MCC or MB throughout this
> document.

True, I managed to mix that up, thanks for pointing this out!

> > +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).
> > +
> > +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 MCP, based on the content of a micro-SD
> > +card, which will be exported as a USB mass storage device via the rear USB-B
> > +socket. So to access that SD card, connect a USB-A->USB-B cable between some
> > +host computer and the board, and mount the FAT partition on 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...
> > +  
> 
> Not sure if you need these details(above one paragraph) here if we can direct
> to one of the pages I have pointed out or specifically [3]. I guess you can
> add other topics from there and links to those subsections if you need more
> details. I am fine either way.

Yeah, I will add a link to the Juno TRM, and refer to that. But at least
on the Linux side I have seen pushback against deep links to manufacturer
websites in documentation, since those URLs tend to 404 sooner or later.
So I am tempted to keep at least that usb_on command in, since I needed to
use that at times, and it's a quick solution to a common problem.

Thanks for your comments!
Andre

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

[Andre Przywara]

On Wed, 15 Dec 2021 15:33:58 +0000
Robin Murphy <robin.murphy@arm.com> wrote:

Hi Robin,

many thanks for having a look and the comments!

> On 2021-12-14 17:55, 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.
> > 
> > Signed-off-by: Andre Przywara <andre.przywara@arm.com>
> > ---
> >   doc/board/armltd/index.rst |   1 +
> >   doc/board/armltd/juno.rst  | 117 +++++++++++++++++++++++++++++++++++++
> >   2 files changed, 118 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..f37bc2c78e
> > --- /dev/null
> > +++ b/doc/board/armltd/juno.rst
> > @@ -0,0 +1,117 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +.. Copyright (C) 2021 Arm Ltd.
> > +
> > +Arm Juno board
> > +==============
> > +
> > +The `Juno development board`_ is an open, vendor-neutral, Armv8-A  
> 
> Nit: I believe its official name (or at least the closest thing to one) 
> is "Juno ARM Development Platform", although that's admittedly not how 
> the hardware product page being cross-referenced here is titled. Maybe 
> that's just one for the commit message.

OK, I will try so squeeze the official name in somewhere, but find the
term "platform" somewhat overloaded, and given Arm's vast offering of
virtual platforms somewhat confusing, because the Juno is actual hardware.

> > +development platform, made by Arm Ltd. It is based on the former Versatile  
> 
> Arguably not so much "based on" as "part of" ;)

Right, I changed it to make the Juno part of the family now ;-)

> > +Express series.
> > +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 (MCP),  
> 
> Note that "MCP" is a standard name for something else not relevant to 
> Juno - the correct name for this thing is "MCC" (Motherboard 
> Configuration Controller).

Right, thanks for pointing this out.

> > +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).
> > +
> > +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 MCP, based on the content of a micro-SD
> > +card, which will be exported as a USB mass storage device via the rear USB-B
> > +socket. So to access that SD card, connect a USB-A->USB-B cable between some
> > +host computer and the board, and mount the FAT partition on the UMS device.  
> 
> This sentence feels a little prejudiced against those of us with only 
> USB-C host ports :P

My condolences ;-)

> If you want to get into this much detail it could be worth noting that 
> it's also viable (and often faster with large images) to power off the 
> board completely and pop the card out from behind the front panel. But 
> for a simple guide I reckon the mere mention of the USB-B socket and 
> FAT16-formatted card implies enough already.

Good point, makes this simpler and more versatile. I guess people playing
around with firmware updates can be trusted to connect a USB cable.

> > +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 beforehand.
> > +
> > +To just repackage with an updated U-Boot, first extract the current FIP image:  
> 
> There should be a `fiptool update` command that allows replacing one or 
> more components in a FIP image directly, which is probably less daunting 
> for the casual user.

Ah, thanks, that's a good one, didn't know that (I was mostly re-compiling
TF-A). Will change that section, since it's indeed so much easier.

> > +
> > +.. code-block:: bash
> > +
> > +    $ mkdir /tmp/juno; cd /tmp/juno
> > +    $ fiptool unpack /mnt/juno/SOFTWARE/fip.bin
> > +
> > +Then, re-assemble the FIP image, replacing the "``nt-fw``" component with
> > +your newly compiled ``u-boot.bin``. To find the right command line, look at the
> > +output of "``fiptool info``", then use the given command line option for each
> > +file:
> > +
> > +.. code-block:: bash
> > +
> > +    $ fiptool info /mnt/juno/SOFTWARE/fip.bin
> > +    $ fiptool create --scp-fw scp-fw.bin --soc-fw soc-fw.bin \
> > +      --hw-config hw-config.bin ... --nt-fw /path/to/your/u-boot.bin fip.bin
> > +    $ cp fip.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`` (as 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 root of the SD card, as ``juno.dtb``,
> > +``juno-r1.dtb``, and ``juno-r2.dtb``, respectively. The MCP firmware will copy
> > +the one matching the board revision into the NOR flash, into the ``board.dtb``  
> 
> While this is technically not untrue for the typical case, I wonder if 
> it might be a slightly misleading oversimplification. AFAIK the MCC 
> doesn't have any awareness beyond looking for configuration files in one 
> of the \SITE1\HBI0262[BCD] directories based on the board ID. It is the 
> images.txt files in there wherein in the stock firmware configuration 
> plays the trick of associating different DTB filenames with the same NOR 
> address.

This is correct, but the outcome for the user is the same: the right DTB
lands in the NOR flash partition. I can mention images.txt, but didn't
want to over-complicate things. I believe that people playing around with
those files know what they do, and they are not really the target audience
of this document.

> This might matter if anyone's tinkered with that configuration 
> already, or possibly still has a really ancient firmware setup (I have a 
> vague memory of something wacky with both r0 and r1 DTBs present and 
> EDK2 deciding which one to pass to Linux).

I can add a link to one of those recovery.zip files, which should allow
older boards to arrive in the 21st century.

> Also I believe the stock setup assumes DTBs in \SOFTWARE, rather than 
> the root directory. At least that's how my r2 here seems to be (not that 
> I've ever actually used it without loading a custom one from GRUB...)

Right, they are in SOFTWARE/, not in the root. My bad.
Since sometimes earlier this year U-Boot picks up the DTB from the NOR
flash partition, and you can pass this on to a kernel, which is also the
default for UEFI apps. So those files there are useful now.

Thanks!
Andre

> > +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 SD card.
> > +
> > +.. _`Juno development board`: https://developer.arm.com/tools-and-software/development-boards/juno-development-board
> > +.. _`SCP firmware`: https://github.com/ARM-software/SCP-firmware.git  

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

[Simon Glass]

Hi Andre,

On Tue, 14 Dec 2021 at 10:55, 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]
> 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..9817b0aa3f
> --- /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 [1]_ (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 [4]_. The u-boot binary can be passed

TF-A has become a bootloader?!

> +into the TF-A build: ``make PLAT=<platform> all fip BL33=u-boot.bin``

What is <platform> in this case?

> +
> +The FVPs can be debugged using Arm Development Studio [2]_.
> +
> +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/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 74ea33e081..78b486538b 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
>

Regards,
Simon

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

[Simon Glass]

On Tue, 14 Dec 2021 at 10:55, 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  | 117 +++++++++++++++++++++++++++++++++++++
>  2 files changed, 118 insertions(+)
>  create mode 100644 doc/board/armltd/juno.rst
>

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

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

[Andre Przywara]

On Fri, 17 Dec 2021 09:37:12 -0700
Simon Glass <sjg@chromium.org> wrote:

Hi,

> On Tue, 14 Dec 2021 at 10:55, 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]
> > 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..9817b0aa3f
> > --- /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 [1]_ (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 [4]_. The u-boot binary can be passed  
> 
> TF-A has become a bootloader?!

As much as U-Boot is firmware, yes :-P

The full featured TF-A suite contains a whole loading stage (BL2), some
platforms have MMC and even USB drivers. We can also put a Linux kernel
directly into DRAM, then TF-A directly drops into Linux directly.

The point is that for those virtual platforms a boot*loader* is strictly
speaking not required, since you can much easier load through your host
- either via semihosting or by letting the model programme put your
binaries directly into the emulated DRAM.

> 
> > +into the TF-A build: ``make PLAT=<platform> all fip BL33=u-boot.bin``  
> 
> What is <platform> in this case?

That depends on the exact model, but just "fvp" would probably be good
enough to put in here.

Cheers,
Andre

> > +
> > +The FVPs can be debugged using Arm Development Studio [2]_.
> > +
> > +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/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 74ea33e081..78b486538b 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
> >  
> 
> Regards,
> Simon