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

[Heinrich Schuchardt]

On 1/19/22 04:09, AKASHI Takahiro wrote:
> 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 '\'

Thank you for reviewing.

This is restructured text. The asterisk must be escaped to be printed. 
Otherwise it will be interpreted as the start of italics.

Best regards

Heinrich

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