svn commit: r290119 - head/share/man/man9
Warner Losh
imp at FreeBSD.org
Wed Oct 28 19:11:08 UTC 2015
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
More information about the svn-src-head
mailing list