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