From nobody Wed Feb 05 19:49:49 2025 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4Yp9mt6HjZz5mHq5; Wed, 05 Feb 2025 19:49:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Yp9mt0YPxz3v4V; Wed, 05 Feb 2025 19:49:50 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1738784990; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Exv6Y16oYaatv7Mcdb7egmgY/7p0yujNYKdFPfB3x3E=; b=vHQum7h10ew1sGKYDKDzUxsqmLH9HbS0F5a+ThB+phTPNNTb4apdmG65H8rvSCXsrAlvqg TOl7KcunqeCz9yHsanMpAM3zWKFifd+Ab9WtN2At73JJUGOQqehTc6oD4bOrlkl4eTr6QU H9O533BPnjUdDgAtC9tMQepbvhuGMSUw0NFJXHKGSiNykwaXUIoVEdv9CaL7dpUFKXYVPL 0Rc+qmUGveB6fUhYkp+zPUaqTpKx+YpDmH0gar+U+E2V08e14lqTU+MZWiKNFEVI4289Qh Ne0THq7PbGX48MmGOVNCZL9KwTkR81SkJEx1jHZXmoVeHekWqxhqbDLSDsdPKA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1738784990; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Exv6Y16oYaatv7Mcdb7egmgY/7p0yujNYKdFPfB3x3E=; b=Jim8tJAy4K1qrCxbENXrvhMbk4KhfLeW0rrZBXLC3wxMDGZkgCTb+Vya1YIrYG+39KInTC S9RUz0I92vrOGDpgn2PAflic5hRrEfn1CEGjCWo7THCmSiOaq3ALfTqiY4sBz2DqVcCMl9 tdwaqzgblqAapexPgd4KEjC2cBgkyZqlSqk0tf2yxdLnysSuXrtKHSlsniNoOgsrs/qWUi M5bDoLKNNG9TzEm6Ql8sWnGdAdEf4adx17BluJHMIwnLuD1+XJz+WiWcJosxq/xiMkTWYP 11J4WJJLPDtqqExEqgkHVYLqPnTlLSlZDUbnI8n/TmcMQwl71eg5hPaqrORelA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1738784990; a=rsa-sha256; cv=none; b=av4rpT/lv34vni1BaBB8c4lxJLPlmKtTfuVXsIqvJMjxnsZyunU030ZRIq0WC0tejidQyn xP94pMoaaxO4SAQzr/ndraNUIu/B837OFBZ5CuzUavxqQ1KcGI1GDb73HUkJlAylFHN7fa HAL0pFae2D9wnTkNYKfJF+vhCmXqgknnclzC6KoC+khtFDrHmqiowUZYwdbOmKRU8umsRq PblAwysInz0U6JfC7l0h7lDsM/ctNCZ7JHNn0eNf7PCDPKruWSEszGvHRY4B85h2JYGUHE Sbkcf2KJDnIjH8HZyInJZVQeUlgup4mEtRv3dR53ekgasOQv8H0cnf6Qj61P1Q== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4Yp9mt043Pz14wH; Wed, 05 Feb 2025 19:49:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 515Jnnrk070317; Wed, 5 Feb 2025 19:49:49 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 515Jnnaf070314; Wed, 5 Feb 2025 19:49:49 GMT (envelope-from git) Date: Wed, 5 Feb 2025 19:49:49 GMT Message-Id: <202502051949.515Jnnaf070314@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: John Baldwin Subject: git: 192d326bcff5 - main - bus_attach_children.9: New manpage for functions operating on children List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: jhb X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 192d326bcff5eef736cfb55fb4568d967b958893 Auto-Submitted: auto-generated The branch main has been updated by jhb: URL: https://cgit.FreeBSD.org/src/commit/?id=192d326bcff5eef736cfb55fb4568d967b958893 commit 192d326bcff5eef736cfb55fb4568d967b958893 Author: John Baldwin AuthorDate: 2025-02-05 19:46:56 +0000 Commit: John Baldwin CommitDate: 2025-02-05 19:47:38 +0000 bus_attach_children.9: New manpage for functions operating on children 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 --- share/man/man9/BUS_HINTED_CHILD.9 | 3 +- share/man/man9/DEVICE_ATTACH.9 | 5 +- share/man/man9/DEVICE_IDENTIFY.9 | 3 +- share/man/man9/Makefile | 5 ++ share/man/man9/bus_attach_children.9 | 152 +++++++++++++++++++++++++++++++++++ 5 files changed, 164 insertions(+), 4 deletions(-) diff --git a/share/man/man9/BUS_HINTED_CHILD.9 b/share/man/man9/BUS_HINTED_CHILD.9 index 699bb06e8dd8..860ee3a995e3 100644 --- a/share/man/man9/BUS_HINTED_CHILD.9 +++ b/share/man/man9/BUS_HINTED_CHILD.9 @@ -2,7 +2,7 @@ .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2025 John Baldwin -.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 diff --git a/share/man/man9/DEVICE_ATTACH.9 b/share/man/man9/DEVICE_ATTACH.9 index 083a0e86f0bc..8e7c46252a6f 100644 --- a/share/man/man9/DEVICE_ATTACH.9 +++ b/share/man/man9/DEVICE_ATTACH.9 @@ -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 , diff --git a/share/man/man9/DEVICE_IDENTIFY.9 b/share/man/man9/DEVICE_IDENTIFY.9 index b10d94143050..31063ae60dff 100644 --- a/share/man/man9/DEVICE_IDENTIFY.9 +++ b/share/man/man9/DEVICE_IDENTIFY.9 @@ -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 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 3054e5b3e9bd..d110ecec0832 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -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 diff --git a/share/man/man9/bus_attach_children.9 b/share/man/man9/bus_attach_children.9 new file mode 100644 index 000000000000..5e3ca4c5e906 --- /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 +.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 .