Struct CanFd 

pub struct CanFd<'d, Dm: DriverMode = Blocking> { /* private fields */ }

A CAN FD controller.

Implementations

impl<'d> CanFd<'d, Blocking>

pub fn set_interrupt_handler(&mut self, handler: InterruptHandler)

Available on crate feature unstable only.

Registers an interrupt handler for this controller.

Replaces any previously registered handler. The handler runs for the sources enabled with CanFd::listen. It must clear them with CanFd::clear_interrupts, or it runs again as soon as it returns.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn listen(&mut self, interrupts: impl Into<EnumSet<CanFdInterrupt>>)

Enables the given interrupt sources.

Without a handler from CanFd::set_interrupt_handler this only makes CanFd::interrupts record what happened.

pub fn unlisten(&mut self, interrupts: impl Into<EnumSet<CanFdInterrupt>>)

Disables the given interrupt sources.

pub fn interrupts(&self) -> EnumSet<CanFdInterrupt>

Returns the interrupt sources that are currently asserted.

pub fn clear_interrupts( &mut self, interrupts: impl Into<EnumSet<CanFdInterrupt>>, )

Clears the given interrupt sources.

pub fn new( twai: impl Instance + 'd, config: Config, ) -> Result<Self, ConfigError>

Creates a new CAN FD driver in Blocking mode.

The controller is configured but stays off the bus. Assign the pins with CanFd::with_rx and CanFd::with_tx, then call CanFd::start.

Errors

ConfigError when the configuration does not fit the hardware.

pub fn into_async(self) -> CanFd<'d, Async>

Converts the driver into an async driver.

impl<'d> CanFd<'d, Async>

pub async fn receive_async(&mut self) -> Frame

Waits until a frame is received, then reads it.

Cancellation Safety

This future is cancel-safe. A frame stays in the hardware RX buffer until it is read, so dropping the future loses nothing.

pub async fn transmit_async(&mut self, frame: &Frame) -> Result<(), Error>

Queues a frame and waits until the hardware finishes with it.

Errors

Error::ControllerStopped when the controller is not on the bus, and Error::NoFreeTxBuffer when every TX buffer is occupied; see CanFdTx::transmit.

Error::TransmitFailed when the controller gave up on the frame.

Error::TransmitAborted when the transmission was aborted.

Cancellation Safety

This future is not cancel-safe. Dropping it leaves the frame queued, and the hardware may still transmit it.

pub fn into_blocking(self) -> CanFd<'d, Blocking>

Converts the driver back into a blocking driver.

impl<'d, Dm: DriverMode> CanFd<'d, Dm>

pub fn with_rx(self, rx: impl PeripheralInput<'d>) -> Self

Assigns the RX pin.

The pin is driven according to Config::with_no_transceiver. That setting is committed to the hardware here and cannot change afterwards.

pub fn with_tx(self, tx: impl PeripheralOutput<'d>) -> Self

Assigns the TX pin.

With Config::with_no_transceiver set, the pin is driven open-drain with a pull-up. Assigning the same pin to CanFd::with_rx then forms a single-node bus that needs no external wiring. That setting is committed to the hardware here and cannot change afterwards.

pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError>

Applies a new configuration.

The controller leaves the bus while the configuration is applied. A running driver must be started again with CanFd::start afterwards. A change of clock source also stops a running timestamp counter, because its resolution is derived from that clock. Start it again with CanFd::start_timestamp_timer and use the resolution that it returns.

Errors

ConfigError when the configuration does not fit the hardware.

ConfigError::TransceiverModeLocked when the configuration changes Config::with_no_transceiver after a pin has been assigned.

pub fn config(&self) -> &Config

Returns the current configuration.

pub fn start(&mut self) -> Result<(), Error>

Joins the bus and waits for the controller to become error-active.

Follows the initialization sequence in TRM 38.3.5.

Errors

Error::BusIntegrationTimeout when the bus does not go idle-recessive long enough for the controller to join it. The controller stays off the bus in that case, unless it was on the bus before the call.

pub fn stop(&mut self) -> Result<(), Error>

Leaves the bus, following the de-initialization sequence in TRM 38.3.6.

Every TX buffer returns to the empty state without its memory being cleared, and the RX buffer is flushed.

While the controller is on the bus, the driver holds a WakeLock, because Light-sleep mode gates the function clock. Leaving the bus releases the lock. A running timestamp counter does not advance during sleep.

Errors

Error::AbortTimeout when a transmission does not settle. The controller stays on the bus in that case.

pub fn is_started(&self) -> bool

Returns whether the controller is on the bus.

This is true between a successful CanFd::start and the next CanFd::stop or CanFd::apply_config.

pub fn identity(&self) -> Identity

Returns the identity of the core.

pub fn function_clock_frequency(&self) -> u32

Returns the frequency of the controller’s function clock, in Hz.

pub fn split(&mut self) -> (CanFdRx<'_, Dm>, CanFdTx<'_, Dm>)

Splits the controller into a receiving and a transmitting half.

The two halves can be used at the same time, for example to wait for a frame while a transmission is in flight. They arm different interrupt sources, so neither disturbs the other.

The halves borrow the driver, which keeps the configuration and the teardown: everything that reconfigures the controller or takes it off the bus stays on CanFd and is unavailable while a half is alive. For two independent tasks, split a driver that lives in a static.

pub fn tx_buffer_count(&self) -> u8

Returns the number of TX buffers the hardware provides.

pub fn transmit(&mut self, frame: &Frame) -> Result<u8, Error>

Queues a frame in the first free TX buffer and arms it.

Returns the index of the buffer used. The hardware chooses the order in which armed buffers are sent, not the order in which they were queued; see CanFdTx::transmit.

Errors

Error::ControllerStopped when the controller is not on the bus, and Error::NoFreeTxBuffer when every TX buffer is occupied; see CanFdTx::transmit.

pub fn tx_buffer_state(&self, index: u8) -> TxBufferState

Returns the state of one TX buffer.

Returns TxBufferState::NotExist for an index the hardware does not have.

pub fn abort_transmit(&mut self, index: u8)

Requests that a queued transmission be aborted.

The buffer moves to “aborted”, or to “abort in progress” if the frame is already on the wire. Does nothing for an index the hardware does not have.

pub fn release_tx_buffer(&mut self, index: u8)

Returns a TX buffer to the empty state, releasing it for reuse.

Does nothing for an index the hardware does not have.

pub fn set_tx_priority(&mut self, index: u8, priority: u8)

Sets a TX buffer’s arbitration priority.

Higher values win, and a value above MAX_TX_PRIORITY counts as that maximum; see CanFdTx::set_tx_priority.

pub fn rx_frame_count(&self) -> u16

Returns the number of complete frames waiting in the RX buffer.

pub fn receive(&mut self) -> Result<Frame, Error>

Reads one frame from the RX buffer.

Errors

Error::RxBufferEmpty when no complete frame is waiting.

pub fn flush_rx(&mut self)

Discards everything in the RX buffer.

pub fn rx_buffer_size_words(&self) -> u16

Returns the size of the RX buffer in 32-bit words.

pub fn rx_buffer_free_words(&self) -> u16

Returns the free space in the RX buffer in 32-bit words.

pub fn rx_overrun(&self) -> bool

Returns whether the RX buffer has overrun and dropped a frame (TRM 38.3.9.4).

pub fn clear_rx_overrun(&mut self)

Clears the RX buffer overrun flag.

pub fn error_state(&self) -> ErrorState

Returns the current fault confinement state.

Returns ErrorState::BusOff while the controller is off the bus, both before the first CanFd::start and after CanFd::stop; that is how the hardware reports a disabled controller. CanFd::is_started tells the two apart.

pub fn error_warning(&self) -> bool

Returns whether an error counter has reached the error warning limit.

A node at the limit is still ErrorState::Active (TRM 38.3.10).

pub fn receive_error_count(&self) -> u16

Returns the receive error counter.

pub fn transmit_error_count(&self) -> u16

Returns the transmit error counter.

pub fn request_bus_off_recovery(&mut self)

Requests that a bus-off controller rejoin the bus; see CanFdTx::request_bus_off_recovery.

pub fn set_error_warning_limit(&mut self, limit: u8) -> Result<(), Error>

Sets the error warning limit, which defaults to 96.

The hardware only accepts the write in test mode (TRM 38.3.10), which is entered for the write and left again.

Errors

Error::ControllerRunning when the controller is still on the bus.

pub fn reset_traffic_counters(&mut self)

Resets the received and transmitted frame counters.

pub fn rx_traffic_count(&self) -> u32

Returns the number of frames received since the traffic counters were last reset.

pub fn tx_traffic_count(&self) -> u32

Returns the number of frames transmitted since the traffic counters were last reset.

pub fn set_mask_filter(&mut self, filter: MaskFilter, config: &MaskFilterConfig)

Configures one mask filter and enables it.

A frame reaches the RX buffer if it passes at least one enabled filter (TRM 38.3.9.8). Out of reset, filter A accepts every frame; see CanFd::accept_all.

pub fn disable_mask_filter(&mut self, filter: MaskFilter)

Disables one mask filter.

pub fn set_range_filter(&mut self, config: &RangeFilterConfig)

Configures the range filter and enables it.

pub fn disable_range_filter(&mut self)

Disables the range filter.

pub fn accept_all(&mut self)

Accepts every frame, by giving filter A a zero mask and disabling the rest.

This is the one filter setting that matches standard and extended identifiers at once.

pub fn error_capture(&self) -> ErrorCapture

Returns details of the last bus error the core captured.

Only meaningful after the core has reported a bus error; see ErrorCapture.

pub fn retransmit_count(&self) -> u8

Returns the number of retransmission attempts made for the frame currently being sent.

pub fn nominal_error_count(&self) -> u16

Returns the number of errors detected at the nominal bit rate.

pub fn fd_error_count(&self) -> u16

Returns the number of errors detected at the data bit rate, in the data phase of bit-rate-switched frames.

pub fn transmitter_delay(&self) -> u8

Returns the transmitter delay the core measured, in function clock periods.

The core measures the delay during every FD frame it sends (TRM 38.3.7.2), so the value reads zero until the first one. The secondary sample point sits at this delay plus the configured offset, and the four-bit-time limit of TRM 38.3.7.3 applies to that sum.

pub fn start_timestamp_timer( &mut self, resolution_hz: u32, ) -> Result<u32, ConfigError>

Starts the timestamp counter from zero, at the requested resolution.

Received frames are stamped at the sixth bit of their end-of-frame field, which is when a frame becomes valid. The achievable resolution is the function clock divided by an integer, so the returned value is the resolution actually programmed, in Hz.

Errors

ConfigError::UnsupportedTimestampResolution when the resolution cannot be reached from the function clock.

ConfigError::TimestampTimerStalled when the counter does not start.

pub fn stop_timestamp_timer(&mut self)

Stops the timestamp counter.

pub fn timestamp(&self) -> u64

Returns the current value of the timestamp counter.

pub fn timestamp_bit_width(&self) -> u8

Returns the width of the timestamp counter in bits.

Trait Implementations

impl<Dm: DriverMode> Debug for CanFd<'_, Dm>

Available on crate feature unstable only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl InterruptConfigurable for CanFd<'_, Blocking>

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn set_interrupt_handler(&mut self, handler: InterruptHandler)

Registers an interrupt handler for the peripheral.