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 cannot
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 Execute a reset on the device as soon as the current IO
515 operation has completed.
517 Executes an ATAPI soft reset if applicable, otherwise
518 executes an ATA soft reset on the controller.
522 HDIO_DRIVE_TASKFILE execute raw taskfile
524 Note: If you don't have a copy of the ANSI ATA specification
525 handy, you should probably ignore this ioctl.
527 Execute an ATA disk command directly by writing the "taskfile"
528 registers of the drive. Requires ADMIN and RAWIO access
534 ide_task_request_t req_task;
535 u8 outbuf[OUTPUT_SIZE];
536 u8 inbuf[INPUT_SIZE];
538 memset(&task.req_task, 0, sizeof(task.req_task));
539 task.req_task.out_size = sizeof(task.outbuf);
540 task.req_task.in_size = sizeof(task.inbuf);
542 ioctl(fd, HDIO_DRIVE_TASKFILE, &task);
547 (See below for details on memory area passed to ioctl.)
549 io_ports[8] values to be written to taskfile registers
550 hob_ports[8] high-order bytes, for extended commands.
551 out_flags flags indicating which registers are valid
552 in_flags flags indicating which registers should be returned
554 req_cmd command type to be executed
555 out_size size of output buffer
556 outbuf buffer of data to be transmitted to disk
557 inbuf buffer of data to be received from disk (see [1])
561 io_ports[] values returned in the taskfile registers
562 hob_ports[] high-order bytes, for extended commands.
563 out_flags flags indicating which registers are valid (see [2])
564 in_flags flags indicating which registers should be returned
565 outbuf buffer of data to be transmitted to disk (see [1])
566 inbuf buffer of data to be received from disk
569 EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
570 ENOMSG Device is not a disk drive.
571 ENOMEM Unable to allocate memory for task
572 EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
573 EPERM req_cmd == TASKFILE_MULTI_OUT and drive
574 multi-count not yet set.
575 EIO Drive failed the command.
579 [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS
580 FULL OF GOTCHAS. Extreme caution should be used with using
581 this ioctl. A mistake can easily corrupt data or hang the
584 [2] Both the input and output buffers are copied from the
585 user and written back to the user, even when not used.
587 [3] If one or more bits are set in out_flags and in_flags is
588 zero, the following values are used for in_flags.all and
589 written back into in_flags on completion.
591 * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8)
592 if LBA48 addressing is enabled for the drive
593 * IDE_TASKFILE_STD_IN_FLAGS
596 The association between in_flags.all and each enable
597 bitfield flips depending on endianess; fortunately, TASKFILE
598 only uses inflags.b.data bit and ignores all other bits.
599 The end result is that, on any endian machines, it has no
600 effect other than modifying in_flags on completion.
602 [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit)
603 except for four drives per port chipsets. For four drives
604 per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first
605 pair and (0x80|DEV_bit|LBA_bit) for the second pair.
607 [5] The argument to the ioctl is a pointer to a region of
608 memory containing a ide_task_request_t structure, followed
609 by an optional buffer of data to be transmitted to the
610 drive, followed by an optional buffer to receive data from
613 Command is passed to the disk drive via the ide_task_request_t
614 structure, which contains these fields:
616 io_ports[8] values for the taskfile registers
617 hob_ports[8] high-order bytes, for extended commands
618 out_flags flags indicating which entries in the
619 io_ports[] and hob_ports[] arrays
620 contain valid values. Type ide_reg_valid_t.
621 in_flags flags indicating which entries in the
622 io_ports[] and hob_ports[] arrays
623 are expected to contain valid values
626 req_cmd Command type, see below
627 out_size output (user->drive) buffer size, bytes
628 in_size input (drive->user) buffer size, bytes
630 When out_flags is zero, the following registers are loaded.
632 HOB_FEATURE If the drive supports LBA48
633 HOB_NSECTOR If the drive supports LBA48
634 HOB_SECTOR If the drive supports LBA48
635 HOB_LCYL If the drive supports LBA48
636 HOB_HCYL If the drive supports LBA48
642 SELECT First, masked with 0xE0 if LBA48, 0xEF
643 otherwise; then, or'ed with the default
646 If any bit in out_flags is set, the following registers are loaded.
648 HOB_DATA If out_flags.b.data is set. HOB_DATA will
649 travel on DD8-DD15 on little endian machines
650 and on DD0-DD7 on big endian machines.
651 DATA If out_flags.b.data is set. DATA will
652 travel on DD0-DD7 on little endian machines
653 and on DD8-DD15 on big endian machines.
654 HOB_NSECTOR If out_flags.b.nsector_hob is set
655 HOB_SECTOR If out_flags.b.sector_hob is set
656 HOB_LCYL If out_flags.b.lcyl_hob is set
657 HOB_HCYL If out_flags.b.hcyl_hob is set
658 FEATURE If out_flags.b.feature is set
659 NSECTOR If out_flags.b.nsector is set
660 SECTOR If out_flags.b.sector is set
661 LCYL If out_flags.b.lcyl is set
662 HCYL If out_flags.b.hcyl is set
663 SELECT Or'ed with the default value of SELECT and
664 loaded regardless of out_flags.b.select.
666 Taskfile registers are read back from the drive into
667 {io|hob}_ports[] after the command completes iff one of the
668 following conditions is met; otherwise, the original values
669 will be written back, unchanged.
671 1. The drive fails the command (EIO).
672 2. One or more than one bits are set in out_flags.
673 3. The requested data_phase is TASKFILE_NO_DATA.
675 HOB_DATA If in_flags.b.data is set. It will contain
676 DD8-DD15 on little endian machines and
677 DD0-DD7 on big endian machines.
678 DATA If in_flags.b.data is set. It will contain
679 DD0-DD7 on little endian machines and
680 DD8-DD15 on big endian machines.
681 HOB_FEATURE If the drive supports LBA48
682 HOB_NSECTOR If the drive supports LBA48
683 HOB_SECTOR If the drive supports LBA48
684 HOB_LCYL If the drive supports LBA48
685 HOB_HCYL If the drive supports LBA48
691 The data_phase field describes the data transfer to be
692 performed. Value is one of:
700 TASKFILE_IN_DMAQ == IN_DMA (queueing not supported)
702 TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported)
703 TASKFILE_P_IN unimplemented
704 TASKFILE_P_IN_DMA unimplemented
705 TASKFILE_P_IN_DMAQ unimplemented
706 TASKFILE_P_OUT unimplemented
707 TASKFILE_P_OUT_DMA unimplemented
708 TASKFILE_P_OUT_DMAQ unimplemented
710 The req_cmd field classifies the command type. It may be
713 IDE_DRIVE_TASK_NO_DATA
714 IDE_DRIVE_TASK_SET_XFER unimplemented
716 IDE_DRIVE_TASK_OUT unimplemented
717 IDE_DRIVE_TASK_RAW_WRITE
719 [6] Do not access {in|out}_flags->all except for resetting
720 all the bits. Always access individual bit fields. ->all
721 value will flip depending on endianess. For the same
722 reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS
723 constants defined in hdreg.h.
727 HDIO_DRIVE_CMD execute a special drive command
729 Note: If you don't have a copy of the ANSI ATA specification
730 handy, you should probably ignore this ioctl.
734 u8 args[4+XFER_SIZE];
736 ioctl(fd, HDIO_DRIVE_CMD, args);
740 Commands other than WIN_SMART
754 args[] buffer is filled with register values followed by any
755 data returned by the disk.
760 args[4+] NSECTOR * 512 bytes of data returned by the command.
763 EACCES Access denied: requires CAP_SYS_RAWIO
764 ENOMEM Unable to allocate memory for task
765 EIO Drive reports error
769 [1] For commands other than WIN_SMART, args[1] should equal
770 args[3]. SECTOR, LCYL and HCYL are undefined. For
771 WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL
772 respectively. In both cases SELECT will contain the default
773 value for the drive. Please refer to HDIO_DRIVE_TASKFILE
774 notes for the default value of SELECT.
776 [2] If NSECTOR value is greater than zero and the drive sets
777 DRQ when interrupting for the command, NSECTOR * 512 bytes
778 are read from the device into the area following NSECTOR.
779 In the above example, the area would be
780 args[4..4+XFER_SIZE]. 16bit PIO is used regardless of
781 HDIO_SET_32BIT setting.
783 [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER
784 && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA
785 mode, IDE driver will try to tune the transfer mode of the
790 HDIO_DRIVE_TASK execute task and special drive command
792 Note: If you don't have a copy of the ANSI ATA specification
793 handy, you should probably ignore this ioctl.
799 ioctl(fd, HDIO_DRIVE_TASK, args);
803 Taskfile register values:
814 Taskfile register values:
824 EACCES Access denied: requires CAP_SYS_RAWIO
825 ENOMEM Unable to allocate memory for task
826 ENOMSG Device is not a disk drive.
827 EIO Drive failed the command.
831 [1] DEV bit (0x10) of SELECT register is ignored and the
832 appropriate value for the drive is used. All other bits
837 HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK
839 Not implemented, as of 2.6.8.1
843 HDIO_SET_32BIT change io_32bit flags
848 ioctl(fd, HDIO_SET_32BIT, val);
851 New value for io_32bit flag
856 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
857 EACCES Access denied: requires CAP_SYS_ADMIN
858 EINVAL value out of range [0 3]
859 EBUSY Controller busy
864 HDIO_SET_NOWERR change ignore-write-error flag
869 ioctl(fd, HDIO_SET_NOWERR, val);
872 New value for ignore-write-error flag. Used for ignoring
878 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
879 EACCES Access denied: requires CAP_SYS_ADMIN
880 EINVAL value out of range [0 1]
881 EBUSY Controller busy
885 HDIO_SET_DMA change use-dma flag
890 ioctl(fd, HDIO_SET_DMA, val);
893 New value for use-dma flag
898 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
899 EACCES Access denied: requires CAP_SYS_ADMIN
900 EINVAL value out of range [0 1]
901 EBUSY Controller busy
905 HDIO_SET_PIO_MODE reconfig interface to new speed
910 ioctl(fd, HDIO_SET_PIO_MODE, val);
918 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
919 EACCES Access denied: requires CAP_SYS_ADMIN
920 EINVAL value out of range [0 255]
921 EBUSY Controller busy
925 HDIO_SCAN_HWIF register and (re)scan interface
931 ioctl(fd, HDIO_SCAN_HWIF, args);
934 args[0] io address to probe
935 args[1] control address to probe
941 EACCES Access denied: requires CAP_SYS_RAWIO
946 This ioctl initializes the addresses and irq for a disk
947 controller, probes for drives, and creates /proc/ide
948 interfaces as appropriate.
952 HDIO_UNREGISTER_HWIF unregister interface
957 ioctl(fd, HDIO_UNREGISTER_HWIF, index);
960 index index of hardware interface to unregister
965 EACCES Access denied: requires CAP_SYS_RAWIO
969 This ioctl removes a hardware interface from the kernel.
971 Currently (2.6.8) this ioctl silently fails if any drive on
972 the interface is busy.
976 HDIO_SET_WCACHE change write cache enable-disable
981 ioctl(fd, HDIO_SET_WCACHE, val);
984 New value for write cache enable
989 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
990 EACCES Access denied: requires CAP_SYS_ADMIN
991 EINVAL value out of range [0 1]
992 EBUSY Controller busy
996 HDIO_SET_ACOUSTIC change acoustic behavior
1001 ioctl(fd, HDIO_SET_ACOUSTIC, val);
1004 New value for drive acoustic settings
1009 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
1010 EACCES Access denied: requires CAP_SYS_ADMIN
1011 EINVAL value out of range [0 254]
1012 EBUSY Controller busy
1016 HDIO_SET_QDMA change use-qdma flag
1018 Not implemented, as of 2.6.8.1
1022 HDIO_SET_ADDRESS change lba addressing modes
1027 ioctl(fd, HDIO_SET_ADDRESS, val);
1030 New value for addressing mode
1033 2 = 48-bit doing 28-bit
1038 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
1039 EACCES Access denied: requires CAP_SYS_ADMIN
1040 EINVAL value out of range [0 2]
1041 EBUSY Controller busy
1042 EIO Drive does not support lba48 mode.
1050 ioctl(fd, HDIO_SET_IDE_SCSI, val);
1053 New value for scsi emulation mode (?)
1058 EINVAL (bdev != bdev->bd_contains) (not sure what this means)
1059 EACCES Access denied: requires CAP_SYS_ADMIN
1060 EINVAL value out of range [0 1]
1061 EBUSY Controller busy
1067 Not implemented, as of 2.6.8.1