ARDL – AUTOSAR Design Language

Lightweight design as code for AUTOSAR Classic application software (ASW) and basic software (BSW). You write .ardl text files; VS Code checks them as you type and shows the diagrams next to the editor. Same idea as Mermaid or PlantUML, but with AUTOSAR concepts built in: ports, interface kinds, runnables, compositions, BSW layers.

interface sr Speed { Value: uint16 }

swc application LightCtrl {
    rport RpSpeed : Speed
    pport PpLamp  : LampState
    runnable R_Control every 10ms reads RpSpeed writes PpLamp
}

composition Body {
    prototype SpeedCalc
    prototype LightCtrl
    connect SpeedCalc.PpSpeed -> LightCtrl.RpSpeed
}

bsw NvM layer services uses MemIf

Three examples in examples/ describe one ECU in three feature files:

The second and third file declare no interface, component or BSW module again; they use those of the first.

Language

Without view declarations a file shows each composition, a BSW layer view if it declares BSW modules, each os and, if it has none of these, one view per SWC.

Task clauses come in any order and may span lines, like the clauses of a runnable. runs maps runnables of any file to the task (the AUTOSAR RTE event to task mapping); BSW main functions are mapped the same way, e.g. runs NvM.NvM_MainFunction. Names inside an os block are local to it. ARDL deliberately has no timing model (WCET, schedule simulation, Gantt charts): it describes the structure, and timing analysis belongs in dedicated tools.

Names are global across all .ardl files of the workspace (there are no packages or imports). A model can be split into files by feature or by kind, e.g. interfaces in one file, but every name is declared exactly once. Views have a namespace of their own, so view Body composition Body is fine.

Checks

• Assembly connectors go from a P-port to an R-port; delegation connectors from outer R to inner R or inner P to outer P.
• Compositions do not contain themselves, directly or through other compositions.
• Connected ports use the same interface; a client port connects to one server only.
• Unconnected R-ports of prototypes are warnings.
• Runnable accesses fit the port: reads a required sr/nv/param port, writes a provided sr/nv port, calls a required cs port, switches a provided mode port; same for the triggers.
• Interface members fit the interface kind.
• BSW layering: an upward uses (e.g. MCAL → services) is a warning; services using an MCAL driver directly is a hint. Complex drivers may use any layer.
• OS profile: AUTOSAR/OSEK resources use the priority ceiling protocol and there are no semaphores, an AUTOSAR/OSEK event belongs to one task; ThreadX/FreeRTOS mutexes use priority inheritance.
• OS objects: locks needs a mutex, takes/gives a semaphore, sends/receives a queue, waits/sets an event. Unused objects, queues without sender or receiver, events nobody sets or nobody waits for, and semaphores that are taken but never given are warnings.
• Priority inversion: a mutex with protocol none shared by tasks of different priority. Lock order: locks A, B in one task and locks B, A in another is a possible deadlock.
• ISRs never block (takes, receives, waits); category 1 ISRs use no OS objects; RTOS mutexes cannot be locked from an ISR.
• Runnable mapping: each runnable runs in one task; a component with some mapped runnables needs all of them mapped, except pure servers (on call only); a periodic runnable's period is a multiple of its task's period. Components without any mapping are not reported, they may belong to another ECU.
• Duplicate names, within a file and across files; unresolved references.

Views

Port symbols: triangle = sender-receiver (points in the data direction), filled circle = server, ring = client, diamond = mode (filled = manager, outline = user). Edge colors follow the interface kind.

VS Code

• Syntax highlighting, diagnostics, completion, go to definition, find references, rename.
• ARDL: Open Diagram Preview to the Side (Cmd+K V, or the preview icon in the editor title). The preview follows the active .ardl editor, refreshes as you type, has a tab per view, zoom (buttons, pinch or Cmd/Ctrl + wheel), drag to pan, and Export SVG for the current view. It uses the editor's light or dark theme.
• ARDL: Export Diagrams as SVG writes one <file>.<view>.svg per view next to the .ardl file.

Command line

npm run build
node bin/ardl.cjs check examples
node bin/ardl.cjs render examples -o out/diagrams

check prints diagnostics and exits with 1 on errors, so it fits a CI job. render writes standalone SVGs (light theme, CSS variables --ardl-* for restyling) that can go straight into a website or a Markdown document.

Development

npm install
npm run build            # Langium generator, type check, esbuild bundles in out/
npm test                 # vitest: parser, validation, rendering
npm run check:examples   # the CLI on examples/
npm run test:e2e         # the extension in a real VS Code (after build)
npm run package          # ardl-<version>.vsix
code --install-extension ardl-0.2.0.vsix --force

test:e2e downloads VS Code into .vscode-test/ on the first run, opens a copy of examples/ and checks activation, diagnostics, go to definition, completion, the preview and SVG export. ARDL_VSCODE_VERSION=1.91.0 npm run test:e2e runs it against the minimum version in engines.

Publishing

1. Bump version in package.json and add an entry to CHANGELOG.md.
2. npm run build && npm test && npm run test:e2e && npm run package.
3. npx vsce publish --packagePath ardl-<version>.vsix (needs the kuebelrobert publisher and an Azure DevOps token with Marketplace › Manage scope); for Open VSX npx ovsx publish ardl-<version>.vsix -p <token>.

The Marketplace icon media/logo.png is rendered from media/logo.svg (256 × 256), e.g. with headless Chrome: chrome --headless --screenshot=media/logo.png --window-size=256,256 --default-background-color=00000000 media/logo.svg.

To debug, open this folder in VS Code and start Run Extension (.vscode/launch.json). It builds, then opens a second window with the extension loaded and examples/ open. Attach to Language Server connects the debugger to the server process.

The generated parser and AST in src/language/generated/ are committed, so tests run right after npm install. Run npm run langium:generate (part of build) after changing the grammar.

Built on Langium (parser, language server) and ELK via elkjs (layered layout with port constraints).

License

MIT, see LICENSE.