Re: [PATCH v2 09/10] platform/x86/intel/ifs: add ABI documentation for IFS

[Greg KH]

On Thu, Apr 07, 2022 at 12:13:46PM -0700, Jithu Joseph wrote:
> Add the sysfs attributes in ABI/testing for In-Field Scan.
> 
> Reviewed-by: Tony Luck <tony.luck@xxxxxxxxx>
> Signed-off-by: Jithu Joseph <jithu.joseph@xxxxxxxxx>
> ---
>  .../ABI/testing/sysfs-platform-intel-ifs      | 54 +++++++++++++++++++
>  1 file changed, 54 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-platform-intel-ifs
> 
> diff --git a/Documentation/ABI/testing/sysfs-platform-intel-ifs b/Documentation/ABI/testing/sysfs-platform-intel-ifs
> new file mode 100644
> index 000000000000..54dc6cd75484
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-platform-intel-ifs
> @@ -0,0 +1,54 @@
> +What:		/sys/devices/platform/intel_ifs/run_test
> +Date:		April 07, 2022
> +KernelVersion:	5.19.0

No need for ".0"

> +Contact:	"Jithu Joseph" <jithu.joseph@xxxxxxxxx>
> +Description:	echo <cpu#> to trigger ifs test for all online cores.
> +		For e.g to test cpu5 do echo 5 > /sys/devices/platform/intel_ifs/run_test

So core numbers are different than cpu numbers here?  How are users
going to map them?

> +
> +What:		/sys/devices/platform/intel_ifs/status
> +Date:		April 07, 2022
> +KernelVersion:	5.19.0
> +Contact:	"Jithu Joseph" <jithu.joseph@xxxxxxxxx>
> +Description:	The status of the last test. It can be one of "pass", "fail"
> +		or "untested".
> +
> +What:		/sys/devices/system/cpu/cpu#/ifs/details
> +Date:		April 07, 2022
> +KernelVersion:	5.19.0
> +Contact:	"Jithu Joseph" <jithu.joseph@xxxxxxxxx>
> +Description:	Additional information regarding the last test. The details file reports
> +		the hex value of the SCAN_STATUS MSR. Note that the error_code field
> +		may contain driver defined software code not defined in the Intel SDM.
> +
> +What:		/sys/devices/platform/intel_ifs/image_version
> +Date:		April 07, 2022
> +KernelVersion:	5.19.0
> +Contact:	"Jithu Joseph" <jithu.joseph@xxxxxxxxx>
> +Description:	Version of loaded IFS binary image.

In what format?

> +
> +What:		/sys/bus/platform/drivers/intel_ifs/bind
> +Date:		April 07, 2022
> +KernelVersion:	5.19.0
> +Contact:	"Jithu Joseph" <jithu.joseph@xxxxxxxxx>
> +Description:	echo "intel_ifs" to reload IFS image.

Huh?  Why are you using a common sysfs file for this type of attribute?
Please do not do so, make it "reload" or something like that.

> +
> +What:		/sys/module/intel_ifs/parameters/noirq
> +Date:		April 07, 2022
> +KernelVersion:	5.19.0
> +Contact:	"Jithu Joseph" <jithu.joseph@xxxxxxxxx>
> +Description:	IFS tunable parameter that user can modify before
> +		the scan run if they wish to override default value.

And where are those parameters documented?  What are valid values here?

> +		When set, system interrupts are not allowed to interrupt an IFS. The
> +		default state for this parameter is set.

set to what?

> +
> +What:		/sys/module/intel_ifs/parameters/retry
> +Date:		April 07, 2022
> +KernelVersion:	5.19.0
> +Contact:	"Jithu Joseph" <jithu.joseph@xxxxxxxxx>
> +Description:	IFS tunable parameter that user can modify before scan run
> +		if they wish to override default value.
> +
> +		Maximum retry counter when the test is not executed due to an
> +		event such as interrupt. The default value is 5, it can be set to any
> +		value from 1 to 20.

Why would anyone ever want to change this value?  Why doesn't it "just
work" without needing anything tuned?

thanks,

greg k-h