Bug 97161

Summary:	bootparam(7): 'debug' parameter: reference to <linux/kernel.h> for information on log levels is misleading.
Product:	Documentation	Reporter:	Alain Kalker (a.c.kalker)
Component:	man-pages	Assignee:	documentation_man-pages (documentation_man-pages)
Status:	RESOLVED CODE_FIX
Severity:	normal	CC:	mtk.manpages, saulery
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:		Subsystem:
Regression:	No	Bisected commit-id:

Description Alain Kalker 2015-04-23 17:07:58 UTC

The section on the 'debug' parameter refers the user to <linux/kernel.h> for more information on kernel log levels, however, that file contains neither a description of console_loglevel nor nor a description of the various log levels.

The closest I can find is <include/linux/kern_levels.h>, which defines the various log levels but doesn't explain console_loglevel, Also, it only exists in recent kernels, version 3.5 and up.
Another candidate would be <include/linux/printk.h>, which does define console_loglevel but doesn't explain the individual log levels.

Perhaps both references (<include/linux/printk.h>, <include/linux/kern_levels.h>) could be included?

Kind regards,

Alain

Comment 1 Alain Kalker 2015-04-23 17:10:10 UTC

Found in Arch Linux, package man-pages 3.83-1. Confirmed in http://man7.org/linux/man-pages/man7/bootparam.7.html

Comment 2 Stéphane Aulery 2015-04-23 22:19:19 UTC

Hello Alain and Michael,

We can quote every level rather than refer to two files.

What do you think about, Michael?

Regards,

-- 
Stéphane Aulery

Comment 3 Michael Kerrisk 2015-04-24 11:50:57 UTC

(In reply to Alain Kalker from comment #0)
> The section on the 'debug' parameter refers the user to <linux/kernel.h> for
> more information on kernel log levels, however, that file contains neither a
> description of console_loglevel nor nor a description of the various log
> levels.
> 
> The closest I can find is <include/linux/kern_levels.h>, which defines the
> various log levels but doesn't explain console_loglevel, Also, it only
> exists in recent kernels, version 3.5 and up.
> Another candidate would be <include/linux/printk.h>, which does define
> console_loglevel but doesn't explain the individual log levels.
> 
> Perhaps both references (<include/linux/printk.h>,
> <include/linux/kern_levels.h>) could be included?

Hello Alain,

I must say I'm generally quite unhappy with the sate of the bootparam(7) page. I'm actually not sure that it was ever a good idea to create it to begin with. But that happened 20 years ago, well before my time as maintainer. As it is now, the page is *horribly( dated, and your report made me seriously think of just removing the page! As it is, I have settled for discarding 60% of the page, and fixing a few of the more glaring errors in the remainder. Regarding your report, I amended the test on 'debug' to read:

   Boot arguments for use by kernel developers
       'debug'
              Kernel  messages  are  handed  off  to  a  daemon (e.g.,
              klogd(8) or similar) so that they may be logged to disk.
              Messages with a priority above console_loglevel are also
              printed on the console.  (For a discussion of these lev‐
              els,  see  syslog(2).)   By default, console_loglevel is
              set to log messages at levels  higher  than  KERN_DEBUG.
              This  boot  argument will cause the kernel to also print
              messages  logged  at  level  KERN_DEBUG.   The   console
              loglevel  can  also  be  set  on a booted system via the
              /proc/sys/kernel/printk file (described  in  syslog(2)),
              the  syslog(2) SYSLOG_ACTION_CONSOLE_LEVEL operation, or
              dmesg(8).


I believe that should address your concerns, so I'm closing the bug.

Cheers,

Michael