Pau Espin Pedrol | 46560ea | 2018-09-20 15:03:19 +0200 | [diff] [blame] | 1 | [[trx_backends]] |
| 2 | == OsmoTRX backend support |
| 3 | |
Pau Espin Pedrol | 6b50b62 | 2018-09-19 17:05:30 +0200 | [diff] [blame] | 4 | [[backend_uhd]] |
Pau Espin Pedrol | 46560ea | 2018-09-20 15:03:19 +0200 | [diff] [blame] | 5 | === `osmo-trx-uhd` for UHD based Transceivers |
Pau Espin Pedrol | d06172c | 2018-07-05 18:26:52 +0200 | [diff] [blame] | 6 | |
| 7 | This OsmoTRX model uses _libuhd_ (UHD, USRP Hardware Driver) to drive the |
| 8 | device, that is configuring it and reading/writing samples from/to it. |
| 9 | |
| 10 | So far, this backend has been mostly used to drive devices such as the Ettus |
| 11 | B200 family and Fairwaves UmTRX family, and used to be the default backend used |
| 12 | for legacy @osmo-trx@ binary when per-backend binaries didn't exist yet. |
| 13 | |
| 14 | Any device providing generic support for UHD should theoretically be able to be |
Martin Hauke | 066fd04 | 2019-10-13 19:08:00 +0200 | [diff] [blame] | 15 | run through this backend without much effort, but practical experience showed |
Pau Espin Pedrol | d06172c | 2018-07-05 18:26:52 +0200 | [diff] [blame] | 16 | that some devices don't play well with it, such as the LimeSDR family of |
| 17 | devices, which showed far better results when using its native interface. |
| 18 | |
| 19 | Related code can be found in the _Transceiver52M/device/uhd/_ directory in |
| 20 | _osmo-trx.git_. |
| 21 | |
Pau Espin Pedrol | 6b50b62 | 2018-09-19 17:05:30 +0200 | [diff] [blame] | 22 | [[backend_lms]] |
Pau Espin Pedrol | 46560ea | 2018-09-20 15:03:19 +0200 | [diff] [blame] | 23 | === `osmo-trx-lms` for LimeSuite based Transceivers |
Pau Espin Pedrol | d06172c | 2018-07-05 18:26:52 +0200 | [diff] [blame] | 24 | |
| 25 | This OsmoTRX model uses LimeSuite API and library to drive the device, that is |
| 26 | configuring it and reading/writing samples from/to it. |
| 27 | |
| 28 | This backend was developed in order to be used together with LimeSDR-USB and |
| 29 | LimeSDR-mini devices, due to to the poor results obtained with the UHD backend, |
| 30 | and to simplify the stack. |
| 31 | |
| 32 | Related code can be found in the _Transceiver52M/device/lms/_ directory in |
| 33 | _osmo-trx.git_. |
| 34 | |
Pau Espin Pedrol | 6b50b62 | 2018-09-19 17:05:30 +0200 | [diff] [blame] | 35 | [[backend_usrp1]] |
Pau Espin Pedrol | 46560ea | 2018-09-20 15:03:19 +0200 | [diff] [blame] | 36 | === `osmo-trx-usrp1` for libusrp based Transceivers |
Pau Espin Pedrol | d06172c | 2018-07-05 18:26:52 +0200 | [diff] [blame] | 37 | |
| 38 | This OsmoTRX model uses the legacy libusrp driver provided in GNU Radio 3.4.2. |
| 39 | |
| 40 | As this code was dropped from GNU Radio at some point and was found very |
| 41 | difficult to build, some work was done to create a standalone libusrp which can |
| 42 | be nowadays found as a separate git repository together with other osmocom git |
| 43 | repositories, in https://git.osmocom.org/libusrp/ |
| 44 | |
| 45 | Related code can be found in the _Transceiver52M/device/usrp1/_ directory in |
| 46 | _osmo-trx.git_. |
Pau Espin Pedrol | 06d3ba0 | 2019-07-30 17:56:03 +0200 | [diff] [blame] | 47 | |
| 48 | The USRPDevice module is basically a driver that reads/writes packets to a USRP |
| 49 | with two RFX900 daughterboards, board A is the Tx chain and board B is the Rx |
| 50 | chain. |
| 51 | |
| 52 | The `radioInterface` module is basically an interface between the transceiver |
| 53 | and the USRP. It operates the basestation clock based upon the sample count of |
| 54 | received USRP samples. Packets from the USRP are queued and segmented into GSM |
| 55 | bursts that are passed up to the transceiver; bursts from the transceiver are |
| 56 | passed down to the USRP. |
| 57 | |
| 58 | The transceiver basically operates "layer 0" of the GSM stack, performing the |
| 59 | modulation, detection, and demodulation of GSM bursts. It communicates with the |
| 60 | GSM stack via three UDP sockets, one socket for data, one for control messages, |
| 61 | and one socket to pass clocking information. The transceiver contains a priority |
| 62 | queue to sort to-be-transmitted bursts, and a filler table to fill in timeslots |
| 63 | that do not have bursts in the priority queue. The transceiver tries to stay |
| 64 | ahead of the basestation clock, adapting its latency when underruns are reported |
| 65 | by the radioInterface/USRP. Received bursts (from the radioInterface) pass |
| 66 | through a simple energy detector, a RACH or midamble correlator, and a DFE-based |
| 67 | demodulator. |
| 68 | |
| 69 | NOTE: There's a `SWLOOPBACK` #define statement, where the USRP is replaced |
| 70 | with a memory buffer. In this mode, data written to the USRP is actually stored |
| 71 | in a buffer, and read commands to the USRP simply pull data from this buffer. |
| 72 | This was very useful in early testing, and still may be useful in testing basic |
| 73 | Transceiver and radioInterface functionality. |
Pau Espin Pedrol | c5f623f | 2024-03-26 16:17:59 +0100 | [diff] [blame] | 74 | |
| 75 | |
| 76 | [[backend_ipc]] |
| 77 | === `osmo-trx-ipc` Inter Process Communication backend |
| 78 | |
| 79 | This OsmoTRX model provides its own Inter Process Communication (IPC) interface |
| 80 | to drive the radio device driver (from now on the Driver), allowing for third |
| 81 | party processes to implement the lowest layer device-specific bits without being |
| 82 | affected by copyleft licenses of OsmoTRX. |
| 83 | |
| 84 | For more information on such interface, see section <<ipc_if>>. |
| 85 | |
| 86 | [[fig-backend-ipc]] |
| 87 | .Architecture with _osmo-trx-ipc_ and its IPC _Driver_ |
| 88 | [graphviz] |
| 89 | ---- |
| 90 | digraph G { |
| 91 | rankdir=LR; |
| 92 | MS0 [label="MS"]; |
| 93 | MS1 [label="MS"]; |
| 94 | OsmoTRX [label="osmo-trx-ipc", color=red]; |
| 95 | BTS; |
| 96 | |
| 97 | subgraph cluster_ipc_driver { |
| 98 | label = "IPC Driver"; |
| 99 | color=red; |
| 100 | RE [label = "Radio Equipment"]; |
| 101 | REC [label="Radio Equipment Controller"]; |
| 102 | RE->REC; |
| 103 | } |
| 104 | |
| 105 | REC->OsmoTRX [label="IPC Interface", color=red]; |
| 106 | |
| 107 | MS0->RE [label="Um"]; |
| 108 | MS1->RE [label="Um"]; |
| 109 | OsmoTRX->BTS [label="bursts over UDP"]; |
| 110 | |
| 111 | } |
| 112 | ---- |
| 113 | |
| 114 | A sample config file for this OsmoTRX model can be found in _osmo-trx.git_ https://gitea.osmocom.org/cellular-infrastructure/osmo-trx/src/branch/master/doc/examples/osmo-trx-ipc/osmo-trx-ipc.cfg[doc/examples/osmo-trx-ipc/osmo-trx-ipc.cfg] |
| 115 | |
| 116 | In the config file, the following VTY command can be used to set up the IPC UD Master Socket _osmo-trx-ipc_ will connect to at startup: |
| 117 | |
| 118 | .Example: _osmo-trx-ipc_ will connect to UD Master Socket /tmp/ipc_sock0 upon startup |
| 119 | ---- |
| 120 | dev-args ipc_msock=/tmp/ipc_sock0 |
| 121 | ---- |
| 122 | |
| 123 | ==== ipc-device-test |
| 124 | |
| 125 | When built with `--with-ipc --with-uhd` configure options, _osmo-trx.git_ will |
| 126 | build the test program called _ipc-driver-test_. This program implements the |
| 127 | _Driver_ side of the osmo-trx-ipc interface (see <<ipc_if>> for more |
| 128 | information) on one side, and also interacts internally with UHD (eg B210 as |
| 129 | when using osmo-trx-uhd). |
| 130 | |
| 131 | You can use this small program as a reference to: |
| 132 | |
| 133 | * Test and experiment with _osmo-trx-ipc_. |
| 134 | |
| 135 | * Write your own IPC _Driver_ connecting to osmo-trx-ipc. |
| 136 | |
| 137 | [[fig-backend-ipc-device-test]] |
| 138 | .Architecture with _osmo-trx-ipc_ and ipc-device-test as IPC _Driver_ |
| 139 | [graphviz] |
| 140 | ---- |
| 141 | digraph G { |
| 142 | rankdir=LR; |
| 143 | MS0 [label="MS"]; |
| 144 | MS1 [label="MS"]; |
| 145 | SDR; |
| 146 | ipc_device_test[label = "ipc-device-test", color=red]; |
| 147 | OsmoTRX [label="osmo-trx-ipc", color=red]; |
| 148 | BTS; |
| 149 | |
| 150 | MS0->SDR [label="Um"]; |
| 151 | MS1->SDR [label="Um"]; |
| 152 | SDR->ipc_device_test [label="UHD"]; |
| 153 | ipc_device_test->OsmoTRX [label="IPC Interface", color=red]; |
| 154 | OsmoTRX->BTS [label="bursts over UDP"]; |
| 155 | } |
| 156 | ---- |
| 157 | |
| 158 | The code for this app is found here: |
| 159 | |
| 160 | * https://gitea.osmocom.org/cellular-infrastructure/osmo-trx/src/branch/master/Transceiver52M/device/ipc/ipc-driver-test.h[Transceiver52M/device/ipc/ipc-driver-test.h] |
| 161 | |
| 162 | * https://gitea.osmocom.org/cellular-infrastructure/osmo-trx/src/branch/master/Transceiver52M/device/ipc/ipc-driver-test.c[Transceiver52M/device/ipc/ipc-driver-test.c] |
| 163 | |
| 164 | Those files use the server-side (_Driver_ side) code to operate the Posix Shared |
| 165 | Memory region implemented in files `shm.c`, `shm.h`, `ipc_shm.c` and `ipc_shm.h` |
| 166 | in the same directory. |
| 167 | |
| 168 | Most of the code in that same directory is deliverately released under a BSD |
| 169 | license (unlike most of _osmo-trx.git_), allowing third parties to reuse/recycle |
| 170 | the code on their implemented _Driver_ program no matter it being proprietary or |
| 171 | under an open license. However, care must be taken with external dependencies, |
| 172 | as for instance shm.c uses the talloc memory allocator, which is GPL licensed |
| 173 | and hence cannot be used in a proprietary driver. |