Document the formatting requirements of location of pnpinfo strings.

[jhb]

Summary

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.

For example, PCI bus events have been broken since the location string
was changed to use a bare 'pciD.B.S.F' as the location string.

Test Plan

• try to create a devd script to load if_ral when inserting a ral pci-express card and realize devd doesn't parse any variables out of the nomatch event via devd -d

[imp]

sys/kern/bus_if.m

541 ↗

(On Diff #15990)

The parser recognizes \" as an escape. PC Card uses this. If devd's parser is broken, then we need to fix it.

568 ↗

(On Diff #15990)

See above.

[jhb]

sys/kern/bus_if.m

541 ↗

(On Diff #15990)

Which PC-Card parser, one in pccardd? devd's parser (which is the only one I'm aware of for these strings) is:

bool
config::chop_var(char *&buffer, char *&lhs, char *&rhs) const
{
   ...
        walker++;               // skip =
        if (*walker == '"') {
                walker++;       // skip "
                rhs = walker;
                while (*walker && *walker != '"')
                        walker++;
                if (*walker != '"')
                        return (false);
                rhs[-2] = '\0';
                *walker++ = '\0';

Once that sees the first '"' in the value it just eats everything up to the second '"'. It does not check if the '"' was preceded by a '\'.

[imp]

sys/kern/bus_if.m

541 ↗

(On Diff #15990)

Then I need to fix that. The PC Card bus code currently quotes the " with \ when it encounters them.

[jhb]

sys/kern/bus_if.m

541 ↗

(On Diff #15990)

Ah, I see. All the more reason to have some methods in libdevinfo to parse these out perhaps. :) (By which I mean methods that accept the string as input and return an nvlist as output. devd could map the nvlist into the vector it uses, or it could just use the nvlist directly perhaps)

[jhb]

sys/kern/bus_if.m

541 ↗

(On Diff #15990)

Hmm, devctl_safe_quote() also needs to escape any '\' characters. Otherwise you can't have a '\' at the end of a value.

[jhb]

Update quoting rules.