printk: update changelog

1 files changed, 62 insertions, 54 deletions

diff --git a/printk.patch b/printk.patch
index 75e47b5..813e9a1 100644
--- a/printk.patch
+++ b/printk.patch
@@ -1,40 +1,47 @@
 From: Kay Sievers <kay@vrfy.org>
 Subject: printk: support structured and multi-facility log messages
 
-The kernel messages are the primary source of information about the overall
-state of the system and the connected device. The usual kernel messages are
-mostly human language, targeted at a person reading them. That part of the
+Kernel log messages are the primary source of information about the overall
+state of the system and connected devices. Traditional kernel messages are
+mostly human language, targeted at a human reading them. This part of the
 picture works very well since a very long time.
 
-Most machines run unattended almost all of their time, and software, and not
-humans, need to process the kernel messages. Having a machine making sense
-out of human language messages is inefficient, unreliable, and sometimes
-plain impossible to get right. All the useful information about the context,
-available at the time of creation of the message, is just thrown away. Later,
-the consumers of the messages will need to apply magic to reconstruct what
-the context might have been, to be able to interpret the messages.
+However, most machines run unattended almost all of their time, and
+software, and not humans, need to process the kernel messages. Having
+a machine making sense out of human language messages is inefficient,
+unreliable, and sometimes plain impossible to get right. With human
+language messages all useful information about their context,
+available at the time of creation of the messages, is just thrown
+away. Later, software consumers of the messages will need to apply
+magic to reconstruct what the context might have been, to be able to
+interpret the messages.
 
-This extends printk() to be able to attach arbitrary key/value pairs to logged
-messages, to carry machine-readable data which describes the context of the
-log message at time of its creation. Users of the log can retrieve, along with
-the human-readable message, a key/value dictionary to reliably identify
-specific devices, drivers, subsystems, classes and types of messages.
+This patch extends printk() to be able to attach arbitrary key/value
+pairs to logged messages, to carry machine-readable data which
+describes the context of the log message at time of its
+creation. Users of the log can retrieve, along with the human-readable
+message, a key/value dictionary to reliably identify specific devices,
+drivers, subsystems, classes and types of messages.
 
-- Record-based instead of the traditional byte-stream buffer. All records
-  carry a 64 bit timestamp, the syslog facility, priority in the record header.
+Various features of this patch:
+
+- Record-based stream instead of the traditional byte stream
+  buffer. All records carry a 64 bit timestamp, the syslog facility
+  and priority in the record header.
 
 - Records consume almost the same amount, sometimes less memory than
-  the traditional byte-stream buffer with printk_time enabled. The record
+  the traditional byte stream buffer (if printk_time is enabled). The record
   header is 16 bytes long, plus some padding bytes at the end if needed.
   The byte-stream buffer needed 3 chars for the syslog prefix, 15 char for
   the timestamp and a newline.
 
-- The buffer management is based on message sequence numbers. When records
-  need to be discarded, the heads move on to the next full record. Unlike
-  the byte-stream buffer, no old logged lines get truncated or partly
-  overwritten by new ones. Sequence numbers also allow consumers of the log
-  stream to get notified if any message in the stream, they are about to read,
-  gets discarded during the time of reading.
+- Buffer management is based on message sequence numbers. When records
+  need to be discarded, the reading heads move on to the next full
+  record. Unlike the byte-stream buffer, no old logged lines get
+  truncated or partly overwritten by new ones. Sequence numbers also
+  allow consumers of the log stream to get notified if any message in
+  the stream they are about to read gets discarded during the time
+  of reading.
 
 - Better buffered IO support for KERN_CONT continuation lines, when printk()
   is called multiple times for a single line. The use of KERN_CONT is now
@@ -42,17 +49,18 @@ specific devices, drivers, subsystems, classes and types of messages.
   here. The buffering could possibly be extended to per-cpu variables to allow
   better thread-safety for multiple printk() invocations for a single line.
 
-- Full-featured syslog facility value support. Different facilities can
-  tag their messages. All userspace-injected messages enforce a facility
-  value > 0 now, to be able to reliably distinguish them from the
-  kernel-generated messages. Independent subsystems like a baseband processor
-  running its own firmware, or a kernel-related userspace process can use
-  their own unique facility values. Multiple independent log streams can
-  co-exist that way in the same buffer. All share the same global sequence
-  number counter to ensure proper ordering and to allow the consumers of the
+- Full-featured syslog facility value support. Different facilities
+  can tag their messages. All userspace-injected messages enforce a
+  facility value > 0 now, to be able to reliably distinguish them from
+  the kernel-generated messages. Independent subsystems like a
+  baseband processor running its own firmware, or a kernel-related
+  userspace process can use their own unique facility values. Multiple
+  independent log streams can co-exist that way in the same
+  buffer. All share the same global sequence number counter to ensure
+  proper ordering (and interleaving) and to allow the consumers of the
   log to reliably correlate the events from different facilities.
 
