diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.bedbug | 56 | ||||
| -rw-r--r-- | doc/README.pxe | 6 | ||||
| -rw-r--r-- | doc/api/dm.rst | 29 | ||||
| -rw-r--r-- | doc/api/index.rst | 1 | ||||
| -rw-r--r-- | doc/board/armltd/index.rst | 1 | ||||
| -rw-r--r-- | doc/board/armltd/juno.rst | 114 | ||||
| -rw-r--r-- | doc/build/gcc.rst | 10 | ||||
| -rw-r--r-- | doc/develop/bloblist.rst | 8 | ||||
| -rw-r--r-- | doc/develop/driver-model/migration.rst | 12 | ||||
| -rw-r--r-- | doc/sphinx/requirements.txt | 6 |
10 files changed, 183 insertions, 60 deletions
diff --git a/doc/README.bedbug b/doc/README.bedbug deleted file mode 100644 index 1a2acd0f14..0000000000 --- a/doc/README.bedbug +++ /dev/null @@ -1,56 +0,0 @@ -BEDBUG Support for U-Boot --------------------------- - -These changes implement the bedbug (emBEDded deBUGger) debugger in U-Boot. - -##################### -### Modifications ### -##################### - -./common/Makefile - Included cmd_bedbug.c and bedbug.c in the Makefile. - -./common/board.c - Added call to initialize debugger on startup. - -./include/ppc_asm.tmpl - Added code to handle critical exceptions - -################# -### New Stuff ### -################# - -./include/bedbug/ppc.h -./include/bedbug/regs.h -./include/bedbug/bedbug.h -./include/bedbug/elf.h [obsoleted by new include/elf.h] -./include/bedbug/tables.h -./include/cmd_bedbug.h -./common/cmd_bedbug.c -./common/bedbug.c - Bedbug library includes code for assembling and disassembling - PowerPC instructions to/from memory as well as handling - hardware breakpoints and stepping through code. These - routines are common to all PowerPC processors. - -Bedbug support for the MPC860 ------------------------------ - -Changes: - - common/cmd_bedbug.c - Added call to initialize 860 debugger. - - arch/powerpc/cpu/mpc8xx/Makefile - Added new file "bedbug_860.c" to the makefile - - arch/powerpc/cpu/mpc8xx/start.S - Added handler for InstructionBreakpoint (0xfd00) - - arch/powerpc/cpu/mpc8xx/traps.c - Added new routine DebugException() - -New Files: - - arch/powerpc/cpu/mpc8xx/bedbug_860.c - CPU-specific routines for 860 debug registers. diff --git a/doc/README.pxe b/doc/README.pxe index b67151ca51..a1f0423adb 100644 --- a/doc/README.pxe +++ b/doc/README.pxe @@ -92,6 +92,12 @@ pxe boot fdtoverlay_addr_r - location in RAM at which 'pxe boot' will temporarily store fdt overlay(s) before applying them to the fdt blob stored at 'fdt_addr_r'. + pxe_label_override - override label to be used, if exists, instead of the + default label. This will allow consumers to choose a pxe label at + runtime instead of having to prompt the user. If "pxe_label_override" is set + but does not exist in the pxe menu, pxe would fallback to the default label if + given, and no failure is returned but rather a warning message. + pxe file format =============== The pxe file format is nearly a subset of the PXELINUX file format; see diff --git a/doc/api/dm.rst b/doc/api/dm.rst new file mode 100644 index 0000000000..df605dae9d --- /dev/null +++ b/doc/api/dm.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Driver Model +============ + +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 + +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 +.. kernel-doc:: include/dm/fdtaddr.h diff --git a/doc/api/index.rst b/doc/api/index.rst index 806c7385a6..3f36174167 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 diff --git a/doc/board/armltd/index.rst b/doc/board/armltd/index.rst index c20d8a0a26..fc1d75aac2 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 0000000000..761c037f92 --- /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 diff --git a/doc/build/gcc.rst b/doc/build/gcc.rst index cdd7970032..0e0d87a022 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 ------------- diff --git a/doc/develop/bloblist.rst b/doc/develop/bloblist.rst index 47274cf8e2..572aa65d76 100644 --- a/doc/develop/bloblist.rst +++ b/doc/develop/bloblist.rst @@ -31,7 +31,7 @@ Blobs While each blob in the bloblist can be of any length, bloblists are designed to hold small amounts of data, typically a few KB at most. It is not possible to change the length of a blob once it has been written. Each blob is normally -created from a C structure which can beused to access its fields. +created from a C structure which can be used to access its fields. Blob tags @@ -93,6 +93,12 @@ This should move to using bloblist, to avoid having its own mechanism for passing information between U-Boot parts. +API documentation +----------------- + +.. kernel-doc:: include/bloblist.h + + Simon Glass sjg@chromium.org 12-Aug-2018 diff --git a/doc/develop/driver-model/migration.rst b/doc/develop/driver-model/migration.rst index 3dbeea6537..10f474e9cd 100644 --- a/doc/develop/driver-model/migration.rst +++ b/doc/develop/driver-model/migration.rst @@ -106,3 +106,15 @@ Deadline: 2022.10 This is a legacy option which has been replaced by driver model. Maintainers should submit patches switching over to using CONFIG_DM_KEYBOARD and other base driver model options in time for inclusion in the 2022.10 release. + +CONFIG_SYS_TIMER_RATE and CONFIG_SYS_TIMER_COUNTER +-------------------------------------------------- +Deadline: 2023.01 + +These are legacy options which have been replaced by driver model. +Maintainers should submit patches switching over to using CONFIG_TIMER and +other base driver model options in time for inclusion in the 2022.10 release. + +There is only one method to implement, unless you want to support bootstage, +in which case you need an early timer also. For example drivers, see +sandbox_timer.c and rockchip_timer.c diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 4555a94d30..44c187880d 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 |