printk: update documentation

1 files changed, 40 insertions, 37 deletions

diff --git a/printk.patch b/printk.patch
index aef7e74..2b3b082 100644
--- a/printk.patch
+++ b/printk.patch
@@ -120,8 +120,8 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  drivers/base/core.c    |   49 +
  drivers/char/mem.c     |   40 -
  include/linux/printk.h |   13 
- kernel/printk.c        | 1391 +++++++++++++++++++++++++++++++++----------------
- 4 files changed, 1024 insertions(+), 469 deletions(-)
+ kernel/printk.c        | 1394 +++++++++++++++++++++++++++++++++----------------
+ 4 files changed, 1027 insertions(+), 469 deletions(-)
 
 --- a/drivers/base/core.c
 +++ b/drivers/base/core.c
@@ -325,7 +325,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
   * If exclusive_console is non-NULL then only this console is to be printed to.
   */
  static struct console *exclusive_console;
-@@ -146,12 +127,546 @@ EXPORT_SYMBOL(console_set_on_cmdline);
+@@ -146,12 +127,549 @@ EXPORT_SYMBOL(console_set_on_cmdline);
  static int console_may_schedule;
  
  #ifdef CONFIG_PRINTK
@@ -335,12 +335,14 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + * the overall length of the record.
 + *
 + * The heads to the first and last entry in the buffer, as well as the
-+ * sequence numbers of these both entries are maintained.
++ * sequence numbers of these both entries are maintained when messages
++ * are stored..
 + *
-+ * If the heads indicate available messages, a length == 0 for the next
-+ * message indicates a wrap-around to the beginning of the buffer.
++ * If the heads indicate available messages, the length in the header
++ * tells the start next message. A length == 0 for the next message
++ * indicates a wrap-around to the beginning of the buffer.
 + *
-+ * Every record carries the monotonic timestamp in nanoseconds, as well as
++ * Every record carries the monotonic timestamp in microseconds, as well as
 + * the standard userspace syslog level and syslog facility. The usual
 + * kernel messages use LOG_KERN; userspace-injected messages always carry
 + * a matching syslog facility, by default LOG_USER. The origin of every
@@ -363,7 +365,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + *   SUBSYSTEM=pci              driver-core subsystem name
 + *
 + * 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
++ * follows directly after a '=' character. Every property is terminated by
 + * a '\n' character.
 + *
 + * Any value that can possibly carry non-printable characters must be
@@ -379,7 +381,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + * 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.
++ * the dictionary MUST be encoded as binary to avoid such problems.
 + *
 + * Example of a message structure:
 + *   0000  ff 8f 00 00 00 00 00 00      monotonic time in nsec
@@ -397,12 +399,13 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
 + *   0032        00 00 00 00 00 00      padding to next message header
 + *
 + * The 'struct log' buffer header must never be directly exported to
-+ * userspace, it is a kernel-private implementation detail.
++ * userspace, it is a kernel-private implementation detail that might
++ * need to be changed in the future, when the requirements change.
 + *
 + * The classic syslog() syscall format export must only export the human
 + * readable text message, with the syslog level and facility prefixed
-+ * as <>. Adding unconverted binary data would break the syslog() syscall
-+ * export format.
++ * as <>. Adding unconverted binary or structured data would break the
++ * syslog() export format.
 + *
 + * Interfaces that export the structured dictionary data, should follow the
 + * binary record format definition of the dictionary and use the following
