Skip to contentSkip to conversation

rust: Update PCI binding safety comments and add inline compiler hint

PATCH Superseded Alistair Popple 4 participants 22 messages Jul 10, 2025 – Jul 28, 2025

Subsystems (3)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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

Update the safety comments to be consistent with other safety comments in the PCI bindings. Also add an inline compiler hint.

Cc Danilo Krummrich <[email protected]>
Cc Bjorn Helgaas <[email protected]>
Cc "Krzysztof Wilczyński" <[email protected]>
Cc Miguel Ojeda <[email protected]>
Cc Alex Gaynor <[email protected]>
Cc Boqun Feng <[email protected]>
Cc Gary Guo <[email protected]>
Cc "Björn Roy Baron" <[email protected]>
Cc Benno Lossin <[email protected]>
Cc Andreas Hindborg <[email protected]>
Cc Alice Ryhl <[email protected]>
Cc Trevor Gross <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc "Rafael J. Wysocki" <[email protected]>
Cc John Hubbard <[email protected]>
Cc Alexandre Courbot <[email protected]>

---

Changes for v2:

- New for v2

---
 rust/kernel/pci.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
rust/kernel/pci.rs +6 -2
index 8435f8132e38..5c35a66a5251 100644
@@ -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
+        // `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`.
         unsafe { (*self.as_raw()).device }
     }
 
Signature · 1 line
2.47.2
#1 lore raw

PATCH v2 2/2 rust: Add several miscellaneous PCI helpers

Add bindings to obtain a PCI device's resource start address, bus/ device function, revision ID and subsystem device and vendor IDs.

These will be used by the nova-core GPU driver which is currently in development.

Cc Danilo Krummrich <[email protected]>
Cc Bjorn Helgaas <[email protected]>
Cc "Krzysztof Wilczyński" <[email protected]>
Cc Miguel Ojeda <[email protected]>
Cc Alex Gaynor <[email protected]>
Cc Boqun Feng <[email protected]>
Cc Gary Guo <[email protected]>
Cc "Björn Roy Baron" <[email protected]>
Cc Benno Lossin <[email protected]>
Cc Andreas Hindborg <[email protected]>
Cc Alice Ryhl <[email protected]>
Cc Trevor Gross <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc "Rafael J. Wysocki" <[email protected]>
Cc John Hubbard <[email protected]>
Cc Alexandre Courbot <[email protected]>

---

Changes for v2:
- Update comments and add inline compiler hint.
- Add note for where these will be used.

---
 rust/helpers/pci.c | 10 ++++++++++
 rust/kernel/pci.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
rust/helpers/pci.c +10 -0
index cd0e6bf2cc4d..59d15bd4bdb1 100644
@@ -12,6 +12,16 @@ void *rust_helper_pci_get_drvdata(struct pci_dev *pdev)
 	return pci_get_drvdata(pdev);
 }
 
+u16 rust_helper_pci_dev_id(struct pci_dev *dev)
+{
+	return PCI_DEVID(dev->bus->number, dev->devfn);
+}
+
+resource_size_t rust_helper_pci_resource_start(struct pci_dev *pdev, int bar)
+{
+	return pci_resource_start(pdev, bar);
+}
+
 resource_size_t rust_helper_pci_resource_len(struct pci_dev *pdev, int bar)
 {
 	return pci_resource_len(pdev, bar);
rust/kernel/pci.rs +44 -0

50 lines not on this page · raw message

Signature · 1 line
2.47.2
reviewer
#2 lore raw
In reply to Alistair Popple

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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.

And this doesn't say anything about the validity of self.as_raw()...

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 385

Quoted 10 lines
rust/kernel/pci.rs +4 -1
+        // `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

Quoted 3 lines
rust/kernel/pci.rs +0 -0
         unsafe { (*self.as_raw()).device }
     }
 
#3 lore raw
Quoted 17 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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//

Quoted 4 lines

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"?

Quoted 1 line

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

Thanks.

Quoted 21 lines

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 385

Quoted 10 lines
rust/kernel/pci.rs +4 -1
+        // `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

Quoted 3 lines
rust/kernel/pci.rs +0 -0
         unsafe { (*self.as_raw()).device }
     }
 
reviewer
#4 lore raw
Quoted 18 lines · Alistair Popple
Quoted 17 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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//

