Merge #319

319: backport CAN r=eldruin a=burrbull



Co-authored-by: Andrey Zgarbul <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+- Backport CAN interface from the upcoming 1.0 release.
+
 ## [v0.2.6] - 2021-08-03
 
 ### Added

src/blocking/can.rs

@@ -0,0 +1,17 @@
+//! Blocking CAN API
+
+/// A blocking CAN interface that is able to transmit and receive frames.
+pub trait Can {
+    /// Associated frame type.
+    type Frame: crate::can::Frame;
+
+    /// Associated error type.
+    type Error: crate::can::Error;
+
+    /// Puts a frame in the transmit buffer. Blocks until space is available in
+    /// the transmit buffer.
+    fn transmit(&mut self, frame: &Self::Frame) -> Result<(), Self::Error>;
+
+    /// Blocks until a frame was received or an error occured.
+    fn receive(&mut self) -> Result<Self::Frame, Self::Error>;
+}

src/blocking/mod.rs

@@ -4,6 +4,7 @@
 //! traits. To save boilerplate when that's the case a `Default` marker trait may be provided.
 //! Implementing that marker trait will opt in your type into a blanket implementation.
 
+pub mod can;
 pub mod delay;
 pub mod i2c;
 pub mod rng;

src/can/id.rs

@@ -0,0 +1,160 @@
+//! CAN Identifiers.
+
+/// Standard 11-bit CAN Identifier (`0..=0x7FF`).
+#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+pub struct StandardId(u16);
+
+impl StandardId {
+    /// CAN ID `0`, the highest priority.
+    pub const ZERO: Self = StandardId(0);
+
+    /// CAN ID `0x7FF`, the lowest priority.
+    pub const MAX: Self = StandardId(0x7FF);
+
+    /// Tries to create a `StandardId` from a raw 16-bit integer.
+    ///
+    /// This will return `None` if `raw` is out of range of an 11-bit integer (`> 0x7FF`).
+    #[inline]
+    pub fn new(raw: u16) -> Option<Self> {
+        if raw <= 0x7FF {
+            Some(StandardId(raw))
+        } else {
+            None
+        }
+    }
+
+    /// Creates a new `StandardId` without checking if it is inside the valid range.
+    ///
+    /// # Safety
+    /// Using this method can create an invalid ID and is thus marked as unsafe.
+    #[inline]
+    pub const unsafe fn new_unchecked(raw: u16) -> Self {
+        StandardId(raw)
+    }
+
+    /// Returns this CAN Identifier as a raw 16-bit integer.
+    #[inline]
+    pub fn as_raw(&self) -> u16 {
+        self.0
+    }
+}
+
+/// Extended 29-bit CAN Identifier (`0..=1FFF_FFFF`).
+#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+pub struct ExtendedId(u32);
+
+impl ExtendedId {
+    /// CAN ID `0`, the highest priority.
+    pub const ZERO: Self = ExtendedId(0);
+
+    /// CAN ID `0x1FFFFFFF`, the lowest priority.
+    pub const MAX: Self = ExtendedId(0x1FFF_FFFF);
+
+    /// Tries to create a `ExtendedId` from a raw 32-bit integer.
+    ///
+    /// This will return `None` if `raw` is out of range of an 29-bit integer (`> 0x1FFF_FFFF`).
+    #[inline]
+    pub fn new(raw: u32) -> Option<Self> {
+        if raw <= 0x1FFF_FFFF {
+            Some(ExtendedId(raw))
+        } else {
+            None
+        }
+    }
+
+    /// Creates a new `ExtendedId` without checking if it is inside the valid range.
+    ///
+    /// # Safety
+    /// Using this method can create an invalid ID and is thus marked as unsafe.
+    #[inline]
+    pub const unsafe fn new_unchecked(raw: u32) -> Self {
+        ExtendedId(raw)
+    }
+
+    /// Returns this CAN Identifier as a raw 32-bit integer.
+    #[inline]
+    pub fn as_raw(&self) -> u32 {
+        self.0
+    }
+
+    /// Returns the Base ID part of this extended identifier.
+    pub fn standard_id(&self) -> StandardId {
+        // ID-28 to ID-18
+        StandardId((self.0 >> 18) as u16)
+    }
+}
+
+/// A CAN Identifier (standard or extended).
+#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+pub enum Id {
+    /// Standard 11-bit Identifier (`0..=0x7FF`).
+    Standard(StandardId),
+
+    /// Extended 29-bit Identifier (`0..=0x1FFF_FFFF`).
+    Extended(ExtendedId),
+}
+
+impl From<StandardId> for Id {
+    #[inline]
+    fn from(id: StandardId) -> Self {
+        Id::Standard(id)
+    }
+}
+
+impl From<ExtendedId> for Id {
+    #[inline]
+    fn from(id: ExtendedId) -> Self {
+        Id::Extended(id)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn standard_id_new() {
+        assert_eq!(
+            StandardId::new(StandardId::MAX.as_raw()),
+            Some(StandardId::MAX)
+        );
+    }
+
+    #[test]
+    fn standard_id_new_out_of_range() {
+        assert_eq!(StandardId::new(StandardId::MAX.as_raw() + 1), None);
+    }
+
+    #[test]
+    fn standard_id_new_unchecked_out_of_range() {
+        let id = StandardId::MAX.as_raw() + 1;
+        assert_eq!(unsafe { StandardId::new_unchecked(id) }, StandardId(id));
+    }
+
+    #[test]
+    fn extended_id_new() {
+        assert_eq!(
+            ExtendedId::new(ExtendedId::MAX.as_raw()),
+            Some(ExtendedId::MAX)
+        );
+    }
+
+    #[test]
+    fn extended_id_new_out_of_range() {
+        assert_eq!(ExtendedId::new(ExtendedId::MAX.as_raw() + 1), None);
+    }
+
+    #[test]
+    fn extended_id_new_unchecked_out_of_range() {
+        let id = ExtendedId::MAX.as_raw() + 1;
+        assert_eq!(unsafe { ExtendedId::new_unchecked(id) }, ExtendedId(id));
+    }
+
+    #[test]
+    fn get_standard_id_from_extended_id() {
+        assert_eq!(
+            Some(ExtendedId::MAX.standard_id()),
+            StandardId::new((ExtendedId::MAX.0 >> 18) as u16)
+        );
+    }
+}

src/can/mod.rs

@@ -0,0 +1,123 @@
+//! Controller Area Network
+
+pub mod nb;
+
+mod id;
+
+pub use self::id::*;
+pub use self::nb::*;
+
+/// A CAN2.0 Frame
+pub trait Frame: Sized {
+    /// Creates a new frame.
+    ///
+    /// This will return `None` if the data slice is too long.
+    fn new(id: impl Into<Id>, data: &[u8]) -> Option<Self>;
+
+    /// Creates a new remote frame (RTR bit set).
+    ///
+    /// This will return `None` if the data length code (DLC) is not valid.
+    fn new_remote(id: impl Into<Id>, dlc: usize) -> Option<Self>;
+
+    /// Returns true if this frame is a extended frame.
+    fn is_extended(&self) -> bool;
+
+    /// Returns true if this frame is a standard frame.
+    fn is_standard(&self) -> bool {
+        !self.is_extended()
+    }
+
+    /// Returns true if this frame is a remote frame.
+    fn is_remote_frame(&self) -> bool;
+
+    /// Returns true if this frame is a data frame.
+    fn is_data_frame(&self) -> bool {
+        !self.is_remote_frame()
+    }
+
+    /// Returns the frame identifier.
+    fn id(&self) -> Id;
+
+    /// Returns the data length code (DLC) which is in the range 0..8.
+    ///
+    /// For data frames the DLC value always matches the length of the data.
+    /// Remote frames do not carry any data, yet the DLC can be greater than 0.
+    fn dlc(&self) -> usize;
+
+    /// Returns the frame data (0..8 bytes in length).
+    fn data(&self) -> &[u8];
+}
+
+/// CAN error
+pub trait Error: core::fmt::Debug {
+    /// Convert error to a generic CAN error kind
+    ///
+    /// By using this method, CAN errors freely defined by HAL implementations
+    /// can be converted to a set of generic serial errors upon which generic
+    /// code can act.
+    fn kind(&self) -> ErrorKind;
+}
+
+/// CAN error kind
+///
+/// This represents a common set of CAN operation errors. HAL implementations are
+/// free to define more specific or additional error types. However, by providing
+/// a mapping to these common CAN errors, generic code can still react to them.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
+pub enum ErrorKind {
+    /// The peripheral receive buffer was overrun.
+    Overrun,
+
+    // MAC sublayer errors
+    /// A bit error is detected at that bit time when the bit value that is
+    /// monitored differs from the bit value sent.
+    Bit,
+
+    /// A stuff error is detected at the bit time of the sixth consecutive
+    /// equal bit level in a frame field that shall be coded by the method
+    /// of bit stuffing.
+    Stuff,
+
+    /// Calculated CRC sequence does not equal the received one.
+    Crc,
+
+    /// A form error shall be detected when a fixed-form bit field contains
+    /// one or more illegal bits.
+    Form,
+
+    /// An ACK  error shall be detected by a transmitter whenever it does not
+    /// monitor a dominant bit during the ACK slot.
+    Acknowledge,
+
+    /// A different error occurred. The original error may contain more information.
+    Other,
+}
+
+impl Error for ErrorKind {
+    fn kind(&self) -> ErrorKind {
+        *self
+    }
+}
+
+impl core::fmt::Display for ErrorKind {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            ErrorKind::Overrun => write!(f, "The peripheral receive buffer was overrun"),
+            ErrorKind::Bit => write!(
+                f,
+                "Bit value that is monitored differs from the bit value sent"
+            ),
+            ErrorKind::Stuff => write!(f, "Sixth consecutive equal bits detected"),
+            ErrorKind::Crc => write!(f, "Calculated CRC sequence does not equal the received one"),
+            ErrorKind::Form => write!(
+                f,
+                "A fixed-form bit field contains one or more illegal bits"
+            ),
+            ErrorKind::Acknowledge => write!(f, "Transmitted frame was not acknowledged"),
+            ErrorKind::Other => write!(
+                f,
+                "A different error occurred. The original error may contain more information"
+            ),
+        }
+    }
+}

