Describe event declaration language

doc/dev/events.md

@@ -0,0 +1,101 @@
+# 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.

mkdocs.yml

@@ -4,6 +4,9 @@ extra_css: [extra.css]
 theme:
   name: readthedocs
   sticky_navigation: false
+  highlightjs: true
+  hljs_languages:
+    - abnf
 extra_javascript: 
     - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML
 markdown_extensions:
@@ -38,6 +41,7 @@ nav:
     - CHANGELOG.md
   - 'Developer guide':
     - dev/index.md
+    - dev/events.md
     - dev/channels.md
     - dev/patchbay.md
     - dev/mux.md