[13/14] Documentation/ABI: Update IFS ABI doc

Message ID 20221021203413.1220137-14-jithu.joseph@intel.com
State New
Headers
Series IFS multi test image support and misc changes |

Commit Message

Jithu Joseph Oct. 21, 2022, 8:34 p.m. UTC
  Remove reload documentation and add current_batch documentation.
Update the kernel version and date for all the entries.

Reviewed-by: Tony Luck <tony.luck@intel.com>
Signed-off-by: Jithu Joseph <jithu.joseph@intel.com>
---
 .../ABI/testing/sysfs-platform-intel-ifs      | 30 ++++++++++---------
 1 file changed, 16 insertions(+), 14 deletions(-)
  

Comments

Sohil Mehta Nov. 1, 2022, 10:34 p.m. UTC | #1
On 10/21/2022 1:34 PM, Jithu Joseph wrote:
> -What:		/sys/devices/virtual/misc/intel_ifs_<N>/reload
> -Date:		April 21 2022
> -KernelVersion:	5.19
> +What:		/sys/devices/virtual/misc/intel_ifs_<N>/current_batch
> +Date:		Sept 30 2022
> +KernelVersion:	6.2
>   Contact:	"Jithu Joseph" <jithu.joseph@intel.com>
> -Description:	Write "1" (or "y" or "Y") to reload the IFS image from
> -		/lib/firmware/intel/ifs/ff-mm-ss.scan.
> +Description:	Write a number less than or equal to 0xff to load an IFS test image.
> +		The number written treated as the 2 digit suffix in the following file name:
> +		/lib/firmware/intel/ifs_<N>/ff-mm-ss-02x.scan
> +		Reading the file will provide the suffix of the currently loaded IFS test image.

A few places in the code use the following string: 
family-model-stepping-02x.{testname}

Does that mean that the in future there might be other extensions apart 
from .scan?

If so, current_batch would let the user identify the 2 digit suffix but 
how would they identify which testname is current loaded?
  
Jithu Joseph Nov. 1, 2022, 10:48 p.m. UTC | #2
On 11/1/2022 3:34 PM, Sohil Mehta wrote:
> On 10/21/2022 1:34 PM, Jithu Joseph wrote:
>> -What:        /sys/devices/virtual/misc/intel_ifs_<N>/reload
>> -Date:        April 21 2022
>> -KernelVersion:    5.19
>> +What:        /sys/devices/virtual/misc/intel_ifs_<N>/current_batch
>> +Date:        Sept 30 2022
>> +KernelVersion:    6.2
>>   Contact:    "Jithu Joseph" <jithu.joseph@intel.com>
>> -Description:    Write "1" (or "y" or "Y") to reload the IFS image from
>> -        /lib/firmware/intel/ifs/ff-mm-ss.scan.
>> +Description:    Write a number less than or equal to 0xff to load an IFS test image.
>> +        The number written treated as the 2 digit suffix in the following file name:
>> +        /lib/firmware/intel/ifs_<N>/ff-mm-ss-02x.scan
>> +        Reading the file will provide the suffix of the currently loaded IFS test image.
> 
> A few places in the code use the following string: family-model-stepping-02x.{testname}
> 
> Does that mean that the in future there might be other extensions apart from .scan?

yes as when when support for additional tests are added

> 
> If so, current_batch would let the user identify the 2 digit suffix but how would they identify which testname is current loaded?

The testname would be inferred based the sysfs file context (the<N> in /sys/devices/virtual/misc/intel_ifs_<N>/current_batch) from which the operation is triggered. 

Meaning if the user writes to /sys/devices/virtual/misc/intel_ifs_0/current_batch it would look for ff-mm-ss.scan and if they write to
/sys/devices/virtual/misc/intel_ifs_2/current_batch  it would look for ff-mm-ss.<test_type_2>


Jithu
  
Sohil Mehta Nov. 1, 2022, 10:59 p.m. UTC | #3
On 11/1/2022 3:48 PM, Joseph, Jithu wrote:
> The testname would be inferred based the sysfs file context (the<N> in /sys/devices/virtual/misc/intel_ifs_<N>/current_batch) from which the operation is triggered.
> 
> Meaning if the user writes to /sys/devices/virtual/misc/intel_ifs_0/current_batch it would look for ff-mm-ss.scan and if they write to
> /sys/devices/virtual/misc/intel_ifs_2/current_batch  it would look for ff-mm-ss.<test_type_2>
> 

So intel_ifs_<N> corresponds to <test_type> i.e. intel_ifs_0 maps to .scan

Is the N to test_type mapping visible to the user somewhere? If not, how 
would the user infer that?

Would it be useful to name the misc device as intel_ifs_<test_type>?
  
