Re: [PATCH] doc: convert printk-formats.txt to rst
From: Tobin C. Harding
Date: Wed Dec 06 2017 - 17:11:17 EST
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@xxxxxxxx>
> > ---
> >
> > 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@xxxxxxxxxxxxx>
> > :Author: Andrew Murray <amurray@xxxxxxxxxxxxxx>
> > @@ -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.