1 .\" Copyright (c) 2020 M. Warner Losh <imp@FreeBSD.org>
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd common disk interfaces
36 Common block device IOCTLs
38 All the block devices in the system should support these disk
40 commands defined here.
41 Much of this information is also available via the
47 calls apply to disk drives, and are defined
51 .Bl -tag -width DIOCGPROVIDERNAME
52 .It Dv DIOCGSECTORSIZE
54 Get the sector or block size of the device in bytes.
55 The sector size is the smallest unit of data which can be transferred
57 This is usually a power of 2 but it might not be (e.g. CDROM audio).
58 Operations to block devices such as
63 may only be performed at file offsets that are integral multiple of
67 Get the size of the entire device in bytes.
68 This should be a multiple of the sector size.
71 Return the firmware's notion of number of sectors per track.
72 This value is mostly used for compatibility with various ill designed
74 Use this value only when absolutely required.
75 Its interpretation and use is largely obsolete.
78 Return the firmware's notion of number of heads per cylinder.
79 This value is mostly used for compatibility with various ill designed
81 Use this value only when absolutely required.
82 Its interpretation and use is largely obsolete.
84 Flush write cache of the device.
87 Mark data on the device as unused.
88 The first element is the offset to start deleting.
89 The second element is the length to delete.
90 Providers may use this information to free storage or instruct storage
91 devices the contents can be discarded.
93 .Pq Li "char[DISK_IDENT_SIZE]"
94 Get the ident for this provider.
95 Ident is a unique and fixed identifier for this provider.
96 Ident's properties are as follow:
99 preserved between reboots,
101 preserved across a provider being detached/attached,
103 provider's name can change - ident can't,
105 ident value should not be based on on-disk metadata; in other
106 words, copying whole data from one disk to another should not
107 yield the same ident for the other disk,
109 there can be more than one provider with the same ident, but
110 only if they point at exactly the same physical storage, this is
111 the case for multipathing for example,
113 GEOM classes that consume a single provider and provide single
118 the identifier should be formed by attaching that provider's class
119 name to the ident of the underlying provider,
121 ident is an NUL-terminated ASCII string (is printable),
123 ident is optional and applications can't relay on its presence.
125 .It Dv DIOCGPROVIDERNAME
126 .Pq Li "char[MAXPATHLEN]"
127 Store the provider name for the device in a buffer.
128 The buffer must be at least MAXPATHLEN bytes long.
129 .It Dv DIOCGSTRIPESIZE
131 Get the size of the device's optimal access block in bytes.
132 This should be a multiple of the sector size.
133 .It Dv DIOCGSTRIPEOFFSET
135 Get the offset of the first device's optimal access block in bytes.
136 This should be a multiple of the sector size.
138 .Pq Li "char[MAXPATHLEN]"
139 Get a string defining the physical path for a given provider.
140 This has similar rules to ident, but is intended to uniquely
141 identify the physical location of the device, not the current
142 occupant of that location.
143 The buffer must be at least MAXPATHLEN bytes long.
145 .Pq Li "struct diocgattr_arg"
146 .Bd -literal -offset indent
147 struct diocgattr_arg {
151 char str[DISK_IDENT_SIZE];
158 Get a geom attribute from the provider.
159 Format of the returned data is specific to the attribute.
161 .Pq Li "struct disk_zone_arg"
162 Send disk zone commands.
163 .It Dv DIOCSKERNELDUMP
164 .Pq Li "struct diocskerneldump_arg"
165 Enable/Disable the device for kernel core dumps.
166 .It Dv DIOCGKERNELDUMP
167 .Pq Li "struct diocskerneldump_arg"
168 Get current kernel netdump configuration details for a given index.
169 .Bd -literal -offset indent
171 * Sentinel values for kda_index.
173 * If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared.
175 * If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified
176 * device are cleared.
178 * If kda_index is KDA_REMOVE, only the specified dump configuration for the
179 * given device is removed from the list of fallback dump configurations.
181 * If kda_index is KDA_APPEND, the dump configuration is added after all
182 * existing dump configurations.
184 * Otherwise, the new configuration is inserted into the fallback dump list at
187 #define KDA_REMOVE UINT8_MAX
188 #define KDA_REMOVE_ALL (UINT8_MAX - 1)
189 #define KDA_REMOVE_DEV (UINT8_MAX - 2)
190 #define KDA_APPEND (UINT8_MAX - 3)
191 struct diocskerneldump_arg {
193 uint8_t kda_compression;
194 uint8_t kda_encryption;
195 uint8_t kda_key[KERNELDUMP_KEY_MAX_SIZE];
196 uint32_t kda_encryptedkeysize;
197 uint8_t *kda_encryptedkey;
198 char kda_iface[IFNAMSIZ];
199 union kd_ip kda_server;
200 union kd_ip kda_client;
201 union kd_ip kda_gateway;
207 The manual page was written by
208 .An M Warner Losh Aq Mt imp@FreeBSD.org
209 from text largely derived from