svn commit: r222253 - head/sys/kern

[John Baldwin]

Author: jhb
Date: Tue May 24 13:22:40 2011
New Revision: 222253
URL: http://svn.freebsd.org/changeset/base/222253

Log:
  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

Modified:
  head/sys/kern/device_if.m

Modified: head/sys/kern/device_if.m
==============================================================================
--- head/sys/kern/device_if.m	Tue May 24 13:17:08 2011	(r222252)
+++ head/sys/kern/device_if.m	Tue May 24 13:22:40 2011	(r222253)
@@ -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