Autres pages › core

Autres pages

Cette page n’est pas encore traduite : voici la version anglaise.

The arche-lang core

This page is the core of arche-lang: what you need to model a small product, from what it must do to what proves it. Everything here is covered by the stability promise of edition 1.0 (editions.md): a model written with the core keeps building, and a renamed name keeps working for one more edition, with a warning and an automatic fix.

The rest of the language is made of extensions: physics, safety analyses, the product's UI, Capella and ReqIF exchange, containers, and more. The tools read them the same way, but they have no stability promise yet. Each one is marked Extension in the full specification.

archec check --core main.arche lists every construct a model uses outside the core, with its extension. The tutorials and examples/greenhouse use only the core; the tests check it. The blocks below, in order, are one model, a kettle that heats water to a set temperature, and the tests compile it.

A project#

Full spec: source files and declarations

project Kettle "Kettle" {
  description "A kettle that heats water to the temperature asked for."
  version "0.1.0"
  edition "1.0"
  author "The kettle team"
  level simple
}

A model is one or more .arche files. The main one has the project. Its edition says how the model is read (editions.md). level simple is this page: the editor offers the core, and says how to use anything else.

A project shares components through libraries. libraries says which folders hold them, uses which versions it accepts, and include reads a file of one:

project Kettle "Kettle" {
  libraries "../shared"
  uses arche-hw-store "^0.1"
}

include "arche-hw-store/devices/relay/relay.arche"
Diagramme : Relay (on a GPIO pin)
Ce qu’archec dessine depuis ce code : Relay (on a GPIO pin)

A library is a folder with a library.arche. Its renamed says which of its declarations changed name, for which edition: a model that writes an old name still builds, with a warning that archec fix resolves (editions.md).

library kettle-parts "Kettle parts" {
  description "Heaters and their probes."
  version "1.1.0"
  archec ">=0.13"
  uses arche-types "^0.1"
  author "The kettle team"
  license "MIT"
  edition "1.0"
  renamed "1.0", { Element: HeatingElement }
}

Data, messages and units#

Full spec: types and values

unit mK "millikelvin" { quantity temperature; base K; factor 0.001; symbol "mK" }

type Celsius = float32 unit °C range -20..120

enum Strength { LOW, MEDIUM, HIGH = 4 }

struct Setting "Setting" {
  description "What the user asks for."
  target:   Celsius "Target" { description "The water's temperature to reach." }
  strength: Strength
}

const MAX_TARGET = 100 unit °C { description "Water boils." }

message SET "Set" { description "The user's setting."; setting: Setting }
message WATER "Water temperature" {
  period 200ms
  temperature: Celsius
}
message STOP: bool "Stop"

event boiled_dry "Boiled dry" { description "The probe reads far above 100 °C." }
  • A type is a base type (bool, int8 … uint64, float32, float64, string, duration) with a unit and a range.
  • An enum lists its literals; a struct lists its fields, each a name and a type, with an optional unit, range and description.
  • A message carries one value (message STOP: bool) or fields. Its period says how often it is sent. Its unit, on a single value, is that value's.
  • An event is what a state machine reacts to that is not a message.
  • A quantity is a number and its unit, with no space: 200ms, 3.3V, °C. archec checks that what you compare or add has the same quantity. A unit declaration adds one: its quantity, its base unit and factor (or offset), its symbol, other spellings (alias), or logarithmic for dB.

Requirements#

Full spec: requirements and traces

requirement REQ-HEAT "Heat to the target" {
  description "The kettle's main function."
  text "The kettle shall heat the water to the target temperature within 5 min."
  rationale "Users wait for it."
  priority high
  status approved
  method test
}
requirement REQ-DRY "Never heat dry" {
  text "The kettle shall stop heating within 1 s when it boils dry."
  derives REQ-HEAT
  formal "ctl in Dry leads to ctl in Idle within 11s"
}

A requirement says what the system shall do. Whatever meets it says so, with satisfies; a test case that checks it says verifies. derives names the requirement it comes from. formal is a property archec verify proves and archec replay checks on a trace: always …, never …, eventually …, a leads to b within 2s, a implies b.

Components, ports and interfaces#

Full spec: structure

interface Heater "Heater" {
  description "Something that heats when told."
  messages STOP
  fn on()
  fn off()
}
interface SafeHeater "Heater with a cut-out" extends Heater

