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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
<table class="head">
<tr>
<td class="head-ltitle">DISK(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">DISK(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">disk</code> — <span class="Nd">kernel disk
storage API</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">geom/geom_disk.h</a>></code></p>
<p class="Pp"><var class="Ft">struct disk *</var>
<br/>
<code class="Fn">disk_alloc</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">disk_create</code>(<var class="Fa" style="white-space: nowrap;">struct
disk *disk</var>, <var class="Fa" style="white-space: nowrap;">int
version</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">disk_gone</code>(<var class="Fa" style="white-space: nowrap;">struct
disk *disk</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">disk_destroy</code>(<var class="Fa" style="white-space: nowrap;">struct
disk *disk</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">disk_resize</code>(<var class="Fa" style="white-space: nowrap;">struct
disk *disk</var>, <var class="Fa" style="white-space: nowrap;">int
flags</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">disk_add_alias</code>(<var class="Fa" style="white-space: nowrap;">struct
disk *disk</var>, <var class="Fa" style="white-space: nowrap;">const char
*alias</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The disk storage API permits kernel device drivers providing
access to disk-like storage devices to advertise the device to other kernel
components, including <a class="Xr">GEOM(4)</a> and
<a class="Xr">devfs(4)</a>.</p>
<p class="Pp">Each disk device is described by a <var class="Vt">struct
disk</var> structure, which contains a variety of parameters for the disk
device, function pointers for various methods that may be performed on the
device, as well as private data storage for the device driver. In addition,
some fields are reserved for use by GEOM in managing access to the device
and its statistics.</p>
<p class="Pp" id="disk_alloc">GEOM has the ownership of <var class="Vt">struct
disk</var>, and drivers must allocate storage for it with the
<a class="permalink" href="#disk_alloc"><code class="Fn">disk_alloc</code></a>()
function, fill in the fields and call <code class="Fn">disk_create</code>()
when the device is ready to service requests.
<a class="permalink" href="#disk_add_alias"><code class="Fn" id="disk_add_alias">disk_add_alias</code></a>()
adds an alias for the disk and must be called before
<code class="Fn">disk_create</code>(), but may be called multiple times. For
each alias added, a device node will be created with
<a class="Xr">make_dev_alias(9)</a> in the same way primary device nodes are
created with <a class="Xr">make_dev(9)</a> for <var class="Va">d_name</var>
and <var class="Va">d_unit</var>. Care should be taken to ensure that only
one driver creates aliases for any given name.
<a class="permalink" href="#disk_resize"><code class="Fn" id="disk_resize">disk_resize</code></a>()
can be called by the driver after modifying
<var class="Va">d_mediasize</var> to notify GEOM about the disk capacity
change. The <var class="Fa">flags</var> field should be set to either
M_WAITOK, or M_NOWAIT. <code class="Fn">disk_gone</code>() orphans all of
the providers associated with the drive, setting an error condition of ENXIO
in each one. In addition, it prevents a re-taste on last close for writing
if an error condition has been set in the provider. After calling
<a class="permalink" href="#disk_destroy"><code class="Fn" id="disk_destroy">disk_destroy</code></a>(),
the device driver is not allowed to access the contents of
<var class="Vt">struct disk</var> anymore.</p>
<p class="Pp" id="disk_create">The
<a class="permalink" href="#disk_create"><code class="Fn">disk_create</code></a>()
function takes a second parameter, <var class="Fa">version</var>, which must
always be passed <code class="Dv">DISK_VERSION</code>. If GEOM detects that
the driver is compiled against an unsupported version, it will ignore the
device and print a warning on the console.</p>
<section class="Ss">
<h2 class="Ss" id="Descriptive_Fields"><a class="permalink" href="#Descriptive_Fields">Descriptive
Fields</a></h2>
<p class="Pp">The following fields identify the disk device described by the
structure instance, and must be filled in prior to submitting the structure
to <code class="Fn">disk_create</code>() and may not be subsequently
changed:</p>
<dl class="Bl-tag">
<dt><var class="Vt">u_int</var> <var class="Va">d_flags</var></dt>
<dd>Optional flags indicating to the storage framework what optional features
or descriptions the storage device driver supports. Currently supported
flags are <code class="Dv">DISKFLAG_OPEN</code> (maintained by storage
framework), <code class="Dv">DISKFLAG_CANDELETE</code> (maintained by
device driver), and <code class="Dv">DISKFLAG_CANFLUSHCACHE</code>
(maintained by device driver).</dd>
<dt><var class="Vt">const char *</var> <var class="Va">d_name</var></dt>
<dd>Holds the name of the storage device class, e.g.,
“<code class="Li">ahd</code>”. This value typically uniquely
identifies a particular driver device, and must not conflict with devices
serviced by other device drivers.</dd>
<dt><var class="Vt">u_int</var> <var class="Va">d_unit</var></dt>
<dd>Holds the instance of the storage device class, e.g.,
“<code class="Li">4</code>”. This namespace is managed by
the device driver, and assignment of unit numbers might be a property of
probe order, or in some cases topology. Together, the
<var class="Va">d_name</var> and <var class="Va">d_unit</var> values will
uniquely identify a disk storage device.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Disk_Device_Methods"><a class="permalink" href="#Disk_Device_Methods">Disk
Device Methods</a></h2>
<p class="Pp">The following fields identify various disk device methods, if
implemented:</p>
<dl class="Bl-tag">
<dt><var class="Vt">disk_open_t *</var> <var class="Va">d_open</var></dt>
<dd>Optional: invoked when the disk device is opened. If no method is
provided, open will always succeed.</dd>
<dt><var class="Vt">disk_close_t *</var> <var class="Va">d_close</var></dt>
<dd>Optional: invoked when the disk device is closed. Although an error code
may be returned, the call should always terminate any state setup by the
corresponding open method call.</dd>
<dt><var class="Vt">disk_strategy_t *</var>
<var class="Va">d_strategy</var></dt>
<dd>Mandatory: invoked when a new <var class="Vt">struct bio</var> is to be
initiated on the disk device.</dd>
<dt><var class="Vt">disk_ioctl_t *</var> <var class="Va">d_ioctl</var></dt>
<dd>Optional: invoked when an I/O control operation is initiated on the disk
device. Please note that for security reasons these operations should not
be able to affect other devices than the one on which they are
performed.</dd>
<dt><var class="Vt">dumper_t *</var> <var class="Va">d_dump</var></dt>
<dd>Optional: if configured with <a class="Xr">dumpon(8)</a>, this function is
invoked from a very restricted system state after a kernel panic to record
a copy of the system RAM to the disk.</dd>
<dt id="g_io_deliver"><var class="Vt">disk_getattr_t *</var>
<var class="Va">d_getattr</var></dt>
<dd>Optional: if this method is provided, it gives the disk driver the
opportunity to override the default GEOM response to BIO_GETATTR requests.
This function should return -1 if the attribute is not handled, 0 if the
attribute is handled, or an errno to be passed to
<a class="permalink" href="#g_io_deliver"><code class="Fn">g_io_deliver</code></a>().</dd>
<dt id="disk_gone"><var class="Vt">disk_gone_t *</var>
<var class="Va">d_gone</var></dt>
<dd>Optional: if this method is provided, it will be called after
<a class="permalink" href="#disk_gone"><code class="Fn">disk_gone</code></a>()
is called, once GEOM has finished its cleanup process. Once this callback
is called, it is safe for the disk driver to free all of its resources, as
it will not be receiving further calls from GEOM.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Mandatory_Media_Properties"><a class="permalink" href="#Mandatory_Media_Properties">Mandatory
Media Properties</a></h2>
<p class="Pp">The following fields identify the size and granularity of the disk
device. These fields must stay stable from return of the drivers open method
until the close method is called, but it is perfectly legal to modify them
in the open method before returning.</p>
<dl class="Bl-tag">
<dt><var class="Vt">u_int</var> <var class="Va">d_sectorsize</var></dt>
<dd>The sector size of the disk device in bytes.</dd>
<dt><var class="Vt">off_t</var> <var class="Va">d_mediasize</var></dt>
<dd>The size of the disk device in bytes.</dd>
<dt><var class="Vt">u_int</var> <var class="Va">d_maxsize</var></dt>
<dd>The maximum supported size in bytes of an I/O request. Requests larger
than this size will be chopped up by GEOM.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Optional_Media_Properties"><a class="permalink" href="#Optional_Media_Properties">Optional
Media Properties</a></h2>
<p class="Pp">These optional fields can provide extra information about the disk
device. Do not initialize these fields if the field/concept does not apply.
These fields must stay stable from return of the drivers open method until
the close method is called, but it is perfectly legal to modify them in the
open method before returning.</p>
<dl class="Bl-tag">
<dt><var class="Vt">u_int</var> <var class="Va">d_fwsectors</var>,
<var class="Vt">u_int</var> <var class="Va">d_fwheads</var></dt>
<dd>The number of sectors and heads advertised on the disk device by the
firmware or BIOS. These values are almost universally bogus, but on some
architectures necessary for the correct calculation of disk
partitioning.</dd>
<dt><var class="Vt">u_int</var> <var class="Va">d_stripeoffset</var>,
<var class="Vt">u_int</var> <var class="Va">d_stripesize</var></dt>
<dd>These two fields can be used to describe the width and location of natural
performance boundaries for most disk technologies. Please see
<span class="Pa">src/sys/geom/notes</span> for details.</dd>
<dt><var class="Vt">char</var>
<var class="Va">d_ident[DISK_IDENT_SIZE]</var></dt>
<dd>This field can and should be used to store disk's serial number if the
d_getattr method described above isn't implemented, or if it does not
support the GEOM::ident attribute.</dd>
<dt><var class="Vt">char</var>
<var class="Va">d_descr[DISK_IDENT_SIZE]</var></dt>
<dd>This field can be used to store the disk vendor and product
description.</dd>
<dt><var class="Vt">uint16_t</var> <var class="Va">d_hba_vendor</var></dt>
<dd>This field can be used to store the PCI vendor ID for the HBA connected to
the disk.</dd>
<dt><var class="Vt">uint16_t</var> <var class="Va">d_hba_device</var></dt>
<dd>This field can be used to store the PCI device ID for the HBA connected to
the disk.</dd>
<dt><var class="Vt">uint16_t</var> <var class="Va">d_hba_subvendor</var></dt>
<dd>This field can be used to store the PCI subvendor ID for the HBA connected
to the disk.</dd>
<dt><var class="Vt">uint16_t</var> <var class="Va">d_hba_subdevice</var></dt>
<dd>This field can be used to store the PCI subdevice ID for the HBA connected
to the disk.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Driver_Private_Data"><a class="permalink" href="#Driver_Private_Data">Driver
Private Data</a></h2>
<p class="Pp">This field may be used by the device driver to store a pointer to
private data to implement the disk service.</p>
<dl class="Bl-tag">
<dt><var class="Vt">void *</var> <var class="Va">d_drv1</var></dt>
<dd>Private data pointer. Typically used to store a pointer to the drivers
<var class="Vt">softc</var> structure for this disk device.</dd>
</dl>
</section>
</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">devfs(4)</a>, <a class="Xr">GEOM(4)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">kernel disk storage API</code> first appeared
in <span class="Ux">FreeBSD 4.9</span>.</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">Robert
Watson</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">Disk aliases are not a general purpose aliasing mechanism, but are
intended only to ease the transition from one name to another. They can be
used to ensure that nvd0 and nda0 are the same thing. They cannot be used to
implement the diskX concept from macOS.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">April 30, 2020</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
