From cbb607d2d9be44a5ded7a652e8e7646925adc1e0 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 30 Jul 2023 11:17:00 -0600 Subject: bootstd: Allow display of the x86 setup information Provide an option to dump this information if available. Move the funciion prototype to the common x86 header. Allow the command line to be left out since 'bootflow info' show this itself and it is not in the correct place in memory until the kernel is actually booted. Fix a badly aligned heading while we are here. Signed-off-by: Simon Glass --- doc/usage/cmd/bootflow.rst | 59 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst index a8af1f8f603..d53f8373eff 100644 --- a/doc/usage/cmd/bootflow.rst +++ b/doc/usage/cmd/bootflow.rst @@ -11,7 +11,7 @@ Synopis bootflow scan [-abelGH] [bootdev] bootflow list [-e] bootflow select [] - bootflow info [-d] + bootflow info [-ds] bootflow boot bootflow cmdline [set|get|clear|delete|auto] [] @@ -191,6 +191,8 @@ Error Use the `-d` flag to dump out the contents of the bootfile file. +The `-s` flag shows any x86 setup block, instead of the above. + bootflow boot ~~~~~~~~~~~~~ @@ -522,6 +524,61 @@ the cmdline is word-wrapped here and some parts of the command line are elided:: [ 0.000000] Command line: loglevel=7 ... usb-storage.quirks=13fe:6500:u earlycon=uart8250,mmio32,0xfe03e000,115200n8 [ 0.000000] x86/split lock detection: warning about user-space split_locks +This shows looking at x86 setup information:: + + => bootfl sel 0 + => bootfl i -s + Setup located at 77b56010: + + ACPI RSDP addr : 0 + E820: 2 entries + Addr Size Type + 0 1000 RAM + fffff000 1000 Reserved + Setup sectors : 1e + Root flags : 1 + Sys size : 63420 + RAM size : 0 + Video mode : ffff + Root dev : 0 + Boot flag : 0 + Jump : 66eb + Header : 53726448 + Kernel V2 + Version : 20d + Real mode switch : 0 + Start sys seg : 1000 + Kernel version : 38cc + @00003acc: + Type of loader : ff + unknown + Load flags : 1 + : loaded-high + Setup move size : 8000 + Code32 start : 100000 + Ramdisk image : 0 + Ramdisk size : 0 + Bootsect kludge : 0 + Heap end ptr : 5160 + Ext loader ver : 0 + Ext loader type : 0 + Command line ptr : 735000 + Initrd addr max : 7fffffff + Kernel alignment : 200000 + Relocatable kernel : 1 + Min alignment : 15 + : 200000 + Xload flags : 3 + : 64-bit-entry can-load-above-4gb + Cmdline size : 7ff + Hardware subarch : 0 + HW subarch data : 0 + Payload offset : 26e + Payload length : 612045 + Setup data : 0 + Pref address : 1000000 + Init size : 1383000 + Handover offset : 0 Return value -- cgit v1.2.3 From c279224ea6686a992b258b01e07fcadb7f0c7ecb Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 10 Aug 2023 19:33:18 -0600 Subject: bootstd: Add a command to read all files for a bootflow Some bootflows (such as EFI and ChromiumOS) delay reading the kernel until it is needed to boot. This saves time when scanning and avoids needing to allocate memory for something that may never be used. To permit reading of these files, add a new 'bootflow read' command. Signed-off-by: Simon Glass --- doc/usage/cmd/bootflow.rst | 80 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 79 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst index d53f8373eff..ead493d0aaf 100644 --- a/doc/usage/cmd/bootflow.rst +++ b/doc/usage/cmd/bootflow.rst @@ -12,6 +12,7 @@ Synopis bootflow list [-e] bootflow select [] bootflow info [-ds] + bootflow read bootflow boot bootflow cmdline [set|get|clear|delete|auto] [] @@ -194,10 +195,26 @@ Use the `-d` flag to dump out the contents of the bootfile file. The `-s` flag shows any x86 setup block, instead of the above. +bootflow read +~~~~~~~~~~~~~ + +This reads any files related to the bootflow. Some bootflows with large files +avoid doing this when the bootflow is scanned, since it uses a lot of memory +and takes extra time. The files are then automatically read when `bootflow boot` +is used. + +This command reads these files immediately. Typically this fills in the bootflow +`buf` property, which can be used to examine the bootflow. + +Note that reading the files does not result in any extra parsing, nor loading of +images in the files. This is purely used to read in the data ready for +booting, or examination. + + bootflow boot ~~~~~~~~~~~~~ -This boots the current bootflow. +This boots the current bootflow, reading any required files first. bootflow cmdline @@ -580,6 +597,67 @@ This shows looking at x86 setup information:: Init size : 1383000 Handover offset : 0 +This shows reading a bootflow to examine the kernel:: + + => bootfl i 0 + Name: + Device: emmc@1c,0.bootdev + Block dev: emmc@1c,0.blk + Method: cros + State: ready + Partition: 2 + Subdir: (none) + Filename: + Buffer: 0 + Size: 63ee00 (6548992 bytes) + OS: ChromeOS + Cmdline: console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off + X86 setup: 77b56010 + Logo: (none) + FDT: + Error: 0 + +Note that `Buffer` is 0 so it has not be read yet. Using `bootflow read`:: + + => bootfl read + => bootfl info + Name: + Device: emmc@1c,0.bootdev + Block dev: emmc@1c,0.blk + Method: cros + State: ready + Partition: 2 + Subdir: (none) + Filename: + Buffer: 77b7e400 + Size: 63ee00 (6548992 bytes) + OS: ChromeOS + Cmdline: console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off + X86 setup: 781b4400 + Logo: (none) + FDT: + Error: 0 + +Now the buffer can be accessed:: + + => md 77b7e400 + 77b7e400: 1186f6fc 40000002 b8fa0c75 00000018 .......@u....... + 77b7e410: c08ed88e a68dd08e 000001e8 000000e8 ................ + 77b7e420: ed815d00 00000021 62c280b8 89e80100 .]..!......b.... + 77b7e430: 22f7e8c4 c0850061 22ec850f eb890061 ..."a......"a... + 77b7e440: 0230868b 01480000 21d0f7c3 00fb81c3 ..0...H....!.... + 77b7e450: 7d010000 0000bb05 c3810100 00d4f000 ...}............ + 77b7e460: 8130858d 85890061 00618132 3095010f ..0.a...2.a....0 + 77b7e470: 0f006181 c883e020 e0220f20 e000bb8d .a.. ... ."..... + 77b7e480: c0310062 001800b9 8dabf300 62e000bb b.1............b + 77b7e490: 07878d00 89000010 00bb8d07 8d0062f0 .............b.. + 77b7e4a0: 00100787 0004b900 07890000 00100005 ................ + 77b7e4b0: 08c78300 8df37549 630000bb 0183b800 ....Iu.....c.... + 77b7e4c0: 00b90000 89000008 00000507 c7830020 ............ ... + 77b7e4d0: f3754908 e000838d 220f0062 0080b9d8 .Iu.....b..".... + 77b7e4e0: 320fc000 08e8ba0f c031300f b8d0000f ...2.....01..... + 77b7e4f0: 00000020 6ad8000f 00858d10 50000002 ......j.......P + Return value ------------ -- cgit v1.2.3 From 4bf49bade124c792e14952738db7b42fddad49af Mon Sep 17 00:00:00 2001 From: Roger Quadros Date: Sat, 5 Aug 2023 11:14:39 +0300 Subject: doc: board: ti: am64: Add boot flow diagram Add documenatation and boot flow diagram for AM64 EVM/SoC. Suggested-by: Nishanth Menon Signed-off-by: Roger Quadros Reviewed-by: Nishanth Menon Tested-by: Nishanth Menon #SK-AM64B --- doc/board/ti/am64x_evm.rst | 197 ++++ doc/board/ti/img/boot_diagram_am64.svg | 1702 ++++++++++++++++++++++++++++++++ doc/board/ti/k3.rst | 1 + 3 files changed, 1900 insertions(+) create mode 100644 doc/board/ti/am64x_evm.rst create mode 100644 doc/board/ti/img/boot_diagram_am64.svg (limited to 'doc') diff --git a/doc/board/ti/am64x_evm.rst b/doc/board/ti/am64x_evm.rst new file mode 100644 index 00000000000..8d3795eb326 --- /dev/null +++ b/doc/board/ti/am64x_evm.rst @@ -0,0 +1,197 @@ +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause +.. sectionauthor:: Nishanth Menon + +AM64 Platforms +============== + +Introduction: +------------- +The AM642 SoC belongs to the K3 Multicore SoC architecture platform, +providing advanced system integration to enable applications such as +Motor Drives, PLC, Remote IO and IoT Gateways. + +Some highlights of this SoC are: + +* Dual Cortex-A53s in a single cluster, two clusters of dual Cortex-R5F + MCUs, and a single Cortex-M4F. +* Two Gigabit Industrial Communication Subsystems (ICSSG). +* Integrated Ethernet switch supporting up to a total of two external + ports. +* PCIe-GEN2x1L, USB3/USB2, 2xCAN-FD, eMMC and SD, UFS, OSPI memory + controller, QSPI, I2C, eCAP/eQEP, ePWM, ADC, among other + peripherals. +* Centralized System Controller for Security, Power, and Resource + Management (DMSC). + +More details can be found in the Technical Reference Manual: + https://www.ti.com/lit/pdf/spruim2 + +Platform information: + +* AM64-EVM: https://www.ti.com/tool/TMDS64EVM +* AM64-SK: https://www.ti.com/tool/SK-AM64B + +Boot Flow: +---------- +Below is the pictorial representation of boot flow: + +.. image:: img/boot_diagram_am64.svg + +- Here TIFS acts as master and provides all the critical services. R5/A53 + requests TIFS to get these services done as shown in the above diagram. + +Sources: +-------- + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_boot_sources + :end-before: .. k3_rst_include_end_boot_sources + +Build procedure: +---------------- +0. Setup the environment variables: + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_common_env_vars_desc + :end-before: .. k3_rst_include_end_common_env_vars_desc + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_board_env_vars_desc + :end-before: .. k3_rst_include_end_board_env_vars_desc + +Set the variables corresponding to this platform: + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_common_env_vars_defn + :end-before: .. k3_rst_include_end_common_env_vars_defn +.. code-block:: bash + + $ export UBOOT_CFG_CORTEXR=am64x_evm_r5_defconfig + $ export UBOOT_CFG_CORTEXA=am64x_evm_a53_defconfig + $ export TFA_BOARD=lite + $ # we dont use any extra TFA parameters + $ unset TFA_EXTRA_ARGS + $ export OPTEE_PLATFORM=k3-am64x + $ # we dont use any extra TFA parameters + $ unset OPTEE_EXTRA_ARGS + +.. am64x_evm_rst_include_start_build_steps + +1. Trusted Firmware-A: + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_build_steps_tfa + :end-before: .. k3_rst_include_end_build_steps_tfa + + +2. OP-TEE: + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_build_steps_optee + :end-before: .. k3_rst_include_end_build_steps_optee + +3. U-Boot: + +* 4.1 R5: + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_build_steps_spl_r5 + :end-before: .. k3_rst_include_end_build_steps_spl_r5 + +* 4.2 A53: + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_build_steps_uboot + :end-before: .. k3_rst_include_end_build_steps_uboot +.. am64x_evm_rst_include_end_build_steps + +Target Images +-------------- +In order to boot we need tiboot3.bin, tispl.bin and u-boot.img. Each SoC +variant (GP, HS-FS, HS-SE) requires a different source for these files. + + - GP + + * tiboot3-am64x-gp-evm.bin from step 3.1 + * tispl.bin_unsigned, u-boot.img_unsigned from step 3.2 + + - HS-FS + + * tiboot3-am64x-hs-fs-evm.bin from step 3.1 + * tispl.bin, u-boot.img from step 3.2 + + - HS-SE + + * tiboot3-am64x-hs-evm.bin from step 3.1 + * tispl.bin, u-boot.img from step 3.2 + +Image formats: +-------------- + +- tiboot3.bin + +.. image:: img/multi_cert_tiboot3.bin.svg + +- tispl.bin + +.. image:: img/nodm_tispl.bin.svg + +Switch Setting for Boot Mode +---------------------------- + +Boot Mode pins provide means to select the boot mode and options before the +device is powered up. After every POR, they are the main source to populate +the Boot Parameter Tables. + +The following table shows some common boot modes used on AM64 platform. More +details can be found in the Technical Reference Manual: +https://www.ti.com/lit/pdf/spruim2 under the `Boot Mode Pins` section. + +.. list-table:: Boot Modes for AM64x-EVM + :widths: 16 16 16 + :header-rows: 1 + + * - Switch Label + - SW2: 12345678 + - SW3: 12345678 + + * - SD/MMC + - 11000010 + - 01000000 + + * - xSPI/SFDP (OSPI) + - 11001110 + - 01000000 + + * - UART + - 11011100 + - 00000000 + +.. note :: + + For SW2 and SW3, the switch state in the "ON" position = 1. + +.. list-table:: Boot Modes for AM64x-SK + :widths: 16 16 16 + :header-rows: 1 + + * - Switch Label + - SW2: 12345678 + - SW3: 12345678 + + * - SD/MMC + - 00000010 + - 01000011 + + * - xSPI/SFDP (OSPI) + - 00000010 + - 01110011 + + * - UART + - 00000000 + - 00111011 + +.. note :: + + For SW2 and SW3, the switch state in the "ON" position = 1. + Boot bits on SK is reversed bits to the bootmode signals diff --git a/doc/board/ti/img/boot_diagram_am64.svg b/doc/board/ti/img/boot_diagram_am64.svg new file mode 100644 index 00000000000..9c922a59fa4 --- /dev/null +++ b/doc/board/ti/img/boot_diagram_am64.svg @@ -0,0 +1,1702 @@ + + + + + + + + + + + + + + + + + Cortex-R + + + + Cortex-R + + + + + + + + + + ROM + + + + ROM + + + + + + + + + + Cortex-R SPL + + + + Cortex-R SPL + + + + + + + + + Load and auth tiboot3.bin + + + + Load and auth t... + + + + + + + + + Load system + +config data + + + + Load system... + + + + + + + + + DDR Config + + + + DDR Config + + + + + + + + + Load tispl.bin + + + + Load tispl.bin + + + + + + + + + Start Cortex-A + + + + Start Cortex-A + + + + + + + + + + Start Cortex-A + + + + Start Cort... + + + + + + + + + + + + + + + + + + Cortex-A + + + + Cortex-A + + + + + + + + + + + + + Cortex-R/M + +C6x/C7x + + + + Cortex-R/M... + + + + + + + + + + Aux f/w + + + + Aux f/w + + + + + + + + + + TIFS/DMSC + + + + TIFS/DMSC + + + + + + + + + + ROM + + + + ROM + + + + + + + + + + + Start SYSFW + + + + Start SYSFW + + + + + + + + + SYSFW + + + + SYSFW + + + + + + + + + + Security Enclave Boot Processor + + + + Security Enclave Boot... + + + + + + + + + + Boot Loader + +Processor + + + + Boot Loader... + + + + + + + + + + Main CPU + + + + Main CPU + + + + + + + + + + Auxiliary + +Processor + + + + Auxiliary... + + + + + + + + + + H/w Seq: Reset rls + + + + H/w Seq: Reset rls + + + + + + + + + + Auth tiboot3.bin + + + + Auth tiboo... + + + + + + + + + + Release Reset + + + + Release Re... + + + + + + + + + + Load system config data + + + + Load syste... + + + + + + + + + Start SYSFW + + + + Start SYSFW + + + + + + + + + + Release Reset + + + + Release Re... + + + + + + + + + TF-A + + + + TF-A + + + + + + + + + + OP-TEE + + + + OP-TEE + + + + + + + + + + Cortex A SPL + + + + Cortex A SPL + + + + + + + + + + U-Boot + + + + U-Boot + + + + + + + + + Load u-boot.img + + + + Load u-boot.img + + + + + + + + + Load Aux core f/w + +(optional) + + + + Load Aux core f/w... + + + + + + + + + Start Aux core + +(optional) + + + + Start Aux core... + + + + + + + + + + Release Reset + + + + Release Re... + + + + + + + Text is not SVG - cannot display + + + diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index d2f86b0a11a..02cfd931688 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -32,6 +32,7 @@ K3 Based SoCs am62x_sk ../toradex/verdin-am62 + am64x_evm am65x_evm j7200_evm j721e_evm -- cgit v1.2.3 From 4d6641d5db85827e9efeab4cec84befbee1cd9f6 Mon Sep 17 00:00:00 2001 From: Alper Nebi Yasak Date: Mon, 14 Aug 2023 20:39:41 +0300 Subject: arm: qemu: Enable Bochs video support Commit 716161663ec49 ("riscv: qemu: Enable Bochs video support") enables a video console for QEMU RISC-V virtual machines using an emulated Bochs VGA card. Similarly, enable it for ARM virtual machines as well. Signed-off-by: Alper Nebi Yasak Reviewed-by: Bin Meng --- doc/board/emulation/qemu-arm.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc') diff --git a/doc/board/emulation/qemu-arm.rst b/doc/board/emulation/qemu-arm.rst index b42d924cc66..1108fe5f818 100644 --- a/doc/board/emulation/qemu-arm.rst +++ b/doc/board/emulation/qemu-arm.rst @@ -67,6 +67,10 @@ Additional persistent U-Boot environment support can be added as follows: Additional peripherals that have been tested to work in both U-Boot and Linux can be enabled with the following command line parameters: +- To add a video console, remove "-nographic" and add e.g.:: + + -serial stdio -device VGA + - To add a Serial ATA disk via an Intel ICH9 AHCI controller, pass e.g.:: -drive if=none,file=disk.img,format=raw,id=mydisk \ -- cgit v1.2.3 From 05e2fa79310ab30dd3e3fe522333aef3cfb1c421 Mon Sep 17 00:00:00 2001 From: Alper Nebi Yasak Date: Mon, 14 Aug 2023 20:39:43 +0300 Subject: arm: qemu: Enable usb keyboard as an input device Commit 02be57caf730 ("riscv: qemu: Enable usb keyboard as an input device") adds PCI xHCI support to QEMU RISC-V virtual machines and enables using a USB keyboard as one of the input devices. Similarly, enable those for ARM virtual machines as well. Signed-off-by: Alper Nebi Yasak Reviewed-by: Simon Glass Reviewed-by: Bin Meng --- doc/board/emulation/qemu-arm.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc') diff --git a/doc/board/emulation/qemu-arm.rst b/doc/board/emulation/qemu-arm.rst index 1108fe5f818..8ec5349fc9e 100644 --- a/doc/board/emulation/qemu-arm.rst +++ b/doc/board/emulation/qemu-arm.rst @@ -84,6 +84,10 @@ can be enabled with the following command line parameters: -device usb-ehci,id=ehci +- To add a USB keyboard attached to an emulated xHCI controller, pass e.g.:: + + -device qemu-xhci,id=xhci -device usb-kbd,bus=xhci.0 + - To add an NVMe disk, pass e.g.:: -drive if=none,file=disk.img,id=mydisk -device nvme,drive=mydisk,serial=foo -- cgit v1.2.3 From 8def269365c81e548c4df3e594cb23aa088b6b21 Mon Sep 17 00:00:00 2001 From: Alper Nebi Yasak Date: Mon, 14 Aug 2023 20:39:44 +0300 Subject: doc: qemu: arm: Add a section on booting Linux distros Add an example qemu-system-aarch64 command that can make U-Boot on QEMU boot into the Debian Installer, along with resulting console messages from U-Boot, based on the existing documentation section for the x86 version. Signed-off-by: Alper Nebi Yasak --- doc/board/emulation/qemu-arm.rst | 68 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) (limited to 'doc') diff --git a/doc/board/emulation/qemu-arm.rst b/doc/board/emulation/qemu-arm.rst index 8ec5349fc9e..78bcc3ee44c 100644 --- a/doc/board/emulation/qemu-arm.rst +++ b/doc/board/emulation/qemu-arm.rst @@ -98,6 +98,74 @@ can be enabled with the following command line parameters: These have been tested in QEMU 2.9.0 but should work in at least 2.5.0 as well. +Booting distros +--------------- + +It is possible to install and boot a standard Linux distribution using +qemu_arm64 by setting up a root disk:: + + qemu-img create root.img 20G + +then using the installer to install. For example, with Debian 12:: + + qemu-system-aarch64 \ + -machine virt -cpu cortex-a53 -m 4G -smp 4 \ + -bios u-boot.bin \ + -serial stdio -device VGA \ + -nic user,model=virtio-net-pci \ + -device virtio-rng-pci \ + -device qemu-xhci,id=xhci \ + -device usb-kbd -device usb-tablet \ + -drive if=virtio,file=debian-12.0.0-arm64-netinst.iso,format=raw,readonly=on,media=cdrom \ + -drive if=virtio,file=root.img,format=raw,media=disk + +The output will be something like this:: + + U-Boot 2023.10-rc2-00075-gbe8fbe718e35 (Aug 11 2023 - 08:38:49 +0000) + + DRAM: 4 GiB + Core: 51 devices, 14 uclasses, devicetree: board + Flash: 64 MiB + Loading Environment from Flash... *** Warning - bad CRC, using default environment + + In: serial,usbkbd + Out: serial,vidconsole + Err: serial,vidconsole + Bus xhci_pci: Register 8001040 NbrPorts 8 + Starting the controller + USB XHCI 1.00 + scanning bus xhci_pci for devices... 3 USB Device(s) found + Net: eth0: virtio-net#32 + Hit any key to stop autoboot: 0 + Scanning for bootflows in all bootdevs + Seq Method State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + Scanning global bootmeth 'efi_mgr': + Scanning bootdev 'fw-cfg@9020000.bootdev': + fatal: no kernel available + scanning bus for devices... + Scanning bootdev 'virtio-blk#34.bootdev': + 0 efi ready virtio 2 virtio-blk#34.bootdev.par efi/boot/bootaa64.efi + ** Booting bootflow 'virtio-blk#34.bootdev.part_2' with efi + Using prior-stage device tree + Failed to load EFI variables + Error: writing contents + ** Unable to write file ubootefi.var ** + Failed to persist EFI variables + Missing TPMv2 device for EFI_TCG_PROTOCOL + Booting /efi\boot\bootaa64.efi + Error: writing contents + ** Unable to write file ubootefi.var ** + Failed to persist EFI variables + Welcome to GRUB! + +Standard boot looks through various available devices and finds the virtio +disks, then boots from the first one. After a second or so the grub menu appears +and you can work through the installer flow normally. + +After the installation, you can boot into the installed system by running QEMU +again without the drive argument corresponding to the installer CD image. + Enabling TPMv2 support ---------------------- -- cgit v1.2.3 From d5737b3f6a0239caf2dd5578a4bc8ebfccfdee3b Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:28 -0600 Subject: expo: Tidy up the expo.py tool and usage Tidy up this tool a little: - define which arguments are needed - split the enum values out into a header file - warn if no enum values are found - display the dtc error if something goes wrong - avoid a Python traceback on error Signed-off-by: Simon Glass --- doc/develop/expo.rst | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) (limited to 'doc') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 2ac4af232da..0643283ae48 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -367,22 +367,27 @@ strings are provided inline in the nodes where they are used. :: - #define ID_PROMPT 1 - #define ID_SCENE1 2 - #define ID_SCENE1_TITLE 3 - - #define ID_CPU_SPEED 4 - #define ID_CPU_SPEED_TITLE 5 - #define ID_CPU_SPEED_1 6 - #define ID_CPU_SPEED_2 7 - #define ID_CPU_SPEED_3 8 - - #define ID_POWER_LOSS 9 - #define ID_AC_OFF 10 - #define ID_AC_ON 11 - #define ID_AC_MEMORY 12 - - #define ID_DYNAMIC_START 13 + /* this comment is parsed by the expo.py tool to insert the values below + + enum { + ZERO, + ID_PROMPT, + ID_SCENE1, + ID_SCENE1_TITLE, + + ID_CPU_SPEED, + ID_CPU_SPEED_TITLE, + ID_CPU_SPEED_1, + ID_CPU_SPEED_2, + ID_CPU_SPEED_3, + + ID_POWER_LOSS, + ID_AC_OFF, + ID_AC_ON, + ID_AC_MEMORY, + + ID_DYNAMIC_START, + */ &cedit { dynamic-start = ; -- cgit v1.2.3 From c5aacf5ef87610d92bf0651b2a935c37778768d2 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:29 -0600 Subject: expo: Add documentation for the configuration editor This is mentioned in passing in the 'cedit' command. Its file format is described under `expo`. But it would be better if it had its own entry in the documentation. Add a new 'cedit' entry with a few details about this feature. Signed-off-by: Simon Glass --- doc/develop/cedit.rst | 147 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/develop/expo.rst | 3 + doc/develop/index.rst | 1 + doc/usage/cmd/cedit.rst | 2 + 4 files changed, 153 insertions(+) create mode 100644 doc/develop/cedit.rst (limited to 'doc') diff --git a/doc/develop/cedit.rst b/doc/develop/cedit.rst new file mode 100644 index 00000000000..48262ee535e --- /dev/null +++ b/doc/develop/cedit.rst @@ -0,0 +1,147 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Configuration Editor +==================== + +Introduction +------------ + +U-Boot provides a configuration editor which allows settings to be changed in +a GUI or text environment. + + +This feature is still in development and has a number of limitations. For +example, cedit only supports menu items (there is no numeric or text entry), +provides no support for colour text and does not support scrolling. Still it is +possible to use it for simple applications. + + +Overview +-------- + +The configuration editor makes use of :doc:`expo` to build a description of the +configuration screens and allow user to interact with it. + +To create a single-scene cedit for your application: + +#. Design the scene, i.e. the objects that need to be present and what their + possible values are + +#. Enter this in .dts format + +#. Create a header file containing the IDs + +#. Run the 'expo.py' tool to generate a .dtb file containing the layout, which + can be used by U-Boot + +#. Use the :doc:`../usage/cmd/cedit` to create the cedit, read the settings, + present the cedit to the user and save the settings afterwards. + +Each of these is described in a separate section. See :ref:`expo_example` for +an example file. + + +Design a scene +-------------- + +Using a piece of paper or a drawing tool, lay out the objects you want in your +scene. Typically you will use the default layout engine, which simply puts items +one after the other from top to bottom. So use a single column and show the +prompt and value for each object. + +For menu items, show one of the values, but keep in mind what else you need. + + +Create an expo-format file +-------------------------- + +The description is in the form of a devicetree file, as documented at +:ref:`expo_format`. Since everything in an expo has an ID number (an integer +greater than 1) the description is written terms of these IDs. They each have +an enum value. which is typically taken care of by the `expo.py` tool. + +The expo should have a `scenes` node with a named scene as a subnode. Within the +scene, add properties for the scene, then a subnode for each object in the +scene. + +All object nodes require an `id` value and a `type` property. Other properties +depend on the type. For example, a menu has a `title` and an `item-label` list +proving the text for the menu items, as well as an `item-id` list providing the +ID of each menu item, so it can be selected. + +Text properties may have two variants. For example `title` specifies the title +of a menu, but you can instead use `title-id` to specify the string ID to use as +the title. String are defined in a separate area, common to the whole expo, +which contains a subnode for each string. Within that subnode are the ID and the +`value` (i.e. the text). For now only English is supported, but in future it may +be possible to append a language identifier to provide other values (e.g. +'value-es' for Spanish). + + +Create an ID header-file +------------------------ + +Expo needs to know the integer value to use for every ID referenced in your +expo-format file. For example, if you have defined a `cpu-speed` node with an +id of `ID_CPU_SPEED`, then Expo needs to know the value of `ID_CPU_SPEED`. + +When you write C code to use the expo, you may need to know the IDs. For +example, to find which value the user selected in `cpu-speed` menu, you must +use the `ID_CPU_SPEED` ID. The ID is the only way to refer to anything in Expo. + +Since we need a shared set of IDs, it is best to have a header file containing +them. Expo supports doing this with an enum, where every ID is listed in the +enum:: + + enum { + ZERO, + + ID_PROMPT, + + ID_SCENE1, + ID_SCENE1_TITLE, + ... + }; + +The C compiler can parse this directly. The `expo.py` tool parses it for expo. + +Create a header file containing every ID mentioned in your expo. Try to group +related things together. + + +Build the expo layout +--------------------- + +Use the `expo.py` tool to build a .dtb for your expo:: + + ./tools/expo.py -e expo_ids.h -l expo_layout.dts -o expo.dtb + +This uses the enum in the provided header file to get the ID numbers, grabs +the `.dts` file, inserts the ID numbers and then uses the devicetree compiler to +build a `.dtb` file. + +If you get an error:: + + Devicetree compiler error: + Error: :9.19-20 syntax error + FATAL ERROR: Unable to parse input tree + +that means that something is wrong with your syntax, or perhaps you have an ID +in the `.dts` file that is not mentioned in your enum. Check both files and try +again. + + +Use the command interface +------------------------- + +See the :doc:`../usage/cmd/cedit` command for information on available commands. +Typically you will use `cedit load` to load the `.dtb` file and `cedit run` to +let the user interact with it. + + +Multiple scenes +--------------- + +Expo supports multiple scenes but has no pre-determined way of moving between +them. You could use selection of a menu item as a signal to change the scene, +but this is not currently implemented in the cedit code (see `cedit_run()`). diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 0643283ae48..fde91494799 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -358,6 +358,9 @@ The `expo_arrange()` function can be called to arrange the expo objects in a suitable manner. For each scene it puts the title at the top, the prompt at the bottom and the objects in order from top to bottom. + +.. _expo_example: + Expo format example ~~~~~~~~~~~~~~~~~~~ diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 5b230d0321f..0d12484ace8 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -38,6 +38,7 @@ Implementation driver-model/index environment expo + cedit event global_data logging diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 8e1110c7c77..3d815bd27af 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -22,6 +22,8 @@ It makes use of the expo subsystem. The description is in the form of a devicetree file, as documented at :ref:`expo_format`. +See :doc:`../../develop/cedit` for information about the configuration editor. + Example ------- -- cgit v1.2.3 From 2045ca5c1f51d054579d0886184b6f245b8a134e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:30 -0600 Subject: expo: Move cedit theme under bootstd This is related to standard boot, so put it under the same node. This may simplify schema upstreaming later. Mention themes in the documentation while we are here. Signed-off-by: Simon Glass --- doc/develop/cedit.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc') diff --git a/doc/develop/cedit.rst b/doc/develop/cedit.rst index 48262ee535e..8f0a554ae91 100644 --- a/doc/develop/cedit.rst +++ b/doc/develop/cedit.rst @@ -145,3 +145,10 @@ Multiple scenes Expo supports multiple scenes but has no pre-determined way of moving between them. You could use selection of a menu item as a signal to change the scene, but this is not currently implemented in the cedit code (see `cedit_run()`). + + +Themes +------ + +The configuration editor uses simple expo themes. The theme is read from +`/bootstd/cedit-theme` in the devicetree. -- cgit v1.2.3 From d65ccbb60138a34dfec583397666ceddab85e16d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:31 -0600 Subject: doc: Expand documentation for the cedit command Add a little information about each subcommand. Signed-off-by: Simon Glass --- doc/usage/cmd/cedit.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'doc') diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 3d815bd27af..d34a220797e 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -24,6 +24,21 @@ The description is in the form of a devicetree file, as documented at See :doc:`../../develop/cedit` for information about the configuration editor. +cedit load +~~~~~~~~~~ + +Loads a configuration-editor description from a file. It creates a new cedit +structure ready for use. Initially no settings are read, so default values are +used for each object. + +cedit run +~~~~~~~~~ + +Runs the default configuration-editor event loop. This is very simple, just +accepting character input and moving through the objects under user control. +The implementation is at `cedit_run()`. + + Example ------- -- cgit v1.2.3 From 2dee81fe5f4a6427ba48fe17ff017930ddf3b4e4 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:33 -0600 Subject: expo: cedit: Support writing settings to a file Support writing settings from an expo into a file in FDT format. It consists of a single node with a two properties for each sceneitem, one with tag ID chosen by the user and another for its text value. Signed-off-by: Simon Glass --- doc/usage/cmd/cedit.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'doc') diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index d34a220797e..0581594831f 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -10,6 +10,7 @@ Synopis cedit load cedit run + cedit write_fdt Description ----------- @@ -38,6 +39,12 @@ Runs the default configuration-editor event loop. This is very simple, just accepting character input and moving through the objects under user control. The implementation is at `cedit_run()`. +cedit write_fdt +~~~~~~~~~~~~~~~ + +Writes the current user settings to a devicetree file. For each menu item the +selected ID and its text string are written. + Example ------- @@ -46,3 +53,15 @@ Example => cedit load hostfs - fred.dtb => cedit run + => cedit write_fdt hostfs - settings.dtb + +That results in:: + + / { + cedit-values { + cpu-speed = <0x00000006>; + cpu-speed-str = "2 GHz"; + power-loss = <0x0000000a>; + power-loss-str = "Always Off"; + }; + } -- cgit v1.2.3 From 472317cb12e534f56b631365987934960dfb0a3f Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:34 -0600 Subject: expo: cedit: Support reading settings from a file Add a command to read cedit settings from a devicetree file. Signed-off-by: Simon Glass --- doc/usage/cmd/cedit.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc') diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 0581594831f..0a9f620b59b 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -11,6 +11,7 @@ Synopis cedit load cedit run cedit write_fdt + cedit read_fdt Description ----------- @@ -45,6 +46,11 @@ cedit write_fdt Writes the current user settings to a devicetree file. For each menu item the selected ID and its text string are written. +cedit read_fdt +~~~~~~~~~~~~~~ + +Reads the user settings from a devicetree file and updates the cedit with those +settings. Example ------- @@ -65,3 +71,5 @@ That results in:: power-loss-str = "Always Off"; }; } + + => cedit read_fdt hostfs - settings.dtb -- cgit v1.2.3 From fc9c0e0771cad76b24f73bb64c105b6ea39721ca Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:35 -0600 Subject: expo: cedit: Support writing settings to environment vars Add a command to write cedit settings to environment variables so that they can be stored with 'saveenv'. Signed-off-by: Simon Glass --- doc/usage/cmd/cedit.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'doc') diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 0a9f620b59b..426470a82ac 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -12,6 +12,7 @@ Synopis cedit run cedit write_fdt cedit read_fdt + cedit write_env [-v] Description ----------- @@ -52,6 +53,19 @@ cedit read_fdt Reads the user settings from a devicetree file and updates the cedit with those settings. +cedit write_env +~~~~~~~~~~~~~~~ + +Writes the settings to environment variables. For each menu item the selected +ID and its text string are written, similar to: + + setenv c. + setenv c.-str + +The `-v` flag enables verbose mode, where each variable is printed before it is +set. + + Example ------- @@ -73,3 +87,14 @@ That results in:: } => cedit read_fdt hostfs - settings.dtb + +This shows settings being stored in the environment:: + + => cedit write_env -v + => print + ... + c.cpu-speed=6 + c.cpu-speed-str=2 GHz + c.power-loss=10 + c.power-loss-str=Always Off + ... -- cgit v1.2.3 From bcf2b7202e960e7fb3df8d5e8ed0d6fa00a5a9fa Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:36 -0600 Subject: expo: cedit: Support reading settings from environment vars Add a command to read cedit settings from environment variables so that they can be restored as part of the environment. Signed-off-by: Simon Glass --- doc/usage/cmd/cedit.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'doc') diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 426470a82ac..1f92b7306a7 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -13,6 +13,7 @@ Synopis cedit write_fdt cedit read_fdt cedit write_env [-v] + cedit read_env [-v] Description ----------- @@ -53,6 +54,16 @@ cedit read_fdt Reads the user settings from a devicetree file and updates the cedit with those settings. +cedit read_env +~~~~~~~~~~~~~~ + +Reads the settings from the environment variables. For each menu item ``, +cedit looks for a variable called `c.` with the ID of the selected menu +item. + +The `-v` flag enables verbose mode, where each variable is printed after it is +read. + cedit write_env ~~~~~~~~~~~~~~~ @@ -91,6 +102,10 @@ That results in:: This shows settings being stored in the environment:: => cedit write_env -v + c.cpu-speed=7 + c.cpu-speed-str=2.5 GHz + c.power-loss=12 + c.power-loss-str=Memory => print ... c.cpu-speed=6 @@ -98,3 +113,7 @@ This shows settings being stored in the environment:: c.power-loss=10 c.power-loss-str=Always Off ... + + => cedit read_env -v + c.cpu-speed=7 + c.power-loss=12 -- cgit v1.2.3 From eb6c71b56282d3054dbffb83793e7d2c6745578e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:37 -0600 Subject: expo: cedit: Support writing settings to CMOS RAM Add a command to write cedit settings to CMOS RAM so that it can be preserved across a reboot. This uses a simple bit-encoding, where each field has a 'bit position' and a 'bit length' in the schema. Signed-off-by: Simon Glass --- doc/develop/expo.rst | 13 +++++++++++++ doc/usage/cmd/cedit.rst | 22 ++++++++++++++++++++++ 2 files changed, 35 insertions(+) (limited to 'doc') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index fde91494799..61b6855c72f 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -317,6 +317,18 @@ id Specifies the ID of the object. This is used when referring to the object. +Where CMOS RAM is used for reading and writing settings, the following +additional properties are required: + +start-bit + Specifies the first bit in the CMOS RAM to use for this setting. For a RAM + with 0x100 bytes, there are 0x800 bit locations. For example, register 0x80 + holds bits 0x400 to 0x407. + +bit-length + Specifies the number of CMOS RAM bits to use for this setting. The bits + extend from `start-bit` to `start-bit + bit-length - 1`. Note that the bits + must be contiguous. Menu nodes have the following additional properties: @@ -474,6 +486,7 @@ Some ideas for future work: - Support curses for proper serial-terminal menus - Add support for large menus which need to scroll - Add support for reading and writing configuration settings with cedit +- Update expo.py tool to check for overlapping names and CMOS locations .. Simon Glass .. 7-Oct-22 diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 1f92b7306a7..3d6f26e631d 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -14,6 +14,7 @@ Synopis cedit read_fdt cedit write_env [-v] cedit read_env [-v] + cedit write_cmos [-v] [dev] Description ----------- @@ -76,6 +77,18 @@ ID and its text string are written, similar to: The `-v` flag enables verbose mode, where each variable is printed before it is set. +cedit write_cmos +~~~~~~~~~~~~~~~~ + +Writes the settings to locations in the CMOS RAM. The locations used are +specified by the schema. See `expo_format_`. + +The `-v` flag enables verbose mode, which shows which CMOS locations were +updated. + +Normally the first RTC device is used to hold the data. You can specify a +different device by name using the `dev` parameter. + Example ------- @@ -117,3 +130,12 @@ This shows settings being stored in the environment:: => cedit read_env -v c.cpu-speed=7 c.power-loss=12 + +This shows writing to CMOS RAM. Notice that the bytes at 80 and 84 change:: + + => rtc read 80 8 + 00000080: 00 00 00 00 00 2f 2a 08 ...../*. + => cedit write_cmos + Write 2 bytes from offset 80 to 84 + => rtc read 80 8 + 00000080: 01 00 00 00 08 2f 2a 08 ...../*. -- cgit v1.2.3 From cfc402db3954d7c852c322b232ad6d8842af6bf1 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:38 -0600 Subject: expo: cedit: Support reading settings from CMOS RAM Add a command to read edit settings from CMOS RAM, using the cedit definition to indicate which registers and bits are used. Signed-off-by: Simon Glass --- doc/usage/cmd/cedit.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst index 3d6f26e631d..f415b48699e 100644 --- a/doc/usage/cmd/cedit.rst +++ b/doc/usage/cmd/cedit.rst @@ -135,7 +135,14 @@ This shows writing to CMOS RAM. Notice that the bytes at 80 and 84 change:: => rtc read 80 8 00000080: 00 00 00 00 00 2f 2a 08 ...../*. - => cedit write_cmos + => cedit write_cmos -v Write 2 bytes from offset 80 to 84 => rtc read 80 8 00000080: 01 00 00 00 08 2f 2a 08 ...../*. + => cedit read_cmos -v + Read 2 bytes from offset 80 to 84 + +Here is an example with the device specified:: + + => cedit write_cmos rtc@43 + => -- cgit v1.2.3 From 84b08afcbb8f8b4402b940d87bf5822984eedb3d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 14 Aug 2023 16:40:39 -0600 Subject: expo: doc: Update documentation for persistent settings Add mention of persistent settings in the documentation. Signed-off-by: Simon Glass --- doc/develop/cedit.rst | 15 +++++++++++++++ doc/develop/expo.rst | 1 - 2 files changed, 15 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/develop/cedit.rst b/doc/develop/cedit.rst index 8f0a554ae91..63dff9d3f14 100644 --- a/doc/develop/cedit.rst +++ b/doc/develop/cedit.rst @@ -152,3 +152,18 @@ Themes The configuration editor uses simple expo themes. The theme is read from `/bootstd/cedit-theme` in the devicetree. + + +Reading and writing settings +---------------------------- + +Cedit provides several options for persistent settings: + +- Writing an FDT file to a filesystem +- Writing to U-Boot's environment variables, which are then typically stored in + a persistent manner +- Writing to CMOS RAM registers (common on x86 machines) + +For now, reading and writing settings is not automatic. See the +:doc:`../usage/cmd/cedit` for how to do this on the command line or in a +script. diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 61b6855c72f..f13761995d3 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -485,7 +485,6 @@ Some ideas for future work: - Support unicode - Support curses for proper serial-terminal menus - Add support for large menus which need to scroll -- Add support for reading and writing configuration settings with cedit - Update expo.py tool to check for overlapping names and CMOS locations .. Simon Glass -- cgit v1.2.3 From 831405f41de122c2a3a0908f07c632c87266709a Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 24 Aug 2023 13:55:43 -0600 Subject: bootstd: Support bootmeths which can scan any partition Some bootmeths support scanning a partition without a filesystem on it. Add a flag to support this. This will allow the ChromiumOS bootmeth to find kernel partition, which are stored in a special format, without a filesystem. Signed-off-by: Simon Glass --- doc/develop/bootstd.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst index ec313653578..c01e0971dc8 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd.rst @@ -677,11 +677,12 @@ Assuming the bootmeth is happy, or at least indicates that it is willing to try partition. If that works it tries to detect a file system. If that works then it calls the bootmeth device once more, this time to read the bootflow. -Note: At present a filesystem is needed for the bootmeth to be called on block -devices, simply because we don't have any examples where this is not the case. -This feature can be added as needed. Note that sandbox is a special case, since -in that case the host filesystem can be accessed even though the block device -is NULL. +Note: Normally a filesystem is needed for the bootmeth to be called on block +devices, but bootmeths which don't need that can set the BOOTMETHF_ANY_PART +flag to indicate that they can scan any partition. An example is the ChromiumOS +bootmeth which can store a kernel in a raw partition. Note also that sandbox is +a special case, since in that case the host filesystem can be accessed even +though the block device is NULL. If we take the example of the `bootmeth_extlinux` driver, this call ends up at `extlinux_read_bootflow()`. It has the filesystem ready, so tries various -- cgit v1.2.3 From 3107f78485893895ef1b690a7275c45de629062a Mon Sep 17 00:00:00 2001 From: Sughosh Ganu Date: Tue, 22 Aug 2023 23:10:01 +0530 Subject: doc: Add documentation to highlight capsule generation related updates The EFI capsules can now be generated as part of U-Boot build, through binman. Highlight these changes in the documentation. Signed-off-by: Sughosh Ganu Acked-by: Heinrich Schuchardt --- doc/develop/uefi/uefi.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'doc') diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index a7a41f2facf..f27cabbcce8 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -318,6 +318,9 @@ Run the following command --guid \ +Capsule with firmware version +***************************** + The UEFI specification does not define the firmware versioning mechanism. EDK II reference implementation inserts the FMP Payload Header right before the payload. It coutains the fw_version and lowest supported version, @@ -345,6 +348,43 @@ add --fw-version option in mkeficapsule tool. If the --fw-version option is not set, FMP Payload Header is not inserted and fw_version is set as 0. +Capsule Generation through binman +********************************* + +Support has also been added to generate capsules during U-Boot build +through binman. This requires the platform's DTB to be populated with +the capsule entry nodes for binman. The capsules then can be generated +by specifying the capsule parameters as properties in the capsule +entry node. + +Check the test/py/tests/test_efi_capsule/capsule_gen_binman.dts file +as reference for how a typical binman node for capsule generation +looks like. For generating capsules as part of the platform's build, a +capsule node would then have to be included into the platform's +devicetree. + +A typical binman node for generating a capsule would look like:: + + capsule { + filename = "u-boot.capsule"; + efi-capsule { + image-index = <0x1>; + image-guid = "09d7cf52-0720-4710-91d1-08469b7fe9c8"; + + u-boot { + }; + }; + }; + +In the above example, a capsule file named u-boot.capsule will be +generated with u-boot.bin as it's input payload. The capsule +generation parameters like image-index and image-guid are being +specified as properties. Similarly, other properties like the private +and public key certificate can be specified for generating signed +capsules. Refer :ref:`etype_efi_capsule` for documentation about the +efi-capsule binman entry type, which describes all the properties that +can be specified. + Performing the update ********************* -- cgit v1.2.3 From 1df1d566d21f52703511e55fadd72993a137a464 Mon Sep 17 00:00:00 2001 From: Sughosh Ganu Date: Tue, 22 Aug 2023 23:10:08 +0530 Subject: doc: capsule: Document the new mechanism to embed ESL file into dtb Update the document to specify how the EFI Signature List(ESL) file can be embedded into the platform's dtb as part of the U-Boot build. Signed-off-by: Sughosh Ganu Reviewed-by: Ilias Apalodimas --- doc/develop/uefi/uefi.rst | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) (limited to 'doc') diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index f27cabbcce8..68f9b332d15 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -562,20 +562,11 @@ and used by the steps highlighted below. ... } -You can do step-4 manually with - -.. code-block:: console - - $ dtc -@ -I dts -O dtb -o signature.dtbo signature.dts - $ fdtoverlay -i orig.dtb -o new.dtb -v signature.dtbo - -where signature.dts looks like:: - - &{/} { - signature { - capsule-key = /incbin/("CRT.esl"); - }; - }; +You can perform step-4 through the Kconfig symbol +CONFIG_EFI_CAPSULE_ESL_FILE. This symbol points to the esl file +generated in step-2. Once the symbol has been populated with the path +to the esl file, it will automatically get embedded into the +platform's dtb as part of U-Boot build. Anti-rollback Protection ************************ -- cgit v1.2.3 From 12be60daab224f2cbcb7c6584ab87f0f7caba83c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 21 Aug 2023 21:16:58 -0600 Subject: event: Update documentation for simple spy Now that we have two types of spy, mention this in the documentation. Put the simple spy first, since it seems to be the common case. Signed-off-by: Simon Glass --- doc/develop/event.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/develop/event.rst b/doc/develop/event.rst index cb09e9c85a9..d5043ec4f4c 100644 --- a/doc/develop/event.rst +++ b/doc/develop/event.rst @@ -21,16 +21,31 @@ Declaring a spy To declare a spy, use something like this:: - static int snow_setup_cpus(void *ctx, struct event *event) + static int snow_check_temperature(void) { /* do something */ return 0; } - EVENT_SPY(EVT_DM_POST_INIT_F, snow_setup_cpus); + EVENT_SPY_SIMPLE(EVT_DM_POST_INIT_F, snow_check_temperature); This function is called when EVT_DM_POST_INIT_F is emitted, i.e. after the driver model is initialized (in U-Boot proper before and after relocation). +If you need access to the event data, use `EVENT_SPY_FULL`, like this:: + + static int snow_setup_cpus(void *ctx, struct event *event) + { + /* do something that uses event->data*/ + return 0; + } + EVENT_SPY_FULL(EVT_DM_POST_INIT_F, snow_setup_cpus); + +Note that the context is always NULL for a static spy. See below for information +about how to use a dynamic spy. + +The return value is handled by the event emitter. If non-zero, then the error +is returned to the function which emitted the event, i.e. the one that called +`event_notify()`. Debugging --------- @@ -80,6 +95,10 @@ to be notified when a particular device is probed or removed. This can be handled by enabling `CONFIG_EVENT_DYNAMIC`. It is then possible to call `event_register()` to register a new handler for a particular event. +If some context is need for the spy, you can pass a pointer to +`event_register()` to provide that. Note that the context is only passed to +a spy registered with `EVENT_SPY_FULL`. + Dynamic event handlers are called after all the static event spy handlers have been processed. Of course, since dynamic event handlers are created at runtime it is not possible to use the `event_dump.py` to see them. -- cgit v1.2.3 From 4aacfffda10c9786b7997183037cf32def5c39c3 Mon Sep 17 00:00:00 2001 From: Nishanth Menon Date: Tue, 22 Aug 2023 11:40:58 -0500 Subject: doc: board: ti: am64x: provide image alt text Provide alternative text for image. Fixes: 4bf49bade124 ("doc: board: ti: am64: Add boot flow diagram") Reported-by: Heinrich Schuchardt Signed-off-by: Nishanth Menon Reviewed-by: Heinrich Schuchardt --- doc/board/ti/am64x_evm.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc') diff --git a/doc/board/ti/am64x_evm.rst b/doc/board/ti/am64x_evm.rst index 8d3795eb326..01e536dac9d 100644 --- a/doc/board/ti/am64x_evm.rst +++ b/doc/board/ti/am64x_evm.rst @@ -36,6 +36,7 @@ Boot Flow: Below is the pictorial representation of boot flow: .. image:: img/boot_diagram_am64.svg + :alt: Boot flow diagram - Here TIFS acts as master and provides all the critical services. R5/A53 requests TIFS to get these services done as shown in the above diagram. @@ -131,10 +132,12 @@ Image formats: - tiboot3.bin .. image:: img/multi_cert_tiboot3.bin.svg + :alt: tiboot3.bin image format - tispl.bin .. image:: img/nodm_tispl.bin.svg + :alt: tispl.bin image format Switch Setting for Boot Mode ---------------------------- -- cgit v1.2.3 From edd8149cc686f749c51fafcfbb7802da73b42aea Mon Sep 17 00:00:00 2001 From: Nishanth Menon Date: Tue, 22 Aug 2023 11:41:03 -0500 Subject: doc: board: ti: am64x: Fix build step numbering Fix up build step numbering. Fixes: 4bf49bade124 ("doc: board: ti: am64: Add boot flow diagram") Signed-off-by: Nishanth Menon Reviewed-by: Heinrich Schuchardt --- doc/board/ti/am64x_evm.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/board/ti/am64x_evm.rst b/doc/board/ti/am64x_evm.rst index 01e536dac9d..db27461cb14 100644 --- a/doc/board/ti/am64x_evm.rst +++ b/doc/board/ti/am64x_evm.rst @@ -93,13 +93,13 @@ Set the variables corresponding to this platform: 3. U-Boot: -* 4.1 R5: +* 3.1 R5: .. include:: k3.rst :start-after: .. k3_rst_include_start_build_steps_spl_r5 :end-before: .. k3_rst_include_end_build_steps_spl_r5 -* 4.2 A53: +* 3.2 A53: .. include:: k3.rst :start-after: .. k3_rst_include_start_build_steps_uboot -- cgit v1.2.3 From e57f6390e7932d8e26da47fe0d567b1e62d934ea Mon Sep 17 00:00:00 2001 From: Nishanth Menon Date: Fri, 25 Aug 2023 13:03:05 -0500 Subject: doc: board: ti: Add BeaglePlay documentation Add base documentation for BeaglePlay Reviewed-by: Mattijs Korpershoek Tested-by: Mattijs Korpershoek Signed-off-by: Nishanth Menon --- doc/board/ti/am62x_beagleplay.rst | 322 ++++++++++++++++ doc/board/ti/img/beagleplay_emmc.svg | 697 +++++++++++++++++++++++++++++++++++ doc/board/ti/k3.rst | 1 + 3 files changed, 1020 insertions(+) create mode 100644 doc/board/ti/am62x_beagleplay.rst create mode 100644 doc/board/ti/img/beagleplay_emmc.svg (limited to 'doc') diff --git a/doc/board/ti/am62x_beagleplay.rst b/doc/board/ti/am62x_beagleplay.rst new file mode 100644 index 00000000000..39913b29ab2 --- /dev/null +++ b/doc/board/ti/am62x_beagleplay.rst @@ -0,0 +1,322 @@ +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause +.. sectionauthor:: Nishanth Menon + +AM62x Beagleboard.org Beagleplay +================================ + +Introduction: +------------- + +BeagleBoard.org BeaglePlay is an easy to use, affordable open source +hardware single board computer based on the Texas Instruments AM625 +SoC that allows you to create connected devices that work even at long +distances using IEEE 802.15.4g LR-WPAN and IEEE 802.3cg 10Base-T1L. +Expansion is provided over open standards based mikroBUS, Grove and +QWIIC headers among other interfaces. + +Further information can be found at: + +* Product Page: https://beagleplay.org/ +* Hardware documentation: https://git.beagleboard.org/beagleplay/beagleplay + +Boot Flow: +---------- +Below is the pictorial representation of boot flow: + +.. image:: img/boot_diagram_k3_current.svg + :alt: Boot flow diagram + +- On this platform, 'TI Foundational Security' (TIFS) functions as the + security enclave master while 'Device Manager' (DM), also known as the + 'TISCI server' in "TI terminology", offers all the essential services. + The A53 or M4F (Aux core) sends requests to TIFS/DM to accomplish these + services, as illustrated in the diagram above. + +Sources: +-------- +.. include:: k3.rst + :start-after: .. k3_rst_include_start_boot_sources + :end-before: .. k3_rst_include_end_boot_sources + +Build procedure: +---------------- +0. Setup the environment variables: + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_common_env_vars_desc + :end-before: .. k3_rst_include_end_common_env_vars_desc + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_board_env_vars_desc + :end-before: .. k3_rst_include_end_board_env_vars_desc + +Set the variables corresponding to this platform: + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_common_env_vars_defn + :end-before: .. k3_rst_include_end_common_env_vars_defn +.. code-block:: bash + + $ export UBOOT_CFG_CORTEXR="am62x_evm_r5_defconfig beagleplay_r5.config" + $ export UBOOT_CFG_CORTEXA="am62x_evm_a53_defconfig beagleplay_a53.config" + $ export TFA_BOARD=lite + $ # we dont use any extra TFA parameters + $ unset TFA_EXTRA_ARGS + $ export OPTEE_PLATFORM=k3-am62x + $ export OPTEE_EXTRA_ARGS="CFG_WITH_SOFTWARE_PRNG=y" + +.. include:: am62x_sk.rst + :start-after: .. am62x_evm_rst_include_start_build_steps + :end-before: .. am62x_evm_rst_include_end_build_steps + +Target Images +-------------- +Copy the below images to an SD card and boot: + +* tiboot3-am62x-gp-evm.bin from R5 build as tiboot3.bin +* tispl.bin_unsigned from Cortex-A build as tispl.bin +* u-boot.img_unsigned from Cortex-A build as u-boot.img + +Image formats +------------- + +- tiboot3.bin + +.. image:: img/multi_cert_tiboot3.bin.svg + :alt: tiboot3.bin image format + +- tispl.bin + +.. image:: img/dm_tispl.bin.svg + :alt: tispl.bin image format + +Additional hardware for U-Boot development +------------------------------------------ + +* Serial Console is critical for U-Boot development on BeaglePlay. See + `BeaglePlay serial console documentation + `_. +* uSD is preferred option over eMMC, and a SD/MMC reader will be needed. +* (optionally) JTAG is useful when working with very early stages of boot. + +Default storage options +----------------------- + +There are multiple storage media options on BeaglePlay, but primarily: + +* Onboard eMMC (default) - reliable, fast and meant for deployment use. +* SD/MMC card interface (hold 'USR' switch and power on) - Entirely + depends on the SD card quality. + +Flash to uSD card or how to deal with "bricked" Board +-------------------------------------------------------- + +When deploying or working on Linux, it's common to use the onboard +eMMC. However, avoiding the eMMC and using the uSD card is safer when +working with U-Boot. + +If you choose to hand format your own bootable uSD card, be +aware that it can be difficult. The following information +may be helpful, but remember that it is only sometimes +reliable, and partition options can cause issues. These +can potentially help: + +* https://git.ti.com/cgit/arago-project/tisdk-setup-scripts/tree/create-sdcard.sh +* https://elinux.org/Beagleboard:Expanding_File_System_Partition_On_A_microSD + +The simplest option is to start with a standard distribution +image like those in `BeagleBoard.org Distros Page +`_ and download a disk image for +BeaglePlay. Pick a 16GB+ uSD card to be on the safer side. + +With an SD/MMC Card reader and `Balena Etcher +`_, having a functional setup in minutes is +a trivial matter, and it works on almost all Host Operating Systems. +Yes Windows users, Windows Subsystem for Linux(WSL) based development +with U-Boot and update uSD card is practical. + +Updating U-Boot is a matter of copying the tiboot3.bin, tispl.bin and +u-boot.img to the "BOOT" partition of the uSD card. Remember to sync +and unmount (or Eject - depending on the Operating System) the uSD +card prior to physically removing from SD card reader. + +Also see following section on switch setting used for booting using +uSD card. + +.. note:: + Great news! If the board has not been damaged physically, there's no + need to worry about it being "bricked" on this platform. You only have + to flash an uSD card, plug it in, and reinstall the image on eMMC. This + means that even if you make a mistake, you can quickly fix it and rest + easy. + + If you are frequently working with uSD cards, you might find the + following useful: + + * `USB-SD-Mux `_ + * `SD-Wire `_ + +Flash to eMMC +------------- + +The eMMC layout selected is user-friendly for developers. The +boot hardware partition of the eMMC only contains the fixed-size +tiboot3.bin image. This is because the contents of the boot partitions +need to run from the SoC's internal SRAM, which remains a fixed size +constant. The other components of the boot sequence, such as tispl.bin +and u-boot.img, are located in the /BOOT partition in the User Defined +Area (UDA) hardware partition of the eMMC. These components can vary +significantly in size. The choice of keeping tiboot3.bin in boot0 or +boot1 partition depends on A/B update requirements. + +.. image:: img/beagleplay_emmc.svg + :alt: eMMC partitions and boot file organization for BeaglePlay + +The following are the steps from Linux shell to program eMMC: + +.. code-block:: bash + + # # Enable Boot0 boot + # mmc bootpart enable 1 2 /dev/mmcblk0 + # mmc bootbus set single_backward x1 x8 /dev/mmcblk0 + # mmc hwreset enable /dev/mmcblk0 + + # # Clear eMMC boot0 + # echo '0' >> /sys/class/block/mmcblk0boot0/force_ro + # dd if=/dev/zero of=/dev/mmcblk0boot0 count=32 bs=128k + # # Write tiboot3.bin + # dd if=tiboot3.bin of=/dev/mmcblk0boot0 bs=128k + + # # Copy the rest of the boot binaries + # mount /dev/mmcblk0p1 /boot/firmware + # cp tispl.bin /boot/firmware + # cp u-boot.img /boot/firmware + # sync + +.. warning :: + + U-Boot is configured to prioritize booting from an SD card if it + detects a valid boot partition and boot files on it, even if the + system initially booted from eMMC. The boot order is set as follows: + + * SD/MMC + * eMMC + * USB + * PXE + +LED patterns during boot +------------------------ + +.. list-table:: USR LED status indication + :widths: 16 16 + :header-rows: 1 + + * - USR LEDs (012345) + - Indicates + + * - 00000 + - Boot failure or R5 image not started up + + * - 11111 + - A53 SPL/U-boot has started up + + * - 10101 + - OS boot process has been initiated + + * - 01010 + - OS boot process failed and drops to U-Boot shell + +.. note :: + + In the table above, 0 indicates LED switched off and 1 indicates LED + switched ON. + +.. warning :: + + If the "red" power LED is not glowing, the system power supply is not + functional. Please refer to `BeaglePlay documentation + `_ for further information. + +A53 SPL DDR Memory Layout +------------------------- + +.. include:: am62x_sk.rst + :start-after: .. am62x_evm_rst_include_start_ddr_mem_layout + :end-before: .. am62x_evm_rst_include_end_ddr_mem_layout + +Switch Setting for Boot Mode +---------------------------- + +The boot time option is configured via "USR" button on the board. +See `Beagleplay Schematics `_ +for details. + +.. list-table:: Boot Modes + :widths: 16 16 16 + :header-rows: 1 + + * - USR Switch Position + - Primary Boot + - Secondary Boot + + * - Not Pressed + - eMMC + - UART + + * - Pressed + - SD/MMC File System (FS) mode + - USB Device Firmware Upgrade (DFU) mode + +To switch to SD card boot mode, hold the USR button while powering on +with Type-C power supply, then release when power LED lights up. + +Debugging U-Boot +---------------- + +See :ref:`Common Debugging environment - OpenOCD`: for +detailed setup and debugging information. + +.. warning:: + + **OpenOCD support since**: v0.12.0 + + If the default package version of OpenOCD in your development + environment's distribution needs to be updated, it might be necessary to + build OpenOCD from the source. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_tag_connect + :end-before: .. k3_rst_include_end_openocd_connect_tag_connect + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_cfg_external_intro + :end-before: .. k3_rst_include_end_openocd_cfg_external_intro + +For example, with BeaglePlay (AM62X platform), the openocd_connect.cfg: + +.. code-block:: tcl + + # TUMPA example: + # http://www.tiaowiki.com/w/TIAO_USB_Multi_Protocol_Adapter_User's_Manual + source [find interface/ftdi/tumpa.cfg] + + transport select jtag + + # default JTAG configuration has only SRST and no TRST + reset_config srst_only srst_push_pull + + # delay after SRST goes inactive + adapter srst delay 20 + + if { ![info exists SOC] } { + # Set the SoC of interest + set SOC am625 + } + + source [find target/ti_k3.cfg] + + ftdi tdo_sample_edge falling + + # Speeds for FT2232H are in multiples of 2, and 32MHz is tops + # max speed we seem to achieve is ~20MHz.. so we pick 16MHz + adapter speed 16000 diff --git a/doc/board/ti/img/beagleplay_emmc.svg b/doc/board/ti/img/beagleplay_emmc.svg new file mode 100644 index 00000000000..c6ff19b7738 --- /dev/null +++ b/doc/board/ti/img/beagleplay_emmc.svg @@ -0,0 +1,697 @@ + + + + + + + + + + + + + + + + + + + + Boot0 + + + + Boot0 + + + + + + + + + Boot1 + + + + Boot1 + + + + + + + + + RPMB + + + + RPMB + + + + + + + + + User Defined Area (UDA) + + + + User Defined Area (UDA) + + + + + + + + + BOOT + + + + BOOT + + + + + + + + + rootfs + + + + rootfs + + + + + + + + + swap + + + + swap + + + + + + + + + ... + + + + ... + + + + + + + + + tiboot3.bin + + + + tiboot3.bin + + + + + + + + + tispl.bin + + + + tispl.bin + + + + + + + + + u-boot.img + + + + u-boot.img + + + + + + + + + extlinux/extlinux.conf + + + + extlinux/extlinux.conf + + + + + + + + + uEnv.txt / boot.scr +(optional) + + + + uEnv.txt / boot.scr... + + + + + + + + + eMMC +hardware partitions + + + + eMMC... + + + + + + + + + UDA partitions + + + + UDA partit... + + + + + + + Text is not SVG - cannot display + + + diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index 95cdb366252..8b5c1a88ed0 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -30,6 +30,7 @@ K3 Based SoCs .. toctree:: :maxdepth: 1 + am62x_beagleplay am62x_sk ../toradex/verdin-am62 am64x_evm -- cgit v1.2.3 From b1433affd9a9de10150c31929564f68ca338911a Mon Sep 17 00:00:00 2001 From: Joshua Watt Date: Thu, 31 Aug 2023 10:51:37 -0600 Subject: cmd: gpt: Add gpt_partition_bootable variable Adds an additional variable called gpt_partition_bootable that indicates if the given partition is bootable or not. Signed-off-by: Joshua Watt --- doc/usage/cmd/gpt.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc') diff --git a/doc/usage/cmd/gpt.rst b/doc/usage/cmd/gpt.rst index 6387c8116fe..b505b159d0a 100644 --- a/doc/usage/cmd/gpt.rst +++ b/doc/usage/cmd/gpt.rst @@ -108,6 +108,9 @@ gpt_partition_name gpt_partition_entry the partition number in the table, e.g. 1, 2, 3, etc. +gpt_partition_bootable + 1 if the partition is marked as bootable, 0 if not + gpt swap ~~~~~~~~ @@ -167,6 +170,8 @@ Get the information about the partition named 'rootfs':: rootfs => echo ${gpt_partition_entry} 2 + => echo ${gpt_partition_bootable} + 0 Get the list of partition names on the disk:: -- cgit v1.2.3 From a1e793add5dd21c2a1b08bc57ac99e43183913b6 Mon Sep 17 00:00:00 2001 From: Joshua Watt Date: Thu, 31 Aug 2023 10:51:38 -0600 Subject: cmd: gpt: Add command to set bootable flags Adds a command that can be used to modify the GPT partition table to indicate which partitions should have the bootable flag set Signed-off-by: Joshua Watt --- doc/usage/cmd/gpt.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc') diff --git a/doc/usage/cmd/gpt.rst b/doc/usage/cmd/gpt.rst index b505b159d0a..288dd365c00 100644 --- a/doc/usage/cmd/gpt.rst +++ b/doc/usage/cmd/gpt.rst @@ -13,6 +13,7 @@ Synopsis gpt read [] gpt rename gpt repair + gpt set-bootable gpt setenv gpt swap gpt verify [] @@ -90,6 +91,13 @@ gpt repair Repairs the GPT partition tables if it they become corrupted. +gpt set-bootable +~~~~~~~~~~~~~~~~ + +Sets the bootable flag for all partitions in the table. If the partition name +is in 'partition list' (separated by ','), the bootable flag is set, otherwise +it is cleared. CONFIG_CMD_GPT_RENAME=y is required. + gpt setenv ~~~~~~~~~~ @@ -187,3 +195,7 @@ Get the GUID for a disk:: => gpt guid mmc gpt_disk_uuid => echo ${gpt_disk_uuid} bec9fc2a-86c1-483d-8a0e-0109732277d7 + +Set the bootable flag for the 'boot' partition and clear it for all others:: + + => gpt set-bootable mmc 0 boot -- cgit v1.2.3 From 7cc1d87d7e1e64d7bb280ead94c55a51c4f3ee63 Mon Sep 17 00:00:00 2001 From: Joshua Watt Date: Thu, 31 Aug 2023 10:51:41 -0600 Subject: cmd: gpt: Add command to swap partition order Adds a command called "gpt transpose" which will swap the order two partition table entries in the GPT partition table (but leaves them pointing to the same locations on disk). This can be useful for swapping bootloaders in systems that use an A/B partitioning scheme where the bootrom is hard coded to look for the bootloader in a specific index in the GPT partition table. Signed-off-by: Joshua Watt --- doc/usage/cmd/gpt.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'doc') diff --git a/doc/usage/cmd/gpt.rst b/doc/usage/cmd/gpt.rst index 288dd365c00..f6115ecb0ee 100644 --- a/doc/usage/cmd/gpt.rst +++ b/doc/usage/cmd/gpt.rst @@ -16,6 +16,7 @@ Synopsis gpt set-bootable gpt setenv gpt swap + gpt transpose gpt verify [] gpt write @@ -126,6 +127,13 @@ Changes the names of all partitions that are named 'name1' to be 'name2', and all partitions named 'name2' to be 'name1'. CONFIG_CMD_GPT_RENAME=y is required. +gpt transpose +~~~~~~~~~~~~~ + +Swaps the order of two partition table entries with indexes 'part1' and 'part2' +in the partition table, but otherwise leaves the actual partition data +untouched. + gpt verify ~~~~~~~~~~ @@ -199,3 +207,20 @@ Get the GUID for a disk:: Set the bootable flag for the 'boot' partition and clear it for all others:: => gpt set-bootable mmc 0 boot + +Swap the order of the 'boot' and 'rootfs' partition table entries:: + => gpt setenv mmc 0 rootfs + => echo ${gpt_partition_entry} + 2 + => gpt setenv mmc 0 boot + => echo ${gpt_partition_entry} + 1 + + => gpt transpose mmc 0 1 2 + + => gpt setenv mmc 0 rootfs + => echo ${gpt_partition_entry} + 1 + => gpt setenv mmc 0 boot + => echo ${gpt_partition_entry} + 2 -- cgit v1.2.3 From 4babaa0c28becc2b80db13daa6f30d8f4d35e94e Mon Sep 17 00:00:00 2001 From: Marek Vasut Date: Wed, 6 Sep 2023 23:30:15 +0200 Subject: post: Remove unused NEEDS_MANUAL_RELOC code bits The last user of the NEEDS_MANUAL_RELOC has been removed in commit 26af162ac8f8 ("arch: m68k: Implement relocation") Remove now unused NEEDS_MANUAL_RELOC code. Signed-off-by: Marek Vasut --- doc/README.POST | 5 ----- 1 file changed, 5 deletions(-) (limited to 'doc') diff --git a/doc/README.POST b/doc/README.POST index 1366f95c662..c614ea44a28 100644 --- a/doc/README.POST +++ b/doc/README.POST @@ -138,11 +138,6 @@ The POST layer will export the following interface routines: mode the test is executed in (power-on, normal, power-fail, manual). - o) void post_reloc(ulong offset); - - This routine will be called from board_init_r() and will - relocate the POST test table. - o) int post_info(char *name); This routine will print the list of all POST tests that can be -- cgit v1.2.3 From 3b58de4d0b6bde8f8dab0fa0c0dc417e57b6c804 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Sep 2023 10:55:55 -0600 Subject: Mark DISTRO_DEFAULTS as deprecated Standard boot has been in place for a while now. Quite a few problems have been found and fixed. It seems like a good time to mark the script-based approach as deprecated and encourage people to use standard boot. Update the DISTRO_DEFAULTS Kconfig to encourage people to move to standard boot, which is able to boot Linux distributions automatically. Add a short migration guide to make this easier. Signed-off-by: Simon Glass Reviewed-by: Tom Rini --- doc/develop/bootstd.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'doc') diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst index e8b90752f08..6172dc906bd 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd.rst @@ -464,6 +464,28 @@ ready File was loaded and is ready for use. In this state the bootflow is ======= ======================================================================= +Migrating from distro_boot +-------------------------- + +To migrate from distro_boot: + +#. Update your board header files to remove the BOOTENV and BOOT_TARGET_xxx + defines. Standard boot finds available boot devices automatically. + +#. Remove the "boot_targets" variable unless you need it. Standard boot uses a + default order from fastest to slowest, which generally matches the order used + by boards. + +#. Make sure that CONFIG_BOOTSTD_DEFAULTS is enabled by your board, so it can + boot common Linux distributions. + +An example patch is at migrate_patch_. + +If you are using custom boot scripts for your board, consider creating your +own bootmeth to hold the logic. There are various examples at +`boot/bootmeth_...`. + + Theory of operation ------------------- @@ -775,3 +797,4 @@ Other ideas: .. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/ .. _distro_boot: https://github.com/u-boot/u-boot/blob/master/boot/distro.c .. _bootflow_h: https://github.com/u-boot/u-boot/blob/master/include/bootflow.h +.. _migrate_patch: https://patchwork.ozlabs.org/project/uboot/patch/20230727215433.578830-2-sjg@chromium.org/ -- cgit v1.2.3 From 90602e779d3ae3bd02faae0eb40b4fcefec419f7 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sun, 17 Sep 2023 13:47:31 +0200 Subject: riscv: dts: starfive: generate u-boot-spl.bin.normal.out MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The StarFive VisionFive 2 board cannot load spl/u-boot-spl.bin but needs a prefixed header. We have referring to a vendor tool (spl_tool) for this task. 'mkimage -T sfspl' can generate the prefixed file. Use binman to invoke mkimage for the generation of file spl/u-boot-spl.bin.normal.out. Update the documentation. Signed-off-by: Heinrich Schuchardt Tested-by: Milan P. Stanić --- doc/board/starfive/visionfive2.rst | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/board/starfive/visionfive2.rst b/doc/board/starfive/visionfive2.rst index 941899a0a4e..f5575ab68be 100644 --- a/doc/board/starfive/visionfive2.rst +++ b/doc/board/starfive/visionfive2.rst @@ -65,18 +65,8 @@ Now build the U-Boot SPL and U-Boot proper make starfive_visionfive2_defconfig make OPENSBI=$(opensbi_dir)/opensbi/build/platform/generic/firmware/fw_dynamic.bin -This will generate spl/u-boot-spl.bin and FIT image (u-boot.itb) - -u-boot-spl.bin cannot be used directly on StarFive VisionFive2,we need -to convert the u-boot-spl.bin to u-boot-spl.bin.normal.out with -the below command: - - ./spl_tool -c -f $(Uboot_PATH)/spl/u-boot-spl.bin - -More detailed description of spl_tool,please refer spl_tool documenation. -(Note: spl_tool git repo is at https://github.com/starfive-tech/Tools/tree/master/spl_tool) - -This will generate u-boot-spl.bin.normal.out file. +This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well +as the FIT image (u-boot.itb) with OpenSBI and U-Boot. Flashing ~~~~~~~~ -- cgit v1.2.3 From e6ff998cb02aad0326a8280498725a8e7bbbb37b Mon Sep 17 00:00:00 2001 From: Michal Simek Date: Fri, 8 Sep 2023 09:11:31 +0200 Subject: global: Use proper project name U-Boot (next2) Use proper project name in README, rst and comment. Done in connection to commit bb922ca3eb4b ("global: Use proper project name U-Boot (next)"). Reviewed-by: Simon Glass Reviewed-by: Alexander Graf (ppce500) Signed-off-by: Michal Simek Link: https://lore.kernel.org/r/536af05e7061982f15b668e87f941cdabfa25392.1694157084.git.michal.simek@amd.com --- doc/board/xilinx/zynq.rst | 2 +- doc/board/xilinx/zynqmp-r5.rst | 4 ++-- doc/imx/mkimage/imximage.txt | 2 +- doc/usage/environment.rst | 2 +- doc/usage/semihosting.rst | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/board/xilinx/zynq.rst b/doc/board/xilinx/zynq.rst index 438912fe42c..76d67bd62ee 100644 --- a/doc/board/xilinx/zynq.rst +++ b/doc/board/xilinx/zynq.rst @@ -83,7 +83,7 @@ Mainline status --------------- - Added basic board configurations support. -- Added zynq u-boot bsp code - arch/arm/mach-zynq +- Added zynq U-Boot bsp code - arch/arm/mach-zynq - Added zynq boards named - zc70x, zed, microzed, zc770_xm010/xm011/xm012/xm013 - Added zynq drivers: diff --git a/doc/board/xilinx/zynqmp-r5.rst b/doc/board/xilinx/zynqmp-r5.rst index 2cd368b0308..266d07d1193 100644 --- a/doc/board/xilinx/zynqmp-r5.rst +++ b/doc/board/xilinx/zynqmp-r5.rst @@ -26,7 +26,7 @@ configure and build armv7 toolchain:: Notes ^^^^^ -Output fragment is u-boot. +Output fragment is U-Boot. Loading ------- @@ -38,7 +38,7 @@ Bootgen ^^^^^^^ The first way is to use Xilinx FSBL (First stage -bootloader) to load u-boot and start it. The following bif can be used for boot +bootloader) to load U-Boot and start it. The following bif can be used for boot image generation via Xilinx bootgen utility:: diff --git a/doc/imx/mkimage/imximage.txt b/doc/imx/mkimage/imximage.txt index f2cf23c5dab..fa4e486661c 100644 --- a/doc/imx/mkimage/imximage.txt +++ b/doc/imx/mkimage/imximage.txt @@ -213,7 +213,7 @@ Disk identifier: 0xb712a870 Device Boot Start End Blocks Id System /dev/mmcblk0p1 3 16 112455 83 Linux -I have set 100MB, leaving the first 2 sectors free. I will copy u-boot +I have set 100MB, leaving the first 2 sectors free. I will copy U-Boot there. 8. Write the partition table and exit. diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index c6439dde668..c57b717caaf 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -216,7 +216,7 @@ fdt_high 0xffffffffffffffff (64-bit machines) then the fdt will not be copied at all on boot. For this to work it must reside in writable memory, have - sufficient padding on the end of it for u-boot to + sufficient padding on the end of it for U-Boot to add the information it needs into it, and the memory must be accessible by the kernel. This usage is strongly discouraged however as it also stops U-Boot from ensuring the device tree starting diff --git a/doc/usage/semihosting.rst b/doc/usage/semihosting.rst index 6a280b455e0..9303a6364d5 100644 --- a/doc/usage/semihosting.rst +++ b/doc/usage/semihosting.rst @@ -23,7 +23,7 @@ eMMC or other NV media are available. There are two main ARM virtual Fixed Virtual Platform (FVP) models, `Versatile Express (VE) FVP and BASE FVP `_. -The initial vexpress64 u-boot board created here runs on the VE virtual +The initial vexpress64 U-Boot board created here runs on the VE virtual platform using the license-free Foundation_v8 simulator. Fortunately, the Foundation_v8 simulator also supports the BASE_FVP model which companies can purchase licenses for and contain much more functionality. -- cgit v1.2.3 From 48bf738e3622a94b96a57055ff0f6466f5830bd4 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 31 Aug 2023 11:20:52 -0600 Subject: Allow Python packages to be dropped When building in a portage chroot, we do not have the environment needed to build pylibfdt. It is instead build as a separate package. Provide a build option to tell U-Boot to skip this part of the build. We still need it to use binman, etc. but don't need it to build its dependencies. Signed-off-by: Simon Glass Reviewed-by: Mike Frysinger [s/build bytes/builds bytes in tools.rst] Signed-off-by: Bin Meng --- doc/build/tools.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'doc') diff --git a/doc/build/tools.rst b/doc/build/tools.rst index ec017229258..5bfa05b2325 100644 --- a/doc/build/tools.rst +++ b/doc/build/tools.rst @@ -45,3 +45,12 @@ Launch the MSYS2 shell of the MSYS2 environment, and do the following:: $ make tools-only_defconfig $ make tools-only + + +Building without Python +----------------------- + +The tools-only builds bytes pylibfdt by default. To disable this, use the +NO_PYTHON variable:: + + NO_PYTHON=1 make tools-only_defconfig tools-only -- cgit v1.2.3 From 9804e572cf1ade7a0aae000740e6159a1e5394fd Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Fri, 1 Sep 2023 12:08:23 -0600 Subject: x86: doc: Document the -cdrom issues I ran into Add a note about using -cdrom with QEMU. Suggested-by: Bin Meng Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/board/emulation/qemu-x86.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc') diff --git a/doc/board/emulation/qemu-x86.rst b/doc/board/emulation/qemu-x86.rst index 15f56b6bc70..c604e42990e 100644 --- a/doc/board/emulation/qemu-x86.rst +++ b/doc/board/emulation/qemu-x86.rst @@ -193,6 +193,9 @@ Linux is selected from grub, e.g. with `debian-12.1.0-i386-netinst.iso`:: The bochs video driver also seems to cause problems before the OS is able to show a display. +The QEMU `-cdrom` option is intended to work with the original ISO-format +images, not the recently invented ISOHybrid image. + Finally, the use of `-M accel=kvm` is intended to use the native CPU's virtual-machine features to accelerate operation, but this causes U-Boot to hang when jumping 64-bit mode, at least on AMD machines. This may be a bug in U-Boot -- cgit v1.2.3 From 35307ba776754aba8fc34b9d17928850c69d4114 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 7 Sep 2023 09:58:21 -0600 Subject: x86: doc: Update the list of supported Chromebooks One is missing, so add it. Also mention the SoC used in each. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/arch/x86.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/arch/x86.rst b/doc/arch/x86.rst index 725a1ae5863..89d3e7ba0e4 100644 --- a/doc/arch/x86.rst +++ b/doc/arch/x86.rst @@ -25,12 +25,13 @@ are supported: - Bayley Bay CRB - Cherry Hill CRB - Congatec QEVAL 2.0 & conga-QA3/E3845 + - Coral (Apollo Lake - Chromebook 2017) - Cougar Canyon 2 CRB - Crown Bay CRB - Galileo - - Link (Chromebook Pixel) + - Link (Ivy Bridge - Chromebook Pixel) - Minnowboard MAX - - Samus (Chromebook Pixel 2015) + - Samus (Broadwell - Chromebook Pixel 2015) - QEMU x86 (32-bit & 64-bit) As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit -- cgit v1.2.3 From 350c0df30da140754766e62c55e9c059e14755bf Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 19 Sep 2023 21:00:02 -0600 Subject: x86: coreboot: Add IDE and SATA Add these options to permit access to more disk types. Add some documentation as well. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/board/coreboot/coreboot.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'doc') diff --git a/doc/board/coreboot/coreboot.rst b/doc/board/coreboot/coreboot.rst index d660a223d9c..be5b0de5495 100644 --- a/doc/board/coreboot/coreboot.rst +++ b/doc/board/coreboot/coreboot.rst @@ -41,6 +41,26 @@ At present it seems that for Minnowboard Max, coreboot does not pass through the video information correctly (it always says the resolution is 0x0). This works correctly for link though. +You can run via QEMU using:: + + qemu-system-x86_64 -bios build/coreboot.rom -serial mon:stdio + +The `-serial mon:stdio` part shows both output in the display and on the +console. It is optional. You can add `nographic` as well to *only* get console +output. + +To run with a SATA drive called `$DISK`:: + + qemu-system-x86_64 -bios build/coreboot.rom -serial mon:stdio \ + -drive id=disk,file=$DISK,if=none \ + -device ahci,id=ahci \ + -device ide-hd,drive=disk,bus=ahci.0 + +Then you can scan it with `scsi scan` and access it normally. + +To use 4GB of memory, typically necessary for booting Linux distros, add +`-m 4GB`. + 64-bit U-Boot ------------- -- cgit v1.2.3 From 04ecda0e1dffef40028d2dc66e7d47b7dcc7b4a5 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 19 Sep 2023 21:00:03 -0600 Subject: x86: coreboot: Enable standard boot Enable bootstd options and provide instructions on how to boot a linux distro using coreboot. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/board/coreboot/coreboot.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/board/coreboot/coreboot.rst b/doc/board/coreboot/coreboot.rst index be5b0de5495..3ef563b71dc 100644 --- a/doc/board/coreboot/coreboot.rst +++ b/doc/board/coreboot/coreboot.rst @@ -67,9 +67,21 @@ To use 4GB of memory, typically necessary for booting Linux distros, add In addition to the 32-bit 'coreboot' build there is a 'coreboot64' build. This produces an image which can be booted from coreboot (32-bit). Internally it works by using a 32-bit SPL binary to switch to 64-bit for running U-Boot. It -can be useful for running UEFI applications, for example. +can be useful for running UEFI applications, for example with the coreboot +build in `$CBDIR`:: + + DISK=ubuntu-23.04-desktop-amd64.iso + CBDIR=~/coreboot/build + + cp $CBDIR/coreboot.rom.in coreboot.rom + cbfstool coreboot.rom add-flat-binary -f u-boot-x86-with-spl.bin \ + -n fallback/payload -c lzma -l 0x1110000 -e 0x1110000 + + qemu-system-x86_64 -m 2G -smp 4 -bios coreboot.rom \ + -drive id=disk,file=$DISK,if=none \ + -device ahci,id=ahci \ + -device ide-hd,drive=disk,bus=ahci.0 \ -This has only been lightly tested. CBFS access ----------- -- cgit v1.2.3 From 9a1447d85e4db144e3c643e7f45582729ef0519d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 21 Sep 2023 07:37:44 -0600 Subject: x86: coreboot: Drop USB init on startup This is very annoying as it is quite slow on many machines. Also, U-Boot has an existing 'preboot' mechanism to enable this feature if desired. Drop this code so that it is possible to choose whether to init USB or not. Use the existing USE_PREBOOT mechanism instead. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/board/coreboot/coreboot.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc') diff --git a/doc/board/coreboot/coreboot.rst b/doc/board/coreboot/coreboot.rst index 3ef563b71dc..eac82cc7629 100644 --- a/doc/board/coreboot/coreboot.rst +++ b/doc/board/coreboot/coreboot.rst @@ -83,6 +83,13 @@ build in `$CBDIR`:: -device ide-hd,drive=disk,bus=ahci.0 \ +USB keyboard +------------ + +The `CONFIG_USE_PREBOOT` option is enabled by default, meaning that USB starts +up just before the command-line starts. This allows user interaction on +non-laptop devices which use a USB keyboard. + CBFS access ----------- -- cgit v1.2.3 From 0cdf6a778ebbe3259ba78fb4652d7947225bd8ae Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 19 Sep 2023 21:00:18 -0600 Subject: x86: doc: Move into its own directory There is enough material that it makes sense to split this up into several files. Create an x86/ directory for this purpose. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/arch/index.rst | 2 +- doc/arch/x86.rst | 752 ------------------------------------------------- doc/arch/x86/index.rst | 11 + doc/arch/x86/x86.rst | 752 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 764 insertions(+), 753 deletions(-) delete mode 100644 doc/arch/x86.rst create mode 100644 doc/arch/x86/index.rst create mode 100644 doc/arch/x86/x86.rst (limited to 'doc') diff --git a/doc/arch/index.rst b/doc/arch/index.rst index 2f916f4026c..60c93b3b664 100644 --- a/doc/arch/index.rst +++ b/doc/arch/index.rst @@ -15,5 +15,5 @@ Architecture-specific doc riscv sandbox/index sh - x86 + x86/index xtensa diff --git a/doc/arch/x86.rst b/doc/arch/x86.rst deleted file mode 100644 index 89d3e7ba0e4..00000000000 --- a/doc/arch/x86.rst +++ /dev/null @@ -1,752 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ -.. Copyright (C) 2014, Simon Glass -.. Copyright (C) 2014, Bin Meng - -x86 -=== - -This document describes the information about U-Boot running on x86 targets, -including supported boards, build instructions, todo list, etc. - -Status ------- -U-Boot supports running as a `coreboot`_ payload on x86. So far only Link -(Chromebook Pixel) and `QEMU`_ x86 targets have been tested, but it should -work with minimal adjustments on other x86 boards since coreboot deals with -most of the low-level details. - -U-Boot is a main bootloader on Intel Edison board. - -U-Boot also supports booting directly from x86 reset vector, without coreboot. -In this case, known as bare mode, from the fact that it runs on the -'bare metal', U-Boot acts like a BIOS replacement. The following platforms -are supported: - - - Bayley Bay CRB - - Cherry Hill CRB - - Congatec QEVAL 2.0 & conga-QA3/E3845 - - Coral (Apollo Lake - Chromebook 2017) - - Cougar Canyon 2 CRB - - Crown Bay CRB - - Galileo - - Link (Ivy Bridge - Chromebook Pixel) - - Minnowboard MAX - - Samus (Broadwell - Chromebook Pixel 2015) - - QEMU x86 (32-bit & 64-bit) - -As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit -Linux kernel as part of a FIT image. It also supports a compressed zImage. -U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks -for more details. - -Build Instructions for U-Boot as BIOS replacement (bare mode) -------------------------------------------------------------- -Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a -little bit tricky, as generally it requires several binary blobs which are not -shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build may -print some warnings if required binary blobs (e.g.: FSP) are not present. - -CPU Microcode -------------- -Modern CPUs usually require a special bit stream called `microcode`_ to be -loaded on the processor after power up in order to function properly. U-Boot -has already integrated these as hex dumps in the source tree. - -SMP Support ------------ -On a multicore system, U-Boot is executed on the bootstrap processor (BSP). -Additional application processors (AP) can be brought up by U-Boot. In order to -have an SMP kernel to discover all of the available processors, U-Boot needs to -prepare configuration tables which contain the multi-CPUs information before -loading the OS kernel. Currently U-Boot supports generating two types of tables -for SMP, called Simple Firmware Interface (`SFI`_) and Multi-Processor (`MP`_) -tables. The writing of these two tables are controlled by two Kconfig -options GENERATE_SFI_TABLE and GENERATE_MP_TABLE. - -Driver Model ------------- -x86 has been converted to use driver model for serial, GPIO, SPI, SPI flash, -keyboard, real-time clock, USB. Video is in progress. - -Device Tree ------------ -x86 uses device tree to configure the board thus requires CONFIG_OF_CONTROL to -be turned on. Not every device on the board is configured via device tree, but -more and more devices will be added as time goes by. Check out the directory -arch/x86/dts/ for these device tree source files. - -Useful Commands ---------------- -In keeping with the U-Boot philosophy of providing functions to check and -adjust internal settings, there are several x86-specific commands that may be -useful: - -fsp - Display information about Intel Firmware Support Package (FSP). - This is only available on platforms which use FSP, mostly Atom. -iod - Display I/O memory -iow - Write I/O memory -mtrr - List and set the Memory Type Range Registers (MTRR). These are used to - tell the CPU whether memory is cacheable and if so the cache write - mode to use. U-Boot sets up some reasonable values but you can - adjust then with this command. - -Booting Ubuntu --------------- -As an example of how to set up your boot flow with U-Boot, here are -instructions for starting Ubuntu from U-Boot. These instructions have been -tested on Minnowboard MAX with a SATA drive but are equally applicable on -other platforms and other media. There are really only four steps and it's a -very simple script, but a more detailed explanation is provided here for -completeness. - -Note: It is possible to set up U-Boot to boot automatically using syslinux. -It could also use the grub.cfg file (/efi/ubuntu/grub.cfg) to obtain the -GUID. If you figure these out, please post patches to this README. - -Firstly, you will need Ubuntu installed on an available disk. It should be -possible to make U-Boot start a USB start-up disk but for now let's assume -that you used another boot loader to install Ubuntu. - -Use the U-Boot command line to find the UUID of the partition you want to -boot. For example our disk is SCSI device 0:: - - => part list scsi 0 - - Partition Map for SCSI device 0 -- Partition Type: EFI - - Part Start LBA End LBA Name - Attributes - Type GUID - Partition GUID - 1 0x00000800 0x001007ff "" - attrs: 0x0000000000000000 - type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b - guid: 9d02e8e4-4d59-408f-a9b0-fd497bc9291c - 2 0x00100800 0x037d8fff "" - attrs: 0x0000000000000000 - type: 0fc63daf-8483-4772-8e79-3d69d8477de4 - guid: 965c59ee-1822-4326-90d2-b02446050059 - 3 0x037d9000 0x03ba27ff "" - attrs: 0x0000000000000000 - type: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f - guid: 2c4282bd-1e82-4bcf-a5ff-51dedbf39f17 - => - -This shows that your SCSI disk has three partitions. The really long hex -strings are called Globally Unique Identifiers (GUIDs). You can look up the -'type' ones `here`_. On this disk the first partition is for EFI and is in -VFAT format (DOS/Windows):: - - => fatls scsi 0:1 - efi/ - - 0 file(s), 1 dir(s) - - -Partition 2 is 'Linux filesystem data' so that will be our root disk. It is -in ext2 format:: - - => ext2ls scsi 0:2 - 4096 . - 4096 .. - 16384 lost+found - 4096 boot - 12288 etc - 4096 media - 4096 bin - 4096 dev - 4096 home - 4096 lib - 4096 lib64 - 4096 mnt - 4096 opt - 4096 proc - 4096 root - 4096 run - 12288 sbin - 4096 srv - 4096 sys - 4096 tmp - 4096 usr - 4096 var - 33 initrd.img - 30 vmlinuz - 4096 cdrom - 33 initrd.img.old - => - -and if you look in the /boot directory you will see the kernel:: - - => ext2ls scsi 0:2 /boot - 4096 . - 4096 .. - 4096 efi - 4096 grub - 3381262 System.map-3.13.0-32-generic - 1162712 abi-3.13.0-32-generic - 165611 config-3.13.0-32-generic - 176500 memtest86+.bin - 178176 memtest86+.elf - 178680 memtest86+_multiboot.bin - 5798112 vmlinuz-3.13.0-32-generic - 165762 config-3.13.0-58-generic - 1165129 abi-3.13.0-58-generic - 5823136 vmlinuz-3.13.0-58-generic - 19215259 initrd.img-3.13.0-58-generic - 3391763 System.map-3.13.0-58-generic - 5825048 vmlinuz-3.13.0-58-generic.efi.signed - 28304443 initrd.img-3.13.0-32-generic - => - -The 'vmlinuz' files contain a packaged Linux kernel. The format is a kind of -self-extracting compressed file mixed with some 'setup' configuration data. -Despite its size (uncompressed it is >10MB) this only includes a basic set of -device drivers, enough to boot on most hardware types. - -The 'initrd' files contain a RAM disk. This is something that can be loaded -into RAM and will appear to Linux like a disk. Ubuntu uses this to hold lots -of drivers for whatever hardware you might have. It is loaded before the -real root disk is accessed. - -The numbers after the end of each file are the version. Here it is Linux -version 3.13. You can find the source code for this in the Linux tree with -the tag v3.13. The '.0' allows for additional Linux releases to fix problems, -but normally this is not needed. The '-58' is used by Ubuntu. Each time they -release a new kernel they increment this number. New Ubuntu versions might -include kernel patches to fix reported bugs. Stable kernels can exist for -some years so this number can get quite high. - -The '.efi.signed' kernel is signed for EFI's secure boot. U-Boot has its own -secure boot mechanism - see `this`_ & `that`_. It cannot read .efi files -at present. - -To boot Ubuntu from U-Boot the steps are as follows: - -1. Set up the boot arguments. Use the GUID for the partition you want to boot:: - - => setenv bootargs root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro - -Here root= tells Linux the location of its root disk. The disk is specified -by its GUID, using '/dev/disk/by-partuuid/', a Linux path to a 'directory' -containing all the GUIDs Linux has found. When it starts up, there will be a -file in that directory with this name in it. It is also possible to use a -device name here, see later. - -2. Load the kernel. Since it is an ext2/4 filesystem we can do:: - - => ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic - -The address 30000000 is arbitrary, but there seem to be problems with using -small addresses (sometimes Linux cannot find the ramdisk). This is 48MB into -the start of RAM (which is at 0 on x86). - -3. Load the ramdisk (to 64MB):: - - => ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic - -4. Start up the kernel. We need to know the size of the ramdisk, but can use - a variable for that. U-Boot sets 'filesize' to the size of the last file it - loaded:: - - => zboot 03000000 0 04000000 ${filesize} - -Type 'help zboot' if you want to see what the arguments are. U-Boot on x86 is -quite verbose when it boots a kernel. You should see these messages from -U-Boot:: - - Valid Boot Flag - Setup Size = 0x00004400 - Magic signature found - Using boot protocol version 2.0c - Linux kernel version 3.13.0-58-generic (buildd@allspice) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 - Building boot_params at 0x00090000 - Loading bzImage at address 100000 (5805728 bytes) - Magic signature found - Initial RAM disk at linear address 0x04000000, size 19215259 bytes - Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro" - - Starting kernel ... - -U-Boot prints out some bootstage timing. This is more useful if you put the -above commands into a script since then it will be faster:: - - Timer summary in microseconds: - Mark Elapsed Stage - 0 0 reset - 241,535 241,535 board_init_r - 2,421,611 2,180,076 id=64 - 2,421,790 179 id=65 - 2,428,215 6,425 main_loop - 48,860,584 46,432,369 start_kernel - - Accumulated time: - 240,329 ahci - 1,422,704 vesa display - -Now the kernel actually starts (if you want to examine kernel boot up message on -the serial console, append "console=ttyS0,115200" to the kernel command line):: - - [ 0.000000] Initializing cgroup subsys cpuset - [ 0.000000] Initializing cgroup subsys cpu - [ 0.000000] Initializing cgroup subsys cpuacct - [ 0.000000] Linux version 3.13.0-58-generic (buildd@allspice) (gcc version 4.8.2 (Ubuntu 4.8.2-19ubuntu1) ) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 (Ubuntu 3.13.0-58.97-generic 3.13.11-ckt22) - [ 0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro console=ttyS0,115200 - -It continues for a long time. Along the way you will see it pick up your -ramdisk:: - - [ 0.000000] RAMDISK: [mem 0x04000000-0x05253fff] - ... - [ 0.788540] Trying to unpack rootfs image as initramfs... - [ 1.540111] Freeing initrd memory: 18768K (ffff880004000000 - ffff880005254000) - ... - -Later it actually starts using it:: - - Begin: Running /scripts/local-premount ... done. - -You should also see your boot disk turn up:: - - [ 4.357243] scsi 1:0:0:0: Direct-Access ATA ADATA SP310 5.2 PQ: 0 ANSI: 5 - [ 4.366860] sd 1:0:0:0: [sda] 62533296 512-byte logical blocks: (32.0 GB/29.8 GiB) - [ 4.375677] sd 1:0:0:0: Attached scsi generic sg0 type 0 - [ 4.381859] sd 1:0:0:0: [sda] Write Protect is off - [ 4.387452] sd 1:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA - [ 4.399535] sda: sda1 sda2 sda3 - -Linux has found the three partitions (sda1-3). Mercifully it doesn't print out -the GUIDs. In step 1 above we could have used:: - - setenv bootargs root=/dev/sda2 ro - -instead of the GUID. However if you add another drive to your board the -numbering may change whereas the GUIDs will not. So if your boot partition -becomes sdb2, it will still boot. For embedded systems where you just want to -boot the first disk, you have that option. - -The last thing you will see on the console is mention of plymouth (which -displays the Ubuntu start-up screen) and a lot of 'Starting' messages:: - - * Starting Mount filesystems on boot [ OK ] - -After a pause you should see a login screen on your display and you are done. - -If you want to put this in a script you can use something like this:: - - setenv bootargs root=UUID=b2aaf743-0418-4d90-94cc-3e6108d7d968 ro - setenv boot zboot 03000000 0 04000000 \${filesize} - setenv bootcmd "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; run boot" - saveenv - -The \ is to tell the shell not to evaluate ${filesize} as part of the setenv -command. - -You can also bake this behaviour into your build by hard-coding the -environment variables if you add this to minnowmax.h: - -.. code-block:: c - - #undef CONFIG_BOOTCOMMAND - #define CONFIG_BOOTCOMMAND \ - "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; " \ - "ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; " \ - "run boot" - - #undef CFG_EXTRA_ENV_SETTINGS - #define CFG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}" - -and change CONFIG_BOOTARGS value in configs/minnowmax_defconfig to:: - - CONFIG_BOOTARGS="root=/dev/sda2 ro" - -Test with SeaBIOS ------------------ -`SeaBIOS`_ is an open source implementation of a 16-bit x86 BIOS. It can run -in an emulator or natively on x86 hardware with the use of U-Boot. With its -help, we can boot some OSes that require 16-bit BIOS services like Windows/DOS. - -As U-Boot, we have to manually create a table where SeaBIOS gets various system -information (eg: E820) from. The table unfortunately has to follow the coreboot -table format as SeaBIOS currently supports booting as a coreboot payload. - -To support loading SeaBIOS, U-Boot should be built with CONFIG_SEABIOS on. -Booting SeaBIOS is done via U-Boot's bootelf command, like below:: - - => tftp bios.bin.elf;bootelf - Using e1000#0 device - TFTP from server 10.10.0.100; our IP address is 10.10.0.108 - ... - Bytes transferred = 128748 (1f6ec hex) - ## Starting application at 0x000fd269 ... - SeaBIOS (version rel-1.14.0-0-g155821a) - ... - -bios.bin.elf is the SeaBIOS image built from SeaBIOS source tree. At the time -being, SeaBIOS release 1.14.0 has been tested. To build the SeaBIOS image:: - - $ echo -e 'CONFIG_COREBOOT=y\nCONFIG_COREBOOT_FLASH=n\nCONFIG_DEBUG_SERIAL=y\nCONFIG_DEBUG_COREBOOT=n' > .config - $ make olddefconfig - $ make - ... - Total size: 128512 Fixed: 69216 Free: 2560 (used 98.0% of 128KiB rom) - Creating out/bios.bin.elf - -Currently this is tested on QEMU x86 target with U-Boot chain-loading SeaBIOS -to install/boot a Windows XP OS (below for example command to install Windows). - -.. code-block:: none - - # Create a 10G disk.img as the virtual hard disk - $ qemu-img create -f qcow2 disk.img 10G - - # Install a Windows XP OS from an ISO image 'winxp.iso' - $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -cdrom winxp.iso -smp 2 -m 512 - - # Boot a Windows XP OS installed on the virutal hard disk - $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -smp 2 -m 512 - -This is also tested on Intel Crown Bay board with a PCIe graphics card, booting -SeaBIOS then chain-loading a GRUB on a USB drive, then Linux kernel finally. - -If you are using Intel Integrated Graphics Device (IGD) as the primary display -device on your board, SeaBIOS needs to be patched manually to get its VGA ROM -loaded and run by SeaBIOS. SeaBIOS locates VGA ROM via the PCI expansion ROM -register, but IGD device does not have its VGA ROM mapped by this register. -Its VGA ROM is packaged as part of u-boot.rom at a configurable flash address -which is unknown to SeaBIOS. An example patch is needed for SeaBIOS below: - -.. code-block:: none - - diff --git a/src/optionroms.c b/src/optionroms.c - index 65f7fe0..c7b6f5e 100644 - --- a/src/optionroms.c - +++ b/src/optionroms.c - @@ -324,6 +324,8 @@ init_pcirom(struct pci_device *pci, int isvga, u64 *sources) - rom = deploy_romfile(file); - else if (RunPCIroms > 1 || (RunPCIroms == 1 && isvga)) - rom = map_pcirom(pci); - + if (pci->bdf == pci_to_bdf(0, 2, 0)) - + rom = (struct rom_header *)0xfff90000; - if (! rom) - // No ROM present. - return; - -Note: the patch above expects IGD device is at PCI b.d.f 0.2.0 and its VGA ROM -is at 0xfff90000 which corresponds to CONFIG_VGA_BIOS_ADDR on Minnowboard MAX. -Change these two accordingly if this is not the case on your board. - -Development Flow ----------------- -These notes are for those who want to port U-Boot to a new x86 platform. - -Since x86 CPUs boot from SPI flash, a SPI flash emulator is a good investment. -The Dediprog em100 can be used on Linux. - -The em100 tool is available here: http://review.coreboot.org/p/em100.git - -On Minnowboard Max the following command line can be used:: - - sudo em100 -s -p LOW -d u-boot.rom -c W25Q64DW -r - -A suitable clip for connecting over the SPI flash chip is here: -http://www.dediprog.com/pd/programmer-accessories/EM-TC-8. - -This allows you to override the SPI flash contents for development purposes. -Typically you can write to the em100 in around 1200ms, considerably faster -than programming the real flash device each time. The only important -limitation of the em100 is that it only supports SPI bus speeds up to 20MHz. -This means that images must be set to boot with that speed. This is an -Intel-specific feature - e.g. tools/ifttool has an option to set the SPI -speed in the SPI descriptor region. - -If your chip/board uses an Intel Firmware Support Package (FSP) it is fairly -easy to fit it in. You can follow the Minnowboard Max implementation, for -example. Hopefully you will just need to create new files similar to those -in arch/x86/cpu/baytrail which provide Bay Trail support. - -If you are not using an FSP you have more freedom and more responsibility. -The ivybridge support works this way, although it still uses a ROM for -graphics and still has binary blobs containing Intel code. You should aim to -support all important peripherals on your platform including video and storage. -Use the device tree for configuration where possible. - -For the microcode you can create a suitable device tree file using the -microcode tool:: - - ./tools/microcode-tool -d microcode.dat -m create - -or if you only have header files and not the full Intel microcode.dat database:: - - ./tools/microcode-tool -H BAY_TRAIL_FSP_KIT/Microcode/M0130673322.h \ - -H BAY_TRAIL_FSP_KIT/Microcode/M0130679901.h -m all create - -These are written to arch/x86/dts/microcode/ by default. - -Note that it is possible to just add the micrcode for your CPU if you know its -model. U-Boot prints this information when it starts:: - - CPU: x86_64, vendor Intel, device 30673h - -so here we can use the M0130673322 file. - -If you platform can display POST codes on two little 7-segment displays on -the board, then you can use post_code() calls from C or assembler to monitor -boot progress. This can be good for debugging. - -If not, you can try to get serial working as early as possible. The early -debug serial port may be useful here. See setup_internal_uart() for an example. - -During the U-Boot porting, one of the important steps is to write correct PIRQ -routing information in the board device tree. Without it, device drivers in the -Linux kernel won't function correctly due to interrupt is not working. Please -refer to U-Boot `doc `_ for -the device tree bindings of Intel interrupt router. Here we have more details -on the intel,pirq-routing property below. - -.. code-block:: none - - intel,pirq-routing = < - PCI_BDF(0, 2, 0) INTA PIRQA - ... - >; - -As you see each entry has 3 cells. For the first one, we need describe all pci -devices mounted on the board. For SoC devices, normally there is a chapter on -the chipset datasheet which lists all the available PCI devices. For example on -Bay Trail, this is chapter 4.3 (PCI configuration space). For the second one, we -can get the interrupt pin either from datasheet or hardware via U-Boot shell. -The reliable source is the hardware as sometimes chipset datasheet is not 100% -up-to-date. Type 'pci header' plus the device's pci bus/device/function number -from U-Boot shell below:: - - => pci header 0.1e.1 - vendor ID = 0x8086 - device ID = 0x0f08 - ... - interrupt line = 0x09 - interrupt pin = 0x04 - ... - -It shows this PCI device is using INTD pin as it reports 4 in the interrupt pin -register. Repeat this until you get interrupt pins for all the devices. The last -cell is the PIRQ line which a particular interrupt pin is mapped to. On Intel -chipset, the power-up default mapping is INTA/B/C/D maps to PIRQA/B/C/D. This -can be changed by registers in LPC bridge. So far Intel FSP does not touch those -registers so we can write down the PIRQ according to the default mapping rule. - -Once we get the PIRQ routing information in the device tree, the interrupt -allocation and assignment will be done by U-Boot automatically. Now you can -enable CONFIG_GENERATE_PIRQ_TABLE for testing Linux kernel using i8259 PIC and -CONFIG_GENERATE_MP_TABLE for testing Linux kernel using local APIC and I/O APIC. - -This script might be useful. If you feed it the output of 'pci long' from -U-Boot then it will generate a device tree fragment with the interrupt -configuration for each device (note it needs gawk 4.0.0):: - - $ cat console_output |awk '/PCI/ {device=$4} /interrupt line/ {line=$4} \ - /interrupt pin/ {pin = $4; if (pin != "0x00" && pin != "0xff") \ - {patsplit(device, bdf, "[0-9a-f]+"); \ - printf "PCI_BDF(%d, %d, %d) INT%c PIRQ%c\n", strtonum("0x" bdf[1]), \ - strtonum("0x" bdf[2]), bdf[3], strtonum(pin) + 64, 64 + strtonum(pin)}}' - -Example output:: - - PCI_BDF(0, 2, 0) INTA PIRQA - PCI_BDF(0, 3, 0) INTA PIRQA - ... - -Porting Hints -------------- - -Quark-specific considerations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To port U-Boot to other boards based on the Intel Quark SoC, a few things need -to be taken care of. The first important part is the Memory Reference Code (MRC) -parameters. Quark MRC supports memory-down configuration only. All these MRC -parameters are supplied via the board device tree. To get started, first copy -the MRC section of arch/x86/dts/galileo.dts to your board's device tree, then -change these values by consulting board manuals or your hardware vendor. -Available MRC parameter values are listed in include/dt-bindings/mrc/quark.h. -The other tricky part is with PCIe. Quark SoC integrates two PCIe root ports, -but by default they are held in reset after power on. In U-Boot, PCIe -initialization is properly handled as per Quark's firmware writer guide. -In your board support codes, you need provide two routines to aid PCIe -initialization, which are board_assert_perst() and board_deassert_perst(). -The two routines need implement a board-specific mechanism to assert/deassert -PCIe PERST# pin. Care must be taken that in those routines that any APIs that -may trigger PCI enumeration process are strictly forbidden, as any access to -PCIe root port's configuration registers will cause system hang while it is -held in reset. For more details, check how they are implemented by the Intel -Galileo board support codes in board/intel/galileo/galileo.c. - -coreboot -^^^^^^^^ - -See scripts/coreboot.sed which can assist with porting coreboot code into -U-Boot drivers. It will not resolve all build errors, but will perform common -transformations. Remember to add attribution to coreboot for new files added -to U-Boot. This should go at the top of each file and list the coreboot -filename where the code originated. - -Debugging ACPI issues with Windows -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Windows might cache system information and only detect ACPI changes if you -modify the ACPI table versions. So tweak them liberally when debugging ACPI -issues with Windows. - -ACPI Support Status -------------------- -Advanced Configuration and Power Interface (`ACPI`_) aims to establish -industry-standard interfaces enabling OS-directed configuration, power -management, and thermal management of mobile, desktop, and server platforms. - -Linux can boot without ACPI with "acpi=off" command line parameter, but -with ACPI the kernel gains the capabilities to handle power management. -For Windows, ACPI is a must-have firmware feature since Windows Vista. -CONFIG_GENERATE_ACPI_TABLE is the config option to turn on ACPI support in -U-Boot. This requires Intel ACPI compiler to be installed on your host to -compile ACPI DSDT table written in ASL format to AML format. You can get -the compiler via "apt-get install iasl" if you are on Ubuntu or download -the source from https://www.acpica.org/downloads to compile one by yourself. - -Current ACPI support in U-Boot is basically complete. More optional features -can be added in the future. The status as of today is: - - * Support generating RSDT, XSDT, FACS, FADT, MADT, MCFG tables. - * Support one static DSDT table only, compiled by Intel ACPI compiler. - * Support S0/S3/S4/S5, reboot and shutdown from OS. - * Support booting a pre-installed Ubuntu distribution via 'zboot' command. - * Support installing and booting Ubuntu 14.04 (or above) from U-Boot with - the help of SeaBIOS using legacy interface (non-UEFI mode). - * Support installing and booting Windows 8.1/10 from U-Boot with the help - of SeaBIOS using legacy interface (non-UEFI mode). - * Support ACPI interrupts with SCI only. - -Features that are optional: - - * Dynamic AML bytecodes insertion at run-time. We may need this to support - SSDT table generation and DSDT fix up. - * SMI support. Since U-Boot is a modern bootloader, we don't want to bring - those legacy stuff into U-Boot. ACPI spec allows a system that does not - support SMI (a legacy-free system). - -ACPI was initially enabled on BayTrail based boards. Testing was done by booting -a pre-installed Ubuntu 14.04 from a SATA drive. Installing Ubuntu 14.04 and -Windows 8.1/10 to a SATA drive and booting from there is also tested. Most -devices seem to work correctly and the board can respond a reboot/shutdown -command from the OS. - -For other platform boards, ACPI support status can be checked by examining their -board defconfig files to see if CONFIG_GENERATE_ACPI_TABLE is set to y. - -The S3 sleeping state is a low wake latency sleeping state defined by ACPI -spec where all system context is lost except system memory. To test S3 resume -with a Linux kernel, simply run "echo mem > /sys/power/state" and kernel will -put the board to S3 state where the power is off. So when the power button is -pressed again, U-Boot runs as it does in cold boot and detects the sleeping -state via ACPI register to see if it is S3, if yes it means we are waking up. -U-Boot is responsible for restoring the machine state as it is before sleep. -When everything is done, U-Boot finds out the wakeup vector provided by OSes -and jump there. To determine whether ACPI S3 resume is supported, check to -see if CONFIG_HAVE_ACPI_RESUME is set for that specific board. - -Note for testing S3 resume with Windows, correct graphics driver must be -installed for your platform, otherwise you won't find "Sleep" option in -the "Power" submenu from the Windows start menu. - -EFI Support ------------ -U-Boot supports booting as a 32-bit or 64-bit EFI payload, e.g. with UEFI. -This is enabled with CONFIG_EFI_STUB to boot from both 32-bit and 64-bit -UEFI BIOS. U-Boot can also run as an EFI application, with CONFIG_EFI_APP. -The CONFIG_EFI_LOADER option, where U-Boot provides an EFI environment to -the kernel (i.e. replaces UEFI completely but provides the same EFI run-time -services) is supported too. For example, we can even use 'bootefi' command -to load a 'u-boot-payload.efi', see below test logs on QEMU. - -.. code-block:: none - - => load ide 0 3000000 u-boot-payload.efi - 489787 bytes read in 138 ms (3.4 MiB/s) - => bootefi 3000000 - Scanning disk ide.blk#0... - Found 2 disks - WARNING: booting without device tree - ## Starting EFI application at 03000000 ... - U-Boot EFI Payload - - - U-Boot 2018.07-rc2 (Jun 23 2018 - 17:12:58 +0800) - - CPU: x86_64, vendor AMD, device 663h - DRAM: 2 GiB - MMC: - Video: 1024x768x32 - Model: EFI x86 Payload - Net: e1000: 52:54:00:12:34:56 - - Warning: e1000#0 using MAC address from ROM - eth0: e1000#0 - No controllers found - Hit any key to stop autoboot: 0 - -See :doc:`../develop/uefi/u-boot_on_efi` and :doc:`../develop/uefi/uefi` for -details of EFI support in U-Boot. - -Chain-loading -------------- -U-Boot can be chain-loaded from another bootloader, such as coreboot or -Slim Bootloader. Typically this is done by building for targets 'coreboot' or -'slimbootloader'. - -For example, at present we have a 'coreboot' target but this runs very -different code from the bare-metal targets, such as coral. There is very little -in common between them. - -It is useful to be able to boot the same U-Boot on a device, with or without a -first-stage bootloader. For example, with chromebook_coral, it is helpful for -testing to be able to boot the same U-Boot (complete with FSP) on bare metal -and from coreboot. It allows checking of things like CPU speed, comparing -registers, ACPI tables and the like. - -To do this you can use ll_boot_init() in appropriate places to skip init that -has already been done by the previous stage. This works by setting a -GD_FLG_NO_LL_INIT flag when U-Boot detects that it is running from another -bootloader. - -With this feature, you can build a bare-metal target and boot it from -coreboot, for example. - -Note that this is a development feature only. It is not intended for use in -production environments. Also it is not currently part of the automated tests -so may break in the future. - -SMBIOS tables -------------- - -To generate SMBIOS tables in U-Boot, for use by the OS, enable the -CONFIG_GENERATE_SMBIOS_TABLE option. The easiest way to provide the values to -use is via the device tree. For details see -:download:`smbios.txt <../device-tree-bindings/sysinfo/smbios.txt>`. - -TODO List ---------- -- Audio -- Chrome OS verified boot - -.. _coreboot: http://www.coreboot.org -.. _QEMU: http://www.qemu.org -.. _microcode: http://en.wikipedia.org/wiki/Microcode -.. _SFI: http://simplefirmware.org -.. _MP: http://www.intel.com/design/archives/processors/pro/docs/242016.htm -.. _here: https://en.wikipedia.org/wiki/GUID_Partition_Table -.. _this: http://events.linuxfoundation.org/sites/events/files/slides/chromeos_and_diy_vboot_0.pdf -.. _that: http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf -.. _SeaBIOS: http://www.seabios.org/SeaBIOS -.. _ACPI: http://www.acpi.info diff --git a/doc/arch/x86/index.rst b/doc/arch/x86/index.rst new file mode 100644 index 00000000000..3dc19d603d4 --- /dev/null +++ b/doc/arch/x86/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0+ */ +.. Copyright 2023 Google LLC +.. sectionauthor:: Simon Glass + +x86 +=== + +.. toctree:: + :maxdepth: 2 + + x86 diff --git a/doc/arch/x86/x86.rst b/doc/arch/x86/x86.rst new file mode 100644 index 00000000000..8781c16e2a1 --- /dev/null +++ b/doc/arch/x86/x86.rst @@ -0,0 +1,752 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2014, Simon Glass +.. Copyright (C) 2014, Bin Meng + +x86 +=== + +This document describes the information about U-Boot running on x86 targets, +including supported boards, build instructions, todo list, etc. + +Status +------ +U-Boot supports running as a `coreboot`_ payload on x86. So far only Link +(Chromebook Pixel) and `QEMU`_ x86 targets have been tested, but it should +work with minimal adjustments on other x86 boards since coreboot deals with +most of the low-level details. + +U-Boot is a main bootloader on Intel Edison board. + +U-Boot also supports booting directly from x86 reset vector, without coreboot. +In this case, known as bare mode, from the fact that it runs on the +'bare metal', U-Boot acts like a BIOS replacement. The following platforms +are supported: + + - Bayley Bay CRB + - Cherry Hill CRB + - Congatec QEVAL 2.0 & conga-QA3/E3845 + - Coral (Apollo Lake - Chromebook 2017) + - Cougar Canyon 2 CRB + - Crown Bay CRB + - Galileo + - Link (Ivy Bridge - Chromebook Pixel) + - Minnowboard MAX + - Samus (Broadwell - Chromebook Pixel 2015) + - QEMU x86 (32-bit & 64-bit) + +As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit +Linux kernel as part of a FIT image. It also supports a compressed zImage. +U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks +for more details. + +Build Instructions for U-Boot as BIOS replacement (bare mode) +------------------------------------------------------------- +Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a +little bit tricky, as generally it requires several binary blobs which are not +shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build may +print some warnings if required binary blobs (e.g.: FSP) are not present. + +CPU Microcode +------------- +Modern CPUs usually require a special bit stream called `microcode`_ to be +loaded on the processor after power up in order to function properly. U-Boot +has already integrated these as hex dumps in the source tree. + +SMP Support +----------- +On a multicore system, U-Boot is executed on the bootstrap processor (BSP). +Additional application processors (AP) can be brought up by U-Boot. In order to +have an SMP kernel to discover all of the available processors, U-Boot needs to +prepare configuration tables which contain the multi-CPUs information before +loading the OS kernel. Currently U-Boot supports generating two types of tables +for SMP, called Simple Firmware Interface (`SFI`_) and Multi-Processor (`MP`_) +tables. The writing of these two tables are controlled by two Kconfig +options GENERATE_SFI_TABLE and GENERATE_MP_TABLE. + +Driver Model +------------ +x86 has been converted to use driver model for serial, GPIO, SPI, SPI flash, +keyboard, real-time clock, USB. Video is in progress. + +Device Tree +----------- +x86 uses device tree to configure the board thus requires CONFIG_OF_CONTROL to +be turned on. Not every device on the board is configured via device tree, but +more and more devices will be added as time goes by. Check out the directory +arch/x86/dts/ for these device tree source files. + +Useful Commands +--------------- +In keeping with the U-Boot philosophy of providing functions to check and +adjust internal settings, there are several x86-specific commands that may be +useful: + +fsp + Display information about Intel Firmware Support Package (FSP). + This is only available on platforms which use FSP, mostly Atom. +iod + Display I/O memory +iow + Write I/O memory +mtrr + List and set the Memory Type Range Registers (MTRR). These are used to + tell the CPU whether memory is cacheable and if so the cache write + mode to use. U-Boot sets up some reasonable values but you can + adjust then with this command. + +Booting Ubuntu +-------------- +As an example of how to set up your boot flow with U-Boot, here are +instructions for starting Ubuntu from U-Boot. These instructions have been +tested on Minnowboard MAX with a SATA drive but are equally applicable on +other platforms and other media. There are really only four steps and it's a +very simple script, but a more detailed explanation is provided here for +completeness. + +Note: It is possible to set up U-Boot to boot automatically using syslinux. +It could also use the grub.cfg file (/efi/ubuntu/grub.cfg) to obtain the +GUID. If you figure these out, please post patches to this README. + +Firstly, you will need Ubuntu installed on an available disk. It should be +possible to make U-Boot start a USB start-up disk but for now let's assume +that you used another boot loader to install Ubuntu. + +Use the U-Boot command line to find the UUID of the partition you want to +boot. For example our disk is SCSI device 0:: + + => part list scsi 0 + + Partition Map for SCSI device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000800 0x001007ff "" + attrs: 0x0000000000000000 + type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b + guid: 9d02e8e4-4d59-408f-a9b0-fd497bc9291c + 2 0x00100800 0x037d8fff "" + attrs: 0x0000000000000000 + type: 0fc63daf-8483-4772-8e79-3d69d8477de4 + guid: 965c59ee-1822-4326-90d2-b02446050059 + 3 0x037d9000 0x03ba27ff "" + attrs: 0x0000000000000000 + type: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f + guid: 2c4282bd-1e82-4bcf-a5ff-51dedbf39f17 + => + +This shows that your SCSI disk has three partitions. The really long hex +strings are called Globally Unique Identifiers (GUIDs). You can look up the +'type' ones `here`_. On this disk the first partition is for EFI and is in +VFAT format (DOS/Windows):: + + => fatls scsi 0:1 + efi/ + + 0 file(s), 1 dir(s) + + +Partition 2 is 'Linux filesystem data' so that will be our root disk. It is +in ext2 format:: + + => ext2ls scsi 0:2 + 4096 . + 4096 .. + 16384 lost+found + 4096 boot + 12288 etc + 4096 media + 4096 bin + 4096 dev + 4096 home + 4096 lib + 4096 lib64 + 4096 mnt + 4096 opt + 4096 proc + 4096 root + 4096 run + 12288 sbin + 4096 srv + 4096 sys + 4096 tmp + 4096 usr + 4096 var + 33 initrd.img + 30 vmlinuz + 4096 cdrom + 33 initrd.img.old + => + +and if you look in the /boot directory you will see the kernel:: + + => ext2ls scsi 0:2 /boot + 4096 . + 4096 .. + 4096 efi + 4096 grub + 3381262 System.map-3.13.0-32-generic + 1162712 abi-3.13.0-32-generic + 165611 config-3.13.0-32-generic + 176500 memtest86+.bin + 178176 memtest86+.elf + 178680 memtest86+_multiboot.bin + 5798112 vmlinuz-3.13.0-32-generic + 165762 config-3.13.0-58-generic + 1165129 abi-3.13.0-58-generic + 5823136 vmlinuz-3.13.0-58-generic + 19215259 initrd.img-3.13.0-58-generic + 3391763 System.map-3.13.0-58-generic + 5825048 vmlinuz-3.13.0-58-generic.efi.signed + 28304443 initrd.img-3.13.0-32-generic + => + +The 'vmlinuz' files contain a packaged Linux kernel. The format is a kind of +self-extracting compressed file mixed with some 'setup' configuration data. +Despite its size (uncompressed it is >10MB) this only includes a basic set of +device drivers, enough to boot on most hardware types. + +The 'initrd' files contain a RAM disk. This is something that can be loaded +into RAM and will appear to Linux like a disk. Ubuntu uses this to hold lots +of drivers for whatever hardware you might have. It is loaded before the +real root disk is accessed. + +The numbers after the end of each file are the version. Here it is Linux +version 3.13. You can find the source code for this in the Linux tree with +the tag v3.13. The '.0' allows for additional Linux releases to fix problems, +but normally this is not needed. The '-58' is used by Ubuntu. Each time they +release a new kernel they increment this number. New Ubuntu versions might +include kernel patches to fix reported bugs. Stable kernels can exist for +some years so this number can get quite high. + +The '.efi.signed' kernel is signed for EFI's secure boot. U-Boot has its own +secure boot mechanism - see `this`_ & `that`_. It cannot read .efi files +at present. + +To boot Ubuntu from U-Boot the steps are as follows: + +1. Set up the boot arguments. Use the GUID for the partition you want to boot:: + + => setenv bootargs root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro + +Here root= tells Linux the location of its root disk. The disk is specified +by its GUID, using '/dev/disk/by-partuuid/', a Linux path to a 'directory' +containing all the GUIDs Linux has found. When it starts up, there will be a +file in that directory with this name in it. It is also possible to use a +device name here, see later. + +2. Load the kernel. Since it is an ext2/4 filesystem we can do:: + + => ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic + +The address 30000000 is arbitrary, but there seem to be problems with using +small addresses (sometimes Linux cannot find the ramdisk). This is 48MB into +the start of RAM (which is at 0 on x86). + +3. Load the ramdisk (to 64MB):: + + => ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic + +4. Start up the kernel. We need to know the size of the ramdisk, but can use + a variable for that. U-Boot sets 'filesize' to the size of the last file it + loaded:: + + => zboot 03000000 0 04000000 ${filesize} + +Type 'help zboot' if you want to see what the arguments are. U-Boot on x86 is +quite verbose when it boots a kernel. You should see these messages from +U-Boot:: + + Valid Boot Flag + Setup Size = 0x00004400 + Magic signature found + Using boot protocol version 2.0c + Linux kernel version 3.13.0-58-generic (buildd@allspice) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 + Building boot_params at 0x00090000 + Loading bzImage at address 100000 (5805728 bytes) + Magic signature found + Initial RAM disk at linear address 0x04000000, size 19215259 bytes + Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro" + + Starting kernel ... + +U-Boot prints out some bootstage timing. This is more useful if you put the +above commands into a script since then it will be faster:: + + Timer summary in microseconds: + Mark Elapsed Stage + 0 0 reset + 241,535 241,535 board_init_r + 2,421,611 2,180,076 id=64 + 2,421,790 179 id=65 + 2,428,215 6,425 main_loop + 48,860,584 46,432,369 start_kernel + + Accumulated time: + 240,329 ahci + 1,422,704 vesa display + +Now the kernel actually starts (if you want to examine kernel boot up message on +the serial console, append "console=ttyS0,115200" to the kernel command line):: + + [ 0.000000] Initializing cgroup subsys cpuset + [ 0.000000] Initializing cgroup subsys cpu + [ 0.000000] Initializing cgroup subsys cpuacct + [ 0.000000] Linux version 3.13.0-58-generic (buildd@allspice) (gcc version 4.8.2 (Ubuntu 4.8.2-19ubuntu1) ) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 (Ubuntu 3.13.0-58.97-generic 3.13.11-ckt22) + [ 0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro console=ttyS0,115200 + +It continues for a long time. Along the way you will see it pick up your +ramdisk:: + + [ 0.000000] RAMDISK: [mem 0x04000000-0x05253fff] + ... + [ 0.788540] Trying to unpack rootfs image as initramfs... + [ 1.540111] Freeing initrd memory: 18768K (ffff880004000000 - ffff880005254000) + ... + +Later it actually starts using it:: + + Begin: Running /scripts/local-premount ... done. + +You should also see your boot disk turn up:: + + [ 4.357243] scsi 1:0:0:0: Direct-Access ATA ADATA SP310 5.2 PQ: 0 ANSI: 5 + [ 4.366860] sd 1:0:0:0: [sda] 62533296 512-byte logical blocks: (32.0 GB/29.8 GiB) + [ 4.375677] sd 1:0:0:0: Attached scsi generic sg0 type 0 + [ 4.381859] sd 1:0:0:0: [sda] Write Protect is off + [ 4.387452] sd 1:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA + [ 4.399535] sda: sda1 sda2 sda3 + +Linux has found the three partitions (sda1-3). Mercifully it doesn't print out +the GUIDs. In step 1 above we could have used:: + + setenv bootargs root=/dev/sda2 ro + +instead of the GUID. However if you add another drive to your board the +numbering may change whereas the GUIDs will not. So if your boot partition +becomes sdb2, it will still boot. For embedded systems where you just want to +boot the first disk, you have that option. + +The last thing you will see on the console is mention of plymouth (which +displays the Ubuntu start-up screen) and a lot of 'Starting' messages:: + + * Starting Mount filesystems on boot [ OK ] + +After a pause you should see a login screen on your display and you are done. + +If you want to put this in a script you can use something like this:: + + setenv bootargs root=UUID=b2aaf743-0418-4d90-94cc-3e6108d7d968 ro + setenv boot zboot 03000000 0 04000000 \${filesize} + setenv bootcmd "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; run boot" + saveenv + +The \ is to tell the shell not to evaluate ${filesize} as part of the setenv +command. + +You can also bake this behaviour into your build by hard-coding the +environment variables if you add this to minnowmax.h: + +.. code-block:: c + + #undef CONFIG_BOOTCOMMAND + #define CONFIG_BOOTCOMMAND \ + "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; " \ + "ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; " \ + "run boot" + + #undef CFG_EXTRA_ENV_SETTINGS + #define CFG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}" + +and change CONFIG_BOOTARGS value in configs/minnowmax_defconfig to:: + + CONFIG_BOOTARGS="root=/dev/sda2 ro" + +Test with SeaBIOS +----------------- +`SeaBIOS`_ is an open source implementation of a 16-bit x86 BIOS. It can run +in an emulator or natively on x86 hardware with the use of U-Boot. With its +help, we can boot some OSes that require 16-bit BIOS services like Windows/DOS. + +As U-Boot, we have to manually create a table where SeaBIOS gets various system +information (eg: E820) from. The table unfortunately has to follow the coreboot +table format as SeaBIOS currently supports booting as a coreboot payload. + +To support loading SeaBIOS, U-Boot should be built with CONFIG_SEABIOS on. +Booting SeaBIOS is done via U-Boot's bootelf command, like below:: + + => tftp bios.bin.elf;bootelf + Using e1000#0 device + TFTP from server 10.10.0.100; our IP address is 10.10.0.108 + ... + Bytes transferred = 128748 (1f6ec hex) + ## Starting application at 0x000fd269 ... + SeaBIOS (version rel-1.14.0-0-g155821a) + ... + +bios.bin.elf is the SeaBIOS image built from SeaBIOS source tree. At the time +being, SeaBIOS release 1.14.0 has been tested. To build the SeaBIOS image:: + + $ echo -e 'CONFIG_COREBOOT=y\nCONFIG_COREBOOT_FLASH=n\nCONFIG_DEBUG_SERIAL=y\nCONFIG_DEBUG_COREBOOT=n' > .config + $ make olddefconfig + $ make + ... + Total size: 128512 Fixed: 69216 Free: 2560 (used 98.0% of 128KiB rom) + Creating out/bios.bin.elf + +Currently this is tested on QEMU x86 target with U-Boot chain-loading SeaBIOS +to install/boot a Windows XP OS (below for example command to install Windows). + +.. code-block:: none + + # Create a 10G disk.img as the virtual hard disk + $ qemu-img create -f qcow2 disk.img 10G + + # Install a Windows XP OS from an ISO image 'winxp.iso' + $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -cdrom winxp.iso -smp 2 -m 512 + + # Boot a Windows XP OS installed on the virutal hard disk + $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -smp 2 -m 512 + +This is also tested on Intel Crown Bay board with a PCIe graphics card, booting +SeaBIOS then chain-loading a GRUB on a USB drive, then Linux kernel finally. + +If you are using Intel Integrated Graphics Device (IGD) as the primary display +device on your board, SeaBIOS needs to be patched manually to get its VGA ROM +loaded and run by SeaBIOS. SeaBIOS locates VGA ROM via the PCI expansion ROM +register, but IGD device does not have its VGA ROM mapped by this register. +Its VGA ROM is packaged as part of u-boot.rom at a configurable flash address +which is unknown to SeaBIOS. An example patch is needed for SeaBIOS below: + +.. code-block:: none + + diff --git a/src/optionroms.c b/src/optionroms.c + index 65f7fe0..c7b6f5e 100644 + --- a/src/optionroms.c + +++ b/src/optionroms.c + @@ -324,6 +324,8 @@ init_pcirom(struct pci_device *pci, int isvga, u64 *sources) + rom = deploy_romfile(file); + else if (RunPCIroms > 1 || (RunPCIroms == 1 && isvga)) + rom = map_pcirom(pci); + + if (pci->bdf == pci_to_bdf(0, 2, 0)) + + rom = (struct rom_header *)0xfff90000; + if (! rom) + // No ROM present. + return; + +Note: the patch above expects IGD device is at PCI b.d.f 0.2.0 and its VGA ROM +is at 0xfff90000 which corresponds to CONFIG_VGA_BIOS_ADDR on Minnowboard MAX. +Change these two accordingly if this is not the case on your board. + +Development Flow +---------------- +These notes are for those who want to port U-Boot to a new x86 platform. + +Since x86 CPUs boot from SPI flash, a SPI flash emulator is a good investment. +The Dediprog em100 can be used on Linux. + +The em100 tool is available here: http://review.coreboot.org/p/em100.git + +On Minnowboard Max the following command line can be used:: + + sudo em100 -s -p LOW -d u-boot.rom -c W25Q64DW -r + +A suitable clip for connecting over the SPI flash chip is here: +http://www.dediprog.com/pd/programmer-accessories/EM-TC-8. + +This allows you to override the SPI flash contents for development purposes. +Typically you can write to the em100 in around 1200ms, considerably faster +than programming the real flash device each time. The only important +limitation of the em100 is that it only supports SPI bus speeds up to 20MHz. +This means that images must be set to boot with that speed. This is an +Intel-specific feature - e.g. tools/ifttool has an option to set the SPI +speed in the SPI descriptor region. + +If your chip/board uses an Intel Firmware Support Package (FSP) it is fairly +easy to fit it in. You can follow the Minnowboard Max implementation, for +example. Hopefully you will just need to create new files similar to those +in arch/x86/cpu/baytrail which provide Bay Trail support. + +If you are not using an FSP you have more freedom and more responsibility. +The ivybridge support works this way, although it still uses a ROM for +graphics and still has binary blobs containing Intel code. You should aim to +support all important peripherals on your platform including video and storage. +Use the device tree for configuration where possible. + +For the microcode you can create a suitable device tree file using the +microcode tool:: + + ./tools/microcode-tool -d microcode.dat -m create + +or if you only have header files and not the full Intel microcode.dat database:: + + ./tools/microcode-tool -H BAY_TRAIL_FSP_KIT/Microcode/M0130673322.h \ + -H BAY_TRAIL_FSP_KIT/Microcode/M0130679901.h -m all create + +These are written to arch/x86/dts/microcode/ by default. + +Note that it is possible to just add the micrcode for your CPU if you know its +model. U-Boot prints this information when it starts:: + + CPU: x86_64, vendor Intel, device 30673h + +so here we can use the M0130673322 file. + +If you platform can display POST codes on two little 7-segment displays on +the board, then you can use post_code() calls from C or assembler to monitor +boot progress. This can be good for debugging. + +If not, you can try to get serial working as early as possible. The early +debug serial port may be useful here. See setup_internal_uart() for an example. + +During the U-Boot porting, one of the important steps is to write correct PIRQ +routing information in the board device tree. Without it, device drivers in the +Linux kernel won't function correctly due to interrupt is not working. Please +refer to U-Boot `doc `_ for +the device tree bindings of Intel interrupt router. Here we have more details +on the intel,pirq-routing property below. + +.. code-block:: none + + intel,pirq-routing = < + PCI_BDF(0, 2, 0) INTA PIRQA + ... + >; + +As you see each entry has 3 cells. For the first one, we need describe all pci +devices mounted on the board. For SoC devices, normally there is a chapter on +the chipset datasheet which lists all the available PCI devices. For example on +Bay Trail, this is chapter 4.3 (PCI configuration space). For the second one, we +can get the interrupt pin either from datasheet or hardware via U-Boot shell. +The reliable source is the hardware as sometimes chipset datasheet is not 100% +up-to-date. Type 'pci header' plus the device's pci bus/device/function number +from U-Boot shell below:: + + => pci header 0.1e.1 + vendor ID = 0x8086 + device ID = 0x0f08 + ... + interrupt line = 0x09 + interrupt pin = 0x04 + ... + +It shows this PCI device is using INTD pin as it reports 4 in the interrupt pin +register. Repeat this until you get interrupt pins for all the devices. The last +cell is the PIRQ line which a particular interrupt pin is mapped to. On Intel +chipset, the power-up default mapping is INTA/B/C/D maps to PIRQA/B/C/D. This +can be changed by registers in LPC bridge. So far Intel FSP does not touch those +registers so we can write down the PIRQ according to the default mapping rule. + +Once we get the PIRQ routing information in the device tree, the interrupt +allocation and assignment will be done by U-Boot automatically. Now you can +enable CONFIG_GENERATE_PIRQ_TABLE for testing Linux kernel using i8259 PIC and +CONFIG_GENERATE_MP_TABLE for testing Linux kernel using local APIC and I/O APIC. + +This script might be useful. If you feed it the output of 'pci long' from +U-Boot then it will generate a device tree fragment with the interrupt +configuration for each device (note it needs gawk 4.0.0):: + + $ cat console_output |awk '/PCI/ {device=$4} /interrupt line/ {line=$4} \ + /interrupt pin/ {pin = $4; if (pin != "0x00" && pin != "0xff") \ + {patsplit(device, bdf, "[0-9a-f]+"); \ + printf "PCI_BDF(%d, %d, %d) INT%c PIRQ%c\n", strtonum("0x" bdf[1]), \ + strtonum("0x" bdf[2]), bdf[3], strtonum(pin) + 64, 64 + strtonum(pin)}}' + +Example output:: + + PCI_BDF(0, 2, 0) INTA PIRQA + PCI_BDF(0, 3, 0) INTA PIRQA + ... + +Porting Hints +------------- + +Quark-specific considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To port U-Boot to other boards based on the Intel Quark SoC, a few things need +to be taken care of. The first important part is the Memory Reference Code (MRC) +parameters. Quark MRC supports memory-down configuration only. All these MRC +parameters are supplied via the board device tree. To get started, first copy +the MRC section of arch/x86/dts/galileo.dts to your board's device tree, then +change these values by consulting board manuals or your hardware vendor. +Available MRC parameter values are listed in include/dt-bindings/mrc/quark.h. +The other tricky part is with PCIe. Quark SoC integrates two PCIe root ports, +but by default they are held in reset after power on. In U-Boot, PCIe +initialization is properly handled as per Quark's firmware writer guide. +In your board support codes, you need provide two routines to aid PCIe +initialization, which are board_assert_perst() and board_deassert_perst(). +The two routines need implement a board-specific mechanism to assert/deassert +PCIe PERST# pin. Care must be taken that in those routines that any APIs that +may trigger PCI enumeration process are strictly forbidden, as any access to +PCIe root port's configuration registers will cause system hang while it is +held in reset. For more details, check how they are implemented by the Intel +Galileo board support codes in board/intel/galileo/galileo.c. + +coreboot +^^^^^^^^ + +See scripts/coreboot.sed which can assist with porting coreboot code into +U-Boot drivers. It will not resolve all build errors, but will perform common +transformations. Remember to add attribution to coreboot for new files added +to U-Boot. This should go at the top of each file and list the coreboot +filename where the code originated. + +Debugging ACPI issues with Windows +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Windows might cache system information and only detect ACPI changes if you +modify the ACPI table versions. So tweak them liberally when debugging ACPI +issues with Windows. + +ACPI Support Status +------------------- +Advanced Configuration and Power Interface (`ACPI`_) aims to establish +industry-standard interfaces enabling OS-directed configuration, power +management, and thermal management of mobile, desktop, and server platforms. + +Linux can boot without ACPI with "acpi=off" command line parameter, but +with ACPI the kernel gains the capabilities to handle power management. +For Windows, ACPI is a must-have firmware feature since Windows Vista. +CONFIG_GENERATE_ACPI_TABLE is the config option to turn on ACPI support in +U-Boot. This requires Intel ACPI compiler to be installed on your host to +compile ACPI DSDT table written in ASL format to AML format. You can get +the compiler via "apt-get install iasl" if you are on Ubuntu or download +the source from https://www.acpica.org/downloads to compile one by yourself. + +Current ACPI support in U-Boot is basically complete. More optional features +can be added in the future. The status as of today is: + + * Support generating RSDT, XSDT, FACS, FADT, MADT, MCFG tables. + * Support one static DSDT table only, compiled by Intel ACPI compiler. + * Support S0/S3/S4/S5, reboot and shutdown from OS. + * Support booting a pre-installed Ubuntu distribution via 'zboot' command. + * Support installing and booting Ubuntu 14.04 (or above) from U-Boot with + the help of SeaBIOS using legacy interface (non-UEFI mode). + * Support installing and booting Windows 8.1/10 from U-Boot with the help + of SeaBIOS using legacy interface (non-UEFI mode). + * Support ACPI interrupts with SCI only. + +Features that are optional: + + * Dynamic AML bytecodes insertion at run-time. We may need this to support + SSDT table generation and DSDT fix up. + * SMI support. Since U-Boot is a modern bootloader, we don't want to bring + those legacy stuff into U-Boot. ACPI spec allows a system that does not + support SMI (a legacy-free system). + +ACPI was initially enabled on BayTrail based boards. Testing was done by booting +a pre-installed Ubuntu 14.04 from a SATA drive. Installing Ubuntu 14.04 and +Windows 8.1/10 to a SATA drive and booting from there is also tested. Most +devices seem to work correctly and the board can respond a reboot/shutdown +command from the OS. + +For other platform boards, ACPI support status can be checked by examining their +board defconfig files to see if CONFIG_GENERATE_ACPI_TABLE is set to y. + +The S3 sleeping state is a low wake latency sleeping state defined by ACPI +spec where all system context is lost except system memory. To test S3 resume +with a Linux kernel, simply run "echo mem > /sys/power/state" and kernel will +put the board to S3 state where the power is off. So when the power button is +pressed again, U-Boot runs as it does in cold boot and detects the sleeping +state via ACPI register to see if it is S3, if yes it means we are waking up. +U-Boot is responsible for restoring the machine state as it is before sleep. +When everything is done, U-Boot finds out the wakeup vector provided by OSes +and jump there. To determine whether ACPI S3 resume is supported, check to +see if CONFIG_HAVE_ACPI_RESUME is set for that specific board. + +Note for testing S3 resume with Windows, correct graphics driver must be +installed for your platform, otherwise you won't find "Sleep" option in +the "Power" submenu from the Windows start menu. + +EFI Support +----------- +U-Boot supports booting as a 32-bit or 64-bit EFI payload, e.g. with UEFI. +This is enabled with CONFIG_EFI_STUB to boot from both 32-bit and 64-bit +UEFI BIOS. U-Boot can also run as an EFI application, with CONFIG_EFI_APP. +The CONFIG_EFI_LOADER option, where U-Boot provides an EFI environment to +the kernel (i.e. replaces UEFI completely but provides the same EFI run-time +services) is supported too. For example, we can even use 'bootefi' command +to load a 'u-boot-payload.efi', see below test logs on QEMU. + +.. code-block:: none + + => load ide 0 3000000 u-boot-payload.efi + 489787 bytes read in 138 ms (3.4 MiB/s) + => bootefi 3000000 + Scanning disk ide.blk#0... + Found 2 disks + WARNING: booting without device tree + ## Starting EFI application at 03000000 ... + U-Boot EFI Payload + + + U-Boot 2018.07-rc2 (Jun 23 2018 - 17:12:58 +0800) + + CPU: x86_64, vendor AMD, device 663h + DRAM: 2 GiB + MMC: + Video: 1024x768x32 + Model: EFI x86 Payload + Net: e1000: 52:54:00:12:34:56 + + Warning: e1000#0 using MAC address from ROM + eth0: e1000#0 + No controllers found + Hit any key to stop autoboot: 0 + +See :doc:`../../develop/uefi/u-boot_on_efi` and :doc:`../../develop/uefi/uefi` +for details of EFI support in U-Boot. + +Chain-loading +------------- +U-Boot can be chain-loaded from another bootloader, such as coreboot or +Slim Bootloader. Typically this is done by building for targets 'coreboot' or +'slimbootloader'. + +For example, at present we have a 'coreboot' target but this runs very +different code from the bare-metal targets, such as coral. There is very little +in common between them. + +It is useful to be able to boot the same U-Boot on a device, with or without a +first-stage bootloader. For example, with chromebook_coral, it is helpful for +testing to be able to boot the same U-Boot (complete with FSP) on bare metal +and from coreboot. It allows checking of things like CPU speed, comparing +registers, ACPI tables and the like. + +To do this you can use ll_boot_init() in appropriate places to skip init that +has already been done by the previous stage. This works by setting a +GD_FLG_NO_LL_INIT flag when U-Boot detects that it is running from another +bootloader. + +With this feature, you can build a bare-metal target and boot it from +coreboot, for example. + +Note that this is a development feature only. It is not intended for use in +production environments. Also it is not currently part of the automated tests +so may break in the future. + +SMBIOS tables +------------- + +To generate SMBIOS tables in U-Boot, for use by the OS, enable the +CONFIG_GENERATE_SMBIOS_TABLE option. The easiest way to provide the values to +use is via the device tree. For details see +:download:`smbios.txt <../../device-tree-bindings/sysinfo/smbios.txt>`. + +TODO List +--------- +- Audio +- Chrome OS verified boot + +.. _coreboot: http://www.coreboot.org +.. _QEMU: http://www.qemu.org +.. _microcode: http://en.wikipedia.org/wiki/Microcode +.. _SFI: http://simplefirmware.org +.. _MP: http://www.intel.com/design/archives/processors/pro/docs/242016.htm +.. _here: https://en.wikipedia.org/wiki/GUID_Partition_Table +.. _this: http://events.linuxfoundation.org/sites/events/files/slides/chromeos_and_diy_vboot_0.pdf +.. _that: http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf +.. _SeaBIOS: http://www.seabios.org/SeaBIOS +.. _ACPI: http://www.acpi.info -- cgit v1.2.3 From f0733d26a51186e8fecccbf538ecbe043b5d1658 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 21 Sep 2023 07:37:45 -0600 Subject: x86: doc: Update summaries and add links Refresh the summary information so it is more up-to-date. Add links to the coreboot and slimbootloader docs. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/arch/x86/x86.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/arch/x86/x86.rst b/doc/arch/x86/x86.rst index 8781c16e2a1..87401008617 100644 --- a/doc/arch/x86/x86.rst +++ b/doc/arch/x86/x86.rst @@ -11,9 +11,9 @@ including supported boards, build instructions, todo list, etc. Status ------ U-Boot supports running as a `coreboot`_ payload on x86. So far only Link -(Chromebook Pixel) and `QEMU`_ x86 targets have been tested, but it should -work with minimal adjustments on other x86 boards since coreboot deals with -most of the low-level details. +(Chromebook Pixel), Brya (Alder Lake Chromebook) and `QEMU`_ x86 targets have +been tested, but it should work with minimal adjustments on other x86 boards +since coreboot deals with most of the low-level details. U-Boot is a main bootloader on Intel Edison board. @@ -32,12 +32,14 @@ are supported: - Link (Ivy Bridge - Chromebook Pixel) - Minnowboard MAX - Samus (Broadwell - Chromebook Pixel 2015) + - Coral (Apollo Lake Chromebooks circa 2017) - QEMU x86 (32-bit & 64-bit) As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit Linux kernel as part of a FIT image. It also supports a compressed zImage. U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks -for more details. +for more details. Finally, U-Boot can boot Linux distributions with a UEFI +interface. Build Instructions for U-Boot as BIOS replacement (bare mode) ------------------------------------------------------------- @@ -701,9 +703,10 @@ for details of EFI support in U-Boot. Chain-loading ------------- -U-Boot can be chain-loaded from another bootloader, such as coreboot or -Slim Bootloader. Typically this is done by building for targets 'coreboot' or -'slimbootloader'. +U-Boot can be chain-loaded from another bootloader, such as +:doc:`../../board/coreboot/index` coreboot or +:doc:`../../board/intel/slimbootloader`. Typically this is done by building for +targets 'coreboot' or 'slimbootloader'. For example, at present we have a 'coreboot' target but this runs very different code from the bare-metal targets, such as coral. There is very little -- cgit v1.2.3 From ad57b98e212bd15492398cea3a8d4df6297e16fd Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 19 Sep 2023 21:00:20 -0600 Subject: x86: doc: Split out manual booting into its own file Move this out of the main file since for simple users it is easier to rely on standard boot. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/arch/x86/index.rst | 1 + doc/arch/x86/manual_boot.rst | 276 +++++++++++++++++++++++++++++++++++++++++++ doc/arch/x86/x86.rst | 272 +----------------------------------------- 3 files changed, 280 insertions(+), 269 deletions(-) create mode 100644 doc/arch/x86/manual_boot.rst (limited to 'doc') diff --git a/doc/arch/x86/index.rst b/doc/arch/x86/index.rst index 3dc19d603d4..69db0a5d648 100644 --- a/doc/arch/x86/index.rst +++ b/doc/arch/x86/index.rst @@ -9,3 +9,4 @@ x86 :maxdepth: 2 x86 + manual_boot diff --git a/doc/arch/x86/manual_boot.rst b/doc/arch/x86/manual_boot.rst new file mode 100644 index 00000000000..ec069f2c397 --- /dev/null +++ b/doc/arch/x86/manual_boot.rst @@ -0,0 +1,276 @@ +Booting Ubuntu Manually +----------------------- + +This shows a manual approach to booting Ubuntu without standard boot or the EFI +interface. + +As an example of how to set up your boot flow with U-Boot, here are +instructions for starting Ubuntu from U-Boot. These instructions have been +tested on Minnowboard MAX with a SATA drive but are equally applicable on +other platforms and other media. There are really only four steps and it's a +very simple script, but a more detailed explanation is provided here for +completeness. + +Note: It is possible to set up U-Boot to boot automatically using syslinux. +It could also use the grub.cfg file (/efi/ubuntu/grub.cfg) to obtain the +GUID. If you figure these out, please post patches to this README. + +Firstly, you will need Ubuntu installed on an available disk. It should be +possible to make U-Boot start a USB start-up disk but for now let's assume +that you used another boot loader to install Ubuntu. + +Use the U-Boot command line to find the UUID of the partition you want to +boot. For example our disk is SCSI device 0:: + + => part list scsi 0 + + Partition Map for SCSI device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000800 0x001007ff "" + attrs: 0x0000000000000000 + type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b + guid: 9d02e8e4-4d59-408f-a9b0-fd497bc9291c + 2 0x00100800 0x037d8fff "" + attrs: 0x0000000000000000 + type: 0fc63daf-8483-4772-8e79-3d69d8477de4 + guid: 965c59ee-1822-4326-90d2-b02446050059 + 3 0x037d9000 0x03ba27ff "" + attrs: 0x0000000000000000 + type: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f + guid: 2c4282bd-1e82-4bcf-a5ff-51dedbf39f17 + => + +This shows that your SCSI disk has three partitions. The really long hex +strings are called Globally Unique Identifiers (GUIDs). You can look up the +'type' ones `here`_. On this disk the first partition is for EFI and is in +VFAT format (DOS/Windows):: + + => fatls scsi 0:1 + efi/ + + 0 file(s), 1 dir(s) + + +Partition 2 is 'Linux filesystem data' so that will be our root disk. It is +in ext2 format:: + + => ext2ls scsi 0:2 + 4096 . + 4096 .. + 16384 lost+found + 4096 boot + 12288 etc + 4096 media + 4096 bin + 4096 dev + 4096 home + 4096 lib + 4096 lib64 + 4096 mnt + 4096 opt + 4096 proc + 4096 root + 4096 run + 12288 sbin + 4096 srv + 4096 sys + 4096 tmp + 4096 usr + 4096 var + 33 initrd.img + 30 vmlinuz + 4096 cdrom + 33 initrd.img.old + => + +and if you look in the /boot directory you will see the kernel:: + + => ext2ls scsi 0:2 /boot + 4096 . + 4096 .. + 4096 efi + 4096 grub + 3381262 System.map-3.13.0-32-generic + 1162712 abi-3.13.0-32-generic + 165611 config-3.13.0-32-generic + 176500 memtest86+.bin + 178176 memtest86+.elf + 178680 memtest86+_multiboot.bin + 5798112 vmlinuz-3.13.0-32-generic + 165762 config-3.13.0-58-generic + 1165129 abi-3.13.0-58-generic + 5823136 vmlinuz-3.13.0-58-generic + 19215259 initrd.img-3.13.0-58-generic + 3391763 System.map-3.13.0-58-generic + 5825048 vmlinuz-3.13.0-58-generic.efi.signed + 28304443 initrd.img-3.13.0-32-generic + => + +The 'vmlinuz' files contain a packaged Linux kernel. The format is a kind of +self-extracting compressed file mixed with some 'setup' configuration data. +Despite its size (uncompressed it is >10MB) this only includes a basic set of +device drivers, enough to boot on most hardware types. + +The 'initrd' files contain a RAM disk. This is something that can be loaded +into RAM and will appear to Linux like a disk. Ubuntu uses this to hold lots +of drivers for whatever hardware you might have. It is loaded before the +real root disk is accessed. + +The numbers after the end of each file are the version. Here it is Linux +version 3.13. You can find the source code for this in the Linux tree with +the tag v3.13. The '.0' allows for additional Linux releases to fix problems, +but normally this is not needed. The '-58' is used by Ubuntu. Each time they +release a new kernel they increment this number. New Ubuntu versions might +include kernel patches to fix reported bugs. Stable kernels can exist for +some years so this number can get quite high. + +The '.efi.signed' kernel is signed for EFI's secure boot. U-Boot has its own +secure boot mechanism - see `this`_ & `that`_. It cannot read .efi files +at present. + +To boot Ubuntu from U-Boot the steps are as follows: + +1. Set up the boot arguments. Use the GUID for the partition you want to boot:: + + => setenv bootargs root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro + +Here root= tells Linux the location of its root disk. The disk is specified +by its GUID, using '/dev/disk/by-partuuid/', a Linux path to a 'directory' +containing all the GUIDs Linux has found. When it starts up, there will be a +file in that directory with this name in it. It is also possible to use a +device name here, see later. + +2. Load the kernel. Since it is an ext2/4 filesystem we can do:: + + => ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic + +The address 30000000 is arbitrary, but there seem to be problems with using +small addresses (sometimes Linux cannot find the ramdisk). This is 48MB into +the start of RAM (which is at 0 on x86). + +3. Load the ramdisk (to 64MB):: + + => ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic + +4. Start up the kernel. We need to know the size of the ramdisk, but can use + a variable for that. U-Boot sets 'filesize' to the size of the last file it + loaded:: + + => zboot 03000000 0 04000000 ${filesize} + +Type 'help zboot' if you want to see what the arguments are. U-Boot on x86 is +quite verbose when it boots a kernel. You should see these messages from +U-Boot:: + + Valid Boot Flag + Setup Size = 0x00004400 + Magic signature found + Using boot protocol version 2.0c + Linux kernel version 3.13.0-58-generic (buildd@allspice) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 + Building boot_params at 0x00090000 + Loading bzImage at address 100000 (5805728 bytes) + Magic signature found + Initial RAM disk at linear address 0x04000000, size 19215259 bytes + Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro" + + Starting kernel ... + +U-Boot prints out some bootstage timing. This is more useful if you put the +above commands into a script since then it will be faster:: + + Timer summary in microseconds: + Mark Elapsed Stage + 0 0 reset + 241,535 241,535 board_init_r + 2,421,611 2,180,076 id=64 + 2,421,790 179 id=65 + 2,428,215 6,425 main_loop + 48,860,584 46,432,369 start_kernel + + Accumulated time: + 240,329 ahci + 1,422,704 vesa display + +Now the kernel actually starts (if you want to examine kernel boot up message on +the serial console, append "console=ttyS0,115200" to the kernel command line):: + + [ 0.000000] Initializing cgroup subsys cpuset + [ 0.000000] Initializing cgroup subsys cpu + [ 0.000000] Initializing cgroup subsys cpuacct + [ 0.000000] Linux version 3.13.0-58-generic (buildd@allspice) (gcc version 4.8.2 (Ubuntu 4.8.2-19ubuntu1) ) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 (Ubuntu 3.13.0-58.97-generic 3.13.11-ckt22) + [ 0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro console=ttyS0,115200 + +It continues for a long time. Along the way you will see it pick up your +ramdisk:: + + [ 0.000000] RAMDISK: [mem 0x04000000-0x05253fff] + ... + [ 0.788540] Trying to unpack rootfs image as initramfs... + [ 1.540111] Freeing initrd memory: 18768K (ffff880004000000 - ffff880005254000) + ... + +Later it actually starts using it:: + + Begin: Running /scripts/local-premount ... done. + +You should also see your boot disk turn up:: + + [ 4.357243] scsi 1:0:0:0: Direct-Access ATA ADATA SP310 5.2 PQ: 0 ANSI: 5 + [ 4.366860] sd 1:0:0:0: [sda] 62533296 512-byte logical blocks: (32.0 GB/29.8 GiB) + [ 4.375677] sd 1:0:0:0: Attached scsi generic sg0 type 0 + [ 4.381859] sd 1:0:0:0: [sda] Write Protect is off + [ 4.387452] sd 1:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA + [ 4.399535] sda: sda1 sda2 sda3 + +Linux has found the three partitions (sda1-3). Mercifully it doesn't print out +the GUIDs. In step 1 above we could have used:: + + setenv bootargs root=/dev/sda2 ro + +instead of the GUID. However if you add another drive to your board the +numbering may change whereas the GUIDs will not. So if your boot partition +becomes sdb2, it will still boot. For embedded systems where you just want to +boot the first disk, you have that option. + +The last thing you will see on the console is mention of plymouth (which +displays the Ubuntu start-up screen) and a lot of 'Starting' messages:: + + * Starting Mount filesystems on boot [ OK ] + +After a pause you should see a login screen on your display and you are done. + +If you want to put this in a script you can use something like this:: + + setenv bootargs root=UUID=b2aaf743-0418-4d90-94cc-3e6108d7d968 ro + setenv boot zboot 03000000 0 04000000 \${filesize} + setenv bootcmd "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; run boot" + saveenv + +The \ is to tell the shell not to evaluate ${filesize} as part of the setenv +command. + +You can also bake this behaviour into your build by hard-coding the +environment variables if you add this to minnowmax.h: + +.. code-block:: c + + #undef CONFIG_BOOTCOMMAND + #define CONFIG_BOOTCOMMAND \ + "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; " \ + "ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; " \ + "run boot" + + #undef CFG_EXTRA_ENV_SETTINGS + #define CFG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}" + +and change CONFIG_BOOTARGS value in configs/minnowmax_defconfig to:: + + CONFIG_BOOTARGS="root=/dev/sda2 ro" + +.. _here: https://en.wikipedia.org/wiki/GUID_Partition_Table +.. _this: http://events.linuxfoundation.org/sites/events/files/slides/chromeos_and_diy_vboot_0.pdf +.. _that: http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf diff --git a/doc/arch/x86/x86.rst b/doc/arch/x86/x86.rst index 87401008617..f67216d6ce0 100644 --- a/doc/arch/x86/x86.rst +++ b/doc/arch/x86/x86.rst @@ -98,272 +98,9 @@ mtrr Booting Ubuntu -------------- -As an example of how to set up your boot flow with U-Boot, here are -instructions for starting Ubuntu from U-Boot. These instructions have been -tested on Minnowboard MAX with a SATA drive but are equally applicable on -other platforms and other media. There are really only four steps and it's a -very simple script, but a more detailed explanation is provided here for -completeness. - -Note: It is possible to set up U-Boot to boot automatically using syslinux. -It could also use the grub.cfg file (/efi/ubuntu/grub.cfg) to obtain the -GUID. If you figure these out, please post patches to this README. - -Firstly, you will need Ubuntu installed on an available disk. It should be -possible to make U-Boot start a USB start-up disk but for now let's assume -that you used another boot loader to install Ubuntu. - -Use the U-Boot command line to find the UUID of the partition you want to -boot. For example our disk is SCSI device 0:: - - => part list scsi 0 - - Partition Map for SCSI device 0 -- Partition Type: EFI - - Part Start LBA End LBA Name - Attributes - Type GUID - Partition GUID - 1 0x00000800 0x001007ff "" - attrs: 0x0000000000000000 - type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b - guid: 9d02e8e4-4d59-408f-a9b0-fd497bc9291c - 2 0x00100800 0x037d8fff "" - attrs: 0x0000000000000000 - type: 0fc63daf-8483-4772-8e79-3d69d8477de4 - guid: 965c59ee-1822-4326-90d2-b02446050059 - 3 0x037d9000 0x03ba27ff "" - attrs: 0x0000000000000000 - type: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f - guid: 2c4282bd-1e82-4bcf-a5ff-51dedbf39f17 - => - -This shows that your SCSI disk has three partitions. The really long hex -strings are called Globally Unique Identifiers (GUIDs). You can look up the -'type' ones `here`_. On this disk the first partition is for EFI and is in -VFAT format (DOS/Windows):: - - => fatls scsi 0:1 - efi/ - - 0 file(s), 1 dir(s) - - -Partition 2 is 'Linux filesystem data' so that will be our root disk. It is -in ext2 format:: - - => ext2ls scsi 0:2 - 4096 . - 4096 .. - 16384 lost+found - 4096 boot - 12288 etc - 4096 media - 4096 bin - 4096 dev - 4096 home - 4096 lib - 4096 lib64 - 4096 mnt - 4096 opt - 4096 proc - 4096 root - 4096 run - 12288 sbin - 4096 srv - 4096 sys - 4096 tmp - 4096 usr - 4096 var - 33 initrd.img - 30 vmlinuz - 4096 cdrom - 33 initrd.img.old - => - -and if you look in the /boot directory you will see the kernel:: - - => ext2ls scsi 0:2 /boot - 4096 . - 4096 .. - 4096 efi - 4096 grub - 3381262 System.map-3.13.0-32-generic - 1162712 abi-3.13.0-32-generic - 165611 config-3.13.0-32-generic - 176500 memtest86+.bin - 178176 memtest86+.elf - 178680 memtest86+_multiboot.bin - 5798112 vmlinuz-3.13.0-32-generic - 165762 config-3.13.0-58-generic - 1165129 abi-3.13.0-58-generic - 5823136 vmlinuz-3.13.0-58-generic - 19215259 initrd.img-3.13.0-58-generic - 3391763 System.map-3.13.0-58-generic - 5825048 vmlinuz-3.13.0-58-generic.efi.signed - 28304443 initrd.img-3.13.0-32-generic - => - -The 'vmlinuz' files contain a packaged Linux kernel. The format is a kind of -self-extracting compressed file mixed with some 'setup' configuration data. -Despite its size (uncompressed it is >10MB) this only includes a basic set of -device drivers, enough to boot on most hardware types. - -The 'initrd' files contain a RAM disk. This is something that can be loaded -into RAM and will appear to Linux like a disk. Ubuntu uses this to hold lots -of drivers for whatever hardware you might have. It is loaded before the -real root disk is accessed. - -The numbers after the end of each file are the version. Here it is Linux -version 3.13. You can find the source code for this in the Linux tree with -the tag v3.13. The '.0' allows for additional Linux releases to fix problems, -but normally this is not needed. The '-58' is used by Ubuntu. Each time they -release a new kernel they increment this number. New Ubuntu versions might -include kernel patches to fix reported bugs. Stable kernels can exist for -some years so this number can get quite high. - -The '.efi.signed' kernel is signed for EFI's secure boot. U-Boot has its own -secure boot mechanism - see `this`_ & `that`_. It cannot read .efi files -at present. - -To boot Ubuntu from U-Boot the steps are as follows: - -1. Set up the boot arguments. Use the GUID for the partition you want to boot:: - - => setenv bootargs root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro - -Here root= tells Linux the location of its root disk. The disk is specified -by its GUID, using '/dev/disk/by-partuuid/', a Linux path to a 'directory' -containing all the GUIDs Linux has found. When it starts up, there will be a -file in that directory with this name in it. It is also possible to use a -device name here, see later. - -2. Load the kernel. Since it is an ext2/4 filesystem we can do:: - - => ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic - -The address 30000000 is arbitrary, but there seem to be problems with using -small addresses (sometimes Linux cannot find the ramdisk). This is 48MB into -the start of RAM (which is at 0 on x86). - -3. Load the ramdisk (to 64MB):: - - => ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic - -4. Start up the kernel. We need to know the size of the ramdisk, but can use - a variable for that. U-Boot sets 'filesize' to the size of the last file it - loaded:: - - => zboot 03000000 0 04000000 ${filesize} - -Type 'help zboot' if you want to see what the arguments are. U-Boot on x86 is -quite verbose when it boots a kernel. You should see these messages from -U-Boot:: - - Valid Boot Flag - Setup Size = 0x00004400 - Magic signature found - Using boot protocol version 2.0c - Linux kernel version 3.13.0-58-generic (buildd@allspice) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 - Building boot_params at 0x00090000 - Loading bzImage at address 100000 (5805728 bytes) - Magic signature found - Initial RAM disk at linear address 0x04000000, size 19215259 bytes - Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro" - - Starting kernel ... - -U-Boot prints out some bootstage timing. This is more useful if you put the -above commands into a script since then it will be faster:: - - Timer summary in microseconds: - Mark Elapsed Stage - 0 0 reset - 241,535 241,535 board_init_r - 2,421,611 2,180,076 id=64 - 2,421,790 179 id=65 - 2,428,215 6,425 main_loop - 48,860,584 46,432,369 start_kernel - - Accumulated time: - 240,329 ahci - 1,422,704 vesa display - -Now the kernel actually starts (if you want to examine kernel boot up message on -the serial console, append "console=ttyS0,115200" to the kernel command line):: - - [ 0.000000] Initializing cgroup subsys cpuset - [ 0.000000] Initializing cgroup subsys cpu - [ 0.000000] Initializing cgroup subsys cpuacct - [ 0.000000] Linux version 3.13.0-58-generic (buildd@allspice) (gcc version 4.8.2 (Ubuntu 4.8.2-19ubuntu1) ) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 (Ubuntu 3.13.0-58.97-generic 3.13.11-ckt22) - [ 0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro console=ttyS0,115200 - -It continues for a long time. Along the way you will see it pick up your -ramdisk:: - - [ 0.000000] RAMDISK: [mem 0x04000000-0x05253fff] - ... - [ 0.788540] Trying to unpack rootfs image as initramfs... - [ 1.540111] Freeing initrd memory: 18768K (ffff880004000000 - ffff880005254000) - ... - -Later it actually starts using it:: - - Begin: Running /scripts/local-premount ... done. - -You should also see your boot disk turn up:: - - [ 4.357243] scsi 1:0:0:0: Direct-Access ATA ADATA SP310 5.2 PQ: 0 ANSI: 5 - [ 4.366860] sd 1:0:0:0: [sda] 62533296 512-byte logical blocks: (32.0 GB/29.8 GiB) - [ 4.375677] sd 1:0:0:0: Attached scsi generic sg0 type 0 - [ 4.381859] sd 1:0:0:0: [sda] Write Protect is off - [ 4.387452] sd 1:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA - [ 4.399535] sda: sda1 sda2 sda3 - -Linux has found the three partitions (sda1-3). Mercifully it doesn't print out -the GUIDs. In step 1 above we could have used:: - - setenv bootargs root=/dev/sda2 ro - -instead of the GUID. However if you add another drive to your board the -numbering may change whereas the GUIDs will not. So if your boot partition -becomes sdb2, it will still boot. For embedded systems where you just want to -boot the first disk, you have that option. - -The last thing you will see on the console is mention of plymouth (which -displays the Ubuntu start-up screen) and a lot of 'Starting' messages:: - - * Starting Mount filesystems on boot [ OK ] - -After a pause you should see a login screen on your display and you are done. - -If you want to put this in a script you can use something like this:: - - setenv bootargs root=UUID=b2aaf743-0418-4d90-94cc-3e6108d7d968 ro - setenv boot zboot 03000000 0 04000000 \${filesize} - setenv bootcmd "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; run boot" - saveenv - -The \ is to tell the shell not to evaluate ${filesize} as part of the setenv -command. - -You can also bake this behaviour into your build by hard-coding the -environment variables if you add this to minnowmax.h: - -.. code-block:: c - - #undef CONFIG_BOOTCOMMAND - #define CONFIG_BOOTCOMMAND \ - "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; " \ - "ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; " \ - "run boot" - - #undef CFG_EXTRA_ENV_SETTINGS - #define CFG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}" - -and change CONFIG_BOOTARGS value in configs/minnowmax_defconfig to:: - - CONFIG_BOOTARGS="root=/dev/sda2 ro" +Typically U-Boot boots distributions automatically so long an `CONFIG_BOOTSTD`, +`CONFIG_BOOTSTD_DEFAULTS` and `CONFIG_EFI_LOADER` are enabled. See +:doc:`manual_boot` for how to do this manually. Test with SeaBIOS ----------------- @@ -748,8 +485,5 @@ TODO List .. _microcode: http://en.wikipedia.org/wiki/Microcode .. _SFI: http://simplefirmware.org .. _MP: http://www.intel.com/design/archives/processors/pro/docs/242016.htm -.. _here: https://en.wikipedia.org/wiki/GUID_Partition_Table -.. _this: http://events.linuxfoundation.org/sites/events/files/slides/chromeos_and_diy_vboot_0.pdf -.. _that: http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf .. _SeaBIOS: http://www.seabios.org/SeaBIOS .. _ACPI: http://www.acpi.info -- cgit v1.2.3 From 5728246dfa11400d4f7aa8262ea630d8c09a85b9 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Tue, 19 Sep 2023 21:00:21 -0600 Subject: x86: doc: coreboot: Mention 64-bit Linux distros Add a little more detail as to why coreboot64 is preferred for booting Linux distros. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/board/coreboot/coreboot.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/board/coreboot/coreboot.rst b/doc/board/coreboot/coreboot.rst index eac82cc7629..10a251c2b64 100644 --- a/doc/board/coreboot/coreboot.rst +++ b/doc/board/coreboot/coreboot.rst @@ -82,6 +82,8 @@ build in `$CBDIR`:: -device ahci,id=ahci \ -device ide-hd,drive=disk,bus=ahci.0 \ +This allows booting and installing various distros, many of which are +64-bit-only, so cannot work with the 32-bit 'coreboot' build. USB keyboard ------------ -- cgit v1.2.3 From 36e45f69c4c6a626fd12de7b3b25135162758654 Mon Sep 17 00:00:00 2001 From: AKASHI Takahiro Date: Wed, 23 Aug 2023 10:49:47 +0900 Subject: cmd: dm: allow for selecting uclass and device The output from "dm tree" or "dm uclass" is a bit annoying if the number of devices available on the system is huge. (This is especially true on sandbox when I debug some DM code.) With this patch, we can specify the uclass name or the device name that we are interested in in order to limit the output. For instance, => dm uclass usb uclass 121: usb 0 usb@1 @ 0bcff8b0, seq 1 uclass 124: usb => dm tree usb:usb@1 Class Index Probed Driver Name ----------------------------------------------------------- usb 0 [ ] usb_sandbox usb@1 usb_hub 0 [ ] usb_hub `-- hub usb_emul 0 [ ] usb_sandbox_hub `-- hub-emul usb_emul 1 [ ] usb_sandbox_flash |-- flash-stick@0 usb_emul 2 [ ] usb_sandbox_flash |-- flash-stick@1 usb_emul 3 [ ] usb_sandbox_flash |-- flash-stick@2 usb_emul 4 [ ] usb_sandbox_keyb `-- keyb@3 If you want forward-matching against a uclass or udevice name, you can specify "-e" option. => dm uclass -e usb uclass 15: usb_emul 0 hub-emul @ 0bcffb00, seq 0 1 flash-stick@0 @ 0bcffc30, seq 1 2 flash-stick@1 @ 0bcffdc0, seq 2 3 flash-stick@2 @ 0bcfff50, seq 3 4 keyb@3 @ 0bd000e0, seq 4 uclass 64: usb_mass_storage uclass 121: usb 0 usb@1 @ 0bcff8b0, seq 1 uclass 122: usb_dev_generic uclass 123: usb_hub 0 hub @ 0bcff9b0, seq 0 uclass 124: usb => dm tree -e usb Class Index Probed Driver Name ----------------------------------------------------------- usb 0 [ ] usb_sandbox usb@1 usb_hub 0 [ ] usb_hub `-- hub usb_emul 0 [ ] usb_sandbox_hub `-- hub-emul usb_emul 1 [ ] usb_sandbox_flash |-- flash-stick@0 usb_emul 2 [ ] usb_sandbox_flash |-- flash-stick@1 usb_emul 3 [ ] usb_sandbox_flash |-- flash-stick@2 usb_emul 4 [ ] usb_sandbox_keyb `-- keyb@3 Signed-off-by: AKASHI Takahiro Reviewed-by: Simon Glass --- doc/usage/cmd/dm.rst | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/usage/cmd/dm.rst b/doc/usage/cmd/dm.rst index 74c6b01e361..12b7edeed68 100644 --- a/doc/usage/cmd/dm.rst +++ b/doc/usage/cmd/dm.rst @@ -12,8 +12,8 @@ Synopis dm devres dm drivers dm static - dm tree [-s] - dm uclass + dm tree [-s][-e] [uclass name] + dm uclass [-e] [udevice name] Description ----------- @@ -127,6 +127,12 @@ If -s is given, the top-level devices (those which are children of the root device) are shown sorted in order of uclass ID, so it is easier to find a particular device type. +If -e is given, forward-matching against existing devices is +made and only the matched devices are shown. + +If a device name is given, forward-matching against existing devices is +made and only the matched devices are shown. + dm uclass ~~~~~~~~~ @@ -140,6 +146,11 @@ For each device, the format is:: where `n` is the index within the uclass, `a` is the address of the device in memory and `s` is the sequence number of the device. +If -e is given, forward-matching against existing uclasses is +made and only the matched uclasses are shown. + +If no uclass name is given, all the uclasses are shown. + Examples -------- @@ -409,6 +420,15 @@ This example shows the abridged sandbox output:: nop 8 [ ] scmi_voltage_domain `-- regulators regulator 5 [ ] scmi_regulator |-- reg@0 regulator 6 [ ] scmi_regulator `-- reg@1 + => dm tree pinc + pinctrl 0 [ + ] sandbox_pinctrl_gpio pinctrl-gpio + gpio 1 [ + ] sandbox_gpio |-- base-gpios + nop 0 [ + ] gpio_hog | |-- hog_input_active_low + nop 1 [ + ] gpio_hog | |-- hog_input_active_high + nop 2 [ + ] gpio_hog | |-- hog_output_low + nop 3 [ + ] gpio_hog | `-- hog_output_high + gpio 2 [ ] sandbox_gpio |-- extra-gpios + gpio 3 [ ] sandbox_gpio `-- pinmux-gpios => @@ -487,4 +507,10 @@ This example shows the abridged sandbox output:: 0 * gpio-wdt @ 0301c070, seq 0 1 * wdt@0 @ 03021710, seq 1 + => dm uclass blk + uclass 22: blk + 0 mmc2.blk @ 0301ca00, seq 0 + 1 mmc1.blk @ 0301cee0, seq 1 + 2 mmc0.blk @ 0301d380, seq 2 + => -- cgit v1.2.3 From ae84514feee209091d331a8baaa344ed8d8e905b Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 7 Sep 2023 10:00:20 -0600 Subject: kontron_sl28: Use u-boot-update.bin instead of u-boot.update A '.update' extension does not get preserved by buildman, so change it. Signed-off-by: Simon Glass Acked-by: Michael Walle --- doc/board/kontron/sl28.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/board/kontron/sl28.rst b/doc/board/kontron/sl28.rst index 44435d90c62..2cb8ec62be4 100644 --- a/doc/board/kontron/sl28.rst +++ b/doc/board/kontron/sl28.rst @@ -39,12 +39,12 @@ Update image ------------ After the build finished, there will be an update image called -u-boot.update. This can either be used in the DFU mode (which isn't +u-boot-update.bin. This can either be used in the DFU mode (which isn't supported yet) or encapsulated in an EFI UpdateCapsule. To build the capsule use the following command - $ tools/mkeficapsule -f u-boot.update -i 1 UpdateUboot + $ tools/mkeficapsule -f u-boot-update.bin -i 1 UpdateUboot Afterward you can copy this file to your ESP into the /EFI/UpdateCapsule/ folder. On the next EFI boot this will automatically update your -- cgit v1.2.3