[PATCH 0/5] histogram docs formatting cleanup

[PATCH 0/5] histogram docs formatting cleanup

[Bagas Sanjaya]

Hi,

Here's a formatting assortment for trace histogram docs. The shortlog
below should be self-explanatory.

Enjoy!

Bagas Sanjaya (5):
  Documentation: trace: histogram: Fix histogram trigger subsection
    number order
  Documentation: trace: histogram-design: Trim trailing vertices in
    diagram explanation text
  Documentation: trace: historgram-design: Separate sched_waking
    histogram section heading and the following diagram
  Documentation: trace: histogram-design: Wrap introductory note in
    note:: directive
  Documentation: trace: histogram: Link to ftrace docs

 Documentation/trace/histogram-design.rst | 151 ++++++++++++-----------
 Documentation/trace/histogram.rst        |  38 +++---
 2 files changed, 96 insertions(+), 93 deletions(-)


base-commit: f44a29784f685804d9970cfb0d3439c9e30981d7
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/5] Documentation: trace: histogram: Fix histogram trigger subsection number order

[Bagas Sanjaya]

Section numbering in subsections of "Histogram Trigger Command" sections
is inconsistent in order. In particular, "'hist' trigger examples" is
erroneously numbered as 6.2, which is a leftover from  b8df4a3634e08a
("tracing: Move hist trigger Documentation to histogram.txt").

Fix the order.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/trace/histogram.rst | 34 +++++++++++++++----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
index af6d2e15568ebd..d158dadaa42447 100644
--- a/Documentation/trace/histogram.rst
+++ b/Documentation/trace/histogram.rst
@@ -186,8 +186,8 @@ Documentation written by Tom Zanussi
   The examples below provide a more concrete illustration of the
   concepts and typical usage patterns discussed above.
 
-'special' event fields
-------------------------
+2.1. 'special' event fields
+---------------------------
 
   There are a number of 'special event fields' available for use as
   keys or values in a hist trigger.  These look like and behave as if
@@ -204,16 +204,16 @@ Documentation written by Tom Zanussi
     common_cpu             int  the cpu on which the event occurred.
     ====================== ==== =======================================
 
-Extended error information
---------------------------
+2.2. Extended error information
+-------------------------------
 
   For some error conditions encountered when invoking a hist trigger
   command, extended error information is available via the
   tracing/error_log file.  See Error Conditions in
   :file:`Documentation/trace/ftrace.rst` for details.
 
-6.2 'hist' trigger examples
----------------------------
+2.3. 'hist' trigger examples
+----------------------------
 
   The first set of examples creates aggregations using the kmalloc
   event.  The fields that can be used for the hist trigger are listed
@@ -1608,8 +1608,8 @@ Extended error information
         Entries: 7
         Dropped: 0
 
-2.2 Inter-event hist triggers
------------------------------
+2.4. Inter-event hist triggers
+------------------------------
 
 Inter-event hist triggers are hist triggers that combine values from
 one or more other events and create a histogram using that data.  Data
@@ -1685,8 +1685,8 @@ pseudo-file.
 
 These features are described in more detail in the following sections.
 
-2.2.1 Histogram Variables
--------------------------
+2.5. Histogram Variables
+------------------------
 
 Variables are simply named locations used for saving and retrieving
 values between matching events.  A 'matching' event is defined as an
@@ -1789,8 +1789,8 @@ or assigned to a variable and referenced in a subsequent expression::
 
 Variables can even hold stacktraces, which are useful with synthetic events.
 
-2.2.2 Synthetic Events
-----------------------
+2.6. Synthetic Events
+---------------------
 
 Synthetic events are user-defined events generated from hist trigger
 variables or fields associated with one or more other events.  Their
@@ -1846,7 +1846,7 @@ the command that defined it with a '!'::
 At this point, there isn't yet an actual 'wakeup_latency' event
 instantiated in the event subsystem - for this to happen, a 'hist
 trigger action' needs to be instantiated and bound to actual fields
