diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.chromium | 296 | ||||
| -rw-r--r-- | doc/README.chromium-chainload | 239 | ||||
| -rw-r--r-- | doc/README.rmobile | 1 | ||||
| -rw-r--r-- | doc/README.uefi | 12 | ||||
| -rw-r--r-- | doc/device-tree-bindings/i2c/i2c.txt | 5 | ||||
| -rw-r--r-- | doc/device-tree-bindings/leds/leds-bcm6858.txt | 51 | ||||
| -rw-r--r-- | doc/device-tree-bindings/mmc/snps,dw-mmc.txt | 33 | ||||
| -rw-r--r-- | doc/device-tree-bindings/mtd/stm32-fmc2-nand.txt | 59 | ||||
| -rw-r--r-- | doc/device-tree-bindings/phy/phy-stm32-usbphyc.txt | 4 | ||||
| -rw-r--r-- | doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt | 2 | ||||
| -rw-r--r-- | doc/device-tree-bindings/spi/spi-atcspi200.txt | 2 | ||||
| -rw-r--r-- | doc/device-tree-bindings/spi/spi-stm32-qspi.txt | 2 | ||||
| -rw-r--r-- | doc/device-tree-bindings/usb/dwc2.txt | 58 | ||||
| -rw-r--r-- | doc/driver-model/MIGRATION.txt | 1 | ||||
| -rw-r--r-- | doc/driver-model/fs_firmware_loader.txt | 62 | ||||
| -rw-r--r-- | doc/git-mailrc | 6 |
16 files changed, 627 insertions, 206 deletions
diff --git a/doc/README.chromium b/doc/README.chromium index 45eaeced2d..096bc4f1f7 100644 --- a/doc/README.chromium +++ b/doc/README.chromium @@ -1,239 +1,177 @@ -Running U-Boot from coreboot on Chromebooks -=========================================== +Chromium OS Support in U-Boot +============================= -U-Boot can be used as a secondary boot loader in a few situations such as from -UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on -ARM platforms to start up the machine. +Introduction +------------ -This document aims to provide a guide to booting U-Boot on a Chromebook. It -is only a starting point, and there are many guides on the interwebs. But -placing this information in the U-Boot tree should make it easier to find for -those who use U-Boot habitually. +This describes how to use U-Boot with Chromium OS. Several options are +available: -Most of these platforms are supported by U-Boot natively, but it is risky to -replace the ROM unless you have a servo board and cable to restore it with. + - Running U-Boot from the 'altfw' feature, which is available on selected + Chromebooks from 2019 onwards (initially Grunt). Press '1' from the + developer-mode screen to get into U-Boot. See here for details: + https://sites.google.com/a/chromium.org/dev/chromium-os/poking-around-your-chrome-os-device?pli=1 + - Running U-Boot from the disk partition. This involves signing U-Boot and + placing it on the disk, for booting as a 'kernel'. See + README.chromium-chainload for information on this. This is the only + option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat + more involved. -For all of these the standard U-Boot build instructions apply. For example on -ARM: + - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be + used instead of either or both of depthcharge (a bootloader which forked + from U-Boot in 2013) and coreboot. See below for more information on + this. - sudo apt install gcc-arm-linux-gnueabi - mkdir b - make O=b/nyan_big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all -You can obtain the vbutil_kernel utility here: +U-Boot with Chromium OS verified boot +------------------------------------- - https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U +To obtain: + git clone https://github.com/sglass68/u-boot.git + cd u-boot + git checkout cros-master -Snow (Samsung ARM Chromebook) ------------------------------ +To build for sandbox: -See here: + UB=/tmp/b/chromeos_sandbox # U-Boot build directory + CROS=/home/sglass/cosarm # Chromium OS directory + make O=$UB/chromeos_sandbox_defconfig + make O=$UB -j20 -s VBOOT_SOURCE=$CROS/src/platform/vboot_reference \ + MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1 -https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook +Replace sandbox with another supported target. +This produces $UB/image.bin which contains the firmware binaries in a SPI +flash image. -Nyan-big --------- - -Compiled based on information here: -https://lists.denx.de/pipermail/u-boot/2015-March/209530.html -https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big -https://lists.denx.de/pipermail/u-boot/2017-May/289491.html -https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card - -1. Build U-Boot - - mkdir b - make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all - - -2. Select a .its file - -Select something from doc/chromium which matches your board, or create your -own. - -Note that the device tree node is required, even though it is not actually -used by U-Boot. This is because the Chromebook expects to pass it to the -kernel, and crashes if it is not present. - - -3. Build and sign an image - - ./b/nyan-big/tools/mkimage -f doc/chromium/nyan-big.its u-boot-chromium.fit - echo test >dummy.txt - vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \ - --signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \ - --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \ - --bootloader dummy.txt --pack u-boot.kpart - - -4. Prepare an SD card - - DISK=/dev/sdc # Replace with your actual SD card device - sudo cgpt create $DISK - sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK - sudo cgpt add -b 32802 -s 2000000 -t rootfs $DISK - sudo gdisk $DISK # Enter command 'w' to write a protective MBR to the disk - - -5. Write U-Boot to the SD card +To run on sandbox: - sudo dd if=u-boot.kpart of=/dev/sdc1; sync + $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out \ + -L6 -c "host bind 0 $CROS/src/build/images/cheza/latest/chromiumos_image.bin; vboot go auto" \ + -l -w -s state.dtb -r +To run on other boards: + Install image.bin in the SPI flash of your device + Boot your system -6. Start it up -Reboot the device in dev mode. Make sure that you have USB booting enabled. To -do this, login as root (via Ctrl-Alt-forward_arrow) and type -'enable_dev_usb_boot'. You only need to do this once. +Sandbox +------- -Reboot the device with the SD card inserted. Press Clrl-U at the developer -mode screen. It should show something like the following on the display: +Most Chromium OS development with U-Boot is undertaken using sandbox. There is +a sandbox target available (chromeos_sandbox) which allows running U-Boot on +a Linux machine completion with emulations of the display, TPM, disk, etc. - U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600) +Running sandbox starts TPL, which contains the first phase of vboot, providing +a device tree and binding a Chromium OS disk image for use to find kernels +(any Chromium OS image will do). It also saves driver state between U-Boot +phases into state.dtb and will automatically ensure that memory is shared +between all phases. TPL will jump to SPL and then on to U-Boot proper. - Model: Acer Chromebook 13 CB5-311 - Board: Google/NVIDIA Nyan-big, ID: 1 +It is possible to run with debugging on, e.g. - Net: No ethernet found. - Hit any key to stop autoboot: 0 - Tegra124 (Nyan-big) # + gdb --args $UB/tpl/u-boot-tpl -d .... +Breakpoints can be set in any U-Boot phase. Overall this is a good debugging +environment for new verified-boot features. -7. Known problems -On the serial console the word MMC is chopped at the start of the line: +Samus +----- -C: sdhci@700b0000: 2, sdhci@700b0400: 1, sdhci@700b0600: 0 +Basic support is available for samus, using the chromeos_samus target. If you +have an em100, use: -This is likely due to some problem with change-over of the serial driver -during relocation (or perhaps updating the clock setup in board_init()). + sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r +to write the image and then boot samus (Power-Refresh). -9. Notes -To check that you copied the u-boot.its file correctly, use these commands. -You should see that the data at 0x100 in u-boot-chromium.fit is the first few -bytes of U-Boot: +Boot flow +--------- - hd u-boot-chromium.fit |head -20 - ... - 00000100 b8 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| +Verified boot starts in TPL, which selects the A or B SPL, which in turn selects +the A or B U-Boot. Then this jumps to the selected kernel. If anything goes +wrong, the device reboots and the recovery SPL and U-Boot are used instead. - hd b/nyan-big/u-boot.bin |head - 00000000 b8 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| +More details are available here: + https://www.chromium.org/chromium-os/chromiumos-design-docs/firmware-boot-and-recovery -The 'data' property of the FIT is set up to start at offset 0x100 bytes into -the file. The change to CONFIG_SYS_TEXT_BASE is also an offset of 0x100 bytes -from the load address. If this changes, you either need to modify U-Boot to be -fully relocatable, or expect it to hang. +New uclasses +------------ -chromebook_jerry ----------------- +Several uclasses are provided in cros/: -The instruction are similar to those for Nyan with changes as noted below: + UCLASS_CROS_AUX_FW Chrome OS auxiliary firmware + UCLASS_CROS_FWSTORE Chrome OS firmware storage + UCLASS_CROS_NVDATA Chrome OS non-volatile data device + UCLASS_CROS_VBOOT_EC Chrome OS vboot EC operations + UCLASS_CROS_VBOOT_FLAG Chrome OS verified boot flag -1. Patch U-Boot +The existing UCLASS_CROS_EC is also used. -Open include/configs/rk3288_common.h -Change: - -#define CONFIG_SYS_TEXT_BASE 0x00100000 - -to: - -#define CONFIG_SYS_TEXT_BASE 0x02000100 - - - -2. Build U-Boot - - mkdir b - make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \ - chromebook_jerry_defconfig all - - -3. See above - -4. Build and sign an image - - ./b/chromebook_jerry/tools/mkimage -f doc/chromium/chromebook_jerry.its \ - u-boot-chromium.fit - echo test >dummy.txt - vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \ - --signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \ - --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \ - --bootloader dummy.txt --pack u-boot.kpart - - -5. See above +Commands +-------- -6. See above +A new 'vboot' command is provided to run particular vboot stages. The most +useful command is 'vboot go auto', which continues where the last stage left +off. -7. Start it up +Note that TPL and SPL do not supports commands as yet, so the vboot code is +called directly from the SPL boot devices (BOOT_DEVICE_CROS_VBOOT). See +cros_load_image_tpl() and cros_load_image_spl() which both call +vboot_run_auto(). -Reboot the device in dev mode. Make sure that you have USB booting enabled. To -do this, login as root (via Ctrl-Alt-forward_arrow) and type -'enable_dev_usb_boot'. You only need to do this once. -Reboot the device with the SD card inserted. Press Clrl-U at the developer -mode screen. It should show something like the following on the display: +Config options +-------------- - U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600) +The main option is CONFIG_CHROMEOS, which enables a wide array of other options +so that the required features are present. - Model: Google Jerry - Net: Net Initialization Skipped - No ethernet found. - Hit any key to stop autoboot: 0 +Device-tree config +------------------ -8. Known problems +Various options are available which control the operation of verified boot. +See cros/dts/bindings/config.txt for details. Most config is handled at run- +time, although build-time config (with Kconfig) could also be added fairly +easily. -None as yet. +Porting to other hardware +------------------------- -9. Notes +A basic port to samus (Chromebook Pixel 2015) is in a basic working state, +using the chromeos_samus target. Patches will likely be forthcoming in early +2019. Ports to an ARM board and coreboot (for x86 Chromebooks) are in the +dreaming state. -None as yet. +Tests +----- -Other notes -=========== +Chromium OS firmware has a very limited set of tests. The tests that originally +existed in U-Boot were not brought over to coreboot or depthcharge. -flashrom --------- +The U-Boot tests ('make check') do operate, but at present there are no +Chromium OS tests available. These will hopefully come together over time. Of +course the above sandbox feature provides a sort of functional test and can +detecte problems that affect the flow or particular vboot features. - Used to make a backup of your firmware, or to replace it. - See: https://www.chromium.org/chromium-os/packages/cros-flashrom +TO DO +----- +- Support for booting from coreboot (patches expected March 2019) +- Support for booting from an ARM board, e.g. bob -coreboot --------- -Coreboot itself is not designed to actually boot an OS. Instead, a program -called Depthcharge is used. This originally came out of U-Boot and was then -heavily hacked and modified such that is is almost unrecognisable. It does -include a very small part of the U-Boot command-line interface but is not -usable as a general-purpose boot loader. - -In addition, it has a very unusual design in that it does not do device init -itself, but instead relies on coreboot. This is similar to (in U-Boot) having -a SPI driver with an empty probe() method, relying on whatever was set up -beforehand. It can be quite hard to figure out between these two code bases -what settings are actually used. When chain-loading into U-Boot we must be -careful to reinit anything that U-Boot expects. If not, some peripherals (or -the whole machine) may not work. This makes the process of chainloading more -complicated than it could be on some platforms. - -Finally, it supports only a subset of the U-Boot's FIT format. In particular -it uses a fixed address to load the FIT and does not support load/exec -addresses. This means that U-Boot must be able to boot from whatever -address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting -in Depthcharge). In practice this means that the data in the kernel@1 FIT node -(see above) must start at the same address as U-Boot's CONFIG_SYS_TEXT_BASE. +Simon Glass +sjg@chromium.org +7 October 2018 diff --git a/doc/README.chromium-chainload b/doc/README.chromium-chainload new file mode 100644 index 0000000000..45eaeced2d --- /dev/null +++ b/doc/README.chromium-chainload @@ -0,0 +1,239 @@ +Running U-Boot from coreboot on Chromebooks +=========================================== + +U-Boot can be used as a secondary boot loader in a few situations such as from +UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on +ARM platforms to start up the machine. + +This document aims to provide a guide to booting U-Boot on a Chromebook. It +is only a starting point, and there are many guides on the interwebs. But +placing this information in the U-Boot tree should make it easier to find for +those who use U-Boot habitually. + +Most of these platforms are supported by U-Boot natively, but it is risky to +replace the ROM unless you have a servo board and cable to restore it with. + + +For all of these the standard U-Boot build instructions apply. For example on +ARM: + + sudo apt install gcc-arm-linux-gnueabi + mkdir b + make O=b/nyan_big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all + +You can obtain the vbutil_kernel utility here: + + https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U + + +Snow (Samsung ARM Chromebook) +----------------------------- + +See here: + +https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook + + +Nyan-big +-------- + +Compiled based on information here: +https://lists.denx.de/pipermail/u-boot/2015-March/209530.html +https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big +https://lists.denx.de/pipermail/u-boot/2017-May/289491.html +https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card + +1. Build U-Boot + + mkdir b + make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all + + +2. Select a .its file + +Select something from doc/chromium which matches your board, or create your +own. + +Note that the device tree node is required, even though it is not actually +used by U-Boot. This is because the Chromebook expects to pass it to the +kernel, and crashes if it is not present. + + +3. Build and sign an image + + ./b/nyan-big/tools/mkimage -f doc/chromium/nyan-big.its u-boot-chromium.fit + echo test >dummy.txt + vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \ + --signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \ + --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \ + --bootloader dummy.txt --pack u-boot.kpart + + +4. Prepare an SD card + + DISK=/dev/sdc # Replace with your actual SD card device + sudo cgpt create $DISK + sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK + sudo cgpt add -b 32802 -s 2000000 -t rootfs $DISK + sudo gdisk $DISK # Enter command 'w' to write a protective MBR to the disk + + +5. Write U-Boot to the SD card + + sudo dd if=u-boot.kpart of=/dev/sdc1; sync + + +6. Start it up + +Reboot the device in dev mode. Make sure that you have USB booting enabled. To +do this, login as root (via Ctrl-Alt-forward_arrow) and type +'enable_dev_usb_boot'. You only need to do this once. + +Reboot the device with the SD card inserted. Press Clrl-U at the developer +mode screen. It should show something like the following on the display: + + U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600) + + Model: Acer Chromebook 13 CB5-311 + Board: Google/NVIDIA Nyan-big, ID: 1 + + Net: No ethernet found. + Hit any key to stop autoboot: 0 + Tegra124 (Nyan-big) # + + +7. Known problems + +On the serial console the word MMC is chopped at the start of the line: + +C: sdhci@700b0000: 2, sdhci@700b0400: 1, sdhci@700b0600: 0 + +This is likely due to some problem with change-over of the serial driver +during relocation (or perhaps updating the clock setup in board_init()). + + +9. Notes + +To check that you copied the u-boot.its file correctly, use these commands. +You should see that the data at 0x100 in u-boot-chromium.fit is the first few +bytes of U-Boot: + + hd u-boot-chromium.fit |head -20 + ... + 00000100 b8 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| + + hd b/nyan-big/u-boot.bin |head + 00000000 b8 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| + + +The 'data' property of the FIT is set up to start at offset 0x100 bytes into +the file. The change to CONFIG_SYS_TEXT_BASE is also an offset of 0x100 bytes +from the load address. If this changes, you either need to modify U-Boot to be +fully relocatable, or expect it to hang. + + +chromebook_jerry +---------------- + +The instruction are similar to those for Nyan with changes as noted below: + +1. Patch U-Boot + +Open include/configs/rk3288_common.h + +Change: + +#define CONFIG_SYS_TEXT_BASE 0x00100000 + +to: + +#define CONFIG_SYS_TEXT_BASE 0x02000100 + + + +2. Build U-Boot + + mkdir b + make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \ + chromebook_jerry_defconfig all + + +3. See above + +4. Build and sign an image + + ./b/chromebook_jerry/tools/mkimage -f doc/chromium/chromebook_jerry.its \ + u-boot-chromium.fit + echo test >dummy.txt + vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \ + --signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \ + --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \ + --bootloader dummy.txt --pack u-boot.kpart + + +5. See above + +6. See above + +7. Start it up + +Reboot the device in dev mode. Make sure that you have USB booting enabled. To +do this, login as root (via Ctrl-Alt-forward_arrow) and type +'enable_dev_usb_boot'. You only need to do this once. + +Reboot the device with the SD card inserted. Press Clrl-U at the developer +mode screen. It should show something like the following on the display: + + U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600) + + Model: Google Jerry + Net: Net Initialization Skipped + No ethernet found. + Hit any key to stop autoboot: 0 + + +8. Known problems + +None as yet. + + +9. Notes + +None as yet. + + +Other notes +=========== + +flashrom +-------- + + Used to make a backup of your firmware, or to replace it. + + See: https://www.chromium.org/chromium-os/packages/cros-flashrom + + +coreboot +-------- + +Coreboot itself is not designed to actually boot an OS. Instead, a program +called Depthcharge is used. This originally came out of U-Boot and was then +heavily hacked and modified such that is is almost unrecognisable. It does +include a very small part of the U-Boot command-line interface but is not +usable as a general-purpose boot loader. + +In addition, it has a very unusual design in that it does not do device init +itself, but instead relies on coreboot. This is similar to (in U-Boot) having +a SPI driver with an empty probe() method, relying on whatever was set up +beforehand. It can be quite hard to figure out between these two code bases +what settings are actually used. When chain-loading into U-Boot we must be +careful to reinit anything that U-Boot expects. If not, some peripherals (or +the whole machine) may not work. This makes the process of chainloading more +complicated than it could be on some platforms. + +Finally, it supports only a subset of the U-Boot's FIT format. In particular +it uses a fixed address to load the FIT and does not support load/exec +addresses. This means that U-Boot must be able to boot from whatever +address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting +in Depthcharge). In practice this means that the data in the kernel@1 FIT node +(see above) must start at the same address as U-Boot's CONFIG_SYS_TEXT_BASE. diff --git a/doc/README.rmobile b/doc/README.rmobile index f1bca54520..ea170a25a6 100644 --- a/doc/README.rmobile +++ b/doc/README.rmobile @@ -32,6 +32,7 @@ Currently the following boards are supported: | R8A7796 M3-W | Renesas Electronics ULCB | r8a7796_ulcb |---------------+----------------------------------------+------------------- | R8A77965 M3-N | Renesas Electronics Salvator-XS | r8a77965_salvator-x_defconfig +| R8A77965 M3-N | Renesas Electronics ULCB | r8a77965_ulcb |---------------+----------------------------------------+------------------- | R8A77970 V3M | Renesas Electronics Eagle | r8a77970_eagle_defconfig |---------------+----------------------------------------+------------------- diff --git a/doc/README.uefi b/doc/README.uefi index 66b6abece5..1d1039a6ae 100644 --- a/doc/README.uefi +++ b/doc/README.uefi @@ -14,9 +14,11 @@ and boot loaders like GRUB or the FreeBSD loader can be executed. ## Development target -The implementation of UEFI in U-Boot strives to reach the minimum requirements -described in "Server Base Boot Requirements System Software on ARM Platforms - -Version 1.1" [4]. +The implementation of UEFI in U-Boot strives to reach the requirements described +in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0" +[4]. The "Server Base Boot Requirements System Software on ARM Platforms" [5] +describes a superset of the EBBR specification and may be used as further +reference. A full blown UEFI implementation would contradict the U-Boot design principle "keep it small". @@ -344,5 +346,7 @@ This driver is only available if U-Boot is configured with http://uefi.org/specifications - UEFI specifications * [2](./driver-model/README.txt) doc/driver-model/README.txt - Driver model * [3](./README.iscsi) doc/README.iscsi - iSCSI booting with U-Boot and iPXE -* [4](https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11) +* [4](https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf) + Embedded Base Boot Requirements (EBBR) Specification - Release v1.0 +* [5](https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11) Server Base Boot Requirements System Software on ARM Platforms - Version 1.1 diff --git a/doc/device-tree-bindings/i2c/i2c.txt b/doc/device-tree-bindings/i2c/i2c.txt index de818d4713..9698e4899b 100644 --- a/doc/device-tree-bindings/i2c/i2c.txt +++ b/doc/device-tree-bindings/i2c/i2c.txt @@ -12,6 +12,10 @@ property which allows the chip offset length to be selected. Optional properties: - u-boot,i2c-offset-len - length of chip offset in bytes. If omitted the default value of 1 is used. +- u-boot,i2c-transaction-bytes - the length of single I2C transaction on + the bus. Some devices require more than single byte transmission + (e.g. mc34708 mfd). This information is necessary to correctly + initialize (put into idle state) I2C bus after soft reset. - gpios = <sda ...>, <scl ...>; pinctrl-names = "default", "gpio"; pinctrl-0 = <&i2c_xfer>; @@ -28,6 +32,7 @@ i2c4: i2c@12ca0000 { compatible = "google,cros-ec"; i2c-max-frequency = <100000>; u-boot,i2c-offset-len = <0>; + u-boot,i2c-transaction-bytes = <3>; ec-interrupt = <&gpx1 6 GPIO_ACTIVE_LOW>; }; }; diff --git a/doc/device-tree-bindings/leds/leds-bcm6858.txt b/doc/device-tree-bindings/leds/leds-bcm6858.txt new file mode 100644 index 0000000000..ea2fe23709 --- /dev/null +++ b/doc/device-tree-bindings/leds/leds-bcm6858.txt @@ -0,0 +1,51 @@ +LEDs connected to Broadcom BCM6858 controller + +This controller is present on BCM6858, BCM6328, BCM6362 and BCM63268. +In these SoCs it's possible to control LEDs both as GPIOs or by hardware. + +Required properties: + - compatible : should be "brcm,bcm6858-leds". + - #address-cells : must be 1. + - #size-cells : must be 0. + - reg : BCM6858 LED controller address and size. + +Optional properties: + - brcm,serial-led-msb-first : Boolean, msb data come out first on serial data pin + Default : false + - brcm,serial-led-en-pol : Boolean, serial led polarity (true => active high) + Default : false + - brcm,serial-led-clk-pol : Boolean, serial clock polarity (true => active high) + Default : false + - brcm,serial-led-data-ppol : Boolean, serial data polarity (true => active high) + Default : false + - brcm,serial-shift-inv : Boolean, led test mode + Default : false + +Each LED is represented as a sub-node of the brcm,bcm6858-leds device. + +LED sub-node required properties: + - reg : LED pin number (only LEDs 0 to 32 are valid). + +LED sub-node optional properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + - active-low : Boolean, makes LED active low. + Default : false + +Examples: +BCM6328 with 2 GPIO LEDs + leds0: led-controller@ff800800 { + compatible = "brcm,bcm6858-leds"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x0 0xff800800 0x0 0xe4>; + + led@2 { + reg = <2>; + label = "green:inet"; + }; + + led@5 { + reg = <5>; + label = "red:alarm"; + }; + }; diff --git a/doc/device-tree-bindings/mmc/snps,dw-mmc.txt b/doc/device-tree-bindings/mmc/snps,dw-mmc.txt new file mode 100644 index 0000000000..69faefa95e --- /dev/null +++ b/doc/device-tree-bindings/mmc/snps,dw-mmc.txt @@ -0,0 +1,33 @@ +Synopsys Designware Mobile Storage Host Controller extensions +used in Synopsys ARC devboards + +Required Properties: + +* compatible: should be - "snps,dw-mshc". +* bus-width: number of data lines connected to the controller. +* clocks: from common clock binding: handle to biu and ciu clocks for the + bus interface unit clock and the card interface unit clock. +* clock-names: from common clock binding: Shall be "biu" and "ciu". + +Optional properties: + +* fifo-depth: The maximum size of the tx/rx fifo's. If this property is not + specified, the default value of the fifo size is determined from the + controller registers. +* fifo-mode: Don't use DMA. +* max-frequency: Maximum operating clock frequency, driver uses 'ciu' clock + frequency if it is not set. + +Example: + +mmc0@f000a000 { + compatible = "snps,dw-mshc"; + reg = <0xf000a000 0x400>; + + bus-width = <4>; + fifo-depth = <256>; + clocks = <&mmcclk_biu>, <&mmcclk_ciu>; + clock-names = "biu", "ciu"; + max-frequency = <25000000>; +}; + diff --git a/doc/device-tree-bindings/mtd/stm32-fmc2-nand.txt b/doc/device-tree-bindings/mtd/stm32-fmc2-nand.txt new file mode 100644 index 0000000000..70e76be2a3 --- /dev/null +++ b/doc/device-tree-bindings/mtd/stm32-fmc2-nand.txt @@ -0,0 +1,59 @@ +STMicroelectronics Flexible Memory Controller 2 (FMC2) +NAND Interface + +Required properties: +- compatible: Should be one of: + * st,stm32mp15-fmc2 +- reg: NAND flash controller memory areas. + First region contains the register location. + Regions 2 to 4 respectively contain the data, command, + and address space for CS0. + Regions 5 to 7 contain the same areas for CS1. +- interrupts: The interrupt number +- pinctrl-0: Standard Pinctrl phandle (see: pinctrl/pinctrl-bindings.txt) +- clocks: The clock needed by the NAND flash controller + +Optional properties: +- resets: Reference to a reset controller asserting the FMC controller +- dmas: DMA specifiers (see: dma/stm32-mdma.txt) +- dma-names: Must be "tx", "rx" and "ecc" + +Optional children nodes: +Children nodes represent the available NAND chips. + +Optional properties: +- nand-on-flash-bbt: see nand.txt +- nand-ecc-strength: see nand.txt +- nand-ecc-step-size: see nand.txt + +The following ECC strength and step size are currently supported: + - nand-ecc-strength = <1>, nand-ecc-step-size = <512> (Hamming) + - nand-ecc-strength = <4>, nand-ecc-step-size = <512> (BCH4) + - nand-ecc-strength = <8>, nand-ecc-step-size = <512> (BCH8) (default) + +Example: + + fmc: nand-controller@58002000 { + compatible = "st,stm32mp15-fmc2"; + reg = <0x58002000 0x1000>, + <0x80000000 0x1000>, + <0x88010000 0x1000>, + <0x88020000 0x1000>, + <0x81000000 0x1000>, + <0x89010000 0x1000>, + <0x89020000 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&rcc FMC_K>; + resets = <&rcc FMC_R>; + pinctrl-names = "default"; + pinctrl-0 = <&fmc_pins_a>; + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + nand-on-flash-bbt; + #address-cells = <1>; + #size-cells = <1>; + }; + }; diff --git a/doc/device-tree-bindings/phy/phy-stm32-usbphyc.txt b/doc/device-tree-bindings/phy/phy-stm32-usbphyc.txt index 725ae71ae6..da98407403 100644 --- a/doc/device-tree-bindings/phy/phy-stm32-usbphyc.txt +++ b/doc/device-tree-bindings/phy/phy-stm32-usbphyc.txt @@ -23,6 +23,8 @@ Required properties: - compatible: must be "st,stm32mp1-usbphyc" - reg: address and length of the usb phy control register set - clocks: phandle + clock specifier for the PLL phy clock +- vdda1v1-supply: phandle to the regulator providing 1V1 power to the PHY +- vdda1v8-supply: phandle to the regulator providing 1V8 power to the PHY - #address-cells: number of address cells for phys sub-nodes, must be <1> - #size-cells: number of size cells for phys sub-nodes, must be <0> @@ -40,8 +42,6 @@ Required properties: - reg: phy port index - phy-supply: phandle to the regulator providing 3V3 power to the PHY, see phy-bindings.txt in the same directory. -- vdda1v1-supply: phandle to the regulator providing 1V1 power to the PHY -- vdda1v8-supply: phandle to the regulator providing 1V8 power to the PHY - #phy-cells: see phy-bindings.txt in the same directory, must be <0> for PHY port#1 and must be <1> for PHY port#2, to select USB controller diff --git a/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt b/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt index a1b559668f..a376c6fba5 100644 --- a/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt +++ b/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt @@ -42,7 +42,7 @@ Example: status = "okay"; spi_flash@0 { - compatible = "spi-flash"; + compatible = "jedec,spi-nor"; reg = <0>; spi-max-frequency = <50000000>; }; diff --git a/doc/device-tree-bindings/spi/spi-atcspi200.txt b/doc/device-tree-bindings/spi/spi-atcspi200.txt index 9c0630b500..e67b3425f0 100644 --- a/doc/device-tree-bindings/spi/spi-atcspi200.txt +++ b/doc/device-tree-bindings/spi/spi-atcspi200.txt @@ -28,7 +28,7 @@ Example: clocks = <&spiclk>; interrupts = <3 4>; flash@0 { - compatible = "spi-flash"; + compatible = "jedec,spi-nor"; spi-max-frequency = <50000000>; reg = <0>; spi-cpol; diff --git a/doc/device-tree-bindings/spi/spi-stm32-qspi.txt b/doc/device-tree-bindings/spi/spi-stm32-qspi.txt index 6c7da1d76c..cec3e1250c 100644 --- a/doc/device-tree-bindings/spi/spi-stm32-qspi.txt +++ b/doc/device-tree-bindings/spi/spi-stm32-qspi.txt @@ -29,7 +29,7 @@ Example: qflash0: n25q128a { #address-cells = <1>; #size-cells = <1>; - compatible = "micron,n25q128a13", "spi-flash"; + compatible = "micron,n25q128a13", "jedec,spi-nor"; spi-max-frequency = <108000000>; spi-tx-bus-width = <4>; spi-rx-bus-width = <4>; diff --git a/doc/device-tree-bindings/usb/dwc2.txt b/doc/device-tree-bindings/usb/dwc2.txt new file mode 100644 index 0000000000..61493f7cb0 --- /dev/null +++ b/doc/device-tree-bindings/usb/dwc2.txt @@ -0,0 +1,58 @@ +Platform DesignWare HS OTG USB 2.0 controller +----------------------------------------------------- + +Required properties: +- compatible : One of: + - brcm,bcm2835-usb: The DWC2 USB controller instance in the BCM2835 SoC. + - hisilicon,hi6220-usb: The DWC2 USB controller instance in the hi6220 SoC. + - rockchip,rk3066-usb: The DWC2 USB controller instance in the rk3066 Soc; + - "rockchip,px30-usb", "rockchip,rk3066-usb", "snps,dwc2": for px30 Soc; + - "rockchip,rk3188-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3188 Soc; + - "rockchip,rk3288-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3288 Soc; + - "lantiq,arx100-usb": The DWC2 USB controller instance in Lantiq ARX SoCs; + - "lantiq,xrx200-usb": The DWC2 USB controller instance in Lantiq XRX SoCs; + - "amlogic,meson8-usb": The DWC2 USB controller instance in Amlogic Meson8 SoCs; + - "amlogic,meson8b-usb": The DWC2 USB controller instance in Amlogic Meson8b SoCs; + - "amlogic,meson-gxbb-usb": The DWC2 USB controller instance in Amlogic S905 SoCs; + - "amcc,dwc-otg": The DWC2 USB controller instance in AMCC Canyonlands 460EX SoCs; + - snps,dwc2: A generic DWC2 USB controller with default parameters. + - "st,stm32f4x9-fsotg": The DWC2 USB FS/HS controller instance in STM32F4x9 SoCs + configured in FS mode; + - "st,stm32f4x9-hsotg": The DWC2 USB HS controller instance in STM32F4x9 SoCs + configured in HS mode; + - "st,stm32f7-hsotg": The DWC2 USB HS controller instance in STM32F7 SoCs + configured in HS mode; +- reg : Should contain 1 register range (address and length) +- interrupts : Should contain 1 interrupt +- clocks: clock provider specifier +- clock-names: shall be "otg" +Refer to clk/clock-bindings.txt for generic clock consumer properties + +Optional properties: +- phys: phy provider specifier +- phy-names: shall be "usb2-phy" +Refer to phy/phy-bindings.txt for generic phy consumer properties +- dr_mode: shall be one of "host", "peripheral" and "otg" + Refer to usb/generic.txt +- g-rx-fifo-size: size of rx fifo size in gadget mode. +- g-np-tx-fifo-size: size of non-periodic tx fifo size in gadget mode. +- g-tx-fifo-size: size of periodic tx fifo per endpoint (except ep0) in gadget mode. +- usb33d-supply: external VBUS and ID sensing comparators supply, in order to + perform OTG operation, used on STM32MP1 SoCs. +- u-boot,force-b-session-valid: force B-peripheral session instead of relying on + VBUS sensing (only valid when dr_mode = "peripheral" and for u-boot). + +Deprecated properties: +- g-use-dma: gadget DMA mode is automatically detected + +Example: + + usb@101c0000 { + compatible = "ralink,rt3050-usb, snps,dwc2"; + reg = <0x101c0000 40000>; + interrupts = <18>; + clocks = <&usb_otg_ahb_clk>; + clock-names = "otg"; + phys = <&usbphy>; + phy-names = "usb2-phy"; + }; diff --git a/doc/driver-model/MIGRATION.txt b/doc/driver-model/MIGRATION.txt index 957529202b..df659f3dd9 100644 --- a/doc/driver-model/MIGRATION.txt +++ b/doc/driver-model/MIGRATION.txt @@ -77,7 +77,6 @@ Partially converted: drivers/spi/kirkwood_spi.c drivers/spi/mxc_spi.c drivers/spi/omap3_spi.c - drivers/spi/ti_qspi.c Status: In progress Deadline: 2019.07 diff --git a/doc/driver-model/fs_firmware_loader.txt b/doc/driver-model/fs_firmware_loader.txt index b9aee848cc..8be6185371 100644 --- a/doc/driver-model/fs_firmware_loader.txt +++ b/doc/driver-model/fs_firmware_loader.txt @@ -1,4 +1,4 @@ -# Copyright (C) 2018 Intel Corporation <www.intel.com> +# Copyright (C) 2018-2019 Intel Corporation <www.intel.com> # # SPDX-License-Identifier: GPL-2.0 @@ -27,7 +27,7 @@ Firmware storage device described in device tree source defined in fs-loader node as shown in below: Example for block device: - fs_loader0: fs-loader@0 { + fs_loader0: fs-loader { u-boot,dm-pre-reloc; compatible = "u-boot,fs-loader"; phandlepart = <&mmc 1>; @@ -39,22 +39,55 @@ Firmware storage device described in device tree source device, it can be described in FDT as shown in below: Example for ubi: - fs_loader1: fs-loader@1 { + fs_loader1: fs-loader { u-boot,dm-pre-reloc; compatible = "u-boot,fs-loader"; mtdpart = "UBI", ubivol = "ubi0"; }; - Then, firmware_loader property would be set with the path of fs_loader - node under /chosen node such as: + Then, firmware-loader property can be added with any device node, which + driver would use the firmware loader for loading. + + The value of the firmware-loader property should be set with phandle + of the fs-loader node. + For example: + firmware-loader = <&fs_loader0>; + + If there are majority of devices using the same fs-loader node, then + firmware-loader property can be added under /chosen node instead of + adding to each of device node. + + For example: /{ chosen { - firmware_loader = &fs_loader0; + firmware-loader = <&fs_loader0>; }; }; - However, this driver is also designed to support U-boot environment + In each respective driver of devices using firmware loader, the firmware + loaded instance should be created by DT phandle. + + For example of getting DT phandle from /chosen and creating instance: + chosen_node = ofnode_path("/chosen"); + if (!ofnode_valid(chosen_node)) { + debug("/chosen node was not found.\n"); + return -ENOENT; + } + + phandle_p = ofnode_get_property(chosen_node, "firmware-loader", &size); + if (!phandle_p) { + debug("firmware-loader property was not found.\n"); + return -ENOENT; + } + + phandle = fdt32_to_cpu(*phandle_p); + ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER, + phandle, &dev); + if (ret) + return ret; + + Firmware loader driver is also designed to support U-boot environment variables, so all these data from FDT can be overwritten through the U-boot environment variable during run time. For examples: @@ -104,9 +137,12 @@ return: Description: The firmware is loaded directly into the buffer pointed to by buf -Example of creating firmware loader instance and calling -request_firmware_into_buf API: - if (uclass_get_device(UCLASS_FS_FIRMWARE_LOADER, 0, &dev)) { - request_firmware_into_buf(dev, filename, buffer_location, - buffer_size, offset_ofreading); - } +Example of calling request_firmware_into_buf API after creating firmware loader +instance: + ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER, + phandle, &dev); + if (ret) + return ret; + + request_firmware_into_buf(dev, filename, buffer_location, buffer_size, + offset_ofreading); diff --git a/doc/git-mailrc b/doc/git-mailrc index b75ebab02b..f989792e8d 100644 --- a/doc/git-mailrc +++ b/doc/git-mailrc @@ -24,9 +24,8 @@ alias dinh Dinh Nguyen <dinguyen@kernel.org> alias hs Heiko Schocher <hs@denx.de> alias iwamatsu Nobuhiro Iwamatsu <iwamatsu@nigauri.org> alias jaehoon Jaehoon Chung <jh80.chung@samsung.com> -alias jagan Jagan Teki <jagan@openedev.com> +alias jagan Jagan Teki <jagan@amarulasolutions.com> alias jhersh Joe Hershberger <joe.hershberger@ni.com> -alias luka Luka Perkov <luka.perkov@sartura.hr> alias lukma Lukasz Majewski <lukma@denx.de> alias macpaul Macpaul Lin <macpaul@andestech.com> alias marex Marek Vasut <marex@denx.de> @@ -35,7 +34,6 @@ alias masahiro Masahiro Yamada <yamada.masahiro@socionext.com> alias mateusz Mateusz Kulikowski <mateusz.kulikowski@gmail.com> alias maxime Maxime Ripard <maxime.ripard@free-electrons.com> alias monstr Michal Simek <monstr@monstr.eu> -alias prafulla Prafulla Wadaskar <prafulla@marvell.com> alias prom Minkyu Kang <mk7.kang@samsung.com> alias ptomsich Philipp Tomsich <philipp.tomsich@theobroma-systems.com> alias sbabic Stefano Babic <sbabic@denx.de> @@ -56,7 +54,7 @@ alias arm uboot, aaribaud, trini alias at91 uboot, abiessmann alias davinci ti alias imx uboot, sbabic -alias kirkwood uboot, prafulla, luka, stroese +alias kirkwood uboot, stroese alias omap ti alias pxa uboot, marex alias rmobile uboot, iwamatsu |