component Probe "Temperature probe" {
  description "An NTC probe on an ADC pin."
  kind sensor
  out water: data sends WATER { noise 0.2°C; resolution 0.1°C }
  in adc:    analog "ADC" { description "The probe's pin."; pins { io PA0 } }
  fn read "Read" {
    wcet 100us
    ```arche
    send water WATER { temperature: 20.0 }
    ```
  }
}

component Element "Heating element" {
  kind device
  in heat:   provides SafeHeater "Heat"
  inout i2c: i2c "Driver" { address 0x40 }
  fn on()
  fn off()
}

A component has ports. A port has a direction (in, out, inout), a port type (can, i2c, gpio, data, analog… are built in), and what crosses it: the messages it sends or receives, or an interface it provides or requires. Through a port that requires an interface, a body calls the operations of the part at the other end (heater.on()). pins and address say where a port is wired; noise and resolution, how a sensor reads in the simulator. depth is how many messages wait at an in port.

Behaviour: functions, variables and state machines#

Full spec: behaviour

component Controller "Kettle controller" {
  description "Heats until the target, stops on demand or when dry."
  satisfies REQ-HEAT
  in water: data receives WATER { depth 4; handler WATER -> seen }
  in user:  data receives SET, STOP {
    on-receive ```arche
      log "a command"
    ```
  }
  out heater: requires Heater { satisfies REQ-DRY }
  var target: float32 = 0 unit °C range 0..100 { description "What to reach." }

  fn seen(temperature: float32) ```arche
    log "water at", temperature
  ```
  fn above(t: float32) -> bool "Above the target" {
    description "Whether a reading is past the target."
    satisfies REQ-HEAT
    wcet 50us
    ```arche
    return t >= target
    ```
  }

  states {
    initial Idle
    state Idle "Off" {
      description "Waiting for a setting."
      on-enter ```arche
        heater.off()
      ```
    }
    state Heating "Heating" {
      on-enter ```arche
        heater.on()
      ```
      on-exit ```arche
        heater.off()
      ```
    }
    state Dry "Boiled dry"
    Idle -> Heating on SET [setting.target <= MAX_TARGET] / log("heating")
    Heating -> Idle on WATER [above(temperature)]
    Heating -> Idle on STOP
    Dry -> Idle on "after 10s"
    * -> Dry on boiled_dry
  }
}
  • A fn has parameters and a result, a body in the action language (a ```arche block), and its wcet: the longest it may take.
  • handler WATER -> seen calls seen when a WATER arrives, its fields by name.
  • A var has a type, a value to start with, a unit and a range.
  • states holds the machine. It starts in its first state, or in the one initial names. A state's on-enter and on-exit are bodies.
  • A transition is From -> To on trigger [guard] / action. The trigger is a message (its fields are names in the guard: setting, temperature), an event, or "after 10s". * -> Dry leaves every state.

The action language#

Full spec: actions

A body is a list of statements, one per line:

Statement Example
a local var d = t - target, var buf: int32[8]
an assignment x = e, x += 1 (also -=, *=, /=)
a choice if a { … } else if b { … } else { … }
a loop while c { … }, for i in 0..8 { … }, for x in buf { … }, break, continue
a message send port MSG { field: e }, send port true for a single value
a state goto Heating, and state == Heating in a condition
time wait 10ms (in a function that runs on its own: fn main)
a result return e
a trace log "text", e
a call f(x) (the part's own function), port.op(x) (the part at the other end)

Expressions: or and not, == != < <= > >=, + - * / %, the bit operators on integers, x.f, a[i], if c { a } else { b }, records ({ f: e }), durations (10ms), and the builtins now() abs min max sqrt sin cos atan2 clamp int float to_s to_ms len. archec checks the names, the types and what each port carries, then writes the body as Python for the simulator, and as C, Rust or Go for the firmware.

Full spec: structure

component Mcu "Kettle MCU" { kind processor; cores 1; hal stm32; chip "stm32f446re"; inout uart: uart "UART" }

component Bus "Serial line" { kind bus; bitrate 115200 }

system KettleSys "Kettle" {
  description "The kettle and its controller."
  satisfies REQ-HEAT
  part mcu:     Mcu
  part line:    Bus
  part probe:   Probe
  part element: Element
  part ctl:     Controller
  probe.water -> ctl.water
  ctl.heater -> element.heat { description "Mains, through a relay." }
  mcu.uart -> line
}
Diagramme : Kettle
Ce qu’archec dessine depuis ce code : Kettle

A system holds parts, each an instance of a component, and links between their ports (a.p -> b.q). archec checks that one end receives what the other sends, and that a required interface is provided. A component's kind is one archec knows: processor (with its cores, its hal and its chip), bus (with a bitrate), board, device, sensor, actuator, power, plant, environment. A kind of your own is declared in a catalog (an extension).

Tests#

Full spec: verification

test-plan TP-KETTLE "Kettle" {
  description "Heating and stopping."
  verifies REQ-HEAT
  case TC-HEAT "Heats, then stops at the target" {
    description "From cold to 90 °C."
    verifies REQ-HEAT
    timeout 5s
    at 0ms do send probe.water WATER { temperature: 20.0 }
    at 10ms do send probe.water WATER { temperature: 95.0 }
    within 100ms expect ctl.state == Idle
  }
}

A case is a timeline: at a time, do something (set a value, send a message); at or within a delay, expect a condition. These lines are the action language, checked as a body is, with the system's parts for names: an assignment (ctl.target = 90.0), a send from a part's port, and conditions on states (ctl.state == Idle), variables and sent(WATER). A line the action language cannot read is Python, as before: the codegen extension, and archec fix writes the common ones over. archec test runs the plans in the simulator and says which requirements they verify.

Where it runs#

Full spec: deployment

deployment OnBoard "On the MCU" {
  description "One firmware with two threads."
  system KettleSys
  platform KettleSys
  binary firmware "kettle.elf" on mcu {
    description "The firmware."
    thread control "Control" { description "The controller."; runs ctl; priority 2; queue 4; wcet 1ms }
    thread sense "Sense" { runs probe; period 200ms; step read; priority 1 }
  }
  chain reaction "From a reading to the heater" { description "REQ-DRY's second."; through probe, ctl; budget 1s; satisfies REQ-DRY }
}
Diagramme : On the MCU
Ce qu’archec dessine depuis ce code : On the MCU

A deployment places the parts of a system on the processors of a platform (a system too; here, the same one). A binary runs on a processor; each thread runs parts, every period (calling its step function) or when a message comes, at a priority, with a queue for what waits. A chain gives a budget to the path through some parts: archec analyze adds up the worst case, and archec timing measures it on a trace.

What is not in the core#

Full spec: every declaration

Every extension, as archec check --core names it; the full spec marks each.

Extension What it covers
deployment processes, containers, interrupts, routes, allocators, watchdogs, packaging
hardware a board's resources, products and drivers, registers, power pins
communication delivery patterns, pub-sub, services and HTTP routes, dataflow, link timing
machines pseudo-states, regions, activities, deadlines
physics equations, Modelica and FMUs, bodies and joints, actuator response
safety hazards, failure modes, fault trees, STPA, TARA, ASIL and DAL
functional actors, missions, use cases, system functions, operating modes
scenarios sequences, simulations, stimuli, keyframes, fault injection
design decisions, variants, parameters, studies, viewpoints, rules, budgets
cad a part's geometry as code, its material, measured limits, clearances
fpga a component with a clock: signals, registers, bit widths, VHDL and GHDL
testing case tables, setup code, the old step blocks
requirements EARS, metrics and limits, categories, IVV blocks, more trace kinds
exchange Capella, SysML, ReqIF and Polarion sources, issue trackers
components a part's life, IDL operations, contracts, struct inheritance
codegen native types, wire formats, Python and TypeScript bodies, code files
catalogs kinds, layers, tags, colours, port types, packages, defaults, translations
ui the product's screens, layouts and elements
app the Arche app: pages, panels, stories, animations, the canvas
generators generators, importers, exporters, plugins
store a library's Arche Store data, the trust a project gives
ai what may leave the machine

The commands work the same on both. Those the loop needs (check, fmt, fix, test, gen, analyze, verify, timing, replay, status, why) are part of the 1.0 promise: what they accept and their verdicts, not the layout of their output, their messages or the code they generate. The others are the extensions' tools (commands).

Editions and the promise#

Full text: editions.md

  • A project names its edition. Edition 1.0 reads a model exactly as 0.13 does.
  • What this page describes keeps its meaning in every 1.x edition.
  • A name that changes (a keyword, a property, a library's declaration) is read for one more edition, with a warning and an automatic fix (archec fix, and the quick fix in the editor). Then it is an error: the store's Led → GpioLed is made for 1.0, a warning through 1.0 and an error from 1.1.
  • Extensions may still change, the same way: through an edition, with a fix.