efi: doc: Add documentation for efidebug command in the app

Mention the efidebug command specifically the EFI-app documentaion, to
highlight its usefulness.

Series-to: concept
Series-cc: heinrich
Cover-letter:
efi: Move towards the EFI app booting EFI applications
This series adds various new features to the EFI app, mostly by moving
code over from the EFI loader implementation.

In particular it adds support for the efidebug command (with only a
subset of subcommands so far).

The main approach is to make use of the system table (for both the app
and the loader) instead of directly calling EFI-loader code.

It also includes a few fixes, which likely have no effect but will help
to avoid confusion in future.
END

Signed-off-by: Simon Glass <sjg@chromium.org>

cmd/Kconfig

@@ -2228,8 +2228,9 @@ config CMD_CLS
 
 config CMD_EFIDEBUG
 	bool "efidebug - display/configure UEFI environment"
-	depends on EFI_LOADER
-	select EFI_DEVICE_PATH_TO_TEXT
+	depends on EFI_LOADER || EFI_APP
+	default y if EFI_APP
+	select EFI_DEVICE_PATH_TO_TEXT if EFI_LOADER
 	help
 	  Enable the 'efidebug' command which provides a subset of UEFI
 	  shell utility with simplified functionality. It will be useful

cmd/efidebug.c

@@ -28,6 +28,16 @@
 
 #define BS systab.boottime
 
+static bool app_not_supported(const char *cmd)
+{
+	if (!IS_ENABLED(CONFIG_EFI_APP))
+		return false;
+
+	printf("Command '%s' is not yet supported in the app\n", cmd);
+
+	return true;
+}
+
 #ifdef CONFIG_EFI_HAVE_CAPSULE_SUPPORT
 /**
  * do_efi_capsule_update() - process a capsule update
@@ -405,6 +415,9 @@ static int do_efi_show_drivers(struct cmd_tbl *cmdtp, int flag,
 	u16 *driver_name, *image_path_text;
 	efi_status_t ret;
 
+	if (app_not_supported("show_drivers"))
+		return CMD_RET_FAILURE;
+
 	ret = EFI_CALL(efi_locate_handle_buffer(
 				BY_PROTOCOL, &efi_guid_driver_binding_protocol,
 				NULL, &num, &handles));
@@ -458,6 +471,9 @@ static int do_efi_show_handles(struct cmd_tbl *cmdtp, int flag,
 	efi_uintn_t num, count, i, j;
 	efi_status_t ret;
 
+	if (app_not_supported("show_handles"))
+		return CMD_RET_FAILURE;
+
 	ret = EFI_CALL(efi_locate_handle_buffer(ALL_HANDLES, NULL, NULL,
 						&num, &handles));
 	if (ret != EFI_SUCCESS)
@@ -643,12 +659,24 @@ static int do_efi_show_memmap(struct cmd_tbl *cmdtp, int flag,
 	struct efi_mem_desc *memmap, *map;
 	efi_uintn_t map_size;
 	const char *type;
-	int i;
-	efi_status_t ret;
+	int desc_size, i;
+	efi_status_t eret;
+	int ret;
 
-	ret = efi_get_memory_map_alloc(&map_size, &memmap);
-	if (ret != EFI_SUCCESS)
-		return CMD_RET_FAILURE;
+	if (IS_ENABLED(CONFIG_EFI_APP)) {
+		uint key, version;
+		int size;
+
+		ret = efi_get_mmap(&memmap, &size, &key, &desc_size, &version);
+		if (ret)
+			return CMD_RET_FAILURE;
+		map_size = size;
+	} else {
+		eret = efi_get_memory_map_alloc(&map_size, &memmap);
+		if (eret)
+			return CMD_RET_FAILURE;
+		desc_size = sizeof(*map);
+	}
 
 	printf("Type             Start%.*s End%.*s Attributes\n",
 	       EFI_PHYS_ADDR_WIDTH - 5, spc, EFI_PHYS_ADDR_WIDTH - 3, spc);
@@ -659,7 +687,8 @@ static int do_efi_show_memmap(struct cmd_tbl *cmdtp, int flag,
 	 * This is a false positive as memmap will always be
 	 * populated by allocate_pool() above.
 	 */
