rust: Update PCI binding safety comments and add inline compiler hint
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.
---
Changes for v2:
- New for v2
--- rust/kernel/pci.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-)
rust/kernel/pci.rs +6 -2
@@ -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
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.
---
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
@@ -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
Benno Lossin
reviewerrust/kernel/pci.rs fn as_raw(&self) -> *mut bindings::pci_dev { · line 376
Quoted 12 lines · Alistair Popple
rust/kernel/pci.rs +2
-1@@ -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
-0unsafe { (*self.as_raw ()).device } }
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@@ -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,
BennoQuoted 3 lines
rust/kernel/pci.rs +0
-0unsafe { (*self.as_raw ()).device } }
Benno Lossin
reviewerQuoted 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@@ -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::Deviceto ensure the underlying structpci_devremains valid for at least the lifetime ofSelf?
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::Devicealso 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,
BennoQuoted 3 lines
rust/kernel/pci.rs +0
-0unsafe { (*self.as_raw ()).device } }
Danilo Krummrich
maintainerQuoted 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@@ -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. :)
Danilo Krummrich
maintainerQuoted 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@@ -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?
Benno Lossin
reviewerQuoted 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@@ -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 consequentlyself.as_raw()can only be a valid pointer to a structpci_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
Danilo Krummrich
maintainerQuoted 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@@ -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 consequentlyself.as_raw()can only be a valid pointer to a structpci_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
Guaranteeon 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.
Benno Lossin
reviewerQuoted 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@@ -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 consequentlyself.as_raw()can only be a valid pointer to a structpci_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
Guaranteeon 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 aGuaranteeto 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
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@@ -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 consequentlyself.as_raw()can only be a valid pointer to a structpci_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
Guaranteeon 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 aGuaranteeto 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
Danilo Krummrich
maintainerQuoted 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@@ -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 consequentlyself.as_raw()can only be a valid pointer to a structpci_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
Guaranteeon 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 aGuaranteeto 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.
Benno Lossin
reviewerQuoted 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
Danilo Krummrich
maintainerQuoted 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.
Benno Lossin
reviewerQuoted 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
Danilo Krummrich
maintainerQuoted 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.
Alice Ryhl
reviewerQuoted 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
Benno Lossin
reviewerQuoted 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
Danilo Krummrich
maintainerQuoted 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 anas_ptrfunction.
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.
Benno Lossin
reviewerQuoted 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 anas_ptrfunction.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
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@@ -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 consequentlyself.as_raw()can only be a valid pointer to a structpci_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
Guaranteeon 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 aGuaranteeto 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.
Benno Lossin
reviewerQuoted 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@@ -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 consequentlyself.as_raw()can only be a valid pointer to a structpci_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
Guaranteeon 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 aGuaranteeto 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