xcp_core/resource.rs
1//! Resource and session-status bit sets.
2//!
3//! [`ResourceMode`] models the resource bitmask carried by the CONNECT
4//! response (`RESOURCE` byte), the GET_STATUS protection status, and the
5//! CONNECT mode byte. [`SessionStatus`] models the GET_STATUS session
6//! status byte.
7
8use core::fmt;
9use core::ops::{BitAnd, BitOr, Not};
10
11/// Bit set of XCP resources: which feature groups a slave offers (CONNECT
12/// response / GET_STATUS protection status) and which access is requested
13/// in the CONNECT mode byte.
14///
15/// Bit assignment per XCP part 1 (`RESOURCE` byte):
16/// bit 0 CAL/PAG, bit 2 DAQ, bit 3 STIM, bit 4 PGM, bit 5 DBG (XCP ≥ 1.5);
17/// bits 1, 6, 7 are reserved.
18///
19/// The CONNECT command's mode byte is `0x00` (normal) or `0x01`
20/// (user-defined) per the spec; `connect(mode)` passes the bit set through
21/// so user-defined modes can be modeled. Use
22/// [`ResourceMode::CONNECT_NORMAL`] / [`ResourceMode::CONNECT_USER_DEFINED`]
23/// for the standard modes.
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
25pub struct ResourceMode(u8);
26
27impl ResourceMode {
28 /// Calibration and page switching (`CAL/PAG`) — bit 0.
29 pub const CAL_PAGE: Self = Self(0x01);
30 /// Data acquisition (`DAQ`) — bit 2.
31 pub const DAQ: Self = Self(0x04);
32 /// Data stimulation (`STIM`) — bit 3.
33 pub const STIM: Self = Self(0x08);
34 /// Flash programming (`PGM`) — bit 4.
35 pub const PGM: Self = Self(0x10);
36 /// Debugging (`DBG`, XCP ≥ 1.5) — bit 5.
37 pub const DBG: Self = Self(0x20);
38 /// Composite: calibration *or* DAQ access (`CAL/PAG | DAQ`) — the
39 /// common "measure or calibrate" session.
40 pub const CAL_PAGE_OR_DAQ: Self = Self(0x05);
41 /// CONNECT mode `0x00` — normal mode.
42 pub const CONNECT_NORMAL: Self = Self(0x00);
43 /// CONNECT mode `0x01` — user-defined mode.
44 pub const CONNECT_USER_DEFINED: Self = Self(0x01);
45
46 /// Build from a raw resource byte. Total: unknown/reserved bits are
47 /// preserved (slaves may set vendor bits).
48 #[must_use]
49 pub const fn from_raw(bits: u8) -> Self {
50 Self(bits)
51 }
52
53 /// The raw resource byte.
54 #[must_use]
55 pub const fn bits(self) -> u8 {
56 self.0
57 }
58
59 /// `true` when no bit is set (e.g. the slave reports no protected
60 /// resources).
61 #[must_use]
62 pub const fn is_empty(self) -> bool {
63 self.0 == 0
64 }
65
66 /// `true` when every bit in `other` is also set in `self`.
67 #[must_use]
68 pub const fn contains(self, other: Self) -> bool {
69 self.0 & other.0 == other.0
70 }
71
72 /// `true` when the CAL/PAG resource is present.
73 #[must_use]
74 pub const fn cal_page(self) -> bool {
75 self.contains(Self::CAL_PAGE)
76 }
77
78 /// `true` when the DAQ resource is present.
79 #[must_use]
80 pub const fn daq(self) -> bool {
81 self.contains(Self::DAQ)
82 }
83
84 /// `true` when the STIM resource is present.
85 #[must_use]
86 pub const fn stim(self) -> bool {
87 self.contains(Self::STIM)
88 }
89
90 /// `true` when the PGM resource is present.
91 #[must_use]
92 pub const fn pgm(self) -> bool {
93 self.contains(Self::PGM)
94 }
95}
96
97impl BitOr for ResourceMode {
98 type Output = Self;
99 fn bitor(self, rhs: Self) -> Self {
100 Self(self.0 | rhs.0)
101 }
102}
103
104impl BitAnd for ResourceMode {
105 type Output = Self;
106 fn bitand(self, rhs: Self) -> Self {
107 Self(self.0 & rhs.0)
108 }
109}
110
111impl Not for ResourceMode {
112 type Output = Self;
113 fn not(self) -> Self {
114 Self(!self.0)
115 }
116}
117
118impl core::ops::BitOr for SessionStatus {
119 type Output = Self;
120 fn bitor(self, rhs: Self) -> Self {
121 Self(self.0 | rhs.0)
122 }
123}
124
125impl fmt::Display for ResourceMode {
126 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
127 if self.is_empty() {
128 return f.write_str("none");
129 }
130 let mut first = true;
131 let flags = [
132 (Self::CAL_PAGE.0, "cal_pag"),
133 (Self::DAQ.0, "daq"),
134 (Self::STIM.0, "stim"),
135 (Self::PGM.0, "pgm"),
136 (Self::DBG.0, "dbg"),
137 ];
138 for (bit, name) in flags {
139 if self.0 & bit == bit {
140 if !first {
141 f.write_str("|")?;
142 }
143 f.write_str(name)?;
144 first = false;
145 }
146 }
147 let unknown = self.0 & !0x3F;
148 if unknown != 0 {
149 if !first {
150 f.write_str("|")?;
151 }
152 write!(f, "0x{unknown:02X}")?;
153 }
154 Ok(())
155 }
156}
157
158/// Bit set carried by the GET_STATUS response's `SESSION_STATUS` byte.
159///
160/// The byte is bit-reversed relative to the resource byte: bit 0
161/// `STORE_CAL_REQUEST`, bit 1 `CAL_PAGE_CFG_LOST`, bit 2
162/// `STORE_DAQ_REQUEST`, bit 3 `CLEAR_DAQ_REQUEST`, bit 4 `DAQ_CFG_LOST`,
163/// bit 5 reserved, bit 6 `DAQ_ACTIVE`, bit 7 `RESUME`.
164#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
165pub struct SessionStatus(u8);
166
167impl SessionStatus {
168 /// Non-volatile calibration data has to be stored — bit 0.
169 pub const STORE_CAL_REQUEST: Self = Self(0x01);
170 /// Calibration page configuration lost — bit 1.
171 pub const CAL_PAGE_CFG_LOST: Self = Self(0x02);
172 /// Non-volatile DAQ configuration has to be stored — bit 2.
173 pub const STORE_DAQ_REQUEST: Self = Self(0x04);
174 /// A request to clear the DAQ configuration is pending — bit 3.
175 pub const CLEAR_DAQ_REQUEST: Self = Self(0x08);
176 /// DAQ configuration lost — bit 4.
177 pub const DAQ_CFG_LOST: Self = Self(0x10);
178 /// DAQ list(s) currently running — bit 6.
179 pub const DAQ_ACTIVE: Self = Self(0x40);
180 /// Session is in resume mode — bit 7.
181 pub const RESUME: Self = Self(0x80);
182
183 /// Build from the raw `SESSION_STATUS` byte. Total: reserved bits are
184 /// preserved.
185 #[must_use]
186 pub const fn from_raw(bits: u8) -> Self {
187 Self(bits)
188 }
189
190 /// The raw `SESSION_STATUS` byte.
191 #[must_use]
192 pub const fn bits(self) -> u8 {
193 self.0
194 }
195
196 /// `true` when no flag is set.
197 #[must_use]
198 pub const fn is_empty(self) -> bool {
199 self.0 == 0
200 }
201
202 /// `true` when every flag in `other` is also set in `self`.
203 #[must_use]
204 pub const fn contains(self, other: Self) -> bool {
205 self.0 & other.0 == other.0
206 }
207
208 /// `true` when DAQ list(s) are currently running.
209 #[must_use]
210 pub const fn daq_active(self) -> bool {
211 self.contains(Self::DAQ_ACTIVE)
212 }
213}
214
215impl fmt::Display for SessionStatus {
216 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
217 write!(f, "0x{:02X}", self.0)
218 }
219}