Add manpages for the new device framework.

1 files changed, 108 insertions, 0 deletions

diff --git a/share/man/man9/device_add_child.9 b/share/man/man9/device_add_child.9
new file mode 100644
index 0000000..0f4d172
--- /dev/null
+++ b/share/man/man9/device_add_child.9
@@ -0,0 +1,108 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 1998 Doug Rabson
+.\"
+.\" All rights reserved.
+.\"
+.\" This program is free software.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $Id$
+.\"
+.Dd June 16, 1998
+.Dt device_add_child 9
+.Os FreeBSD
+.Sh NAME
+.Nm device_add_child ,
+.Nm device_add_child_after
+.Nd add a new device as a child of an existing device
+.Sh SYNOPSIS
+.Fd #include <sys/param.h>
+.Fd #include <sys/bus.h>
+.Ft int
+.Fn bus_add_child "device_t dev" "const char *name" "int unit" "void *ivars"
+.Ft int
+.Fn bus_add_child_after "device_t dev" "device_t place" "const char *name" "int unit" "void *ivars"
+.Sh DESCRIPTION
+.Pp
+Create a new child device of
+.Fa dev .
+The
+.Fa name
+and
+.Fa unit
+arguments specify the name and unit number of the device.
+If the name is unknown then the caller should pass
+.Dv NULL .
+If the unit is unknown then the caller should pass 
+.Dv -1
+and the system will choose the next available unit number.
+If there is any bus-specific data associated with the new child device 
+(i.e. port numbers, irq settings etc.) then this should be supplied as 
+the
+.Fa ivars
+argument.
+.Pp
+The name of the device is used to determine which drivers might be
+appropriate for the device.  If a name is specified then only drivers
+of that name are probed.  If no name is given then all drivers for the 
+owning bus are probed.
+.Pp
+This allows busses which can uniquely identify device instances (such
+as PCI) to allow each driver to check each device instance for a
+match.  For busses which rely on supplied probe hints where only one
+driver can have a change of probing the device, the driver name should
+specified as the device name.
+.Pp
+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
+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 ISA bus devices which are sensitive to failed probe attempts 
+of unrelated drivers), the
+.Fa place
+argument of
+.Xr device_add_child_after 9
+should be used.  If
+.Dv NULL
+is passed, the new device will be added as the first child of
+.Fa dev ,
+otherwise it will be added immediately after
+.Fa place
+(which must be an existing child of
+.Fa dev )
+in the list of children.  If
+.Xr device_add_child 9
+is used, then the new child will be added at the end of the list.
+.Sh RETURN VALUES
+The new device if successful, NULL otherwise.
+.Sh SEE ALSO
+.Xr device 9
+.Sh AUTHORS
+This man page was written by
+.An Doug Rabson .