tock-register-interface: Provide `none` method for FieldValue type. #3013

qwandor · 2022-04-05T18:12:18Z

Pull Request Overview

Default is useful to construct a FieldValue which can be passed to
modify as a no-op or used as an additive identity when combining other
FieldValues.

Eq and PartialEq are useful for assertions in testing.

Testing Strategy

This pull request was tested by cargo test.

Documentation Updated

Updated the relevant files in /docs, or no updates are required.

Formatting

Ran make prepush.

Default is useful to construct a FieldValue which can be passed to `modify` as a no-op or used as an additive identity when combining other FieldValues. Eq and PartialEq are useful for assertions in testing.

lschuermann · 2022-04-06T04:47:51Z

I don't see the benefit of having a first-class additive identity for FieldValues in mind. Do you have a particular usecase? I'm hesitant, as it might not be immediately clear that a default FieldValue is not just some zero-value, but in fact has a zero mask.

Also, I'm not convinced we should make FieldValue comparable. Given this implicitly compares both the mask and value, it combines two fundamentally distinct operations into a single, opaque and undocumented one. As a user, I could for instance think that the implementation would instead check that the values contained with two FieldValues are identical, compensating for any shift. As we already have the enum abstraction, can we just use that for comparing a given field's value instead (i.e. add #[derive(Eq)])? This has the field encoded in the type information instead.

qwandor · 2022-04-06T11:45:14Z

There are several usecases I see for Default.

Setting all fields in a register to 0 in a type-safe way, like

registers.reg.write(REG::default());

(Yes, I realise you could just use registers.reg.set(0), but I'd rather set expose the raw setters. In my actual code I have a wrapper around write.)

Accumulating a series of updates to make in one go, like

let mut field_values = REG::default();

if some_condition {
  field_values += REG::FIELD::SET;
}

if some_other_condition {
  field_values += REG::OTHER_FIELD::SET;
}

registers.reg.modify(field_values);

As for Eq, I mostly had in mind using it for testing, so I could use assert_eq! with values passed to a mock, but it's less important to me right now.

Derive Copy, Clone, Eq and PartialEq for generated field value enums.

lschuermann · 2022-04-06T16:06:56Z

Okay, I see the benefit of having a default implementation for FieldValues now. I'm not super happy with the name still, as it's not immediately clear what "default" implies. Especially for memory-mapped registers, default is a common phrase to refer to the reset-values of a given register, which aren't necessarily zero. It seems entirely reasonable and super useful for some cases to introduce custom register types which have a proper const-generic default value attached to them, representing the reset value of this register, and perhaps also a mask of writeable vs. reserved bits. In that spirit, would it perhaps be better to call this associated function none or empty?

qwandor · 2022-04-06T17:33:17Z

Implementing the Default trait has the advantage that it can then be derived on containing structs (i.e. if I make a struct that contains a FieldValue), and also seems more idiomatic to me, but a none or empty method would work for my immediate usecase. I think none is probably a better name than empty as it represents modifying none of the fields.

alistair23 · 2022-04-07T06:24:07Z

I agree, Default implies the reset value so none of empty seem like better names

hudson-ayers · 2022-04-07T07:29:21Z

I might even recommend zeroed(), though I think none or empty are fine as well

qwandor · 2022-04-07T15:40:17Z

Done. zeroed sounds to me like it would result in setting some fields to 0, which is not what this does, so I've gone with none.

lschuermann · 2022-04-08T08:00:38Z

As for Eq, I mostly had in mind using it for testing, so I could use assert_eq! with values passed to a mock, but it's less important to me right now.

Could you perhaps remove this change from this PR? I'm still not 100% convinced on that and it seems it wouldn't be a major inconvenience to you to just compare the mask and the read value (in conjuction with the corresponding Field type), if this matches your definition of equality?

As requested in code review.

Code reviewers don't like it.

qwandor · 2022-04-08T11:33:21Z

Done.

lschuermann · 2022-04-09T13:38:03Z

bors r+

bors · 2022-04-09T13:57:40Z

Build succeeded:

`tock-registers` now supports stable Rust! There is a small breaking change, documented below, required to support Rust 2021 edition. Most of the remaining changes are improvements to the internal self-testing infrastructure and documentation. There are also some additions to `FieldValue` to improve ergonomics. **Breaking Changes** - #2842: tock-registers: rename TryFromValue::try_from to try_from_value - #2833: Update to Rust 2021 edition Other Changes - #3126: [trivial] tock-registers: mark two methods as `const` - #3088: tock_registers/test_fields: respect struct size padding w/ alignment - #3072: Update Rust nightly version + Expose virtual-function-elimination - libraries/tock-register-interface: Fixup register_structs documentation - #2988: Remove const_fn_trait_bound feature and update nightly (Mar 2022) - #3014: tock-registers: Implement From field enum value type for FieldValue - #3013: tock-register-interface: Provide none method for FieldValue type - #2916: tock-register-interface: improve read_as_enum documentation - #2922: tock-register-interface: replace register tests by const assertions

`tock-registers` now supports stable Rust! There is a small breaking change, documented below, required to support Rust 2021 edition. Most of the remaining changes are improvements to the internal self-testing infrastructure and documentation. There are also some additions to `FieldValue` to improve ergonomics. **Breaking Changes** - #2842: tock-registers: rename TryFromValue::try_from to try_from_value - #2838: Update to Rust 2021 edition Other Changes - #3126: [trivial] tock-registers: mark two methods as `const` - #3088: tock_registers/test_fields: respect struct size padding w/ alignment - #3072: Update Rust nightly version + Expose virtual-function-elimination - libraries/tock-register-interface: Fixup register_structs documentation - #2988: Remove const_fn_trait_bound feature and update nightly (Mar 2022) - #3014: tock-registers: Implement From field enum value type for FieldValue - #3013: tock-register-interface: Provide none method for FieldValue type - #2916: tock-register-interface: improve read_as_enum documentation - #2922: tock-register-interface: replace register tests by const assertions

3151: tock-registers: release v0.8 r=lschuermann a=ppannuto ### Pull Request Overview Prepare a v0.8 release of tock-registers. Fixes #2982. --- `tock-registers` now supports stable Rust! There is a small breaking change, documented below, required to support Rust 2021 edition. Most of the remaining changes are improvements to the internal self-testing infrastructure and documentation. There are also some additions to `FieldValue` to improve ergonomics. **Breaking Changes** - #2842: tock-registers: rename TryFromValue::try_from to try_from_value - #2838: Update to Rust 2021 edition Other Changes - #3126: [trivial] tock-registers: mark two methods as `const` - #3088: tock_registers/test_fields: respect struct size padding w/ alignment - #3072: Update Rust nightly version + Expose virtual-function-elimination - libraries/tock-register-interface: Fixup register_structs documentation - #2988: Remove const_fn_trait_bound feature and update nightly (Mar 2022) - #3014: tock-registers: Implement From field enum value type for FieldValue - #3013: tock-register-interface: Provide none method for FieldValue type - #2916: tock-register-interface: improve read_as_enum documentation - #2922: tock-register-interface: replace register tests by const assertions ### Testing Strategy N/A ### TODO or Help Wanted N/A ### Documentation Updated - [x] Updated the relevant files in `/docs`, or no updates are required. ### Formatting - [ ] Ran `make prepush`. Co-authored-by: Pat Pannuto <[email protected]>

github-actions bot added the tock-libraries This affects libraries supported by the Tock project label Apr 5, 2022

tock-registers: Derive Default, Eq and PartialEq for FieldValue.

fd5687d

Default is useful to construct a FieldValue which can be passed to `modify` as a no-op or used as an additive identity when combining other FieldValues. Eq and PartialEq are useful for assertions in testing.

qwandor force-pushed the fieldvaluetraits branch from 3755003 to fd5687d Compare April 5, 2022 19:26

tock-registers: Derive traits for field value enums too.

1e0d46b

Derive Copy, Clone, Eq and PartialEq for generated field value enums.

alistair23 previously approved these changes Apr 7, 2022

View reviewed changes

qwandor added 2 commits April 8, 2022 12:30

tock-registers: Add none method rather than implementing Default.

07a1b45

As requested in code review.

tock-registers: Don't derive PartialEq for FieldValue after all.

bbc58e6

Code reviewers don't like it.

qwandor dismissed alistair23’s stale review via bbc58e6 April 8, 2022 11:32

qwandor force-pushed the fieldvaluetraits branch from e6e4a3a to bbc58e6 Compare April 8, 2022 11:32

lschuermann approved these changes Apr 8, 2022

View reviewed changes

bradjc approved these changes Apr 8, 2022

View reviewed changes

brghena approved these changes Apr 8, 2022

View reviewed changes

hudson-ayers approved these changes Apr 8, 2022

View reviewed changes

lschuermann changed the title ~~Derive Default, Eq and PartialEq for FieldValue.~~ tock-register-interface: Provide none method for FieldValue type. Apr 9, 2022

bors bot merged commit da015b6 into tock:master Apr 9, 2022

ppannuto mentioned this pull request Aug 19, 2022

tock-registers: release v0.8 #3151

Merged

2 tasks

ppannuto mentioned this pull request Sep 1, 2022

Release 2.1 Breaking Changes and Release Notes #3141

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

tock-register-interface: Provide `none` method for FieldValue type. #3013

tock-register-interface: Provide `none` method for FieldValue type. #3013

Uh oh!

qwandor commented Apr 5, 2022

Uh oh!

lschuermann commented Apr 6, 2022

Uh oh!

qwandor commented Apr 6, 2022

Uh oh!

lschuermann commented Apr 6, 2022

Uh oh!

qwandor commented Apr 6, 2022

Uh oh!

alistair23 commented Apr 7, 2022

Uh oh!

hudson-ayers commented Apr 7, 2022

Uh oh!

qwandor commented Apr 7, 2022

Uh oh!

lschuermann commented Apr 8, 2022

Uh oh!

qwandor commented Apr 8, 2022

Uh oh!

lschuermann commented Apr 9, 2022

Uh oh!

bors bot commented Apr 9, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

tock-register-interface: Provide none method for FieldValue type. #3013

tock-register-interface: Provide none method for FieldValue type. #3013

Uh oh!

Conversation

qwandor commented Apr 5, 2022

Pull Request Overview

Testing Strategy

Documentation Updated

Formatting

Uh oh!

lschuermann commented Apr 6, 2022

Uh oh!

qwandor commented Apr 6, 2022

Uh oh!

lschuermann commented Apr 6, 2022

Uh oh!

qwandor commented Apr 6, 2022

Uh oh!

alistair23 commented Apr 7, 2022

Uh oh!

hudson-ayers commented Apr 7, 2022

Uh oh!

qwandor commented Apr 7, 2022

Uh oh!

lschuermann commented Apr 8, 2022

Uh oh!

qwandor commented Apr 8, 2022

Uh oh!

lschuermann commented Apr 9, 2022

Uh oh!

bors bot commented Apr 9, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

tock-register-interface: Provide `none` method for FieldValue type. #3013

tock-register-interface: Provide `none` method for FieldValue type. #3013