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

From: Tobin C. Harding
Date: Wed Dec 06 2017 - 16:17:01 EST

Next message: Rob Herring: "Re: [PATCH 4/8] dt-bindings: power: supply: axp20x: add AXP813 battery DT binding"
Previous message: SF Markus Elfring: "[PATCH 3/3] tty/serial/ucc_uart: Fix a typo in a comment line"
In reply to: Randy Dunlap: "Re: [PATCH] doc: convert printk-formats.txt to rst"
Next in thread: Randy Dunlap: "Re: [PATCH] doc: convert printk-formats.txt to rst"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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@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...

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.

Next message: Rob Herring: "Re: [PATCH 4/8] dt-bindings: power: supply: axp20x: add AXP813 battery DT binding"
Previous message: SF Markus Elfring: "[PATCH 3/3] tty/serial/ucc_uart: Fix a typo in a comment line"
In reply to: Randy Dunlap: "Re: [PATCH] doc: convert printk-formats.txt to rst"
Next in thread: Randy Dunlap: "Re: [PATCH] doc: convert printk-formats.txt to rst"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]