Pau Espin Pedrol | f570b4a | 2018-09-20 15:02:03 +0200 | [diff] [blame] | 1 | [[code_architecture]] |
| 2 | == Code Architecture |
| 3 | |
| 4 | [[fig-code-architecture-general]] |
| 5 | .General overview of main OsmoTRX components |
| 6 | [graphviz] |
| 7 | ---- |
| 8 | digraph hierarchy { |
| 9 | node[shape=record,style=filled,fillcolor=gray95] |
| 10 | edge[dir=back, arrowtail=empty] |
| 11 | |
Pau Espin Pedrol | 8fd51cb | 2024-03-26 18:14:08 +0100 | [diff] [blame^] | 12 | 2[label = "{Transceiver|+ constructor()\l+ destructor()\l+ init()\l+ numChans()\l+ receiveFIFO()\l+ setSignalHandler()\l}"] |
Pau Espin Pedrol | f570b4a | 2018-09-20 15:02:03 +0200 | [diff] [blame] | 13 | 3[label = "{RadioInterface|...}"] |
| 14 | 4[label = "{RadioInterfaceResamp|...}"] |
| 15 | 5[label = "{RadioInterfaceMulti|...}"] |
| 16 | 6[label = "{RadioDevice|...}"] |
| 17 | 7[label = "{UHDDevice|...}"] |
| 18 | 8[label = "{LMSDevice|...}"] |
| 19 | 9[label = "{USRPDevice|...}"] |
| 20 | |
| 21 | 2->3[arrowtail=odiamond] |
| 22 | 3->4[constraint=false] |
| 23 | 3->5[constraint=false] |
| 24 | 3->6[arrowtail=odiamond] |
| 25 | 6->7 |
| 26 | 6->8 |
| 27 | 6->9 |
| 28 | } |
| 29 | ---- |
| 30 | |
| 31 | [[fig-code-architecture-threads]] |
| 32 | .Example of thread architecture with OsmoTRX configured to use 2 logical RF channels (Trx=Transceiver, RI=RadioIface) |
| 33 | [graphviz] |
| 34 | ---- |
| 35 | digraph hierarchy { |
| 36 | node[shape=record,style=filled,fillcolor=gray95] |
| 37 | |
| 38 | trans [label="Transceiver"]; |
| 39 | radioiface [label="RadioInterface"]; |
| 40 | radiodev [label="RadioDevice"]; |
| 41 | |
Pau Espin Pedrol | c62a051 | 2020-07-01 12:24:52 +0200 | [diff] [blame] | 42 | trans:nw->trans:ne [label="Main"]; |
Pau Espin Pedrol | f570b4a | 2018-09-20 15:02:03 +0200 | [diff] [blame] | 43 | trans:w->radioiface:w [label="Trx.TxPriorityQueueServiceLoop_0"]; |
| 44 | trans:w->radioiface:w [label="Trx.TxPriorityQueueServiceLoop_1"]; |
| 45 | radioiface:e->trans:e [label="Trx.RxServiceLoop_0"]; |
| 46 | radioiface:e->trans:e [label="Trx.RxServiceLoop_1"]; |
| 47 | radioiface->radiodev[label="RI.AlignRadioServiceLoop"]; |
| 48 | radioiface:sw->radiodev:nw [label="Trx.TxLowerLoop"]; |
| 49 | radiodev:ne->radioiface:se [label="Trx.RxLowerLoop"]; |
| 50 | } |
| 51 | ---- |
| 52 | |
| 53 | [[code_component_transceiver]] |
| 54 | === Transceiver |
| 55 | |
| 56 | The Transceiver is the main component managing the other components running in |
| 57 | the OsmoTRX process. There's a unique instance per process. |
| 58 | |
| 59 | This class is quite complex from code point of view, as it starts lots of |
| 60 | different threads and hence the interaction with this class from the outside is |
| 61 | quite limited. Only interaction possible is to: |
| 62 | |
| 63 | * `Transceiver()`: Create an instance through its constructor, at this time most |
| 64 | configuration is handed to it. |
| 65 | * `init()`: Start running all the threads. |
| 66 | * `receiveFIFO()`: Attach a `radioInterface` channel FIFO in order to use it. |
| 67 | * `setSignalHandler()`: Used to set up a callback to receive certain events |
| 68 | asynchronously from the Transceiver. No assumptions can be made about from |
| 69 | which thread is the callback being called, which means multi-thread locking |
| 70 | precautions may be required in certain cases, similar to usual signal handler |
| 71 | processing. One important event received through this path is for instance |
| 72 | when the Transceiver detected a fatal error which requires it to stop. Since |
| 73 | it cannot stop itself (see destructor below), stopping procedure must be |
| 74 | delegated to the user who created the instance. |
| 75 | * `~Transceiver()`: The destructor, which stops all running threads created at |
| 76 | `init()` time. Destroying the object is the only way to stop the `Transceiver` |
| 77 | completely, and must be called from a thread not managed by the |
| 78 | `Transceiver`, otherwise it will deadlock. Usually it is stopped from the main |
| 79 | thread, the one that called the constructor during startup. |
| 80 | |
| 81 | During `init()` time, `Transceiver` will create a noticeable amount of threads, |
| 82 | which may vary depending on the amount of RF channels requested. |
| 83 | |
| 84 | Static amount of Threads (1 per `Transceiver` instance): |
| 85 | |
| 86 | * `RxLowerLoop`: This thread is responsible for reading bursts from the |
| 87 | `RadioInterface`, storing them into its FIFO and sending Clock Indications |
| 88 | (<<trx_if_clock_ind>>) to _osmo-bts_trx_. |
| 89 | * `TxLowerLoop`: Manages pushing bursts from buffers in the FIFO into the |
| 90 | `RadioInterface` at expected correct time based on the Transceiver clock. |
| 91 | |
| 92 | Dynamic amount of Threads (1 per RF logical channel on the `Transceiver` instance): |
| 93 | |
Pau Espin Pedrol | f570b4a | 2018-09-20 15:02:03 +0200 | [diff] [blame] | 94 | * `RxServiceLoop`: Each thread of this type pulls bursts from the |
| 95 | `RadioInterface` FIFO for one specific logical RF channel and handles it |
| 96 | according to the slot and burst correlation type, finally sending proper data |
| 97 | over the TRX Manager UDP socket (<<trx_if>>). |
| 98 | * `TxPriorityQueueServiceLoop`: Blocks reading from one ARFCN specific TRX |
| 99 | Manager UDP socket (<<trx_if>>), and fills the `RadioInterface` with it |
| 100 | setting clock related information. |
| 101 | |
Pau Espin Pedrol | c62a051 | 2020-07-01 12:24:52 +0200 | [diff] [blame] | 102 | All the Per-ARFCN Control Interface socket (<<trx_if_control>>) commands are |
| 103 | handled by the event loop runnnig on the main thread. This is the only thread |
| 104 | expected to use the private `start()` and `stop()` methods. |
| 105 | |
Pau Espin Pedrol | f570b4a | 2018-09-20 15:02:03 +0200 | [diff] [blame] | 106 | [[code_component_radioiface]] |
| 107 | === RadioInterface |
| 108 | |
| 109 | The `RadioInterface` sits between the `Transceiver` and the `RadioDevice`, and |
| 110 | provides extra features to the pipe like channelizers, resamplers, Tx/Rx |
| 111 | synchronization on some devices, etc. |
| 112 | |
| 113 | If the `RadioDevice` it drives requires it (only _USRP1_ so far), the |
| 114 | `RadioIntercace` will start and manage a thread internally called |
| 115 | `AlignRadioServiceLoop` which will align current RX and TX timestamps. |
| 116 | |
| 117 | Different features are offered through different `RadioInterface` subclasses |
| 118 | which are selected based on configuration and device detected at runtime. Using |
| 119 | these features may impact on the amount of CPU required to run the entire pipe. |
| 120 | |
| 121 | ==== RadioInterfaceResamp |
| 122 | |
| 123 | This subclass of `RadioInterface` is automatically selected when some known |
| 124 | specific UHD are to be used, since they require resampling to work properly. |
| 125 | Some of this devices are for instance Ettus B100, USRP2 and X3XX models. |
| 126 | |
| 127 | ==== RadioInterfaceMulti |
| 128 | |
| 129 | This subclass of `RadioInterface` is used when <<multiarfcn_mode>> is requested. |
| 130 | |
| 131 | [[code_component_radiodev]] |
| 132 | === RadioDevice |
| 133 | |
| 134 | The `RadioDevice` class is responsible for driving the actual Hardware device. |
| 135 | It is actually only an interface, and it is implemented in each backend which in |
| 136 | turn becomes a specific OsmoTRX binary, see <<trx_backends>>. |