docs: ioctl: convert to ReST

Rename the iio documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

The cdrom.txt and hdio.txt have their own particular syntax.
In order to speedup the conversion, I used a small ancillary
perl script:

	my $d;
	$d .= $_ while(<>);
	$d =~ s/(\nCDROM\S+)\s+(\w[^\n]*)/$1\n\t$2\n/g;
	$d =~ s/(\nHDIO\S+)\s+(\w[^\n]*)/$1\n\t$2\n/g;
	$d =~ s/(\n\s*usage:)[\s\n]*(\w[^\n]*)/$1:\n\n\t  $2\n/g;
	$d =~ s/(\n\s*)(E\w+[\s\n]*\w[^\n]*)/$1- $2/g;
	$d =~ s/(\n\s*)(inputs|outputs|notes):\s*(\w[^\n]*)/$1$2:\n\t\t$3\n/g;
	print $d;

It basically add blank lines on a few interesting places. The
script is not perfect: still several things require manual work,
but it saved quite some time doing some obvious stuff.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.rst
similarity index 99%
rename from Documentation/ioctl/botching-up-ioctls.txt
rename to Documentation/ioctl/botching-up-ioctls.rst
index 883fb034bd04af77a99a569f9dc3b85b7e7a982a..ac697fef35457375190c66ff88ae213dd624d5f7 100644 (file)
--- a/Documentation/ioctl/botching-up-ioctls.txt
+++ b/Documentation/ioctl/botching-up-ioctls.rst
@@ -1,3 +1,4 @@
+=================================

 (How to avoid) Botching up ioctls
 =================================
 
 (How to avoid) Botching up ioctls
 =================================
 

