[PATCH] doc-rst: fixed kernel-doc directives in usb/typec.rst

[Markus Heiser]

Even if this file is not yet included in any toctree, it is parsed by
Sphinx since it is named '.rst'. This patch fixes the following two
ERRORs from Sphinx build:

Documentation/usb/typec.rst:116: ERROR: Error in "kernel-doc" directive:
invalid option block.

.. kernel-doc:: drivers/usb/typec/typec.c
   :functions: typec_register_cable typec_unregister_cable typec_register_plug
   typec_unregister_plug

Documentation/usb/typec.rst:139: ERROR: Error in "kernel-doc" directive:
invalid option block.

.. kernel-doc:: drivers/usb/typec/typec.c
   :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role
   typec_set_pwr_opmode

Signed-off-by: Markus Heiser 
---
 Documentation/usb/typec.rst | 6 ++
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/Documentation/usb/typec.rst b/Documentation/usb/typec.rst
index b67a467..8a7249f 100644
--- a/Documentation/usb/typec.rst
+++ b/Documentation/usb/typec.rst
@@ -114,8 +114,7 @@ the details during registration. The class offers the 
following API for
 registering/unregistering cables and their plugs:
 
 .. kernel-doc:: drivers/usb/typec/typec.c
-   :functions: typec_register_cable typec_unregister_cable typec_register_plug
-   typec_unregister_plug
+   :functions: typec_register_cable typec_unregister_cable typec_register_plug 
typec_unregister_plug
 
 The class will provide a handle to struct typec_cable and struct typec_plug if
 the registration is successful, or NULL if it isn't.
@@ -137,8 +136,7 @@ during connection of a partner or cable, the port driver 
must use the following
 APIs to report it to the class:
 
 .. kernel-doc:: drivers/usb/typec/typec.c
-   :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role
-   typec_set_pwr_opmode
+   :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role 
typec_set_pwr_opmode
 
 Alternate Modes
 ~~~
-- 
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

[PATCH] doc-rst: fix inline emphasis in unshare.rst

[Markus Heiser]

The asterisk of the pointer is interpreted as a start tag for inline
emphasis. Asterisks which are not Sphinx markup need to be quoted in
rst-files. This fixes the Sphinx warning:

Documentation/userspace-api/unshare.rst:108: WARNING: Inline emphasis 
start-string without end-string.

Signed-off-by: Markus Heiser 
---
 Documentation/userspace-api/unshare.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/userspace-api/unshare.rst 
b/Documentation/userspace-api/unshare.rst
index 737c192..877e90a 100644
--- a/Documentation/userspace-api/unshare.rst
+++ b/Documentation/userspace-api/unshare.rst
@@ -107,7 +107,7 @@ the benefits of this new feature can exceed its cost.
 
 unshare() reverses sharing that was done using clone(2) system call,
 so unshare() should have a similar interface as clone(2). That is,
-since flags in clone(int flags, void *stack) specifies what should
+since flags in clone(int flags, void \*stack) specifies what should
 be shared, similar flags in unshare(int flags) should specify
 what should be unshared. Unfortunately, this may appear to invert
 the meaning of the flags from the way they are used in clone(2).
-- 
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

[PATCH] core-api: remove an unexpected unident

[Markus Heiser]

As complained by Sphinx:
Documentation/core-api/assoc_array.rst:13: WARNING: Enumerated list 
ends without a blank line; unexpected unindent.

This was already addressed, but not really fixed in 2ba90ccca7.

Signed-off-by: Markus Heiser 
---
 Documentation/core-api/assoc_array.rst | 5 -
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/core-api/assoc_array.rst 
b/Documentation/core-api/assoc_array.rst
index d83cfff..8231b91 100644
--- a/Documentation/core-api/assoc_array.rst
+++ b/Documentation/core-api/assoc_array.rst
@@ -10,7 +10,10 @@ properties:
 
 1. Objects are opaque pointers.  The implementation does not care where they
point (if anywhere) or what they point to (if anything).
-.. note:: Pointers to objects _must_ be zero in the least significant bit.
+
+   .. note::
+
+  Pointers to objects _must_ be zero in the least significant bit.
 
 2. Objects do not need to contain linkage blocks for use by the array.  This
permits an object to be located in multiple arrays simultaneously.
-- 
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

[PATCH V4] cfg80211: add request id to cfg80211_sched_scan_*() api

[Markus Heiser]

Hi Arend,

I guess there is a typo in your kernel-doc comment [1]:


