File:  [DragonFly] / src / share / man / man9 / device_add_child.9
Revision 1.2: download - view: text, annotated - select for diffs
Tue Jun 17 04:37:01 2003 UTC (10 years, 10 months ago) by dillon
Branches: MAIN
CVS tags: HEAD
Add the DragonFly cvs id and perform general cleanups on cvs/rcs/sccs ids.  Most
ids have been removed from !lint sections and moved into comment sections.

    1: .\" -*- nroff -*-
    2: .\"
    3: .\" Copyright (c) 1998 Doug Rabson
    4: .\"
    5: .\" All rights reserved.
    6: .\"
    7: .\" This program is free software.
    8: .\"
    9: .\" Redistribution and use in source and binary forms, with or without
   10: .\" modification, are permitted provided that the following conditions
   11: .\" are met:
   12: .\" 1. Redistributions of source code must retain the above copyright
   13: .\"    notice, this list of conditions and the following disclaimer.
   14: .\" 2. Redistributions in binary form must reproduce the above copyright
   15: .\"    notice, this list of conditions and the following disclaimer in the
   16: .\"    documentation and/or other materials provided with the distribution.
   17: .\"
   18: .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
   19: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   20: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
   21: .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
   22: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
   23: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   24: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   25: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   26: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
   27: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   28: .\"
   29: .\" $FreeBSD: src/share/man/man9/device_add_child.9,v 1.8.2.5 2001/12/17 11:30:18 ru Exp $
   30: .\" $DragonFly: src/share/man/man9/device_add_child.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
   31: .\"
   32: .Dd June 16, 1998
   33: .Dt DEVICE_ADD_CHILD 9
   34: .Os
   35: .Sh NAME
   36: .Nm device_add_child ,
   37: .Nm device_add_child_ordered
   38: .Nd "add a new device as a child of an existing device"
   39: .Sh SYNOPSIS
   40: .In sys/param.h
   41: .In sys/bus.h
   42: .Ft device_t
   43: .Fn device_add_child "device_t dev" "const char *name" "int unit"
   44: .Ft device_t
   45: .Fn device_add_child_ordered "device_t dev" "int order" "const char *name" "int unit"
   46: .Sh DESCRIPTION
   47: Create a new child device of
   48: .Fa dev .
   49: The
   50: .Fa name
   51: and
   52: .Fa unit
   53: arguments specify the name and unit number of the device.
   54: If the name is unknown then the caller should pass
   55: .Dv NULL .
   56: If the unit is unknown then the caller should pass
   57: .Dv -1
   58: and the system will choose the next available unit number.
   59: .Pp
   60: The name of the device is used to determine which drivers might be
   61: appropriate for the device.  If a name is specified then only drivers
   62: of that name are probed.  If no name is given then all drivers for the
   63: owning bus are probed.
   64: .Pp
   65: This allows busses which can uniquely identify device instances (such
   66: as PCI) to allow each driver to check each device instance for a
   67: match.  For busses which rely on supplied probe hints where only one
   68: driver can have a change of probing the device, the driver name should
   69: specified as the device name.
   70: .Pp
   71: Normally unit numbers will be chosen automatically by the system and a
   72: unit number of
   73: .Dv -1
   74: should be given.
   75: When a specific unit number is desired (e.g. for wiring a particular
   76: piece of hardware to a pre-configured unit number), that unit should
   77: be passed.  If the specified unit number is already allocated, a new
   78: unit will be allocated and a diagnostic message printed.
   79: .Pp
   80: If the devices attached to a bus must be probed in a specific order
   81: (e.g. for the ISA bus some devices are sensitive to failed probe attempts
   82: of unrelated drivers and therefore must be probed first),
   83: the
   84: .Fa order
   85: argument of
   86: .Xr device_add_child_ordered 9
   87: should be used to specify a partial ordering.
   88: The new device will be added before any existing device with a greater
   89: order.
   90: If
   91: .Xr device_add_child 9
   92: is used, then the new child will be added as if its order was zero.
   93: .Sh RETURN VALUES
   94: The new device if successful, NULL otherwise.
   95: .Sh SEE ALSO
   96: .Xr device 9
   97: .Sh AUTHORS
   98: This man page was written by
   99: .An Doug Rabson .