The branch main has been updated by jhb:
URL:
https://cgit.FreeBSD.org/src/commit/?id=d7fa71dfedd6db18ded3971c6f42b3699b5627d7
commit d7fa71dfedd6db18ded3971c6f42b3699b5627d7
Author: John Baldwin <j...@freebsd.org>
AuthorDate: 2025-02-05 19:44:57 +0000
Commit: John Baldwin <j...@freebsd.org>
CommitDate: 2025-02-05 19:45:41 +0000
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 | 3 +
share/man/man9/device_probe_and_attach.9 | 128 ++++++++++++++++++++++++++++---
2 files changed, 120 insertions(+), 11 deletions(-)
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 6af9880b8d57..3054e5b3e9bd 100644
--- a/share/man/man9/Makefile
+++ b/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 \
diff --git a/share/man/man9/device_probe_and_attach.9
b/share/man/man9/device_probe_and_attach.9
index 5d5de52cee66..0c438be3a483 100644
--- a/share/man/man9/device_probe_and_attach.9
+++ b/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.
+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 is called.
-If the device is disabled using
-.Xr device_disable 9
-then it will not be probed.
+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
