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.

2 files changed, 30 insertions, 7 deletions

diff --git a/share/man/man9/BUS_ADD_CHILD.9 b/share/man/man9/BUS_ADD_CHILD.9
index 8b69d5a..1e98ffe 100644
--- a/share/man/man9/BUS_ADD_CHILD.9
+++ b/share/man/man9/BUS_ADD_CHILD.9
@@ -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 ,
diff --git a/share/man/man9/device_add_child.9 b/share/man/man9/device_add_child.9
index 7ddd19a..052db92 100644
--- a/share/man/man9/device_add_child.9
+++ b/share/man/man9/device_add_child.9
@@ -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 automatically by the system and a
 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 careful when adding children
 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