Re: [PATCH 09/15] docs: Add ABI documentation for intel_pmt feature directories

["Ilpo Järvinen" <ilpo.jarvinen@linux.intel.com>]

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

On Wed, 30 Apr 2025, David E. Box wrote:

> Add a new sysfs ABI documentation file describing the layout and content of
> the features-<PCI BDF>/ directory used by Intel PMT (Platform Monitoring
> Technology). This directory exposes telemetry and control feature details
> for a given PMT PCI device.
> 
> Signed-off-by: David E. Box <david.e.box@linux.intel.com>
> ---
>  .../testing/sysfs-class-intel_pmt-features    | 128 ++++++++++++++++++
>  MAINTAINERS                                   |   1 +
>  2 files changed, 129 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-class-intel_pmt-features
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-intel_pmt-features b/Documentation/ABI/testing/sysfs-class-intel_pmt-features
> new file mode 100644
> index 000000000000..6dfb9b4b30b5
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-class-intel_pmt-features
> @@ -0,0 +1,128 @@
> +What:          /sys/class/intel_pmt/features-<PCI BDF>/
> +Date:          2025-04-24
> +KernelVersion: 6.16
> +Contact:       david.e.box@linux.intel.com
> +Description:
> +               The `features-<PCI BDF>/` directory represents the "features"
> +               capability exposed by Intel PMT (Platform Monitoring Technology)
> +               for the given PCI device.
> +
> +               Each directory corresponds to a PMT feature and contains
> +               attributes describing the available telemetry, monitoring, or
> +               control functionalities.
> +
> +Directory Structure:
> +
> +  /sys/class/intel_pmt/features-<PCI BDF>/
> +  ├── accelerator_telemetry/		# Per-accelerator telemetry data
> +  ├── crash_log/			# Contains system crash telemetry logs
> +  ├── per_core_environment_telemetry/	# Environmental telemetry per core
> +  ├── per_core_performance_telemetry/	# Performance telemetry per core
> +  ├── per_rmid_energy_telemetry/	# Energy telemetry for RMIDs
> +  ├── per_rmid_perf_telemetry/		# Performance telemetry for RMIDs
> +  ├── tpmi_control/			# TPMI-related controls and telemetry
> +  ├── tracing/				# PMT tracing features
> +  └── uncore_telemetry/			# Uncore telemetry data
> +
> +Common Files (Present in all feature directories):
> +
> +  caps
> +    - Read-only
> +    - Lists available capabilities for this feature.
> +
> +  guids
> +    - Read-only
> +    - Lists GUIDs associated with this feature.
> +
> +Additional Attributes (Conditional Presence):
> +
> +  max_command_size
> +    - Read-only
> +    - Present if the feature supports out-of-band MCTP access.
> +    - Maximum supported MCTP command size for out-of-band PMT access (bytes).
> +
> +  max_stream_size
> +    - Read-only
> +    - Present if the feature supports out-of-band MCTP access.
> +    - Maximum supported MCTP stream size (bytes).
> +
> +  min_watcher_period_ms
> +    - Read-only
> +    - Present if the feature supports the watcher API.
> +    - Minimum supported time period for the watcher interface (milliseconds).
> +
> +  num_rmids
> +    - Read-only
> +    - Present if the feature supports RMID telemetry.
> +    - Maximum number of RMIDs tracked simultaneously.
> +
> +Example:
> +For a device with PCI BDF `0000:00:03.1`, the directory tree could look like:
> +
> +  /sys/class/intel_pmt/features-0000:00:03.1/
> +  ├── accelerator_telemetry/
> +  │   ├── caps
> +  │   ├── guids
> +  │   ├── max_command_size
> +  │   ├── max_stream_size
> +  │   ├── min_watcher_period_ms
> +  ├── crash_log/
> +  │   ├── caps
> +  │   ├── guids
> +  │   ├── max_command_size
> +  │   ├── max_stream_size
> +  ├── per_core_environment_telemetry/
> +  │   ├── caps
> +  │   ├── guids
> +  │   ├── max_command_size
> +  │   ├── max_stream_size
> +  │   ├── min_watcher_period_ms
> +  ├── per_rmid_energy_telemetry/
> +  │   ├── caps
> +  │   ├── guids
> +  │   ├── max_command_size
> +  │   ├── max_stream_size
> +  │   ├── min_watcher_period_ms
> +  │   ├── num_rmids
> +  ├── tpmi_control/
> +  │   ├── caps
> +  │   ├── guids
> +  ├── tracing/
> +  │   ├── caps
> +  │   ├── guids
> +  ├── uncore_telemetry/
> +  │   ├── caps
> +  │   ├── guids
> +  │   ├── max_command_size
> +  │   ├── max_stream_size
> +  │   ├── min_watcher_period_ms
> +
> +Notes:
> +  - Some attributes are only present if the corresponding feature supports
> +    the capability (e.g., `max_command_size` for MCTP-capable features).
> +  - Features supporting RMIDs include `num_rmids`.
> +  - Features supporting the watcher API include `min_watcher_period_ms`.
> +  - The `caps` file provides additional information about the functionality
> +    of the feature.
> +
> +Example 'caps' content for the 'tracing' feature:
> +
> +  /sys/class/intel_pmt/features-0000:00:03.1/
> +  ├── tracing/
> +  │   ├── caps
> +
> +	telemetry                                Available: No
> +	watcher                                  Available: Yes
> +	crashlog                                 Available: No
> +	streaming                                Available: No
> +	threashold                               Available: No
> +	window                                   Available: No
> +	config                                   Available: Yes
> +	tracing                                  Available: No
> +	inband                                   Available: Yes
> +	oob                                      Available: Yes
> +	secure_chan                              Available: No
> +	pmt_sp                                   Available: Yes
> +	PMT SP Policy                            Available: Yes
> +	mailbox                                  Available: Yes
> +	bios_lock                                Available: Yes

It would be good to open RMID somewhere as I'm not sure if that acronym 
is well-known.

> diff --git a/MAINTAINERS b/MAINTAINERS
> index bd9f99585894..10338ea81667 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -12181,6 +12181,7 @@ INTEL PMT DRIVERS
>  M:	David E. Box <david.e.box@linux.intel.com>
>  S:	Supported
>  F:	Documentation/ABI/testing/sysfs-class-intel_pmt
> +F:	Documentation/ABI/testing/sysfs-class-intel_pmt-features
>  F:	drivers/platform/x86/intel/pmt/
>  
>  INTEL PRO/WIRELESS 2100, 2200BG, 2915ABG NETWORK CONNECTION SUPPORT
> 

-- 
 i.