Re: [PATCH v8 07/10] rust: io: introduce `IntoIoVal` trait and single-argument `write_val`

[Alexandre Courbot]

On Wed Mar 11, 2026 at 11:56 PM JST, Danilo Krummrich wrote:
> On Wed Mar 11, 2026 at 2:28 PM CET, Alexandre Courbot wrote:
>> The fact is, there is a symmetry between `read` and `write`:
>>
>> - `read` takes a location and returns a value,
>> - `write` takes a location and a value.
>
> This is not entirely true.
>
> read() takes an absolute location and returns something that encodes the value
> and a relative location, where for fixed registers the relative location is
> equivalent to an absolute location.

Let's look at the prototype of `read` (inherited constraints in parentheses):

    fn read<T, L>(&self, location: L) -> T
    where
        L: IoLoc<T>,
        Self: IoKnownSize + IoCapable<L::IoType>,
        (L::IoType: Into<T> + From<T>,)

It takes an absolute location and returns... something that can be
converted to/from the I/O type. There is no mention of a relative
location anywhere.

The very concept of a relative location is local to the `register`
module. `read` doesn't care about this at all. It just so happens that
register do carry that information in their type  - but that's not a
requirement of the read/write I/O API.

>
> write() works with both an absolute location and something that encodes the
> value and a relative location, or a base location and something that encodes the
> value and a relative location.

Again, looking at the prototype for `write`:

    fn write<T, L>(&self, location: L, value: T)
    where
        L: IoLoc<T>,
        Self: IoKnownSize + IoCapable<L::IoType>,
        (L::IoType: Into<T> + From<T>,)

The first argument is an absolute location. The second argument is just
a value - there is no requirement for any kind of partial location
information.

It is true that in the case of registers, we can use the second argument
to infer a generic parameter of the first that is needed to build that
absolute location, which makes the first argument look as if it
contained partial location information, but that's just because the
*register* module defines this relationship between its own location and
value types (and the compiler is nice enough to connect the dots for
us). This is again not the work of the read/write I/O API.

So we really have this:

- read(location) -> value
- write(location, value)

Otherwise we couldn't use primitive types with read/write, since they
don't carry any location information by themselves.

>
> 	// `reg` encodes the value and an absolute location.
> 	let reg = bar.read(regs::NV_PMC_BOOT_0);
>
> 	// `reg` encodes the value and a relative location.
> 	let reg = bar.read(regs::NV_PFALCON_FALCON_RM::of::<E>());
>
> 	// First argument is an absolute location, second argument is a type
> 	// that encodes a value and a relative location.
> 	bar.write(regs::NV_PFALCON_FALCON_RM::of::<E>(), reg);
>
> 	// First argument is a base location that infers the relative location
> 	// from `reg`.
> 	bar.write(WithBase::of::<E>(), reg);
>
> And yes, I am aware that the above wording around the difference between
> regs::NV_PFALCON_FALCON_RM::of::<E>() and WithBase::of::<E>() is at least a bit
> vague technically, but my point is about how this appears to users.
>
> In any case, the fact that you can write WithBase::of::<E>() as a location
> argument in the first place proves that `reg` is not *only* a value.

But that is only true in the case of registers. The I/O module can and
does cover things other than registers - currently primitive values, but
we might want to extend that in future (don't ask me with what, but I
don't see a reason to close the possibility :)).

>
> 	fn write<T, L>(&self, location: L, value: T)
> 	where
> 	    L: IoLoc<T>,
> 	    Self: IoKnownSize + IoCapable<L::IoType>,
>
> Which is the reason why L: IoLoc<T>, i.e. the relative location is on T, not on
> L.
>
> So, what you could say is
>
>   - read() takes an absolute location and returns something that encodes a value
>     and relative location
>
>   - write() takes a base location (or absolute location) and something that
>     encodes a value and relative location
>
> But then there is the case with fixed registers that simply do not have a base,
> but write() still asks for a base (or absolute) location.
>
>> `write_val` is really nothing but a convenience shortcut that has
>> technically no strong reason to exist. As Gary pointed out, the
>> counterpart of
>>
>>     let reg = bar.read(regs::NV_PMC_BOOT_0);
>>
>> is
>>
>>     bar.write(regs::NV_PMC_BOOT_0, reg);
>
> I do not agree for the reasons mentioned above.
>
> In this case read() returns (location + value), while write() asks for location
> *and* (location + value), i.e. there is no base location for fixed registers.
>
>> ... and we introduced `write_val` for those cases where the value
>> in itself provides its location, as `NV_PMC_BOOT_0` is redundant. But
>> the above statement could also be written:
>>
>>     bar.write((), reg);
>
> This makes more sense, as one could argue that a fixed register still requires a
> base location, which is just always zero, but why would we bother users with
> this implementation detail?
>
> Is this really less confusing than an additional bar.write_reg(reg) that just
> works with any register?

I don't think it is less or more confusing, in the end they are really
equivalent.

What I would like to avoid is having register-specific functions spill
into the `io` module. I mean, I am not strictly opposed to it if we
reach the conclusion that it is more convenient to users - in this case
we could add an `impl Io` block in `register.rs` and add a `write_reg`
method (and possibly a `read` variant returning the full position
information?). But if we can just use the same 2 methods everywhere,
that's better IMHO.

>
>> which is exactly the same length as the `write_val` equivalent - it's
>> just that you need to remember that `()` can be used in this case. But
>> if you can remember that your register type can be used with
>> `write_val`, then why not this? This actually makes me doubt that
>> `write_val` is needed at all, and if we get rid of it, then we have a
>> symmetric API.
>
> Still not symmetric, and I also don't think we will have a lot of fun explaining
> people why they have to call it as bar.write((), reg). :(
>
> OOC, how would you explain it when the question is raised without arguing with
> implementation details?

This seems to indicate that instead of a `Io::write_val` method in `io.rs`,
we might need a `Io::write_reg` method in `register.rs` that is
dedicated to writing unambiguous registers exclusively. How does that
sound to you?

>
>> We were so focused on this single issue for the last few revisions that
>> the single-argument write variant sounded like the only way to handle
>> this properly, but the `()` use proposed by Gary actually fulfills the
>> same role and doesn't introduce more burden when you think of it.
>>
>> So why not try without `write_val` at first? We can always add it later
>> if we feel the need (and the same applies to a `(location, value)`
>> symmetric read/write API).
>
> If you really think it's the best solution, I'm fine picking it up this way for
> now, but to me it still sounds like we have no solution for a very simple case
> that does not at least raise an eyebrow.

I think the current `read` and `write` methods are going to stay the
basis of I/O, so I'm pretty confident we can commit to them. They also
allow to do everything we want to do with registers. So my suggestion
would be to see how it goes and add functionality as we get feedback and
more visibility into how the API is used.

After reading your reply I believe an `Io::write_reg` in `register.rs`
could solve the problem of writing fixed offset registers without making
a single-argument `write` part of the core I/O API (and save the trouble
of finding a generic-enough name for it!). It's just not clear to me
that we should add this right now - but I can of course do it in the
next revision if you think the idea is good.