modified   include/net/cfg80211.h
@@ -1666,6 +1666,7 @@ struct cfg80211_bss_select_adjust {
  * (others are filtered out).
  * If ommited, all results are passed.
  * @n_match_sets: number of match sets
+ * @results_wk: worker for processing results notification.
-

I'am not familiar with the implementation, but as far as I can see, there
is no results_wk in the struct ... and you added report_results (see below)
which needs a documentation.


  * @wiphy: the wiphy this was for
  * @dev: the interface
  * @scan_start: start time of the scheduled scan
@@ -1726,6 +1727,7 @@ struct cfg80211_sched_scan_request {
struct wiphy *wiphy;
struct net_device *dev;
unsigned long scan_start;
+   bool report_results;
struct rcu_head rcu_head;
u32 owner_nlportid;
bool nl_owner_dead;
@@ -4564,31 +4566,34 @@ void cfg80211_scan_done(struct cfg80211_scan_request 
*request,


Here is what I get, when compiling the documentation:

  make DOCBOOKS= cleandocs htmldocs

./include/net/cfg80211.h:1738: warning: No description found for parameter 
'report_results'
./include/net/cfg80211.h:1738: warning: Excess struct/union/enum/typedef member 
'results_wk' description in 'cfg80211_sched_scan_request'

Can you please look at this / Thanks a lot!

-- Markus --

[1] https://www.spinics.net/lists/linux-wireless/msg161889.html--
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 03/17] doc: ReSTify IMA-templates.txt

[Kees Cook]

Adjust IMA-templates.txt for ReST markup and add to the index for
security/, under the Kernel API Documentation.

Cc: Mimi Zohar 
Signed-off-by: Kees Cook 
---
 Documentation/security/00-INDEX|  2 -
 .../{IMA-templates.txt => IMA-templates.rst}   | 46 --
 Documentation/security/index.rst   |  4 +-
 3 files changed, 29 insertions(+), 23 deletions(-)
 rename Documentation/security/{IMA-templates.txt => IMA-templates.rst} (72%)

diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 45c82fd3e9d3..414235c1fcfc 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -22,5 +22,3 @@ keys.txt
- description of the kernel key retention service.
 tomoyo.txt
- documentation on the TOMOYO Linux Security Module.
-IMA-templates.txt
-   - documentation on the template management mechanism for IMA.
diff --git a/Documentation/security/IMA-templates.txt 
b/Documentation/security/IMA-templates.rst
similarity index 72%
rename from Documentation/security/IMA-templates.txt
rename to Documentation/security/IMA-templates.rst
index 839b5dad9226..2cd0e273cc9a 100644
--- a/Documentation/security/IMA-templates.txt
+++ b/Documentation/security/IMA-templates.rst
@@ -1,9 +1,12 @@
-   IMA Template Management Mechanism
+=
+IMA Template Management Mechanism
+=
 
 
- INTRODUCTION 
+Introduction
+
 
-The original 'ima' template is fixed length, containing the filedata hash
+The original ``ima`` template is fixed length, containing the filedata hash
 and pathname. The filedata hash is limited to 20 bytes (md5/sha1).
 The pathname is a null terminated string, limited to 255 characters.
 To overcome these limitations and to add additional file metadata, it is
@@ -28,61 +31,64 @@ a new data type, developers define the field identifier and 
implement
 two functions, init() and show(), respectively to generate and display
 measurement entries. Defining a new template descriptor requires
 specifying the template format (a string of field identifiers separated
-by the '|' character) through the 'ima_template_fmt' kernel command line
+by the ``|`` character) through the ``ima_template_fmt`` kernel command line
 parameter. At boot time, IMA initializes the chosen template descriptor
 by translating the format into an array of template fields structures taken
 from the set of the supported ones.
 
-After the initialization step, IMA will call ima_alloc_init_template()
+After the initialization step, IMA will call ``ima_alloc_init_template()``
 (new function defined within the patches for the new template management
 mechanism) to generate a new measurement entry by using the template
 descriptor chosen through the kernel configuration or through the newly
-introduced 'ima_template' and 'ima_template_fmt' kernel command line 
parameters.
+introduced ``ima_template`` and ``ima_template_fmt`` kernel command line 
parameters.
 It is during this phase that the advantages of the new architecture are
 clearly shown: the latter function will not contain specific code to handle
-a given template but, instead, it simply calls the init() method of the 
template
+a given template but, instead, it simply calls the ``init()`` method of the 
template
 fields associated to the chosen template descriptor and store the result
 (pointer to allocated data and data length) in the measurement entry structure.
 
 The same mechanism is employed to display measurements entries.
-The functions ima[_ascii]_measurements_show() retrieve, for each entry,
+The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry,
 the template descriptor used to produce that entry and call the show()
 method for each item of the array of template fields structures.
 
 
 
- SUPPORTED TEMPLATE FIELDS AND DESCRIPTORS 
+Supported Template Fields and Descriptors
+=
 
 In the following, there is the list of supported template fields
-('': description), that can be used to define new template
+``('': description)``, that can be used to define new template
 descriptors by adding their identifier to the format string
 (support for more data types will be added later):
 
  - 'd': the digest of the event (i.e. the digest of a measured file),
-calculated with the SHA1 or MD5 hash algorithm;
+   calculated with the SHA1 or MD5 hash algorithm;
  - 'n': the name of the event (i.e. the file name), with size up to 255 bytes;
  - 'd-ng': the digest of the event, calculated with an arbitrary hash
-   algorithm (field format: [:]digest, where the digest
-   prefix is shown only if the hash algorithm is not SHA1 or MD5);
+   algorithm (field format: [:]digest, where the digest
+   prefix is shown only if the hash algorithm is not SHA1 or MD5);
 

[PATCH 04/17] doc: ReSTify credentials.txt

[Kees Cook]

This updates the credentials API documentation to ReST markup and moves
it under the security subsection of kernel API documentation.

Cc: David Howells 
Signed-off-by: Kees Cook 
---
 Documentation/security/00-INDEX|   2 -
 .../security/{credentials.txt => credentials.rst}  | 275 ++---
 Documentation/security/index.rst   |   1 +
 include/linux/cred.h   |   2 +-
 kernel/cred.c  |   2 +-
 5 files changed, 127 insertions(+), 155 deletions(-)
 rename Documentation/security/{credentials.txt => credentials.rst} (72%)

diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 414235c1fcfc..c4df62a9ae5b 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -10,8 +10,6 @@ Yama.txt
- documentation on the Yama Linux Security Module.
 apparmor.txt
- documentation on the AppArmor security extension.
-credentials.txt
-   - documentation about credentials in Linux.
 keys-ecryptfs.txt
- description of the encryption keys for the ecryptfs filesystem.
 keys-request-key.txt
diff --git a/Documentation/security/credentials.txt 
b/Documentation/security/credentials.rst
similarity index 72%
rename from Documentation/security/credentials.txt
rename to Documentation/security/credentials.rst
index 86257052e31a..038a7e19eff9 100644
--- a/Documentation/security/credentials.txt
+++ b/Documentation/security/credentials.rst
@@ -1,38 +1,18 @@
-
-CREDENTIALS IN LINUX
-
+
+Credentials in Linux
+
 
 By: David Howells 
 
-Contents:
-
- (*) Overview.
-
- (*) Types of credentials.
-
- (*) File markings.
-
- (*) Task credentials.
+.. contents:: :local:
 
- - Immutable credentials.
- - Accessing task credentials.
- - Accessing another task's credentials.
- - Altering credentials.
- - Managing credentials.
-
- (*) Open file credentials.
-
- (*) Overriding the VFS's use of credentials.
-
-
-
-OVERVIEW
+Overview
 
 
 There are several parts to the security check performed by Linux when one
 object acts upon another:
 
- (1) Objects.
+ 1. Objects.
 
  Objects are things in the system that may be acted upon directly by
  userspace programs.  Linux has a variety of actionable objects, including:
@@ -48,7 +28,7 @@ object acts upon another:
  As a part of the description of all these objects there is a set of
  credentials.  What's in the set depends on the type of object.
 
- (2) Object ownership.
+ 2. Object ownership.
 
  Amongst the credentials of most objects, there will be a subset that
  indicates the ownership of that object.  This is used for resource
@@ -57,7 +37,7 @@ object acts upon another:
  In a standard UNIX filesystem, for instance, this will be defined by the
  UID marked on the inode.
 
- (3) The objective context.
+ 3. The objective context.
 
  Also amongst the credentials of those objects, there will be a subset that
  indicates the 'objective context' of that object.  This may or may not be
@@ -67,7 +47,7 @@ object acts upon another:
  The objective context is used as part of the security calculation that is
  carried out when an object is acted upon.
 
- (4) Subjects.
+ 4. Subjects.
 
  A subject is an object that is acting upon another object.
 
@@ -77,10 +57,10 @@ object acts upon another:
 
  Objects other than tasks may under some circumstances also be subjects.
  For instance an open file may send SIGIO to a task using the UID and EUID
- given to it by a task that called fcntl(F_SETOWN) upon it.  In this case,
+ given to it by a task that called ``fcntl(F_SETOWN)`` upon it.  In this 
case,
  the file struct will have a subjective context too.
 
- (5) The subjective context.
+ 5. The subjective context.
 
  A subject has an additional interpretation of its credentials.  A subset
  of its credentials forms the 'subjective context'.  The subjective context
@@ -92,7 +72,7 @@ object acts upon another:
  from the real UID and GID that normally form the objective context of the
  task.
 
- (6) Actions.
+ 6. Actions.
 
  Linux has a number of actions available that a subject may perform upon an
  object.  The set of actions available depends on the nature of the subject
@@ -101,7 +81,7 @@ object acts upon another:
  Actions include reading, writing, creating and deleting files; forking or
  signalling and tracing tasks.
 
- (7) Rules, access control lists and security calculations.
+ 7. Rules, access control lists and security calculations.
 
  When a subject acts upon an object, a security calculation is made.  This
  involves taking the subjective context, the 

[PATCH 06/17] doc: security: minor cleanups to build kernel-doc

[Kees Cook]

These fixes were needed to parse lsm_hooks.h kernel-doc. More work is
needed, but this is the first step.

Cc: Casey Schaufler 
Signed-off-by: Kees Cook 
---
 include/linux/lsm_hooks.h | 25 -
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h
index 080f34e66017..a1eeaf603d2f 100644
--- a/include/linux/lsm_hooks.h
+++ b/include/linux/lsm_hooks.h
@@ -29,6 +29,8 @@
 #include 
 
 /**
+ * union security_list_options - Linux Security Module hook function list
+ *
  * Security hooks for program execution operations.
  *
  * @bprm_set_creds:
@@ -193,8 +195,8 @@
  * @value will be set to the allocated attribute value.
  * @len will be set to the length of the value.
  * Returns 0 if @name and @value have been successfully set,
- * -EOPNOTSUPP if no security attribute is needed, or
- * -ENOMEM on memory allocation failure.
+ * -EOPNOTSUPP if no security attribute is needed, or
+ * -ENOMEM on memory allocation failure.
  * @inode_create:
  * Check permission to create a regular file.
  * @dir contains inode structure of the parent of the new file.
@@ -510,8 +512,7 @@
  * process @tsk.  Note that this hook is sometimes called from interrupt.
  * Note that the fown_struct, @fown, is never outside the context of a
  * struct file, so the file structure (and associated security information)
- * can always be obtained:
- * container_of(fown, struct file, f_owner)
+ * can always be obtained: container_of(fown, struct file, f_owner)
  * @tsk contains the structure of task receiving signal.
  * @fown contains the file owner information.
  * @sig is the signal that will be sent.  When 0, kernel sends SIGIO.
@@ -521,7 +522,7 @@
  * to receive an open file descriptor via socket IPC.
  * @file contains the file structure being received.
  * Return 0 if permission is granted.
- * @file_open
+ * @file_open:
  * Save open-time permission checking state for later use upon
  * file_permission, and recheck access if anything has changed
  * since inode_permission.
@@ -1143,7 +1144,7 @@
  * @sma contains the semaphore structure.  May be NULL.
  * @cmd contains the operation to be performed.
  * Return 0 if permission is granted.
- * @sem_semop
+ * @sem_semop:
  * Check permissions before performing operations on members of the
  * semaphore set @sma.  If the @alter flag is nonzero, the semaphore set
  * may be modified.
@@ -1153,20 +1154,20 @@
  * @alter contains the flag indicating whether changes are to be made.
  * Return 0 if permission is granted.
  *
- * @binder_set_context_mgr
+ * @binder_set_context_mgr:
  * Check whether @mgr is allowed to be the binder context manager.
  * @mgr contains the task_struct for the task being registered.
  * Return 0 if permission is granted.
- * @binder_transaction
+ * @binder_transaction:
  * Check whether @from is allowed to invoke a binder transaction call
  * to @to.
  * @from contains the task_struct for the sending task.
  * @to contains the task_struct for the receiving task.
- * @binder_transfer_binder
+ * @binder_transfer_binder:
  * Check whether @from is allowed to transfer a binder reference to @to.
  * @from contains the task_struct for the sending task.
  * @to contains the task_struct for the receiving task.
- * @binder_transfer_file
+ * @binder_transfer_file:
  * Check whether @from is allowed to transfer @file to @to.
  * @from contains the task_struct for the sending task.
  * @file contains the struct file being transferred.
@@ -1214,7 +1215,7 @@
  * @cred contains the credentials to use.
  * @ns contains the user namespace we want the capability in
  * @cap contains the capability .
- * @audit: Whether to write an audit message or not
+ * @audit contains whether to write an audit message or not
  * Return 0 if the capability is granted for @tsk.
  * @syslog:
  * Check permission before accessing the kernel message ring or changing
@@ -1336,9 +1337,7 @@
  * @inode we wish to get the security context of.
  * @ctx is a pointer in which to place the allocated security context.
  * @ctxlen points to the place to put the length of @ctx.
- * This is the main security structure.
  */
-
 union security_list_options {
int (*binder_set_context_mgr)(struct task_struct *mgr);
int (*binder_transaction)(struct task_struct *from,
-- 
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

[PATCH 02/17] doc: ReSTify no_new_privs.txt

[Kees Cook]

This updates no_new_privs documentation to ReST markup and adds it to
the user-space API documentation.

Signed-off-by: Kees Cook 
---
 Documentation/userspace-api/index.rst  |  1 +
 .../no_new_privs.rst}  | 44 --
 2 files changed, 26 insertions(+), 19 deletions(-)
 rename Documentation/{prctl/no_new_privs.txt => 
userspace-api/no_new_privs.rst} (54%)

diff --git a/Documentation/userspace-api/index.rst 
b/Documentation/userspace-api/index.rst
index 15ff12342db8..7b2eb1b7d4ca 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -16,6 +16,7 @@ place where this information is gathered.
 .. toctree::
:maxdepth: 2
 
+   no_new_privs
seccomp_filter
unshare
 
diff --git a/Documentation/prctl/no_new_privs.txt 
b/Documentation/userspace-api/no_new_privs.rst
similarity index 54%
rename from Documentation/prctl/no_new_privs.txt
rename to Documentation/userspace-api/no_new_privs.rst
index f7be84fba910..d060ea217ea1 100644
--- a/Documentation/prctl/no_new_privs.txt
+++ b/Documentation/userspace-api/no_new_privs.rst
@@ -1,3 +1,7 @@
+==
+No New Privileges Flag
+==
+
 The execve system call can grant a newly-started program privileges that
 its parent did not have.  The most obvious examples are setuid/setgid
 programs and file capabilities.  To prevent the parent program from
@@ -5,53 +9,55 @@ gaining these privileges as well, the kernel and user code 
must be
 careful to prevent the parent from doing anything that could subvert the
 child.  For example:
 
- - The dynamic loader handles LD_* environment variables differently if
+ - The dynamic loader handles ``LD_*`` environment variables differently if
a program is setuid.
 
  - chroot is disallowed to unprivileged processes, since it would allow
-   /etc/passwd to be replaced from the point of view of a process that
+   ``/etc/passwd`` to be replaced from the point of view of a process that
inherited chroot.
 
  - The exec code has special handling for ptrace.
 
-These are all ad-hoc fixes.  The no_new_privs bit (since Linux 3.5) is a
+These are all ad-hoc fixes.  The ``no_new_privs`` bit (since Linux 3.5) is a
 new, generic mechanism to make it safe for a process to modify its
 execution environment in a manner that persists across execve.  Any task
-can set no_new_privs.  Once the bit is set, it is inherited across fork,
-clone, and execve and cannot be unset.  With no_new_privs set, execve
+can set ``no_new_privs``.  Once the bit is set, it is inherited across fork,
+clone, and execve and cannot be unset.  With ``no_new_privs`` set, ``execve()``
 promises not to grant the privilege to do anything that could not have
 been done without the execve call.  For example, the setuid and setgid
 bits will no longer change the uid or gid; file capabilities will not
 add to the permitted set, and LSMs will not relax constraints after
 execve.
 
-To set no_new_privs, use prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0).
+To set ``no_new_privs``, use::
+
+prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);
 
 Be careful, though: LSMs might also not tighten constraints on exec
