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

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