Re: [PATCH 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Fri, Dec 08, 2017 at 09:27:54AM +1100, Tobin C. Harding wrote:
[snip]

New comments have come in from Kees Cook in thread for previous
version. Please drop this set so Kees's suggestions can be implemented.

thanks,
Tobin.

Re: [PATCH 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

On Fri, Dec 08, 2017 at 09:27:54AM +1100, Tobin C. Harding wrote:
[snip]

New comments have come in from Kees Cook in thread for previous
version. Please drop this set so Kees's suggestions can be implemented.

thanks,
Tobin.

[PATCH 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

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

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX

 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - 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

Signed-off-by: Tobin C. Harding 
---
 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 268 +++--
 lib/vsprintf.c | 155 +---
 4 files changed, 196 insertions(+), 230 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7023bfaec21c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -346,8 +346,6 @@ prctl/
- directory with info on the priveledge control subsystem
 preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
-   - how to get printk format specifiers right
 process/
- how to work with the mainline kernel development process.
 pps/
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d5bbe035316d..2f9df634a726 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -21,6 +21,7 @@ Core utilities
flexible-arrays
librs
genalloc
+   printk-formats
 
 Interfaces for kernel debugging
 ===
diff --git a/Documentation/printk-formats.txt 
b/Documentation/core-api/printk-formats.rst
similarity index 59%
rename from Documentation/printk-formats.txt
rename to Documentation/core-api/printk-formats.rst
index aa0a776c817a..f1262a617dec 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
 :Author: Randy Dunlap 
 :Author: Andrew Murray 
 
+
 Integer types
 =
 
@@ -25,39 +26,49 @@ Integer types
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.
+
+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);
 
-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
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. 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
+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 abcdef12
 
-Symbols/Function Pointers
-=
+Pointers printed without a specifier extension (i.e unadorned %p) are
+hashed to prevent leaking information about the kernel memory layout. This
+has the added benefit of providing a unique identifier. On 64-bit machines
+the first 32 bits are zeroed. If you *really* want the address see %px
+below.
+

[PATCH 1/3] doc: convert printk-formats.txt to rst

[Tobin C. Harding]

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

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX

 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - 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

Signed-off-by: Tobin C. Harding 
---
 Documentation/00-INDEX |   2 -
 Documentation/core-api/index.rst   |   1 +
 .../printk-formats.rst}| 268 +++--
 lib/vsprintf.c | 155 +---
 4 files changed, 196 insertions(+), 230 deletions(-)
 rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (59%)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..7023bfaec21c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -346,8 +346,6 @@ prctl/
- directory with info on the priveledge control subsystem
 preempt-locking.txt
- info on locking under a preemptive kernel.
-printk-formats.txt
-   - how to get printk format specifiers right
 process/
- how to work with the mainline kernel development process.
 pps/
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d5bbe035316d..2f9df634a726 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -21,6 +21,7 @@ Core utilities
flexible-arrays
librs
genalloc
+   printk-formats
 
 Interfaces for kernel debugging
 ===
diff --git a/Documentation/printk-formats.txt 
b/Documentation/core-api/printk-formats.rst
similarity index 59%
rename from Documentation/printk-formats.txt
rename to Documentation/core-api/printk-formats.rst
index aa0a776c817a..f1262a617dec 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/core-api/printk-formats.rst
@@ -5,6 +5,7 @@ How to get printk format specifiers right
 :Author: Randy Dunlap 
 :Author: Andrew Murray 
 
+
 Integer types
 =
 
@@ -25,39 +26,49 @@ Integer types
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.
+
+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);
 
-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
-point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
+The kernel's printf does not support %n. Floating point formats (%e, %f,
+%g, %a) are also not recognized, for obvious reasons. 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
+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 abcdef12
 
-Symbols/Function Pointers
-=
+Pointers printed without a specifier extension (i.e unadorned %p) are
+hashed to prevent leaking information about the kernel memory layout. This
+has the added benefit of providing a unique identifier. On 64-bit machines
+the first 32 bits are zeroed. If you *really* want the address see %px
+below.
+
+Symbols/Function pointers
+-
 
 ::
 
@@ -69,22