DEVICE_PROBE_AND_ATTACH(9)                   FreeBSD Kernel Developer's Manual

NAME

     device_attach, device_detach, device_probe, device_probe_and_attach -
     manage device's connection to a device driver

SYNOPSIS

     #include <sys/param.h>
     #include <sys/bus.h>

     int
     device_attach(device_t dev);

     int
     device_detach(device_t dev);

     int
     device_probe(device_t dev);

     int
     device_probe_and_attach(device_t dev);

DESCRIPTION

     These functions manage the relationship between a device and device
     drivers.

     device_probe() invokes the DEVICE_PROBE(9) method of each suitable driver
     and to find the driver with the best match for dev.  If a matching driver
     is found, dev is set to the DS_ALIVE state and zero is returned.  If dev
     is already attached to a device driver or has been disabled via
     device_disable(9), then it will not be probed and -1 is returned.

     device_attach() fully attaches a device driver to dev.  This function
     prints a description of the device and invokes the DEVICE_ATTACH(9)
     method.  If the DEVICE_ATTACH(9) method succeeds, dev is set to the
     DS_ATTACHED state and zero is returned.  If the DEVICE_ATTACH(9) method
     fails, BUS_CHILD_DETACHED(9) is called and an error value is returned.

     If the device name and unit are disabled by a hint, device_attach()
     disables the device, demotes it to the DS_NOTPRESENT state, and returns
     ENXIO.  The device retains its device name and unit and can be re-enabled
     via devctl(8).

     device_probe_and_attach() is a wrapper function around device_probe() and
     device_attach() that fully initialises a device.  If dev is already
     attached or disabled, device_probe_and_attach() leaves the device
     unchanged and returns zero.  Otherwise, device_probe() is used to
     identify a device driver for dev and device_attach() finalizes attaching
     the driver to dev.  Device drivers should generally use this function to
     initialize a device rather than direct calls to device_probe() and
     device_attach().

     device_detach() detaches the device driver from dev.  This function
     invokes the DEVICE_DETACH(9) method to tear down device driver state for
     dev.  If the method fails, its error value is returned and dev remains
     attached.  If the method succeeds, otherwise, BUS_CHILD_DETACHED(9) is
     called, the device is set to the DS_NOTPRESENT state, and zero is
     returned.  If a device is busy, device_detach() fails with EBUSY and
     leaving dev unchanged.

RETURN VALUES

     Zero is returned on success, otherwise an appropriate error is returned.
     In addition, device_probe() returns -1 if dev is disabled or already
     attached.

SEE ALSO

     devctl(8), BUS_CHILD_DETACHED(9), device(9), DEVICE_ATTACH(9),
     DEVICE_DETACH(9), DEVICE_PROBE(9), driver(9)

AUTHORS

     This manual page was written by Doug Rabson.

FreeBSD 15.1-STABLE-HBSD       February 5, 2025     DEVICE_PROBE_AND_ATTACH(9)