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>

Documentation/ioctl/botching-up-ioctls.txt → Documentation/ioctl/botching-up-ioctls.rst

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

Documentation/ioctl/cdrom.txt → Documentation/ioctl/cdrom.rst

-		Summary of CDROM ioctl calls.
-		============================
+============================
+Summary of CDROM 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 CDROM layer.  These are by-and-large implemented (as of Linux 2.6)
@@ -12,6 +13,7 @@ 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)
@@ -65,16 +67,13 @@ are as follows:
 	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:
 
@@ -91,266 +90,361 @@ General:
 	Unless otherwise specified, all data structures and constants
 	are defined in <linux/cdrom.h>
 
+------------------------------------------------------------------------------
 
 
+CDROMPAUSE
+	Pause Audio Operation
 
-CDROMPAUSE			Pause Audio Operation
 
-	usage:
+	usage::
 
 	  ioctl(fd, CDROMPAUSE, 0);
 
-	inputs:		none
 
-	outputs:	none
+	inputs:
+		none
+
+
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
+
 
+CDROMRESUME
+	Resume paused Audio Operation
 
-CDROMRESUME			Resume paused Audio Operation
 
-	usage:
+	usage::
 
 	  ioctl(fd, CDROMRESUME, 0);
 
-	inputs:		none
 
-	outputs:	none
+	inputs:
+		none
+
+
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
+
+
+CDROMPLAYMSF
+	Play Audio MSF
 
+	(struct cdrom_msf)
 
-CDROMPLAYMSF			Play Audio MSF (struct cdrom_msf)
 
-	usage:
+	usage::
 
 	  struct cdrom_msf msf;
+
 	  ioctl(fd, CDROMPLAYMSF, &msf);
 
 	inputs:
 		cdrom_msf structure, describing a segment of music to play
 
-	outputs:	none
+
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
 
 	notes:
-	  MSF stands for minutes-seconds-frames
-	  LBA stands for logical block address
+		- 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.
+
 
-	  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)
 
-CDROMPLAYTRKIND			Play Audio Track/index (struct cdrom_ti)
 
-	usage:
+	usage::
 
 	  struct cdrom_ti ti;
+
 	  ioctl(fd, CDROMPLAYTRKIND, &ti);
 
 	inputs:
 		cdrom_ti structure, describing a segment of music to play
 
-	outputs:	none
+
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
 
 	notes:
-	  Segment is described as start and end times, where each time
+		- 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)
+CDROMREADTOCHDR
+	Read TOC header
+
+	(struct cdrom_tochdr)
 
-	usage:
+
+	usage::
 
 	  cdrom_tochdr header;
+
 	  ioctl(fd, CDROMREADTOCHDR, &header);
 
 	inputs:
 		cdrom_tochdr structure
 
+
 	outputs:
 		cdrom_tochdr structure
 
+
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
 
 
 
-CDROMREADTOCENTRY		Read TOC entry (struct cdrom_tocentry)
+CDROMREADTOCENTRY
+	Read TOC entry
 
