Re: [PATCH] rust: io: move offset_valid and io_addr(_assert) to IoRaw

[Danilo Krummrich <dakr@kernel.org>]

On Wed, Jan 22, 2025 at 02:56:53PM +0000, Gary Guo wrote:
> On Wed, 22 Jan 2025 15:22:27 +0100
> Danilo Krummrich <dakr@kernel.org> wrote:
> 
> > On Wed, Jan 22, 2025 at 01:38:09PM +0100, Fiona Behrens wrote:
> > > Move the helper functions `offset_valid`, `io_addr` and
> > > `io_addr_asset` from `Io` to `IoRaw`. This allows `IoRaw` to be reused
> > > if other abstractions with different write/read functions are
> > > needed (e.g. `writeb` vs `iowrite` vs `outb`).
> > > 
> > > Make this functions public as well so they can be used from other
> > > modules if you aquire a `IoRaw`.  
> > 
> > I don't think they should be public. Instead the abstraction for I/O ports
> > should be in this file, just like `Io` is.
> > 
> > Another option could also be to just extend the existing `Io` abstraction for
> > I/O ports.
> > 
> > > 
> > > Signed-off-by: Fiona Behrens <me@kloenk.dev>
> > > ---
> > >  rust/kernel/io.rs | 98 +++++++++++++++++++++++++++++++++++--------------------
> > >  1 file changed, 63 insertions(+), 35 deletions(-)
> > > 
> > > diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
> > > index d4a73e52e3ee68f7b558749ed0108acde92ae5fe..a6d026f458608626113fd194ee5a8616b4ef76fe 100644
> > > --- a/rust/kernel/io.rs
> > > +++ b/rust/kernel/io.rs
> > > @@ -15,6 +15,11 @@
> > >  /// Instead, the bus specific MMIO implementation must convert this raw representation into an `Io`
> > >  /// instance providing the actual memory accessors. Only by the conversion into an `Io` structure
> > >  /// any guarantees are given.
> > > +///
> > > +/// # Invariant  
> > 
> > You phrased this invariant as if it would be a requirement, but it's more like a
> > something that's always uphold. I'd phrase it as a fact that can be relied on.
> 
> I thinkt the use of `Invariant` here is correct, as this needs to be

I think so too -- `Invariant` is the correct thing to use here.

But everywhere else in the kernel we phrase it differently. For instace, in
`Box` we say:

"`self.0` is always properly aligned and either points to memory allocated with
`A` or, for zero-sized types, is a dangling, well aligned pointer."

because this is ensured by the (safety requirements of the) constructor.

We don't say:

"`self.0` must be always properly aligned and either point to memory allocated
with `A` or, for zero-sized types, must be a dangling, well aligned pointer."

> uphold by the constructors (and only then it can be relied on). However
> the patch doesn't clearly indicate that.