[RFC] Proposal: Add sysfs interface for PCIe TPH Steering Tag retrieval and configuration

[RFC] Proposal: Add sysfs interface for PCIe TPH Steering Tag retrieval and configuration

[fengchengwen]

Hi all,

I'm writing to propose adding a sysfs interface to expose and configure 
the PCIe TPH
Steering Tag for PCIe devices, which is retrieved inside the kernel.


Background: The TPH Steering Tag is tightly coupled with both a PCIe 
device (identified
by its BDF) and a CPU core. It can only be obtained in kernel mode. To 
allow user-space
applications to fetch and set this value securely and conveniently, we 
need a standard
kernel-to-user interface.


Proposed Solution: Add several sysfs attributes under each PCIe device's 
sysfs directory:
1. /sys/bus/pci/devices/<BDF>/tph_mode to query the TPH mode (interrupt 
or device specific)
2. /sys/bus/pci/devices/<BDF>/tph_enable to control the TPH feature
3. /sys/bus/pci/devices/<BDF>/tph_st to support both read and write 
operations, e.g.:
    Read operation:
      echo "cpu=3" > /sys/bus/pci/devices/0000:01:00.0/tph_st
      cat /sys/bus/pci/devices/0000:01:00.0/tph_st
    Write operation:
      echo "index=10 st=123" > /sys/bus/pci/devices/0000:01:00.0/tph_st


The design strictly follows PCI subsystem sysfs standards and has the 
following key properties:

1. Dynamic Visibility: The sysfs attributes will only be present for 
PCIe devices that
    support TPH Steering Tag. Devices without TPH capability will not 
show these nodes,
    avoiding unnecessary user confusion.

2. Permission Control: The attributes will use 0600 file permissions, 
ensuring only
    privileged root users can read or write them, which satisfies 
security requirements
    for hardware configuration interfaces.

3. Standard Implementation Location: The interface will be implemented in
    drivers/pci/pci-sysfs.c, the canonical location for all PCI device 
sysfs attributes,
    ensuring consistency and maintainability within the PCI subsystem.


Why sysfs instead of alternatives like VFIO-PCI ioctl:

- Universality: sysfs does not require binding the device to a special 
driver such as
   vfio-pci. It is available to any privileged user-space component, 
including system
   utilities, daemons, and monitoring tools.

- Simplicity: Both user-space usage (cat/echo) and kernel implementation are
   straightforward, reducing code complexity and long-term maintenance cost.

- Design Alignment: TPH Steering Tag is a generic PCIe device feature, 
not specific to
   user-space drivers like DPDK or VFIO. Exposing it via sysfs matches 
the kernel's
   standard pattern for hardware capabilities.


I look forward to your comments about this design before submitting the 
final patch.

Best regards,
Chengwen Feng

Re: [RFC] Proposal: Add sysfs interface for PCIe TPH Steering Tag retrieval and configuration

[Leon Romanovsky]

