Merge tag 'efi-2023-07-rc1' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request for efi-2023-07-rc1

Documentation:

* man-page for coninfo command
* documentation style
* switch settings for boot modes on AM62 SK

UEFI:

* avoid using deprecated HandleProtocol()
* set static attribute for non-exported functions and variables

cmd/console.c

@@ -9,6 +9,7 @@
  */
 #include <common.h>
 #include <command.h>
+#include <iomux.h>
 #include <stdio_dev.h>
 
 extern void _do_coninfo (void);
@@ -33,9 +34,15 @@ static int do_coninfo(struct cmd_tbl *cmd, int flag, int argc,
 		       (dev->flags & DEV_FLAGS_OUTPUT) ? "O" : "");
 
 		for (l = 0; l < MAX_FILES; l++) {
-			if (stdio_devices[l] == dev) {
+			if (CONFIG_IS_ENABLED(CONSOLE_MUX)) {
+				if (iomux_match_device(console_devices[l],
+						       cd_count[l], dev) >= 0)
+					printf("|   |-- %s\n", stdio_names[l]);
+			} else {
+				if (stdio_devices[l] == dev)
 					printf("|   |-- %s\n", stdio_names[l]);
 			}
+
 		}
 	}
 	return 0;

doc/board/ti/am62x_sk.rst

@@ -229,3 +229,28 @@ Image formats:
                 | |   SPL DTB 1...N   | |
                 | +-------------------+ |
                 +-----------------------+
+
+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 AM62 platform. More
+details can be found in the Technical Reference Manual:
+https://www.ti.com/lit/pdf/spruiv7 under the `Boot Mode Pins` section.
+
+*Boot Modes*
+
+============ ============= =============
+Switch Label SW2: 12345678 SW3: 12345678
+============ ============= =============
+SD           01000000      11000010
+OSPI         00000000      11001110
+EMMC         00000000      11010010
+UART         00000000      11011100
+USB DFU      00000000      11001010
+============ ============= =============
+
+For SW2 and SW1, the switch state in the "ON" position = 1.

doc/build/documentation.rst

@@ -26,6 +26,9 @@ The *htmldocs* target is used to build the HTML documentation. It uses the
     # Display the documentation in a graphical web browser
     x-www-browser doc/output/index.html
 
+The HTML documentation is published at https://u-boot.readthedocs.io. The build
+process for that site is controlled by the file *.readthedocs.yml*.
+
 Infodoc documentation
 ---------------------
 

doc/develop/docstyle.rst

@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Documentation Style
+===================
+
+Documentation is crucial for the U-Boot project. It has to encompass the needs
+of different reader groups from first time users to developers and maintainers.
+This requires different types of documentation like tutorials, how-to-guides,
+explanatory texts, and reference.
+
+We want to be able to generate documentation in different target formats. We
+therefore use `Sphinx <https://www.sphinx-doc.org>`_ for the generation of
+documents from reStructured text.
+
+We apply the following rules:
+
+* Documentation files are located in *doc/* or its sub-directories.
+* Each documentation file is added to an index page to allow navigation
+  to the document.
+* For documentation we use reStructured text conforming to the requirements
+  of `Sphinx <https://www.sphinx-doc.org>`_.
+* For documentation within code we follow the Linux kernel guide
+  `Writing kernel-doc comments <https://docs.kernel.org/doc-guide/kernel-doc.html>`_.
+* We try to stick to 80 columns per line in documents.
+* For tables we prefer simple tables over grid tables. We avoid list tables
+  as they make the reStructured text documents hard to read.
+* Before submitting documentation patches we build the HTML documentation and
+  fix all warnings. The build process is described in
+  :doc:`/build/documentation`.

doc/develop/index.rst

@@ -11,6 +11,7 @@ General
 
    codingstyle
    designprinciples
+   docstyle
    patman
    process
    release_cycle

doc/usage/cmd/coninfo.rst

@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+coninfo command
+===============
+
+Synopsis
+--------
+
+::
+
+    coninfo
+
+Description
+-----------
+
+The coninfo command provides a list of available console input and output
+devices and their assignment as stdin, stdout, stderr console devices.
+
+If CONFIG_SYS_CONSOLE_IS_IN_ENV=y, the assignment is controlled by the
+environment variables stdin, stdout, stderr which contain a comma separated
+list of device names.
+
+Example
+--------
+
+.. code-block:: console
+
+    => coninfo
+    List of available devices
+    |-- pl011@9000000 (IO)
+    |   |-- stdin
+    |   |-- stdout
+    |   |-- stderr
+    |-- serial (IO)
+    |-- usbkbd (I)
+    => setenv stdin pl011@9000000,usbkbd
+    => coninfo
+    List of available devices
+    |-- pl011@9000000 (IO)
+    |   |-- stdin
+    |   |-- stdout
+    |   |-- stderr
+    |-- serial (IO)
+    |-- usbkbd (I)
+    |   |-- stdin
+
+Configuration
+-------------
+
+The coninfo command is only available if CONFIG_CMD_CONSOLE=y.
+
+Return value
+------------
+
+The return value $? is always 0 (true).

doc/usage/index.rst

@@ -39,6 +39,7 @@ Shell commands
    cmd/cbsysinfo
    cmd/cls
    cmd/cmp
+   cmd/coninfo
    cmd/conitrace
    cmd/cyclic
    cmd/dm

include/efi_loader.h

@@ -513,9 +513,6 @@ struct efi_register_notify_event {
 	struct list_head handles;
 };
 
-/* List of all events registered by RegisterProtocolNotify() */
-extern struct list_head efi_register_notify_events;
-
 /* called at pre-initialization */
 int efi_init_early(void);
 /* Initialize efi execution environment */

