[PATCH 2/2] doc: add Arm Juno board documentation
Robin Murphy
robin.murphy at arm.com
Wed Dec 15 16:33:58 CET 2021
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 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.
> +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
More information about the U-Boot
mailing list