printk/index: Printk index feature documentation
Subsystems (2)
PATCH 1/1 printk/index: Printk index feature documentation
Document the printk index feature. The primary motivation is to explain that it is not creating KABI from particular printk() calls.
---
Changes against RFC[*]:
+ Updated text by feedback from Darrick.
+ Updated index.rst and MAINTAINERS.
+ Tested build of the html documentation.
Did not add Sergey's ack because there were some changes.
[*] https://lore.kernel.org/r/[email protected]
Documentation/core-api/index.rst | 1 + Documentation/core-api/printk-index.rst | 136 ++++++++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 138 insertions(+) create mode 100644 Documentation/core-api/printk-index.rst
Documentation/core-api/index.rst +1 -0
@@ -20,6 +20,7 @@ it. workqueue printk-basics printk-formats + printk-index symbol-namespaces Data structures and low-level utilities
Documentation/core-api/printk-index.rst new file +136 -0
136 lines not on this page · raw message
MAINTAINERS +1 -0
@@ -15855,6 +15855,7 @@ F: kernel/printk/ PRINTK INDEXING R: Chris Down <[email protected]> S: Maintained +F: Documentation/core-api/printk-index.rst F: kernel/printk/index.c PROC FILESYSTEM
Signature · 1 line
2.26.2
Quoted 5 lines · Petr Mladek
Document the printk index feature. The primary motivation is to explain that it is not creating KABI from particular
printk()calls.Signed-off-by Petr Mladek <[email protected]>
This looks great, thanks a lot for spending the time to write this up. Just some very minor comments.
Quoted 71 lines
---
Changes against RFC[*]:+ Updated text by feedback from Darrick.
+ Updatedindex.rstandMAINTAINERS.
+ Tested build of the html documentation.Did not add Sergey's ack because there were some changes.
[*] https://lore.kernel.org/r/[email protected]
Documentation/core-api/index.rst | 1 + Documentation/core-api/printk-index.rst | 136 ++++++++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 138 insertions(+)create mode 100644
Documentation/core-api/printk-index.rstDocumentation/core-api/index.rst +1
-0@@ -20,6 +20,7 @@ it. workqueue printk-basics printk-formats + printk-index symbol-namespacesData structures and low-level utilities
Documentation/core-api/printk-index.rst new file +36
-0@@ -0,0 +1,136 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +Printk Index +============ + +There are many ways how to monitor the state of the system. One important +source of information is the system log. It provides a lot of information, +including more or less important warnings and error messages. + +There are monitoring tools that filter and take action based on messages +logged. + +The kernel messages are evolving together with the code. As a result, +particular kernel messages are not KABI and never will be! + +It is a huge challenge for maintaining the system log monitors. It requires +knowing what messages were updated in a particular kernel version and why. +Finding these changes in the sources would require non-trivial parsers. +Also it would require matching the sources with the binary kernel which +is not always trivial. Various changes might be backported. Various kernel +versions might be used on different monitored systems. + +This is where the printk index feature might become useful. It provides +a dump of printk formats used all over the source code used for the kernel +and modules on the running system. It is accessible at runtime via debugfs. + +The printk index helps to find changes in the message formats. Also it helps +to track the strings back to the kernel sources and the related commit. + + +User Interface +============== + +The index of printk formats are split in into separate files. The files are +named according to the binaries where the printk formats are built-in. There
Documentation/core-api/printk-index.rst line 46
Quoted 10 lines
Documentation/core-api/printk-index.rst new file +10
-0+is always "vmlinux" and optionally also modules, for example:: + + /sys/kernel/debug/printk/index/vmlinux + /sys/kernel/debug/printk/index/ext4 + /sys/kernel/debug/printk/index/scsi_mod + +Note that only loaded modules are shown. Also printk formats from a module +might appear in "vmlinux" when the module is built-in. + +The content is inspired by the dynamic debug interface and looks like::
s/::/:/
Documentation/core-api/printk-index.rst line 58
Quoted 12 lines
Documentation/core-api/printk-index.rst new file +12
-0+ + $> head -1 /sys/kernel/debug/printk/index/vmlinux; shuf -n 5 vmlinux + # <level[,flags]> filename:line function "format" + <5> block/blk-settings.c:661 disk_stack_limits "%s: Warning: Device %s is misaligned\n" + <4> kernel/trace/trace.c:8296 trace_create_file "Could not create tracefs '%s' entry\n" + <6> arch/x86/kernel/hpet.c:144 _hpet_print_config "hpet: %s(%d):\n" + <6> init/do_mounts.c:605 prepare_namespace "Waiting for root device %s...\n" + <6> drivers/acpi/osl.c:1410 acpi_no_auto_serialize_setup "ACPI: auto-serialization disabled\n" + +, where the meaning is:: + + - level: log level
Maybe worth noting that level may not be there if we have a KERN_CONT.
Quoted 93 lines
Documentation/core-api/printk-index.rst new file +78
-0+ - flags: optional flags: currently only 'c' for KERN_CONT + - filename:line: source filename and line number of the related + printk() call. Note that there are many wrappers, for example, + pr_warn(), pr_warn_once(), dev_warn(). + - function: function name where the printk() call is used. + - format: format string + +The extra information makes it a bit harder to find differences +between various kernels. Especially the line number might change +very often. On the other hand, it helps a lot to confirm that +it is the same string or find the commit that is responsible +for eventual changes. + + +printk() Is Not a Stable KABI +============================= + +Several developers are afraid that exporting all these implementation +details into the user space will transform particular printk() calls +into KABI. + +But it is exactly the opposite. printk() calls must _not_ be KABI. +And the printk index helps user space tools to deal with this. + + +Subsystem specific printk wrappers +================================== + +The printk index is generated using extra metadata that are stored in +a dedicated .elf section ".printk_index". It is achieved using macro +wrappers doing __printk_index_emit() together with the real printk() +call. The same technique is used also for the metadata used by +the dynamic debug feature. + +The metadata are stored for a particular message only when it is printed +using these special wrappers. It is implemented for the commonly +used printk() calls, including, for example, pr_warn(), or pr_once(). + +Additional changes are necessary for various subsystem specific wrappers +that call the original printk() via a common helper function. These needs +their own wrappers adding __printk_index_emit(). + +Only few subsystem specific wrappers have been updated so far, +for example, dev_printk(). As a result, the printk formats from +some subsystes can be missing in the printk index. + + +Subsystem specific prefix +========================= + +The macro pr_fmt() macro allows to define a prefix that is printed +before the string generated by the related printk() calls. + +Subsystem specific wrappers usually add even more complicated +prefixes. + +These prefixes can be stored into the printk index metadata +by an optional parameter of __printk_index_emit(). The debugfs +interface might then show the printk formats including these prefixes. +For example, drivers/acpi/osl.c contains:: + + #define pr_fmt(fmt) "ACPI: OSL: " fmt + + static int __init acpi_no_auto_serialize_setup(char *str) + { + acpi_gbl_auto_serialize_methods = FALSE; + pr_info("Auto-serialization disabled\n"); + + return 1; + } + +This results in the following printk index entry:: + + <6> drivers/acpi/osl.c:1410 acpi_no_auto_serialize_setup "ACPI: auto-serialization disabled\n" + +It helps matching messages from the real log with printk index. +Then the source file name, line number, and function name can +be used to match the string with the source code.MAINTAINERS +0
-0@@ -15855,6 +15855,7 @@ F: kernel/printk/PRINTK INDEXING
R: Chris Down <[email protected]>
S: Maintained
+F:Documentation/core-api/printk-index.rst
F:kernel/printk/index.cPROC FILESYSTEM
Signature · 1 line
2.26.2
Quoted 9 lines · Chris Down
Quoted 5 lines · Petr Mladek
Document the printk index feature. The primary motivation is to explain that it is not creating KABI from particular
printk()calls.Signed-off-by Petr Mladek <[email protected]>This looks great, thanks a lot for spending the time to write this up. Just some very minor comments.
Ah, I forgot to do the small fixup when pushing. So, I did it now are rebased.
Quoted 11 lines
Quoted 11 lines
Documentation/core-api/printk-index.rst new file +9
-0+User Interface +============== + +The index of printk formats are split in into separate files. The files are +named according to the binaries where the printk formats are built-in. There +is always "vmlinux" and optionally also modules, for example:: + + /sys/kernel/debug/printk/index/vmlinux + /sys/kernel/debug/printk/index/ext4
Quoted 8 lines
Documentation/core-api/printk-index.rst line 46
Quoted 6 lines
Documentation/core-api/printk-index.rst new file +6
-0+ /sys/kernel/debug/printk/index/scsi_mod + +Note that only loaded modules are shown. Also printk formats from a module +might appear in "vmlinux" when the module is built-in. + +The content is inspired by the dynamic debug interface and looks like::s/::/:/
The double double dots '::' cause that the following paragraph will be block quoting. There is only single ':' in the generated html.
Quoted 9 lines
Documentation/core-api/printk-index.rst line 56
Quoted 9 lines
Documentation/core-api/printk-index.rst new file +9
-0+ $> head -1 /sys/kernel/debug/printk/index/vmlinux; shuf -n 5 vmlinux + # <level[,flags]> filename:line function "format" + <5> block/blk-settings.c:661 disk_stack_limits "%s: Warning: Device %s is misaligned\n" + <4> kernel/trace/trace.c:8296 trace_create_file "Could not create tracefs '%s' entry\n" + <6> arch/x86/kernel/hpet.c:144 _hpet_print_config "hpet: %s(%d):\n" + <6> init/do_mounts.c:605 prepare_namespace "Waiting for root device %s...\n" + <6> drivers/acpi/osl.c:1410 acpi_no_auto_serialize_setup "ACPI: auto-serialization disabled\n" + +, where the meaning is::
I uses only single double dot here.
Quoted 3 lines
Quoted 1 line
+ - level: log level
Maybe worth noting that level may not be there if we have a
KERN_CONT.
I added:
- :level: log level value: 0-7 for particular severity, -1 as default, 'c' as continuous line without an explicit log level
Quoted 6 lines
Quoted 1 line
+ - flags: optional flags: currently only 'c' for
KERN_CONT+ - filename:line: source filename and line number of the related
Documentation/core-api/printk-index.rst line 64
Quoted 4 lines
Documentation/core-api/printk-index.rst new file +4
-0+ printk() call. Note that there are many wrappers, for example, + pr_warn(), pr_warn_once(), dev_warn(). + - function: function name where the printk() call is used. + - format: format string
I added few more double dots to generate bold: 'level', 'flags', 'filename:line', etc.
See the updated commit at
https://git.kernel.org/pub/scm/linux/kernel/git/printk/linux.git/commit/?h=for-5.19&id=a5c7a39f508ae1fd3288493b96dd26079bae41bf
Best Regards,
Petr
Quoted 5 lines · Petr Mladek
Document the printk index feature. The primary motivation is to explain that it is not creating KABI from particular
printk()calls.Signed-off-by Petr Mladek <[email protected]>
JFYI, the patch has been committed into printk/linux.git, branch for-5.19.
Best Regards,
Petr