Re: [PATCH v4 4/4] Documentation: add debugfs description for hisi migration

[liulongfang]

On 2024/4/5 4:07, Alex Williamson wrote:
> On Tue, 2 Apr 2024 11:24:32 +0800
> Longfang Liu <liulongfang@xxxxxxxxxx> wrote:
> 
>> Add a debugfs document description file to help users understand
>> how to use the hisilicon accelerator live migration driver's
>> debugfs.
>>
>> Update the file paths that need to be maintained in MAINTAINERS
>>
>> Signed-off-by: Longfang Liu <liulongfang@xxxxxxxxxx>
>> ---
>>  .../ABI/testing/debugfs-hisi-migration        | 34 +++++++++++++++++++
>>  MAINTAINERS                                   |  1 +
>>  2 files changed, 35 insertions(+)
>>  create mode 100644 Documentation/ABI/testing/debugfs-hisi-migration
>>
>> diff --git a/Documentation/ABI/testing/debugfs-hisi-migration b/Documentation/ABI/testing/debugfs-hisi-migration
>> new file mode 100644
>> index 000000000000..3d7339276e6f
>> --- /dev/null
>> +++ b/Documentation/ABI/testing/debugfs-hisi-migration
>> @@ -0,0 +1,34 @@
>> +What:		/sys/kernel/debug/vfio/<device>/migration/hisi_acc/data
>> +Date:		Apr 2024
>> +KernelVersion:  6.9
> 
> At best 6.10 with a merge window in May.
> 
>> +Contact:	Longfang Liu <liulongfang@xxxxxxxxxx>
>> +Description:	Read the live migration data of the vfio device.
>> +		These data include device status data, queue configuration
>> +		data and some task configuration data.
>> +		The output format of the data is defined by the live
>> +		migration driver.
> 
> "Dumps the device debug migration buffer, state must first be saved
> using the 'save' attribute."
> 
>> +
>> +What:		/sys/kernel/debug/vfio/<device>/migration/hisi_acc/attr
>> +Date:		Apr 2024
>> +KernelVersion:  6.9
>> +Contact:	Longfang Liu <liulongfang@xxxxxxxxxx>
>> +Description:	Read the live migration attributes of the vfio device.
>> +		it include device status attributes and data length attributes
>> +		The output format of the attributes is defined by the live
>> +		migration driver.
> 
> AFAICT from the previous patch, this attribute is useless.
> 
>> +
>> +What:		/sys/kernel/debug/vfio/<device>/migration/hisi_acc/cmd_state
>> +Date:		Apr 2024
>> +KernelVersion:  6.9
>> +Contact:	Longfang Liu <liulongfang@xxxxxxxxxx>
>> +Description:	Used to obtain the device command sending and receiving
>> +		channel status. If successful, returns the command value.
>> +		If failed, return error log.
>> +
> 
> Seems like it statically returns "OK" plus the actual value.
> 
> 
>> +What:		/sys/kernel/debug/vfio/<device>/migration/hisi_acc/save
>> +Date:		Apr 2024
>> +KernelVersion:  6.9
>> +Contact:	Longfang Liu <liulongfang@xxxxxxxxxx>
>> +Description:	Trigger the Hisilicon accelerator device to perform
>> +		the state saving operation of live migration through the read
>> +		operation, and output the operation log results.
> 
> These interfaces are confusing, attr and data only work if there has
> either been a previous save OR the user migration process closed saving
> or resuming fds in the interim, and the user doesn't know which one
> they get.  Note that debug_migf isn't even discarded between
> open/close, only cmd and save require the device to be opened by a
> user, data and attr might continue to return data from some previous
> user save, resume, or debugfs save.
>

data: Indicates the device migration data obtained after the migration is completed.
This data is saved in debug_migf. The user reads it through "cat" and
presents it to the user in the form of hexadecimal pure data.

attr: Indicates the configuration parameters of the migration process after the
migration is completed. These parameters are saved in vfio device and debug_migf.
The user reads it through "cat" and presents it to the user in the form of key-value
pairs such as <attribute name, attribute value>.

Save is an action process. After "cat" it, a migration save operation will be
performed and the result data will be updated to debug_migf.

There is still a big difference between data and attr, and the data formats are
also different. Not merging makes it easier for users to obtain information.
If you feel confused about save, it is recommended to use migrate_save.

Thanks,
Longfang.

> 
> 
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index 7625911ec2f1..8c2d13b13273 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -23072,6 +23072,7 @@ M:	Longfang Liu <liulongfang@xxxxxxxxxx>
>>  M:	Shameer Kolothum <shameerali.kolothum.thodi@xxxxxxxxxx>
>>  L:	kvm@xxxxxxxxxxxxxxx
>>  S:	Maintained
>> +F:	Documentation/ABI/testing/debugfs-hisi-migration
>>  F:	drivers/vfio/pci/hisilicon/
>>  
>>  VFIO MEDIATED DEVICE DRIVERS
> 
> .
>