diff mbox series

docs: printk-formats: Clarify %*pb format parameters

Message ID 20230516-printk-bitmap-v1-1-d5f810192a10@fairphone.com
State New
Headers
Series docs: printk-formats: Clarify %*pb format parameters |

Commit Message

Luca Weiss May 16, 2023, 6:52 a.m. UTC 
  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(-)


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

Best regards,

Comments

Andy Shevchenko May 17, 2023, 4:19 p.m. UTC | #1 
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).
Luca Weiss May 22, 2023, 6:41 a.m. UTC | #2 
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
diff mbox series

Patch

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.