Skip to main content

xcp_core/
byteorder.rs

1//! Byte order (endianness) per the XCP protocol layer.
2//!
3//! A slave advertises its byte order in the CONNECT response
4//! (`COMM_MODE_BASIC` bit 0: `0` = Intel / little-endian, `1` = Motorola /
5//! big-endian). Every multi-byte field the master sends or receives —
6//! `SET_MTA` addresses, `MAX_DTO`, DAQ list numbers, event channels,
7//! timestamps — is encoded in that order. Address granularity is carried
8//! alongside it (`BYTE`, `WORD`, `DWORD`).
9
10use alloc::vec::Vec;
11use core::fmt;
12
13/// The two byte orders a slave may advertise, per XCP part 1, §CONNECT
14/// (`COMM_MODE_BASIC` bit 0).
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
16pub enum ByteOrder {
17    /// Intel / little-endian: least significant byte first (`0x00800000`
18    /// → `00 00 80 00`). The common case on CAN-attached ECUs; the crate's
19    /// default where a builder is offered without an explicit order.
20    #[default]
21    Intel,
22    /// Motorola / big-endian: most significant byte first (`0x00800000` →
23    /// `00 80 00 00`).
24    Motorola,
25}
26
27impl ByteOrder {
28    /// Decode from the `COMM_MODE_BASIC` bit 0 value (`0` = Intel, `1` =
29    /// Motorola).
30    #[must_use]
31    pub const fn from_bit(bit: u8) -> Self {
32        if bit & 0x01 == 0x01 {
33            Self::Motorola
34        } else {
35            Self::Intel
36        }
37    }
38
39    /// Encode to the `COMM_MODE_BASIC` bit 0 value (`0` = Intel, `1` =
40    /// Motorola).
41    #[must_use]
42    pub const fn to_bit(self) -> u8 {
43        match self {
44            Self::Intel => 0,
45            Self::Motorola => 1,
46        }
47    }
48
49    /// Append a `u16` in this byte order.
50    pub fn put_u16(self, buf: &mut Vec<u8>, value: u16) {
51        let [a, b] = value.to_be_bytes();
52        if matches!(self, Self::Intel) {
53            buf.extend_from_slice(&[b, a]);
54        } else {
55            buf.extend_from_slice(&[a, b]);
56        }
57    }
58
59    /// Append a `u32` in this byte order.
60    pub fn put_u32(self, buf: &mut Vec<u8>, value: u32) {
61        let [a, b, c, d] = value.to_be_bytes();
62        if matches!(self, Self::Intel) {
63            buf.extend_from_slice(&[d, c, b, a]);
64        } else {
65            buf.extend_from_slice(&[a, b, c, d]);
66        }
67    }
68
69    /// Read a `u16` from the front of `bytes` in this byte order. Returns
70    /// `None` when fewer than two bytes are available.
71    #[must_use]
72    pub fn get_u16(self, bytes: &[u8]) -> Option<u16> {
73        let &[first, second] = bytes.first_chunk::<2>()?;
74        Some(match self {
75            // Intel: least significant byte first.
76            Self::Intel => u16::from_le_bytes([first, second]),
77            // Motorola: most significant byte first.
78            Self::Motorola => u16::from_be_bytes([first, second]),
79        })
80    }
81
82    /// Read a `u32` from the front of `bytes` in this byte order. Returns
83    /// `None` when fewer than four bytes are available.
84    #[must_use]
85    pub fn get_u32(self, bytes: &[u8]) -> Option<u32> {
86        let b = bytes.first()?;
87        let c = bytes.get(1)?;
88        let d = bytes.get(2)?;
89        let e = bytes.get(3)?;
90        let (a0, a1, a2, a3) = match self {
91            Self::Intel => (*e, *d, *c, *b),
92            Self::Motorola => (*b, *c, *d, *e),
93        };
94        Some((u32::from(a0) << 24) | (u32::from(a1) << 16) | (u32::from(a2) << 8) | u32::from(a3))
95    }
96}
97
98impl fmt::Display for ByteOrder {
99    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100        match self {
101            Self::Intel => f.write_str("intel"),
102            Self::Motorola => f.write_str("motorola"),
103        }
104    }
105}
106
107/// The address granularity a slave advertises in `COMM_MODE_BASIC` bits 1–2:
108/// the unit in which `SET_MTA` addresses and element counts are counted.
109#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
110pub enum AddressGranularity {
111    /// Addresses count bytes (granularity code `0b00`).
112    #[default]
113    Byte,
114    /// Addresses count 16-bit words (granularity code `0b01`).
115    Word,
116    /// Addresses count 32-bit dwords (granularity code `0b10`).
117    Dword,
118    /// Reserved granularity code (`0b11`) — accepted, never emitted.
119    Reserved,
120}
121
122impl AddressGranularity {
123    /// Decode from `COMM_MODE_BASIC` bits 1–2 (the two bits above the byte
124    /// order bit).
125    #[must_use]
126    pub const fn from_bits(bits: u8) -> Self {
127        match (bits >> 1) & 0x03 {
128            0b01 => Self::Word,
129            0b10 => Self::Dword,
130            0b11 => Self::Reserved,
131            _ => Self::Byte,
132        }
133    }
134
135    /// Encode to `COMM_MODE_BASIC` bits 1–2.
136    #[must_use]
137    pub const fn to_bits(self) -> u8 {
138        match self {
139            Self::Byte => 0b00,
140            Self::Word => 0b01,
141            Self::Dword => 0b10,
142            Self::Reserved => 0b11,
143        }
144    }
145}