Re: [PATCH v2 1/5] rust/io: factor common I/O helpers into Io trait and specialize Mmio<SIZE>

[Bjorn Helgaas <helgaas@kernel.org>]

On Thu, Oct 16, 2025 at 09:02:46PM +0000, Zhi Wang wrote:
> The previous Io<SIZE> type combined both the generic I/O access helpers
> and MMIO implementation details in a single struct.
> 
> To establish a cleaner layering between the I/O interface and its concrete
> backends, paving the way for supporting additional I/O mechanisms in the
> future, Io<SIZE> need to be factored.
> 
> Factor the common helpers into a new Io trait, and moves the MMIO-specific
> logic into a dedicated Mmio<SIZE> type implementing that trait. Rename the
> IoRaw to MmioRaw and pdate the bus MMIO implementations to use MmioRaw.

s/and moves/and move/ to match "Factor" and "Rename"
s/pdate/update/ ?

> +/// Instead, the bus specific MMIO implementation must convert this raw representation into an
> +/// `Mmio` instance providing the actual memory accessors. Only by the conversion into an `Mmio`
> +/// structure any guarantees are given.

s/any guarantees are given/are any guarantees given/

> +    /// Returns a new `MmioRaw` instance ...
> +/// Provides common helpers ...
> +    /// Checks whether an access ...

There's a Linux trend toward using "imperative mood", e.g., "Return",
for commit logs and comments, but I notice Rust code more often seems
to use the indicative mood: "Returns", "Provides", "Checks", etc.

Maybe that's part of the Rust style; I dunno if that's intentional or
worth commenting on, just something I notice.

Bjorn