diff options
Diffstat (limited to 'doc')
32 files changed, 735 insertions, 82 deletions
diff --git a/doc/I2C_Edge_Conditions b/doc/I2C_Edge_Conditions index f4a99687011..9ccb21c5092 100644 --- a/doc/I2C_Edge_Conditions +++ b/doc/I2C_Edge_Conditions @@ -31,12 +31,10 @@ Notes !!!THIS IS AN UNDOCUMENTED I2C BUS BUG, NOT A AMCC 4xx BUG!!! This reset edge condition could possibly be present in every I2C -controller and device available. For boards where a I2C bus reset -function can be implemented a i2c_init_board() function should be -provided and enabled by #define'ing CONFIG_SYS_I2C_INIT_BOARD in your -board's config file. Note that this is NOT necessary when using the -bit-banging I2C driver (common/soft_i2c.c) as this already includes -the I2C bus reset sequence. +controller and device available. + +Note that this problem does not happen when using the bit-banging I2C driver +(common/soft_i2c.c) as this already includes the I2C bus reset sequence. Many thanks to Bill Hunter for finding this serious BUG. diff --git a/doc/arch/sandbox/sandbox.rst b/doc/arch/sandbox/sandbox.rst index 5f8db126657..a8b0d7f0395 100644 --- a/doc/arch/sandbox/sandbox.rst +++ b/doc/arch/sandbox/sandbox.rst @@ -655,14 +655,17 @@ Memory Map Sandbox has its own emulated memory starting at 0. Here are some of the things that are mapped into that memory: -======= ======================== =============================== -Addr Config Usage -======= ======================== =============================== - 100 CONFIG_SYS_FDT_LOAD_ADDR Device tree - b000 CONFIG_BLOBLIST_ADDR Blob list - 10000 CFG_MALLOC_F_ADDR Early memory allocation - f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer - 100000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled). Also used - as the SPL load buffer in spl_test_load(). - 200000 CONFIG_TEXT_BASE Load buffer for U-Boot (sandbox_spl only) -======= ======================== =============================== +======== ======================== =============================== +Addr Config Usage +======== ======================== =============================== + 100 CONFIG_SYS_FDT_LOAD_ADDR Device tree + b000 CONFIG_BLOBLIST_ADDR Blob list + 10000 CFG_MALLOC_F_ADDR Early memory allocation + f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer + 100000 TCG Event log TCG Event Log + 200000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled). Also used + 400000 CONFIG_TEXT_BASE Load buffer for U-Boot (sandbox_spl only) +10000000 PCI address space (see test.dts) + +ff000000 Memory-mapping tags start here +======== ======================== =============================== diff --git a/doc/board/aspeed/ibex-ast2700.rst b/doc/board/aspeed/ibex-ast2700.rst new file mode 100644 index 00000000000..511bd081ba2 --- /dev/null +++ b/doc/board/aspeed/ibex-ast2700.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +IBex AST2700 +============ + +AST2700 integrates an IBex RISC-V 32-bits CPU as the boot MCU to execute the +first stage bootlaoder, namely SPL. + +Build +----- + +1. Prepare the toolchains and make sure the $PATH to toolchains is correct. +2. Use `make ibex-ast2700_defconfig` in u-boot root to build the image + +Running U-Boot SPL +------------------ + +The U-Boot SPL will boot in M mode and load the FIT image which includes +the 2nd stage bootloaders executed by the main processor Cortex-A35. + + +Burn U-Boot to SPI Flash +------------------------ + +Use SPI flash programmer (e.g. SF100) to program the u-book-spl.bin with the +offset 0x80 bytes to the SPI flash beginning. diff --git a/doc/board/aspeed/index.rst b/doc/board/aspeed/index.rst new file mode 100644 index 00000000000..d784c88494f --- /dev/null +++ b/doc/board/aspeed/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Aspeed +====== + +.. toctree:: + :maxdepth: 2 + + ibex-ast2700 diff --git a/doc/board/atmel/at91ek.rst b/doc/board/atmel/at91ek.rst index 6185b1dfb28..a500b2f8950 100644 --- a/doc/board/atmel/at91ek.rst +++ b/doc/board/atmel/at91ek.rst @@ -6,8 +6,8 @@ AT91 Evaluation kits Board mapping & boot media -------------------------- -AT91SAM9260EK, AT91SAM9G20EK & AT91SAM9XEEK -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +AT91SAM9260EK & AT91SAM9G20EK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Memory map:: diff --git a/doc/board/index.rst b/doc/board/index.rst index 417c128c7af..3fb7c84f10c 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -14,6 +14,7 @@ Board-specific doc anbernic/index apple/index armltd/index + aspeed/index asus/index atmel/index beacon/index diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst index 4955274a39b..8c7969987a9 100644 --- a/doc/board/qualcomm/index.rst +++ b/doc/board/qualcomm/index.rst @@ -7,5 +7,6 @@ Qualcomm :maxdepth: 2 dragonboard410c + rb3gen2 board debugging diff --git a/doc/board/qualcomm/rb3gen2.rst b/doc/board/qualcomm/rb3gen2.rst new file mode 100644 index 00000000000..4240606224f --- /dev/null +++ b/doc/board/qualcomm/rb3gen2.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Caleb Connolly <caleb.connolly@linaro.org> + +Qualcomm Robotics RB3 Gen 2 +=========================== + +The RB3 Gen 2 is a development board based on the Qualcomm QCM6490 SoC (a derivative +of SC7280). More information can be found on `Qualcomm's product page`_. + +U-Boot can be used as a replacement for Qualcomm's original EDK2 bootloader by +flashing it directly to the uefi_a (or _b) partition. + +.. _Qualcomm's product page: https://www.qualcomm.com/developer/hardware/rb3-gen-2-development-kit + +Installation +------------ +First, setup ``CROSS_COMPILE`` for aarch64. Then, build U-Boot for ``qcm6490``:: + + $ export CROSS_COMPILE=<aarch64 toolchain prefix> + $ make qcm6490_defconfig + $ make -j8 + +This will build ``u-boot.elf`` in the configured output directory. + +Although the RB3 Gen 2 does not have secure boot set up by default, +the firmware still expects firmware ELF images to be "signed". The signature +does not provide any security in this case, but it provides the firmware with +some required metadata. + +To "sign" ``u-boot.elf`` you can use e.g. `qtestsign`_:: + + $ qtestsign -v6 aboot -o u-boot.mbn u-boot.elf + +Then install the resulting ``u-boot.mbn`` to the ``uefi_a`` partition +on your device with ``fastboot flash uefi_a u-boot.mbn``. + +U-Boot should be running after a reboot (``fastboot reboot``). + +Note that fastboot is not yet supported in U-Boot on this board, as a result, +to flash back the original firmware, or new versoins of the U-Boot, EDL mode +must be used. This can be accessed by pressing the EDL mode button as described +in the Qualcomm Linux documentation. A tool like bkerler's `edl`_ can be used +for flashing with the firehose loader binary appropriate for the board. + +.. _qtestsign: https://github.com/msm8916-mainline/qtestsign +.. _edl: https://github.com/bkerler/edl + +Usage +----- + +The USB Type-A ports are connected via a PCIe USB hub, which is not supported yet. +However, the Type-C port can be used with a powered USB dock to connect peripherals +like a USB stick. diff --git a/doc/board/samsung/e850-96.rst b/doc/board/samsung/e850-96.rst index 0cb95473e53..0a7b6fc0c9d 100644 --- a/doc/board/samsung/e850-96.rst +++ b/doc/board/samsung/e850-96.rst @@ -47,12 +47,13 @@ Build Procedure --------------- .. warning:: - At the moment both eMMC and USB features are not enabled in U-Boot. Flashing + At the moment USB is not enabled in U-Boot for this board. Although eMMC is + enabled, you won't be able to flash images over USB (fastboot). So flashing U-Boot binary **WILL** effectively brick your board. The ``dltool`` [8]_ can be used then to perform USB boot and flash LittleKernel bootloader binary [7]_ to unbrick and revive the board. Flashing U-Boot binary might be helpful for developers or anybody who want to check current state of U-Boot enablement on - E850-96 (which is mostly serial console and related blocks). + E850-96 (which is mostly serial console, eMMC and related blocks). Build U-Boot binary from source code (using AArch64 baremetal GCC toolchain): diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst index b9d35244d44..51dab839ddd 100644 --- a/doc/board/ti/am62x_sk.rst +++ b/doc/board/ti/am62x_sk.rst @@ -132,6 +132,20 @@ DFU support (and disable storage support) .. include:: ../ti/k3.rst :start-after: .. k3_rst_include_start_build_steps_uboot :end-before: .. k3_rst_include_end_build_steps_uboot + +* 3.2.1 Alternative build of A53 for Android bootflow: + +Since the Android requires many more dependencies, it is disabled by default. +An extra config fragment should be used to enable Android bootflow support. + +.. prompt:: bash $ + + export UBOOT_CFG_CORTEXR="${UBOOT_CFG_CORTEXA} am62x_a53_android.config" + +.. include:: ../ti/k3.rst + :start-after: .. k3_rst_include_start_build_steps_uboot + :end-before: .. k3_rst_include_end_build_steps_uboot + .. am62x_evm_rst_include_end_build_steps Target Images diff --git a/doc/develop/commands.rst b/doc/develop/commands.rst index 5ad4e59c838..77a7a4d9c02 100644 --- a/doc/develop/commands.rst +++ b/doc/develop/commands.rst @@ -197,7 +197,6 @@ Here is an example: ctx.current = buf; ut_assertok(acpi_fill_ssdt(&ctx)); - console_record_reset(); run_command("acpi items", 0); ut_assert_nextline("dev 'acpi-test', type 1, size 2"); ut_assert_nextline("dev 'acpi-test2', type 1, size 2"); @@ -205,13 +204,11 @@ Here is an example: ctx.current = buf; ut_assertok(acpi_inject_dsdt(&ctx)); - console_record_reset(); run_command("acpi items", 0); ut_assert_nextline("dev 'acpi-test', type 2, size 2"); ut_assert_nextline("dev 'acpi-test2', type 2, size 2"); ut_assert_console_end(); - console_record_reset(); run_command("acpi items -d", 0); ut_assert_nextline("dev 'acpi-test', type 2, size 2"); ut_assert_nextlines_are_dump(2); @@ -223,4 +220,8 @@ Here is an example: return 0; } - DM_TEST(dm_test_acpi_cmd_items, UT_TESTF_SCAN_PDATA | UT_TESTF_SCAN_FDT); + DM_TEST(dm_test_acpi_cmd_items, UTF_SCAN_PDATA | UTF_SCAN_FDT | UTF_CONSOLE); + +Note that it is not necessary to call console_record_reset() unless you are +trying to drop some unchecked output. Consider using ut_check_skip_to_line() +instead. diff --git a/doc/develop/global_data.rst b/doc/develop/global_data.rst index d143f27eedd..2863154ea42 100644 --- a/doc/develop/global_data.rst +++ b/doc/develop/global_data.rst @@ -51,6 +51,31 @@ U-Boot. The value of gd has to be saved every time U-Boot is left and restored whenever U-Boot is reentered. This is also relevant for the implementation of function tracing. For setting the value of gd function set_gd() can be used. +Guidelines +---------- + +The global_data structure is placed in some memory which is available very early +after boot to allow for a minimum set of global variables during system +initialisation (until the memory controller is set up and RAM can be used). It +is the primary data structure passed from pre-relocation U-Boot to +post-relocation, i.e. ``from board_init_f()`` ``to board_init_r()``. + +The global_data struct exists for the lifetime of U-Boot. Since the struct is +used by all architectures, fields added should be useful for most architectures. +Fields which are only needed on one or two architectures can be placed in the +architecture-specific ``struct arch_global_data``. + +In any case the struct should be kept small, since it uses precious SRAM on +many boards. + +SPL also uses global data, as well as U-Boot proper, so take care to avoid +adding fields to SPL which are not actually used by SPL. You can create +access functions or macros in the header file to avoid filling the C code with +#ifdefs. + +A flags word is available, which provides a convenient means to track the state +of various initialisation phases within U-Boot. + Global data structure --------------------- diff --git a/doc/README.generic-board b/doc/develop/historical/generic_board.rst index bc35179fbfd..12550a140e0 100644 --- a/doc/README.generic-board +++ b/doc/develop/historical/generic_board.rst @@ -1,10 +1,9 @@ -# SPDX-License-Identifier: GPL-2.0+ -# -# (C) Copyright 2014 Google, Inc -# Simon Glass <sjg@chromium.org> +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2014 Google, Inc +.. sectionauthor:: Simon Glass <sjg@chromium.org> -Background ----------- +Generic board +------------- U-Boot traditionally had a board.c file for each architecture. This introduced quite a lot of duplication, with each architecture tending to do @@ -16,7 +15,7 @@ All boards and architectures have moved to this as of mid 2016. What has changed? ------------------ +~~~~~~~~~~~~~~~~~ The main change is that the arch/<arch>/lib/board.c file is removed in favour of common/board_f.c (for pre-relocation init) and common/board_r.c @@ -28,7 +27,7 @@ have been moved to separate structures. Further Background ------------------- +~~~~~~~~~~~~~~~~~~ The full text of the original generic board series is reproduced below. @@ -132,4 +131,6 @@ convenience. Simon Glass, sjg@chromium.org March 2014 + Updated after final removal, May 2016 + diff --git a/doc/develop/historical/index.rst b/doc/develop/historical/index.rst new file mode 100644 index 00000000000..e4462f5d2a7 --- /dev/null +++ b/doc/develop/historical/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Historical Documents +==================== + +This section provides documentation about major changes in U-Boot over the +years. + +.. toctree:: + :maxdepth: 1 + + generic_board diff --git a/doc/develop/index.rst b/doc/develop/index.rst index c0107a783fc..0d0e60ab56c 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -99,3 +99,11 @@ Code quality :maxdepth: 1 python_cq + +Historical documentation +------------------------ + +.. toctree:: + :maxdepth: 2 + + historical/index diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index 44b544fa78b..a328ebfef33 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -81,7 +81,7 @@ The best of both worlds is sometimes to have a Python test set things up and perform some operations, with a 'checker' C unit test doing the checks afterwards. This can be achieved with these steps: -- Add the `UT_TESTF_MANUAL` flag to the checker test so that the `ut` command +- Add the `UTF_MANUAL` flag to the checker test so that the `ut` command does not run it by default - Add a `_norun` suffix to the name so that pytest knows to skip it too @@ -95,7 +95,7 @@ test to run it, e.g.:: # Run the checker to make sure that everything worked ut -f bootstd vbe_test_fixup_norun -Note that apart from the `UT_TESTF_MANUAL` flag, the code in a 'manual' C test +Note that apart from the `UTF_MANUAL` flag, the code in a 'manual' C test is just like any other C test. It still uses ut_assert...() and other such constructs, in this case to check that the expected things happened in the Python test. @@ -151,7 +151,6 @@ There is no exactly equivalent C test, but here is a similar one that tests 'ms' buf[0x31] = 0x12; buf[0xff] = 0x12; buf[0x100] = 0x12; - ut_assertok(console_record_reset_enable()); run_command("ms.b 1 ff 12", 0); ut_assert_nextline("00000030: 00 12 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................"); ut_assert_nextline("--"); @@ -167,7 +166,7 @@ There is no exactly equivalent C test, but here is a similar one that tests 'ms' return 0; } - MEM_TEST(mem_test_ms_b, UT_TESTF_CONSOLE_REC); + MEM_TEST(mem_test_ms_b, UTF_CONSOLE); This runs the command directly in U-Boot, then checks the console output, also directly in U-Boot. If run by itself this takes 100ms. For 1000 runs it takes @@ -226,14 +225,17 @@ Declare the test with:: return 0; } - DM_TEST(dm_test_uclassname_what, UT_TESTF_SCAN_FDT); + DM_TEST(dm_test_uclassname_what, UTF_SCAN_FDT); + +Note that the convention is to NOT add a blank line before the macro, so that +the function it relates to is more obvious. Replace 'uclassname' with the name of your uclass, if applicable. Replace 'what' with what you are testing. The flags for DM_TEST() are defined in test/test.h and you typically want -UT_TESTF_SCAN_FDT so that the devicetree is scanned and all devices are bound -and ready for use. The DM_TEST macro adds UT_TESTF_DM automatically so that +UTF_SCAN_FDT so that the devicetree is scanned and all devices are bound +and ready for use. The DM_TEST macro adds UTF_DM automatically so that the test runner knows it is a driver model test. Driver model tests are special in that the entire driver model state is @@ -263,7 +265,7 @@ with the suite. For example, to add a new mem_search test:: return 0; } - MEM_TEST(mem_test_ms_new_thing, UT_TESTF_CONSOLE_REC); + MEM_TEST(mem_test_ms_new_thing, UTF_CONSOLE); Note that the MEM_TEST() macros is defined at the top of the file. diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index d450b12bf80..94482758573 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -449,6 +449,33 @@ practice. Getting this information from the firmware itself is more secure, assuming the firmware has been verified by a previous stage boot loader. +Dynamic Firmware Update GUIDs +***************************** + +The image_type_id contains a GUID value which is specific to the image +and board being updated, that is to say it should uniquely identify the +board model (and revision if relevant) and image pair. Traditionally, +these GUIDs are generated manually and hardcoded on a per-board basis, +however this scheme makes it difficult to scale up to support many +boards. + +To address this, v5 GUIDs can be used to generate board-specific GUIDs +at runtime, based on the board's devicetree root compatible +(e.g. "qcom,qrb5165-rb5"). + +These strings are combined with the fw_image name to generate GUIDs for +each image. Support for dynamic UUIDs can be enabled by generating a new +namespace UUID and setting EFI_CAPSULE_NAMESPACE_GUID to it. Dynamic GUID +generation is only enabled if the image_type_id property is unset for your +firmware images, this is to avoid breaking existing boards with hardcoded +GUIDs. + +The mkeficapsule tool can be used to determine the GUIDs for a particular +board and image. It can be found in the tools directory. + +Firmware update images +********************** + The firmware images structure defines the GUID values, image index values and the name of the images that are to be updated through the capsule update feature. These values are to be defined as part of diff --git a/doc/device-tree-bindings/arm/adi/adi,sc5xx.yaml b/doc/device-tree-bindings/arm/adi/adi,sc5xx.yaml new file mode 100644 index 00000000000..df976c7ae73 --- /dev/null +++ b/doc/device-tree-bindings/arm/adi/adi,sc5xx.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0+) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/adi/adi,sc5xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices SC5XX ARM-based SoCs + +maintainers: + - Vasileios Bimpikas <vasileios.bimpikas@analog.com> + - Utsav Agarwal <utsav.agarwal@analog.com> + - Arturs Artamonovs <arturs.artamonovs@analog.com> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: SC57X Series Boards + items: + - const: adi,sc573-ezkit + - const: adi,sc57x + + - description: SC58X Series Boards + items: + - enum: + - adi,sc584-ezkit + - adi,sc589-ezkit + - adi,sc589-mini + - const: adi,sc58x + + - description: SC59X Series 32-bit Boards + items: + - enum: + - adi,sc594-som-ezkit + - adi,sc594-som-ezlite + - const: adi,sc59x + + - description: SC59X Series 64-bit Boards + items: + - enum: + - adi,sc598-som-ezkit + - adi,sc598-som-ezlite + - const: adi,sc59x-64 + +additionalProperties: true diff --git a/doc/device-tree-bindings/clock/adi,sc5xx-clocks.yaml b/doc/device-tree-bindings/clock/adi,sc5xx-clocks.yaml new file mode 100644 index 00000000000..9bbd5467a01 --- /dev/null +++ b/doc/device-tree-bindings/clock/adi,sc5xx-clocks.yaml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: (GPL-2.0+) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/adi,sc5xx-clocks.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Clock Tree Drivers for Analog Devices SC5XX Processors + +maintainers: + - Vasileios Bimpikas <vasileios.bimpikas@analog.com> + - Utsav Agarwal <utsav.agarwal@analog.com> + - Arturs Artamonovs <arturs.artamonovs@analog.com> + +description: | + These drivers read in the processors CDU (clock distribution unit) + and CGU (clock generation unit) values to determine various clock + rates + +properties: + compatible: + enum: + - adi,sc5xx-clocks # Any + - adi,sc57x-clocks # 32-Bit SC573 processor + - adi,sc58x-clocks # 32-Bit SC584, SC589 processors + - adi,sc594-clocks # 32-Bit SC594 processor + - adi,sc598-clocks # 64-Bit SC598 processor + + '#clock-cells': + const: 1 + + reg: + minItems: 3 + maxItems: 4 + + reg-names: + description: + String reference names for the reg property + minItems: 3 + maxItems: 4 + + clocks: + description: + Specifies the CLKIN0 and CLKIN1 reference clock(s) from which the + output frequencies are derived via CDU+CGU + minItems: 2 + maxItems: 2 + + clock-names: + description: + String reference names for CLKIN0 and CLKIN1 + minItems: 2 + maxItems: 2 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + - clock-names + +additionalProperties: false + +examples: + - | + clk0: clocks@3108d000 { + compatible = "adi,sc57x-clocks"; + reg = <0x3108d000 0x1000>, + <0x3108e000 0x1000>, + <0x3108f000 0x1000>; + #clock-cells = <1>; + clocks = <&sys_clkin0>, <&sys_clkin1>; + clock-names = "sys_clkin0", "sys_clkin1"; + status = "okay"; + }; + + - | + clk1: clocks@3108d000 { + compatible = "adi,sc58x-clocks"; + reg = <0x3108d000 0x1000>, + <0x3108e000 0x1000>, + <0x3108f000 0x1000>; + #clock-cells = <1>; + clocks = <&sys_clkin0>, <&sys_clkin1>; + clock-names = "sys_clkin0", "sys_clkin1"; + status = "okay"; + }; + + - | + clk2: clocks@3108d000 { + compatible = "adi,sc594-clocks"; + reg = <0x3108d000 0x1000>, + <0x3108e000 0x1000>, + <0x3108f000 0x1000>; + #clock-cells = <1>; + clocks = <&sys_clkin0>, <&sys_clkin1>; + clock-names = "sys_clkin0", "sys_clkin1"; + status = "okay"; + }; + + - | + clk3: clocks@3108d000 { + compatible = "adi,sc598-clocks"; + reg = <0x3108d000 0x1000>, + <0x3108e000 0x1000>, + <0x3108f000 0x1000>, + <0x310a9000 0x1000>; + #clock-cells = <1>; + clocks = <&sys_clkin0>, <&sys_clkin1>; + clock-names = "sys_clkin0", "sys_clkin1"; + status = "okay"; + }; + diff --git a/doc/device-tree-bindings/exynos/dwmmc.txt b/doc/device-tree-bindings/exynos/dwmmc.txt index 694d1959162..d90792be859 100644 --- a/doc/device-tree-bindings/exynos/dwmmc.txt +++ b/doc/device-tree-bindings/exynos/dwmmc.txt @@ -12,7 +12,9 @@ SOC specific and Board specific properties are channel specific. Required SoC Specific Properties: - compatible: should be - - samsung,exynos-dwmmc: for exynos platforms + - samsung,exynos4412-dw-mshc: for Exynos4 platforms + - samsung,exynos-dwmmc: for Exynos5 platforms + - samsung,exynos7-dw-mshc-smu: for Exynos7 platforms (with SMU block) - reg: physical base address of the controller and length of memory mapped region. @@ -23,32 +25,38 @@ Required Board Specific Properties: - #address-cells: should be 1. - #size-cells: should be 0. -- samsung,bus-width: The width of the bus used to interface the devices +- bus-width: The width of the bus used to interface the devices supported by DWC_mobile_storage (SD-MMC/EMMC/SDIO). . Typically the bus width is 4 or 8. -- samsung,timing: The timing values to be written into the - Drv/sample clock selection register of corresponding channel. - . It is comprised of 3 values corresponding to the 3 fileds - 'SelClk_sample', 'SelClk_drv' and 'DIVRATIO' of CLKSEL register. - . SelClk_sample: Select sample clock among 8 shifted clocks. - . SelClk_drv: Select drv clock among 8 shifted clocks. - . DIVRATIO: Clock Divide ratio select. - . The above 3 values are used by the clock phase shifter. +- samsung,dw-mshc-ciu-div: The divider value for the card interface unit (ciu) + clock (0..7). +- samsung,dw-mshc-sdr-timing: The timing values for single data rate (SDR) mode + operation. + . First value is CIU clock phase shift value for TX mode (0..7). + . Second value is CIU clock phase shift value for RX mode (0..7). +- samsung,dw-mshc-ddr-timing: The timing values for double data rate (DDR) mode + operation. If missing, values from samsung,dw-mshc-sdr-timing are used. + . First value is CIU clock phase shift value for TX mode (0..7). + . Second value is CIU clock phase shift value for RX mode (0..7). Example: mmc@12200000 { - samsung,bus-width = <8>; - samsung,timing = <1 3 3>; - samsung,removable = <1>; -} + bus-width = <8>; + non-removable; + samsung,dw-mshc-ciu-div = <3>; + samsung,dw-mshc-sdr-timing = <1 3>; + samsung,dw-mshc-ddr-timing = <0 2>; +}; + In the above example, . The bus width is 8 - . Timing is comprised of 3 values as explained below + . Divider value for CLKSEL register is 3. The CIU clock rate will be + calculated as SDCLKIN / (3 + 1). + . SDR and DDR timings are comprised of 2 values as explained below 1 - SelClk_sample 3 - SelClk_drv - 3 - DIVRATIO - . The 'removable' flag indicates whether the the particilar device + . The 'non-removable' flag indicates whether the particular device cannot be removed (always present) or it is a removable device. - 1 - Indicates that the device is removable. - 0 - Indicates that the device cannot be removed. + Flag is present - Indicates that the device cannot be removed. + Flag is not present - Indicates that the device is removable. diff --git a/doc/device-tree-bindings/spi/soft-spi.txt b/doc/device-tree-bindings/spi/soft-spi.txt index bdf7e86befb..77b01b2fd9a 100644 --- a/doc/device-tree-bindings/spi/soft-spi.txt +++ b/doc/device-tree-bindings/spi/soft-spi.txt @@ -8,14 +8,15 @@ The soft SPI node requires the following properties: Mandatory properties: compatible: "spi-gpio" -cs-gpios: GPIOs to use for SPI chip select (output) +cs-gpios: GPIOs to use for SPI chip select (output), not required if num-chipselects = <0> sck-gpios: GPIO to use for SPI clock (output) And at least one of: mosi-gpios: GPIO to use for SPI MOSI line (output) miso-gpios: GPIO to use for SPI MISO line (input) -Optional propertie: +Optional properties: spi-delay-us: Number of microseconds of delay between each CS transition +num-chipselects: Number of chipselect lines The GPIOs should be specified as required by the GPIO controller referenced. The first cell holds the phandle of the controller and the second cell diff --git a/doc/device-tree-bindings/timer/adi,sc5xx-gptimer.yaml b/doc/device-tree-bindings/timer/adi,sc5xx-gptimer.yaml new file mode 100644 index 00000000000..5e313af6fe0 --- /dev/null +++ b/doc/device-tree-bindings/timer/adi,sc5xx-gptimer.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0+) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/adi,sc5xx-gptimer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices SC5XX Series SoC Timer Peripherals + +maintainers: + - Vasileios Bimpikas <vasileios.bimpikas@analog.com> + - Utsav Agarwal <utsav.agarwal@analog.com> + - Arturs Artamonovs <arturs.artamonovs@analog.com> + +properties: + compatible: + const: adi,sc5xx-gptimer + + reg: + minItems: 2 + maxItems: 2 + + clocks: + minItems: 1 + maxItems: 1 + +required: + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + timer0: timer@31018000 { + compatible = "adi,sc5xx-gptimer"; + reg = <0x31018004 0x100>, + <0x31018060 0x100>; + status = "okay"; + bootph-all; + }; + diff --git a/doc/mkeficapsule.1 b/doc/mkeficapsule.1 index eaaba2cf232..a726149ba2c 100644 --- a/doc/mkeficapsule.1 +++ b/doc/mkeficapsule.1 @@ -10,6 +10,9 @@ mkeficapsule \- Generate EFI capsule file for U-Boot .B mkeficapsule .RI [ options ] " " [ image-blob ] " " capsule-file +.B mkeficapsule +.RI guidgen " " [ GUID ] " " DTB " " IMAGE_NAME... + .SH "DESCRIPTION" The .B mkeficapsule @@ -42,6 +45,10 @@ multiple binary blobs in a single capsule file. This type of image file can be generated by .BR mkimage . +mkeficapsule can also be used to simulate the dynamic GUID generation used to +identify firmware images in capsule updates by providing the namespace guid, dtb +for the board, and a list of firmware images. + .SH "OPTIONS" .TP @@ -117,6 +124,22 @@ at every firmware update. .B "-d\fR,\fB --dump_sig" Dump signature data into *.p7 file +.SH "GUIDGEN OPTIONS" + +.TP +.B "[GUID]" +The namespace/salt GUID, by default this is EFI_CAPSULE_NAMESPACE_GUID. +The format is: + xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +.TP +.B DTB +The device tree blob file for the board. + +.TP +.B IMAGE_NAME... +The names of the firmware images to generate GUIDs for. + .PP .SH FILES .TP diff --git a/doc/usage/cmd/bind.rst b/doc/usage/cmd/bind.rst index 23457783666..67a0405bab5 100644 --- a/doc/usage/cmd/bind.rst +++ b/doc/usage/cmd/bind.rst @@ -12,7 +12,7 @@ Synopsis :: bind <node path> <driver> - bind <class> <index> <driver> + bind <class> <seq> <driver> Description ----------- @@ -30,8 +30,8 @@ node path class device class name -index - index of the parent device in the device class +seq + sequence number of the parent device in the device class driver device driver name @@ -46,7 +46,7 @@ using the two alternative bind syntaxes. .. code-block:: => dm tree - Class Index Probed Driver Name + Class Seq Probed Driver Name ----------------------------------------------------------- root 0 [ + ] root_driver root_driver ... @@ -75,13 +75,13 @@ using the two alternative bind syntaxes. => date Cannot find RTC: err=-19 => dm tree - Class Index Probed Driver Name + Class Seq Probed Driver Name ----------------------------------------------------------- root 0 [ + ] root_driver root_driver ... => bind /pl031@9010000 rtc-pl031 => dm tree - Class Index Probed Driver Name + Class Seq Probed Driver Name ----------------------------------------------------------- root 0 [ + ] root_driver root_driver ... diff --git a/doc/usage/cmd/dm.rst b/doc/usage/cmd/dm.rst index 7651507937a..196b22d1376 100644 --- a/doc/usage/cmd/dm.rst +++ b/doc/usage/cmd/dm.rst @@ -112,9 +112,8 @@ This shows the full tree of devices including the following fields: uclass Shows the name of the uclass for the device -Index - Shows the index number of the device, within the uclass. This shows the - ordering within the uclass, but not the sequence number. +Seq + Shows the sequence number of the device, within the uclass. Probed Shows `+` if the device is active @@ -366,7 +365,7 @@ dm tree This example shows the abridged sandbox output:: => dm tree - Class Index Probed Driver Name + Class Seq Probed Driver Name ----------------------------------------------------------- root 0 [ + ] root_driver root_driver demo 0 [ ] demo_shape_drv |-- demo_shape_drv diff --git a/doc/usage/cmd/env.rst b/doc/usage/cmd/env.rst index 9629f97ffc4..b65d85b6681 100644 --- a/doc/usage/cmd/env.rst +++ b/doc/usage/cmd/env.rst @@ -79,7 +79,8 @@ The *env default* command resets the selected variables in the U-Boot environment to their default values. var - list of variable name. + list of variable names. If variable is not part of default + environment, it is deleted with a warning message on console. \-a all U-Boot environment. \-f @@ -309,6 +310,7 @@ Delete environment variable in memory:: Reset environment variable to default value, in memory:: => env default bootcmd + => env default ipaddr serverip => env default -a Save current environment in persistent storage:: diff --git a/doc/usage/cmd/mmc.rst b/doc/usage/cmd/mmc.rst index 5a64400eeae..55391fda24c 100644 --- a/doc/usage/cmd/mmc.rst +++ b/doc/usage/cmd/mmc.rst @@ -15,6 +15,7 @@ Synopsis mmc read addr blk# cnt mmc write addr blk# cnt mmc erase blk# cnt + mmc erase partname mmc rescan [mode] mmc part mmc dev [dev] [part] [mode] @@ -44,12 +45,15 @@ The 'mmc write' command writes raw data to MMC device from memory address with b cnt block count -The 'mmc erase' command erases *cnt* blocks on the MMC device starting at block *blk#*. +The 'mmc erase' command erases *cnt* blocks on the MMC device starting at block *blk#* or +the entire partition specified by *partname*. blk# start block offset cnt block count + partname + partition name The 'mmc rescan' command scans the available MMC device. diff --git a/doc/usage/cmd/unbind.rst b/doc/usage/cmd/unbind.rst index 0309e90f6ea..1ae9c1b172c 100644 --- a/doc/usage/cmd/unbind.rst +++ b/doc/usage/cmd/unbind.rst @@ -12,8 +12,8 @@ Synopsis :: unbind <node path> - unbind <class> <index> - unbind <class> <index> <driver> + unbind <class> <seq> + unbind <class> <seq> <driver> Description ----------- @@ -27,8 +27,8 @@ node path class device class name -index - index of the device in the device class +seq + sequence number of the device in the device class driver device driver name @@ -43,7 +43,7 @@ using the three alternative unbind syntaxes. .. code-block:: => dm tree - Class Index Probed Driver Name + Class Seq Probed Driver Name ----------------------------------------------------------- root 0 [ + ] root_driver root_driver ... @@ -70,7 +70,7 @@ using the three alternative unbind syntaxes. } => unbind /pl031@9010000 => dm tree - Class Index Probed Driver Name + Class Seq Probed Driver Name ----------------------------------------------------------- root 0 [ + ] root_driver root_driver ... @@ -78,7 +78,7 @@ using the three alternative unbind syntaxes. Cannot find a device with path /pl031@9010000 => bind /pl031@9010000 rtc-pl031 => dm tree - Class Index Probed Driver Name + Class Seq Probed Driver Name ----------------------------------------------------------- root 0 [ + ] root_driver root_driver ... diff --git a/doc/usage/cmd/upl.rst b/doc/usage/cmd/upl.rst new file mode 100644 index 00000000000..8d6ea5daa37 --- /dev/null +++ b/doc/usage/cmd/upl.rst @@ -0,0 +1,186 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +upl command +=========== + +Synopsis +-------- + +:: + + upl write + upl read <addr> + upl info [-v] + +Description +----------- + +The *upl* command is used to test U-Boot's support for the Universal Payload +Specification (UPL) firmware standard (see :doc:`../upl`). It allows creation of +a fake handoff for use in testing. + + +upl write +~~~~~~~~~ + +Write a fake UPL handoff structure. The `upladdr` environment variable is set to +the address of this structure and `uplsize` is set to the size. + + +upl read +~~~~~~~~ + +Read a UPL handoff structure into internal state. This allows testing that the +handoff can be obtained. + +upl info +~~~~~~~~ + +Show basic information about usage of UPL: + + UPL state + active or inactive (indicates whether U-Boot booted from UPL or not) + + fit + Address of the FIT which was loaded + + conf_offset 2a4 + FIT offset of the chosen configuration + +For each image the following information is shown: + + Image number + Images are numbered from 0 + + load + Address to which the image was loaded + + size + Size of the loaded image + + offset + FIT offset of the image + + description + Description of the image + + +Example +------- + +This shows checking whether a UPL handoff was read at start-up:: + + => upl info + UPL state: active + +This shows how to use the command to write and display the handoff:: + + => upl write + UPL handoff written to bc8a5e0 size 662 + => print upladdr + upladdr=bc8a5e0 + => print uplsize + uplsize=662 + + > fdt addr ${upladdr} + Working FDT set to bc8a5e0 + => fdt print + / { + #address-cells = <0x00000001>; + #size-cells = <0x00000001>; + options { + upl-params { + smbios = <0x00000123>; + acpi = <0x00000456>; + bootmode = "default", "s3"; + addr-width = <0x0000002e>; + acpi-nvs-size = <0x00000100>; + }; + upl-image { + fit = <0x00000789>; + conf-offset = <0x00000234>; + image-1 { + load = <0x00000001>; + size = <0x00000002>; + offset = <0x00000003>; + description = "U-Boot"; + }; + image-2 { + load = <0x00000004>; + size = <0x00000005>; + offset = <0x00000006>; + description = "ATF"; + }; + }; + }; + memory@0x10 { + reg = <0x00000010 0x00000020 0x00000030 0x00000040 0x00000050 0x00000060>; + }; + memory@0x70 { + reg = <0x00000070 0x00000080>; + hotpluggable; + }; + memory-map { + acpi@0x11 { + reg = <0x00000011 0x00000012 0x00000013 0x00000014 0x00000015 0x00000016 0x00000017 0x00000018 0x00000019 0x0000001a>; + usage = "acpi-reclaim"; + }; + u-boot@0x21 { + reg = <0x00000021 0x00000022>; + usage = "boot-data"; + }; + efi@0x23 { + reg = <0x00000023 0x00000024>; + usage = "runtime-code"; + }; + empty@0x25 { + reg = <0x00000025 0x00000026 0x00000027 0x00000028>; + }; + acpi-things@0x2a { + reg = <0x0000002a 0x00000000>; + usage = "acpi-nvs", "runtime-code"; + }; + }; + reserved-memory { + mmio@0x2b { + reg = <0x0000002b 0x0000002c>; + }; + memory@0x2d { + reg = <0x0000002d 0x0000002e 0x0000002f 0x00000030>; + no-map; + }; + }; + serial@0xf1de0000 { + compatible = "ns16550a"; + clock-frequency = <0x001c2000>; + current-speed = <0x0001c200>; + reg = <0xf1de0000 0x00000100>; + reg-io-shift = <0x00000002>; + reg-offset = <0x00000040>; + virtual-reg = <0x20000000>; + access-type = "mmio"; + }; + framebuffer@0xd0000000 { + compatible = "simple-framebuffer"; + reg = <0xd0000000 0x10000000>; + width = <0x00000500>; + height = <0x00000500>; + stride = <0x00001400>; + format = "a8r8g8b8"; + }; + }; + => + +This showing reading the handoff into internal state:: + + => upl read bc8a5e0 + Reading UPL at bc8a5e0 + => + +This shows getting basic information about UPL: + + => upl info -v + UPL state: active + fit 1264000 + conf_offset 2a4 + image 0: load 200000 size 105f5c8 offset a4: U-Boot 2024.07-00770-g739ee12e8358 for sandbox board diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst index 45bc9ffbdc5..afeafa824d6 100644 --- a/doc/usage/cmd/ut.rst +++ b/doc/usage/cmd/ut.rst @@ -32,7 +32,7 @@ to run some tests on real boards. For a list of available test suites, type `ut` by itself. -Each test is normally run once, although those marked with `UT_TESTF_DM` are +Each test is normally run once, although those marked with `UTF_DM` are run with livetree and flattree where possible. To run a test more than once, use the `-r` flag. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 6a218c46b4e..70563374899 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -15,6 +15,7 @@ Use U-Boot cmdline semihosting measured_boot + upl Shell commands -------------- @@ -115,6 +116,7 @@ Shell commands cmd/tftpput cmd/trace cmd/true + cmd/upl cmd/ums cmd/unbind cmd/ut diff --git a/doc/usage/upl.rst b/doc/usage/upl.rst new file mode 100644 index 00000000000..3c4a10c862c --- /dev/null +++ b/doc/usage/upl.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Universal Payload +----------------- + +`Universal Payload (UPL) <https://universalpayload.github.io/spec/index.html>`_ +is an Industry Standard for firmware components. UPL +is designed to improve interoperability within the firmware industry, allowing +mixing and matching of projects with less friction and fewer project-specific +implementations. UPL is cross-platform, supporting ARM, x86 and RISC-V +initially. + +UPL is defined in termns of two firmware components: + +`Platform Init` + Perhaps initial setup of the hardware and jumps to the payload. + +`Payload` + Selects the OS to boot + +In practice UPL can be used to handle any number of handoffs through the +firmware startup process, with one program acting as platform init and another +acting as the payload. + +UPL provides a standard for three main pieces: + +- file format for the payload, which may comprise multiple images to load +- handoff format for the information the payload needs, such as serial port, + memory layout, etc. +- machine state and register settings at the point of handoff + +See also the :doc:`cmd/upl`. + +UPL in U-Boot +~~~~~~~~~~~~~ + +U-Boot supports: + +- writing a UPL handoff (devicetree) in SPL +- reading a UPL handoff in U-Boot proper +- creating a FIT + +There are some new FIT features in UPL which are not yet supported in U-Boot. + +.. sectionauthor:: Simon Glass <sjg@chromium.org> +.. July 2024 |