arche-lang — pattern reference

Every construct the language accepts, with its syntax, its properties and an example. This page is generated from the language definition (src/spec.ts) by archec patterns. A complete file using every pattern is examples/patterns/patterns.arche.

The sets#

The declarations come in sets, like Go's language and its packages: the core is what every model is written with, and what to learn first; the others are for a purpose. Each declaration below says its set.

Lexical rules#

LaTeX#

Any description, requirement text, rationale or objective may contain inline math $…$ or display math $$…$$. A math property (or a ```latex / ```math block) holds raw LaTeX. The math is kept as written in the generated YAML; archec doc main.arche -o spec.tex typesets it in a complete LaTeX specification. \$ writes a literal dollar.

requirement REQ-BRK-001 "Stopping distance" {
  text "The vehicle shall stop within $d \le \frac{v^2}{2\mu g}$ on dry asphalt."
  math ```latex
  \mu \ge 0.7
  ```
}

Short forms#

Write the short form. The long one is still accepted, but the linter marks each one (long-form, a hint with its quick fix) and archec fmt --simplify --write rewrites them all without changing the generated project — so a reader only ever has to know one spelling.

component Sensor {
  out data: can "Samples" sends SAMPLE
  in cfg: can receives CONFIG
  fn main ```python
    while True:
        await wait(ms(10))
        send(self.data, SAMPLE(value=1))
  ```
}
system Rig { part s: Sensor; part c: Controller; s.data -> c.data_in "Samples" }

Types and pointers#

Built-in types: bool, uint8, int8, uint16, int16, uint32, int32, uint64, int64, float32, float64, char, byte, string, bytes, duration, timestamp, any, void — plus every type, enum and struct you declare. A type may be an array (uint8[16], Sample[]) and a pointer:

A pointer is initialised with an address, a constant or nil. In the Arche project it becomes a catalog entry ptr_T (an unsigned integer as wide as an address, unit address); a pointer field to a structure is an association in the class diagram. A pointer in a message payload is flagged: an address means nothing in the receiver's memory.

project "Firmware" { pointer-size 4 }
struct Block { size: uint32; next: *Block; data: uint8* }
component Allocator {
  var free_list: *Block = nil
  memory DMA_SRC @ 0x4000_0010 : *void rw
  fn alloc(n: uint32) -> *Block ```python
    return self.free_list
  ```
}

Python in .py files#

Code longer than a few lines reads better in a .py file, with your editor's Python support. code "ctrl.py" on a component (or a system, or the project) names the file; in the model a function's name goes where a ``` block would. archec copies each body into the Arche project, so Arche runs exactly what the same code written inline would give (archec fmt --extract-code --write moves existing blocks out, and that is tested to change nothing).

A hook's parameters are the names Arche gives it, the ones you use: a port msg, message, port, value, prev, rise, fall and the fields of the messages it receives; a state from_, to; a memory block index, value, field, writer. Imports, constants and helper functions at the top of the file are copied into the bodies that use them — a copy per body, so a top-level name cannot keep state between calls: keep it on the component (var n in the model, self.n in Python). A def's docstring becomes the function's description. from arche import * is for the editor only: archec stubs (or the VS Code extension, on its own) writes arche.py beside the .py files with Arche's helpers and the model's messages and constants.

Code edited in the Arche app comes back with archec pull main.arche --write (into the def or ``` block it came from; a build will not overwrite it until it is pulled), and Arche's errors — "(Controller › Control loop, line 4)", a line of the copy — are mapped back to the source line by archec test, archec run and archec where (and the VS Code commands Run Tests and Go to Simulator Error…).

component ctrl "Controller" {
  code "ctrl.py"
  in sense: i2c receives SAMPLE { on-receive on_sense }
  fn main "Control loop"
  fn command(rpm: Rpm)
  states {
    state Off
    state On { on-enter enter_on }      // on-exit: def on_exit_On, by its name
  }
}

# ctrl.py
from arche import *

async def main(self):
    while True:
        await wait(PERIOD)
        await self.command(self.target)

def command(self, rpm):
    send(self.bus, SPEED_CMD(rpm=rpm))

def on_sense(self, msg):
    self.last = msg

def enter_on(self):
    log("on")

def on_exit_On(self):
    log("off")

Project & files#

Splitting a specification over files, project metadata, the versioned libraries a project uses, and code generators of your own.

project#

Project metadata: name, version, authors. One per project.

• Keywords: project
• Set: the core
• Where: top level
• Syntax: project "Name" { version "1.0" … }

project "Autonomous car" {
  version "0.3"
  author "Systems team"
}

library#

A library: a folder of .arche files shared between projects, named and versioned in its library.arche. The folder is <name>/ or <name>@<version>/ in a project's libraries folder, so versions sit side by side; a project says which it accepts with uses <name> "<range>". archec lib lists what a project uses and archec lib lock records it in arche.lock.

• Keywords: library
• Set: project tooling
• Where: top level
• Syntax: library kria-parts { version "1.4.0" }

library kria-parts "KR260 parts" {
  version "1.4.0"
  archec ">=0.10"
}

translations#

The texts of the model in another language, apart: each line is an element (its id, or its path) and its name in that language, or one of its text properties (REQ-1.description), or — for a text no path names, a sequence step or a branch — the text itself ("initialisation" "start-up"), translated wherever it is written. The model's own files then read in one language; it is the same as writing en "…" after each text. archec refactor translations main.arche --extract en moves the inline ones into a file of their own. An entry that names nothing, or repeats a translation written inline, is pointed out.

• Keywords: translations
• Set: project tooling
• Where: top level
• Syntax: translations en { REQ-1 "Start"; REQ-1.text "The pump shall start."; Station.ctrl "Controller"; "démarrage" "start-up" }

translations en {
  REQ-START "Start on command"
  REQ-START.text "The pump shall start within 100 ms of a START command."
}

include#

