0001 ==============================
0002 Summary of `HDIO_` ioctl calls
0003 ==============================
0004
0005 - Edward A. Falk <efalk@google.com>
0006
0007 November, 2004
0008
0009 This document attempts to describe the ioctl(2) calls supported by
0010 the HD/IDE layer. These are by-and-large implemented (as of Linux 5.11)
0011 drivers/ata/libata-scsi.c.
0012
0013 ioctl values are listed in <linux/hdreg.h>. As of this writing, they
0014 are as follows:
0015
0016 ioctls that pass argument pointers to user space:
0017
0018 ======================= =======================================
0019 HDIO_GETGEO get device geometry
0020 HDIO_GET_32BIT get current io_32bit setting
0021 HDIO_GET_IDENTITY get IDE identification info
0022 HDIO_DRIVE_TASKFILE execute raw taskfile
0023 HDIO_DRIVE_TASK execute task and special drive command
0024 HDIO_DRIVE_CMD execute a special drive command
0025 ======================= =======================================
0026
0027 ioctls that pass non-pointer values:
0028
0029 ======================= =======================================
0030 HDIO_SET_32BIT change io_32bit flags
0031 ======================= =======================================
0032
0033
0034 The information that follows was determined from reading kernel source
0035 code. It is likely that some corrections will be made over time.
0036
0037 ------------------------------------------------------------------------------
0038
0039 General:
0040
0041 Unless otherwise specified, all ioctl calls return 0 on success
0042 and -1 with errno set to an appropriate value on error.
0043
0044 Unless otherwise specified, all ioctl calls return -1 and set
0045 errno to EFAULT on a failed attempt to copy data to or from user
0046 address space.
0047
0048 Unless otherwise specified, all data structures and constants
0049 are defined in <linux/hdreg.h>
0050
0051 ------------------------------------------------------------------------------
0052
0053 HDIO_GETGEO
0054 get device geometry
0055
0056
0057 usage::
0058
0059 struct hd_geometry geom;
0060
0061 ioctl(fd, HDIO_GETGEO, &geom);
0062
0063
0064 inputs:
0065 none
0066
0067
0068
0069 outputs:
0070 hd_geometry structure containing:
0071
0072
0073 ========= ==================================
0074 heads number of heads
0075 sectors number of sectors/track
0076 cylinders number of cylinders, mod 65536
0077 start starting sector of this partition.
0078 ========= ==================================
0079
0080
0081 error returns:
0082 - EINVAL
0083
0084 if the device is not a disk drive or floppy drive,
0085 or if the user passes a null pointer
0086
0087
0088 notes:
0089 Not particularly useful with modern disk drives, whose geometry
0090 is a polite fiction anyway. Modern drives are addressed
0091 purely by sector number nowadays (lba addressing), and the
0092 drive geometry is an abstraction which is actually subject
0093 to change. Currently (as of Nov 2004), the geometry values
0094 are the "bios" values -- presumably the values the drive had
0095 when Linux first booted.
0096
0097 In addition, the cylinders field of the hd_geometry is an
0098 unsigned short, meaning that on most architectures, this
0099 ioctl will not return a meaningful value on drives with more
0100 than 65535 tracks.
0101
0102 The start field is unsigned long, meaning that it will not
0103 contain a meaningful value for disks over 219 Gb in size.
0104
0105
0106
0107 HDIO_GET_IDENTITY
0108 get IDE identification info
0109
0110
0111 usage::
0112
0113 unsigned char identity[512];
0114
0115 ioctl(fd, HDIO_GET_IDENTITY, identity);
0116
0117 inputs:
0118 none
0119
0120
0121
0122 outputs:
0123 ATA drive identity information. For full description, see
0124 the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
0125 the ATA specification.
0126
0127 error returns:
0128 - EINVAL Called on a partition instead of the whole disk device
0129 - ENOMSG IDENTIFY DEVICE information not available
0130
0131 notes:
0132 Returns information that was obtained when the drive was
0133 probed. Some of this information is subject to change, and
0134 this ioctl does not re-probe the drive to update the
0135 information.
0136
0137 This information is also available from /proc/ide/hdX/identify
0138
0139
0140
0141 HDIO_GET_32BIT
0142 get current io_32bit setting
0143
0144
0145 usage::
0146
0147 long val;
0148
0149 ioctl(fd, HDIO_GET_32BIT, &val);
0150
0151 inputs:
0152 none
0153
0154
0155
0156 outputs:
0157 The value of the current io_32bit setting
0158
0159
0160
0161 notes:
0162 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
0163
0164
0165
0166 HDIO_DRIVE_TASKFILE
0167 execute raw taskfile
0168
0169
0170 Note:
0171 If you don't have a copy of the ANSI ATA specification
0172 handy, you should probably ignore this ioctl.
0173
0174 - Execute an ATA disk command directly by writing the "taskfile"
0175 registers of the drive. Requires ADMIN and RAWIO access
0176 privileges.
0177
0178 usage::
0179
0180 struct {
0181
0182 ide_task_request_t req_task;
0183 u8 outbuf[OUTPUT_SIZE];
0184 u8 inbuf[INPUT_SIZE];
0185 } task;
0186 memset(&task.req_task, 0, sizeof(task.req_task));
0187 task.req_task.out_size = sizeof(task.outbuf);
0188 task.req_task.in_size = sizeof(task.inbuf);
0189 ...
0190 ioctl(fd, HDIO_DRIVE_TASKFILE, &task);
0191 ...
0192
0193 inputs:
0194
0195 (See below for details on memory area passed to ioctl.)
0196
0197 ============ ===================================================
0198 io_ports[8] values to be written to taskfile registers
0199 hob_ports[8] high-order bytes, for extended commands.
0200 out_flags flags indicating which registers are valid
0201 in_flags flags indicating which registers should be returned
0202 data_phase see below
0203 req_cmd command type to be executed
0204 out_size size of output buffer
0205 outbuf buffer of data to be transmitted to disk
0206 inbuf buffer of data to be received from disk (see [1])
0207 ============ ===================================================
0208
0209 outputs:
0210
0211 =========== ====================================================
0212 io_ports[] values returned in the taskfile registers
0213 hob_ports[] high-order bytes, for extended commands.
0214 out_flags flags indicating which registers are valid (see [2])
0215 in_flags flags indicating which registers should be returned
0216 outbuf buffer of data to be transmitted to disk (see [1])
0217 inbuf buffer of data to be received from disk
0218 =========== ====================================================
0219
0220 error returns:
0221 - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
0222 - ENOMSG Device is not a disk drive.
0223 - ENOMEM Unable to allocate memory for task
0224 - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
0225 - EPERM
0226
0227 req_cmd == TASKFILE_MULTI_OUT and drive
0228 multi-count not yet set.
0229 - EIO Drive failed the command.
0230
0231 notes:
0232
0233 [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS
0234 FULL OF GOTCHAS. Extreme caution should be used with using
0235 this ioctl. A mistake can easily corrupt data or hang the
0236 system.
0237
0238 [2] Both the input and output buffers are copied from the
0239 user and written back to the user, even when not used.
0240
0241 [3] If one or more bits are set in out_flags and in_flags is
0242 zero, the following values are used for in_flags.all and
0243 written back into in_flags on completion.
0244
0245 * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8)
0246 if LBA48 addressing is enabled for the drive
0247 * IDE_TASKFILE_STD_IN_FLAGS
0248 if CHS/LBA28
0249
0250 The association between in_flags.all and each enable
0251 bitfield flips depending on endianness; fortunately, TASKFILE
0252 only uses inflags.b.data bit and ignores all other bits.
0253 The end result is that, on any endian machines, it has no
0254 effect other than modifying in_flags on completion.
0255
0256 [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit)
0257 except for four drives per port chipsets. For four drives
0258 per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first
0259 pair and (0x80|DEV_bit|LBA_bit) for the second pair.
0260
0261 [5] The argument to the ioctl is a pointer to a region of
0262 memory containing a ide_task_request_t structure, followed
0263 by an optional buffer of data to be transmitted to the
0264 drive, followed by an optional buffer to receive data from
0265 the drive.
0266
0267 Command is passed to the disk drive via the ide_task_request_t
0268 structure, which contains these fields:
0269
0270 ============ ===============================================
0271 io_ports[8] values for the taskfile registers
0272 hob_ports[8] high-order bytes, for extended commands
0273 out_flags flags indicating which entries in the
0274 io_ports[] and hob_ports[] arrays
0275 contain valid values. Type ide_reg_valid_t.
0276 in_flags flags indicating which entries in the
0277 io_ports[] and hob_ports[] arrays
0278 are expected to contain valid values
0279 on return.
0280 data_phase See below
0281 req_cmd Command type, see below
0282 out_size output (user->drive) buffer size, bytes
0283 in_size input (drive->user) buffer size, bytes
0284 ============ ===============================================
0285
0286 When out_flags is zero, the following registers are loaded.
0287
0288 ============ ===============================================
0289 HOB_FEATURE If the drive supports LBA48
0290 HOB_NSECTOR If the drive supports LBA48
0291 HOB_SECTOR If the drive supports LBA48
0292 HOB_LCYL If the drive supports LBA48
0293 HOB_HCYL If the drive supports LBA48
0294 FEATURE
0295 NSECTOR
0296 SECTOR
0297 LCYL
0298 HCYL
0299 SELECT First, masked with 0xE0 if LBA48, 0xEF
0300 otherwise; then, or'ed with the default
0301 value of SELECT.
0302 ============ ===============================================
0303
0304 If any bit in out_flags is set, the following registers are loaded.
0305
0306 ============ ===============================================
0307 HOB_DATA If out_flags.b.data is set. HOB_DATA will
0308 travel on DD8-DD15 on little endian machines
0309 and on DD0-DD7 on big endian machines.
0310 DATA If out_flags.b.data is set. DATA will
0311 travel on DD0-DD7 on little endian machines
0312 and on DD8-DD15 on big endian machines.
0313 HOB_NSECTOR If out_flags.b.nsector_hob is set
0314 HOB_SECTOR If out_flags.b.sector_hob is set
0315 HOB_LCYL If out_flags.b.lcyl_hob is set
0316 HOB_HCYL If out_flags.b.hcyl_hob is set
0317 FEATURE If out_flags.b.feature is set
0318 NSECTOR If out_flags.b.nsector is set
0319 SECTOR If out_flags.b.sector is set
0320 LCYL If out_flags.b.lcyl is set
0321 HCYL If out_flags.b.hcyl is set
0322 SELECT Or'ed with the default value of SELECT and
0323 loaded regardless of out_flags.b.select.
0324 ============ ===============================================
0325
0326 Taskfile registers are read back from the drive into
0327 {io|hob}_ports[] after the command completes iff one of the
0328 following conditions is met; otherwise, the original values
0329 will be written back, unchanged.
0330
0331 1. The drive fails the command (EIO).
0332 2. One or more than one bits are set in out_flags.
0333 3. The requested data_phase is TASKFILE_NO_DATA.
0334
0335 ============ ===============================================
0336 HOB_DATA If in_flags.b.data is set. It will contain
0337 DD8-DD15 on little endian machines and
0338 DD0-DD7 on big endian machines.
0339 DATA If in_flags.b.data is set. It will contain
0340 DD0-DD7 on little endian machines and
0341 DD8-DD15 on big endian machines.
0342 HOB_FEATURE If the drive supports LBA48
0343 HOB_NSECTOR If the drive supports LBA48
0344 HOB_SECTOR If the drive supports LBA48
0345 HOB_LCYL If the drive supports LBA48
0346 HOB_HCYL If the drive supports LBA48
0347 NSECTOR
0348 SECTOR
0349 LCYL
0350 HCYL
0351 ============ ===============================================
0352
0353 The data_phase field describes the data transfer to be
0354 performed. Value is one of:
0355
0356 =================== ========================================
0357 TASKFILE_IN
0358 TASKFILE_MULTI_IN
0359 TASKFILE_OUT
0360 TASKFILE_MULTI_OUT
0361 TASKFILE_IN_OUT
0362 TASKFILE_IN_DMA
0363 TASKFILE_IN_DMAQ == IN_DMA (queueing not supported)
0364 TASKFILE_OUT_DMA
0365 TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported)
0366 TASKFILE_P_IN unimplemented
0367 TASKFILE_P_IN_DMA unimplemented
0368 TASKFILE_P_IN_DMAQ unimplemented
0369 TASKFILE_P_OUT unimplemented
0370 TASKFILE_P_OUT_DMA unimplemented
0371 TASKFILE_P_OUT_DMAQ unimplemented
0372 =================== ========================================
0373
0374 The req_cmd field classifies the command type. It may be
0375 one of:
0376
0377 ======================== =======================================
0378 IDE_DRIVE_TASK_NO_DATA
0379 IDE_DRIVE_TASK_SET_XFER unimplemented
0380 IDE_DRIVE_TASK_IN
0381 IDE_DRIVE_TASK_OUT unimplemented
0382 IDE_DRIVE_TASK_RAW_WRITE
0383 ======================== =======================================
0384
0385 [6] Do not access {in|out}_flags->all except for resetting
0386 all the bits. Always access individual bit fields. ->all
0387 value will flip depending on endianness. For the same
0388 reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS
0389 constants defined in hdreg.h.
0390
0391
0392
0393 HDIO_DRIVE_CMD
0394 execute a special drive command
0395
0396
0397 Note: If you don't have a copy of the ANSI ATA specification
0398 handy, you should probably ignore this ioctl.
0399
0400 usage::
0401
0402 u8 args[4+XFER_SIZE];
0403
0404 ...
0405 ioctl(fd, HDIO_DRIVE_CMD, args);
0406
0407 inputs:
0408 Commands other than WIN_SMART:
0409
0410 ======= =======
0411 args[0] COMMAND
0412 args[1] NSECTOR
0413 args[2] FEATURE
0414 args[3] NSECTOR
0415 ======= =======
0416
0417 WIN_SMART:
0418
0419 ======= =======
0420 args[0] COMMAND
0421 args[1] SECTOR
0422 args[2] FEATURE
0423 args[3] NSECTOR
0424 ======= =======
0425
0426 outputs:
0427 args[] buffer is filled with register values followed by any
0428
0429
0430 data returned by the disk.
0431
0432 ======== ====================================================
0433 args[0] status
0434 args[1] error
0435 args[2] NSECTOR
0436 args[3] undefined
0437 args[4+] NSECTOR * 512 bytes of data returned by the command.
0438 ======== ====================================================
0439
0440 error returns:
0441 - EACCES Access denied: requires CAP_SYS_RAWIO
0442 - ENOMEM Unable to allocate memory for task
0443 - EIO Drive reports error
0444
0445 notes:
0446
0447 [1] For commands other than WIN_SMART, args[1] should equal
0448 args[3]. SECTOR, LCYL and HCYL are undefined. For
0449 WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL
0450 respectively. In both cases SELECT will contain the default
0451 value for the drive. Please refer to HDIO_DRIVE_TASKFILE
0452 notes for the default value of SELECT.
0453
0454 [2] If NSECTOR value is greater than zero and the drive sets
0455 DRQ when interrupting for the command, NSECTOR * 512 bytes
0456 are read from the device into the area following NSECTOR.
0457 In the above example, the area would be
0458 args[4..4+XFER_SIZE]. 16bit PIO is used regardless of
0459 HDIO_SET_32BIT setting.
0460
0461 [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER
0462 && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA
0463 mode, IDE driver will try to tune the transfer mode of the
0464 drive accordingly.
0465
0466
0467
0468 HDIO_DRIVE_TASK
0469 execute task and special drive command
0470
0471
0472 Note: If you don't have a copy of the ANSI ATA specification
0473 handy, you should probably ignore this ioctl.
0474
0475 usage::
0476
0477 u8 args[7];
0478
0479 ...
0480 ioctl(fd, HDIO_DRIVE_TASK, args);
0481
0482 inputs:
0483 Taskfile register values:
0484
0485 ======= =======
0486 args[0] COMMAND
0487 args[1] FEATURE
0488 args[2] NSECTOR
0489 args[3] SECTOR
0490 args[4] LCYL
0491 args[5] HCYL
0492 args[6] SELECT
0493 ======= =======
0494
0495 outputs:
0496 Taskfile register values:
0497
0498
0499 ======= =======
0500 args[0] status
0501 args[1] error
0502 args[2] NSECTOR
0503 args[3] SECTOR
0504 args[4] LCYL
0505 args[5] HCYL
0506 args[6] SELECT
0507 ======= =======
0508
0509 error returns:
0510 - EACCES Access denied: requires CAP_SYS_RAWIO
0511 - ENOMEM Unable to allocate memory for task
0512 - ENOMSG Device is not a disk drive.
0513 - EIO Drive failed the command.
0514
0515 notes:
0516
0517 [1] DEV bit (0x10) of SELECT register is ignored and the
0518 appropriate value for the drive is used. All other bits
0519 are used unaltered.
0520
0521
0522
0523 HDIO_SET_32BIT
0524 change io_32bit flags
0525
0526
0527 usage::
0528
0529 int val;
0530
0531 ioctl(fd, HDIO_SET_32BIT, val);
0532
0533 inputs:
0534 New value for io_32bit flag
0535
0536
0537
0538 outputs:
0539 none
0540
0541
0542
0543 error return:
0544 - EINVAL Called on a partition instead of the whole disk device
0545 - EACCES Access denied: requires CAP_SYS_ADMIN
0546 - EINVAL value out of range [0 3]
0547 - EBUSY Controller busy
