1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
<table class="head">
<tr>
<td class="head-ltitle">DEVICE_PROBE_AND_ATTACH(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">DEVICE_PROBE_AND_ATTACH(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">device_attach</code>,
<code class="Nm">device_detach</code>, <code class="Nm">device_probe</code>,
<code class="Nm">device_probe_and_attach</code> —
<span class="Nd">manage device's connection to a device driver</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/param.h</a>></code>
<br/>
<code class="In">#include <<a class="In">sys/bus.h</a>></code></p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">device_attach</code>(<var class="Fa" style="white-space: nowrap;">device_t
dev</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">device_detach</code>(<var class="Fa" style="white-space: nowrap;">device_t
dev</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">device_probe</code>(<var class="Fa" style="white-space: nowrap;">device_t
dev</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">device_probe_and_attach</code>(<var class="Fa" style="white-space: nowrap;">device_t
dev</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">These functions manage the relationship between a device and
device drivers.</p>
<p class="Pp" id="device_probe"><a class="permalink" href="#device_probe"><code class="Fn">device_probe</code></a>()
invokes the <a class="Xr">DEVICE_PROBE(9)</a> method of each suitable driver
and to find the driver with the best match for <var class="Fa">dev</var>. If
a matching driver is found, <var class="Fa">dev</var> is set to the
<code class="Dv">DS_ALIVE</code> state and zero is returned. If
<var class="Fa">dev</var> is already attached to a device driver or has been
disabled via <a class="Xr">device_disable(9)</a>, then it will not be probed
and -1 is returned.</p>
<p class="Pp" id="device_attach"><a class="permalink" href="#device_attach"><code class="Fn">device_attach</code></a>()
fully attaches a device driver to <var class="Fa">dev</var>. This function
prints a description of the device and invokes the
<a class="Xr">DEVICE_ATTACH(9)</a> method. If the
<a class="Xr">DEVICE_ATTACH(9)</a> method succeeds,
<var class="Fa">dev</var> is set to the <code class="Dv">DS_ATTACHED</code>
state and zero is returned. If the <a class="Xr">DEVICE_ATTACH(9)</a> method
fails, <a class="Xr">BUS_CHILD_DETACHED(9)</a> is called and an error value
is returned.</p>
<p class="Pp" id="device_attach~2">If the device name and unit are disabled by a
hint,
<a class="permalink" href="#device_attach~2"><code class="Fn">device_attach</code></a>()
disables the device, demotes it to the <code class="Dv">DS_NOTPRESENT</code>
state, and returns <code class="Dv">ENXIO</code>. The device retains its
device name and unit and can be re-enabled via
<a class="Xr">devctl(8)</a>.</p>
<p class="Pp" id="device_probe_and_attach"><a class="permalink" href="#device_probe_and_attach"><code class="Fn">device_probe_and_attach</code></a>()
is a wrapper function around <code class="Fn">device_probe</code>() and
<code class="Fn">device_attach</code>() that fully initialises a device. If
<var class="Fa">dev</var> is already attached or disabled,
<code class="Fn">device_probe_and_attach</code>() leaves the device
unchanged and returns zero. Otherwise,
<code class="Fn">device_probe</code>() is used to identify a device driver
for <var class="Fa">dev</var> and <code class="Fn">device_attach</code>()
finalizes attaching the driver to <var class="Fa">dev</var>. Device drivers
should generally use this function to initialize a device rather than direct
calls to <code class="Fn">device_probe</code>() and
<code class="Fn">device_attach</code>().</p>
<p class="Pp" id="device_detach"><a class="permalink" href="#device_detach"><code class="Fn">device_detach</code></a>()
detaches the device driver from <var class="Fa">dev</var>. This function
invokes the <a class="Xr">DEVICE_DETACH(9)</a> method to tear down device
driver state for <var class="Fa">dev</var>. If the method fails, its error
value is returned and <var class="Fa">dev</var> remains attached. If the
method succeeds, otherwise, <a class="Xr">BUS_CHILD_DETACHED(9)</a> is
called, the device is set to the <code class="Dv">DS_NOTPRESENT</code>
state, and zero is returned. If a device is busy,
<code class="Fn">device_detach</code>() fails with
<code class="Dv">EBUSY</code> and leaving <var class="Fa">dev</var>
unchanged.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">Zero is returned on success, otherwise an appropriate error is
returned. In addition, <code class="Fn">device_probe</code>() returns -1 if
<var class="Fa">dev</var> is disabled or already attached.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">devctl(8)</a>,
<a class="Xr">BUS_CHILD_DETACHED(9)</a>, <a class="Xr">device(9)</a>,
<a class="Xr">DEVICE_ATTACH(9)</a>, <a class="Xr">DEVICE_DETACH(9)</a>,
<a class="Xr">DEVICE_PROBE(9)</a>, <a class="Xr">driver(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">This manual page was written by <span class="An">Doug
Rabson</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">February 5, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
