diff options
| -rw-r--r-- | Documentation/trace/histogram-design.rst | 48 |
1 files 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 | | | | |