ovni/doc/dev/events.md

Emulator events

The events processed by the emulator are described in each model. Unrecognized events will cause a panic and stop the emulator in most cases.

The events may have additional arguments in the payload, which are also described. To this end, a simple language was created to specify the format of each event in a concise declaration.

Additionally, a printf-like string is declared for each event, so they can be explained in plain English. The values of the arguments are also substituted in the description of the event following a extended printf format described below.

Event format

The events are defined by a small language that defines the MCV of an event, if is a jumbo and the arguments in the payload (if any).

The grammar of this language is as follows in ABNF.

event-definition = event-mcv event-type [ "(" argument-list ")" ]
event-mcv = VCHAR VCHAR VCHAR
event-type = [ '+' ]
argument-list = argument-type " " argument-name [ ", " argument-list ]
argument-name = 1*(CHAR / DIGIT)
argument-type = type-signed | type-unsigned | type-string
type-signed = "i8" | "i16" | "i32" | "i64"
type-unsigned = "u8" | "u16" | "u32" | "u64"
type-string = "str"

The event-type defines the type of event. Using the symbol + defines the event as jumbo. Otherwise, if not given it is considered a normal event.

Here are some examples:

• OHp: A normal event with OHp MCV and no payload.

• OAs(i32 cpu): A normal event with OAs MCV that has the cpu stored in the payload as a 32 bits signed integer.

• OHC(i32 cpu, u64 tag): A normal event with OHC MCV that has two arguments in the payload: the cpu stored as a 32 bit signed integer, and a tag stored as a 64 bit unsigned integer.

• VYc+(u32 typeid, str label): A jumbo event with VTc MCV that has in the jumbo payload a 32 bits unsigned integer for the typeid followed by the label null-terminated string of variable size.

Event description

To describe the meaning of each event, a description follows the event declaration. This description accepts printf-like format specifiers that are replaced with the value of the argument they refer to.

The formats are specified as follows:

format-specifier = "%" [ printf-format] "{" argument-name "}"
argument-name = 1*(CHAR / DIGIT)

Where the optional printf-format is any string accepted by the format specifier of printf(), as defined in the manual printf(3). If the printf-format is not given, the default format for the argument type is used.

Here are some examples of event descriptions of the previous events:

{ "OHp", "pauses the execution" },
{ "OAs(i32 cpu)", "switches it's own affinity to the CPU %{cpu}" },
{ "OHC(i32 cpu, u64 tag)", "creates a new thread on CPU %{cpu} with tag %#llx{tag}" },
{ "VYc+(u32 typeid, str label)", "creates task type %{typeid} with label \"%{label}\"" },

Which would be printed with ovnidump like:

OHp  pauses the execution
OAs  switches it's own affinity to the CPU 7
OHC  creates a new thread on CPU 3 with tag 0x7f9239c6b6c0
VYc  creates task type 4 with label "block computation"

Model version

When adding new events of changing the format of already existing events, the version of the model that defines the event must be changed accordingly to the rules of Semantic Versions.

In general, adding new events will cause a minor increase in the version, while changing events will cause a major increase. Notice that the emulator will reject a stream which contains events from a model which is not compatible with the current model version.