-	for (i = 0, map = memmap; i < map_size / sizeof(*map); map++, i++) {
+	for (i = 0, map = memmap; i < map_size / desc_size;
+	     map = (void *)map + desc_size, i++) {
 		if (map->type < ARRAY_SIZE(efi_mem_type_string))
 			type = efi_mem_type_string[map->type];
 		else
@@ -698,7 +727,7 @@ static int do_efi_show_memmap(struct cmd_tbl *cmdtp, int flag,
 static int do_efi_show_tables(struct cmd_tbl *cmdtp, int flag,
 			      int argc, char *const argv[])
 {
-	efi_show_tables(&systab);
+	efi_show_tables(efi_get_sys_table());
 
 	return CMD_RET_SUCCESS;
 }

doc/develop/uefi/u-boot_on_efi.rst

@@ -143,6 +143,27 @@ enough) should be straightforward.
 
 Use the 'reset' command to get back to EFI.
 
+EFI Debugging Commands
+~~~~~~~~~~~~~~~~~~~~~~
+When running as an EFI application, U-Boot provides access to the 'efidebug'
+command, which offers a subset of functionality useful for debugging and
+inspecting the UEFI environment. This command allows you to:
+
+* Display memory maps with 'efidebug memmap'
+* Show EFI system tables with 'efidebug show tables'
+* Manage boot options with 'efidebug boot' subcommands:
+
+  - dump - Display current boot options
+  - add - Add new boot options
+  - rm - Remove boot options
+  - order - Display boot order
+
+This command  uses the EFI system table and runtime services to provide this
+functionality, so it can help with understanding and debugging UEFI
+environments.
+
+See the :doc:`/usage/cmd/efidebug` for more information.
+
 EFI Payload
 ~~~~~~~~~~~
 The payload approach is a different kettle of fish. It works by building

include/efi.h

@@ -152,6 +152,9 @@ typedef struct efi_object *efi_handle_t;
 		(c) & 0xff, ((c) >> 8) & 0xff, \
 		(d0), (d1), (d2), (d3), (d4), (d5), (d6), (d7) } }
 