lib/efi_loader/efi_boottime.c

@@ -35,7 +35,7 @@ LIST_HEAD(efi_obj_list);
 __efi_runtime_data LIST_HEAD(efi_events);
 
 /* List of queued events */
-LIST_HEAD(efi_event_queue);
+static LIST_HEAD(efi_event_queue);
 
 /* Flag to disable timer activity in ExitBootServices() */
 static bool timers_enabled = true;
@@ -44,7 +44,7 @@ static bool timers_enabled = true;
 bool efi_st_keep_devices;
 
 /* List of all events registered by RegisterProtocolNotify() */
-LIST_HEAD(efi_register_notify_events);
+static LIST_HEAD(efi_register_notify_events);
 
 /* Handle of the currently executing image */
 static efi_handle_t current_image;

lib/efi_loader/efi_memory.c

@@ -36,7 +36,7 @@ struct efi_mem_list {
 #define EFI_CARVE_OVERLAPS_NONRAM	-3
 
 /* This list contains all memory map items */
-LIST_HEAD(efi_mem);
+static LIST_HEAD(efi_mem);
 
 #ifdef CONFIG_EFI_LOADER_BOUNCE_BUFFER
 void *efi_bounce_buffer;

lib/efi_loader/efi_runtime.c

@@ -32,7 +32,7 @@ struct efi_runtime_mmio_list {
 };
 
 /* This list contains all runtime available mmio regions */
-LIST_HEAD(efi_runtime_mmio);
+static LIST_HEAD(efi_runtime_mmio);
 
 static efi_status_t __efi_runtime EFIAPI efi_unimplemented(void);
 

lib/efi_loader/helloworld.c

@@ -197,8 +197,10 @@ efi_status_t EFIAPI efi_main(efi_handle_t handle,
 	print_config_tables();
 
 	/* Get the loaded image protocol */
-	ret = boottime->handle_protocol(handle, &loaded_image_guid,
+	ret = boottime->open_protocol(handle, &loaded_image_guid,
-					(void **)&loaded_image);
+				      (void **)&loaded_image, NULL, NULL,
+				      EFI_OPEN_PROTOCOL_GET_PROTOCOL);
+
 	if (ret != EFI_SUCCESS) {
 		con_out->output_string
 			(con_out, u"Cannot open loaded image protocol\r\n");
@@ -219,9 +221,10 @@ efi_status_t EFIAPI efi_main(efi_handle_t handle,
 			(con_out, u"Missing device handle\r\n");
 		goto out;
 	}
-	ret = boottime->handle_protocol(loaded_image->device_handle,
+	ret = boottime->open_protocol(loaded_image->device_handle,
 				      &device_path_guid,
-					(void **)&device_path);
+				      (void **)&device_path, NULL, NULL,
+				      EFI_OPEN_PROTOCOL_GET_PROTOCOL);
 	if (ret != EFI_SUCCESS) {
 		con_out->output_string
 			(con_out, u"Missing device path for device handle\r\n");

lib/efi_loader/initrddump.c

@@ -291,8 +291,9 @@ static efi_status_t get_initrd(void **initrd, efi_uintn_t *initrd_size)
 		error(u"Load File2 protocol not found\r\n");
 		return ret;
 	}
-	ret = bs->handle_protocol(handle, &load_file2_guid,
+	ret = bs->open_protocol(handle, &load_file2_guid,
-				 (void **)&load_file2_prot);
+				(void **)&load_file2_prot, NULL, NULL,
+				EFI_OPEN_PROTOCOL_GET_PROTOCOL);
 	ret = load_file2_prot->load_file(load_file2_prot, dp, false,
 					 initrd_size, NULL);
 	if (ret != EFI_BUFFER_TOO_SMALL) {

lib/efi_selftest/efi_selftest_exitbootservices.c

@@ -27,7 +27,7 @@ struct notification_context {
 
 static struct efi_boot_services *boottime;
 static struct efi_event *efi_st_event_notify;
-struct notification_record record;
+static struct notification_record record;
 
 struct notification_context context_before = {
 	.record = &record,

lib/efi_selftest/efi_selftest_load_file.c

@@ -206,7 +206,7 @@ static efi_status_t decompress(u8 **image)
  * @buffer_size:	(required) buffer size
  * @buffer:		buffer to which the file is to be loaded
  */
-efi_status_t EFIAPI load_file(struct efi_load_file_protocol *this,
+static efi_status_t EFIAPI load_file(struct efi_load_file_protocol *this,
 				     struct efi_device_path *file_path,
 				     bool boot_policy,
 				     efi_uintn_t *buffer_size,
@@ -243,7 +243,7 @@ efi_status_t EFIAPI load_file(struct efi_load_file_protocol *this,
  * @buffer_size:	(required) buffer size
  * @buffer:		buffer to which the file is to be loaded
  */
-efi_status_t EFIAPI load_file2(struct efi_load_file_protocol *this,
+static efi_status_t EFIAPI load_file2(struct efi_load_file_protocol *this,
 				      struct efi_device_path *file_path,
 				      bool boot_policy,
 				      efi_uintn_t *buffer_size,