1## UART(E) models
2
3A model of the UART and UART-E peripherals is included with these models.
4
5You can find information about their limitations and approximations in
6[the source files](../src/HW_models/NHW_UART.c).
7
8The UART models are divided in 2 parts:
9* A peripheral model, which emulates both the nRF UART and UART-E.
10* A backend which can send and receive the data somewhere.
11
12When using the peripheral you select which backend is used for each UART instance
13with command line parameters.
14If no backend is enabled, that UART instance is disconnected: whatever is sent is dropped, and
15nothing is received.
16
17### Logging to files
18
19Each UART can be configured to log to a file the Tx and/or Rx bytes.
20Enabling this and selecting the file is done with command line options.
21When enabled, the model will dump one line in this file per byte, with two columns:
22The first column is a timestamp, in microseconds, when the frame *ended*;
23The second column is the byte itself.
24
25### Test API
26
27The UART also has a test API which allows embedded code to register callbacks to be
28called whenever a byte is transmitted or received. This callback can replace the byte before
29the UART peripheral processes it further. Check
30[the UART header file](../src/HW_models/NHW_UART.h) for more info.
31It is also possible for test code to call `nhw_UARTE_digest_Rx_byte()` to inject
32bytes into the UART peripheral like if they arrived through the Rx line.
33
34### Backends:
35
36Today there are 3 backends to choose from:
37 * The loopback backend
38 * The FIFO backend
39 * The PTY backend
40
41#### The Loopback backend
42
43This backend just connects an instance Tx to its Rx, including the RTS and CTS signals.
44While having minimal overhead.
45
46#### The FIFO backend
47
48This backend can connect two instances of these UART models to each other.
49For this it uses one Linux FIFO (named pipe) for Tx and another for Rx.
50In these pipes it will carry both the data, information about the CTS/RTS pin toggles,
51bit rate, frame configuration, and other control messages.
52Therefore you cannot connect this backend to a console, or real devices.
53
54You enable this backend for each instance using command line parameters, by specifying
55the path to each FIFO.
56
57The backend will automatically create and delete the FIFOs on its own.
58
59Remember to use unique paths for each simulation you run in parallel.
60
61The backend will also realize about a possible abrupt disconnect from the other side.
62In that case, it will terminate the simulation.
63In case of a graceful disconnect from the other side, the backend will, by default, also
64terminate the simulation; But you can change this with a command line option, so that it will
65just disconnect the backend and continue running.
66
67For performance reasons, the backend does not react immediately to a CTS/RTS pin toggle from the
68other side. Instead up to 1 frame time (1 byte time) will elapse between the pin toggle
69and the UART peripheral model being notified. Note that the UART peripheral has a 6 byte Rx FIFO,
70and that it toggles RTS while there are still 4 spaces left. So even though this will, in some cases,
71cause up to 1 extra byte to be sent to the other side, it should not cause any transmission losses.
72
73If there is a miss-configuration between the devices (bit rate, parity or number of stop bits),
74the backend will print a warning for each received byte, but the ERRORSRC register in the UART
75peripheral won't be set due to frame, or parity errors, or break conditions.
76
77##### Loopback
78
79It is possible to connect a UART instance Tx directly to its Rx (or to another instance Rx),
80and have the RTR propagated to the CTS.
81To do this, just configure the same FIFO file name for both the Rx and Tx, for example like:
82`-uart0_fifob_rxfile=looped_back -uart0_fifob_txfile=looped_back`
83Note that you can also use the loopback backend when connecting a single instance in loopback,
84and have the same result with lower overhead, and no files created on disk.
85
86**IMPOTANT**:
87  Do not connect both devices which are connected thru the UART FIFO backend to the Physical layer
88  simulation simultaneously. Connect only the one which has the BLE/15.4 controller.
89  Otherwise, with the current implementation the simulation will deadlock with very high
90  likelihood, and if it does not deadlock it will slow down the simulation considerably.
91  You can still provide the sim_id and an unused device number to the other device, but
92  in that case, launch it with the `-nosim` option.
93
94#### The PTY backend
95
96With this backend you can connect a UART to a Linux pseudoterminal. A new pseudoterminal will be
97created for each UART for which this backend is enabled.<br>
98Check the command line options with `-help`.
99Between others you can select if a terminal should be automatically attached to each UART,
100if data should be held while RTS is high, if the simulation should be held until a terminal has been
101attached to the pty, and the Rx data polling period.
102