[ide] final polish on disk ioctl documentation

From: Edward Falk <efalk@google.com>
Signed-off-by: Bartlomiej Zolnierkiewicz <bzolnier@gmail.com>

Documentation/ioctl/cdrom.txt

@@ -34,7 +34,7 @@ are as follows:
 				  (struct cdrom_multisession)
 	CDROM_GET_MCN		Obtain the "Universal Product Code"
 				   if available (struct cdrom_mcn)
-	CDROM_GET_UPC		CDROM_GET_MCN  (deprecated)
+	CDROM_GET_UPC		Deprecated, use CDROM_GET_MCN instead.
 	CDROMRESET		hard-reset the drive
 	CDROMVOLREAD		Get the drive's volume setting
 					  (struct cdrom_volctrl)
@@ -44,8 +44,8 @@ are as follows:
 	CDROMSEEK		seek msf address
 	CDROMPLAYBLK		scsi-cd only, (struct cdrom_blk)
 	CDROMREADALL		read all 2646 bytes
-	CDROMGETSPINDOWN
-	CDROMSETSPINDOWN
+	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
@@ -79,10 +79,12 @@ 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.
+	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 EFAULT on a
-	failed attempt to copy data to or from user address space.
+	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.
 
@@ -136,6 +138,9 @@ CDROMPLAYMSF			Play Audio MSF (struct cdrom_msf)
 	  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.
@@ -196,8 +201,11 @@ CDROMREADTOCENTRY		Read TOC entry (struct cdrom_tocentry)
 	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
 
@@ -216,6 +224,10 @@ CDROMSTOP			Stop the cdrom drive
 	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
 
@@ -230,6 +242,11 @@ CDROMSTART			Start the cdrom drive
 	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
 
@@ -241,9 +258,12 @@ CDROMEJECT			Ejects the cdrom media
 
 	outputs:	none
 
-	error return:
+	error returns:
 	  ENOSYS	cd drive not capable of ejecting
-	  EBUSY		other processes have drive open or door is locked
+	  EBUSY		other processes are accessing drive, or door is locked
+
+	notes:
+	  See CDROM_LOCKDOOR, below.
 
 
 
@@ -257,9 +277,12 @@ CDROMCLOSETRAY			pendant of CDROMEJECT
 
 	outputs:	none
 
-	error return:
+	error returns:
 	  ENOSYS	cd drive not capable of ejecting
-	  EBUSY		other processes have drive open or door is locked
+	  EBUSY		other processes are accessing drive, or door is locked
+
+	notes:
+	  See CDROM_LOCKDOOR, below.
 
 
 
@@ -577,7 +600,7 @@ CDROM_SET_OPTIONS		Set behavior options
 
 	inputs:
 	  New values for drive options.  The logical 'or' of:
-	    CDO_AUTO_CLOSE	close tray on first open
+	    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
@@ -918,6 +941,10 @@ CDROM_NEXT_WRITABLE		get next writable block
 	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
@@ -925,11 +952,15 @@ CDROM_LAST_WRITTEN		get last block written on disc
 	usage:
 
 	  long last;
