Skip to main content

xcp_core/
lib.rs

1//! XCP on CAN — Universal Measurement and Calibration Protocol: commands,
2//! responses, DAQ lists.
3//!
4//! `xcp-core` is the estate's **L1 substrate** for XCP calibration and
5//! measurement work: the complete CTO command table (ASAM XCP part 1,
6//! protocol layer, versions 1.0–1.5), a total response parser with the
7//! full slave error taxonomy, DAQ list configuration framing, and the CAN
8//! transport bridge ([`transport`], XCP part 3) over [`can-core`].
9//!
10//! # Total parsing
11//!
12//! [`parse_response`] never panics: every buffer access is bounds-checked,
13//! and any input — hostile replay captures included — resolves to a typed
14//! [`XcpResponse`] or a typed [`XcpError`]. Slave `ERR` packets map onto
15//! the exhaustive [`XcpError`] taxonomy (`0x20` command unknown, `0x31`
16//! generic, `0x33` resource temporarily not accessible, …), so session
17//! logic can `match` on protocol semantics, not raw bytes.
18//!
19//! # Byte order
20//!
21//! XCP slaves declare their byte order — Intel (little-endian) or Motorola
22//! (big-endian) — in the CONNECT response. [`ByteOrder`] parameterizes
23//! every multi-byte field the crate sends or decodes
24//! ([`frame::set_mta`], [`frame::download_with`], [`daq::DaqList::configure_frames`],
25//! [`parse_response_with`]), with Intel as the crate default.
26//!
27//! # Example
28//!
29//! A full CONNECT exchange, wire bytes to typed session parameters:
30//!
31//! ```
32//! use xcp_core::{connect, parse_response, ByteOrder, Expect, ResourceMode, XcpCommand};
33//!
34//! // Master → slave: CONNECT, normal mode.
35//! assert_eq!(connect(ResourceMode::CONNECT_NORMAL), [0xFF, 0x00]);
36//!
37//! // Slave → master (a real-world response):
38//! let reply = [0xFF, 0x1C, 0xC0, 0x08, 0x08, 0x00, 0x01, 0x01];
39//! let res = xcp_core::parse_response_with(ByteOrder::Intel, Expect::Connect, &reply)?;
40//!
41//! assert_eq!(res,
42//!     xcp_core::XcpResponse::Connect(xcp_core::ConnectInfo {
43//!         resource: ResourceMode::DAQ | ResourceMode::STIM | ResourceMode::PGM,
44//!         comm_mode: xcp_core::CommModeBasic {
45//!             byte_order: ByteOrder::Intel,
46//!             address_granularity: xcp_core::AddressGranularity::Byte,
47//!             slave_block_mode: true,
48//!             optional_info: true,
49//!         },
50//!         max_cto: 8,
51//!         max_dto: 8,
52//!         protocol_version: (1, 0),
53//!         transport_version: (1, 0),
54//!     }));
55//! assert!(matches!(XcpCommand::from_code(0xF6), Some(XcpCommand::SetMta)));
56//! # Ok::<(), xcp_core::XcpError>(())
57//! ```
58//!
59//! Calibration data goes through the MTA — [`frame::download`] builds the
60//! whole SET_MTA + DOWNLOAD (block-mode chunked) sequence, and DAQ
61//! measurement is configured with [`daq::DaqList`]:
62//!
63//! ```
64//! use xcp_core::{DaqEntry, DaqList};
65//!
66//! let mut list = DaqList::new(0, 0x0010);
67//! list.push_entry(DaqEntry { bit_offset: 0, size: 2, address: 0x3200_0100, address_extension: 0 });
68//! let frames = list.configure_frames(xcp_core::ByteOrder::Intel);
69//! // SET_DAQ_LIST_MODE, SET_DAQ_PTR, WRITE_DAQ — 8 bytes each:
70//! assert_eq!(frames.len(), 24);
71//! assert_eq!(list.start_frame(), [0xDE, 0x01, 0x00, 0x00]);
72//! ```
73//!
74//! # `no_std`
75//!
76//! The crate is `no_std` + `alloc` and depends only on `can-core` (the L0
77//! frame layer) and `thiserror`.
78
79// XCP/ASAM wire identifiers (SET_MTA, DOWNLOAD_NEXT, GET_STATUS …)
80// are proper nouns of the protocol; backticking every occurrence
81// would bury the prose. Allowed with this justification per the
82// fleet pedantic policy.
83#![allow(clippy::doc_markdown)]
84#![no_std]
85extern crate alloc;
86
87mod byteorder;
88mod command;
89mod daq;
90mod error;
91mod frame;
92mod resource;
93mod response;
94pub mod transport;
95
96pub use byteorder::{AddressGranularity, ByteOrder};
97pub use command::XcpCommand;
98pub use daq::{DaqEntry, DaqList, DaqListMode, Direction, StartStopMode};
99pub use error::XcpError;
100pub use frame::{
101    connect, disconnect, download, download_frames, download_with, get_cal_page,
102    get_comm_mode_info, get_id, get_status, get_version, set_cal_page, set_mta, short_download,
103    short_upload, synch, upload, upload_frame, upload_with, DOWNLOAD_MAX_CHUNK,
104    DOWNLOAD_NEXT_MAX_CHUNK,
105};
106pub use resource::{ResourceMode, SessionStatus};
107pub use response::{
108    parse_response, parse_response_with, CommModeBasic, ConnectInfo, Expect, IdInfo, Pid,
109    StatusInfo, VersionInfo, XcpResponse,
110};