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 (c) 2017, Joyent, Inc.
  21 .\"
  22 .Dd October 23, 2017
  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 .El
 697 .Ss "RETURN VALUES"
 698 Upon successful completion, the value returned is
 699 .Sy 0 .
 700 Otherwise,
 701 .Sy -1
 702 is returned and
 703 .Va errno
 704 is set to indicate the error.
 705 .Ss "x86 Only"
 706 The following
 707 .Xr ioctl 2
 708 requests set and/or retrieve the current disk
 709 controller, partitions, or geometry information on the x86 architecture.
 710 .Bl -tag -width 1n
 711 .It Dv DKIOCG_PHYGEOM
 712 .Pp
 713 The argument is a pointer to a
 714 .Vt dk_geom
 715 structure (described below).
 716 This
 717 .Xr ioctl 2
 718 gets the driver's notion of the physical geometry of the disk drive.
 719 It is functionally identical to the
 720 .Dv DKIOCGGEOM
 721 .Xr ioctl 2 .
 722 .It Dv DKIOCG_VIRTGEOM
 723 .Pp
 724 The argument is a pointer to a
 725 .Vt dk_geom
 726 structure (described below).
 727 This
 728 .Xr ioctl 2
 729 gets the controller's (and hence the driver's) notion of the
 730 virtual geometry of the disk drive.
 731 Virtual geometry is a view of the disk
 732 geometry maintained by the firmware in a host bus adapter or disk controller.
 733 If the disk is larger than 8 Gbytes, this ioctl fails because a CHS-based
 734 geometry is not relevant or useful for this drive.
 735 .Bd -literal -offset 2n
 736 /*
 737  * Definition of a disk's geometry
 738  */
 739 struct dk_geom {
 740     unsigned shor    dkg_ncyl;   /* # of data cylinders */
 741     unsigned shor    dkg_acyl;   /* # of alternate cylinders */
 742     unsigned short   dkg_bcyl;   /* cyl offset (for fixed head */
 743                                  /* area) */
 744     unsigned short   dkg_nhead;  /* # of heads */
 745     unsigned short   dkg_obs1;   /* obsolete */
 746     unsigned short   dkg_nsect;  /* # of sectors per track */
 747     unsigned short   dkg_intrlv; /* interleave factor */
 748     unsigned short   dkg_obs2;   /* obsolete */
 749     unsigned short   dkg_obs3;   /* obsolete */
 750     unsigned short   dkg_apc;    /* alternates per cylinder */
 751                                  /* (SCSI only) */
 752     unsigned short   dkg_rpm;    /* revolutions per min */
 753     unsigned short   dkg_pcyl;   /* # of physical cylinders */
 754     unsigned short   dkg_write_reinstruct; /* # sectors to skip, */
 755                                            /* writes */
 756     unsigned short   dkg_read_reinstruct;  /* # sectors to skip ,*/
 757                                            /* reads */
 758     unsigned short   dkg_extra[7]; /* for compatible expansion */
 759 };
 760 .Ed
 761 .It Dv DKIOCADDBAD
 762 .Pp
 763 This
 764 .Xr ioctl 2
 765 forces the driver to re-examine the alternates slice and
 766 rebuild the internal bad block map accordingly.
 767 It should be used whenever the
 768 alternates slice is changed by any method other than the
 769 .Xr addbadsec 1M
 770 or
 771 .Xr format 1M
 772 utilities.
 773 .Dv DKIOCADDBAD
 774 can only be used for software
 775 remapping on
 776 .Sy IDE
 777 drives;
 778 .Sy SCSI
 779 drives use hardware remapping of alternate sectors.
 780 .It Dv DKIOCPARTINFO
 781 .Pp
 782 The argument is a pointer to a
 783 .Vt part_info
 784 structure (described below).
 785 This
 786 .Xr ioctl 2
 787 gets the driver's notion of the size and extent of the
 788 partition or slice indicated by the file descriptor argument.
 789 .Bd -literal -offset 2n
 790 /*
 791  * Used by applications to get partition or slice information
 792  */
 793 struct part_info {
 794     daddr_t    p_start;
 795     int        p_length;
 796 };
 797 .Ed
 798 .It Dv DKIOCEXTPARTINFO
 799 .Pp
 800 The argument is a pointer to an
 801 .Vt extpart_info
 802 structure (described below).
 803 This ioctl gets the driver's notion of the size and extent of the partition or
 804 slice indicated by the file descriptor argument.
 805 On disks larger than 1TB, this ioctl must be used instead of
 806 .Dv DKIOCPARTINFO .
 807 .Bd -literal -offset 2n
 808 /*
 809  * Used by applications to get partition or slice information
 810  */
 811 struct extpart_info {
 812     diskkaddr_t      p_start;
 813     diskaddr_t       p_length;
 814 };
 815 .Ed
 816 .It Dv DKIOCSETEXTPART
 817 .Pp
 818 This ioctl is used to update the in-memory copy of the logical drive
 819 information maintained by the driver.
 820 The ioctl takes no arguments.
 821 It causes a re-read of the partition information and recreation of minor nodes
 822 if required.
 823 Prior to updating the data structures, the ioctl ensures that the partitions do
 824 not overlap.
 825 Device nodes are created only for valid partition entries.
 826 If there is any change in the partition offset, size or ID from the previous
 827 read, the partition is deemed to have been changed and hence the device nodes
 828 are recreated.
 829 Any modification to any of the logical partitions results in the
 830 recreation of all logical device nodes.
 831 .El
 832 .Sh SEE ALSO
 833 .Xr addbadsec 1M ,
 834 .Xr fdisk 1M ,
 835 .Xr format 1M ,
 836 .Xr ioctl 2 ,
 837 .Xr cmdk 7D ,
 838 .Xr sd 7D ,
 839 .Xr cdio 7I ,
 840 .Xr fdio 7I ,
 841 .Xr hdio 7I
 842 .Sh NOTES
 843 Blocksize information provided in
 844 .Dv DKIOCGMEDIAINFO
 845 is the size (in bytes) of the device's basic unit of operation and can differ
 846 from the blocksize that the Solaris operating environment exports to the user.
 847 Capacity information provided in the
 848 .Dv DKIOCGMEDIAINFO
 849 are for reference only and you are advised to use the values returned by
 850 .Dv DKIOCGGEOM
 851 or other appropriate
 852 .Xr ioctl 2
 853 for accessing data using the standard interfaces.
 854 .Pp
 855 For x86 only: If the
 856 .Dv DKIOCSMBOOT
 857 command is used to modify the Solaris partitions, the VTOC information should
 858 also be set appropriately to reflect the changes to partition.
 859 Failure to do so leads to unexpected results when the
 860 device is closed and reopened fresh at a later time.
 861 This is because a default VTOC is assumed by driver when a Solaris partition
 862 is changed.
 863 The default VTOC persists until the ioctl
 864 .Dv DKIOCSVTOC
 865 is called to modify VTOC or the device is closed and reopened.
 866 At that point, the old valid VTOC is read from
 867 the disk if it is still available.