|author||Vlastimil Babka <firstname.lastname@example.org>||2021-02-25 17:46:39 +0100|
|committer||Petr Mladek <email@example.com>||2021-04-07 13:20:59 +0200|
printk: clarify the documentation for plain pointer printing
We have several modifiers for plain pointers (%p, %px and %pK) and now also the no_hash_pointers boot parameter. The documentation should help to choose which variant to use. Importantly, we should discourage %px in favor of %p (with the new boot parameter when debugging), and stress that %pK should be only used for procfs and similar files, not dmesg buffer. This patch clarifies the documentation in that regard. Signed-off-by: Vlastimil Babka <firstname.lastname@example.org> Reviewed-by: Matthew Wilcox (Oracle) <email@example.com> Reviewed-by: Petr Mladek <firstname.lastname@example.org> Signed-off-by: Petr Mladek <email@example.com> Link: https://firstname.lastname@example.org
Diffstat (limited to 'Documentation/core-api')
1 files changed, 25 insertions, 1 deletions
diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
index 160e710d992f..6724adf58082 100644
@@ -79,7 +79,19 @@ 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. The kernel will print ``(ptrval)`` until it
-gathers enough entropy. If you *really* want the address see %px below.
+gathers enough entropy.
+When possible, use specialised modifiers such as %pS or %pB (described below)
+to avoid the need of providing an unhashed address that has to be interpreted
+post-hoc. If not possible, and the aim of printing the address is to provide
+more information for debugging, use %p and boot the kernel with the
+``no_hash_pointers`` parameter during debugging, which will print all %p
+addresses unmodified. If you *really* always want the unmodified address, see
+If (and only if) you are printing addresses as a content of a virtual file in
+e.g. procfs or sysfs (using e.g. seq_printf(), not printk()) read by a
+userspace process, use the %pK modifier described below instead of %p or %px.
@@ -139,6 +151,11 @@ For printing kernel pointers which should be hidden from unprivileged
users. The behaviour of %pK depends on the kptr_restrict sysctl - see
Documentation/admin-guide/sysctl/kernel.rst for more details.
+This modifier is *only* intended when producing content of a file read by
+userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the
+section about %p above for discussion about how to manage hashing pointers
@@ -153,6 +170,13 @@ equivalent to %lx (or %lu). %px is preferred 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.
+Before using %px, consider if using %p is sufficient together with enabling the
+``no_hash_pointers`` kernel parameter during debugging sessions (see the %p
+description above). One valid scenario for %px might be printing information
+immediately before a panic, which prevents any sensitive information to be
+exploited anyway, and with %px there would be no need to reproduce the panic