kgess-mirror/freebsd-src
1
0
Fork 0
mirror of https://git.freebsd.org/src.git synced 2026-01-12 06:54:03 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

bus_attach_children.9: New manpage for functions operating on children

Browse source 
This documents bus_attach_children, bus_delayed_attach_children,
bus_detach_children, bus_enumerate_hinted_children, and
bus_identify_children.

Differential Revision:	https://reviews.freebsd.org/D48368
This commit is contained in:
John Baldwin 2025-02-05 14:46:56 -05:00
parent 3f93f96c26
commit 192d326bcf
5 changed files with 164 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
share/man/man9/BUS_HINTED_CHILD.9
View file

@ -2,7 +2,7 @@
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2025 John Baldwin <jhb@FreeBSD.org>
.Dd January 6, 2025
.Dd February 5, 2025
.Dt BUS_HINTED_CHILD 9
.Os
.Sh NAME
@ -28,6 +28,7 @@ If so, a new device should be added via
.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

5
share/man/man9/DEVICE_ATTACH.9
View file

@ -26,7 +26,7 @@
.\" (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 January 15, 2017
.Dd February 5, 2025
.Dt DEVICE_ATTACH 9
.Os
.Sh NAME
@ -53,12 +53,13 @@ Devices which implement buses should use this method to probe for
the existence of devices attached to the bus and add them as
children.
If this is combined with the use of
.Xr bus_generic_attach 9
.Xr bus_attach_children 9
the child devices will be automatically probed and attached.
.Sh RETURN VALUES
Zero is returned on success, otherwise an appropriate error is returned.
.Sh SEE ALSO
.Xr devfs 4 ,
.Xr bus_attach_children 9 ,
.Xr device 9 ,
.Xr DEVICE_DETACH 9 ,
.Xr DEVICE_IDENTIFY 9 ,

3
share/man/man9/DEVICE_IDENTIFY.9
View file

@ -26,7 +26,7 @@
.\" (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 January 9, 2025
.Dd February 5, 2025
.Dt DEVICE_IDENTIFY 9
.Os
.Sh NAME
@ -82,6 +82,7 @@ foo_identify(driver_t *driver, device_t parent)
.Ed
.Sh SEE ALSO
.Xr BUS_ADD_CHILD 9 ,
.Xr bus_identify_children 9 ,
.Xr bus_set_resource 9 ,
.Xr device 9 ,
.Xr device_find_child 9

5
share/man/man9/Makefile
View file

@ -28,6 +28,7 @@ MAN= accept_filter.9 \
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 @@ MLINKS+=buf_ring.9 buf_ring_alloc.9 \
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_CONFIG_INTR.9 bus_config_intr.9
MLINKS+=BUS_DESCRIBE_INTR.9 bus_describe_intr.9

152
share/man/man9/bus_attach_children.9 Normal file
View file

@ -0,0 +1,152 @@
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2025 John Baldwin <jhb@FreeBSD.org>
.Dd February 5, 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 .