Merge branch '2022-04-25-initial-implementation-of-stdboot'

To quote the author:
The bootflow feature provide a built-in way for U-Boot to automatically
boot an Operating System without custom scripting and other customisation.
This is called 'standard boot' since it provides a standard way for
U-Boot to boot a distro, without scripting.

It introduces the following concepts:

   - bootdev - a device which can hold a distro
   - bootmeth - a method to scan a bootdev to find bootflows (owned by
                U-Boot)
   - bootflow - a description of how to boot (owned by the distro)

This series provides an implementation of these, enabled to scan for
bootflows from MMC, USB and Ethernet. It supports the existing distro
boot as well as the EFI loader flow (bootefi/bootmgr). It works
similiarly to the existing script-based approach, but is native to
U-Boot.

With this we can boot on a Raspberry Pi 3 with just one command:

   bootflow scan -lb

which means to scan, listing (-l) each bootflow and trying to boot each
one (-b). The final patch shows this.

With a standard way to identify boot devices, booting become easier. It
also should be possible to support U-Boot scripts, for backwards
compatibility only.

...

The design is described in these two documents:

https://drive.google.com/file/d/1ggW0KJpUOR__vBkj3l61L2dav4ZkNC12/view?usp=sharing

https://drive.google.com/file/d/1kTrflO9vvGlKp-ZH_jlgb9TY3WYG6FF9/view?usp=sharing

1 files changed, 69 insertions, 48 deletions

diff --git a/include/vsprintf.h b/include/vsprintf.h
index 532ef3650bd..e006af200fd 100644
--- a/include/vsprintf.h
+++ b/include/vsprintf.h
@@ -13,9 +13,9 @@
 /**
  * simple_strtoul - convert a string to an unsigned long
  *
- * @param cp	The string to be converted
- * @param endp	Updated to point to the first character not converted
- * @param base	The number base to use (0 for the default)
+ * @cp: The string to be converted
+ * @endp: Updated to point to the first character not converted
+ * @base: The number base to use (0 for the default)
  * Return: value decoded from string (0 if invalid)
  *
  * Converts a string to an unsigned long. If there are invalid characters at
@@ -34,8 +34,8 @@ ulong simple_strtoul(const char *cp, char **endp, unsigned int base);
 /**
  * hex_strtoul - convert a string in hex to an unsigned long
  *
- * @param cp	The string to be converted
- * @param endp	Updated to point to the first character not converted
+ * @cp: The string to be converted
+ * @endp: Updated to point to the first character not converted
  * Return: value decoded from string (0 if invalid)
  *
  * Converts a hex string to an unsigned long. If there are invalid characters at
@@ -47,8 +47,8 @@ unsigned long hextoul(const char *cp, char **endp);
 /**
  * dec_strtoul - convert a string in decimal to an unsigned long
  *
- * @param cp	The string to be converted
- * @param endp	Updated to point to the first character not converted
+ * @cp: The string to be converted
+ * @endp: Updated to point to the first character not converted
  * Return: value decoded from string (0 if invalid)
  *
  * Converts a decimal string to an unsigned long. If there are invalid
@@ -59,11 +59,11 @@ unsigned long dectoul(const char *cp, char **endp);
 
 /**
  * strict_strtoul - convert a string to an unsigned long strictly
- * @param cp	The string to be converted
- * @param base	The number base to use (0 for the default)
- * @param res	The converted result value
- * Return: 0 if conversion is successful and *res is set to the converted
- * value, otherwise it returns -EINVAL and *res is set to 0.
+ * @cp: The string to be converted
+ * @base: The number base to use (0 for the default)
+ * @res: The converted result value
+ * Return: 0 if conversion is successful and `*res` is set to the converted
+ * value, otherwise it returns -EINVAL and `*res` is set to 0.
  *
  * strict_strtoul converts a string to an unsigned long only if the
  * string is really an unsigned long string, any string containing
@@ -98,8 +98,11 @@ long long simple_strtoll(const char *cp, char **endp, unsigned int base);
  * Given a string this finds a trailing number on the string and returns it.
  * For example, "abc123" would return 123.
  *
- * @str:	String to exxamine
- * Return: training number if found, else -1
+ * Note that this does not handle a string without a prefix. See dectoul() for
+ * that case.
+ *
+ * @str:	String to examine
+ * Return: trailing number if found, else -1
  */
 long trailing_strtol(const char *str);
 
@@ -111,20 +114,38 @@ long trailing_strtol(const char *str);
  * characters between @str and @end - 1 are examined. If @end is NULL, it is
  * set to str + strlen(str).
  *
- * @str:	String to exxamine
+ * @str:	String to examine
  * @end:	Pointer to end of string to examine, or NULL to use the
  *		whole string
- * Return: training number if found, else -1
+ * Return: trailing number if found, else -1
  */
 long trailing_strtoln(const char *str, const char *end);
 
 /**
+ * trailing_strtoln_end() - extract trailing integer from a fixed-length string
+ *
+ * Given a fixed-length string this finds a trailing number on the string
+ * and returns it. For example, "abc123" would return 123. Only the
+ * characters between @str and @end - 1 are examined. If @end is NULL, it is
+ * set to str + strlen(str).
+ *
+ * @str:	String to examine
+ * @end:	Pointer to end of string to examine, or NULL to use the
+ *		whole string
+ * @endp:	If non-NULL, this is set to point to the character where the
+ *	number starts, e.g. for "mmc0" this would be point to the '0'; if no
+ *	trailing number is found, it is set to the end of the string
+ * Return: training number if found, else -1
+ */
+long trailing_strtoln_end(const char *str, const char *end, char const **endp);
+
+/**
  * panic() - Print a message and reset/hang
  *
  * Prints a message on the console(s) and then resets. If CONFIG_PANIC_HANG is
  * defined, then it will hang instead of resetting.
  *
- * @param fmt:	printf() format string for message, which should not include
+ * @fmt: printf() format string for message, which should not include
  *		\n, followed by arguments
  */
 void panic(const char *fmt, ...)