-in no_new_privs mode.  (This means that setting up a general-purpose
-service launcher to set no_new_privs before execing daemons may
+in ``no_new_privs`` mode.  (This means that setting up a general-purpose
+service launcher to set ``no_new_privs`` before execing daemons may
 interfere with LSM-based sandboxing.)
 
-Note that no_new_privs does not prevent privilege changes that do not
-involve execve.  An appropriately privileged task can still call
-setuid(2) and receive SCM_RIGHTS datagrams.
+Note that ``no_new_privs`` does not prevent privilege changes that do not
+involve ``execve()``.  An appropriately privileged task can still call
+``setuid(2)`` and receive SCM_RIGHTS datagrams.
 
-There are two main use cases for no_new_privs so far:
+There are two main use cases for ``no_new_privs`` so far:
 
  - Filters installed for the seccomp mode 2 sandbox persist across
execve and can change the behavior of newly-executed programs.
Unprivileged users are therefore only allowed to install such filters
-   if no_new_privs is set.
+   if ``no_new_privs`` is set.
 
- - By itself, no_new_privs can be used to reduce the attack surface
+ - By itself, ``no_new_privs`` can be used to reduce the attack surface
available to an unprivileged user.  If everything running with a
-   given uid has no_new_privs set, then that uid will be unable to
+   given uid has ``no_new_privs`` set, then that uid will be unable to
escalate its privileges by directly attacking setuid, setgid, and
fcap-using binaries; it will need to compromise something without the
-   no_new_privs bit set first.
+   ``no_new_privs`` bit set first.
 
 In the future, other potentially dangerous kernel features could become
-available to unprivileged tasks if 

[PATCH 11/17] doc: ReSTify Yama.txt

[Kees Cook]

Adjusts for ReST markup and moves under LSM admin guide.

Signed-off-by: Kees Cook 
---
 .../Yama.txt => admin-guide/LSM/Yama.rst}  | 55 --
 Documentation/admin-guide/LSM/index.rst|  1 +
 Documentation/security/00-INDEX|  2 -
 MAINTAINERS|  1 +
 security/yama/Kconfig  |  3 +-
 5 files changed, 33 insertions(+), 29 deletions(-)
 rename Documentation/{security/Yama.txt => admin-guide/LSM/Yama.rst} (60%)

