From 46620d21a65f2af6f1fb8a82b3c10186d9bc02b3 Mon Sep 17 00:00:00 2001 From: Andre Przywara Date: Mon, 20 Dec 2021 18:12:04 +0000 Subject: doc: add Arm Juno board documentation 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 Reviewed-by: Sudeep Holla Reviewed-by: Linus Walleij Reviewed-by: Simon Glass --- doc/board/armltd/index.rst | 1 + doc/board/armltd/juno.rst | 114 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 doc/board/armltd/juno.rst (limited to 'doc') diff --git a/doc/board/armltd/index.rst b/doc/board/armltd/index.rst index c20d8a0a26b..fc1d75aac29 100644 --- a/doc/board/armltd/index.rst +++ b/doc/board/armltd/index.rst @@ -6,4 +6,5 @@ Arm Ltd .. toctree:: :maxdepth: 2 + juno vexpress64.rst diff --git a/doc/board/armltd/juno.rst b/doc/board/armltd/juno.rst new file mode 100644 index 00000000000..761c037f92b --- /dev/null +++ b/doc/board/armltd/juno.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2021 Arm Ltd. + +Arm Juno development platform +============================= + +The `Juno development board`_ is an open, vendor-neutral, Armv8-A development +platform, made by Arm Ltd. It is part of the Versatile Express family. +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 (MCC), +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). +The `V2M-Juno TRM`_ contains more technical details. + +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 MCC, based on the content of a micro-SD +card, which is exported as a USB mass storage device via the rear USB-B +socket. So to access that SD card, connect a cable to some host computer, and +mount the FAT16 partition of 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, or at least +the current ``fip.bin``, beforehand. + +To just replace the BL33 image in the exising FIP image, you can use +`fiptool`_ from the Trusted Firmware repository, on the image file: + +.. code-block:: bash + + git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git + cd trusted-firmware-a + make fiptool + tools/fiptool/fiptool update --nt-fw=/path/to/your/u-boot.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``, using `fiptool`_ (see 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 ``SOFTWARE/`` directory of the SD card, as +``juno.dtb``, ``juno-r1.dtb``, and ``juno-r2.dtb``, respectively. The MCC +firmware will look into the images.txt file matching the board revision, from +the ``SITE1/`` directory. Each version there will reference its respective DTB +file in ``SOFTWARE/``, and so the correct version will end in the NOR flash, in +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 ``SOFTWARE/`` directory of the SD card. + +.. _`Juno development board`: https://developer.arm.com/tools-and-software/development-boards/juno-development-board +.. _`V2M-Juno TRM`: https://developer.arm.com/documentation/100113/latest +.. _`fiptool`: https://github.com/ARM-software/arm-trusted-firmware/tree/master/tools/fiptool +.. _`SCP firmware`: https://github.com/ARM-software/SCP-firmware.git -- cgit v1.2.3 From bba1cc9b8c857855f4db42dc9f92b0f98d78df25 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Tue, 11 Jan 2022 01:37:01 +0100 Subject: doc: Building on Alpine Linux Describe the required packages for building U-Boot on Alpine Linux Signed-off-by: Heinrich Schuchardt --- doc/build/gcc.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'doc') diff --git a/doc/build/gcc.rst b/doc/build/gcc.rst index cdd79700326..0e0d87a022d 100644 --- a/doc/build/gcc.rst +++ b/doc/build/gcc.rst @@ -51,6 +51,16 @@ Depending on the build targets further packages maybe needed. zypper install bc bison flex gcc libopenssl-devel libSDL2-devel make \ ncurses-devel python3-devel python3-pytest swig +Alpine Linux +~~~~~~~~~~~~ + +For building U-Boot on Alpine Linux at least the following packages are needed: + +.. code-block:: bash + + apk add alpine-sdk bc bison dtc flex linux-headers ncurses-dev \ + openssl-dev python3 py3-setuptools python3-dev sdl2 + Prerequisites ------------- -- cgit v1.2.3 From 8804b276a7ebab31573ecbbf08832a54bdfad48d Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Wed, 12 Jan 2022 02:35:00 +0100 Subject: .readthedocs.yml: update the requirements Fix an error: This project needs at least Sphinx v2.4.4. Signed-off-by: Heinrich Schuchardt --- doc/sphinx/requirements.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 4555a94d300..44c187880d6 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -1,4 +1,4 @@ docutils==0.16 -Sphinx==3.4.3 -sphinx_rtd_theme -six +sphinx==3.4.3 +sphinx_rtd_theme==1.0.0 +six==1.16.0 -- cgit v1.2.3 From 797b2a2ed4a0d34ea521e6ee07a31bdb5bd8c14a Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:42 +0100 Subject: doc: add include/dm/uclass.h to the HTML documentation Correct Sphinx style comments in include/dm/uclass.h and add the driver model UCLASS API to the HTML documentation. Signed-off-by: Patrick Delaunay Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 9 +++++++++ doc/api/index.rst | 1 + 2 files changed, 10 insertions(+) create mode 100644 doc/api/dm.rst (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst new file mode 100644 index 00000000000..edce25da51d --- /dev/null +++ b/doc/api/dm.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Driver Model +============ + +Uclass and Driver +----------------- + +.. kernel-doc:: include/dm/uclass.h diff --git a/doc/api/index.rst b/doc/api/index.rst index 806c7385a62..3f361741677 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -7,6 +7,7 @@ U-Boot API documentation :maxdepth: 2 dfu + dm efi getopt linker_lists -- cgit v1.2.3 From 0cdd7ded8887d41d83f518e7b352972e58b47a1e Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:43 +0100 Subject: doc: add include/dm/root.h to the HTML documentation Correct Sphinx style comments in include/dm/devres.h and add the associated driver model API to the HTML documentation. Signed-off-by: Patrick Delaunay Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst index edce25da51d..181a454c245 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -7,3 +7,4 @@ Uclass and Driver ----------------- .. kernel-doc:: include/dm/uclass.h +.. kernel-doc:: include/dm/root.h -- cgit v1.2.3 From cbb14ac92c1a40201aae0328b3af690dff133ecd Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:44 +0100 Subject: doc: add include/dm/lists.h to the HTML documentation Correct Sphinx style comments in include/dm/lists.h and add the list API to the HTML documentation. Signed-off-by: Patrick Delaunay Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 181a454c245..168d129250c 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -8,3 +8,4 @@ Uclass and Driver .. kernel-doc:: include/dm/uclass.h .. kernel-doc:: include/dm/root.h +.. kernel-doc:: include/dm/lists.h -- cgit v1.2.3 From ca4ca43e2f245a03b0953e723e38c49c676af78c Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:45 +0100 Subject: doc: add include/dm/platdata.h to the HTML documentation Correct Sphinx style comments in include/dm/platdata.h and add the associated API to the HTML documentation. Signed-off-by: Patrick Delaunay Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 168d129250c..6f72b0b6201 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -9,3 +9,4 @@ Uclass and Driver .. kernel-doc:: include/dm/uclass.h .. kernel-doc:: include/dm/root.h .. kernel-doc:: include/dm/lists.h +.. kernel-doc:: include/dm/platdata.h -- cgit v1.2.3 From 9fb1c77ef645232b95aa15e6f445aba8559186e1 Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:46 +0100 Subject: doc: add include/dm/device.h to the HTML documentation Correct Sphinx style comments in include/dm/device.h and add the driver model device API to the HTML documentation. Signed-off-by: Patrick Delaunay Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 6f72b0b6201..7a77a91c1f9 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -10,3 +10,8 @@ Uclass and Driver .. kernel-doc:: include/dm/root.h .. kernel-doc:: include/dm/lists.h .. kernel-doc:: include/dm/platdata.h + +Device +------ + +.. kernel-doc:: include/dm/device.h -- cgit v1.2.3 From 494bc8e6f0f125cf706f27aac1a219f3eb3c8565 Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:47 +0100 Subject: doc: add include/dm/devres.h to the HTML documentation Correct Sphinx style comments in include/dm/devres.h and add the driver model device resource API, devres_*(), to the HTML documentation. Signed-off-by: Patrick Delaunay Reviewed-by-by: Heinrich Schuchardt --- doc/api/dm.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 7a77a91c1f9..0342620786a 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -15,3 +15,4 @@ Device ------ .. kernel-doc:: include/dm/device.h +.. kernel-doc:: include/dm/devres.h -- cgit v1.2.3 From 6de6a615f8527b722b512b0ea36821ab2439b773 Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:48 +0100 Subject: doc: add include/dm/read.h to the HTML documentation Correct Sphinx style comments in include/dm/read.h and add the device read from device tree API to the HTML documentation. Signed-off-by: Patrick Delaunay Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 0342620786a..19a473f1f09 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -16,3 +16,4 @@ Device .. kernel-doc:: include/dm/device.h .. kernel-doc:: include/dm/devres.h +.. kernel-doc:: include/dm/read.h -- cgit v1.2.3 From be74f71a679c8ca25a09bea86967dcee8a8b8cae Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:49 +0100 Subject: doc: add include/dm/of*.h to the HTML documentation Correct Sphinx style comments in include/dm/ofnode.h and add the device tree node API to the HTML documentation; the ofnode functions are compatible with Live tree or with flat device tree. Signed-off-by: Patrick Delaunay Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 19a473f1f09..5bb66f2f507 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -17,3 +17,12 @@ Device .. kernel-doc:: include/dm/device.h .. kernel-doc:: include/dm/devres.h .. kernel-doc:: include/dm/read.h + +Device tree +----------- + +.. kernel-doc:: include/dm/of.h +.. kernel-doc:: include/dm/ofnode.h +.. kernel-doc:: include/dm/of_extra.h +.. kernel-doc:: include/dm/of_access.h +.. kernel-doc:: include/dm/of_addr.h -- cgit v1.2.3 From 5ebb52702edeeb2b46699ead31c56a7a5a127b49 Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:55:41 +0100 Subject: doc: add include/dm/fdtaddr.h to the HTML documentation Correct Sphinx style comments in include/dm/fdtaddr.h and add the devfdt API to the HTML documentation; these functions are NOT compatible with live tree. Signed-off-by: Patrick Delaunay Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 5bb66f2f507..df605dae9d6 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -26,3 +26,4 @@ Device tree .. kernel-doc:: include/dm/of_extra.h .. kernel-doc:: include/dm/of_access.h .. kernel-doc:: include/dm/of_addr.h +.. kernel-doc:: include/dm/fdtaddr.h -- cgit v1.2.3