[RFC PATCH 0/2] rust: pci: add config space accessors (and a small in-tree user)

[RFC PATCH 0/2] rust: pci: add config space accessors (and a small in-tree user)

[Zijing Zhang]

This RFC proposes adding basic PCI config space accessors to
`rust/kernel/pci`.
It also includes a tiny update to the existing Rust PCI driver sample to
exercise the new API.

Motivation
----------
Rust PCI drivers occasionally need to access PCI config space (e.g. for
capability discovery, SR-IOV queries, or MSI-related setup).

Having a small, reviewed API in `kernel::pci` avoids each Rust driver
growing its own ad-hoc wrappers and error handling around config space.

This RFC is also motivated by the "PCI MISC APIs" TODO item in
`Documentation/gpu/nova/core/todo.rst`: config space accessors as a first
step, with capability/MSI/SR-IOV helpers as follow-ups.

Proposed API
------------
Add the following methods to `pci::Device`:

  - read_config_u8/u16/u32(offset: u16) -> Result<T>
  - write_config_u8/u16/u32(offset: u16, val: T) -> Result

Notes
-----
This is intentionally a thin wrapper: it exposes a safe interface and
translates errors into `Result`, but it does not try to add policy or extra
validation.

  - No additional range/alignment checks are performed in Rust. If an
    argument needs validation beyond what the C PCI accessors already do,
    it should likely be addressed in the PCI core instead of in a Rust-only
    wrapper.
  - The underlying C helpers may return positive PCIBIOS status codes.
    These are mapped to the corresponding `-errno` values for Rust callers
    (same mapping as `pcibios_err_to_errno()` in `include/linux/pci.h`).

`pcibios_err_to_errno` mapping helper
-------------------------------------
The mapping logic is kept as a private helper in the `kernel::pci` module
rather than inside `Device`: it is not tied to any particular device
instance and may be reused by future PCI helpers.

Also, the C `pcibios_err_to_errno()` is a `static inline`, so Rust cannot
call it directly without adding an exported wrapper.

In-tree user
------------
The `samples/rust/rust_driver_pci` sample is updated to read vendor/device
IDs from config space (0x00/0x02) and print them during probe using
`dev_dbg!`.

Note: in the current Rust support, `dev_dbg!` does not hook into dynamic
debug and is compiled out unless Rust debug assertions are enabled.

For local testing, enable `CONFIG_RUST_DEBUG_ASSERTIONS=y` if you want
to see the `dev_dbg!` line.

Questions for reviewers
-----------------------
1) Does using `u16` for the config-space offset and returning `Result<T>`
   look OK?
2) Is mapping PCIBIOS status codes to `-errno` acceptable for Rust callers,
   or would you prefer we add a small exported C wrapper so Rust can reuse
   the existing `pcibios_err_to_errno()` helper directly?

Testing
-------
Build:
  - x86_64 defconfig-based kernel with Rust enabled.
  - Out-of-tree build directory (i.e. `make O=...`).
  - Options enabled for this test:
      * CONFIG_SAMPLES_RUST=y
      * CONFIG_SAMPLE_RUST_DRIVER_PCI=y (built-in)
      * CONFIG_RUST_DEBUG_ASSERTIONS=y

Runtime:
  - Booted the resulting bzImage under QEMU x86_64 with:
      * `-device virtio-serial-pci`
      * `-device pci-testdev`
  - Kernel command line included:
      * `loglevel=8`
  - Observed:
      * `pci-testdev data-match count: 1`
      * `Probe Rust PCI driver sample (... cfg: 0x1b36:0x0005).`

Zijing Zhang (2):
  rust: pci: add config space accessors
  samples: rust: pci: exercise config space accessors

 rust/kernel/pci.rs              | 86 +++++++++++++++++++++++++++++++++
 samples/rust/rust_driver_pci.rs |  8 ++-
 2 files changed, 92 insertions(+), 2 deletions(-)

-- 
2.52.0

[RFC PATCH 1/2] rust: pci: add config space accessors

[Zijing Zhang]

Add basic PCI config space accessors to kernel::pci::Device.

The underlying C helpers may return positive PCIBIOS status codes; map them
to standard -errno values for Rust callers.

Signed-off-by: Zijing Zhang <zijing.zhang@ry.rs>
---
 rust/kernel/pci.rs | 86 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/rust/kernel/pci.rs b/rust/kernel/pci.rs
index bea76ca9c3da..229290ffde47 100644
--- a/rust/kernel/pci.rs
+++ b/rust/kernel/pci.rs
@@ -47,6 +47,26 @@
     IrqVector, //
 };
 
