Hi Tony,
On 8/29/25 12:33 PM, Tony Luck wrote:
> Update resctrl filesystem documentation with the details about the
> resctrl files that support telemetry events.
>
> Signed-off-by: Tony Luck <tony.luck@intel.com>
> ---
> Documentation/filesystems/resctrl.rst | 99 +++++++++++++++++++++++----
> 1 file changed, 86 insertions(+), 13 deletions(-)
>
> diff --git a/Documentation/filesystems/resctrl.rst b/Documentation/filesystems/resctrl.rst
> index c7949dd44f2f..7ee2832a3aa6 100644
> --- a/Documentation/filesystems/resctrl.rst
> +++ b/Documentation/filesystems/resctrl.rst
> @@ -167,13 +167,12 @@ with respect to allocation:
> bandwidth percentages are directly applied to
> the threads running on the core
>
> -If RDT monitoring is available there will be an "L3_MON" directory
> +If L3 monitoring is available there will be an "L3_MON" directory
> with the following files:
>
> "num_rmids":
> - The number of RMIDs available. This is the
> - upper bound for how many "CTRL_MON" + "MON"
> - groups can be created.
> + The number of RMIDs supported by hardware for
> + L3 monitoring events.
>
> "mon_features":
> Lists the monitoring events if
> @@ -261,6 +260,19 @@ with the following files:
> bytes) at which a previously used LLC_occupancy
> counter can be considered for re-use.
>
> +If telemetry monitoring is available there will be an "PERF_PKG_MON" directory
> +with the following files:
> +
> +"num_rmids":
> + The number of RMIDs supported by hardware for
> + telemetry monitoring events.
> +
> +"mon_features":
> + Lists the telemetry monitoring events that are enabled on this system.
> +
> +The upper bound for how many "CTRL_MON" + "MON" can be created
> +is the smaller of the "num_rmids" values.
To be specific this can be "smaller of the L3_MON and PERF_PKG_MON
"num_rmids" values."
> +
> Finally, in the top level of the "info" directory there is a file
> named "last_cmd_status". This is reset with every "command" issued
> via the file system (making new directories or writing to any of the
> @@ -366,15 +378,38 @@ When control is enabled all CTRL_MON groups will also contain:
> When monitoring is enabled all MON groups will also contain:
>
> "mon_data":
> - This contains a set of files organized by L3 domain and by
> - RDT event. E.g. on a system with two L3 domains there will
> - be subdirectories "mon_L3_00" and "mon_L3_01". Each of these
> - directories have one file per event (e.g. "llc_occupancy",
> - "mbm_total_bytes", and "mbm_local_bytes"). In a MON group these
> - files provide a read out of the current value of the event for
> - all tasks in the group. In CTRL_MON groups these files provide
> - the sum for all tasks in the CTRL_MON group and all tasks in
> - MON groups. Please see example section for more details on usage.
> + This contains a set of directories, one for each instance
> + of an L3 cache, another for each processor package. The L3 cache
... so two sets of directories? I am not able to parse.
> + directories are named "mon_L3_00", "mon_L3_01" etc. The
> + package directories "mon_PERF_PKG_00", "mon_PERF_PKG_01" etc.
> +
> + Within each directory there is one file per event. For
> + example the L3 directories may contain "llc_occupancy", "mbm_total_bytes",
> + and "mbm_local_bytes". The PERF_PKG directories may contain "core_energy",
> + "activity", etc.
It can help to append information how user can exactly know which files can be expected
(by looking at mon_features file).
> +
> + "core energy" reports a floating point number for the energy (in Joules)
> + consumed by cores (registers, arithmetic units, TLB and L1/L2 caches)
> + during execution of instructions summed across all logical CPUs on a
> + package for the current RMID.
> +
> + "activity" also reports a floating point value (in Farads).
> + This provides an estimate of work done independent of the
> + frequency that the CPUs used for execution.
> +
> + Note that these two counters only measure energy/activity
> + in the "core" of the CPU (arithmetic units, TLB, L1 and L2
> + caches, etc.). They do not include L3 cache, memory, I/O
> + devices etc.
> +
> + All other events report decimal integer values.
> +
> + In a MON group these files provide a read out of the current
> + value of the event for all tasks in the group. In CTRL_MON groups
> + these files provide the sum for all tasks in the CTRL_MON group
> + and all tasks in MON groups. Please see example section for more
> + details on usage.
> +
> On systems with Sub-NUMA Cluster (SNC) enabled there are extra
> directories for each node (located within the "mon_L3_XX" directory
> for the L3 cache they occupy). These are named "mon_sub_L3_YY"
> @@ -1300,6 +1335,44 @@ Example with C::
> resctrl_release_lock(fd);
> }
>
> +Debugfs
> +=======
> +In addition to the use of debugfs for tracing of pseudo-locking
> +performance, architecture code may create debugfs directories
> +associated with monitoring features for a specific resource.
> +
> +The full pathname for these is in the form:
> +
> + /sys/kernel/debug/resctrl/info/{resource_name}_MON/{arch}/
> +
> +The presence, names, and format of these files will vary
Same comment as in v8.
> +between architectures even if the same resource is present.
> +
> +PERF_PKG_MON/x86_64
> +-------------------
> +Three files are present per telemetry aggregator instance
> +that show when and how often the hardware has failed to
Sounds like all three files are related to failures, but I do
not believe they are.
> +collect and accumulate data from the CPUs. The prefix of
> +each file name describes the type ("energy" or "perf") which
> +processor package it belongs to, and the instance number of
> +the aggregator. For example: "energy_pkg1_agg2".
The "instance number" is assigned/enumerated by INTEL_PMT_TELEMETRY.
Does this have consistent and clear meaning to user space?
Reinette