In preparation for ioremap support, add a Rust abstraction for struct
resource.

A future commit will introduce the Rust API to ioremap a resource from a
platform device. The current abstraction, therefore, adds only the
minimum API needed to get that done.

Co-developed-by: Fiona Behrens <me@kloenk.dev>
Signed-off-by: Fiona Behrens <me@kloenk.dev>
Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
---
 rust/bindings/bindings_helper.h |   1 +
 rust/helpers/io.c               |  36 +++++++
 rust/kernel/io.rs               |   4 +
 rust/kernel/io/resource.rs      | 209 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 250 insertions(+)

diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
index 7e8f2285064797d5bbac5583990ff823b76c6bdc..5f795e60e889b9fc887013743c81b1cf92a52adb 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -53,6 +53,7 @@
 #include <linux/file.h>
 #include <linux/firmware.h>
 #include <linux/fs.h>
+#include <linux/ioport.h>
 #include <linux/jiffies.h>
 #include <linux/jump_label.h>
 #include <linux/mdio.h>
diff --git a/rust/helpers/io.c b/rust/helpers/io.c
index 15ea187c5466256effd07efe6f6995a1dd95a967..404776cf6717c8570c7600a24712ce6e4623d3c6 100644
--- a/rust/helpers/io.c
+++ b/rust/helpers/io.c
@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: GPL-2.0
 
 #include <linux/io.h>
+#include <linux/ioport.h>
 
 void __iomem *rust_helper_ioremap(phys_addr_t offset, size_t size)
 {
@@ -99,3 +100,38 @@ void rust_helper_writeq_relaxed(u64 value, void __iomem *addr)
 	writeq_relaxed(value, addr);
 }
 #endif
+
+resource_size_t rust_helper_resource_size(struct resource *res)
+{
+	return resource_size(res);
+}
+
+struct resource *rust_helper_request_mem_region(resource_size_t start,
+						resource_size_t n,
+						const char *name)
+{
+	return request_mem_region(start, n, name);
+}
+
+void rust_helper_release_mem_region(resource_size_t start, resource_size_t n)
+{
+	release_mem_region(start, n);
+}
+
+struct resource *rust_helper_request_region(resource_size_t start,
+					    resource_size_t n, const char *name)
+{
+	return request_region(start, n, name);
+}
+
+struct resource *rust_helper_request_muxed_region(resource_size_t start,
+						  resource_size_t n,
+						  const char *name)
+{
+	return request_muxed_region(start, n, name);
+}
+
+void rust_helper_release_region(resource_size_t start, resource_size_t n)
+{
+	release_region(start, n);
+}
diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 72d80a6f131e3e826ecd9d2c3bcf54e89aa60cc3..7b70d5b5477e57d6d0f24bcd26bd8b0071721bc0 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -7,6 +7,10 @@
 use crate::error::{code::EINVAL, Result};
 use crate::{bindings, build_assert};
 
+pub mod resource;
+
+pub use resource::Resource;
+
 /// Raw representation of an MMIO region.
 ///
 /// By itself, the existence of an instance of this structure does not provide any guarantees that
