doc: printf() codes

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

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
This commit is contained in:
Heinrich Schuchardt 2022-01-19 01:20:45 +01:00
parent 3280eaad18
commit f5e9035043
2 changed files with 200 additions and 0 deletions

View file

@ -21,6 +21,7 @@ Implementation
logging
makefiles
menus
printf
uefi/index
version

199
doc/develop/printf.rst Normal file
View file

@ -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.