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}