Merge tag 'efi-2022-07-rc1-2' of https://source.denx.de/u-boot/custodians/u-boot-efiWIP/15Apr2022

Pull request for efi-2022-07-rc1-2

Documentation:

* Describe env command

UEFI

* simplify Unicode string functions
* clean up the usage of GUIDs for capsule updates

7 files changed, 485 insertions, 15 deletions

diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
index fe337c8..753a4e5 100644
--- a/doc/develop/uefi/uefi.rst
+++ b/doc/develop/uefi/uefi.rst
@@ -312,8 +312,8 @@ Run the following command
 .. code-block:: console
 
     $ mkeficapsule \
-      --index 1 --instance 0 \
-      [--fit <FIT image> | --raw <raw image>] \
+      --index <index> --instance 0 \
+      --guid <image GUID> \
       <capsule_file_name>
 
 Performing the update
@@ -333,8 +333,104 @@ won't be taken over across the reboot. If this is the case, you can skip
 this feature check with the Kconfig option (CONFIG_EFI_IGNORE_OSINDICATIONS)
 set.
 
+A few values need to be defined in the board file for performing the
+capsule update. These values are defined in the board file by
+initialisation of a structure which provides information needed for
+capsule updates. The following structures have been defined for
+containing the image related information
+
+.. code-block:: c
+
+	struct efi_fw_image {
+		efi_guid_t image_type_id;
+		u16 *fw_name;
+		u8 image_index;
+	};
+
+	struct efi_capsule_update_info {
+		const char *dfu_string;
+		struct efi_fw_image *images;
+	};
+
+
+A string is defined which is to be used for populating the
+dfu_alt_info variable. This string is used by the function
+set_dfu_alt_info. Instead of taking the variable from the environment,
+the capsule update feature requires that the variable be set through
+the function, since that is more robust. Allowing the user to change
+the location of the firmware updates is not a very secure
+practice. Getting this information from the firmware itself is more
+secure, assuming the firmware has been verified by a previous stage
+boot loader.
+
+The firmware images structure defines the GUID values, image index
+values and the name of the images that are to be updated through
+the capsule update feature. These values are to be defined as part of
+an array. These GUID values would be used by the Firmware Management
+Protocol(FMP) to populate the image descriptor array and also
+displayed as part of the ESRT table. The image index values defined in
+the array should be one greater than the dfu alt number that
+corresponds to the firmware image. So, if the dfu alt number for an
+image is 2, the value of image index in the fw_images array for that
+image should be 3. The dfu alt number can be obtained by running the
+following command::
+
+    dfu list
+
+When using the FMP for FIT images, the image index value needs to be
+set to 1.
+
 Finally, the capsule update can be initiated by rebooting the board.
 
+An example of setting the values in the struct efi_fw_image and
+struct efi_capsule_update_info is shown below
+
+.. code-block:: c
+
+	struct efi_fw_image fw_images[] = {
+		{
+			.image_type_id = DEVELOPERBOX_UBOOT_IMAGE_GUID,
+			.fw_name = u"DEVELOPERBOX-UBOOT",
+			.image_index = 1,
+		},
+		{
+			.image_type_id = DEVELOPERBOX_FIP_IMAGE_GUID,
+			.fw_name = u"DEVELOPERBOX-FIP",
+			.image_index = 2,
+		},
+		{
+			.image_type_id = DEVELOPERBOX_OPTEE_IMAGE_GUID,
+			.fw_name = u"DEVELOPERBOX-OPTEE",
+			.image_index = 3,
+		},
+	};
+
+	struct efi_capsule_update_info update_info = {
+		.dfu_string = "mtd nor1=u-boot.bin raw 200000 100000;"
+				"fip.bin raw 180000 78000;"
+				"optee.bin raw 500000 100000",
+		.images = fw_images,
+	};
+
+Platforms must declare a variable update_info of type struct
+efi_capsule_update_info as shown in the example above. The platform
+will also define a fw_images array which contains information of all
+the firmware images that are to be updated through capsule update
+mechanism. The dfu_string is the string that is to be set as
+dfu_alt_info. In the example above, the image index to be set for
+u-boot.bin binary is 0x1, for fip.bin is 0x2 and for optee.bin is 0x3.
+
+As an example, for generating the capsule for the optee.bin image, the
+following command can be issued
+
+.. code-block:: bash
+
+    $ ./tools/mkeficapsule \
+      --index 0x3 --instance 0 \
+      --guid c1b629f1-ce0e-4894-82bf-f0a38387e630 \
+      optee.bin optee.capsule
+
+
 Enabling Capsule Authentication
 *******************************
 
