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

1 files changed, 15 insertions, 1 deletions

diff --git a/sys/kern/bus_if.m b/sys/kern/bus_if.m
index f0115e8670a2..aeaa5ce60467 100644
--- a/sys/kern/bus_if.m
+++ b/sys/kern/bus_if.m
@@ -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