Skip to main content

Crate xcp_core

Crate xcp_core 

Source
Expand description

XCP on CAN — Universal Measurement and Calibration Protocol: commands, responses, DAQ lists.

xcp-core is the estate’s L1 substrate for XCP calibration and measurement work: the complete CTO command table (ASAM XCP part 1, protocol layer, versions 1.0–1.5), a total response parser with the full slave error taxonomy, DAQ list configuration framing, and the CAN transport bridge (transport, XCP part 3) over [can-core].

§Total parsing

parse_response never panics: every buffer access is bounds-checked, and any input — hostile replay captures included — resolves to a typed XcpResponse or a typed XcpError. Slave ERR packets map onto the exhaustive XcpError taxonomy (0x20 command unknown, 0x31 generic, 0x33 resource temporarily not accessible, …), so session logic can match on protocol semantics, not raw bytes.

§Byte order

XCP slaves declare their byte order — Intel (little-endian) or Motorola (big-endian) — in the CONNECT response. ByteOrder parameterizes every multi-byte field the crate sends or decodes (frame::set_mta, frame::download_with, daq::DaqList::configure_frames, parse_response_with), with Intel as the crate default.

§Example

A full CONNECT exchange, wire bytes to typed session parameters:

use xcp_core::{connect, parse_response, ByteOrder, Expect, ResourceMode, XcpCommand};

// Master → slave: CONNECT, normal mode.
assert_eq!(connect(ResourceMode::CONNECT_NORMAL), [0xFF, 0x00]);

// Slave → master (a real-world response):
let reply = [0xFF, 0x1C, 0xC0, 0x08, 0x08, 0x00, 0x01, 0x01];
let res = xcp_core::parse_response_with(ByteOrder::Intel, Expect::Connect, &reply)?;

assert_eq!(res,
    xcp_core::XcpResponse::Connect(xcp_core::ConnectInfo {
        resource: ResourceMode::DAQ | ResourceMode::STIM | ResourceMode::PGM,
        comm_mode: xcp_core::CommModeBasic {
            byte_order: ByteOrder::Intel,
            address_granularity: xcp_core::AddressGranularity::Byte,
            slave_block_mode: true,
            optional_info: true,
        },
        max_cto: 8,
        max_dto: 8,
        protocol_version: (1, 0),
        transport_version: (1, 0),
    }));
assert!(matches!(XcpCommand::from_code(0xF6), Some(XcpCommand::SetMta)));

Calibration data goes through the MTA — frame::download builds the whole SET_MTA + DOWNLOAD (block-mode chunked) sequence, and DAQ measurement is configured with daq::DaqList:

use xcp_core::{DaqEntry, DaqList};

let mut list = DaqList::new(0, 0x0010);
list.push_entry(DaqEntry { bit_offset: 0, size: 2, address: 0x3200_0100, address_extension: 0 });
let frames = list.configure_frames(xcp_core::ByteOrder::Intel);
// SET_DAQ_LIST_MODE, SET_DAQ_PTR, WRITE_DAQ — 8 bytes each:
assert_eq!(frames.len(), 24);
assert_eq!(list.start_frame(), [0xDE, 0x01, 0x00, 0x00]);

§no_std

The crate is no_std + alloc and depends only on can-core (the L0 frame layer) and thiserror.

Modules§

transport
XCP on CAN transport framing (ASAM XCP part 3).

Structs§

CommModeBasic
The COMM_MODE_BASIC byte of the CONNECT response.
ConnectInfo
The CONNECT response payload.
DaqEntry
One ODT entry: a slice of ECU memory sampled into a DAQ packet.
DaqList
A DAQ list configuration for periodic measurement: which event channel triggers it, at what prescaler/priority, and which ODT entries it samples.
DaqListMode
Bits of the SET_DAQ_LIST_MODE MODE byte.
IdInfo
The GET_ID response payload.
ResourceMode
Bit set of XCP resources: which feature groups a slave offers (CONNECT response / GET_STATUS protection status) and which access is requested in the CONNECT mode byte.
SessionStatus
Bit set carried by the GET_STATUS response’s SESSION_STATUS byte.
StatusInfo
The GET_STATUS response payload.
VersionInfo
The GET_VERSION response payload.

