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@xxxxxxxxxx> --- 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@xxxxxxxxxxxxxxx> Intel Finland Oy
Attachment:
signature.asc
Description: PGP signature
