[4/4] gprofng: document HW-counter interface
Checks
| Context |
Check |
Description |
| linaro-tcwg-bot/tcwg_binutils_build--master-aarch64 |
success
|
Build passed
|
| linaro-tcwg-bot/tcwg_binutils_check--master-aarch64 |
success
|
Test passed
|
Commit Message
The existing "Inclusive and Exclusive Metrics" section explains the
distinction at the function level but does not state that the same
reasoning applies in source/disassembly views, where a line without a
call necessarily has Excl == Incl. The "Hardware Event Counters
Explained" appendix lists the limitations of HW counters but does not
mention sample skid nor the distinction between precise (PEBS/IBS)
and standard events.
gprofng/
* doc/gprofng_ug.texi (Inclusive and Exclusive Metrics):
Note that lines without function calls have identical
inclusive and exclusive values in source/disassembly views.
(Hardware Event Counters Explained): Add an note describing the
precise/standard-event distinction.
(Getting Information on the Counters Supported): Describe the
Precise events/Standard events grouping.
---
gprofng/doc/gprofng_ug.texi | 52 +++++++++++++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
@@ -2595,6 +2595,27 @@ Raw HW counters:
As can be seen, these names are not always easy to correlate to a specific
event of interest. The processor manual should provide more clarity on this.
+@cindex Precise event
+The alias listing and the raw-counter listing are each split into two
+subsections labeled ``Precise events'' and ``Standard events''. Precise
+events (PEBS on Intel, IBS on AMD) tag the sample with the program counter
+of the retiring instruction, and should be preferred for source-line and
+instruction-level analysis. Standard events are subject to skid: the
+reported program counter may be several instructions past the one that
+caused the event, which most commonly shows up as counts attributed to the
+control statement of a hot loop rather than to the instruction in the loop
+body that actually missed. @xref{Hardware Event Counters Explained} for
+more on skid and the precise/standard distinction. In the column labeled
+@code{type}, precise events are tagged @code{memoryspace (precise)}, while
+standard events show types such as @code{load}, @code{store}, or are left
+blank when no backtracking is supported.
+
+When the marker @code{(*)} appears in a column header of a
+@code{gprofng display text} report, it indicates that the counter feeding
+that column is a standard (non-precise) event and that source-line
+attribution for that column may skid. A footnote below the column header
+block describes the marker and points back to this section.
+
@c -- A new node --------------------------------------------------------------
@node Examples Using Hardware Event Counters
@subsection Examples Using Hardware Event Counters
@@ -3940,6 +3961,13 @@ In case of a @emph{leaf function}, the inclusive and exclusive values for the
metric are the same since by definition, it is not calling any other
function(s).
+The same reasoning applies in the @emph{source} and @emph{disassembly} views,
+which attribute metrics to individual lines or instructions. A line that
+contains no function call has no callees, so its inclusive and exclusive
+values are identical. This is expected and not a defect of the report; the
+two columns only diverge for lines (such as a function-call statement) whose
+inclusive value rolls up the cost incurred inside the callee.
+
Why do we use these two different values? The inclusive metric shows the most
expensive path, in terms of this metric, in the application. For example, if
the metric is cache misses, the function with the highest inclusive metric
@@ -4273,6 +4301,30 @@ to cover all the events of interest.
The names of the events may also not be easy to interpret. In such cases,
the description can be found in the architecture manual for the processor.
+@cindex Skid
+@cindex Precise event
+@item
+For most hardware events, the program counter (PC) sampled when the counter
+overflows is not the PC of the instruction that actually caused the event.
+The interrupt is delivered several instructions later, after the relevant
+instruction has already retired. This delay is called @emph{skid} and
+typically pushes the sampled PC forward, often onto the next basic block.
+In a hot loop, for example, cache misses originating in the loop body may
+be reported against the loop's control statement (the @code{for} or
+@code{while} line at the top of the loop). When the report shows
+unexpectedly high counts on a line that does little observable work, skid
+is the most likely explanation; consulting the @emph{disassembly} view
+will show on which individual instruction the samples actually landed.
+
+Some processors provide a second class of events, called @emph{precise}
+events, that do not skid. On Intel processors this mechanism is called
+@emph{PEBS}, and on AMD processors it is called @emph{IBS}. When precise
+events are available for the metric of interest, they should be preferred
+for source-line and instruction-level analysis. @ToolName{} lists precise
+events in a dedicated subsection of the output of
+@code{gprofng collect app -h}, separately from the skid-prone standard
+events; @xref{Getting Information on the Counters Supported}.
+
@end itemize
Despite these drawbacks, hardware event counters are extremely useful and