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
}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, asstd::uint64_t; - enums are
enum class; - unions are
std::variant. A case with no payload isstd::monostate; - optional fields are
std::optional; - arrays are
std::array, orstd::vectorwhen they have no size; - structs and messages are structs. A message that is a value (
message PING : uint32) holds it invalue; - each message with a fixed layout has
kSize,encode(buf)anddecode(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 getsMsg: a messageSTATUSbeside a typeStatusbecomesStatusMsg; - 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::functionmember per port and message:send_<port>, orsend_<port>_<message>when the port sends several. A member that is not set sends nothing. - Its state machine is an
enum class Stateand 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
aftertransition 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:
lateis how late the trigger being handled is. A transition'sdeadlinereads it, and runs itson-deadlineinstead.
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 astd::thread, per thread of the model. It runs its parts'mainand the functions itrunsonce. Then, each period, it runs itsstep, 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)inhooks.cpp. The frame id is the route'sid, 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 corwire). --traceand--monitorsare 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.