Merge tag 'doc-2024-04-rc2' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request doc-2024-04-rc2

Documentation:

* Fix and extend utf8_to_utf32_stream() documentation
* Fix rendering of OpenSBI logo in VisionFive 2 description
* Document imxrt1170-evk board
* codingstyle.rst: Clarify include section

UEFI:

* simplify error message in efi_disk_create_raw()

6 files changed, 81 insertions, 20 deletions

diff --git a/doc/board/nxp/imxrt1170-evk.rst b/doc/board/nxp/imxrt1170-evk.rst
new file mode 100644
index 0000000..86bd39c
--- /dev/null
+++ b/doc/board/nxp/imxrt1170-evk.rst
@@ -0,0 +1,50 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+imxrt1170-evk
+=============
+
+How to use U-Boot on NXP i.MXRT1170 EVK
+---------------------------------------
+
+- Build U-Boot for i.MXRT1170 EVK:
+
+  .. code-block:: bash
+
+      $ make mrproper
+      $ make imxrt1170-evk_defconfig
+      $ make
+
+  This will generate the SPL image called SPL and the u-boot.img.
+
+- Flash the SPL image into the micro SD card:
+
+  .. code-block:: bash
+
+      $sudo dd if=SPL of=/dev/sdX bs=1k seek=1 conv=notrunc; sync
+
+  This location is not compatible with GPT partioning. Please, use MBR
+  partitioning instead.
+
+- Flash the u-boot.img image into the micro SD card:
+
+  .. code-block:: bash
+
+      $sudo dd if=u-boot.img of=/dev/sdX bs=1k seek=128 conv=notrunc; sync
+
+- Jumper settings
+
+  .. list-table::
+     :stub-columns: 1
+
+     * - SW1
+       - 1 0 1 0
+     * - SW2
+       - 0 0 0 0 | 0 0 0 0 | 1 0 0 0
+
+  where 0 means bottom position and 1 means top position (from the
+  switch label numbers reference).
+
+- Connect the USB cable between the EVK and the PC for the console.
+  The USB console connector is the one close the ethernet connector
+
+- Insert the micro SD card in the board, power it up and U-Boot messages should come up.
diff --git a/doc/board/nxp/index.rst b/doc/board/nxp/index.rst
index 3bd9ed3..9468773 100644
--- a/doc/board/nxp/index.rst
+++ b/doc/board/nxp/index.rst
@@ -14,6 +14,7 @@ NXP Semiconductors
    imx93_11x11_evk
    imxrt1020-evk
    imxrt1050-evk
+   imxrt1170-evk
    ls1046ardb
    mx6sabreauto
    mx6sabresd
diff --git a/doc/board/starfive/visionfive2.rst b/doc/board/starfive/visionfive2.rst
index 6cb033e..abda8ac 100644
--- a/doc/board/starfive/visionfive2.rst
+++ b/doc/board/starfive/visionfive2.rst
@@ -133,14 +133,14 @@ Sample boot log from StarFive VisionFive2 board
 	Trying to boot from MMC2
 
 	OpenSBI v1.2-80-g4b28afc
-	____                    _____ ____ _____
-	/ __ \                  / ____|  _ \_   _|
+	  ____                    _____ ____ _____
+	 / __ \                  / ____|  _ \_   _|
 	| |  | |_ __   ___ _ __ | (___ | |_) || |
 	| |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
 	| |__| | |_) |  __/ | | |____) | |_) || |_
-	\____/| .__/ \___|_| |_|_____/|___/_____|
-			| |
-			|_|
+	 \____/| .__/ \___|_| |_|_____/|____/_____|
+	       | |
+	       |_|
 
 	Platform Name             : StarFive VisionFive 2 v1.3B
 	Platform Features         : medeleg
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
index b25bfbd..f6248cd 100644
--- a/doc/develop/codingstyle.rst
+++ b/doc/develop/codingstyle.rst
@@ -108,30 +108,29 @@ expected size, or that particular members appear at the right offset.
 Include files
 -------------
 
-You should follow this ordering in U-Boot. The common.h header (which is going
-away at some point) should always be first, followed by other headers in order,
-then headers with directories, then local files:
+You should follow this ordering in U-Boot. In all cases, they should be listed
+in alphabetical order. First comes headers which are located directly in our
+top-level include diretory. This excludes the common.h header file which is to
+be removed. Second are headers within subdirectories, Finally directory-local
+includes should be listed. See this example:
 
 .. code-block:: C
 
-   #include <common.h>
    #include <bootstage.h>
    #include <dm.h>
    #include <others.h>
    #include <asm/...>
-   #include <arm/arch/...>
+   #include <asm/arch/...>
    #include <dm/device_compat.h>
    #include <linux/...>
    #include "local.h"
 
-Within that order, sort your includes.
-
-It is important to include common.h first since it provides basic features used
-by most files, e.g. CONFIG options.
-
 For files that need to be compiled for the host (e.g. tools), you need to use
-``#ifndef USE_HOSTCC`` to avoid including common.h since it includes a lot of
-internal U-Boot things. See common/image.c for an example.
+``#ifndef USE_HOSTCC`` to avoid including U-Boot specific include files. See
+common/image.c for an example.
+
+If you encounter code which still uses <common.h> a patch to remove that and
+replace it with any required include files directly is much appreciated.
 
 If your file uses driver model, include <dm.h> in the C file. Do not include
 dm.h in a header file. Try to use forward declarations (e.g. ``struct
diff --git a/include/charset.h b/include/charset.h
index 44034c7..f1050c9 100644
--- a/include/charset.h
+++ b/include/charset.h
@@ -324,11 +324,21 @@ int utf_to_cp(s32 *c, const u16 *codepage);
 int utf8_to_cp437_stream(u8 c, char *buffer);
 
 /**
- * utf8_to_utf32_stream() - convert UTF-8 stream to UTF-32
+ * utf8_to_utf32_stream() - convert UTF-8 byte stream to Unicode code points
+ *
+ * The function is called for each byte @c in a UTF-8 stream. The byte is
+ * appended to the temporary storage @buffer until the UTF-8 stream in
+ * @buffer describes a Unicode code point.
+ *
+ * When a new code point has been decoded it is returned and buffer[0] is
+ * set to '\0', otherwise the return value is 0.
+ *
+ * The buffer must be at least 5 characters long. Before the first function
+ * invocation buffer[0] must be set to '\0'."
  *
  * @c:		next UTF-8 character to convert
  * @buffer:	buffer, at least 5 characters
- * Return:	next codepage 437 character or 0
+ * Return:	Unicode code point or 0
  */
 int utf8_to_utf32_stream(u8 c, char *buffer);
 
diff --git a/lib/efi_loader/efi_disk.c b/lib/efi_loader/efi_disk.c
index b1739d9..93a9a5a 100644
--- a/lib/efi_loader/efi_disk.c
+++ b/lib/efi_loader/efi_disk.c
@@ -574,7 +574,8 @@ static int efi_disk_create_raw(struct udevice *dev, efi_handle_t agent_handle)
 			log_notice("Disk %s not ready\n", dev->name);
 			ret = -EBUSY;
 		} else {
-			log_err("Adding disk for %s failed (err=%ld/%#lx)\n", dev->name, ret, ret);
+			log_err("Adding block device %s failed, r = %lu\n",
+				dev->name, ret & ~EFI_ERROR_MASK);
 			ret = -ENOENT;
 		}