linux/Documentation/userspace-api/ioctl/hdio.rst
<<
>>
Prefs
   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