diff --git a/rust/kernel/io/resource.rs b/rust/kernel/io/resource.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a8ad04b1abf8e46928ed98564e64a07180250024
--- /dev/null
+++ b/rust/kernel/io/resource.rs
@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Abstractions for [system
+//! resources](https://docs.kernel.org/core-api/kernel-api.html#resources-management).
+//!
+//! C header: [`include/linux/ioport.h`](srctree/include/linux/ioport.h)
+
+use core::ops::Deref;
+use core::ptr::NonNull;
+
+use crate::str::CStr;
+use crate::types::Opaque;
+
+/// Resource Size type.
+///
+/// This is a type alias to either `u32` or `u64` depending on the config option
+/// `CONFIG_PHYS_ADDR_T_64BIT`.
+#[cfg(CONFIG_PHYS_ADDR_T_64BIT)]
+pub type ResourceSize = u64;
+
+/// Resource Size type.
+///
+/// This is a type alias to either `u32` or `u64` depending on the config option
+/// `CONFIG_PHYS_ADDR_T_64BIT`.
+#[cfg(not(CONFIG_PHYS_ADDR_T_64BIT))]
+pub type ResourceSize = u32;
+
+/// A region allocated from a parent [`Resource`].
+///
+/// # Invariants
+///
+/// - `self.0` points to a valid `bindings::resource` that was obtained through
+///   `bindings::__request_region`.
+pub struct Region(NonNull<bindings::resource>);
+
+impl Deref for Region {
+    type Target = Resource;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: Safe as per the invariant of `Region`.
+        unsafe { Resource::as_ref(self.0.as_ptr()) }
+    }
+}
+
+impl Drop for Region {
+    fn drop(&mut self) {
+        // SAFETY: Safe as per the invariant of `Region`.
+        let res = unsafe { Resource::as_ref(self.0.as_ptr()) };
+        let flags = res.flags();
+
+        let release_fn = if flags.contains(flags::IORESOURCE_MEM) {
+            bindings::release_mem_region
+        } else {
+            bindings::release_region
+        };
+
+        // SAFETY: Safe as per the invariant of `Region`.
+        unsafe { release_fn(res.start(), res.size()) };
+    }
+}
+
+// SAFETY: `Region` only holds a pointer to a C `struct resource`, which is safe to be used from
+// any thread.
+unsafe impl Send for Region {}
+
+// SAFETY: `Region` only holds a pointer to a C `struct resource`, references to which are
+// safe to be used from any thread.
+unsafe impl Sync for Region {}
+
+/// A resource abstraction.
+///
+/// # Invariants
+///
+/// [`Resource`] is a transparent wrapper around a valid `bindings::resource`.
+#[repr(transparent)]
+pub struct Resource(Opaque<bindings::resource>);
+
+impl Resource {
+    /// Creates a reference to a [`Resource`] from a valid pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that for the duration of 'a, the pointer will
+    /// point at a valid `bindings::resource`.
+    ///
+    /// The caller must also ensure that the [`Resource`] is only accessed via the
+    /// returned reference for the duration of 'a.
+    pub(crate) const unsafe fn as_ref<'a>(ptr: *mut bindings::resource) -> &'a Self {
+        // SAFETY: Self is a transparent wrapper around `Opaque<bindings::resource>`.
+        unsafe { &*ptr.cast() }
+    }
+
+    /// Requests a resource region.
+    ///
+    /// Exclusive access will be given and the region will be marked as busy.
+    /// Further calls to [`Self::request_region`] will return [`None`] if
+    /// the region, or a part of it, is already in use.
+    pub fn request_region(
+        &self,
+        start: ResourceSize,
+        size: ResourceSize,
+        name: &'static CStr,
+        flags: Flags,
+    ) -> Option<Region> {
+        // SAFETY: Safe as per the invariant of `Resource`.
+        let region = unsafe {
+            bindings::__request_region(
+                self.0.get(),
+                start,
+                size,
+                name.as_char_ptr(),
+                flags.0 as i32,
+            )
+        };
+
+        Some(Region(NonNull::new(region)?))
+    }
+
+    /// Returns the size of the resource.
+    pub fn size(&self) -> ResourceSize {
+        let inner = self.0.get();
+        // SAFETY: safe as per the invariants of `Resource`.
+        unsafe { bindings::resource_size(inner) }
+    }
+
+    /// Returns the start address of the resource.
+    pub fn start(&self) -> u64 {
+        let inner = self.0.get();
+        // SAFETY: safe as per the invariants of `Resource`.
+        unsafe { *inner }.start
+    }
+
+    /// Returns the name of the resource.
+    pub fn name(&self) -> &'static CStr {
+        let inner = self.0.get();
+        // SAFETY: safe as per the invariants of `Resource`
+        unsafe { CStr::from_char_ptr((*inner).name) }
+    }
+
+    /// Returns the flags associated with the resource.
+    pub fn flags(&self) -> Flags {
+        let inner = self.0.get();
+        // SAFETY: safe as per the invariants of `Resource`
+        let flags = unsafe { *inner }.flags;
+
+        Flags(flags)
+    }
+}
+
+// SAFETY: `Resource` only holds a pointer to a C `struct resource`, which is
+// safe to be used from any thread.
+unsafe impl Send for Resource {}
+
+// SAFETY: `Resource` only holds a pointer to a C `struct resource`, references
+// to which are safe to be used from any thread.
+unsafe impl Sync for Resource {}
+
+/// Resource flags as stored in the C `struct resource::flags` field.
+///
+/// They can be combined with the operators `|`, `&`, and `!`.
+///
+/// Values can be used from the [`flags`] module.
+#[derive(Clone, Copy, PartialEq)]
+pub struct Flags(usize);
+
+impl Flags {
+    /// Check whether `flags` is contained in `self`.
+    pub fn contains(self, flags: Flags) -> bool {
+        (self & flags) == flags
+    }
+}
+
+impl core::ops::BitOr for Flags {
+    type Output = Self;
+    fn bitor(self, rhs: Self) -> Self::Output {
+        Self(self.0 | rhs.0)
+    }
+}
+
+impl core::ops::BitAnd for Flags {
+    type Output = Self;
+    fn bitand(self, rhs: Self) -> Self::Output {
+        Self(self.0 & rhs.0)
+    }
+}
+
+impl core::ops::Not for Flags {
+    type Output = Self;
+    fn not(self) -> Self::Output {
+        Self(!self.0)
+    }
+}
+
+/// Resource flags as stored in the `struct resource::flags` field.
+pub mod flags {
+    use super::Flags;
+
+    /// PCI/ISA I/O ports.
+    pub const IORESOURCE_IO: Flags = Flags(bindings::IORESOURCE_IO as usize);
+
+    /// Resource is software muxed.
+    pub const IORESOURCE_MUXED: Flags = Flags(bindings::IORESOURCE_MUXED as usize);
+
+    /// Resource represents a memory region.
+    pub const IORESOURCE_MEM: Flags = Flags(bindings::IORESOURCE_MEM as usize);
+
+    /// Resource represents a memory region that must be ioremaped using `ioremap_np`.
+    pub const IORESOURCE_MEM_NONPOSTED: Flags = Flags(bindings::IORESOURCE_MEM_NONPOSTED as usize);
+}

