can_utils/
frames.rs

1//! The `frames` module houses various CAN frame representations.
2//!
3//! Regular CAN is a very low level technology (OSI layers 1 and 2), and as such there's a need for
4//! data representations that don't impose usage patterns on the user (since hardware needs vary).
5//! But at the same time, one of Rusts great strengths is its type system and most Rustaceans
6//! prefer more type level sanity checks.  This module contains frame representations that cater
7//! to both use cases, as well as easy (and cheap) layers to convert between them.
8
9/// A low level representation of the frames that might be sent and received on a CAN bus.
10///
11/// This struct can represent any CAN frame, as described in the CAN specification
12/// version 2.0, published September 1991 by Bosch GmbH.  They can be used for either
13/// transmission or reception.
14pub struct CanFrame {
15  /// This contains either the Base Identifier or the Extended Identifier, depending on `ide`.
16  pub id: u32,
17  /// Number of bytes in the payload.
18  pub dlc: u8,
19  /// The frame's data payload, only the first `dlc` bytes are valid.
20  pub data: [u8; 8],
21  /// True iff this frame is a Remote Transmission Request.
22  pub rtr: bool,
23  /// True iff the id field is extended (ie 29 bits long, as opposed to 11).
24  pub ide: bool,
25  /// At the time of this writing this field isn't specified, but it can be received as either
26  /// value and subsequent protocols may end up using it.
27  pub reserved0: bool,
28  /// At the time of this writing this field isn't specified, but it can be received as either
29  /// value and subsequent protocols may end up using it.
30  pub reserved1: bool,
31}
32
33/// A low level representation of the frames that might be sent and received on a CAN FD bus.
34///
35/// This struct can represent any CAN FD frame, as described in the CAN FD specification
36/// version 1.0, published April 2012 by Bosch GmbH.  They can be used for either
37/// transmission or reception.
38pub struct CanFdFrame {
39  /// This contains either the Base Identifier or the Extended Identifier, depending on `ide`.
40  pub id: u32,
41  /// Number of bytes in the payload.
42  ///
43  /// # Note
44  /// This is *not* the DLC field value, this is the number of bytes of payload in the frame,
45  /// in CAN FD those are not the same thing, but the implementation of this HAL should hide that
46  /// from you.
47  pub data_length: u8,
48  /// The frame's data payload, only the first `data_length` bytes are valid.
49  pub data: [u8; 64],
50  /// True iff the id field is extended (ie 29 bits long, as opposed to 11).
51  pub ide: bool,
52  /// True iff this is a CAN FD format frame.  Including it here to give implementations the option
53  /// to use CanFdFrame for all traffic on the bus, if they so choose.
54  pub edl: bool,
55  /// True iff the frame was sent with a switched bit rate.
56  pub brs: bool,
57  /// True iff the sender is in FaultConfinementState::ErrorPassive (or possibly in BusOff).
58  pub esi: bool,
59  /// At the time of this writing this field isn't specified, but it can be received as either
60  /// value and subsequent protocols may end up using it.
61  pub reserved0: bool,
62  /// At the time of this writing this field isn't specified, but it can be received as either
63  /// value and subsequent protocols may end up using it.
64  pub reserved1: bool,
65}
66
67/// Converts a CAN-FD DLC into a byte count.
68///
69/// NOTE: According to the CAN 2.0 spec a data length of 8 can be encoded as any DLC >= 8.
70/// This function has no way of knowing the frame type, so be sure to only call it after
71/// you've verified that it's a CAN-FD frame you're dealing with.
72pub fn can_fd_dlc_to_byte_count(dlc: u8) -> u8 {
73  match dlc & 0xF {
74    0...8 => dlc,
75    9...12 => 8 + 4 * (dlc & 0b111),
76    13 => 32,
77    14 => 48,
78    15 => 64,
79    _ => unreachable!(),
80  }
81}
82
83/// Converts a byte count into a CAN-FD DLC.
84///
85/// NOTE: Not all byte counts can be represented as DLCs, which by implication means that not all
86/// byte counts are valid CAN-FD frame sizes.  This function accounts for the truncation and
87/// padding that may be incurred as a result of that.
88///
89/// If n != byte_count_to_can_fd_dlc(can_fd_dlc_to_byte_count(n)) truncation or padding will occur.
90pub fn byte_count_to_can_fd_dlc(byte_count: u8) -> u8 {
91  match byte_count {
92    0...8 => byte_count,
93    9...12 => 0b1001,
94    13...16 => 0b1010,
95    17...20 => 0b1011,
96    21...24 => 0b1100,
97    25...32 => 0b1101,
98    32...48 => 0b1110,
99    _ => 0b1111,
100  }
101}
can_utils/frames.rs

can_utils/
frames.rs
