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:
> 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).
> 
> > - 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...
> 
> >  
> > -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?
> 
> >  
> >  ::
> >  
> > @@ -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.

Another place in the file uses 'hex notation'. I guess we should unify
all usage (within this file at least).

thanks,
Tobin.