-and variables defined on other events (see Section 2.2.3 below on
+and variables defined on other events (see Section 2.7. below on
 how that is done using hist trigger 'onmatch' action). Once that is
 done, the 'wakeup_latency' synthetic event instance is created.
 
@@ -2094,8 +2094,8 @@ histogram::
     Entries: 7
     Dropped: 0
 
-2.2.3 Hist trigger 'handlers' and 'actions'
--------------------------------------------
+2.7. Hist trigger 'handlers' and 'actions'
+------------------------------------------
 
 A hist trigger 'action' is a function that's executed (in most cases
 conditionally) whenever a histogram entry is added or updated.
@@ -2526,8 +2526,8 @@ The following commonly-used handler.action pairs are available:
          kworker/3:2-135   [003] d..3    49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120
               <idle>-0     [004] ..s7    49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312
 
-3. User space creating a trigger
---------------------------------
+2.8. User space creating a trigger
+----------------------------------
 
 Writing into /sys/kernel/tracing/trace_marker writes into the ftrace
 ring buffer. This can also act like an event, by writing into the trigger
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/5] Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text

[Bagas Sanjaya]

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.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/trace/histogram-design.rst | 138 +++++++++++------------
 1 file changed, 69 insertions(+), 69 deletions(-)

diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
index 5765eb3e9efa78..231a12bd7d461c 100644
--- a/Documentation/trace/histogram-design.rst
+++ b/Documentation/trace/histogram-design.rst
@@ -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        |                                                      | |
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 3/5] Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram

[Bagas Sanjaya]

Section heading for sched_waking histogram is shown as normal paragraph
instead due to codeblock marker for the following diagram being in the
same line as the section underline. Separate them.

Fixes: daceabf1b494 ("tracing/doc: Fix ascii-art in histogram-design.rst")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/trace/histogram-design.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
index 231a12bd7d461c..4faff1669b77bd 100644
--- a/Documentation/trace/histogram-design.rst
+++ b/Documentation/trace/histogram-design.rst
@@ -380,7 +380,9 @@ entry, ts0, corresponding to the ts0 variable in the sched_waking
 trigger above.
 
 sched_waking histogram
-----------------------::
+----------------------
+
+.. code-block::
 
   +------------------+
   | hist_data        |<-------------------------------------------------------+
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 4/5] Documentation: trace: histogram-design: Wrap introductory note in note:: directive

[Bagas Sanjaya]

Use Sphinx note:: directive for the introductory note at the beginning
of docs, instead of aligned-text paragraph that renders as definition
list.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/trace/histogram-design.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
index 4faff1669b77bd..ae71b5bf97c6c7 100644
--- a/Documentation/trace/histogram-design.rst
+++ b/Documentation/trace/histogram-design.rst
@@ -11,13 +11,14 @@ histograms work and how the individual pieces map to the data
 structures used to implement them in trace_events_hist.c and
 tracing_map.c.
 
-Note: All the ftrace histogram command examples assume the working
-      directory is the ftrace /tracing directory. For example::
+.. note::
+   All the ftrace histogram command examples assume the working
+   directory is the ftrace /tracing directory. For example::
 
 	# cd /sys/kernel/tracing
 
-Also, the histogram output displayed for those commands will be
-generally be truncated - only enough to make the point is displayed.
+   Also, the histogram output displayed for those commands will be
+   generally be truncated - only enough to make the point is displayed.
 
 'hist_debug' trace event files
 ==============================
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 5/5] Documentation: trace: histogram: Link to ftrace docs

[Bagas Sanjaya]

In brief "Extended error information" section, details on error
condition is referred to ftrace docs. Add the link to it.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/trace/histogram.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
index d158dadaa42447..340bcb5099e7a4 100644
--- a/Documentation/trace/histogram.rst
+++ b/Documentation/trace/histogram.rst
@@ -209,8 +209,8 @@ Documentation written by Tom Zanussi
 
   For some error conditions encountered when invoking a hist trigger
   command, extended error information is available via the
