File:  [DragonFly] / src / share / man / man9 / device.9
Revision 1.3: download - view: text, annotated - select for diffs
Sun Jul 27 05:36:06 2003 UTC (11 years, 3 months ago) by hmp
Branches: MAIN
CVS tags: HEAD
mdoc(7) assorted fixes:

	- Nuke usage of .Ar from Section 9.  The `.Ar' macro
	  should only be used for userland manual pages.

	- Replace usage of `.Ar' with `.Va' or `.Vt' as necessary.

    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.9,v 1.7.2.4 2001/08/17 13:08:54 ru Exp $
   30: .\" $DragonFly: src/share/man/man9/device.9,v 1.3 2003/07/27 05:36:06 hmp Exp $
   31: .\"
   32: .Dd June 16, 1998
   33: .Dt DEVICE 9
   34: .Os
   35: .Sh NAME
   36: .Nm device
   37: .Nd an abstract representation of a device
   38: .Sh SYNOPSIS
   39: .Vt typedef struct device *device_t ;
   40: .Sh DESCRIPTION
   41: The device object represents a piece of hardware attached to the
   42: system such as an expansion card, the bus which that card is plugged
   43: into, disk drives attached to the expansion card etc.
   44: The system defines one device,
   45: .Dv root_bus
   46: and all other devices are created dynamically during
   47: autoconfiguration.  Normally devices representing toplevel busses in
   48: the system (ISA, PCI etc.) will be attached directly to
   49: .Dv root_bus
   50: and other devices will be added as children of their relevant bus.
   51: .Pp
   52: The devices in a system form a tree.
   53: All devices except
   54: .Dv root_bus
   55: have a parent (see
   56: .Xr device_get_parent 9 ) .
   57: In addition, any device can have children attached to it (see
   58: .Xr device_add_child 9 ,
   59: .Xr device_add_child_ordered 9 ,
   60: .Xr device_find_child 9 ,
   61: .Xr device_get_children 9 ,
   62: and
   63: .Xr device_delete_child 9 ) .
   64: .Pp
   65: A device which has been successfully probed and attached to the
   66: system will also have a driver (see
   67: .Xr device_get_driver 9
   68: and
   69: .Xr driver 9 )
   70: and a devclass (see
   71: .Xr device_get_devclass 9
   72: and
   73: .Xr devclass 9 ) .
   74: Various other attributes of the device include a unit number (see
   75: .Xr device_get_unit 9 ) ,
   76: verbose description (normally supplied by the driver, see
   77: .Xr device_set_desc 9
   78: and
   79: .Xr device_get_desc 9 ) ,
   80: a set of bus-specific variables (see
   81: .Xr device_get_ivars 9 )
   82: and a set of driver-specific variables (see
   83: .Xr device_get_softc 9 ) .
   84: .Pp
   85: Devices can be in one of several states:
   86: .Bl -tag -width DS_NOTPRESENT
   87: .It Dv DS_NOTPRESENT
   88: the device has not been probed for existence or the probe failed
   89: .It Dv DS_ALIVE
   90: the device probe succeeded but not yet attached
   91: .It Dv DS_ATTACHED
   92: the device has been successfully attached
   93: .It Dv DS_BUSY
   94: the device is currently open
   95: .El
   96: .Pp
   97: The current state of the device can be determined by calling
   98: .Xr device_get_state 9 .
   99: .Sh SEE ALSO
  100: .Xr devclass 9 ,
  101: .Xr driver 9
  102: .Sh AUTHORS
  103: This man page was written by
  104: .An Doug Rabson .