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 }
>> > }
>> >
>>