-  tracing/error_log file.  See Error Conditions in
-  :file:`Documentation/trace/ftrace.rst` for details.
+  tracing/error_log file.  See "Error conditions" section in
+  Documentation/trace/ftrace.rst for details.
 
 2.3. 'hist' trigger examples
 ----------------------------
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 5/5] Documentation: trace: histogram: Link to ftrace docs

[Masami Hiramatsu]

On Thu, 11 Sep 2025 11:25:27 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> In brief "Extended error information" section, details on error
> condition is referred to ftrace docs. Add the link to it.

It seems this does not add the link. Can you make a tag and
link to it?

Thank you,

> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
> index d158dadaa42447..340bcb5099e7a4 100644
> --- a/Documentation/trace/histogram.rst
> +++ b/Documentation/trace/histogram.rst
> @@ -209,8 +209,8 @@ Documentation written by Tom Zanussi
>  
>    For some error conditions encountered when invoking a hist trigger
>    command, extended error information is available via the
> -  tracing/error_log file.  See Error Conditions in
> -  :file:`Documentation/trace/ftrace.rst` for details.
> +  tracing/error_log file.  See "Error conditions" section in
> +  Documentation/trace/ftrace.rst for details.
>  
>  2.3. 'hist' trigger examples
>  ----------------------------
> -- 
> An old man doll... just what I always wanted! - Clara
> 


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>

Re: [PATCH 1/5] Documentation: trace: histogram: Fix histogram trigger subsection number order

[Masami Hiramatsu]

On Thu, 11 Sep 2025 11:25:23 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> Section numbering in subsections of "Histogram Trigger Command" sections
> is inconsistent in order. In particular, "'hist' trigger examples" is
> erroneously numbered as 6.2, which is a leftover from  b8df4a3634e08a
> ("tracing: Move hist trigger Documentation to histogram.txt").
> 
> Fix the order.

Thanks for fixing. This looks good to me.

Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>

Thanks,

> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram.rst | 34 +++++++++++++++----------------
>  1 file changed, 17 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
> index af6d2e15568ebd..d158dadaa42447 100644
> --- a/Documentation/trace/histogram.rst
> +++ b/Documentation/trace/histogram.rst
> @@ -186,8 +186,8 @@ Documentation written by Tom Zanussi
>    The examples below provide a more concrete illustration of the
>    concepts and typical usage patterns discussed above.
>  
> -'special' event fields
> -------------------------
> +2.1. 'special' event fields
> +---------------------------
>  
>    There are a number of 'special event fields' available for use as
>    keys or values in a hist trigger.  These look like and behave as if
> @@ -204,16 +204,16 @@ Documentation written by Tom Zanussi
>      common_cpu             int  the cpu on which the event occurred.
>      ====================== ==== =======================================
>  
> -Extended error information
> ---------------------------
> +2.2. Extended error information
> +-------------------------------
>  
>    For some error conditions encountered when invoking a hist trigger
>    command, extended error information is available via the
>    tracing/error_log file.  See Error Conditions in
>    :file:`Documentation/trace/ftrace.rst` for details.
>  
> -6.2 'hist' trigger examples
> ----------------------------
> +2.3. 'hist' trigger examples
> +----------------------------
>  
>    The first set of examples creates aggregations using the kmalloc
>    event.  The fields that can be used for the hist trigger are listed
> @@ -1608,8 +1608,8 @@ Extended error information
>          Entries: 7
>          Dropped: 0
>  
> -2.2 Inter-event hist triggers
> ------------------------------
> +2.4. Inter-event hist triggers
> +------------------------------
>  
>  Inter-event hist triggers are hist triggers that combine values from
>  one or more other events and create a histogram using that data.  Data
> @@ -1685,8 +1685,8 @@ pseudo-file.
>  
>  These features are described in more detail in the following sections.
>  
> -2.2.1 Histogram Variables
> --------------------------
> +2.5. Histogram Variables
> +------------------------
>  
>  Variables are simply named locations used for saving and retrieving
>  values between matching events.  A 'matching' event is defined as an
> @@ -1789,8 +1789,8 @@ or assigned to a variable and referenced in a subsequent expression::
>  
>  Variables can even hold stacktraces, which are useful with synthetic events.
>  
> -2.2.2 Synthetic Events
> -----------------------
> +2.6. Synthetic Events
> +---------------------
>  
>  Synthetic events are user-defined events generated from hist trigger
>  variables or fields associated with one or more other events.  Their
> @@ -1846,7 +1846,7 @@ the command that defined it with a '!'::
>  At this point, there isn't yet an actual 'wakeup_latency' event
>  instantiated in the event subsystem - for this to happen, a 'hist
>  trigger action' needs to be instantiated and bound to actual fields
> -and variables defined on other events (see Section 2.2.3 below on
> +and variables defined on other events (see Section 2.7. below on
>  how that is done using hist trigger 'onmatch' action). Once that is
>  done, the 'wakeup_latency' synthetic event instance is created.
>  
> @@ -2094,8 +2094,8 @@ histogram::
>      Entries: 7
>      Dropped: 0
>  
> -2.2.3 Hist trigger 'handlers' and 'actions'
> --------------------------------------------
> +2.7. Hist trigger 'handlers' and 'actions'
> +------------------------------------------
>  
>  A hist trigger 'action' is a function that's executed (in most cases
>  conditionally) whenever a histogram entry is added or updated.
> @@ -2526,8 +2526,8 @@ The following commonly-used handler.action pairs are available:
>           kworker/3:2-135   [003] d..3    49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120
>                <idle>-0     [004] ..s7    49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312
>  
> -3. User space creating a trigger
> ---------------------------------
> +2.8. User space creating a trigger
> +----------------------------------
>  
>  Writing into /sys/kernel/tracing/trace_marker writes into the ftrace
>  ring buffer. This can also act like an event, by writing into the trigger
> -- 
> An old man doll... just what I always wanted! - Clara
> 


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>

Re: [PATCH 2/5] Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text

[Masami Hiramatsu]

On Thu, 11 Sep 2025 11:25:24 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> 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.

I got it (e.g. https://docs.kernel.org/trace/histogram-design.html),
yeah it should be removed.

Looks good to me.

Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>

> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram-design.rst | 138 +++++++++++------------
>  1 file changed, 69 insertions(+), 69 deletions(-)
> 
> diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
> index 5765eb3e9efa78..231a12bd7d461c 100644
> --- a/Documentation/trace/histogram-design.rst
> +++ b/Documentation/trace/histogram-design.rst
> @@ -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        |                                                      | |
> -- 
> An old man doll... just what I always wanted! - Clara
> 


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>

Re: [PATCH 3/5] Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram

[Masami Hiramatsu]

On Thu, 11 Sep 2025 11:25:25 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> Section heading for sched_waking histogram is shown as normal paragraph
> instead due to codeblock marker for the following diagram being in the
> same line as the section underline. Separate them.
> 

Looks good to me.

Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>

Thank you!

> Fixes: daceabf1b494 ("tracing/doc: Fix ascii-art in histogram-design.rst")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram-design.rst | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
> index 231a12bd7d461c..4faff1669b77bd 100644
> --- a/Documentation/trace/histogram-design.rst
> +++ b/Documentation/trace/histogram-design.rst
> @@ -380,7 +380,9 @@ entry, ts0, corresponding to the ts0 variable in the sched_waking
>  trigger above.
>  
>  sched_waking histogram
> -----------------------::
> +----------------------
> +
> +.. code-block::
>  
>    +------------------+
>    | hist_data        |<-------------------------------------------------------+
> -- 
> An old man doll... just what I always wanted! - Clara
> 


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>

Re: [PATCH 4/5] Documentation: trace: histogram-design: Wrap introductory note in note:: directive

[Masami Hiramatsu]

On Thu, 11 Sep 2025 11:25:26 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> Use Sphinx note:: directive for the introductory note at the beginning
> of docs, instead of aligned-text paragraph that renders as definition
> list.
> 

Looks good change ;)

