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