doc: update printk documentation
Subsystems (3)
v4 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.
This is my first documentation conversion. Please do be hard on this patch series. I'd like to get it _really_ 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.
v4:
- fix typo 'kpt_restrict' -> 'kptr_restrict' (thanks Randy).
v3:
- Update filename .txt -> .rst in lib/vsnprintf.c comment (Joe Perches)
- Remove unnecessary commas (as suggested by Randy Dunlap)
- Re-apply theory 'make as few changes as possible to complete the conversion'
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.
- Apply theory 'make as few changes as possible to complete the conversion'
Tobin C. Harding (3):
doc: convert printk-formats.txt to rst
doc: update kptr_restrict documentation
doc: add documentation on printing kernel addresses
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst} | 229 +++++++++++----------
Documentation/security/self-protection.rst | 15 ++
Documentation/sysctl/kernel.txt | 3 +-
lib/vsprintf.c | 3 +-
6 files changed, 139 insertions(+), 114 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (63%)Signature · 1 line
2.7.4
PATCH v4 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).
- Remove extraneous double backticks (suggested by Jonathan Corbet).
- Simplify documentation for kobject.
---
Documentation/00-INDEX | 2 -
Documentation/core-api/index.rst | 1 +
.../printk-formats.rst} | 229 +++++++++++----------
lib/vsprintf.c | 3 +-
4 files changed, 122 insertions(+), 113 deletions(-)
rename Documentation/{printk-formats.txt => core-api/printk-formats.rst} (63%)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 +119 -110
485 lines not on this page · raw message
lib/vsprintf.c +2 -1
@@ -1834,7 +1834,8 @@ static char *ptr_to_id(char *buf, char *end, void *ptr, struct printf_spec spec)* * - 'x' For printing the address. Equivalent to "%lx". * -* ** Please update also Documentation/printk-formats.txt when making changes ** +* ** When making changes please also update: +* Documentation/core-api/printk-formats.rst * * Note: The difference between 'S' and 'F' is that on ia64 and ppc64 * function pointers are really function descriptors, which contain a
Signature · 1 line
2.7.4
PATCH v4 2/3 doc: update kptr_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 kptr_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
PATCH v4 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
Jonathan Corbet
maintainerQuoted 10 lines · On Wed, 20 Dec 2017 08:17:14 +1100 "Tobin C. Harding" <[email protected]> wrote:
This set converts printk-formats.txt ->
core-api/printk-formats.rstWe also update the documentation around printing kernel addresses.
This is my first documentation conversion. Please do be hard on this patch series. I'd like to get it _really_ 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.
So I spent a while thinking hard about how I could make Tobin do another round or two on these patches. But then I figure that it's the holidays, and I should just apply them. So that's done. Thanks for all of your work on this!
That said...
- I don't quite understand why you capitalize "kernel" everywhere. I vaguely recall some sort of discussion on that. To me it looks strange...oh well.
- There's a dangling reference to printk-formats.txt in lib/vsprintf.c that we'll want to fix up.
- The vsprintf kerneldoc currently gets pulled into the big "kernel API" dumpster. Someday, it would be nice to turn printk-formats.rst into a "how to output data from the kernel" section, with documentation on vnsprintf, printk, trace_printk, and format strings all in one place. What a fine day that would be...
Thanks again,
jon
Randy Dunlap
reviewerQuoted 19 lines · Jonathan Corbet
Quoted 10 lines · On Wed, 20 Dec 2017 08:17:14 +1100 "Tobin C. Harding" <[email protected]> wrote:
This set converts printk-formats.txt ->
core-api/printk-formats.rstWe also update the documentation around printing kernel addresses.
This is my first documentation conversion. Please do be hard on this patch series. I'd like to get it _really_ 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.
So I spent a while thinking hard about how I could make Tobin do another round or two on these patches. But then I figure that it's the holidays, and I should just apply them. So that's done. Thanks for all of your work on this!
Quoted 5 lines
That said...
- I don't quite understand why you capitalize "kernel" everywhere. I vaguely recall some sort of discussion on that. To me it looks strange...oh well.
Mauro explained that he capitalizes Kernel when it is being used as a shortened version of "the Linux kernel," i.e., as a proper name, so I think that Tobin appropriated that style.
It would be OK to undo that IMO.
Quoted 8 lines
- There's a dangling reference to printk-formats.txt in
lib/vsprintf.cthat we'll want to fix up.- The vsprintf kerneldoc currently gets pulled into the big "kernel API" dumpster. Someday, it would be nice to turn
printk-formats.rstinto a "how to output data from the kernel" section, with documentation on vnsprintf, printk,trace_printk, and format strings all in one place. What a fine day that would be...
Signature · 1 line
~Randy
Quoted 26 lines · Randy Dunlap
Quoted 19 lines · Jonathan Corbet
Quoted 10 lines · On Wed, 20 Dec 2017 08:17:14 +1100 "Tobin C. Harding" <[email protected]> wrote:
This set converts printk-formats.txt ->
core-api/printk-formats.rstWe also update the documentation around printing kernel addresses.
This is my first documentation conversion. Please do be hard on this patch series. I'd like to get it _really_ 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.
So I spent a while thinking hard about how I could make Tobin do another round or two on these patches. But then I figure that it's the holidays, and I should just apply them. So that's done. Thanks for all of your work on this!
Quoted 5 lines
That said...
- I don't quite understand why you capitalize "kernel" everywhere. I vaguely recall some sort of discussion on that. To me it looks strange...oh well.
Quoted 5 lines
Mauro explained that he capitalizes Kernel when it is being used as a shortened version of "the Linux kernel," i.e., as a proper name, so I think that Tobin appropriated that style.
It would be OK to undo that IMO.
I'm happy to write it however, if everyone is happy with 'kernel' everywhere then that is good (and easier). I think Mauro is correct but I also think Jon is correct, it does look funny. Code language doesn't always follow English grammar rules after all.
thanks,
Tobin.
Quoted 6 lines · Jonathan Corbet
Quoted 3 lines · On Wed, 20 Dec 2017 08:17:14 +1100 "Tobin C. Harding" <[email protected]> wrote:
This set converts printk-formats.txt ->
core-api/printk-formats.rstWe also update the documentation around printing kernel addresses.
[]
Quoted 2 lines
Quoted 1 line
- There's a dangling reference to printk-formats.txt in
lib/vsprintf.cthat we'll want to fix up.
patch 1/3 updates that reference.
Jonathan Corbet
maintainerQuoted 4 lines · On Thu, 21 Dec 2017 11:30:57 -0800 Joe Perches <[email protected]> wrote:
Quoted 2 lines
Quoted 1 line
- There's a dangling reference to printk-formats.txt in
lib/vsprintf.cthat we'll want to fix up.
patch 1/3 updates that reference.
It updates one of them - there were two, one of which remains. I'll just toss in a patch to do that one too.
jon
Quoted 12 lines · Jonathan Corbet
Quoted 9 lines · On Wed, 20 Dec 2017 08:17:14 +1100 "Tobin C. Harding" <[email protected]> wrote:
This set converts printk-formats.txt ->
core-api/printk-formats.rstWe also update the documentation around printing kernel addresses.
This is my first documentation conversion. Please do be hard on this patch series. I'd like to get it _really_ 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.
Quoted 6 lines
Quoted 1 line
Thank you for the time already given to reviewing previous versions.
So I spent a while thinking hard about how I could make Tobin do another round or two on these patches. But then I figure that it's the holidays, and I should just apply them. So that's done. Thanks for all of your work on this!
Oh ok, I would have been happy to drag it over the holiday period and get it super correct. I'm always chasing perfection (even if seemingly a long way from it ;) so please never feel you have to rush things through. I'm happy to learn how to do it correctly and that will save everyone time in the future.
Quoted 1 line
That said...
I am happy also to patch on top of what was applied after Christmas break :) I don't want to create any extra work for anyone else.
Quoted 3 lines
- I don't quite understand why you capitalize "kernel" everywhere. I vaguely recall some sort of discussion on that. To me it looks strange...oh well.
Ok, I'm going to go with 'kernel' everywhere from now on. Despite having two degrees I am particularly crap at English [grammar]. Please do pick me up on any mistakes no matter how trivial. That is the only way to learn IMO.
Quoted 2 lines
- There's a dangling reference to printk-formats.txt in
lib/vsprintf.cthat we'll want to fix up.
Bad Tobin, no biscuit.
Quoted 5 lines
- The vsprintf kerneldoc currently gets pulled into the big "kernel API" dumpster. Someday, it would be nice to turn
printk-formats.rstinto a "how to output data from the kernel" section, with documentation on vnsprintf, printk,trace_printk, and format strings all in one place. What a fine day that would be...
I don't quite understand this yet. (I added to my kernel list of things to learn and work on ;)
thanks Jon. Merry Christmas,
Tobin.