@@ -875,7 +878,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  
  #ifdef CONFIG_KEXEC
  /*
-@@ -165,9 +680,9 @@ static int saved_console_loglevel = -1;
+@@ -165,9 +683,9 @@ static int saved_console_loglevel = -1;
  void log_buf_kexec_setup(void)
  {
  	VMCOREINFO_SYMBOL(log_buf);
@@ -887,7 +890,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  }
  #endif
  
-@@ -191,7 +706,6 @@ early_param("log_buf_len", log_buf_len_s
+@@ -191,7 +709,6 @@ early_param("log_buf_len", log_buf_len_s
  void __init setup_log_buf(int early)
  {
  	unsigned long flags;
@@ -895,7 +898,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  	char *new_log_buf;
  	int free;
  
-@@ -219,20 +733,8 @@ void __init setup_log_buf(int early)
+@@ -219,20 +736,8 @@ void __init setup_log_buf(int early)
  	log_buf_len = new_log_buf_len;
  	log_buf = new_log_buf;
  	new_log_buf_len = 0;
@@ -918,7 +921,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  	raw_spin_unlock_irqrestore(&logbuf_lock, flags);
  
  	pr_info("log_buf_len: %d\n", log_buf_len);
-@@ -332,11 +834,165 @@ static int check_syslog_permissions(int
+@@ -332,11 +837,165 @@ static int check_syslog_permissions(int
  	return 0;
  }
  
@@ -1087,7 +1090,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  	int error;
  
  	error = check_syslog_permissions(type, from_file);
-@@ -364,28 +1020,14 @@ int do_syslog(int type, char __user *buf
+@@ -364,28 +1023,14 @@ int do_syslog(int type, char __user *buf
  			goto out;
  		}
  		error = wait_event_interruptible(log_wait,
@@ -1119,7 +1122,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  		/* FALL THRU */
  	/* Read last kernel messages */
  	case SYSLOG_ACTION_READ_ALL:
-@@ -399,52 +1041,11 @@ int do_syslog(int type, char __user *buf
+@@ -399,52 +1044,11 @@ int do_syslog(int type, char __user *buf
  			error = -EFAULT;
  			goto out;
  		}
@@ -1174,7 +1177,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  	/* Disable logging to console */
  	case SYSLOG_ACTION_CONSOLE_OFF:
  		if (saved_console_loglevel == -1)
-@@ -472,7 +1073,33 @@ int do_syslog(int type, char __user *buf
+@@ -472,7 +1076,33 @@ int do_syslog(int type, char __user *buf
  		break;
  	/* Number of chars in the log buffer */
  	case SYSLOG_ACTION_SIZE_UNREAD:
@@ -1209,7 +1212,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  		break;
  	/* Size of the log buffer */
  	case SYSLOG_ACTION_SIZE_BUFFER:
-@@ -501,29 +1128,11 @@ void kdb_syslog_data(char *syslog_data[4
+@@ -501,29 +1131,11 @@ void kdb_syslog_data(char *syslog_data[4
  {
  	syslog_data[0] = log_buf;
  	syslog_data[1] = log_buf + log_buf_len;
@@ -1241,7 +1244,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  static bool __read_mostly ignore_loglevel;
  
  static int __init ignore_loglevel_setup(char *str)
-@@ -540,142 +1149,33 @@ MODULE_PARM_DESC(ignore_loglevel, "ignor
+@@ -540,142 +1152,33 @@ MODULE_PARM_DESC(ignore_loglevel, "ignor
  	"print all kernel messages to the console.");
  
  /*
@@ -1403,7 +1406,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  }
  
  /*
-@@ -700,16 +1200,6 @@ static void zap_locks(void)
+@@ -700,16 +1203,6 @@ static void zap_locks(void)
  	sema_init(&console_sem, 1);
  }
  
@@ -1420,7 +1423,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  /* Check if we have any console registered that can be called early in boot. */
  static int have_callable_console(void)
  {
-@@ -722,51 +1212,6 @@ static int have_callable_console(void)
+@@ -722,51 +1215,6 @@ static int have_callable_console(void)
  	return 0;
  }
  
@@ -1472,7 +1475,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  /*
   * Can we actually use the console at this time on this cpu?
   *
-@@ -810,17 +1255,12 @@ static int console_trylock_for_printk(un
+@@ -810,17 +1258,12 @@ static int console_trylock_for_printk(un
  			retval = 0;
  		}
  	}
@@ -1491,7 +1494,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  
  int printk_delay_msec __read_mostly;
  
-@@ -836,15 +1276,22 @@ static inline void printk_delay(void)
+@@ -836,15 +1279,22 @@ static inline void printk_delay(void)
  	}
  }
  
@@ -1521,7 +1524,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  
  	boot_delay_msec();
  	printk_delay();
-@@ -856,7 +1303,7 @@ asmlinkage int vprintk(const char *fmt,
+@@ -856,7 +1306,7 @@ asmlinkage int vprintk(const char *fmt,
  	/*
  	 * Ouch, printk recursed into itself!
  	 */
@@ -1530,7 +1533,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  		/*
  		 * If a crash is occurring during printk() on this CPU,
  		 * then try to get the crash message out but make sure
-@@ -873,97 +1320,92 @@ asmlinkage int vprintk(const char *fmt,
+@@ -873,97 +1323,92 @@ asmlinkage int vprintk(const char *fmt,
  
  	lockdep_off();
  	raw_spin_lock(&logbuf_lock);
@@ -1699,7 +1702,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  	 */
  	if (console_trylock_for_printk(this_cpu))
  		console_unlock();
-@@ -974,12 +1416,73 @@ out_restore_irqs:
+@@ -974,12 +1419,73 @@ out_restore_irqs:
  
  	return printed_len;
  }
@@ -1775,7 +1778,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  {
  }
  
-@@ -1217,7 +1720,7 @@ int is_console_locked(void)
+@@ -1217,7 +1723,7 @@ int is_console_locked(void)
  }
  
  /*
@@ -1784,7 +1787,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
   */
  #define PRINTK_BUF_SIZE		512
  
-@@ -1253,6 +1756,10 @@ void wake_up_klogd(void)
+@@ -1253,6 +1759,10 @@ void wake_up_klogd(void)
  		this_cpu_or(printk_pending, PRINTK_PENDING_WAKEUP);
  }
  
@@ -1795,7 +1798,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  /**
   * console_unlock - unlock the console system
   *
-@@ -1263,15 +1770,16 @@ void wake_up_klogd(void)
+@@ -1263,15 +1773,16 @@ void wake_up_klogd(void)
   * by printk().  If this is the case, console_unlock(); emits
   * the output prior to releasing the lock.
   *
@@ -1815,7 +1818,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  
  	if (console_suspended) {
  		up(&console_sem);
-@@ -1281,17 +1789,41 @@ void console_unlock(void)
+@@ -1281,17 +1792,41 @@ void console_unlock(void)
  	console_may_schedule = 0;
  
  again:
@@ -1865,7 +1868,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  		start_critical_timings();
  		local_irq_restore(flags);
  	}
-@@ -1312,8 +1844,7 @@ again:
+@@ -1312,8 +1847,7 @@ again:
  	 * flush, no worries.
  	 */
  	raw_spin_lock(&logbuf_lock);
@@ -1875,7 +1878,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  	raw_spin_unlock_irqrestore(&logbuf_lock, flags);
  
  	if (retry && console_trylock())
-@@ -1549,7 +2080,8 @@ void register_console(struct console *ne
+@@ -1549,7 +2083,8 @@ void register_console(struct console *ne
  		 * for us.
  		 */
  		raw_spin_lock_irqsave(&logbuf_lock, flags);
@@ -1885,7 +1888,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  		raw_spin_unlock_irqrestore(&logbuf_lock, flags);
  		/*
  		 * We're about to replay the log buffer.  Only do this to the
-@@ -1758,6 +2290,9 @@ int kmsg_dump_unregister(struct kmsg_dum
+@@ -1758,6 +2293,9 @@ int kmsg_dump_unregister(struct kmsg_dum
  }
  EXPORT_SYMBOL_GPL(kmsg_dump_unregister);
  
@@ -1895,7 +1898,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  /**
   * kmsg_dump - dump kernel log to kernel message dumpers.
   * @reason: the reason (oops, panic etc) for dumping
-@@ -1767,8 +2302,7 @@ EXPORT_SYMBOL_GPL(kmsg_dump_unregister);
+@@ -1767,8 +2305,7 @@ EXPORT_SYMBOL_GPL(kmsg_dump_unregister);
   */
  void kmsg_dump(enum kmsg_dump_reason reason)
  {
@@ -1905,7 +1908,7 @@ Signed-off-by: Kay Sievers <kay@vrfy.org>
  	struct kmsg_dumper *dumper;
  	const char *s1, *s2;
  	unsigned long l1, l2;
-@@ -1780,24 +2314,27 @@ void kmsg_dump(enum kmsg_dump_reason rea
+@@ -1780,24 +2317,27 @@ void kmsg_dump(enum kmsg_dump_reason rea
  	/* Theoretically, the log could move on after we do this, but
  	   there's not a lot we can do about that. The new messages
  	   will overwrite the start of what we dump. */