Ioctl Requests dkio(7I)
NAME
dkio - disk control operations
SYNOPSIS
#include
#include
DESCRIPTION
Disk drivers support a set of ioctl(2) requests for disk
controller, geometry, and partition information. Basic to
these ioctl() requests are the definitions in .
IOCTLS
The following ioctl() requests set and/or retrieve the
current disk controller, partitions, or geometry information
on all architectures:
DKIOCINFO The argument is a pointer to a dkcinfo struc-
ture (described below). This structure tells
the controller-type and attributes regarding
bad-block processing done on the controller.
/*
* Structures and definitions for disk I/O control commands
*/
#define DKDEVLEN 16 /* device name max length, */
/* including unit # and NUL */
/* Used for controller info */
struct dkcinfo {
char dkicname[DKDEVLEN]; /* controller name */
/*(no unit #)*/
ushortt dkictype; /* controller type */
ushortt dkiflags; /* flags */
ushortt dkicnum; /* controller number */
uintt dkiaddr; /* controller address */
uintt dkispace; /* controller bus type */
uintt dkiprio; /* interrupt priority */
uintt dkivec; /* interrupt vector */
char dkidname[DKDEVLEN]; /* drive name (no unit #) */
uintt dkiunit; /* unit number */
uintt dkislave; /* slave number */
ushortt dkipartition; /* partition number */
ushortt dkimaxtransfer; /* maximum transfer size */
/* in DEVBSIZE */
};
/*
* Controller types
SunOS 5.11 Last change: 29 Jul 2008 1
Ioctl Requests dkio(7I)
*/
#define DKCUNKNOWN 0
#define DKCDROM 1 /* CD-ROM, SCSI or other */
#define DKCWDC2880 2
#define DKCX0 3 /* unassigned */
#define DKCX1 4 /* unassigned */
#define DKCDSD5215 5
#define DKCACB4000 7
#define DKCX2 9 /* unassigned */
#define DKCNCRFLOPY 10
#define DKCSMSFLOPY 12
#define DKCSCSICS 13 /* SCSI CS compatible */
#define DKCINTEL82072 14 /* native floppy chip */
#define DKCMD 16 /* meta-disk (virtual-disk) */
/* driver */
#define DKCINTEL82077 19 /* 82077 floppy disk */
/* controller */
#define DKCDIRECT 20 /* Intel direct attached */
/* device (IDE) */
#define DKCPCMCIAMEM 21 /* PCMCIA memory disk-like */
/* type */
#define DKCPCMCIATA 22 /* PCMCIA AT Attached type */
/*
* Sun reserves up through 1023
*/
#define DKCUSTOMERBASE 1024
/*
* Flags
*/
#define DKIBAD144 0x01 /* use DEC std 144 */
/* bad sector fwding */
#define DKIMAPTRK 0x02 /* controller does */
/* track mapping */
#define DKIFMTRK 0x04 /* formats only full
/* track at a time*/
#define DKIFMTVOL 0x08 /* formats only full */
/* volume at a time*/
#define DKIFMTCYL 0x10 /* formats only full */
/* cylinders at a time*/
#define DKIHEXUNIT 0x20 /* unit number printed as */
/* 3 hexdigits */
#define DKIPCMCIAPFD 0x40 /* PCMCIA pseudo-floppy */
/* memory card */
DKIOCGAPART The argument is a pointer to a dkallmap
structure (described below). This ioctl()
SunOS 5.11 Last change: 29 Jul 2008 2
Ioctl Requests dkio(7I)
gets the controller's notion of the current
partition table for disk drive.
DKIOCSAPART The argument is a pointer to a dkallmap
structure (described below). This ioctl()
sets the controller's notion of the partition
table without changing the disk itself.
/*
* Partition map (part of dklabel)
*/ struct dkmap {
daddrt dklcylno; /* starting cylinder */
daddrt dklnblk; /* number of blocks */
};
/*
* Used for all partitions
*/
struct dkmap {
struct dkallmap {
struct dkmap dkamap[NDKMAP];
};
DKIOCGEOM The argument is a pointer to a dkgeom struc-
ture (described below). This ioctl() gets the
controller's notion of the current geometry of
the disk drive.
DKIOCSGEOM The argument is a pointer to a dkgeom struc-
ture (described below). This ioctl() sets the
controller's notion of the geometry without
changing the disk itself.
DKIOCGVTOC The argument is a pointer to a vtoc structure
(described below). This ioctl() returns the
device's current volume table of contents
(VTOC.) For disks larger than 1TB,
DKIOCGEXTVTOC must be used instead.
DKIOCSVTOC The argument is a pointer to a vtoc structure
(described below). This ioctl() changes the
VTOC associated with the device. For disks
larger than 1TB, DKIOCSEXTVTOC must be used
instead.
struct partition {
SunOS 5.11 Last change: 29 Jul 2008 3
Ioctl Requests dkio(7I)
ushortt ptag; /* ID tag of partition */
ushortt pflag; /* permission flags */
daddrt pstart; /* start sector of partition */
long psize; /* # of blocks in partition */
};
If DKIOCSVTOC is used with a floppy diskette, the pstart
field must be the first sector of a cylinder. To compute the
number of sectors per cylinder, multiply the number of heads
by the number of sectors per track.
struct vtoc {
unsigned long vbootinfo[3]; /* info needed by mboot
/* (unsupported)*/
unsigned long vsanity; /* to verify vtoc sanity */
unsigned long vversion; /* layout version */
char vvolume[LENDKLVOL]; /* volume name */
ushortt vsectorsz;
sector size in bytes*/
ushortt vnparts;
number of partitions*/
unsigned long vreserved[10]; /* free space */
struct partition vpart[VNUMPAR]; /* partition headers*/
timet timestamp[VNUMPAR]; /* partition timestamp
/* (unsupported)*/
char vasciilabel[LENDKLASCI]; /* compatibility */
};
/*
* Partition permission flags
*/
#define VUNMNT 0x01 /* Unmountable partition */
#define VRONLY 0x10 /* Read only */
/*
* Partition identification tags
*/
#define VUNASIGNED 0x00 /* unassigned partition */
#define VBOT 0x01 /* Boot partition */
#define VROT 0x02 /* Root filesystem */
#define VSWAP 0x03 /* Swap filesystem */
#define VUSR 0x04 /* Usr filesystem */
#define VBACKUP 0x05 /* full disk */
#define VAR 0x07 /* Var partition */
#define VHOME 0x08 /* Home partition */
#define VALTSCTR 0x09 /* Alternate sector partition */
SunOS 5.11 Last change: 29 Jul 2008 4
Ioctl Requests dkio(7I)
DKIOCGEXTVTOC The argument is a pointer to an extvtoc
structure (described below). This ioctl
returns the device's current volume table
of contents (VTOC). VTOC is extended to
support a disk up to 2TB in size. For
disks larger than 1TB this ioctl must be
used instead of DKIOCGVTOC.
DKIOCSEXTVTOC: The argument is a pointer to an extvtoc
structure (described below). This ioctl
changes the VTOC associated with the dev-
ice. VTOC is extended to support a disk up
to 2TB in size. For disks larger than 1TB
this ioctl must be used instead of
DKIOCSVTOC.
struct extpartition {
ushortt ptag; /* ID tag of partition */
ushortt pflag; /* permission flags */
ushortt ppad[2]; /* reserved */
diskaddrt pstart; /* start sector no of partition */
diskaddrt psize; /* # of blocks in partition */
};
struct extvtoc {
uint64t vbootinfo[3]; /* info needed by mboot (unsupported) */
uint64t vsanity; /* to verify vtoc sanity */
uint64t vversion; /* layout version */
char vvolume[LENDKLVOL]; /* volume name */
ushortt vsectorsz; /* sector size in bytes */
ushortt vnparts; /* number of partitions */
ushortt pad[2];
uint64t vreserved[10];
struct extpartition vpart[VNUMPAR]; /* partition headers */
uint64t timestamp[VNUMPAR]; /* partition timestamp (unsupported) */
char vasciilabel[LENDKLASCI]; /* for compatibility */
};
Partition permissions flags and identification tags
are defined the same as vtoc structure.
DKIOCEJECT If the drive supports removable media,
this ioctl() requests the disk drive to
eject its disk.
DKIOCREMOVABLE The argument to this ioctl() is an
integer. After successful completion,
SunOS 5.11 Last change: 29 Jul 2008 5
Ioctl Requests dkio(7I)
this ioctl() sets that integer to a
non-zero value if the drive in question
has removable media. If the media is
not removable, the integer is set to 0.
DKIOCHOTPLUGABLE The argument to this ioctl() is an
integer. After successful comple-
tion, this ioctl() sets that integer to
a non-zero value if the drive in ques-
tion is hotpluggable. If the media is
not hotpluggable, the integer is set to
0.
DKIOCSTATE This ioctl() blocks until the state of
the drive, inserted or ejected, is
changed. The argument is a pointer to a
dkiostate, enum, whose possible
enumerations are listed below. The ini-
tial value should be either the last
reported state of the drive, or
DKIONONE. Upon return, the enum
pointed to by the argument is updated
with the current state of the drive.
enum dkiostate {
DKIONONE, /* Return disk's current state */
DKIOEJECTED, /* Disk state is 'ejected' */
DKIOINSERTED /* Disk state is 'inserted' */
};
DKIOCLOCK For devices with removable media, this
ioctl() requests the disk drive to lock
the door.
DKIOCUNLOCK For devices with removable media, this
ioctl() requests the disk drive to unlock
the door.
DKIOCGMEDIAINFO The argument to this ioctl() is a pointer
to a dkminfo structure. The structure
indicates the type of media or the com-
mand set profile used by the drive to
operate on the media. The dkminfo struc-
ture also indicates the logical media
blocksize the drive uses as the basic
unit blocksize of operation and the raw
SunOS 5.11 Last change: 29 Jul 2008 6
Ioctl Requests dkio(7I)
formatted capacity of the media in number
of logical blocks.
/*
* Used for media info or profile info
*/
struct dkminfo {
uintt dkimediatype; /* Media type or profile info */
uintt dkilbsize; /* Logical blocksize of media */
diskaddrt dkicapacity; /* Capacity as # of dkilbsize blks */
};
/*
* Media types or profiles known
*/
#define DKUNKNOWN 0x00 /* Media inserted - type unknown */
/*
* SF 8090 Specification Version 3, media types 0x01 - 0xfffe are retained to
* maintain compatibility with SF8090. The following define the
* optical media type.
*/
#define DKMOERASABLE 0x03 /* MO Erasable */
#define DKMOWRITEONCE 0x04 /* MO Write once */
#define DKASMO 0x05 /* AS MO */
#define DKCDROM 0x08 /* CDROM */
#define DKCDR 0x09 /* CD-R */
#define DKCDRW 0x0A /* CD-RW */
#define DKDVDROM 0x10 /* DVD-ROM */
#define DKDVDR 0x11 /* DVD-R */
#define DKDVDRAM 0x12 /* DVDRAM or DVD-RW */
/*
* Media types for other rewritable magnetic media
*/
#define DKFIXEDISK 0x10001 /* Fixed disk SCSI or otherwise */
#define DKFLOPY 0x10002 /* Floppy media */
#define DKZIP 0x10003 /* IOMEGA ZIP media */
#define DKJAZ 0x10004 /* IOMEGA JAZ media */
If the media exists and the host can obtain a current pro-
file list, the command succeeds and returns the dkminfo
structure with data representing that media.
If there is no media in the drive, the command fails and the
host returns an ENXIO error, indicating that it cannot
gather the information requested.
SunOS 5.11 Last change: 29 Jul 2008 7
Ioctl Requests dkio(7I)
If the profile list is not available, the host attempts to
identify the media-type based on the available information.
If identification is not possible, the host returns media
type DKUNKNOWN. See NOTES for blocksize usage and capacity
information.
DKIOCSMBOT The argument is a pointer to struct mboot.
Copies the mboot information supplied in
the argument to the absolute sector 0 of
the device. Prior to copying the informa-
tion, this ioctl() performs the following
checks on the mboot data:
o Ensures that the signature field
is set to 0xA55.
o Ensures that partitions do not
overlap.
o On SPARC platforms, determines if
the device is a removable media.
If the above verification fails, errno is
set to EINVAL and the ioctl() command
fails.
x86 Platforms - Upon successful write of
mboot, the partition map structure main-
tained in the driver is updated. If the
new Solaris partition is different from
the previous one, the internal VTOC table
maintained in the driver is set as fol-
lows:
If SUNOSVTOC8 is defined:
Partition: 0. Start: 0. Capacity = Capa-
city of device.
Partition: 2. Start: 0. Capacity = Capa-
city of device.
If SUNOSVTOC16 is defined:
Partition: 2. Start: 0. Size = Size speci-
fied in mboot - 2 cylinders.
Partition: 8. Start: 0. Size =
Sectors/cylinder.
SunOS 5.11 Last change: 29 Jul 2008 8
Ioctl Requests dkio(7I)
Partition: 9. Start: Sectors/cylinder.
Size = 2 * sectors/cylinder
To determine if the Solaris partition has
changed:
If either offset or the size of the
Solaris partition is different from the
previous one then it shall be deemed to
have changed. In all other cases, the
internal VTOC info remains as before.
SPARC Platforms - The VTOC label and mboot
both occupy the same location, namely sec-
tor 0. As a result, following the success-
ful write of mboot info, the internal VTOC
table maintained in the driver is set as
follows:
Partition: 0. Start: 0. Size = Capacity of
device.
Partition: 2. Start: 0. Size = Capacity of
device.
See the NOTES section for usage of
DKIOCSMBOT when modifying Solaris parti-
tions.
DKIOCGETVOLCAP This ioctl provides information and status
of available capabilities.
vcinfo is a bitmap and the valid flag
values are:
DKVABRCAP - Capable of application-based recovery
DKVDMRCAP - Ability to read specific copy of data when
multiple copies exist. For example, in a two
way mirror, this ioctl is used to read each
side of the mirror.
vcset is a bitmap and the valid flag
values are:
DKVABRCAP - This flag is set if ABR has been set on a device
that supports ABR functionality.
DKVDMRCAP - Directed read has been enabled.
Note: These capabilities are not required
to be persistent across a system reboot
and their persistence depends upon the
SunOS 5.11 Last change: 29 Jul 2008 9
Ioctl Requests dkio(7I)
implementation. For example, if the ABR
capability for a DRL mirror simply clears
the dirty-region list and subseqently
stops updating this list, there is no rea-
son for persistence because the VM
recovery is a no-op. Conversely, if the
ABR capability is applied to a non-DRL
mirror to indicate that the VM should not
perform a full recovery of the mirror fol-
lowing a system crash, the capability must
be persistent so that the VM know whether
or not to perform recovery.
Return Errors:
EINVAL - Invalid device for this opera-
tion.
ENOTSUP - Functionality that is attempted
to be set is not supported.
DKIOCSETVOLCAP This ioctl sets the available capabilities
for the device. If a capability flag is
not set in vcset, that capability is
cleared.
vcinfo flags are ignored
vcset valid flags are:
DKVABRCAP - Flag to set application-based recovery. A device can
successfully support ABR only if it is capable.
DKVDMRCAP - Flag to set directed read.
int
ioctl(int , DKIODMR, voldirectedrd *);
DKIODMR This ioctl allows highly available appli-
cations to perform round-robin reads from
the underlying devices of a replicated
device.
vdroffset - offset at which the read should occur.
vdrnbytes - number of bytes to be read
vdrbytesread - number of bytes successfully read by the kernel.
vdrdata - pointer to a user allocated buffer to return the data
read
vdrside - side to be read. Initialized to DKVSIDEINIT
SunOS 5.11 Last change: 29 Jul 2008 10
Ioctl Requests dkio(7I)
vdrsidename - The volume name that has been read.
Valid vdrflags are:
DKVDMRNEXTSIDE (set by user)
DKVDMRDONE (return value)
DKVDMREROR (return value)
DKVDMRSUCES(return value)
DKVDMRSHORT(return value)
The calling sequence is as follows: The
caller sets the vdrflags to
DKDMRNEXTSIDE and vdrside to
DKVSIDEINIT at the start. Subsequent
calls should be made without any changes
to these values. If they are changed the
results of the ioctl are indeterminate.
When DKVSIDEINIT is set, the call
results in the kernel reading from the
first side. The kernel updates vdrside to
indicate the side that was read, and
vdrsidename to contain the name of that
side. vdrdata contains the data that was
read. Therefore to perform a round-robin
read all of the valid sides, there is no
need for the caller to change the contents
of vdrside.
Subsequent ioctl calls result in reads
from the next valid side until all valid
sides have been read. On success, the ker-
nel sets DKVDMRSUCES. The following
table shows the values of vdrflags that
are returned when an error occurs:
vdrflags vdrside Notes
------------------------------------------------------------
DKVDMREROR DKVSIDEINIT No valid side to read
DKVDMRDONE Not Init side All valid sides read
DKVDMRSHORT Any value Bytes requested cannot
be read. vdrbytesread
set to bytes actually
read.
Typical code fragment:
enable->vcset = DKVABRSET;
retval = ioctl(filedes, DKIOSETVOLCAP, enable);
if (retval != EINVAL retval != ENOTSUP) {
if (info->vcset & DKVDMRSET) {
dr->vdrflags = DKVDMRNEXTSIDE;
SunOS 5.11 Last change: 29 Jul 2008 11
Ioctl Requests dkio(7I)
dr->vdrside = DKVSIDEINIT;
dr->vdrnbytes = 1024;
dr->vdroffset = 0xff00;
do {
rval =ioctl(fildes, DKIODMR, dr);
if (rval != EINVAL) {
/* Process data */
}
} while (rval != EINVAL dr->vdrflags &
(DKVDMRDONE DKVDMREROR DKVDMRSHORT)
}
}
RETURN VALUES
Upon successful completion, the value returned is 0. Other-
wise, -1 is returned and errno is set to indicate the
error.
x86 Only
The following ioctl() requests set and/or retrieve the
current disk controller, partitions, or geometry information
on the x86 architecture.
DKIOCGPHYGEOM The argument is a pointer to a dkgeom
structure (described below). This ioctl()
gets the driver's notion of the physical
geometry of the disk drive. It is func-
tionally identical to the DKIOCGEOM
ioctl().
DKIOCGVIRTGEOM The argument is a pointer to a dkgeom
structure (described below). This ioctl()
gets the controller's (and hence the
driver's) notion of the virtual geometry
of the disk drive. Virtual geometry is a
view of the disk geometry maintained by
the firmware in a host bus adapter or
disk controller. If the disk is larger
than 8 Gbytes, this ioctl fails because a
CHS-based geometry is not relevant or
useful for this drive.
/*
* Definition of a disk's geometry
*/
*/struct dkgeom {
unsigned shor dkgncyl; /* # of data cylinders */
unsigned shor dkgacyl; /* # of alternate cylinders */
SunOS 5.11 Last change: 29 Jul 2008 12
Ioctl Requests dkio(7I)
unsigned short dkgbcyl; /* cyl offset (for fixed head area) */
unsigned short dkgnhead; /* # of heads */
unsigned short dkgobs1; /* obsolete */
unsigned short dkgnsect; /* # of sectors per track*/
unsigned short dkgintrlv; /* interleave factor */
unsigned short dkgobs2; /* obsolete */
unsigned short dkgobs3; /* obsolete */
unsigned short dkgapc; /* alternates per cylinder */
/* (SCSI only) */
unsigned short dkgrpm; /* revolutions per min*/
unsigned short dkgpcyl; /* # of physical cylinders */
unsigned short dkgwritereinstruct; /* # sectors to skip, writes*/
unsigned short dkgreadreinstruct; /* # sectors to skip, reads*/
unsigned short dkgextra[7]; /* for compatible expansion*/
};
DKIOCADBAD This ioctl() forces the driver to re-
examine the alternates slice and rebuild
the internal bad block map accordingly.
It should be used whenever the alter-
nates slice is changed by any method
other than the addbadsec(1M) or
format(1M) utilities. DKIOCADBAD can
only be used for software remapping on
IDE drives; SCSI drives use hardware
remapping of alternate sectors.
DKIOCPARTINFO The argument is a pointer to a partinfo
structure (described below). This
ioctl() gets the driver's notion of the
size and extent of the partition or
slice indicated by the file descriptor
argument.
/*
* Used by applications to get partition or slice information
*/
struct partinfo {
daddrt pstart;
int plength;
};
DKIOCEXTPARTINFO The argument is a pointer to an
extpartinfo structure (described
below). This ioctl() gets
the driver's notion of the size and
extent of the partition or slice indi-
cated by the file descriptor argument.
SunOS 5.11 Last change: 29 Jul 2008 13
Ioctl Requests dkio(7I)
On disks larger than 1TB, this ioctl
must be used instead of DKIOCPARTINFO.
/*
* Used by applications to get partition or slice information
*/
struct extpartinfo {
diskkaddrt pstart;
diskaddrt plength;
};
SEE ALSO
fdisk(1M), format(1M), ioctl(2), sd(7D), cdio(7I), fdio(7I),
hdio(7I)
x86 Only
addbadsec(1M), cmdk(7D)
NOTES
Blocksize information provided in DKIOCGMEDIAINFO is the
size (in bytes) of the device's basic unit of operation and
may differ from the blocksize that the Solaris operating
environment exports to the user. Capacity information pro-
vided in the DKIOCGMEDIAINFO are for reference only and you
are advised to use the values returned by DKIOCGEOM or
other appropriate ioctl for accessing data using the stan-
dard interfaces.
For x86 only: If the DKIOCSMBOT command is used to modify
the Solaris partitions, the VTOC information should also be
set appropriately to reflect the the changes to partition.
Failure to do so will lead to unexpected results when the
device is closed and re-opened fresh at a later time. This
is because a default VTOC is assumed by driver when a
Solaris partition is changed. The default VTOC will persist
until the ioctl DKIOCSVTOC is called to modify VTOC or the
device is closed and re-opened. At that point, the old valid
VTOC will be read from the disk if it is still available.
SunOS 5.11 Last change: 29 Jul 2008 14
|