-- 
2.50.0

On Fri, Jul 04, 2025 at 01:25:26PM -0300, Daniel Almeida wrote:
> In preparation for ioremap support, add a Rust abstraction for struct
> resource.
> 
> A future commit will introduce the Rust API to ioremap a resource from a
> platform device. The current abstraction, therefore, adds only the
> minimum API needed to get that done.
> 
> Co-developed-by: Fiona Behrens <me@kloenk.dev>
> Signed-off-by: Fiona Behrens <me@kloenk.dev>
> Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>

Overall looks reasonable, but some comments below:

>  rust/bindings/bindings_helper.h |   1 +
>  rust/helpers/io.c               |  36 +++++++
>  rust/kernel/io.rs               |   4 +
>  rust/kernel/io/resource.rs      | 209 ++++++++++++++++++++++++++++++++++++++++
>  4 files changed, 250 insertions(+)
> 
> diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
> index 7e8f2285064797d5bbac5583990ff823b76c6bdc..5f795e60e889b9fc887013743c81b1cf92a52adb 100644
> --- a/rust/bindings/bindings_helper.h
> +++ b/rust/bindings/bindings_helper.h
> @@ -53,6 +53,7 @@
>  #include <linux/file.h>
>  #include <linux/firmware.h>
>  #include <linux/fs.h>
> +#include <linux/ioport.h>
>  #include <linux/jiffies.h>
>  #include <linux/jump_label.h>
>  #include <linux/mdio.h>
> diff --git a/rust/helpers/io.c b/rust/helpers/io.c
> index 15ea187c5466256effd07efe6f6995a1dd95a967..404776cf6717c8570c7600a24712ce6e4623d3c6 100644
> --- a/rust/helpers/io.c
> +++ b/rust/helpers/io.c
> @@ -1,6 +1,7 @@
>  // SPDX-License-Identifier: GPL-2.0
>  
>  #include <linux/io.h>
> +#include <linux/ioport.h>
>  
>  void __iomem *rust_helper_ioremap(phys_addr_t offset, size_t size)
>  {
> @@ -99,3 +100,38 @@ void rust_helper_writeq_relaxed(u64 value, void __iomem *addr)
>  	writeq_relaxed(value, addr);
>  }
>  #endif
> +
> +resource_size_t rust_helper_resource_size(struct resource *res)
> +{
> +	return resource_size(res);
> +}
> +
> +struct resource *rust_helper_request_mem_region(resource_size_t start,
> +						resource_size_t n,
> +						const char *name)
> +{
> +	return request_mem_region(start, n, name);
> +}
> +
> +void rust_helper_release_mem_region(resource_size_t start, resource_size_t n)
> +{
> +	release_mem_region(start, n);
> +}
> +
> +struct resource *rust_helper_request_region(resource_size_t start,
> +					    resource_size_t n, const char *name)
> +{
> +	return request_region(start, n, name);
> +}
> +
> +struct resource *rust_helper_request_muxed_region(resource_size_t start,
> +						  resource_size_t n,
> +						  const char *name)
> +{
> +	return request_muxed_region(start, n, name);
> +}
> +
> +void rust_helper_release_region(resource_size_t start, resource_size_t n)
> +{
> +	release_region(start, n);
> +}
> diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
> index 72d80a6f131e3e826ecd9d2c3bcf54e89aa60cc3..7b70d5b5477e57d6d0f24bcd26bd8b0071721bc0 100644
> --- a/rust/kernel/io.rs
> +++ b/rust/kernel/io.rs
> @@ -7,6 +7,10 @@
>  use crate::error::{code::EINVAL, Result};
>  use crate::{bindings, build_assert};
>  
> +pub mod resource;
> +
> +pub use resource::Resource;
> +
>  /// Raw representation of an MMIO region.
>  ///
>  /// By itself, the existence of an instance of this structure does not provide any guarantees that
> diff --git a/rust/kernel/io/resource.rs b/rust/kernel/io/resource.rs
> new file mode 100644
> index 0000000000000000000000000000000000000000..a8ad04b1abf8e46928ed98564e64a07180250024
> --- /dev/null
> +++ b/rust/kernel/io/resource.rs
> @@ -0,0 +1,209 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Abstractions for [system
> +//! resources](https://docs.kernel.org/core-api/kernel-api.html#resources-management).
> +//!
> +//! C header: [`include/linux/ioport.h`](srctree/include/linux/ioport.h)
> +
> +use core::ops::Deref;
> +use core::ptr::NonNull;
> +
> +use crate::str::CStr;
> +use crate::types::Opaque;
> +
> +/// Resource Size type.
> +///
> +/// This is a type alias to either `u32` or `u64` depending on the config option
> +/// `CONFIG_PHYS_ADDR_T_64BIT`.
> +#[cfg(CONFIG_PHYS_ADDR_T_64BIT)]
> +pub type ResourceSize = u64;
> +
> +/// Resource Size type.
> +///
> +/// This is a type alias to either `u32` or `u64` depending on the config option
> +/// `CONFIG_PHYS_ADDR_T_64BIT`.
> +#[cfg(not(CONFIG_PHYS_ADDR_T_64BIT))]
> +pub type ResourceSize = u32;
> +
> +/// A region allocated from a parent [`Resource`].
> +///
> +/// # Invariants
> +///
> +/// - `self.0` points to a valid `bindings::resource` that was obtained through
> +///   `bindings::__request_region`.
> +pub struct Region(NonNull<bindings::resource>);
> +
> +impl Deref for Region {
> +    type Target = Resource;
> +
> +    fn deref(&self) -> &Self::Target {
> +        // SAFETY: Safe as per the invariant of `Region`.
> +        unsafe { Resource::as_ref(self.0.as_ptr()) }
> +    }
> +}
> +
> +impl Drop for Region {
> +    fn drop(&mut self) {
> +        // SAFETY: Safe as per the invariant of `Region`.
> +        let res = unsafe { Resource::as_ref(self.0.as_ptr()) };
> +        let flags = res.flags();
> +
> +        let release_fn = if flags.contains(flags::IORESOURCE_MEM) {
> +            bindings::release_mem_region
> +        } else {
> +            bindings::release_region
> +        };

You can avoid this unsafe via the deref() impl.

let (flags, start, size) = {
    let res = &**self;
    (res.flags(), res.start(), res.size())
};

> +        // SAFETY: Safe as per the invariant of `Region`.
> +        unsafe { release_fn(res.start(), res.size()) };
> +    }
> +}
> +
> +// SAFETY: `Region` only holds a pointer to a C `struct resource`, which is safe to be used from
> +// any thread.
> +unsafe impl Send for Region {}
> +
> +// SAFETY: `Region` only holds a pointer to a C `struct resource`, references to which are
> +// safe to be used from any thread.
> +unsafe impl Sync for Region {}
> +
> +/// A resource abstraction.
> +///
> +/// # Invariants
> +///
> +/// [`Resource`] is a transparent wrapper around a valid `bindings::resource`.
> +#[repr(transparent)]
> +pub struct Resource(Opaque<bindings::resource>);
> +
> +impl Resource {
> +    /// Creates a reference to a [`Resource`] from a valid pointer.
> +    ///
> +    /// # Safety
> +    ///
> +    /// The caller must ensure that for the duration of 'a, the pointer will
> +    /// point at a valid `bindings::resource`.
> +    ///
> +    /// The caller must also ensure that the [`Resource`] is only accessed via the
> +    /// returned reference for the duration of 'a.
> +    pub(crate) const unsafe fn as_ref<'a>(ptr: *mut bindings::resource) -> &'a Self {

We usually call this method `from_raw`.

> +        // SAFETY: Self is a transparent wrapper around `Opaque<bindings::resource>`.
> +        unsafe { &*ptr.cast() }
> +    }
> +
> +    /// Requests a resource region.
> +    ///
> +    /// Exclusive access will be given and the region will be marked as busy.
> +    /// Further calls to [`Self::request_region`] will return [`None`] if
> +    /// the region, or a part of it, is already in use.
> +    pub fn request_region(
> +        &self,
> +        start: ResourceSize,
> +        size: ResourceSize,
> +        name: &'static CStr,

Is this name used for a lookup or stored? If just a lookup, then it
doesn't need to be 'static.

> +        flags: Flags,
> +    ) -> Option<Region> {
> +        // SAFETY: Safe as per the invariant of `Resource`.
> +        let region = unsafe {
> +            bindings::__request_region(
> +                self.0.get(),
> +                start,
> +                size,
> +                name.as_char_ptr(),
> +                flags.0 as i32,

I would use `as c_int` here. (Or change the type stored in Flags.)

> +            )
> +        };
> +
> +        Some(Region(NonNull::new(region)?))
> +    }
> +
> +    /// Returns the size of the resource.
> +    pub fn size(&self) -> ResourceSize {
> +        let inner = self.0.get();
> +        // SAFETY: safe as per the invariants of `Resource`.
> +        unsafe { bindings::resource_size(inner) }
> +    }
> +
> +    /// Returns the start address of the resource.
> +    pub fn start(&self) -> u64 {
> +        let inner = self.0.get();
> +        // SAFETY: safe as per the invariants of `Resource`.
> +        unsafe { *inner }.start

This needs to be

unsafe { (*inner).start }

What you wrote is not equivalent. (*inner) is a place expression, but
when you write `unsafe { <place expr> }` that turns it into a value
expression by reading the value. So this code copies the entire struct
to the stack, and then you read `start` from the copy on the stack.

> +    }
> +
> +    /// Returns the name of the resource.
> +    pub fn name(&self) -> &'static CStr {
> +        let inner = self.0.get();
> +        // SAFETY: safe as per the invariants of `Resource`
> +        unsafe { CStr::from_char_ptr((*inner).name) }
> +    }
> +
> +    /// Returns the flags associated with the resource.
> +    pub fn flags(&self) -> Flags {
> +        let inner = self.0.get();
> +        // SAFETY: safe as per the invariants of `Resource`
> +        let flags = unsafe { *inner }.flags;
> +
> +        Flags(flags)
> +    }
> +}
> +
> +// SAFETY: `Resource` only holds a pointer to a C `struct resource`, which is
> +// safe to be used from any thread.
> +unsafe impl Send for Resource {}
> +
> +// SAFETY: `Resource` only holds a pointer to a C `struct resource`, references
> +// to which are safe to be used from any thread.
> +unsafe impl Sync for Resource {}
> +
> +/// Resource flags as stored in the C `struct resource::flags` field.
> +///
> +/// They can be combined with the operators `|`, `&`, and `!`.
> +///
> +/// Values can be used from the [`flags`] module.
> +#[derive(Clone, Copy, PartialEq)]
> +pub struct Flags(usize);