src/can/nb.rs

@@ -0,0 +1,28 @@
+//! Non-blocking CAN API
+
+/// A CAN interface that is able to transmit and receive frames.
+pub trait Can {
+    /// Associated frame type.
+    type Frame: crate::can::Frame;
+
+    /// Associated error type.
+    type Error: crate::can::Error;
+
+    /// Puts a frame in the transmit buffer to be sent on the bus.
+    ///
+    /// If the transmit buffer is full, this function will try to replace a pending
+    /// lower priority frame and return the frame that was replaced.
+    /// Returns `Err(WouldBlock)` if the transmit buffer is full and no frame can be
+    /// replaced.
+    ///
+    /// # Notes for implementers
+    ///
+    /// * Frames of equal identifier shall be transmited in FIFO fashion when more
+    ///   than one transmit buffer is available.
+    /// * When replacing pending frames make sure the frame is not in the process of
+    ///   being send to the bus.
+    fn transmit(&mut self, frame: &Self::Frame) -> nb::Result<Option<Self::Frame>, Self::Error>;
+
+    /// Returns a received frame if available.
+    fn receive(&mut self) -> nb::Result<Self::Frame, Self::Error>;
+}

src/lib.rs

@@ -691,6 +691,7 @@ extern crate void;
 
 pub mod adc;
 pub mod blocking;
+pub mod can;
 pub mod digital;
 pub mod fmt;
 pub mod prelude;