-	usage:
+	(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
+	  - 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
+		- TOC stands for Table Of Contents
+		- MSF stands for minutes-seconds-frames
+		- LBA stands for logical block address
 
 
 
-CDROMSTOP			Stop the cdrom drive
+CDROMSTOP
+	Stop the cdrom drive
 
-	usage:
+
+	usage::
 
 	  ioctl(fd, CDROMSTOP, 0);
 
-	inputs:		none
 
-	outputs:	none
+	inputs:
+		none
+
+
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
 
 	notes:
-	  Exact interpretation of this ioctl depends on the device,
+	  - Exact interpretation of this ioctl depends on the device,
 	    but most seem to spin the drive down.
 
 
-CDROMSTART			Start the cdrom drive
+CDROMSTART
+	Start the cdrom drive
+
 
-	usage:
+	usage::
 
 	  ioctl(fd, CDROMSTART, 0);
 
-	inputs:		none
 
-	outputs:	none
+	inputs:
+		none
+
+
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
 
 	notes:
-	  Exact interpretation of this ioctl depends on the device,
+	  - 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
+CDROMEJECT
+	- Ejects the cdrom media
 
-	usage:
+
+	usage::
 
 	  ioctl(fd, CDROMEJECT, 0);
 
-	inputs:		none
 
-	outputs:	none
+	inputs:
+		none
+
+
+	outputs:
+		none
+
 
 	error returns:
-	  ENOSYS	cd drive not capable of ejecting
-	  EBUSY		other processes are accessing drive, or door is locked
+	  - ENOSYS	cd drive not capable of ejecting
+	  - EBUSY	other processes are accessing drive, or door is locked
 
 	notes:
-	  See CDROM_LOCKDOOR, below.
+		- See CDROM_LOCKDOOR, below.
 
 
 
-CDROMCLOSETRAY			pendant of CDROMEJECT
 
-	usage:
+CDROMCLOSETRAY
+	pendant of CDROMEJECT
+
+
+	usage::
 
 	  ioctl(fd, CDROMCLOSETRAY, 0);
 
-	inputs:		none
 
-	outputs:	none
+	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
+	  - ENOSYS	cd drive not capable of closing the tray
+	  - EBUSY	other processes are accessing drive, or door is locked
 
 	notes:
-	  See CDROM_LOCKDOOR, below.
+		- See CDROM_LOCKDOOR, below.
 
 
 
-CDROMVOLCTRL			Control output volume (struct cdrom_volctrl)
 
-	usage:
+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
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
+
 
 
+CDROMVOLREAD
+	Get the drive's volume setting
 
-CDROMVOLREAD			Get the drive's volume setting
 	(struct cdrom_volctrl)
 
-	usage:
+
+	usage::
 
 	  struct cdrom_volctrl volume;
+
 	  ioctl(fd, CDROMVOLREAD, &volume);
 
-	inputs:		none
+	inputs:
+		none
+
 
 	outputs:
 		The current volume settings.
 
+
 	error return:
-	  ENOSYS	cd drive not audio-capable.
+	  - ENOSYS	cd drive not audio-capable.
 
 
 
-CDROMSUBCHNL			Read subchannel data (struct cdrom_subchnl)
+CDROMSUBCHNL
+	Read subchannel data
 
-	usage:
+	(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
+	  - ENOSYS	cd drive not audio-capable.
+	  - EINVAL	format not CDROM_MSF or CDROM_LBA
 
 	notes:
-	  Format is converted to CDROM_MSF or CDROM_LBA
+		- Format is converted to CDROM_MSF or CDROM_LBA
 		  as per user request on return
 
 
 
-CDROMREADRAW			read data in raw mode (2352 Bytes)
+CDROMREADRAW
+	read data in raw mode (2352 Bytes)
+
 	(struct cdrom_read)
 
-	usage:
+	usage::
 
 	  union {
+
 	    struct cdrom_msf msf;		/* input */
 	    char buffer[CD_FRAMESIZE_RAW];	/* return */
 	  } arg;
@@ -358,29 +452,33 @@ CDROMREADRAW			read data in raw mode (2352 Bytes)
 
 	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
+	  - 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
+		- 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:
+		- 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)
+CDROMREADMODE1
+	Read CDROM mode 1 data (2048 Bytes)
+
 	(struct cdrom_read)
 
 	notes:
@@ -389,7 +487,9 @@ CDROMREADMODE1			Read CDROM mode 1 data (2048 Bytes)
 
 
 
-CDROMREADMODE2			Read CDROM mode 2 data (2336 Bytes)
+CDROMREADMODE2
+	Read CDROM mode 2 data (2336 Bytes)
+
 	(struct cdrom_read)
 
 	notes:
@@ -398,11 +498,13 @@ CDROMREADMODE2			Read CDROM mode 2 data (2336 Bytes)
 
 
 
-CDROMREADAUDIO			(struct cdrom_read_audio)
+CDROMREADAUDIO
+	(struct cdrom_read_audio)
 
-	usage:
+	usage::
 
 	  struct cdrom_read_audio ra;
+
 	  ioctl(fd, CDROMREADAUDIO, &ra);
 
 	inputs:
@@ -412,42 +514,53 @@ CDROMREADAUDIO			(struct cdrom_read_audio)
 	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
+	  - 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
+CDROMEJECT_SW
+	enable(1)/disable(0) auto-ejecting
 
-	usage:
+
+	usage::
 
 	  int val;
+
 	  ioctl(fd, CDROMEJECT_SW, val);
 
 	inputs:
 		Flag specifying auto-eject flag.
 
-	outputs:	none
+
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	Drive is not capable of ejecting.
-	  EBUSY		Door is locked
+	  - ENOSYS	Drive is not capable of ejecting.
+	  - EBUSY	Door is locked
 
 
 
 
-CDROMMULTISESSION		Obtain the start-of-last-session
-				  address of multi session disks
+CDROMMULTISESSION
+	Obtain the start-of-last-session address of multi session disks
+
 	(struct cdrom_multisession)
-	usage:
+
+	usage::
 
 	  struct cdrom_multisession ms_info;
+
 	  ioctl(fd, CDROMMULTISESSION, &ms_info);
 
 	inputs:
 		cdrom_multisession structure containing desired
+
 	  format.
 
 	outputs:
@@ -455,27 +568,35 @@ CDROMMULTISESSION		Obtain the start-of-last-session
 		information.
 
 	error return:
-	  EINVAL	format not CDROM_MSF or CDROM_LBA
+	  - EINVAL	format not CDROM_MSF or CDROM_LBA
 
 
-CDROM_GET_MCN			Obtain the "Universal Product Code"
-				   if available (struct cdrom_mcn)
+CDROM_GET_MCN
+	Obtain the "Universal Product Code"
+	if available
+
+	(struct cdrom_mcn)
 
-	usage:
+
+	usage::
 
 	  struct cdrom_mcn mcn;
+
 	  ioctl(fd, CDROM_GET_MCN, &mcn);
 
-	inputs:		none
+	inputs:
+		none
+
 
 	outputs:
 		Universal Product Code
 
+
 	error return:
-	  ENOSYS	Drive is not capable of reading MCN data.
+	  - ENOSYS	Drive is not capable of reading MCN data.
 
 	notes:
-	  Source code comments state:
+		- Source code comments state::
 
 		    The following function is implemented, although very few
 		    audio discs give Universal Product Code information, which
@@ -486,89 +607,123 @@ CDROM_GET_MCN			Obtain the "Universal Product Code"
 
 
 
-CDROM_GET_UPC			CDROM_GET_MCN  (deprecated)
+CDROM_GET_UPC
+	CDROM_GET_MCN  (deprecated)
+
 
 	Not implemented, as of 2.6.8.1
 
 
 
-CDROMRESET			hard-reset the drive
+CDROMRESET
+	hard-reset the drive
+
 
-	usage:
+	usage::
 
 	  ioctl(fd, CDROMRESET, 0);
 
-	inputs:		none
 
-	outputs:	none
+	inputs:
+		none
+
+
+	outputs:
+		none
+
 
 	error return:
-	  EACCES	Access denied:  requires CAP_SYS_ADMIN
-	  ENOSYS	Drive is not capable of resetting.
+	  - EACCES	Access denied:  requires CAP_SYS_ADMIN
+	  - ENOSYS	Drive is not capable of resetting.
+
 
 
 
+CDROMREADCOOKED
+	read data in cooked mode
 
-CDROMREADCOOKED			read data in cooked mode
 
-	usage:
+	usage::
 
 	  u8 buffer[CD_FRAMESIZE]
+
 	  ioctl(fd, CDROMREADCOOKED, buffer);
 
-	inputs:		none
+	inputs:
+		none
+
 
 	outputs:
 		2048 bytes of data, "cooked" mode.
 
+
 	notes:
 		Not implemented on all drives.
 
 
 
 
-CDROMREADALL			read all 2646 bytes
+
+CDROMREADALL
+	read all 2646 bytes
+
 
 	Same as CDROMREADCOOKED, but reads 2646 bytes.
 
 
 
-CDROMSEEK			seek msf address
+CDROMSEEK
+	seek msf address
+
 
-	usage:
+	usage::
 
 	  struct cdrom_msf msf;
+
 	  ioctl(fd, CDROMSEEK, &msf);
 
 	inputs:
 		MSF address to seek to.
 
-	outputs:	none
+
+	outputs:
+		none
+
+
 
 
+CDROMPLAYBLK
+	scsi-cd only
 
-CDROMPLAYBLK			scsi-cd only, (struct cdrom_blk)
+	(struct cdrom_blk)
 
-	usage:
+
+	usage::
 
 	  struct cdrom_blk blk;
+
 	  ioctl(fd, CDROMPLAYBLK, &blk);
 
 	inputs:
 		Region to play
 
-	outputs:	none
 
+	outputs:
+		none
 
 
-CDROMGETSPINDOWN
 
-	usage:
+
+CDROMGETSPINDOWN
+	usage::
 
 	  char spindown;
+
 	  ioctl(fd, CDROMGETSPINDOWN, &spindown);
 
-	inputs:		none
+	inputs:
+		none
+
 
 	outputs:
 		The value of the current 4-bit spindown value.
@@ -576,162 +731,207 @@ CDROMGETSPINDOWN
 
 
 
-CDROMSETSPINDOWN
 
-	usage:
+CDROMSETSPINDOWN
+	usage::
 
 	  char spindown
+
 	  ioctl(fd, CDROMSETSPINDOWN, &spindown);
 
 	inputs:
 		4-bit value used to control spindown (TODO: more detail here)
 
-	outputs:	none
+
+	outputs:
+		none
+
 
 
 
 
 
-CDROM_SET_OPTIONS		Set behavior options
+CDROM_SET_OPTIONS
+	Set behavior options
 
-	usage:
+
+	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.
+	  - ENOSYS	selected option(s) not supported by drive.
+
 
 
 
+CDROM_CLEAR_OPTIONS
+	Clear behavior options
 
-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
+CDROM_SELECT_SPEED
+	Set the CD-ROM speed
+
 
-	usage:
+	usage::
 
 	  int speed;
+
 	  ioctl(fd, CDROM_SELECT_SPEED, speed);
 
 	inputs:
 		New drive speed.
 
-	outputs:	none
+
+	outputs:
+		none
+
 
 	error return:
-	  ENOSYS	speed selection not supported by drive.
+	  - ENOSYS	speed selection not supported by drive.
 
 
 
-CDROM_SELECT_DISC		Select disc (for juke-boxes)
+CDROM_SELECT_DISC
+	Select disc (for juke-boxes)
 
-	usage:
+
+	usage::
 
 	  int disk;
+
 	  ioctl(fd, CDROM_SELECT_DISC, disk);
 
 	inputs:
 		Disk to load into drive.
 
-	outputs:	none
+
+	outputs:
+		none
+
 
 	error return:
-	  EINVAL	Disk number beyond capacity of drive
+	  - EINVAL	Disk number beyond capacity of drive
 
 
 
-CDROM_MEDIA_CHANGED		Check is media changed
+CDROM_MEDIA_CHANGED
+	Check is media changed
 
-	usage:
+
+	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
+	  - 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.
 
-CDROM_DRIVE_STATUS		Get tray position, etc.
 
-	usage:
+	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
+	  - 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.
+CDROM_DISC_STATUS
+	Get disc type, etc.
 
-	usage:
+
+	usage::
 
 	  ioctl(fd, CDROM_DISC_STATUS, 0);
 
-	inputs:		none
+
+	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
+	    - 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:
+	    - 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
@@ -755,37 +955,53 @@ CDROM_DISC_STATUS		Get disc type, etc.
 
 
 
-CDROM_CHANGER_NSLOTS		Get number of slots
+CDROM_CHANGER_NSLOTS
+	Get number of slots
+
 
-	usage:
+	usage::
 
 	  ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
 
-	inputs:		none
+
+	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
+	error returns:
+		none
+
 
 
+CDROM_LOCKDOOR
+	lock or unlock door
 
-CDROM_LOCKDOOR			lock or unlock door
 
-	usage:
+	usage::
 
 	  int lock;
+
 	  ioctl(fd, CDROM_LOCKDOOR, lock);
 
 	inputs:
 		Door lock flag, 1=lock, 0=unlock
 
-	outputs:	none
+
+	outputs:
+		none
+
 
 	error returns:
-	  EDRIVE_CANT_DO_THIS	Door lock function not supported.
-	  EBUSY			Attempt to unlock when multiple users
+	  - 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:
@@ -798,31 +1014,41 @@ CDROM_LOCKDOOR			lock or unlock door
 
 
 
-CDROM_DEBUG			Turn debug messages on/off
+CDROM_DEBUG
+	Turn debug messages on/off
+
 
-	usage:
+	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
+	  - EACCES	Access denied:  requires CAP_SYS_ADMIN
 
 
 
-CDROM_GET_CAPABILITY		get capabilities
+CDROM_GET_CAPABILITY
+	get capabilities
 
-	usage:
+
+	usage::
 
 	  ioctl(fd, CDROM_GET_CAPABILITY, 0);
 
-	inputs:		none
+
+	inputs:
+		none
+
 
 	outputs:
 		The ioctl return value is the current device capability
@@ -830,37 +1056,45 @@ CDROM_GET_CAPABILITY		get capabilities
 
 
 
-CDROMAUDIOBUFSIZ		set the audio buffer size
+CDROMAUDIOBUFSIZ
+	set the audio buffer size
+
 
-	usage:
+	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.
+	  - ENOSYS	Not supported by this driver.
 
 	notes:
 		Not supported by all drivers.
 
 
 
+
 DVD_READ_STRUCT			Read structure
 
-	usage:
+	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,
@@ -868,18 +1102,22 @@ DVD_READ_STRUCT			Read structure
 	    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
+	  - EINVAL	physical.layer_num exceeds number of layers
+	  - EIO		Received invalid response from drive
 
 
 
@@ -891,75 +1129,103 @@ DVD_WRITE_STRUCT		Write structure
 
 DVD_AUTH			Authentication
 
-	usage:
+	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.
+	  - ENOTTY	ai.type not recognized.
+
 
 
+CDROM_SEND_PACKET
+	send a packet to the drive
 
-CDROM_SEND_PACKET		send a packet to the drive
 
-	usage:
+	usage::
 
 	  struct cdrom_generic_command cgc;
+
 	  ioctl(fd, CDROM_SEND_PACKET, &cgc);
 
 	inputs:
 		cdrom_generic_command structure containing the packet to send.
 
-	outputs:	none
+
+	outputs:
+		none
+
 	  cdrom_generic_command structure containing results.
 
 	error return:
-	  EIO		command failed.
-	  EPERM		Operation not permitted, either because a
+	  - 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
+	  - EINVAL
+
+			cgc.data_direction not set
 
 
 
-CDROM_NEXT_WRITABLE		get next writable block
+CDROM_NEXT_WRITABLE
+	get next writable block
 
-	usage:
+
+	usage::
 
 	  long next;
+
 	  ioctl(fd, CDROM_NEXT_WRITABLE, &next);
 
-	inputs:		none
+	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
+CDROM_LAST_WRITTEN
+	get last block written on disc
+
 
-	usage:
+	usage::
 
 	  long last;
+
 	  ioctl(fd, CDROM_LAST_WRITTEN, &last);
 
-	inputs:		none
+	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

Documentation/ioctl/hdio.txt → Documentation/ioctl/hdio.rst

-		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)
@@ -14,6 +15,7 @@ are as follows:
 
     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
