APPLY FOR YOUR URGENT LOAN AT 2%
* Do you need an urgent loan? We offer all kinds of loan * Very fast and urgent transfer to your bank account. * Payment begins (6) months after you get the money in your bank account * Low interest rates 2% * Payment of long-term (1-30 years) duration For more information and loan application form through the Contact now E-mail: thomascreditf...@gmail.com Thomas B. Dawson THOMAS CREDIT FIRM --- This email has been checked for viruses by Avast antivirus software. https://www.avast.com/antivirus -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 30/36] net: skbuff.h: properly escape a macro name on kernel-doc
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 --- 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 05/36] locking.rst: reformat locking table
Use a different markup for this table, in order to make it smaller when seeing in text mode. Signed-off-by: Mauro Carvalho Chehab --- 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 +=
[PATCH 08/36] docs-rst: convert kgdb DocBook to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile| 2 +- Documentation/DocBook/kgdb.tmpl | 918 - Documentation/dev-tools/index.rst | 1 + Documentation/dev-tools/kgdb.rst | 930 ++ 4 files changed, 932 insertions(+), 919 deletions(-) delete mode 100644 Documentation/DocBook/kgdb.tmpl create mode 100644 Documentation/dev-tools/kgdb.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 9df94f7c2003..b9d2b88b9905 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,7 +8,7 @@ DOCBOOKS := z8530book.xml \ networking.xml \ - filesystems.xml lsm.xml kgdb.xml \ + filesystems.xml lsm.xml \ libata.xml mtdnand.xml librs.xml rapidio.xml \ s390-drivers.xml scsi.xml \ sh.xml w1.xml diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl deleted file mode 100644 index 856ac20bf367.. --- a/Documentation/DocBook/kgdb.tmpl +++ /dev/null @@ -1,918 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - - Using kgdb, kdb and the kernel debugger internals - - - -Jason -Wessel - - - jason.wes...@windriver.com - - - - - - 2008,2010 - Wind River Systems, Inc. - - - 2004-2005 - MontaVista Software, Inc. - - - 2004 - Amit S. Kale - - - - - This file is licensed under the terms of the GNU General Public License - version 2. This program is licensed "as is" without any warranty of any - kind, whether express or implied. - - - - - - - -Introduction - -The kernel has two different debugger front ends (kdb and kgdb) -which interface to the debug core. It is possible to use either -of the debugger front ends and dynamically transition between them -if you configure the kernel properly at compile and runtime. - - -Kdb is simplistic shell-style interface which you can use on a -system console with a keyboard or serial console. You can use it -to inspect memory, registers, process lists, dmesg, and even set -breakpoints to stop in a certain location. Kdb is not a source -level debugger, although you can set breakpoints and execute some -basic kernel run control. Kdb is mainly aimed at doing some -analysis to aid in development or diagnosing kernel problems. You -can access some symbols by name in kernel built-ins or in kernel -modules if the code was built -with CONFIG_KALLSYMS. - - -Kgdb is intended to be used as a source level debugger for the -Linux kernel. It is used along with gdb to debug a Linux kernel. -The expectation is that gdb can be used to "break in" to the -kernel to inspect memory, variables and look through call stack -information similar to the way an application developer would use -gdb to debug an application. It is possible to place breakpoints -in kernel code and perform some limited execution stepping. - - -Two machines are required for using kgdb. One of these machines is -a development machine and the other is the target machine. The -kernel to be debugged runs on the target machine. The development -machine runs an instance of gdb against the vmlinux file which -contains the symbols (not a boot image such as bzImage, zImage, -uImage...). In gdb the developer specifies the connection -parameters and connects to kgdb. The type of connection a -developer makes with gdb depends on the availability of kgdb I/O -modules compiled as built-ins or loadable kernel modules in the test -machine's kernel. - - - - Compiling a kernel - - - In order to enable compilation of kdb, you must first enable kgdb. - The kgdb test compile options are described in the kgdb test suite chapter. - - - -Kernel config options for kgdb - -To enable CONFIG_KGDB you should look under -"Kernel hacking" / "Kernel debugging" and select "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. - - -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 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 tr
[PATCH 17/36] docs-rst: convert filesystems book to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/filesystems.tmpl | 381 - Documentation/conf.py | 2 + Documentation/filesystems/conf.py | 10 + Documentation/filesystems/index.rst| 314 +++ Documentation/index.rst| 1 + 6 files changed, 328 insertions(+), 382 deletions(-) delete mode 100644 Documentation/DocBook/filesystems.tmpl create mode 100644 Documentation/filesystems/conf.py create mode 100644 Documentation/filesystems/index.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b9d2b88b9905..2f767e30b59e 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,7 +8,7 @@ DOCBOOKS := z8530book.xml \ networking.xml \ - filesystems.xml lsm.xml \ + lsm.xml \ libata.xml mtdnand.xml librs.xml rapidio.xml \ s390-drivers.xml scsi.xml \ sh.xml w1.xml diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl deleted file mode 100644 index 6006b6358c86.. --- a/Documentation/DocBook/filesystems.tmpl +++ /dev/null @@ -1,381 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - - Linux Filesystems API - - - - 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. - - - - 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. - - - - 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 - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - The Linux VFS - The Filesystem types -!Iinclude/linux/fs.h - - The Directory Cache -!Efs/dcache.c -!Iinclude/linux/dcache.h - - Inode Handling -!Efs/inode.c -!Efs/bad_inode.c - - Registration and Superblocks -!Efs/super.c - - File Locks -!Efs/locks.c -!Ifs/locks.c - - Other Functions -!Efs/mpage.c -!Efs/namei.c -!Efs/buffer.c -!Eblock/bio.c -!Efs/seq_file.c -!Efs/filesystems.c -!Efs/fs-writeback.c -!Efs/block_dev.c - - - - - The proc filesystem - - sysctl interface -!Ekernel/sysctl.c - - - proc filesystem interface -!Ifs/proc/base.c - - - - - Events based on file descriptors -!Efs/eventfd.c - - - - The Filesystem for Exporting Kernel Objects -!Efs/sysfs/file.c -!Efs/sysfs/symlink.c - - - - The debugfs filesystem - - debugfs interface -!Efs/debugfs/inode.c -!Efs/debugfs/file.c - - - - - - The Linux Journalling API - - - - Roger - Gammans - - - rgamm...@computer-surgery.co.uk - - - - - - - -Stephen -Tweedie - - - s...@redhat.com - - - - - - - 2002 - Roger Gammans - - - - The Linux Journalling API - - - Overview - - Details - -The journalling layer is easy to use. You need to -first of all create a journal_t data structure. There are -two calls to do this dependent on how you decide to allocate the physical -media on which the journal resides. The jbd2_journal_init_inode() call -is for journals stored in filesystem inodes, or the jbd2_journal_init_dev() -call can be used for journal stored on a raw device (in a continuous range -of blocks). A journal_t is a typedef for a struct pointer, so when -you are finally finished make sure you call jbd2_journal_destroy() on it -to free up any used kernel memory. - - - -Once you have got your journal_t object you need to 'mount' or load the journal -file. The journalling layer expects the space for the journal was already -allocated and initialized properly by the userspace tools. When loading the -journal you must call jbd2_journal_load() to process journal contents. If the -client file system detects the journal contents does not need to be processed -(or even need not have valid contents), it may call jbd2_journal_wipe() to -clear the journal contents before calling jbd2_journal_load(). - - - -Note that jbd2_journal_wipe(..,0) calls jbd2_journal_skip_recovery() for you if -it detects any outstanding transactions in the journal and similarly -jbd2_journal_load() will call jbd2_jou
[PATCH 12/36] docs-rst: conf.py: remove kernel-documentation from LaTeX
There's no kernel-documentation.rst file at Documentation/
anymore. So, remove it from the list of LaTeX-generated
documents.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/conf.py | 2 --
1 file changed, 2 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1a76daec7f9c..15f34d6863a7 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -359,8 +359,6 @@ latex_documents = [
'The kernel development community', 'manual'),
('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
'The kernel development community', 'manual'),
-('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel
Documentation',
- 'The kernel development community', 'manual'),
('kernel-hacking/index', 'kernel-hacking.tex', 'Unreliable Guide To
Hacking The Linux Kernel',
'The kernel development community', 'manual'),
('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST
There are a few issues on some kernel-doc markups that was
causing troubles with kernel-doc output on ReST format.
Fix them.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab
---
include/linux/mutex.h | 6 +++---
kernel/futex.c | 40
kernel/locking/mutex.c | 6 --
3 files changed, 27 insertions(+), 25 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
fu
[PATCH 18/36] docs-rst: filesystems: use c domain references where needed
Instead of just mention the function names, use cross-references
to the kernel-doc tags where pertinent.
While not all function documentation is included here, I
double-checked that all functions mentioned there still
exists.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/filesystems/index.rst | 76 +++--
1 file changed, 40 insertions(+), 36 deletions(-)
diff --git a/Documentation/filesystems/index.rst
b/Documentation/filesystems/index.rst
index 3bc82e9d22f0..148becd91cba 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -125,27 +125,27 @@ Details
The journalling layer is easy to use. You need to first of all create a
journal_t data structure. There are two calls to do this dependent on
how you decide to allocate the physical media on which the journal
-resides. The jbd2_journal_init_inode() call is for journals stored in
-filesystem inodes, or the jbd2_journal_init_dev() call can be used
+resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in
+filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used
for journal stored on a raw device (in a continuous range of blocks). A
journal_t is a typedef for a struct pointer, so when you are finally
-finished make sure you call jbd2_journal_destroy() on it to free up
+finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up
any used kernel memory.
Once you have got your journal_t object you need to 'mount' or load the
journal file. The journalling layer expects the space for the journal
was already allocated and initialized properly by the userspace tools.
-When loading the journal you must call jbd2_journal_load() to process
+When loading the journal you must call :c:func:`jbd2_journal_load` to process
journal contents. If the client file system detects the journal contents
does not need to be processed (or even need not have valid contents), it
-may call jbd2_journal_wipe() to clear the journal contents before
-calling jbd2_journal_load().
+may call :c:func:`jbd2_journal_wipe` to clear the journal contents before
+calling :c:func:`jbd2_journal_load`.
Note that jbd2_journal_wipe(..,0) calls
-jbd2_journal_skip_recovery() for you if it detects any outstanding
-transactions in the journal and similarly jbd2_journal_load() will
-call jbd2_journal_recover() if necessary. I would advise reading
-ext4_load_journal() in fs/ext4/super.c for examples on this stage.
+:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
+transactions in the journal and similarly :c:func:`jbd2_journal_load` will
+call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
+:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
Now you can go ahead and start modifying the underlying filesystem.
Almost.
@@ -154,54 +154,57 @@ You still need to actually journal your filesystem
changes, this is done
by wrapping them into transactions. Additionally you also need to wrap
the modification of each of the buffers with calls to the journal layer,
so it knows what the modifications you are actually making are. To do
-this use jbd2_journal_start() which returns a transaction handle.
+this use :c:func:`jbd2_journal_start` which returns a transaction handle.
-jbd2_journal_start() and its counterpart jbd2_journal_stop(), which
-indicates the end of a transaction are nestable calls, so you can
+:c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`,
+which indicates the end of a transaction are nestable calls, so you can
reenter a transaction if necessary, but remember you must call
-jbd2_journal_stop() the same number of times as jbd2_journal_start()
-before the transaction is completed (or more accurately leaves the
-update phase). Ext4/VFS makes use of this feature to simplify handling
-of inode dirtying, quota support, etc.
+:c:func:`jbd2_journal_stop` the same number of times as
+:c:func:`jbd2_journal_start` before the transaction is completed (or more
+accurately leaves the update phase). Ext4/VFS makes use of this feature to
+simplify handling of inode dirtying, quota support, etc.
Inside each transaction you need to wrap the modifications to the
individual buffers (blocks). Before you start to modify a buffer you
-need to call jbd2_journal_get_{create,write,undo}_access() as
-appropriate, this allows the journalling layer to copy the unmodified
+need to call :c:func:`jbd2_journal_get_create_access()` /
+:c:func:`jbd2_journal_get_write_access()` /
+:c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the
+journalling layer to copy the unmodified
data if it needs to. After all the buffer may be part of a previously
uncommitted transaction. At this point you are at last ready to modify a
buffer, and once you are have done so you need to call
-jbd2_journal_dirty_{meta,}data(). Or if you've asked for access to a
+:c:func:`jbd2_journal_di
[PATCH 01/36] docs-rst: convert kernel-hacking to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. - Manually adjusted to use ..note and ..warning - Minor fixes for it to be parsed without errors - Use **bold** for emphasis. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile|2 +- Documentation/DocBook/kernel-hacking.tmpl | 1312 - Documentation/conf.py |2 + Documentation/index.rst |1 + Documentation/kernel-hacking/conf.py | 10 + Documentation/kernel-hacking/index.rst| 794 + 6 files changed, 808 insertions(+), 1313 deletions(-) delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl create mode 100644 Documentation/kernel-hacking/conf.py create mode 100644 Documentation/kernel-hacking/index.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 85916f13d330..7d7482b5ad92 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -7,7 +7,7 @@ # list of DOCBOOKS. DOCBOOKS := z8530book.xml \ - kernel-hacking.xml kernel-locking.xml \ + kernel-locking.xml \ networking.xml \ filesystems.xml lsm.xml kgdb.xml \ libata.xml mtdnand.xml librs.xml rapidio.xml \ diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl deleted file mode 100644 index da5c087462b1.. --- a/Documentation/DocBook/kernel-hacking.tmpl +++ /dev/null @@ -1,1312 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - - Unreliable Guide To Hacking The Linux Kernel - - - -Rusty -Russell - - - ru...@rustcorp.com.au - - - - - - - 2005 - Rusty Russell - - - - -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. - - - -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. - - - -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 - - - -For more details see the file COPYING in the source -distribution of Linux. - - - - - This is the first release of this document as part of the kernel tarball. - - - - - - - - Introduction - - Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux - Kernel Hacking. This document describes the common routines and - general requirements for kernel code: its goal is to serve as a - primer for Linux kernel development for experienced C - programmers. I avoid implementation details: that's what the - code is for, and I ignore whole tracts of useful routines. - - - Before you read this, please understand that I never wanted to - write this document, being grossly under-qualified, but I always - wanted to read it, and this was the only way. I hope it will - grow into a compendium of best practice, common starting points - and random information. - - - - - The Players - - - At any time each of the CPUs in a system can be: - - - - - - not associated with any process, serving a hardware interrupt; - - - - - - not associated with any process, serving a softirq or tasklet; - - - - - - running in kernel space, associated with a process (user context); - - - - - - running a process in user space. - - - - - - There is an ordering between these. The bottom two can preempt - each other, but above that is a strict hierarchy: each can only be - preempted by the ones above it. For example, while a softirq is - running on a CPU, no other softirq will preempt it, but a hardware - interrupt can. However, any other CPUs in the system execute - independently. - - - - We'll see a number of ways that the user context can block - interrupts, to become truly non-preemptable. - - - - User Context - - -User context is when you are coming in from a system call or other -trap: like userspace, you can be preempted by more important tasks -and by interrupts. You can sleep, by calling -schedule(). - - - - - You are always in user context on module load and unload, - and on operations on the block device layer. - - - - -In user context, the current pointer (indicating -the task we are currently executing) is valid, and -
Re: [PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments
On Fri, 2017-05-12 at 11:00 -0300, Mauro Carvalho Chehab wrote: > There are a few syntax violations that cause outputs of > a few comments to not be properly parsed in ReST format. > > No functional changes. > > Signed-off-by: Mauro Carvalho Chehab > --- > fs/locks.c | 18 -- > 1 file changed, 8 insertions(+), 10 deletions(-) > > diff --git a/fs/locks.c b/fs/locks.c > index 26811321d39b..bdce708e4251 100644 > --- a/fs/locks.c > +++ b/fs/locks.c > @@ -1858,8 +1858,8 @@ EXPORT_SYMBOL(generic_setlease); > * > * Call this to establish a lease on the file. The "lease" argument is not > * used for F_UNLCK requests and may be NULL. For commands that set or alter > - * an existing lease, the (*lease)->fl_lmops->lm_break operation must be set; > - * if not, this function will return -ENOLCK (and generate a scary-looking > + * an existing lease, the ``(*lease)->fl_lmops->lm_break`` operation must be > + * set; if not, this function will return -ENOLCK (and generate a > scary-looking > * stack trace). > * > * The "priv" pointer is passed directly to the lm_setup function as-is. It > @@ -1972,15 +1972,13 @@ EXPORT_SYMBOL(locks_lock_inode_wait); > * @cmd: the type of lock to apply. > * > * Apply a %FL_FLOCK style lock to an open file descriptor. > - * The @cmd can be one of > + * The @cmd can be one of: > * > - * %LOCK_SH -- a shared lock. > - * > - * %LOCK_EX -- an exclusive lock. > - * > - * %LOCK_UN -- remove an existing lock. > - * > - * %LOCK_MAND -- a `mandatory' flock. This exists to emulate Windows > Share Modes. > + * - %LOCK_SH -- a shared lock. > + * - %LOCK_EX -- an exclusive lock. > + * - %LOCK_UN -- remove an existing lock. > + * - %LOCK_MAND -- a 'mandatory' flock. > + * This exists to emulate Windows Share Modes. > * > * %LOCK_MAND can be combined with %LOCK_READ or %LOCK_WRITE to allow other > * processes read and write access respectively. LGTM. Do you need me or Bruce to pick this one up? Reviewed-by: Jeff Layton -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 36/36] docs-rst: convert rapidio book to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile | 4 +- Documentation/DocBook/rapidio.tmpl | 155 --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/rapidio.rst | 107 4 files changed, 110 insertions(+), 157 deletions(-) delete mode 100644 Documentation/DocBook/rapidio.tmpl create mode 100644 Documentation/driver-api/rapidio.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 3bbda02d6aee..baedb14f3b40 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,8 +8,8 @@ DOCBOOKS := \ lsm.xml \ - mtdnand.xml librs.xml rapidio.xml \ - sh.xml w1.xml + mtdnand.xml librs.xml \ + sh.xml ifeq ($(DOCBOOKS),) diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl deleted file mode 100644 index ac3cca3399a1.. --- a/Documentation/DocBook/rapidio.tmpl +++ /dev/null @@ -1,155 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [ - - ]> - - - - RapidIO Subsystem Guide - - - -Matt -Porter - - - mpor...@kernel.crashing.org - mpor...@mvista.com - - - - - - - 2005 - MontaVista Software, Inc. - - - - - 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. - - - - 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. - - - - 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 - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - - RapidIO is a high speed switched fabric interconnect with - features aimed at the embedded market. RapidIO provides - support for memory-mapped I/O as well as message-based - transactions over the switched fabric network. RapidIO has - a standardized discovery mechanism not unlike the PCI bus - standard that allows simple detection of devices in a - network. - - - This documentation is provided for developers intending - to support RapidIO on new architectures, write new drivers, - or to understand the subsystem internals. - - - - - Known Bugs and Limitations - - - Bugs - None. ;) - - - Limitations - - - Access/management of RapidIO memory regions is not supported - Multiple host enumeration is not supported - - - - - - - RapidIO driver interface - - Drivers are provided a set of calls in order - to interface with the subsystem to gather info - on devices, request/map memory region resources, - and manage mailboxes/doorbells. - - - Functions -!Iinclude/linux/rio_drv.h -!Edrivers/rapidio/rio-driver.c -!Edrivers/rapidio/rio.c - - - - - Internals - - - This chapter contains the autogenerated documentation of the RapidIO - subsystem. - - - Structures -!Iinclude/linux/rio.h - - Enumeration and Discovery -!Idrivers/rapidio/rio-scan.c - - Driver functionality -!Idrivers/rapidio/rio.c -!Idrivers/rapidio/rio-access.c - - Device model support -!Idrivers/rapidio/rio-driver.c - - PPC32 support -!Iarch/powerpc/sysdev/fsl_rio.c - - - - - Credits - - The following people have contributed to the RapidIO - subsystem directly or indirectly: - - Matt Portermpor...@kernel.crashing.org - Randy Vinsonrvin...@mvista.com - Dan Malekd...@embeddedalley.com - - - - The following people have contributed to this document: - - Matt Portermpor...@kernel.crashing.org - - - - diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 8610aab8f342..1f8517db39c7 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -36,6 +36,7 @@ available subsections can be seen below. libata miscellaneous w1 + rapidi
[PATCH 14/36] docs-rst: add dev-tools book to pdf output
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
---
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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 25/36] docs-rst: convert libata book to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile |2 +- Documentation/DocBook/libata.tmpl | 1625 --- Documentation/driver-api/index.rst |1 + Documentation/driver-api/libata.rst | 1027 ++ 4 files changed, 1029 insertions(+), 1626 deletions(-) delete mode 100644 Documentation/DocBook/libata.tmpl create mode 100644 Documentation/driver-api/libata.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 2f767e30b59e..abe71345160b 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -9,7 +9,7 @@ DOCBOOKS := z8530book.xml \ networking.xml \ lsm.xml \ - libata.xml mtdnand.xml librs.xml rapidio.xml \ + mtdnand.xml librs.xml rapidio.xml \ s390-drivers.xml scsi.xml \ sh.xml w1.xml diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl deleted file mode 100644 index 0320910b866d.. --- a/Documentation/DocBook/libata.tmpl +++ /dev/null @@ -1,1625 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - - libATA Developer's Guide - - - -Jeff -Garzik - - - - - 2003-2006 - Jeff Garzik - - - - - The contents of this file are subject to the Open - Software License version 1.1 that can be found at - http://fedoraproject.org/wiki/Licensing:OSL1.1";>http://fedoraproject.org/wiki/Licensing:OSL1.1 - and is included herein by reference. - - - - Alternatively, the contents of this file may be used under the terms - of the GNU General Public License version 2 (the "GPL") as distributed - in the kernel source COPYING file, in which case the provisions of - the GPL are applicable instead of the above. If you wish to allow - the use of your version of this file only under the terms of the - GPL and not to allow others to use your version of this file under - the OSL, indicate your decision by deleting the provisions above and - replace them with the notice and other provisions required by the GPL. - If you do not delete the provisions above, a recipient may use your - version of this file under either the OSL or the GPL. - - - - - - - - - Introduction - - libATA is a library used inside the Linux kernel to support ATA host - controllers and devices. libATA provides an ATA driver API, class - transports for ATA and ATAPI devices, and SCSI<->ATA translation - for ATA devices according to the T10 SAT specification. - - - This Guide documents the libATA driver API, library functions, library - internals, and a couple sample ATA low-level drivers. - - - - - libata Driver API - - struct 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 - 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 - - Disable ATA port - -void (*port_disable) (struct ata_port *); - - - - Called from 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. - - - Called from ata_bus_probe() on a failed probe. - Called from ata_scsi_release(). - - - - - Post-IDENTIFY device configuration - -void (*dev_config) (struct ata_port *, struct ata_device *); - - - - Called after IDENTIFY [PACKET] DEVICE is issued to each device - found. Typically used to apply device-specific fixups prior to - issue of SET FEATURES - XFER MODE, and prior to operation. - - - This entry may be specified as NULL in ata_port_operations. - - - - - Set PIO/DMA mode - -void (*set_piomode) (struct ata_port *, struct ata_device *); -void (*set_dmamode) (struct ata_port *, struct ata_device *); -void (*post_set_mode) (struct ata_port *); -unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); - - - - 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 which should return a m
[PATCH 02/36] kernel-hacking: update document
This document is fairly updated. Yet, some stuff moved to
other kernel headers. So, update to point to the right
places.
While here, adjust some minor ReST markups.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/kernel-hacking/index.rst | 179 ++---
1 file changed, 98 insertions(+), 81 deletions(-)
diff --git a/Documentation/kernel-hacking/index.rst
b/Documentation/kernel-hacking/index.rst
index 75597e627791..1a456b60a7cf 100644
--- a/Documentation/kernel-hacking/index.rst
+++ b/Documentation/kernel-hacking/index.rst
@@ -56,7 +56,7 @@ interrupts. You can sleep, by calling :c:func:`schedule()`.
In user context, the ``current`` pointer (indicating the task we are
currently executing) is valid, and :c:func:`in_interrupt()`
-(``include/linux/interrupt.h``) is false.
+(``include/linux/preempt.h``) is false.
.. warning::
@@ -114,12 +114,12 @@ time, although different tasklets can run simultaneously.
Kuznetsov had at the time.
You can tell you are in a softirq (or tasklet) using the
-:c:func:`in_softirq()` macro (``include/linux/interrupt.h``).
+:c:func:`in_softirq()` macro (``include/linux/preempt.h``).
.. warning::
-Beware that this will return a false positive if a bh lock (see
-below) is held.
+Beware that this will return a false positive if a
+:ref:`botton half lock ` is held.
Some Basic Rules
@@ -154,9 +154,7 @@ The Linux kernel is portable
ioctls: Not writing a new system call
=
-A system call generally looks like this
-
-::
+A system call generally looks like this::
asmlinkage long sys_mycall(int arg)
{
@@ -175,7 +173,9 @@ If all your routine does is read or write some parameter,
consider
implementing a :c:func:`sysfs()` interface instead.
Inside the ioctl you're in user context to a process. When a error
-occurs you return a negated errno (see ``include/linux/errno.h``),
+occurs you return a negated errno (see
+``include/uapi/asm-generic/errno-base.h``,
+``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
otherwise you return 0.
After you slept you should check if a signal occurred: the Unix/Linux
@@ -195,9 +195,7 @@ some data structure.
If you're doing longer computations: first think userspace. If you
**really** want to do it in kernel you should regularly check if you need
to give up the CPU (remember there is cooperative multitasking per CPU).
-Idiom:
-
-::
+Idiom::
cond_resched(); /* Will sleep */
@@ -231,26 +229,24 @@ Really.
Common Routines
===
-:c:func:`printk()` ``include/linux/kernel.h``
--
+:c:func:`printk()`
+--
+
+Defined in ``include/linux/printk.h``
:c:func:`printk()` feeds kernel messages to the console, dmesg, and
the syslog daemon. It is useful for debugging and reporting errors, and
can be used inside interrupt context, but use with caution: a machine
which has its console flooded with printk messages is unusable. It uses
a format string mostly compatible with ANSI C printf, and C string
-concatenation to give it a first "priority" argument:
-
-::
+concatenation to give it a first "priority" argument::
printk(KERN_INFO "i = %u\n", i);
-See ``include/linux/kernel.h``; for other ``KERN_`` values; these are
+See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are
interpreted by syslog as the level. Special case: for printing an IP
-address use
-
-::
+address use::
__be32 ipaddress;
printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
@@ -270,8 +266,10 @@ overruns. Make sure that will be enough.
on top of its printf function: "Printf should not be used for
chit-chat". You should follow that advice.
-:c:func:`copy_[to/from]_user()` / :c:func:`get_user()` / :c:func:`put_user()`
``include/linux/uaccess.h``
--
+:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` /
:c:func:`put_user()`
+---
+
+Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
**[SLEEPS]**
@@ -297,8 +295,10 @@ The functions may sleep implicitly. This should never be
called outside
user context (it makes no sense), with interrupts disabled, or a
spinlock held.
-:c:func:`kmalloc()`/:c:func:`kfree()` ``include/linux/slab.h``
---
+:c:func:`kmalloc()`/:c:func:`kfree()`
+-
+
+Defined in ``include/linux/slab.h``
**[MAY SLEEP: SEE BELOW]**
@@ -324,9 +324,9 @@ message, then maybe you called a sleeping allocation
function from
interrupt context without ``GFP_ATOMIC``. You should really fix that.
Run, don't walk.
-If you are allocating at least ``PAGE_SIZE`` (``include/asm/pag
[PATCH 32/36] docs-rst: convert z8530book DocBook to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Some manual adjustments were required due to some conversion error on some literals. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/z8530book.tmpl | 371 - Documentation/networking/index.rst | 1 + Documentation/networking/z8530book.rst | 257 +++ 4 files changed, 259 insertions(+), 372 deletions(-) delete mode 100644 Documentation/DocBook/z8530book.tmpl create mode 100644 Documentation/networking/z8530book.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 8a90891c3712..00a61f4ffcff 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -6,7 +6,7 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS. -DOCBOOKS := z8530book.xml \ +DOCBOOKS := \ lsm.xml \ mtdnand.xml librs.xml rapidio.xml \ scsi.xml \ diff --git a/Documentation/DocBook/z8530book.tmpl b/Documentation/DocBook/z8530book.tmpl deleted file mode 100644 index 6f3883be877e.. --- a/Documentation/DocBook/z8530book.tmpl +++ /dev/null @@ -1,371 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - - Z8530 Programming Guide - - - -Alan -Cox - - - a...@lxorguk.ukuu.org.uk - - - - - - - 2000 - Alan Cox - - - - - 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. - - - - 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. - - - - 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 - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - - The Z85x30 family synchronous/asynchronous controller chips are - used on a large number of cheap network interface cards. The - kernel provides a core interface layer that is designed to make - it easy to provide WAN services using this chip. - - - The current driver only support synchronous operation. Merging the - asynchronous driver support into this code to allow any Z85x30 - device to be used as both a tty interface and as a synchronous - controller is a project for Linux post the 2.4 release - - - - - Driver Modes - - The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices - in three different modes. Each mode can be applied to an individual - channel on the chip (each chip has two channels). - - - The PIO synchronous mode supports the most common Z8530 wiring. Here - the chip is interface to the I/O and interrupt facilities of the - host machine but not to the DMA subsystem. When running PIO the - Z8530 has extremely tight timing requirements. Doing high speeds, - even with a Z85230 will be tricky. Typically you should expect to - achieve at best 9600 baud with a Z8C530 and 64Kbits with a Z85230. - - - The DMA mode supports the chip when it is configured to use dual DMA - channels on an ISA bus. The better cards tend to support this mode - of operation for a single channel. With DMA running the Z85230 tops - out when it starts to hit ISA DMA constraints at about 512Kbits. It - is worth noting here that many PC machines hang or crash when the - chip is driven fast enough to hold the ISA bus solid. - - - Transmit DMA mode uses a single DMA channel. The DMA channel is used - for transmission as the transmit FIFO is smaller than the receive - FIFO. it gives better performance than pure PIO mode but is nowhere - near as ideal as pure DMA mode. - - - - - Using the Z85230 driver - - The Z85230 driver provides the back end interface to your board. To - configure a Z8530 interface you need to detect the board and to - identify its ports and interrupt resources. It is also your problem - to verify the resources are available. - - - Having identified the chip you need to fill in a struct z8530_dev, - which describes each chip. This object must exist until you finally - shutdown the board. Firstly zero the act
[PATCH 33/36] docs-rst: convert scsi DocBook to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- 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.. --- a/Documentation/DocBook/scsi.tmpl +++ /dev/null @@ -1,409 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - -SCSI Interfaces Guide - - - -James -Bottomley - - -james.bottom...@hansenpartnership.com - - - - - -Rob -Landley - - -r...@landley.net - - - - - - - - 2007 - Linux Foundation - - - - -This documentation is free software; you can redistribute -it and/or modify it under the terms of the GNU General Public -License version 2. - - - -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. - - - - - - - -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 -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, TCP/IP -(iSCSI), even -Parallel -ports. - - - - 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 - - -!Iinclude/scsi/scsi_
[PATCH 31/36] net: fix some identation issues at kernel-doc markups
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
---
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_selectreceive packet
+ * CPU1CPU2
+ * sys_select receive packet
* ... ...
* __add_wait_queueupdate 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 p
[PATCH 09/36] kgdb.rst: Adjust ReST markups
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 --- 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 th
[PATCH 07/36] locking.rst: Update some ReST markups
Correct a few minor issues with ReST notation used on this file (produced by an automatic tool). Signed-off-by: Mauro Carvalho Chehab --- 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) ` - :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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 29/36] docs-rst: convert networking book to ReST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab
---
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..
--- a/Documentation/DocBook/networking.tmpl
+++ /dev/null
@@ -1,111 +0,0 @@
-
-http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []>
-
-
-
- Linux Networking and Network Devices APIs
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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
-
-
-
- For more details see the file COPYING in the source
- distribution of Linux.
-
-
-
-
-
-
-
- Linux Networking
- Networking Base Types
-!Iinclude/linux/net.h
-
- Socket Buffer Functions
-!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
-
- Socket Filter
-!Enet/core/filter.c
-
- Generic Network Statistics
-!Iinclude/uapi/linux/gen_stats.h
-!Enet/core/gen_stats.c
-!Enet/core/gen_estimator.c
-
- SUN RPC subsystem
-
-!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
-
- WiMAX
-!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
-
-
-
-
- Network device support
- Driver Support
-!Enet/core/dev.c
-!Enet/ethernet/eth.c
-!Enet/sched/sch_generic.c
-!Iinclude/linux/etherdevice.h
-!Iinclude/linux/netdevice.h
-
- PHY Support
-!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
-
-
-
-
-
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 ..40f69e67a883
--- /dev/null
+++ b/Documentation/networking/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Netw
[PATCH 24/36] fs: jbd2: escape a string with special chars on a kernel-doc
kernel-doc will try to interpret a foo() string, except if properly escaped. Signed-off-by: Mauro Carvalho Chehab --- fs/jbd2/transaction.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c index fe7f4a373436..38e1dcabbaca 100644 --- a/fs/jbd2/transaction.c +++ b/fs/jbd2/transaction.c @@ -1066,10 +1066,10 @@ static bool jbd2_write_access_granted(handle_t *handle, struct buffer_head *bh, * @handle: transaction to add buffer modifications to * @bh: bh to be used for metadata writes * - * Returns an error code or 0 on success. + * Returns: error code or 0 on success. * * In full data journalling mode the buffer may be of type BJ_AsyncData, - * because we're write()ing a buffer which is also part of a shared mapping. + * because we're ``write()ing`` a buffer which is also part of a shared mapping. */ int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh) -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 13/36] docs-rst: add crypto API book to pdf output
The crypto API book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/conf.py| 2 ++
Documentation/crypto/conf.py | 10 ++
2 files changed, 12 insertions(+)
create mode 100644 Documentation/crypto/conf.py
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 15f34d6863a7..ce62723491d4 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -351,6 +351,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('core-api/index', 'core-api.tex', 'The kernel core API manual',
'The kernel development community', 'manual'),
+('crypto/index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
+ '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',
diff --git a/Documentation/crypto/conf.py b/Documentation/crypto/conf.py
new file mode 100644
index ..4335d251ddf3
--- /dev/null
+++ b/Documentation/crypto/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel Crypto API'
+
+tags.add("subproject")
+
+latex_documents = [
+('index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
+ 'The kernel development community', 'manual'),
+]
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments
There are a few syntax violations that cause outputs of a few comments to not be properly parsed in ReST format. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- fs/locks.c | 18 -- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/fs/locks.c b/fs/locks.c index 26811321d39b..bdce708e4251 100644 --- a/fs/locks.c +++ b/fs/locks.c @@ -1858,8 +1858,8 @@ EXPORT_SYMBOL(generic_setlease); * * Call this to establish a lease on the file. The "lease" argument is not * used for F_UNLCK requests and may be NULL. For commands that set or alter - * an existing lease, the (*lease)->fl_lmops->lm_break operation must be set; - * if not, this function will return -ENOLCK (and generate a scary-looking + * an existing lease, the ``(*lease)->fl_lmops->lm_break`` operation must be + * set; if not, this function will return -ENOLCK (and generate a scary-looking * stack trace). * * The "priv" pointer is passed directly to the lm_setup function as-is. It @@ -1972,15 +1972,13 @@ EXPORT_SYMBOL(locks_lock_inode_wait); * @cmd: the type of lock to apply. * * Apply a %FL_FLOCK style lock to an open file descriptor. - * The @cmd can be one of + * The @cmd can be one of: * - * %LOCK_SH -- a shared lock. - * - * %LOCK_EX -- an exclusive lock. - * - * %LOCK_UN -- remove an existing lock. - * - * %LOCK_MAND -- a `mandatory' flock. This exists to emulate Windows Share Modes. + * - %LOCK_SH -- a shared lock. + * - %LOCK_EX -- an exclusive lock. + * - %LOCK_UN -- remove an existing lock. + * - %LOCK_MAND -- a 'mandatory' flock. + * This exists to emulate Windows Share Modes. * * %LOCK_MAND can be combined with %LOCK_READ or %LOCK_WRITE to allow other * processes read and write access respectively. -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 26/36] libata.rst: add c function and struct cross-references
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 --- 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 ` +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 ` +-- 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 loa
[PATCH 27/36] libata: fix identation on a kernel-doc markup
Sphinx got confused with the markup identation:
./drivers/ata/libata-scsi.c:3402: ERROR: Unexpected indentation.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab
---
drivers/ata/libata-scsi.c | 7 ---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/drivers/ata/libata-scsi.c b/drivers/ata/libata-scsi.c
index 49ba9834c715..dcd38d9e9804 100644
--- a/drivers/ata/libata-scsi.c
+++ b/drivers/ata/libata-scsi.c
@@ -3398,9 +3398,10 @@ static size_t ata_format_dsm_trim_descr(struct scsi_cmnd
*cmd, u32 trmax,
*
* Translate a SCSI WRITE SAME command to be either a DSM TRIM command or
* an SCT Write Same command.
- * Based on WRITE SAME has the UNMAP flag
- * When set translate to DSM TRIM
- * When clear translate to SCT Write Same
+ * Based on WRITE SAME has the UNMAP flag:
+ *
+ * - When set translate to DSM TRIM
+ * - When clear translate to SCT Write Same
*/
static unsigned int ata_scsi_write_same_xlat(struct ata_queued_cmd *qc)
{
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 34/36] scsi: fix some kernel-doc markups
Sphinx is very pedantic with regards to ident/spacing. Fix some kernel-doc markups in order to solve those errors/warnings: ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsicam.c:121: WARNING: Inline emphasis start-string without end-string. ./drivers/scsi/scsi_scan.c:1056: ERROR: Unexpected indentation. ./drivers/scsi/scsi_scan.c:1057: WARNING: Block quote ends without a blank line; unexpected unindent. ./drivers/scsi/scsi_transport_fc.c:2918: ERROR: Unexpected indentation. ./drivers/scsi/scsi_transport_fc.c:2921: WARNING: Block quote ends without a blank line; unexpected unindent. ./drivers/scsi/scsi_transport_fc.c:2922: WARNING: Enumerated list ends without a blank line; unexpected unindent. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- drivers/scsi/scsi_scan.c | 7 --- drivers/scsi/scsi_transport_fc.c | 18 ++ drivers/scsi/scsicam.c | 4 ++-- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/drivers/scsi/scsi_scan.c b/drivers/scsi/scsi_scan.c index 6f7128f49c30..69979574004f 100644 --- a/drivers/scsi/scsi_scan.c +++ b/drivers/scsi/scsi_scan.c @@ -1051,10 +1051,11 @@ static unsigned char *scsi_inq_str(unsigned char *buf, unsigned char *inq, * allocate and set it up by calling scsi_add_lun. * * Return: - * SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device - * SCSI_SCAN_TARGET_PRESENT: target responded, but no device is + * + * - SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device + * - SCSI_SCAN_TARGET_PRESENT: target responded, but no device is * attached at the LUN - * SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized + * - SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized **/ static int scsi_probe_and_add_lun(struct scsi_target *starget, u64 lun, int *bflagsp, diff --git a/drivers/scsi/scsi_transport_fc.c b/drivers/scsi/scsi_transport_fc.c index d4cf32d55546..1df77453f6b6 100644 --- a/drivers/scsi/scsi_transport_fc.c +++ b/drivers/scsi/scsi_transport_fc.c @@ -2914,16 +2914,18 @@ EXPORT_SYMBOL(fc_remote_port_add); * port is no longer part of the topology. Note: Although a port * may no longer be part of the topology, it may persist in the remote * ports displayed by the fc_host. We do this under 2 conditions: + * * 1) If the port was a scsi target, we delay its deletion by "blocking" it. - * This allows the port to temporarily disappear, then reappear without - * disrupting the SCSI device tree attached to it. During the "blocked" - * period the port will still exist. + *This allows the port to temporarily disappear, then reappear without + *disrupting the SCSI device tree attached to it. During the "blocked" + *period the port will still exist. + * * 2) If the port was a scsi target and disappears for longer than we - * expect, we'll delete the port and the tear down the SCSI device tree - * attached to it. However, we want to semi-persist the target id assigned - * to that port if it eventually does exist. The port structure will - * remain (although with minimal information) so that the target id - * bindings remails. + *expect, we'll delete the port and the tear down the SCSI device tree + *attached to it. However, we want to semi-persist the target id assigned + *to that port if it eventually does exist. The port structure will + *remain (although with minimal information) so that the target id + *bindings remails. * * If the remote port is not an FCP Target, it will be fully torn down * and deallocated, including the fc_remote_port class device. diff --git a/drivers/scsi/scsicam.c b/drivers/scsi/scsicam.c index 910f4a7a3924..31273468589c 100644 --- a/drivers/scsi/scsicam.c +++ b/drivers/scsi/scsicam.c @@ -116,8 +116,8 @@ EXPORT_SYMBOL(scsicam_bios_param); * @hds: put heads here * @secs: put sectors here * - * Description: determine the BIOS mapping/geometry used to create the partition - * table, storing the results in *cyls, *hds, and *secs + * Determine the BIOS mapping/geometry used to create the partition + * table, storing the results in @cyls, @hds, and @secs * * Returns: -1 on failure, 0 on success. */ -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 23/36] fs: eventfd: fix identation on kernel-doc
Sphinx require explicit tags in order to use a list of possible values, otherwise it produces this error: ./fs/eventfd.c:219: WARNING: Option list ends without a blank line; unexpected unindent. Signed-off-by: Mauro Carvalho Chehab --- fs/eventfd.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fs/eventfd.c b/fs/eventfd.c index 68b9fffcb2c8..beac8175de19 100644 --- a/fs/eventfd.c +++ b/fs/eventfd.c @@ -215,8 +215,8 @@ EXPORT_SYMBOL_GPL(eventfd_ctx_remove_wait_queue); * * Returns %0 if successful, or the following error codes: * - * -EAGAIN : The operation would have blocked but @no_wait was non-zero. - * -ERESTARTSYS : A signal interrupted the wait operation. + * - -EAGAIN : The operation would have blocked but @no_wait was non-zero. + * - -ERESTARTSYS : A signal interrupted the wait operation. * * If @no_wait is zero, the function might sleep until the eventfd internal * counter becomes greater than zero. -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 35/36] docs-rst: convert w1 book to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- 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.. --- a/Documentation/DocBook/w1.tmpl +++ /dev/null @@ -1,101 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - -W1: Dallas' 1-wire bus - - - -David -Fries - - -da...@fries.net - - - - - - - - 2013 - - - - - -This documentation is free software; you can redistribute -it and/or modify it under the terms of the GNU General Public -License version 2. - - - -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. - - - - - - - -W1 API internal to the kernel - - - W1 API internal to the kernel - -drivers/w1/w1.h -W1 core functions. -!Idrivers/w1/w1.h - - - -drivers/w1/w1.c -W1 core functions. -!Idrivers/w1/w1.c - - - -drivers/w1/w1_family.h -Allows registering device family operations. -!Idrivers/w1/w1_family.h - - - -drivers/w1/w1_family.c -Allows registering device family operations. -!Edrivers/w1/w1_family.c - - - -drivers/w1/w1_int.c -W1 internal initialization for master devices. -!Edrivers/w1/w1_int.c - - - -drivers/w1/w1_netlink.h -W1 external netlink API structures and commands. -!Idrivers/w1/w1_netlink.h - - - -drivers/w1/w1_io.c -W1 input/output. -!Edrivers/w1/w1_io.c -!Idrivers/w1/w1_io.c - - - - - - - - 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 ..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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 06/36] locking.rst: add captions to two tables
Those tables have a "caption" at the end, but ReST actually expects it on a different way. Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-hacking/locking.rst | 66 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index 17774b1f7587..b70c2c4eb147 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -29,43 +29,45 @@ In a normal program, you can increment a counter like so: This is what they would expect to happen: -+++ -| Instance 1 | Instance 2 | -+++ -| read very_important_count (5) || -+++ -| add 1 (6) || -+++ -| write very_important_count (6) || -+++ -|| read very_important_count (6) | -+++ -|| add 1 (7) | -+++ -|| write very_important_count (7) | -+++ -Table: Expected Results +.. table:: Expected Results + + +++ + | Instance 1 | Instance 2 | + +++ + | read very_important_count (5) || + +++ + | add 1 (6) || + +++ + | write very_important_count (6) || + +++ + || read very_important_count (6) | + +++ + || add 1 (7) | + +++ + || write very_important_count (7) | + +++ This is what might happen: -+++ -| Instance 1 | Instance 2 | -+++ -| read very_important_count (5) || -+++ -|| read very_important_count (5) | -+++ -| add 1 (6) || -+++ -|| add 1 (6) | -+++ -| write very_important_count (6) || -+++ -|| write very_important_count (6) | -+++ +.. table:: Possible Results + + +++ + | Instance 1 | Instance 2 | + +++ + | read very_important_count (5) || + +++ + || read very_important_count (5) | + +++ + | add 1 (6) || + +++ + || add 1 (
[PATCH 10/36] conf.py: define a color for important markup on PDF output
As kdbg.rst uses the ".. important::" annotation, let's define a
color for PDF output.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/conf.py | 8 +++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index bfa95c881956..e9480717746e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -281,6 +281,7 @@ latex_elements = {
\\definecolor{NoteColor}{RGB}{204,255,255}
\\definecolor{WarningColor}{RGB}{255,204,204}
\\definecolor{AttentionColor}{RGB}{255,255,204}
+ \\definecolor{ImportantColor}{RGB}{192,255,204}
\\definecolor{OtherColor}{RGB}{204,204,204}
\\newlength{\\mynoticelength}
\\makeatletter\\newenvironment{coloredbox}[1]{%
@@ -301,7 +302,12 @@ latex_elements = {
\\ifthenelse%
{\\equal{\\py@noticetype}{attention}}%
{\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
- {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
+ {%
+ \\ifthenelse%
+ {\\equal{\\py@noticetype}{important}}%
+ {\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}%
+ {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
+ }%
}%
}%
}\\makeatother
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 28/36] docs-rst: convert s390-drivers DocBook to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile| 2 +- Documentation/DocBook/s390-drivers.tmpl | 161 -- Documentation/driver-api/index.rst| 1 + Documentation/driver-api/s390-drivers.rst | 111 4 files changed, 113 insertions(+), 162 deletions(-) delete mode 100644 Documentation/DocBook/s390-drivers.tmpl create mode 100644 Documentation/driver-api/s390-drivers.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index abe71345160b..a25bf10384e1 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -10,7 +10,7 @@ DOCBOOKS := z8530book.xml \ networking.xml \ lsm.xml \ mtdnand.xml librs.xml rapidio.xml \ - s390-drivers.xml scsi.xml \ + scsi.xml \ sh.xml w1.xml ifeq ($(DOCBOOKS),) diff --git a/Documentation/DocBook/s390-drivers.tmpl b/Documentation/DocBook/s390-drivers.tmpl deleted file mode 100644 index 95bfc12e5439.. --- a/Documentation/DocBook/s390-drivers.tmpl +++ /dev/null @@ -1,161 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - - Writing s390 channel device drivers - - - -Cornelia -Huck - - - cornelia.h...@de.ibm.com - - - - - - - 2007 - IBM Corp. - - - - - 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. - - - - 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. - - - - 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 - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - -This document describes the interfaces available for device drivers that -drive s390 based channel attached I/O devices. This includes interfaces for -interaction with the hardware and interfaces for interacting with the -common driver core. Those interfaces are provided by the s390 common I/O -layer. - - -The document assumes a familarity with the technical terms associated -with the s390 channel I/O architecture. For a description of this -architecture, please refer to the "z/Architecture: Principles of -Operation", IBM publication no. SA22-7832. - - -While most I/O devices on a s390 system are typically driven through the -channel I/O mechanism described here, there are various other methods -(like the diag interface). These are out of the scope of this document. - - -Some additional information can also be found in the kernel source -under Documentation/s390/driver-model.txt. - - - - The ccw bus - - The ccw bus typically contains the majority of devices available to - a s390 system. Named after the channel command word (ccw), the basic - command structure used to address its devices, the ccw bus contains - so-called channel attached devices. They are addressed via I/O - subchannels, visible on the css bus. A device driver for - channel-attached devices, however, will never interact with the - subchannel directly, but only via the I/O device on the ccw bus, - the ccw device. - - - I/O functions for channel-attached devices - - Some hardware structures have been translated into C structures for use - by the common I/O layer and device drivers. For more information on - the hardware structures represented here, please consult the Principles - of Operation. - -!Iarch/s390/include/asm/cio.h - - - ccw devices - - Devices that want to initiate channel I/O need to attach to the ccw bus. - Interaction with the driver core is done via the common I/O layer, which - provides the abstractions of ccw devices and ccw device drivers. - - - The functions that initiate or terminate channel I/O all act upon a - ccw device structure. Device drivers must not bypass those functions - or strange side effects may happen. - -!Iarch/s390/include/asm/ccwdev.h -!Edrivers/s390/cio/device.c -!Edrivers/s390/cio/device_ops.c - - - The channel-measurement facility - - The channel-measurement facility provides a means
[PATCH 19/36] fs: jbd2: make jbd2_journal_start() kernel-doc parseable
kernel-doc script expects that a function documentation to
be just before the function, otherwise it will be ignored.
So, move the kernel-doc markup to the right place.
Signed-off-by: Mauro Carvalho Chehab
---
fs/jbd2/transaction.c | 38 +++---
1 file changed, 19 insertions(+), 19 deletions(-)
diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
index 9ee4832b6f8b..fe7f4a373436 100644
--- a/fs/jbd2/transaction.c
+++ b/fs/jbd2/transaction.c
@@ -409,25 +409,6 @@ static handle_t *new_handle(int nblocks)
return handle;
}
-/**
- * handle_t *jbd2_journal_start() - Obtain a new handle.
- * @journal: Journal to start transaction on.
- * @nblocks: number of block buffer we might modify
- *
- * We make sure that the transaction can guarantee at least nblocks of
- * modified buffers in the log. We block until the log can guarantee
- * that much space. Additionally, if rsv_blocks > 0, we also create another
- * handle with rsv_blocks reserved blocks in the journal. This handle is
- * is stored in h_rsv_handle. It is not attached to any particular transaction
- * and thus doesn't block transaction commit. If the caller uses this reserved
- * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
- * on the parent handle will dispose the reserved one. Reserved handle has to
- * be converted to a normal handle using jbd2_journal_start_reserved() before
- * it can be used.
- *
- * Return a pointer to a newly allocated handle, or an ERR_PTR() value
- * on failure.
- */
handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
gfp_t gfp_mask, unsigned int type,
unsigned int line_no)
@@ -478,6 +459,25 @@ handle_t *jbd2__journal_start(journal_t *journal, int
nblocks, int rsv_blocks,
EXPORT_SYMBOL(jbd2__journal_start);
+/**
+ * handle_t *jbd2_journal_start() - Obtain a new handle.
+ * @journal: Journal to start transaction on.
+ * @nblocks: number of block buffer we might modify
+ *
+ * We make sure that the transaction can guarantee at least nblocks of
+ * modified buffers in the log. We block until the log can guarantee
+ * that much space. Additionally, if rsv_blocks > 0, we also create another
+ * handle with rsv_blocks reserved blocks in the journal. This handle is
+ * is stored in h_rsv_handle. It is not attached to any particular transaction
+ * and thus doesn't block transaction commit. If the caller uses this reserved
+ * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
+ * on the parent handle will dispose the reserved one. Reserved handle has to
+ * be converted to a normal handle using jbd2_journal_start_reserved() before
+ * it can be used.
+ *
+ * Return a pointer to a newly allocated handle, or an ERR_PTR() value
+ * on failure.
+ */
handle_t *jbd2_journal_start(journal_t *journal, int nblocks)
{
return jbd2__journal_start(journal, nblocks, 0, GFP_NOFS, 0, 0);
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 20/36] docs-rst: don't ignore internal functions for jbd2 docs
Those functions are currently ignored, causing references at the documentation to be lost. Don't ignore it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/filesystems/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 148becd91cba..256e10eedba4 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -287,7 +287,6 @@ Transasction Level ~~ .. kernel-doc:: fs/jbd2/transaction.c - :export: See also -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 22/36] fs: add a blank lines on some kernel-doc comments
Sphinx gets confused when it finds identation without a good reason for it and without a preceding blank line: ./fs/mpage.c:347: ERROR: Unexpected indentation. ./fs/namei.c:4303: ERROR: Unexpected indentation. ./fs/fs-writeback.c:2060: ERROR: Unexpected indentation. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- fs/fs-writeback.c | 12 +++- fs/mpage.c| 1 + fs/namei.c| 1 + 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/fs/fs-writeback.c b/fs/fs-writeback.c index 63ee2940775c..8b426f83909f 100644 --- a/fs/fs-writeback.c +++ b/fs/fs-writeback.c @@ -2052,11 +2052,13 @@ static noinline void block_dump___mark_inode_dirty(struct inode *inode) } /** - * __mark_inode_dirty -internal function - * @inode: inode to mark - * @flags: what kind of dirty (i.e. I_DIRTY_SYNC) - * Mark an inode as dirty. Callers should use mark_inode_dirty or - * mark_inode_dirty_sync. + * __mark_inode_dirty -internal function + * + * @inode: inode to mark + * @flags: what kind of dirty (i.e. I_DIRTY_SYNC) + * + * Mark an inode as dirty. Callers should use mark_inode_dirty or + * mark_inode_dirty_sync. * * Put the inode on the super block's dirty list. * diff --git a/fs/mpage.c b/fs/mpage.c index baff8f820c29..4760a0c09a4e 100644 --- a/fs/mpage.c +++ b/fs/mpage.c @@ -344,6 +344,7 @@ do_mpage_readpage(struct bio *bio, struct page *page, unsigned nr_pages, * * So an mpage read of the first 16 blocks of an ext2 file will cause I/O to be * submitted in the following order: + * * 12 0 1 2 3 4 5 6 7 8 9 10 11 13 14 15 16 * * because the indirect block has to be read to get the mappings of blocks diff --git a/fs/namei.c b/fs/namei.c index 7286f87ce863..b5af8228e2d9 100644 --- a/fs/namei.c +++ b/fs/namei.c @@ -4300,6 +4300,7 @@ SYSCALL_DEFINE2(link, const char __user *, oldname, const char __user *, newname * The worst of all namespace operations - renaming directory. "Perverted" * doesn't even start to describe it. Somebody in UCB had a heck of a trip... * Problems: + * * a) we can get into loop creation. * b) race potential - two innocent renames can create a loop together. *That's where 4.4 screws up. Current fix: serialization on -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 15/36] docs-rst: add sound book to pdf output
The sound subsystem book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/conf.py | 2 ++
Documentation/sound/conf.py | 10 ++
2 files changed, 12 insertions(+)
create mode 100644 Documentation/sound/conf.py
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1d461f0c1cd0..bca751960dec 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -371,6 +371,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('security/index', 'security.tex', 'The kernel security subsystem manual',
'The kernel development community', 'manual'),
+('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
+ 'The kernel development community', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
diff --git a/Documentation/sound/conf.py b/Documentation/sound/conf.py
new file mode 100644
index ..3f1fc5e74e7b
--- /dev/null
+++ b/Documentation/sound/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux Sound Subsystem Documentation"
+
+tags.add("subproject")
+
+latex_documents = [
+('index', 'sound.tex', project,
+ 'The kernel development community', 'manual'),
+]
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 16/36] docs-rst: add userspace API book to pdf output
The userspace API book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/conf.py | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index bca751960dec..2e215477edf5 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -373,6 +373,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
'The kernel development community', 'manual'),
+('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space
API guide',
+ 'The kernel development community', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 11/36] docs-rst: conf.py: sort LaTeX documents in alphabetical order
As we add more documents, it makes more sense to sort the
entries there in alphabetical order, as it makes easier to
check if something is not there.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/conf.py | 13 +++--
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index e9480717746e..1a76daec7f9c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -345,27 +345,28 @@ if major == 1 and minor > 3:
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
+# Sorted in alphabetical order
latex_documents = [
-('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation
Guide',
- 'The kernel development community', 'manual'),
('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
'The kernel development community', 'manual'),
('core-api/index', 'core-api.tex', 'The kernel core API manual',
'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',
'The kernel development community', 'manual'),
+('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
+ 'The kernel development community', 'manual'),
('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
'The kernel development community', 'manual'),
('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel
Documentation',
'The kernel development community', 'manual'),
('kernel-hacking/index', 'kernel-hacking.tex', 'Unreliable Guide To
Hacking The Linux Kernel',
'The kernel development community', 'manual'),
-('process/index', 'development-process.tex', 'Linux Kernel Development
Documentation',
- 'The kernel development community', 'manual'),
-('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
- 'The kernel development community', 'manual'),
('media/index', 'media.tex', 'Linux Media Subsystem 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',
'The kernel development community', 'manual'),
]
--
2.9.3
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] Documentation: crypto: Fixed bugs, added example usage of calc_hash().
- Fixed bugs in example for shash and rng (added missing "*" and " *").
- Corrected pr_info() in calc_hash().
- Added example usage of calc_hash().
- No need for negate PTR_ERR to get error code, as crypto_alloc_rng
already returns negative values like ERR_PTR(-ENOMEM). Fixed.
Signed-off-by: Kamil Konieczny
---
Documentation/crypto/api-samples.rst | 38 ++--
1 file changed, 28 insertions(+), 10 deletions(-)
diff --git a/Documentation/crypto/api-samples.rst
b/Documentation/crypto/api-samples.rst
index d021fd96a76d..2531948db89f 100644
--- a/Documentation/crypto/api-samples.rst
+++ b/Documentation/crypto/api-samples.rst
@@ -155,9 +155,9 @@ Code Example For Use of Operational State Memory With SHASH
char ctx[];
};
-static struct sdesc init_sdesc(struct crypto_shash *alg)
+static struct sdesc *init_sdesc(struct crypto_shash *alg)
{
-struct sdesc sdesc;
+struct sdesc *sdesc;
int size;
size = sizeof(struct shash_desc) + crypto_shash_descsize(alg);
@@ -169,15 +169,16 @@ Code Example For Use of Operational State Memory With
SHASH
return sdesc;
}
-static int calc_hash(struct crypto_shashalg,
- const unsigned chardata, unsigned int datalen,
- unsigned chardigest) {
-struct sdesc sdesc;
+static int calc_hash(struct crypto_shash *alg,
+ const unsigned char *data, unsigned int datalen,
+ unsigned char *digest)
+{
+struct sdesc *sdesc;
int ret;
sdesc = init_sdesc(alg);
if (IS_ERR(sdesc)) {
-pr_info("trusted_key: can't alloc %s\n", hash_alg);
+pr_info("can't alloc sdesc\n");
return PTR_ERR(sdesc);
}
@@ -186,6 +187,23 @@ Code Example For Use of Operational State Memory With SHASH
return ret;
}
+static int test_hash(const unsigned char *data, unsigned int datalen,
+ unsigned char *digest)
+{
+struct crypto_shash *alg;
+char *hash_alg_name = "sha1-padlock-nano";
+int ret;
+
+alg = crypto_alloc_shash(hash_alg_name, CRYPTO_ALG_TYPE_SHASH, 0);
+if (IS_ERR(alg)) {
+pr_info("can't alloc alg %s\n", hash_alg_name);
+return PTR_ERR(alg);
+}
+ret = calc_hash(alg, data, datalen, digest);
+crypto_free_shash(alg);
+return ret;
+}
+
Code Example For Random Number Generator Usage
--
@@ -195,8 +213,8 @@ Code Example For Random Number Generator Usage
static int get_random_numbers(u8 *buf, unsigned int len)
{
-struct crypto_rngrng = NULL;
-chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */
+struct crypto_rng *rng = NULL;
+char *drbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */
int ret;
if (!buf || !len) {
@@ -207,7 +225,7 @@ Code Example For Random Number Generator Usage
rng = crypto_alloc_rng(drbg, 0, 0);
if (IS_ERR(rng)) {
pr_debug("could not allocate RNG handle for %s\n", drbg);
-return -PTR_ERR(rng);
+return PTR_ERR(rng);
}
ret = crypto_rng_get_bytes(rng, buf, len);
--
2.7.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 01/36] docs-rst: convert kernel-hacking to ReST
Am 12.05.2017 um 15:59 schrieb Mauro Carvalho Chehab : > Use pandoc to convert documentation to ReST by calling > Documentation/sphinx/tmplcvt script. > > - Manually adjusted to use ..note and ..warning > - Minor fixes for it to be parsed without errors > - Use **bold** for emphasis. > > Signed-off-by: Mauro Carvalho Chehab > --- > Documentation/DocBook/Makefile|2 +- > Documentation/DocBook/kernel-hacking.tmpl | 1312 - > Documentation/conf.py |2 + > Documentation/index.rst |1 + > Documentation/kernel-hacking/conf.py | 10 + > Documentation/kernel-hacking/index.rst| 794 + > 6 files changed, 808 insertions(+), 1313 deletions(-) > delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl > create mode 100644 Documentation/kernel-hacking/conf.py > create mode 100644 Documentation/kernel-hacking/index.rst > > > +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` > ``include/asm/byteorder.h`` > +--- > + Hi Mauro, just my bikeshedding: what do you think, do we really need to refer functions in titles? As far as I know, there is no use-case where we can get any benefit from. So I recommend to write titles more simple, e.g.: cpu_to_be32()/be32_to_cpu()/cpu_to_le32()/le32_to_cpu() include/asm/byteorder.h .. which is long enough ;) -- Markus -- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST
On Fri, May 12, 2017 at 10:59:47AM -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. > Fix them. > > No functional changes. > > Signed-off-by: Mauro Carvalho Chehab No objection. One question, rather than prefixing the bulleted list of return codes with a "-" which has no ReST meaning I could find, should we use "*" instead which would be converted to a bullet it formatted documentation? > @@ -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 > * e.g. * Return: * * 0 - ready to wait * * 1 - acquired the lock * * <0 - error I'm fine with either though, just curious if this would be an improvement, or if we have an established policy (which I didn't find in the docs on docs...). Acked-by: Darren Hart (VMware) -- Darren Hart VMware Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] mm: per-cgroup memory reclaim stats
On Fri, May 12, 2017 at 12:25:22PM +1000, Balbir Singh wrote:
> On Thu, 2017-05-11 at 20:16 +0100, Roman Gushchin wrote:
> > The meaning of each value is the same as for global counters,
> > available using /proc/vmstat.
> >
> > Also, for consistency, rename mem_cgroup_count_vm_event() to
> > count_memcg_event_mm().
> >
>
> I still prefer the mem_cgroup_count_vm_event() name, or
> memcg_count_vm_event(),
> the namespace upfront makes it easier to parse where to look for the the
> implementation and also grep. In any case the rename should be independent
> patch, but I don't like the name you've proposed.
The memory controller is no longer a tacked-on feature to the VM - the
entire reclaim path is designed around cgroups at this point. The
namespacing is just cumbersome and doesn't add add any value, IMO.
This name is also more consistent with the stats interface, where we
use nodes, zones, memcgs all equally to describe scopes/containers:
inc_node_state(), inc_zone_state(), inc_memcg_state()
> > @@ -357,6 +357,17 @@ static inline unsigned short mem_cgroup_id(struct
> > mem_cgroup *memcg)
> > }
> > struct mem_cgroup *mem_cgroup_from_id(unsigned short id);
> >
> > +static inline struct mem_cgroup *lruvec_memcg(struct lruvec *lruvec)
>
> mem_cgroup_from_lruvec()?
This name is consistent with other lruvec accessors such as
lruvec_pgdat() and lruvec_lru_size() etc.
> > @@ -1741,11 +1748,16 @@ shrink_inactive_list(unsigned long nr_to_scan,
> > struct lruvec *lruvec,
> >
> > spin_lock_irq(&pgdat->lru_lock);
> >
> > - if (global_reclaim(sc)) {
> > - if (current_is_kswapd())
> > + if (current_is_kswapd()) {
> > + if (global_reclaim(sc))
> > __count_vm_events(PGSTEAL_KSWAPD, nr_reclaimed);
> > - else
> > + count_memcg_events(lruvec_memcg(lruvec), PGSTEAL_KSWAPD,
> > + nr_reclaimed);
>
> Has the else gone missing? What happens if it's global_reclaim(), do
> we still account the count in memcg?
>
> > + } else {
> > + if (global_reclaim(sc))
> > __count_vm_events(PGSTEAL_DIRECT, nr_reclaimed);
> > + count_memcg_events(lruvec_memcg(lruvec), PGSTEAL_DIRECT,
> > + nr_reclaimed);
>
> It sounds like memcg accumlates both global and memcg reclaim driver
> counts -- is this what we want?
Yes.
Consider a fully containerized system that is using only memory.low
and thus exclusively global reclaim to enforce the partitioning, NOT
artificial limits and limit reclaim. In this case, we still want to
know how much reclaim activity each group is experiencing.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 03/36] docs-rst: convert kernel-locking to ReST
Am 12.05.2017 um 15:59 schrieb Mauro Carvalho Chehab : > Use pandoc to convert documentation to ReST by calling > Documentation/sphinx/tmplcvt script. > > - Manually adjust tables with got broken by conversion > > Signed-off-by: Mauro Carvalho Chehab > --- > Documentation/DocBook/Makefile|1 - > Documentation/DocBook/kernel-locking.tmpl | 2151 - > Documentation/kernel-hacking/hacking.rst | 811 +++ > Documentation/kernel-hacking/index.rst| 814 +-- > Documentation/kernel-hacking/locking.rst | 1453 +++ > 5 files changed, 2268 insertions(+), 2962 deletions(-) > delete mode 100644 Documentation/DocBook/kernel-locking.tmpl > create mode 100644 Documentation/kernel-hacking/hacking.rst > create mode 100644 Documentation/kernel-hacking/locking.rst ... There are some misplaced colons at the end of the filenames ... > +``arch/x86/include/asm/uaccess_32.h:``:: > + > +#define copy_to_user(to,from,n) \ > +(__builtin_constant_p(n) ? \ > + __constant_copy_to_user((to),(from),(n)) : \ > + __generic_copy_to_user((to),(from),(n))) > + ... > + > +``arch/sparc/kernel/head.S:``:: > + > +/* > + * Sun people can't spell worth damn. "compatability" indeed. > + * At least we *know* we can't spell, and use a spell-checker. > + */ > + ... > + > +``arch/sparc/lib/checksum.S:``:: > + > +/* Sun, you just can't beat me, you just can't. Stop trying, > + * give up. I'm serious, I am going to kick the living shit > + * out of you, game over, lights out. > + */ -- Markus-- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 03/36] docs-rst: convert kernel-locking to ReST
Am 12.05.2017 um 15:59 schrieb Mauro Carvalho Chehab : > Use pandoc to convert documentation to ReST by calling > Documentation/sphinx/tmplcvt script. > > - Manually adjust tables with got broken by conversion > > Signed-off-by: Mauro Carvalho Chehab > --- > Documentation/DocBook/Makefile|1 - > Documentation/DocBook/kernel-locking.tmpl | 2151 - > Documentation/kernel-hacking/hacking.rst | 811 +++ > Documentation/kernel-hacking/index.rst| 814 +-- > Documentation/kernel-hacking/locking.rst | 1453 +++ > 5 files changed, 2268 insertions(+), 2962 deletions(-) > delete mode 100644 Documentation/DocBook/kernel-locking.tmpl > create mode 100644 Documentation/kernel-hacking/hacking.rst > create mode 100644 Documentation/kernel-hacking/locking.rst > > ... > diff --git a/Documentation/kernel-hacking/index.rst > b/Documentation/kernel-hacking/index.rst > index 1a456b60a7cf..b3d8fe56d310 100644 > --- a/Documentation/kernel-hacking/index.rst > +++ b/Documentation/kernel-hacking/index.rst > @@ -1,811 +1,5 @@ > - > -Unreliable Guide To Hacking The Linux Kernel > - > +.. toctree:: > + :maxdepth: 2 Every .rst file needs a title, otherwise is inserted, see breadcrumb at the top : https://mchehab.fedorapeople.org/kernel_docs/kernel-hacking/index.html -- Markus -- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Support for advanced documentation around data type definitions
Hello, Some data type definitions are provided by Linux source files. How would you like to see them represented in the documentation formats which are generated by the Sphinx software? Regards, Markus -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Resend][PATCH] cpufreq: intel_pstate: Document the current behavior and user interface
On Friday, May 05, 2017 11:38:42 PM Rafael J. Wysocki wrote: > From: Rafael J. Wysocki > > Add a document describing the current behavior and user space > interface of the intel_pstate driver in the RST format and > drop the existing outdated intel_pstate.txt document. > > Also update admin-guide/pm/cpufreq.rst with proper RST references > to the new intel_pstate.rst document. > > Signed-off-by: Rafael J. Wysocki > --- > > Hi Jon, > > All of the dependencies for this patch have been merged, so I can route it > through the PM tree. > > Please let me know if you prefer to take it into the documentation tree > instead. I'm taking the lack of response as the lack of objections, so I'll route this document through the PM tree. Thanks, Rafael -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Resend][PATCH] cpufreq: intel_pstate: Document the current behavior and user interface
On Fri, 12 May 2017 22:47:25 +0200 "Rafael J. Wysocki" wrote: > > Hi Jon, > > > > All of the dependencies for this patch have been merged, so I can route it > > through the PM tree. > > > > Please let me know if you prefer to take it into the documentation tree > > instead. > > I'm taking the lack of response as the lack of objections, so I'll route this > document through the PM tree. Sorry, didn't mean to drop the ball on this. Anyway, no objections. Thanks, jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [Resend][PATCH] cpufreq: intel_pstate: Document the current behavior and user interface
On Friday, May 12, 2017 03:20:48 PM Jonathan Corbet wrote: > On Fri, 12 May 2017 22:47:25 +0200 > "Rafael J. Wysocki" wrote: > > > > Hi Jon, > > > > > > All of the dependencies for this patch have been merged, so I can route it > > > through the PM tree. > > > > > > Please let me know if you prefer to take it into the documentation tree > > > instead. > > > > I'm taking the lack of response as the lack of objections, so I'll route > > this > > document through the PM tree. > > Sorry, didn't mean to drop the ball on this. No worries. > Anyway, no objections. Thanks! Cheers, Rafael -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST
Em Fri, 12 May 2017 09:41:22 -0700 Darren Hart escreveu: > On Fri, May 12, 2017 at 10:59:47AM -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. > > Fix them. > > > > No functional changes. > > > > Signed-off-by: Mauro Carvalho Chehab > > No objection. One question, rather than prefixing the bulleted list of return > codes with a "-" which has no ReST meaning I could find, should we use "*" > instead which would be converted to a bullet it formatted documentation? At least on Sphinx[1]: "A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed by whitespace, is a bullet list item" I never tried "+", but both "-" and "*" produce the same visual. [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists > > > @@ -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 > > * > > e.g. > > * Return: > * * 0 - ready to wait > * * 1 - acquired the lock > * * <0 - error > > I'm fine with either though, just curious if this would be an improvement, or > if > we have an established policy (which I didn't find in the docs on docs...). I prefer myself to use "-". IMHO, a dash is visually less polluted than an asterisk, when reading text files, but I guess this is a matter of taste. > Acked-by: Darren Hart (VMware) Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST
On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote: > Em Fri, 12 May 2017 09:41:22 -0700 > Darren Hart escreveu: > > > On Fri, May 12, 2017 at 10:59:47AM -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. > > > Fix them. > > > > > > No functional changes. > > > > > > Signed-off-by: Mauro Carvalho Chehab > > > > No objection. One question, rather than prefixing the bulleted list of > > return > > codes with a "-" which has no ReST meaning I could find, should we use "*" > > instead which would be converted to a bullet it formatted documentation? > > At least on Sphinx[1]: > "A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", >followed by whitespace, is a bullet list item" > > I never tried "+", but both "-" and "*" produce the same visual. > > [1] > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists > Thanks, my search turned up a much shorter list of "list" special characters. > > > > > @@ -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 > > > * > > > > e.g. > > > > * Return: > > * * 0 - ready to wait > > * * 1 - acquired the lock > > * * <0 - error > > > > I'm fine with either though, just curious if this would be an improvement, > > or if > > we have an established policy (which I didn't find in the docs on docs...). > > I prefer myself to use "-". IMHO, a dash is visually less polluted > than an asterisk, when reading text files, but I guess this is a > matter of taste. Definitely agreed. - is preferable if it renders the same. Thanks, -- Darren Hart VMware Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST
On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote: > > * Return: > > * * 0 - ready to wait > > * * 1 - acquired the lock > > * * <0 - error > > > > I'm fine with either though, just curious if this would be an improvement, > > or if > > we have an established policy (which I didn't find in the docs on docs...). > > I prefer myself to use "-". IMHO, a dash is visually less polluted > than an asterisk, when reading text files, but I guess this is a > matter of taste. Not to mention it just reads very awkward in a comment. I don't much care about it in any other context. And I really _really_ hate to see that rest crap spread here. Can't we just delete all that nonsense and go back to 80 column 7bit ASCII ? It is an incentive not to use kerneldoc.. -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST
On Sat, May 13, 2017 at 12:11:09AM +0200, Peter Zijlstra wrote: > On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote: > > > * Return: > > > * * 0 - ready to wait > > > * * 1 - acquired the lock > > > * * <0 - error > > > > > > I'm fine with either though, just curious if this would be an > > > improvement, or if > > > we have an established policy (which I didn't find in the docs on > > > docs...). > > > > I prefer myself to use "-". IMHO, a dash is visually less polluted > > than an asterisk, when reading text files, but I guess this is a > > matter of taste. > > Not to mention it just reads very awkward in a comment. I don't much > care about it in any other context. Agreed, the - is better (and equally functional - so yay). > > And I really _really_ hate to see that rest crap spread here. Can't we > just delete all that nonsense and go back to 80 column 7bit ASCII ? > Depending on the source this could be a genuine appeal or satire :-D In this case, I don't think the ReST changes (with -) make the comment block any less readable in the C files. > It is an incentive not to use kerneldoc.. > I like the kerneldoc if for no other reason that it helps keeps formatting consistent. I would object if I started seeing XML or some other horrible formatting style showing up in the code, but this honestly seems like a fairly minimal imposition... but that's me. -- Darren Hart VMware Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 26/36] libata.rst: add c function and struct cross-references
Hi Mauro, [auto build test WARNING on linus/master] [also build test WARNING on next-20170512] [cannot apply to v4.11] [if your patch is applied to the wrong git tree, please drop us a note to help improve the system] url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/docs-rst-convert-kernel-hacking-to-ReST/20170513-131229 reproduce: make htmldocs All warnings (new ones prefixed by >>): WARNING: convert(1) not found, for SVG to PDF conversion install ImageMagick (https://www.imagemagick.org) arch/x86/include/asm/uaccess_32.h:1: warning: no structured comments found include/linux/init.h:1: warning: no structured comments found include/linux/mod_devicetable.h:686: warning: Excess struct/union/enum/typedef member 'ver_major' description in 'fsl_mc_device_id' include/linux/mod_devicetable.h:686: warning: Excess struct/union/enum/typedef member 'ver_minor' description in 'fsl_mc_device_id' kernel/sched/core.c:2088: warning: No description found for parameter 'rf' kernel/sched/core.c:2088: warning: Excess function parameter 'cookie' description in 'try_to_wake_up_local' include/linux/kthread.h:26: warning: Excess function parameter '...' description in 'kthread_create' kernel/sys.c:1: warning: no structured comments found include/linux/device.h:969: warning: No description found for parameter 'dma_ops' drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found include/linux/iio/iio.h:597: warning: No description found for parameter 'trig_readonly' include/linux/iio/trigger.h:151: warning: No description found for parameter 'indio_dev' include/linux/iio/trigger.h:151: warning: No description found for parameter 'trig' include/linux/device.h:970: warning: No description found for parameter 'dma_ops' >> drivers/ata/libata-eh.c:1449: warning: No description found for parameter >> 'link' >> drivers/ata/libata-eh.c:1449: warning: Excess function parameter 'ap' >> description in 'ata_eh_done' >> drivers/ata/libata-eh.c:1654: warning: No description found for parameter >> 'qc' >> drivers/ata/libata-eh.c:1654: warning: Excess function parameter 'dev' >> description in 'ata_eh_request_sense' include/linux/usb/gadget.h:230: warning: No description found for parameter 'claimed' include/linux/usb/gadget.h:230: warning: No description found for parameter 'enabled' include/linux/usb/gadget.h:408: warning: No description found for parameter 'quirk_altset_not_supp' include/linux/usb/gadget.h:408: warning: No description found for parameter 'quirk_stall_not_supp' include/linux/usb/gadget.h:408: warning: No description found for parameter 'quirk_zlp_not_supp' fs/inode.c:1665: warning: No description found for parameter 'rcu' include/linux/jbd2.h:443: warning: No description found for parameter 'i_transaction' include/linux/jbd2.h:443: warning: No description found for parameter 'i_next_transaction' include/linux/jbd2.h:443: warning: No description found for parameter 'i_list' include/linux/jbd2.h:443: warning: No description found for parameter 'i_vfs_inode' include/linux/jbd2.h:443: warning: No description found for parameter 'i_flags' include/linux/jbd2.h:497: warning: No description found for parameter 'h_rsv_handle' include/linux/jbd2.h:497: warning: No description found for parameter 'h_reserved' include/linux/jbd2.h:497: warning: No description found for parameter 'h_type' include/linux/jbd2.h:497: warning: No description found for parameter 'h_line_no' include/linux/jbd2.h:497: warning: No description found for parameter 'h_start_jiffies' include/linux/jbd2.h:497: warning: No description found for parameter 'h_requested_credits' include/linux/jbd2.h:497: warning: No description found for parameter 'saved_alloc_context' include/linux/jbd2.h:1050: warning: No description found for parameter 'j_chkpt_bhs' include/linux/jbd2.h:1050: warning: No description found for parameter 'j_devname' include/linux/jbd2.h:1050: warning: No description found for parameter 'j_average_commit_time' include/linux/jbd2.h:1050: warning: No description found for parameter 'j_min_batch_time' include/linux/jbd2.h:1050: warning: No description found for parameter 'j_max_batch_time' include/linux/jbd2.h:1050: warning: No description found for parameter 'j_commit_callback' include/linux/jbd2.h:1050: warning: No description found for parameter 'j_failed_commit'
