The doc examples in io.rs and devres.rs directly call
bindings::ioremap() and bindings::iounmap(), which do not exist when
CONFIG_HAS_IOMEM is not set. This causes build failures with
CONFIG_RUST_KERNEL_DOCTESTS=y on such configurations (e.g. s390
allnoconfig).
Gate the affected doctests with `#![cfg(CONFIG_HAS_IOMEM)]` so they are
skipped when IOMEM is unavailable.
Fixes: 3f70ebe638 ("s390: Enable Rust support")
Reviewed-by: Arnd Bergmann <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
s390 does not provide ioremap()/iounmap() when CONFIG_HAS_IOMEM is not
set (which requires CONFIG_PCI on that architecture). This causes a
build failure with Rust enabled on e.g. s390 allnoconfig:
In file included from rust/helpers/helpers.c:68:
rust/helpers/io.c:8:9: error: call to undeclared function 'ioremap'; ISO C99 and later do not support implicit function declarations
[-Wimplicit-function-declaration]
8 | return ioremap(offset, size);
| ^
rust/helpers/io.c:19:2: error: call to undeclared function 'iounmap'; ISO C99 and later do not support implicit function declarations
[-Wimplicit-function-declaration]
19 | iounmap(addr);
Guard the C helpers behind #ifdef CONFIG_HAS_IOMEM and cfg-gate the Rust
io::mem module, such that IoMem, ExclusiveIoMem and IoRequest are not
available without CONFIG_HAS_IOMEM.
Note that the C API is inconsistent about this. For instance,
devm_ioremap() has no stub and produces a link failure without
CONFIG_HAS_IOMEM, whereas devm_platform_ioremap_resource() provides an
inline stub returning -EINVAL.
The approach taken here (compile-time gating) matches the former, which
is slightly more appropriate since any driver performing MMIO currently
requires CONFIG_HAS_IOMEM.
Ideally, s390 should provide ioremap()/iounmap() stubs unconditionally
(as UML already does), removing the need for any config gating as
discussed in [1]; a follow-up patch for s390 is expected.
Cc: Arnd Bergmann <[email protected]>
Reported-by: Miguel Ojeda <[email protected]>
Closes: https://lore.kernel.org/all/[email protected] [1]
Fixes: 3f70ebe638 ("s390: Enable Rust support")
Reviewed-by: Arnd Bergmann <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Due to the usage of `build_assert!` for address validity checking, these
accessors want constant offsets. Non-constant offsets can work but it
depend on compiler optimization levels, so it should be avoided.
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Alexandre Courbot <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Add an enum as sum type for `Mmio` and `SysMem`. This serves similar
purpose of `iosys_map`. Thanks to Rust's type system, all of projection and
struct read/write can be handled by the generic I/O projection mechanism
(i.e. `io_project!`, `io_read!, `io_write!`) for free, and there is no need
to provide things like `iosys_map_rd_field` or `iosys_map_wr_field`. An
enum type also makes it very easy to construct or destruct.
This could be made more generic by implementing on a general purpose sum
type like `Either`; however this is kept specific unless a need arises that
warrants this to be generic over other I/O backends.
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
One feature that was lost from the old `dma_read!` and `dma_write!` when
moving to `io_read!` and `io_write!` was the ability to read/write a large
structs. However, the semantics was unclear to begin with, as there was no
guarantee about their atomicity even for structs that were small enough to
fit in u32. Re-introduce the capability in the form of copying methods.
dma_read!(foo, bar) -> io_project!(foo, bar).copy_read()
dma_write!(foo, bar, baz) -> io_project!(foo, bar).copy_write(baz)
Model these semantics after memcpy so user has clear expectation of lack of
atomicity. As an additional benefit of this change, this now works for MMIO
as well by mapping them to `memcpy_{from,to}io`.
For slices which is DST so the `copy_read` and `copy_write` API above can't
work, add `copy_from_slice` and `copy_to_slice` to copy from/to normal
memory.
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Alexandre Courbot <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Provide `read_val` and `write_val` that allow I/O views to be accessed when
they're narrowed down to just views of primitives.
This is used to provide `io_read!` and `io_write!` macros, which are
generalized version of current `dma_read!` and `dma_write!` macro that work
for all types that implement `Io`.
Note though `io_read!` and `io_write!` only works if backend implements
`IoCapable` for the type; which is typically only implemented for
atomically accessible primitives. `dma_read!` and `dma_write!` currently
supports them via `read_volatile` and `write_volatile`; this can be
undesirable for aggregates as LLVM may turn them to multiple instructions
to access parts and re-assemble, even if they could be combined to a single
instruction. Thus, `io_read!()` and `io_write!()` does not fully replace
`dma_read!()` and `dma_write!()` in this scenario. The ability to
read/write aggregates (when atomicity is of no concern) is better served
with copying primitives (e.g. memcpy_{from,to}io).
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Add `SysMem`, an `Io` trait implementation for kernel virtual address
ranges. It uses volatile accessors to provide safe access to shared
memory that may be concurrently accessed by external hardware. Implement
`IoCapable` for `u8`, `u16`, `u32`, and `u64` (for 64-bit system).
This can be used instead of `Coherent` for cases where a different layer
takes care of mapping the system memory to the device (e.g. dma-buf or
GPUVM).
Signed-off-by: Laura Nao <[email protected]>
[ Rebased and adapted on top of I/O rework. - Gary ]
Co-developed-by: Gary Guo <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Alexandre Courbot <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Add an `io_project!()` macro to allow projection from `Io` to a subview of
it, using the pointer projection mechanism to perform compile-time checks.
For cases where type-casting is required, the `try_cast()` function may be
used where the size and alignment checks are performed at runtime.
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
`Io` trait now has a single required method with many more provided
methods. Provided methods may want to rely on their implementations to not
be arbitrarily overridden by implementers for correctness or soundness.
A good example is the `size` method, it may be relied by unsafe code and
thus must be consistent with the metadata obtained from `as_ptr`.
Thus, create a new trait to host `size` method, extract existing provided
methods to the new trait, and provide a blanket implementation. This
pattern is used extensively in userspace Rust libraries e.g. `tokio` where
`AsyncRead` has minimum methods and `AsyncReadExt` is what users mostly
interact with.
To avoid changing all user imports, the base trait is renamed to `IoBase`
and the newly added trait takes the existing `Io` name.
Reviewed-by: Alexandre Courbot <[email protected]>
Suggested-by: Danilo Krummrich <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ Add comment explaining the purpose of the Io blanket implementation.
- Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
Currently, `io_read` and `io_write` methods require the exact type of `Io`
plus an address. This means that they need to be monomorphized for each
different `Io` instance. This also means that multiple I/O implementors for
the same I/O kind needs to duplicate implementation (e.g. `Mmio` and
`MmioOwned`).
Create a new `IoBackend` trait and define these operations on it instead.
The operations are just going to receive a view type and operate on them.
This has the additional advantage that the invariants can be moved from the
trait (and guaranteed via `unsafe`) to type invariants on the canonical
view types of the backends, so `io_read` and `io_write` can be safe.
Note that a view type is needed; addresses are insufficient in this
design, as they do not carry sufficient information. For example,
`ConfigSpace` needs `&pci::Device` in addition to the address.
`io_addr_assert` and `io_addr` are renamed to `io_view*` to reflect
that they operate on views now, and make them standalone functions so
they cannot be used by users to cast types outside io.rs.
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Implement `Mmio` as view type and convert `RelaxedMmio` to view type as
well. I/O implementations of `MmioOwned` are changed to delegate to the
`Mmio` view type.
All existing users of `MmioOwned` in the documentation which do not
actually reflect the owning semantics is converted.
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Tested-by: Daniel Almeida <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Conceptually, `MmioRaw` is just `__iomem *`, so it should work for any
types. Update the existing use case where it represents a region of
compile-time known minimum size and run-time known actual size to use the
dynamic-sized type `Region<SIZE>` instead. Rename `maxsize` method to
reflect that it is the actual size (not a bound) of the region.
Implement `Clone` and `Copy` manually, which cannot be derived due to the
generic parameter. The use of raw pointers also cause the `Send` and `Sync`
auto trait implementation to be lost, so add them back by manual
implementation.
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Suggested-by: Danilo Krummrich <[email protected]>
Link: https://rust-for-linux.zulipchat.com/#narrow/channel/288089-General/topic/Generic.20I.2FO.20backends/near/571198078
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Currently, `Io` is implemented on owned I/O objects (e.g. `Bar`). This is
going to change with I/O projections, as then `Io` needs to work both for
owned objects and views of them. Views are themselves reference-like
(however they obviously cannot be references, because they belong to a
different address space).
To facilitate the change, change `Io` to be implemented on reference types
for the owned I/O objects, and make methods take `self` instead of `&self`.
When I/O views are implemented, we can then naturally implement `Io` for
these objects.
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Currently the `Io` trait exposes a bunch of untyped IO accesses, but if the
`Io` region itself is typed, then it might be weird to have
let io: Mmio<u32> = /* ... */;
io.read8(1);
while not unsound, it is surely strange. Thus, restrict the untyped methods
and also the register macro to `Region` type only.
Implement it by adding a generic type to `IoLoc` indicating allowed base
types. This also paves the way to add typed register blocks in the future;
for example, we could use this mechanism to block driver A's `register!()`
generated macro from being used on driver B's MMIO. The same mechanism
could be used for relative IO registers. These are future opportunities,
and for now restrict everything to require `IoLoc<Region<SIZE>, _>`.
Suggested-by: Alexandre Courbot <[email protected]>
Link: https://lore.kernel.org/rust-for-linux/[email protected]/
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
The current safety comment on `io_read`/`io_write` does not cover the topic
about alignment. Add it so it can be relied on by implementor of
`IoCapable`.
Expand the check performed by `Io` by taking `self.addr()` into
consideration when checking if `offset` is aligned. For the compile-time
`io_addr_assert` check, check using the known minimum alignment of
`Io::Target` and the accessed type.
While at it, fix the alignment check to use `align_of` instead of
`size_of`. The values match for all primitives (including u64, given that
we do not provide u64 accessor on 32-bit platforms), but are not
necessarily true for custom types.
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Currently many I/O related structs carry a `SIZE` parameter to denote the
minimum size of the I/O region, while they also carry a field indicating
the actual size. Proliferation of the pattern creates a lot of duplicated
code, and makes it hard to create typed views of I/O.
Introduce a `Region` type that carries the `SIZE` parameter. It is a
wrapper of `[u8]`, which makes it dynamically sized with a metadata of
`usize`. This way, pointers to `Region` naturally carry size information.
This type is required to be 4-byte aligned.
Expose the minimum size information via `MIN_SIZE` constant of the
`KnownSize` trait. Similarly, expose the minimum alignment information via
`KnownSize::MIN_ALIGN`.
With these changes, it is possible to add an associated type to `Io` trait
to represent the type of I/O region. For untyped regions, this is the newly
added `Region` type. Remove `IoKnownSize` as it is no longer necessary. Use
the same mechanism to indicate minimum size of PCI config spaces.
Reviewed-by: Alexandre Courbot <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ Add brief explanation on MIN_ALIGN. - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
Some I/O types, like fixed address registers, carry their location
alongside their values. For these types, the regular `Io::write` method
can lead into repeating the location information twice: once to provide
the location itself, another time to build the value.
We are also considering supporting making all register values carry
their full location information for convenience and safety.
Add a new `Io::write_reg` method that takes a single argument
implementing `LocatedRegister`, a trait that decomposes implementors
into a `(location, value)` tuple. This allows write operations on fixed
offset registers to be done while specifying their name only once.
Suggested-by: Danilo Krummrich <[email protected]>
Link: https://lore.kernel.org/all/[email protected]/
Signed-off-by: Alexandre Courbot <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ Replace FIFO with VERSION register in the examples. - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
Add a macro for defining hardware register types with I/O accessors.
Each register field is represented as a `Bounded` of the appropriate bit
width, ensuring field values are never silently truncated.
Fields can optionally be converted to/from custom types, either fallibly
or infallibly.
The address of registers can be direct, relative, or indexed, supporting
most of the patterns in which registers are arranged.
Suggested-by: Danilo Krummrich <[email protected]>
Link: https://lore.kernel.org/all/[email protected]/
Co-developed-by: Gary Guo <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Signed-off-by: Alexandre Courbot <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ * Improve wording and formatting of doc-comments,
* Import build_assert!(),
* Add missing inline annotations,
* Call static_assert!() with absolute path,
* Use expect instead of allow.
- Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
By providing the required `IoLoc` implementations on `usize`, we can
leverage the generic accessors and reduce the number of unsafe blocks in
the module.
This also allows us to directly call the generic `read/write/update`
methods with primitive types, so add examples illustrating this.
Signed-off-by: Alexandre Courbot <[email protected]>
Reviewed-by: Gary Guo <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ Slightly improve wording in doc-comment. - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
I/O accesses are defined by the following properties:
- An I/O location, which consists of a start address, a width, and a
type to interpret the read value as,
- A value, which is returned for reads or provided for writes.
Introduce the `IoLoc` trait, which allows implementing types to fully
specify an I/O location.
This allows I/O operations to be made generic through the new `read` and
`write` methods.
This design will allow us to factorize the I/O code working with
primitives, and to introduce ways to perform I/O with a higher degree of
control through register types.
Co-developed-by: Gary Guo <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Signed-off-by: Alexandre Courbot <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ Fix incorrect reference to io_addr_assert() in try_update(). - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
Relaxed I/O accessors for `Mmio` are currently implemented as an extra
set of methods that mirror the ones defined in `Io`, but with the
`_relaxed` suffix.
This makes these methods impossible to use with generic code, which is a
highly plausible proposition now that we have the `Io` trait.
Address this by adding a new `RelaxedMmio` wrapper type for `Mmio` that
provides its own `IoCapable` implementations relying on the relaxed C
accessors. This makes it possible to use relaxed operations on a `Mmio`
simply by wrapping it, and to use `RelaxedMmio` in code generic against
`Io`.
Acked-by: Alice Ryhl <[email protected]>
Signed-off-by: Alexandre Courbot <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Reviewed-by: Gary Guo <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ Use kernel import style in examples. - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
`IoCapable<T>` is currently used as a marker trait to signal that the
methods of the `Io` trait corresponding to `T` have been overridden by
the implementor (the default implementations triggering a build-time
error).
This goes against the DRY principle and separates the signaling of the
capability from its implementation, making it possible to forget a step
while implementing a new `Io`.
Another undesirable side-effect is that it makes the implementation of
I/O backends boilerplate-y and convoluted: currently this is done using
two levels of imbricated macros that generate unsafe code.
Fix these issues by turning `IoCapable` into a functional trait that
includes the raw implementation of the I/O access for `T` using
unsafe methods that work with an arbitrary address.
This allows us to turn the default methods of `Io` into regular methods
that check the passed offset, turn it into an address, and call into the
corresponding `IoCapable` functions, removing the need to overload them
at all.
`IoCapable` must still be implemented for all supported primitive types,
which is still done more concisely using a macro, but this macro becomes
much simpler and does not require calling into another one.
Reviewed-by: Daniel Almeida <[email protected]>
Acked-by: Alice Ryhl <[email protected]>
Signed-off-by: Alexandre Courbot <[email protected]>
Reviewed-by: Gary Guo <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
Currently, the define_read!() and define_write!() I/O macros are crate
public. The only user outside of the I/O module is PCI (for the
configurations space I/O backend). Consequently, when CONFIG_PCI=n this
causes a compile time warning [1].
In order to fix this, rename the macros to io_define_read!() and
io_define_write!() and use #[macro_export] to export them.
This is better than making the crate public visibility conditional, as
eventually subsystems will have their own crate.
Also, I/O backends are valid to be implemented by drivers as well. For
instance, there are devices (such as GPUs) that run firmware which
allows to program other devices only accessible through the primary
device through indirect I/O.
Since the macros are now public, also add the corresponding
documentation.
Fixes: 121d87b28e ("rust: io: separate generic I/O helpers from MMIO implementation")
Reported-by: Miguel Ojeda <[email protected]>
Closes: https://lore.kernel.org/driver-core/CANiq72khOYkt6t5zwMvSiyZvWWHMZuNCMERXu=7K=_5tT-8Pgg@mail.gmail.com/ [1]
Reviewed-by: Alice Ryhl <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
`MIN_SIZE` and `io_addr_assert` are only ever used for IO types which
implement `IoKnownSize` and do not make sense for types that don't.
It looks like they should have been there since the beginning, so move
them while the code is still fresh.
Also update `IoKnownSize`'s documentation since it is not just a marker
trait anymore.
Fixes: 121d87b28e ("rust: io: separate generic I/O helpers from MMIO implementation")
Signed-off-by: Alexandre Courbot <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ Fix typo in commit message. - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
Drivers might need to access PCI config space for querying capability
structures and access the registers inside the structures.
For Rust drivers need to access PCI config space, the Rust PCI abstraction
needs to support it in a way that upholds Rust's safety principles.
Introduce a `ConfigSpace` wrapper in Rust PCI abstraction to provide safe
accessors for PCI config space. The new type implements the `Io` trait and
`IoCapable<T>` for u8, u16, and u32 to share offset validation and
bound-checking logic with other I/O backends.
The `ConfigSpace` type uses marker types (`Normal` and `Extended`) to
represent configuration space sizes at the type level.
Cc: Alexandre Courbot <[email protected]>
Cc: Danilo Krummrich <[email protected]>
Cc: Gary Guo <[email protected]>
Cc: Joel Fernandes <[email protected]>
Signed-off-by: Zhi Wang <[email protected]>
Reviewed-by: Gary Guo <[email protected]>
Link: https://lore.kernel.org/all/[email protected]/ [1]
Link: https://patch.msgid.link/[email protected]
[ Applied the diff from [1], considering subsequent comment; remove
#[expect(unused)] from define_{read,write}!(). - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
Refactor the existing MMIO accessors to use common call macros
instead of inlining the bindings calls in each `define_{read,write}!`
expansion.
This factoring separates the common offset/bounds checks from the
low-level call pattern, making it easier to add additional I/O accessor
families.
No functional change intended.
Cc: Alexandre Courbot <[email protected]>
Signed-off-by: Zhi Wang <[email protected]>
Reviewed-by: Alexandre Courbot <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
The previous Io<SIZE> type combined both the generic I/O access helpers
and MMIO implementation details in a single struct. This coupling prevented
reusing the I/O helpers for other backends, such as PCI configuration
space.
Establish a clean separation between the I/O interface and concrete
backends by separating generic I/O helpers from MMIO implementation.
Introduce a new trait hierarchy to handle different access capabilities:
- IoCapable<T>: A marker trait indicating that a backend supports I/O
operations of a certain type (u8, u16, u32, or u64).
- Io trait: Defines fallible (try_read8, try_write8, etc.) and infallibile
(read8, write8, etc.) I/O methods with runtime bounds checking and
compile-time bounds checking.
- IoKnownSize trait: The marker trait for types support infallible I/O
methods.
Move the MMIO-specific logic into a dedicated Mmio<SIZE> type that
implements the Io traits. Rename IoRaw to MmioRaw and update consumers to
use the new types.
Cc: Alexandre Courbot <[email protected]>
Cc: Alice Ryhl <[email protected]>
Cc: Bjorn Helgaas <[email protected]>
Cc: Gary Guo <[email protected]>
Cc: Danilo Krummrich <[email protected]>
Cc: John Hubbard <[email protected]>
Signed-off-by: Zhi Wang <[email protected]>
Reviewed-by: Alice Ryhl <[email protected]>
Reviewed-by: Alexandre Courbot <[email protected]>
Reviewed-by: Gary Guo <[email protected]>
Link: https://patch.msgid.link/[email protected]
[ Add #[expect(unused)] to define_{read,write}!(). - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
`build_assert` relies on the compiler to optimize out its error path.
Functions using it with its arguments must thus always be inlined,
otherwise the error path of `build_assert` might not be optimized out,
triggering a build error.
Cc: [email protected]
Fixes: ce30d94e68 ("rust: add `io::{Io, IoRaw}` base types")
Reviewed-by: Daniel Almeida <[email protected]>
Signed-off-by: Alexandre Courbot <[email protected]>
Tested-by: Timur Tabi <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Danilo Krummrich <[email protected]>
The C typedef phys_addr_t is missing an analogue in Rust, meaning that
we end up using bindings::phys_addr_t or ResourceSize as a replacement
in various places throughout the kernel. Fix that by introducing a new
typedef on the Rust side. Place it next to the existing ResourceSize
typedef since they're quite related to each other.
Cc: [email protected] # for v6.18 [1]
Signed-off-by: Alice Ryhl <[email protected]>
Link: https://patch.msgid.link/[email protected]
Link: https://lore.kernel.org/all/[email protected]/ [1]
Signed-off-by: Danilo Krummrich <[email protected]>
Resource sizes are a general concept for dealing with physical
addresses, and not specific to the Resource type, which is just one way
to access physical addresses. Thus, move the typedef to the io module.
Still keep a re-export under resource. This avoids this commit from
being a flag-day, but I also think it's a useful re-export in general so
that you can import
use kernel::io::resource::{Resource, ResourceSize};
instead of having to write
use kernel::io::{
resource::Resource,
ResourceSize,
};
in the specific cases where you need ResourceSize because you are using
the Resource type. Therefore I think it makes sense to keep this
re-export indefinitely and it is *not* intended as a temporary re-export
for migration purposes.
Cc: [email protected] # for v6.18 [1]
Signed-off-by: Alice Ryhl <[email protected]>
Link: https://patch.msgid.link/[email protected]
Link: https://lore.kernel.org/all/[email protected]/ [1]
Signed-off-by: Danilo Krummrich <[email protected]>
Add read_poll_timeout function which polls periodically until a
condition is met, an error occurs, or the timeout is reached.
The C's read_poll_timeout (include/linux/iopoll.h) is a complicated
macro and a simple wrapper for Rust doesn't work. So this implements
the same functionality in Rust.
The C version uses usleep_range() while the Rust version uses
fsleep(), which uses the best sleep method so it works with spans that
usleep_range() doesn't work nicely with.
The sleep_before_read argument isn't supported since there is no user
for now. It's rarely used in the C version.
Reviewed-by: Andreas Hindborg <[email protected]>
Reviewed-by: Fiona Behrens <[email protected]>
Reviewed-by: Alexandre Courbot <[email protected]>
Tested-by: Alexandre Courbot <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Tested-by: Daniel Almeida <[email protected]>
Reviewed-by: Alice Ryhl <[email protected]>
Signed-off-by: FUJITA Tomonori <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
[ Fix a minor typo and add missing backticks. - Danilo ]
Signed-off-by: Danilo Krummrich <[email protected]>
Pull Rust updates from Miguel Ojeda:
"Toolchain and infrastructure:
- Enable a set of Clippy lints: 'ptr_as_ptr', 'ptr_cast_constness',
'as_ptr_cast_mut', 'as_underscore', 'cast_lossless' and
'ref_as_ptr'
These are intended to avoid type casts with the 'as' operator,
which are quite powerful, into restricted variants that are less
powerful and thus should help to avoid mistakes
- Remove the 'author' key now that most instances were moved to the
plural one in the previous cycle
'kernel' crate:
- New 'bug' module: add 'warn_on!' macro which reuses the existing
'BUG'/'WARN' infrastructure, i.e. it respects the usual sysctls and
kernel parameters:
warn_on!(value == 42);
To avoid duplicating the assembly code, the same strategy is
followed as for the static branch code in order to share the
assembly between both C and Rust
This required a few rearrangements on C arch headers -- the
existing C macros should still generate the same outputs, thus no
functional change expected there
- 'workqueue' module: add delayed work items, including a
'DelayedWork' struct, a 'impl_has_delayed_work!' macro and an
'enqueue_delayed' method, e.g.:
/// Enqueue the struct for execution on the system workqueue,
/// where its value will be printed 42 jiffies later.
fn print_later(value: Arc<MyStruct>) {
let _ = workqueue::system().enqueue_delayed(value, 42);
}
- New 'bits' module: add support for 'bit' and 'genmask' functions,
with runtime- and compile-time variants, e.g.:
static_assert!(0b00010000 == bit_u8(4));
static_assert!(0b00011110 == genmask_u8(1..=4));
assert!(checked_bit_u32(u32::BITS).is_none());
- 'uaccess' module: add 'UserSliceReader::strcpy_into_buf', which
reads NUL-terminated strings from userspace into a '&CStr'
Introduce 'UserPtr' newtype, similar in purpose to '__user' in C,
to minimize mistakes handling userspace pointers, including mixing
them up with integers and leaking them via the 'Debug' trait. Add
it to the prelude, too
- Start preparations for the replacement of our custom 'CStr' type
with the analogous type in the 'core' standard library. This will
take place across several cycles to make it easier. For this one,
it includes a new 'fmt' module, using upstream method names and
some other cleanups
Replace 'fmt!' with a re-export, which helps Clippy lint properly,
and clean up the found 'uninlined-format-args' instances
- 'dma' module:
- Clarify wording and be consistent in 'coherent' nomenclature
- Convert the 'read!()' and 'write!()' macros to return a 'Result'
- Add 'as_slice()', 'write()' methods in 'CoherentAllocation'
- Expose 'count()' and 'size()' in 'CoherentAllocation' and add
the corresponding type invariants
- Implement 'CoherentAllocation::dma_handle_with_offset()'
- 'time' module:
- Make 'Instant' generic over clock source. This allows the
compiler to assert that arithmetic expressions involving the
'Instant' use 'Instants' based on the same clock source
- Make 'HrTimer' generic over the timer mode. 'HrTimer' timers
take a 'Duration' or an 'Instant' when setting the expiry time,
depending on the timer mode. With this change, the compiler can
check the type matches the timer mode
- Add an abstraction for 'fsleep'. 'fsleep' is a flexible sleep
function that will select an appropriate sleep method depending
on the requested sleep time
- Avoid 64-bit divisions on 32-bit hardware when calculating
timestamps
- Seal the 'HrTimerMode' trait. This prevents users of the
'HrTimerMode' from implementing the trait on their own types
- Pass the correct timer mode ID to 'hrtimer_start_range_ns()'
- 'list' module: remove 'OFFSET' constants, allowing to remove
pointer arithmetic; now 'impl_list_item!' invokes
'impl_has_list_links!' or 'impl_has_list_links_self_ptr!'. Other
simplifications too
- 'types' module: remove 'ForeignOwnable::PointedTo' in favor of a
constant, which avoids exposing the type of the opaque pointer, and
require 'into_foreign' to return non-null
Remove the 'Either<L, R>' type as well. It is unused, and we want
to encourage the use of custom enums for concrete use cases
- 'sync' module: implement 'Borrow' and 'BorrowMut' for 'Arc' types
to allow them to be used in generic APIs
- 'alloc' module: implement 'Borrow' and 'BorrowMut' for 'Box<T, A>';
and 'Borrow', 'BorrowMut' and 'Default' for 'Vec<T, A>'
- 'Opaque' type: add 'cast_from' method to perform a restricted cast
that cannot change the inner type and use it in callers of
'container_of!'. Rename 'raw_get' to 'cast_into' to match it
- 'rbtree' module: add 'is_empty' method
- 'sync' module: new 'aref' submodule to hold 'AlwaysRefCounted' and
'ARef', which are moved from the too general 'types' module which
we want to reduce or eventually remove. Also fix a safety comment
in 'static_lock_class'
'pin-init' crate:
- Add 'impl<T, E> [Pin]Init<T, E> for Result<T, E>', so results are
now (pin-)initializers
- Add 'Zeroable::init_zeroed()' that delegates to 'init_zeroed()'
- New 'zeroed()', a safe version of 'mem::zeroed()' and also provide
it via 'Zeroable::zeroed()'
- Implement 'Zeroable' for 'Option<&T>', 'Option<&mut T>' and for
'Option<[unsafe] [extern "abi"] fn(...args...) -> ret>' for
'"Rust"' and '"C"' ABIs and up to 20 arguments
- Changed blanket impls of 'Init' and 'PinInit' from 'impl<T, E>
[Pin]Init<T, E> for T' to 'impl<T> [Pin]Init<T> for T'
- Renamed 'zeroed()' to 'init_zeroed()'
- Upstream dev news: improve CI more to deny warnings, use
'--all-targets'. Check the synchronization status of the two
'-next' branches in upstream and the kernel
MAINTAINERS:
- Add Vlastimil Babka, Liam R. Howlett, Uladzislau Rezki and Lorenzo
Stoakes as reviewers (thanks everyone)
And a few other cleanups and improvements"
* tag 'rust-6.17' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux: (76 commits)
rust: Add warn_on macro
arm64/bug: Add ARCH_WARN_ASM macro for BUG/WARN asm code sharing with Rust
riscv/bug: Add ARCH_WARN_ASM macro for BUG/WARN asm code sharing with Rust
x86/bug: Add ARCH_WARN_ASM macro for BUG/WARN asm code sharing with Rust
rust: kernel: move ARef and AlwaysRefCounted to sync::aref
rust: sync: fix safety comment for `static_lock_class`
rust: types: remove `Either<L, R>`
rust: kernel: use `core::ffi::CStr` method names
rust: str: add `CStr` methods matching `core::ffi::CStr`
rust: str: remove unnecessary qualification
rust: use `kernel::{fmt,prelude::fmt!}`
rust: kernel: add `fmt` module
rust: kernel: remove `fmt!`, fix clippy::uninlined-format-args
scripts: rust: emit path candidates in panic message
scripts: rust: replace length checks with match
rust: list: remove nonexistent generic parameter in link
rust: bits: add support for bits/genmask macros
rust: list: remove OFFSET constants
rust: list: add `impl_list_item!` examples
rust: list: use fully qualified path
...
Add 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.
Acked-by: Miguel Ojeda <[email protected]>
Reviewed-by: Alice Ryhl <[email protected]>
Signed-off-by: Daniel Almeida <[email protected]>
Link: https://lore.kernel.org/r/20250717-topics-tyr-platform_iomem-v15-2-beca780b77e3@collabora.com
[ 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 ]
Signed-off-by: Danilo Krummrich <[email protected]>
In Rust 1.63.0, Clippy introduced the `as_underscore` lint [1]:
> The conversion might include lossy conversion or a dangerous cast that
> might go undetected due to the type being inferred.
>
> The lint is allowed by default as using `_` is less wordy than always
> specifying the type.
Always specifying the type is especially helpful in function call
contexts where the inferred type may change at a distance. Specifying
the type also allows Clippy to spot more cases of `useless_conversion`.
The primary downside is the need to specify the type in trivial getters.
There are 4 such functions: 3 have become slightly less ergonomic, 1 was
revealed to be a `useless_conversion`.
While this doesn't eliminate unchecked `as` conversions, it makes such
conversions easier to scrutinize. It also has the slight benefit of
removing a degree of freedom on which to bikeshed. Thus apply the
changes and enable the lint -- no functional change intended.
Link: https://rust-lang.github.io/rust-clippy/master/index.html#as_underscore [1]
Reviewed-by: Benno Lossin <[email protected]>
Reviewed-by: Boqun Feng <[email protected]>
Signed-off-by: Tamir Duberstein <[email protected]>
Acked-by: Greg Kroah-Hartman <[email protected]>
Acked-by: Danilo Krummrich <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
[ Changed `isize` to `c_long`. - Miguel ]
Signed-off-by: Miguel Ojeda <[email protected]>
I/O memory is typically either mapped through direct calls to ioremap()
or subsystem / bus specific ones such as pci_iomap().
Even though subsystem / bus specific functions to map I/O memory are
based on ioremap() / iounmap() it is not desirable to re-implement them
in Rust.
Instead, implement a base type for I/O mapped memory, which generically
provides the corresponding accessors, such as `Io::readb` or
`Io:try_readb`.
`Io` supports an optional const generic, such that a driver can indicate
the minimal expected and required size of the mapping at compile time.
Correspondingly, calls to the 'non-try' accessors, support compile time
checks of the I/O memory offset to read / write, while the 'try'
accessors, provide boundary checks on runtime.
`IoRaw` is meant to be embedded into a structure (e.g. pci::Bar or
io::IoMem) which creates the actual I/O memory mapping and initializes
`IoRaw` accordingly.
To ensure that I/O mapped memory can't out-live the device it may be
bound to, subsystems must embed the corresponding I/O memory type (e.g.
pci::Bar) into a `Devres` container, such that it gets revoked once the
device is unbound.
Reviewed-by: Alice Ryhl <[email protected]>
Tested-by: Daniel Almeida <[email protected]>
Reviewed-by: Daniel Almeida <[email protected]>
Signed-off-by: Danilo Krummrich <[email protected]>
Tested-by: Dirk Behme <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Greg Kroah-Hartman <[email protected]>
Danilo Krummrich