Jithu Joseph Nov. 2, 2022, 10:10 p.m. UTC | #4
On 11/1/2022 3:59 PM, Sohil Mehta wrote:
> On 11/1/2022 3:48 PM, Joseph, Jithu wrote:
>> The testname would be inferred based the sysfs file context (the<N> in /sys/devices/virtual/misc/intel_ifs_<N>/current_batch) from which the operation is triggered.
>>
>> Meaning if the user writes to /sys/devices/virtual/misc/intel_ifs_0/current_batch it would look for ff-mm-ss.scan and if they write to
>> /sys/devices/virtual/misc/intel_ifs_2/current_batch  it would look for ff-mm-ss.<test_type_2>
>>
> 
> So intel_ifs_<N> corresponds to <test_type> i.e. intel_ifs_0 maps to .scan
> 
> Is the N to test_type mapping visible to the user somewhere? If not, how would the user infer that?
> 
> Would it be useful to name the misc device as intel_ifs_<test_type>?
> 

There is a mapping based on the device number, for e.g if the user tries to use the below sysfs file for loading
/sys/devices/virtual/misc/intel_ifs_<N>/current_batch

The driver will look for the below test image for loading
/lib/firmware/intel/ifs_<N>/ff-mm-ss-02x.<test_type>

The number<N> is same in both the above path.
Prior to issuing the load command, user has to simply copy the supplied test image to the corresponding /lib/firmware path

Jithu
  
Sohil Mehta Nov. 3, 2022, 7:49 a.m. UTC | #5
On 11/2/2022 3:10 PM, Joseph, Jithu wrote:
> 
> There is a mapping based on the device number, for e.g if the user tries to use the below sysfs file for loading
> /sys/devices/virtual/misc/intel_ifs_<N>/current_batch
> 
> The driver will look for the below test image for loading
> /lib/firmware/intel/ifs_<N>/ff-mm-ss-02x.<test_type>
> 
> The number<N> is same in both the above path.

I guess that is OK. Adding the test name to the device path could 
potentially make the interface more restrictive.

Sohil
  

Patch

diff --git a/Documentation/ABI/testing/sysfs-platform-intel-ifs b/Documentation/ABI/testing/sysfs-platform-intel-ifs
index 486d6d2ff8a0..f74df3abee57 100644
--- a/Documentation/ABI/testing/sysfs-platform-intel-ifs
+++ b/Documentation/ABI/testing/sysfs-platform-intel-ifs
@@ -1,39 +1,41 @@ 
 What:		/sys/devices/virtual/misc/intel_ifs_<N>/run_test
-Date:		April 21 2022
-KernelVersion:	5.19
+Date:		Sept 30 2022
+KernelVersion:	6.2
 Contact:	"Jithu Joseph" <jithu.joseph@intel.com>
 Description:	Write <cpu#> to trigger IFS test for one online core.
 		Note that the test is per core. The cpu# can be
 		for any thread on the core. Running on one thread
 		completes the test for the core containing that thread.
 		Example: to test the core containing cpu5: echo 5 >
-		/sys/devices/platform/intel_ifs.<N>/run_test
+		/sys/devices/virtual/misc/intel_ifs_<N>/run_test
 
 What:		/sys/devices/virtual/misc/intel_ifs_<N>/status
-Date:		April 21 2022
-KernelVersion:	5.19
+Date:		Sept 30 2022
+KernelVersion:	6.2
 Contact:	"Jithu Joseph" <jithu.joseph@intel.com>
 Description:	The status of the last test. It can be one of "pass", "fail"
 		or "untested".
 
 What:		/sys/devices/virtual/misc/intel_ifs_<N>/details
-Date:		April 21 2022
-KernelVersion:	5.19
+Date:		Sept 30 2022
+KernelVersion:	6.2
 Contact:	"Jithu Joseph" <jithu.joseph@intel.com>
 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/virtual/misc/intel_ifs_<N>/image_version
-Date:		April 21 2022
-KernelVersion:	5.19
+Date:		Sept 30 2022
+KernelVersion:	6.2
 Contact:	"Jithu Joseph" <jithu.joseph@intel.com>
 Description:	Version (hexadecimal) of loaded IFS binary image. If no scan image
 		is loaded reports "none".
 
-What:		/sys/devices/virtual/misc/intel_ifs_<N>/reload
-Date:		April 21 2022
-KernelVersion:	5.19
+What:		/sys/devices/virtual/misc/intel_ifs_<N>/current_batch
+Date:		Sept 30 2022
+KernelVersion:	6.2
 Contact:	"Jithu Joseph" <jithu.joseph@intel.com>
-Description:	Write "1" (or "y" or "Y") to reload the IFS image from
-		/lib/firmware/intel/ifs/ff-mm-ss.scan.
+Description:	Write a number less than or equal to 0xff to load an IFS test image.
+		The number written treated as the 2 digit suffix in the following file name:
+		/lib/firmware/intel/ifs_<N>/ff-mm-ss-02x.scan
+		Reading the file will provide the suffix of the currently loaded IFS test image.