Skip to content

Commit daceabf

Browse files
Tom Zanussirostedt
Tom Zanussi
authored and
rostedt
committed
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/[email protected] Reported-by: Stephen Rothwell <[email protected]> Tested-by: Stephen Rothwell <[email protected]> Signed-off-by: Tom Zanussi <[email protected]> Signed-off-by: Steven Rostedt (VMware) <[email protected]>
1 parent c200784 commit daceabf

File tree

1 file changed

+24
-24
lines changed

1 file changed

+24
-24
lines changed

‎Documentation/trace/histogram-design.rst

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ tracing_map.c.
1414
Note: All the ftrace histogram command examples assume the working
1515
directory is the ftrace /tracing directory. For example::
1616

17-
# cd /sys/kernel/debug/tracing
17+
# cd /sys/kernel/debug/tracing
1818

1919
Also, the histogram output displayed for those commands will be
2020
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.
107107
Below that is a diagram of a run-time snapshot of what the tracing_map
108108
might look like for a given run. It attempts to show the
109109
relationships between the hist_data fields and the tracing_map
110-
elements for a couple hypothetical keys and values.
110+
elements for a couple hypothetical keys and values.::
111111

112112
+------------------+
113113
| hist_data |
@@ -141,20 +141,20 @@ elements for a couple hypothetical keys and values.
141141
| | | |
142142
+--------------+ | |
143143
n_keys = n_fields - n_vals | |
144-
| |
144+
145145
The hist_data n_vals and n_fields delineate the extent of the fields[] | |
146146
array and separate keys from values for the rest of the code. | |
147-
| |
147+
148148
Below is a run-time representation of the tracing_map part of the | |
149149
histogram, with pointers from various parts of the fields[] array | |
150150
to corresponding parts of the tracing_map. | |
151-
| |
151+
152152
The tracing_map consists of an array of tracing_map_entrys and a set | |
153153
of preallocated tracing_map_elts (abbreviated below as map_entry and | |
154154
map_elt). The total number of map_entrys in the hist_data.map array = | |
155155
map->max_elts (actually map->map_size but only max_elts of those are | |
156156
used. This is a property required by the map_insert() algorithm). | |
157-
| |
157+
158158
If a map_entry is unused, meaning no key has yet hashed into it, its | |
159159
.key value is 0 and its .val pointer is NULL. Once a map_entry has | |
160160
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 | |
163163
entry in the map_elt.fields[] array corresponding to each hist_field | |
164164
in the histogram, and this is where the continually aggregated sums | |
165165
corresponding to each histogram value are kept. | |
166-
| |
166+
167167
The diagram attempts to show the relationship between the | |
168168
hist_data.fields[] and the map_elt.fields[] with the links drawn | |
169-
between diagrams:: | |
170-
| |
169+
between diagrams::
170+
171171
+-----------+ | |
172172
| hist_data | | |
173173
+-----------+ | |
@@ -380,7 +380,7 @@ entry, ts0, corresponding to the ts0 variable in the sched_waking
380380
trigger above.
381381

382382
sched_waking histogram
383-
----------------------
383+
----------------------::
384384

385385
+------------------+
386386
| hist_data |<-------------------------------------------------------+
@@ -439,34 +439,34 @@ sched_waking histogram
439439
+-----------------+ | | |
440440
n_keys = n_fields - n_vals | | |
441441
| | |
442-
| | |
442+
443443
This is very similar to the basic case. In the above diagram, we can | | |
444444
see a new .flags member has been added to the struct hist_field | | |
445445
struct, and a new entry added to hist_data.fields representing the ts0 | | |
446446
variable. For a normal val hist_field, .flags is just 0 (modulo | | |
447447
modifier flags), but if the value is defined as a variable, the .flags | | |
448448
contains a set FL_VAR bit. | | |
449-
| | |
449+
450450
As you can see, the ts0 entry's .var.idx member contains the index | | |
451451
into the tracing_map_elts' .vars[] array containing variable values. | | |
452452
This idx is used whenever the value of the variable is set or read. | | |
453453
The map_elt.vars idx assigned to the given variable is assigned and | | |
454454
saved in .var.idx by create_tracing_map_fields() after it calls | | |
455455
tracing_map_add_var(). | | |
456-
| | |
456+
457457
Below is a representation of the histogram at run-time, which | | |
458458
populates the map, along with correspondence to the above hist_data and | | |
459459
hist_field data structures. | | |
460-
| | |
460+
461461
The diagram attempts to show the relationship between the | | |
462462
hist_data.fields[] and the map_elt.fields[] and map_elt.vars[] with | | |
463463
the links drawn between diagrams. For each of the map_elts, you can | | |
464464
see that the .fields[] members point to the .sum or .offset of a key | | |
465465
or val and the .vars[] members point to the value of a variable. The | | |
466466
arrows between the two diagrams show the linkages between those | | |
467467
tracing_map members and the field definitions in the corresponding | | |
468-
hist_data fields[] members. | | |
469-
| | |
468+
hist_data fields[] members.::
469+
470470
+-----------+ | | |
471471
| hist_data | | | |
472472
+-----------+ | | |
@@ -564,27 +564,27 @@ hist_data fields[] members. | | |
564564
| unused | | |
565565
| | | |
566566
+---------------+ | |
567-
| |
567+
568568
For each used map entry, there's a map_elt pointing to an array of | |
569569
.vars containing the current value of the variables associated with | |
570570
that histogram entry. So in the above, the timestamp associated with | |
571571
pid 999 is 113345679876, and the timestamp variable in the same | |
572572
.var.idx for pid 4444 is 213499240729. | |
573-
| |
573+
574574
sched_switch histogram | |
575575
---------------------- | |
576-
| |
576+
577577
The sched_switch histogram paired with the above sched_waking | |
578578
histogram is shown below. The most important aspect of the | |
579579
sched_switch histogram is that it references a variable on the | |
580580
sched_waking histogram above. | |
581-
| |
581+
582582
The histogram diagram is very similar to the others so far displayed, | |
583583
but it adds variable references. You can see the normal hitcount and | |
584584
key fields along with a new wakeup_lat variable implemented in the | |
585585
same way as the sched_waking ts0 variable, but in addition there's an | |
586586
entry with the new FL_VAR_REF (short for HIST_FIELD_FL_VAR_REF) flag. | |
587-
| |
587+
588588
Associated with the new var ref field are a couple of new hist_field | |
589589
members, var.hist_data and var_ref_idx. For a variable reference, the | |
590590
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 | |
593593
each variable whenever a hist trigger is updated. Those resulting | |
594594
values are then finally accessed by other code such as trace action | |
595595
code that uses the var_ref_idx values to assign param values. | |
596-
| |
596+
597597
The diagram below describes the situation for the sched_switch | |
598-
histogram referred to before: | |
599-
| |
598+
histogram referred to before::
599+
600600
# echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> | |
601601
events/sched/sched_switch/trigger | |
602602
| |

0 commit comments

Comments
 (0)