d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

BUS_ADD_CHILD calls device_add_child. device_add_child does not call

Browse Source 
BUS_ADD_CHILD. Make it explicit since it follows the command paradigm
rather than the callback paradigm. Add other clarifying notes as well.
This commit is contained in:
Warner Losh 2015-10-28 19:11:06 +00:00
parent 668c0ec64f
commit c64c9b8e46
2 changed files with 30 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
share/man/man9/BUS_ADD_CHILD.9
View File

@ -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 ,

16
share/man/man9/device_add_child.9
View File

@ -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