On Fri, Apr 10, 2026 at 10:30:52PM +0800, fengchengwen wrote:
> Hi all,
> 
> I'm writing to propose adding a sysfs interface to expose and configure the
> PCIe TPH
> Steering Tag for PCIe devices, which is retrieved inside the kernel.
> 
> 
> Background: The TPH Steering Tag is tightly coupled with both a PCIe device
> (identified
> by its BDF) and a CPU core. It can only be obtained in kernel mode. To allow
> user-space
> applications to fetch and set this value securely and conveniently, we need
> a standard
> kernel-to-user interface.
> 
> 
> Proposed Solution: Add several sysfs attributes under each PCIe device's
> sysfs directory:
> 1. /sys/bus/pci/devices/<BDF>/tph_mode to query the TPH mode (interrupt or
> device specific)
> 2. /sys/bus/pci/devices/<BDF>/tph_enable to control the TPH feature
> 3. /sys/bus/pci/devices/<BDF>/tph_st to support both read and write
> operations, e.g.:
>    Read operation:
>      echo "cpu=3" > /sys/bus/pci/devices/0000:01:00.0/tph_st
>      cat /sys/bus/pci/devices/0000:01:00.0/tph_st
>    Write operation:
>      echo "index=10 st=123" > /sys/bus/pci/devices/0000:01:00.0/tph_st
> 
> 
> The design strictly follows PCI subsystem sysfs standards and has the
> following key properties:
> 
> 1. Dynamic Visibility: The sysfs attributes will only be present for PCIe
> devices that
>    support TPH Steering Tag. Devices without TPH capability will not show
> these nodes,
>    avoiding unnecessary user confusion.
> 
> 2. Permission Control: The attributes will use 0600 file permissions,
> ensuring only
>    privileged root users can read or write them, which satisfies security
> requirements
>    for hardware configuration interfaces.
> 
> 3. Standard Implementation Location: The interface will be implemented in
>    drivers/pci/pci-sysfs.c, the canonical location for all PCI device sysfs
> attributes,
>    ensuring consistency and maintainability within the PCI subsystem.
> 
> 
> Why sysfs instead of alternatives like VFIO-PCI ioctl:
> 
> - Universality: sysfs does not require binding the device to a special
> driver such as
>   vfio-pci. It is available to any privileged user-space component,
> including system
>   utilities, daemons, and monitoring tools.
> 
> - Simplicity: Both user-space usage (cat/echo) and kernel implementation are
>   straightforward, reducing code complexity and long-term maintenance cost.
> 
> - Design Alignment: TPH Steering Tag is a generic PCIe device feature, not
> specific to
>   user-space drivers like DPDK or VFIO. Exposing it via sysfs matches the
> kernel's
>   standard pattern for hardware capabilities.
> 
> 
> I look forward to your comments about this design before submitting the
> final patch.

You need to explain more clearly why this write functionality is useful
and necessary outside the VFIO/RDMA context:
https://lore.kernel.org/all/20260324234615.3731237-1-zhipingz@meta.com/

AFAIK, for non-VFIO TPH callers, kernel has enough knowledge to set
right ST values.

There are several comments regarding the implementation, but those can wait
until the rationale behind the proposal is fully clarified.

Thanks

> 
> Best regards,
> Chengwen Feng
> 

Re: [RFC] Proposal: Add sysfs interface for PCIe TPH Steering Tag retrieval and configuration

[fengchengwen]

On 4/13/2026 6:01 PM, Leon Romanovsky wrote:
> On Fri, Apr 10, 2026 at 10:30:52PM +0800, fengchengwen wrote:
>> Hi all,
>>
>> I'm writing to propose adding a sysfs interface to expose and configure the
>> PCIe TPH
>> Steering Tag for PCIe devices, which is retrieved inside the kernel.
>>
>>
>> Background: The TPH Steering Tag is tightly coupled with both a PCIe device
>> (identified
>> by its BDF) and a CPU core. It can only be obtained in kernel mode. To allow
>> user-space
>> applications to fetch and set this value securely and conveniently, we need
>> a standard
>> kernel-to-user interface.
>>
>>
>> Proposed Solution: Add several sysfs attributes under each PCIe device's
>> sysfs directory:
>> 1. /sys/bus/pci/devices/<BDF>/tph_mode to query the TPH mode (interrupt or
>> device specific)
>> 2. /sys/bus/pci/devices/<BDF>/tph_enable to control the TPH feature
>> 3. /sys/bus/pci/devices/<BDF>/tph_st to support both read and write
>> operations, e.g.:
>>    Read operation:
>>      echo "cpu=3" > /sys/bus/pci/devices/0000:01:00.0/tph_st
>>      cat /sys/bus/pci/devices/0000:01:00.0/tph_st
>>    Write operation:
>>      echo "index=10 st=123" > /sys/bus/pci/devices/0000:01:00.0/tph_st
>>
>>
>> The design strictly follows PCI subsystem sysfs standards and has the
>> following key properties:
>>
>> 1. Dynamic Visibility: The sysfs attributes will only be present for PCIe
>> devices that
>>    support TPH Steering Tag. Devices without TPH capability will not show
>> these nodes,
>>    avoiding unnecessary user confusion.
>>
>> 2. Permission Control: The attributes will use 0600 file permissions,
>> ensuring only
>>    privileged root users can read or write them, which satisfies security
>> requirements
>>    for hardware configuration interfaces.
>>
>> 3. Standard Implementation Location: The interface will be implemented in
>>    drivers/pci/pci-sysfs.c, the canonical location for all PCI device sysfs
>> attributes,
>>    ensuring consistency and maintainability within the PCI subsystem.
>>
>>
>> Why sysfs instead of alternatives like VFIO-PCI ioctl:
>>
>> - Universality: sysfs does not require binding the device to a special
>> driver such as
>>   vfio-pci. It is available to any privileged user-space component,
>> including system
>>   utilities, daemons, and monitoring tools.
>>
>> - Simplicity: Both user-space usage (cat/echo) and kernel implementation are
>>   straightforward, reducing code complexity and long-term maintenance cost.
>>
>> - Design Alignment: TPH Steering Tag is a generic PCIe device feature, not
>> specific to
>>   user-space drivers like DPDK or VFIO. Exposing it via sysfs matches the
>> kernel's
>>   standard pattern for hardware capabilities.
>>
>>
>> I look forward to your comments about this design before submitting the
>> final patch.
> 
> You need to explain more clearly why this write functionality is useful
> and necessary outside the VFIO/RDMA context:
> https://lore.kernel.org/all/20260324234615.3731237-1-zhipingz@meta.com/
> 
> AFAIK, for non-VFIO TPH callers, kernel has enough knowledge to set
> right ST values.
> 
> There are several comments regarding the implementation, but those can wait
> until the rationale behind the proposal is fully clarified.

