[PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format

[PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format

[Mauro Carvalho Chehab]

Some new chapters were added to the documentation. This caused
Sphinx to complain, as the literal blocks there are not properly
tagged as such. Also, a new note added there doesn't follow
the ReST format.

This fixes the following warnings:

    Documentation/trace/events.rst:589: WARNING: Definition list ends without a blank line; unexpected unindent.
    Documentation/trace/events.rst:620: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:623: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:626: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:703: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:697: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:722: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:775: WARNING: Definition list ends without a blank line; unexpected unindent.
    Documentation/trace/events.rst:814: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:817: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:820: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:823: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:826: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:829: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:832: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:844: WARNING: Unexpected indentation.
    Documentation/trace/events.rst:845: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/trace/events.rst:849: WARNING: Unexpected indentation.
    Documentation/trace/events.rst:850: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/trace/events.rst:883: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:886: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:889: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:895: WARNING: Bullet list ends without a blank line; unexpected unindent.
    Documentation/trace/events.rst:895: WARNING: Inline emphasis start-string without end-string.
    Documentation/trace/events.rst:968: WARNING: Inline emphasis start-string without end-string.

Fixes: 34ed63573b66 ("tracing: Documentation for in-kernel synthetic event API")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/trace/events.rst | 63 +++++++++++++++++-----------------
 1 file changed, 32 insertions(+), 31 deletions(-)

diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst
index ed79b220bd07..4a2ebe0bd19b 100644
--- a/Documentation/trace/events.rst
+++ b/Documentation/trace/events.rst
@@ -342,7 +342,8 @@ section of Documentation/trace/ftrace.rst), but there are major
 differences and the implementation isn't currently tied to it in any
 way, so beware about making generalizations between the two.
 
-Note: Writing into trace_marker (See Documentation/trace/ftrace.rst)
+.. Note::
+     Writing into trace_marker (See Documentation/trace/ftrace.rst)
      can also enable triggers that are written into
      /sys/kernel/tracing/events/ftrace/print/trigger
 
@@ -569,14 +570,14 @@ The first creates the event in one step, using synth_event_create().
 In this method, the name of the event to create and an array defining
 the fields is supplied to synth_event_create().  If successful, a
 synthetic event with that name and fields will exist following that
-call.  For example, to create a new "schedtest" synthetic event:
+call.  For example, to create a new "schedtest" synthetic event::
 
   ret = synth_event_create("schedtest", sched_fields,
                            ARRAY_SIZE(sched_fields), THIS_MODULE);
 
 The sched_fields param in this example points to an array of struct
 synth_field_desc, each of which describes an event field by type and
-name:
+name::
 
   static struct synth_field_desc sched_fields[] = {
         { .type = "pid_t",              .name = "next_pid_field" },
@@ -615,7 +616,7 @@ synth_event_gen_cmd_array_start(), the user should create and
 initialize a dynevent_cmd object using synth_event_cmd_init().
 
 For example, to create a new "schedtest" synthetic event with two
-fields:
+fields::
 
   struct dynevent_cmd cmd;
   char *buf;
@@ -631,7 +632,7 @@ fields:
                                   "u64", "ts_ns");
 
 Alternatively, using an array of struct synth_field_desc fields
-containing the same information:
+containing the same information::
 
   ret = synth_event_gen_cmd_array_start(&cmd, "schedtest", THIS_MODULE,
                                         fields, n_fields);
@@ -640,7 +641,7 @@ Once the synthetic event object has been created, it can then be
 populated with more fields.  Fields are added one by one using
 synth_event_add_field(), supplying the dynevent_cmd object, a field
 type, and a field name.  For example, to add a new int field named
-"intfield", the following call should be made:
+"intfield", the following call should be made::
 
   ret = synth_event_add_field(&cmd, "int", "intfield");
 
@@ -649,7 +650,7 @@ the field is considered to be an array.
 
 A group of fields can also be added all at once using an array of
 synth_field_desc with add_synth_fields().  For example, this would add
-just the first four sched_fields:
+just the first four sched_fields::
 
   ret = synth_event_add_fields(&cmd, sched_fields, 4);
 
@@ -658,7 +659,7 @@ synth_event_add_field_str() can be used to add it as-is; it will
 also automatically append a ';' to the string.
 
 Once all the fields have been added, the event should be finalized and
-registered by calling the synth_event_gen_cmd_end() function:
+registered by calling the synth_event_gen_cmd_end() function::
 
   ret = synth_event_gen_cmd_end(&cmd);
 
@@ -691,7 +692,7 @@ trace array)), along with an variable number of u64 args, one for each
 synthetic event field, and the number of values being passed.
 
 So, to trace an event corresponding to the synthetic event definition
-above, code like the following could be used:
+above, code like the following could be used::
 
   ret = synth_event_trace(create_synth_test, 7, /* number of values */
                           444,             /* next_pid_field */
@@ -715,7 +716,7 @@ trace array)), along with an array of u64, one for each synthetic
 event field.
 
 To trace an event corresponding to the synthetic event definition
-above, code like the following could be used:
+above, code like the following could be used::
 
   u64 vals[7];
 
@@ -739,7 +740,7 @@ In order to trace a synthetic event, a pointer to the trace event file
 is needed.  The trace_get_event_file() function can be used to get
 it - it will find the file in the given trace instance (in this case
 NULL since the top trace array is being used) while at the same time
-preventing the instance containing it from going away:
+preventing the instance containing it from going away::
 
        schedtest_event_file = trace_get_event_file(NULL, "synthetic",
                                                    "schedtest");
@@ -751,31 +752,31 @@ To enable a synthetic event from the kernel, trace_array_set_clr_event()
 can be used (which is not specific to synthetic events, so does need
 the "synthetic" system name to be specified explicitly).
 
-To enable the event, pass 'true' to it:
+To enable the event, pass 'true' to it::
 
        trace_array_set_clr_event(schedtest_event_file->tr,
                                  "synthetic", "schedtest", true);
 
-To disable it pass false:
+To disable it pass false::
 
        trace_array_set_clr_event(schedtest_event_file->tr,
                                  "synthetic", "schedtest", false);
 
 Finally, synth_event_trace_array() can be used to actually trace the
-event, which should be visible in the trace buffer afterwards:
+event, which should be visible in the trace buffer afterwards::
 
        ret = synth_event_trace_array(schedtest_event_file, vals,
                                      ARRAY_SIZE(vals));
 
 To remove the synthetic event, the event should be disabled, and the
-trace instance should be 'put' back using trace_put_event_file():
+trace instance should be 'put' back using trace_put_event_file()::
 
        trace_array_set_clr_event(schedtest_event_file->tr,
                                  "synthetic", "schedtest", false);
        trace_put_event_file(schedtest_event_file);
 
 If those have been successful, synth_event_delete() can be called to
-remove the event:
+remove the event::
 
        ret = synth_event_delete("schedtest");
 
@@ -784,7 +785,7 @@ remove the event:
 
 To trace a synthetic using the piecewise method described above, the
 synth_event_trace_start() function is used to 'open' the synthetic
-event trace:
+event trace::
 
        struct synth_trace_state trace_state;
 
@@ -809,7 +810,7 @@ along with the value to set the next field in the event.  After each
 field is set, the 'cursor' points to the next field, which will be set
 by the subsequent call, continuing until all the fields have been set
 in order.  The same sequence of calls as in the above examples using
-this method would be (without error-handling code):
+this method would be (without error-handling code)::
 
        /* next_pid_field */
        ret = synth_event_add_next_val(777, &trace_state);
