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

[Danilo Krummrich]

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.

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.

	// `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.

	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?

> 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?

> 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.

> And most importantly, that way we also don't have to worry about its
> name. :)