Skip to main content

xcp_core/
daq.rs

1//! DAQ list configuration for periodic measurement.
2//!
3//! A DAQ (Data ACquisition) list groups ODTs (Object Descriptor Tables),
4//! each holding ODT entries — (bit offset, size, address) slices of ECU
5//! memory sampled on an event channel. This module frames the static
6//! configuration sequence ([`DaqList::configure_frames`]: SET_DAQ_LIST_MODE,
7//! then per-entry SET_DAQ_PTR/WRITE_DAQ) and the run-control frames
8//! (START_STOP_DAQ_LIST / START_STOP_SYNCH).
9//!
10//! # Example
11//!
12//! ```
13//! use xcp_core::{ByteOrder, DaqEntry, DaqList};
14//!
15//! let mut list = DaqList::new(1, 0x0010);
16//! list.timestamp = true;
17//! list.push_entry(DaqEntry { bit_offset: 0, size: 4, address: 0x3200_1000, address_extension: 0 });
18//!
19//! // SET_DAQ_LIST_MODE + (SET_DAQ_PTR + WRITE_DAQ) × entries:
20//! let frames = list.configure_frames(ByteOrder::Intel);
21//! assert_eq!(frames[0], 0xE0);          // SET_DAQ_LIST_MODE
22//! assert_eq!(frames[8], 0xE2);          // SET_DAQ_PTR
23//! assert_eq!(frames[16], 0xE1);         // WRITE_DAQ
24//!
25//! // Start the list (mode 0x01), then all selected lists:
26//! assert_eq!(list.start_frame(), [0xDE, 0x01, 0x01, 0x00]);
27//! assert_eq!(DaqList::start_synch_frame(), [0xDD, 0x00]);
28//! ```
29
30use crate::byteorder::ByteOrder;
31use alloc::vec::Vec;
32
33/// One ODT entry: a slice of ECU memory sampled into a DAQ packet.
34#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
35pub struct DaqEntry {
36    /// Bit offset within the addressed element (0–7 for byte granularity).
37    pub bit_offset: u8,
38    /// Element size in address-granularity units (bytes at byte
39    /// granularity).
40    pub size: u8,
41    /// ECU address of the element.
42    pub address: u32,
43    /// Address extension (memory selector; `0` on most ECUs).
44    pub address_extension: u8,
45}
46
47/// DAQ list direction for [`DaqListMode::STIM`].
48#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
49#[allow(clippy::exhaustive_enums)]
50pub enum Direction {
51    /// Data acquisition (slave → master).
52    #[default]
53    Daq,
54    /// Data stimulation (master → slave).
55    Stim,
56}
57
58/// Bits of the SET_DAQ_LIST_MODE `MODE` byte.
59#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
60pub struct DaqListMode {
61    /// Direction: DAQ (default) or STIM.
62    pub direction: Direction,
63    /// Attach a timestamp to the list's DTOs.
64    pub timestamp: bool,
65    /// Send DTOs without the identification field (PID off).
66    pub pid_off: bool,
67}
68
69impl DaqListMode {
70    /// Encode to the SET_DAQ_LIST_MODE `MODE` byte.
71    #[must_use]
72    pub const fn to_bits(self) -> u8 {
73        let stim = match self.direction {
74            Direction::Daq => 0x00,
75            Direction::Stim => 0x02,
76        };
77        stim | if self.timestamp { 0x10 } else { 0 } | if self.pid_off { 0x20 } else { 0 }
78    }
79}
80
81/// START_STOP_DAQ_LIST modes.
82#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
83#[allow(clippy::exhaustive_enums)]
84pub enum StartStopMode {
85    /// `0x00` — stop the DAQ list.
86    Stop = 0x00,
87    /// `0x01` — start the DAQ list.
88    Start = 0x01,
89    /// `0x02` — select the DAQ list for a later START_STOP_SYNCH.
90    Select = 0x02,
91}
92
93impl StartStopMode {
94    /// The wire mode byte.
95    #[must_use]
96    pub const fn to_bits(self) -> u8 {
97        match self {
98            Self::Stop => 0x00,
99            Self::Start => 0x01,
100            Self::Select => 0x02,
101        }
102    }
103}
104
105/// A DAQ list configuration for periodic measurement: which event channel
106/// triggers it, at what prescaler/priority, and which ODT entries it
107/// samples.
108#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
109pub struct DaqList {
110    /// DAQ list number (`0x0000`–`MAX_DAQ − 1`).
111    pub number: u16,
112    /// Event channel the list is triggered by.
113    pub event_channel: u16,
114    /// Event-channel prescaler: sample every `prescaler`-th event
115    /// (`1` = every event). Applied at start time.
116    pub prescaler: u8,
117    /// DAQ list priority (`0` = standard).
118    pub priority: u8,
119    /// Attach timestamps to this list's DTOs.
120    pub timestamp: bool,
121    /// Send DTOs without the identification field.
122    pub pid_off: bool,
123    /// DAQ (measure) or STIM (stimulate).
124    pub direction: Direction,
125    /// The list's ODT entries, in sampling order.
126    pub entries: Vec<DaqEntry>,
127}
128
129impl DaqList {
130    /// A fresh DAQ list on `event_channel`, prescaler 1, priority 0, no
131    /// entries.
132    #[must_use]
133    pub fn new(number: u16, event_channel: u16) -> Self {
134        Self {
135            number,
136            event_channel,
137            prescaler: 1,
138            priority: 0,
139            timestamp: false,
140            pid_off: false,
141            direction: Direction::Daq,
142            entries: Vec::new(),
143        }
144    }
145
146    /// Append an ODT entry.
147    pub fn push_entry(&mut self, entry: DaqEntry) {
148        self.entries.push(entry);
149    }
150
151    /// The SET_DAQ_LIST_MODE `MODE` byte for this list.
152    #[must_use]
153    pub fn mode_bits(&self) -> u8 {
154        DaqListMode {
155            direction: self.direction,
156            timestamp: self.timestamp,
157            pid_off: self.pid_off,
158        }
159        .to_bits()
160    }
161
162    /// Build the full static-configuration frame sequence:
163    /// SET_DAQ_LIST_MODE, then SET_DAQ_PTR + WRITE_DAQ for every entry.
164    ///
165    /// All multi-byte fields use `byte_order` — the order the slave
166    /// advertised in CONNECT. For a *dynamic* list, precede this sequence
167    /// with FREE_DAQ/ALLOC_DAQ/ALLOC_ODT/ALLOC_ODT_ENTRY (not framed here).
168    #[must_use]
169    pub fn configure_frames(&self, byte_order: ByteOrder) -> Vec<u8> {
170        // SET_DAQ_LIST_MODE: E0, MODE, DAQ(word), EVENT(word), PRESCALER,
171        // PRIORITY.
172        let mut out = Vec::with_capacity(8 + self.entries.len() * 16);
173        out.push(crate::XcpCommand::SetDaqListMode.code());
174        out.push(self.mode_bits());
175        byte_order.put_u16(&mut out, self.number);
176        byte_order.put_u16(&mut out, self.event_channel);
177        out.push(self.prescaler);
178        out.push(self.priority);
179
180        // SET_DAQ_PTR: E2, 0, 0, 0, DAQ(word), ODT, ODT_ENTRY.
181        // WRITE_DAQ:   E1, BIT_OFFSET, SIZE, ADDR_EXT, ADDR(dword).
182        for (i, entry) in self.entries.iter().enumerate() {
183            // One ODT per entry (the default optimisation type); entry 0
184            // within each ODT. Lists beyond 256 entries saturate — a
185            // slave's MAX_ODT limit applies long before.
186            let odt = u8::try_from(i).unwrap_or(u8::MAX);
187            out.push(crate::XcpCommand::SetDaqPtr.code());
188            out.extend_from_slice(&[0x00, 0x00, 0x00]);
189            byte_order.put_u16(&mut out, self.number);
190            out.push(odt);
191            out.push(0x00); // entry 0 within the ODT
192
193            out.push(crate::XcpCommand::WriteDaq.code());
194            out.push(entry.bit_offset);
195            out.push(entry.size);
196            out.push(entry.address_extension);
197            byte_order.put_u32(&mut out, entry.address);
198        }
199        out
200    }
201
202    /// Build a START_STOP_DAQ_LIST frame for this list in `mode`:
203    /// `[0xDE, MODE, DAQ₂, DAQ₁]`.
204    #[must_use]
205    pub fn start_stop_frame(&self, mode: StartStopMode) -> Vec<u8> {
206        self.start_stop_frame_with(ByteOrder::Intel, mode)
207    }
208
209    /// [`DaqList::start_stop_frame`] with explicit byte order.
210    #[must_use]
211    pub fn start_stop_frame_with(&self, byte_order: ByteOrder, mode: StartStopMode) -> Vec<u8> {
212        let mut f = alloc::vec![crate::XcpCommand::StartStopDaqList.code(), mode.to_bits()];
213        byte_order.put_u16(&mut f, self.number);
214        f
215    }
216
217    /// `[0xDE, 0x01, DAQ₂, DAQ₁]` — start this list (Intel byte order).
218    #[must_use]
219    pub fn start_frame(&self) -> Vec<u8> {
220        self.start_stop_frame(StartStopMode::Start)
221    }
222
223    /// `[0xDE, 0x00, DAQ₂, DAQ₁]` — stop this list (Intel byte order).
224    #[must_use]
225    pub fn stop_frame(&self) -> Vec<u8> {
226        self.start_stop_frame(StartStopMode::Stop)
227    }
228
229    /// `[0xDD, 0x00]` — START_STOP_SYNCH: start all selected DAQ lists.
230    #[must_use]
231    pub fn start_synch_frame() -> Vec<u8> {
232        alloc::vec![crate::XcpCommand::StartStopSynch.code(), 0x00]
233    }
234
235    /// `[0xDD, 0x01]` — START_STOP_SYNCH: stop all selected DAQ lists.
236    #[must_use]
237    pub fn stop_synch_frame() -> Vec<u8> {
238        alloc::vec![crate::XcpCommand::StartStopSynch.code(), 0x01]
239    }
240}