Re: [PATCH v2] lib: Documentation: Synchronize %p formatting documentation

Andy Shevchenko
2015-09-24T08:16:52Z

On Thu, 2015-09-24 at 10:08 +0200, Martin Kletzander wrote:
> Move all pointer-formatting documentation to one place in the code
> and
> one place in the documentation instead of keeping it in three places
> with different level of completeness. Documentation/printk
> -formats.txt
> has detailed information about each modifier, docstring above
> pointer()
> has short descriptions of them (as that is the function dealing with
> %p)
> and docstring above vsprintf() is removed as redundant. Both
> docstrings
> in the code that were modified are updated with a reminder of
> updating
> the documentation upon any further change.
>

Good for me!

Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

> Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
> ---
> Documentation/printk-formats.txt | 27 +++++++++++++++++++++++++
> lib/vsprintf.c | 43 ++++++++----------------------
> ----------
> 2 files changed, 35 insertions(+), 35 deletions(-)
>
> diff --git a/Documentation/printk-formats.txt b/Documentation/printk
> -formats.txt
> index 2ec6d84f391c..c85e27264a2b 100644
> --- a/Documentation/printk-formats.txt
> +++ b/Documentation/printk-formats.txt
> @@ -119,6 +119,7 @@ Raw buffer as an escaped string:
> If field width is omitted the 1 byte only will be escaped.
>
> Raw buffer as a hex string:
> +
> %*ph 00 01 02 ... 3f
> %*phC 00:01:02: ... :3f
> %*phD 00-01-02- ... -3f
> @@ -234,6 +235,7 @@ UUID/GUID addresses:
> Passed by reference.
>
> dentry names:
> +
> %pd{,2,3,4}
> %pD{,2,3,4}
>
> @@ -264,6 +266,8 @@ struct va_format:
> va_list *va;
> };
>
> + Implements a "recursive vsnprintf".
> +
> Do not use this feature without some mechanism to verify the
> correctness of the format string and va_list arguments.
>
> @@ -292,6 +296,29 @@ bitmap and its derivatives such as cpumask and
> nodemask:
>
> Passed by reference.
>
> +Network device features:
> +
> + %pNF 0x000000000000c000
> +
> + For printing netdev_features_t.
> +
> + Passed by reference.
> +
> +Command from struct task_struct
> +
> + %pT ls
> +
> + For printing executable name excluding path from struct
> + task_struct.
> +
> + Passed by reference.
> +
> +Ignored argument:
> +
> + %pn
> +
> + The argument passed will be ignored.
> +
> Thank you for your cooperation and attention.
>
>
> diff --git a/lib/vsprintf.c b/lib/vsprintf.c
> index becd87facf48..9ab68775b840 100644
> --- a/lib/vsprintf.c
> +++ b/lib/vsprintf.c
> @@ -1463,7 +1463,10 @@ int kptr_restrict __read_mostly;
> * - 'Cn' For a clock, it prints the name (Common Clock Framework)
> or address
> * (legacy clock framework) of the clock
> * - 'Cr' For a clock, it prints the current rate of the clock
> - * - 'T' task_struct->comm
> + * - 'T' For task_struct->comm
> + * - 'n' For ignored argument
> + *
> + * ** Please update Documentation/printk-formats.txt when making
> changes **
> *
> * Note: The difference between 'S' and 'F' is that on ia64 and
> ppc64
> * function pointers are really function descriptors, which contain
> a
> @@ -1829,41 +1832,11 @@ qualifier:
> * @fmt: The format string to use
> * @args: Arguments for the format string
> *
> - * This function follows C99 vsnprintf, but has some extensions:
> - * %pS output the name of a text symbol with offset
> - * %ps output the name of a text symbol without offset
> - * %pF output the name of a function pointer with its offset
> - * %pf output the name of a function pointer without its offset
> - * %pB output the name of a backtrace symbol with its offset
> - * %pR output the address range in a struct resource with decoded
> flags
> - * %pr output the address range in a struct resource with raw flags
> - * %pb output the bitmap with field width as the number of bits
> - * %pbl output the bitmap as range list with field width as the
> number of bits
> - * %pM output a 6-byte MAC address with colons
> - * %pMR output a 6-byte MAC address with colons in reversed order
> - * %pMF output a 6-byte MAC address with dashes
> - * %pm output a 6-byte MAC address without colons
> - * %pmR output a 6-byte MAC address without colons in reversed order
> - * %pI4 print an IPv4 address without leading zeros
> - * %pi4 print an IPv4 address with leading zeros
> - * %pI6 print an IPv6 address with colons
> - * %pi6 print an IPv6 address without colons
> - * %pI6c print an IPv6 address as specified by RFC 5952
> - * %pIS depending on sa_family of 'struct sockaddr *' print
> IPv4/IPv6 address
> - * %piS depending on sa_family of 'struct sockaddr *' print
> IPv4/IPv6 address
> - * %pU[bBlL] print a UUID/GUID in big or little endian using lower
> or upper
> - * case.
> - * %*pE[achnops] print an escaped buffer
> - * %*ph[CDN] a variable-length hex string with a separator (supports
> up to 64
> - * bytes of the input)
> - * %pC output the name (Common Clock Framework) or address (legacy
> clock
> - * framework) of a clock
> - * %pCn output the name (Common Clock Framework) or address (legacy
> clock
> - * framework) of a clock
> - * %pCr output the current rate of a clock
> - * %n is ignored
> + * This function follows C99 vsnprintf, but has some extensions.
> See
> + * pointer() or Documentation/printk-formats.txt for all format
> + * specifiers.
> *
> - * ** Please update Documentation/printk-formats.txt when making
> changes **
> + * ** Please update the documentation when making changes **
> *
> * The return value is the number of characters which would
> * be generated for the given input, excluding the trailing

--
Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Intel Finland Oy