485 lines
17 KiB
Plaintext
485 lines
17 KiB
Plaintext
[[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.
|
|
|
|
GSM is a TDMA (time division multiple access) system on the radio
|
|
interface. OsmoTRX is the "clock master" of that in the Osmocom
|
|
implementation. It informs OsmoBTS of the current GSM frame
|
|
number. However, as there is non-zero delays (UDP packet trnsmission
|
|
delay, operating system scheduler delay on both OsmoTRX and OsmoBTS
|
|
side, ...), OsmoBTS must compensate for that delay by "advancing"
|
|
the clock a certain amount of time.
|
|
|
|
In other words, if OsmoTRX informs us that the current frame number is N,
|
|
we advance it by `fn-advance` and transmit burst data for
|
|
`N + fn-advance` towards OsmoTRX.
|
|
|
|
The fn-advance should be kept as low as possible to avoid additional
|
|
delays to the user voice plane as well as to improve the performance
|
|
of the control plane (LAPDm) as well as GPRS.
|
|
|
|
However, fn-advance must be kept sufficiently high to ensure no
|
|
underruns on the OsmoTRX side.
|
|
|
|
The detailed value will depend on your underlying computer systems,
|
|
operating system and related tuning parameters. Running OsmoTRX
|
|
on a remote host will inevitably require a higher fn-advance then
|
|
running it on the same machine, where the UDP packetes are just passed
|
|
over the loopback device.
|
|
|
|
The default value for `fn-advance` is 20 (corresponding to 92
|
|
milliseconds).
|
|
|
|
===== `osmotrx rts-advance <0-30>`
|
|
|
|
Set the number of frames to be requested from L1SAP in advance of current
|
|
frame number and fn-advance.
|
|
|
|
The value specified as `rts-advance` is added to the current GSM frame
|
|
number as reported by OsmoTRX *and* the `osmotrx fn-advance` in order
|
|
to generate the PH-RTS.ind (ready to send indications) across the L1SAP
|
|
interface inside osmo-bts. This will trigger the Layer 2 (LAPDm for
|
|
the control plane, RTP for the voice plane, and OsmoPCU for GPRS) to
|
|
generate a MAC block and input it into the osmo-bts-trx TDMA scheduler.
|
|
|
|
If OsmoTRX reported N as the current frame number, the actual frame number
|
|
reported on L1SAP to higher layers will be computed as follows:
|
|
|
|
N + fn-advance + rts-advance
|
|
|
|
The default value of `rts-advance` is 5 (corresponding to 23 milliseconds).
|
|
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 configuration 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)
|