Documentation/userspace-api/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 5.11)
  11 drivers/ata/libata-scsi.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_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
  34 The information that follows was determined from reading kernel source
  35 code.  It is likely that some corrections will be made over time.
  36
  37 ------------------------------------------------------------------------------
  38
  39 General:
  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
  53 HDIO_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
 107 HDIO_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
 141 HDIO_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
 166 HDIO_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
 393 HDIO_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
 468 HDIO_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
 523 HDIO_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