From owner-svn-src-all@freebsd.org Wed Oct 28 19:11:08 2015 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 17EE5A20408; Wed, 28 Oct 2015 19:11:08 +0000 (UTC) (envelope-from imp@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id DF3651EBE; Wed, 28 Oct 2015 19:11:07 +0000 (UTC) (envelope-from imp@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id t9SJB6mQ076061; Wed, 28 Oct 2015 19:11:06 GMT (envelope-from imp@FreeBSD.org) Received: (from imp@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id t9SJB6nL076059; Wed, 28 Oct 2015 19:11:06 GMT (envelope-from imp@FreeBSD.org) Message-Id: <201510281911.t9SJB6nL076059@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: imp set sender to imp@FreeBSD.org using -f From: Warner Losh Date: Wed, 28 Oct 2015 19:11:06 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r290119 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 28 Oct 2015 19:11:08 -0000 Author: imp Date: Wed Oct 28 19:11:06 2015 New Revision: 290119 URL: https://svnweb.freebsd.org/changeset/base/290119 Log: BUS_ADD_CHILD calls device_add_child. device_add_child does not call BUS_ADD_CHILD. Make it explicit since it follows the command paradigm rather than the callback paradigm. Add other clarifying notes as well. Modified: head/share/man/man9/BUS_ADD_CHILD.9 head/share/man/man9/device_add_child.9 Modified: head/share/man/man9/BUS_ADD_CHILD.9 ============================================================================== --- head/share/man/man9/BUS_ADD_CHILD.9 Wed Oct 28 19:08:51 2015 (r290118) +++ head/share/man/man9/BUS_ADD_CHILD.9 Wed Oct 28 19:11:06 2015 (r290119) @@ -28,7 +28,7 @@ .\" .\" $FreeBSD$ .\" -.Dd May 13, 2004 +.Dd October 28, 2015 .Dt BUS_ADD_CHILD 9 .Os .Sh NAME @@ -44,6 +44,8 @@ The .Fn BUS_ADD_CHILD method is used by the driver identify routine to add devices to the tree. +It can also be used to add children to buses that implement this +routine in other contexts, although the behavior is bus specific. Please see .Xr device_add_child 9 for more details. @@ -53,18 +55,31 @@ however, the bus' .Fn BUS_ADD_CHILD is called. .Pp -Busses implementing +Buses implementing .Fn BUS_ADD_CHILD should insert the device into the tree using .Xr device_add_child 9 before adding things such as their own ivars and resource lists to the device. +.Fn BUS_ADD_CHILD +is not called by +.Xr device_add_child 9 . +.Fn BUS_ADD_CHILD +instead calls +.Xr device_add_child 9 . +.Pp +A panic will result when called for a bus that does not implement +.Fn BUS_ADD_CHILD . +Some buses require a special bus-specific routine to be called instead +of +.Fn BUS_ADD_CHILD . .Sh RETURN VALUES The .Fn BUS_ADD_CHILD method returns .Vt device_t added to the tree, or -.Dv NULL . +.Dv NULL +to indicate failure. .Sh SEE ALSO .Xr device 9 , .Xr device_add_child 9 , Modified: head/share/man/man9/device_add_child.9 ============================================================================== --- head/share/man/man9/device_add_child.9 Wed Oct 28 19:08:51 2015 (r290118) +++ head/share/man/man9/device_add_child.9 Wed Oct 28 19:11:06 2015 (r290119) @@ -28,7 +28,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 12, 2006 +.Dd October 28, 2015 .Dt DEVICE_ADD_CHILD 9 .Os .Sh NAME @@ -74,14 +74,14 @@ Normally unit numbers will be chosen aut unit number of .Dv -1 should be given. -When a specific unit number is desired (e.g.\& for wiring a particular +When a specific unit number is desired (e.g.,\& for wiring a particular piece of hardware to a pre-configured unit number), that unit should be passed. If the specified unit number is already allocated, a new unit will be allocated and a diagnostic message printed. .Pp If the devices attached to a bus must be probed in a specific order -(e.g.\& for the ISA bus some devices are sensitive to failed probe attempts +(e.g.,\& for the ISA bus some devices are sensitive to failed probe attempts of unrelated drivers and therefore must be probed first), the .Fa order @@ -109,10 +109,18 @@ Authors of bus drivers must likewise be when they are loaded and unloaded to avoid duplication of children devices. .Pp -Identify routines should use +When adding a child to another device node, such as in an identify +routine, use .Xr BUS_ADD_CHILD 9 instead of .Xr device_add_child 9 . +.Xr BUS_ADD_CHILD 9 +will call +.Xr device_add_child 9 +and add the proper bus-specific data to the new child. +.Fn device_add_child +does not call +.Xr BUS_ADD_CHILD 9 . .Sh RETURN VALUES The new device if successful, NULL otherwise. .Sh SEE ALSO