Thanks for your review and comments.

Let me clarify the rationale behind this user-space sysfs interface:

1. VFIO is just one of the user-space device access frameworks.
   There are many other in-kernel frameworks that expose devices
   to user space, such as UIO, UACCE, etc., which may also require
   TPH Steering Tag support.

2. The kernel can automatically program Steering Tags only when
   the device provides a standard ST table in MSI-X or config space.
   However, many devices implement vendor-specific or platform-specific
   Steering Tag programming methods that cannot be fully handled
   by the generic kernel code.

3. For such devices, user-space applications or framework drivers
   need to retrieve and configure TPH Steering Tags directly.
   A unified sysfs interface allows all user-space frameworks
   (not just VFIO) to use a common, standard way to manage
   TPH Steering Tags, rather than implementing duplicated logic
   in each subsystem.

This interface provides a uniform method for any user-space
device access solution to work with TPH, which is why I believe
it is useful and necessary beyond the VFIO/RDMA case.

Thanks

> 
> Thanks
> 
>>
>> Best regards,
>> Chengwen Feng
>>

Re: [RFC] Proposal: Add sysfs interface for PCIe TPH Steering Tag retrieval and configuration

[Jason Gunthorpe]

On Fri, Apr 10, 2026 at 10:30:52PM +0800, fengchengwen wrote:

> Background: The TPH Steering Tag is tightly coupled with both a PCIe
> device (identified by its BDF) and a CPU core. It can only be
> obtained in kernel mode. To allow user-space applications to fetch
> and set this value securely and conveniently, we need a standard
> kernel-to-user interface.

There is no reason for userspace to have this value outside VFIO.

> Proposed Solution: Add several sysfs attributes under each PCIe device's
> sysfs directory:
> 1. /sys/bus/pci/devices/<BDF>/tph_mode to query the TPH mode (interrupt or
> device specific)
> 2. /sys/bus/pci/devices/<BDF>/tph_enable to control the TPH feature
> 3. /sys/bus/pci/devices/<BDF>/tph_st to support both read and write
> operations, e.g.:
>    Read operation:
>      echo "cpu=3" > /sys/bus/pci/devices/0000:01:00.0/tph_st
>      cat /sys/bus/pci/devices/0000:01:00.0/tph_st
>    Write operation:
>      echo "index=10 st=123" > /sys/bus/pci/devices/0000:01:00.0/tph_st

NAK

This is all low level details controled exclusively by the kernel
driver. Allowing userspace to mess it up will break drivers.

There is no justification to give userspace this kind of write access.

Jason