Quoted 6 lines
Quoted 4 lines

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`.
Quoted 4 lines
Quoted 1 line

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.

Quoted 4 lines

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

Quoted 24 lines

Thanks.

Quoted 21 lines

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 385

Quoted 10 lines
rust/kernel/pci.rs +4 -1
+        // `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

Quoted 3 lines
rust/kernel/pci.rs +0 -0
         unsafe { (*self.as_raw()).device }
     }
 
maintainer
#5 lore raw
In reply to Alistair Popple
Quoted 18 lines · Alistair Popple
Quoted 17 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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//

Quoted 6 lines
Quoted 4 lines

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"?

Yes, and it's fixed in the driver-core tree already. :)

maintainer
#6 lore raw
In reply to Benno Lossin
Quoted 17 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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//

Quoted 6 lines

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.

And this doesn't say anything about the validity of self.as_raw()...

Hm...why not? If an instance of Self always represents a valid struct pci_dev, then consequently self.as_raw() can only be a valid pointer to a struct pci_dev, no?

reviewer
#7 lore raw
Quoted 21 lines · Danilo Krummrich
Quoted 20 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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:

Quoted 7 lines
Quoted 3 lines
    /// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.

And this doesn't say anything about the validity of self.as_raw()...

Hm...why not? If an instance of Self always represents a valid struct pci_dev, then consequently self.as_raw() can only be a valid pointer to a struct pci_dev, no?

While it's true, you need to look into the implementation of as_raw. It could very well return a null pointer...

This is where we can use a Guarantee on that function. But since it's not shorter than .0.get(), I would just remove it.

---
Cheers,
Benno

maintainer
#8 lore raw
Quoted 30 lines · Benno Lossin
Quoted 21 lines · Danilo Krummrich
Quoted 20 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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:

Quoted 7 lines
Quoted 3 lines
    /// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.

And this doesn't say anything about the validity of self.as_raw()...

Hm...why not? If an instance of Self always represents a valid struct pci_dev, then consequently self.as_raw() can only be a valid pointer to a struct pci_dev, no?

Quoted 5 lines

While it's true, you need to look into the implementation of as_raw. It could very well return a null pointer...

This is where we can use a Guarantee on that function. But since it's not shorter than .0.get(), I would just remove it.

We have 15 to 20 as_raw() methods of this kind in the tree. If this really needs a Guarantee to be clean, we should probably fix it up in a treewide change.

as_raw() is a common pattern and everyone knows what it does, .0.get() seems much less obvious.

reviewer
#9 lore raw
Quoted 34 lines · Danilo Krummrich
Quoted 33 lines · Benno Lossin
Quoted 21 lines · Danilo Krummrich
Quoted 20 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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:

Quoted 7 lines
Quoted 3 lines
    /// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.

And this doesn't say anything about the validity of self.as_raw()...

Hm...why not? If an instance of Self always represents a valid struct pci_dev, then consequently self.as_raw() can only be a valid pointer to a struct pci_dev, no?

While it's true, you need to look into the implementation of as_raw. It could very well return a null pointer...

Quoted 8 lines
Quoted 2 lines

This is where we can use a Guarantee on that function. But since it's not shorter than .0.get(), I would just remove it.

We have 15 to 20 as_raw() methods of this kind in the tree. If this really needs a Guarantee to be clean, we should probably fix it up in a treewide change.

as_raw() is a common pattern and everyone knows what it does, .0.get() seems much less obvious.

Yeah I guess then we need to do the treewide change... I don't have the bandwidth for that, we can probably make this a good-first-issue.

---
Cheers,
Benno

#10 lore raw
Quoted 35 lines · Benno Lossin
Quoted 34 lines · Danilo Krummrich
Quoted 33 lines · Benno Lossin
Quoted 21 lines · Danilo Krummrich
Quoted 20 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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:

Quoted 7 lines
Quoted 3 lines
    /// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.

And this doesn't say anything about the validity of self.as_raw()...

Hm...why not? If an instance of Self always represents a valid struct pci_dev, then consequently self.as_raw() can only be a valid pointer to a struct pci_dev, no?

While it's true, you need to look into the implementation of as_raw. It could very well return a null pointer...

Quoted 8 lines
Quoted 8 lines
Quoted 2 lines

This is where we can use a Guarantee on that function. But since it's not shorter than .0.get(), I would just remove it.

