Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1642478 > unrolled thread
| Started by | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| First post | 2017-05-16 14:20 +0200 |
| Last post | 2017-05-19 01:10 +0200 |
| Articles | 20 on this page of 57 — 8 participants |
Back to article view | Back to linux.kernel
[PATCH v2 00/53] Get rid of Docbook Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 18/53] docs-rst: filesystems: use c domain references where needed Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 06/53] locking.rst: add captions to two tables Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 33/53] scsi: fix some kernel-doc markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 17/53] docs-rst: convert filesystems book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
[PATCH v2 39/53] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:20 +0200
Re: [PATCH v2 39/53] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings Boris Brezillon <boris.brezillon@free-electrons.com> - 2017-05-16 15:20 +0200
[PATCH v2 16/53] docs-rst: add userspace API book to pdf output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 20/53] docs-rst: don't ignore internal functions for jbd2 docs Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 15/53] docs-rst: add sound book to pdf output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
Re: [PATCH v2 15/53] docs-rst: add sound book to pdf output Takashi Iwai <tiwai@suse.de> - 2017-05-16 21:10 +0200
[PATCH v2 31/53] docs-rst: convert z8530book DocBook to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 10/53] conf.py: define a color for important markup on PDF output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 44/53] MAINTAINERS: update old references for DocBook directory Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 02/53] kernel-hacking: update document Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 53/53] kernel-doc: describe the ``literal`` syntax Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:20 +0200
[PATCH v2 52/53] docs-rst: get rid of Documentation/sphinx/tmplcvt script Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:20 +0200
[PATCH v2 50/53] fs: fix the location of the kernel-api book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:20 +0200
[PATCH v2 51/53] usb: fix the comment with regards to DocBook Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:20 +0200
Re: [PATCH v2 51/53] usb: fix the comment with regards to DocBook Felipe Balbi <balbi@kernel.org> - 2017-05-17 13:20 +0200
[PATCH v2 14/53] docs-rst: add dev-tools book to pdf output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 29/53] net: skbuff.h: properly escape a macro name on kernel-doc Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 07/53] locking.rst: Update some ReST markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 09/53] kgdb.rst: Adjust ReST markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 47/53] irq: update genericirq book location Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 41/53] docs-rst: convert lsm from DocBook to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 46/53] ia64, scsi: update references for the device-io book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 05/53] locking.rst: reformat locking table Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 25/53] libata.rst: add c function and struct cross-references Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 36/53] docs-rst: convert librs book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 42/53] docs: remove DocBook from the building system Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 32/53] docs-rst: convert scsi DocBook to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 48/53] fs: update location of filesystems documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 34/53] docs-rst: convert w1 book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 49/53] lib: update location of kgdb documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 28/53] docs-rst: convert networking book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 30/53] net: fix some identation issues at kernel-doc markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
Re: [PATCH v2 30/53] net: fix some identation issues at kernel-doc markups David Howells <dhowells@redhat.com> - 2017-05-16 14:40 +0200
[PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
Re: [PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-16 19:40 +0200
Re: [PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 20:30 +0200
Re: [PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST Darren Hart <dvhart@infradead.org> - 2017-05-16 21:10 +0200
[PATCH v2 21/53] fs: add a blank lines on some kernel-doc comments Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 11/53] docs-rst: conf.py: sort LaTeX documents in alphabetical order Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 12/53] docs-rst: conf.py: remove kernel-documentation from LaTeX Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
[PATCH v2 43/53] docs: update old references for DocBook from the documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:30 +0200
Re: [PATCH v2 43/53] docs: update old references for DocBook from the documentation Bjorn Helgaas <helgaas@kernel.org> - 2017-05-17 19:00 +0200
[PATCH v2 13/53] docs-rst: add crypto API book to pdf output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 22/53] fs: eventfd: fix identation on kernel-doc Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 35/53] docs-rst: convert rapidio book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 27/53] docs-rst: convert s390-drivers DocBook to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 26/53] libata: fix identation on a kernel-doc markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
[PATCH v2 38/53] mtdnand.rst: group the "::" with previous line Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
Re: [PATCH v2 38/53] mtdnand.rst: group the "::" with previous line Boris Brezillon <boris.brezillon@free-electrons.com> - 2017-05-16 15:20 +0200
[PATCH v2 40/53] docs-rst: convert sh book to ReST Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-16 14:40 +0200
Re: [PATCH v2 00/53] Get rid of Docbook Jonathan Corbet <corbet@lwn.net> - 2017-05-18 19:30 +0200
Re: [PATCH v2 00/53] Get rid of Docbook Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 01:10 +0200
Page 2 of 3 — ← Prev page 1 [2] 3 Next page →
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 14/53] docs-rst: add dev-tools book to pdf output |
| Message-ID | <tHJLY-5yL-23@gated-at.bofh.it> |
| In reply to | #1642478 |
The dev-tools API book was added without the bits required to
generate PDF output at the main conf.py. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/conf.py | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index ce62723491d4..1d461f0c1cd0 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -353,6 +353,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('crypto/index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
'The kernel development community', 'manual'),
+ ('dev-tools/index', 'dev-tools.tex', 'Development tools for the Kernel',
+ 'The kernel development community', 'manual'),
('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
'The kernel development community', 'manual'),
('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 29/53] net: skbuff.h: properly escape a macro name on kernel-doc |
| Message-ID | <tHJLY-5yL-25@gated-at.bofh.it> |
| In reply to | #1642478 |
The "%" escape code of kernel-doc only handle letters. It doesn't handle special chars. So, use the ``literal`` notation. That fixes this warning: ./include/linux/skbuff.h:2695: WARNING: Inline literal start-string without end-string. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- include/linux/skbuff.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/linux/skbuff.h b/include/linux/skbuff.h index a098d95b3d84..25b1659c832a 100644 --- a/include/linux/skbuff.h +++ b/include/linux/skbuff.h @@ -2691,7 +2691,7 @@ bool skb_page_frag_refill(unsigned int sz, struct page_frag *pfrag, gfp_t prio); * @offset: the offset within the fragment (starting at the * fragment's own offset) * @size: the number of bytes to map - * @dir: the direction of the mapping (%PCI_DMA_*) + * @dir: the direction of the mapping (``PCI_DMA_*``) * * Maps the page associated with @frag to @device. */ -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 07/53] locking.rst: Update some ReST markups |
| Message-ID | <tHJLZ-5yL-29@gated-at.bofh.it> |
| In reply to | #1642478 |
Correct a few minor issues with ReST notation used on
this file (produced by an automatic tool).
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/kernel-hacking/locking.rst | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index b70c2c4eb147..f937c0fd11aa 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -93,13 +93,13 @@ Locking in the Linux Kernel
===========================
If I could give you one piece of advice: never sleep with anyone crazier
-than yourself. But if I had to give you advice on locking: *keep it
-simple*.
+than yourself. But if I had to give you advice on locking: **keep it
+simple**.
Be reluctant to introduce new locks.
Strangely enough, this last one is the exact reverse of my advice when
-you *have* slept with someone crazier than yourself. And you should
+you **have** slept with someone crazier than yourself. And you should
think about getting a big dog.
Two Main Types of Kernel Locks: Spinlocks and Mutexes
@@ -311,7 +311,7 @@ Pete Zaitcev gives the following summary:
Table of Minimum Requirements
-----------------------------
-The following table lists the *minimum* locking requirements between
+The following table lists the **minimum** locking requirements between
various contexts. In some cases, the same context can only be running on
one CPU at a time, so no locking is required for that context (eg. a
particular thread can only run on one CPU at a time, but if it needs
@@ -703,7 +703,7 @@ reference count, but they are more complicated.
Using Atomic Operations For The Reference Count
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In practice, ``atomic_t`` would usually be used for refcnt. There are a
+In practice, :c:type:`atomic_t` would usually be used for refcnt. There are a
number of atomic operations defined in ``include/asm/atomic.h``: these
are guaranteed to be seen atomically from all CPUs in the system, so no
lock is required. In this case, it is simpler than using spinlocks,
@@ -1321,7 +1321,7 @@ from user context, and can sleep.
- :c:func:`put_user()`
-- ``kmalloc(GFP_KERNEL)``
+- :c:func:`kmalloc(GFP_KERNEL) <kmalloc>`
- :c:func:`mutex_lock_interruptible()` and
:c:func:`mutex_lock()`
@@ -1431,10 +1431,10 @@ tasklet
timer
A dynamically-registrable software interrupt, which is run at (or close
to) a given time. When running, it is just like a tasklet (in fact, they
- are called from the TIMER_SOFTIRQ).
+ are called from the ``TIMER_SOFTIRQ``).
UP
- Uni-Processor: Non-SMP. (CONFIG_SMP=n).
+ Uni-Processor: Non-SMP. (``CONFIG_SMP=n``).
User Context
The kernel executing on behalf of a particular process (ie. a system
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 09/53] kgdb.rst: Adjust ReST markups |
| Message-ID | <tHJLY-5yL-21@gated-at.bofh.it> |
| In reply to | #1642478 |
The automatic conversion didn't work too well for this file.
It added weird html blocks inside it, and did some weird
things for literals. Manually fix it, in order to present
a nice display at html/pdf outputs.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/dev-tools/kgdb.rst | 489 +++++++++++++++++++--------------------
1 file changed, 233 insertions(+), 256 deletions(-)
diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst
index ea01541806c8..75273203a35a 100644
--- a/Documentation/dev-tools/kgdb.rst
+++ b/Documentation/dev-tools/kgdb.rst
@@ -51,28 +51,29 @@ Compiling a kernel
Kernel config options for kgdb
------------------------------
-To enable ``CONFIG_KGDB`` you should look under "Kernel hacking" /
-"Kernel debugging" and select "KGDB: kernel debugger".
+To enable ``CONFIG_KGDB`` you should look under
+:menuselection:`Kernel hacking --> Kernel debugging` and select
+:menuselection:`KGDB: kernel debugger`.
While it is not a hard requirement that you have symbols in your vmlinux
file, gdb tends not to be very useful without the symbolic data, so you
-will want to turn on ``CONFIG_DEBUG_INFO`` which is called "Compile the
-kernel with debug info" in the config menu.
+will want to turn on ``CONFIG_DEBUG_INFO`` which is called
+:menuselection:`Compile the kernel with debug info` in the config menu.
It is advised, but not required, that you turn on the
-``CONFIG_FRAME_POINTER`` kernel option which is called "Compile the
-kernel with frame pointers" in the config menu. This option inserts code
+``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`Compile
+the kernel with frame pointers` in the config menu. This option inserts code
to into the compiled executable which saves the frame information in
registers or on the stack at different points which allows a debugger
such as gdb to more accurately construct stack back traces while
debugging the kernel.
If the architecture that you are using supports the kernel option
-CONFIG_STRICT_KERNEL_RWX, you should consider turning it off. This
+``CONFIG_STRICT_KERNEL_RWX``, you should consider turning it off. This
option will prevent the use of software breakpoints because it marks
certain regions of the kernel's memory space as read-only. If kgdb
supports it for the architecture you are using, you can use hardware
-breakpoints if you desire to run with the CONFIG_STRICT_KERNEL_RWX
+breakpoints if you desire to run with the ``CONFIG_STRICT_KERNEL_RWX``
option turned on, else you need to turn off this option.
Next you should choose one of more I/O drivers to interconnect debugging
@@ -80,17 +81,14 @@ host and debugged target. Early boot debugging requires a KGDB I/O
driver that supports early debugging and the driver must be built into
the kernel directly. Kgdb I/O driver configuration takes place via
kernel or module parameters which you can learn more about in the in the
-section that describes the parameter "kgdboc".
+section that describes the parameter kgdboc.
-Here is an example set of .config symbols to enable or disable for kgdb:
+Here is an example set of ``.config`` symbols to enable or disable for kgdb::
-- # CONFIG_STRICT_KERNEL_RWX is not set
-
-- CONFIG_FRAME_POINTER=y
-
-- CONFIG_KGDB=y
-
-- CONFIG_KGDB_SERIAL_CONSOLE=y
+ # CONFIG_STRICT_KERNEL_RWX is not set
+ CONFIG_FRAME_POINTER=y
+ CONFIG_KGDB=y
+ CONFIG_KGDB_SERIAL_CONSOLE=y
Kernel config options for kdb
-----------------------------
@@ -99,34 +97,29 @@ Kdb is quite a bit more complex than the simple gdbstub sitting on top
of the kernel's debug core. Kdb must implement a shell, and also adds
some helper functions in other parts of the kernel, responsible for
printing out interesting data such as what you would see if you ran
-"lsmod", or "ps". In order to build kdb into the kernel you follow the
+``lsmod``, or ``ps``. In order to build kdb into the kernel you follow the
same steps as you would for kgdb.
The main config option for kdb is ``CONFIG_KGDB_KDB`` which is called
-"KGDB_KDB: include kdb frontend for kgdb" in the config menu. In theory
-you would have already also selected an I/O driver such as the
-CONFIG_KGDB_SERIAL_CONSOLE interface if you plan on using kdb on a
+:menuselection:`KGDB_KDB: include kdb frontend for kgdb` in the config menu.
+In theory you would have already also selected an I/O driver such as the
+``CONFIG_KGDB_SERIAL_CONSOLE`` interface if you plan on using kdb on a
serial port, when you were configuring kgdb.
If you want to use a PS/2-style keyboard with kdb, you would select
-CONFIG_KDB_KEYBOARD which is called "KGDB_KDB: keyboard as input
-device" in the config menu. The CONFIG_KDB_KEYBOARD option is not used
-for anything in the gdb interface to kgdb. The CONFIG_KDB_KEYBOARD
+``CONFIG_KDB_KEYBOARD`` which is called :menuselection:`KGDB_KDB: keyboard as
+input device` in the config menu. The ``CONFIG_KDB_KEYBOARD`` option is not
+used for anything in the gdb interface to kgdb. The ``CONFIG_KDB_KEYBOARD``
option only works with kdb.
-Here is an example set of .config symbols to enable/disable kdb:
-
-- # CONFIG_STRICT_KERNEL_RWX is not set
-
-- CONFIG_FRAME_POINTER=y
-
-- CONFIG_KGDB=y
-
-- CONFIG_KGDB_SERIAL_CONSOLE=y
-
-- CONFIG_KGDB_KDB=y
-
-- CONFIG_KDB_KEYBOARD=y
+Here is an example set of ``.config`` symbols to enable/disable kdb::
+
+ # CONFIG_STRICT_KERNEL_RWX is not set
+ CONFIG_FRAME_POINTER=y
+ CONFIG_KGDB=y
+ CONFIG_KGDB_SERIAL_CONSOLE=y
+ CONFIG_KGDB_KDB=y
+ CONFIG_KDB_KEYBOARD=y
Kernel Debugger Boot Arguments
==============================
@@ -164,7 +157,9 @@ with kdb while allowing the full graphics console applications to run.
kgdboc arguments
~~~~~~~~~~~~~~~~
-Usage: ``kgdboc=[kms][[,]kbd][[,]serial_device][,baud]``
+Usage::
+
+ kgdboc=[kms][[,]kbd][[,]serial_device][,baud]
The order listed above must be observed if you use any of the optional
configurations together.
@@ -186,11 +181,15 @@ Using loadable module or built-in
1. As a kernel built-in:
- Use the kernel boot argument: ``kgdboc=<tty-device>,[baud]``
+ Use the kernel boot argument::
+
+ kgdboc=<tty-device>,[baud]
2. As a kernel loadable module:
- Use the command: ``modprobe kgdboc kgdboc=<tty-device>,[baud]``
+ Use the command::
+
+ modprobe kgdboc kgdboc=<tty-device>,[baud]
Here are two examples of how you might format the kgdboc string. The
first is for an x86 target using the first serial port. The second
@@ -206,16 +205,18 @@ Configure kgdboc at runtime with sysfs
At run time you can enable or disable kgdboc by echoing a parameters
into the sysfs. Here are two examples:
-1. Enable kgdboc on ttyS0
+1. Enable kgdboc on ttyS0::
- ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+ echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
-2. Disable kgdboc
+2. Disable kgdboc::
- ``echo "" > /sys/module/kgdboc/parameters/kgdboc``
+ echo "" > /sys/module/kgdboc/parameters/kgdboc
-NOTE: You do not need to specify the baud if you are configuring the
-console on tty which is already configured or open.
+.. note::
+
+ You do not need to specify the baud if you are configuring the
+ console on tty which is already configured or open.
More examples
^^^^^^^^^^^^^
@@ -224,35 +225,42 @@ You can configure kgdboc to use the keyboard, and/or a serial device
depending on if you are using kdb and/or kgdb, in one of the following
scenarios.
-1. kdb and kgdb over only a serial port
+1. kdb and kgdb over only a serial port::
- ``kgdboc=<serial_device>[,baud]``
+ kgdboc=<serial_device>[,baud]
- Example: ``kgdboc=ttyS0,115200``
+ Example::
-2. kdb and kgdb with keyboard and a serial port
+ kgdboc=ttyS0,115200
- ``kgdboc=kbd,<serial_device>[,baud]``
+2. kdb and kgdb with keyboard and a serial port::
- Example: ``kgdboc=kbd,ttyS0,115200``
+ kgdboc=kbd,<serial_device>[,baud]
-3. kdb with a keyboard
+ Example::
- ``kgdboc=kbd``
+ kgdboc=kbd,ttyS0,115200
-4. kdb with kernel mode setting
+3. kdb with a keyboard::
- ``kgdboc=kms,kbd``
+ kgdboc=kbd
-5. kdb with kernel mode setting and kgdb over a serial port
+4. kdb with kernel mode setting::
- ``kgdboc=kms,kbd,ttyS0,115200``
+ kgdboc=kms,kbd
-NOTE: Kgdboc does not support interrupting the target via the gdb remote
-protocol. You must manually send a sysrq-g unless you have a proxy that
-splits console output to a terminal program. A console proxy has a
-separate TCP port for the debugger and a separate TCP port for the
-"human" console. The proxy can take care of sending the sysrq-g for you.
+5. kdb with kernel mode setting and kgdb over a serial port::
+
+ kgdboc=kms,kbd,ttyS0,115200
+
+.. note::
+
+ Kgdboc does not support interrupting the target via the gdb remote
+ protocol. You must manually send a :kbd:`SysRq-G` unless you have a proxy
+ that splits console output to a terminal program. A console proxy has a
+ separate TCP port for the debugger and a separate TCP port for the
+ "human" console. The proxy can take care of sending the :kbd:`SysRq-G`
+ for you.
When using kgdboc with no debugger proxy, you can end up connecting the
debugger at one of two entry points. If an exception occurs after you
@@ -260,14 +268,14 @@ have loaded kgdboc, a message should print on the console stating it is
waiting for the debugger. In this case you disconnect your terminal
program and then connect the debugger in its place. If you want to
interrupt the target system and forcibly enter a debug session you have
-to issue a Sysrq sequence and then type the letter ``g``. Then you
+to issue a :kbd:`Sysrq` sequence and then type the letter :kbd:`g`. Then you
disconnect the terminal session and connect gdb. Your options if you
-don't like this are to hack gdb to send the sysrq-g for you as well as
+don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as
on the initial connect, or to use a debugger proxy that allows an
unmodified gdb to do the debugging.
-Kernel parameter: kgdbwait
---------------------------
+Kernel parameter: ``kgdbwait``
+------------------------------
The Kernel command line option ``kgdbwait`` makes kgdb wait for a
debugger connection during booting of a kernel. You can only use this
@@ -281,54 +289,64 @@ The kernel will stop and wait as early as the I/O driver and
architecture allows when you use this option. If you build the kgdb I/O
driver as a loadable kernel module kgdbwait will not do anything.
-Kernel parameter: kgdbcon
--------------------------
+Kernel parameter: ``kgdbcon``
+-----------------------------
-The kgdbcon feature allows you to see printk() messages inside gdb while
-gdb is connected to the kernel. Kdb does not make use of the kgdbcon
+The ``kgdbcon`` feature allows you to see :c:func:`printk` messages inside gdb
+while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
feature.
Kgdb supports using the gdb serial protocol to send console messages to
the debugger when the debugger is connected and running. There are two
ways to activate this feature.
-1. Activate with the kernel command line option:
+1. Activate with the kernel command line option::
- ``kgdbcon``
+ kgdbcon
-2. Use sysfs before configuring an I/O driver
+2. Use sysfs before configuring an I/O driver::
- ``echo 1 > /sys/module/kgdb/parameters/kgdb_use_con``
+ echo 1 > /sys/module/kgdb/parameters/kgdb_use_con
- NOTE: If you do this after you configure the kgdb I/O driver, the
+.. note::
+
+ If you do this after you configure the kgdb I/O driver, the
setting will not take effect until the next point the I/O is
reconfigured.
-IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an
-active system console. An example of incorrect usage is
-``console=ttyS0,115200 kgdboc=ttyS0 kgdbcon``
+.. important::
+
+ You cannot use kgdboc + kgdbcon on a tty that is an
+ active system console. An example of incorrect usage is::
+
+ console=ttyS0,115200 kgdboc=ttyS0 kgdbcon
It is possible to use this option with kgdboc on a tty that is not a
system console.
-Run time parameter: kgdbreboot
-------------------------------
+Run time parameter: ``kgdbreboot``
+----------------------------------
The kgdbreboot feature allows you to change how the debugger deals with
the reboot notification. You have 3 choices for the behavior. The
default behavior is always set to 0.
-1. echo -1 > /sys/module/debug_core/parameters/kgdbreboot
+.. tabularcolumns:: |p{0.4cm}|p{11.5cm}|p{5.6cm}|
- Ignore the reboot notification entirely.
+.. flat-table::
+ :widths: 1 10 8
-2. echo 0 > /sys/module/debug_core/parameters/kgdbreboot
+ * - 1
+ - ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot``
+ - Ignore the reboot notification entirely.
- Send the detach message to any attached debugger client.
+ * - 2
+ - ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot``
+ - Send the detach message to any attached debugger client.
-3. echo 1 > /sys/module/debug_core/parameters/kgdbreboot
-
- Enter the debugger on reboot notify.
+ * - 3
+ - ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot``
+ - Enter the debugger on reboot notify.
Using kdb
=========
@@ -338,66 +356,56 @@ Quick start for kdb on a serial port
This is a quick example of how to use kdb.
-1. Configure kgdboc at boot using kernel parameters:
+1. Configure kgdboc at boot using kernel parameters::
- - ``console=ttyS0,115200 kgdboc=ttyS0,115200``
+ console=ttyS0,115200 kgdboc=ttyS0,115200
OR
Configure kgdboc after the kernel has booted; assuming you are using
- a serial port console:
+ a serial port console::
- - ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+ echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
2. Enter the kernel debugger manually or by waiting for an oops or
fault. There are several ways you can enter the kernel debugger
- manually; all involve using the sysrq-g, which means you must have
- enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.
+ manually; all involve using the :kbd:`SysRq-G`, which means you must have
+ enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
- - When logged in as root or with a super user session you can run:
+ - When logged in as root or with a super user session you can run::
- ``echo g > /proc/sysrq-trigger``
+ echo g > /proc/sysrq-trigger
- Example using minicom 2.2
- Press: ``Control-a``
-
- Press: ``f``
-
- Press: ``g``
+ Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
- When you have telneted to a terminal server that supports sending
a remote break
- Press: ``Control-]``
+ Press: :kbd:`CTRL-]`
- Type in:\ ``send break``
+ Type in: ``send break``
- Press: ``Enter``
+ Press: :kbd:`Enter` :kbd:`g`
- Press: ``g``
-
-3. From the kdb prompt you can run the "help" command to see a complete
+3. From the kdb prompt you can run the ``help`` command to see a complete
list of the commands that are available.
Some useful commands in kdb include:
- - lsmod -- Shows where kernel modules are loaded
-
- - ps -- Displays only the active processes
-
- - ps A -- Shows all the processes
-
- - summary -- Shows kernel version info and memory usage
-
- - bt -- Get a backtrace of the current process using dump_stack()
-
- - dmesg -- View the kernel syslog buffer
-
- - go -- Continue the system
+ =========== =================================================================
+ ``lsmod`` Shows where kernel modules are loaded
+ ``ps`` Displays only the active processes
+ ``ps A`` Shows all the processes
+ ``summary`` Shows kernel version info and memory usage
+ ``bt`` Get a backtrace of the current process using :c:func:`dump_stack`
+ ``dmesg`` View the kernel syslog buffer
+ ``go`` Continue the system
+ =========== =================================================================
4. When you are done using kdb you need to consider rebooting the system
- or using the "go" command to resuming normal kernel execution. If you
+ or using the ``go`` command to resuming normal kernel execution. If you
have paused the kernel for a lengthy period of time, applications
that rely on timely networking or anything to do with real wall clock
time could be adversely affected, so you should take this into
@@ -408,50 +416,50 @@ Quick start for kdb using a keyboard connected console
This is a quick example of how to use kdb with a keyboard.
-1. Configure kgdboc at boot using kernel parameters:
+1. Configure kgdboc at boot using kernel parameters::
- - ``kgdboc=kbd``
+ kgdboc=kbd
OR
- Configure kgdboc after the kernel has booted:
+ Configure kgdboc after the kernel has booted::
- - ``echo kbd > /sys/module/kgdboc/parameters/kgdboc``
+ echo kbd > /sys/module/kgdboc/parameters/kgdboc
2. Enter the kernel debugger manually or by waiting for an oops or
fault. There are several ways you can enter the kernel debugger
- manually; all involve using the sysrq-g, which means you must have
- enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.
+ manually; all involve using the :kbd:`SysRq-G`, which means you must have
+ enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
- - When logged in as root or with a super user session you can run:
+ - When logged in as root or with a super user session you can run::
- ``echo g > /proc/sysrq-trigger``
+ echo g > /proc/sysrq-trigger
- - Example using a laptop keyboard
+ - Example using a laptop keyboard:
- Press and hold down: ``Alt``
+ Press and hold down: :kbd:`Alt`
- Press and hold down: ``Fn``
+ Press and hold down: :kbd:`Fn`
- Press and release the key with the label: ``SysRq``
+ Press and release the key with the label: :kbd:`SysRq`
- Release: ``Fn``
+ Release: :kbd:`Fn`
- Press and release: ``g``
+ Press and release: :kbd:`g`
- Release: ``Alt``
+ Release: :kbd:`Alt`
- Example using a PS/2 101-key keyboard
- Press and hold down: ``Alt``
+ Press and hold down: :kbd:`Alt`
- Press and release the key with the label: ``SysRq``
+ Press and release the key with the label: :kbd:`SysRq`
- Press and release: ``g``
+ Press and release: :kbd:`g`
- Release: ``Alt``
+ Release: :kbd:`Alt`
-3. Now type in a kdb command such as "help", "dmesg", "bt" or "go" to
+3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to
continue kernel execution.
Using kgdb / gdb
@@ -477,61 +485,51 @@ Connecting with gdb to a serial port
1. Configure kgdboc
- Configure kgdboc at boot using kernel parameters:
+ Configure kgdboc at boot using kernel parameters::
- - ``kgdboc=ttyS0,115200``
+ kgdboc=ttyS0,115200
OR
- Configure kgdboc after the kernel has booted:
+ Configure kgdboc after the kernel has booted::
- - ``echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc``
+ echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
2. Stop kernel execution (break into the debugger)
In order to connect to gdb via kgdboc, the kernel must first be
stopped. There are several ways to stop the kernel which include
- using kgdbwait as a boot argument, via a sysrq-g, or running the
+ using kgdbwait as a boot argument, via a :kbd:`SysRq-G`, or running the
kernel until it takes an exception where it waits for the debugger to
attach.
- - When logged in as root or with a super user session you can run:
+ - When logged in as root or with a super user session you can run::
- ``echo g > /proc/sysrq-trigger``
+ echo g > /proc/sysrq-trigger
- Example using minicom 2.2
- Press: ``Control-a``
-
- Press: ``f``
-
- Press: ``g``
+ Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
- When you have telneted to a terminal server that supports sending
a remote break
- Press: ``Control-]``
+ Press: :kbd:`CTRL-]`
- Type in:\ ``send break``
+ Type in: ``send break``
- Press: ``Enter``
-
- Press: ``g``
+ Press: :kbd:`Enter` :kbd:`g`
3. Connect from gdb
- Example (using a directly connected port):
-
- ::
+ Example (using a directly connected port)::
% gdb ./vmlinux
(gdb) set remotebaud 115200
(gdb) target remote /dev/ttyS0
- Example (kgdb to a terminal server on TCP port 2012):
-
- ::
+ Example (kgdb to a terminal server on TCP port 2012)::
% gdb ./vmlinux
(gdb) target remote 192.168.2.2:2012
@@ -543,12 +541,13 @@ Connecting with gdb to a serial port
If you are having problems connecting or something is going seriously
wrong while debugging, it will most often be the case that you want
to enable gdb to be verbose about its target communications. You do
- this prior to issuing the ``target
- remote`` command by typing in: ``set debug remote 1``
+ this prior to issuing the ``target remote`` command by typing in::
+
+ set debug remote 1
Remember if you continue in gdb, and need to "break in" again, you need
-to issue an other sysrq-g. It is easy to create a simple entry point by
-putting a breakpoint at ``sys_sync`` and then you can run "sync" from a
+to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by
+putting a breakpoint at ``sys_sync`` and then you can run ``sync`` from a
shell or script to break into the debugger.
kgdb and kdb interoperability
@@ -565,22 +564,26 @@ Switching from kgdb to kdb
~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two ways to switch from kgdb to kdb: you can use gdb to issue
-a maintenance packet, or you can blindly type the command $3#33.
+a maintenance packet, or you can blindly type the command ``$3#33``.
Whenever the kernel debugger stops in kgdb mode it will print the
message ``KGDB or $3#33 for KDB``. It is important to note that you have
to type the sequence correctly in one pass. You cannot type a backspace
or delete because kgdb will interpret that as part of the debug stream.
-1. Change from kgdb to kdb by blindly typing:
+1. Change from kgdb to kdb by blindly typing::
- ``$3#33``
+ $3#33
-2. Change from kgdb to kdb with gdb
+2. Change from kgdb to kdb with gdb::
- ``maintenance packet 3``
+ maintenance packet 3
- NOTE: Now you must kill gdb. Typically you press control-z and issue
- the command: kill -9 %
+ .. note::
+
+ Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue
+ the command::
+
+ kill -9 %
Change from kdb to kgdb
~~~~~~~~~~~~~~~~~~~~~~~
@@ -592,9 +595,9 @@ shell looks for the typical first commands that gdb would issue with the
gdb remote protocol and if it sees one of those commands it
automatically changes into kgdb mode.
-1. From kdb issue the command:
+1. From kdb issue the command::
- ``kgdb``
+ kgdb
Now disconnect your terminal program and connect gdb in its place
@@ -613,13 +616,7 @@ are things like lsmod, dmesg, ps or possibly some of the memory
information commands. To see all the kdb commands you can run
``monitor help``.
-Example:
-
-.. raw:: html
-
- <div class="informalexample">
-
-::
+Example::
(gdb) monitor ps
1 idle process (state I) and
@@ -632,30 +629,25 @@ Example:
0xc78789c0 944 1 0 0 S 0xc7878bf4 sh
(gdb)
-
-.. raw:: html
-
- </div>
-
kgdb Test Suite
===============
When kgdb is enabled in the kernel config you can also elect to enable
-the config parameter KGDB_TESTS. Turning this on will enable a special
+the config parameter ``KGDB_TESTS``. Turning this on will enable a special
kgdb I/O module which is designed to test the kgdb internal functions.
The kgdb tests are mainly intended for developers to test the kgdb
internals as well as a tool for developing a new kgdb architecture
specific implementation. These tests are not really for end users of the
Linux kernel. The primary source of documentation would be to look in
-the drivers/misc/kgdbts.c file.
+the ``drivers/misc/kgdbts.c`` file.
The kgdb test suite can also be configured at compile time to run the
core set of tests by setting the kernel config parameter
-KGDB_TESTS_ON_BOOT. This particular option is aimed at automated
+``KGDB_TESTS_ON_BOOT``. This particular option is aimed at automated
regression testing and does not require modifying the kernel boot config
arguments. If this is turned on, the kgdb test suite can be disabled by
-specifying "kgdbts=" as a kernel boot argument.
+specifying ``kgdbts=`` as a kernel boot argument.
Kernel Debugger Internals
=========================
@@ -667,7 +659,7 @@ The kernel debugger is organized into a number of components:
1. The debug core
- The debug core is found in kernel/debugger/debug_core.c. It
+ The debug core is found in ``kernel/debugger/debug_core.c``. It
contains:
- A generic OS exception handler which includes sync'ing the
@@ -688,20 +680,20 @@ The kernel debugger is organized into a number of components:
- The structures and callback API for atomic kernel mode setting.
- NOTE: kgdboc is where the kms callbacks are invoked.
+ .. note:: kgdboc is where the kms callbacks are invoked.
2. kgdb arch-specific implementation
- This implementation is generally found in arch/\*/kernel/kgdb.c. As
- an example, arch/x86/kernel/kgdb.c contains the specifics to
+ This implementation is generally found in ``arch/*/kernel/kgdb.c``. As
+ an example, ``arch/x86/kernel/kgdb.c`` contains the specifics to
implement HW breakpoint as well as the initialization to dynamically
register and unregister for the trap handlers on this architecture.
The arch-specific portion implements:
- contains an arch-specific trap catcher which invokes
- kgdb_handle_exception() to start kgdb about doing its work
+ :c:func:`kgdb_handle_exception` to start kgdb about doing its work
- - translation to and from gdb specific packet format to pt_regs
+ - translation to and from gdb specific packet format to :c:type:`pt_regs`
- Registration and unregistration of architecture specific trap
hooks
@@ -714,7 +706,7 @@ The kernel debugger is organized into a number of components:
3. gdbstub frontend (aka kgdb)
- The gdbstub is located in kernel/debug/gdbstub.c. It contains:
+ The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains:
- All the logic to implement the gdb serial protocol
@@ -733,18 +725,18 @@ The kernel debugger is organized into a number of components:
- A registration API to register additional kdb shell commands.
- - A good example of a self-contained kdb module is the "ftdump"
+ - A good example of a self-contained kdb module is the ``ftdump``
command for dumping the ftrace buffer. See:
- kernel/trace/trace_kdb.c
+ ``kernel/trace/trace_kdb.c``
- For an example of how to dynamically register a new kdb command
you can build the kdb_hello.ko kernel module from
- samples/kdb/kdb_hello.c. To build this example you can set
- CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel
- config. Later run "modprobe kdb_hello" and the next time you
- enter the kdb shell, you can run the "hello" command.
+ ``samples/kdb/kdb_hello.c``. To build this example you can set
+ ``CONFIG_SAMPLES=y`` and ``CONFIG_SAMPLE_KDB=m`` in your kernel
+ config. Later run ``modprobe kdb_hello`` and the next time you
+ enter the kdb shell, you can run the ``hello`` command.
- - The implementation for kdb_printf() which emits messages directly
+ - The implementation for :c:func:`kdb_printf` which emits messages directly
to I/O drivers, bypassing the kernel log.
- SW / HW breakpoint management for the kdb shell
@@ -780,21 +772,24 @@ architecture, and at that point you must create an architecture specific
kgdb implementation.
There are a few flags which must be set on every architecture in their
-<asm/kgdb.h> file. These are:
+``asm/kgdb.h`` file. These are:
-- NUMREGBYTES: The size in bytes of all of the registers, so that we
- can ensure they will all fit into a packet.
+- ``NUMREGBYTES``:
+ The size in bytes of all of the registers, so that we
+ can ensure they will all fit into a packet.
-- BUFMAX: The size in bytes of the buffer GDB will read into. This must
- be larger than NUMREGBYTES.
+- ``BUFMAX``:
+ The size in bytes of the buffer GDB will read into. This must
+ be larger than NUMREGBYTES.
-- CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
- flush_cache_range or flush_icache_range. On some architectures,
- these functions may not be safe to call on SMP since we keep other
- CPUs in a holding pattern.
+- ``CACHE_FLUSH_IS_SAFE``:
+ Set to 1 if it is always safe to call
+ flush_cache_range or flush_icache_range. On some architectures,
+ these functions may not be safe to call on SMP since we keep other
+ CPUs in a holding pattern.
There are also the following functions for the common backend, found in
-kernel/kgdb.c, that must be supplied by the architecture-specific
+``kernel/kgdb.c``, that must be supplied by the architecture-specific
backend unless marked as (optional), in which case a default function
maybe used if the architecture does not need to provide a specific
implementation.
@@ -818,9 +813,9 @@ invokes a callback in the serial core which in turn uses the callback in
the UART driver.
When using kgdboc with a UART, the UART driver must implement two
-callbacks in the ``struct uart_ops``. Example from drivers/8250.c:
+callbacks in the :c:type:`struct uart_ops <uart_ops>`.
+Example from ``drivers/8250.c``::
-::
#ifdef CONFIG_CONSOLE_POLL
.poll_get_char = serial8250_get_poll_char,
@@ -838,46 +833,41 @@ consider, because failing here is most likely going to mean pressing the
reset button.
kgdboc and keyboards
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
The kgdboc driver contains logic to configure communications with an
attached keyboard. The keyboard infrastructure is only compiled into the
-kernel when CONFIG_KDB_KEYBOARD=y is set in the kernel configuration.
+kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
The core polled keyboard driver driver for PS/2 type keyboards is in
-drivers/char/kdb_keyboard.c. This driver is hooked into the debug core
+``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
when kgdboc populates the callback in the array called
-``kdb_poll_funcs[]``. The kdb_get_kbd_char() is the top-level
+:c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level
function which polls hardware for single character input.
kgdboc and kms
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
The kgdboc driver contains logic to request the graphics display to
-switch to a text context when you are using "kgdboc=kms,kbd", provided
+switch to a text context when you are using ``kgdboc=kms,kbd``, provided
that you have a video driver which has a frame buffer console and atomic
kernel mode setting support.
Every time the kernel debugger is entered it calls
-kgdboc_pre_exp_handler() which in turn calls con_debug_enter() in
-the virtual console layer. On resuming kernel execution, the kernel
-debugger calls kgdboc_post_exp_handler() which in turn calls
-con_debug_leave().
+:c:func:`kgdboc_pre_exp_handler` which in turn calls :c:func:`con_debug_enter`
+in the virtual console layer. On resuming kernel execution, the kernel
+debugger calls :c:func:`kgdboc_post_exp_handler` which in turn calls
+:c:func:`con_debug_leave`.
Any video driver that wants to be compatible with the kernel debugger
-and the atomic kms callbacks must implement the mode_set_base_atomic,
-fb_debug_enter and fb_debug_leave operations. For the
-fb_debug_enter and fb_debug_leave the option exists to use the
+and the atomic kms callbacks must implement the ``mode_set_base_atomic``,
+``fb_debug_enter`` and ``fb_debug_leave operations``. For the
+``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the
generic drm fb helper functions or implement something custom for the
hardware. The following example shows the initialization of the
.mode_set_base_atomic operation in
-drivers/gpu/drm/i915/intel_display.c:
+drivers/gpu/drm/i915/intel_display.c::
-.. raw:: html
-
- <div class="informalexample">
-
-::
static const struct drm_crtc_helper_funcs intel_helper_funcs = {
[...]
@@ -886,19 +876,10 @@ drivers/gpu/drm/i915/intel_display.c:
};
-.. raw:: html
-
- </div>
-
Here is an example of how the i915 driver initializes the
fb_debug_enter and fb_debug_leave functions to use the generic drm
-helpers in drivers/gpu/drm/i915/intel_fb.c:
+helpers in ``drivers/gpu/drm/i915/intel_fb.c``::
-.. raw:: html
-
- <div class="informalexample">
-
-::
static struct fb_ops intelfb_ops = {
[...]
@@ -908,23 +889,19 @@ helpers in drivers/gpu/drm/i915/intel_fb.c:
};
-.. raw:: html
-
- </div>
-
Credits
=======
The following people have contributed to this document:
-1. Amit Kale\ amitkale@linsyssoft.com
+1. Amit Kale <amitkale@linsyssoft.com>
-2. Tom Rini\ trini@kernel.crashing.org
+2. Tom Rini <trini@kernel.crashing.org>
In March 2008 this document was completely rewritten by:
-- Jason Wessel\ jason.wessel@windriver.com
+- Jason Wessel <jason.wessel@windriver.com>
In Jan 2010 this document was updated to include kdb.
-- Jason Wessel\ jason.wessel@windriver.com
+- Jason Wessel <jason.wessel@windriver.com>
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 47/53] irq: update genericirq book location |
| Message-ID | <tHJLY-5yL-27@gated-at.bofh.it> |
| In reply to | #1642478 |
This book got converted from DocBook. Update its references to point to the current location. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- kernel/irq/chip.c | 2 +- kernel/irq/handle.c | 2 +- kernel/irq/irqdesc.c | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/kernel/irq/chip.c b/kernel/irq/chip.c index 686be4b73018..4188a0a7691f 100644 --- a/kernel/irq/chip.c +++ b/kernel/irq/chip.c @@ -7,7 +7,7 @@ * This file contains the core interrupt handling code, for irq-chip * based architectures. * - * Detailed information is available in Documentation/DocBook/genericirq + * Detailed information is available in Documentation/core-api/genericirq.rst */ #include <linux/irq.h> diff --git a/kernel/irq/handle.c b/kernel/irq/handle.c index d3f24905852c..bbf9a7174283 100644 --- a/kernel/irq/handle.c +++ b/kernel/irq/handle.c @@ -6,7 +6,7 @@ * * This file contains the core interrupt handling code. * - * Detailed information is available in Documentation/DocBook/genericirq + * Detailed information is available in Documentation/core-api/genericirq.rst * */ diff --git a/kernel/irq/irqdesc.c b/kernel/irq/irqdesc.c index 00bb0aeea1d0..22e443133987 100644 --- a/kernel/irq/irqdesc.c +++ b/kernel/irq/irqdesc.c @@ -4,7 +4,7 @@ * * This file contains the interrupt descriptor management code * - * Detailed information is available in Documentation/DocBook/genericirq + * Detailed information is available in Documentation/core-api/genericirq.rst * */ #include <linux/irq.h> -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 41/53] docs-rst: convert lsm from DocBook to ReST |
| Message-ID | <tHJLZ-5yL-31@gated-at.bofh.it> |
| In reply to | #1642478 |
This file is outdated. Still, as it is the only one left at DocBook dir, convert it, and store it, with a .txt extension, under Documentation/lsm.txt. This way, we can get rid of DocBook from the building system, without needing to wait for someone to take care of it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/00-INDEX | 2 + Documentation/DocBook/Makefile | 275 ----------------------------------------- Documentation/DocBook/lsm.tmpl | 265 --------------------------------------- Documentation/lsm.txt | 201 ++++++++++++++++++++++++++++++ 4 files changed, 203 insertions(+), 540 deletions(-) delete mode 100644 Documentation/DocBook/lsm.tmpl create mode 100644 Documentation/lsm.txt diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 793acf999e9e..8c2a66e176b9 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -264,6 +264,8 @@ logo.gif - full colour GIF image of Linux logo (penguin - Tux). logo.txt - info on creator of above logo & site to get additional images from. +lsm.txt + - Linux Security Modules: General Security Hooks for Linux lzo.txt - kernel LZO decompressor input formats m68k/ diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index efba7f980895..8b137891791f 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -1,276 +1 @@ -### -# This makefile is used to generate the kernel documentation, -# primarily based on in-line comments in various source files. -# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how -# to document the SRC - and how to read it. -# To add a new book the only step required is to add the book to the -# list of DOCBOOKS. -DOCBOOKS := lsm.xml - -ifeq ($(DOCBOOKS),) - -# Skip DocBook build if the user explicitly requested no DOCBOOKS. -.DEFAULT: - @echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)." -else -ifneq ($(SPHINXDIRS),) - -# Skip DocBook build if the user explicitly requested a sphinx dir -.DEFAULT: - @echo " SKIP DocBook $@ target (SPHINXDIRS specified)." -else - - -### -# The build process is as follows (targets): -# (xmldocs) [by docproc] -# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto] -# +--> file.pdf (pdfdocs) [by db2pdf or xmlto] -# +--> DIR=file (htmldocs) [by xmlto] -# +--> man/ (mandocs) [by xmlto] - - -# for PDF and PS output you can choose between xmlto and docbook-utils tools -PDF_METHOD = $(prefer-db2x) -PS_METHOD = $(prefer-db2x) - - -targets += $(DOCBOOKS) -BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) -xmldocs: $(BOOKS) -sgmldocs: xmldocs - -PS := $(patsubst %.xml, %.ps, $(BOOKS)) -psdocs: $(PS) - -PDF := $(patsubst %.xml, %.pdf, $(BOOKS)) -pdfdocs: $(PDF) - -HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) -htmldocs: $(HTML) - $(call cmd,build_main_index) - -MAN := $(patsubst %.xml, %.9, $(BOOKS)) -mandocs: $(MAN) - find $(obj)/man -name '*.9' | xargs gzip -nf - -# Default location for installed man pages -export INSTALL_MAN_PATH = $(objtree)/usr - -installmandocs: mandocs - mkdir -p $(INSTALL_MAN_PATH)/man/man9/ - find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \ - sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ - xargs install -m 644 -t $(INSTALL_MAN_PATH)/man/man9/ - -# no-op for the DocBook toolchain -epubdocs: -latexdocs: -linkcheckdocs: - -### -#External programs used -KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref -KERNELDOC = $(srctree)/scripts/kernel-doc -DOCPROC = $(objtree)/scripts/docproc -CHECK_LC_CTYPE = $(objtree)/scripts/check-lc_ctype - -# Use a fixed encoding - UTF-8 if the C library has support built-in -# or ASCII if not -LC_CTYPE := $(call try-run, LC_CTYPE=C.UTF-8 $(CHECK_LC_CTYPE),C.UTF-8,C) -export LC_CTYPE - -XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl -XMLTOFLAGS += --skip-validation - -### -# DOCPROC is used for two purposes: -# 1) To generate a dependency list for a .tmpl file -# 2) To preprocess a .tmpl file and call kernel-doc with -# appropriate parameters. -# The following rules are used to generate the .xml documentation -# required to generate the final targets. (ps, pdf, html). -quiet_cmd_docproc = DOCPROC $@ - cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@ -define rule_docproc - set -e; \ - $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \ - $(cmd_$(1)); \ - ( \ - echo 'cmd_$@ := $(cmd_$(1))'; \ - echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \ - ) > $(dir $@).$(notdir $@).cmd -endef - -%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE - $(call if_changed_rule,docproc) - -# Tell kbuild to always build the programs -always := $(hostprogs-y) - -notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \ - exit 1 -db2xtemplate = db2TYPE -o $(dir $@) $< -xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $< - -# determine which methods are available -ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found) - use-db2x = db2x - prefer-db2x = db2x -else - use-db2x = notfound - prefer-db2x = $(use-xmlto) -endif -ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found) - use-xmlto = xmlto - prefer-xmlto = xmlto -else - use-xmlto = notfound - prefer-xmlto = $(use-db2x) -endif - -# the commands, generated from the chosen template -quiet_cmd_db2ps = PS $@ - cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template)) -%.ps : %.xml - $(call cmd,db2ps) - -quiet_cmd_db2pdf = PDF $@ - cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template)) -%.pdf : %.xml - $(call cmd,db2pdf) - - -index = index.html -main_idx = $(obj)/$(index) -quiet_cmd_build_main_index = HTML $(main_idx) - cmd_build_main_index = rm -rf $(main_idx); \ - echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \ - echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \ - cat $(HTML) >> $(main_idx) - -quiet_cmd_db2html = HTML $@ - cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ - echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ - $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ - -### -# Rules to create an aux XML and .db, and use them to re-process the DocBook XML -# to fill internal hyperlinks - gen_aux_xml = : - quiet_gen_aux_xml = echo ' XMLREF $@' -silent_gen_aux_xml = : -%.aux.xml: %.xml - @$($(quiet)gen_aux_xml) - @rm -rf $@ - @(cat $< | egrep "^<refentry id" | egrep -o "\".*\"" | cut -f 2 -d \" > $<.db) - @$(KERNELDOCXMLREF) -db $<.db $< > $@ -.PRECIOUS: %.aux.xml - -%.html: %.aux.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ - exit 1) - @rm -rf $@ $(patsubst %.html,%,$@) - $(call cmd,db2html) - @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ - cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi - -quiet_cmd_db2man = MAN $@ - cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi -%.9 : %.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ - exit 1) - $(Q)mkdir -p $(obj)/man/$(*F) - $(call cmd,db2man) - @touch $@ - -### -# Rules to generate postscripts and PNG images from .fig format files -quiet_cmd_fig2eps = FIG2EPS $@ - cmd_fig2eps = fig2dev -Leps $< $@ - -%.eps: %.fig - @(which fig2dev > /dev/null 2>&1) || \ - (echo "*** You need to install transfig ***"; \ - exit 1) - $(call cmd,fig2eps) - -quiet_cmd_fig2png = FIG2PNG $@ - cmd_fig2png = fig2dev -Lpng $< $@ - -%.png: %.fig - @(which fig2dev > /dev/null 2>&1) || \ - (echo "*** You need to install transfig ***"; \ - exit 1) - $(call cmd,fig2png) - -### -# Rule to convert a .c file to inline XML documentation - gen_xml = : - quiet_gen_xml = echo ' GEN $@' -silent_gen_xml = : -%.xml: %.c - @$($(quiet)gen_xml) - @( \ - echo "<programlisting>"; \ - expand --tabs=8 < $< | \ - sed -e "s/&/\\&/g" \ - -e "s/</\\</g" \ - -e "s/>/\\>/g"; \ - echo "</programlisting>") > $@ - -endif # DOCBOOKS="" -endif # SPHINDIR=... - -### -# Help targets as used by the top-level makefile -dochelp: - @echo ' Linux kernel internal documentation in different formats (DocBook):' - @echo ' htmldocs - HTML' - @echo ' pdfdocs - PDF' - @echo ' psdocs - Postscript' - @echo ' xmldocs - XML DocBook' - @echo ' mandocs - man pages' - @echo ' installmandocs - install man pages generated by mandocs to INSTALL_MAN_PATH'; \ - echo ' (default: $(INSTALL_MAN_PATH))'; \ - echo '' - @echo ' cleandocs - clean all generated DocBook files' - @echo - @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' - @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' - @echo - @echo " make DOCBOOKS=\"\" [target] Don't generate docs from Docbook" - @echo ' This is useful to generate only the ReST docs (Sphinx)' - - -### -# Temporary files left by various tools -clean-files := $(DOCBOOKS) \ - $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ - $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ - $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ - $(patsubst %.xml, %.log, $(DOCBOOKS)) \ - $(patsubst %.xml, %.out, $(DOCBOOKS)) \ - $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ - $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ - $(patsubst %.xml, %.html, $(DOCBOOKS)) \ - $(patsubst %.xml, %.9, $(DOCBOOKS)) \ - $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ - $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ - $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ - $(patsubst %.xml, .%.xml.cmd, $(DOCBOOKS)) \ - $(index) - -clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man - -cleandocs: - $(Q)rm -f $(call objectify, $(clean-files)) - $(Q)rm -rf $(call objectify, $(clean-dirs)) - -# Declare the contents of the .PHONY variable as phony. We keep that -# information in a variable so we can use it in if_changed and friends. - -.PHONY: $(PHONY) diff --git a/Documentation/DocBook/lsm.tmpl b/Documentation/DocBook/lsm.tmpl deleted file mode 100644 index fe7664ce9667..000000000000 --- a/Documentation/DocBook/lsm.tmpl +++ /dev/null @@ -1,265 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<article class="whitepaper" id="LinuxSecurityModule" lang="en"> - <articleinfo> - <title>Linux Security Modules: General Security Hooks for Linux</title> - <authorgroup> - <author> - <firstname>Stephen</firstname> - <surname>Smalley</surname> - <affiliation> - <orgname>NAI Labs</orgname> - <address><email>ssmalley@nai.com</email></address> - </affiliation> - </author> - <author> - <firstname>Timothy</firstname> - <surname>Fraser</surname> - <affiliation> - <orgname>NAI Labs</orgname> - <address><email>tfraser@nai.com</email></address> - </affiliation> - </author> - <author> - <firstname>Chris</firstname> - <surname>Vance</surname> - <affiliation> - <orgname>NAI Labs</orgname> - <address><email>cvance@nai.com</email></address> - </affiliation> - </author> - </authorgroup> - </articleinfo> - -<sect1 id="Introduction"><title>Introduction</title> - -<para> -In March 2001, the National Security Agency (NSA) gave a presentation -about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel -Summit. SELinux is an implementation of flexible and fine-grained -nondiscretionary access controls in the Linux kernel, originally -implemented as its own particular kernel patch. Several other -security projects (e.g. RSBAC, Medusa) have also developed flexible -access control architectures for the Linux kernel, and various -projects have developed particular access control models for Linux -(e.g. LIDS, DTE, SubDomain). Each project has developed and -maintained its own kernel patch to support its security needs. -</para> - -<para> -In response to the NSA presentation, Linus Torvalds made a set of -remarks that described a security framework he would be willing to -consider for inclusion in the mainstream Linux kernel. He described a -general framework that would provide a set of security hooks to -control operations on kernel objects and a set of opaque security -fields in kernel data structures for maintaining security attributes. -This framework could then be used by loadable kernel modules to -implement any desired model of security. Linus also suggested the -possibility of migrating the Linux capabilities code into such a -module. -</para> - -<para> -The Linux Security Modules (LSM) project was started by WireX to -develop such a framework. LSM is a joint development effort by -several security projects, including Immunix, SELinux, SGI and Janus, -and several individuals, including Greg Kroah-Hartman and James -Morris, to develop a Linux kernel patch that implements this -framework. The patch is currently tracking the 2.4 series and is -targeted for integration into the 2.5 development series. This -technical report provides an overview of the framework and the example -capabilities security module provided by the LSM kernel patch. -</para> - -</sect1> - -<sect1 id="framework"><title>LSM Framework</title> - -<para> -The LSM kernel patch provides a general kernel framework to support -security modules. In particular, the LSM framework is primarily -focused on supporting access control modules, although future -development is likely to address other security needs such as -auditing. By itself, the framework does not provide any additional -security; it merely provides the infrastructure to support security -modules. The LSM kernel patch also moves most of the capabilities -logic into an optional security module, with the system defaulting -to the traditional superuser logic. This capabilities module -is discussed further in <xref linkend="cap"/>. -</para> - -<para> -The LSM kernel patch adds security fields to kernel data structures -and inserts calls to hook functions at critical points in the kernel -code to manage the security fields and to perform access control. It -also adds functions for registering and unregistering security -modules, and adds a general <function>security</function> system call -to support new system calls for security-aware applications. -</para> - -<para> -The LSM security fields are simply <type>void*</type> pointers. For -process and program execution security information, security fields -were added to <structname>struct task_struct</structname> and -<structname>struct linux_binprm</structname>. For filesystem security -information, a security field was added to -<structname>struct super_block</structname>. For pipe, file, and socket -security information, security fields were added to -<structname>struct inode</structname> and -<structname>struct file</structname>. For packet and network device security -information, security fields were added to -<structname>struct sk_buff</structname> and -<structname>struct net_device</structname>. For System V IPC security -information, security fields were added to -<structname>struct kern_ipc_perm</structname> and -<structname>struct msg_msg</structname>; additionally, the definitions -for <structname>struct msg_msg</structname>, <structname>struct -msg_queue</structname>, and <structname>struct -shmid_kernel</structname> were moved to header files -(<filename>include/linux/msg.h</filename> and -<filename>include/linux/shm.h</filename> as appropriate) to allow -the security modules to use these definitions. -</para> - -<para> -Each LSM hook is a function pointer in a global table, -security_ops. This table is a -<structname>security_operations</structname> structure as defined by -<filename>include/linux/security.h</filename>. Detailed documentation -for each hook is included in this header file. At present, this -structure consists of a collection of substructures that group related -hooks based on the kernel object (e.g. task, inode, file, sk_buff, -etc) as well as some top-level hook function pointers for system -operations. This structure is likely to be flattened in the future -for performance. The placement of the hook calls in the kernel code -is described by the "called:" lines in the per-hook documentation in -the header file. The hook calls can also be easily found in the -kernel code by looking for the string "security_ops->". - -</para> - -<para> -Linus mentioned per-process security hooks in his original remarks as a -possible alternative to global security hooks. However, if LSM were -to start from the perspective of per-process hooks, then the base -framework would have to deal with how to handle operations that -involve multiple processes (e.g. kill), since each process might have -its own hook for controlling the operation. This would require a -general mechanism for composing hooks in the base framework. -Additionally, LSM would still need global hooks for operations that -have no process context (e.g. network input operations). -Consequently, LSM provides global security hooks, but a security -module is free to implement per-process hooks (where that makes sense) -by storing a security_ops table in each process' security field and -then invoking these per-process hooks from the global hooks. -The problem of composition is thus deferred to the module. -</para> - -<para> -The global security_ops table is initialized to a set of hook -functions provided by a dummy security module that provides -traditional superuser logic. A <function>register_security</function> -function (in <filename>security/security.c</filename>) is provided to -allow a security module to set security_ops to refer to its own hook -functions, and an <function>unregister_security</function> function is -provided to revert security_ops to the dummy module hooks. This -mechanism is used to set the primary security module, which is -responsible for making the final decision for each hook. -</para> - -<para> -LSM also provides a simple mechanism for stacking additional security -modules with the primary security module. It defines -<function>register_security</function> and -<function>unregister_security</function> hooks in the -<structname>security_operations</structname> structure and provides -<function>mod_reg_security</function> and -<function>mod_unreg_security</function> functions that invoke these -hooks after performing some sanity checking. A security module can -call these functions in order to stack with other modules. However, -the actual details of how this stacking is handled are deferred to the -module, which can implement these hooks in any way it wishes -(including always returning an error if it does not wish to support -stacking). In this manner, LSM again defers the problem of -composition to the module. -</para> - -<para> -Although the LSM hooks are organized into substructures based on -kernel object, all of the hooks can be viewed as falling into two -major categories: hooks that are used to manage the security fields -and hooks that are used to perform access control. Examples of the -first category of hooks include the -<function>alloc_security</function> and -<function>free_security</function> hooks defined for each kernel data -structure that has a security field. These hooks are used to allocate -and free security structures for kernel objects. The first category -of hooks also includes hooks that set information in the security -field after allocation, such as the <function>post_lookup</function> -hook in <structname>struct inode_security_ops</structname>. This hook -is used to set security information for inodes after successful lookup -operations. An example of the second category of hooks is the -<function>permission</function> hook in -<structname>struct inode_security_ops</structname>. This hook checks -permission when accessing an inode. -</para> - -</sect1> - -<sect1 id="cap"><title>LSM Capabilities Module</title> - -<para> -The LSM kernel patch moves most of the existing POSIX.1e capabilities -logic into an optional security module stored in the file -<filename>security/capability.c</filename>. This change allows -users who do not want to use capabilities to omit this code entirely -from their kernel, instead using the dummy module for traditional -superuser logic or any other module that they desire. This change -also allows the developers of the capabilities logic to maintain and -enhance their code more freely, without needing to integrate patches -back into the base kernel. -</para> - -<para> -In addition to moving the capabilities logic, the LSM kernel patch -could move the capability-related fields from the kernel data -structures into the new security fields managed by the security -modules. However, at present, the LSM kernel patch leaves the -capability fields in the kernel data structures. In his original -remarks, Linus suggested that this might be preferable so that other -security modules can be easily stacked with the capabilities module -without needing to chain multiple security structures on the security field. -It also avoids imposing extra overhead on the capabilities module -to manage the security fields. However, the LSM framework could -certainly support such a move if it is determined to be desirable, -with only a few additional changes described below. -</para> - -<para> -At present, the capabilities logic for computing process capabilities -on <function>execve</function> and <function>set*uid</function>, -checking capabilities for a particular process, saving and checking -capabilities for netlink messages, and handling the -<function>capget</function> and <function>capset</function> system -calls have been moved into the capabilities module. There are still a -few locations in the base kernel where capability-related fields are -directly examined or modified, but the current version of the LSM -patch does allow a security module to completely replace the -assignment and testing of capabilities. These few locations would -need to be changed if the capability-related fields were moved into -the security field. The following is a list of known locations that -still perform such direct examination or modification of -capability-related fields: -<itemizedlist> -<listitem><para><filename>fs/open.c</filename>:<function>sys_access</function></para></listitem> -<listitem><para><filename>fs/lockd/host.c</filename>:<function>nlm_bind_host</function></para></listitem> -<listitem><para><filename>fs/nfsd/auth.c</filename>:<function>nfsd_setuser</function></para></listitem> -<listitem><para><filename>fs/proc/array.c</filename>:<function>task_cap</function></para></listitem> -</itemizedlist> -</para> - -</sect1> - -</article> diff --git a/Documentation/lsm.txt b/Documentation/lsm.txt new file mode 100644 index 000000000000..ad4dfd020e0d --- /dev/null +++ b/Documentation/lsm.txt @@ -0,0 +1,201 @@ +======================================================== +Linux Security Modules: General Security Hooks for Linux +======================================================== + +:Author: Stephen Smalley +:Author: Timothy Fraser +:Author: Chris Vance + +.. note:: + + The APIs described in this book are outdated. + +Introduction +============ + +In March 2001, the National Security Agency (NSA) gave a presentation +about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit. +SELinux is an implementation of flexible and fine-grained +nondiscretionary access controls in the Linux kernel, originally +implemented as its own particular kernel patch. Several other security +projects (e.g. RSBAC, Medusa) have also developed flexible access +control architectures for the Linux kernel, and various projects have +developed particular access control models for Linux (e.g. LIDS, DTE, +SubDomain). Each project has developed and maintained its own kernel +patch to support its security needs. + +In response to the NSA presentation, Linus Torvalds made a set of +remarks that described a security framework he would be willing to +consider for inclusion in the mainstream Linux kernel. He described a +general framework that would provide a set of security hooks to control +operations on kernel objects and a set of opaque security fields in +kernel data structures for maintaining security attributes. This +framework could then be used by loadable kernel modules to implement any +desired model of security. Linus also suggested the possibility of +migrating the Linux capabilities code into such a module. + +The Linux Security Modules (LSM) project was started by WireX to develop +such a framework. LSM is a joint development effort by several security +projects, including Immunix, SELinux, SGI and Janus, and several +individuals, including Greg Kroah-Hartman and James Morris, to develop a +Linux kernel patch that implements this framework. The patch is +currently tracking the 2.4 series and is targeted for integration into +the 2.5 development series. This technical report provides an overview +of the framework and the example capabilities security module provided +by the LSM kernel patch. + +LSM Framework +============= + +The LSM kernel patch provides a general kernel framework to support +security modules. In particular, the LSM framework is primarily focused +on supporting access control modules, although future development is +likely to address other security needs such as auditing. By itself, the +framework does not provide any additional security; it merely provides +the infrastructure to support security modules. The LSM kernel patch +also moves most of the capabilities logic into an optional security +module, with the system defaulting to the traditional superuser logic. +This capabilities module is discussed further in +`LSM Capabilities Module <#cap>`__. + +The LSM kernel patch adds security fields to kernel data structures and +inserts calls to hook functions at critical points in the kernel code to +manage the security fields and to perform access control. It also adds +functions for registering and unregistering security modules, and adds a +general :c:func:`security()` system call to support new system calls +for security-aware applications. + +The LSM security fields are simply ``void*`` pointers. For process and +program execution security information, security fields were added to +:c:type:`struct task_struct <task_struct>` and +:c:type:`struct linux_binprm <linux_binprm>`. For filesystem +security information, a security field was added to :c:type:`struct +super_block <super_block>`. For pipe, file, and socket security +information, security fields were added to :c:type:`struct inode +<inode>` and :c:type:`struct file <file>`. For packet and +network device security information, security fields were added to +:c:type:`struct sk_buff <sk_buff>` and :c:type:`struct +net_device <net_device>`. For System V IPC security information, +security fields were added to :c:type:`struct kern_ipc_perm +<kern_ipc_perm>` and :c:type:`struct msg_msg +<msg_msg>`; additionally, the definitions for :c:type:`struct +msg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel +were moved to header files (``include/linux/msg.h`` and +``include/linux/shm.h`` as appropriate) to allow the security modules to +use these definitions. + +Each LSM hook is a function pointer in a global table, security_ops. +This table is a :c:type:`struct security_operations +<security_operations>` structure as defined by +``include/linux/security.h``. Detailed documentation for each hook is +included in this header file. At present, this structure consists of a +collection of substructures that group related hooks based on the kernel +object (e.g. task, inode, file, sk_buff, etc) as well as some top-level +hook function pointers for system operations. This structure is likely +to be flattened in the future for performance. The placement of the hook +calls in the kernel code is described by the "called:" lines in the +per-hook documentation in the header file. The hook calls can also be +easily found in the kernel code by looking for the string +"security_ops->". + +Linus mentioned per-process security hooks in his original remarks as a +possible alternative to global security hooks. However, if LSM were to +start from the perspective of per-process hooks, then the base framework +would have to deal with how to handle operations that involve multiple +processes (e.g. kill), since each process might have its own hook for +controlling the operation. This would require a general mechanism for +composing hooks in the base framework. Additionally, LSM would still +need global hooks for operations that have no process context (e.g. +network input operations). Consequently, LSM provides global security +hooks, but a security module is free to implement per-process hooks +(where that makes sense) by storing a security_ops table in each +process' security field and then invoking these per-process hooks from +the global hooks. The problem of composition is thus deferred to the +module. + +The global security_ops table is initialized to a set of hook functions +provided by a dummy security module that provides traditional superuser +logic. A :c:func:`register_security()` function (in +``security/security.c``) is provided to allow a security module to set +security_ops to refer to its own hook functions, and an +:c:func:`unregister_security()` function is provided to revert +security_ops to the dummy module hooks. This mechanism is used to set +the primary security module, which is responsible for making the final +decision for each hook. + +LSM also provides a simple mechanism for stacking additional security +modules with the primary security module. It defines +:c:func:`register_security()` and +:c:func:`unregister_security()` hooks in the :c:type:`struct +security_operations <security_operations>` structure and +provides :c:func:`mod_reg_security()` and +:c:func:`mod_unreg_security()` functions that invoke these hooks +after performing some sanity checking. A security module can call these +functions in order to stack with other modules. However, the actual +details of how this stacking is handled are deferred to the module, +which can implement these hooks in any way it wishes (including always +returning an error if it does not wish to support stacking). In this +manner, LSM again defers the problem of composition to the module. + +Although the LSM hooks are organized into substructures based on kernel +object, all of the hooks can be viewed as falling into two major +categories: hooks that are used to manage the security fields and hooks +that are used to perform access control. Examples of the first category +of hooks include the :c:func:`alloc_security()` and +:c:func:`free_security()` hooks defined for each kernel data +structure that has a security field. These hooks are used to allocate +and free security structures for kernel objects. The first category of +hooks also includes hooks that set information in the security field +after allocation, such as the :c:func:`post_lookup()` hook in +:c:type:`struct inode_security_ops <inode_security_ops>`. +This hook is used to set security information for inodes after +successful lookup operations. An example of the second category of hooks +is the :c:func:`permission()` hook in :c:type:`struct +inode_security_ops <inode_security_ops>`. This hook checks +permission when accessing an inode. + +LSM Capabilities Module +======================= + +The LSM kernel patch moves most of the existing POSIX.1e capabilities +logic into an optional security module stored in the file +``security/capability.c``. This change allows users who do not want to +use capabilities to omit this code entirely from their kernel, instead +using the dummy module for traditional superuser logic or any other +module that they desire. This change also allows the developers of the +capabilities logic to maintain and enhance their code more freely, +without needing to integrate patches back into the base kernel. + +In addition to moving the capabilities logic, the LSM kernel patch could +move the capability-related fields from the kernel data structures into +the new security fields managed by the security modules. However, at +present, the LSM kernel patch leaves the capability fields in the kernel +data structures. In his original remarks, Linus suggested that this +might be preferable so that other security modules can be easily stacked +with the capabilities module without needing to chain multiple security +structures on the security field. It also avoids imposing extra overhead +on the capabilities module to manage the security fields. However, the +LSM framework could certainly support such a move if it is determined to +be desirable, with only a few additional changes described below. + +At present, the capabilities logic for computing process capabilities on +:c:func:`execve()` and :c:func:`set\*uid()`, checking +capabilities for a particular process, saving and checking capabilities +for netlink messages, and handling the :c:func:`capget()` and +:c:func:`capset()` system calls have been moved into the +capabilities module. There are still a few locations in the base kernel +where capability-related fields are directly examined or modified, but +the current version of the LSM patch does allow a security module to +completely replace the assignment and testing of capabilities. These few +locations would need to be changed if the capability-related fields were +moved into the security field. The following is a list of known +locations that still perform such direct examination or modification of +capability-related fields: + +- ``fs/open.c``::c:func:`sys_access()` + +- ``fs/lockd/host.c``::c:func:`nlm_bind_host()` + +- ``fs/nfsd/auth.c``::c:func:`nfsd_setuser()` + +- ``fs/proc/array.c``::c:func:`task_cap()` -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 46/53] ia64, scsi: update references for the device-io book |
| Message-ID | <tHJLZ-5yL-41@gated-at.bofh.it> |
| In reply to | #1642478 |
The book is now at Documentation/driver-api/device-io.rst.
Update such references.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
arch/ia64/include/asm/io.h | 2 +-
arch/ia64/sn/kernel/iomv.c | 2 +-
drivers/scsi/qla1280.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/arch/ia64/include/asm/io.h b/arch/ia64/include/asm/io.h
index 5de673ac9cb1..a2540e21f919 100644
--- a/arch/ia64/include/asm/io.h
+++ b/arch/ia64/include/asm/io.h
@@ -117,7 +117,7 @@ extern int valid_mmap_phys_addr_range (unsigned long pfn, size_t count);
* following the barrier will arrive after all previous writes. For most
* ia64 platforms, this is a simple 'mf.a' instruction.
*
- * See Documentation/DocBook/deviceiobook.tmpl for more information.
+ * See Documentation/driver-api/device-io.rst for more information.
*/
static inline void ___ia64_mmiowb(void)
{
diff --git a/arch/ia64/sn/kernel/iomv.c b/arch/ia64/sn/kernel/iomv.c
index c77ebdf98119..2b22a71663c1 100644
--- a/arch/ia64/sn/kernel/iomv.c
+++ b/arch/ia64/sn/kernel/iomv.c
@@ -63,7 +63,7 @@ EXPORT_SYMBOL(sn_io_addr);
/**
* __sn_mmiowb - I/O space memory barrier
*
- * See arch/ia64/include/asm/io.h and Documentation/DocBook/deviceiobook.tmpl
+ * See arch/ia64/include/asm/io.h and Documentation/driver-api/device-io.rst
* for details.
*
* On SN2, we wait for the PIO_WRITE_STATUS SHub register to clear.
diff --git a/drivers/scsi/qla1280.c b/drivers/scsi/qla1280.c
index 634254a52301..8a29fb09db14 100644
--- a/drivers/scsi/qla1280.c
+++ b/drivers/scsi/qla1280.c
@@ -3390,7 +3390,7 @@ qla1280_isp_cmd(struct scsi_qla_host *ha)
* On PCI bus, order reverses and write of 6 posts, then index 5,
* causing chip to issue full queue of stale commands
* The mmiowb() prevents future writes from crossing the barrier.
- * See Documentation/DocBook/deviceiobook.tmpl for more information.
+ * See Documentation/driver-api/device-io.rst for more information.
*/
WRT_REG_WORD(®->mailbox4, ha->req_ring_index);
mmiowb();
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 05/53] locking.rst: reformat locking table |
| Message-ID | <tHJLZ-5yL-39@gated-at.bofh.it> |
| In reply to | #1642478 |
Use a different markup for this table, in order to make it smaller when seeing in text mode. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/kernel-hacking/locking.rst | 37 ++++++++++++-------------------- 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index 976b2703df75..17774b1f7587 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -319,29 +319,20 @@ Remember the advice above: you can always use :c:func:`spin_lock_irqsave()`, which is a superset of all other spinlock primitives. -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| | IRQ Handler A | IRQ Handler B | Softirq A | Softirq B | Tasklet A | Tasklet B | Timer A | Timer B | User Context A | User Context B | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| IRQ Handler A | None | | | | | | | | | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| IRQ Handler B | SLIS | None | | | | | | | | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| Softirq A | SLI | SLI | SL | | | | | | | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| Softirq B | SLI | SLI | SL | SL | | | | | | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| Tasklet A | SLI | SLI | SL | SL | None | | | | | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| Tasklet B | SLI | SLI | SL | SL | SL | None | | | | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| Timer A | SLI | SLI | SL | SL | SL | SL | None | | | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| Timer B | SLI | SLI | SL | SL | SL | SL | SL | None | | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| User Context A | SLI | SLI | SLBH | SLBH | SLBH | SLBH | SLBH | SLBH | None | | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ -| User Context B | SLI | SLI | SLBH | SLBH | SLBH | SLBH | SLBH | SLBH | MLI | None | -+------------------+-----------------+-----------------+-------------+-------------+-------------+-------------+-----------+-----------+------------------+------------------+ +============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ============== +. IRQ Handler A IRQ Handler B Softirq A Softirq B Tasklet A Tasklet B Timer A Timer B User Context A User Context B +============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ============== +IRQ Handler A None +IRQ Handler B SLIS None +Softirq A SLI SLI SL +Softirq B SLI SLI SL SL +Tasklet A SLI SLI SL SL None +Tasklet B SLI SLI SL SL SL None +Timer A SLI SLI SL SL SL SL None +Timer B SLI SLI SL SL SL SL SL None +User Context A SLI SLI SLBH SLBH SLBH SLBH SLBH SLBH None +User Context B SLI SLI SLBH SLBH SLBH SLBH SLBH SLBH MLI None +============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ============== Table: Table of Locking Requirements -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 25/53] libata.rst: add c function and struct cross-references |
| Message-ID | <tHJLZ-5yL-43@gated-at.bofh.it> |
| In reply to | #1642478 |
Instead of just using text for functions and structs, use
the C domain tags, in order to allow cross-referencing with
the kernel-doc markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/driver-api/libata.rst | 244 ++++++++++++++++++------------------
1 file changed, 124 insertions(+), 120 deletions(-)
diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst
index 774bf238ff79..4adc056f7635 100644
--- a/Documentation/driver-api/libata.rst
+++ b/Documentation/driver-api/libata.rst
@@ -18,18 +18,19 @@ internals, and a couple sample ATA low-level drivers.
libata Driver API
=================
-struct ata_port_operations is defined for every low-level libata
+:c:type:`struct ata_port_operations <ata_port_operations>`
+is defined for every low-level libata
hardware driver, and it controls how the low-level driver interfaces
with the ATA and SCSI layers.
-FIS-based drivers will hook into the system with ->qc_prep() and
-->qc_issue() high-level hooks. Hardware which behaves in a manner
+FIS-based drivers will hook into the system with ``->qc_prep()`` and
+``->qc_issue()`` high-level hooks. Hardware which behaves in a manner
similar to PCI IDE hardware may utilize several generic helpers,
defining at a bare minimum the bus I/O addresses of the ATA shadow
register blocks.
-struct ata_port_operations
-----------------------------
+:c:type:`struct ata_port_operations <ata_port_operations>`
+----------------------------------------------------------
Disable ATA port
~~~~~~~~~~~~~~~~
@@ -39,13 +40,13 @@ Disable ATA port
void (*port_disable) (struct ata_port *);
-Called from ata_bus_probe() error path, as well as when unregistering
+Called from :c:func:`ata_bus_probe` error path, as well as when unregistering
from the SCSI module (rmmod, hot unplug). This function should do
whatever needs to be done to take the port out of use. In most cases,
-ata_port_disable() can be used as this hook.
+:c:func:`ata_port_disable` can be used as this hook.
-Called from ata_bus_probe() on a failed probe. Called from
-ata_scsi_release().
+Called from :c:func:`ata_bus_probe` on a failed probe. Called from
+:c:func:`ata_scsi_release`.
Post-IDENTIFY device configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -73,22 +74,22 @@ Set PIO/DMA mode
Hooks called prior to the issue of SET FEATURES - XFER MODE command. The
-optional ->mode_filter() hook is called when libata has built a mask of
-the possible modes. This is passed to the ->mode_filter() function
+optional ``->mode_filter()`` hook is called when libata has built a mask of
+the possible modes. This is passed to the ``->mode_filter()`` function
which should return a mask of valid modes after filtering those
unsuitable due to hardware limits. It is not valid to use this interface
to add modes.
-dev->pio_mode and dev->dma_mode are guaranteed to be valid when
-->set_piomode() and when ->set_dmamode() is called. The timings for
+``dev->pio_mode`` and ``dev->dma_mode`` are guaranteed to be valid when
+``->set_piomode()`` and when ``->set_dmamode()`` is called. The timings for
any other drive sharing the cable will also be valid at this point. That
is the library records the decisions for the modes of each drive on a
channel before it attempts to set any of them.
-->post_set_mode() is called unconditionally, after the SET FEATURES -
+``->post_set_mode()`` is called unconditionally, after the SET FEATURES -
XFER MODE command completes successfully.
-->set_piomode() is always called (if present), but ->set_dma_mode()
+``->set_piomode()`` is always called (if present), but ``->set_dma_mode()``
is only called if DMA is possible.
Taskfile read/write
@@ -100,11 +101,11 @@ Taskfile read/write
void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf);
-->tf_load() is called to load the given taskfile into hardware
-registers / DMA buffers. ->tf_read() is called to read the hardware
+``->tf_load()`` is called to load the given taskfile into hardware
+registers / DMA buffers. ``->tf_read()`` is called to read the hardware
registers / DMA buffers, to obtain the current set of taskfile register
values. Most drivers for taskfile-based hardware (PIO or MMIO) use
-ata_sff_tf_load() and ata_sff_tf_read() for these hooks.
+:c:func:`ata_sff_tf_load` and :c:func:`ata_sff_tf_read` for these hooks.
PIO data read/write
~~~~~~~~~~~~~~~~~~~
@@ -117,8 +118,8 @@ PIO data read/write
All bmdma-style drivers must implement this hook. This is the low-level
operation that actually copies the data bytes during a PIO data
transfer. Typically the driver will choose one of
-ata_sff_data_xfer_noirq(), ata_sff_data_xfer(), or
-ata_sff_data_xfer32().
+:c:func:`ata_sff_data_xfer_noirq`, :c:func:`ata_sff_data_xfer`, or
+:c:func:`ata_sff_data_xfer32`.
ATA command execute
~~~~~~~~~~~~~~~~~~~
@@ -128,9 +129,9 @@ ATA command execute
void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf);
-causes an ATA command, previously loaded with ->tf_load(), to be
+causes an ATA command, previously loaded with ``->tf_load()``, to be
initiated in hardware. Most drivers for taskfile-based hardware use
-ata_sff_exec_command() for this hook.
+:c:func:`ata_sff_exec_command` for this hook.
Per-cmd ATAPI DMA capabilities filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -159,7 +160,7 @@ Read specific ATA shadow registers
Reads the Status/AltStatus ATA shadow register from hardware. On some
hardware, reading the Status register has the side effect of clearing
the interrupt condition. Most drivers for taskfile-based hardware use
-ata_sff_check_status() for this hook.
+:c:func:`ata_sff_check_status` for this hook.
Write specific ATA shadow register
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -184,7 +185,7 @@ Issues the low-level hardware command(s) that causes one of N hardware
devices to be considered 'selected' (active and available for use) on
the ATA bus. This generally has no meaning on FIS-based devices.
-Most drivers for taskfile-based hardware use ata_sff_dev_select() for
+Most drivers for taskfile-based hardware use :c:func:`ata_sff_dev_select` for
this hook.
Private tuning method
@@ -222,28 +223,28 @@ Control PCI IDE BMDMA engine
When setting up an IDE BMDMA transaction, these hooks arm
-(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) the
-hardware's DMA engine. ->bmdma_status is used to read the standard PCI
+(``->bmdma_setup``), fire (``->bmdma_start``), and halt (``->bmdma_stop``) the
+hardware's DMA engine. ``->bmdma_status`` is used to read the standard PCI
IDE DMA Status register.
These hooks are typically either no-ops, or simply not implemented, in
FIS-based drivers.
-Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()
-hook. ata_bmdma_setup() will write the pointer to the PRD table to the
-IDE PRD Table Address register, enable DMA in the DMA Command register,
-and call exec_command() to begin the transfer.
+Most legacy IDE drivers use :c:func:`ata_bmdma_setup` for the
+:c:func:`bmdma_setup` hook. :c:func:`ata_bmdma_setup` will write the pointer
+to the PRD table to the IDE PRD Table Address register, enable DMA in the DMA
+Command register, and call :c:func:`exec_command` to begin the transfer.
-Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()
-hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA
-Command register.
+Most legacy IDE drivers use :c:func:`ata_bmdma_start` for the
+:c:func:`bmdma_start` hook. :c:func:`ata_bmdma_start` will write the
+ATA_DMA_START flag to the DMA Command register.
-Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()
-hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA
-command register.
+Many legacy IDE drivers use :c:func:`ata_bmdma_stop` for the
+:c:func:`bmdma_stop` hook. :c:func:`ata_bmdma_stop` clears the ATA_DMA_START
+flag in the DMA command register.
-Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status()
-hook.
+Many legacy IDE drivers use :c:func:`ata_bmdma_status` as the
+:c:func:`bmdma_status` hook.
High-level taskfile hooks
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -255,19 +256,19 @@ High-level taskfile hooks
Higher-level hooks, these two hooks can potentially supercede several of
-the above taskfile/DMA engine hooks. ->qc_prep is called after the
+the above taskfile/DMA engine hooks. ``->qc_prep`` is called after the
buffers have been DMA-mapped, and is typically used to populate the
hardware's DMA scatter-gather table. Most drivers use the standard
-ata_qc_prep() helper function, but more advanced drivers roll their
+:c:func:`ata_qc_prep` helper function, but more advanced drivers roll their
own.
-->qc_issue is used to make a command active, once the hardware and S/G
+``->qc_issue`` is used to make a command active, once the hardware and S/G
tables have been prepared. IDE BMDMA drivers use the helper function
-ata_qc_issue_prot() for taskfile protocol-based dispatch. More
-advanced drivers implement their own ->qc_issue.
+:c:func:`ata_qc_issue_prot` for taskfile protocol-based dispatch. More
+advanced drivers implement their own ``->qc_issue``.
-ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and
-->bmdma_start() as necessary to initiate a transfer.
+:c:func:`ata_qc_issue_prot` calls ``->tf_load()``, ``->bmdma_setup()``, and
+``->bmdma_start()`` as necessary to initiate a transfer.
Exception and probe handling (EH)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -278,7 +279,7 @@ Exception and probe handling (EH)
void (*phy_reset) (struct ata_port *ap);
-Deprecated. Use ->error_handler() instead.
+Deprecated. Use ``->error_handler()`` instead.
::
@@ -286,18 +287,18 @@ Deprecated. Use ->error_handler() instead.
void (*thaw) (struct ata_port *ap);
-ata_port_freeze() is called when HSM violations or some other
+:c:func:`ata_port_freeze` is called when HSM violations or some other
condition disrupts normal operation of the port. A frozen port is not
allowed to perform any operation until the port is thawed, which usually
follows a successful reset.
-The optional ->freeze() callback can be used for freezing the port
+The optional ``->freeze()`` callback can be used for freezing the port
hardware-wise (e.g. mask interrupt and stop DMA engine). If a port
cannot be frozen hardware-wise, the interrupt handler must ack and clear
interrupts unconditionally while the port is frozen.
-The optional ->thaw() callback is called to perform the opposite of
-->freeze(): prepare the port for normal operation once again. Unmask
+The optional ``->thaw()`` callback is called to perform the opposite of
+``->freeze()``: prepare the port for normal operation once again. Unmask
interrupts, start DMA engine, etc.
::
@@ -305,10 +306,10 @@ interrupts, start DMA engine, etc.
void (*error_handler) (struct ata_port *ap);
-->error_handler() is a driver's hook into probe, hotplug, and recovery
+``->error_handler()`` is a driver's hook into probe, hotplug, and recovery
and other exceptional conditions. The primary responsibility of an
-implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with
-a set of EH hooks as arguments:
+implementation is to call :c:func:`ata_do_eh` or :c:func:`ata_bmdma_drive_eh`
+with a set of EH hooks as arguments:
'prereset' hook (may be NULL) is called during an EH reset, before any
other actions are taken.
@@ -327,7 +328,7 @@ called to perform the low-level EH reset.
Perform any hardware-specific actions necessary to finish processing
after executing a probe-time or EH-time command via
-ata_exec_internal().
+:c:func:`ata_exec_internal`.
Hardware interrupt handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -338,20 +339,20 @@ Hardware interrupt handling
void (*irq_clear) (struct ata_port *);
-->irq_handler is the interrupt handling routine registered with the
-system, by libata. ->irq_clear is called during probe just before the
+``->irq_handler`` is the interrupt handling routine registered with the
+system, by libata. ``->irq_clear`` is called during probe just before the
interrupt handler is registered, to be sure hardware is quiet.
The second argument, dev_instance, should be cast to a pointer to
-struct ata_host_set.
+:c:type:`struct ata_host_set <ata_host_set>`.
-Most legacy IDE drivers use ata_sff_interrupt() for the irq_handler
+Most legacy IDE drivers use :c:func:`ata_sff_interrupt` for the irq_handler
hook, which scans all ports in the host_set, determines which queued
command was active (if any), and calls ata_sff_host_intr(ap,qc).
-Most legacy IDE drivers use ata_sff_irq_clear() for the irq_clear()
-hook, which simply clears the interrupt and error flags in the DMA
-status register.
+Most legacy IDE drivers use :c:func:`ata_sff_irq_clear` for the
+:c:func:`irq_clear` hook, which simply clears the interrupt and error flags
+in the DMA status register.
SATA phy read/write
~~~~~~~~~~~~~~~~~~~
@@ -365,8 +366,8 @@ SATA phy read/write
Read and write standard SATA phy registers. Currently only used if
-->phy_reset hook called the sata_phy_reset() helper function. sc_reg
-is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
+``->phy_reset`` hook called the :c:func:`sata_phy_reset` helper function.
+sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
Init and shutdown
~~~~~~~~~~~~~~~~~
@@ -378,21 +379,21 @@ Init and shutdown
void (*host_stop) (struct ata_host_set *host_set);
-->port_start() is called just after the data structures for each port
+``->port_start()`` is called just after the data structures for each port
are initialized. Typically this is used to alloc per-port DMA buffers /
tables / rings, enable DMA engines, and similar tasks. Some drivers also
use this entry point as a chance to allocate driver-private memory for
-ap->private_data.
+``ap->private_data``.
-Many drivers use ata_port_start() as this hook or call it from their
-own port_start() hooks. ata_port_start() allocates space for a legacy
-IDE PRD table and returns.
+Many drivers use :c:func:`ata_port_start` as this hook or call it from their
+own :c:func:`port_start` hooks. :c:func:`ata_port_start` allocates space for
+a legacy IDE PRD table and returns.
-->port_stop() is called after ->host_stop(). Its sole function is to
+``->port_stop()`` is called after ``->host_stop()``. Its sole function is to
release DMA/memory resources, now that they are no longer actively being
used. Many drivers also free driver-private data from port at this time.
-->host_stop() is called after all ->port_stop() calls have completed.
+``->host_stop()`` is called after all ``->port_stop()`` calls have completed.
The hook must finalize hardware shutdown, release DMA and other
resources, etc. This hook may be specified as NULL, in which case it is
not called.
@@ -407,7 +408,8 @@ exceptions doc first.
Origins of commands
-------------------
-In libata, a command is represented with struct ata_queued_cmd or qc.
+In libata, a command is represented with
+:c:type:`struct ata_queued_cmd <ata_queued_cmd>` or qc.
qc's are preallocated during port initialization and repetitively used
for command executions. Currently only one qc is allocated per port but
yet-to-be-merged NCQ branch allocates one for each tag and maps each qc
@@ -423,17 +425,17 @@ How commands are issued
-----------------------
Internal commands
- First, qc is allocated and initialized using ata_qc_new_init().
- Although ata_qc_new_init() doesn't implement any wait or retry
+ First, qc is allocated and initialized using :c:func:`ata_qc_new_init`.
+ Although :c:func:`ata_qc_new_init` doesn't implement any wait or retry
mechanism when qc is not available, internal commands are currently
issued only during initialization and error recovery, so no other
command is active and allocation is guaranteed to succeed.
Once allocated qc's taskfile is initialized for the command to be
executed. qc currently has two mechanisms to notify completion. One
- is via qc->complete_fn() callback and the other is completion
- qc->waiting. qc->complete_fn() callback is the asynchronous path
- used by normal SCSI translated commands and qc->waiting is the
+ is via ``qc->complete_fn()`` callback and the other is completion
+ ``qc->waiting``. ``qc->complete_fn()`` callback is the asynchronous path
+ used by normal SCSI translated commands and ``qc->waiting`` is the
synchronous (issuer sleeps in process context) path used by internal
commands.
@@ -441,21 +443,21 @@ Internal commands
qc is issued.
SCSI commands
- All libata drivers use ata_scsi_queuecmd() as hostt->queuecommand
- callback. scmds can either be simulated or translated. No qc is
- involved in processing a simulated scmd. The result is computed
- right away and the scmd is completed.
+ All libata drivers use :c:func:`ata_scsi_queuecmd` as
+ ``hostt->queuecommand`` callback. scmds can either be simulated or
+ translated. No qc is involved in processing a simulated scmd. The
+ result is computed right away and the scmd is completed.
- For a translated scmd, ata_qc_new_init() is invoked to allocate a
+ For a translated scmd, :c:func:`ata_qc_new_init` is invoked to allocate a
qc and the scmd is translated into the qc. SCSI midlayer's
completion notification function pointer is stored into
- qc->scsidone.
+ ``qc->scsidone``.
- qc->complete_fn() callback is used for completion notification. ATA
- commands use ata_scsi_qc_complete() while ATAPI commands use
- atapi_qc_complete(). Both functions end up calling qc->scsidone to
- notify upper layer when the qc is finished. After translation is
- completed, the qc is issued with ata_qc_issue().
+ ``qc->complete_fn()`` callback is used for completion notification. ATA
+ commands use :c:func:`ata_scsi_qc_complete` while ATAPI commands use
+ :c:func:`atapi_qc_complete`. Both functions end up calling ``qc->scsidone``
+ to notify upper layer when the qc is finished. After translation is
+ completed, the qc is issued with :c:func:`ata_qc_issue`.
Note that SCSI midlayer invokes hostt->queuecommand while holding
host_set lock, so all above occur while holding host_set lock.
@@ -495,34 +497,34 @@ ATAPI PIO
How commands are completed
--------------------------
-Once issued, all qc's are either completed with ata_qc_complete() or
+Once issued, all qc's are either completed with :c:func:`ata_qc_complete` or
time out. For commands which are handled by interrupts,
-ata_host_intr() invokes ata_qc_complete(), and, for PIO tasks,
-pio_task invokes ata_qc_complete(). In error cases, packet_task may
+:c:func:`ata_host_intr` invokes :c:func:`ata_qc_complete`, and, for PIO tasks,
+pio_task invokes :c:func:`ata_qc_complete`. In error cases, packet_task may
also complete commands.
-ata_qc_complete() does the following.
+:c:func:`ata_qc_complete` does the following.
1. DMA memory is unmapped.
2. ATA_QCFLAG_ACTIVE is cleared from qc->flags.
-3. qc->complete_fn() callback is invoked. If the return value of the
+3. :c:func:`qc->complete_fn` callback is invoked. If the return value of the
callback is not zero. Completion is short circuited and
- ata_qc_complete() returns.
+ :c:func:`ata_qc_complete` returns.
-4. __ata_qc_complete() is called, which does
+4. :c:func:`__ata_qc_complete` is called, which does
- 1. qc->flags is cleared to zero.
+ 1. ``qc->flags`` is cleared to zero.
- 2. ap->active_tag and qc->tag are poisoned.
+ 2. ``ap->active_tag`` and ``qc->tag`` are poisoned.
- 3. qc->waiting is cleared & completed (in that order).
+ 3. ``qc->waiting`` is cleared & completed (in that order).
- 4. qc is deallocated by clearing appropriate bit in ap->qactive.
+ 4. qc is deallocated by clearing appropriate bit in ``ap->qactive``.
So, it basically notifies upper layer and deallocates qc. One exception
-is short-circuit path in #3 which is used by atapi_qc_complete().
+is short-circuit path in #3 which is used by :c:func:`atapi_qc_complete`.
For all non-ATAPI commands, whether it fails or not, almost the same
code path is taken and very little error handling takes place. A qc is
@@ -531,33 +533,33 @@ otherwise.
However, failed ATAPI commands require more handling as REQUEST SENSE is
needed to acquire sense data. If an ATAPI command fails,
-ata_qc_complete() is invoked with error status, which in turn invokes
-atapi_qc_complete() via qc->complete_fn() callback.
+:c:func:`ata_qc_complete` is invoked with error status, which in turn invokes
+:c:func:`atapi_qc_complete` via ``qc->complete_fn()`` callback.
-This makes atapi_qc_complete() set scmd->result to
+This makes :c:func:`atapi_qc_complete` set ``scmd->result`` to
SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As the
-sense data is empty but scmd->result is CHECK CONDITION, SCSI midlayer
-will invoke EH for the scmd, and returning 1 makes ata_qc_complete()
+sense data is empty but ``scmd->result`` is CHECK CONDITION, SCSI midlayer
+will invoke EH for the scmd, and returning 1 makes :c:func:`ata_qc_complete`
to return without deallocating the qc. This leads us to
-ata_scsi_error() with partially completed qc.
+:c:func:`ata_scsi_error` with partially completed qc.
-ata_scsi_error()
-------------------
+:c:func:`ata_scsi_error`
+------------------------
-ata_scsi_error() is the current transportt->eh_strategy_handler()
+:c:func:`ata_scsi_error` is the current ``transportt->eh_strategy_handler()``
for libata. As discussed above, this will be entered in two cases -
timeout and ATAPI error completion. This function calls low level libata
-driver's eng_timeout() callback, the standard callback for which is
-ata_eng_timeout(). It checks if a qc is active and calls
-ata_qc_timeout() on the qc if so. Actual error handling occurs in
-ata_qc_timeout().
+driver's :c:func:`eng_timeout` callback, the standard callback for which is
+:c:func:`ata_eng_timeout`. It checks if a qc is active and calls
+:c:func:`ata_qc_timeout` on the qc if so. Actual error handling occurs in
+:c:func:`ata_qc_timeout`.
-If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and
+If EH is invoked for timeout, :c:func:`ata_qc_timeout` stops BMDMA and
completes the qc. Note that as we're currently in EH, we cannot call
scsi_done. As described in SCSI EH doc, a recovered scmd should be
-either retried with scsi_queue_insert() or finished with
-scsi_finish_command(). Here, we override qc->scsidone with
-scsi_finish_command() and calls ata_qc_complete().
+either retried with :c:func:`scsi_queue_insert` or finished with
+:c:func:`scsi_finish_command`. Here, we override ``qc->scsidone`` with
+:c:func:`scsi_finish_command` and calls :c:func:`ata_qc_complete`.
If EH is invoked due to a failed ATAPI qc, the qc here is completed but
not deallocated. The purpose of this half-completion is to use the qc as
@@ -565,11 +567,11 @@ place holder to make EH code reach this place. This is a bit hackish,
but it works.
Once control reaches here, the qc is deallocated by invoking
-__ata_qc_complete() explicitly. Then, internal qc for REQUEST SENSE
+:c:func:`__ata_qc_complete` explicitly. Then, internal qc for REQUEST SENSE
is issued. Once sense data is acquired, scmd is finished by directly
-invoking scsi_finish_command() on the scmd. Note that as we already
+invoking :c:func:`scsi_finish_command` on the scmd. Note that as we already
have completed and deallocated the qc which was associated with the
-scmd, we don't need to/cannot call ata_qc_complete() again.
+scmd, we don't need to/cannot call :c:func:`ata_qc_complete` again.
Problems with the current EH
----------------------------
@@ -583,7 +585,7 @@ Problems with the current EH
- When handling timeouts, no action is taken to make device forget
about the timed out command and ready for new commands.
-- EH handling via ata_scsi_error() is not properly protected from
+- EH handling via :c:func:`ata_scsi_error` is not properly protected from
usual command processing. On EH entrance, the device is not in
quiescent state. Timed out commands may succeed or fail any time.
pio_task and atapi_task may still be running.
@@ -622,6 +624,8 @@ libata Core Internals
.. kernel-doc:: drivers/ata/libata-core.c
:internal:
+.. kernel-doc:: drivers/ata/libata-eh.c
+
libata SCSI translation/emulation
=================================
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 36/53] docs-rst: convert librs book to ReST |
| Message-ID | <tHJLZ-5yL-45@gated-at.bofh.it> |
| In reply to | #1642478 |
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 2 +-
Documentation/DocBook/librs.tmpl | 289 ---------------------------------------
Documentation/core-api/index.rst | 1 +
Documentation/core-api/librs.rst | 212 ++++++++++++++++++++++++++++
4 files changed, 214 insertions(+), 290 deletions(-)
delete mode 100644 Documentation/DocBook/librs.tmpl
create mode 100644 Documentation/core-api/librs.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index baedb14f3b40..0a82f6253682 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -8,7 +8,7 @@
DOCBOOKS := \
lsm.xml \
- mtdnand.xml librs.xml \
+ mtdnand.xml \
sh.xml
ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/librs.tmpl b/Documentation/DocBook/librs.tmpl
deleted file mode 100644
index 94f21361e0ed..000000000000
--- a/Documentation/DocBook/librs.tmpl
+++ /dev/null
@@ -1,289 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="Reed-Solomon-Library-Guide">
- <bookinfo>
- <title>Reed-Solomon Library Programming Interface</title>
-
- <authorgroup>
- <author>
- <firstname>Thomas</firstname>
- <surname>Gleixner</surname>
- <affiliation>
- <address>
- <email>tglx@linutronix.de</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2004</year>
- <holder>Thomas Gleixner</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
- </para>
-
- <para>
- 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.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- 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., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The generic Reed-Solomon Library provides encoding, decoding
- and error correction functions.
- </para>
- <para>
- Reed-Solomon codes are used in communication and storage
- applications to ensure data integrity.
- </para>
- <para>
- This documentation is provided for developers who want to utilize
- the functions provided by the library.
- </para>
- </chapter>
-
- <chapter id="bugs">
- <title>Known Bugs And Assumptions</title>
- <para>
- None.
- </para>
- </chapter>
-
- <chapter id="usage">
- <title>Usage</title>
- <para>
- This chapter provides examples of how to use the library.
- </para>
- <sect1>
- <title>Initializing</title>
- <para>
- The init function init_rs returns a pointer to an
- rs decoder structure, which holds the necessary
- information for encoding, decoding and error correction
- with the given polynomial. It either uses an existing
- matching decoder or creates a new one. On creation all
- the lookup tables for fast en/decoding are created.
- The function may take a while, so make sure not to
- call it in critical code paths.
- </para>
- <programlisting>
-/* the Reed Solomon control structure */
-static struct rs_control *rs_decoder;
-
-/* Symbolsize is 10 (bits)
- * Primitive polynomial is x^10+x^3+1
- * first consecutive root is 0
- * primitive element to generate roots = 1
- * generator polynomial degree (number of roots) = 6
- */
-rs_decoder = init_rs (10, 0x409, 0, 1, 6);
- </programlisting>
- </sect1>
- <sect1>
- <title>Encoding</title>
- <para>
- The encoder calculates the Reed-Solomon code over
- the given data length and stores the result in
- the parity buffer. Note that the parity buffer must
- be initialized before calling the encoder.
- </para>
- <para>
- The expanded data can be inverted on the fly by
- providing a non-zero inversion mask. The expanded data is
- XOR'ed with the mask. This is used e.g. for FLASH
- ECC, where the all 0xFF is inverted to an all 0x00.
- The Reed-Solomon code for all 0x00 is all 0x00. The
- code is inverted before storing to FLASH so it is 0xFF
- too. This prevents that reading from an erased FLASH
- results in ECC errors.
- </para>
- <para>
- The databytes are expanded to the given symbol size
- on the fly. There is no support for encoding continuous
- bitstreams with a symbol size != 8 at the moment. If
- it is necessary it should be not a big deal to implement
- such functionality.
- </para>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6];
-/* Initialize the parity buffer */
-memset(par, 0, sizeof(par));
-/* Encode 512 byte in data8. Store parity in buffer par */
-encode_rs8 (rs_decoder, data8, 512, par, 0);
- </programlisting>
- </sect1>
- <sect1>
- <title>Decoding</title>
- <para>
- The decoder calculates the syndrome over
- the given data length and the received parity symbols
- and corrects errors in the data.
- </para>
- <para>
- If a syndrome is available from a hardware decoder
- then the syndrome calculation is skipped.
- </para>
- <para>
- The correction of the data buffer can be suppressed
- by providing a correction pattern buffer and an error
- location buffer to the decoder. The decoder stores the
- calculated error location and the correction bitmask
- in the given buffers. This is useful for hardware
- decoders which use a weird bit ordering scheme.
- </para>
- <para>
- The databytes are expanded to the given symbol size
- on the fly. There is no support for decoding continuous
- bitstreams with a symbolsize != 8 at the moment. If
- it is necessary it should be not a big deal to implement
- such functionality.
- </para>
-
- <sect2>
- <title>
- Decoding with syndrome calculation, direct data correction
- </title>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6];
-uint8_t data[512];
-int numerr;
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
- </programlisting>
- </sect2>
-
- <sect2>
- <title>
- Decoding with syndrome given by hardware decoder, direct data correction
- </title>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6], syn[6];
-uint8_t data[512];
-int numerr;
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Get syndrome from hardware decoder */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
- </programlisting>
- </sect2>
-
- <sect2>
- <title>
- Decoding with syndrome given by hardware decoder, no direct data correction.
- </title>
- <para>
- Note: It's not necessary to give data and received parity to the decoder.
- </para>
- <programlisting>
-/* Parity buffer. Size = number of roots */
-uint16_t par[6], syn[6], corr[8];
-uint8_t data[512];
-int numerr, errpos[8];
-/* Receive data */
-.....
-/* Receive parity */
-.....
-/* Get syndrome from hardware decoder */
-.....
-/* Decode 512 byte in data8.*/
-numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
-for (i = 0; i < numerr; i++) {
- do_error_correction_in_your_buffer(errpos[i], corr[i]);
-}
- </programlisting>
- </sect2>
- </sect1>
- <sect1>
- <title>Cleanup</title>
- <para>
- The function free_rs frees the allocated resources,
- if the caller is the last user of the decoder.
- </para>
- <programlisting>
-/* Release resources */
-free_rs(rs_decoder);
- </programlisting>
- </sect1>
-
- </chapter>
-
- <chapter id="structs">
- <title>Structures</title>
- <para>
- This chapter contains the autogenerated documentation of the structures which are
- used in the Reed-Solomon Library and are relevant for a developer.
- </para>
-!Iinclude/linux/rslib.h
- </chapter>
-
- <chapter id="pubfunctions">
- <title>Public Functions Provided</title>
- <para>
- This chapter contains the autogenerated documentation of the Reed-Solomon functions
- which are exported.
- </para>
-!Elib/reed_solomon/reed_solomon.c
- </chapter>
-
- <chapter id="credits">
- <title>Credits</title>
- <para>
- The library code for encoding and decoding was written by Phil Karn.
- </para>
- <programlisting>
- Copyright 2002, Phil Karn, KA9Q
- May be used under the terms of the GNU General Public License (GPL)
- </programlisting>
- <para>
- The wrapper functions and interfaces are written by Thomas Gleixner.
- </para>
- <para>
- Many users have provided bugfixes, improvements and helping hands for testing.
- Thanks a lot.
- </para>
- <para>
- The following people have contributed to this document:
- </para>
- <para>
- Thomas Gleixner<email>tglx@linutronix.de</email>
- </para>
- </chapter>
-</book>
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 62abd36bfffb..0606be3a3111 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -19,6 +19,7 @@ Core utilities
workqueue
genericirq
flexible-arrays
+ librs
Interfaces for kernel debugging
===============================
diff --git a/Documentation/core-api/librs.rst b/Documentation/core-api/librs.rst
new file mode 100644
index 000000000000..6010f5bc5bf9
--- /dev/null
+++ b/Documentation/core-api/librs.rst
@@ -0,0 +1,212 @@
+==========================================
+Reed-Solomon Library Programming Interface
+==========================================
+
+:Author: Thomas Gleixner
+
+Introduction
+============
+
+The generic Reed-Solomon Library provides encoding, decoding and error
+correction functions.
+
+Reed-Solomon codes are used in communication and storage applications to
+ensure data integrity.
+
+This documentation is provided for developers who want to utilize the
+functions provided by the library.
+
+Known Bugs And Assumptions
+==========================
+
+None.
+
+Usage
+=====
+
+This chapter provides examples of how to use the library.
+
+Initializing
+------------
+
+The init function init_rs returns a pointer to an rs decoder structure,
+which holds the necessary information for encoding, decoding and error
+correction with the given polynomial. It either uses an existing
+matching decoder or creates a new one. On creation all the lookup tables
+for fast en/decoding are created. The function may take a while, so make
+sure not to call it in critical code paths.
+
+::
+
+ /* the Reed Solomon control structure */
+ static struct rs_control *rs_decoder;
+
+ /* Symbolsize is 10 (bits)
+ * Primitive polynomial is x^10+x^3+1
+ * first consecutive root is 0
+ * primitive element to generate roots = 1
+ * generator polynomial degree (number of roots) = 6
+ */
+ rs_decoder = init_rs (10, 0x409, 0, 1, 6);
+
+
+Encoding
+--------
+
+The encoder calculates the Reed-Solomon code over the given data length
+and stores the result in the parity buffer. Note that the parity buffer
+must be initialized before calling the encoder.
+
+The expanded data can be inverted on the fly by providing a non-zero
+inversion mask. The expanded data is XOR'ed with the mask. This is used
+e.g. for FLASH ECC, where the all 0xFF is inverted to an all 0x00. The
+Reed-Solomon code for all 0x00 is all 0x00. The code is inverted before
+storing to FLASH so it is 0xFF too. This prevents that reading from an
+erased FLASH results in ECC errors.
+
+The databytes are expanded to the given symbol size on the fly. There is
+no support for encoding continuous bitstreams with a symbol size != 8 at
+the moment. If it is necessary it should be not a big deal to implement
+such functionality.
+
+::
+
+ /* Parity buffer. Size = number of roots */
+ uint16_t par[6];
+ /* Initialize the parity buffer */
+ memset(par, 0, sizeof(par));
+ /* Encode 512 byte in data8. Store parity in buffer par */
+ encode_rs8 (rs_decoder, data8, 512, par, 0);
+
+
+Decoding
+--------
+
+The decoder calculates the syndrome over the given data length and the
+received parity symbols and corrects errors in the data.
+
+If a syndrome is available from a hardware decoder then the syndrome
+calculation is skipped.
+
+The correction of the data buffer can be suppressed by providing a
+correction pattern buffer and an error location buffer to the decoder.
+The decoder stores the calculated error location and the correction
+bitmask in the given buffers. This is useful for hardware decoders which
+use a weird bit ordering scheme.
+
+The databytes are expanded to the given symbol size on the fly. There is
+no support for decoding continuous bitstreams with a symbolsize != 8 at
+the moment. If it is necessary it should be not a big deal to implement
+such functionality.
+
+Decoding with syndrome calculation, direct data correction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ /* Parity buffer. Size = number of roots */
+ uint16_t par[6];
+ uint8_t data[512];
+ int numerr;
+ /* Receive data */
+ .....
+ /* Receive parity */
+ .....
+ /* Decode 512 byte in data8.*/
+ numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
+
+
+Decoding with syndrome given by hardware decoder, direct data correction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ /* Parity buffer. Size = number of roots */
+ uint16_t par[6], syn[6];
+ uint8_t data[512];
+ int numerr;
+ /* Receive data */
+ .....
+ /* Receive parity */
+ .....
+ /* Get syndrome from hardware decoder */
+ .....
+ /* Decode 512 byte in data8.*/
+ numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
+
+
+Decoding with syndrome given by hardware decoder, no direct data correction.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note: It's not necessary to give data and received parity to the
+decoder.
+
+::
+
+ /* Parity buffer. Size = number of roots */
+ uint16_t par[6], syn[6], corr[8];
+ uint8_t data[512];
+ int numerr, errpos[8];
+ /* Receive data */
+ .....
+ /* Receive parity */
+ .....
+ /* Get syndrome from hardware decoder */
+ .....
+ /* Decode 512 byte in data8.*/
+ numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
+ for (i = 0; i < numerr; i++) {
+ do_error_correction_in_your_buffer(errpos[i], corr[i]);
+ }
+
+
+Cleanup
+-------
+
+The function free_rs frees the allocated resources, if the caller is
+the last user of the decoder.
+
+::
+
+ /* Release resources */
+ free_rs(rs_decoder);
+
+
+Structures
+==========
+
+This chapter contains the autogenerated documentation of the structures
+which are used in the Reed-Solomon Library and are relevant for a
+developer.
+
+.. kernel-doc:: include/linux/rslib.h
+ :internal:
+
+Public Functions Provided
+=========================
+
+This chapter contains the autogenerated documentation of the
+Reed-Solomon functions which are exported.
+
+.. kernel-doc:: lib/reed_solomon/reed_solomon.c
+ :export:
+
+Credits
+=======
+
+The library code for encoding and decoding was written by Phil Karn.
+
+::
+
+ Copyright 2002, Phil Karn, KA9Q
+ May be used under the terms of the GNU General Public License (GPL)
+
+
+The wrapper functions and interfaces are written by Thomas Gleixner.
+
+Many users have provided bugfixes, improvements and helping hands for
+testing. Thanks a lot.
+
+The following people have contributed to this document:
+
+Thomas Gleixner\ tglx@linutronix.de
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 42/53] docs: remove DocBook from the building system |
| Message-ID | <tHJM0-5yL-57@gated-at.bofh.it> |
| In reply to | #1642478 |
Now that we don't have any DocBook anymore, remove it from
the building system.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/00-INDEX | 4 --
Documentation/DocBook/.gitignore | 17 -----
Documentation/DocBook/Makefile | 1 -
Documentation/DocBook/stylesheet.xsl | 11 ---
Documentation/Makefile | 125 +++++++++++++++++++++++++++++++++
Documentation/Makefile.sphinx | 130 -----------------------------------
Documentation/doc-guide/docbook.rst | 90 ------------------------
Makefile | 11 ++-
scripts/Makefile | 9 +--
scripts/check-lc_ctype.c | 11 ---
10 files changed, 132 insertions(+), 277 deletions(-)
delete mode 100644 Documentation/DocBook/.gitignore
delete mode 100644 Documentation/DocBook/Makefile
delete mode 100644 Documentation/DocBook/stylesheet.xsl
delete mode 100644 Documentation/Makefile.sphinx
delete mode 100644 Documentation/doc-guide/docbook.rst
delete mode 100644 scripts/check-lc_ctype.c
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 8c2a66e176b9..d0165461b024 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -24,8 +24,6 @@ DMA-ISA-LPC.txt
- How to do DMA with ISA (and LPC) devices.
DMA-attributes.txt
- listing of the various possible attributes a DMA region can have
-DocBook/
- - directory with DocBook templates etc. for kernel documentation.
EDID/
- directory with info on customizing EDID for broken gfx/displays.
IPMI.txt
@@ -40,8 +38,6 @@ Intel-IOMMU.txt
- basic info on the Intel IOMMU virtualization support.
Makefile
- It's not of interest for those who aren't touching the build system.
-Makefile.sphinx
- - It's not of interest for those who aren't touching the build system.
PCI/
- info related to PCI drivers.
RCU/
diff --git a/Documentation/DocBook/.gitignore b/Documentation/DocBook/.gitignore
deleted file mode 100644
index e05da3f7aa21..000000000000
--- a/Documentation/DocBook/.gitignore
+++ /dev/null
@@ -1,17 +0,0 @@
-*.xml
-*.ps
-*.pdf
-*.html
-*.9.gz
-*.9
-*.aux
-*.dvi
-*.log
-*.out
-*.png
-*.gif
-*.svg
-*.proc
-*.db
-media-indices.tmpl
-media-entities.tmpl
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
deleted file mode 100644
index 8b137891791f..000000000000
--- a/Documentation/DocBook/Makefile
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl
deleted file mode 100644
index 3bf4ecf3d760..000000000000
--- a/Documentation/DocBook/stylesheet.xsl
+++ /dev/null
@@ -1,11 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
-<param name="chunk.quietly">1</param>
-<param name="funcsynopsis.style">ansi</param>
-<param name="funcsynopsis.tabular.threshold">80</param>
-<param name="callout.graphics">0</param>
-<!-- <param name="paper.type">A4</param> -->
-<param name="generate.consistent.ids">1</param>
-<param name="generate.section.toc.level">2</param>
-<param name="use.id.as.filename">1</param>
-</stylesheet>
diff --git a/Documentation/Makefile b/Documentation/Makefile
index c2a469112c37..a42320385df3 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1 +1,126 @@
+# -*- makefile -*-
+# Makefile for Sphinx documentation
+#
+
subdir-y :=
+
+# You can set these variables from the command line.
+SPHINXBUILD = sphinx-build
+SPHINXOPTS =
+SPHINXDIRS = .
+_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
+SPHINX_CONF = conf.py
+PAPER =
+BUILDDIR = $(obj)/output
+PDFLATEX = xelatex
+LATEXOPTS = -interaction=batchmode
+
+# User-friendly check for sphinx-build
+HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
+
+ifeq ($(HAVE_SPHINX),0)
+
+.DEFAULT:
+ $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
+ @echo " SKIP Sphinx $@ target."
+
+else # HAVE_SPHINX
+
+# User-friendly check for pdflatex
+HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+KERNELDOC = $(srctree)/scripts/kernel-doc
+KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
+ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
+loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
+
+# $2 sphinx builder e.g. "html"
+# $3 name of the build subfolder / e.g. "media", used as:
+# * dest folder relative to $(BUILDDIR) and
+# * cache folder relative to $(BUILDDIR)/.doctrees
+# $4 dest subfolder e.g. "man" for man pages at media/man
+# $5 reST source folder relative to $(srctree)/$(src),
+# e.g. "media" for the linux-tv book-set at ./Documentation/media
+
+quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
+ cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
+ PYTHONDONTWRITEBYTECODE=1 \
+ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
+ $(SPHINXBUILD) \
+ -b $2 \
+ -c $(abspath $(srctree)/$(src)) \
+ -d $(abspath $(BUILDDIR)/.doctrees/$3) \
+ -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
+ $(ALLSPHINXOPTS) \
+ $(abspath $(srctree)/$(src)/$5) \
+ $(abspath $(BUILDDIR)/$3/$4)
+
+htmldocs:
+ @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+
+linkcheckdocs:
+ @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
+
+latexdocs:
+ @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
+
+ifeq ($(HAVE_PDFLATEX),0)
+
+pdfdocs:
+ $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
+ @echo " SKIP Sphinx $@ target."
+
+else # HAVE_PDFLATEX
+
+pdfdocs: latexdocs
+ $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
+
+endif # HAVE_PDFLATEX
+
+epubdocs:
+ @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
+
+xmldocs:
+ @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
+
+endif # HAVE_SPHINX
+
+# The following targets are independent of HAVE_SPHINX, and the rules should
+# work or silently pass without Sphinx.
+
+# no-ops for the Sphinx toolchain
+sgmldocs:
+ @:
+psdocs:
+ @:
+mandocs:
+ @:
+installmandocs:
+ @:
+
+cleandocs:
+ $(Q)rm -rf $(BUILDDIR)
+ $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
+
+dochelp:
+ @echo ' Linux kernel internal documentation in different formats from ReST:'
+ @echo ' htmldocs - HTML'
+ @echo ' latexdocs - LaTeX'
+ @echo ' pdfdocs - PDF'
+ @echo ' epubdocs - EPUB'
+ @echo ' xmldocs - XML'
+ @echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
+ @echo ' cleandocs - clean all generated files'
+ @echo
+ @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
+ @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
+ @echo
+ @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
+ @echo ' configuration. This is e.g. useful to build with nit-picking config.'
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
deleted file mode 100644
index bcf529f6cf9b..000000000000
--- a/Documentation/Makefile.sphinx
+++ /dev/null
@@ -1,130 +0,0 @@
-# -*- makefile -*-
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXBUILD = sphinx-build
-SPHINXOPTS =
-SPHINXDIRS = .
-_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
-SPHINX_CONF = conf.py
-PAPER =
-BUILDDIR = $(obj)/output
-PDFLATEX = xelatex
-LATEXOPTS = -interaction=batchmode
-
-# User-friendly check for sphinx-build
-HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
-
-ifeq ($(HAVE_SPHINX),0)
-
-.DEFAULT:
- $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
- @echo " SKIP Sphinx $@ target."
-
-else ifneq ($(DOCBOOKS),)
-
-# Skip Sphinx build if the user explicitly requested DOCBOOKS.
-.DEFAULT:
- @echo " SKIP Sphinx $@ target (DOCBOOKS specified)."
-
-else # HAVE_SPHINX
-
-# User-friendly check for pdflatex
-HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
-
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-KERNELDOC = $(srctree)/scripts/kernel-doc
-KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
-ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
-loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
-
-# $2 sphinx builder e.g. "html"
-# $3 name of the build subfolder / e.g. "media", used as:
-# * dest folder relative to $(BUILDDIR) and
-# * cache folder relative to $(BUILDDIR)/.doctrees
-# $4 dest subfolder e.g. "man" for man pages at media/man
-# $5 reST source folder relative to $(srctree)/$(src),
-# e.g. "media" for the linux-tv book-set at ./Documentation/media
-
-quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
- cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
- PYTHONDONTWRITEBYTECODE=1 \
- BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
- $(SPHINXBUILD) \
- -b $2 \
- -c $(abspath $(srctree)/$(src)) \
- -d $(abspath $(BUILDDIR)/.doctrees/$3) \
- -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
- $(ALLSPHINXOPTS) \
- $(abspath $(srctree)/$(src)/$5) \
- $(abspath $(BUILDDIR)/$3/$4)
-
-htmldocs:
- @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
-
-linkcheckdocs:
- @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
-
-latexdocs:
- @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
-
-ifeq ($(HAVE_PDFLATEX),0)
-
-pdfdocs:
- $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
- @echo " SKIP Sphinx $@ target."
-
-else # HAVE_PDFLATEX
-
-pdfdocs: latexdocs
- $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
-
-endif # HAVE_PDFLATEX
-
-epubdocs:
- @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
-
-xmldocs:
- @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
-
-endif # HAVE_SPHINX
-
-# The following targets are independent of HAVE_SPHINX, and the rules should
-# work or silently pass without Sphinx.
-
-# no-ops for the Sphinx toolchain
-sgmldocs:
- @:
-psdocs:
- @:
-mandocs:
- @:
-installmandocs:
- @:
-
-cleandocs:
- $(Q)rm -rf $(BUILDDIR)
- $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
-
-dochelp:
- @echo ' Linux kernel internal documentation in different formats (Sphinx):'
- @echo ' htmldocs - HTML'
- @echo ' latexdocs - LaTeX'
- @echo ' pdfdocs - PDF'
- @echo ' epubdocs - EPUB'
- @echo ' xmldocs - XML'
- @echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
- @echo ' cleandocs - clean all generated files'
- @echo
- @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
- @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
- @echo
- @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
- @echo ' configuration. This is e.g. useful to build with nit-picking config.'
diff --git a/Documentation/doc-guide/docbook.rst b/Documentation/doc-guide/docbook.rst
deleted file mode 100644
index d8bf04308b43..000000000000
--- a/Documentation/doc-guide/docbook.rst
+++ /dev/null
@@ -1,90 +0,0 @@
-DocBook XML [DEPRECATED]
-========================
-
-.. attention::
-
- This section describes the deprecated DocBook XML toolchain. Please do not
- create new DocBook XML template files. Please consider converting existing
- DocBook XML templates files to Sphinx/reStructuredText.
-
-Converting DocBook to Sphinx
-----------------------------
-
-Over time, we expect all of the documents under ``Documentation/DocBook`` to be
-converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
-enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
-which uses ``pandoc`` under the hood. For example::
-
- $ cd Documentation/sphinx
- $ ./tmplcvt ../DocBook/in.tmpl ../out.rst
-
-Then edit the resulting rst files to fix any remaining issues, and add the
-document in the ``toctree`` in ``Documentation/index.rst``.
-
-Components of the kernel-doc system
------------------------------------
-
-Many places in the source tree have extractable documentation in the form of
-block comments above functions. The components of this system are:
-
-- ``scripts/kernel-doc``
-
- This is a perl script that hunts for the block comments and can mark them up
- directly into reStructuredText, DocBook, man, text, and HTML. (No, not
- texinfo.)
-
-- ``Documentation/DocBook/*.tmpl``
-
- These are XML template files, which are normal XML files with special
- place-holders for where the extracted documentation should go.
-
-- ``scripts/docproc.c``
-
- This is a program for converting XML template files into XML files. When a
- file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
- able to distinguish between internal and external functions.
-
- It invokes kernel-doc, giving it the list of functions that are to be
- documented.
-
- Additionally it is used to scan the XML template files to locate all the files
- referenced herein. This is used to generate dependency information as used by
- make.
-
-- ``Makefile``
-
- The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
- DocBook XML files, PostScript files, PDF files, and html files in
- Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
-
-- ``Documentation/DocBook/Makefile``
-
- This is where C files are associated with SGML templates.
-
-How to use kernel-doc comments in DocBook XML template files
-------------------------------------------------------------
-
-DocBook XML template files (\*.tmpl) are like normal XML files, except that they
-can contain escape sequences where extracted documentation should be inserted.
-
-``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
-functions that are exported using ``EXPORT_SYMBOL``: the function list is
-collected from files listed in ``Documentation/DocBook/Makefile``.
-
-``!I<filename>`` is replaced by the documentation for functions that are **not**
-exported using ``EXPORT_SYMBOL``.
-
-``!D<filename>`` is used to name additional files to search for functions
-exported using ``EXPORT_SYMBOL``.
-
-``!F<filename> <function [functions...]>`` is replaced by the documentation, in
-``<filename>``, for the functions listed.
-
-``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
-section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
-``<section title>``; do not quote the ``<section title>``.
-
-``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
-sections and documented functions, symbols, etc. are used. This makes sense to
-use when you use ``!F`` or ``!P`` only and want to verify that all documentation
-is included.
diff --git a/Makefile b/Makefile
index 220121fdca4d..80be98ccca60 100644
--- a/Makefile
+++ b/Makefile
@@ -1298,7 +1298,7 @@ clean: archclean vmlinuxclean
#
mrproper: rm-dirs := $(wildcard $(MRPROPER_DIRS))
mrproper: rm-files := $(wildcard $(MRPROPER_FILES))
-mrproper-dirs := $(addprefix _mrproper_,Documentation/DocBook scripts)
+mrproper-dirs := $(addprefix _mrproper_,scripts)
PHONY += $(mrproper-dirs) mrproper archmrproper
$(mrproper-dirs):
@@ -1400,9 +1400,7 @@ help:
@$(MAKE) $(build)=$(package-dir) help
@echo ''
@echo 'Documentation targets:'
- @$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
- @echo ''
- @$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
+ @$(MAKE) -f $(srctree)/Documentation/Makefile dochelp
@echo ''
@echo 'Architecture specific targets ($(SRCARCH)):'
@$(if $(archhelp),$(archhelp),\
@@ -1453,9 +1451,8 @@ $(help-board-dirs): help-%:
DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
PHONY += $(DOC_TARGETS)
$(DOC_TARGETS): scripts_basic FORCE
- $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
- $(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
- $(Q)$(MAKE) $(build)=Documentation/DocBook $@
+ $(Q)$(MAKE) $(build)=scripts build_docproc
+ $(Q)$(MAKE) $(build)=Documentation $@
else # KBUILD_EXTMOD
diff --git a/scripts/Makefile b/scripts/Makefile
index 1d80897a9644..55550e4141c4 100644
--- a/scripts/Makefile
+++ b/scripts/Makefile
@@ -6,8 +6,7 @@
# pnmttologo: Convert pnm files to logo files
# conmakehash: Create chartable
# conmakehash: Create arrays for initializing the kernel console tables
-# docproc: Used in Documentation/DocBook
-# check-lc_ctype: Used in Documentation/DocBook
+# docproc: Used in Documentation/
HOST_EXTRACFLAGS += -I$(srctree)/tools/include
@@ -29,16 +28,14 @@ HOSTLOADLIBES_extract-cert = -lcrypto
always := $(hostprogs-y) $(hostprogs-m)
# The following hostprogs-y programs are only build on demand
-hostprogs-y += unifdef docproc check-lc_ctype
+hostprogs-y += unifdef docproc
# These targets are used internally to avoid "is up to date" messages
-PHONY += build_unifdef build_docproc build_check-lc_ctype
+PHONY += build_unifdef build_docproc
build_unifdef: $(obj)/unifdef
@:
build_docproc: $(obj)/docproc
@:
-build_check-lc_ctype: $(obj)/check-lc_ctype
- @:
subdir-$(CONFIG_MODVERSIONS) += genksyms
subdir-y += mod
diff --git a/scripts/check-lc_ctype.c b/scripts/check-lc_ctype.c
deleted file mode 100644
index 9097ff5449fb..000000000000
--- a/scripts/check-lc_ctype.c
+++ /dev/null
@@ -1,11 +0,0 @@
-/*
- * Check that a specified locale works as LC_CTYPE. Used by the
- * DocBook build system to probe for C.UTF-8 support.
- */
-
-#include <locale.h>
-
-int main(void)
-{
- return !setlocale(LC_CTYPE, "");
-}
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 32/53] docs-rst: convert scsi DocBook to ReST |
| Message-ID | <tHJLZ-5yL-47@gated-at.bofh.it> |
| In reply to | #1642478 |
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 1 -
Documentation/DocBook/scsi.tmpl | 409 ---------------------------------
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/scsi.rst | 344 +++++++++++++++++++++++++++
Documentation/networking/z8530book.rst | 15 +-
5 files changed, 352 insertions(+), 418 deletions(-)
delete mode 100644 Documentation/DocBook/scsi.tmpl
create mode 100644 Documentation/driver-api/scsi.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 00a61f4ffcff..3bbda02d6aee 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -9,7 +9,6 @@
DOCBOOKS := \
lsm.xml \
mtdnand.xml librs.xml rapidio.xml \
- scsi.xml \
sh.xml w1.xml
ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl
deleted file mode 100644
index 4b9b9b286cea..000000000000
--- a/Documentation/DocBook/scsi.tmpl
+++ /dev/null
@@ -1,409 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="scsimid">
- <bookinfo>
- <title>SCSI Interfaces Guide</title>
-
- <authorgroup>
- <author>
- <firstname>James</firstname>
- <surname>Bottomley</surname>
- <affiliation>
- <address>
- <email>James.Bottomley@hansenpartnership.com</email>
- </address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Rob</firstname>
- <surname>Landley</surname>
- <affiliation>
- <address>
- <email>rob@landley.net</email>
- </address>
- </affiliation>
- </author>
-
- </authorgroup>
-
- <copyright>
- <year>2007</year>
- <holder>Linux Foundation</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2.
- </para>
-
- <para>
- 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.
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
- <toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <sect1 id="protocol_vs_bus">
- <title>Protocol vs bus</title>
- <para>
- Once upon a time, the Small Computer Systems Interface defined both
- a parallel I/O bus and a data protocol to connect a wide variety of
- peripherals (disk drives, tape drives, modems, printers, scanners,
- optical drives, test equipment, and medical devices) to a host
- computer.
- </para>
- <para>
- Although the old parallel (fast/wide/ultra) SCSI bus has largely
- fallen out of use, the SCSI command set is more widely used than ever
- to communicate with devices over a number of different busses.
- </para>
- <para>
- The <ulink url='http://www.t10.org/scsi-3.htm'>SCSI protocol</ulink>
- is a big-endian peer-to-peer packet based protocol. SCSI commands
- are 6, 10, 12, or 16 bytes long, often followed by an associated data
- payload.
- </para>
- <para>
- SCSI commands can be transported over just about any kind of bus, and
- are the default protocol for storage devices attached to USB, SATA,
- SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are
- also commonly exchanged over Infiniband,
- <ulink url='http://i2o.shadowconnect.com/faq.php'>I20</ulink>, TCP/IP
- (<ulink url='https://en.wikipedia.org/wiki/ISCSI'>iSCSI</ulink>), even
- <ulink url='http://cyberelk.net/tim/parport/parscsi.html'>Parallel
- ports</ulink>.
- </para>
- </sect1>
- <sect1 id="subsystem_design">
- <title>Design of the Linux SCSI subsystem</title>
- <para>
- The SCSI subsystem uses a three layer design, with upper, mid, and low
- layers. Every operation involving the SCSI subsystem (such as reading
- a sector from a disk) uses one driver at each of the 3 levels: one
- upper layer driver, one lower layer driver, and the SCSI midlayer.
- </para>
- <para>
- The SCSI upper layer provides the interface between userspace and the
- kernel, in the form of block and char device nodes for I/O and
- ioctl(). The SCSI lower layer contains drivers for specific hardware
- devices.
- </para>
- <para>
- In between is the SCSI mid-layer, analogous to a network routing
- layer such as the IPv4 stack. The SCSI mid-layer routes a packet
- based data protocol between the upper layer's /dev nodes and the
- corresponding devices in the lower layer. It manages command queues,
- provides error handling and power management functions, and responds
- to ioctl() requests.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="upper_layer">
- <title>SCSI upper layer</title>
- <para>
- The upper layer supports the user-kernel interface by providing
- device nodes.
- </para>
- <sect1 id="sd">
- <title>sd (SCSI Disk)</title>
- <para>sd (sd_mod.o)</para>
-<!-- !Idrivers/scsi/sd.c -->
- </sect1>
- <sect1 id="sr">
- <title>sr (SCSI CD-ROM)</title>
- <para>sr (sr_mod.o)</para>
- </sect1>
- <sect1 id="st">
- <title>st (SCSI Tape)</title>
- <para>st (st.o)</para>
- </sect1>
- <sect1 id="sg">
- <title>sg (SCSI Generic)</title>
- <para>sg (sg.o)</para>
- </sect1>
- <sect1 id="ch">
- <title>ch (SCSI Media Changer)</title>
- <para>ch (ch.c)</para>
- </sect1>
- </chapter>
-
- <chapter id="mid_layer">
- <title>SCSI mid layer</title>
-
- <sect1 id="midlayer_implementation">
- <title>SCSI midlayer implementation</title>
- <sect2 id="scsi_device.h">
- <title>include/scsi/scsi_device.h</title>
- <para>
- </para>
-!Iinclude/scsi/scsi_device.h
- </sect2>
-
- <sect2 id="scsi.c">
- <title>drivers/scsi/scsi.c</title>
- <para>Main file for the SCSI midlayer.</para>
-!Edrivers/scsi/scsi.c
- </sect2>
- <sect2 id="scsicam.c">
- <title>drivers/scsi/scsicam.c</title>
- <para>
- <ulink url='http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf'>SCSI
- Common Access Method</ulink> support functions, for use with
- HDIO_GETGEO, etc.
- </para>
-!Edrivers/scsi/scsicam.c
- </sect2>
- <sect2 id="scsi_error.c">
- <title>drivers/scsi/scsi_error.c</title>
- <para>Common SCSI error/timeout handling routines.</para>
-!Edrivers/scsi/scsi_error.c
- </sect2>
- <sect2 id="scsi_devinfo.c">
- <title>drivers/scsi/scsi_devinfo.c</title>
- <para>
- Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
- devices.
- </para>
-!Idrivers/scsi/scsi_devinfo.c
- </sect2>
- <sect2 id="scsi_ioctl.c">
- <title>drivers/scsi/scsi_ioctl.c</title>
- <para>
- Handle ioctl() calls for SCSI devices.
- </para>
-!Edrivers/scsi/scsi_ioctl.c
- </sect2>
- <sect2 id="scsi_lib.c">
- <title>drivers/scsi/scsi_lib.c</title>
- <para>
- SCSI queuing library.
- </para>
-!Edrivers/scsi/scsi_lib.c
- </sect2>
- <sect2 id="scsi_lib_dma.c">
- <title>drivers/scsi/scsi_lib_dma.c</title>
- <para>
- SCSI library functions depending on DMA
- (map and unmap scatter-gather lists).
- </para>
-!Edrivers/scsi/scsi_lib_dma.c
- </sect2>
- <sect2 id="scsi_module.c">
- <title>drivers/scsi/scsi_module.c</title>
- <para>
- The file drivers/scsi/scsi_module.c contains legacy support for
- old-style host templates. It should never be used by any new driver.
- </para>
- </sect2>
- <sect2 id="scsi_proc.c">
- <title>drivers/scsi/scsi_proc.c</title>
- <para>
- The functions in this file provide an interface between
- the PROC file system and the SCSI device drivers
- It is mainly used for debugging, statistics and to pass
- information directly to the lowlevel driver.
-
- I.E. plumbing to manage /proc/scsi/*
- </para>
-!Idrivers/scsi/scsi_proc.c
- </sect2>
- <sect2 id="scsi_netlink.c">
- <title>drivers/scsi/scsi_netlink.c</title>
- <para>
- Infrastructure to provide async events from transports to userspace
- via netlink, using a single NETLINK_SCSITRANSPORT protocol for all
- transports.
-
- See <ulink url='http://marc.info/?l=linux-scsi&m=115507374832500&w=2'>the
- original patch submission</ulink> for more details.
- </para>
-!Idrivers/scsi/scsi_netlink.c
- </sect2>
- <sect2 id="scsi_scan.c">
- <title>drivers/scsi/scsi_scan.c</title>
- <para>
- Scan a host to determine which (if any) devices are attached.
-
- The general scanning/probing algorithm is as follows, exceptions are
- made to it depending on device specific flags, compilation options,
- and global variable (boot or module load time) settings.
-
- A specific LUN is scanned via an INQUIRY command; if the LUN has a
- device attached, a scsi_device is allocated and setup for it.
-
- For every id of every channel on the given host, start by scanning
- LUN 0. Skip hosts that don't respond at all to a scan of LUN 0.
- Otherwise, if LUN 0 has a device attached, allocate and setup a
- scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN,
- and scan all of the LUNs returned by the REPORT LUN; else,
- sequentially scan LUNs up until some maximum is reached, or a LUN is
- seen that cannot have a device attached to it.
- </para>
-!Idrivers/scsi/scsi_scan.c
- </sect2>
- <sect2 id="scsi_sysctl.c">
- <title>drivers/scsi/scsi_sysctl.c</title>
- <para>
- Set up the sysctl entry: "/dev/scsi/logging_level"
- (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
- </para>
- </sect2>
- <sect2 id="scsi_sysfs.c">
- <title>drivers/scsi/scsi_sysfs.c</title>
- <para>
- SCSI sysfs interface routines.
- </para>
-!Edrivers/scsi/scsi_sysfs.c
- </sect2>
- <sect2 id="hosts.c">
- <title>drivers/scsi/hosts.c</title>
- <para>
- mid to lowlevel SCSI driver interface
- </para>
-!Edrivers/scsi/hosts.c
- </sect2>
- <sect2 id="constants.c">
- <title>drivers/scsi/constants.c</title>
- <para>
- mid to lowlevel SCSI driver interface
- </para>
-!Edrivers/scsi/constants.c
- </sect2>
- </sect1>
-
- <sect1 id="Transport_classes">
- <title>Transport classes</title>
- <para>
- Transport classes are service libraries for drivers in the SCSI
- lower layer, which expose transport attributes in sysfs.
- </para>
- <sect2 id="Fibre_Channel_transport">
- <title>Fibre Channel transport</title>
- <para>
- The file drivers/scsi/scsi_transport_fc.c defines transport attributes
- for Fibre Channel.
- </para>
-!Edrivers/scsi/scsi_transport_fc.c
- </sect2>
- <sect2 id="iSCSI_transport">
- <title>iSCSI transport class</title>
- <para>
- The file drivers/scsi/scsi_transport_iscsi.c defines transport
- attributes for the iSCSI class, which sends SCSI packets over TCP/IP
- connections.
- </para>
-!Edrivers/scsi/scsi_transport_iscsi.c
- </sect2>
- <sect2 id="SAS_transport">
- <title>Serial Attached SCSI (SAS) transport class</title>
- <para>
- The file drivers/scsi/scsi_transport_sas.c defines transport
- attributes for Serial Attached SCSI, a variant of SATA aimed at
- large high-end systems.
- </para>
- <para>
- The SAS transport class contains common code to deal with SAS HBAs,
- an aproximated representation of SAS topologies in the driver model,
- and various sysfs attributes to expose these topologies and management
- interfaces to userspace.
- </para>
- <para>
- In addition to the basic SCSI core objects this transport class
- introduces two additional intermediate objects: The SAS PHY
- as represented by struct sas_phy defines an "outgoing" PHY on
- a SAS HBA or Expander, and the SAS remote PHY represented by
- struct sas_rphy defines an "incoming" PHY on a SAS Expander or
- end device. Note that this is purely a software concept, the
- underlying hardware for a PHY and a remote PHY is the exactly
- the same.
- </para>
- <para>
- There is no concept of a SAS port in this code, users can see
- what PHYs form a wide port based on the port_identifier attribute,
- which is the same for all PHYs in a port.
- </para>
-!Edrivers/scsi/scsi_transport_sas.c
- </sect2>
- <sect2 id="SATA_transport">
- <title>SATA transport class</title>
- <para>
- The SATA transport is handled by libata, which has its own book of
- documentation in this directory.
- </para>
- </sect2>
- <sect2 id="SPI_transport">
- <title>Parallel SCSI (SPI) transport class</title>
- <para>
- The file drivers/scsi/scsi_transport_spi.c defines transport
- attributes for traditional (fast/wide/ultra) SCSI busses.
- </para>
-!Edrivers/scsi/scsi_transport_spi.c
- </sect2>
- <sect2 id="SRP_transport">
- <title>SCSI RDMA (SRP) transport class</title>
- <para>
- The file drivers/scsi/scsi_transport_srp.c defines transport
- attributes for SCSI over Remote Direct Memory Access.
- </para>
-!Edrivers/scsi/scsi_transport_srp.c
- </sect2>
- </sect1>
-
- </chapter>
-
- <chapter id="lower_layer">
- <title>SCSI lower layer</title>
- <sect1 id="hba_drivers">
- <title>Host Bus Adapter transport types</title>
- <para>
- Many modern device controllers use the SCSI command set as a protocol to
- communicate with their devices through many different types of physical
- connections.
- </para>
- <para>
- In SCSI language a bus capable of carrying SCSI commands is
- called a "transport", and a controller connecting to such a bus is
- called a "host bus adapter" (HBA).
- </para>
- <sect2 id="scsi_debug.c">
- <title>Debug transport</title>
- <para>
- The file drivers/scsi/scsi_debug.c simulates a host adapter with a
- variable number of disks (or disk like devices) attached, sharing a
- common amount of RAM. Does a lot of checking to make sure that we are
- not getting blocks mixed up, and panics the kernel if anything out of
- the ordinary is seen.
- </para>
- <para>
- To be more realistic, the simulated devices have the transport
- attributes of SAS disks.
- </para>
- <para>
- For documentation see
- <ulink url='http://sg.danny.cz/sg/sdebug26.html'>http://sg.danny.cz/sg/sdebug26.html</ulink>
- </para>
-<!-- !Edrivers/scsi/scsi_debug.c -->
- </sect2>
- <sect2 id="todo">
- <title>todo</title>
- <para>Parallel (fast/wide/ultra) SCSI, USB, SATA,
- SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband,
- I20, iSCSI, Parallel ports, netlink...
- </para>
- </sect2>
- </sect1>
- </chapter>
-</book>
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index a9687731810e..9589b06e374e 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -32,6 +32,7 @@ available subsections can be seen below.
i2c
hsi
edac
+ scsi
libata
miscellaneous
s390-drivers
diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst
new file mode 100644
index 000000000000..859fb672319f
--- /dev/null
+++ b/Documentation/driver-api/scsi.rst
@@ -0,0 +1,344 @@
+=====================
+SCSI Interfaces Guide
+=====================
+
+:Author: James Bottomley
+:Author: Rob Landley
+
+Introduction
+============
+
+Protocol vs bus
+---------------
+
+Once upon a time, the Small Computer Systems Interface defined both a
+parallel I/O bus and a data protocol to connect a wide variety of
+peripherals (disk drives, tape drives, modems, printers, scanners,
+optical drives, test equipment, and medical devices) to a host computer.
+
+Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen
+out of use, the SCSI command set is more widely used than ever to
+communicate with devices over a number of different busses.
+
+The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ is a big-endian
+peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16
+bytes long, often followed by an associated data payload.
+
+SCSI commands can be transported over just about any kind of bus, and
+are the default protocol for storage devices attached to USB, SATA, SAS,
+Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also
+commonly exchanged over Infiniband,
+`I20 <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP
+(`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel
+ports <http://cyberelk.net/tim/parport/parscsi.html>`__.
+
+Design of the Linux SCSI subsystem
+----------------------------------
+
+The SCSI subsystem uses a three layer design, with upper, mid, and low
+layers. Every operation involving the SCSI subsystem (such as reading a
+sector from a disk) uses one driver at each of the 3 levels: one upper
+layer driver, one lower layer driver, and the SCSI midlayer.
+
+The SCSI upper layer provides the interface between userspace and the
+kernel, in the form of block and char device nodes for I/O and ioctl().
+The SCSI lower layer contains drivers for specific hardware devices.
+
+In between is the SCSI mid-layer, analogous to a network routing layer
+such as the IPv4 stack. The SCSI mid-layer routes a packet based data
+protocol between the upper layer's /dev nodes and the corresponding
+devices in the lower layer. It manages command queues, provides error
+handling and power management functions, and responds to ioctl()
+requests.
+
+SCSI upper layer
+================
+
+The upper layer supports the user-kernel interface by providing device
+nodes.
+
+sd (SCSI Disk)
+--------------
+
+sd (sd_mod.o)
+
+sr (SCSI CD-ROM)
+----------------
+
+sr (sr_mod.o)
+
+st (SCSI Tape)
+--------------
+
+st (st.o)
+
+sg (SCSI Generic)
+-----------------
+
+sg (sg.o)
+
+ch (SCSI Media Changer)
+-----------------------
+
+ch (ch.c)
+
+SCSI mid layer
+==============
+
+SCSI midlayer implementation
+----------------------------
+
+include/scsi/scsi_device.h
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: include/scsi/scsi_device.h
+ :internal:
+
+drivers/scsi/scsi.c
+~~~~~~~~~~~~~~~~~~~
+
+Main file for the SCSI midlayer.
+
+.. kernel-doc:: drivers/scsi/scsi.c
+ :export:
+
+drivers/scsi/scsicam.c
+~~~~~~~~~~~~~~~~~~~~~~
+
+`SCSI Common Access
+Method <http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf>`__ support
+functions, for use with HDIO_GETGEO, etc.
+
+.. kernel-doc:: drivers/scsi/scsicam.c
+ :export:
+
+drivers/scsi/scsi_error.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Common SCSI error/timeout handling routines.
+
+.. kernel-doc:: drivers/scsi/scsi_error.c
+ :export:
+
+drivers/scsi/scsi_devinfo.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
+devices.
+
+.. kernel-doc:: drivers/scsi/scsi_devinfo.c
+ :internal:
+
+drivers/scsi/scsi_ioctl.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Handle ioctl() calls for SCSI devices.
+
+.. kernel-doc:: drivers/scsi/scsi_ioctl.c
+ :export:
+
+drivers/scsi/scsi_lib.c
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+SCSI queuing library.
+
+.. kernel-doc:: drivers/scsi/scsi_lib.c
+ :export:
+
+drivers/scsi/scsi_lib_dma.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SCSI library functions depending on DMA (map and unmap scatter-gather
+lists).
+
+.. kernel-doc:: drivers/scsi/scsi_lib_dma.c
+ :export:
+
+drivers/scsi/scsi_module.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The file drivers/scsi/scsi_module.c contains legacy support for
+old-style host templates. It should never be used by any new driver.
+
+drivers/scsi/scsi_proc.c
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The functions in this file provide an interface between the PROC file
+system and the SCSI device drivers It is mainly used for debugging,
+statistics and to pass information directly to the lowlevel driver. I.E.
+plumbing to manage /proc/scsi/\*
+
+.. kernel-doc:: drivers/scsi/scsi_proc.c
+ :internal:
+
+drivers/scsi/scsi_netlink.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Infrastructure to provide async events from transports to userspace via
+netlink, using a single NETLINK_SCSITRANSPORT protocol for all
+transports. See `the original patch
+submission <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for
+more details.
+
+.. kernel-doc:: drivers/scsi/scsi_netlink.c
+ :internal:
+
+drivers/scsi/scsi_scan.c
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Scan a host to determine which (if any) devices are attached. The
+general scanning/probing algorithm is as follows, exceptions are made to
+it depending on device specific flags, compilation options, and global
+variable (boot or module load time) settings. A specific LUN is scanned
+via an INQUIRY command; if the LUN has a device attached, a scsi_device
+is allocated and setup for it. For every id of every channel on the
+given host, start by scanning LUN 0. Skip hosts that don't respond at
+all to a scan of LUN 0. Otherwise, if LUN 0 has a device attached,
+allocate and setup a scsi_device for it. If target is SCSI-3 or up,
+issue a REPORT LUN, and scan all of the LUNs returned by the REPORT LUN;
+else, sequentially scan LUNs up until some maximum is reached, or a LUN
+is seen that cannot have a device attached to it.
+
+.. kernel-doc:: drivers/scsi/scsi_scan.c
+ :internal:
+
+drivers/scsi/scsi_sysctl.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set up the sysctl entry: "/dev/scsi/logging_level"
+(DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
+
+drivers/scsi/scsi_sysfs.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SCSI sysfs interface routines.
+
+.. kernel-doc:: drivers/scsi/scsi_sysfs.c
+ :export:
+
+drivers/scsi/hosts.c
+~~~~~~~~~~~~~~~~~~~~
+
+mid to lowlevel SCSI driver interface
+
+.. kernel-doc:: drivers/scsi/hosts.c
+ :export:
+
+drivers/scsi/constants.c
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+mid to lowlevel SCSI driver interface
+
+.. kernel-doc:: drivers/scsi/constants.c
+ :export:
+
+Transport classes
+-----------------
+
+Transport classes are service libraries for drivers in the SCSI lower
+layer, which expose transport attributes in sysfs.
+
+Fibre Channel transport
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The file drivers/scsi/scsi_transport_fc.c defines transport attributes
+for Fibre Channel.
+
+.. kernel-doc:: drivers/scsi/scsi_transport_fc.c
+ :export:
+
+iSCSI transport class
+~~~~~~~~~~~~~~~~~~~~~
+
+The file drivers/scsi/scsi_transport_iscsi.c defines transport
+attributes for the iSCSI class, which sends SCSI packets over TCP/IP
+connections.
+
+.. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
+ :export:
+
+Serial Attached SCSI (SAS) transport class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The file drivers/scsi/scsi_transport_sas.c defines transport
+attributes for Serial Attached SCSI, a variant of SATA aimed at large
+high-end systems.
+
+The SAS transport class contains common code to deal with SAS HBAs, an
+aproximated representation of SAS topologies in the driver model, and
+various sysfs attributes to expose these topologies and management
+interfaces to userspace.
+
+In addition to the basic SCSI core objects this transport class
+introduces two additional intermediate objects: The SAS PHY as
+represented by struct sas_phy defines an "outgoing" PHY on a SAS HBA or
+Expander, and the SAS remote PHY represented by struct sas_rphy defines
+an "incoming" PHY on a SAS Expander or end device. Note that this is
+purely a software concept, the underlying hardware for a PHY and a
+remote PHY is the exactly the same.
+
+There is no concept of a SAS port in this code, users can see what PHYs
+form a wide port based on the port_identifier attribute, which is the
+same for all PHYs in a port.
+
+.. kernel-doc:: drivers/scsi/scsi_transport_sas.c
+ :export:
+
+SATA transport class
+~~~~~~~~~~~~~~~~~~~~
+
+The SATA transport is handled by libata, which has its own book of
+documentation in this directory.
+
+Parallel SCSI (SPI) transport class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The file drivers/scsi/scsi_transport_spi.c defines transport
+attributes for traditional (fast/wide/ultra) SCSI busses.
+
+.. kernel-doc:: drivers/scsi/scsi_transport_spi.c
+ :export:
+
+SCSI RDMA (SRP) transport class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The file drivers/scsi/scsi_transport_srp.c defines transport
+attributes for SCSI over Remote Direct Memory Access.
+
+.. kernel-doc:: drivers/scsi/scsi_transport_srp.c
+ :export:
+
+SCSI lower layer
+================
+
+Host Bus Adapter transport types
+--------------------------------
+
+Many modern device controllers use the SCSI command set as a protocol to
+communicate with their devices through many different types of physical
+connections.
+
+In SCSI language a bus capable of carrying SCSI commands is called a
+"transport", and a controller connecting to such a bus is called a "host
+bus adapter" (HBA).
+
+Debug transport
+~~~~~~~~~~~~~~~
+
+The file drivers/scsi/scsi_debug.c simulates a host adapter with a
+variable number of disks (or disk like devices) attached, sharing a
+common amount of RAM. Does a lot of checking to make sure that we are
+not getting blocks mixed up, and panics the kernel if anything out of
+the ordinary is seen.
+
+To be more realistic, the simulated devices have the transport
+attributes of SAS disks.
+
+For documentation see http://sg.danny.cz/sg/sdebug26.html
+
+todo
+~~~~
+
+Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,
+FireWire, ATAPI devices, Infiniband, I20, iSCSI, Parallel ports,
+netlink...
diff --git a/Documentation/networking/z8530book.rst b/Documentation/networking/z8530book.rst
index 31032ee36081..fea2c40e7973 100644
--- a/Documentation/networking/z8530book.rst
+++ b/Documentation/networking/z8530book.rst
@@ -170,10 +170,10 @@ This function is very timing critical. When you wish to simply discard
data the support code provides the function
:c:func:`z8530_null_rx()` to discard the data.
-To active PIO mode sending and receiving the ``
- z8530_sync_open`` is called. This expects to be passed the network
-device and the channel. Typically this is called from your network
-device open callback. On a failure a non zero error status is returned.
+To active PIO mode sending and receiving the ``z8530_sync_open`` is called.
+This expects to be passed the network device and the channel. Typically
+this is called from your network device open callback. On a failure a
+non zero error status is returned.
The :c:func:`z8530_sync_close()` function shuts down a PIO
channel. This must be done before the channel is opened again and before
the driver shuts down and unloads.
@@ -190,8 +190,7 @@ the close function matching the open mode you used.
The final supported mode uses a single DMA channel to drive the transmit
side. As the Z85C30 has a larger FIFO on the receive channel this tends
to increase the maximum speed a little. This is activated by calling the
-``z8530_sync_txdma_open
- ``. This returns a non zero error code on failure. The
+``z8530_sync_txdma_open``. This returns a non zero error code on failure. The
:c:func:`z8530_sync_txdma_close()` function closes down the Z8530
interface from this mode.
@@ -228,8 +227,8 @@ Should you need to retarget the Z8530 driver to another architecture the
only code that should need changing are the port I/O functions. At the
moment these assume PC I/O port accesses. This may not be appropriate
for all platforms. Replacing :c:func:`z8530_read_port()` and
-``z8530_write_port
- `` is intended to be all that is required to port this driver layer.
+``z8530_write_port`` is intended to be all that is required to port
+this driver layer.
Known Bugs And Assumptions
==========================
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 48/53] fs: update location of filesystems documentation |
| Message-ID | <tHJM0-5yL-61@gated-at.bofh.it> |
| In reply to | #1642478 |
The filesystem documentation was moved from DocBook to Documentation/filesystems/. Update it at the sources. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- fs/debugfs/file.c | 2 +- include/linux/debugfs.h | 2 +- lib/Kconfig.debug | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/fs/debugfs/file.c b/fs/debugfs/file.c index 354e2ab62031..6dabc4a10396 100644 --- a/fs/debugfs/file.c +++ b/fs/debugfs/file.c @@ -9,7 +9,7 @@ * 2 as published by the Free Software Foundation. * * debugfs is for people to use instead of /proc or /sys. - * See Documentation/DocBook/filesystems for more details. + * See Documentation/filesystems/ for more details. * */ diff --git a/include/linux/debugfs.h b/include/linux/debugfs.h index 9174b0d28582..aa86e6d8c1aa 100644 --- a/include/linux/debugfs.h +++ b/include/linux/debugfs.h @@ -9,7 +9,7 @@ * 2 as published by the Free Software Foundation. * * debugfs is for people to use instead of /proc or /sys. - * See Documentation/DocBook/filesystems for more details. + * See Documentation/filesystems/ for more details. */ #ifndef _DEBUGFS_H_ diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index e4587ebe52c7..b7882d45f48e 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -286,7 +286,7 @@ config DEBUG_FS write to these files. For detailed documentation on the debugfs API, see - Documentation/DocBook/filesystems. + Documentation/filesystems/. If unsure, say N. -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 34/53] docs-rst: convert w1 book to ReST |
| Message-ID | <tHJLZ-5yL-49@gated-at.bofh.it> |
| In reply to | #1642478 |
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/w1.tmpl | 101 -------------------------------------
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/w1.rst | 70 +++++++++++++++++++++++++
3 files changed, 71 insertions(+), 101 deletions(-)
delete mode 100644 Documentation/DocBook/w1.tmpl
create mode 100644 Documentation/driver-api/w1.rst
diff --git a/Documentation/DocBook/w1.tmpl b/Documentation/DocBook/w1.tmpl
deleted file mode 100644
index b0228d4c81bb..000000000000
--- a/Documentation/DocBook/w1.tmpl
+++ /dev/null
@@ -1,101 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="w1id">
- <bookinfo>
- <title>W1: Dallas' 1-wire bus</title>
-
- <authorgroup>
- <author>
- <firstname>David</firstname>
- <surname>Fries</surname>
- <affiliation>
- <address>
- <email>David@Fries.net</email>
- </address>
- </affiliation>
- </author>
-
- </authorgroup>
-
- <copyright>
- <year>2013</year>
- <!--
- <holder></holder>
- -->
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2.
- </para>
-
- <para>
- 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.
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
- <toc></toc>
-
- <chapter id="w1_internal">
- <title>W1 API internal to the kernel</title>
-
- <sect1 id="w1_internal_api">
- <title>W1 API internal to the kernel</title>
- <sect2 id="w1.h">
- <title>drivers/w1/w1.h</title>
- <para>W1 core functions.</para>
-!Idrivers/w1/w1.h
- </sect2>
-
- <sect2 id="w1.c">
- <title>drivers/w1/w1.c</title>
- <para>W1 core functions.</para>
-!Idrivers/w1/w1.c
- </sect2>
-
- <sect2 id="w1_family.h">
- <title>drivers/w1/w1_family.h</title>
- <para>Allows registering device family operations.</para>
-!Idrivers/w1/w1_family.h
- </sect2>
-
- <sect2 id="w1_family.c">
- <title>drivers/w1/w1_family.c</title>
- <para>Allows registering device family operations.</para>
-!Edrivers/w1/w1_family.c
- </sect2>
-
- <sect2 id="w1_int.c">
- <title>drivers/w1/w1_int.c</title>
- <para>W1 internal initialization for master devices.</para>
-!Edrivers/w1/w1_int.c
- </sect2>
-
- <sect2 id="w1_netlink.h">
- <title>drivers/w1/w1_netlink.h</title>
- <para>W1 external netlink API structures and commands.</para>
-!Idrivers/w1/w1_netlink.h
- </sect2>
-
- <sect2 id="w1_io.c">
- <title>drivers/w1/w1_io.c</title>
- <para>W1 input/output.</para>
-!Edrivers/w1/w1_io.c
-!Idrivers/w1/w1_io.c
- </sect2>
-
- </sect1>
-
-
- </chapter>
-
-</book>
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 9589b06e374e..8610aab8f342 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -35,6 +35,7 @@ available subsections can be seen below.
scsi
libata
miscellaneous
+ w1
s390-drivers
vme
80211/index
diff --git a/Documentation/driver-api/w1.rst b/Documentation/driver-api/w1.rst
new file mode 100644
index 000000000000..c1da8f0cb476
--- /dev/null
+++ b/Documentation/driver-api/w1.rst
@@ -0,0 +1,70 @@
+======================
+W1: Dallas' 1-wire bus
+======================
+
+:Author: David Fries
+
+W1 API internal to the kernel
+=============================
+
+W1 API internal to the kernel
+-----------------------------
+
+drivers/w1/w1.h
+~~~~~~~~~~~~~~~
+
+W1 core functions.
+
+.. kernel-doc:: drivers/w1/w1.h
+ :internal:
+
+drivers/w1/w1.c
+~~~~~~~~~~~~~~~
+
+W1 core functions.
+
+.. kernel-doc:: drivers/w1/w1.c
+ :internal:
+
+drivers/w1/w1_family.h
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows registering device family operations.
+
+.. kernel-doc:: drivers/w1/w1_family.h
+ :internal:
+
+drivers/w1/w1_family.c
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows registering device family operations.
+
+.. kernel-doc:: drivers/w1/w1_family.c
+ :export:
+
+drivers/w1/w1_int.c
+~~~~~~~~~~~~~~~~~~~~
+
+W1 internal initialization for master devices.
+
+.. kernel-doc:: drivers/w1/w1_int.c
+ :export:
+
+drivers/w1/w1_netlink.h
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+W1 external netlink API structures and commands.
+
+.. kernel-doc:: drivers/w1/w1_netlink.h
+ :internal:
+
+drivers/w1/w1_io.c
+~~~~~~~~~~~~~~~~~~~
+
+W1 input/output.
+
+.. kernel-doc:: drivers/w1/w1_io.c
+ :export:
+
+.. kernel-doc:: drivers/w1/w1_io.c
+ :internal:
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 49/53] lib: update location of kgdb documentation |
| Message-ID | <tHJM0-5yL-55@gated-at.bofh.it> |
| In reply to | #1642478 |
The documentation was moved from DocBook directory. Update its location. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- lib/Kconfig.kgdb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/Kconfig.kgdb b/lib/Kconfig.kgdb index 533f912638ed..ab4ff0eea776 100644 --- a/lib/Kconfig.kgdb +++ b/lib/Kconfig.kgdb @@ -13,7 +13,7 @@ menuconfig KGDB CONFIG_FRAME_POINTER to aid in producing more reliable stack backtraces in the external debugger. Documentation of kernel debugger is available at http://kgdb.sourceforge.net - as well as in DocBook form in Documentation/DocBook/. If + as well as in Documentation/dev-tools/kgdb.rst. If unsure, say N. if KGDB -- 2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 28/53] docs-rst: convert networking book to ReST |
| Message-ID | <tHJM0-5yL-63@gated-at.bofh.it> |
| In reply to | #1642478 |
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DocBook/Makefile | 1 -
Documentation/DocBook/networking.tmpl | 111 -------------------------
Documentation/conf.py | 2 +
Documentation/index.rst | 1 +
Documentation/networking/conf.py | 10 +++
Documentation/networking/index.rst | 17 ++++
Documentation/networking/kapi.rst | 147 ++++++++++++++++++++++++++++++++++
7 files changed, 177 insertions(+), 112 deletions(-)
delete mode 100644 Documentation/DocBook/networking.tmpl
create mode 100644 Documentation/networking/conf.py
create mode 100644 Documentation/networking/index.rst
create mode 100644 Documentation/networking/kapi.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index a25bf10384e1..8a90891c3712 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -7,7 +7,6 @@
# list of DOCBOOKS.
DOCBOOKS := z8530book.xml \
- networking.xml \
lsm.xml \
mtdnand.xml librs.xml rapidio.xml \
scsi.xml \
diff --git a/Documentation/DocBook/networking.tmpl b/Documentation/DocBook/networking.tmpl
deleted file mode 100644
index 29df25016c7c..000000000000
--- a/Documentation/DocBook/networking.tmpl
+++ /dev/null
@@ -1,111 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="LinuxNetworking">
- <bookinfo>
- <title>Linux Networking and Network Devices APIs</title>
-
- <legalnotice>
- <para>
- This documentation 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; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- 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.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- 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., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="netcore">
- <title>Linux Networking</title>
- <sect1><title>Networking Base Types</title>
-!Iinclude/linux/net.h
- </sect1>
- <sect1><title>Socket Buffer Functions</title>
-!Iinclude/linux/skbuff.h
-!Iinclude/net/sock.h
-!Enet/socket.c
-!Enet/core/skbuff.c
-!Enet/core/sock.c
-!Enet/core/datagram.c
-!Enet/core/stream.c
- </sect1>
- <sect1><title>Socket Filter</title>
-!Enet/core/filter.c
- </sect1>
- <sect1><title>Generic Network Statistics</title>
-!Iinclude/uapi/linux/gen_stats.h
-!Enet/core/gen_stats.c
-!Enet/core/gen_estimator.c
- </sect1>
- <sect1><title>SUN RPC subsystem</title>
-<!-- The !D functionality is not perfect, garbage has to be protected by comments
-!Dnet/sunrpc/sunrpc_syms.c
--->
-!Enet/sunrpc/xdr.c
-!Enet/sunrpc/svc_xprt.c
-!Enet/sunrpc/xprt.c
-!Enet/sunrpc/sched.c
-!Enet/sunrpc/socklib.c
-!Enet/sunrpc/stats.c
-!Enet/sunrpc/rpc_pipe.c
-!Enet/sunrpc/rpcb_clnt.c
-!Enet/sunrpc/clnt.c
- </sect1>
- <sect1><title>WiMAX</title>
-!Enet/wimax/op-msg.c
-!Enet/wimax/op-reset.c
-!Enet/wimax/op-rfkill.c
-!Enet/wimax/stack.c
-!Iinclude/net/wimax.h
-!Iinclude/uapi/linux/wimax.h
- </sect1>
- </chapter>
-
- <chapter id="netdev">
- <title>Network device support</title>
- <sect1><title>Driver Support</title>
-!Enet/core/dev.c
-!Enet/ethernet/eth.c
-!Enet/sched/sch_generic.c
-!Iinclude/linux/etherdevice.h
-!Iinclude/linux/netdevice.h
- </sect1>
- <sect1><title>PHY Support</title>
-!Edrivers/net/phy/phy.c
-!Idrivers/net/phy/phy.c
-!Edrivers/net/phy/phy_device.c
-!Idrivers/net/phy/phy_device.c
-!Edrivers/net/phy/mdio_bus.c
-!Idrivers/net/phy/mdio_bus.c
- </sect1>
-<!-- FIXME: Removed for now since no structured comments in source
- <sect1><title>Wireless</title>
-X!Enet/core/wireless.c
- </sect1>
--->
- </chapter>
-
-</book>
diff --git a/Documentation/conf.py b/Documentation/conf.py
index ad9a4781b330..dfe14f7525d0 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -369,6 +369,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
'The kernel development community', 'manual'),
+ ('networking/index', 'networking.tex', 'Linux Networking Documentation',
+ 'The kernel development community', 'manual'),
('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
'The kernel development community', 'manual'),
('security/index', 'security.tex', 'The kernel security subsystem manual',
diff --git a/Documentation/index.rst b/Documentation/index.rst
index dae365f3820e..25c4da41da6b 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -68,6 +68,7 @@ needed).
driver-api/index
core-api/index
media/index
+ networking/index
input/index
gpu/index
security/index
diff --git a/Documentation/networking/conf.py b/Documentation/networking/conf.py
new file mode 100644
index 000000000000..40f69e67a883
--- /dev/null
+++ b/Documentation/networking/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Networking Documentation"
+
+tags.add("subproject")
+
+latex_documents = [
+ ('index', 'networking.tex', project,
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
new file mode 100644
index 000000000000..ff652ff279e8
--- /dev/null
+++ b/Documentation/networking/index.rst
@@ -0,0 +1,17 @@
+Linux Networking Documentation
+==============================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ kapi
+
+.. only:: subproject
+
+ Indices
+ =======
+
+ * :ref:`genindex`
+
diff --git a/Documentation/networking/kapi.rst b/Documentation/networking/kapi.rst
new file mode 100644
index 000000000000..580289f345da
--- /dev/null
+++ b/Documentation/networking/kapi.rst
@@ -0,0 +1,147 @@
+=========================================
+Linux Networking and Network Devices APIs
+=========================================
+
+Linux Networking
+================
+
+Networking Base Types
+---------------------
+
+.. kernel-doc:: include/linux/net.h
+ :internal:
+
+Socket Buffer Functions
+-----------------------
+
+.. kernel-doc:: include/linux/skbuff.h
+ :internal:
+
+.. kernel-doc:: include/net/sock.h
+ :internal:
+
+.. kernel-doc:: net/socket.c
+ :export:
+
+.. kernel-doc:: net/core/skbuff.c
+ :export:
+
+.. kernel-doc:: net/core/sock.c
+ :export:
+
+.. kernel-doc:: net/core/datagram.c
+ :export:
+
+.. kernel-doc:: net/core/stream.c
+ :export:
+
+Socket Filter
+-------------
+
+.. kernel-doc:: net/core/filter.c
+ :export:
+
+Generic Network Statistics
+--------------------------
+
+.. kernel-doc:: include/uapi/linux/gen_stats.h
+ :internal:
+
+.. kernel-doc:: net/core/gen_stats.c
+ :export:
+
+.. kernel-doc:: net/core/gen_estimator.c
+ :export:
+
+SUN RPC subsystem
+-----------------
+
+.. kernel-doc:: net/sunrpc/xdr.c
+ :export:
+
+.. kernel-doc:: net/sunrpc/svc_xprt.c
+ :export:
+
+.. kernel-doc:: net/sunrpc/xprt.c
+ :export:
+
+.. kernel-doc:: net/sunrpc/sched.c
+ :export:
+
+.. kernel-doc:: net/sunrpc/socklib.c
+ :export:
+
+.. kernel-doc:: net/sunrpc/stats.c
+ :export:
+
+.. kernel-doc:: net/sunrpc/rpc_pipe.c
+ :export:
+
+.. kernel-doc:: net/sunrpc/rpcb_clnt.c
+ :export:
+
+.. kernel-doc:: net/sunrpc/clnt.c
+ :export:
+
+WiMAX
+-----
+
+.. kernel-doc:: net/wimax/op-msg.c
+ :export:
+
+.. kernel-doc:: net/wimax/op-reset.c
+ :export:
+
+.. kernel-doc:: net/wimax/op-rfkill.c
+ :export:
+
+.. kernel-doc:: net/wimax/stack.c
+ :export:
+
+.. kernel-doc:: include/net/wimax.h
+ :internal:
+
+.. kernel-doc:: include/uapi/linux/wimax.h
+ :internal:
+
+Network device support
+======================
+
+Driver Support
+--------------
+
+.. kernel-doc:: net/core/dev.c
+ :export:
+
+.. kernel-doc:: net/ethernet/eth.c
+ :export:
+
+.. kernel-doc:: net/sched/sch_generic.c
+ :export:
+
+.. kernel-doc:: include/linux/etherdevice.h
+ :internal:
+
+.. kernel-doc:: include/linux/netdevice.h
+ :internal:
+
+PHY Support
+-----------
+
+.. kernel-doc:: drivers/net/phy/phy.c
+ :export:
+
+.. kernel-doc:: drivers/net/phy/phy.c
+ :internal:
+
+.. kernel-doc:: drivers/net/phy/phy_device.c
+ :export:
+
+.. kernel-doc:: drivers/net/phy/phy_device.c
+ :internal:
+
+.. kernel-doc:: drivers/net/phy/mdio_bus.c
+ :export:
+
+.. kernel-doc:: drivers/net/phy/mdio_bus.c
+ :internal:
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 30/53] net: fix some identation issues at kernel-doc markups |
| Message-ID | <tHJLZ-5yL-53@gated-at.bofh.it> |
| In reply to | #1642478 |
Sphinx is very pedantic with regards to identation and
escape sequences:
./include/net/sock.h:1967: ERROR: Unexpected indentation.
./include/net/sock.h:1969: ERROR: Unexpected indentation.
./include/net/sock.h:1970: WARNING: Block quote ends without a blank line; unexpected unindent.
./include/net/sock.h:1971: WARNING: Block quote ends without a blank line; unexpected unindent.
./include/net/sock.h:2268: WARNING: Inline emphasis start-string without end-string.
./net/core/sock.c:2686: ERROR: Unexpected indentation.
./net/core/sock.c:2687: WARNING: Block quote ends without a blank line; unexpected unindent.
./net/core/datagram.c:182: WARNING: Inline emphasis start-string without end-string.
./include/linux/netdevice.h:1444: ERROR: Unexpected indentation.
./drivers/net/phy/phy.c:381: ERROR: Unexpected indentation.
./drivers/net/phy/phy.c:382: WARNING: Block quote ends without a blank line; unexpected unindent.
- Fix spacing where needed;
- Properly escape constants;
- Use a literal block for a race description.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/net/phy/phy.c | 1 +
include/linux/netdevice.h | 9 +++++----
include/net/sock.h | 9 ++++-----
net/core/datagram.c | 2 +-
net/core/sock.c | 7 +++++--
5 files changed, 16 insertions(+), 12 deletions(-)
diff --git a/drivers/net/phy/phy.c b/drivers/net/phy/phy.c
index 82ab8fb82587..709b8be53443 100644
--- a/drivers/net/phy/phy.c
+++ b/drivers/net/phy/phy.c
@@ -377,6 +377,7 @@ static void phy_sanitize_settings(struct phy_device *phydev)
* @cmd: ethtool_cmd
*
* A few notes about parameter checking:
+ *
* - We don't set port or transceiver, so we don't care what they
* were set to.
* - phy_start_aneg() will make sure forced settings are sane, and
diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 9c23bd2efb56..56d54b6fac45 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -1433,13 +1433,14 @@ enum netdev_priv_flags {
/**
* struct net_device - The DEVICE structure.
- * Actually, this whole structure is a big mistake. It mixes I/O
- * data with strictly "high-level" data, and it has to know about
- * almost every data structure used in the INET module.
+ *
+ * Actually, this whole structure is a big mistake. It mixes I/O
+ * data with strictly "high-level" data, and it has to know about
+ * almost every data structure used in the INET module.
*
* @name: This is the first field of the "visible" part of this structure
* (i.e. as seen by users in the "Space.c" file). It is the name
- * of the interface.
+ * of the interface.
*
* @name_hlist: Device name hash chain, please keep it close to name[]
* @ifalias: SNMP alias
diff --git a/include/net/sock.h b/include/net/sock.h
index 66349e49d468..9ca99b5c1328 100644
--- a/include/net/sock.h
+++ b/include/net/sock.h
@@ -1953,11 +1953,10 @@ static inline bool sk_has_allocations(const struct sock *sk)
* The purpose of the skwq_has_sleeper and sock_poll_wait is to wrap the memory
* barrier call. They were added due to the race found within the tcp code.
*
- * Consider following tcp code paths:
+ * Consider following tcp code paths::
*
- * CPU1 CPU2
- *
- * sys_select receive packet
+ * CPU1 CPU2
+ * sys_select receive packet
* ... ...
* __add_wait_queue update tp->rcv_nxt
* ... ...
@@ -2264,7 +2263,7 @@ void __sock_tx_timestamp(__u16 tsflags, __u8 *tx_flags);
* @tsflags: timestamping flags to use
* @tx_flags: completed with instructions for time stamping
*
- * Note : callers should take care of initial *tx_flags value (usually 0)
+ * Note: callers should take care of initial ``*tx_flags`` value (usually 0)
*/
static inline void sock_tx_timestamp(const struct sock *sk, __u16 tsflags,
__u8 *tx_flags)
diff --git a/net/core/datagram.c b/net/core/datagram.c
index db1866f2ffcf..4dd594741b6d 100644
--- a/net/core/datagram.c
+++ b/net/core/datagram.c
@@ -181,7 +181,7 @@ static struct sk_buff *skb_set_peeked(struct sk_buff *skb)
*
* This function will lock the socket if a skb is returned, so
* the caller needs to unlock the socket in that case (usually by
- * calling skb_free_datagram). Returns NULL with *err set to
+ * calling skb_free_datagram). Returns NULL with @err set to
* -EAGAIN if no data was available or to some other value if an
* error was detected.
*
diff --git a/net/core/sock.c b/net/core/sock.c
index 79c6aee6af9b..6adc69edfdd6 100644
--- a/net/core/sock.c
+++ b/net/core/sock.c
@@ -2682,9 +2682,12 @@ EXPORT_SYMBOL(release_sock);
* @sk: socket
*
* This version should be used for very small section, where process wont block
- * return false if fast path is taken
+ * return false if fast path is taken:
+ *
* sk_lock.slock locked, owned = 0, BH disabled
- * return true if slow path is taken
+ *
+ * return true if slow path is taken:
+ *
* sk_lock.slock unlocked, owned = 1, BH enabled
*/
bool lock_sock_fast(struct sock *sk)
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | David Howells <dhowells@redhat.com> |
|---|---|
| Date | 2017-05-16 14:40 +0200 |
| Subject | Re: [PATCH v2 30/53] net: fix some identation issues at kernel-doc markups |
| Message-ID | <tHJVE-5BS-21@gated-at.bofh.it> |
| In reply to | #1642516 |
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > - * calling skb_free_datagram). Returns NULL with *err set to > + * calling skb_free_datagram). Returns NULL with @err set to I think this should be *@err or @*err. err is not itself changed. David
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-16 14:30 +0200 |
| Subject | [PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST |
| Message-ID | <tHJM0-5yL-67@gated-at.bofh.it> |
| In reply to | #1642478 |
There are a few issues on some kernel-doc markups that was
causing troubles with kernel-doc output on ReST format:
./kernel/futex.c:492: WARNING: Inline emphasis start-string without end-string.
./kernel/futex.c:1264: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:1721: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2338: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2426: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2899: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2972: WARNING: Block quote ends without a blank line; unexpected unindent.
Fix them.
No functional changes.
Acked-by: Darren Hart (VMware) <dvhart@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/linux/mutex.h | 6 +++---
kernel/futex.c | 40 ++++++++++++++++++++--------------------
kernel/locking/mutex.c | 6 +++---
3 files changed, 26 insertions(+), 26 deletions(-)
diff --git a/include/linux/mutex.h b/include/linux/mutex.h
index 1127fe31645d..ffcba1f337da 100644
--- a/include/linux/mutex.h
+++ b/include/linux/mutex.h
@@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum {
* raisins, and once those are gone this will be removed.
*
* Returns:
- * MUTEX_TRYLOCK_FAILED - trylock failed,
- * MUTEX_TRYLOCK_SUCCESS - lock acquired,
- * MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
+ * - MUTEX_TRYLOCK_FAILED - trylock failed,
+ * - MUTEX_TRYLOCK_SUCCESS - lock acquired,
+ * - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
*/
static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
mutex_trylock_recursive(struct mutex *lock)
diff --git a/kernel/futex.c b/kernel/futex.c
index 357348a6cf6b..b8ae87d227da 100644
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -488,7 +488,7 @@ static void drop_futex_key_refs(union futex_key *key)
*
* Return: a negative error code or 0
*
- * The key words are stored in *key on success.
+ * The key words are stored in @key on success.
*
* For shared mappings, it's (page->index, file_inode(vma->vm_file),
* offset_within_page). For private mappings, it's (uaddr, current->mm).
@@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
* @set_waiters: force setting the FUTEX_WAITERS bit (1) or not (0)
*
* Return:
- * 0 - ready to wait;
- * 1 - acquired the lock;
- * <0 - error
+ * - 0 - ready to wait;
+ * - 1 - acquired the lock;
+ * - <0 - error
*
* The hb->lock and futex_key refs shall be held by the caller.
*/
@@ -1717,9 +1717,9 @@ void requeue_pi_wake_futex(struct futex_q *q, union futex_key *key,
* hb1 and hb2 must be held by the caller.
*
* Return:
- * 0 - failed to acquire the lock atomically;
- * >0 - acquired the lock, return value is vpid of the top_waiter
- * <0 - error
+ * - 0 - failed to acquire the lock atomically;
+ * - >0 - acquired the lock, return value is vpid of the top_waiter
+ * - <0 - error
*/
static int futex_proxy_trylock_atomic(u32 __user *pifutex,
struct futex_hash_bucket *hb1,
@@ -1785,8 +1785,8 @@ static int futex_proxy_trylock_atomic(u32 __user *pifutex,
* uaddr2 atomically on behalf of the top waiter.
*
* Return:
- * >=0 - on success, the number of tasks requeued or woken;
- * <0 - on error
+ * - >=0 - on success, the number of tasks requeued or woken;
+ * - <0 - on error
*/
static int futex_requeue(u32 __user *uaddr1, unsigned int flags,
u32 __user *uaddr2, int nr_wake, int nr_requeue,
@@ -2142,8 +2142,8 @@ static inline void queue_me(struct futex_q *q, struct futex_hash_bucket *hb)
* be paired with exactly one earlier call to queue_me().
*
* Return:
- * 1 - if the futex_q was still queued (and we removed unqueued it);
- * 0 - if the futex_q was already removed by the waking thread
+ * - 1 - if the futex_q was still queued (and we removed unqueued it);
+ * - 0 - if the futex_q was already removed by the waking thread
*/
static int unqueue_me(struct futex_q *q)
{
@@ -2333,9 +2333,9 @@ static long futex_wait_restart(struct restart_block *restart);
* acquire the lock. Must be called with the hb lock held.
*
* Return:
- * 1 - success, lock taken;
- * 0 - success, lock not taken;
- * <0 - on error (-EFAULT)
+ * - 1 - success, lock taken;
+ * - 0 - success, lock not taken;
+ * - <0 - on error (-EFAULT)
*/
static int fixup_owner(u32 __user *uaddr, struct futex_q *q, int locked)
{
@@ -2422,8 +2422,8 @@ static void futex_wait_queue_me(struct futex_hash_bucket *hb, struct futex_q *q,
* with no q.key reference on failure.
*
* Return:
- * 0 - uaddr contains val and hb has been locked;
- * <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
+ * - 0 - uaddr contains val and hb has been locked;
+ * - <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
*/
static int futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags,
struct futex_q *q, struct futex_hash_bucket **hb)
@@ -2895,8 +2895,8 @@ static int futex_unlock_pi(u32 __user *uaddr, unsigned int flags)
* called with the hb lock held.
*
* Return:
- * 0 = no early wakeup detected;
- * <0 = -ETIMEDOUT or -ERESTARTNOINTR
+ * - 0 = no early wakeup detected;
+ * - <0 = -ETIMEDOUT or -ERESTARTNOINTR
*/
static inline
int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
@@ -2968,8 +2968,8 @@ int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
* If 4 or 7, we cleanup and return with -ETIMEDOUT.
*
* Return:
- * 0 - On success;
- * <0 - On error
+ * - 0 - On success;
+ * - <0 - On error
*/
static int futex_wait_requeue_pi(u32 __user *uaddr, unsigned int flags,
u32 val, ktime_t *abs_time, u32 bitset,
diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
index 198527a62149..858a07590e39 100644
--- a/kernel/locking/mutex.c
+++ b/kernel/locking/mutex.c
@@ -227,9 +227,9 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
* (or statically defined) before it can be locked. memset()-ing
* the mutex to 0 is not allowed.
*
- * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
- * checks that will enforce the restrictions and will also do
- * deadlock debugging. )
+ * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging
+ * checks that will enforce the restrictions and will also do
+ * deadlock debugging)
*
* This function is similar to (but not equivalent to) down().
*/
--
2.9.3
[toc] | [prev] | [next] | [standalone]
| From | Darren Hart <dvhart@infradead.org> |
|---|---|
| Date | 2017-05-16 19:40 +0200 |
| Subject | Re: [PATCH v2 04/53] mutex, futex: adjust kernel-doc markups to generate ReST |
| Message-ID | <tHOBY-6g-13@gated-at.bofh.it> |
| In reply to | #1642517 |
On Tue, May 16, 2017 at 09:15:56AM -0300, Mauro Carvalho Chehab wrote:
> There are a few issues on some kernel-doc markups that was
> causing troubles with kernel-doc output on ReST format:
>
> ./kernel/futex.c:492: WARNING: Inline emphasis start-string without end-string.
> ./kernel/futex.c:1264: WARNING: Block quote ends without a blank line; unexpected unindent.
> ./kernel/futex.c:1721: WARNING: Block quote ends without a blank line; unexpected unindent.
> ./kernel/futex.c:2338: WARNING: Block quote ends without a blank line; unexpected unindent.
> ./kernel/futex.c:2426: WARNING: Block quote ends without a blank line; unexpected unindent.
> ./kernel/futex.c:2899: WARNING: Block quote ends without a blank line; unexpected unindent.
> ./kernel/futex.c:2972: WARNING: Block quote ends without a blank line; unexpected unindent.
>
> Fix them.
>
> No functional changes.
>
> Acked-by: Darren Hart (VMware) <dvhart@infradead.org>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
What was the difference from v1? Quick scan didn't reveal anything obvious to
me... (context left intact in case you want to point it out inline), but just a
"Changes since v1" below the --- is always appreciated - even it it's "no
changes, new commit log".
> include/linux/mutex.h | 6 +++---
> kernel/futex.c | 40 ++++++++++++++++++++--------------------
> kernel/locking/mutex.c | 6 +++---
> 3 files changed, 26 insertions(+), 26 deletions(-)
>
> diff --git a/include/linux/mutex.h b/include/linux/mutex.h
> index 1127fe31645d..ffcba1f337da 100644
> --- a/include/linux/mutex.h
> +++ b/include/linux/mutex.h
> @@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum {
> * raisins, and once those are gone this will be removed.
> *
> * Returns:
> - * MUTEX_TRYLOCK_FAILED - trylock failed,
> - * MUTEX_TRYLOCK_SUCCESS - lock acquired,
> - * MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
> + * - MUTEX_TRYLOCK_FAILED - trylock failed,
> + * - MUTEX_TRYLOCK_SUCCESS - lock acquired,
> + * - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
> */
> static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
> mutex_trylock_recursive(struct mutex *lock)
> diff --git a/kernel/futex.c b/kernel/futex.c
> index 357348a6cf6b..b8ae87d227da 100644
> --- a/kernel/futex.c
> +++ b/kernel/futex.c
> @@ -488,7 +488,7 @@ static void drop_futex_key_refs(union futex_key *key)
> *
> * Return: a negative error code or 0
> *
> - * The key words are stored in *key on success.
> + * The key words are stored in @key on success.
> *
> * For shared mappings, it's (page->index, file_inode(vma->vm_file),
> * offset_within_page). For private mappings, it's (uaddr, current->mm).
> @@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval)
> * @set_waiters: force setting the FUTEX_WAITERS bit (1) or not (0)
> *
> * Return:
> - * 0 - ready to wait;
> - * 1 - acquired the lock;
> - * <0 - error
> + * - 0 - ready to wait;
> + * - 1 - acquired the lock;
> + * - <0 - error
> *
> * The hb->lock and futex_key refs shall be held by the caller.
> */
> @@ -1717,9 +1717,9 @@ void requeue_pi_wake_futex(struct futex_q *q, union futex_key *key,
> * hb1 and hb2 must be held by the caller.
> *
> * Return:
> - * 0 - failed to acquire the lock atomically;
> - * >0 - acquired the lock, return value is vpid of the top_waiter
> - * <0 - error
> + * - 0 - failed to acquire the lock atomically;
> + * - >0 - acquired the lock, return value is vpid of the top_waiter
> + * - <0 - error
> */
> static int futex_proxy_trylock_atomic(u32 __user *pifutex,
> struct futex_hash_bucket *hb1,
> @@ -1785,8 +1785,8 @@ static int futex_proxy_trylock_atomic(u32 __user *pifutex,
> * uaddr2 atomically on behalf of the top waiter.
> *
> * Return:
> - * >=0 - on success, the number of tasks requeued or woken;
> - * <0 - on error
> + * - >=0 - on success, the number of tasks requeued or woken;
> + * - <0 - on error
> */
> static int futex_requeue(u32 __user *uaddr1, unsigned int flags,
> u32 __user *uaddr2, int nr_wake, int nr_requeue,
> @@ -2142,8 +2142,8 @@ static inline void queue_me(struct futex_q *q, struct futex_hash_bucket *hb)
> * be paired with exactly one earlier call to queue_me().
> *
> * Return:
> - * 1 - if the futex_q was still queued (and we removed unqueued it);
> - * 0 - if the futex_q was already removed by the waking thread
> + * - 1 - if the futex_q was still queued (and we removed unqueued it);
> + * - 0 - if the futex_q was already removed by the waking thread
> */
> static int unqueue_me(struct futex_q *q)
> {
> @@ -2333,9 +2333,9 @@ static long futex_wait_restart(struct restart_block *restart);
> * acquire the lock. Must be called with the hb lock held.
> *
> * Return:
> - * 1 - success, lock taken;
> - * 0 - success, lock not taken;
> - * <0 - on error (-EFAULT)
> + * - 1 - success, lock taken;
> + * - 0 - success, lock not taken;
> + * - <0 - on error (-EFAULT)
> */
> static int fixup_owner(u32 __user *uaddr, struct futex_q *q, int locked)
> {
> @@ -2422,8 +2422,8 @@ static void futex_wait_queue_me(struct futex_hash_bucket *hb, struct futex_q *q,
> * with no q.key reference on failure.
> *
> * Return:
> - * 0 - uaddr contains val and hb has been locked;
> - * <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
> + * - 0 - uaddr contains val and hb has been locked;
> + * - <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked
> */
> static int futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags,
> struct futex_q *q, struct futex_hash_bucket **hb)
> @@ -2895,8 +2895,8 @@ static int futex_unlock_pi(u32 __user *uaddr, unsigned int flags)
> * called with the hb lock held.
> *
> * Return:
> - * 0 = no early wakeup detected;
> - * <0 = -ETIMEDOUT or -ERESTARTNOINTR
> + * - 0 = no early wakeup detected;
> + * - <0 = -ETIMEDOUT or -ERESTARTNOINTR
> */
> static inline
> int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
> @@ -2968,8 +2968,8 @@ int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
> * If 4 or 7, we cleanup and return with -ETIMEDOUT.
> *
> * Return:
> - * 0 - On success;
> - * <0 - On error
> + * - 0 - On success;
> + * - <0 - On error
> */
> static int futex_wait_requeue_pi(u32 __user *uaddr, unsigned int flags,
> u32 val, ktime_t *abs_time, u32 bitset,
> diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
> index 198527a62149..858a07590e39 100644
> --- a/kernel/locking/mutex.c
> +++ b/kernel/locking/mutex.c
> @@ -227,9 +227,9 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock);
> * (or statically defined) before it can be locked. memset()-ing
> * the mutex to 0 is not allowed.
> *
> - * ( The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> - * checks that will enforce the restrictions and will also do
> - * deadlock debugging. )
> + * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging
> + * checks that will enforce the restrictions and will also do
> + * deadlock debugging)
> *
> * This function is similar to (but not equivalent to) down().
> */
> --
> 2.9.3
>
>
--
Darren Hart
VMware Open Source Technology Center
[toc] | [prev] | [next] | [standalone]
Page 2 of 3 — ← Prev page 1 [2] 3 Next page →
Back to top | Article view | linux.kernel
csiph-web