diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.bloblist | 82 | ||||
| -rw-r--r-- | doc/README.distro | 3 | ||||
| -rw-r--r-- | doc/README.iscsi | 35 | ||||
| -rw-r--r-- | doc/README.mediatek | 221 | ||||
| -rw-r--r-- | doc/README.trace | 2 | ||||
| -rw-r--r-- | doc/device-tree-bindings/spi/spi-cadence.txt | 2 | ||||
| -rw-r--r-- | doc/driver-model/MIGRATION.txt | 41 | ||||
| -rw-r--r-- | doc/uImage.FIT/signature.txt | 3 |
8 files changed, 364 insertions, 25 deletions
diff --git a/doc/README.bloblist b/doc/README.bloblist new file mode 100644 index 0000000000..b0e787b97d --- /dev/null +++ b/doc/README.bloblist @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: GPL-2.0+ + +Blob Lists - bloblist +===================== + +Introduction +------------ + +A bloblist provides a way to store collections of binary information (blobs) in +a central structure. Each record of information is assigned a tag so that its +owner can find it and update it. Each record is generally described by a C +structure defined by the code that owns it. + + +Passing state through the boot process +-------------------------------------- + +The bloblist is created when the first U-Boot component runs (often SPL, +sometimes TPL). It is passed through to each successive part of the boot and +can be accessed as needed. This provides a way to transfer state from one part +to the next. For example, TPL may determine that a watchdog reset occurred by +reading an SoC register. Reading the register may reset the value, so that it +cannot be read a second time. So TPL can store that in a bloblist record which +can be passed through to SPL and U-Boot proper, which can print a message +indicating that something went wrong and the watchdog fired. + + +Blobs +----- + +While each blob in the bloblist can be of any length, bloblists are designed to +hold small amounts of data, typically a few KB at most. It is not possible to +change the length of a blob once it has been written. Each blob is normally +created from a C structure which can beused to access its fields. + + +Blob tags +--------- + +Each blob has a tag which is a 32-bit number. This uniquely identifies the +owner of the blob. Blob tags are listed in enum blob_tag_t and are named +with a BLOBT_ prefix. + + +Single structure +---------------- + +There is normally only one bloblist in U-Boot. Since a bloblist can store +multiple blobs it does not seem useful to allow multiple bloblists. Of course +there could be reasons for this, such as needing to spread the blobs around in +different memory areas due to fragmented memory, but it is simpler to just have +a single bloblist. + + +API +--- + +Bloblist provides a fairly simple API which allows blobs to be created and +found. All access is via the blob's tag. + + +Finishing the bloblist +---------------------- + +When a part of U-Boot is about to jump to the next part, it can 'finish' the +bloblist in preparation for the next stage. This involves adding a checksum so +that the next stage can make sure that the data arrived safely. While the +bloblist is in use, changes can be made which will affect the checksum, so it +is easier to calculate the checksum at the end after all changes are made. + + +Future work +----------- + +Bootstage has a mechanism to 'stash' its records for passing to the next part. +This should move to using bloblist, to avoid having its own mechanism for +passing information between U-Boot parts. + + +Simon Glass +sjg@chromium.org +12-Aug-2018 diff --git a/doc/README.distro b/doc/README.distro index f8e9752a0f..ab6e6f4e74 100644 --- a/doc/README.distro +++ b/doc/README.distro @@ -292,7 +292,7 @@ Each entry in the macro defines a single boot device (e.g. a specific eMMC device or SD card) or type of boot device (e.g. USB disk). The parameters to the func macro (passed in by the internal implementation of the header) are: -- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE). +- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE, VIRTIO). - Lower-case disk type (same options as above). - ID of the specific disk (MMC only) or ignored for other types. @@ -398,6 +398,7 @@ The list of possible targets consists of: * scsi * ide * usb + * virtio Other *boot* variables than the ones defined above are only for internal use of the boot environment and are not guaranteed to exist or work in the same diff --git a/doc/README.iscsi b/doc/README.iscsi index faee636264..3a12438f90 100644 --- a/doc/README.iscsi +++ b/doc/README.iscsi @@ -1,8 +1,6 @@ -iSCSI booting with U-Boot and iPXE -================================== +# iSCSI booting with U-Boot and iPXE -Motivation ----------- +## Motivation U-Boot has only a reduced set of supported network protocols. The focus for network booting has been on UDP based protocols. A TCP stack and HTTP support @@ -41,8 +39,7 @@ fine grained control of the boot process and can provide a command shell. iPXE can be built as an EFI application (named snp.efi) which can be loaded and run by U-Boot. -Boot sequence -------------- +## Boot sequence U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This application has network access via the simple network protocol offered by @@ -106,19 +103,16 @@ the EFI stub Linux is called as an EFI application:: | | | ~ ~ ~ ~| -Security --------- +## Security The iSCSI protocol is not encrypted. The traffic could be secured using IPsec but neither U-Boot nor iPXE does support this. So we should at least separate the iSCSI traffic from all other network traffic. This can be achieved using a virtual local area network (VLAN). -Configuration -------------- +## Configuration -iPXE -^^^^ +### iPXE For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed:: @@ -157,9 +151,20 @@ following into src/config/local/general.h is sufficient for most use cases:: #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */ #define DOWNLOAD_PROTO_FILE /* Local file system access */ -Links ------ +### Open-iSCSI + +When the root file system is on an iSCSI drive you should disable pings and set +the replacement timer to a high value [3]: + + node.conn[0].timeo.noop_out_interval = 0 + node.conn[0].timeo.noop_out_timeout = 0 + node.session.timeo.replacement_timeout = 86400 + +## Links * [1](https://ipxe.org) https://ipxe.org - iPXE open source boot firmware * [2](https://www.gnu.org/software/grub/) https://www.gnu.org/software/grub/ - - GNU GRUB (Grand Unified Bootloader) + GNU GRUB (Grand Unified Bootloader) +* [3](https://github.com/open-iscsi/open-iscsi/blob/master/README) + https://github.com/open-iscsi/open-iscsi/blob/master/README - + Open-iSCSI README diff --git a/doc/README.mediatek b/doc/README.mediatek new file mode 100644 index 0000000000..246579d4be --- /dev/null +++ b/doc/README.mediatek @@ -0,0 +1,221 @@ +# SPDX-License-Identifier: GPL-2.0+ +# +# Copyright (C) 2018 MediaTek Inc. +# Ryder Lee <ryder.lee@kernel.org> + + +This document describes how to compile the U-Boot and how to change U-Boot +configuration about the MediaTek SoCs. + + +Build Procedure +=============== + -Set the cross compiler: + + # export CROSS_COMPILE=/path/to/toolchain/arm-linux-gnueabi- + + -Clean-up old residuals: + + # make mrproper + + -Configure the U-Boot: + + # make <defconfig_file> + # make + + - For the MT7623n bananapi R2 board use "mt7623n_bpir2_defconfig" + - For the MT7629 reference board use "mt7629_rfb_defconfig" + + +Boot sequence +============= + -Bootrom -> MTK preloader -> U-Boot + + - MT7623n + + This version of U-Boot doesn't implement SPL. So, MTK preloader binary + is needed to boot up: + + https://github.com/BPI-SINOVOIP/BPI-R2-bsp/tree/master/mt-pack/mtk/bpi-r2/bin + + + -Bootrom -> SPL -> U-Boot + + - MT7629 + + +Configuration update +==================== + To update the U-Boot configuration, please refer to doc/README.kconfig + + +MediaTek image header +===================== +Currently there are two image headers used for MediaTek chips: + + - BootROM image header. This header is used by the first stage bootloader. It records + the desired compatible boot device, integrity information and its load address. + + The on-chip BootROM will firstly verify integrity and compatibility of the bootloader. + + If verification passed, the BootROM will then load the bootloader into on-chip SRAM, + and pass control to it. + + Note that this header is actually a combination of three independent headers: + Device header, BRLYT header and GFH header. + + Used by U-Boot SPL of MT7629 and preloader of MT7623. + + + - MediaTek legacy image header. This header was originally used by the legacy image. It + basically records the load address, image size and image name. + + After all low level initializations passed, the preloader will locate the LK image and + load it into DRAM, and pass control to it. + + Now this header is used by U-Boot of MT7623. + + +To generate these two headers with mkimage: + + # mkimage -T mtk_image -a <load_addr> -n <option_string> -d <input_file> <image_file> + + - mtk_image means using MediaTek's header generation method. + + + - load_addr is the load address of this image. + For first stage bootloader like U-Boot SPL or preloader, it usually points to the + on-chip SRAM. + + For second stage bootloader like U-Boot, it usually points to the DRAM. + + + - option_string contains options to generate the header. + + The option string is using the follow format: + key1=value1;key2=value2;... + + The following key names are valid: + lk: If lk=1, LK image header is used. Otherwise BootROM image header is used. + + lkname: The name of the LK image header. The maximum length is 32. + The default value is "U-Boot". + + media: Desired boot device. The valid values are: + nand : Parallel NAND + snand: Serial NAND + nor : Serial NOR + emmc : eMMC + sdmmc: SD + + nandinfo: Desired NAND device type, a combination of page size, oob size and + optional device capacity. Valid types are: + 2k+64 : for Serial NAND, 2KiB page size + 64B oob size + 2k+120 : for Serial NAND, 2KiB page size + 120B oob size + 2k+128 : for Serial NAND, 2KiB page size + 128B oob size + 4k+256 : for Serial NAND, 4KiB page size + 256B oob size + 1g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 1Gbit size + 2g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 2Gbit size + 4g:2k+64 : for Parallel NAND, 2KiB page size + 64B oob size, total 4Gbit size + 2g:2k+128: for Parallel NAND, 2KiB page size + 128B oob size, total 2Gbit size + 4g:2k+128: for Parallel NAND, 2KiB page size + 128B oob size, total 4Gbit size + + +MT7629 partitions on Serial NOR +=============================== + + Start End Size Description + 00000000 - 0000ffff: 64KiB U-Boot SPL + 00010000 - 0005ffff: 320KiB U-Boot + 00060000 - 0006ffff: 64KiB U-Boot env / MediaTek NVRAM + 00070000 - 000affff: 256KiB RF calibration data + 000b0000 - xxxxxxxx: all left Firmware image + + +BPi-R2 (MT7623N) partitions on SD +================================= + Please note that the last two partitions can vary from different Linux distributions + depending on the MBR partition table. + + Start End Size Description + 00000000 - 000001ff: 512B Device header (with MBR partition table) + 00000200 - 000007ff: 1536B BRLYT header + 00000800 - 0004ffff: 318KiB Preloader (with GFH header) + 00050000 - 000fffff: 704KiB U-Boot + 00100000 - 063fffff: 99MiB Reserved + 06400000 - 163fffff: 256MiB Partition 1 (FAT32) + 16400000 - xxxxxxxx: all left Partition 2 (ext4) + + +Upgrading notice on Serial NOR +============================== +Example: MT7629 + + The command sf is used to operate the Serial NOR device: + + - To probe current NOR flash: + + # sf probe + + - To erase a region: + + # sf erase <offset> <len> + + - To write data to an offset: + + # sf write <data_addr> <offset> <len> + + - To boot kernel: + + # bootm 0x300b0000 + + The memory address range 0x30000000 - 0x3fffffff is mapped to the NOR flash. + The DRAM starts at 0x40000000. + + Please note that the output binary u-boot-mtk.bin is a combination of SPL and U-Boot, + and it should be write to beginning of the flash. + + Otherwise you should use standalone files: + + spl/u-boot-spl-mtk.bin for SPL, + u-boot.img for U-Boot. + + +Upgrading notice on SD / eMMC +============================= +Example: MT7623 + + Normally only Preloader and U-Boot can be upgraded within U-Boot, and other partitions + should be written in PC. + + - To probe current SD card / eMMC: + + # mmc dev 0 for eMMC + # mmc dev 1 for SD + + - To erase a region: + + # mmc erase <blk_offset> <blk_num> + + - To write data to a block offset: + + # mmc write <data_addr> <blk_offset> <blk_num> + + - To load kernel image from partition 1: + + # fatload mmc 0:1 <load_address> <path_to_kernel_uImage> for eMMC + # fatload mmc 1:1 <load_address> <path_to_kernel_uImage> for SD + + - To boot kernel: + + # bootm <load_address> + + The DRAM starts at 0x80000000. + + Please note that we use block offset and block count for SD card, not the byte offset. + The block size is always 512 bytes for SD card. + + +Documentation +============= + http://wiki.banana-pi.org/Banana_Pi_BPI-R2 diff --git a/doc/README.trace b/doc/README.trace index 74ba26a5a4..2e7ca3319a 100644 --- a/doc/README.trace +++ b/doc/README.trace @@ -88,7 +88,7 @@ stdin=serial stdout=serial Environment size: 117/8188 bytes -=>sb save host 0 trace 0 ${profoffset} +=>host save host 0 trace 0 ${profoffset} 11405888 bytes written in 10 ms (1.1 GiB/s) =>reset diff --git a/doc/device-tree-bindings/spi/spi-cadence.txt b/doc/device-tree-bindings/spi/spi-cadence.txt index 74c82080fc..69e02c1c4b 100644 --- a/doc/device-tree-bindings/spi/spi-cadence.txt +++ b/doc/device-tree-bindings/spi/spi-cadence.txt @@ -2,7 +2,7 @@ Cadence QSPI controller device tree bindings -------------------------------------------- Required properties: -- compatible : should be "cadence,qspi". +- compatible : should be "cdns,qspi-nor" - reg : 1.Physical base address and size of SPI registers map. 2. Physical base address & size of NOR Flash. - clocks : Clock phandles (see clock bindings for details). diff --git a/doc/driver-model/MIGRATION.txt b/doc/driver-model/MIGRATION.txt index 5ebefd608b..6b691338b4 100644 --- a/doc/driver-model/MIGRATION.txt +++ b/doc/driver-model/MIGRATION.txt @@ -5,19 +5,46 @@ U-Boot has been migrating to a new driver model since its introduction in 2014. This file describes the schedule for deprecation of pre-driver-model features. +CONFIG_DM_MMC +------------- + +Status: In progress +Deadline: 2019.04 + +The subsystem itself has been converted and maintainers should submit patches +switching over to using CONFIG_DM_MMC and other base driver model options in +time for inclusion in the 2019.04 rerelease. + +CONFIG_DM_USB +------------- + +Status: In progress +Deadline: 2019.07 + +The subsystem itself has been converted along with many of the host controller +and maintainers should submit patches switching over to using CONFIG_DM_USB and +other base driver model options in time for inclusion in the 2019.07 rerelease. + +CONFIG_SATA +----------- + +Status: In progress +Deadline: 2019.07 + +The subsystem itself has been converted along with many of the host controller +and maintainers should submit patches switching over to using CONFIG_AHCI and +other base driver model options in time for inclusion in the 2019.07 rerelease. CONFIG_BLK ---------- Status: In progress -Deadline: 2018.05 - -Maintainers should submit patches for enabling CONFIG_BLK on all boards in -time for inclusion in the 2018.05 release. Boards not converted by this -time may be removed in a subsequent release. +Deadline: 2019.07 -Note that this implies use of driver model for all block devices (e.g. -MMC, USB, SCSI, SATA). +In concert with maintainers migrating their block device usage to the +appropriate DM driver, CONFIG_BLK needs to be set as well. The final deadline +here coincides with the final deadline for migration of the various block +subsystems. CONFIG_DM_SPI CONFIG_DM_SPI_FLASH diff --git a/doc/uImage.FIT/signature.txt b/doc/uImage.FIT/signature.txt index a765722679..bfff6fdc73 100644 --- a/doc/uImage.FIT/signature.txt +++ b/doc/uImage.FIT/signature.txt @@ -106,6 +106,9 @@ When the image is signed, the following properties are optional: - comment: Additional information about the signer or image +- padding: The padding algorithm, it may be pkcs-1.5 or pss, + if no value is provided we assume pkcs-1.5 + For config bindings (see Signed Configurations below), the following additional properties are optional: |