From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> To: Linux Doc Mailing List <linux-doc@vger.kernel.org> Cc: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>, Mauro Carvalho Chehab <mchehab@infradead.org>, linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>, Maarten Lankhorst <maarten.lankhorst@linux.intel.com>, Maxime Ripard <maxime.ripard@bootlin.com>, Sean Paul <sean@poorly.run>, David Airlie <airlied@linux.ie>, Daniel Vetter <daniel@ffwll.ch>, dri-devel@lists.freedesktop.org Subject: [PATCH v2 65/79] docs: ioctl: convert to ReST Date: Mon, 22 Apr 2019 10:27:54 -0300 [thread overview] Message-ID: <3bc56b16284ce581b00400d49ab9e984ab714756.1555938376.git.mchehab+samsung@kernel.org> (raw) In-Reply-To: <cover.1555938375.git.mchehab+samsung@kernel.org> 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> --- ...g-up-ioctls.txt => botching-up-ioctls.rst} | 1 + Documentation/ioctl/cdrom.rst | 1233 +++++++++++++++++ Documentation/ioctl/cdrom.txt | 967 ------------- Documentation/ioctl/{hdio.txt => hdio.rst} | 835 +++++++---- Documentation/ioctl/index.rst | 16 + ...{ioctl-decoding.txt => ioctl-decoding.rst} | 13 +- drivers/gpu/drm/drm_ioctl.c | 2 +- 7 files changed, 1814 insertions(+), 1253 deletions(-) rename Documentation/ioctl/{botching-up-ioctls.txt => botching-up-ioctls.rst} (99%) create mode 100644 Documentation/ioctl/cdrom.rst delete mode 100644 Documentation/ioctl/cdrom.txt rename Documentation/ioctl/{hdio.txt => hdio.rst} (54%) create mode 100644 Documentation/ioctl/index.rst rename Documentation/ioctl/{ioctl-decoding.txt => ioctl-decoding.rst} (54%) 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 883fb034bd04..ac697fef3545 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.rst @@ -1,3 +1,4 @@ +================================= (How to avoid) Botching up ioctls ================================= diff --git a/Documentation/ioctl/cdrom.rst b/Documentation/ioctl/cdrom.rst new file mode 100644 index 000000000000..3b4c0506de46 --- /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 index a4d62a9d6771..000000000000 --- 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 18eb98c44ffe..e822e3dff176 100644 --- 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) @@ -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,459 +81,610 @@ 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: + 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. + ========= ================================== 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: + 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; + ioctl(fd, HDIO_GET_UNMASKINTR, &val); - inputs: none + inputs: + none + + 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; + ioctl(fd, HDIO_SET_UNMASKINTR, val); inputs: - New value for unmask flag + 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 - 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; + 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: - 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: - - ATA drive identity information. For full description, see - the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in - the ATA specification. + 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 + 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; + ioctl(fd, HDIO_GET_KEEPSETTINGS, &val); - inputs: none + inputs: + none + + outputs: - The value of the current "keep settings" flag + The value of the current "keep settings" flag + + 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; + 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: - 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 + The value of the current io_32bit setting + + 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 - 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 + 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 + 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: + The drive's "nice" values. + - The drive's "nice" values. 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; + ... ioctl(fd, HDIO_SET_NICE, nice); inputs: - bitmask of nice flags. + 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. - 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; + ioctl(fd, HDIO_GET_WCACHE, &val); - inputs: none + inputs: + none + + 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; + ioctl(fd, HDIO_GET_ACOUSTIC, &val); - inputs: none + inputs: + none + + outputs: - The value of the current acoustic settings + The value of the current acoustic settings + + notes: + See HDIO_SET_ACOUSTIC + - 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 + 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 - usage: +HDIO_GET_BUSSTATE + get the bus state of the hwif + + + 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 + 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); 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: - 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 - 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. - usage: + - Execute an ATA disk command directly by writing the "taskfile" + registers of the drive. Requires ADMIN and RAWIO access + privileges. + + 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 - 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: @@ -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: + ============ =============================================== 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 - 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 + ============ =============================================== 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 + - 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: - 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: - 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,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 -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 + 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 + 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 + 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. + 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. - 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 + 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. - 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; + 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: - 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 + 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 + New value for addressing mode + + = =================== + 0 28-bit + 1 48-bit + 2 48-bit doing 28-bit + = =================== + + 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 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 (?) + New value for scsi emulation mode (?) + + + + 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_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 index 000000000000..1a6f437566e3 --- /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 e35efb0cec2e..380d6bb3e3ea 100644 --- 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. - bits meaning + ====== ================================== + 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]) diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c index ce8a70875bd5..ae44a1a31d9f 100644 --- a/drivers/gpu/drm/drm_ioctl.c +++ b/drivers/gpu/drm/drm_ioctl.c @@ -720,7 +720,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. * -- 2.20.1
WARNING: multiple messages have this Message-ID (diff)
From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> To: Linux Doc Mailing List <linux-doc@vger.kernel.org> Cc: Jonathan Corbet <corbet@lwn.net>, Maxime Ripard <maxime.ripard@bootlin.com>, linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org, Mauro Carvalho Chehab <mchehab@infradead.org>, David Airlie <airlied@linux.ie>, Mauro Carvalho Chehab <mchehab+samsung@kernel.org>, Sean Paul <sean@poorly.run> Subject: [PATCH v2 65/79] docs: ioctl: convert to ReST Date: Mon, 22 Apr 2019 10:27:54 -0300 [thread overview] Message-ID: <3bc56b16284ce581b00400d49ab9e984ab714756.1555938376.git.mchehab+samsung@kernel.org> (raw) In-Reply-To: <cover.1555938375.git.mchehab+samsung@kernel.org> 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> --- ...g-up-ioctls.txt => botching-up-ioctls.rst} | 1 + Documentation/ioctl/cdrom.rst | 1233 +++++++++++++++++ Documentation/ioctl/cdrom.txt | 967 ------------- Documentation/ioctl/{hdio.txt => hdio.rst} | 835 +++++++---- Documentation/ioctl/index.rst | 16 + ...{ioctl-decoding.txt => ioctl-decoding.rst} | 13 +- drivers/gpu/drm/drm_ioctl.c | 2 +- 7 files changed, 1814 insertions(+), 1253 deletions(-) rename Documentation/ioctl/{botching-up-ioctls.txt => botching-up-ioctls.rst} (99%) create mode 100644 Documentation/ioctl/cdrom.rst delete mode 100644 Documentation/ioctl/cdrom.txt rename Documentation/ioctl/{hdio.txt => hdio.rst} (54%) create mode 100644 Documentation/ioctl/index.rst rename Documentation/ioctl/{ioctl-decoding.txt => ioctl-decoding.rst} (54%) 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 883fb034bd04..ac697fef3545 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.rst @@ -1,3 +1,4 @@ +================================= (How to avoid) Botching up ioctls ================================= diff --git a/Documentation/ioctl/cdrom.rst b/Documentation/ioctl/cdrom.rst new file mode 100644 index 000000000000..3b4c0506de46 --- /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 index a4d62a9d6771..000000000000 --- 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 18eb98c44ffe..e822e3dff176 100644 --- 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) @@ -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,459 +81,610 @@ 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: + 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. + ========= ================================== 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: + 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; + ioctl(fd, HDIO_GET_UNMASKINTR, &val); - inputs: none + inputs: + none + + 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; + ioctl(fd, HDIO_SET_UNMASKINTR, val); inputs: - New value for unmask flag + 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 - 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; + 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: - 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: - - ATA drive identity information. For full description, see - the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in - the ATA specification. + 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 + 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; + ioctl(fd, HDIO_GET_KEEPSETTINGS, &val); - inputs: none + inputs: + none + + outputs: - The value of the current "keep settings" flag + The value of the current "keep settings" flag + + 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; + 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: - 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 + The value of the current io_32bit setting + + 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 - 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 + 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 + 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: + The drive's "nice" values. + - The drive's "nice" values. 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; + ... ioctl(fd, HDIO_SET_NICE, nice); inputs: - bitmask of nice flags. + 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. - 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; + ioctl(fd, HDIO_GET_WCACHE, &val); - inputs: none + inputs: + none + + 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; + ioctl(fd, HDIO_GET_ACOUSTIC, &val); - inputs: none + inputs: + none + + outputs: - The value of the current acoustic settings + The value of the current acoustic settings + + notes: + See HDIO_SET_ACOUSTIC + - 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 + 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 - usage: +HDIO_GET_BUSSTATE + get the bus state of the hwif + + + 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 + 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); 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: - 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 - 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. - usage: + - Execute an ATA disk command directly by writing the "taskfile" + registers of the drive. Requires ADMIN and RAWIO access + privileges. + + 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 - 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: @@ -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: + ============ =============================================== 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 - 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 + ============ =============================================== 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 + - 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: - 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: - 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,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 -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 + 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 + 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 + 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. + 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. - 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 + 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. - 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; + 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: - 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 + 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 + New value for addressing mode + + = =================== + 0 28-bit + 1 48-bit + 2 48-bit doing 28-bit + = =================== + + 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 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 (?) + New value for scsi emulation mode (?) + + + + 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_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 index 000000000000..1a6f437566e3 --- /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 e35efb0cec2e..380d6bb3e3ea 100644 --- 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. - bits meaning + ====== ================================== + 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]) diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c index ce8a70875bd5..ae44a1a31d9f 100644 --- a/drivers/gpu/drm/drm_ioctl.c +++ b/drivers/gpu/drm/drm_ioctl.c @@ -720,7 +720,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. * -- 2.20.1 _______________________________________________ dri-devel mailing list dri-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/dri-devel
next prev parent reply other threads:[~2019-04-22 13:32 UTC|newest] Thread overview: 261+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-04-22 13:26 [PATCH v2 00/79] Convert files to ReST Mauro Carvalho Chehab 2019-04-22 13:26 ` Mauro Carvalho Chehab 2019-04-22 13:26 ` [PATCH v2 01/79] docs: core-api: fix broken references for div64.c and gcd.c Mauro Carvalho Chehab 2019-04-22 13:26 ` [PATCH v2 02/79] docs: trace: fix some Sphinx warnings Mauro Carvalho Chehab 2019-04-24 15:10 ` Steven Rostedt 2019-04-22 13:26 ` [PATCH v2 03/79] scripts/documentation-file-ref-check: don't parse Next/ dir Mauro Carvalho Chehab 2019-04-22 13:26 ` [PATCH v2 04/79] docs: aoe: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-22 13:26 ` [PATCH v2 05/79] docs: arm64: convert docs to ReST and rename to .rst Mauro Carvalho Chehab 2019-04-22 13:26 ` Mauro Carvalho Chehab 2019-04-22 13:26 ` [PATCH v2 06/79] docs: cdrom-standard.tex: convert from LaTeX to ReST Mauro Carvalho Chehab 2019-04-22 13:26 ` [PATCH v2 07/79] docs: cdrom: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-22 13:26 ` [PATCH v2 08/79] docs: cgroup-v1: " Mauro Carvalho Chehab 2019-04-22 13:26 ` Mauro Carvalho Chehab 2019-05-06 15:47 ` Tejun Heo 2019-05-06 15:47 ` Tejun Heo 2019-04-22 13:26 ` [PATCH v2 09/79] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler Mauro Carvalho Chehab 2019-04-22 13:26 ` [PATCH v2 10/79] docs: cpu-freq: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-23 8:21 ` Rafael J. Wysocki 2019-04-22 13:27 ` [PATCH v2 11/79] docs: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 12/79] docs: fault-injection: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 13/79] docs: fb: " Mauro Carvalho Chehab 2019-05-06 13:40 ` Bartlomiej Zolnierkiewicz 2019-05-06 13:40 ` Bartlomiej Zolnierkiewicz 2019-04-22 13:27 ` [PATCH v2 14/79] docs: fpga: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 15/79] docs: gpio: " Mauro Carvalho Chehab 2019-04-23 11:23 ` Linus Walleij 2019-04-23 12:36 ` Mauro Carvalho Chehab 2019-04-23 21:30 ` Linus Walleij 2019-04-22 13:27 ` [PATCH v2 16/79] docs: ide: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 17/79] docs: infiniband: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 18/79] docs: kbuild: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [Bridge] " Mauro Carvalho Chehab 2019-04-22 13:27 ` [OpenRISC] " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 19/79] docs: kdump: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 20/79] docs: livepatch: " Mauro Carvalho Chehab 2019-04-26 8:10 ` Petr Mladek 2019-04-26 9:04 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 21/79] docs: locking: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 22/79] docs: mic: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 23/79] docs: netlabel: " Mauro Carvalho Chehab 2019-04-22 18:10 ` Paul Moore 2019-04-22 13:27 ` [PATCH v2 24/79] docs: pcmcia: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 25/79] docs: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:48 ` Bjorn Helgaas 2019-04-22 14:07 ` Mauro Carvalho Chehab 2019-04-25 18:07 ` Mark Brown 2019-04-25 18:07 ` Mark Brown 2019-04-25 18:07 ` Mark Brown 2019-04-26 9:46 ` Mauro Carvalho Chehab 2019-04-26 9:46 ` Mauro Carvalho Chehab 2019-04-26 9:46 ` Mauro Carvalho Chehab 2019-04-27 17:25 ` Mark Brown 2019-04-27 17:25 ` Mark Brown 2019-04-27 17:25 ` Mark Brown 2019-04-27 18:13 ` Mauro Carvalho Chehab 2019-04-27 18:13 ` Mauro Carvalho Chehab 2019-04-27 18:13 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 26/79] docs: powerpc: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-24 1:15 ` Andrew Donnellan 2019-04-24 1:15 ` Andrew Donnellan 2019-04-24 1:15 ` Andrew Donnellan 2019-04-24 1:15 ` Andrew Donnellan 2019-04-22 13:27 ` [PATCH v2 27/79] docs: pps.txt: convert to ReST and rename to pps.rst Mauro Carvalho Chehab 2019-04-22 16:19 ` Rodolfo Giometti 2019-04-22 13:27 ` [PATCH v2 28/79] docs: ptp.txt: convert to ReST and move to driver-api Mauro Carvalho Chehab 2019-04-22 15:40 ` Richard Cochran 2019-04-22 13:27 ` [PATCH v2 29/79] docs: riscv: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 30/79] docs: Debugging390.txt: convert table to ascii artwork Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-23 16:12 ` Farhan Ali 2019-04-23 19:46 ` Mauro Carvalho Chehab 2019-04-24 11:41 ` Cornelia Huck 2019-04-24 12:30 ` Heiko Carstens 2019-04-24 12:44 ` Mauro Carvalho Chehab 2019-04-24 12:52 ` Cornelia Huck 2019-04-22 13:27 ` [PATCH v2 32/79] s390: include/asm/debug.h add kerneldoc markups Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 33/79] docs: serial: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 34/79] docs: target: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 35/79] docs: timers: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 36/79] docs: watchdog: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 37/79] docs: xilinx: convert eemi.txt to eemi.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 38/79] docs: scheduler: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-23 8:29 ` Peter Zijlstra 2019-04-23 10:32 ` Ingo Molnar 2019-04-23 11:19 ` Peter Zijlstra 2019-04-23 12:30 ` Ingo Molnar 2019-04-22 13:27 ` [PATCH v2 39/79] docs: EDID/HOWTO.txt: convert it and rename to howto.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 40/79] convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 41/79] docs: lcd-panel-cgram.txt: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 42/79] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 43/79] docs: m68k: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-05-03 11:55 ` Geert Uytterhoeven 2019-04-22 13:27 ` [PATCH v2 44/79] docs: cma/debugfs.txt: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 45/79] docs: console.txt: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-05-06 13:41 ` Bartlomiej Zolnierkiewicz 2019-05-06 13:41 ` Bartlomiej Zolnierkiewicz 2019-04-22 13:27 ` [PATCH v2 46/79] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 47/79] docs: early-userspace: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 48/79] docs: driver-model: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [Intel-wired-lan] " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 14:47 ` Julia Lawall 2019-04-22 14:47 ` [Intel-wired-lan] " Julia Lawall 2019-04-22 14:47 ` Julia Lawall 2019-04-22 22:30 ` Guenter Roeck 2019-04-22 22:30 ` [Intel-wired-lan] " Guenter Roeck 2019-04-22 13:27 ` [PATCH v2 49/79] docs: arm: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 50/79] docs: memory-devices: convert ti-emif.txt to ReST Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 51/79] docs: xen-tpmfront.txt: convert it to .rst Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 52/79] docs: bus-devices: ti-gpmc.rst: convert it to ReST Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 53/79] docs: nvmem: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 54/79] docs: phy: convert samsung-usb2.txt to ReST format Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 55/79] docs: rbtree.txt: fix Sphinx build warnings Mauro Carvalho Chehab [not found] ` <cover.1555938375.git.mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> 2019-04-22 13:27 ` [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab [not found] ` <cda57849a6462ccc72dcd360b30068ab6a1021c4.1555938376.git.mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> 2019-04-22 16:37 ` Logan Gunthorpe 2019-04-22 16:37 ` Logan Gunthorpe 2019-04-22 16:37 ` Logan Gunthorpe 2019-04-23 8:31 ` Peter Zijlstra 2019-04-23 8:31 ` Peter Zijlstra 2019-04-23 8:31 ` Peter Zijlstra [not found] ` <20190423083135.GA11158-Nxj+rRp3nVydTX5a5knrm8zTDFooKrT+cvkQGrU6aU0@public.gmane.org> 2019-04-23 12:55 ` Mike Snitzer 2019-04-23 12:55 ` Mike Snitzer 2019-04-23 12:55 ` Mike Snitzer [not found] ` <20190423125519.GA7104-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> 2019-04-23 13:01 ` Peter Zijlstra 2019-04-23 13:01 ` Peter Zijlstra 2019-04-23 13:01 ` Peter Zijlstra 2019-04-23 14:52 ` David Howells 2019-04-23 16:54 ` Jonathan Corbet 2019-04-23 17:12 ` Peter Zijlstra 2019-04-23 20:26 ` Mauro Carvalho Chehab 2019-04-24 11:51 ` Mike Rapoport 2019-04-24 11:51 ` Mike Rapoport 2019-04-24 12:57 ` Mauro Carvalho Chehab 2019-04-23 19:37 ` Mauro Carvalho Chehab [not found] ` <20190423130132.GT4038-Nxj+rRp3nVydTX5a5knrm8zTDFooKrT+cvkQGrU6aU0@public.gmane.org> 2019-04-23 13:21 ` Mike Snitzer 2019-04-23 13:21 ` Mike Snitzer 2019-04-23 13:21 ` Mike Snitzer [not found] ` <20190423132100.GB7132-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> 2019-04-23 15:07 ` Mauro Carvalho Chehab 2019-04-23 15:07 ` Mauro Carvalho Chehab 2019-04-23 15:07 ` Mauro Carvalho Chehab 2019-04-23 16:30 ` Jonathan Corbet 2019-04-23 16:30 ` Jonathan Corbet 2019-04-23 16:30 ` Jonathan Corbet [not found] ` <20190423103053.07cf2149-T1hC0tSOHrs@public.gmane.org> 2019-04-23 17:11 ` Peter Zijlstra 2019-04-23 17:11 ` Peter Zijlstra 2019-04-23 17:11 ` Peter Zijlstra [not found] ` <20190423171158.GG12232-Nxj+rRp3nVydTX5a5knrm8zTDFooKrT+cvkQGrU6aU0@public.gmane.org> 2019-04-23 17:20 ` Borislav Petkov 2019-04-23 17:20 ` Borislav Petkov 2019-04-23 17:20 ` Borislav Petkov [not found] ` <20190423172006.GD16353-Jj63ApZU6fQ@public.gmane.org> 2019-04-23 20:05 ` Mauro Carvalho Chehab 2019-04-23 20:05 ` Mauro Carvalho Chehab 2019-04-23 20:05 ` Mauro Carvalho Chehab [not found] ` <20190423170409.7b1370ac-qA1ZUp+OV9c@public.gmane.org> 2019-04-23 21:38 ` Borislav Petkov 2019-04-23 21:38 ` Borislav Petkov 2019-04-23 21:38 ` Borislav Petkov [not found] ` <20190423213816.GE16353-Jj63ApZU6fQ@public.gmane.org> 2019-04-23 22:06 ` Jonathan Corbet 2019-04-23 22:06 ` Jonathan Corbet 2019-04-23 22:06 ` Jonathan Corbet [not found] ` <20190423160640.70c9703f-T1hC0tSOHrs@public.gmane.org> 2019-04-24 9:19 ` Borislav Petkov 2019-04-24 9:19 ` Borislav Petkov 2019-04-24 9:19 ` Borislav Petkov 2019-04-24 6:52 ` Peter Zijlstra 2019-04-24 6:52 ` Peter Zijlstra 2019-04-24 6:52 ` Peter Zijlstra [not found] ` <20190424065209.GC4038-Nxj+rRp3nVydTX5a5knrm8zTDFooKrT+cvkQGrU6aU0@public.gmane.org> 2019-05-06 19:50 ` Mauro Carvalho Chehab 2019-05-06 19:50 ` Mauro Carvalho Chehab 2019-05-06 19:50 ` Mauro Carvalho Chehab 2019-04-24 10:40 ` Mauro Carvalho Chehab 2019-04-24 10:40 ` Mauro Carvalho Chehab 2019-04-24 10:40 ` Mauro Carvalho Chehab [not found] ` <20190423232325.679c100b-qA1ZUp+OV9c@public.gmane.org> 2019-04-24 14:54 ` Borislav Petkov 2019-04-24 14:54 ` Borislav Petkov 2019-04-24 14:54 ` Borislav Petkov [not found] ` <20190424145410.GE30142-Jj63ApZU6fQ@public.gmane.org> 2019-04-24 16:36 ` Mauro Carvalho Chehab 2019-04-24 16:36 ` Mauro Carvalho Chehab 2019-04-24 16:36 ` Mauro Carvalho Chehab 2019-04-23 17:53 ` Jonathan Corbet 2019-04-23 17:53 ` Jonathan Corbet 2019-04-23 17:53 ` Jonathan Corbet [not found] ` <20190423115349.589c3d50-T1hC0tSOHrs@public.gmane.org> 2019-04-23 18:21 ` Peter Zijlstra 2019-04-23 18:21 ` Peter Zijlstra 2019-04-23 18:21 ` Peter Zijlstra 2019-04-23 20:19 ` Mauro Carvalho Chehab 2019-04-23 20:19 ` Mauro Carvalho Chehab 2019-04-23 20:19 ` Mauro Carvalho Chehab [not found] ` <20190423171944.7ac6db54-qA1ZUp+OV9c@public.gmane.org> 2019-04-23 20:34 ` Jonathan Corbet 2019-04-23 20:34 ` Jonathan Corbet 2019-04-23 20:34 ` Jonathan Corbet 2019-04-23 17:13 ` Wes Turner 2019-04-23 17:13 ` Wes Turner 2019-04-23 17:13 ` Wes Turner [not found] ` <CACfEFw-viqBH7tDJ8t_um5erPFnRmzuztux86+3XR0+e=YcYYA-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org> 2019-04-23 17:41 ` Peter Zijlstra 2019-04-23 17:41 ` Peter Zijlstra 2019-04-23 17:41 ` Peter Zijlstra 2019-04-23 17:28 ` Wes Turner 2019-04-23 17:28 ` Wes Turner 2019-04-23 17:28 ` Wes Turner 2019-04-22 13:27 ` [PATCH v2 57/79] docs: accounting: convert to ReST Mauro Carvalho Chehab 2019-05-06 15:46 ` Tejun Heo 2019-04-22 13:27 ` [PATCH v2 58/79] docs: fmc: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 59/79] docs: hid: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [v2,59/79] " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 60/79] docs: ia64: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 61/79] docs: leds: " Mauro Carvalho Chehab 2019-04-23 19:00 ` Jacek Anaszewski 2019-04-22 13:27 ` [PATCH v2 62/79] docs: laptops: " Mauro Carvalho Chehab 2019-05-06 8:59 ` Andy Shevchenko 2019-04-22 13:27 ` [PATCH v2 63/79] docs: iio: " Mauro Carvalho Chehab 2019-04-22 14:25 ` Jonathan Cameron 2019-04-22 13:27 ` [PATCH v2 64/79] docs: ioctl-number.txt: convert it to ReST format Mauro Carvalho Chehab 2019-04-22 14:05 ` Doug Ledford 2019-04-22 14:17 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab [this message] 2019-04-22 13:27 ` [PATCH v2 65/79] docs: ioctl: convert to ReST Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 66/79] docs: namespaces: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 67/79] docs: nfc: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 68/79] docs: md: " Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 69/79] docs: mtd: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 70/79] docs: nvdimm: " Mauro Carvalho Chehab 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:28 ` [PATCH v2 71/79] docs: xtensa: " Mauro Carvalho Chehab 2019-04-22 13:28 ` [PATCH v2 72/79] docs: mmc: " Mauro Carvalho Chehab 2019-04-22 13:28 ` [PATCH v2 73/79] docs: sparc: " Mauro Carvalho Chehab 2019-04-22 13:28 ` Mauro Carvalho Chehab 2019-04-22 13:28 ` [PATCH v2 74/79] docs: thermal: " Mauro Carvalho Chehab 2019-04-22 13:28 ` Mauro Carvalho Chehab 2019-04-22 13:28 ` [PATCH v2 75/79] docs: rapidio: " Mauro Carvalho Chehab 2019-04-22 13:28 ` [PATCH v2 76/79] docs: blockdev: " Mauro Carvalho Chehab 2019-04-22 13:28 ` Mauro Carvalho Chehab 2019-04-22 13:28 ` mchehab+samsung 2019-04-22 13:28 ` [PATCH v2 77/79] docs: perf: " Mauro Carvalho Chehab 2019-04-22 13:28 ` Mauro Carvalho Chehab 2019-04-22 13:28 ` Mauro Carvalho Chehab 2019-04-22 13:28 ` [PATCH v2 78/79] docs: sysctl: " Mauro Carvalho Chehab 2019-04-22 13:28 ` [PATCH v2 79/79] docs: block: " Mauro Carvalho Chehab 2019-04-22 14:51 ` [PATCH v2 00/79] Convert files " Mauro Carvalho Chehab 2019-04-22 14:51 ` Mauro Carvalho Chehab
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=3bc56b16284ce581b00400d49ab9e984ab714756.1555938376.git.mchehab+samsung@kernel.org \ --to=mchehab+samsung@kernel.org \ --cc=airlied@linux.ie \ --cc=corbet@lwn.net \ --cc=daniel@ffwll.ch \ --cc=dri-devel@lists.freedesktop.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=maarten.lankhorst@linux.intel.com \ --cc=maxime.ripard@bootlin.com \ --cc=mchehab@infradead.org \ --cc=sean@poorly.run \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.