@@ -837,7 +838,7 @@ used.  Each call is passed the same synth_trace_state object used in
 the synth_event_trace_start(), along with the field name of the field
 to set and the value to set it to.  The same sequence of calls as in
 the above examples using this method would be (without error-handling
-code):
+code)::
 
        ret = synth_event_add_val("next_pid_field", 777, &trace_state);
        ret = synth_event_add_val("next_comm_field", (u64)"silly putty",
@@ -855,7 +856,7 @@ can be used but not both at the same time.
 
 Finally, the event won't be actually traced until it's 'closed',
 which is done using synth_event_trace_end(), which takes only the
-struct synth_trace_state object used in the previous calls:
+struct synth_trace_state object used in the previous calls::
 
        ret = synth_event_trace_end(&trace_state);
 
@@ -878,7 +879,7 @@ function.  Before calling kprobe_event_gen_cmd_start(), the user
 should create and initialize a dynevent_cmd object using
 kprobe_event_cmd_init().
 
-For example, to create a new "schedtest" kprobe event with two fields:
+For example, to create a new "schedtest" kprobe event with two fields::
 
   struct dynevent_cmd cmd;
   char *buf;
@@ -900,18 +901,18 @@ Once the kprobe event object has been created, it can then be
 populated with more fields.  Fields can be added using
 kprobe_event_add_fields(), supplying the dynevent_cmd object along
 with a variable arg list of probe fields.  For example, to add a
-couple additional fields, the following call could be made:
+couple additional fields, the following call could be made::
 
   ret = kprobe_event_add_fields(&cmd, "flags=%cx", "mode=+4($stack)");
 
 Once all the fields have been added, the event should be finalized and
 registered by calling the kprobe_event_gen_cmd_end() or
 kretprobe_event_gen_cmd_end() functions, depending on whether a kprobe
-or kretprobe command was started:
+or kretprobe command was started::
 
   ret = kprobe_event_gen_cmd_end(&cmd);
 
-or
+or::
 
   ret = kretprobe_event_gen_cmd_end(&cmd);
 
@@ -920,13 +921,13 @@ events.
 
 Similarly, a kretprobe event can be created using
 kretprobe_event_gen_cmd_start() with a probe name and location and
-additional params such as $retval:
+additional params such as $retval::
 
   ret = kretprobe_event_gen_cmd_start(&cmd, "gen_kretprobe_test",
                                       "do_sys_open", "$retval");
 
 Similar to the synthetic event case, code like the following can be
-used to enable the newly created kprobe event:
+used to enable the newly created kprobe event::
 
   gen_kprobe_test = trace_get_event_file(NULL, "kprobes", "gen_kprobe_test");
 
@@ -934,7 +935,7 @@ used to enable the newly created kprobe event:
                                   "kprobes", "gen_kprobe_test", true);
 
 Finally, also similar to synthetic events, the following code can be
-used to give the kprobe event file back and delete the event:
+used to give the kprobe event file back and delete the event::
 
   trace_put_event_file(gen_kprobe_test);
 
@@ -963,7 +964,7 @@ are described below.
 
 The first step in building a new command string is to create and
 initialize an instance of a dynevent_cmd.  Here, for instance, we
-create a dynevent_cmd on the stack and initialize it:
+create a dynevent_cmd on the stack and initialize it::
 
   struct dynevent_cmd cmd;
   char *buf;
@@ -989,7 +990,7 @@ calls to argument-adding functions.
 To add a single argument, define and initialize a struct dynevent_arg
 or struct dynevent_arg_pair object.  Here's an example of the simplest
 possible arg addition, which is simply to append the given string as
-a whitespace-separated argument to the command:
+a whitespace-separated argument to the command::
 
   struct dynevent_arg arg;
 
@@ -1007,7 +1008,7 @@ the arg.
 Here's another more complicated example using an 'arg pair', which is
 used to create an argument that consists of a couple components added
 together as a unit, for example, a 'type field_name;' arg or a simple
-expression arg e.g. 'flags=%cx':
+expression arg e.g. 'flags=%cx'::
 
   struct dynevent_arg_pair arg_pair;
 
@@ -1031,7 +1032,7 @@ Any number of dynevent_*_add() calls can be made to build up the string
 (until its length surpasses cmd->maxlen).  When all the arguments have
 been added and the command string is complete, the only thing left to
 do is run the command, which happens by simply calling
-dynevent_create():
+dynevent_create()::
 
   ret = dynevent_create(&cmd);
 
-- 
2.24.1

[PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings

[Mauro Carvalho Chehab]

Sphinx doesn't like multi-line literal blocks with ``foobar``:

    Documentation/watch_queue.rst:109: WARNING: Inline literal start-string without end-string.
    Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
    Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
    Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
    Documentation/watch_queue.rst:186: WARNING: Inline literal start-string without end-string.
    Documentation/watch_queue.rst:186: WARNING: Inline emphasis start-string without end-string.
    Documentation/watch_queue.rst:185: WARNING: Inline emphasis start-string without end-string.

So, let's use the "::" markup instead.

While we could do the fix only at the affected lines, let's
do the same change along the entire file, in order to preserve
the same look and feel at the entire doc.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/watch_queue.rst | 34 +++++++++++++++++++++++++---------
 1 file changed, 25 insertions(+), 9 deletions(-)

diff --git a/Documentation/watch_queue.rst b/Documentation/watch_queue.rst
index d8f70282d247..f1ffe9cdf81f 100644
--- a/Documentation/watch_queue.rst
+++ b/Documentation/watch_queue.rst
@@ -105,15 +105,19 @@ watch that specific key).
 
 To manage a watch list, the following functions are provided:
 
-  * ``void init_watch_list(struct watch_list *wlist,
-			   void (*release_watch)(struct watch *wlist));``
+  * ::
+
+      void init_watch_list(struct watch_list *wlist,
+			   void (*release_watch)(struct watch *wlist));
 
     Initialise a watch list.  If ``release_watch`` is not NULL, then this
     indicates a function that should be called when the watch_list object is
     destroyed to discard any references the watch list holds on the watched
     object.
 
-  * ``void remove_watch_list(struct watch_list *wlist);``
+  * ::
+
+      void remove_watch_list(struct watch_list *wlist);
 
     This removes all of the watches subscribed to a watch_list and frees them
     and then destroys the watch_list object itself.
@@ -127,14 +131,18 @@ records will be written into.  The workings of this are hidden entirely inside
 of the watch_queue device driver, but it is necessary to gain a reference to it
 to set a watch.  These can be managed with:
 
-  * ``struct watch_queue *get_watch_queue(int fd);``
+  * ::
+
+      struct watch_queue *get_watch_queue(int fd);``
 
     Since watch queues are indicated to the kernel by the fd of the pipe that
     implements the buffer, userspace must hand that fd through a system call.
     This can be used to look up an opaque pointer to the watch queue from the
     system call.
 
-  * ``void put_watch_queue(struct watch_queue *wqueue);``
+  * ::
+
+      void put_watch_queue(struct watch_queue *wqueue);
 
     This discards the reference obtained from ``get_watch_queue()``.
 
@@ -170,18 +178,24 @@ different ID are ignored.
 
 The following functions are provided to manage watches:
 
-  * ``void init_watch(struct watch *watch, struct watch_queue *wqueue);``
+  * ::
+
+      void init_watch(struct watch *watch, struct watch_queue *wqueue);
 
     Initialise a watch object, setting its pointer to the watch queue, using
     appropriate barriering to avoid lockdep complaints.
 
