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 {}