1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 John Baldwin <jhb@FreeBSD.org> 5.Dd February 5, 2025 6.Dt BUS_ATTACH_CHILDREN 9 7.Os 8.Sh NAME 9.Nm bus_attach_children , 10.Nm bus_delayed_attach_children , 11.Nm bus_detach_children , 12.Nm bus_enumerate_hinted_children , 13.Nm bus_identify_children 14.Nd manage child devices of a bus device 15.Sh SYNOPSIS 16.In sys/param.h 17.In sys/bus.h 18.Ft void 19.Fn bus_attach_children "device_t dev" 20.Ft void 21.Fn bus_delayed_attach_children "device_t bus" 22.Ft int 23.Fn bus_detach_children "device_t dev" 24.Ft void 25.Fn bus_enumerate_hinted_children "device_t bus" 26.Ft void 27.Fn bus_identify_children "device_t dev" 28.Sh DESCRIPTION 29These functions manage state transitions of child devices for 30.Fa dev . 31.Pp 32.Fn bus_enumerate_hinted_children 33walks the kernel environment to identify any device hints that describe a 34device attached to 35.Fa dev . 36For each set of matching hints, 37the 38.Xr BUS_HINTED_CHILD 9 39method is invoked. 40This function is typically called from a bus driver's 41.Xr DEVICE_ATTACH 9 42method to add hinted devices. 43Note that most bus drivers do not use hints to identify child devices. 44This is typically used for legacy buses such as ISA that do not provide 45a mechanism for enumerating devices. 46.Pp 47.Fn bus_identify_children 48iterates over all eligible device drivers for children of 49.Fa dev 50invoking the 51.Xr DEVICE_IDENTIFY 9 52method. 53This allows device drivers to add child devices that are enumerated via 54alternate mechanisms such as firmware tables. 55This function is typically called from a bus driver's 56.Xr DEVICE_ATTACH 9 57method. 58.Pp 59.Fn bus_attach_children 60attaches device drivers to all children of 61.Fa dev . 62This function invokes 63.Xr device_probe_and_attach 9 64on each child device ignoring errors. 65It makes a best-effort pass to attach device drivers to all children. 66Child devices are attached in increasing order. 67Child devices with the same order are attached in FIFO order based 68on the time when the device was created via 69.Xr device_add_child 9 . 70This function is typically called from a bus driver's 71.Xr DEVICE_ATTACH 9 72method after adding devices. 73.Pp 74.Fn bus_delayed_attach_children 75attaches device drivers to all children of 76.Fa dev 77after interrupts are enabled. 78This function schedules a call to 79.Fn bus_attach_children 80after interrupts are enabled via 81.Xr config_intrhook_establish 9 . 82If interrupts are already enabled 83(for example, when loading a device driver after booting), 84.Fn bus_attach_children 85is called immediately. 86.Pp 87.Fn bus_detach_children 88detaches device drivers from all children of 89.Fa dev 90by calling 91.Xr device_detach 9 92on each child device. 93Unlike 94.Fn bus_attach_children , 95this function does not make a best-effort pass. 96If a child device fails to detach, 97.Fn bus_detach_children 98immediately fails returning the error from the child's failed detach. 99Child devices are detached in reverse order compared to 100.Fn bus_attach_children . 101That is, 102child devices are detached in decreasing order, 103and child devices with the same order are detached in LIFO order. 104Detached devices are not deleted. 105.Pp 106.Fn bus_detach_children 107is typically called at the start of a bus driver's 108.Xr DEVICE_ATTACH 9 109method to give child devices a chance to veto the detach request. 110It is usually paired with a later call to 111.Fn device_delete_children 9 112to delete child devices. 113If no additional logic is required between the two function calls, 114a bus driver can use 115.Xr bus_generic_detach 9 116to detach and delete children. 117.Sh RETURN VALUES 118.Sh SEE ALSO 119.Xr config_intrhook_establish 9 , 120.Xr device_add_child 9 , 121.Xr DEVICE_ATTACH 9 , 122.Xr device_delete_children 9 , 123.Xr DEVICE_DETACH 9 , 124.Xr device_detach 9 , 125.Xr DEVICE_IDENTIFY 9 , 126.Xr device_probe_and_attach 9 127.Sh HISTORY 128.Fn bus_enumerate_hinted_children 129first appeared in 130.Fx 6.2 . 131.Pp 132.Fn bus_delayed_attach_children 133first appeared in 134.Fx 12.2 . 135.Pp 136.Fn bus_identify_children 137first appeared in 138.Fx 15.0 . 139Its functionality is available in older releases via the deprecated 140.Fn bus_generic_probe . 141.Pp 142.Fn bus_attach_children 143first appeared in 144.Fx 15.0 . 145Its functionality is available in older releases via the deprecated 146.Fn bus_generic_attach . 147.Pp 148.Fn bus_detach_children 149first appeared in 150.Fx 15.0 . 151Its functionality is available in older releases via 152.Fn bus_generic_detach . 153