Based on usage it looks like the correct type is c_int?

> +impl Flags {
> +    /// Check whether `flags` is contained in `self`.
> +    pub fn contains(self, flags: Flags) -> bool {
> +        (self & flags) == flags
> +    }
> +}
> +
> +impl core::ops::BitOr for Flags {
> +    type Output = Self;
> +    fn bitor(self, rhs: Self) -> Self::Output {
> +        Self(self.0 | rhs.0)
> +    }
> +}
> +
> +impl core::ops::BitAnd for Flags {
> +    type Output = Self;
> +    fn bitand(self, rhs: Self) -> Self::Output {
> +        Self(self.0 & rhs.0)
> +    }
> +}
> +
> +impl core::ops::Not for Flags {
> +    type Output = Self;
> +    fn not(self) -> Self::Output {
> +        Self(!self.0)
> +    }
> +}
> +
> +/// Resource flags as stored in the `struct resource::flags` field.
> +pub mod flags {

You can do:

impl Flags {
    pub const IORESOURCE_IO: Flags = Flags(bindings::IORESOURCE_IO as usize);
}

instead of a module.

> +    use super::Flags;
> +
> +    /// PCI/ISA I/O ports.
> +    pub const IORESOURCE_IO: Flags = Flags(bindings::IORESOURCE_IO as usize);
> +
> +    /// Resource is software muxed.
> +    pub const IORESOURCE_MUXED: Flags = Flags(bindings::IORESOURCE_MUXED as usize);
> +
> +    /// Resource represents a memory region.
> +    pub const IORESOURCE_MEM: Flags = Flags(bindings::IORESOURCE_MEM as usize);
> +
> +    /// Resource represents a memory region that must be ioremaped using `ioremap_np`.
> +    pub const IORESOURCE_MEM_NONPOSTED: Flags = Flags(bindings::IORESOURCE_MEM_NONPOSTED as usize);
> +}
> 
> -- 
> 2.50.0
>

