summaryrefslogtreecommitdiffstats
path: root/OsmoBTS/chapters/bts-models.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'OsmoBTS/chapters/bts-models.adoc')
-rw-r--r--OsmoBTS/chapters/bts-models.adoc441
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)