2022-03-09 11:14:54 +01:00
|
|
|
# fsm
|
|
|
|
|
|
|
|
This module implements a Finite State Machine (FSM).
|
|
|
|
The FSM is composed of states and transitions between them.
|
|
|
|
These need to be specified by the client.
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
Have a look at `fsm_test.v` for usage examples.
|
|
|
|
|
|
|
|
On each `run()`, all the possible transitions from the current state are evaluated.
|
|
|
|
The first transition for the current state, whose condition evaluates to true is
|
|
|
|
taken (the condition is specified by a transition callback function).
|
|
|
|
|
|
|
|
In a successfull transition, the current state changes to the new one.
|
|
|
|
When that happens:
|
|
|
|
* the client-specified `on_exit()` handler from the current state is called.
|
|
|
|
* the client-specified `on_entry()` handler of the new state is called.
|
|
|
|
|
|
|
|
After all transitions are checked, and thus the state is changed, the client-specified
|
|
|
|
`on_run()` handler of the now current state is called.
|
2022-03-13 10:40:03 +01:00
|
|
|
|
|
|
|
## Plot States and Transitions
|
|
|
|
This module includes a tool for generating dot diagrams from .v source code,
|
|
|
|
that defines a FSM. The tool is located in [fsm_graph.v](tools/fsm_graph.v).
|
|
|
|
|
|
|
|
Here is an example of how to generate a .dot file with the graph and transitions:
|
|
|
|
```bash
|
|
|
|
v run vlib/datatypes/fsm/tools/fsm_graph.v -f vlib/datatypes/fsm/fsm_test.v > graph.dot
|
|
|
|
```
|
|
|
|
|
|
|
|
You can convert the generated .dot file to a PNG file with Graphviz's `dot`
|
|
|
|
conversion tool:
|
|
|
|
```bash
|
|
|
|
v run vlib/datatypes/fsm/tools/fsm_graph.v -f vlib/datatypes/fsm/fsm_test.v > graph.dot
|
|
|
|
dot -Tpng graph.dot > graph.png
|
|
|
|
xdg-open graph.png
|
|
|
|
```
|
|
|
|
|
|
|
|
You can also visualise it with Graphviz (the `dot` command)
|
|
|
|
& ImageMagick (the `display` command):
|
|
|
|
```bash
|
|
|
|
v run vlib/datatypes/fsm/tools/fsm_graph.v -f vlib/datatypes/fsm/fsm_test.v | dot -Tpng | display
|
|
|
|
```
|
|
|
|
|
|
|
|
To view the .dot file, you can also use any of the
|
|
|
|
[Graphviz Graphical Interfaces](https://graphviz.org/resources/#graphical-interfaces)
|
|
|
|
and `xdot` in particular:
|
|
|
|
```bash
|
|
|
|
v run vlib/datatypes/fsm/tools/fsm_graph.v -f vlib/datatypes/fsm/fsm_test.v | xdot -
|
|
|
|
```
|
|
|
|
|
|
|
|
In all of the above examples, you can replace `vlib/datatypes/fsm/fsm_test.v`
|
|
|
|
with the path to your own .v code that imports and uses `fsm`.
|