[…]

> 
>> +    }
>> +
>> +    /// Returns the name of the resource.
>> +    pub fn name(&self) -> &'static CStr {
>> +        let inner = self.0.get();
>> +        // SAFETY: safe as per the invariants of `Resource`
>> +        unsafe { CStr::from_char_ptr((*inner).name) }
>> +    }
>> +
>> +    /// Returns the flags associated with the resource.
>> +    pub fn flags(&self) -> Flags {
>> +        let inner = self.0.get();
>> +        // SAFETY: safe as per the invariants of `Resource`
>> +        let flags = unsafe { *inner }.flags;
>> +
>> +        Flags(flags)
>> +    }
>> +}
>> +
>> +// SAFETY: `Resource` only holds a pointer to a C `struct resource`, which is
>> +// safe to be used from any thread.
>> +unsafe impl Send for Resource {}
>> +
>> +// SAFETY: `Resource` only holds a pointer to a C `struct resource`, references
>> +// to which are safe to be used from any thread.
>> +unsafe impl Sync for Resource {}
>> +
>> +/// Resource flags as stored in the C `struct resource::flags` field.
>> +///
>> +/// They can be combined with the operators `|`, `&`, and `!`.
>> +///
>> +/// Values can be used from the [`flags`] module.
>> +#[derive(Clone, Copy, PartialEq)]
>> +pub struct Flags(usize);
> 
> Based on usage it looks like the correct type is c_int?

