Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752177AbdLFWLO (ORCPT ); Wed, 6 Dec 2017 17:11:14 -0500 Received: from out5-smtp.messagingengine.com ([66.111.4.29]:32797 "EHLO out5-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751827AbdLFWLL (ORCPT ); Wed, 6 Dec 2017 17:11:11 -0500 X-ME-Sender: Date: Thu, 7 Dec 2017 09:11:07 +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: <20171206221107.GH11835@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: 15923 Lines: 440 On Wed, Dec 06, 2017 at 10:18:49AM -0800, Randy Dunlap wrote: > 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). > > > - 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... > > > > > -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? > > > > > :: > > > > @@ -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. Another place in the file uses 'hex notation'. I guess we should unify all usage (within this file at least). thanks, Tobin.