Reviewed-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>

Thank you!

> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram-design.rst | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
> index 4faff1669b77bd..ae71b5bf97c6c7 100644
> --- a/Documentation/trace/histogram-design.rst
> +++ b/Documentation/trace/histogram-design.rst
> @@ -11,13 +11,14 @@ histograms work and how the individual pieces map to the data
>  structures used to implement them in trace_events_hist.c and
>  tracing_map.c.
>  
> -Note: All the ftrace histogram command examples assume the working
> -      directory is the ftrace /tracing directory. For example::
> +.. note::
> +   All the ftrace histogram command examples assume the working
> +   directory is the ftrace /tracing directory. For example::
>  
>  	# cd /sys/kernel/tracing
>  
> -Also, the histogram output displayed for those commands will be
> -generally be truncated - only enough to make the point is displayed.
> +   Also, the histogram output displayed for those commands will be
> +   generally be truncated - only enough to make the point is displayed.
>  
>  'hist_debug' trace event files
>  ==============================
> -- 
> An old man doll... just what I always wanted! - Clara
> 


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>

Re: [PATCH 5/5] Documentation: trace: histogram: Link to ftrace docs

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 579 bytes --]

On Fri, Sep 12, 2025 at 09:58:27AM +0900, Masami Hiramatsu wrote:
> On Thu, 11 Sep 2025 11:25:27 +0700
> Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> 
> > In brief "Extended error information" section, details on error
> > condition is referred to ftrace docs. Add the link to it.
> 
> It seems this does not add the link. Can you make a tag and
> link to it?

Nope.

What the patch does instead is to convert :file: markup to proper
cross-reference. I will fix the patch description in v2.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 1/5] Documentation: trace: histogram: Fix histogram trigger subsection number order

[Tom Zanussi]

On Thu, 2025-09-11 at 11:25 +0700, Bagas Sanjaya wrote:
> Section numbering in subsections of "Histogram Trigger Command"
> sections
> is inconsistent in order. In particular, "'hist' trigger examples" is
> erroneously numbered as 6.2, which is a leftover from  b8df4a3634e08a
> ("tracing: Move hist trigger Documentation to histogram.txt").
> 
> Fix the order.

Looks good to me, thanks!

Reviewed-by: Tom Zanussi <zanussi@kernel.org>

> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram.rst | 34 +++++++++++++++--------------
> --
>  1 file changed, 17 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/trace/histogram.rst
> b/Documentation/trace/histogram.rst
> index af6d2e15568ebd..d158dadaa42447 100644
> --- a/Documentation/trace/histogram.rst
> +++ b/Documentation/trace/histogram.rst
> @@ -186,8 +186,8 @@ Documentation written by Tom Zanussi
>    The examples below provide a more concrete illustration of the
>    concepts and typical usage patterns discussed above.
>  
> -'special' event fields
> -------------------------
> +2.1. 'special' event fields
> +---------------------------
>  
>    There are a number of 'special event fields' available for use as
>    keys or values in a hist trigger.  These look like and behave as
> if
> @@ -204,16 +204,16 @@ Documentation written by Tom Zanussi
>      common_cpu             int  the cpu on which the event occurred.
>      ====================== ====
> =======================================
>  
> -Extended error information
> ---------------------------
> +2.2. Extended error information
> +-------------------------------
>  
>    For some error conditions encountered when invoking a hist trigger
>    command, extended error information is available via the
>    tracing/error_log file.  See Error Conditions in
>    :file:`Documentation/trace/ftrace.rst` for details.
>  
> -6.2 'hist' trigger examples
> ----------------------------
> +2.3. 'hist' trigger examples
> +----------------------------
>  
>    The first set of examples creates aggregations using the kmalloc
>    event.  The fields that can be used for the hist trigger are
> listed
> @@ -1608,8 +1608,8 @@ Extended error information
>          Entries: 7
>          Dropped: 0
>  
> -2.2 Inter-event hist triggers
> ------------------------------
> +2.4. Inter-event hist triggers
> +------------------------------
>  
>  Inter-event hist triggers are hist triggers that combine values from
>  one or more other events and create a histogram using that data. 
> Data
> @@ -1685,8 +1685,8 @@ pseudo-file.
>  
>  These features are described in more detail in the following
> sections.
>  
> -2.2.1 Histogram Variables
> --------------------------
> +2.5. Histogram Variables
> +------------------------
>  
>  Variables are simply named locations used for saving and retrieving
>  values between matching events.  A 'matching' event is defined as an
> @@ -1789,8 +1789,8 @@ or assigned to a variable and referenced in a
> subsequent expression::
>  
>  Variables can even hold stacktraces, which are useful with synthetic
> events.
>  
> -2.2.2 Synthetic Events
> -----------------------
> +2.6. Synthetic Events
> +---------------------
>  
>  Synthetic events are user-defined events generated from hist trigger
>  variables or fields associated with one or more other events.  Their
> @@ -1846,7 +1846,7 @@ the command that defined it with a '!'::
>  At this point, there isn't yet an actual 'wakeup_latency' event
>  instantiated in the event subsystem - for this to happen, a 'hist
>  trigger action' needs to be instantiated and bound to actual fields
> -and variables defined on other events (see Section 2.2.3 below on
> +and variables defined on other events (see Section 2.7. below on
>  how that is done using hist trigger 'onmatch' action). Once that is
>  done, the 'wakeup_latency' synthetic event instance is created.
>  
> @@ -2094,8 +2094,8 @@ histogram::
>      Entries: 7
>      Dropped: 0
>  
> -2.2.3 Hist trigger 'handlers' and 'actions'
> --------------------------------------------
> +2.7. Hist trigger 'handlers' and 'actions'
> +------------------------------------------
>  
>  A hist trigger 'action' is a function that's executed (in most cases
>  conditionally) whenever a histogram entry is added or updated.
> @@ -2526,8 +2526,8 @@ The following commonly-used handler.action
> pairs are available:
>           kworker/3:2-135   [003] d..3    49.823123: sched_switch:
> prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==>
> next_comm=swapper/3 next_pid=0 next_prio=120
>                <idle>-0     [004] ..s7    49.823798: tcp_probe:
> src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32
> snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647
> snd_wnd=28960 srtt=19604 rcv_wnd=29312
>  
> -3. User space creating a trigger
> ---------------------------------
> +2.8. User space creating a trigger
> +----------------------------------
>  
>  Writing into /sys/kernel/tracing/trace_marker writes into the ftrace
>  ring buffer. This can also act like an event, by writing into the
> trigger

Re: [PATCH 2/5] Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text

[Tom Zanussi]

On Thu, 2025-09-11 at 11:25 +0700, Bagas Sanjaya wrote:
> 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.

Yes, this is much better, and the lines are still followable in the
text version. Thanks,

Reviewed-by: Tom Zanussi <zanussi@kernel.org>

> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram-design.rst | 138 +++++++++++----------
> --
>  1 file changed, 69 insertions(+), 69 deletions(-)
> 
> diff --git a/Documentation/trace/histogram-design.rst
> b/Documentation/trace/histogram-design.rst
> index 5765eb3e9efa78..231a12bd7d461c 100644
> --- a/Documentation/trace/histogram-design.rst
> +++ b/Documentation/trace/histogram-design.rst
> @@ -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       
> |                                                      | |

