Skip to main content

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}