* [PATCH 1/1] doc: printf() codes
@ 2022-01-19 0:23 Heinrich Schuchardt
2022-01-19 3:09 ` AKASHI Takahiro
0 siblings, 1 reply; 3+ messages in thread
From: Heinrich Schuchardt @ 2022-01-19 0:23 UTC (permalink / raw)
To: Tom Rini; +Cc: u-boot, AKASHI Takahiro, Heinrich Schuchardt
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.
--
2.33.1
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH 1/1] doc: printf() codes
2022-01-19 0:23 [PATCH 1/1] doc: printf() codes Heinrich Schuchardt
@ 2022-01-19 3:09 ` AKASHI Takahiro
2022-01-19 14:27 ` Heinrich Schuchardt
0 siblings, 1 reply; 3+ messages in thread
From: AKASHI Takahiro @ 2022-01-19 3:09 UTC (permalink / raw)
To: Heinrich Schuchardt; +Cc: Tom Rini, u-boot
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 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
>
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH 1/1] doc: printf() codes
2022-01-19 3:09 ` AKASHI Takahiro
@ 2022-01-19 14:27 ` Heinrich Schuchardt
0 siblings, 0 replies; 3+ messages in thread
From: Heinrich Schuchardt @ 2022-01-19 14:27 UTC (permalink / raw)
To: AKASHI Takahiro
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 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
>>
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-01-19 14:28 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-01-19 0:23 [PATCH 1/1] doc: printf() codes Heinrich Schuchardt
2022-01-19 3:09 ` AKASHI Takahiro
2022-01-19 14:27 ` Heinrich Schuchardt
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox