How-to guides › Generate C++

How-to guides

C++

archec gen --target cpp writes C++17 from the model, for a hosted target: Linux, macOS, or an RTOS with a C++ standard library and threads. The c target is the one for a microcontroller with no heap. This one is for the computer that runs the bigger parts, and it is written the way C++ is written there.

A first class#

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
}
Diagram: Demo
What archec draws from this code: Demo
Try it
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 has a class with the part's variable and its handler:

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();
    …
};

Build it with CMake:

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

With no deployment, CMake builds a library of the parts. With a deployment, it also builds an executable per binary. For example:

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

A component framework of your own can have its own C++ generator, as a plugin (plugins).

What it writes, in cpp/#

File What it is
arche/rt.hpp What a part needs from the platform: arche::now_ns() (a steady clock), wait_ns and log. The little-endian put and get the codecs use. min, max and clamp, in the common type of their arguments. arche::Worker, a thread of the model.
arche_types.hpp/.cpp The model's types, in namespace model (see below).
<part>.hpp/.cpp A class per component that behaves (not the hardware).
<binary>/main.cpp With a deployment: the program of a binary.
<binary>/hooks.hpp, hooks.cpp What leaves the binary, and what your drivers call. hooks.cpp is written once: it is yours.
CMakeLists.txt A library of the parts, and an executable per binary. It builds with -Wall -Wextra -Werror; -DARCHE_WERROR=OFF relaxes this.

The types in arche_types.hpp:

  • constants are inline constexpr. Durations are in ns, as std::uint64_t;
  • enums are enum class;
  • unions are std::variant. A case with no payload is std::monostate;
  • optional fields are std::optional;
  • arrays are std::array, or std::vector when they have no size;
  • structs and messages are structs. A message that is a value (message PING : uint32) holds it in value;
  • each message with a fixed layout has kSize, encode(buf) and decode(buf, len). The wire layout is the same as the C, the DBC and the Rust: the same bytes.

Names:

  • a type or a message is PascalCase: BRAKE_CMD → BrakeCmd. A message whose name would clash with a type's gets Msg: a message STATUS beside a type Status becomes StatusMsg;
  • a field or a member is snake_case;
  • a constant, an enumerator or an event is SCREAMING_SNAKE;
  • a state is as written.

A component#

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)) { … }
  • Its variables are public members, with the model's initial values.
  • Its functions are member functions. A ```arche body is translated. A Python body is translated when it says what the action language says; most simple ones do. Otherwise it is a TODO, with the Python under it.
  • What it sends is a std::function member per port and message: send_<port>, or send_<port>_<message> when the port sends several. A member that is not set sends nothing.
  • Its state machine is an enum class State and a switch. It is the C's algorithm in a class, in the order the specification gives:
    • fire(event, msg) takes the transition the event triggers, innermost state first. The message's fields are the names its guards and actions read;
    • go_to(state) runs the on-exits and on-enters;
    • in(state) is true in a state or in a state inside it.
  • Timers: each after transition and each watchdog is a timer.
    • next_due() says when the next one runs out;
    • timeouts() runs those that did;
    • kick(WD_X) restarts a watchdog;
    • on_timer, when set, is told each time a timer is armed.
  • Deadlines: late is how late the trigger being handled is. A transition's deadline reads it, and runs its on-deadline instead.

A deployment#

With a deployment, each binary that says language cpp gets a main.cpp. When no binary says it, each binary gets one. A main.cpp has:

  • an instance of each part the binary runs;
  • an arche::Worker, which is a std::thread, per thread of the model. It runs its parts' main and the functions it runs once. Then, each period, it runs its step, the messages other threads post to it, and its parts' timers when they run out;
  • each link between two parts of the binary. The receiver's thread delivers the message: its transition, the port's on-receive, its handlers;
  • each link out of the binary. The message is encoded, then passed to arche_external_send(link, msg, id, buf, len) in hooks.cpp. The frame id is the route's id, as in the C;
  • a message from outside comes in through arche_receive(link, msg, buf, len), which your driver calls.

main runs until SIGINT or SIGTERM, or for ARCHE_RUN_MS milliseconds.

A thread's priority and policy are written as a comment beside its worker. If they matter, set them on native_handle() in arche_hooks_start(). On Linux, that is pthread_setschedparam.

Verified#

test/cppgen.test.js:

  • builds examples/autonomous-car with CMake and -std=c++17 -Wall -Wextra -Werror, and runs it;
  • compiles every example and the difftest fixtures with -Werror;
  • encodes a message with an enum, a union, an optional field and an array, in C++ and in C, and compares the bytes. It also decodes the C's bytes;
  • runs door.arche's machine in C and in C++, message by message, and compares the state and the variables after each message;
  • drives a rover's nested machine, guards, action, on-enter, handler and watchdog.

Limits#

  • A sensor's noise and an actuator's lag and clamping (realism.ts) are in the C only.
  • A message that gives its wire format bit by bit (at, bits, scale) has its struct but no C++ codec. The C has it (--target c or wire).
  • --trace and --monitors are C and Rust only.
  • Thread priorities, policies and cores are comments: they are not applied.
  • An AUTOSAR Adaptive flavour (ara::com proxies and skeletons) is not written.