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

["Gary Guo" <gary@garyguo.net>]

On Wed Mar 11, 2026 at 2:56 PM GMT, 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.

The value returned by `read` does not encode relative location. If a primitive
is returned (of course, this is not currently supported by the `register!`
macro) for the FIFO register case, the returned integer has no location
informaiton whatsoever. What encodes the relative location is the type itself.

If you just construct the value yourself without using `read`, you can also use
`write_val` or `bar.write(WithBase...)`.

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

The latter is just a type inferred version of the former, to avoid having you to
write the name twice. They're exactly the same.

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

Not true as discussed above.

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

The location has nothing to do with `value`, just the type `T`.

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

Only `location` gives you the location. Value has nothing to do with locations at all. Type
inference does the trick.

Best,
Gary

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