Device-driver codegen¶

This chapter captures the requirements for the device-driver codegen toolchain: a layered set of crates that translates EtherCAT ESI XML device descriptions into strongly-typed Rust driver modules at build time, with zero runtime XML parsing and no dependency on the taktora-connector-ethercat runtime.

The decomposition mirrors the convention established in Connector framework and Soft-RT PLC runtime heart:

Top-level umbrella feature — Device-driver codegen toolc... (FEAT_0050) — peer to PLC runtime heart on iceoryx2 (FEAT_0010) (PLC runtime heart), Connector framework (FEAT_0030) (Connector framework), and Bounded global allocator (FEAT_0040) (Bounded global allocator). The codegen toolchain is a build-time concern orthogonal to the runtime connector framework; it is not bound to taktora-executor or taktora-connector and could be consumed by any ethercrab user.
Capability-cluster sub-features — one per crate-layer concern, each :satisfies: Device-driver codegen toolc... (FEAT_0050).
Requirements — concrete shall-clauses that :satisfies: a capability-cluster feature.

This round covers EtherCAT only (ESI XML → typed driver structs). CANopen / EDS support is explicitly out of scope; the architecture preserves the option to extract a shared object-dictionary IR later (see Future CANopen support via ... (ADR_0073)).

The umbrella decomposes into seven capability clusters, each on its own page (see the toctree): the ESI parser (ESI parser (FEAT_0051)), the IR and codegen backend trait (IR and codegen backend trait (FEAT_0052)), the ethercrab backend (ethercrab codegen backend (FEAT_0053)), the runtime trait surface (Runtime trait surface (FEAT_0054)), the build helper (Build helper (build.rs glue) (FEAT_0055)), CLI inspection (CLI inspection (cargo subco... (FEAT_0056)), and EEPROM diff verification (EEPROM diff verification (FEAT_0057)). The deliberately rejected anti-goals and the umbrella-level traceability tables live on Anti-goals and cross-cutting traceability.

Top-level umbrella¶

Feature: Device-driver codegen toolchain FEAT_0050

status: open

is satisfied by: REQ_0590, REQ_0591, REQ_0592, REQ_0593, REQ_0594, REQ_0595, FEAT_0055, FEAT_0056, FEAT_0057, FEAT_0051, FEAT_0053, FEAT_0052, FEAT_0054

is refined by: ARCH_0054, QG_0010, QG_0011, QG_0012, ARCH_0050, ARCH_0051, ADR_0070, ADR_0073

is implemented by: BB_0067

A layered set of Rust crates that consumes EtherCAT Slave Information (ESI) XML files and emits strongly-typed driver modules at build time. The toolchain is organised as four layers that depend only leftwards:

Parse layer — ethercat-esi: XML → typed IR, no_std + alloc. No knowledge of codegen or ethercrab.
Codegen layer — ethercat-esi-codegen (IR → TokenStream via a CodegenBackend trait) plus ethercat-esi-codegen-ethercrab (the one concrete backend shipped in this round).
Tooling layer — ethercat-esi-build (build.rs glue), ethercat-esi-cli (cargo esi expand / cargo esi list one-shot tools), and ethercat-esi-verify (diff ESI XML against captured SII EEPROM .bin dumps).
Runtime trait crate — ethercat-esi-rt: the EsiDevice / EsiConfigurable traits the generated drivers implement.

The taktora-connector-ethercat crate (see EtherCAT reference connector (FEAT_0041)) is not part of this toolchain. It sits one layer above as a thin adapter that maps any EsiDevice into the ethercat_hal::EthercatDevice trait it already consumes. No change to EtherCAT reference connector (FEAT_0041)’s runtime contracts is required by this spec.

Requirements at a glance¶

Used filter:

ID	Title	Status	Satisfies
FEAT_0051	ESI parser	implemented	FEAT_0050
FEAT_0052	IR and codegen backend trait	open	FEAT_0050
FEAT_0053	ethercrab codegen backend	open	FEAT_0050
FEAT_0054	Runtime trait surface	open	FEAT_0050
FEAT_0055	Build helper (build.rs glue)	open	FEAT_0050
FEAT_0056	CLI inspection (cargo subcommand)	open	FEAT_0050
FEAT_0057	EEPROM diff verification	open	FEAT_0050
REQ_0500	Pure parse function with no I/O	implemented	FEAT_0051
REQ_0501	no_std + alloc compatible	rejected	FEAT_0051
REQ_0502	quick-xml + serde backend	implemented	FEAT_0051
REQ_0503	Parser does not depend on ethercrab or codegen	implemented	FEAT_0051
REQ_0504	IR carries identity, PDO maps, mailbox, DC, and OD	implemented	FEAT_0051
REQ_0505	Vendor-specific extensions captured as opaque blobs	implemented	FEAT_0051
REQ_0506	Parse errors carry line and column	implemented	FEAT_0051
REQ_0510	CodegenBackend trait shape	open	FEAT_0052
REQ_0511	Naming policy is owned by codegen, not the backend	open	FEAT_0052
REQ_0512	Revision collision handled deterministically	open	FEAT_0052
REQ_0513	Common PDO entry types deduplicated	open	FEAT_0052
REQ_0514	Emission target is proc_macro2 TokenStream	open	FEAT_0052
REQ_0520	Backend crate is the sole ethercrab dependency	open	FEAT_0053
REQ_0521	One device struct per ESI device entry	open	FEAT_0053
REQ_0522	Identity const emitted per device	open	FEAT_0053
REQ_0523	Selectable PDO assignments emitted as a joint per-device OpMode enum	implemented	FEAT_0053
REQ_0524	Each OpMode variant carries a per-mode inputs/outputs data struct	implemented	FEAT_0053
REQ_0525	Generated module root exposes a registry	open	FEAT_0053
REQ_0526	Generated code compiles under no_std + alloc	open	FEAT_0053
REQ_0527	Default PDO assignment derived from Sm/Mandatory, not Fixed	implemented	FEAT_0053
REQ_0528	Per-active-mode Rx/Tx PDO-index lists exposed for 0x1C12/0x1C13	implemented	FEAT_0053
REQ_0529	AlternativeSmMapping captured faithfully, never resolved	implemented	FEAT_0051
REQ_0530	EsiDevice trait shape	open	FEAT_0054
REQ_0531	EsiConfigurable trait shape for preop bring-up	open	FEAT_0054
REQ_0532	Traits live in ethercat-esi-rt, not taktora-connector	open	FEAT_0054
REQ_0533	Object dictionary emission is a default-off cargo feature	open	FEAT_0054
REQ_0534	Process image access via bitvec BitSlice	open	FEAT_0054
REQ_0535	SdoWrite abstraction keeps ethercrab out of the trait crate	open	FEAT_0054
REQ_0540	Builder API shape	open	FEAT_0055
REQ_0541	Output written to OUT_DIR	open	FEAT_0055
REQ_0542	Cargo rerun-if directives emitted per ESI input	open	FEAT_0055
REQ_0543	Generated output passes through prettyplease	open	FEAT_0055
REQ_0550	cargo esi expand emits one device's generated code	open	FEAT_0056
REQ_0551	cargo esi list enumerates devices in a glob	open	FEAT_0056
REQ_0552	CLI shares the parser and codegen crates	open	FEAT_0056
REQ_0560	Verifier ingests ESI XML plus SII binary	open	FEAT_0057
REQ_0561	Diagnostic output names the differing field	open	FEAT_0057
REQ_0562	Verifier reuses the parser	open	FEAT_0057
REQ_0563	Verifier exits non-zero on mismatch	open	FEAT_0057
REQ_0590	NO CAN / CANopen / EDS support in this round	rejected	FEAT_0050
REQ_0591	NO proc-macro front-end	rejected	FEAT_0050
REQ_0592	NO unification of EtherCAT and CANopen runtime traits	rejected	FEAT_0050
REQ_0593	NO runtime XML parsing	rejected	FEAT_0050
REQ_0594	NO modification of taktora-connector-ethercat runtime	rejected	FEAT_0050
REQ_0595	NO automatic vendor library scraping	rejected	FEAT_0050
REQ_0843	ESI model exposes per-SM watchdog-trigger enable	implemented	FEAT_0051
REQ_0848	FMMU declarations captured in the IR	implemented	FEAT_0051
REQ_0849	EEPROM (SII source) data captured without interpretation	implemented	FEAT_0051
REQ_0850	MDP module catalog and slot constraints captured, never resolved	implemented	FEAT_0051