Re: [PATCH v2 3/3] doc: Add ABI documentation for uio_pci_sva driver sysfs attributes

[yaxing guo <guoyaxing@bosc.ac.cn>]

Hi, Greg,

Thank you for your feedback.

On 9/25/2025 8:32 PM, Greg KH wrote:
> On Thu, Sep 25, 2025 at 06:40:18PM +0800, Yaxing Guo wrote:
>> Add ABI documentation for the sysfs interface provided by the
>> uio_pci_sva driver, specifically the 'pasid' attribute.
>>
>> The 'pasid' attribute exposes the Process Address Space ID (PASID)
>> assigned by the IOMMU to the device for use with Shared Virtual
>> Addressing (SVA). User-space UIO applications read this attribute
>> to obtain the PASID and program it into the device's configuration
>> registers, enabling the device to perform DMA using user-space
>> virtual addresses.
>>
>> This attribute appears under:
>> /sys/bus/pci/drivers/uio_pci_sva/<pci_dev>/pasid
>>
>> Signed-off-by: Yaxing Guo <guoyaxing@bosc.ac.cn>
>> ---
>>   .../ABI/testing/sysfs-driver-uio_pci_sva-pasid    | 15 +++++++++++++++
>>   1 file changed, 15 insertions(+)
>>   create mode 100644 Documentation/ABI/testing/sysfs-driver-uio_pci_sva-pasid
>>
>> diff --git a/Documentation/ABI/testing/sysfs-driver-uio_pci_sva-pasid b/Documentation/ABI/testing/sysfs-driver-uio_pci_sva-pasid
>> new file mode 100644
>> index 000000000000..a6afa8c2775c
>> --- /dev/null
>> +++ b/Documentation/ABI/testing/sysfs-driver-uio_pci_sva-pasid
>> @@ -0,0 +1,15 @@
>> +What:		/sys/bus/pci/drivers/uio_pci_sva/<pci_dev>/pasid
>> +Date:		September 2025
>> +Contact:	Yaxing Guo <guoyaxing@bosc.ac.cn>
>> +Description:
>> +		Process Address Space ID (PASID) assigned by IOMMU driver to
>> +		the device for use witch Shared Virtual Addressing (SVA).
> 
> "with", not "witch", right?
> 
>> +
>> +		This read-only attribute exposes the PASID allocated by the
>> +		IOMMU driver during sva device binding.
>> +
>> +		User-space UIO applications must read this attribute to
>> +		obtain the PASID and program it into the device's configuration
>> +		registers. This enables the device to perform DMA using
>> +		user-space virtual address, with address translation handled
>> +		by IOMMU.
> 
> What is a PASID?  What format is it in?
> 
> How can it then be used in userspace?  What is a "device configuration
> register" and what api uses it?
> 
> And where is the userspace code that interacts with all of this?
> 

The UIO userspace code is inherently tied to the hardware and its
register layout. Therefore, there isn't a single open-source userspace
implementation(In my job, this is for a simple FPAG-based test device 
used for iommu-sva functionality validation).

However, to help users understand how to use the interface, I can add a
**code example in this ABI documentation** that demonstrates:

- Reading the PASID from sysfs
- Mapping the device's register space via /dev/uioX
- Writing the PASID to a device-specific register (with example offset)

The code maybe like this:

map = mmap(..., "/dev/uio0", ...);

f = fopen("/sys/.../pasid", "r");
fscanf(f, "%d", &pasid);

map[REG_PASID_OFFSET] = pasid;

Would you prefer that I include such an example directly in the ABI doc, 
or is there another way you'd like this to be documented?

> And finally, this too can be part of the first commit.
> 
> thanks,
> 
> greg k-h

Best regards,
Yaxing Guo