-	  ioctl(fd, CDROM_NEXT_WRITABLE, &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.

Documentation/ioctl/hdio.txt

@@ -28,7 +28,7 @@ are as follows:
 	HDIO_GET_IDENTITY	get IDE identification info
 	HDIO_GET_WCACHE		get write cache mode on|off
 	HDIO_GET_ACOUSTIC	get acoustic value
-	HDIO_GET_ADDRESS
+	HDIO_GET_ADDRESS	get sector addressing mode
 	HDIO_GET_BUSSTATE	get the bus state of the hwif
 	HDIO_TRISTATE_HWIF	execute a channel tristate
 	HDIO_DRIVE_RESET	execute a device reset
@@ -55,8 +55,8 @@ are as follows:
 	HDIO_SET_QDMA		change use-qdma flag
 	HDIO_SET_ADDRESS	change lba addressing modes
 
-	HDIO_SET_IDE_SCSI
-	HDIO_SET_SCSI_IDE
+	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
@@ -73,8 +73,9 @@ General:
 	Unless otherwise specified, all ioctl calls return 0 on success
 	and -1 with errno set to an appropriate value on error.
 
-	Unless otherwise specified, all ioctl calls return EFAULT on a
-	failed attempt to copy data to or from user address space.
+	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.
 
 	Unless otherwise specified, all data structures and constants
 	are defined in <linux/hdreg.h>
@@ -145,7 +146,7 @@ HDIO_SET_UNMASKINTR		permit other irqs during I/O
 
 	usage:
 
-	  long val;
+	  unsigned long val;
 	  ioctl(fd, HDIO_SET_UNMASKINTR, val);
 
 	inputs:
@@ -204,7 +205,7 @@ HDIO_SET_MULTCOUNT		change IDE blockmode
 
 	    This is tightly woven into the driver->do_special can not
 	    touch.  DON'T do it again until a total personality rewrite
-	    is committed."
+	    is committed.
 
 	  If blockmode has already been set, this ioctl will fail with
 	  EBUSY
@@ -371,14 +372,12 @@ HDIO_SET_NICE			set nice flags
 
 	usage:
 
-	  int nice;
+	  unsigned long nice;
 	  ...
 	  ioctl(fd, HDIO_SET_NICE, nice);
 
 	inputs:
-	  args[0]	io address to probe
-	  args[1]	control address to probe
-	  args[2]	irq number
+	  bitmask of nice flags.
 
 	outputs:	none
 
@@ -392,6 +391,9 @@ HDIO_SET_NICE			set nice flags
 	  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.
+
 
 
 
@@ -509,7 +511,7 @@ HDIO_DRIVE_RESET		execute a device reset
 
 	notes:
 
-	  Aborts any current command, prevent anything else from being
+	  Abort any current command, prevent anything else from being
 	  queued, execute a reset on the device, and issue BLKRRPART
 	  ioctl on the block device.
 
@@ -523,6 +525,10 @@ 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.
+
 	usage:
 
 	  struct {
@@ -541,27 +547,27 @@ HDIO_DRIVE_TASKFILE		execute raw taskfile
 
 	  (See below for details on memory area passed to ioctl.)
 
-	  io_ports[]	values to be written to taskfile registers
-	  hob_ports[]	values to be written to taskfile registers
+	  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
 	  in_flags	flags indicating which registers should be returned
 	  data_phase	see below
 	  req_cmd	command type to be executed
 	  out_size	size of output buffer
 	  outbuf	buffer of data to be transmitted to disk
-	  inbuf		buffer of data to be received from disk
+	  inbuf		buffer of data to be received from disk (see [1])
 
 	outputs:
 
 	  io_ports[]	values returned in the taskfile registers
-	  hob_ports[]	values returned in the taskfile registers
-	  out_flags	flags indicating which registers are valid
+	  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
+	  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 privelege not set.
+	  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)
@@ -571,9 +577,14 @@ HDIO_DRIVE_TASKFILE		execute raw taskfile
 
 	notes:
 
-	  Execute an ATA disk command directly by writing the "taskfile"
-	  registers of the drive.  Requires ADMIN and RAWIO access
-	  privileges.
+	  [1] Currently (2.6.8), both the input and output buffers are
+	  copied from the user and written back to the user, even when
+	  not used.  This may be a bug.
+
+	  [2] The out_flags and in_flags are returned to the user after
+	  the ioctl completes.	Currently (2.6.8) these are the same
+	  as the input values, unchanged.  In the future, they may have
+	  more significance.
 
 	  Extreme caution should be used with using this ioctl.  A
 	  mistake can easily corrupt data or hang the system.
@@ -590,7 +601,7 @@ HDIO_DRIVE_TASKFILE		execute raw taskfile
 	    hob_ports[8]	high-order bytes, for extended commands
 	    out_flags		flags indicating which entries in the
 	    			io_ports[] and hob_ports[] arrays
-				contain valid values.
+				contain valid values.  Type ide_reg_valid_t.
 	    in_flags		flags indicating which entries in the
 	    			io_ports[] and hob_ports[] arrays
 				are expected to contain valid values
@@ -600,8 +611,11 @@ HDIO_DRIVE_TASKFILE		execute raw taskfile
 	    out_size		output (user->drive) buffer size, bytes
 	    in_size		input (drive->user) buffer size, bytes
 
-	  Unused fields of io_ports[] and hob_ports[] should be set to
-	  zero.
+	  This ioctl does not necessarily respect all flags in the
+	  out_flags and in_flags values -- some taskfile registers
+	  may be written or read even if not requested in the flags.
+	  Unused fields of io_ports[] and hob_ports[] should be set
+	  to zero.
 
 	  The data_phase field describes the data transfer to be
 	  performed.  Value is one of:
@@ -631,10 +645,6 @@ HDIO_DRIVE_TASKFILE		execute raw taskfile
 	    IDE_DRIVE_TASK_OUT
 	    IDE_DRIVE_TASK_RAW_WRITE
 
-	  Currently (2.6.8), both the input and output buffers are
-	  copied from the user and written back to the user, even when
-	  not used.
-
 
 
 
@@ -666,11 +676,17 @@ HDIO_DRIVE_CMD			execute a special drive 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:
 	  EACCES	Access denied:  requires CAP_SYS_RAWIO
 	  ENOMEM	Unable to allocate memory for task
 
+	notes:
+
+	  Taskfile registers IDE_LCYL, IDE_HCYL, and IDE_SELECT are
+	  set to zero before executing the command.