diff --git a/Documentation/ioctl/cdrom.rst b/Documentation/ioctl/cdrom.rst
new file mode 100644 (file)
index 0000000..3b4c050
--- /dev/null
+++ b/Documentation/ioctl/cdrom.rst
@@ -0,0 +1,1233 @@
+============================
+Summary of CDROM ioctl calls
+============================
+
+- Edward A. Falk <efalk@google.com>
+
+November, 2004
+
+This document attempts to describe the ioctl(2) calls supported by
+the CDROM layer.  These are by-and-large implemented (as of Linux 2.6)
+in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c
+
+ioctl values are listed in <linux/cdrom.h>.  As of this writing, they
+are as follows:
+
+       ======================  ===============================================
+       CDROMPAUSE              Pause Audio Operation
+       CDROMRESUME             Resume paused Audio Operation
+       CDROMPLAYMSF            Play Audio MSF (struct cdrom_msf)
+       CDROMPLAYTRKIND         Play Audio Track/index (struct cdrom_ti)
+       CDROMREADTOCHDR         Read TOC header (struct cdrom_tochdr)
+       CDROMREADTOCENTRY       Read TOC entry (struct cdrom_tocentry)
+       CDROMSTOP               Stop the cdrom drive
+       CDROMSTART              Start the cdrom drive
+       CDROMEJECT              Ejects the cdrom media
+       CDROMVOLCTRL            Control output volume (struct cdrom_volctrl)
+       CDROMSUBCHNL            Read subchannel data (struct cdrom_subchnl)
+       CDROMREADMODE2          Read CDROM mode 2 data (2336 Bytes)
+                               (struct cdrom_read)
+       CDROMREADMODE1          Read CDROM mode 1 data (2048 Bytes)
+                               (struct cdrom_read)
+       CDROMREADAUDIO          (struct cdrom_read_audio)
+       CDROMEJECT_SW           enable(1)/disable(0) auto-ejecting
+       CDROMMULTISESSION       Obtain the start-of-last-session
+                               address of multi session disks
+                               (struct cdrom_multisession)
+       CDROM_GET_MCN           Obtain the "Universal Product Code"
+                               if available (struct cdrom_mcn)
+       CDROM_GET_UPC           Deprecated, use CDROM_GET_MCN instead.
+       CDROMRESET              hard-reset the drive
+       CDROMVOLREAD            Get the drive's volume setting
+                               (struct cdrom_volctrl)
+       CDROMREADRAW            read data in raw mode (2352 Bytes)
+                               (struct cdrom_read)
+       CDROMREADCOOKED         read data in cooked mode
+       CDROMSEEK               seek msf address
+       CDROMPLAYBLK            scsi-cd only, (struct cdrom_blk)
+       CDROMREADALL            read all 2646 bytes
+       CDROMGETSPINDOWN        return 4-bit spindown value
+       CDROMSETSPINDOWN        set 4-bit spindown value
+       CDROMCLOSETRAY          pendant of CDROMEJECT
+       CDROM_SET_OPTIONS       Set behavior options
+       CDROM_CLEAR_OPTIONS     Clear behavior options
+       CDROM_SELECT_SPEED      Set the CD-ROM speed
+       CDROM_SELECT_DISC       Select disc (for juke-boxes)
+       CDROM_MEDIA_CHANGED     Check is media changed
+       CDROM_DRIVE_STATUS      Get tray position, etc.
+       CDROM_DISC_STATUS       Get disc type, etc.
+       CDROM_CHANGER_NSLOTS    Get number of slots
+       CDROM_LOCKDOOR          lock or unlock door
+       CDROM_DEBUG             Turn debug messages on/off
+       CDROM_GET_CAPABILITY    get capabilities
+       CDROMAUDIOBUFSIZ        set the audio buffer size
+       DVD_READ_STRUCT         Read structure
+       DVD_WRITE_STRUCT        Write structure
+       DVD_AUTH                Authentication
+       CDROM_SEND_PACKET       send a packet to the drive
+       CDROM_NEXT_WRITABLE     get next writable block
+       CDROM_LAST_WRITTEN      get last block written on disc
+       ======================  ===============================================
+
+
+The information that follows was determined from reading kernel source
+code.  It is likely that some corrections will be made over time.
+
+------------------------------------------------------------------------------
+
+General:
+
+       Unless otherwise specified, all ioctl calls return 0 on success
+       and -1 with errno set to an appropriate value on error.  (Some
+       ioctls return non-negative data values.)
+
+       Unless otherwise specified, all ioctl calls return -1 and set
+       errno to EFAULT on a failed attempt to copy data to or from user
+       address space.
+
+       Individual drivers may return error codes not listed here.
+
+       Unless otherwise specified, all data structures and constants
+       are defined in <linux/cdrom.h>
+
+------------------------------------------------------------------------------
+
+
+CDROMPAUSE
+       Pause Audio Operation
+
+
+       usage::
+
+         ioctl(fd, CDROMPAUSE, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+
+CDROMRESUME
+       Resume paused Audio Operation
+
+
+       usage::
+
+         ioctl(fd, CDROMRESUME, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+
+CDROMPLAYMSF
+       Play Audio MSF
+
+       (struct cdrom_msf)
+
+
+       usage::
+
+         struct cdrom_msf msf;
+
+         ioctl(fd, CDROMPLAYMSF, &msf);
+
+       inputs:
+               cdrom_msf structure, describing a segment of music to play
+
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+       notes:
+               - MSF stands for minutes-seconds-frames
+               - LBA stands for logical block address
+               - Segment is described as start and end times, where each time
+                 is described as minutes:seconds:frames.
+                 A frame is 1/75 of a second.
+
+
+CDROMPLAYTRKIND
+       Play Audio Track/index
+
+       (struct cdrom_ti)
+
+
+       usage::
+
+         struct cdrom_ti ti;
+
+         ioctl(fd, CDROMPLAYTRKIND, &ti);
+
+       inputs:
+               cdrom_ti structure, describing a segment of music to play
+
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+       notes:
+               - Segment is described as start and end times, where each time
+                 is described as a track and an index.
+
+
+
+CDROMREADTOCHDR
+       Read TOC header
+
+       (struct cdrom_tochdr)
+
+
+       usage::
+
+         cdrom_tochdr header;
+
+         ioctl(fd, CDROMREADTOCHDR, &header);
+
+       inputs:
+               cdrom_tochdr structure
+
+
+       outputs:
+               cdrom_tochdr structure
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+
+
+CDROMREADTOCENTRY
+       Read TOC entry
+
+       (struct cdrom_tocentry)
+
+
+       usage::
+
+         struct cdrom_tocentry entry;
+
+         ioctl(fd, CDROMREADTOCENTRY, &entry);
+
+       inputs:
+               cdrom_tocentry structure
+
+
+       outputs:
+               cdrom_tocentry structure
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+         - EINVAL      entry.cdte_format not CDROM_MSF or CDROM_LBA
+         - EINVAL      requested track out of bounds
+         - EIO         I/O error reading TOC
+
+       notes:
+               - TOC stands for Table Of Contents
+               - MSF stands for minutes-seconds-frames
+               - LBA stands for logical block address
+
+
+
+CDROMSTOP
+       Stop the cdrom drive
+
+
+       usage::
+
+         ioctl(fd, CDROMSTOP, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+       notes:
+         - Exact interpretation of this ioctl depends on the device,
+           but most seem to spin the drive down.
+
+
+CDROMSTART
+       Start the cdrom drive
+
+
+       usage::
+
+         ioctl(fd, CDROMSTART, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+       notes:
+         - Exact interpretation of this ioctl depends on the device,
+           but most seem to spin the drive up and/or close the tray.
+           Other devices ignore the ioctl completely.
+
+
+CDROMEJECT
+       - Ejects the cdrom media
+
+
+       usage::
+
+         ioctl(fd, CDROMEJECT, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               none
+
+
+       error returns:
+         - ENOSYS      cd drive not capable of ejecting
+         - EBUSY       other processes are accessing drive, or door is locked
+
+       notes:
+               - See CDROM_LOCKDOOR, below.
+
+
+
+
+CDROMCLOSETRAY
+       pendant of CDROMEJECT
+
+
+       usage::
+
+         ioctl(fd, CDROMCLOSETRAY, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               none
+
+
+       error returns:
+         - ENOSYS      cd drive not capable of closing the tray
+         - EBUSY       other processes are accessing drive, or door is locked
+
+       notes:
+               - See CDROM_LOCKDOOR, below.
+
+
+
+
+CDROMVOLCTRL
+       Control output volume (struct cdrom_volctrl)
+
+
+       usage::
+
+         struct cdrom_volctrl volume;
+
+         ioctl(fd, CDROMVOLCTRL, &volume);
+
+       inputs:
+               cdrom_volctrl structure containing volumes for up to 4
+               channels.
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+
+
+CDROMVOLREAD
+       Get the drive's volume setting
+
+       (struct cdrom_volctrl)
+
+
+       usage::
+
+         struct cdrom_volctrl volume;
+
+         ioctl(fd, CDROMVOLREAD, &volume);
+
+       inputs:
+               none
+
+
+       outputs:
+               The current volume settings.
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+
+
+
+CDROMSUBCHNL
+       Read subchannel data
+
+       (struct cdrom_subchnl)
+
+
+       usage::
+
+         struct cdrom_subchnl q;
+
+         ioctl(fd, CDROMSUBCHNL, &q);
+
+       inputs:
+               cdrom_subchnl structure
+
+
+       outputs:
+               cdrom_subchnl structure
+
+
+       error return:
+         - ENOSYS      cd drive not audio-capable.
+         - EINVAL      format not CDROM_MSF or CDROM_LBA
+
+       notes:
+               - Format is converted to CDROM_MSF or CDROM_LBA
+                 as per user request on return
+
+
+
+CDROMREADRAW
+       read data in raw mode (2352 Bytes)
+
+       (struct cdrom_read)
+
+       usage::
+
+         union {
+
+           struct cdrom_msf msf;               /* input */
+           char buffer[CD_FRAMESIZE_RAW];      /* return */
+         } arg;
+         ioctl(fd, CDROMREADRAW, &arg);
+
+       inputs:
+               cdrom_msf structure indicating an address to read.
+
+               Only the start values are significant.
+
+       outputs:
+               Data written to address provided by user.
+
+
+       error return:
+         - EINVAL      address less than 0, or msf less than 0:2:0
+         - ENOMEM      out of memory
+
+       notes:
+               - As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this
+                 ioctl accepts a cdrom_read structure, but actual source code
+                 reads a cdrom_msf structure and writes a buffer of data to
+                 the same address.
+
+               - MSF values are converted to LBA values via this formula::
+
+                   lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;
+
+
+
+
+CDROMREADMODE1
+       Read CDROM mode 1 data (2048 Bytes)
+
+       (struct cdrom_read)
+
+       notes:
+               Identical to CDROMREADRAW except that block size is
+               CD_FRAMESIZE (2048) bytes
+
+
+
+CDROMREADMODE2
+       Read CDROM mode 2 data (2336 Bytes)
+
+       (struct cdrom_read)
+
+       notes:
+               Identical to CDROMREADRAW except that block size is
+               CD_FRAMESIZE_RAW0 (2336) bytes
+
+
+
+CDROMREADAUDIO
+       (struct cdrom_read_audio)
+
+       usage::
+
+         struct cdrom_read_audio ra;
+
+         ioctl(fd, CDROMREADAUDIO, &ra);
+
+       inputs:
+               cdrom_read_audio structure containing read start
+               point and length
+
+       outputs:
+               audio data, returned to buffer indicated by ra
+
+
+       error return:
+         - EINVAL      format not CDROM_MSF or CDROM_LBA
+         - EINVAL      nframes not in range [1 75]
+         - ENXIO       drive has no queue (probably means invalid fd)
+         - ENOMEM      out of memory
+
+
+CDROMEJECT_SW
+       enable(1)/disable(0) auto-ejecting
+
+
+       usage::
+
+         int val;
+
+         ioctl(fd, CDROMEJECT_SW, val);
+
+       inputs:
+               Flag specifying auto-eject flag.
+
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      Drive is not capable of ejecting.
+         - EBUSY       Door is locked
+
+
+
+
+CDROMMULTISESSION
+       Obtain the start-of-last-session address of multi session disks
+
+       (struct cdrom_multisession)
+
+       usage::
+
+         struct cdrom_multisession ms_info;
+
+         ioctl(fd, CDROMMULTISESSION, &ms_info);
+
+       inputs:
+               cdrom_multisession structure containing desired
+
+         format.
+
+       outputs:
+               cdrom_multisession structure is filled with last_session
+               information.
+
+       error return:
+         - EINVAL      format not CDROM_MSF or CDROM_LBA
+
+
+CDROM_GET_MCN
+       Obtain the "Universal Product Code"
+       if available
+
+       (struct cdrom_mcn)
+
+
+       usage::
+
+         struct cdrom_mcn mcn;
+
+         ioctl(fd, CDROM_GET_MCN, &mcn);
+
+       inputs:
+               none
+
+
+       outputs:
+               Universal Product Code
+
+
+       error return:
+         - ENOSYS      Drive is not capable of reading MCN data.
+
+       notes:
+               - Source code comments state::
+
+                   The following function is implemented, although very few
+                   audio discs give Universal Product Code information, which
+                   should just be the Medium Catalog Number on the box.  Note,
+                   that the way the code is written on the CD is /not/ uniform
+                   across all discs!
+
+
+
+
+CDROM_GET_UPC
+       CDROM_GET_MCN  (deprecated)
+
+
+       Not implemented, as of 2.6.8.1
+
+
+
+CDROMRESET
+       hard-reset the drive
+
+
+       usage::
+
+         ioctl(fd, CDROMRESET, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               none
+
+
+       error return:
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - ENOSYS      Drive is not capable of resetting.
+
+
+
+
+CDROMREADCOOKED
+       read data in cooked mode
+
+
+       usage::
+
+         u8 buffer[CD_FRAMESIZE]
+
+         ioctl(fd, CDROMREADCOOKED, buffer);
+
+       inputs:
+               none
+
+
+       outputs:
+               2048 bytes of data, "cooked" mode.
+
+
+       notes:
+               Not implemented on all drives.
+
+
+
+
+
+CDROMREADALL
+       read all 2646 bytes
+
+
+       Same as CDROMREADCOOKED, but reads 2646 bytes.
+
+
+
+CDROMSEEK
+       seek msf address
+
+
+       usage::
+
+         struct cdrom_msf msf;
+
+         ioctl(fd, CDROMSEEK, &msf);
+
+       inputs:
+               MSF address to seek to.
+
+
+       outputs:
+               none
+
+
+
+
+CDROMPLAYBLK
+       scsi-cd only
+
+       (struct cdrom_blk)
+
+
+       usage::
+
+         struct cdrom_blk blk;
+
+         ioctl(fd, CDROMPLAYBLK, &blk);
+
+       inputs:
+               Region to play
+
+
+       outputs:
+               none
+
+
+
+
+CDROMGETSPINDOWN
+       usage::
+
+         char spindown;
+
+         ioctl(fd, CDROMGETSPINDOWN, &spindown);
+
+       inputs:
+               none
+
+
+       outputs:
+               The value of the current 4-bit spindown value.
+
+
+
+
+
+CDROMSETSPINDOWN
+       usage::
+
+         char spindown
+
+         ioctl(fd, CDROMSETSPINDOWN, &spindown);
+
+       inputs:
+               4-bit value used to control spindown (TODO: more detail here)
+
+
+       outputs:
+               none
+
+
+
+
+
+
+CDROM_SET_OPTIONS
+       Set behavior options
+
+
+       usage::
+
+         int options;
+
+         ioctl(fd, CDROM_SET_OPTIONS, options);
+
+       inputs:
+               New values for drive options.  The logical 'or' of:
+
+           ==============      ==================================
+           CDO_AUTO_CLOSE      close tray on first open(2)
+           CDO_AUTO_EJECT      open tray on last release
+           CDO_USE_FFLAGS      use O_NONBLOCK information on open
+           CDO_LOCK            lock tray on open files
+           CDO_CHECK_TYPE      check type on open for data
+           ==============      ==================================
+
+       outputs:
+               Returns the resulting options settings in the
+               ioctl return value.  Returns -1 on error.
+
+       error return:
+         - ENOSYS      selected option(s) not supported by drive.
+
+
+
+
+CDROM_CLEAR_OPTIONS
+       Clear behavior options
+
+
+       Same as CDROM_SET_OPTIONS, except that selected options are
+       turned off.
+
+
+
+CDROM_SELECT_SPEED
+       Set the CD-ROM speed
+
+
+       usage::
+
+         int speed;
+
+         ioctl(fd, CDROM_SELECT_SPEED, speed);
+
+       inputs:
+               New drive speed.
+
+
+       outputs:
+               none
+
+
+       error return:
+         - ENOSYS      speed selection not supported by drive.
+
+
+
+CDROM_SELECT_DISC
+       Select disc (for juke-boxes)
+
+
+       usage::
+
+         int disk;
+
+         ioctl(fd, CDROM_SELECT_DISC, disk);
+
+       inputs:
+               Disk to load into drive.
+
+
+       outputs:
+               none
+
+
+       error return:
+         - EINVAL      Disk number beyond capacity of drive
+
+
+
+CDROM_MEDIA_CHANGED
+       Check is media changed
+
+
+       usage::
+
+         int slot;
+
+         ioctl(fd, CDROM_MEDIA_CHANGED, slot);
+
+       inputs:
+               Slot number to be tested, always zero except for jukeboxes.
+
+               May also be special values CDSL_NONE or CDSL_CURRENT
+
+       outputs:
+               Ioctl return value is 0 or 1 depending on whether the media
+
+         has been changed, or -1 on error.
+
+       error returns:
+         - ENOSYS      Drive can't detect media change
+         - EINVAL      Slot number beyond capacity of drive
+         - ENOMEM      Out of memory
+
+
+
+CDROM_DRIVE_STATUS
+       Get tray position, etc.
+
+
+       usage::
+
+         int slot;
+
+         ioctl(fd, CDROM_DRIVE_STATUS, slot);
+
+       inputs:
+               Slot number to be tested, always zero except for jukeboxes.
+
+               May also be special values CDSL_NONE or CDSL_CURRENT
+
+       outputs:
+               Ioctl return value will be one of the following values
+
+         from <linux/cdrom.h>:
+
+           =================== ==========================
+           CDS_NO_INFO         Information not available.
+           CDS_NO_DISC
+           CDS_TRAY_OPEN
+           CDS_DRIVE_NOT_READY
+           CDS_DISC_OK
+           -1                  error
+           =================== ==========================
+
+       error returns:
+         - ENOSYS      Drive can't detect drive status
+         - EINVAL      Slot number beyond capacity of drive
+         - ENOMEM      Out of memory
+
+
+
+
+CDROM_DISC_STATUS
+       Get disc type, etc.
+
+
+       usage::
+
+         ioctl(fd, CDROM_DISC_STATUS, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               Ioctl return value will be one of the following values
+
+         from <linux/cdrom.h>:
+
+           - CDS_NO_INFO
+           - CDS_AUDIO
+           - CDS_MIXED
+           - CDS_XA_2_2
+           - CDS_XA_2_1
+           - CDS_DATA_1
+
+       error returns:
+               none at present
+
+       notes:
+           - Source code comments state::
+
+
+               Ok, this is where problems start.  The current interface for
+               the CDROM_DISC_STATUS ioctl is flawed.  It makes the false
+               assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.
+               Unfortunately, while this is often the case, it is also
+               very common for CDs to have some tracks with data, and some
+               tracks with audio.      Just because I feel like it, I declare
+               the following to be the best way to cope.  If the CD has
+               ANY data tracks on it, it will be returned as a data CD.
+               If it has any XA tracks, I will return it as that.      Now I
+               could simplify this interface by combining these returns with
+               the above, but this more clearly demonstrates the problem
+               with the current interface.  Too bad this wasn't designed
+               to use bitmasks...             -Erik
+
+               Well, now we have the option CDS_MIXED: a mixed-type CD.
+               User level programmers might feel the ioctl is not very
+               useful.
+                               ---david
+
+
+
+
+CDROM_CHANGER_NSLOTS
+       Get number of slots
+
+
+       usage::
+
+         ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               The ioctl return value will be the number of slots in a
+               CD changer.  Typically 1 for non-multi-disk devices.
+
+       error returns:
+               none
+
+
+
+CDROM_LOCKDOOR
+       lock or unlock door
+
+
+       usage::
+
+         int lock;
+
+         ioctl(fd, CDROM_LOCKDOOR, lock);
+
+       inputs:
+               Door lock flag, 1=lock, 0=unlock
+
+
+       outputs:
+               none
+
+
+       error returns:
+         - EDRIVE_CANT_DO_THIS
+
+                               Door lock function not supported.
+         - EBUSY
+
+                               Attempt to unlock when multiple users
+                               have the drive open and not CAP_SYS_ADMIN
+
+       notes:
+               As of 2.6.8.1, the lock flag is a global lock, meaning that
+               all CD drives will be locked or unlocked together.  This is
+               probably a bug.
+
+               The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>
+               and is currently (2.6.8.1) the same as EOPNOTSUPP
+
+
+
+CDROM_DEBUG
+       Turn debug messages on/off
+
+
+       usage::
+
+         int debug;
+
+         ioctl(fd, CDROM_DEBUG, debug);
+
+       inputs:
+               Cdrom debug flag, 0=disable, 1=enable
+
+
+       outputs:
+               The ioctl return value will be the new debug flag.
+
+
+       error return:
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+
+
+
+CDROM_GET_CAPABILITY
+       get capabilities
+
+
+       usage::
+
+         ioctl(fd, CDROM_GET_CAPABILITY, 0);
+
+
+       inputs:
+               none
+
+
+       outputs:
+               The ioctl return value is the current device capability
+               flags.  See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.
+
+
+
+CDROMAUDIOBUFSIZ
+       set the audio buffer size
+
+
+       usage::
+
+         int arg;
+
+         ioctl(fd, CDROMAUDIOBUFSIZ, val);
+
+       inputs:
+               New audio buffer size
+
+
+       outputs:
+               The ioctl return value is the new audio buffer size, or -1
+               on error.
+
+       error return:
+         - ENOSYS      Not supported by this driver.
+
+       notes:
+               Not supported by all drivers.
+
+
+
+
+DVD_READ_STRUCT                        Read structure
+
+       usage::
+
+         dvd_struct s;
+
+         ioctl(fd, DVD_READ_STRUCT, &s);
+
+       inputs:
+               dvd_struct structure, containing:
+
+           =================== ==========================================
+           type                specifies the information desired, one of
+                               DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,
+                               DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,
+                               DVD_STRUCT_MANUFACT
+           physical.layer_num  desired layer, indexed from 0
+           copyright.layer_num desired layer, indexed from 0
+           disckey.agid
+           =================== ==========================================
+
+       outputs:
+               dvd_struct structure, containing:
+
+           =================== ================================
+           physical            for type == DVD_STRUCT_PHYSICAL
+           copyright           for type == DVD_STRUCT_COPYRIGHT
+           disckey.value       for type == DVD_STRUCT_DISCKEY
+           bca.{len,value}     for type == DVD_STRUCT_BCA
+           manufact.{len,valu} for type == DVD_STRUCT_MANUFACT
+           =================== ================================
+
+       error returns:
+         - EINVAL      physical.layer_num exceeds number of layers
+         - EIO         Received invalid response from drive
+
+
+
+DVD_WRITE_STRUCT               Write structure
+
+       Not implemented, as of 2.6.8.1
+
+
+
+DVD_AUTH                       Authentication
+
+       usage::
+
+         dvd_authinfo ai;
+
+         ioctl(fd, DVD_AUTH, &ai);
+
+       inputs:
+               dvd_authinfo structure.  See <linux/cdrom.h>
+
+
+       outputs:
+               dvd_authinfo structure.
+
+
+       error return:
+         - ENOTTY      ai.type not recognized.
+
+
+
+CDROM_SEND_PACKET
+       send a packet to the drive
+
+
+       usage::
+
+         struct cdrom_generic_command cgc;
+
+         ioctl(fd, CDROM_SEND_PACKET, &cgc);
+
+       inputs:
+               cdrom_generic_command structure containing the packet to send.
+
+
+       outputs:
+               none
+
+         cdrom_generic_command structure containing results.
+
+       error return:
+         - EIO
+
+                       command failed.
+         - EPERM
+
+                       Operation not permitted, either because a
+                       write command was attempted on a drive which
+                       is opened read-only, or because the command
+                       requires CAP_SYS_RAWIO
+         - EINVAL
+
+                       cgc.data_direction not set
+
+
+
+CDROM_NEXT_WRITABLE
+       get next writable block
+
+
+       usage::
+
+         long next;
+
+         ioctl(fd, CDROM_NEXT_WRITABLE, &next);
+
+       inputs:
+               none
+
+
+       outputs:
+               The next writable block.
+
+
+       notes:
+               If the device does not support this ioctl directly, the
+
+         ioctl will return CDROM_LAST_WRITTEN + 7.
+
+
+
+CDROM_LAST_WRITTEN
+       get last block written on disc
+
+
+       usage::
+
+         long last;
+
+         ioctl(fd, CDROM_LAST_WRITTEN, &last);
+
+       inputs:
+               none
+
+
+       outputs:
+               The last block written on disc
+
+
+       notes:
+               If the device does not support this ioctl directly, the
+               result is derived from the disc's table of contents.  If the
+               table of contents can't be read, this ioctl returns an
+               error.

diff --git a/Documentation/ioctl/cdrom.txt b/Documentation/ioctl/cdrom.txt
deleted file mode 100644 (file)
index a4d62a9..0000000
--- a/Documentation/ioctl/cdrom.txt
+++ /dev/null
@@ -1,967 +0,0 @@
-               Summary of CDROM ioctl calls.
-               ============================
-
-               Edward A. Falk <efalk@google.com>
-
-               November, 2004
-
-This document attempts to describe the ioctl(2) calls supported by
-the CDROM layer.  These are by-and-large implemented (as of Linux 2.6)
-in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c
-
-ioctl values are listed in <linux/cdrom.h>.  As of this writing, they
-are as follows:
-
-       CDROMPAUSE              Pause Audio Operation
-       CDROMRESUME             Resume paused Audio Operation
-       CDROMPLAYMSF            Play Audio MSF (struct cdrom_msf)
-       CDROMPLAYTRKIND         Play Audio Track/index (struct cdrom_ti)
-       CDROMREADTOCHDR         Read TOC header (struct cdrom_tochdr)
-       CDROMREADTOCENTRY       Read TOC entry (struct cdrom_tocentry)
-       CDROMSTOP               Stop the cdrom drive
-       CDROMSTART              Start the cdrom drive
-       CDROMEJECT              Ejects the cdrom media
-       CDROMVOLCTRL            Control output volume (struct cdrom_volctrl)
-       CDROMSUBCHNL            Read subchannel data (struct cdrom_subchnl)
-       CDROMREADMODE2          Read CDROM mode 2 data (2336 Bytes)
-                                          (struct cdrom_read)
-       CDROMREADMODE1          Read CDROM mode 1 data (2048 Bytes)
-                                          (struct cdrom_read)
-       CDROMREADAUDIO          (struct cdrom_read_audio)
-       CDROMEJECT_SW           enable(1)/disable(0) auto-ejecting
-       CDROMMULTISESSION       Obtain the start-of-last-session
-                                 address of multi session disks
-                                 (struct cdrom_multisession)
-       CDROM_GET_MCN           Obtain the "Universal Product Code"
-                                  if available (struct cdrom_mcn)
-       CDROM_GET_UPC           Deprecated, use CDROM_GET_MCN instead.
-       CDROMRESET              hard-reset the drive
-       CDROMVOLREAD            Get the drive's volume setting
-                                         (struct cdrom_volctrl)
-       CDROMREADRAW            read data in raw mode (2352 Bytes)
-                                          (struct cdrom_read)
-       CDROMREADCOOKED         read data in cooked mode
-       CDROMSEEK               seek msf address
-       CDROMPLAYBLK            scsi-cd only, (struct cdrom_blk)
-       CDROMREADALL            read all 2646 bytes
-       CDROMGETSPINDOWN        return 4-bit spindown value
-       CDROMSETSPINDOWN        set 4-bit spindown value
-       CDROMCLOSETRAY          pendant of CDROMEJECT
-       CDROM_SET_OPTIONS       Set behavior options
-       CDROM_CLEAR_OPTIONS     Clear behavior options
-       CDROM_SELECT_SPEED      Set the CD-ROM speed
-       CDROM_SELECT_DISC       Select disc (for juke-boxes)
-       CDROM_MEDIA_CHANGED     Check is media changed
-       CDROM_DRIVE_STATUS      Get tray position, etc.
-       CDROM_DISC_STATUS       Get disc type, etc.
-       CDROM_CHANGER_NSLOTS    Get number of slots
-       CDROM_LOCKDOOR          lock or unlock door
-       CDROM_DEBUG             Turn debug messages on/off
-       CDROM_GET_CAPABILITY    get capabilities
-       CDROMAUDIOBUFSIZ        set the audio buffer size
-       DVD_READ_STRUCT         Read structure
-       DVD_WRITE_STRUCT        Write structure
-       DVD_AUTH                Authentication
-       CDROM_SEND_PACKET       send a packet to the drive
-       CDROM_NEXT_WRITABLE     get next writable block
-       CDROM_LAST_WRITTEN      get last block written on disc
-
-
-The information that follows was determined from reading kernel source
-code.  It is likely that some corrections will be made over time.
-
-
-
-
-
-
-
-General:
-
-       Unless otherwise specified, all ioctl calls return 0 on success
-       and -1 with errno set to an appropriate value on error.  (Some
-       ioctls return non-negative data values.)
-
-       Unless otherwise specified, all ioctl calls return -1 and set
-       errno to EFAULT on a failed attempt to copy data to or from user
-       address space.
-
-       Individual drivers may return error codes not listed here.
-
-       Unless otherwise specified, all data structures and constants
-       are defined in <linux/cdrom.h>
-
-
-
-
-CDROMPAUSE                     Pause Audio Operation
-
-       usage:
-
-         ioctl(fd, CDROMPAUSE, 0);
-
-       inputs:         none
-
-       outputs:        none
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-
-CDROMRESUME                    Resume paused Audio Operation
-
-       usage:
-
-         ioctl(fd, CDROMRESUME, 0);
-
-       inputs:         none
-
-       outputs:        none
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-
-CDROMPLAYMSF                   Play Audio MSF (struct cdrom_msf)
-
-       usage:
-
-         struct cdrom_msf msf;
-         ioctl(fd, CDROMPLAYMSF, &msf);
-
-       inputs:
-         cdrom_msf structure, describing a segment of music to play
-
-       outputs:        none
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-       notes:
-         MSF stands for minutes-seconds-frames
-         LBA stands for logical block address
-
-         Segment is described as start and end times, where each time
-         is described as minutes:seconds:frames.  A frame is 1/75 of
-         a second.
-
-
-CDROMPLAYTRKIND                        Play Audio Track/index (struct cdrom_ti)
-
-       usage:
-
-         struct cdrom_ti ti;
-         ioctl(fd, CDROMPLAYTRKIND, &ti);
-
-       inputs:
-         cdrom_ti structure, describing a segment of music to play
-
-       outputs:        none
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-       notes:
-         Segment is described as start and end times, where each time
-         is described as a track and an index.
-
-
-
-CDROMREADTOCHDR                        Read TOC header (struct cdrom_tochdr)
-
-       usage:
-
-         cdrom_tochdr header;
-         ioctl(fd, CDROMREADTOCHDR, &header);
-
-       inputs:
-         cdrom_tochdr structure
-
-       outputs:
-         cdrom_tochdr structure
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-
-
-CDROMREADTOCENTRY              Read TOC entry (struct cdrom_tocentry)
-
-       usage:
-
-         struct cdrom_tocentry entry;
-         ioctl(fd, CDROMREADTOCENTRY, &entry);
-
-       inputs:
-         cdrom_tocentry structure
-
-       outputs:
-         cdrom_tocentry structure
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-         EINVAL        entry.cdte_format not CDROM_MSF or CDROM_LBA
-         EINVAL        requested track out of bounds
-         EIO           I/O error reading TOC
-
-       notes:
-         TOC stands for Table Of Contents
-         MSF stands for minutes-seconds-frames
-         LBA stands for logical block address
-
-
-
-CDROMSTOP                      Stop the cdrom drive
-
-       usage:
-
-         ioctl(fd, CDROMSTOP, 0);
-
-       inputs:         none
-
-       outputs:        none
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-       notes:
-         Exact interpretation of this ioctl depends on the device,
-         but most seem to spin the drive down.
-
-
-CDROMSTART                     Start the cdrom drive
-
-       usage:
-
-         ioctl(fd, CDROMSTART, 0);
-
-       inputs:         none
-
-       outputs:        none
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-       notes:
-         Exact interpretation of this ioctl depends on the device,
-         but most seem to spin the drive up and/or close the tray.
-         Other devices ignore the ioctl completely.
-
-
-CDROMEJECT                     Ejects the cdrom media
-
-       usage:
-
-         ioctl(fd, CDROMEJECT, 0);
-
-       inputs:         none
-
-       outputs:        none
-
-       error returns:
-         ENOSYS        cd drive not capable of ejecting
-         EBUSY         other processes are accessing drive, or door is locked
-
-       notes:
-         See CDROM_LOCKDOOR, below.
-
-
-
-CDROMCLOSETRAY                 pendant of CDROMEJECT
-
-       usage:
-
-         ioctl(fd, CDROMCLOSETRAY, 0);
-
-       inputs:         none
-
-       outputs:        none
-
-       error returns:
-         ENOSYS        cd drive not capable of closing the tray
-         EBUSY         other processes are accessing drive, or door is locked
-
-       notes:
-         See CDROM_LOCKDOOR, below.
-
-
-
-CDROMVOLCTRL                   Control output volume (struct cdrom_volctrl)
-
-       usage:
-
-         struct cdrom_volctrl volume;
-         ioctl(fd, CDROMVOLCTRL, &volume);
-
-       inputs:
-         cdrom_volctrl structure containing volumes for up to 4
-         channels.
-
-       outputs:        none
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-
-
-CDROMVOLREAD                   Get the drive's volume setting
-                                         (struct cdrom_volctrl)
-
-       usage:
-
-         struct cdrom_volctrl volume;
-         ioctl(fd, CDROMVOLREAD, &volume);
-
-       inputs:         none
-
-       outputs:
-         The current volume settings.
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-
-
-
-CDROMSUBCHNL                   Read subchannel data (struct cdrom_subchnl)
-
-       usage:
-
-         struct cdrom_subchnl q;
-         ioctl(fd, CDROMSUBCHNL, &q);
-
-       inputs:
-         cdrom_subchnl structure
-
-       outputs:
-         cdrom_subchnl structure
-
-       error return:
-         ENOSYS        cd drive not audio-capable.
-         EINVAL        format not CDROM_MSF or CDROM_LBA
-
-       notes:
-         Format is converted to CDROM_MSF or CDROM_LBA
-         as per user request on return
-
-
-
-CDROMREADRAW                   read data in raw mode (2352 Bytes)
-                                          (struct cdrom_read)
-
-       usage:
-
-         union {
-           struct cdrom_msf msf;               /* input */
-           char buffer[CD_FRAMESIZE_RAW];      /* return */
-         } arg;
-         ioctl(fd, CDROMREADRAW, &arg);
-
-       inputs:
-         cdrom_msf structure indicating an address to read.
-         Only the start values are significant.
-
-       outputs:
-         Data written to address provided by user.
-
-       error return:
-         EINVAL        address less than 0, or msf less than 0:2:0
-         ENOMEM        out of memory
-
-       notes:
-         As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this
-         ioctl accepts a cdrom_read structure, but actual source code
-         reads a cdrom_msf structure and writes a buffer of data to
-         the same address.
-
-         MSF values are converted to LBA values via this formula:
-
-           lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;
-
-
-
-
-CDROMREADMODE1                 Read CDROM mode 1 data (2048 Bytes)
-                                          (struct cdrom_read)
-
-       notes:
-         Identical to CDROMREADRAW except that block size is
-         CD_FRAMESIZE (2048) bytes
-
-
-
-CDROMREADMODE2                 Read CDROM mode 2 data (2336 Bytes)
-                                          (struct cdrom_read)
-
-       notes:
-         Identical to CDROMREADRAW except that block size is
-         CD_FRAMESIZE_RAW0 (2336) bytes
-
-
-
-CDROMREADAUDIO                 (struct cdrom_read_audio)
-
-       usage:
-
-         struct cdrom_read_audio ra;
-         ioctl(fd, CDROMREADAUDIO, &ra);
-
-       inputs:
-         cdrom_read_audio structure containing read start
-         point and length
-
-       outputs:
-         audio data, returned to buffer indicated by ra
-
-       error return:
-         EINVAL        format not CDROM_MSF or CDROM_LBA
-         EINVAL        nframes not in range [1 75]
-         ENXIO         drive has no queue (probably means invalid fd)
-         ENOMEM        out of memory
-
-
-CDROMEJECT_SW                  enable(1)/disable(0) auto-ejecting
-
-       usage:
-
-         int val;
-         ioctl(fd, CDROMEJECT_SW, val);
-
-       inputs:
-         Flag specifying auto-eject flag.
-
-       outputs:        none
-
-       error return:
-         ENOSYS        Drive is not capable of ejecting.
-         EBUSY         Door is locked
-
-
-
-
-CDROMMULTISESSION              Obtain the start-of-last-session
-                                 address of multi session disks
-                                 (struct cdrom_multisession)
-       usage:
-
-         struct cdrom_multisession ms_info;
-         ioctl(fd, CDROMMULTISESSION, &ms_info);
-
-       inputs:
-         cdrom_multisession structure containing desired
-         format.
-
-       outputs:
-         cdrom_multisession structure is filled with last_session
-         information.
-
-       error return:
-         EINVAL        format not CDROM_MSF or CDROM_LBA
-
-
-CDROM_GET_MCN                  Obtain the "Universal Product Code"
-                                  if available (struct cdrom_mcn)
-
-       usage:
-
-         struct cdrom_mcn mcn;
-         ioctl(fd, CDROM_GET_MCN, &mcn);
-
-       inputs:         none
-
-       outputs:
-         Universal Product Code
-
-       error return:
-         ENOSYS        Drive is not capable of reading MCN data.
-
-       notes:
-         Source code comments state:
-
-           The following function is implemented, although very few
-           audio discs give Universal Product Code information, which
-           should just be the Medium Catalog Number on the box.  Note,
-           that the way the code is written on the CD is /not/ uniform
-           across all discs!
-
-
-
-
-CDROM_GET_UPC                  CDROM_GET_MCN  (deprecated)
-
-       Not implemented, as of 2.6.8.1
-
-
-
-CDROMRESET                     hard-reset the drive
-
-       usage:
-
-         ioctl(fd, CDROMRESET, 0);
-
-       inputs:         none
-
-       outputs:        none
-
-       error return:
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         ENOSYS        Drive is not capable of resetting.
-
-
-
-
-CDROMREADCOOKED                        read data in cooked mode
-
-       usage:
-
-         u8 buffer[CD_FRAMESIZE]
-         ioctl(fd, CDROMREADCOOKED, buffer);
-
-       inputs:         none
-
-       outputs:
-         2048 bytes of data, "cooked" mode.
-
-       notes:
-         Not implemented on all drives.
-
-
-
-
-CDROMREADALL                   read all 2646 bytes
-
-       Same as CDROMREADCOOKED, but reads 2646 bytes.
-
-
-
-CDROMSEEK                      seek msf address
-
-       usage:
-
-         struct cdrom_msf msf;
-         ioctl(fd, CDROMSEEK, &msf);
-
-       inputs:
-         MSF address to seek to.
-
-       outputs:        none
-
-
-
-CDROMPLAYBLK                   scsi-cd only, (struct cdrom_blk)
-
-       usage:
-
-         struct cdrom_blk blk;
-         ioctl(fd, CDROMPLAYBLK, &blk);
-
-       inputs:
-         Region to play
-
-       outputs:        none
-
-
-
-CDROMGETSPINDOWN
-
-       usage:
-
-         char spindown;
-         ioctl(fd, CDROMGETSPINDOWN, &spindown);
-
-       inputs:         none
-
-       outputs:
-         The value of the current 4-bit spindown value.
-
-
-
-
-CDROMSETSPINDOWN
-
-       usage:
-
-         char spindown
-         ioctl(fd, CDROMSETSPINDOWN, &spindown);
-
-       inputs:
-         4-bit value used to control spindown (TODO: more detail here)
-
-       outputs:        none
-
-
-
-
-
-CDROM_SET_OPTIONS              Set behavior options
-
-       usage:
-
-         int options;
-         ioctl(fd, CDROM_SET_OPTIONS, options);
-
-       inputs:
-         New values for drive options.  The logical 'or' of:
-           CDO_AUTO_CLOSE      close tray on first open(2)
-           CDO_AUTO_EJECT      open tray on last release
-           CDO_USE_FFLAGS      use O_NONBLOCK information on open
-           CDO_LOCK            lock tray on open files
-           CDO_CHECK_TYPE      check type on open for data
-
-       outputs:
-         Returns the resulting options settings in the
-         ioctl return value.  Returns -1 on error.
-
-       error return:
-         ENOSYS        selected option(s) not supported by drive.
-
-
-
-
-CDROM_CLEAR_OPTIONS            Clear behavior options
-
-       Same as CDROM_SET_OPTIONS, except that selected options are
-       turned off.
-
-
-
-CDROM_SELECT_SPEED             Set the CD-ROM speed
-
-       usage:
-
-         int speed;
-         ioctl(fd, CDROM_SELECT_SPEED, speed);
-
-       inputs:
-         New drive speed.
-
-       outputs:        none
-
-       error return:
-         ENOSYS        speed selection not supported by drive.
-
-
-
-CDROM_SELECT_DISC              Select disc (for juke-boxes)
-
-       usage:
-
-         int disk;
-         ioctl(fd, CDROM_SELECT_DISC, disk);
-
-       inputs:
-         Disk to load into drive.
-
-       outputs:        none
-
-       error return:
-         EINVAL        Disk number beyond capacity of drive
-
-
-
-CDROM_MEDIA_CHANGED            Check is media changed
-
-       usage:
-
-         int slot;
-         ioctl(fd, CDROM_MEDIA_CHANGED, slot);
-
-       inputs:
-         Slot number to be tested, always zero except for jukeboxes.
-         May also be special values CDSL_NONE or CDSL_CURRENT
-
-       outputs:
-         Ioctl return value is 0 or 1 depending on whether the media
-         has been changed, or -1 on error.
-
-       error returns:
-         ENOSYS        Drive can't detect media change
-         EINVAL        Slot number beyond capacity of drive
-         ENOMEM        Out of memory
-
-
-
-CDROM_DRIVE_STATUS             Get tray position, etc.
-
-       usage:
-
-         int slot;
-         ioctl(fd, CDROM_DRIVE_STATUS, slot);
-
-       inputs:
-         Slot number to be tested, always zero except for jukeboxes.
-         May also be special values CDSL_NONE or CDSL_CURRENT
-
-       outputs:
-         Ioctl return value will be one of the following values
-         from <linux/cdrom.h>:
-
-           CDS_NO_INFO         Information not available.
-           CDS_NO_DISC
-           CDS_TRAY_OPEN
-           CDS_DRIVE_NOT_READY
-           CDS_DISC_OK
-           -1                  error
-
-       error returns:
-         ENOSYS        Drive can't detect drive status
-         EINVAL        Slot number beyond capacity of drive
-         ENOMEM        Out of memory
-
-
-
-
-CDROM_DISC_STATUS              Get disc type, etc.
-
-       usage:
-
-         ioctl(fd, CDROM_DISC_STATUS, 0);
-
-       inputs:         none
-
-       outputs:
-         Ioctl return value will be one of the following values
-         from <linux/cdrom.h>:
-           CDS_NO_INFO
-           CDS_AUDIO
-           CDS_MIXED
-           CDS_XA_2_2
-           CDS_XA_2_1
-           CDS_DATA_1
-
-       error returns:  none at present
-
-       notes:
-         Source code comments state:
-
-           Ok, this is where problems start.  The current interface for
-           the CDROM_DISC_STATUS ioctl is flawed.  It makes the false
-           assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.
-           Unfortunately, while this is often the case, it is also
-           very common for CDs to have some tracks with data, and some
-           tracks with audio.  Just because I feel like it, I declare
-           the following to be the best way to cope.  If the CD has
-           ANY data tracks on it, it will be returned as a data CD.
-           If it has any XA tracks, I will return it as that.  Now I
-           could simplify this interface by combining these returns with
-           the above, but this more clearly demonstrates the problem
-           with the current interface.  Too bad this wasn't designed
-           to use bitmasks...         -Erik
-
-           Well, now we have the option CDS_MIXED: a mixed-type CD.
-           User level programmers might feel the ioctl is not very
-           useful.
-                       ---david
-
-
-
-
-CDROM_CHANGER_NSLOTS           Get number of slots
-
-       usage:
-
-         ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
-
-       inputs:         none
-
-       outputs:
-         The ioctl return value will be the number of slots in a
-         CD changer.  Typically 1 for non-multi-disk devices.
-
-       error returns:  none
-
-
-
-CDROM_LOCKDOOR                 lock or unlock door
-
-       usage:
-
-         int lock;
-         ioctl(fd, CDROM_LOCKDOOR, lock);
-
-       inputs:
-         Door lock flag, 1=lock, 0=unlock
-
-       outputs:        none
-
-       error returns:
-         EDRIVE_CANT_DO_THIS   Door lock function not supported.
-         EBUSY                 Attempt to unlock when multiple users
-                               have the drive open and not CAP_SYS_ADMIN
-
-       notes:
-         As of 2.6.8.1, the lock flag is a global lock, meaning that
-         all CD drives will be locked or unlocked together.  This is
-         probably a bug.
-
-         The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>
-         and is currently (2.6.8.1) the same as EOPNOTSUPP
-
-
-
-CDROM_DEBUG                    Turn debug messages on/off
-
-       usage:
-
-         int debug;
-         ioctl(fd, CDROM_DEBUG, debug);
-
-       inputs:
-         Cdrom debug flag, 0=disable, 1=enable
-
-       outputs:
-         The ioctl return value will be the new debug flag.
-
-       error return:
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-
-
-
-CDROM_GET_CAPABILITY           get capabilities
-
-       usage:
-
-         ioctl(fd, CDROM_GET_CAPABILITY, 0);
-
-       inputs:         none
-
-       outputs:
-         The ioctl return value is the current device capability
-         flags.  See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.
-
-
-
-CDROMAUDIOBUFSIZ               set the audio buffer size
-
-       usage:
-
-         int arg;
-         ioctl(fd, CDROMAUDIOBUFSIZ, val);
-
-       inputs:
-         New audio buffer size
-
-       outputs:
-         The ioctl return value is the new audio buffer size, or -1
-         on error.
-
-       error return:
-         ENOSYS        Not supported by this driver.
-
-       notes:
-         Not supported by all drivers.
-
-
-
-DVD_READ_STRUCT                        Read structure
-
-       usage:
-
-         dvd_struct s;
-         ioctl(fd, DVD_READ_STRUCT, &s);
-
-       inputs:
-         dvd_struct structure, containing:
-           type                specifies the information desired, one of
-                               DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,
-                               DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,
-                               DVD_STRUCT_MANUFACT
-           physical.layer_num  desired layer, indexed from 0
-           copyright.layer_num desired layer, indexed from 0
-           disckey.agid
-
-       outputs:
-         dvd_struct structure, containing:
-           physical            for type == DVD_STRUCT_PHYSICAL
-           copyright           for type == DVD_STRUCT_COPYRIGHT
-           disckey.value       for type == DVD_STRUCT_DISCKEY
-           bca.{len,value}     for type == DVD_STRUCT_BCA
-           manufact.{len,valu} for type == DVD_STRUCT_MANUFACT
-
-       error returns:
-         EINVAL        physical.layer_num exceeds number of layers
-         EIO           Received invalid response from drive
-
-
-
-DVD_WRITE_STRUCT               Write structure
-
-       Not implemented, as of 2.6.8.1
-
-
-
-DVD_AUTH                       Authentication
-
-       usage:
-
-         dvd_authinfo ai;
-         ioctl(fd, DVD_AUTH, &ai);
-
-       inputs:
-         dvd_authinfo structure.  See <linux/cdrom.h>
-
-       outputs:
-         dvd_authinfo structure.
-
-       error return:
-         ENOTTY        ai.type not recognized.
-
-
-
-CDROM_SEND_PACKET              send a packet to the drive
-
-       usage:
-
-         struct cdrom_generic_command cgc;
-         ioctl(fd, CDROM_SEND_PACKET, &cgc);
-
-       inputs:
-         cdrom_generic_command structure containing the packet to send.
-
-       outputs:        none
-         cdrom_generic_command structure containing results.
-
-       error return:
-         EIO           command failed.
-         EPERM         Operation not permitted, either because a
-                       write command was attempted on a drive which
-                       is opened read-only, or because the command
-                       requires CAP_SYS_RAWIO
-         EINVAL        cgc.data_direction not set
-
-
-
-CDROM_NEXT_WRITABLE            get next writable block
-
-       usage:
-
-         long next;
-         ioctl(fd, CDROM_NEXT_WRITABLE, &next);
-
-       inputs:         none
-
-       outputs:
-         The next writable block.
-
-       notes:
-         If the device does not support this ioctl directly, the
-         ioctl will return CDROM_LAST_WRITTEN + 7.
-
-
-
-CDROM_LAST_WRITTEN             get last block written on disc
-
-       usage:
-
-         long last;
-         ioctl(fd, CDROM_LAST_WRITTEN, &last);
-
-       inputs:         none
-
-       outputs:
-         The last block written on disc
-
-       notes:
-         If the device does not support this ioctl directly, the
-         result is derived from the disc's table of contents.  If the
-         table of contents can't be read, this ioctl returns an
-         error.

diff --git a/Documentation/ioctl/hdio.txt b/Documentation/ioctl/hdio.rst
similarity index 54%
rename from Documentation/ioctl/hdio.txt
rename to Documentation/ioctl/hdio.rst
index 18eb98c44ffeb1e24bec6c1efb7b6937d97fb75a..e822e3dff1769bd952c390f2f6fa4e4dd28b1a33 100644 (file)
--- a/Documentation/ioctl/hdio.txt
+++ b/Documentation/ioctl/hdio.rst
@@ -1,9 +1,10 @@
-               Summary of HDIO_ ioctl calls.
-               ============================
+==============================
+Summary of `HDIO_` ioctl calls
+==============================

 
 

-               Edward A. Falk <efalk@google.com>
+- Edward A. Falk <efalk@google.com>

 
 

-               November, 2004
+November, 2004

 
 This document attempts to describe the ioctl(2) calls supported by
 the HD/IDE layer.  These are by-and-large implemented (as of Linux 2.6)
 
 This document attempts to describe the ioctl(2) calls supported by
 the HD/IDE layer.  These are by-and-large implemented (as of Linux 2.6)


@@ -14,6 +15,7 @@ are as follows:
 
     ioctls that pass argument pointers to user space:
 
 
     ioctls that pass argument pointers to user space:
 

+       ======================= =======================================

        HDIO_GETGEO             get device geometry
        HDIO_GET_UNMASKINTR     get current unmask setting
        HDIO_GET_MULTCOUNT      get current IDE blockmode setting
        HDIO_GETGEO             get device geometry
        HDIO_GET_UNMASKINTR     get current unmask setting
        HDIO_GET_MULTCOUNT      get current IDE blockmode setting


@@ -36,9 +38,11 @@ are as follows:
        HDIO_DRIVE_TASK         execute task and special drive command
        HDIO_DRIVE_CMD          execute a special drive command
        HDIO_DRIVE_CMD_AEB      HDIO_DRIVE_TASK
        HDIO_DRIVE_TASK         execute task and special drive command
        HDIO_DRIVE_CMD          execute a special drive command
        HDIO_DRIVE_CMD_AEB      HDIO_DRIVE_TASK

+       ======================= =======================================

 
     ioctls that pass non-pointer values:
 
 
     ioctls that pass non-pointer values:
 

+       ======================= =======================================

        HDIO_SET_MULTCOUNT      change IDE blockmode
        HDIO_SET_UNMASKINTR     permit other irqs during I/O
        HDIO_SET_KEEPSETTINGS   keep ioctl settings on reset
        HDIO_SET_MULTCOUNT      change IDE blockmode
        HDIO_SET_UNMASKINTR     permit other irqs during I/O
        HDIO_SET_KEEPSETTINGS   keep ioctl settings on reset


@@ -57,16 +61,13 @@ are as follows:
 
        HDIO_SET_IDE_SCSI       Set scsi emulation mode on/off
        HDIO_SET_SCSI_IDE       not implemented yet
 
        HDIO_SET_IDE_SCSI       Set scsi emulation mode on/off
        HDIO_SET_SCSI_IDE       not implemented yet

+       ======================= =======================================

 
 
 The information that follows was determined from reading kernel source
 code.  It is likely that some corrections will be made over time.
 
 
 
 The information that follows was determined from reading kernel source
 code.  It is likely that some corrections will be made over time.
 

-
-
-
-
-
+------------------------------------------------------------------------------

 
 General:
 
 
 General:
 


@@ -80,459 +81,610 @@ General:
        Unless otherwise specified, all data structures and constants
        are defined in <linux/hdreg.h>
 
        Unless otherwise specified, all data structures and constants
        are defined in <linux/hdreg.h>
 

+------------------------------------------------------------------------------

 
 

+HDIO_GETGEO
+       get device geometry

 
 

-HDIO_GETGEO                    get device geometry

 
 

-       usage:
+       usage::

 
          struct hd_geometry geom;
 
          struct hd_geometry geom;

+

          ioctl(fd, HDIO_GETGEO, &geom);
 
 
          ioctl(fd, HDIO_GETGEO, &geom);
 
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

+               hd_geometry structure containing:

 
 

-         hd_geometry structure containing:

 
 

+           =========   ==================================

            heads       number of heads
            sectors     number of sectors/track
            cylinders   number of cylinders, mod 65536
            start       starting sector of this partition.
            heads       number of heads
            sectors     number of sectors/track
            cylinders   number of cylinders, mod 65536
            start       starting sector of this partition.

+           =========   ==================================

 
 
        error returns:
 
 
        error returns:

-         EINVAL        if the device is not a disk drive or floppy drive,
-                       or if the user passes a null pointer
+         - EINVAL
+
+                       if the device is not a disk drive or floppy drive,
+                       or if the user passes a null pointer

 
 
        notes:
 
 
        notes:

+               Not particularly useful with modern disk drives, whose geometry
+               is a polite fiction anyway.  Modern drives are addressed
+               purely by sector number nowadays (lba addressing), and the
+               drive geometry is an abstraction which is actually subject
+               to change.  Currently (as of Nov 2004), the geometry values
+               are the "bios" values -- presumably the values the drive had
+               when Linux first booted.

 
 

-         Not particularly useful with modern disk drives, whose geometry
-         is a polite fiction anyway.  Modern drives are addressed
-         purely by sector number nowadays (lba addressing), and the
-         drive geometry is an abstraction which is actually subject
-         to change.  Currently (as of Nov 2004), the geometry values
-         are the "bios" values -- presumably the values the drive had
-         when Linux first booted.
+               In addition, the cylinders field of the hd_geometry is an
+               unsigned short, meaning that on most architectures, this
+               ioctl will not return a meaningful value on drives with more
+               than 65535 tracks.

 
 

-         In addition, the cylinders field of the hd_geometry is an
-         unsigned short, meaning that on most architectures, this
-         ioctl will not return a meaningful value on drives with more
-         than 65535 tracks.
+               The start field is unsigned long, meaning that it will not
+               contain a meaningful value for disks over 219 Gb in size.

 
 

-         The start field is unsigned long, meaning that it will not
-         contain a meaningful value for disks over 219 Gb in size.

 
 
 
 
 
 

+HDIO_GET_UNMASKINTR
+       get current unmask setting

 
 

-HDIO_GET_UNMASKINTR            get current unmask setting

 
 

-       usage:
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_UNMASKINTR, &val);
 
          ioctl(fd, HDIO_GET_UNMASKINTR, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the drive's current unmask setting
+               The value of the drive's current unmask setting

 
 
 
 
 
 

-HDIO_SET_UNMASKINTR            permit other irqs during I/O

 
 

-       usage:
+
+HDIO_SET_UNMASKINTR
+       permit other irqs during I/O
+
+
+       usage::

 
          unsigned long val;
 
          unsigned long val;

+

          ioctl(fd, HDIO_SET_UNMASKINTR, val);
 
        inputs:
          ioctl(fd, HDIO_SET_UNMASKINTR, val);
 
        inputs:

-         New value for unmask flag
+               New value for unmask flag
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 1]
-         EBUSY         Controller busy
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 1]
+         - EBUSY       Controller busy
+

 
 
 
 
 
 

+HDIO_GET_MULTCOUNT
+       get current IDE blockmode setting

 
 

-HDIO_GET_MULTCOUNT             get current IDE blockmode setting

 
 

-       usage:
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_MULTCOUNT, &val);
 
          ioctl(fd, HDIO_GET_MULTCOUNT, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the current IDE block mode setting.  This
-         controls how many sectors the drive will transfer per
-         interrupt.
+               The value of the current IDE block mode setting.  This
+               controls how many sectors the drive will transfer per
+               interrupt.
+

 
 
 
 

+HDIO_SET_MULTCOUNT
+       change IDE blockmode

 
 

-HDIO_SET_MULTCOUNT             change IDE blockmode

 
 

-       usage:
+       usage::

 
          int val;
 
          int val;

+

          ioctl(fd, HDIO_SET_MULTCOUNT, val);
 
        inputs:
          ioctl(fd, HDIO_SET_MULTCOUNT, val);
 
        inputs:

-         New value for IDE block mode setting.  This controls how many
-         sectors the drive will transfer per interrupt.
+               New value for IDE block mode setting.  This controls how many
+               sectors the drive will transfer per interrupt.
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range supported by disk.
-         EBUSY         Controller busy or blockmode already set.
-         EIO           Drive did not accept new block mode.
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range supported by disk.
+         - EBUSY       Controller busy or blockmode already set.
+         - EIO         Drive did not accept new block mode.

 
        notes:
 
        notes:

-
-         Source code comments read:
+         Source code comments read::

 
            This is tightly woven into the driver->do_special cannot
            touch.  DON'T do it again until a total personality rewrite
            is committed.
 
          If blockmode has already been set, this ioctl will fail with
 
            This is tightly woven into the driver->do_special cannot
            touch.  DON'T do it again until a total personality rewrite
            is committed.
 
          If blockmode has already been set, this ioctl will fail with

-         EBUSY
+         -EBUSY

 
 
 
 
 
 

-HDIO_GET_QDMA                  get use-qdma flag
+HDIO_GET_QDMA
+       get use-qdma flag
+

 
        Not implemented, as of 2.6.8.1
 
 
 
 
        Not implemented, as of 2.6.8.1
 
 
 

-HDIO_SET_XFER                  set transfer rate via proc
+HDIO_SET_XFER
+       set transfer rate via proc
+

 
        Not implemented, as of 2.6.8.1
 
 
 
 
        Not implemented, as of 2.6.8.1
 
 
 

-HDIO_OBSOLETE_IDENTITY         OBSOLETE, DO NOT USE
+HDIO_OBSOLETE_IDENTITY
+       OBSOLETE, DO NOT USE
+

 
        Same as HDIO_GET_IDENTITY (see below), except that it only
        returns the first 142 bytes of drive identity information.
 
 
 
 
        Same as HDIO_GET_IDENTITY (see below), except that it only
        returns the first 142 bytes of drive identity information.
 
 
 

-HDIO_GET_IDENTITY              get IDE identification info
+HDIO_GET_IDENTITY
+       get IDE identification info
+

 
 

-       usage:
+       usage::

 
          unsigned char identity[512];
 
          unsigned char identity[512];

+

          ioctl(fd, HDIO_GET_IDENTITY, identity);
 
          ioctl(fd, HDIO_GET_IDENTITY, identity);
 

-       inputs:         none
+       inputs:
+               none

 
 

-       outputs:

 
 

-         ATA drive identity information.  For full description, see
-         the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
-         the ATA specification.
+
+       outputs:
+               ATA drive identity information.  For full description, see
+               the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
+               the ATA specification.

 
        error returns:
 
        error returns:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         ENOMSG        IDENTIFY DEVICE information not available
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - ENOMSG      IDENTIFY DEVICE information not available

 
        notes:
 
        notes:

+               Returns information that was obtained when the drive was
+               probed.  Some of this information is subject to change, and
+               this ioctl does not re-probe the drive to update the
+               information.

 
 

-         Returns information that was obtained when the drive was
-         probed.  Some of this information is subject to change, and
-         this ioctl does not re-probe the drive to update the
-         information.
+               This information is also available from /proc/ide/hdX/identify

 
 

-         This information is also available from /proc/ide/hdX/identify

 
 
 
 

+HDIO_GET_KEEPSETTINGS
+       get keep-settings-on-reset flag

 
 

-HDIO_GET_KEEPSETTINGS          get keep-settings-on-reset flag

 
 

-       usage:
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
 
          ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the current "keep settings" flag
+               The value of the current "keep settings" flag
+
+

 
        notes:
 
        notes:

+               When set, indicates that kernel should restore settings
+               after a drive reset.

 
 

-         When set, indicates that kernel should restore settings
-         after a drive reset.

 
 
 
 

+HDIO_SET_KEEPSETTINGS
+       keep ioctl settings on reset

 
 

-HDIO_SET_KEEPSETTINGS          keep ioctl settings on reset

 
 

-       usage:
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
 
        inputs:
          ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
 
        inputs:

-         New value for keep_settings flag
+               New value for keep_settings flag
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 1]
-         EBUSY         Controller busy
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 1]
+         - EBUSY               Controller busy
+

 
 
 
 

+HDIO_GET_32BIT
+       get current io_32bit setting

 
 

-HDIO_GET_32BIT                 get current io_32bit setting

 
 

-       usage:
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_32BIT, &val);
 
          ioctl(fd, HDIO_GET_32BIT, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the current io_32bit setting
+               The value of the current io_32bit setting
+
+

 
        notes:
 
        notes:

+               0=16-bit, 1=32-bit, 2,3 = 32bit+sync
+

 
 

-         0=16-bit, 1=32-bit, 2,3 = 32bit+sync

 
 
 
 
 
 

-HDIO_GET_NOWERR                        get ignore-write-error flag
+HDIO_GET_NOWERR
+       get ignore-write-error flag

 
 

-       usage:
+
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_NOWERR, &val);
 
          ioctl(fd, HDIO_GET_NOWERR, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the current ignore-write-error flag
+               The value of the current ignore-write-error flag

 
 
 
 
 
 

-HDIO_GET_DMA                   get use-dma flag

 
 

-       usage:
+
+HDIO_GET_DMA
+       get use-dma flag
+
+
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_DMA, &val);
 
          ioctl(fd, HDIO_GET_DMA, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the current use-dma flag
+               The value of the current use-dma flag

 
 
 
 
 
 

-HDIO_GET_NICE                  get nice flags

 
 

-       usage:
+
+HDIO_GET_NICE
+       get nice flags
+
+
+       usage::

 
          long nice;
 
          long nice;

+

          ioctl(fd, HDIO_GET_NICE, &nice);
 
          ioctl(fd, HDIO_GET_NICE, &nice);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

+               The drive's "nice" values.
+

 
 

-         The drive's "nice" values.

 
        notes:
 
        notes:

+               Per-drive flags which determine when the system will give more
+               bandwidth to other devices sharing the same IDE bus.

 
 

-         Per-drive flags which determine when the system will give more
-         bandwidth to other devices sharing the same IDE bus.
-         See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
+               See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.

 
 
 
 
 
 
 
 

-HDIO_SET_NICE                  set nice flags
+HDIO_SET_NICE
+       set nice flags

 
 

-       usage:
+
+       usage::

 
          unsigned long nice;
 
          unsigned long nice;

+

          ...
          ioctl(fd, HDIO_SET_NICE, nice);
 
        inputs:
          ...
          ioctl(fd, HDIO_SET_NICE, nice);
 
        inputs:

-         bitmask of nice flags.
+               bitmask of nice flags.
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error returns:
 
        error returns:

-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EPERM         Flags other than DSC_OVERLAP and NICE_1 set.
-         EPERM         DSC_OVERLAP specified but not supported by drive
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EPERM       Flags other than DSC_OVERLAP and NICE_1 set.
+         - EPERM       DSC_OVERLAP specified but not supported by drive

 
        notes:
 
        notes:

+               This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
+               provided by the user.

 
 

-         This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
-         provided by the user.
+               Nice flags are listed in <linux/hdreg.h>, starting with
+               IDE_NICE_DSC_OVERLAP.  These values represent shifts.

 
 

-         Nice flags are listed in <linux/hdreg.h>, starting with
-         IDE_NICE_DSC_OVERLAP.  These values represent shifts.

 
 
 
 
 
 
 
 

+HDIO_GET_WCACHE
+       get write cache mode on|off

 
 

-HDIO_GET_WCACHE                        get write cache mode on|off

 
 

-       usage:
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_WCACHE, &val);
 
          ioctl(fd, HDIO_GET_WCACHE, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the current write cache mode
+               The value of the current write cache mode

 
 
 
 
 
 

-HDIO_GET_ACOUSTIC              get acoustic value

 
 

-       usage:
+
+HDIO_GET_ACOUSTIC
+       get acoustic value
+
+
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_ACOUSTIC, &val);
 
          ioctl(fd, HDIO_GET_ACOUSTIC, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the current acoustic settings
+               The value of the current acoustic settings
+
+

 
        notes:
 
        notes:

+               See HDIO_SET_ACOUSTIC
+

 
 

-         See HDIO_SET_ACOUSTIC

 
 
 
 HDIO_GET_ADDRESS
 
 
 
 HDIO_GET_ADDRESS

+       usage::

 
 

-       usage:

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_GET_ADDRESS, &val);
 
          ioctl(fd, HDIO_GET_ADDRESS, &val);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         The value of the current addressing mode:
-           0 = 28-bit
-           1 = 48-bit
-           2 = 48-bit doing 28-bit
-           3 = 64-bit
+               The value of the current addressing mode:
+
+           =  ===================
+           0  28-bit
+           1  48-bit
+           2  48-bit doing 28-bit
+           3  64-bit
+           =  ===================

 
 
 
 
 
 

-HDIO_GET_BUSSTATE              get the bus state of the hwif
+HDIO_GET_BUSSTATE
+       get the bus state of the hwif

 
 

-       usage:
+
+       usage::

 
          long state;
 
          long state;

+

          ioctl(fd, HDIO_SCAN_HWIF, &state);
 
          ioctl(fd, HDIO_SCAN_HWIF, &state);
 

-       inputs:         none
+       inputs:
+               none
+
+

 
        outputs:
 
        outputs:

-         Current power state of the IDE bus.  One of BUSSTATE_OFF,
-         BUSSTATE_ON, or BUSSTATE_TRISTATE
+               Current power state of the IDE bus.  One of BUSSTATE_OFF,
+               BUSSTATE_ON, or BUSSTATE_TRISTATE

 
        error returns:
 
        error returns:

-         EACCES        Access denied:  requires CAP_SYS_ADMIN
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN

 
 
 
 
 
 
 
 

-HDIO_SET_BUSSTATE              set the bus state of the hwif
+HDIO_SET_BUSSTATE
+       set the bus state of the hwif

 
 

-       usage:
+
+       usage::

 
          int state;
 
          int state;

+

          ...
          ioctl(fd, HDIO_SCAN_HWIF, state);
 
        inputs:
          ...
          ioctl(fd, HDIO_SCAN_HWIF, state);
 
        inputs:

-         Desired IDE power state.  One of BUSSTATE_OFF, BUSSTATE_ON,
-         or BUSSTATE_TRISTATE
+               Desired IDE power state.  One of BUSSTATE_OFF, BUSSTATE_ON,
+               or BUSSTATE_TRISTATE
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error returns:
 
        error returns:

-         EACCES        Access denied:  requires CAP_SYS_RAWIO
-         EOPNOTSUPP    Hardware interface does not support bus power control
+         - EACCES      Access denied:  requires CAP_SYS_RAWIO
+         - EOPNOTSUPP  Hardware interface does not support bus power control
+

 
 
 
 
 
 

+HDIO_TRISTATE_HWIF
+       execute a channel tristate

 
 

-HDIO_TRISTATE_HWIF             execute a channel tristate

 
        Not implemented, as of 2.6.8.1.  See HDIO_SET_BUSSTATE
 
 
 
 
        Not implemented, as of 2.6.8.1.  See HDIO_SET_BUSSTATE
 
 
 

-HDIO_DRIVE_RESET               execute a device reset
+HDIO_DRIVE_RESET
+       execute a device reset
+

 
 

-       usage:
+       usage::

 
          int args[3]
 
          int args[3]

+

          ...
          ioctl(fd, HDIO_DRIVE_RESET, args);
 
          ...
          ioctl(fd, HDIO_DRIVE_RESET, args);
 

-       inputs:         none
+       inputs:
+               none
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error returns:
 
        error returns:

-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         ENXIO         No such device: phy dead or ctl_addr == 0
-         EIO           I/O error:      reset timed out or hardware error
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - ENXIO       No such device: phy dead or ctl_addr == 0
+         - EIO         I/O error:      reset timed out or hardware error

 
        notes:
 
 
        notes:
 

-         Execute a reset on the device as soon as the current IO
-         operation has completed.
+         - Execute a reset on the device as soon as the current IO
+           operation has completed.

 
 

-         Executes an ATAPI soft reset if applicable, otherwise
-         executes an ATA soft reset on the controller.
+         - Executes an ATAPI soft reset if applicable, otherwise
+           executes an ATA soft reset on the controller.

 
 
 
 
 
 

-HDIO_DRIVE_TASKFILE            execute raw taskfile
+HDIO_DRIVE_TASKFILE
+       execute raw taskfile

 
 

-       Note:  If you don't have a copy of the ANSI ATA specification
-       handy, you should probably ignore this ioctl.

 
 

-       Execute an ATA disk command directly by writing the "taskfile"
-       registers of the drive.  Requires ADMIN and RAWIO access
-       privileges.
+       Note:
+               If you don't have a copy of the ANSI ATA specification
+               handy, you should probably ignore this ioctl.
+
+       - Execute an ATA disk command directly by writing the "taskfile"
+         registers of the drive.  Requires ADMIN and RAWIO access
+         privileges.

 
 

-       usage:
+       usage::

 
          struct {
 
          struct {

+

            ide_task_request_t req_task;
            u8 outbuf[OUTPUT_SIZE];
            u8 inbuf[INPUT_SIZE];
            ide_task_request_t req_task;
            u8 outbuf[OUTPUT_SIZE];
            u8 inbuf[INPUT_SIZE];


@@ -548,6 +700,7 @@ HDIO_DRIVE_TASKFILE         execute raw taskfile
 
          (See below for details on memory area passed to ioctl.)
 
 
          (See below for details on memory area passed to ioctl.)
 

+         ============  ===================================================

          io_ports[8]   values to be written to taskfile registers
          hob_ports[8]  high-order bytes, for extended commands.
          out_flags     flags indicating which registers are valid
          io_ports[8]   values to be written to taskfile registers
          hob_ports[8]  high-order bytes, for extended commands.
          out_flags     flags indicating which registers are valid


@@ -557,24 +710,29 @@ HDIO_DRIVE_TASKFILE               execute raw taskfile
          out_size      size of output buffer
          outbuf        buffer of data to be transmitted to disk
          inbuf         buffer of data to be received from disk (see [1])
          out_size      size of output buffer
          outbuf        buffer of data to be transmitted to disk
          inbuf         buffer of data to be received from disk (see [1])

+         ============  ===================================================

 
        outputs:
 
 
        outputs:
 

+         ===========   ====================================================

          io_ports[]    values returned in the taskfile registers
          hob_ports[]   high-order bytes, for extended commands.
          out_flags     flags indicating which registers are valid (see [2])
          in_flags      flags indicating which registers should be returned
          outbuf        buffer of data to be transmitted to disk (see [1])
          inbuf         buffer of data to be received from disk
          io_ports[]    values returned in the taskfile registers
          hob_ports[]   high-order bytes, for extended commands.
          out_flags     flags indicating which registers are valid (see [2])
          in_flags      flags indicating which registers should be returned
          outbuf        buffer of data to be transmitted to disk (see [1])
          inbuf         buffer of data to be received from disk

+         ===========   ====================================================

 
        error returns:
 
        error returns:

-         EACCES        CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
-         ENOMSG        Device is not a disk drive.
-         ENOMEM        Unable to allocate memory for task
-         EFAULT        req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
-         EPERM         req_cmd == TASKFILE_MULTI_OUT and drive
-                       multi-count not yet set.
-         EIO           Drive failed the command.
+         - EACCES      CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set.
+         - ENOMSG      Device is not a disk drive.
+         - ENOMEM      Unable to allocate memory for task
+         - EFAULT      req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8)
+         - EPERM
+
+                       req_cmd == TASKFILE_MULTI_OUT and drive
+                       multi-count not yet set.
+         - EIO         Drive failed the command.

 
        notes:
 
 
        notes:
 


@@ -615,22 +773,25 @@ HDIO_DRIVE_TASKFILE               execute raw taskfile
          Command is passed to the disk drive via the ide_task_request_t
          structure, which contains these fields:
 
          Command is passed to the disk drive via the ide_task_request_t
          structure, which contains these fields:
 

+           ============        ===============================================

            io_ports[8]         values for the taskfile registers
            hob_ports[8]        high-order bytes, for extended commands
            out_flags           flags indicating which entries in the
            io_ports[8]         values for the taskfile registers
            hob_ports[8]        high-order bytes, for extended commands
            out_flags           flags indicating which entries in the

-                               io_ports[] and hob_ports[] arrays
+                               io_ports[] and hob_ports[] arrays

                                contain valid values.  Type ide_reg_valid_t.
            in_flags            flags indicating which entries in the
                                contain valid values.  Type ide_reg_valid_t.
            in_flags            flags indicating which entries in the

-                               io_ports[] and hob_ports[] arrays
+                               io_ports[] and hob_ports[] arrays

                                are expected to contain valid values
                                on return.
            data_phase          See below
            req_cmd             Command type, see below
            out_size            output (user->drive) buffer size, bytes
            in_size             input (drive->user) buffer size, bytes
                                are expected to contain valid values
                                on return.
            data_phase          See below
            req_cmd             Command type, see below
            out_size            output (user->drive) buffer size, bytes
            in_size             input (drive->user) buffer size, bytes

+           ============        ===============================================

 
          When out_flags is zero, the following registers are loaded.
 
 
          When out_flags is zero, the following registers are loaded.
 

+           ============        ===============================================

            HOB_FEATURE         If the drive supports LBA48
            HOB_NSECTOR         If the drive supports LBA48
            HOB_SECTOR          If the drive supports LBA48
            HOB_FEATURE         If the drive supports LBA48
            HOB_NSECTOR         If the drive supports LBA48
            HOB_SECTOR          If the drive supports LBA48


@@ -644,9 +805,11 @@ HDIO_DRIVE_TASKFILE                execute raw taskfile
            SELECT              First, masked with 0xE0 if LBA48, 0xEF
                                otherwise; then, or'ed with the default
                                value of SELECT.
            SELECT              First, masked with 0xE0 if LBA48, 0xEF
                                otherwise; then, or'ed with the default
                                value of SELECT.

+           ============        ===============================================

 
          If any bit in out_flags is set, the following registers are loaded.
 
 
          If any bit in out_flags is set, the following registers are loaded.
 

+           ============        ===============================================

            HOB_DATA            If out_flags.b.data is set.  HOB_DATA will
                                travel on DD8-DD15 on little endian machines
                                and on DD0-DD7 on big endian machines.
            HOB_DATA            If out_flags.b.data is set.  HOB_DATA will
                                travel on DD8-DD15 on little endian machines
                                and on DD0-DD7 on big endian machines.


@@ -664,6 +827,7 @@ HDIO_DRIVE_TASKFILE         execute raw taskfile
            HCYL                If out_flags.b.hcyl is set
            SELECT              Or'ed with the default value of SELECT and
                                loaded regardless of out_flags.b.select.
            HCYL                If out_flags.b.hcyl is set
            SELECT              Or'ed with the default value of SELECT and
                                loaded regardless of out_flags.b.select.

+           ============        ===============================================

 
          Taskfile registers are read back from the drive into
          {io|hob}_ports[] after the command completes iff one of the
 
          Taskfile registers are read back from the drive into
          {io|hob}_ports[] after the command completes iff one of the


@@ -674,6 +838,7 @@ HDIO_DRIVE_TASKFILE         execute raw taskfile
            2. One or more than one bits are set in out_flags.
            3. The requested data_phase is TASKFILE_NO_DATA.
 
            2. One or more than one bits are set in out_flags.
            3. The requested data_phase is TASKFILE_NO_DATA.
 

+           ============        ===============================================

            HOB_DATA            If in_flags.b.data is set.  It will contain
                                DD8-DD15 on little endian machines and
                                DD0-DD7 on big endian machines.
            HOB_DATA            If in_flags.b.data is set.  It will contain
                                DD8-DD15 on little endian machines and
                                DD0-DD7 on big endian machines.


@@ -689,10 +854,12 @@ HDIO_DRIVE_TASKFILE               execute raw taskfile
            SECTOR
            LCYL
            HCYL
            SECTOR
            LCYL
            HCYL

+           ============        ===============================================

 
          The data_phase field describes the data transfer to be
          performed.  Value is one of:
 
 
          The data_phase field describes the data transfer to be
          performed.  Value is one of:
 

+           ===================        ========================================

            TASKFILE_IN
            TASKFILE_MULTI_IN
            TASKFILE_OUT
            TASKFILE_IN
            TASKFILE_MULTI_IN
            TASKFILE_OUT


@@ -708,15 +875,18 @@ HDIO_DRIVE_TASKFILE               execute raw taskfile
            TASKFILE_P_OUT              unimplemented
            TASKFILE_P_OUT_DMA          unimplemented
            TASKFILE_P_OUT_DMAQ         unimplemented
            TASKFILE_P_OUT              unimplemented
            TASKFILE_P_OUT_DMA          unimplemented
            TASKFILE_P_OUT_DMAQ         unimplemented

+           ===================        ========================================

 
          The req_cmd field classifies the command type.  It may be
          one of:
 
 
          The req_cmd field classifies the command type.  It may be
          one of:
 

+           ========================    =======================================

            IDE_DRIVE_TASK_NO_DATA
            IDE_DRIVE_TASK_SET_XFER     unimplemented
            IDE_DRIVE_TASK_IN
            IDE_DRIVE_TASK_OUT          unimplemented
            IDE_DRIVE_TASK_RAW_WRITE
            IDE_DRIVE_TASK_NO_DATA
            IDE_DRIVE_TASK_SET_XFER     unimplemented
            IDE_DRIVE_TASK_IN
            IDE_DRIVE_TASK_OUT          unimplemented
            IDE_DRIVE_TASK_RAW_WRITE

+           ========================    =======================================

 
          [6] Do not access {in|out}_flags->all except for resetting
          all the bits.  Always access individual bit fields.  ->all
 
          [6] Do not access {in|out}_flags->all except for resetting
          all the bits.  Always access individual bit fields.  ->all


@@ -726,45 +896,57 @@ HDIO_DRIVE_TASKFILE               execute raw taskfile
 
 
 
 
 
 

-HDIO_DRIVE_CMD                 execute a special drive command
+HDIO_DRIVE_CMD
+       execute a special drive command
+

 
        Note:  If you don't have a copy of the ANSI ATA specification
        handy, you should probably ignore this ioctl.
 
 
        Note:  If you don't have a copy of the ANSI ATA specification
        handy, you should probably ignore this ioctl.
 

-       usage:
+       usage::

 
          u8 args[4+XFER_SIZE];
 
          u8 args[4+XFER_SIZE];

+

          ...
          ioctl(fd, HDIO_DRIVE_CMD, args);
 
        inputs:
          ...
          ioctl(fd, HDIO_DRIVE_CMD, args);
 
        inputs:

+           Commands other than WIN_SMART:

 
 

-         Commands other than WIN_SMART
+           =======     =======

            args[0]     COMMAND
            args[1]     NSECTOR
            args[2]     FEATURE
            args[3]     NSECTOR
            args[0]     COMMAND
            args[1]     NSECTOR
            args[2]     FEATURE
            args[3]     NSECTOR

+           =======     =======
+
+           WIN_SMART:

 
 

-         WIN_SMART
+           =======     =======

            args[0]     COMMAND
            args[1]     SECTOR
            args[2]     FEATURE
            args[3]     NSECTOR
            args[0]     COMMAND
            args[1]     SECTOR
            args[2]     FEATURE
            args[3]     NSECTOR

+           =======     =======

 
        outputs:
 
        outputs:

+               args[] buffer is filled with register values followed by any
+

 
 

-         args[] buffer is filled with register values followed by any

          data returned by the disk.
          data returned by the disk.

+
+           ========    ====================================================

            args[0]     status
            args[1]     error
            args[2]     NSECTOR
            args[3]     undefined
            args[4+]    NSECTOR * 512 bytes of data returned by the command.
            args[0]     status
            args[1]     error
            args[2]     NSECTOR
            args[3]     undefined
            args[4+]    NSECTOR * 512 bytes of data returned by the command.

+           ========    ====================================================

 
        error returns:
 
        error returns:

-         EACCES        Access denied:  requires CAP_SYS_RAWIO
-         ENOMEM        Unable to allocate memory for task
-         EIO           Drive reports error
+         - EACCES      Access denied:  requires CAP_SYS_RAWIO
+         - ENOMEM      Unable to allocate memory for task
+         - EIO         Drive reports error

 
        notes:
 
 
        notes:
 


@@ -789,20 +971,24 @@ HDIO_DRIVE_CMD                    execute a special drive command
 
 
 
 
 
 

-HDIO_DRIVE_TASK                        execute task and special drive command
+HDIO_DRIVE_TASK
+       execute task and special drive command
+

 
        Note:  If you don't have a copy of the ANSI ATA specification
        handy, you should probably ignore this ioctl.
 
 
        Note:  If you don't have a copy of the ANSI ATA specification
        handy, you should probably ignore this ioctl.
 

-       usage:
+       usage::

 
          u8 args[7];
 
          u8 args[7];

+

          ...
          ioctl(fd, HDIO_DRIVE_TASK, args);
 
        inputs:
          ...
          ioctl(fd, HDIO_DRIVE_TASK, args);
 
        inputs:

+           Taskfile register values:

 
 

-         Taskfile register values:
+           =======     =======

            args[0]     COMMAND
            args[1]     FEATURE
            args[2]     NSECTOR
            args[0]     COMMAND
            args[1]     FEATURE
            args[2]     NSECTOR


@@ -810,10 +996,13 @@ HDIO_DRIVE_TASK                   execute task and special drive command
            args[4]     LCYL
            args[5]     HCYL
            args[6]     SELECT
            args[4]     LCYL
            args[5]     HCYL
            args[6]     SELECT

+           =======     =======

 
        outputs:
 
        outputs:

+           Taskfile register values:
+

 
 

-         Taskfile register values:
+           =======     =======

            args[0]     status
            args[1]     error
            args[2]     NSECTOR
            args[0]     status
            args[1]     error
            args[2]     NSECTOR


@@ -821,12 +1010,13 @@ HDIO_DRIVE_TASK                  execute task and special drive command
            args[4]     LCYL
            args[5]     HCYL
            args[6]     SELECT
            args[4]     LCYL
            args[5]     HCYL
            args[6]     SELECT

+           =======     =======

 
        error returns:
 
        error returns:

-         EACCES        Access denied:  requires CAP_SYS_RAWIO
-         ENOMEM        Unable to allocate memory for task
-         ENOMSG        Device is not a disk drive.
-         EIO           Drive failed the command.
+         - EACCES      Access denied:  requires CAP_SYS_RAWIO
+         - ENOMEM      Unable to allocate memory for task
+         - ENOMSG      Device is not a disk drive.
+         - EIO         Drive failed the command.

 
        notes:
 
 
        notes:
 


@@ -836,236 +1026,317 @@ HDIO_DRIVE_TASK                        execute task and special drive command
 
 
 
 
 
 

-HDIO_DRIVE_CMD_AEB             HDIO_DRIVE_TASK
+HDIO_DRIVE_CMD_AEB
+       HDIO_DRIVE_TASK
+

 
        Not implemented, as of 2.6.8.1
 
 
 
 
        Not implemented, as of 2.6.8.1
 
 
 

-HDIO_SET_32BIT                 change io_32bit flags
+HDIO_SET_32BIT
+       change io_32bit flags
+

 
 

-       usage:
+       usage::

 
          int val;
 
          int val;

+

          ioctl(fd, HDIO_SET_32BIT, val);
 
        inputs:
          ioctl(fd, HDIO_SET_32BIT, val);
 
        inputs:

-         New value for io_32bit flag
+               New value for io_32bit flag
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 3]
-         EBUSY         Controller busy
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 3]
+         - EBUSY       Controller busy

 
 
 
 
 
 
 
 

-HDIO_SET_NOWERR                        change ignore-write-error flag
+HDIO_SET_NOWERR
+       change ignore-write-error flag

 
 

-       usage:
+
+       usage::

 
          int val;
 
          int val;

+

          ioctl(fd, HDIO_SET_NOWERR, val);
 
        inputs:
          ioctl(fd, HDIO_SET_NOWERR, val);
 
        inputs:

-         New value for ignore-write-error flag.  Used for ignoring
+               New value for ignore-write-error flag.  Used for ignoring
+
+

          WRERR_STAT
 
          WRERR_STAT
 

-       outputs:        none
+       outputs:
+               none
+
+

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 1]
-         EBUSY         Controller busy
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 1]
+         - EBUSY               Controller busy
+

 
 
 
 

+HDIO_SET_DMA
+       change use-dma flag

 
 

-HDIO_SET_DMA                   change use-dma flag

 
 

-       usage:
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_SET_DMA, val);
 
        inputs:
          ioctl(fd, HDIO_SET_DMA, val);
 
        inputs:

-         New value for use-dma flag
+               New value for use-dma flag
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 1]
-         EBUSY         Controller busy
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 1]
+         - EBUSY       Controller busy
+

 
 
 
 

+HDIO_SET_PIO_MODE
+       reconfig interface to new speed

 
 

-HDIO_SET_PIO_MODE              reconfig interface to new speed

 
 

-       usage:
+       usage::

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_SET_PIO_MODE, val);
 
        inputs:
          ioctl(fd, HDIO_SET_PIO_MODE, val);
 
        inputs:

-         New interface speed.
+               New interface speed.
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 255]
-         EBUSY         Controller busy
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 255]
+         - EBUSY       Controller busy
+

 
 
 
 

+HDIO_SCAN_HWIF
+       register and (re)scan interface

 
 

-HDIO_SCAN_HWIF                 register and (re)scan interface

 
 

-       usage:
+       usage::

 
          int args[3]
 
          int args[3]

+

          ...
          ioctl(fd, HDIO_SCAN_HWIF, args);
 
        inputs:
          ...
          ioctl(fd, HDIO_SCAN_HWIF, args);
 
        inputs:

+
+         =======       =========================

          args[0]       io address to probe
          args[0]       io address to probe

+
+

          args[1]       control address to probe
          args[2]       irq number
          args[1]       control address to probe
          args[2]       irq number

+         =======       =========================
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error returns:
 
        error returns:

-         EACCES        Access denied:  requires CAP_SYS_RAWIO
-         EIO           Probe failed.
+         - EACCES      Access denied:  requires CAP_SYS_RAWIO
+         - EIO         Probe failed.

 
        notes:
 
        notes:

+               This ioctl initializes the addresses and irq for a disk
+               controller, probes for drives, and creates /proc/ide
+               interfaces as appropriate.

 
 

-         This ioctl initializes the addresses and irq for a disk
-         controller, probes for drives, and creates /proc/ide
-         interfaces as appropriate.

 
 
 
 

+HDIO_UNREGISTER_HWIF
+       unregister interface

 
 

-HDIO_UNREGISTER_HWIF           unregister interface

 
 

-       usage:
+       usage::

 
          int index;
 
          int index;

+

          ioctl(fd, HDIO_UNREGISTER_HWIF, index);
 
        inputs:
          ioctl(fd, HDIO_UNREGISTER_HWIF, index);
 
        inputs:

-         index         index of hardware interface to unregister
+               index           index of hardware interface to unregister
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error returns:
 
        error returns:

-         EACCES        Access denied:  requires CAP_SYS_RAWIO
+         - EACCES      Access denied:  requires CAP_SYS_RAWIO

 
        notes:
 
        notes:

+               This ioctl removes a hardware interface from the kernel.

 
 

-         This ioctl removes a hardware interface from the kernel.
+               Currently (2.6.8) this ioctl silently fails if any drive on
+               the interface is busy.

 
 

-         Currently (2.6.8) this ioctl silently fails if any drive on
-         the interface is busy.

 
 
 
 

+HDIO_SET_WCACHE
+       change write cache enable-disable

 
 

-HDIO_SET_WCACHE                        change write cache enable-disable

 
 

-       usage:
+       usage::

 
          int val;
 
          int val;

+

          ioctl(fd, HDIO_SET_WCACHE, val);
 
        inputs:
          ioctl(fd, HDIO_SET_WCACHE, val);
 
        inputs:

-         New value for write cache enable
+               New value for write cache enable
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 1]
-         EBUSY         Controller busy
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 1]
+         - EBUSY       Controller busy
+

 
 
 
 

+HDIO_SET_ACOUSTIC
+       change acoustic behavior

 
 

-HDIO_SET_ACOUSTIC              change acoustic behavior

 
 

-       usage:
+       usage::

 
          int val;
 
          int val;