@@ -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
+	=======================	=======================================
 
     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
@@ -57,16 +61,13 @@ are as follows:
 
 	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.
 
-
-
-
-
-
+------------------------------------------------------------------------------
 
 General:
 
@@ -80,35 +81,44 @@ General:
 	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;
+
 	  ioctl(fd, HDIO_GETGEO, &geom);
 
 
-	inputs:		none
+	inputs:
+		none
 
-	outputs:
 
+
+	outputs:
 		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.
+	    =========	==================================
 
 
 	error returns:
-	  EINVAL	if the device is not a disk drive or floppy drive,
+	  - EINVAL
+
+			if the device is not a disk drive or floppy drive,
 			or if the user passes a null pointer
 
 
 	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
@@ -128,49 +138,71 @@ HDIO_GETGEO			get device geometry
 
 
 
-HDIO_GET_UNMASKINTR		get current unmask setting
+HDIO_GET_UNMASKINTR
+	get current unmask setting
+
 
-	usage:
+	usage::
 
 	  long val;
+
 	  ioctl(fd, HDIO_GET_UNMASKINTR, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		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;
+
 	  ioctl(fd, HDIO_SET_UNMASKINTR, val);
 
 	inputs:
 		New value for unmask flag
 
-	outputs:	none
+
+
+	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
+	  - 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;
+
 	  ioctl(fd, HDIO_GET_MULTCOUNT, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		The value of the current IDE block mode setting.  This
@@ -179,79 +211,94 @@ HDIO_GET_MULTCOUNT		get current IDE blockmode setting
 
 
 
-HDIO_SET_MULTCOUNT		change IDE blockmode
+HDIO_SET_MULTCOUNT
+	change IDE blockmode
 
-	usage:
+
+	usage::
 
 	  int val;
+
 	  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.
 
-	outputs:	none
+	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 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:
-
-	  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
-	  EBUSY
+	  -EBUSY
 
 
 
-HDIO_GET_QDMA			get use-qdma flag
+HDIO_GET_QDMA
+	get use-qdma flag
+
 
 	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
 
 
 
-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.
 
 
 
-HDIO_GET_IDENTITY		get IDE identification info
+HDIO_GET_IDENTITY
+	get IDE identification info
+
 
-	usage:
+	usage::
 
 	  unsigned char identity[512];
+
 	  ioctl(fd, HDIO_GET_IDENTITY, identity);
 
-	inputs:		none
+	inputs:
+		none
 
-	outputs:
 
+
+	outputs:
 		ATA drive identity information.  For full description, see
 		the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
 		the ATA specification.
 
 	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:
-
 		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
@@ -261,133 +308,187 @@ HDIO_GET_IDENTITY		get IDE identification info
 
 
 
-HDIO_GET_KEEPSETTINGS		get keep-settings-on-reset flag
+HDIO_GET_KEEPSETTINGS
+	get keep-settings-on-reset flag
+
 
-	usage:
+	usage::
 
 	  long val;
+
 	  ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		The value of the current "keep settings" flag
 
-	notes:
 
+
+	notes:
 		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;
+
 	  ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
 
 	inputs:
 		New value for keep_settings flag
 
-	outputs:	none
+
+
+	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
+	  - 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;
+
 	  ioctl(fd, HDIO_GET_32BIT, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		The value of the current io_32bit setting
 
-	notes:
 
+
+	notes:
 		0=16-bit, 1=32-bit, 2,3 = 32bit+sync
 
 
 
-HDIO_GET_NOWERR			get ignore-write-error flag
 
-	usage:
+
+HDIO_GET_NOWERR
+	get ignore-write-error flag
+
+
+	usage::
 
 	  long val;
+
 	  ioctl(fd, HDIO_GET_NOWERR, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		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;
+
 	  ioctl(fd, HDIO_GET_DMA, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		The value of the current use-dma flag
 
 
 
-HDIO_GET_NICE			get nice flags
 
-	usage:
+
+HDIO_GET_NICE
+	get nice flags
+
+
+	usage::
 
 	  long nice;
+
 	  ioctl(fd, HDIO_GET_NICE, &nice);
 
-	inputs:		none
+	inputs:
+		none
+
 
-	outputs:
 
+	outputs:
 		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.
+
 		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;
+
 	  ...
 	  ioctl(fd, HDIO_SET_NICE, nice);
 
 	inputs:
 		bitmask of nice flags.
 
-	outputs:	none
+
+
+	outputs:
+		none
+
+
 
 	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:
-
 		This ioctl sets the DSC_OVERLAP and NICE_1 flags from values
 		provided by the user.
 
@@ -398,80 +499,113 @@ HDIO_SET_NICE			set nice flags
 
 
 
-HDIO_GET_WCACHE			get write cache mode on|off
+HDIO_GET_WCACHE
+	get write cache mode on|off
 
-	usage:
+
+	usage::
 
 	  long val;
+
 	  ioctl(fd, HDIO_GET_WCACHE, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		The value of the current write cache mode
 
 
 
-HDIO_GET_ACOUSTIC		get acoustic value
 
-	usage:
+
+HDIO_GET_ACOUSTIC
+	get acoustic value
+
+
+	usage::
 
 	  long val;
+
 	  ioctl(fd, HDIO_GET_ACOUSTIC, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		The value of the current acoustic settings
 
-	notes:
 
+
+	notes:
 		See HDIO_SET_ACOUSTIC
 
 
 
+
+
 HDIO_GET_ADDRESS
+	usage::
 
-	usage:
 
 	  long val;
+
 	  ioctl(fd, HDIO_GET_ADDRESS, &val);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		The value of the current addressing mode:
-	    0 = 28-bit
-	    1 = 48-bit
-	    2 = 48-bit doing 28-bit
-	    3 = 64-bit
+
+	    =  ===================
+	    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;
+
 	  ioctl(fd, HDIO_SCAN_HWIF, &state);
 
-	inputs:		none
+	inputs:
+		none
+
+
 
 	outputs:
 		Current power state of the IDE bus.  One of BUSSTATE_OFF,
 		BUSSTATE_ON, or BUSSTATE_TRISTATE
 
 	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;
+
 	  ...
 	  ioctl(fd, HDIO_SCAN_HWIF, state);
 
@@ -479,60 +613,78 @@ HDIO_SET_BUSSTATE		set the bus state of the hwif
 		Desired IDE power state.  One of BUSSTATE_OFF, BUSSTATE_ON,
 		or BUSSTATE_TRISTATE
 
-	outputs:	none
+	outputs:
+		none
+
+
 
 	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
 
 
 
-HDIO_DRIVE_RESET		execute a device reset
+HDIO_DRIVE_RESET
+	execute a device reset
+
 
-	usage:
+	usage::
 
 	  int args[3]
+
 	  ...
 	  ioctl(fd, HDIO_DRIVE_RESET, args);
 
-	inputs:		none
+	inputs:
+		none
+
+
+
+	outputs:
+		none
+
 
-	outputs:	none
 
 	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:
 
-	  Execute a reset on the device as soon as the current IO
+	  - 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 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
+
+	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"
+	- Execute an ATA disk command directly by writing the "taskfile"
 	  registers of the drive.  Requires ADMIN and RAWIO access
 	  privileges.
 
-	usage:
+	usage::
 
 	  struct {
+
 	    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.)
 
+	  ============	===================================================
 	  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])
+	  ============	===================================================
 
 	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
+	  ===========	====================================================
 
 	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
+	  - 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.
+	  - EIO		Drive failed the command.
 
 	notes:
 
@@ -615,6 +773,7 @@ HDIO_DRIVE_TASKFILE		execute raw taskfile
 	  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
@@ -628,9 +787,11 @@ HDIO_DRIVE_TASKFILE		execute raw taskfile
 	    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.
 
+	    ============	===============================================
 	    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.
+	    ============	===============================================
 
 	  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.
@@ -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.
+	    ============	===============================================
 
 	  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.
 
+	    ============	===============================================
 	    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
+	    ============	===============================================
 
 	  The data_phase field describes the data transfer to be
 	  performed.  Value is one of:
 
+	    ===================        ========================================
 	    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
+	    ===================        ========================================
 
 	  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
+	    ========================    =======================================
 
 	  [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.
 
-	usage:
+	usage::
 
 	  u8 args[4+XFER_SIZE];
+
 	  ...
 	  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
+	    =======     =======
 
-	  WIN_SMART
+	    WIN_SMART:
+
+	    =======     =======
 	    args[0]	COMMAND
 	    args[1]	SECTOR
 	    args[2]	FEATURE
 	    args[3]	NSECTOR
+	    =======     =======
 
 	outputs:
-
 		args[] buffer is filled with register values followed by any
+
+
 	  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.
+	    ========	====================================================
 
 	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:
 
@@ -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.
 
-	usage:
+	usage::
 
 	  u8 args[7];
+
 	  ...
 	  ioctl(fd, HDIO_DRIVE_TASK, args);
 
 	inputs:
-
 	    Taskfile register values:
+
+	    =======	=======
 	    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
+	    =======	=======
 
 	outputs:
-
 	    Taskfile register values:
+
+
+	    =======	=======
 	    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
+	    =======	=======
 
 	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:
 
@@ -836,138 +1026,189 @@ 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
 
 
 
-HDIO_SET_32BIT			change io_32bit flags
+HDIO_SET_32BIT
+	change io_32bit flags
 
-	usage:
+
+	usage::
 
 	  int val;
+
 	  ioctl(fd, HDIO_SET_32BIT, val);
 
 	inputs:
 		New value for io_32bit flag
 
-	outputs:	none
+
+
+	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 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;
+
 	  ioctl(fd, HDIO_SET_NOWERR, val);
 
 	inputs:
 		New value for ignore-write-error flag.  Used for ignoring
+
+
 	  WRERR_STAT
 
-	outputs:	none
+	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
+	  - 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;
+
 	  ioctl(fd, HDIO_SET_DMA, val);
 
 	inputs:
 		New value for use-dma flag
 
-	outputs:	none
+
+
+	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
+	  - 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;
+
 	  ioctl(fd, HDIO_SET_PIO_MODE, val);
 
 	inputs:
 		New interface speed.
 
-	outputs:	none
+
+
+	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 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]
+
 	  ...
 	  ioctl(fd, HDIO_SCAN_HWIF, args);
 
 	inputs:
+
+	  =======	=========================
 	  args[0]	io address to probe
+
+
 	  args[1]	control address to probe
 	  args[2]	irq number
+	  =======	=========================
+
+	outputs:
+		none
+
 
-	outputs:	none
 
 	error returns:
-	  EACCES	Access denied:  requires CAP_SYS_RAWIO
-	  EIO		Probe failed.
+	  - EACCES	Access denied:  requires CAP_SYS_RAWIO
+	  - EIO		Probe failed.
 
 	notes:
-
 		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;
+
 	  ioctl(fd, HDIO_UNREGISTER_HWIF, index);
 
 	inputs:
 		index		index of hardware interface to unregister
 
-	outputs:	none
+
+
+	outputs:
+		none
+
+
 
 	error returns:
-	  EACCES	Access denied:  requires CAP_SYS_RAWIO
+	  - EACCES	Access denied:  requires CAP_SYS_RAWIO
 
 	notes:
-
 		This ioctl removes a hardware interface from the kernel.
 
 		Currently (2.6.8) this ioctl silently fails if any drive on
@@ -975,97 +1216,127 @@ HDIO_UNREGISTER_HWIF		unregister interface
 
 
 
-HDIO_SET_WCACHE			change write cache enable-disable
+HDIO_SET_WCACHE
+	change write cache enable-disable
 
-	usage:
+
+	usage::
 
 	  int val;
+
 	  ioctl(fd, HDIO_SET_WCACHE, val);
 
 	inputs:
 		New value for write cache enable
 
-	outputs:	none
+
+
+	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
+	  - 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;
+
 	  ioctl(fd, HDIO_SET_ACOUSTIC, val);
 
 	inputs:
 		New value for drive acoustic settings
 
-	outputs:	none
+
+
+	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 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
 
 
 
-HDIO_SET_ADDRESS		change lba addressing modes
+HDIO_SET_ADDRESS
+	change lba addressing modes
 
-	usage:
+
+	usage::
 
 	  int val;
+
 	  ioctl(fd, HDIO_SET_ADDRESS, val);
 
 	inputs:
 		New value for addressing mode
-	    0 = 28-bit
-	    1 = 48-bit
-	    2 = 48-bit doing 28-bit
 
-	outputs:	none
+	    =   ===================
+	    0   28-bit
+	    1   48-bit
+	    2   48-bit doing 28-bit
+	    =   ===================
+
+	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 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
+	usage::
 
-	usage:
 
 	  long val;
+
 	  ioctl(fd, HDIO_SET_IDE_SCSI, val);
 
 	inputs:
 		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

Documentation/ioctl/index.rst

+:orphan:
+
+======
+IOCTLs
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   ioctl-number
+
+   botching-up-ioctls
+   ioctl-decoding
+
+   cdrom
+   hdio

Documentation/ioctl/ioctl-decoding.txt → Documentation/ioctl/ioctl-decoding.rst

+==============================
+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.
 
+ ====== ==================================
  bits   meaning
+ ====== ==================================
  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 #
+ ====== ==================================
 
 
 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])

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
- * ``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.
  *