La qualité du code généré
archec gen écrit du code qui doit compiler sans avertissement. Un relecteur
doit pouvoir le relier au modèle, et les plans de test du modèle doivent
pouvoir le tester. Cette page montre comment vérifier chacun de ces points, à
partir du modèle.
Une première vérification#
Une part qui compte les ticks, une exigence, et un plan de test qui la vérifie :
message TICK "A tick" { n: uint32 }
component Counter "Counts the ticks" {
in tick: data receives TICK {
on-receive ```arche
count += 1
```
}
var count: uint32 = 0
satisfies REQ-COUNT
}
system Demo {
part counter: Counter
}
requirement REQ-COUNT "Count each tick" {
text "The counter shall add one for each TICK it receives."
}
test-plan TP-COUNT "Counting" {
case TC-COUNT-01 "Two ticks count two" {
verifies REQ-COUNT
at 0ms do send(counter.tick, TICK(1))
at 1ms do send(counter.tick, TICK(2))
within 5ms expect counter.count == 2
}
}Compilez le C et passez-le aux linters :
archec gen main.arche --target c -o generated --build --lint
── cc -std=c99 -Wall -Wextra -Werror -pedantic -O2
note: cppcheck: the MISRA C:2012 check (its misra addon) is not run — install cppcheck 2.x
note: clang-tidy: not run — install it (LLVM) for its checks
✓ built clean, 0 finding(s) from the linters
Exécutez le plan de test sur le C généré :
archec gen main.arche --target c-tests -o generated --run
── make -C generated/c-tests test
PASS TP-COUNT/TC-COUNT-01 Two ticks count two
arche-tests: 1 passed, 0 failed, 0 skipped
results: generated/c-tests/results.json
Écrivez ensuite la matrice de traçabilité :
archec gen main.arche --target trace-matrix -o generated
generated/trace-matrix/matrix.md a une ligne par exigence :
| Exigence | Élément du modèle | Code généré | Cas de test | Dernier résultat |
|---|---|---|---|---|
| REQ-COUNT Count each tick | component Counter (main.arche:3) | c/counter.c:9 counter_init |
TP-COUNT/TC-COUNT-01 | pass (C) |
Les sections suivantes détaillent chaque vérification :
- Compiler et linter :
archec gen --build --lint. Chaque constat est affiché sur l’élément du modèle dont il provient. - Des tests unitaires C tirés des plans de
test :
archec gen --target c-tests,make test, et la couverture des états et des transitions. - Le code défensif :
--defensive. Plages, entrées périmées et contrôles de bout en bout (CRC, compteur) à la réception. - La matrice de traçabilité :
archec gen --target trace-matrix. Exigence → élément → fonction générée → cas de test → résultat.
archec lance d’autres outils : cppcheck, clang-tidy, cargo clippy, gcov. Quand
l’un d’eux n’est pas installé, la commande le dit, et ce qu’il aurait vérifié
est laissé de côté. Rien n’est jamais simulé. test/codegen-quality.test.js
lance pour de vrai les outils installés.
Compiler et linter#
archec gen main.arche --target c -o generated --build # build it
archec gen main.arche --target c -o generated --build --lint # and lint it
archec gen main.arche --target embassy -o generated --lint --sarif gen.sarif
--build compile ce qui vient d’être écrit. --lint lance en plus les
linters :
| Cible | Compilation | Ce qu’ajoute --lint |
|---|---|---|
c |
le Makefile de chaque binaire (make -B). Sans déploiement, chaque module séparément (-fsyntax-only). Les options sont -std=c99 -Wall -Wextra -Werror -pedantic. |
cppcheck avec son addon MISRA C:2012 (--addon=misra). clang-tidy, avec bugprone, cert, clang-analyzer et performance ; si le dossier de sortie contient un .clang-tidy, c’est le vôtre qui est utilisé. |
embassy |
cargo build dans chaque crate |
cargo clippy à la place de la compilation |
Le C généré est censé compiler sans avertissement. Avec -Werror, un
avertissement est donc une erreur de compilation. La commande sort avec 1 quand
la compilation échoue, et 0 sinon. Un constat de linter ne la fait pas échouer
à lui seul : lisez les constats, ou bloquez sur le SARIF en CI.
Chaque constat est affiché sur l’élément du modèle dont vient la ligne générée. Suit l’endroit où il se trouve dans le code généré :
main.arche:57 error [cc-unused-variable] unused variable 'x' — c/controller_ports.c:6 in controller_send_cmd (port cmd of Controller)
components.arche:172 warning [clippy-blocks_in_conditions] … — embassy/brake_fw/src/app.rs:26 in main (fn main of brakes)
components.arche:118 warning [misra-10.4] … — c/adcu.c:61 in adcu_fire_with (transition Manual -> Ready on self_test_ok of Adcu)
La règle entre crochets est :
cc-<warning>pour le compilateur ;misra-<rule>pour une règle MISRA C:2012 ;cppcheck-<id>pour les autres vérifications de cppcheck ;- le nom de la vérification clang-tidy ;
clippy-<lint>pour clippy.
L’élément est retrouvé grâce aux noms que donnent les générateurs et aux commentaires qu’ils écrivent :
| Généré | Élément du modèle |
|---|---|
<part>_init, toute autre ligne de c/<part>.c |
le composant |
<part>_<fn> |
sa fonction |
<part>_on_receive_<port>, _on_deadline_, _command_, _output_, _send_ |
le port |
<part>_fire_with, _timeout, sous /* transition A -> B on M */ |
cette transition |
<part>_enter, _exit, sous case <PART>_<STATE>: |
cet état |
<msg>_encode, _decode dans c/arche_types.c |
le message |
thread_<id>, une fonction d’envoi dans c/<binary>/wiring.c |
le thread, le port |
fn x dans embassy/<binary>/src/app.rs, après /// <part path> |
la fonction (ou le port) de cette part |
Une ligne qui ne correspond à rien, comme un fichier du runtime ou main.c,
n’est affichée qu’avec son fichier et sa ligne dans le code généré.
--sarif <file> écrit les constats en SARIF 2.1.0, comme le fait archec check --sarif :
- chaque constat est placé sur le fichier et la ligne de l’élément du modèle :
le code scanning l’affiche donc sur le fichier
.arche; - son message indique l’endroit dans le code généré ;
- il y a une règle par code.
Des tests unitaires C tirés des plans de test#
archec gen main.arche --target c-tests -o generated # write them
make -C generated/c-tests test # build and run them
archec gen main.arche --target c-tests -o generated --run # both
archec gen main.arche --target c-tests -o generated --coverage # and gcov's coverage
--target c-tests écrit, sous c-tests/ :
- le C de chaque composant, tel que l’écrit
--target c; arche_tests.c;- un
Makefile.
arche_tests.c est le harnais : le programme avec lequel archec difftest
pilote le C généré. Il fait tourner les parts du système sur une horloge
virtuelle. Chaque message suit ses liens, avec leur latence. Chaque part fait
une seule chose à la fois, dans l’ordre que donne la
spécification. Le harnais contient aussi une fonction par
cas de test.
Il n’y a pas de framework de test : le harnais est lui-même le lanceur de
tests. make test sort avec 1 quand un cas échoue.
make test CASES="TC-1 TP-2"lance certains cas, par identifiant ou par plan.ARCHE_TRACE=1affiche ce que font les parts, comme le tracearchec difftest.
Un cas s’exécute comme le fait le lanceur de tests d’Arche. Il part d’un état
neuf. Chaque étape s’exécute à son at : son do, son wait, puis ses
attentes. Une attente est l’une des formes suivantes :
- une expression, vérifiée une fois l’étape stabilisée ;
within 40ms:, vraie au plus tard 40 ms après le début de l’étape ;at d:;eventually:, dans letimeoutdu cas (100 ms) ;never:etalways:, surveillées après chaque événement jusqu’à la fin du cas. Un cas se termine 10 ms après sa dernière étape.
Ce qu’un cas exprime en Python est traduit là où le C peut l’exprimer :
| Dans le cas | En C |
|---|---|
send(ctrl.engage, ENGAGE(True)) — un port qui reçoit |
la part le traite tout de suite, comme un message venu de l’extérieur |
send(hmi.bus, ENGAGE_REQ(True)) — un port qui envoie |
envoyé le long des liens du port |
MSG(points=1000, nearest=30.0), MSG(1000, 30.0) |
les champs du message, par nom ou dans l’ordre |
adcu.speed = 20.0, +=, -= |
la variable de la part |
brakes.state == "Braking" |
la part est dans Braking (ou dans un état qu’il contient) |
sent("BRAKE_CMD") >= 1 |
les envois de ce message depuis le début du cas |
nombres, constantes, True/False, and/or/not, comparaisons, arithmétique |
la même chose |
Un cas qui contient autre chose est généré en SKIP, avec ce que le C n’a pas
pu exprimer. Par exemple print, received(…), une panne, une keyframe ou un
test de fonction. Rien n’est deviné. La sortie a la forme que archec test lit
depuis Arche :
PASS TP-BRK/TC-BRK-01 Brakes when fast
FAIL TP-BRK/TC-BRK-03 A wrong expectation
ctrl.state == "Braking" — false at 1.000 ms (main.arche:111)
SKIP TP-BRK/TC-BRK-04 Python the C tests cannot say — do print("hello") (main.arche:114)
arche-tests: 2 passed, 1 failed, 1 skipped
--run les compile, les exécute et affiche ce résultat. Il écrit aussi
c-tests/results.json, comme archec test écrit .archec/test-results.json.
Ce fichier contient les verdicts par PLAN/CASE, et ce qu’ils disent des
exigences que les cas vérifient. La matrice de traçabilité le lit.
Un corps qui attend (await wait(…)) s’exécute dans le harnais, mais son
attente ne prend aucun temps. Un corps qui boucle sans fin sur ses attentes
(while True: await wait(WATCHDOG)) dépasse 100000 événements. Son cas est
alors en ERROR, et le cas suivant s’exécute quand même. C’est ce que fait
aujourd’hui la boucle de watchdog de la voiture autonome. En C, il lui faudrait
un thread, et le harnais n’en donne pas aux corps.
Couverture#
Avec gcov (--coverage, ou make coverage), chaque module est compilé avec
--coverage. Les lignes exécutées sont ensuite relues comme des éléments du
modèle :
| gcov compte | couvert dans le modèle |
|---|---|
la ligne qui suit /* transition A -> B on M */ |
cette transition a été franchie |
case <PART>_<STATE>: exécuté dans <part>_enter, l’état initial à l’init, ou la cible d’une transition franchie |
on est entré dans cet état |
une ligne de <part>_<fn> |
cette fonction s’est exécutée |
Le résultat est présenté comme archec test --coverage présente la couverture
d’Arche. Il est aussi écrit dans c-tests/coverage.json :
Coverage (the generated C (gcov)):
states 5/5 100 %
transitions 3/4 75 %
not covered: brakes: Braking -> Released on after 100ms
functions 0/1 0 %
not covered: sensor.scan
Une part qui n’a qu’une instance est désignée par son chemin (brakes). Un
module que se partagent plusieurs instances est désigné par son composant
(Brakes).
Le code défensif#
archec gen main.arche --target c --defensive -o generated
--defensive ajoute des contrôles au C. Ils vérifient ce que le modèle dit
qu’un message peut contenir, là où le message arrive :
| Le modèle indique | Ce que fait le C à la réception |
|---|---|
la range d’un champ (ou de son type), ou celle d’un message valeur |
<msg>_in_range() dans arche_types.c. Un message dont une valeur sort de sa plage est rejeté, pas écrêté. Il est compté dans arche_errors.range. |
le stale-after d’un port, sinon la period du message |
Une entrée qui n’est pas arrivée depuis ce délai est marquée périmée. Pour une période, le délai est la période × 1,5, la tolérance que lui accorde archec replay. <binary>_input_stale(<BINARY>_IN_k) dit si elle est périmée en ce moment. arche_errors.stale compte chaque passage à l’état périmé. |
un format de trame avec un checksum |
Une trame dont la somme de contrôle est fausse ne se décode pas. Elle est comptée dans arche_errors.crc. |
un format de trame avec un counter |
Dans l’esprit d’AUTOSAR E2E. Un compteur qui n’a pas bougé signale un doublon : le message est rejeté (arche_errors.repeat). Un compteur qui a sauté signale des messages perdus : le message est gardé, et la perte est comptée (arche_errors.jump) et journalisée. |
Pourquoi rejeter plutôt qu’écrêter ? Une valeur hors plage révèle un défaut en amont : un capteur, un bus, un bug chez l’émetteur. Une valeur écrêtée masque ce défaut derrière une valeur plausible. Un message rejeté n’atteint jamais la part, qui continue d’agir sur le dernier message valide. Le drapeau « périmé » signale quand cette situation dure trop longtemps.
Avec un déploiement, le wiring.c de chaque binaire :
- vérifie chaque message qu’il distribue à une part
(
arche_accept_<link>_<msg>).wiring.hrecense ses entrées ; - cherche les entrées périmées à chaque période d’un thread périodique, et à chaque message ;
- journalise chaque rejet une seule fois, jusqu’à ce que l’entrée soit de nouveau acceptée. Un capteur bloqué n’inonde donc pas le journal.
Sans déploiement, <msg>_in_range() et arche_errors sont à disposition de
votre code de réception.
Un thread qui attend des messages et n’a pas de période ne voit une entrée
devenir périmée qu’à son message suivant, ou quand on le lui demande
(<binary>_input_stale).
Les contrôles sont à activer explicitement, et ne sont pas actifs par défaut, pour deux raisons :
- Ils changent ce que voient les parts : un message rejeté ne les atteint
jamais.
archec difftestne comparerait donc plus des choses comparables avec le simulateur, qui ne vérifie rien de tout cela. - Chaque entrée contrôlée coûte quelques octets de RAM et quelques comparaisons. Sur une petite cible, ce coût doit être un choix.
La matrice de traçabilité#
archec test main.arche # Arche's simulator: arche-out/.archec/test-results.json
archec gen main.arche --target c-tests -o generated --run # the C: generated/c-tests/results.json
archec gen main.arche --target trace-matrix -o generated # generated/trace-matrix/matrix.md, .csv
Pour chaque exigence, la matrice donne :
- les éléments du modèle qui la satisfont :
satisfies(et les anciennes formes, lues jusqu’à 0.13 :satisfied-by,trace satisfies) ; - le C généré pour chacun : le fichier, la ligne et la fonction de
--target c, relus comme dans compiler et linter ; - les cas de test qui la vérifient : le
verifiesd’un plan ou d’un cas, et les anciennes formesverified-by,trace verifies,verify { tests … }; - ce qu’a donné la dernière exécution de chaque cas.
| Exigence | Élément du modèle | Code généré | Cas de test | Dernier résultat |
|---|---|---|---|---|
| REQ-BRAKE Brake when fast | component Controller (main.arche:54) | c/controller.c:9 controller_init |
TP-BRK/TC-BRK-01 TP-BRK/TC-BRK-03 |
pass (C), pass (sim) fail (C) |
| REQ-SCAN Report the speed | fn scan (main.arche:46) | c/sensor.c:11 sensor_scan |
— | — |
Comment chaque élément apparaît dans la colonne « Code généré » :
- un composant, par l’endroit où commence son module (son
init) ; - une fonction, un état, une transition ou un port tracé vers une exigence, par sa propre fonction générée ;
- une part, par la sienne et par celle de son composant.
Les résultats viennent de --results <file> : chacun est un JSON de
résultats, et l’option peut être répétée. Sans elle, ce sont les résultats
trouvés qui servent : arche-out/.archec/test-results.json (sim) et
<out>/c-tests/results.json (C). Un cas absent des deux est not run.
Sous le tableau viennent les lacunes. Une lacune est une exigence :
- qu’aucun élément ne satisfait ;
- dont les éléments n’ont pas de C généré ;
- qu’aucun cas ne vérifie ;
- dont un cas a échoué ;
- dont les cas n’ont pas été exécutés.
matrix.csv a une ligne par exigence, élément et cas
(requirement,title,element,element_at,generated,test_case,result). Il est
destiné à un tableur ou à un outil de certification.
Limites#
- Un linter ou gcov qui n’est pas installé n’est pas lancé. Ce qu’il aurait vérifié est laissé de côté, et la commande le dit.
- Un cas de test qui contient quelque chose que le C ne sait pas exprimer
(
print,received(…), une panne, une keyframe, un test de fonction) est unSKIP, avec la raison. - Dans les tests C, une attente ne prend aucun temps. Un corps qui boucle sans
fin sur ses attentes est en
ERRORaprès 100000 événements : en C, il lui faudrait un thread, et le harnais n’en donne pas aux corps. - Les contrôles défensifs n’existent qu’en C : les crates Embassy ne les ont pas encore.