Print this page
document DKIOCFREE
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/dkio.7i
+++ new/usr/src/man/man7i/dkio.7i
1 1 .\"
2 2 .\" The contents of this file are subject to the terms of the
3 3 .\" Common Development and Distribution License (the "License").
4 4 .\" You may not use this file except in compliance with the License.
5 5 .\"
6 6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
7 7 .\" or http://www.opensolaris.org/os/licensing.
8 8 .\" See the License for the specific language governing permissions
9 9 .\" and limitations under the License.
|
↓ open down ↓ |
9 lines elided |
↑ open up ↑ |
10 10 .\"
11 11 .\" When distributing Covered Code, include this CDDL HEADER in each
12 12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
13 13 .\" If applicable, add the following below this CDDL HEADER, with the
14 14 .\" fields enclosed by brackets "[]" replaced with your own identifying
15 15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
16 16 .\"
17 17 .\"
18 18 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
19 19 .\" Copyright 2016 Nexenta Systems, Inc.
20 -.\" Copyright (c) 2017, Joyent, Inc.
20 +.\" Copyright 2020 Joyent, Inc.
21 21 .\"
22 -.Dd October 23, 2017
22 +.Dd February 14, 2020
23 23 .Dt DKIO 7I
24 24 .Os
25 25 .Sh NAME
26 26 .Nm dkio
27 27 .Nd disk control operations
28 28 .Sh SYNOPSIS
29 29 .In sys/dkio.h
30 30 .In sys/vtoc.h
31 31 .Sh DESCRIPTION
32 32 Disk drivers support a set of
33 33 .Xr ioctl 2
34 34 requests for disk controller, geometry, and partition information.
35 35 Basic to these
36 36 .Xr ioctl 2
37 37 requests are the definitions in
38 38 .In sys/dkio.h .
39 39 .Sh IOCTLS
40 40 The following
41 41 .Xr ioctl 2
42 42 requests set and/or retrieve the current disk
43 43 controller, partitions, or geometry information on all architectures:
44 44 .Bl -tag -width 1n
45 45 .It Dv DKIOCINFO
46 46 .Pp
47 47 The argument is a pointer to a
48 48 .Vt dk_cinfo
49 49 structure (described below).
50 50 This structure tells the controller-type and attributes regarding bad-block
51 51 processing done on the controller.
52 52 .Bd -literal -offset 2n
53 53 /*
54 54 * Structures and definitions for disk I/O control commands
55 55 */
56 56 #define DK_DEVLEN 16 /* device name max length, */
57 57 /* including unit # and NULL */
58 58
59 59 /* Used for controller info */
60 60 struct dk_cinfo {
61 61 char dki_cname[DK_DEVLEN]; /* controller name */
62 62 /* (no unit #) */
63 63 ushort_t dki_ctype; /* controller type */
64 64 ushort_t dki_flags; /* flags */
65 65 ushort_t dki_cnum; /* controller number */
66 66 uint_t dki_addr; /* controller address */
67 67 uint_t dki_space; /* controller bus type */
68 68 uint_t dki_prio; /* interrupt priority */
69 69 uint_t dki_vec; /* interrupt vector */
70 70 char dki_dname[DK_DEVLEN]; /* drive name (no unit #) */
71 71 uint_t dki_unit; /* unit number */
72 72 uint_t dki_slave; /* slave number */
73 73 ushort_t dki_partition; /* partition number */
74 74 ushort_t dki_maxtransfer; /* maximum transfer size */
75 75 /* in DEV_BSIZE */
76 76 };
77 77
78 78 /*
79 79 * Controller types
80 80 */
81 81 #define DKC_UNKNOWN 0
82 82 #define DKC_CDROM 1 /* CD-ROM, SCSI or other */
83 83 #define DKC_WDC2880 2
84 84 #define DKC_XXX_0 3 /* unassigned */
85 85 #define DKC_XXX_1 4 /* unassigned */
86 86 #define DKC_DSD5215 5
87 87 #define DKC_ACB4000 7
88 88 #define DKC_XXX_2 9 /* unassigned */
89 89 #define DKC_NCRFLOPPY 10
90 90 #define DKC_SMSFLOPPY 12
91 91 #define DKC_SCSI_CCS 13 /* SCSI CCS compatible */
92 92 #define DKC_INTEL82072 14 /* native floppy chip */
93 93 #define DKC_INTEL82077 19 /* 82077 floppy disk */
94 94 /* controller */
95 95 #define DKC_DIRECT 20 /* Intel direct attached */
96 96 /* device (IDE) */
97 97 #define DKC_PCMCIA_MEM 21 /* PCMCIA memory disk-like */
98 98 /* type */
99 99 #define DKC_PCMCIA_ATA 22 /* PCMCIA AT Attached type */
100 100
101 101 /*
102 102 * Sun reserves up through 1023
103 103 */
104 104
105 105 #define DKC_CUSTOMER_BASE 1024
106 106
107 107 /*
108 108 * Flags
109 109 */
110 110 #define DKI_BAD144 0x01 /* use DEC std 144 */
111 111 /* bad sector fwding */
112 112 #define DKI_MAPTRK 0x02 /* controller does */
113 113 /* track mapping */
114 114 #define DKI_FMTTRK 0x04 /* formats only full
115 115 /* track at a time */
116 116 #define DKI_FMTVOL 0x08 /* formats only full */
117 117 /* volume at a time */
118 118 #define DKI_FMTCYL 0x10 /* formats only full */
119 119 /* cylinders at a time */
120 120 #define DKI_HEXUNIT 0x20 /* unit number printed */
121 121 /* as 3 hexdigits */
122 122 #define DKI_PCMCIA_PFD 0x40 /* PCMCIA pseudo-floppy */
123 123 /* memory card */
124 124 .Ed
125 125 .It Dv DKIOCGAPART
126 126 .Pp
127 127 The argument is a pointer to a
128 128 .Vt dk_allmap
129 129 structure (described below).
130 130 This
131 131 .Xr ioctl 2
132 132 gets the controller's notion of the current partition table
133 133 for disk drive.
134 134 .It Dv DKIOCSAPART
135 135 .Pp
136 136 The argument is a pointer to a
137 137 .Vt dk_allmap
138 138 structure (described below).
139 139 This
140 140 .Xr ioctl 2
141 141 sets the controller's notion of the partition table without
142 142 changing the disk itself.
143 143 .Bd -literal -offset 2n
144 144 /*
145 145 * Partition map (part of dk_label)
146 146 */
147 147 struct dk_map {
148 148 daddr_t dkl_cylno; /* starting cylinder */
149 149 daddr_t dkl_nblk; /* number of blocks */
150 150 };
151 151
152 152 /*
153 153 * Used for all partitions
154 154 */
155 155 struct dk_allmap {
156 156 struct dk_map dka_map[NDKMAP];
157 157 };
158 158 .Ed
159 159 .It Dv DKIOCGGEOM
160 160 .Pp
161 161 The argument is a pointer to a
162 162 .Vt dk_geom
163 163 structure (described below).
164 164 This
165 165 .Xr ioctl 2
166 166 gets the controller's notion of the current geometry of the disk drive.
167 167 .It Dv DKIOCSGEOM
168 168 .Pp
169 169 The argument is a pointer to a
170 170 .Vt dk_geom
171 171 structure (described below).
172 172 This
173 173 .Xr ioctl 2
174 174 sets the controller's notion of the geometry without changing the disk itself.
175 175 .It Dv DKIOCGVTOC
176 176 .Pp
177 177 The argument is a pointer to a
178 178 .Vt vtoc
179 179 structure (described below).
180 180 This
181 181 .Xr ioctl 2
182 182 returns the device's current volume table of contents (VTOC).
183 183 For disks larger than 1TB,
184 184 .Dv DKIOCGEXTVTOC
185 185 must be used instead.
186 186 .It Dv DKIOCSVTOC
187 187 .Pp
188 188 The argument is a pointer to a
189 189 .Vt vtoc
190 190 structure (described below).
191 191 This
192 192 .Xr ioctl 2
193 193 changes the VTOC associated with the device.
194 194 For disks larger than 1TB,
195 195 .Dv DKIOCSEXTVTOC
196 196 must be used instead.
197 197 .Bd -literal -offset 2n
198 198 struct partition {
199 199 ushort_t p_tag; /* ID tag of partition */
200 200 ushort_t p_flag; /* permission flags */
201 201 daddr_t p_start; /* start sector of partition */
202 202 long p_size; /* # of blocks in partition */
203 203 };
204 204 .Ed
205 205 .Pp
206 206 If
207 207 .Dv DKIOCSVTOC
208 208 is used with a floppy diskette, the
209 209 .Fa p_start
210 210 field must be the first sector of a cylinder.
211 211 To compute the number of sectors per
212 212 cylinder, multiply the number of heads by the number of sectors per track.
213 213 .Bd -literal -offset 2n
214 214 struct vtoc {
215 215 unsigned long v_bootinfo[3]; /* info needed by mboot */
216 216 /* (unsupported) */
217 217 unsigned long v_sanity; /* to verify vtoc */
218 218 /* sanity */
219 219 unsigned long v_version; /* layout version */
220 220 char v_volume[LEN_DKL_VVOL]; /* volume name */
221 221 ushort_t v_sectorsz; /* sector size in bytes */
222 222 ushort_t v_nparts; /* number of partitions */
223 223 unsigned long v_reserved[10]; /* free space */
224 224 struct partition v_part[V_NUMPAR]; /* partition headers */
225 225 time_t timestamp[V_NUMPAR]; /* partition timestamp */
226 226 /* (unsupported) */
227 227 char v_asciilabel[LEN_DKL_ASCII]; /* compatibility */
228 228 };
229 229
230 230 /*
231 231 * Partition permission flags
232 232 */
233 233 #define V_UNMNT 0x01 /* Unmountable partition */
234 234 #define V_RONLY 0x10 /* Read only */
235 235
236 236 /*
237 237 * Partition identification tags
238 238 */
239 239 #define V_UNASSIGNED 0x00 /* unassigned partition */
240 240 #define V_BOOT 0x01 /* Boot partition */
241 241 #define V_ROOT 0x02 /* Root filesystem */
242 242 #define V_SWAP 0x03 /* Swap filesystem */
243 243 #define V_USR 0x04 /* Usr filesystem */
244 244 #define V_BACKUP 0x05 /* full disk */
245 245 #define V_VAR 0x07 /* Var partition */
246 246 #define V_HOME 0x08 /* Home partition */
247 247 #define V_ALTSCTR 0x09 /* Alternate sector partition */
248 248 .Ed
249 249 .It Dv DKIOCGEXTVTOC
250 250 .Pp
251 251 The argument is a pointer to an
252 252 .Vt extvtoc
253 253 structure (described below).
254 254 This ioctl returns the device's current volume table of contents (VTOC).
255 255 VTOC is extended to support a disk up to 2TB in size.
256 256 For disks larger than 1TB this ioctl must be used instead of
257 257 .Dv DKIOCGVTOC .
258 258 .It Dv DKIOCSEXTVTOC
259 259 .Pp
260 260 The argument is a pointer to an
261 261 .Vt extvtoc
262 262 structure (described below).
263 263 This ioctl changes the VTOC associated with the device.
264 264 VTOC is extended to support a disk up to 2TB in size.
265 265 For disks larger than 1TB this ioctl must be used instead of
266 266 .Vt DKIOCSVTOC .
267 267 .Bd -literal -offset 2n
268 268 struct extpartition {
269 269 ushort_t p_tag; /* ID tag of partition */
270 270 ushort_t p_flag; /* permission flags */
271 271 ushort_t p_pad[2]; /* reserved */
272 272 diskaddr_t p_start; /* start sector no of partition */
273 273 diskaddr_t p_size; /* # of blocks in partition */
274 274 };
275 275
276 276 struct extvtoc {
277 277 uint64_t v_bootinfo[3]; /* info needed by mboot (unsupported) */
278 278 uint64_t v_sanity; /* to verify vtoc sanity */
279 279 uint64_t v_version; /* layout version */
280 280 char v_volume[LEN_DKL_VVOL]; /* volume name */
281 281 ushort_t v_sectorsz; /* sector size in bytes */
282 282 ushort_t v_nparts; /* number of partitions */
283 283 ushort_t pad[2];
284 284 uint64_t v_reserved[10];
285 285 struct extpartition v_part[V_NUMPAR]; /* partition headers */
286 286 uint64_t timestamp[V_NUMPAR]; /* partition timestamp */
287 287 /* (unsupported) */
288 288 char v_asciilabel[LEN_DKL_ASCII]; /* for compatibility */
289 289 };
290 290 .Ed
291 291 .Pp
292 292 Partition permissions flags and identification tags
293 293 are defined the same as vtoc structure.
294 294 .It Dv DKIOCEJECT
295 295 .Pp
296 296 If the drive supports removable media, this
297 297 .Xr ioctl 2
298 298 requests the disk drive to eject its disk.
299 299 .It Dv DKIOCREMOVABLE
300 300 .Pp
301 301 The argument to this
302 302 .Xr ioctl 2
303 303 is an integer.
304 304 After successful completion, this
305 305 .Xr ioctl 2
306 306 sets that integer to a non-zero value if the drive in
307 307 question has removable media.
308 308 If the media is not removable, the integer is set to
309 309 .Sy 0 .
310 310 .It Dv DKIOCHOTPLUGGABLE
311 311 .Pp
312 312 The argument to this
313 313 .Xr ioctl 2
314 314 is an integer.
315 315 After successful completion, this
316 316 .Xr ioctl 2
317 317 sets that integer to a non-zero value if the drive in question is hotpluggable.
318 318 If the media is not hotpluggable, the integer is set to 0.
319 319 .It Dv DKIOCSTATE
320 320 .Pp
321 321 This
322 322 .Xr ioctl 2
323 323 blocks until the state of the drive, inserted or ejected, is changed.
324 324 The argument is a pointer to a
325 325 .Vt dkio_state ,
326 326 enum, whose possible enumerations are listed below.
327 327 The initial value should be either the last
328 328 reported state of the drive, or
329 329 .Dv DKIO_NONE .
330 330 Upon return, the enum pointed
331 331 to by the argument is updated with the current state of the drive.
332 332 .Bd -literal -offset 2n
333 333 enum dkio_state {
334 334 DKIO_NONE, /* Return disk's current state */
335 335 DKIO_EJECTED, /* Disk state is 'ejected' */
336 336 DKIO_INSERTED /* Disk state is 'inserted' */
337 337 };
338 338 .Ed
339 339 .It Dv DKIOCLOCK
340 340 .Pp
341 341 For devices with removable media, this
342 342 .Xr ioctl 2
343 343 requests the disk drive to lock the door.
344 344 .It Dv DKIOCUNLOCK
345 345 .Pp
346 346 For devices with removable media, this
347 347 .Xr ioctl 2
348 348 requests the disk drive to unlock the door.
349 349 .It Dv DKIOCGMEDIAINFO
350 350 .Pp
351 351 The argument to this
352 352 .Xr ioctl 2
353 353 is a pointer to a
354 354 .Vt dk_minfo
355 355 structure.
356 356 The structure indicates the type of media or the command set profile used by
357 357 the drive to operate on the media.
358 358 The
359 359 .Vt dk_minfo
360 360 structure also indicates the logical media block size the drive uses as the
361 361 basic unit block size of operation and the raw formatted capacity of the media
362 362 in number of logical blocks.
363 363 .It Dv DKIOCGMEDIAINFOEXT
364 364 .Pp
365 365 The argument to this
366 366 .Xr ioctl 2
367 367 is a pointer to a
368 368 .Vt dk_minfo_ext
369 369 structure.
370 370 The structure indicates the type of media or the command set profile
371 371 used by the drive to operate on the media.
372 372 The
373 373 .Vt dk_minfo_ext
374 374 structure
375 375 also indicates the logical media block size the drive uses as the basic unit
376 376 block size of operation, the raw formatted capacity of the media in number of
377 377 logical blocks and the physical block size of the media.
378 378 .Bd -literal -offset 2n
379 379 /*
380 380 * Used for media info or profile info
381 381 */
382 382 struct dk_minfo {
383 383 uint_t dki_media_type; /* Media type or profile info */
384 384 uint_t dki_lbsize; /* Logical blocksize of media */
385 385 diskaddr_t dki_capacity; /* Capacity as # of dki_lbsize blks */
386 386 };
387 387
388 388 /*
389 389 * Used for media info or profile info and physical blocksize
390 390 */
391 391 struct dk_minfo_ext {
392 392 uint_t dki_media_type; /* Media type or profile info */
393 393 uint_t dki_lbsize; /* Logical blocksize of media */
394 394 diskaddr_t dki_capacity; /* Capacity as # of dki_lbsize blks */
395 395 uint_t dki_pbsize; /* Physical blocksize of media */
396 396 };
397 397
398 398
399 399 /*
400 400 * Media types or profiles known
401 401 */
402 402 #define DK_UNKNOWN 0x00 /* Media inserted - type unknown */
403 403
404 404 /*
405 405 * SFF 8090 Specification Version 3, media types 0x01 - 0xfffe are
406 406 * retained to maintain compatibility with SFF8090. The following
407 407 * define the optical media type.
408 408 */
409 409 #define DK_MO_ERASABLE 0x03 /* MO Erasable */
410 410 #define DK_MO_WRITEONCE 0x04 /* MO Write once */
411 411 #define DK_AS_MO 0x05 /* AS MO */
412 412 #define DK_CDROM 0x08 /* CDROM */
413 413 #define DK_CDR 0x09 /* CD-R */
414 414 #define DK_CDRW 0x0A /* CD-RW */
415 415 #define DK_DVDROM 0x10 /* DVD-ROM */
416 416 #define DK_DVDR 0x11 /* DVD-R */
417 417 #define DK_DVDRAM 0x12 /* DVD_RAM or DVD-RW */
418 418
419 419 /*
420 420 * Media types for other rewritable magnetic media
421 421 */
422 422 #define DK_FIXED_DISK 0x10001 /* Fixed disk SCSI or otherwise */
423 423 #define DK_FLOPPY 0x10002 /* Floppy media */
424 424 #define DK_ZIP 0x10003 /* IOMEGA ZIP media */
425 425 #define DK_JAZ 0x10004 /* IOMEGA JAZ media */
426 426 .Ed
427 427 .Pp
428 428 If the media exists and the host can obtain a current profile list, the command
429 429 succeeds and returns the
430 430 .Vt dk_minfo
431 431 structure with data representing that media.
432 432 .Pp
433 433 If there is no media in the drive, the command fails and the host returns an
434 434 .Er ENXIO
435 435 error, indicating that it cannot gather the information requested.
436 436 .Pp
437 437 If the profile list is not available, the host attempts to identify the
438 438 media-type based on the available information.
439 439 .Pp
440 440 If identification is not possible, the host returns media type
441 441 .Dv DK_UNKNOWN .
442 442 See
443 443 .Sx NOTES
444 444 for blocksize usage and capacity information.
445 445 .It Dv DKIOCSMBOOT
446 446 .Pp
447 447 The argument is a pointer to struct
448 448 .Vt mboot .
449 449 .Pp
450 450 Copies the
451 451 .Vt mboot
452 452 information supplied in the argument to the absolute sector 0 of the device.
453 453 Prior to copying the information, this
454 454 .Xr ioctl 2
455 455 performs the following checks on the
456 456 .Vt mboot
457 457 data:
458 458 .Bl -bullet -offset indent
459 459 .It
460 460 Ensures that the signature field is set to 0xAA55.
461 461 .It
462 462 Ensures that partitions do not overlap.
463 463 .It
464 464 On SPARC platforms, determines if the device is a removable media.
465 465 .El
466 466 .Pp
467 467 If the above verification fails,
468 468 .Va errno
469 469 is set to
470 470 .Er EINVAL
471 471 and the
472 472 .Xr ioctl 2
473 473 command fails.
474 474 .Pp
475 475 x86 Platforms \(em Upon successful write of
476 476 .Vt mboot ,
477 477 the partition map structure maintained in the driver is updated.
478 478 If the new Solaris partition is
479 479 different from the previous one, the internal VTOC table maintained in the
480 480 driver is set as follows:
481 481 .Pp
482 482 If
483 483 .Dv _SUNOS_VTOC_8
484 484 is defined:
485 485 .Bd -unfilled -offset 4n
486 486 Partition: 0 Start: 0 Capacity = Capacity of device.
487 487 Partition: 2 Start: 0 Capacity = Capacity of device.
488 488 .Ed
489 489 .Pp
490 490 If
491 491 .Dv _SUNOS_VTOC_16
492 492 is defined:
493 493 .Bd -unfilled -offset 4n
494 494 Partition: 2 Start: 0 Size = Size specified in mboot - 2 cylinders.
495 495 Partition: 8 Start: 0 Size = Sectors/cylinder.
496 496 Partition: 9 Start: Sectors/cylinder Size = 2 * sectors/cylinder
497 497 .Ed
498 498 .Pp
499 499 To determine if the Solaris partition has changed:
500 500 .Bd -offset 4n -ragged
501 501 If either offset or the size of the Solaris partition is different from the
502 502 previous one then it shall be deemed to have changed.
503 503 In all other cases, the
504 504 internal VTOC info remains as before.
505 505 .Ed
506 506 .Pp
507 507 SPARC Platforms \(em The VTOC label and
508 508 .Vt mboot
509 509 both occupy the same location, namely sector 0.
510 510 As a result, following the successful write of
511 511 .Vt mboot
512 512 info, the internal VTOC table maintained in the driver is set as follows:
513 513 .Bd -unfilled -offset 4n
514 514 Partition: 0 Start: 0 Size = Capacity of device.
515 515 Partition: 2 Start: 0 Size = Capacity of device.
516 516 .Ed
517 517 .Pp
518 518 See the
519 519 .Sx NOTES
520 520 section for usage of
521 521 .Dv DKIOCSMBOOT
522 522 when modifying Solaris partitions.
523 523 .It Dv DKIOCGETVOLCAP
524 524 .Pp
525 525 This ioctl provides information and status of available capabilities.
526 526 .Fa vc_info
527 527 is a bitmap and the valid flag values are:
528 528 .Pp
529 529 .Bl -tag -width DKV_ABR_CAP -compact -offset 2n
530 530 .It Dv DKV_ABR_CAP
531 531 Capable of application-based recovery
532 532 .It Dv DKV_DMR_CAP
533 533 Ability to read specific copy of data when multiple copies exist.
534 534 For example, in a two way mirror, this ioctl is used to read each
535 535 side of the mirror.
536 536 .El
537 537 .Pp
538 538 .Fa vc_set
539 539 is a bitmap and the valid flag values are:
540 540 .Pp
541 541 .Bl -tag -width DKV_ABR_CAP -compact -offset 2n
542 542 .It Dv DKV_ABR_CAP
543 543 This flag is set if ABR has been set on a device that supports ABR functionality.
544 544 .It Dv DKV_DMR_CAP
545 545 Directed read has been enabled.
546 546 .El
547 547 .Pp
548 548 These capabilities are not required to be persistent across a system reboot and
549 549 their persistence depends upon the implementation.
550 550 For example, if the ABR
551 551 capability for a DRL mirror simply clears the dirty-region list and
552 552 subsequently stops updating this list, there is no reason for persistence
553 553 because the VM recovery is a no-op.
554 554 Conversely, if the ABR capability is
555 555 applied to a non-DRL mirror to indicate that the VM should not perform a full
556 556 recovery of the mirror following a system crash, the capability must be
557 557 persistent so that the VM know whether or not to perform recovery.
558 558 .Pp
559 559 Return Errors:
560 560 .Pp
561 561 .Bl -tag -width ENOTSUP -compact -offset 2n
562 562 .It Er EINVAL
563 563 Invalid device for this operation.
564 564 .It Er ENOTSUP
565 565 Functionality that is attempted to be set is not supported.
566 566 .El
567 567 .It Dv DKIOCSETVOLCAP
568 568 .Pp
569 569 This ioctl sets the available capabilities for the device.
570 570 If a capability flag
571 571 is not set in
572 572 .Fa vc_set ,
573 573 that capability is cleared.
574 574 .Pp
575 575 .Fa vc_info
576 576 flags are ignored.
577 577 .Pp
578 578 .Fa vc_set
579 579 valid flags are:
580 580 .Pp
581 581 .Bl -tag -width DKV_ABR_CAP -compact -offset 2n
582 582 .It Dv DKV_ABR_CAP
583 583 Flag to set application-based recovery.
584 584 A device can successfully support ABR only if it is capable.
585 585 .It Dv DKV_DMR_CAP
586 586 Flag to set directed read.
587 587 .El
588 588 .It Dv DKIODMR
589 589 .Pp
590 590 .Ft int
591 591 .Fo ioctl
592 592 .Fa int ,
593 593 .\" This could be .Fa as well -- but mandoc doesn't seem to allow both
594 594 .Dv DKIODMR ,
595 595 .Fa "vol_directed_rd *"
596 596 .Fc
597 597 .Pp
598 598 This ioctl allows highly available applications to perform round-robin reads
599 599 from the underlying devices of a replicated device.
600 600 .Pp
601 601 .Bl -tag -width vdr_bytesread -offset 2n -compact
602 602 .It Fa vdr_offset
603 603 Offset at which the read should occur.
604 604 .It Fa vdr_nbytes
605 605 Number of bytes to be read
606 606 .It Fa vdr_bytesread
607 607 Number of bytes successfully read by the kernel.
608 608 .It Fa vdr_data
609 609 Pointer to a user allocated buffer to return the data read
610 610 .It Fa vdr_side
611 611 Side to be read.
612 612 Initialized to
613 613 .Dv DKV_SIDE_INIT
614 614 .It Fa vdr_side_name
615 615 The volume name that has been read.
616 616 .El
617 617 .Pp
618 618 Valid
619 619 .Fa vdr_flags
620 620 are:
621 621 .Pp
622 622 .Bl -tag -width DKV_DMR_NEXT_SIDE -offset 2n -compact
623 623 .It Dv DKV_DMR_NEXT_SIDE
624 624 Set by user
625 625 .It Dv DKV_DMR_DONE
626 626 Return value
627 627 .It Dv DKV_DMR_ERROR
628 628 Return value
629 629 .It Dv DKV_DMR_SUCCESS
630 630 Return value
631 631 .It Dv DKV_DMR_SHORT
632 632 Return value
633 633 .El
634 634 .Pp
635 635 The calling sequence is as follows: The caller sets the
636 636 .Fa vdr_flags
637 637 to
638 638 .Dv DK_DMR_NEXT_SIDE
639 639 and
640 640 .Fa vdr_side
641 641 to
642 642 .Dv DKV_SIDE_INIT
643 643 at the start.
644 644 Subsequent calls should be made without any changes to these values.
645 645 If they are changed the results of the ioctl are indeterminate.
646 646 .Pp
647 647 When
648 648 .Dv DKV_SIDE_INIT
649 649 is set, the call results in the kernel reading from the first side.
650 650 The kernel updates
651 651 .Fa vdr_side
652 652 to indicate the side that was read, and
653 653 .Fa vdr_side_name
654 654 to contain the name of that side.
655 655 .Fa vdr_data
656 656 contains the data that was read.
657 657 Therefore to perform a round-robin read all of
658 658 the valid sides, there is no need for the caller to change the contents of
659 659 .Fa vdr_side .
660 660 .Pp
661 661 Subsequent
662 662 .Xr ioctl 2
663 663 calls result in reads from the next valid side until all valid
664 664 sides have been read.
665 665 On success, the kernel sets
666 666 .Dv DKV_DMR_SUCCESS .
667 667 The following table shows the values of
668 668 .Fa vdr_flags
669 669 that are returned when an error occurs:
670 670 .Bl -column DKV_DMR_SHORT DKV_SIDE_INIT "Bytes requested cannot" -offset 2n
671 671 .It Fa vda_flags Ta Fa vdr_side Ta Notes
672 672 .It Dv DKV_DMR_ERROR Ta Dv DKV_SIDE_INIT Ta \&No valid side to read
673 673 .It Dv DKV_DMR_DONE Ta Not Init side Ta All valid sides read
674 674 .It Dv DKV_DMR_SHORT Ta Any value Ta Bytes requested cannot be read Fa vdr_bytesread No set to bytes actually read
675 675 .El
676 676 Typical code fragment:
677 677 .Bd -literal -offset 2n
678 678 enable->vc_set |= DKV_ABR_SET;
679 679 retval = ioctl(filedes, DKIOSETVOLCAP, enable);
680 680 if (retval != EINVAL || retval != ENOTSUP) {
681 681 if (info->vc_set & DKV_DMR_SET) {
682 682 dr->vdr_flags |= DKV_DMR_NEXT_SIDE;
683 683 dr->vdr_side = DKV_SIDE_INIT;
684 684 dr->vdr_nbytes = 1024;
685 685 dr->vdr_offset = 0xff00;
|
↓ open down ↓ |
653 lines elided |
↑ open up ↑ |
686 686 do {
687 687 rval = ioctl(fildes, DKIODMR, dr);
688 688 if (rval != EINVAL) {
689 689 /* Process data */
690 690 }
691 691 } while (rval != EINVAL || dr->vdr_flags &
692 692 (DKV_DMR_DONE | DKV_DMR_ERROR | DKV_DMR_SHORT)
693 693 }
694 694 }
695 695 .Ed
696 +.It Dv DKIOCFREE
697 +.Pp
698 +The argument is a pointer to a
699 +.Vt dkioc_free_list_t
700 +structure (described below).
701 +The structure consists of a header followed by one or more
702 +.Vt dkioc_free_list_ext_t
703 +strctures (described below) that list the extents that the device should free.
704 +.Bd -literal -offset 2n
705 +typedef struct dkioc_free_list_ext_s {
706 + uint64_t dfle_start;
707 + uint64_t dfle_length;
708 +} dkioc_free_list_ext_t;
709 +
710 +typedef struct dkioc_free_list_s {
711 + uint64_t dfl_flags;
712 + uint64_t dfl_num_exts;
713 + uint64_t dfl_offset;
714 + dkioc_free_list_ext_t dfl_exts[1];
715 +} dkioc_free_list_t;
716 +.Ed
717 +.Pp
718 +The
719 +.Fa dfle_start ,
720 +.Fa dfle_length ,
721 +and
722 +.Fa dfl_offset
723 +fields are in units of bytes (not blocks).
724 +.Pp
725 +The values for
726 +.Fa dfl_flags
727 +are:
728 +.Bl -tag -width Dv
729 +.It Dv DF_WAIT_SYNC
730 +Wait for the device to complete freeing the space before returning.
696 731 .El
732 +.Pp
733 +The
734 +.Fa dfl_num_exts
735 +field indicates the number of
736 +.Vt dkioc_free_list_ext_t
737 +structures follow the
738 +.Vt dkioc_free_list_t
739 +structure (including the first entry in
740 +.Fa dfl_exts ) .
741 +There must be at least one
742 +.Vt dkioc_free_list_ext_t
743 +in the
744 +.Xr ioctl 2
745 +request (i.e\&.
746 +.Fa dfl_num_exts
747 +must be \(>= 1).
748 +.Pp
749 +The
750 +.Fa dfl_offset
751 +field is added to all of the values of
752 +.Fa dfle_start
753 +when processed by the device.
754 +.Pp
755 +The
756 +.Fa dfl_exts
757 +field contains the first extent to free, immediately followed by any
758 +additional
759 +.Vt dkioc_free_list_ext_t
760 +structures if there are more than one extent to free.
761 +.Pp
762 +The
763 +.Dv DFL_SZ(num_exts)
764 +macro can be used to calculate the amount of memory required to hold
765 +.Fa num_exts
766 +extents.
767 +.It Dv DKIOC_CANFREE
768 +The argument is a pointer to an
769 +.Vt int
770 +that is populated by the
771 +.Xr ioctl 2
772 +request.
773 +Upon a successful return, if a non-zero value has been set in the
774 +.Vt int
775 +parameter, it indicates that the device supports the
776 +.Dv DKIOCFREE
777 +.Xr ioctl 2 .
778 +If the
779 +.Vt int
780 +parameter has been set to zero, the
781 +.Dv DKIOCFREE
782 +.Xr ioctl 2
783 +is not supported by the device.
784 +.El
697 785 .Ss "RETURN VALUES"
698 786 Upon successful completion, the value returned is
699 787 .Sy 0 .
700 788 Otherwise,
701 789 .Sy -1
702 790 is returned and
703 791 .Va errno
704 792 is set to indicate the error.
705 793 .Ss "x86 Only"
706 794 The following
707 795 .Xr ioctl 2
708 796 requests set and/or retrieve the current disk
709 797 controller, partitions, or geometry information on the x86 architecture.
710 798 .Bl -tag -width 1n
711 799 .It Dv DKIOCG_PHYGEOM
712 800 .Pp
713 801 The argument is a pointer to a
714 802 .Vt dk_geom
715 803 structure (described below).
716 804 This
717 805 .Xr ioctl 2
718 806 gets the driver's notion of the physical geometry of the disk drive.
719 807 It is functionally identical to the
720 808 .Dv DKIOCGGEOM
721 809 .Xr ioctl 2 .
722 810 .It Dv DKIOCG_VIRTGEOM
723 811 .Pp
724 812 The argument is a pointer to a
725 813 .Vt dk_geom
726 814 structure (described below).
727 815 This
728 816 .Xr ioctl 2
729 817 gets the controller's (and hence the driver's) notion of the
730 818 virtual geometry of the disk drive.
731 819 Virtual geometry is a view of the disk
732 820 geometry maintained by the firmware in a host bus adapter or disk controller.
733 821 If the disk is larger than 8 Gbytes, this ioctl fails because a CHS-based
734 822 geometry is not relevant or useful for this drive.
735 823 .Bd -literal -offset 2n
736 824 /*
737 825 * Definition of a disk's geometry
738 826 */
739 827 struct dk_geom {
740 828 unsigned shor dkg_ncyl; /* # of data cylinders */
741 829 unsigned shor dkg_acyl; /* # of alternate cylinders */
742 830 unsigned short dkg_bcyl; /* cyl offset (for fixed head */
743 831 /* area) */
744 832 unsigned short dkg_nhead; /* # of heads */
745 833 unsigned short dkg_obs1; /* obsolete */
746 834 unsigned short dkg_nsect; /* # of sectors per track */
747 835 unsigned short dkg_intrlv; /* interleave factor */
748 836 unsigned short dkg_obs2; /* obsolete */
749 837 unsigned short dkg_obs3; /* obsolete */
750 838 unsigned short dkg_apc; /* alternates per cylinder */
751 839 /* (SCSI only) */
752 840 unsigned short dkg_rpm; /* revolutions per min */
753 841 unsigned short dkg_pcyl; /* # of physical cylinders */
754 842 unsigned short dkg_write_reinstruct; /* # sectors to skip, */
755 843 /* writes */
756 844 unsigned short dkg_read_reinstruct; /* # sectors to skip ,*/
757 845 /* reads */
758 846 unsigned short dkg_extra[7]; /* for compatible expansion */
759 847 };
760 848 .Ed
761 849 .It Dv DKIOCADDBAD
762 850 .Pp
763 851 This
764 852 .Xr ioctl 2
765 853 forces the driver to re-examine the alternates slice and
766 854 rebuild the internal bad block map accordingly.
767 855 It should be used whenever the
768 856 alternates slice is changed by any method other than the
769 857 .Xr addbadsec 1M
770 858 or
771 859 .Xr format 1M
772 860 utilities.
773 861 .Dv DKIOCADDBAD
774 862 can only be used for software
775 863 remapping on
776 864 .Sy IDE
777 865 drives;
778 866 .Sy SCSI
779 867 drives use hardware remapping of alternate sectors.
780 868 .It Dv DKIOCPARTINFO
781 869 .Pp
782 870 The argument is a pointer to a
783 871 .Vt part_info
784 872 structure (described below).
785 873 This
786 874 .Xr ioctl 2
787 875 gets the driver's notion of the size and extent of the
788 876 partition or slice indicated by the file descriptor argument.
789 877 .Bd -literal -offset 2n
790 878 /*
791 879 * Used by applications to get partition or slice information
792 880 */
793 881 struct part_info {
794 882 daddr_t p_start;
795 883 int p_length;
796 884 };
797 885 .Ed
798 886 .It Dv DKIOCEXTPARTINFO
799 887 .Pp
800 888 The argument is a pointer to an
801 889 .Vt extpart_info
802 890 structure (described below).
803 891 This ioctl gets the driver's notion of the size and extent of the partition or
804 892 slice indicated by the file descriptor argument.
805 893 On disks larger than 1TB, this ioctl must be used instead of
806 894 .Dv DKIOCPARTINFO .
807 895 .Bd -literal -offset 2n
808 896 /*
809 897 * Used by applications to get partition or slice information
810 898 */
811 899 struct extpart_info {
812 900 diskkaddr_t p_start;
813 901 diskaddr_t p_length;
814 902 };
815 903 .Ed
816 904 .It Dv DKIOCSETEXTPART
817 905 .Pp
818 906 This ioctl is used to update the in-memory copy of the logical drive
819 907 information maintained by the driver.
820 908 The ioctl takes no arguments.
821 909 It causes a re-read of the partition information and recreation of minor nodes
822 910 if required.
823 911 Prior to updating the data structures, the ioctl ensures that the partitions do
824 912 not overlap.
825 913 Device nodes are created only for valid partition entries.
826 914 If there is any change in the partition offset, size or ID from the previous
827 915 read, the partition is deemed to have been changed and hence the device nodes
828 916 are recreated.
829 917 Any modification to any of the logical partitions results in the
830 918 recreation of all logical device nodes.
831 919 .El
832 920 .Sh SEE ALSO
833 921 .Xr addbadsec 1M ,
834 922 .Xr fdisk 1M ,
835 923 .Xr format 1M ,
836 924 .Xr ioctl 2 ,
837 925 .Xr cmdk 7D ,
838 926 .Xr sd 7D ,
839 927 .Xr cdio 7I ,
840 928 .Xr fdio 7I ,
841 929 .Xr hdio 7I
842 930 .Sh NOTES
843 931 Blocksize information provided in
844 932 .Dv DKIOCGMEDIAINFO
845 933 is the size (in bytes) of the device's basic unit of operation and can differ
846 934 from the blocksize that the Solaris operating environment exports to the user.
847 935 Capacity information provided in the
848 936 .Dv DKIOCGMEDIAINFO
849 937 are for reference only and you are advised to use the values returned by
850 938 .Dv DKIOCGGEOM
851 939 or other appropriate
852 940 .Xr ioctl 2
853 941 for accessing data using the standard interfaces.
854 942 .Pp
855 943 For x86 only: If the
856 944 .Dv DKIOCSMBOOT
857 945 command is used to modify the Solaris partitions, the VTOC information should
858 946 also be set appropriately to reflect the changes to partition.
859 947 Failure to do so leads to unexpected results when the
860 948 device is closed and reopened fresh at a later time.
861 949 This is because a default VTOC is assumed by driver when a Solaris partition
862 950 is changed.
863 951 The default VTOC persists until the ioctl
864 952 .Dv DKIOCSVTOC
865 953 is called to modify VTOC or the device is closed and reopened.
866 954 At that point, the old valid VTOC is read from
867 955 the disk if it is still available.
|
↓ open down ↓ |
161 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX