diff options
Diffstat (limited to 'OsmoTRX/chapters')
| -rw-r--r-- | OsmoTRX/chapters/code-architecture.adoc | 141 | ||||
| -rw-r--r-- | OsmoTRX/chapters/configuration.adoc | 85 | ||||
| -rw-r--r-- | OsmoTRX/chapters/control.adoc | 12 | ||||
| -rw-r--r-- | OsmoTRX/chapters/counters.adoc | 4 | ||||
| -rw-r--r-- | OsmoTRX/chapters/counters_generated.adoc | 7 | ||||
| -rw-r--r-- | OsmoTRX/chapters/overview.adoc | 62 | ||||
| -rw-r--r-- | OsmoTRX/chapters/running.adoc | 19 | ||||
| -rw-r--r-- | OsmoTRX/chapters/trx-architectures.adoc | 34 | ||||
| -rw-r--r-- | OsmoTRX/chapters/trx-backends.adoc | 46 | ||||
| -rw-r--r-- | OsmoTRX/chapters/trx-devices.adoc | 90 |
10 files changed, 0 insertions, 500 deletions
diff --git a/OsmoTRX/chapters/code-architecture.adoc b/OsmoTRX/chapters/code-architecture.adoc deleted file mode 100644 index 18d0e3a..0000000 --- a/OsmoTRX/chapters/code-architecture.adoc +++ /dev/null @@ -1,141 +0,0 @@ -[[code_architecture]] -== Code Architecture - -[[fig-code-architecture-general]] -.General overview of main OsmoTRX components -[graphviz] ----- -digraph hierarchy { -node[shape=record,style=filled,fillcolor=gray95] -edge[dir=back, arrowtail=empty] - -2[label = "{Transceiver|+ constructor()\l+ destructor()\l+ init()\l+ numChans()\l+ receiveFIFO()\l+ setSignalHandler()}"] -3[label = "{RadioInterface|...}"] -4[label = "{RadioInterfaceResamp|...}"] -5[label = "{RadioInterfaceMulti|...}"] -6[label = "{RadioDevice|...}"] -7[label = "{UHDDevice|...}"] -8[label = "{LMSDevice|...}"] -9[label = "{USRPDevice|...}"] - -2->3[arrowtail=odiamond] -3->4[constraint=false] -3->5[constraint=false] -3->6[arrowtail=odiamond] -6->7 -6->8 -6->9 -} ----- - -[[fig-code-architecture-threads]] -.Example of thread architecture with OsmoTRX configured to use 2 logical RF channels (Trx=Transceiver, RI=RadioIface) -[graphviz] ----- -digraph hierarchy { -node[shape=record,style=filled,fillcolor=gray95] - -trans [label="Transceiver"]; -radioiface [label="RadioInterface"]; -radiodev [label="RadioDevice"]; - -trans:nw->trans:ne [label="Trx.ControlServiceLoop_0"]; -trans:nw->trans:ne [label="Trx.ControlServiceLoop_1"]; -trans:w->radioiface:w [label="Trx.TxPriorityQueueServiceLoop_0"]; -trans:w->radioiface:w [label="Trx.TxPriorityQueueServiceLoop_1"]; -radioiface:e->trans:e [label="Trx.RxServiceLoop_0"]; -radioiface:e->trans:e [label="Trx.RxServiceLoop_1"]; -radioiface->radiodev[label="RI.AlignRadioServiceLoop"]; -radioiface:sw->radiodev:nw [label="Trx.TxLowerLoop"]; -radiodev:ne->radioiface:se [label="Trx.RxLowerLoop"]; -} ----- - -[[code_component_transceiver]] -=== Transceiver - -The Transceiver is the main component managing the other components running in -the OsmoTRX process. There's a unique instance per process. - -This class is quite complex from code point of view, as it starts lots of -different threads and hence the interaction with this class from the outside is -quite limited. Only interaction possible is to: - -* `Transceiver()`: Create an instance through its constructor, at this time most - configuration is handed to it. -* `init()`: Start running all the threads. -* `receiveFIFO()`: Attach a `radioInterface` channel FIFO in order to use it. -* `setSignalHandler()`: Used to set up a callback to receive certain events - asynchronously from the Transceiver. No assumptions can be made about from - which thread is the callback being called, which means multi-thread locking - precautions may be required in certain cases, similar to usual signal handler - processing. One important event received through this path is for instance - when the Transceiver detected a fatal error which requires it to stop. Since - it cannot stop itself (see destructor below), stopping procedure must be - delegated to the user who created the instance. -* `~Transceiver()`: The destructor, which stops all running threads created at - `init()` time. Destroying the object is the only way to stop the `Transceiver` - completely, and must be called from a thread not managed by the - `Transceiver`, otherwise it will deadlock. Usually it is stopped from the main - thread, the one that called the constructor during startup. - -During `init()` time, `Transceiver` will create a noticeable amount of threads, -which may vary depending on the amount of RF channels requested. - -Static amount of Threads (1 per `Transceiver` instance): - -* `RxLowerLoop`: This thread is responsible for reading bursts from the - `RadioInterface`, storing them into its FIFO and sending Clock Indications - (<<trx_if_clock_ind>>) to _osmo-bts_trx_. -* `TxLowerLoop`: Manages pushing bursts from buffers in the FIFO into the - `RadioInterface` at expected correct time based on the Transceiver clock. - -Dynamic amount of Threads (1 per RF logical channel on the `Transceiver` instance): - -* `ControlServiceLoop`: Handles commands from the Per-ARFCN Control Interface - socket (<<trx_if_control>>). Each thread is responsible for managing one - socket related to one ARFCN or which is the same, to one RF logical channel. - These are the only threads expected to use the private `start()` and `stop()` - methods of the `Transceiver()` class, since those methods don't stop any of - the `ControlServiceLoop` threads as they must keep running to handle new - commands (for instance, to re-start processing samples with the _POWERON_ - command). -* `RxServiceLoop`: Each thread of this type pulls bursts from the - `RadioInterface` FIFO for one specific logical RF channel and handles it - according to the slot and burst correlation type, finally sending proper data - over the TRX Manager UDP socket (<<trx_if>>). -* `TxPriorityQueueServiceLoop`: Blocks reading from one ARFCN specific TRX - Manager UDP socket (<<trx_if>>), and fills the `RadioInterface` with it - setting clock related information. - -[[code_component_radioiface]] -=== RadioInterface - -The `RadioInterface` sits between the `Transceiver` and the `RadioDevice`, and -provides extra features to the pipe like channelizers, resamplers, Tx/Rx -synchronization on some devices, etc. - -If the `RadioDevice` it drives requires it (only _USRP1_ so far), the -`RadioIntercace` will start and manage a thread internally called -`AlignRadioServiceLoop` which will align current RX and TX timestamps. - -Different features are offered through different `RadioInterface` subclasses -which are selected based on configuration and device detected at runtime. Using -these features may impact on the amount of CPU required to run the entire pipe. - -==== RadioInterfaceResamp - -This subclass of `RadioInterface` is automatically selected when some known -specific UHD are to be used, since they require resampling to work properly. -Some of this devices are for instance Ettus B100, USRP2 and X3XX models. - -==== RadioInterfaceMulti - -This subclass of `RadioInterface` is used when <<multiarfcn_mode>> is requested. - -[[code_component_radiodev]] -=== RadioDevice - -The `RadioDevice` class is responsible for driving the actual Hardware device. -It is actually only an interface, and it is implemented in each backend which in -turn becomes a specific OsmoTRX binary, see <<trx_backends>>. diff --git a/OsmoTRX/chapters/configuration.adoc b/OsmoTRX/chapters/configuration.adoc deleted file mode 100644 index 87d7903..0000000 --- a/OsmoTRX/chapters/configuration.adoc +++ /dev/null @@ -1,85 +0,0 @@ -== Configuring OsmTRX - -OsmoTRX will read the configuration at startup time and configure the -transceiver accordingly after validating the configuration. - -OsmoTRX can handle several TRX channels, but at least one must be configured in -order to be able to start it successfully. Channels must be present in the -configuration file in incremental order, starting from 0 and be consecutive. - -Example configuration files for different devices and setups can be found in -`doc/examples/` in 'osmo-trx' git repository. - -=== Documented example - -.Example: Static GGSN/APN configuration (single catch-all GGSN) ----- -trx - bind-ip 127.0.0.1 <1> - remote-ip 127.0.0.1 <2> - base-port 5700 <3> - egprs disable <4> - tx-sps 4 <5> - rx-sps 4 <6> - chan 0 <7> - tx-path BAND1 <8> - rx-path LNAW <9> ----- -<1> Configure the local IP address at the TRX used for the connection against `osmo-bts-trx`. -<2> Specify the IP address of `osmo-bts-trx` to connect to. -<3> Specify the reference base UDP port to use for communication. -<4> Don't enable EDGE support. -<5> Use 4 TX samples per symbol. This is device specific. -<6> Use 4 RX samples per symbol. This is device specific. -<7> Configure the first channel. As no other channels are specified, `osmo-trx` assumes it is using only one channel. -<8> Configure the device to use `BAND1` Tx antenna path from all the available ones (device specific). -<9> Configure the device to use `LNAW` Rx antenna path from all the available ones (device specific). - -[[multiarfcn_mode]] -=== Multi-ARFCN mode - -The Multi-ARFCN feature allows to have a multi-carrier approach multiplexed on a -single physical RF channel, which can introduce several benefits, such as lower -cost and higher capacity support. - -Multi-ARFCN support is available since osmo-trx release `0.2.0`, and it was -added specifically in commit `76764278169d252980853251daeb9f1ba0c246e1`. - -This feature is useful for instance if you want to run more than 1 TRX with an -Ettus B200 device, or 3 TRX with an Ettus B210 device, since they support only 1 -and 2 physical RF channels respectively. No device from other providers or even -other devices than B200 and B210 from Ettus are known to support this feature. - -With multi-ARFCN enabled, ARFCN spacing is fixed at 800 kHz or 4 GSM channels. -So if TRX-0 is set to ARFCN 51, TRX-1 _must_ be set to 55, and so on. Up to -three ARFCN's is supported for multi-TRX. - -From BTS and BSC point of view, supporting multiple TRX through multi-ARFCN -feature in OsmoTRX doesn't make any difference from a regular multi-TRX setup, -leaving apart of course the mentioned ARFCN limitations explained above and as a -consequence physical installation and operational differences. - -.Example: osmo-bts-trx.cfg using 2 TRX against an osmo-trx driven device ----- -phy 0 - osmotrx ip local 127.0.0.1 - osmotrx ip remote 127.0.0.1 - instance 0 - instance 1 -bts 0 - ... - band GSM-1800 - trx 0 - phy 0 instance 0 - trx 1 - phy 0 instance 1 ----- - -.Example: osmo-trx.cfg using Multi-ARFCN mode to run 2 TRX ----- -trx - ... - multi-arfcn enable - chan 0 - chan 1 ----- diff --git a/OsmoTRX/chapters/control.adoc b/OsmoTRX/chapters/control.adoc deleted file mode 100644 index 168769a..0000000 --- a/OsmoTRX/chapters/control.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[[control]] -== Control interface - -The actual protocol is described in <<common-control-if>>, the variables -common to all programs using it are described in <<ctrl_common_vars>>. Here we -describe variables specific to OsmoTRX. - -.Variables available over control interface -[options="header",width="100%",cols="20%,5%,5%,50%,20%"] -|=== -|Name|Access|Trap|Value|Comment -|=== diff --git a/OsmoTRX/chapters/counters.adoc b/OsmoTRX/chapters/counters.adoc deleted file mode 100644 index 7fbb10c..0000000 --- a/OsmoTRX/chapters/counters.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[[counters]] -== Counters - -include::./counters_generated.adoc[] diff --git a/OsmoTRX/chapters/counters_generated.adoc b/OsmoTRX/chapters/counters_generated.adoc deleted file mode 100644 index b40dc37..0000000 --- a/OsmoTRX/chapters/counters_generated.adoc +++ /dev/null @@ -1,7 +0,0 @@ -// autogenerated by show asciidoc counters -These counters and their description based on OsmoTRX 0.2.0.61-408f (OsmoTRX). - -// generating tables for rate_ctr_group -// generating tables for osmo_stat_items -// generating tables for osmo_counters -// there are no ungrouped osmo_counters diff --git a/OsmoTRX/chapters/overview.adoc b/OsmoTRX/chapters/overview.adoc deleted file mode 100644 index 785e26b..0000000 --- a/OsmoTRX/chapters/overview.adoc +++ /dev/null @@ -1,62 +0,0 @@ -[[chapter_introduction]] -== Overview - -[[intro_overview]] -=== About OsmoTRX - -OsmoTRX is a C/C++ language implementation of the GSM radio modem, -originally developed as the 'Transceiver' part of OpenBTS. This radio -modem offers an interface based on top of UDP streams. - - -The OsmoBTS bts_model code for OsmoTRX is called -`osmo-bts-trx`. It implements the UDP stream interface of -OsmoTRX, so both parts can be used together to implement a complete GSM -BTS based on general-purpose computing SDR. - -As OsmoTRX is general-purpose software running on top of Linux, it is -thus not tied to any specific physical hardware. At the time of this -writing, OsmoTRX supports a variety of Lime Microsystems and Ettus USRP SDRs via -the UHD driver, as well as the Fairwaves UmTRX and derived products. - -OsmoTRX is not a complete GSM PHY but 'just' the radio modem. This -means that all of the Layer 1 functionality such as scheduling, -convolutional coding, etc. is actually also implemented inside OsmoBTS. -OsmoTRX is a software-defined radio transceiver that implements the Layer 1 -physical layer of a BTS comprising the following 3GPP specifications: - -* TS 05.01 "Physical layer on the radio path" -* TS 05.02 "Multiplexing and Multiple Access on the Radio Path" -* TS 05.04 "Modulation" -* TS 05.10 "Radio subsystem synchronization - -As such, the boundary between OsmoTRX and `osmo-bts-trx` is at -a much lower interface, which is an internal interface of other more -traditional GSM PHY implementations. - -Besides OsmoTRX, there are also other implementations (both Free -Software and proprietary) that implement the same UDP stream based radio -modem interface. - -[[fig-gprs-pcubts]] -.GSM network architecture with OsmoTRX and OsmoBTS -[graphviz] ----- -digraph G { - rankdir=LR; - MS0 [label="MS"]; - MS1 [label="MS"]; - MS0->SDR[label="Um"]; - MS1->SDR [label="Um"]; - SDR -> OsmoTRX [label="Raw Samples"]; - OsmoTRX->BTS [label="bursts over UDP"]; - BTS->BSC [label="Abis"]; - BSC->MSC [label="A"]; - BTS->PCU [label="pcu_sock"]; - PCU->SGSN [label="Gb"]; - OsmoTRX [color=red]; -} ----- - -For more information see -https://osmocom.org/projects/osmotrx/wiki/OsmoTRX diff --git a/OsmoTRX/chapters/running.adoc b/OsmoTRX/chapters/running.adoc deleted file mode 100644 index 7ed2884..0000000 --- a/OsmoTRX/chapters/running.adoc +++ /dev/null @@ -1,19 +0,0 @@ -== Running OsmoTRX - -The OsmoTRX executable (`osmo-trx`) offers the following command-line -options: - - -=== SYNOPSIS - -*osmo-trx* [-h] [-C 'CONFIGFILE'] - - -=== OPTIONS - -*-h*:: - Print a short help message about the supported options -*-C 'CONFIGFILE'*:: - Specify the file and path name of the configuration file to be - used. If none is specified, use `osmo_trx.cfg` in the current - working directory. diff --git a/OsmoTRX/chapters/trx-architectures.adoc b/OsmoTRX/chapters/trx-architectures.adoc deleted file mode 100644 index 66eae5e..0000000 --- a/OsmoTRX/chapters/trx-architectures.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[[osmotrx_arch_support]] -== OsmoTRX hardware architecture support - -OsmoTRX comes out-of-the-box with several algorithms and operations -optimized for certain instruction-set architectures, as well as non-optimized -fall-back algorithms in case required instruction sets are not supported by the -compiler at compile time or by the executing machine at run-time. Support for -these optimized algorithms can be enabled and disabled by means of configure -flags. Accelerated operations include pulse shape filtering, resampling, -sequence correlation, and many other signal processing operations. - -On Intel processors, OsmoTRX makes heavy use of the Streaming SIMD Extensions -(SSE) instruction set. SSE3 is the minimum requirement for accelerated use. -SSE3 is present in the majority of Intel processors since later versions of the -Pentium 4 architecture and is also present on low power Atom processors. Support -is automatically detected at build time. SSE4.1 instruction set is supported -too. This feature is enabled by default unless explicitly disabled by passing -the configure flag _--with-sse=no_. When enabled, the compiler will build an -extra version of each of the supported algorithms using each of the supported -mentioned instruction sets. Then, at run-time, OsmoTRX will auto-detect -capabilities of the executing machine and enable an optimized algorithm using -the most suitable available (previously compiled) instruction set. - -On ARM processors, NEON and NEON FMA are supported. Different to the x86, there -is no auto-detection in this case, nor difference between compile and runtime. -NEON support is disabled by default and can be enabled by passing the flag -_--with-neon=yes_ to the configure script; the used compiler must support NEON -instruction set and the resulting binary will only run fine on an ARM board -supporting NEON extensions. Running OsmoTRX built with flag _--with-neon_ on a -board without NEON instruction set support, will most probably end up in the -process being killed with a _SIGILL_ Illegal Instruction signal by the operating -system. NEON FMA (Fused Multiply-Add) is an extension to the NEON instruction -set, and its use in OsmoTRX can be enabled by passing the _--with_neon_vfpv4_ -flag, which will also implicitly enable NEON support (_--with_neon_). diff --git a/OsmoTRX/chapters/trx-backends.adoc b/OsmoTRX/chapters/trx-backends.adoc deleted file mode 100644 index 8829fa6..0000000 --- a/OsmoTRX/chapters/trx-backends.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[[trx_backends]] -== OsmoTRX backend support - -[[backend_uhd]] -=== `osmo-trx-uhd` for UHD based Transceivers - -This OsmoTRX model uses _libuhd_ (UHD, USRP Hardware Driver) to drive the -device, that is configuring it and reading/writing samples from/to it. - -So far, this backend has been mostly used to drive devices such as the Ettus -B200 family and Fairwaves UmTRX family, and used to be the default backend used -for legacy @osmo-trx@ binary when per-backend binaries didn't exist yet. - -Any device providing generic support for UHD should theoretically be able to be -run through this backend without much effort, but pracitcal experience showed -that some devices don't play well with it, such as the LimeSDR family of -devices, which showed far better results when using its native interface. - -Related code can be found in the _Transceiver52M/device/uhd/_ directory in -_osmo-trx.git_. - -[[backend_lms]] -=== `osmo-trx-lms` for LimeSuite based Transceivers - -This OsmoTRX model uses LimeSuite API and library to drive the device, that is -configuring it and reading/writing samples from/to it. - -This backend was developed in order to be used together with LimeSDR-USB and -LimeSDR-mini devices, due to to the poor results obtained with the UHD backend, -and to simplify the stack. - -Related code can be found in the _Transceiver52M/device/lms/_ directory in -_osmo-trx.git_. - -[[backend_usrp1]] -=== `osmo-trx-usrp1` for libusrp based Transceivers - -This OsmoTRX model uses the legacy libusrp driver provided in GNU Radio 3.4.2. - -As this code was dropped from GNU Radio at some point and was found very -difficult to build, some work was done to create a standalone libusrp which can -be nowadays found as a separate git repository together with other osmocom git -repositories, in https://git.osmocom.org/libusrp/ - -Related code can be found in the _Transceiver52M/device/usrp1/_ directory in -_osmo-trx.git_. diff --git a/OsmoTRX/chapters/trx-devices.adoc b/OsmoTRX/chapters/trx-devices.adoc deleted file mode 100644 index 10c8529..0000000 --- a/OsmoTRX/chapters/trx-devices.adoc +++ /dev/null @@ -1,90 +0,0 @@ -[[osmotrx_device_support]] -== OsmoTRX hardware device support - -OsmoTRX consists of a _common_ part that applies to all TRX devices as well as -_hardware-specific_ parts for each TRX device. The hardware-specific parts are -usually provided by vendor-specific or device-specific libraries that are then -handled by some OsmoTRX glue code presenting a unified interface towards the -rest of the code by means of a _RadioDevice_ class. - -The common part includes the core TRX architecture as well as code for -implementing the external interfaces such as the TRX Manager UDP socket, -control, and VTY interfaces. - -The hardware-specific parts include support for driving one particular -implementation of a radio modem. Such a physical layer -implementation can come in many forms. Sometimes it runs on a general -purpose CPU, sometimes on a dedicated ARM core, a dedicated DSP, a -combination of DSP and FPGA. - -Joining the common part with each of the available backends results in a -different binary with different suffix for each backend. For instance, when -OsmoTRX is built with UHD backend, an _osmo-trx-uhd_ binary is generated; when -OsmoTRX is built with LimeSuite backend, an _osmo-trx-lms_ binary is generated. -Build of different backend can be enabled and disabled by means of configure -flags, which can be found in each subsection relative to each backend below. - -[[dev_ettus_usrp1]] -=== Ettus USRP1 - -The binary _osmo-trx-usrp1_ is used to drive this device, see <<backend_usrp1>>. - -[[dev_ettus_b200]] -=== Ettus B200 - -The binary _osmo-trx-uhd_ is used to drive this device, see <<backend_uhd>>. - -Comes only with 1 RF channel. It can still be used in a multi-TRX setup by using -the <<multiarfcn_mode>> feature. By using this feature, one can drive up to 3 -TRX (with the restrictions explained there). - -[[dev_ettus_b200]] -=== Ettus B210 - -The binary _osmo-trx-uhd_ is used to drive this device, see <<backend_uhd>>. - -Comes with 2 RF channels, which can be used to set up a multi-TRX BTS. However, -due to a shared local oscillator for both RF channels, ARFCN separation can be -up about 25 MHz. - -This device also supports the <<multiarfcn_mode>> feature. By using this -feature, one can drive up to 3 TRX (with the restrictions explained there). -Please note that the above configurations cannot be combined, which means -maximum number of TRX one can achieve is 2 by using separate physical RF -channels, or 3 by using multi-ARFCN method. You cannot support, for example, 6 -ARFCN operation on B210 using 3 TRX on side A and another 3 TRX on side B. - -[[dev_limesdr_usb]] -=== LimeSDR-USB - -The binary _osmo-trx-lms_ is used to drive this device, see <<backend_lms>>. - -This device comes with 2 RF channels, so it should theoretically be possible to -run a multi-TRX setup with it, but there are yet no records that this kind of -setup was tested with this device. - -This device has 3 different Rx paths with different antenna connectors in the -PCB, each with a different frequency and bandwidth range. One should make sure -the physical antenna is connected to the correct connector matching the Rx path -you want to use. If one wants to be able to use the device in both 900 and 1800 -MHz GSM bands and easily switch between them, then Rx Path `LNAW` should be used -,since it is the only one covering both bands, and the antenna physically plugged -accordingly. Following example shows how to then configure _osmo-trx-lms_ to use -that Rx path to read samples. - -.Example: Configure osmo-trx-lms to use LNAW as Rx path and BAND1 as Tx Path ----- -trx - ... - chan 0 - tx-path BAND1 - rx-path LNAW ----- - -[[dev_limesdr_mini]] -=== LimeSDR-mini - -The binary _osmo-trx-lms_ is used to drive this device, see <<backend_lms>>. - -As a smaller brother of the [[dev_limesdr_usb]], this device comes only with 1 -RF channel. As a result, it can only hold 1 TRX as of today. |