We have 15 to 20 as_raw() methods of this kind in the tree. If this really needs a Guarantee to be clean, we should probably fix it up in a treewide change.

as_raw() is a common pattern and everyone knows what it does, .0.get() seems much less obvious.

Coming from a C kernel programming background I agree .as_raw() is more obvious than .0.get(). However now I'm confused ... what if anything needs changing to get these two small patches merged?

Thanks.

- Alistair

Quoted 6 lines

Yeah I guess then we need to do the treewide change... I don't have the bandwidth for that, we can probably make this a good-first-issue.

---
Cheers,
Benno

maintainer
#11 lore raw
Quoted 42 lines · Alistair Popple
Quoted 41 lines · Benno Lossin
Quoted 40 lines · Danilo Krummrich
Quoted 30 lines · Benno Lossin
Quoted 21 lines · Danilo Krummrich
Quoted 20 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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:

Quoted 7 lines
Quoted 3 lines
    /// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.

And this doesn't say anything about the validity of self.as_raw()...

Hm...why not? If an instance of Self always represents a valid struct pci_dev, then consequently self.as_raw() can only be a valid pointer to a struct pci_dev, no?

Quoted 5 lines

While it's true, you need to look into the implementation of as_raw. It could very well return a null pointer...

This is where we can use a Guarantee on that function. But since it's not shorter than .0.get(), I would just remove it.

We have 15 to 20 as_raw() methods of this kind in the tree. If this really needs a Guarantee to be clean, we should probably fix it up in a treewide change.

Quoted 6 lines
Quoted 2 lines
Quoted 2 lines

as_raw() is a common pattern and everyone knows what it does, .0.get() seems much less obvious.

Coming from a C kernel programming background I agree .as_raw() is more obvious than .0.get(). However now I'm confused ... what if anything needs changing to get these two small patches merged?

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

One minor nit would be to start the safety comments with a capital letter instead.

reviewer
#12 lore raw
Quoted 8 lines · Danilo Krummrich

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

At a minimum I'd say "The returned pointer is valid.", but that doesn't really say for what it's valid... AFAIK you're mostly using this pointer to pass it to the C side, in that case, how about:

    /// # Guarantees
    ///
    /// The returned pointer is valid for reads and writes from the C side for as long as `self` exists.

Maybe we need to change it a bit more, but let's just start with this.

