hollalinux
/
linux-sg2042
mirror of https://github.com/sophgo/linux-riscv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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: Stephen Rothwell <sfr@canb.auug.org.au>
Tested-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Tom Zanussi <zanussi@kernel.org>
Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
This commit is contained in:
Tom Zanussi 2020-06-03 10:21:24 -05:00 committed by Steven Rostedt (VMware)
parent c200784a08
commit daceabf1b4
1 changed files with 24 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
Documentation/trace/histogram-design.rst
View File

@ -14,7 +14,7 @@ tracing_map.c.
Note: All the ftrace histogram command examples assume the working Note: All the ftrace histogram command examples assume the working
directory is the ftrace /tracing directory. For example:: 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 Also, the histogram output displayed for those commands will be
generally be truncated - only enough to make the point is displayed. 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 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 might look like for a given run. It attempts to show the
relationships between the hist_data fields and the tracing_map 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 | | hist_data |
@ -141,20 +141,20 @@ elements for a couple hypothetical keys and values.
| | | | | | | |
+--------------+ | | +--------------+ | |
n_keys = n_fields - n_vals | | n_keys = n_fields - n_vals | |
| |
The hist_data n_vals and n_fields delineate the extent of the fields[] | | 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. | | 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 | | Below is a run-time representation of the tracing_map part of the | |
histogram, with pointers from various parts of the fields[] array | | histogram, with pointers from various parts of the fields[] array | |
to corresponding parts of the tracing_map. | | to corresponding parts of the tracing_map. | |
| |
The tracing_map consists of an array of tracing_map_entrys and a set | | 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 | | 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_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 | | 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). | | 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 | | 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 | | .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 | | 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 | | entry in the map_elt.fields[] array corresponding to each hist_field | |
in the histogram, and this is where the continually aggregated sums | | in the histogram, and this is where the continually aggregated sums | |
corresponding to each histogram value are kept. | | corresponding to each histogram value are kept. | |
| |
The diagram attempts to show the relationship between the | | The diagram attempts to show the relationship between the | |
hist_data.fields[] and the map_elt.fields[] with the links drawn | | hist_data.fields[] and the map_elt.fields[] with the links drawn | |
between diagrams:: | | between diagrams::
| |
+-----------+ | | +-----------+ | |
| hist_data | | | | hist_data | | |
+-----------+ | | +-----------+ | |
@ -380,7 +380,7 @@ entry, ts0, corresponding to the ts0 variable in the sched_waking
trigger above. trigger above.
sched_waking histogram sched_waking histogram
---------------------- ----------------------::
+------------------+ +------------------+
| hist_data |<-------------------------------------------------------+ | hist_data |<-------------------------------------------------------+
@ -439,25 +439,25 @@ sched_waking histogram
+-----------------+ | | | +-----------------+ | | |
n_keys = n_fields - n_vals | | | n_keys = n_fields - n_vals | | |
| | | | | |
| | |
This is very similar to the basic case. In the above diagram, we can | | | 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 | | | 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 | | | 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 | | | 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 | | | modifier flags), but if the value is defined as a variable, the .flags | | |
contains a set FL_VAR bit. | | | contains a set FL_VAR bit. | | |
| | |
As you can see, the ts0 entry's .var.idx member contains the index | | | As you can see, the ts0 entry's .var.idx member contains the index | | |
into the tracing_map_elts' .vars[] array containing variable values. | | | into the tracing_map_elts' .vars[] array containing variable values. | | |
This idx is used whenever the value of the variable is set or read. | | | 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 | | | 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 | | | saved in .var.idx by create_tracing_map_fields() after it calls | | |
tracing_map_add_var(). | | | tracing_map_add_var(). | | |
| | |
Below is a representation of the histogram at run-time, which | | | Below is a representation of the histogram at run-time, which | | |
populates the map, along with correspondence to the above hist_data and | | | populates the map, along with correspondence to the above hist_data and | | |
hist_field data structures. | | | hist_field data structures. | | |
| | |
The diagram attempts to show the relationship between the | | | The diagram attempts to show the relationship between the | | |
hist_data.fields[] and the map_elt.fields[] and map_elt.vars[] with | | | 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 | | | 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 | | | or val and the .vars[] members point to the value of a variable. The | | |
arrows between the two diagrams show the linkages between those | | | arrows between the two diagrams show the linkages between those | | |
tracing_map members and the field definitions in the corresponding | | | tracing_map members and the field definitions in the corresponding | | |
hist_data fields[] members. | | | hist_data fields[] members.::
| | |
+-----------+ | | | +-----------+ | | |
| hist_data | | | | | hist_data | | | |
+-----------+ | | | +-----------+ | | |
@ -564,27 +564,27 @@ hist_data fields[] members. | | |
| unused | | | | unused | | |
| | | | | | | |
+---------------+ | | +---------------+ | |
| |
For each used map entry, there's a map_elt pointing to an array of | | 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 | | .vars containing the current value of the variables associated with | |
that histogram entry. So in the above, the timestamp associated with | | that histogram entry. So in the above, the timestamp associated with | |
pid 999 is 113345679876, and the timestamp variable in the same | | pid 999 is 113345679876, and the timestamp variable in the same | |
.var.idx for pid 4444 is 213499240729. | | .var.idx for pid 4444 is 213499240729. | |
| |
sched_switch histogram | | sched_switch histogram | |
---------------------- | | ---------------------- | |
| |
The sched_switch histogram paired with the above sched_waking | | The sched_switch histogram paired with the above sched_waking | |
histogram is shown below. The most important aspect of the | | histogram is shown below. The most important aspect of the | |
sched_switch histogram is that it references a variable on the | | sched_switch histogram is that it references a variable on the | |
sched_waking histogram above. | | sched_waking histogram above. | |
| |
The histogram diagram is very similar to the others so far displayed, | | The histogram diagram is very similar to the others so far displayed, | |
but it adds variable references. You can see the normal hitcount and | | but it adds variable references. You can see the normal hitcount and | |
key fields along with a new wakeup_lat variable implemented in the | | 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 | | 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. | | 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 | | 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 | | 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 | | 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 | | each variable whenever a hist trigger is updated. Those resulting | |
values are then finally accessed by other code such as trace action | | values are then finally accessed by other code such as trace action | |
code that uses the var_ref_idx values to assign param values. | | code that uses the var_ref_idx values to assign param values. | |
| |
The diagram below describes the situation for the sched_switch | | 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' >> | | # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> | |
events/sched/sched_switch/trigger | | events/sched/sched_switch/trigger | |
| | | |