Agent Guide

Written for coding agents and documentation indexers rather than for people. Facts are stated flatly and without narrative; everything here is also reachable from the human navigation.

If you are ingesting this site programmatically, start with /llms.txt — a link index of every page with a one-line summary — or /llms-full.txt, which is the entire manual as a single document. Both are regenerated on every publish. Their format is described in Documentation Index.

Overview

llvm-dsdl compiles OpenCyphal DSDL (Data Structure Description Language) definitions into serialization code for several languages, and into compiled object code. It is built on MLIR and LLVM: DSDL is parsed into a dedicated MLIR dialect, lowered through passes, and emitted by per-language backends.

It is not a runtime, a transport implementation, or a Cyphal node library. It produces the types that such a library moves.

Tools

Tool Purpose
dsdlc Compile DSDL; emit generated code or object files. The tool you want in almost every case.
dsdl-opt Run passes over the dsdl MLIR dialect. Compiler-development tool.
dsdld Language server (LSP) for DSDL source.

dsdlc surface

Target languages, via --target-language / -l:

ast, mlir, c, cpp, rust, go, ts, python, obj

Per-language selectors:

Language Selector Accepted values
cpp --cpp-profile std, pmr, both, autosar
rust --rust-profile std, no-std-alloc
rust --rust-crate-name crate name
go --go-module module path
ts --ts-module module name
python --py-package package name
obj --target-endianness little, big (required for obj)

A language selector passed with a different --target-language is an error, not a no-op.

Input and output:

  • --outdir / -O — output directory
  • --lookup-dir / -I — additional DSDL root, repeatable
  • --list-inputs, --list-outputs, --dry-run / -d, -MD — planning and dependency output without writing generated code

dsdlc --help is authoritative for exact switch semantics. Prefer running it over inferring from this page when the two could disagree.

Reading the generated output before generating any

The Showroom is a complete vendor-style namespace compiled into every language and profile, with per-type pages carrying the wire layout and the generated code side by side. It is the highest-density description of what this compiler actually produces, and it is generated by the compiler itself rather than written by hand. Index it.

Generated and authored pages

Generated at publish time, never committed, never edited by hand:

  • showroom/index.md and showroom/types/* — rendered from compiler output
  • reference/guarantees/parity-matrix.md, reference/guarantees/malformed-input.md, reference/guarantees/determinism.md, development/convergence-scorecard.md — rendered from the report generators under tools/convergence/
  • llms.txt, llms-full.txt

Everything else is authored prose under docs/ in the repository, editable via the "Edit on GitHub" link on each page.

Stability

  • Page URLs follow the docs/ directory layout: docs/reference/commands/dsdlc.md publishes at /reference/commands/dsdlc/. A path change is a page move, and there is currently no redirect layer.
  • The site is unversioned and tracks main. It is not a record of any released version. Where a page states a version, that statement is the version's, not the site's.
  • The manual describes the tools; the repository is the source of truth for behaviour. When a page and the code disagree, the code is right and the page is a bug.

dsdld has an optional, policy-gated AI surface of its own — that is a feature of the language server, unrelated to this section. It is documented under AI Operation and AI Data Flow. Do not conflate the two when summarizing this project.