(If you're also using the pointer from Rust, then we need to make changes)

---
Cheers,
Benno

maintainer
#13 lore raw
Quoted 5 lines · Benno Lossin
Quoted 4 lines · Danilo Krummrich

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Quoted 8 lines
Quoted 4 lines

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

At a minimum I'd say "The returned pointer is valid.", but that doesn't really say for what it's valid... AFAIK you're mostly using this pointer to pass it to the C side, in that case, how about:

It is used for for FFI calls and to access fields of the underlying struct pci_dev.

Quoted 5 lines
     /// # Guarantees
     ///
     /// The returned pointer is valid for reads and writes from the C side for as long as `self` exists.

Maybe we need to change it a bit more, but let's just start with this.

reviewer
#14 lore raw
Quoted 9 lines · Danilo Krummrich
Quoted 8 lines · Benno Lossin
Quoted 7 lines · Danilo Krummrich

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

Quoted 8 lines
Quoted 5 lines
Quoted 1 line

@Benno: Any proposal on what this section should say?

At a minimum I'd say "The returned pointer is valid.", but that doesn't really say for what it's valid... AFAIK you're mostly using this pointer to pass it to the C side, in that case, how about:

It is used for for FFI calls and to access fields of the underlying struct pci_dev.

By "access fields" you mean read-only?

---
Cheers,
Benno

maintainer
#15 lore raw
Quoted 12 lines · Benno Lossin
Quoted 11 lines · Danilo Krummrich
Quoted 10 lines · Benno Lossin
Quoted 8 lines · Danilo Krummrich

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

Quoted 8 lines
Quoted 6 lines
Quoted 3 lines

At a minimum I'd say "The returned pointer is valid.", but that doesn't really say for what it's valid... AFAIK you're mostly using this pointer to pass it to the C side, in that case, how about:

It is used for for FFI calls and to access fields of the underlying struct pci_dev.

By "access fields" you mean read-only?

We might also write them, but currently we only write them through FFI calls on the C side.

reviewer
#16 lore raw
In reply to Benno Lossin
Quoted 15 lines · Benno Lossin
Quoted 8 lines · Danilo Krummrich

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

At a minimum I'd say "The returned pointer is valid.", but that doesn't really say for what it's valid... AFAIK you're mostly using this pointer to pass it to the C side, in that case, how about:

Quoted 8 lines
    /// # Guarantees
    ///
    /// The returned pointer is valid for reads and writes from the C side for as long as `self` exists.

Maybe we need to change it a bit more, but let's just start with this.

(If you're also using the pointer from Rust, then we need to make changes)

Honestly I think this is a bit over the top. I wouldn't bother adding a section like that to every single as_raw() method out there.

Alice

reviewer
#17 lore raw
Quoted 20 lines · Alice Ryhl
Quoted 19 lines · Benno Lossin
Quoted 8 lines · Danilo Krummrich

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

At a minimum I'd say "The returned pointer is valid.", but that doesn't really say for what it's valid... AFAIK you're mostly using this pointer to pass it to the C side, in that case, how about:

    /// # Guarantees
    ///
    /// The returned pointer is valid for reads and writes from the C side for as long as `self` exists.
Quoted 7 lines
Quoted 4 lines

Maybe we need to change it a bit more, but let's just start with this.

(If you're also using the pointer from Rust, then we need to make changes)

Honestly I think this is a bit over the top. I wouldn't bother adding a section like that to every single as_raw() method out there.

Hmm. And then just assume that these kinds of functions return valid pointers? I get that this is annoying to put on every function...

Another option would be to have a Ptr<'a, T> type that is a valid pointer, but doesn't allow writing/reading safely (you need to justify why it's not a data race). And for FFI there could be an as_ptr function.

---
Cheers,
Benno

maintainer
#18 lore raw
Quoted 29 lines · Benno Lossin
Quoted 20 lines · Alice Ryhl
Quoted 19 lines · Benno Lossin
Quoted 8 lines · Danilo Krummrich

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

At a minimum I'd say "The returned pointer is valid.", but that doesn't really say for what it's valid... AFAIK you're mostly using this pointer to pass it to the C side, in that case, how about:

    /// # Guarantees
    ///
    /// The returned pointer is valid for reads and writes from the C side for as long as `self` exists.
Quoted 7 lines
Quoted 4 lines

Maybe we need to change it a bit more, but let's just start with this.

(If you're also using the pointer from Rust, then we need to make changes)

Honestly I think this is a bit over the top. I wouldn't bother adding a section like that to every single as_raw() method out there.

Quoted 7 lines

Hmm. And then just assume that these kinds of functions return valid pointers? I get that this is annoying to put on every function...

Another option would be to have a Ptr<'a, T> type that is a valid pointer, but doesn't allow writing/reading safely (you need to justify why it's not a data race). And for FFI there could be an as_ptr function.

I don't understand where's the difference between the two. For FFI calls we'd also have to justify it's not a data race, no?

The only guarantee we take as granted from as_raw() is that it returns a raw pointer to the wrapped FFI type in Self, i.e. it points to valid memory. Any additional guarantees may come from the context where the pointer is used and which specific fields it is used to access.

reviewer
#19 lore raw
Quoted 33 lines · Danilo Krummrich
Quoted 32 lines · Benno Lossin
Quoted 20 lines · Alice Ryhl
Quoted 19 lines · Benno Lossin
Quoted 8 lines · Danilo Krummrich

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

At a minimum I'd say "The returned pointer is valid.", but that doesn't really say for what it's valid... AFAIK you're mostly using this pointer to pass it to the C side, in that case, how about:

    /// # Guarantees
    ///
    /// The returned pointer is valid for reads and writes from the C side for as long as `self` exists.
Quoted 7 lines
Quoted 4 lines

Maybe we need to change it a bit more, but let's just start with this.

(If you're also using the pointer from Rust, then we need to make changes)

Honestly I think this is a bit over the top. I wouldn't bother adding a section like that to every single as_raw() method out there.

Hmm. And then just assume that these kinds of functions return valid pointers? I get that this is annoying to put on every function...

Quoted 7 lines
Quoted 4 lines

Another option would be to have a Ptr<'a, T> type that is a valid pointer, but doesn't allow writing/reading safely (you need to justify why it's not a data race). And for FFI there could be an as_ptr function.

I don't understand where's the difference between the two. For FFI calls we'd also have to justify it's not a data race, no?

Yes, but there you need a raw pointer.

Quoted 4 lines

The only guarantee we take as granted from as_raw() is that it returns a raw pointer to the wrapped FFI type in Self, i.e. it points to valid memory. Any additional guarantees may come from the context where the pointer is used and which specific fields it is used to access.

Sure you need additional guarantees from the context, but you also need the fact that the pointer coming from as_raw isn't just a random pointer, but that it is derived from the reference...

I don't have any good plan forward for this, so maybe we should revisit this in the future...

---
Cheers,
Benno

#20 lore raw
In reply to Danilo Krummrich
Quoted 46 lines · Danilo Krummrich
Quoted 45 lines · Alistair Popple
Quoted 43 lines · Benno Lossin
Quoted 42 lines · Danilo Krummrich
Quoted 30 lines · Benno Lossin
Quoted 21 lines · Danilo Krummrich
Quoted 20 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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:

Quoted 7 lines
Quoted 3 lines
    /// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.

And this doesn't say anything about the validity of self.as_raw()...

Hm...why not? If an instance of Self always represents a valid struct pci_dev, then consequently self.as_raw() can only be a valid pointer to a struct pci_dev, no?

Quoted 5 lines

While it's true, you need to look into the implementation of as_raw. It could very well return a null pointer...

This is where we can use a Guarantee on that function. But since it's not shorter than .0.get(), I would just remove it.

We have 15 to 20 as_raw() methods of this kind in the tree. If this really needs a Guarantee to be clean, we should probably fix it up in a treewide change.

as_raw() is a common pattern and everyone knows what it does, .0.get() seems much less obvious.

Quoted 7 lines
Quoted 3 lines

Coming from a C kernel programming background I agree .as_raw() is more obvious than .0.get(). However now I'm confused ... what if anything needs changing to get these two small patches merged?

I think they're good, but we're pretty late in the cycle now. That should be fine though, we can probably take them through the nova tree, or in the worst case share a tag, if needed.

Thanks, although I don't have any burning need to get them in for this cycle. Next cycle would be fine too, I just wanted to make progress getting them off my TODO list and it wasn't clear if more changes were needed.

On that front is seems like the discussion has settled on maybe we need to do something in future, but not for these patches? So aside from the minor nit below (which I will fix) I don't know of anything else that needs changing.

Quoted 7 lines

Given that, it would probably be good to add the Guarantee section on as_raw(), as proposed by Benno, right away.

@Benno: Any proposal on what this section should say?

One minor nit would be to start the safety comments with a capital letter instead.

reviewer
#21 lore raw
In reply to Alistair Popple
Quoted 39 lines · Alistair Popple
Quoted 38 lines · Benno Lossin
Quoted 37 lines · Danilo Krummrich
Quoted 35 lines · Benno Lossin
Quoted 21 lines · Danilo Krummrich
Quoted 20 lines · Benno Lossin

rust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376

Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2 -1
index 8435f8132e38..5c35a66a5251 100644
@@ -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:

Quoted 7 lines
Quoted 3 lines
    /// A [`Device`] instance represents a valid `struct device` created by the C portion of the kernel.

And this doesn't say anything about the validity of self.as_raw()...

Hm...why not? If an instance of Self always represents a valid struct pci_dev, then consequently self.as_raw() can only be a valid pointer to a struct pci_dev, no?

While it's true, you need to look into the implementation of as_raw. It could very well return a null pointer...

This is where we can use a Guarantee on that function. But since it's not shorter than .0.get(), I would just remove it.

Quoted 8 lines
Quoted 5 lines
Quoted 5 lines

We have 15 to 20 as_raw() methods of this kind in the tree. If this really needs a Guarantee to be clean, we should probably fix it up in a treewide change.

as_raw() is a common pattern and everyone knows what it does, .0.get() seems much less obvious.

Coming from a C kernel programming background I agree .as_raw() is more obvious than .0.get().

Makes sense, then I wouldn't recommend changing it.

Quoted 2 lines

However now I'm confused ... what if anything needs changing to get these two small patches merged?

I'd like to see as_raw get a Guarantee section, but that is independent from this patch series.

---
Cheers,
Benno