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}