+

          ioctl(fd, HDIO_SET_ACOUSTIC, val);
 
        inputs:
          ioctl(fd, HDIO_SET_ACOUSTIC, val);
 
        inputs:

-         New value for drive acoustic settings
+               New value for drive acoustic settings
+
+
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 254]
-         EBUSY         Controller busy
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 254]
+         - EBUSY       Controller busy

 
 
 
 
 
 

-HDIO_SET_QDMA                  change use-qdma flag
+HDIO_SET_QDMA
+       change use-qdma flag
+

 
        Not implemented, as of 2.6.8.1
 
 
 
 
        Not implemented, as of 2.6.8.1
 
 
 

-HDIO_SET_ADDRESS               change lba addressing modes
+HDIO_SET_ADDRESS
+       change lba addressing modes
+

 
 

-       usage:
+       usage::

 
          int val;
 
          int val;

+

          ioctl(fd, HDIO_SET_ADDRESS, val);
 
        inputs:
          ioctl(fd, HDIO_SET_ADDRESS, val);
 
        inputs:

-         New value for addressing mode
-           0 = 28-bit
-           1 = 48-bit
-           2 = 48-bit doing 28-bit
+               New value for addressing mode
+
+           =   ===================
+           0   28-bit
+           1   48-bit
+           2   48-bit doing 28-bit
+           =   ===================
+
+       outputs:
+               none
+

 
 

