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/index.rst b/doc/develop/index.rst
index 9592d19..c84b10e 100644 (file)
--- 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 (file)
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.