BUS_ATTACH_CHILDREN(9)                       FreeBSD Kernel Developer's Manual

NAME

     bus_attach_children, bus_delayed_attach_children, bus_detach_children,
     bus_enumerate_hinted_children, bus_identify_children - manage child
     devices of a bus device

SYNOPSIS

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

     void
     bus_attach_children(device_t dev);

     void
     bus_delayed_attach_children(device_t bus);

     int
     bus_detach_children(device_t dev);

     void
     bus_enumerate_hinted_children(device_t bus);

     void
     bus_identify_children(device_t dev);

DESCRIPTION

     These functions manage state transitions of child devices for dev.

     bus_enumerate_hinted_children() walks the kernel environment to identify
     any device hints that describe a device attached to dev.  For each set of
     matching hints, the BUS_HINTED_CHILD(9) method is invoked.  This function
     is typically called from a bus driver's DEVICE_ATTACH(9) method to add
     hinted devices.  Note that most bus drivers do not use hints to identify
     child devices.  This is typically used for legacy buses such as ISA that
     do not provide a mechanism for enumerating devices.

     bus_identify_children() iterates over all eligible device drivers for
     children of dev invoking the DEVICE_IDENTIFY(9) method.  This allows
     device drivers to add child devices that are enumerated via alternate
     mechanisms such as firmware tables.  This function is typically called
     from a bus driver's DEVICE_ATTACH(9) method.

     bus_attach_children() attaches device drivers to all children of dev.
     This function invokes device_probe_and_attach(9) on each child device
     ignoring errors.  It makes a best-effort pass to attach device drivers to
     all children.  Child devices are attached in increasing order.  Child
     devices with the same order are attached in FIFO order based on the time
     when the device was created via device_add_child(9).  This function is
     typically called from a bus driver's DEVICE_ATTACH(9) method after adding
     devices.

     bus_delayed_attach_children() attaches device drivers to all children of
     dev after interrupts are enabled.  This function schedules a call to
     bus_attach_children() after interrupts are enabled via
     config_intrhook_establish(9).  If interrupts are already enabled (for
     example, when loading a device driver after booting),
     bus_attach_children() is called immediately.

     bus_detach_children() detaches device drivers from all children of dev by
     calling device_detach(9) on each child device.  Unlike
     bus_attach_children(), this function does not make a best-effort pass.
     If a child device fails to detach, bus_detach_children() immediately
     fails returning the error from the child's failed detach.  Child devices
     are detached in reverse order compared to bus_attach_children().  That
     is, child devices are detached in decreasing order, and child devices
     with the same order are detached in LIFO order.  Detached devices are not
     deleted.

     bus_detach_children() is typically called at the start of a bus driver's
     DEVICE_DETACH(9) method to give child devices a chance to veto the detach
     request.  It is usually paired with a later call to
     device_delete_children(9) to delete child devices.  If no additional
     logic is required between the two function calls, a bus driver can use
     bus_generic_detach(9) to detach and delete children.

RETURN VALUES

SEE ALSO

     config_intrhook_establish(9), device_add_child(9), DEVICE_ATTACH(9),
     device_delete_children(9), DEVICE_DETACH(9), device_detach(9),
     DEVICE_IDENTIFY(9), device_probe_and_attach(9)

HISTORY

     bus_enumerate_hinted_children() first appeared in FreeBSD 6.2.

     bus_delayed_attach_children() first appeared in FreeBSD 12.2.

     bus_identify_children() first appeared in FreeBSD 15.0.  Its
     functionality is available in older releases via the deprecated
     bus_generic_probe().

     bus_attach_children() first appeared in FreeBSD 15.0.  Its functionality
     is available in older releases via the deprecated bus_generic_attach().

     bus_detach_children() first appeared in FreeBSD 15.0.  Its functionality
     is available in older releases via bus_generic_detach().

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