Include another .arche file (relative path). Each file is included once; cycles are reported. Inside a system or component body, the file holds part of that body (its parts, links, functions…), read as if written where the include is — a large system split into one file per subsystem. requires "../../interfaces/spi" at the top of a file is an include that says what the file depends on: a component kept in a components/<name>/ folder (a component library) may use only what its folder declares, the standard library, and what it requires — so the folder can be copied into another project (component-not-self-contained). include "std/units", "std/buses", "std/interfaces", "std/parts" are the standard library shipped with archec; a path not found beside the file is looked for in the project's libraries.

• Keywords: include · requires (old spelling: import)
• Set: the core
• Where: top level, inside system, inside component
• Syntax: include "path/to/file.arche"

include "common/messages.arche"

package#

package chassis on its own line, first in a file, puts the whole file in the package, as in Go; package chassis { … } groups part of one. A group of declarations — components, messages, types, requirements — under one name, so a large model reads by part. Inside, names are written as usual; from anywhere, chassis.BrakeEcu names one explicitly (a bare BrakeEcu works too). Arche ids are global, so a name is still declared once in the whole project: a package groups and qualifies, it does not let two things share an id. include inside a package puts that file's declarations in it.

• Keywords: package (old spelling: namespace)
• Set: the core
• Where: top level
• Syntax: package name (the rest of the file is in it, as in Go) | package name { declarations… }

package chassis {
  message BRAKE_CMD { force: float32 }
  component BrakeEcu { in can: can receives BRAKE_CMD }
}
system Car { part brakes: chassis.BrakeEcu }

raw#

A file of the project that Arche does not define: data "file.yaml" = { … } writes the value as YAML (a record, a list), checked as any value is; `raw "file.yaml" ```yaml … ```` writes the text verbatim — the escape hatch for anything the language does not model yet.

• Keywords: raw · data
• Set: project tooling
• Where: top level
• Syntax: `data "file.yaml" = { key: value, … } | raw "file.yaml" ```yaml … ````

raw "plots.yaml" ```yaml
version: 1
plots: []
```

file#

Fields of a generated file itself (its top level), with attr: file "requirements.yaml" { attr version = nil }.

• Keywords: file
• Set: project tooling
• Where: top level
• Syntax: file "name.yaml" { version 1; attr key = value }

file "deliverables.yaml" { attr version = 1 }

generator#

A code generator of your own, run as archec gen --target <id> beside the built-in targets. It reads the generator model — the project as JSON, every name resolved, each message's layout on the wire, each element's file and line (schemas/generator-model.v1.json) — and returns files. Three kinds: templates "folder" (text files with {{ }} placeholders), script "gen.js" (module.exports = function generate(model, ctx) { … }, run in a sandbox) or command "python3 gen.py" (any language: the model as JSON on stdin, the files as JSON on stdout). from <generator> is another one with other options: how a project sets those of a generator a library ships. Its files go to <output>/<id>/, never over one marked keep that exists.

• Keywords: generator
• Set: project tooling
• Where: top level
• Syntax: generator id "Label" [from base] { templates "dir" | script "gen.js" | command "…"; option k "…" { type string; default v }; options { k v }; builtins c; after c; needs deployment; output "dir"; api 1 }

generator rte "RTE glue" {
  templates "generators/rte"
  options { prefix "kc_" }
  needs deployment
}

importer#

An importer of your own: a file of another tool read into arche-lang, run as archec import <file> when its extensions match one no built-in importer reads (or --importer <id>). A script "import.ts" (export default function importFile(input, ctx), sandboxed: ctx.readFile reads the imported file's folder and the plugin's own, nothing else) or a command "python3 x.py" (the input as JSON on stdin) returns .arche files with notes and errors; archec writes them and checks them. Usually in a plugin (docs/plugins.md).

• Keywords: importer
• Set: project tooling
• Where: top level
• Syntax: importer id "Label" [from base] { script "import.ts" | command "…"; extensions ".x", ".y"; option k "…" { type string; default v }; options { k v } }

importer melody "Melody CCM" {
  script "import.ts"
  extensions ".ccmproject"
}

exporter#

