* [PATCH] lib: Documentation: Synchronize %p formatting documentation @ 2015-09-21 9:13 Martin Kletzander 2015-09-21 9:18 ` Andy Shevchenko 0 siblings, 1 reply; 6+ messages in thread From: Martin Kletzander @ 2015-09-21 9:13 UTC (permalink / raw) To: linux-doc Cc: Jonathan Corbet, Andrew Morton, Rasmus Villemoes, Andy Shevchenko, Geert Uytterhoeven, Tetsuo Handa, Stephen Boyd, Tejun Heo, linux-kernel Move all pointer-formatting documentation to one place instead of keeping it in three places with different level of completeness. Signed-off-by: Martin Kletzander <mkletzan@redhat.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 -- 2.5.3 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] lib: Documentation: Synchronize %p formatting documentation 2015-09-21 9:13 [PATCH] lib: Documentation: Synchronize %p formatting documentation Martin Kletzander @ 2015-09-21 9:18 ` Andy Shevchenko 2015-09-21 13:04 ` Martin Kletzander 2015-09-22 18:40 ` Rasmus Villemoes 0 siblings, 2 replies; 6+ messages in thread From: Andy Shevchenko @ 2015-09-21 9:18 UTC (permalink / raw) To: Martin Kletzander, linux-doc Cc: Jonathan Corbet, Andrew Morton, Rasmus Villemoes, Geert Uytterhoeven, Tetsuo Handa, Stephen Boyd, Tejun Heo, linux-kernel 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. > Signed-off-by: Martin Kletzander <mkletzan@redhat.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@linux.intel.com> Intel Finland Oy ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] lib: Documentation: Synchronize %p formatting documentation 2015-09-21 9:18 ` Andy Shevchenko @ 2015-09-21 13:04 ` Martin Kletzander 2015-09-22 18:40 ` Rasmus Villemoes 1 sibling, 0 replies; 6+ messages in thread From: Martin Kletzander @ 2015-09-21 13:04 UTC (permalink / raw) To: Andy Shevchenko Cc: linux-doc, Jonathan Corbet, Andrew Morton, Rasmus Villemoes, Geert Uytterhoeven, Tetsuo Handa, Stephen Boyd, Tejun Heo, linux-kernel [-- Attachment #1: Type: text/plain, Size: 10770 bytes --] 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@redhat.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@linux.intel.com> >Intel Finland Oy [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 819 bytes --] ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] lib: Documentation: Synchronize %p formatting documentation 2015-09-21 9:18 ` Andy Shevchenko 2015-09-21 13:04 ` Martin Kletzander @ 2015-09-22 18:40 ` Rasmus Villemoes 2015-09-22 18:48 ` Martin Kletzander 2015-09-23 8:52 ` Andy Shevchenko 1 sibling, 2 replies; 6+ messages in thread From: Rasmus Villemoes @ 2015-09-22 18:40 UTC (permalink / raw) To: Andy Shevchenko Cc: Martin Kletzander, linux-doc, Jonathan Corbet, Andrew Morton, Geert Uytterhoeven, Tetsuo Handa, Stephen Boyd, Tejun Heo, linux-kernel On Mon, Sep 21 2015, Andy Shevchenko <andriy.shevchenko@linux.intel.com> 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've had a patch titled "vsnprintf: collect documentation in one place" lying in a misc_printf branch for a while now, so I certainly like this. > 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. I'd really prefer actually collecting it in that single place, under Documentation/, but I guess eliminating one redundant copy is better than nothing... Rasmus ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] lib: Documentation: Synchronize %p formatting documentation 2015-09-22 18:40 ` Rasmus Villemoes @ 2015-09-22 18:48 ` Martin Kletzander 2015-09-23 8:52 ` Andy Shevchenko 1 sibling, 0 replies; 6+ messages in thread From: Martin Kletzander @ 2015-09-22 18:48 UTC (permalink / raw) To: Rasmus Villemoes Cc: Andy Shevchenko, linux-doc, Jonathan Corbet, Andrew Morton, Geert Uytterhoeven, Tetsuo Handa, Stephen Boyd, Tejun Heo, linux-kernel [-- Attachment #1: Type: text/plain, Size: 1072 bytes --] On Tue, Sep 22, 2015 at 08:40:03PM +0200, Rasmus Villemoes wrote: >On Mon, Sep 21 2015, Andy Shevchenko <andriy.shevchenko@linux.intel.com> 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've had a patch titled "vsnprintf: collect documentation in one place" >lying in a misc_printf branch for a while now, so I certainly like this. > >> 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. > >I'd really prefer actually collecting it in that single place, under >Documentation/, but I guess eliminating one redundant copy is better >than nothing... > And the second copy (in the code) will be way shorter, simply serving as a hint as opposed to the full blown documentation. I just need to go through each modifier to make sure all of them are mentioned in both places. I'll try to find some spare time tomorrow. >Rasmus [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 819 bytes --] ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] lib: Documentation: Synchronize %p formatting documentation 2015-09-22 18:40 ` Rasmus Villemoes 2015-09-22 18:48 ` Martin Kletzander @ 2015-09-23 8:52 ` Andy Shevchenko 1 sibling, 0 replies; 6+ messages in thread From: Andy Shevchenko @ 2015-09-23 8:52 UTC (permalink / raw) To: Rasmus Villemoes Cc: Martin Kletzander, linux-doc, Jonathan Corbet, Andrew Morton, Geert Uytterhoeven, Tetsuo Handa, Stephen Boyd, Tejun Heo, linux-kernel On Tue, 2015-09-22 at 20:40 +0200, Rasmus Villemoes wrote: > On Mon, Sep 21 2015, Andy Shevchenko < > andriy.shevchenko@linux.intel.com> 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've had a patch titled "vsnprintf: collect documentation in one > place" > lying in a misc_printf branch for a while now, so I certainly like > this. > > > 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. > > I'd really prefer actually collecting it in that single place, under > Documentation/, but I guess eliminating one redundant copy is better > than nothing... Agree. -- Andy Shevchenko <andriy.shevchenko@linux.intel.com> Intel Finland Oy ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2015-09-23 8:52 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2015-09-21 9:13 [PATCH] lib: Documentation: Synchronize %p formatting documentation Martin Kletzander 2015-09-21 9:18 ` Andy Shevchenko 2015-09-21 13:04 ` Martin Kletzander 2015-09-22 18:40 ` Rasmus Villemoes 2015-09-22 18:48 ` Martin Kletzander 2015-09-23 8:52 ` Andy Shevchenko
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).