[PATCH 1/1] doc: printf() codes
Document the format specifier codes used by U-Boot's printf() implementation.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@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 + +%l + long + +%ll, %L + long long + +%t + ptr_diff_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 +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 +size_t %zu, %zx, %Zu, %Zx +ssize_t %zd, %zx, %Zd, %Zx +=================== ===================== + +Characters +---------- + +%c + prints a single character + +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 size of phys_addr_t + +%pD + prints an 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 low endian, lower case + e.g. '33221100-5544-7766-8899-aabbccddeeff' + +%pUL + prints GUID low endian, upper case + e.g. '33221100-5544-7766-8899-AABBCCDDEEFF' + +%pUs + prints text description of a GUID or if such is not known low endian, + lower case, e.g. 'system' for a GUID identifying an EFI system + partition.
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@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 topreceded 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 casee.g. '00112233-4455-6677-8899-aabbccddeeff'+%pUB
prints GUID big endian, upper casee.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
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@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 topreceded with 0x and zero padding according to size of phys_addr_t+%pD
prints an UEFI device pathan -> 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 casee.g. '00112233-4455-6677-8899-aabbccddeeff'+%pUB
prints GUID big endian, upper casee.g. '00112233-4455-6677-8899-AABBCCDDEEFF'+%pUl
prints GUID low endian, lower caselow -> little
e.g. '33221100-5544-7766-8899-aabbccddeeff'+%pUL
prints GUID low endian, upper caseditto
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
participants (2)
-
AKASHI Takahiro -
Heinrich Schuchardt