-- The dev_printk() output is reliably machine-readable now. In addition
+- Output of dev_printk() is reliably machine-readable now. In addition
   to the printed plain text message, it creates a log dictionary with the
   following properties:
     SUBSYSTEM=     - the driver-core subsytem name
@@ -62,16 +70,17 @@ specific devices, drivers, subsystems, classes and types of messages.
       n8           - netdev ifindex
       +sound:card0 - subsystem:devname
 
-- Support for multiple concurrent readers of /dev/kmsg. Full read(), seek(),
-  poll() support. Output of message sequence numbers, to allow userspace log
-  consumers to reliably reconnect and reconstruct their state at any given
-  time. After open("/dev/kmsg"), read() always returns all currently available
-  records in the buffer. If only future messages should be read, SEEK_END can
-  be used. In case records get overwritten while /dev/kmsg is held open and
-  not read, or records get faster overwritten than they are read, the next
-  read() will return -EPIPE and the current reading position gets updated to
-  the next available record. The passed sequence numbers allow the log consumer
-  to calculate the amount of lost messages.
+- Support for multiple concurrent readers of /dev/kmsg, with read(),
+  seek(), poll() support. Output of message sequence numbers, to allow
+  userspace log consumers to reliably reconnect and reconstruct their
+  state at any given time. After open("/dev/kmsg"), read() always
+  returns *all* buffered records. If only future messages should be
+  read, SEEK_END can be used. In case records get overwritten while
+  /dev/kmsg is held open, or records get faster overwritten than they
+  are read, the next read() will return -EPIPE and the current reading
+  position gets updated to the next available record. The passed
+  sequence numbers allow the log consumer to calculate the amount of
+  lost messages.
 
   $ cat /dev/kmsg
   PRIORITY=5
@@ -81,7 +90,6 @@ specific devices, drivers, subsystems, classes and types of messages.
 
   ...
 
-  SYSLOG_FACILITY=0
   PRIORITY=7
   SEQNUM=268
   TIMESTAMP=399682
@@ -353,12 +361,12 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + *                                +sound:card0  subsystem:devname
 + *   SUBSYSTEM=pci              driver-core subsystem name
 + *
-+ * Valid characters in property names are only [a-zA-Z0-9.-_]. The plain
-+ * text value follows directly the after a '=' character. Any value that
-+ * can possibly carry non-printable characters must be explicitly encoded
-+ * as a binary value.
++ * Valid characters in property names are [a-zA-Z0-9.-_]. The plain text value
++ * follows directly the after a '=' character. Every property is terminated by
++ * a '\n' character.
 + *
-+ * Multiple properties are terminated by a '\n' character.
++ * Any value that can possibly carry non-printable characters must be
++ * explicitly encoded as a binary value.
 + *
 + * A binary value is encoded by not using a '=' character as a delimiter,
 + * but a '\n' character followed directly by a non-aligned inlined little-endian
@@ -366,11 +374,11 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + * Example for a binary property containing 4 bytes:
 + *  "DEVICE=b12:8\nFIRMWARE_DUMP\n\x04\x00\x00\x00\x00\x00\x00\x00\x11\x12\x13\x14\nDRIVER=ahci\0"
 + *
-+ * Any values containing possibly non-printable characters MUST be encoded
-+ * as binary properties before being added to the dictionary. Values
-+ * containing newlines could be interpreted as keys, and would be a security
-+ * risk. Userspace must be able to trust the generated key/value output
-+ * stream to be valid regarding the key and newline sequence.
++ * Userspace must be able to trust the generated key/value output stream to be
++ * valid regarding the key and newline sequence. Values containing newlines
++ * could be interpreted as keys, and would be a potential security risk. Any
++ * properties copied verbatim from hardware, or other untrusted sources, into
++ * the dictionary must be encoded as binary, to avoid such problems.
 + *
 + * Example for a plain text dictionary:
 + *   "DEVICE=b12:8\nSUBSYSTEM=pci\nDRIVER=ahci\n"