Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752296AbdLFVQ6 (ORCPT ); Wed, 6 Dec 2017 16:16:58 -0500 Received: from out5-smtp.messagingengine.com ([66.111.4.29]:41547 "EHLO out5-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751604AbdLFVQ5 (ORCPT ); Wed, 6 Dec 2017 16:16:57 -0500 X-ME-Sender: Date: Thu, 7 Dec 2017 08:16:51 +1100 From: "Tobin C. Harding" To: Randy Dunlap Cc: Jonathan Corbet , Andrew Murray , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH] doc: convert printk-formats.txt to rst Message-ID: <20171206211651.GD11835@eros> References: <1512524729-16051-1-git-send-email-me@tobin.cc> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Mailer: Mutt 1.5.24 (2015-08-30) User-Agent: Mutt/1.5.24 (2015-08-30) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 26455 Lines: 725 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 > > --- > > > > 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 > > :Author: Andrew Murray > > @@ -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 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 ```` 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`` 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 > > -. > > +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 ````. > > > > 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.