Référence › Référence du langage › Data

Référence › Référence du langage

Cette page n’est pas encore traduite : voici la version anglaise.

Data

The types, constants and messages a model uses.

On this page: type · enum · struct · field · const · message

Types, constants and the message catalog.

type#

A named data type (data-types.yaml) — a built-in read in a unit, with an optional range. type Iq native { … } is a type the code provides: its name in each language and the header (C, C++), or the module (Go), that declares it — the generated code uses it as it is.

  • Keywords: type
  • Set: the model
  • Where: top level
  • Syntax: type Id = base [unit u] [range lo..hi] | type Id native { c "name" include "h.h"; cpp "ns::Name" include "h.h"; rust "crate::Name"; go "pkg.Name" import "path" }
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
unit string Physical unit, written as it is (unit km/h, unit m/s², unit °C); one with a space is quoted.
range range Allowed range lo..hi.
bits number How many bits a value of the type takes in an FPGA component (the fpga extension): type Adc12 = uint16 { bits 12 } is a 12-bit signal or register. Without it an integer type has its own width (uint8: 8).
native bool The type is the code's: written in the header, type Iq native { … }.
cpp string A native type's name in C++, and its header: cpp "dsp::Iq" include "dsp/iq.h".
c string A native type's name in C, and the header that declares it: c "iq_t" include "dsp/iq.h".
rust string A native type's path in Rust: rust "dsp::Iq".
go string A native type's name in Go, and the package to import: go "dsp.Iq" import "example.com/dsp".
type Speed = float32 unit km/h range 0..250

type Iq native "IQ sample" {
  cpp "dsp::Iq" include "dsp/iq.h"
  rust "dsp::Iq"
}

enum#

An enumeration (data-types.yaml). Literals in order; = n when the encoding is not the position.

  • Keywords: enum
  • Set: the model
  • Where: top level
  • Syntax: enum Id { A, B = 4, C }
Property Value Meaning
literal-form object | name literal-form object: every literal is written {name: …} in Arche, even with no value (default: a bare name when it has none).
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
enum DriveMode { MANUAL, ASSISTED, AUTONOMOUS = 4 }

struct#

A structure (data-types.yaml). Fields are name: Type, optionally with unit, range, default; optional T is a field that may be absent (multiplicity 0..1). union Command { stop; move: MoveArgs; speed: float32 } holds one of its cases: a bare name has no payload, name: Type carries one. Arche gets a struct with a case field (the enum CommandCase) and one optional field per payload; archec gen embassy writes a Rust enum. exception NotFound { id: uint32 } is a struct an operation raises (IDL's exception): what it carries is its fields.

  • Keywords: struct · union · exception (old spelling: record)
  • Set: the model
  • Where: top level
  • Syntax: struct Id [extends Base] { name: [optional] Type [= default] [unit u] } | union Id { case; case: Type } | exception Id { name: Type }
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
extends type name Base structure whose fields come first.
abstract bool Only ever specialised.
struct ImuSample {
  ts: uint64 unit ns
  accel: float32[3] unit m/s²
  gyro: float32[3] unit rad/s
}

field#

A field of a struct, message or memory record. The field keyword is optional: name: Type. = value is its default: a message built without the field (BRAKE_CMD(force=1.0)) carries it, and a struct field with no default of its own is built from its fields' defaults — so header: Header needs writing only when it differs.

  • Keywords: field
  • Set: the model
  • Where: inside struct, inside message, inside memory, inside field, inside icd
  • Syntax: name: Type [= default] ["Label"] [unit u] [range lo..hi] [bits "7:0"] — in a message: [at n] [bits n] [scale x] [offset x] [signed] [checksum crc8] [counter]
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
unit string Physical unit, written as it is (unit km/h, unit m/s², unit °C); one with a space is quoted.
range range Allowed range.
bits any In a memory record, the bitfield ("7:0"). In a message, how many bits the field takes on the wire (bits 12): the message then has a wire format.
at number The bit of the frame a message field starts at (wire format): its least significant bit little-endian, its most significant big-endian, as a DBC start bit counts. Default: right after the field before.
scale number A message field sent as a whole number: raw = round((value - offset) / scale), value = raw × scale + offset (wire format, DBC factor).
offset number What raw 0 stands for, with scale (wire format, DBC offset).
signed bool The raw value on the wire is two's complement (default: when the field's type is signed).
byte-order little | big This field's byte order on the wire, when not the message's: little (Intel) or big (Motorola).
checksum crc8 | xor8 An 8-bit checksum of the frame's other bytes, written by encode and checked by decode: crc8 (SAE J1850) or xor8.
counter bool A rolling counter: the generated C wiring counts it up at each send, wrapping at its bits.
size number Size in bytes: of a memory record's field, or of a message field on the wire (size 0: it travels out of band, as a chip-select line does, and costs no transfer time).
multiplicity any 1 (default), 0..1, 0..*, 1..4.
aggregation composition | aggregation | association composition | aggregation | association.
enable: uint8 bits "0:0"

const#

A project constant (variables.yaml): readable by name from every piece of behaviour code. Durations become ns.

  • Keywords: const (old spelling: constant)
  • Set: the model
  • Where: top level
  • Syntax: const NAME [: Type] = value [unit u]
Property Value Meaning
tbc bool To be confirmed: the value is not final.
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
unit string Unit shown beside the value.
range range Tunable: the values a tuner may give it, range lo..hi (archec fit --pass, the MCP params_set; see docs/tuning.md).
const MAX_SPEED = 130 unit km/h
const WATCHDOG = 50ms
const KP = 30.0 { range 5..80 }

message#

A message of the project catalog (messages.yaml): a scalar payload (: float32), a struct (: ImuSample) or inline fields. A message with fields may say its exact wire format, as a CAN DBC does: byte-order and size on it, at, bits, scale, offset, signed, checksum, counter on its fields. The DBC, the ICD and the C, Rust, Go and Python codecs (archec gen --target wire) then put each field on its bits.

  • Keywords: message (old spelling: msg)
  • Set: the model
  • Where: top level
  • Syntax: message ID ["Name"] [: Type] { field: Type … }
Property Value Meaning
description text Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX.
color color name A palette color id, or a literal "#rrggbb".
unit string Unit of a scalar payload.
period duration Nominal emission period.
byte-order little | big Gives the message a wire format (bit-exact, as a DBC says it): its fields' byte order, little (Intel, the default) or big (Motorola). See at, bits, scale on its fields.
size number Gives the message a wire format: the frame's length in bytes (default: as many as its fields reach). The bits no field takes are zeros.
kind metric kind metric: a metric — a value an algorithm publishes about its processing (a level, a count), read by others through pub-sub topics (topic "/chain/*/snr"). A package of metrics is a metric package.
message BRAKE_CMD "Brake command" {
  force: float32 unit N
  emergency: bool
}