Guides pratiques › Générer du C++

Guides pratiques

C++

archec gen --target cpp écrit du C++17 à partir du modèle, pour une cible hébergée : Linux, macOS, ou un RTOS doté d’une bibliothèque standard C++ et de threads. La cible c sert pour un microcontrôleur sans tas. Celle-ci sert pour l’ordinateur qui fait tourner les parts plus lourdes, et elle écrit le C++ comme on l’écrit sur ce genre de machine.

Une première classe#

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
}

system Demo {
  part counter: Counter
}
Diagramme : Demo
Ce qu’archec dessine depuis ce code : Demo
Essayer
archec gen main.arche --target cpp -o generated
  generated/cpp/arche/rt.hpp
  generated/cpp/arche_types.hpp
  generated/cpp/arche_types.cpp
  generated/cpp/counter.hpp
  generated/cpp/counter.cpp
  generated/cpp/CMakeLists.txt

counter.hpp contient une classe avec la variable de la part et son gestionnaire :

class Counter {
public:
    Counter();
    void start();

    // its variables
    std::uint32_t count = 0;
    /** tick's on-receive: after each message on the port. */
    void on_receive_tick();
    …
};

Compilez-la avec CMake :

cmake -S generated/cpp -B build && cmake --build build
[100%] Linking CXX static library libarche_model.a
[100%] Built target arche_model

Sans déploiement, CMake construit une bibliothèque des parts. Avec un déploiement, il construit en plus un exécutable par binaire. Par exemple :

archec gen examples/autonomous-car/main.arche --target cpp -o generated
cmake -S generated/cpp -B build && cmake --build build
ARCHE_RUN_MS=500 ./build/adas

Votre propre framework de composants peut avoir son générateur C++, sous forme de plugin (plugins).

Ce qu’il écrit, dans cpp/#

Fichier Ce que c’est
arche/rt.hpp Ce dont une part a besoin de la plateforme : arche::now_ns() (une horloge monotone), wait_ns et log. Les fonctions put et get en little-endian qu’utilisent les codecs. min, max et clamp, dans le type commun de leurs arguments. arche::Worker, un thread du modèle.
arche_types.hpp/.cpp Les types du modèle, dans namespace model (voir plus bas).
<part>.hpp/.cpp Une classe par composant doté d’un comportement (pas le matériel).
<binary>/main.cpp Avec un déploiement : le programme d’un binaire.
<binary>/hooks.hpp, hooks.cpp Ce qui sort du binaire, et ce qu’appellent vos pilotes. hooks.cpp n’est écrit qu’une fois : il vous appartient.
CMakeLists.txt Une bibliothèque des parts, et un exécutable par binaire. La compilation se fait avec -Wall -Wextra -Werror ; -DARCHE_WERROR=OFF assouplit cette règle.

Les types dans arche_types.hpp :

  • les constantes sont inline constexpr. Les durées sont en ns, en std::uint64_t ;
  • les énumérations sont des enum class ;
  • les unions sont des std::variant. Un cas sans charge utile est un std::monostate ;
  • les champs optionnels sont des std::optional ;
  • les tableaux sont des std::array, ou des std::vector quand ils n’ont pas de taille ;
  • les structures et les messages sont des structs. Un message qui est une valeur (message PING : uint32) la stocke dans value ;
  • chaque message à disposition fixe a kSize, encode(buf) et decode(buf, len). La disposition sur le fil est la même qu’en C, dans le DBC et en Rust : les mêmes octets.

Les noms :

  • un type ou un message est en PascalCase : BRAKE_CMD → BrakeCmd. Un message dont le nom entrerait en conflit avec celui d’un type reçoit Msg : un message STATUS à côté d’un type Status devient StatusMsg ;
  • un champ ou un membre est en snake_case ;
  • une constante, un énumérateur ou un événement est en SCREAMING_SNAKE ;
  • un état garde le nom écrit dans le modèle.

Un composant#

model::Adcu adcu;
adcu.send_can_brake_brake_cmd = [](const model::BrakeCmd &m) { /* to the bus */ };
adcu.start();                                   // watchdogs armed, the initial state entered
model::EngageReq req{true};
adcu.fire(model::Adcu::Event::ENGAGE_REQ, &req);
if (adcu.in(model::Adcu::State::Autonomous)) { … }
  • Ses variables sont des membres publics, avec les valeurs initiales du modèle.
  • Ses fonctions sont des fonctions membres. Un corps ```arche est traduit. Un corps Python est traduit quand il se limite à ce que permet le langage d’action ; c’est le cas de la plupart des corps simples. Sinon, c’est un TODO, avec le Python en dessous.
  • Ce qu’il envoie passe par un membre std::function par port et par message : send_<port>, ou send_<port>_<message> quand le port envoie plusieurs messages. Un membre non renseigné n’envoie rien.
  • Sa machine à états est un enum class State et un switch. C’est l’algorithme du C dans une classe, dans l’ordre que donne la spécification :
    • fire(event, msg) prend la transition que déclenche l’événement, en commençant par l’état le plus interne. Les champs du message sont les noms que lisent ses gardes et ses actions ;
    • go_to(state) exécute les on-exit et les on-enter ;
    • in(state) est vrai dans un état ou dans un état qu’il contient.
  • Les temporisations : chaque transition after et chaque watchdog est une temporisation.
    • next_due() indique quand la prochaine expire ;
    • timeouts() exécute celles qui ont expiré ;
    • kick(WD_X) relance un watchdog ;
    • on_timer, s’il est renseigné, est prévenu chaque fois qu’une temporisation est armée.
  • Les échéances : late indique le retard du déclencheur en cours de traitement. Le deadline d’une transition le lit, et exécute alors son on-deadline à la place.

Un déploiement#

Avec un déploiement, chaque binaire qui indique language cpp reçoit un main.cpp. Si aucun binaire ne l’indique, chaque binaire en reçoit un. Un main.cpp contient :

  • une instance de chaque part qu’exécute le binaire ;
  • un arche::Worker, qui est un std::thread, par thread du modèle. Il exécute une fois le main de ses parts et les fonctions qu’il runs. Ensuite, à chaque période, il exécute son step, les messages que les autres threads lui postent et les temporisations de ses parts quand elles expirent ;
  • chaque lien entre deux parts du binaire. Le thread du destinataire livre le message : sa transition, le on-receive du port, ses gestionnaires ;
  • chaque lien qui sort du binaire. Le message est encodé, puis passé à arche_external_send(link, msg, id, buf, len) dans hooks.cpp. L’identifiant de trame est l’id de la route, comme en C ;
  • un message venu de l’extérieur entre par arche_receive(link, msg, buf, len), que votre pilote appelle.

main tourne jusqu’à SIGINT ou SIGTERM, ou pendant ARCHE_RUN_MS millisecondes.

La priority et la policy d’un thread sont écrites en commentaire à côté de son worker. Si elles comptent, appliquez-les sur native_handle() dans arche_hooks_start(). Sous Linux, cela passe par pthread_setschedparam.

Vérifié#

test/cppgen.test.js :

  • construit examples/autonomous-car avec CMake et -std=c++17 -Wall -Wextra -Werror, puis l’exécute ;
  • compile chaque exemple et les fixtures de difftest avec -Werror ;
  • encode un message avec une énumération, une union, un champ optionnel et un tableau, en C++ et en C, et compare les octets. Il décode aussi les octets produits par le C ;
  • exécute la machine de door.arche en C et en C++, message par message, et compare l’état et les variables après chaque message ;
  • pilote la machine imbriquée d’un rover : gardes, action, on-enter, gestionnaire et watchdog.

Limites#

  • Le bruit d’un capteur, le retard et l’écrêtage d’un actionneur (realism.ts) n’existent qu’en C.
  • Un message qui décrit son format sur le fil bit par bit (at, bits, scale) a sa struct, mais pas de codec C++. Le C l’a (--target c ou wire).
  • --trace et --monitors n’existent qu’en C et en Rust.
  • Les priorités, politiques et cœurs des threads sont des commentaires : ils ne sont pas appliqués.
  • Aucune variante AUTOSAR Adaptive (proxies et skeletons ara::com) n’est générée.