Documentation/trace/histogram-design.rst

90 indicates which type of field it is - key, value, variable, variable
378 map_elt specifically designed to store and retrieve variable values.
379 The diagram below shows those new elements and adds a new variable
380 entry, ts0, corresponding to the ts0 variable in the sched_waking
449 variable.  For a normal val hist_field, .flags is just 0 (modulo
450 modifier flags), but if the value is defined as a variable, the .flags
454 into the tracing_map_elts' .vars[] array containing variable values.
455 This idx is used whenever the value of the variable is set or read.
456 The map_elt.vars idx assigned to the given variable is assigned and
468 or val and the .vars[] members point to the value of a variable.  The
574 pid 999 is 113345679876, and the timestamp variable in the same
582 sched_switch histogram is that it references a variable on the
586 but it adds variable references.  You can see the normal hitcount and
587 key fields along with a new wakeup_lat variable implemented in the
588 same way as the sched_waking ts0 variable, but in addition there's an
592 members, var.hist_data and var_ref_idx.  For a variable reference, the
594 a particular variable on a particular histogram.  The var_ref_idx is
596 each variable whenever a hist trigger is updated.  Those resulting
699 When a hist trigger makes use of a variable, a new hist_field is
702 variable, as well as the referenced variable's size, type, and
704 variable it references.  If a variable reference was created using the
709 because we have a reference to a variable on another histogram, we
710 need to resolve all variable references first.  This is done via the
714 variable's var.hist_data along with the current key is used to look up
716 referenced variable's var.idx is used to look up the variable's value
718 the variable for that element, ts0 in the case above.  Note that both
719 the hist_fields representing both the variable and the variable
722 Variable and variable reference test
725 This example creates a variable on the sched_waking event, ts0, and
727 creates its own variable, wakeup_lat, but nothing yet uses it::
736 represents a variable.  Note that in addition to the variable name,
738 index into the tracing_map_elt.vars[] array of the actual variable
784 to the unused wakeup_lat variable, we see a new section displaying
785 variable references.  Variable references are displayed in a separate
791 variable on the sched_waking trigger, $ts0.  Looking at the details,
792 we can see that the var.hist_data value of the referenced variable
795 variable.  Also displayed is the var_ref_idx value for that variable
796 reference, which is where the value for that variable is cached for
840   variable reference fields:
863 wakeup_lat variable, namely send it and another field as a synthetic
876 variables.  In this case, $wakeup_lat is obviously a variable, but
881 the covers, a temporary variable is created for the named field, and
882 this variable is what is actually passed to the trace handler.  In the
883 code and documentation, this type of variable is called a 'field
884 variable'.
889 synthetic events) and use that special histogram field as a variable.
907 means it will be automatically converted into a field variable::
1055 As you can see, for a field variable, two hist_fields are created: one
1056 representing the variable, in this case next_pid, and one to actually
1058 field does.  These are created separately from normal variable
1062 $next_pid variable in the trace() action.
1064 Note that $wakeup_lat is also a variable reference, referencing the
1073 variable at the var.idx offset in the appropriate tracing_map_elt's
1074 variable at elt->vars[var.idx].
1095 trace() action field variable test
1099 of the wakeup_lat variable, but in addition also creates a couple of
1113 to the wakeup_lat variable, and finally use it along with a couple
1170 the actual variable locations for those variables in the
1174 also that those are the same values displayed for the variable
1175 references corresponding to those variables in the variable reference
1178 the matching - you can see that the first variable refers to the 0
1180 associated with that trigger), while the second variable refers to the
1182 variable references.
1228   variable reference fields:
1323 finally all those variable values are collected via references to them
1377 save() action field variable test
1447 reference to the variable being tracked, in this case the $wakeup_lat
1448 variable.  In order to perform the onmax() handler function, there
1449 also needs to be a variable that tracks the current maximum by getting
1451 an auto-generated variable named ' __max' has been created and is
1452 visible in the actions[].track_data.track_var variable.
1502   variable reference fields:
1627 field variable is created for the other event, but since an existing
1629 histogram with a matching variable is created and used, and we'll see
1644 which is a field name that needs to have a field variable created for
1646 it would seem that it wouldn't be possible to create a field variable
1649 with that is that it's not currently possible to define a new variable
1651 variable to the existing sched_waking histogram.  It is however
1654 define the new prio field variable on that.
1664 special histogram we created to provide the prio field variable.
1666 Looking at the second histogram below, we see a variable with the name
1667 synthetic_prio.  This is the field variable created for the prio field
1753 the synthetic_prio variable on sched_waking, and looking at the
1756 normal variable, wakeup_lat, and to a normal field variable, next_pid,
1800   variable reference fields:
1886 but in this case we save the pid in the waking_pid variable::
1898 normal fields, we can see the waking_pid variable::
1951 The sched_switch hist_debug output shows that a variable named
1956 Despite that implementation detail, an alias variable is actually more
1957 like a variable reference; in fact it can be thought of as a reference
1959 variable reference being referenced, in this case, the waking_pid
1962 variable reference it's using, so waking_pid's var_ref_idx is also
1968 as the var_ref_idx of the reference, waking_pid, in the variable
1971 Additionally, once it gets that value, since it is also a variable, it
1975 there's a woken_pid var_ref in the variable refs section.  That is the
1976 reference to the woken_pid alias variable, and you can see that it
2034   variable reference fields: