Subject: [PATCH] tracing/doc: Fix ascii-art in histogram-design.rst

From: Tom Zanussi <[email-masked]>
Date: Wed, 03 Jun 2020 10:21:24 -0500

This fixes the Sphinx parallel build error when building htmldocs:

  docutils.utils.SystemMessage: /home/sfr/next/next/Documentation/trace/histogram-design.rst:219: (SEVERE/4) Unexpected section title.

It also fixes a bunch of other warnings I noticed when fixing the
above, caused by mixing ascii-art and text.

Signed-off-by: Tom Zanussi <[email-masked]>
Reported-by: Stephen Rothwell <[email-masked]>
---
 Documentation/trace/histogram-design.rst | 48 ++++++++++++------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
index 06f5c7e5f2ee..eef840043da9 100644
--- a/Documentation/trace/histogram-design.rst
+++ b/Documentation/trace/histogram-design.rst
@@ -14,7 +14,7 @@ tracing_map.c.
 Note: All the ftrace histogram command examples assume the working
       directory is the ftrace /tracing directory. For example::
 
-  # cd /sys/kernel/debug/tracing
+	# cd /sys/kernel/debug/tracing
 
 Also, the histogram output displayed for those commands will be
 generally be truncated - only enough to make the point is displayed.
@@ -107,7 +107,7 @@ for the hitcount and one key field for the pid key.
 Below that is a diagram of a run-time snapshot of what the tracing_map
 might look like for a given run.  It attempts to show the
 relationships between the hist_data fields and the tracing_map
-elements for a couple hypothetical keys and values.
+elements for a couple hypothetical keys and values.::
 
   +------------------+
   | hist_data        |
@@ -141,20 +141,20 @@ elements for a couple hypothetical keys and values.
                              |              |                            |  |
                              +--------------+                            |  |
                                             n_keys = n_fields - n_vals   |  |
-		                                                         |  |
+
 The hist_data n_vals and n_fields delineate the extent of the fields[]   |  |
 array and separate keys from values for the rest of the code.            |  |
-		                                                         |  |
+
 Below is a run-time representation of the tracing_map part of the        |  |
 histogram, with pointers from various parts of the fields[] array        |  |
 to corresponding parts of the tracing_map.                               |  |
-		                                                         |  |
+
 The tracing_map consists of an array of tracing_map_entrys and a set     |  |
 of preallocated tracing_map_elts (abbreviated below as map_entry and     |  |
 map_elt).  The total number of map_entrys in the hist_data.map array =   |  |
 map->max_elts (actually map->map_size but only max_elts of those are     |  |
 used.  This is a property required by the map_insert() algorithm).       |  |
-		                                                         |  |
+
 If a map_entry is unused, meaning no key has yet hashed into it, its     |  |
 .key value is 0 and its .val pointer is NULL.  Once a map_entry has      |  |
 been claimed, the .key value contains the key's hash value and the       |  |
@@ -163,11 +163,11 @@ for each key or value in the map_elt.fields[] array.  There is an        |  |
 entry in the map_elt.fields[] array corresponding to each hist_field     |  |
 in the histogram, and this is where the continually aggregated sums      |  |
 corresponding to each histogram value are kept.                          |  |
-		                                                         |  |
+
 The diagram attempts to show the relationship between the                |  |
 hist_data.fields[] and the map_elt.fields[] with the links drawn         |  |
-between diagrams::                                                       |  |
-		                                                         |  |
+between diagrams::
+
   +-----------+		                                                 |  |
   | hist_data |		                                                 |  |
   +-----------+		                                                 |  |
@@ -380,7 +380,7 @@ entry, ts0, corresponding to the ts0 variable in the sched_waking
 trigger above.
 
 sched_waking histogram
-----------------------
+----------------------::
 
   +------------------+
   | hist_data        |<-------------------------------------------------------+
@@ -439,25 +439,25 @@ sched_waking histogram
                            +-----------------+                            | | |
                                              n_keys = n_fields - n_vals   | | |
                                                                           | | |