An exporter of your own: the model written as a file of another tool, run as archec export <main.arche> --format <id> -o out.x (or picked by -o's ending). It reads the generator model (the same JSON, version 1) and returns files, as a generator does: templates, a script or a command. Usually in a plugin (docs/plugins.md).

• Keywords: exporter
• Set: project tooling
• Where: top level
• Syntax: exporter id "Label" [from base] { templates "dir" | script "export.ts" | command "…"; extension ".x"; option k "…" { type string; default v }; options { k v }; needs deployment }

exporter melody "Melody CCM" {
  script "export.ts"
  extension ".ccmproject"
}

option#

An option of a generator, declared: its type, its default, the values it may take, what it is for. archec check holds what a generator started from it (or --option) sets to it — an option it does not declare, a value of the wrong type or not among its values; its default goes into the model's options when nothing sets it; the editor completes and explains it in options { }; archec gen --list lists it.

• Keywords: option
• Set: project tooling
• Where: inside generator, inside importer, inside exporter
• Syntax: option name "What it is for" { type string|int|float|bool|list; default v; values a, b }

option prefix "The prefix of the C names" { type string; default "kc_" }

Catalogs#

The project vocabulary: kinds, layers, tags, colors and port types. Undeclared kinds, layers and tags that are used are added automatically.

kind#

An element kind for the kinds catalog (kinds.yaml).

• Keywords: kind
• Set: the core
• Where: top level
• Syntax: kind id "Label" { icon "«P»" }

kind ecu "ECU" { icon "«E»"; description "Electronic control unit." }

layer#

An abstraction layer (layers.yaml). Declare most abstract first: the order is the meaning.

• Keywords: layer
• Set: the core
• Where: top level
• Syntax: layer id "Label"

layer logical "Logical"
layer physical "Physical"

tag#

A tag for the tag catalog (tags.yaml).

• Keywords: tag
• Set: the core
• Where: top level
• Syntax: tag id "Label" { group status }

tag safety "Safety-critical" { group domain; color red }

color#

A palette color (colors.yaml). One value, or light/dark per theme.

• Keywords: color (old spelling: colour)
• Set: the core
• Where: top level
• Syntax: color id = "#rrggbb" | color id { light "#…"; dark "#…" }

color brand = "#0b6e4f"
color alert { light "#c62828"; dark "#ef5350" }

port-type#

A port type (types.yaml): the kind of connection a port offers, with its wires and timing.

• Keywords: port-type (old spellings: porttype, bus)
• Set: the core
• Where: top level
• Syntax: port-type id "Label" { color …; handling message; wire … }

port-type can-fd "CAN FD" {
  color amber
  handling message
  bitrate 2Mbps
  wire canh "CAN_H" inout
  wire canl "CAN_L" inout
}

wire#

One conductor of a port type.

• Keywords: wire
• Set: the core
• Where: inside port-type
• Syntax: wire id "Name" [in|out|inout] { signal "3V3 CMOS" }

wire sclk "SCLK" out { signal "3V3 CMOS" }

Data#

Types, constants and the message catalog.

type#

A named data type (data-types.yaml) — a built-in read in a unit, with an optional range. type Iq native { … } is a type the code provides: its name in each language and the header (C, C++), or the module (Go), that declares it — the generated code uses it as it is (PYCOGEN's native types).

• Keywords: type
• Set: the core
• Where: top level
• Syntax: type Id = base [unit u] [range lo..hi] | type Id native { c "name" include "h.h"; cpp "ns::Name" include "h.h"; rust "crate::Name"; go "pkg.Name" import "path" }

type Speed = float32 unit km/h range 0..250

type Iq native "IQ sample" {
  cpp "dsp::Iq" include "dsp/iq.h"
  rust "dsp::Iq"
}

enum#

An enumeration (data-types.yaml). Literals in order; = n when the encoding is not the position.

• Keywords: enum
• Set: the core
• Where: top level
• Syntax: enum Id { A, B = 4, C }

enum DriveMode { MANUAL, ASSISTED, AUTONOMOUS = 4 }

struct#

A structure (data-types.yaml). Fields are name: Type, optionally with unit, range, default; optional T is a field that may be absent (multiplicity 0..1). union Command { stop; move: MoveArgs; speed: float32 } holds one of its cases: a bare name has no payload, name: Type carries one. Arche gets a struct with a case field (the enum CommandCase) and one optional field per payload; archec gen embassy writes a Rust enum. exception NotFound { id: uint32 } is a struct an operation raises (IDL's exception): what it carries is its fields.

• Keywords: struct · union · exception (old spelling: record)
• Set: the core
• Where: top level
• Syntax: struct Id [extends Base] { name: [optional] Type [= default] [unit u] } | union Id { case; case: Type } | exception Id { name: Type }

struct ImuSample {
  ts: uint64 unit ns
  accel: float32[3] unit m/s²
  gyro: float32[3] unit rad/s
}

field#

A field of a struct, message or memory record. The field keyword is optional: name: Type. = value is its default: a message built without the field (BRAKE_CMD(force=1.0)) carries it, and a struct field with no default of its own is built from its fields' defaults — so header: Header needs writing only when it differs.

• Keywords: field
• Set: the core
• Where: inside struct, inside message, inside memory, inside field, inside icd
• Syntax: name: Type [= default] ["Label"] [unit u] [range lo..hi] [bits "7:0"] — in a message: [at n] [bits n] [scale x] [offset x] [signed] [checksum crc8] [counter]

enable: uint8 bits "0:0"

const#

A project constant (variables.yaml): readable by name from every piece of behaviour code. Durations become ns.

• Keywords: const (old spelling: constant)
• Set: the core
• Where: top level
• Syntax: const NAME [: Type] = value [unit u]

const MAX_SPEED = 130 unit km/h
const WATCHDOG = 50ms

message#

A message of the project catalog (messages.yaml): a scalar payload (: float32), a struct (: ImuSample) or inline fields. A message with fields may say its exact wire format, as a CAN DBC does: byte-order and size on it, at, bits, scale, offset, signed, checksum, counter on its fields. The DBC, the ICD and the C, Rust, Go and Python codecs (archec gen --target wire) then put each field on its bits.

• Keywords: message (old spelling: msg)
• Set: the core
• Where: top level
• Syntax: message ID ["Name"] [: Type] { field: Type … }

message BRAKE_CMD "Brake command" {
  force: float32 unit N
  emergency: bool
}

Operational & requirements#

Who uses the system, what it is for, what it shall do, and the documents that say so.

actor#

An external entity that interacts with the system (actors.yaml).

• Keywords: actor
• Set: functional analysis & scenarios
• Where: top level
• Syntax: actor id "Name" { description "…" }

actor driver "Driver" { description "Supervises the vehicle and can take over." }

mission#

A high-level goal the system must fulfil (missions.yaml).

• Keywords: mission (old spelling: goal)
• Set: functional analysis & scenarios
• Where: top level
• Syntax: mission id "Name" { involves [actors] }

mission reach-destination "Reach the destination safely" { involves driver, passenger }

requirement#

A requirement. Top-level ones go to requirements.yaml; nested ones stay on their element.

• Keywords: requirement (old spelling: req)
• Set: the core
• Where: top level, inside component, inside system, inside port, inside fn, inside link
• Syntax: requirement ID "Name" { text "The system shall …" priority high … }

requirement REQ-BRK-001 "Emergency braking distance" {
  text "The vehicle shall stop within $d \le \frac{v^2}{2\mu g} + v\,t_r$."
  priority critical
  method test
  verified-by TP-AEB
}

verify#

How it is verified (IVV): at which level, with which means, by which procedure, and the test cases that do it.

• Keywords: verify (old spelling: ivv)
• Set: the core
• Where: inside requirement, inside component, inside system, inside link
• Syntax: verify { level integration; means "…"; procedure "…"; tests TC-1, TC-2 }

verify {
  level integration
  means "Integration bench" fr "Banc d'intégration"
  procedure "Type POINT 10 20: one OK line."
  tests TC-OPS-01
}

means#

A means of verification (a bench, a simulator, a tool) named once: verify { means bench } then says it by name, and Arche gets its text (and translations) as if written there.

• Keywords: means
• Set: functional analysis & scenarios
• Where: top level
• Syntax: means id "What it is" [en "…"]

means bench "Banc d'intégration KR260" en "KR260 integration bench"

defaults#

Values the requirements (or verify blocks…) of this file share, written once: each one that does not set a property takes it from here. At the top of a file it covers the whole file; inside a component or system, that block and what it contains, in this file. The nearest defaults wins, and an element's own value always does. The generated project is the same as if each element wrote them.

• Keywords: defaults
• Set: the core
• Where: top level, inside component, inside system
• Syntax: defaults requirement { status draft; method test; document SRS }

defaults requirement { status draft; method test; document SRS }

decision#

A design decision (an architecture decision record): the context, the options weighed, the one chosen and why, what it answers and what it affects. Written to Arche as a requirement of category decision — listed, linked and documented with the requirements — with answers as a derives trace and affects as satisfies traces from the elements that carry it out.

• Keywords: decision (old spelling: adr)
• Set: safety, security & design space
• Where: top level
• Syntax: decision ADR-n "Title" { status accepted; context "…"; option "A"; option "B"; chosen "A"; because "…"; answers REQ-…; affects element… }

decision ADR-007 "A lockstep core owns the brake path" {
  status accepted
  context "The emergency brake must survive a single core fault."
  option "Lockstep core"
  option "Two independent MCUs"
  chosen "Lockstep core"
  because "One part, diagnostics in hardware, no voting software."
  answers REQ-SAF-001
  affects Car.adcu.brakes_path
}

deliverable#

A document the project delivers — a specification, an ICD, a design (deliverables.yaml). The Documentation page assembles each one from the model: the requirements whose document names it and what it covers.

• Keywords: deliverable
• Set: functional analysis & scenarios
• Where: top level
• Syntax: deliverable ID "Name" { group "Software" kind specification status draft covers [REQ-1] }

deliverable SRS "Software Requirements Specification" {
  kind specification
  status draft
  group "Software"
  version "0.3"
}

Structure#

Systems (model files), components, their ports and the links between them, and the contracts the two ends of a link agree on.

system#

A model — one Arche model file. Its children are the root components of the canvas; links connect them.

• Keywords: system (old spelling: model)
• Set: the core
• Where: top level
• Syntax: system Id "Name" { component … ; part x: Def ; a.p -> b.q }

system Car "Autonomous car" {
  layer physical
  part lidar: Lidar
  part fusion: FusionEcu
  lidar.cloud -> fusion.lidar_in
}

component#

A component. At top level it is a reusable definition (templates.yaml); inside a system or component it is a child — part x: Def instantiates a definition, {…} overrides it. component LidarFront extends Lidar { … } is a definition built on another: it has the base's kind, ports, functions, variables, parameters and state machine, and what it writes adds to them or replaces them (by id); its state machine adds states and transitions to the base's.

• Keywords: component · part (old spellings: block, subsystem, device, processor)
• Set: the core
• Where: top level, inside component, inside system
• Syntax: component id ["Name"] [extends Base | : Definition] { kind …; port …; fn …; var …; memory …; states { … } }

component Lidar "Lidar" {
  purpose "Scans the scene"
  kind device
  out cloud: ethernet sends POINT_CLOUD
  in pwr: power
  fn scan ```arche
    send cloud POINT_CLOUD { points: 1 }
  ```
}

port#

A port: a link endpoint with a type and direction. sends lists catalog messages; = child.port delegates to a child. port id: T is a port that says no direction.

• Keywords: port · in · out · inout
• Set: the core
• Where: inside component, inside system, inside system-function
• Syntax: in|out|inout id: [requires|provides] type ["Name"] [sends MSG, …] { handler … } | port id = child.port

inout can0: can-fd "CAN" sends BRAKE_CMD receives WHEEL_SPEED

interface#

A contract a port takes part in: the messages that may cross it and the operations a provider implements (an Arche port type with messages and operations, in types.yaml). A port says provides I or requires I; a link whose one end requires what the other does not provide is reported, and so is a provider without a function for each operation. extends adds another interface's messages and operations. In a ```arche body, port.op(…) on a port that requires it calls the operation of the part at the other end of the link (docs/spec.md, Calling another part). As in IDL: an argument is in (the default), out or inout; oneway fn has no result and the caller does not wait; raises E1, E2 names the exceptions it may raise; attribute x: T (readonly attribute) is a value the provider holds.

• Keywords: interface (old spelling: contract)
• Set: the core
• Where: top level
• Syntax: interface Id "Name" { messages A, B; extends Base; [readonly] attribute x: T; [oneway] fn op([in|out|inout] arg: Type) [-> Type] [raises E, …] }

exception Busy { reason: string }

interface BrakeApi "Brake API" {
  messages BRAKE_CMD, BRAKE_STATUS
  readonly attribute applied: uint16
  fn apply(force: float32) -> bool raises Busy
  fn status(out force: float32)
  oneway fn reset()
}
component BrakeEcu {
  in can: can-fd provides BrakeApi
  fn apply(force: float32) -> bool ```arche
    return true
  ```
}

contract#

What a component (or an interface, or a port type) assumes of what it receives and guarantees of what it sends. A clause is a condition on a port's message fields or on a variable: cmd.force in 0..1000N, status.mode == 2, out.level <= 5V, conditions joined by and; always and eventually may open it, within 20ms [after cmd] may close it. At each link a.p -> b.q, what a guarantees on p must imply what b assumes on q: ranges and equalities on the same field, in the same unit (time units are converted, others are not), and deadlines (a guarantee within 20ms meets an assumption within 50ms). An unmet assumption is contract-unmet; one archec cannot decide is contract-unknown. On an interface or a port type, the clauses name the message (BRAKE_CMD.force) or the field, and hold on every port that takes part in it: guarantees where it sends, assumptions where it receives. Arche has no place for contracts: they stay in the model (and in archec sysml).

• Keywords: contract
• Set: the core
• Where: inside component, inside system, inside interface, inside port-type
• Syntax: contract { assume <cond> [and <cond>…]; guarantee [always|eventually] <cond> [within 20ms [after port]] } — cond: path in lo..hi | path ==|!=|<|<=|>|>= value | [not] path

component BrakeEcu {
  in cmd: can-fd receives BRAKE_CMD
  out status: can-fd sends BRAKE_STATUS
  contract {
    assume cmd.force in 0..1000N
    guarantee status.applied within 20ms after cmd
  }
}

handler#

What an in port answers: an HTTP route (POST "/boot" -> boot) or a message (BRAKE_CMD -> apply).

• Keywords: handler (old spelling: on)
• Set: the core
• Where: inside port
• Syntax: handler METHOD "/path" -> fn | handler MESSAGE -> fn

handler POST "/api/v1/boot" -> boot
handler BRAKE_CMD -> apply_brake

link#

A link between two ports (or components) in this scope. link is optional: a.p -> b.q works on its own line.

• Keywords: link (old spelling: connect)
• Set: the core
• Where: inside component, inside system
• Syntax: a.port -> b.port ["Name"] [{ latency 2ms }] — type and messages come from the ports; : porttypeandcarries M, … override them

lidar.cloud -> fusion.lidar_in "Point cloud" { latency 2ms }
link chassis adcu.can0 -> brakes.can "Brake CAN" { carries BRAKE_CMD }

icd#

A message of the link's interface control document, as the link carries it: its fields (name: Type). Without one, the ICD lists the messages the link carries.

• Keywords: icd
• Set: functional analysis & scenarios
• Where: inside link
• Syntax: icd id "Name" { field: Type; … }

icd m1 "Pointing" { Azimuth: float64; Elevation: float64 }

canvas#

Where the blocks of a system (or a component definition) sit on the canvas, kept apart from its structure: one line per block, path at x, y [size w, h]. Dragging a block in the diagram writes here when the system has one. (Not to be confused with project { layout … }, the Arche app's left pane.) A block placed here takes no at of its own.

• Keywords: canvas
• Set: functional analysis & scenarios
• Where: top level
• Syntax: canvas System { part at x, y; part.child at x, y size w, h }

canvas Car {
  lidar at 40, 40
  adcu at 420, 200 size 260, 240
}

Behaviour#

Functions, data, memory maps and state machines, and the events a machine reacts to that are not messages. Code blocks are Python, as Arche runs it.

fn#

A function the component exposes. private fn hides it. main runs at t=0 as the component's thread.

• Keywords: fn (old spellings: function, operation)
• Set: the core
• Where: inside component, inside system, inside interface
• Syntax: fn name ["Label"] ([in|out|inout] arg: Type, …) [-> Type] [raises E, …] ```arche … ``` | fn name { calls …; ```arche … ``` } | oneway fn name(…) (```python for Python)

fn apply_brake(force: float32) ```arche
  pressure = force * GAIN
```

fn actuate(p: *Valve) -> bool {
  calls apply_brake
  ```arche
  return true
  ```
}

var#

A component variable; its value is the initial value. In an interface, attribute x: T is a value its provider holds and a client may read (and write, unless readonly attribute): IDL's attribute.

• Keywords: var · attribute (old spellings: variable, let)
• Set: the core
• Where: inside component, inside system, inside interface
• Syntax: var name[: Type[n]] [= value] [unit u] (no type: any type, written as none in Arche) | [readonly] attribute name: Type (in an interface)

var retries: uint8 = 3
var thresholds: float32[4] = [0.1, 0.2, 0.4, 0.8]

memory#

A memory block / register map: size × count at an address, optionally a record of bitfields. On a processor, a memory with no type and no address is one of its memories: memory ddr { size 2GiB } (shared when other processors reach it, else local) — what a deployment's allocators are in.

• Keywords: memory (old spellings: register, regs)
• Set: the core
• Where: inside component, inside system
• Syntax: memory NAME @ 0x4000_0000 : uint32[8] rw { field: uint8 bits "7:0" }

memory CTRL @ 0x4000_0000 : uint32 rw {
  enable: uint8 bits "0:0"
  mode: uint8 bits "3:1"
}

states#

The component's state machine. It starts in its first state (initial X starts it elsewhere); A -> B on trig [guard] / action are transitions. The linter walks it: a state nothing reaches (unreachable-state), a state with no way out that is not pseudo final (deadlock-state; a state every state falls into, * -> Fault, is a safe state and may be one), a transition on a message no input port receives or with a guard that is false (dead-transition), one that an earlier unguarded one on the same trigger always beats (shadowed-transition), and two guarded ones whose guards may hold together (nondeterministic). archec gen --target uppaal (or nusmv) hands it to a model checker.

• Keywords: states (old spellings: statemachine, machine)
• Set: the core
• Where: inside component, inside system
• Syntax: states { state A; state B { state B1 }; A -> B on go [ready] / start() }

states {
  state Off "Powered off"
  state On { state Idle; state Driving }
  Off -> Idle on power_on
  Idle -> Driving on go [speed_ok] / engage()
}

state#

A state. Nest states for a statechart; pseudo makes a pseudo-state.

• Keywords: state (old spelling: mode)
• Set: the core
• Where: inside states, inside state
• Syntax: state id ["Name"] { on-enter ```arche …```; state child … }

state Driving "Autonomous driving" {
  on-enter ```arche
    log "engaged"
  ```
}

transition#

A transition A -> B on trigger [guard] / action. With a deadline, a trigger the part starts on too late (a message later than that after it was sent, a timer later than that after it ran out) runs on-deadline instead of the transition — as Lingua Franca's deadlines.

• Keywords: (no keyword)
• Where: inside states, inside state
• Syntax: A -> B [as id] [on trigger] [[guard] | when "guard"] [/ action] [{ deadline 10ms; on-deadline ```arche … ``` }]

Idle -> Driving on go [speed_ok] / engage()

event#

An event a state machine reacts to that is not a message: Idle -> Run on dry_run. Declared, a trigger that names it is not a typo (the linter warns on a trigger that is neither a message, nor an event, nor a member of its part — unknown-trigger). It has no payload and is not sent on a port: the generated C machine takes it as one of its events (…_fire(self, CTRL_EV_DRY_RUN)); the simulation fires only messages, so a test or a panel raises it. Declared in a component, it is that component's.

• Keywords: event
• Set: functional analysis & scenarios
• Where: top level, inside component, inside system
• Syntax: event id ["Name"] [{ description "…" }]

event dry_run "Dry run" { description "The operator asks for a run without water." }

Deployment#

Where and in what the parts run: processors and their cores, containers, binaries, processes, threads and interrupts, the bus each link takes, latency chains, and the watchdogs a part keeps. A deployment is kept apart from the system it places, so the logical model does not change. How two parts talk — pattern and buffer on ports and links — is in the port and link properties; a deadline is on a port or a transition.

core#

A named core of a processor — a place a thread can run. cores N declares N identical ones (cpu0 …); core names a special one (an accelerator, a lockstep safety core).

• Keywords: core
• Set: deployment
• Where: inside component
• Syntax: core id ["Name"] { type "Cortex-R52" }

core safety "Safety island" { type "Cortex-R52" }

deployment#

Where and in what the parts of a system run: binaries placed on processors, their processes and threads, and the bus each link takes. Kept apart from the system, like canvas, so one system can have several deployments. Emitted to processes.yaml, threads.yaml, tasks.yaml and containers.yaml, thread: on each part, and link timing.

• Keywords: deployment
• Set: deployment
• Where: top level
• Syntax: deployment Id ["Name"] { system Sys; platform Hw; binary b on cpu { process p { thread t { runs part } } }; container c "image" on cpu { binary … }; route a.p -> b.q over bus }

deployment Vehicle "L4 stack on the vehicle" {
  system Car
  platform CarHw
  binary adas "adas-stack" on adcu_soc {
    process driving {
      core cpu2
      thread drive { runs adcu; priority 80 }
    }
  }
  route adcu.can_brake -> brakes.can over chassis_can { priority 3 }
}

container#

An OCI container on a Linux processor whose runtime is containerd (or docker / podman): its image after the id, the cores and memory its cgroup allows, its network and the devices it sees. Its binaries run in it — they take its on. In the Arche project it is an entry of containers.yaml (processor, cpuset, memory-limit, network, image), and its processes and threads say container:. archec gen --target containerd writes a Containerfile per container and a compose file for nerdctl compose, --target k8s a Kubernetes Deployment pinned to its processor's node.

• Keywords: container
• Set: deployment
• Where: inside deployment
• Syntax: container id "registry/image:tag" on processor { core cpu2, cpu3; memory-limit 4GiB; network host; binary … }

container perception "registry.local/adas/perception:1.4" on adcu_soc {
  core cpu2, cpu3
  memory-limit 4GiB
  network host
  capabilities sys_nice
  binary planner {
    language rust
    thread drive { runs adcu; priority 80; policy fifo }
  }
}

binary#

What is built and installed: one executable or firmware image, placed on a processor of the platform — or written inside a container, which it runs in and takes its on from. On an rtos / bare-metal processor it is one address space: write its threads directly in it (they become RTOS tasks).

• Keywords: binary (old spellings: executable, firmware)
• Set: deployment
• Where: inside deployment, inside container
• Syntax: binary id ["file name"] on processor { process … ; thread … }

binary brake_fw "brake.elf" on brake_mcu {
  thread ctl { runs brakes; period 1ms; step regulate; priority 10 }
}

process#

An address space and fault boundary inside a binary (processes.yaml). Arche pins a process to one core: a thread with a core of its own is placed on it directly.

• Keywords: process (old spelling: partition)
• Set: deployment
• Where: inside binary
• Syntax: process id ["Name"] { core cpu0; memory-limit 512MiB; thread … }

process driving {
  core cpu2
  memory-limit 4GiB
  thread drive { runs adcu; priority 80 }
}

thread#

A unit of scheduling (threads.yaml, or tasks.yaml on an RTOS). It runs parts: their functions, handlers and state machine execute on it, one at a time. With a period it is time-triggered and calls step each period; without one it wakes on each message.

• Keywords: thread (old spelling: task)
• Set: deployment
• Where: inside binary, inside process
• Syntax: thread id ["Name"] { runs part, …; priority 50; period 10ms; step fn; core cpu1; deadline 8ms }

thread ctl "Brake control" { runs brakes; period 1ms; step regulate; priority 10 }

isr#

An interrupt service routine: a thread started by an interrupt, above every task of its core.

• Keywords: isr (old spelling: interrupt)
• Set: deployment
• Where: inside binary, inside process
• Syntax: isr id ["Name"] { runs part; irq 42; wcet 20us; min-interval 1ms }

isr can_rx { runs brakes; irq 42; wcet 15us; min-interval 500us }

route#

The bus a link of the system takes when its two ends run on different processors. Simulated as a shared medium: one transfer at a time, by priority.

• Keywords: route
• Set: deployment
• Where: inside deployment
• Syntax: route a.port -> b.port over bus { priority 3; id 0x120 }

route adcu.can_brake -> brakes.can over chassis_can { priority 3; id 0x120 }

chain#

A cause-effect chain through parts of the system, with a latency budget: the analysis adds up execution, waiting for periods and transport along it, and warns past the budget.

• Keywords: chain
• Set: deployment
• Where: inside deployment
• Syntax: chain id ["Name"] { through a, b, c; budget 100ms }

chain obstacle "Obstacle to brake command" { through adcu, brakes; budget 100ms }

watchdog#

A timer the part restarts with kick <name> in a ```arche body: armed when the part starts, it runs out timeout after the last kick, and then on-timeout runs, once — until the next kick arms it again. As Lingua Franca's watchdogs. Simulated (archec sim), and generated in C (archec gen --target c) and in Rust (--target embassy: an embassy_time timer in the part's task); archec difftest compares the C with the simulator.

• Keywords: watchdog
• Set: deployment
• Where: inside component, inside system
• Syntax: watchdog name ["Label"] { timeout 50ms; on-timeout ```arche … ``` }

watchdog link "Link lost" {
  timeout 50ms
  on-timeout ```arche
    goto Lost
  ```
}

allocator#

A memory allocator of a deployment: a pool of blocks of one size, a partition, a flipflop (two buffers in turn), a heap or static memory — in a processor's memory, inside another allocator (parent). In a process it is that process's own; in a binary or the deployment, shared makes it reachable from several. Parts, ports and algorithms take their memory from allocators through a place.

• Keywords: allocator
• Set: deployment
• Where: inside deployment, inside binary, inside process
• Syntax: allocator id ["Name"] { kind pool; block-size 4KiB; blocks 16; memory cpu.ddr; alignment 64; parent heap; shared; mapped }

allocator frames "Frame buffers" { kind pool; block-size 4KiB; blocks 16; memory cpu.ddr }

place#

How one part (or one port) of the system executes and where its memory comes from, in a deployment. In a process, a part no thread runs is placed in it with no thread of its own: execution passive (it runs in its callers' threads) or protected (one caller at a time). memory hrt|lrt <allocator> is its memory for real-time and non-real-time data, memory saved|tmp <allocator> an algorithm's working memory, memory comm <allocator> its ports' (parameters marshalled into a queue); on a port, its buffering.

• Keywords: place
• Set: deployment
• Where: inside deployment, inside binary, inside process
• Syntax: place part[.port] { execution passive|protected|active; memory hrt pool; memory comm pool; buffering { … } }

place split.input {
  memory comm frames
  buffering { max-size 4KiB; transfer copy; destroy after-processing; allocator frames }
}

Safety#

Hazards and safety goals (ISO 26262, written to safety.yaml as Arche reads them), failure modes and fault-tree gates (checked, and typeset in the LaTeX specification). The error model of the parts — produces, contains, turns, from on their ports — gives each hazard with error … on … a derived fault tree, and an FMEA row per error source (archec safety). STPA: control actions between the parts, their unsafe control actions of the four types, each traced to hazards and constraints, and the loss scenarios behind them.

hazard#

A hazardous event (ISO 26262-3): what the system does, in which situation, rated for severity (S0–S3), exposure (E0–E4) and controllability (C0–C3) — its ASIL is derived from the three, never written. goal names the safety goal that answers it. caused-by lists the failure modes and gates that lead to it (OR); with target (per hour) the probability of the top event is checked. Written to safety.yaml (hazards).

• Keywords: hazard
• Set: safety, security & design space
• Where: top level
• Syntax: hazard id "Label" { situation; effect; item }

hazard HZ-01 "Unintended braking" {
  situation "Motorway, 130 km/h"
  effect "Rear-end collision"
  severity S3
  exposure E4
  controllability C3
  goal SG-01
  caused-by FM-VALVE, G-PUMPS
  target 1e-8
}

safety-goal#

A safety goal: the top-level safety requirement answering hazards, with the state the system must reach and the time it has (FTTI). Its ASIL is the highest of its hazards'; one written lower is reported. Written to safety.yaml (safetyGoals).

• Keywords: safety-goal
• Set: safety, security & design space
• Where: top level
• Syntax: safety-goal id "Label" { safe-state; ftti; asil }

safety-goal SG-01 "No braking without a demand" { safe-state "Brake pressure released"; ftti 100ms }

failure-mode#

A failure mode (FMEA): what fails, of which element, with what effect; rated for severity, occurrence and detection (1–10, their product is the RPN), with its probability per hour for fault trees. Checked and typeset in the LaTeX specification; Arche has no place for it yet.

• Keywords: failure-mode
• Set: safety, security & design space
• Where: top level
• Syntax: failure-mode Id "What fails" { of element; effect "…"; severity 9; occurrence 3; detection 4; probability 1e-7; causes HZ-…; mitigated-by … }

failure-mode FM-VALVE "Brake valve stuck open" {
  of Car.brakes
  effect "Pressure on one wheel without a demand"
  severity 9
  occurrence 3
  detection 4
  probability 1e-7
  causes HZ-01
}

gate#

A fault-tree gate: all A, B fails when every one does (probability: the product), any A, B when one does. A hazard's caused-by and other gates name it.

• Keywords: gate
• Set: safety, security & design space
• Where: top level
• Syntax: gate Id "Event" { all A, B } | gate Id "Event" { any A, B }

gate G-PUMPS "Both pumps fail" { all FM-PUMP-A, FM-PUMP-B }

control-action#

A control action (STPA): what a controller (from, a part) commands of the process it controls (to, a part), over the links of the architecture, and what it learns back (feedback). Its unsafe control actions (uca) are written in it, one for each of the four ways a control action can be unsafe — or the type is said not-applicable. Checked and typeset by archec (archec safety); Arche has no place for it yet.

• Keywords: control-action
• Set: safety, security & design space
• Where: top level
• Syntax: control-action Id "What" { from controller; to process; carries MSG; feedback MSG; not-applicable timing; uca … }

control-action CA-BRAKE "Apply the brakes" {
  from Car.adcu
  to Car.brakes
  carries BRAKE_CMD
  feedback WHEEL_SPEED
  not-applicable duration
  because "The brakes release on their own when the command stops."
  uca UCA-1 "No braking with an obstacle within the stopping distance" {
    type not-provided
    causes HZ-01
    constraint REQ-SAF-1
  }
}

uca#

An unsafe control action (STPA), in its control action: in which context giving it — or not — is hazardous. Of one of four types: not-provided (not given when needed), provided (given when it causes a hazard), timing (too early, too late, out of order), duration (stopped too soon, applied too long). It names the hazards it leads to (causes) and the constraint that prevents it (constraint, a requirement). Its loss scenarios — how it could happen — are written in it.

• Keywords: uca
• Set: safety, security & design space
• Where: inside control-action
• Syntax: uca Id "Unsafe when" { type not-provided; context "…"; causes HZ-…; constraint REQ-…; loss-scenario … }

uca UCA-1 "No braking with an obstacle within the stopping distance" {
  type not-provided
  context "Obstacle ahead, closer than the stopping distance"
  causes HZ-01
  constraint REQ-SAF-1
}

loss-scenario#

A loss scenario (STPA), in its unsafe control action: how it could come about — a controller that decides wrong, feedback that is missing or wrong, an actuator or a process that does not do what it is told — and the constraint that prevents it.

• Keywords: loss-scenario
• Set: safety, security & design space
• Where: inside uca
• Syntax: loss-scenario Id "How" { factor feedback; constraint REQ-… }

loss-scenario LS-1 "The radar misses the obstacle in heavy rain" {
  factor feedback
  constraint REQ-SAF-2
}

Cybersecurity#

A threat analysis and risk assessment (ISO/SAE 21434): assets, damage scenarios, threats and attack paths (rated, checked and typeset by archec — archec tara), and security goals (Arche requirements of category security).

asset#

A cybersecurity asset (ISO/SAE 21434 TARA): something worth protecting — a message, a function, a key, the data of a part — and the properties of it an attack can break. Checked and typeset by archec (archec tara); Arche has no place for it yet.

• Keywords: asset
• Set: safety, security & design space
• Where: top level
• Syntax: asset Id "What" { of element; properties integrity, availability }

asset AS-BRAKE "Brake commands" { of Car.adcu.can_brake; properties integrity, availability }

damage-scenario#

A damage scenario: what happens to the road user when a property of an asset is broken, rated by impact category (severe, major, moderate, negligible). Its impact is the worst of its ratings.

• Keywords: damage-scenario
• Set: safety, security & design space
• Where: top level
• Syntax: damage-scenario Id "What happens" { asset AS-…; property integrity; safety severe; financial …; operational …; privacy … }

damage-scenario DS-BRAKE "Unintended full braking on the motorway" { asset AS-BRAKE; property integrity; safety severe; operational major }

threat#

A threat scenario: how an attacker brings a damage scenario about, through which entry point and from how far (vector). Its risk (1–5) comes from the impact of what it damages and the feasibility of its easiest attack path; its CAL from the impact and the vector. A risk of 4 or 5 needs a treatment, and reduce a security goal.

• Keywords: threat
• Set: safety, security & design space
• Where: top level
• Syntax: threat Id "How" { damages DS-…; stride spoofing; via element; vector network; treatment reduce; goal CSG-… }

threat TS-SPOOF "Spoofed brake commands on the chassis CAN" {
  damages DS-BRAKE
  stride spoofing
  via Car.chassis_can
  vector adjacent
  treatment reduce
  goal CSG-01
}

attack-path#

An attack path: the steps an attacker takes to carry a threat out, rated for attack potential (ISO/SAE 21434 annex G): elapsed time, expertise, knowledge of the item, window of opportunity and equipment. The points add up to the feasibility: 0–9 high, 10–13 medium, 14–19 low, 20 and more very low.

• Keywords: attack-path
• Set: safety, security & design space
• Where: top level
• Syntax: attack-path Id "How" { threat TS-…; step "…"; elapsed week; expertise proficient; knowledge restricted; window easy; equipment specialized }

attack-path AP-OBD "Frames injected from the diagnostic port" {
  threat TS-SPOOF
  step "Plug a CAN adapter into the OBD port"
  step "Replay a captured BRAKE_CMD"
  elapsed week
  expertise proficient
  knowledge restricted
  window moderate
  equipment standard
}

security-goal#

A cybersecurity goal: the top-level security requirement answering threats, with its CAL (cybersecurity assurance level, CAL1–CAL4; derived from its threats when not written, and one written lower is reported). Written to Arche as a requirement of category security.

• Keywords: security-goal
• Set: safety, security & design space
• Where: top level
• Syntax: security-goal Id "Title" { text "…"; answers TS-…; cal CAL3 }

security-goal CSG-01 "Brake commands are authentic" { text "The brake ECU shall act only on brake commands from the ADCU."; answers TS-SPOOF }

Design space#

The numbers a design is sized for, the alternative designs of a product line, the studies that compare them, and views by concern — written to parameters.yaml, variants.yaml, studies.yaml and viewpoints.yaml, as Arche reads them.

parameter#

A number the design is sized for: given (value, with choices or min/max for a knob) or derived (expr, a formula over other parameters and constants, recomputed when they move). Readable by name from behaviour code, as a constant; a variant can redefine it; a study sweeps it. Written to parameters.yaml (parameters).

• Keywords: parameter (old spelling: param)
• Set: safety, security & design space
• Where: top level
• Syntax: parameter id "Label" { value; expr; unit }

parameter TILES_FITTED { value 4; choices 1, 2, 4, 8; group "Aperture" }
parameter ELEMENTS { expr ELEMENTS_PER_TILE * TILES_FITTED }

variant#

One design of a product line (a 150% model): components and links that say variants a, b belong only to those; everything else to all. set P = expr redefines a parameter in it; default is the one chosen when none is. Arche narrows the canvas, the simulation and the costs to the variant chosen. Written to variants.yaml (variants).

• Keywords: variant
• Set: safety, security & design space
• Where: top level
• Syntax: variant id "Label" { summary; default; set }

variant cff "B · the fan-out computes" {
  default
  set LOAD_LANES = TILES_FITTED
  pros "One lane per tile."
  cons "Logic to design and verify."
}