diff --git a/Documentation/security/Yama.txt 
b/Documentation/admin-guide/LSM/Yama.rst
similarity index 60%
rename from Documentation/security/Yama.txt
rename to Documentation/admin-guide/LSM/Yama.rst
index d9ee7d7a6c7f..13468ea696b7 100644
--- a/Documentation/security/Yama.txt
+++ b/Documentation/admin-guide/LSM/Yama.rst
@@ -1,13 +1,14 @@
+
+Yama
+
+
 Yama is a Linux Security Module that collects system-wide DAC security
 protections that are not handled by the core kernel itself. This is
-selectable at build-time with CONFIG_SECURITY_YAMA, and can be controlled
-at run-time through sysctls in /proc/sys/kernel/yama:
-
-- ptrace_scope
+selectable at build-time with ``CONFIG_SECURITY_YAMA``, and can be controlled
+at run-time through sysctls in ``/proc/sys/kernel/yama``:
 
-==
-
-ptrace_scope:
+ptrace_scope
+
 
 As Linux grows in popularity, it will become a larger target for
 malware. One particularly troubling weakness of the Linux process
@@ -25,47 +26,49 @@ exist and remain possible if ptrace is allowed to operate 
as before.
 Since ptrace is not commonly used by non-developers and non-admins, system
 builders should be allowed the option to disable this debugging system.
 
-For a solution, some applications use prctl(PR_SET_DUMPABLE, ...) to
+For a solution, some applications use ``prctl(PR_SET_DUMPABLE, ...)`` to
 specifically disallow such ptrace attachment (e.g. ssh-agent), but many
 do not. A more general solution is to only allow ptrace directly from a
 parent to a child process (i.e. direct "gdb EXE" and "strace EXE" still
-work), or with CAP_SYS_PTRACE (i.e. "gdb --pid=PID", and "strace -p PID"
+work), or with ``CAP_SYS_PTRACE`` (i.e. "gdb --pid=PID", and "strace -p PID"
 still work as root).
 
 In mode 1, software that has defined application-specific relationships
 between a debugging process and its inferior (crash handlers, etc),
