kmsg - add Documentation/ABI/testing/dev-kmsg

Signed-off-by: Kay Sievers <kay@vrfy.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg
new file mode 100644 (file)
index 0000000..281ecc5
--- /dev/null
+++ b/Documentation/ABI/testing/dev-kmsg
@@ -0,0 +1,90 @@
+What:          /dev/kmsg
+Date:          Mai 2012
+KernelVersion: 3.5
+Contact:       Kay Sievers <kay@vrfy.org>
+Description:   The /dev/kmsg character device node provides userspace access
+               to the kernel's printk buffer.
+
+               Injecting messages:
+               Every write() to the opened device node places a log entry in
+               the kernel's printk buffer.
+
+               The logged line can be prefixed with a <N> syslog prefix, which
+               carries the syslog priority and facility. The single decimal
+               prefix number is composed of the 3 lowest bits being the syslog
+               priority and the higher bits the syslog facility number.
+
+               If no prefix is given, the priority number is the default kernel
+               log priority and the facility number is set to LOG_USER (1). It
+               is not possible to inject messages from userspace with the
+               facility number LOG_KERN (0), to make sure that the origin of
+               the messages can always be reliably determined.
+
+               Accessing the buffer:
+               Every read() from the opened device node receives one record
+               of the kernel's printk buffer.
+
+               The first read() directly following an open() always returns
+               first message in the buffer; there is no kernel-internal
+               persistent state; many readers can concurrently open the device
+               and read from it, without affecting other readers.
+
+               Every read() will receive the next available record. If no more
+               records are available read() will block, or if O_NONBLOCK is
+               used -EAGAIN returned.
+
+               Messages in the record ring buffer get overwritten as whole,
+               there are never partial messages received by read().
+
+               In case messages get overwritten in the circular buffer while
+               the device is kept open, the next read() will return -EPIPE,
+               and the seek position be updated to the next available record.
+               Subsequent reads() will return available records again.
+
+               Unlike the classic syslog() interface, the 64 bit record
+               sequence numbers allow to calculate the amount of lost
+               messages, in case the buffer gets overwritten. And they allow
+               to reconnect to the buffer and reconstruct the read position
+               if needed, without limiting the interface to a single reader.
+
+               The device supports seek with the following parameters:
+               SEEK_SET, 0
+                 seek to the first entry in the buffer
+               SEEK_END, 0
+                 seek after the last entry in the buffer
+               SEEK_DATA, 0
+                 seek after the last record available at the time
+                 the last SYSLOG_ACTION_CLEAR was issued.
+
+               The output format consists of a prefix carrying the syslog
+               prefix including priority and facility, the 64 bit message
+               sequence number and the monotonic timestamp in microseconds.
+               The values are separated by a ','. Future extensions might
+               add more comma separated values before the terminating ';'.
+               Unknown values should be gracefully ignored.
+
+               The human readable text string starts directly after the ';'
+               and is terminated by a '\n'. Untrusted values derived from
+               hardware or other facilities are printed, therefore
+               all non-printable characters in the log message are escaped
+               by "\x00" C-style hex encoding.
+
+               A line starting with ' ', is a continuation line, adding
+               key/value pairs to the log message, which provide the machine
+               readable context of the message, for reliable processing in
+               userspace.
+
+               Example:
+               7,160,424069;pci_root PNP0A03:00: host bridge window [io  0x0000-0x0cf7] (ignored)
+                SUBSYSTEM=acpi
+                DEVICE=+acpi:PNP0A03:00
+               6,339,5140900;NET: Registered protocol family 10
+               30,340,5690716;udevd[80]: starting version 181
+
+               The DEVICE= key uniquely identifies devices the following way:
+                 b12:8        - block dev_t
+                 c127:3       - char dev_t
+                 n8           - netdev ifindex
+                 +sound:card0 - subsystem:devname
+
+Users:         dmesg(1), userspace kernel log consumers

diff --git a/Documentation/devices.txt b/Documentation/devices.txt
index 00383186d8fb3e2c0fc4d5a12852844cb5b2721f..5941f5136c6b6adadf1f28554278896280782ccd 100644 (file)
--- a/Documentation/devices.txt
+++ b/Documentation/devices.txt
@@ -98,7 +98,8 @@ Your cooperation is appreciated.
                  8 = /dev/random       Nondeterministic random number gen.
                  9 = /dev/urandom      Faster, less secure random number gen.
                 10 = /dev/aio          Asynchronous I/O notification interface
-                11 = /dev/kmsg         Writes to this come out as printk's
+                11 = /dev/kmsg         Writes to this come out as printk's, reads
+                                       export the buffered printk records.
                 12 = /dev/oldmem       Used by crashdump kernels to access
                                        the memory of the kernel that crashed.