diff options
Diffstat (limited to 'doc')
39 files changed, 2373 insertions, 146 deletions
diff --git a/doc/api/index.rst b/doc/api/index.rst index a9338cfef9..3a80ae0635 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -15,6 +15,7 @@ U-Boot API documentation lmb logging nvmem + part pinctrl rng sandbox diff --git a/doc/api/part.rst b/doc/api/part.rst new file mode 100644 index 0000000000..d1df1d8494 --- /dev/null +++ b/doc/api/part.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Partition API +============= + +.. kernel-doc:: include/part.h diff --git a/doc/arch/arm64.ffa.rst b/doc/arch/arm64.ffa.rst new file mode 100644 index 0000000000..4ecdc31716 --- /dev/null +++ b/doc/arch/arm64.ffa.rst @@ -0,0 +1,261 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Arm FF-A Support +================ + +Summary +------- + +FF-A stands for Firmware Framework for Arm A-profile processors. + +FF-A specifies interfaces that enable a pair of software execution environments aka partitions to +communicate with each other. A partition could be a VM in the Normal or Secure world, an +application in S-EL0, or a Trusted OS in S-EL1. + +The U-Boot FF-A support (the bus) implements the interfaces to communicate +with partitions in the Secure world aka Secure partitions (SPs). + +The FF-A support specifically focuses on communicating with SPs that +isolate portions of EFI runtime services that must run in a protected +environment which is inaccessible by the Host OS or Hypervisor. +Examples of such services are set/get variables. + +The FF-A support uses the SMC ABIs defined by the FF-A specification to: + +- Discover the presence of SPs of interest +- Access an SP's service through communication protocols + e.g. EFI MM communication protocol + +At this stage of development only EFI boot-time services are supported. +Runtime support will be added in future developments. + +The U-Boot FF-A support provides the following parts: + +- A Uclass driver providing generic FF-A methods. +- An Arm FF-A device driver providing Arm-specific methods and reusing the Uclass methods. +- A sandbox emulator for Arm FF-A, emulates the FF-A side of the Secure World and provides + FF-A ABIs inspection methods. +- An FF-A sandbox device driver for FF-A communication with the emulated Secure World. + The driver leverages the FF-A Uclass to establish FF-A communication. +- Sandbox FF-A test cases. + +FF-A and SMC specifications +------------------------------------------- + +The current implementation of the U-Boot FF-A support relies on +`FF-A v1.0 specification`_ and uses SMC32 calling convention which +means using the first 32-bit data of the Xn registers. + +At this stage we only need the FF-A v1.0 features. + +The FF-A support has been tested with OP-TEE which supports SMC32 calling +convention. + +Hypervisors are supported if they are configured to trap SMC calls. + +The FF-A support uses 64-bit registers as per `SMC Calling Convention v1.2 specification`_. + +Supported hardware +-------------------------------- + +Aarch64 plaforms + +Configuration +---------------------- + +CONFIG_ARM_FFA_TRANSPORT + Enables the FF-A support. Turn this on if you want to use FF-A + communication. + When using an Arm 64-bit platform, the Arm FF-A driver will be used. + When using sandbox, the sandbox FF-A emulator and FF-A sandbox driver will be used. + +FF-A ABIs under the hood +--------------------------------------- + +Invoking an FF-A ABI involves providing to the secure world/hypervisor the +expected arguments from the ABI. + +On an Arm 64-bit platform, the ABI arguments are stored in x0 to x7 registers. +Then, an SMC instruction is executed. + +At the secure side level or hypervisor the ABI is handled at a higher exception +level and the arguments are read and processed. + +The response is put back through x0 to x7 registers and control is given back +to the U-Boot Arm FF-A driver (non-secure world). + +The driver reads the response and processes it accordingly. + +This methodology applies to all the FF-A ABIs. + +FF-A bus discovery on Arm 64-bit platforms +--------------------------------------------- + +When CONFIG_ARM_FFA_TRANSPORT is enabled, the FF-A bus is considered as +an architecture feature and discovered using ARM_SMCCC_FEATURES mechanism. +This discovery mechanism is performed by the PSCI driver. + +The PSCI driver comes with a PSCI device tree node which is the root node for all +architecture features including FF-A bus. + +:: + + => dm tree + + Class Index Probed Driver Name + ----------------------------------------------------------- + firmware 0 [ + ] psci |-- psci + ffa 0 [ ] arm_ffa | `-- arm_ffa + +The PSCI driver is bound to the PSCI device and when probed it tries to discover +the architecture features by calling a callback the features drivers provide. + +In case of FF-A, the callback is arm_ffa_is_supported() which tries to discover the +FF-A framework by querying the FF-A framework version from secure world using +FFA_VERSION ABI. When discovery is successful, the ARM_SMCCC_FEATURES +mechanism creates a U-Boot device for the FF-A bus and binds the Arm FF-A driver +with the device using device_bind_driver(). + +At this stage the FF-A bus is registered with the DM and can be interacted with using +the DM APIs. + +Clients are able to probe then use the FF-A bus by calling uclass_first_device(). +Please refer to the armffa command implementation as an example of how to probe +and interact with the FF-A bus. + +When calling uclass_first_device(), the FF-A driver is probed and ends up calling +ffa_do_probe() provided by the Uclass which does the following: + + - saving the FF-A framework version in uc_priv + - querying from secure world the u-boot endpoint ID + - querying from secure world the supported features of FFA_RXTX_MAP + - mapping the RX/TX buffers + - querying from secure world all the partitions information + +When one of the above actions fails, probing fails and the driver stays not active +and can be probed again if needed. + +Requirements for clients +------------------------------------- + +When using the FF-A bus with EFI, clients must query the SPs they are looking for +during EFI boot-time mode using the service UUID. + +The RX/TX buffers are only available at EFI boot-time. Querying partitions is +done at boot time and data is cached for future use. + +RX/TX buffers should be unmapped before EFI runtime mode starts. +The driver provides a bus operation for that called ffa_rxtx_unmap(). + +The user should call ffa_rxtx_unmap() to unmap the RX/TX buffers when required +(e.g: at efi_exit_boot_services()). + +The Linux kernel allocates its own RX/TX buffers. To be able to register these kernel buffers +with secure world, the U-Boot's RX/TX buffers should be unmapped before EFI runtime starts. + +When invoking FF-A direct messaging, clients should specify which ABI protocol +they want to use (32-bit vs 64-bit). Selecting the protocol means using +the 32-bit or 64-bit version of FFA_MSG_SEND_DIRECT_{REQ, RESP}. +The calling convention between U-Boot and the secure world stays the same: SMC32. + +Requirements for user drivers +------------------------------------- + +Users who want to implement their custom FF-A device driver while reusing the FF-A Uclass can do so +by implementing their own invoke_ffa_fn() in the user driver. + +The bus driver layer +------------------------------ + +FF-A support comes on top of the SMCCC layer and is implemented by the FF-A Uclass drivers/firmware/arm-ffa/arm-ffa-uclass.c + +The following features are provided: + +- Support for the 32-bit version of the following ABIs: + + - FFA_VERSION + - FFA_ID_GET + - FFA_FEATURES + - FFA_PARTITION_INFO_GET + - FFA_RXTX_UNMAP + - FFA_RX_RELEASE + - FFA_RUN + - FFA_ERROR + - FFA_SUCCESS + - FFA_INTERRUPT + - FFA_MSG_SEND_DIRECT_REQ + - FFA_MSG_SEND_DIRECT_RESP + +- Support for the 64-bit version of the following ABIs: + + - FFA_RXTX_MAP + - FFA_MSG_SEND_DIRECT_REQ + - FFA_MSG_SEND_DIRECT_RESP + +- Processing the received data from the secure world/hypervisor and caching it + +- Hiding from upper layers the FF-A protocol and registers details. Upper + layers focus on exchanged data, FF-A support takes care of how to transport + that to the secure world/hypervisor using FF-A + +- FF-A support provides driver operations to be used by upper layers: + + - ffa_partition_info_get + - ffa_sync_send_receive + - ffa_rxtx_unmap + +- FF-A bus discovery makes sure FF-A framework is responsive and compatible + with the driver + +- FF-A bus can be compiled and used without EFI + +Relationship between the sandbox emulator and the FF-A device +--------------------------------------------------------------- + +:: + + => dm tree + + Class Index Probed Driver Name + ----------------------------------------------------------- + ffa_emul 0 [ + ] sandbox_ffa_emul `-- arm-ffa-emul + ffa 0 [ ] sandbox_arm_ffa `-- sandbox-arm-ffa + +The armffa command +----------------------------------- + +armffa is a command showcasing how to use the FF-A bus and how to invoke the driver operations. + +Please refer the command documentation at :doc:`../usage/cmd/armffa` + +Example of boot logs with FF-A enabled +-------------------------------------- + +For example, when using FF-A with Corstone-1000, debug logs enabled, the output is as follows: + +:: + + U-Boot 2023.01 (May 10 2023 - 11:08:07 +0000) corstone1000 aarch64 + + DRAM: 2 GiB + Arm FF-A framework discovery + FF-A driver 1.0 + FF-A framework 1.0 + FF-A versions are compatible + ... + FF-A driver 1.0 + FF-A framework 1.0 + FF-A versions are compatible + EFI: MM partition ID 0x8003 + ... + EFI stub: Booting Linux Kernel... + ... + Linux version 6.1.9-yocto-standard (oe-user@oe-host) (aarch64-poky-linux-musl-gcc (GCC) 12.2.0, GNU ld (GNU Binutils) 2.40.202301193 + Machine model: ARM Corstone1000 FPGA MPS3 board + +Contributors +------------ + * Abdellatif El Khlifi <abdellatif.elkhlifi@arm.com> + +.. _`FF-A v1.0 specification`: https://documentation-service.arm.com/static/5fb7e8a6ca04df4095c1d65e +.. _`SMC Calling Convention v1.2 specification`: https://documentation-service.arm.com/static/5f8edaeff86e16515cdbe4c6 diff --git a/doc/arch/index.rst b/doc/arch/index.rst index b8da4b8c8e..2f916f4026 100644 --- a/doc/arch/index.rst +++ b/doc/arch/index.rst @@ -8,6 +8,7 @@ Architecture-specific doc arc arm64 + arm64.ffa m68k mips nios2 diff --git a/doc/arch/sandbox/sandbox.rst b/doc/arch/sandbox/sandbox.rst index 77ca6bc4cc..a3631de749 100644 --- a/doc/arch/sandbox/sandbox.rst +++ b/doc/arch/sandbox/sandbox.rst @@ -200,6 +200,7 @@ Supported Drivers U-Boot sandbox supports these emulations: +- Arm FF-A - Block devices - Chrome OS EC - GPIO diff --git a/doc/board/asus/grouper_common.rst b/doc/board/asus/grouper_common.rst new file mode 100644 index 0000000000..2e4450b40e --- /dev/null +++ b/doc/board/asus/grouper_common.rst @@ -0,0 +1,94 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the ASUS/Google Nexus 7 (2012) +========================================= + +``DISCLAMER!`` Moving your ASUS/Google Nexus 7 (2012) to use +U-Boot assumes replacement of the vendor ASUS bootloader. Vendor +android firmwares will no longer be able to run on the device. +This replacement IS reversible. + +Quick Start +----------- + +- Build U-Boot +- Pack U-Boot into repart-block +- Flash repart-block into the eMMC +- Boot +- Self Upgrading + +Build U-Boot +------------ + +Device support is implemented by applying config fragment to a generic +board defconfig. Valid fragments are ``grouper_E1565.config``, +``grouper_PM269.config`` and ``tilapia.config``. + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-linux-gnueabi- + $ make grouper_common_defconfig grouper_E1565.config # For maxim based grouper + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +image, ready for flashing (but check the next section for additional +adjustments). + +Pack U-Boot into repar-block +---------------------------- + +``DISCLAMER!`` All questions related to re-crypt work should be asked +in re-crypt repo issues. NOT HERE! + +re-crypt is a small script which packs ``u-boot-dtb-tegra.bin`` in +form usable by device. This process is required only on the first +installation or to recover the device in case of a failed update. +You need to know your tablet's individual SBK to continue. + +.. code-block:: bash + + $ git clone https://github.com/clamor-s/re-crypt.git + $ cd re-crypt # place your u-boot-dtb-regra.bin here + $ ./re-crypt.sh -d grouper -k deadbeefdeadc0dedeadd00dfee1dead + +Script will produce you a ``repart-block.bin`` ready to flash. + +Flash repart-block into the eMMC +-------------------------------- + +``DISCLAMER!`` All questions related to NvFlash should be asked +in the proper place. NOT HERE! Flashing repart-block will erase +all your eMMC, so make a backup before! + +``repart-block.bin`` contains BCT and bootloader in encrypted state +in form which can just be written RAW at the start of eMMC. + +.. code-block:: bash + + $ wheelie --blob blob.bin + $ nvflash --resume --rawdevicewrite 0 1024 repart-block.bin + +Boot +---- + +After flashing ``repart-block.bin`` the device should reboot and turn +itself off. This is normal behavior if no boot configuration is +found. + +To boot Linux, U-Boot will look for an ``extlinux.conf`` configuration +on eMMC. Additionally if Volume Down button is pressed while booting +device will enter bootmenu. Bootmenu contains entries to mount eMMC as +mass storage, fastboot, reboot, reboot RCM, poweroff, enter U-Boot +console and update bootloader (check next chapter). + +Flashing ``repart-block.bin`` eliminates vendor restriction on eMMC +and allows the user to use/partition it in any way the user desires. + +Self Upgrading +-------------- + +Place your ``u-boot-dtb-tegra.bin`` on the first partition of the +eMMC (using ability of u-boot to mount it). Enter bootmenu, choose +update bootloader option with Power button and U-Boot should update +itself. Once the process is completed, U-Boot will ask to press any +button to reboot. diff --git a/doc/board/asus/index.rst b/doc/board/asus/index.rst new file mode 100644 index 0000000000..87e535fe34 --- /dev/null +++ b/doc/board/asus/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +ASUS +==== + +.. toctree:: + :maxdepth: 2 + + grouper_common + transformer_t30 diff --git a/doc/board/asus/transformer_t30.rst b/doc/board/asus/transformer_t30.rst new file mode 100644 index 0000000000..b6b6101540 --- /dev/null +++ b/doc/board/asus/transformer_t30.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the ASUS Transformer device family +============================================= + +``DISCLAMER!`` Moving your ASUS Transformer to use U-Boot +assumes replacement of the vendor ASUS bootloader. Vendor +android firmwares will no longer be able to run on the device. +This replacement IS reversible. + +Quick Start +----------- + +- Build U-Boot +- Pack U-Boot into repart-block +- Flash repart-block into the eMMC +- Flash repart-block into TF600T SPI flash +- Boot +- Self Upgrading + +Build U-Boot +------------ + +Device support is implemented by applying config fragment +to a generic board defconfig. Valid fragments are ``tf201.config``, +``tf300t.config``, ``tf300tg.config``, ``tf300tl.config``, +``tf700t.config``, ``tf600t.config`` and ``p1801-t.config``. + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-linux-gnueabi- + $ make transformer_t30_defconfig tf201.config # For TF201 + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +image, ready for flashing (but check the next section for additional +adjustments). + +Pack U-Boot into repar-block +---------------------------- + +``DISCLAMER!`` All questions related to re-crypt work should be asked +in re-crypt repo issues. NOT HERE! + +re-crypt is a small script which packs ``u-boot-dtb-tegra.bin`` in +form usable by device. This process is required only on the first +installation or to recover the device in case of a failed update. +You need to know your tablet's individual SBK to continue. + +.. code-block:: bash + + $ git clone https://github.com/clamor-s/re-crypt.git + $ cd re-crypt # place your u-boot-dtb-regra.bin here + $ ./re-crypt.sh -d tf201 -k deadbeefdeadc0dedeadd00dfee1dead + +Script will produce you a `repart-block.bin` ready to flash. + +Flash repart-block into the eMMC +-------------------------------- + +``DISCLAMER!`` All questions related to NvFlash should be asked +in the proper place. NOT HERE! Flashing repart-block will erase +all your eMMC, so make a backup before! + +``repart-block.bin`` contains BCT and bootloader in encrypted state +in form which can just be written RAW at the start of eMMC. + +.. code-block:: bash + + $ wheelie --blob blob.bin + $ nvflash --resume --rawdevicewrite 0 1024 repart-block.bin + +Flash repart-block into TF600T SPI flash +---------------------------------------- + +Unlike other transformers TF600T uses separate 4 MB SPI flash which +contains all data required for boot. It is flashed from within u-boot +itself preloaded into RAM using fusee gelee. After creating your +``repart-block.bin`` you have to place it on a 1st partition of microSD +card formated in fat. Then insert this microSD card into your tablet +and boot it using fusee gelee and u-boot which was included into +repart-block.bin, while booting you must hold volume down button. +Process should take less then a minute, if everything goes correct, +on microSD will appear ``spi-flash-backup.bin`` file, which is dump of +your spi flash content and can be used to restore UEFI, do not loose it, +tablet will power itself off. + +Self-updating of u-boot is performed by placing ``u-boot-dtb-tegra.bin`` +on 1st partition of microSD, inserting it into tablet and booting with +pressed volume down button. + +Boot +---- + +After flashing ``repart-block.bin`` the device should reboot and turn +itself off. This is normal behavior if no boot configuration is +found. + +To boot Linux, U-Boot will look for an ``extlinux.conf`` on MicroSD +and then on eMMC. Additionally if Volume Down button is pressed +while booting device will enter bootmenu. Bootmenu contains entries +to mount MicroSD and eMMC as mass storage, fastboot, reboot, reboot +RCM, poweroff, enter U-Boot console and update bootloader (check next +chapter). + +Flashing ``repart-block.bin`` eliminates vendor restriction on eMMC +and allows the user to use/partition it in any way the user desires. + +Self Upgrading +-------------- + +Place your ``u-boot-dtb-tegra.bin`` on the first partition of the +MicroSD card and insert it into the tablet. Enter bootmenu, choose +update bootloader option with Power button and U-Boot should update +itself. Once the process is completed, U-Boot will ask to press any +button to reboot. diff --git a/doc/board/coreboot/coreboot.rst b/doc/board/coreboot/coreboot.rst index 0fe95af56d..d660a223d9 100644 --- a/doc/board/coreboot/coreboot.rst +++ b/doc/board/coreboot/coreboot.rst @@ -51,6 +51,40 @@ can be useful for running UEFI applications, for example. This has only been lightly tested. +CBFS access +----------- + +You can use the 'cbfs' commands to access the Coreboot filesystem:: + + => cbfsinit + => cbfsinfo + + CBFS version: 0x31313132 + ROM size: 0x100000 + Boot block size: 0x4 + CBFS size: 0xffdfc + Alignment: 64 + Offset: 0x200 + + => cbfsls + size type name + ------------------------------------------ + 32 cbfs header cbfs master header + 16720 17 fallback/romstage + 53052 17 fallback/ramstage + 398 raw config + 715 raw revision + 117 raw build_info + 4044 raw fallback/dsdt.aml + 640 cmos layout cmos_layout.bin + 17804 17 fallback/postcar + 335797 payload fallback/payload + 607000 null (empty) + 10752 bootblock bootblock + + 12 file(s) + + => Memory map ---------- @@ -100,3 +134,23 @@ input clock is 1843200. So you can add the following CONFIG options:: CONFIG_DEBUG_UART_CLOCK=1843200 CONFIG_DEBUG_UART_SHIFT=2 CONFIG_DEBUG_UART_ANNOUNCE=y + +coreboot in CI +-------------- + +CI runs tests using a pre-built coreboot image. This ensures that U-Boot can +boot as a coreboot payload, based on a known-good build of coreboot. + +To update the `coreboot.rom` file which is used: + +#. Build coreboot with `CONFIG_LINEAR_FRAMEBUFFER=y`. If using `make menuconfig` + this is under + `Devices ->Display->Framebuffer mode->Linear "high resolution" framebuffer`. + +#. Compress the resulting `coreboot.rom`:: + + xz -c /path/to/coreboot/build/coreboot.rom >coreboot.rom.xz + +#. Upload the file to Google drive + +#. Send a patch to change the file ID used by wget in the CI yaml files. diff --git a/doc/board/emulation/qemu-x86.rst b/doc/board/emulation/qemu-x86.rst index e7dd4e994d..15f56b6bc7 100644 --- a/doc/board/emulation/qemu-x86.rst +++ b/doc/board/emulation/qemu-x86.rst @@ -113,7 +113,87 @@ sure the specified CPU supports 64-bit like '-cpu core2duo'. Conversely '-cpu pentium' won't work for obvious reasons that the processor only supports 32-bit. -Note 64-bit support is very preliminary at this point. Lots of features -are missing in the 64-bit world. One notable feature is the VGA console -support which is currently missing, so that you must specify '-nographic' -to get 64-bit U-Boot up and running. +Booting distros +--------------- + +It is possible to install and boot a standard Linux distribution using +qemu-x86_64 by setting up a root disk:: + + qemu-img create root.img 10G + +then using the installer to install. For example, with Ubuntu 2023.04:: + + qemu-system-x86_64 -m 8G -smp 4 -bios /tmp/b/qemu-x86_64/u-boot.rom \ + -drive file=root.img,if=virtio,driver=raw \ + -drive file=ubuntu-23.04-desktop-amd64.iso,if=virtio,driver=raw + +You can also add `-serial mon:stdio` if you want the serial console to show as +well as the video. + +The output will be something like this:: + + U-Boot SPL 2023.07 (Jul 23 2023 - 08:00:12 -0600) + Trying to boot from SPI + Jumping to 64-bit U-Boot: Note many features are missing + + + U-Boot 2023.07 (Jul 23 2023 - 08:00:12 -0600) + + CPU: QEMU Virtual CPU version 2.5+ + DRAM: 8 GiB + Core: 20 devices, 13 uclasses, devicetree: separate + Loading Environment from nowhere... OK + Model: QEMU x86 (I440FX) + Net: e1000: 52:54:00:12:34:56 + eth0: e1000#0 + Hit any key to stop autoboot: 0 + Scanning for bootflows in all bootdevs + Seq Method State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + Scanning global bootmeth 'efi_mgr': + Hunting with: nvme + Hunting with: qfw + Hunting with: scsi + scanning bus for devices... + Hunting with: virtio + Scanning bootdev 'qfw_pio.bootdev': + fatal: no kernel available + Scanning bootdev 'virtio-blk#0.bootdev': + Scanning bootdev 'virtio-blk#1.bootdev': + 0 efi ready virtio 2 virtio-blk#1.bootdev.part efi/boot/bootx64.efi + ** Booting bootflow 'virtio-blk#1.bootdev.part_2' with efi + EFI using ACPI tables at f0060 + efi_install_fdt() WARNING: Can't have ACPI table and device tree - ignoring DT. + efi_run_image() Booting /efi\boot\bootx64.efi + error: file `/boot/' not found. + +Standard boot looks through various available devices and finds the virtio +disks, then boots from the first one. After a second or so the grub menu appears +and you can work through the installer flow normally. + +Note that standard boot will not find 32-bit distros, since it looks for a +different filename. + +Current limitations +------------------- + +Only qemu-x86-64 can be used for booting distros, since qemu-x86 (the 32-bit +version of U-Boot) seems to have an EFI bug leading to the boot handing after +Linux is selected from grub, e.g. with `debian-12.1.0-i386-netinst.iso`:: + + ** Booting bootflow 'virtio-blk#1.bootdev.part_2' with efi + EFI using ACPI tables at f0180 + efi_install_fdt() WARNING: Can't have ACPI table and device tree - ignoring DT. + efi_run_image() Booting /efi\boot\bootia32.efi + Failed to open efi\boot\root=/dev/sdb3 - Not Found + Failed to load image 큀緃: Not Found + start_image() returned Not Found, falling back to default loader + Welcome to GRUB! + +The bochs video driver also seems to cause problems before the OS is able to +show a display. + +Finally, the use of `-M accel=kvm` is intended to use the native CPU's +virtual-machine features to accelerate operation, but this causes U-Boot to hang +when jumping 64-bit mode, at least on AMD machines. This may be a bug in U-Boot +or something else. diff --git a/doc/board/htc/endeavoru.rst b/doc/board/htc/endeavoru.rst new file mode 100644 index 0000000000..950c713f2f --- /dev/null +++ b/doc/board/htc/endeavoru.rst @@ -0,0 +1,89 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the HTC One X (endeavoru) +==================================== + +``DISCLAMER!`` Moving your HTC ONe X to use U-Boot assumes +replacement of the vendor hboot. Vendor android firmwares +will no longer be able to run on the device. +This replacement IS reversible. + +Quick Start +----------- + +- Build U-Boot +- Pack U-Boot into repart-block +- Flash repart-block into the eMMC +- Boot +- Self Upgrading + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-linux-gnueabi- + $ make endeavoru_defconfig + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +image, ready for flashing (but check the next section for additional +adjustments). + +Pack U-Boot into repar-block +---------------------------- + +``DISCLAMER!`` All questions related to re-crypt work should be +asked in re-crypt repo issues. NOT HERE! + +re-crypt is a small script which packs ``u-boot-dtb-tegra.bin`` in +form usable by device. This process is required only on the first +installation or to recover the device in case of a failed update. + +.. code-block:: bash + + $ git clone https://github.com/clamor-s/re-crypt.git + $ cd re-crypt # place your u-boot-dtb-regra.bin here + $ ./re-crypt.sh -d endeavoru + +Script will produce you a ``repart-block.bin`` ready to flash. + +Flash repart-block into the eMMC +-------------------------------- + +``DISCLAMER!`` All questions related to NvFlash should be asked +in the proper place. NOT HERE! Flashing repart-block will erase +all your eMMC, so make a backup before! + +``repart-block.bin`` contains BCT and bootloader in encrypted state +in form which can just be written RAW at the start of eMMC. + +.. code-block:: bash + + $ wheelie --blob blob.bin + $ nvflash --resume --rawdevicewrite 0 1024 repart-block.bin + +Boot +---- + +After flashing ``repart-block.bin`` the device should reboot and turn +itself off. This is normal behavior if no boot configuration is +found. + +To boot Linux, U-Boot will look for an ``extlinux.conf`` configuration +on eMMC. Additionally if Volume Down button is pressed while booting +device will enter bootmenu. Bootmenu contains entries to mount eMMC as +mass storage, fastboot, reboot, reboot RCM, poweroff, enter U-Boot +console and update bootloader (check next chapter). + +Flashing ``repart-block.bin`` eliminates vendor restriction on eMMC +and allows the user to use/partition it in any way the user desires. + +Self Upgrading +-------------- + +Place your ``u-boot-dtb-tegra.bin`` on the first partition of the +eMMC (using ability of u-boot to mount it). Enter bootmenu, choose +update bootloader option with Power button and U-Boot should update +itself. Once the process is completed, U-Boot will ask to press any +button to reboot. diff --git a/doc/board/htc/index.rst b/doc/board/htc/index.rst new file mode 100644 index 0000000000..955c9b9e03 --- /dev/null +++ b/doc/board/htc/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +HTC +=== + +.. toctree:: + :maxdepth: 2 + + endeavoru diff --git a/doc/board/index.rst b/doc/board/index.rst index 84aa8c158a..0194f0aaa3 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -14,6 +14,7 @@ Board-specific doc anbernic/index apple/index armltd/index + asus/index atmel/index beacon/index broadcom/index @@ -25,8 +26,10 @@ Board-specific doc gateworks/index google/index highbank/index + htc/index intel/index kontron/index + lg/index mediatek/index microchip/index nokia/index diff --git a/doc/board/lg/index.rst b/doc/board/lg/index.rst new file mode 100644 index 0000000000..3af3681e0b --- /dev/null +++ b/doc/board/lg/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +LG +== + +.. toctree:: + :maxdepth: 2 + + x3_t30 diff --git a/doc/board/lg/x3_t30.rst b/doc/board/lg/x3_t30.rst new file mode 100644 index 0000000000..5c564aabc6 --- /dev/null +++ b/doc/board/lg/x3_t30.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the LG X3 T30 device family +====================================== + +``DISCLAMER!`` Moving your LG P880 or P895 to use U-Boot +assumes replacement of the vendor LG bootloader. Vendor +android firmwares will no longer be able to run on the +device. This replacement IS reversible. + +Quick Start +----------- + +- Build U-Boot +- Pack U-Boot into repart-block +- Flash repart-block into the eMMC +- Boot +- Self Upgrading + +Build U-Boot +------------ + +Device support is implemented by applying config fragment to a generic +board defconfig. Valid fragments are ``p880.config`` and ``p895.config``. + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-linux-gnueabi- + $ make x3_t30_defconfig p895.config # For LG Optimus Vu + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +image, ready for flashing (but check the next section for additional +adjustments). + +Pack U-Boot into repar-block +---------------------------- + +``DISCLAMER!`` All questions related to re-crypt work should be +asked in re-crypt repo issues. NOT HERE! + +re-crypt is a small script which packs ``u-boot-dtb-tegra.bin`` in +form usable by device. This process is required only on the first +installation or to recover the device in case of a failed update. + +.. code-block:: bash + + $ git clone https://github.com/clamor-s/re-crypt.git + $ cd re-crypt # place your u-boot-dtb-regra.bin here + $ ./re-crypt.sh -d p895 + +Script will produce you a ``repart-block.bin`` ready to flash. + +Flash repart-block into the eMMC +-------------------------------- + +``DISCLAMER!`` All questions related to NvFlash should be asked +in the proper place. NOT HERE! Flashing repart-block will erase +all your eMMC, so make a backup before! + +``repart-block.bin`` contains BCT and bootloader in encrypted state +in form which can just be written RAW at the start of eMMC. + +.. code-block:: bash + + $ wheelie --blob blob.bin + $ nvflash --resume --rawdevicewrite 0 1024 repart-block.bin + +Boot +---- + +After flashing ``repart-block.bin`` the device should reboot and turn +itself off. This is normal behavior if no boot configuration is +found. + +To boot Linux, U-Boot will look for an ``extlinux.conf`` on MicroSD +and then on eMMC. Additionally if Volume Down button is pressed +while booting device will enter bootmenu. Bootmenu contains entries +to mount MicroSD and eMMC as mass storage, fastboot, reboot, reboot +RCM, poweroff, enter U-Boot console and update bootloader (check next +chapter). + +Flashing ``repart-block.bin`` eliminates vendor restriction on eMMC +and allows the user to use/partition it in any way the user desires. + +Self Upgrading +-------------- + +Place your ``u-boot-dtb-tegra.bin`` on the first partition of the +eMMC (using ability of u-boot to mount it). Enter bootmenu, choose +update bootloader option with Power button and U-Boot should update +itself. Once the process is completed, U-Boot will ask to press any +button to reboot. diff --git a/doc/board/nxp/imx8mp_evk.rst b/doc/board/nxp/imx8mp_evk.rst index e7cc7b396b..72175dbe78 100644 --- a/doc/board/nxp/imx8mp_evk.rst +++ b/doc/board/nxp/imx8mp_evk.rst @@ -37,21 +37,22 @@ Build U-Boot .. code-block:: bash +Note: builddir is U-Boot build directory (source directory for in-tree builds). + $ export CROSS_COMPILE=aarch64-poky-linux- $ make O=build imx8mp_evk_defconfig - $ cp ../imx-atf/build/imx8mp/release/bl31.bin ./build/bl31.bin - $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_dmem_202006.bin ./build/ - $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_imem_202006.bin ./build/ - $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_dmem_202006.bin ./build/ - $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_imem_202006.bin ./build/ - $ export ATF_LOAD_ADDR=0x970000 - $ make O=build + $ cp ../imx-atf/build/imx8mp/release/bl31.bin $(builddir) + $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_dmem_202006.bin $(builddir) + $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_imem_202006.bin $(builddir) + $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_dmem_202006.bin $(builddir) + $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_imem_202006.bin $(builddir) + $ make Burn the flash.bin to the MicroSD card at offset 32KB: .. code-block:: bash - $sudo dd if=build/flash.bin of=/dev/sd[x] bs=1K seek=32 conv=notrunc; sync + $ sudo dd if=flash.bin of=/dev/sd[x] bs=1K seek=32 conv=notrunc; sync Boot ---- diff --git a/doc/board/rockchip/rockchip.rst b/doc/board/rockchip/rockchip.rst index 49a0c5797a..de9fe8e642 100644 --- a/doc/board/rockchip/rockchip.rst +++ b/doc/board/rockchip/rockchip.rst @@ -91,17 +91,22 @@ List of mainline supported Rockchip boards: - Theobroma Systems RK3399-Q7 SoM - Puma (puma_rk3399) * rk3566 - - Anbernic RGxx3 (rgxx3-rk3566) + - Anbernic RGxx3 (anbernic-rgxx3-rk3566) + - Pine64 Quartz64-A Board (quartz64-a-rk3566) + - Pine64 Quartz64-B Board (quartz64-b-rk3566) + - Pine64 SOQuartz on Blade (soquartz-blade-rk3566) + - Pine64 SOQuartz on CM4-IO (soquartz-cm4-rk3566) + - Pine64 SOQuartz on Model A (soquartz-model-a-rk3566) + - Radxa CM3 IO Board (radxa-cm3-io-rk3566) * rk3568 - Rockchip Evb-RK3568 (evb-rk3568) + - EmbedFire LubanCat 2 (lubancat-2-rk3568) + - FriendlyElec NanoPi R5C (nanopi-r5c-rk3568) + - FriendlyElec NanoPi R5S (nanopi-r5s-rk3568) - Hardkernel ODROID-M1 (odroid-m1-rk3568) - - Pine64 Quartz64-A Board (quartz64-a-rk3566_defconfig) - - Pine64 Quartz64-B Board (quartz64-b-rk3566_defconfig) - - Pine64 SOQuartz on Blade (soquartz-blade-rk3566_defconfig) - - Pine64 SOQuartz on CM4-IO (soquartz-cm4-rk3566_defconfig) - - Pine64 SOQuartz on Model A (soquartz-model-a-rk3566_defconfig) - - Radxa E25 Carrier Board (radxa-e25-rk3568_defconfig) + - Radxa E25 Carrier Board (radxa-e25-rk3568) + - Radxa ROCK 3 Model A (rock-3a-rk3568) * rk3588 - Rockchip EVB (evb-rk3588) diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst index ee4faec37c..3332d51b36 100644 --- a/doc/board/ti/am335x_evm.rst +++ b/doc/board/ti/am335x_evm.rst @@ -201,3 +201,65 @@ booting and mtdparts have been configured correctly for the board: U-Boot # spl export fdt ${loadaddr} - ${fdtaddr} U-Boot # nand erase.part u-boot-spl-os U-Boot # nand write ${fdtaddr} u-boot-spl-os + +USB device +---------- + +The platform code for am33xx based designs is legacy in the sense that +it is not fully compliant with the driver model in its management of the +various resources. This is particularly true for the USB Ethernet gadget +which will automatically be bound to the first USB Device Controller +(UDC). This make the USB Ethernet gadget work out of the box on common +boards like the Beagle Bone Blacks and by default will prevents other +gadgets to be used. + +The output of the 'dm tree' command shows which driver is bound to which +device, so the user can easily configure their platform differently from +the command line: + +.. code-block:: text + + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + [...] + misc 0 [ + ] ti-musb-wrapper | |-- usb@47400000 + usb 0 [ + ] ti-musb-peripheral | | |-- usb@47401000 + ethernet 1 [ + ] usb_ether | | | `-- usb_ether + bootdev 3 [ ] eth_bootdev | | | `-- usb_ether.bootdev + usb 0 [ ] ti-musb-host | | `-- usb@47401800 + +Typically here any network command performed using the usb_ether +interface would work, while using other gadgets would fail: + +.. code-block:: text + + => fastboot usb 0 + All UDC in use (1 available), use the unbind command + g_dnl_register: failed!, error: -19 + exit not allowed from main input shell. + +As hinted by the primary error message, the only controller available +(usb@47401000) is currently bound to the usb_ether driver, which makes +it impossible for the fastboot command to bind with this device (at +least from a bootloader point of view). The solution here would be to +use the unbind command specifying the class and index parameters (as +shown above in the 'dm tree' output) to target the driver to unbind: + +.. code-block:: text + + => unbind ethernet 1 + +The output of the 'dm tree' command now shows the availability of the +first USB device controller, the fastboot gadget will now be able to +bind with it: + +.. code-block:: text + + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + [...] + misc 0 [ + ] ti-musb-wrapper | |-- usb@47400000 + usb 0 [ ] ti-musb-peripheral | | |-- usb@47401000 + usb 0 [ ] ti-musb-host | | `-- usb@47401800 diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst index 4646bc0f52..5ed17c0a3a 100644 --- a/doc/board/ti/am62x_sk.rst +++ b/doc/board/ti/am62x_sk.rst @@ -246,3 +246,27 @@ https://www.ti.com/lit/pdf/spruiv7 under the `Boot Mode Pins` section. - 11001010 For SW2 and SW1, the switch state in the "ON" position = 1. + +Debugging U-Boot +---------------- + +See :ref:`Common Debugging environment - OpenOCD<k3_rst_refer_openocd>`: for +detailed setup information. + +.. warning:: + + **OpenOCD support since**: v0.12.0 + + If the default package version of OpenOCD in your development + environment's distribution needs to be updated, it might be necessary to + build OpenOCD from the source. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_XDS110 + :end-before: .. k3_rst_include_end_openocd_connect_XDS110 + +To start OpenOCD and connect to the board + +.. code-block:: bash + + openocd -f board/ti_am625evm.cfg diff --git a/doc/board/ti/am65x_evm.rst b/doc/board/ti/am65x_evm.rst index 0129235c2b..5f3c46cf9f 100644 --- a/doc/board/ti/am65x_evm.rst +++ b/doc/board/ti/am65x_evm.rst @@ -287,3 +287,27 @@ artifacts needed to the device: sb --ymodem tispl.bin > $MAIN_DEV < $MAIN_DEV sleep 1 sb --xmodem u-boot.img > $MAIN_DEV < $MAIN_DEV + +Debugging U-Boot +---------------- + +See :ref:`Common Debugging environment - OpenOCD<k3_rst_refer_openocd>`: for +detailed setup information. + +.. warning:: + + **OpenOCD support since**: v0.12.0 + + If the default package version of OpenOCD in your development + environment's distribution needs to be updated, it might be necessary to + build OpenOCD from the source. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_XDS110 + :end-before: .. k3_rst_include_end_openocd_connect_XDS110 + +To start OpenOCD and connect to the board + +.. code-block:: bash + + openocd -f board/ti_am654evm.cfg diff --git a/doc/board/ti/img/openocd-overview.svg b/doc/board/ti/img/openocd-overview.svg new file mode 100644 index 0000000000..afb6f7472a --- /dev/null +++ b/doc/board/ti/img/openocd-overview.svg @@ -0,0 +1,580 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!--SPDX-License-Identifier: GPL-2.0-or-later OR BSD-3-Clause--> + +<!--Copyright (C) 2023 Texas Instruments Incorporated - https://www.ti.com/--> + +<svg + xmlns:xhtml="http://www.w3.org/1999/xhtml" + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + version="1.1" + width="281px" + height="671px" + viewBox="-0.5 -0.5 281 671" + id="svg128" + sodipodi:docname="openocd-overview.svg" + inkscape:version="0.92.3 (2405546, 2018-03-11)"> + <metadata + id="metadata132"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="3440" + inkscape:window-height="1391" + id="namedview130" + showgrid="false" + inkscape:zoom="1.4068554" + inkscape:cx="283.8637" + inkscape:cy="385.05999" + inkscape:window-x="0" + inkscape:window-y="25" + inkscape:window-maximized="1" + inkscape:current-layer="svg128" /> + <defs + id="defs2" /> + <g + id="g118"> + <path + d="M 0 510 L 0 510 L 280 510 L 280 510" + fill="rgb(255, 255, 255)" + stroke="#ff0a1b" + stroke-miterlimit="10" + pointer-events="all" + id="path4" /> + <path + d="M 0 510 L 0 670 L 280 670 L 280 510" + fill="none" + stroke="#ff0a1b" + stroke-miterlimit="10" + pointer-events="none" + id="path6" /> + <rect + x="10" + y="590" + width="100" + height="70" + fill="#f8cecc" + stroke="#b85450" + pointer-events="none" + id="rect8" /> + <path + d="M 20 590 L 20 660 M 100 590 L 100 660" + fill="none" + stroke="#b85450" + stroke-miterlimit="10" + pointer-events="none" + id="path10" /> + <g + transform="translate(-0.5 -0.5)" + id="g16"> + <switch + id="switch14"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 625px; margin-left: 21px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Cortex-R</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="60" + y="629" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text12">Cortex-R</text> + </switch> + </g> + <rect + x="170" + y="590" + width="100" + height="70" + fill="#f8cecc" + stroke="#b85450" + pointer-events="none" + id="rect18" /> + <path + d="M 180 590 L 180 660 M 260 590 L 260 660" + fill="none" + stroke="#b85450" + stroke-miterlimit="10" + pointer-events="none" + id="path20" /> + <g + transform="translate(-0.5 -0.5)" + id="g26"> + <switch + id="switch24"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 625px; margin-left: 181px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Cortex-A</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="220" + y="629" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text22">Cortex-A</text> + </switch> + </g> + <g + transform="translate(-0.5 -0.5)" + id="g32"> + <switch + id="switch30"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 530px; margin-left: 221px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">K3 SoC</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="250" + y="534" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text28">K3 SoC</text> + </switch> + </g> + <path + d="M 140 550 L 140 570 L 60 570 L 60 583.63" + fill="none" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path34" /> + <path + d="M 60 588.88 L 56.5 581.88 L 60 583.63 L 63.5 581.88 Z" + fill="rgb(0, 0, 0)" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path36" /> + <path + d="M 140 550 L 140 570 L 220 570 L 220 583.63" + fill="none" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path38" /> + <path + d="M 220 588.88 L 216.5 581.88 L 220 583.63 L 223.5 581.88 Z" + fill="rgb(0, 0, 0)" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path40" /> + <rect + x="90" + y="520" + width="100" + height="30" + fill="#f8cecc" + stroke="#b85450" + pointer-events="none" + id="rect42" /> + <g + transform="translate(-0.5 -0.5)" + id="g48"> + <switch + id="switch46"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 535px; margin-left: 91px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Debug SS</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="140" + y="539" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text44">Debug SS</text> + </switch> + </g> + <path + d="M 140 470 L 140 503.63" + fill="none" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path50" /> + <path + d="M 140 508.88 L 136.5 501.88 L 140 503.63 L 143.5 501.88 Z" + fill="rgb(0, 0, 0)" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path52" /> + <rect + x="80" + y="410" + width="120" + height="60" + rx="9" + ry="9" + fill="#ffe6cc" + stroke="#d79b00" + pointer-events="none" + id="rect54" /> + <g + transform="translate(-0.5 -0.5)" + id="g60"> + <switch + id="switch58"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 440px; margin-left: 81px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Jtag Interface<xhtml:br /> +(XDS110, TUMPA..)</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="140" + y="444" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text56">Jtag Interface...</text> + </switch> + </g> + <path + d="M 140 370 L 140 403.63" + fill="none" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path62" /> + <path + d="M 140 408.88 L 136.5 401.88 L 140 403.63 L 143.5 401.88 Z" + fill="rgb(0, 0, 0)" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path64" /> + <rect + x="80" + y="310" + width="120" + height="60" + fill="#f5f5f5" + stroke="#666666" + pointer-events="none" + id="rect66" /> + <g + transform="translate(-0.5 -0.5)" + id="g72"> + <switch + id="switch70"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 340px; margin-left: 81px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: #333333; "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(51, 51, 51); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">PC</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="140" + y="344" + fill="#333333" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text68">PC</text> + </switch> + </g> + <g + transform="translate(-0.5 -0.5)" + id="g78"> + <switch + id="switch76"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 385px; margin-left: 141px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">USB</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="170" + y="389" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text74">USB</text> + </switch> + </g> + <g + transform="translate(-0.5 -0.5)" + id="g84"> + <switch + id="switch82"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 485px; margin-left: 141px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">JTAG</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="170" + y="489" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text80">JTAG</text> + </switch> + </g> + <path + d="M 100 230 L 180 230 L 200 270 L 180 310 L 100 310 L 80 270 Z" + fill="#e1d5e7" + stroke="#9673a6" + stroke-miterlimit="10" + pointer-events="none" + id="path86" /> + <g + transform="translate(-0.5 -0.5)" + id="g92"> + <switch + id="switch90"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 270px; margin-left: 81px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">OpenOCD</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="140" + y="274" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text88">OpenOCD</text> + </switch> + </g> + <path + d="M 140 200 L 140 220 L 140 210 L 140 223.63" + fill="none" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path94" /> + <path + d="M 140 228.88 L 136.5 221.88 L 140 223.63 L 143.5 221.88 Z" + fill="rgb(0, 0, 0)" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path96" /> + <path + d="M 100 120 L 180 120 L 200 160 L 180 200 L 100 200 L 80 160 Z" + fill="#e1d5e7" + stroke="#9673a6" + stroke-miterlimit="10" + pointer-events="none" + id="path98" /> + <g + transform="translate(-0.5 -0.5)" + id="g104"> + <switch + id="switch102"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 160px; margin-left: 81px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">GDB</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="140" + y="164" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text100">GDB</text> + </switch> + </g> + <path + d="M 140 80 L 140 113.63" + fill="none" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path106" /> + <path + d="M 140 118.88 L 136.5 111.88 L 140 113.63 L 143.5 111.88 Z" + fill="rgb(0, 0, 0)" + stroke="rgb(0, 0, 0)" + stroke-miterlimit="10" + pointer-events="none" + id="path108" /> + <path + d="M 80 0 L 200 0 L 200 68 Q 170 46.4 140 68 Q 110 89.6 80 68 L 80 12 Z" + fill="#e1d5e7" + stroke="#9673a6" + stroke-miterlimit="10" + pointer-events="none" + id="path110" /> + <g + transform="translate(-0.5 -0.5)" + id="g116"> + <switch + id="switch114"> + <foreignObject + style="overflow: visible; text-align: left;" + pointer-events="none" + width="100%" + height="100%" + requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <xhtml:div + style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 28px; margin-left: 81px;"> + <xhtml:div + style="box-sizing: border-box; font-size: 0px; text-align: center;" + data-drawio-colors="color: rgb(0, 0, 0); "> + <xhtml:div + style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">IDE debugging code</xhtml:div> + </xhtml:div> + </xhtml:div> + </foreignObject> + <text + x="140" + y="32" + fill="rgb(0, 0, 0)" + font-family="Helvetica" + font-size="12px" + text-anchor="middle" + id="text112">IDE debugging code</text> + </switch> + </g> + </g> +</svg> diff --git a/doc/board/ti/j7200_evm.rst b/doc/board/ti/j7200_evm.rst index 69abc55a93..2e60e22ba1 100644 --- a/doc/board/ti/j7200_evm.rst +++ b/doc/board/ti/j7200_evm.rst @@ -201,3 +201,27 @@ fat formatted UDA FS as file. In case of booting from eMMC, write above images into raw or UDA FS. and set mmc partconf accordingly. + +Debugging U-Boot +---------------- + +See :ref:`Common Debugging environment - OpenOCD<k3_rst_refer_openocd>`: for +detailed setup information. + +.. warning:: + + **OpenOCD support since**: v0.12.0 + + If the default package version of OpenOCD in your development + environment's distribution needs to be updated, it might be necessary to + build OpenOCD from the source. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_XDS110 + :end-before: .. k3_rst_include_end_openocd_connect_XDS110 + +To start OpenOCD and connect to the board + +.. code-block:: bash + + openocd -f board/ti_j7200evm.cfg diff --git a/doc/board/ti/j721e_evm.rst b/doc/board/ti/j721e_evm.rst index f4b4c192d9..d2a214fb33 100644 --- a/doc/board/ti/j721e_evm.rst +++ b/doc/board/ti/j721e_evm.rst @@ -228,3 +228,27 @@ J721E common processor board can be attached to a Ethernet QSGMII card and the PHY in the card has to be reset before it can be used for data transfer. "do_main_cpsw0_qsgmii_phyinit" env variable has to be set for the U-BOOT to configure this PHY. + +Debugging U-Boot +---------------- + +See :ref:`Common Debugging environment - OpenOCD<k3_rst_refer_openocd>`: for +detailed setup information. + +.. warning:: + + **OpenOCD support since**: v0.12.0 + + If the default package version of OpenOCD in your development + environment's distribution needs to be updated, it might be necessary to + build OpenOCD from the source. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_XDS110 + :end-before: .. k3_rst_include_end_openocd_connect_XDS110 + +To start OpenOCD and connect to the board + +.. code-block:: bash + + openocd -f board/ti_j721eevm.cfg diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index 02cfd93168..5f9bd4dfcb 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -469,3 +469,517 @@ filesystem and then imported => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile} => env import -t ${loadaddr} ${filesize} + +.. _k3_rst_refer_openocd: + +Common Debugging environment - OpenOCD +-------------------------------------- + +This section will show you how to connect a board to `OpenOCD +<https://openocd.org/>`_ and load the SPL symbols for debugging with +a K3 generation device. To follow this guide, you must build custom +u-boot binaries, start your board from a boot media such as an SD +card, and use an OpenOCD environment. This section uses generic +examples, though you can apply these instructions to any supported K3 +generation device. + +The overall structure of this setup is in the following figure. + +.. image:: img/openocd-overview.svg + +.. note:: + + If you find these instructions useful, please consider `donating + <https://openocd.org/pages/donations.html>`_ to OpenOCD. + +Step 1: Download and install OpenOCD +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To get started, it is more convenient if the distribution you +use supports OpenOCD by default. Follow the instructions in the +`getting OpenOCD <https://openocd.org/pages/getting-openocd.html>`_ +documentation to pick the installation steps appropriate to your +environment. Some references to OpenOCD documentation: + +* `OpenOCD User Guide <https://openocd.org/doc/html/index.html>`_ +* `OpenOCD Developer's Guide <https://openocd.org/doc/doxygen/html/index.html>`_ + +Refer to the release notes corresponding to the `OpenOCD version +<https://github.com/openocd-org/openocd/releases>`_ to ensure + +* Processor support: In general, processor support shouldn't present + any difficulties since OpenOCD provides solid support for both ARMv8 + and ARMv7. +* SoC support: When working with System-on-a-Chip (SoC), the support + usually comes as a TCL config file. It is vital to ensure the correct + version of OpenOCD or to use the TCL files from the latest release or + the one mentioned. +* Board or the JTAG adapter support: In most cases, board support is + a relatively easy problem if the board has a JTAG pin header. All + you need to do is ensure that the adapter you select is compatible + with OpenOCD. Some boards come with an onboard JTAG adapter that + requires a USB cable to be plugged into the board, in which case, it + is vital to ensure that the JTAG adapter is supported. Fortunately, + almost all TI K3 SK/EVMs come with TI's XDS110, which has out of the + box support by OpenOCD. The board-specific documentation will + cover the details and any adapter/dongle recommendations. + +.. code-block:: bash + + openocd -v + +.. note:: + + OpenOCD version 0.12.0 is usually required to connect to most K3 + devices. If your device is only supported by a newer version than the + one provided by your distribution, you may need to build it from the source. + +Building OpenOCD from source +"""""""""""""""""""""""""""" + +The dependency package installation instructions below are for Debian +systems, but equivalent instructions should exist for systems with +other package managers. Please refer to the `OpenOCD Documentation +<https://openocd.org/>`_ for more recent installation steps. + +.. code-block:: bash + + $ # Check the packages to be installed: needs deb-src in sources.list + $ sudo apt build-dep openocd + $ # The following list is NOT complete - please check the latest + $ sudo apt-get install libtool pkg-config texinfo libusb-dev \ + libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake + $ git clone https://github.com/openocd-org/openocd.git openocd + $ cd openocd + $ git submodule init + $ git submodule update + $ ./bootstrap + $ ./configure --prefix=/usr/local/ + $ make -j`nproc` + $ sudo make install + +.. note:: + + The example above uses the GitHub mirror site. See + `git repo information <https://openocd.org/doc/html/Developers.html#OpenOCD-Git-Repository>`_ + information to pick the official git repo. + If a specific version is desired, select the version using `git checkout tag`. + +Installing OpenOCD udev rules +""""""""""""""""""""""""""""" + +The step is not necessary if the distribution supports the OpenOCD, but +if building from a source, ensure that the udev rules are installed +correctly to ensure a sane system. + +.. code-block:: bash + + # Go to the OpenOCD source directory + $ cd openocd + # Copy the udev rules to the correct system location + $ sudo cp ./contrib/60-openocd.rules \ + ./src/JTAG/drivers/libjaylink/contrib/99-libjaylink.rules \ + /etc/udev/rules.d/ + # Get Udev to load the new rules up + $ sudo udevadm control --reload-rules + # Use the new rules on existing connected devices + $ sudo udevadm trigger + +Step 2: Setup GDB +^^^^^^^^^^^^^^^^^ + +Most systems come with gdb-multiarch package. + +.. code-block:: bash + + # Install gdb-multiarch package + $ sudo apt-get install gdb-multiarch + +Though using GDB natively is normal, developers with interest in using IDE +may find a few of these interesting: + +* `gdb-dashboard <https://github.com/cyrus-and/gdb-dashboard>`_ +* `gef <https://github.com/hugsy/gef>`_ +* `peda <https://github.com/longld/peda>`_ +* `pwndbg <https://github.com/pwndbg/pwndbg>`_ +* `voltron <https://github.com/snare/voltron>`_ +* `ddd <https://www.gnu.org/software/ddd/>`_ +* `vscode <https://www.justinmklam.com/posts/2017/10/vscode-debugger-setup/>`_ +* `vim conque-gdb <https://github.com/vim-scripts/Conque-GDB>`_ +* `emacs realgud <https://github.com/realgud/realgud/wiki/gdb-notes>`_ +* `Lauterbach IDE <https://www2.lauterbach.com/pdf/backend_gdb.pdf>`_ + +.. warning:: + LLDB support for OpenOCD is still a work in progress as of this writing. + Using GDB is probably the safest option at this point in time. + +Step 3: Connect board to PC +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +There are few patterns of boards in the ecosystem + +.. k3_rst_include_start_openocd_connect_XDS110 + +**Integrated JTAG adapter/dongle**: The board has a micro-USB connector labelled +XDS110 USB or JTAG. Connect a USB cable to the board to the mentioned port. + +.. note:: + + There are multiple USB ports on a typical board, So, ensure you have read + the user guide for the board and confirmed the silk screen label to ensure + connecting to the correct port. + +.. k3_rst_include_end_openocd_connect_XDS110 + +.. k3_rst_include_start_openocd_connect_cti20 + +**cTI20 connector**: The TI's `cTI20 +<https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_JTAG_connectors.html#cti-20-pin-header-information>`_ connector +is probably the most prevelant on TI platforms. Though many +TI boards have an onboard XDS110, cTI20 connector is usually +provided as an alternate scheme to connect alternatives such +as `Lauterbach <https://www.lauterbach.com/>`_ or `XDS560 +<https://www.ti.com/tool/TMDSEMU560V2STM-U>`_. + +To debug on these boards, the following combinations is suggested: + +* `TUMPA <https://www.diygadget.com/JTAG-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-JTAG-spi-i2c-serial>`_ + or `equivalent dongles supported by OpenOCD. <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_ +* Cable such as `Tag-connect ribbon cable <https://www.tag-connect.com/product/20-pin-cortex-ribbon-cable-4-length-with-50-mil-connectors>`_ +* Adapter to convert cTI20 to ARM20 such as those from + `Segger <https://www.segger.com/products/debug-probes/j-link/accessories/adapters/ti-cti-20-adapter/>`_ + or `Lauterbach LA-3780 <https://www.lauterbach.com/ad3780.html>`_ + Or optionally, if you have manufacturing capability then you could try + `BeagleBone JTAG Adapter <https://github.com/mmorawiec/BeagleBone-Black-JTAG-Adapters>`_ + +.. warning:: + XDS560 and Lauterbach are proprietary solutions and is not supported by + OpenOCD. + When purchasing an off the shelf adapter/dongle, you do want to be careful + about the signalling though. Please + `read for additional info <https://software-dl.ti.com/ccs/esd/xdsdebugprobes/emu_JTAG_connectors.html>`_. + +.. k3_rst_include_end_openocd_connect_cti20 + +.. k3_rst_include_start_openocd_connect_tag_connect + +**Tag-Connect**: `Tag-Connect <https://www.tag-connect.com/>`_ +pads on the boards which require special cable. Please check the documentation +to `identify <https://www.tag-connect.com/info/legs-or-no-legs>`_ if "legged" +or "no-leg" version of the cable is appropriate for the board. + +To debug on these boards, you will need: + +* `TUMPA <https://www.diygadget.com/JTAG-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-JTAG-spi-i2c-serial>`_ + or `equivalent dongles supported by OpenOCD <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_. +* Tag-Connect cable appropriate to the board such as + `TC2050-IDC-NL <https://www.tag-connect.com/product/TC2050-IDC-NL-10-pin-no-legs-cable-with-ribbon-connector>`_ +* In case of no-leg, version, a + `retaining clip <https://www.tag-connect.com/product/tc2050-clip-3pack-retaining-clip>`_ +* Tag-Connect to ARM20 + `adapter <https://www.tag-connect.com/product/tc2050-arm2010-arm-20-pin-to-tc2050-adapter>`_ + +.. note:: + You can optionally use a 3d printed solution such as + `Protective cap <https://www.thingiverse.com/thing:3025584>`_ or + `clip <https://www.thingiverse.com/thing:3035278>`_ to replace + the retaining clip. + +.. warning:: + With the Tag-Connect to ARM20 adapter, Please solder the "Trst" signal for + connection to work. + +.. k3_rst_include_end_openocd_connect_tag_connect + +Debugging with OpenOCD +^^^^^^^^^^^^^^^^^^^^^^ + +Debugging U-Boot is different from debugging regular user space +applications. The bootloader initialization process involves many boot +media and hardware configuration operations. For K3 devices, there +are also interactions with security firmware. While reloading the +"elf" file works through GDB, developers must be mindful of cascading +initialization's potential consequences. + +Consider the following code change: + +.. code-block:: diff + + --- a/file.c 2023-07-29 10:55:29.647928811 -0500 + +++ b/file.c 2023-07-29 10:55:46.091856816 -0500 + @@ -1,3 +1,3 @@ + val = readl(reg); + -val |= 0x2; + +val |= 0x1; + writel(val, reg); + +Re-running the elf file with the above change will result in the +register setting 0x3 instead of the intended 0x1. There are other +hardware blocks which may not behave very well with a re-initialization +without proper shutdown. + +To help narrow the debug down, it is usually simpler to use the +standard boot media to get to the bootloader and debug only in the area +of interest. + +In general, to debug u-boot spl/u-boot with OpenOCD there are three steps: + +* Modify the code adding a loop to allow the debugger to attach + near the point of interest. Boot up normally to stop at the loop. +* Connect with OpenOCD and step out of the loop. +* Step through the code to find the root of issue. + +Typical debugging involves a few iterations of the above sequence. +Though most bootloader developers like to use printf to debug, +debug with JTAG tends to be most efficient since it is possible to +investigate the code flow and inspect hardware registers without +repeated iterations. + +Code modification +""""""""""""""""" + +* **start.S**: Adding an infinite while loop at the very entry of + U-Boot. For this, look for the corresponding start.S entry file. + This is usually only required when debugging some core SoC or + processor related function. For example: arch/arm/cpu/armv8/start.S or + arch/arm/cpu/armv7/start.S + +.. code-block:: diff + + diff --git a/arch/arm/cpu/armv7/start.S b/arch/arm/cpu/armv7/start.S + index 69e281b086..744929e825 100644 + --- a/arch/arm/cpu/armv7/start.S + +++ b/arch/arm/cpu/armv7/start.S + @@ -37,6 +37,8 @@ + #endif + + reset: + +dead_loop: + + b dead_loop + /* Allow the board to save important registers */ + b save_boot_params + save_boot_params_ret: + +* **board_init_f**: Adding an infinite while loop at the board entry + function. In many cases, it is important to debug the boot process if + any changes are made for board-specific applications. Below is a step + by step process for debugging the boot SPL or Armv8 SPL: + + To debug the boot process in either domain, we will first + add a modification to the code we would like to debug. + In this example, we will debug ``board_init_f`` inside + ``arch/arm/mach-k3/{soc}_init.c``. Since some sections of U-Boot + will be executed multiple times during the bootup process of K3 + devices, we will need to include either ``CONFIG_CPU_ARM64`` or + ``CONFIG_CPU_V7R`` to catch the CPU at the desired place during the + bootup process (Main or Wakeup domains). For example, modify the + file as follows (depending on need): + +.. code-block:: c + + void board_init_f(ulong dummy) + { + . + . + /* Code to run on the R5F (Wakeup/Boot Domain) */ + if (IS_ENABLED(CONFIG_CPU_V7R)) { + volatile int x = 1; + while(x) {}; + } + ... + /* Code to run on the ARMV8 (Main Domain) */ + if (IS_ENABLED(CONFIG_CPU_ARM64)) { + volatile int x = 1; + while(x) {}; + } + . + . + } + +Connecting with OpenOCD for a debug session +""""""""""""""""""""""""""""""""""""""""""" + +Startup OpenOCD to debug the platform as follows: + +* **Integrated JTAG interface**: If the evm has a debugger such as + XDS110 inbuilt, there is typically an evm board support added and a + cfg file will be available. + +.. k3_rst_include_start_openocd_cfg_XDS110 + +.. code-block:: bash + + openocd -f board/{board_of_choice}.cfg + +.. k3_rst_include_end_openocd_cfg_XDS110 + +.. k3_rst_include_start_openocd_cfg_external_intro + +* **External JTAG adapter/interface**: In other cases, where an + adapter/dongle is used, a simple cfg file can be created to integrate the + SoC and adapter information. See `supported TI K3 SoCs + <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_ + to decide if the SoC is supported or not. + +.. code-block:: bash + + openocd -f openocd_connect.cfg + +.. k3_rst_include_end_openocd_cfg_external_intro + + For example, with BeaglePlay (AM62X platform), the openocd_connect.cfg: + +.. code-block:: tcl + + # TUMPA example: + # http://www.tiaowiki.com/w/TIAO_USB_Multi_Protocol_Adapter_User's_Manual + source [find interface/ftdi/tumpa.cfg] + + transport select jtag + + # default JTAG configuration has only SRST and no TRST + reset_config srst_only srst_push_pull + + # delay after SRST goes inactive + adapter srst delay 20 + + if { ![info exists SOC] } { + # Set the SoC of interest + set SOC am625 + } + + source [find target/ti_k3.cfg] + + ftdi tdo_sample_edge falling + + # Speeds for FT2232H are in multiples of 2, and 32MHz is tops + # max speed we seem to achieve is ~20MHz.. so we pick 16MHz + adapter speed 16000 + +Below is an example of the output of this command: + +.. code-block:: console + + Info : Listening on port 6666 for tcl connections + Info : Listening on port 4444 for telnet connections + Info : XDS110: connected + Info : XDS110: vid/pid = 0451/bef3 + Info : XDS110: firmware version = 3.0.0.20 + Info : XDS110: hardware version = 0x002f + Info : XDS110: connected to target via JTAG + Info : XDS110: TCK set to 2500 kHz + Info : clock speed 2500 kHz + Info : JTAG tap: am625.cpu tap/device found: 0x0bb7e02f (mfg: 0x017 (Texas Instruments), part: 0xbb7e, ver: 0x0) + Info : starting gdb server for am625.cpu.sysctrl on 3333 + Info : Listening on port 3333 for gdb connections + Info : starting gdb server for am625.cpu.a53.0 on 3334 + Info : Listening on port 3334 for gdb connections + Info : starting gdb server for am625.cpu.a53.1 on 3335 + Info : Listening on port 3335 for gdb connections + Info : starting gdb server for am625.cpu.a53.2 on 3336 + Info : Listening on port 3336 for gdb connections + Info : starting gdb server for am625.cpu.a53.3 on 3337 + Info : Listening on port 3337 for gdb connections + Info : starting gdb server for am625.cpu.main0_r5.0 on 3338 + Info : Listening on port 3338 for gdb connections + Info : starting gdb server for am625.cpu.gp_mcu on 3339 + Info : Listening on port 3339 for gdb connections + +.. note:: + Notice the default configuration is non-SMP configuration allowing + for each of the core to be attached and debugged simultaneously. + ARMv8 SPL/U-Boot starts up on cpu0 of a53/a72. + +.. k3_rst_include_start_openocd_cfg_external_gdb + +To debug using this server, use GDB directly or your preferred +GDB-based IDE. To start up GDB in the terminal, run the following +command. + +.. code-block:: bash + + gdb-multiarch + +To connect to your desired core, run the following command within GDB: + +.. code-block:: bash + + target extended-remote localhost:{port for desired core} + +To load symbols: + +.. warning:: + + SPL and U-Boot does a re-location of address compared to where it + is loaded originally. This step takes place after the DDR size is + determined from dt parsing. So, debugging can be split into either + "before re-location" or "after re-location". Please refer to the + file ''doc/README.arm-relocation'' to see how to grab the relocation + address. + +* Prior to relocation: + +.. code-block:: bash + + symbol-file {path to elf file} + +* After relocation: + +.. code-block:: bash + + # Drop old symbol file + symbol-file + # Pick up new relocaddr + add-symbol-file {path to elf file} {relocaddr} + +.. k3_rst_include_end_openocd_cfg_external_gdb + +In the above example of AM625, + +.. code-block:: bash + + target extended-remote localhost:3338 <- R5F (Wakeup Domain) + target extended-remote localhost:3334 <- A53 (Main Domain) + +The core can now be debugged directly within GDB using GDB commands or +if using IDE, as appropriate to the IDE. + +Stepping through the code +""""""""""""""""""""""""" + +`GDB TUI Commands +<https://sourceware.org/gdb/onlinedocs/gdb/TUI-Commands.html>`_ can +help set up the display more sensible for debug. Provide the name +of the layout that can be used to debug. For example, use the GDB +command ``layout src`` after loading the symbols to see the code and +breakpoints. To exit the debug loop added above, add any breakpoints +needed and run the following GDB commands to step out of the debug +loop set in the ``board_init_f`` function. + +.. code-block:: bash + + set x = 0 + continue + +The platform has now been successfully setup to debug with OpenOCD +using GDB commands or a GDB-based IDE. See `OpenOCD documentation for +GDB <https://openocd.org/doc/html/GDB-and-OpenOCD.html>`_ for further +information. + +.. warning:: + + On the K3 family of devices, a watchdog timer within the DMSC is + enabled by default by the ROM bootcode with a timeout of 3 minutes. + The watchdog timer is serviced by System Firmware (SYSFW) or TI + Foundational Security (TIFS) during normal operation. If debugging + the SPL before the SYSFW is loaded, the watchdog timer will not get + serviced automatically and the debug session will reset after 3 + minutes. It is recommended to start debugging SPL code only after + the startup of SYSFW to avoid running into the watchdog timer reset. + +Miscellaneous notes with OpenOCD +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Currently, OpenOCD does not support tracing for K3 platforms. Tracing +function could be beneficial if the bug in code occurs deep within +nested function and can optionally save developers major trouble of +stepping through a large quantity of code. diff --git a/doc/board/toradex/verdin-am62.rst b/doc/board/toradex/verdin-am62.rst index ac0e86b300..36db149cda 100644 --- a/doc/board/toradex/verdin-am62.rst +++ b/doc/board/toradex/verdin-am62.rst @@ -4,6 +4,9 @@ Verdin AM62 Module ================== +- SoM: https://www.toradex.com/computer-on-modules/verdin-arm-family/ti-am62 +- Carrier board: https://www.toradex.com/products/carrier-board/verdin-development-board-kit + Quick Start ----------- @@ -74,57 +77,57 @@ Boot Output: -.. code-block:: bash - -U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:14 +0200) -SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)') -SPL initial stack usage: 13368 bytes -Trying to boot from MMC1 -Authentication passed -Authentication passed -Authentication passed -Authentication passed -Authentication passed -Starting ATF on ARM64 core... - -NOTICE: BL31: v2.9(release):v2.9.0-73-g463655cc8 -NOTICE: BL31: Built : 14:51:42, Jun 5 2023 -I/TC: -I/TC: OP-TEE version: 3.21.0-168-g322cf9e33 (gcc version 12.2.1 20221205 (Arm GNU Toolchain 12.2.Rel1 (Build arm-12.24))) #2 Mon Jun 5 13:04:15 UTC 2023 aarch64 -I/TC: WARNING: This OP-TEE configuration might be insecure! -I/TC: WARNING: Please check https://optee.readthedocs.io/en/latest/architecture/porting_guidelines.html -I/TC: Primary CPU initializing -I/TC: SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)') -I/TC: HUK Initialized -I/TC: Primary CPU switching to normal world boot - -U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:41 +0200) -SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)') -SPL initial stack usage: 1840 bytes -Trying to boot from MMC1 -Authentication passed -Authentication passed - - -U-Boot 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:41 +0200) - -SoC: AM62X SR1.0 HS-FS -DRAM: 2 GiB -Core: 136 devices, 28 uclasses, devicetree: separate -MMC: mmc@fa10000: 0, mmc@fa00000: 1 -Loading Environment from MMC... OK -In: serial@2800000 -Out: serial@2800000 -Err: serial@2800000 -Model: Toradex 0076 Verdin AM62 Quad 2GB WB IT V1.0A -Serial#: 15037380 -Carrier: Toradex Verdin Development Board V1.1A, Serial# 10754333 -am65_cpsw_nuss ethernet@8000000: K3 CPSW: nuss_ver: 0x6BA01103 cpsw_ver: 0x6BA81103 ale_ver: 0x00290105 Ports:2 mdio_freq:1000000 -Setting variant to wifi -Net: -Warning: ethernet@8000000port@1 MAC addresses don't match: -Address in ROM is 1c:63:49:22:5f:f9 -Address in environment is 00:14:2d:e5:73:c4 -eth0: ethernet@8000000port@1 [PRIME], eth1: ethernet@8000000port@2 -Hit any key to stop autoboot: 0 -Verdin AM62 # +.. code-block:: none + + U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:14 +0200) + SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)') + SPL initial stack usage: 13368 bytes + Trying to boot from MMC1 + Authentication passed + Authentication passed + Authentication passed + Authentication passed + Authentication passed + Starting ATF on ARM64 core... + + NOTICE: BL31: v2.9(release):v2.9.0-73-g463655cc8 + NOTICE: BL31: Built : 14:51:42, Jun 5 2023 + I/TC: + I/TC: OP-TEE version: 3.21.0-168-g322cf9e33 (gcc version 12.2.1 20221205 (Arm GNU Toolchain 12.2.Rel1 (Build arm-12.24))) #2 Mon Jun 5 13:04:15 UTC 2023 aarch64 + I/TC: WARNING: This OP-TEE configuration might be insecure! + I/TC: WARNING: Please check https://optee.readthedocs.io/en/latest/architecture/porting_guidelines.html + I/TC: Primary CPU initializing + I/TC: SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)') + I/TC: HUK Initialized + I/TC: Primary CPU switching to normal world boot + + U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:41 +0200) + SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)') + SPL initial stack usage: 1840 bytes + Trying to boot from MMC1 + Authentication passed + Authentication passed + + + U-Boot 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:41 +0200) + + SoC: AM62X SR1.0 HS-FS + DRAM: 2 GiB + Core: 136 devices, 28 uclasses, devicetree: separate + MMC: mmc@fa10000: 0, mmc@fa00000: 1 + Loading Environment from MMC... OK + In: serial@2800000 + Out: serial@2800000 + Err: serial@2800000 + Model: Toradex 0076 Verdin AM62 Quad 2GB WB IT V1.0A + Serial#: 15037380 + Carrier: Toradex Verdin Development Board V1.1A, Serial# 10754333 + am65_cpsw_nuss ethernet@8000000: K3 CPSW: nuss_ver: 0x6BA01103 cpsw_ver: 0x6BA81103 ale_ver: 0x00290105 Ports:2 mdio_freq:1000000 + Setting variant to wifi + Net: + Warning: ethernet@8000000port@1 MAC addresses don't match: + Address in ROM is 1c:63:49:22:5f:f9 + Address in environment is 00:14:2d:e5:73:c4 + eth0: ethernet@8000000port@1 [PRIME], eth1: ethernet@8000000port@2 + Hit any key to stop autoboot: 0 + Verdin AM62 # diff --git a/doc/board/toradex/verdin-imx8mm.rst b/doc/board/toradex/verdin-imx8mm.rst index 439128adce..cc39030450 100644 --- a/doc/board/toradex/verdin-imx8mm.rst +++ b/doc/board/toradex/verdin-imx8mm.rst @@ -1,8 +1,12 @@ -.. SPDX-License-Identifier: GPL-2.0+ +.. SPDX-License-Identifier: GPL-2.0-or-later +.. sectionauthor:: Marcel Ziswiler <marcel.ziswiler@toradex.com> Verdin iMX8M Mini Module ======================== +- SoM: https://www.toradex.com/computer-on-modules/verdin-arm-family/nxp-imx-8m-mini-nano +- Carrier board: https://www.toradex.com/products/carrier-board/verdin-development-board-kit + Quick Start ----------- @@ -25,6 +29,7 @@ Then build ATF (TF-A): .. code-block:: bash + $ export CROSS_COMPILE=aarch64-linux-gnu- $ make PLAT=imx8mm IMX_BOOT_UART_BASE=0x30860000 bl31 $ cp build/imx8mm/release/bl31.bin ../ @@ -75,30 +80,30 @@ Boot sequence is: Output: -.. code-block:: bash - -U-Boot SPL 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200) -Normal Boot -WDT: Started with servicing (60s timeout) -Trying to boot from MMC1 -NOTICE: BL31: v2.2(release):rel_imx_5.4.70_2.3.2_rc1-5-g835a8f67b -NOTICE: BL31: Built : 18:02:12, Aug 16 2021 - - -U-Boot 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200) - -CPU: Freescale i.MX8MMQ rev1.0 at 1200 MHz -Reset cause: POR -DRAM: 2 GiB -WDT: Started with servicing (60s timeout) -MMC: FSL_SDHC: 0, FSL_SDHC: 1, FSL_SDHC: 2 -Loading Environment from MMC... OK -In: serial -Out: serial -Err: serial -Model: Toradex Verdin iMX8M Mini Quad 2GB Wi-Fi / BT IT V1.1A, Serial# 06760554 -Carrier: Toradex Verdin Development Board V1.1A, Serial# 10754333 -Setting variant to wifi -Net: eth0: ethernet@30be0000 -Hit any key to stop autoboot: 0 -Verdin iMX8MM # +.. code-block:: none + + U-Boot SPL 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200) + Normal Boot + WDT: Started with servicing (60s timeout) + Trying to boot from MMC1 + NOTICE: BL31: v2.2(release):rel_imx_5.4.70_2.3.2_rc1-5-g835a8f67b + NOTICE: BL31: Built : 18:02:12, Aug 16 2021 + + + U-Boot 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200) + + CPU: Freescale i.MX8MMQ rev1.0 at 1200 MHz + Reset cause: POR + DRAM: 2 GiB + WDT: Started with servicing (60s timeout) + MMC: FSL_SDHC: 0, FSL_SDHC: 1, FSL_SDHC: 2 + Loading Environment from MMC... OK + In: serial + Out: serial + Err: serial + Model: Toradex Verdin iMX8M Mini Quad 2GB Wi-Fi / BT IT V1.1A, Serial# 06760554 + Carrier: Toradex Verdin Development Board V1.1A, Serial# 10754333 + Setting variant to wifi + Net: eth0: ethernet@30be0000 + Hit any key to stop autoboot: 0 + Verdin iMX8MM # diff --git a/doc/board/toradex/verdin-imx8mp.rst b/doc/board/toradex/verdin-imx8mp.rst index 482f693577..bdc4d0c2cb 100644 --- a/doc/board/toradex/verdin-imx8mp.rst +++ b/doc/board/toradex/verdin-imx8mp.rst @@ -1,8 +1,12 @@ .. SPDX-License-Identifier: GPL-2.0-or-later +.. sectionauthor:: Marcel Ziswiler <marcel.ziswiler@toradex.com> Verdin iMX8M Plus Module ======================== +- SoM: https://www.toradex.com/computer-on-modules/verdin-arm-family/nxp-imx-8m-plus +- Carrier board: https://www.toradex.com/products/carrier-board/verdin-development-board-kit + Quick Start ----------- @@ -76,36 +80,36 @@ Boot sequence is: Output: -.. code-block:: bash - -U-Boot SPL 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100) -Quad die, dual rank failed, attempting dual die, single rank configuration. -Normal Boot -WDT: Started watchdog@30280000 with servicing (60s timeout) -Trying to boot from BOOTROM -Find img info 0x&48025a00, size 872 -Need continue download 1024 -Download 779264, Total size 780424 -NOTICE: BL31: v2.2(release):rel_imx_5.4.70_2.3.2_rc1-5-g835a8f67b -NOTICE: BL31: Built : 16:52:37, Aug 26 2021 - - -U-Boot 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100) - -CPU: Freescale i.MX8MP[8] rev1.1 at 1200 MHz -Reset cause: POR -DRAM: 8 GiB -Core: 78 devices, 18 uclasses, devicetree: separate -WDT: Started watchdog@30280000 with servicing (60s timeout) -MMC: FSL_SDHC: 1, FSL_SDHC: 2 -Loading Environment from MMC... OK -In: serial -Out: serial -Err: serial -Model: Toradex Verdin iMX8M Plus Quad 4GB Wi-Fi / BT IT V1.0B, Serial# 06817281 -Carrier: Toradex Verdin Development Board V1.1A, Serial# 10807609 -Setting variant to wifi -Net: Hard-coding pdata->enetaddr -eth1: ethernet@30be0000, eth0: ethernet@30bf0000 [PRIME] -Hit any key to stop autoboot: 0 -Verdin iMX8MP # +.. code-block:: none + + U-Boot SPL 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100) + Quad die, dual rank failed, attempting dual die, single rank configuration. + Normal Boot + WDT: Started watchdog@30280000 with servicing (60s timeout) + Trying to boot from BOOTROM + Find img info 0x&48025a00, size 872 + Need continue download 1024 + Download 779264, Total size 780424 + NOTICE: BL31: v2.2(release):rel_imx_5.4.70_2.3.2_rc1-5-g835a8f67b + NOTICE: BL31: Built : 16:52:37, Aug 26 2021 + + + U-Boot 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100) + + CPU: Freescale i.MX8MP[8] rev1.1 at 1200 MHz + Reset cause: POR + DRAM: 8 GiB + Core: 78 devices, 18 uclasses, devicetree: separate + WDT: Started watchdog@30280000 with servicing (60s timeout) + MMC: FSL_SDHC: 1, FSL_SDHC: 2 + Loading Environment from MMC... OK + In: serial + Out: serial + Err: serial + Model: Toradex Verdin iMX8M Plus Quad 4GB Wi-Fi / BT IT V1.0B, Serial# 06817281 + Carrier: Toradex Verdin Development Board V1.1A, Serial# 10807609 + Setting variant to wifi + Net: Hard-coding pdata->enetaddr + eth1: ethernet@30be0000, eth0: ethernet@30bf0000 [PRIME] + Hit any key to stop autoboot: 0 + Verdin iMX8MP # diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst new file mode 100644 index 0000000000..f44401eab7 --- /dev/null +++ b/doc/develop/board_best_practices.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Best Practices for Board Ports +============================== + +In addition to the regular best practices such as using :doc:`checkpatch` and +following the :doc:`docstyle` and the :doc:`codingstyle` there are some things +which are specific to creating a new board port. + +* Implement :doc:`bootstd` to ensure that most operating systems will be + supported by the platform. + +* The platform defconfig file must be generated via `make savedefconfig`. + +* The Kconfig and Kbuild infrastructure supports using "fragments" that can be + used to apply changes on top of a defconfig file. These can be useful for + many things such as: + + * Supporting different firmware locations (e.g. eMMC, SD, QSPI). + + * Multiple board variants when runtime detection is not desired. + + * Supporting different build types such as production and development. + + Kconfig fragments should reside in the board directory itself rather than in + the top-level `configs/` directory. diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst index 7a2a69fdfc..ec31365357 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd.rst @@ -306,7 +306,7 @@ media device:: The bootdev device is typically created automatically in the media uclass' `post_bind()` method by calling `bootdev_setup_for_dev()` or -`bootdev_setup_sibling_blk()`. The code typically something like this:: +`bootdev_setup_for_sibling_blk()`. The code typically something like this:: /* dev is the Ethernet device */ ret = bootdev_setup_for_dev(dev, "eth_bootdev"); @@ -316,7 +316,7 @@ The bootdev device is typically created automatically in the media uclass' or:: /* blk is the block device (child of MMC device) - ret = bootdev_setup_sibling_blk(blk, "mmc_bootdev"); + ret = bootdev_setup_for_sibling_blk(blk, "mmc_bootdev"); if (ret) return log_msg_ret("bootdev", ret); diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 263d404b4c..5b230d0321 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -9,6 +9,7 @@ General .. toctree:: :maxdepth: 1 + board_best_practices codingstyle designprinciples docstyle diff --git a/doc/develop/printf.rst b/doc/develop/printf.rst index 7b9aea0687..99d05061b1 100644 --- a/doc/develop/printf.rst +++ b/doc/develop/printf.rst @@ -105,19 +105,19 @@ for the individual integer types. =================== ================== Type Format specifier =================== ================== -bool %d, %x +bool %d, %x char %d, %x unsigned char %u, %x short %d, %x unsigned short %u, %x int %d, %x -unsigned int %d, %x +unsigned int %u, %x long %ld, %lx unsigned long %lu, %lx long long %lld, %llx unsigned long long %llu, %llx off_t %llu, %llx -ptr_diff_t %td, %tx +ptr_diff_t %td, %tx fdt_addr_t %pa, see pointers fdt_size_t %pa, see pointers phys_addr_t %pa, see pointers diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst index 752e1304d3..50d33df421 100644 --- a/doc/develop/release_cycle.rst +++ b/doc/develop/release_cycle.rst @@ -68,7 +68,7 @@ For the next scheduled release, release candidates were made on:: * U-Boot v2023.10-rc2 was released on Mon 07 August 2023. -.. * U-Boot v2023.10-rc3 was released on Mon 21 August 2023. +* U-Boot v2023.10-rc3 was released on Mon 21 August 2023. .. * U-Boot v2023.10-rc4 was released on Mon 04 September 2023. diff --git a/doc/develop/trace.rst b/doc/develop/trace.rst index 9bbe1345d2..546862020b 100644 --- a/doc/develop/trace.rst +++ b/doc/develop/trace.rst @@ -139,7 +139,7 @@ There is a -f option available to select a function graph: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace -f funcgraph dump-ftrace >trace.dat + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace -f funcgraph dump-ftrace -o trace.dat Again, you can use kernelshark or trace-cmd to look at the output. In this case you will see the time taken by each function shown against its exit record. @@ -171,7 +171,7 @@ command: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph >trace.fg + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -o trace.fg $ flamegraph.pl trace.fg >trace.svg You can load the .svg file into a viewer. If you use Chrome (and some other @@ -191,7 +191,7 @@ spend in each call stack: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -f timing >trace.fg + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -f timing -o trace.fg $ flamegraph.pl trace.fg >trace.svg Note that trace collection does slow down execution so the timings will be diff --git a/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt b/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt index da210bfc86..1381bdcd16 100644 --- a/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt +++ b/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt @@ -41,3 +41,6 @@ Example: Bundles both peripheral bitstream and core bitstream into FIT image resets = <&rst FPGAMGR_RESET>; altr,bitstream = "fit_spl_fpga.itb"; }; + +- The .its related documentations can be found here + - Appendix - Reducing Arria 10 Fabric Configuration Time - https://rocketboards.org/foswiki/Documentation/BuildingBootloaderCycloneVAndArria10 diff --git a/doc/imx/habv4/csf_examples/mx8m/csf.sh b/doc/imx/habv4/csf_examples/mx8m/csf.sh index d87015f6c4..65c143073c 100644 --- a/doc/imx/habv4/csf_examples/mx8m/csf.sh +++ b/doc/imx/habv4/csf_examples/mx8m/csf.sh @@ -11,7 +11,6 @@ # 1) Build U-Boot (e.g. for i.MX8MM) # -# export ATF_LOAD_ADDR=0x920000 # cp -Lv /path/to/arm-trusted-firmware/build/imx8mm/release/bl31.bin . # cp -Lv /path/to/firmware-imx-8.14/firmware/ddr/synopsys/ddr3* . # make -j imx8mm_board_defconfig diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index b74661ad3f..4f411f78d0 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -1,6 +1,6 @@ alabaster==0.7.12 Babel==2.9.1 -certifi==2023.5.7 +certifi==2023.07.22 charset-normalizer==2.0.12 docutils==0.16 idna==3.3 diff --git a/doc/usage/cmd/armffa.rst b/doc/usage/cmd/armffa.rst new file mode 100644 index 0000000000..13fa90c129 --- /dev/null +++ b/doc/usage/cmd/armffa.rst @@ -0,0 +1,94 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com> + +armffa command +============== + +Synopsis +-------- + +:: + + armffa [sub-command] [arguments] + + sub-commands: + + getpart [partition UUID] + + lists the partition(s) info + + ping [partition ID] + + sends a data pattern to the specified partition + + devlist + + displays information about the FF-A device/driver + +Description +----------- + +armffa is a command showcasing how to use the FF-A bus and how to invoke its operations. + +This provides a guidance to the client developers on how to call the FF-A bus interfaces. + +The command also allows to gather secure partitions information and ping these partitions. + +The command is also helpful in testing the communication with secure partitions. + +Example +------- + +The following examples are run on Corstone-1000 platform. + +* ping + +:: + + corstone1000# armffa ping 0x8003 + SP response: + [LSB] + fffffffe + 0 + 0 + 0 + 0 + +* ping (failure case) + +:: + + corstone1000# armffa ping 0 + Sending direct request error (-22) + +* getpart + +:: + + corstone1000# armffa getpart 33d532ed-e699-0942-c09c-a798d9cd722d + Partition: id = 8003 , exec_ctxt 1 , properties 3 + +* getpart (failure case) + +:: + + corstone1000# armffa getpart 33d532ed-e699-0942-c09c-a798d9cd7221 + INVALID_PARAMETERS: Unrecognized UUID + Failure in querying partitions count (error code: -22) + +* devlist + +:: + + corstone1000# armffa devlist + device name arm_ffa, dev 00000000fdf41c30, driver name arm_ffa, ops 00000000fffc0e98 + +Configuration +------------- + +The command is available if CONFIG_CMD_ARMFFA=y and CONFIG_ARM_FFA_TRANSPORT=y. + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) on failure. diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 2c44e5da6a..c6439dde66 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -81,6 +81,12 @@ Example:: echo CONFIG_SYS_BOARD boot failed - please check your image echo Load address is CONFIG_SYS_LOAD_ADDR +Settings which are common to a group of boards can use #include to bring in +a common file in the `include/env` directory, containing environment +settings. For example:: + + #include <env/ti/mmc.env> + If CONFIG_ENV_SOURCE_FILE is empty and the default filename is not present, then the old-style C environment is used instead. See below. @@ -94,7 +100,7 @@ to add environment variables. Board maintainers are encouraged to migrate to the text-based environment as it is easier to maintain. The distro-board script still requires the old-style -environment but work is underway to address this. +environments, so use :doc:`../develop/bootstd` instead. List of environment variables diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 072db53614..3326ec82ff 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -22,6 +22,7 @@ Shell commands cmd/acpi cmd/addrmap + cmd/armffa cmd/askenv cmd/base cmd/bdinfo |
