1use crate::conversion::CompuMethod;
24use crate::error::CalError;
25use crate::model::{CharKind, Characteristic, Measurement, Module};
26use crate::signal::SignalBinding;
27use a2l_parse::{A2lProject, DataType};
28use dbc_parse::Dbc;
29use std::cmp::Ordering;
30use std::collections::BTreeMap;
31use std::path::Path;
32
33#[derive(Debug, Clone, PartialEq)]
36pub struct CalibrationProject {
37 a2l: A2lProject,
38 modules: Vec<Module>,
39 dbc: Option<Dbc>,
40 tables: BTreeMap<String, Vec<(f64, f64)>>,
41 bindings: BTreeMap<String, BTreeMap<String, SignalBinding>>,
42 measurement_bindings: BTreeMap<String, BTreeMap<String, SignalBinding>>,
43 deposit_byte_order: xcp_core::ByteOrder,
44}
45
46impl CalibrationProject {
47 pub fn from_a2l(text: &str) -> Result<Self, CalError> {
56 Self::from_parsed(A2lProject::parse(text)?)
57 }
58
59 pub fn from_a2l_file(path: &Path) -> Result<Self, CalError> {
66 let text = std::fs::read_to_string(path).map_err(|err| CalError::Io {
67 path: path.display().to_string(),
68 detail: err.to_string(),
69 })?;
70 Self::from_a2l(&text)
71 }
72
73 pub fn from_parsed(a2l: A2lProject) -> Result<Self, CalError> {
79 let mut modules = Vec::with_capacity(a2l.modules.len());
80 for a2l_module in &a2l.modules {
81 let mut characteristics = Vec::with_capacity(a2l_module.characteristics.len());
82 for raw in &a2l_module.characteristics {
83 let layout = a2l_module
84 .record_layout_by_name(&raw.deposit)
85 .ok_or_else(|| CalError::Unsupported {
86 subject: format!("characteristic `{}`", raw.name),
87 reason: format!(
88 "RECORD_LAYOUT `{}` is not declared in module `{}`",
89 raw.deposit, a2l_module.name
90 ),
91 })?;
92 let fnc = layout.fnc_values.ok_or_else(|| CalError::Unsupported {
93 subject: format!("characteristic `{}`", raw.name),
94 reason: format!(
95 "RECORD_LAYOUT `{}` declares no FNC_VALUES, so the deposit datatype is unknown",
96 raw.deposit
97 ),
98 })?;
99 let method = a2l_module
100 .compu_method_by_name(&raw.conversion)
101 .ok_or_else(|| CalError::Unsupported {
102 subject: format!("characteristic `{}`", raw.name),
103 reason: format!(
104 "COMPU_METHOD `{}` is not declared in module `{}`",
105 raw.conversion, a2l_module.name
106 ),
107 })?;
108 characteristics.push(Characteristic {
109 name: raw.name.clone(),
110 kind: CharKind::from_char_type(raw.r#type),
111 address: raw.address,
112 deposit: raw.deposit.clone(),
113 deposit_position: fnc.position,
114 datatype: fnc.datatype,
115 elements: 1,
116 conversion: CompuMethod::from_a2l(method),
117 lower_limit: raw.lower_limit,
118 upper_limit: raw.upper_limit,
119 max_diff: raw.max_diff,
120 });
121 }
122 let mut measurements = Vec::with_capacity(a2l_module.measurements.len());
123 for raw in &a2l_module.measurements {
124 let method = a2l_module
125 .compu_method_by_name(&raw.conversion)
126 .ok_or_else(|| CalError::Unsupported {
127 subject: format!("measurement `{}`", raw.name),
128 reason: format!(
129 "COMPU_METHOD `{}` is not declared in module `{}`",
130 raw.conversion, a2l_module.name
131 ),
132 })?;
133 measurements.push(Measurement {
134 name: raw.name.clone(),
135 address: raw.address,
136 conversion: CompuMethod::from_a2l(method),
137 datatype: raw.datatype,
138 });
139 }
140 modules.push(Module {
141 name: a2l_module.name.clone(),
142 characteristics,
143 measurements,
144 });
145 }
146 Ok(Self {
147 a2l,
148 modules,
149 dbc: None,
150 tables: BTreeMap::new(),
151 bindings: BTreeMap::new(),
152 measurement_bindings: BTreeMap::new(),
153 deposit_byte_order: xcp_core::ByteOrder::Intel,
154 })
155 }
156
157 #[must_use]
159 pub fn project_name(&self) -> &str {
160 &self.a2l.project
161 }
162
163 #[must_use]
166 pub const fn a2l(&self) -> &A2lProject {
167 &self.a2l
168 }
169
170 #[must_use]
172 pub const fn dbc(&self) -> Option<&Dbc> {
173 self.dbc.as_ref()
174 }
175
176 pub fn modules(&self) -> impl Iterator<Item = &Module> {
178 self.modules.iter()
179 }
180
181 pub fn module(&self, name: &str) -> Result<&Module, CalError> {
187 self.modules
188 .iter()
189 .find(|m| m.name == name)
190 .ok_or_else(|| CalError::UnknownModule(name.to_string()))
191 }
192
193 pub fn module_names(&self) -> impl Iterator<Item = &str> {
195 self.modules.iter().map(|m| m.name.as_str())
196 }
197
198 pub fn characteristic(&self, module: &str, name: &str) -> Result<&Characteristic, CalError> {
204 self.module(module)?
205 .characteristic(name)
206 .ok_or_else(|| CalError::UnknownCharacteristic(qualified(module, name)))
207 }
208
209 pub fn measurement(&self, module: &str, name: &str) -> Result<&Measurement, CalError> {
215 self.module(module)?
216 .measurement(name)
217 .ok_or_else(|| CalError::UnknownCharacteristic(qualified(module, name)))
218 }
219
220 pub fn declare_elements(
233 &mut self,
234 module: &str,
235 name: &str,
236 elements: usize,
237 ) -> Result<(), CalError> {
238 let target = self
239 .modules
240 .iter_mut()
241 .find(|m| m.name == module)
242 .ok_or_else(|| CalError::UnknownModule(module.to_string()))?
243 .characteristics
244 .iter_mut()
245 .find(|c| c.name == name)
246 .ok_or_else(|| CalError::UnknownCharacteristic(qualified(module, name)))?;
247 target.elements = elements;
248 Ok(())
249 }
250
251 pub fn register_table(&mut self, name: &str, points: Vec<(f64, f64)>) -> Result<(), CalError> {
262 if points.is_empty() {
263 return Err(CalError::Unsupported {
264 subject: format!("COMPU_TAB `{name}`"),
265 reason: "a table needs at least one point".to_string(),
266 });
267 }
268 if points.windows(2).any(|pair| match pair {
273 [first, second] => !matches!(first.0.partial_cmp(&second.0), Some(Ordering::Less)),
274 _ => true,
275 }) {
276 return Err(CalError::Unsupported {
277 subject: format!("COMPU_TAB `{name}`"),
278 reason: "points must be strictly ascending by raw value".to_string(),
279 });
280 }
281 self.tables.insert(name.to_string(), points);
282 Ok(())
283 }
284
285 #[must_use]
287 pub fn table(&self, name: &str) -> Option<&[(f64, f64)]> {
288 self.tables.get(name).map(Vec::as_slice)
289 }
290
291 #[must_use]
293 pub const fn tables(&self) -> &BTreeMap<String, Vec<(f64, f64)>> {
294 &self.tables
295 }
296
297 #[must_use]
302 pub const fn deposit_byte_order(&self) -> xcp_core::ByteOrder {
303 self.deposit_byte_order
304 }
305
306 pub fn set_deposit_byte_order(&mut self, order: xcp_core::ByteOrder) {
308 self.deposit_byte_order = order;
309 }
310
311 pub fn attach_dbc(&mut self, dbc: Dbc) -> Result<(), CalError> {
327 let mut bindings: BTreeMap<String, BTreeMap<String, SignalBinding>> = BTreeMap::new();
328 let mut measurement_bindings: BTreeMap<String, BTreeMap<String, SignalBinding>> =
329 BTreeMap::new();
330 for module in &self.modules {
331 let mut per_module = BTreeMap::new();
332 for characteristic in &module.characteristics {
333 if let Some((can_id, signal)) = find_signal(&dbc, &characteristic.name) {
334 let binding = validate_binding(&characteristic.name, can_id, signal)?;
335 per_module.insert(characteristic.name.clone(), binding);
336 }
337 }
338 let mut per_measurement = BTreeMap::new();
339 for measurement in &module.measurements {
340 if let Some((can_id, signal)) = find_signal(&dbc, &measurement.name) {
341 let binding = validate_binding(&measurement.name, can_id, signal)?;
342 per_measurement.insert(measurement.name.clone(), binding);
343 }
344 }
345 bindings.insert(module.name.clone(), per_module);
346 measurement_bindings.insert(module.name.clone(), per_measurement);
347 }
348 self.bindings = bindings;
349 self.measurement_bindings = measurement_bindings;
350 self.dbc = Some(dbc);
351 Ok(())
352 }
353
354 pub fn attach_dbc_text(&mut self, text: &str) -> Result<(), CalError> {
361 self.attach_dbc(Dbc::parse(text)?)
362 }
363
364 #[must_use]
366 pub fn signal_for_characteristic(
367 &self,
368 module: &str,
369 char_name: &str,
370 ) -> Option<&SignalBinding> {
371 self.bindings.get(module)?.get(char_name)
372 }
373
374 #[must_use]
376 pub fn signal_bindings(&self, module: &str) -> Vec<&SignalBinding> {
377 self.bindings
378 .get(module)
379 .map(|m| m.values().collect())
380 .unwrap_or_default()
381 }
382
383 #[must_use]
389 pub fn signal_for_measurement(
390 &self,
391 module: &str,
392 measurement: &str,
393 ) -> Option<&SignalBinding> {
394 self.measurement_bindings.get(module)?.get(measurement)
395 }
396
397 #[must_use]
399 pub fn measurement_bindings(&self, module: &str) -> Vec<&SignalBinding> {
400 self.measurement_bindings
401 .get(module)
402 .map(|m| m.values().collect())
403 .unwrap_or_default()
404 }
405
406 pub fn require_measurement_binding(
413 &self,
414 module: &str,
415 measurement: &str,
416 ) -> Result<&SignalBinding, CalError> {
417 self.measurement(module, measurement)?;
418 self.signal_for_measurement(module, measurement)
419 .ok_or_else(|| CalError::NoSignalBinding(qualified(module, measurement)))
420 }
421
422 pub fn require_signal_binding(
430 &self,
431 module: &str,
432 char_name: &str,
433 ) -> Result<&SignalBinding, CalError> {
434 self.characteristic(module, char_name)?;
435 self.signal_for_characteristic(module, char_name)
436 .ok_or_else(|| CalError::NoSignalBinding(qualified(module, char_name)))
437 }
438
439 pub fn resolved_conversion(
447 &self,
448 characteristic: &Characteristic,
449 ) -> Result<CompuMethod, CalError> {
450 characteristic.conversion.resolved(&self.tables)
451 }
452
453 pub fn to_physical(&self, module: &str, name: &str, raw: u64) -> Result<f64, CalError> {
464 let characteristic = self.characteristic(module, name)?;
465 let conversion = self.resolved_conversion(characteristic)?;
466 Ok(conversion.apply(characteristic.raw_value(raw)))
467 }
468
469 pub fn to_raw(&self, module: &str, name: &str, physical: f64) -> Result<u64, CalError> {
483 let characteristic = self.characteristic(module, name)?;
484 self.check_physical_limits(characteristic, physical)?;
485 let conversion = self.resolved_conversion(characteristic)?;
486 let (value_min, value_max) = characteristic.value_bounds();
487 let value = conversion.invert(&characteristic.name, physical, value_min, value_max)?;
488 let rounded = value.round();
489 let bounded = if rounded < value_min {
490 value_min
491 } else if rounded > value_max {
492 value_max
493 } else {
494 rounded
495 };
496 Ok(characteristic.raw_bits(bounded))
497 }
498
499 pub fn check_physical_limits(
506 &self,
507 characteristic: &Characteristic,
508 physical: f64,
509 ) -> Result<(), CalError> {
510 if characteristic.within_limits(physical) {
511 return Ok(());
512 }
513 Err(CalError::LimitViolation {
514 name: characteristic.name.clone(),
515 value: physical,
516 lower: characteristic.lower_limit,
517 upper: characteristic.upper_limit,
518 })
519 }
520
521 pub fn check_limits(&self, module: &str, name: &str, raw: u64) -> Result<(), CalError> {
528 let physical = self.to_physical(module, name, raw)?;
529 let characteristic = self.characteristic(module, name)?;
530 self.check_physical_limits(characteristic, physical)
531 }
532
533 pub fn locate(&self, name: &str) -> Result<(&str, &Characteristic), CalError> {
540 self.modules
541 .iter()
542 .find_map(|module| {
543 module
544 .characteristic(name)
545 .map(|characteristic| (module.name.as_str(), characteristic))
546 })
547 .ok_or_else(|| CalError::UnknownCharacteristic(name.to_string()))
548 }
549
550 pub fn read_raw(
558 &self,
559 characteristic: &Characteristic,
560 data: &[u8],
561 ) -> Result<Vec<u64>, CalError> {
562 require_integer_datatype(characteristic)?;
563 let size = characteristic.datatype.size_bytes();
564 let needed = usize::from(characteristic.deposit_position) + characteristic.elements * size;
567 if data.len() < needed {
568 return Err(CalError::Unsupported {
569 subject: format!("characteristic `{}`", characteristic.name),
570 reason: format!(
571 "deposit needs {needed} bytes ({} element(s) · {size} byte(s) at position {}) but the payload carries {}",
572 characteristic.elements,
573 characteristic.deposit_position,
574 data.len()
575 ),
576 });
577 }
578 let mut raws = Vec::with_capacity(characteristic.elements);
579 for index in 0..characteristic.elements {
580 let start = usize::from(characteristic.deposit_position) + index * size;
581 let end = start + size;
582 let slice = data.get(start..end).ok_or_else(|| CalError::Unsupported {
583 subject: format!("characteristic `{}`", characteristic.name),
584 reason: format!(
585 "deposit needs {end} bytes but the payload carries {}",
586 data.len()
587 ),
588 })?;
589 raws.push(decode_element(slice, self.deposit_byte_order));
590 }
591 Ok(raws)
592 }
593
594 pub fn write_raw(
607 &self,
608 characteristic: &Characteristic,
609 raws: &[u64],
610 ) -> Result<Vec<u8>, CalError> {
611 require_integer_datatype(characteristic)?;
612 let size = characteristic.datatype.size_bytes();
613 let leading = usize::from(characteristic.deposit_position);
614 let needed = leading
615 .checked_add(
616 raws.len()
617 .checked_mul(size)
618 .ok_or_else(|| CalError::Unsupported {
619 subject: format!("characteristic `{}`", characteristic.name),
620 reason: "element count overflows the deposit size".to_string(),
621 })?,
622 )
623 .ok_or_else(|| CalError::Unsupported {
624 subject: format!("characteristic `{}`", characteristic.name),
625 reason: "deposit size overflows".to_string(),
626 })?;
627 if needed > usize::from(u8::MAX) {
628 return Err(CalError::Unsupported {
629 subject: format!("characteristic `{}`", characteristic.name),
630 reason: format!("deposit of {needed} bytes exceeds one XCP UPLOAD"),
631 });
632 }
633 let mut data = vec![0_u8; needed];
634 for (index, &raw) in raws.iter().enumerate() {
635 let value = characteristic.raw_value(raw);
636 let start = leading + index * size;
637 if let Some(slot) = data.get_mut(start..start + size) {
638 encode_element(slot, value, self.deposit_byte_order);
639 }
640 }
641 Ok(data)
642 }
643
644 pub fn physical_values(
650 &self,
651 characteristic: &Characteristic,
652 raws: &[u64],
653 ) -> Result<Vec<f64>, CalError> {
654 let conversion = self.resolved_conversion(characteristic)?;
655 Ok(raws
656 .iter()
657 .map(|&raw| conversion.apply(characteristic.raw_value(raw)))
658 .collect())
659 }
660}
661
662fn require_integer_datatype(characteristic: &Characteristic) -> Result<(), CalError> {
665 match characteristic.datatype {
666 DataType::Float32 | DataType::Float64 => Err(CalError::Unsupported {
667 subject: format!("characteristic `{}`", characteristic.name),
668 reason: format!(
669 "{} deposits are IEEE-754 values, not integer bit patterns",
670 characteristic.datatype.keyword()
671 ),
672 }),
673 _ => Ok(()),
674 }
675}
676
677fn validate_binding(
680 name: &str,
681 can_id: u32,
682 signal: &dbc_parse::Signal,
683) -> Result<SignalBinding, CalError> {
684 if signal.bit_length == 0 || signal.bit_length > 64 || signal.start_bit > 511 {
685 return Err(CalError::Unsupported {
686 subject: format!("signal `{}`", signal.name),
687 reason: format!(
688 "layout start_bit {} length {} is outside the DBC range (start <= 511, length 1..=64)",
689 signal.start_bit, signal.bit_length
690 ),
691 });
692 }
693 Ok(SignalBinding::from_signal(name, can_id, signal))
694}
695
696fn find_signal<'a>(dbc: &'a Dbc, name: &str) -> Option<(u32, &'a dbc_parse::Signal)> {
699 for message in &dbc.messages {
700 for signal in &message.signals {
701 if signal.name == name {
702 return Some((message.id.raw(), signal));
703 }
704 }
705 }
706 for message in &dbc.messages {
707 for signal in &message.signals {
708 if signal.name.eq_ignore_ascii_case(name) {
709 return Some((message.id.raw(), signal));
710 }
711 }
712 }
713 None
714}
715
716fn qualified(module: &str, name: &str) -> String {
718 format!("{module}.{name}")
719}
720
721fn decode_element(bytes: &[u8], order: xcp_core::ByteOrder) -> u64 {
723 let len = bytes.len();
724 let mut value = 0_u64;
725 for (index, &byte) in bytes.iter().enumerate() {
726 let shift = match order {
727 xcp_core::ByteOrder::Intel => index * 8,
728 xcp_core::ByteOrder::Motorola => (len - 1 - index) * 8,
729 };
730 value |= u64::from(byte) << shift;
731 }
732 value
733}
734
735fn encode_element(bytes: &mut [u8], value: f64, order: xcp_core::ByteOrder) {
737 #[allow(clippy::cast_possible_wrap)]
738 let bits = value as i64 as u64;
739 let len = bytes.len();
740 for (index, slot) in bytes.iter_mut().enumerate() {
741 let shift = match order {
742 xcp_core::ByteOrder::Intel => index * 8,
743 xcp_core::ByteOrder::Motorola => (len - 1 - index) * 8,
744 };
745 #[allow(clippy::cast_possible_truncation)]
746 {
747 *slot = ((bits >> shift) & 0xFF) as u8;
748 }
749 }
750}