From 624faeecec5b0df74791d7eac3f9984673f5b33b Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 7 Apr 2023 11:28:00 +0200 Subject: [PATCH 01/12] doc: describe our documentation style Provide a reference document for the U-Boot documentation style. Signed-off-by: Heinrich Schuchardt Reviewed-by: Tom Rini Reviewed-by: Simon Glass --- doc/develop/docstyle.rst | 29 +++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 30 insertions(+) create mode 100644 doc/develop/docstyle.rst diff --git a/doc/develop/docstyle.rst b/doc/develop/docstyle.rst new file mode 100644 index 00000000000..f9ba83a559c --- /dev/null +++ b/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 `_ 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 `_. +* For documentation within code we follow the Linux kernel guide + `Writing kernel-doc comments `_. +* 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`. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index a52ad630d0d..ddbf8dad4a1 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -11,6 +11,7 @@ General codingstyle designprinciples + docstyle patman process release_cycle From 354c05f265eb42ef90e5411ddad684f752d0587b Mon Sep 17 00:00:00 2001 From: Judith Mendez Date: Fri, 31 Mar 2023 15:36:15 -0500 Subject: [PATCH 02/12] doc: ti: Add switch setting for boot modes on AM62 SK List some common boot modes and their corresponding switch settings for AM62 SK. Signed-off-by: Judith Mendez Reviewed-by: Tom Rini Signed-off-by: Heinrich Schuchardt --- doc/board/ti/am62x_sk.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst index b1b7d99befb..27d7b527c6a 100644 --- a/doc/board/ti/am62x_sk.rst +++ b/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. From dc3e41ec598db6914bd06a0d99555fd10d1acc9e Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 7 Apr 2023 11:17:23 +0200 Subject: [PATCH 03/12] doc: mention usage of .readthedocs.yml Mention that HTML pages are published at https://u-boot.readthedocs.io/ and that the file .readthedocs.yml controls the build process. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/build/documentation.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst index 896264dd7c1..011cd34a57c 100644 --- a/doc/build/documentation.rst +++ b/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 --------------------- From 5eed4a1ed7849bf651e4628538e9dab3a5e91fbc Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 1 Apr 2023 12:33:49 +0200 Subject: [PATCH 04/12] doc: coninfo man-page Provide a man-page for the coninfo command. Signed-off-by: Heinrich Schuchardt --- doc/usage/cmd/coninfo.rst | 55 +++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 2 files changed, 56 insertions(+) create mode 100644 doc/usage/cmd/coninfo.rst diff --git a/doc/usage/cmd/coninfo.rst b/doc/usage/cmd/coninfo.rst new file mode 100644 index 00000000000..f913148c44a --- /dev/null +++ b/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). diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 729541bcff5..cdf710919a2 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -39,6 +39,7 @@ Shell commands cmd/cbsysinfo cmd/cls cmd/cmp + cmd/coninfo cmd/conitrace cmd/cyclic cmd/dm From ff6ce8da978bbcf283e34c07406085af2359f7b0 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Tue, 4 Apr 2023 07:17:48 +0200 Subject: [PATCH 05/12] efi_loader: avoid using HandleProtocol in helloworld.efi HandleProtocol() is deprecated and leaves an OpenedProtocolInformation behind. Use OpenProtocol(GET_PROTOCOL) instead. Signed-off-by: Heinrich Schuchardt Reviewed-by: Ilias Apalodimas --- lib/efi_loader/helloworld.c | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/lib/efi_loader/helloworld.c b/lib/efi_loader/helloworld.c index 49fa8cc2f00..6405f58ec3f 100644 --- a/lib/efi_loader/helloworld.c +++ b/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, - (void **)&loaded_image); + ret = boottime->open_protocol(handle, &loaded_image_guid, + (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, - &device_path_guid, - (void **)&device_path); + ret = boottime->open_protocol(loaded_image->device_handle, + &device_path_guid, + (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"); From 199675b9d54c9be682e98b4835d22da98c0b11e3 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Tue, 4 Apr 2023 07:23:53 +0200 Subject: [PATCH 06/12] efi_loader: avoid using HandleProtocol in initrddump.efi HandleProtocol() is deprecated and leaves an OpenedProtocolInformation behind. Use OpenProtocol(GET_PROTOCOL) instead. Signed-off-by: Heinrich Schuchardt Reviewed-by: Ilias Apalodimas --- lib/efi_loader/initrddump.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/lib/efi_loader/initrddump.c b/lib/efi_loader/initrddump.c index 971a3b6236c..5b470f48194 100644 --- a/lib/efi_loader/initrddump.c +++ b/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, - (void **)&load_file2_prot); + ret = bs->open_protocol(handle, &load_file2_guid, + (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) { From 013f9f89f89045b77c4d1c92ea0875a46916095a Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Wed, 5 Apr 2023 20:15:15 +0800 Subject: [PATCH 07/12] efi: selftest: Make record static record is only referenced in efi_selftest_exitbootservices.c Signed-off-by: Bin Meng --- lib/efi_selftest/efi_selftest_exitbootservices.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/efi_selftest/efi_selftest_exitbootservices.c b/lib/efi_selftest/efi_selftest_exitbootservices.c index 11b43fdd90b..b090ce74d23 100644 --- a/lib/efi_selftest/efi_selftest_exitbootservices.c +++ b/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, From 8063c55e585c9fa17f4ae8faf638564949027871 Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Wed, 5 Apr 2023 20:15:16 +0800 Subject: [PATCH 08/12] efi: selftest: Make load_file() and load_file2() static load_file() and load_file2() are only referenced in efi_selftest_load_file.c Signed-off-by: Bin Meng --- lib/efi_selftest/efi_selftest_load_file.c | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/lib/efi_selftest/efi_selftest_load_file.c b/lib/efi_selftest/efi_selftest_load_file.c index 8784a761721..14df7611727 100644 --- a/lib/efi_selftest/efi_selftest_load_file.c +++ b/lib/efi_selftest/efi_selftest_load_file.c @@ -206,11 +206,11 @@ 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, - struct efi_device_path *file_path, - bool boot_policy, - efi_uintn_t *buffer_size, - void *buffer) +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, + void *buffer) { ++load_file_call_count; if (memcmp(file_path, dp_lf_file_remainder, @@ -243,11 +243,11 @@ 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, - struct efi_device_path *file_path, - bool boot_policy, - efi_uintn_t *buffer_size, - void *buffer) +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, + void *buffer) { ++load_file2_call_count; if (memcmp(file_path, dp_lf2_file_remainder, From ee23830b6ed20827c24e3ef775e6c75948a61b94 Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Wed, 5 Apr 2023 20:15:17 +0800 Subject: [PATCH 09/12] efi: loader: Make efi_event_queue and efi_register_notify_events static efi_event_queue and efi_register_notify_events are only referenced in efi_boottime.c Signed-off-by: Bin Meng --- include/efi_loader.h | 3 --- lib/efi_loader/efi_boottime.c | 4 ++-- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/include/efi_loader.h b/include/efi_loader.h index 4b89b9816d4..b395eef9e79 100644 --- a/include/efi_loader.h +++ b/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 */ diff --git a/lib/efi_loader/efi_boottime.c b/lib/efi_loader/efi_boottime.c index caaab685ee0..d5065f296ae 100644 --- a/lib/efi_loader/efi_boottime.c +++ b/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; From 207b686421563c574eb1179efd4fa7eedddfab5f Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Wed, 5 Apr 2023 20:15:18 +0800 Subject: [PATCH 10/12] efi: loader: Make efi_mem static efi_mem is only referenced in efi_memory.c Signed-off-by: Bin Meng --- lib/efi_loader/efi_memory.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/efi_loader/efi_memory.c b/lib/efi_loader/efi_memory.c index 8f82496740f..e2ca78d935f 100644 --- a/lib/efi_loader/efi_memory.c +++ b/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; From 6fc4fc38ac4d11ac53b4d539588d216d107f7703 Mon Sep 17 00:00:00 2001 From: Bin Meng Date: Wed, 5 Apr 2023 20:15:19 +0800 Subject: [PATCH 11/12] efi: loader: Make efi_runtime_mmio static efi_runtime_mmio is only referenced in efi_boottime.c Signed-off-by: Bin Meng --- lib/efi_loader/efi_runtime.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/efi_loader/efi_runtime.c b/lib/efi_loader/efi_runtime.c index cee96bfc7fc..bf54d6ad871 100644 --- a/lib/efi_loader/efi_runtime.c +++ b/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); From d9d07d751e0f41d009051e8c25e2d5d9cf7ca41c Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 1 Apr 2023 12:20:34 +0200 Subject: [PATCH 12/12] cmd: consider multiplexing in coninfo If console multiplexing in enabled (CONFIG_CONSOLE_MUX=y), the output of the coninfo command should show the file association (stdin, stderr, stdout) for all devices not only the default ones. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- cmd/console.c | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/cmd/console.c b/cmd/console.c index 620a961cdef..58c2cf1c894 100644 --- a/cmd/console.c +++ b/cmd/console.c @@ -9,6 +9,7 @@ */ #include #include +#include #include 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) { - printf("| |-- %s\n", stdio_names[l]); + 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;