@@ -139,16 +160,16 @@ void panic(const char *fmt, ...)
  * This function can be used instead of panic() when your board does not
  * already use printf(), * to keep code size small.
  *
- * @param fmt:	string to display, which should not include \n
+ * @str: string to display, which should not include \n
  */
 void panic_str(const char *str) __attribute__ ((noreturn));
 
 /**
  * Format a string and place it in a buffer
  *
- * @param buf	The buffer to place the result into
- * @param fmt	The format string to use
- * @param ...	Arguments for the format string
+ * @buf: The buffer to place the result into
+ * @fmt: The format string to use
+ * @...: Arguments for the format string
  *
  * The function returns the number of characters written
  * into @buf.
@@ -161,9 +182,9 @@ int sprintf(char *buf, const char *fmt, ...)
 /**
  * Format a string and place it in a buffer (va_list version)
  *
- * @param buf	The buffer to place the result into
- * @param fmt	The format string to use
- * @param args	Arguments for the format string
+ * @buf: The buffer to place the result into
+ * @fmt: The format string to use
+ * @args: Arguments for the format string
  * Return: the number of characters which have been written into
  * the @buf not including the trailing '\0'.
  *
@@ -178,7 +199,7 @@ int vsprintf(char *buf, const char *fmt, va_list args);
  *
  * This returns a static string containing the decimal representation of the
  * given value. The returned value may be overwritten by other calls to other
- * simple_... functions, so should be used immediately
+ * simple... functions, so should be used immediately
  *
  * @val: Value to convert
  * Return: string containing the decimal representation of @val
@@ -190,9 +211,9 @@ char *simple_itoa(ulong val);
  *
  * This returns a static string containing the hexadecimal representation of the
  * given value. The returned value may be overwritten by other calls to other
- * simple_... functions, so should be used immediately
+ * simple... functions, so should be used immediately
  *
- * @val: Value to convert
+ * @num: Value to convert
  * Return: string containing the hexecimal representation of @val
  */
 char *simple_xtoa(ulong num);
@@ -200,10 +221,10 @@ char *simple_xtoa(ulong num);
 /**
  * Format a string and place it in a buffer
  *
- * @param buf	The buffer to place the result into
- * @param size	The size of the buffer, including the trailing null space
- * @param fmt	The format string to use
- * @param ...	Arguments for the format string
+ * @buf: The buffer to place the result into
+ * @size: The size of the buffer, including the trailing null space
+ * @fmt: The format string to use
+ * @...: Arguments for the format string
  * Return: the number of characters which would be
  * generated for the given input, excluding the trailing null,
  * as per ISO C99.  If the return is greater than or equal to
@@ -217,10 +238,10 @@ int snprintf(char *buf, size_t size, const char *fmt, ...)
 /**
  * Format a string and place it in a buffer
  *
- * @param buf	The buffer to place the result into
- * @param size	The size of the buffer, including the trailing null space
- * @param fmt	The format string to use
- * @param ...	Arguments for the format string
+ * @buf: The buffer to place the result into
+ * @size: The size of the buffer, including the trailing null space
+ * @fmt: The format string to use
+ * @...: Arguments for the format string
  *
  * The return value is the number of characters written into @buf not including
  * the trailing '\0'. If @size is == 0 the function returns 0.
@@ -233,10 +254,10 @@ int scnprintf(char *buf, size_t size, const char *fmt, ...)
 /**
  * Format a string and place it in a buffer (base function)
  *
- * @param buf	The buffer to place the result into
- * @param size	The size of the buffer, including the trailing null space
- * @param fmt	The format string to use
- * @param args	Arguments for the format string
+ * @buf: The buffer to place the result into
+ * @size: The size of the buffer, including the trailing null space
+ * @fmt: The format string to use
+ * @args: Arguments for the format string
  * Return: The number characters which would be generated for the given
  * input, excluding the trailing '\0', as per ISO C99. Note that fewer
  * characters may be written if this number of characters is >= size.
@@ -258,10 +279,10 @@ int vsnprintf(char *buf, size_t size, const char *fmt, va_list args);
 /**
  * Format a string and place it in a buffer (va_list version)
  *
- * @param buf	The buffer to place the result into
- * @param size	The size of the buffer, including the trailing null space
- * @param fmt	The format string to use
- * @param args	Arguments for the format string
+ * @buf: The buffer to place the result into
+ * @size: The size of the buffer, including the trailing null space
+ * @fmt: The format string to use
+ * @args: Arguments for the format string
  * Return: the number of characters which have been written into
  * the @buf not including the trailing '\0'. If @size is == 0 the function
  * returns 0.
@@ -278,8 +299,8 @@ int vscnprintf(char *buf, size_t size, const char *fmt, va_list args);
  * This prints a value with grouped digits, like 12,345,678 to make it easier
  * to read.
  *
- * @val:	Value to print
- * @digits:	Number of digiits to print
+ * @int_val: Value to print
+ * @digits: Number of digiits to print
  */
 void print_grouped_ull(unsigned long long int_val, int digits);
 
@@ -309,9 +330,9 @@ void str_to_upper(const char *in, char *out, size_t len);
 
 /**
  * vsscanf - Unformat a buffer into a list of arguments
- * @buf:	input buffer
- * @fmt:	format of buffer
- * @args:	arguments
+ * @inp: input buffer
+ * @fmt0: format of buffer
+ * @ap: arguments
  */
 int vsscanf(const char *inp, char const *fmt0, va_list ap);