Rust PCI capability infrastructure and SR-IOV support
cover Rust PCI capability infrastructure and SR-IOV support
This RFC series introduces PCI capability discovery and access infrastructure for Rust kernel drivers, with initial support for SR-IOV (Single Root I/O Virtualization) capabilities.
Background
----------
Modern PCI devices expose advanced features through capability structures in configuration space. Rust drivers need type-safe, ergonomic APIs to discover and access these capabilities while maintaining the kernel's existing safety guarantees. An example can be found in RFC patch. [1]
Overview
--------
Patch 1 extends ConfigSpace with fallible I/O methods that properly handle PCI bus errors, providing the foundation for safe capability access with runtime-determined offsets.
Patch 2 introduces the core capability infrastructure:
- Generic Capability<S, K> struct with Io trait implementation
- Capability size calculation using kernel's capability chaining
- SriovCapability wrapper for accessing VF configuration registers
- Support for reading VF Offset and VF BAR0/1/2 registers
Feedback Requested
------------------
1) The configuration cap doesn't have an fixed offset, thus it doesn't fit with the infallible accessors. But to have fallible accessors, it needs the config space backend to implement the fallible accessors as well. I tried different approaches, this seems the most reasonable one. Any thought?
2) Capability traits hierarchy
I was thinking several solutions of arranging common functions for Normal/Extended caps, all the extended caps. It seems a complicated traits hierarchy again. Would like to hear more about this.
[1] https://lore.kernel.org/all/[email protected]/
Zhi Wang (2):
pci: Add fallible I/O methods to ConfigSpace
pci: Add PCI capability infrastructure and SR-IOV capability support
rust/kernel/pci.rs | 9 ++ rust/kernel/pci/cap.rs | 274 +++++++++++++++++++++++++++++++++++++++++ rust/kernel/pci/io.rs | 34 ++++- 3 files changed, 314 insertions(+), 3 deletions(-) create mode 100644 rust/kernel/pci/cap.rs
Signature · 1 line
2.51.0
RFC 1/2 pci: Add fallible I/O methods to ConfigSpace
Rust PCI drivers might need to access device configuration space with runtime bound check. The existing ConfigSpace abstraction only provides infallible methods (read8/16/32) that use compile-time bounds checking via io_addr_assert, which cannot handle dynamic offsets.
Add fallible I/O methods to ConfigSpace.
--- rust/kernel/pci/io.rs | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-)
rust/kernel/pci/io.rs +31 -3
@@ -112,6 +112,17 @@ macro_rules! call_config_read { let _ret = unsafe { bindings::$c_fn($self.pdev.as_raw(), $addr as i32, &mut val) }; val }}; + + (fallible, $c_fn:ident, $self:ident, $ty:ty, $addr:expr) => {{ +let mut val: $ty =0 ; +// SAFETY: By the type invariant `$self.pdev` is a valid address. + let ret = unsafe { bindings::$c_fn($self.pdev.as_raw(), $addr as i32, &mut val) }; +if ret !=0 { +Err (EIO ) + }else { +Ok (val) + } + }}; }/// Internal helper macros used to invoke C PCI configuration space write functions.
@@ -140,6 +151,16 @@ macro_rules! call_config_write {// Return value from C function is ignored in infallible accessors. let _ret = unsafe { bindings::$c_fn($self.pdev.as_raw(), $addr as i32, $value) }; }; + + (fallible, $c_fn:ident, $self:ident, $ty:ty, $addr:expr, $value:expr) => {{ +// SAFETY: By the type invariant `$self.pdev` is a valid address. + let ret = unsafe { bindings::$c_fn($self.pdev.as_raw(), $addr as i32, $value) }; +if ret !=0 { +Err (EIO ) + }else { +Ok (()) + } + }}; }// PCI configuration space supports 8, 16, and 32-bit accesses.
@@ -162,9 +183,7 @@ fn maxsize(&self) -> usize { self.pdev.cfg_size ().into_raw () } -// PCI configuration space does not support fallible operations. -// The default implementations from the Io trait are not used. - +// Infallible methods with compile-time bounds checking define_read! (infallible, read8,call_config_read (pci_read_config_byte) ->u8 );define_read! (infallible, read16,call_config_read (pci_read_config_word) ->u16 );define_read! (infallible, read32,call_config_read (pci_read_config_dword) ->u32 );
@@ -172,6 +191,15 @@ fn maxsize(&self) -> usize {define_write! (infallible, write8,call_config_write (pci_write_config_byte) <-u8 );define_write! (infallible, write16,call_config_write (pci_write_config_word) <-u16 );define_write! (infallible, write32,call_config_write (pci_write_config_dword) <-u32 ); + +// Fallible methods with runtime bounds checking +define_read! (fallible, try_read8,call_config_read (pci_read_config_byte) ->u8 ); +define_read! (fallible, try_read16,call_config_read (pci_read_config_word) ->u16 ); +define_read! (fallible, try_read32,call_config_read (pci_read_config_dword) ->u32 ); + +define_write! (fallible, try_write8,call_config_write (pci_write_config_byte) <-u8 ); +define_write! (fallible, try_write16,call_config_write (pci_write_config_word) <-u16 ); +define_write! (fallible, try_write32,call_config_write (pci_write_config_dword) <-u32 ); }/// Marker trait indicating ConfigSpace has a known size at compile time.
Signature · 1 line
2.51.0
RFC 2/2 pci: Add PCI capability infrastructure and SR-IOV capability support
In reply to Zhi WangRust drivers may need to access PCI capabilities (such as SR-IOV) to configure firmware metadata.
Add a generic Capability<S, K> structure that:
- Wraps capability discovery via kernel's pci_find_ext_capability()
- Dynamically calculates capability size by reading next capability pointers (using 0xffc mask per PCI_EXT_CAP_NEXT for extended caps)
- Implements fallible I/O via the Io trait with runtime bounds checking
Add SR-IOV (Single Root I/O Virtualization) capability support:
- SriovCapability wraps Capability<Extended, Extended>
- read_vf_offset() reads PCI_SRIOV_VF_OFFSET register
- read_vf_bar(n) reads PCI_SRIOV_BAR + n*4 (32-bit BAR)
- read_vf_bar64(n) reads 64-bit BAR by combining two 32-bit reads
--- rust/kernel/pci.rs | 9 ++ rust/kernel/pci/cap.rs | 274 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 283 insertions(+) create mode 100644 rust/kernel/pci/cap.rs
rust/kernel/pci.rs +9 -0
@@ -31,6 +31,7 @@ }, }; +mod cap;mod id;mod io;mod irq;
@@ -42,6 +43,7 @@ };pub use self::io::{Bar , +ConfigSpace ,ConfigSpaceKind ,ConfigSpaceSize ,Extended ,
@@ -52,6 +54,13 @@ IrqTypes, IrqVector, // }; +pub use self::cap::{ +Capability , +CapabilityId , +CapabilityKind , +ExtCapabilityId , +SriovCapability ,// +};/// An adapter for the registration of PCI drivers. pub struct Adapter <T :Driver >(T );
rust/kernel/pci/cap.rs new file +274 -0
274 lines not on this page · raw message
Signature · 1 line
2.51.0
Gary Guo
reviewerRe: [RFC 2/2] pci: Add PCI capability infrastructure and SR-IOV capability support
Quoted 149 lines · Zhi Wang
Rust drivers may need to access PCI capabilities (such as SR-IOV) to configure firmware metadata.
Add a generic Capability<S, K> structure that:
- Wraps capability discovery via kernel'spci_find_ext_capability()
- Dynamically calculates capability size by reading next capability pointers (using0xffcmask perPCI_EXT_CAP_NEXTfor extended caps)
- Implements fallible I/O via the Io trait with runtime bounds checkingAdd SR-IOV (Single Root I/O Virtualization) capability support:
- SriovCapability wraps Capability<Extended, Extended>
-read_vf_offset()readsPCI_SRIOV_VF_OFFSETregister
-read_vf_bar(n)readsPCI_SRIOV_BAR+ n*4 (32-bit BAR)
-read_vf_bar64(n)reads 64-bit BAR by combining two 32-bit readsSigned-off-by Zhi Wang <[email protected]>--- rust/kernel/pci.rs | 9 ++ rust/kernel/pci/cap.rs | 274 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 283 insertions(+) create mode 100644 rust/kernel/pci/cap.rsrust/kernel/pci.rs +9
-0@@ -31,6 +31,7 @@ }, }; +mod cap;mod id;mod io;mod irq;@@ -42,6 +43,7 @@ };pub use self::io::{Bar , +ConfigSpace ,ConfigSpaceKind ,ConfigSpaceSize ,Extended ,@@ -52,6 +54,13 @@ IrqTypes, IrqVector, // }; +pub use self::cap::{ +Capability , +CapabilityId , +CapabilityKind , +ExtCapabilityId , +SriovCapability ,// +};/// An adapter for the registration of PCI drivers. pub struct Adapter <T :Driver >(T );rust/kernel/pci/cap.rs new file +87
-0@@ -0,0 +1,274 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! PCI Capability support. +//! +//! This module provides abstractions for discovering and accessing PCI capabilities. + +use super ::{ +ConfigSpace , +ConfigSpaceKind , +Extended , +Normal ,// +}; +use crate ::{ + bindings, + io::{ + define_read, + define_write, +Io , +IoCapable ,// + }, + prelude::*, +}; + +/// Internal helper macro to call ConfigSpace fallible methods from Capability. +macro_rules! call_cap_read { + (fallible, $method:ident, $self:ident, $ty:ty, $addr:expr) => { + $self.config_space.$method($self.offset () + $addr) + }; +} + +/// Internal helper macro to call ConfigSpace fallible write methods from Capability. +macro_rules! call_cap_write { + (fallible, $method:ident, $self:ident, $ty:ty, $addr:expr, $value:expr) => { + $self.config_space.$method($value, $self.offset () + $addr) + }; +} + +/// PCI Capability IDs for normal capabilities (in 256-byte config space). +/// +/// These are not currently implemented, but the enum is provided for API completeness. +#[repr( u8 )] +#[derive( Debug , Clone , Copy , PartialEq , Eq )] +pub enum CapabilityId { +/// Power Management +PM = bindings::PCI_CAP_ID_PM as u8 , +/// Message Signalled Interrupts +MSI = bindings::PCI_CAP_ID_MSI as u8 , +/// MSI-X +MSIX = bindings::PCI_CAP_ID_MSIX as u8 , +/// PCI Express +Express = bindings::PCI_CAP_ID_EXP as u8 , +/// Vendor Specific +VendorSpecific = bindings::PCI_CAP_ID_VNDR as u8 , +} + +/// PCI Extended Capability IDs (in 4096-byte config space). +/// +/// Currently only SR-IOV is implemented. +#[repr( u16 )] +#[derive( Debug , Clone , Copy , PartialEq , Eq )] +pub enum ExtCapabilityId { +/// Single Root I/O Virtualization +SRIOV = bindings::PCI_EXT_CAP_ID_SRIOV as u16 , +} + +/// Trait for capability kinds (Normal or Extended). +pub trait CapabilityKind { +/// The capability ID type for this kind. +type IdType :Copy +PartialEq ; + +/// Start offset for capability scanning. +const START_OFFSET :usize ; +} + +/// Marker for normal (legacy) PCI capabilities. +impl CapabilityKind for Normal { +type IdType =u8 ; +const START_OFFSET :usize = bindings::PCI_CAPABILITY_LIST as usize ; +} + +/// Marker for extended PCI capabilities. +impl CapabilityKind for Extended { +type IdType =u16 ; +const START_OFFSET :usize = bindings::PCI_CFG_SPACE_SIZE as usize ; +} + +/// A PCI capability.
rust/kernel/pci/cap.rs line 97
Quoted 10 lines
rust/kernel/pci/cap.rs new file +10
-0+/// +/// This type represents a discovered PCI capability and provides safe access +/// to its registers. All I/O operations are relative to the capability's +/// base offset in configuration space. +pub struct Capability <'a,S :ConfigSpaceKind ,K :CapabilityKind > { + config_space: &'aConfigSpace <'a,S >, + offset:usize , + id:K ::IdType , + size:usize , +}
Some thoughts about this: given that the IDs are different for PCI capability and PCI extended capabilities, it feels that we shouldn't overlap them into the same type.
The offset and size feels like it can be something more generic, something like
/// A subview into I/O.
pub struct IoView<T> {
io: T,
offset: usize,
size: usize,
}
impl<T: IO> IoView<T> {
// ....
}This is just like a slice, but act on arbitrary IO.
The capability enumeration can just be something like
fn capabilities(&self) -> impl Iterator<Item = (CapabilityId, IoView<&Self>)>
and another method for capabilities_ext.
If you want to add typed capabilities, an option is to have
enum Capability<'a> {
SpecificParsedCapability,
Other(CapabilityId, IoView<&ConfigSpace<...>>),
}Thoughts?
Best,
Gary
Quoted 177 lines
rust/kernel/pci/cap.rs new file +177
-0+ +impl <'a,S :ConfigSpaceKind ,K :CapabilityKind >Capability <'a,S ,K > { +/// Creates a new capability handle. +fn new ( + config_space: &'aConfigSpace <'a,S >, + offset:usize , + id:K ::IdType , + size:usize , + ) ->Self { +Self { + config_space, + offset, + id, + size, + } + } + +/// Returns the offset of this capability in configuration space. +pub fn offset (&self) ->usize { + self.offset + } + +/// Returns the capability ID. +pub fn id (&self) ->K ::IdType { + self.id + } + +/// Returns the size of this capability in bytes. +pub fn size (&self) ->usize { + self.size + } +} + +// Implement IoCapable for Capability +impl <'a,S :ConfigSpaceKind ,K :CapabilityKind >IoCapable <u8 >for Capability <'a,S ,K > {} +impl <'a,S :ConfigSpaceKind ,K :CapabilityKind >IoCapable <u16 >for Capability <'a,S ,K > {} +impl <'a,S :ConfigSpaceKind ,K :CapabilityKind >IoCapable <u32 >for Capability <'a,S ,K > {} + +// Implement Io trait for Capability using fallible methods (runtime checks) +impl <'a,S :ConfigSpaceKind ,K :CapabilityKind >Io for Capability <'a,S ,K > { +const MIN_SIZE :usize =S ::SIZE ;// Use config space size for fallible bounds checking + +#[inline] +fn addr (&self) ->usize { +0 // Offsets are relative to capability base, not absolute + } + +#[inline] +fn maxsize (&self) ->usize { + self.size () + } + +// Only implement fallible methods (no IoKnownSize, so infallible methods not available) +define_read! (fallible, try_read8,call_cap_read (try_read8) ->u8 ); +define_read! (fallible, try_read16,call_cap_read (try_read16) ->u16 ); +define_read! (fallible, try_read32,call_cap_read (try_read32) ->u32 ); + +define_write! (fallible, try_write8,call_cap_write (try_write8) <-u8 ); +define_write! (fallible, try_write16,call_cap_write (try_write16) <-u16 ); +define_write! (fallible, try_write32,call_cap_write (try_write32) <-u32 ); +} + +impl <'a>ConfigSpace <'a,Extended > { +/// Finds a specific extended capability by ID using the kernel's `pci_find_ext_capability`. +pub fn find_ext_capability (&self, id:u16 ) ->Option <Capability <'_,Extended ,Extended >> { +// SAFETY: pdev is valid by ConfigSpace invariants +let offset =unsafe { bindings::pci_find_ext_capability (self.pdev.as_raw (), idas i32 ) }; + +if offset ==0 { +return None ; + } + +let size = self.calculate_ext_cap_size (offsetas usize ); +Some (Capability ::new (self, offsetas usize , id, size)) + } + +fn calculate_ext_cap_size (&self, offset:usize ) ->usize { +// Extended capability header: [31:20] = next capability offset +// Use 0xffc mask (not 0xfff) to match kernel's PCI_EXT_CAP_NEXT macro +let header = self.try_read32 (offset).unwrap_or (0 ); +let next_ptr = ((header >>20 ) &0xffc )as usize ; + +if next_ptr ==0 { +// Last capability, size goes to end of config space + self.pdev.cfg_size ().into_raw () - offset + }else { +// Size is distance to next capability + next_ptr - offset + } + } + +/// Finds the next occurrence of a specific extended capability starting from a given position. +pub fn find_next_ext_capability ( + &self, + start_pos:u16 , + id:u16 , + ) ->Option <Capability <'_,Extended ,Extended >> { +// SAFETY: pdev is valid by ConfigSpace invariants +let offset =unsafe { + bindings::pci_find_next_ext_capability (self.pdev.as_raw (), start_pos, idas i32 ) + }; + +if offset ==0 { +return None ; + } + +// Calculate real capability size +let size = self.calculate_ext_cap_size (offsetas usize ); +Some (Capability ::new (self, offsetas usize , id, size)) + } +} + +/// SR-IOV register offsets (relative to the capability base). +mod sriov_offsets { +use crate ::bindings; + +/// First VF Offset register offset +pub (super )const VF_OFFSET :usize = bindings::PCI_SRIOV_VF_OFFSET as usize ; +/// VF BAR0 register offset (first of 6 VF BARs) +pub (super )const VF_BAR0 :usize = bindings::PCI_SRIOV_BAR as usize ; +} + +/// SR-IOV capability structure. +/// +/// This structure provides typed access to the SR-IOV extended capability +/// registers using the PCI configuration space backend. +pub struct SriovCapability <'a> { + cap:Capability <'a,Extended ,Extended >, +} + +impl <'a>SriovCapability <'a> { +/// Creates a new SR-IOV capability from an extended capability. +pub fn new (cap:Capability <'a,Extended ,Extended >) ->Result <Self > { +if cap.id () !=ExtCapabilityId ::SRIOV as u16 { +return Err (EINVAL ); + } +Ok (Self { cap }) + } + +/// Tries to find and create an SR-IOV capability from a config space. +pub fn from_config_space (config_space: &'aConfigSpace <'a,Extended >) ->Result <Self > { +let cap = config_space + .find_ext_capability (ExtCapabilityId ::SRIOV as u16 ) + .ok_or (ENODEV )?; +Self ::new (cap) + } + +/// Returns the offset of this capability in configuration space. +pub fn offset (&self) ->usize { + self.cap.offset () + } + +/// Reads the First VF Offset register. +pub fn read_vf_offset (&self) ->Result <u16 > { + self.cap.try_read16 (sriov_offsets::VF_OFFSET ) + } + +/// Reads a VF BAR register (32-bit). +/// Returns the 32-bit value of the specified VF BAR register. +pub fn read_vf_bar (&self, bar_index:usize ) ->Result <u32 > { +if bar_index >=6 { +return Err (EINVAL ); + } + self.cap.try_read32 (sriov_offsets::VF_BAR0 + bar_index *4 ) + } + +/// Reads a 64-bit VF BAR register. +/// Returns the 64-bit address combining BAR[n] (low) and BAR[n+1] (high). +pub fn read_vf_bar64 (&self, bar_index:usize ) ->Result <u64 > { +if bar_index >=5 { +return Err (EINVAL ); + } +let low = self.read_vf_bar (bar_index)?; +let high = self.read_vf_bar (bar_index +1 )?; +Ok ((u64::from (high) <<32 ) | u64::from (low)) + } +}
Re: [RFC 2/2] pci: Add PCI capability infrastructure and SR-IOV capability support
On Tue, 27 Jan 2026 15:36:29 +0000
"Gary Guo" <[email protected]> wrote:
snip
Quoted 19 lines
Quoted 19 lines
rust/kernel/pci/cap.rs new file +4
-0+/// Marker for normal (legacy) PCI capabilities. +impl CapabilityKind for Normal { +type IdType =u8 ; + const START_OFFSET: usize = bindings::PCI_CAPABILITY_LIST asusize; +}
rust/kernel/pci/cap.rs new file +5
-0+ +/// Marker for extended PCI capabilities. +impl CapabilityKind for Extended { +type IdType =u16 ; + const START_OFFSET: usize = bindings::PCI_CFG_SPACE_SIZE asusize; +}
rust/kernel/pci/cap.rs new file +4
-0+ +/// A PCI capability. +/// +/// This type represents a discovered PCI capability and provides safe access +/// to its registers. All I/O operations are relative to the capability's +/// base offset in configuration space.
(quoted diff) +2
-0+pub struct Capability<'a, S: ConfigSpaceKind, K: CapabilityKind> { + config_space: &'a ConfigSpace<'a, S>,
Quoted 9 lines
rust/kernel/pci/cap.rs line 97
Quoted 4 lines
rust/kernel/pci/cap.rs new file +4
-0+ offset: usize, + id: K::IdType, + size: usize, +}Some thoughts about this: given that the IDs are different for PCI capability and PCI extended capabilities, it feels that we shouldn't overlap them into the same type.
Make sense. Sorry for the late reply as I was evaluating what would be the impact of IoCapable trait refinement to this patch.
Quoted 14 lines
The
offsetandsizefeels like it can be something more generic, something like/// A subview into I/O. pub struct IoView<T> { io: T, offset: usize, size: usize, } impl<T: IO> IoView<T> { // .... }
Quoted 9 lines
This is just like a slice, but act on arbitrary IO.
The capability enumeration can just be something like
fn capabilities(&self) -> impl Iterator<Item = (CapabilityId,IoView<&Self>)>
and another method for
capabilities_ext.
I actually had a version of that, but dropped it. The C side already handles finding capabilities by ID, so a Rust iterator seemed redundant for the common case. Unless we need to handle multiple capabilities with the same ID (which is rare). IMO, it might be better we add it when a rust driver really need this.
Quoted 7 lines
If you want to add typed capabilities, an option is to have
enum Capability<'a> { SpecificParsedCapability, Other(CapabilityId, IoView<&ConfigSpace<...>>), }
But given that the kernel's C API favors looking up by ID, usage of an enum might be slightly awkward here (e.g., calling find_capability(ID) and still having to unwrap an enum)?
Quoted 209 lines
Thoughts?
Best,
GaryQuoted 202 lines
(quoted diff) +2
-0+ +impl<'a, S: ConfigSpaceKind, K: CapabilityKind> Capability<'a, S,K> {
rust/kernel/pci/cap.rs new file +16
-0+/// Creates a new capability handle. +fn new ( + config_space: &'aConfigSpace <'a,S >, + offset:usize , + id:K ::IdType , + size:usize , + ) ->Self { +Self { + config_space, + offset, + id, + size, + } + } + +/// Returns the offset of this capability in configuration space.
rust/kernel/pci/cap.rs new file +17
-0+pub fn offset (&self) ->usize { + self.offset + } + +/// Returns the capability ID. +pub fn id (&self) ->K ::IdType { + self.id + } + +/// Returns the size of this capability in bytes. +pub fn size (&self) ->usize { + self.size + } +} + +// Implement IoCapable for Capability +impl<'a, S: ConfigSpaceKind, K: CapabilityKind> IoCapable<u8> forCapability<'a, S, K> {} +impl<'a, S: ConfigSpaceKind, K:
CapabilityKind> IoCapable<u16> for Capability<'a, S, K> {} CapabilityKind> +impl<'a, S: ConfigSpaceKind, K: CapabilityKind> CapabilityKind> IoCapable<u32> for Capability<'a, S, K> {}(quoted diff) +2
-0+ +// Implement Io trait for Capability using fallible methods(runtime checks) +impl<'a, S: ConfigSpaceKind, K: CapabilityKind> Io for Capability<'a, S, K> {
+ constMIN_SIZE: usize =S::SIZE; // Use config space size for
fallible bounds checking +rust/kernel/pci/cap.rs new file +11
-0+#[inline] +fn addr (&self) ->usize { +0 // Offsets are relative to capability base, not absolute + } + +#[inline] +fn maxsize (&self) ->usize { + self.size () + } + +// Only implement fallible methods (no IoKnownSize, so infallible methods not available)
+ define_read!(fallible,try_read8,call_cap_read(try_read8)->
u8);(quoted diff) +3
-2+ define_read!(fallible, try_read16, call_cap_read(try_read16) -> u16); + define_read!(fallible, try_read32, call_cap_read(try_read32) -> u32); + + define_write!(fallible, try_write8, call_cap_write(try_write8)<- u8);
+ define_write!(fallible,try_write16,call_cap_write(try_write16)<- u16);
+ define_write!(fallible,try_write32,call_cap_write(try_write32)<- u32); +}rust/kernel/pci/cap.rs new file +3
-0+ +impl <'a>ConfigSpace <'a,Extended > { +/// Finds a specific extended capability by ID using the kernel's
pci_find_ext_capability.
+ pub fnfind_ext_capability(&self, id: u16)->
Option<Capability<'_, Extended, Extended>> {(quoted diff) +2
-0+ // SAFETY: pdev is valid by ConfigSpace invariants + let offset = unsafe {
bindings::pci_find_ext_capability(self.pdev.as_raw(), id as i32)};rust/kernel/pci/cap.rs new file +11
-0+ +if offset ==0 { +return None ; + } + +let size = self.calculate_ext_cap_size (offsetas usize ); +Some (Capability ::new (self, offsetas usize , id, size)) + } + +fn calculate_ext_cap_size (&self, offset:usize ) ->usize { +// Extended capability header: [31:20] = next capability offset
+ // Use0xffcmask (not0xfff) to match kernel'sPCI_EXT_CAP_NEXTmacrorust/kernel/pci/cap.rs new file +13
-0+let header = self.try_read32 (offset).unwrap_or (0 ); +let next_ptr = ((header >>20 ) &0xffc )as usize ; + +if next_ptr ==0 { +// Last capability, size goes to end of config space + self.pdev.cfg_size ().into_raw () - offset + }else { +// Size is distance to next capability + next_ptr - offset + } + } + +/// Finds the next occurrence of a specific extended capability starting from a given position.
rust/kernel/pci/cap.rs new file +8
-0+pub fn find_next_ext_capability ( + &self, + start_pos:u16 , + id:u16 , + ) ->Option <Capability <'_,Extended ,Extended >> { +// SAFETY: pdev is valid by ConfigSpace invariants +let offset =unsafe { +
bindings::pci_find_next_ext_capability(self.pdev.as_raw(), start_pos, id as i32)rust/kernel/pci/cap.rs new file +18
-0+ }; + +if offset ==0 { +return None ; + } + +// Calculate real capability size +let size = self.calculate_ext_cap_size (offsetas usize ); +Some (Capability ::new (self, offsetas usize , id, size)) + } +} + +/// SR-IOV register offsets (relative to the capability base). +mod sriov_offsets { +use crate ::bindings; + +/// First VF Offset register offset + pub(super) const VF_OFFSET: usize =
bindings::PCI_SRIOV_VF_OFFSETas usize;(quoted diff) +2
-0+ /// VF BAR0 register offset (first of 6 VF BARs) + pub(super) const VF_BAR0: usize = bindings::PCI_SRIOV_BAR asusize; +}
rust/kernel/pci/cap.rs new file +4
-0+ +/// SR-IOV capability structure. +/// +/// This structure provides typed access to the SR-IOV extended capability +/// registers using the PCI configuration space backend.
rust/kernel/pci/cap.rs new file +6
-0+pub struct SriovCapability <'a> { + cap:Capability <'a,Extended ,Extended >, +} + +impl <'a>SriovCapability <'a> { +/// Creates a new SR-IOV capability from an extended capability.
+ pub fnnew(cap: Capability<'a, Extended, Extended>)->
Result<Self> {rust/kernel/pci/cap.rs new file +7
-0+if cap.id () !=ExtCapabilityId ::SRIOV as u16 { +return Err (EINVAL ); + } +Ok (Self { cap }) + } + +/// Tries to find and create an SR-IOV capability from a config space.
+ pub fn from_config_space(config_space: &'a ConfigSpace<'a,
Extended>) -> Result<Self> {rust/kernel/pci/cap.rs new file +7
-0+let cap = config_space + .find_ext_capability (ExtCapabilityId ::SRIOV as u16 ) + .ok_or (ENODEV )?; +Self ::new (cap) + } + +/// Returns the offset of this capability in configuration space.
rust/kernel/pci/cap.rs new file +20
-0+pub fn offset (&self) ->usize { + self.cap.offset () + } + +/// Reads the First VF Offset register. +pub fn read_vf_offset (&self) ->Result <u16 > { + self.cap.try_read16 (sriov_offsets::VF_OFFSET ) + } + +/// Reads a VF BAR register (32-bit). +/// Returns the 32-bit value of the specified VF BAR register. +pub fn read_vf_bar (&self, bar_index:usize ) ->Result <u32 > { +if bar_index >=6 { +return Err (EINVAL ); + } + self.cap.try_read32 (sriov_offsets::VF_BAR0 + bar_index *4 ) + } + +/// Reads a 64-bit VF BAR register. +/// Returns the 64-bit address combining BAR[n] (low) and BAR[n+1] (high).
rust/kernel/pci/cap.rs new file +9
-0+pub fn read_vf_bar64 (&self, bar_index:usize ) ->Result <u64 > { +if bar_index >=5 { +return Err (EINVAL ); + } +let low = self.read_vf_bar (bar_index)?; +let high = self.read_vf_bar (bar_index +1 )?; +Ok ((u64::from (high) <<32 ) | u64::from (low)) + } +}
Gary Guo
reviewerRe: [RFC 2/2] pci: Add PCI capability infrastructure and SR-IOV capability support
Quoted 34 lines · Zhi Wang
On Tue, 27 Jan 2026 15:36:29 +0000
"Gary Guo" <[email protected]> wrote:snip
Quoted 19 lines
Quoted 19 lines
rust/kernel/pci/cap.rs new file +4
-0+/// Marker for normal (legacy) PCI capabilities. +impl CapabilityKind for Normal { +type IdType =u8 ; + const START_OFFSET: usize = bindings::PCI_CAPABILITY_LIST asusize; +}
rust/kernel/pci/cap.rs new file +5
-0+ +/// Marker for extended PCI capabilities. +impl CapabilityKind for Extended { +type IdType =u16 ; + const START_OFFSET: usize = bindings::PCI_CFG_SPACE_SIZE asusize; +}
rust/kernel/pci/cap.rs new file +4
-0+ +/// A PCI capability. +/// +/// This type represents a discovered PCI capability and provides safe access +/// to its registers. All I/O operations are relative to the capability's +/// base offset in configuration space.
(quoted diff) +2
-0+pub struct Capability<'a, S: ConfigSpaceKind, K: CapabilityKind> { + config_space: &'a ConfigSpace<'a, S>,Quoted 9 lines
rust/kernel/pci/cap.rs line 97
Quoted 4 lines
rust/kernel/pci/cap.rs new file +4
-0+ offset: usize, + id: K::IdType, + size: usize, +}Some thoughts about this: given that the IDs are different for PCI capability and PCI extended capabilities, it feels that we shouldn't overlap them into the same type.
Quoted 2 lines
Make sense. Sorry for the late reply as I was evaluating what would be the impact of IoCapable trait refinement to this patch.
There's a few discussions about this recently and I think we've determined a generic infrastrucutre for a subview of a I/O region is desired. I'm going to work on this in the upcoming weeks and would report my progress on Zulip. Let's coordinate there.
Quoted 22 lines
Quoted 22 lines
The
offsetandsizefeels like it can be something more generic, something like/// A subview into I/O. pub struct IoView<T> { io: T, offset: usize, size: usize, } impl<T: IO> IoView<T> { // .... }This is just like a slice, but act on arbitrary IO.
The capability enumeration can just be something like
fn capabilities(&self) -> impl Iterator<Item = (CapabilityId,IoView<&Self>)>
Quoted 8 lines
Quoted 2 lines
and another method for
capabilities_ext.I actually had a version of that, but dropped it. The C side already handles finding capabilities by ID, so a Rust iterator seemed redundant for the common case. Unless we need to handle multiple capabilities with the same ID (which is rare). IMO, it might be better we add it when a rust driver really need this.
If we're not going to expose any API that support enumeration at all, then what you say makes sense.
Quoted 9 lines
Quoted 8 lines
If you want to add typed capabilities, an option is to have
enum Capability<'a> { SpecificParsedCapability, Other(CapabilityId, IoView<&ConfigSpace<...>>), }
Quoted 3 lines
But given that the kernel's C API favors looking up by ID, usage of an enum might be slightly awkward here (e.g., calling
find_capability(ID)and still having to unwrap an enum)?
Indeed. What you have there makes sense for typed capability lookup.
Best,
Gary