Shouldn’t this be c_ulong because of:

#[repr(C)]
#[derive(Copy, Clone)]
pub struct resource {
    pub start: resource_size_t,
    pub end: resource_size_t,
    pub name: *const ffi::c_char,
    pub flags: ffi::c_ulong, <——

In any case, we will have to cast this because __request_region
expects c_int.

— Daniel

On Thu, Jul 10, 2025 at 3:34 PM Daniel Almeida
<daniel.almeida@collabora.com> wrote:
>
> […]
>
> >
> >> +    }
> >> +
> >> +    /// Returns the name of the resource.
> >> +    pub fn name(&self) -> &'static CStr {
> >> +        let inner = self.0.get();
> >> +        // SAFETY: safe as per the invariants of `Resource`
> >> +        unsafe { CStr::from_char_ptr((*inner).name) }
> >> +    }
> >> +
> >> +    /// Returns the flags associated with the resource.
> >> +    pub fn flags(&self) -> Flags {
> >> +        let inner = self.0.get();
> >> +        // SAFETY: safe as per the invariants of `Resource`
> >> +        let flags = unsafe { *inner }.flags;
> >> +
> >> +        Flags(flags)
> >> +    }
> >> +}
> >> +
> >> +// SAFETY: `Resource` only holds a pointer to a C `struct resource`, which is
> >> +// safe to be used from any thread.
> >> +unsafe impl Send for Resource {}
> >> +
> >> +// SAFETY: `Resource` only holds a pointer to a C `struct resource`, references
> >> +// to which are safe to be used from any thread.
> >> +unsafe impl Sync for Resource {}
> >> +
> >> +/// Resource flags as stored in the C `struct resource::flags` field.
> >> +///
> >> +/// They can be combined with the operators `|`, `&`, and `!`.
> >> +///
> >> +/// Values can be used from the [`flags`] module.
> >> +#[derive(Clone, Copy, PartialEq)]
> >> +pub struct Flags(usize);
> >
> > Based on usage it looks like the correct type is c_int?
>
> Shouldn’t this be c_ulong because of:
>
> #[repr(C)]
> #[derive(Copy, Clone)]
> pub struct resource {
>     pub start: resource_size_t,
>     pub end: resource_size_t,
>     pub name: *const ffi::c_char,
>     pub flags: ffi::c_ulong, <——
>
> In any case, we will have to cast this because __request_region
> expects c_int.

I saw that you called a C function that expects an int, so that's why
I suggested c_int. It sounds like the cast from int to long happens in
C code.

Alice

Hi Alice,

> Is this name used for a lookup or stored? If just a lookup, then it
> doesn't need to be 'static.
> 
>> +        flags: Flags,
>> +    ) -> Option<Region> {
>> +        // SAFETY: Safe as per the invariant of `Resource`.
>> +        let region = unsafe {
>> +            bindings::__request_region(
>> +                self.0.get(),
>> +                start,
>> +                size,
>> +                name.as_char_ptr(),
>> +                flags.0 as i32,
> 

JFYI, this is stored:

static int __request_region_locked(struct resource *res, struct resource *parent,
				   resource_size_t start, resource_size_t n,
				   const char *name, int flags)
{
	DECLARE_WAITQUEUE(wait, current);

	res->name = name;


— Daniel

On Thu, Jul 10, 2025 at 3:16 PM Daniel Almeida
<daniel.almeida@collabora.com> wrote:
>
> Hi Alice,
>
> > Is this name used for a lookup or stored? If just a lookup, then it
> > doesn't need to be 'static.
> >
> >> +        flags: Flags,
> >> +    ) -> Option<Region> {
> >> +        // SAFETY: Safe as per the invariant of `Resource`.
> >> +        let region = unsafe {
> >> +            bindings::__request_region(
> >> +                self.0.get(),
> >> +                start,
> >> +                size,
> >> +                name.as_char_ptr(),
> >> +                flags.0 as i32,
> >
>
> JFYI, this is stored:
>
> static int __request_region_locked(struct resource *res, struct resource *parent,
>                                    resource_size_t start, resource_size_t n,
>                                    const char *name, int flags)
> {
>         DECLARE_WAITQUEUE(wait, current);
>
>         res->name = name;

I think it would be useful for the safety comment to say something
along the lines of "it's okay that __request_region stashes a copy of
the string because it is static".

Alice

Hi Alice,

[…]


>> +
>> +impl Resource {
>> +    /// Creates a reference to a [`Resource`] from a valid pointer.
>> +    ///
>> +    /// # Safety
>> +    ///
>> +    /// The caller must ensure that for the duration of 'a, the pointer will
>> +    /// point at a valid `bindings::resource`.
>> +    ///
>> +    /// The caller must also ensure that the [`Resource`] is only accessed via the
>> +    /// returned reference for the duration of 'a.
>> +    pub(crate) const unsafe fn as_ref<'a>(ptr: *mut bindings::resource) -> &'a Self {
> 
> We usually call this method `from_raw`.

Hmm, pretty sure I have seen the exact opposite being asked. In fact, this was
discussed a bit at length a while ago. See the thread starting at [0] for context.

> 
>> +            )
>> +        };
>> +
>> +        Some(Region(NonNull::new(region)?))
>> +    }
>> +
>> +    /// Returns the size of the resource.
>> +    pub fn size(&self) -> ResourceSize {
>> +        let inner = self.0.get();
>> +        // SAFETY: safe as per the invariants of `Resource`.
>> +        unsafe { bindings::resource_size(inner) }
>> +    }
>> +
>> +    /// Returns the start address of the resource.
>> +    pub fn start(&self) -> u64 {
>> +        let inner = self.0.get();
>> +        // SAFETY: safe as per the invariants of `Resource`.
>> +        unsafe { *inner }.start
> 
> This needs to be
> 
> unsafe { (*inner).start }
> 
> What you wrote is not equivalent. (*inner) is a place expression, but
> when you write `unsafe { <place expr> }` that turns it into a value
> expression by reading the value. So this code copies the entire struct
> to the stack, and then you read `start` from the copy on the stack.

To be honest, I've seen a bug where the opposite was going on, a field was
being written on the value that was copied to the stack, leaving the original unchanged.

In any case, I thought this would be optimized away by the compiler. Also, IMHO
there should be a lint for this, because it does not make sense to copy a struct
just to read a field if we can just read the original location.

Thanks for catching that though, I will fix it on the next iteration :)

[…]

Thanks for the other comments,

— Daniel

[0] https://lore.kernel.org/rust-for-linux/B3564D77-9E26-4019-9B75-B0C53B26B64F@collabora.com/

On Tue, Jul 08, 2025 at 02:43:33PM -0300, Daniel Almeida wrote:
> > What you wrote is not equivalent. (*inner) is a place expression, but
> > when you write `unsafe { <place expr> }` that turns it into a value
> > expression by reading the value. So this code copies the entire struct
> > to the stack, and then you read `start` from the copy on the stack.
> 
> To be honest, I've seen a bug where the opposite was going on, a field was
> being written on the value that was copied to the stack, leaving the original unchanged.
> 
> In any case, I thought this would be optimized away by the compiler. Also, IMHO
> there should be a lint for this, because it does not make sense to copy a struct
> just to read a field if we can just read the original location.
> 
> Thanks for catching that though, I will fix it on the next iteration :)

Yes, it is probably optimized out. However, the main problem is that
when you read the entire struct, that could be a data race of another
field which may be UB.

Alice

On Tue, Jul 8, 2025 at 7:44 PM Daniel Almeida
<daniel.almeida@collabora.com> wrote:
>
> Hi Alice,
>
> […]
>
>
> >> +
> >> +impl Resource {
> >> +    /// Creates a reference to a [`Resource`] from a valid pointer.
> >> +    ///
> >> +    /// # Safety
> >> +    ///
> >> +    /// The caller must ensure that for the duration of 'a, the pointer will
> >> +    /// point at a valid `bindings::resource`.
> >> +    ///
> >> +    /// The caller must also ensure that the [`Resource`] is only accessed via the
> >> +    /// returned reference for the duration of 'a.
> >> +    pub(crate) const unsafe fn as_ref<'a>(ptr: *mut bindings::resource) -> &'a Self {
> >
> > We usually call this method `from_raw`.
>
> Hmm, pretty sure I have seen the exact opposite being asked. In fact, this was
> discussed a bit at length a while ago. See the thread starting at [0] for context.

I will submit a patch.

Alicej

On Fri, Jul 04, 2025 at 01:25:26PM -0300, Daniel Almeida wrote:
> +/// Resource Size type.
> +///
> +/// This is a type alias to either `u32` or `u64` depending on the config option
> +/// `CONFIG_PHYS_ADDR_T_64BIT`.
> +#[cfg(CONFIG_PHYS_ADDR_T_64BIT)]
> +pub type ResourceSize = u64;
> +
> +/// Resource Size type.
> +///
> +/// This is a type alias to either `u32` or `u64` depending on the config option
> +/// `CONFIG_PHYS_ADDR_T_64BIT`.
> +#[cfg(not(CONFIG_PHYS_ADDR_T_64BIT))]
> +pub type ResourceSize = u32;

I think someone commented on this previously, but maybe I also do not remember
correctly.

Anyways, can't we just do:

	pub type ResourceSize = bindings::phys_addr_t;

Given that phys_addr_t is already either u32 or u64.

On Sat, Jul 05, 2025 at 07:28:07PM +0200, Danilo Krummrich wrote:
> On Fri, Jul 04, 2025 at 01:25:26PM -0300, Daniel Almeida wrote:
> > +/// Resource Size type.
> > +///
> > +/// This is a type alias to either `u32` or `u64` depending on the config option
> > +/// `CONFIG_PHYS_ADDR_T_64BIT`.
> > +#[cfg(CONFIG_PHYS_ADDR_T_64BIT)]
> > +pub type ResourceSize = u64;
> > +
> > +/// Resource Size type.
> > +///
> > +/// This is a type alias to either `u32` or `u64` depending on the config option
> > +/// `CONFIG_PHYS_ADDR_T_64BIT`.
> > +#[cfg(not(CONFIG_PHYS_ADDR_T_64BIT))]
> > +pub type ResourceSize = u32;
> 
> I think someone commented on this previously, but maybe I also do not remember
> correctly.
> 
> Anyways, can't we just do:
> 
> 	pub type ResourceSize = bindings::phys_addr_t;
> 
> Given that phys_addr_t is already either u32 or u64.

In addition, it would be nice for the documentation to mention that it
can be 64-bit even on a 32-bit machine.

Alice