diff options
Diffstat (limited to 'OsmoBTS/chapters/bts-models.adoc')
| -rw-r--r-- | OsmoBTS/chapters/bts-models.adoc | 441 |
1 files changed, 0 insertions, 441 deletions
diff --git a/OsmoBTS/chapters/bts-models.adoc b/OsmoBTS/chapters/bts-models.adoc deleted file mode 100644 index 4ae73c0..0000000 --- a/OsmoBTS/chapters/bts-models.adoc +++ /dev/null @@ -1,441 +0,0 @@ -[[osmobts_hardware_support]] -== OsmoBTS hardware support - -OsmoBTS consists of a _common_ part that applies to all BTS models as well as -_hardware-specific_ parts for each BTS model. The hardware specific parts are -generally referred to as the _bts_model_ code. - -The common part includes the core BTS architecture as well as code for -implementing the external interfaces such as Abis, control, PCU socket and -GSMTAP. - -The bts_model parts include support for driving one particular -implementation of a GSM physical layer (PHY). 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. - -Every PHY implementation offers some kind of primitives by which the PHY -can be controlled, and by which the PHY exchanges data with the higher -layers of the protocol stack in the OsmoBTS code. - -The PHY-specific primitives are encapsulated in the bts_model code, and -offered as a PHY-independent _L1SAP_ interface towards the common part of -OsmoBTS. - -In addition, each bts_model implements a set of functions that the -common part calls. Those functions are pre-fixed by _bts_model__. - -Each bts_model may offer - -* model-specific VTY commands for both configuration and run-time interaction -* model-specific command line arguments -* model-specific control interface commands - -== `osmo-bts-sysmo` for sysmocom sysmoBTS - -The sysmocom sysmoBTS is a range of GSM BTSs based around an embedded -system implementing the PHY in a combination of DSP+FPGA. The PHY is -configured by a set of primitives described by header files. Those -primitives are exchanged over a set of message queues exposed on the -Linux-running ARM core via device nodes in `/dev/msgq/`. Internally, -the message queues map to shared memory between the Linux-running ARM -core and the DSP running the PHY implementation. - -The OsmoBTS bts_model code for the sysmoBTS can be found in the -`src/osmo-bts-sysmo` sub-directory of the OsmoBTS code base. - -`osmo-bts-sysmo` has been the primary target platform for -OsmoBTS for many years and is thus the most feature-complete and mature -platform supported by OsmoBTS at this point. - -The sysmoBTS PHY supports a direct PHY interface to OsmoPCU, reducing -the latency and amount of primitives that OsmoBTS would otherwise need -to pass through from the PHY message queues to the PCU socket and -vice-versa. - - -=== `osmo-bts-sysmo` specific command line arguments - -*--dsp-trace 'DSPMASK'*:: - Set the DSP trace flags (a single hexadecimal 32bit value). - This has been deprecated by VTY based commands, see - <<osmo-bts-sysmo-dsp-trace>> for further information. -*--pcu-direct*:: - Indicate that an external PCU (e.g. OsmoPCU) will directly - open the DSP message queues to the PHY / PH-SAP, and only MPH - primitives are passed via OsmoBTS. - - -=== `osmo-bts-sysmo` specific VTY commands - -For a auto-generated complete syntax reference of the VTY commands, -please see the associated _OsmoBTS VTY reference manual_ -<<vty-ref-osmobts>>. The section -below only lists the most important commands. - -==== at the 'SHOW' node - -===== `show trx 0 clock-source` - -Display the currently active clock source configuration for the TRX - -[[osmo-bts-sysmo-dsp-trace]] -===== `show trx 0 dsp-trace-flags` - -Show the currently active DSP trace flags for the TRX - -===== `trx 0 dsp-trace-flag` - -Use this command to enable/disable/configure the DSP tracing flags that -define what debug messages will appear on `/dev/rtfifo/dsp_trace`. - -==== at the 'ENABLE' node - -===== `trx 0 tx-power <-110-100>` - -Change the current TRX transmit power to the given value in dBm. - -===== `trx 0 rf-clock-info reset` - -Part of the clock calibration procedure: -Reset the clock correction value. - -===== `trx 0 rf-clock-info correct` - -Part of the clock calibration procedure: -Apply the current measured correction value between the reference clock -and the local clock. - -==== at the 'PHY instance' node - -==== `clock-calibration eeprom` - -Obtain clock calibration value from EEPROM. - -==== `clock-calibration default` - -Use hardware default clock calibration value. - -==== `clock-calibration <-4095-4095>` - -Use specified clock calibration value (not EEPROM/default). - -==== `clock-source (tcxo|ocxo|ext|gps)` - -Specify the clock source for the PHY: - -tcxo:: - Use the TCXO. This is the default on sysmoBTS 2050. -ocxo:: - Use the OCXO (only valid on units equipped with OCXO). This is - the default on all sysmoBTS 1002/1020/1100 and SOB-BTS. -ext:: - Use the external clock input. -gps:: - Use the clock derived from GPS. You shouldn't use this clock - directly, but rather use the TCXO and regularly re-calibrate - against GPS. - -==== `trx-calibration-path PATH` - -Use calibration files from the given 'PATH', rather tan calibration -values from the EEPROM. - -=== `osmo-bts-sysmo` specific control interface commands - -==== trx.0.clock-info - -Obtain information on the current clock status: - ----- -bsc_control.py -d localhost -p 4238 -g trx.0.clock-info -Got message: GET_REPLY 1 trx.0.clock-info -100,ocxo,0,0,gps ----- - -which is to be interpreted as: - -* current clock correction value is -100 ppb -* current clock source is OCXO -* deviation between clock source and calibration source is 0 ppb -* resolution of clock error measurement is 0 ppt (0 means no result yet) -* current calibration source is GPS - -When this attribute is set, any value passed on is discarded, but the clock -calibration process is re-started. - -==== trx.0.clock-correction - -This attribute can get and set the current clock correction value: - ----- -bsc_control.py -d localhost -p 4238 -g trx.0.clock-correction -Got message: GET_REPLY 1 trx.0.clock-correction -100 ----- - ----- -bsc_control.py -d localhost -p 4238 -s trx.0.clock-correction -- -99 -Got message: SET_REPLY 1 trx.0.clock-correction success ----- - - -== `osmo-bts-trx` for OsmoTRX - -OsmoTRX is a 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. - -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. - - -=== `osmo-bts-trx` specific VTY commands - -For a auto-generated complete syntax reference of the VTY commands, -pleas see the associated _OsmoBTS VTY reference manual_ -<<vty-ref-osmobts>>. The section below only lists the most important -commands. - -==== at the 'SHOW' node - -===== `show transceivers` - -Display information about configured/connected OsmoTRX transceivers in -human-readable format to current VTY session. - -==== at the 'PHY' configuration node - -===== `osmotrx ip HOST` - -Set the IP address for the OsmoTRX interface for both the local (OsmoBTS) and -remote (OsmoTRX) side of the UDP flows. This option has been deprecated by the -more detailed option `osmotrx ip (local|remote) A.B.C.D`. - -===== `osmotrx ip (local|remote) A.B.C.D` - -Set the IP address for the OsmoTRX interface for either the local (OsmoBTS) or -remote (OsmoTRX) side of the UDP flows. - -===== `osmotrx base-port (local|remote) <0-65535>` - -Configure the base UDP port for the OsmoTRX interface for either the -local (OsmoBTS) or remote (OsmoTRX) side of the UDP flows. - -===== `osmotrx fn-advance <0-30>` - -Set the number of frames to be transmitted to transceiver in advance of -current GSM frame number. - -===== `osmotrx rts-advance <0-30>` - -Set the number of frames to be requested from PCU in advance of current -frame number. Do not change this unless you have a good reason! - -===== `osmotrx rx-gain <0-50>` - -Set the receiver gain (configured in the hardware) in dB. - -===== `osmotrx tx-attenuation <0-50>` - -Set the transmitter attenuation (configured in the hardware) in dB. - -===== `osmotrx tx-attenuation oml` - -Use the Value in the A-bis OML Attribute `MAX_POWER_REDUCTION` as -transmitter attenuation. - -==== at the 'PHY Instance' configuration node - -===== `slotmask (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0)` - -Configure which timeslots should be active on this TRX. Normally all -timeslots are enabled, unless you are running on a cpu-constrained -deeply embedded system. - -===== `osmotrx maxdly <0-31>` - -Set the maximum delay for received symbols (in number of GSM symbols). - - -== `osmo-bts-octphy` for Octasic OCTPHY-2G - -The Octasic OCTPHY-2G is a GSM PHY implementation inside an Octasic -proprietary 24-core DSP called OCTDSP. - -This DSP has a built-in Gigabit Ethernet interface, over which it -exchanges PHY-layer primitives in raw Ethernet frames with the upper -layers running on another CPU attached to the same Ethernet. Those -primitives are described in a set of C-language header files. - -OsmoBTS implements the raw Ethernet frame based primitives as well as -the associated transport protocol (OKTPKT/OCTVC1) in the -`osmo-btso-octphy` bts_model code. - -You can run the `osmo-bts-octphy` on any system connected to the same -Ethernet as the OCTDSP running the OCTPHY. This can be either an -embedded ARM or x86 SoM part of the OCTBTS hardware, or it can be any -other Linux system attached via an Ethernet switch. - -Each OCTDSP running OCTSDR-2G offers a set of primitives part of a -OCTPKT session, which is mapped to an OsmoBTS PHY link. Depending on -the OCTSDR-2G software version, you may create multiple software TRX by -creating multiple OsmoBTS PHY instances inside that PHY link. - -Multiple DSPs may exist in one circuit board, then each of the DSPs is -interfaced by one OsmoBTS PHY link, and each of them may have one or -more OsmoBTS PHY instances creating a Multi-TRX configuration. - - -== `osmo-bts-litecell15` for Nutaq/Nuran LiteCell 1.5 - -The Nutaq/Nuran LiteCell 1.5 implements a dual-transceiver GSM BTS based -on a mixed ARM/DSP/FPGA architecture. The PHY layer is implemented on -DSP/FPGA and similar to that of the sysmoBTS: It exchanges primitives -described in a set of C-language header files over message queues -between the ARM and the DSP. - -This interface is implemented in the `osmo-bts-litecell15` bts_model of -OsmoBTS. You would run `osmo-bts-litecell15` on the ARM/Linux processor -of the Litecell 1.5. - -The two transceivers of the Litecell 1.5 each have their own set of DSP -message queues. Each set of message queues is wrapped into one OsmoBTS -PHY link, offering one OsmoBTS PHY instance. - -The Litecell 1.5 PHY supports a direct PHY interface to OsmoPCU, -reducing the latency and amount of primitives that OsmoBTS would -otherwise need to pass through from the PHY message queues to the PCU -socket and vice-versa. - -=== `osmo-bts-trx` specific VTY commands - -For a auto-generated complete syntax reference of the VTY commands, -please see the associated _OsmoBTS VTY reference manual_ -<<vty-ref-osmobts>>. The section below only lists the most important -commands. - -==== at the 'SHOW' node - -===== `show phy <0-255> system-information` - -Show information about the hardware platform, DSP and OCTPHY-2G software -version. - -===== `show phy <0-255> rf-port-stats <0-1>` - -Show information about the RF port interfaces. - -===== `show phy <0-255> clk-sync-stats` - -Show information about the clock synchronization manager. - -==== at the 'PHY' configuration node - -===== `octphy hw-addr HWADDR` - -Specify the Ethernet hardware address (mac address) of the DSP running -the OCTPHY-2G software for this PHY link. - -===== `octphy net-device NAME` - -Specify the Ethernet network device (like `eth0`) through which the DSP -can be reached from OsmoBTS. - -===== `octphy rf-port-index <0-255>` - -Specify which RF port should be used for this PHY link. - -===== `octphy rx-gain <0-73>` - -Configure the receiver gain in dB. - -===== `octphy tx-attenuation <0-359>` - -Configure the transmitter attenuation in quarter-dB - - - - -== `osmo-bts-virtual` for Virtual Um Interface - -This is a special BTS model used for research, simulation and testing. -Rather than communicating over a wireless RF interface, the GSM Um -messages are encapsulated over GSMTAP/UDP/IP. - -The Virtual Um interface (i.e. virtual radio layer) between OsmoBTS and -OsmocomBB allows us to run a complete GSM network with 1-N BTSs and 1-M -MSs without any actual radio hardware, which is of course excellent for -all kinds of testing scenarios. - -The Virtual Um layer is based on sending L2 frames (blocks) encapsulated -via GSMTAP UDP multicast packets. There are two separate multicast -groups, one for uplink and one for downlink. The multicast nature -simulates the shared medium and enables any simulated phone to receive -the signal from multiple BTSs via the downlink multicast group. - -In OsmoBTS, this is implemented via the `osmo-bts-virtual` BTS model. - -Setting up OsmoBTS in its `osmo-bts-virtual` flavor isn't really much -different from setting it up with real hardware. The amount of required -configuration at the BTS configuration file is (as always) very minimal, -as in the GSM network architecture provides almost all relevant -configuration to the BTS from the BSC. - -An example configuratin file is provided as part of the osmo-bts source -code: `doc/examples/virtual/osmobts-virtual.cfg` - -For more information see -http://osmocom.org/projects/cellular-infrastructure/wiki/Virtual_Um - -=== `osmo-bts-virtual` specific VTY commands - -For a auto-generated complete syntax reference of the VTY commands, -please see the associated _OsmoBTS VTY reference manual_ -<<vty-ref-osmobts>>. The section below only lists the most important -commands. - -==== at the 'PHY' config node - -===== `virtual-um net-device NETDEV` - -Configure the network device used for sending/receiving the virtual Um -interface messages (e.g. `eth0`). - -===== `virtual-um ms-udp-port <0-65535>` - -Configure the UDP port used for sending virtual Um -downlink messages towards the MS (default: GSMTAP 4729). - -===== `virtual-um ms-multicast-group GROUP` - -Configure the IP multicast group used for sending virtual -Um downlink messages towards the MS (default: 239.193.23.1) - -===== `virtual-um bts-udp-port <0-65535>` - -Configure the UDP port used for receiving virtual Um -uplink messages from the MS (default: GSMTAP 4729). - -===== `virtual-um bts-multicast-group GROUP` - -Configure the IP multicast group used for receiving virtual -Um uplink messages from the MS (default: 239.193.23.2) |