diff --git a/doc/mkeficapsule.1 b/doc/mkeficapsule.1
index 8babb27..09bdc24 100644
--- a/doc/mkeficapsule.1
+++ b/doc/mkeficapsule.1
@@ -41,18 +41,6 @@ If you want to use other types than above two, you should explicitly
 specify a guid for the FMP driver.
 
 .SH "OPTIONS"
-One of
-.BR --fit ", " --raw " or " --guid
-option must be specified.
-
-.TP
-.BR -f ", " --fit
-Indicate that the blob is a FIT image file
-
-.TP
-.BR -r ", " --raw
-Indicate that the blob is a raw image file
-
 .TP
 .BI "-g\fR,\fB --guid " guid-string
 Specify guid for image blob type. The format is:
diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst
index 5c4ca35..347bd59 100644
--- a/doc/usage/cmd/askenv.rst
+++ b/doc/usage/cmd/askenv.rst
@@ -16,6 +16,8 @@ Description
 Display message and get environment variable name of max size characters
 from stdin.
 
+See also *env ask* in :doc:`env`.
+
 name
     name of the environment variable
 
diff --git a/doc/usage/cmd/env.rst b/doc/usage/cmd/env.rst
new file mode 100644
index 0000000..1bebfa4
--- /dev/null
+++ b/doc/usage/cmd/env.rst
@@ -0,0 +1,381 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later:
+
+env command
+===========
+
+Synopsis
+--------
+
+::
+
+	env ask name [message] [size]
+	env callbacks
+	env default [-f] (-a | var [...])
+	env delete [-f] var [...]
+	env edit name
+	env exists name
+	env export [-t | -b | -c] [-s size] addr [var ...]
+	env flags
+	env grep [-e] [-n | -v | -b] string [...]
+	env import [-d] [-t [-r] | -b | -c] addr [size] [var ...]
+	env info [-d] [-p] [-q]
+	env print [-a | name ...]
+	env print -e [-guid guid] [-n] [name ...]
+	env run var [...]
+	env save
+	env erase
+	env load
+	env select [target]
+	env set [-f] name [value]
+	env set -e [-nv][-bs][-rt][-at][-a][-i addr:size][-v] name [value]
+
+Description
+-----------
+
+The *env* commands is used to handle the U-Boot (:doc:`../environment`) or
+the UEFI variables.
+
+The next commands are kept as alias and for compatibility:
+
++ *editenv* = *env edit*
++ *grepenv* = *env grep*
++ *setenv* = *env set*
++ *askenv* = *env ask*
++ *run* = *env run*
+
+Ask
+~~~
+
+The *env ask* command asks for the new value of an environment variable
+(alias :doc:`askenv`).
+
+    name
+        name of the environment variable.
+
+    message
+        message to be displayed while the command waits for the value to be
+        entered from stdin. If no message is specified, a default message
+        "Please enter name:" will be displayed.
+
+    size
+        maximum number of characters that will be stored in the environment
+        variable name. This is in decimal number format (unlike in
+        other commands where size values are hexa-decimal). The default
+        value of size is 1023 (CONFIG_SYS_CBSIZE - 1).
+
+Callbacks
+~~~~~~~~~
+
+The *env callbacks* command prints callbacks and their associated variables.
+
+Default
+~~~~~~~
+
+The *env default* command resets the selected variables in the U-Boot
+environment to their default values.
+
+    var
+        list of variable name.
+    \-a
+        all U-Boot environment.
+    \-f
+        forcibly, overwrite read-only/write-once variables.
+
+Delete
+~~~~~~
+
+The *env delete* command deletes the selected variables from the U-Boot
+environment.
+
+    var
+        name of the variable to delete.
+    \-f
+        forcibly, overwrite read-only/write-once variables.
+
+Edit
+~~~~
+
+The *env edit* command edits an environment variable.
+
+    name
+        name of the variable.
+
+Exists
+~~~~~~
+
+The *env exists* command tests for existence of variable.
+
+    name
+        name of the variable.
+
+Export
+~~~~~~
+
+The *env export* command exports the U-Boot environment in memory; on success,
+the variable $filesize will be set.
+
+    addr
+        memory address where environment gets stored.
+    var
+        list of variable names that get included into the export.
+        Without arguments, the whole environment gets exported.
+    \-b
+        export as binary format (name=value pairs separated by
+        list end marked by double "\0\0").
+    \-t
+        export as text format; if size is given, data will be
+        padded with '\0' bytes; if not, one terminating '\0'
+        will be added.
+    \-c
+        Export as checksum protected environment format as used by
+        'env save' command.
+    \-s size
+        size of output buffer.
+
+Flags
+~~~~~
+
+The *env flags* command prints variables that have non-default flags.
+
+Grep
+~~~~
+
+The *env grep* command searches environment, list environment name=value pairs
+matching the requested 'string'.
+
+    string
+        string to search in U-Boot environment.
+    \-e
+        enable regular expressions.
+    \-n
+        search string in variable names.
+    \-v
+        search string in vairable values.
+    \-b
+        search both names and values (default).
+
+Import
+~~~~~~
+
+The *env import* command imports environment from memory.
+
+    addr
+        memory address to read from.
+    size
+        length of input data; if missing, proper '\0' termination is mandatory
+        if var is set and size should be missing (i.e. '\0' termination),
+        set size to '-'.
+    var
+        List of the names of the only variables that get imported from
+        the environment at address 'addr'. Without arguments, the whole
+        environment gets imported.
+    \-d
+        delete existing environment before importing if no var is passed;
+        if vars are passed, if one var is in the current environment but not
+        in the environment at addr, delete var from current environment;
+        otherwise overwrite / append to existing definitions.
+    \-t
+        assume text format; either "size" must be given or the text data must
+        be '\0' terminated.
+    \-r
+        handle CRLF like LF, that means exported variables with a content which
+        ends with \r won't get imported. Used to import text files created with
+        editors which are using CRLF for line endings.
+        Only effective in addition to -t.
+    \-b
+        assume binary format ('\0' separated, "\0\0" terminated).
+    \-c
+        assume checksum protected environment format.
+
+Info
+~~~~
+
+The *env info* command displays (without argument) or evaluates the U-Boot
+environment information.
+
+    \-d
+        evaluate if the default environment is used.
+    \-p
+        evaluate if environment can be persisted.
+    \-q
+        quiet output,  use only for command result, by example with
+        'test' command.
+
+Print
+~~~~~
+
+The *env print* command prints the selected variables in U-Boot environment or
+in UEFI variables.
+
+    name
+        list of variable name.
+    \-a
+        all U-Boot environment, when 'name' is absent.
+    \-e
+        print UEFI variables, all by default when 'name'.
+    \-guid guid
+        print only the UEFI variables matching this GUID (any by default)
+        with guid format = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".
+    \-n
+         suppress dumping variable's value for UEFI.
+
+Run
+~~~
+
+The *env run* command runs commands in an environment variable.
+
+    var
+        name of the variable.
+
+Save
+~~~~
+
+The *env save* command saves the U-Boot environment in persistent storage.
+
+Erase
+~~~~~
+
+The *env erase* command erases the U-Boot environment.
+
+Load
+~~~~
+
+The *env load* command loads the U-Boot environment from persistent storage.
+
+Select
+~~~~~~
+
+The *env select* command selects an U-Boot environment target, it is useful to
+overid the default location when several U-Boot environment backend are
+availables.
+
+    target
+        name of the U-Boot environment backend to select: EEPROM, EXT4, FAT,
+        Flash, MMC, NAND, nowhere, NVRAM, OneNAND, Remote, SATA, SPIFlash, UBI.
+
+
+Set
+~~~
+
+The *env set* command sets or delete (when 'value' or '-i' are absent)
+U-Boot variable in environment or UEFI variables (when -e is specified).
+
+    name
+        variable name to modify.
+    value
+        when present, set the environment variable 'name' to 'value'
+        when absent, delete the environment variable 'name'.
+    \-f
+        forcibly, overwrite read-only/write-once U-Boot variables.
+    \-e
+        update UEFI variables.
+    \-nv
+        set non-volatile attribute (UEFI).
+    \-bs
+        set boot-service attribute (UEFI).
+    \-rt
+        set runtime attribute (UEFI).
+    \-at
+        set time-based authentication attribute (UEFI).
+    \-a
+        append-write (UEFI).
+    \-i addr:size
+        use <addr,size> as variable's value (UEFI).
+    \-v
+        verbose message (UEFI).
+
+Example
+-------
+
+Print the U-Boot environment variables::
+
+    => env print -a
+    => env print bootcmd stdout
+
+Update environment variable in memory::
+
+    => env set bootcmd "run distro_bootcmd"
+    => env set stdout "serial,vidconsole"
+
+Delete environment variable in memory::
+
+    => env delete bootcmd
+    => env set bootcmd
+
+Reset environment variable to default value, in memory::
+
+    => env default bootcmd
+    => env default -a
+
+Save current environment in persistent storage::
+
+    => env save
+
+Restore the default environment in persistent storage::
+
+    => env erase
+
+Create a text snapshot/backup of the current settings in RAM
+(${filesize} can be use to save the snapshot in file)::
+
+    => env export -t ${backup_addr}
+
+Re-import this snapshot, deleting all other settings::
+
+    => env import -d -t ${backup_addr}
+
+Save environment if default enviromnent is used and persistent storage is
+selected::
+
+    => if env info -p -d -q; then env save; fi
+
+Configuration
+-------------
+
+The env command is always available but some sub-commands depend on
+configuration options:
+
+ask
+    CONFIG_CMD_ASKENV
+
+callback
+    CONFIG_CMD_ENV_CALLBACK
+
+edit
+    CONFIG_CMD_EDITENV
+
+exists
+    CONFIG_CMD_ENV_EXISTS
+
+flsgs
+    CONFIG_CMD_ENV_FLAGS
+
+erase
+    CONFIG_CMD_ERASEENV
+
+export
+    CONFIG_CMD_EXPORTENV
+
+grep
+    CONFIG_CMD_GREPENV, CONFIG_REGEX for '-e' option
+
+import
+    CONFIG_CMD_IMPORTENV
+
+info
+    CONFIG_CMD_NVEDIT_INFO
+
+load
+    CONFIG_CMD_NVEDIT_LOAD
+
+run
+    CONFIG_CMD_RUN
+
+save
+    CONFIG_CMD_SAVEENV
+
+select
+    CONFIG_CMD_NVEDIT_SELECT
+
+set, print
+    CONFIG_CMD_NVEDIT_EFI for '-e' option
diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst
index 88f18c9..58240c5 100644
--- a/doc/usage/cmdline.rst
+++ b/doc/usage/cmdline.rst
@@ -14,7 +14,7 @@ Simple command-line parser
 
 This takes very little code space and offers only basic features:
 
-- supports environment variables (through setenv / saveenv commands)
+- supports environment variables (through :doc:`cmd/env`)
 - several commands on one line, separated by ';'
 - variable substitution using "... ${name} ..." syntax
 - special characters ('$', ';') can be escaped by prefixing with '\',
diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
index 80550fc..dc61703 100644
--- a/doc/usage/environment.rst
+++ b/doc/usage/environment.rst
@@ -15,6 +15,8 @@ environment. As long as you don't save the environment, you are
 working with an in-memory copy. In case the Flash area containing the
 environment is erased by accident, a default environment is provided.
 
+See :doc:`cmd/env` for details.
+
 Some configuration is controlled by Environment Variables, so that setting the
 variable can adjust the behaviour of U-Boot (e.g. autoboot delay, autoloading
 from tftp).
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index f457bff..f343e4e 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -30,6 +30,7 @@ Shell commands
    cmd/cbsysinfo
    cmd/conitrace
    cmd/echo
+   cmd/env
    cmd/event
    cmd/exception
    cmd/extension