1## GPIO models
2
3A model of the GPIO peripherals (both P0 and P1 ports) is included with these models.
4
5You can find information about their limitations and approximations in
6[the source files](../src/HW_models/NRF_GPIO.c).
7
8Note that as of today these models:
9* Consider the output drivers to have 0 impedance: The drive is instantaneous.
10* Do not allow outputs drivers to be in a tristate mode (an output can be disconnected, but not
11 not-driven)
12* Do not allow several outputs to be shortcircuited together to form logical OR's or AND's
13* Do not model input pulls.
14
15That is, inputs just sample the input pin, and outputs just deliver a logical level: high or low.
16
17### Driving inputs:
18
19Inputs can be driven in 3 different ways:
20
21* From an input stimuli file (`-gpio_in_file=<path>`). Which follows the stimuli format
22  described below
23* From test code, calling `nrf_gpio_test_change_pin_level()`
24* By shortcuiting the input and output, either set from a configuration file
25  (`-gpio_conf_file=<path>`, see below), or
26  programmatically, by calling `nrf_gpio_backend_register_short()`
27
28### Output files:
29
30It is possible to have the GPIOs output activity dumped into a file.
31For this just call the excutable with `-gpio_out_file=<path>`.
32Any toggle in any pin configured as an output will be dumped to that file, following the
33stimuli file format described below.
34
35### Monitor inputs/outputs from test code:
36
37Embedded test code specific for simulation can monitor the inputs and outputs changes
38by registering a callback with `nrf_gpio_test_register_in_callback()` and
39`nrf_gpio_test_register_out_callback()`.
40With the first one, the callback will be called each time an *input gpio pin register* is modified.
41With the second one, each time the output pin itself changes. That is, both will be called only
42if the pin is connected/driven in that direction.
43
44### Stimuli file format
45
46This is a comma separated file (.csv), with 4 columns: time,port,pin,level. Where:
47* Time is a 64 bit unsigned value, representing time in microseconds since boot.
48* Port is the GPIO port number starting from 0 (for a nrf52833: 0 or 1).
49* Pin is the pin number in that port (for a nrf52833: 0..31 for port 0, and 0..9 for port 1)
50* Level is either 0 (for low) or 1 (for high)
51
52For example:
53
54```
55time(microsecond),port,pin,level
560,0,0,1
57200,0,0,0
58600,0,0,1
59800,0,0,0
601000,0,0,1
611000,0,0,0
62101624,0,0,1
63```
64
65Where pin 0 in port 0, is toggled at boot, 200microseconds, 600microseconds, 800microseconds, 1ms
66(up and immediately down), and 101.624ms.
67
68### Configuration file format
69
70The configuration file can define output->input short-circuits.
71
72Note that these shorts only work one way: output to input.
73It is not possible to short 2 outputs together.
74It is possible to short one output to several (up to 8) inputs.
75
76The configuration file is made of lines, each with the following format, either:
77
78`short out_port.out_pin in_port.in_pin`<br>
79`s out_port.out_pin in_port.in_pin`
80
81The first word must always be either "short" or "s"
82And it must always be followed by 4 unsigned integers in 2 pairs.
83Each pair separated by a dot. The first value of each pair being the port number,
84the second value the pin in that port.
85The first pair indicating the output pin that will be shorted from, and the 2nd pair
86the input pin that will be shorted to.
87
88For example:
89
90```
91short 0.1 1.2
92short 0.1 1.3
93```
94To short pin 1 from port 0, to both pins 2 and 3 from port 1,<br>
95
96```
97short 1.0 0.2
98```
99to short pin 0 from port 1 to pin 2 from port 2.
100
101Note that both ports and pins are numbered from 0.
102
103### Comments in input files
104
105For both stimuli input and configuration files, '#' is treated as a comment delimiter: That
106character and anything after until the end of the line will be ignored.
107
108Empty lines, are also ignored.
109