102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
# 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][abnf].
|
|
|
|
[abnf]: https://en.wikipedia.org/wiki/Augmented_Backus%E2%80%93Naur_form
|
|
|
|
```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:
|
|
|
|
```ABNF
|
|
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:
|
|
|
|
```c
|
|
{ "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:
|
|
|
|
```nohighlight
|
|
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](https://semver.org).
|
|
|
|
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.
|