-prctl(PR_SET_PTRACER, pid, ...) can be used. An inferior can declare which
-other process (and its descendants) are allowed to call PTRACE_ATTACH
+``prctl(PR_SET_PTRACER, pid, ...)`` can be used. An inferior can declare which
+other process (and its descendants) are allowed to call ``PTRACE_ATTACH``
 against it. Only one such declared debugging process can exists for
 each inferior at a time. For example, this is used by KDE, Chromium, and
 Firefox's crash handlers, and by Wine for allowing only Wine processes
 to ptrace each other. If a process wishes to entirely disable these ptrace
-restrictions, it can call prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)
+restrictions, it can call ``prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)``
 so that any otherwise allowed process (even those in external pid namespaces)
 may attach.
 
-The sysctl settings (writable only with CAP_SYS_PTRACE) are:
+The sysctl settings (writable only with ``CAP_SYS_PTRACE``) are:
 
-0 - classic ptrace permissions: a process can PTRACE_ATTACH to any other
+0 - classic ptrace permissions:
+a process can ``PTRACE_ATTACH`` to any other
 process running under the same uid, as long as it is dumpable (i.e.
 did not transition uids, start privileged, or have called
-prctl(PR_SET_DUMPABLE...) already). Similarly, PTRACE_TRACEME is
+``prctl(PR_SET_DUMPABLE...)`` already). Similarly, ``PTRACE_TRACEME`` is
 unchanged.
 
-1 - restricted ptrace: a process must have a predefined relationship
-with the inferior it wants to call PTRACE_ATTACH on. By default,
+1 - restricted ptrace:
+a process must have a predefined relationship
+with the inferior it wants to call ``PTRACE_ATTACH`` on. By default,
 this relationship is that of only its descendants when the above
 classic criteria is also met. To change the relationship, an
-inferior can call prctl(PR_SET_PTRACER, debugger, ...) to declare
-an allowed debugger PID to call PTRACE_ATTACH on the inferior.
-Using PTRACE_TRACEME is unchanged.
+inferior can call ``prctl(PR_SET_PTRACER, debugger, ...)`` to declare
+an allowed debugger PID to call ``PTRACE_ATTACH`` on the inferior.
+Using ``PTRACE_TRACEME`` is unchanged.
 
-2 - admin-only attach: only processes with CAP_SYS_PTRACE may use ptrace
-with PTRACE_ATTACH, or through children calling PTRACE_TRACEME.
+2 - admin-only attach:
+only processes with ``CAP_SYS_PTRACE`` may use ptrace
+with ``PTRACE_ATTACH``, or 

[PATCH 13/17] doc: ReSTify Smack.txt

[Kees Cook]

Adjusts for ReST markup and moves under LSM admin guide.

Cc: Casey Schaufler 
Signed-off-by: Kees Cook 
---
 .../Smack.txt => admin-guide/LSM/Smack.rst}| 273 ++---
 Documentation/admin-guide/LSM/index.rst|   1 +
 Documentation/security/00-INDEX|   2 -
 MAINTAINERS|   2 +-
 4 files changed, 191 insertions(+), 87 deletions(-)
 rename Documentation/{security/Smack.txt => admin-guide/LSM/Smack.rst} (85%)

diff --git a/Documentation/security/Smack.txt 
b/Documentation/admin-guide/LSM/Smack.rst
similarity index 85%
rename from Documentation/security/Smack.txt
rename to Documentation/admin-guide/LSM/Smack.rst
index 945cc633d883..6a5826a13aea 100644
--- a/Documentation/security/Smack.txt
+++ b/Documentation/admin-guide/LSM/Smack.rst
@@ -1,3 +1,6 @@
+=
+Smack
+=
 
 
 "Good for you, you've decided to clean the elevator!"
@@ -14,6 +17,7 @@ available to determine which is best suited to the problem
 at hand.
 
 Smack consists of three major components:
+
 - The kernel
 - Basic utilities, which are helpful but not required
 - Configuration data
@@ -39,16 +43,24 @@ The current git repository for Smack user space is:
 This should make and install on most modern distributions.
 There are five commands included in smackutil:
 
-chsmack- display or set Smack extended attribute values
-smackctl   - load the Smack access rules
-smackaccess - report if a process with one label has access
-  to an object with another
+chsmack:
+   display or set Smack extended attribute values
+
+smackctl:
+   load the Smack access rules
+
+smackaccess:
+   report if a process with one label has access
+   to an object with another
 
 These two commands are obsolete with the introduction of
 the smackfs/load2 and smackfs/cipso2 interfaces.
 
-smackload  - properly formats data for writing to smackfs/load
-smackcipso - properly formats data for writing to smackfs/cipso
+smackload:
+   properly formats data for writing to smackfs/load
+
+smackcipso:
+   properly formats data for writing to smackfs/cipso
 
 In keeping with the intent of Smack, configuration data is
 minimal and not strictly required. The most important
@@ -56,15 +68,15 @@ configuration step is mounting the smackfs pseudo 
filesystem.
 If smackutil is installed the startup script will take care
 of this, but it can be manually as well.
 
-Add this line to /etc/fstab:
+Add this line to ``/etc/fstab``::
 
 smackfs /sys/fs/smackfs smackfs defaults 0 0
 
-The /sys/fs/smackfs directory is created by the kernel.
+The ``/sys/fs/smackfs`` directory is created by the kernel.
 
 Smack uses extended attributes (xattrs) to store labels on filesystem
 objects. The attributes are stored in the extended attribute security
-name space. A process must have CAP_MAC_ADMIN to change any of these
+name space. A process must have ``CAP_MAC_ADMIN`` to change any of these
 attributes.
 
 The extended attributes that Smack uses are:
@@ -73,14 +85,17 @@ SMACK64
Used to make access control decisions. In almost all cases
the label given to a new filesystem object will be the label
of the process that created it.
+
 SMACK64EXEC
The Smack label of a process that execs a program file with
this attribute set will run with this attribute's value.
+
 SMACK64MMAP
Don't allow the file to be mmapped by a process whose Smack
label does not allow all of the access permitted to a process
with the label contained in this attribute. This is a very
specific use case for shared libraries.
+
 SMACK64TRANSMUTE
