svn commit: r300073 - head/sys/kern

[John Baldwin]

Author: jhb
Date: Tue May 17 19:34:07 2016
New Revision: 300073
URL: https://svnweb.freebsd.org/changeset/base/300073

Log:
  Document the formatting requirements of location and pnpinfo strings.
  
  devd requires location and pnpinfo strings generated by bus drivers
  to be formatted as a list of name=value keypairs.  Non-conforming
  bus drivers cause devd to mis-parse device events for these buses.
  
  Note that this documents the desired requirements.  devctl_safe_quote()
  doesn't yet escape backslash characters, and devd doesn't handle escaped
  characters in quoted values.
  
  Differential Revision:	https://reviews.freebsd.org/D6252

Modified:
  head/sys/kern/bus_if.m

Modified: head/sys/kern/bus_if.m
==============================================================================
--- head/sys/kern/bus_if.m	Tue May 17 19:00:09 2016	(r300072)
+++ head/sys/kern/bus_if.m	Tue May 17 19:34:07 2016	(r300073)
@@ -532,6 +532,13 @@ METHOD int child_present {
  *
  * Return it as a string.  If the string is insufficient for the
  * storage, then return EOVERFLOW.
+ *
+ * The string must be formatted as a space-separated list of
+ * name=value pairs.  Names may only contain alphanumeric characters,
+ * underscores ('_') and hyphens ('-').  Values can contain any
+ * non-whitespace characters.  Values containing whitespace can be
+ * quoted with double quotes ('"').  Double quotes and backslashes in
+ * quoted values can be escaped with backslashes ('\').
  * 
  * @param _dev		the parent device of @p _child
  * @param _child	the device which is being examined
@@ -551,7 +558,14 @@ METHOD int child_pnpinfo_str {
  *
  * Return it as a string.  If the string is insufficient for the
  * storage, then return EOVERFLOW.
- * 
+ *
+ * The string must be formatted as a space-separated list of
+ * name=value pairs.  Names may only contain alphanumeric characters,
+ * underscores ('_') and hyphens ('-').  Values can contain any
+ * non-whitespace characters.  Values containing whitespace can be
+ * quoted with double quotes ('"').  Double quotes and backslashes in
+ * quoted values can be escaped with backslashes ('\').
+ *
  * @param _dev		the parent device of @p _child
  * @param _child	the device which is being examined
  * @param _buf		the address of a buffer to receive the location