device_probe_and_attach.9: Document more device functions

Split out separate descriptions of device_probe and device_attach and
include extra details (such as the effect of a disabled hint during
device_attach).  Reframe device_probe_and_attach as a recommended
wrapper function around device_probe and device_attach.

While here, add a description of device_detach.

Differential Revision:	https://reviews.freebsd.org/D48364

share/man/man9/Makefile

@@ -1044,6 +1044,9 @@ MLINKS+=device_set_desc.9 device_get_desc.9 \
 	device_set_desc.9 device_set_descf.9 \
 	device_set_desc.9 device_set_desc_copy.9
 MLINKS+=device_set_flags.9 device_get_flags.9
+MLINKS+=device_probe_and_attach.9 device_attach.9 \
+	device_probe_and_attach.9 device_detach.9 \
+	device_probe_and_attach.9 device_probe.9
 MLINKS+=devstat.9 devicestat.9 \
 	devstat.9 devstat_new_entry.9 \
 	devstat.9 devstat_end_transaction.9 \

share/man/man9/device_probe_and_attach.9

@@ -26,33 +26,139 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 16, 1998
+.Dd February 5, 2025
 .Dt DEVICE_PROBE_AND_ATTACH 9
 .Os
 .Sh NAME
+.Nm device_attach ,
+.Nm device_detach ,
+.Nm device_probe ,
 .Nm device_probe_and_attach
-.Nd initialise a device
+.Nd manage device's connection to a device driver
 .Sh SYNOPSIS
 .In sys/param.h
 .In sys/bus.h
 .Ft int
+.Fn device_attach "device_t dev"
+.Ft int
+.Fn device_detach "device_t dev"
+.Ft int
+.Fn device_probe "device_t dev"
+.Ft int
 .Fn device_probe_and_attach "device_t dev"
 .Sh DESCRIPTION
-This function is called during autoconfiguration to initialise the
-devices in the system.
-For each device, the
+These functions manage the relationship between a device and device drivers.
+.Pp
+.Fn device_probe
+invokes the
 .Xr DEVICE_PROBE 9
-method of each suitable driver is called and if a probe succeeds, a
-description of the device is printed and the
+method of each suitable driver and to find the driver with the best match for
+.Fa dev .
+If a matching driver is found,
+.Fa dev
+is set to the
+.Dv DS_ALIVE
+state and zero is returned.
+If
+.Fa dev
+is already attached to a device driver or has been disabled via
+.Xr device_disable 9 ,
+then it will not be probed and -1 is returned.
+.Pp
+.Fn device_attach
+fully attaches a device driver to
+.Fa dev .
+This function prints a description of the device and invokes the
 .Xr DEVICE_ATTACH 9
-method is called.
-If the device is disabled using
-.Xr device_disable 9
-then it will not be probed.
+method.
+If the
+.Xr DEVICE_ATTACH 9
+method succeeds,
+.Fa dev
+is set to the
+.Dv DS_ATTACHED
+state and zero is returned.
+If the
+.Xr DEVICE_ATTACH 9
+method fails,
+.Xr BUS_CHILD_DETACHED 9
+is called and an error value is returned.
+.Pp
+If the device name and unit are disabled by a hint,
+.Fn device_attach
+disables the device, demotes it to the
+.Dv DS_NOTPRESENT
+state,
+and returns
+.Dv ENXIO .
+The device retains its device name and unit and can be re-enabled via
+.Xr devctl 8 .
+.Pp
+.Fn device_probe_and_attach
+is a wrapper function around
+.Fn device_probe
+and
+.Fn device_attach
+that fully initialises a device.
+If
+.Fa dev
+is already attached or disabled,
+.Fn device_probe_and_attach
+leaves the device unchanged and returns zero.
+Otherwise,
+.Fn device_probe
+is used to identify a device driver for
+.Fa dev
+and
+.Fn device_attach
+finalizes attaching the driver to
+.Fa dev .
+Device drivers should generally use this function to initialize a device
+rather than direct calls to
+.Fn device_probe
+and
+.Fn device_attach .
+.Pp
+.Fn device_detach
+detaches the device driver from
+.Fa dev .
+This function invokes the
+.Xr DEVICE_DETACH 9
+method to tear down device driver state for
+.Fa dev .
+If the method fails,
+its error value is returned and
+.Fa dev
+remains attached.
+If the method succeeds,
+otherwise,
+.Xr BUS_CHILD_DETACHED 9
+is called,
+the device is set to the
+.Dv DS_NOTPRESENT
+state,
+and zero is returned.
+If a device is busy,
+.Fn device_detach
+fails with
+.Dv EBUSY
+and leaving
+.Fa dev
+unchanged.
 .Sh RETURN VALUES
 Zero is returned on success, otherwise an appropriate error is returned.
+In addition,
+.Fn device_probe
+returns -1 if
+.Fa dev
+is disabled or already attached.
 .Sh SEE ALSO
+.Xr devctl 8 ,
+.Xr BUS_CHILD_DETACHED 9 ,
 .Xr device 9 ,
+.Xr DEVICE_ATTACH 9 ,
+.Xr DEVICE_DETACH 9 ,
+.Xr DEVICE_PROBE 9 ,
 .Xr driver 9
 .Sh AUTHORS
 This manual page was written by