[PATCH] docs: printk-formats: Clarify %*pb format parameters

[PATCH] docs: printk-formats: Clarify %*pb format parameters

[Luca Weiss]

Since it's rather unusual for printk formats to require two parameters,
expand the documentation to clearly mention that in the printk format
for bitmaps.

As an extra example, for example from include/net/bluetooth/hci_core.h
we have a bitmap DECLARE_BITMAP(dev_flags, __HCI_NUM_FLAGS);
This can be printed with ("%*pb", __HCI_NUM_FLAGS, hdev->dev_flags)

Signed-off-by: Luca Weiss <luca.weiss@fairphone.com>
---
This probably also applies to other printk formats but since this is the
only one so far I've used that requires two parameters I cannot really
help with the others.

Someone with more knowledge on the other more unusual format strings
could apply this to others also.
---
 Documentation/core-api/printk-formats.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
index dfe7e75a71de..3cafb988d757 100644
--- a/Documentation/core-api/printk-formats.rst
+++ b/Documentation/core-api/printk-formats.rst
@@ -571,7 +571,9 @@ For printing bitmap and its derivatives such as cpumask and nodemask,
 %*pb outputs the bitmap with field width as the number of bits and %*pbl
 output the bitmap as range list with field width as the number of bits.
 
-The field width is passed by value, the bitmap is passed by reference.
+This requires two parameters, the field width (number of bits in the bitmap)
+passed by value and the bitmap passed by reference.
+
 Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease
 printing cpumask and nodemask.
 

---
base-commit: 16a8829130ca22666ac6236178a6233208d425c3
change-id: 20230516-printk-bitmap-bcffd77379ac

Best regards,
-- 
Luca Weiss <luca.weiss@fairphone.com>

Re: [PATCH] docs: printk-formats: Clarify %*pb format parameters

[Andy Shevchenko]

On Tue, May 16, 2023 at 08:52:43AM +0200, Luca Weiss wrote:
> Since it's rather unusual for printk formats to require two parameters,

I don't think this is "unusual". The %*... is very well described in the
printf(3) (the meaning of *). It applies here for %*p... as well.

> expand the documentation to clearly mention that in the printk format
> for bitmaps.
> 
> As an extra example, for example from include/net/bluetooth/hci_core.h
> we have a bitmap DECLARE_BITMAP(dev_flags, __HCI_NUM_FLAGS);
> This can be printed with ("%*pb", __HCI_NUM_FLAGS, hdev->dev_flags)

I think this change is not needed. But try to convince PRINTK maintainers.
Maybe they will be okay with it if it covers all %*p... cases (like %*ph).

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH] docs: printk-formats: Clarify %*pb format parameters

[Luca Weiss]

On Wed May 17, 2023 at 6:19 PM CEST, Andy Shevchenko wrote:
> On Tue, May 16, 2023 at 08:52:43AM +0200, Luca Weiss wrote:
> > Since it's rather unusual for printk formats to require two parameters,
>
> I don't think this is "unusual".

Well, unusual for me at least. I've never really used anything except
the standard integer types and %px. And I've been contributing to the
kernel since 2017.

> The %*... is very well described in the printf(3) (the meaning of *).
> It applies here for %*p... as well.

The printf(3) man page is never mentioned on this docs page. And even if
it would be mentioned somewhere, I doubt anyone is reading most of the
page when they're just looking for a format specifier for e.g. bitmap.
At least I am not.

>
> > expand the documentation to clearly mention that in the printk format
> > for bitmaps.
> > 
> > As an extra example, for example from include/net/bluetooth/hci_core.h
> > we have a bitmap DECLARE_BITMAP(dev_flags, __HCI_NUM_FLAGS);
> > This can be printed with ("%*pb", __HCI_NUM_FLAGS, hdev->dev_flags)
>
> I think this change is not needed. But try to convince PRINTK maintainers.
> Maybe they will be okay with it if it covers all %*p... cases (like %*ph).

Cannot say I haven't tried :) As I wrote in the initial email I'd be
happy also if someone who knows more about the formats to include some
text for all the %* options so users know what's up.