-       outputs:        none

 
        error return:
 
        error return:

-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 2]
-         EBUSY         Controller busy
-         EIO           Drive does not support lba48 mode.
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 2]
+         - EBUSY               Controller busy
+         - EIO         Drive does not support lba48 mode.

 
 
 HDIO_SET_IDE_SCSI
 
 
 HDIO_SET_IDE_SCSI

+       usage::

 
 

-       usage:

 
          long val;
 
          long val;

+

          ioctl(fd, HDIO_SET_IDE_SCSI, val);
 
        inputs:
          ioctl(fd, HDIO_SET_IDE_SCSI, val);
 
        inputs:

-         New value for scsi emulation mode (?)
+               New value for scsi emulation mode (?)

 
 

-       outputs:        none

 
 

-       error return:
-         EINVAL        (bdev != bdev->bd_contains) (not sure what this means)
-         EACCES        Access denied:  requires CAP_SYS_ADMIN
-         EINVAL        value out of range [0 1]
-         EBUSY         Controller busy

 
 

+       outputs:
+               none

 
 
 
 

-HDIO_SET_SCSI_IDE

 
 

-       Not implemented, as of 2.6.8.1
+       error return:
+         - EINVAL      (bdev != bdev->bd_contains) (not sure what this means)
+         - EACCES      Access denied:  requires CAP_SYS_ADMIN
+         - EINVAL      value out of range [0 1]
+         - EBUSY       Controller busy

 
 
 
 