Can only have the value "TRUE". If this attribute is present
on a directory when an object is created in the directory and
@@ -89,27 +104,29 @@ SMACK64TRANSMUTE
gets the label of the directory instead of the label of the
creating process. If the object being created is a directory
the SMACK64TRANSMUTE attribute is set as well.
+
 SMACK64IPIN
This attribute is only available on file descriptors for sockets.
Use the Smack label in this attribute for access control
decisions on packets being delivered to this socket.
+
 SMACK64IPOUT
This attribute is only available on file descriptors for sockets.
Use the Smack label in this attribute for access control
decisions on packets coming from this socket.
 
-There are multiple ways to set a Smack label on a file:
+There are multiple ways to set a Smack label on a file::
 
 # attr -S -s SMACK64 -V "value" path
 # chsmack -a value path
 
 A process can see the Smack label it is running with by
-reading /proc/self/attr/current. A process with CAP_MAC_ADMIN
+reading ``/proc/self/attr/current``. A process with ``CAP_MAC_ADMIN``
 can set the process Smack by writing there.
 
 Most Smack configuration is 

[PATCH 14/17] doc: ReSTify keys.txt

[Kees Cook]

This creates a new section in the security development index for kernel
keys, and adjusts for ReST markup.

Cc: David Howells 
Signed-off-by: Kees Cook 
---
 Documentation/crypto/asymmetric-keys.txt   |   2 +-
 Documentation/security/00-INDEX|   2 -
 Documentation/security/index.rst   |   1 +
 Documentation/security/{keys.txt => keys/core.rst} | 314 ++---
 Documentation/security/keys/index.rst  |   8 +
 MAINTAINERS|   2 +-
 include/linux/key.h|   2 +-
 7 files changed, 163 insertions(+), 168 deletions(-)
 rename Documentation/security/{keys.txt => keys/core.rst} (89%)
 create mode 100644 Documentation/security/keys/index.rst

diff --git a/Documentation/crypto/asymmetric-keys.txt 
b/Documentation/crypto/asymmetric-keys.txt
index 5ad6480e3fb9..b82b6ad48488 100644
--- a/Documentation/crypto/asymmetric-keys.txt
+++ b/Documentation/crypto/asymmetric-keys.txt
@@ -265,7 +265,7 @@ mandatory:
 
  The caller passes a pointer to the following struct with all of the fields
  cleared, except for data, datalen and quotalen [see
- Documentation/security/keys.txt].
+ Documentation/security/keys/core.rst].
 
struct key_preparsed_payload {
char*description;
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index cdb2294ec047..a840095bb11c 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -6,5 +6,3 @@ keys-request-key.txt
- description of the kernel key request service.
 keys-trusted-encrypted.txt
- info on the Trusted and Encrypted keys in the kernel key ring service.
-keys.txt
-   - description of the kernel key retention service.
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 94ba1cfc01c5..298a94a33f05 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -7,6 +7,7 @@ Security Documentation
 
credentials
IMA-templates
+   keys/index
LSM
self-protection
tpm/index
diff --git a/Documentation/security/keys.txt 
b/Documentation/security/keys/core.rst
similarity index 89%
rename from Documentation/security/keys.txt
rename to Documentation/security/keys/core.rst
index cd5019934d7f..0d831a7afe4f 100644
--- a/Documentation/security/keys.txt
+++ b/Documentation/security/keys/core.rst
@@ -1,6 +1,6 @@
-
-KERNEL KEY RETENTION SERVICE
-
+
+Kernel Key Retention Service
+
 
 This service allows cryptographic keys, authentication tokens, cross-domain
 user mappings, and similar to be cached in the kernel for the use of
@@ -29,8 +29,7 @@ This document has the following sections:
- Garbage collection
 
 
-
-KEY OVERVIEW
+Key Overview
 
 
 In this context, keys represent units of cryptographic data, authentication
@@ -47,14 +46,14 @@ Each key has a number of attributes:
- State.
 
 
- (*) Each key is issued a serial number of type key_serial_t that is unique for
+  *  Each key is issued a serial number of type key_serial_t that is unique for
  the lifetime of that key. All serial numbers are positive non-zero 32-bit
  integers.
 
  Userspace programs can use a key's serial numbers as a way to gain access
  to it, subject to permission checking.
 
- (*) Each key is of a defined "type". Types must be registered inside the
+  *  Each key is of a defined "type". Types must be registered inside the
  kernel by a kernel service (such as a filesystem) before keys of that type
  can be added or used. Userspace programs cannot define new types directly.
 
@@ -64,18 +63,18 @@ Each key has a number of attributes:
  Should a type be removed from the system, all the keys of that type will
  be invalidated.
 
- (*) Each key has a description. This should be a printable string. The key
+  *  Each key has a description. This should be a printable string. The key
  type provides an operation to perform a match between the description on a
  key and a criterion string.
 
- (*) Each key has an owner user ID, a group ID and a permissions mask. These
+  *  Each key has an owner user ID, a group ID and a permissions mask. These
  are used to control what a process may do to a key from userspace, and
  whether a kernel service will be able to find the key.
 
- (*) Each key can be set to expire at a specific time by the key type's
+  *  Each key can be set to expire at a specific time by the key type's
  instantiation function. Keys can also be immortal.
 
- (*) Each key can have a payload. This is a quantity of data that represent the
+  *  Each key can have a payload. This is a 

[PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line

[Mauro Carvalho Chehab]

Typo:
ored -> ordered

While here, group the :: with the previous paragraph, in order
to make it visually better when reading as a text file.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/driver-api/mtdnand.rst | 24 +++-
 1 file changed, 7 insertions(+), 17 deletions(-)

diff --git a/Documentation/driver-api/mtdnand.rst 
b/Documentation/driver-api/mtdnand.rst
index 8723175f955e..e670f8b15a79 100644
--- a/Documentation/driver-api/mtdnand.rst
+++ b/Documentation/driver-api/mtdnand.rst
@@ -843,10 +843,8 @@ Chip option constants
 Constants for chip id table
 ~~~
 
-These constants are defined in nand.h. They are ored together to
-describe the chip functionality.
-
-::
+These constants are defined in nand.h. They are ordered together to
+describe the chip functionality::
 
 /* Buswitdh is 16 bit */
 #define NAND_BUSWIDTH_160x0002
@@ -867,10 +865,8 @@ describe the chip functionality.
 Constants for runtime options
 ~
 
-These constants are defined in nand.h. They are ored together to
-describe the functionality.
-
-::
+These constants are defined in nand.h. They are ordered together to
+describe the functionality::
 
 /* The hw ecc generator provides a syndrome instead a ecc value on read
  * This can only work if we have the ecc bytes directly behind the
@@ -881,9 +877,7 @@ describe the functionality.
 ECC selection constants
 ---
 
-Use these constants to select the ECC algorithm.
-
-::
+Use these constants to select the ECC algorithm::
 
 /* No ECC. Usage is not recommended ! */
 #define NAND_ECC_NONE   0
@@ -903,9 +897,7 @@ Hardware control related constants
 --
 
 These constants describe the requested hardware access function when the
-boardspecific hardware control function is called
-
-::
+boardspecific hardware control function is called::
 
 /* Select the chip by setting nCE to low */
 #define NAND_CTL_SETNCE 1
@@ -929,9 +921,7 @@ Bad block table related constants
 -
 
 These constants describe the options used for bad block table
-descriptors.
-
-::
+descriptors::
 
 /* Options for the bad block table descriptors */
 
-- 
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 5/5] docs-rst: convert sh book to ReST

[Mauro Carvalho Chehab]

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/sh.tmpl  | 105 -
 Documentation/conf.py  |   2 +
 Documentation/index.rst|  11 +
 Documentation/sh/index.rst |  59 +++
 5 files changed, 73 insertions(+), 108 deletions(-)
 delete mode 100644 Documentation/DocBook/sh.tmpl
 create mode 100644 Documentation/sh/index.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 226e5e9fc801..efba7f980895 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -6,9 +6,7 @@
 # To add a new book the only step required is to add the book to the
 # list of DOCBOOKS.
 
-DOCBOOKS := \
-   lsm.xml \
-   sh.xml
+DOCBOOKS := lsm.xml
 
