Controller Area Network (CAN) Take 4 by timokroeger · Pull Request #314 · rust-embedded/embedded-hal

timokroeger · 2021-09-22T18:01:01Z

Updated to the latest HAL changes:

Removed try_ prefix
Moved non-blocking implementation to nb module
Removed default blocking implementaions

Usage Example

stm32-fwupdate

Implementations

Updated for this PR:

pcan-basic on top of an existing software API
bxcan

Based on the very similar predecessor traits embedded-can v0.3 (diff v0.3 -> this PR)

candev implementing the traits for linux SocketCAN
socketcan-isotc

Previous Discussion

rust-highfive · 2021-09-22T18:01:04Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @therealprof (or someone else) soon.

Please see the contribution instructions for more information.

adamgreig · 2021-09-28T16:55:30Z

This looks good to me! I have a couple of thoughts but apologies if they've already been discussed in the previous threads...

Does new_unchecked actually need to be unsafe, i.e. might any memory safety rely on it later?
For CAN, might it make more sense to call it transmit and receive in both the blocking and nb traits, rather than read and write in blocking?
I saw you mentioned this on the old PR thread but it does seem like it would be nice to add some error types to Add error traits for communication interfaces #296 for things like invalid ID or data-too-long.
Could you add a CHANGELOG entry?

therealprof

@timokroeger If you could resolve the merge conflict, this seems to be ready to merge to us.

eldruin · 2021-10-19T18:25:36Z

We agreed this is ready for merge. Could you rebase/resolve the conflict @timokroeger ?

Invalid CAN identifiers are still memory safe.

The blocking traits borrowed the naming convention from socketcan. Rename the methods to `transmit()` and `receive()` to make them consistent with the `nb` traits.

timokroeger · 2021-10-20T14:01:13Z

Rebased to resolve the changelog conflict. The PR is ready to be merged.

eldruin · 2021-10-21T07:53:44Z

The MSRV would need to be raised to Rust 1.46.0 in order to keep the StandardId::new as a const function.
Raising the MSRV would be fine with me.

andresv · 2021-10-22T13:45:36Z

Just in right time. I would like to use it in https://github.com/esp-rs/esp-idf-hal.

andresv · 2021-10-25T12:03:08Z

Is anybody opposing increasing MSRV to 1.46 to get this over finish line?

eldruin · 2021-10-25T12:17:35Z

Opinions @therealprof, @ryankurte ?

Rahix · 2021-10-25T12:41:17Z

