Guides pratiques › Contrôler le code généré

Guides pratiques

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
  }
}
Diagramme : Demo
Ce qu’archec dessine depuis ce code : Demo
Essayer

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 :

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=1 affiche ce que font les parts, comme le trace archec 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 le timeout du cas (100 ms) ;
  • never: et always:, 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.h recense 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 difftest ne 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 verifies d’un plan ou d’un cas, et les anciennes formes verified-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 un SKIP, avec la raison.
  • Dans les tests C, une attente ne prend aucun temps. Un corps qui boucle sans fin sur ses attentes est en ERROR aprè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.