 ifeq ($(DOCBOOKS),)
 
diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl
deleted file mode 100644
index 4a38f604fa66..
--- a/Documentation/DocBook/sh.tmpl
+++ /dev/null
@@ -1,105 +0,0 @@
-
-http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd; []>
-
-
- 
-  SuperH Interfaces Guide
-  
-  
-   
-Paul
-Mundt
-
- 
-  let...@linux-sh.org
- 
-
-   
-  
-
-  
-   2008-2010
-   Paul Mundt
-  
-  
-   2008-2010
-   Renesas Technology Corp.
-  
-  
-   2010
-   Renesas Electronics Corp.
-  
-
-  
-   
- 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.
-   
-  
- 
-
-
-
-  
-Memory Management
-
-SH-4
-  
-Store Queue API
-!Earch/sh/kernel/cpu/sh4/sq.c
-  
-
-
-  SH-5
-  
-   TLB Interfaces
-!Iarch/sh/mm/tlb-sh5.c
-!Iarch/sh/include/asm/tlb_64.h
-  
-
-  
-  
-Machine Specific Interfaces
-
-  mach-dreamcast
-!Iarch/sh/boards/mach-dreamcast/rtc.c
-
-
-  mach-x3proto
-!Earch/sh/boards/mach-x3proto/ilsel.c
-
-  
-  
-Busses
-
-  SuperHyway
-!Edrivers/sh/superhyway/superhyway.c
-
-
-
-  Maple
-!Edrivers/sh/maple/maple.c
-
-  
-
diff --git a/Documentation/conf.py b/Documentation/conf.py
index dfe14f7525d0..77d47bb1df1d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -375,6 +375,8 @@ latex_documents = [
  'The kernel development community', 'manual'),
 ('security/index', 'security.tex', 'The kernel security subsystem manual',
  'The kernel development community', 'manual'),
+('sh/index', 'sh.tex', 'SuperH architecture implementation manual',
+ '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',
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 25c4da41da6b..e9017bb3a6ce 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -76,6 +76,17 @@ needed).
crypto/index
filesystems/index
 
+Architecture-specific documentation
+---
+
+These books provide programming details about architecture-specific
+implementation.
+
+.. toctree::
+   :maxdepth: 2
+
+   sh/index
+
 Korean translations
 ---
 
diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
new file mode 100644
index ..bc8db7ba894a
--- /dev/null
+++ b/Documentation/sh/index.rst
@@ -0,0 +1,59 @@
+===
+SuperH Interfaces Guide
+===
+
+:Author: Paul Mundt
+
+Memory Management
+=
+
+SH-4
+
+
+Store Queue API
+~~~
+
+.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
+   :export:
+
+SH-5
+
+
+TLB Interfaces
+~~
+
+.. kernel-doc:: arch/sh/mm/tlb-sh5.c
+   :internal:
+
+.. kernel-doc:: arch/sh/include/asm/tlb_64.h
+   :internal:
+
+Machine Specific Interfaces
+===
+
+mach-dreamcast
+--
+
+.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
+   :internal:
+
+mach-x3proto
+
+
+.. kernel-doc:: 

[PATCH 2/5] docs-rst: convert mtdnand book to ReST

[Mauro Carvalho Chehab]

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

The tables were manually adjusted to fit into 80 columns.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/DocBook/Makefile   |1 -
 Documentation/DocBook/mtdnand.tmpl   | 1291 --
 Documentation/driver-api/index.rst   |1 +
 Documentation/driver-api/mtdnand.rst | 1020 +++
 4 files changed, 1021 insertions(+), 1292 deletions(-)
 delete mode 100644 Documentation/DocBook/mtdnand.tmpl
 create mode 100644 Documentation/driver-api/mtdnand.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 0a82f6253682..226e5e9fc801 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -8,7 +8,6 @@
 
