Date:	Mon, 21 Sep 2015 15:04:35 +0200
From:	Martin Kletzander <mkletzan@...hat.com>
To:	Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Cc:	linux-doc@...r.kernel.org, Jonathan Corbet <corbet@....net>,
	Andrew Morton <akpm@...ux-foundation.org>,
	Rasmus Villemoes <linux@...musvillemoes.dk>,
	Geert Uytterhoeven <geert+renesas@...der.be>,
	Tetsuo Handa <penguin-kernel@...ove.sakura.ne.jp>,
	Stephen Boyd <sboyd@...eaurora.org>, Tejun Heo <tj@...nel.org>,
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH] lib: Documentation: Synchronize %p formatting
 documentation

On Mon, Sep 21, 2015 at 12:18:07PM +0300, Andy Shevchenko wrote:
>On Mon, 2015-09-21 at 11:13 +0200, Martin Kletzander wrote:
>> Move all pointer-formatting documentation to one place instead of
>> keeping it in three places with different level of completeness.
>>
>
>I think we still need at least one in the code. I, for example, often
>read it from the actual c-file, not from documentation.
>
>So, good change for printk-formats.txt, but not okay for me for the
>vsprintf.c.
>

OK, I agree with that.  Since pointer() is the function handling
exactly this and the documentation there is rather full, I'll go with
that as a place where to also leave it.

I'll add synchronization reminders to all three places in order to
hopefully keep it as clean as possible.  Should I also add one to
Documentation/SubmitChecklist or is that too excessive?

>> Signed-off-by: Martin Kletzander <mkletzan@...hat.com>
>> ---
>>  Documentation/printk-formats.txt |  27 +++++++++
>>  lib/vsprintf.c                   | 123 ++---------------------------
>> ----------
>>  2 files changed, 32 insertions(+), 118 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..6e358dc81ef0 100644
>> --- a/lib/vsprintf.c
>> +++ b/lib/vsprintf.c
>> @@ -1383,91 +1383,9 @@ int kptr_restrict __read_mostly;
>>   * by an extra set of alphanumeric characters that are extended
>> format
>>   * specifiers.
>>   *
>> - * Right now we handle:
>> + * All format specifiers are documented in Documentation/printk
>> -formats.txt.
>>   *
>> - * - '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
>> - *       IPv4 uses dot-separated decimal without leading 0's
>> (1.2.3.4)
>> - *       IPv6 uses colon separated network-order 16 bit hex with
>> leading 0's
>> - *       [S][pfs]
>> - *       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)
>> - *       [S][pfs]
>> - *       Generic IPv4/IPv6 address (struct sockaddr *) that falls
>> back to
>> - *       [4] or [6] and is able to print port [p], flowinfo [f],
>> scope [s]
>> - * - '[Ii][4S][hnbl]' IPv4 addresses in host, network, big or little
>> endian order
>> - * - 'I[6S]c' for IPv6 addresses printed as specified by
>> - *       http://tools.ietf.org/html/rfc5952
>> - * - 'E[achnops]' For an escaped buffer, where rules are defined by
>> combination
>> - *                of the following flags (see string_escape_mem()
>> for the
>> - *                details):
>> - *                  a - ESCAPE_ANY
>> - *                  c - ESCAPE_SPECIAL
>> - *                  h - ESCAPE_HEX
>> - *                  n - ESCAPE_NULL
>> - *                  o - ESCAPE_OCTAL
>> - *                  p - ESCAPE_NP
>> - *                  s - ESCAPE_SPACE
>> - *                By default ESCAPE_ANY_NP is used.
>> - * - 'U' For a 16 byte UUID/GUID, it prints the UUID/GUID in the
>> form
>> - *       "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
>> - *       Options for %pU are:
>> - *         b big endian lower case hex (default)
>> - *         B big endian UPPER case hex
>> - *         l little endian lower case hex
>> - *         L little endian UPPER case hex
>> - *           big endian output byte order is:
>> - *             [0][1][2][3]-[4][5]-[6][7]-[8][9]
>> -[10][11][12][13][14][15]
>> - *           little endian output byte order is:
>> - *             [3][2][1][0]-[5][4]-[7][6]-[8][9]
>> -[10][11][12][13][14][15]
>> - * - 'V' For a struct va_format which contains a format string * and
>> va_list *,
>> - *       call vsnprintf(->format, *->va_list).
>> - *       Implements a "recursive vsnprintf".
>> - *       Do not use this feature without some mechanism to verify
>> the
>> - *       correctness of the format string and va_list arguments.
>> - * - '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, it prints it as a hex
>> string with
>> - *            a certain separator (' ' by default):
>> - *              C colon
>> - *              D dash
>> - *              N no separator
>> - *            The maximum supported length is 64 bytes of the input.
>> Consider
>> - *            to use print_hex_dump() for the larger input.
>> - * - 'a[pd]' For address types [p] phys_addr_t, [d] dma_addr_t and
>> derivatives
>> - *           (default assumed to be phys_addr_t, passed by
>> reference)
>> - * - 'd[234]' For a dentry name (optionally 2-4 last components)
>> - * - 'D[234]' Same as 'd' but for a struct file
>> - * - 'C' For a clock, it prints the name (Common Clock Framework) or
>> address
>> - *       (legacy clock framework) of the clock
>> - * - '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
>> - *
>> - * Note: The difference between 'S' and 'F' is that on ia64 and
>> ppc64
>> - * function pointers are really function descriptors, which contain
>> a
>> - * pointer to the real address.
>> + * ** Please update the documentation when making changes **
>>   */
>>  static noinline_for_stack
>>  char *pointer(const char *fmt, char *buf, char *end, void *ptr,
>> @@ -1829,41 +1747,10 @@ 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.
>> + * All format specifiers are documented in Documentation/printk
>> -formats.txt.
>>   *
>> - * ** 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@...ux.intel.com>
>Intel Finland Oy

Download attachment "signature.asc" of type "application/pgp-signature" (820 bytes)

Powered by blists - more mailing lists