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... +.. [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

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

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-develop... +.. _`SCP firmware`: https://github.com/ARM-software/SCP-firmware.git