1# EDTT transport for BabbleSim devices
2
3This is a description of the inner workings of the
4EDTT transport for BabbleSim (`edttt_bsim.py` and associated embedded driver)
5
6## Introduction
7
8In simulation the picture of how the communication between the EDTT and the
9devices looks as follows:
10
11```
12 ___________       __________       _________________
13|           | --> |          | --> |                 |
14|           |     | Device 0 |     |                 |
15| EDTT      | <-- |__________| <-- |                 |
16| BSim      |      __________      |                 |
17| transport | --> |          | --> |                 |
18|           |     | Device 1 |     |                 |
19|           | <-- |__________| <-- |                 |
20|           |                      |                 |
21|           | <------------------- |                 |
22|___________| -------------------> |                 |
23  |                                |    BabbleSim    |
24  |                                |                 |
25 ________                          |                 |
26|        |                         |                 |
27| low    | ----------------------> |                 |
28| level  |                         |                 |
29| device | <---------------------- |                 |
30|________|                         |_________________|
31
32```
33
34Each of the “-->” is a POSIX named pipe (FIFO) (which by default can buffer up to
3564KB in each direction).
36
37The low level device (if enabled) is a BSim device in itself; It can be used to inject raw
38BLE packets without going through a BLE controller first.
39
40The transport has 2 main functions:
41
42* It allows reading and writting from the EDTT data to the appropriate device
43* It pauses the simulation while the EDTT is processing, so there is no asynchronous
44  behaviour, and let's it advance only when desired (when wait() is called,
45  or when a recv() cannot be completed instantenously
46
47
48The EDTT, will only run while the simulation itself is paused.
49
50The EDTT can interact in 3 ways with the devices and Phy:
51* When the EDTT writes to a device, that data is piped immediately to the device (without unblocking the simulation).
52* When the EDTT reads from the device, it tries to read from the device pipe immediately:
53  * If it succeeds it responds to the caller immediately with the data
54  * If there is not enough data yet from the device, it will wait
55    `<RxWait>` in simulated time, that is, it will let the
56    simulation time to advance by `<RxWait>`, and try again.
57    (`<RxWait>` is a  command line option, by default 10ms)
58* When the EDTT does `transport.wait(time)`, it tells the Phy to just let
59the simulation time go ahead for `<time>`.
60
61
62### The embedded device transport
63
64* When the app tries to read from the EDTT transport: it will try immediately
65  * If there is enough data, it just returns it to the caller
66  * If it does not have enough data yet, and the read was blocking,
67    will wait for `EDTT_IF_RECHECK_DELTA` (5ms) and retry
68* When told to write it will pipe it to the bridge immediately without any delay
69
70So effectively:
71
72* Writing from the EDTT to the device can be aparent to the device only the next
73  time the device checks (up to EDTT_IF_RECHECK_DELTA later)
74* Reading from the device can take up to the next `<RxWait>` boundary
75  for the EDTT bridge to read it out, apart from the simulated time it may
76  take for the device to generate it.
77
78
79## Implementation details:
80
81The named pipes are placed in /tmp/bsim_<user>/<sim_id>/
82There are 2 from the EDTT transport to each device
83
84* Device<device_id>.PTTin
85* Device<device_id>.PTTout
86
87### Notes about the transport in the EDTT side
88
89When connect() is called the FIFOs to the Phy will be created
90(if not yet there), and the EDTT will be blocked until the Phy
91connects on the other side.
92
93Rigth after the FIFOs to the devices will be created, similarly
94blocking the EDTTT.
95
96When disconnecting, the transport will attempt to delete the FIFOs
97(the last one who disconnects from its end succeds)
98
99### Notes about the transport in the DUT side
100
101On the initial connection, edtt_start(), the pipes are opened,
102and the simulated device execution is blocked until the EDTTT
103connects to the other side.
104
105When sending and receiving data to and towards the EDTT,
106the byte stream is passed through unaltered.
107
108Reads can be blocking (EDTTT_BLOCK), waiting for the bytes to arrive,
109or non-blocking (EDTTT_NONBLOCK).
110
111Writes are always treated as non-blocking in this trasnport, assuming that
112the FIFO is large enough to queue the request. In the very unlikely case in which
113it would not be, an error would be printed.
114
115When the transport layer is closed, the EDTTT FIFOs are closed and deleted.
116
117### Note about the low level device
118
119The low level device attached to the EDTT BSim transport is optional (though some test
120cases may require it to be present). By default, the EDTT BSim transport will run without
121it; To enable it use the --low-level-device (or -l for short) command line argument.
122
123Since the low level device is a BSim device in itself, it requires a BSim device number
124to be assigned to it when enabled; Specify this using the --low-level-device-nbr command line argument.
125