Nouveau - Aug 2025 - [PATCH v6 2/5] rust: pci: provide access to PCI Vendor values

On Fri Aug 22, 2025 at 11:03 AM JST, John Hubbard wrote:
> This allows callers to write Vendor::SOME_COMPANY instead of
> bindings::PCI_VENDOR_ID_SOME_COMPANY.
>
> New APIs:
>     Vendor::SOME_COMPANY
>     Vendor::as_raw()
>     Vendor: From<u32> for Vendor
>
> Cc: Danilo Krummrich <dakr at kernel.org>
> Cc: Alexandre Courbot <acourbot at nvidia.com>
> Cc: Elle Rhumsaa <elle at weathered-steel.dev>
> Signed-off-by: John Hubbard <jhubbard at nvidia.com>
> ---
>  rust/kernel/pci.rs    |   2 +-
>  rust/kernel/pci/id.rs | 355 +++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 355 insertions(+), 2 deletions(-)
>
> diff --git a/rust/kernel/pci.rs b/rust/kernel/pci.rs
> index 0faec49bf8a2..d4675b7d4a86 100644
> --- a/rust/kernel/pci.rs
> +++ b/rust/kernel/pci.rs
> @@ -25,7 +25,7 @@
>  
>  mod id;
>  
> -pub use self::id::{Class, ClassMask};
> +pub use self::id::{Class, ClassMask, Vendor};
>  
>  /// An adapter for the registration of PCI drivers.
>  pub struct Adapter<T: Driver>(T);
> diff --git a/rust/kernel/pci/id.rs b/rust/kernel/pci/id.rs
> index 1291553b4e15..dd91e25a6890 100644
> --- a/rust/kernel/pci/id.rs
> +++ b/rust/kernel/pci/id.rs
> @@ -2,7 +2,7 @@
>  
>  //! PCI device identifiers and related types.
>  //!
> -//! This module contains PCI class codes and supporting types.
> +//! This module contains PCI class codes, Vendor IDs, and supporting
types.
>  
>  use crate::{bindings, error::code::EINVAL, error::Error, prelude::*};
>  use core::fmt;
> @@ -115,6 +115,74 @@ fn try_from(value: u32) -> Result<Self,
Self::Error> {
>      }
>  }
>  
> +/// PCI vendor IDs.
> +///
> +/// Each entry contains the 16-bit PCI vendor ID as assigned by the PCI
SIG.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// # use kernel::{device::Core, pci::{self, Vendor}, prelude::*};
> +/// fn log_device_info(pdev: &pci::Device<Core>) ->
Result<()> {
> +///     // Get the raw PCI vendor ID and convert to Vendor
> +///     let vendor_id = pdev.vendor_id();
> +///     let vendor = Vendor::new(vendor_id.into());
> +///     dev_info!(
> +///         pdev.as_ref(),
> +///         "Device: Vendor={}, Device=0x{:x}\n",
> +///         vendor,
> +///         pdev.device_id()
> +///     );
> +///     Ok(())
> +/// }
> +/// ```
> +#[derive(Debug, Clone, Copy, PartialEq, Eq)]
> +#[repr(transparent)]
> +pub struct Vendor(u32);
> +
> +macro_rules! define_all_pci_vendors {
> +    (
> +        $($variant:ident = $binding:expr,)+
> +    ) => {
> +
> +        impl Vendor {
> +            $(
> +                #[allow(missing_docs)]
> +                pub const $variant: Self = Self($binding as u32);
> +            )+
> +        }
> +
> +        /// Convert a raw 16-bit vendor ID to a `Vendor`.
> +        impl From<u32> for Vendor {
> +            fn from(value: u32) -> Self {
> +                match value {
> +                    $(x if x == Self::$variant.0 => Self::$variant,)+
> +                    _ => Self::UNKNOWN,
> +                }
> +            }
Naive question from someone with a device tree background and almost no
PCI experience: one consequence of using `From` here is that if I create
an non-registered Vendor value (e.g. `let vendor Vendor::from(0xf0f0)`), then do
`vendor.as_raw()`, I won't get the value
passed initially but the one for `UNKNOWN`, e.g. `0xffff`. Are we ok
with this?
> +        }
> +    };
> +}
> +
> +/// Once constructed, a `Vendor` contains a valid PCI Vendor ID.
> +impl Vendor {
> +    /// Create a new Vendor from a raw 16-bit vendor ID.
The argument is 32-bit. :) Which triggers the question: why store these
as u32 if a u16 is the right size?

On Mon Aug 25, 2025 at 2:33 PM CEST, Alexandre Courbot
wrote:
>> +#[derive(Debug, Clone, Copy, PartialEq, Eq)]
>> +#[repr(transparent)]
>> +pub struct Vendor(u32);
>> +
>> +macro_rules! define_all_pci_vendors {
>> +    (
>> +        $($variant:ident = $binding:expr,)+
>> +    ) => {
>> +
>> +        impl Vendor {
>> +            $(
>> +                #[allow(missing_docs)]
>> +                pub const $variant: Self = Self($binding as u32);
>> +            )+
>> +        }
>> +
>> +        /// Convert a raw 16-bit vendor ID to a `Vendor`.
>> +        impl From<u32> for Vendor {
>> +            fn from(value: u32) -> Self {
>> +                match value {
>> +                    $(x if x == Self::$variant.0 =>
Self::$variant,)+
>> +                    _ => Self::UNKNOWN,
>> +                }
>> +            }
>
> Naive question from someone with a device tree background and almost no
> PCI experience: one consequence of using `From` here is that if I create
> an non-registered Vendor value (e.g. `let vendor >
Vendor::from(0xf0f0)`), then do `vendor.as_raw()`, I won't get the value
> passed initially but the one for `UNKNOWN`, e.g. `0xffff`. Are we ok
> with this?
I think that's fine, since we shouldn't actually hit this. Drivers
should only
ever use the pre-defined constants of Vendor; consequently the
Device::vendor_id() can't return UNKNOWN either.

So, I think the From impl is not ideal, since we can't limit its visibility.
In
order to improve this, I suggest to use Vendor::new() directly in the macro, and
make Vendor::new() private. The same goes for Class, I guess.

On 8/25/25 5:33 AM, Alexandre Courbot wrote:
>> +/// Once constructed, a `Vendor` contains a valid PCI Vendor ID.
>> +impl Vendor {
>> +    /// Create a new Vendor from a raw 16-bit vendor ID.
> 
> The argument is 32-bit. :) Which triggers the question: why store these
> as u32 if a u16 is the right size?
Good point! I'll change it to u16.


thanks,
-- 
John Hubbard