Document more clearly that a probe routine:

Should have no side effects
	Must not hold resources when it returns
	May be called multiple times if it returns < 0.

Remove the bad advise that the probe routine should look for children
for devices that implement busses.  This is more properly reserved for
the attach routine.
This commit is contained in:
Warner Losh 2004-04-11 06:37:21 +00:00
parent 1f51408ade
commit a545630488

View File

@ -64,15 +64,14 @@ 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.
In addition it is an absolute requirement that the probe routine have
no side effects whatsoever.
The probe routine may be called more than once before the attach
routine is called.
.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.
If a success code of zero is
returned, the driver can assume that it will be the one attached, but
must not hold any resources when the probe routine returns.
.Sh RETURN VALUES
A value equal to or less than zero indicates success, greater than
zero indicates an error (errno). For values equal to or less than
@ -81,6 +80,7 @@ for a value less than 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 ,
.Xr DEVICE_DETACH 9 ,
.Xr DEVICE_IDENTIFY 9 ,
.Xr DEVICE_SHUTDOWN 9