La spécification d’arche-lang
Le cœur du langage, ce que l’édition 1.0 promet de garder, se trouve dans
core.md : assez court pour se lire en une soirée. Une section marquée
Extension ci-dessous n’est pas encore couverte par cette promesse ;
archec check --core nomme ce qu’un modèle utilise de chacune
(editions.md).
arche-lang décrit un système en texte simple : de quoi il est fait, ce que fait chaque part, ce qu’il doit faire et comment on le vérifie. Il se compile en un projet Arche. Ce document décrit le langage lui-même : ses éléments lexicaux, sa grammaire et le sens de chaque construction. La référence de chaque déclaration et de chaque propriété se trouve dans patterns.md. Pour bien écrire un modèle, lisez style.md. Pour un premier modèle pas à pas, suivez le tutoriel.
Comme Go, le langage est petit. Il offre une seule façon d’écrire chaque chose
et une seule mise en page, que archec fmt écrit pour vous. Chaque exemple
ci-dessous compile tel quel (les tests les compilent). Un bloc marqué
fragment est un morceau de déclaration.
Notation#
La grammaire est écrite en EBNF :
Production = name "=" Expression "." .
Expression = Term { "|" Term } .
Term = Factor { Factor } .
Factor = name | "literal" | "(" Expression ")" | "[" Expression "]" | "{" Expression "}" .
[ … ] est optionnel, { … } signifie zéro ou plusieurs fois, | sépare les
alternatives. newline est la fin d’une ligne.
Fichiers sources#
Un modèle tient dans un ou plusieurs fichiers UTF-8 qui se terminent par
.arche. L’un d’eux est le fichier principal. Les autres y sont inclus,
directement ou non. Un fichier contient des déclarations. Un fichier inclus dans
le corps d’un system ou d’un component contient une partie de ce corps.
File = [ PackageClause ] { Include | Declaration } .
PackageClause = "package" QualifiedName newline .
Include = ( "include" | "requires" ) string newline .
Éléments lexicaux#
| Élément | Forme |
|---|---|
| Commentaire | // to the end of the line, /* … */ ; /// … placé avant une déclaration en est la description |
| Identifiant | lettres, chiffres, _ ; un - à l’intérieur (REQ-BRK-001, kria-parts) : une soustraction s’écrit donc avec des espaces autour de son - |
| Mot-clé | contextuel : un mot n’est un mot-clé que là où une déclaration peut commencer, si bien que state, port ou type restent utilisables comme noms |
| Nombre | 42, 3.14, 1e-3, 0xFF, 0b1010, 1_000_000 |
| Grandeur | un nombre et son unité, sans espace : 5ms, 100MHz, 3.3V, 2kg ; ns us µs ms s min h donnent une durée |
| Chaîne | "…" avec \n \t \" \\ ; les autres barres obliques inverses sont conservées ("$\frac{a}{b}$") ; """…""" s’étend sur plusieurs lignes |
| Traduction | après une chaîne, en "…" (ou de, fr…) sur la même ligne ou sur la suivante, plus indentée |
| Code | ```ts … ```, ```python … ```, ```arche … ``` (ou latex, yaml) ; un ``` seul désigne le langage handlers du projet ; quelques propriétés acceptent une simple ligne de Python, et le do et le expect d’un cas de test une ligne du langage d’actions ou de Python (do send p.out M { a: 1 }, do send(p.out, M(a=1))) |
| Séparateur | un saut de ligne termine une propriété ou une déclaration ; dans un bloc sur une ligne, ; |
QualifiedName = identifier { "." identifier } .
Path = identifier [ "[" Index "]" ] { "." identifier [ "[" Index "]" ] } .
Text = string { language string } .
Un projet indique l’édition du langage dans laquelle il est écrit, comme go.mod
nomme une version de Go : edition "1.0". Sans édition, il est lu comme il
l’a toujours été. À partir de l’édition 0.12, une ancienne orthographe de
mot-clé est une erreur, et non plus un avertissement ; à partir de 0.13, une
deuxième façon d’écrire une même chose aussi ; 1.0 se lit comme 0.13 et ouvre
la promesse de stabilité (editions.md).
archec fmt --edition 1.0 --write écrit les orthographes standard et
l’édition. Une édition plus récente que celles qu’archec connaît est une
erreur : mettez archec à jour.
Un mot-clé de deux mots s’écrit avec un trait d’union, comme un groupe nominal :
port-type, test-plan, use-case, system-function, failure-mode,
operating-mode. Les orthographes soudées (porttype, testplan, usecase,
statemachine) sont les anciennes. Et un mot n’a qu’un sens : quand l’ancienne
orthographe d’une déclaration est le mot standard d’autre chose,
l’avertissement indique quoi écrire et à quoi sert le mot :
Write `state` (`mode` is for operating modes, `operating-mode`).
| Mot | Ce qu’il signifie | Ce qu’il ne signifie plus : écrivez plutôt |
|---|---|---|
process |
un processus du système d’exploitation dans un déploiement | un workflow : workflow |
contract |
un contrat hypothèse/garantie dans un composant | une interface : interface |
mode |
(un mode de fonctionnement s’écrit operating-mode) |
un état : state |
model |
le système sur lequel tourne un plan de test ou une simulation | un système : system |
bus |
le bus lui-même : un composant avec kind bus, le over d’une route, le bus d’un lien |
un type de port : port-type |
view |
la page qu’ouvre une entrée de menu ou une étape d’histoire | un point de vue : viewpoint |
goal |
l’objectif de sûreté ou de sécurité auquel répond un danger ou une menace | une mission : mission |
function |
une fonction système (system-function) qu’exécute une étape de chaîne |
une fonction d’un composant : fn |
tests |
les cas que nomme un bloc verify |
un plan de test : test-plan |
kind |
une catégorie du catalogue | la sorte d’un pseudo-état : pseudo |
source |
l’endroit où se trouve le code (un composant, une fonction) | l’origine d’une exigence : origin |
Déclarations#
Toutes les déclarations ont la même forme : un mot-clé, un nom, un libellé, ce que le mot-clé accepte dans l’en-tête, puis un corps de propriétés et de déclarations imbriquées.
Declaration = keyword [ identifier ] [ Text ] { Header } [ "as" identifier ] [ Body ] newline .
Body = "{" { Property | Group | Declaration } "}" .
Property = key [ Values ] newline .
Group = groupname "{" Property { ";" Property } "}" .
Values = Value { "," Value } .
component Pump "Water pump" {
description "Moves water from the tank to the field."
kind device
in power: power
out flow: can sends FLOW
}
message FLOW: float32 "Flow"
system Field {
part pump: Pump
}- Le nom permet au modèle de désigner l’élément. Sa casse dit ce qu’il est,
comme en Go :
PascalCasepour ce qui est défini (composants, systèmes, types),snake_casepour ce qui est à l’intérieur (parts, ports, fonctions, variables),SCREAMING_CASEpour les messages, les constantes et les littéraux. Les identifiants d’exigences et de tests s’écrivent comme dans leurs documents (REQ-BRK-001). - Le libellé est le nom que lisent les gens, avec ses traductions.
as iddonne à l’élément son identifiant dans Arche quand ce n’est pas son nom (un import conserve ainsi les identifiants d’Arche :component flash_memory "FLASH" as c-1793752253957).- Une propriété est une clé et ses valeurs, sur une ligne. Une liste de
valeurs continue à la ligne suivante après une
,. Les propriétés qui vont ensemble peuvent s’écrire en groupe, ce qui revient à les écrire une par une :
timing { latency 2ms; jitter 100us; bitrate 1Mbps }
Les groupes sont timing, delivery (la façon dont les messages sont
livrés), compute (les cœurs, l’OS, la mémoire, la flash et la puce d’un processeur),
physical (masse, puissance, coût), resources (ce qu’a une carte :
peripherals, pinout, io-level — docs/boards.md) et errors (le modèle
d’erreurs d’une part : errors { produces omission; from a }). Un port
d’alimentation dit sa voltage (une valeur, ou une plage 1.71V..3.6V pour
ce qu’il accepte) et son current (ce qu’un out fournit au plus, ce qu’un
in consomme).
Les déclarations se répartissent en ensembles (patterns.md les liste) : le modèle, avec lequel s’écrit tout modèle, et des ensembles dédiés à un usage : le déploiement, l’analyse fonctionnelle et les scénarios, la sûreté, la sécurité et l’espace de conception, l’application Arche, l’outillage du projet.
L’outillage du projet regroupe ce qui étend archec : un generator (une cible
de code), un importer (un fichier d’un autre outil lu en arche-lang :
script ou command, extensions, reads) et un exporter (le modèle écrit
dans un tel fichier : templates, script ou command, extension), chacun
avec ses option typées. On les écrit en général dans un plugin
(plugins, générateurs).
importer kv "Key-value files" { script "kv/import.ts"; extensions ".kv" }
exporter kv "Key-value files" { script "kv/export.ts"; extension ".kv" }
Types et valeurs#
Type = [ "optional" ] [ "*" ] TypeName [ TypeArgs ] [ "[" [ Index ] "]" ] | string .
TypeName = QualifiedName | "struct" Body .
TypeArgs = "<" ( Type | number ) { "," ( Type | number ) } ">" . // no space before "<"
Generic = "struct" identifier "<" identifier [ ":" "int" ] { "," identifier [ ":" "int" ] } ">" Body .
Value = number | quantity | Text | Code | "true" | "false" | "nil" | Path
| "[" [ Values ] "]" | "{" [ Field { "," Field } ] "}" | Value ".." [ Value ] | Expression .
Les types scalaires sont bool, int8…int64, uint8…uint64, float32,
float64, char, byte, string, bytes, duration, timestamp. any
désigne n’importe lequel d’entre eux. T[4] est un tableau, optional T peut
être absent, *T pointe vers un T, et "Vec<u8>" est un type d’un autre
langage, conservé tel qu’il est écrit.
const MAX_SPEED = 36 unit m/s
type Speed = float32 unit m/s range 0..70
enum Mode { MANUAL, AUTO }
struct Sample {
speed: Speed
mode: Mode
stamp: optional uint64
}
union Command {
stop
go: Speed
}
Une unité s’écrit telle quelle (unit m/s²). archec vérifie que ce qu’on
compare ou qu’on additionne relève d’une même grandeur. Un produit ou un
quotient a la grandeur que donnent ses dimensions : V_BUS * I_MAX est une
puissance, DIST / T_STOP une vitesse, 1 / 5ms une fréquence. Ainsi,
const P = V_BUS * I_MAX { unit W } est valide, et { unit s } donne un
unit-mismatch. Il en va de même pour l’expr d’un paramètre face à son
unit. Une dimension sans nom usuel s’écrit en toutes lettres
(length·time⁻³). Rien n’est converti : kWh et J sont tous deux des énergies,
et c’est tout ce qu’archec vérifie.
Une struct peut prendre des types et des nombres : struct Ring<T, N: int>.
Chaque utilisation avec ses arguments, Ring<Sample, 64>, est une struct à part
entière, Ring_Sample_64, dont les champs ont T et N remplacés. C’est elle
que voient Arche, les codecs et le code généré. La struct générique elle-même
n’est pas émise.
struct Reading {
value: float32
}
struct Ring<T, N: int> "Ring buffer" {
items: T[N]
head: uint16
}
message HISTORY {
last: Ring<Reading, 8>
}
Un type que fournit le code est native : on indique son nom dans chaque
langage, ainsi que l’en-tête (C, C++) ou le paquet (Go) qui le déclare. Le code
généré l’utilise tel quel. archec ne regarde pas à l’intérieur.
type Iq native "IQ sample" {
cpp "dsp::Iq" include "dsp/iq.h"
c "iq_t" include "dsp/iq.h"
rust "dsp::Iq"
go "dsp.Iq" import "example.com/dsp"
}
Un type natif qui ne donne son nom dans aucun langage est un native-type.
Formats de trame#
Extension — hors de la promesse de stabilité 1.0 (
codegen; le cœur)
Les octets d’un message sont ses champs dans l’ordre, en little-endian, alignés
sur l’octet, sauf s’il précise son format de trame, bit par bit, comme le
fait un DBC CAN ou l’ACN d’ASN.1. Il suffit pour cela de l’un de byte-order
et size sur le message, ou de at, bits, scale, offset, signed,
checksum, counter sur un champ :
enum Gear { P, R, N, D }
message WHEEL_SPEED {
byte-order big
size 8
speed: float32 unit km/h range 0..600 bits 16 scale 0.01
gear: Gear
temp: float32 range -40..215 bits 8 offset -40
alive: uint8 bits 4 range 0..15 counter
crc: uint8 at 56 checksum crc8
}
- Un champ commence au bit
atde la trame, ou juste après le champ précédent. Il occupebitsbits : 1 pour un bool, le minimum qui contient ses littéraux pour un enum, la taille de son type pour un nombre. - Le bit k de la trame se trouve dans l’octet k / 8. En little-endian
(
byte-order little, le défaut, Intel) :atest le bit de poids faible du champ, et le bit k est le bit k % 8 de son octet. En big-endian (big, Motorola) :atest son bit de poids fort, le bit k est le bit 7 - k % 8, et le champ s’étend vers la fin de la trame. Un champ peut indiquer son proprebyte-order. - Avec
scaleouoffset, un nombre circule sous forme d’entier : brut = round((valeur - offset) / scale), saturé à ce que contiennent ses bits ; valeur = brut × scale + offset. Un flottant sans ces propriétés circule sous forme de ses bits IEEE, 32 ou 64. - La valeur brute est signée quand le type du champ l’est, ou avec
signed. checksum crc8(SAE J1850) ouchecksum xor8: un octet calculé sur les autres octets de la trame. Une trame dont la somme de contrôle est fausse n’est pas décodée.counter: un compteur cyclique, que le câblage C généré incrémente à chaque envoi.- La trame fait
sizeoctets, ou autant qu’en atteignent les champs. Les bits qu’aucun champ n’occupe valent zéro.
archec vérifie que deux champs ne partagent aucun bit (wire-overlap), que
chacun tient dans la trame (wire-size), que la range d’un champ correspond
à ce que ses bits transportent une fois mis à l’échelle (wire-range), et
qu’un message qu’une route place sur un bus CAN tient dans sa trame, 8 octets
ou 64 en CAN FD (wire-frame). Le DBC, l’ARXML, l’ICD, Renode et archec replay lisent les champs sur leurs bits, et archec gen --target wire écrit
leurs codecs en C, en Rust (no_std), en Go et en Python. --target c,
embassy et go envoient et reçoivent avec ce même code.
Noms, paquets et chemins#
Extension — hors de la promesse de stabilité 1.0 (
catalogs, pour unpackage; les noms et les chemins sont du cœur ; le cœur)
Toute déclaration qui porte un nom est connue partout sous ce nom : les noms
sont globaux, comme les identifiants d’Arche. Un paquet regroupe des
déclarations sous un nom. Écrit en tête d’un fichier, package chassis place le
fichier dans ce paquet, et chassis.BRAKE_CMD désigne explicitement l’une de
ses déclarations.
package chassis
message BRAKE_CMD: float32 "Brake"
Un élément situé dans un autre se désigne par son chemin : Car.ecu.can0
est le port can0 de la part ecu du système Car. Dans un composant, un
chemin part de ce composant (ecu.can0). Une part qui montre le composant d’un
autre modèle (ref tile.tile) est parcourue : ce qui se trouve dans ce
composant se trouve dans la part.
Structure#
Un system est un modèle d’Arche : les parts qui le composent et la façon dont
elles sont reliées. Un component est une définition dont ses parts sont des
copies. Un composant écrit dans un autre en est une part.
Port = ( "in" | "out" | "inout" ) identifier [ ":" Type ] [ Text ] [ ( "sends" | "receives" ) Values ] [ Body ] .
Link = [ "link" [ identifier ] ] Path "->" Path [ Text ] [ ":" Type ] [ "as" identifier ] [ Body ] .
message GO: bool "Go"
component Panel "Panel" {
out button: can sends GO
}
component Motor "Motor" {
in cmd: can receives GO
}
system Station {
part panel: Panel
part motor: Motor
panel.button -> motor.cmd
}Le type d’un lien et les messages qu’il transporte viennent de ses ports.
L’éditeur les affiche, et : type et carries les indiquent sur le lien.
Code#
Extension — hors de la promesse de stabilité 1.0 (
exchange; le cœur)
Une part indique à quels fichiers du code elle correspond avec source, sur son
composant : un fichier, un dossier ou un motif glob (* dans un dossier, **
à travers les dossiers, {a,b}), à partir du dossier du fichier principal. Un
fichier appartient à la part dont la source le désigne au plus près : un fichier
nommé explicitement passe avant un glob, un dossier plus long avant un plus
court. La source d’une fonction est celle de son composant.
port-type call "Call" {
handling message
}
component Planner "Planner" {
source "src/planner/**"
in api: call
}
component Shell "Command line" {
source "src/cli.ts"
source "src/cli/*.ts"
out uses: call
}
system App {
part shell: Shell
part planner: Planner
shell.uses -> planner.api
}archec recover écrit un tel modèle à partir du code. archec conform vérifie
que chaque import entre deux parts correspond à l’un des liens du modèle, et
signale les liens qu’aucun import ne justifie. Deux props leur en disent plus.
prop weak_links sur un système ou un composant liste des paires de ses parts
(["a -> b: 1 import"]) dont les imports sont autorisés sans qu’un lien soit
tracé. prop recovered sur un système indique qu’archec recover l’a écrit, si
bien qu’archec diagram ne trace que ses liens les plus lourds (le poids d’un
lien est le nombre que donne son libellé : "12 imports").
Services, flux de données et topics#
Extension — hors de la promesse de stabilité 1.0 (
communication; le cœur)
La façon dont deux parts communiquent se décrit sur leurs ports (et leurs
liens) : pattern, buffer, timeout… (déploiement). Trois
autres moyens décrivent comment les composants se rencontrent.
Un service est appelé par son nom, où qu’il s’exécute : service "name"
sur un port out l’appelle, sur un port in le fournit. Aucun lien n’est
tracé. Un nom qu’aucun port in ne fournit donne un no-service.
message JOB {
id: uint32
}
component Planner "Planner" {
out compute: data sends JOB { service "compute" }
}
component Worker "Worker" {
in compute: data receives JOB { service "compute" }
}Le flux de données (dataflow), c’est le traitement du signal : une source
émet en continu des vecteurs d’échantillons, et un puits s’exécute quand il en a
reçu assez. Ses propriétés vont dans un groupe dataflow (ou une par une, ce
qui revient au même) et donnent au port pattern dataflow.
| Propriété | Côté | Ce qu’elle indique |
|---|---|---|
vector T |
les deux | le type d’un échantillon |
header H |
les deux | l’en-tête que porte chaque vecteur |
push-threshold n |
source | les échantillons rassemblés avant d’être poussés |
transfer copy | share |
les deux | le puits reçoit une copie (par défaut), ou le même tampon |
threshold n |
puits | les échantillons qui doivent être arrivés pour qu’il s’exécute |
history n |
puits | les échantillons du vecteur précédent que chaque exécution revoit |
max-processing n |
puits | le nombre maximal d’échantillons que prend une exécution |
backpressure on | off |
les deux | le puits peut faire attendre sa source (off par défaut) |
backpressure-threshold n |
puits | les échantillons en attente à partir desquels il le demande |
struct FrameHeader {
seq: uint32
}
component Adc "ADC" {
out iq: data {
dataflow { vector float32; header FrameHeader; push-threshold 256 }
}
}
component Fft "FFT" {
in iq: data {
dataflow { vector float32; header FrameHeader; threshold 1024; history 64 }
}
}
system Receiver {
part adc: Adc
part fft: Fft
adc.iq -> fft.iq
}Un puits relié à un port qui n’est pas une source, ou à une source d’un autre
vector, donne un dataflow-source. Deux extrémités qui n’indiquent pas le
même backpressure donnent un dataflow-backpressure. Une propriété de flux de
données sur un autre pattern, ou du mauvais côté, donne un comm-property ou un
wrong-side.
Un topic nomme ce qu’un port pub-sub publie ou ce à quoi il s’abonne. Ses
parties entre accolades sont remplies quand un message est publié, chacune à
partir du champ du message qui porte ce nom, ou du type écrit
({sensor: uint8}). Un port qui a un topic est associé par ce topic : un port
in du même topic s’y abonne. Le relier en plus donne donc un topic-wired.
Une partie qui ne nomme rien de ce que contient le message donne un
topic-part. archec sim livre ce qu’un tel port envoie à chaque port in
dont le topic lui correspond (* pour un niveau, ** pour un nombre
quelconque de niveaux, une partie entre accolades pour n’importe quelle
valeur). Une métrique atteint de la même façon les filtres qui correspondent à
/<part path>/<metric>.
message TRACK {
id: uint32
range: float32
}
component Radar "Radar" {
out tracks: data sends TRACK { pattern pub-sub; topic "/tracks/{id}" }
}
component Display "Display" {
in tracks: data receives TRACK { pattern pub-sub; topic "/tracks/{id}" }
}Le modèle des générateurs donne à chaque port et à chaque lien son pattern
(un port qui requiert ou fournit une interface avec des opérations est
client-server), son topic et ses topicParts, son service, et dataflow
avec les propriétés des deux extrémités.
Comportement#
Le corps d’une fonction est du code, tel qu’Arche l’exécute : TypeScript,
Python ou le langage d’actions. Le projet indique lequel
(handlers typescript | python | arche). Un composant peut indiquer le sien, et
un bloc aussi : ```ts (voir handlers.md). Ce code
s’écrit dans le modèle ou dans un fichier .ts ou .py à côté
(archec fmt --extract-code). Une variable a un type et une valeur. Une machine
à états a des états et des transitions :
Transition = ( Path | "*" ) "->" Path [ "as" identifier ] [ "on" ( identifier | string ) ] [ Guard ] [ "/" Action ] .
Guard = "[" text "]" | "when" string .
message GO: bool
component Valve "Valve" {
in cmd: can receives GO
var open: bool = false
fn toggle "Toggle" ```python
self.open = not self.open
```
states {
state Closed
state Open
Closed -> Open on GO [self.open]
Open -> Closed on GO
}
}
system Plant {
part valve: Valve
}Une garde s’écrit entre crochets. when "…" sert pour une garde qui est une
phrase que des crochets ne pourraient pas contenir (une apostrophe, un accent).
* -> Fault quitte n’importe quel état.
Un corps Python est traduit dans le langage d’actions quand il ne dit que ce que
le langage d’actions sait dire (src/pyaction.ts). Les générateurs et le
simulateur du navigateur utilisent alors la traduction. Cela couvre
self.x = …, if/elif/while, for i in range(a, b, step), for x in buf,
for i, x in enumerate(buf), une liste de taille fixe ([0.0] * 8, [1, 2, 3],
[i * 0.5 for i in range(4)], xs: list[float] = …), buf[i], len,
sum/min/max/any/all d’une liste ou d’un générateur (une boucle avant
l’instruction), a // b et a % b (floor_div, floor_mod), x ** y,
a if c else b, x in (1, 2), a < b < c, a, b = b, a + b,
math.pi/sin/cos/atan2/sqrt/radians, les docstrings, et les lignes
qui continuent entre parenthèses ou crochets. Une traduction n’est utilisée que
si elle passe la vérification des types. Là où elle calculerait autre chose que
Python, elle est refusée : / entre deux entiers (celui de Python donne un
float), ** entre deux entiers. Tout le reste n’a pas de traduction, et la
raison nomme la construction : "sorted(): it makes a new list", "a slice",
"raise: an exception", "np.mean(): numpy is not translated".
Le Python que le langage d’actions ne sait pas dire (un dict, une liste qui
grandit, un entier au-delà de 64 bits, numpy) ne tourne qu’en simulation :
archec sim l’exécute en Python (sim.md). Un composant
(ou une fonction) qui contient un tel code dit simulation-only ;
archec gen --target c|cpp|embassy|go refuse un déploiement qui le place sur un
microcontrôleur (simulation-only). pip "numpy>=1.26" indique les paquets
qu’importe son Python. Un def sans self dans un fichier code se lie à la fn
qui a les mêmes paramètres (def gcd(a, b) ↔ fn gcd(a: int64, b: int64)).
Actions#
Un corps peut aussi s’écrire dans le langage d’actions, dans un bloc marqué
arche au lieu de python. archec le vérifie (les noms qu’il utilise, leurs
types, les ports sur lesquels il envoie et ce qu’ils transportent, les états
vers lesquels il va) et le traduit : vers le Python qu’exécute le simulateur
d’Arche, vers du Rust avec archec gen --target embassy (sans laisser de TODO
dans app.rs), vers du C. Python reste utilisé pour les modèles de
l’environnement et le code de test.
Body = { Statement newline } .
Statement = "var" identifier [ ":" Type [ "[" [ Size ] "]" ] ] [ "=" Expr ] // var buf: int32[64], var t: int32[] = [1, 2]
| "var" "(" identifier { "," identifier } ")" "=" Expr // var (q, r) = divmod(7, 2)
| Target ( "=" | "+=" | "-=" | "*=" | "/=" ) Expr
| "(" Target { "," Target } ")" "=" Expr // (a, b) = (b, a)
| "if" Expr Block { "else" "if" Expr Block } [ "else" Block ]
| "while" Expr Block
| "for" identifier "in" Expr ".." Expr [ "step" Expr ] Block // for i in n..0 step -1
| "for" identifier "in" Expr Block // for x in arr
| "send" identifier Expr // a port, and a message: BRAKE_CMD { force: 1.0 }
| "goto" identifier | "kick" identifier | "wait" Expr | "return" [ Expr ]
| "log" Expr { "," Expr } | "break" | "continue" | Call .
Call = identifier "(" [ Expr { "," Expr } ] ")" // a function of the part, a builtin
| identifier "." identifier "(" [ Expr { "," Expr } ] ")" . // port.op(…): over the port's link
Expr = or and not, == != < <= > >=, | ^ & << >> (on integers), + - * / %, unary - and ~, x.f, a[i],
f(…), port.op(…), MSG { f: e }, { f: e } where a record is expected, 10ms, 0x1F, 0b101,
"text", true, false; [e, …] where an array is declared, (e, e, …) where several values go;
"if" Expr "{" Expr "}" "else" ( "{" Expr "}" | "if" … ), a value chosen.
Les noms que voit un corps sont ses variables locales, les paramètres de la
fonction, les variables et fonctions de la part, les constantes et les valeurs
d’enum (Mode.On). state == Ready teste l’état de la part. Fonctions
intégrées : now() (en ns), abs min max clamp sqrt, sin cos atan2 (en
rad), pow(x, y) (des floats), int et float pour convertir, to_s et
to_ms, floor_div et floor_mod. Les durées s’écrivent 10ms, 50us, 2s.
Un entier sur 64 bits contient un temps en ns et se combine avec elles. Un
entier divisé par un entier donne un entier, comme en Rust et en C : /
arrondit vers 0 et % a le signe du côté gauche (-7 / 2 vaut -3, -7 % 2
vaut -1). floor_div(a, b) et floor_mod(a, b) sont le // et le % de
Python : le quotient arrondi vers le bas, le reste du signe du diviseur
(floor_div(-7, 2) vaut -4, floor_mod(-7, 2) vaut 1). Ils prennent des
entiers. Un seul endroit diffère : dans les handlers Python d’Arche, % est
celui de Python, donc un côté négatif y donne le résultat de floor_mod ;
archec sim, C, C++, Rust, Go et TypeScript donnent le signe du côté gauche.
Écrivez floor_mod là où un côté peut être négatif et où c’est le résultat de
Python que vous voulez.
if c { a } else { b } est une valeur autant qu’une instruction :
var s = if x > 0 { 1 } else { -1 }. Il a un else, et seul le côté choisi
est calculé. Son type est celui des deux côtés (1 à côté de 2.5 donne un
float). C’est le a if c else b de Python, le c ? a : b du C, le if de
Rust ; Go reçoit une fonction littérale.
Les opérateurs de bits & | ^ << >> prennent des entiers et ont la même
priorité qu’en Python : sous + et -, au-dessus des comparaisons
(crc & 0x80 != 0 est (crc & 0x80) != 0). Leur résultat garde la largeur de
son type dans toutes les cibles : (crc << 1) d’un uint16 perd le bit qui
en sort, en Python et en JavaScript aussi. ~x inverse chaque bit d’un entier,
dans la largeur de son type (~0xA5 d’un uint8 vaut 0x5A).
component Crc16 {
var crc: uint16 = 0xFFFF
var last: uint8[4]
var n: int32 = 0
fn add(b: uint8) ```arche
last[n % len(last)] = b
n += 1
crc = crc ^ (int(b) << 8)
for k in 0..8 {
if crc & 0x8000 != 0 {
crc = (crc << 1) ^ 0x1021
} else {
crc = crc << 1
}
}
```
}const REACTION_TIME = 150ms
const MU_DRY = 0.7
message BRAKE_CMD { force: float32; emergency: bool }
component Planner "Planner" {
out can_brake: can sends BRAKE_CMD
var speed: float32 = 0
var obstacle_m: float32 = 100
fn plan "Trajectory planning" ```arche
var d = speed * to_s(REACTION_TIME) + speed * speed / (2 * MU_DRY * 9.81)
if obstacle_m < d * 1.2 {
send can_brake BRAKE_CMD { force: 8000.0, emergency: true }
}
```
}
system Car {
part planner: Planner
}Tableaux#
Un tableau est une variable de la part (var buf: float32[8], ou
= [1, 2, 3, 4, 5, 6, 7, 8]), une variable locale d’un corps, ou un paramètre
de fonction. buf[i] lit ou affecte un élément, len(buf) donne leur nombre.
Un indice est un entier ; un indice littéral hors du tableau est une erreur.
Un tableau ne s’affecte pas et ne se copie pas en entier.
- Un tableau local est sur la pile :
var buf: int32[64]commence à zéro,var t: int32[4] = [1, 2, 3, 4]avec ses éléments (int32[]prend sa taille dans ceux-ci). Sa taille est un nombre entier ou une constante. Ses éléments sont des nombres ou des booléens. - Une fonction prend un tableau en paramètre :
fn sort(a: int32[], n: int32)en prend un de n’importe quelle longueur,fn f(a: int32[8])un de huit. L’appelant donne un tableau par son nom : une variable de la part, un tableau local, ou son propre paramètre tableau. La fonction travaille sur le tableau même de l’appelant : ce qu’elle affecte, l’appelant le voit. Les éléments sont du même type (sans conversion) ; un paramètre avec une taille prend un tableau de cette taille. for x in arrdonne chaque élément à tour de rôle (une copie : affecterxne change pas le tableau ;arr[i] = …, si).- Un tableau ne passe pas par un port (
port.op(a)) : seulement vers une fonction de la part. Une struct transporte des valeurs vers une autre part.
| Cible | fn sort(a: int32[]), sort(buf) |
|---|---|
| C | int32_t a[], int32_t a_len (const quand la fonction ne fait que le lire), sort(self, self->buf, 8) ; a: int32[8] donne int32_t a[8] |
| C++ | std::int32_t *a, std::int32_t a_len, this->buf.data(), …size() |
| Rust | a: &mut [i32] (&[i32] quand il est seulement lu) ; une variable de la part est copiée à l’aller et au retour, une locale est &mut buf |
| Go | a []int32, buf[:] |
Python, TypeScript, archec sim |
la liste ou le tableau lui-même |
Plusieurs résultats#
Une fonction donne plusieurs valeurs avec -> (T, U) et return (a, b). On
les sépare dans de nouvelles variables locales, var (q, r) = divmod(7, 2)
(_ n’en garde aucune), ou dans des variables, (q, r) = divmod(7, 2).
(a, b) = (b, a) échange : toutes les valeurs de droite sont calculées
d’abord, puis chaque cible est affectée. Plusieurs valeurs ne forment pas une
expression : elles sont retournées ou séparées, rien d’autre. Une opération
à travers un port donne une seule valeur. C reçoit une struct
(arche_tuple_int32_int32_t, champs v0, v1), C++ un std::tuple, Rust un
tuple, Go ses résultats multiples.
Compter#
for i in a..b compte à partir de a tant que i < b, de un en un. step
dit de combien : for i in 0..n step 2 ; un pas négatif compte à rebours
tant que i > b, comme le range(n, 0, -1) de Python est
for i in n..0 step -1. Un pas qui est un nombre entier ou une constante
(-STRIDE aussi) peut être négatif ; toute autre expression compte en
montant, et doit être au-dessus de 0 (for j in i * i..n step i ; le
simulateur s’arrête sur un pas qui ne l’est pas). Un pas de 0 est une erreur.
Le corps ne change ni le compteur ni les bornes.
Un algorithme, tel que Python l’écrit, dans le langage d’actions :
component Sorter {
var data: int32[6] = [5, 2, 9, 1, 7, 3]
var at: int32 = -1
var q: int32 = 0
var r: int32 = 0
fn bubble_sort(a: int32[], n: int32) ```arche
for i in 0..n {
for j in 0..n - 1 - i {
if a[j] > a[j + 1] {
(a[j], a[j + 1]) = (a[j + 1], a[j])
}
}
}
```
fn divmod(a: int32, b: int32) -> (int32, int32) ```arche
return (floor_div(a, b), floor_mod(a, b))
```
fn run() ```arche
bubble_sort(data, len(data))
for i in len(data) - 1..-1 step -1 {
if data[i] == 7 {
at = i
}
}
(q, r) = divmod(-7, 2)
```
}Appeler une autre part#
port.op(…) appelle une fonction de la part située à l’autre bout du lien du
port : une opération d’une interface que le port requires (avec ce qu’elle
étend). archec vérifie l’appel par rapport à l’interface : le port,
l’opération, le nombre d’arguments qu’elle prend, leurs types et ce qu’elle
renvoie. Il vérifie aussi que l’autre bout du lien fournit l’interface
(unprovided-interface) avec une fonction de ce nom (missing-operation).
interface BrakeApi "Brake API" {
fn apply(force: float32) -> bool
fn release()
}
component Controller "Controller" {
out brake: requires BrakeApi
var applied: uint16 = 0
fn step "Brake when asked" ```arche
if brake.apply(2.5) {
applied += 1
} else {
brake.release()
}
```
}
component Brake "Brake" {
in api: provides BrakeApi
var force: float32 = 0
fn apply(f: float32) -> bool ```arche
force = f
return f > 1.0
```
fn release() ```arche
force = 0.0
```
}
system Car {
part ctl: Controller
part brk: Brake
ctl.brake -> brk.api
}La fonction du fournisseur s’exécute chez le fournisseur, sur ses variables et son état, et son résultat revient. L’appelant l’attend. Voici comment chaque cible procède :
| Cible | brake.apply(2.5) |
|---|---|
archec sim |
la fonction s’exécute aussitôt sur brk (comme un appel de fonction : sans délai ni file d’attente, même si brk est occupée) |
| Arche (Python, TypeScript) | await component("brk").apply(2.5) : la part nommée est celle de l’autre bout du lien |
| C | controller_call_brake_apply(self, 2.5f) : le câblage appelle brake_apply(&part_brk, …) selon la part qui demande, dans le thread de l’appelant ; sans déploiement, dans controller_ports.c, que vous écrivez |
| C++ | this->call_brake_apply(2.5f), une std::function que définit main.cpp (non définie, elle lève une exception) |
| Rust (Embassy) | _out.call_brake_apply(2.5).await : une requête sur un canal vers la tâche de brk, qui exécute la fonction et signale la réponse ; les deux parts doivent donc être sur deux threads (sur un seul, archec le signale et l’appel renvoie la valeur par défaut) |
| Go | self.Call("brake", "apply", float32(2.5)).(bool) : main.go appelle parts.Brk.Apply, dans la goroutine de l’appelant |
En C, en C++ et en Go, la fonction du fournisseur s’exécute dans le thread de l’appelant. Ce qui garantit la sûreté, c’est que les deux parts soient sur un même thread, ou que la fonction ne lise et n’écrive que ses propres variables. Une part qu’on atteint par un bus (un autre binaire) n’est pas appelée : archec le signale.
Opérations, comme en IDL#
Extension — hors de la promesse de stabilité 1.0 (
components; le cœur)
Une opération peut en dire plus, comme dans l’IDL de CORBA :
Operation = [ "oneway" ] "fn" identifier "(" [ Arg { "," Arg } ] ")" [ "->" Type ] [ "raises" Path { "," Path } ] .
Arg = [ "in" | "out" | "inout" ] identifier ":" Type .
Attribute = [ "readonly" ] "attribute" identifier ":" Type .
Exception = "exception" identifier [ Text ] Body . // a struct
exception NotFound "Not found" {
id: uint32
}
struct Track {
id: uint32
range: float32
}
interface Tracks "Tracks" {
readonly attribute count: uint32
attribute rate: float32
fn lookup(id: uint32, out t: Track, inout hint: uint8) -> bool raises NotFound
oneway fn forget(id: uint32)
}
interface TracksAdmin extends Tracks {
fn clear()
}
- Un argument est
inpar défaut. L’opération écrit un argumentout, et lit et écrit un argumentinout: à l’appelport.op(…), ce qu’on y passe est une variable (ou un champ), pas une valeur. - Une opération
onewayn’a pas de résultat, et l’appelant ne l’attend pas : ni-> T, ni argumentout(oneway-result). raisesnomme desexception: des structs qu’une opération peut lever à la place de son résultat (raises-not-exceptionpour un autre type).- Un
attributeest une valeur que détient le fournisseur, et qu’un client lit (et écrit, sauf si elle estreadonly). extends(dans l’en-tête ou dans le corps) ajoute les opérations, les attributs et les messages d’une autre interface.
archec sim traite un argument out comme un argument in : sa valeur ne
revient pas. Le modèle des générateurs donne chaque opération avec la direction
de ses arguments, oneway et raises, pour que le code généré les exprime.
Les périphériques d’un microcontrôleur#
Extension — hors de la promesse de stabilité 1.0 (
hardware; le cœur)
include "std/peripherals" déclare une interface par périphérique :
DigitalOut, DigitalIn, Uart, I2cBus, SpiBus, Adc, Pwm, CanBus,
Timer. Un port d’un type intégré fournit l’interface de son type (gpio les
deux numériques, uart Uart, i2c I2cBus, spi SpiBus, analog Adc, pwm
Pwm, can CanBus). Ainsi, inout bus: i2c { requires I2cBus } se relie au
port i2c de n’importe quelle carte. Ce qui les pilote sur chaque carte :
drivers.md.
Un corps dessiné en séquence#
Extension — hors de la promesse de stabilité 1.0 (
scenarios; le cœur)
Une étape de scénario avec expand dessine, après l’étape, ce que fait le corps
app -> ctl : step
ctl -> brk : apply the condition, tested before the choice
brk --> ctl : apply its reply (dashed)
alt [brake.apply(2.5)]
(applied += 1 calls nothing: not drawn)
else
ctl -> brk : release no reply: release gives nothing
end
Une fonction propre appelée (f()) est une étape sur la ligne de vie de la part
elle-même, suivie de ce que fait son corps à son tour. port.op(…) est une
étape vers la part à l’autre bout du lien, suivie de ce que fait le corps du
fournisseur, puis de la réponse (aucune pour une opération oneway ou sans
résultat). send port M { … } est un message vers la part à laquelle le port
est relié. if / else if / else donne un alt avec une branche par cas, un
if seul un opt, while et for un loop, chacun étiqueté avec son propre
texte. Un fragment dont aucune branche n’appelle rien est omis. expand 2
s’arrête deux appels plus bas, et une fonction rencontrée de nouveau en
descendant est dessinée mais pas suivie. Un corps ne peut pas appeler la
fonction d’un enfant : calls child.f est donc dessiné après les étapes du
corps. Un corps Python ou TypeScript n’est pas lu : c’est le calls de sa
fonction qui est dessiné. Une étape dessinée se trouve à la ligne de son appel :
l’éditeur l’ouvre.
Équations physiques#
Extension — hors de la promesse de stabilité 1.0 (
physics; le cœur)
Un type de port avec un potential et un flow est physique : une broche
(tension, courant), une bride (vitesse, force), un arbre, un port thermique, un
tuyau. Une part qui a de tels ports décrit son comportement par des équations
sans direction, avec der(x) n’importe où. Les variables d’un port s’écrivent
port.name. Une var que nomme der est un état (sa valeur est la valeur de
départ). Une var qui a une valeur et pas de der est un paramètre. Une var
sans valeur est une inconnue. Les liens de la part réunissent les ports en
nœuds, où les potentiels sont égaux et où la somme des flux entrant dans les
parts est nulle.
PortVar = ( "potential" | "flow" ) identifier [ "unit" unit ] .
Equation = "equation" Expr "=" Expr . // + - * / ^, der(x), t, functions; no comparison
port-type pin "Electrical pin" {
potential v unit V
flow i unit A
}
component Cell(v: float64 = 1.5V) "Cell" {
inout p: pin
inout n: pin
equation p.v - n.v = v
equation p.i + n.i = 0
}
component Resistor(r: float64 = 100Ω) "Resistor" {
inout p: pin
inout n: pin
var i: float64 unit A
equation p.v - n.v = r * i
equation p.i = i
equation p.i + n.i = 0
}
component Cap(c: float64 = 1mF) "Capacitor" {
inout p: pin
inout n: pin
var v: float64 = 0 unit V
equation v = p.v - n.v
equation c * der(v) = p.i
equation p.i + n.i = 0
}
component Ground "Ground" {
inout p: pin
equation p.v = 0
}
system Rc {
part cell: Cell
part r: Resistor
part c: Cap
part gnd: Ground
cell.p -> r.p
r.n -> c.p
c.n -> cell.n
cell.n -> gnd.p
}Une part a autant d’équations que d’inconnues : ses variables sans valeur, ses
états, le potentiel de chacun de ses ports (leurs flux viennent des liens).
archec vérifie que chaque réseau donne chaque inconnue une seule fois.
archec physics le trie et le résout, archec fit trouve ses paramètres à
partir de données mesurées, archec fmi en fait une FMU, et le simulateur
d’Arche l’exécute comme les équations d’une part physics. Les parts standard
se trouvent dans include "std/physics".
archec physics intègre par défaut à pas fixe avec RK4. Un réseau raide (une
constante de temps rapide à côté d’une lente) demande --integrator implicit ou
trapezoid (chaque pas est résolu par la méthode de Newton), et --tol 1e-6
laisse le pas s’adapter à l’erreur commise.
archec physics … --linearize donne les matrices A, B, C et D du réseau en un
point de fonctionnement, ses modes (constantes de temps, fréquences et
amortissements) et, avec --lqr Q,R, un gain de retour d’état.
--batch 100 --vary motor.r=0.8..1.2 l’exécute cent fois sur des threads de
travail, en tirant chaque fois un paramètre dans sa plage, puis résume les
exécutions (archec sim --batch fait de même pour le comportement).
Corps#
Extension — hors de la promesse de stabilité 1.0 (
physics; le cœur)
Une part peut décrire son corps, pour un moteur physique : sa shape, sa
mass, et la joint par laquelle elle bouge dans la part qui la contient (le
monde pour une part de premier niveau). Toutes deux vont dans le groupe
physical.
Shape = "shape" ( "box" len "," len "," len | "sphere" len | ( "capsule" | "cylinder" ) len "," len ) [ "at" Vec ] [ "rot" Rot ] .
Joint = "joint" [ ( "hinge" | "slide" ) [ Axis ] | "ball" | "free" | "fixed" ] [ "at" Vec ] [ "rot" Rot ] [ "range" Value ".." Value ] [ "=" Value ] .
Axis = "x" | "y" | "z" | "-x" | "-y" | "-z" | "[" Value "," Value "," Value "]" .
Vec = len "," len "," len .
Rot = angle "," angle "," angle | Axis angle .
component Link "Link" {
physical {
mass 1kg
shape capsule 0.04m, 0.5m at 0, 0, -0.25m
}
}
system Arm {
part upper: Link {
joint hinge y at 0, 0, 1.5m range -2..2 = 0.3
part fore: Link {
joint hinge y at 0, 0, -0.5m
}
}
}Les dimensions d’une boîte sont ses dimensions complètes. Celles d’une capsule
ou d’un cylindre sont son rayon et sa longueur, selon z. at donne la position
du centre de la forme dans le repère de la part, ou la position du repère de la
part dans celui de son parent : c’est là que se trouve la liaison. rot fait
tourner la forme dans le repère de la part, ou le repère de la part dans celui
de son parent : roulis, tangage, lacet (rot 0, 0, 90deg, autour du x du
parent, puis de y, puis de z : le rpy d’URDF) ou un axe et un angle
(rot z 90deg, rot [1, 1, 0] 45deg). Un angle sans unité est en rad. L’axe de
la liaison, la forme, l’emplacement des capteurs et des propulseurs et les
parts intérieures sont exprimés dans le repère tourné
(joint hinge y at 0, 0, 1m rot z 90deg pivote autour du -x du parent). La
range et la position de départ d’une charnière sont en rad, celles d’une
glissière en m. L’axe est z quand il n’est pas précisé.
archec gen --target mujoco crée un corps pour chaque part qui a une masse ou
une forme, imbriqués comme le sont les parts.
archec import robot.urdf et archec import scene.xml (MJCF) écrivent un robot
de cette façon : une part par corps, avec sa mass, sa shape et sa joint.
Ce que ces formats disent en plus devient des enregistrements prop
(prop shoulder = {damping: 0.1, effort: 20}, prop inertial = {…}, les
géométries supplémentaires en
prop rod = {geom: capsule, size: [0.02, 0.25]} avec les dimensions de
MuJoCo). Un actionneur est une part kind actuator dans le corps dont il
entraîne la liaison, un capteur une part kind sensor dans le corps qu’il
mesure. Leur nature vient de l’unité du message qu’ils reçoivent ou envoient.
Le noise et le cutoff d’un capteur deviennent le noise de son port et la
range de ses champs. La forcerange et le filtre d’un actionneur deviennent
la force-range et le lag de son port. Chaque <key> (le premier donne aussi
les positions de départ des liaisons) devient une keyframe du système.
Géométrie#
Extension — hors de la promesse de stabilité 1.0 (
cad; le cœur)
Un composant peut dire sa géométrie : un fichier Python qui définit part, un
solide build123d, et en option anchors, les endroits nommés où se placent les
autres parts. Ce dont il est fait suit le fichier dans un bloc, ou s’écrit à
côté (les trois peuvent aller dans le groupe physical, avec la masse et la
forme). Une part d’un système peut avoir sa propre géométrie, et une place :
une ancre de la géométrie d’une autre part.
Cad = "cad" string [ "{" { Material } "}" ] .
Material = "material" identifier | "density" quantity .
Place = "at" Path .
Clearance = "clearance" Path "," Path Compare quantity .
CadLimit = "limit" Path Compare quantity { "," quantity } .
Compare = "<=" | "<" | ">=" | ">" .
Pcb = "pcb" string .
Outline = "outline" quantity "," quantity .
Hole = "hole" quantity "at" quantity "," quantity .
Fits = "fits" Path "," Path [ ( "<=" | "<" ) quantity ] .
Sourced = "sourced" identifier .
requirement REQ-BOX "Fits the bracket" {
text "The enclosure shall be at most 120 mm × 95 mm × 40 mm, and weigh at most 80 g."
limit Enclosure.size <= 120mm, 95mm, 40mm
limit Enclosure.mass <= 80g
}
component Enclosure "Enclosure" {
cad "cad/enclosure.py" { material PETG }
}
system Assembly {
part box: Enclosure
part relay: GpioRelay { cad "cad/relay.py"; at box.relay }
clearance box, relay >= 0mm
}
Le chemin d’une limite se termine par ce qui est mesuré : size (la boîte
englobante, trois bornes selon x, y et z, ou une seule pour les trois), mass
ou volume. Avant vient un composant avec un cad, ou une part d’un système.
Un material est un nom de la table de cad.md, ou une constante dont
la valeur est une densité. Une borne s’écrit avec son unité et est convertie
(mm, cm, m ; g, kg ; mm³, cm³, L) : une borne dans une
autre sorte d’unité est une erreur. Un limit sans comparaison est la borne
d’une metric, comme avant, et at x, y est une place sur le canevas.
archec cad exécute chaque fichier, écrit du STEP, du STL et du GLB dans
build/cad/, mesure la géométrie, place les parts et vérifie les limites et
les jeux. Une limite ou un jeu écrit dans une exigence est enregistré comme
preuve pour elle. Des parts qui se touchent sont à 0 mm l’une de l’autre ;
des parts qui s’interpénètrent échouent à tous les jeux. Le budget de masse
(budget mass 150g) compte la masse mesurée d’une part qui a une géométrie et
un matériau. cad.md dit tout.
Une part dont la géométrie est construite est un corps pour la physique
(archec gen --target mujoco, la vue 3D) : son maillage, et la masse, le
centre de masse et l’inertie mesurés, remplacent un shape et un mass écrits.
Une valeur écrite qui diffère de la valeur mesurée donne un avertissement qui
indique les deux.
Un composant peut aussi dire ce qu’il est en tant que carte : pcb nomme un
fichier de carte KiCad, dont on lit le contour (la couche Edge.Cuts) et les
trous de fixation (les empreintes MountingHole) ; sans lui, outline donne la
taille de la carte selon x et y, et chaque hole le diamètre d’un trou de
fixation et son centre depuis le coin inférieur gauche du contour.
fits board, box, dans un système ou une exigence, vérifie que chaque
entretoise que le boîtier donne à la carte (mounts dans le fichier de sa
géométrie) est sous un trou de la carte, à 0,2 mm près ou à la longueur écrite.
sourced Assembly, dans une exigence, vérifie que chaque part achetée d’un
système a un part-number. archec cad lance l’ERC et le DRC de KiCad sur une
carte qui nomme son pcb quand kicad-cli est installé, et les enregistre pour
les exigences que le composant satisfait.
requirement REQ-MOUNT "The board screws onto the tray" {
text "The tray's standoffs shall be under the board's mounting holes."
fits board, tray
}
requirement REQ-BUY "What is bought can be ordered" {
text "Every bought part of the unit shall have a part number."
sourced Unit
}
component Controller "Controller board" {
pcb "hw/controller.kicad_pcb"
cad "cad/board.py" { material FR4 }
}
component Shield "A bought board" {
physical {
outline 50mm, 40mm
hole 3.2mm at 3.5mm, 3.5mm
hole 3.2mm at 46.5mm, 36.5mm
}
}
component Tray {
cad "cad/tray.py" { material PETG }
}
system Unit {
part tray: Tray
part board: Controller { at tray.board }
}
Composants FPGA#
Extension — hors de la promesse de stabilité 1.0 (
fpga; le cœur)
Un composant doté d’une horloge est un composant FPGA : du matériel, écrit comme n’importe quel autre composant.
type Adc12 = uint16 { bits 12 }
message WRAP "Wrapped" { turns: uint16 }
component Counter "Counter" {
clock clk 100MHz
reset rst_n active low async
step tick
in enable: bool
in sample: Adc12
out wrap: data sends WRAP
var count: uint8 = 0
var turns: uint16 = 0
fn tick ```arche
if enable { count += 1 }
if count == 0 {
turns += 1
send wrap WRAP { turns: turns }
}
```
}clock <name> <frequency>(clock clk 100MHz) en fait un composant FPGA.clock 10ms, une seule valeur, reste la période d’un composant qui n’est pas du matériel.reset <name>prendactive high(par défaut) ouactive low, etsync(par défaut) ouasync. Sansreset, c’estrst, actif à l’état haut, synchrone.step <fn>nomme la fonction appelée à chaque cycle.- Un port dont le type est un type de donnée est un signal de cette largeur :
bool, un type entier, une énumération, ou untypeavecbits N. Dans un corps, c’est un nom : un signalinse lit, un signalouts’affecte. Un port quisendsoureceivesest une poignée de main valid / ready avec les champs du message. - Une
varest un registre. Un blocmemoryavec une adresse est un registre du banc AXI4-Lite :rwetwsont écrits par le bus et lus par la logique,rest piloté par la logique.
À chaque front montant, dans l’ordre : fn main jusqu’à son prochain wait ;
chaque message arrivé (sa transition, le on-receive du port, ses handlers) ;
les transitions on "after …", comptées en cycles ; les transitions avec une
garde et sans déclencheur, essayées à chaque cycle ; la fonction step. Les
sorties sont registrées. Le simulateur exécute ainsi une part FPGA, cycle par
cycle.
archec check signale dans un composant FPGA ce qui ne peut pas être synthétisé
(fpga-synthesis, fpga-recursion) : flottants, chaînes, tableaux sans taille,
boucles while et boucles for dont les bornes ne sont pas des constantes,
récursion, appels à une autre part, corps Python et TypeScript, un wait hors
de fn main. Une affectation qui perd des bits est un avertissement
(fpga-width).
archec gen --target vhdl écrit chaque composant FPGA sous forme d’entité
VHDL-2008, les données du modèle sous forme de package, les parts FPGA du
système sous forme d’entité top, et un testbench GHDL par cas de test.
archec test --target vhdl exécute les cas dans GHDL : chacun est une preuve au
lieu ghdl, et laisse une trace que lisent archec why, why-not et timing.
archec synth synthétise les parts FPGA d’un système, puis les place et les
route, pour le circuit que nomme sa part kind fpga (chip "iCE40UP5K-SG48",
chip "LFE5U-25F-6BG381"). Une exigence borne ce qu’il mesure d’un composant
FPGA ou d’un système qui a des parts FPGA : limit Pwm.luts <= 500, et de même
pour ffs, bram et dsp ; limit Pwm.fmax >= 100MHz. Une limite sur autre
chose, ou avec une borne qui n’est ni un nombre de cellules ni une fréquence, est
une erreur (synth-limit). Un chip pour lequel archec ne sait pas synthétiser
est un avertissement (synth-device). Ce qui est mesuré est une preuve au lieu
synth <device>. fpga.md dit tout.
Capteurs et actionneurs#
Extension — hors de la promesse de stabilité 1.0 (
physics, mais lenoiseet laresolutiond’un capteur sont du cœur ; le cœur)
Un capteur lit ce qui est, mais pas exactement. Un actionneur fait ce qu’on lui
demande, mais pas tout de suite. Une part kind sensor indique comment elle lit
sur son port de sortie, une part kind actuator comment elle agit sur son port
d’entrée : c’est le groupe response.
noise σ of a gaussian noise on each float field of that quantity: 0.002rad, or 0.05m/s², 0.001rad/s
resolution the step a reading is rounded to: 0.0015rad
latency how old the reading is (on an actuator's in port: its dead time)
gain output = gain × command (1 when not said)
lag a first-order lag from the command to the output: 20ms
force-range where the output saturates: -2..2
message ANGLE { angle: float64 unit rad range -3.2..3.2 }
message TORQUE { torque: float64 unit N·m range -1..1 }
component Encoder "Encoder" {
kind sensor
out angle: data sends ANGLE {
noise 0.002rad
resolution 0.0015rad
latency 2ms
}
}
component Motor "Motor" {
kind actuator
in cmd: data receives TORQUE {
response { gain 2; lag 20ms; force-range -1.5..1.5 }
}
}Une lecture est la valeur plus son bruit, saturée par la range du champ (le
cutoff de MuJoCo), puis arrondie à la résolution. Un bruit exprimé dans une
autre unité de la grandeur du champ est converti (1deg sur un champ en rad).
Un nombre sans unité s’applique à tous les champs flottants. Une commande est
d’abord bornée par la range de son champ (le ctrlrange de MuJoCo) : c’est ce
que voient les handlers de la part. La sortie la suit à travers le retard,
multipliée par le gain, saturée par la force-range. La latency d’un port
s’ajoute à celle de ses liens.
Le bruit est tiré à partir d’une graine (simulation { seed 7 }, --seed, 1
sinon), avec un même générateur partout : archec sim et sa page, le pont
MuJoCo, le C d’un build de simulation (-DARCHE_SIM : le firmware de
production n’ajoute aucun bruit ; les bornes et le retard sont toujours là).
Ainsi, une exécution se répète, et archec difftest compare les deux côtés avec
le bruit actif. Dans un réseau physique, le signal in d’un actionneur prend sa
commande à <port>.command et agit à travers la plage de son type, son retard
(un état du réseau : archec physics --linearize montre son mode), son gain et
sa force-range. Le signal out d’un capteur est affiché tel qu’il le lit.
archec avertit d’un bruit là où aucun capteur ne lit ou d’un gain là où aucun
actionneur n’agit (realism-port), d’un bruit d’une grandeur qu’aucun champ n’a
(unit-mismatch) et d’une plage à l’envers (range-reversed).
Keyframes#
Extension — hors de la promesse de stabilité 1.0 (
scenarios; le cœur)
Une keyframe dans un système est un état de départ nommé, comme celles de
MuJoCo. Chaque ligne fixe une variable d’une part, la position de la liaison
d’une part (part.joint, en rad ou en m) ou la commande avec laquelle démarre
un actionneur (son port d’entrée).
Keyframe = "keyframe" identifier [ Text ] "{" { Path "=" Value } "}" .
message TORQUE { torque: float64 unit N·m range -1..1 }
component Link "Link" {
physical { mass 1kg; shape capsule 0.04m, 0.5m at 0, 0, -0.25m }
}
component Motor "Motor" {
kind actuator
in cmd: data receives TORQUE
}
component Ctrl "Controller" {
out cmd: data sends TORQUE
var target: float64 = 0
}
system Arm {
part upper: Link {
joint hinge y at 0, 0, 1.5m
part motor: Motor
}
part ctrl: Ctrl
ctrl.cmd -> upper.motor.cmd
keyframe raised "Raised" {
upper.joint = 1.2
upper.motor.cmd = 0.3
ctrl.target = 1.2
}
}archec sim --keyframe raised et archec physics --keyframe raised partent de
cet état (et --linearize --at raised y linéarise), archec gen --target mujoco
l’écrit sous forme de <key>, et un cas de test avec keyframe raised part de
ses variables. Une ligne qui ne désigne rien de modifiable est une erreur
(keyframe-name).
La ligne d’une liaison dépend de sa sorte, comme les qpos et qvel de MuJoCo :
| Liaison | Où elle se trouve | À quelle vitesse elle bouge |
|---|---|---|
hinge, slide |
part.joint = 0.3 (rad, m) |
part.joint.vel = 1 (rad/s, m/s) |
ball |
part.joint = [0, 0, 30deg] (roulis, tangage, lacet) ou [w, x, y, z] (un quaternion) |
part.joint.vel = [wx, wy, wz] (rad/s, dans son repère) |
free |
part.joint.at = [x, y, z] et part.joint.rot = [r, p, y] (ou [w, x, y, z]), dans le monde |
part.joint.vel = [vx, vy, vz] (m/s, dans le monde), part.joint.spin = [wx, wy, wz] (rad/s, dans son repère) |
Ce qu’une ligne ne fixe pas reste à la position de départ de la liaison : un corps libre là où ses parts le placent.
Un instant#
Ce qui se passe à un instant donné se passe dans un ordre défini par le modèle,
et non par la machine, comme dans Lingua Franca. Le simulateur (archec sim)
suit cet ordre, le C qu’écrit archec gen le suit au sein d’un thread, et
archec difftest vérifie que les deux concordent.
- Le temps est logique : un corps ne prend aucun temps, sauf s’il attend
(
wait 10ms). - Ce qui est dû au même instant s’exécute dans l’ordre où cela a été planifié : un message envoyé sur un lien sans latence passe après ce qui était déjà dû à cet instant.
- Au démarrage : les watchdogs de chaque part sont armés et sa machine entre
dans son état initial, les parts dans l’ordre où le système les déclare (les
parts d’une part après elle). Ensuite, chaque
fn maindémarre. Puis viennent les threads périodiques, dans l’ordre où le déploiement les déclare, le premier appel une période plus tard. - Une part fait une seule chose à la fois, jusqu’au bout. Ce qui lui arrive pendant ce temps attend dans sa boîte aux lettres, dans l’ordre d’arrivée.
- Un message vers une part déclenche d’abord la transition unique qu’il
provoque : on part de l’état le plus intérieur où se trouve la part et on
remonte, dans l’ordre d’écriture à chaque niveau,
* ->en dernier (et non prise quand la part est déjà dans son état cible) ; c’est la première dont la garde est vraie. Viennent ensuite leon-receivedu port, puis les handlers du port dans l’ordre d’écriture. Une garde et une action voient les champs du message par leur nom. - Une transition exécute le
on-exitde chaque état qu’elle quitte, le plus intérieur d’abord, puis son action, puis leon-enterde chaque état où elle entre, le plus extérieur d’abord. Elle quitte et réintègre ce qui se trouve dans l’état le plus intérieur qui entoure à la fois sa source et sa cible (pour* ->etgoto, la source est l’état où se trouve la part). Ainsi,Up -> UpquitteUpet ses états intérieurs, puis y entre de nouveau. on "after 500ms"compte à partir de l’entrée dans l’état. Y entrer de nouveau relance le décompte. En sortir l’arrête.- Un message envoyé là où des liens se séparent les suit dans l’ordre où ils sont écrits.
- Une variable garde ce que son type peut contenir : un
uint8à 255 plus 1 vaut 0, un entier divisé par un entier donne un entier, unfloat32est arrondi en conséquence.
message BEAT { seq: uint16 }
component Monitor "Monitor" {
in beat: can receives BEAT
states {
state Waiting
state Up
state Lost
Waiting -> Up on BEAT
Up -> Up on BEAT [seq > 0]
Up -> Lost on "after 30ms"
Lost -> Up on BEAT
}
}
system Net {
part monitor: Monitor
}Chaque battement dont le seq est supérieur à 0 fait entrer de nouveau dans
Up : ses 30 ms repartent de zéro.
La vie d’une part#
Extension — hors de la promesse de stabilité 1.0 (
components; le cœur)
Une part peut indiquer ce qu’elle exécute quand elle est créée, démarrée,
arrêtée et libérée, comme dans les frameworks à composants : on-init,
on-start, on-stop et on-release, chacun étant un corps sur le composant.
component Filter "Filter" {
var taps: uint16 = 0
var running: bool = false
on-init ```arche
taps = 64
```
on-start ```arche
running = true
```
on-stop ```arche
running = false
```
on-release ```arche
taps = 0
```
}
system Rx {
part filter: Filter
}archec sim exécute le on-init de chaque part, puis le on-start de chaque
part, à l’instant 0, dans l’ordre des parts, avant que les machines à états
entrent dans leur premier état et que les fn main démarrent. À la fin de
l’exécution (--for), il exécute le on-stop de chaque part, puis chaque
on-release. Une définition construite sur une autre (extends) reprend ceux
de sa base quand elle n’en indique pas. Le modèle des générateurs les donne
comme lifecycle de chaque composant, avec leur C, C++, Rust et Go.
Échéances et watchdogs#
Extension — hors de la promesse de stabilité 1.0 (
machines, etdeploymentpour un watchdog ; le cœur)
Un port ou une transition peut indiquer à partir de quand c’est trop tard. Une
fois son deadline dépassé (la part commence à traiter le message plus
longtemps que cela après son envoi, ou le timer plus longtemps que cela après
son expiration), c’est son on-deadline qui s’exécute à la place (sur un port :
à la place des transitions, du on-receive et des handlers ; sur une
transition : une fois sa garde vraie, à la place de la transition). Un
watchdog exécute son on-timeout quand aucun kick ne l’a relancé dans son
timeout. Il est armé au démarrage. Une fois expiré, seul un kick le réarme.
message CMD { level: uint8 }
component Actuator "Actuator" {
in cmd: can receives CMD {
on-receive ```arche
kick quiet
```
deadline 5ms
on-deadline ```arche
late += 1
```
}
var late: uint16 = 0
watchdog quiet "Commands stopped" {
timeout 50ms
on-timeout ```arche
goto Safe
```
}
states {
state Idle
state Active
state Safe
Idle -> Active on CMD [level > 50]
Active -> Idle on CMD [level < 20] {
deadline 2ms
on-deadline ```arche
late += 1
```
}
Safe -> Idle on CMD [level == 0]
}
}
system Plant {
part act: Actuator
}Les deux sont simulés, et générés en C et en Rust (Embassy : ce qui arrive à une part qui a une échéance porte l’instant de son envoi, et la tâche de la part attend son prochain watchdog en même temps que ses entrées). Le simulateur d’Arche ne les prend pas encore en charge.
Algorithmes et flux de données#
Extension — hors de la promesse de stabilité 1.0 (
communication; le cœur)
Un algorithme de traitement du signal est un composant avec kind algorithm.
Ses ports transportent les données. Son cycle est formé des fonctions qu’il
possède parmi initialize, configure, execute_preprocessing, execute,
execute_postprocessing et reset (archec sim exécute initialize et
configure au démarrage). Ses paramètres d’instanciation sont les paramètres du
composant. Une var avec parameter configuration est redéfinie à chaque
configuration, une var avec parameter internal lui est propre.
working-memory saved 1KiB et working-memory tmp 4KiB indiquent la mémoire
dans laquelle il travaille. Le place d’un déploiement indique l’allocateur.
stereotype indique de quelle sorte d’algorithme il s’agit : splitter (une
entrée, plusieurs sorties), joiner (plusieurs entrées, une sortie),
cylinder, macro-algo, do-not-use-sw-caches, pipeline,
local-memory-only. Sur une part, disable-thresholds et
bypass-config-threading concernent l’instance.
Un algorithme qui a des parts est un composite : ses parts sont ses rôles, ses
liens les connexions entre eux, et ses ports écrits = part.port ses
délégations. Il est L1 quand ses parts sont de simples algorithmes, LN quand
l’une d’elles est un composite. Le after d’une part l’exécute après une autre
part, sans données entre elles.
Une métrique est un message avec kind metric. Un port de sortie qui l’envoie
la publie sur /<part path>/<metric> (ou sur son topic). Un port d’entrée la
lit, et son topic filtre ce qu’il prend : * pour un niveau, ** pour un
nombre quelconque. (Le splitter et le joiner sont écrits en entier dans
examples/signal-chain.)
message SNR { kind metric; value: float32 }
component Filter(taps: int32 = 16) {
kind algorithm
processing { stereotype pipeline; working-memory tmp 4KiB }
var gain: float32 = 1.0 { parameter configuration }
in input: data receives FRAME { handler FRAME -> execute }
out output: data sends FRAME
out snr: data sends SNR { pattern pub-sub }
fn configure ```arche
gain = clamp(gain, 0.0, 4.0)
```
fn execute(seq: uint32, level: float32) ```arche
send output FRAME { seq: seq, level: level * gain }
send snr SNR { value: level * gain }
```
}
component Chain {
kind algorithm
in input = split.input
out output = join.output
part split: Splitter
part f1: Filter(taps = 32)
part f2: Filter { after f1 }
part join: Joiner
split.left -> f1.input
split.right -> f2.input
f1.output -> join.left
f2.output -> join.right
}
Le linter signale un stéréotype du mauvais côté (celui d’une instance sur une
définition), un splitter ou un joiner qui n’a pas les bons ports, une part d’un
composite qui n’est pas un algorithme, des parts qui s’exécutent les unes après
les autres en cercle, un filtre de métrique sur lequel rien n’est publié, et un
lien de flux de données dont les deux extrémités ne décrivent pas la
contre-pression de la même façon (backpressure on aux deux extrémités, voir
Services, flux de données et topics).
Exigences et traces#
Une exigence est un énoncé, accompagné de ce qui la caractérise (priority,
status, method…). Une trace relie deux éléments. Elle s’écrit là où elle
part, sous forme de propriété (satisfies, verifies, derives,
refines…), chaque valeur avec son identifiant si elle en a un :
TraceProperty = tracekey TraceValue { "," TraceValue } .
TraceValue = Path [ "as" identifier ] .
TraceDecl = "trace" tracekey Path "->" TraceValue { "," TraceValue } [ Text ] .
requirement REQ-1 "Start" {
text "The pump shall start within 100 ms of a START command."
priority high
}
component Pump "Pump" {
satisfies REQ-1 as s-1
}
system Field {
part pump: Pump
}Un lien vers une exigence s’écrit sur ce qui la satisfait (satisfies sur un
composant, une part, un port ou une fonction) ou sur ce qui la vérifie (verifies
sur un cas de test, un plan de test ou un scénario). Une ligne trace sert aux
autres sortes (derives, refines, allocates, realizes, involves, deploys, traces),
et à un lien qui porte un commentaire. Les anciennes formes sont lues jusqu’à 0.13
(requirement-link, un avertissement, une erreur avec edition "0.13") :
satisfied-by et verified-by sur l’exigence, trace satisfies et
trace verifies, et tests dans le bloc verify d’une exigence. La correction
rapide et archec fmt en déplacent une quand les deux bouts sont dans le même
fichier et que la construction reste la même ; archec refactor move-traces
déplace les autres, en vérifiant la construction. À partir de 0.13, le bloc
verify d’une exigence liste, pour l’ivv d’Arche, les tests qui disent la
vérifier.
Extension — hors de la promesse de stabilité 1.0 (
requirements, pour une phraseears;formalest du cœur ; le cœur)
Une exigence peut s’écrire en EARS, à propos des parts du modèle, et être prouvée :
ears "[while <state>,] [when|if <trigger>,] <part> shall <response> [within <time>]"
<trigger> = <part> receives <MESSAGE> | <part> enters <State> | <state>
<response> = be in <State> [or …] | not be in <State> | send <MESSAGE>
formal "never brakes in Fault" | "always …" | "eventually … [within <time>]"
| "<a> leads to <b> [within <time>]" | "<a> implies <b>"
archec vérifie les parts, les états et les messages que nomme une phrase
ears. Cette phrase sert de texte à l’exigence quand elle n’en a pas, et
fournit sa propriété formal. archec verify prouve les propriétés formal
avec NuSMV (sans le temps : un within est vérifié par les moniteurs,
archec replay et archec verify --conflicts).
archec gen --target ears-tests écrit un cas de test par exigence EARS.
archec verify --conflicts trouve les exigences qu’aucune implémentation ne
peut satisfaire ensemble (de façon bornée : le temps est compté en ticks).
archec verify --meaning dessine sur une ligne de temps ce que dit chaque
propriété.
Vérification#
Un plan de test contient des cas. Un cas est une ligne de temps faite de moments :
at 10ms do …, at 10ms expect …, at 20ms fault … et within 100ms expect …
(au plus tard 100 ms après le at qui le précède). Un nom après l’heure nomme
l’étape dans les rapports : at 0ms "Engage" do …. Un at ne commence pas avant
son heure ; il commence plus tard si une attente avant lui a pris du temps. Les
lignes d’une même heure s’exécutent dans l’ordre où elles sont écrites. Les
stimuli d’une simulation sont les mêmes lignes, avec at … do seulement. Les
anciens blocs, le step "…" { do …; wait 10ms; expect … } d’un cas et le
stimulus "…" { at 5ms; do … } d’une simulation, sont lus jusqu’à l’édition 0.13
(old-form). archec fmt les réécrit en lignes de temps, à l’identique, ou dit
pourquoi il ne le peut pas.
Lignes de test#
Ce qu’un moment fait et attend s’écrit dans le langage d’actions, comme un corps, avec les parts du système pour noms :
at 0ms do send probe.water WATER { temperature: 20.0 } a message sent from a part's port
at 0ms do ctl.target = 90.0 a part's variable set
at 5ms do send hmi.bus ENGAGE_REQ(true) a message that carries one value
within 100ms expect ctl.state == Idle a part's state, by its name
at 1s expect sent(HEAT) >= 1 and not relay.closed sent(MSG), received(MSG), received(part, MSG), now()
within 50ms expect never: sent(BRAKE_CMD) > 0 within …:, never:, always:, eventually: kept as before
Une part se nomme par son chemin (ctl, arm.ctrl), ou par son seul nom là où
une seule part le porte ; puis l’une de ses variables (celle d’un appareil du
store aussi : relay.closed), ses ports (dans send) ou son state. Les
constantes et les enums du modèle, les fonctions intégrées du langage d’actions,
et sent(MSG), received(MSG) (combien depuis le début du cas) sont les autres
noms. Une ligne est vérifiée comme un corps : une part, une variable, un port,
un message, un champ ou un état inconnu est une erreur (test-line) là où il
est écrit, tout comme une instruction de corps (wait, goto) : les heures
sont celles des moments.
Dans quel langage une ligne est lue : une ligne qui se lit dans le langage
d’actions et passe la vérification est du langage d’actions ; une ligne avec
une forme que seul le langage d’actions a (send p M { … }, true, un
enregistrement, une durée, x.state == Idle, sent(MSG)) est du langage
d’actions, et ses erreurs sont signalées ; tout le reste est du Python, comme
avant (send(p, M(a=1)), True, elapsed()). Une ligne qui se lit de la même
façon dans les deux (ctl.target = 90.0, not relay.closed,
ctl.state == "Idle") veut dire la même chose dans les deux, et s’exécute
telle qu’elle est écrite ; une ligne dont le sens différerait (une division
de deux entiers) reste du Python. Un bloc ```arche dans un do ou un
expect est du langage d’actions, un bloc ```python du Python. La règle
est la même dans toutes les éditions.
Les simulateurs exécutent les lignes du langage d’actions traduites : en
Python pour celui d’Arche, en TypeScript dans un projet handlers typescript,
et le simulateur du navigateur, les tests C et Renode lisent la traduction
Python comme ils lisent une ligne Python. archec test donne donc les mêmes
verdicts. Une ligne Python relève de l’extension codegen
(archec check --core) ; l’indication arche-test-line et archec fix
écrivent les plus courantes dans le langage d’actions
(send(p.out, M(a=1)) → send p.out M { a: 1 }, True → true,
x.state == "S" → x.state == S, sent("M") → sent(M)), et laissent ce
qu’ils ne savent pas dire.
Les cas qui ne diffèrent que par leurs valeurs s’écrivent une seule fois, avec
un tableau (cases : une extension, testing) :
component Box {
var speed: float32 = 0
}
system Rig {
part box: Box
}
test-plan TP "Speeds" {
cases "Speed {v}" {
at 0ms do box.speed = {v}
at 1ms expect box.speed == {v}
rows {
id | v
TC-1 | 10
TC-2 | 30
}
}
}Sûreté#
Extension — hors de la promesse de stabilité 1.0 (
safety; le cœur)
Un danger est évalué (severity, exposure, controllability) et son ASIL en
est déduit. Les modes de défaillance et les portes forment son arbre de fautes
quand on l’écrit à la main. Une part peut aussi dire quelles erreurs elle
produit et ce que deviennent celles qui l’atteignent (son modèle d’erreurs) :
archec en déduit alors l’arbre.
ErrorType = "omission" | "commission" | "value" | "early" | "late" .
Produces = "produces" ErrorType { "," ErrorType } . // on an output
Contains = "contains" ( ErrorType | "all" ) { "," ErrorType } . // on an input
Turns = "turns" ErrorType { "," ErrorType } "into" ErrorType . // on an input
From = ( "from" | "from-all" ) identifier { "," identifier } . // on an output: the inputs behind it
TopEvent = "error" ErrorType { "," ErrorType } "on" Path . // on a hazard
message SPEED: float32
message CMD: float32
component Sensor {
out speed: can sends SPEED {
produces omission
}
}
component Ctrl {
in a: can receives SPEED {
turns value into omission
}
in b: can receives SPEED
out cmd: can sends CMD {
from-all a, b
}
}
component Brake {
in cmd: can receives CMD
}
system Car {
part s1: Sensor
part s2: Sensor
part ctrl: Ctrl
part brakes: Brake
s1.speed -> ctrl.a
s2.speed -> ctrl.b
ctrl.cmd -> brakes.cmd
}
failure-mode FM-S1 "Sensor 1 dead" {
of Car.s1
produces omission
probability 1e-5
}
hazard HZ-01 "No braking on demand" {
severity S3
exposure E4
controllability C3
goal SG-01
error omission on Car.brakes.cmd
}
safety-goal SG-01 "Brake on demand" {
safe-state "Braking"
}Une erreur se propage le long des liens. À travers une part, elle va de chaque
entrée vers chaque sortie (ou vers celles dont le from la nomme), sauf si
l’entrée la contient. turns change son type. from-all exige l’erreur sur
chaque entrée nommée (un ET). Les événements de base sont les modes de
défaillance qui produce une erreur sur leur élément, avec leur probability,
ou le produces de la part seul, sans taux. Un danger écrit des deux façons est
vérifié : les deux arbres doivent avoir les mêmes coupes minimales.
Une analyse STPA prend l’architecture comme structure de contrôle : une
control-action va from une part contrôleur to la part qu’elle contrôle, en
passant par les liens. Elle contient ses actions de contrôle dangereuses, une ou
plusieurs pour chacun des quatre types (not-provided, provided, timing,
duration), ou le type déclaré not-applicable. Chaque uca nomme les dangers
qu’elle causes et l’exigence (constraint) qui l’empêche, et contient ses
loss-scenario.
Vues#
Extension — hors de la promesse de stabilité 1.0 (
design; le cœur)
Un viewpoint qui dit ce qu’il inclut est un diagramme à part entière : une
requête sur un système, et non un dessin. Ses termes sont lus dans l’ordre,
chaque exclude retirant ce qu’un include précédent a ajouté. Les blocs qu’il
sélectionne, à n’importe quelle profondeur, sont dessinés avec les liens entre
eux et placés automatiquement (archec diagram, l’éditeur).
Term = "*" | Path [ ".*" | ".**" ] | ( "kind" | "tag" | "layer" ) identifier
| Selector ( "->" | "<->" ) Selector .
Selector = "*" | Path [ ".*" | ".**" ] | ( "kind" | "tag" | "layer" ) identifier .
message GO: bool
component Sensor { out o: can sends GO }
component Ctl { in i: can receives GO; out o: can sends GO }
component Brake { in i: can receives GO }
system Car {
part lidar: Sensor
part adcu: Ctl
part brakes: Brake
lidar.o -> adcu.i
adcu.o -> brakes.i
}
viewpoint braking "Braking" {
of Car
include * -> adcu, adcu -> *
exclude lidar
}* désigne les parts de premier niveau du système, adcu.* les parts d’adcu,
adcu.** tous les blocs qu’il contient. * -> adcu désigne adcu et les blocs
qui lui envoient des messages, chacun pris au niveau d’adcu (un lien de
cam.isp vers adcu amène cam). depth 2 va jusqu’à deux liens de distance.
Un lien entre des blocs qui ne sont pas dessinés est tracé entre les blocs les
plus proches de ses extrémités. Un terme qui ne correspond à rien donne un
avertissement view-empty. Les noms que donne un terme sont des références : un
renommage dans l’éditeur les renomme aussi.
La position des blocs d’un diagramme ne fait pas partie du modèle : l’éditeur
garde les positions choisies à la souris dans une vue dans main.layout.json, à
côté du fichier principal, par diagramme et par élément
("view:braking": { "Car.adcu": {"at": [420, 200]} }), et un renommage les
renomme. Un bloc placé dans la source (at, une ligne canvas) garde cette
position. Les autres sont placés automatiquement.
Interface utilisateur#
Extension — hors de la promesse de stabilité 1.0 (
ui; le cœur)
Un bloc ui, dans le composant (ou le système) qui possède un écran, décrit
l’interface utilisateur du produit (le guide). À l’intérieur de ce
bloc, et seulement là, les mots ci-dessous ouvrent des déclarations. Ailleurs,
ce sont des noms comme les autres.
Ui = "ui" "{" { UiProp | Screen | ElementDef } "}" .
Screen = ( "screen" | "dialog" | "overlay" ) identifier [ string ] "{" { Prop | Item } "}" .
Item = Layout | Element | Use | For | If | Fits .
Layout = ( "row" | "column" | "grid" | "stack" ) [ identifier ] [ "{" { Prop | Item } "}" ] .
Element = ElementWord [ identifier ] [ string ] [ "{" { Prop | Binding | Event } "}" ] .
ElementDef = "element" identifier "(" [ Param { "," Param } ] ")" "{" { Item } "}" .
Param = identifier ":" [ "bind" ] Type .
Use = identifier [ identifier ] "(" [ Arg { "," Arg } ] ")" [ "{" { Prop } "}" ] .
Arg = [ identifier ":" ] ( string | Expression ) .
For = "for" identifier "in" Expression "max" integer "{" { Item } "}" .
If = "if" Expression "{" { Item } "}" { "else" "if" Expression "{" { Item } "}" } [ "else" "{" { Item } "}" ] .
Fits = "fits" "{" { Layout } "}" .
Binding = ( "value" | "enabled" | "visible" ) Expression .
Event = "on" ( "press" | "release" | "long-press" | "change" | "enter" | "exit" ) ( Statements | "{" Statements "}" | CodeBlock )
| "on" Expression .
ElementWord est l’un de spacer label gauge bar chart telltale image list table button toggle slider select input stepper custom. Un ElementDef s’écrit dans
un ui ou en tête de fichier ; son Use, sans espace avant (, est
développé en ce qu’il contient (archec ui montre le résultat), un paramètre
bind prenant une variable de la part. if/else donnent un visible à ce
qu’ils contiennent ; for dessine son unique élément au plus max fois ;
fits garde la première disposition qui tient sur l’écran. L’Expression d’une liaison
de données et les Statements d’un événement relèvent du langage d’actions
(Actions) et sont lus jusqu’à la fin de la ligne (ou du bloc). Les
noms qu’on peut y utiliser sont les variables de la part (speed), son
state, le dernier message reçu sur un port (bus.STATUS.speed, ou
bus.FAULT pour un message qui est une seule valeur), l’état et les variables
d’une part voisine (ctrl.state, ctrl.speed) et les constantes. Un événement
envoie (send port MSG(args), les arguments dans l’ordre des champs, ou
MSG { field: value }), passe d’un écran à l’autre (goto Screen, back),
modifie les variables propres de la part, prend des décisions (if), journalise
et appelle les fonctions de la part. Un texte affiche des valeurs avec
${expression}.
message STATUS { speed: float32 unit km/h range 0..200 }
message STOP { hard: bool }
component Ctrl {
in cmd: data receives STOP
out st: data sends STATUS
states {
state Running
state Stopped
Running -> Stopped on STOP
}
}
component Panel {
in bus: data receives STATUS
out cmd: data sends STOP
ui {
display 800x480
screen Main "Main" {
gauge speed "Speed" { value bus.STATUS.speed }
label state { text "Now: ${ctrl.state}" }
button stop "Stop" { style danger; enabled ctrl.state == Running; on press send cmd STOP(true) }
}
}
}
system Machine {
part ctrl: Ctrl
part panel: Panel
ctrl.st -> panel.bus
panel.cmd -> ctrl.cmd
}Le premier screen est celui où démarre l’interface (initial en désigne un
autre). Un overlay se superpose à tous les écrans. Ce à quoi chaque élément est
lié est vérifié par rapport à ce qu’il affiche, avec son unité et sa plage. Ce
qu’envoie un appui doit atteindre une part qui le reçoit. Chaque écran doit être
accessible et pouvoir être quitté. Un message lié à la sûreté doit être visible
sur chaque écran. Le contenu doit tenir dans l’écran. Le contraste et les
libellés suivent WCAG AA (les codes ui-*). archec ui affiche le modèle
résolu, UiModel dans src/ui.ts.
Mise en page#
Il n’y a qu’une mise en page, et archec fmt l’écrit. Rien n’y est affaire de
choix :
- deux espaces par niveau ; l’accolade
}d’un bloc sur sa propre ligne ; - une propriété ou une déclaration par ligne (
;seulement dans un bloc écrit sur une ligne) ; - les propriétés dans un ordre fixe : ce qu’est l’élément (
description,text), comment il est classé (kind,tags,status…), son type, le reste, ses traces (satisfies,verifies…), sa place sur le canevas (at,size) ; - trois propriétés ou plus d’un même groupe écrites sous forme de groupe ;
- l’orthographe standard de chaque mot-clé (une ancienne orthographe donne un avertissement, et disparaît en 0.12).
archec vet signale ce que fmt ne peut pas corriger : des noms qui ne
respectent pas leur casse, un long bloc Python dans un fichier de modèle, une
déclaration hors de son ensemble.