Update the comments on values than can be returned by DEVICE_PROBE.

DEVICE_PROBE can return priorities.

Reviewed by:	Doug Rabson <dfr@nlsystems.com>

1 files changed, 27 insertions, 9 deletions

diff --git a/share/man/man9/DEVICE_PROBE.9 b/share/man/man9/DEVICE_PROBE.9
index 412c8a5..6c853bf 100644
--- a/share/man/man9/DEVICE_PROBE.9
+++ b/share/man/man9/DEVICE_PROBE.9
@@ -26,7 +26,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $Id$
+.\" $Id: DEVICE_PROBE.9,v 1.1 1998/09/03 21:52:04 dfr Exp $
 .\"
 .Dd June 16, 1998
 .Os
@@ -42,18 +42,36 @@
 .Fn DEVICE_PROBE "device_t dev"
 .Sh DESCRIPTION
 .Pp
-This device method should probe to see if the device is present.  If
-the device exists, the probe should return 0, otherwise ENXIO should
-be returned.  If some other error happens during the probe (such as a
-memory allocation failure), an appropriate error code should be returned.
+This device method should probe to see if the device is present.
+It should return 0 if the device exists, ENXIO if it cannot be
+found. If some other error happens during the probe (such as a memory
+allocation failure), an appropriate error code should be returned. For
+cases where more than one driver matches a device, a priority value can
+be returned.  In this case, success codes are values less than or equal
+to zero with the highest value representing the best match.  Failure
+codes are represented by positive values and the regular unix error
+codes should be used for the purpose.
 .Pp
-Devices which implement busses should use this method to probe for the
-existence of devices attached to the bus and add them as children.  If
-this is combined with the use of
+If a driver returns a success code which is less than zero, it must
+not assume that it will be the same driver which is attached to the
+device. In particular, it must not assume that any values stored in
+the softc structure will be available for its attach method and any
+resources allocated during probe must be released and re-allocated
+if the attach method is called. If a success code of zero is
+returned, the driver can assume that it will be the one attached.
+.Pp
+Devices which implement busses should use this method to probe for
+the existence of devices attached to the bus and add them as
+children. If this is combined with the use of
 .Xr bus_generic_attach 9
 the child devices will be automatically probed and attached.
 .Sh RETURN VALUES
-Zero is returned on success, otherwise an error is returned.
+A value equal to or less than zero indicates success, greater than
+zero indicates an error (errno). For values equal to or less than
+zero: zero indicates highest priority, no further probing is done;
+for a value less then zero, the lower the value the lower the
+priority, e.g. -100 indicates a lower priority than -50.
+
 .Sh SEE ALSO
 .Xr device 9 ,
 .Xr DEVICE_ATTACH 9