-                                                                          | | |
+
 This is very similar to the basic case.  In the above diagram, we can     | | |
 see a new .flags member has been added to the struct hist_field           | | |
 struct, and a new entry added to hist_data.fields representing the ts0    | | |
 variable.  For a normal val hist_field, .flags is just 0 (modulo          | | |
 modifier flags), but if the value is defined as a variable, the .flags    | | |
 contains a set FL_VAR bit.                                                | | |
-                                                                          | | |
+
 As you can see, the ts0 entry's .var.idx member contains the index        | | |
 into the tracing_map_elts' .vars[] array containing variable values.      | | |
 This idx is used whenever the value of the variable is set or read.       | | |
 The map_elt.vars idx assigned to the given variable is assigned and       | | |
 saved in .var.idx by create_tracing_map_fields() after it calls           | | |
 tracing_map_add_var().                                                    | | |
-                                                                          | | |
+
 Below is a representation of the histogram at run-time, which             | | |
 populates the map, along with correspondence to the above hist_data and   | | |
 hist_field data structures.                                               | | |
-                                                                          | | |
+
 The diagram attempts to show the relationship between the                 | | |
 hist_data.fields[] and the map_elt.fields[] and map_elt.vars[] with       | | |
 the links drawn between diagrams.  For each of the map_elts, you can      | | |
@@ -465,8 +465,8 @@ see that the .fields[] members point to the .sum or .offset of a key      | | |
 or val and the .vars[] members point to the value of a variable.  The     | | |
 arrows between the two diagrams show the linkages between those           | | |
 tracing_map members and the field definitions in the corresponding        | | |
-hist_data fields[] members.                                               | | |
-                                                                          | | |
+hist_data fields[] members.::
+
   +-----------+		                                                  | | |
   | hist_data |		                                                  | | |
   +-----------+		                                                  | | |
@@ -564,27 +564,27 @@ hist_data fields[] members.                                               | | |
                                                       | unused        |     | |
                                                       |               |     | |
                                                       +---------------+     | |
-                                                                            | |
+
 For each used map entry, there's a map_elt pointing to an array of          | |
 .vars containing the current value of the variables associated with         | |
 that histogram entry.  So in the above, the timestamp associated with       | |
 pid 999 is 113345679876, and the timestamp variable in the same             | |
 .var.idx for pid 4444 is 213499240729.                                      | |
-                                                                            | |
+
 sched_switch histogram                                                      | |
 ----------------------                                                      | |
-                                                                            | |
+
 The sched_switch histogram paired with the above sched_waking               | |
 histogram is shown below.  The most important aspect of the                 | |
 sched_switch histogram is that it references a variable on the              | |
 sched_waking histogram above.                                               | |
-                                                                            | |
+
 The histogram diagram is very similar to the others so far displayed,       | |
 but it adds variable references.  You can see the normal hitcount and       | |
 key fields along with a new wakeup_lat variable implemented in the          | |
 same way as the sched_waking ts0 variable, but in addition there's an       | |
 entry with the new FL_VAR_REF (short for HIST_FIELD_FL_VAR_REF) flag.       | |
-                                                                            | |
+
 Associated with the new var ref field are a couple of new hist_field        | |
 members, var.hist_data and var_ref_idx.  For a variable reference, the      | |
 var.hist_data goes with the var.idx, which together uniquely identify       | |
@@ -593,10 +593,10 @@ just the index into the var_ref_vals[] array that caches the values of      | |
 each variable whenever a hist trigger is updated.  Those resulting          | |
 values are then finally accessed by other code such as trace action         | |
 code that uses the var_ref_idx values to assign param values.               | |
-                                                                            | |
+
 The diagram below describes the situation for the sched_switch              | |
-histogram referred to before:                                               | |
-                                                                            | |
+histogram referred to before::
+
   # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >>     | |
           events/sched/sched_switch/trigger                                 | |
                                                                             | |
-- 
2.17.1