+// Mirrors `pcibios_err_to_errno()` in `include/linux/pci.h`.
+//
+// That helper is a C `static inline` and thus not directly callable from Rust.
+// We keep the mapping local to this module so the `Device` API stays focused.
+fn pcibios_err_to_errno(err: c_int) -> c_int {
+    if err <= 0 {
+        return err;
+    }
+
+    match err as u32 {
+        bindings::PCIBIOS_FUNC_NOT_SUPPORTED => -(bindings::ENOENT as c_int),
+        bindings::PCIBIOS_BAD_VENDOR_ID => -(bindings::ENOTTY as c_int),
+        bindings::PCIBIOS_DEVICE_NOT_FOUND => -(bindings::ENODEV as c_int),
+        bindings::PCIBIOS_BAD_REGISTER_NUMBER => -(bindings::EFAULT as c_int),
+        bindings::PCIBIOS_SET_FAILED => -(bindings::EIO as c_int),
+        bindings::PCIBIOS_BUFFER_TOO_SMALL => -(bindings::ENOSPC as c_int),
+        _ => -(bindings::ERANGE as c_int),
+    }
+}
+
 /// An adapter for the registration of PCI drivers.
 pub struct Adapter<T: Driver>(T);
 
@@ -436,6 +456,72 @@ pub fn pci_class(&self) -> Class {
         // SAFETY: `self.as_raw` is a valid pointer to a `struct pci_dev`.
         Class::from_raw(unsafe { (*self.as_raw()).class })
     }