-  * ``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);``
+  * ::
+
+      int add_watch_to_object(struct watch *watch, struct watch_list *wlist);
 
     Subscribe a watch to a watch list (notification source).  The
     driver-settable fields in the watch struct must have been set before this
     is called.
 
-  * ``int remove_watch_from_object(struct watch_list *wlist,
+  * ::
+
+      int remove_watch_from_object(struct watch_list *wlist,
 				   struct watch_queue *wqueue,
 				   u64 id, false);``
 
@@ -190,7 +204,9 @@ The following functions are provided to manage watches:
     (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue to
     indicate that the watch got removed.
 
-  * ``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);``
+  * ::
+
+      int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);
 
     Remove all the watches from a watch list.  It is expected that this will be
     called preparatory to destruction and that the watch list will be
-- 
2.24.1

[PATCH 3/9] docs: dmaengine: provider.rst: get rid of some warnings

[Mauro Carvalho Chehab]

Get rid of those warnings by adding extra blank lines:

    Documentation/driver-api/dmaengine/provider.rst:270: WARNING: Unexpected indentation.
    Documentation/driver-api/dmaengine/provider.rst:273: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/driver-api/dmaengine/provider.rst:288: WARNING: Unexpected indentation.
    Documentation/driver-api/dmaengine/provider.rst:290: WARNING: Block quote ends without a blank line; unexpected unindent.

While here, use parenthesis after get_metadata_ptr/set_metadata_len,
as, if some day someone adds a kerneldoc markup for those, it
should automatically generate a cross-reference to them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/dmaengine/provider.rst | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
index 790a15089f1f..56e5833e8a07 100644
--- a/Documentation/driver-api/dmaengine/provider.rst
+++ b/Documentation/driver-api/dmaengine/provider.rst
@@ -266,11 +266,15 @@ to use.
   attached (via the dmaengine_desc_attach_metadata() helper to the descriptor.
 
   From the DMA driver the following is expected for this mode:
+
   - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM
+
     The data from the provided metadata buffer should be prepared for the DMA
     controller to be sent alongside of the payload data. Either by copying to a
     hardware descriptor, or highly coupled packet.
+
   - DMA_DEV_TO_MEM
+
     On transfer completion the DMA driver must copy the metadata to the client
     provided metadata buffer before notifying the client about the completion.
     After the transfer completion, DMA drivers must not touch the metadata
@@ -284,10 +288,14 @@ to use.
   and dmaengine_desc_set_metadata_len() is provided as helper functions.
 
   From the DMA driver the following is expected for this mode:
-  - get_metadata_ptr
+
+  - get_metadata_ptr()
+
     Should return a pointer for the metadata buffer, the maximum size of the
     metadata buffer and the currently used / valid (if any) bytes in the buffer.
-  - set_metadata_len
+
+  - set_metadata_len()
+
     It is called by the clients after it have placed the metadata to the buffer
     to let the DMA driver know the number of valid bytes provided.
 
-- 
2.24.1

[PATCH 4/9] docs: driver.rst: supress two ReSt warnings

[Mauro Carvalho Chehab]

Get rid of those, by marking a literal block as such:

	Documentation/driver-api/gpio/driver.rst:425: WARNING: Unexpected indentation.
	Documentation/driver-api/gpio/driver.rst:423: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/driver-model/driver.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
index baa6a85c8287..63887b813005 100644
--- a/Documentation/driver-api/driver-model/driver.rst
+++ b/Documentation/driver-api/driver-model/driver.rst
@@ -210,7 +210,7 @@ probed.
 While the typical use case for sync_state() is to have the kernel cleanly take
 over management of devices from the bootloader, the usage of sync_state() is
 not restricted to that. Use it whenever it makes sense to take an action after
-all the consumers of a device have probed.
+all the consumers of a device have probed::
 
 	int 	(*remove)	(struct device *dev);
 
-- 
2.24.1

[PATCH 5/9] docs: gpio: driver.rst: don't mark literal blocks twice

[Mauro Carvalho Chehab]

Two literal blocks there are marked with both "::" and

	.. code-block:: c

This causes Sphinx (2.4.1) to do the wrong thing, causing
lots of warnings:

    Documentation/driver-api/gpio/driver.rst:425: WARNING: Unexpected indentation.
    Documentation/driver-api/gpio/driver.rst:423: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:427: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/driver-api/gpio/driver.rst:429: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:429: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:429: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:433: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:446: WARNING: Unexpected indentation.
    Documentation/driver-api/gpio/driver.rst:440: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:440: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:447: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/driver-api/gpio/driver.rst:449: WARNING: Definition list ends without a blank line; unexpected unindent.
    Documentation/driver-api/gpio/driver.rst:462: WARNING: Unexpected indentation.
    Documentation/driver-api/gpio/driver.rst:460: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:462: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:465: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/driver-api/gpio/driver.rst:467: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:467: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:467: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:471: WARNING: Inline emphasis start-string without end-string.
    Documentation/driver-api/gpio/driver.rst:478: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/gpio/driver.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 871922529332..9809f593c0ab 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -416,7 +416,7 @@ The preferred way to set up the helpers is to fill in the
 struct gpio_irq_chip inside struct gpio_chip before adding the gpio_chip.
 If you do this, the additional irq_chip will be set up by gpiolib at the
 same time as setting up the rest of the GPIO functionality. The following
-is a typical example of a cascaded interrupt handler using gpio_irq_chip::
+is a typical example of a cascaded interrupt handler using gpio_irq_chip:
 
 .. code-block:: c
 
@@ -453,7 +453,7 @@ is a typical example of a cascaded interrupt handler using gpio_irq_chip::
   return devm_gpiochip_add_data(dev, &g->gc, g);
 
 The helper support using hierarchical interrupt controllers as well.
-In this case the typical set-up will look like this::
+In this case the typical set-up will look like this:
 
 .. code-block:: c
 
-- 
2.24.1

[PATCH 6/9] docs: translations: it: avoid duplicate refs at programming-language.rst

[Mauro Carvalho Chehab]

As the translations document is part of the main body, we can't
keep duplicated references there. So, prefix the Italian ones
with "it-".

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../it_IT/process/programming-language.rst    | 30 +++++++++----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/translations/it_IT/process/programming-language.rst b/Documentation/translations/it_IT/process/programming-language.rst
index f4b006395849..c4fc9d394c29 100644
--- a/Documentation/translations/it_IT/process/programming-language.rst
+++ b/Documentation/translations/it_IT/process/programming-language.rst
@@ -8,26 +8,26 @@
 Linguaggio di programmazione
 ============================
 
-Il kernel è scritto nel linguaggio di programmazione C [c-language]_.
-Più precisamente, il kernel viene compilato con ``gcc`` [gcc]_ usando
-l'opzione ``-std=gnu89`` [gcc-c-dialect-options]_: il dialetto GNU
+Il kernel è scritto nel linguaggio di programmazione C [it-c-language]_.
+Più precisamente, il kernel viene compilato con ``gcc`` [it-gcc]_ usando
+l'opzione ``-std=gnu89`` [it-gcc-c-dialect-options]_: il dialetto GNU
 dello standard ISO C90 (con l'aggiunta di alcune funzionalità da C99)
 
-Questo dialetto contiene diverse estensioni al linguaggio [gnu-extensions]_,
+Questo dialetto contiene diverse estensioni al linguaggio [it-gnu-extensions]_,
 e molte di queste vengono usate sistematicamente dal kernel.
 
 Il kernel offre un certo livello di supporto per la compilazione con ``clang``
-[clang]_ e ``icc`` [icc]_ su diverse architetture, tuttavia in questo momento
+[it-clang]_ e ``icc`` [it-icc]_ su diverse architetture, tuttavia in questo momento
 il supporto non è completo e richiede delle patch aggiuntive.
 
 Attributi
 ---------
 
 Una delle estensioni più comuni e usate nel kernel sono gli attributi
-[gcc-attribute-syntax]_. Gli attributi permettono di aggiungere una semantica,
+[it-gcc-attribute-syntax]_. Gli attributi permettono di aggiungere una semantica,
 definita dell'implementazione, alle entità del linguaggio (come le variabili,
 le funzioni o i tipi) senza dover fare importanti modifiche sintattiche al
-linguaggio stesso (come l'aggiunta di nuove parole chiave) [n2049]_.
+linguaggio stesso (come l'aggiunta di nuove parole chiave) [it-n2049]_.
 
 In alcuni casi, gli attributi sono opzionali (ovvero un compilatore che non
 dovesse supportarli dovrebbe produrre comunque codice corretto, anche se
@@ -41,11 +41,11 @@ possono usare e/o per accorciare il codice.
 Per maggiori informazioni consultate il file d'intestazione
 ``include/linux/compiler_attributes.h``.
 
-.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
-.. [gcc] https://gcc.gnu.org
-.. [clang] https://clang.llvm.org
-.. [icc] https://software.intel.com/en-us/c-compilers
-.. [gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html
-.. [gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html
-.. [gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html
-.. [n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf
+.. [it-c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
+.. [it-gcc] https://gcc.gnu.org
+.. [it-clang] https://clang.llvm.org
+.. [it-icc] https://software.intel.com/en-us/c-compilers
+.. [it-gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html
+.. [it-gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html
+.. [it-gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html
+.. [it-n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf
-- 
2.24.1

[PATCH 7/9] docs: filesystems: fuse.rst: supress a Sphinx warning

[Mauro Carvalho Chehab]

Get rid of this warning:

    Documentation/filesystems/fuse.rst:2: WARNING: Explicit markup ends without a blank line; unexpected unindent.

Fixes: 8ab13bca428b ("Documentation: filesystems: convert fuse to RST")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/filesystems/fuse.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/fuse.rst b/Documentation/filesystems/fuse.rst
index 8e455065ce9e..cd717f9bf940 100644
--- a/Documentation/filesystems/fuse.rst
+++ b/Documentation/filesystems/fuse.rst
@@ -1,7 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0
-==============
+
+====
 FUSE
-==============
+====
 
 Definitions
 ===========
-- 
2.24.1

[PATCH 8/9] docs: perf: imx-ddr.rst: get rid of a warning

[Mauro Carvalho Chehab]

    Documentation/admin-guide/perf/imx-ddr.rst:47: WARNING: Unexpected indentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/perf/imx-ddr.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/perf/imx-ddr.rst b/Documentation/admin-guide/perf/imx-ddr.rst
index 3726a10a03ba..f05f56c73b7d 100644
--- a/Documentation/admin-guide/perf/imx-ddr.rst
+++ b/Documentation/admin-guide/perf/imx-ddr.rst
@@ -43,7 +43,8 @@ value 1 for supported.
 
   AXI_ID and AXI_MASKING are mapped on DPCR1 register in performance counter.
   When non-masked bits are matching corresponding AXI_ID bits then counter is
-  incremented. Perf counter is incremented if
+  incremented. Perf counter is incremented if::
+
         AxID && AXI_MASKING == AXI_ID && AXI_MASKING
 
   This filter doesn't support filter different AXI ID for axid-read and axid-write
-- 
2.24.1

[PATCH 9/9] docs: hw-vuln: tsx_async_abort.rst: get rid of an unused ref

[Mauro Carvalho Chehab]

The virt_mechanism reference there points to a section
called elsewhere (Virtualization mitigation). Also, it is
not used anywere.

Besides that, it conflicts with a label with the same name
inside:

	Documentation/admin-guide/hw-vuln/mds.rst

Perhaps added due to some cut-and-paste?

Anyway, as this is not used, let's just get rid of it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/hw-vuln/tsx_async_abort.rst | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
index af6865b822d2..68d96f0e9c95 100644
--- a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
+++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
@@ -136,8 +136,6 @@ enables the mitigation by default.
 The mitigation can be controlled at boot time via a kernel command line option.
 See :ref:`taa_mitigation_control_command_line`.
 
-.. _virt_mechanism:
-
 Virtualization mitigation
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- 
2.24.1

Re: [PATCH 6/9] docs: translations: it: avoid duplicate refs at programming-language.rst

[Nick Desaulniers]

On Tue, Mar 3, 2020 at 7:50 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> As the translations document is part of the main body, we can't
> keep duplicated references there. So, prefix the Italian ones
> with "it-".
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Recensito-da: Nick Desaulniers <ndesaulniers@google.com>

> ---
>  .../it_IT/process/programming-language.rst    | 30 +++++++++----------
>  1 file changed, 15 insertions(+), 15 deletions(-)
>
> diff --git a/Documentation/translations/it_IT/process/programming-language.rst b/Documentation/translations/it_IT/process/programming-language.rst
> index f4b006395849..c4fc9d394c29 100644
> --- a/Documentation/translations/it_IT/process/programming-language.rst
> +++ b/Documentation/translations/it_IT/process/programming-language.rst
> @@ -8,26 +8,26 @@
>  Linguaggio di programmazione
>  ============================
>
> -Il kernel è scritto nel linguaggio di programmazione C [c-language]_.
> -Più precisamente, il kernel viene compilato con ``gcc`` [gcc]_ usando
> -l'opzione ``-std=gnu89`` [gcc-c-dialect-options]_: il dialetto GNU
> +Il kernel è scritto nel linguaggio di programmazione C [it-c-language]_.
> +Più precisamente, il kernel viene compilato con ``gcc`` [it-gcc]_ usando
> +l'opzione ``-std=gnu89`` [it-gcc-c-dialect-options]_: il dialetto GNU
>  dello standard ISO C90 (con l'aggiunta di alcune funzionalità da C99)
>
> -Questo dialetto contiene diverse estensioni al linguaggio [gnu-extensions]_,
> +Questo dialetto contiene diverse estensioni al linguaggio [it-gnu-extensions]_,
>  e molte di queste vengono usate sistematicamente dal kernel.
>
>  Il kernel offre un certo livello di supporto per la compilazione con ``clang``
> -[clang]_ e ``icc`` [icc]_ su diverse architetture, tuttavia in questo momento
> +[it-clang]_ e ``icc`` [it-icc]_ su diverse architetture, tuttavia in questo momento
>  il supporto non è completo e richiede delle patch aggiuntive.
>
>  Attributi
>  ---------
>
>  Una delle estensioni più comuni e usate nel kernel sono gli attributi
> -[gcc-attribute-syntax]_. Gli attributi permettono di aggiungere una semantica,
> +[it-gcc-attribute-syntax]_. Gli attributi permettono di aggiungere una semantica,
>  definita dell'implementazione, alle entità del linguaggio (come le variabili,
>  le funzioni o i tipi) senza dover fare importanti modifiche sintattiche al
> -linguaggio stesso (come l'aggiunta di nuove parole chiave) [n2049]_.
> +linguaggio stesso (come l'aggiunta di nuove parole chiave) [it-n2049]_.
>
>  In alcuni casi, gli attributi sono opzionali (ovvero un compilatore che non
>  dovesse supportarli dovrebbe produrre comunque codice corretto, anche se
> @@ -41,11 +41,11 @@ possono usare e/o per accorciare il codice.
>  Per maggiori informazioni consultate il file d'intestazione
>  ``include/linux/compiler_attributes.h``.
>
> -.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
> -.. [gcc] https://gcc.gnu.org
> -.. [clang] https://clang.llvm.org
> -.. [icc] https://software.intel.com/en-us/c-compilers
> -.. [gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html
> -.. [gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html
> -.. [gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html
> -.. [n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf
> +.. [it-c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
> +.. [it-gcc] https://gcc.gnu.org
> +.. [it-clang] https://clang.llvm.org
> +.. [it-icc] https://software.intel.com/en-us/c-compilers
> +.. [it-gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html
> +.. [it-gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html
> +.. [it-gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html
> +.. [it-n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf
> --
> 2.24.1
>
> --
> You received this message because you are subscribed to the Google Groups "Clang Built Linux" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to clang-built-linux+unsubscribe@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/clang-built-linux/e733111f3599dff96524ad09ace5204ac6bb496b.1583250595.git.mchehab%2Bhuawei%40kernel.org.



-- 
Thanks,
~Nick Desaulniers

Re: [PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format

[Tom Zanussi]

Hi Mauro,

On Tue, 2020-03-03 at 16:50 +0100, Mauro Carvalho Chehab wrote:
> Some new chapters were added to the documentation. This caused
> Sphinx to complain, as the literal blocks there are not properly
> tagged as such. Also, a new note added there doesn't follow
> the ReST format.
> 

Thanks for fixing these.

Reviewed-by: Tom Zanussi <zanussi@kernel.org>


> This fixes the following warnings:
> 
>     Documentation/trace/events.rst:589: WARNING: Definition list ends
> without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:620: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:623: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:626: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:703: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:697: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:722: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:775: WARNING: Definition list ends
> without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:814: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:817: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:820: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:823: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:826: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:829: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:832: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:844: WARNING: Unexpected
> indentation.
>     Documentation/trace/events.rst:845: WARNING: Block quote ends
> without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:849: WARNING: Unexpected
> indentation.
>     Documentation/trace/events.rst:850: WARNING: Block quote ends
> without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:883: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:886: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:889: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:895: WARNING: Bullet list ends
> without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:895: WARNING: Inline emphasis
> start-string without end-string.
>     Documentation/trace/events.rst:968: WARNING: Inline emphasis
> start-string without end-string.
> 
> Fixes: 34ed63573b66 ("tracing: Documentation for in-kernel synthetic
> event API")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/trace/events.rst | 63 +++++++++++++++++---------------
> --
>  1 file changed, 32 insertions(+), 31 deletions(-)
> 
> diff --git a/Documentation/trace/events.rst
> b/Documentation/trace/events.rst
> index ed79b220bd07..4a2ebe0bd19b 100644
> --- a/Documentation/trace/events.rst
> +++ b/Documentation/trace/events.rst
> @@ -342,7 +342,8 @@ section of Documentation/trace/ftrace.rst), but
> there are major
>  differences and the implementation isn't currently tied to it in any
>  way, so beware about making generalizations between the two.
>  
> -Note: Writing into trace_marker (See Documentation/trace/ftrace.rst)
> +.. Note::
> +     Writing into trace_marker (See Documentation/trace/ftrace.rst)
>       can also enable triggers that are written into
>       /sys/kernel/tracing/events/ftrace/print/trigger
>  
> @@ -569,14 +570,14 @@ The first creates the event in one step, using
> synth_event_create().
>  In this method, the name of the event to create and an array
> defining
>  the fields is supplied to synth_event_create().  If successful, a
>  synthetic event with that name and fields will exist following that
> -call.  For example, to create a new "schedtest" synthetic event:
> +call.  For example, to create a new "schedtest" synthetic event::
>  
>    ret = synth_event_create("schedtest", sched_fields,
>                             ARRAY_SIZE(sched_fields), THIS_MODULE);
>  
>  The sched_fields param in this example points to an array of struct
>  synth_field_desc, each of which describes an event field by type and
> -name:
> +name::
>  
>    static struct synth_field_desc sched_fields[] = {
>          { .type = "pid_t",              .name = "next_pid_field" },
> @@ -615,7 +616,7 @@ synth_event_gen_cmd_array_start(), the user
> should create and
>  initialize a dynevent_cmd object using synth_event_cmd_init().
>  
>  For example, to create a new "schedtest" synthetic event with two
> -fields:
> +fields::
>  
>    struct dynevent_cmd cmd;
>    char *buf;
> @@ -631,7 +632,7 @@ fields:
>                                    "u64", "ts_ns");
>  
>  Alternatively, using an array of struct synth_field_desc fields
> -containing the same information:
> +containing the same information::
>  
>    ret = synth_event_gen_cmd_array_start(&cmd, "schedtest",
> THIS_MODULE,
>                                          fields, n_fields);
> @@ -640,7 +641,7 @@ Once the synthetic event object has been created,
> it can then be
>  populated with more fields.  Fields are added one by one using
>  synth_event_add_field(), supplying the dynevent_cmd object, a field
>  type, and a field name.  For example, to add a new int field named
> -"intfield", the following call should be made:
> +"intfield", the following call should be made::
>  
>    ret = synth_event_add_field(&cmd, "int", "intfield");
>  
> @@ -649,7 +650,7 @@ the field is considered to be an array.
>  
>  A group of fields can also be added all at once using an array of
>  synth_field_desc with add_synth_fields().  For example, this would
> add
> -just the first four sched_fields:
> +just the first four sched_fields::
>  
>    ret = synth_event_add_fields(&cmd, sched_fields, 4);
>  
> @@ -658,7 +659,7 @@ synth_event_add_field_str() can be used to add it
> as-is; it will
>  also automatically append a ';' to the string.
>  
>  Once all the fields have been added, the event should be finalized
> and
> -registered by calling the synth_event_gen_cmd_end() function:
> +registered by calling the synth_event_gen_cmd_end() function::
>  
>    ret = synth_event_gen_cmd_end(&cmd);
>  
> @@ -691,7 +692,7 @@ trace array)), along with an variable number of
> u64 args, one for each
>  synthetic event field, and the number of values being passed.
>  
>  So, to trace an event corresponding to the synthetic event
> definition
> -above, code like the following could be used:
> +above, code like the following could be used::
>  
>    ret = synth_event_trace(create_synth_test, 7, /* number of values
> */
>                            444,             /* next_pid_field */
> @@ -715,7 +716,7 @@ trace array)), along with an array of u64, one
> for each synthetic
>  event field.
>  
>  To trace an event corresponding to the synthetic event definition
> -above, code like the following could be used:
> +above, code like the following could be used::
>  
>    u64 vals[7];
>  
> @@ -739,7 +740,7 @@ In order to trace a synthetic event, a pointer to
> the trace event file
>  is needed.  The trace_get_event_file() function can be used to get
>  it - it will find the file in the given trace instance (in this case
>  NULL since the top trace array is being used) while at the same time
> -preventing the instance containing it from going away:
> +preventing the instance containing it from going away::
>  
>         schedtest_event_file = trace_get_event_file(NULL,
> "synthetic",
>                                                     "schedtest");
> @@ -751,31 +752,31 @@ To enable a synthetic event from the kernel,
> trace_array_set_clr_event()
>  can be used (which is not specific to synthetic events, so does need
>  the "synthetic" system name to be specified explicitly).
>  
> -To enable the event, pass 'true' to it:
> +To enable the event, pass 'true' to it::
>  
>         trace_array_set_clr_event(schedtest_event_file->tr,
>                                   "synthetic", "schedtest", true);
>  
> -To disable it pass false:
> +To disable it pass false::
>  
>         trace_array_set_clr_event(schedtest_event_file->tr,
>                                   "synthetic", "schedtest", false);
>  
>  Finally, synth_event_trace_array() can be used to actually trace the
> -event, which should be visible in the trace buffer afterwards:
> +event, which should be visible in the trace buffer afterwards::
>  
>         ret = synth_event_trace_array(schedtest_event_file, vals,
>                                       ARRAY_SIZE(vals));
>  
>  To remove the synthetic event, the event should be disabled, and the
> -trace instance should be 'put' back using trace_put_event_file():
> +trace instance should be 'put' back using trace_put_event_file()::
>  
>         trace_array_set_clr_event(schedtest_event_file->tr,
>                                   "synthetic", "schedtest", false);
>         trace_put_event_file(schedtest_event_file);
>  
>  If those have been successful, synth_event_delete() can be called to
> -remove the event:
> +remove the event::
>  
>         ret = synth_event_delete("schedtest");
>  
> @@ -784,7 +785,7 @@ remove the event:
>  
>  To trace a synthetic using the piecewise method described above, the
>  synth_event_trace_start() function is used to 'open' the synthetic
> -event trace:
> +event trace::
>  
>         struct synth_trace_state trace_state;
>  
> @@ -809,7 +810,7 @@ along with the value to set the next field in the
> event.  After each
>  field is set, the 'cursor' points to the next field, which will be
> set
>  by the subsequent call, continuing until all the fields have been
> set
>  in order.  The same sequence of calls as in the above examples using
> -this method would be (without error-handling code):
> +this method would be (without error-handling code)::
>  
>         /* next_pid_field */
>         ret = synth_event_add_next_val(777, &trace_state);
> @@ -837,7 +838,7 @@ used.  Each call is passed the same
> synth_trace_state object used in
>  the synth_event_trace_start(), along with the field name of the
> field
>  to set and the value to set it to.  The same sequence of calls as in
>  the above examples using this method would be (without error-
> handling
> -code):
> +code)::
>  
>         ret = synth_event_add_val("next_pid_field", 777,
> &trace_state);
>         ret = synth_event_add_val("next_comm_field", (u64)"silly
> putty",
> @@ -855,7 +856,7 @@ can be used but not both at the same time.
>  
>  Finally, the event won't be actually traced until it's 'closed',
>  which is done using synth_event_trace_end(), which takes only the
> -struct synth_trace_state object used in the previous calls:
> +struct synth_trace_state object used in the previous calls::
>  
>         ret = synth_event_trace_end(&trace_state);
>  
> @@ -878,7 +879,7 @@ function.  Before calling
> kprobe_event_gen_cmd_start(), the user
>  should create and initialize a dynevent_cmd object using
>  kprobe_event_cmd_init().
>  
> -For example, to create a new "schedtest" kprobe event with two
> fields:
> +For example, to create a new "schedtest" kprobe event with two
> fields::
>  
>    struct dynevent_cmd cmd;
>    char *buf;
> @@ -900,18 +901,18 @@ Once the kprobe event object has been created,
> it can then be
>  populated with more fields.  Fields can be added using
>  kprobe_event_add_fields(), supplying the dynevent_cmd object along
>  with a variable arg list of probe fields.  For example, to add a
> -couple additional fields, the following call could be made:
> +couple additional fields, the following call could be made::
>  
>    ret = kprobe_event_add_fields(&cmd, "flags=%cx",
> "mode=+4($stack)");
>  
>  Once all the fields have been added, the event should be finalized
> and
>  registered by calling the kprobe_event_gen_cmd_end() or
>  kretprobe_event_gen_cmd_end() functions, depending on whether a
> kprobe
> -or kretprobe command was started:
> +or kretprobe command was started::
>  
>    ret = kprobe_event_gen_cmd_end(&cmd);
>  
> -or
> +or::
>  
>    ret = kretprobe_event_gen_cmd_end(&cmd);
>  
> @@ -920,13 +921,13 @@ events.
>  
>  Similarly, a kretprobe event can be created using
>  kretprobe_event_gen_cmd_start() with a probe name and location and
> -additional params such as $retval:
> +additional params such as $retval::
>  
>    ret = kretprobe_event_gen_cmd_start(&cmd, "gen_kretprobe_test",
>                                        "do_sys_open", "$retval");
>  
>  Similar to the synthetic event case, code like the following can be
> -used to enable the newly created kprobe event:
> +used to enable the newly created kprobe event::
>  
>    gen_kprobe_test = trace_get_event_file(NULL, "kprobes",
> "gen_kprobe_test");
>  
> @@ -934,7 +935,7 @@ used to enable the newly created kprobe event:
>                                    "kprobes", "gen_kprobe_test",
> true);
>  
>  Finally, also similar to synthetic events, the following code can be
> -used to give the kprobe event file back and delete the event:
> +used to give the kprobe event file back and delete the event::
>  
>    trace_put_event_file(gen_kprobe_test);
>  
> @@ -963,7 +964,7 @@ are described below.
>  
>  The first step in building a new command string is to create and
>  initialize an instance of a dynevent_cmd.  Here, for instance, we
> -create a dynevent_cmd on the stack and initialize it:
> +create a dynevent_cmd on the stack and initialize it::
>  
>    struct dynevent_cmd cmd;
>    char *buf;
> @@ -989,7 +990,7 @@ calls to argument-adding functions.
>  To add a single argument, define and initialize a struct
> dynevent_arg
>  or struct dynevent_arg_pair object.  Here's an example of the
> simplest
>  possible arg addition, which is simply to append the given string as
> -a whitespace-separated argument to the command:
> +a whitespace-separated argument to the command::
>  
>    struct dynevent_arg arg;
>  
> @@ -1007,7 +1008,7 @@ the arg.
>  Here's another more complicated example using an 'arg pair', which
> is
>  used to create an argument that consists of a couple components
> added
>  together as a unit, for example, a 'type field_name;' arg or a
> simple
> -expression arg e.g. 'flags=%cx':
> +expression arg e.g. 'flags=%cx'::
>  
>    struct dynevent_arg_pair arg_pair;
>  
> @@ -1031,7 +1032,7 @@ Any number of dynevent_*_add() calls can be
> made to build up the string
>  (until its length surpasses cmd->maxlen).  When all the arguments
> have
>  been added and the command string is complete, the only thing left
> to
>  do is run the command, which happens by simply calling
> -dynevent_create():
> +dynevent_create()::
>  
>    ret = dynevent_create(&cmd);
>  

Re: [PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format

[Steven Rostedt]

On Tue,  3 Mar 2020 16:50:31 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Some new chapters were added to the documentation. This caused
> Sphinx to complain, as the literal blocks there are not properly
> tagged as such. Also, a new note added there doesn't follow
> the ReST format.
> 
> This fixes the following warnings:
> 
>     Documentation/trace/events.rst:589: WARNING: Definition list ends without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:620: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:623: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:626: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:703: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:697: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:722: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:775: WARNING: Definition list ends without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:814: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:817: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:820: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:823: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:826: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:829: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:832: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:844: WARNING: Unexpected indentation.
>     Documentation/trace/events.rst:845: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:849: WARNING: Unexpected indentation.
>     Documentation/trace/events.rst:850: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:883: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:886: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:889: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:895: WARNING: Bullet list ends without a blank line; unexpected unindent.
>     Documentation/trace/events.rst:895: WARNING: Inline emphasis start-string without end-string.
>     Documentation/trace/events.rst:968: WARNING: Inline emphasis start-string without end-string.
> 
> Fixes: 34ed63573b66 ("tracing: Documentation for in-kernel synthetic event API")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>

Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>

Jon, let me know if this applies to your tree. If not, I'll take it in mine.

-- Steve

Re: [PATCH 6/9] docs: translations: it: avoid duplicate refs at programming-language.rst

[Federico Vaga]

On Tuesday, March 3, 2020 4:50:36 PM CET Mauro Carvalho Chehab wrote:
> As the translations document is part of the main body, we can't
> keep duplicated references there. So, prefix the Italian ones
> with "it-".
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

I thought this patch was already there, it was raised some months ago; 
probably I am confused I can't retrieve the thread. Anyway:

Reviewed-by: Federico Vaga <federico.vaga@vaga.pv.it>

Hopefully in the next weeks I should be able to be on duty again and fix all 
the issues and re-align the translation. It took a while to fix my personal 
life :)

> ---
>  .../it_IT/process/programming-language.rst    | 30 +++++++++----------
>  1 file changed, 15 insertions(+), 15 deletions(-)
> 
> diff --git
> a/Documentation/translations/it_IT/process/programming-language.rst
> b/Documentation/translations/it_IT/process/programming-language.rst index
> f4b006395849..c4fc9d394c29 100644
> --- a/Documentation/translations/it_IT/process/programming-language.rst
> +++ b/Documentation/translations/it_IT/process/programming-language.rst
> @@ -8,26 +8,26 @@
>  Linguaggio di programmazione
>  ============================
> 
> -Il kernel è scritto nel linguaggio di programmazione C [c-language]_.
> -Più precisamente, il kernel viene compilato con ``gcc`` [gcc]_ usando
> -l'opzione ``-std=gnu89`` [gcc-c-dialect-options]_: il dialetto GNU
> +Il kernel è scritto nel linguaggio di programmazione C [it-c-language]_.
> +Più precisamente, il kernel viene compilato con ``gcc`` [it-gcc]_ usando
> +l'opzione ``-std=gnu89`` [it-gcc-c-dialect-options]_: il dialetto GNU
>  dello standard ISO C90 (con l'aggiunta di alcune funzionalità da C99)
> 
> -Questo dialetto contiene diverse estensioni al linguaggio
> [gnu-extensions]_, +Questo dialetto contiene diverse estensioni al
> linguaggio [it-gnu-extensions]_, e molte di queste vengono usate
> sistematicamente dal kernel.
> 
>  Il kernel offre un certo livello di supporto per la compilazione con
> ``clang`` -[clang]_ e ``icc`` [icc]_ su diverse architetture, tuttavia in
> questo momento +[it-clang]_ e ``icc`` [it-icc]_ su diverse architetture,
> tuttavia in questo momento il supporto non è completo e richiede delle
> patch aggiuntive.
> 
>  Attributi
>  ---------
> 
>  Una delle estensioni più comuni e usate nel kernel sono gli attributi
> -[gcc-attribute-syntax]_. Gli attributi permettono di aggiungere una
> semantica, +[it-gcc-attribute-syntax]_. Gli attributi permettono di
> aggiungere una semantica, definita dell'implementazione, alle entità del
> linguaggio (come le variabili, le funzioni o i tipi) senza dover fare
> importanti modifiche sintattiche al -linguaggio stesso (come l'aggiunta di
> nuove parole chiave) [n2049]_. +linguaggio stesso (come l'aggiunta di nuove
> parole chiave) [it-n2049]_.
> 
>  In alcuni casi, gli attributi sono opzionali (ovvero un compilatore che non
> dovesse supportarli dovrebbe produrre comunque codice corretto, anche se @@
> -41,11 +41,11 @@ possono usare e/o per accorciare il codice.
>  Per maggiori informazioni consultate il file d'intestazione
>  ``include/linux/compiler_attributes.h``.
> 
> -.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
> -.. [gcc] https://gcc.gnu.org
> -.. [clang] https://clang.llvm.org
> -.. [icc] https://software.intel.com/en-us/c-compilers
> -.. [gcc-c-dialect-options]
> https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html -..
> [gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html -..
> [gcc-attribute-syntax]
> https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html -.. [n2049]
> http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf +..
> [it-c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards +..
> [it-gcc] https://gcc.gnu.org
> +.. [it-clang] https://clang.llvm.org
> +.. [it-icc] https://software.intel.com/en-us/c-compilers
> +.. [it-gcc-c-dialect-options]
> https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html +..
> [it-gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html
> +.. [it-gcc-attribute-syntax]
> https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html +.. [it-n2049]
> http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf


-- 
Federico Vaga
http://www.federicovaga.it/

Re: [PATCH 5/9] docs: gpio: driver.rst: don't mark literal blocks twice

[Bartosz Golaszewski]

wt., 3 mar 2020 o 16:50 Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> napisał(a):
>
> Two literal blocks there are marked with both "::" and
>
>         .. code-block:: c
>
> This causes Sphinx (2.4.1) to do the wrong thing, causing
> lots of warnings:
>
>     Documentation/driver-api/gpio/driver.rst:425: WARNING: Unexpected indentation.
>     Documentation/driver-api/gpio/driver.rst:423: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:427: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/driver-api/gpio/driver.rst:429: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:429: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:429: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:433: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:446: WARNING: Unexpected indentation.
>     Documentation/driver-api/gpio/driver.rst:440: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:440: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:447: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/driver-api/gpio/driver.rst:449: WARNING: Definition list ends without a blank line; unexpected unindent.
>     Documentation/driver-api/gpio/driver.rst:462: WARNING: Unexpected indentation.
>     Documentation/driver-api/gpio/driver.rst:460: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:462: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:465: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/driver-api/gpio/driver.rst:467: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:467: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:467: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:471: WARNING: Inline emphasis start-string without end-string.
>     Documentation/driver-api/gpio/driver.rst:478: WARNING: Inline emphasis start-string without end-string.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Patch applied. Thanks!

Bart

Re: [PATCH 3/9] docs: dmaengine: provider.rst: get rid of some warnings

[Vinod Koul]

On 03-03-20, 16:50, Mauro Carvalho Chehab wrote:
> Get rid of those warnings by adding extra blank lines:
> 
>     Documentation/driver-api/dmaengine/provider.rst:270: WARNING: Unexpected indentation.
>     Documentation/driver-api/dmaengine/provider.rst:273: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/driver-api/dmaengine/provider.rst:288: WARNING: Unexpected indentation.
>     Documentation/driver-api/dmaengine/provider.rst:290: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> While here, use parenthesis after get_metadata_ptr/set_metadata_len,
> as, if some day someone adds a kerneldoc markup for those, it
> should automatically generate a cross-reference to them.

Applied, thanks

-- 
~Vinod

Re: [PATCH 1/9] docs: trace: events.rst: convert some new stuff to ReST format

[Jonathan Corbet]

On Tue, 3 Mar 2020 15:48:26 -0500
Steven Rostedt <rostedt@goodmis.org> wrote:

> Acked-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
> 
> Jon, let me know if this applies to your tree. If not, I'll take it in mine.

I've applied it, thanks.

jon

Re: [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings

[Jonathan Corbet]

On Tue,  3 Mar 2020 16:50:32 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Sphinx doesn't like multi-line literal blocks with ``foobar``:
> 
>     Documentation/watch_queue.rst:109: WARNING: Inline literal start-string without end-string.
>     Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
>     Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
>     Documentation/watch_queue.rst:109: WARNING: Inline emphasis start-string without end-string.
>     Documentation/watch_queue.rst:186: WARNING: Inline literal start-string without end-string.
>     Documentation/watch_queue.rst:186: WARNING: Inline emphasis start-string without end-string.
>     Documentation/watch_queue.rst:185: WARNING: Inline emphasis start-string without end-string.
> 
> So, let's use the "::" markup instead.
> 
> While we could do the fix only at the affected lines, let's
> do the same change along the entire file, in order to preserve
> the same look and feel at the entire doc.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

So this doesn't apply to docs-next, of course, since there is no such
file.  Looking in linux-next, I see a few things to comment on beyond
these issues...

 - We *really* don't want to be adding more files like this to the top
   level; we have a directory hierarchy for a reason.  This looks like it
   belongs (mostly) in the core-api manual.

 - Can the user-space example be instead turned into a working program
   under samples (or perhaps a test under tests/)?

The first of these, at least, I would really like to see fixed before this
goes upstream.

Thanks,

jon

Re: [PATCH 4/9] docs: driver.rst: supress two ReSt warnings

[Jonathan Corbet]

On Tue,  3 Mar 2020 16:50:34 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Get rid of those, by marking a literal block as such:
> 
> 	Documentation/driver-api/gpio/driver.rst:425: WARNING: Unexpected indentation.
> 	Documentation/driver-api/gpio/driver.rst:423: WARNING: Inline emphasis start-string without end-string.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/driver-api/driver-model/driver.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
> index baa6a85c8287..63887b813005 100644
> --- a/Documentation/driver-api/driver-model/driver.rst
> +++ b/Documentation/driver-api/driver-model/driver.rst
> @@ -210,7 +210,7 @@ probed.
>  While the typical use case for sync_state() is to have the kernel cleanly take
>  over management of devices from the bootloader, the usage of sync_state() is
>  not restricted to that. Use it whenever it makes sense to take an action after
> -all the consumers of a device have probed.
> +all the consumers of a device have probed::

Applied, thanks.

jon

Re: [PATCH 6/9] docs: translations: it: avoid duplicate refs at programming-language.rst

[Jonathan Corbet]

On Tue,  3 Mar 2020 16:50:36 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> As the translations document is part of the main body, we can't
> keep duplicated references there. So, prefix the Italian ones
> with "it-".
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied, thanks.

jon

Re: [PATCH 7/9] docs: filesystems: fuse.rst: supress a Sphinx warning

[Jonathan Corbet]

On Tue,  3 Mar 2020 16:50:37 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Get rid of this warning:
> 
>     Documentation/filesystems/fuse.rst:2: WARNING: Explicit markup ends without a blank line; unexpected unindent.
> 
> Fixes: 8ab13bca428b ("Documentation: filesystems: convert fuse to RST")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/filesystems/fuse.rst | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)

Applied, thanks.

jon

Re: [PATCH 8/9] docs: perf: imx-ddr.rst: get rid of a warning

[Jonathan Corbet]

On Tue,  3 Mar 2020 16:50:38 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

>     Documentation/admin-guide/perf/imx-ddr.rst:47: WARNING: Unexpected indentation.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/admin-guide/perf/imx-ddr.rst | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/admin-guide/perf/imx-ddr.rst b/Documentation/admin-guide/perf/imx-ddr.rst
> index 3726a10a03ba..f05f56c73b7d 100644
> --- a/Documentation/admin-guide/perf/imx-ddr.rst
> +++ b/Documentation/admin-guide/perf/imx-ddr.rst
> @@ -43,7 +43,8 @@ value 1 for supported.
>  
>    AXI_ID and AXI_MASKING are mapped on DPCR1 register in performance counter.
>    When non-masked bits are matching corresponding AXI_ID bits then counter is
> -  incremented. Perf counter is incremented if
> +  incremented. Perf counter is incremented if::
> +

Applied, thanks.

jon

Re: [PATCH 9/9] docs: hw-vuln: tsx_async_abort.rst: get rid of an unused ref

[Jonathan Corbet]

On Tue,  3 Mar 2020 16:50:39 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> The virt_mechanism reference there points to a section
> called elsewhere (Virtualization mitigation). Also, it is
> not used anywere.
> 
> Besides that, it conflicts with a label with the same name
> inside:
> 
> 	Documentation/admin-guide/hw-vuln/mds.rst
> 
> Perhaps added due to some cut-and-paste?
> 
> Anyway, as this is not used, let's just get rid of it.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---

Applied, thanks.

jon

Re: [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings

[David Howells]

Jonathan Corbet <corbet@lwn.net> wrote:

>  - We *really* don't want to be adding more files like this to the top
>    level; we have a directory hierarchy for a reason.  This looks like it
>    belongs (mostly) in the core-api manual.

Sure.  Btw, the core-api/ is a bit of a miscellaneous bag - errseq, for
example, should probably be in filesystems/.

>  - Can the user-space example be instead turned into a working program
>    under samples (or perhaps a test under tests/)?

There is a working sample under samples/ also. See:

	https://lore.kernel.org/linux-fsdevel/158375623086.334846.16121725232323108842.stgit@warthog.procyon.org.uk/T/#t

patches 7, 14 and 17.

But no, this needs to be documented in the documentation also.  Manual pages
and testing (at least of key notifications) are available in a branch of the
keyutils package.

Actually, I need to amend my document to remove references to usb and block
notifications.

David

Re: [PATCH 2/9] docs: watch_queue.rst: supress some Sphinx warnings

[Mauro Carvalho Chehab]

Em Tue, 10 Mar 2020 18:29:18 +0000
David Howells <dhowells@redhat.com> escreveu:

> Jonathan Corbet <corbet@lwn.net> wrote:
> 
> >  - We *really* don't want to be adding more files like this to the top
> >    level; we have a directory hierarchy for a reason.  This looks like it
> >    belongs (mostly) in the core-api manual.  
> 
> Sure.  Btw, the core-api/ is a bit of a miscellaneous bag - errseq, for
> example, should probably be in filesystems/.
> 
> >  - Can the user-space example be instead turned into a working program
> >    under samples (or perhaps a test under tests/)?  
> 
> There is a working sample under samples/ also. See:
> 
> 	https://lore.kernel.org/linux-fsdevel/158375623086.334846.16121725232323108842.stgit@warthog.procyon.org.uk/T/#t
> 
> patches 7, 14 and 17.

Well, you could include the complete example from samples at the end of
this file, using a code block with:

	.. literalinclude:: /samples/foo.c
	   :language: c

This will display the Sphinx output files there at the html/pdf output,
as if it is part of the watch_queue.rst, and use the C code highlight.

> 
> But no, this needs to be documented in the documentation also.  Manual pages
> and testing (at least of key notifications) are available in a branch of the
> keyutils package.
> 
> Actually, I need to amend my document to remove references to usb and block
> notifications.
> 
> David
>