The operation of a Linux system sometimes requires to decode themeaning of a specific kernel message, e.g. an error message of adriver. Especially on our mainframe zSeries platform systemadministrators want to have descriptions for Linux kernel messages.They are used to that, because all other operating systems on thatplatform like z/OS, z/VM or z/VSE have message catalogs with detaileddescriptions about the semantics of the messages.

In general we think, that also for Linux it is a good thing to havedocumentation for the most important kernel/driver messages. Evenkernel hackers not always are aware of the meaning of kernel messagesfor components, which they don't know in detail. Most of the messagesare self explaining but sometimes you get something like "Clocksourcetsc unstable (delta = 7304132729 ns)" and you wonder if your system isgoing to explode.

Unfortunately currently there is no general infrastructure in the Linuxkernel for the documentation of messages. I worked on a proposal, howthat could be implemented in an easy way using the already existingkernel-doc infrastructure and using printk. The proposal is as follows

1. We use message identifiers in order to map messages to messagedescriptions. A message identifier consists out of a component name andwithin that component unique message number.

2. Messages and message descriptions are maintained together in thekernel sources in order to keep them up to date. Messages catalog aregenerated automatically for exactly one kernel level.

3. A special tool checks, if messages are not documented or if thereare message descriptions without corresponding messages.

4. We use the already existing kernel-doc tool to generate an onlinemessage catalog or e.g. a pdf for offline documentation.

Current prototype implementation:================================= The structure of a kernel message is: <component>.<msg number>: <msg>

* component: Name of the kernel or driver component e.g. "pci", "ide", etc.* msg number: Within the component unique number of a kernel message.* msg: printk message

New macros KMSG_ERR(), KMSG_WARN(), etc. are defined, which have to beused in printk. These macros have as parameter the message number andare using a per c-file defined macro KMSG_COMPONENT.

The messages have to be documented within the C source filein the following way:

/** * message * @0: device number of device. * * Description: * An operation has been performed on the msgtest device, but the * device has not been set online. Therefore the operation failed * * User Response: * Operator should set device online. * Issue "chccwdev -e <device number>". * */KMSG_DOC(kmsgtest, 2, "Device %x not online");

I created a patch for the kernel-doc tool so it can be used to generatea catalog of all kernel messages:

>> kernel-doc -man kmsgtest.c > kmsgtest.2>> man ./kmsgtest.2

# Kernel API(9) Linux Messages Kernel API(9)# # MESSAGE:# kmsgtest.2: "device %x not online"## Parameter:# 1 Device number of device.## Description:# An operation has been performed on the msgtest device, but# the device has not been set online. Therefore the operation failed.## User Response:# Operator should set device online.# Issue "chccwdev -e <device number>".## May 2007 kmsgtest.2 Kernel API(9)

A nice thing would be to include the online kernel message catalog inthe kernel rpm. One possibility for that would be to have one man pageper message. If an operator finds the message kmsgtest.2 invar/log/messages and wants to know what the message means, he simplyissues "man kmsgtest.2" and gets the description.

To ensure that all messages are documented and there are no messagedescriptions without corresponding messages, a checker tool isprovided. To enable message checking, in the toplevel Makefile thefollowing has to be added:

CHECK = scripts/kmsg_check.pl check

To enable message checking during kernel build, the "C" option hasto be used: