Page MenuHomeFreeBSD
Files F161793584

D48364.diff
No OneTemporary
Actions

D48364.diff
View Options

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1044,6 +1044,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
--- 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

File Metadata

Mime Type
text/plain
Expires
Tue, Jul 7, 10:14 PM (2 h, 37 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34815283
Default Alt Text
D48364.diff (4 KB)

Event Timeline