+
+HDIO_SET_SCSI_IDE
+       Not implemented, as of 2.6.8.1

diff --git a/Documentation/ioctl/index.rst b/Documentation/ioctl/index.rst
new file mode 100644 (file)
index 0000000..1a6f437
--- /dev/null
+++ b/Documentation/ioctl/index.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+======
+IOCTLs
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   ioctl-number
+
+   botching-up-ioctls
+   ioctl-decoding
+
+   cdrom
+   hdio

diff --git a/Documentation/ioctl/ioctl-decoding.txt b/Documentation/ioctl/ioctl-decoding.rst
similarity index 54%
rename from Documentation/ioctl/ioctl-decoding.txt
rename to Documentation/ioctl/ioctl-decoding.rst
index e35efb0cec2e64a99538d24c2c7c7b38846abc26..380d6bb3e3ea56faf320172d5266a095999ba86a 100644 (file)
--- a/Documentation/ioctl/ioctl-decoding.txt
+++ b/Documentation/ioctl/ioctl-decoding.rst
@@ -1,10 +1,16 @@
+==============================
+Decoding an IOCTL Magic Number
+==============================
+

 To decode a hex IOCTL code:
 
 Most architectures use this generic format, but check
 include/ARCH/ioctl.h for specifics, e.g. powerpc
 uses 3 bits to encode read/write and 13 bits for size.
 
 To decode a hex IOCTL code:
 
 Most architectures use this generic format, but check
 include/ARCH/ioctl.h for specifics, e.g. powerpc
 uses 3 bits to encode read/write and 13 bits for size.
 

- bits    meaning
+ ====== ==================================
+ bits   meaning
+ ====== ==================================

  31-30 00 - no parameters: uses _IO macro
        10 - read: _IOR
        01 - write: _IOW
  31-30 00 - no parameters: uses _IO macro
        10 - read: _IOR
        01 - write: _IOW


@@ -16,9 +22,10 @@ uses 3 bits to encode read/write and 13 bits for size.
        unique to each driver
 
  7-0   function #
        unique to each driver
 
  7-0   function #

+ ====== ==================================

 
 
 So for example 0x82187201 is a read with arg length of 0x218,
 
 
 So for example 0x82187201 is a read with arg length of 0x218,

-character 'r' function 1. Grepping the source reveals this is:
+character 'r' function 1. Grepping the source reveals this is::

 
 

-#define VFAT_IOCTL_READDIR_BOTH         _IOR('r', 1, struct dirent [2])
+       #define VFAT_IOCTL_READDIR_BOTH         _IOR('r', 1, struct dirent [2])

diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c
index 2263e3ddd8222bbc2732a2d93328edcd99de8842..42fb0d6d6034d80b4fc45394f5d95ceefa962f0d 100644 (file)
--- a/drivers/gpu/drm/drm_ioctl.c
+++ b/drivers/gpu/drm/drm_ioctl.c
@@ -730,7 +730,7 @@ static const struct drm_ioctl_desc drm_ioctls[] = {
  *     };
  *
  * Please make sure that you follow all the best practices from
  *     };
  *
  * Please make sure that you follow all the best practices from

- * ``Documentation/ioctl/botching-up-ioctls.txt``. Note that drm_ioctl()
+ * ``Documentation/ioctl/botching-up-ioctls.rst``. Note that drm_ioctl()

  * automatically zero-extends structures, hence make sure you can add more stuff
  * at the end, i.e. don't put a variable sized array there.
  *
  * automatically zero-extends structures, hence make sure you can add more stuff
  * at the end, i.e. don't put a variable sized array there.
  *