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}