1 Summary of HDIO_ ioctl calls.
2 ============================
4 Edward A. Falk <efalk@google.com>
8 This document attempts to describe the ioctl(2) calls supported by
9 the HD/IDE layer. These are by-and-large implemented (as of Linux 2.6)
10 in drivers/ide/ide.c and drivers/block/scsi_ioctl.c
12 ioctl values are listed in <linux/hdreg.h>. As of this writing, they
15 ioctls that pass argument pointers to user space:
17 HDIO_GETGEO get device geometry
18 HDIO_GET_UNMASKINTR get current unmask setting
19 HDIO_GET_MULTCOUNT get current IDE blockmode setting
20 HDIO_GET_QDMA get use-qdma flag
21 HDIO_SET_XFER set transfer rate via proc
22 HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE
23 HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag
24 HDIO_GET_32BIT get current io_32bit setting
25 HDIO_GET_NOWERR get ignore-write-error flag
26 HDIO_GET_DMA get use-dma flag
27 HDIO_GET_NICE get nice flags
28 HDIO_GET_IDENTITY get IDE identification info
29 HDIO_GET_WCACHE get write cache mode on|off
30 HDIO_GET_ACOUSTIC get acoustic value
31 HDIO_GET_ADDRESS get sector addressing mode
32 HDIO_GET_BUSSTATE get the bus state of the hwif
33 HDIO_TRISTATE_HWIF execute a channel tristate
34 HDIO_DRIVE_RESET execute a device reset
35 HDIO_DRIVE_TASKFILE execute raw taskfile
36 HDIO_DRIVE_TASK execute task and special drive command
37 HDIO_DRIVE_CMD execute a special drive command
38 HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK
40 ioctls that pass non-pointer values:
42 HDIO_SET_MULTCOUNT change IDE blockmode
43 HDIO_SET_UNMASKINTR permit other irqs during I/O
44 HDIO_SET_KEEPSETTINGS keep ioctl settings on reset
45 HDIO_SET_32BIT change io_32bit flags
46 HDIO_SET_NOWERR change ignore-write-error flag
47 HDIO_SET_DMA change use-dma flag
48 HDIO_SET_PIO_MODE reconfig interface to new speed
49 HDIO_SCAN_HWIF register and (re)scan interface
50 HDIO_SET_NICE set nice flags
51 HDIO_UNREGISTER_HWIF unregister interface
52 HDIO_SET_WCACHE change write cache enable-disable
53 HDIO_SET_ACOUSTIC change acoustic behavior
54 HDIO_SET_BUSSTATE set the bus state of the hwif
55 HDIO_SET_QDMA change use-qdma flag
56 HDIO_SET_ADDRESS change lba addressing modes
58 HDIO_SET_IDE_SCSI Set scsi emulation mode on/off
59 HDIO_SET_SCSI_IDE not implemented yet
62 The information that follows was determined from reading kernel source
63 code. It is likely that some corrections will be made over time.
73 Unless otherwise specified, all ioctl calls return 0 on success
74 and -1 with errno set to an appropriate value on error.
76 Unless otherwise specified, all ioctl calls return -1 and set
77 errno to EFAULT on a failed attempt to copy data to or from user
80 Unless otherwise specified, all data structures and constants
81 are defined in <linux/hdreg.h>
85 HDIO_GETGEO get device geometry
89 struct hd_geometry geom;
90 ioctl(fd, HDIO_GETGEO, &geom);
97 hd_geometry structure containing:
100 sectors number of sectors/track
101 cylinders number of cylinders, mod 65536
102 start starting sector of this partition.
106 EINVAL if the device is not a disk drive or floppy drive,
107 or if the user passes a null pointer
112 Not particularly useful with modern disk drives, whose geometry
113 is a polite fiction anyway. Modern drives are addressed
114 purely by sector number nowadays (lba addressing), and the
115 drive geometry is an abstraction which is actually subject
116 to change. Currently (as of Nov 2004), the geometry values
117 are the "bios" values -- presumably the values the drive had
118 when Linux first booted.
120 In addition, the cylinders field of the hd_geometry is an
121 unsigned short, meaning that on most architectures, this
122 ioctl will not return a meaningful value on drives with more
125 The start field is unsigned long, meaning that it will not
126 contain a meaningful value for disks over 219 Gb in size.
131 HDIO_GET_UNMASKINTR get current unmask setting
136 ioctl(fd, HDIO_GET_UNMASKINTR, &val);
141 The value of the drive's current unmask setting
145 HDIO_SET_UNMASKINTR permit other irqs during I/O
150 ioctl(fd, HDIO_SET_UNMASKINTR, val);
153 New value for unmask flag
158 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
159 EACCES Access denied: requires CAP_SYS_ADMIN
160 EINVAL value out of range [0 1]
161 EBUSY Controller busy
166 HDIO_GET_MULTCOUNT get current IDE blockmode setting
171 ioctl(fd, HDIO_GET_MULTCOUNT, &val);
176 The value of the current IDE block mode setting. This
177 controls how many sectors the drive will transfer per
182 HDIO_SET_MULTCOUNT change IDE blockmode
187 ioctl(fd, HDIO_SET_MULTCOUNT, val);
190 New value for IDE block mode setting. This controls how many
191 sectors the drive will transfer per interrupt.
196 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
197 EACCES Access denied: requires CAP_SYS_ADMIN
198 EINVAL value out of range supported by disk.
199 EBUSY Controller busy or blockmode already set.
200 EIO Drive did not accept new block mode.
204 Source code comments read:
206 This is tightly woven into the driver->do_special can not
207 touch. DON'T do it again until a total personality rewrite
210 If blockmode has already been set, this ioctl will fail with
215 HDIO_GET_QDMA get use-qdma flag
217 Not implemented, as of 2.6.8.1
221 HDIO_SET_XFER set transfer rate via proc
223 Not implemented, as of 2.6.8.1
227 HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE
229 Same as HDIO_GET_IDENTITY (see below), except that it only
230 returns the first 142 bytes of drive identity information.
234 HDIO_GET_IDENTITY get IDE identification info
238 unsigned char identity[512];
239 ioctl(fd, HDIO_GET_IDENTITY, identity);
245 ATA drive identity information. For full description, see
246 the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
247 the ATA specification.
250 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
251 ENOMSG IDENTIFY DEVICE information not available
255 Returns information that was obtained when the drive was
256 probed. Some of this information is subject to change, and
257 this ioctl does not re-probe the drive to update the
260 This information is also available from /proc/ide/hdX/identify
264 HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag
269 ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
274 The value of the current "keep settings" flag
278 When set, indicates that kernel should restore settings
283 HDIO_SET_KEEPSETTINGS keep ioctl settings on reset
288 ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
291 New value for keep_settings flag
296 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
297 EACCES Access denied: requires CAP_SYS_ADMIN
298 EINVAL value out of range [0 1]
299 EBUSY Controller busy
303 HDIO_GET_32BIT get current io_32bit setting
308 ioctl(fd, HDIO_GET_32BIT, &val);
313 The value of the current io_32bit setting
317 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
321 HDIO_GET_NOWERR get ignore-write-error flag
326 ioctl(fd, HDIO_GET_NOWERR, &val);
331 The value of the current ignore-write-error flag
335 HDIO_GET_DMA get use-dma flag
340 ioctl(fd, HDIO_GET_DMA, &val);
345 The value of the current use-dma flag
349 HDIO_GET_NICE get nice flags
354 ioctl(fd, HDIO_GET_NICE, &nice);
360 The drive's "nice" values.
364 Per-drive flags which determine when the system will give more
365 bandwidth to other devices sharing the same IDE bus.
366 See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
371 HDIO_SET_NICE set nice flags
377 ioctl(fd, HDIO_SET_NICE, nice);
380 bitmask of nice flags.
385 EACCES Access denied: requires CAP_SYS_ADMIN
386 EPERM Flags other than DSC_OVERLAP and NICE_1 set.
387 EPERM DSC_OVERLAP specified but not supported by drive
391 This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
392 provided by the user.
394 Nice flags are listed in <linux/hdreg.h>, starting with
395 IDE_NICE_DSC_OVERLAP. These values represent shifts.
401 HDIO_GET_WCACHE get write cache mode on|off
406 ioctl(fd, HDIO_GET_WCACHE, &val);
411 The value of the current write cache mode
415 HDIO_GET_ACOUSTIC get acoustic value
420 ioctl(fd, HDIO_GET_ACOUSTIC, &val);
425 The value of the current acoustic settings
429 See HDIO_SET_ACOUSTIC
438 ioctl(fd, HDIO_GET_ADDRESS, &val);
443 The value of the current addressing mode:
446 2 = 48-bit doing 28-bit
451 HDIO_GET_BUSSTATE get the bus state of the hwif
456 ioctl(fd, HDIO_SCAN_HWIF, &state);
461 Current power state of the IDE bus. One of BUSSTATE_OFF,
462 BUSSTATE_ON, or BUSSTATE_TRISTATE
465 EACCES Access denied: requires CAP_SYS_ADMIN
470 HDIO_SET_BUSSTATE set the bus state of the hwif
476 ioctl(fd, HDIO_SCAN_HWIF, state);
479 Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON,
485 EACCES Access denied: requires CAP_SYS_RAWIO
486 EOPNOTSUPP Hardware interface does not support bus power control
491 HDIO_TRISTATE_HWIF execute a channel tristate
493 Not implemented, as of 2.6.8.1. See HDIO_SET_BUSSTATE
497 HDIO_DRIVE_RESET execute a device reset
503 ioctl(fd, HDIO_DRIVE_RESET, args);
510 EACCES Access denied: requires CAP_SYS_ADMIN
514 Abort any current command, prevent anything else from being
515 queued, execute a reset on the device, and issue BLKRRPART
516 ioctl on the block device.
518 Executes an ATAPI soft reset if applicable, otherwise
519 executes an ATA soft reset on the controller.
523 HDIO_DRIVE_TASKFILE execute raw taskfile
525 Note: If you don't have a copy of the ANSI ATA specification
526 handy, you should probably ignore this ioctl.
528 Execute an ATA disk command directly by writing the "taskfile"
529 registers of the drive. Requires ADMIN and RAWIO access
535 ide_task_request_t req_task;
536 u8 outbuf[OUTPUT_SIZE];
537 u8 inbuf[INPUT_SIZE];
539 memset(&task.req_task, 0, sizeof(task.req_task));
540 task.req_task.out_size = sizeof(task.outbuf);
541 task.req_task.in_size = sizeof(task.inbuf);
543 ioctl(fd, HDIO_DRIVE_TASKFILE, &task);
548 (See below for details on memory area passed to ioctl.)
550 io_ports[8] values to be written to taskfile registers
551 hob_ports[8] high-order bytes, for extended commands.
552 out_flags flags indicating which registers are valid
553 in_flags flags indicating which registers should be returned
555 req_cmd command type to be executed
556 out_size size of output buffer
557 outbuf buffer of data to be transmitted to disk
558 inbuf buffer of data to be received from disk (see [1])
562 io_ports[] values returned in the taskfile registers
563 hob_ports[] high-order bytes, for extended commands.
564 out_flags flags indicating which registers are valid (see [2])
565 in_flags flags indicating which registers should be returned
566 outbuf buffer of data to be transmitted to disk (see [1])
567 inbuf buffer of data to be received from disk
570 EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
571 ENOMSG Device is not a disk drive.
572 ENOMEM Unable to allocate memory for task
573 EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
574 EPERM req_cmd == TASKFILE_MULTI_OUT and drive
575 multi-count not yet set.
580 [1] Currently (2.6.8), both the input and output buffers are
581 copied from the user and written back to the user, even when
582 not used. This may be a bug.
584 [2] The out_flags and in_flags are returned to the user after
585 the ioctl completes. Currently (2.6.8) these are the same
586 as the input values, unchanged. In the future, they may have
589 Extreme caution should be used with using this ioctl. A
590 mistake can easily corrupt data or hang the system.
592 The argument to the ioctl is a pointer to a region of memory
593 containing a ide_task_request_t structure, followed by an
594 optional buffer of data to be transmitted to the drive,
595 followed by an optional buffer to receive data from the drive.
597 Command is passed to the disk drive via the ide_task_request_t
598 structure, which contains these fields:
600 io_ports[8] values for the taskfile registers
601 hob_ports[8] high-order bytes, for extended commands
602 out_flags flags indicating which entries in the
603 io_ports[] and hob_ports[] arrays
604 contain valid values. Type ide_reg_valid_t.
605 in_flags flags indicating which entries in the
606 io_ports[] and hob_ports[] arrays
607 are expected to contain valid values
610 req_cmd Command type, see below
611 out_size output (user->drive) buffer size, bytes
612 in_size input (drive->user) buffer size, bytes
614 This ioctl does not necessarily respect all flags in the
615 out_flags and in_flags values -- some taskfile registers
616 may be written or read even if not requested in the flags.
617 Unused fields of io_ports[] and hob_ports[] should be set
620 The data_phase field describes the data transfer to be
621 performed. Value is one of:
639 The req_cmd field classifies the command type. It may be
642 IDE_DRIVE_TASK_NO_DATA
643 IDE_DRIVE_TASK_SET_XFER
646 IDE_DRIVE_TASK_RAW_WRITE
653 HDIO_DRIVE_CMD execute a special drive command
655 Note: If you don't have a copy of the ANSI ATA specification
656 handy, you should probably ignore this ioctl.
660 u8 args[4+XFER_SIZE];
662 ioctl(fd, HDIO_DRIVE_CMD, args);
666 Taskfile register values:
674 args[] buffer is filled with register values followed by any
675 data returned by the disk.
680 args[4+] NSECTOR * 512 bytes of data returned by the command.
683 EACCES Access denied: requires CAP_SYS_RAWIO
684 ENOMEM Unable to allocate memory for task
688 Taskfile registers IDE_LCYL, IDE_HCYL, and IDE_SELECT are
689 set to zero before executing the command.
693 HDIO_DRIVE_TASK execute task and special drive command
695 Note: If you don't have a copy of the ANSI ATA specification
696 handy, you should probably ignore this ioctl.
702 ioctl(fd, HDIO_DRIVE_TASK, args);
706 Taskfile register values:
717 Taskfile register values:
727 EACCES Access denied: requires CAP_SYS_RAWIO
728 ENOMEM Unable to allocate memory for task
733 HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK
735 Not implemented, as of 2.6.8.1
739 HDIO_SET_32BIT change io_32bit flags
744 ioctl(fd, HDIO_SET_32BIT, val);
747 New value for io_32bit flag
752 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
753 EACCES Access denied: requires CAP_SYS_ADMIN
754 EINVAL value out of range [0 3]
755 EBUSY Controller busy
760 HDIO_SET_NOWERR change ignore-write-error flag
765 ioctl(fd, HDIO_SET_NOWERR, val);
768 New value for ignore-write-error flag. Used for ignoring
774 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
775 EACCES Access denied: requires CAP_SYS_ADMIN
776 EINVAL value out of range [0 1]
777 EBUSY Controller busy
781 HDIO_SET_DMA change use-dma flag
786 ioctl(fd, HDIO_SET_DMA, val);
789 New value for use-dma flag
794 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
795 EACCES Access denied: requires CAP_SYS_ADMIN
796 EINVAL value out of range [0 1]
797 EBUSY Controller busy
801 HDIO_SET_PIO_MODE reconfig interface to new speed
806 ioctl(fd, HDIO_SET_PIO_MODE, val);
814 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
815 EACCES Access denied: requires CAP_SYS_ADMIN
816 EINVAL value out of range [0 255]
817 EBUSY Controller busy
821 HDIO_SCAN_HWIF register and (re)scan interface
827 ioctl(fd, HDIO_SCAN_HWIF, args);
830 args[0] io address to probe
831 args[1] control address to probe
837 EACCES Access denied: requires CAP_SYS_RAWIO
842 This ioctl initializes the addresses and irq for a disk
843 controller, probes for drives, and creates /proc/ide
844 interfaces as appropiate.
848 HDIO_UNREGISTER_HWIF unregister interface
853 ioctl(fd, HDIO_UNREGISTER_HWIF, index);
856 index index of hardware interface to unregister
861 EACCES Access denied: requires CAP_SYS_RAWIO
865 This ioctl removes a hardware interface from the kernel.
867 Currently (2.6.8) this ioctl silently fails if any drive on
868 the interface is busy.
872 HDIO_SET_WCACHE change write cache enable-disable
877 ioctl(fd, HDIO_SET_WCACHE, val);
880 New value for write cache enable
885 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
886 EACCES Access denied: requires CAP_SYS_ADMIN
887 EINVAL value out of range [0 1]
888 EBUSY Controller busy
892 HDIO_SET_ACOUSTIC change acoustic behavior
897 ioctl(fd, HDIO_SET_ACOUSTIC, val);
900 New value for drive acoustic settings
905 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
906 EACCES Access denied: requires CAP_SYS_ADMIN
907 EINVAL value out of range [0 254]
908 EBUSY Controller busy
912 HDIO_SET_QDMA change use-qdma flag
914 Not implemented, as of 2.6.8.1
918 HDIO_SET_ADDRESS change lba addressing modes
923 ioctl(fd, HDIO_SET_ADDRESS, val);
926 New value for addressing mode
929 2 = 48-bit doing 28-bit
934 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
935 EACCES Access denied: requires CAP_SYS_ADMIN
936 EINVAL value out of range [0 2]
937 EBUSY Controller busy
938 EIO Drive does not support lba48 mode.
946 ioctl(fd, HDIO_SET_IDE_SCSI, val);
949 New value for scsi emulation mode (?)
954 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
955 EACCES Access denied: requires CAP_SYS_ADMIN
956 EINVAL value out of range [0 1]
957 EBUSY Controller busy
963 Not implemented, as of 2.6.8.1