Re: [PATCH 3/5] Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram

[Tom Zanussi]

On Thu, 2025-09-11 at 11:25 +0700, Bagas Sanjaya wrote:
> Section heading for sched_waking histogram is shown as normal
> paragraph
> instead due to codeblock marker for the following diagram being in
> the
> same line as the section underline. Separate them.
> 
> 

Small typo in the subject line, s/historgram/histogram but otherwise
looks good.

Thanks,

Reviewed-by: Tom Zanussi <zanussi@kernel.org>

> Fixes: daceabf1b494 ("tracing/doc: Fix ascii-art in histogram-
> design.rst")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram-design.rst | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/trace/histogram-design.rst
> b/Documentation/trace/histogram-design.rst
> index 231a12bd7d461c..4faff1669b77bd 100644
> --- a/Documentation/trace/histogram-design.rst
> +++ b/Documentation/trace/histogram-design.rst
> @@ -380,7 +380,9 @@ entry, ts0, corresponding to the ts0 variable in
> the sched_waking
>  trigger above.
>  
>  sched_waking histogram
> -----------------------::
> +----------------------
> +
> +.. code-block::
>  
>    +------------------+
>    | hist_data        |<---------------------------------------------
> ----------+

Re: [PATCH 4/5] Documentation: trace: histogram-design: Wrap introductory note in note:: directive

[Tom Zanussi]

On Thu, 2025-09-11 at 11:25 +0700, Bagas Sanjaya wrote:
> Use Sphinx note:: directive for the introductory note at the
> beginning
> of docs, instead of aligned-text paragraph that renders as definition
> list.

Reviewed-by: Tom Zanussi <zanussi@kernel.org>

> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram-design.rst | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/trace/histogram-design.rst
> b/Documentation/trace/histogram-design.rst
> index 4faff1669b77bd..ae71b5bf97c6c7 100644
> --- a/Documentation/trace/histogram-design.rst
> +++ b/Documentation/trace/histogram-design.rst
> @@ -11,13 +11,14 @@ histograms work and how the individual pieces map
> to the data
>  structures used to implement them in trace_events_hist.c and
>  tracing_map.c.
>  
> -Note: All the ftrace histogram command examples assume the working
> -      directory is the ftrace /tracing directory. For example::
> +.. note::
> +   All the ftrace histogram command examples assume the working
> +   directory is the ftrace /tracing directory. For example::
>  
>  	# cd /sys/kernel/tracing
>  
> -Also, the histogram output displayed for those commands will be
> -generally be truncated - only enough to make the point is displayed.
> +   Also, the histogram output displayed for those commands will be
> +   generally be truncated - only enough to make the point is
> displayed.
>  
>  'hist_debug' trace event files
>  ==============================

Re: [PATCH 5/5] Documentation: trace: histogram: Link to ftrace docs

[Tom Zanussi]

On Thu, 2025-09-11 at 11:25 +0700, Bagas Sanjaya wrote:
> In brief "Extended error information" section, details on error
> condition is referred to ftrace docs. Add the link to it.

Reviewed-by: Tom Zanussi <zanussi@kernel.org>

> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/trace/histogram.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/trace/histogram.rst
> b/Documentation/trace/histogram.rst
> index d158dadaa42447..340bcb5099e7a4 100644
> --- a/Documentation/trace/histogram.rst
> +++ b/Documentation/trace/histogram.rst
> @@ -209,8 +209,8 @@ Documentation written by Tom Zanussi
>  
>    For some error conditions encountered when invoking a hist trigger
>    command, extended error information is available via the
> -  tracing/error_log file.  See Error Conditions in
> -  :file:`Documentation/trace/ftrace.rst` for details.
> +  tracing/error_log file.  See "Error conditions" section in
> +  Documentation/trace/ftrace.rst for details.
>  
>  2.3. 'hist' trigger examples
>  ----------------------------