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