From patchwork Sun Dec 20 16:11:41 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1418831 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=85.214.62.61; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmx.de Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.a=rsa-sha256 header.s=badeba3b8450 header.b=VrThl3SH; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4CzSKR4GWzz9sVj for ; Mon, 21 Dec 2020 03:11:55 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 4026E8266E; Sun, 20 Dec 2020 17:11:52 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.b="VrThl3SH"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 8D0D1828C5; Sun, 20 Dec 2020 17:11:50 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW,RCVD_IN_MSPIKE_H2, SPF_HELO_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from mout.gmx.net (mout.gmx.net [212.227.15.18]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id E24C88266B for ; Sun, 20 Dec 2020 17:11:46 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=xypron.glpk@gmx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1608480706; bh=Sw+KgcswzHdG8h4P+80fGiDFtfL0z2ydICg35nOIMwM=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date; b=VrThl3SHN25u0QAxzfNL9llW+R0Fz0DNbzhyLoaV2d/J06Vpchc0T/QpOx7EL20b/ dkBhyGmHjizDPIaE0Mew67cSWQ0eguKzG4rAD2qsfgx1BgGPlJlb6P44KNildD+RKU SEZ58FznVoPBwd3QrWcmQxDXEZpfOSopajzKuXmM= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from LT02.fritz.box ([62.143.246.89]) by mail.gmx.com (mrgmx004 [212.227.17.184]) with ESMTPSA (Nemesis) id 1MhD2O-1kCzSt3jGM-00eJPc; Sun, 20 Dec 2020 17:11:45 +0100 From: Heinrich Schuchardt To: Alexander Graf Cc: u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH v2 1/1] doc: man-page for bootefi command Date: Sun, 20 Dec 2020 17:11:41 +0100 Message-Id: <20201220161141.19068-1-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.29.2 MIME-Version: 1.0 X-Provags-ID: V03:K1:d0TrvA/8xyAvSXUB5CcJWlrlmjB5jRl4yBKmok/3sYyILDewnFU dq9AhGIC5SrkMDlX6mX+m1sDsGb5ups6ZM9peyZBzvnw2+xIMKt+Nu3nLIJ6wuMUJp7CNgd 4imHux0kbcIdPLxVs1ynj9F7DoNLkg/+AhhU6TiIov/s0LX5NTRHQp1UG1rO2/f8sDxZxyl YpgPCCxEyYraGub+nmzbQ== X-UI-Out-Filterresults: notjunk:1;V03:K0:lEA/Cb1CtXk=:HyyIGW2UTHWud5Ps0D9REE VlLqXmHWIPDm2OPjtqe10LpRAACAx0KY2R+yuofgYhyOJRs7xMxijhYoqnvIJpQopndkR4jXl b4Zer9d+QrAwtRmo9/CGL7Qu1gbmogOqZFiDzsSP2hUT0F0Dnkgm2vLBQwXgwLKb0NZR7e8lC q2lU3r9Td+Lg5xOSNWJ2yN9pcESQmV4Hh4DRb0ueEqJdbhmAStcq6nFFLYNos0r+p5voC+U4O /sRS7WbTbehLwaW8gRlFgt0DwW4xlHzV0InDjMGf2JY2dqZ2U8raTgWcUkZfH5/DHA/D10jUB XBtv0bTu0BGcUlqbTLDSrzwioxcRoqQddHs15zZoeQ8jbx0dATmiKtIllDTdk5Jt0OSNKP6OD ljzoFJJzC3FBw+HcmXp6pHNrIXw0na7STJOR/7I5w/SLWPZB3ksuVk7je3ZbzjLKlvY+l7UsK 3a0RuvvOQ//Z5NxW4sAe+AlAHXPQ/F9JheZzTm9roAPPQPl5T6B8j8twgyutYor/htflYY4ay LAw/ODjXwvI4jc9YmdWJ6QOb8J2Jz13rFmKoD8UcUJrRF70bzxRHKOQGYI2RjbMXuJNmBF0gb 1FqLJYhQ062DxAMbngSoiYVtC1MlqBmh+DgDRVABEtARQo8Q39HEzjQFDwdMb9yZbHxqUJI2B LXJYtBRpc8K1E6esm9y+NNPtg+44iOzLDbrGJ3Tmtje9o8xddPawAOGr1r2g4qb+oydsr+wRe ev2QFMPzT+FErw/sRN60GBO6Ln37QXQBtyzjtVAgGjWYxtqOOASpLZa6u9l20hziiwx2++D1S 2nvMK5M2ByLpL0pI+ye2pO5N/m7/SNzkIbYiyKKiuuLq9vyQb7gbsZjyhcX01ajiJFb8ZI2LZ GDAKRKWuhP6pwxhuCocg== X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.102.3 at phobos.denx.de X-Virus-Status: Clean Provide a description of the bootefi command. Signed-off-by: Heinrich Schuchardt --- v2: Replace ".. code-block::" by "::" as the build-system on Gitlab does not like code-block without language. The problem did not occur locally. --- MAINTAINERS | 1 + doc/usage/bootefi.rst | 135 ++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 3 files changed, 137 insertions(+) create mode 100644 doc/usage/bootefi.rst -- 2.29.2 diff --git a/MAINTAINERS b/MAINTAINERS index 127e30c0a5..8675965fe5 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -679,6 +679,7 @@ S: Maintained T: git https://gitlab.denx.de/u-boot/custodians/u-boot-efi.git F: doc/api/efi.rst F: doc/uefi/* +F: doc/usage/bootefi.rst F: drivers/rtc/emul_rtc.c F: include/capitalization.h F: include/charset.h diff --git a/doc/usage/bootefi.rst b/doc/usage/bootefi.rst new file mode 100644 index 0000000000..282f22aac9 --- /dev/null +++ b/doc/usage/bootefi.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020, Heinrich Schuchardt + +bootefi command +=============== + +Synopsis +-------- + +:: + + bootefi [image_addr] [fdt_addr] + bootefi bootmgr [fdt_addr] + bootefi hello [fdt_addr] + bootefi selftest [fdt_addr] + +Description +----------- + +The *bootefi* command is used to launch a UEFI binary which can be either of + +* UEFI application +* UEFI boot services driver +* UEFI run-time services driver + +An operating system requires a hardware description which can either be +presented as ACPI table (CONFIG\_GENERATE\_ACPI\_TABLE=y) or as device-tree +The load address of the device-tree may be provided as parameter *fdt\_addr*. If +this address is not specified, the bootefi command will try to fall back in +sequence to: + +* the device-tree specified by environment variable *fdt\_addr* +* the device-tree specified by environment variable *fdtcontroladdr* + +The load address of the binary is specified by parameter *image_address*. A +command sequence to run a UEFI application might look like + +:: + + load mmc 0:2 $fdt_addr_r dtb + load mmc 0:1 $kernel_addr_r /EFI/grub/grubaa64.efi + bootefi $kernel_addr_r $fdt_addr_r + +The last file loaded defines the image file path in the loaded image protocol. +Hence the executable should always be loaded last. + +The value of the environment variable *bootargs* is converted from UTF-8 to +UTF-16 and passed as load options in the loaded image protocol to the UEFI +binary. + +Note + UEFI binaries that are contained in FIT images are launched via the + *bootm* command. + +UEFI boot manager +''''''''''''''''' + +The UEFI boot manager is invoked by the *bootefi bootmgr* sub-command. +Here boot options are defined by UEFI variables with a name consisting of the +letters *Boot* followed by a four digit hexadecimal number, e.g. *Boot0001* or +*BootA03E*. The boot variable defines a label, the device path of the binary to +execute as well as the load options passed in the loaded image protocol. + +If the UEFI variable *BootNext* is defined, it specifies the number of the boot +option to execute next. If no binary can be loaded via *BootNext* the variable +*BootOrder* specifies in which sequence boot options shalled be tried. + +The values of these variables can be managed using the U-Boot command +*efidebug*. + +UEFI hello world application +'''''''''''''''''''''''''''' + +U-Boot can be compiled with a hello world application that can be launched using +the *bootefi hello* sub-command. A session might look like + +:: + + => setenv bootargs 'Greetings to the world' + => bootefi hello + Booting /MemoryMapped(0x0,0x10001000,0x1000) + Hello, world! + Running on UEFI 2.8 + Have SMBIOS table + Have device tree + Load options: Greetings to the world + +UEFI selftest +''''''''''''' + +U-Boot can be compiled with UEFI unit tests. These unit tests are invoked using +the *bootefi selftest* sub-command. + +Which unit test is executed is controlled by the environment variable +*efi\_selftest*. If this variable is not set, all unit tests that are not marked +as 'on request' are executed. + +To show a list of the available unit tests the value *list* can be used + +:: + + => setenv efi_selftest list + => bootefi selftest + + Available tests: + 'block image transfer' - on request + 'block device' + 'configuration tables' + ... + +A single test is selected for execution by setting the *efi\_selftest* +environment variable to match one of the listed identifiers + +:: + + => setenv efi_selftest 'block image transfer' + => bootefi selftest + +Some of the tests execute the ExitBootServices() UEFI boot service and will not +return to the command line but require a board reset. + +Configuration +------------- + +To use the *bootefi* command you must specify CONFIG\_CMD\_BOOTEFI=y. +The *bootefi hello* sub-command requries CMD\_BOOTEFI\_HELLO=y. +The *bootefi selftest* sub-command depends on CMD\_BOOTEFI\_SELFTEST=y. + +See also +-------- + +* *bootm* for launching UEFI binaries packed in FIT images +* *booti*, *bootm*, *bootz* for launching a Linux kernel without using the + UEFI sub-system +* *efidebug* for setting UEFI boot variables diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 6c4b5b9240..fbb2c0481c 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -11,6 +11,7 @@ Shell commands .. toctree:: :maxdepth: 1 + bootefi bootmenu button pstore