Re: [PATCH v2 1/2] rust: Update PCI binding safety comments and add inline compiler hint

["Benno Lossin" <lossin@kernel.org>]

On Fri Jul 11, 2025 at 1:22 AM CEST, Alistair Popple wrote:
> On Thu, Jul 10, 2025 at 10:01:05AM +0200, Benno Lossin wrote:
>> On Thu Jul 10, 2025 at 4:24 AM CEST, Alistair Popple wrote:
>> > diff --git a/rust/kernel/pci.rs b/rust/kernel/pci.rs
>> > index 8435f8132e38..5c35a66a5251 100644
>> > --- a/rust/kernel/pci.rs
>> > +++ b/rust/kernel/pci.rs
>> > @@ -371,14 +371,18 @@ fn as_raw(&self) -> *mut bindings::pci_dev {
>> >  
>> >  impl Device {
>> >      /// Returns the PCI vendor ID.
>> > +    #[inline]
>> >      pub fn vendor_id(&self) -> u16 {
>> > -        // SAFETY: `self.as_raw` is a valid pointer to a `struct pci_dev`.
>> > +        // SAFETY: by its type invariant `self.as_raw` is always a valid pointer to a
>> 
>> s/by its type invariant/by the type invariants of `Self`,/
>> s/always//
>> 
>> Also, which invariant does this refer to? The only one that I can see
>> is:
>> 
>>     /// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.
>
> Actually isn't that wrong? Shouldn't that read for "a valid `struct pci_dev`"?

Yeah it should probably be changed, I'm not sure what exactly is
required here, but this already would be an improvement:

    /// `self.0` is a valid `struct pci_dev`.

>> And this doesn't say anything about the validity of `self.as_raw()`...
>
> Isn't it up to whatever created this pci::Device to ensure the underlying struct
> pci_dev remains valid for at least the lifetime of `Self`?

Well yes and no. It is up to the creator of this specific `pci::Device`
to ensure that it is valid, but that is true for all creators of
`pci::Device`. In other words this property doesn't change while the
`pci::Device` is alive so we call it an "invariant".

When creating a `pci::Device`, you have to ensure all invariants are met
and then anyone using it can rely on them being true.

Now in this particular instance the `as_raw` function is just calling
`self.0.get()`. I'm not sure that's worth it, since it isn't even
shorter and it makes the safety docs a bit worse. So my suggestion would
be to remove it.

> Sorry I'm quite new to Rust (and especially Rust in the kernel), so
> not sure what the best way to express that in a SAFETY style comment
> would be. Are you saying the list of invariants for pci::Device also
> needs expanding?

No worries, safety documentation is pretty hard :)

---
Cheers,
Benno

>
> Thanks.
>
>> > +        // `struct pci_dev`.
>> >          unsafe { (*self.as_raw()).vendor }
>> >      }
>> >  
>> >      /// Returns the PCI device ID.
>> > +    #[inline]
>> >      pub fn device_id(&self) -> u16 {
>> > -        // SAFETY: `self.as_raw` is a valid pointer to a `struct pci_dev`.
>> > +        // SAFETY: by its type invariant `self.as_raw` is always a valid pointer to a
>> > +        // `struct pci_dev`.
>> 
>> Ditto here.
>> 
>> ---
>> Cheers,
>> Benno
>> 
>> >          unsafe { (*self.as_raw()).device }
>> >      }
>> >  
>>