diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.ext4 | 22 | ||||
| -rw-r--r-- | doc/README.iscsi | 159 | ||||
| -rw-r--r-- | doc/README.m54418twr | 1 | ||||
| -rw-r--r-- | doc/README.qemu-arm | 21 | ||||
| -rw-r--r-- | doc/device-tree-bindings/spi/soft-spi.txt | 24 | ||||
| -rw-r--r-- | doc/device-tree-bindings/spi/spi-cadence.txt | 13 |
6 files changed, 208 insertions, 32 deletions
diff --git a/doc/README.ext4 b/doc/README.ext4 index 2b0eab5ddec..8ecd21eee3b 100644 --- a/doc/README.ext4 +++ b/doc/README.ext4 @@ -2,10 +2,10 @@ U-Boot supports access of both ext2 and ext4 filesystems, either in read-only mode or in read-write mode. First, to enable support for both ext4 (and, automatically, ext2 as well), -but without selecting the corresponding commands, use one of: +but without selecting the corresponding commands, enable one of the following: - #define CONFIG_FS_EXT4 (for read-only) - #define CONFIG_EXT4_WRITE (for read-write) + CONFIG_FS_EXT4 (for read-only) + CONFIG_EXT4_WRITE (for read-write) Next, to select the ext2-related commands: @@ -20,22 +20,22 @@ or ext4-related commands: use one or both of: - #define CONFIG_CMD_EXT2 - #define CONFIG_CMD_EXT4 + CONFIG_CMD_EXT2 + CONFIG_CMD_EXT4 -Selecting either of the above automatically defines CONFIG_FS_EXT4 if it -wasn't defined already. +Selecting either of the above automatically selects CONFIG_FS_EXT4 if it +wasn't enabled already. -In addition, to get the write access command "ext4write", use: +In addition, to get the write access command "ext4write", enable: - #define CONFIG_CMD_EXT4_WRITE + CONFIG_CMD_EXT4_WRITE -which automatically defines CONFIG_EXT4_WRITE if it wasn't defined +which automatically selects CONFIG_EXT4_WRITE if it wasn't defined already. Also relevant are the generic filesystem commands, selected by: - #define CONFIG_CMD_FS_GENERIC + CONFIG_CMD_FS_GENERIC This does not automatically enable EXT4 support for you, you still need to do that yourself. diff --git a/doc/README.iscsi b/doc/README.iscsi new file mode 100644 index 00000000000..cb71c6e7446 --- /dev/null +++ b/doc/README.iscsi @@ -0,0 +1,159 @@ +# iSCSI booting with U-Boot and iPXE + +## 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 +are expected to be integrated in 2018 together with a wget command. + +For booting a diskless computer this leaves us with BOOTP or DHCP to get the +address of a boot script. TFTP or NFS can be used to load the boot script, the +operating system kernel and the initial file system (initrd). + +These protocols are insecure. The client cannot validate the authenticity +of the contacted servers. And the server cannot verify the identity of the +client. + +Furthermore the services providing the operating system loader or kernel are +not the ones that the operating system typically will use. Especially in a SAN +environment this makes updating the operating system a hassle. After installing +a new kernel version the boot files have to be copied to the TFTP server +directory. + +The HTTPS protocol provides certificate based validation of servers. Sensitive +data like passwords can be securely transmitted. + +The iSCSI protocol is used for connecting storage attached networks. It +provides mutual authentication using the CHAP protocol. It typically runs on +a TCP transport. + +Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script +via HTTPS and to download any other files needed for booting via iSCSI from the +same target where the operating system is installed. + +An alternative to implementing these protocols in U-Boot is to use an existing +software that can run on top of U-Boot. iPXE is the "swiss army knife" of +network booting. It supports both HTTPS and iSCSI. It has a scripting engine for +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 + +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 +U-Boot. + +iPXE executes its internal script. This script may optionally chain load a +secondary boot script via HTTPS or open a shell. + +For the further boot process iPXE connects to the iSCSI server. This includes +the mutual authentication using the CHAP protocol. After the authentication iPXE +has access to the iSCSI targets. + +For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It +uses the ConnectController boot service of U-Boot to request U-Boot to connect a +file system driver. U-Boot reads from the iSCSI drive via the block IO protocol +offered by iPXE. It creates the partition handles and installs the simple file +protocol. Now iPXE can call the simple file protocol to load Grub. U-Boot uses +the block IO protocol offered by iPXE to fulfill the request. + +Once Grub is started it uses the same block IO protocol to load Linux. Via +the EFI stub Linux is called as an EFI application. + +``` + +--------+ +--------+ + | | Runs | | + | U-Boot |=========>| iPXE | + | EFI | | snp.efi| ++--------+ | | DHCP | | +| |<====|********|<=========| | +| DHCP | | | Get IP | | +| Server | | | Address | | +| |====>|********|=========>| | ++--------+ | | Response | | + | | | | + | | | | ++--------+ | | HTTPS | | +| |<====|********|<=========| | +| HTTPS | | | Load | | +| Server | | | Script | | +| |====>|********|=========>| | ++--------+ | | | | + | | | | + | | | | ++--------+ | | iSCSI | | +| |<====|********|<=========| | +| iSCSI | | | Auth | | +| Server |====>|********|=========>| | +| | | | | | +| | | | Loads | | +| |<====|********|<=========| | +--------+ +| | | | Grub | | Runs | | +| |====>|********|=========>| |=======>| Grub | +| | | | | | | | +| | | | | | | | +| | | | | | Loads | | +| |<====|********|<=========|********|<=======| | +--------+ +| | | | | | Linux | | Runs | | +| |====>|********|=========>|********|=======>| |=====>| Linux | +| | | | | | | | | | ++--------+ +--------+ +--------+ +--------+ | | + | | + | | + | ~ ~ ~ ~| +``` + +## 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 + +### iPXE + +For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed. + + git clone http://git.ipxe.org/ipxe.git + cd ipxe/src + make bin-arm64-efi/snp.efi -j6 EMBED=myscript.ipxe + +The available commands for the boot script are documented at: + +http://ipxe.org/cmd + +Credentials are managed as environment variables. These are described here: + +http://ipxe.org/cfg + +iPXE by default will put the CPU to rest when waiting for input. U-Boot does +not wake it up due to missing interrupt support. To avoid this behavior create +file src/config/local/nap.h. + + /* nap.h */ + #undef NAP_EFIX86 + #undef NAP_EFIARM + #define NAP_NULL + +The supported commands in iPXE are controlled by an include, too. Putting the +following into src/config/local/general.h is sufficient for most use cases. + + /* general.h */ + #define NSLOOKUP_CMD /* Name resolution command */ + #define PING_CMD /* Ping command */ + #define NTP_CMD /* NTP commands */ + #define VLAN_CMD /* VLAN commands */ + #define IMAGE_EFI /* EFI image support */ + #define DOWNLOAD_PROTO_HTTPS /* Secure Hypertext Transfer Protocol */ + #define DOWNLOAD_PROTO_FTP /* File Transfer Protocol */ + #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */ + #define DOWNLOAD_PROTO_FILE /* Local file system access */ + +## Links + +* https://ipxe.org - iPXE open source boot firmware +* https://www.gnu.org/software/grub/ - GNU Grub (Grand Unified Bootloader) diff --git a/doc/README.m54418twr b/doc/README.m54418twr index 1d90fccbcff..0ca74aa114c 100644 --- a/doc/README.m54418twr +++ b/doc/README.m54418twr @@ -63,7 +63,6 @@ Changed files: 1.2 Configuration settings for M54418TWR Development Board CONFIG_MCF5441x -- define for all MCF5441x CPUs CONFIG_M54418 -- define for all Freescale MCF54418 CPUs -CONFIG_M54418TWR -- define for M54418TWR board CONFIG_MCFUART -- define to use common CF Uart driver CONFIG_SYS_UART_PORT -- define UART port number, start with 0, 1 and 2 diff --git a/doc/README.qemu-arm b/doc/README.qemu-arm index 2895e3b97ff..aee789447ae 100644 --- a/doc/README.qemu-arm +++ b/doc/README.qemu-arm @@ -4,11 +4,12 @@ # SPDX-License-Identifier: GPL-2.0+ # -U-Boot on QEMU's 'virt' machine on ARM -====================================== +U-Boot on QEMU's 'virt' machine on ARM & AArch64 +================================================ QEMU for ARM supports a special 'virt' machine designed for emulation and virtualization purposes. This document describes how to run U-Boot under it. +Both 32-bit ARM and AArch64 are supported. The 'virt' platform provides the following as the basic functionality: @@ -17,7 +18,7 @@ The 'virt' platform provides the following as the basic functionality: - A generated device tree blob placed at the start of RAM - A freely configurable amount of RAM, described by the DTB - A PL011 serial port, discoverable via the DTB - - An ARMv7 architected timer + - An ARMv7/ARMv8 architected timer - PSCI for rebooting the system - A generic ECAM-based PCI host controller, discoverable via the DTB @@ -25,19 +26,29 @@ Additionally, a number of optional peripherals can be added to the PCI bus. Building U-Boot --------------- -Set the CROSS_COMPILE and ARCH=arm environment variables as usual, and run: +Set the CROSS_COMPILE environment variable as usual, and run: +- For ARM: make qemu_arm_defconfig make +- For AArch64: + make qemu_arm64_defconfig + make + Running U-Boot -------------- The minimal QEMU command line to get U-Boot up and running is: +- For ARM: qemu-system-arm -machine virt,highmem=off -bios u-boot.bin +- For AArch64: + qemu-system-aarch64 -machine virt,highmem=off -cpu cortex-a57 -bios u-boot.bin + The 'highmem=off' parameter to the 'virt' machine is required for PCI to work -in U-Boot. +in U-Boot. Also, for some odd reason qemu-system-aarch64 needs to be explicitly +told to use a 64-bit CPU or it will boot in 32-bit mode. Additional peripherals that have been tested to work in both U-Boot and Linux can be enabled with the following command line parameters: diff --git a/doc/device-tree-bindings/spi/soft-spi.txt b/doc/device-tree-bindings/spi/soft-spi.txt index d09c1a50765..dfb50664732 100644 --- a/doc/device-tree-bindings/spi/soft-spi.txt +++ b/doc/device-tree-bindings/spi/soft-spi.txt @@ -6,11 +6,15 @@ performance will typically be much lower than a real SPI bus. The soft SPI node requires the following properties: -compatible: "u-boot,soft-spi" -soft_spi_cs: GPIO number to use for SPI chip select (output) -soft_spi_sclk: GPIO number to use for SPI clock (output) -soft_spi_mosi: GPIO number to use for SPI MOSI line (output) -soft_spi_miso GPIO number to use for SPI MISO line (input) +Mandatory properties: +compatible: "spi-gpio" +cs-gpios: GPIOs to use for SPI chip select (output) +gpio-sck: GPIO to use for SPI clock (output) +And at least one of: +gpio-mosi: GPIO to use for SPI MOSI line (output) +gpio-miso: GPIO to use for SPI MISO line (input) + +Optional propertie: spi-delay-us: Number of microseconds of delay between each CS transition The GPIOs should be specified as required by the GPIO controller referenced. @@ -21,11 +25,11 @@ typically holds the GPIO number. Example: soft-spi { - compatible = "u-boot,soft-spi"; - cs-gpio = <&gpio 235 0>; /* Y43 */ - sclk-gpio = <&gpio 225 0>; /* Y31 */ - mosi-gpio = <&gpio 227 0>; /* Y33 */ - miso-gpio = <&gpio 224 0>; /* Y30 */ + compatible = "spi-gpio"; + cs-gpios = <&gpio 235 0>; /* Y43 */ + gpio-sck = <&gpio 225 0>; /* Y31 */ + gpio-mosi = <&gpio 227 0>; /* Y33 */ + gpio-miso = <&gpio 224 0>; /* Y30 */ spi-delay-us = <1>; #address-cells = <1>; #size-cells = <0>; diff --git a/doc/device-tree-bindings/spi/spi-cadence.txt b/doc/device-tree-bindings/spi/spi-cadence.txt index c1e2233d7cd..74c82080fc9 100644 --- a/doc/device-tree-bindings/spi/spi-cadence.txt +++ b/doc/device-tree-bindings/spi/spi-cadence.txt @@ -6,7 +6,10 @@ Required properties: - 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). -- sram-size : spi controller sram size. +- cdns,fifo-depth : Size of the data FIFO in words. +- cdns,fifo-width : Bus width of the data FIFO in bytes. +- cdns,trigger-address : 32-bit indirect AHB trigger address. +- cdns,is-decoded-cs : Flag to indicate whether decoder is used or not. - status : enable in requried dts. connected flash properties @@ -15,14 +18,14 @@ connected flash properties - spi-max-frequency : Max supported spi frequency. - page-size : Flash page size. - block-size : Flash memory block size. -- tshsl-ns : Added delay in master reference clocks (ref_clk) for +- cdns,tshsl-ns : Added delay in master reference clocks (ref_clk) for the length that the master mode chip select outputs are de-asserted between transactions. -- tsd2d-ns : Delay in master reference clocks (ref_clk) between one +- cdns,tsd2d-ns : Delay in master reference clocks (ref_clk) between one chip select being de-activated and the activation of another. -- tchsh-ns : Delay in master reference clocks between last bit of +- cdns,tchsh-ns : Delay in master reference clocks between last bit of current transaction and de-asserting the device chip select (n_ss_out). -- tslch-ns : Delay in master reference clocks between setting +- cdns,tslch-ns : Delay in master reference clocks between setting n_ss_out low and first bit transfer |