File:  [DragonFly] / src / share / man / man9 / device_add_child.9
Revision 1.3: download - view: text, annotated - select for diffs
Tue Jun 1 11:36:53 2004 UTC (10 years, 1 month ago) by hmp
Branches: MAIN
CVS tags: HEAD, DragonFly_Stable, DragonFly_Snap29Sep2004, DragonFly_Snap13Sep2004, DragonFly_RELEASE_2_0_Slip, DragonFly_RELEASE_2_0, DragonFly_RELEASE_1_8_Slip, DragonFly_RELEASE_1_8, DragonFly_RELEASE_1_6_Slip, DragonFly_RELEASE_1_6, DragonFly_RELEASE_1_4_Slip, DragonFly_RELEASE_1_4, DragonFly_RELEASE_1_2_Slip, DragonFly_RELEASE_1_2, DragonFly_RELEASE_1_12_Slip, DragonFly_RELEASE_1_12, DragonFly_RELEASE_1_10_Slip, DragonFly_RELEASE_1_10, DragonFly_Preview, DragonFly_1_0_REL, DragonFly_1_0_RC1, DragonFly_1_0A_REL
Remove '-*- nroff -*-'.

Lets make a habit not to put editor-related magic into our base
files.  They are redundant and useless.

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