LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Heiko Carstens <heiko.carstens@de.ibm.com>
To: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Andrew Morton <akpm@linux-foundation.org>,
	Greg Kroah-Hartman <gregkh@suse.de>,
	linux-kernel@vger.kernel.org, linux-s390@vger.kernel.org
Subject: Re: [GIT PULL/RESEND] kernel message catalog patches
Date: Thu, 23 Oct 2008 23:04:46 +0200	[thread overview]
Message-ID: <20081023210446.GA12003@osiris.boeblingen.de.ibm.com> (raw)
In-Reply-To: <alpine.LFD.2.00.0810230835150.3287@nehalem.linux-foundation.org>

On Thu, Oct 23, 2008 at 08:35:40AM -0700, Linus Torvalds wrote:
> On Tue, 21 Oct 2008, Heiko Carstens wrote:
> > 
> > please pull from 'kmsg' branch of
> > 
> >         git://git390.osdl.marist.edu/pub/scm/linux-2.6.git kmsg
> > 
> > to get the kernel message catalog code.
> 
> I'm not going to pull it, since I have no idea what it is, or why I'd 
> _want_ to pull it.

The whole point of the patch set is to add documentation for kernel
messages that are emitted via printk. The documentation is supposed to
help a sys admin to help understand what went wrong.

To achieve this each message gets a component name and a hash and so
gets a unique identifier with which the documentation for the message
can be found. The documentation can be within the source code or in
the Documentation/kmsg/<arch> folder. A script allows to create man
pages from the documentations (make D=2). The user can then just issue
'man <componentname>.<hash>' and gets a detailed description of what
went wrong and what to do.

To add component name and hash to the printk output new macros have to
be used (see patch "kmsg: tagged kernel messages."):

kmsg_emerg(format, args...);
kmsg_alert(format, args...);
kmsg_crit(format, args...);
kmsg_err(format, args...);
kmsg_warn(format, args...);
kmsg_notice(format, args...);
kmsg_info(format, args...);

If kernel message identifiers are disabled they just translate into
printk(KERN_EMERG, format, args...); etc.

Otherwise the code in question has to specify its compoment name
with a KMSG_COMPONENT define and kmesg_<level>() would translate into

printk_hash(level KMSG_COMPONENT ".%06x" ": ", format, ##__VA_ARGS__)

where printk_hash will generate a hash for the format string.

Example:

The s390 xpram driver now has:

#define KMSG_COMPONENT "xpram"
[...]
	if (devs <= 0 || devs > XPRAM_MAX_DEVS) {
		kmsg_err("%d is not a valid number of XPRAM devices\n",devs);

If the message would be printed it could look like:

xpram.ab9aa4 42 is not a valid number of XPRAM devices

The corresponding description for the message is in
Documentation/kmsg/s390/xpram :

/*?
 * Tag: xpram.ab9aa4
 * Text: "%d is not a valid number of XPRAM devices\n"
 * Severity: Error
 * Parameter:
 *   @1: number of partitions
 * Description:
 * The number of XPRAM partitions specified for the 'devs' module parameter 
 * or with the 'xpram.parts' kernel parameter must be an integer in the
 * range 1 to 32. The XPRAM device driver created a maximum of 32 partitions
 * that are probably not configured as intended.
 * User action:
 * If the XPRAM device driver has been compiled as a separate module,
 * unload the module and load it again with a correct value for the 
 * 'devs' module parameter. If the XPRAM device driver has been compiled
 * into the kernel, correct the 'xpram.parts' parameter in the kernel
 * command line and restart Linux.
 */

With "make D=2" a man page can be created from this:

.TH "xpram.ab9aa4" 9 "Linux Messages" LINUX
.SH Message
xpram.ab9aa4: %d is not a valid number of XPRAM devices\n
.SH Severity
Error
.SH Parameters
@1: number of partitions

.SH Description
The number of XPRAM partitions specified for the 'devs' module parameter 
or with the 'xpram.parts' kernel parameter must be an integer in the
range 1 to 32. The XPRAM device driver created a maximum of 32 partitions
that are probably not configured as intended.
.SH User action
If the XPRAM device driver has been compiled as a separate module,
unload the module and load it again with a correct value for the 
'devs' module parameter. If the XPRAM device driver has been compiled
into the kernel, correct the 'xpram.parts' parameter in the kernel
command line and restart Linux.


So with 'man <componentname>.<hash>' a sys admin would get information
of what went wrong.

Please note that this was initially an s390 only patch set but we moved
the infrastructure to generic code since it looks like others want a
facility like this too. iirc Andrew requested the move.

Thanks,
Heiko

  reply	other threads:[~2008-10-23 21:06 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2008-10-16 14:50 [GIT PULL] " Martin Schwidefsky
2008-10-17  7:59 ` Martin Schwidefsky
2008-10-21  9:21   ` [GIT PULL/RESEND] " Heiko Carstens
2008-10-23 15:35     ` Linus Torvalds
2008-10-23 21:04       ` Heiko Carstens [this message]
2008-10-23 21:37         ` Linus Torvalds
2008-10-24 15:50           ` Heiko Carstens
2008-10-26 19:26           ` Martin Schwidefsky
2008-10-26 19:12             ` Linus Torvalds
2008-10-27 10:01               ` Martin Schwidefsky
2008-10-27 15:05                 ` Linus Torvalds
2008-10-27 15:52                   ` Martin Schwidefsky
2008-10-27 16:19                     ` Theodore Tso
2008-10-27 16:27                       ` Randy Dunlap
2008-10-28  8:25                         ` Martin Schwidefsky
2008-10-27 16:03                   ` Alan Cox
2008-10-27 16:10                     ` Linus Torvalds
2008-10-27 16:35                       ` Alan Cox
2008-10-27 19:36                       ` Theodore Tso

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20081023210446.GA12003@osiris.boeblingen.de.ibm.com \
    --to=heiko.carstens@de.ibm.com \
    --cc=akpm@linux-foundation.org \
    --cc=gregkh@suse.de \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-s390@vger.kernel.org \
    --cc=torvalds@linux-foundation.org \
    --subject='Re: [GIT PULL/RESEND] kernel message catalog patches' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).