mirrors/linux
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-12-27 12:21:22 -05:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text

Browse Source 
Diagram explanation text is supposed to be interleaved commentary
between diagram parts that are spread out, but it outputs ugly in
htmldocs due to trailing vertices as if both the explanation and the
diagram are in the same literal code block.

Trim trailing vertices.

Reviewed-by: Tom Zanussi <zanussi@kernel.org>
Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250916054202.582074-4-bagasdotme@gmail.com>
This commit is contained in:
Bagas Sanjaya
2025-09-16 12:42:00 +07:00
committed by Jonathan Corbet
parent 348b7ca8d3
commit f867a298ac
1 changed files with 69 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -142,30 +142,30 @@ 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. | |
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. | |
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). | |
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 | |
.val member points to a map_elt containing the full key and an entry | |
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. | |
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
.val member points to a map_elt containing the full key and an entry
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 | |
The diagram attempts to show the relationship between the
hist_data.fields[] and the map_elt.fields[] with the links drawn
between diagrams::
+-----------+ | |
@@ -440,31 +440,31 @@ 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. | | |
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(). | | |
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. | | |
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 | | |
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 | | |
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
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.::
+-----------+ | | |
@@ -565,40 +565,40 @@ hist_data fields[] members.::
| | | |
+---------------+ | |
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. | |
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 | |
---------------------- | |
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 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. | |
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 | |
a particular variable on a particular histogram. The var_ref_idx is | |
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. | |
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
a particular variable on a particular histogram. The var_ref_idx is
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 | |
The diagram below describes the situation for the sched_switch
histogram referred to before::
# echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> | |
events/sched/sched_switch/trigger | |
# echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >>
events/sched/sched_switch/trigger
| |
+------------------+ | |
| hist_data | | |