summaryrefslogtreecommitdiff
path: root/Documentation/doc-guide/kernel-doc.rst
diff options
context:
space:
mode:
authorMatthew Wilcox <mawilcox@microsoft.com>2018-02-13 13:15:33 -0800
committerJonathan Corbet <corbet@lwn.net>2018-02-13 14:21:40 -0700
commitda70b8c47515ea408e3ab7fd97307ef16d3b9ff1 (patch)
tree1b0654d666b4437a9f5a0242ffe384b6b48140bd /Documentation/doc-guide/kernel-doc.rst
parente474785a12b46230ecf9f3663166b0de1175bcdc (diff)
Add documentation for Context section
This section is mentioned in scripts/kernel-doc, so we should mention it in doc-guide/kernel-doc.rst. There are close to 500 comments using the Context section already, and almost 300 using a Locking section which fulfills much the same purpose (and should probably be converted for consistency). Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/doc-guide/kernel-doc.rst')
-rw-r--r--Documentation/doc-guide/kernel-doc.rst25
1 files changed, 25 insertions, 0 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 722d4525f7cf..315b0ecc7a11 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -117,6 +117,7 @@ Example kernel-doc function comment::
*
* Longer description of foobar.
*
+ * Context: Interrupt / locking context of foobar.
* Return: Description of return value of foobar.
*/
int foobar(int argument1, char *argument2)
@@ -216,6 +217,9 @@ The general format of a function and function-like macro kernel-doc comment is::
*
* The longer description may have multiple paragraphs.
*
+ * Context: Describes whether the function can sleep, what locks it takes,
+ * releases, or expects to be held. It can extend over multiple
+ * lines.
* Return: Describe the return value of foobar.
*
* The return value description can also have multiple paragraphs, and should
@@ -226,6 +230,24 @@ The brief description following the function name may span multiple lines, and
ends with an argument description, a blank comment line, or the end of the
comment block.
+Function context
+~~~~~~~~~~~~~~~~
+
+The context in which a function can be called should be described in a
+section named ``Context``. This should include whether the function
+sleeps or can be called from interrupt context, as well as what locks
+it takes, releases and expects to be held by its caller.
+
+Examples::
+
+ * Context: Any context.
+ * Context: Any context. Takes and releases the RCU lock.
+ * Context: Any context. Expects <lock> to be held by caller.
+ * Context: Process context. May sleep if @gfp flags permit.
+ * Context: Process context. Takes and releases <mutex>.
+ * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
+ * Context: Interrupt context.
+
Return values
~~~~~~~~~~~~~
@@ -347,6 +369,9 @@ Typedefs with function prototypes can also be documented::
* @arg2: description of arg2
*
* Description of the type.
+ *
+ * Context: Locking context.
+ * Return: Meaning of the return value.
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);