* [PATCH v3 25/33] docs: Debugging390.txt: convert table to ascii artwork
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Heiko Carstens, Vasily Gorbik,
Christian Borntraeger, linux-s390
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The first bit/value table inside the document is very
hard to read and won't fit ReST format. Also, some columns aren't
properly aligned.
Convert it to a nice ascii artwork table with makes it easier to
read as plain text and is compatible with ReST format parser
on Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/s390/Debugging390.txt | 210 ++++++++++++++++------------
1 file changed, 120 insertions(+), 90 deletions(-)
diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt
index 5ae7f868a007..c35804c238ad 100644
--- a/Documentation/s390/Debugging390.txt
+++ b/Documentation/s390/Debugging390.txt
@@ -78,96 +78,126 @@ e.g. switching address translation off requires that you
have a logical=physical mapping for the address you are
currently running at.
- Bit Value
-s/390 z/Architecture
-0 0 Reserved ( must be 0 ) otherwise specification exception occurs.
-
-1 1 Program Event Recording 1 PER enabled,
- PER is used to facilitate debugging e.g. single stepping.
-
-2-4 2-4 Reserved ( must be 0 ).
-
-5 5 Dynamic address translation 1=DAT on.
-
-6 6 Input/Output interrupt Mask
-
-7 7 External interrupt Mask used primarily for interprocessor
- signalling and clock interrupts.
-
-8-11 8-11 PSW Key used for complex memory protection mechanism
- (not used under linux)
-
-12 12 1 on s/390 0 on z/Architecture
-
-13 13 Machine Check Mask 1=enable machine check interrupts
-
-14 14 Wait State. Set this to 1 to stop the processor except for
- interrupts and give time to other LPARS. Used in CPU idle in
- the kernel to increase overall usage of processor resources.
-
-15 15 Problem state ( if set to 1 certain instructions are disabled )
- all linux user programs run with this bit 1
- ( useful info for debugging under VM ).
-
-16-17 16-17 Address Space Control
-
- 00 Primary Space Mode:
- The register CR1 contains the primary address-space control ele-
- ment (PASCE), which points to the primary space region/segment
- table origin.
-
- 01 Access register mode
-
- 10 Secondary Space Mode:
- The register CR7 contains the secondary address-space control
- element (SASCE), which points to the secondary space region or
- segment table origin.
-
- 11 Home Space Mode:
- The register CR13 contains the home space address-space control
- element (HASCE), which points to the home space region/segment
- table origin.
-
- See "Address Spaces on Linux for s/390 & z/Architecture" below
- for more information about address space usage in Linux.
-
-18-19 18-19 Condition codes (CC)
-
-20 20 Fixed point overflow mask if 1=FPU exceptions for this event
- occur ( normally 0 )
-
-21 21 Decimal overflow mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-22 22 Exponent underflow mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-23 23 Significance Mask if 1=FPU exceptions for this event occur
- ( normally 0 )
-
-24-31 24-30 Reserved Must be 0.
-
- 31 Extended Addressing Mode
- 32 Basic Addressing Mode
- Used to set addressing mode
- PSW 31 PSW 32
- 0 0 24 bit
- 0 1 31 bit
- 1 1 64 bit
-
-32 1=31 bit addressing mode 0=24 bit addressing mode (for backward
- compatibility), linux always runs with this bit set to 1
-
-33-64 Instruction address.
- 33-63 Reserved must be 0
- 64-127 Address
- In 24 bits mode bits 64-103=0 bits 104-127 Address
- In 31 bits mode bits 64-96=0 bits 97-127 Address
- Note: unlike 31 bit mode on s/390 bit 96 must be zero
- when loading the address with LPSWE otherwise a
- specification exception occurs, LPSW is fully backward
- compatible.
-
++-------------------------+-------------------------------------------------+
+| Bit | |
++--------+----------------+ Value |
+| s/390 | z/Architecture | |
++========+================+=================================================+
+| 0 | 0 | Reserved (must be 0) otherwise specification |
+| | | exception occurs. |
++--------+----------------+-------------------------------------------------+
+| 1 | 1 | Program Event Recording 1 PER enabled, |
+| | | PER is used to facilitate debugging e.g. |
+| | | single stepping. |
++--------+----------------+-------------------------------------------------+
+| 2-4 | 2-4 | Reserved (must be 0). |
++--------+----------------+-------------------------------------------------+
+| 5 | 5 | Dynamic address translation 1=DAT on. |
++--------+----------------+-------------------------------------------------+
+| 6 | 6 | Input/Output interrupt Mask |
++--------+----------------+-------------------------------------------------+
+| 7 | 7 | External interrupt Mask used primarily for |
+| | | interprocessor signalling and clock interrupts. |
++--------+----------------+-------------------------------------------------+
+| 8-11 | 8-11 | PSW Key used for complex memory protection |
+| | | mechanism (not used under linux) |
++--------+----------------+-------------------------------------------------+
+| 12 | 12 | 1 on s/390 0 on z/Architecture |
++--------+----------------+-------------------------------------------------+
+| 13 | 13 | Machine Check Mask 1=enable machine check |
+| | | interrupts |
++--------+----------------+-------------------------------------------------+
+| 14 | 14 | Wait State. Set this to 1 to stop the processor |
+| | | except for interrupts and give time to other |
+| | | LPARS. Used in CPU idle in the kernel to |
+| | | increase overall usage of processor resources. |
++--------+----------------+-------------------------------------------------+
+| 15 | 15 | Problem state (if set to 1 certain instructions |
+| | | are disabled). All linux user programs run with |
+| | | this bit 1 (useful info for debugging under VM).|
++--------+----------------+-------------------------------------------------+
+| 16-17 | 16-17 | Address Space Control |
+| | | |
+| | | 00 Primary Space Mode: |
+| | | |
+| | | The register CR1 contains the primary |
+| | | address-space control element (PASCE), which |
+| | | points to the primary space region/segment |
+| | | table origin. |
+| | | |
+| | | 01 Access register mode |
+| | | |
+| | | 10 Secondary Space Mode: |
+| | | |
+| | | The register CR7 contains the secondary |
+| | | address-space control element (SASCE), which |
+| | | points to the secondary space region or |
+| | | segment table origin. |
+| | | |
+| | | 11 Home Space Mode: |
+| | | |
+| | | The register CR13 contains the home space |
+| | | address-space control element (HASCE), which |
+| | | points to the home space region/segment |
+| | | table origin. |
+| | | |
+| | | See "Address Spaces on Linux for s/390 & |
+| | | z/Architecture" below for more information |
+| | | about address space usage in Linux. |
++--------+----------------+-------------------------------------------------+
+| 18-19 | 18-19 | Condition codes (CC) |
++--------+----------------+-------------------------------------------------+
+| 20 | 20 | Fixed point overflow mask if 1=FPU exceptions |
+| | | for this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 21 | 21 | Decimal overflow mask if 1=FPU exceptions for |
+| | | this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 22 | 22 | Exponent underflow mask if 1=FPU exceptions |
+| | | for this event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 23 | 23 | Significance Mask if 1=FPU exceptions for this |
+| | | event occur (normally 0) |
++--------+----------------+-------------------------------------------------+
+| 24-31 | 24-30 | Reserved Must be 0. |
+| +----------------+-------------------------------------------------+
+| | 31 | Extended Addressing Mode |
+| +----------------+-------------------------------------------------+
+| | 32 | Basic Addressing Mode |
+| | | |
+| | | Used to set addressing mode |
+| | | |
+| | | +---------+----------+----------+ |
+| | | | PSW 31 | PSW 32 | | |
+| | | +---------+----------+----------+ |
+| | | | 0 | 0 | 24 bit | |
+| | | +---------+----------+----------+ |
+| | | | 0 | 1 | 31 bit | |
+| | | +---------+----------+----------+ |
+| | | | 1 | 1 | 64 bit | |
+| | | +---------+----------+----------+ |
++--------+----------------+-------------------------------------------------+
+| 32 | | 1=31 bit addressing mode 0=24 bit addressing |
+| | | mode (for backward compatibility), linux |
+| | | always runs with this bit set to 1 |
++--------+----------------+-------------------------------------------------+
+| 33-64 | | Instruction address. |
+| +----------------+-------------------------------------------------+
+| | 33-63 | Reserved must be 0 |
+| +----------------+-------------------------------------------------+
+| | 64-127 | Address |
+| | | |
+| | | - In 24 bits mode bits 64-103=0 bits 104-127 |
+| | | Address |
+| | | - In 31 bits mode bits 64-96=0 bits 97-127 |
+| | | Address |
+| | | |
+| | | Note: |
+| | | unlike 31 bit mode on s/390 bit 96 must be |
+| | | zero when loading the address with LPSWE |
+| | | otherwise a specification exception occurs, |
+| | | LPSW is fully backward compatible. |
++--------+----------------+-------------------------------------------------+
Prefix Page(s)
--------------
--
2.21.0
^ permalink raw reply related
* [PATCH v3 12/33] docs: ide: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Borislav Petkov, Jens Axboe, David S. Miller,
Geert Uytterhoeven, linux-ide, linux-m68k
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/cdrom/ide-cd.rst | 18 +--
Documentation/ide/changelogs.rst | 17 ++
.../ide/{ide-tape.txt => ide-tape.rst} | 23 +--
Documentation/ide/{ide.txt => ide.rst} | 147 ++++++++++--------
Documentation/ide/index.rst | 21 +++
...arm-plug-howto.txt => warm-plug-howto.rst} | 10 +-
arch/m68k/q40/README | 2 +-
drivers/ide/Kconfig | 20 +--
9 files changed, 155 insertions(+), 105 deletions(-)
create mode 100644 Documentation/ide/changelogs.rst
rename Documentation/ide/{ide-tape.txt => ide-tape.rst} (83%)
rename Documentation/ide/{ide.txt => ide.rst} (72%)
create mode 100644 Documentation/ide/index.rst
rename Documentation/ide/{warm-plug-howto.txt => warm-plug-howto.rst} (61%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index d5f01f7eb5ca..e4544f0335e3 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1502,7 +1502,7 @@
Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc
.vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr
.cdrom .chs .ignore_cable are additional options
- See Documentation/ide/ide.txt.
+ See Documentation/ide/ide.rst.
ide-generic.probe-mask= [HW] (E)IDE subsystem
Format: <int>
diff --git a/Documentation/cdrom/ide-cd.rst b/Documentation/cdrom/ide-cd.rst
index dadc94ef6b6c..bdccb74fc92d 100644
--- a/Documentation/cdrom/ide-cd.rst
+++ b/Documentation/cdrom/ide-cd.rst
@@ -47,7 +47,7 @@ This driver provides the following features:
---------------
0. The ide-cd relies on the ide disk driver. See
- Documentation/ide/ide.txt for up-to-date information on the ide
+ Documentation/ide/ide.rst for up-to-date information on the ide
driver.
1. Make sure that the ide and ide-cd drivers are compiled into the
@@ -62,7 +62,7 @@ This driver provides the following features:
Depending on what type of IDE interface you have, you may need to
specify additional configuration options. See
- Documentation/ide/ide.txt.
+ Documentation/ide/ide.rst.
2. You should also ensure that the iso9660 filesystem is either
compiled into the kernel or available as a loadable module. You
@@ -82,7 +82,7 @@ This driver provides the following features:
on the primary IDE interface are called `hda` and `hdb`,
respectively. The drives on the secondary interface are called
`hdc` and `hdd`. (Interfaces at other locations get other letters
- in the third position; see Documentation/ide/ide.txt.)
+ in the third position; see Documentation/ide/ide.rst.)
If you want your CDROM drive to be found automatically by the
driver, you should make sure your IDE interface uses either the
@@ -91,7 +91,7 @@ This driver provides the following features:
be jumpered as `master`. (If for some reason you cannot configure
your system in this manner, you can probably still use the driver.
You may have to pass extra configuration information to the kernel
- when you boot, however. See Documentation/ide/ide.txt for more
+ when you boot, however. See Documentation/ide/ide.rst for more
information.)
4. Boot the system. If the drive is recognized, you should see a
@@ -163,7 +163,7 @@ to change. If the slot number is -1, the drive is unloaded.
This section discusses some common problems encountered when trying to
use the driver, and some possible solutions. Note that if you are
experiencing problems, you should probably also review
-Documentation/ide/ide.txt for current information about the underlying
+Documentation/ide/ide.rst for current information about the underlying
IDE support code. Some of these items apply only to earlier versions
of the driver, but are mentioned here for completeness.
@@ -173,7 +173,7 @@ from the driver.
a. Drive is not detected during booting.
- Review the configuration instructions above and in
- Documentation/ide/ide.txt, and check how your hardware is
+ Documentation/ide/ide.rst, and check how your hardware is
configured.
- If your drive is the only device on an IDE interface, it should
@@ -181,7 +181,7 @@ a. Drive is not detected during booting.
- If your IDE interface is not at the standard addresses of 0x170
or 0x1f0, you'll need to explicitly inform the driver using a
- lilo option. See Documentation/ide/ide.txt. (This feature was
+ lilo option. See Documentation/ide/ide.rst. (This feature was
added around kernel version 1.3.30.)
- If the autoprobing is not finding your drive, you can tell the
@@ -207,7 +207,7 @@ a. Drive is not detected during booting.
Support for some interfaces needing extra initialization is
provided in later 1.3.x kernels. You may need to turn on
additional kernel configuration options to get them to work;
- see Documentation/ide/ide.txt.
+ see Documentation/ide/ide.rst.
Even if support is not available for your interface, you may be
able to get it to work with the following procedure. First boot
@@ -261,7 +261,7 @@ c. System hangups.
be worked around by specifying the `serialize` option when
booting. Recent kernels should be able to detect the need for
this automatically in most cases, but the detection is not
- foolproof. See Documentation/ide/ide.txt for more information
+ foolproof. See Documentation/ide/ide.rst for more information
about the `serialize` option and the CMD640B.
- Note that many MS-DOS CDROM drivers will work with such buggy
diff --git a/Documentation/ide/changelogs.rst b/Documentation/ide/changelogs.rst
new file mode 100644
index 000000000000..fdf9d0fb8027
--- /dev/null
+++ b/Documentation/ide/changelogs.rst
@@ -0,0 +1,17 @@
+Changelog for ide cd
+--------------------
+
+ .. include:: ChangeLog.ide-cd.1994-2004
+ :literal:
+
+Changelog for ide floppy
+------------------------
+
+ .. include:: ChangeLog.ide-floppy.1996-2002
+ :literal:
+
+Changelog for ide tape
+----------------------
+
+ .. include:: ChangeLog.ide-tape.1995-2002
+ :literal:
diff --git a/Documentation/ide/ide-tape.txt b/Documentation/ide/ide-tape.rst
similarity index 83%
rename from Documentation/ide/ide-tape.txt
rename to Documentation/ide/ide-tape.rst
index 3f348a0b21d8..3e061d9c0e38 100644
--- a/Documentation/ide/ide-tape.txt
+++ b/Documentation/ide/ide-tape.rst
@@ -1,4 +1,6 @@
-IDE ATAPI streaming tape driver.
+===============================
+IDE ATAPI streaming tape driver
+===============================
This driver is a part of the Linux ide driver.
@@ -10,14 +12,14 @@ to the request-list of the block device, and waits for their completion.
The block device major and minor numbers are determined from the
tape's relative position in the ide interfaces, as explained in ide.c.
-The character device interface consists of the following devices:
+The character device interface consists of the following devices::
-ht0 major 37, minor 0 first IDE tape, rewind on close.
-ht1 major 37, minor 1 second IDE tape, rewind on close.
-...
-nht0 major 37, minor 128 first IDE tape, no rewind on close.
-nht1 major 37, minor 129 second IDE tape, no rewind on close.
-...
+ ht0 major 37, minor 0 first IDE tape, rewind on close.
+ ht1 major 37, minor 1 second IDE tape, rewind on close.
+ ...
+ nht0 major 37, minor 128 first IDE tape, no rewind on close.
+ nht1 major 37, minor 129 second IDE tape, no rewind on close.
+ ...
The general magnetic tape commands compatible interface, as defined by
include/linux/mtio.h, is accessible through the character device.
@@ -40,9 +42,10 @@ Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive.
Here are some words from the first releases of hd.c, which are quoted
in ide.c and apply here as well:
-| Special care is recommended. Have Fun!
+* Special care is recommended. Have Fun!
-Possible improvements:
+Possible improvements
+=====================
1. Support for the ATAPI overlap protocol.
diff --git a/Documentation/ide/ide.txt b/Documentation/ide/ide.rst
similarity index 72%
rename from Documentation/ide/ide.txt
rename to Documentation/ide/ide.rst
index 7aca987c23d9..88bdcba92f7d 100644
--- a/Documentation/ide/ide.txt
+++ b/Documentation/ide/ide.rst
@@ -1,41 +1,43 @@
-
- Information regarding the Enhanced IDE drive in Linux 2.6
-
-==============================================================================
-
+============================================
+Information regarding the Enhanced IDE drive
+============================================
The hdparm utility can be used to control various IDE features on a
running system. It is packaged separately. Please Look for it on popular
linux FTP sites.
+-------------------------------------------------------------------------------
+.. important::
-*** IMPORTANT NOTICES: BUGGY IDE CHIPSETS CAN CORRUPT DATA!!
-*** =================
-*** PCI versions of the CMD640 and RZ1000 interfaces are now detected
-*** automatically at startup when PCI BIOS support is configured.
-***
-*** Linux disables the "prefetch" ("readahead") mode of the RZ1000
-*** to prevent data corruption possible due to hardware design flaws.
-***
-*** For the CMD640, linux disables "IRQ unmasking" (hdparm -u1) on any
-*** drive for which the "prefetch" mode of the CMD640 is turned on.
-*** If "prefetch" is disabled (hdparm -p8), then "IRQ unmasking" can be
-*** used again.
-***
-*** For the CMD640, linux disables "32bit I/O" (hdparm -c1) on any drive
-*** for which the "prefetch" mode of the CMD640 is turned off.
-*** If "prefetch" is enabled (hdparm -p9), then "32bit I/O" can be
-*** used again.
-***
-*** The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
-*** automatically detected by Linux. For safe, reliable operation with such
-*** interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
-***
-*** Use of the "serialize" option is no longer necessary.
-
-================================================================================
-Common pitfalls:
+ BUGGY IDE CHIPSETS CAN CORRUPT DATA!!
+
+ PCI versions of the CMD640 and RZ1000 interfaces are now detected
+ automatically at startup when PCI BIOS support is configured.
+
+ Linux disables the "prefetch" ("readahead") mode of the RZ1000
+ to prevent data corruption possible due to hardware design flaws.
+
+ For the CMD640, linux disables "IRQ unmasking" (hdparm -u1) on any
+ drive for which the "prefetch" mode of the CMD640 is turned on.
+ If "prefetch" is disabled (hdparm -p8), then "IRQ unmasking" can be
+ used again.
+
+ For the CMD640, linux disables "32bit I/O" (hdparm -c1) on any drive
+ for which the "prefetch" mode of the CMD640 is turned off.
+ If "prefetch" is enabled (hdparm -p9), then "32bit I/O" can be
+ used again.
+
+ The CMD640 is also used on some Vesa Local Bus (VLB) cards, and is *NOT*
+ automatically detected by Linux. For safe, reliable operation with such
+ interfaces, one *MUST* use the "cmd640.probe_vlb" kernel option.
+
+ Use of the "serialize" option is no longer necessary.
+
+-------------------------------------------------------------------------------
+
+Common pitfalls
+===============
- 40-conductor IDE cables are capable of transferring data in DMA modes up to
udma2, but no faster.
@@ -49,19 +51,18 @@ Common pitfalls:
- Even better try to stick to the same vendor and device type on the same
cable.
-================================================================================
-
-This is the multiple IDE interface driver, as evolved from hd.c.
+This is the multiple IDE interface driver, as evolved from hd.c
+===============================================================
It supports up to 9 IDE interfaces per default, on one or more IRQs (usually
-14 & 15). There can be up to two drives per interface, as per the ATA-6 spec.
+14 & 15). There can be up to two drives per interface, as per the ATA-6 spec.::
-Primary: ide0, port 0x1f0; major=3; hda is minor=0; hdb is minor=64
-Secondary: ide1, port 0x170; major=22; hdc is minor=0; hdd is minor=64
-Tertiary: ide2, port 0x1e8; major=33; hde is minor=0; hdf is minor=64
-Quaternary: ide3, port 0x168; major=34; hdg is minor=0; hdh is minor=64
-fifth.. ide4, usually PCI, probed
-sixth.. ide5, usually PCI, probed
+ Primary: ide0, port 0x1f0; major=3; hda is minor=0; hdb is minor=64
+ Secondary: ide1, port 0x170; major=22; hdc is minor=0; hdd is minor=64
+ Tertiary: ide2, port 0x1e8; major=33; hde is minor=0; hdf is minor=64
+ Quaternary: ide3, port 0x168; major=34; hdg is minor=0; hdh is minor=64
+ fifth.. ide4, usually PCI, probed
+ sixth.. ide5, usually PCI, probed
To access devices on interfaces > ide0, device entries please make sure that
device files for them are present in /dev. If not, please create such
@@ -80,12 +81,15 @@ seldom occurs. Be careful, and if in doubt, don't do it!
Drives are normally found by auto-probing and/or examining the CMOS/BIOS data.
For really weird situations, the apparent (fdisk) geometry can also be specified
-on the kernel "command line" using LILO. The format of such lines is:
+on the kernel "command line" using LILO. The format of such lines is::
ide_core.chs=[interface_number.device_number]:cyls,heads,sects
-or ide_core.cdrom=[interface_number.device_number]
-For example:
+or::
+
+ ide_core.cdrom=[interface_number.device_number]
+
+For example::
ide_core.chs=1.0:1050,32,64 ide_core.cdrom=1.1
@@ -96,10 +100,12 @@ geometry for partitioning purposes (fdisk).
If the auto-probing during boot time confuses a drive (ie. the drive works
with hd.c but not with ide.c), then an command line option may be specified
for each drive for which you'd like the drive to skip the hardware
-probe/identification sequence. For example:
+probe/identification sequence. For example::
ide_core.noprobe=0.1
-or
+
+or::
+
ide_core.chs=1.0:768,16,32
ide_core.noprobe=1.0
@@ -115,22 +121,24 @@ Such drives will be identified at boot time, just like a hard disk.
If for some reason your cdrom drive is *not* found at boot time, you can force
the probe to look harder by supplying a kernel command line parameter
-via LILO, such as:
+via LILO, such as:::
ide_core.cdrom=1.0 /* "master" on second interface (hdc) */
-or
+
+or::
+
ide_core.cdrom=1.1 /* "slave" on second interface (hdd) */
For example, a GW2000 system might have a hard drive on the primary
interface (/dev/hda) and an IDE cdrom drive on the secondary interface
-(/dev/hdc). To mount a CD in the cdrom drive, one would use something like:
+(/dev/hdc). To mount a CD in the cdrom drive, one would use something like::
ln -sf /dev/hdc /dev/cdrom
mkdir /mnt/cdrom
mount /dev/cdrom /mnt/cdrom -t iso9660 -o ro
If, after doing all of the above, mount doesn't work and you see
-errors from the driver (with dmesg) complaining about `status=0xff',
+errors from the driver (with dmesg) complaining about `status=0xff`,
this means that the hardware is not responding to the driver's attempts
to read it. One of the following is probably the problem:
@@ -165,7 +173,7 @@ drivers can always be compiled as loadable modules, the chipset drivers
can only be compiled into the kernel, and the core code (ide.c) can be
compiled as a loadable module provided no chipset support is needed.
-When using ide.c as a module in combination with kmod, add:
+When using ide.c as a module in combination with kmod, add::
alias block-major-3 ide-probe
@@ -176,10 +184,8 @@ driver using the "options=" keyword to insmod, while replacing any ',' with
';'.
-================================================================================
-
Summary of ide driver parameters for kernel command line
---------------------------------------------------------
+========================================================
For legacy IDE VLB host drivers (ali14xx/dtc2278/ht6560b/qd65xx/umc8672)
you need to explicitly enable probing by using "probe" kernel parameter,
@@ -226,28 +232,31 @@ Other kernel parameters for ide_core are:
* "chs=[interface_number.device_number]" to force device as a disk (using CHS)
-================================================================================
Some Terminology
-----------------
-IDE = Integrated Drive Electronics, meaning that each drive has a built-in
-controller, which is why an "IDE interface card" is not a "controller card".
+================
-ATA = AT (the old IBM 286 computer) Attachment Interface, a draft American
-National Standard for connecting hard drives to PCs. This is the official
-name for "IDE".
+IDE
+ Integrated Drive Electronics, meaning that each drive has a built-in
+ controller, which is why an "IDE interface card" is not a "controller card".
-The latest standards define some enhancements, known as the ATA-6 spec,
-which grew out of vendor-specific "Enhanced IDE" (EIDE) implementations.
+ATA
+ AT (the old IBM 286 computer) Attachment Interface, a draft American
+ National Standard for connecting hard drives to PCs. This is the official
+ name for "IDE".
-ATAPI = ATA Packet Interface, a new protocol for controlling the drives,
-similar to SCSI protocols, created at the same time as the ATA2 standard.
-ATAPI is currently used for controlling CDROM, TAPE and FLOPPY (ZIP or
-LS120/240) devices, removable R/W cartridges, and for high capacity hard disk
-drives.
+ The latest standards define some enhancements, known as the ATA-6 spec,
+ which grew out of vendor-specific "Enhanced IDE" (EIDE) implementations.
+
+ATAPI
+ ATA Packet Interface, a new protocol for controlling the drives,
+ similar to SCSI protocols, created at the same time as the ATA2 standard.
+ ATAPI is currently used for controlling CDROM, TAPE and FLOPPY (ZIP or
+ LS120/240) devices, removable R/W cartridges, and for high capacity hard disk
+ drives.
mlord@pobox.com
---
+
Wed Apr 17 22:52:44 CEST 2002 edited by Marcin Dalecki, the current
maintainer.
diff --git a/Documentation/ide/index.rst b/Documentation/ide/index.rst
new file mode 100644
index 000000000000..45bc12d3957f
--- /dev/null
+++ b/Documentation/ide/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+==================================
+Integrated Drive Electronics (IDE)
+==================================
+
+.. toctree::
+ :maxdepth: 1
+
+ ide
+ ide-tape
+ warm-plug-howto
+
+ changelogs
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/ide/warm-plug-howto.txt b/Documentation/ide/warm-plug-howto.rst
similarity index 61%
rename from Documentation/ide/warm-plug-howto.txt
rename to Documentation/ide/warm-plug-howto.rst
index 98152bcd515a..c245242ef2f1 100644
--- a/Documentation/ide/warm-plug-howto.txt
+++ b/Documentation/ide/warm-plug-howto.rst
@@ -1,14 +1,14 @@
-
+===================
IDE warm-plug HOWTO
===================
-To warm-plug devices on a port 'idex':
+To warm-plug devices on a port 'idex'::
-# echo -n "1" > /sys/class/ide_port/idex/delete_devices
+ # echo -n "1" > /sys/class/ide_port/idex/delete_devices
-unplug old device(s) and plug new device(s)
+unplug old device(s) and plug new device(s)::
-# echo -n "1" > /sys/class/ide_port/idex/scan
+ # echo -n "1" > /sys/class/ide_port/idex/scan
done
diff --git a/arch/m68k/q40/README b/arch/m68k/q40/README
index 93f4c4cd3c45..a4991d2d8af6 100644
--- a/arch/m68k/q40/README
+++ b/arch/m68k/q40/README
@@ -31,7 +31,7 @@ drivers used by the Q40, apart from the very obvious (console etc.):
char/joystick/* # most of this should work, not
# in default config.in
block/q40ide.c # startup for ide
- ide* # see Documentation/ide/ide.txt
+ ide* # see Documentation/ide/ide.rst
floppy.c # normal PC driver, DMA emu in asm/floppy.h
# and arch/m68k/kernel/entry.S
# see drivers/block/README.fd
diff --git a/drivers/ide/Kconfig b/drivers/ide/Kconfig
index fdd2a62f9d52..9eada392df15 100644
--- a/drivers/ide/Kconfig
+++ b/drivers/ide/Kconfig
@@ -25,13 +25,13 @@ menuconfig IDE
To compile this driver as a module, choose M here: the
module will be called ide-core.
- For further information, please read <file:Documentation/ide/ide.txt>.
+ For further information, please read <file:Documentation/ide/ide.rst>.
If unsure, say N.
if IDE
-comment "Please see Documentation/ide/ide.txt for help/info on IDE drives"
+comment "Please see Documentation/ide/ide.rst for help/info on IDE drives"
config IDE_XFER_MODE
bool
@@ -163,7 +163,7 @@ config BLK_DEV_IDETAPE
along with other IDE devices, as "hdb" or "hdc", or something
similar, and will be mapped to a character device such as "ht0"
(check the boot messages with dmesg). Be sure to consult the
- <file:drivers/ide/ide-tape.c> and <file:Documentation/ide/ide.txt>
+ <file:drivers/ide/ide-tape.c> and <file:Documentation/ide/ide.rst>
files for usage information.
To compile this driver as a module, choose M here: the
@@ -251,7 +251,7 @@ config BLK_DEV_CMD640
The CMD640 chip is also used on add-in cards by Acculogic, and on
the "CSA-6400E PCI to IDE controller" that some people have. For
- details, read <file:Documentation/ide/ide.txt>.
+ details, read <file:Documentation/ide/ide.rst>.
config BLK_DEV_CMD640_ENHANCED
bool "CMD640 enhanced support"
@@ -259,7 +259,7 @@ config BLK_DEV_CMD640_ENHANCED
help
This option includes support for setting/autotuning PIO modes and
prefetch on CMD640 IDE interfaces. For details, read
- <file:Documentation/ide/ide.txt>. If you have a CMD640 IDE interface
+ <file:Documentation/ide/ide.rst>. If you have a CMD640 IDE interface
and your BIOS does not already do this for you, then say Y here.
Otherwise say N.
@@ -819,7 +819,7 @@ config BLK_DEV_ALI14XX
boot parameter. It enables support for the secondary IDE interface
of the ALI M1439/1443/1445/1487/1489 chipsets, and permits faster
I/O speeds to be set as well.
- See the files <file:Documentation/ide/ide.txt> and
+ See the files <file:Documentation/ide/ide.rst> and
<file:drivers/ide/ali14xx.c> for more info.
config BLK_DEV_DTC2278
@@ -830,7 +830,7 @@ config BLK_DEV_DTC2278
This driver is enabled at runtime using the "dtc2278.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the DTC-2278 card, and permits faster I/O speeds to be set as
- well. See the <file:Documentation/ide/ide.txt> and
+ well. See the <file:Documentation/ide/ide.rst> and
<file:drivers/ide/dtc2278.c> files for more info.
config BLK_DEV_HT6560B
@@ -841,7 +841,7 @@ config BLK_DEV_HT6560B
This driver is enabled at runtime using the "ht6560b.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the Holtek card, and permits faster I/O speeds to be set as well.
- See the <file:Documentation/ide/ide.txt> and
+ See the <file:Documentation/ide/ide.rst> and
<file:drivers/ide/ht6560b.c> files for more info.
config BLK_DEV_QD65XX
@@ -851,7 +851,7 @@ config BLK_DEV_QD65XX
help
This driver is enabled at runtime using the "qd65xx.probe" kernel
boot parameter. It permits faster I/O speeds to be set. See the
- <file:Documentation/ide/ide.txt> and <file:drivers/ide/qd65xx.c>
+ <file:Documentation/ide/ide.rst> and <file:drivers/ide/qd65xx.c>
for more info.
config BLK_DEV_UMC8672
@@ -862,7 +862,7 @@ config BLK_DEV_UMC8672
This driver is enabled at runtime using the "umc8672.probe" kernel
boot parameter. It enables support for the secondary IDE interface
of the UMC-8672, and permits faster I/O speeds to be set as well.
- See the files <file:Documentation/ide/ide.txt> and
+ See the files <file:Documentation/ide/ide.rst> and
<file:drivers/ide/umc8672.c> for more info.
endif
--
2.21.0
^ permalink raw reply related
* [PATCH v3 27/33] s390: include/asm/debug.h add kerneldoc markups
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Heiko Carstens, Vasily Gorbik,
Christian Borntraeger, linux-s390
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
Instead of keeping the documentation inside s390dbf.rst,
move them to arch/s390/include/asm/debug.h, using standard
kernel-doc markups.
Keeping the documentation close to the code helps to keep it
updated. It also makes easier to document other stuff inside
debug.h, as all it needs is to add kernel-doc markups inside
it, as the file will be already be included at the produced
documentation.
-
Those were converted to kerneldoc using this script specially
designed to parse ths file, and manually editted:
<script>
use strict;
my $mode = "";
my $parameter = "";
my $ret = "";
my $descr = "";
sub add_var($)
{
my $ln = shift;
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
$ln =~ s/^(\S+)\s+/$1\t/;
print " * \@$ln\n";
}
sub add_return($)
{
my $ln = shift;
print " *\n * Return:\n" if ($mode ne "Return Value:");
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
print " * - $ln\n";
}
sub add_description($)
{
my $ln = shift;
print " *\n * \n" if ($mode ne "Description:");
$ln =~ s/^\s+//;
$ln =~ s/\s+$//;
return if ($ln eq "");
print " * $ln\n";
}
sub flush_results()
{
print " */\n\n";
}
while (<>) {
if (m/^[\-]+$/) {
flush_results();
$mode = "";
$parameter = "";
$ret = "";
$descr = "";
next;
}
if (m/(Parameter:)(.*)/) {
print " *\n" if ($mode eq "func");
add_var($2);
$mode = $1;
next;
}
if (m/(Return Value:)(.*)/) {
add_return($2);
$mode = $1;
next;
}
if (m/(Description:)(.*)/) {
add_description($2);
$mode = $1;
next;
}
if ($mode eq "Parameter:") {
add_var($_);
next;
}
if ($mode eq "Return Value:") {
add_return($_);
next;
}
if ($mode eq "Description:") {
add_description($_);
next;
}
next if (m/^\s*$/);
if (m/^\S+.*\s\*?(\S+)\s*\(/) {
if ($mode eq "") {
print "/**\n * $1()\n";
} else {
print " * $1()\n";
}
$mode="func";
}
}
flush_results();
</script>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/s390/s390dbf.rst | 672 +--------------------------------
arch/s390/include/asm/debug.h | 231 ++++++++++++
2 files changed, 232 insertions(+), 671 deletions(-)
diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst
index ec2a1faa414b..d2595b548879 100644
--- a/Documentation/s390/s390dbf.rst
+++ b/Documentation/s390/s390dbf.rst
@@ -104,684 +104,14 @@ the "debug_stoppable" sysctl. If you set "debug_stoppable" to 0 the debug
feature cannot be stopped. If the debug feature is already stopped, it
will stay deactivated.
-----------------------------------------------------------------------------
-
Kernel Interfaces:
------------------
-::
-
- debug_info_t *debug_register(char *name, int pages, int nr_areas,
- int buf_size);
-
-Parameter:
- name:
- Name of debug log (e.g. used for debugfs entry)
- pages:
- Number of pages, which will be allocated per area
- nr_areas:
- Number of debug areas
- buf_size:
- Size of data area in each debug entry
-
-Return Value:
- Handle for generated debug area
-
- NULL if register failed
-
-Description: Allocates memory for a debug log
- Must not be called within an interrupt handler
-
-----------------------------------------------------------------------------
-
-::
-
- debug_info_t *debug_register_mode(char *name, int pages, int nr_areas,
- int buf_size, mode_t mode, uid_t uid,
- gid_t gid);
-
-Parameter:
- name:
- Name of debug log (e.g. used for debugfs entry)
- pages:
- Number of pages, which will be allocated per area
- nr_areas:
- Number of debug areas
- buf_size:
- Size of data area in each debug entry
- mode:
- File mode for debugfs files. E.g. S_IRWXUGO
- uid:
- User ID for debugfs files. Currently only 0 is
- supported.
- gid:
- Group ID for debugfs files. Currently only 0 is
- supported.
-
-Return Value:
- Handle for generated debug area
-
- NULL if register failed
-
-Description:
- Allocates memory for a debug log
- Must not be called within an interrupt handler
-
----------------------------------------------------------------------------
-
-::
-
- void debug_unregister (debug_info_t * id);
-
-Parameter:
- id:
- handle for debug log
-
-Return Value:
- none
-
-Description:
- frees memory for a debug log and removes all registered debug
- views.
-
- Must not be called within an interrupt handler
-
----------------------------------------------------------------------------
-
-::
-
- void debug_set_level (debug_info_t * id, int new_level);
-
-Parameter: id: handle for debug log
- new_level: new debug level
-
-Return Value:
- none
-
-Description:
- Sets new actual debug level if new_level is valid.
-
----------------------------------------------------------------------------
-
-::
-
- bool debug_level_enabled (debug_info_t * id, int level);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
-
-Return Value:
- True if level is less or equal to the current debug level.
-
-Description:
- Returns true if debug events for the specified level would be
- logged. Otherwise returns false.
-
----------------------------------------------------------------------------
-
-::
-
- void debug_stop_all(void);
-
-Parameter:
- none
-
-Return Value:
- none
-
-Description:
- stops the debug feature if stopping is allowed. Currently
- used in case of a kernel oops.
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_event (debug_info_t* id, int level, void* data,
- int length);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- pointer to data for debug entry
- length:
- length of data in bytes
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_int_event (debug_info_t * id, int level,
- unsigned int data);
- debug_entry_t* debug_long_event(debug_info_t * id, int level,
- unsigned long data);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- integer value for debug entry
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_text_event (debug_info_t * id, int level,
- const char* data);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- string for debug entry
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry in ascii format to active debug area
- (if level <= actual debug level)
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_sprintf_event (debug_info_t * id, int level,
- char* string,...);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- string:
- format string for debug entry
- ...:
- varargs used as in sprintf()
-
-Return Value: Address of written debug entry
-
-Description:
- writes debug entry with format string and varargs (longs) to
- active debug area (if level $<=$ actual debug level).
- floats and long long datatypes cannot be used as varargs.
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_exception (debug_info_t* id, int level, void* data,
- int length);
-
-Parameter:
- id:
- handle for debug log
- level:
- debug level
- data:
- pointer to data for debug entry
- length:
- length of data in bytes
-
-Return Value:
- Address of written debug entry
-
-Description:
- writes debug entry to active debug area (if level <= actual
- debug level) and switches to next debug area
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_int_exception (debug_info_t * id, int level,
- unsigned int data);
- debug_entry_t* debug_long_exception(debug_info_t * id, int level,
- unsigned long data);
-
-Parameter: id: handle for debug log
- level: debug level
- data: integer value for debug entry
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry to active debug area (if level <= actual
- debug level) and switches to next debug area
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_text_exception (debug_info_t * id, int level,
- const char* data);
-
-Parameter: id: handle for debug log
- level: debug level
- data: string for debug entry
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry in ascii format to active debug area
- (if level <= actual debug level) and switches to next debug
- area
-
----------------------------------------------------------------------------
-
-::
-
- debug_entry_t* debug_sprintf_exception (debug_info_t * id, int level,
- char* string,...);
-
-Parameter: id: handle for debug log
- level: debug level
- string: format string for debug entry
- ...: varargs used as in sprintf()
-
-Return Value: Address of written debug entry
-
-Description: writes debug entry with format string and varargs (longs) to
- active debug area (if level $<=$ actual debug level) and
- switches to next debug area.
- floats and long long datatypes cannot be used as varargs.
-
----------------------------------------------------------------------------
-
-::
-
- int debug_register_view (debug_info_t * id, struct debug_view *view);
-
-Parameter: id: handle for debug log
- view: pointer to debug view struct
-
-Return Value: 0 : ok
- < 0: Error
-
-Description: registers new debug view and creates debugfs dir entry
-
----------------------------------------------------------------------------
-
-::
-
- int debug_unregister_view (debug_info_t * id, struct debug_view *view);
-
-Parameter: id: handle for debug log
- view: pointer to debug view struct
-
-Return Value: 0 : ok
- < 0: Error
-
-Description: unregisters debug view and removes debugfs dir entry
-
-
+.. kernel-doc:: arch/s390/include/asm/debug.h
Predefined views:
-----------------
-extern struct debug_view debug_hex_ascii_view;
-
-extern struct debug_view debug_raw_view;
-
-extern struct debug_view debug_sprintf_view;
-
-Examples
---------
-
-::
-
- /*
- * hex_ascii- + raw-view Example
- */
-
- #include <linux/init.h>
- #include <asm/debug.h>
-
- static debug_info_t* debug_info;
-
- static int init(void)
- {
- /* register 4 debug areas with one page each and 4 byte data field */
-
- debug_info = debug_register ("test", 1, 4, 4 );
- debug_register_view(debug_info,&debug_hex_ascii_view);
- debug_register_view(debug_info,&debug_raw_view);
-
- debug_text_event(debug_info, 4 , "one ");
- debug_int_exception(debug_info, 4, 4711);
- debug_event(debug_info, 3, &debug_info, 4);
-
- return 0;
- }
-
- static void cleanup(void)
- {
- debug_unregister (debug_info);
- }
-
- module_init(init);
- module_exit(cleanup);
-
----------------------------------------------------------------------------
-
-::
-
- /*
- * sprintf-view Example
- */
-
- #include <linux/init.h>
- #include <asm/debug.h>
-
- static debug_info_t* debug_info;
-
- static int init(void)
- {
- /* register 4 debug areas with one page each and data field for */
- /* format string pointer + 2 varargs (= 3 * sizeof(long)) */
-
- debug_info = debug_register ("test", 1, 4, sizeof(long) * 3);
- debug_register_view(debug_info,&debug_sprintf_view);
-
- debug_sprintf_event(debug_info, 2 , "first event in %s:%i\n",__FILE__,__LINE__);
- debug_sprintf_exception(debug_info, 1, "pointer to debug info: %p\n",&debug_info);
-
- return 0;
- }
-
- static void cleanup(void)
- {
- debug_unregister (debug_info);
- }
-
- module_init(init);
- module_exit(cleanup);
-
-Debugfs Interface
------------------
-Views to the debug logs can be investigated through reading the corresponding
-debugfs-files:
-
-Example::
-
- > ls /sys/kernel/debug/s390dbf/dasd
- flush hex_ascii level pages raw
- > cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort -k2,2 -s
- 00 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | ....
- 00 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE
- 00 00974733272:682213 2 - 02 0006adf6 07 ea 4a 90 | ....
- 00 00974733272:682281 1 * 02 0006ab08 41 4c 4c 43 | EXCP
- 01 00974733272:682284 2 - 02 0006ab16 45 43 4b 44 | ECKD
- 01 00974733272:682287 2 - 02 0006ab28 00 00 00 04 | ....
- 01 00974733272:682289 2 - 02 0006ab3e 00 00 00 20 | ...
- 01 00974733272:682297 2 - 02 0006ad7e 07 ea 4a 90 | ....
- 01 00974733272:684384 2 - 00 0006ade6 46 52 45 45 | FREE
- 01 00974733272:684388 2 - 00 0006adf6 07 ea 4a 90 | ....
-
-See section about predefined views for explanation of the above output!
-
-Changing the debug level
-------------------------
-
-Example::
-
-
- > cat /sys/kernel/debug/s390dbf/dasd/level
- 3
- > echo "5" > /sys/kernel/debug/s390dbf/dasd/level
- > cat /sys/kernel/debug/s390dbf/dasd/level
- 5
-
-Flushing debug areas
---------------------
-Debug areas can be flushed with piping the number of the desired
-area (0...n) to the debugfs file "flush". When using "-" all debug areas
-are flushed.
-
-Examples:
-
-1. Flush debug area 0::
-
- > echo "0" > /sys/kernel/debug/s390dbf/dasd/flush
-
-2. Flush all debug areas::
-
- > echo "-" > /sys/kernel/debug/s390dbf/dasd/flush
-
-Changing the size of debug areas
-------------------------------------
-It is possible the change the size of debug areas through piping
-the number of pages to the debugfs file "pages". The resize request will
-also flush the debug areas.
-
-Example:
-
-Define 4 pages for the debug areas of debug feature "dasd"::
-
- > echo "4" > /sys/kernel/debug/s390dbf/dasd/pages
-
-Stooping the debug feature
---------------------------
-Example:
-
-1. Check if stopping is allowed::
-
- > cat /proc/sys/s390dbf/debug_stoppable
-
-2. Stop debug feature::
-
- > echo 0 > /proc/sys/s390dbf/debug_active
-
-lcrash Interface
-----------------
-It is planned that the dump analysis tool lcrash gets an additional command
-'s390dbf' to display all the debug logs. With this tool it will be possible
-to investigate the debug logs on a live system and with a memory dump after
-a system crash.
-
-Investigating raw memory
-------------------------
-One last possibility to investigate the debug logs at a live
-system and after a system crash is to look at the raw memory
-under VM or at the Service Element.
-It is possible to find the anker of the debug-logs through
-the 'debug_area_first' symbol in the System map. Then one has
-to follow the correct pointers of the data-structures defined
-in debug.h and find the debug-areas in memory.
-Normally modules which use the debug feature will also have
-a global variable with the pointer to the debug-logs. Following
-this pointer it will also be possible to find the debug logs in
-memory.
-
-For this method it is recommended to use '16 * x + 4' byte (x = 0..n)
-for the length of the data field in debug_register() in
-order to see the debug entries well formatted.
-
-
-Predefined Views
-----------------
-
-There are three predefined views: hex_ascii, raw and sprintf.
-The hex_ascii view shows the data field in hex and ascii representation
-(e.g. '45 43 4b 44 | ECKD').
-The raw view returns a bytestream as the debug areas are stored in memory.
-
-The sprintf view formats the debug entries in the same way as the sprintf
-function would do. The sprintf event/exception functions write to the
-debug entry a pointer to the format string (size = sizeof(long))
-and for each vararg a long value. So e.g. for a debug entry with a format
-string plus two varargs one would need to allocate a (3 * sizeof(long))
-byte data area in the debug_register() function.
-
-IMPORTANT:
- Using "%s" in sprintf event functions is dangerous. You can only
- use "%s" in the sprintf event functions, if the memory for the passed string
- is available as long as the debug feature exists. The reason behind this is
- that due to performance considerations only a pointer to the string is stored
- in the debug feature. If you log a string that is freed afterwards, you will
- get an OOPS when inspecting the debug feature, because then the debug feature
- will access the already freed memory.
-
-NOTE:
- If using the sprintf view do NOT use other event/exception functions
- than the sprintf-event and -exception functions.
-
-The format of the hex_ascii and sprintf view is as follows:
-
-- Number of area
-- Timestamp (formatted as seconds and microseconds since 00:00:00 Coordinated
- Universal Time (UTC), January 1, 1970)
-- level of debug entry
-- Exception flag (* = Exception)
-- Cpu-Number of calling task
-- Return Address to caller
-- data field
-
-The format of the raw view is:
-
-- Header as described in debug.h
-- datafield
-
-A typical line of the hex_ascii view will look like the following (first line
-is only for explanation and will not be displayed when 'cating' the view):
-
-area time level exception cpu caller data (hex + ascii)
---------------------------------------------------------------------------
-00 00964419409:440690 1 - 00 88023fe
-
-
-Defining views
---------------
-
-Views are specified with the 'debug_view' structure. There are defined
-callback functions which are used for reading and writing the debugfs files::
-
- struct debug_view {
- char name[DEBUG_MAX_PROCF_LEN];
- debug_prolog_proc_t* prolog_proc;
- debug_header_proc_t* header_proc;
- debug_format_proc_t* format_proc;
- debug_input_proc_t* input_proc;
- void* private_data;
- };
-
-where::
-
- typedef int (debug_header_proc_t) (debug_info_t* id,
- struct debug_view* view,
- int area,
- debug_entry_t* entry,
- char* out_buf);
-
- typedef int (debug_format_proc_t) (debug_info_t* id,
- struct debug_view* view, char* out_buf,
- const char* in_buf);
- typedef int (debug_prolog_proc_t) (debug_info_t* id,
- struct debug_view* view,
- char* out_buf);
- typedef int (debug_input_proc_t) (debug_info_t* id,
- struct debug_view* view,
- struct file* file, const char* user_buf,
- size_t in_buf_size, loff_t* offset);
-
-
-The "private_data" member can be used as pointer to view specific data.
-It is not used by the debug feature itself.
-
-The output when reading a debugfs file is structured like this::
-
- "prolog_proc output"
-
- "header_proc output 1" "format_proc output 1"
- "header_proc output 2" "format_proc output 2"
- "header_proc output 3" "format_proc output 3"
- ...
-
-When a view is read from the debugfs, the Debug Feature calls the
-'prolog_proc' once for writing the prolog.
-Then 'header_proc' and 'format_proc' are called for each
-existing debug entry.
-
-The input_proc can be used to implement functionality when it is written to
-the view (e.g. like with 'echo "0" > /sys/kernel/debug/s390dbf/dasd/level).
-
-For header_proc there can be used the default function
-debug_dflt_header_fn() which is defined in debug.h.
-and which produces the same header output as the predefined views.
-E.g::
-
- 00 00964419409:440761 2 - 00 88023ec
-
-In order to see how to use the callback functions check the implementation
-of the default views!
-
-Example::
-
- #include <asm/debug.h>
-
- #define UNKNOWNSTR "data: %08x"
-
- const char* messages[] =
- {"This error...........\n",
- "That error...........\n",
- "Problem..............\n",
- "Something went wrong.\n",
- "Everything ok........\n",
- NULL
- };
-
- static int debug_test_format_fn(
- debug_info_t * id, struct debug_view *view,
- char *out_buf, const char *in_buf
- )
- {
- int i, rc = 0;
-
- if(id->buf_size >= 4) {
- int msg_nr = *((int*)in_buf);
- if(msg_nr < sizeof(messages)/sizeof(char*) - 1)
- rc += sprintf(out_buf, "%s", messages[msg_nr]);
- else
- rc += sprintf(out_buf, UNKNOWNSTR, msg_nr);
- }
- out:
- return rc;
- }
-
- struct debug_view debug_test_view = {
- "myview", /* name of view */
- NULL, /* no prolog */
- &debug_dflt_header_fn, /* default header for each entry */
- &debug_test_format_fn, /* our own format function */
- NULL, /* no input function */
- NULL /* no private data */
- };
-
-test:
-=====
-
::
debug_info_t *debug_info;
diff --git a/arch/s390/include/asm/debug.h b/arch/s390/include/asm/debug.h
index b94783f71322..b55486f70deb 100644
--- a/arch/s390/include/asm/debug.h
+++ b/arch/s390/include/asm/debug.h
@@ -95,25 +95,106 @@ debug_entry_t *debug_exception_common(debug_info_t *id, int level,
/* Debug Feature API: */
+/**
+ * debug_register() - allocates memory for a debug log.
+ *
+ * @name: Name of debug log (e.g. used for debugfs entry)
+ * @pages: Number of pages, which will be allocated per area
+ * @nr_areas: Number of debug areas
+ * @buf_size: Size of data area in each debug entry
+ *
+ * Return:
+ * - Handler for generated debug area
+ * - %NULL if register failed
+ *
+ * Must not be called within an interrupt handler.
+ */
debug_info_t *debug_register(const char *name, int pages, int nr_areas,
int buf_size);
+/**
+ * debug_register_mode() - allocates memory for a debug log.
+ *
+ * @name: Name of debug log (e.g. used for debugfs entry)
+ * @pages: Number of pages, which will be allocated per area
+ * @nr_areas: Number of debug areas
+ * @buf_size: Size of data area in each debug entry
+ * @mode: File mode for debugfs files. E.g. S_IRWXUGO
+ * @uid: User ID for debugfs files. Currently only 0 is supported.
+ * @gid: Group ID for debugfs files. Currently only 0 is supported.
+ *
+ * Return:
+ * - Handler for generated debug area
+ * - %NULL if register failed
+ *
+ * Must not be called within an interrupt handler
+ */
debug_info_t *debug_register_mode(const char *name, int pages, int nr_areas,
int buf_size, umode_t mode, uid_t uid,
gid_t gid);
+/**
+ * debug_unregister() - frees memory for a debug log and removes all
+ * registered debug
+ * views.
+ *
+ * @id: handle for debug log
+ *
+ * Return:
+ * none
+ *
+ * Must not be called within an interrupt handler
+ */
void debug_unregister(debug_info_t *id);
+/**
+ * debug_set_level() - Sets new actual debug level if new_level is valid.
+ *
+ * @id: handle for debug log
+ * @new_level: new debug level
+ *
+ * Return:
+ * none
+ */
void debug_set_level(debug_info_t *id, int new_level);
void debug_set_critical(void);
+
+/**
+ * debug_stop_all() - stops the debug feature if stopping is allowed.
+ *
+ * Return:
+ * - none
+ */
void debug_stop_all(void);
+/**
+ * debug_level_enabled() - Returns true if debug events for the specified
+ * level would be logged. Otherwise returns false.
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ *
+ * Return:
+ * - %true if level is less or equal to the current debug level.
+ */
static inline bool debug_level_enabled(debug_info_t *id, int level)
{
return level <= id->level;
}
+/**
+ * debug_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @data: pointer to data for debug entry
+ * @length: length of data in bytes
+ *
+ * Return:
+ * - Address of written debug entry
+ */
static inline debug_entry_t *debug_event(debug_info_t *id, int level,
void *data, int length)
{
@@ -122,6 +203,18 @@ static inline debug_entry_t *debug_event(debug_info_t *id, int level,
return debug_event_common(id, level, data, length);
}
+/**
+ * debug_int_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
unsigned int tag)
{
@@ -132,6 +225,18 @@ static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
return debug_event_common(id, level, &t, sizeof(unsigned int));
}
+/**
+ * debug_long_event() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
unsigned long tag)
{
@@ -142,6 +247,18 @@ static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
return debug_event_common(id, level, &t, sizeof(unsigned long));
}
+/**
+ * debug_text_event() - writes debug entry in ascii format to active
+ * debug area (if level <= actual debug level)
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @txt: string for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_text_event(debug_info_t *id, int level,
const char *txt)
{
@@ -158,6 +275,22 @@ extern debug_entry_t *
__debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
__attribute__ ((format(printf, 3, 4)));
+/**
+ * debug_sprintf_event() - writes debug entry with format string
+ * and varargs (longs) to active debug area
+ * (if level $<=$ actual debug level).
+ *
+ * @_id: handle for debug log
+ * @_level: debug level
+ * @_fmt: format string for debug entry
+ * @...: varargs used as in sprintf()
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ *
+ * floats and long long datatypes cannot be used as varargs.
+ */
#define debug_sprintf_event(_id, _level, _fmt, ...) \
({ \
debug_entry_t *__ret; \
@@ -172,6 +305,20 @@ __debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
__ret; \
})
+/**
+ * debug_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level) and switches
+ * to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @data: pointer to data for debug entry
+ * @length: length of data in bytes
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
void *data, int length)
{
@@ -180,6 +327,19 @@ static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
return debug_exception_common(id, level, data, length);
}
+/**
+ * debug_int_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ * and switches to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
unsigned int tag)
{
@@ -190,6 +350,19 @@ static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
return debug_exception_common(id, level, &t, sizeof(unsigned int));
}
+/**
+ * debug_long_exception() - writes debug entry to active debug area
+ * (if level <= actual debug level)
+ * and switches to next debug area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @tag: integer value for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
unsigned long tag)
{
@@ -200,6 +373,20 @@ static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
return debug_exception_common(id, level, &t, sizeof(unsigned long));
}
+/**
+ * debug_text_exception() - writes debug entry in ascii format to active
+ * debug area (if level <= actual debug level)
+ * and switches to next debug
+ * area
+ *
+ * @id: handle for debug log
+ * @level: debug level
+ * @txt: string for debug entry
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ */
static inline debug_entry_t *debug_text_exception(debug_info_t *id, int level,
const char *txt)
{
@@ -216,6 +403,24 @@ extern debug_entry_t *
__debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
__attribute__ ((format(printf, 3, 4)));
+
+/**
+ * debug_sprintf_exception() - writes debug entry with format string and
+ * varargs (longs) to active debug area
+ * (if level $<=$ actual debug level)
+ * and switches to next debug area.
+ *
+ * @_id: handle for debug log
+ * @_level: debug level
+ * @_fmt: format string for debug entry
+ * @...: varargs used as in sprintf()
+ *
+ * Return:
+ * - Address of written debug entry
+ * - %NULL if error
+ *
+ * floats and long long datatypes cannot be used as varargs.
+ */
#define debug_sprintf_exception(_id, _level, _fmt, ...) \
({ \
debug_entry_t *__ret; \
@@ -230,7 +435,33 @@ __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
__ret; \
})
+/**
+ * debug_register_view() - registers new debug view and creates debugfs
+ * dir entry
+ *
+ * @id: handle for debug log
+ * @view: pointer to debug view struct
+ *
+ * Return:
+ * - 0 : ok
+ * - < 0: Error
+ */
int debug_register_view(debug_info_t *id, struct debug_view *view);
+
+/**
+ * debug_unregister_view()
+ *
+ * @id: handle for debug log
+ * @view: pointer to debug view struct
+ *
+ * Return:
+ * - 0 : ok
+ * - < 0: Error
+ *
+ *
+ * unregisters debug view and removes debugfs dir entry
+ */
+
int debug_unregister_view(debug_info_t *id, struct debug_view *view);
/*
--
2.21.0
^ permalink raw reply related
* [PATCH v3 24/33] docs: riscv: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Palmer Dabbelt, Albert Ou, linux-riscv
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The conversion here is trivial:
- Adjust the document title's markup
- Do some whitespace alignment;
- mark literal blocks;
- Use ReST way to markup indented lists.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/riscv/index.rst | 17 ++++
Documentation/riscv/{pmu.txt => pmu.rst} | 98 +++++++++++++-----------
2 files changed, 69 insertions(+), 46 deletions(-)
create mode 100644 Documentation/riscv/index.rst
rename Documentation/riscv/{pmu.txt => pmu.rst} (77%)
diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
new file mode 100644
index 000000000000..c4b906d9b5a7
--- /dev/null
+++ b/Documentation/riscv/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+===================
+RISC-V architecture
+===================
+
+.. toctree::
+ :maxdepth: 1
+
+ pmu
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/riscv/pmu.txt b/Documentation/riscv/pmu.rst
similarity index 77%
rename from Documentation/riscv/pmu.txt
rename to Documentation/riscv/pmu.rst
index b29f03a6d82f..acb216b99c26 100644
--- a/Documentation/riscv/pmu.txt
+++ b/Documentation/riscv/pmu.rst
@@ -1,5 +1,7 @@
+===================================
Supporting PMUs on RISC-V platforms
-==========================================
+===================================
+
Alan Kao <alankao@andestech.com>, Mar 2018
Introduction
@@ -77,13 +79,13 @@ Note that some features can be done in this stage as well:
(2) privilege level setting (user space only, kernel space only, both);
(3) destructor setting. Normally it is sufficient to apply *riscv_destroy_event*;
(4) tweaks for non-sampling events, which will be utilized by functions such as
-*perf_adjust_period*, usually something like the follows:
+ *perf_adjust_period*, usually something like the follows::
-if (!is_sampling_event(event)) {
- hwc->sample_period = x86_pmu.max_period;
- hwc->last_period = hwc->sample_period;
- local64_set(&hwc->period_left, hwc->sample_period);
-}
+ if (!is_sampling_event(event)) {
+ hwc->sample_period = x86_pmu.max_period;
+ hwc->last_period = hwc->sample_period;
+ local64_set(&hwc->period_left, hwc->sample_period);
+ }
In the case of *riscv_base_pmu*, only (3) is provided for now.
@@ -94,10 +96,10 @@ In the case of *riscv_base_pmu*, only (3) is provided for now.
3.1. Interrupt Initialization
This often occurs at the beginning of the *event_init* method. In common
-practice, this should be a code segment like
+practice, this should be a code segment like::
-int x86_reserve_hardware(void)
-{
+ int x86_reserve_hardware(void)
+ {
int err = 0;
if (!atomic_inc_not_zero(&pmc_refcount)) {
@@ -114,7 +116,7 @@ int x86_reserve_hardware(void)
}
return err;
-}
+ }
And the magic is in *reserve_pmc_hardware*, which usually does atomic
operations to make implemented IRQ accessible from some global function pointer.
@@ -128,28 +130,28 @@ which will be introduced in the next section.)
3.2. IRQ Structure
-Basically, a IRQ runs the following pseudo code:
+Basically, a IRQ runs the following pseudo code::
-for each hardware counter that triggered this overflow
+ for each hardware counter that triggered this overflow
- get the event of this counter
+ get the event of this counter
- // following two steps are defined as *read()*,
- // check the section Reading/Writing Counters for details.
- count the delta value since previous interrupt
- update the event->count (# event occurs) by adding delta, and
- event->hw.period_left by subtracting delta
+ // following two steps are defined as *read()*,
+ // check the section Reading/Writing Counters for details.
+ count the delta value since previous interrupt
+ update the event->count (# event occurs) by adding delta, and
+ event->hw.period_left by subtracting delta
- if the event overflows
- sample data
- set the counter appropriately for the next overflow
+ if the event overflows
+ sample data
+ set the counter appropriately for the next overflow
- if the event overflows again
- too frequently, throttle this event
- fi
- fi
+ if the event overflows again
+ too frequently, throttle this event
+ fi
+ fi
-end for
+ end for
However as of this writing, none of the RISC-V implementations have designed an
interrupt for perf, so the details are to be completed in the future.
@@ -195,23 +197,26 @@ A normal flow of these state transitions are as follows:
At this stage, a general event is bound to a physical counter, if any.
The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now
stopped, and the (software) event count does not need updating.
-** *start* is then called, and the counter is enabled.
- With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check
- previous section for detail).
- Nothing is written if the flag does not contain PERF_EF_RELOAD.
- The state now is reset to none, because it is neither stopped nor updated
- (the counting already started)
+
+ - *start* is then called, and the counter is enabled.
+ With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check
+ previous section for detail).
+ Nothing is written if the flag does not contain PERF_EF_RELOAD.
+ The state now is reset to none, because it is neither stopped nor updated
+ (the counting already started)
+
* When being context-switched out, *del* is called. It then checks out all the
events in the PMU and calls *stop* to update their counts.
-** *stop* is called by *del*
- and the perf core with flag PERF_EF_UPDATE, and it often shares the same
- subroutine as *read* with the same logic.
- The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.
-** Life cycle of these two pairs: *add* and *del* are called repeatedly as
- tasks switch in-and-out; *start* and *stop* is also called when the perf core
- needs a quick stop-and-start, for instance, when the interrupt period is being
- adjusted.
+ - *stop* is called by *del*
+ and the perf core with flag PERF_EF_UPDATE, and it often shares the same
+ subroutine as *read* with the same logic.
+ The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.
+
+ - Life cycle of these two pairs: *add* and *del* are called repeatedly as
+ tasks switch in-and-out; *start* and *stop* is also called when the perf core
+ needs a quick stop-and-start, for instance, when the interrupt period is being
+ adjusted.
Current implementation is sufficient for now and can be easily extended to
features in the future.
@@ -225,25 +230,26 @@ A. Related Structures
Both structures are designed to be read-only.
*struct pmu* defines some function pointer interfaces, and most of them take
-*struct perf_event* as a main argument, dealing with perf events according to
-perf's internal state machine (check kernel/events/core.c for details).
+ *struct perf_event* as a main argument, dealing with perf events according to
+ perf's internal state machine (check kernel/events/core.c for details).
*struct riscv_pmu* defines PMU-specific parameters. The naming follows the
-convention of all other architectures.
+ convention of all other architectures.
* struct perf_event: include/linux/perf_event.h
* struct hw_perf_event
The generic structure that represents perf events, and the hardware-related
-details.
+ details.
* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h
The structure that holds the status of events, has two fixed members:
-the number of events and the array of the events.
+ the number of events and the array of the events.
References
----------
[1] https://github.com/riscv/riscv-linux/pull/124
+
[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA
--
2.21.0
^ permalink raw reply related
* [PATCH v3 23/33] docs: ptp.txt: convert to ReST and move to driver-api
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Richard Cochran, David S. Miller, netdev
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The conversion is trivial: just adjust title markups.
In order to avoid conflicts, let's add an :orphan: tag
to it, to be removed when this file gets added to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{ptp/ptp.txt => driver-api/ptp.rst} | 26 +++++++++++++------
Documentation/networking/timestamping.txt | 2 +-
MAINTAINERS | 2 +-
3 files changed, 20 insertions(+), 10 deletions(-)
rename Documentation/{ptp/ptp.txt => driver-api/ptp.rst} (88%)
diff --git a/Documentation/ptp/ptp.txt b/Documentation/driver-api/ptp.rst
similarity index 88%
rename from Documentation/ptp/ptp.txt
rename to Documentation/driver-api/ptp.rst
index 11e904ee073f..b6e65d66d37a 100644
--- a/Documentation/ptp/ptp.txt
+++ b/Documentation/driver-api/ptp.rst
@@ -1,5 +1,8 @@
+:orphan:
-* PTP hardware clock infrastructure for Linux
+===========================================
+PTP hardware clock infrastructure for Linux
+===========================================
This patch set introduces support for IEEE 1588 PTP clocks in
Linux. Together with the SO_TIMESTAMPING socket options, this
@@ -22,7 +25,8 @@
- Period output signals configurable from user space
- Synchronization of the Linux system time via the PPS subsystem
-** PTP hardware clock kernel API
+PTP hardware clock kernel API
+=============================
A PTP clock driver registers itself with the class driver. The
class driver handles all of the dealings with user space. The
@@ -36,7 +40,8 @@
development, it can be useful to have more than one clock in a
single system, in order to allow performance comparisons.
-** PTP hardware clock user space API
+PTP hardware clock user space API
+=================================
The class driver also creates a character device for each
registered clock. User space can use an open file descriptor from
@@ -49,7 +54,8 @@
ancillary clock features. User space can receive time stamped
events via blocking read() and poll().
-** Writing clock drivers
+Writing clock drivers
+=====================
Clock drivers include include/linux/ptp_clock_kernel.h and register
themselves by presenting a 'struct ptp_clock_info' to the
@@ -66,14 +72,17 @@
class driver, since the lock may also be needed by the clock
driver's interrupt service routine.
-** Supported hardware
+Supported hardware
+==================
+
+ * Freescale eTSEC gianfar
- + Freescale eTSEC gianfar
- 2 Time stamp external triggers, programmable polarity (opt. interrupt)
- 2 Alarm registers (optional interrupt)
- 3 Periodic signals (optional interrupt)
- + National DP83640
+ * National DP83640
+
- 6 GPIOs programmable as inputs or outputs
- 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
used as general inputs or outputs
@@ -81,6 +90,7 @@
- GPIO outputs can produce periodic signals
- 1 interrupt pin
- + Intel IXP465
+ * Intel IXP465
+
- Auxiliary Slave/Master Mode Snapshot (optional interrupt)
- Target Time (optional interrupt)
diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt
index bbdaf8990031..8dd6333c3270 100644
--- a/Documentation/networking/timestamping.txt
+++ b/Documentation/networking/timestamping.txt
@@ -368,7 +368,7 @@ ts[1] used to hold hardware timestamps converted to system time.
Instead, expose the hardware clock device on the NIC directly as
a HW PTP clock source, to allow time conversion in userspace and
optionally synchronize system time with a userspace PTP stack such
-as linuxptp. For the PTP clock API, see Documentation/ptp/ptp.txt.
+as linuxptp. For the PTP clock API, see Documentation/driver-api/ptp.rst.
Note that if the SO_TIMESTAMP or SO_TIMESTAMPNS option is enabled
together with SO_TIMESTAMPING using SOF_TIMESTAMPING_SOFTWARE, a false
diff --git a/MAINTAINERS b/MAINTAINERS
index b982622ea7ee..72d1e5da0779 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12795,7 +12795,7 @@ L: netdev@vger.kernel.org
S: Maintained
W: http://linuxptp.sourceforge.net/
F: Documentation/ABI/testing/sysfs-ptp
-F: Documentation/ptp/*
+F: Documentation/driver-api/ptp.rst
F: drivers/net/phy/dp83640*
F: drivers/ptp/*
F: include/linux/ptp_cl*
--
2.21.0
^ permalink raw reply related
* [PATCH v3 06/33] docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
From: Mauro Carvalho Chehab @ 2019-06-09 2:26 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The CFQ scheduler was removed on this changeset:
commit f382fb0bcef4c37dc049e9f6963e3baf204d815c
Author: Jens Axboe <axboe@kernel.dk>
Date: Fri Oct 12 10:14:46 2018 -0600
block: remove legacy IO schedulers
Retain the deadline documentation, as that carries over to mq-deadline
as well.
Tested-by: Ming Lei <ming.lei@redhat.com>
Reviewed-by: Omar Sandoval <osandov@fb.com>
Signed-off-by: Jens Axboe <axboe@kernel.dk>
However, the cgroups-v1 documentation still mentions it and points
to a removed file that used to belong to such scheduler.
Add a note about that, as someone needs to fix the document pointing
to another scheduler, if cgroups-v1 blockio is not dependent of
CFQ scheduler.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/cgroup-v1/blkio-controller.rst | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/Documentation/cgroup-v1/blkio-controller.rst b/Documentation/cgroup-v1/blkio-controller.rst
index 2c1b907afc14..2836c2c31e63 100644
--- a/Documentation/cgroup-v1/blkio-controller.rst
+++ b/Documentation/cgroup-v1/blkio-controller.rst
@@ -17,6 +17,13 @@ one is throttling policy which can be used to specify upper IO rate limits
on devices. This policy is implemented in generic block layer and can be
used on leaf nodes as well as higher level logical devices like device mapper.
+.. note::
+
+ While this document mentions the CFQ scheduler, it got removed at
+ Kernel 4.20, as there are other schedulers that are more efficient.
+
+ Someone needs to update this file in order to reflect such change.
+
HOWTO
=====
Proportional Weight division of bandwidth
--
2.21.0
^ permalink raw reply related
* [PATCH v3 18/33] docs: netlabel: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Paul Moore, netdev, linux-security-module
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
Convert netlabel documentation to ReST.
This was trivial: just add proper title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{cipso_ipv4.txt => cipso_ipv4.rst} | 19 +++++++++++------
Documentation/netlabel/draft_ietf.rst | 5 +++++
Documentation/netlabel/index.rst | 21 +++++++++++++++++++
.../{introduction.txt => introduction.rst} | 16 +++++++++-----
.../{lsm_interface.txt => lsm_interface.rst} | 16 +++++++++-----
5 files changed, 61 insertions(+), 16 deletions(-)
rename Documentation/netlabel/{cipso_ipv4.txt => cipso_ipv4.rst} (87%)
create mode 100644 Documentation/netlabel/draft_ietf.rst
create mode 100644 Documentation/netlabel/index.rst
rename Documentation/netlabel/{introduction.txt => introduction.rst} (91%)
rename Documentation/netlabel/{lsm_interface.txt => lsm_interface.rst} (88%)
diff --git a/Documentation/netlabel/cipso_ipv4.txt b/Documentation/netlabel/cipso_ipv4.rst
similarity index 87%
rename from Documentation/netlabel/cipso_ipv4.txt
rename to Documentation/netlabel/cipso_ipv4.rst
index a6075481fd60..cbd3f3231221 100644
--- a/Documentation/netlabel/cipso_ipv4.txt
+++ b/Documentation/netlabel/cipso_ipv4.rst
@@ -1,10 +1,13 @@
+===================================
NetLabel CIPSO/IPv4 Protocol Engine
-==============================================================================
+===================================
+
Paul Moore, paul.moore@hp.com
May 17, 2006
- * Overview
+Overview
+========
The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial
IP Security Option (CIPSO) draft from July 16, 1992. A copy of this
@@ -13,7 +16,8 @@ draft can be found in this directory
it to an RFC standard it has become a de-facto standard for labeled
networking and is used in many trusted operating systems.
- * Outbound Packet Processing
+Outbound Packet Processing
+==========================
The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by
adding the CIPSO label to the socket. This causes all packets leaving the
@@ -24,7 +28,8 @@ label by using the NetLabel security module API; if the NetLabel "domain" is
configured to use CIPSO for packet labeling then a CIPSO IP option will be
generated and attached to the socket.
- * Inbound Packet Processing
+Inbound Packet Processing
+=========================
The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the
IP layer without any special handling required by the LSM. However, in order
@@ -33,7 +38,8 @@ NetLabel security module API to extract the security attributes of the packet.
This is typically done at the socket layer using the 'socket_sock_rcv_skb()'
LSM hook.
- * Label Translation
+Label Translation
+=================
The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security
attributes such as sensitivity level and category to values which are
@@ -42,7 +48,8 @@ Domain Of Interpretation (DOI) definition and are configured through the
NetLabel user space communication layer. Each DOI definition can have a
different security attribute mapping table.
- * Label Translation Cache
+Label Translation Cache
+=======================
The NetLabel system provides a framework for caching security attribute
mappings from the network labels to the corresponding LSM identifiers. The
diff --git a/Documentation/netlabel/draft_ietf.rst b/Documentation/netlabel/draft_ietf.rst
new file mode 100644
index 000000000000..5ed39ab8234b
--- /dev/null
+++ b/Documentation/netlabel/draft_ietf.rst
@@ -0,0 +1,5 @@
+Draft IETF CIPSO IP Security
+----------------------------
+
+ .. include:: draft-ietf-cipso-ipsecurity-01.txt
+ :literal:
diff --git a/Documentation/netlabel/index.rst b/Documentation/netlabel/index.rst
new file mode 100644
index 000000000000..47f1e0e5acd1
--- /dev/null
+++ b/Documentation/netlabel/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+========
+NetLabel
+========
+
+.. toctree::
+ :maxdepth: 1
+
+ introduction
+ cipso_ipv4
+ lsm_interface
+
+ draft_ietf
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/netlabel/introduction.txt b/Documentation/netlabel/introduction.rst
similarity index 91%
rename from Documentation/netlabel/introduction.txt
rename to Documentation/netlabel/introduction.rst
index 3caf77bcff0f..9333bbb0adc1 100644
--- a/Documentation/netlabel/introduction.txt
+++ b/Documentation/netlabel/introduction.rst
@@ -1,10 +1,13 @@
+=====================
NetLabel Introduction
-==============================================================================
+=====================
+
Paul Moore, paul.moore@hp.com
August 2, 2006
- * Overview
+Overview
+========
NetLabel is a mechanism which can be used by kernel security modules to attach
security attributes to outgoing network packets generated from user space
@@ -12,7 +15,8 @@ applications and read security attributes from incoming network packets. It
is composed of three main components, the protocol engines, the communication
layer, and the kernel security module API.
- * Protocol Engines
+Protocol Engines
+================
The protocol engines are responsible for both applying and retrieving the
network packet's security attributes. If any translation between the network
@@ -24,7 +28,8 @@ the NetLabel kernel security module API described below.
Detailed information about each NetLabel protocol engine can be found in this
directory.
- * Communication Layer
+Communication Layer
+===================
The communication layer exists to allow NetLabel configuration and monitoring
from user space. The NetLabel communication layer uses a message based
@@ -33,7 +38,8 @@ formatting of these NetLabel messages as well as the Generic NETLINK family
names can be found in the 'net/netlabel/' directory as comments in the
header files as well as in 'include/net/netlabel.h'.
- * Security Module API
+Security Module API
+===================
The purpose of the NetLabel security module API is to provide a protocol
independent interface to the underlying NetLabel protocol engines. In addition
diff --git a/Documentation/netlabel/lsm_interface.txt b/Documentation/netlabel/lsm_interface.rst
similarity index 88%
rename from Documentation/netlabel/lsm_interface.txt
rename to Documentation/netlabel/lsm_interface.rst
index 638c74f7de7f..026fc267f798 100644
--- a/Documentation/netlabel/lsm_interface.txt
+++ b/Documentation/netlabel/lsm_interface.rst
@@ -1,10 +1,13 @@
+========================================
NetLabel Linux Security Module Interface
-==============================================================================
+========================================
+
Paul Moore, paul.moore@hp.com
May 17, 2006
- * Overview
+Overview
+========
NetLabel is a mechanism which can set and retrieve security attributes from
network packets. It is intended to be used by LSM developers who want to make
@@ -12,7 +15,8 @@ use of a common code base for several different packet labeling protocols.
The NetLabel security module API is defined in 'include/net/netlabel.h' but a
brief overview is given below.
- * NetLabel Security Attributes
+NetLabel Security Attributes
+============================
Since NetLabel supports multiple different packet labeling protocols and LSMs
it uses the concept of security attributes to refer to the packet's security
@@ -24,7 +28,8 @@ configuration. It is up to the LSM developer to translate the NetLabel
security attributes into whatever security identifiers are in use for their
particular LSM.
- * NetLabel LSM Protocol Operations
+NetLabel LSM Protocol Operations
+================================
These are the functions which allow the LSM developer to manipulate the labels
on outgoing packets as well as read the labels on incoming packets. Functions
@@ -32,7 +37,8 @@ exist to operate both on sockets as well as the sk_buffs directly. These high
level functions are translated into low level protocol operations based on how
the administrator has configured the NetLabel subsystem.
- * NetLabel Label Mapping Cache Operations
+NetLabel Label Mapping Cache Operations
+=======================================
Depending on the exact configuration, translation between the network packet
label and the internal LSM security identifier can be time consuming. The
--
2.21.0
^ permalink raw reply related
* [PATCH v3 22/33] docs: pps.txt: convert to ReST and rename to pps.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rodolfo Giometti
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
This file is already in a good shape: just its title and
adding some literal block markups is needed for it to be
part of the document.
While it has a small chapter with sysfs stuff, most of
the document is focused on driver development.
As it describes a kernel API, move it to the driver-api
directory.
In order to avoid conflicts, let's add an :orphan: tag
to it, to be removed when added to the driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{pps/pps.txt => driver-api/pps.rst} | 67 ++++++++++---------
MAINTAINERS | 2 +-
2 files changed, 36 insertions(+), 33 deletions(-)
rename Documentation/{pps/pps.txt => driver-api/pps.rst} (89%)
diff --git a/Documentation/pps/pps.txt b/Documentation/driver-api/pps.rst
similarity index 89%
rename from Documentation/pps/pps.txt
rename to Documentation/driver-api/pps.rst
index 99f5d8c4c652..1456d2c32ebd 100644
--- a/Documentation/pps/pps.txt
+++ b/Documentation/driver-api/pps.rst
@@ -1,8 +1,10 @@
+:orphan:
- PPS - Pulse Per Second
- ----------------------
+======================
+PPS - Pulse Per Second
+======================
-(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com>
+Copyright (C) 2007 Rodolfo Giometti <giometti@enneenne.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
@@ -88,7 +90,7 @@ Coding example
--------------
To register a PPS source into the kernel you should define a struct
-pps_source_info as follows:
+pps_source_info as follows::
static struct pps_source_info pps_ktimer_info = {
.name = "ktimer",
@@ -101,12 +103,12 @@ pps_source_info as follows:
};
and then calling the function pps_register_source() in your
-initialization routine as follows:
+initialization routine as follows::
source = pps_register_source(&pps_ktimer_info,
PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
-The pps_register_source() prototype is:
+The pps_register_source() prototype is::
int pps_register_source(struct pps_source_info *info, int default_params)
@@ -118,7 +120,7 @@ pps_source_info which describe the capabilities of the driver).
Once you have registered a new PPS source into the system you can
signal an assert event (for example in the interrupt handler routine)
-just using:
+just using::
pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
@@ -134,13 +136,13 @@ Please see the file drivers/pps/clients/pps-ktimer.c for example code.
SYSFS support
-------------
-If the SYSFS filesystem is enabled in the kernel it provides a new class:
+If the SYSFS filesystem is enabled in the kernel it provides a new class::
$ ls /sys/class/pps/
pps0/ pps1/ pps2/
Every directory is the ID of a PPS sources defined in the system and
-inside you find several files:
+inside you find several files::
$ ls -F /sys/class/pps/pps0/
assert dev mode path subsystem@
@@ -148,7 +150,7 @@ inside you find several files:
Inside each "assert" and "clear" file you can find the timestamp and a
-sequence number:
+sequence number::
$ cat /sys/class/pps/pps0/assert
1170026870.983207967#8
@@ -175,11 +177,11 @@ and the userland tools available in your distribution's pps-tools package,
http://linuxpps.org , or https://github.com/redlab-i/pps-tools.
Once you have enabled the compilation of pps-ktimer just modprobe it (if
-not statically compiled):
+not statically compiled)::
# modprobe pps-ktimer
-and the run ppstest as follow:
+and the run ppstest as follow::
$ ./ppstest /dev/pps1
trying PPS source "/dev/pps1"
@@ -204,26 +206,27 @@ nor affordable. The cheap way is to load a PPS generator on one of the
computers (master) and PPS clients on others (slaves), and use very simple
cables to deliver signals using parallel ports, for example.
-Parallel port cable pinout:
-pin name master slave
-1 STROBE *------ *
-2 D0 * | *
-3 D1 * | *
-4 D2 * | *
-5 D3 * | *
-6 D4 * | *
-7 D5 * | *
-8 D6 * | *
-9 D7 * | *
-10 ACK * ------*
-11 BUSY * *
-12 PE * *
-13 SEL * *
-14 AUTOFD * *
-15 ERROR * *
-16 INIT * *
-17 SELIN * *
-18-25 GND *-----------*
+Parallel port cable pinout::
+
+ pin name master slave
+ 1 STROBE *------ *
+ 2 D0 * | *
+ 3 D1 * | *
+ 4 D2 * | *
+ 5 D3 * | *
+ 6 D4 * | *
+ 7 D5 * | *
+ 8 D6 * | *
+ 9 D7 * | *
+ 10 ACK * ------*
+ 11 BUSY * *
+ 12 PE * *
+ 13 SEL * *
+ 14 AUTOFD * *
+ 15 ERROR * *
+ 16 INIT * *
+ 17 SELIN * *
+ 18-25 GND *-----------*
Please note that parallel port interrupt occurs only on high->low transition,
so it is used for PPS assert edge. PPS clear edge can be determined only
diff --git a/MAINTAINERS b/MAINTAINERS
index 01d9120bb83b..b982622ea7ee 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12689,7 +12689,7 @@ M: Rodolfo Giometti <giometti@enneenne.com>
W: http://wiki.enneenne.com/index.php/LinuxPPS_support
L: linuxpps@ml.enneenne.com (subscribers-only)
S: Maintained
-F: Documentation/pps/
+F: Documentation/driver-api/pps.rst
F: Documentation/devicetree/bindings/pps/pps-gpio.txt
F: Documentation/ABI/testing/sysfs-pps
F: drivers/pps/
--
2.21.0
^ permalink raw reply related
* [PATCH v3 04/33] docs: cdrom: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:26 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jens Axboe, Borislav Petkov, David S. Miller,
linux-ide, linux-block
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The stuff there is almost already at ReST format. A
conversion for them is trivial: just add a missing titles
and fix some scape codes for them to match ReST syntax.
While here, rename the cdrom-standard.txt, with was converted
from LaTeX to ReST on the previous patch, and add it to the
index file.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...{cdrom-standard.txt => cdrom-standard.rst} | 0
Documentation/cdrom/{ide-cd => ide-cd.rst} | 178 +++++++++---------
Documentation/cdrom/index.rst | 19 ++
...{packet-writing.txt => packet-writing.rst} | 27 ++-
MAINTAINERS | 2 +-
drivers/block/Kconfig | 2 +-
drivers/cdrom/cdrom.c | 2 +-
drivers/ide/ide-cd.c | 2 +-
8 files changed, 131 insertions(+), 101 deletions(-)
rename Documentation/cdrom/{cdrom-standard.txt => cdrom-standard.rst} (100%)
rename Documentation/cdrom/{ide-cd => ide-cd.rst} (84%)
create mode 100644 Documentation/cdrom/index.rst
rename Documentation/cdrom/{packet-writing.txt => packet-writing.rst} (91%)
diff --git a/Documentation/cdrom/cdrom-standard.txt b/Documentation/cdrom/cdrom-standard.rst
similarity index 100%
rename from Documentation/cdrom/cdrom-standard.txt
rename to Documentation/cdrom/cdrom-standard.rst
diff --git a/Documentation/cdrom/ide-cd b/Documentation/cdrom/ide-cd.rst
similarity index 84%
rename from Documentation/cdrom/ide-cd
rename to Documentation/cdrom/ide-cd.rst
index a5f2a7f1ff46..dadc94ef6b6c 100644
--- a/Documentation/cdrom/ide-cd
+++ b/Documentation/cdrom/ide-cd.rst
@@ -1,18 +1,20 @@
IDE-CD driver documentation
-Originally by scott snyder <snyder@fnald0.fnal.gov> (19 May 1996)
-Carrying on the torch is: Erik Andersen <andersee@debian.org>
-New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>
+===========================
+
+:Originally by: scott snyder <snyder@fnald0.fnal.gov> (19 May 1996)
+:Carrying on the torch is: Erik Andersen <andersee@debian.org>
+:New maintainers (19 Oct 1998): Jens Axboe <axboe@image.dk>
1. Introduction
---------------
-The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant
+The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant
CDROM drives which attach to an IDE interface. Note that some CDROM vendors
(including Mitsumi, Sony, Creative, Aztech, and Goldstar) have made
both ATAPI-compliant drives and drives which use a proprietary
interface. If your drive uses one of those proprietary interfaces,
this driver will not work with it (but one of the other CDROM drivers
-probably will). This driver will not work with `ATAPI' drives which
+probably will). This driver will not work with `ATAPI` drives which
attach to the parallel port. In addition, there is at least one drive
(CyCDROM CR520ie) which attaches to the IDE port but is not ATAPI;
this driver will not work with drives like that either (but see the
@@ -31,7 +33,7 @@ This driver provides the following features:
from audio tracks. The program cdda2wav can be used for this.
Note, however, that only some drives actually support this.
- - There is now support for CDROM changers which comply with the
+ - There is now support for CDROM changers which comply with the
ATAPI 2.6 draft standard (such as the NEC CDR-251). This additional
functionality includes a function call to query which slot is the
currently selected slot, a function call to query which slots contain
@@ -49,11 +51,11 @@ This driver provides the following features:
driver.
1. Make sure that the ide and ide-cd drivers are compiled into the
- kernel you're using. When configuring the kernel, in the section
- entitled "Floppy, IDE, and other block devices", say either `Y'
- (which will compile the support directly into the kernel) or `M'
+ kernel you're using. When configuring the kernel, in the section
+ entitled "Floppy, IDE, and other block devices", say either `Y`
+ (which will compile the support directly into the kernel) or `M`
(to compile support as a module which can be loaded and unloaded)
- to the options:
+ to the options::
ATA/ATAPI/MFM/RLL support
Include IDE/ATAPI CDROM support
@@ -72,35 +74,35 @@ This driver provides the following features:
address and an IRQ number, the standard assignments being
0x1f0 and 14 for the primary interface and 0x170 and 15 for the
secondary interface. Each interface can control up to two devices,
- where each device can be a hard drive, a CDROM drive, a floppy drive,
- or a tape drive. The two devices on an interface are called `master'
- and `slave'; this is usually selectable via a jumper on the drive.
+ where each device can be a hard drive, a CDROM drive, a floppy drive,
+ or a tape drive. The two devices on an interface are called `master`
+ and `slave`; this is usually selectable via a jumper on the drive.
Linux names these devices as follows. The master and slave devices
- on the primary IDE interface are called `hda' and `hdb',
+ on the primary IDE interface are called `hda` and `hdb`,
respectively. The drives on the secondary interface are called
- `hdc' and `hdd'. (Interfaces at other locations get other letters
+ `hdc` and `hdd`. (Interfaces at other locations get other letters
in the third position; see Documentation/ide/ide.txt.)
If you want your CDROM drive to be found automatically by the
driver, you should make sure your IDE interface uses either the
primary or secondary addresses mentioned above. In addition, if
the CDROM drive is the only device on the IDE interface, it should
- be jumpered as `master'. (If for some reason you cannot configure
+ be jumpered as `master`. (If for some reason you cannot configure
your system in this manner, you can probably still use the driver.
You may have to pass extra configuration information to the kernel
when you boot, however. See Documentation/ide/ide.txt for more
information.)
4. Boot the system. If the drive is recognized, you should see a
- message which looks like
+ message which looks like::
hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive
If you do not see this, see section 5 below.
5. You may want to create a symbolic link /dev/cdrom pointing to the
- actual device. You can do this with the command
+ actual device. You can do this with the command::
ln -s /dev/hdX /dev/cdrom
@@ -108,14 +110,14 @@ This driver provides the following features:
drive is installed.
6. You should be able to see any error messages from the driver with
- the `dmesg' command.
+ the `dmesg` command.
3. Basic usage
--------------
-An ISO 9660 CDROM can be mounted by putting the disc in the drive and
-typing (as root)
+An ISO 9660 CDROM can be mounted by putting the disc in the drive and
+typing (as root)::
mount -t iso9660 /dev/cdrom /mnt/cdrom
@@ -123,7 +125,7 @@ where it is assumed that /dev/cdrom is a link pointing to the actual
device (as described in step 5 of the last section) and /mnt/cdrom is
an empty directory. You should now be able to see the contents of the
CDROM under the /mnt/cdrom directory. If you want to eject the CDROM,
-you must first dismount it with a command like
+you must first dismount it with a command like::
umount /mnt/cdrom
@@ -148,7 +150,7 @@ such as cdda2wav. The only types of drive which I've heard support
this are Sony and Toshiba drives. You will get errors if you try to
use this function on a drive which does not support it.
-For supported changers, you can use the `cdchange' program (appended to
+For supported changers, you can use the `cdchange` program (appended to
the end of this file) to switch between changer slots. Note that the
drive should be unmounted before attempting this. The program takes
two arguments: the CDROM device, and the slot number to which you wish
@@ -165,7 +167,7 @@ Documentation/ide/ide.txt for current information about the underlying
IDE support code. Some of these items apply only to earlier versions
of the driver, but are mentioned here for completeness.
-In most cases, you should probably check with `dmesg' for any errors
+In most cases, you should probably check with `dmesg` for any errors
from the driver.
a. Drive is not detected during booting.
@@ -184,9 +186,9 @@ a. Drive is not detected during booting.
- If the autoprobing is not finding your drive, you can tell the
driver to assume that one exists by using a lilo option of the
- form `hdX=cdrom', where X is the drive letter corresponding to
- where your drive is installed. Note that if you do this and you
- see a boot message like
+ form `hdX=cdrom`, where X is the drive letter corresponding to
+ where your drive is installed. Note that if you do this and you
+ see a boot message like::
hdX: ATAPI cdrom (?)
@@ -220,7 +222,7 @@ b. Timeout/IRQ errors.
probably not making it to the host.
- IRQ problems may also be indicated by the message
- `IRQ probe failed (<n>)' while booting. If <n> is zero, that
+ `IRQ probe failed (<n>)` while booting. If <n> is zero, that
means that the system did not see an interrupt from the drive when
it was expecting one (on any feasible IRQ). If <n> is negative,
that means the system saw interrupts on multiple IRQ lines, when
@@ -240,27 +242,27 @@ b. Timeout/IRQ errors.
there are hardware problems with the interrupt setup; they
apparently don't use interrupts.
- - If you own a Pioneer DR-A24X, you _will_ get nasty error messages
+ - If you own a Pioneer DR-A24X, you _will_ get nasty error messages
on boot such as "irq timeout: status=0x50 { DriveReady SeekComplete }"
The Pioneer DR-A24X CDROM drives are fairly popular these days.
Unfortunately, these drives seem to become very confused when we perform
the standard Linux ATA disk drive probe. If you own one of these drives,
- you can bypass the ATA probing which confuses these CDROM drives, by
- adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running
- lilo (again where X is the drive letter corresponding to where your drive
+ you can bypass the ATA probing which confuses these CDROM drives, by
+ adding `append="hdX=noprobe hdX=cdrom"` to your lilo.conf file and running
+ lilo (again where X is the drive letter corresponding to where your drive
is installed.)
-
+
c. System hangups.
- If the system locks up when you try to access the CDROM, the most
likely cause is that you have a buggy IDE adapter which doesn't
properly handle simultaneous transactions on multiple interfaces.
The most notorious of these is the CMD640B chip. This problem can
- be worked around by specifying the `serialize' option when
+ be worked around by specifying the `serialize` option when
booting. Recent kernels should be able to detect the need for
this automatically in most cases, but the detection is not
foolproof. See Documentation/ide/ide.txt for more information
- about the `serialize' option and the CMD640B.
+ about the `serialize` option and the CMD640B.
- Note that many MS-DOS CDROM drivers will work with such buggy
hardware, apparently because they never attempt to overlap CDROM
@@ -269,14 +271,14 @@ c. System hangups.
d. Can't mount a CDROM.
- - If you get errors from mount, it may help to check `dmesg' to see
+ - If you get errors from mount, it may help to check `dmesg` to see
if there are any more specific errors from the driver or from the
filesystem.
- Make sure there's a CDROM loaded in the drive, and that's it's an
ISO 9660 disc. You can't mount an audio CD.
- - With the CDROM in the drive and unmounted, try something like
+ - With the CDROM in the drive and unmounted, try something like::
cat /dev/cdrom | od | more
@@ -284,9 +286,9 @@ d. Can't mount a CDROM.
OK, and the problem is at the filesystem level (i.e., the CDROM is
not ISO 9660 or has errors in the filesystem structure).
- - If you see `not a block device' errors, check that the definitions
+ - If you see `not a block device` errors, check that the definitions
of the device special files are correct. They should be as
- follows:
+ follows::
brw-rw---- 1 root disk 3, 0 Nov 11 18:48 /dev/hda
brw-rw---- 1 root disk 3, 64 Nov 11 18:48 /dev/hdb
@@ -301,7 +303,7 @@ d. Can't mount a CDROM.
If you have a /dev/cdrom symbolic link, check that it is pointing
to the correct device file.
- If you hear people talking of the devices `hd1a' and `hd1b', these
+ If you hear people talking of the devices `hd1a` and `hd1b`, these
were old names for what are now called hdc and hdd. Those names
should be considered obsolete.
@@ -311,8 +313,8 @@ d. Can't mount a CDROM.
always give meaningful error messages.
-e. Directory listings are unpredictably truncated, and `dmesg' shows
- `buffer botch' error messages from the driver.
+e. Directory listings are unpredictably truncated, and `dmesg` shows
+ `buffer botch` error messages from the driver.
- There was a bug in the version of the driver in 1.2.x kernels
which could cause this. It was fixed in 1.3.0. If you can't
@@ -335,34 +337,36 @@ f. Data corruption.
5. cdchange.c
-------------
-/*
- * cdchange.c [-v] <device> [<slot>]
- *
- * This loads a CDROM from a specified slot in a changer, and displays
- * information about the changer status. The drive should be unmounted before
- * using this program.
- *
- * Changer information is displayed if either the -v flag is specified
- * or no slot was specified.
- *
- * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>.
- * Changer status information, and rewrite for the new Uniform CDROM driver
- * interface by Erik Andersen <andersee@debian.org>.
- */
+::
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <string.h>
-#include <unistd.h>
-#include <fcntl.h>
-#include <sys/ioctl.h>
-#include <linux/cdrom.h>
+ /*
+ * cdchange.c [-v] <device> [<slot>]
+ *
+ * This loads a CDROM from a specified slot in a changer, and displays
+ * information about the changer status. The drive should be unmounted before
+ * using this program.
+ *
+ * Changer information is displayed if either the -v flag is specified
+ * or no slot was specified.
+ *
+ * Based on code originally from Gerhard Zuber <zuber@berlin.snafu.de>.
+ * Changer status information, and rewrite for the new Uniform CDROM driver
+ * interface by Erik Andersen <andersee@debian.org>.
+ */
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <errno.h>
+ #include <string.h>
+ #include <unistd.h>
+ #include <fcntl.h>
+ #include <sys/ioctl.h>
+ #include <linux/cdrom.h>
-int
-main (int argc, char **argv)
-{
+
+ int
+ main (int argc, char **argv)
+ {
char *program;
char *device;
int fd; /* file descriptor for CD-ROM device */
@@ -382,30 +386,30 @@ main (int argc, char **argv)
fprintf (stderr, " Slots are numbered 1 -- n.\n");
exit (1);
}
-
+
if (strcmp (argv[0], "-v") == 0) {
verbose = 1;
++argv;
--argc;
}
-
+
device = argv[0];
-
+
if (argc == 2)
slot = atoi (argv[1]) - 1;
- /* open device */
+ /* open device */
fd = open(device, O_RDONLY | O_NONBLOCK);
if (fd < 0) {
- fprintf (stderr, "%s: open failed for `%s': %s\n",
+ fprintf (stderr, "%s: open failed for `%s`: %s\n",
program, device, strerror (errno));
exit (1);
}
- /* Check CD player status */
+ /* Check CD player status */
total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS);
if (total_slots_available <= 1 ) {
- fprintf (stderr, "%s: Device `%s' is not an ATAPI "
+ fprintf (stderr, "%s: Device `%s` is not an ATAPI "
"compliant CD changer.\n", program, device);
exit (1);
}
@@ -418,7 +422,7 @@ main (int argc, char **argv)
exit (1);
}
- /* load */
+ /* load */
slot=ioctl (fd, CDROM_SELECT_DISC, slot);
if (slot<0) {
fflush(stdout);
@@ -462,14 +466,14 @@ main (int argc, char **argv)
for (x_slot=0; x_slot<total_slots_available; x_slot++) {
printf ("Slot %2d: ", x_slot+1);
- status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
- if (status<0) {
- perror(" CDROM_DRIVE_STATUS");
- } else switch(status) {
+ status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
+ if (status<0) {
+ perror(" CDROM_DRIVE_STATUS");
+ } else switch(status) {
case CDS_DISC_OK:
printf ("Disc present.");
break;
- case CDS_NO_DISC:
+ case CDS_NO_DISC:
printf ("Empty slot.");
break;
case CDS_TRAY_OPEN:
@@ -507,11 +511,11 @@ main (int argc, char **argv)
break;
}
}
- status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
- if (status<0) {
+ status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
+ if (status<0) {
perror(" CDROM_MEDIA_CHANGED");
- }
- switch (status) {
+ }
+ switch (status) {
case 1:
printf ("Changed.\n");
break;
@@ -525,10 +529,10 @@ main (int argc, char **argv)
/* close device */
status = close (fd);
if (status != 0) {
- fprintf (stderr, "%s: close failed for `%s': %s\n",
+ fprintf (stderr, "%s: close failed for `%s`: %s\n",
program, device, strerror (errno));
exit (1);
}
-
+
exit (0);
-}
+ }
diff --git a/Documentation/cdrom/index.rst b/Documentation/cdrom/index.rst
new file mode 100644
index 000000000000..efbd5d111825
--- /dev/null
+++ b/Documentation/cdrom/index.rst
@@ -0,0 +1,19 @@
+:orphan:
+
+=====
+cdrom
+=====
+
+.. toctree::
+ :maxdepth: 1
+
+ cdrom-standard
+ ide-cd
+ packet-writing
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.rst
similarity index 91%
rename from Documentation/cdrom/packet-writing.txt
rename to Documentation/cdrom/packet-writing.rst
index 2834170d821e..c5c957195a5a 100644
--- a/Documentation/cdrom/packet-writing.txt
+++ b/Documentation/cdrom/packet-writing.rst
@@ -1,3 +1,7 @@
+==============
+Packet writing
+==============
+
Getting started quick
---------------------
@@ -10,13 +14,16 @@ Getting started quick
Download from http://sourceforge.net/projects/linux-udf/
- Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute
- as appropriate):
+ as appropriate)::
+
# cdrwtool -d /dev/hdc -q
-- Setup your writer
+- Setup your writer::
+
# pktsetup dev_name /dev/hdc
-- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy!
+- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy::
+
# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -25,11 +32,11 @@ Packet writing for DVD-RW media
DVD-RW discs can be written to much like CD-RW discs if they are in
the so called "restricted overwrite" mode. To put a disc in restricted
-overwrite mode, run:
+overwrite mode, run::
# dvd+rw-format /dev/hdc
-You can then use the disc the same way you would use a CD-RW disc:
+You can then use the disc the same way you would use a CD-RW disc::
# pktsetup dev_name /dev/hdc
# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -41,7 +48,7 @@ Packet writing for DVD+RW media
According to the DVD+RW specification, a drive supporting DVD+RW discs
shall implement "true random writes with 2KB granularity", which means
that it should be possible to put any filesystem with a block size >=
-2KB on such a disc. For example, it should be possible to do:
+2KB on such a disc. For example, it should be possible to do::
# dvd+rw-format /dev/hdc (only needed if the disc has never
been formatted)
@@ -54,7 +61,7 @@ follow the specification, but suffer bad performance problems if the
writes are not 32KB aligned.
Both problems can be solved by using the pktcdvd driver, which always
-generates aligned writes.
+generates aligned writes::
# dvd+rw-format /dev/hdc
# pktsetup dev_name /dev/hdc
@@ -83,7 +90,7 @@ Notes
- Since the pktcdvd driver makes the disc appear as a regular block
device with a 2KB block size, you can put any filesystem you like on
- the disc. For example, run:
+ the disc. For example, run::
# /sbin/mke2fs /dev/pktcdvd/dev_name
@@ -97,7 +104,7 @@ Since Linux 2.6.20, the pktcdvd module has a sysfs interface
and can be controlled by it. For example the "pktcdvd" tool uses
this interface. (see http://tom.ist-im-web.de/download/pktcdvd )
-"pktcdvd" works similar to "pktsetup", e.g.:
+"pktcdvd" works similar to "pktsetup", e.g.::
# pktcdvd -a dev_name /dev/hdc
# mkudffs /dev/pktcdvd/dev_name
@@ -115,7 +122,7 @@ For a description of the sysfs interface look into the file:
Using the pktcdvd debugfs interface
-----------------------------------
-To read pktcdvd device infos in human readable form, do:
+To read pktcdvd device infos in human readable form, do::
# cat /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/info
diff --git a/MAINTAINERS b/MAINTAINERS
index 10b77121b9bf..fd40fa26f062 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7631,7 +7631,7 @@ IDE/ATAPI DRIVERS
M: Borislav Petkov <bp@alien8.de>
L: linux-ide@vger.kernel.org
S: Maintained
-F: Documentation/cdrom/ide-cd
+F: Documentation/cdrom/ide-cd.rst
F: drivers/ide/ide-cd*
IDEAPAD LAPTOP EXTRAS DRIVER
diff --git a/drivers/block/Kconfig b/drivers/block/Kconfig
index 20bb4bfa4be6..96ec7e0fc1ea 100644
--- a/drivers/block/Kconfig
+++ b/drivers/block/Kconfig
@@ -347,7 +347,7 @@ config CDROM_PKTCDVD
is possible.
DVD-RW disks must be in restricted overwrite mode.
- See the file <file:Documentation/cdrom/packet-writing.txt>
+ See the file <file:Documentation/cdrom/packet-writing.rst>
for further information on the use of this driver.
To compile this driver as a module, choose M here: the
diff --git a/drivers/cdrom/cdrom.c b/drivers/cdrom/cdrom.c
index 5d1e0a4a7d84..ac42ae4651ce 100644
--- a/drivers/cdrom/cdrom.c
+++ b/drivers/cdrom/cdrom.c
@@ -7,7 +7,7 @@
License. See linux/COPYING for more information.
Uniform CD-ROM driver for Linux.
- See Documentation/cdrom/cdrom-standard.txt for usage information.
+ See Documentation/cdrom/cdrom-standard.rst for usage information.
The routines in the file provide a uniform interface between the
software that uses CD-ROMs and the various low-level drivers that
diff --git a/drivers/ide/ide-cd.c b/drivers/ide/ide-cd.c
index 3b15adc6ce98..9d117936bee1 100644
--- a/drivers/ide/ide-cd.c
+++ b/drivers/ide/ide-cd.c
@@ -9,7 +9,7 @@
* May be copied or modified under the terms of the GNU General Public
* License. See linux/COPYING for more information.
*
- * See Documentation/cdrom/ide-cd for usage information.
+ * See Documentation/cdrom/ide-cd.rst for usage information.
*
* Suggestions are welcome. Patches that work are more welcome though. ;-)
*
--
2.21.0
^ permalink raw reply related
* [PATCH v3 00/33] Convert files to ReST - part 1
From: Mauro Carvalho Chehab @ 2019-06-09 2:26 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Palmer Dabbelt, Albert Ou, Alexei Starovoitov,
Daniel Borkmann, Martin KaFai Lau, Song Liu, Yonghong Song,
Greentime Hu, Vincent Chen, linux-riscv, netdev, bpf
This is the first part of a series I wrote sometime ago where I manually
convert lots of files to be properly parsed by Sphinx as ReST files.
As it touches on lot of stuff, this series is based on today's docs-next
+ linux-next, at tag next-20190607.
I have right now about 85 patches with this undergoing work. That's
because I opted to do ~1 patch per converted directory.
That sounds too much to be send on a single round. So, I'm opting to split
it on 3 parts. Those patches should probably be good to be merged
either by subsystem maintainers or via the docs tree.
I opted to mark new files not included yet to the main index.rst (directly or
indirectly ) with the :orphan: tag, in order to avoid adding warnings to the
build system. This should be removed after we find a "home" for all
the converted files within the new document tree arrangement.
Both this series and the next parts are on my devel git tree,
at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v4
The final output in html (after all patches I currently have, including
the upcoming series) can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
Mauro Carvalho Chehab (33):
docs: aoe: convert docs to ReST and rename to *.rst
docs: arm64: convert docs to ReST and rename to .rst
docs: cdrom-standard.tex: convert from LaTeX to ReST
docs: cdrom: convert docs to ReST and rename to *.rst
docs: cgroup-v1: convert docs to ReST and rename to *.rst
docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
docs: cpu-freq: convert docs to ReST and rename to *.rst
docs: convert docs to ReST and rename to *.rst
docs: fault-injection: convert docs to ReST and rename to *.rst
docs: fb: convert docs to ReST and rename to *.rst
docs: fpga: convert docs to ReST and rename to *.rst
docs: ide: convert docs to ReST and rename to *.rst
docs: infiniband: convert docs to ReST and rename to *.rst
docs: kbuild: convert docs to ReST and rename to *.rst
docs: kdump: convert docs to ReST and rename to *.rst
docs: locking: convert docs to ReST and rename to *.rst
docs: mic: convert docs to ReST and rename to *.rst
docs: netlabel: convert docs to ReST and rename to *.rst
docs: pcmcia: convert docs to ReST and rename to *.rst
docs: convert docs to ReST and rename to *.rst
docs: powerpc: convert docs to ReST and rename to *.rst
docs: pps.txt: convert to ReST and rename to pps.rst
docs: ptp.txt: convert to ReST and move to driver-api
docs: riscv: convert docs to ReST and rename to *.rst
docs: Debugging390.txt: convert table to ascii artwork
docs: s390: convert docs to ReST and rename to *.rst
s390: include/asm/debug.h add kerneldoc markups
docs: target: convert docs to ReST and rename to *.rst
docs: timers: convert docs to ReST and rename to *.rst
docs: watchdog: convert docs to ReST and rename to *.rst
docs: xilinx: convert eemi.txt to eemi.rst
docs: scheduler: convert docs to ReST and rename to *.rst
docs: EDID/HOWTO.txt: convert it and rename to howto.rst
.../ABI/testing/sysfs-class-powercap | 2 +-
Documentation/ABI/testing/sysfs-kernel-uids | 2 +-
Documentation/EDID/{HOWTO.txt => howto.rst} | 31 +-
Documentation/PCI/pci-error-recovery.rst | 23 +-
Documentation/admin-guide/README.rst | 2 +-
Documentation/admin-guide/bug-hunting.rst | 2 +-
Documentation/admin-guide/hw-vuln/l1tf.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 28 +-
.../admin-guide/mm/numa_memory_policy.rst | 2 +-
Documentation/aoe/{aoe.txt => aoe.rst} | 63 +-
Documentation/aoe/examples.rst | 23 +
Documentation/aoe/index.rst | 19 +
Documentation/aoe/{todo.txt => todo.rst} | 3 +
Documentation/aoe/udev.txt | 2 +-
...object_usage.txt => acpi_object_usage.rst} | 288 +-
.../arm64/{arm-acpi.txt => arm-acpi.rst} | 155 +-
.../arm64/{booting.txt => booting.rst} | 91 +-
...egisters.txt => cpu-feature-registers.rst} | 204 +-
.../arm64/{elf_hwcaps.txt => elf_hwcaps.rst} | 56 +-
.../{hugetlbpage.txt => hugetlbpage.rst} | 7 +-
Documentation/arm64/index.rst | 28 +
...structions.txt => legacy_instructions.rst} | 43 +-
.../arm64/{memory.txt => memory.rst} | 91 +-
...ication.txt => pointer-authentication.rst} | 2 +
...{silicon-errata.txt => silicon-errata.rst} | 65 +-
Documentation/arm64/{sve.txt => sve.rst} | 12 +-
...agged-pointers.txt => tagged-pointers.rst} | 6 +-
Documentation/block/bfq-iosched.txt | 2 +-
Documentation/cdrom/Makefile | 21 -
...{cdrom-standard.tex => cdrom-standard.rst} | 1491 +++++-----
Documentation/cdrom/{ide-cd => ide-cd.rst} | 196 +-
Documentation/cdrom/index.rst | 19 +
...{packet-writing.txt => packet-writing.rst} | 27 +-
...io-controller.txt => blkio-controller.rst} | 103 +-
.../cgroup-v1/{cgroups.txt => cgroups.rst} | 184 +-
.../cgroup-v1/{cpuacct.txt => cpuacct.rst} | 15 +-
.../cgroup-v1/{cpusets.txt => cpusets.rst} | 205 +-
.../cgroup-v1/{devices.txt => devices.rst} | 40 +-
...er-subsystem.txt => freezer-subsystem.rst} | 14 +-
.../cgroup-v1/{hugetlb.txt => hugetlb.rst} | 39 +-
Documentation/cgroup-v1/index.rst | 30 +
.../{memcg_test.txt => memcg_test.rst} | 263 +-
.../cgroup-v1/{memory.txt => memory.rst} | 449 +--
.../cgroup-v1/{net_cls.txt => net_cls.rst} | 37 +-
.../cgroup-v1/{net_prio.txt => net_prio.rst} | 24 +-
.../cgroup-v1/{pids.txt => pids.rst} | 78 +-
.../cgroup-v1/{rdma.txt => rdma.rst} | 66 +-
.../{amd-powernow.txt => amd-powernow.rst} | 11 +-
Documentation/cpu-freq/{core.txt => core.rst} | 68 +-
.../{cpu-drivers.txt => cpu-drivers.rst} | 217 +-
...pufreq-nforce2.txt => cpufreq-nforce2.rst} | 12 +-
.../{cpufreq-stats.txt => cpufreq-stats.rst} | 141 +-
.../cpu-freq/{index.txt => index.rst} | 44 +-
.../{pcc-cpufreq.txt => pcc-cpufreq.rst} | 102 +-
...{cache-policies.txt => cache-policies.rst} | 24 +-
.../device-mapper/{cache.txt => cache.rst} | 206 +-
.../device-mapper/{delay.txt => delay.rst} | 29 +-
.../{dm-crypt.txt => dm-crypt.rst} | 57 +-
.../{dm-flakey.txt => dm-flakey.rst} | 45 +-
.../{dm-init.txt => dm-init.rst} | 75 +-
.../{dm-integrity.txt => dm-integrity.rst} | 62 +-
.../device-mapper/{dm-io.txt => dm-io.rst} | 14 +-
.../device-mapper/{dm-log.txt => dm-log.rst} | 5 +-
...m-queue-length.txt => dm-queue-length.rst} | 25 +-
.../{dm-raid.txt => dm-raid.rst} | 225 +-
...m-service-time.txt => dm-service-time.rst} | 68 +-
.../{dm-uevent.txt => dm-uevent.rst} | 143 +-
.../{dm-zoned.txt => dm-zoned.rst} | 10 +-
.../device-mapper/{era.txt => era.rst} | 36 +-
Documentation/device-mapper/index.rst | 44 +
.../device-mapper/{kcopyd.txt => kcopyd.rst} | 10 +-
.../device-mapper/{linear.txt => linear.rst} | 100 +-
.../{log-writes.txt => log-writes.rst} | 91 +-
...ersistent-data.txt => persistent-data.rst} | 4 +
.../{snapshot.txt => snapshot.rst} | 116 +-
.../{statistics.txt => statistics.rst} | 62 +-
.../{striped.txt => striped.rst} | 68 +-
.../device-mapper/{switch.txt => switch.rst} | 47 +-
...provisioning.txt => thin-provisioning.rst} | 68 +-
.../{unstriped.txt => unstriped.rst} | 111 +-
.../device-mapper/{verity.txt => verity.rst} | 20 +-
.../{writecache.txt => writecache.rst} | 13 +-
.../device-mapper/{zero.txt => zero.rst} | 14 +-
Documentation/driver-api/pm/devices.rst | 6 +-
.../{pps/pps.txt => driver-api/pps.rst} | 67 +-
.../{ptp/ptp.txt => driver-api/ptp.rst} | 26 +-
Documentation/driver-api/s390-drivers.rst | 4 +-
.../driver-api/usb/power-management.rst | 2 +-
...ault-injection.txt => fault-injection.rst} | 265 +-
Documentation/fault-injection/index.rst | 20 +
...r-inject.txt => notifier-error-inject.rst} | 18 +-
...injection.txt => nvme-fault-injection.rst} | 174 +-
...rovoke-crashes.txt => provoke-crashes.rst} | 40 +-
Documentation/fb/{api.txt => api.rst} | 29 +-
Documentation/fb/{arkfb.txt => arkfb.rst} | 8 +-
.../fb/{aty128fb.txt => aty128fb.rst} | 35 +-
.../fb/{cirrusfb.txt => cirrusfb.rst} | 47 +-
.../fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} | 57 +-
.../fb/{deferred_io.txt => deferred_io.rst} | 28 +-
Documentation/fb/{efifb.txt => efifb.rst} | 18 +-
.../fb/{ep93xx-fb.txt => ep93xx-fb.rst} | 27 +-
Documentation/fb/{fbcon.txt => fbcon.rst} | 177 +-
.../fb/{framebuffer.txt => framebuffer.rst} | 79 +-
Documentation/fb/{gxfb.txt => gxfb.rst} | 24 +-
Documentation/fb/index.rst | 50 +
.../fb/{intel810.txt => intel810.rst} | 79 +-
Documentation/fb/{intelfb.txt => intelfb.rst} | 62 +-
.../fb/{internals.txt => internals.rst} | 24 +-
Documentation/fb/{lxfb.txt => lxfb.rst} | 25 +-
.../fb/{matroxfb.txt => matroxfb.rst} | 528 ++--
.../fb/{metronomefb.txt => metronomefb.rst} | 8 +-
Documentation/fb/{modedb.txt => modedb.rst} | 44 +-
Documentation/fb/{pvr2fb.txt => pvr2fb.rst} | 55 +-
Documentation/fb/{pxafb.txt => pxafb.rst} | 81 +-
Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +-
.../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +-
.../fb/{sh7760fb.txt => sh7760fb.rst} | 153 +-
Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +-
Documentation/fb/{sm501.txt => sm501.rst} | 7 +-
Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +-
Documentation/fb/{sstfb.txt => sstfb.rst} | 231 +-
Documentation/fb/{tgafb.txt => tgafb.rst} | 30 +-
.../fb/{tridentfb.txt => tridentfb.rst} | 36 +-
Documentation/fb/{udlfb.txt => udlfb.rst} | 55 +-
Documentation/fb/{uvesafb.txt => uvesafb.rst} | 128 +-
Documentation/fb/{vesafb.txt => vesafb.rst} | 121 +-
Documentation/fb/{viafb.txt => viafb.rst} | 393 +--
.../fb/{vt8623fb.txt => vt8623fb.rst} | 10 +-
Documentation/filesystems/tmpfs.txt | 2 +-
.../filesystems/ubifs-authentication.md | 4 +-
Documentation/fpga/{dfl.txt => dfl.rst} | 58 +-
Documentation/fpga/index.rst | 17 +
Documentation/ide/changelogs.rst | 17 +
.../ide/{ide-tape.txt => ide-tape.rst} | 23 +-
Documentation/ide/{ide.txt => ide.rst} | 147 +-
Documentation/ide/index.rst | 21 +
...arm-plug-howto.txt => warm-plug-howto.rst} | 10 +-
.../{core_locking.txt => core_locking.rst} | 64 +-
Documentation/infiniband/index.rst | 23 +
.../infiniband/{ipoib.txt => ipoib.rst} | 24 +-
.../infiniband/{opa_vnic.txt => opa_vnic.rst} | 108 +-
.../infiniband/{sysfs.txt => sysfs.rst} | 4 +-
.../{tag_matching.txt => tag_matching.rst} | 5 +
.../infiniband/{user_mad.txt => user_mad.rst} | 33 +-
.../{user_verbs.txt => user_verbs.rst} | 12 +-
...eaders_install.txt => headers_install.rst} | 5 +-
Documentation/kbuild/index.rst | 27 +
Documentation/kbuild/issues.rst | 11 +
.../kbuild/{kbuild.txt => kbuild.rst} | 119 +-
...nfig-language.txt => kconfig-language.rst} | 232 +-
...anguage.txt => kconfig-macro-language.rst} | 37 +-
.../kbuild/{kconfig.txt => kconfig.rst} | 136 +-
.../kbuild/{makefiles.txt => makefiles.rst} | 530 ++--
.../kbuild/{modules.txt => modules.rst} | 168 +-
Documentation/kdump/index.rst | 21 +
Documentation/kdump/{kdump.txt => kdump.rst} | 131 +-
.../kdump/{vmcoreinfo.txt => vmcoreinfo.rst} | 59 +-
Documentation/kernel-hacking/hacking.rst | 4 +-
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/kernel-per-CPU-kthreads.txt | 2 +-
Documentation/locking/index.rst | 24 +
...{lockdep-design.txt => lockdep-design.rst} | 51 +-
.../locking/{lockstat.txt => lockstat.rst} | 221 +-
.../{locktorture.txt => locktorture.rst} | 105 +-
.../{mutex-design.txt => mutex-design.rst} | 26 +-
...t-mutex-design.txt => rt-mutex-design.rst} | 139 +-
.../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +-
.../locking/{spinlocks.txt => spinlocks.rst} | 32 +-
...w-mutex-design.txt => ww-mutex-design.rst} | 82 +-
Documentation/mic/index.rst | 18 +
.../{mic_overview.txt => mic_overview.rst} | 6 +-
.../{scif_overview.txt => scif_overview.rst} | 58 +-
.../{cipso_ipv4.txt => cipso_ipv4.rst} | 19 +-
Documentation/netlabel/draft_ietf.rst | 5 +
Documentation/netlabel/index.rst | 21 +
.../{introduction.txt => introduction.rst} | 16 +-
.../{lsm_interface.txt => lsm_interface.rst} | 16 +-
Documentation/networking/timestamping.txt | 2 +-
.../{devicetable.txt => devicetable.rst} | 4 +
...{driver-changes.txt => driver-changes.rst} | 35 +-
.../pcmcia/{driver.txt => driver.rst} | 18 +-
Documentation/pcmcia/index.rst | 20 +
.../pcmcia/{locking.txt => locking.rst} | 39 +-
Documentation/pi-futex.txt | 2 +-
.../power/{apm-acpi.txt => apm-acpi.rst} | 10 +-
...m-debugging.txt => basic-pm-debugging.rst} | 79 +-
...harger-manager.txt => charger-manager.rst} | 101 +-
...rivers-testing.txt => drivers-testing.rst} | 15 +-
.../{energy-model.txt => energy-model.rst} | 101 +-
...ing-of-tasks.txt => freezing-of-tasks.rst} | 91 +-
Documentation/power/index.rst | 46 +
.../power/{interface.txt => interface.rst} | 24 +-
Documentation/power/{opp.txt => opp.rst} | 175 +-
Documentation/power/{pci.txt => pci.rst} | 87 +-
...qos_interface.txt => pm_qos_interface.rst} | 127 +-
...upply_class.txt => power_supply_class.rst} | 269 +-
.../powercap/{powercap.txt => powercap.rst} | 297 +-
.../regulator/{consumer.txt => consumer.rst} | 141 +-
.../regulator/{design.txt => design.rst} | 9 +-
.../regulator/{machine.txt => machine.rst} | 47 +-
.../regulator/{overview.txt => overview.rst} | 57 +-
.../{regulator.txt => regulator.rst} | 18 +-
.../power/{runtime_pm.txt => runtime_pm.rst} | 234 +-
Documentation/power/{s2ram.txt => s2ram.rst} | 20 +-
...hotplug.txt => suspend-and-cpuhotplug.rst} | 42 +-
...errupts.txt => suspend-and-interrupts.rst} | 2 +
...ap-files.txt => swsusp-and-swap-files.rst} | 17 +-
...{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} | 120 +-
.../power/{swsusp.txt => swsusp.rst} | 639 ++--
.../power/{tricks.txt => tricks.rst} | 6 +-
...serland-swsusp.txt => userland-swsusp.rst} | 55 +-
Documentation/power/{video.txt => video.rst} | 156 +-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 119 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +-
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/process/4.Coding.rst | 2 +-
Documentation/process/coding-style.rst | 2 +-
Documentation/process/submit-checklist.rst | 2 +-
Documentation/process/submitting-drivers.rst | 2 +-
Documentation/riscv/index.rst | 17 +
Documentation/riscv/{pmu.txt => pmu.rst} | 98 +-
Documentation/s390/{3270.txt => 3270.rst} | 85 +-
Documentation/s390/{cds.txt => cds.rst} | 354 ++-
.../s390/{CommonIO => common_io.rst} | 49 +-
Documentation/s390/{DASD => dasd.rst} | 33 +-
.../{Debugging390.txt => debugging390.rst} | 2599 ++++++++++-------
.../{driver-model.txt => driver-model.rst} | 179 +-
Documentation/s390/index.rst | 30 +
.../s390/{monreader.txt => monreader.rst} | 85 +-
Documentation/s390/{qeth.txt => qeth.rst} | 36 +-
.../s390/{s390dbf.txt => s390dbf.rst} | 616 +---
Documentation/s390/text_files.rst | 11 +
.../s390/{vfio-ap.txt => vfio-ap.rst} | 487 +--
.../s390/{vfio-ccw.txt => vfio-ccw.rst} | 90 +-
.../s390/{zfcpdump.txt => zfcpdump.rst} | 2 +
.../{completion.txt => completion.rst} | 38 +-
Documentation/scheduler/index.rst | 29 +
.../{sched-arch.txt => sched-arch.rst} | 18 +-
.../{sched-bwc.txt => sched-bwc.rst} | 30 +-
...{sched-deadline.txt => sched-deadline.rst} | 297 +-
...ed-design-CFS.txt => sched-design-CFS.rst} | 17 +-
.../{sched-domains.txt => sched-domains.rst} | 8 +-
.../{sched-energy.txt => sched-energy.rst} | 53 +-
...-nice-design.txt => sched-nice-design.rst} | 6 +-
...{sched-rt-group.txt => sched-rt-group.rst} | 30 +-
.../{sched-stats.txt => sched-stats.rst} | 35 +-
Documentation/scheduler/text_files.rst | 5 +
Documentation/target/index.rst | 19 +
Documentation/target/scripts.rst | 11 +
...cm_mod_builder.txt => tcm_mod_builder.rst} | 200 +-
.../{tcmu-design.txt => tcmu-design.rst} | 268 +-
.../timers/{highres.txt => highres.rst} | 13 +-
Documentation/timers/{hpet.txt => hpet.rst} | 4 +-
.../timers/{hrtimers.txt => hrtimers.rst} | 6 +-
Documentation/timers/index.rst | 22 +
Documentation/timers/{NO_HZ.txt => no_hz.rst} | 40 +-
.../{timekeeping.txt => timekeeping.rst} | 3 +-
.../{timers-howto.txt => timers-howto.rst} | 15 +-
Documentation/trace/coresight-cpu-debug.txt | 2 +-
.../it_IT/kernel-hacking/hacking.rst | 4 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
.../translations/it_IT/process/4.Coding.rst | 2 +-
.../it_IT/process/coding-style.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
.../translations/zh_CN/arm64/booting.txt | 4 +-
.../zh_CN/arm64/legacy_instructions.txt | 4 +-
.../translations/zh_CN/arm64/memory.txt | 4 +-
.../zh_CN/arm64/silicon-errata.txt | 4 +-
.../zh_CN/arm64/tagged-pointers.txt | 4 +-
.../translations/zh_CN/oops-tracing.txt | 2 +-
.../translations/zh_CN/process/4.Coding.rst | 2 +-
.../zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
.../zh_CN/process/submitting-drivers.rst | 2 +-
Documentation/virtual/kvm/api.txt | 2 +-
Documentation/vm/numa.rst | 6 +-
Documentation/vm/page_migration.rst | 2 +-
Documentation/vm/unevictable-lru.rst | 2 +-
....txt => convert_drivers_to_kernel_api.rst} | 109 +-
.../watchdog/{hpwdt.txt => hpwdt.rst} | 27 +-
Documentation/watchdog/index.rst | 25 +
.../watchdog/{mlx-wdt.txt => mlx-wdt.rst} | 24 +-
.../{pcwd-watchdog.txt => pcwd-watchdog.rst} | 13 +-
.../{watchdog-api.txt => watchdog-api.rst} | 76 +-
...kernel-api.txt => watchdog-kernel-api.rst} | 91 +-
...parameters.txt => watchdog-parameters.rst} | 672 +++--
.../{watchdog-pm.txt => watchdog-pm.rst} | 3 +
Documentation/watchdog/{wdt.txt => wdt.rst} | 31 +-
.../x86/x86_64/fake-numa-for-cpusets.rst | 4 +-
Documentation/xilinx/{eemi.txt => eemi.rst} | 8 +-
Documentation/xilinx/index.rst | 17 +
Kconfig | 2 +-
MAINTAINERS | 38 +-
arch/arc/plat-eznps/Kconfig | 2 +-
arch/arm/Kconfig | 2 +-
arch/arm64/Kconfig | 2 +-
arch/arm64/include/asm/efi.h | 2 +-
arch/arm64/include/asm/image.h | 2 +-
arch/arm64/include/uapi/asm/sigcontext.h | 2 +-
arch/arm64/kernel/kexec_image.c | 2 +-
arch/c6x/Kconfig | 2 +-
arch/m68k/q40/README | 2 +-
arch/microblaze/Kconfig.debug | 2 +-
arch/microblaze/Kconfig.platform | 2 +-
arch/nds32/Kconfig | 2 +-
arch/openrisc/Kconfig | 2 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
arch/powerpc/sysdev/Kconfig | 2 +-
arch/riscv/Kconfig | 2 +-
arch/s390/Kconfig | 4 +-
arch/s390/include/asm/debug.h | 235 +-
arch/sh/Kconfig | 2 +-
arch/x86/Kconfig | 6 +-
block/Kconfig | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/block/Kconfig | 2 +-
drivers/cdrom/cdrom.c | 2 +-
drivers/cpufreq/Kconfig.x86 | 2 +-
drivers/firmware/Kconfig | 2 +-
drivers/gpu/drm/Kconfig | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
drivers/gpu/drm/i915/i915_drv.h | 2 +-
drivers/ide/Kconfig | 20 +-
drivers/ide/ide-cd.c | 2 +-
drivers/infiniband/core/user_mad.c | 2 +-
drivers/infiniband/ulp/ipoib/Kconfig | 2 +-
drivers/md/Kconfig | 2 +-
drivers/md/dm-init.c | 2 +-
drivers/md/dm-raid.c | 2 +-
drivers/media/usb/dvb-usb-v2/anysee.c | 2 +-
drivers/misc/lkdtm/core.c | 2 +-
drivers/mtd/devices/Kconfig | 2 +-
drivers/net/ethernet/smsc/Kconfig | 6 +-
drivers/net/wireless/intel/iwlegacy/Kconfig | 4 +-
drivers/net/wireless/intel/iwlwifi/Kconfig | 2 +-
drivers/opp/Kconfig | 2 +-
drivers/parport/Kconfig | 2 +-
drivers/pcmcia/ds.c | 2 +-
drivers/power/supply/power_supply_core.c | 2 +-
drivers/regulator/core.c | 2 +-
drivers/s390/char/zcore.c | 2 +-
drivers/scsi/Kconfig | 4 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/staging/sm750fb/Kconfig | 2 +-
drivers/tty/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
drivers/usb/misc/Kconfig | 4 +-
drivers/video/fbdev/Kconfig | 38 +-
drivers/video/fbdev/matrox/matroxfb_base.c | 2 +-
drivers/video/fbdev/pxafb.c | 2 +-
drivers/video/fbdev/sh7760fb.c | 2 +-
drivers/watchdog/Kconfig | 6 +-
drivers/watchdog/smsc37b787_wdt.c | 2 +-
include/linux/cgroup-defs.h | 2 +-
include/linux/fault-inject.h | 2 +-
include/linux/interrupt.h | 2 +-
include/linux/iopoll.h | 4 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/pci.h | 2 +-
include/linux/pm.h | 2 +-
include/linux/regmap.h | 4 +-
include/linux/rwsem.h | 2 +-
include/pcmcia/ds.h | 2 +-
include/pcmcia/ss.h | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
include/uapi/linux/bpf.h | 2 +-
init/Kconfig | 8 +-
kernel/cgroup/cpuset.c | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
kernel/power/Kconfig | 6 +-
kernel/sched/deadline.c | 2 +-
lib/Kconfig.debug | 6 +-
net/bridge/netfilter/Kconfig | 2 +-
net/ipv4/netfilter/Kconfig | 2 +-
net/ipv6/netfilter/Kconfig | 2 +-
net/netfilter/Kconfig | 16 +-
net/tipc/Kconfig | 2 +-
net/wireless/Kconfig | 2 +-
scripts/Kbuild.include | 4 +-
scripts/Makefile.host | 2 +-
scripts/checkpatch.pl | 8 +-
scripts/documentation-file-ref-check | 2 +-
scripts/kconfig/symbol.c | 2 +-
.../tests/err_recursive_dep/expected_stderr | 14 +-
security/device_cgroup.c | 2 +-
sound/oss/dmasound/Kconfig | 6 +-
sound/soc/sof/ops.h | 2 +-
tools/include/uapi/linux/bpf.h | 2 +-
tools/testing/fault-injection/failcmd.sh | 2 +-
407 files changed, 14319 insertions(+), 10552 deletions(-)
rename Documentation/EDID/{HOWTO.txt => howto.rst} (83%)
rename Documentation/aoe/{aoe.txt => aoe.rst} (79%)
create mode 100644 Documentation/aoe/examples.rst
create mode 100644 Documentation/aoe/index.rst
rename Documentation/aoe/{todo.txt => todo.rst} (98%)
rename Documentation/arm64/{acpi_object_usage.txt => acpi_object_usage.rst} (84%)
rename Documentation/arm64/{arm-acpi.txt => arm-acpi.rst} (86%)
rename Documentation/arm64/{booting.txt => booting.rst} (86%)
rename Documentation/arm64/{cpu-feature-registers.txt => cpu-feature-registers.rst} (65%)
rename Documentation/arm64/{elf_hwcaps.txt => elf_hwcaps.rst} (92%)
rename Documentation/arm64/{hugetlbpage.txt => hugetlbpage.rst} (86%)
create mode 100644 Documentation/arm64/index.rst
rename Documentation/arm64/{legacy_instructions.txt => legacy_instructions.rst} (73%)
rename Documentation/arm64/{memory.txt => memory.rst} (36%)
rename Documentation/arm64/{pointer-authentication.txt => pointer-authentication.rst} (99%)
rename Documentation/arm64/{silicon-errata.txt => silicon-errata.rst} (55%)
rename Documentation/arm64/{sve.txt => sve.rst} (98%)
rename Documentation/arm64/{tagged-pointers.txt => tagged-pointers.rst} (94%)
delete mode 100644 Documentation/cdrom/Makefile
rename Documentation/cdrom/{cdrom-standard.tex => cdrom-standard.rst} (26%)
rename Documentation/cdrom/{ide-cd => ide-cd.rst} (82%)
create mode 100644 Documentation/cdrom/index.rst
rename Documentation/cdrom/{packet-writing.txt => packet-writing.rst} (91%)
rename Documentation/cgroup-v1/{blkio-controller.txt => blkio-controller.rst} (89%)
rename Documentation/cgroup-v1/{cgroups.txt => cgroups.rst} (88%)
rename Documentation/cgroup-v1/{cpuacct.txt => cpuacct.rst} (90%)
rename Documentation/cgroup-v1/{cpusets.txt => cpusets.rst} (90%)
rename Documentation/cgroup-v1/{devices.txt => devices.rst} (88%)
rename Documentation/cgroup-v1/{freezer-subsystem.txt => freezer-subsystem.rst} (95%)
rename Documentation/cgroup-v1/{hugetlb.txt => hugetlb.rst} (70%)
create mode 100644 Documentation/cgroup-v1/index.rst
rename Documentation/cgroup-v1/{memcg_test.txt => memcg_test.rst} (62%)
rename Documentation/cgroup-v1/{memory.txt => memory.rst} (71%)
rename Documentation/cgroup-v1/{net_cls.txt => net_cls.rst} (50%)
rename Documentation/cgroup-v1/{net_prio.txt => net_prio.rst} (71%)
rename Documentation/cgroup-v1/{pids.txt => pids.rst} (62%)
rename Documentation/cgroup-v1/{rdma.txt => rdma.rst} (79%)
rename Documentation/cpu-freq/{amd-powernow.txt => amd-powernow.rst} (91%)
rename Documentation/cpu-freq/{core.txt => core.rst} (66%)
rename Documentation/cpu-freq/{cpu-drivers.txt => cpu-drivers.rst} (57%)
rename Documentation/cpu-freq/{cpufreq-nforce2.txt => cpufreq-nforce2.rst} (65%)
rename Documentation/cpu-freq/{cpufreq-stats.txt => cpufreq-stats.rst} (31%)
rename Documentation/cpu-freq/{index.txt => index.rst} (37%)
rename Documentation/cpu-freq/{pcc-cpufreq.txt => pcc-cpufreq.rst} (80%)
rename Documentation/device-mapper/{cache-policies.txt => cache-policies.rst} (94%)
rename Documentation/device-mapper/{cache.txt => cache.rst} (61%)
rename Documentation/device-mapper/{delay.txt => delay.rst} (53%)
rename Documentation/device-mapper/{dm-crypt.txt => dm-crypt.rst} (87%)
rename Documentation/device-mapper/{dm-flakey.txt => dm-flakey.rst} (60%)
rename Documentation/device-mapper/{dm-init.txt => dm-init.rst} (69%)
rename Documentation/device-mapper/{dm-integrity.txt => dm-integrity.rst} (90%)
rename Documentation/device-mapper/{dm-io.txt => dm-io.rst} (92%)
rename Documentation/device-mapper/{dm-log.txt => dm-log.rst} (90%)
rename Documentation/device-mapper/{dm-queue-length.txt => dm-queue-length.rst} (76%)
rename Documentation/device-mapper/{dm-raid.txt => dm-raid.rst} (71%)
rename Documentation/device-mapper/{dm-service-time.txt => dm-service-time.rst} (60%)
rename Documentation/device-mapper/{dm-uevent.txt => dm-uevent.rst} (31%)
rename Documentation/device-mapper/{dm-zoned.txt => dm-zoned.rst} (97%)
rename Documentation/device-mapper/{era.txt => era.rst} (70%)
create mode 100644 Documentation/device-mapper/index.rst
rename Documentation/device-mapper/{kcopyd.txt => kcopyd.rst} (93%)
rename Documentation/device-mapper/{linear.txt => linear.rst} (18%)
rename Documentation/device-mapper/{log-writes.txt => log-writes.rst} (61%)
rename Documentation/device-mapper/{persistent-data.txt => persistent-data.rst} (98%)
rename Documentation/device-mapper/{snapshot.txt => snapshot.rst} (62%)
rename Documentation/device-mapper/{statistics.txt => statistics.rst} (87%)
rename Documentation/device-mapper/{striped.txt => striped.rst} (32%)
rename Documentation/device-mapper/{switch.txt => switch.rst} (84%)
rename Documentation/device-mapper/{thin-provisioning.txt => thin-provisioning.rst} (92%)
rename Documentation/device-mapper/{unstriped.txt => unstriped.rst} (60%)
rename Documentation/device-mapper/{verity.txt => verity.rst} (98%)
rename Documentation/device-mapper/{writecache.txt => writecache.rst} (96%)
rename Documentation/device-mapper/{zero.txt => zero.rst} (83%)
rename Documentation/{pps/pps.txt => driver-api/pps.rst} (89%)
rename Documentation/{ptp/ptp.txt => driver-api/ptp.rst} (88%)
rename Documentation/fault-injection/{fault-injection.txt => fault-injection.rst} (68%)
create mode 100644 Documentation/fault-injection/index.rst
rename Documentation/fault-injection/{notifier-error-inject.txt => notifier-error-inject.rst} (83%)
rename Documentation/fault-injection/{nvme-fault-injection.txt => nvme-fault-injection.rst} (19%)
rename Documentation/fault-injection/{provoke-crashes.txt => provoke-crashes.rst} (45%)
rename Documentation/fb/{api.txt => api.rst} (97%)
rename Documentation/fb/{arkfb.txt => arkfb.rst} (92%)
rename Documentation/fb/{aty128fb.txt => aty128fb.rst} (61%)
rename Documentation/fb/{cirrusfb.txt => cirrusfb.rst} (75%)
rename Documentation/fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} (50%)
rename Documentation/fb/{deferred_io.txt => deferred_io.rst} (86%)
rename Documentation/fb/{efifb.txt => efifb.rst} (75%)
rename Documentation/fb/{ep93xx-fb.txt => ep93xx-fb.rst} (85%)
rename Documentation/fb/{fbcon.txt => fbcon.rst} (69%)
rename Documentation/fb/{framebuffer.txt => framebuffer.rst} (92%)
rename Documentation/fb/{gxfb.txt => gxfb.rst} (60%)
create mode 100644 Documentation/fb/index.rst
rename Documentation/fb/{intel810.txt => intel810.rst} (83%)
rename Documentation/fb/{intelfb.txt => intelfb.rst} (73%)
rename Documentation/fb/{internals.txt => internals.rst} (82%)
rename Documentation/fb/{lxfb.txt => lxfb.rst} (60%)
rename Documentation/fb/{matroxfb.txt => matroxfb.rst} (32%)
rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%)
rename Documentation/fb/{modedb.txt => modedb.rst} (87%)
rename Documentation/fb/{pvr2fb.txt => pvr2fb.rst} (36%)
rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%)
rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%)
rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%)
rename Documentation/fb/{sh7760fb.txt => sh7760fb.rst} (39%)
rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%)
rename Documentation/fb/{sm501.txt => sm501.rst} (65%)
rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%)
rename Documentation/fb/{sstfb.txt => sstfb.rst} (28%)
rename Documentation/fb/{tgafb.txt => tgafb.rst} (71%)
rename Documentation/fb/{tridentfb.txt => tridentfb.rst} (70%)
rename Documentation/fb/{udlfb.txt => udlfb.rst} (77%)
rename Documentation/fb/{uvesafb.txt => uvesafb.rst} (52%)
rename Documentation/fb/{vesafb.txt => vesafb.rst} (57%)
rename Documentation/fb/{viafb.txt => viafb.rst} (18%)
rename Documentation/fb/{vt8623fb.txt => vt8623fb.rst} (85%)
rename Documentation/fpga/{dfl.txt => dfl.rst} (89%)
create mode 100644 Documentation/fpga/index.rst
create mode 100644 Documentation/ide/changelogs.rst
rename Documentation/ide/{ide-tape.txt => ide-tape.rst} (83%)
rename Documentation/ide/{ide.txt => ide.rst} (72%)
create mode 100644 Documentation/ide/index.rst
rename Documentation/ide/{warm-plug-howto.txt => warm-plug-howto.rst} (61%)
rename Documentation/infiniband/{core_locking.txt => core_locking.rst} (78%)
create mode 100644 Documentation/infiniband/index.rst
rename Documentation/infiniband/{ipoib.txt => ipoib.rst} (90%)
rename Documentation/infiniband/{opa_vnic.txt => opa_vnic.rst} (63%)
rename Documentation/infiniband/{sysfs.txt => sysfs.rst} (69%)
rename Documentation/infiniband/{tag_matching.txt => tag_matching.rst} (98%)
rename Documentation/infiniband/{user_mad.txt => user_mad.rst} (90%)
rename Documentation/infiniband/{user_verbs.txt => user_verbs.rst} (93%)
rename Documentation/kbuild/{headers_install.txt => headers_install.rst} (96%)
create mode 100644 Documentation/kbuild/index.rst
create mode 100644 Documentation/kbuild/issues.rst
rename Documentation/kbuild/{kbuild.txt => kbuild.rst} (72%)
rename Documentation/kbuild/{kconfig-language.txt => kconfig-language.rst} (85%)
rename Documentation/kbuild/{kconfig-macro-language.txt => kconfig-macro-language.rst} (94%)
rename Documentation/kbuild/{kconfig.txt => kconfig.rst} (80%)
rename Documentation/kbuild/{makefiles.txt => makefiles.rst} (83%)
rename Documentation/kbuild/{modules.txt => modules.rst} (84%)
create mode 100644 Documentation/kdump/index.rst
rename Documentation/kdump/{kdump.txt => kdump.rst} (91%)
rename Documentation/kdump/{vmcoreinfo.txt => vmcoreinfo.rst} (95%)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
rename Documentation/locking/{lockstat.txt => lockstat.rst} (41%)
rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%)
rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%)
rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%)
rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%)
rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%)
rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%)
create mode 100644 Documentation/mic/index.rst
rename Documentation/mic/{mic_overview.txt => mic_overview.rst} (96%)
rename Documentation/mic/{scif_overview.txt => scif_overview.rst} (76%)
rename Documentation/netlabel/{cipso_ipv4.txt => cipso_ipv4.rst} (87%)
create mode 100644 Documentation/netlabel/draft_ietf.rst
create mode 100644 Documentation/netlabel/index.rst
rename Documentation/netlabel/{introduction.txt => introduction.rst} (91%)
rename Documentation/netlabel/{lsm_interface.txt => lsm_interface.rst} (88%)
rename Documentation/pcmcia/{devicetable.txt => devicetable.rst} (97%)
rename Documentation/pcmcia/{driver-changes.txt => driver-changes.rst} (90%)
rename Documentation/pcmcia/{driver.txt => driver.rst} (66%)
create mode 100644 Documentation/pcmcia/index.rst
rename Documentation/pcmcia/{locking.txt => locking.rst} (81%)
rename Documentation/power/{apm-acpi.txt => apm-acpi.rst} (87%)
rename Documentation/power/{basic-pm-debugging.txt => basic-pm-debugging.rst} (87%)
rename Documentation/power/{charger-manager.txt => charger-manager.rst} (78%)
rename Documentation/power/{drivers-testing.txt => drivers-testing.rst} (86%)
rename Documentation/power/{energy-model.txt => energy-model.rst} (74%)
rename Documentation/power/{freezing-of-tasks.txt => freezing-of-tasks.rst} (75%)
create mode 100644 Documentation/power/index.rst
rename Documentation/power/{interface.txt => interface.rst} (84%)
rename Documentation/power/{opp.txt => opp.rst} (78%)
rename Documentation/power/{pci.txt => pci.rst} (97%)
rename Documentation/power/{pm_qos_interface.txt => pm_qos_interface.rst} (62%)
rename Documentation/power/{power_supply_class.txt => power_supply_class.rst} (46%)
rename Documentation/power/powercap/{powercap.txt => powercap.rst} (40%)
rename Documentation/power/regulator/{consumer.txt => consumer.rst} (61%)
rename Documentation/power/regulator/{design.txt => design.rst} (86%)
rename Documentation/power/regulator/{machine.txt => machine.rst} (75%)
rename Documentation/power/regulator/{overview.txt => overview.rst} (79%)
rename Documentation/power/regulator/{regulator.txt => regulator.rst} (49%)
rename Documentation/power/{runtime_pm.txt => runtime_pm.rst} (89%)
rename Documentation/power/{s2ram.txt => s2ram.rst} (92%)
rename Documentation/power/{suspend-and-cpuhotplug.txt => suspend-and-cpuhotplug.rst} (90%)
rename Documentation/power/{suspend-and-interrupts.txt => suspend-and-interrupts.rst} (98%)
rename Documentation/power/{swsusp-and-swap-files.txt => swsusp-and-swap-files.rst} (83%)
rename Documentation/power/{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} (67%)
rename Documentation/power/{swsusp.txt => swsusp.rst} (20%)
rename Documentation/power/{tricks.txt => tricks.rst} (93%)
rename Documentation/power/{userland-swsusp.txt => userland-swsusp.rst} (85%)
rename Documentation/power/{video.txt => video.rst} (56%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
create mode 100644 Documentation/riscv/index.rst
rename Documentation/riscv/{pmu.txt => pmu.rst} (77%)
rename Documentation/s390/{3270.txt => 3270.rst} (90%)
rename Documentation/s390/{cds.txt => cds.rst} (64%)
rename Documentation/s390/{CommonIO => common_io.rst} (87%)
rename Documentation/s390/{DASD => dasd.rst} (92%)
rename Documentation/s390/{Debugging390.txt => debugging390.rst} (43%)
rename Documentation/s390/{driver-model.txt => driver-model.rst} (73%)
create mode 100644 Documentation/s390/index.rst
rename Documentation/s390/{monreader.txt => monreader.rst} (81%)
rename Documentation/s390/{qeth.txt => qeth.rst} (62%)
rename Documentation/s390/{s390dbf.txt => s390dbf.rst} (18%)
create mode 100644 Documentation/s390/text_files.rst
rename Documentation/s390/{vfio-ap.txt => vfio-ap.rst} (72%)
rename Documentation/s390/{vfio-ccw.txt => vfio-ccw.rst} (89%)
rename Documentation/s390/{zfcpdump.txt => zfcpdump.rst} (97%)
rename Documentation/scheduler/{completion.txt => completion.rst} (94%)
create mode 100644 Documentation/scheduler/index.rst
rename Documentation/scheduler/{sched-arch.txt => sched-arch.rst} (81%)
rename Documentation/scheduler/{sched-bwc.txt => sched-bwc.rst} (90%)
rename Documentation/scheduler/{sched-deadline.txt => sched-deadline.rst} (88%)
rename Documentation/scheduler/{sched-design-CFS.txt => sched-design-CFS.rst} (97%)
rename Documentation/scheduler/{sched-domains.txt => sched-domains.rst} (97%)
rename Documentation/scheduler/{sched-energy.txt => sched-energy.rst} (96%)
rename Documentation/scheduler/{sched-nice-design.txt => sched-nice-design.rst} (98%)
rename Documentation/scheduler/{sched-rt-group.txt => sched-rt-group.rst} (95%)
rename Documentation/scheduler/{sched-stats.txt => sched-stats.rst} (91%)
create mode 100644 Documentation/scheduler/text_files.rst
create mode 100644 Documentation/target/index.rst
create mode 100644 Documentation/target/scripts.rst
rename Documentation/target/{tcm_mod_builder.txt => tcm_mod_builder.rst} (22%)
rename Documentation/target/{tcmu-design.txt => tcmu-design.rst} (69%)
rename Documentation/timers/{highres.txt => highres.rst} (98%)
rename Documentation/timers/{hpet.txt => hpet.rst} (91%)
rename Documentation/timers/{hrtimers.txt => hrtimers.rst} (98%)
create mode 100644 Documentation/timers/index.rst
rename Documentation/timers/{NO_HZ.txt => no_hz.rst} (93%)
rename Documentation/timers/{timekeeping.txt => timekeeping.rst} (98%)
rename Documentation/timers/{timers-howto.txt => timers-howto.rst} (93%)
rename Documentation/watchdog/{convert_drivers_to_kernel_api.txt => convert_drivers_to_kernel_api.rst} (75%)
rename Documentation/watchdog/{hpwdt.txt => hpwdt.rst} (78%)
create mode 100644 Documentation/watchdog/index.rst
rename Documentation/watchdog/{mlx-wdt.txt => mlx-wdt.rst} (78%)
rename Documentation/watchdog/{pcwd-watchdog.txt => pcwd-watchdog.rst} (89%)
rename Documentation/watchdog/{watchdog-api.txt => watchdog-api.rst} (80%)
rename Documentation/watchdog/{watchdog-kernel-api.txt => watchdog-kernel-api.rst} (90%)
rename Documentation/watchdog/{watchdog-parameters.txt => watchdog-parameters.rst} (42%)
rename Documentation/watchdog/{watchdog-pm.txt => watchdog-pm.rst} (92%)
rename Documentation/watchdog/{wdt.txt => wdt.rst} (68%)
rename Documentation/xilinx/{eemi.txt => eemi.rst} (92%)
create mode 100644 Documentation/xilinx/index.rst
--
2.21.0
^ permalink raw reply
* [PATCH v3 17/33] docs: mic: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sudeep Dutt, Ashutosh Dixit
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
Convert Intel Many Integrated Core architecture docs to ReST.
The conversion is trivial: just add title and literal block
markups, and adjust some identation.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/mic/index.rst | 18 ++++++
.../{mic_overview.txt => mic_overview.rst} | 6 +-
.../{scif_overview.txt => scif_overview.rst} | 58 +++++++++++--------
3 files changed, 57 insertions(+), 25 deletions(-)
create mode 100644 Documentation/mic/index.rst
rename Documentation/mic/{mic_overview.txt => mic_overview.rst} (96%)
rename Documentation/mic/{scif_overview.txt => scif_overview.rst} (76%)
diff --git a/Documentation/mic/index.rst b/Documentation/mic/index.rst
new file mode 100644
index 000000000000..082fa8f6a260
--- /dev/null
+++ b/Documentation/mic/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+=============================================
+Intel Many Integrated Core (MIC) architecture
+=============================================
+
+.. toctree::
+ :maxdepth: 1
+
+ mic_overview
+ scif_overview
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/mic/mic_overview.txt b/Documentation/mic/mic_overview.rst
similarity index 96%
rename from Documentation/mic/mic_overview.txt
rename to Documentation/mic/mic_overview.rst
index 074adbdf83a4..17d956bdaf7c 100644
--- a/Documentation/mic/mic_overview.txt
+++ b/Documentation/mic/mic_overview.rst
@@ -1,3 +1,7 @@
+======================================================
+Intel Many Integrated Core (MIC) architecture overview
+======================================================
+
An Intel MIC X100 device is a PCIe form factor add-in coprocessor
card based on the Intel Many Integrated Core (MIC) architecture
that runs a Linux OS. It is a PCIe endpoint in a platform and therefore
@@ -45,7 +49,7 @@ Here is a block diagram of the various components described above. The
virtio backends are situated on the host rather than the card given better
single threaded performance for the host compared to MIC, the ability of
the host to initiate DMA's to/from the card using the MIC DMA engine and
-the fact that the virtio block storage backend can only be on the host.
+the fact that the virtio block storage backend can only be on the host::
+----------+ | +----------+
| Card OS | | | Host OS |
diff --git a/Documentation/mic/scif_overview.txt b/Documentation/mic/scif_overview.rst
similarity index 76%
rename from Documentation/mic/scif_overview.txt
rename to Documentation/mic/scif_overview.rst
index 0a280d986731..4c8ad9e43706 100644
--- a/Documentation/mic/scif_overview.txt
+++ b/Documentation/mic/scif_overview.rst
@@ -1,3 +1,7 @@
+========================================
+Symmetric Communication Interface (SCIF)
+========================================
+
The Symmetric Communication Interface (SCIF (pronounced as skiff)) is a low
level communications API across PCIe currently implemented for MIC. Currently
SCIF provides inter-node communication within a single host platform, where a
@@ -8,8 +12,11 @@ is to deliver the maximum possible performance given the communication
abilities of the hardware. SCIF has been used to implement an offload compiler
runtime and OFED support for MPI implementations for MIC coprocessors.
-==== SCIF API Components ====
+SCIF API Components
+===================
+
The SCIF API has the following parts:
+
1. Connection establishment using a client server model
2. Byte stream messaging intended for short messages
3. Node enumeration to determine online nodes
@@ -28,9 +35,12 @@ can also register local memory which is followed by data transfer using either
DMA, CPU copies or remote memory mapping via mmap. SCIF supports both user and
kernel mode clients which are functionally equivalent.
-==== SCIF Performance for MIC ====
+SCIF Performance for MIC
+========================
+
DMA bandwidth comparison between the TCP (over ethernet over PCIe) stack versus
-SCIF shows the performance advantages of SCIF for HPC applications and runtimes.
+SCIF shows the performance advantages of SCIF for HPC applications and
+runtimes::
Comparison of TCP and SCIF based BW
@@ -66,33 +76,33 @@ space API similar to the kernel API in scif.h. The SCIF user space library
is distributed @ https://software.intel.com/en-us/mic-developer
Here is some pseudo code for an example of how two applications on two PCIe
-nodes would typically use the SCIF API:
+nodes would typically use the SCIF API::
-Process A (on node A) Process B (on node B)
+ Process A (on node A) Process B (on node B)
-/* get online node information */
-scif_get_node_ids(..) scif_get_node_ids(..)
-scif_open(..) scif_open(..)
-scif_bind(..) scif_bind(..)
-scif_listen(..)
-scif_accept(..) scif_connect(..)
-/* SCIF connection established */
+ /* get online node information */
+ scif_get_node_ids(..) scif_get_node_ids(..)
+ scif_open(..) scif_open(..)
+ scif_bind(..) scif_bind(..)
+ scif_listen(..)
+ scif_accept(..) scif_connect(..)
+ /* SCIF connection established */
-/* Send and receive short messages */
-scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..)
+ /* Send and receive short messages */
+ scif_send(..)/scif_recv(..) scif_send(..)/scif_recv(..)
-/* Register memory */
-scif_register(..) scif_register(..)
+ /* Register memory */
+ scif_register(..) scif_register(..)
-/* RDMA */
-scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..)
+ /* RDMA */
+ scif_readfrom(..)/scif_writeto(..) scif_readfrom(..)/scif_writeto(..)
-/* Fence DMAs */
-scif_fence_signal(..) scif_fence_signal(..)
+ /* Fence DMAs */
+ scif_fence_signal(..) scif_fence_signal(..)
-mmap(..) mmap(..)
+ mmap(..) mmap(..)
-/* Access remote registered memory */
+ /* Access remote registered memory */
-/* Close the endpoints */
-scif_close(..) scif_close(..)
+ /* Close the endpoints */
+ scif_close(..) scif_close(..)
--
2.21.0
^ permalink raw reply related
* [PATCH v3 07/33] docs: cpu-freq: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:26 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Rafael J. Wysocki, Viresh Kumar, linux-pm
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{amd-powernow.txt => amd-powernow.rst} | 11 +-
Documentation/cpu-freq/{core.txt => core.rst} | 66 +++---
.../{cpu-drivers.txt => cpu-drivers.rst} | 217 +++++++++---------
...pufreq-nforce2.txt => cpufreq-nforce2.rst} | 12 +-
.../{cpufreq-stats.txt => cpufreq-stats.rst} | 141 ++++++------
.../cpu-freq/{index.txt => index.rst} | 44 ++--
.../{pcc-cpufreq.txt => pcc-cpufreq.rst} | 102 ++++----
drivers/cpufreq/Kconfig.x86 | 2 +-
8 files changed, 302 insertions(+), 293 deletions(-)
rename Documentation/cpu-freq/{amd-powernow.txt => amd-powernow.rst} (91%)
rename Documentation/cpu-freq/{core.txt => core.rst} (67%)
rename Documentation/cpu-freq/{cpu-drivers.txt => cpu-drivers.rst} (57%)
rename Documentation/cpu-freq/{cpufreq-nforce2.txt => cpufreq-nforce2.rst} (65%)
rename Documentation/cpu-freq/{cpufreq-stats.txt => cpufreq-stats.rst} (31%)
rename Documentation/cpu-freq/{index.txt => index.rst} (37%)
rename Documentation/cpu-freq/{pcc-cpufreq.txt => pcc-cpufreq.rst} (80%)
diff --git a/Documentation/cpu-freq/amd-powernow.txt b/Documentation/cpu-freq/amd-powernow.rst
similarity index 91%
rename from Documentation/cpu-freq/amd-powernow.txt
rename to Documentation/cpu-freq/amd-powernow.rst
index 254da155fa47..50b2c45c3a2c 100644
--- a/Documentation/cpu-freq/amd-powernow.txt
+++ b/Documentation/cpu-freq/amd-powernow.rst
@@ -1,3 +1,7 @@
+=============================
+AMD powernow driver specifics
+=============================
+
PowerNow! and Cool'n'Quiet are AMD names for frequency
management capabilities in AMD processors. As the hardware
@@ -23,16 +27,19 @@ not supply these tables.
7th Generation: powernow-k7: Athlon, Duron, Geode.
8th Generation: powernow-k8: Athlon, Athlon 64, Opteron, Sempron.
+
Documentation on this functionality in 8th generation processors
is available in the "BIOS and Kernel Developer's Guide", publication
-26094, in chapter 9, available for download from www.amd.com.
+26094, in chapter 9, available for download from www.amd.com.
BIOS supplied data, for powernow-k7 and for powernow-k8, may be
from either the PSB table or from ACPI objects. The ACPI support
is only available if the kernel config sets CONFIG_ACPI_PROCESSOR.
+
The powernow-k8 driver will attempt to use ACPI if so configured,
and fall back to PST if that fails.
+
The powernow-k7 driver will try to use the PSB support first, and
fall back to ACPI if the PSB support fails. A module parameter,
-acpi_force, is provided to force ACPI support to be used instead
+acpi_force, is provided to force ACPI support to be used instead
of PSB support.
diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.rst
similarity index 67%
rename from Documentation/cpu-freq/core.txt
rename to Documentation/cpu-freq/core.rst
index 073f128af5a7..c719e3cb700c 100644
--- a/Documentation/cpu-freq/core.txt
+++ b/Documentation/cpu-freq/core.rst
@@ -1,31 +1,22 @@
- CPU frequency and voltage scaling code in the Linux(TM) kernel
+================================================================
+General description of the CPUFreq core and of CPUFreq notifiers
+================================================================
+Authors:
+ - Dominik Brodowski <linux@brodo.de>
+ - David Kimdon <dwhedon@debian.org>
+ - Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+ - Viresh Kumar <viresh.kumar@linaro.org>
- L i n u x C P U F r e q
- C P U F r e q C o r e
+.. Contents:
-
- Dominik Brodowski <linux@brodo.de>
- David Kimdon <dwhedon@debian.org>
- Rafael J. Wysocki <rafael.j.wysocki@intel.com>
- Viresh Kumar <viresh.kumar@linaro.org>
-
-
-
- Clock scaling allows you to change the clock speed of the CPUs on the
- fly. This is a nice method to save battery power, because the lower
- the clock speed, the less power the CPU consumes.
-
-
-Contents:
----------
-1. CPUFreq core and interfaces
-2. CPUFreq notifiers
-3. CPUFreq Table Generation with Operating Performance Point (OPP)
+ 1. CPUFreq core and interfaces
+ 2. CPUFreq notifiers
+ 3. CPUFreq Table Generation with Operating Performance Point (OPP)
1. General Information
-=======================
+======================
The CPUFreq core code is located in drivers/cpufreq/cpufreq.c. This
cpufreq code offers a standardized interface for the CPUFreq
@@ -60,18 +51,18 @@ transition notifiers.
These are notified when a new policy is intended to be set. Each
CPUFreq policy notifier is called twice for a policy transition:
-1.) During CPUFREQ_ADJUST all CPUFreq notifiers may change the limit if
- they see a need for this - may it be thermal considerations or
- hardware limitations.
+1) During CPUFREQ_ADJUST all CPUFreq notifiers may change the limit if
+ they see a need for this - may it be thermal considerations or
+ hardware limitations.
-2.) And during CPUFREQ_NOTIFY all notifiers are informed of the new policy
- - if two hardware drivers failed to agree on a new policy before this
+2) And during CPUFREQ_NOTIFY all notifiers are informed of the new policy -
+ if two hardware drivers failed to agree on a new policy before this
stage, the incompatible hardware shall be shut down, and the user
informed of this.
The phase is specified in the second argument to the notifier.
-The third argument, a void *pointer, points to a struct cpufreq_policy
+The third argument, a `void *` pointer, points to a struct cpufreq_policy
consisting of several values, including min, max (the lower and upper
frequencies (in kHz) of the new policy).
@@ -88,23 +79,27 @@ CPUFREQ_POSTCHANGE.
The third argument is a struct cpufreq_freqs with the following
values:
-cpu - number of the affected CPU
-old - old frequency
-new - new frequency
-flags - flags of the cpufreq driver
+
+======= ===========================
+cpu number of the affected CPU
+old old frequency
+new new frequency
+flags flags of the cpufreq driver
+======= ===========================
3. CPUFreq Table Generation with Operating Performance Point (OPP)
==================================================================
For details about OPP, see Documentation/power/opp.txt
-dev_pm_opp_init_cpufreq_table -
+dev_pm_opp_init_cpufreq_table
This function provides a ready to use conversion routine to translate
the OPP layer's internal information about the available frequencies
into a format readily providable to cpufreq.
WARNING: Do not use this function in interrupt context.
- Example:
+ Example::
+
soc_pm_init()
{
/* Do things */
@@ -117,4 +112,5 @@ dev_pm_opp_init_cpufreq_table -
NOTE: This function is available only if CONFIG_CPU_FREQ is enabled in
addition to CONFIG_PM_OPP.
-dev_pm_opp_free_cpufreq_table - Free up the table allocated by dev_pm_opp_init_cpufreq_table
+dev_pm_opp_free_cpufreq_table
+ Free up the table allocated by dev_pm_opp_init_cpufreq_table
diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.rst
similarity index 57%
rename from Documentation/cpu-freq/cpu-drivers.txt
rename to Documentation/cpu-freq/cpu-drivers.rst
index 6e353d00cdc6..9cc2559bc34b 100644
--- a/Documentation/cpu-freq/cpu-drivers.txt
+++ b/Documentation/cpu-freq/cpu-drivers.rst
@@ -1,35 +1,25 @@
- CPU frequency and voltage scaling code in the Linux(TM) kernel
-
-
- L i n u x C P U F r e q
-
- C P U D r i v e r s
-
- - information for developers -
-
-
- Dominik Brodowski <linux@brodo.de>
- Rafael J. Wysocki <rafael.j.wysocki@intel.com>
- Viresh Kumar <viresh.kumar@linaro.org>
-
-
-
- Clock scaling allows you to change the clock speed of the CPUs on the
- fly. This is a nice method to save battery power, because the lower
- the clock speed, the less power the CPU consumes.
-
-
-Contents:
----------
-1. What To Do?
-1.1 Initialization
-1.2 Per-CPU Initialization
-1.3 verify
-1.4 target/target_index or setpolicy?
-1.5 target/target_index
-1.6 setpolicy
-1.7 get_intermediate and target_intermediate
-2. Frequency Table Helpers
+===============================================
+How to implement a new cpufreq processor driver
+===============================================
+
+.. information for developers
+
+Authors:
+ - Dominik Brodowski <linux@brodo.de>
+ - Rafael J. Wysocki <rafael.j.wysocki@intel.com>
+ - Viresh Kumar <viresh.kumar@linaro.org>
+
+.. Contents:
+
+ 1. What To Do?
+ 1.1 Initialization
+ 1.2 Per-CPU Initialization
+ 1.3 verify
+ 1.4 target/target_index or setpolicy?
+ 1.5 target/target_index
+ 1.6 setpolicy
+ 1.7 get_intermediate and target_intermediate
+ 2. Frequency Table Helpers
@@ -46,59 +36,73 @@ on what is necessary:
First of all, in an __initcall level 7 (module_init()) or later
function check whether this kernel runs on the right CPU and the right
-chipset. If so, register a struct cpufreq_driver with the CPUfreq core
-using cpufreq_register_driver()
+chipset. If so, register a `struct cpufreq_driver` with the CPUfreq core
+using `cpufreq_register_driver()`
-What shall this struct cpufreq_driver contain?
+What shall this `struct cpufreq_driver` contain?
- .name - The name of this driver.
+.name
+ The name of this driver.
- .init - A pointer to the per-policy initialization function.
+.init
+ A pointer to the per-policy initialization function.
- .verify - A pointer to a "verification" function.
+.verify
+ A pointer to a "verification" function.
- .setpolicy _or_ .fast_switch _or_ .target _or_ .target_index - See
- below on the differences.
+.setpolicy **or** .fast_switch **or** .target **or** .target_index
+ See below on the differences.
And optionally
- .flags - Hints for the cpufreq core.
+.flags
+ Hints for the cpufreq core.
- .driver_data - cpufreq driver specific data.
+.driver_data
+ cpufreq driver specific data.
- .resolve_freq - Returns the most appropriate frequency for a target
- frequency. Doesn't change the frequency though.
+.resolve_freq
+ Returns the most appropriate frequency for a target
+ frequency. Doesn't change the frequency though.
- .get_intermediate and target_intermediate - Used to switch to stable
- frequency while changing CPU frequency.
+.get_intermediate and target_intermediate
+ Used to switch to stable frequency while changing CPU frequency.
- .get - Returns current frequency of the CPU.
+.get
+ Returns current frequency of the CPU.
- .bios_limit - Returns HW/BIOS max frequency limitations for the CPU.
+.bios_limit
+ Returns HW/BIOS max frequency limitations for the CPU.
- .exit - A pointer to a per-policy cleanup function called during
- CPU_POST_DEAD phase of cpu hotplug process.
+.exit
+ A pointer to a per-policy cleanup function called during
+ CPU_POST_DEAD phase of cpu hotplug process.
- .stop_cpu - A pointer to a per-policy stop function called during
- CPU_DOWN_PREPARE phase of cpu hotplug process.
+.stop_cpu
+ A pointer to a per-policy stop function called during
+ CPU_DOWN_PREPARE phase of cpu hotplug process.
- .suspend - A pointer to a per-policy suspend function which is called
- with interrupts disabled and _after_ the governor is stopped for the
- policy.
+.suspend
+ A pointer to a per-policy suspend function which is called with
+ interrupts disabled and **after** the governor is stopped for the policy.
- .resume - A pointer to a per-policy resume function which is called
- with interrupts disabled and _before_ the governor is started again.
+.resume
+ A pointer to a per-policy resume function which is called
+ with interrupts disabled and **before** the governor is started again.
- .ready - A pointer to a per-policy ready function which is called after
- the policy is fully initialized.
+.ready
+ A pointer to a per-policy ready function which is called after
+ the policy is fully initialized.
- .attr - A pointer to a NULL-terminated list of "struct freq_attr" which
- allow to export values to sysfs.
+.attr
+ A pointer to a NULL-terminated list of `struct freq_attr` which
+ allow to export values to sysfs.
- .boost_enabled - If set, boost frequencies are enabled.
+.boost_enabled
+ If set, boost frequencies are enabled.
- .set_boost - A pointer to a per-policy function to enable/disable boost
- frequencies.
+.set_boost
+ A pointer to a per-policy function to enable/disable boost frequencies.
1.2 Per-CPU Initialization
@@ -108,37 +112,42 @@ Whenever a new CPU is registered with the device model, or after the
cpufreq driver registers itself, the per-policy initialization function
cpufreq_driver.init is called if no cpufreq policy existed for the CPU.
Note that the .init() and .exit() routines are called only once for the
-policy and not for each CPU managed by the policy. It takes a struct
-cpufreq_policy *policy as argument. What to do now?
+policy and not for each CPU managed by the policy. It takes a `struct
+cpufreq_policy *policy` as argument. What to do now?
If necessary, activate the CPUfreq support on your CPU.
Then, the driver must fill in the following values:
-policy->cpuinfo.min_freq _and_
-policy->cpuinfo.max_freq - the minimum and maximum frequency
- (in kHz) which is supported by
- this CPU
-policy->cpuinfo.transition_latency the time it takes on this CPU to
- switch between two frequencies in
- nanoseconds (if appropriate, else
- specify CPUFREQ_ETERNAL)
-
-policy->cur The current operating frequency of
- this CPU (if appropriate)
-policy->min,
-policy->max,
-policy->policy and, if necessary,
-policy->governor must contain the "default policy" for
- this CPU. A few moments later,
- cpufreq_driver.verify and either
- cpufreq_driver.setpolicy or
- cpufreq_driver.target/target_index is called
- with these values.
-policy->cpus Update this with the masks of the
- (online + offline) CPUs that do DVFS
- along with this CPU (i.e. that share
- clock/voltage rails with it).
++---------------------------------------+--------------------------------------+
+| policy->cpuinfo.min_freq **and** | |
+| policy->cpuinfo.max_freq | the minimum and maximum frequency |
+| | (in kHz) which is supported by |
+| | this CPU |
++---------------------------------------+--------------------------------------+
+| policy->cpuinfo.transition_latency | the time it takes on this CPU to |
+| | switch between two frequencies in |
+| | nanoseconds (if appropriate, else |
+| | specify CPUFREQ_ETERNAL) |
++---------------------------------------+--------------------------------------+
+| policy->cur | The current operating frequency of |
+| | this CPU (if appropriate) |
++---------------------------------------+--------------------------------------+
+| policy->min, | |
+| policy->max, | |
+| policy->policy and, if necessary, | |
+| policy->governor | must contain the "default policy" |
+| | for this CPU. A few moments later, |
+| | cpufreq_driver.verify and either |
+| | cpufreq_driver.setpolicy or |
+| | cpufreq_driver.target/target_index |
+| | is called with these values. |
++---------------------------------------+--------------------------------------+
+| policy->cpus | Update this with the masks of the |
+| | (online + offline) CPUs that do DVFS |
+| | along with this CPU (i.e. that share |
+| | clock/voltage rails with it). |
++---------------------------------------+--------------------------------------+
For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the
frequency table helpers might be helpful. See the section 2 for more information
@@ -151,8 +160,8 @@ on them.
When the user decides a new policy (consisting of
"policy,governor,min,max") shall be set, this policy must be validated
so that incompatible values can be corrected. For verifying these
-values cpufreq_verify_within_limits(struct cpufreq_policy *policy,
-unsigned int min_freq, unsigned int max_freq) function might be helpful.
+values `cpufreq_verify_within_limits(struct cpufreq_policy *policy,
+unsigned int min_freq, unsigned int max_freq)` function might be helpful.
See section 2 for details on frequency table helpers.
You need to make sure that at least one valid frequency (or operating
@@ -163,7 +172,7 @@ policy->max first, and only if this is no solution, decrease policy->min.
1.4 target or target_index or setpolicy or fast_switch?
-------------------------------------------------------
-Most cpufreq drivers or even most cpu frequency scaling algorithms
+Most cpufreq drivers or even most cpu frequency scaling algorithms
only allow the CPU frequency to be set to predefined fixed values. For
these, you use the ->target(), ->target_index() or ->fast_switch()
callbacks.
@@ -175,8 +184,8 @@ limits on their own. These shall use the ->setpolicy() callback.
1.5. target/target_index
------------------------
-The target_index call has two arguments: struct cpufreq_policy *policy,
-and unsigned int index (into the exposed frequency table).
+The target_index call has two arguments: `struct cpufreq_policy *policy`,
+and `unsigned int index` (into the exposed frequency table).
The CPUfreq driver must set the new frequency when called here. The
actual frequency must be determined by freq_table[index].frequency.
@@ -184,10 +193,10 @@ actual frequency must be determined by freq_table[index].frequency.
It should always restore to earlier frequency (i.e. policy->restore_freq) in
case of errors, even if we switched to intermediate frequency earlier.
-Deprecated:
+Deprecated
----------
-The target call has three arguments: struct cpufreq_policy *policy,
-unsigned int target_frequency, unsigned int relation.
+The target call has three arguments: `struct cpufreq_policy *policy`,
+`unsigned int target_frequency`, `unsigned int relation`.
The CPUfreq driver must set the new frequency when called here. The
actual frequency must be determined using the following rules:
@@ -210,14 +219,14 @@ Not all drivers are expected to implement it, as sleeping from within
this callback isn't allowed. This callback must be highly optimized to
do switching as fast as possible.
-This function has two arguments: struct cpufreq_policy *policy and
-unsigned int target_frequency.
+This function has two arguments: `struct cpufreq_policy *policy` and
+`unsigned int target_frequency`.
1.7 setpolicy
-------------
-The setpolicy call only takes a struct cpufreq_policy *policy as
+The setpolicy call only takes a `struct cpufreq_policy *policy` as
argument. You need to set the lower limit of the in-processor or
in-chipset dynamic frequency switching to policy->min, the upper limit
to policy->max, and -if supported- select a performance-oriented
@@ -278,10 +287,10 @@ table.
cpufreq_for_each_valid_entry(pos, table) - iterates over all entries,
excluding CPUFREQ_ENTRY_INVALID frequencies.
-Use arguments "pos" - a cpufreq_frequency_table * as a loop cursor and
-"table" - the cpufreq_frequency_table * you want to iterate over.
+Use arguments "pos" - a `cpufreq_frequency_table *` as a loop cursor and
+"table" - the `cpufreq_frequency_table *` you want to iterate over.
-For example:
+For example::
struct cpufreq_frequency_table *pos, *driver_freq_table;
diff --git a/Documentation/cpu-freq/cpufreq-nforce2.txt b/Documentation/cpu-freq/cpufreq-nforce2.rst
similarity index 65%
rename from Documentation/cpu-freq/cpufreq-nforce2.txt
rename to Documentation/cpu-freq/cpufreq-nforce2.rst
index babce1315026..d40700bd5083 100644
--- a/Documentation/cpu-freq/cpufreq-nforce2.txt
+++ b/Documentation/cpu-freq/cpufreq-nforce2.rst
@@ -1,3 +1,6 @@
+=================================
+nVidia nForce2 platform specifics
+=================================
The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 platforms.
@@ -6,14 +9,15 @@ can be controlled independently from the PCI/AGP clock.
The module has two options:
+ ======== ======================================
fid: multiplier * 10 (for example 8.5 = 85)
min_fsb: minimum FSB
+ ======== ======================================
If not set, fid is calculated from the current CPU speed and the FSB.
min_fsb defaults to FSB at boot time - 50 MHz.
-IMPORTANT: The available range is limited downwards!
- Also the minimum available FSB can differ, for systems
+IMPORTANT:
+ The available range is limited downwards!
+ Also the minimum available FSB can differ, for systems
booting with 200 MHz, 150 should always work.
-
-
diff --git a/Documentation/cpu-freq/cpufreq-stats.txt b/Documentation/cpu-freq/cpufreq-stats.rst
similarity index 31%
rename from Documentation/cpu-freq/cpufreq-stats.txt
rename to Documentation/cpu-freq/cpufreq-stats.rst
index 14378cecb172..3e33712b496e 100644
--- a/Documentation/cpu-freq/cpufreq-stats.txt
+++ b/Documentation/cpu-freq/cpufreq-stats.rst
@@ -1,21 +1,20 @@
+==========================================
+General description of sysfs cpufreq stats
+==========================================
- CPU frequency and voltage scaling statistics in the Linux(TM) kernel
+.. information for users
- L i n u x c p u f r e q - s t a t s d r i v e r
+Author: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
- - information for users -
-
-
- Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
-
-Contents
-1. Introduction
-2. Statistics Provided (with example)
-3. Configuring cpufreq-stats
+.. Contents
+ 1. Introduction
+ 2. Statistics Provided (with example)
+ 3. Configuring cpufreq-stats
1. Introduction
+===============
cpufreq-stats is a driver that provides CPU frequency statistics for each CPU.
These statistics are provided in /sysfs as a bunch of read_only interfaces. This
@@ -28,6 +27,7 @@ that may be running on your CPU. So, it will work with any cpufreq_driver.
2. Statistics Provided (with example)
+=====================================
cpufreq stats provides following statistics (explained in detail below).
- time_in_state
@@ -39,78 +39,79 @@ All the statistics will be from the time the stats driver has been inserted
statistic is done. Obviously, stats driver will not have any information
about the frequency transitions before the stats driver insertion.
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l
-total 0
-drwxr-xr-x 2 root root 0 May 14 16:06 .
-drwxr-xr-x 3 root root 0 May 14 15:58 ..
---w------- 1 root root 4096 May 14 16:06 reset
--r--r--r-- 1 root root 4096 May 14 16:06 time_in_state
--r--r--r-- 1 root root 4096 May 14 16:06 total_trans
--r--r--r-- 1 root root 4096 May 14 16:06 trans_table
---------------------------------------------------------------------------------
+::
-- reset
-Write-only attribute that can be used to reset the stat counters. This can be
-useful for evaluating system behaviour under different governors without the
-need for a reboot.
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l
+ total 0
+ drwxr-xr-x 2 root root 0 May 14 16:06 .
+ drwxr-xr-x 3 root root 0 May 14 15:58 ..
+ --w------- 1 root root 4096 May 14 16:06 reset
+ -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state
+ -r--r--r-- 1 root root 4096 May 14 16:06 total_trans
+ -r--r--r-- 1 root root 4096 May 14 16:06 trans_table
-- time_in_state
-This gives the amount of time spent in each of the frequencies supported by
-this CPU. The cat output will have "<frequency> <time>" pair in each line, which
-will mean this CPU spent <time> usertime units of time at <frequency>. Output
-will have one line for each of the supported frequencies. usertime units here
-is 10mS (similar to other time exported in /proc).
+reset
+ Write-only attribute that can be used to reset the stat counters. This can be
+ useful for evaluating system behaviour under different governors without the
+ need for a reboot.
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state
-3600000 2089
-3400000 136
-3200000 34
-3000000 67
-2800000 172488
---------------------------------------------------------------------------------
+time_in_state
+ This gives the amount of time spent in each of the frequencies supported by
+ this CPU. The cat output will have "<frequency> <time>" pair in each line,
+ which will mean this CPU spent <time> usertime units of time at <frequency>.
+ Output will have one line for each of the supported frequencies. usertime
+ units here is 10mS (similar to other time exported in /proc).
+::
-- total_trans
-This gives the total number of frequency transitions on this CPU. The cat
-output will have a single count which is the total number of frequency
-transitions.
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state
+ 3600000 2089
+ 3400000 136
+ 3200000 34
+ 3000000 67
+ 2800000 172488
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans
-20
---------------------------------------------------------------------------------
-- trans_table
-This will give a fine grained information about all the CPU frequency
-transitions. The cat output here is a two dimensional matrix, where an entry
-<i,j> (row i, column j) represents the count of number of transitions from
-Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in
-which the driver has provided the frequency table initially to the cpufreq core
-and so can be sorted (ascending or descending) or unsorted. The output here
-also contains the actual freq values for each row and column for better
-readability.
+total_trans
+ This gives the total number of frequency transitions on this CPU. The cat
+ output will have a single count which is the total number of frequency
+ transitions.
-If the transition table is bigger than PAGE_SIZE, reading this will
-return an -EFBIG error.
+::
---------------------------------------------------------------------------------
-<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table
- From : To
- : 3600000 3400000 3200000 3000000 2800000
- 3600000: 0 5 0 0 0
- 3400000: 4 0 2 0 0
- 3200000: 0 1 0 2 0
- 3000000: 0 0 1 0 3
- 2800000: 0 0 0 2 0
---------------------------------------------------------------------------------
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans
+ 20
+trans_table
+ This will give a fine grained information about all the CPU frequency
+ transitions. The cat output here is a two dimensional matrix, where an entry
+ <i,j> (row i, column j) represents the count of number of transitions from
+ Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in
+ which the driver has provided the frequency table initially to the cpufreq
+ core and so can be sorted (ascending or descending) or unsorted. The output
+ here also contains the actual freq values for each row and column for better
+ readability.
+
+ If the transition table is bigger than PAGE_SIZE, reading this will
+ return an -EFBIG error.
+
+::
+
+ <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table
+ From : To
+ : 3600000 3400000 3200000 3000000 2800000
+ 3600000: 0 5 0 0 0
+ 3400000: 4 0 2 0 0
+ 3200000: 0 1 0 2 0
+ 3000000: 0 0 1 0 3
+ 2800000: 0 0 0 2 0
3. Configuring cpufreq-stats
+============================
-To configure cpufreq-stats in your kernel
-Config Main Menu
+To configure cpufreq-stats in your kernel::
+
+ Config Main Menu
Power management options (ACPI, APM) --->
CPU Frequency scaling --->
[*] CPU Frequency scaling
diff --git a/Documentation/cpu-freq/index.txt b/Documentation/cpu-freq/index.rst
similarity index 37%
rename from Documentation/cpu-freq/index.txt
rename to Documentation/cpu-freq/index.rst
index c15e75386a05..10e6c05f60f6 100644
--- a/Documentation/cpu-freq/index.txt
+++ b/Documentation/cpu-freq/index.rst
@@ -1,39 +1,35 @@
- CPU frequency and voltage scaling code in the Linux(TM) kernel
+:orphan:
+==============================================================
+CPU frequency and voltage scaling code in the Linux(TM) kernel
+==============================================================
- L i n u x C P U F r e q
+Author: Dominik Brodowski <linux@brodo.de>
+Clock scaling allows you to change the clock speed of the CPUs on the
+fly. This is a nice method to save battery power, because the lower
+the clock speed, the less power the CPU consumes.
- Dominik Brodowski <linux@brodo.de>
+.. toctree::
+ :maxdepth: 1
+ core
+ cpufreq-stats
+ cpu-drivers
- Clock scaling allows you to change the clock speed of the CPUs on the
- fly. This is a nice method to save battery power, because the lower
- the clock speed, the less power the CPU consumes.
+ amd-powernow
+ cpufreq-nforce2
+ pcc-cpufreq
+.. only:: subproject and html
+ Indices
+ =======
-Documents in this directory:
-----------------------------
-
-amd-powernow.txt - AMD powernow driver specific file.
-
-core.txt - General description of the CPUFreq core and
- of CPUFreq notifiers.
-
-cpu-drivers.txt - How to implement a new cpufreq processor driver.
-
-cpufreq-nforce2.txt - nVidia nForce2 platform specific file.
-
-cpufreq-stats.txt - General description of sysfs cpufreq stats.
-
-index.txt - File index, Mailing list and Links (this document)
-
-pcc-cpufreq.txt - PCC cpufreq driver specific file.
-
+ * :ref:`genindex`
Mailing List
------------
diff --git a/Documentation/cpu-freq/pcc-cpufreq.txt b/Documentation/cpu-freq/pcc-cpufreq.rst
similarity index 80%
rename from Documentation/cpu-freq/pcc-cpufreq.txt
rename to Documentation/cpu-freq/pcc-cpufreq.rst
index 9e3c3b33514c..d846a36536e4 100644
--- a/Documentation/cpu-freq/pcc-cpufreq.txt
+++ b/Documentation/cpu-freq/pcc-cpufreq.rst
@@ -1,45 +1,38 @@
-/*
- * pcc-cpufreq.txt - PCC interface documentation
- *
- * Copyright (C) 2009 Red Hat, Matthew Garrett <mjg@redhat.com>
- * Copyright (C) 2009 Hewlett-Packard Development Company, L.P.
- * Nagananda Chumbalkar <nagananda.chumbalkar@hp.com>
- *
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; version 2 of the License.
- *
- * This program is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or NON
- * INFRINGEMENT. See the GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- */
-
-
- Processor Clocking Control Driver
- ---------------------------------
-
-Contents:
----------
-1. Introduction
-1.1 PCC interface
-1.1.1 Get Average Frequency
-1.1.2 Set Desired Frequency
-1.2 Platforms affected
-2. Driver and /sys details
-2.1 scaling_available_frequencies
-2.2 cpuinfo_transition_latency
-2.3 cpuinfo_cur_freq
-2.4 related_cpus
-3. Caveats
+==========================================================
+Processor Clocking Control Driver cpufreq driver specifics
+==========================================================
+
+
+.. pcc-cpufreq.txt - PCC interface documentation
+
+ Copyright (C) 2009 Red Hat, Matthew Garrett <mjg@redhat.com>
+ Copyright (C) 2009 Hewlett-Packard Development Company, L.P.
+ Nagananda Chumbalkar <nagananda.chumbalkar@hp.com>
+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; version 2 of the License.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or NON
+ INFRINGEMENT. See the GNU General Public License for more details.
+
+
+.. Contents:
+ 1. Introduction
+ 1.1 PCC interface
+ 1.1.1 Get Average Frequency
+ 1.1.2 Set Desired Frequency
+ 1.2 Platforms affected
+ 2. Driver and /sys details
+ 2.1 scaling_available_frequencies
+ 2.2 cpuinfo_transition_latency
+ 2.3 cpuinfo_cur_freq
+ 2.4 related_cpus
+ 3. Caveats
1. Introduction:
----------------
@@ -72,6 +65,7 @@ memory region. The shared memory region header contains the "command" and
doorbell.
The following commands are supported by the PCC interface:
+
* Get Average Frequency
* Set Desired Frequency
@@ -140,7 +134,9 @@ Internally, there is no need for the driver to convert the "target" frequency
to a corresponding P-state.
The VERSION number for the driver will be of the format v.xy.ab.
-eg: 1.00.02
+eg::
+
+ 1.00.02
----- --
| |
| -- this will increase with bug fixes/enhancements to the driver
@@ -168,21 +164,21 @@ A) Often cpuinfo_cur_freq will show a value different than what is declared
in the scaling_available_frequencies or scaling_cur_freq, or scaling_max_freq.
This is due to "turbo boost" available on recent Intel processors. If certain
conditions are met the BIOS can achieve a slightly higher speed than requested
-by OSPM. An example:
+by OSPM. An example::
-scaling_cur_freq : 2933000
-cpuinfo_cur_freq : 3196000
+ scaling_cur_freq : 2933000
+ cpuinfo_cur_freq : 3196000
B) There is a round-off error associated with the cpuinfo_cur_freq value.
Since the driver obtains the current frequency as a "percentage" (%) of the
nominal frequency from the BIOS, sometimes, the values displayed by
-scaling_cur_freq and cpuinfo_cur_freq may not match. An example:
+scaling_cur_freq and cpuinfo_cur_freq may not match. An example::
-scaling_cur_freq : 1600000
-cpuinfo_cur_freq : 1583000
+ scaling_cur_freq : 1600000
+ cpuinfo_cur_freq : 1583000
In this example, the nominal frequency is 2933 MHz. The driver obtains the
-current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency:
+current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency::
54% of 2933 MHz = 1583 MHz
@@ -191,10 +187,10 @@ corresponds to the frequency of the P0 P-state.
2.4 related_cpus:
-----------------
-The related_cpus field is identical to affected_cpus.
+The related_cpus field is identical to affected_cpus:
-affected_cpus : 4
-related_cpus : 4
+ affected_cpus : 4
+ related_cpus : 4
Currently, the PCC driver does not evaluate _PSD. The platforms that support
PCC do not implement SW_ALL. So OSPM doesn't need to perform any coordination
diff --git a/drivers/cpufreq/Kconfig.x86 b/drivers/cpufreq/Kconfig.x86
index dfa6457deaf6..336a295fac4c 100644
--- a/drivers/cpufreq/Kconfig.x86
+++ b/drivers/cpufreq/Kconfig.x86
@@ -25,7 +25,7 @@ config X86_PCC_CPUFREQ
This driver adds support for the PCC interface.
For details, take a look at:
- <file:Documentation/cpu-freq/pcc-cpufreq.txt>.
+ <file:Documentation/cpu-freq/pcc-cpufreq.rst>.
To compile this driver as a module, choose M here: the
module will be called pcc-cpufreq.
--
2.21.0
^ permalink raw reply related
* [PATCH v3 09/33] docs: fault-injection: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:26 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Akinobu Mita, Federico Vaga, Harry Wei, Alex Shi,
Kees Cook, Arnd Bergmann, Greg Kroah-Hartman
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...ault-injection.txt => fault-injection.rst} | 265 +++++++++---------
Documentation/fault-injection/index.rst | 20 ++
...r-inject.txt => notifier-error-inject.rst} | 18 +-
...injection.txt => nvme-fault-injection.rst} | 174 ++++++------
...rovoke-crashes.txt => provoke-crashes.rst} | 40 ++-
Documentation/process/4.Coding.rst | 2 +-
.../translations/it_IT/process/4.Coding.rst | 2 +-
.../translations/zh_CN/process/4.Coding.rst | 2 +-
drivers/misc/lkdtm/core.c | 2 +-
include/linux/fault-inject.h | 2 +-
lib/Kconfig.debug | 2 +-
tools/testing/fault-injection/failcmd.sh | 2 +-
12 files changed, 290 insertions(+), 241 deletions(-)
rename Documentation/fault-injection/{fault-injection.txt => fault-injection.rst} (68%)
create mode 100644 Documentation/fault-injection/index.rst
rename Documentation/fault-injection/{notifier-error-inject.txt => notifier-error-inject.rst} (83%)
rename Documentation/fault-injection/{nvme-fault-injection.txt => nvme-fault-injection.rst} (19%)
rename Documentation/fault-injection/{provoke-crashes.txt => provoke-crashes.rst} (45%)
diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.rst
similarity index 68%
rename from Documentation/fault-injection/fault-injection.txt
rename to Documentation/fault-injection/fault-injection.rst
index a17517a083c3..f51bb21d20e4 100644
--- a/Documentation/fault-injection/fault-injection.txt
+++ b/Documentation/fault-injection/fault-injection.rst
@@ -1,3 +1,4 @@
+===========================================
Fault injection capabilities infrastructure
===========================================
@@ -7,36 +8,36 @@ See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug.
Available fault injection capabilities
--------------------------------------
-o failslab
+- failslab
injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
-o fail_page_alloc
+- fail_page_alloc
injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
-o fail_futex
+- fail_futex
injects futex deadlock and uaddr fault errors.
-o fail_make_request
+- fail_make_request
injects disk IO errors on devices permitted by setting
/sys/block/<device>/make-it-fail or
/sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
-o fail_mmc_request
+- fail_mmc_request
injects MMC data errors on devices permitted by setting
debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request
-o fail_function
+- fail_function
injects error return on specific functions, which are marked by
ALLOW_ERROR_INJECTION() macro, by setting debugfs entries
under /sys/kernel/debug/fail_function. No boot option supported.
-o NVMe fault injection
+- NVMe fault injection
inject NVMe status code and retry flag on devices permitted by setting
debugfs entries under /sys/kernel/debug/nvme*/fault_inject. The default
@@ -47,7 +48,8 @@ o NVMe fault injection
Configure fault-injection capabilities behavior
-----------------------------------------------
-o debugfs entries
+debugfs entries
+^^^^^^^^^^^^^^^
fault-inject-debugfs kernel module provides some debugfs entries for runtime
configuration of fault-injection capabilities.
@@ -55,6 +57,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/probability:
likelihood of failure injection, in percent.
+
Format: <percent>
Note that one-failure-per-hundred is a very high error rate
@@ -83,6 +86,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/verbose
Format: { 0 | 1 | 2 }
+
specifies the verbosity of the messages when failure is
injected. '0' means no messages; '1' will print only a single
log line per failure; '2' will print a call trace too -- useful
@@ -91,14 +95,15 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail*/task-filter:
Format: { 'Y' | 'N' }
+
A value of 'N' disables filtering by process (default).
Any positive value limits failures to only processes indicated by
/proc/<pid>/make-it-fail==1.
-- /sys/kernel/debug/fail*/require-start:
-- /sys/kernel/debug/fail*/require-end:
-- /sys/kernel/debug/fail*/reject-start:
-- /sys/kernel/debug/fail*/reject-end:
+- /sys/kernel/debug/fail*/require-start,
+ /sys/kernel/debug/fail*/require-end,
+ /sys/kernel/debug/fail*/reject-start,
+ /sys/kernel/debug/fail*/reject-end:
specifies the range of virtual addresses tested during
stacktrace walking. Failure is injected only if some caller
@@ -116,6 +121,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' won't inject failures into
highmem/user allocations.
@@ -123,6 +129,7 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will inject failures
only into non-sleep allocations (GFP_ATOMIC allocations).
@@ -134,12 +141,14 @@ configuration of fault-injection capabilities.
- /sys/kernel/debug/fail_futex/ignore-private:
Format: { 'Y' | 'N' }
+
default is 'N', setting it to 'Y' will disable failure injections
when dealing with private (address space) futexes.
- /sys/kernel/debug/fail_function/inject:
Format: { 'function-name' | '!function-name' | '' }
+
specifies the target function of error injection by name.
If the function name leads '!' prefix, given function is
removed from injection list. If nothing specified ('')
@@ -160,10 +169,11 @@ configuration of fault-injection capabilities.
function for given function. This will be created when
user specifies new injection entry.
-o Boot option
+Boot option
+^^^^^^^^^^^
In order to inject faults while debugfs is not available (early boot time),
-use the boot option:
+use the boot option::
failslab=
fail_page_alloc=
@@ -171,10 +181,11 @@ use the boot option:
fail_futex=
mmc_core.fail_request=<interval>,<probability>,<space>,<times>
-o proc entries
+proc entries
+^^^^^^^^^^^^
-- /proc/<pid>/fail-nth:
-- /proc/self/task/<tid>/fail-nth:
+- /proc/<pid>/fail-nth,
+ /proc/self/task/<tid>/fail-nth:
Write to this file of integer N makes N-th call in the task fail.
Read from this file returns a integer value. A value of '0' indicates
@@ -191,16 +202,16 @@ o proc entries
How to add new fault injection capability
-----------------------------------------
-o #include <linux/fault-inject.h>
+- #include <linux/fault-inject.h>
-o define the fault attributes
+- define the fault attributes
DECLARE_FAULT_ATTR(name);
Please see the definition of struct fault_attr in fault-inject.h
for details.
-o provide a way to configure fault attributes
+- provide a way to configure fault attributes
- boot option
@@ -222,126 +233,126 @@ o provide a way to configure fault attributes
single kernel module, it is better to provide module parameters to
configure the fault attributes.
-o add a hook to insert failures
+- add a hook to insert failures
- Upon should_fail() returning true, client code should inject a failure.
+ Upon should_fail() returning true, client code should inject a failure:
should_fail(attr, size);
Application Examples
--------------------
-o Inject slab allocation failures into module init/exit code
+- Inject slab allocation failures into module init/exit code::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=failslab
-echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ FAILTYPE=failslab
+ echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-faulty_system()
-{
+ faulty_system()
+ {
bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
-}
+ }
-if [ $# -eq 0 ]
-then
+ if [ $# -eq 0 ]
+ then
echo "Usage: $0 modulename [ modulename ... ]"
exit 1
-fi
+ fi
-for m in $*
-do
+ for m in $*
+ do
echo inserting $m...
faulty_system modprobe $m
echo removing $m...
faulty_system modprobe -r $m
-done
+ done
------------------------------------------------------------------------------
-o Inject page allocation failures only for a specific module
+- Inject page allocation failures only for a specific module::
-#!/bin/bash
+ #!/bin/bash
-FAILTYPE=fail_page_alloc
-module=$1
+ FAILTYPE=fail_page_alloc
+ module=$1
-if [ -z $module ]
-then
+ if [ -z $module ]
+ then
echo "Usage: $0 <modulename>"
exit 1
-fi
+ fi
-modprobe $module
+ modprobe $module
-if [ ! -d /sys/module/$module/sections ]
-then
+ if [ ! -d /sys/module/$module/sections ]
+ then
echo Module $module is not loaded
exit 1
-fi
+ fi
-cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
-cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
+ cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
+ cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
-echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+ echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
+ echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
-trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
+ trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
-echo "Injecting errors into the module $module... (interrupt to stop)"
-sleep 1000000
+ echo "Injecting errors into the module $module... (interrupt to stop)"
+ sleep 1000000
------------------------------------------------------------------------------
-o Inject open_ctree error while btrfs mount
+- Inject open_ctree error while btrfs mount::
-#!/bin/bash
+ #!/bin/bash
-rm -f testfile.img
-dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
-DEVICE=$(losetup --show -f testfile.img)
-mkfs.btrfs -f $DEVICE
-mkdir -p tmpmnt
+ rm -f testfile.img
+ dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
+ DEVICE=$(losetup --show -f testfile.img)
+ mkfs.btrfs -f $DEVICE
+ mkdir -p tmpmnt
-FAILTYPE=fail_function
-FAILFUNC=open_ctree
-echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
-echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 100 > /sys/kernel/debug/$FAILTYPE/probability
-echo 0 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
+ FAILTYPE=fail_function
+ FAILFUNC=open_ctree
+ echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
+ echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
+ echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+ echo 100 > /sys/kernel/debug/$FAILTYPE/probability
+ echo 0 > /sys/kernel/debug/$FAILTYPE/interval
+ echo -1 > /sys/kernel/debug/$FAILTYPE/times
+ echo 0 > /sys/kernel/debug/$FAILTYPE/space
+ echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
-mount -t btrfs $DEVICE tmpmnt
-if [ $? -ne 0 ]
-then
+ mount -t btrfs $DEVICE tmpmnt
+ if [ $? -ne 0 ]
+ then
echo "SUCCESS!"
-else
+ else
echo "FAILED!"
umount tmpmnt
-fi
+ fi
-echo > /sys/kernel/debug/$FAILTYPE/inject
+ echo > /sys/kernel/debug/$FAILTYPE/inject
-rmdir tmpmnt
-losetup -d $DEVICE
-rm testfile.img
+ rmdir tmpmnt
+ losetup -d $DEVICE
+ rm testfile.img
Tool to run command with failslab or fail_page_alloc
@@ -354,43 +365,43 @@ see the following examples.
Examples:
Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab
-allocation failure.
+allocation failure::
# ./tools/testing/fault-injection/failcmd.sh \
-- make -C tools/testing/selftests/ run_tests
Same as above except to specify 100 times failures at most instead of one time
-at most by default.
+at most by default::
# ./tools/testing/fault-injection/failcmd.sh --times=100 \
-- make -C tools/testing/selftests/ run_tests
Same as above except to inject page allocation failure instead of slab
-allocation failure.
+allocation failure::
# env FAILCMD_TYPE=fail_page_alloc \
./tools/testing/fault-injection/failcmd.sh --times=100 \
- -- make -C tools/testing/selftests/ run_tests
+ -- make -C tools/testing/selftests/ run_tests
Systematic faults using fail-nth
---------------------------------
The following code systematically faults 0-th, 1-st, 2-nd and so on
-capabilities in the socketpair() system call.
+capabilities in the socketpair() system call::
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <sys/socket.h>
-#include <sys/syscall.h>
-#include <fcntl.h>
-#include <unistd.h>
-#include <string.h>
-#include <stdlib.h>
-#include <stdio.h>
-#include <errno.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <sys/socket.h>
+ #include <sys/syscall.h>
+ #include <fcntl.h>
+ #include <unistd.h>
+ #include <string.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+ #include <errno.h>
-int main()
-{
+ int main()
+ {
int i, err, res, fail_nth, fds[2];
char buf[128];
@@ -413,23 +424,23 @@ int main()
break;
}
return 0;
-}
+ }
-An example output:
+An example output::
-1-th fault Y: res=-1/23
-2-th fault Y: res=-1/23
-3-th fault Y: res=-1/12
-4-th fault Y: res=-1/12
-5-th fault Y: res=-1/23
-6-th fault Y: res=-1/23
-7-th fault Y: res=-1/23
-8-th fault Y: res=-1/12
-9-th fault Y: res=-1/12
-10-th fault Y: res=-1/12
-11-th fault Y: res=-1/12
-12-th fault Y: res=-1/12
-13-th fault Y: res=-1/12
-14-th fault Y: res=-1/12
-15-th fault Y: res=-1/12
-16-th fault N: res=0/12
+ 1-th fault Y: res=-1/23
+ 2-th fault Y: res=-1/23
+ 3-th fault Y: res=-1/12
+ 4-th fault Y: res=-1/12
+ 5-th fault Y: res=-1/23
+ 6-th fault Y: res=-1/23
+ 7-th fault Y: res=-1/23
+ 8-th fault Y: res=-1/12
+ 9-th fault Y: res=-1/12
+ 10-th fault Y: res=-1/12
+ 11-th fault Y: res=-1/12
+ 12-th fault Y: res=-1/12
+ 13-th fault Y: res=-1/12
+ 14-th fault Y: res=-1/12
+ 15-th fault Y: res=-1/12
+ 16-th fault N: res=0/12
diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst
new file mode 100644
index 000000000000..92b5639ed07a
--- /dev/null
+++ b/Documentation/fault-injection/index.rst
@@ -0,0 +1,20 @@
+:orphan:
+
+===============
+fault-injection
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ fault-injection
+ notifier-error-inject
+ nvme-fault-injection
+ provoke-crashes
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/fault-injection/notifier-error-inject.txt b/Documentation/fault-injection/notifier-error-inject.rst
similarity index 83%
rename from Documentation/fault-injection/notifier-error-inject.txt
rename to Documentation/fault-injection/notifier-error-inject.rst
index e861d761de24..1668b6e48d3a 100644
--- a/Documentation/fault-injection/notifier-error-inject.txt
+++ b/Documentation/fault-injection/notifier-error-inject.rst
@@ -14,7 +14,8 @@ modules that can be used to test the following notifiers.
PM notifier error injection module
----------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
Possible PM notifier events to be failed are:
@@ -22,7 +23,7 @@ Possible PM notifier events to be failed are:
* PM_SUSPEND_PREPARE
* PM_RESTORE_PREPARE
-Example: Inject PM suspend error (-12 = -ENOMEM)
+Example: Inject PM suspend error (-12 = -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/pm/
# echo -12 > actions/PM_SUSPEND_PREPARE/error
@@ -32,14 +33,15 @@ Example: Inject PM suspend error (-12 = -ENOMEM)
Memory hotplug notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
Possible memory notifier events to be failed are:
* MEM_GOING_ONLINE
* MEM_GOING_OFFLINE
-Example: Inject memory hotplug offline error (-12 == -ENOMEM)
+Example: Inject memory hotplug offline error (-12 == -ENOMEM)::
# cd /sys/kernel/debug/notifier-error-inject/memory
# echo -12 > actions/MEM_GOING_OFFLINE/error
@@ -49,7 +51,8 @@ Example: Inject memory hotplug offline error (-12 == -ENOMEM)
powerpc pSeries reconfig notifier error injection module
--------------------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
Possible pSeries reconfig notifier events to be failed are:
@@ -61,7 +64,8 @@ Possible pSeries reconfig notifier events to be failed are:
Netdevice notifier error injection module
----------------------------------------------
This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
+
+ /sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
Netdevice notifier events which can be failed are:
@@ -75,7 +79,7 @@ Netdevice notifier events which can be failed are:
* NETDEV_PRECHANGEUPPER
* NETDEV_CHANGEUPPER
-Example: Inject netdevice mtu change error (-22 == -EINVAL)
+Example: Inject netdevice mtu change error (-22 == -EINVAL)::
# cd /sys/kernel/debug/notifier-error-inject/netdev
# echo -22 > actions/NETDEV_CHANGEMTU/error
diff --git a/Documentation/fault-injection/nvme-fault-injection.txt b/Documentation/fault-injection/nvme-fault-injection.rst
similarity index 19%
rename from Documentation/fault-injection/nvme-fault-injection.txt
rename to Documentation/fault-injection/nvme-fault-injection.rst
index 8fbf3bf60b62..bbb1bf3e8650 100644
--- a/Documentation/fault-injection/nvme-fault-injection.txt
+++ b/Documentation/fault-injection/nvme-fault-injection.rst
@@ -16,101 +16,105 @@ following.
Example 1: Inject default status code with no retry
---------------------------------------------------
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-cp a.file /mnt
+::
-Expected Result:
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ cp a.file /mnt
-cp: cannot stat ‘/mnt/a.file’: Input/output error
+Expected Result::
-Message from dmesg:
+ cp: cannot stat ‘/mnt/a.file’: Input/output error
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
-Hardware name: innotek GmbH VirtualBox/VirtualBox,
-BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x2f/0x50 [nvme_core]
- nvme_process_cq+0xe7/0x1d0 [nvme]
- nvme_irq+0x1e/0x40 [nvme]
- __handle_irq_event_percpu+0x3a/0x190
- handle_irq_event_percpu+0x30/0x70
- handle_irq_event+0x36/0x60
- handle_fasteoi_irq+0x78/0x120
- handle_irq+0xa7/0x130
- ? tick_irq_enter+0xa8/0xc0
- do_IRQ+0x43/0xc0
- common_interrupt+0xa2/0xa2
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
-RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
-R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_kernel+0x4c4/0x4e4
- ? set_init_arg+0x55/0x55
- secondary_startup_64+0xa5/0xb0
- print_req_error: I/O error, dev nvme0n1, sector 9240
-EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
-inode #2: comm cp: reading directory lblock 0
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 0 PID: 0 Comm: swapper/0 Not tainted 4.15.0-rc8+ #2
+ Hardware name: innotek GmbH VirtualBox/VirtualBox,
+ BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x2f/0x50 [nvme_core]
+ nvme_process_cq+0xe7/0x1d0 [nvme]
+ nvme_irq+0x1e/0x40 [nvme]
+ __handle_irq_event_percpu+0x3a/0x190
+ handle_irq_event_percpu+0x30/0x70
+ handle_irq_event+0x36/0x60
+ handle_fasteoi_irq+0x78/0x120
+ handle_irq+0xa7/0x130
+ ? tick_irq_enter+0xa8/0xc0
+ do_IRQ+0x43/0xc0
+ common_interrupt+0xa2/0xa2
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffffff82003e90 EFLAGS: 00000246 ORIG_RAX: ffffffffffffffdd
+ RAX: ffffffff817a10c0 RBX: ffffffff82012480 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000000 R08: 000000008e38ce64 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffffffff82012480
+ R13: ffffffff82012480 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_kernel+0x4c4/0x4e4
+ ? set_init_arg+0x55/0x55
+ secondary_startup_64+0xa5/0xb0
+ print_req_error: I/O error, dev nvme0n1, sector 9240
+ EXT4-fs error (device nvme0n1): ext4_find_entry:1436:
+ inode #2: comm cp: reading directory lblock 0
Example 2: Inject default status code with retry
------------------------------------------------
-mount /dev/nvme0n1 /mnt
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
-echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
-echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
-echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
+::
-cp a.file /mnt
+ mount /dev/nvme0n1 /mnt
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/times
+ echo 100 > /sys/kernel/debug/nvme0n1/fault_inject/probability
+ echo 1 > /sys/kernel/debug/nvme0n1/fault_inject/status
+ echo 0 > /sys/kernel/debug/nvme0n1/fault_inject/dont_retry
-Expected Result:
+ cp a.file /mnt
-command success without error
+Expected Result::
-Message from dmesg:
+ command success without error
-FAULT_INJECTION: forcing a failure.
-name fault_inject, interval 1, probability 100, space 0, times 1
-CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
-Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
-Call Trace:
- <IRQ>
- dump_stack+0x5c/0x7d
- should_fail+0x148/0x170
- nvme_should_fail+0x30/0x60 [nvme_core]
- nvme_loop_queue_response+0x84/0x110 [nvme_loop]
- nvmet_req_complete+0x11/0x40 [nvmet]
- nvmet_bio_done+0x28/0x40 [nvmet]
- blk_update_request+0xb0/0x310
- blk_mq_end_request+0x18/0x60
- flush_smp_call_function_queue+0x3d/0xf0
- smp_call_function_single_interrupt+0x2c/0xc0
- call_function_single_interrupt+0xa2/0xb0
- </IRQ>
-RIP: 0010:native_safe_halt+0x2/0x10
-RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
-RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
-RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
-RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
-R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
-R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
- ? __sched_text_end+0x4/0x4
- default_idle+0x18/0xf0
- do_idle+0x150/0x1d0
- cpu_startup_entry+0x6f/0x80
- start_secondary+0x187/0x1e0
- secondary_startup_64+0xa5/0xb0
+Message from dmesg::
+
+ FAULT_INJECTION: forcing a failure.
+ name fault_inject, interval 1, probability 100, space 0, times 1
+ CPU: 1 PID: 0 Comm: swapper/1 Not tainted 4.15.0-rc8+ #4
+ Hardware name: innotek GmbH VirtualBox/VirtualBox, BIOS VirtualBox 12/01/2006
+ Call Trace:
+ <IRQ>
+ dump_stack+0x5c/0x7d
+ should_fail+0x148/0x170
+ nvme_should_fail+0x30/0x60 [nvme_core]
+ nvme_loop_queue_response+0x84/0x110 [nvme_loop]
+ nvmet_req_complete+0x11/0x40 [nvmet]
+ nvmet_bio_done+0x28/0x40 [nvmet]
+ blk_update_request+0xb0/0x310
+ blk_mq_end_request+0x18/0x60
+ flush_smp_call_function_queue+0x3d/0xf0
+ smp_call_function_single_interrupt+0x2c/0xc0
+ call_function_single_interrupt+0xa2/0xb0
+ </IRQ>
+ RIP: 0010:native_safe_halt+0x2/0x10
+ RSP: 0018:ffffc9000068bec0 EFLAGS: 00000246 ORIG_RAX: ffffffffffffff04
+ RAX: ffffffff817a10c0 RBX: ffff88011a3c9680 RCX: 0000000000000000
+ RDX: 0000000000000000 RSI: 0000000000000000 RDI: 0000000000000000
+ RBP: 0000000000000001 R08: 000000008e38c131 R09: 0000000000000000
+ R10: 0000000000000000 R11: 0000000000000000 R12: ffff88011a3c9680
+ R13: ffff88011a3c9680 R14: 0000000000000000 R15: 0000000000000000
+ ? __sched_text_end+0x4/0x4
+ default_idle+0x18/0xf0
+ do_idle+0x150/0x1d0
+ cpu_startup_entry+0x6f/0x80
+ start_secondary+0x187/0x1e0
+ secondary_startup_64+0xa5/0xb0
diff --git a/Documentation/fault-injection/provoke-crashes.txt b/Documentation/fault-injection/provoke-crashes.rst
similarity index 45%
rename from Documentation/fault-injection/provoke-crashes.txt
rename to Documentation/fault-injection/provoke-crashes.rst
index 7a9d3d81525b..9279a3e12278 100644
--- a/Documentation/fault-injection/provoke-crashes.txt
+++ b/Documentation/fault-injection/provoke-crashes.rst
@@ -1,3 +1,7 @@
+===============
+Provoke crashes
+===============
+
The lkdtm module provides an interface to crash or injure the kernel at
predefined crashpoints to evaluate the reliability of crash dumps obtained
using different dumping solutions. The module uses KPROBEs to instrument
@@ -8,31 +12,37 @@ support.
You can provide the way either through module arguments when inserting
the module, or through a debugfs interface.
-Usage: insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
- [cpoint_count={>0}]
+Usage::
- recur_count : Recursion level for the stack overflow test. Default is 10.
+ insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
+ [cpoint_count={>0}]
- cpoint_name : Crash point where the kernel is to be crashed. It can be
- one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
- FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
- IDE_CORE_CP, DIRECT
+recur_count
+ Recursion level for the stack overflow test. Default is 10.
- cpoint_type : Indicates the action to be taken on hitting the crash point.
- It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
- CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
- WRITE_AFTER_FREE,
+cpoint_name
+ Crash point where the kernel is to be crashed. It can be
+ one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
+ FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
+ IDE_CORE_CP, DIRECT
- cpoint_count : Indicates the number of times the crash point is to be hit
- to trigger an action. The default is 10.
+cpoint_type
+ Indicates the action to be taken on hitting the crash point.
+ It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
+ CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
+ WRITE_AFTER_FREE,
+
+cpoint_count
+ Indicates the number of times the crash point is to be hit
+ to trigger an action. The default is 10.
You can also induce failures by mounting debugfs and writing the type to
-<mountpoint>/provoke-crash/<crashpoint>. E.g.,
+<mountpoint>/provoke-crash/<crashpoint>. E.g.::
mount -t debugfs debugfs /mnt
echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
-A special file is `DIRECT' which will induce the crash directly without
+A special file is `DIRECT` which will induce the crash directly without
KPROBE instrumentation. This mode is the only one available when the module
is built on a kernel without KPROBEs support.
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 4b7a5ab3cec1..13dd893c9f88 100644
--- a/Documentation/process/4.Coding.rst
+++ b/Documentation/process/4.Coding.rst
@@ -298,7 +298,7 @@ enabled, a configurable percentage of memory allocations will be made to
fail; these failures can be restricted to a specific range of code.
Running with fault injection enabled allows the programmer to see how the
code responds when things go badly. See
-Documentation/fault-injection/fault-injection.txt for more information on
+Documentation/fault-injection/fault-injection.rst for more information on
how to use this facility.
Other kinds of errors can be found with the "sparse" static analysis tool.
diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst
index c05b89e616dd..a5e36aa60448 100644
--- a/Documentation/translations/it_IT/process/4.Coding.rst
+++ b/Documentation/translations/it_IT/process/4.Coding.rst
@@ -314,7 +314,7 @@ di allocazione di memoria sarà destinata al fallimento; questi fallimenti
possono essere ridotti ad uno specifico pezzo di codice. Procedere con
l'inserimento dei fallimenti attivo permette al programmatore di verificare
come il codice risponde quando le cose vanno male. Consultate:
-Documentation/fault-injection/fault-injection.txt per avere maggiori
+Documentation/fault-injection/fault-injection.rst per avere maggiori
informazioni su come utilizzare questo strumento.
Altre tipologie di errori possono essere riscontrati con lo strumento di
diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst
index 8bb777941394..b82b1dde3122 100644
--- a/Documentation/translations/zh_CN/process/4.Coding.rst
+++ b/Documentation/translations/zh_CN/process/4.Coding.rst
@@ -205,7 +205,7 @@ Linus对这个问题给出了最佳答案:
启用故障注入后，内存分配的可配置百分比将失败；这些失败可以限制在特定的代码
范围内。在启用了故障注入的情况下运行，程序员可以看到当情况恶化时代码如何响
应。有关如何使用此工具的详细信息，请参阅
-Documentation/fault-injection/fault-injection.txt。
+Documentation/fault-injection/fault-injection.rst。
使用“sparse”静态分析工具可以发现其他类型的错误。对于sparse，可以警告程序员
用户空间和内核空间地址之间的混淆、big endian和small endian数量的混合、在需
diff --git a/drivers/misc/lkdtm/core.c b/drivers/misc/lkdtm/core.c
index df9429e3fd3a..c7a507482051 100644
--- a/drivers/misc/lkdtm/core.c
+++ b/drivers/misc/lkdtm/core.c
@@ -15,7 +15,7 @@
*
* Debugfs support added by Simon Kagstrom <simon.kagstrom@netinsight.net>
*
- * See Documentation/fault-injection/provoke-crashes.txt for instructions
+ * See Documentation/fault-injection/provoke-crashes.rst for instructions
*/
#include "lkdtm.h"
#include <linux/fs.h>
diff --git a/include/linux/fault-inject.h b/include/linux/fault-inject.h
index 7e6c77740413..e525f6957c49 100644
--- a/include/linux/fault-inject.h
+++ b/include/linux/fault-inject.h
@@ -11,7 +11,7 @@
/*
* For explanation of the elements of this struct, see
- * Documentation/fault-injection/fault-injection.txt
+ * Documentation/fault-injection/fault-injection.rst
*/
struct fault_attr {
unsigned long probability;
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index d08f5848958e..3a3554e8ca0f 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -1701,7 +1701,7 @@ config LKDTM
called lkdtm.
Documentation on how to use the module can be found in
- Documentation/fault-injection/provoke-crashes.txt
+ Documentation/fault-injection/provoke-crashes.rst
config TEST_LIST_SORT
tristate "Linked list sorting test"
diff --git a/tools/testing/fault-injection/failcmd.sh b/tools/testing/fault-injection/failcmd.sh
index 29a6c63c5a15..78dac34264be 100644
--- a/tools/testing/fault-injection/failcmd.sh
+++ b/tools/testing/fault-injection/failcmd.sh
@@ -42,7 +42,7 @@ OPTIONS
--interval=value, --space=value, --verbose=value, --task-filter=value,
--stacktrace-depth=value, --require-start=value, --require-end=value,
--reject-start=value, --reject-end=value, --ignore-gfp-wait=value
- See Documentation/fault-injection/fault-injection.txt for more
+ See Documentation/fault-injection/fault-injection.rst for more
information
failslab options:
--
2.21.0
^ permalink raw reply related
* [PATCH v3 03/33] docs: cdrom-standard.tex: convert from LaTeX to ReST
From: Mauro Carvalho Chehab @ 2019-06-09 2:26 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jens Axboe
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
This is the only LaTeX documentation file inside the documentation.
Instead of having a Latex document directly there, convert
it to ReST format, as this is the format we're using for docs.
For now, let's keep the extension as .txt in order to avoid
warnings when building the documentation with Sphinx.
The next patch patch will rename it to .rst and add it to the
building system.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/cdrom/Makefile | 21 -
...{cdrom-standard.tex => cdrom-standard.txt} | 1491 +++++++++--------
drivers/cdrom/cdrom.c | 2 +-
3 files changed, 765 insertions(+), 749 deletions(-)
delete mode 100644 Documentation/cdrom/Makefile
rename Documentation/cdrom/{cdrom-standard.tex => cdrom-standard.txt} (26%)
diff --git a/Documentation/cdrom/Makefile b/Documentation/cdrom/Makefile
deleted file mode 100644
index a19e321928e1..000000000000
--- a/Documentation/cdrom/Makefile
+++ /dev/null
@@ -1,21 +0,0 @@
-LATEXFILE = cdrom-standard
-
-all:
- make clean
- latex $(LATEXFILE)
- latex $(LATEXFILE)
- @if [ -x `which gv` ]; then \
- `dvips -q -t letter -o $(LATEXFILE).ps $(LATEXFILE).dvi` ;\
- `gv -antialias -media letter -nocenter $(LATEXFILE).ps` ;\
- else \
- `xdvi $(LATEXFILE).dvi &` ;\
- fi
- make sortofclean
-
-clean:
- rm -f $(LATEXFILE).ps $(LATEXFILE).dvi $(LATEXFILE).aux $(LATEXFILE).log
-
-sortofclean:
- rm -f $(LATEXFILE).aux $(LATEXFILE).log
-
-
diff --git a/Documentation/cdrom/cdrom-standard.tex b/Documentation/cdrom/cdrom-standard.txt
similarity index 26%
rename from Documentation/cdrom/cdrom-standard.tex
rename to Documentation/cdrom/cdrom-standard.txt
index f7cd455973f7..dde4f7f7fdbf 100644
--- a/Documentation/cdrom/cdrom-standard.tex
+++ b/Documentation/cdrom/cdrom-standard.txt
@@ -1,488 +1,480 @@
-\documentclass{article}
-\def\version{$Id: cdrom-standard.tex,v 1.9 1997/12/28 15:42:49 david Exp $}
-\newcommand{\newsection}[1]{\newpage\section{#1}}
+=======================
+A Linux CD-ROM standard
+=======================
-\evensidemargin=0pt
-\oddsidemargin=0pt
-\topmargin=-\headheight \advance\topmargin by -\headsep
-\textwidth=15.99cm \textheight=24.62cm % normal A4, 1'' margin
+:Author: David van Leeuwen <david@ElseWare.cistron.nl>
+:Date: 12 March 1999
+:Updated by: Erik Andersen (andersee@debian.org)
+:Updated by: Jens Axboe (axboe@image.dk)
-\def\linux{{\sc Linux}}
-\def\cdrom{{\sc cd-rom}}
-\def\UCD{{\sc Uniform cd-rom Driver}}
-\def\cdromc{{\tt {cdrom.c}}}
-\def\cdromh{{\tt {cdrom.h}}}
-\def\fo{\sl} % foreign words
-\def\ie{{\fo i.e.}}
-\def\eg{{\fo e.g.}}
-\everymath{\it} \everydisplay{\it}
-\catcode `\_=\active \def_{\_\penalty100 }
-\catcode`\<=\active \def<#1>{{\langle\hbox{\rm#1}\rangle}}
+Introduction
+============
-\begin{document}
-\title{A \linux\ \cdrom\ standard}
-\author{David van Leeuwen\\{\normalsize\tt david@ElseWare.cistron.nl}
-\\{\footnotesize updated by Erik Andersen {\tt(andersee@debian.org)}}
-\\{\footnotesize updated by Jens Axboe {\tt(axboe@image.dk)}}}
-\date{12 March 1999}
-
-\maketitle
-
-\newsection{Introduction}
-
-\linux\ is probably the Unix-like operating system that supports
+Linux is probably the Unix-like operating system that supports
the widest variety of hardware devices. The reasons for this are
-presumably
-\begin{itemize}
-\item
- The large list of hardware devices available for the many platforms
- that \linux\ now supports (\ie, i386-PCs, Sparc Suns, etc.)
-\item
- The open design of the operating system, such that anybody can write a
- driver for \linux.
-\item
- There is plenty of source code around as examples of how to write a driver.
-\end{itemize}
-The openness of \linux, and the many different types of available
-hardware has allowed \linux\ to support many different hardware devices.
-Unfortunately, the very openness that has allowed \linux\ to support
+presumably
+
+- The large list of hardware devices available for the many platforms
+ that Linux now supports (i.e., i386-PCs, Sparc Suns, etc.)
+- The open design of the operating system, such that anybody can write a
+ driver for Linux.
+- There is plenty of source code around as examples of how to write a driver.
+
+The openness of Linux, and the many different types of available
+hardware has allowed Linux to support many different hardware devices.
+Unfortunately, the very openness that has allowed Linux to support
all these different devices has also allowed the behavior of each
device driver to differ significantly from one device to another.
-This divergence of behavior has been very significant for \cdrom\
-devices; the way a particular drive reacts to a `standard' $ioctl()$
+This divergence of behavior has been very significant for CD-ROM
+devices; the way a particular drive reacts to a `standard` *ioctl()*
call varies greatly from one device driver to another. To avoid making
-their drivers totally inconsistent, the writers of \linux\ \cdrom\
+their drivers totally inconsistent, the writers of Linux CD-ROM
drivers generally created new device drivers by understanding, copying,
and then changing an existing one. Unfortunately, this practice did not
-maintain uniform behavior across all the \linux\ \cdrom\ drivers.
+maintain uniform behavior across all the Linux CD-ROM drivers.
This document describes an effort to establish Uniform behavior across
-all the different \cdrom\ device drivers for \linux. This document also
-defines the various $ioctl$s, and how the low-level \cdrom\ device
-drivers should implement them. Currently (as of the \linux\ 2.1.$x$
-development kernels) several low-level \cdrom\ device drivers, including
+all the different CD-ROM device drivers for Linux. This document also
+defines the various *ioctl()'s*, and how the low-level CD-ROM device
+drivers should implement them. Currently (as of the Linux 2.1.\ *x*
+development kernels) several low-level CD-ROM device drivers, including
both IDE/ATAPI and SCSI, now use this Uniform interface.
-When the \cdrom\ was developed, the interface between the \cdrom\ drive
+When the CD-ROM was developed, the interface between the CD-ROM drive
and the computer was not specified in the standards. As a result, many
-different \cdrom\ interfaces were developed. Some of them had their
+different CD-ROM interfaces were developed. Some of them had their
own proprietary design (Sony, Mitsumi, Panasonic, Philips), other
manufacturers adopted an existing electrical interface and changed
the functionality (CreativeLabs/SoundBlaster, Teac, Funai) or simply
adapted their drives to one or more of the already existing electrical
interfaces (Aztech, Sanyo, Funai, Vertos, Longshine, Optics Storage and
-most of the `NoName' manufacturers). In cases where a new drive really
+most of the `NoName` manufacturers). In cases where a new drive really
brought its own interface or used its own command set and flow control
scheme, either a separate driver had to be written, or an existing
-driver had to be enhanced. History has delivered us \cdrom\ support for
-many of these different interfaces. Nowadays, almost all new \cdrom\
+driver had to be enhanced. History has delivered us CD-ROM support for
+many of these different interfaces. Nowadays, almost all new CD-ROM
drives are either IDE/ATAPI or SCSI, and it is very unlikely that any
manufacturer will create a new interface. Even finding drives for the
old proprietary interfaces is getting difficult.
When (in the 1.3.70's) I looked at the existing software interface,
-which was expressed through \cdromh, it appeared to be a rather wild
-set of commands and data formats.\footnote{I cannot recollect what
-kernel version I looked at, then, presumably 1.2.13 and 1.3.34---the
-latest kernel that I was indirectly involved in.} It seemed that many
+which was expressed through `cdrom.h`, it appeared to be a rather wild
+set of commands and data formats [#f1]_. It seemed that many
features of the software interface had been added to accommodate the
-capabilities of a particular drive, in an {\fo ad hoc\/} manner. More
-importantly, it appeared that the behavior of the `standard' commands
-was different for most of the different drivers: \eg, some drivers
-close the tray if an $open()$ call occurs when the tray is open, while
+capabilities of a particular drive, in an *ad hoc* manner. More
+importantly, it appeared that the behavior of the `standard` commands
+was different for most of the different drivers: e. g., some drivers
+close the tray if an *open()* call occurs when the tray is open, while
others do not. Some drivers lock the door upon opening the device, to
prevent an incoherent file system, but others don't, to allow software
ejection. Undoubtedly, the capabilities of the different drives vary,
but even when two drives have the same capability their drivers'
behavior was usually different.
-I decided to start a discussion on how to make all the \linux\ \cdrom\
+.. [#f1]
+ I cannot recollect what kernel version I looked at, then,
+ presumably 1.2.13 and 1.3.34 --- the latest kernel that I was
+ indirectly involved in.
+
+I decided to start a discussion on how to make all the Linux CD-ROM
drivers behave more uniformly. I began by contacting the developers of
-the many \cdrom\ drivers found in the \linux\ kernel. Their reactions
-encouraged me to write the \UCD\ which this document is intended to
-describe. The implementation of the \UCD\ is in the file \cdromc. This
-driver is intended to be an additional software layer that sits on top
-of the low-level device drivers for each \cdrom\ drive. By adding this
-additional layer, it is possible to have all the different \cdrom\
-devices behave {\em exactly\/} the same (insofar as the underlying
+the many CD-ROM drivers found in the Linux kernel. Their reactions
+encouraged me to write the Uniform CD-ROM Driver which this document is
+intended to describe. The implementation of the Uniform CD-ROM Driver is
+in the file `cdrom.c`. This driver is intended to be an additional software
+layer that sits on top of the low-level device drivers for each CD-ROM drive.
+By adding this additional layer, it is possible to have all the different
+CD-ROM devices behave **exactly** the same (insofar as the underlying
hardware will allow).
-The goal of the \UCD\ is {\em not\/} to alienate driver developers who
-have not yet taken steps to support this effort. The goal of \UCD\ is
-simply to give people writing application programs for \cdrom\ drives
-{\em one\/} \linux\ \cdrom\ interface with consistent behavior for all
-\cdrom\ devices. In addition, this also provides a consistent interface
-between the low-level device driver code and the \linux\ kernel. Care
-is taken that 100\,\% compatibility exists with the data structures and
-programmer's interface defined in \cdromh. This guide was written to
-help \cdrom\ driver developers adapt their code to use the \UCD\ code
-defined in \cdromc.
+The goal of the Uniform CD-ROM Driver is **not** to alienate driver developers
+whohave not yet taken steps to support this effort. The goal of Uniform CD-ROM
+Driver is simply to give people writing application programs for CD-ROM drives
+**one** Linux CD-ROM interface with consistent behavior for all
+CD-ROM devices. In addition, this also provides a consistent interface
+between the low-level device driver code and the Linux kernel. Care
+is taken that 100% compatibility exists with the data structures and
+programmer's interface defined in `cdrom.h`. This guide was written to
+help CD-ROM driver developers adapt their code to use the Uniform CD-ROM
+Driver code defined in `cdrom.c`.
Personally, I think that the most important hardware interfaces are
the IDE/ATAPI drives and, of course, the SCSI drives, but as prices
of hardware drop continuously, it is also likely that people may have
-more than one \cdrom\ drive, possibly of mixed types. It is important
+more than one CD-ROM drive, possibly of mixed types. It is important
that these drives behave in the same way. In December 1994, one of the
-cheapest \cdrom\ drives was a Philips cm206, a double-speed proprietary
-drive. In the months that I was busy writing a \linux\ driver for it,
+cheapest CD-ROM drives was a Philips cm206, a double-speed proprietary
+drive. In the months that I was busy writing a Linux driver for it,
proprietary drives became obsolete and IDE/ATAPI drives became the
standard. At the time of the last update to this document (November
-1997) it is becoming difficult to even {\em find} anything less than a
-16 speed \cdrom\ drive, and 24 speed drives are common.
+1997) it is becoming difficult to even **find** anything less than a
+16 speed CD-ROM drive, and 24 speed drives are common.
-\newsection{Standardizing through another software level}
-\label{cdrom.c}
+.. _cdrom_api:
+
+Standardizing through another software level
+============================================
At the time this document was conceived, all drivers directly
-implemented the \cdrom\ $ioctl()$ calls through their own routines. This
+implemented the CD-ROM *ioctl()* calls through their own routines. This
led to the danger of different drivers forgetting to do important things
like checking that the user was giving the driver valid data. More
importantly, this led to the divergence of behavior, which has already
been discussed.
-For this reason, the \UCD\ was created to enforce consistent \cdrom\
-drive behavior, and to provide a common set of services to the various
-low-level \cdrom\ device drivers. The \UCD\ now provides another
-software-level, that separates the $ioctl()$ and $open()$ implementation
+For this reason, the Uniform CD-ROM Driver was created to enforce consistent
+CD-ROM drive behavior, and to provide a common set of services to the various
+low-level CD-ROM device drivers. The Uniform CD-ROM Driver now provides another
+software-level, that separates the *ioctl()* and *open()* implementation
from the actual hardware implementation. Note that this effort has
made few changes which will affect a user's application programs. The
greatest change involved moving the contents of the various low-level
-\cdrom\ drivers' header files to the kernel's cdrom directory. This was
+CD-ROM drivers\' header files to the kernel's cdrom directory. This was
done to help ensure that the user is only presented with only one cdrom
-interface, the interface defined in \cdromh.
+interface, the interface defined in `cdrom.h`.
-\cdrom\ drives are specific enough (\ie, different from other
+CD-ROM drives are specific enough (i. e., different from other
block-devices such as floppy or hard disc drives), to define a set
-of common {\em \cdrom\ device operations}, $<cdrom-device>_dops$.
+of common **CD-ROM device operations**, *<cdrom-device>_dops*.
These operations are different from the classical block-device file
-operations, $<block-device>_fops$.
+operations, *<block-device>_fops*.
-The routines for the \UCD\ interface level are implemented in the file
-\cdromc. In this file, the \UCD\ interfaces with the kernel as a block
-device by registering the following general $struct\ file_operations$:
-$$
-\halign{$#$\ \hfil&$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-struct& file_operations\ cdrom_fops = \{\hidewidth\cr
- &NULL, & lseek \cr
- &block_read, & read---general block-dev read \cr
- &block_write, & write---general block-dev write \cr
- &NULL, & readdir \cr
- &NULL, & select \cr
- &cdrom_ioctl, & ioctl \cr
- &NULL, & mmap \cr
- &cdrom_open, & open \cr
- &cdrom_release, & release \cr
- &NULL, & fsync \cr
- &NULL, & fasync \cr
- &cdrom_media_changed, & media change \cr
- &NULL & revalidate \cr
-\};\cr
-}
-$$
+The routines for the Uniform CD-ROM Driver interface level are implemented
+in the file `cdrom.c`. In this file, the Uniform CD-ROM Driver interfaces
+with the kernel as a block device by registering the following general
+*struct file_operations*::
-Every active \cdrom\ device shares this $struct$. The routines
-declared above are all implemented in \cdromc, since this file is the
-place where the behavior of all \cdrom-devices is defined and
-standardized. The actual interface to the various types of \cdrom\
-hardware is still performed by various low-level \cdrom-device
-drivers. These routines simply implement certain {\em capabilities\/}
-that are common to all \cdrom\ (and really, all removable-media
+ struct file_operations cdrom_fops = {
+ NULL, /∗ lseek ∗/
+ block _read , /∗ read—general block-dev read ∗/
+ block _write, /∗ write—general block-dev write ∗/
+ NULL, /∗ readdir ∗/
+ NULL, /∗ select ∗/
+ cdrom_ioctl, /∗ ioctl ∗/
+ NULL, /∗ mmap ∗/
+ cdrom_open, /∗ open ∗/
+ cdrom_release, /∗ release ∗/
+ NULL, /∗ fsync ∗/
+ NULL, /∗ fasync ∗/
+ cdrom_media_changed, /∗ media change ∗/
+ NULL /∗ revalidate ∗/
+ };
+
+Every active CD-ROM device shares this *struct*. The routines
+declared above are all implemented in `cdrom.c`, since this file is the
+place where the behavior of all CD-ROM-devices is defined and
+standardized. The actual interface to the various types of CD-ROM
+hardware is still performed by various low-level CD-ROM-device
+drivers. These routines simply implement certain **capabilities**
+that are common to all CD-ROM (and really, all removable-media
devices).
-Registration of a low-level \cdrom\ device driver is now done through
-the general routines in \cdromc, not through the Virtual File System
-(VFS) any more. The interface implemented in \cdromc\ is carried out
+Registration of a low-level CD-ROM device driver is now done through
+the general routines in `cdrom.c`, not through the Virtual File System
+(VFS) any more. The interface implemented in `cdrom.c` is carried out
through two general structures that contain information about the
capabilities of the driver, and the specific drives on which the
driver operates. The structures are:
-\begin{description}
-\item[$cdrom_device_ops$]
+
+cdrom_device_ops
This structure contains information about the low-level driver for a
- \cdrom\ device. This structure is conceptually connected to the major
+ CD-ROM device. This structure is conceptually connected to the major
number of the device (although some drivers may have different
major numbers, as is the case for the IDE driver).
-\item[$cdrom_device_info$]
- This structure contains information about a particular \cdrom\ drive,
+
+cdrom_device_info
+ This structure contains information about a particular CD-ROM drive,
such as its device name, speed, etc. This structure is conceptually
connected to the minor number of the device.
-\end{description}
-Registering a particular \cdrom\ drive with the \UCD\ is done by the
-low-level device driver though a call to:
-$$register_cdrom(struct\ cdrom_device_info * <device>_info)
-$$
-The device information structure, $<device>_info$, contains all the
+Registering a particular CD-ROM drive with the Uniform CD-ROM Driver
+is done by the low-level device driver though a call to::
+
+ register_cdrom(struct cdrom_device_info * <device>_info)
+
+The device information structure, *<device>_info*, contains all the
information needed for the kernel to interface with the low-level
-\cdrom\ device driver. One of the most important entries in this
-structure is a pointer to the $cdrom_device_ops$ structure of the
+CD-ROM device driver. One of the most important entries in this
+structure is a pointer to the *cdrom_device_ops* structure of the
low-level driver.
-The device operations structure, $cdrom_device_ops$, contains a list
+The device operations structure, *cdrom_device_ops*, contains a list
of pointers to the functions which are implemented in the low-level
-device driver. When \cdromc\ accesses a \cdrom\ device, it does it
+device driver. When `cdrom.c` accesses a CD-ROM device, it does it
through the functions in this structure. It is impossible to know all
-the capabilities of future \cdrom\ drives, so it is expected that this
+the capabilities of future CD-ROM drives, so it is expected that this
list may need to be expanded from time to time as new technologies are
developed. For example, CD-R and CD-R/W drives are beginning to become
popular, and support will soon need to be added for them. For now, the
-current $struct$ is:
-$$
-\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&
- $/*$ \rm# $*/$\hfil\cr
-struct& cdrom_device_ops\ \{ \hidewidth\cr
- &int& (* open)(struct\ cdrom_device_info *, int)\cr
- &void& (* release)(struct\ cdrom_device_info *);\cr
- &int& (* drive_status)(struct\ cdrom_device_info *, int);\cr
- &unsigned\ int& (* check_events)(struct\ cdrom_device_info *, unsigned\ int, int);\cr
- &int& (* media_changed)(struct\ cdrom_device_info *, int);\cr
- &int& (* tray_move)(struct\ cdrom_device_info *, int);\cr
- &int& (* lock_door)(struct\ cdrom_device_info *, int);\cr
- &int& (* select_speed)(struct\ cdrom_device_info *, int);\cr
- &int& (* select_disc)(struct\ cdrom_device_info *, int);\cr
- &int& (* get_last_session) (struct\ cdrom_device_info *,
- struct\ cdrom_multisession *{});\cr
- &int& (* get_mcn)(struct\ cdrom_device_info *, struct\ cdrom_mcn *{});\cr
- &int& (* reset)(struct\ cdrom_device_info *);\cr
- &int& (* audio_ioctl)(struct\ cdrom_device_info *, unsigned\ int,
- void *{});\cr
-\noalign{\medskip}
- &const\ int& capability;& capability flags \cr
- &int& (* generic_packet)(struct\ cdrom_device_info *, struct\ packet_command *{});\cr
-\};\cr
-}
-$$
+current *struct* is::
+
+ struct cdrom_device_ops {
+ int (*open)(struct cdrom_device_info *, int)
+ void (*release)(struct cdrom_device_info *);
+ int (*drive_status)(struct cdrom_device_info *, int);
+ unsigned int (*check_events)(struct cdrom_device_info *,
+ unsigned int, int);
+ int (*media_changed)(struct cdrom_device_info *, int);
+ int (*tray_move)(struct cdrom_device_info *, int);
+ int (*lock_door)(struct cdrom_device_info *, int);
+ int (*select_speed)(struct cdrom_device_info *, int);
+ int (*select_disc)(struct cdrom_device_info *, int);
+ int (*get_last_session) (struct cdrom_device_info *,
+ struct cdrom_multisession *);
+ int (*get_mcn)(struct cdrom_device_info *, struct cdrom_mcn *);
+ int (*reset)(struct cdrom_device_info *);
+ int (*audio_ioctl)(struct cdrom_device_info *,
+ unsigned int, void *);
+ const int capability; /* capability flags */
+ int (*generic_packet)(struct cdrom_device_info *,
+ struct packet_command *);
+ };
+
When a low-level device driver implements one of these capabilities,
-it should add a function pointer to this $struct$. When a particular
-function is not implemented, however, this $struct$ should contain a
-NULL instead. The $capability$ flags specify the capabilities of the
-\cdrom\ hardware and/or low-level \cdrom\ driver when a \cdrom\ drive
-is registered with the \UCD.
+it should add a function pointer to this *struct*. When a particular
+function is not implemented, however, this *struct* should contain a
+NULL instead. The *capability* flags specify the capabilities of the
+CD-ROM hardware and/or low-level CD-ROM driver when a CD-ROM drive
+is registered with the Uniform CD-ROM Driver.
Note that most functions have fewer parameters than their
-$blkdev_fops$ counterparts. This is because very little of the
-information in the structures $inode$ and $file$ is used. For most
-drivers, the main parameter is the $struct$ $cdrom_device_info$, from
+*blkdev_fops* counterparts. This is because very little of the
+information in the structures *inode* and *file* is used. For most
+drivers, the main parameter is the *struct* *cdrom_device_info*, from
which the major and minor number can be extracted. (Most low-level
-\cdrom\ drivers don't even look at the major and minor number though,
+CD-ROM drivers don't even look at the major and minor number though,
since many of them only support one device.) This will be available
-through $dev$ in $cdrom_device_info$ described below.
+through *dev* in *cdrom_device_info* described below.
The drive-specific, minor-like information that is registered with
-\cdromc, currently contains the following fields:
-$$
-\halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&
- $/*$ \rm# $*/$\hfil\cr
-struct& cdrom_device_info\ \{ \hidewidth\cr
- & const\ struct\ cdrom_device_ops *& ops;& device operations for this major\cr
- & struct\ list_head& list;& linked list of all device_info\cr
- & struct\ gendisk *& disk;& matching block layer disk\cr
- & void *& handle;& driver-dependent data\cr
-\noalign{\medskip}
- & int& mask;& mask of capability: disables them \cr
- & int& speed;& maximum speed for reading data \cr
- & int& capacity;& number of discs in a jukebox \cr
-\noalign{\medskip}
- &unsigned\ int& options : 30;& options flags \cr
- &unsigned& mc_flags : 2;& media-change buffer flags \cr
- &unsigned\ int& vfs_events;& cached events for vfs path\cr
- &unsigned\ int& ioctl_events;& cached events for ioctl path\cr
- & int& use_count;& number of times device is opened\cr
- & char& name[20];& name of the device type\cr
-\noalign{\medskip}
- &__u8& sanyo_slot : 2;& Sanyo 3-CD changer support\cr
- &__u8& keeplocked : 1;& CDROM_LOCKDOOR status\cr
- &__u8& reserved : 5;& not used yet\cr
- & int& cdda_method;& see CDDA_* flags\cr
- &__u8& last_sense;& saves last sense key\cr
- &__u8& media_written;& dirty flag, DVD+RW bookkeeping\cr
- &unsigned\ short& mmc3_profile;& current MMC3 profile\cr
- & int& for_data;& unknown:TBD\cr
- & int\ (* exit)\ (struct\ cdrom_device_info *);&& unknown:TBD\cr
- & int& mrw_mode_page;& which MRW mode page is in use\cr
-\}\cr
-}$$
-Using this $struct$, a linked list of the registered minor devices is
-built, using the $next$ field. The device number, the device operations
+`cdrom.c`, currently contains the following fields::
+
+ struct cdrom_device_info {
+ const struct cdrom_device_ops * ops; /* device operations for this major */
+ struct list_head list; /* linked list of all device_info */
+ struct gendisk * disk; /* matching block layer disk */
+ void * handle; /* driver-dependent data */
+
+ int mask; /* mask of capability: disables them */
+ int speed; /* maximum speed for reading data */
+ int capacity; /* number of discs in a jukebox */
+
+ unsigned int options:30; /* options flags */
+ unsigned mc_flags:2; /* media-change buffer flags */
+ unsigned int vfs_events; /* cached events for vfs path */
+ unsigned int ioctl_events; /* cached events for ioctl path */
+ int use_count; /* number of times device is opened */
+ char name[20]; /* name of the device type */
+
+ __u8 sanyo_slot : 2; /* Sanyo 3-CD changer support */
+ __u8 keeplocked : 1; /* CDROM_LOCKDOOR status */
+ __u8 reserved : 5; /* not used yet */
+ int cdda_method; /* see CDDA_* flags */
+ __u8 last_sense; /* saves last sense key */
+ __u8 media_written; /* dirty flag, DVD+RW bookkeeping */
+ unsigned short mmc3_profile; /* current MMC3 profile */
+ int for_data; /* unknown:TBD */
+ int (*exit)(struct cdrom_device_info *);/* unknown:TBD */
+ int mrw_mode_page; /* which MRW mode page is in use */
+ };
+
+Using this *struct*, a linked list of the registered minor devices is
+built, using the *next* field. The device number, the device operations
struct and specifications of properties of the drive are stored in this
structure.
-The $mask$ flags can be used to mask out some of the capabilities listed
-in $ops\to capability$, if a specific drive doesn't support a feature
-of the driver. The value $speed$ specifies the maximum head-rate of the
-drive, measured in units of normal audio speed (176\,kB/sec raw data or
-150\,kB/sec file system data). The parameters are declared $const$
+The *mask* flags can be used to mask out some of the capabilities listed
+in *ops->capability*, if a specific drive doesn't support a feature
+of the driver. The value *speed* specifies the maximum head-rate of the
+drive, measured in units of normal audio speed (176kB/sec raw data or
+150kB/sec file system data). The parameters are declared *const*
because they describe properties of the drive, which don't change after
registration.
-A few registers contain variables local to the \cdrom\ drive. The
-flags $options$ are used to specify how the general \cdrom\ routines
+A few registers contain variables local to the CD-ROM drive. The
+flags *options* are used to specify how the general CD-ROM routines
should behave. These various flags registers should provide enough
-flexibility to adapt to the different users' wishes (and {\em not\/} the
-`arbitrary' wishes of the author of the low-level device driver, as is
-the case in the old scheme). The register $mc_flags$ is used to buffer
-the information from $media_changed()$ to two separate queues. Other
-data that is specific to a minor drive, can be accessed through $handle$,
+flexibility to adapt to the different users' wishes (and **not** the
+`arbitrary` wishes of the author of the low-level device driver, as is
+the case in the old scheme). The register *mc_flags* is used to buffer
+the information from *media_changed()* to two separate queues. Other
+data that is specific to a minor drive, can be accessed through *handle*,
which can point to a data structure specific to the low-level driver.
-The fields $use_count$, $next$, $options$ and $mc_flags$ need not be
+The fields *use_count*, *next*, *options* and *mc_flags* need not be
initialized.
-The intermediate software layer that \cdromc\ forms will perform some
+The intermediate software layer that `cdrom.c` forms will perform some
additional bookkeeping. The use count of the device (the number of
-processes that have the device opened) is registered in $use_count$. The
-function $cdrom_ioctl()$ will verify the appropriate user-memory regions
+processes that have the device opened) is registered in *use_count*. The
+function *cdrom_ioctl()* will verify the appropriate user-memory regions
for read and write, and in case a location on the CD is transferred,
-it will `sanitize' the format by making requests to the low-level
+it will `sanitize` the format by making requests to the low-level
drivers in a standard format, and translating all formats between the
user-software and low level drivers. This relieves much of the drivers'
memory checking and format checking and translation. Also, the necessary
structures will be declared on the program stack.
The implementation of the functions should be as defined in the
-following sections. Two functions {\em must\/} be implemented, namely
-$open()$ and $release()$. Other functions may be omitted, their
+following sections. Two functions **must** be implemented, namely
+*open()* and *release()*. Other functions may be omitted, their
corresponding capability flags will be cleared upon registration.
Generally, a function returns zero on success and negative on error. A
function call should return only after the command has completed, but of
course waiting for the device should not use processor time.
-\subsection{$Int\ open(struct\ cdrom_device_info * cdi, int\ purpose)$}
+::
-$Open()$ should try to open the device for a specific $purpose$, which
+ int open(struct cdrom_device_info *cdi, int purpose)
+
+*Open()* should try to open the device for a specific *purpose*, which
can be either:
-\begin{itemize}
-\item[0] Open for reading data, as done by {\tt {mount()}} (2), or the
-user commands {\tt {dd}} or {\tt {cat}}.
-\item[1] Open for $ioctl$ commands, as done by audio-CD playing
-programs.
-\end{itemize}
-Notice that any strategic code (closing tray upon $open()$, etc.)\ is
-done by the calling routine in \cdromc, so the low-level routine
+
+- Open for reading data, as done by `mount()` (2), or the
+ user commands `dd` or `cat`.
+- Open for *ioctl* commands, as done by audio-CD playing programs.
+
+Notice that any strategic code (closing tray upon *open()*, etc.) is
+done by the calling routine in `cdrom.c`, so the low-level routine
should only be concerned with proper initialization, such as spinning
-up the disc, etc. % and device-use count
+up the disc, etc.
+::
-\subsection{$Void\ release(struct\ cdrom_device_info * cdi)$}
-
+ void release(struct cdrom_device_info *cdi)
Device-specific actions should be taken such as spinning down the device.
However, strategic actions such as ejection of the tray, or unlocking
-the door, should be left over to the general routine $cdrom_release()$.
-This is the only function returning type $void$.
+the door, should be left over to the general routine *cdrom_release()*.
+This is the only function returning type *void*.
-\subsection{$Int\ drive_status(struct\ cdrom_device_info * cdi, int\ slot_nr)$}
-\label{drive status}
+.. _cdrom_drive_status:
-The function $drive_status$, if implemented, should provide
+::
+
+ int drive_status(struct cdrom_device_info *cdi, int slot_nr)
+
+The function *drive_status*, if implemented, should provide
information on the status of the drive (not the status of the disc,
which may or may not be in the drive). If the drive is not a changer,
-$slot_nr$ should be ignored. In \cdromh\ the possibilities are listed:
-$$
-\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-CDS_NO_INFO& no information available\cr
-CDS_NO_DISC& no disc is inserted, tray is closed\cr
-CDS_TRAY_OPEN& tray is opened\cr
-CDS_DRIVE_NOT_READY& something is wrong, tray is moving?\cr
-CDS_DISC_OK& a disc is loaded and everything is fine\cr
-}
-$$
+*slot_nr* should be ignored. In `cdrom.h` the possibilities are listed::
-\subsection{$Int\ media_changed(struct\ cdrom_device_info * cdi, int\ disc_nr)$}
-This function is very similar to the original function in $struct\
-file_operations$. It returns 1 if the medium of the device $cdi\to
-dev$ has changed since the last call, and 0 otherwise. The parameter
-$disc_nr$ identifies a specific slot in a juke-box, it should be
-ignored for single-disc drives. Note that by `re-routing' this
-function through $cdrom_media_changed()$, we can implement separate
-queues for the VFS and a new $ioctl()$ function that can report device
-changes to software (\eg, an auto-mounting daemon).
+ CDS_NO_INFO /* no information available */
+ CDS_NO_DISC /* no disc is inserted, tray is closed */
+ CDS_TRAY_OPEN /* tray is opened */
+ CDS_DRIVE_NOT_READY /* something is wrong, tray is moving? */
+ CDS_DISC_OK /* a disc is loaded and everything is fine */
-\subsection{$Int\ tray_move(struct\ cdrom_device_info * cdi, int\ position)$}
+::
+
+ int media_changed(struct cdrom_device_info *cdi, int disc_nr)
+
+This function is very similar to the original function in $struct
+file_operations*. It returns 1 if the medium of the device *cdi->dev*
+has changed since the last call, and 0 otherwise. The parameter
+*disc_nr* identifies a specific slot in a juke-box, it should be
+ignored for single-disc drives. Note that by `re-routing` this
+function through *cdrom_media_changed()*, we can implement separate
+queues for the VFS and a new *ioctl()* function that can report device
+changes to software (e. g., an auto-mounting daemon).
+
+::
+
+ int tray_move(struct cdrom_device_info *cdi, int position)
This function, if implemented, should control the tray movement. (No
-other function should control this.) The parameter $position$ controls
+other function should control this.) The parameter *position* controls
the desired direction of movement:
-\begin{itemize}
-\item[0] Close tray
-\item[1] Open tray
-\end{itemize}
+
+- 0 Close tray
+- 1 Open tray
+
This function returns 0 upon success, and a non-zero value upon
error. Note that if the tray is already in the desired position, no
-action need be taken, and the return value should be 0.
+action need be taken, and the return value should be 0.
-\subsection{$Int\ lock_door(struct\ cdrom_device_info * cdi, int\ lock)$}
+::
+
+ int lock_door(struct cdrom_device_info *cdi, int lock)
This function (and no other code) controls locking of the door, if the
-drive allows this. The value of $lock$ controls the desired locking
+drive allows this. The value of *lock* controls the desired locking
state:
-\begin{itemize}
-\item[0] Unlock door, manual opening is allowed
-\item[1] Lock door, tray cannot be ejected manually
-\end{itemize}
+
+- 0 Unlock door, manual opening is allowed
+- 1 Lock door, tray cannot be ejected manually
+
This function returns 0 upon success, and a non-zero value upon
error. Note that if the door is already in the requested state, no
-action need be taken, and the return value should be 0.
+action need be taken, and the return value should be 0.
-\subsection{$Int\ select_speed(struct\ cdrom_device_info * cdi, int\ speed)$}
+::
-Some \cdrom\ drives are capable of changing their head-speed. There
-are several reasons for changing the speed of a \cdrom\ drive. Badly
-pressed \cdrom s may benefit from less-than-maximum head rate. Modern
-\cdrom\ drives can obtain very high head rates (up to $24\times$ is
-common). It has been reported that these drives can make reading
+ int select_speed(struct cdrom_device_info *cdi, int speed)
+
+Some CD-ROM drives are capable of changing their head-speed. There
+are several reasons for changing the speed of a CD-ROM drive. Badly
+pressed CD-ROM s may benefit from less-than-maximum head rate. Modern
+CD-ROM drives can obtain very high head rates (up to *24x* is
+common). It has been reported that these drives can make reading
errors at these high speeds, reducing the speed can prevent data loss
-in these circumstances. Finally, some of these drives can
-make an annoyingly loud noise, which a lower speed may reduce. %Finally,
-%although the audio-low-pass filters probably aren't designed for it,
-%more than real-time playback of audio might be used for high-speed
-%copying of audio tracks.
+in these circumstances. Finally, some of these drives can
+make an annoyingly loud noise, which a lower speed may reduce.
This function specifies the speed at which data is read or audio is
-played back. The value of $speed$ specifies the head-speed of the
-drive, measured in units of standard cdrom speed (176\,kB/sec raw data
-or 150\,kB/sec file system data). So to request that a \cdrom\ drive
-operate at 300\,kB/sec you would call the CDROM_SELECT_SPEED $ioctl$
-with $speed=2$. The special value `0' means `auto-selection', \ie,
+played back. The value of *speed* specifies the head-speed of the
+drive, measured in units of standard cdrom speed (176kB/sec raw data
+or 150kB/sec file system data). So to request that a CD-ROM drive
+operate at 300kB/sec you would call the CDROM_SELECT_SPEED *ioctl*
+with *speed=2*. The special value `0` means `auto-selection`, i. e.,
maximum data-rate or real-time audio rate. If the drive doesn't have
-this `auto-selection' capability, the decision should be made on the
+this `auto-selection` capability, the decision should be made on the
current disc loaded and the return value should be positive. A negative
return value indicates an error.
-\subsection{$Int\ select_disc(struct\ cdrom_device_info * cdi, int\ number)$}
+::
+
+ int select_disc(struct cdrom_device_info *cdi, int number)
If the drive can store multiple discs (a juke-box) this function
will perform disc selection. It should return the number of the
selected disc on success, a negative value on error. Currently, only
the ide-cd driver supports this functionality.
-\subsection{$Int\ get_last_session(struct\ cdrom_device_info * cdi, struct\
- cdrom_multisession * ms_info)$}
+::
-This function should implement the old corresponding $ioctl()$. For
-device $cdi\to dev$, the start of the last session of the current disc
-should be returned in the pointer argument $ms_info$. Note that
-routines in \cdromc\ have sanitized this argument: its requested
-format will {\em always\/} be of the type $CDROM_LBA$ (linear block
+ int get_last_session(struct cdrom_device_info *cdi,
+ struct cdrom_multisession *ms_info)
+
+This function should implement the old corresponding *ioctl()*. For
+device *cdi->dev*, the start of the last session of the current disc
+should be returned in the pointer argument *ms_info*. Note that
+routines in `cdrom.c` have sanitized this argument: its requested
+format will **always** be of the type *CDROM_LBA* (linear block
addressing mode), whatever the calling software requested. But
sanitization goes even further: the low-level implementation may
-return the requested information in $CDROM_MSF$ format if it wishes so
-(setting the $ms_info\rightarrow addr_format$ field appropriately, of
-course) and the routines in \cdromc\ will make the transformation if
+return the requested information in *CDROM_MSF* format if it wishes so
+(setting the *ms_info->addr_format* field appropriately, of
+course) and the routines in `cdrom.c` will make the transformation if
necessary. The return value is 0 upon success.
-\subsection{$Int\ get_mcn(struct\ cdrom_device_info * cdi, struct\
- cdrom_mcn * mcn)$}
+::
-Some discs carry a `Media Catalog Number' (MCN), also called
-`Universal Product Code' (UPC). This number should reflect the number
+ int get_mcn(struct cdrom_device_info *cdi,
+ struct cdrom_mcn *mcn)
+
+Some discs carry a `Media Catalog Number` (MCN), also called
+`Universal Product Code` (UPC). This number should reflect the number
that is generally found in the bar-code on the product. Unfortunately,
the few discs that carry such a number on the disc don't even use the
same format. The return argument to this function is a pointer to a
-pre-declared memory region of type $struct\ cdrom_mcn$. The MCN is
+pre-declared memory region of type *struct cdrom_mcn*. The MCN is
expected as a 13-character string, terminated by a null-character.
-\subsection{$Int\ reset(struct\ cdrom_device_info * cdi)$}
+::
+
+ int reset(struct cdrom_device_info *cdi)
This call should perform a hard-reset on the drive (although in
circumstances that a hard-reset is necessary, a drive may very well not
@@ -491,536 +483,581 @@ caller only after the drive has finished resetting. If the drive is no
longer listening, it may be wise for the underlying low-level cdrom
driver to time out.
-\subsection{$Int\ audio_ioctl(struct\ cdrom_device_info * cdi, unsigned\
- int\ cmd, void * arg)$}
+::
-Some of the \cdrom-$ioctl$s defined in \cdromh\ can be
+ int audio_ioctl(struct cdrom_device_info *cdi,
+ unsigned int cmd, void *arg)
+
+Some of the CD-ROM-\ *ioctl()*\ 's defined in `cdrom.h` can be
implemented by the routines described above, and hence the function
-$cdrom_ioctl$ will use those. However, most $ioctl$s deal with
+*cdrom_ioctl* will use those. However, most *ioctl()*\ 's deal with
audio-control. We have decided to leave these to be accessed through a
-single function, repeating the arguments $cmd$ and $arg$. Note that
-the latter is of type $void*{}$, rather than $unsigned\ long\
-int$. The routine $cdrom_ioctl()$ does do some useful things,
-though. It sanitizes the address format type to $CDROM_MSF$ (Minutes,
+single function, repeating the arguments *cmd* and *arg*. Note that
+the latter is of type *void*, rather than *unsigned long int*.
+The routine *cdrom_ioctl()* does do some useful things,
+though. It sanitizes the address format type to *CDROM_MSF* (Minutes,
Seconds, Frames) for all audio calls. It also verifies the memory
-location of $arg$, and reserves stack-memory for the argument. This
-makes implementation of the $audio_ioctl()$ much simpler than in the
+location of *arg*, and reserves stack-memory for the argument. This
+makes implementation of the *audio_ioctl()* much simpler than in the
old driver scheme. For example, you may look up the function
-$cm206_audio_ioctl()$ in {\tt {cm206.c}} that should be updated with
-this documentation.
+*cm206_audio_ioctl()* `cm206.c` that should be updated with
+this documentation.
-An unimplemented ioctl should return $-ENOSYS$, but a harmless request
-(\eg, $CDROMSTART$) may be ignored by returning 0 (success). Other
+An unimplemented ioctl should return *-ENOSYS*, but a harmless request
+(e. g., *CDROMSTART*) may be ignored by returning 0 (success). Other
errors should be according to the standards, whatever they are. When
-an error is returned by the low-level driver, the \UCD\ tries whenever
-possible to return the error code to the calling program. (We may decide
-to sanitize the return value in $cdrom_ioctl()$ though, in order to
-guarantee a uniform interface to the audio-player software.)
+an error is returned by the low-level driver, the Uniform CD-ROM Driver
+tries whenever possible to return the error code to the calling program.
+(We may decide to sanitize the return value in *cdrom_ioctl()* though, in
+order to guarantee a uniform interface to the audio-player software.)
-\subsection{$Int\ dev_ioctl(struct\ cdrom_device_info * cdi, unsigned\ int\
- cmd, unsigned\ long\ arg)$}
+::
-Some $ioctl$s seem to be specific to certain \cdrom\ drives. That is,
+ int dev_ioctl(struct cdrom_device_info *cdi,
+ unsigned int cmd, unsigned long arg)
+
+Some *ioctl()'s* seem to be specific to certain CD-ROM drives. That is,
they are introduced to service some capabilities of certain drives. In
-fact, there are 6 different $ioctl$s for reading data, either in some
+fact, there are 6 different *ioctl()'s* for reading data, either in some
particular kind of format, or audio data. Not many drives support
reading audio tracks as data, I believe this is because of protection
of copyrights of artists. Moreover, I think that if audio-tracks are
-supported, it should be done through the VFS and not via $ioctl$s. A
+supported, it should be done through the VFS and not via *ioctl()'s*. A
problem here could be the fact that audio-frames are 2352 bytes long,
so either the audio-file-system should ask for 75264 bytes at once
(the least common multiple of 512 and 2352), or the drivers should
bend their backs to cope with this incoherence (to which I would be
-opposed). Furthermore, it is very difficult for the hardware to find
+opposed). Furthermore, it is very difficult for the hardware to find
the exact frame boundaries, since there are no synchronization headers
-in audio frames. Once these issues are resolved, this code should be
-standardized in \cdromc.
-
-Because there are so many $ioctl$s that seem to be introduced to
-satisfy certain drivers,\footnote{Is there software around that
- actually uses these? I'd be interested!} any `non-standard' $ioctl$s
-are routed through the call $dev_ioctl()$. In principle, `private'
-$ioctl$s should be numbered after the device's major number, and not
-the general \cdrom\ $ioctl$ number, {\tt {0x53}}. Currently the
-non-supported $ioctl$s are: {\it CDROMREADMODE1, CDROMREADMODE2,
- CDROMREADAUDIO, CDROMREADRAW, CDROMREADCOOKED, CDROMSEEK,
- CDROMPLAY\-BLK and CDROM\-READALL}.
-
-
-\subsection{\cdrom\ capabilities}
-\label{capability}
-
-Instead of just implementing some $ioctl$ calls, the interface in
-\cdromc\ supplies the possibility to indicate the {\em capabilities\/}
-of a \cdrom\ drive. This can be done by ORing any number of
-capability-constants that are defined in \cdromh\ at the registration
-phase. Currently, the capabilities are any of:
-$$
-\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-CDC_CLOSE_TRAY& can close tray by software control\cr
-CDC_OPEN_TRAY& can open tray\cr
-CDC_LOCK& can lock and unlock the door\cr
-CDC_SELECT_SPEED& can select speed, in units of $\sim$150\,kB/s\cr
-CDC_SELECT_DISC& drive is juke-box\cr
-CDC_MULTI_SESSION& can read sessions $>\rm1$\cr
-CDC_MCN& can read Media Catalog Number\cr
-CDC_MEDIA_CHANGED& can report if disc has changed\cr
-CDC_PLAY_AUDIO& can perform audio-functions (play, pause, etc)\cr
-CDC_RESET& hard reset device\cr
-CDC_IOCTLS& driver has non-standard ioctls\cr
-CDC_DRIVE_STATUS& driver implements drive status\cr
-}
-$$
-The capability flag is declared $const$, to prevent drivers from
+in audio frames. Once these issues are resolved, this code should be
+standardized in `cdrom.c`.
+
+Because there are so many *ioctl()'s* that seem to be introduced to
+satisfy certain drivers [#f2]_, any non-standard *ioctl()*\ s
+are routed through the call *dev_ioctl()*. In principle, `private`
+*ioctl()*\ 's should be numbered after the device's major number, and not
+the general CD-ROM *ioctl* number, `0x53`. Currently the
+non-supported *ioctl()'s* are:
+
+ CDROMREADMODE1, CDROMREADMODE2, CDROMREADAUDIO, CDROMREADRAW,
+ CDROMREADCOOKED, CDROMSEEK, CDROMPLAY-BLK and CDROM-READALL
+
+.. [#f2]
+
+ Is there software around that actually uses these? I'd be interested!
+
+.. _cdrom_capabilities:
+
+CD-ROM capabilities
+-------------------
+
+Instead of just implementing some *ioctl* calls, the interface in
+`cdrom.c` supplies the possibility to indicate the **capabilities**
+of a CD-ROM drive. This can be done by ORing any number of
+capability-constants that are defined in `cdrom.h` at the registration
+phase. Currently, the capabilities are any of::
+
+ CDC_CLOSE_TRAY /* can close tray by software control */
+ CDC_OPEN_TRAY /* can open tray */
+ CDC_LOCK /* can lock and unlock the door */
+ CDC_SELECT_SPEED /* can select speed, in units of * sim*150 ,kB/s */
+ CDC_SELECT_DISC /* drive is juke-box */
+ CDC_MULTI_SESSION /* can read sessions *> rm1* */
+ CDC_MCN /* can read Media Catalog Number */
+ CDC_MEDIA_CHANGED /* can report if disc has changed */
+ CDC_PLAY_AUDIO /* can perform audio-functions (play, pause, etc) */
+ CDC_RESET /* hard reset device */
+ CDC_IOCTLS /* driver has non-standard ioctls */
+ CDC_DRIVE_STATUS /* driver implements drive status */
+
+The capability flag is declared *const*, to prevent drivers from
accidentally tampering with the contents. The capability fags actually
-inform \cdromc\ of what the driver can do. If the drive found
+inform `cdrom.c` of what the driver can do. If the drive found
by the driver does not have the capability, is can be masked out by
-the $cdrom_device_info$ variable $mask$. For instance, the SCSI \cdrom\
-driver has implemented the code for loading and ejecting \cdrom's, and
-hence its corresponding flags in $capability$ will be set. But a SCSI
-\cdrom\ drive might be a caddy system, which can't load the tray, and
-hence for this drive the $cdrom_device_info$ struct will have set
-the $CDC_CLOSE_TRAY$ bit in $mask$.
+the *cdrom_device_info* variable *mask*. For instance, the SCSI CD-ROM
+driver has implemented the code for loading and ejecting CD-ROM's, and
+hence its corresponding flags in *capability* will be set. But a SCSI
+CD-ROM drive might be a caddy system, which can't load the tray, and
+hence for this drive the *cdrom_device_info* struct will have set
+the *CDC_CLOSE_TRAY* bit in *mask*.
-In the file \cdromc\ you will encounter many constructions of the type
-$$\it
-if\ (cdo\rightarrow capability \mathrel\& \mathord{\sim} cdi\rightarrow mask
- \mathrel{\&} CDC_<capability>) \ldots
-$$
-There is no $ioctl$ to set the mask\dots The reason is that
-I think it is better to control the {\em behavior\/} rather than the
-{\em capabilities}.
+In the file `cdrom.c` you will encounter many constructions of the type::
-\subsection{Options}
+ if (cdo->capability & ∼cdi->mask & CDC _⟨capability⟩) ...
-A final flag register controls the {\em behavior\/} of the \cdrom\
+There is no *ioctl* to set the mask... The reason is that
+I think it is better to control the **behavior** rather than the
+**capabilities**.
+
+Options
+-------
+
+A final flag register controls the **behavior** of the CD-ROM
drives, in order to satisfy different users' wishes, hopefully
independently of the ideas of the respective author who happened to
-have made the drive's support available to the \linux\ community. The
-current behavior options are:
-$$
-\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-CDO_AUTO_CLOSE& try to close tray upon device $open()$\cr
-CDO_AUTO_EJECT& try to open tray on last device $close()$\cr
-CDO_USE_FFLAGS& use $file_pointer\rightarrow f_flags$ to indicate
- purpose for $open()$\cr
-CDO_LOCK& try to lock door if device is opened\cr
-CDO_CHECK_TYPE& ensure disc type is data if opened for data\cr
-}
-$$
+have made the drive's support available to the Linux community. The
+current behavior options are::
-The initial value of this register is $CDO_AUTO_CLOSE \mathrel|
-CDO_USE_FFLAGS \mathrel| CDO_LOCK$, reflecting my own view on user
+ CDO_AUTO_CLOSE /* try to close tray upon device open() */
+ CDO_AUTO_EJECT /* try to open tray on last device close() */
+ CDO_USE_FFLAGS /* use file_pointer->f_flags to indicate purpose for open() */
+ CDO_LOCK /* try to lock door if device is opened */
+ CDO_CHECK_TYPE /* ensure disc type is data if opened for data */
+
+The initial value of this register is
+`CDO_AUTO_CLOSE | CDO_USE_FFLAGS | CDO_LOCK`, reflecting my own view on user
interface and software standards. Before you protest, there are two
-new $ioctl$s implemented in \cdromc, that allow you to control the
-behavior by software. These are:
-$$
-\halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
-CDROM_SET_OPTIONS& set options specified in $(int)\ arg$\cr
-CDROM_CLEAR_OPTIONS& clear options specified in $(int)\ arg$\cr
-}
-$$
-One option needs some more explanation: $CDO_USE_FFLAGS$. In the next
+new *ioctl()'s* implemented in `cdrom.c`, that allow you to control the
+behavior by software. These are::
+
+ CDROM_SET_OPTIONS /* set options specified in (int)arg */
+ CDROM_CLEAR_OPTIONS /* clear options specified in (int)arg */
+
+One option needs some more explanation: *CDO_USE_FFLAGS*. In the next
newsection we explain what the need for this option is.
-A software package {\tt setcd}, available from the Debian distribution
-and {\tt sunsite.unc.edu}, allows user level control of these flags.
+A software package `setcd`, available from the Debian distribution
+and `sunsite.unc.edu`, allows user level control of these flags.
-\newsection{The need to know the purpose of opening the \cdrom\ device}
-Traditionally, Unix devices can be used in two different `modes',
+The need to know the purpose of opening the CD-ROM device
+=========================================================
+
+Traditionally, Unix devices can be used in two different `modes`,
either by reading/writing to the device file, or by issuing
-controlling commands to the device, by the device's $ioctl()$
-call. The problem with \cdrom\ drives, is that they can be used for
+controlling commands to the device, by the device's *ioctl()*
+call. The problem with CD-ROM drives, is that they can be used for
two entirely different purposes. One is to mount removable
-file systems, \cdrom s, the other is to play audio CD's. Audio commands
-are implemented entirely through $ioctl$s, presumably because the
+file systems, CD-ROM's, the other is to play audio CD's. Audio commands
+are implemented entirely through *ioctl()\'s*, presumably because the
first implementation (SUN?) has been such. In principle there is
-nothing wrong with this, but a good control of the `CD player' demands
-that the device can {\em always\/} be opened in order to give the
-$ioctl$ commands, regardless of the state the drive is in.
+nothing wrong with this, but a good control of the `CD player` demands
+that the device can **always** be opened in order to give the
+*ioctl* commands, regardless of the state the drive is in.
On the other hand, when used as a removable-media disc drive (what the
-original purpose of \cdrom s is) we would like to make sure that the
+original purpose of CD-ROM s is) we would like to make sure that the
disc drive is ready for operation upon opening the device. In the old
-scheme, some \cdrom\ drivers don't do any integrity checking, resulting
+scheme, some CD-ROM drivers don't do any integrity checking, resulting
in a number of i/o errors reported by the VFS to the kernel when an
-attempt for mounting a \cdrom\ on an empty drive occurs. This is not a
-particularly elegant way to find out that there is no \cdrom\ inserted;
+attempt for mounting a CD-ROM on an empty drive occurs. This is not a
+particularly elegant way to find out that there is no CD-ROM inserted;
it more-or-less looks like the old IBM-PC trying to read an empty floppy
drive for a couple of seconds, after which the system complains it
-can't read from it. Nowadays we can {\em sense\/} the existence of a
+can't read from it. Nowadays we can **sense** the existence of a
removable medium in a drive, and we believe we should exploit that
fact. An integrity check on opening of the device, that verifies the
-availability of a \cdrom\ and its correct type (data), would be
+availability of a CD-ROM and its correct type (data), would be
desirable.
-These two ways of using a \cdrom\ drive, principally for data and
+These two ways of using a CD-ROM drive, principally for data and
secondarily for playing audio discs, have different demands for the
-behavior of the $open()$ call. Audio use simply wants to open the
+behavior of the *open()* call. Audio use simply wants to open the
device in order to get a file handle which is needed for issuing
-$ioctl$ commands, while data use wants to open for correct and
+*ioctl* commands, while data use wants to open for correct and
reliable data transfer. The only way user programs can indicate what
-their {\em purpose\/} of opening the device is, is through the $flags$
-parameter (see {\tt {open(2)}}). For \cdrom\ devices, these flags aren't
+their *purpose* of opening the device is, is through the *flags*
+parameter (see `open(2)`). For CD-ROM devices, these flags aren't
implemented (some drivers implement checking for write-related flags,
but this is not strictly necessary if the device file has correct
permission flags). Most option flags simply don't make sense to
-\cdrom\ devices: $O_CREAT$, $O_NOCTTY$, $O_TRUNC$, $O_APPEND$, and
-$O_SYNC$ have no meaning to a \cdrom.
+CD-ROM devices: *O_CREAT*, *O_NOCTTY*, *O_TRUNC*, *O_APPEND*, and
+*O_SYNC* have no meaning to a CD-ROM.
-We therefore propose to use the flag $O_NONBLOCK$ to indicate
-that the device is opened just for issuing $ioctl$
-commands. Strictly, the meaning of $O_NONBLOCK$ is that opening and
+We therefore propose to use the flag *O_NONBLOCK* to indicate
+that the device is opened just for issuing *ioctl*
+commands. Strictly, the meaning of *O_NONBLOCK* is that opening and
subsequent calls to the device don't cause the calling process to
-wait. We could interpret this as ``don't wait until someone has
-inserted some valid data-\cdrom.'' Thus, our proposal of the
-implementation for the $open()$ call for \cdrom s is:
-\begin{itemize}
-\item If no other flags are set than $O_RDONLY$, the device is opened
-for data transfer, and the return value will be 0 only upon successful
-initialization of the transfer. The call may even induce some actions
-on the \cdrom, such as closing the tray.
-\item If the option flag $O_NONBLOCK$ is set, opening will always be
-successful, unless the whole device doesn't exist. The drive will take
-no actions whatsoever.
-\end{itemize}
+wait. We could interpret this as don't wait until someone has
+inserted some valid data-CD-ROM. Thus, our proposal of the
+implementation for the *open()* call for CD-ROM s is:
-\subsection{And what about standards?}
+- If no other flags are set than *O_RDONLY*, the device is opened
+ for data transfer, and the return value will be 0 only upon successful
+ initialization of the transfer. The call may even induce some actions
+ on the CD-ROM, such as closing the tray.
+- If the option flag *O_NONBLOCK* is set, opening will always be
+ successful, unless the whole device doesn't exist. The drive will take
+ no actions whatsoever.
+
+And what about standards?
+-------------------------
You might hesitate to accept this proposal as it comes from the
-\linux\ community, and not from some standardizing institute. What
+Linux community, and not from some standardizing institute. What
about SUN, SGI, HP and all those other Unix and hardware vendors?
Well, these companies are in the lucky position that they generally
control both the hardware and software of their supported products,
and are large enough to set their own standard. They do not have to
deal with a dozen or more different, competing hardware
-configurations.\footnote{Incidentally, I think that SUN's approach to
-mounting \cdrom s is very good in origin: under Solaris a
-volume-daemon automatically mounts a newly inserted \cdrom\ under {\tt
-{/cdrom/$<volume-name>$/}}. In my opinion they should have pushed this
-further and have {\em every\/} \cdrom\ on the local area network be
-mounted at the similar location, \ie, no matter in which particular
-machine you insert a \cdrom, it will always appear at the same
-position in the directory tree, on every system. When I wanted to
-implement such a user-program for \linux, I came across the
-differences in behavior of the various drivers, and the need for an
-$ioctl$ informing about media changes.}
-
-We believe that using $O_NONBLOCK$ to indicate that a device is being opened
-for $ioctl$ commands only can be easily introduced in the \linux\
+configurations\ [#f3]_.
+
+.. [#f3]
+
+ Incidentally, I think that SUN's approach to mounting CD-ROM s is very
+ good in origin: under Solaris a volume-daemon automatically mounts a
+ newly inserted CD-ROM under `/cdrom/*<volume-name>*`.
+
+ In my opinion they should have pushed this
+ further and have **every** CD-ROM on the local area network be
+ mounted at the similar location, i. e., no matter in which particular
+ machine you insert a CD-ROM, it will always appear at the same
+ position in the directory tree, on every system. When I wanted to
+ implement such a user-program for Linux, I came across the
+ differences in behavior of the various drivers, and the need for an
+ *ioctl* informing about media changes.
+
+We believe that using *O_NONBLOCK* to indicate that a device is being opened
+for *ioctl* commands only can be easily introduced in the Linux
community. All the CD-player authors will have to be informed, we can
-even send in our own patches to the programs. The use of $O_NONBLOCK$
+even send in our own patches to the programs. The use of *O_NONBLOCK*
has most likely no influence on the behavior of the CD-players on
-other operating systems than \linux. Finally, a user can always revert
-to old behavior by a call to $ioctl(file_descriptor, CDROM_CLEAR_OPTIONS,
-CDO_USE_FFLAGS)$.
+other operating systems than Linux. Finally, a user can always revert
+to old behavior by a call to
+*ioctl(file_descriptor, CDROM_CLEAR_OPTIONS, CDO_USE_FFLAGS)*.
-\subsection{The preferred strategy of $open()$}
+The preferred strategy of *open()*
+----------------------------------
-The routines in \cdromc\ are designed in such a way that run-time
-configuration of the behavior of \cdrom\ devices (of {\em any\/} type)
-can be carried out, by the $CDROM_SET/CLEAR_OPTIONS$ $ioctls$. Thus, various
+The routines in `cdrom.c` are designed in such a way that run-time
+configuration of the behavior of CD-ROM devices (of **any** type)
+can be carried out, by the *CDROM_SET/CLEAR_OPTIONS* *ioctls*. Thus, various
modes of operation can be set:
-\begin{description}
-\item[$CDO_AUTO_CLOSE \mathrel| CDO_USE_FFLAGS \mathrel| CDO_LOCK$] This
-is the default setting. (With $CDO_CHECK_TYPE$ it will be better, in the
-future.) If the device is not yet opened by any other process, and if
-the device is being opened for data ($O_NONBLOCK$ is not set) and the
-tray is found to be open, an attempt to close the tray is made. Then,
-it is verified that a disc is in the drive and, if $CDO_CHECK_TYPE$ is
-set, that it contains tracks of type `data mode 1.' Only if all tests
-are passed is the return value zero. The door is locked to prevent file
-system corruption. If the drive is opened for audio ($O_NONBLOCK$ is
-set), no actions are taken and a value of 0 will be returned.
-\item[$CDO_AUTO_CLOSE \mathrel| CDO_AUTO_EJECT \mathrel| CDO_LOCK$] This
-mimics the behavior of the current sbpcd-driver. The option flags are
-ignored, the tray is closed on the first open, if necessary. Similarly,
-the tray is opened on the last release, \ie, if a \cdrom\ is unmounted,
-it is automatically ejected, such that the user can replace it.
-\end{description}
+
+`CDO_AUTO_CLOSE | CDO_USE_FFLAGS | CDO_LOCK`
+ This is the default setting. (With *CDO_CHECK_TYPE* it will be better, in
+ the future.) If the device is not yet opened by any other process, and if
+ the device is being opened for data (*O_NONBLOCK* is not set) and the
+ tray is found to be open, an attempt to close the tray is made. Then,
+ it is verified that a disc is in the drive and, if *CDO_CHECK_TYPE* is
+ set, that it contains tracks of type `data mode 1`. Only if all tests
+ are passed is the return value zero. The door is locked to prevent file
+ system corruption. If the drive is opened for audio (*O_NONBLOCK* is
+ set), no actions are taken and a value of 0 will be returned.
+
+`CDO_AUTO_CLOSE | CDO_AUTO_EJECT | CDO_LOCK`
+ This mimics the behavior of the current sbpcd-driver. The option flags are
+ ignored, the tray is closed on the first open, if necessary. Similarly,
+ the tray is opened on the last release, i. e., if a CD-ROM is unmounted,
+ it is automatically ejected, such that the user can replace it.
+
We hope that these option can convince everybody (both driver
-maintainers and user program developers) to adopt the new \cdrom\
+maintainers and user program developers) to adopt the new CD-ROM
driver scheme and option flag interpretation.
-\newsection{Description of routines in \cdromc}
+Description of routines in `cdrom.c`
+====================================
-Only a few routines in \cdromc\ are exported to the drivers. In this
+Only a few routines in `cdrom.c` are exported to the drivers. In this
new section we will discuss these, as well as the functions that `take
-over' the \cdrom\ interface to the kernel. The header file belonging
-to \cdromc\ is called \cdromh. Formerly, some of the contents of this
-file were placed in the file {\tt {ucdrom.h}}, but this file has now been
-merged back into \cdromh.
+over' the CD-ROM interface to the kernel. The header file belonging
+to `cdrom.c` is called `cdrom.h`. Formerly, some of the contents of this
+file were placed in the file `ucdrom.h`, but this file has now been
+merged back into `cdrom.h`.
-\subsection{$Struct\ file_operations\ cdrom_fops$}
+::
-The contents of this structure were described in section~\ref{cdrom.c}.
-A pointer to this structure is assigned to the $fops$ field
-of the $struct gendisk$.
+ struct file_operations cdrom_fops
-\subsection{$Int\ register_cdrom( struct\ cdrom_device_info\ * cdi)$}
+The contents of this structure were described in cdrom_api_.
+A pointer to this structure is assigned to the *fops* field
+of the *struct gendisk*.
-This function is used in about the same way one registers $cdrom_fops$
+::
+
+ int register_cdrom(struct cdrom_device_info *cdi)
+
+This function is used in about the same way one registers *cdrom_fops*
with the kernel, the device operations and information structures,
-as described in section~\ref{cdrom.c}, should be registered with the
-\UCD:
-$$
-register_cdrom(\&<device>_info));
-$$
+as described in cdrom_api_, should be registered with the
+Uniform CD-ROM Driver::
+
+ register_cdrom(&<device>_info);
+
+
This function returns zero upon success, and non-zero upon
-failure. The structure $<device>_info$ should have a pointer to the
-driver's $<device>_dops$, as in
-$$
-\vbox{\halign{&$#$\hfil\cr
-struct\ &cdrom_device_info\ <device>_info = \{\cr
-& <device>_dops;\cr
-&\ldots\cr
-\}\cr
-}}$$
-Note that a driver must have one static structure, $<device>_dops$, while
-it may have as many structures $<device>_info$ as there are minor devices
-active. $Register_cdrom()$ builds a linked list from these.
+failure. The structure *<device>_info* should have a pointer to the
+driver's *<device>_dops*, as in::
-\subsection{$Void\ unregister_cdrom(struct\ cdrom_device_info * cdi)$}
+ struct cdrom_device_info <device>_info = {
+ <device>_dops;
+ ...
+ }
-Unregistering device $cdi$ with minor number $MINOR(cdi\to dev)$ removes
+Note that a driver must have one static structure, *<device>_dops*, while
+it may have as many structures *<device>_info* as there are minor devices
+active. *Register_cdrom()* builds a linked list from these.
+
+
+::
+
+ void unregister_cdrom(struct cdrom_device_info *cdi)
+
+Unregistering device *cdi* with minor number *MINOR(cdi->dev)* removes
the minor device from the list. If it was the last registered minor for
the low-level driver, this disconnects the registered device-operation
-routines from the \cdrom\ interface. This function returns zero upon
+routines from the CD-ROM interface. This function returns zero upon
success, and non-zero upon failure.
-\subsection{$Int\ cdrom_open(struct\ inode * ip, struct\ file * fp)$}
+::
+
+ int cdrom_open(struct inode * ip, struct file * fp)
This function is not called directly by the low-level drivers, it is
-listed in the standard $cdrom_fops$. If the VFS opens a file, this
+listed in the standard *cdrom_fops*. If the VFS opens a file, this
function becomes active. A strategy is implemented in this routine,
taking care of all capabilities and options that are set in the
-$cdrom_device_ops$ connected to the device. Then, the program flow is
-transferred to the device_dependent $open()$ call.
+*cdrom_device_ops* connected to the device. Then, the program flow is
+transferred to the device_dependent *open()* call.
-\subsection{$Void\ cdrom_release(struct\ inode *ip, struct\ file
-*fp)$}
+::
-This function implements the reverse-logic of $cdrom_open()$, and then
-calls the device-dependent $release()$ routine. When the use-count has
-reached 0, the allocated buffers are flushed by calls to $sync_dev(dev)$
-and $invalidate_buffers(dev)$.
+ void cdrom_release(struct inode *ip, struct file *fp)
+This function implements the reverse-logic of *cdrom_open()*, and then
+calls the device-dependent *release()* routine. When the use-count has
+reached 0, the allocated buffers are flushed by calls to *sync_dev(dev)*
+and *invalidate_buffers(dev)*.
-\subsection{$Int\ cdrom_ioctl(struct\ inode *ip, struct\ file *fp,
-unsigned\ int\ cmd, unsigned\ long\ arg)$}
-\label{cdrom-ioctl}
-This function handles all the standard $ioctl$ requests for \cdrom\
+.. _cdrom_ioctl:
+
+::
+
+ int cdrom_ioctl(struct inode *ip, struct file *fp,
+ unsigned int cmd, unsigned long arg)
+
+This function handles all the standard *ioctl* requests for CD-ROM
devices in a uniform way. The different calls fall into three
-categories: $ioctl$s that can be directly implemented by device
-operations, ones that are routed through the call $audio_ioctl()$, and
+categories: *ioctl()'s* that can be directly implemented by device
+operations, ones that are routed through the call *audio_ioctl()*, and
the remaining ones, that are presumable device-dependent. Generally, a
negative return value indicates an error.
-\subsubsection{Directly implemented $ioctl$s}
-\label{ioctl-direct}
+Directly implemented *ioctl()'s*
+--------------------------------
-The following `old' \cdrom-$ioctl$s are implemented by directly
-calling device-operations in $cdrom_device_ops$, if implemented and
+The following `old` CD-ROM *ioctl()*\ 's are implemented by directly
+calling device-operations in *cdrom_device_ops*, if implemented and
not masked:
-\begin{description}
-\item[CDROMMULTISESSION] Requests the last session on a \cdrom.
-\item[CDROMEJECT] Open tray.
-\item[CDROMCLOSETRAY] Close tray.
-\item[CDROMEJECT_SW] If $arg\not=0$, set behavior to auto-close (close
-tray on first open) and auto-eject (eject on last release), otherwise
-set behavior to non-moving on $open()$ and $release()$ calls.
-\item[CDROM_GET_MCN] Get the Media Catalog Number from a CD.
-\end{description}
-\subsubsection{$Ioctl$s routed through $audio_ioctl()$}
-\label{ioctl-audio}
+`CDROMMULTISESSION`
+ Requests the last session on a CD-ROM.
+`CDROMEJECT`
+ Open tray.
+`CDROMCLOSETRAY`
+ Close tray.
+`CDROMEJECT_SW`
+ If *arg\not=0*, set behavior to auto-close (close
+ tray on first open) and auto-eject (eject on last release), otherwise
+ set behavior to non-moving on *open()* and *release()* calls.
+`CDROM_GET_MCN`
+ Get the Media Catalog Number from a CD.
-The following set of $ioctl$s are all implemented through a call to
-the $cdrom_fops$ function $audio_ioctl()$. Memory checks and
-allocation are performed in $cdrom_ioctl()$, and also sanitization of
-address format ($CDROM_LBA$/$CDROM_MSF$) is done.
-\begin{description}
-\item[CDROMSUBCHNL] Get sub-channel data in argument $arg$ of type $struct\
-cdrom_subchnl *{}$.
-\item[CDROMREADTOCHDR] Read Table of Contents header, in $arg$ of type
-$struct\ cdrom_tochdr *{}$.
-\item[CDROMREADTOCENTRY] Read a Table of Contents entry in $arg$ and
-specified by $arg$ of type $struct\ cdrom_tocentry *{}$.
-\item[CDROMPLAYMSF] Play audio fragment specified in Minute, Second,
-Frame format, delimited by $arg$ of type $struct\ cdrom_msf *{}$.
-\item[CDROMPLAYTRKIND] Play audio fragment in track-index format
-delimited by $arg$ of type $struct\ \penalty-1000 cdrom_ti *{}$.
-\item[CDROMVOLCTRL] Set volume specified by $arg$ of type $struct\
-cdrom_volctrl *{}$.
-\item[CDROMVOLREAD] Read volume into by $arg$ of type $struct\
-cdrom_volctrl *{}$.
-\item[CDROMSTART] Spin up disc.
-\item[CDROMSTOP] Stop playback of audio fragment.
-\item[CDROMPAUSE] Pause playback of audio fragment.
-\item[CDROMRESUME] Resume playing.
-\end{description}
+*Ioctl*s routed through *audio_ioctl()*
+---------------------------------------
-\subsubsection{New $ioctl$s in \cdromc}
+The following set of *ioctl()'s* are all implemented through a call to
+the *cdrom_fops* function *audio_ioctl()*. Memory checks and
+allocation are performed in *cdrom_ioctl()*, and also sanitization of
+address format (*CDROM_LBA*/*CDROM_MSF*) is done.
-The following $ioctl$s have been introduced to allow user programs to
-control the behavior of individual \cdrom\ devices. New $ioctl$
+`CDROMSUBCHNL`
+ Get sub-channel data in argument *arg* of type
+ `struct cdrom_subchnl *`.
+`CDROMREADTOCHDR`
+ Read Table of Contents header, in *arg* of type
+ `struct cdrom_tochdr *`.
+`CDROMREADTOCENTRY`
+ Read a Table of Contents entry in *arg* and specified by *arg*
+ of type `struct cdrom_tocentry *`.
+`CDROMPLAYMSF`
+ Play audio fragment specified in Minute, Second, Frame format,
+ delimited by *arg* of type `struct cdrom_msf *`.
+`CDROMPLAYTRKIND`
+ Play audio fragment in track-index format delimited by *arg*
+ of type `struct cdrom_ti *`.
+`CDROMVOLCTRL`
+ Set volume specified by *arg* of type `struct cdrom_volctrl *`.
+`CDROMVOLREAD`
+ Read volume into by *arg* of type `struct cdrom_volctrl *`.
+`CDROMSTART`
+ Spin up disc.
+`CDROMSTOP`
+ Stop playback of audio fragment.
+`CDROMPAUSE`
+ Pause playback of audio fragment.
+`CDROMRESUME`
+ Resume playing.
+
+New *ioctl()'s* in `cdrom.c`
+----------------------------
+
+The following *ioctl()'s* have been introduced to allow user programs to
+control the behavior of individual CD-ROM devices. New *ioctl*
commands can be identified by the underscores in their names.
-\begin{description}
-\item[CDROM_SET_OPTIONS] Set options specified by $arg$. Returns the
-option flag register after modification. Use $arg = \rm0$ for reading
-the current flags.
-\item[CDROM_CLEAR_OPTIONS] Clear options specified by $arg$. Returns
- the option flag register after modification.
-\item[CDROM_SELECT_SPEED] Select head-rate speed of disc specified as
- by $arg$ in units of standard cdrom speed (176\,kB/sec raw data or
- 150\,kB/sec file system data). The value 0 means `auto-select', \ie,
- play audio discs at real time and data discs at maximum speed. The value
- $arg$ is checked against the maximum head rate of the drive found in the
- $cdrom_dops$.
-\item[CDROM_SELECT_DISC] Select disc numbered $arg$ from a juke-box.
- First disc is numbered 0. The number $arg$ is checked against the
- maximum number of discs in the juke-box found in the $cdrom_dops$.
-\item[CDROM_MEDIA_CHANGED] Returns 1 if a disc has been changed since
- the last call. Note that calls to $cdrom_media_changed$ by the VFS
- are treated by an independent queue, so both mechanisms will detect
- a media change once. For juke-boxes, an extra argument $arg$
- specifies the slot for which the information is given. The special
- value $CDSL_CURRENT$ requests that information about the currently
- selected slot be returned.
-\item[CDROM_DRIVE_STATUS] Returns the status of the drive by a call to
- $drive_status()$. Return values are defined in section~\ref{drive
- status}. Note that this call doesn't return information on the
- current playing activity of the drive; this can be polled through an
- $ioctl$ call to $CDROMSUBCHNL$. For juke-boxes, an extra argument
- $arg$ specifies the slot for which (possibly limited) information is
- given. The special value $CDSL_CURRENT$ requests that information
- about the currently selected slot be returned.
-\item[CDROM_DISC_STATUS] Returns the type of the disc currently in the
- drive. It should be viewed as a complement to $CDROM_DRIVE_STATUS$.
- This $ioctl$ can provide \emph {some} information about the current
- disc that is inserted in the drive. This functionality used to be
- implemented in the low level drivers, but is now carried out
- entirely in \UCD.
-
- The history of development of the CD's use as a carrier medium for
- various digital information has lead to many different disc types.
- This $ioctl$ is useful only in the case that CDs have \emph {only
- one} type of data on them. While this is often the case, it is
- also very common for CDs to have some tracks with data, and some
- tracks with audio. Because this is an existing interface, rather
- than fixing this interface by changing the assumptions it was made
- under, thereby breaking all user applications that use this
- function, the \UCD\ implements this $ioctl$ as follows: If the CD in
- question has audio tracks on it, and it has absolutely no CD-I, XA,
- or data tracks on it, it will be reported as $CDS_AUDIO$. If it has
- both audio and data tracks, it will return $CDS_MIXED$. If there
- are no audio tracks on the disc, and if the CD in question has any
- CD-I tracks on it, it will be reported as $CDS_XA_2_2$. Failing
- that, if the CD in question has any XA tracks on it, it will be
- reported as $CDS_XA_2_1$. Finally, if the CD in question has any
- data tracks on it, it will be reported as a data CD ($CDS_DATA_1$).
- This $ioctl$ can return:
- $$
- \halign{$#$\ \hfil&$/*$ \rm# $*/$\hfil\cr
- CDS_NO_INFO& no information available\cr
- CDS_NO_DISC& no disc is inserted, or tray is opened\cr
- CDS_AUDIO& Audio disc (2352 audio bytes/frame)\cr
- CDS_DATA_1& data disc, mode 1 (2048 user bytes/frame)\cr
- CDS_XA_2_1& mixed data (XA), mode 2, form 1 (2048 user bytes)\cr
- CDS_XA_2_2& mixed data (XA), mode 2, form 1 (2324 user bytes)\cr
- CDS_MIXED& mixed audio/data disc\cr
- }
- $$
- For some information concerning frame layout of the various disc
- types, see a recent version of \cdromh.
+`CDROM_SET_OPTIONS`
+ Set options specified by *arg*. Returns the option flag register
+ after modification. Use *arg = \rm0* for reading the current flags.
+`CDROM_CLEAR_OPTIONS`
+ Clear options specified by *arg*. Returns the option flag register
+ after modification.
+`CDROM_SELECT_SPEED`
+ Select head-rate speed of disc specified as by *arg* in units
+ of standard cdrom speed (176\,kB/sec raw data or
+ 150kB/sec file system data). The value 0 means `auto-select`,
+ i. e., play audio discs at real time and data discs at maximum speed.
+ The value *arg* is checked against the maximum head rate of the
+ drive found in the *cdrom_dops*.
+`CDROM_SELECT_DISC`
+ Select disc numbered *arg* from a juke-box.
-\item[CDROM_CHANGER_NSLOTS] Returns the number of slots in a
- juke-box.
-\item[CDROMRESET] Reset the drive.
-\item[CDROM_GET_CAPABILITY] Returns the $capability$ flags for the
- drive. Refer to section \ref{capability} for more information on
- these flags.
-\item[CDROM_LOCKDOOR] Locks the door of the drive. $arg == \rm0$
- unlocks the door, any other value locks it.
-\item[CDROM_DEBUG] Turns on debugging info. Only root is allowed
- to do this. Same semantics as CDROM_LOCKDOOR.
-\end{description}
+ First disc is numbered 0. The number *arg* is checked against the
+ maximum number of discs in the juke-box found in the *cdrom_dops*.
+`CDROM_MEDIA_CHANGED`
+ Returns 1 if a disc has been changed since the last call.
+ Note that calls to *cdrom_media_changed* by the VFS are treated
+ by an independent queue, so both mechanisms will detect a
+ media change once. For juke-boxes, an extra argument *arg*
+ specifies the slot for which the information is given. The special
+ value *CDSL_CURRENT* requests that information about the currently
+ selected slot be returned.
+`CDROM_DRIVE_STATUS`
+ Returns the status of the drive by a call to
+ *drive_status()*. Return values are defined in cdrom_drive_status_.
+ Note that this call doesn't return information on the
+ current playing activity of the drive; this can be polled through
+ an *ioctl* call to *CDROMSUBCHNL*. For juke-boxes, an extra argument
+ *arg* specifies the slot for which (possibly limited) information is
+ given. The special value *CDSL_CURRENT* requests that information
+ about the currently selected slot be returned.
+`CDROM_DISC_STATUS`
+ Returns the type of the disc currently in the drive.
+ It should be viewed as a complement to *CDROM_DRIVE_STATUS*.
+ This *ioctl* can provide *some* information about the current
+ disc that is inserted in the drive. This functionality used to be
+ implemented in the low level drivers, but is now carried out
+ entirely in Uniform CD-ROM Driver.
-\subsubsection{Device dependent $ioctl$s}
+ The history of development of the CD's use as a carrier medium for
+ various digital information has lead to many different disc types.
+ This *ioctl* is useful only in the case that CDs have \emph {only
+ one} type of data on them. While this is often the case, it is
+ also very common for CDs to have some tracks with data, and some
+ tracks with audio. Because this is an existing interface, rather
+ than fixing this interface by changing the assumptions it was made
+ under, thereby breaking all user applications that use this
+ function, the Uniform CD-ROM Driver implements this *ioctl* as
+ follows: If the CD in question has audio tracks on it, and it has
+ absolutely no CD-I, XA, or data tracks on it, it will be reported
+ as *CDS_AUDIO*. If it has both audio and data tracks, it will
+ return *CDS_MIXED*. If there are no audio tracks on the disc, and
+ if the CD in question has any CD-I tracks on it, it will be
+ reported as *CDS_XA_2_2*. Failing that, if the CD in question
+ has any XA tracks on it, it will be reported as *CDS_XA_2_1*.
+ Finally, if the CD in question has any data tracks on it,
+ it will be reported as a data CD (*CDS_DATA_1*).
-Finally, all other $ioctl$s are passed to the function $dev_ioctl()$,
-if implemented. No memory allocation or verification is carried out.
+ This *ioctl* can return::
-\newsection{How to update your driver}
+ CDS_NO_INFO /* no information available */
+ CDS_NO_DISC /* no disc is inserted, or tray is opened */
+ CDS_AUDIO /* Audio disc (2352 audio bytes/frame) */
+ CDS_DATA_1 /* data disc, mode 1 (2048 user bytes/frame) */
+ CDS_XA_2_1 /* mixed data (XA), mode 2, form 1 (2048 user bytes) */
+ CDS_XA_2_2 /* mixed data (XA), mode 2, form 1 (2324 user bytes) */
+ CDS_MIXED /* mixed audio/data disc */
-\begin{enumerate}
-\item Make a backup of your current driver.
-\item Get hold of the files \cdromc\ and \cdromh, they should be in
+ For some information concerning frame layout of the various disc
+ types, see a recent version of `cdrom.h`.
+
+`CDROM_CHANGER_NSLOTS`
+ Returns the number of slots in a juke-box.
+`CDROMRESET`
+ Reset the drive.
+`CDROM_GET_CAPABILITY`
+ Returns the *capability* flags for the drive. Refer to section
+ cdrom_capabilities_ for more information on these flags.
+`CDROM_LOCKDOOR`
+ Locks the door of the drive. `arg == 0` unlocks the door,
+ any other value locks it.
+`CDROM_DEBUG`
+ Turns on debugging info. Only root is allowed to do this.
+ Same semantics as CDROM_LOCKDOOR.
+
+
+Device dependent *ioctl()'s*
+----------------------------
+
+Finally, all other *ioctl()'s* are passed to the function *dev_ioctl()*,
+if implemented. No memory allocation or verification is carried out.
+
+How to update your driver
+=========================
+
+- Make a backup of your current driver.
+- Get hold of the files `cdrom.c` and `cdrom.h`, they should be in
the directory tree that came with this documentation.
-\item Make sure you include \cdromh.
-\item Change the 3rd argument of $register_blkdev$ from
-$\&<your-drive>_fops$ to $\&cdrom_fops$.
-\item Just after that line, add the following to register with the \UCD:
- $$register_cdrom(\&<your-drive>_info);$$
- Similarly, add a call to $unregister_cdrom()$ at the appropriate place.
-\item Copy an example of the device-operations $struct$ to your
- source, \eg, from {\tt {cm206.c}} $cm206_dops$, and change all
+- Make sure you include `cdrom.h`.
+- Change the 3rd argument of *register_blkdev* from `&<your-drive>_fops`
+ to `&cdrom_fops`.
+- Just after that line, add the following to register with the Uniform
+ CD-ROM Driver::
+
+ register_cdrom(&<your-drive>_info);*
+
+ Similarly, add a call to *unregister_cdrom()* at the appropriate place.
+- Copy an example of the device-operations *struct* to your
+ source, e. g., from `cm206.c` *cm206_dops*, and change all
entries to names corresponding to your driver, or names you just
happen to like. If your driver doesn't support a certain function,
- make the entry $NULL$. At the entry $capability$ you should list all
+ make the entry *NULL*. At the entry *capability* you should list all
capabilities your driver currently supports. If your driver
has a capability that is not listed, please send me a message.
-\item Copy the $cdrom_device_info$ declaration from the same example
+- Copy the *cdrom_device_info* declaration from the same example
driver, and modify the entries according to your needs. If your
driver dynamically determines the capabilities of the hardware, this
- structure should also be declared dynamically.
-\item Implement all functions in your $<device>_dops$ structure,
- according to prototypes listed in \cdromh, and specifications given
- in section~\ref{cdrom.c}. Most likely you have already implemented
+ structure should also be declared dynamically.
+- Implement all functions in your `<device>_dops` structure,
+ according to prototypes listed in `cdrom.h`, and specifications given
+ in cdrom_api_. Most likely you have already implemented
the code in a large part, and you will almost certainly need to adapt the
prototype and return values.
-\item Rename your $<device>_ioctl()$ function to $audio_ioctl$ and
+- Rename your `<device>_ioctl()` function to *audio_ioctl* and
change the prototype a little. Remove entries listed in the first
- part in section~\ref{cdrom-ioctl}, if your code was OK, these are
+ part in cdrom_ioctl_, if your code was OK, these are
just calls to the routines you adapted in the previous step.
-\item You may remove all remaining memory checking code in the
- $audio_ioctl()$ function that deals with audio commands (these are
- listed in the second part of section~\ref{cdrom-ioctl}). There is no
- need for memory allocation either, so most $case$s in the $switch$
- statement look similar to:
- $$
- case\ CDROMREADTOCENTRY\colon get_toc_entry\bigl((struct\
- cdrom_tocentry *{})\ arg\bigr);
- $$
-\item All remaining $ioctl$ cases must be moved to a separate
- function, $<device>_ioctl$, the device-dependent $ioctl$s. Note that
+- You may remove all remaining memory checking code in the
+ *audio_ioctl()* function that deals with audio commands (these are
+ listed in the second part of cdrom_ioctl_. There is no
+ need for memory allocation either, so most *case*s in the *switch*
+ statement look similar to::
+
+ case CDROMREADTOCENTRY:
+ get_toc_entry\bigl((struct cdrom_tocentry *) arg);
+
+- All remaining *ioctl* cases must be moved to a separate
+ function, *<device>_ioctl*, the device-dependent *ioctl()'s*. Note that
memory checking and allocation must be kept in this code!
-\item Change the prototypes of $<device>_open()$ and
- $<device>_release()$, and remove any strategic code (\ie, tray
+- Change the prototypes of *<device>_open()* and
+ *<device>_release()*, and remove any strategic code (i. e., tray
movement, door locking, etc.).
-\item Try to recompile the drivers. We advise you to use modules, both
- for {\tt {cdrom.o}} and your driver, as debugging is much easier this
+- Try to recompile the drivers. We advise you to use modules, both
+ for `cdrom.o` and your driver, as debugging is much easier this
way.
-\end{enumerate}
-\newsection{Thanks}
+Thanks
+======
-Thanks to all the people involved. First, Erik Andersen, who has
-taken over the torch in maintaining \cdromc\ and integrating much
-\cdrom-related code in the 2.1-kernel. Thanks to Scott Snyder and
+Thanks to all the people involved. First, Erik Andersen, who has
+taken over the torch in maintaining `cdrom.c` and integrating much
+CD-ROM-related code in the 2.1-kernel. Thanks to Scott Snyder and
Gerd Knorr, who were the first to implement this interface for SCSI
and IDE-CD drivers and added many ideas for extension of the data
-structures relative to kernel~2.0. Further thanks to Heiko Ei{\ss}feldt,
-Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard M\"onkeberg and Andrew
-Kroll, the \linux\ \cdrom\ device driver developers who were kind
+structures relative to kernel~2.0. Further thanks to Heiko Eißfeldt,
+Thomas Quinot, Jon Tombs, Ken Pizzini, Eberhard Mönkeberg and Andrew Kroll,
+the Linux CD-ROM device driver developers who were kind
enough to give suggestions and criticisms during the writing. Finally
of course, I want to thank Linus Torvalds for making this possible in
the first place.
-
-\vfill
-$ \version\ $
-\eject
-\end{document}
diff --git a/drivers/cdrom/cdrom.c b/drivers/cdrom/cdrom.c
index 933268b8d6a5..5d1e0a4a7d84 100644
--- a/drivers/cdrom/cdrom.c
+++ b/drivers/cdrom/cdrom.c
@@ -7,7 +7,7 @@
License. See linux/COPYING for more information.
Uniform CD-ROM driver for Linux.
- See Documentation/cdrom/cdrom-standard.tex for usage information.
+ See Documentation/cdrom/cdrom-standard.txt for usage information.
The routines in the file provide a uniform interface between the
software that uses CD-ROMs and the various low-level drivers that
--
2.21.0
^ permalink raw reply related
* [PATCH v3 19/33] docs: pcmcia: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Dominik Brodowski
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
Convert the pcmcia docs to ReST format. Most of the changes here
are trivial.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../{devicetable.txt => devicetable.rst} | 4 ++
...{driver-changes.txt => driver-changes.rst} | 35 +++++++++++------
.../pcmcia/{driver.txt => driver.rst} | 18 ++++-----
Documentation/pcmcia/index.rst | 20 ++++++++++
.../pcmcia/{locking.txt => locking.rst} | 39 +++++++++++++------
drivers/pcmcia/ds.c | 2 +-
include/pcmcia/ds.h | 2 +-
include/pcmcia/ss.h | 2 +-
8 files changed, 86 insertions(+), 36 deletions(-)
rename Documentation/pcmcia/{devicetable.txt => devicetable.rst} (97%)
rename Documentation/pcmcia/{driver-changes.txt => driver-changes.rst} (90%)
rename Documentation/pcmcia/{driver.txt => driver.rst} (66%)
create mode 100644 Documentation/pcmcia/index.rst
rename Documentation/pcmcia/{locking.txt => locking.rst} (81%)
diff --git a/Documentation/pcmcia/devicetable.txt b/Documentation/pcmcia/devicetable.rst
similarity index 97%
rename from Documentation/pcmcia/devicetable.txt
rename to Documentation/pcmcia/devicetable.rst
index 5f3e00ab54c4..fd1d60d12ca1 100644
--- a/Documentation/pcmcia/devicetable.txt
+++ b/Documentation/pcmcia/devicetable.rst
@@ -1,3 +1,7 @@
+============
+Device table
+============
+
Matching of PCMCIA devices to drivers is done using one or more of the
following criteria:
diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.rst
similarity index 90%
rename from Documentation/pcmcia/driver-changes.txt
rename to Documentation/pcmcia/driver-changes.rst
index 78355c4c268a..33fe9ebec049 100644
--- a/Documentation/pcmcia/driver-changes.txt
+++ b/Documentation/pcmcia/driver-changes.rst
@@ -1,15 +1,21 @@
+==============
+Driver changes
+==============
+
This file details changes in 2.6 which affect PCMCIA card driver authors:
+
* pcmcia_loop_config() and autoconfiguration (as of 2.6.36)
- If struct pcmcia_device *p_dev->config_flags is set accordingly,
+ If `struct pcmcia_device *p_dev->config_flags` is set accordingly,
pcmcia_loop_config() now sets up certain configuration values
automatically, though the driver may still override the settings
in the callback function. The following autoconfiguration options
are provided at the moment:
- CONF_AUTO_CHECK_VCC : check for matching Vcc
- CONF_AUTO_SET_VPP : set Vpp
- CONF_AUTO_AUDIO : auto-enable audio line, if required
- CONF_AUTO_SET_IO : set ioport resources (->resource[0,1])
- CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
+
+ - CONF_AUTO_CHECK_VCC : check for matching Vcc
+ - CONF_AUTO_SET_VPP : set Vpp
+ - CONF_AUTO_AUDIO : auto-enable audio line, if required
+ - CONF_AUTO_SET_IO : set ioport resources (->resource[0,1])
+ - CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
* pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36)
pcmcia_request_configuration() got renamed to pcmcia_enable_device(),
@@ -19,14 +25,14 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* pcmcia_request_window changes (as of 2.6.36)
Instead of win_req_t, drivers are now requested to fill out
- struct pcmcia_device *p_dev->resource[2,3,4,5] for up to four ioport
+ `struct pcmcia_device *p_dev->resource[2,3,4,5]` for up to four ioport
ranges. After a call to pcmcia_request_window(), the regions found there
are reserved and may be used immediately -- until pcmcia_release_window()
is called.
* pcmcia_request_io changes (as of 2.6.36)
Instead of io_req_t, drivers are now requested to fill out
- struct pcmcia_device *p_dev->resource[0,1] for up to two ioport
+ `struct pcmcia_device *p_dev->resource[0,1]` for up to two ioport
ranges. After a call to pcmcia_request_io(), the ports found there
are reserved, after calling pcmcia_request_configuration(), they may
be used.
@@ -42,7 +48,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* New IRQ request rules (as of 2.6.35)
Instead of the old pcmcia_request_irq() interface, drivers may now
choose between:
- - calling request_irq/free_irq directly. Use the IRQ from *p_dev->irq.
+
+ - calling request_irq/free_irq directly. Use the IRQ from `*p_dev->irq`.
- use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will
clean up automatically on calls to pcmcia_disable_device() or
device ejection.
@@ -72,13 +79,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
exports for them were removed.
* Unify detach and REMOVAL event code, as well as attach and INSERTION
- code (as of 2.6.16)
+ code (as of 2.6.16)::
+
void (*remove) (struct pcmcia_device *dev);
int (*probe) (struct pcmcia_device *dev);
-* Move suspend, resume and reset out of event handler (as of 2.6.16)
+* Move suspend, resume and reset out of event handler (as of 2.6.16)::
+
int (*suspend) (struct pcmcia_device *dev);
int (*resume) (struct pcmcia_device *dev);
+
should be initialized in struct pcmcia_driver, and handle
(SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events
@@ -117,7 +127,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
* core functions no longer available (as of 2.6.11)
The following functions have been removed from the kernel source
because they are unused by all in-kernel drivers, and no external
- driver was reported to rely on them:
+ driver was reported to rely on them::
+
pcmcia_get_first_region()
pcmcia_get_next_region()
pcmcia_modify_window()
diff --git a/Documentation/pcmcia/driver.txt b/Documentation/pcmcia/driver.rst
similarity index 66%
rename from Documentation/pcmcia/driver.txt
rename to Documentation/pcmcia/driver.rst
index 0ac167920778..5c4fe84d51c1 100644
--- a/Documentation/pcmcia/driver.txt
+++ b/Documentation/pcmcia/driver.rst
@@ -1,16 +1,16 @@
+=============
PCMCIA Driver
--------------
-
+=============
sysfs
-----
New PCMCIA IDs may be added to a device driver pcmcia_device_id table at
-runtime as shown below:
+runtime as shown below::
-echo "match_flags manf_id card_id func_id function device_no \
-prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
-/sys/bus/pcmcia/drivers/{driver}/new_id
+ echo "match_flags manf_id card_id func_id function device_no \
+ prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
+ /sys/bus/pcmcia/drivers/{driver}/new_id
All fields are passed in as hexadecimal values (no leading 0x).
The meaning is described in the PCMCIA specification, the match_flags is
@@ -22,9 +22,9 @@ PCMCIA device listed in its (newly updated) pcmcia_device_id list.
A common use-case is to add a new device according to the manufacturer ID
and the card ID (form the manf_id and card_id file in the device tree).
-For this, just use:
+For this, just use::
-echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
- /sys/bus/pcmcia/drivers/{driver}/new_id
+ echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
+ /sys/bus/pcmcia/drivers/{driver}/new_id
after loading the driver.
diff --git a/Documentation/pcmcia/index.rst b/Documentation/pcmcia/index.rst
new file mode 100644
index 000000000000..779c8527109e
--- /dev/null
+++ b/Documentation/pcmcia/index.rst
@@ -0,0 +1,20 @@
+:orphan:
+
+======
+pcmcia
+======
+
+.. toctree::
+ :maxdepth: 1
+
+ driver
+ devicetable
+ locking
+ driver-changes
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/pcmcia/locking.txt b/Documentation/pcmcia/locking.rst
similarity index 81%
rename from Documentation/pcmcia/locking.txt
rename to Documentation/pcmcia/locking.rst
index b2c9b478906b..e35257139c89 100644
--- a/Documentation/pcmcia/locking.txt
+++ b/Documentation/pcmcia/locking.rst
@@ -1,3 +1,7 @@
+=======
+Locking
+=======
+
This file explains the locking and exclusion scheme used in the PCCARD
and PCMCIA subsystems.
@@ -5,16 +9,21 @@ and PCMCIA subsystems.
A) Overview, Locking Hierarchy:
===============================
-pcmcia_socket_list_rwsem - protects only the list of sockets
-- skt_mutex - serializes card insert / ejection
- - ops_mutex - serializes socket operation
+pcmcia_socket_list_rwsem
+ - protects only the list of sockets
+
+- skt_mutex
+ - serializes card insert / ejection
+
+ - ops_mutex
+ - serializes socket operation
B) Exclusion
============
The following functions and callbacks to struct pcmcia_socket must
-be called with "skt_mutex" held:
+be called with "skt_mutex" held::
socket_detect_change()
send_event()
@@ -31,7 +40,7 @@ be called with "skt_mutex" held:
struct pcmcia_callback *callback
The following functions and callbacks to struct pcmcia_socket must
-be called with "ops_mutex" held:
+be called with "ops_mutex" held::
socket_reset()
socket_setup()
@@ -39,7 +48,7 @@ be called with "ops_mutex" held:
struct pccard_operations *ops
struct pccard_resource_ops *resource_ops;
-Note that send_event() and struct pcmcia_callback *callback must not be
+Note that send_event() and `struct pcmcia_callback *callback` must not be
called with "ops_mutex" held.
@@ -60,19 +69,23 @@ The resource_ops and their data are protected by ops_mutex.
The "main" struct pcmcia_socket is protected as follows (read-only fields
or single-use fields not mentioned):
-- by pcmcia_socket_list_rwsem:
+- by pcmcia_socket_list_rwsem::
+
struct list_head socket_list;
-- by thread_lock:
+- by thread_lock::
+
unsigned int thread_events;
-- by skt_mutex:
+- by skt_mutex::
+
u_int suspended_state;
void (*tune_bridge);
struct pcmcia_callback *callback;
int resume_status;
-- by ops_mutex:
+- by ops_mutex::
+
socket_state_t socket;
u_int state;
u_short lock_count;
@@ -100,7 +113,8 @@ The "main" struct pcmcia_device is protected as follows (read-only fields
or single-use fields not mentioned):
-- by pcmcia_socket->ops_mutex:
+- by pcmcia_socket->ops_mutex::
+
struct list_head socket_device_list;
struct config_t *function_config;
u16 _irq:1;
@@ -111,7 +125,8 @@ or single-use fields not mentioned):
u16 suspended:1;
u16 _removed:1;
-- by the PCMCIA driver:
+- by the PCMCIA driver::
+
io_req_t io;
irq_req_t irq;
config_req_t conf;
diff --git a/drivers/pcmcia/ds.c b/drivers/pcmcia/ds.c
index a9258f641cee..5230e284bb20 100644
--- a/drivers/pcmcia/ds.c
+++ b/drivers/pcmcia/ds.c
@@ -67,7 +67,7 @@ static void pcmcia_check_driver(struct pcmcia_driver *p_drv)
"be 0x%x\n", p_drv->name, did->prod_id[i],
did->prod_id_hash[i], hash);
printk(KERN_DEBUG "pcmcia: see "
- "Documentation/pcmcia/devicetable.txt for "
+ "Documentation/pcmcia/devicetable.rst for "
"details\n");
}
did++;
diff --git a/include/pcmcia/ds.h b/include/pcmcia/ds.h
index 3037157855f0..4e58c20dabcb 100644
--- a/include/pcmcia/ds.h
+++ b/include/pcmcia/ds.h
@@ -39,7 +39,7 @@ struct config_t;
struct net_device;
/* dynamic device IDs for PCMCIA device drivers. See
- * Documentation/pcmcia/driver.txt for details.
+ * Documentation/pcmcia/driver.rst for details.
*/
struct pcmcia_dynids {
struct mutex lock;
diff --git a/include/pcmcia/ss.h b/include/pcmcia/ss.h
index 731cde010f42..89629ee57840 100644
--- a/include/pcmcia/ss.h
+++ b/include/pcmcia/ss.h
@@ -190,7 +190,7 @@ struct pcmcia_socket {
unsigned int sysfs_events;
/* For the non-trivial interaction between these locks,
- * see Documentation/pcmcia/locking.txt */
+ * see Documentation/pcmcia/locking.rst */
struct mutex skt_mutex;
struct mutex ops_mutex;
--
2.21.0
^ permalink raw reply related
* [PATCH v3 11/33] docs: fpga: convert docs to ReST and rename to *.rst
From: Mauro Carvalho Chehab @ 2019-06-09 2:27 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Wu Hao, Alan Tull, Moritz Fischer, linux-fpga
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
The dfl.txt file is almost there. It needs just a few
adjustments to be properly parsed.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/fpga/{dfl.txt => dfl.rst} | 58 ++++++++++++++-----------
Documentation/fpga/index.rst | 17 ++++++++
MAINTAINERS | 2 +-
3 files changed, 50 insertions(+), 27 deletions(-)
rename Documentation/fpga/{dfl.txt => dfl.rst} (89%)
create mode 100644 Documentation/fpga/index.rst
diff --git a/Documentation/fpga/dfl.txt b/Documentation/fpga/dfl.rst
similarity index 89%
rename from Documentation/fpga/dfl.txt
rename to Documentation/fpga/dfl.rst
index 6df4621c3f2a..2f125abd777f 100644
--- a/Documentation/fpga/dfl.txt
+++ b/Documentation/fpga/dfl.rst
@@ -1,9 +1,12 @@
-===============================================================================
- FPGA Device Feature List (DFL) Framework Overview
--------------------------------------------------------------------------------
- Enno Luebbers <enno.luebbers@intel.com>
- Xiao Guangrong <guangrong.xiao@linux.intel.com>
- Wu Hao <hao.wu@intel.com>
+=================================================
+FPGA Device Feature List (DFL) Framework Overview
+=================================================
+
+Authors:
+
+- Enno Luebbers <enno.luebbers@intel.com>
+- Xiao Guangrong <guangrong.xiao@linux.intel.com>
+- Wu Hao <hao.wu@intel.com>
The Device Feature List (DFL) FPGA framework (and drivers according to this
this framework) hides the very details of low layer hardwares and provides
@@ -19,7 +22,7 @@ Device Feature List (DFL) defines a linked list of feature headers within the
device MMIO space to provide an extensible way of adding features. Software can
walk through these predefined data structures to enumerate FPGA features:
FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features,
-as illustrated below:
+as illustrated below::
Header Header Header Header
+----------+ +-->+----------+ +-->+----------+ +-->+----------+
@@ -81,9 +84,9 @@ and release it using close().
The following functions are exposed through ioctls:
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Program bitstream (DFL_FPGA_FME_PORT_PR)
+- Get driver API version (DFL_FPGA_GET_API_VERSION)
+- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
+- Program bitstream (DFL_FPGA_FME_PORT_PR)
More functions are exposed through sysfs
(/sys/class/fpga_region/regionX/dfl-fme.n/):
@@ -118,18 +121,19 @@ port by using open() on the port device node and release it using close().
The following functions are exposed through ioctls:
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Get port info (DFL_FPGA_PORT_GET_INFO)
- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
- Reset AFU (*DFL_FPGA_PORT_RESET)
+- Get driver API version (DFL_FPGA_GET_API_VERSION)
+- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
+- Get port info (DFL_FPGA_PORT_GET_INFO)
+- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
+- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
+- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
+- Reset AFU (DFL_FPGA_PORT_RESET)
-*DFL_FPGA_PORT_RESET: reset the FPGA Port and its AFU. Userspace can do Port
-reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
-never cause any system level issue, only functional failure (e.g. DMA or PR
-operation failure) and be recoverable from the failure.
+DFL_FPGA_PORT_RESET:
+ reset the FPGA Port and its AFU. Userspace can do Port
+ reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
+ never cause any system level issue, only functional failure (e.g. DMA or PR
+ operation failure) and be recoverable from the failure.
User-space applications can also mmap() accelerator MMIO regions.
@@ -143,6 +147,8 @@ More functions are exposed through sysfs:
DFL Framework Overview
======================
+::
+
+----------+ +--------+ +--------+ +--------+
| FME | | AFU | | AFU | | AFU |
| Module | | Module | | Module | | Module |
@@ -151,7 +157,7 @@ DFL Framework Overview
| FPGA Container Device | Device Feature List
| (FPGA Base Region) | Framework
+-----------------------+
---------------------------------------------------------------------
+ ------------------------------------------------------------------
+----------------------------+
| FPGA DFL Device Module |
| (e.g. PCIE/Platform Device)|
@@ -220,7 +226,7 @@ the sysfs hierarchy under /sys/class/fpga_region.
In the example below, two DFL based FPGA devices are installed in the host. Each
fpga device has one FME and two ports (AFUs).
-FPGA regions are created under /sys/class/fpga_region/
+FPGA regions are created under /sys/class/fpga_region/::
/sys/class/fpga_region/region0
/sys/class/fpga_region/region1
@@ -231,7 +237,7 @@ Application needs to search each regionX folder, if feature device is found,
(e.g. "dfl-port.n" or "dfl-fme.m" is found), then it's the base
fpga region which represents the FPGA device.
-Each base region has one FME and two ports (AFUs) as child devices:
+Each base region has one FME and two ports (AFUs) as child devices::
/sys/class/fpga_region/region0/dfl-fme.0
/sys/class/fpga_region/region0/dfl-port.0
@@ -243,7 +249,7 @@ Each base region has one FME and two ports (AFUs) as child devices:
/sys/class/fpga_region/region3/dfl-port.3
...
-In general, the FME/AFU sysfs interfaces are named as follows:
+In general, the FME/AFU sysfs interfaces are named as follows::
/sys/class/fpga_region/<regionX>/<dfl-fme.n>/
/sys/class/fpga_region/<regionX>/<dfl-port.m>/
@@ -251,7 +257,7 @@ In general, the FME/AFU sysfs interfaces are named as follows:
with 'n' consecutively numbering all FMEs and 'm' consecutively numbering all
ports.
-The device nodes used for ioctl() or mmap() can be referenced through:
+The device nodes used for ioctl() or mmap() can be referenced through::
/sys/class/fpga_region/<regionX>/<dfl-fme.n>/dev
/sys/class/fpga_region/<regionX>/<dfl-port.n>/dev
diff --git a/Documentation/fpga/index.rst b/Documentation/fpga/index.rst
new file mode 100644
index 000000000000..2c87d1ea084f
--- /dev/null
+++ b/Documentation/fpga/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+====
+fpga
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ dfl
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/MAINTAINERS b/MAINTAINERS
index 9f83a79fdfdb..cc11aea722c8 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6270,7 +6270,7 @@ FPGA DFL DRIVERS
M: Wu Hao <hao.wu@intel.com>
L: linux-fpga@vger.kernel.org
S: Maintained
-F: Documentation/fpga/dfl.txt
+F: Documentation/fpga/dfl.rst
F: include/uapi/linux/fpga-dfl.h
F: drivers/fpga/dfl*
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v2 00/22] Some documentation fixes
From: Mauro Carvalho Chehab @ 2019-06-09 2:31 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Alexei Starovoitov, Daniel Borkmann, Martin KaFai Lau, Song Liu,
Yonghong Song, netdev, bpf
In-Reply-To: <20190608134407.580f8bb5@lwn.net>
Em Sat, 8 Jun 2019 13:44:07 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Fri, 7 Jun 2019 15:44:30 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > After doing that, there are 17 patches yet to be applied. Two new
> > patches are now needed too, due to vfs.txt -> vfs.rst and
> > pci.txt -> pci.rst renames.
>
> OK, I've applied the set, minus those that had been picked up elsewhere.
Thank you!
I'm sending the conversion patches based after your tree + linux-next.
I opted to split it on a few series, as I have already 85 patches
here (and still several new "orphan" index files that I need to work
in order to find them a place).
Sending right now the first 33 patches.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v2 00/22] Some documentation fixes
From: Mauro Carvalho Chehab @ 2019-06-09 2:33 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Alexei Starovoitov, Daniel Borkmann, Martin KaFai Lau, Song Liu,
Yonghong Song, netdev, bpf
In-Reply-To: <20190608134407.580f8bb5@lwn.net>
Em Sat, 8 Jun 2019 13:44:07 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Fri, 7 Jun 2019 15:44:30 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > After doing that, there are 17 patches yet to be applied. Two new
> > patches are now needed too, due to vfs.txt -> vfs.rst and
> > pci.txt -> pci.rst renames.
>
> OK, I've applied the set, minus those that had been picked up elsewhere.
Thank you!
I'm sending the conversion patches based after your tree + linux-next.
I opted to split it on a few series, as I have already 85 patches
here (and still several new "orphan" index files that I need to work
in order to find them a place).
Sending right now the first 33 patches.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v3 19/33] docs: pcmcia: convert docs to ReST and rename to *.rst
From: Dominik Brodowski @ 2019-06-09 6:59 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <d1b05720154bdbc4b75f5583cd4d1740e58b4cde.1560045490.git.mchehab+samsung@kernel.org>
On Sat, Jun 08, 2019 at 11:27:09PM -0300, Mauro Carvalho Chehab wrote:
> Convert the pcmcia docs to ReST format. Most of the changes here
> are trivial.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Dominik Brodowski <linux@dominikbrodowski.net>
Thanks,
Dominik
^ permalink raw reply
* Re: [PATCH v3 12/33] docs: ide: convert docs to ReST and rename to *.rst
From: Geert Uytterhoeven @ 2019-06-09 7:50 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Borislav Petkov,
Jens Axboe, David S. Miller, linux-ide, linux-m68k
In-Reply-To: <472757a7481a8645837092f0f257f37996af6299.1560045490.git.mchehab+samsung@kernel.org>
On Sun, Jun 9, 2019 at 4:27 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> arch/m68k/q40/README | 2 +-
Acked-by: Geert Uytterhoeven <geert@linux-m68k.org>
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
^ permalink raw reply
* Re: [PATCH v3 10/33] docs: fb: convert docs to ReST and rename to *.rst
From: Geert Uytterhoeven @ 2019-06-09 7:54 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet,
Bartlomiej Zolnierkiewicz, Maik Broemme, Thomas Winischhofer,
Sudip Mukherjee, Teddy Wang, Bernie Thompson, Michal Januszewski,
Greg Kroah-Hartman, Jiri Slaby, DRI Development,
Linux Fbdev development list
In-Reply-To: <f7f9c692a870f836e5657b8a763d751b6ac0e86e.1560045490.git.mchehab+samsung@kernel.org>
Hi Mauro,
On Sun, Jun 9, 2019 at 4:29 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Thanks!
> --- a/Documentation/fb/framebuffer.txt
> +++ b/Documentation/fb/framebuffer.rst
> @@ -1,5 +1,6 @@
> - The Frame Buffer Device
> - -----------------------
> +=======================
> +The Frame Buffer Device
> +=======================
>
> Maintained by Geert Uytterhoeven <geert@linux-m68k.org>
I'm happy to see this line dropped ;-)
> Last revised: May 10, 2001
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
^ permalink raw reply
* Re: [PATCH v3 00/33] Convert files to ReST - part 1
From: Heiko Carstens @ 2019-06-09 9:16 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Palmer Dabbelt, Albert Ou, Alexei Starovoitov,
Daniel Borkmann, Martin KaFai Lau, Song Liu, Yonghong Song,
Greentime Hu, Vincent Chen, linux-riscv, netdev, bpf
In-Reply-To: <cover.1560045490.git.mchehab+samsung@kernel.org>
On Sat, Jun 08, 2019 at 11:26:50PM -0300, Mauro Carvalho Chehab wrote:
> This is the first part of a series I wrote sometime ago where I manually
> convert lots of files to be properly parsed by Sphinx as ReST files.
>
> As it touches on lot of stuff, this series is based on today's docs-next
> + linux-next, at tag next-20190607.
>
> I have right now about 85 patches with this undergoing work. That's
> because I opted to do ~1 patch per converted directory.
>
> That sounds too much to be send on a single round. So, I'm opting to split
> it on 3 parts. Those patches should probably be good to be merged
> either by subsystem maintainers or via the docs tree.
>
> I opted to mark new files not included yet to the main index.rst (directly or
> indirectly ) with the :orphan: tag, in order to avoid adding warnings to the
> build system. This should be removed after we find a "home" for all
> the converted files within the new document tree arrangement.
>
> Both this series and the next parts are on my devel git tree,
> at:
>
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v4
>
> The final output in html (after all patches I currently have, including
> the upcoming series) can be seen at:
>
> https://www.infradead.org/~mchehab/rst_conversion/
Will there be a web page (e.g. kernel.org), which contains always the
latest upstream version?
> docs: Debugging390.txt: convert table to ascii artwork
> docs: s390: convert docs to ReST and rename to *.rst
> s390: include/asm/debug.h add kerneldoc markups
I can pick these up for s390. Or do you want to send the whole series
in one go upstream?
^ permalink raw reply
* Re: [PATCH v3 15/20] docs: move protection-keys.rst to the core-api book
From: Geert Uytterhoeven @ 2019-06-09 9:19 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Thomas Gleixner,
Ingo Molnar, Borislav Petkov, H. Peter Anvin,
the arch/x86 maintainers, Benjamin Herrenschmidt, Paul Mackerras,
Michael Ellerman, Shuah Khan, linuxppc-dev,
open list:KERNEL SELFTEST FRAMEWORK
In-Reply-To: <4948a096397bb86cebf489b8ac4f623797257fe7.1559933665.git.mchehab+samsung@kernel.org>
Hi Mauro,
On Fri, Jun 7, 2019 at 9:38 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
> This document is used by multiple architectures:
Indeed it is...
>
> $ echo $(git grep -l pkey_mprotect arch|cut -d'/' -f 2|sort|uniq)
> alpha arm arm64 ia64 m68k microblaze mips parisc powerpc s390 sh sparc x86 xtensa
... but not because we now have a unified space for new syscall numbers ;-)
$ git grep -w ARCH_HAS_PKEYS -- "*Kconf*"
arch/powerpc/Kconfig: select ARCH_HAS_PKEYS
arch/x86/Kconfig: select ARCH_HAS_PKEYS
mm/Kconfig:config ARCH_HAS_PKEYS
I.e. limited to x86 and powerpc.
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
^ permalink raw reply
* Re: [PATCH v3 00/33] Convert files to ReST - part 1
From: Markus Heiser @ 2019-06-09 9:22 UTC (permalink / raw)
To: Heiko Carstens, Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Palmer Dabbelt, Albert Ou, Alexei Starovoitov,
Daniel Borkmann, Martin KaFai Lau, Song Liu, Yonghong Song,
Greentime Hu, Vincent Chen, linux-riscv, netdev, bpf
In-Reply-To: <20190609091642.GA3705@osiris>
Am 09.06.19 um 11:16 schrieb Heiko Carstens:
> Will there be a web page (e.g. kernel.org), which contains always the
> latest upstream version?
You are looking for the HTML docs on kernel.org?
https://www.kernel.org/doc/html/latest/
-- Markus --
^ permalink raw reply
* Re: [PATCH v3 22/33] docs: pps.txt: convert to ReST and rename to pps.rst
From: Rodolfo Giometti @ 2019-06-09 9:20 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
In-Reply-To: <cb9274c1d5e94a74c5922c04d99b90554f2d804b.1560045490.git.mchehab+samsung@kernel.org>
On 09/06/2019 04:27, Mauro Carvalho Chehab wrote:
> This file is already in a good shape: just its title and
> adding some literal block markups is needed for it to be
> part of the document.
>
> While it has a small chapter with sysfs stuff, most of
> the document is focused on driver development.
>
> As it describes a kernel API, move it to the driver-api
> directory.
>
> In order to avoid conflicts, let's add an :orphan: tag
> to it, to be removed when added to the driver-api book.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rodolfo Giometti <giometti@enneenne.com>
--
GNU/Linux Solutions e-mail: giometti@enneenne.com
Linux Device Driver giometti@linux.it
Embedded Systems phone: +39 349 2432127
UNIX programming skype: rodolfo.giometti
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox