diff options
author | jhb <jhb@FreeBSD.org> | 2011-05-24 13:22:40 +0000 |
---|---|---|
committer | jhb <jhb@FreeBSD.org> | 2011-05-24 13:22:40 +0000 |
commit | 4d0fe668f783d3ba8aff483a99e55b514bf9cba0 (patch) | |
tree | 888aafa91e59840eec766a5dccce40ab3acd2102 /sys/kern/device_if.m | |
parent | d73862793bc31f12208c877a64fee924896b3d1b (diff) | |
download | FreeBSD-src-4d0fe668f783d3ba8aff483a99e55b514bf9cba0.zip FreeBSD-src-4d0fe668f783d3ba8aff483a99e55b514bf9cba0.tar.gz |
Update comments for DEVICE_PROBE() to reflect that BUS_PROBE_DEFAULT is
now the preferred typical return value from a probe routine. Discourage
the use of 0 (BUS_PROBE_SPECIFIC) as it should be used very rarely.
Point the reader to the DEVICE_PROBE(9) manpage for more detailed notes
on possible probe return values.
Submitted by: Philip Soeberg philip-dev of soeberg net
Diffstat (limited to 'sys/kern/device_if.m')
-rw-r--r-- | sys/kern/device_if.m | 20 |
1 files changed, 11 insertions, 9 deletions
diff --git a/sys/kern/device_if.m b/sys/kern/device_if.m index 2931c0a..eb720eb 100644 --- a/sys/kern/device_if.m +++ b/sys/kern/device_if.m @@ -89,28 +89,29 @@ CODE { * the probe before returning. The return value of DEVICE_PROBE() * is used to elect which driver is used - the driver which returns * the largest non-error value wins the election and attaches to - * the device. + * the device. Common non-error values are described in the + * DEVICE_PROBE(9) manual page. * * If a driver matches the hardware, it should set the device * description string using device_set_desc() or - * device_set_desc_copy(). This string is - * used to generate an informative message when DEVICE_ATTACH() - * is called. + * device_set_desc_copy(). This string is used to generate an + * informative message when DEVICE_ATTACH() is called. * * As a special case, if a driver returns zero, the driver election * is cut short and that driver will attach to the device - * immediately. + * immediately. This should rarely be used. * - * For example, a probe method for a pci device driver might look + * For example, a probe method for a PCI device driver might look * like this: * * @code - * int foo_probe(device_t dev) + * int + * foo_probe(device_t dev) * { * if (pci_get_vendor(dev) == FOOVENDOR && * pci_get_device(dev) == FOODEVICE) { * device_set_desc(dev, "Foo device"); - * return (0); + * return (BUS_PROBE_DEFAULT); * } * return (ENXIO); * } @@ -125,7 +126,8 @@ CODE { * * @param dev the device to probe * - * @retval 0 if the driver strongly matches this device + * @retval 0 if this is the only possible driver for this + * device * @retval negative if the driver can match this device - the * least negative value is used to select the * driver |