1.. SPDX-License-Identifier: GPL-2.0
2.. Copyright (C) 2021 Arm Ltd.
3
4Arm Juno development platform
5=============================
6
7The `Juno development board`_ is an open, vendor-neutral, Armv8-A development
8platform, made by Arm Ltd. It is part of the Versatile Express family.
9There are three revisions of the board:
10
11* Juno r0, with two Cortex-A57 and four Cortex-A53 cores, without PCIe.
12* Juno r1, with two Cortex-A57 and four Cortex-A53 cores, in later silicon
13  revisions, and with PCIe slots, Gigabit Ethernet and two SATA ports.
14* Juno r2, with two Cortex-A72 and four Cortex-A53 cores, otherwise the
15  same as r1.
16
17Among other things, the motherboard contains a management controller (MCC),
18an FPGA providing I/O interfaces (IOFPGA) and 64MB of NOR flash. The provided
19platform devices resemble the VExpress peripherals.
20The actual SoC also contains a Cortex-M3 based System Control Processor (SCP).
21The `V2M-Juno TRM`_ contains more technical details.
22
23U-Boot build
24------------
25There is only one defconfig and one binary build that covers all three board
26revisions, so to generate the needed ``u-boot.bin``:
27
28.. code-block:: bash
29
30    $ make vexpress_aemv8a_juno_defconfig
31    $ make
32
33The automatic distro boot sequence looks for UEFI boot applications and
34``boot.scr`` scripts on various boot media, starting with USB, then on disks
35connected to the two SATA ports, PXE, DHCP and eventually on the NOR flash.
36
37U-Boot installation
38-------------------
39This assumes there is some firmware on the SD card or NOR flash (see below
40for more details). The U-Boot binary is included in the Trusted Firmware
41FIP image, so after building U-Boot, this needs to be repackaged or recompiled.
42
43The NOR flash will be updated by the MCC, based on the content of a micro-SD
44card, which is exported as a USB mass storage device via the rear USB-B
45socket. So to access that SD card, connect a cable to some host computer, and
46mount the FAT16 partition of the UMS device.
47If there is no device, check the upper serial port for a prompt, and
48explicitly enable the USB interface::
49
50    Cmd> usb_on
51    Enabling debug USB...
52
53Repackaging an existing FIP image
54^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
55To prevent problems, it is probably a good idea to backup the existing firmware,
56for instance by just copying the entire ``SOFTWARE/`` directory, or at least
57the current ``fip.bin``, beforehand.
58
59To just replace the BL33 image in the exising FIP image, you can use
60`fiptool`_ from the Trusted Firmware repository, on the image file:
61
62.. code-block:: bash
63
64    git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
65    cd trusted-firmware-a
66    make fiptool
67    tools/fiptool/fiptool update --nt-fw=/path/to/your/u-boot.bin /mnt/juno/SOFTWARE/fip.bin
68
69Unmount the USB mass storage device and reboot the board, the new ``fip.bin``
70will be automatically written to the NOR flash and then used.
71
72Rebuilding Trusted Firmware
73^^^^^^^^^^^^^^^^^^^^^^^^^^^
74You can also generate a new FIP image by compiling Arm Trusted Firmware,
75and providing ``u-boot.bin`` as the BL33 file. For that you can either build
76the required `SCP firmware`_ yourself, or just extract the existing
77version from your ``fip.bin``, using `fiptool`_ (see above):
78
79.. code-block:: bash
80
81    mkdir /tmp/juno; cd /tmp/juno
82    fiptool unpack /mnt/juno/SOFTWARE/fip.bin
83
84Then build TF-A:
85
86.. code-block:: bash
87
88    git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
89    cd trusted-firmware-a
90    make CROSS_COMPILE=aarch64-linux-gnu- PLAT=juno DEBUG=1 \
91    SCP_BL2=/tmp/juno/scp-fw.bin BL33=/path/to/your/u-boot.bin fiptool all fip
92    cp build/juno/debug/bl1.bin build/juno/debug/fip.bin /mnt/juno/SOFTWARE
93
94Then umount the USB device, and reboot, as above.
95
96Device trees
97------------
98The device tree files for the boards are maintained in the Linux kernel
99repository. They end up in the ``SOFTWARE/`` directory of the SD card, as
100``juno.dtb``, ``juno-r1.dtb``, and ``juno-r2.dtb``, respectively. The MCC
101firmware will look into the images.txt file matching the board revision, from
102the ``SITE1/`` directory. Each version there will reference its respective DTB
103file in ``SOFTWARE/``, and so the correct version will end in the NOR flash, in
104the ``board.dtb`` partition. U-Boot picks its control DTB from there, you can
105pass this on to a kernel using ``$fdtcontroladdr``.
106
107You can update the DTBs anytime, by building them using the ``dtbs`` make
108target from a Linux kernel tree, then just copying the generated binaries
109to the ``SOFTWARE/`` directory of the SD card.
110
111.. _`Juno development board`: https://developer.arm.com/tools-and-software/development-boards/juno-development-board
112.. _`V2M-Juno TRM`: https://developer.arm.com/documentation/100113/latest
113.. _`fiptool`: https://github.com/ARM-software/arm-trusted-firmware/tree/master/tools/fiptool
114.. _`SCP firmware`: https://github.com/ARM-software/SCP-firmware.git
115