 DOCBOOKS := \
lsm.xml \
-   mtdnand.xml \
sh.xml
 
 ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/mtdnand.tmpl 
b/Documentation/DocBook/mtdnand.tmpl
deleted file mode 100644
index b442921bca54..
--- a/Documentation/DocBook/mtdnand.tmpl
+++ /dev/null
@@ -1,1291 +0,0 @@
-
-http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd; []>
-
-
- 
-  MTD NAND Driver Programming Interface
-  
-  
-   
-Thomas
-Gleixner
-
- 
-  t...@linutronix.de
- 
-
-   
-  
-
-  
-   2004
-   Thomas Gleixner
-  
-
-  
-   
- 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
-  
-   The generic NAND driver supports almost all NAND and AG-AND based
-   chips and connects them to the Memory Technology Devices (MTD)
-   subsystem of the Linux Kernel.
-  
-  
-   This documentation is provided for developers who want to implement
-   board drivers or filesystem drivers suitable for NAND devices.
-  
-  
-  
-  
- Known Bugs And Assumptions
-  
-   None.   
-  
-  
-
-  
- Documentation hints
- 
- The function and structure docs are autogenerated. Each function and 
- struct member has a short description which is marked with an [XXX] 
identifier.
- The following chapters explain the meaning of those identifiers.
- 
- 
-   Function identifiers [XXX]
-   
-   The functions are marked with [XXX] identifiers in the short
-   comment. The identifiers explain the usage and scope of the
-   functions. Following identifiers are used:
-   
-   
-   
-   [MTD Interface]
-   These functions provide the interface to the MTD kernel API. 
-   They are not replaceable and provide functionality
-   which is complete hardware independent.
-   
-   
-   [NAND Interface]
-   These functions are exported and provide the interface to the 
NAND kernel API. 
-   
-   
-   [GENERIC]
-   Generic functions are not replaceable and provide functionality
-   which is complete hardware independent.
-   
-   
-   [DEFAULT]
-   Default functions provide hardware related functionality which 
is suitable
-   for most of the implementations. These functions can be 
replaced by the
-   board driver if necessary. Those functions are called via 
pointers in the
-   NAND chip description structure. The board driver can set the 
functions which
-   should be replaced by board dependent functions before calling 
nand_scan().
-   If the function pointer is NULL on entry to nand_scan() then 
the pointer
-   is set to the default function which is suitable for the 
detected chip type.
-   
-   
- 
- 
-   Struct member identifiers [XXX]
-   
-   The struct members are marked with [XXX] identifiers in the 
-   comment. The identifiers explain the usage and scope of the
-   members. Following identifiers are used:
-   
-   
-   
-   [INTERN]
-   These members are for NAND driver internal use only and must 
not be
-   

Re: [PATCH 01/36] docs-rst: convert kernel-hacking to ReST

[Mauro Carvalho Chehab]

Em Fri, 12 May 2017 18:35:29 +0200
Markus Heiser  escreveu:

> 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 ;)

There are some functions there that are only mentioned at the title,
like: local_bh_disable().

IMHO, it is a good idea to add a cross-reference to those, as it
helps the reader to get further information if needed. So, except if
this would cause Sphinx to crash, I prefer to keep the references.

What I did, instead, on patch 02/36 is to move all header references
to be outside the title:

+:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()`
+---
+
+Defined in ``include/asm/byteorder.h``
 

With reduces the displayed title to something reasonable.

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

[Mauro Carvalho Chehab]

Em Fri, 12 May 2017 15:19:17 -0700
Darren Hart  escreveu:

> 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..

Very few kerneldoc markups need changes due to ReST introduction, and
usually is just whitespace/blank lines adjustment. Ok, someone could
try to improve the script to make it smarter[1], but, on my experiences
addressing it, usually doing the required changes make it visually
better on both C file and on PDF/LaTeX/HTML outputs.

[1] probably rewriting the entire script to work more like a lexical
interpreter than a bunch of rejex expressions.

> 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.

IMHO, the best thing with kerneldoc is that it helps to keep the
documentation updated, as it warns when someone change the function
arguments without updating the comments.

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 03/36] docs-rst: convert kernel-locking to ReST

[Mauro Carvalho Chehab]

Em Fri, 12 May 2017 18:57:13 +0200
Markus Heiser  escreveu:

> 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

Thanks for review!

I'll fold it with the enclosed path.

diff --git a/Documentation/conf.py b/Documentation/conf.py
index bfa95c881956..0ce8001a50b6 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -352,7 +352,7 @@ latex_documents = [
  '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',
+('kernel-hacking/index', 'kernel-hacking.tex', 'Kernel Hacking Guides',
  'The kernel development community', 'manual'),
 ('process/index', 'development-process.tex', 'Linux Kernel Development 
Documentation',
  'The kernel development community', 'manual'),
diff --git a/Documentation/kernel-hacking/conf.py 
b/Documentation/kernel-hacking/conf.py
index 4facca74a6f0..3d8acf0f33ad 100644
--- a/Documentation/kernel-hacking/conf.py
+++ b/Documentation/kernel-hacking/conf.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8; mode: python -*-
 
-project = "Unreliable Guide To Hacking The Linux Kernel"
+project = "Kernel Hacking Guides"
 
 tags.add("subproject")
 
diff --git a/Documentation/kernel-hacking/index.rst 
b/Documentation/kernel-hacking/index.rst
index b3d8fe56d310..fcb0eda3cca3 100644
--- a/Documentation/kernel-hacking/index.rst
+++ b/Documentation/kernel-hacking/index.rst
@@ -1,3 +1,7 @@
+=
+Kernel Hacking Guides
+=
+
 .. toctree::
:maxdepth: 2
 
diff --git a/Documentation/kernel-hacking/hacking.rst 
b/Documentation/kernel-hacking/hacking.rst
index 1a456b60a7cf..58831decd5ae 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -764,7 +764,7 @@ Some favorites from browsing the source. Feel free to add 
to this list.
  #define PTR_ERR(ptr)((long)(ptr))
  #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))
 
-``arch/x86/include/asm/uaccess_32.h:``::
+``arch/x86/include/asm/uaccess_32.h``::
 
 #define copy_to_user(to,from,n) \
 (__builtin_constant_p(n) ?  \
@@ -772,7 +772,7 @@ Some favorites from browsing the source. Feel free to add 
to this list.
  __generic_copy_to_user((to),(from),(n)))
 
 
-``arch/sparc/kernel/head.S:``::
+``arch/sparc/kernel/head.S``::
 
 /*
  * Sun people can't spell worth damn. "compatability" indeed.
@@ -791,7 +791,7 @@ Some favorites from browsing the source. Feel free to add 
to this list.
 .asciz "compatible"
 
 
-``arch/sparc/lib/checksum.S:``::
+``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


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 21/36] fs: locks: Fix some troubles at kernel-doc comments

[Mauro Carvalho Chehab]

Hi Jeff,

Em Fri, 12 May 2017 10:02:56 -0400
Jeff Layton  escreveu:

> 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?

Feel free to pick it, if it works best for you.

> Reviewed-by: Jeff Layton 


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 26/36] libata.rst: add c function and struct cross-references

[kbuild test robot]

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'
   include/linux/jbd2.h:1050: warning: No description found for parameter 
'j_chksum_driver'
   include/linux/jbd2.h:1050: warning: No description found for parameter 
'j_csum_seed'
   fs/jbd2/transaction.c:511: warning: No description found for parameter 'type'
   fs/jbd2/transaction.c:511: warning: No description found for parameter 
'line_no'
   fs/jbd2/transaction.c:641: warning: No description found for parameter 
'gfp_mask'
   include/drm/drm_