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 thru the Rx line.
33
34### Backends:
35
36Today there are 2 backends to choose from:
37 * The loopback backend
38 * The FIFO backend
39
40#### The Loopback backend
41
42This backend just connects an instance Tx to its Rx, including the RTS and CTS signals.
43While having minimal overhead.
44
45#### The FIFO backend
46
47This backend can connect two instances of these UART models to each other.
48For this it uses one Linux FIFO (named pipe) for Tx and another for Rx.
49In these pipes it will carry both the data, information about the CTS/RTS pin toggles,
50bit rate, frame configuration, and other control messages.
51Therefore you cannot connect this backend to a console, or real devices.
52
53You enable this backend for each instance using command line parameters, by specifying
54the path to each FIFO.
55
56The backend will automatically create and delete the FIFOs on its own.
57
58Remember to use unique paths for each simulation you run in parallel.
59
60The backend will also realize about a possible abrupt disconnect from the other side.
61In that case, it will terminate the simulation.
62In case of a graceful disconnect from the other side, the backend will, by default, also
63terminate the simulation; But you can change this with a command line option, so that it will
64just disconnect the backend and continue running.
65
66For performance reasons, the backend does not react immediately to a CTS/RTS pin toggle from the
67other side. Instead up to 1 frame time (1 byte time) will elapse between the pin toggle
68and the UART peripheral model being notified. Note that the UART peripheral has a 6 byte Rx FIFO,
69and that it toggles RTS while there are still 4 spaces left. So even though this will, in some cases,
70cause up to 1 extra byte to be sent to the other side, it should not cause any transmission losses.
71
72If there is a miss-configuration between the devices (bit rate, parity or number of stop bits),
73the backend will print a warning for each received byte, but the ERRORSRC register in the UART
74peripheral won't be set due to fame, or parity errors, or break conditions.
75
76#### Loopback
77
78It is possible to connect a UART instance Tx directly to its Rx (or to another instance Rx),
79and have the RTR propagated to the CTS.
80To do this, just configure the same FIFO file name for both the Rx and Tx, for example like:
81`-uart0_fifob_rxfile=looped_back -uart0_fifob_txfile=looped_back`
82Note that you can also use the loopback backend when connecting a single instance in loopback,
83and have the same result with lower overhead, and no files created on disk.
84
85**IMPOTANT**:
86  Do not connect both devices which are connected thru the UART FIFO backend to the Physical layer
87  simulation simultaneously. Connect only the one which has the BLE/15.4 controller.
88  Otherwise, with the current implementation the simulation will deadlock with very high
89  likelihood, and if it does not deadlock it will slow down the simulation considerably.
90  You can still provide the sim_id and an unused device number to the other device, but
91  in that case, launch it with the `-nosim` option.
92