+
+    /// Creates a new `StandardId` without checking if it is inside the valid range.
+    #[inline]
+    pub const fn new_unchecked(raw: u16) -> Self {


Does new_unchecked() actually need to be unsafe, i.e. might any memory safety rely on it later?

I'd actually argue that yes, it must be an unsafe function. Implementations and users of the traits should be able to rely on StandardId/ExtendedId always containing a valid ID. In my opinion, that's the entire point of using such wrapper types in the first place (ref "Parse, don't validate"). "Relying on" should then mean that even writing unsafe code based on this assumption should be possible - without the need for additional validation of the passed IDs.

Hmm, for StandardId it is not marked as unsafe but for ExtendedId it is:

embedded-hal/src/can/id.rs

Lines 62 to 66 in 6b3820e

/// Creates a new `ExtendedId` without checking if it is inside the valid range.

#[inline]

pub const unsafe fn new_unchecked(raw: u32) -> Self {

Self(raw)

}

The unsafe on ExtendedId was an oversight, pushed a fix.

IMO both perspectives on the unsafe are appropriate here. Are there any "unsafe API guidelines" which could help us find a decision?

My reasoning for functions needing to be unsafe is as follows: As soon as there exists a way to create an instance of StandardId containing an invalid ID from safe Rust, any possible downstream code which wants to rely on it containing a valid ID must add its own validation checks to ensure that it does. The is necessary for logic purposes and UB-purposes alike.

If, however, the API "contract" of the StandardId type is to only ever contain a valid ID and from safe Rust only abiding instances can be created, then downstream code can rely on this guarantee. Again, this is useful for logic reasons and UB avoidance alike.

As an example from the Rust stdlib, from_utf8_unchecked() is also unsafe. The reason is that some code handling strs downstream might want to optimize on the guarantee that str always contains valid UTF-8 data. Analogous, a CAN peripheral driver might want to optimize on the assumption that the u16 representing an ID will only ever have some of its lower 13 bits set. By keeping these functions safe, we're disallowing any such downstream code to be sound without additional code for validation.

Asking the other way around: What is gained from making these functions safe in the first place? For statically initializing a variable of type StandardId, it is irrelevant: The check in ::new() will be constant-folded away in probably all conceivable cases. The only place where ::new_unchecked() is really needed is when an ID is dynamically retrieved from elsewhere and you can guarantee that it has already been validated before. And even then, it is only relevant for edge-cases where the last bytes of memory and cycles of CPU time need to be optimized.

I agree with @Rahix. It seems *_unchecked() APIs are typically marked as unsafe in rust std lib and also for example in heapless.

Are those CAN traits going to be in v1.0?

I am generally against marking functions as unsafe unless they actually lead to UB, and especially against doing it just because they seem like "scary" functions or some extra care (unrelated to UB) is required. In this case though I think @Rahix is right: the list of Rust UB explicitly includes "Producing an invalid value... The following values are invalid: Invalid values for a type with a custom definition of invalid values".

So, if we do reasonably define this type as only containing valid IDs, then it's right to say producing an invalid valid could cause UB, if some other code later depended on this property in order to be sound. I can't think of any such situations but I guess they could exist.

What if we just remove new_unchecked() for now?

One downside is that using unwrap and expect introduces format bloat and makes binaries bigger and in this case there is also a little performance hit by always checking those values.

let canid = read_can(); let id = ExtendedId::new(canid).expect("always valid"); vs let id = unsafe { ExtendedId::new_unchecked(canid) };

Invalid CAN identifiers are still memory safe.

ryankurte

lgtm, MSRV bump seems fine to me, and real excited to try this...

thanks everyone for the huuge effort in prior PRs and to get this over the line!

This reverts commit b2d00d1 and 31eabd5. Mark the constructor as unsafe again to prevent UB in safe code that assumes the CAN IDs to contain valid data. This is in line with functions like `from_utf8_unchecked()` from the std library.

eldruin

@timokroeger Could you also do the following?

Add a couple of unit tests for the functions that have an implementation.
Raise the MSRV to 1.46.0

therealprof · 2021-10-26T18:14:57Z

Looks good to me as well. 👍🏻

chemicstry · 2021-10-27T14:30:15Z

A bit late, but what about the timestamp API, which was proposed in earlier PR? I would like to use this for UAVCAN, which needs timestamp support.

I guess it can also be added later as a non breaking change to not block this merge with discussions on wether to use embedded-time.

andresv · 2021-10-27T14:36:42Z

rtic folks found that embedded-time moves too slowly is too complicated and tries to do too much, therefore korken89 created https://github.com/korken89/const-embedded-time which is not yet released.

It would be better if timestamp API is added later. It might take a lot of time to figure out what is the best way for that.

ryankurte · 2021-10-27T21:22:39Z

I guess it can also be added later as a non breaking change to not block this merge with discussions on wether to use embedded-time.

It would be better if timestamp API is added later. It might take a lot of time to figure out what is the best way for that.

yep, definitely a few other dependencies so we won't include this here. feel free to open a new issue / PR to discuss this ^_^

eldruin

Alright, let's get this merged. I will add the couple of unit tests in a separate PR.
Thank you @timokroeger for your work!
Thank you as well to everybody else involved in all the previous PRs and discussions!

bors merge

bors · 2021-10-28T06:08:37Z

Build succeeded:

burrbull · 2021-10-28T06:13:42Z

Should we backport this to 0.2?

eldruin · 2021-10-28T06:31:42Z

This could be backported if there is interest. We would need to remove the const in the const fns and see if there are other things that do not build with Rust 1.31.0.

andresv · 2021-10-28T06:37:06Z

I guess it also depends on when 1.0 is going to be released. If this happens rather quickly then I think it is not needed to backport it. We actually want that 1.0 is adopted and all the stuff is updated from 0.2 to 1.0.
Otherwise we have python 2 vs 3 situation.

burrbull · 2021-10-28T07:07:44Z

I guess it also depends on when 1.0 is going to be released. If this happens rather quickly then I think it is not needed to backport it. We actually want that 1.0 is adopted and all the stuff is updated from 0.2 to 1.0. Otherwise we have python 2 vs 3 situation.

Sure. But we need several implementations to be sure all work as expected before stabilize in 1.0. I see 0.2 as test playground, not alternative implementaion. Nothing similar to python2/3.

timokroeger requested a review from a team as a code owner September 22, 2021 18:01

rust-highfive assigned therealprof Sep 22, 2021

rust-highfive added S-waiting-on-review Review is incomplete T-hal labels Sep 22, 2021

eldruin reviewed Oct 5, 2021

View reviewed changes

Comment thread src/can/mod.rs Outdated

therealprof previously approved these changes Oct 19, 2021

View reviewed changes

timokroeger added 7 commits October 20, 2021 15:58

Traits for CAN (Controller Area Network)

7558350

can: Make Id::new_unchecked() safe

b2d00d1

Invalid CAN identifiers are still memory safe.

can: Rename blocking methods

5f8ed23

The blocking traits borrowed the naming convention from socketcan. Rename the methods to `transmit()` and `receive()` to make them consistent with the `nb` traits.

can: Add error traits like rust-embedded#296

5f7cd3b

can: Changelog entry

402f1cf

can: Add Other error kind

6a6ad3f

can: Rename 'Ack' error to 'Acknowledge'

6b3820e

timokroeger dismissed therealprof’s stale review via 6b3820e October 20, 2021 13:59

timokroeger force-pushed the can-take-4 branch from e8852cb to 6b3820e Compare October 20, 2021 13:59

Rahix reviewed Oct 25, 2021

View reviewed changes

can: Make ExtendedId::new_unchecked() safe

31eabd5

Invalid CAN identifiers are still memory safe.

ryankurte previously approved these changes Oct 25, 2021

View reviewed changes

Revert "can: Make new_unchecked() safe"

1f43e5d

This reverts commit b2d00d1 and 31eabd5. Mark the constructor as unsafe again to prevent UB in safe code that assumes the CAN IDs to contain valid data. This is in line with functions like `from_utf8_unchecked()` from the std library.

timokroeger dismissed ryankurte’s stale review via 1f43e5d October 26, 2021 09:31

eldruin reviewed Oct 26, 2021

View reviewed changes

Raise MSRV to Rust 1.46.0

7387323

ryankurte approved these changes Oct 26, 2021

View reviewed changes

andresv approved these changes Oct 27, 2021

View reviewed changes

eldruin approved these changes Oct 28, 2021

View reviewed changes

bors Bot merged commit 45d3170 into rust-embedded:master Oct 28, 2021

This was referenced Oct 28, 2021

added a HAL for CAN interfaces #53

Closed

Controller Area Network (CAN) Take 3 #212

Closed

This was referenced Oct 29, 2021

[WIP] CAN Interface take 2 #77

Closed

CAN/CAN-FD API? #21

Closed

adamgreig mentioned this pull request Nov 11, 2021

FDCAN issues stm32-rs/stm32g4xx-hal#34

Closed

	/// Creates a new `ExtendedId` without checking if it is inside the valid range.
	#[inline]
	pub const unsafe fn new_unchecked(raw: u32) -> Self {
	Self(raw)
	}

Conversation

timokroeger commented Sep 22, 2021

Usage Example

Implementations

Previous Discussion

Uh oh!

rust-highfive commented Sep 22, 2021

Uh oh!

adamgreig commented Sep 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

therealprof left a comment

Choose a reason for hiding this comment

Uh oh!

eldruin commented Oct 19, 2021

Uh oh!

timokroeger commented Oct 20, 2021

Uh oh!

eldruin commented Oct 21, 2021

Uh oh!

andresv commented Oct 22, 2021

Uh oh!

andresv commented Oct 25, 2021

Uh oh!

eldruin commented Oct 25, 2021

Uh oh!

Rahix Oct 25, 2021

Choose a reason for hiding this comment

Uh oh!

andresv Oct 25, 2021

Choose a reason for hiding this comment

Uh oh!

timokroeger Oct 25, 2021

Choose a reason for hiding this comment

Uh oh!

timokroeger Oct 25, 2021

Choose a reason for hiding this comment

Uh oh!

Rahix Oct 25, 2021

Choose a reason for hiding this comment

Uh oh!

andresv Oct 25, 2021

Choose a reason for hiding this comment

Uh oh!

adamgreig Oct 26, 2021

Choose a reason for hiding this comment

Uh oh!

andresv Oct 26, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryankurte left a comment

Choose a reason for hiding this comment

Uh oh!

eldruin left a comment

Choose a reason for hiding this comment

Uh oh!

therealprof commented Oct 26, 2021

Uh oh!

chemicstry commented Oct 27, 2021

Uh oh!

andresv commented Oct 27, 2021

Uh oh!

ryankurte commented Oct 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eldruin left a comment

Choose a reason for hiding this comment

Uh oh!

bors Bot commented Oct 28, 2021

Uh oh!

burrbull commented Oct 28, 2021

Uh oh!

eldruin commented Oct 28, 2021

Uh oh!

andresv commented Oct 28, 2021

Uh oh!

burrbull commented Oct 28, 2021

Uh oh!

adamgreig commented Sep 28, 2021 •

edited

Loading

andresv Oct 26, 2021 •

edited

Loading

ryankurte commented Oct 27, 2021 •

edited

Loading