1============================== 2Summary of `HDIO_` ioctl calls 3============================== 4 5- Edward A. Falk <efalk@google.com> 6 7November, 2004 8 9This document attempts to describe the ioctl(2) calls supported by 10the 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, they 14are as follows: 15 16 ioctls that pass argument pointers to user space: 17 18 ======================= ======================================= 19 HDIO_GETGEO get device geometry 20 HDIO_GET_32BIT get current io_32bit setting 21 HDIO_GET_IDENTITY get IDE identification info 22 HDIO_DRIVE_TASKFILE execute raw taskfile 23 HDIO_DRIVE_TASK execute task and special drive command 24 HDIO_DRIVE_CMD execute a special drive command 25 ======================= ======================================= 26 27 ioctls that pass non-pointer values: 28 29 ======================= ======================================= 30 HDIO_SET_32BIT change io_32bit flags 31 ======================= ======================================= 32 33 34The information that follows was determined from reading kernel source 35code. 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 success 42 and -1 with errno set to an appropriate value on error. 43 44 Unless otherwise specified, all ioctl calls return -1 and set 45 errno to EFAULT on a failed attempt to copy data to or from user 46 address space. 47 48 Unless otherwise specified, all data structures and constants 49 are defined in <linux/hdreg.h> 50 51------------------------------------------------------------------------------ 52 53HDIO_GETGEO 54 get device geometry 55 56 57 usage:: 58 59 struct hd_geometry geom; 60 61 ioctl(fd, HDIO_GETGEO, &geom); 62 63 64 inputs: 65 none 66 67 68 69 outputs: 70 hd_geometry structure containing: 71 72 73 ========= ================================== 74 heads number of heads 75 sectors number of sectors/track 76 cylinders number of cylinders, mod 65536 77 start starting sector of this partition. 78 ========= ================================== 79 80 81 error returns: 82 - EINVAL 83 84 if the device is not a disk drive or floppy drive, 85 or if the user passes a null pointer 86 87 88 notes: 89 Not particularly useful with modern disk drives, whose geometry 90 is a polite fiction anyway. Modern drives are addressed 91 purely by sector number nowadays (lba addressing), and the 92 drive geometry is an abstraction which is actually subject 93 to change. Currently (as of Nov 2004), the geometry values 94 are the "bios" values -- presumably the values the drive had 95 when Linux first booted. 96 97 In addition, the cylinders field of the hd_geometry is an 98 unsigned short, meaning that on most architectures, this 99 ioctl will not return a meaningful value on drives with more 100 than 65535 tracks. 101 102 The start field is unsigned long, meaning that it will not 103 contain a meaningful value for disks over 219 Gb in size. 104 105 106 107HDIO_GET_IDENTITY 108 get IDE identification info 109 110 111 usage:: 112 113 unsigned char identity[512]; 114 115 ioctl(fd, HDIO_GET_IDENTITY, identity); 116 117 inputs: 118 none 119 120 121 122 outputs: 123 ATA drive identity information. For full description, see 124 the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in 125 the ATA specification. 126 127 error returns: 128 - EINVAL Called on a partition instead of the whole disk device 129 - ENOMSG IDENTIFY DEVICE information not available 130 131 notes: 132 Returns information that was obtained when the drive was 133 probed. Some of this information is subject to change, and 134 this ioctl does not re-probe the drive to update the 135 information. 136 137 This information is also available from /proc/ide/hdX/identify 138 139 140 141HDIO_GET_32BIT 142 get current io_32bit setting 143 144 145 usage:: 146 147 long val; 148 149 ioctl(fd, HDIO_GET_32BIT, &val); 150 151 inputs: 152 none 153 154 155 156 outputs: 157 The value of the current io_32bit setting 158 159 160 161 notes: 162 0=16-bit, 1=32-bit, 2,3 = 32bit+sync 163 164 165 166HDIO_DRIVE_TASKFILE 167 execute raw taskfile 168 169 170 Note: 171 If you don't have a copy of the ANSI ATA specification 172 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 access 176 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 registers 199 hob_ports[8] high-order bytes, for extended commands. 200 out_flags flags indicating which registers are valid 201 in_flags flags indicating which registers should be returned 202 data_phase see below 203 req_cmd command type to be executed 204 out_size size of output buffer 205 outbuf buffer of data to be transmitted to disk 206 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 registers 213 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 returned 216 outbuf buffer of data to be transmitted to disk (see [1]) 217 inbuf buffer of data to be received from disk 218 =========== ==================================================== 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 task 224 - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8) 225 - EPERM 226 227 req_cmd == TASKFILE_MULTI_OUT and drive 228 multi-count not yet set. 229 - EIO Drive failed the command. 230 231 notes: 232 233 [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS 234 FULL OF GOTCHAS. Extreme caution should be used with using 235 this ioctl. A mistake can easily corrupt data or hang the 236 system. 237 238 [2] Both the input and output buffers are copied from the 239 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 is 242 zero, the following values are used for in_flags.all and 243 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 drive 247 * IDE_TASKFILE_STD_IN_FLAGS 248 if CHS/LBA28 249 250 The association between in_flags.all and each enable 251 bitfield flips depending on endianness; fortunately, TASKFILE 252 only uses inflags.b.data bit and ignores all other bits. 253 The end result is that, on any endian machines, it has no 254 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 drives 258 per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first 259 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 of 262 memory containing a ide_task_request_t structure, followed 263 by an optional buffer of data to be transmitted to the 264 drive, followed by an optional buffer to receive data from 265 the drive. 266 267 Command is passed to the disk drive via the ide_task_request_t 268 structure, which contains these fields: 269 270 ============ =============================================== 271 io_ports[8] values for the taskfile registers 272 hob_ports[8] high-order bytes, for extended commands 273 out_flags flags indicating which entries in the 274 io_ports[] and hob_ports[] arrays 275 contain valid values. Type ide_reg_valid_t. 276 in_flags flags indicating which entries in the 277 io_ports[] and hob_ports[] arrays 278 are expected to contain valid values 279 on return. 280 data_phase See below 281 req_cmd Command type, see below 282 out_size output (user->drive) buffer size, bytes 283 in_size input (drive->user) buffer size, bytes 284 ============ =============================================== 285 286 When out_flags is zero, the following registers are loaded. 287 288 ============ =============================================== 289 HOB_FEATURE If the drive supports LBA48 290 HOB_NSECTOR If the drive supports LBA48 291 HOB_SECTOR If the drive supports LBA48 292 HOB_LCYL If the drive supports LBA48 293 HOB_HCYL If the drive supports LBA48 294 FEATURE 295 NSECTOR 296 SECTOR 297 LCYL 298 HCYL 299 SELECT First, masked with 0xE0 if LBA48, 0xEF 300 otherwise; then, or'ed with the default 301 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 will 308 travel on DD8-DD15 on little endian machines 309 and on DD0-DD7 on big endian machines. 310 DATA If out_flags.b.data is set. DATA will 311 travel on DD0-DD7 on little endian machines 312 and on DD8-DD15 on big endian machines. 313 HOB_NSECTOR If out_flags.b.nsector_hob is set 314 HOB_SECTOR If out_flags.b.sector_hob is set 315 HOB_LCYL If out_flags.b.lcyl_hob is set 316 HOB_HCYL If out_flags.b.hcyl_hob is set 317 FEATURE If out_flags.b.feature is set 318 NSECTOR If out_flags.b.nsector is set 319 SECTOR If out_flags.b.sector is set 320 LCYL If out_flags.b.lcyl is set 321 HCYL If out_flags.b.hcyl is set 322 SELECT Or'ed with the default value of SELECT and 323 loaded regardless of out_flags.b.select. 324 ============ =============================================== 325 326 Taskfile registers are read back from the drive into 327 {io|hob}_ports[] after the command completes iff one of the 328 following conditions is met; otherwise, the original values 329 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 contain 337 DD8-DD15 on little endian machines and 338 DD0-DD7 on big endian machines. 339 DATA If in_flags.b.data is set. It will contain 340 DD0-DD7 on little endian machines and 341 DD8-DD15 on big endian machines. 342 HOB_FEATURE If the drive supports LBA48 343 HOB_NSECTOR If the drive supports LBA48 344 HOB_SECTOR If the drive supports LBA48 345 HOB_LCYL If the drive supports LBA48 346 HOB_HCYL If the drive supports LBA48 347 NSECTOR 348 SECTOR 349 LCYL 350 HCYL 351 ============ =============================================== 352 353 The data_phase field describes the data transfer to be 354 performed. Value is one of: 355 356 =================== ======================================== 357 TASKFILE_IN 358 TASKFILE_MULTI_IN 359 TASKFILE_OUT 360 TASKFILE_MULTI_OUT 361 TASKFILE_IN_OUT 362 TASKFILE_IN_DMA 363 TASKFILE_IN_DMAQ == IN_DMA (queueing not supported) 364 TASKFILE_OUT_DMA 365 TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported) 366 TASKFILE_P_IN unimplemented 367 TASKFILE_P_IN_DMA unimplemented 368 TASKFILE_P_IN_DMAQ unimplemented 369 TASKFILE_P_OUT unimplemented 370 TASKFILE_P_OUT_DMA unimplemented 371 TASKFILE_P_OUT_DMAQ unimplemented 372 =================== ======================================== 373 374 The req_cmd field classifies the command type. It may be 375 one of: 376 377 ======================== ======================================= 378 IDE_DRIVE_TASK_NO_DATA 379 IDE_DRIVE_TASK_SET_XFER unimplemented 380 IDE_DRIVE_TASK_IN 381 IDE_DRIVE_TASK_OUT unimplemented 382 IDE_DRIVE_TASK_RAW_WRITE 383 ======================== ======================================= 384 385 [6] Do not access {in|out}_flags->all except for resetting 386 all the bits. Always access individual bit fields. ->all 387 value will flip depending on endianness. For the same 388 reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS 389 constants defined in hdreg.h. 390 391 392 393HDIO_DRIVE_CMD 394 execute a special drive command 395 396 397 Note: If you don't have a copy of the ANSI ATA specification 398 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] COMMAND 412 args[1] NSECTOR 413 args[2] FEATURE 414 args[3] NSECTOR 415 ======= ======= 416 417 WIN_SMART: 418 419 ======= ======= 420 args[0] COMMAND 421 args[1] SECTOR 422 args[2] FEATURE 423 args[3] NSECTOR 424 ======= ======= 425 426 outputs: 427 args[] buffer is filled with register values followed by any 428 429 430 data returned by the disk. 431 432 ======== ==================================================== 433 args[0] status 434 args[1] error 435 args[2] NSECTOR 436 args[3] undefined 437 args[4+] NSECTOR * 512 bytes of data returned by the command. 438 ======== ==================================================== 439 440 error returns: 441 - EACCES Access denied: requires CAP_SYS_RAWIO 442 - ENOMEM Unable to allocate memory for task 443 - EIO Drive reports error 444 445 notes: 446 447 [1] For commands other than WIN_SMART, args[1] should equal 448 args[3]. SECTOR, LCYL and HCYL are undefined. For 449 WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL 450 respectively. In both cases SELECT will contain the default 451 value for the drive. Please refer to HDIO_DRIVE_TASKFILE 452 notes for the default value of SELECT. 453 454 [2] If NSECTOR value is greater than zero and the drive sets 455 DRQ when interrupting for the command, NSECTOR * 512 bytes 456 are read from the device into the area following NSECTOR. 457 In the above example, the area would be 458 args[4..4+XFER_SIZE]. 16bit PIO is used regardless of 459 HDIO_SET_32BIT setting. 460 461 [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER 462 && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA 463 mode, IDE driver will try to tune the transfer mode of the 464 drive accordingly. 465 466 467 468HDIO_DRIVE_TASK 469 execute task and special drive command 470 471 472 Note: If you don't have a copy of the ANSI ATA specification 473 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] COMMAND 487 args[1] FEATURE 488 args[2] NSECTOR 489 args[3] SECTOR 490 args[4] LCYL 491 args[5] HCYL 492 args[6] SELECT 493 ======= ======= 494 495 outputs: 496 Taskfile register values: 497 498 499 ======= ======= 500 args[0] status 501 args[1] error 502 args[2] NSECTOR 503 args[3] SECTOR 504 args[4] LCYL 505 args[5] HCYL 506 args[6] SELECT 507 ======= ======= 508 509 error returns: 510 - EACCES Access denied: requires CAP_SYS_RAWIO 511 - ENOMEM Unable to allocate memory for task 512 - 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 the 518 appropriate value for the drive is used. All other bits 519 are used unaltered. 520 521 522 523HDIO_SET_32BIT 524 change io_32bit flags 525 526 527 usage:: 528 529 int val; 530 531 ioctl(fd, HDIO_SET_32BIT, val); 532 533 inputs: 534 New value for io_32bit flag 535 536 537 538 outputs: 539 none 540 541 542 543 error return: 544 - EINVAL Called on a partition instead of the whole disk device 545 - EACCES Access denied: requires CAP_SYS_ADMIN 546 - EINVAL value out of range [0 3] 547 - EBUSY Controller busy 548