+
+    /// Reads a byte from PCI config space.
+    ///
+    /// `offset` is the config-space offset. For PCIe devices this may cover the extended config
+    /// space.
+    pub fn read_config_u8(&self, offset: u16) -> Result<u8> {
+        let offset = c_int::from(offset);
+        let mut val = 0u8;
+
+        // SAFETY: `self.as_raw()` points to a valid `struct pci_dev` and `val` is a valid out
+        // pointer.
+        let err = unsafe { bindings::pci_read_config_byte(self.as_raw(), offset, &mut val) };
+        to_result(pcibios_err_to_errno(err))?;
+        Ok(val)
+    }
+
+    /// Reads a 16-bit word from PCI config space.
+    pub fn read_config_u16(&self, offset: u16) -> Result<u16> {
+        let offset = c_int::from(offset);
+        let mut val = 0u16;
+
+        // SAFETY: `self.as_raw()` points to a valid `struct pci_dev` and `val` is a valid out
+        // pointer.
+        let err = unsafe { bindings::pci_read_config_word(self.as_raw(), offset, &mut val) };
+        to_result(pcibios_err_to_errno(err))?;
+        Ok(val)
+    }
+
+    /// Reads a 32-bit dword from PCI config space.
+    pub fn read_config_u32(&self, offset: u16) -> Result<u32> {
+        let offset = c_int::from(offset);
+        let mut val = 0u32;
+
+        // SAFETY: `self.as_raw()` points to a valid `struct pci_dev` and `val` is a valid out
+        // pointer.
+        let err = unsafe { bindings::pci_read_config_dword(self.as_raw(), offset, &mut val) };
+        to_result(pcibios_err_to_errno(err))?;
+        Ok(val)
+    }
+
+    /// Writes a byte to PCI config space.
+    pub fn write_config_u8(&self, offset: u16, val: u8) -> Result {
+        let offset = c_int::from(offset);
+
+        // SAFETY: `self.as_raw()` points to a valid `struct pci_dev`.
+        let err = unsafe { bindings::pci_write_config_byte(self.as_raw(), offset, val) };
+        to_result(pcibios_err_to_errno(err))
+    }
+
+    /// Writes a 16-bit word to PCI config space.
+    pub fn write_config_u16(&self, offset: u16, val: u16) -> Result {
+        let offset = c_int::from(offset);
+
+        // SAFETY: `self.as_raw()` points to a valid `struct pci_dev`.
+        let err = unsafe { bindings::pci_write_config_word(self.as_raw(), offset, val) };
+        to_result(pcibios_err_to_errno(err))
+    }
+
+    /// Writes a 32-bit dword to PCI config space.
+    pub fn write_config_u32(&self, offset: u16, val: u32) -> Result {
+        let offset = c_int::from(offset);
+
+        // SAFETY: `self.as_raw()` points to a valid `struct pci_dev`.
+        let err = unsafe { bindings::pci_write_config_dword(self.as_raw(), offset, val) };
+        to_result(pcibios_err_to_errno(err))
+    }
 }
 
 impl Device<device::Core> {
-- 
2.52.0

[RFC PATCH 2/2] samples: rust: pci: exercise config space accessors

[Zijing Zhang]

Use the new PCI config space accessors from the Rust PCI sample driver.

Signed-off-by: Zijing Zhang <zijing.zhang@ry.rs>
---
 samples/rust/rust_driver_pci.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/samples/rust/rust_driver_pci.rs b/samples/rust/rust_driver_pci.rs
index fa677991a5c4..1089352626fc 100644
--- a/samples/rust/rust_driver_pci.rs
+++ b/samples/rust/rust_driver_pci.rs
@@ -68,11 +68,15 @@ impl pci::Driver for SampleDriver {
     fn probe(pdev: &pci::Device<Core>, info: &Self::IdInfo) -> impl PinInit<Self, Error> {
         pin_init::pin_init_scope(move || {
             let vendor = pdev.vendor_id();
+            let vendor_cfg = pdev.read_config_u16(0x00)?;
+            let device_cfg = pdev.read_config_u16(0x02)?;
             dev_dbg!(
                 pdev.as_ref(),
-                "Probe Rust PCI driver sample (PCI ID: {}, 0x{:x}).\n",
+                "Probe Rust PCI driver sample (PCI ID: {}, 0x{:x}; cfg: 0x{:04x}:0x{:04x}).\n",
                 vendor,
-                pdev.device_id()
+                pdev.device_id(),
+                vendor_cfg,
+                device_cfg,
             );
 
             pdev.enable_device_mem()?;
-- 
2.52.0

Re: [RFC PATCH 0/2] rust: pci: add config space accessors (and a small in-tree user)

[Charalampos Mitrodimas]

Zijing Zhang <zijing.zhang@ry.rs> writes:

> This RFC proposes adding basic PCI config space accessors to
> `rust/kernel/pci`.
> It also includes a tiny update to the existing Rust PCI driver sample to
> exercise the new API.
>
> Motivation
> ----------
> Rust PCI drivers occasionally need to access PCI config space (e.g. for
> capability discovery, SR-IOV queries, or MSI-related setup).
>
> Having a small, reviewed API in `kernel::pci` avoids each Rust driver
> growing its own ad-hoc wrappers and error handling around config space.
>
> This RFC is also motivated by the "PCI MISC APIs" TODO item in
> `Documentation/gpu/nova/core/todo.rst`: config space accessors as a first
> step, with capability/MSI/SR-IOV helpers as follow-ups.
>
> Proposed API
> ------------
> Add the following methods to `pci::Device`:
>
>   - read_config_u8/u16/u32(offset: u16) -> Result<T>
>   - write_config_u8/u16/u32(offset: u16, val: T) -> Result
>
> Notes
> -----
> This is intentionally a thin wrapper: it exposes a safe interface and
> translates errors into `Result`, but it does not try to add policy or extra
> validation.
>
>   - No additional range/alignment checks are performed in Rust. If an
>     argument needs validation beyond what the C PCI accessors already do,
>     it should likely be addressed in the PCI core instead of in a Rust-only
>     wrapper.
>   - The underlying C helpers may return positive PCIBIOS status codes.
>     These are mapped to the corresponding `-errno` values for Rust callers
>     (same mapping as `pcibios_err_to_errno()` in `include/linux/pci.h`).
>
> `pcibios_err_to_errno` mapping helper
> -------------------------------------
> The mapping logic is kept as a private helper in the `kernel::pci` module
> rather than inside `Device`: it is not tied to any particular device
> instance and may be reused by future PCI helpers.
>
> Also, the C `pcibios_err_to_errno()` is a `static inline`, so Rust cannot
> call it directly without adding an exported wrapper.
>
> In-tree user
> ------------
> The `samples/rust/rust_driver_pci` sample is updated to read vendor/device
> IDs from config space (0x00/0x02) and print them during probe using
> `dev_dbg!`.
>
> Note: in the current Rust support, `dev_dbg!` does not hook into dynamic
> debug and is compiled out unless Rust debug assertions are enabled.
>
> For local testing, enable `CONFIG_RUST_DEBUG_ASSERTIONS=y` if you want
> to see the `dev_dbg!` line.
>
> Questions for reviewers
> -----------------------
> 1) Does using `u16` for the config-space offset and returning `Result<T>`
>    look OK?

IMO using u16 looks good to me, since it covers the full PCIe extended
config space while making negative offsets unrepresentable at the type
level.

> 2) Is mapping PCIBIOS status codes to `-errno` acceptable for Rust callers,
>    or would you prefer we add a small exported C wrapper so Rust can reuse
>    the existing `pcibios_err_to_errno()` helper directly?

Personally I would prefer a small exported C wrapper. Although the local
re-implementation works, I believe it is an established pattern in the
rust helpers (i.e. to wrap `static inline` helpers), so the Rust side
automatically stays in sync with any changes done in the C side, no
logic duplication etc.

>
> Testing
> -------
> Build:
>   - x86_64 defconfig-based kernel with Rust enabled.
>   - Out-of-tree build directory (i.e. `make O=...`).
>   - Options enabled for this test:
>       * CONFIG_SAMPLES_RUST=y
>       * CONFIG_SAMPLE_RUST_DRIVER_PCI=y (built-in)
>       * CONFIG_RUST_DEBUG_ASSERTIONS=y
>
> Runtime:
>   - Booted the resulting bzImage under QEMU x86_64 with:
>       * `-device virtio-serial-pci`
>       * `-device pci-testdev`
>   - Kernel command line included:
>       * `loglevel=8`
>   - Observed:
>       * `pci-testdev data-match count: 1`
>       * `Probe Rust PCI driver sample (... cfg: 0x1b36:0x0005).`

Tested-by: Charalampos Mitrodimas <charmitro@posteo.net>

  [    0.176714] rust_driver_pci 0000:00:02.0: Probe Rust PCI driver sample (PCI ID: REDHAT, 0x5; cfg: 0x1b36:0x0005).
  [    0.176727] rust_driver_pci 0000:00:02.0: enabling device (0000 -> 0002)
  [    0.177100] rust_driver_pci 0000:00:02.0: pci-testdev data-match count: 1

Cheers,
C. Mitrodimas

>
> Zijing Zhang (2):
>   rust: pci: add config space accessors
>   samples: rust: pci: exercise config space accessors
>
>  rust/kernel/pci.rs              | 86 +++++++++++++++++++++++++++++++++
>  samples/rust/rust_driver_pci.rs |  8 ++-
>  2 files changed, 92 insertions(+), 2 deletions(-)

Re: [RFC PATCH 0/2] rust: pci: add config space accessors (and a small in-tree user)

[Gary Guo]

On Fri Jan 30, 2026 at 5:10 PM GMT, Zijing Zhang wrote:
> This RFC proposes adding basic PCI config space accessors to
> `rust/kernel/pci`.
> It also includes a tiny update to the existing Rust PCI driver sample to
> exercise the new API.
>
> Motivation
> ----------
> Rust PCI drivers occasionally need to access PCI config space (e.g. for
> capability discovery, SR-IOV queries, or MSI-related setup).
>
> Having a small, reviewed API in `kernel::pci` avoids each Rust driver
> growing its own ad-hoc wrappers and error handling around config space.
>
> This RFC is also motivated by the "PCI MISC APIs" TODO item in
> `Documentation/gpu/nova/core/todo.rst`: config space accessors as a first
> step, with capability/MSI/SR-IOV helpers as follow-ups.
>
> Proposed API
> ------------
> Add the following methods to `pci::Device`:
>
>   - read_config_u8/u16/u32(offset: u16) -> Result<T>
>   - write_config_u8/u16/u32(offset: u16, val: T) -> Result

We already have config space merged.

Patch series: https://lore.kernel.org/rust-for-linux/20260121202212.4438-1-zhiw@nvidia.com/

Code: https://rust.docs.kernel.org/next/src/kernel/pci/io.rs.html

Although, I do noted that the documentation is not having it. It looks like
while we re-export `ConfigSpaceKind` and `ConfigSpaceSize`, we forgot to export
the most important `ConfigSpace` struct :/

Best,
Gary

>
> Notes
> -----
> This is intentionally a thin wrapper: it exposes a safe interface and
> translates errors into `Result`, but it does not try to add policy or extra
> validation.
>
>   - No additional range/alignment checks are performed in Rust. If an
>     argument needs validation beyond what the C PCI accessors already do,
>     it should likely be addressed in the PCI core instead of in a Rust-only
>     wrapper.
>   - The underlying C helpers may return positive PCIBIOS status codes.
>     These are mapped to the corresponding `-errno` values for Rust callers
>     (same mapping as `pcibios_err_to_errno()` in `include/linux/pci.h`).
>
> `pcibios_err_to_errno` mapping helper
> -------------------------------------
> The mapping logic is kept as a private helper in the `kernel::pci` module
> rather than inside `Device`: it is not tied to any particular device
> instance and may be reused by future PCI helpers.
>
> Also, the C `pcibios_err_to_errno()` is a `static inline`, so Rust cannot
> call it directly without adding an exported wrapper.
>
> In-tree user
> ------------
> The `samples/rust/rust_driver_pci` sample is updated to read vendor/device
> IDs from config space (0x00/0x02) and print them during probe using
> `dev_dbg!`.
>
> Note: in the current Rust support, `dev_dbg!` does not hook into dynamic
> debug and is compiled out unless Rust debug assertions are enabled.
>
> For local testing, enable `CONFIG_RUST_DEBUG_ASSERTIONS=y` if you want
> to see the `dev_dbg!` line.
>
> Questions for reviewers
> -----------------------
> 1) Does using `u16` for the config-space offset and returning `Result<T>`
>    look OK?
> 2) Is mapping PCIBIOS status codes to `-errno` acceptable for Rust callers,
>    or would you prefer we add a small exported C wrapper so Rust can reuse
>    the existing `pcibios_err_to_errno()` helper directly?
>
> Testing
> -------
> Build:
>   - x86_64 defconfig-based kernel with Rust enabled.
>   - Out-of-tree build directory (i.e. `make O=...`).
>   - Options enabled for this test:
>       * CONFIG_SAMPLES_RUST=y
>       * CONFIG_SAMPLE_RUST_DRIVER_PCI=y (built-in)
>       * CONFIG_RUST_DEBUG_ASSERTIONS=y
>
> Runtime:
>   - Booted the resulting bzImage under QEMU x86_64 with:
>       * `-device virtio-serial-pci`
>       * `-device pci-testdev`
>   - Kernel command line included:
>       * `loglevel=8`
>   - Observed:
>       * `pci-testdev data-match count: 1`
>       * `Probe Rust PCI driver sample (... cfg: 0x1b36:0x0005).`
>
> Zijing Zhang (2):
>   rust: pci: add config space accessors
>   samples: rust: pci: exercise config space accessors
>
>  rust/kernel/pci.rs              | 86 +++++++++++++++++++++++++++++++++
>  samples/rust/rust_driver_pci.rs |  8 ++-
>  2 files changed, 92 insertions(+), 2 deletions(-)

Re: [RFC PATCH 0/2] rust: pci: add config space accessors (and a small in-tree user)

[Alexandre Courbot]

On Sat Jan 31, 2026 at 2:10 AM JST, Zijing Zhang wrote:
> This RFC proposes adding basic PCI config space accessors to
> `rust/kernel/pci`.
> It also includes a tiny update to the existing Rust PCI driver sample to
> exercise the new API.

The following has already been merged:

https://lore.kernel.org/all/20260121202212.4438-1-zhiw@nvidia.com/

Re: [RFC PATCH 0/2] rust: pci: add config space accessors (and a small in-tree user)

[Zijing Zhang]

Hi Charalampos,

Thanks a lot for the review and for testing the RFC series (and for the Tested-by).
Much appreciated.

It turns out I missed that PCI config space support for Rust has already landed via
Zhi Wang’s series:
https://lore.kernel.org/rust-for-linux/20260121202212.4438-1-zhiw@nvidia.com/

So my RFC is redundant and I’ll stop pushing it to avoid wasting reviewers’ time.
Sorry for the noise.

However, Gary pointed out a real usability/doc issue in the current API: while
`ConfigSpaceKind`/`ConfigSpaceSize` are re-exported from `kernel::pci`, the
`ConfigSpace` struct itself is not, which makes it hard to name the returned type
from `Device::config_space*()` and also affects rustdoc.

I’ll send a small follow-up patch to re-export `ConfigSpace` from `kernel::pci`
shortly.

Thanks again,
Zijing

Re: [RFC PATCH 0/2] rust: pci: add config space accessors (and a small in-tree user)

[Charalampos Mitrodimas]

Zijing Zhang <zijing.zhang@ry.rs> writes:

> Hi Charalampos,
>
> Thanks a lot for the review and for testing the RFC series (and for the Tested-by).
> Much appreciated.
>
> It turns out I missed that PCI config space support for Rust has already landed via
> Zhi Wang’s series:
> https://lore.kernel.org/rust-for-linux/20260121202212.4438-1-zhiw@nvidia.com/
>
> So my RFC is redundant and I’ll stop pushing it to avoid wasting reviewers’ time.
> Sorry for the noise.

Mistakes happen, I also missed it myself.

Cheers,
C. Mitrodimas

>
> However, Gary pointed out a real usability/doc issue in the current API: while
> `ConfigSpaceKind`/`ConfigSpaceSize` are re-exported from `kernel::pci`, the
> `ConfigSpace` struct itself is not, which makes it hard to name the returned type
> from `Device::config_space*()` and also affects rustdoc.
>
> I’ll send a small follow-up patch to re-export `ConfigSpace` from `kernel::pci`
> shortly.
>
> Thanks again,
> Zijing