Mark Yao <markyao0591@gmail.com> <mark.yao@rock-chips.com>
Martin Kepplinger <martink@posteo.de> <martin.kepplinger@theobroma-systems.com>
Martin Kepplinger <martink@posteo.de> <martin.kepplinger@ginzinger.com>
+Martin Kepplinger <martink@posteo.de> <martin.kepplinger@puri.sm>
Mathieu Othacehe <m.othacehe@gmail.com>
Matthew Wilcox <willy@infradead.org> <matthew.r.wilcox@intel.com>
Matthew Wilcox <willy@infradead.org> <matthew@wil.cx>
N: Martin Kepplinger
E: martink@posteo.de
-E: martin.kepplinger@ginzinger.com
+E: martin.kepplinger@puri.sm
W: http://www.martinkepplinger.com
+P: 4096R/5AB387D3 F208 2B88 0F9E 4239 3468 6E3F 5003 98DF 5AB3 87D3
D: mma8452 accelerators iio driver
D: pegasus_notetaker input driver
D: Kernel fixes and cleanups
SPHINXBUILD = sphinx-build
SPHINXOPTS =
SPHINXDIRS = .
-_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
+_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))
SPHINX_CONF = conf.py
PAPER =
BUILDDIR = $(obj)/output
else # HAVE_SPHINX
-export SPHINXOPTS = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while (<IN>) { if (m/([\d\.]+)/) { print "-jauto" if ($$1 >= "1.7") } ;} close IN')
+export SPHINX_PARALLEL = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while (<IN>) { if (m/([\d\.]+)/) { print "auto" if ($$1 >= "1.7") } ;} close IN')
# User-friendly check for pdflatex and latexmk
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
PYTHONDONTWRITEBYTECODE=1 \
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
$(SPHINXBUILD) \
+ -j $(shell python $(srctree)/scripts/jobserver-count $(SPHINX_PARALLEL)) \
-b $2 \
-c $(abspath $(srctree)/$(src)) \
-d $(abspath $(BUILDDIR)/.doctrees/$3) \
spawning semantics in the application (e.g. by using a privileged helper program
to do process spawning and UID/GID transitions). Unfortunately, there are a
number of semantics around process spawning that would be affected by this, such
-as fork() calls where the program doesn???t immediately call exec() after the
+as fork() calls where the program doesn't immediately call exec() after the
fork(), parent processes specifying custom environment variables or command line
args for spawned child processes, or inheritance of file handles across a
fork()/exec(). Because of this, as solution that uses a privileged helper in
initial system user namespace, affectively preventing privilege escalation.
Unfortunately, it is not generally feasible to use user namespaces in isolation,
without pairing them with other namespace types, which is not always an option.
-Linux checks for capabilities based off of the user namespace that ???owns??? some
+Linux checks for capabilities based off of the user namespace that "owns" some
entity. For example, Linux has the notion that network namespaces are owned by
the user namespace in which they were created. A consequence of this is that
capability checks for access to a given network namespace are done by checking
Best-effort memory protection. If the memory usage of a
cgroup is within its effective low boundary, the cgroup's
- memory won't be reclaimed unless memory can be reclaimed
- from unprotected cgroups. Above the effective low boundary (or
+ memory won't be reclaimed unless there is no reclaimable
+ memory available in unprotected cgroups.
+ Above the effective low boundary (or
effective min boundary if it is higher), pages are reclaimed
proportionally to the overage, reducing reclaim pressure for
smaller overages.
It accepts only the following input values when written to.
- "root" - a paritition root
+ "root" - a partition root
"member" - a non-root member of a partition
When set to be a partition root, the current cgroup is the
--- /dev/null
+=========================================\r
+Dell Remote BIOS Update driver (dell_rbu)\r
+=========================================\r
+
+Purpose
+=======
+
+Document demonstrating the use of the Dell Remote BIOS Update driver
+for updating BIOS images on Dell servers and desktops.
+
+Scope
+=====
+
+This document discusses the functionality of the rbu driver only.
+It does not cover the support needed from applications to enable the BIOS to
+update itself with the image downloaded in to the memory.
+
+Overview
+========
+
+This driver works with Dell OpenManage or Dell Update Packages for updating
+the BIOS on Dell servers (starting from servers sold since 1999), desktops
+and notebooks (starting from those sold in 2005).
+
+Please go to http://support.dell.com register and you can find info on
+OpenManage and Dell Update packages (DUP).
+
+Libsmbios can also be used to update BIOS on Dell systems go to
+http://linux.dell.com/libsmbios/ for details.
+
+Dell_RBU driver supports BIOS update using the monolithic image and packetized
+image methods. In case of monolithic the driver allocates a contiguous chunk
+of physical pages having the BIOS image. In case of packetized the app
+using the driver breaks the image in to packets of fixed sizes and the driver
+would place each packet in contiguous physical memory. The driver also
+maintains a link list of packets for reading them back.
+
+If the dell_rbu driver is unloaded all the allocated memory is freed.
+
+The rbu driver needs to have an application (as mentioned above) which will
+inform the BIOS to enable the update in the next system reboot.
+
+The user should not unload the rbu driver after downloading the BIOS image
+or updating.
+
+The driver load creates the following directories under the /sys file system::
+
+ /sys/class/firmware/dell_rbu/loading
+ /sys/class/firmware/dell_rbu/data
+ /sys/devices/platform/dell_rbu/image_type
+ /sys/devices/platform/dell_rbu/data
+ /sys/devices/platform/dell_rbu/packet_size
+
+The driver supports two types of update mechanism; monolithic and packetized.
+These update mechanism depends upon the BIOS currently running on the system.
+Most of the Dell systems support a monolithic update where the BIOS image is
+copied to a single contiguous block of physical memory.
+
+In case of packet mechanism the single memory can be broken in smaller chunks
+of contiguous memory and the BIOS image is scattered in these packets.
+
+By default the driver uses monolithic memory for the update type. This can be
+changed to packets during the driver load time by specifying the load
+parameter image_type=packet. This can also be changed later as below::
+
+ echo packet > /sys/devices/platform/dell_rbu/image_type
+
+In packet update mode the packet size has to be given before any packets can
+be downloaded. It is done as below::
+
+ echo XXXX > /sys/devices/platform/dell_rbu/packet_size
+
+In the packet update mechanism, the user needs to create a new file having
+packets of data arranged back to back. It can be done as follows:
+The user creates packets header, gets the chunk of the BIOS image and
+places it next to the packetheader; now, the packetheader + BIOS image chunk
+added together should match the specified packet_size. This makes one
+packet, the user needs to create more such packets out of the entire BIOS
+image file and then arrange all these packets back to back in to one single
+file.
+
+This file is then copied to /sys/class/firmware/dell_rbu/data.
+Once this file gets to the driver, the driver extracts packet_size data from
+the file and spreads it across the physical memory in contiguous packet_sized
+space.
+
+This method makes sure that all the packets get to the driver in a single operation.
+
+In monolithic update the user simply get the BIOS image (.hdr file) and copies
+to the data file as is without any change to the BIOS image itself.
+
+Do the steps below to download the BIOS image.
+
+1) echo 1 > /sys/class/firmware/dell_rbu/loading
+2) cp bios_image.hdr /sys/class/firmware/dell_rbu/data
+3) echo 0 > /sys/class/firmware/dell_rbu/loading
+
+The /sys/class/firmware/dell_rbu/ entries will remain till the following is
+done.
+
+::
+
+ echo -1 > /sys/class/firmware/dell_rbu/loading
+
+Until this step is completed the driver cannot be unloaded.
+
+Also echoing either mono, packet or init in to image_type will free up the
+memory allocated by the driver.
+
+If a user by accident executes steps 1 and 3 above without executing step 2;
+it will make the /sys/class/firmware/dell_rbu/ entries disappear.
+
+The entries can be recreated by doing the following::
+
+ echo init > /sys/devices/platform/dell_rbu/image_type
+
+.. note:: echoing init in image_type does not change its original value.
+
+Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to
+read back the image downloaded.
+
+.. note::
+
+ After updating the BIOS image a user mode application needs to execute
+ code which sends the BIOS update request to the BIOS. So on the next reboot
+ the BIOS knows about the new image downloaded and it updates itself.
+ Also don't unload the rbu driver if the image has to be updated.
+
--- /dev/null
+dm-dust
+=======
+
+This target emulates the behavior of bad sectors at arbitrary
+locations, and the ability to enable the emulation of the failures
+at an arbitrary time.
+
+This target behaves similarly to a linear target. At a given time,
+the user can send a message to the target to start failing read
+requests on specific blocks (to emulate the behavior of a hard disk
+drive with bad sectors).
+
+When the failure behavior is enabled (i.e.: when the output of
+"dmsetup status" displays "fail_read_on_bad_block"), reads of blocks
+in the "bad block list" will fail with EIO ("Input/output error").
+
+Writes of blocks in the "bad block list will result in the following:
+
+1. Remove the block from the "bad block list".
+2. Successfully complete the write.
+
+This emulates the "remapped sector" behavior of a drive with bad
+sectors.
+
+Normally, a drive that is encountering bad sectors will most likely
+encounter more bad sectors, at an unknown time or location.
+With dm-dust, the user can use the "addbadblock" and "removebadblock"
+messages to add arbitrary bad blocks at new locations, and the
+"enable" and "disable" messages to modulate the state of whether the
+configured "bad blocks" will be treated as bad, or bypassed.
+This allows the pre-writing of test data and metadata prior to
+simulating a "failure" event where bad sectors start to appear.
+
+Table parameters
+----------------
+<device_path> <offset> <blksz>
+
+Mandatory parameters:
+ <device_path>:
+ Path to the block device.
+
+ <offset>:
+ Offset to data area from start of device_path
+
+ <blksz>:
+ Block size in bytes
+
+ (minimum 512, maximum 1073741824, must be a power of 2)
+
+Usage instructions
+------------------
+
+First, find the size (in 512-byte sectors) of the device to be used::
+
+ $ sudo blockdev --getsz /dev/vdb1
+ 33552384
+
+Create the dm-dust device:
+(For a device with a block size of 512 bytes)
+
+::
+
+ $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512'
+
+(For a device with a block size of 4096 bytes)
+
+::
+
+ $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096'
+
+Check the status of the read behavior ("bypass" indicates that all I/O
+will be passed through to the underlying device)::
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 bypass
+
+ $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct
+ 128+0 records in
+ 128+0 records out
+
+ $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
+ 128+0 records in
+ 128+0 records out
+
+Adding and removing bad blocks
+------------------------------
+
+At any time (i.e.: whether the device has the "bad block" emulation
+enabled or disabled), bad blocks may be added or removed from the
+device via the "addbadblock" and "removebadblock" messages::
+
+ $ sudo dmsetup message dust1 0 addbadblock 60
+ kernel: device-mapper: dust: badblock added at block 60
+
+ $ sudo dmsetup message dust1 0 addbadblock 67
+ kernel: device-mapper: dust: badblock added at block 67
+
+ $ sudo dmsetup message dust1 0 addbadblock 72
+ kernel: device-mapper: dust: badblock added at block 72
+
+These bad blocks will be stored in the "bad block list".
+While the device is in "bypass" mode, reads and writes will succeed::
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 bypass
+
+Enabling block read failures
+----------------------------
+
+To enable the "fail read on bad block" behavior, send the "enable" message::
+
+ $ sudo dmsetup message dust1 0 enable
+ kernel: device-mapper: dust: enabling read failures on bad sectors
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 fail_read_on_bad_block
+
+With the device in "fail read on bad block" mode, attempting to read a
+block will encounter an "Input/output error"::
+
+ $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct
+ dd: error reading '/dev/mapper/dust1': Input/output error
+ 0+0 records in
+ 0+0 records out
+ 0 bytes copied, 0.00040651 s, 0.0 kB/s
+
+...and writing to the bad blocks will remove the blocks from the list,
+therefore emulating the "remap" behavior of hard disk drives::
+
+ $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
+ 128+0 records in
+ 128+0 records out
+
+ kernel: device-mapper: dust: block 60 removed from badblocklist by write
+ kernel: device-mapper: dust: block 67 removed from badblocklist by write
+ kernel: device-mapper: dust: block 72 removed from badblocklist by write
+ kernel: device-mapper: dust: block 87 removed from badblocklist by write
+
+Bad block add/remove error handling
+-----------------------------------
+
+Attempting to add a bad block that already exists in the list will
+result in an "Invalid argument" error, as well as a helpful message::
+
+ $ sudo dmsetup message dust1 0 addbadblock 88
+ device-mapper: message ioctl on dust1 failed: Invalid argument
+ kernel: device-mapper: dust: block 88 already in badblocklist
+
+Attempting to remove a bad block that doesn't exist in the list will
+result in an "Invalid argument" error, as well as a helpful message::
+
+ $ sudo dmsetup message dust1 0 removebadblock 87
+ device-mapper: message ioctl on dust1 failed: Invalid argument
+ kernel: device-mapper: dust: block 87 not found in badblocklist
+
+Counting the number of bad blocks in the bad block list
+-------------------------------------------------------
+
+To count the number of bad blocks configured in the device, run the
+following message command::
+
+ $ sudo dmsetup message dust1 0 countbadblocks
+
+A message will print with the number of bad blocks currently
+configured on the device::
+
+ kernel: device-mapper: dust: countbadblocks: 895 badblock(s) found
+
+Querying for specific bad blocks
+--------------------------------
+
+To find out if a specific block is in the bad block list, run the
+following message command::
+
+ $ sudo dmsetup message dust1 0 queryblock 72
+
+The following message will print if the block is in the list::
+
+ device-mapper: dust: queryblock: block 72 found in badblocklist
+
+The following message will print if the block is not in the list::
+
+ device-mapper: dust: queryblock: block 72 not found in badblocklist
+
+The "queryblock" message command will work in both the "enabled"
+and "disabled" modes, allowing the verification of whether a block
+will be treated as "bad" without having to issue I/O to the device,
+or having to "enable" the bad block emulation.
+
+Clearing the bad block list
+---------------------------
+
+To clear the bad block list (without needing to individually run
+a "removebadblock" message command for every block), run the
+following message command::
+
+ $ sudo dmsetup message dust1 0 clearbadblocks
+
+After clearing the bad block list, the following message will appear::
+
+ kernel: device-mapper: dust: clearbadblocks: badblocks cleared
+
+If there were no bad blocks to clear, the following message will
+appear::
+
+ kernel: device-mapper: dust: clearbadblocks: no badblocks found
+
+Message commands list
+---------------------
+
+Below is a list of the messages that can be sent to a dust device:
+
+Operations on blocks (requires a <blknum> argument)::
+
+ addbadblock <blknum>
+ queryblock <blknum>
+ removebadblock <blknum>
+
+...where <blknum> is a block number within range of the device
+(corresponding to the block size of the device.)
+
+Single argument message commands::
+
+ countbadblocks
+ clearbadblocks
+ disable
+ enable
+ quiet
+
+Device removal
+--------------
+
+When finished, remove the device via the "dmsetup remove" command::
+
+ $ sudo dmsetup remove dust1
+
+Quiet mode
+----------
+
+On test runs with many bad blocks, it may be desirable to avoid
+excessive logging (from bad blocks added, removed, or "remapped").
+This can be done by enabling "quiet mode" via the following message::
+
+ $ sudo dmsetup message dust1 0 quiet
+
+This will suppress log messages from add / remove / removed by write
+operations. Log messages from "countbadblocks" or "queryblock"
+message commands will still print in quiet mode.
+
+The status of quiet mode can be seen by running "dmsetup status"::
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 fail_read_on_bad_block quiet
+
+To disable quiet mode, send the "quiet" message again::
+
+ $ sudo dmsetup message dust1 0 quiet
+
+ $ sudo dmsetup status dust1
+ 0 33552384 dust 252:17 fail_read_on_bad_block verbose
+
+(The presence of "verbose" indicates normal logging.)
+
+"Why not...?"
+-------------
+
+scsi_debug has a "medium error" mode that can fail reads on one
+specified sector (sector 0x1234, hardcoded in the source code), but
+it uses RAM for the persistent storage, which drastically decreases
+the potential device size.
+
+dm-flakey fails all I/O from all block locations at a specified time
+frequency, and not a given point in time.
+
+When a bad sector occurs on a hard disk drive, reads to that sector
+are failed by the device, usually resulting in an error code of EIO
+("I/O error") or ENODATA ("No data available"). However, a write to
+the sector may succeed, and result in the sector becoming readable
+after the device controller no longer experiences errors reading the
+sector (or after a reallocation of the sector). However, there may
+be bad sectors that occur on the device in the future, in a different,
+unpredictable location.
+
+This target seeks to provide a device that can exhibit the behavior
+of a bad sector at a known sector location, at a known time, based
+on a large storage device (at least tens of gigabytes, not occupying
+system memory).
+++ /dev/null
-dm-dust
-=======
-
-This target emulates the behavior of bad sectors at arbitrary
-locations, and the ability to enable the emulation of the failures
-at an arbitrary time.
-
-This target behaves similarly to a linear target. At a given time,
-the user can send a message to the target to start failing read
-requests on specific blocks (to emulate the behavior of a hard disk
-drive with bad sectors).
-
-When the failure behavior is enabled (i.e.: when the output of
-"dmsetup status" displays "fail_read_on_bad_block"), reads of blocks
-in the "bad block list" will fail with EIO ("Input/output error").
-
-Writes of blocks in the "bad block list will result in the following:
-
-1. Remove the block from the "bad block list".
-2. Successfully complete the write.
-
-This emulates the "remapped sector" behavior of a drive with bad
-sectors.
-
-Normally, a drive that is encountering bad sectors will most likely
-encounter more bad sectors, at an unknown time or location.
-With dm-dust, the user can use the "addbadblock" and "removebadblock"
-messages to add arbitrary bad blocks at new locations, and the
-"enable" and "disable" messages to modulate the state of whether the
-configured "bad blocks" will be treated as bad, or bypassed.
-This allows the pre-writing of test data and metadata prior to
-simulating a "failure" event where bad sectors start to appear.
-
-Table parameters:
------------------
-<device_path> <offset> <blksz>
-
-Mandatory parameters:
- <device_path>: path to the block device.
- <offset>: offset to data area from start of device_path
- <blksz>: block size in bytes
- (minimum 512, maximum 1073741824, must be a power of 2)
-
-Usage instructions:
--------------------
-
-First, find the size (in 512-byte sectors) of the device to be used:
-
-$ sudo blockdev --getsz /dev/vdb1
-33552384
-
-Create the dm-dust device:
-(For a device with a block size of 512 bytes)
-$ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512'
-
-(For a device with a block size of 4096 bytes)
-$ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096'
-
-Check the status of the read behavior ("bypass" indicates that all I/O
-will be passed through to the underlying device):
-$ sudo dmsetup status dust1
-0 33552384 dust 252:17 bypass
-
-$ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct
-128+0 records in
-128+0 records out
-
-$ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
-128+0 records in
-128+0 records out
-
-Adding and removing bad blocks:
--------------------------------
-
-At any time (i.e.: whether the device has the "bad block" emulation
-enabled or disabled), bad blocks may be added or removed from the
-device via the "addbadblock" and "removebadblock" messages:
-
-$ sudo dmsetup message dust1 0 addbadblock 60
-kernel: device-mapper: dust: badblock added at block 60
-
-$ sudo dmsetup message dust1 0 addbadblock 67
-kernel: device-mapper: dust: badblock added at block 67
-
-$ sudo dmsetup message dust1 0 addbadblock 72
-kernel: device-mapper: dust: badblock added at block 72
-
-These bad blocks will be stored in the "bad block list".
-While the device is in "bypass" mode, reads and writes will succeed:
-
-$ sudo dmsetup status dust1
-0 33552384 dust 252:17 bypass
-
-Enabling block read failures:
------------------------------
-
-To enable the "fail read on bad block" behavior, send the "enable" message:
-
-$ sudo dmsetup message dust1 0 enable
-kernel: device-mapper: dust: enabling read failures on bad sectors
-
-$ sudo dmsetup status dust1
-0 33552384 dust 252:17 fail_read_on_bad_block
-
-With the device in "fail read on bad block" mode, attempting to read a
-block will encounter an "Input/output error":
-
-$ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct
-dd: error reading '/dev/mapper/dust1': Input/output error
-0+0 records in
-0+0 records out
-0 bytes copied, 0.00040651 s, 0.0 kB/s
-
-...and writing to the bad blocks will remove the blocks from the list,
-therefore emulating the "remap" behavior of hard disk drives:
-
-$ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct
-128+0 records in
-128+0 records out
-
-kernel: device-mapper: dust: block 60 removed from badblocklist by write
-kernel: device-mapper: dust: block 67 removed from badblocklist by write
-kernel: device-mapper: dust: block 72 removed from badblocklist by write
-kernel: device-mapper: dust: block 87 removed from badblocklist by write
-
-Bad block add/remove error handling:
-------------------------------------
-
-Attempting to add a bad block that already exists in the list will
-result in an "Invalid argument" error, as well as a helpful message:
-
-$ sudo dmsetup message dust1 0 addbadblock 88
-device-mapper: message ioctl on dust1 failed: Invalid argument
-kernel: device-mapper: dust: block 88 already in badblocklist
-
-Attempting to remove a bad block that doesn't exist in the list will
-result in an "Invalid argument" error, as well as a helpful message:
-
-$ sudo dmsetup message dust1 0 removebadblock 87
-device-mapper: message ioctl on dust1 failed: Invalid argument
-kernel: device-mapper: dust: block 87 not found in badblocklist
-
-Counting the number of bad blocks in the bad block list:
---------------------------------------------------------
-
-To count the number of bad blocks configured in the device, run the
-following message command:
-
-$ sudo dmsetup message dust1 0 countbadblocks
-
-A message will print with the number of bad blocks currently
-configured on the device:
-
-kernel: device-mapper: dust: countbadblocks: 895 badblock(s) found
-
-Querying for specific bad blocks:
----------------------------------
-
-To find out if a specific block is in the bad block list, run the
-following message command:
-
-$ sudo dmsetup message dust1 0 queryblock 72
-
-The following message will print if the block is in the list:
-device-mapper: dust: queryblock: block 72 found in badblocklist
-
-The following message will print if the block is in the list:
-device-mapper: dust: queryblock: block 72 not found in badblocklist
-
-The "queryblock" message command will work in both the "enabled"
-and "disabled" modes, allowing the verification of whether a block
-will be treated as "bad" without having to issue I/O to the device,
-or having to "enable" the bad block emulation.
-
-Clearing the bad block list:
-----------------------------
-
-To clear the bad block list (without needing to individually run
-a "removebadblock" message command for every block), run the
-following message command:
-
-$ sudo dmsetup message dust1 0 clearbadblocks
-
-After clearing the bad block list, the following message will appear:
-
-kernel: device-mapper: dust: clearbadblocks: badblocks cleared
-
-If there were no bad blocks to clear, the following message will
-appear:
-
-kernel: device-mapper: dust: clearbadblocks: no badblocks found
-
-Message commands list:
-----------------------
-
-Below is a list of the messages that can be sent to a dust device:
-
-Operations on blocks (requires a <blknum> argument):
-
-addbadblock <blknum>
-queryblock <blknum>
-removebadblock <blknum>
-
-...where <blknum> is a block number within range of the device
- (corresponding to the block size of the device.)
-
-Single argument message commands:
-
-countbadblocks
-clearbadblocks
-disable
-enable
-quiet
-
-Device removal:
----------------
-
-When finished, remove the device via the "dmsetup remove" command:
-
-$ sudo dmsetup remove dust1
-
-Quiet mode:
------------
-
-On test runs with many bad blocks, it may be desirable to avoid
-excessive logging (from bad blocks added, removed, or "remapped").
-This can be done by enabling "quiet mode" via the following message:
-
-$ sudo dmsetup message dust1 0 quiet
-
-This will suppress log messages from add / remove / removed by write
-operations. Log messages from "countbadblocks" or "queryblock"
-message commands will still print in quiet mode.
-
-The status of quiet mode can be seen by running "dmsetup status":
-
-$ sudo dmsetup status dust1
-0 33552384 dust 252:17 fail_read_on_bad_block quiet
-
-To disable quiet mode, send the "quiet" message again:
-
-$ sudo dmsetup message dust1 0 quiet
-
-$ sudo dmsetup status dust1
-0 33552384 dust 252:17 fail_read_on_bad_block verbose
-
-(The presence of "verbose" indicates normal logging.)
-
-"Why not...?"
--------------
-
-scsi_debug has a "medium error" mode that can fail reads on one
-specified sector (sector 0x1234, hardcoded in the source code), but
-it uses RAM for the persistent storage, which drastically decreases
-the potential device size.
-
-dm-flakey fails all I/O from all block locations at a specified time
-frequency, and not a given point in time.
-
-When a bad sector occurs on a hard disk drive, reads to that sector
-are failed by the device, usually resulting in an error code of EIO
-("I/O error") or ENODATA ("No data available"). However, a write to
-the sector may succeed, and result in the sector becoming readable
-after the device controller no longer experiences errors reading the
-sector (or after a reallocation of the sector). However, there may
-be bad sectors that occur on the device in the future, in a different,
-unpredictable location.
-
-This target seeks to provide a device that can exhibit the behavior
-of a bad sector at a known sector location, at a known time, based
-on a large storage device (at least tens of gigabytes, not occupying
-system memory).
cache
delay
dm-crypt
+ dm-dust
dm-flakey
dm-init
dm-integrity
.. toctree::
:maxdepth: 1
- initrd
- cgroup-v2
- cgroup-v1/index
- serial-console
- braille-console
- parport
- md
- module-signing
- rapidio
- sysrq
- unicode
- vga-softcursor
- binfmt-misc
- mono
- java
- ras
- bcache
- blockdev/index
- ext4
- binderfs
- cifs/index
- xfs
- jfs
- ufs
- pm/index
- thunderbolt
- LSM/index
- mm/index
- namespaces/index
- perf-security
acpi/index
aoe/index
+ auxdisplay/index
+ bcache
+ binderfs
+ binfmt-misc
+ blockdev/index
+ braille-console
btmrvl
+ cgroup-v1/index
+ cgroup-v2
+ cifs/index
clearing-warn-once
cpu-load
cputopology
+ dell_rbu
device-mapper/index
efi-stub
+ ext4
gpio/index
highuid
hw_random
+ initrd
iostats
+ java
+ jfs
kernel-per-CPU-kthreads
laptops/index
- auxdisplay/index
lcd-panel-cgram
ldm
lockup-watchdogs
+ LSM/index
+ md
+ mm/index
+ module-signing
+ mono
+ namespaces/index
numastat
+ parport
+ perf-security
+ pm/index
pnp
+ rapidio
+ ras
rtc
+ serial-console
svga
- wimax/index
+ sysrq
+ thunderbolt
+ ufs
+ unicode
+ vga-softcursor
video-output
+ wimax/index
+ xfs
.. only:: subproject and html
In 2.4, the statistics fields are those after the device name. In
the above example, the first field of statistics would be 446216.
By contrast, in 2.6+ if you look at ``/sys/block/hda/stat``, you'll
-find just the eleven fields, beginning with 446216. If you look at
-``/proc/diskstats``, the eleven fields will be preceded by the major and
+find just the 15 fields, beginning with 446216. If you look at
+``/proc/diskstats``, the 15 fields will be preceded by the major and
minor device numbers, and device name. Each of these formats provides
-eleven fields of statistics, each meaning exactly the same things.
+15 fields of statistics, each meaning exactly the same things.
All fields except field 9 are cumulative since boot. Field 9 should
go to zero as I/Os complete; all others only increase (unless they
-overflow and wrap). Yes, these are (32-bit or 64-bit) unsigned long
-(native word size) numbers, and on a very busy or long-lived system they
-may wrap. Applications should be prepared to deal with that; unless
-your observations are measured in large numbers of minutes or hours,
-they should not wrap twice before you notice them.
+overflow and wrap). Wrapping might eventually occur on a very busy
+or long-lived system; so applications should be prepared to deal with
+it. Regarding wrapping, the types of the fields are either unsigned
+int (32 bit) or unsigned long (32-bit or 64-bit, depending on your
+machine) as noted per-field below. Unless your observations are very
+spread in time, these fields should not wrap twice before you notice it.
Each set of stats only applies to the indicated device; if you want
system-wide stats you'll have to find all the devices and sum them all up.
-Field 1 -- # of reads completed
+Field 1 -- # of reads completed (unsigned long)
This is the total number of reads completed successfully.
-Field 2 -- # of reads merged, field 6 -- # of writes merged
+Field 2 -- # of reads merged, field 6 -- # of writes merged (unsigned long)
Reads and writes which are adjacent to each other may be merged for
efficiency. Thus two 4K reads may become one 8K read before it is
ultimately handed to the disk, and so it will be counted (and queued)
as only one I/O. This field lets you know how often this was done.
-Field 3 -- # of sectors read
+Field 3 -- # of sectors read (unsigned long)
This is the total number of sectors read successfully.
-Field 4 -- # of milliseconds spent reading
+Field 4 -- # of milliseconds spent reading (unsigned int)
This is the total number of milliseconds spent by all reads (as
measured from __make_request() to end_that_request_last()).
-Field 5 -- # of writes completed
+Field 5 -- # of writes completed (unsigned long)
This is the total number of writes completed successfully.
-Field 6 -- # of writes merged
+Field 6 -- # of writes merged (unsigned long)
See the description of field 2.
-Field 7 -- # of sectors written
+Field 7 -- # of sectors written (unsigned long)
This is the total number of sectors written successfully.
-Field 8 -- # of milliseconds spent writing
+Field 8 -- # of milliseconds spent writing (unsigned int)
This is the total number of milliseconds spent by all writes (as
measured from __make_request() to end_that_request_last()).
-Field 9 -- # of I/Os currently in progress
+Field 9 -- # of I/Os currently in progress (unsigned int)
The only field that should go to zero. Incremented as requests are
given to appropriate struct request_queue and decremented as they finish.
-Field 10 -- # of milliseconds spent doing I/Os
+Field 10 -- # of milliseconds spent doing I/Os (unsigned int)
This field increases so long as field 9 is nonzero.
Since 5.0 this field counts jiffies when at least one request was
started or completed. If request runs more than 2 jiffies then some
I/O time will not be accounted unless there are other requests.
-Field 11 -- weighted # of milliseconds spent doing I/Os
+Field 11 -- weighted # of milliseconds spent doing I/Os (unsigned int)
This field is incremented at each I/O start, I/O completion, I/O
merge, or read of these stats by the number of I/Os in progress
(field 9) times the number of milliseconds spent doing I/O since the
last update of this field. This can provide an easy measure of both
I/O completion time and the backlog that may be accumulating.
-Field 12 -- # of discards completed
+Field 12 -- # of discards completed (unsigned long)
This is the total number of discards completed successfully.
-Field 13 -- # of discards merged
+Field 13 -- # of discards merged (unsigned long)
See the description of field 2
-Field 14 -- # of sectors discarded
+Field 14 -- # of sectors discarded (unsigned long)
This is the total number of sectors discarded successfully.
-Field 15 -- # of milliseconds spent discarding
+Field 15 -- # of milliseconds spent discarding (unsigned int)
This is the total number of milliseconds spent by all discards (as
measured from __make_request() to end_that_request_last()).
earlycon= [KNL] Output early console device and options.
- [ARM64] The early console is determined by the
- stdout-path property in device tree's chosen node,
- or determined by the ACPI SPCR table.
-
- [X86] When used with no options the early console is
- determined by the ACPI SPCR table.
+ When used with no options, the early console is
+ determined by stdout-path property in device tree's
+ chosen node or the ACPI SPCR table if supported by
+ the platform.
+
+ [RISCV] When used with no options, the early
+ console is determined by the stdout-path
+ property in the device tree's chosen node.
cdns,<addr>[,options]
Start an early, polled-mode console on a Cadence
devices/imx8_ddr0/format/. The "events" directory describes the events types
hardware supported that can be used with perf tool, see /sys/bus/event_source/
devices/imx8_ddr0/events/.
- e.g.::
+
+ .. code-block:: bash
+
perf stat -a -e imx8_ddr0/cycles/ cmd
perf stat -a -e imx8_ddr0/read/,imx8_ddr0/write/ cmd
Filter is defined with two configuration parts:
--AXI_ID defines AxID matching value.
--AXI_MASKING defines which bits of AxID are meaningful for the matching.
- 0：corresponding bit is masked.
- 1: corresponding bit is not masked, i.e. used to do the matching.
+
+ - 0: corresponding bit is masked.
+ - 1: corresponding bit is not masked, i.e. used to do the matching.
AXI_ID and AXI_MASKING are mapped on DPCR1 register in performance counter.
When non-masked bits are matching corresponding AXI_ID bits then counter is
incremented. Perf counter is incremented if
- AxID && AXI_MASKING == AXI_ID && AXI_MASKING
+ AxID && AXI_MASKING == AXI_ID && AXI_MASKING
This filter doesn't support filter different AXI ID for axid-read and axid-write
event at the same time as this filter is shared between counters.
- e.g.::
- perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd
- perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd
-
- NOTE: axi_mask is inverted in userspace(i.e. set bits are bits to mask), and
- it will be reverted in driver automatically. so that the user can just specify
- axi_id to monitor a specific id, rather than having to specify axi_mask.
- e.g.::
- perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12
+
+ .. code-block:: bash
+
+ perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd
+ perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd
+
+ .. note::
+
+ axi_mask is inverted in userspace(i.e. set bits are bits to mask), and
+ it will be reverted in driver automatically. so that the user can just specify
+ axi_id to monitor a specific id, rather than having to specify axi_mask.
+
+ .. code-block:: bash
+
+ perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12
:maxdepth: 1
hisi-pmu
+ imx-ddr
qcom_l2_pmu
qcom_l3_pmu
arm-ccn
=================
Some warning messages are rate limited. printk_ratelimit specifies
-the minimum length of time between these messages (in jiffies), by
-default we allow one every 5 seconds.
+the minimum length of time between these messages (in seconds).
+The default value is 5 seconds.
A value of 0 will disable rate limiting.
printk_ratelimit_burst specifies the number of messages we can
send before ratelimiting kicks in.
+The default value is 10 messages.
+
printk_devkmsg:
===============
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
- 'kfigure', 'sphinx.ext.ifconfig', 'automarkup']
+ 'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
+ 'maintainers_include']
# The name of the math extension changed on Sphinx 1.4
if (major == 1 and minor > 3) or (major > 1):
.. kernel-doc:: lib/genalloc.c
:functions: devm_gen_pool_create
-A call to :c:func:`gen_pool_create` will create a pool. The granularity of
+A call to gen_pool_create() will create a pool. The granularity of
allocations is set with min_alloc_order; it is a log-base-2 number like
those used by the page allocator, but it refers to bytes rather than pages.
So, if min_alloc_order is passed as 3, then all allocations will be a
which NUMA node should be used for the allocation of the housekeeping
structures; it can be -1 if the caller doesn't care.
-The "managed" interface :c:func:`devm_gen_pool_create` ties the pool to a
+The "managed" interface devm_gen_pool_create() ties the pool to a
specific device. Among other things, it will automatically clean up the
pool when the given device is destroyed.
:functions: gen_pool_add
.. kernel-doc:: lib/genalloc.c
- :functions: gen_pool_add_virt
+ :functions: gen_pool_add_owner
-A call to :c:func:`gen_pool_add` will place the size bytes of memory
+A call to gen_pool_add() will place the size bytes of memory
starting at addr (in the kernel's virtual address space) into the given
pool, once again using nid as the node ID for ancillary memory allocations.
-The :c:func:`gen_pool_add_virt` variant associates an explicit physical
+The gen_pool_add_virt() variant associates an explicit physical
address with the memory; this is only necessary if the pool will be used
for DMA allocations.
The functions for allocating memory from the pool (and putting it back)
are:
-.. kernel-doc:: lib/genalloc.c
+.. kernel-doc:: include/linux/genalloc.h
:functions: gen_pool_alloc
.. kernel-doc:: lib/genalloc.c
:functions: gen_pool_dma_alloc
.. kernel-doc:: lib/genalloc.c
- :functions: gen_pool_free
+ :functions: gen_pool_free_owner
-As one would expect, :c:func:`gen_pool_alloc` will allocate size< bytes
-from the given pool. The :c:func:`gen_pool_dma_alloc` variant allocates
+As one would expect, gen_pool_alloc() will allocate size< bytes
+from the given pool. The gen_pool_dma_alloc() variant allocates
memory for use with DMA operations, returning the associated physical
address in the space pointed to by dma. This will only work if the memory
-was added with :c:func:`gen_pool_add_virt`. Note that this function
+was added with gen_pool_add_virt(). Note that this function
departs from the usual genpool pattern of using unsigned long values to
represent kernel addresses; it returns a void * instead.
of interest:
.. kernel-doc:: lib/genalloc.c
- :functions: gen_pool_alloc_algo
+ :functions: gen_pool_alloc_algo_owner
.. kernel-doc:: lib/genalloc.c
:functions: gen_pool_set_algo
-Allocations with :c:func:`gen_pool_alloc_algo` specify an algorithm to be
+Allocations with gen_pool_alloc_algo() specify an algorithm to be
used to choose the memory to be allocated; the default algorithm can be set
-with :c:func:`gen_pool_set_algo`. The data value is passed to the
+with gen_pool_set_algo(). The data value is passed to the
algorithm; most ignore it, but it is occasionally needed. One can,
naturally, write a special-purpose algorithm, but there is a fair set
already available:
=========
The original implementation of interrupt handling in Linux uses the
-:c:func:`__do_IRQ` super-handler, which is able to deal with every type of
+__do_IRQ() super-handler, which is able to deal with every type of
interrupt logic.
Originally, Russell King identified different types of handlers to build
- Fast EOI type
-In the SMP world of the :c:func:`__do_IRQ` super-handler another type was
+In the SMP world of the __do_IRQ() super-handler another type was
identified:
- Per CPU type
(sub)architecture specific 'edge type' implementation.
To make the transition to the new model easier and prevent the breakage
-of existing implementations, the :c:func:`__do_IRQ` super-handler is still
+of existing implementations, the __do_IRQ() super-handler is still
available. This leads to a kind of duality for the time being. Over time
the new model should be used in more and more architectures, as it
enables smaller and cleaner IRQ subsystems. It's deprecated for three
interrupt chip structure which are assigned to this interrupt.
Whenever an interrupt triggers, the low-level architecture code calls
-into the generic interrupt code by calling :c:func:`desc->handle_irq`. This
+into the generic interrupt code by calling desc->handle_irq(). This
high-level IRQ handling function only uses desc->irq_data.chip
primitives referenced by the assigned chip descriptor structure.
The high-level Driver API consists of following functions:
-- :c:func:`request_irq`
+- request_irq()
-- :c:func:`free_irq`
+- free_irq()
-- :c:func:`disable_irq`
+- disable_irq()
-- :c:func:`enable_irq`
+- enable_irq()
-- :c:func:`disable_irq_nosync` (SMP only)
+- disable_irq_nosync() (SMP only)
-- :c:func:`synchronize_irq` (SMP only)
+- synchronize_irq() (SMP only)
-- :c:func:`irq_set_irq_type`
+- irq_set_irq_type()
-- :c:func:`irq_set_irq_wake`
+- irq_set_irq_wake()
-- :c:func:`irq_set_handler_data`
+- irq_set_handler_data()
-- :c:func:`irq_set_chip`
+- irq_set_chip()
-- :c:func:`irq_set_chip_data`
+- irq_set_chip_data()
See the autogenerated function documentation for details.
The generic layer provides a set of pre-defined irq-flow methods:
-- :c:func:`handle_level_irq`
+- handle_level_irq()
-- :c:func:`handle_edge_irq`
+- handle_edge_irq()
-- :c:func:`handle_fasteoi_irq`
+- handle_fasteoi_irq()
-- :c:func:`handle_simple_irq`
+- handle_simple_irq()
-- :c:func:`handle_percpu_irq`
+- handle_percpu_irq()
-- :c:func:`handle_edge_eoi_irq`
+- handle_edge_eoi_irq()
-- :c:func:`handle_bad_irq`
+- handle_bad_irq()
The interrupt flow handlers (either pre-defined or architecture
specific) are assigned to specific interrupts by the architecture either
This per interrupt selectable feature, which was introduced by Russell
King in the ARM interrupt implementation, does not mask an interrupt at
-the hardware level when :c:func:`disable_irq` is called. The interrupt is kept
+the hardware level when disable_irq() is called. The interrupt is kept
enabled and is masked in the flow handler when an interrupt event
happens. This prevents losing edge interrupts on hardware which does not
store an edge interrupt event while the interrupt is disabled at the
hardware level. When an interrupt arrives while the IRQ_DISABLED flag
is set, then the interrupt is masked at the hardware level and the
IRQ_PENDING bit is set. When the interrupt is re-enabled by
-:c:func:`enable_irq` the pending bit is checked and if it is set, the interrupt
+enable_irq() the pending bit is checked and if it is set, the interrupt
is resent either via hardware or by a software resend mechanism. (It's
necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use
the delayed interrupt disable feature and your hardware is not capable
__do_IRQ entry point
====================
-The original implementation :c:func:`__do_IRQ` was an alternative entry point
+The original implementation __do_IRQ() was an alternative entry point
for all types of interrupts. It no longer exists.
This handler turned out to be not suitable for all interrupt hardware
.. kernel-doc:: arch/x86/lib/usercopy_32.c
:export:
-.. kernel-doc:: mm/util.c
+.. kernel-doc:: mm/gup.c
:functions: get_user_pages_fast
.. _mm-api-gfp-flags:
program order (po) relation (on the same CPU). It guarantees that
each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions
are executed in program order on a single CPU.
-This is implemented using :c:func:`READ_ONCE`/:c:func:`WRITE_ONCE` and
+This is implemented using READ_ONCE()/WRITE_ONCE() and
compare-and-swap primitives.
A strong (full) memory ordering guarantees that all prior loads and
It also guarantees that all po-earlier stores on the same CPU
and all propagated stores from other CPUs must propagate to all
other CPUs before any po-later instruction is executed on the original
-CPU (A-cumulative property). This is implemented using :c:func:`smp_mb`.
+CPU (A-cumulative property). This is implemented using smp_mb().
A RELEASE memory ordering guarantees that all prior loads and
stores (all po-earlier instructions) on the same CPU are completed
stores on the same CPU and all propagated stores from other CPUs
must propagate to all other CPUs before the release operation
(A-cumulative property). This is implemented using
-:c:func:`smp_store_release`.
+smp_store_release().
An ACQUIRE memory ordering guarantees that all post loads and
stores (all po-later instructions) on the same CPU are
completed after the acquire operation. It also guarantees that all
po-later stores on the same CPU must propagate to all other CPUs
after the acquire operation executes. This is implemented using
-:c:func:`smp_acquire__after_ctrl_dep`.
+smp_acquire__after_ctrl_dep().
A control dependency (on success) for refcounters guarantees that
if a reference for an object was successfully obtained (reference
Function changes:
- * :c:func:`atomic_set` --> :c:func:`refcount_set`
- * :c:func:`atomic_read` --> :c:func:`refcount_read`
+ * atomic_set() --> refcount_set()
+ * atomic_read() --> refcount_read()
Memory ordering guarantee changes:
Function changes:
- * :c:func:`atomic_inc` --> :c:func:`refcount_inc`
- * :c:func:`atomic_add` --> :c:func:`refcount_add`
+ * atomic_inc() --> refcount_inc()
+ * atomic_add() --> refcount_add()
Memory ordering guarantee changes:
Function changes:
- * :c:func:`atomic_dec` --> :c:func:`refcount_dec`
+ * atomic_dec() --> refcount_dec()
Memory ordering guarantee changes:
Function changes:
- * :c:func:`atomic_inc_not_zero` --> :c:func:`refcount_inc_not_zero`
- * no atomic counterpart --> :c:func:`refcount_add_not_zero`
+ * atomic_inc_not_zero() --> refcount_inc_not_zero()
+ * no atomic counterpart --> refcount_add_not_zero()
Memory ordering guarantees changes:
Function changes:
- * :c:func:`atomic_dec_and_test` --> :c:func:`refcount_dec_and_test`
- * :c:func:`atomic_sub_and_test` --> :c:func:`refcount_sub_and_test`
+ * atomic_dec_and_test() --> refcount_dec_and_test()
+ * atomic_sub_and_test() --> refcount_sub_and_test()
Memory ordering guarantees changes:
Function changes:
- * no atomic counterpart --> :c:func:`refcount_dec_if_one`
+ * no atomic counterpart --> refcount_dec_if_one()
* ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)``
Memory ordering guarantees changes:
* fully ordered --> RELEASE ordering + control dependency
-.. note:: :c:func:`atomic_add_unless` only provides full order on success.
+.. note:: atomic_add_unless() only provides full order on success.
case 7) - lock-based RMW
Function changes:
- * :c:func:`atomic_dec_and_lock` --> :c:func:`refcount_dec_and_lock`
- * :c:func:`atomic_dec_and_mutex_lock` --> :c:func:`refcount_dec_and_mutex_lock`
+ * atomic_dec_and_lock() --> refcount_dec_and_lock()
+ * atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock()
Memory ordering guarantees changes:
* fully ordered --> RELEASE ordering + control dependency + hold
- :c:func:`spin_lock` on success
+ spin_lock() on success
Memory may be allocated or freed before kmemleak is initialised and
these actions are stored in an early log buffer. The size of this buffer
-is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option.
+is configured via the CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE option.
If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is
disabled by default. Passing ``kmemleak=on`` on the kernel command
[2] Devicetree NUMA binding description
Documentation/devicetree/bindings/numa.txt
[3] RISC-V Linux kernel documentation
- Documentation/devicetree/bindings/riscv/cpus.txt
+ Documentation/devicetree/bindings/riscv/cpus.yaml
[4] https://www.devicetree.org/specifications/
==========================================================
For a description of the TCU hardware and drivers, have a look at
-Documentation/mips/ingenic-tcu.txt.
+Documentation/mips/ingenic-tcu.rst.
Required properties:
+++ /dev/null
-=============================================================
-Usage of the new open sourced rbu (Remote BIOS Update) driver
-=============================================================
-
-Purpose
-=======
-
-Document demonstrating the use of the Dell Remote BIOS Update driver.
-for updating BIOS images on Dell servers and desktops.
-
-Scope
-=====
-
-This document discusses the functionality of the rbu driver only.
-It does not cover the support needed from applications to enable the BIOS to
-update itself with the image downloaded in to the memory.
-
-Overview
-========
-
-This driver works with Dell OpenManage or Dell Update Packages for updating
-the BIOS on Dell servers (starting from servers sold since 1999), desktops
-and notebooks (starting from those sold in 2005).
-
-Please go to http://support.dell.com register and you can find info on
-OpenManage and Dell Update packages (DUP).
-
-Libsmbios can also be used to update BIOS on Dell systems go to
-http://linux.dell.com/libsmbios/ for details.
-
-Dell_RBU driver supports BIOS update using the monolithic image and packetized
-image methods. In case of monolithic the driver allocates a contiguous chunk
-of physical pages having the BIOS image. In case of packetized the app
-using the driver breaks the image in to packets of fixed sizes and the driver
-would place each packet in contiguous physical memory. The driver also
-maintains a link list of packets for reading them back.
-
-If the dell_rbu driver is unloaded all the allocated memory is freed.
-
-The rbu driver needs to have an application (as mentioned above)which will
-inform the BIOS to enable the update in the next system reboot.
-
-The user should not unload the rbu driver after downloading the BIOS image
-or updating.
-
-The driver load creates the following directories under the /sys file system::
-
- /sys/class/firmware/dell_rbu/loading
- /sys/class/firmware/dell_rbu/data
- /sys/devices/platform/dell_rbu/image_type
- /sys/devices/platform/dell_rbu/data
- /sys/devices/platform/dell_rbu/packet_size
-
-The driver supports two types of update mechanism; monolithic and packetized.
-These update mechanism depends upon the BIOS currently running on the system.
-Most of the Dell systems support a monolithic update where the BIOS image is
-copied to a single contiguous block of physical memory.
-
-In case of packet mechanism the single memory can be broken in smaller chunks
-of contiguous memory and the BIOS image is scattered in these packets.
-
-By default the driver uses monolithic memory for the update type. This can be
-changed to packets during the driver load time by specifying the load
-parameter image_type=packet. This can also be changed later as below::
-
- echo packet > /sys/devices/platform/dell_rbu/image_type
-
-In packet update mode the packet size has to be given before any packets can
-be downloaded. It is done as below::
-
- echo XXXX > /sys/devices/platform/dell_rbu/packet_size
-
-In the packet update mechanism, the user needs to create a new file having
-packets of data arranged back to back. It can be done as follows
-The user creates packets header, gets the chunk of the BIOS image and
-places it next to the packetheader; now, the packetheader + BIOS image chunk
-added together should match the specified packet_size. This makes one
-packet, the user needs to create more such packets out of the entire BIOS
-image file and then arrange all these packets back to back in to one single
-file.
-
-This file is then copied to /sys/class/firmware/dell_rbu/data.
-Once this file gets to the driver, the driver extracts packet_size data from
-the file and spreads it across the physical memory in contiguous packet_sized
-space.
-
-This method makes sure that all the packets get to the driver in a single operation.
-
-In monolithic update the user simply get the BIOS image (.hdr file) and copies
-to the data file as is without any change to the BIOS image itself.
-
-Do the steps below to download the BIOS image.
-
-1) echo 1 > /sys/class/firmware/dell_rbu/loading
-2) cp bios_image.hdr /sys/class/firmware/dell_rbu/data
-3) echo 0 > /sys/class/firmware/dell_rbu/loading
-
-The /sys/class/firmware/dell_rbu/ entries will remain till the following is
-done.
-
-::
-
- echo -1 > /sys/class/firmware/dell_rbu/loading
-
-Until this step is completed the driver cannot be unloaded.
-
-Also echoing either mono, packet or init in to image_type will free up the
-memory allocated by the driver.
-
-If a user by accident executes steps 1 and 3 above without executing step 2;
-it will make the /sys/class/firmware/dell_rbu/ entries disappear.
-
-The entries can be recreated by doing the following::
-
- echo init > /sys/devices/platform/dell_rbu/image_type
-
-.. note:: echoing init in image_type does not change it original value.
-
-Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to
-read back the image downloaded.
-
-.. note::
-
- After updating the BIOS image a user mode application needs to execute
- code which sends the BIOS update request to the BIOS. So on the next reboot
- the BIOS knows about the new image downloaded and it updates itself.
- Also don't unload the rbu driver if the image has to be updated.
-
Reservation Objects
-------------------
-.. kernel-doc:: drivers/dma-buf/reservation.c
+.. kernel-doc:: drivers/dma-buf/dma-resv.c
:doc: Reservation Object Overview
-.. kernel-doc:: drivers/dma-buf/reservation.c
+.. kernel-doc:: drivers/dma-buf/dma-resv.c
:export:
-.. kernel-doc:: include/linux/reservation.h
+.. kernel-doc:: include/linux/dma-resv.h
:internal:
DMA Fences
gpiochip. It will pass the struct gpio_chip* for the chip to all IRQ
callbacks, so the callbacks need to embed the gpio_chip in its state
container and obtain a pointer to the container using container_of().
- (See Documentation/driver-model/design-patterns.txt)
+ (See Documentation/driver-api/driver-model/design-patterns.rst)
- gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip,
as discussed above regarding different types of cascaded irqchips. The
connector
console
dcdbas
- dell_rbu
edid
eisa
ipmb
pwm
rfkill
serial/index
- sgi-ioc4
sm501
smsc_ece1099
switchtec
Device Drivers DMA Management
-----------------------------
-.. kernel-doc:: kernel/dma/coherent.c
- :export:
-
.. kernel-doc:: kernel/dma/mapping.c
:export:
the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter
and n_tracesink line discpline drivers but is a generic
operation for a program to use a line discpline driver
-on a tty port other than the default n_tty::
+on a tty port other than the default n_tty:
+
+.. code-block:: c
/////////// To hook up n_tracerouter and n_tracesink /////////
These functions are useful as long as the developer knows the size of the
value to be exported. Some types can have different widths on different
-architectures, though, complicating the situation somewhat. There is a
-function meant to help out in one special case:
+architectures, though, complicating the situation somewhat. There are
+functions meant to help out in such special cases:
struct dentry *debugfs_create_size_t(const char *name, umode_t mode,
struct dentry *parent,
As might be expected, this function will create a debugfs file to represent
a variable of type size_t.
+Similarly, there is a helper for variables of type unsigned long:
+
+ struct dentry *debugfs_create_ulong(const char *name, umode_t mode,
+ struct dentry *parent,
+ unsigned long *value);
+
Boolean values can be placed in debugfs with:
struct dentry *debugfs_create_bool(const char *name, umode_t mode,
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries
-. SPDX-License-Identifier: GPL-2.0
+.. SPDX-License-Identifier: GPL-2.0
===============
I2C Bus Drivers
-. SPDX-License-Identifier: GPL-2.0
+.. SPDX-License-Identifier: GPL-2.0
===================
I2C/SMBus Subsystem
:maxdepth: 2
userspace-api/index
- ioctl/index
Introduction to kernel development
+++ /dev/null
-=================================
-(How to avoid) Botching up ioctls
-=================================
-
-From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html
-
-By: Daniel Vetter, Copyright © 2013 Intel Corporation
-
-One clear insight kernel graphics hackers gained in the past few years is that
-trying to come up with a unified interface to manage the execution units and
-memory on completely different GPUs is a futile effort. So nowadays every
-driver has its own set of ioctls to allocate memory and submit work to the GPU.
-Which is nice, since there's no more insanity in the form of fake-generic, but
-actually only used once interfaces. But the clear downside is that there's much
-more potential to screw things up.
-
-To avoid repeating all the same mistakes again I've written up some of the
-lessons learned while botching the job for the drm/i915 driver. Most of these
-only cover technicalities and not the big-picture issues like what the command
-submission ioctl exactly should look like. Learning these lessons is probably
-something every GPU driver has to do on its own.
-
-
-Prerequisites
--------------
-
-First the prerequisites. Without these you have already failed, because you
-will need to add a 32-bit compat layer:
-
- * Only use fixed sized integers. To avoid conflicts with typedefs in userspace
- the kernel has special types like __u32, __s64. Use them.
-
- * Align everything to the natural size and use explicit padding. 32-bit
- platforms don't necessarily align 64-bit values to 64-bit boundaries, but
- 64-bit platforms do. So we always need padding to the natural size to get
- this right.
-
- * Pad the entire struct to a multiple of 64-bits if the structure contains
- 64-bit types - the structure size will otherwise differ on 32-bit versus
- 64-bit. Having a different structure size hurts when passing arrays of
- structures to the kernel, or if the kernel checks the structure size, which
- e.g. the drm core does.
-
- * Pointers are __u64, cast from/to a uintprt_t on the userspace side and
- from/to a void __user * in the kernel. Try really hard not to delay this
- conversion or worse, fiddle the raw __u64 through your code since that
- diminishes the checking tools like sparse can provide. The macro
- u64_to_user_ptr can be used in the kernel to avoid warnings about integers
- and pointres of different sizes.
-
-
-Basics
-------
-
-With the joys of writing a compat layer avoided we can take a look at the basic
-fumbles. Neglecting these will make backward and forward compatibility a real
-pain. And since getting things wrong on the first attempt is guaranteed you
-will have a second iteration or at least an extension for any given interface.
-
- * Have a clear way for userspace to figure out whether your new ioctl or ioctl
- extension is supported on a given kernel. If you can't rely on old kernels
- rejecting the new flags/modes or ioctls (since doing that was botched in the
- past) then you need a driver feature flag or revision number somewhere.
-
- * Have a plan for extending ioctls with new flags or new fields at the end of
- the structure. The drm core checks the passed-in size for each ioctl call
- and zero-extends any mismatches between kernel and userspace. That helps,
- but isn't a complete solution since newer userspace on older kernels won't
- notice that the newly added fields at the end get ignored. So this still
- needs a new driver feature flags.
-
- * Check all unused fields and flags and all the padding for whether it's 0,
- and reject the ioctl if that's not the case. Otherwise your nice plan for
- future extensions is going right down the gutters since someone will submit
- an ioctl struct with random stack garbage in the yet unused parts. Which
- then bakes in the ABI that those fields can never be used for anything else
- but garbage. This is also the reason why you must explicitly pad all
- structures, even if you never use them in an array - the padding the compiler
- might insert could contain garbage.
-
- * Have simple testcases for all of the above.
-
-
-Fun with Error Paths
---------------------
-
-Nowadays we don't have any excuse left any more for drm drivers being neat
-little root exploits. This means we both need full input validation and solid
-error handling paths - GPUs will die eventually in the oddmost corner cases
-anyway:
-
- * The ioctl must check for array overflows. Also it needs to check for
- over/underflows and clamping issues of integer values in general. The usual
- example is sprite positioning values fed directly into the hardware with the
- hardware just having 12 bits or so. Works nicely until some odd display
- server doesn't bother with clamping itself and the cursor wraps around the
- screen.
-
- * Have simple testcases for every input validation failure case in your ioctl.
- Check that the error code matches your expectations. And finally make sure
- that you only test for one single error path in each subtest by submitting
- otherwise perfectly valid data. Without this an earlier check might reject
- the ioctl already and shadow the codepath you actually want to test, hiding
- bugs and regressions.
-
- * Make all your ioctls restartable. First X really loves signals and second
- this will allow you to test 90% of all error handling paths by just
- interrupting your main test suite constantly with signals. Thanks to X's
- love for signal you'll get an excellent base coverage of all your error
- paths pretty much for free for graphics drivers. Also, be consistent with
- how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its
- userspace library. The i915 driver botched this with the set_tiling ioctl,
- now we're stuck forever with some arcane semantics in both the kernel and
- userspace.
-
- * If you can't make a given codepath restartable make a stuck task at least
- killable. GPUs just die and your users won't like you more if you hang their
- entire box (by means of an unkillable X process). If the state recovery is
- still too tricky have a timeout or hangcheck safety net as a last-ditch
- effort in case the hardware has gone bananas.
-
- * Have testcases for the really tricky corner cases in your error recovery code
- - it's way too easy to create a deadlock between your hangcheck code and
- waiters.
-
-
-Time, Waiting and Missing it
-----------------------------
-
-GPUs do most everything asynchronously, so we have a need to time operations and
-wait for outstanding ones. This is really tricky business; at the moment none of
-the ioctls supported by the drm/i915 get this fully right, which means there's
-still tons more lessons to learn here.
-
- * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and
- v4l use by default nowadays. But let userspace know which timestamps are
- derived from different clock domains like your main system clock (provided
- by the kernel) or some independent hardware counter somewhere else. Clocks
- will mismatch if you look close enough, but if performance measuring tools
- have this information they can at least compensate. If your userspace can
- get at the raw values of some clocks (e.g. through in-command-stream
- performance counter sampling instructions) consider exposing those also.
-
- * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most
- convenient time specification, but it's mostly the standard.
-
- * Check that input time values are normalized and reject them if not. Note
- that the kernel native struct ktime has a signed integer for both seconds
- and nanoseconds, so beware here.
-
- * For timeouts, use absolute times. If you're a good fellow and made your
- ioctl restartable relative timeouts tend to be too coarse and can
- indefinitely extend your wait time due to rounding on each restart.
- Especially if your reference clock is something really slow like the display
- frame counter. With a spec lawyer hat on this isn't a bug since timeouts can
- always be extended - but users will surely hate you if their neat animations
- starts to stutter due to this.
-
- * Consider ditching any synchronous wait ioctls with timeouts and just deliver
- an asynchronous event on a pollable file descriptor. It fits much better
- into event driven applications' main loop.
-
- * Have testcases for corner-cases, especially whether the return values for
- already-completed events, successful waits and timed-out waits are all sane
- and suiting to your needs.
-
-
-Leaking Resources, Not
-----------------------
-
-A full-blown drm driver essentially implements a little OS, but specialized to
-the given GPU platforms. This means a driver needs to expose tons of handles
-for different objects and other resources to userspace. Doing that right
-entails its own little set of pitfalls:
-
- * Always attach the lifetime of your dynamically created resources to the
- lifetime of a file descriptor. Consider using a 1:1 mapping if your resource
- needs to be shared across processes - fd-passing over unix domain sockets
- also simplifies lifetime management for userspace.
-
- * Always have O_CLOEXEC support.
-
- * Ensure that you have sufficient insulation between different clients. By
- default pick a private per-fd namespace which forces any sharing to be done
- explicitly. Only go with a more global per-device namespace if the objects
- are truly device-unique. One counterexample in the drm modeset interfaces is
- that the per-device modeset objects like connectors share a namespace with
- framebuffer objects, which mostly are not shared at all. A separate
- namespace, private by default, for framebuffers would have been more
- suitable.
-
- * Think about uniqueness requirements for userspace handles. E.g. for most drm
- drivers it's a userspace bug to submit the same object twice in the same
- command submission ioctl. But then if objects are shareable userspace needs
- to know whether it has seen an imported object from a different process
- already or not. I haven't tried this myself yet due to lack of a new class
- of objects, but consider using inode numbers on your shared file descriptors
- as unique identifiers - it's how real files are told apart, too.
- Unfortunately this requires a full-blown virtual filesystem in the kernel.
-
-
-Last, but not Least
--------------------
-
-Not every problem needs a new ioctl:
-
- * Think hard whether you really want a driver-private interface. Of course
- it's much quicker to push a driver-private interface than engaging in
- lengthy discussions for a more generic solution. And occasionally doing a
- private interface to spearhead a new concept is what's required. But in the
- end, once the generic interface comes around you'll end up maintainer two
- interfaces. Indefinitely.
-
- * Consider other interfaces than ioctls. A sysfs attribute is much better for
- per-device settings, or for child objects with fairly static lifetimes (like
- output connectors in drm with all the detection override attributes). Or
- maybe only your testsuite needs this interface, and then debugfs with its
- disclaimer of not having a stable ABI would be better.
-
-Finally, the name of the game is to get it right on the first attempt, since if
-your driver proves popular and your hardware platforms long-lived then you'll
-be stuck with a given ioctl essentially forever. You can try to deprecate
-horrible ioctls on newer iterations of your hardware, but generally it takes
-years to accomplish this. And then again years until the last user able to
-complain about regressions disappears, too.
+++ /dev/null
-============================
-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.
+++ /dev/null
-==============================
-Summary of `HDIO_` ioctl calls
-==============================
-
-- Edward A. Falk <efalk@google.com>
-
-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)
-in drivers/ide/ide.c and drivers/block/scsi_ioctl.c
-
-ioctl values are listed in <linux/hdreg.h>. As of this writing, they
-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
- HDIO_GET_QDMA get use-qdma flag
- HDIO_SET_XFER set transfer rate via proc
- HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE
- HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag
- HDIO_GET_32BIT get current io_32bit setting
- HDIO_GET_NOWERR get ignore-write-error flag
- HDIO_GET_DMA get use-dma flag
- HDIO_GET_NICE get nice flags
- HDIO_GET_IDENTITY get IDE identification info
- HDIO_GET_WCACHE get write cache mode on|off
- HDIO_GET_ACOUSTIC get acoustic value
- HDIO_GET_ADDRESS get sector addressing mode
- HDIO_GET_BUSSTATE get the bus state of the hwif
- HDIO_TRISTATE_HWIF execute a channel tristate
- HDIO_DRIVE_RESET execute a device reset
- HDIO_DRIVE_TASKFILE execute raw taskfile
- 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
- HDIO_SET_32BIT change io_32bit flags
- HDIO_SET_NOWERR change ignore-write-error flag
- HDIO_SET_DMA change use-dma flag
- HDIO_SET_PIO_MODE reconfig interface to new speed
- HDIO_SCAN_HWIF register and (re)scan interface
- HDIO_SET_NICE set nice flags
- HDIO_UNREGISTER_HWIF unregister interface
- HDIO_SET_WCACHE change write cache enable-disable
- HDIO_SET_ACOUSTIC change acoustic behavior
- HDIO_SET_BUSSTATE set the bus state of the hwif
- HDIO_SET_QDMA change use-qdma flag
- HDIO_SET_ADDRESS change lba addressing modes
-
- 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:
-
- Unless otherwise specified, all ioctl calls return 0 on success
- and -1 with errno set to an appropriate value on error.
-
- Unless otherwise specified, all ioctl calls return -1 and set
- errno to EFAULT on a failed attempt to copy data to or from user
- address space.
-
- Unless otherwise specified, all data structures and constants
- are defined in <linux/hdreg.h>
-
-------------------------------------------------------------------------------
-
-HDIO_GETGEO
- get device geometry
-
-
- usage::
-
- struct hd_geometry geom;
-
- ioctl(fd, HDIO_GETGEO, &geom);
-
-
- inputs:
- none
-
-
-
- outputs:
- hd_geometry structure containing:
-
-
- ========= ==================================
- heads number of heads
- sectors number of sectors/track
- cylinders number of cylinders, mod 65536
- start starting sector of this partition.
- ========= ==================================
-
-
- error returns:
- - EINVAL
-
- if the device is not a disk drive or floppy drive,
- 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.
-
- 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.
-
-
-
-
-HDIO_GET_UNMASKINTR
- get current unmask setting
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_GET_UNMASKINTR, &val);
-
- inputs:
- none
-
-
-
- outputs:
- The value of the drive's current unmask setting
-
-
-
-
-
-HDIO_SET_UNMASKINTR
- permit other irqs during I/O
-
-
- usage::
-
- unsigned long val;
-
- ioctl(fd, HDIO_SET_UNMASKINTR, val);
-
- inputs:
- New value for unmask flag
-
-
-
- outputs:
- none
-
-
-
- error return:
- - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- - EACCES Access denied: requires CAP_SYS_ADMIN
- - EINVAL value out of range [0 1]
- - EBUSY Controller busy
-
-
-
-
-HDIO_GET_MULTCOUNT
- get current IDE blockmode setting
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_GET_MULTCOUNT, &val);
-
- inputs:
- none
-
-
-
- outputs:
- 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
-
-
- usage::
-
- int val;
-
- ioctl(fd, HDIO_SET_MULTCOUNT, val);
-
- inputs:
- New value for IDE block mode setting. This controls how many
- sectors the drive will transfer per interrupt.
-
- outputs:
- none
-
-
-
- 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.
-
- notes:
- 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
-
-
-
-HDIO_GET_QDMA
- get use-qdma flag
-
-
- Not implemented, as of 2.6.8.1
-
-
-
-HDIO_SET_XFER
- set transfer rate via proc
-
-
- Not implemented, as of 2.6.8.1
-
-
-
-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
-
-
- usage::
-
- unsigned char identity[512];
-
- ioctl(fd, HDIO_GET_IDENTITY, identity);
-
- inputs:
- none
-
-
-
- outputs:
- ATA drive identity information. For full description, see
- the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
- the ATA specification.
-
- error returns:
- - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- - ENOMSG IDENTIFY DEVICE information not available
-
- 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.
-
- This information is also available from /proc/ide/hdX/identify
-
-
-
-HDIO_GET_KEEPSETTINGS
- get keep-settings-on-reset flag
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
-
- inputs:
- none
-
-
-
- outputs:
- The value of the current "keep settings" flag
-
-
-
- notes:
- When set, indicates that kernel should restore settings
- after a drive reset.
-
-
-
-HDIO_SET_KEEPSETTINGS
- keep ioctl settings on reset
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
-
- inputs:
- New value for keep_settings flag
-
-
-
- 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
-
-
-
-HDIO_GET_32BIT
- get current io_32bit setting
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_GET_32BIT, &val);
-
- inputs:
- none
-
-
-
- outputs:
- The value of the current io_32bit setting
-
-
-
- notes:
- 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
-
-
-
-
-
-HDIO_GET_NOWERR
- get ignore-write-error flag
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_GET_NOWERR, &val);
-
- inputs:
- none
-
-
-
- outputs:
- The value of the current ignore-write-error flag
-
-
-
-
-
-HDIO_GET_DMA
- get use-dma flag
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_GET_DMA, &val);
-
- inputs:
- none
-
-
-
- outputs:
- The value of the current use-dma flag
-
-
-
-
-
-HDIO_GET_NICE
- get nice flags
-
-
- usage::
-
- long nice;
-
- ioctl(fd, HDIO_GET_NICE, &nice);
-
- inputs:
- none
-
-
-
- outputs:
- 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.
-
- See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
-
-
-
-
-HDIO_SET_NICE
- set nice flags
-
-
- usage::
-
- unsigned long nice;
-
- ...
- ioctl(fd, HDIO_SET_NICE, nice);
-
- inputs:
- bitmask of nice flags.
-
-
-
- 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
-
- notes:
- 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.
-
-
-
-
-
-HDIO_GET_WCACHE
- get write cache mode on|off
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_GET_WCACHE, &val);
-
- inputs:
- none
-
-
-
- outputs:
- The value of the current write cache mode
-
-
-
-
-
-HDIO_GET_ACOUSTIC
- get acoustic value
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_GET_ACOUSTIC, &val);
-
- inputs:
- none
-
-
-
- outputs:
- The value of the current acoustic settings
-
-
-
- notes:
- See HDIO_SET_ACOUSTIC
-
-
-
-
-
-HDIO_GET_ADDRESS
- usage::
-
-
- long val;
-
- ioctl(fd, HDIO_GET_ADDRESS, &val);
-
- 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
- = ===================
-
-
-
-HDIO_GET_BUSSTATE
- get the bus state of the hwif
-
-
- usage::
-
- long state;
-
- ioctl(fd, HDIO_SCAN_HWIF, &state);
-
- inputs:
- none
-
-
-
- outputs:
- Current power state of the IDE bus. One of BUSSTATE_OFF,
- BUSSTATE_ON, or BUSSTATE_TRISTATE
-
- error returns:
- - EACCES Access denied: requires CAP_SYS_ADMIN
-
-
-
-
-HDIO_SET_BUSSTATE
- set the bus state of the hwif
-
-
- usage::
-
- int state;
-
- ...
- ioctl(fd, HDIO_SCAN_HWIF, state);
-
- inputs:
- Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON,
- or BUSSTATE_TRISTATE
-
- outputs:
- none
-
-
-
- error returns:
- - EACCES Access denied: requires CAP_SYS_RAWIO
- - EOPNOTSUPP Hardware interface does not support bus power control
-
-
-
-
-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
-
-
- usage::
-
- int args[3]
-
- ...
- ioctl(fd, HDIO_DRIVE_RESET, args);
-
- inputs:
- 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
-
- notes:
-
- - 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.
-
-
-
-HDIO_DRIVE_TASKFILE
- execute raw taskfile
-
-
- Note:
- If you don't have a copy of the ANSI ATA specification
- handy, you should probably ignore this ioctl.
-
- - Execute an ATA disk command directly by writing the "taskfile"
- registers of the drive. Requires ADMIN and RAWIO access
- privileges.
-
- usage::
-
- struct {
-
- ide_task_request_t req_task;
- u8 outbuf[OUTPUT_SIZE];
- u8 inbuf[INPUT_SIZE];
- } task;
- memset(&task.req_task, 0, sizeof(task.req_task));
- task.req_task.out_size = sizeof(task.outbuf);
- task.req_task.in_size = sizeof(task.inbuf);
- ...
- ioctl(fd, HDIO_DRIVE_TASKFILE, &task);
- ...
-
- inputs:
-
- (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
- in_flags flags indicating which registers should be returned
- data_phase see below
- req_cmd command type to be executed
- out_size size of output buffer
- outbuf buffer of data to be transmitted to disk
- inbuf buffer of data to be received from disk (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.
-
- notes:
-
- [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS
- FULL OF GOTCHAS. Extreme caution should be used with using
- this ioctl. A mistake can easily corrupt data or hang the
- system.
-
- [2] Both the input and output buffers are copied from the
- user and written back to the user, even when not used.
-
- [3] If one or more bits are set in out_flags and in_flags is
- zero, the following values are used for in_flags.all and
- written back into in_flags on completion.
-
- * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8)
- if LBA48 addressing is enabled for the drive
- * IDE_TASKFILE_STD_IN_FLAGS
- if CHS/LBA28
-
- The association between in_flags.all and each enable
- bitfield flips depending on endianness; fortunately, TASKFILE
- only uses inflags.b.data bit and ignores all other bits.
- The end result is that, on any endian machines, it has no
- effect other than modifying in_flags on completion.
-
- [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit)
- except for four drives per port chipsets. For four drives
- per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first
- pair and (0x80|DEV_bit|LBA_bit) for the second pair.
-
- [5] The argument to the ioctl is a pointer to a region of
- memory containing a ide_task_request_t structure, followed
- by an optional buffer of data to be transmitted to the
- drive, followed by an optional buffer to receive data from
- the drive.
-
- 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
- contain valid values. Type ide_reg_valid_t.
- in_flags flags indicating which entries in the
- io_ports[] and hob_ports[] arrays
- are expected to contain valid values
- 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
- HOB_LCYL If the drive supports LBA48
- HOB_HCYL If the drive supports LBA48
- FEATURE
- NSECTOR
- SECTOR
- LCYL
- HCYL
- 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.
- DATA If out_flags.b.data is set. DATA will
- travel on DD0-DD7 on little endian machines
- and on DD8-DD15 on big endian machines.
- HOB_NSECTOR If out_flags.b.nsector_hob is set
- HOB_SECTOR If out_flags.b.sector_hob is set
- HOB_LCYL If out_flags.b.lcyl_hob is set
- HOB_HCYL If out_flags.b.hcyl_hob is set
- FEATURE If out_flags.b.feature is set
- NSECTOR If out_flags.b.nsector is set
- SECTOR If out_flags.b.sector is set
- LCYL If out_flags.b.lcyl is set
- 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
- following conditions is met; otherwise, the original values
- will be written back, unchanged.
-
- 1. The drive fails the command (EIO).
- 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.
- DATA If in_flags.b.data is set. It will contain
- DD0-DD7 on little endian machines and
- DD8-DD15 on big endian machines.
- HOB_FEATURE If the drive supports LBA48
- HOB_NSECTOR If the drive supports LBA48
- HOB_SECTOR If the drive supports LBA48
- HOB_LCYL If the drive supports LBA48
- HOB_HCYL If the drive supports LBA48
- NSECTOR
- 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
- TASKFILE_MULTI_OUT
- TASKFILE_IN_OUT
- TASKFILE_IN_DMA
- TASKFILE_IN_DMAQ == IN_DMA (queueing not supported)
- TASKFILE_OUT_DMA
- TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported)
- TASKFILE_P_IN unimplemented
- TASKFILE_P_IN_DMA unimplemented
- TASKFILE_P_IN_DMAQ unimplemented
- TASKFILE_P_OUT unimplemented
- TASKFILE_P_OUT_DMA unimplemented
- TASKFILE_P_OUT_DMAQ unimplemented
- =================== ========================================
-
- The req_cmd field classifies the command type. It may be
- one of:
-
- ======================== =======================================
- 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
- value will flip depending on endianness. For the same
- reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS
- constants defined in hdreg.h.
-
-
-
-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::
-
- u8 args[4+XFER_SIZE];
-
- ...
- ioctl(fd, HDIO_DRIVE_CMD, args);
-
- inputs:
- Commands other than WIN_SMART:
-
- ======= =======
- args[0] COMMAND
- args[1] NSECTOR
- args[2] FEATURE
- args[3] NSECTOR
- ======= =======
-
- WIN_SMART:
-
- ======= =======
- args[0] COMMAND
- args[1] SECTOR
- args[2] FEATURE
- args[3] NSECTOR
- ======= =======
-
- outputs:
- args[] buffer is filled with register values followed by any
-
-
- data returned by the disk.
-
- ======== ====================================================
- args[0] status
- args[1] error
- args[2] NSECTOR
- args[3] undefined
- args[4+] NSECTOR * 512 bytes of data returned by the command.
- ======== ====================================================
-
- error returns:
- - EACCES Access denied: requires CAP_SYS_RAWIO
- - ENOMEM Unable to allocate memory for task
- - EIO Drive reports error
-
- notes:
-
- [1] For commands other than WIN_SMART, args[1] should equal
- args[3]. SECTOR, LCYL and HCYL are undefined. For
- WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL
- respectively. In both cases SELECT will contain the default
- value for the drive. Please refer to HDIO_DRIVE_TASKFILE
- notes for the default value of SELECT.
-
- [2] If NSECTOR value is greater than zero and the drive sets
- DRQ when interrupting for the command, NSECTOR * 512 bytes
- are read from the device into the area following NSECTOR.
- In the above example, the area would be
- args[4..4+XFER_SIZE]. 16bit PIO is used regardless of
- HDIO_SET_32BIT setting.
-
- [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER
- && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA
- mode, IDE driver will try to tune the transfer mode of the
- drive accordingly.
-
-
-
-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::
-
- u8 args[7];
-
- ...
- ioctl(fd, HDIO_DRIVE_TASK, args);
-
- inputs:
- Taskfile register values:
-
- ======= =======
- args[0] COMMAND
- args[1] FEATURE
- args[2] NSECTOR
- args[3] SECTOR
- args[4] LCYL
- args[5] HCYL
- args[6] SELECT
- ======= =======
-
- outputs:
- Taskfile register values:
-
-
- ======= =======
- args[0] status
- args[1] error
- args[2] NSECTOR
- args[3] SECTOR
- 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.
-
- notes:
-
- [1] DEV bit (0x10) of SELECT register is ignored and the
- appropriate value for the drive is used. All other bits
- are used unaltered.
-
-
-
-HDIO_DRIVE_CMD_AEB
- HDIO_DRIVE_TASK
-
-
- Not implemented, as of 2.6.8.1
-
-
-
-HDIO_SET_32BIT
- change io_32bit flags
-
-
- usage::
-
- int val;
-
- ioctl(fd, HDIO_SET_32BIT, val);
-
- inputs:
- New value for io_32bit flag
-
-
-
- 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
-
-
-
-
-HDIO_SET_NOWERR
- change ignore-write-error flag
-
-
- usage::
-
- int val;
-
- ioctl(fd, HDIO_SET_NOWERR, val);
-
- inputs:
- New value for ignore-write-error flag. Used for ignoring
-
-
- WRERR_STAT
-
- 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
-
-
-
-HDIO_SET_DMA
- change use-dma flag
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_SET_DMA, val);
-
- inputs:
- New value for use-dma flag
-
-
-
- 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
-
-
-
-HDIO_SET_PIO_MODE
- reconfig interface to new speed
-
-
- usage::
-
- long val;
-
- ioctl(fd, HDIO_SET_PIO_MODE, val);
-
- inputs:
- New interface speed.
-
-
-
- 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
-
-
-
-HDIO_SCAN_HWIF
- register and (re)scan interface
-
-
- 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
-
-
-
- error returns:
- - EACCES Access denied: requires CAP_SYS_RAWIO
- - EIO Probe failed.
-
- notes:
- This ioctl initializes the addresses and irq for a disk
- controller, probes for drives, and creates /proc/ide
- interfaces as appropriate.
-
-
-
-HDIO_UNREGISTER_HWIF
- unregister interface
-
-
- usage::
-
- int index;
-
- ioctl(fd, HDIO_UNREGISTER_HWIF, index);
-
- inputs:
- index index of hardware interface to unregister
-
-
-
- outputs:
- none
-
-
-
- error returns:
- - EACCES Access denied: requires CAP_SYS_RAWIO
-
- notes:
- This ioctl removes a hardware interface from the kernel.
-
- Currently (2.6.8) this ioctl silently fails if any drive on
- the interface is busy.
-
-
-
-HDIO_SET_WCACHE
- change write cache enable-disable
-
-
- usage::
-
- int val;
-
- ioctl(fd, HDIO_SET_WCACHE, val);
-
- inputs:
- New value for write cache enable
-
-
-
- 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
-
-
-
-HDIO_SET_ACOUSTIC
- change acoustic behavior
-
-
- usage::
-
- int val;
-
- ioctl(fd, HDIO_SET_ACOUSTIC, val);
-
- inputs:
- New value for drive acoustic settings
-
-
-
- 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
-
-
-
-HDIO_SET_QDMA
- change use-qdma flag
-
-
- Not implemented, as of 2.6.8.1
-
-
-
-HDIO_SET_ADDRESS
- change lba addressing modes
-
-
- usage::
-
- int val;
-
- ioctl(fd, HDIO_SET_ADDRESS, val);
-
- inputs:
- New value for addressing mode
-
- = ===================
- 0 28-bit
- 1 48-bit
- 2 48-bit doing 28-bit
- = ===================
-
- outputs:
- none
-
-
-
- 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.
-
-
-HDIO_SET_IDE_SCSI
- usage::
-
-
- long val;
-
- ioctl(fd, HDIO_SET_IDE_SCSI, val);
-
- inputs:
- New value for scsi emulation mode (?)
-
-
-
- outputs:
- none
-
-
-
- error return:
- - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
- - EACCES Access denied: requires CAP_SYS_ADMIN
- - EINVAL value out of range [0 1]
- - EBUSY Controller busy
-
-
-
-HDIO_SET_SCSI_IDE
- Not implemented, as of 2.6.8.1
+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0
-
-======
-IOCTLs
-======
-
-.. toctree::
- :maxdepth: 1
-
- ioctl-number
-
- botching-up-ioctls
- ioctl-decoding
-
- cdrom
- hdio
+++ /dev/null
-==============================
-Decoding an IOCTL Magic Number
-==============================
-
-To decode a hex IOCTL code:
-
-Most architectures use this generic format, but check
-include/ARCH/ioctl.h for specifics, e.g. powerpc
-uses 3 bits to encode read/write and 13 bits for size.
-
- ====== ==================================
- bits meaning
- ====== ==================================
- 31-30 00 - no parameters: uses _IO macro
- 10 - read: _IOR
- 01 - write: _IOW
- 11 - read/write: _IOWR
-
- 29-16 size of arguments
-
- 15-8 ascii character supposedly
- 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::
-
- #define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2])
+++ /dev/null
-=============
-Ioctl Numbers
-=============
-
-19 October 1999
-
-Michael Elizabeth Chastain
-<mec@shout.net>
-
-If you are adding new ioctl's to the kernel, you should use the _IO
-macros defined in <linux/ioctl.h>:
-
- ====== == ============================================
- _IO an ioctl with no parameters
- _IOW an ioctl with write parameters (copy_from_user)
- _IOR an ioctl with read parameters (copy_to_user)
- _IOWR an ioctl with both write and read parameters.
- ====== == ============================================
-
-'Write' and 'read' are from the user's point of view, just like the
-system calls 'write' and 'read'. For example, a SET_FOO ioctl would
-be _IOW, although the kernel would actually read data from user space;
-a GET_FOO ioctl would be _IOR, although the kernel would actually write
-data to user space.
-
-The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter
-or number from the table below. Because of the large number of drivers,
-many drivers share a partial letter with other drivers.
-
-If you are writing a driver for a new device and need a letter, pick an
-unused block with enough room for expansion: 32 to 256 ioctl commands.
-You can register the block by patching this file and submitting the
-patch to Linus Torvalds. Or you can e-mail me at <mec@shout.net> and
-I'll register one for you.
-
-The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number
-to distinguish ioctls from each other. The third argument to _IOW,
-_IOR, or _IOWR is the type of the data going into the kernel or coming
-out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use
-sizeof(arg) as the third argument as this results in your ioctl thinking
-it passes an argument of type size_t.
-
-Some devices use their major number as the identifier; this is OK, as
-long as it is unique. Some devices are irregular and don't follow any
-convention at all.
-
-Following this convention is good because:
-
-(1) Keeping the ioctl's globally unique helps error checking:
- if a program calls an ioctl on the wrong device, it will get an
- error rather than some unexpected behaviour.
-
-(2) The 'strace' build procedure automatically finds ioctl numbers
- defined with _IO, _IOW, _IOR, or _IOWR.
-
-(3) 'strace' can decode numbers back into useful names when the
- numbers are unique.
-
-(4) People looking for ioctls can grep for them more easily when
- this convention is used to define the ioctl numbers.
-
-(5) When following the convention, the driver code can use generic
- code to copy the parameters between user and kernel space.
-
-This table lists ioctls visible from user land for Linux/x86. It contains
-most drivers up to 2.6.31, but I know I am missing some. There has been
-no attempt to list non-X86 architectures or ioctls from drivers/staging/.
-
-==== ===== ======================================================= ================================================================
-Code Seq# Include File Comments
- (hex)
-==== ===== ======================================================= ================================================================
-0x00 00-1F linux/fs.h conflict!
-0x00 00-1F scsi/scsi_ioctl.h conflict!
-0x00 00-1F linux/fb.h conflict!
-0x00 00-1F linux/wavefront.h conflict!
-0x02 all linux/fd.h
-0x03 all linux/hdreg.h
-0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these.
-0x06 all linux/lp.h
-0x09 all linux/raid/md_u.h
-0x10 00-0F drivers/char/s390/vmcp.h
-0x10 10-1F arch/s390/include/uapi/sclp_ctl.h
-0x10 20-2F arch/s390/include/uapi/asm/hypfs.h
-0x12 all linux/fs.h
- linux/blkpg.h
-0x1b all InfiniBand Subsystem
- <http://infiniband.sourceforge.net/>
-0x20 all drivers/cdrom/cm206.h
-0x22 all scsi/sg.h
-'!' 00-1F uapi/linux/seccomp.h
-'#' 00-3F IEEE 1394 Subsystem
- Block for the entire subsystem
-'$' 00-0F linux/perf_counter.h, linux/perf_event.h
-'%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem
- <mailto:alexander.shishkin@linux.intel.com>
-'&' 00-07 drivers/firewire/nosy-user.h
-'1' 00-1F linux/timepps.h PPS kit from Ulrich Windl
- <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/>
-'2' 01-04 linux/i2o.h
-'3' 00-0F drivers/s390/char/raw3270.h conflict!
-'3' 00-1F linux/suspend_ioctls.h, conflict!
- kernel/power/user.c
-'8' all SNP8023 advanced NIC card
- <mailto:mcr@solidum.com>
-';' 64-7F linux/vfio.h
-'@' 00-0F linux/radeonfb.h conflict!
-'@' 00-0F drivers/video/aty/aty128fb.c conflict!
-'A' 00-1F linux/apm_bios.h conflict!
-'A' 00-0F linux/agpgart.h, conflict!
- drivers/char/agp/compat_ioctl.h
-'A' 00-7F sound/asound.h conflict!
-'B' 00-1F linux/cciss_ioctl.h conflict!
-'B' 00-0F include/linux/pmu.h conflict!
-'B' C0-FF advanced bbus <mailto:maassen@uni-freiburg.de>
-'C' all linux/soundcard.h conflict!
-'C' 01-2F linux/capi.h conflict!
-'C' F0-FF drivers/net/wan/cosa.h conflict!
-'D' all arch/s390/include/asm/dasd.h
-'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h
-'D' 05 drivers/scsi/pmcraid.h
-'E' all linux/input.h conflict!
-'E' 00-0F xen/evtchn.h conflict!
-'F' all linux/fb.h conflict!
-'F' 01-02 drivers/scsi/pmcraid.h conflict!
-'F' 20 drivers/video/fsl-diu-fb.h conflict!
-'F' 20 drivers/video/intelfb/intelfb.h conflict!
-'F' 20 linux/ivtvfb.h conflict!
-'F' 20 linux/matroxfb.h conflict!
-'F' 20 drivers/video/aty/atyfb_base.c conflict!
-'F' 00-0F video/da8xx-fb.h conflict!
-'F' 80-8F linux/arcfb.h conflict!
-'F' DD video/sstfb.h conflict!
-'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict!
-'G' 00-0F linux/gigaset_dev.h conflict!
-'H' 00-7F linux/hiddev.h conflict!
-'H' 00-0F linux/hidraw.h conflict!
-'H' 01 linux/mei.h conflict!
-'H' 02 linux/mei.h conflict!
-'H' 03 linux/mei.h conflict!
-'H' 00-0F sound/asound.h conflict!
-'H' 20-40 sound/asound_fm.h conflict!
-'H' 80-8F sound/sfnt_info.h conflict!
-'H' 10-8F sound/emu10k1.h conflict!
-'H' 10-1F sound/sb16_csp.h conflict!
-'H' 10-1F sound/hda_hwdep.h conflict!
-'H' 40-4F sound/hdspm.h conflict!
-'H' 40-4F sound/hdsp.h conflict!
-'H' 90 sound/usb/usx2y/usb_stream.h
-'H' A0 uapi/linux/usb/cdc-wdm.h
-'H' C0-F0 net/bluetooth/hci.h conflict!
-'H' C0-DF net/bluetooth/hidp/hidp.h conflict!
-'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict!
-'H' C0-DF net/bluetooth/bnep/bnep.h conflict!
-'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net>
-'H' F8-FA sound/firewire.h
-'I' all linux/isdn.h conflict!
-'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict!
-'I' 40-4F linux/mISDNif.h conflict!
-'J' 00-1F drivers/scsi/gdth_ioctl.h
-'K' all linux/kd.h
-'L' 00-1F linux/loop.h conflict!
-'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict!
-'L' 20-2F linux/lightnvm.h
-'L' E0-FF linux/ppdd.h encrypted disk device driver
- <http://linux01.gwdg.de/~alatham/ppdd.html>
-'M' all linux/soundcard.h conflict!
-'M' 01-16 mtd/mtd-abi.h conflict!
- and drivers/mtd/mtdchar.c
-'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h
-'M' 00-0F drivers/video/fsl-diu-fb.h conflict!
-'N' 00-1F drivers/usb/scanner.h
-'N' 40-7F drivers/block/nvme.c
-'O' 00-06 mtd/ubi-user.h UBI
-'P' all linux/soundcard.h conflict!
-'P' 60-6F sound/sscape_ioctl.h conflict!
-'P' 00-0F drivers/usb/class/usblp.c conflict!
-'P' 01-09 drivers/misc/pci_endpoint_test.c conflict!
-'Q' all linux/soundcard.h
-'R' 00-1F linux/random.h conflict!
-'R' 01 linux/rfkill.h conflict!
-'R' C0-DF net/bluetooth/rfcomm.h
-'S' all linux/cdrom.h conflict!
-'S' 80-81 scsi/scsi_ioctl.h conflict!
-'S' 82-FF scsi/scsi.h conflict!
-'S' 00-7F sound/asequencer.h conflict!
-'T' all linux/soundcard.h conflict!
-'T' 00-AF sound/asound.h conflict!
-'T' all arch/x86/include/asm/ioctls.h conflict!
-'T' C0-DF linux/if_tun.h conflict!
-'U' all sound/asound.h conflict!
-'U' 00-CF linux/uinput.h conflict!
-'U' 00-EF linux/usbdevice_fs.h
-'U' C0-CF drivers/bluetooth/hci_uart.h
-'V' all linux/vt.h conflict!
-'V' all linux/videodev2.h conflict!
-'V' C0 linux/ivtvfb.h conflict!
-'V' C0 linux/ivtv.h conflict!
-'V' C0 media/davinci/vpfe_capture.h conflict!
-'V' C0 media/si4713.h conflict!
-'W' 00-1F linux/watchdog.h conflict!
-'W' 00-1F linux/wanrouter.h conflict! (pre 3.9)
-'W' 00-3F sound/asound.h conflict!
-'W' 40-5F drivers/pci/switch/switchtec.c
-'X' all fs/xfs/xfs_fs.h, conflict!
- fs/xfs/linux-2.6/xfs_ioctl32.h,
- include/linux/falloc.h,
- linux/fs.h,
-'X' all fs/ocfs2/ocfs_fs.h conflict!
-'X' 01 linux/pktcdvd.h conflict!
-'Y' all linux/cyclades.h
-'Z' 14-15 drivers/message/fusion/mptctl.h
-'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices
- <mailto:gregkh@linuxfoundation.org>
-'a' all linux/atm*.h, linux/sonet.h ATM on linux
- <http://lrcwww.epfl.ch/>
-'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver
-'b' 00-FF conflict! bit3 vme host bridge
- <mailto:natalia@nikhefk.nikhef.nl>
-'c' all linux/cm4000_cs.h conflict!
-'c' 00-7F linux/comstats.h conflict!
-'c' 00-7F linux/coda.h conflict!
-'c' 00-1F linux/chio.h conflict!
-'c' 80-9F arch/s390/include/asm/chsc.h conflict!
-'c' A0-AF arch/x86/include/asm/msr.h conflict!
-'d' 00-FF linux/char/drm/drm.h conflict!
-'d' 02-40 pcmcia/ds.h conflict!
-'d' F0-FF linux/digi1.h
-'e' all linux/digi1.h conflict!
-'f' 00-1F linux/ext2_fs.h conflict!
-'f' 00-1F linux/ext3_fs.h conflict!
-'f' 00-0F fs/jfs/jfs_dinode.h conflict!
-'f' 00-0F fs/ext4/ext4.h conflict!
-'f' 00-0F linux/fs.h conflict!
-'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict!
-'f' 81-8F linux/fsverity.h
-'g' 00-0F linux/usb/gadgetfs.h
-'g' 20-2F linux/usb/g_printer.h
-'h' 00-7F conflict! Charon filesystem
- <mailto:zapman@interlan.net>
-'h' 00-1F linux/hpet.h conflict!
-'h' 80-8F fs/hfsplus/ioctl.c
-'i' 00-3F linux/i2o-dev.h conflict!
-'i' 0B-1F linux/ipmi.h conflict!
-'i' 80-8F linux/i8k.h
-'j' 00-3F linux/joystick.h
-'k' 00-0F linux/spi/spidev.h conflict!
-'k' 00-05 video/kyro.h conflict!
-'k' 10-17 linux/hsi/hsi_char.h HSI character device
-'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system
- <http://web.archive.org/web/%2A/http://mikonos.dia.unisa.it/tcfs>
-'l' 40-7F linux/udf_fs_i.h in development:
- <http://sourceforge.net/projects/linux-udf/>
-'m' 00-09 linux/mmtimer.h conflict!
-'m' all linux/mtio.h conflict!
-'m' all linux/soundcard.h conflict!
-'m' all linux/synclink.h conflict!
-'m' 00-19 drivers/message/fusion/mptctl.h conflict!
-'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict!
-'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c
-'n' 80-8F uapi/linux/nilfs2_api.h NILFS2
-'n' E0-FF linux/matroxfb.h matroxfb
-'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2
-'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps)
-'o' 40-41 mtd/ubi-user.h UBI
-'o' 01-A1 `linux/dvb/*.h` DVB
-'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this)
-'p' 00-1F linux/rtc.h conflict!
-'p' 00-3F linux/mc146818rtc.h conflict!
-'p' 40-7F linux/nvram.h
-'p' 80-9F linux/ppdev.h user-space parport
- <mailto:tim@cyberelk.net>
-'p' A1-A5 linux/pps.h LinuxPPS
- <mailto:giometti@linux.it>
-'q' 00-1F linux/serio.h
-'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK
- linux/ixjuser.h <http://web.archive.org/web/%2A/http://www.quicknet.net>
-'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c
-'s' all linux/cdk.h
-'t' 00-7F linux/ppp-ioctl.h
-'t' 80-8F linux/isdn_ppp.h
-'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM
-'u' 00-1F linux/smb_fs.h gone
-'u' 20-3F linux/uvcvideo.h USB video class host driver
-'u' 40-4f linux/udmabuf.h userspace dma-buf misc device
-'v' 00-1F linux/ext2_fs.h conflict!
-'v' 00-1F linux/fs.h conflict!
-'v' 00-0F linux/sonypi.h conflict!
-'v' 00-0F media/v4l2-subdev.h conflict!
-'v' C0-FF linux/meye.h conflict!
-'w' all CERN SCI driver
-'y' 00-1F packet based user level communications
- <mailto:zapman@interlan.net>
-'z' 00-3F CAN bus card conflict!
- <mailto:hdstich@connectu.ulm.circular.de>
-'z' 40-7F CAN bus card conflict!
- <mailto:oe@port.de>
-'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict!
-'|' 00-7F linux/media.h
-0x80 00-1F linux/fb.h
-0x89 00-06 arch/x86/include/asm/sockios.h
-0x89 0B-DF linux/sockios.h
-0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range
-0x89 E0-EF linux/dn.h PROTOPRIVATE range
-0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range
-0x8B all linux/wireless.h
-0x8C 00-3F WiNRADiO driver
- <http://www.winradio.com.au/>
-0x90 00 drivers/cdrom/sbpcd.h
-0x92 00-0F drivers/usb/mon/mon_bin.c
-0x93 60-7F linux/auto_fs.h
-0x94 all fs/btrfs/ioctl.h Btrfs filesystem
- and linux/fs.h some lifted to vfs/generic
-0x97 00-7F fs/ceph/ioctl.h Ceph file system
-0x99 00-0F 537-Addinboard driver
- <mailto:buk@buks.ipn.de>
-0xA0 all linux/sdp/sdp.h Industrial Device Project
- <mailto:kenji@bitgate.com>
-0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver
-0xA3 80-8F Port ACL in development:
- <mailto:tlewis@mindspring.com>
-0xA3 90-9F linux/dtlk.h
-0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem
-0xAA 00-3F linux/uapi/linux/userfaultfd.h
-0xAB 00-1F linux/nbd.h
-0xAC 00-1F linux/raw.h
-0xAD 00 Netfilter device in development:
- <mailto:rusty@rustcorp.com.au>
-0xAE all linux/kvm.h Kernel-based Virtual Machine
- <mailto:kvm@vger.kernel.org>
-0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor
-0xB0 all RATIO devices in development:
- <mailto:vgo@ratio.de>
-0xB1 00-1F PPPoX
- <mailto:mostrows@styx.uwaterloo.ca>
-0xB3 00 linux/mmc/ioctl.h
-0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org>
-0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org>
-0xB6 all linux/fpga-dfl.h
-0xC0 00-0F linux/usb/iowarrior.h
-0xCA 00-0F uapi/misc/cxl.h
-0xCA 10-2F uapi/misc/ocxl.h
-0xCA 80-BF uapi/scsi/cxlflash_ioctl.h
-0xCB 00-1F CBM serial IEC bus in development:
- <mailto:michael.klein@puffin.lb.shuttle.de>
-0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver
-0xCD 01 linux/reiserfs_fs.h
-0xCF 02 fs/cifs/ioctl.c
-0xDB 00-0F drivers/char/mwave/mwavepub.h
-0xDD 00-3F ZFCP device driver see drivers/s390/scsi/
- <mailto:aherrman@de.ibm.com>
-0xE5 00-3F linux/fuse.h
-0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver
-0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development)
- <mailto:thomas@winischhofer.net>
-0xF4 00-1F video/mbxfb.h mbxfb
- <mailto:raph@8d.com>
-0xF6 all LTTng Linux Trace Toolkit Next Generation
- <mailto:mathieu.desnoyers@efficios.com>
-0xFD all linux/dm-ioctl.h
-0xFE all linux/isst_if.h
-==== ===== ======================================================= ================================================================
drivers access their registers through the same regmap.
For more information regarding the devicetree bindings of the TCU drivers,
-have a look at Documentation/devicetree/bindings/mfd/ingenic,tcu.txt.
+have a look at Documentation/devicetree/bindings/timer/ingenic,tcu.txt.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+====================
+Xilinx SD-FEC Driver
+====================
+
+Overview
+========
+
+This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| RFSoCs.
+
+.. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122
+ .. with trademark sign
+
+For a full description of SD-FEC core features, see the `SD-FEC Product Guide (PG256) <https://www.xilinx.com/cgi-bin/docs/ipdoc?c=sd_fec;v=latest;d=pg256-sdfec-integrated-block.pdf>`_
+
+This driver supports the following features:
+
+ - Retrieval of the Integrated Block configuration and status information
+ - Configuration of LDPC codes
+ - Configuration of Turbo decoding
+ - Monitoring errors
+
+Missing features, known issues, and limitations of the SD-FEC driver are as
+follows:
+
+ - Only allows a single open file handler to any instance of the driver at any time
+ - Reset of the SD-FEC Integrated Block is not controlled by this driver
+ - Does not support shared LDPC code table wraparound
+
+The device tree entry is described in:
+`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt <https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/misc/xlnx%2Csd-fec.txt>`_
+
+
+Modes of Operation
+------------------
+
+The driver works with the SD-FEC core in two modes of operation:
+
+ - Run-time configuration
+ - Programmable Logic (PL) initialization
+
+
+Run-time Configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
+For Run-time configuration the role of driver is to allow the software application to do the following:
+
+ - Load the configuration parameters for either Turbo decode or LDPC encode or decode
+ - Activate the SD-FEC core
+ - Monitor the SD-FEC core for errors
+ - Retrieve the status and configuration of the SD-FEC core
+
+Programmable Logic (PL) Initialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For PL initialization, supporting logic loads configuration parameters for either
+the Turbo decode or LDPC encode or decode. The role of the driver is to allow
+the software application to do the following:
+
+ - Activate the SD-FEC core
+ - Monitor the SD-FEC core for errors
+ - Retrieve the status and configuration of the SD-FEC core
+
+
+Driver Structure
+================
+
+The driver provides a platform device where the ``probe`` and ``remove``
+operations are provided.
+
+ - probe: Updates configuration register with device-tree entries plus determines the current activate state of the core, for example, is the core bypassed or has the core been started.
+
+
+The driver defines the following driver file operations to provide user
+application interfaces:
+
+ - open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time
+ - release: Allows another file descriptor to be open, that is after current file descriptor is closed
+ - poll: Provides a method to monitor for SD-FEC Error events
+ - unlocked_ioctl: Provides the the following ioctl commands that allows the application configure the SD-FEC core:
+
+ - :c:macro:`XSDFEC_START_DEV`
+ - :c:macro:`XSDFEC_STOP_DEV`
+ - :c:macro:`XSDFEC_GET_STATUS`
+ - :c:macro:`XSDFEC_SET_IRQ`
+ - :c:macro:`XSDFEC_SET_TURBO`
+ - :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS`
+ - :c:macro:`XSDFEC_GET_CONFIG`
+ - :c:macro:`XSDFEC_SET_ORDER`
+ - :c:macro:`XSDFEC_SET_BYPASS`
+ - :c:macro:`XSDFEC_IS_ACTIVE`
+ - :c:macro:`XSDFEC_CLEAR_STATS`
+ - :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`
+
+
+Driver Usage
+============
+
+
+Overview
+--------
+
+After opening the driver, the user should find out what operations need to be
+performed to configure and activate the SD-FEC core and determine the
+configuration of the driver.
+The following outlines the flow the user should perform:
+
+ - Determine Configuration
+ - Set the order, if not already configured as desired
+ - Set Turbo decode, LPDC encode or decode parameters, depending on how the
+ SD-FEC core is configured plus if the SD-FEC has not been configured for PL
+ initialization
+ - Enable interrupts, if not already enabled
+ - Bypass the SD-FEC core, if required
+ - Start the SD-FEC core if not already started
+ - Get the SD-FEC core status
+ - Monitor for interrupts
+ - Stop the SD-FEC core
+
+
+Note: When monitoring for interrupts if a critical error is detected where a reset is required, the driver will be required to load the default configuration.
+
+
+Determine Configuration
+-----------------------
+
+Determine the configuration of the SD-FEC core by using the ioctl
+:c:macro:`XSDFEC_GET_CONFIG`.
+
+Set the Order
+-------------
+
+Setting the order determines how the order of Blocks can change from input to output.
+
+Setting the order is done by using the ioctl :c:macro:`XSDFEC_SET_ORDER`
+
+Setting the order can only be done if the following restrictions are met:
+
+ - The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED
+
+
+Add LDPC Codes
+--------------
+
+The following steps indicate how to add LDPC codes to the SD-FEC core:
+
+ - Use the auto-generated parameters to fill the :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>` for the desired LDPC code.
+ - Set the SC, QA, and LA table offsets for the LPDC parameters and the parameters in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>`
+ - Set the desired Code Id value in the structure :c:type:`struct xsdfec_ldpc_params <xsdfec_ldpc_params>`
+ - Add the LPDC Code Parameters using the ioctl :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS`
+ - For the applied LPDC Code Parameter use the function :c:func:`xsdfec_calculate_shared_ldpc_table_entry_size` to calculate the size of shared LPDC code tables. This allows the user to determine the shared table usage so when selecting the table offsets for the next LDPC code parameters unused table areas can be selected.
+ - Repeat for each LDPC code parameter.
+
+Adding LDPC codes can only be done if the following restrictions are met:
+
+ - The ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as LDPC
+ - The ``code_wr_protect`` of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates that write protection is not enabled
+ - The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not started
+
+Set Turbo Decode
+----------------
+
+Configuring the Turbo decode parameters is done by using the ioctl :c:macro:`XSDFEC_SET_TURBO` using auto-generated parameters to fill the :c:type:`struct xsdfec_turbo <xsdfec_turbo>` for the desired Turbo code.
+
+Adding Turbo decode can only be done if the following restrictions are met:
+
+ - The ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as TURBO
+ - The ``state`` member of struct :c:type:`xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED
+
+Enable Interrupts
+-----------------
+
+Enabling or disabling interrupts is done by using the ioctl :c:macro:`XSDFEC_SET_IRQ`. The members of the parameter passed, :c:type:`struct xsdfec_irq <xsdfec_irq>`, to the ioctl are used to set and clear different categories of interrupts. The category of interrupt is controlled as following:
+
+ - ``enable_isr`` controls the ``tlast`` interrupts
+ - ``enable_ecc_isr`` controls the ECC interrupts
+
+If the ``code`` member of :c:type:`struct xsdfec_config <xsdfec_config>` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as TURBO then the enabling ECC errors is not required.
+
+Bypass the SD-FEC
+-----------------
+
+Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS`
+
+Bypassing the SD-FEC can only be done if the following restrictions are met:
+
+ - The ``state`` member of :c:type:`struct xsdfec_status <xsdfec_status>` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED
+
+Start the SD-FEC core
+---------------------
+
+Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV`
+
+Get SD-FEC Status
+-----------------
+
+Get the SD-FEC status of the device by using the ioctl :c:macro:`XSDFEC_GET_STATUS`, which will fill the :c:type:`struct xsdfec_status <xsdfec_status>`
+
+Monitor for Interrupts
+----------------------
+
+ - Use the poll system call to monitor for an interrupt. The poll system call waits for an interrupt to wake it up or times out if no interrupt occurs.
+ - On return Poll ``revents`` will indicate whether stats and/or state have been updated
+ - ``POLLPRI`` indicates a critical error and the user should use :c:macro:`XSDFEC_GET_STATUS` and :c:macro:`XSDFEC_GET_STATS` to confirm
+ - ``POLLRDNORM`` indicates a non-critical error has occurred and the user should use :c:macro:`XSDFEC_GET_STATS` to confirm
+ - Get stats by using the ioctl :c:macro:`XSDFEC_GET_STATS`
+ - For critical error the ``isr_err_count`` or ``uecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero
+ - For non-critical errors the ``cecc_count`` member of :c:type:`struct xsdfec_stats <xsdfec_stats>` is non-zero
+ - Get state by using the ioctl :c:macro:`XSDFEC_GET_STATUS`
+ - For a critical error the ``state`` of :c:type:`xsdfec_status <xsdfec_status>` will indicate a Reset Is Required
+ - Clear stats by using the ioctl :c:macro:`XSDFEC_CLEAR_STATS`
+
+If a critical error is detected where a reset is required. The application is required to call the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`, after the reset and it is not required to call the ioctl :c:macro:`XSDFEC_STOP_DEV`
+
+Note: Using poll system call prevents busy looping using :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS`
+
+Stop the SD-FEC Core
+---------------------
+
+Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV`
+
+Set the Default Configuration
+-----------------------------
+
+Load default configuration by using the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` to restore the driver.
+
+Limitations
+-----------
+
+Users should not duplicate SD-FEC device file handlers, for example fork() or dup() a process that has a created an SD-FEC file handler.
+
+Driver IOCTLs
+==============
+
+.. c:macro:: XSDFEC_START_DEV
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_START_DEV
+
+.. c:macro:: XSDFEC_STOP_DEV
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_STOP_DEV
+
+.. c:macro:: XSDFEC_GET_STATUS
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_GET_STATUS
+
+.. c:macro:: XSDFEC_SET_IRQ
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_SET_IRQ
+
+.. c:macro:: XSDFEC_SET_TURBO
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_SET_TURBO
+
+.. c:macro:: XSDFEC_ADD_LDPC_CODE_PARAMS
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_ADD_LDPC_CODE_PARAMS
+
+.. c:macro:: XSDFEC_GET_CONFIG
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_GET_CONFIG
+
+.. c:macro:: XSDFEC_SET_ORDER
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_SET_ORDER
+
+.. c:macro:: XSDFEC_SET_BYPASS
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_SET_BYPASS
+
+.. c:macro:: XSDFEC_IS_ACTIVE
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_IS_ACTIVE
+
+.. c:macro:: XSDFEC_CLEAR_STATS
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_CLEAR_STATS
+
+.. c:macro:: XSDFEC_GET_STATS
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_GET_STATS
+
+.. c:macro:: XSDFEC_SET_DEFAULT_CONFIG
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :doc: XSDFEC_SET_DEFAULT_CONFIG
+
+Driver Type Definitions
+=======================
+
+.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h
+ :internal:
.. SPDX-License-Identifier: GPL-2.0+
-==============================================================
-Linux* Base Driver for the Intel(R) PRO/100 Family of Adapters
-==============================================================
+=============================================================\r
+Linux Base Driver for the Intel(R) PRO/100 Family of Adapters\r
+=============================================================\r
June 1, 2018
In This Release
===============
-This file describes the Linux* Base Driver for the Intel(R) PRO/100 Family of
+This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of\r
Adapters. This driver includes support for Itanium(R)2-based systems.
For questions related to hardware requirements, refer to the documentation
The latest release of ethtool can be found from
https://www.kernel.org/pub/software/network/ethtool/
-Enabling Wake on LAN* (WoL)
----------------------------
-WoL is provided through the ethtool* utility. For instructions on
+Enabling Wake on LAN (WoL)\r
+--------------------------\r
+WoL is provided through the ethtool utility. For instructions on\r
enabling WoL with ethtool, refer to the ethtool man page. WoL will be
enabled on the system during the next shut down or reboot. For this
driver version, in order to enable WoL, the e100 driver must be loaded
.. SPDX-License-Identifier: GPL-2.0+
-===========================================================
-Linux* Base Driver for Intel(R) Ethernet Network Connection
-===========================================================
+==========================================================\r
+Linux Base Driver for Intel(R) Ethernet Network Connection\r
+==========================================================\r
Intel Gigabit Linux driver.
Copyright(c) 1999 - 2013 Intel Corporation.
The latest release of ethtool can be found from
https://www.kernel.org/pub/software/network/ethtool/
-Enabling Wake on LAN* (WoL)
----------------------------
+Enabling Wake on LAN (WoL)\r
+--------------------------\r
- WoL is configured through the ethtool* utility.
+ WoL is configured through the ethtool utility.\r
WoL will be enabled on the system during the next shut down or reboot.
For this driver version, in order to enable WoL, the e1000 driver must be
.. SPDX-License-Identifier: GPL-2.0+
-======================================================
-Linux* Driver for Intel(R) Ethernet Network Connection
-======================================================
+=====================================================\r
+Linux Driver for Intel(R) Ethernet Network Connection\r
+=====================================================\r
Intel Gigabit Linux driver.
Copyright(c) 2008-2018 Intel Corporation.
manually set devices for 1 Gbps and higher.
Speed, duplex, and autonegotiation advertising are configured through the
-ethtool* utility.
+ethtool utility.\r
Caution: Only experienced network administrators should force speed and duplex
or change autonegotiation advertising manually. The settings at the switch must
operate only in full duplex and only at their native speed.
-Enabling Wake on LAN* (WoL)
----------------------------
-WoL is configured through the ethtool* utility.
+Enabling Wake on LAN (WoL)\r
+--------------------------\r
+WoL is configured through the ethtool utility.\r
WoL will be enabled on the system during the next shut down or reboot. For
this driver version, in order to enable WoL, the e1000e driver must be loaded
.. SPDX-License-Identifier: GPL-2.0+
-==============================================================
-Linux* Base Driver for Intel(R) Ethernet Multi-host Controller
-==============================================================
+=============================================================\r
+Linux Base Driver for Intel(R) Ethernet Multi-host Controller\r
+=============================================================\r
August 20, 2018
Copyright(c) 2015-2018 Intel Corporation.
Known Issues/Troubleshooting
============================
-Enabling SR-IOV in a 64-bit Microsoft* Windows Server* 2012/R2 guest OS under Linux KVM
----------------------------------------------------------------------------------------
+Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS under Linux KVM\r
+-------------------------------------------------------------------------------------\r
KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This
includes traditional PCIe devices, as well as SR-IOV-capable devices based on
the Intel Ethernet Controller XL710.
.. SPDX-License-Identifier: GPL-2.0+
-==================================================================
-Linux* Base Driver for the Intel(R) Ethernet Controller 700 Series
-==================================================================
+=================================================================\r
+Linux Base Driver for the Intel(R) Ethernet Controller 700 Series\r
+=================================================================\r
Intel 40 Gigabit Linux driver.
Copyright(c) 1999-2018 Intel Corporation.
Network Adapter XXV710 based devices.
Speed, duplex, and autonegotiation advertising are configured through the
-ethtool* utility.
+ethtool utility.\r
Caution: Only experienced network administrators should force speed and duplex
or change autonegotiation advertising manually. The settings at the switch must
.. SPDX-License-Identifier: GPL-2.0+
-==================================================================
-Linux* Base Driver for Intel(R) Ethernet Adaptive Virtual Function
-==================================================================
+=================================================================\r
+Linux Base Driver for Intel(R) Ethernet Adaptive Virtual Function\r
+=================================================================\r
Intel Ethernet Adaptive Virtual Function Linux driver.
Copyright(c) 2013-2018 Intel Corporation.
Overview
========
-This file describes the iavf Linux* Base Driver. This driver was formerly
+This file describes the iavf Linux Base Driver. This driver was formerly\r
called i40evf.
The iavf driver supports the below mentioned virtual function devices and
.. SPDX-License-Identifier: GPL-2.0+
-===================================================================
-Linux* Base Driver for the Intel(R) Ethernet Connection E800 Series
-===================================================================
+==================================================================\r
+Linux Base Driver for the Intel(R) Ethernet Connection E800 Series\r
+==================================================================\r
Intel ice Linux driver.
Copyright(c) 2018 Intel Corporation.
.. SPDX-License-Identifier: GPL-2.0+
-===========================================================
-Linux* Base Driver for Intel(R) Ethernet Network Connection
-===========================================================
+==========================================================\r
+Linux Base Driver for Intel(R) Ethernet Network Connection\r
+==========================================================\r
Intel Gigabit Linux driver.
Copyright(c) 1999-2018 Intel Corporation.
https://www.kernel.org/pub/software/network/ethtool/
-Enabling Wake on LAN* (WoL)
----------------------------
-WoL is configured through the ethtool* utility.
+Enabling Wake on LAN (WoL)\r
+--------------------------\r
+WoL is configured through the ethtool utility.\r
WoL will be enabled on the system during the next shut down or reboot. For
this driver version, in order to enable WoL, the igb driver must be loaded
.. SPDX-License-Identifier: GPL-2.0+
-============================================================
-Linux* Base Virtual Function Driver for Intel(R) 1G Ethernet
-============================================================
+===========================================================\r
+Linux Base Virtual Function Driver for Intel(R) 1G Ethernet\r
+===========================================================\r
Intel Gigabit Virtual Function Linux driver.
Copyright(c) 1999-2018 Intel Corporation.
.. SPDX-License-Identifier: GPL-2.0+
-=============================================================================
-Linux* Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters
-=============================================================================
+===========================================================================\r
+Linux Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters\r
+===========================================================================\r
Intel 10 Gigabit Linux driver.
Copyright(c) 1999-2018 Intel Corporation.
Known Issues/Troubleshooting
============================
-Enabling SR-IOV in a 64-bit Microsoft* Windows Server* 2012/R2 guest OS
------------------------------------------------------------------------
+Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS\r
+---------------------------------------------------------------------\r
Linux KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM.
This includes traditional PCIe devices, as well as SR-IOV-capable devices based
on the Intel Ethernet Controller XL710.
.. SPDX-License-Identifier: GPL-2.0+
-=============================================================
-Linux* Base Virtual Function Driver for Intel(R) 10G Ethernet
-=============================================================
+============================================================\r
+Linux Base Virtual Function Driver for Intel(R) 10G Ethernet\r
+============================================================\r
Intel 10 Gigabit Virtual Function Linux driver.
Copyright(c) 1999-2018 Intel Corporation.
================
mlx5 driver provides internal trace points for tracking and debugging using
-kernel tracepoints interfaces (refer to Documentation/trace/ftrase.rst).
+kernel tracepoints interfaces (refer to Documentation/trace/ftrace.rst).
For the list of support mlx5 events check /sys/kernel/debug/tracing/events/mlx5/
.. SPDX-License-Identifier: GPL-2.0+
-==========================================================
-Linux* Driver for the Pensando(R) Ethernet adapter family
-==========================================================
+========================================================\r
+Linux Driver for the Pensando(R) Ethernet adapter family\r
+========================================================\r
Pensando Linux Ethernet driver.
Copyright(c) 2019 Pensando Systems, Inc
links to the description of driver-specific traps registered by various device
drivers:
- * :doc:`/devlink-trap-netdevsim`
+ * :doc:`devlink-trap-netdevsim`
Generic Packet Trap Groups
==========================
electrical signal interface using a synchronous 125Mhz clock signal and several
data lines. Due to this design decision, a 1.5ns to 2ns delay must be added
between the clock line (RXC or TXC) and the data lines to let the PHY (clock
-sink) have enough setup and hold times to sample the data lines correctly. The
+sink) have a large enough setup and hold time to sample the data lines correctly. The
PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let
the PHY driver and optionally the MAC driver, implement the required delay. The
values of phy_interface_t must be understood from the perspective of the PHY
--- /dev/null
+=================================
+(How to avoid) Botching up ioctls
+=================================
+
+From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html
+
+By: Daniel Vetter, Copyright © 2013 Intel Corporation
+
+One clear insight kernel graphics hackers gained in the past few years is that
+trying to come up with a unified interface to manage the execution units and
+memory on completely different GPUs is a futile effort. So nowadays every
+driver has its own set of ioctls to allocate memory and submit work to the GPU.
+Which is nice, since there's no more insanity in the form of fake-generic, but
+actually only used once interfaces. But the clear downside is that there's much
+more potential to screw things up.
+
+To avoid repeating all the same mistakes again I've written up some of the
+lessons learned while botching the job for the drm/i915 driver. Most of these
+only cover technicalities and not the big-picture issues like what the command
+submission ioctl exactly should look like. Learning these lessons is probably
+something every GPU driver has to do on its own.
+
+
+Prerequisites
+-------------
+
+First the prerequisites. Without these you have already failed, because you
+will need to add a 32-bit compat layer:
+
+ * Only use fixed sized integers. To avoid conflicts with typedefs in userspace
+ the kernel has special types like __u32, __s64. Use them.
+
+ * Align everything to the natural size and use explicit padding. 32-bit
+ platforms don't necessarily align 64-bit values to 64-bit boundaries, but
+ 64-bit platforms do. So we always need padding to the natural size to get
+ this right.
+
+ * Pad the entire struct to a multiple of 64-bits if the structure contains
+ 64-bit types - the structure size will otherwise differ on 32-bit versus
+ 64-bit. Having a different structure size hurts when passing arrays of
+ structures to the kernel, or if the kernel checks the structure size, which
+ e.g. the drm core does.
+
+ * Pointers are __u64, cast from/to a uintprt_t on the userspace side and
+ from/to a void __user * in the kernel. Try really hard not to delay this
+ conversion or worse, fiddle the raw __u64 through your code since that
+ diminishes the checking tools like sparse can provide. The macro
+ u64_to_user_ptr can be used in the kernel to avoid warnings about integers
+ and pointers of different sizes.
+
+
+Basics
+------
+
+With the joys of writing a compat layer avoided we can take a look at the basic
+fumbles. Neglecting these will make backward and forward compatibility a real
+pain. And since getting things wrong on the first attempt is guaranteed you
+will have a second iteration or at least an extension for any given interface.
+
+ * Have a clear way for userspace to figure out whether your new ioctl or ioctl
+ extension is supported on a given kernel. If you can't rely on old kernels
+ rejecting the new flags/modes or ioctls (since doing that was botched in the
+ past) then you need a driver feature flag or revision number somewhere.
+
+ * Have a plan for extending ioctls with new flags or new fields at the end of
+ the structure. The drm core checks the passed-in size for each ioctl call
+ and zero-extends any mismatches between kernel and userspace. That helps,
+ but isn't a complete solution since newer userspace on older kernels won't
+ notice that the newly added fields at the end get ignored. So this still
+ needs a new driver feature flags.
+
+ * Check all unused fields and flags and all the padding for whether it's 0,
+ and reject the ioctl if that's not the case. Otherwise your nice plan for
+ future extensions is going right down the gutters since someone will submit
+ an ioctl struct with random stack garbage in the yet unused parts. Which
+ then bakes in the ABI that those fields can never be used for anything else
+ but garbage. This is also the reason why you must explicitly pad all
+ structures, even if you never use them in an array - the padding the compiler
+ might insert could contain garbage.
+
+ * Have simple testcases for all of the above.
+
+
+Fun with Error Paths
+--------------------
+
+Nowadays we don't have any excuse left any more for drm drivers being neat
+little root exploits. This means we both need full input validation and solid
+error handling paths - GPUs will die eventually in the oddmost corner cases
+anyway:
+
+ * The ioctl must check for array overflows. Also it needs to check for
+ over/underflows and clamping issues of integer values in general. The usual
+ example is sprite positioning values fed directly into the hardware with the
+ hardware just having 12 bits or so. Works nicely until some odd display
+ server doesn't bother with clamping itself and the cursor wraps around the
+ screen.
+
+ * Have simple testcases for every input validation failure case in your ioctl.
+ Check that the error code matches your expectations. And finally make sure
+ that you only test for one single error path in each subtest by submitting
+ otherwise perfectly valid data. Without this an earlier check might reject
+ the ioctl already and shadow the codepath you actually want to test, hiding
+ bugs and regressions.
+
+ * Make all your ioctls restartable. First X really loves signals and second
+ this will allow you to test 90% of all error handling paths by just
+ interrupting your main test suite constantly with signals. Thanks to X's
+ love for signal you'll get an excellent base coverage of all your error
+ paths pretty much for free for graphics drivers. Also, be consistent with
+ how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its
+ userspace library. The i915 driver botched this with the set_tiling ioctl,
+ now we're stuck forever with some arcane semantics in both the kernel and
+ userspace.
+
+ * If you can't make a given codepath restartable make a stuck task at least
+ killable. GPUs just die and your users won't like you more if you hang their
+ entire box (by means of an unkillable X process). If the state recovery is
+ still too tricky have a timeout or hangcheck safety net as a last-ditch
+ effort in case the hardware has gone bananas.
+
+ * Have testcases for the really tricky corner cases in your error recovery code
+ - it's way too easy to create a deadlock between your hangcheck code and
+ waiters.
+
+
+Time, Waiting and Missing it
+----------------------------
+
+GPUs do most everything asynchronously, so we have a need to time operations and
+wait for outstanding ones. This is really tricky business; at the moment none of
+the ioctls supported by the drm/i915 get this fully right, which means there's
+still tons more lessons to learn here.
+
+ * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and
+ v4l use by default nowadays. But let userspace know which timestamps are
+ derived from different clock domains like your main system clock (provided
+ by the kernel) or some independent hardware counter somewhere else. Clocks
+ will mismatch if you look close enough, but if performance measuring tools
+ have this information they can at least compensate. If your userspace can
+ get at the raw values of some clocks (e.g. through in-command-stream
+ performance counter sampling instructions) consider exposing those also.
+
+ * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most
+ convenient time specification, but it's mostly the standard.
+
+ * Check that input time values are normalized and reject them if not. Note
+ that the kernel native struct ktime has a signed integer for both seconds
+ and nanoseconds, so beware here.
+
+ * For timeouts, use absolute times. If you're a good fellow and made your
+ ioctl restartable relative timeouts tend to be too coarse and can
+ indefinitely extend your wait time due to rounding on each restart.
+ Especially if your reference clock is something really slow like the display
+ frame counter. With a spec lawyer hat on this isn't a bug since timeouts can
+ always be extended - but users will surely hate you if their neat animations
+ starts to stutter due to this.
+
+ * Consider ditching any synchronous wait ioctls with timeouts and just deliver
+ an asynchronous event on a pollable file descriptor. It fits much better
+ into event driven applications' main loop.
+
+ * Have testcases for corner-cases, especially whether the return values for
+ already-completed events, successful waits and timed-out waits are all sane
+ and suiting to your needs.
+
+
+Leaking Resources, Not
+----------------------
+
+A full-blown drm driver essentially implements a little OS, but specialized to
+the given GPU platforms. This means a driver needs to expose tons of handles
+for different objects and other resources to userspace. Doing that right
+entails its own little set of pitfalls:
+
+ * Always attach the lifetime of your dynamically created resources to the
+ lifetime of a file descriptor. Consider using a 1:1 mapping if your resource
+ needs to be shared across processes - fd-passing over unix domain sockets
+ also simplifies lifetime management for userspace.
+
+ * Always have O_CLOEXEC support.
+
+ * Ensure that you have sufficient insulation between different clients. By
+ default pick a private per-fd namespace which forces any sharing to be done
+ explicitly. Only go with a more global per-device namespace if the objects
+ are truly device-unique. One counterexample in the drm modeset interfaces is
+ that the per-device modeset objects like connectors share a namespace with
+ framebuffer objects, which mostly are not shared at all. A separate
+ namespace, private by default, for framebuffers would have been more
+ suitable.
+
+ * Think about uniqueness requirements for userspace handles. E.g. for most drm
+ drivers it's a userspace bug to submit the same object twice in the same
+ command submission ioctl. But then if objects are shareable userspace needs
+ to know whether it has seen an imported object from a different process
+ already or not. I haven't tried this myself yet due to lack of a new class
+ of objects, but consider using inode numbers on your shared file descriptors
+ as unique identifiers - it's how real files are told apart, too.
+ Unfortunately this requires a full-blown virtual filesystem in the kernel.
+
+
+Last, but not Least
+-------------------
+
+Not every problem needs a new ioctl:
+
+ * Think hard whether you really want a driver-private interface. Of course
+ it's much quicker to push a driver-private interface than engaging in
+ lengthy discussions for a more generic solution. And occasionally doing a
+ private interface to spearhead a new concept is what's required. But in the
+ end, once the generic interface comes around you'll end up maintainer two
+ interfaces. Indefinitely.
+
+ * Consider other interfaces than ioctls. A sysfs attribute is much better for
+ per-device settings, or for child objects with fairly static lifetimes (like
+ output connectors in drm with all the detection override attributes). Or
+ maybe only your testsuite needs this interface, and then debugfs with its
+ disclaimer of not having a stable ABI would be better.
+
+Finally, the name of the game is to get it right on the first attempt, since if
+your driver proves popular and your hardware platforms long-lived then you'll
+be stuck with a given ioctl essentially forever. You can try to deprecate
+horrible ioctls on newer iterations of your hardware, but generally it takes
+years to accomplish this. And then again years until the last user able to
+complain about regressions disappears, too.
kernel-docs
deprecated
embargoed-hardware-issues
+ maintainers
These are some overall technical guides that have been put here for now for
lack of a better place.
adding-syscalls
magic-number
volatile-considered-harmful
+ botching-up-ioctls
clang-format
.. only:: subproject and html
--- /dev/null
+.. maintainers-include::
u32 res1 = 0; /* Reserved */
u64 res2 = 0; /* Reserved */
u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */
- u32 magic2 = 0x56534905; /* Magic number 2, little endian, "RSC\x05" */
+ u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */
u32 res4; /* Reserved for PE COFF offset */
This header format is compliant with PE/COFF header and largely inspired from
the change in the counters at each subsequent observation. A perl script
which does this for many of the fields is available at
- http://eaglet.rain.com/rick/linux/schedstat/
+ http://eaglet.pdxhosts.com/rick/linux/schedstat/
Note that any such script will necessarily be version-specific, as the main
reason to change versions is changes in the output format. For those wishing
under the scheduler's policies. A simple version of such a program is
available at
- http://eaglet.rain.com/rick/linux/schedstat/v12/latency.c
+ http://eaglet.pdxhosts.com/rick/linux/schedstat/v12/latency.c
also moves most of the capabilities logic into an optional security
module, with the system defaulting to the traditional superuser logic.
This capabilities module is discussed further in
-`LSM Capabilities Module <#cap>`__.
+`LSM Capabilities Module`_.
The LSM kernel patch adds security fields to kernel data structures and
inserts calls to hook functions at critical points in the kernel code to
line-height: normal;
}
+/* Keep fields from being strangely far apart due to inheirited table CSS. */
+.rst-content table.field-list th.field-name {
+ padding-top: 1px;
+ padding-bottom: 1px;
+}
+.rst-content table.field-list td.field-body {
+ padding-top: 1px;
+ padding-bottom: 1px;
+}
+
@media screen {
/* content column
--- /dev/null
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0
+# -*- coding: utf-8; mode: python -*-
+# pylint: disable=R0903, C0330, R0914, R0912, E0401
+
+u"""
+ maintainers-include
+ ~~~~~~~~~~~~~~~~~~~
+
+ Implementation of the ``maintainers-include`` reST-directive.
+
+ :copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org>
+ :license: GPL Version 2, June 1991 see linux/COPYING for details.
+
+ The ``maintainers-include`` reST-directive performs extensive parsing
+ specific to the Linux kernel's standard "MAINTAINERS" file, in an
+ effort to avoid needing to heavily mark up the original plain text.
+"""
+
+import sys
+import re
+import os.path
+
+from docutils import statemachine
+from docutils.utils.error_reporting import ErrorString
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst.directives.misc import Include
+
+__version__ = '1.0'
+
+def setup(app):
+ app.add_directive("maintainers-include", MaintainersInclude)
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
+
+class MaintainersInclude(Include):
+ u"""MaintainersInclude (``maintainers-include``) directive"""
+ required_arguments = 0
+
+ def parse_maintainers(self, path):
+ """Parse all the MAINTAINERS lines into ReST for human-readability"""
+
+ result = list()
+ result.append(".. _maintainers:")
+ result.append("")
+
+ # Poor man's state machine.
+ descriptions = False
+ maintainers = False
+ subsystems = False
+
+ # Field letter to field name mapping.
+ field_letter = None
+ fields = dict()
+
+ prev = None
+ field_prev = ""
+ field_content = ""
+
+ for line in open(path):
+ if sys.version_info.major == 2:
+ line = unicode(line, 'utf-8')
+ # Have we reached the end of the preformatted Descriptions text?
+ if descriptions and line.startswith('Maintainers'):
+ descriptions = False
+ # Ensure a blank line following the last "|"-prefixed line.
+ result.append("")
+
+ # Start subsystem processing? This is to skip processing the text
+ # between the Maintainers heading and the first subsystem name.
+ if maintainers and not subsystems:
+ if re.search('^[A-Z0-9]', line):
+ subsystems = True
+
+ # Drop needless input whitespace.
+ line = line.rstrip()
+
+ # Linkify all non-wildcard refs to ReST files in Documentation/.
+ pat = '(Documentation/([^\s\?\*]*)\.rst)'
+ m = re.search(pat, line)
+ if m:
+ # maintainers.rst is in a subdirectory, so include "../".
+ line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
+
+ # Check state machine for output rendering behavior.
+ output = None
+ if descriptions:
+ # Escape the escapes in preformatted text.
+ output = "| %s" % (line.replace("\\", "\\\\"))
+ # Look for and record field letter to field name mappings:
+ # R: Designated *reviewer*: FullName <address@domain>
+ m = re.search("\s(\S):\s", line)
+ if m:
+ field_letter = m.group(1)
+ if field_letter and not field_letter in fields:
+ m = re.search("\*([^\*]+)\*", line)
+ if m:
+ fields[field_letter] = m.group(1)
+ elif subsystems:
+ # Skip empty lines: subsystem parser adds them as needed.
+ if len(line) == 0:
+ continue
+ # Subsystem fields are batched into "field_content"
+ if line[1] != ':':
+ # Render a subsystem entry as:
+ # SUBSYSTEM NAME
+ # ~~~~~~~~~~~~~~
+
+ # Flush pending field content.
+ output = field_content + "\n\n"
+ field_content = ""
+
+ # Collapse whitespace in subsystem name.
+ heading = re.sub("\s+", " ", line)
+ output = output + "%s\n%s" % (heading, "~" * len(heading))
+ field_prev = ""
+ else:
+ # Render a subsystem field as:
+ # :Field: entry
+ # entry...
+ field, details = line.split(':', 1)
+ details = details.strip()
+
+ # Mark paths (and regexes) as literal text for improved
+ # readability and to escape any escapes.
+ if field in ['F', 'N', 'X', 'K']:
+ # But only if not already marked :)
+ if not ':doc:' in details:
+ details = '``%s``' % (details)
+
+ # Comma separate email field continuations.
+ if field == field_prev and field_prev in ['M', 'R', 'L']:
+ field_content = field_content + ","
+
+ # Do not repeat field names, so that field entries
+ # will be collapsed together.
+ if field != field_prev:
+ output = field_content + "\n"
+ field_content = ":%s:" % (fields.get(field, field))
+ field_content = field_content + "\n\t%s" % (details)
+ field_prev = field
+ else:
+ output = line
+
+ # Re-split on any added newlines in any above parsing.
+ if output != None:
+ for separated in output.split('\n'):
+ result.append(separated)
+
+ # Update the state machine when we find heading separators.
+ if line.startswith('----------'):
+ if prev.startswith('Descriptions'):
+ descriptions = True
+ if prev.startswith('Maintainers'):
+ maintainers = True
+
+ # Retain previous line for state machine transitions.
+ prev = line
+
+ # Flush pending field contents.
+ if field_content != "":
+ for separated in field_content.split('\n'):
+ result.append(separated)
+
+ output = "\n".join(result)
+ # For debugging the pre-rendered results...
+ #print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
+
+ self.state_machine.insert_input(
+ statemachine.string2lines(output), path)
+
+ def run(self):
+ """Include the MAINTAINERS file as part of this reST file."""
+ if not self.state.document.settings.file_insertion_enabled:
+ raise self.warning('"%s" directive disabled.' % self.name)
+
+ # Walk up source path directories to find Documentation/../
+ path = self.state_machine.document.attributes['source']
+ path = os.path.realpath(path)
+ tail = path
+ while tail != "Documentation" and tail != "":
+ (path, tail) = os.path.split(path)
+
+ # Append "MAINTAINERS"
+ path = os.path.join(path, "MAINTAINERS")
+
+ try:
+ self.state.document.settings.record_dependencies.add(path)
+ lines = self.parse_maintainers(path)
+ except IOError as error:
+ raise self.severe('Problems with "%s" directive path:\n%s.' %
+ (self.name, ErrorString(error)))
+
+ return []
`GnuK`_ della FSIJ. Questo è uno dei pochi dispositivi a supportare le chiavi
ECC ED25519, ma offre meno funzionalità di sicurezza (come la resistenza
alla manomissione o alcuni attacchi ad un canale laterale).
-- `Nitrokey Pro`_: è simile alla Nitrokey Start, ma è più resistente alla
+- `Nitrokey Pro 2`_: è simile alla Nitrokey Start, ma è più resistente alla
manomissione e offre più funzionalità di sicurezza. La Pro 2 supporta la
crittografia ECC (NISTP).
- `Yubikey 5`_: l'hardware e il software sono proprietari, ma è più economica
unshare
spec_ctrl
accelerators/ocxl
+ ioctl/index
.. only:: subproject and html
--- /dev/null
+============================
+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.
--- /dev/null
+==============================
+Summary of `HDIO_` ioctl calls
+==============================
+
+- Edward A. Falk <efalk@google.com>
+
+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)
+in drivers/ide/ide.c and drivers/block/scsi_ioctl.c
+
+ioctl values are listed in <linux/hdreg.h>. As of this writing, they
+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
+ HDIO_GET_QDMA get use-qdma flag
+ HDIO_SET_XFER set transfer rate via proc
+ HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE
+ HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag
+ HDIO_GET_32BIT get current io_32bit setting
+ HDIO_GET_NOWERR get ignore-write-error flag
+ HDIO_GET_DMA get use-dma flag
+ HDIO_GET_NICE get nice flags
+ HDIO_GET_IDENTITY get IDE identification info
+ HDIO_GET_WCACHE get write cache mode on|off
+ HDIO_GET_ACOUSTIC get acoustic value
+ HDIO_GET_ADDRESS get sector addressing mode
+ HDIO_GET_BUSSTATE get the bus state of the hwif
+ HDIO_TRISTATE_HWIF execute a channel tristate
+ HDIO_DRIVE_RESET execute a device reset
+ HDIO_DRIVE_TASKFILE execute raw taskfile
+ 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
+ HDIO_SET_32BIT change io_32bit flags
+ HDIO_SET_NOWERR change ignore-write-error flag
+ HDIO_SET_DMA change use-dma flag
+ HDIO_SET_PIO_MODE reconfig interface to new speed
+ HDIO_SCAN_HWIF register and (re)scan interface
+ HDIO_SET_NICE set nice flags
+ HDIO_UNREGISTER_HWIF unregister interface
+ HDIO_SET_WCACHE change write cache enable-disable
+ HDIO_SET_ACOUSTIC change acoustic behavior
+ HDIO_SET_BUSSTATE set the bus state of the hwif
+ HDIO_SET_QDMA change use-qdma flag
+ HDIO_SET_ADDRESS change lba addressing modes
+
+ 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:
+
+ Unless otherwise specified, all ioctl calls return 0 on success
+ and -1 with errno set to an appropriate value on error.
+
+ Unless otherwise specified, all ioctl calls return -1 and set
+ errno to EFAULT on a failed attempt to copy data to or from user
+ address space.
+
+ Unless otherwise specified, all data structures and constants
+ are defined in <linux/hdreg.h>
+
+------------------------------------------------------------------------------
+
+HDIO_GETGEO
+ get device geometry
+
+
+ usage::
+
+ struct hd_geometry geom;
+
+ ioctl(fd, HDIO_GETGEO, &geom);
+
+
+ inputs:
+ none
+
+
+
+ outputs:
+ hd_geometry structure containing:
+
+
+ ========= ==================================
+ heads number of heads
+ sectors number of sectors/track
+ cylinders number of cylinders, mod 65536
+ start starting sector of this partition.
+ ========= ==================================
+
+
+ error returns:
+ - EINVAL
+
+ if the device is not a disk drive or floppy drive,
+ 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.
+
+ 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.
+
+
+
+
+HDIO_GET_UNMASKINTR
+ get current unmask setting
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_GET_UNMASKINTR, &val);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ The value of the drive's current unmask setting
+
+
+
+
+
+HDIO_SET_UNMASKINTR
+ permit other irqs during I/O
+
+
+ usage::
+
+ unsigned long val;
+
+ ioctl(fd, HDIO_SET_UNMASKINTR, val);
+
+ inputs:
+ New value for unmask flag
+
+
+
+ outputs:
+ none
+
+
+
+ error return:
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
+
+
+
+
+HDIO_GET_MULTCOUNT
+ get current IDE blockmode setting
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_GET_MULTCOUNT, &val);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ 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
+
+
+ usage::
+
+ int val;
+
+ ioctl(fd, HDIO_SET_MULTCOUNT, val);
+
+ inputs:
+ New value for IDE block mode setting. This controls how many
+ sectors the drive will transfer per interrupt.
+
+ outputs:
+ none
+
+
+
+ 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.
+
+ notes:
+ 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
+
+
+
+HDIO_GET_QDMA
+ get use-qdma flag
+
+
+ Not implemented, as of 2.6.8.1
+
+
+
+HDIO_SET_XFER
+ set transfer rate via proc
+
+
+ Not implemented, as of 2.6.8.1
+
+
+
+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
+
+
+ usage::
+
+ unsigned char identity[512];
+
+ ioctl(fd, HDIO_GET_IDENTITY, identity);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ ATA drive identity information. For full description, see
+ the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in
+ the ATA specification.
+
+ error returns:
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - ENOMSG IDENTIFY DEVICE information not available
+
+ 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.
+
+ This information is also available from /proc/ide/hdX/identify
+
+
+
+HDIO_GET_KEEPSETTINGS
+ get keep-settings-on-reset flag
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_GET_KEEPSETTINGS, &val);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ The value of the current "keep settings" flag
+
+
+
+ notes:
+ When set, indicates that kernel should restore settings
+ after a drive reset.
+
+
+
+HDIO_SET_KEEPSETTINGS
+ keep ioctl settings on reset
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_SET_KEEPSETTINGS, val);
+
+ inputs:
+ New value for keep_settings flag
+
+
+
+ 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
+
+
+
+HDIO_GET_32BIT
+ get current io_32bit setting
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_GET_32BIT, &val);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ The value of the current io_32bit setting
+
+
+
+ notes:
+ 0=16-bit, 1=32-bit, 2,3 = 32bit+sync
+
+
+
+
+
+HDIO_GET_NOWERR
+ get ignore-write-error flag
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_GET_NOWERR, &val);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ The value of the current ignore-write-error flag
+
+
+
+
+
+HDIO_GET_DMA
+ get use-dma flag
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_GET_DMA, &val);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ The value of the current use-dma flag
+
+
+
+
+
+HDIO_GET_NICE
+ get nice flags
+
+
+ usage::
+
+ long nice;
+
+ ioctl(fd, HDIO_GET_NICE, &nice);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ 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.
+
+ See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP.
+
+
+
+
+HDIO_SET_NICE
+ set nice flags
+
+
+ usage::
+
+ unsigned long nice;
+
+ ...
+ ioctl(fd, HDIO_SET_NICE, nice);
+
+ inputs:
+ bitmask of nice flags.
+
+
+
+ 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
+
+ notes:
+ 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.
+
+
+
+
+
+HDIO_GET_WCACHE
+ get write cache mode on|off
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_GET_WCACHE, &val);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ The value of the current write cache mode
+
+
+
+
+
+HDIO_GET_ACOUSTIC
+ get acoustic value
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_GET_ACOUSTIC, &val);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ The value of the current acoustic settings
+
+
+
+ notes:
+ See HDIO_SET_ACOUSTIC
+
+
+
+
+
+HDIO_GET_ADDRESS
+ usage::
+
+
+ long val;
+
+ ioctl(fd, HDIO_GET_ADDRESS, &val);
+
+ 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
+ = ===================
+
+
+
+HDIO_GET_BUSSTATE
+ get the bus state of the hwif
+
+
+ usage::
+
+ long state;
+
+ ioctl(fd, HDIO_SCAN_HWIF, &state);
+
+ inputs:
+ none
+
+
+
+ outputs:
+ Current power state of the IDE bus. One of BUSSTATE_OFF,
+ BUSSTATE_ON, or BUSSTATE_TRISTATE
+
+ error returns:
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+
+
+
+
+HDIO_SET_BUSSTATE
+ set the bus state of the hwif
+
+
+ usage::
+
+ int state;
+
+ ...
+ ioctl(fd, HDIO_SCAN_HWIF, state);
+
+ inputs:
+ Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON,
+ or BUSSTATE_TRISTATE
+
+ outputs:
+ none
+
+
+
+ error returns:
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - EOPNOTSUPP Hardware interface does not support bus power control
+
+
+
+
+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
+
+
+ usage::
+
+ int args[3]
+
+ ...
+ ioctl(fd, HDIO_DRIVE_RESET, args);
+
+ inputs:
+ 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
+
+ notes:
+
+ - 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.
+
+
+
+HDIO_DRIVE_TASKFILE
+ execute raw taskfile
+
+
+ Note:
+ If you don't have a copy of the ANSI ATA specification
+ handy, you should probably ignore this ioctl.
+
+ - Execute an ATA disk command directly by writing the "taskfile"
+ registers of the drive. Requires ADMIN and RAWIO access
+ privileges.
+
+ usage::
+
+ struct {
+
+ ide_task_request_t req_task;
+ u8 outbuf[OUTPUT_SIZE];
+ u8 inbuf[INPUT_SIZE];
+ } task;
+ memset(&task.req_task, 0, sizeof(task.req_task));
+ task.req_task.out_size = sizeof(task.outbuf);
+ task.req_task.in_size = sizeof(task.inbuf);
+ ...
+ ioctl(fd, HDIO_DRIVE_TASKFILE, &task);
+ ...
+
+ inputs:
+
+ (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
+ in_flags flags indicating which registers should be returned
+ data_phase see below
+ req_cmd command type to be executed
+ out_size size of output buffer
+ outbuf buffer of data to be transmitted to disk
+ inbuf buffer of data to be received from disk (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.
+
+ notes:
+
+ [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS
+ FULL OF GOTCHAS. Extreme caution should be used with using
+ this ioctl. A mistake can easily corrupt data or hang the
+ system.
+
+ [2] Both the input and output buffers are copied from the
+ user and written back to the user, even when not used.
+
+ [3] If one or more bits are set in out_flags and in_flags is
+ zero, the following values are used for in_flags.all and
+ written back into in_flags on completion.
+
+ * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8)
+ if LBA48 addressing is enabled for the drive
+ * IDE_TASKFILE_STD_IN_FLAGS
+ if CHS/LBA28
+
+ The association between in_flags.all and each enable
+ bitfield flips depending on endianness; fortunately, TASKFILE
+ only uses inflags.b.data bit and ignores all other bits.
+ The end result is that, on any endian machines, it has no
+ effect other than modifying in_flags on completion.
+
+ [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit)
+ except for four drives per port chipsets. For four drives
+ per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first
+ pair and (0x80|DEV_bit|LBA_bit) for the second pair.
+
+ [5] The argument to the ioctl is a pointer to a region of
+ memory containing a ide_task_request_t structure, followed
+ by an optional buffer of data to be transmitted to the
+ drive, followed by an optional buffer to receive data from
+ the drive.
+
+ 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
+ contain valid values. Type ide_reg_valid_t.
+ in_flags flags indicating which entries in the
+ io_ports[] and hob_ports[] arrays
+ are expected to contain valid values
+ 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
+ HOB_LCYL If the drive supports LBA48
+ HOB_HCYL If the drive supports LBA48
+ FEATURE
+ NSECTOR
+ SECTOR
+ LCYL
+ HCYL
+ 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.
+ DATA If out_flags.b.data is set. DATA will
+ travel on DD0-DD7 on little endian machines
+ and on DD8-DD15 on big endian machines.
+ HOB_NSECTOR If out_flags.b.nsector_hob is set
+ HOB_SECTOR If out_flags.b.sector_hob is set
+ HOB_LCYL If out_flags.b.lcyl_hob is set
+ HOB_HCYL If out_flags.b.hcyl_hob is set
+ FEATURE If out_flags.b.feature is set
+ NSECTOR If out_flags.b.nsector is set
+ SECTOR If out_flags.b.sector is set
+ LCYL If out_flags.b.lcyl is set
+ 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
+ following conditions is met; otherwise, the original values
+ will be written back, unchanged.
+
+ 1. The drive fails the command (EIO).
+ 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.
+ DATA If in_flags.b.data is set. It will contain
+ DD0-DD7 on little endian machines and
+ DD8-DD15 on big endian machines.
+ HOB_FEATURE If the drive supports LBA48
+ HOB_NSECTOR If the drive supports LBA48
+ HOB_SECTOR If the drive supports LBA48
+ HOB_LCYL If the drive supports LBA48
+ HOB_HCYL If the drive supports LBA48
+ NSECTOR
+ 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
+ TASKFILE_MULTI_OUT
+ TASKFILE_IN_OUT
+ TASKFILE_IN_DMA
+ TASKFILE_IN_DMAQ == IN_DMA (queueing not supported)
+ TASKFILE_OUT_DMA
+ TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported)
+ TASKFILE_P_IN unimplemented
+ TASKFILE_P_IN_DMA unimplemented
+ TASKFILE_P_IN_DMAQ unimplemented
+ TASKFILE_P_OUT unimplemented
+ TASKFILE_P_OUT_DMA unimplemented
+ TASKFILE_P_OUT_DMAQ unimplemented
+ =================== ========================================
+
+ The req_cmd field classifies the command type. It may be
+ one of:
+
+ ======================== =======================================
+ 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
+ value will flip depending on endianness. For the same
+ reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS
+ constants defined in hdreg.h.
+
+
+
+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::
+
+ u8 args[4+XFER_SIZE];
+
+ ...
+ ioctl(fd, HDIO_DRIVE_CMD, args);
+
+ inputs:
+ Commands other than WIN_SMART:
+
+ ======= =======
+ args[0] COMMAND
+ args[1] NSECTOR
+ args[2] FEATURE
+ args[3] NSECTOR
+ ======= =======
+
+ WIN_SMART:
+
+ ======= =======
+ args[0] COMMAND
+ args[1] SECTOR
+ args[2] FEATURE
+ args[3] NSECTOR
+ ======= =======
+
+ outputs:
+ args[] buffer is filled with register values followed by any
+
+
+ data returned by the disk.
+
+ ======== ====================================================
+ args[0] status
+ args[1] error
+ args[2] NSECTOR
+ args[3] undefined
+ args[4+] NSECTOR * 512 bytes of data returned by the command.
+ ======== ====================================================
+
+ error returns:
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - ENOMEM Unable to allocate memory for task
+ - EIO Drive reports error
+
+ notes:
+
+ [1] For commands other than WIN_SMART, args[1] should equal
+ args[3]. SECTOR, LCYL and HCYL are undefined. For
+ WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL
+ respectively. In both cases SELECT will contain the default
+ value for the drive. Please refer to HDIO_DRIVE_TASKFILE
+ notes for the default value of SELECT.
+
+ [2] If NSECTOR value is greater than zero and the drive sets
+ DRQ when interrupting for the command, NSECTOR * 512 bytes
+ are read from the device into the area following NSECTOR.
+ In the above example, the area would be
+ args[4..4+XFER_SIZE]. 16bit PIO is used regardless of
+ HDIO_SET_32BIT setting.
+
+ [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER
+ && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA
+ mode, IDE driver will try to tune the transfer mode of the
+ drive accordingly.
+
+
+
+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::
+
+ u8 args[7];
+
+ ...
+ ioctl(fd, HDIO_DRIVE_TASK, args);
+
+ inputs:
+ Taskfile register values:
+
+ ======= =======
+ args[0] COMMAND
+ args[1] FEATURE
+ args[2] NSECTOR
+ args[3] SECTOR
+ args[4] LCYL
+ args[5] HCYL
+ args[6] SELECT
+ ======= =======
+
+ outputs:
+ Taskfile register values:
+
+
+ ======= =======
+ args[0] status
+ args[1] error
+ args[2] NSECTOR
+ args[3] SECTOR
+ 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.
+
+ notes:
+
+ [1] DEV bit (0x10) of SELECT register is ignored and the
+ appropriate value for the drive is used. All other bits
+ are used unaltered.
+
+
+
+HDIO_DRIVE_CMD_AEB
+ HDIO_DRIVE_TASK
+
+
+ Not implemented, as of 2.6.8.1
+
+
+
+HDIO_SET_32BIT
+ change io_32bit flags
+
+
+ usage::
+
+ int val;
+
+ ioctl(fd, HDIO_SET_32BIT, val);
+
+ inputs:
+ New value for io_32bit flag
+
+
+
+ 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
+
+
+
+
+HDIO_SET_NOWERR
+ change ignore-write-error flag
+
+
+ usage::
+
+ int val;
+
+ ioctl(fd, HDIO_SET_NOWERR, val);
+
+ inputs:
+ New value for ignore-write-error flag. Used for ignoring
+
+
+ WRERR_STAT
+
+ 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
+
+
+
+HDIO_SET_DMA
+ change use-dma flag
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_SET_DMA, val);
+
+ inputs:
+ New value for use-dma flag
+
+
+
+ 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
+
+
+
+HDIO_SET_PIO_MODE
+ reconfig interface to new speed
+
+
+ usage::
+
+ long val;
+
+ ioctl(fd, HDIO_SET_PIO_MODE, val);
+
+ inputs:
+ New interface speed.
+
+
+
+ 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
+
+
+
+HDIO_SCAN_HWIF
+ register and (re)scan interface
+
+
+ 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
+
+
+
+ error returns:
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+ - EIO Probe failed.
+
+ notes:
+ This ioctl initializes the addresses and irq for a disk
+ controller, probes for drives, and creates /proc/ide
+ interfaces as appropriate.
+
+
+
+HDIO_UNREGISTER_HWIF
+ unregister interface
+
+
+ usage::
+
+ int index;
+
+ ioctl(fd, HDIO_UNREGISTER_HWIF, index);
+
+ inputs:
+ index index of hardware interface to unregister
+
+
+
+ outputs:
+ none
+
+
+
+ error returns:
+ - EACCES Access denied: requires CAP_SYS_RAWIO
+
+ notes:
+ This ioctl removes a hardware interface from the kernel.
+
+ Currently (2.6.8) this ioctl silently fails if any drive on
+ the interface is busy.
+
+
+
+HDIO_SET_WCACHE
+ change write cache enable-disable
+
+
+ usage::
+
+ int val;
+
+ ioctl(fd, HDIO_SET_WCACHE, val);
+
+ inputs:
+ New value for write cache enable
+
+
+
+ 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
+
+
+
+HDIO_SET_ACOUSTIC
+ change acoustic behavior
+
+
+ usage::
+
+ int val;
+
+ ioctl(fd, HDIO_SET_ACOUSTIC, val);
+
+ inputs:
+ New value for drive acoustic settings
+
+
+
+ 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
+
+
+
+HDIO_SET_QDMA
+ change use-qdma flag
+
+
+ Not implemented, as of 2.6.8.1
+
+
+
+HDIO_SET_ADDRESS
+ change lba addressing modes
+
+
+ usage::
+
+ int val;
+
+ ioctl(fd, HDIO_SET_ADDRESS, val);
+
+ inputs:
+ New value for addressing mode
+
+ = ===================
+ 0 28-bit
+ 1 48-bit
+ 2 48-bit doing 28-bit
+ = ===================
+
+ outputs:
+ none
+
+
+
+ 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.
+
+
+HDIO_SET_IDE_SCSI
+ usage::
+
+
+ long val;
+
+ ioctl(fd, HDIO_SET_IDE_SCSI, val);
+
+ inputs:
+ New value for scsi emulation mode (?)
+
+
+
+ outputs:
+ none
+
+
+
+ error return:
+ - EINVAL (bdev != bdev->bd_contains) (not sure what this means)
+ - EACCES Access denied: requires CAP_SYS_ADMIN
+ - EINVAL value out of range [0 1]
+ - EBUSY Controller busy
+
+
+
+HDIO_SET_SCSI_IDE
+ Not implemented, as of 2.6.8.1
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0
+
+======
+IOCTLs
+======
+
+.. toctree::
+ :maxdepth: 1
+
+ ioctl-number
+
+ ioctl-decoding
+
+ cdrom
+ hdio
--- /dev/null
+==============================
+Decoding an IOCTL Magic Number
+==============================
+
+To decode a hex IOCTL code:
+
+Most architectures use this generic format, but check
+include/ARCH/ioctl.h for specifics, e.g. powerpc
+uses 3 bits to encode read/write and 13 bits for size.
+
+ ====== ==================================
+ bits meaning
+ ====== ==================================
+ 31-30 00 - no parameters: uses _IO macro
+ 10 - read: _IOR
+ 01 - write: _IOW
+ 11 - read/write: _IOWR
+
+ 29-16 size of arguments
+
+ 15-8 ascii character supposedly
+ 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::
+
+ #define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2])
--- /dev/null
+=============
+Ioctl Numbers
+=============
+
+19 October 1999
+
+Michael Elizabeth Chastain
+<mec@shout.net>
+
+If you are adding new ioctl's to the kernel, you should use the _IO
+macros defined in <linux/ioctl.h>:
+
+ ====== == ============================================
+ _IO an ioctl with no parameters
+ _IOW an ioctl with write parameters (copy_from_user)
+ _IOR an ioctl with read parameters (copy_to_user)
+ _IOWR an ioctl with both write and read parameters.
+ ====== == ============================================
+
+'Write' and 'read' are from the user's point of view, just like the
+system calls 'write' and 'read'. For example, a SET_FOO ioctl would
+be _IOW, although the kernel would actually read data from user space;
+a GET_FOO ioctl would be _IOR, although the kernel would actually write
+data to user space.
+
+The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter
+or number from the table below. Because of the large number of drivers,
+many drivers share a partial letter with other drivers.
+
+If you are writing a driver for a new device and need a letter, pick an
+unused block with enough room for expansion: 32 to 256 ioctl commands.
+You can register the block by patching this file and submitting the
+patch to Linus Torvalds. Or you can e-mail me at <mec@shout.net> and
+I'll register one for you.
+
+The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number
+to distinguish ioctls from each other. The third argument to _IOW,
+_IOR, or _IOWR is the type of the data going into the kernel or coming
+out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use
+sizeof(arg) as the third argument as this results in your ioctl thinking
+it passes an argument of type size_t.
+
+Some devices use their major number as the identifier; this is OK, as
+long as it is unique. Some devices are irregular and don't follow any
+convention at all.
+
+Following this convention is good because:
+
+(1) Keeping the ioctl's globally unique helps error checking:
+ if a program calls an ioctl on the wrong device, it will get an
+ error rather than some unexpected behaviour.
+
+(2) The 'strace' build procedure automatically finds ioctl numbers
+ defined with _IO, _IOW, _IOR, or _IOWR.
+
+(3) 'strace' can decode numbers back into useful names when the
+ numbers are unique.
+
+(4) People looking for ioctls can grep for them more easily when
+ this convention is used to define the ioctl numbers.
+
+(5) When following the convention, the driver code can use generic
+ code to copy the parameters between user and kernel space.
+
+This table lists ioctls visible from user land for Linux/x86. It contains
+most drivers up to 2.6.31, but I know I am missing some. There has been
+no attempt to list non-X86 architectures or ioctls from drivers/staging/.
+
+==== ===== ======================================================= ================================================================
+Code Seq# Include File Comments
+ (hex)
+==== ===== ======================================================= ================================================================
+0x00 00-1F linux/fs.h conflict!
+0x00 00-1F scsi/scsi_ioctl.h conflict!
+0x00 00-1F linux/fb.h conflict!
+0x00 00-1F linux/wavefront.h conflict!
+0x02 all linux/fd.h
+0x03 all linux/hdreg.h
+0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these.
+0x06 all linux/lp.h
+0x09 all linux/raid/md_u.h
+0x10 00-0F drivers/char/s390/vmcp.h
+0x10 10-1F arch/s390/include/uapi/sclp_ctl.h
+0x10 20-2F arch/s390/include/uapi/asm/hypfs.h
+0x12 all linux/fs.h
+ linux/blkpg.h
+0x1b all InfiniBand Subsystem
+ <http://infiniband.sourceforge.net/>
+0x20 all drivers/cdrom/cm206.h
+0x22 all scsi/sg.h
+'!' 00-1F uapi/linux/seccomp.h
+'#' 00-3F IEEE 1394 Subsystem
+ Block for the entire subsystem
+'$' 00-0F linux/perf_counter.h, linux/perf_event.h
+'%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem
+ <mailto:alexander.shishkin@linux.intel.com>
+'&' 00-07 drivers/firewire/nosy-user.h
+'1' 00-1F linux/timepps.h PPS kit from Ulrich Windl
+ <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/>
+'2' 01-04 linux/i2o.h
+'3' 00-0F drivers/s390/char/raw3270.h conflict!
+'3' 00-1F linux/suspend_ioctls.h, conflict!
+ kernel/power/user.c
+'8' all SNP8023 advanced NIC card
+ <mailto:mcr@solidum.com>
+';' 64-7F linux/vfio.h
+'@' 00-0F linux/radeonfb.h conflict!
+'@' 00-0F drivers/video/aty/aty128fb.c conflict!
+'A' 00-1F linux/apm_bios.h conflict!
+'A' 00-0F linux/agpgart.h, conflict!
+ drivers/char/agp/compat_ioctl.h
+'A' 00-7F sound/asound.h conflict!
+'B' 00-1F linux/cciss_ioctl.h conflict!
+'B' 00-0F include/linux/pmu.h conflict!
+'B' C0-FF advanced bbus <mailto:maassen@uni-freiburg.de>
+'C' all linux/soundcard.h conflict!
+'C' 01-2F linux/capi.h conflict!
+'C' F0-FF drivers/net/wan/cosa.h conflict!
+'D' all arch/s390/include/asm/dasd.h
+'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h
+'D' 05 drivers/scsi/pmcraid.h
+'E' all linux/input.h conflict!
+'E' 00-0F xen/evtchn.h conflict!
+'F' all linux/fb.h conflict!
+'F' 01-02 drivers/scsi/pmcraid.h conflict!
+'F' 20 drivers/video/fsl-diu-fb.h conflict!
+'F' 20 drivers/video/intelfb/intelfb.h conflict!
+'F' 20 linux/ivtvfb.h conflict!
+'F' 20 linux/matroxfb.h conflict!
+'F' 20 drivers/video/aty/atyfb_base.c conflict!
+'F' 00-0F video/da8xx-fb.h conflict!
+'F' 80-8F linux/arcfb.h conflict!
+'F' DD video/sstfb.h conflict!
+'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict!
+'G' 00-0F linux/gigaset_dev.h conflict!
+'H' 00-7F linux/hiddev.h conflict!
+'H' 00-0F linux/hidraw.h conflict!
+'H' 01 linux/mei.h conflict!
+'H' 02 linux/mei.h conflict!
+'H' 03 linux/mei.h conflict!
+'H' 00-0F sound/asound.h conflict!
+'H' 20-40 sound/asound_fm.h conflict!
+'H' 80-8F sound/sfnt_info.h conflict!
+'H' 10-8F sound/emu10k1.h conflict!
+'H' 10-1F sound/sb16_csp.h conflict!
+'H' 10-1F sound/hda_hwdep.h conflict!
+'H' 40-4F sound/hdspm.h conflict!
+'H' 40-4F sound/hdsp.h conflict!
+'H' 90 sound/usb/usx2y/usb_stream.h
+'H' A0 uapi/linux/usb/cdc-wdm.h
+'H' C0-F0 net/bluetooth/hci.h conflict!
+'H' C0-DF net/bluetooth/hidp/hidp.h conflict!
+'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict!
+'H' C0-DF net/bluetooth/bnep/bnep.h conflict!
+'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net>
+'H' F8-FA sound/firewire.h
+'I' all linux/isdn.h conflict!
+'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict!
+'I' 40-4F linux/mISDNif.h conflict!
+'J' 00-1F drivers/scsi/gdth_ioctl.h
+'K' all linux/kd.h
+'L' 00-1F linux/loop.h conflict!
+'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict!
+'L' 20-2F linux/lightnvm.h
+'L' E0-FF linux/ppdd.h encrypted disk device driver
+ <http://linux01.gwdg.de/~alatham/ppdd.html>
+'M' all linux/soundcard.h conflict!
+'M' 01-16 mtd/mtd-abi.h conflict!
+ and drivers/mtd/mtdchar.c
+'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h
+'M' 00-0F drivers/video/fsl-diu-fb.h conflict!
+'N' 00-1F drivers/usb/scanner.h
+'N' 40-7F drivers/block/nvme.c
+'O' 00-06 mtd/ubi-user.h UBI
+'P' all linux/soundcard.h conflict!
+'P' 60-6F sound/sscape_ioctl.h conflict!
+'P' 00-0F drivers/usb/class/usblp.c conflict!
+'P' 01-09 drivers/misc/pci_endpoint_test.c conflict!
+'Q' all linux/soundcard.h
+'R' 00-1F linux/random.h conflict!
+'R' 01 linux/rfkill.h conflict!
+'R' C0-DF net/bluetooth/rfcomm.h
+'S' all linux/cdrom.h conflict!
+'S' 80-81 scsi/scsi_ioctl.h conflict!
+'S' 82-FF scsi/scsi.h conflict!
+'S' 00-7F sound/asequencer.h conflict!
+'T' all linux/soundcard.h conflict!
+'T' 00-AF sound/asound.h conflict!
+'T' all arch/x86/include/asm/ioctls.h conflict!
+'T' C0-DF linux/if_tun.h conflict!
+'U' all sound/asound.h conflict!
+'U' 00-CF linux/uinput.h conflict!
+'U' 00-EF linux/usbdevice_fs.h
+'U' C0-CF drivers/bluetooth/hci_uart.h
+'V' all linux/vt.h conflict!
+'V' all linux/videodev2.h conflict!
+'V' C0 linux/ivtvfb.h conflict!
+'V' C0 linux/ivtv.h conflict!
+'V' C0 media/davinci/vpfe_capture.h conflict!
+'V' C0 media/si4713.h conflict!
+'W' 00-1F linux/watchdog.h conflict!
+'W' 00-1F linux/wanrouter.h conflict! (pre 3.9)
+'W' 00-3F sound/asound.h conflict!
+'W' 40-5F drivers/pci/switch/switchtec.c
+'X' all fs/xfs/xfs_fs.h, conflict!
+ fs/xfs/linux-2.6/xfs_ioctl32.h,
+ include/linux/falloc.h,
+ linux/fs.h,
+'X' all fs/ocfs2/ocfs_fs.h conflict!
+'X' 01 linux/pktcdvd.h conflict!
+'Y' all linux/cyclades.h
+'Z' 14-15 drivers/message/fusion/mptctl.h
+'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices
+ <mailto:gregkh@linuxfoundation.org>
+'a' all linux/atm*.h, linux/sonet.h ATM on linux
+ <http://lrcwww.epfl.ch/>
+'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver
+'b' 00-FF conflict! bit3 vme host bridge
+ <mailto:natalia@nikhefk.nikhef.nl>
+'c' all linux/cm4000_cs.h conflict!
+'c' 00-7F linux/comstats.h conflict!
+'c' 00-7F linux/coda.h conflict!
+'c' 00-1F linux/chio.h conflict!
+'c' 80-9F arch/s390/include/asm/chsc.h conflict!
+'c' A0-AF arch/x86/include/asm/msr.h conflict!
+'d' 00-FF linux/char/drm/drm.h conflict!
+'d' 02-40 pcmcia/ds.h conflict!
+'d' F0-FF linux/digi1.h
+'e' all linux/digi1.h conflict!
+'f' 00-1F linux/ext2_fs.h conflict!
+'f' 00-1F linux/ext3_fs.h conflict!
+'f' 00-0F fs/jfs/jfs_dinode.h conflict!
+'f' 00-0F fs/ext4/ext4.h conflict!
+'f' 00-0F linux/fs.h conflict!
+'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict!
+'f' 81-8F linux/fsverity.h
+'g' 00-0F linux/usb/gadgetfs.h
+'g' 20-2F linux/usb/g_printer.h
+'h' 00-7F conflict! Charon filesystem
+ <mailto:zapman@interlan.net>
+'h' 00-1F linux/hpet.h conflict!
+'h' 80-8F fs/hfsplus/ioctl.c
+'i' 00-3F linux/i2o-dev.h conflict!
+'i' 0B-1F linux/ipmi.h conflict!
+'i' 80-8F linux/i8k.h
+'j' 00-3F linux/joystick.h
+'k' 00-0F linux/spi/spidev.h conflict!
+'k' 00-05 video/kyro.h conflict!
+'k' 10-17 linux/hsi/hsi_char.h HSI character device
+'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system
+ <http://web.archive.org/web/%2A/http://mikonos.dia.unisa.it/tcfs>
+'l' 40-7F linux/udf_fs_i.h in development:
+ <http://sourceforge.net/projects/linux-udf/>
+'m' 00-09 linux/mmtimer.h conflict!
+'m' all linux/mtio.h conflict!
+'m' all linux/soundcard.h conflict!
+'m' all linux/synclink.h conflict!
+'m' 00-19 drivers/message/fusion/mptctl.h conflict!
+'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict!
+'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c
+'n' 80-8F uapi/linux/nilfs2_api.h NILFS2
+'n' E0-FF linux/matroxfb.h matroxfb
+'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2
+'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps)
+'o' 40-41 mtd/ubi-user.h UBI
+'o' 01-A1 `linux/dvb/*.h` DVB
+'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this)
+'p' 00-1F linux/rtc.h conflict!
+'p' 00-3F linux/mc146818rtc.h conflict!
+'p' 40-7F linux/nvram.h
+'p' 80-9F linux/ppdev.h user-space parport
+ <mailto:tim@cyberelk.net>
+'p' A1-A5 linux/pps.h LinuxPPS
+ <mailto:giometti@linux.it>
+'q' 00-1F linux/serio.h
+'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK
+ linux/ixjuser.h <http://web.archive.org/web/%2A/http://www.quicknet.net>
+'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c
+'s' all linux/cdk.h
+'t' 00-7F linux/ppp-ioctl.h
+'t' 80-8F linux/isdn_ppp.h
+'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM
+'u' 00-1F linux/smb_fs.h gone
+'u' 20-3F linux/uvcvideo.h USB video class host driver
+'u' 40-4f linux/udmabuf.h userspace dma-buf misc device
+'v' 00-1F linux/ext2_fs.h conflict!
+'v' 00-1F linux/fs.h conflict!
+'v' 00-0F linux/sonypi.h conflict!
+'v' 00-0F media/v4l2-subdev.h conflict!
+'v' C0-FF linux/meye.h conflict!
+'w' all CERN SCI driver
+'y' 00-1F packet based user level communications
+ <mailto:zapman@interlan.net>
+'z' 00-3F CAN bus card conflict!
+ <mailto:hdstich@connectu.ulm.circular.de>
+'z' 40-7F CAN bus card conflict!
+ <mailto:oe@port.de>
+'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict!
+'|' 00-7F linux/media.h
+0x80 00-1F linux/fb.h
+0x89 00-06 arch/x86/include/asm/sockios.h
+0x89 0B-DF linux/sockios.h
+0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range
+0x89 E0-EF linux/dn.h PROTOPRIVATE range
+0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range
+0x8B all linux/wireless.h
+0x8C 00-3F WiNRADiO driver
+ <http://www.winradio.com.au/>
+0x90 00 drivers/cdrom/sbpcd.h
+0x92 00-0F drivers/usb/mon/mon_bin.c
+0x93 60-7F linux/auto_fs.h
+0x94 all fs/btrfs/ioctl.h Btrfs filesystem
+ and linux/fs.h some lifted to vfs/generic
+0x97 00-7F fs/ceph/ioctl.h Ceph file system
+0x99 00-0F 537-Addinboard driver
+ <mailto:buk@buks.ipn.de>
+0xA0 all linux/sdp/sdp.h Industrial Device Project
+ <mailto:kenji@bitgate.com>
+0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver
+0xA3 80-8F Port ACL in development:
+ <mailto:tlewis@mindspring.com>
+0xA3 90-9F linux/dtlk.h
+0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem
+0xAA 00-3F linux/uapi/linux/userfaultfd.h
+0xAB 00-1F linux/nbd.h
+0xAC 00-1F linux/raw.h
+0xAD 00 Netfilter device in development:
+ <mailto:rusty@rustcorp.com.au>
+0xAE all linux/kvm.h Kernel-based Virtual Machine
+ <mailto:kvm@vger.kernel.org>
+0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor
+0xB0 all RATIO devices in development:
+ <mailto:vgo@ratio.de>
+0xB1 00-1F PPPoX
+ <mailto:mostrows@styx.uwaterloo.ca>
+0xB3 00 linux/mmc/ioctl.h
+0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org>
+0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org>
+0xB6 all linux/fpga-dfl.h
+0xC0 00-0F linux/usb/iowarrior.h
+0xCA 00-0F uapi/misc/cxl.h
+0xCA 10-2F uapi/misc/ocxl.h
+0xCA 80-BF uapi/scsi/cxlflash_ioctl.h
+0xCB 00-1F CBM serial IEC bus in development:
+ <mailto:michael.klein@puffin.lb.shuttle.de>
+0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver
+0xCD 01 linux/reiserfs_fs.h
+0xCF 02 fs/cifs/ioctl.c
+0xDB 00-0F drivers/char/mwave/mwavepub.h
+0xDD 00-3F ZFCP device driver see drivers/s390/scsi/
+ <mailto:aherrman@de.ibm.com>
+0xE5 00-3F linux/fuse.h
+0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver
+0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development)
+ <mailto:thomas@winischhofer.net>
+0xF4 00-1F video/mbxfb.h mbxfb
+ <mailto:raph@8d.com>
+0xF6 all LTTng Linux Trace Toolkit Next Generation
+ <mailto:mathieu.desnoyers@efficios.com>
+0xFD all linux/dm-ioctl.h
+0xFE all linux/isst_if.h
+==== ===== ======================================================= ================================================================
-. SPDX-License-Identifier: GPL-2.0
+.. SPDX-License-Identifier: GPL-2.0
================
1-Wire Subsystem
-
-
- List of maintainers and how to submit kernel changes
+List of maintainers and how to submit kernel changes
+====================================================
Please try to follow the guidelines below. This will make things
easier on the maintainers. Not all of these guidelines matter for every
trivial patch so apply some common sense.
-1. Always _test_ your changes, however small, on at least 4 or
+Tips for patch submitters
+-------------------------
+
+1. Always *test* your changes, however small, on at least 4 or
5 people, preferably many more.
2. Try to release a few ALPHA test versions to the net. Announce
testing and await feedback.
5. Make a patch available to the relevant maintainer in the list. Use
- 'diff -u' to make the patch easy to merge. Be prepared to get your
+ ``diff -u`` to make the patch easy to merge. Be prepared to get your
changes sent back with seemingly silly requests about formatting
and variable names. These aren't as silly as they seem. One
job the maintainers (and especially Linus) do is to keep things
See Documentation/process/coding-style.rst for guidance here.
PLEASE CC: the maintainers and mailing lists that are generated
- by scripts/get_maintainer.pl. The results returned by the
+ by ``scripts/get_maintainer.pl.`` The results returned by the
script will be best if you have git installed and are making
your changes in a branch derived from Linus' latest git tree.
See Documentation/process/submitting-patches.rst for details.
not represent an immediate threat and are better handled publicly,
and ideally, should come with a patch proposal. Please do not send
automated reports to this list either. Such bugs will be handled
- better and faster in the usual public places.
+ better and faster in the usual public places. See
+ Documentation/admin-guide/security-bugs.rst for details.
8. Happy hacking.
-Descriptions of section entries:
+Descriptions of section entries
+-------------------------------
- P: Person (obsolete)
- M: Mail patches to: FullName <address@domain>
- R: Designated reviewer: FullName <address@domain>
+ M: *Mail* patches to: FullName <address@domain>
+ R: Designated *Reviewer*: FullName <address@domain>
These reviewers should be CCed on patches.
- L: Mailing list that is relevant to this area
- W: Web-page with status/info
- B: URI for where to file bugs. A web-page with detailed bug
+ L: *Mailing list* that is relevant to this area
+ W: *Web-page* with status/info
+ B: URI for where to file *bugs*. A web-page with detailed bug
filing info, a direct bug tracker link, or a mailto: URI.
- C: URI for chat protocol, server and channel where developers
+ C: URI for *chat* protocol, server and channel where developers
usually hang out, for example irc://server/channel.
- Q: Patchwork web based patch tracking system site
- T: SCM tree type and location.
+ Q: *Patchwork* web based patch tracking system site
+ T: *SCM* tree type and location.
Type is one of: git, hg, quilt, stgit, topgit
- S: Status, one of the following:
+ S: *Status*, one of the following:
Supported: Someone is actually paid to look after this.
Maintained: Someone actually looks after it.
Odd Fixes: It has a maintainer but they don't have time to do
Obsolete: Old code. Something tagged obsolete generally means
it has been replaced by a better system and you
should be using that.
- F: Files and directories with wildcard patterns.
+ F: *Files* and directories wildcard patterns.
A trailing slash includes all files and subdirectory files.
F: drivers/net/ all files in and below drivers/net
F: drivers/net/* all files in drivers/net, but not below
F: */net/* all files in "any top level directory"/net
One pattern per line. Multiple F: lines acceptable.
- N: Files and directories with regex patterns.
+ N: Files and directories *Regex* patterns.
N: [^a-z]tegra all files whose path contains the word tegra
One pattern per line. Multiple N: lines acceptable.
scripts/get_maintainer.pl has different behavior for files that
get_maintainer will not look at git log history when an F: pattern
match occurs. When an N: match occurs, git log history is used
to also notify the people that have git commit signatures.
- X: Files and directories that are NOT maintained, same rules as F:
- Files exclusions are tested before file matches.
+ X: *Excluded* files and directories that are NOT maintained, same
+ rules as F:. Files exclusions are tested before file matches.
Can be useful for excluding a specific subdirectory, for instance:
F: net/
X: net/ipv6/
matches all files in and below net excluding net/ipv6/
- K: Keyword perl extended regex pattern to match content in a
- patch or file. For instance:
+ K: *Content regex* (perl extended) pattern match in a patch or file.
+ For instance:
K: of_get_profile
matches patches or files that contain "of_get_profile"
K: \b(printk|pr_(info|err))\b
printk, pr_info or pr_err
One regex pattern per line. Multiple K: lines acceptable.
-Note: For the hard of thinking, this list is meant to remain in alphabetical
-order. If you could add yourselves to it in alphabetical order that would be
-so much easier [Ed]
-
-Maintainers List (try to look for most precise areas first)
+Maintainers List
+----------------
- -----------------------------------
+.. note:: When reading this list, please look for the most precise areas
+ first. When adding to this list, please keep the entries in
+ alphabetical order.
3C59X NETWORK DRIVER
M: Steffen Klassert <klassert@kernel.org>
R: Pengutronix Kernel Team <kernel@pengutronix.de>
L: linux-can@vger.kernel.org
S: Maintained
-F: Documentation/networking/j1939.txt
+F: Documentation/networking/j1939.rst
F: net/can/j1939/
F: include/uapi/linux/can/j1939.h
M: Hans de Goede <hdegoede@redhat.com>
L: linux-input@vger.kernel.org
S: Maintained
-F: Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt
+F: Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml
F: drivers/input/keyboard/sun4i-lradc-keys.c
SUNDANCE NETWORK DRIVER
}
/* Indicate that we support PAUSE frames (see comment in
- * Documentation/networking/phy.txt)
+ * Documentation/networking/phy.rst)
*/
phy_support_asym_pause(phy);
* the @encap is set, the device will
* offload the outer header checksums using
* LCO (local checksum offload) (see
- * Documentation/networking/checksum-
- * offloads.txt for more info).
+ * Documentation/networking/checksum-offloads.rst
+ * for more info).
*
* IONIC_TXQ_DESC_OPCODE_CSUM_HW:
*
DELL system. Note you need a Dell OpenManage or Dell Update package (DUP)
supporting application to communicate with the BIOS regarding the new
image for the image update to take effect.
- See <file:Documentation/driver-api/dell_rbu.rst> for more details on the driver.
+ See <file:Documentation/admin-guide/dell_rbu.rst> for more details on the driver.
config FUJITSU_LAPTOP
* on every time the packet data is written. This driver requires an
* application to break the BIOS image in to fixed sized packet chunks.
*
- * See Documentation/driver-api/dell_rbu.rst for more info.
+ * See Documentation/admin-guide/dell_rbu.rst for more info.
*/
#include <linux/init.h>
#include <linux/module.h>
/*
* Consider in future setting limit!=0 maybe to min(num_of_cores - 1, 3)
* so that we don't launch too many worker threads but
- * Documentation/workqueue.txt recommends setting it to 0
+ * Documentation/core-api/workqueue.rst recommends setting it to 0
*/
/* WQ_UNBOUND allows decrypt tasks to run on any CPU */
EXPORT_SYMBOL(gen_pool_dma_zalloc_align);
/**
- * gen_pool_free - free allocated special memory back to the pool
+ * gen_pool_free_owner - free allocated special memory back to the pool
* @pool: pool to free to
* @addr: starting address of memory to free back to pool
* @size: size in bytes of memory to free
--- /dev/null
+#!/usr/bin/env python
+# SPDX-License-Identifier: GPL-2.0+
+#
+# This determines how many parallel tasks "make" is expecting, as it is
+# not exposed via an special variables.
+# https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver
+from __future__ import print_function
+import os, sys, fcntl, errno
+
+# Default parallelism is "1" unless overridden on the command-line.
+default="1"
+if len(sys.argv) > 1:
+ default=sys.argv[1]
+
+# Set non-blocking for a given file descriptor.
+def nonblock(fd):
+ flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+ fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+ return fd
+
+# Extract and prepare jobserver file descriptors from envirnoment.
+try:
+ # Fetch the make environment options.
+ flags = os.environ['MAKEFLAGS']
+
+ # Look for "--jobserver=R,W"
+ opts = [x for x in flags.split(" ") if x.startswith("--jobserver")]
+
+ # Parse out R,W file descriptor numbers and set them nonblocking.
+ fds = opts[0].split("=", 1)[1]
+ reader, writer = [int(x) for x in fds.split(",", 1)]
+ reader = nonblock(reader)
+except (KeyError, IndexError, ValueError, IOError):
+ # Any missing environment strings or bad fds should result in just
+ # using the default specified parallelism.
+ print(default)
+ sys.exit(0)
+
+# Read out as many jobserver slots as possible.
+jobs = b""
+while True:
+ try:
+ slot = os.read(reader, 1)
+ jobs += slot
+ except (OSError, IOError) as e:
+ if e.errno == errno.EWOULDBLOCK:
+ # Stop when reach the end of the jobserver queue.
+ break
+ raise e
+# Return all the reserved slots.
+os.write(writer, jobs)
+
+# If the jobserver was (impossibly) full or communication failed, use default.
+if len(jobs) < 1:
+ print(default)
+
+# Report available slots (with a bump for our caller's reserveration).
+print(len(jobs) + 1)
my $x = shift;
my $file = shift;
- if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
+ if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
my $decl_type = $1;
$declaration_name = $2;
my $members = $3;
# strip comments:
$members =~ s/\/\*.*?\*\///gos;
# strip attributes
- $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi;
- $members =~ s/\s*__aligned\s*\([^;]*\)//gos;
- $members =~ s/\s*__packed\s*//gos;
- $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
+ $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
+ $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
+ $members =~ s/\s*__packed\s*/ /gos;
+ $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
+ $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
# replace DECLARE_BITMAP
$members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
# replace DECLARE_HASHTABLE
sub check_missing_file($$$)
{
- my $file = shift;
+ my $files = shift;
my $package = shift;
my $is_optional = shift;
- return if(-e $file);
+ for (@$files) {
+ return if(-e $_);
+ }
add_package($package, $is_optional);
}
);
if ($pdf) {
- check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+ check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"],
"fonts-dejavu", 2);
- check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
+ check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
+ "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"],
"fonts-noto-cjk", 2);
}
}
if ($pdf) {
- check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
+ check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"],
"google-noto-sans-cjk-ttc-fonts", 2);
}
$map{"latexmk"} = "texlive-collection-basic";
if ($pdf) {
- check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
+ check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"],
"google-noto-sans-cjk-ttc-fonts", 2);
}
check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf);
if ($pdf) {
- check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
+ check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"],
"noto-fonts-cjk", 2);
}
"rsvg-convert" => "gnome-base/librsvg",
);
- check_missing_file("/usr/share/fonts/dejavu/DejaVuSans.ttf",
+ check_missing_file(["/usr/share/fonts/dejavu/DejaVuSans.ttf"],
"media-fonts/dejavu", 2) if ($pdf);
if ($pdf) {
- check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf",
+ check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf"],
"media-fonts/noto-cjk", 2);
}
# Common dependencies
#
+sub deactivate_help()
+{
+ printf "\tIf you want to exit the virtualenv, you can use:\n";
+ printf "\tdeactivate\n";
+}
+
sub check_needs()
{
# Check for needed programs/tools
if ($need_sphinx && scalar @activates > 0 && $activates[0] ge $min_activate) {
printf "\nNeed to activate a compatible Sphinx version on virtualenv with:\n";
printf "\t. $activates[0]\n";
+ deactivate_help();
exit (1);
} else {
my $rec_activate = "$virtenv_dir/bin/activate";
printf "\t$virtualenv $virtenv_dir\n";
printf "\t. $rec_activate\n";
printf "\tpip install -r $requirement_file\n";
+ deactivate_help();
$need++ if (!$rec_sphinx_upgrade);
}
projects / linux-2.6-microblaze.git / commitdiff