548 lines · plain
1==============================2Summary of `HDIO_` ioctl calls3==============================4 5- Edward A. Falk <efalk@google.com>6 7November, 20048 9This document attempts to describe the ioctl(2) calls supported by10the HD/IDE layer. These are by-and-large implemented (as of Linux 5.11)11drivers/ata/libata-scsi.c.12 13ioctl values are listed in <linux/hdreg.h>. As of this writing, they14are as follows:15 16 ioctls that pass argument pointers to user space:17 18 ======================= =======================================19 HDIO_GETGEO get device geometry20 HDIO_GET_32BIT get current io_32bit setting21 HDIO_GET_IDENTITY get IDE identification info22 HDIO_DRIVE_TASKFILE execute raw taskfile23 HDIO_DRIVE_TASK execute task and special drive command24 HDIO_DRIVE_CMD execute a special drive command25 ======================= =======================================26 27 ioctls that pass non-pointer values:28 29 ======================= =======================================30 HDIO_SET_32BIT change io_32bit flags31 ======================= =======================================32 33 34The information that follows was determined from reading kernel source35code. It is likely that some corrections will be made over time.36 37------------------------------------------------------------------------------38 39General:40 41 Unless otherwise specified, all ioctl calls return 0 on success42 and -1 with errno set to an appropriate value on error.43 44 Unless otherwise specified, all ioctl calls return -1 and set45 errno to EFAULT on a failed attempt to copy data to or from user46 address space.47 48 Unless otherwise specified, all data structures and constants49 are defined in <linux/hdreg.h>50 51------------------------------------------------------------------------------52 53HDIO_GETGEO54 get device geometry55 56 57 usage::58 59 struct hd_geometry geom;60 61 ioctl(fd, HDIO_GETGEO, &geom);62 63 64 inputs:65 none66 67 68 69 outputs:70 hd_geometry structure containing:71 72 73 ========= ==================================74 heads number of heads75 sectors number of sectors/track76 cylinders number of cylinders, mod 6553677 start starting sector of this partition.78 ========= ==================================79 80 81 error returns:82 - EINVAL83 84 if the device is not a disk drive or floppy drive,85 or if the user passes a null pointer86 87 88 notes:89 Not particularly useful with modern disk drives, whose geometry90 is a polite fiction anyway. Modern drives are addressed91 purely by sector number nowadays (lba addressing), and the92 drive geometry is an abstraction which is actually subject93 to change. Currently (as of Nov 2004), the geometry values94 are the "bios" values -- presumably the values the drive had95 when Linux first booted.96 97 In addition, the cylinders field of the hd_geometry is an98 unsigned short, meaning that on most architectures, this99 ioctl will not return a meaningful value on drives with more100 than 65535 tracks.101 102 The start field is unsigned long, meaning that it will not103 contain a meaningful value for disks over 219 Gb in size.104 105 106 107HDIO_GET_IDENTITY108 get IDE identification info109 110 111 usage::112 113 unsigned char identity[512];114 115 ioctl(fd, HDIO_GET_IDENTITY, identity);116 117 inputs:118 none119 120 121 122 outputs:123 ATA drive identity information. For full description, see124 the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in125 the ATA specification.126 127 error returns:128 - EINVAL Called on a partition instead of the whole disk device129 - ENOMSG IDENTIFY DEVICE information not available130 131 notes:132 Returns information that was obtained when the drive was133 probed. Some of this information is subject to change, and134 this ioctl does not re-probe the drive to update the135 information.136 137 This information is also available from /proc/ide/hdX/identify138 139 140 141HDIO_GET_32BIT142 get current io_32bit setting143 144 145 usage::146 147 long val;148 149 ioctl(fd, HDIO_GET_32BIT, &val);150 151 inputs:152 none153 154 155 156 outputs:157 The value of the current io_32bit setting158 159 160 161 notes:162 0=16-bit, 1=32-bit, 2,3 = 32bit+sync163 164 165 166HDIO_DRIVE_TASKFILE167 execute raw taskfile168 169 170 Note:171 If you don't have a copy of the ANSI ATA specification172 handy, you should probably ignore this ioctl.173 174 - Execute an ATA disk command directly by writing the "taskfile"175 registers of the drive. Requires ADMIN and RAWIO access176 privileges.177 178 usage::179 180 struct {181 182 ide_task_request_t req_task;183 u8 outbuf[OUTPUT_SIZE];184 u8 inbuf[INPUT_SIZE];185 } task;186 memset(&task.req_task, 0, sizeof(task.req_task));187 task.req_task.out_size = sizeof(task.outbuf);188 task.req_task.in_size = sizeof(task.inbuf);189 ...190 ioctl(fd, HDIO_DRIVE_TASKFILE, &task);191 ...192 193 inputs:194 195 (See below for details on memory area passed to ioctl.)196 197 ============ ===================================================198 io_ports[8] values to be written to taskfile registers199 hob_ports[8] high-order bytes, for extended commands.200 out_flags flags indicating which registers are valid201 in_flags flags indicating which registers should be returned202 data_phase see below203 req_cmd command type to be executed204 out_size size of output buffer205 outbuf buffer of data to be transmitted to disk206 inbuf buffer of data to be received from disk (see [1])207 ============ ===================================================208 209 outputs:210 211 =========== ====================================================212 io_ports[] values returned in the taskfile registers213 hob_ports[] high-order bytes, for extended commands.214 out_flags flags indicating which registers are valid (see [2])215 in_flags flags indicating which registers should be returned216 outbuf buffer of data to be transmitted to disk (see [1])217 inbuf buffer of data to be received from disk218 =========== ====================================================219 220 error returns:221 - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.222 - ENOMSG Device is not a disk drive.223 - ENOMEM Unable to allocate memory for task224 - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)225 - EPERM226 227 req_cmd == TASKFILE_MULTI_OUT and drive228 multi-count not yet set.229 - EIO Drive failed the command.230 231 notes:232 233 [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS234 FULL OF GOTCHAS. Extreme caution should be used with using235 this ioctl. A mistake can easily corrupt data or hang the236 system.237 238 [2] Both the input and output buffers are copied from the239 user and written back to the user, even when not used.240 241 [3] If one or more bits are set in out_flags and in_flags is242 zero, the following values are used for in_flags.all and243 written back into in_flags on completion.244 245 * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8)246 if LBA48 addressing is enabled for the drive247 * IDE_TASKFILE_STD_IN_FLAGS248 if CHS/LBA28249 250 The association between in_flags.all and each enable251 bitfield flips depending on endianness; fortunately, TASKFILE252 only uses inflags.b.data bit and ignores all other bits.253 The end result is that, on any endian machines, it has no254 effect other than modifying in_flags on completion.255 256 [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit)257 except for four drives per port chipsets. For four drives258 per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first259 pair and (0x80|DEV_bit|LBA_bit) for the second pair.260 261 [5] The argument to the ioctl is a pointer to a region of262 memory containing a ide_task_request_t structure, followed263 by an optional buffer of data to be transmitted to the264 drive, followed by an optional buffer to receive data from265 the drive.266 267 Command is passed to the disk drive via the ide_task_request_t268 structure, which contains these fields:269 270 ============ ===============================================271 io_ports[8] values for the taskfile registers272 hob_ports[8] high-order bytes, for extended commands273 out_flags flags indicating which entries in the274 io_ports[] and hob_ports[] arrays275 contain valid values. Type ide_reg_valid_t.276 in_flags flags indicating which entries in the277 io_ports[] and hob_ports[] arrays278 are expected to contain valid values279 on return.280 data_phase See below281 req_cmd Command type, see below282 out_size output (user->drive) buffer size, bytes283 in_size input (drive->user) buffer size, bytes284 ============ ===============================================285 286 When out_flags is zero, the following registers are loaded.287 288 ============ ===============================================289 HOB_FEATURE If the drive supports LBA48290 HOB_NSECTOR If the drive supports LBA48291 HOB_SECTOR If the drive supports LBA48292 HOB_LCYL If the drive supports LBA48293 HOB_HCYL If the drive supports LBA48294 FEATURE295 NSECTOR296 SECTOR297 LCYL298 HCYL299 SELECT First, masked with 0xE0 if LBA48, 0xEF300 otherwise; then, or'ed with the default301 value of SELECT.302 ============ ===============================================303 304 If any bit in out_flags is set, the following registers are loaded.305 306 ============ ===============================================307 HOB_DATA If out_flags.b.data is set. HOB_DATA will308 travel on DD8-DD15 on little endian machines309 and on DD0-DD7 on big endian machines.310 DATA If out_flags.b.data is set. DATA will311 travel on DD0-DD7 on little endian machines312 and on DD8-DD15 on big endian machines.313 HOB_NSECTOR If out_flags.b.nsector_hob is set314 HOB_SECTOR If out_flags.b.sector_hob is set315 HOB_LCYL If out_flags.b.lcyl_hob is set316 HOB_HCYL If out_flags.b.hcyl_hob is set317 FEATURE If out_flags.b.feature is set318 NSECTOR If out_flags.b.nsector is set319 SECTOR If out_flags.b.sector is set320 LCYL If out_flags.b.lcyl is set321 HCYL If out_flags.b.hcyl is set322 SELECT Or'ed with the default value of SELECT and323 loaded regardless of out_flags.b.select.324 ============ ===============================================325 326 Taskfile registers are read back from the drive into327 {io|hob}_ports[] after the command completes iff one of the328 following conditions is met; otherwise, the original values329 will be written back, unchanged.330 331 1. The drive fails the command (EIO).332 2. One or more than one bits are set in out_flags.333 3. The requested data_phase is TASKFILE_NO_DATA.334 335 ============ ===============================================336 HOB_DATA If in_flags.b.data is set. It will contain337 DD8-DD15 on little endian machines and338 DD0-DD7 on big endian machines.339 DATA If in_flags.b.data is set. It will contain340 DD0-DD7 on little endian machines and341 DD8-DD15 on big endian machines.342 HOB_FEATURE If the drive supports LBA48343 HOB_NSECTOR If the drive supports LBA48344 HOB_SECTOR If the drive supports LBA48345 HOB_LCYL If the drive supports LBA48346 HOB_HCYL If the drive supports LBA48347 NSECTOR348 SECTOR349 LCYL350 HCYL351 ============ ===============================================352 353 The data_phase field describes the data transfer to be354 performed. Value is one of:355 356 =================== ========================================357 TASKFILE_IN358 TASKFILE_MULTI_IN359 TASKFILE_OUT360 TASKFILE_MULTI_OUT361 TASKFILE_IN_OUT362 TASKFILE_IN_DMA363 TASKFILE_IN_DMAQ == IN_DMA (queueing not supported)364 TASKFILE_OUT_DMA365 TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported)366 TASKFILE_P_IN unimplemented367 TASKFILE_P_IN_DMA unimplemented368 TASKFILE_P_IN_DMAQ unimplemented369 TASKFILE_P_OUT unimplemented370 TASKFILE_P_OUT_DMA unimplemented371 TASKFILE_P_OUT_DMAQ unimplemented372 =================== ========================================373 374 The req_cmd field classifies the command type. It may be375 one of:376 377 ======================== =======================================378 IDE_DRIVE_TASK_NO_DATA379 IDE_DRIVE_TASK_SET_XFER unimplemented380 IDE_DRIVE_TASK_IN381 IDE_DRIVE_TASK_OUT unimplemented382 IDE_DRIVE_TASK_RAW_WRITE383 ======================== =======================================384 385 [6] Do not access {in|out}_flags->all except for resetting386 all the bits. Always access individual bit fields. ->all387 value will flip depending on endianness. For the same388 reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS389 constants defined in hdreg.h.390 391 392 393HDIO_DRIVE_CMD394 execute a special drive command395 396 397 Note: If you don't have a copy of the ANSI ATA specification398 handy, you should probably ignore this ioctl.399 400 usage::401 402 u8 args[4+XFER_SIZE];403 404 ...405 ioctl(fd, HDIO_DRIVE_CMD, args);406 407 inputs:408 Commands other than WIN_SMART:409 410 ======= =======411 args[0] COMMAND412 args[1] NSECTOR413 args[2] FEATURE414 args[3] NSECTOR415 ======= =======416 417 WIN_SMART:418 419 ======= =======420 args[0] COMMAND421 args[1] SECTOR422 args[2] FEATURE423 args[3] NSECTOR424 ======= =======425 426 outputs:427 args[] buffer is filled with register values followed by any428 429 430 data returned by the disk.431 432 ======== ====================================================433 args[0] status434 args[1] error435 args[2] NSECTOR436 args[3] undefined437 args[4+] NSECTOR * 512 bytes of data returned by the command.438 ======== ====================================================439 440 error returns:441 - EACCES Access denied: requires CAP_SYS_RAWIO442 - ENOMEM Unable to allocate memory for task443 - EIO Drive reports error444 445 notes:446 447 [1] For commands other than WIN_SMART, args[1] should equal448 args[3]. SECTOR, LCYL and HCYL are undefined. For449 WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL450 respectively. In both cases SELECT will contain the default451 value for the drive. Please refer to HDIO_DRIVE_TASKFILE452 notes for the default value of SELECT.453 454 [2] If NSECTOR value is greater than zero and the drive sets455 DRQ when interrupting for the command, NSECTOR * 512 bytes456 are read from the device into the area following NSECTOR.457 In the above example, the area would be458 args[4..4+XFER_SIZE]. 16bit PIO is used regardless of459 HDIO_SET_32BIT setting.460 461 [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER462 && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA463 mode, IDE driver will try to tune the transfer mode of the464 drive accordingly.465 466 467 468HDIO_DRIVE_TASK469 execute task and special drive command470 471 472 Note: If you don't have a copy of the ANSI ATA specification473 handy, you should probably ignore this ioctl.474 475 usage::476 477 u8 args[7];478 479 ...480 ioctl(fd, HDIO_DRIVE_TASK, args);481 482 inputs:483 Taskfile register values:484 485 ======= =======486 args[0] COMMAND487 args[1] FEATURE488 args[2] NSECTOR489 args[3] SECTOR490 args[4] LCYL491 args[5] HCYL492 args[6] SELECT493 ======= =======494 495 outputs:496 Taskfile register values:497 498 499 ======= =======500 args[0] status501 args[1] error502 args[2] NSECTOR503 args[3] SECTOR504 args[4] LCYL505 args[5] HCYL506 args[6] SELECT507 ======= =======508 509 error returns:510 - EACCES Access denied: requires CAP_SYS_RAWIO511 - ENOMEM Unable to allocate memory for task512 - ENOMSG Device is not a disk drive.513 - EIO Drive failed the command.514 515 notes:516 517 [1] DEV bit (0x10) of SELECT register is ignored and the518 appropriate value for the drive is used. All other bits519 are used unaltered.520 521 522 523HDIO_SET_32BIT524 change io_32bit flags525 526 527 usage::528 529 int val;530 531 ioctl(fd, HDIO_SET_32BIT, val);532 533 inputs:534 New value for io_32bit flag535 536 537 538 outputs:539 none540 541 542 543 error return:544 - EINVAL Called on a partition instead of the whole disk device545 - EACCES Access denied: requires CAP_SYS_ADMIN546 - EINVAL value out of range [0 3]547 - EBUSY Controller busy548