doc: update printk documentation
Subsystems (2)
v2 cover doc: update printk documentation
This set converts printk-formats.txt -> core-api/printk-formats.rst
We also update the documentation around printing kernel addresses.
For v2 I have attempted to toe the line more in regards to 'make as few changes as possible to complete the conversion'.
This is my first documentation conversion. Please do be hard on this patch series. I'd like to get it _realy_ correct so that future conversions will require less review effort. Also if there are any peculiarities to patching docs (as apposed to C files) please say so.
Thank you for the time already given to reviewing previous versions.
thanks,
Tobin.
v2:
- Remove conversion/inclusion of kernel-docs from lib/vsprintf.c
- Add '<>' around file name (in section 'Thanks').
- Remove a few more double back ticks.
- Remove unnecessary [style] edits.
Tobin C. Harding (3):
doc: convert printk-formats.txt to rst
doc: update kpt_restrict documentation
doc: add documentation on printing kernel addresses
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst} | 271 +++++++++++----------
Documentation/security/self-protection.rst | 15 ++
Documentation/sysctl/kernel.txt | 3 +-
5 files changed, 158 insertions(+), 134 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (57%)Signature · 1 line
2.7.4
PATCH v2 1/3 doc: convert printk-formats.txt to rst
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.
---
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst} | 271 +++++++++++----------
3 files changed, 141 insertions(+), 133 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (57%)Documentation/00-INDEX +0 -2
@@ -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/
Documentation/core-api/index.rst +1 -0
@@ -22,6 +22,7 @@ Core utilities flexible-arrays librs genalloc + printk-formats Interfaces for kernel debugging ===============================
Documentation/core-api/printk-formats.rst renamed from Documentation/printk-formats.txt +140 -131
515 lines not on this page · raw message
Signature · 1 line
2.7.4
PATCH v2 2/3 doc: update kpt_restrict documentation
In reply to Tobin C. HardingRecently the behaviour of printk specifier %pK was changed. The documentation does not currently mirror this.
Update documentation for sysctl kpt_restrict.
--- Documentation/sysctl/kernel.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sysctl/kernel.txt +2 -1
@@ -391,7 +391,8 @@ kptr_restrict: This toggle indicates whether restrictions are placed on exposing kernel addresses via /proc and other interfaces. -When kptr_restrict is set to (0), the default, there are no restrictions. +When kptr_restrict is set to (0), the default, the address is hashed before +printing. (This is the equivalent to %p.) When kptr_restrict is set to (1), kernel pointers printed using the %pK format specifier will be replaced with 0's unless the user has CAP_SYSLOG
Signature · 1 line
2.7.4
Randy Dunlap
reviewerRe: [PATCH v2 2/3] doc: update kpt_restrict documentation
Quoted 15 lines · Tobin C. Harding
Recently the behaviour of printk specifier %pK was changed. The documentation does not currently mirror this.
Update documentation for sysctl
kpt_restrict.Signed-off-by Tobin C. Harding <[email protected]>--- Documentation/sysctl/kernel.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Documentation/sysctl/kernel.txt +0
-0
Documentation/sysctl/kernel.txt kptr_restrict: · line 394
Quoted 5 lines
Documentation/sysctl/kernel.txt +1
-1@@ -391,7 +391,8 @@ kptr_restrict: This toggle indicates whether restrictions are placed on exposing kernel addresses via /proc and other interfaces. -When kptr_restrict is set to (0), the default, there are no restrictions. +When kptr_restrict is set to (0), the default, the address is hashed before
how about:
is set to 0 (the default),
or
is set to (0) [the default],
Quoted 5 lines
Documentation/sysctl/kernel.txt +1
-0+printing. (This is the equivalent to %p.) When kptr_restrict is set to (1), kernel pointers printed using the %pK format specifier will be replaced with 0's unless the user has CAP_SYSLOG
Signature · 1 line
~Randy
PATCH v2 3/3 doc: add documentation on printing kernel addresses
In reply to Tobin C. HardingHashing addresses printed with printk specifier %p was implemented recently. During development a number of issues were raised regarding leaking kernel addresses to userspace. Other documentation was updated but security/self-protection missed out.
Add self-protection documentation regarding printing kernel addresses.
--- Documentation/security/self-protection.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+)
Documentation/security/self-protection.rst +15 -0
@@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of both kernel memory addresses and kernel memory contents (since they may contain kernel addresses or other sensitive things like canary values). +Kernel addresses +---------------- + +Printing kernel addresses to userspace leaks sensitive information about +the kernel memory layout. Care should be exercised when using any printk +specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb] +in certain circumstances [*]). Any file written to using one of these +specifiers should be readable only by privileged processes. + +Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1 +addresses printed with the specifier %p are hashed before printing. + +[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is +printed. If KALLSYMS is not enabled the raw address is printed. + Unique identifiers ------------------
Signature · 1 line
2.7.4
Quoted 3 lines · Tobin C. Harding
This set converts printk-formats.txt ->
core-api/printk-formats.rstWe also update the documentation around printing kernel addresses.
Please also update the comment in lib/vsprintf.c
* ** Please update also Documentation/printk-formats.txt when making changes **
Quoted 1 line
I'd like to get it _realy_ correct so that future
sp: realy->really
Quoted 5 lines · Joe Perches
Quoted 3 lines · Tobin C. Harding
This set converts printk-formats.txt ->
core-api/printk-formats.rstWe also update the documentation around printing kernel addresses.
Quoted 8 lines
Please also update the comment in
lib/vsprintf.c* ** Please update also
Documentation/printk-formats.txtwhen making changes **Quoted 1 line
I'd like to get it _realy_ correct so that future
sp:
realy->really
Damn emphasis plays havoc with the spell checker. I do believe you have made this comment before Joe ;) I'll learn to spell one day.
Will fix as suggested and re-spin.
thanks,
Tobin