Regards
Luca

[PATCH] vsprintf/doc: Document format flags including field width and precision

[Petr Mladek]

The kernel implementation of vsprintf() tries to be as compatible with
the user space variant as possible. Though it does not implement all
features. On the other hand, it adds some special pointer printing
modifiers.

Most differences are described in Documentation/core-api/printk-formats.rst
Add the missing documentation of the supported flag characters
'#', '0', '-', ' ', '+' together with field width and precision modifiers.

Suggested-by: Luca Weiss <luca.weiss@fairphone.com>
Signed-off-by: Petr Mladek <pmladek@suse.com>
---
What about something like this, please?

 Documentation/core-api/printk-formats.rst | 69 +++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
index dfe7e75a71de..79655b319658 100644
--- a/Documentation/core-api/printk-formats.rst
+++ b/Documentation/core-api/printk-formats.rst
@@ -8,6 +8,75 @@ How to get printk format specifiers right
 :Author: Andrew Murray <amurray@mpc-data.co.uk>
 
 
+Flag characters
+===============
+
+The character '%' might be followed by the following flags that modify
+the output:
+
+	- '#' - prepend '0', '0x', or 'OX for 'o', 'x', 'X' number conversions
+	- '0' - zero pad number conversions on the field boundary
+	- '-' - left adjust on the field boundary, blank pad on the right
+	- ' ' - prepend space on positive numbers
+	- '+' - prepend + for positive numbers when using signed formats
+
+Examples::
+
+	|%x|	|1a|
+	|%#x|	|0x1a|
+	|%d|	|26|
+	|% d|	| 26|
+	|%+d|	|+26|
+
+
+Field width
+===========
+
+A field width may be defined when '%' is optionally followed by the above flag
+characters and:
+
+	- 'number' - the decimal number defines the field width
+	- '*' the field width is defined by an extra parameter
+
+Values are never truncated when the filed width is not big enough.
+Spaces are used by default when a padding is needed.
+
+Examples::
+
+	|%6d|	|    26|
+	|%-6d|	|26    |
+	|%06d|	|000026|
+
+	printk("Dynamic table: |%*d|%*s|\n", id_width, id, max_name_len, name);
+
+The filed width value might have special meaning for some pointer formats.
+For example, it limits the size of the bitmap handled by %*pb format.
+
+
+
+Field precision:
+================
+
+A field width may be defined when '%' is optionally followed by the above flag
+characters:
+
+	- '.number' - the decimal number defines the field precision
+	- '.*' the field precision is defined by an extra parameter
+
+The precision defines:
+
+	- number of digits after the decimal point in float number conversions
+	- minimal number of digits in integer conversions
+	- maximum number of characters in string conversions
+
+Examples::
+
+	|%.3f|	|12.300|
+	|%.6d|	|    26|
+	|%.6s|	|Hi, th|
+
+	printk("Dynamic precision: %.*f\n", precision, value);
+
 Integer types
 =============
 
-- 
2.35.3

Re: [PATCH] vsprintf/doc: Document format flags including field width and precision

[Rasmus Villemoes]

On 22/05/2023 17.08, Petr Mladek wrote:
> The kernel implementation of vsprintf() tries to be as compatible with
> the user space variant as possible. Though it does not implement all
> features. On the other hand, it adds some special pointer printing
> modifiers.
> 
> Most differences are described in Documentation/core-api/printk-formats.rst
> Add the missing documentation of the supported flag characters
> '#', '0', '-', ' ', '+' together with field width and precision modifiers.
> 
> Suggested-by: Luca Weiss <luca.weiss@fairphone.com>
> Signed-off-by: Petr Mladek <pmladek@suse.com>
> ---
> What about something like this, please?
> 
>  Documentation/core-api/printk-formats.rst | 69 +++++++++++++++++++++++
>  1 file changed, 69 insertions(+)
> 
> diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
> index dfe7e75a71de..79655b319658 100644
> --- a/Documentation/core-api/printk-formats.rst
> +++ b/Documentation/core-api/printk-formats.rst
> @@ -8,6 +8,75 @@ How to get printk format specifiers right
>  :Author: Andrew Murray <amurray@mpc-data.co.uk>
>  
>  
> +Flag characters
> +===============
> +
> +The character '%' might be followed by the following flags that modify
> +the output:
> +
> +	- '#' - prepend '0', '0x', or 'OX for 'o', 'x', 'X' number conversions
> +	- '0' - zero pad number conversions on the field boundary
> +	- '-' - left adjust on the field boundary, blank pad on the right
> +	- ' ' - prepend space on positive numbers
> +	- '+' - prepend + for positive numbers when using signed formats

