Re: [PATCH] tracing: Documentation: Update histogram-design.rst for fn() handling

[Steven Rostedt]

Hi Jon,

Can you take this through your tree?

Thanks,

-- Steve


On Mon, 26 Jan 2026 18:17:42 -0500
Steven Rostedt <rostedt@xxxxxxxxxxx> wrote:

> From: Steven Rostedt <rostedt@xxxxxxxxxxx>
> 
> The histogram documentation describes the old method of the histogram
> triggers using the fn() field of the histogram field structure to process
> the field. But due to Spectre mitigation, the function pointer to handle
> the fields at runtime caused a noticeable overhead. It was converted over
> to a fn_num and hist_fn_call() is now used to call the specific functions
> for the fields via a switch statement based on the field's fn_num value.
> 
> Update the documentation to reflect this change.
> 
> Signed-off-by: Steven Rostedt (Google) <rostedt@xxxxxxxxxxx>
> ---
>  Documentation/trace/histogram-design.rst | 20 +++++++++++++-------
>  1 file changed, 13 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
> index ae71b5bf97c6..e92f56ebd0b5 100644
> --- a/Documentation/trace/histogram-design.rst
> +++ b/Documentation/trace/histogram-design.rst
> @@ -69,7 +69,8 @@ So in this histogram, there's a separate bucket for each pid, and each
>  bucket contains a value for that bucket, counting the number of times
>  sched_waking was called for that pid.
>  
> -Each histogram is represented by a hist_data struct.
> +Each histogram is represented by a hist_data struct
> +(struct hist_trigger_data).
>  
>  To keep track of each key and value field in the histogram, hist_data
>  keeps an array of these fields named fields[].  The fields[] array is
> @@ -82,7 +83,7 @@ value or not, which the above histogram does not.
>  
>  Each struct hist_field contains a pointer to the ftrace_event_field
>  from the event's trace_event_file along with various bits related to
> -that such as the size, offset, type, and a hist_field_fn_t function,
> +that such as the size, offset, type, and a hist field function,
>  which is used to grab the field's data from the ftrace event buffer
>  (in most cases - some hist_fields such as hitcount don't directly map
>  to an event field in the trace buffer - in these cases the function
> @@ -241,28 +242,33 @@ it, event_hist_trigger() is called.  event_hist_trigger() first deals
>  with the key: for each subkey in the key (in the above example, there
>  is just one subkey corresponding to pid), the hist_field that
>  represents that subkey is retrieved from hist_data.fields[] and the
> -hist_field_fn_t fn() associated with that field, along with the
> +hist field function associated with that field, along with the
>  field's size and offset, is used to grab that subkey's data from the
>  current trace record.
>  
> +Note, the hist field function use to be a function pointer in the
> +hist_field stucture. Due to spectre mitigation, it was converted into
> +a fn_num and hist_fn_call() is used to call the associated hist field
> +function that corresponds to the fn_num of the hist_field structure.
> +
>  Once the complete key has been retrieved, it's used to look that key
>  up in the tracing_map.  If there's no tracing_map_elt associated with
>  that key, an empty one is claimed and inserted in the map for the new
>  key.  In either case, the tracing_map_elt associated with that key is
>  returned.
>  
> -Once a tracing_map_elt available, hist_trigger_elt_update() is called.
> +Once a tracing_map_elt is available, hist_trigger_elt_update() is called.
>  As the name implies, this updates the element, which basically means
>  updating the element's fields.  There's a tracing_map_field associated
>  with each key and value in the histogram, and each of these correspond
>  to the key and value hist_fields created when the histogram was
>  created.  hist_trigger_elt_update() goes through each value hist_field
> -and, as for the keys, uses the hist_field's fn() and size and offset
> +and, as for the keys, uses the hist_field's function and size and offset
>  to grab the field's value from the current trace record.  Once it has
>  that value, it simply adds that value to that field's
>  continually-updated tracing_map_field.sum member.  Some hist_field
> -fn()s, such as for the hitcount, don't actually grab anything from the
> -trace record (the hitcount fn() just increments the counter sum by 1),
> +functions, such as for the hitcount, don't actually grab anything from the
> +trace record (the hitcount function just increments the counter sum by 1),
>  but the idea is the same.
>  
>  Once all the values have been updated, hist_trigger_elt_update() is