Page MenuHomeFreeBSD
Files F109258632

D48368.id148889.diff
No OneTemporary
Actions

D48368.id148889.diff
View Options

diff --git a/share/man/man9/BUS_HINTED_CHILD.9 b/share/man/man9/BUS_HINTED_CHILD.9
--- a/share/man/man9/BUS_HINTED_CHILD.9
+++ b/share/man/man9/BUS_HINTED_CHILD.9
@@ -28,6 +28,7 @@
.Xr BUS_ADD_CHILD 9 .
.Sh SEE ALSO
.Xr BUS_ADD_CHILD 9 ,
+.Xr bus_enumerate_hinted_children 9 ,
.Xr device 9
.Sh HISTORY
The
diff --git a/share/man/man9/DEVICE_IDENTIFY.9 b/share/man/man9/DEVICE_IDENTIFY.9
--- a/share/man/man9/DEVICE_IDENTIFY.9
+++ b/share/man/man9/DEVICE_IDENTIFY.9
@@ -82,6 +82,7 @@
.Ed
.Sh SEE ALSO
.Xr BUS_ADD_CHILD 9 ,
+.Xr bus_identify_children 9 ,
.Xr bus_set_resource 9 ,
.Xr device 9 ,
.Xr device_get_child 9
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -28,6 +28,7 @@
BUS_ADD_CHILD.9 \
bus_adjust_resource.9 \
bus_alloc_resource.9 \
+ bus_attach_children.9 \
BUS_BIND_INTR.9 \
bus_child_present.9 \
BUS_CHILD_DELETED.9 \
@@ -673,6 +674,10 @@
buf_ring.9 buf_ring_peek.9
MLINKS+=bus_activate_resource.9 bus_deactivate_resource.9
MLINKS+=bus_alloc_resource.9 bus_alloc_resource_any.9
+MLINKS+=bus_attach_children.9 bus_delayed_attach_children.9 \
+ bus_attach_children.9 bus_detach_children.9 \
+ bus_attach_children.9 bus_enumerate_hinted_children.9 \
+ bus_attach_children.9 bus_identify_children.9
MLINKS+=BUS_BIND_INTR.9 bus_bind_intr.9
MLINKS+=BUS_DESCRIBE_INTR.9 bus_describe_intr.9
MLINKS+=bus_dma.9 busdma.9 \
diff --git a/share/man/man9/bus_attach_children.9 b/share/man/man9/bus_attach_children.9
new file mode 100644
--- /dev/null
+++ b/share/man/man9/bus_attach_children.9
@@ -0,0 +1,152 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2025 John Baldwin <jhb@FreeBSD.org>
+.Dd January 6, 2025
+.Dt BUS_ATTACH_CHILDREN 9
+.Os
+.Sh NAME
+.Nm bus_attach_children ,
+.Nm bus_delayed_attach_children ,
+.Nm bus_detach_children ,
+.Nm bus_enumerate_hinted_children ,
+.Nm bus_identify_children
+.Nd manage child devices of a bus device
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/bus.h
+.Ft void
+.Fn bus_attach_children "device_t dev"
+.Ft void
+.Fn bus_delayed_attach_children "device_t bus"
+.Ft int
+.Fn bus_detach_children "device_t dev"
+.Ft void
+.Fn bus_enumerate_hinted_children "device_t bus"
+.Ft void
+.Fn bus_identify_children "device_t dev"
+.Sh DESCRIPTION
+These functions manage state transitions of child devices for
+.Fa dev .
+.Pp
+.Fn bus_enumerate_hinted_children
+walks the kernel environment to identify any device hints that describe a
+device attached to
+.Fa dev .
+For each set of matching hints,
+the
+.Xr BUS_HINTED_CHILD 9
+method is invoked.
+This function is typically called from a bus driver's
+.Xr 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.
+.Pp
+.Fn bus_identify_children
+iterates over all eligible device drivers for children of
+.Fa dev
+invoking the
+.Xr 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
+.Xr DEVICE_ATTACH 9
+method.
+.Pp
+.Fn bus_attach_children
+attaches device drivers to all children of
+.Fa dev .
+This function invokes
+.Xr 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
+.Xr device_add_child 9 .
+This function is typically called from a bus driver's
+.Xr DEVICE_ATTACH 9
+method after adding devices.
+.Pp
+.Fn bus_delayed_attach_children
+attaches device drivers to all children of
+.Fa dev
+after interrupts are enabled.
+This function schedules a call to
+.Fn bus_attach_children
+after interrupts are enabled via
+.Xr config_intrhook_establish 9 .
+If interrupts are already enabled
+(for example, when loading a device driver after booting),
+.Fn bus_attach_children
+is called immediately.
+.Pp
+.Fn bus_detach_children
+detaches device drivers from all children of
+.Fa dev
+by calling
+.Xr device_detach 9
+on each child device.
+Unlike
+.Fn bus_attach_children ,
+this function does not make a best-effort pass.
+If a child device fails to detach,
+.Fn bus_detach_children
+immediately fails returning the error from the child's failed detach.
+Child devices are detached in reverse order compared to
+.Fn 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.
+.Pp
+.Fn bus_detach_children
+is typically called at the start of a bus driver's
+.Xr DEVICE_ATTACH 9
+method to give child devices a chance to veto the detach request.
+It is usually paired with a later call to
+.Fn device_delete_children 9
+to delete child devices.
+If no additional logic is required between the two function calls,
+a bus driver can use
+.Xr bus_generic_detach 9
+to detach and delete children.
+.Sh RETURN VALUES
+.Sh SEE ALSO
+.Xr config_intrhook_establish 9 ,
+.Xr device_add_child 9 ,
+.Xr DEVICE_ATTACH 9 ,
+.Xr device_delete_children 9 ,
+.Xr device_detach 9 ,
+.Xr DEVICE_DETACH 9 ,
+.Xr DEVICE_IDENTIFY 9 ,
+.Xr device_probe_and_attach 9
+.Sh HISTORY
+.Fn bus_enumerate_hinted_children
+first appeared in
+.Fx 6.2 .
+.Pp
+.Fn bus_delayed_attach_children
+first appeared in
+.Fx 12.2 .
+.Pp
+.Fn bus_identify_children
+first appeared in
+.Fx 15.0 .
+Its functionality is available in older releases via the deprecated
+.Fn bus_generic_probe .
+.Pp
+.Fn bus_attach_children
+first appeared in
+.Fx 15.0 .
+Its functionality is available in older releases via the deprecated
+.Fn bus_generic_attach .
+.Pp
+.Fn bus_detach_children
+first appeared in
+.Fx 15.0 .
+Its functionality is available in older releases via
+.Fn bus_generic_detach .

File Metadata

Mime Type
text/plain
Expires
Mon, Feb 3, 5:22 PM (7 h, 3 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
16439461
Default Alt Text
D48368.id148889.diff (5 KB)

Event Timeline