Re: [PATCH] printk/index: Printk index feature documentation

[Petr Mladek]

On Tue 2022-04-05 13:22:49, Chris Down wrote:
> Petr Mladek writes:
> > 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 <pmladek@xxxxxxxx>
> > Acked-by: Sergey Senozhatsky <senozhatsky@xxxxxxxxxxxx>
> 
> 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.

> > --- /dev/null
> > +++ b/Documentation/core-api/printk-index.rst
> > +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::
> 
> s/::/:/

The double double dots '::' cause that the following paragraph will be
block quoting. There is only single ':' in the generated html.

> > +   $> 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.

> > +   - 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

> > +   - 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

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