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

Thu Dec 16 18:56:54 CET 2021

On Wed, 15 Dec 2021 15:33:58 +0000
Robin Murphy <robin.murphy at 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 at 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  