[I wonder if we have a single user of any of the latter two in the
entire tree.]

> +Examples::
> +
> +	|%x|	|1a|
> +	|%#x|	|0x1a|
> +	|%d|	|26|
> +	|% d|	| 26|
> +	|%+d|	|+26|
> +
> +
> +Field width
> +===========
> +
> +A field width may be defined when '%' is optionally followed by the above flag
> +characters and:
> +
> +	- 'number' - the decimal number defines the field width
> +	- '*' the field width is defined by an extra parameter
> +
> +Values are never truncated when the filed width is not big enough.

filed -> field (several places)

> +Spaces are used by default when a padding is needed.
> +
> +Examples::
> +
> +	|%6d|	|    26|
> +	|%-6d|	|26    |
> +	|%06d|	|000026|
> +
> +	printk("Dynamic table: |%*d|%*s|\n", id_width, id, max_name_len, name);
> +
> +The filed width value might have special meaning for some pointer formats.
> +For example, it limits the size of the bitmap handled by %*pb format.

It should also be noted that a negative field width passed as a *
argument is interpreted as if the - flag is used and then the absolute
value is used as field width.

> +
> +
> +Field precision:
> +================
> +
> +A field width may be defined when '%' is optionally followed by the above flag
> +characters:
> +
> +	- '.number' - the decimal number defines the field precision
> +	- '.*' the field precision is defined by an extra parameter
> +
> +The precision defines:
> +
> +	- number of digits after the decimal point in float number conversions

No, don't mention floats, the kernel doesn't do those.

> +	- minimal number of digits in integer conversions
> +	- maximum number of characters in string conversions
> +
> +Examples::
> +
> +	|%.3f|	|12.300|

Remove.

> +	|%.6d|	|    26|

Nope, that actually produces 000026.

---

So overall, I'm not sure this is a net win. I think it might be better
to emphasize that

- the kernel doesn't do floats, argument reordering via m$, wide
characters/strings, %m or %n (just so that's out of the equation)

- for string and integer conversions, the kernel's printf is very very
close to following POSIX/libc/whatever, in terms of flags, field width
etc. [There are a few exceptions, those I've found are documented in
test_printf.c, but nobody is ever likely to hit those.]

- for %p, the kernel has its own rules, starting with the fact that
modifying behaviour based on alphanumerics following the p is completely
non-standard.

and then spend the rest explaining those rules, and perhaps also some
background on why the %p extensions exist and why they are implemented
the way they are - for example "we want -Wformat to tell us if something
is wrong", but that, for example, means we can only use a field width
and not a precision to pass an extra argument to a %psomething. And
alphanumerics are chosen because nobody would usually follow a normal %p
by anything but whitespace or punctuation, and because the compiler
format checking is happy as long as there's some pointer argument
corresponding to the %p, and the remaining characters are, from the
compiler's POV, just literal characters.

Rasmus

Re: [PATCH] vsprintf/doc: Document format flags including field width and precision

[John Ogness]

On 2023-05-22, Petr Mladek <pmladek@suse.com> wrote:
> +Examples::

> +	printk("Dynamic table: |%*d|%*s|\n", id_width, id, max_name_len, name);

> +	printk("Dynamic precision: %.*f\n", precision, value);

Generally speaking, it is rare to use printk() without a loglevel
specified. And it is preferred that the pr_ or dev_ macros are
used. Perhaps the examples should call pr_info() instead?

John Ogness