Re: [PATCH] doc: convert printk-formats.txt to rst

["Tobin C. Harding" <me@tobin.cc>]

On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote:

Thanks for your comments Randy.

> On 12/05/2017 05:45 PM, Tobin C. Harding wrote:
> > Documentation/printk-formats.txt is a candidate for conversion to
> > ReStructuredText format. Some effort has already been made to do this
> > conversion even thought the suffix is currently .txt
> > 
> > Changes required to complete conversion
> > 
> > - Add double backticks where needed.
> > - Add entry to Documentation/index.rst
> > - Use flat-table instead of ASCII table.
> > - Fix minor grammatical errors.
> > - Capitalize headers and correctly order heading adornments.
> 
> That's a style choice and an unneeded change (referring to Capitalize headers).

No worries, will revert.

> > - Use 'Passed by reference' uniformly.
> > - Update pointer documentation around %px specifier.
> > - Fix erroneous double backticks (to commas).
> > - Simplify documentation for kobject.
> > - Convert lib/vsnprintf.c function docs to use kernel-docs and
> >   include in Documentation/printk-formats.rst
> 
> good idea.
>
> > 
> > Signed-off-by: Tobin C. Harding <me@tobin.cc>
> > ---
> > 
> > The last two need special reviewing please. In particular the conversion
> > of kernel-docs in vsnprintf.c attempt was made to reduce documentation
> > duplication with comments in the source code being simplified in order
> > to be suitable for inclusion in Documentation/printk-formats.rst
> > 
> > I used -M when formatting the patch. If you don't like the diff with
> > this flag just holla.
> > 
> > thanks,
> > Tobin.
> > 
> >  Documentation/index.rst                            |  10 +
> >  .../{printk-formats.txt => printk-formats.rst}     | 295 ++++++++++++---------
> >  lib/vsprintf.c                                     | 160 +++++------
> >  3 files changed, 235 insertions(+), 230 deletions(-)
> >  rename Documentation/{printk-formats.txt => printk-formats.rst} (61%)
> 
> > diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.rst
> > similarity index 61%
> > rename from Documentation/printk-formats.txt
> > rename to Documentation/printk-formats.rst
> > index aa0a776c817a..51449d213748 100644
> > --- a/Documentation/printk-formats.txt
> > +++ b/Documentation/printk-formats.rst
> > @@ -1,6 +1,6 @@
> > -=========================================
> > -How to get printk format specifiers right
> > -=========================================
> > +=============================================
> > +How to Get ``printk`` Format Specifiers Right
> > +=============================================
> >  
> >  :Author: Randy Dunlap <rdunlap@infradead.org>
> >  :Author: Andrew Murray <amurray@mpc-data.co.uk>
> > @@ -8,56 +8,91 @@ How to get printk format specifiers right
> >  Integer types
> >  =============
> >  
> > -::
> > +For printing integer types, we have the following format specifiers:
> > +		
> > +   .. flat-table:: 
> > +      :widths: 2 2
> > +
> > +      * - **Type**
> > +	- **Specifier**
> > +
> > +      * - ``int``
> > +        - ``%d`` or ``%x``
> > +
> > +      * - ``unsigned int``
> > +	- ``%u`` or ``%x``
> > +
> > +      * - ``long``
> > +	- ``%ld`` or ``%lx``
> > +
> > +      * - ``unsigned long``
> > +	- ``%lu`` or ``%lx``
> > +
> > +      * - ``long long``
> > +	- ``%lld`` or ``%llx``
> >  
> > -	If variable is of Type,		use printk format specifier:
> > -	------------------------------------------------------------
> > -		int			%d or %x
> > -		unsigned int		%u or %x
> > -		long			%ld or %lx
> > -		unsigned long		%lu or %lx
> > -		long long		%lld or %llx
> > -		unsigned long long	%llu or %llx
> > -		size_t			%zu or %zx
> > -		ssize_t			%zd or %zx
> > -		s32			%d or %x
> > -		u32			%u or %x
> > -		s64			%lld or %llx
> > -		u64			%llu or %llx
> > -
> > -If <type> is dependent on a config option for its size (e.g., ``sector_t``,
> > +      * - ``unsigned long long``
> > +	- ``%llu`` or ``%llx``
> > +
> > +      * - ``size_t``
> > +	- ``%zu`` or ``%zx``
> > +
> > +      * - ``ssize_t``
> > +	- ``%zd`` or ``%zx``
> > +
> > +      * - ``s32``
> > +	- ``%d`` or ``%x``
> > +
> > +      * - ``u32``
> > +	- ``%u`` or ``%x``
> > +
> > +      * - ``s64``
> > +	- ``%lld`` or ``%llx``
> > +
> > +      * - ``u64``
> > +	- ``%llu`` or ``%llx``
> > +
> > +
> > +If ``<type>`` is dependent on a config option for its size (e.g., ``sector_t``,
> >  ``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
> >  use a format specifier of its largest possible type and explicitly cast to it.
> >  
> >  Example::
> >  
> > -	printk("test: sector number/total blocks: %llu/%llu\n",
> > -		(unsigned long long)sector, (unsigned long long)blockcount);
> > +	printk("test: total blocks: %llu\n", (unsigned long long)blockcount);
> >  
> > -Reminder: ``sizeof()`` result is of type ``size_t``.
> > +Reminder: ``sizeof()`` returns type ``size_t``.
> >  
> > -The kernel's printf does not support ``%n``. For obvious reasons, floating
> > +The kernel's printf does not support ``%n``. For obvious reasons floating
> >  point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
> >  unsupported specifier or length qualifier results in a WARN and early
> > -return from vsnprintf.
> > -
> > -Raw pointer value SHOULD be printed with %p. The kernel supports
> > -the following extended format specifiers for pointer types:
> > +return from ``vsnprintf()``.
> >  
> >  Pointer Types
> >  =============
> >  
> > -Pointers printed without a specifier extension (i.e unadorned %p) are
> > -hashed to give a unique identifier without leaking kernel addresses to user
> > -space. On 64 bit machines the first 32 bits are zeroed. If you _really_
> > -want the address see %px below.
> > +A raw pointer value may be printed with ``%p`` which will hash the address
> > +before printing. The Kernel also supports extended specifiers for printing
> > +pointers of different types.
> > +
> > +.. kernel-doc:: lib/vsprintf.c
> > +     :doc: Extended Format Pointer Specifiers
> > +
> > +
> > +Plain Pointers
> > +--------------
> >  
> >  ::
> >  
> >  	%p	abcdef12 or 00000000abcdef12
> >  
> > +Pointers printed without a specifier extension (i.e unadorned ``%p``) are
> > +hashed to give a unique identifier without leaking kernel addresses to user
> > +space. On 64 bit machines the first 32 bits are zeroed. If you *really*
> 
>              64-bit
> 
> > +want the address see ``%px`` below.
> > +
> >  Symbols/Function Pointers
> > -=========================
> > +-------------------------
> >  
> >  ::
> >  
> > @@ -69,61 +104,60 @@ Symbols/Function Pointers
> >  	%ps	versatile_init
> >  	%pB	prev_fn_of_versatile_init+0x88/0x88
> >  
> > -The ``F`` and ``f`` specifiers are for printing function pointers,
> > -for example, f->func, &gettimeofday. They have the same result as
> > -``S`` and ``s`` specifiers. But they do an extra conversion on
> > -ia64, ppc64 and parisc64 architectures where the function pointers
> > -are actually function descriptors.
> > +The ``F`` and ``f`` specifiers are for printing function pointers, for
> > +example, ``f->func``, ``&gettimeofday``. They have the same result as ``S``
> > +and ``s`` specifiers. But they do an extra conversion on ia64, ppc64 and
> > +parisc64 architectures where the function pointers are actually function
> > +descriptors.
> >  
> >  The ``S`` and ``s`` specifiers can be used for printing symbols
> > -from direct addresses, for example, __builtin_return_address(0),
> > -(void *)regs->ip. They result in the symbol name with (``S``) or
> > +from direct addresses, for example, ``__builtin_return_address(0)``,
> > +``(void *)regs->ip``. They result in the symbol name with (``S``) or
> >  without (``s``) offsets. If KALLSYMS are disabled then the symbol
> >  address is printed instead.
> >  
> >  The ``B`` specifier results in the symbol name with offsets and should be
> >  used when printing stack backtraces. The specifier takes into
> >  consideration the effect of compiler optimisations which may occur
> > -when tail-call``s are used and marked with the noreturn GCC attribute.
> > +when tail-call's are used and marked with the ``noreturn`` GCC attribute.
> >  
> >  Examples::
> >  
> >  	printk("Going to call: %pF\n", gettimeofday);
> >  	printk("Going to call: %pF\n", p->func);
> >  	printk("%s: called from %pS\n", __func__, (void *)_RET_IP_);
> > -	printk("%s: called from %pS\n", __func__,
> > -				(void *)__builtin_return_address(0));
> > +	printk("%s: called from %pS\n", __func__, (void *)__builtin_return_address(0));
> >  	printk("Faulted at %pS\n", (void *)regs->ip);
> >  	printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack);
> >  
> >  Kernel Pointers
> > -===============
> > +---------------
> >  
> >  ::
> >  
> >  	%pK	01234567 or 0123456789abcdef
> >  
> >  For printing kernel pointers which should be hidden from unprivileged
> > -users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see
> > -Documentation/sysctl/kernel.txt for more details.
> > +users. The behaviour of ``%pK`` depends on the ``kptr_restrict`` sysctl -
> > +see ``Documentation/sysctl/kernel.txt`` for more details.
> >  
> >  Unmodified Addresses
> > -====================
> > +--------------------
> >  
> >  ::
> >  
> >  	%px	01234567 or 0123456789abcdef
> >  
> > -For printing pointers when you _really_ want to print the address. Please
> > +For printing pointers when you *really* want to print the address. Please
> >  consider whether or not you are leaking sensitive information about the
> > -Kernel layout in memory before printing pointers with %px. %px is
> > -functionally equivalent to %lx. %px is preferred to %lx because it is more
> > -uniquely grep'able. If, in the future, we need to modify the way the Kernel
> > -handles printing pointers it will be nice to be able to find the call
> > -sites.
> > +kernel memory layout before printing pointers with ``%px``. ``%px`` is
> > +functionally equivalent to ``%lx`` (or ``%lu``). ``%px``, however, is
> > +preferable because it is more uniquely grep'able. If, in the future, we need
> > +to modify the way the Kernel handles printing pointers we will be better
> > +equipped to find the call sites.
> >  
> >  Struct Resources
> > -================
> > +----------------
> >  
> >  ::
> >  
> > @@ -132,12 +166,13 @@ Struct Resources
> >  	%pR	[mem 0x60000000-0x6fffffff pref] or
> >  		[mem 0x0000000060000000-0x000000006fffffff pref]
> >  
> > -For printing struct resources. The ``R`` and ``r`` specifiers result in a
> > +For printing ``struct resources``. The ``R`` and ``r`` specifiers result in a
> >  printed resource with (``R``) or without (``r``) a decoded flags member.
> > +
> >  Passed by reference.
> >  
> > -Physical addresses types ``phys_addr_t``
> > -========================================
> > +Physical Address Types ``phys_addr_t``
> > +--------------------------------------
> >  
> >  ::
> >  
> > @@ -145,20 +180,24 @@ Physical addresses types ``phys_addr_t``
> >  
> >  For printing a ``phys_addr_t`` type (and its derivatives, such as
> >  ``resource_size_t``) which can vary based on build options, regardless of
> > -the width of the CPU data path. Passed by reference.
> > +the width of the CPU data path.
> > +
> > +Passed by reference.
> >  
> > -DMA addresses types ``dma_addr_t``
> > -==================================
> > +DMA Address Types ``dma_addr_t``
> > +--------------------------------
> >  
> >  ::
> >  
> >  	%pad	0x01234567 or 0x0123456789abcdef
> >  
> >  For printing a ``dma_addr_t`` type which can vary based on build options,
> > -regardless of the width of the CPU data path. Passed by reference.
> > +regardless of the width of the CPU data path.
> >  
> > -Raw buffer as an escaped string
> > -===============================
> > +Passed by reference.
> > +
> > +Raw Buffer as an Escaped String
> > +-------------------------------
> >  
> >  ::
> >  
> > @@ -168,7 +207,7 @@ For printing raw buffer as an escaped string. For the following buffer::
> >  
> >  		1b 62 20 5c 43 07 22 90 0d 5d
> >  
> > -few examples show how the conversion would be done (the result string
> > +A few examples show how the conversion would be done (the result string
> >  without surrounding quotes)::
> >  
> >  		%*pE		"\eb \C\a"\220\r]"
> > @@ -194,8 +233,8 @@ printing SSIDs.
> >  
> >  If field width is omitted the 1 byte only will be escaped.
> 
>                              then
> I think...

Ha ha, I was borderline with this change when doing this patch. It may
not appear so but I did try to do the minimal amount of changes while
improving correctness. I appreciate your comments since hopefully I can
better make these judgment calls next time.

Will change as suggested.

> >  
> > -Raw buffer as a hex string
> > -==========================
> > +Raw Buffer as a Hex String
> > +--------------------------
> >  
> >  ::
> >  
> > @@ -205,11 +244,11 @@ Raw buffer as a hex string
> >  	%*phN	000102 ... 3f
> >  
> >  For printing a small buffers (up to 64 bytes long) as a hex string with
> > -certain separator. For the larger buffers consider to use
> > +certain separator. For the larger buffers consider using
> >  :c:func:`print_hex_dump`.
> >  
> > -MAC/FDDI addresses
> > -==================
> > +MAC/FDDI Addresses
> > +------------------
> >  
> >  ::
> >  
> > @@ -233,8 +272,8 @@ of Bluetooth addresses which are in the little endian order.
> >  
> >  Passed by reference.
> >  
> > -IPv4 addresses
> > -==============
> > +IPv4 Addresses
> > +--------------
> >  
> >  ::
> >  
> > @@ -252,8 +291,8 @@ no specifier is provided the default network/big endian order is used.
> >  
> >  Passed by reference.
> >  
> > -IPv6 addresses
> > -==============
> > +IPv6 Addresses
> > +--------------
> >  
> >  ::
> >  
> > @@ -271,8 +310,8 @@ http://tools.ietf.org/html/rfc5952
> >  
> >  Passed by reference.
> >  
> > -IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
> > -=========================================================
> > +IPv4/IPv6 Addresses (generic, with port, flowinfo or scope)
> > +---------------------------------------------------------------
> 
> I prefer the additional (Oxford) comma.
> and why is the --- line longer than the header?

I had to look up Oxford comma. For the record, with Oxford comma would
be 

> > +IPv4/IPv6 Addresses (generic, with port, flowinfo, or scope)

After learning what that was I re investigated this one. I am now
leaning towards thinking the original is even better, although not
grammatically correct it better describes the code. 'or' is definitely
wrong because multiple [pfs] are allowed.

Will revert to original (and fix underscore, sloppy work :( )

> >  ::
> >  
> > @@ -282,8 +321,8 @@ IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
> >  	%pISpc	1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345
> >  	%p[Ii]S[pfschnbl]
> >  
> > -For printing an IP address without the need to distinguish whether it``s
> > -of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``,
> > +For printing an IP address without the need to distinguish whether it's
> > +of type AF_INET or AF_INET6. A pointer to a valid ``struct sockaddr``,
> >  specified through ``IS`` or ``iS``, can be passed to this format specifier.
> >  
> >  The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
> > @@ -308,8 +347,8 @@ Further examples::
> >  	%pISsc		1.2.3.4		or [1:2:3:4:5:6:7:8]%1234567890
> >  	%pISpfc		1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345/123456789
> >  
> > -UUID/GUID addresses
> > -===================
> > +UUID/GUID Addresses
> > +-------------------
> >  
> >  ::
> >  
> > @@ -318,18 +357,18 @@ UUID/GUID addresses
> >  	%pUl	03020100-0504-0706-0809-0a0b0c0e0e0f
> >  	%pUL	03020100-0504-0706-0809-0A0B0C0E0E0F
> >  
> > -For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L',
> > -'b' and 'B' specifiers are used to specify a little endian order in
> > -lower ('l') or upper case ('L') hex characters - and big endian order
> > -in lower ('b') or upper case ('B') hex characters.
> > +For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``,
> > +``b`` and ``B`` specifiers are used to specify a little endian order in
> > +lower (``l``) or upper case (``L``) hex digits - and big endian order
> > +in lower (``b``) or upper case (``B``) hex digits.
> >  
> >  Where no additional specifiers are used the default big endian
> > -order with lower case hex characters will be printed.
> > +order with lower case hex digits will be printed.
> 
> digits could imply base 10. but no big deal.

Are you sure about this? I was under the impression that when
representing a number the character set used are refereed to as 'digits'
irrespective of base.

hexadecimal digit
octal digit
digit (assumed base 10)

Open to correction though.

> >  
> >  Passed by reference.
> >  
> > -dentry names
> > -============
> > +Dentry Names
> > +------------
> >  
> >  ::
> >  
> > @@ -343,24 +382,24 @@ equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd<n>`` prints
> >  
> >  Passed by reference.
> >  
> > -block_device names
> > -==================
> > +block_device Names
> > +------------------
> >  
> >  ::
> >  
> >  	%pg	sda, sda1 or loop0p1
> >  
> > -For printing name of block_device pointers.
> > +For printing name of ``block_device`` pointers.
> >  
> >  struct va_format
> > -================
> > +----------------
> >  
> >  ::
> >  
> >  	%pV
> >  
> > -For printing struct va_format structures. These contain a format string
> > -and va_list as follows::
> > +For printing ``struct va_format`` structures. These contain a format string
> > +and ``va_list`` as follows::
> >  
> >  	struct va_format {
> >  		const char *fmt;
> > @@ -370,36 +409,33 @@ and va_list as follows::
> >  Implements a "recursive vsnprintf".
> >  
> >  Do not use this feature without some mechanism to verify the
> > -correctness of the format string and va_list arguments.
> > +correctness of the format string and ``va_list`` arguments.
> >  
> >  Passed by reference.
> >  
> >  kobjects
> > -========
> > -
> > +--------
> > +	
> >  ::
> >  
> > -	%pO
> > +	%pOF[fnpPcCF]
> >  
> > -	Base specifier for kobject based structs. Must be followed with
> > -	character for specific type of kobject as listed below:
> >  
> > -	Device tree nodes:
> > +For printing kobject based structs (device nodes). Default behaviour is
> > +equivalent to ``%pOFf``.
> >  
> > -	%pOF[fnpPcCF]
> > +	- ``f`` device node full_name
> > +	- ``n`` device node name
> > +	- ``p`` device node phandle
> > +	- ``P`` device node path spec (name + @unit)
> > +	- ``F`` device node flags
> > +	- ``c`` major compatible string
> > +	- ``C`` full compatible string
> >  
> > -	For printing device tree nodes. The optional arguments are:
> > -	    f device node full_name
> > -	    n device node name
> > -	    p device node phandle
> > -	    P device node path spec (name + @unit)
> > -	    F device node flags
> > -	    c major compatible string
> > -	    C full compatible string
> > -	Without any arguments prints full_name (same as %pOFf)
> > -	The separator when using multiple arguments is ':'
> > +The separator when using multiple arguments is ``:``
> >  
> > -	Examples:
> > +Examples:
> > +::
> >  
> >  	%pOF	/foo/bar@0			- Node full name
> >  	%pOFf	/foo/bar@0			- Same as above
> > @@ -412,11 +448,10 @@ kobjects
> >  							P - Populated
> >  							B - Populated bus
> >  
> > -	Passed by reference.
> > -
> > +Passed by reference.
> >  
> >  struct clk
> > -==========
> > +----------
> >  
> >  ::
> >  
> > @@ -424,14 +459,14 @@ struct clk
> >  	%pCn	pll1
> >  	%pCr	1560000000
> >  
> > -For printing struct clk structures. ``%pC`` and ``%pCn`` print the name
> > +For printing ``struct clk structures``. ``%pC`` and ``%pCn`` print the name
> >  (Common Clock Framework) or address (legacy clock framework) of the
> >  structure; ``%pCr`` prints the current clock rate.
> >  
> >  Passed by reference.
> >  
> > -bitmap and its derivatives such as cpumask and nodemask
> > -=======================================================
> > +Bitmap and its Derivatives (such as cpumask and nodemask)
> > +---------------------------------------------------------
> >  
> >  ::
> >  
> > @@ -439,13 +474,13 @@ bitmap and its derivatives such as cpumask and nodemask
> >  	%*pbl	0,3-6,8-10
> >  
> >  For printing bitmap and its derivatives such as cpumask and nodemask,
> > -``%*pb`` output 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.
> > +``%*pb`` outputs the bitmap with field width as the number of bits and ``%*pbl``
> > +outputs the bitmap as range list with field width as the number of bits.
> >  
> >  Passed by reference.
> >  
> > -Flags bitfields such as page flags, gfp_flags
> > -=============================================
> > +Flags Bitfields (such as page flags, gfp_flags)
> > +-----------------------------------------------
> >  
> >  ::
> >  
> > @@ -459,25 +494,27 @@ character. Currently supported are [p]age flags, [v]ma_flags (both
> >  expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag
> >  names and print order depends on the particular	type.
> >  
> > -Note that this format should not be used directly in :c:func:`TP_printk()` part
> > -of a tracepoint. Instead, use the ``show_*_flags()`` functions from
> > -<trace/events/mmflags.h>.
> > +Note that this format should not be used directly in the
> > +:c:func:`TP_printk()` part of a tracepoint. Instead, use the
> > +``show_*_flags()`` functions from ``<trace/events/mmflags.h>``. 
> >  
> >  Passed by reference.
> >  
> > -Network device features
> > -=======================
> > +Network Device Features
> > +-----------------------
> >  
> >  ::
> >  
> >  	%pNF	0x000000000000c000
> >  
> > -For printing netdev_features_t.
> > +For printing ``netdev_features_t``.
> >  
> >  Passed by reference.
> >  
> > -If you add other ``%p`` extensions, please extend lib/test_printf.c with
> > -one or more test cases, if at all feasible.
> > +Thanks
> > +======
> >  
> > +If you add other ``%p`` extensions, please extend ``lib/test_printf.c``
> > +with one or more test cases, if at all feasible.
> >  
> >  Thank you for your cooperation and attention.
> > diff --git a/lib/vsprintf.c b/lib/vsprintf.c
> > index 01c3957b2de6..f9247b78e8ef 100644
> > --- a/lib/vsprintf.c
> > +++ b/lib/vsprintf.c
> > @@ -1727,115 +1727,73 @@ static char *ptr_to_id(char *buf, char *end, void *ptr, struct printf_spec spec)
> >  	return number(buf, end, hashval, spec);
> >  }
> >  
> > +/**
> > + * DOC: Extended Format Pointer Specifiers
> > + *
> > + * Briefly we handle the following extensions:
> > + *
> > + * - ``F`` - For symbolic function descriptor pointers with offset.
> > + * - ``f`` - For simple symbolic function names without offset.
> > + *
> > + * - ``S`` - For symbolic direct pointers with offset.
> > + * - ``s`` - For symbolic direct pointers without offset.
> > + * - ``[FfSs]R`` - As above with ``__builtin_extract_return_addr()`` translation.
> > + * - ``B`` - For backtraced symbolic direct pointers with offset.
> > + * - ``R`` - For decoded struct resource, e.g., [mem 0x0-0x1f 64bit pref].
> > + * - ``r`` - For raw struct resource, e.g., [mem 0x0-0x1f flags 0x201].
> > + * - ``b[l]`` - For a bitmap, the number of bits is determined by the field
> > + *   width which must be explicitly specified either as part of the format
> > + *   string ``32b[l]`` or through ``*b[l]``, ``[l]`` selects range-list format
> > + *   instead of hex format.
> > + * - ``M`` - For a 6-byte MAC address, it prints the address in the usual
> > + *   colon-separated hex notation.
> > + * - ``m`` - For a 6-byte MAC address, it prints the hex address without colons.
> > + * - ``MF`` - For a 6-byte MAC FDDI address, it prints the address with a
> > + *   dash-separated hex notation.
> > + * - ``[mM]R`` - For a 6-byte MAC address, Reverse order (Bluetooth).
> > + * - ``I[46]`` - For IPv4/IPv6 addresses printed in the usual way.
> > + * - ``I[S][pfs]`` - For generic IPv4/IPv6 address (struct sockaddr *) that falls
> > + *   back to ``[4]`` or ``[6]`` and is able to print port ``[p]``,
> > + *   flowinfo ``[f]``, scope ``[s]``.
> > + * - ``i[46]`` - For 'raw' IPv4/IPv6 addresses IPv6 omits the colons (01020304...0f)
> > + *   IPv4 uses dot-separated decimal with leading 0's (010.123.045.006).
> > + * - ``i[S][pfs]`` - For generic IPv4/IPv6 address (struct sockaddr *) that falls back
> > + *   to ``[4]`` or ``[6]`` (``[pfs]`` as above).
> > + * - ``[Ii][4S][hnbl]`` - For IPv4 addresses in host, network, big or little endian order.
> > + * - ``I[6S]c`` - For IPv6 addresses printed as per http://tools.ietf.org/html/rfc5952.
> > + * - ``E[achnops]`` - For an escaped buffer.
> > + * - ``U`` - For a 16 byte UUID/GUID.
> > + * - ``V`` - For a ``struct va_format`` which contains a format ``string *``
> > + *   and ``va_list *``.
> > + * - ``K`` -  For a kernel pointer that should be hidden from unprivileged users.
> > + * - ``NF`` - For a ``netdev_features_t``.
> > + * - ``h[CDN]`` - For a variable-length buffer.
> > + * - ``a[pd]`` - For address types ``[p] phys_addr_t``, ``[d] dma_addr_t`` and
> > + *   derivatives.
> > + * - ``d[234]`` - For a dentry name (optionally 2-4 last components).
> > + * - ``D[234]`` - Same as 'd' but for a struct file.
> > + * - ``g`` - For ``block_device`` name (gendisk + partition number).
> > + * - ``C[n]`` - For a clock, it prints the name (Common Clock Framework) or
> > + *   address (legacy clock framework) of the clock. ``[n]`` is optional.
> > + * - ``Cr`` - For a clock, it prints the current rate of the clock.
> > + * - ``G`` - For flags to be printed as a collection of symbolic strings that
> > + *   would construct the specific value.
> > + * - ``O`` - For a kobject based struct (device node).
> > + * - ``x`` - For printing the address. Equivalent to ``%lx``.
> > + */
> > +
> >  /*
> >   * Show a '%p' thing.  A kernel extension is that the '%p' is followed
> >   * by an extra set of alphanumeric characters that are extended format
> >   * specifiers.
> >   *
> > + * Please see Documentation/printk-formats.rst for fuller description
> > + * of specifier extensions. Also please update this file when making
> 
> "this file" is the file that I am reading?  or could it be "that file"?

Got it.

thanks,
Tobin.