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

[AKASHI Takahiro]

Heinrich,

Thank you for additional work.

On Wed, Jan 19, 2022 at 01:23:00AM +0100, Heinrich Schuchardt wrote:
> 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

low -> lower? (think of the opposite, "upper" or "higher")
> +
> +%l
> +	long
> +
> +%ll, %L
> +	long long
> +
> +%t
> +	ptr_diff_t

ptrdiff_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

and %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

Does "see pointers" refer to "Pointer" section?
There is no further description about fdt_[addr|size]_t there.

> +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
> +=================== =====================

For completeness, we might better address padding (space, '0')
justification ('+', '-') and '#' as well.

> +
> +Characters
> +----------
> +
> +%c
> +        prints a single character
> +
> +Strings
> +-------
> +
> +%s
> +        prints a UTF-8 string (char \*)

may drop "a" for consistency in below cases

drop '\'

> +
> +%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

an -> a, or drop it.

> +
> +%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

low -> little

> +        e.g. '33221100-5544-7766-8899-aabbccddeeff'
> +
> +%pUL
> +        prints GUID low endian, upper case

ditto

> +        e.g. '33221100-5544-7766-8899-AABBCCDDEEFF'
> +
> +%pUs
> +        prints text description of a GUID or if such is not known low endian,

ditto

-Takahiro Akashi

> +        lower case, e.g. 'system' for a GUID identifying an EFI system
> +	partition.
> -- 
> 2.33.1
>