Skip to main content

can_core/
error.rs

1//! Typed, exhaustive error taxonomy for every operation in the crate.
2//!
3//! The enum is deliberately **exhaustive** (no `#[non_exhaustive]`): callers
4//! are expected to match every variant, and a new variant is a
5//! semver-minor event by design — the same policy as `wire-kit`'s
6//! `WireError`. No codec entry point panics, wraps, or reads out of bounds:
7//! every malformed input resolves to one of these variants.
8
9use core::fmt;
10
11/// The single crate-level error for the frame codec and bit-timing calculator.
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
13pub enum CanError {
14    /// An identifier does not fit its width: 11-bit (standard) identifiers
15    /// top out at `0x7FF`, 29-bit (extended) at `0x1FFF_FFFF`. Also surfaces
16    /// for raw `SocketCAN` id words that carry bits outside the modeled space
17    /// (the `CAN_ERR_FLAG` error-frame class is not modeled; `got` is the
18    /// full id word, which then necessarily exceeds `max`).
19    InvalidIdLength {
20        /// Largest value the identifier width permits (`0x7FF` or
21        /// `0x1FFF_FFFF`).
22        max: u32,
23        /// The offending value.
24        got: u32,
25    },
26    /// A payload does not fit the frame's constraints: more than 8 bytes on
27    /// a classic frame, more than 64 bytes anywhere, or a CAN FD length that
28    /// is not one of the DLC-representable values (9–11, 13–15, … bytes are
29    /// not encodable). `max` is the largest length that would have fit.
30    DataTooLong {
31        /// Largest permitted payload length for this frame type.
32        max: usize,
33        /// The offending length.
34        got: usize,
35    },
36    /// A DLC value outside `0..=15`, or a classic-frame length byte outside
37    /// `0..=8`.
38    ///
39    /// Note: classic *remote* frames may legitimately carry a refined DLC
40    /// of 9–15 (the SocketCAN `len8_dlc` extension); this variant is for
41    /// values outside the representable space.
42    InvalidDlc(u8),
43    /// A CAN FD-only flag (BRS or ESI) was set on a classic frame.
44    FdBrsOnClassic,
45    /// A remote frame that carries data bytes, or a CAN FD frame marked as
46    /// remote (CAN FD abolished remote frames — both violations surface
47    /// here).
48    RemoteFrameWithData,
49    /// The buffer is shorter than the `SocketCAN` frame format requires
50    /// (16 bytes for `struct can_frame`, 72 for `struct canfd_frame`).
51    BufferTooShort {
52        /// Number of bytes the frame format requires.
53        need: usize,
54        /// Number of bytes actually available.
55        have: usize,
56    },
57    /// A bit-timing calculation was given impossible parameters (zero
58    /// baudrate, zero clock, a sample point outside `(0, 1)`) or no
59    /// configuration under the Bosch segment limits achieves the request.
60    InvalidTiming(&'static str),
61}
62
63impl fmt::Display for CanError {
64    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
65        match *self {
66            Self::InvalidIdLength { max, got } => {
67                write!(f, "identifier 0x{got:X} exceeds its width limit 0x{max:X}")
68            }
69            Self::DataTooLong { max, got } => {
70                write!(
71                    f,
72                    "payload of {got} bytes exceeds the {max}-byte maximum for this frame type"
73                )
74            }
75            Self::InvalidDlc(dlc) => {
76                write!(
77                    f,
78                    "invalid DLC {dlc}: expected 0..=15 (0..=8 for classic frames)"
79                )
80            }
81            Self::FdBrsOnClassic => {
82                write!(f, "FD-only flag (BRS/ESI) set on a classic CAN frame")
83            }
84            Self::RemoteFrameWithData => {
85                write!(
86                    f,
87                    "remote frame carrying data bytes, or FD frame marked remote"
88                )
89            }
90            Self::BufferTooShort { need, have } => {
91                write!(f, "buffer of {have} bytes is too short: need {need}")
92            }
93            Self::InvalidTiming(reason) => {
94                write!(f, "invalid bit-timing parameters: {reason}")
95            }
96        }
97    }
98}
99
100impl core::error::Error for CanError {}