printk: update changelog and comments

1 files changed, 31 insertions, 12 deletions

diff --git a/printk.patch b/printk.patch
index c79f40e..3bc374c 100644
--- a/printk.patch
+++ b/printk.patch
@@ -1,5 +1,23 @@
 From: Kay Sievers <kay@vrfy.org>
-Subject: [WORK-IN-PROGRESS] printk: introduce structured and multi-facility logging
+Subject: [WORK-IN-PROGRESS] 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 its connected hardware. The usual kernel messages are
+mostly un-formatted plain text, targeted at a human reading them. That goal
+works very well since a very long time.
+
+Most machines though, run unattended, and software and not humans needs to read
+the messages. Having a machine making sense out of human readable messages is
+inefficient, unreliable, or sometimes plain impossible to get right. All the
+useful information about the context available at the time of creation of the
+message is thrown away. Later consumers of the messages will need to apply
+magic to guess what the context might have been, which was thrown way.
+
+This extends printk to be able to attach key/value pairs to the log messages,
+to carry machine-readable key/values to describe the context of the log
+at time of creation. Users of the log can retrieve, along with the
+human-readable message, the key/value dictionary to reliably identify specific
+devices, drivers, subsystems, classes and types of messages.
 
 - Record-based instead of byte-stream buffer. All records carry proper
   timestamp, syslog facility, priority in the record header.
@@ -27,11 +45,12 @@ Subject: [WORK-IN-PROGRESS] printk: introduce structured and multi-facility logg
   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 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 log to realibly corrrelate the events from differnt facilities.
+  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 log to reliably correlate the events
+  from different facilities.
 
 - Subsystems and drivers can easily attach key/value pair dictionaries
   to any printk() message. Log consumers can extract and recognize
@@ -41,7 +60,7 @@ Subject: [WORK-IN-PROGRESS] printk: introduce structured and multi-facility logg
 - The dev_printk() output is reliably machine-readable now. In addition
   to the printed message, it creates a log dictionary with the following
   properties:
-    SUBSYSTEM=     - the driver-core susbsytem name
+    SUBSYSTEM=     - the driver-core subsytem name
     DEVICE=
       b12:8        - block dev_t
       c127:3       - char dev_t
@@ -55,7 +74,7 @@ Subject: [WORK-IN-PROGRESS] printk: introduce structured and multi-facility logg
   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 -EIO and the current
+  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.
@@ -316,7 +335,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + * sequence numbers of these both entries are maintained.
 + *
 + * If the heads indicate available messages, a length == 0 for the next
-+ * messge indicates a wrap-around to the beginning of the buffer.
++ * message indicates a wrap-around to the beginning of the buffer.
 + *
 + * Every record carries the monotonic timestamp in nanoseconds, as well as
 + * the standard userspace syslog level and syslog facility. The usual
@@ -342,7 +361,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + *
 + * 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 explicitely encoded
++ * can possibly carry non-printable characters must be explicitly encoded
 + * as a binary value.
 + *
 + * Multiple properties are terminated by a '\n' character.
@@ -381,7 +400,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + * userspace, it is a kernel-private implementation detail.
 + *
 + * The classic syslog() syscall format export must only export the human
-+ * readable text message, with the syslog level and facility prepended
++ * readable text message, with the syslog level and facility prefixed
 + * as <>. Adding unconverted binary data would break the syslog() syscall
 + * export format.
 + *
@@ -518,7 +537,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 +	if (log_next_idx + size + sizeof(struct log) >= log_buf_len) {
 +		/*
 +		 * This message + an additional empty header does not fit
-+		 * at the end of the buffer. Add an empty header with len = 0
++		 * at the end of the buffer. Add an empty header with len == 0
 +		 * to signify a wrap around.
 +		 */
 +		memset(log_buf + log_next_idx, 0, sizeof(struct log));