Documentation/ioctl/hdio.rst

   1 ==============================
   2 Summary of `HDIO_` ioctl calls
   3 ==============================
   4
   5 - Edward A. Falk <efalk@google.com>
   6
   7 November, 2004
   8
   9 This document attempts to describe the ioctl(2) calls supported by
  10 the HD/IDE layer.  These are by-and-large implemented (as of Linux 2.6)
  11 in drivers/ide/ide.c and drivers/block/scsi_ioctl.c
  12
  13 ioctl values are listed in <linux/hdreg.h>.  As of this writing, they
  14 are as follows:
  15
  16     ioctls that pass argument pointers to user space:
  17
  18         ======================= =======================================
  19         HDIO_GETGEO             get device geometry
  20         HDIO_GET_UNMASKINTR     get current unmask setting
  21         HDIO_GET_MULTCOUNT      get current IDE blockmode setting
  22         HDIO_GET_QDMA           get use-qdma flag
  23         HDIO_SET_XFER           set transfer rate via proc
  24         HDIO_OBSOLETE_IDENTITY  OBSOLETE, DO NOT USE
  25         HDIO_GET_KEEPSETTINGS   get keep-settings-on-reset flag
  26         HDIO_GET_32BIT          get current io_32bit setting
  27         HDIO_GET_NOWERR         get ignore-write-error flag
  28         HDIO_GET_DMA            get use-dma flag
  29         HDIO_GET_NICE           get nice flags
  30         HDIO_GET_IDENTITY       get IDE identification info
  31         HDIO_GET_WCACHE         get write cache mode on|off
  32         HDIO_GET_ACOUSTIC       get acoustic value
  33         HDIO_GET_ADDRESS        get sector addressing mode
  34         HDIO_GET_BUSSTATE       get the bus state of the hwif
  35         HDIO_TRISTATE_HWIF      execute a channel tristate
  36         HDIO_DRIVE_RESET        execute a device reset
  37         HDIO_DRIVE_TASKFILE     execute raw taskfile
  38         HDIO_DRIVE_TASK         execute task and special drive command
  39         HDIO_DRIVE_CMD          execute a special drive command
  40         HDIO_DRIVE_CMD_AEB      HDIO_DRIVE_TASK
  41         ======================= =======================================
  42
  43     ioctls that pass non-pointer values:
  44
  45         ======================= =======================================
  46         HDIO_SET_MULTCOUNT      change IDE blockmode
  47         HDIO_SET_UNMASKINTR     permit other irqs during I/O
  48         HDIO_SET_KEEPSETTINGS   keep ioctl settings on reset
  49         HDIO_SET_32BIT          change io_32bit flags
  50         HDIO_SET_NOWERR         change ignore-write-error flag
  51         HDIO_SET_DMA            change use-dma flag
  52         HDIO_SET_PIO_MODE       reconfig interface to new speed
  53         HDIO_SCAN_HWIF          register and (re)scan interface
  54         HDIO_SET_NICE           set nice flags
  55         HDIO_UNREGISTER_HWIF    unregister interface
  56         HDIO_SET_WCACHE         change write cache enable-disable
  57         HDIO_SET_ACOUSTIC       change acoustic behavior
  58         HDIO_SET_BUSSTATE       set the bus state of the hwif
  59         HDIO_SET_QDMA           change use-qdma flag
  60         HDIO_SET_ADDRESS        change lba addressing modes
  61
  62         HDIO_SET_IDE_SCSI       Set scsi emulation mode on/off
  63         HDIO_SET_SCSI_IDE       not implemented yet
  64         ======================= =======================================
  65
  66
  67 The information that follows was determined from reading kernel source
  68 code.  It is likely that some corrections will be made over time.
  69
  70 ------------------------------------------------------------------------------
  71
  72 General:
  73
  74         Unless otherwise specified, all ioctl calls return 0 on success
  75         and -1 with errno set to an appropriate value on error.
  76
  77         Unless otherwise specified, all ioctl calls return -1 and set
  78         errno to EFAULT on a failed attempt to copy data to or from user
  79         address space.
  80
  81         Unless otherwise specified, all data structures and constants
  82         are defined in <linux/hdreg.h>
  83
  84 ------------------------------------------------------------------------------
  85
  86 HDIO_GETGEO
  87         get device geometry
  88
  89
  90         usage::
  91
  92           struct hd_geometry geom;
  93
  94           ioctl(fd, HDIO_GETGEO, &geom);
  95
  96
  97         inputs:
  98                 none
  99
 100
 101
 102         outputs:
 103                 hd_geometry structure containing:
 104
 105
 106             =========   ==================================
 107             heads       number of heads
 108             sectors     number of sectors/track
 109             cylinders   number of cylinders, mod 65536
 110             start       starting sector of this partition.
 111             =========   ==================================
 112
 113
 114         error returns:
 115           - EINVAL
 116
 117                         if the device is not a disk drive or floppy drive,
 118                         or if the user passes a null pointer
 119
 120
 121         notes:
 122                 Not particularly useful with modern disk drives, whose geometry
 123                 is a polite fiction anyway.  Modern drives are addressed
 124                 purely by sector number nowadays (lba addressing), and the
 125                 drive geometry is an abstraction which is actually subject
 126                 to change.  Currently (as of Nov 2004), the geometry values
 127                 are the "bios" values -- presumably the values the drive had
 128                 when Linux first booted.
 129
 130                 In addition, the cylinders field of the hd_geometry is an
 131                 unsigned short, meaning that on most architectures, this
 132                 ioctl will not return a meaningful value on drives with more
 133                 than 65535 tracks.
 134
 135                 The start field is unsigned long, meaning that it will not
 136                 contain a meaningful value for disks over 219 Gb in size.
 137
 138
 139
 140
 141 HDIO_GET_UNMASKINTR
 142         get current unmask setting
 143
 144
 145         usage::
 146
 147           long val;
 148
 149           ioctl(fd, HDIO_GET_UNMASKINTR, &val);
 150
 151         inputs:
 152                 none
 153
 154
 155
 156         outputs:
 157                 The value of the drive's current unmask setting
 158
 159
 160
 161
 162
 163 HDIO_SET_UNMASKINTR
 164         permit other irqs during I/O
 165
 166
 167         usage::
 168
 169           unsigned long val;
 170
 171           ioctl(fd, HDIO_SET_UNMASKINTR, val);
 172
 173         inputs:
 174                 New value for unmask flag
 175
 176
 177
 178         outputs:
 179                 none
 180
 181
 182
 183         error return:
 184           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
 185           - EACCES      Access denied:  requires CAP_SYS_ADMIN
 186           - EINVAL      value out of range [0 1]
 187           - EBUSY       Controller busy
 188
 189
 190
 191
 192 HDIO_GET_MULTCOUNT
 193         get current IDE blockmode setting
 194
 195
 196         usage::
 197
 198           long val;
 199
 200           ioctl(fd, HDIO_GET_MULTCOUNT, &val);
 201
 202         inputs:
 203                 none
 204
 205
 206
 207         outputs:
 208                 The value of the current IDE block mode setting.  This
 209                 controls how many sectors the drive will transfer per
 210                 interrupt.
 211
 212
 213
 214 HDIO_SET_MULTCOUNT
 215         change IDE blockmode
 216
 217
 218         usage::
 219
 220           int val;
 221
 222           ioctl(fd, HDIO_SET_MULTCOUNT, val);
 223
 224         inputs:
 225                 New value for IDE block mode setting.  This controls how many
 226                 sectors the drive will transfer per interrupt.
 227
 228         outputs:
 229                 none
 230
 231
 232
 233         error return:
 234           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
 235           - EACCES      Access denied:  requires CAP_SYS_ADMIN
 236           - EINVAL      value out of range supported by disk.
 237           - EBUSY       Controller busy or blockmode already set.
 238           - EIO         Drive did not accept new block mode.
 239
 240         notes:
 241           Source code comments read::
 242
 243             This is tightly woven into the driver->do_special cannot
 244             touch.  DON'T do it again until a total personality rewrite
 245             is committed.
 246
 247           If blockmode has already been set, this ioctl will fail with
 248           -EBUSY
 249
 250
 251
 252 HDIO_GET_QDMA
 253         get use-qdma flag
 254
 255
 256         Not implemented, as of 2.6.8.1
 257
 258
 259
 260 HDIO_SET_XFER
 261         set transfer rate via proc
 262
 263
 264         Not implemented, as of 2.6.8.1
 265
 266
 267
 268 HDIO_OBSOLETE_IDENTITY
 269         OBSOLETE, DO NOT USE
 270
 271
 272         Same as HDIO_GET_IDENTITY (see below), except that it only
 273         returns the first 142 bytes of drive identity information.
 274
 275
 276
 277 HDIO_GET_IDENTITY
 278         get IDE identification info
 279
 280
 281         usage::
 282
 283           unsigned char identity[512];
 284
 285           ioctl(fd, HDIO_GET_IDENTITY, identity);
 286
 287         inputs:
 288                 none
 289
 290
 291
 292         outputs:
 293                 ATA drive identity information.  For full description, see
 294                 the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
 295                 the ATA specification.
 296
 297         error returns:
 298           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
 299           - ENOMSG      IDENTIFY DEVICE information not available
 300
 301         notes:
 302                 Returns information that was obtained when the drive was
 303                 probed.  Some of this information is subject to change, and
 304                 this ioctl does not re-probe the drive to update the
 305                 information.
 306
 307                 This information is also available from /proc/ide/hdX/identify
 308
 309
 310
 311 HDIO_GET_KEEPSETTINGS
 312         get keep-settings-on-reset flag
 313
 314
 315         usage::
 316
 317           long val;
 318
 319           ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
 320
 321         inputs:
 322                 none
 323
 324
 325
 326         outputs:
 327                 The value of the current "keep settings" flag
 328
 329
 330
 331         notes:
 332                 When set, indicates that kernel should restore settings
 333                 after a drive reset.
 334
 335
 336
 337 HDIO_SET_KEEPSETTINGS
 338         keep ioctl settings on reset
 339
 340
 341         usage::
 342
 343           long val;
 344
 345           ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
 346
 347         inputs:
 348                 New value for keep_settings flag
 349
 350
 351
 352         outputs:
 353                 none
 354
 355
 356
 357         error return:
 358           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
 359           - EACCES      Access denied:  requires CAP_SYS_ADMIN
 360           - EINVAL      value out of range [0 1]
 361           - EBUSY               Controller busy
 362
 363
 364
 365 HDIO_GET_32BIT
 366         get current io_32bit setting
 367
 368
 369         usage::
 370
 371           long val;
 372
 373           ioctl(fd, HDIO_GET_32BIT, &val);
 374
 375         inputs:
 376                 none
 377
 378
 379
 380         outputs:
 381                 The value of the current io_32bit setting
 382
 383
 384
 385         notes:
 386                 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
 387
 388
 389
 390
 391
 392 HDIO_GET_NOWERR
 393         get ignore-write-error flag
 394
 395
 396         usage::
 397
 398           long val;
 399
 400           ioctl(fd, HDIO_GET_NOWERR, &val);
 401
 402         inputs:
 403                 none
 404
 405
 406
 407         outputs:
 408                 The value of the current ignore-write-error flag
 409
 410
 411
 412
 413
 414 HDIO_GET_DMA
 415         get use-dma flag
 416
 417
 418         usage::
 419
 420           long val;
 421
 422           ioctl(fd, HDIO_GET_DMA, &val);
 423
 424         inputs:
 425                 none
 426
 427
 428
 429         outputs:
 430                 The value of the current use-dma flag
 431
 432
 433
 434
 435
 436 HDIO_GET_NICE
 437         get nice flags
 438
 439
 440         usage::
 441
 442           long nice;
 443
 444           ioctl(fd, HDIO_GET_NICE, &nice);
 445
 446         inputs:
 447                 none
 448
 449
 450
 451         outputs:
 452                 The drive's "nice" values.
 453
 454
 455
 456         notes:
 457                 Per-drive flags which determine when the system will give more
 458                 bandwidth to other devices sharing the same IDE bus.
 459
 460                 See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
 461
 462
 463
 464
 465 HDIO_SET_NICE
 466         set nice flags
 467
 468
 469         usage::
 470
 471           unsigned long nice;
 472
 473           ...
 474           ioctl(fd, HDIO_SET_NICE, nice);
 475
 476         inputs:
 477                 bitmask of nice flags.
 478
 479
 480
 481         outputs:
 482                 none
 483
 484
 485
 486         error returns:
 487           - EACCES      Access denied:  requires CAP_SYS_ADMIN
 488           - EPERM       Flags other than DSC_OVERLAP and NICE_1 set.
 489           - EPERM       DSC_OVERLAP specified but not supported by drive
 490
 491         notes:
 492                 This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
 493                 provided by the user.
 494
 495                 Nice flags are listed in <linux/hdreg.h>, starting with
 496                 IDE_NICE_DSC_OVERLAP.  These values represent shifts.
 497
 498
 499
 500
 501
 502 HDIO_GET_WCACHE
 503         get write cache mode on|off
 504
 505
 506         usage::
 507
 508           long val;
 509
 510           ioctl(fd, HDIO_GET_WCACHE, &val);
 511
 512         inputs:
 513                 none
 514
 515
 516
 517         outputs:
 518                 The value of the current write cache mode
 519
 520
 521
 522
 523
 524 HDIO_GET_ACOUSTIC
 525         get acoustic value
 526
 527
 528         usage::
 529
 530           long val;
 531
 532           ioctl(fd, HDIO_GET_ACOUSTIC, &val);
 533
 534         inputs:
 535                 none
 536
 537
 538
 539         outputs:
 540                 The value of the current acoustic settings
 541
 542
 543
 544         notes:
 545                 See HDIO_SET_ACOUSTIC
 546
 547
 548
 549
 550
 551 HDIO_GET_ADDRESS
 552         usage::
 553
 554
 555           long val;
 556
 557           ioctl(fd, HDIO_GET_ADDRESS, &val);
 558
 559         inputs:
 560                 none
 561
 562
 563
 564         outputs:
 565                 The value of the current addressing mode:
 566
 567             =  ===================
 568             0  28-bit
 569             1  48-bit
 570             2  48-bit doing 28-bit
 571             3  64-bit
 572             =  ===================
 573
 574
 575
 576 HDIO_GET_BUSSTATE
 577         get the bus state of the hwif
 578
 579
 580         usage::
 581
 582           long state;
 583
 584           ioctl(fd, HDIO_SCAN_HWIF, &state);
 585
 586         inputs:
 587                 none
 588
 589
 590
 591         outputs:
 592                 Current power state of the IDE bus.  One of BUSSTATE_OFF,
 593                 BUSSTATE_ON, or BUSSTATE_TRISTATE
 594
 595         error returns:
 596           - EACCES      Access denied:  requires CAP_SYS_ADMIN
 597
 598
 599
 600
 601 HDIO_SET_BUSSTATE
 602         set the bus state of the hwif
 603
 604
 605         usage::
 606
 607           int state;
 608
 609           ...
 610           ioctl(fd, HDIO_SCAN_HWIF, state);
 611
 612         inputs:
 613                 Desired IDE power state.  One of BUSSTATE_OFF, BUSSTATE_ON,
 614                 or BUSSTATE_TRISTATE
 615
 616         outputs:
 617                 none
 618
 619
 620
 621         error returns:
 622           - EACCES      Access denied:  requires CAP_SYS_RAWIO
 623           - EOPNOTSUPP  Hardware interface does not support bus power control
 624
 625
 626
 627
 628 HDIO_TRISTATE_HWIF
 629         execute a channel tristate
 630
 631
 632         Not implemented, as of 2.6.8.1.  See HDIO_SET_BUSSTATE
 633
 634
 635
 636 HDIO_DRIVE_RESET
 637         execute a device reset
 638
 639
 640         usage::
 641
 642           int args[3]
 643
 644           ...
 645           ioctl(fd, HDIO_DRIVE_RESET, args);
 646
 647         inputs:
 648                 none
 649
 650
 651
 652         outputs:
 653                 none
 654
 655
 656
 657         error returns:
 658           - EACCES      Access denied:  requires CAP_SYS_ADMIN
 659           - ENXIO       No such device: phy dead or ctl_addr == 0
 660           - EIO         I/O error:      reset timed out or hardware error
 661
 662         notes:
 663
 664           - Execute a reset on the device as soon as the current IO
 665             operation has completed.
 666
 667           - Executes an ATAPI soft reset if applicable, otherwise
 668             executes an ATA soft reset on the controller.
 669
 670
 671
 672 HDIO_DRIVE_TASKFILE
 673         execute raw taskfile
 674
 675
 676         Note:
 677                 If you don't have a copy of the ANSI ATA specification
 678                 handy, you should probably ignore this ioctl.
 679
 680         - Execute an ATA disk command directly by writing the "taskfile"
 681           registers of the drive.  Requires ADMIN and RAWIO access
 682           privileges.
 683
 684         usage::
 685
 686           struct {
 687
 688             ide_task_request_t req_task;
 689             u8 outbuf[OUTPUT_SIZE];
 690             u8 inbuf[INPUT_SIZE];
 691           } task;
 692           memset(&task.req_task, 0, sizeof(task.req_task));
 693           task.req_task.out_size = sizeof(task.outbuf);
 694           task.req_task.in_size = sizeof(task.inbuf);
 695           ...
 696           ioctl(fd, HDIO_DRIVE_TASKFILE, &task);
 697           ...
 698
 699         inputs:
 700
 701           (See below for details on memory area passed to ioctl.)
 702
 703           ============  ===================================================
 704           io_ports[8]   values to be written to taskfile registers
 705           hob_ports[8]  high-order bytes, for extended commands.
 706           out_flags     flags indicating which registers are valid
 707           in_flags      flags indicating which registers should be returned
 708           data_phase    see below
 709           req_cmd       command type to be executed
 710           out_size      size of output buffer
 711           outbuf        buffer of data to be transmitted to disk
 712           inbuf         buffer of data to be received from disk (see [1])
 713           ============  ===================================================
 714
 715         outputs:
 716
 717           ===========   ====================================================
 718           io_ports[]    values returned in the taskfile registers
 719           hob_ports[]   high-order bytes, for extended commands.
 720           out_flags     flags indicating which registers are valid (see [2])
 721           in_flags      flags indicating which registers should be returned
 722           outbuf        buffer of data to be transmitted to disk (see [1])
 723           inbuf         buffer of data to be received from disk
 724           ===========   ====================================================
 725
 726         error returns:
 727           - EACCES      CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
 728           - ENOMSG      Device is not a disk drive.
 729           - ENOMEM      Unable to allocate memory for task
 730           - EFAULT      req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
 731           - EPERM
 732
 733                         req_cmd == TASKFILE_MULTI_OUT and drive
 734                         multi-count not yet set.
 735           - EIO         Drive failed the command.
 736
 737         notes:
 738
 739           [1] READ THE FOLLOWING NOTES *CAREFULLY*.  THIS IOCTL IS
 740           FULL OF GOTCHAS.  Extreme caution should be used with using
 741           this ioctl.  A mistake can easily corrupt data or hang the
 742           system.
 743
 744           [2] Both the input and output buffers are copied from the
 745           user and written back to the user, even when not used.
 746
 747           [3] If one or more bits are set in out_flags and in_flags is
 748           zero, the following values are used for in_flags.all and
 749           written back into in_flags on completion.
 750
 751            * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8)
 752              if LBA48 addressing is enabled for the drive
 753            * IDE_TASKFILE_STD_IN_FLAGS
 754              if CHS/LBA28
 755
 756           The association between in_flags.all and each enable
 757           bitfield flips depending on endianness; fortunately, TASKFILE
 758           only uses inflags.b.data bit and ignores all other bits.
 759           The end result is that, on any endian machines, it has no
 760           effect other than modifying in_flags on completion.
 761
 762           [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit)
 763           except for four drives per port chipsets.  For four drives
 764           per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first
 765           pair and (0x80|DEV_bit|LBA_bit) for the second pair.
 766
 767           [5] The argument to the ioctl is a pointer to a region of
 768           memory containing a ide_task_request_t structure, followed
 769           by an optional buffer of data to be transmitted to the
 770           drive, followed by an optional buffer to receive data from
 771           the drive.
 772
 773           Command is passed to the disk drive via the ide_task_request_t
 774           structure, which contains these fields:
 775
 776             ============        ===============================================
 777             io_ports[8]         values for the taskfile registers
 778             hob_ports[8]        high-order bytes, for extended commands
 779             out_flags           flags indicating which entries in the
 780                                 io_ports[] and hob_ports[] arrays
 781                                 contain valid values.  Type ide_reg_valid_t.
 782             in_flags            flags indicating which entries in the
 783                                 io_ports[] and hob_ports[] arrays
 784                                 are expected to contain valid values
 785                                 on return.
 786             data_phase          See below
 787             req_cmd             Command type, see below
 788             out_size            output (user->drive) buffer size, bytes
 789             in_size             input (drive->user) buffer size, bytes
 790             ============        ===============================================
 791
 792           When out_flags is zero, the following registers are loaded.
 793
 794             ============        ===============================================
 795             HOB_FEATURE         If the drive supports LBA48
 796             HOB_NSECTOR         If the drive supports LBA48
 797             HOB_SECTOR          If the drive supports LBA48
 798             HOB_LCYL            If the drive supports LBA48
 799             HOB_HCYL            If the drive supports LBA48
 800             FEATURE
 801             NSECTOR
 802             SECTOR
 803             LCYL
 804             HCYL
 805             SELECT              First, masked with 0xE0 if LBA48, 0xEF
 806                                 otherwise; then, or'ed with the default
 807                                 value of SELECT.
 808             ============        ===============================================
 809
 810           If any bit in out_flags is set, the following registers are loaded.
 811
 812             ============        ===============================================
 813             HOB_DATA            If out_flags.b.data is set.  HOB_DATA will
 814                                 travel on DD8-DD15 on little endian machines
 815                                 and on DD0-DD7 on big endian machines.
 816             DATA                If out_flags.b.data is set.  DATA will
 817                                 travel on DD0-DD7 on little endian machines
 818                                 and on DD8-DD15 on big endian machines.
 819             HOB_NSECTOR         If out_flags.b.nsector_hob is set
 820             HOB_SECTOR          If out_flags.b.sector_hob is set
 821             HOB_LCYL            If out_flags.b.lcyl_hob is set
 822             HOB_HCYL            If out_flags.b.hcyl_hob is set
 823             FEATURE             If out_flags.b.feature is set
 824             NSECTOR             If out_flags.b.nsector is set
 825             SECTOR              If out_flags.b.sector is set
 826             LCYL                If out_flags.b.lcyl is set
 827             HCYL                If out_flags.b.hcyl is set
 828             SELECT              Or'ed with the default value of SELECT and
 829                                 loaded regardless of out_flags.b.select.
 830             ============        ===============================================
 831
 832           Taskfile registers are read back from the drive into
 833           {io|hob}_ports[] after the command completes iff one of the
 834           following conditions is met; otherwise, the original values
 835           will be written back, unchanged.
 836
 837             1. The drive fails the command (EIO).
 838             2. One or more than one bits are set in out_flags.
 839             3. The requested data_phase is TASKFILE_NO_DATA.
 840
 841             ============        ===============================================
 842             HOB_DATA            If in_flags.b.data is set.  It will contain
 843                                 DD8-DD15 on little endian machines and
 844                                 DD0-DD7 on big endian machines.
 845             DATA                If in_flags.b.data is set.  It will contain
 846                                 DD0-DD7 on little endian machines and
 847                                 DD8-DD15 on big endian machines.
 848             HOB_FEATURE         If the drive supports LBA48
 849             HOB_NSECTOR         If the drive supports LBA48
 850             HOB_SECTOR          If the drive supports LBA48
 851             HOB_LCYL            If the drive supports LBA48
 852             HOB_HCYL            If the drive supports LBA48
 853             NSECTOR
 854             SECTOR
 855             LCYL
 856             HCYL
 857             ============        ===============================================
 858
 859           The data_phase field describes the data transfer to be
 860           performed.  Value is one of:
 861
 862             ===================        ========================================
 863             TASKFILE_IN
 864             TASKFILE_MULTI_IN
 865             TASKFILE_OUT
 866             TASKFILE_MULTI_OUT
 867             TASKFILE_IN_OUT
 868             TASKFILE_IN_DMA
 869             TASKFILE_IN_DMAQ            == IN_DMA (queueing not supported)
 870             TASKFILE_OUT_DMA
 871             TASKFILE_OUT_DMAQ           == OUT_DMA (queueing not supported)
 872             TASKFILE_P_IN               unimplemented
 873             TASKFILE_P_IN_DMA           unimplemented
 874             TASKFILE_P_IN_DMAQ          unimplemented
 875             TASKFILE_P_OUT              unimplemented
 876             TASKFILE_P_OUT_DMA          unimplemented
 877             TASKFILE_P_OUT_DMAQ         unimplemented
 878             ===================        ========================================
 879
 880           The req_cmd field classifies the command type.  It may be
 881           one of:
 882
 883             ========================    =======================================
 884             IDE_DRIVE_TASK_NO_DATA
 885             IDE_DRIVE_TASK_SET_XFER     unimplemented
 886             IDE_DRIVE_TASK_IN
 887             IDE_DRIVE_TASK_OUT          unimplemented
 888             IDE_DRIVE_TASK_RAW_WRITE
 889             ========================    =======================================
 890
 891           [6] Do not access {in|out}_flags->all except for resetting
 892           all the bits.  Always access individual bit fields.  ->all
 893           value will flip depending on endianness.  For the same
 894           reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS
 895           constants defined in hdreg.h.
 896
 897
 898
 899 HDIO_DRIVE_CMD
 900         execute a special drive command
 901
 902
 903         Note:  If you don't have a copy of the ANSI ATA specification
 904         handy, you should probably ignore this ioctl.
 905
 906         usage::
 907
 908           u8 args[4+XFER_SIZE];
 909
 910           ...
 911           ioctl(fd, HDIO_DRIVE_CMD, args);
 912
 913         inputs:
 914             Commands other than WIN_SMART:
 915
 916             =======     =======
 917             args[0]     COMMAND
 918             args[1]     NSECTOR
 919             args[2]     FEATURE
 920             args[3]     NSECTOR
 921             =======     =======
 922
 923             WIN_SMART:
 924
 925             =======     =======
 926             args[0]     COMMAND
 927             args[1]     SECTOR
 928             args[2]     FEATURE
 929             args[3]     NSECTOR
 930             =======     =======
 931
 932         outputs:
 933                 args[] buffer is filled with register values followed by any
 934
 935
 936           data returned by the disk.
 937
 938             ========    ====================================================
 939             args[0]     status
 940             args[1]     error
 941             args[2]     NSECTOR
 942             args[3]     undefined
 943             args[4+]    NSECTOR * 512 bytes of data returned by the command.
 944             ========    ====================================================
 945
 946         error returns:
 947           - EACCES      Access denied:  requires CAP_SYS_RAWIO
 948           - ENOMEM      Unable to allocate memory for task
 949           - EIO         Drive reports error
 950
 951         notes:
 952
 953           [1] For commands other than WIN_SMART, args[1] should equal
 954           args[3].  SECTOR, LCYL and HCYL are undefined.  For
 955           WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL
 956           respectively.  In both cases SELECT will contain the default
 957           value for the drive.  Please refer to HDIO_DRIVE_TASKFILE
 958           notes for the default value of SELECT.
 959
 960           [2] If NSECTOR value is greater than zero and the drive sets
 961           DRQ when interrupting for the command, NSECTOR * 512 bytes
 962           are read from the device into the area following NSECTOR.
 963           In the above example, the area would be
 964           args[4..4+XFER_SIZE].  16bit PIO is used regardless of
 965           HDIO_SET_32BIT setting.
 966
 967           [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER
 968           && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA
 969           mode, IDE driver will try to tune the transfer mode of the
 970           drive accordingly.
 971
 972
 973
 974 HDIO_DRIVE_TASK
 975         execute task and special drive command
 976
 977
 978         Note:  If you don't have a copy of the ANSI ATA specification
 979         handy, you should probably ignore this ioctl.
 980
 981         usage::
 982
 983           u8 args[7];
 984
 985           ...
 986           ioctl(fd, HDIO_DRIVE_TASK, args);
 987
 988         inputs:
 989             Taskfile register values:
 990
 991             =======     =======
 992             args[0]     COMMAND
 993             args[1]     FEATURE
 994             args[2]     NSECTOR
 995             args[3]     SECTOR
 996             args[4]     LCYL
 997             args[5]     HCYL
 998             args[6]     SELECT
 999             =======     =======
1000
1001         outputs:
1002             Taskfile register values:
1003
1004
1005             =======     =======
1006             args[0]     status
1007             args[1]     error
1008             args[2]     NSECTOR
1009             args[3]     SECTOR
1010             args[4]     LCYL
1011             args[5]     HCYL
1012             args[6]     SELECT
1013             =======     =======
1014
1015         error returns:
1016           - EACCES      Access denied:  requires CAP_SYS_RAWIO
1017           - ENOMEM      Unable to allocate memory for task
1018           - ENOMSG      Device is not a disk drive.
1019           - EIO         Drive failed the command.
1020
1021         notes:
1022
1023           [1] DEV bit (0x10) of SELECT register is ignored and the
1024           appropriate value for the drive is used.  All other bits
1025           are used unaltered.
1026
1027
1028
1029 HDIO_DRIVE_CMD_AEB
1030         HDIO_DRIVE_TASK
1031
1032
1033         Not implemented, as of 2.6.8.1
1034
1035
1036
1037 HDIO_SET_32BIT
1038         change io_32bit flags
1039
1040
1041         usage::
1042
1043           int val;
1044
1045           ioctl(fd, HDIO_SET_32BIT, val);
1046
1047         inputs:
1048                 New value for io_32bit flag
1049
1050
1051
1052         outputs:
1053                 none
1054
1055
1056
1057         error return:
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 3]
1061           - EBUSY       Controller busy
1062
1063
1064
1065
1066 HDIO_SET_NOWERR
1067         change ignore-write-error flag
1068
1069
1070         usage::
1071
1072           int val;
1073
1074           ioctl(fd, HDIO_SET_NOWERR, val);
1075
1076         inputs:
1077                 New value for ignore-write-error flag.  Used for ignoring
1078
1079
1080           WRERR_STAT
1081
1082         outputs:
1083                 none
1084
1085
1086
1087         error return:
1088           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
1089           - EACCES      Access denied:  requires CAP_SYS_ADMIN
1090           - EINVAL      value out of range [0 1]
1091           - EBUSY               Controller busy
1092
1093
1094
1095 HDIO_SET_DMA
1096         change use-dma flag
1097
1098
1099         usage::
1100
1101           long val;
1102
1103           ioctl(fd, HDIO_SET_DMA, val);
1104
1105         inputs:
1106                 New value for use-dma flag
1107
1108
1109
1110         outputs:
1111                 none
1112
1113
1114
1115         error return:
1116           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
1117           - EACCES      Access denied:  requires CAP_SYS_ADMIN
1118           - EINVAL      value out of range [0 1]
1119           - EBUSY       Controller busy
1120
1121
1122
1123 HDIO_SET_PIO_MODE
1124         reconfig interface to new speed
1125
1126
1127         usage::
1128
1129           long val;
1130
1131           ioctl(fd, HDIO_SET_PIO_MODE, val);
1132
1133         inputs:
1134                 New interface speed.
1135
1136
1137
1138         outputs:
1139                 none
1140
1141
1142
1143         error return:
1144           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
1145           - EACCES      Access denied:  requires CAP_SYS_ADMIN
1146           - EINVAL      value out of range [0 255]
1147           - EBUSY       Controller busy
1148
1149
1150
1151 HDIO_SCAN_HWIF
1152         register and (re)scan interface
1153
1154
1155         usage::
1156
1157           int args[3]
1158
1159           ...
1160           ioctl(fd, HDIO_SCAN_HWIF, args);
1161
1162         inputs:
1163
1164           =======       =========================
1165           args[0]       io address to probe
1166
1167
1168           args[1]       control address to probe
1169           args[2]       irq number
1170           =======       =========================
1171
1172         outputs:
1173                 none
1174
1175
1176
1177         error returns:
1178           - EACCES      Access denied:  requires CAP_SYS_RAWIO
1179           - EIO         Probe failed.
1180
1181         notes:
1182                 This ioctl initializes the addresses and irq for a disk
1183                 controller, probes for drives, and creates /proc/ide
1184                 interfaces as appropriate.
1185
1186
1187
1188 HDIO_UNREGISTER_HWIF
1189         unregister interface
1190
1191
1192         usage::
1193
1194           int index;
1195
1196           ioctl(fd, HDIO_UNREGISTER_HWIF, index);
1197
1198         inputs:
1199                 index           index of hardware interface to unregister
1200
1201
1202
1203         outputs:
1204                 none
1205
1206
1207
1208         error returns:
1209           - EACCES      Access denied:  requires CAP_SYS_RAWIO
1210
1211         notes:
1212                 This ioctl removes a hardware interface from the kernel.
1213
1214                 Currently (2.6.8) this ioctl silently fails if any drive on
1215                 the interface is busy.
1216
1217
1218
1219 HDIO_SET_WCACHE
1220         change write cache enable-disable
1221
1222
1223         usage::
1224
1225           int val;
1226
1227           ioctl(fd, HDIO_SET_WCACHE, val);
1228
1229         inputs:
1230                 New value for write cache enable
1231
1232
1233
1234         outputs:
1235                 none
1236
1237
1238
1239         error return:
1240           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
1241           - EACCES      Access denied:  requires CAP_SYS_ADMIN
1242           - EINVAL      value out of range [0 1]
1243           - EBUSY       Controller busy
1244
1245
1246
1247 HDIO_SET_ACOUSTIC
1248         change acoustic behavior
1249
1250
1251         usage::
1252
1253           int val;
1254
1255           ioctl(fd, HDIO_SET_ACOUSTIC, val);
1256
1257         inputs:
1258                 New value for drive acoustic settings
1259
1260
1261
1262         outputs:
1263                 none
1264
1265
1266
1267         error return:
1268           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
1269           - EACCES      Access denied:  requires CAP_SYS_ADMIN
1270           - EINVAL      value out of range [0 254]
1271           - EBUSY       Controller busy
1272
1273
1274
1275 HDIO_SET_QDMA
1276         change use-qdma flag
1277
1278
1279         Not implemented, as of 2.6.8.1
1280
1281
1282
1283 HDIO_SET_ADDRESS
1284         change lba addressing modes
1285
1286
1287         usage::
1288
1289           int val;
1290
1291           ioctl(fd, HDIO_SET_ADDRESS, val);
1292
1293         inputs:
1294                 New value for addressing mode
1295
1296             =   ===================
1297             0   28-bit
1298             1   48-bit
1299             2   48-bit doing 28-bit
1300             =   ===================
1301
1302         outputs:
1303                 none
1304
1305
1306
1307         error return:
1308           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
1309           - EACCES      Access denied:  requires CAP_SYS_ADMIN
1310           - EINVAL      value out of range [0 2]
1311           - EBUSY               Controller busy
1312           - EIO         Drive does not support lba48 mode.
1313
1314
1315 HDIO_SET_IDE_SCSI
1316         usage::
1317
1318
1319           long val;
1320
1321           ioctl(fd, HDIO_SET_IDE_SCSI, val);
1322
1323         inputs:
1324                 New value for scsi emulation mode (?)
1325
1326
1327
1328         outputs:
1329                 none
1330
1331
1332
1333         error return:
1334           - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
1335           - EACCES      Access denied:  requires CAP_SYS_ADMIN
1336           - EINVAL      value out of range [0 1]
1337           - EBUSY       Controller busy
1338
1339
1340
1341 HDIO_SET_SCSI_IDE
1342         Not implemented, as of 2.6.8.1