Documentation/core-api/printk-index.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/printk-index.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/printk-index.rst
Extension
.rst
Size
5513 bytes
Lines
138
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

============
Printk Index
============

There are many ways 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
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::

   $> 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 value: 0-7 for particular severity, -1 as default,
	'c' as continuous line without an explicit log level
   - :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

Annotation

Implementation Notes