doc: printf() codes
Document the format specifier codes used by U-Boot's printf()
implementation.
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
diff --git a/doc/develop/printf.rst b/doc/develop/printf.rst
new file mode 100644
index 0000000..7b9aea0
--- /dev/null
+++ b/doc/develop/printf.rst
@@ -0,0 +1,199 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Printf() format codes
+=====================
+
+Each conversion specification consists of:
+
+* leading '%' character
+* zero or more flags
+* an optional minimum field width
+* an optional precision field preceded by '.'
+* an optional length modifier
+* a conversion specifier
+
+Flags
+-----
+
+'space'
+ fill up with spaces to reach the specified length
+
+\-
+ left justify
+
+\+
+ add sign field of decimal conversion
+
+#
+ convert to alternative form
+
+ * prepend 0 to octal output
+ * ignored for decimal output
+ * prepend 0X to hexadecimal output
+
+0
+ fill up with zeroes to reach the specified length
+
+
+Integer types
+-------------
+
+Length modifiers
+''''''''''''''''
+
+The optional length modifier specifies the size of the argument.
+
+no modifier
+ bool, enum, short, int are passed as int
+
+%h
+ convert to (unsigned) short before printing.
+ Only the low 16 bits are printed.
+
+%hh
+ **not implemented**
+
+%j
+ **not implemented**
+
+%l
+ long
+
+%ll, %L
+ long long
+
+%t
+ ptr_diff_t
+
+%z, %Z
+ size_t, ssize_t
+
+Conversion specifiers
+'''''''''''''''''''''
+
+Conversion specifiers control the output.
+
+%d
+ signed decimal
+
+%u
+ unsigned decimal
+
+%o
+ unsigned octal
+
+%x
+ unsigned lower case hexadecimal
+
+%X
+ unsigned upper case hexadecimal
+
+The floating point conversion specifiers are not implemented:
+
+* %a
+* %A
+* %e
+* %E
+* %f
+* %F
+* %g
+* %G
+
+The following tables shows the correct combinations of modifiers 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
+resource_size_t %pa, see pointers
+size_t %zu, %zx, %zX
+ssize_t %zd, %zx, %zX
+=================== ==================
+
+Characters
+----------
+
+%%
+ a '%' character is written
+
+%c
+ prints a single character
+
+%lc
+ **not implemented**
+
+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 the size of phys_addr_t.
+ The following types should be printed this way:
+
+ * fdt_addr_t
+ * fdt_size_t
+ * phys_addr_t
+ * phys_size_t
+ * resource_size_t
+
+%pD
+ prints a 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 little endian, lower case
+ e.g. '33221100-5544-7766-8899-aabbccddeeff'
+
+%pUL
+ prints GUID little endian, upper case
+ e.g. '33221100-5544-7766-8899-AABBCCDDEEFF'
+
+%pUs
+ prints text description of a GUID or if such is not known little endian,
+ lower case, e.g. 'system' for a GUID identifying an EFI system
+ partition.