1## GPIO models
2
3A model of the GPIO peripherals 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### Mapping of real ports to simulated port indexes
45
46* 52822
47    * P0: 0
48    * P1: 1
49* 5340 NOTE: The Net and App cores ports are mapped to different/separate simulated ports/pins,
50  unlike in real HW where they are connected to the same physical pins. Note that from the embedded
51  SW point of view (that is, when configuring an App core GPIOTE channel), the App core port P0 is
52  port "0" just like when configuring it in real HW).
53    * Net core P0: 0
54    * Net core P1: 1
55    * App core P0: 2
56    * App core P1: 3
57* 54L15
58    * P0 (LP domain): 0
59    * P1 (Per domain): 1
60    * P2 (MCU domain): 2
61
62### Stimuli file format
63
64This is a comma separated file (.csv), with 4 columns: time,port,pin,level. Where:
65* Time is a 64 bit unsigned value, representing time in microseconds since boot.
66* Port is the GPIO port number starting from 0 (for a nrf52833: 0 or 1).
67* Pin is the pin number in that port (for a nrf52833: 0..31 for port 0, and 0..9 for port 1)
68* Level is either 0 (for low) or 1 (for high)
69
70For example:
71
72```
73time(microsecond),port,pin,level
740,0,0,1
75200,0,0,0
76600,0,0,1
77800,0,0,0
781000,0,0,1
791000,0,0,0
80101624,0,0,1
81```
82
83Where pin 0 in port 0, is toggled at boot, 200microseconds, 600microseconds, 800microseconds, 1ms
84(up and immediately down), and 101.624ms.
85
86### Configuration file format
87
88The configuration file can define output->input short-circuits.
89
90Note that these shorts only work one way: output to input.
91It is not possible to short 2 outputs together.
92It is possible to short one output to several (up to 8) inputs.
93
94The configuration file is made of lines, each with the following format, either:
95
96`short out_port.out_pin in_port.in_pin`<br>
97`s out_port.out_pin in_port.in_pin`
98
99The first word must always be either "short" or "s"
100And it must always be followed by 4 unsigned integers in 2 pairs.
101Each pair separated by a dot. The first value of each pair being the port number,
102the second value the pin in that port.
103The first pair indicating the output pin that will be shorted from, and the 2nd pair
104the input pin that will be shorted to.
105
106For example:
107
108```
109short 0.1 1.2
110short 0.1 1.3
111```
112To short pin 1 from port 0, to both pins 2 and 3 from port 1,<br>
113
114```
115short 1.0 0.2
116```
117to short pin 0 from port 1 to pin 2 from port 2.
118
119Note that both ports and pins are numbered from 0.
120
121### Comments in input files
122
123For both stimuli input and configuration files, '#' is treated as a comment delimiter: That
124character and anything after until the end of the line will be ignored.
125
126Empty lines, are also ignored.
127