rust: platform: add Io support
Subsystems (3)
Daniel Almeida
maintainerv15 cover rust: platform: add Io support
Changes in v15:
- Use a default string in ioremap() if the resource doesn't have a name
- Fix the doctests in mem.rs to use the new name for io_request_by_*
- Link to v14: https://lore.kernel.org/r/20250716-topics-tyr-platform_iomem-v14-0-2c2709135cb2@collabora.com
Changes in v14:
- Changed Resource::size() to return ResourceSize instead of u64 (Alice)
- Changed Resource::name() to return a non-static lifetime (i.e.: the
lifetime of &self). It turns out that although this value tends to often
point to string literals, this value is not necessarily static in C.
(Thanks for bringing this up, Alice)
- "name" is now owned by the Region. We were storing Resource::name()
previously as that was 'static, but that is not the case anymore. The
string is now copied from Resource::name() instead. If there is no name,
we fail.
- Changed Resource::name() to return an Option, as the name may be NULL in
C (see the DEFINE_RES_* family of macros in C)
- Added a TODO to the "size" cast in IoMem::ioremap(), noting that we
should fix this in C in the future (Thanks, Alice)
- Casting "size" in IoMem::ioremap() only once now (thanks, Alice)
- Introduced Flags::new(), which derives from a comment in the request_irq
series. This introduces a build_assert to reduce the number of casts.
- Added Alice's r-b to patches 1-2
- Added Miguel's a-b to patches 1-3 (Given in v11 and forgotten)
- Link to v13: https://lore.kernel.org/r/20250711-topics-tyr-platform_iomem-v13-0-06328b514db3@collabora.com
Changes in v13:
- Change ResourceSize to just be bindings::phys_addr_t (Danilo)
- Mention that ResourceSize can be 32bits even on 64bit architectures (Alice)
- Use the deref impl for Resource to avoid unsafe (Alice)
- Change Resource::as_ref() to Resource::from_raw() (Alice)
- Mention that it's ok for __request_region to store the name as we require
it to be 'static
- Remove all instances of core::ffi::* as these are in the prelude already
(Alice)
- Resource::start() and Resoruce::flags() do not copy &self anymore (Alice)
- Define the resource::Flags constants within impl Flags itself (Alice)
- Apply the diff from Danilo to return impl PinInit<...> instead of
Result<impl PinInin<...>> from the iomap() functions.
- Fix the docs in patch 2 (Alice)
- Use try_into() instead of blindly casting ResourceSize to usize (Alice)
- Rename request_io_by{index,name} to io_request_by{index,name} (Danilo)
- Link to v12: https://lore.kernel.org/rust-for-linux/20250704-topics-tyr-platform_iomem-v12-0-1d3d4bd8207d@collabora.com/
Changes in v12:
- Fixed the typos that Miguel pointed out in resource.rs
- Fixed a typo where thread was written as thead
- Removed ioport_resource() and iomem_resource() (Danilo)
- Created IoRequest<'a> and gave it an unsafe constructor (Danilo)
- Moved all the logic to map resources from platform.rs to IoRequest.
- Dropped the last patch as a result of the above.
- Link to v11: https://lore.kernel.org/r/20250701-topics-tyr-platform_iomem-v11-0-6cd5d5061151@collabora.com
Changes in v11:
- Rebased on top of driver-core-next (to get the latest Devres changes)
- Changed the order between requesting the resource and mapping it
(Danilo)
- Link to v10: https://lore.kernel.org/r/20250623-topics-tyr-platform_iomem-v10-0-ed860a562940@collabora.com
Changes in v10:
- Rebased on driver-core-next
- Fixed examples (they were still using try_access())
- Removed map_err() from the examples, as it was not needed.
- Added a pub use for Resource in io.rs
- Reworked the platform code to make use of the pub use above
- Link to v9: https://lore.kernel.org/r/20250603-topics-tyr-platform_iomem-v9-0-a27e04157e3e@collabora.com
Changes in v9:
- Rebased on top of nova-next (for Devres::access())
- Reworked the documentation to add more markdown.
- Converted to &raw mut instead of addr_of_mut!()
- Renamed 'from_ptr' to 'as_ref' for consistency
- Changed the IoMem examples to use the signature for probe()
- Changed resource() to resource_by_index(). It's a better fit given
the existance of resource_by_name().
- Created a separate patch for the resource accessors above.
- Moved the accessors into the generic impl block, so they work with all
Device contexts.
- Take Device<Bound> where applicable
- Renamed "ioremap_*" to "iomap_*", in order to be consistent with the code
in pci.rs
- Switched to Devres::access()
- Link to v8: https://lore.kernel.org/r/20250509-topics-tyr-platform_iomem-v8-0-e9f1725a40da@collabora.com
rust: platform: add Io support
Changes in v8:
- Rebased on driver-core-next
- Opted to wait for 'rust/revocable: add try_with() convenience method' to
land instead of using the suggested closure (let me know if we should
just switch to the closure anyways)
- Cc'd more people
- Link to v7: https://lore.kernel.org/r/20250318-topics-tyr-platform_iomem-v7-0-7438691d9ef7@collabora.com
Changes in v7:
- Rebased on top of rust-next
- Fixed a few Clippy lints
- Fixed typos (Thanks Daniel!)
- "struct Flags" now contains a usize (thanks Daniel)
- Fixed "Doc list without indentation" warning (thanks, Guangbo)
Thanks, Fiona {
- Removed RequestFn, as all functions simply used request_region and RequestFn had issues. Only request_region() is exposed now.
- Gated iomem_resource on CONFIG_HAS_IOMEM
- Require that the name argument be 'static
}
- Correctly check for IORESOURCE_MEM_NONPOSTED. We now call ioremap_np if that is set (thanks, Lina!)
- Remove #[dead_code] attribute from ExclusiveIoMem::region.
Changes in v6:
- Added Fiona as co-developer in the first patch, as I merged part of her code from the LED driver series (thanks, Fiona)
- (Fiona) added the ResourceSize type, thereby fixing the u32 vs u64 issues pointed out by Christian
- Moved the request_region, release_region and friends to resource.rs
- Added the Region type. This type represents a resource returned by request_region and friends. It is also owned, representing the fact that the region remains marked as busy until release_region is called on drop. (Thanks Alice, for pointing out this pattern)
- Rewrote the IoMem abstraction to implement a separate type for exclusive access to an underlying region. I really disliked the EXCLUSIVE const generic, as it was definitely not ergonomic, i.e.:
IoMem<0, false>
...doesn't really say much. In fact, I believe that boolean parameters hurt readability in general.
This new approach lets users build either regular IoMem's, which basically call ioremap under the covers, and ExclusiveIoMem's , which also call request_region via the Region type.
- Added access to the ioresource_port and ioresource_mem globals.
Link to v5: https://lore.kernel.org/rust-for-linux/[email protected]/
Changes in v5:
- resend v5, as the r4l list was not cc'd
- use srctree where applicable in the docs (Alice)
- Remove 'mut' in Resource::from_ptr() (Alice)
- Add 'invariants' section for Resource (Alice)
- Fix typos in mem.rs (Alice)
- Turn 'exclusive' into a const generic (Alice)
- Fix example in platform.rs (Alice)
- Rework the resource.is_null() check (Alice)
- Refactor IoMem::new() to return DevRes<IoMem> directly (Danilo)
link to v4: https://lore.kernel.org/rust-for-linux/[email protected]/
Changes in v4:
- Rebased on top of driver-core-next
- Split series in multiple patches (Danilo)
- Move IoMem and Resource into its own files (Danilo)
- Fix a missing "if exclusive {...}" check (Danilo)
- Fixed the example, since it was using the old API (Danilo)
- Use Opaque in Resource, instead of NonNull and PhantomData (Boqun)
- Highlight that non-exclusive access to the iomem might be required in some cases
- Fixed the safety comment in IoMem::deref()
Changes in v3:
- Rebased on top of v5 for the PCI/Platform abstractions
- platform_get_resource is now called only once when calling ioremap
- Introduced a platform::Resource type, which is bound to the lifetime of the platform Device
- Allow retrieving resources from the platform device either by index or name
- Make request_mem_region() optional
- Use resource.name() in request_mem_region
- Reword the example to remove an unaligned, out-of-bounds offset
- Update the safety requirements of platform::IoMem
Changes in v2:
- reworked the commit message
- added missing request_mem_region call (Thanks Alice, Danilo)
- IoMem::new() now takes the platform::Device, the resource number and the name, instead of an address and a size (thanks, Danilo)
- Added a new example for both sized and unsized versions of IoMem.
- Compiled the examples using kunit.py (thanks for the tip, Alice!)
- Removed instances of foo as _. All as casts now spell out the actual type.
- Now compiling with CLIPPY=1 (I realized I had forgotten, sorry)
- Rebased on top of rust-next to check for any warnings given the new unsafe lints.
---
Daniel Almeida (3):
rust: io: add resource abstraction
rust: io: mem: add a generic iomem abstraction
rust: platform: add resource accessors
rust/bindings/bindings_helper.h | 1 + rust/helpers/io.c | 41 ++++++ rust/kernel/io.rs | 5 + rust/kernel/io/mem.rs | 283 ++++++++++++++++++++++++++++++++++++++++ rust/kernel/io/resource.rs | 229 ++++++++++++++++++++++++++++++++ rust/kernel/platform.rs | 60 ++++++++- 6 files changed, 618 insertions(+), 1 deletion(-)
---
base-commit: f5d3ef25d238901a76fe0277787afa44f7714739
change-id: 20250318-topics-tyr-platform_iomem-1710a177e1df
Best regards,
Signature · 1 line
Daniel Almeida <[email protected]>
Daniel Almeida
maintainerPATCH v15 1/3 rust: io: add resource abstraction
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.
--- rust/bindings/bindings_helper.h | 1 + rust/helpers/io.c | 36 +++++++ rust/kernel/io.rs | 4 + rust/kernel/io/resource.rs | 229 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 270 insertions(+)
rust/bindings/bindings_helper.h +1 -0
@@ -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>
rust/helpers/io.c +36 -0
@@ -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); +}
rust/kernel/io.rs +4 -0
@@ -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
rust/kernel/io/resource.rs new file +229 -0
229 lines not on this page · raw message
Signature · 1 line
2.50.0
Daniel Almeida
maintainerPATCH v15 2/3 rust: io: mem: add a generic iomem abstraction
In reply to Daniel AlmeidaAdd a generic iomem abstraction to safely read and write ioremapped regions. This abstraction requires a previously acquired IoRequest instance. This makes it so that both the resource and the device match, or, in other words, that the resource is indeed a valid resource for a given bound device.
A subsequent patch will add the ability to retrieve IoRequest instances from platform devices.
The reads and writes are done through IoRaw, and are thus checked either at compile-time, if the size of the region is known at that point, or at runtime otherwise.
Non-exclusive access to the underlying memory region is made possible to cater to cases where overlapped regions are unavoidable.
--- rust/helpers/io.c | 5 + rust/kernel/io.rs | 1 + rust/kernel/io/mem.rs | 283 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 289 insertions(+)
rust/helpers/io.c +5 -0
@@ -8,6 +8,11 @@ void __iomem *rust_helper_ioremap(phys_addr_t offset, size_t size)return ioremap (offset, size); } +void __iomem *rust_helper_ioremap_np (phys_addr_t offset,size_t size) +{ +return ioremap_np (offset, size); +} +void rust_helper_iounmap (void __iomem *addr) {iounmap (addr);
rust/kernel/io.rs +1 -0
@@ -7,6 +7,7 @@use crate ::error::{code::EINVAL ,Result };use crate ::{bindings, build_assert}; +pub mod mem;pub mod resource;pub use resource::Resource ;
rust/kernel/io/mem.rs new file +283 -0
283 lines not on this page · raw message
Signature · 1 line
2.50.0
Danilo Krummrich
maintainerRe: [PATCH v15 2/3] rust: io: mem: add a generic iomem abstraction
rust/kernel/io/mem.rs line 225
Quoted 6 lines · Daniel Almeida
rust/kernel/io/mem.rs new file +6
-0+impl <const SIZE :usize >IoMem <SIZE > { +fn ioremap (resource: &Resource ) ->Result <Self > { +// Note: It looks like there aren't any 32-bit architectures that define +// ioremap_np. This means that sometimes this conversion will fail. If +// we performed a lossy cast, i.e., using `as`, then `bindings::ioremap` +// would return NULL anyway.
Why would ioremap() return NULL if you perform a lossy cast?
Anyways, I find it a bit difficult to decode the actual problem from the above description.
I feel it would be better to just explain that some ioremap() implementations use types that depend on the CPU word width rather than the bus address width.
If you agree, no need to resend though, we can change it when applying the series.
Quoted 5 lines
rust/kernel/io/mem.rs new file +5
-0+// TODO: Properly address this in the C code to avoid this `try_into`. +let size = resource.size ().try_into ()?; +if size ==0 { +return Err (EINVAL ); + }
Daniel Almeida
maintainerRe: [PATCH v15 2/3] rust: io: mem: add a generic iomem abstraction
Hi Danilo,
Quoted 12 lines · Danilo Krummrich
rust/kernel/io/mem.rs line 225
Quoted 6 lines · Daniel Almeida
rust/kernel/io/mem.rs new file +6
-0+impl <const SIZE :usize >IoMem <SIZE > { +fn ioremap (resource: &Resource ) ->Result <Self > { +// Note: It looks like there aren't any 32-bit architectures that define +// ioremap_np. This means that sometimes this conversion will fail. If +// we performed a lossy cast, i.e., using `as`, then `bindings::ioremap` +// would return NULL anyway. Why would
ioremap()return NULL if you perform a lossy cast?
Quoted 15 lines
Anyways, I find it a bit difficult to decode the actual problem from the above description.
I feel it would be better to just explain that some
ioremap()implementations use types that depend on the CPU word width rather than the bus address width.If you agree, no need to resend though, we can change it when applying the series.
Quoted 5 lines
rust/kernel/io/mem.rs new file +5
-0+// TODO: Properly address this in the C code to avoid this `try_into`. +let size = resource.size ().try_into ()?; +if size ==0 { +return Err (EINVAL ); + }
Ok, I do agree that what you said is better. Feel free to use it then.
— Daniel
Danilo Krummrich
maintainerRe: [PATCH v15 2/3] rust: io: mem: add a generic iomem abstraction
In reply to Daniel AlmeidaQuoted 36 lines · Daniel Almeida
rust/kernel/io/mem.rs new file +36
-0+/// Maps an [`IoRequest`] where the size is known at compile time. +/// +/// This uses the [`ioremap()`] C API. +/// +/// [`ioremap()`]: https://docs.kernel.org/driver-api/device-io.html#getting-access-to-the-device +/// +/// # Examples +/// +/// The following example uses a [`platform::Device`] for illustration +/// purposes. +/// +/// ```no_run +/// use kernel::{bindings, c_str, platform, of, device::Core}; +/// struct SampleDriver; +/// +/// impl platform::Driver for SampleDriver { +/// # type IdInfo = (); +/// # const OF_ID_TABLE: Option<of::IdTable<Self::IdInfo>> = None; +/// +/// fn probe( +/// pdev: &platform::Device<Core>, +/// info: Option<&Self::IdInfo>, +/// ) -> Result<Pin<KBox<Self>>> { +/// let offset = 0; // Some offset. +/// +/// // If the size is known at compile time, use [`Self::iomap_sized`]. +/// // +/// // No runtime checks will apply when reading and writing. +/// let request = pdev.io_request_by_index(0).ok_or(ENODEV)?; +/// let iomem = request.iomap_sized::<42>(); +/// let iomem = KBox::pin_init(iomem, GFP_KERNEL)?; +/// +/// let io = iomem.access(pdev.as_ref())?; +/// +/// // Read and write a 32-bit value at `offset`. +/// let data = io.read32_relaxed(offset);
rust/kernel/io/mem.rs line 80
Quoted 10 lines
rust/kernel/io/mem.rs new file +10
-0+/// +/// io.write32_relaxed(data, offset); +/// +/// # Ok(KBox::new(SampleDriver, GFP_KERNEL)?.into()) +/// } +/// } +/// ``` +pub fn iomap_sized <const SIZE :usize >(self) ->impl PinInit <Devres <IoMem <SIZE >>,Error > + 'a { +IoMem ::new (self) + }
This doc-test and the one below break the build, since the used platform device infrastructure is introduced with the next patch.
I can set them to ignore and we turn them into no_run with a subsequent patch.
Quoted 53 lines
rust/kernel/io/mem.rs new file +53
-0+/// Maps an [`IoRequest`] where the size is not known at compile time, +/// +/// This uses the [`ioremap()`] C API. +/// +/// [`ioremap()`]: https://docs.kernel.org/driver-api/device-io.html#getting-access-to-the-device +/// +/// # Examples +/// +/// The following example uses a [`platform::Device`] for illustration +/// purposes. +/// +/// ```no_run +/// use kernel::{bindings, c_str, platform, of, device::Core}; +/// struct SampleDriver; +/// +/// impl platform::Driver for SampleDriver { +/// # type IdInfo = (); +/// # const OF_ID_TABLE: Option<of::IdTable<Self::IdInfo>> = None; +/// +/// fn probe( +/// pdev: &platform::Device<Core>, +/// info: Option<&Self::IdInfo>, +/// ) -> Result<Pin<KBox<Self>>> { +/// let offset = 0; // Some offset. +/// +/// // Unlike [`Self::iomap_sized`], here the size of the memory region +/// // is not known at compile time, so only the `try_read*` and `try_write*` +/// // family of functions should be used, leading to runtime checks on every +/// // access. +/// let request = pdev.io_request_by_index(0).ok_or(ENODEV)?; +/// let iomem = request.iomap(); +/// let iomem = KBox::pin_init(iomem, GFP_KERNEL)?; +/// +/// let io = iomem.access(pdev.as_ref())?; +/// +/// let data = io.try_read32_relaxed(offset)?; +/// +/// io.try_write32_relaxed(data, offset)?; +/// +/// # Ok(KBox::new(SampleDriver, GFP_KERNEL)?.into()) +/// } +/// } +/// ``` +pub fn iomap (self) ->impl PinInit <Devres <IoMem <0 >>,Error > + 'a { +Self ::iomap_sized ::<0 >(self) + } + +/// Same as [`Self::iomap`] but with exclusive access to the underlying +/// region. +pub fn iomap_exclusive (self) ->impl PinInit <Devres <ExclusiveIoMem <0 >>,Error > + 'a { +Self ::iomap_exclusive_sized ::<0 >(self) + } +}
Danilo Krummrich
maintainerPATCH 1/1 rust: io: mem: enable IoRequest doc-tests
When introduced, the IoRequest doc-tests did depend on infrastructure added in subsequent patches, hence they temporarily had to be disabled.
Now that we have the corresponding platform device infrastructure, enable them.
--- rust/kernel/io/mem.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
rust/kernel/io/mem.rs +2 -2
@@ -43,7 +43,7 @@ pub unsafe fn new(device: &'a Device<Bound>, resource: &'a Resource) -> Self {/// The following example uses a [`platform::Device`] for illustration /// purposes. /// -/// ```ignore +/// ```no_run /// use kernel::{bindings, c_str, platform, of, device::Core}; /// struct SampleDriver; ///
@@ -101,7 +101,7 @@ pub fn iomap_exclusive_sized<const SIZE: usize>(/// The following example uses a [`platform::Device`] for illustration /// purposes. /// -/// ```ignore +/// ```no_run /// use kernel::{bindings, c_str, platform, of, device::Core}; /// struct SampleDriver; ///
Signature · 1 line
2.50.0
Danilo Krummrich
maintainerRe: [PATCH] rust: io: mem: enable IoRequest doc-tests
Quoted 7 lines · Danilo Krummrich
When introduced, the IoRequest doc-tests did depend on infrastructure added in subsequent patches, hence they temporarily had to be disabled.
Now that we have the corresponding platform device infrastructure, enable them.
Signed-off-by Danilo Krummrich <[email protected]>
Applied to driver-core-testing, thanks!
Daniel Almeida
maintainerPATCH v15 3/3 rust: platform: add resource accessors
In reply to Daniel AlmeidaThe previous patches have added the abstractions for Resources and the ability to map them and therefore read and write the underlying memory .
The only thing missing to make this accessible for platform devices is to provide accessors that return instances of IoRequest<'a>. These ensure that the resource are valid only for the lifetime of the platform device, and that the platform device is in the Bound state.
Therefore, add these accessors. Also make it possible to retrieve resources from platform devices in Rust using either a name or an index.
--- rust/kernel/platform.rs | 60 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-)
rust/kernel/platform.rs +59 -1
@@ -5,8 +5,11 @@//! C header: [`include/linux/platform_device.h`](srctree/include/linux/platform_device.h) use crate ::{ - acpi, bindings, container_of, device, driver, + acpi, bindings, container_of, + device::{self,Bound }, + driver, error::{to_result,Result }, + io::{mem::IoRequest ,Resource }, of, prelude::*, str::CStr ,
@@ -211,6 +214,61 @@ impl<Ctx: device::DeviceContext> Device<Ctx> {fn as_raw (&self) -> *mut bindings::platform_device { self.0 .get () } + +/// Returns the resource at `index`, if any. +pub fn resource_by_index (&self, index:u32 ) ->Option <&Resource > { +// SAFETY: `self.as_raw()` returns a valid pointer to a `struct platform_device`. +let resource =unsafe { + bindings::platform_get_resource (self.as_raw (), bindings::IORESOURCE_MEM , index) + }; + +if resource.is_null () { +return None ; + } + +// SAFETY: `resource` is a valid pointer to a `struct resource` as +// returned by `platform_get_resource`. +Some (unsafe {Resource ::from_raw (resource) }) + } + +/// Returns the resource with a given `name`, if any. +pub fn resource_by_name (&self, name: &CStr ) ->Option <&Resource > { +// SAFETY: `self.as_raw()` returns a valid pointer to a `struct +// platform_device` and `name` points to a valid C string. +let resource =unsafe { + bindings::platform_get_resource_byname ( + self.as_raw (), + bindings::IORESOURCE_MEM , + name.as_char_ptr (), + ) + }; + +if resource.is_null () { +return None ; + } + +// SAFETY: `resource` is a valid pointer to a `struct resource` as +// returned by `platform_get_resource`. +Some (unsafe {Resource ::from_raw (resource) }) + } +} + +impl Device <Bound > { +/// Returns an `IoRequest` for the resource at `index`, if any. +pub fn io_request_by_index (&self, index:u32 ) ->Option <IoRequest <'_>> { +// SAFETY: `resource` is a valid resource for `&self` during the +// lifetime of the `IoRequest`. + self.resource_by_index (index) + .map (|resource|unsafe {IoRequest ::new (self.as_ref (), resource) }) + } + +/// Returns an `IoRequest` for the resource with a given `name`, if any. +pub fn io_request_by_name (&self, name: &CStr ) ->Option <IoRequest <'_>> { +// SAFETY: `resource` is a valid resource for `&self` during the +// lifetime of the `IoRequest`. + self.resource_by_name (name) + .map (|resource|unsafe {IoRequest ::new (self.as_ref (), resource) }) + } }// SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
Signature · 1 line
2.50.0
Danilo Krummrich
maintainerRe: [PATCH v15 3/3] rust: platform: add resource accessors
rust/kernel/platform.rs impl<Ctx: device::DeviceContext> Device<Ctx> { · line 262
Quoted 7 lines · Daniel Almeida
rust/kernel/platform.rs +7
-0+impl Device <Bound > { +/// Returns an `IoRequest` for the resource at `index`, if any. +pub fn io_request_by_index (&self, index:u32 ) ->Option <IoRequest <'_>> { +// SAFETY: `resource` is a valid resource for `&self` during the +// lifetime of the `IoRequest`. + self.resource_by_index (index) + .map (|resource|unsafe {IoRequest ::new (self.as_ref (), resource) })
It seems there's a bug in some clippy versions we support. My regular testing shows a warning for this with clippy 1.78:
warning: unsafe block missing a safety comment
--> rust/kernel/platform.rs:275:29
|
275 | .map(|resource| unsafe { IoRequest::new(self.as_ref(), resource) })
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|However, there clearly is a safety comment.
It seems it gets confused by the multiline formatting. If I write this as
self.resource_by_index(index)
// SAFETY: `resource` is a valid resource for `&self` during the
// lifetime of the `IoRequest`.
.map(|resource| unsafe { IoRequest::new(self.as_ref(), resource) })the warning goes away.
@Miguel: What's the preferred way dealing with this? I assume we just want to ignore this warning for the affected compiler versions?
Quoted 10 lines
rust/kernel/platform.rs +9
-0+ } + +/// Returns an `IoRequest` for the resource with a given `name`, if any. +pub fn io_request_by_name (&self, name: &CStr ) ->Option <IoRequest <'_>> { +// SAFETY: `resource` is a valid resource for `&self` during the +// lifetime of the `IoRequest`. + self.resource_by_name (name) + .map (|resource|unsafe {IoRequest ::new (self.as_ref (), resource) }) + } }
Re: [PATCH v15 3/3] rust: platform: add resource accessors
Quoted 3 lines · Danilo Krummrich
@Miguel: What's the preferred way dealing with this? I assume we just want to ignore this warning for the affected compiler versions?
Yeah, we had this in the past -- when I introduced the lint, I just went with putting in the middle, e.g. in rust/kernel/sync/lock.rs's do_unlocked.
It has been fairly confusing, because long ago AFAIU it was not intended to be supported, but then they introduced a config option for it, and then it was made the default, but there were false positives.
It seems it has been finally fixed in
https://github.com/rust-lang/rust-clippy/pull/13888 for Rust 1.87.0.
I would say just put it in the middle. The only advantage of using an allow would be using the "reason" field to say we can move it >= 1.87, but if we really want to move it, we can always use a normal comment to say so instead.
Cheers,
Miguel
Re: [PATCH v15 3/3] rust: platform: add resource accessors
Quoted 9 lines · Miguel Ojeda
Yeah, we had this in the past -- when I introduced the lint, I just went with putting in the middle, e.g. in
rust/kernel/sync/lock.rs'sdo_unlocked.It has been fairly confusing, because long ago AFAIU it was not intended to be supported, but then they introduced a config option for it, and then it was made the default, but there were false positives.
Quoted 7 lines
It seems it has been finally fixed in
https://github.com/rust-lang/rust-clippy/pull/13888 for Rust 1.87.0.I would say just put it in the middle. The only advantage of using an
allowwould be using the "reason" field to say we can move it >= 1.87, but if we really want to move it, we can always use a normal comment to say so instead.
I have added some information and links about this to
https://github.com/Rust-for-Linux/linux/issues/349.
Cheers,
Miguel
Greg Kroah-Hartman
maintainerQuoted 6 lines · Daniel Almeida
---
Daniel Almeida (3):
rust: io: add resource abstraction
rust: io: mem: add a generic iomem abstraction
rust: platform: add resource accessors
Quoted 7 lines
rust/bindings/bindings_helper.h | 1 + rust/helpers/io.c | 41 ++++++ rust/kernel/io.rs | 5 + rust/kernel/io/mem.rs | 283 ++++++++++++++++++++++++++++++++++++++++ rust/kernel/io/resource.rs | 229 ++++++++++++++++++++++++++++++++ rust/kernel/platform.rs | 60 ++++++++- 6 files changed, 618 insertions(+), 1 deletion(-)
Who is going to be responsible for the new files you have added?
And no real objection, but no copyright info was added to them either, was that intentional? I know some companies frown on that as it goes against their corporate policy (but some don't care, it's hard to keep track of who likes what at times...)
thanks,
greg k-h
Danilo Krummrich
maintainerQuoted 15 lines · Greg Kroah-Hartman
Quoted 6 lines · Daniel Almeida
---
Daniel Almeida (3):
rust: io: add resource abstraction
rust: io: mem: add a generic iomem abstraction
rust: platform: add resource accessorsQuoted 7 lines
rust/bindings/bindings_helper.h | 1 + rust/helpers/io.c | 41 ++++++ rust/kernel/io.rs | 5 + rust/kernel/io/mem.rs | 283 ++++++++++++++++++++++++++++++++++++++++ rust/kernel/io/resource.rs | 229 ++++++++++++++++++++++++++++++++ rust/kernel/platform.rs | 60 ++++++++- 6 files changed, 618 insertions(+), 1 deletion(-)
Quoted 1 line
Who is going to be responsible for the new files you have added?
I'm going to take care of the Rust I/O stuff. We'll add an entry for this soon. Until then, it automatically defaults to the RUST entry, like the existing I/O stuff.
Daniel Almeida
maintainerHi Greg,
Quoted 17 lines · Greg Kroah-Hartman
Quoted 6 lines · Daniel Almeida
---
Daniel Almeida (3):
rust: io: add resource abstraction
rust: io: mem: add a generic iomem abstraction
rust: platform: add resource accessorsQuoted 7 lines
rust/bindings/bindings_helper.h | 1 + rust/helpers/io.c | 41 ++++++ rust/kernel/io.rs | 5 + rust/kernel/io/mem.rs | 283 ++++++++++++++++++++++++++++++++++++++++ rust/kernel/io/resource.rs | 229 ++++++++++++++++++++++++++++++++ rust/kernel/platform.rs | 60 ++++++++- 6 files changed, 618 insertions(+), 1 deletion(-)
Quoted 1 line
Who is going to be responsible for the new files you have added?
As Danilo said, there will be a separate entry for the Rust I/O code, which I’ve agreed to share the responsibility for.
Quoted 10 lines
And no real objection, but no copyright info was added to them either, was that intentional? I know some companies frown on that as it goes against their corporate policy (but some don't care, it's hard to keep track of who likes what at times...)
thanks,
greg k-h
Good catch. It wasn't intentional, but I don't think it will be a problem.
-- Daniel
Danilo Krummrich
maintainerQuoted 2 lines · Daniel Almeida
Daniel Almeida (3):
rust: io: add resource abstraction
[ Capitalize safety comments and end it with a period. - Danilo ]
Quoted 1 line
rust: io: mem: add a generic iomem abstraction
[ Add #[expect(dead_code)] to avoid a temporary warning, remove
unnecessary OF_ID_TABLE constants in doc-tests and ignore doc-tests for now to avoid a temporary build failure. - Danilo ]
Quoted 1 line
rust: platform: add resource accessors
[ Remove #[expect(dead_code)] from IoRequest::new() and move SAFETY
comments right on top of unsafe blocks to avoid clippy warnings for some (older) clippy versions. - Danilo ]
Applied to driver-core-testing, thanks!
Quoted 4 lines · Daniel Almeida
Changes in v15:
- Use a default string inioremap()if the resource doesn't have a name
- Fix the doctests inmem.rsto use the new name for io_request_by_*
- Link to v14: https://lore.kernel.org/r/20250716-topics-tyr-platform_iomem-v14-0-2c2709135cb2@collabora.com
I'm not sure if it is too late for this (already applied?) but with
https://lore.kernel.org/rust-for-linux/[email protected]/
in case it helps:
Thanks!
Dirk
Quoted 210 lines
Changes in v14:
- ChangedResource::size()to return ResourceSize instead of u64 (Alice)
- ChangedResource::name()to return a non-static lifetime (i.e.: the
lifetime of &self). It turns out that although this value tends to often
point to string literals, this value is not necessarily static in C.
(Thanks for bringing this up, Alice)
- "name" is now owned by the Region. We were storingResource::name()
previously as that was 'static, but that is not the case anymore. The
string is now copied fromResource::name()instead. If there is no name,
we fail.
- ChangedResource::name()to return an Option, as the name may be NULL in
C (see the DEFINE_RES_* family of macros in C)
- Added a TODO to the "size" cast inIoMem::ioremap(), noting that we
should fix this in C in the future (Thanks, Alice)
- Casting "size" inIoMem::ioremap()only once now (thanks, Alice)
- IntroducedFlags::new(), which derives from a comment in therequest_irq
series. This introduces abuild_assertto reduce the number of casts.
- Added Alice's r-b to patches 1-2
- Added Miguel's a-b to patches 1-3 (Given in v11 and forgotten)
- Link to v13: https://lore.kernel.org/r/20250711-topics-tyr-platform_iomem-v13-0-06328b514db3@collabora.comChanges in v13:
- Change ResourceSize to just bebindings::phys_addr_t(Danilo)
- Mention that ResourceSize can be 32bits even on 64bit architectures (Alice)
- Use the deref impl for Resource to avoid unsafe (Alice)
- ChangeResource::as_ref()toResource::from_raw()(Alice)
- Mention that it's ok for__request_regionto store the name as we require
it to be 'static
- Remove all instances of core::ffi::* as these are in the prelude already
(Alice)
-Resource::start()andResoruce::flags()do not copy &self anymore (Alice)
- Define theresource::Flagsconstants within impl Flags itself (Alice)
- Apply the diff from Danilo to return impl PinInit<...> instead of
Result<impl PinInin<...>> from theiomap()functions.
- Fix the docs in patch 2 (Alice)
- Usetry_into()instead of blindly casting ResourceSize to usize (Alice)
- Rename request_io_by{index,name} to io_request_by{index,name} (Danilo)
- Link to v12: https://lore.kernel.org/rust-for-linux/20250704-topics-tyr-platform_iomem-v12-0-1d3d4bd8207d@collabora.com/Changes in v12:
- Fixed the typos that Miguel pointed out inresource.rs
- Fixed a typo where thread was written as thead
- Removedioport_resource()andiomem_resource()(Danilo)
- Created IoRequest<'a> and gave it an unsafe constructor (Danilo)
- Moved all the logic to map resources fromplatform.rsto IoRequest.
- Dropped the last patch as a result of the above.
- Link to v11: https://lore.kernel.org/r/20250701-topics-tyr-platform_iomem-v11-0-6cd5d5061151@collabora.comChanges in v11:
- Rebased on top of driver-core-next (to get the latest Devres changes)
- Changed the order between requesting the resource and mapping it
(Danilo)
- Link to v10: https://lore.kernel.org/r/20250623-topics-tyr-platform_iomem-v10-0-ed860a562940@collabora.comChanges in v10:
- Rebased on driver-core-next
- Fixed examples (they were still usingtry_access())
- Removedmap_err()from the examples, as it was not needed.
- Added a pub use for Resource inio.rs
- Reworked the platform code to make use of the pub use above
- Link to v9: https://lore.kernel.org/r/20250603-topics-tyr-platform_iomem-v9-0-a27e04157e3e@collabora.comChanges in v9:
- Rebased on top of nova-next (forDevres::access())
- Reworked the documentation to add more markdown.
- Converted to &raw mut instead of addr_of_mut!()
- Renamed 'from_ptr' to 'as_ref' for consistency
- Changed the IoMem examples to use the signature forprobe()
- Changedresource()toresource_by_index(). It's a better fit given
the existance ofresource_by_name().
- Created a separate patch for the resource accessors above.
- Moved the accessors into the generic impl block, so they work with all
Device contexts.
- Take Device<Bound> where applicable
- Renamed "ioremap_*" to "iomap_*", in order to be consistent with the code
inpci.rs
- Switched toDevres::access()
- Link to v8: https://lore.kernel.org/r/20250509-topics-tyr-platform_iomem-v8-0-e9f1725a40da@collabora.comrust: platform: add Io support
Changes in v8:
- Rebased on driver-core-next
- Opted to wait for 'rust/revocable: addtry_with()convenience method' to
land instead of using the suggested closure (let me know if we should
just switch to the closure anyways)
- Cc'd more people
- Link to v7: https://lore.kernel.org/r/20250318-topics-tyr-platform_iomem-v7-0-7438691d9ef7@collabora.comChanges in v7:
- Rebased on top of rust-next
- Fixed a few Clippy lints
- Fixed typos (Thanks Daniel!)
- "struct Flags" now contains a usize (thanks Daniel)
- Fixed "Doc list without indentation" warning (thanks, Guangbo)Thanks, Fiona {
- Removed RequestFn, as all functions simply usedrequest_regionand RequestFn had issues. Onlyrequest_region()is exposed now.
- Gatediomem_resourceonCONFIG_HAS_IOMEM
- Require that the name argument be 'static
}- Correctly check for
IORESOURCE_MEM_NONPOSTED. We now callioremap_npif that is set (thanks, Lina!)
- Remove #[dead_code] attribute fromExclusiveIoMem::region.Changes in v6:
- Added Fiona as co-developer in the first patch, as I merged part of her code from the LED driver series (thanks, Fiona)
- (Fiona) added the ResourceSize type, thereby fixing the u32 vs u64 issues pointed out by Christian
- Moved the
request_region,release_regionand friends toresource.rs- Added the Region type. This type represents a resource returned by
request_regionand friends. It is also owned, representing the fact that the region remains marked as busy untilrelease_regionis called on drop. (Thanks Alice, for pointing out this pattern)- Rewrote the IoMem abstraction to implement a separate type for exclusive access to an underlying region. I really disliked the
EXCLUSIVEconst generic, as it was definitely not ergonomic, i.e.:
IoMem<0, false>...doesn't really say much. In fact, I believe that boolean parameters hurt readability in general.
This new approach lets users build either regular IoMem's, which basically call ioremap under the covers, and ExclusiveIoMem's , which also call
request_regionvia the Region type.- Added access to the
ioresource_portandioresource_memglobals.Link to v5: https://lore.kernel.org/rust-for-linux/[email protected]/
Changes in v5:
- resend v5, as the r4l list was not cc'd
- use srctree where applicable in the docs (Alice)
- Remove 'mut' inResource::from_ptr()(Alice)
- Add 'invariants' section for Resource (Alice)
- Fix typos inmem.rs(Alice)
- Turn 'exclusive' into a const generic (Alice)
- Fix example inplatform.rs(Alice)
- Rework theresource.is_null()check (Alice)
- RefactorIoMem::new()to return DevRes<IoMem> directly (Danilo)link to v4: https://lore.kernel.org/rust-for-linux/[email protected]/
Changes in v4:
- Rebased on top of driver-core-next
- Split series in multiple patches (Danilo)
- Move IoMem and Resource into its own files (Danilo)
- Fix a missing "if exclusive {...}" check (Danilo)
- Fixed the example, since it was using the old API (Danilo)
- Use Opaque inResource, instead of NonNull and PhantomData (Boqun)
- Highlight that non-exclusive access to the iomem might be required in some cases
- Fixed the safety comment inIoMem::deref()Changes in v3:
- Rebased on top of v5 for the PCI/Platform abstractions
-platform_get_resourceis now called only once when calling ioremap
- Introduced aplatform::Resourcetype, which is bound to the lifetime of the platform Device
- Allow retrieving resources from the platform device either by index or name
- Makerequest_mem_region()optional
- Useresource.name()inrequest_mem_region
- Reword the example to remove an unaligned, out-of-bounds offset
- Update the safety requirements ofplatform::IoMemChanges in v2:
- reworked the commit message
- added missingrequest_mem_regioncall (Thanks Alice, Danilo)
-IoMem::new()now takes theplatform::Device, the resource number and the name, instead of an address and a size (thanks, Danilo)
- Added a new example for both sized and unsized versions of IoMem.
- Compiled the examples usingkunit.py(thanks for the tip, Alice!)
- Removed instances offoo as _. Allascasts now spell out the actual type.
- Now compiling with CLIPPY=1 (I realized I had forgotten, sorry)
- Rebased on top of rust-next to check for any warnings given the new unsafe lints.---
Daniel Almeida (3):
rust: io: add resource abstraction
rust: io: mem: add a generic iomem abstraction
rust: platform: add resource accessorsrust/bindings/bindings_helper.h | 1 + rust/helpers/io.c | 41 ++++++ rust/kernel/io.rs | 5 + rust/kernel/io/mem.rs | 283 ++++++++++++++++++++++++++++++++++++++++ rust/kernel/io/resource.rs | 229 ++++++++++++++++++++++++++++++++ rust/kernel/platform.rs | 60 ++++++++- 6 files changed, 618 insertions(+), 1 deletion(-)---
base-commit:f5d3ef25d238901a76fe0277787afa44f7714739
change-id: 20250318-topics-tyr-platform_iomem-1710a177e1dfBest regards,
Daniel Almeida
maintainerQuoted 15 lines · Dirk Behme
Quoted 4 lines · Daniel Almeida
Changes in v15:
- Use a default string inioremap()if the resource doesn't have a name
- Fix the doctests inmem.rsto use the new name for io_request_by_*
- Link to v14: https://lore.kernel.org/r/20250716-topics-tyr-platform_iomem-v14-0-2c2709135cb2@collabora.comI'm not sure if it is too late for this (already applied?) but with
Quoted 8 lines
in case it helps:
Tested-by Dirk Behme <[email protected]>Thanks!
Dirk
Applied already, but thanks anyways! :)
— Daniel