can_core/lib.rs
1//! CAN 2.0 and CAN FD frame codec — identifier parsing, DLC handling,
2//! bit-timing calculation, arbitration model.
3//!
4//! `can-core` is the estate's **L0 leaf** for Controller Area Network work:
5//! a total, allocation-free-at-parse frame codec over the `SocketCAN` wire
6//! format, plus the bit-timing and arbitration models every higher CAN
7//! layer shares.
8//!
9//! # Zero-copy, total parsing
10//!
11//! [`CanFrame::parse`] borrows the payload straight out of the input buffer —
12//! one buffer in, a typed view out, nothing copied. Every buffer access is
13//! bounds-checked: malformed, truncated, or hostile input yields a typed
14//! [`CanError`], never a panic (enforced by deny-level lints on the lib
15//! target, a cargo-fuzz target, and miri).
16//!
17//! # The frame model
18//!
19//! A [`CanFrame`] is an identifier ([`CanId`]: 11-bit standard or 29-bit
20//! extended), a payload of 0–64 bytes, the Data Length Code, and the flag
21//! bits (`is_remote`, `is_fd`, `brs`, `error_state_indicator`). Classic CAN
22//! payloads cap at 8 bytes with DLC = length; CAN FD maps DLC 0–15 through
23//! the table `0,1,2,3,4,5,6,7,8,12,16,20,24,32,48,64`
24//! ([`dlc_to_len`]/[`len_to_dlc`]). Remote frames carry no payload, and CAN
25//! FD — which abolished remote frames — rejects them outright.
26//!
27//! # Bit timing
28//!
29//! [`timing::BitTiming::calculate`] solves the standard Bosch bit-timing
30//! algorithm from baudrate and clock: prescaler search plus segment split,
31//! sample point closest to the `CiA` default (87.5 % below 800 kbit/s, 75 %
32//! above), rendered as SJA1000-style BTR register bytes via
33//! [`timing::BitTiming::btr`].
34//!
35//! # Arbitration
36//!
37//! Lower identifiers win — with the wire-level subtlety that a standard
38//! frame beats an extended frame sharing its first 11 id bits (dominant IDE
39//! vs recessive SRR). [`arbitration::dominates`] models the full comparison;
40//! CAN FD changes nothing at arbitration phase (BRS applies only after the
41//! winner is decided).
42//!
43//! # Example
44//!
45//! ```
46//! use can_core::{CanFrame, CanId, CanError};
47//!
48//! // Build and round-trip a CAN FD frame:
49//! let id = CanId::extended(0x18FF_0102)?;
50//! let frame = CanFrame::fd(id, &[0xDE, 0xAD, 0xBE, 0xEF], true, false)?;
51//! let bytes = frame.to_bytes();
52//! assert_eq!(bytes.len(), 72);
53//! assert_eq!(CanFrame::parse(&bytes)?, frame);
54//!
55//! // Out-of-range ids are rejected, never truncated:
56//! assert!(matches!(
57//! CanId::standard(0x800),
58//! Err(CanError::InvalidIdLength { max: 0x7FF, got: 0x800 })
59//! ));
60//! # Ok::<(), CanError>(())
61//! ```
62//!
63//! # `no_std`
64//!
65//! The crate is `no_std` + `alloc` — it builds for embedded targets
66//! (`thumbv7em-none-eabihf` is exercised in CI) and depends only on
67//! `thiserror` for the error taxonomy.
68
69#![no_std]
70extern crate alloc;
71
72mod error;
73mod frame;
74mod id;
75
76pub mod arbitration;
77pub mod timing;
78
79pub use error::CanError;
80pub use frame::{
81 dlc_to_len, len_to_dlc, CanFrame, CLASSIC_FRAME_SIZE, CLASSIC_MAX_LEN, FD_DLC_TO_LEN,
82 FD_FRAME_SIZE, FD_MAX_LEN,
83};
84pub use id::{CanId, EXTENDED_ID_MAX, STANDARD_ID_MAX};