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