[PATCH 1/1] doc: printf() codes

[Heinrich Schuchardt]

Document the format specifier codes used by U-Boot's printf()
implementation.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
---
 doc/develop/index.rst  |   1 +
 doc/develop/printf.rst | 132 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 133 insertions(+)
 create mode 100644 doc/develop/printf.rst

diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 9592d193fc..c84b10ea88 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -21,6 +21,7 @@ Implementation
    logging
    makefiles
    menus
+   printf
    uefi/index
    version
 
diff --git a/doc/develop/printf.rst b/doc/develop/printf.rst
new file mode 100644
index 0000000000..6a1266618e
--- /dev/null
+++ b/doc/develop/printf.rst
@@ -0,0 +1,132 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Printf() format codes
+=====================
+
+Integer types
+-------------
+
+Integer qualifiers
+''''''''''''''''''
+
+Inter qualifers describe how integer types are passed as arguments.
+
+no specifier
+	int (used for bool, enum, short, int)
+
+%h
+	int, consider only the low 16 bits
+
+%l
+	long
+
+%ll, %L
+	long long
+
+%t
+	ptr_diff_t
+
+%z, %Z
+	size_t, ssize_t
+
+Format specifiers
+'''''''''''''''''
+
+Format specifiers control the output.
+
+%d
+	signed decimal
+
+%u
+	unsigned decimal
+
+%x
+	lower case hexadecimal
+
+%X
+	upper case hexadecimal
+
+The following tables shows the correct combinations of qulifiers and specifiers
+for the individual integer types.
+
+=================== =====================
+Type                Format specifier
+=================== =====================
+bool		    %d, %x
+char                %d, %x
+unsigned char       %u, %x 
+short               %d, %x
+unsigned short      %u, %x
+int                 %d, %x
+unsigned int        %d, %x
+long                %ld, %lx
+unsigned long       %lu, %lx
+long long           %lld, %llx
+unsigned long long  %llu, %llx
+off_t               %llu, %llx
+ptr_diff_t	    %td, %tx
+fdt_addr_t          %pa, see pointers
+fdt_size_t          %pa, see pointers
+phys_addr_t         %pa, see pointers
+phys_size_t         %pa, see pointers
+size_t              %zu, %zx, %Zu, %Zx
+ssize_t             %zd, %zx, %Zd, %Zx
+=================== =====================
+
+Characters
+----------
+
+%c
+        prints a single character
+
+Strings
+-------
+
+%s
+        prints a UTF-8 string (char \*)
+
+%ls
+        prints a UTF-16 string (u16 \*)
+
+Pointers
+--------
+
+%p
+        prints the address the pointer points to hexadecimally
+
+%pa, %pap
+        prints the value of a phys_addr_t value that the pointer points to
+        preceded with 0x and zero padding according to size of phys_addr_t
+
+%pD
+        prints an UEFI device path
+
+%pi4, %pI4
+        prints IPv4 address, e.g. '192.168.0.1'
+
+%pm
+        prints MAC address without separators, e.g. '001122334455'
+
+%pM
+        print MAC address colon separated, e.g. '00:01:02:03:04:05'        
+
+%pUb
+        prints GUID big endian, lower case
+        e.g. '00112233-4455-6677-8899-aabbccddeeff'
+
+%pUB
+        prints GUID big endian, upper case
+        e.g. '00112233-4455-6677-8899-AABBCCDDEEFF'
+
+%pUl
+        prints GUID low endian, lower case
+        e.g. '33221100-5544-7766-8899-aabbccddeeff'
+
+%pUL
+        prints GUID low endian, upper case
+        e.g. '33221100-5544-7766-8899-AABBCCDDEEFF'
+
+%pUs
+        prints text description of a GUID or if such is not known low endian,
+        lower case, e.g. 'system' for a GUID identifying an EFI system
+	partition.
-- 
2.33.1