diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.efi | 86 | ||||
| -rw-r--r-- | doc/README.log | 3 | ||||
| -rw-r--r-- | doc/README.mxc_hab | 14 | ||||
| -rw-r--r-- | doc/README.uefi | 334 | ||||
| -rw-r--r-- | doc/README.vxworks | 51 | ||||
| -rw-r--r-- | doc/README.x86 | 2 | ||||
| -rw-r--r-- | doc/device-tree-bindings/i2c/i2c.txt | 13 | ||||
| -rw-r--r-- | doc/git-mailrc | 4 |
8 files changed, 392 insertions, 115 deletions
diff --git a/doc/README.efi b/doc/README.efi deleted file mode 100644 index 956f5bfa0c..0000000000 --- a/doc/README.efi +++ /dev/null @@ -1,86 +0,0 @@ -# -# Copyright (C) 2015 Google, Inc -# -# SPDX-License-Identifier: GPL-2.0+ -# - -EFI on U-Boot -============= -This document provides information about the implementation of the UEFI API [1] -in U-Boot. - - -=========== Table of Contents =========== - -Motivation -How do I get it? -Status -Future work - - -Motivation ----------- - -With this API support in place, you can run any UEFI payload (such as the Linux -kernel, grub2 or gummiboot) on U-Boot. This dramatically simplifies boot loader -configuration, as U-Boot based systems now look and feel (almost) the same way -as TianoCore based systems. - -How do I get it? ----------------- - -EFI support for 32bit ARM and AArch64 is already included in U-Boot. All you -need to do is enable - - CONFIG_CMD_BOOTEFI=y - CONFIG_EFI_LOADER=y - -in your .config file and you will automatically get a bootefi command to run -an efi application as well as snippet in the default distro boot script that -scans for removable media efi binaries as fallback. - -Status ------- - -I am successfully able to run grub2 and Linux EFI binaries with this code on -ARMv7 as well as AArch64 systems. - -When enabled, the resulting U-Boot binary only grows by ~10KB, so it's very -light weight. - -All storage devices are directly accessible from the uEFI payload - -Removable media booting (search for /efi/boot/boota{a64,arm}.efi) is supported. - -Simple use cases like "Plug this SD card into my ARM device and it just -boots into grub which boots into Linux", work very well. - - -Running HelloWord.efi ---------------------- - -You can run a simple 'hello world' EFI program in U-Boot. -Enable the option CONFIG_CMD_BOOTEFI_HELLO. - -Then you can boot into U-Boot and type: - - > bootefi hello - -The 'hello world EFI' program will then run, print a message and exit. - - -Future work ------------ - -Of course, there are still a few things one could do on top: - - - Improve disk media detection (don't scan, use what information we -have) - - Add EFI variable support using NVRAM - - Add GFX support - - Make EFI Shell work - - Network device support - - Support for payload exit - - Payload Watchdog support - -[1] http://uefi.org/ diff --git a/doc/README.log b/doc/README.log index dc9e2deec5..2ee1b753bc 100644 --- a/doc/README.log +++ b/doc/README.log @@ -162,7 +162,8 @@ Code size --------- Code size impact depends largely on what is enabled. The following numbers are -for snow, which is a Thumb-2 board: +generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in +bytes): This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0 CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0 diff --git a/doc/README.mxc_hab b/doc/README.mxc_hab index 75390a505e..a40ebf3e84 100644 --- a/doc/README.mxc_hab +++ b/doc/README.mxc_hab @@ -33,12 +33,12 @@ Image Ver: 2 (i.MX53/6 compatible) Data Size: 327680 Bytes = 320.00 kB = 0.31 MB Load Address: 177ff420 Entry Point: 17800000 -HAB Blocks: 177ff400 00000000 0004dc00 - ^^^^^^^^ ^^^^^^^^ ^^^^^^^^ - | | | - | | -------- (1) - | | - | ------------------- (2) +HAB Blocks: 0x177ff400 0x00000000 0x0004dc00 + ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^ + | | | + | | ----- (1) + | | + | ---------------- (2) | --------------------------- (3) @@ -78,7 +78,7 @@ Example Output of the SPL (imximage) creation: Data Size: 61440 Bytes = 60.00 kB = 0.06 MB Load Address: 00907420 Entry Point: 00908000 - HAB Blocks: 00907400 00000000 0000cc00 + HAB Blocks: 0x00907400 0x00000000 0x0000cc00 Example Output of the u-boot-ivt.img (firmware_ivt) creation: Image Name: U-Boot 2016.11-rc1-31589-g2a4411 diff --git a/doc/README.uefi b/doc/README.uefi new file mode 100644 index 0000000000..bb89b7ac2f --- /dev/null +++ b/doc/README.uefi @@ -0,0 +1,334 @@ +<!-- + Copyright (c) 2018 Heinrich Schuchardt + + SPDX-License-Identifier: GPL-2.0+ +--> + +# UEFI on U-Boot + +The Unified Extensible Firmware Interface Specification (UEFI) [1] has become +the default for booting on AArch64 and x86 systems. It provides a stable API for +the interaction of drivers and applications with the firmware. The API comprises +access to block storage, network, and console to name a few. The Linux kernel +and boot loaders like GRUB or the FreeBSD loader can be executed. + +## Building for UEFI + +The UEFI standard supports only little endian systems. The UEFI support can be +activated for ARM and x86 by specifying + + CONFIG_CMD_BOOTEFI=y + CONFIG_EFI_LOADER=y + +in the .config file. + +Support for attaching virtual block devices, e.g. iSCSI drives connected by the +loaded UEFI application [3], requires + + CONFIG_BLK=y + CONFIG_PARTITIONS=y + +### Executing a UEFI binary + +The bootefi command is used to start UEFI applications or to install UEFI +drivers. It takes two parameters + + bootefi <image address> [fdt address] + +* image address - the memory address of the UEFI binary +* fdt address - the memory address of the flattened device tree + +Below you find the output of an example session starting GRUB. + + => load mmc 0:2 ${fdt_addr_r} boot/dtb + 29830 bytes read in 14 ms (2 MiB/s) + => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi + reading efi/debian/grubaa64.efi + 120832 bytes read in 7 ms (16.5 MiB/s) + => bootefi ${kernel_addr_r} ${fdt_addr_r} + +The environment variable 'bootargs' is passed as load options in the UEFI system +table. The Linux kernel EFI stub uses the load options as command line +arguments. + +### Executing the boot manager + +The UEFI specfication foresees to define boot entries and boot sequence via UEFI +variables. Booting according to these variables is possible via + + bootefi bootmgr [fdt address] + +As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at +runtime. + +### Executing the built in hello world application + +A hello world UEFI application can be built with + + CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y + +It can be embedded into the U-Boot binary with + + CONFIG_CMD_BOOTEFI_HELLO=y + +The bootefi command is used to start the embedded hello world application. + + bootefi hello [fdt address] + +Below you find the output of an example session. + + => bootefi hello ${fdtcontroladdr} + ## Starting EFI application at 01000000 ... + WARNING: using memory device/image path, this may confuse some payloads! + Hello, world! + Running on UEFI 2.7 + Have SMBIOS table + Have device tree + Load options: root=/dev/sdb3 init=/sbin/init rootwait ro + ## Application terminated, r = 0 + +The environment variable fdtcontroladdr points to U-Boot's internal device tree +(if available). + +### Executing the built-in selftest + +An UEFI selftest suite can be embedded in U-Boot by building with + + CONFIG_CMD_BOOTEFI_SELFTEST=y + +For testing the UEFI implementation the bootefi command can be used to start the +selftest. + + bootefi selftest [fdt address] + +The environment variable 'efi_selftest' can be used to select a single test. If +it is not provided all tests are executed except those marked as 'on request'. +If the environment variable is set to 'list' a list of all tests is shown. + +Below you can find the output of an example session. + + => setenv efi_selftest simple network protocol + => bootefi selftest + Testing EFI API implementation + Selected test: 'simple network protocol' + Setting up 'simple network protocol' + Setting up 'simple network protocol' succeeded + Executing 'simple network protocol' + DHCP Discover + DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02) + as broadcast message. + Executing 'simple network protocol' succeeded + Tearing down 'simple network protocol' + Tearing down 'simple network protocol' succeeded + Boot services terminated + Summary: 0 failures + Preparing for reset. Press any key. + +## The UEFI life cycle + +After the U-Boot platform has been initialized the UEFI API provides two kinds +of services + +* boot services and +* runtime services. + +The API can be extended by loading UEFI drivers which come in two variants + +* boot drivers and +* runtime drivers. + +UEFI drivers are installed with U-Boot's bootefi command. With the same command +UEFI applications can be executed. + +Loaded images of UEFI drivers stay in memory after returning to U-Boot while +loaded images of applications are removed from memory. + +An UEFI application (e.g. an operating system) that wants to take full control +of the system calls ExitBootServices. After a UEFI application calls +ExitBootServices + +* boot services are not available anymore +* timer events are stopped +* the memory used by U-Boot except for runtime services is released +* the memory used by boot time drivers is released + +So this is a point of no return. Afterwards the UEFI application can only return +to U-Boot by rebooting. + +## The UEFI object model + +UEFI offers a flexible and expandable object model. The objects in the UEFI API +are devices, drivers, and loaded images. These objects are referenced by +handles. + +The interfaces implemented by the objects are referred to as protocols. These +are identified by GUIDs. They can be installed and uninstalled by calling the +appropriate boot services. + +Handles are created by the InstallProtocolInterface or the +InstallMultipleProtocolinterfaces service if NULL is passed as handle. + +Handles are deleted when the last protocol has been removed with the +UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service. + +Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation +of device nodes. By their device paths all devices of a system are arranged in a +tree. + +Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect +a driver to devices (which are referenced as controllers in this context). + +Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta +information about the image and a pointer to the unload callback function. + +## The UEFI events + +In the UEFI terminology an event is a data object referencing a notification +function which is queued for calling when the event is signaled. The following +types of events exist: + +* periodic and single shot timer events +* exit boot services events, triggered by calling the ExitBootServices() service +* virtual address change events +* memory map change events +* read to boot events +* reset system events +* system table events +* events that are only triggered programmatically + +Events can be created with the CreateEvent service and deleted with CloseEvent +service. + +Events can be assigned to an event group. If any of the events in a group is +signaled, all other events in the group are also set to the signaled state. + +## The UEFI driver model + +A driver is specific for a single protocol installed on a device. To install a +driver on a device the ConnectController service is called. In this context +controller refers to the device for which the driver is installed. + +The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This +protocol has has three functions: + +* supported - determines if the driver is compatible with the device +* start - installs the driver by opening the relevant protocol with + attribute EFI_OPEN_PROTOCOL_BY_DRIVER +* stop - uninstalls the driver + +The driver may create child controllers (child devices). E.g. a driver for block +IO devices will create the device handles for the partitions. The child +controllers will open the supported protocol with the attribute +EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. + +A driver can be detached from a device using the DisconnectController service. + +## U-Boot devices mapped as UEFI devices + +Some of the U-Boot devices are mapped as UEFI devices + +* block IO devices +* console +* graphical output +* network adapter + +As of U-Boot 2018.03 the logic for doing this is hard coded. + +The development target is to integrate the setup of these UEFI devices with the +U-Boot driver model. So when a U-Boot device is discovered a handle should be +created and the device path protocol and the relevant IO protocol should be +installed. The UEFI driver then would be attached by calling ConnectController. +When a U-Boot device is removed DisconnectController should be called. + +## UEFI devices mapped as U-Boot devices + +UEFI drivers binaries and applications may create new (virtual) devices, install +a protocol and call the ConnectController service. Now the matching UEFI driver +is determined by iterating over the implementations of the +EFI_DRIVER_BINDING_PROTOCOL. + +It is the task of the UEFI driver to create a corresponding U-Boot device and to +proxy calls for this U-Boot device to the controller. + +In U-Boot 2018.03 this has only been implemented for block IO devices. + +### UEFI uclass + +An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that +takes care of initializing the UEFI drivers and providing the +EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers. + +A linker created list is used to keep track of the UEFI drivers. To create an +entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying +UCLASS_EFI as the ID of its uclass, e.g. + + /* Identify as UEFI driver */ + U_BOOT_DRIVER(efi_block) = { + .name = "EFI block driver", + .id = UCLASS_EFI, + .ops = &driver_ops, + }; + +The available operations are defined via the structure struct efi_driver_ops. + + struct efi_driver_ops { + const efi_guid_t *protocol; + const efi_guid_t *child_protocol; + int (*bind)(efi_handle_t handle, void *interface); + }; + +When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the +uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver. +In the start() function the bind() function of the UEFI driver is called after +checking the GUID. +The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child +controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03 +this is not yet completely implemented.) + +### UEFI block IO driver + +The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL. + +When connected it creates a new U-Boot block IO device with interface type +IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the +EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the +software iPXE to boot from iSCSI network drives [3]. + +This driver is only available if U-Boot is configured with + + CONFIG_BLK=y + CONFIG_PARTITIONS=y + +## TODOs as of U-Boot 2018.03 + +* unimplemented or incompletely implemented boot services + * Exit - call unload function, unload applications only + * ReinstallProtocolInterface + * UnloadImage + +* unimplemented events + * EVT_RUNTIME + * EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE + * event groups + +* data model + * manage events in a linked list + * manage configuration tables in a linked list + +* UEFI drivers + * support DisconnectController for UEFI block devices. + +* support for CONFIG_EFI_LOADER in the sandbox (CONFIG_SANDBOX=y) + +* UEFI variables + * persistence + * runtime support + +* support bootefi booting ARMv7 in non-secure mode (CONFIG_ARMV7_NONSEC=y) + +## Links + +* [1](http://uefi.org/specifications) + 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 diff --git a/doc/README.vxworks b/doc/README.vxworks index 3433e4f3ae..3239c5bb11 100644 --- a/doc/README.vxworks +++ b/doc/README.vxworks @@ -17,9 +17,7 @@ For booting old kernels (6.9.x) on PowerPC and ARM, and all kernel versions on other architectures, 'bootvx' shall be used. For booting VxWorks 7 kernels on PowerPC and ARM, 'bootm' shall be used. -64-bit x86 kernel cannot be loaded as of today. - -VxWork 7 on PowerPC and ARM +VxWorks 7 on PowerPC and ARM --------------------------- From VxWorks 7, VxWorks starts adopting device tree as its hardware decription mechansim (for PowerPC and ARM), thus requiring boot interface changes. @@ -30,11 +28,11 @@ the ePAPR standard, which is shown below (see ePAPR for more details): void (*kernel_entry)(fdt_addr, 0, 0, EPAPR_MAGIC, boot_IMA, 0, 0) -For ARM, the calling convention is show below: +For ARM, the calling convention is shown below: void (*kernel_entry)(void *fdt_addr) -When booting new VxWorks kernel (uImage format), the parameters passed to bootm +When booting a VxWorks 7 kernel (uImage format), the parameters passed to bootm is like below: bootm <kernel image address> - <device tree address> @@ -46,7 +44,7 @@ board-specific address before loading VxWorks. U-Boot supplies its address via "bootaddr" environment variable. To check where the bootline should be for a specific board, go to the VxWorks BSP for that board, and look for a parameter called BOOT_LINE_ADRS. Assign its value to "bootaddr". A typical -value for "bootaddr" is 0x101200. +value for "bootaddr" on an x86 board is 0x101200. If a "bootargs" variable is defined, its content will be copied to the memory location pointed by "bootaddr" as the kernel bootline. If "bootargs" is not @@ -67,19 +65,34 @@ look like VxWorks hangs somewhere as nothing outputs on the serial console. x86-specific information ------------------------ -Before loading an x86 kernel, two additional environment variables need to be -provided. They are "e820data" and "e820info", which represent the address of -E820 table and E820 information (defined by VxWorks) in system memory. - -Check VxWorks kernel configuration to look for BIOS_E820_DATA_START and -BIOS_E820_INFO_START, and assign their values to "e820data" and "e820info" -accordingly. If neither of these two are supplied, U-Boot assumes a default -location at 0x4000 for "e820data" and 0x4a00 for "e820info". Typical values -for "e820data" and "e820info" are 0x104000 and 0x104a00. But there is one -exception on Intel Galileo, where "e820data" and "e820info" should be left -unset, which assume the default location for VxWorks. - -Note since currently U-Boot does not support ACPI yet, VxWorks kernel must +Before loading an x86 kernel, one additional environment variable need to be +provided. This is "vx_phys_mem_base", which represent the physical memory +base address of VxWorks. + +Check VxWorks kernel configuration to look for LOCAL_MEM_LOCAL_ADRS. For +VxWorks 7, this is normally a virtual address and you need find out its +corresponding physical address and assign its value to "vx_phys_mem_base". + +For boards on which ACPI is not supported by U-Boot yet, VxWorks kernel must be configured to use MP table and virtual wire interrupt mode. This requires INCLUDE_MPTABLE_BOOT_OP and INCLUDE_VIRTUAL_WIRE_MODE to be included in a VxWorks kernel configuration. + +Both 32-bit x86 and 64-bit x64 kernels can be loaded. + +There are two types of graphics console drivers in VxWorks. One is the 80x25 +VGA text mode driver. The other one is the EFI console bitmapped graphics mode +driver. To make these drivers function, U-Boot needs to load and run the VGA +BIOS of the graphics card first. + + - If the kernel is configured with 80x25 VGA text mode driver, + CONFIG_FRAMEBUFFER_SET_VESA_MODE must be unset in U-Boot. + - If the kernel is configured with bitmapped graphics mode driver, + CONFIG_FRAMEBUFFER_SET_VESA_MODE need remain set but care must be taken + at which VESA mode is to be set. The supported pixel format is 32-bit + RGBA, hence the available VESA mode can only be one of the following: + * FRAMEBUFFER_VESA_MODE_10F + * FRAMEBUFFER_VESA_MODE_112 + * FRAMEBUFFER_VESA_MODE_115 + * FRAMEBUFFER_VESA_MODE_118 + * FRAMEBUFFER_VESA_MODE_11B diff --git a/doc/README.x86 b/doc/README.x86 index 772e8d2a86..b1663a4111 100644 --- a/doc/README.x86 +++ b/doc/README.x86 @@ -46,7 +46,7 @@ Build Instructions for U-Boot as coreboot payload Building U-Boot as a coreboot payload is just like building U-Boot for targets on other architectures, like below: -$ make coreboot-x86_defconfig +$ make coreboot_defconfig $ make all Note this default configuration will build a U-Boot payload for the QEMU board. diff --git a/doc/device-tree-bindings/i2c/i2c.txt b/doc/device-tree-bindings/i2c/i2c.txt index ea918dd61d..de818d4713 100644 --- a/doc/device-tree-bindings/i2c/i2c.txt +++ b/doc/device-tree-bindings/i2c/i2c.txt @@ -12,6 +12,11 @@ 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. +- gpios = <sda ...>, <scl ...>; + pinctrl-names = "default", "gpio"; + pinctrl-0 = <&i2c_xfer>; + pinctrl-1 = <&i2c_gpio>; + Pin description for I2C bus software deblocking. Example @@ -26,3 +31,11 @@ i2c4: i2c@12ca0000 { ec-interrupt = <&gpx1 6 GPIO_ACTIVE_LOW>; }; }; + +&i2c1 { + pinctrl-names = "default", "gpio"; + pinctrl-0 = <&i2c1_xfer>; + pinctrl-1 = <&i2c1_gpio>; + gpios = <&gpio1 26 GPIO_ACTIVE_LOW>, /* SDA */ + <&gpio1 27 GPIO_ACTIVE_LOW>; /* SCL */ +}; diff --git a/doc/git-mailrc b/doc/git-mailrc index 5a365cddd9..e55a1cb1d9 100644 --- a/doc/git-mailrc +++ b/doc/git-mailrc @@ -15,6 +15,7 @@ alias abiessmann Andreas Bießmann <andreas@biessmann.org> alias abrodkin Alexey Brodkin <alexey.brodkin@synopsys.com> alias afleming Andy Fleming <afleming@gmail.com> alias ag Anatolij Gustschin <agust@denx.de> +alias agraf Alexander Graf <agraf@suse.de> alias alisonwang Alison Wang <alison.wang@freescale.com> alias angelo_ts Angelo Dureghello <angelo@sysam.it> alias bmeng Bin Meng <bmeng.cn@gmail.com> @@ -31,7 +32,7 @@ alias jhersh Joe Hershberger <joe.hershberger@ni.com> alias jwrdegoede Hans de Goede <hdegoede@redhat.com> alias kimphill Kim Phillips <kim.phillips@freescale.com> alias luka Luka Perkov <luka.perkov@sartura.hr> -alias lukma Lukasz Majewski <l.majewski@denx.de> +alias lukma Lukasz Majewski <lukma@denx.de> alias macpaul Macpaul Lin <macpaul@andestech.com> alias marex Marek Vasut <marex@denx.de> alias masahiro Masahiro Yamada <yamada.masahiro@socionext.com> @@ -120,6 +121,7 @@ alias x86 uboot, sjg, bmeng alias dm uboot, sjg alias cfi uboot, stroese alias dfu uboot, lukma +alias efi uboot, agraf alias eth uboot, jhersh alias kerneldoc uboot, marex alias fdt uboot, sjg |