+extern const efi_guid_t efi_global_variable_guid;
+extern const efi_guid_t efi_guid_fdt;
+
 /* Generic EFI table header */
 struct efi_table_hdr {
 	u64 signature;
@@ -468,6 +471,7 @@ static inline struct efi_mem_desc *efi_get_next_mem_desc(
  *	allocate_pages() and free_pages()
  * @ram_base: Base address of RAM (size CONFIG_EFI_RAM_SIZE)
  * @image_data_type: Type of the loaded image (e.g. EFI_LOADER_CODE)
+ * @efi_dp_to_text: Pointer to the EFI_DEVICE_PATH protocol, or NULL if none
  *
  * @info: Header of the info list, holding info collected by the stub and passed
  *	to U-Boot
@@ -493,6 +497,7 @@ struct efi_priv {
 	bool use_pool_for_malloc;
 	unsigned long ram_base;
 	unsigned int image_data_type;
+	struct efi_device_path_to_text_protocol *efi_dp_to_text;
 
 	/* stub: */
 	struct efi_info_hdr *info;
@@ -604,6 +609,13 @@ struct efi_system_table *efi_get_sys_table(void);
  */
 struct efi_boot_services *efi_get_boot(void);
 
+/**
+ * efi_get_run() - Get access to the EFI runtime-services table
+ *
+ * Returns: pointer to EFI runtime-services table
+ */
+struct efi_runtime_services *efi_get_run(void);
+
 /**
  * efi_get_parent_image() - Get the handle of the parent image
  *
@@ -650,6 +662,14 @@ void *efi_malloc(struct efi_priv *priv, int size, efi_status_t *retp);
  */
 void efi_free(struct efi_priv *priv, void *ptr);
 
+/**
+ * efi_free_pool() - free memory from pool
+ *
+ * @buffer:	start of memory to be freed
+ * Return:	status code
+ */
+efi_status_t efi_free_pool(void *buffer);
+
 /**
  * efi_puts() - Write out a string to the EFI console
  *

include/efi_loader.h

@@ -317,7 +317,6 @@ extern const efi_guid_t efi_guid_host_dev;
 extern const efi_guid_t efi_block_io_guid;
 /* GUID of the EFI_SIMPLE_NETWORK_PROTOCOL */
 extern const efi_guid_t efi_net_guid;
-extern const efi_guid_t efi_global_variable_guid;
 extern const efi_guid_t efi_guid_console_control;
 extern const efi_guid_t efi_guid_device_path;
 /* GUID of the EFI system partition */
@@ -336,8 +335,6 @@ extern const efi_guid_t efi_guid_event_group_ready_to_boot;
 extern const efi_guid_t efi_guid_event_group_reset_system;
 /* event group return to efibootmgr */
 extern const efi_guid_t efi_guid_event_group_return_to_efibootmgr;
-/* GUID of the device tree table */
-extern const efi_guid_t efi_guid_fdt;
 extern const efi_guid_t efi_guid_loaded_image;
 extern const efi_guid_t efi_guid_loaded_image_device_path;
 extern const efi_guid_t efi_guid_device_path_to_text_protocol;
@@ -894,14 +891,6 @@ efi_status_t efi_free_pages(uint64_t memory, efi_uintn_t pages);
 efi_status_t efi_allocate_pool(enum efi_memory_type pool_type,
 			       efi_uintn_t size, void **buffer);
 
-/**
- * efi_free_pool() - free memory from pool
- *
- * @buffer:	start of memory to be freed
- * Return:	status code
- */
-efi_status_t efi_free_pool(void *buffer);
-
 /* Allocate and retrieve EFI memory map */
 efi_status_t efi_get_memory_map_alloc(efi_uintn_t *map_size,
 				      struct efi_mem_desc **memory_map);

lib/efi/Kconfig

@@ -11,12 +11,22 @@ config EFI
 
 	  This is used to provide libraries shared by both.
 
+if EFI_LOADER
+
 config EFI_BINARY_EXEC
 	bool "Execute UEFI binary"
 	default y
-	depends on EFI_LOADER
 	help
 	  Select this option if you want to execute the UEFI binary after
 	  loading it with U-Boot load commands or other methods.
 	  You may enable CMD_BOOTEFI_BINARY so that you can use bootefi
 	  command to do that.
+
+config EFI_DEVICE_PATH_TO_TEXT
+	bool "Device path to text protocol"
+	default y
+	help
+	  The device path to text protocol converts device nodes and paths to
+	  human readable strings.
+
+endif # EFI_LOADER

lib/efi/Makefile

@@ -5,5 +5,8 @@
 
 obj-y += basename.o
 obj-y += device_path.o
+obj-y += helper.o
+obj-y += load_options.o
 obj-y += memory.o
 obj-y += run.o
+obj-y += string.o

lib/efi/device_path.c

@@ -32,6 +32,8 @@ const efi_guid_t efi_simple_file_system_protocol_guid =
 		EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_GUID;
 const efi_guid_t efi_file_info_guid = EFI_FILE_INFO_GUID;
 const efi_guid_t efi_u_boot_guid = U_BOOT_GUID;
+/* GUID of the device tree table */
+const efi_guid_t efi_guid_fdt = EFI_FDT_GUID;
 
 /* template EFI_DP_END node: */
 const struct efi_device_path EFI_DP_END = {
@@ -328,7 +330,7 @@ bool efi_dp_is_multi_instance(const struct efi_device_path *dp)
 
 __maybe_unused static unsigned int dp_size(struct udevice *dev)
 {
-	uint parent_size, size;
+	uint parent_size, size = 0;
 
 	if (!dev || !dev->driver)
 		return sizeof(struct efi_device_path_udevice);
@@ -374,6 +376,7 @@ __maybe_unused static unsigned int dp_size(struct udevice *dev)
 			size = sizeof(struct efi_device_path_udevice);
 			break;
 		}
+		break;
 	case UCLASS_MMC:
 		if (IS_ENABLED(CONFIG_MMC))
 			size = sizeof(struct efi_device_path_sd_mmc_path);
@@ -528,6 +531,7 @@ __maybe_unused static void *dp_fill(void *buf, struct udevice *dev)
 
 			return &dp[1];
 		}
+		break;
 	}
 	case UCLASS_MMC:
 	if (IS_ENABLED(CONFIG_MMC)) {
@@ -739,12 +743,14 @@ static void path_to_uefi(void *uefi, const char *src)
 {
 	u16 *pos = uefi;
 
-	/*
-	 * efi_set_bootdev() calls this routine indirectly before the UEFI
-	 * subsystem is initialized. So we cannot assume unaligned access to be
-	 * enabled.
-	 */
-	allow_unaligned();
+	if (!IS_ENABLED(CONFIG_EFI_APP)) {
+		/*
+		 * efi_set_bootdev() calls this routine indirectly before the
+		 * UEFI subsystem is initialized. So we cannot assume unaligned
+		 * access to be enabled.
+		 */
+		allow_unaligned();
+	}
 
 	while (*src) {
 		s32 code = utf8_get(&src);

lib/efi/helper.c

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: GPL-2.0+
+/*
+ * Copyright (c) 2020, Linaro Limited
+ */
+
+#define LOG_CATEGORY LOGC_EFI
+
+#include <efi.h>
+#include <efi_device_path.h>
+#include <string.h>
+#include <linux/types.h>
+
+static int u16_tohex(u16 c)
+{
+	if (c >= '0' && c <= '9')
+		return c - '0';
+	if (c >= 'A' && c <= 'F')
+		return c - 'A' + 10;
+
+	/* not hexadecimal */
+	return -1;
+}
+
+bool efi_varname_is_load_option(u16 *var_name16, int *index)
+{
+	int id, i, digit;
+
+	if (memcmp(var_name16, u"Boot", 8))
+		return false;
+
+	for (id = 0, i = 0; i < 4; i++) {
+		digit = u16_tohex(var_name16[4 + i]);
+		if (digit < 0)
+			break;
+		id = (id << 4) + digit;
+	}
+	if (i == 4 && !var_name16[8]) {
+		if (index)
+			*index = id;
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * efi_load_option_dp_join() - join device-paths for load option
+ *
+ * @dp:		in: binary device-path, out: joined device-path
+ * @dp_size:	size of joined device-path
+ * @initrd_dp:	initrd device-path or NULL
+ * @fdt_dp:	device-tree device-path or NULL
+ * Return:	status_code
+ */
+efi_status_t efi_load_option_dp_join(struct efi_device_path **dp,
+				     size_t *dp_size,
+				     struct efi_device_path *initrd_dp,
+				     struct efi_device_path *fdt_dp)
+{
+	if (!dp)
+		return EFI_INVALID_PARAMETER;
+
+	*dp_size = efi_dp_size(*dp);
+
+	if (initrd_dp) {
+		struct efi_device_path *tmp_dp = *dp;
+
+		*dp = efi_dp_concat(tmp_dp, initrd_dp, *dp_size);
+		efi_free_pool(tmp_dp);
+		if (!*dp)
+			return EFI_OUT_OF_RESOURCES;
+		*dp_size += efi_dp_size(initrd_dp) + sizeof(EFI_DP_END);
+	}
+
+	if (fdt_dp) {
+		struct efi_device_path *tmp_dp = *dp;
+
+		*dp = efi_dp_concat(tmp_dp, fdt_dp, *dp_size);
+		efi_free_pool(tmp_dp);
+		if (!*dp)
+			return EFI_OUT_OF_RESOURCES;
+		*dp_size += efi_dp_size(fdt_dp) + sizeof(EFI_DP_END);
+	}
+
+	*dp_size += sizeof(EFI_DP_END);
+
+	return EFI_SUCCESS;
+}

lib/efi_client/efi.c

@@ -65,6 +65,11 @@ struct efi_boot_services *efi_get_boot(void)
 	return global_priv->boot;
 }
 
+struct efi_runtime_services *efi_get_run(void)
+{
+	return global_priv->run;
+}
+
 efi_handle_t efi_get_parent_image(void)
 {
 	return global_priv->parent_image;
@@ -185,9 +190,26 @@ void *efi_alloc(size_t size)
 	return efi_malloc(priv, size, &ret);
 }
 
-void efi_free_pool(void *ptr)
+efi_status_t efi_free_pool(void *ptr)
 {
 	struct efi_priv *priv = efi_get_priv();
 
 	efi_free(priv, ptr);
+
+	return 0;
+}
+
+/* helper for debug prints.. efi_free_pool() the result. */
+uint16_t *efi_dp_str(struct efi_device_path *dp)
+{
+	struct efi_priv *priv = efi_get_priv();
+	u16 *val;
+
+	if (!priv->efi_dp_to_text)
+		return NULL;
+
+	val = priv->efi_dp_to_text->convert_device_path_to_text(dp, true,
+								true);
+
+	return val;
 }

lib/efi_client/efi_app.c

@@ -176,6 +176,14 @@ static void scan_tables(struct efi_system_table *sys_table)
 	}
 }
 
+static void find_protocols(struct efi_priv *priv)
+{
+	efi_guid_t guid = EFI_DEVICE_PATH_TO_TEXT_PROTOCOL_GUID;
+	struct efi_boot_services *boot = priv->boot;
+
+	boot->locate_protocol(&guid, NULL, (void **)&priv->efi_dp_to_text);
+}
+
 /**
  * efi_main() - Start an EFI image
  *
@@ -211,6 +219,7 @@ efi_status_t EFIAPI efi_main(efi_handle_t image,
 	}
 
 	scan_tables(priv->sys_table);
+	find_protocols(priv);
 
 	/*
 	 * We could store the EFI memory map here, but it changes all the time,

lib/efi_client/efi_vars.c

@@ -18,8 +18,7 @@ efi_status_t efi_get_variable_int(const u16 *variable_name, const efi_guid_t *ve
 				  u32 *attributes, efi_uintn_t *data_size,
 				  void *data, u64 *timep)
 {
-	struct efi_priv *priv = efi_get_priv();
-	struct efi_runtime_services *run = priv->run;
+	struct efi_runtime_services *run = efi_get_run();
 
 	return run->get_variable((u16 *)variable_name, vendor, attributes, data_size, data);
 }
@@ -28,8 +27,7 @@ efi_status_t efi_set_variable_int(const u16 *variable_name, const efi_guid_t *ve
 				  u32 attributes, efi_uintn_t data_size, const void *data,
 				  bool ro_check)
 {
-	struct efi_priv *priv = efi_get_priv();
-	struct efi_runtime_services *run = priv->run;
+	struct efi_runtime_services *run = efi_get_run();
 
 	return run->set_variable((u16 *)variable_name, vendor, attributes, data_size, data);
 }
@@ -37,8 +35,21 @@ efi_status_t efi_set_variable_int(const u16 *variable_name, const efi_guid_t *ve
 efi_status_t efi_get_next_variable_name_int(efi_uintn_t *variable_name_size,
 					    u16 *variable_name, efi_guid_t *vendor)
 {
-	struct efi_priv *priv = efi_get_priv();
-	struct efi_runtime_services *run = priv->run;
+	struct efi_runtime_services *run = efi_get_run();
 
 	return run->get_next_variable_name(variable_name_size, variable_name, vendor);
 }
+
+efi_status_t efi_query_variable_info_int(u32 attributes,
+					 u64 *maximum_variable_storage_size,
+					 u64 *remaining_variable_storage_size,
+					 u64 *maximum_variable_size)
+{
+	struct efi_runtime_services *run = efi_get_run();
+
+	return run->query_variable_info(attributes,
+					maximum_variable_storage_size,
+					remaining_variable_storage_size,
+					maximum_variable_size);
+}
+

lib/efi_loader/Kconfig

@@ -356,13 +356,6 @@ endmenu
 
 menu "UEFI protocol support"
 
-config EFI_DEVICE_PATH_TO_TEXT
-	bool "Device path to text protocol"
-	default y
-	help
-	  The device path to text protocol converts device nodes and paths to
-	  human readable strings.
-
 config EFI_DEVICE_PATH_UTIL
 	bool "Device path utilities protocol"
 	default y

lib/efi_loader/Makefile

@@ -38,13 +38,11 @@ obj-y += efi_fdt.o
 obj-y += efi_file.o
 obj-$(CONFIG_EFI_LOADER_HII) += efi_hii.o efi_hii_config.o
 obj-y += efi_image_loader.o
-obj-y += efi_load_options.o
 obj-$(CONFIG_EFI_LOG) += efi_log.o
 obj-y += efi_memory.o
 obj-y += efi_root_node.o
 obj-y += efi_runtime.o
 obj-y += efi_setup.o
-obj-y += efi_string.o
 obj-$(CONFIG_EFI_UNICODE_COLLATION_PROTOCOL2) += efi_unicode_collation.o
 obj-y += efi_var_common.o
 obj-y += efi_var_mem.o

lib/efi_loader/efi_boottime.c

@@ -68,8 +68,6 @@ efi_status_t efi_uninstall_protocol
 /* 1 if inside U-Boot code, 0 if inside EFI payload code */
 static int entry_count = 1;
 static int nesting_level;
-/* GUID of the device tree table */
-const efi_guid_t efi_guid_fdt = EFI_FDT_GUID;
 /* GUID of the EFI_DRIVER_BINDING_PROTOCOL */
 const efi_guid_t efi_guid_driver_binding_protocol =
 			EFI_DRIVER_BINDING_PROTOCOL_GUID;
@@ -4026,3 +4024,8 @@ efi_status_t efi_initialize_system_table(void)
 
 	return ret;
 }
+
+struct efi_system_table *efi_get_sys_table(void)
+{
+	return &systab;
+}

lib/efi_loader/efi_helper.c

@@ -99,50 +99,6 @@ err:
 	return file_path;
 }
 
-/**
- * efi_load_option_dp_join() - join device-paths for load option
- *
- * @dp:		in: binary device-path, out: joined device-path
- * @dp_size:	size of joined device-path
- * @initrd_dp:	initrd device-path or NULL
- * @fdt_dp:	device-tree device-path or NULL
- * Return:	status_code
- */
-efi_status_t efi_load_option_dp_join(struct efi_device_path **dp,
-				     size_t *dp_size,
-				     struct efi_device_path *initrd_dp,
-				     struct efi_device_path *fdt_dp)
-{
-	if (!dp)
-		return EFI_INVALID_PARAMETER;
-
-	*dp_size = efi_dp_size(*dp);
-
-	if (initrd_dp) {
-		struct efi_device_path *tmp_dp = *dp;
-
-		*dp = efi_dp_concat(tmp_dp, initrd_dp, *dp_size);
-		efi_free_pool(tmp_dp);
-		if (!*dp)
-			return EFI_OUT_OF_RESOURCES;
-		*dp_size += efi_dp_size(initrd_dp) + sizeof(EFI_DP_END);
-	}
-
-	if (fdt_dp) {
-		struct efi_device_path *tmp_dp = *dp;
-
-		*dp = efi_dp_concat(tmp_dp, fdt_dp, *dp_size);
-		efi_free_pool(tmp_dp);
-		if (!*dp)
-			return EFI_OUT_OF_RESOURCES;
-		*dp_size += efi_dp_size(fdt_dp) + sizeof(EFI_DP_END);
-	}
-
-	*dp_size += sizeof(EFI_DP_END);
-
-	return EFI_SUCCESS;
-}
-
 const struct guid_to_hash_map {
 	efi_guid_t guid;
 	const char algo[32];
@@ -241,39 +197,6 @@ int efi_unlink_dev(efi_handle_t handle)
 	return 0;
 }
 
-static int u16_tohex(u16 c)
-{
-	if (c >= '0' && c <= '9')
-		return c - '0';
-	if (c >= 'A' && c <= 'F')
-		return c - 'A' + 10;
-
-	/* not hexadecimal */
-	return -1;
-}
-
-bool efi_varname_is_load_option(u16 *var_name16, int *index)
-{
-	int id, i, digit;
-
-	if (memcmp(var_name16, u"Boot", 8))
-		return false;
-
-	for (id = 0, i = 0; i < 4; i++) {
-		digit = u16_tohex(var_name16[4 + i]);
-		if (digit < 0)
-			break;
-		id = (id << 4) + digit;
-	}
-	if (i == 4 && !var_name16[8]) {
-		if (index)
-			*index = id;
-		return true;
-	}
-
-	return false;
-}
-
 /**
  * efi_next_variable_name() - get next variable name
  *