diff options
| author | Tom Rini <trini@konsulko.com> | 2021-10-04 11:27:55 -0400 |
|---|---|---|
| committer | Tom Rini <trini@konsulko.com> | 2021-10-04 11:28:16 -0400 |
| commit | 50c84208ad50a27382c64af911abba4510a8b608 (patch) | |
| tree | 1b79a2e167ca4094d4adc80ab1195f42e792e309 /doc | |
| parent | d80bb749fab53da72c4a0e09b8c2d2aaa3103c91 (diff) | |
| parent | e17cbdd050f7127737988997f4a01583b34f7c96 (diff) | |
| download | u-boot-50c84208ad50a27382c64af911abba4510a8b608.tar.gz u-boot-50c84208ad50a27382c64af911abba4510a8b608.tar.bz2 u-boot-50c84208ad50a27382c64af911abba4510a8b608.zip | |
Merge branch 'next'
Signed-off-by: Tom Rini <trini@konsulko.com>
Diffstat (limited to 'doc')
50 files changed, 1408 insertions, 111 deletions
diff --git a/doc/README.SPL b/doc/README.SPL index 0448835f5f..011fd42537 100644 --- a/doc/README.SPL +++ b/doc/README.SPL @@ -49,10 +49,10 @@ CONFIG_SPL_LIBCOMMON_SUPPORT (common/libcommon.o) CONFIG_SPL_LIBDISK_SUPPORT (disk/libdisk.o) CONFIG_SPL_I2C (drivers/i2c/libi2c.o) CONFIG_SPL_GPIO (drivers/gpio/libgpio.o) -CONFIG_SPL_MMC_SUPPORT (drivers/mmc/libmmc.o) -CONFIG_SPL_SERIAL_SUPPORT (drivers/serial/libserial.o) +CONFIG_SPL_MMC (drivers/mmc/libmmc.o) +CONFIG_SPL_SERIAL (drivers/serial/libserial.o) CONFIG_SPL_SPI_FLASH_SUPPORT (drivers/mtd/spi/libspi_flash.o) -CONFIG_SPL_SPI_SUPPORT (drivers/spi/libspi.o) +CONFIG_SPL_SPI (drivers/spi/libspi.o) CONFIG_SPL_FS_FAT (fs/fat/libfat.o) CONFIG_SPL_FS_EXT4 CONFIG_SPL_LIBGENERIC_SUPPORT (lib/libgeneric.o) diff --git a/doc/README.commands.spl b/doc/README.commands.spl index cb3e0c8e0a..ecfd3ca9ee 100644 --- a/doc/README.commands.spl +++ b/doc/README.commands.spl @@ -17,14 +17,14 @@ TYPICAL CALL on OMAP3: nandecc hw -nand read 0x82000000 0x280000 0x400000 /* Read kernel image from NAND*/ -spl export atags /* export ATAGS */ +nand read 0x82000000 0x280000 0x400000 /* Read kernel image from NAND*/ +spl export atags /* export ATAGS */ nand erase 0x680000 0x20000 /* erase - one page */ nand write 0x80000100 0x680000 0x20000 /* write the image - one page */ call with FDT: nandecc hw -nand read 0x82000000 0x280000 0x400000 /* Read kernel image from NAND*/ +nand read 0x82000000 0x280000 0x400000 /* Read kernel image from NAND*/ tftpboot 0x80000100 devkit8000.dtb /* Read fdt */ spl export fdt 0x82000000 - 0x80000100 /* export FDT */ nand erase 0x680000 0x20000 /* erase - one page */ diff --git a/doc/README.dfutftp b/doc/README.dfutftp index a3341bbb61..1206507911 100644 --- a/doc/README.dfutftp +++ b/doc/README.dfutftp @@ -88,7 +88,6 @@ for pure DFU USB transfer. possible to set large enough default buffer (8 MiB @ BBB) - FIT image format for download ----------------------------- @@ -110,7 +109,6 @@ should look like where "u-boot.bin" is the DFU entity name to be stored. - To do ----- diff --git a/doc/README.distro b/doc/README.distro index c4f041ca71..fa8cec1102 100644 --- a/doc/README.distro +++ b/doc/README.distro @@ -233,7 +233,7 @@ fdtfile: the DTB with a different DTB. fdtfile will automatically be set for you if it matches the format ${soc}-${board}.dtb which covers most 32 bit use cases. AArch64 generally does not match as the Linux kernel put the dtb files under - SoC vendor directories. + SoC vendor directories. ramdisk_addr_r: diff --git a/doc/README.falcon b/doc/README.falcon index 713d7063a1..88218d35b9 100644 --- a/doc/README.falcon +++ b/doc/README.falcon @@ -69,7 +69,7 @@ CONFIG_CMD_SPL_NAND_OFS Offset in NAND where the parameters area was saved. CONFIG_CMD_SPL_NOR_OFS Offset in NOR where the parameters area was saved. -CONFIG_CMD_SPL_WRITE_SIZE Size of the parameters area to be copied +CONFIG_CMD_SPL_WRITE_SIZE Size of the parameters area to be copied CONFIG_SPL_OS_BOOT Activate Falcon Mode. @@ -89,7 +89,7 @@ Environment variables A board may chose to look at the environment for decisions about falcon mode. In this case the following variables may be supported: -boot_os : Set to yes/Yes/true/True/1 to enable booting to OS, +boot_os : Set to yes/Yes/true/True/1 to enable booting to OS, any other value to fall back to U-Boot (including unset) falcon_args_file : Filename to load as the 'args' portion of falcon mode diff --git a/doc/README.odroid b/doc/README.odroid index bc77ae3175..1090a0ea14 100644 --- a/doc/README.odroid +++ b/doc/README.odroid @@ -296,8 +296,8 @@ Odroid # usb part 0 Partition Map for USB device 0 -- Partition Type: DOS Part Start Sector Num Sectors UUID Type - 1 3072 263168 000c4046-01 06 - 2 266240 13457408 000c4046-02 83 + 1 3072 263168 000c4046-01 06 + 2 266240 13457408 000c4046-02 83 Odroid # ls usb 0:2 /boot <DIR> 4096 . diff --git a/doc/README.pcap b/doc/README.pcap index 97b3e55fd8..8e30b93c66 100644 --- a/doc/README.pcap +++ b/doc/README.pcap @@ -59,4 +59,3 @@ PCAP status: # pcap stop # tftpput 0xffffffff80100000 $pcapsize 10.0.2.2:capture.pcap - diff --git a/doc/SPL/README.am335x-network b/doc/SPL/README.am335x-network index e05270673d..9599729d8f 100644 --- a/doc/SPL/README.am335x-network +++ b/doc/SPL/README.am335x-network @@ -7,7 +7,7 @@ NAND and bricked (empty) board with only a network cable. I. Building the required images 1. You have to enable generic SPL configuration options (see -doc/README.SPL) as well as CONFIG_SPL_NET_SUPPORT, +doc/README.SPL) as well as CONFIG_SPL_NET, CONFIG_SPL_ETH, CONFIG_SPL_LIBGENERIC_SUPPORT and CONFIG_SPL_LIBCOMMON_SUPPORT in your board configuration file to build SPL with support for booting over the network. Also you have to enable diff --git a/doc/board/AndesTech/adp-ag101p.rst b/doc/board/AndesTech/adp-ag101p.rst index 879eba0294..f867eeae3e 100644 --- a/doc/board/AndesTech/adp-ag101p.rst +++ b/doc/board/AndesTech/adp-ag101p.rst @@ -23,8 +23,8 @@ CONFIG_MEM_REMAP: CONFIG_SKIP_LOWLEVEL_INIT: If you want to boot this system from SPI ROM and bypass e-bios (the - other boot loader on ROM). You should undefine CONFIG_SKIP_LOWLEVEL_INIT - in "include/configs/adp-ag101p.h". + other boot loader on ROM). You should enable CONFIG_SKIP_LOWLEVEL_INIT + when running menuconfig or similar. Build and boot steps -------------------- diff --git a/doc/board/index.rst b/doc/board/index.rst index 33087074fa..aa397ab942 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -22,10 +22,12 @@ Board-specific doc openpiton/index qualcomm/index rockchip/index + siemens/index sifive/index sipeed/index socionext/index st/index + ste/index tbs/index ti/index toradex/index diff --git a/doc/board/siemens/index.rst b/doc/board/siemens/index.rst new file mode 100644 index 0000000000..082936ea7e --- /dev/null +++ b/doc/board/siemens/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Siemens +======= + +.. toctree:: + :maxdepth: 2 + + iot2050 diff --git a/doc/board/siemens/iot2050.rst b/doc/board/siemens/iot2050.rst new file mode 100644 index 0000000000..592c59be03 --- /dev/null +++ b/doc/board/siemens/iot2050.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Jan Kiszka <jan.kiszka@siemens.com> + +SIMATIC IOT2050 BASIC and ADVANCED +================================== + +The SIMATIC IOT2050 is an open industrial IoT gateway that is using the TI +AM6528 GP (Basic variant) or the AM6548 HS (Advanced variant). The Advanced +variant is prepared for secure boot. + +The IOT2050 starts only from OSPI. It loads a Siemens-provided bootloader +called SE-Boot for the MCU domain (R5F cores), then hands over to ATF and +OP-TEE, before booting U-Boot on the A53 cores. This describes how to build all +open artifacts into a flashable image for the OSPI flash. The flash image will +work on both variants. + +Dependencies +------------ + +ATF: Upstream release 2.4 or newer +OP-TEE: Upstream release 3.10.0 or newer + +Binary dependencies can be found in +https://github.com/siemens/meta-iot2050/tree/master/recipes-bsp/u-boot/files/prebuild. +The following binaries from that source need to be present in the build folder: + + - tiboot3.bin + - sysfw.itb + - sysfw.itb_HS + - sysfw_sr2.itb + - sysfw_sr2.itb_HS + +Building +-------- + +Make sure that CROSS_COMPILE is set appropriately: + +.. code-block:: text + + $ export CROSS_COMPILE=aarch64-linux-gnu- + +ATF: + +.. code-block:: text + + $ make PLAT=k3 SPD=opteed K3_USART=1 + +OP-TEE: + +.. code-block:: text + + $ make PLATFORM=k3-am65x CFG_ARM64_core=y CFG_TEE_CORE_LOG_LEVEL=2 CFG_CONSOLE_UART=1 + +U-Boot: + +.. code-block:: text + + $ export ATF=/path/to/bl31.bin + $ export TEE=/path/to/tee-pager_v2.bin + $ make iot2050_defconfig + $ make + +Flashing +-------- + +Via U-Boot: + +.. code-block:: text + + IOT2050> sf probe + IOT2050> load mmc 0:1 $loadaddr /path/to/flash.bin + IOT2050> sf update $loadaddr 0x0 $filesize + +Via external programmer Dediprog SF100 or SF600: + +.. code-block:: text + + $ dpcmd --vcc 2 -v -u flash.bin diff --git a/doc/board/ste/index.rst b/doc/board/ste/index.rst new file mode 100644 index 0000000000..bef520ce63 --- /dev/null +++ b/doc/board/ste/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +ST-Ericsson +=========== + +.. toctree:: + :maxdepth: 2 + + stemmy diff --git a/doc/board/ste/stemmy.rst b/doc/board/ste/stemmy.rst new file mode 100644 index 0000000000..6d77fe9c83 --- /dev/null +++ b/doc/board/ste/stemmy.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Stephan Gerhold <stephan@gerhold.net> + +ST-Ericsson U8500 Samsung "stemmy" board +======================================== + +The "stemmy" board supports Samsung smartphones released with +the ST-Ericsson NovaThor U8500 SoC, e.g. + + +---------------------------+----------+--------------+----------------+ + | Device | Model | Codename | U-Boot | + +===========================+==========+==============+================+ + | Samsung Galaxy Ace 2 | GT-I8160 | codina | ``u-boot.bin`` | + +---------------------------+----------+--------------+----------------+ + | Samsung Galaxy Amp | SGH-I407 | kyle | ``u-boot.img`` | + +---------------------------+----------+--------------+----------------+ + | Samsung Galaxy Beam | GT-I8530 | gavini | ``u-boot.bin`` | + +---------------------------+----------+--------------+----------------+ + | Samsung Galaxy Exhibit | SGH-T599 | codina (TMO) | ``u-boot.bin`` | + +---------------------------+----------+--------------+----------------+ + | Samsung Galaxy S Advance | GT-I9070 | janice | ``u-boot.bin`` | + +---------------------------+----------+--------------+----------------+ + | Samsung Galaxy S III mini | GT-I8190 | golden | ``u-boot.img`` | + +---------------------------+----------+--------------+----------------+ + | Samsung Galaxy Xcover 2 | GT-S7710 | skomer | ``u-boot.img`` | + +---------------------------+----------+--------------+----------------+ + +At the moment, U-Boot is intended to be chain-loaded from +the original Samsung bootloader, not replacing it entirely. + +Installation +------------ +First, setup ``CROSS_COMPILE`` for ARMv7. Then, build U-Boot for ``stemmy``:: + + $ export CROSS_COMPILE=arm-none-eabi- + $ make stemmy_defconfig + $ make + +This will build ``u-boot.bin`` in the configured output directory. + +For newer devices (check ``u-boot.img`` in the table above), the U-Boot binary +has to be packed into an Android boot image. Devices with ``u-boot.bin`` boot +the raw U-Boot binary from the boot partition. You can build the Android boot +image with ``mkbootimg``, e.g. from from android-7.1.2_r37_:: + + $ mkbootimg \ + --kernel=u-boot.bin \ + --base=0x00000000 \ + --kernel_offset=0x00100000 \ + --ramdisk_offset=0x02000000 \ + --tags_offset=0x00000100 \ + --output=u-boot.img + +.. _android-7.1.2_r37: https://android.googlesource.com/platform/system/core/+/refs/tags/android-7.1.2_r37/mkbootimg/mkbootimg + +To flash the U-Boot binary, enter the Samsung download mode +(press Power + Home + Volume Down). Use Heimdall_ to flash the U-Boot image to +the Android boot partition:: + + $ heimdall flash --Kernel u-boot.(bin|img) + +If this is not working but there are messages like ``Android recovery image`` in +the UART console, you can try flashing to the recovery partition instead:: + + $ heimdall flash --Kernel2 u-boot.(bin|img) + +.. _Heimdall: https://gitlab.com/BenjaminDobell/Heimdall + +After a reboot the U-Boot prompt should appear via UART. Unless interrupted it +automatically boots to USB Fastboot mode where Android boot images can be booted +via ``fastboot boot boot.img``. It is mainly intended to boot mainline Linux, +but booting original Samsung Android boot images is also supported (e.g. for +charging). + +UART +---- +UART is available through the micro USB port, similar to the Carkit standard. +With a ~619kOhm resistor between ID and GND, 1.8V RX/TX is available at D+/D-. + +.. note:: + Make sure to connect the UART cable **before** turning on the phone. diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst new file mode 100644 index 0000000000..a90f32da7a --- /dev/null +++ b/doc/board/ti/am335x_evm.rst @@ -0,0 +1,200 @@ +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause +.. sectionauthor:: Tom Rini <trini@konsulko.com> + +Summary +======= + +This document covers various features of the `am335x_evm` default +configuration, some of the related defconfigs, and how to enable hardware +features not present by default in the defconfigs. + +Hardware +-------- + +The binary produced by this board supports, based on parsing of the EEPROM +documented in TI's reference designs: +* AM335x GP EVM +* AM335x EVM SK +* The Beaglebone family of designs + +Customization +------------- + +Given that all of the above boards are reference platforms (and the +Beaglebone platforms are OSHA), it is likely that this platform code and +configuration will be used as the basis of a custom platform. It is +worth noting that aside from things such as NAND or MMC only being +required if a custom platform makes use of these blocks, the following +are required, depending on design: + +* GPIO is only required if DDR3 power is controlled in a way similar to EVM SK +* SPI is only required for SPI flash, or exposing the SPI bus. + +The following blocks are required: + +* I2C, to talk with the PMIC and ensure that we do not run afoul of + errata 1.0.24. + +When removing options as part of customization, note that you will likely need +to look at both `include/configs/am335x_evm.h`, +`include/configs/ti_am335x_common.h` and `include/configs/am335x_evm.h` as the +migration to Kconfig is not yet complete. + +NAND +---- + +The AM335x GP EVM ships with a 256MiB NAND available in most profiles. In +this example to program the NAND we assume that an SD card has been +inserted with the files to write in the first SD slot and that mtdparts +have been configured correctly for the board. All images are first loaded +into memory, then written to NAND. + +Step-1: Building u-boot for NAND boot + Set following CONFIGxx options for NAND device. + CONFIG_SYS_NAND_PAGE_SIZE number of main bytes in NAND page + CONFIG_SYS_NAND_OOBSIZE number of OOB bytes in NAND page + CONFIG_SYS_NAND_BLOCK_SIZE number of bytes in NAND erase-block + CONFIG_SYS_NAND_ECCPOS ECC map for NAND page + CONFIG_NAND_OMAP_ECCSCHEME (refer doc/README.nand) + +Step-2: Flashing NAND via MMC/SD + +.. code-block:: text + + # select BOOTSEL to MMC/SD boot and boot from MMC/SD card + U-Boot # mmc rescan + # erase flash + U-Boot # nand erase.chip + U-Boot # env default -f -a + U-Boot # saveenv + # flash MLO. Redundant copies of MLO are kept for failsafe + U-Boot # load mmc 0 0x82000000 MLO + U-Boot # nand write 0x82000000 0x00000 0x20000 + U-Boot # nand write 0x82000000 0x20000 0x20000 + U-Boot # nand write 0x82000000 0x40000 0x20000 + U-Boot # nand write 0x82000000 0x60000 0x20000 + # flash u-boot.img + U-Boot # load mmc 0 0x82000000 u-boot.img + U-Boot # nand write 0x82000000 0x80000 0x60000 + # flash kernel image + U-Boot # load mmc 0 0x82000000 uImage + U-Boot # nand write 0x82000000 ${nandsrcaddr} ${nandimgsize} + # flash filesystem image + U-Boot # load mmc 0 0x82000000 filesystem.img + U-Boot # nand write 0x82000000 ${loadaddress} 0x300000 + +Step-3: Set BOOTSEL pin to select NAND boot, and POR the device. + The device should boot from images flashed on NAND device. + + +Falcon Mode +----------- + +The default build includes "Falcon Mode" (see doc/README.falcon) via NAND, +eMMC (or raw SD cards) and FAT SD cards. Our default behavior currently is +to read a 'c' on the console while in SPL at any point prior to loading the +OS payload (so as soon as possible) to opt to booting full U-Boot. Also +note that while one can program Falcon Mode "in place" great care needs to +be taken by the user to not 'brick' their setup. As these are all eval +boards with multiple boot methods, recovery should not be an issue in this +worst-case however. + +Falcon Mode: eMMC +----------------- + +The recommended layout in this case is: + +.. code-block:: text + + MMC BLOCKS |--------------------------------| LOCATION IN BYTES + 0x0000 - 0x007F : MBR or GPT table : 0x000000 - 0x020000 + 0x0080 - 0x00FF : ARGS or FDT file : 0x010000 - 0x020000 + 0x0100 - 0x01FF : SPL.backup1 (first copy used) : 0x020000 - 0x040000 + 0x0200 - 0x02FF : SPL.backup2 (second copy used) : 0x040000 - 0x060000 + 0x0300 - 0x06FF : U-Boot : 0x060000 - 0x0e0000 + 0x0700 - 0x08FF : U-Boot Env + Redundant : 0x0e0000 - 0x120000 + 0x0900 - 0x28FF : Kernel : 0x120000 - 0x520000 + +Note that when we run 'spl export' it will prepare to boot the kernel. +This includes relocation of the uImage from where we loaded it to the entry +point defined in the header. As these locations overlap by default, it +would leave us with an image that if written to MMC will not boot, so +instead of using the loadaddr variable we use 0x81000000 in the following +example. In this example we are loading from the network, for simplicity, +and assume a valid partition table already exists and 'mmc dev' has already +been run to select the correct device. Also note that if you previously +had a FAT partition (such as on a Beaglebone Black) it is not enough to +write garbage into the area, you must delete it from the partition table +first. + +.. code-block:: text + + # Ensure we are able to talk with this mmc device + U-Boot # mmc rescan + U-Boot # tftp 81000000 am335x/MLO + # Write to two of the backup locations ROM uses + U-Boot # mmc write 81000000 100 100 + U-Boot # mmc write 81000000 200 100 + # Write U-Boot to the location set in the config + U-Boot # tftp 81000000 am335x/u-boot.img + U-Boot # mmc write 81000000 300 400 + # Load kernel and device tree into memory, perform export + U-Boot # tftp 81000000 am335x/uImage + U-Boot # run findfdt + U-Boot # tftp ${fdtaddr} am335x/${fdtfile} + U-Boot # run mmcargs + U-Boot # spl export fdt 81000000 - ${fdtaddr} + # Write the updated device tree to MMC + U-Boot # mmc write ${fdtaddr} 80 80 + # Write the uImage to MMC + U-Boot # mmc write 81000000 900 2000 + +Falcon Mode: FAT SD cards +------------------------- + +In this case the additional file is written to the filesystem. In this +example we assume that the uImage and device tree to be used are already on +the FAT filesystem (only the uImage MUST be for this to function +afterwards) along with a Falcon Mode aware MLO and the FAT partition has +already been created and marked bootable: + +.. code-block:: text + + U-Boot # mmc rescan + # Load kernel and device tree into memory, perform export + U-Boot # load mmc 0:1 ${loadaddr} uImage + U-Boot # run findfdt + U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile} + U-Boot # run mmcargs + U-Boot # spl export fdt ${loadaddr} - ${fdtaddr} + +This will print a number of lines and then end with something like: + +.. code-block:: text + + Using Device Tree in place at 80f80000, end 80f85928 + Using Device Tree in place at 80f80000, end 80f88928 + +So then you: + +.. code-block:: text + + U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928 + +Falcon Mode: NAND +----------------- + +In this case the additional data is written to another partition of the +NAND. In this example we assume that the uImage and device tree to be are +already located on the NAND somewhere (such as filesystem or mtd partition) +along with a Falcon Mode aware MLO written to the correct locations for +booting and mtdparts have been configured correctly for the board: + +.. code-block:: text + + U-Boot # nand read ${loadaddr} kernel + U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb + U-Boot # run nandargs + 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 diff --git a/doc/board/ti/index.rst b/doc/board/ti/index.rst index c0da04b109..014a097178 100644 --- a/doc/board/ti/index.rst +++ b/doc/board/ti/index.rst @@ -6,4 +6,5 @@ Texas Instruments .. toctree:: :maxdepth: 2 + am335x_evm j721e_evm diff --git a/doc/develop/checkpatch.rst b/doc/develop/checkpatch.rst new file mode 100644 index 0000000000..51fed1bd72 --- /dev/null +++ b/doc/develop/checkpatch.rst @@ -0,0 +1,755 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +========== +Checkpatch +========== + +Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial +style violations in patches and optionally corrects them. Checkpatch can +also be run on file contexts and without the kernel tree. + +Checkpatch is not always right. Your judgement takes precedence over checkpatch +messages. If your code looks better with the violations, then its probably +best left alone. + + +Options +======= + +This section will describe the options checkpatch can be run with. + +Usage:: + + ./scripts/checkpatch.pl [OPTION]... [FILE]... + +Available options: + + - -q, --quiet + + Enable quiet mode. + + - -v, --verbose + Enable verbose mode. Additional verbose test descriptions are output + so as to provide information on why that particular message is shown. + + - --no-tree + + Run checkpatch without the kernel tree. + + - --no-signoff + + Disable the 'Signed-off-by' line check. The sign-off is a simple line at + the end of the explanation for the patch, which certifies that you wrote it + or otherwise have the right to pass it on as an open-source patch. + + Example:: + + Signed-off-by: Random J Developer <random@developer.example.org> + + Setting this flag effectively stops a message for a missing signed-off-by + line in a patch context. + + - --patch + + Treat FILE as a patch. This is the default option and need not be + explicitly specified. + + - --emacs + + Set output to emacs compile window format. This allows emacs users to jump + from the error in the compile window directly to the offending line in the + patch. + + - --terse + + Output only one line per report. + + - --showfile + + Show the diffed file position instead of the input file position. + + - -g, --git + + Treat FILE as a single commit or a git revision range. + + Single commit with: + + - <rev> + - <rev>^ + - <rev>~n + + Multiple commits with: + + - <rev1>..<rev2> + - <rev1>...<rev2> + - <rev>-<count> + + - -f, --file + + Treat FILE as a regular source file. This option must be used when running + checkpatch on source files in the kernel. + + - --subjective, --strict + + Enable stricter tests in checkpatch. By default the tests emitted as CHECK + do not activate by default. Use this flag to activate the CHECK tests. + + - --list-types + + Every message emitted by checkpatch has an associated TYPE. Add this flag + to display all the types in checkpatch. + + Note that when this flag is active, checkpatch does not read the input FILE, + and no message is emitted. Only a list of types in checkpatch is output. + + - --types TYPE(,TYPE2...) + + Only display messages with the given types. + + Example:: + + ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES + + - --ignore TYPE(,TYPE2...) + + Checkpatch will not emit messages for the specified types. + + Example:: + + ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES + + - --show-types + + By default checkpatch doesn't display the type associated with the messages. + Set this flag to show the message type in the output. + + - --max-line-length=n + + Set the max line length (default 100). If a line exceeds the specified + length, a LONG_LINE message is emitted. + + + The message level is different for patch and file contexts. For patches, + a WARNING is emitted. While a milder CHECK is emitted for files. So for + file contexts, the --strict flag must also be enabled. + + - --min-conf-desc-length=n + + Set the Kconfig entry minimum description length, if shorter, warn. + + - --tab-size=n + + Set the number of spaces for tab (default 8). + + - --root=PATH + + PATH to the kernel tree root. + + This option must be specified when invoking checkpatch from outside + the kernel root. + + - --no-summary + + Suppress the per file summary. + + - --mailback + + Only produce a report in case of Warnings or Errors. Milder Checks are + excluded from this. + + - --summary-file + + Include the filename in summary. + + - --debug KEY=[0|1] + + Turn on/off debugging of KEY, where KEY is one of 'values', 'possible', + 'type', and 'attr' (default is all off). + + - --fix + + This is an EXPERIMENTAL feature. If correctable errors exists, a file + <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the + automatically fixable errors corrected. + + - --fix-inplace + + EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes. + + DO NOT USE this flag unless you are absolutely sure and you have a backup + in place. + + - --ignore-perl-version + + Override checking of perl version. Runtime errors maybe encountered after + enabling this flag if the perl version does not meet the minimum specified. + + - --codespell + + Use the codespell dictionary for checking spelling errors. + + - --codespellfile + + Use the specified codespell file. + Default is '/usr/share/codespell/dictionary.txt'. + + - --typedefsfile + + Read additional types from this file. + + - --color[=WHEN] + + Use colors 'always', 'never', or only when output is a terminal ('auto'). + Default is 'auto'. + + - --kconfig-prefix=WORD + + Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`). + + - -h, --help, --version + + Display the help text. + +Message Levels +============== + +Messages in checkpatch are divided into three levels. The levels of messages +in checkpatch denote the severity of the error. They are: + + - ERROR + + This is the most strict level. Messages of type ERROR must be taken + seriously as they denote things that are very likely to be wrong. + + - WARNING + + This is the next stricter level. Messages of type WARNING requires a + more careful review. But it is milder than an ERROR. + + - CHECK + + This is the mildest level. These are things which may require some thought. + +Type Descriptions +================= + +This section contains a description of all the message types in checkpatch. + +.. Types in this section are also parsed by checkpatch. +.. The types are grouped into subsections based on use. + + +Allocation style +---------------- + + **ALLOC_ARRAY_ARGS** + The first argument for kcalloc or kmalloc_array should be the + number of elements. sizeof() as the first argument is generally + wrong. + See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html + + **ALLOC_SIZEOF_STRUCT** + The allocation style is bad. In general for family of + allocation functions using sizeof() to get memory size, + constructs like:: + + p = alloc(sizeof(struct foo), ...) + + should be:: + + p = alloc(sizeof(*p), ...) + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory + + **ALLOC_WITH_MULTIPLY** + Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a + sizeof multiply. + See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html + + +API usage +--------- + + **ARCH_DEFINES** + Architecture specific defines should be avoided wherever + possible. + + **ARCH_INCLUDE_LINUX** + Whenever asm/file.h is included and linux/file.h exists, a + conversion can be made when linux/file.h includes asm/file.h. + However this is not always the case (See signal.h). + This message type is emitted only for includes from arch/. + + **AVOID_BUG** + BUG() or BUG_ON() should be avoided totally. + Use WARN() and WARN_ON() instead, and handle the "impossible" + error condition as gracefully as possible. + See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on + + **CONSIDER_KSTRTO** + The simple_strtol(), simple_strtoll(), simple_strtoul(), and + simple_strtoull() functions explicitly ignore overflows, which + may lead to unexpected results in callers. The respective kstrtol(), + kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the + correct replacements. + See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull + + **LOCKDEP** + The lockdep_no_validate class was added as a temporary measure to + prevent warnings on conversion of device->sem to device->mutex. + It should not be used for any other purpose. + See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/ + + **MALFORMED_INCLUDE** + The #include statement has a malformed path. This has happened + because the author has included a double slash "//" in the pathname + accidentally. + + **USE_LOCKDEP** + lockdep_assert_held() annotations should be preferred over + assertions based on spin_is_locked() + See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations + + **UAPI_INCLUDE** + No #include statements in include/uapi should use a uapi/ path. + + +Comment style +------------- + + **BLOCK_COMMENT_STYLE** + The comment style is incorrect. The preferred style for multi- + line comments is:: + + /* + * This is the preferred style + * for multi line comments. + */ + + The networking comment style is a bit different, with the first line + not empty like the former:: + + /* This is the preferred comment style + * for files in net/ and drivers/net/ + */ + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting + + **C99_COMMENTS** + C99 style single line comments (//) should not be used. + Prefer the block comment style instead. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting + + +Commit message +-------------- + + **BAD_SIGN_OFF** + The signed-off-by line does not fall in line with the standards + specified by the community. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1 + + **BAD_STABLE_ADDRESS_STYLE** + The email format for stable is incorrect. + Some valid options for stable address are:: + + 1. stable@vger.kernel.org + 2. stable@kernel.org + + For adding version info, the following comment style should be used:: + + stable@vger.kernel.org # version info + + **COMMIT_COMMENT_SYMBOL** + Commit log lines starting with a '#' are ignored by git as + comments. To solve this problem addition of a single space + infront of the log line is enough. + + **COMMIT_MESSAGE** + The patch is missing a commit description. A brief + description of the changes made by the patch should be added. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes + + **MISSING_SIGN_OFF** + The patch is missing a Signed-off-by line. A signed-off-by + line should be added according to Developer's certificate of + Origin. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + + **NO_AUTHOR_SIGN_OFF** + The author of the patch has not signed off the patch. It is + required that a simple sign off line should be present at the + end of explanation of the patch to denote that the author has + written it or otherwise has the rights to pass it on as an open + source patch. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + + **DIFF_IN_COMMIT_MSG** + Avoid having diff content in commit message. + This causes problems when one tries to apply a file containing both + the changelog and the diff because patch(1) tries to apply the diff + which it found in the changelog. + See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/ + + **GERRIT_CHANGE_ID** + To be picked up by gerrit, the footer of the commit message might + have a Change-Id like:: + + Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b + Signed-off-by: A. U. Thor <author@example.com> + + The Change-Id line must be removed before submitting. + + **GIT_COMMIT_ID** + The proper way to reference a commit id is: + commit <12+ chars of sha1> ("<title line>") + + An example may be:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes + + +Comparison style +---------------- + + **ASSIGN_IN_IF** + Do not use assignments in if condition. + Example:: + + if ((foo = bar(...)) < BAZ) { + + should be written as:: + + foo = bar(...); + if (foo < BAZ) { + + **BOOL_COMPARISON** + Comparisons of A to true and false are better written + as A and !A. + See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/ + + **COMPARISON_TO_NULL** + Comparisons to NULL in the form (foo == NULL) or (foo != NULL) + are better written as (!foo) and (foo). + + **CONSTANT_COMPARISON** + Comparisons with a constant or upper case identifier on the left + side of the test should be avoided. + + +Macros, Attributes and Symbols +------------------------------ + + **ARRAY_SIZE** + The ARRAY_SIZE(foo) macro should be preferred over + sizeof(foo)/sizeof(foo[0]) for finding number of elements in an + array. + + The macro is defined in include/linux/kernel.h:: + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + + **AVOID_EXTERNS** + Function prototypes don't need to be declared extern in .h + files. It's assumed by the compiler and is unnecessary. + + **AVOID_L_PREFIX** + Local symbol names that are prefixed with `.L` should be avoided, + as this has special meaning for the assembler; a symbol entry will + not be emitted into the symbol table. This can prevent `objtool` + from generating correct unwind info. + + Symbols with STB_LOCAL binding may still be used, and `.L` prefixed + local symbol names are still generally usable within a function, + but `.L` prefixed local symbol names should not be used to denote + the beginning or end of code regions via + `SYM_CODE_START_LOCAL`/`SYM_CODE_END` + + **BIT_MACRO** + Defines like: 1 << <digit> could be BIT(digit). + The BIT() macro is defined in include/linux/bitops.h:: + + #define BIT(nr) (1UL << (nr)) + + **CONST_READ_MOSTLY** + When a variable is tagged with the __read_mostly annotation, it is a + signal to the compiler that accesses to the variable will be mostly + reads and rarely(but NOT never) a write. + + const __read_mostly does not make any sense as const data is already + read-only. The __read_mostly annotation thus should be removed. + + **DATE_TIME** + It is generally desirable that building the same source code with + the same set of tools is reproducible, i.e. the output is always + exactly the same. + + The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, + and enables warnings if they are used as they can lead to + non-deterministic builds. + See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps + + **DEFINE_ARCH_HAS** + The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong. + + For big conceptual features use Kconfig symbols instead. And for + smaller things where we have compatibility fallback functions but + want architectures able to override them with optimized ones, we + should either use weak functions (appropriate for some cases), or + the symbol that protects them should be the same symbol we use. + See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/ + + **INIT_ATTRIBUTE** + Const init definitions should use __initconst instead of + __initdata. + + Similarly init definitions without const require a separate + use of const. + + **INLINE_LOCATION** + The inline keyword should sit between storage class and type. + + For example, the following segment:: + + inline static int example_function(void) + { + ... + } + + should be:: + + static inline int example_function(void) + { + ... + } + + **MULTISTATEMENT_MACRO_USE_DO_WHILE** + Macros with multiple statements should be enclosed in a + do - while block. Same should also be the case for macros + starting with `if` to avoid logic defects:: + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl + + **WEAK_DECLARATION** + Using weak declarations like __attribute__((weak)) or __weak + can have unintended link defects. Avoid using them. + + +Functions and Variables +----------------------- + + **CAMELCASE** + Avoid CamelCase Identifiers. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming + + **FUNCTION_WITHOUT_ARGS** + Function declarations without arguments like:: + + int foo() + + should be:: + + int foo(void) + + **GLOBAL_INITIALISERS** + Global variables should not be initialized explicitly to + 0 (or NULL, false, etc.). Your compiler (or rather your + loader, which is responsible for zeroing out the relevant + sections) automatically does it for you. + + **INITIALISED_STATIC** + Static variables should not be initialized explicitly to zero. + Your compiler (or rather your loader) automatically does + it for you. + + **RETURN_PARENTHESES** + return is not a function and as such doesn't need parentheses:: + + return (bar); + + can simply be:: + + return bar; + + +Spacing and Brackets +-------------------- + + **ASSIGNMENT_CONTINUATIONS** + Assignment operators should not be written at the start of a + line but should follow the operand at the previous line. + + **BRACES** + The placement of braces is stylistically incorrect. + The preferred way is to put the opening brace last on the line, + and put the closing brace first:: + + if (x is true) { + we do y + } + + This applies for all non-functional blocks. + However, there is one special case, namely functions: they have the + opening brace at the beginning of the next line, thus:: + + int function(int x) + { + body of function + } + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **BRACKET_SPACE** + Whitespace before opening bracket '[' is prohibited. + There are some exceptions: + + 1. With a type on the left:: + + ;int [] a; + + 2. At the beginning of a line for slice initialisers:: + + [0...10] = 5, + + 3. Inside a curly brace:: + + = { [0...10] = 5 } + + **CODE_INDENT** + Code indent should use tabs instead of spaces. + Outside of comments, documentation and Kconfig, + spaces are never used for indentation. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation + + **CONCATENATED_STRING** + Concatenated elements should have a space in between. + Example:: + + printk(KERN_INFO"bar"); + + should be:: + + printk(KERN_INFO "bar"); + + **ELSE_AFTER_BRACE** + `else {` should follow the closing block `}` on the same line. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **LINE_SPACING** + Vertical space is wasted given the limited number of lines an + editor window can display when multiple blank lines are used. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **OPEN_BRACE** + The opening brace should be following the function definitions on the + next line. For any non-functional block it should be on the same line + as the last construct. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **POINTER_LOCATION** + When using pointer data or a function that returns a pointer type, + the preferred use of * is adjacent to the data name or function name + and not adjacent to the type name. + Examples:: + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **SPACING** + Whitespace style used in the kernel sources is described in kernel docs. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **SWITCH_CASE_INDENT_LEVEL** + switch should be at the same indent as case. + Example:: + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation + + **TRAILING_WHITESPACE** + Trailing whitespace should always be removed. + Some editors highlight the trailing whitespace and cause visual + distractions when editing files. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **WHILE_AFTER_BRACE** + while should follow the closing bracket on the same line:: + + do { + ... + } while(something); + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + +Others +------ + + **CONFIG_DESCRIPTION** + Kconfig symbols should have a help text which fully describes + it. + + **CORRUPTED_PATCH** + The patch seems to be corrupted or lines are wrapped. + Please regenerate the patch file before sending it to the maintainer. + + **DOS_LINE_ENDINGS** + For DOS-formatted patches, there are extra ^M symbols at the end of + the line. These should be removed. + + **EXECUTE_PERMISSIONS** + There is no reason for source files to be executable. The executable + bit can be removed safely. + + **NON_OCTAL_PERMISSIONS** + Permission bits should use 4 digit octal permissions (like 0700 or 0444). + Avoid using any other base like decimal. + + **NOT_UNIFIED_DIFF** + The patch file does not appear to be in unified-diff format. Please + regenerate the patch file before sending it to the maintainer. + + **PRINTF_0XDECIMAL** + Prefixing 0x with decimal output is defective and should be corrected. + + **TRAILING_STATEMENTS** + Trailing statements (for example after any conditional) should be + on the next line. + Like:: + + if (x == y) break; + + should be:: + + if (x == y) + break; diff --git a/doc/develop/driver-model/of-plat.rst b/doc/develop/driver-model/of-plat.rst index 8a8eaed4c1..237af38ad4 100644 --- a/doc/develop/driver-model/of-plat.rst +++ b/doc/develop/driver-model/of-plat.rst @@ -215,16 +215,16 @@ For example: static int mmc_of_to_plat(struct udevice *dev) { - #if !CONFIG_IS_ENABLED(OF_PLATDATA) + if (CONFIG_IS_ENABLED(OF_REAL)) { /* Decode the devicetree data */ struct mmc_plat *plat = dev_get_plat(dev); const void *blob = gd->fdt_blob; int node = dev_of_offset(dev); plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); - #endif + } - return 0; + return 0; } static int mmc_probe(struct udevice *dev) @@ -600,6 +600,11 @@ as a macro included in the driver definition:: Problems -------- +This section shows some common problems and how to fix them. + +Driver not found +~~~~~~~~~~~~~~~~ + In some cases you will you see something like this:: WARNING: the driver rockchip_rk3188_grf was not found in the driver list @@ -633,8 +638,11 @@ the devicetree. For example, if the devicetree has:: then dtoc looks at the first compatible string ("rockchip,rk3188-grf"), converts that to a C identifier (rockchip_rk3188_grf) and then looks for that. +Missing .compatible or Missing .id +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Various things can cause dtoc to fail to find the driver and it tries to -warn about these. For example: +warn about these. For example:: rockchip_rk3188_uart: Missing .compatible in drivers/serial/serial_rockchip.c : WARNING: the driver rockchip_rk3188_uart was not found in the driver list @@ -649,6 +657,130 @@ Checks are also made to confirm that the referenced driver has a .compatible member and a .id member. The first provides the array of compatible strings and the second provides the uclass ID. +Missing parent +~~~~~~~~~~~~~~ + +When a device is used, its parent must be present as well. If you see an error +like:: + + Node '/i2c@0/emul/emul0' requires parent node '/i2c@0/emul' but it is not in + the valid list + +it indicates that you are using a node whose parent is not present in the +devicetree. In this example, if you look at the device tree output +(e.g. fdtdump tpl/u-boot-tpl.dtb in your build directory), you may see something +like this:: + + emul { + emul0 { + compatible = "sandbox,i2c-rtc-emul"; + #emul-cells = <0x00000000>; + phandle = <0x00000003>; + }; + }; + +In this example, 'emul0' exists but its parent 'emul' has no properties. These +have been dropped by fdtgrep in an effort to reduce the devicetree size. This +indicates that the two nodes have different phase settings. Looking at the +source .dts:: + + i2c_emul: emul { + u-boot,dm-spl; + reg = <0xff>; + compatible = "sandbox,i2c-emul-parent"; + emul0: emul0 { + u-boot,dm-pre-reloc; + compatible = "sandbox,i2c-rtc-emul"; + #emul-cells = <0>; + }; + }; + +you can see that the child node 'emul0' usees 'u-boot,dm-pre-reloc', indicating +that the node is present in all SPL builds, but its parent uses 'u-boot,dm-spl' +indicating it is only present in SPL, not TPL. For a TPL build, this will fail +with the above message. The fix is to change 'emul0' to use the same +'u-boot,dm-spl' condition, so that it is not present in TPL, like its parent. + +Link errors / undefined reference +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes dtoc does not find the problem for you, but something is wrong and +you get a link error, e.g.:: + + :(.u_boot_list_2_udevice_2_spl_test5+0x0): undefined reference to + `_u_boot_list_2_driver_2_sandbox_spl_test' + /usr/bin/ld: dts/dt-uclass.o:(.u_boot_list_2_uclass_2_misc+0x8): + undefined reference to `_u_boot_list_2_uclass_driver_2_misc' + +The first one indicates that the device cannot find its driver. This means that +there is a driver 'sandbox_spl_test' but it is not compiled into the build. +Check your Kconfig settings to make sure it is. If you don't want that in the +build, adjust your phase settings, e.g. by using 'u-boot,dm-spl' in the node +to exclude it from the TPL build:: + + spl-test5 { + u-boot,dm-tpl; + compatible = "sandbox,spl-test"; + stringarray = "tpl"; + }; + +We can drop the 'u-boot,dm-tpl' line so this node won't appear in the TPL +devicetree and thus the driver won't be needed. + +The second error above indicates that the MISC uclass is needed by the driver +(since it is in the MISC uclass) but that uclass is not compiled in the build. +The fix above would fix this error too. But if you do want this uclass in the +build, check your Kconfig settings to make sure the uclass is being built +(CONFIG_MISC in this case). + +Another error that can crop up is something like:: + + spl/dts/dt-device.c:257:38: error: invalid application of ‘sizeof’ to + incomplete type ‘struct sandbox_irq_priv’ + 257 | u8 _sandbox_irq_priv_irq_sbox[sizeof(struct sandbox_irq_priv)] + | ^~~~~~ + +This indicates that `struct sandbox_irq_priv` is not defined anywhere. The +solution is to add a DM_HEADER() line, as below, so this is included in the +dt-device.c file:: + + U_BOOT_DRIVER(sandbox_irq) = { + .name = "sandbox_irq", + .id = UCLASS_IRQ, + .of_match = sandbox_irq_ids, + .ops = &sandbox_irq_ops, + .priv_auto = sizeof(struct sandbox_irq_priv), + DM_HEADER(<asm/irq.h>) + }; + +Note that there is no dependency checking on the above, so U-Boot will not +regenerate the dt-device.c file when you update the source file (here, +`irq_sandbox.c`). You need to run `make mrproper` first to get a fresh build. + +Another error that can crop up is something like:: + + spl/dts/dt-device.c:257:38: error: invalid application of ‘sizeof’ to + incomplete type ‘struct sandbox_irq_priv’ + 257 | u8 _sandbox_irq_priv_irq_sbox[sizeof(struct sandbox_irq_priv)] + | ^~~~~~ + +This indicates that `struct sandbox_irq_priv` is not defined anywhere. The +solution is to add a DM_HEADER() line, as below, so this is included in the +dt-device.c file:: + + U_BOOT_DRIVER(sandbox_irq) = { + .name = "sandbox_irq", + .id = UCLASS_IRQ, + .of_match = sandbox_irq_ids, + .ops = &sandbox_irq_ops, + .priv_auto = sizeof(struct sandbox_irq_priv), + DM_HEADER(<asm/irq.h>) + }; + +Note that there is no dependency checking on the above, so U-Boot will not +regenerate the dt-device.c file when you update the source file (here, +`irq_sandbox.c`). You need to run `make mrproper` first to get a fresh build. + Caveats ------- @@ -697,7 +829,7 @@ Internals --------- Generated files -``````````````` +~~~~~~~~~~~~~~~ When enabled, dtoc generates the following five files: @@ -738,7 +870,7 @@ spl/dt-plat.c. CONFIG options -`````````````` +~~~~~~~~~~~~~~ Several CONFIG options are used to control the behaviour of of-platdata, all available for both SPL and TPL: @@ -793,7 +925,7 @@ READ_ONLY the nodes cannot be updated, OF_PLATDATA_NO_BIND is enabled. Data structures -``````````````` +~~~~~~~~~~~~~~~ A few extra data structures are used with of-platdata: @@ -821,7 +953,7 @@ A few extra data structures are used with of-platdata: `device_get_by_ofplat_idx()`. Other changes -````````````` +~~~~~~~~~~~~~ Some other changes are made with of-platdata: diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 24056b10fd..5e064a4dac 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -56,5 +56,6 @@ Refactoring .. toctree:: :maxdepth: 1 + checkpatch coccinelle moveconfig diff --git a/doc/develop/version.rst b/doc/develop/version.rst index 066901bcd2..8f3231b761 100644 --- a/doc/develop/version.rst +++ b/doc/develop/version.rst @@ -60,15 +60,6 @@ The following are available: This is used as part of the banner string when U-Boot starts. - U_BOOT_VERSION_STRING (string #define) - U_BOOT_VERSION followed by build-time information - and CONFIG_IDENT_STRING. - - Examples:: - - U-Boot 2020.10 (Jan 06 2021 - 08:50:36 -0700) - U-Boot 2021.01-rc5-00248-g60dd854f3ba-dirty (Jan 06 2021 - 08:50:36 -0700) for spring - U_BOOT_VERSION_NUM (integer #define) Release year, e.g. 2021 for release 2021.01. Note this is an integer, not a string. @@ -77,6 +68,18 @@ The following are available: Patch number, e.g. 1 for release 2020.01. Note this is an integer, not a string. +Human readable U-Boot version string is available in header file +include/version_string.h in following variable: + + version_string (const char[]) + U_BOOT_VERSION followed by build-time information + and CONFIG_IDENT_STRING. + + Examples:: + + U-Boot 2020.10 (Jan 06 2021 - 08:50:36 -0700) + U-Boot 2021.01-rc5-00248-g60dd854f3ba-dirty (Jan 06 2021 - 08:50:36 -0700) for spring + Build date/time is also included. See the generated file include/generated/timestamp_autogenerated.h for the available fields. For example:: diff --git a/doc/device-tree-bindings/config.txt b/doc/device-tree-bindings/config.txt index 85379fbbe5..3151778b2c 100644 --- a/doc/device-tree-bindings/config.txt +++ b/doc/device-tree-bindings/config.txt @@ -2,8 +2,8 @@ The /config node (Configuration Options) ---------------------------------------- A number of run-time configuration options are provided in the /config node -of the control device tree. You can access these using fdtdec_get_config_int(), -fdtdec_get_config_bool() and fdtdec_get_config_string(). +of the control device tree. You can access these using ofnode_conf_read_int(), +ofnode_conf_read_bool() and ofnode_conf_read_str(). These options are designed to affect the operation of U-Boot at runtime. Runtime-configuration items can help avoid proliferation of different builds diff --git a/doc/device-tree-bindings/firmware/linaro,optee-tz.txt b/doc/device-tree-bindings/firmware/linaro,optee-tz.txt index d38834c67d..2d75c2b1b5 100644 --- a/doc/device-tree-bindings/firmware/linaro,optee-tz.txt +++ b/doc/device-tree-bindings/firmware/linaro,optee-tz.txt @@ -21,7 +21,6 @@ the reference implementation maintained by Linaro. in drivers/tee/optee/optee_smc.h - Example: firmware { optee { diff --git a/doc/device-tree-bindings/mailbox/k3-secure-proxy.txt b/doc/device-tree-bindings/mailbox/k3-secure-proxy.txt index f3add0d4e7..c25d7091bf 100644 --- a/doc/device-tree-bindings/mailbox/k3-secure-proxy.txt +++ b/doc/device-tree-bindings/mailbox/k3-secure-proxy.txt @@ -10,7 +10,7 @@ Secure Proxy Device Node: Required properties: -------------------- - compatible: Shall be: "ti,am654-secure-proxy" -- reg-names data - Map the data region +- reg-names data - Map the data region scfg - Map the secure configuration region rt - Map the Realtime region. - reg: Contains the register map per reg-names. diff --git a/doc/device-tree-bindings/memory-controller/k3-j721e-ddrss.txt b/doc/device-tree-bindings/memory-controller/k3-j721e-ddrss.txt index c4cf26eaa4..dd0260b394 100644 --- a/doc/device-tree-bindings/memory-controller/k3-j721e-ddrss.txt +++ b/doc/device-tree-bindings/memory-controller/k3-j721e-ddrss.txt @@ -11,7 +11,7 @@ Required properties: -------------------- - compatible: Shall be: "ti,j721e-ddrss" for j721e, j7200 "ti,am64-ddrss" for am642 -- reg-names cfg - Map the controller configuration region +- reg-names cfg - Map the controller configuration region ctrl_mmr_lp4 - Map LP4 register region in ctrl mmr - reg: Contains the register map per reg-names. - power-domains: Should contain two entries: diff --git a/doc/device-tree-bindings/memory-controllers/k3-am654-ddrss.txt b/doc/device-tree-bindings/memory-controllers/k3-am654-ddrss.txt index 4ed731c524..1e11edf7b1 100644 --- a/doc/device-tree-bindings/memory-controllers/k3-am654-ddrss.txt +++ b/doc/device-tree-bindings/memory-controllers/k3-am654-ddrss.txt @@ -14,7 +14,7 @@ DDRSS device node: Required properties: -------------------- - compatible: Shall be: "ti,am654-ddrss" -- reg-names ss - Map the sub system wrapper logic region +- reg-names ss - Map the sub system wrapper logic region ctl - Map the controller region phy - Map the PHY region - reg: Contains the register map per reg-names. diff --git a/doc/device-tree-bindings/mmc/snps,dw-mmc.txt b/doc/device-tree-bindings/mmc/snps,dw-mmc.txt index 69faefa95e..0c9e3ada5a 100644 --- a/doc/device-tree-bindings/mmc/snps,dw-mmc.txt +++ b/doc/device-tree-bindings/mmc/snps,dw-mmc.txt @@ -30,4 +30,3 @@ mmc0@f000a000 { clock-names = "biu", "ciu"; max-frequency = <25000000>; }; - diff --git a/doc/device-tree-bindings/net/altera_tse.txt b/doc/device-tree-bindings/net/altera_tse.txt index cb190df65f..96ab1d6ebc 100644 --- a/doc/device-tree-bindings/net/altera_tse.txt +++ b/doc/device-tree-bindings/net/altera_tse.txt @@ -90,7 +90,7 @@ Example: tse_sub_1_eth_tse_0: ethernet@0x1,00001000 { compatible = "altr,tse-msgdma-1.0"; - reg = <0x00000001 0x00001000 0x00000400>, + reg = <0x00000001 0x00001000 0x00000400>, <0x00000001 0x00001460 0x00000020>, <0x00000001 0x00001480 0x00000020>, <0x00000001 0x000014A0 0x00000008>, diff --git a/doc/device-tree-bindings/net/ethernet.txt b/doc/device-tree-bindings/net/ethernet.txt index cfc376bc97..648a1aee69 100644 --- a/doc/device-tree-bindings/net/ethernet.txt +++ b/doc/device-tree-bindings/net/ethernet.txt @@ -41,7 +41,17 @@ Documentation/devicetree/bindings/phy/phy-bindings.txt. * "2500base-x", * "rxaui" * "xaui" - * "10gbase-kr" (10GBASE-KR, XFI, SFI) + * "10gbase-r" (This is the IEEE 802.3 Clause 49 defined 10GBASE-R protocol + used with various different mediums. Please refer to the IEEE standard for + a definition of this. Note: 10GBASE-R is just one protocol that can be used + with XFI and SFI. XFI and SFI permit multiple protocols over a single + SERDES lane, and also defines the electrical characteristics of the signals + with a host compliance board plugged into the host XFP/SFP connector. + Therefore, XFI and SFI are not PHY interface types in their own right.) + * "10gbase-kr" (This is the IEEE 802.3 Clause 49 defined 10GBASE-R with + Clause 73 autonegotiation. Please refer to the IEEE standard for further + information. Note: due to legacy usage, some 10GBASE-R usage incorrectly + makes use of this definition). - phy-connection-type: the same as "phy-mode" property but described in the Devicetree Specification; - phy-handle: phandle, specifies a reference to a node representing a PHY diff --git a/doc/device-tree-bindings/net/fsl,mcf-dma-fec.txt b/doc/device-tree-bindings/net/fsl,mcf-dma-fec.txt index e237825bac..5c6d548cae 100644 --- a/doc/device-tree-bindings/net/fsl,mcf-dma-fec.txt +++ b/doc/device-tree-bindings/net/fsl,mcf-dma-fec.txt @@ -21,7 +21,7 @@ Example: fec0: ethernet@9000 { compatible = "fsl,mcf-dma-fec"; - reg = <0x9000 0x800>; + reg = <0x9000 0x800>; mii-base = <0>; phy-addr = <0>; timeout-loop = <5000>; diff --git a/doc/device-tree-bindings/net/fsl,mcf-fec.txt b/doc/device-tree-bindings/net/fsl,mcf-fec.txt index 39bbaa52f3..2699b5ac07 100644 --- a/doc/device-tree-bindings/net/fsl,mcf-fec.txt +++ b/doc/device-tree-bindings/net/fsl,mcf-fec.txt @@ -15,7 +15,7 @@ Example: fec0: ethernet@fc030000 { compatible = "fsl,mcf-fec"; - reg = <0xfc030000 0x400>; + reg = <0xfc030000 0x400>; mii-base = <0>; phy-addr = <0>; timeout-loop = <5000>; diff --git a/doc/device-tree-bindings/net/mdio.txt b/doc/device-tree-bindings/net/mdio.txt index 1595325050..a7d8ac5b15 100644 --- a/doc/device-tree-bindings/net/mdio.txt +++ b/doc/device-tree-bindings/net/mdio.txt @@ -33,4 +33,3 @@ requires no compatible property for probing. reg = <2>; }; }; - diff --git a/doc/device-tree-bindings/pinctrl/bcm6838-pinctrl.txt b/doc/device-tree-bindings/pinctrl/bcm6838-pinctrl.txt index 2034f05993..ace66ead5c 100644 --- a/doc/device-tree-bindings/pinctrl/bcm6838-pinctrl.txt +++ b/doc/device-tree-bindings/pinctrl/bcm6838-pinctrl.txt @@ -2,7 +2,7 @@ Required properties for the pinctrl driver: - compatible: "brcm,bcm6838-pinctrl" -- regmap: specify the gpio test port syscon +- regmap: specify the gpio test port syscon - brcm,pins-count: the number of pin - brcm,functions-count: the number of function diff --git a/doc/device-tree-bindings/pinctrl/marvell,armada-apn806-pinctrl.txt b/doc/device-tree-bindings/pinctrl/marvell,armada-apn806-pinctrl.txt index 51f2f2c79c..0d6f861445 100644 --- a/doc/device-tree-bindings/pinctrl/marvell,armada-apn806-pinctrl.txt +++ b/doc/device-tree-bindings/pinctrl/marvell,armada-apn806-pinctrl.txt @@ -3,19 +3,19 @@ ---------------------------------------------------------------------- MPP# 0x1 0x2 0x3 0x4 ---------------------------------------------------------------------- -0 SDIO_CLK - SPI0_CLK - +0 SDIO_CLK - SPI0_CLK - 1 SDIO_CMD - SPI0_MISO - -2 SDIO_D[0] - SPI0_MOSI - -3 SDIO_D[1] - SPI0_CS0n - +2 SDIO_D[0] - SPI0_MOSI - +3 SDIO_D[1] - SPI0_CS0n - 4 SDIO_D[2] - I2C0_SDA SPI0_CS1n 5 SDIO_D[3] - I2C0_SCK - 6 SDIO_DS - - - 7 SDIO_D[4] - UART1_RXD - -8 SDIO_D[5] - UART1_TXD - -9 SDIO_D[6] - SPI0_CS1n - +8 SDIO_D[5] - UART1_TXD - +9 SDIO_D[6] - SPI0_CS1n - 10 SDIO_D[7] - - - -11 - - UART0_TXD - -12 SDIO_CARD_PW_OFF SDIO_HW_RST - - +11 - - UART0_TXD - +12 SDIO_CARD_PW_OFF SDIO_HW_RST - - 13 - - - - 14 - - - - 15 - - - - diff --git a/doc/device-tree-bindings/pinctrl/marvell,mvebu-pinctrl.txt b/doc/device-tree-bindings/pinctrl/marvell,mvebu-pinctrl.txt index 1fc1bc6645..c6984ddd60 100644 --- a/doc/device-tree-bindings/pinctrl/marvell,mvebu-pinctrl.txt +++ b/doc/device-tree-bindings/pinctrl/marvell,mvebu-pinctrl.txt @@ -11,7 +11,7 @@ Required properties for the pinctrl driver: "marvell,armada-8k-cpm-pinctrl", "marvell,armada-8k-cps-pinctrl" - bank-name: A string defining the pinc controller bank name -- reg: A pair of values defining the pin controller base address +- reg: A pair of values defining the pin controller base address and the address space - pin-count: Numeric value defining the amount of multi purpose pins included in this bank diff --git a/doc/device-tree-bindings/regulator/fsl,anatop-regulator.txt b/doc/device-tree-bindings/regulator/fsl,anatop-regulator.txt index 2a60e4941b..bd272384af 100644 --- a/doc/device-tree-bindings/regulator/fsl,anatop-regulator.txt +++ b/doc/device-tree-bindings/regulator/fsl,anatop-regulator.txt @@ -8,21 +8,21 @@ Required properties: - anatop-reg-offset: u32 value representing the anatop MFD register offset. - anatop-vol-bit-shift: u32 value representing the bit shift for the register. - anatop-vol-bit-width: u32 value representing the number of bits used in the - register. + register. - anatop-min-bit-val: u32 value representing the minimum value of this - register. + register. - anatop-min-voltage: u32 value representing the minimum voltage of this - regulator. + regulator. - anatop-max-voltage: u32 value representing the maximum voltage of this - regulator. + regulator. Optional properties: - anatop-delay-reg-offset: u32 value representing the anatop MFD step time - register offset. + register offset. - anatop-delay-bit-shift: u32 value representing the bit shift for the step - time register. + time register. - anatop-delay-bit-width: u32 value representing the number of bits used in - the step time register. + the step time register. - anatop-enable-bit: u32 value representing regulator enable bit offset. - vin-supply: input supply phandle. diff --git a/doc/device-tree-bindings/spi/spi-bus.txt b/doc/device-tree-bindings/spi/spi-bus.txt index 420ec9529f..e57897ac0c 100644 --- a/doc/device-tree-bindings/spi/spi-bus.txt +++ b/doc/device-tree-bindings/spi/spi-bus.txt @@ -8,10 +8,10 @@ in slave mode. The SPI master node requires the following properties: - #address-cells - number of cells required to define a chip select - address on the SPI bus. + address on the SPI bus. - #size-cells - should be zero. - compatible - name of SPI bus controller following generic names - recommended practice. + recommended practice. - cs-gpios - (optional) gpios chip select. No other properties are required in the SPI bus node. It is assumed that a driver for an SPI bus device will understand that it is an SPI bus. @@ -45,16 +45,16 @@ SPI slave nodes must be children of the SPI master node and can contain the following properties. - reg - (required) chip select address of device. - compatible - (required) name of SPI device following generic names - recommended practice + recommended practice - spi-max-frequency - (required) Maximum SPI clocking speed of device in Hz - spi-cpol - (optional) Empty property indicating device requires - inverse clock polarity (CPOL) mode + inverse clock polarity (CPOL) mode - spi-cpha - (optional) Empty property indicating device requires - shifted clock phase (CPHA) mode + shifted clock phase (CPHA) mode - spi-cs-high - (optional) Empty property indicating device requires - chip select active high + chip select active high - spi-3wire - (optional) Empty property indicating device requires - 3-wire mode. + 3-wire mode. - spi-tx-bus-width - (optional) The bus width(number of data wires) that used for MOSI. Defaults to 1 if not present. - spi-rx-bus-width - (optional) The bus width(number of data wires) that diff --git a/doc/device-tree-bindings/spi/spi-qup.txt b/doc/device-tree-bindings/spi/spi-qup.txt index 3697df2631..2f2f070c5a 100644 --- a/doc/device-tree-bindings/spi/spi-qup.txt +++ b/doc/device-tree-bindings/spi/spi-qup.txt @@ -7,7 +7,7 @@ Required properties: - reg : Physical base address and size of SPI registers map. - clock : Clock phandle (see clock bindings for details). - #address-cells : Number of cells required to define a chip select - address on the SPI bus. Should be set to 1. + address on the SPI bus. Should be set to 1. - #size-cells : Should be zero. - pinctrl-names : Must be "default" - pinctrl-n : At least one pinctrl phandle diff --git a/doc/device-tree-bindings/tpm2/sandbox.txt b/doc/device-tree-bindings/tpm2/sandbox.txt index 3d0f727cc4..05a310e057 100644 --- a/doc/device-tree-bindings/tpm2/sandbox.txt +++ b/doc/device-tree-bindings/tpm2/sandbox.txt @@ -7,5 +7,5 @@ Required properties: Example: tpm { - compatible = "sandbox,tpm2"; + compatible = "sandbox,tpm2"; }; diff --git a/doc/device-tree-bindings/tpm2/tis-tpm2-spi.txt b/doc/device-tree-bindings/tpm2/tis-tpm2-spi.txt index 3a2ee4bd17..16f870225f 100644 --- a/doc/device-tree-bindings/tpm2/tis-tpm2-spi.txt +++ b/doc/device-tree-bindings/tpm2/tis-tpm2-spi.txt @@ -6,7 +6,8 @@ Required properties: - reg : SPI Chip select Optional properties: -- gpio-reset : Reset GPIO (if not connected to the SoC reset line) +- reset-gpios : Reset GPIO (if not connected to the SoC reset line) +- gpio-reset : Reset GPIO (deprecated, use reset-gpios instead) - spi-max-frequency : See spi-bus.txt Example: diff --git a/doc/device-tree-bindings/w1-eeprom/ds24xxx.txt b/doc/device-tree-bindings/w1-eeprom/ds24xxx.txt index 2e91be93b7..3ad8d460f2 100644 --- a/doc/device-tree-bindings/w1-eeprom/ds24xxx.txt +++ b/doc/device-tree-bindings/w1-eeprom/ds24xxx.txt @@ -34,4 +34,3 @@ onewire_tm: onewire { compatible = "maxim,ds24xxx"; } }; - diff --git a/doc/device-tree-bindings/w1-eeprom/ds2502.txt b/doc/device-tree-bindings/w1-eeprom/ds2502.txt index 7f05fc432e..8788e57058 100644 --- a/doc/device-tree-bindings/w1-eeprom/ds2502.txt +++ b/doc/device-tree-bindings/w1-eeprom/ds2502.txt @@ -30,4 +30,3 @@ Example with parent bus: compatible = "maxim,ds2502"; }; }; - diff --git a/doc/device-tree-bindings/w1-eeprom/eep_sandbox.txt b/doc/device-tree-bindings/w1-eeprom/eep_sandbox.txt index 82bb5899af..ebf718c743 100644 --- a/doc/device-tree-bindings/w1-eeprom/eep_sandbox.txt +++ b/doc/device-tree-bindings/w1-eeprom/eep_sandbox.txt @@ -31,4 +31,3 @@ onewire_tm: onewire { compatible = "sandbox,w1-eeprom"; } }; - diff --git a/doc/device-tree-bindings/w1/w1-gpio.txt b/doc/device-tree-bindings/w1/w1-gpio.txt index 5a582448e4..2ba86d7d91 100644 --- a/doc/device-tree-bindings/w1/w1-gpio.txt +++ b/doc/device-tree-bindings/w1/w1-gpio.txt @@ -37,4 +37,3 @@ onewire_tm: onewire { compatible = "maxim,ds24xxx"; } }; - diff --git a/doc/device-tree-bindings/watchdog/gpio-wdt.txt b/doc/device-tree-bindings/watchdog/gpio-wdt.txt new file mode 100644 index 0000000000..c9a8559a3e --- /dev/null +++ b/doc/device-tree-bindings/watchdog/gpio-wdt.txt @@ -0,0 +1,19 @@ +GPIO watchdog timer + +Describes a simple watchdog timer which is reset by toggling a gpio. + +Required properties: + +- compatible: Must be "linux,wdt-gpio". +- gpios: gpio to toggle when wdt driver reset method is called. +- always-running: Boolean property indicating that the watchdog cannot + be disabled. At present, U-Boot only supports this kind of GPIO + watchdog. + +Example: + + gpio-wdt { + gpios = <&gpio0 1 0>; + compatible = "linux,wdt-gpio"; + always-running; + }; diff --git a/doc/imx/common/imx25.txt b/doc/imx/common/imx25.txt deleted file mode 100644 index 0ca21b6dfe..0000000000 --- a/doc/imx/common/imx25.txt +++ /dev/null @@ -1,10 +0,0 @@ -U-Boot for Freescale i.MX25 - -This file contains information for the port of U-Boot to the Freescale i.MX25 -SoC. - -1. CONVENTIONS FOR FUSE ASSIGNMENTS ------------------------------------ - -1.1 MAC Address: It is stored in the words 26 to 31 of fuse bank 0, using the - natural MAC byte order (i.e. MSB first). diff --git a/doc/imx/common/imx6.txt b/doc/imx/common/imx6.txt index 0b5061128c..9007cfbf58 100644 --- a/doc/imx/common/imx6.txt +++ b/doc/imx/common/imx6.txt @@ -9,7 +9,7 @@ SoC. 1.1 MAC Address: It is stored in fuse bank 4, with the 32 lsbs in word 2 and the 16 msbs in word 3[15:0]. For i.MX6SX and i.MX6UL, they have two MAC addresses. The second MAC address - is stored in fuse bank 4, with the 16 lsb in word 3[31:16] and the 32 msbs in + is stored in fuse bank 4, with the 16 lsb in word 3[31:16] and the 32 msbs in word 4. Example: diff --git a/doc/kwboot.1 b/doc/kwboot.1 index 1e9ca268f7..acdea891d9 100644 --- a/doc/kwboot.1 +++ b/doc/kwboot.1 @@ -1,21 +1,22 @@ -.TH KWBOOT 1 "2012-05-19" +.TH KWBOOT 1 "2021-08-25" .SH NAME -kwboot \- Boot Marvell Kirkwood SoCs over a serial link. +kwboot \- Boot Marvell Kirkwood (and others 32-bit) SoCs over a serial link. .SH SYNOPSIS .B kwboot .RB [ "-b \fIimage\fP" ] -.RB [ "-p" ] .RB [ "-t" ] .RB [ "-B \fIbaudrate\fP" ] .RB \fITTY\fP .SH "DESCRIPTION" -The \fBmkimage\fP program boots boards based on Marvell's Kirkwood -platform over their integrated UART. Boot image files will typically +The \fBkwboot\fP program boots boards based on Marvell's 32-bit +platforms including Kirkwood, Dove, A370, AXP, A375, A38x +and A39x over their integrated UART. Boot image files will typically contain a second stage boot loader, such as U-Boot. The image file must conform to Marvell's BootROM firmware image format -(\fIkwbimage\fP), created using a tool such as \fBmkimage\fP. +(\fIkwbimage v0\fP or \fIv1\fP), created using a tool such as +\fBmkimage\fP. Following power-up or a system reset, system BootROM code polls the UART for a brief period of time, sensing a handshake message which @@ -36,25 +37,23 @@ by the second-stage loader. Handshake; then upload file \fIimage\fP over \fITTY\fP. Note that for the encapsulated boot code to be executed, \fIimage\fP -must be of type "UART boot" (0x69). Boot images of different types, -such as backup images of vendor firmware downloaded from flash memory -(type 0x8B), will not work (or not as expected). See \fB-p\fP for a -workaround. +must be of type "UART boot" (0x69). The \fBkwboot\fP program changes +this type automatically, unless the \fIimage\fP is signed, in which +case it cannot be changed. This mode writes handshake status and upload progress indication to -stdout. +stdout. It is possible that \fIimage\fP contains an optional binary +code in it's header which may also print some output via UART (for +example U-Boot SPL does this). In such a case, this output is also +written to stdout after the header is sent. .TP .BI "\-p" -In combination with \fB-b\fP, patches the header in \fIimage\fP prior -to upload, to "UART boot" type. +Obsolete. Does nothing. -This option attempts on-the-fly conversion of some none-UART image -types, such as images which were originally formatted to be stored in -flash memory. - -Conversion is performed in memory. The contents of \fIimage\fP will -not be altered. +In the past, when this option was used, the program patched the header +in the image prior upload, to "UART boot" type. This is now done by +default. .TP .BI "\-t" @@ -65,11 +64,26 @@ If used in combination with \fB-b\fP, terminal mode is entered immediately following a successful image upload. If standard I/O streams connect to a console, this mode will terminate -after receiving 'ctrl-\\' followed by 'c' from console input. +after receiving \fBctrl-\e\fP followed by \fBc\fP from console input. .TP .BI "\-B \fIbaudrate\fP" -Adjust the baud rate on \fITTY\fP. Default rate is 115200. +If used in combination with \fB-b\fP, inject into the image header +code that changes baud rate to \fIbaudrate\fP after uploading image +header, and code that changes the baud rate back to the default +(115200 Bd) before executing payload, and also adjust the baud rate +on \fITTY\fP correspondingly. This can make the upload significantly +faster. + +If used in combination with \fB-t\fP, adjust the baud rate to +\fIbaudrate\fP on \fITTY\fP before starting terminal. + +If both \fB-b\fP and \fB-t\fP are used, the baud rate is changed +back to 115200 after the upload. + +Tested values for \fIbaudrate\fP for Armada 38x include: 115200, +230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000, +2000000, 2500000, 3125000, 4000000 and 5200000. .SH "SEE ALSO" .PP @@ -82,3 +96,7 @@ Daniel Stodden <daniel.stodden@gmail.com> Luka Perkov <luka@openwrt.org> .br David Purdy <david.c.purdy@gmail.com> +.br +Pali Rohár <pali@kernel.org> +.br +Marek Behún <marek.behun@nic.cz> diff --git a/doc/mvebu/armada-8k-memory.txt b/doc/mvebu/armada-8k-memory.txt index 064518eb51..f554d71e99 100644 --- a/doc/mvebu/armada-8k-memory.txt +++ b/doc/mvebu/armada-8k-memory.txt @@ -53,4 +53,3 @@ Start End Use 0xFFF00000 0xFFFFFFFF Bootrom 0x100000000 <DRAM Size>-1 DRAM - diff --git a/doc/mvebu/cmd/bubt.txt b/doc/mvebu/cmd/bubt.txt index a539c15bcd..6051243f11 100644 --- a/doc/mvebu/cmd/bubt.txt +++ b/doc/mvebu/cmd/bubt.txt @@ -52,4 +52,3 @@ Notes: - NAND: # nand write <load_address> 0 <ATF Size> - SPI: # sf write <load_address> 0 <ATF Size> - SD/eMMC: # mmc write <load_address> [0|1] <ATF Size>/<block_size> - diff --git a/doc/usage/qfw.rst b/doc/usage/qfw.rst index 87463e1e5b..b3704b92d6 100644 --- a/doc/usage/qfw.rst +++ b/doc/usage/qfw.rst @@ -26,7 +26,7 @@ The *qfw load* command is used to load a kernel and an initial RAM disk. kernel_addr address to which the file specified by the -kernel parameter of QEMU shall be loaded. Defaults to environment variable *loadaddr* and further to - the value of *CONFIG_LOADADDR*. + the value of *CONFIG_SYS_LOAD_ADDR*. initrd_addr address to which the file specified by the -initrd parameter of QEMU shall |