Skip to main content

cal_model/
error.rs

1//! Typed, exhaustive error taxonomy for the calibration application layer.
2//!
3//! The enum is deliberately **exhaustive** (no `#[non_exhaustive]`):
4//! callers match every variant, and a new variant is a semver-minor event
5//! by design — the same policy as `a2l_parse::A2lError`, `xcp_core::XcpError`,
6//! and `dbc_parse::DbcError`, all of which are re-exported here as the
7//! `A2l`, `Xcp`, and `Dbc` variants.
8//!
9//! # What "no panics" means here
10//!
11//! Every failure mode of a calibration session resolves to one of these
12//! variants: a malformed A2L file ([`CalError::A2l`]), a slave ERR response
13//! ([`CalError::Xcp`]), a DBC layout that cannot be coded
14//! ([`CalError::Dbc`]), a name that does not resolve, a physical value
15//! outside the A2L limits, a value the deposit cannot represent, an
16//! unusable conversion, a non-converging optimiser, or a transport that
17//! reported a failure. There is no variant-free panic path, and no
18//! `unwrap` or index expression in the library target.
19
20/// The single crate-level error for every calibration operation.
21#[derive(Debug, Clone, PartialEq, thiserror::Error)]
22pub enum CalError {
23    /// The A2L project description could not be parsed, or a declaration it
24    /// carries does not resolve (an undeclared `COMPU_METHOD` or
25    /// `RECORD_LAYOUT` is reported as [`CalError::Unsupported`]).
26    #[error("A2L description error: {0}")]
27    A2l(#[from] a2l_parse::A2lError),
28
29    /// An XCP protocol failure: a slave ERR response, or a transport that
30    /// advertised no CAL/PAG resource.
31    #[error("XCP error: {0}")]
32    Xcp(#[from] xcp_core::XcpError),
33
34    /// A DBC failure: a malformed database, or a signal layout that cannot
35    /// be bit-coded into a payload buffer.
36    #[error("DBC error: {0}")]
37    Dbc(#[from] dbc_parse::DbcError),
38
39    /// No `/begin MODULE` with this name exists in the project.
40    #[error("unknown module `{0}`")]
41    UnknownModule(String),
42
43    /// The module exists but has no CHARACTERISTIC (or MEASUREMENT) with
44    /// this name.
45    #[error("unknown characteristic `{0}`")]
46    UnknownCharacteristic(String),
47
48    /// A physical value lies outside the A2L `LOWER_LIMIT`/`UPPER_LIMIT` of
49    /// the characteristic. `value` is the offending **physical** value.
50    #[error("`{name}` = {value} violates its calibration limits [{lower}, {upper}]")]
51    LimitViolation {
52        /// The CHARACTERISTIC name.
53        name: String,
54        /// The offending physical value.
55        value: f64,
56        /// `LOWER_LIMIT` from the A2L description.
57        lower: f64,
58        /// `UPPER_LIMIT` from the A2L description.
59        upper: f64,
60    },
61
62    /// A value is inside the A2L limits but outside what the ECU deposit
63    /// can represent — the raw value the conversion would need lies beyond
64    /// the datatype's range, or the conversion is not invertible there.
65    /// `value` is the offending physical value; `lower`/`upper` are the
66    /// bounds of the deposit, in physical units.
67    #[error("`{name}` = {value} is outside the representable range [{lower}, {upper}]")]
68    OutOfBounds {
69        /// The CHARACTERISTIC name.
70        name: String,
71        /// The offending physical value.
72        value: f64,
73        /// Smallest value the destination can hold, in physical units.
74        lower: f64,
75        /// Largest value the destination can hold, in physical units.
76        upper: f64,
77    },
78
79    /// No CAN signal in the attached DBC binds to this characteristic. The
80    /// payload is `module.characteristic`.
81    #[error("no CAN signal binding for `{0}`")]
82    NoSignalBinding(String),
83
84    /// The [`XcpTransport`](crate::XcpTransport) reported a failure. The
85    /// payload is the transport's own message.
86    #[error("transport failure: {0}")]
87    Transport(String),
88
89    /// The optimiser did not converge. Carries the number of iterations it
90    /// spent before giving up.
91    #[error("optimiser did not converge after {iterations} iterations")]
92    Convergence {
93        /// Sweeps performed before giving up.
94        iterations: u32,
95    },
96
97    /// A declaration cannot be honoured: an undeclared `COMPU_METHOD` /
98    /// `RECORD_LAYOUT`, a TABLE conversion whose `COMPU_TAB_REF` has no
99    /// registered points, a non-invertible conversion, a signal layout
100    /// outside the DBC range, or a deposit too large for one XCP UPLOAD.
101    #[error("{subject}: {reason}")]
102    Unsupported {
103        /// What the failure is about (a characteristic, a signal, a
104        /// conversion, …).
105        subject: String,
106        /// Why it cannot be honoured.
107        reason: String,
108    },
109
110    /// A calibration curve's ordinates change direction: the fit requires a
111    /// monotone piecewise-linear function.
112    #[error("non-monotone curve at `{name}`: {value} follows {previous}")]
113    NonMonotone {
114        /// The node name whose ordinate breaks monotonicity.
115        name: String,
116        /// The offending ordinate.
117        value: f64,
118        /// The ordinate it must not cross (the preceding node's value).
119        previous: f64,
120    },
121
122    /// Reading an A2L file from disk failed. `path` is the file, `detail`
123    /// the platform's message.
124    #[error("cannot read `{path}`: {detail}")]
125    Io {
126        /// The path that could not be read.
127        path: String,
128        /// The platform error message.
129        detail: String,
130    },
131}