Enums§

AddressGranularity
The address granularity a slave advertises in COMM_MODE_BASIC bits 1–2: the unit in which SET_MTA addresses and element counts are counted.
ByteOrder
The two byte orders a slave may advertise, per XCP part 1, §CONNECT (COMM_MODE_BASIC bit 0).
Direction
DAQ list direction for [DaqListMode::STIM].
Expect
The command whose response to expect — disambiguates RES layouts.
Pid
The response PID classes.
StartStopMode
START_STOP_DAQ_LIST modes.
XcpCommand
An XCP CTO command code — every command defined by the ASAM XCP protocol layer (part 1) through version 1.5.
XcpError
The single crate-level error for command framing, response parsing, and DAQ list configuration.
XcpResponse
A parsed XCP CTO response packet.

Constants§

DOWNLOAD_MAX_CHUNK
Largest DOWNLOAD payload in one CTO: the absolute protocol cap is MAX_CTO = 255, minus the PID and the element-count byte.
DOWNLOAD_NEXT_MAX_CHUNK
Largest DOWNLOAD_NEXT payload in one CTO: PID plus element-count byte.

Functions§

connect
Build the CONNECT command frame: [0xFF, MODE].
disconnect
Build the DISCONNECT command frame: [0xFE].
download
Build the SET_MTA + DOWNLOAD frame sequence for a plain memory write with Intel (little-endian) addressing and address extension 0x00.
download_frames
Build the block-mode DOWNLOAD frame sequence (DOWNLOAD + DOWNLOAD_NEXTs) without the SET_MTA prefix.
download_with
Build the SET_MTA + DOWNLOAD sequence with explicit byte order and address extension.
get_cal_page
Build the GET_CAL_PAGE command frame: [0xEA, MODE, SEG₂, SEG₁].
get_comm_mode_info
Build the GET_COMM_MODE_INFO command frame: [0xFB].
get_id
Build the GET_ID command frame: [0xFA, MODE, 0x00, 0x00].
get_status
Build the GET_STATUS command frame: [0xFD].
get_version
Build the GET_VERSION command frame: [0xC0, 0x00] (XCP ≥ 1.1).
parse_response
Parse an XCP CTO response packet with Intel (little-endian) byte order and no outstanding-command context — the inference heuristic of Expect::Generic.
parse_response_with
Parse an XCP CTO response packet with explicit byte order and the outstanding command (Expect).
set_cal_page
Build the SET_CAL_PAGE command frame: [0xEB, MODE, SEG₂, SEG₁].
set_mta
Build a SET_MTA command frame: [0xF6, 0x00, 0x00, EXT, ADDR₃…₀].
short_download
Build the SHORT_DOWNLOAD command frame: [0xED, 0x00, EXT, ADDR₃…₀, DATA…] — write without changing the MTA. The data must fit one CTO (at most 250 bytes after the 5-byte header for a 255-byte MAX_CTO); longer writes belong in download, which chunks.
short_upload
Build the SHORT_UPLOAD command frame: [0xF4, LEN, 0x00, EXT, ADDR₃…₀] — read without changing the MTA.
synch
Build the SYNCH command frame: [0xFC]. The slave answers with ERR 0x00 (XcpError::CmdSynch) once the command stream is synchronised.
upload
Build the SET_MTA + UPLOAD frame sequence for a plain memory read with Intel (little-endian) addressing and address extension 0x00.
upload_frame
Build the UPLOAD command frame: [0xF5, LEN] (reads from the current MTA).
upload_with
Build the SET_MTA + UPLOAD sequence with explicit byte order and address extension.