Commit daceabf1 authored by Tom Zanussi's avatar Tom Zanussi Committed by Steven Rostedt (VMware)
Browse files

tracing/doc: Fix ascii-art in histogram-design.rst 

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.

Link: https://lkml.kernel.org/r/69c291c76964642a417e5dd170d183ba6b552010.camel@kernel.org



Reported-by: default avatarStephen Rothwell <sfr@canb.auug.org.au>
Tested-by: default avatarStephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: default avatarTom Zanussi <zanussi@kernel.org>
Signed-off-by: default avatarSteven Rostedt (VMware) <rostedt@goodmis.org>
parent c200784a

Documentation/trace/histogram-design.rst

+24 −24
Original line number Diff line number Diff line
@@ -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                                 | |

                                                                            | |

CRA Git | Maintained and supported by SUSTech CRA and CCSE