doc/manuals/chapters/configuration.adoc

== Configuring OsmoPCU

Contrary to other network elements (like OsmoBSC, OsmoNITB), the
OsmoPCU has a relatively simple minimum configuration.

This is primarily because most of the PCU configuration happens
indirectly from the BSC, who passes the configuation over A-bis OML via
OsmoBTS and its PCU socket into OsmoPCU.

A minimal OsmoPCU configuration file is provided below for your reference:

.Example: Minimal OsmoPCU configuration file (`osmo-pcu.cfg`)
----
pcu
 flow-control-interval 10 <1>
 cs 2 <2>
 alloc-algorithm dynamic <3>
 gamma 0
----
<1> send a BSSGP flow-control PDU every 10 seconds
<2> start a TBF with the initial coding scheme 2
<3> dynamically chose between single-slot or multi-slot TBF allocations
    depending on system load

However, there are plenty of tuning parameters for people interested to
optimize PCU throughput or latency according to their requirements.

=== Configuring the Coding Schemes and Rate Adaption

As a reminder:

- GPRS supports Coding Schemes 1-4 (CS1-4), all of them use GMSK modulation
  (same as GSM).
- EGPRS supports MCS1-9, where MCS1-4 is GMSK, and MCS5-9 use 8-PSK modulation.

The range of Coding Schemes above only apply to RLCMAC data blocks; RLCMAC
control blocks are always transmitted with CS1 (GMSK). Hence, CS1 is always
supported and must be always permitted.

The BSC includes a bit-mask of permitted [E]GPRS coding schemes as part of the
A-bis OML configuration, controlled by VTY `gprs mode (none|gprs|egprs)`.  This
is passed from the BTS via the PCU socket into OsmoPCU, and the resulting set
can be further constrained by OsmoPCU VTY configuration.

Some additional OsmoPCU parameters can be set as described below.

==== Initial Coding Scheme

You can use the `cs <1-4> [<1-4>]` command at the `pcu` VTY config node
to set the initial GPRS coding scheme to be used.  The optional second
value allows to specify a different initial coding scheme for uplink.

Similarly, `mcs <1-9> [<1-9>]` can be used to set up the initial EGPRS coding
scheme.

[[max_cs_mcs]]
==== Maximum Coding Scheme

You can use the `cs max <1-4> [<1-4>]` command at the `pcu` VTY config
node to set the maximum GPRS coding scheme that should be used as part of the
rate adaption.  The optional second value allows to specify a different maximum
coding scheme for uplink.

Similarly, `mcs max <1-9> [<1-9>]` can be used to set up the maximum EGPRS
coding scheme.

The actual Maximum Coding Scheme for each direction used at runtime is actually
the result of taking the maximum value from the permitted GPRS coding schemes
received by the BSC (or BTS) over PCUIF which is equal or lower tho the
configured value.

Example: PCUIF announces permitted MCS bit-mask (`MCS1 MCS2 MCS3 MCS4`) and
OsmoPCU is configured `mcs max 6`, then the actual maximum MCS used at runtime
will be `MCS4`.

==== Rate Adaption Error Thresholds

You can use the `cs threshold <0-100> <0-100>` command at the `pcu` VTY
config node to determine the upper and lower limit for the error rate
percentage to use in the rate adaption.  If the upper threshold is
reached, a lower coding sheme is chosen, and if the lower threshold is
reached, a higher coding scheme is chosen.

==== Rate Adation Link Quality Thresholds

You can use the `cs link-quality-ranges cs1 <0-35> cs2 <0-35> <0-35> cs3
<0-35> <0-35> cs4 <0-35>` command at the `pcu` VTY config node to tune
the link quality ranges for the respective coding schemes.

==== Data Size based CS downgrade Threshold

You can use the `cs downgrade-threshold <1-10000>` command at the `pcu`
VTY config node to ask the PCU to down-grade the coding scheme if less
than the specified number of octets are left to be transmitted.

=== Miscellaneous Configuration / Tuning Parameters

==== Downlink TBF idle time

After a down-link TBF is idle (all data in the current LLC downlink
queue for the MS has been transmitted), we can keep the TBF established
for a configurable time.  This avoids having to go through a new one or
two phase TBF establishment once the next data for downlink arrives.

You can use the `dl-tbf-idle-time <1-5000>` to specify that time in
units of milli-seconds.  The default is 2 seconds.

==== MS idle time

Using the `ms-idle-time <1-7200>` command at the `pcu` VTY config node
you can configure the number of seconds for which the PCU should keep
the MS data structure alive before releasing it if there are no active
TBF for this MS.

The OsmoPCU default value is 60 seconds, which is slightly more than
what 3GPP TS 24.008 recommends for T3314 (44s).

The MS data structure only consumes memory in the PCU and does not
require any resources of the air interface.

==== Forcing two-phase access

If the MS is using a single-phase access, you can still force it to
use a two-phase access using the `two-phase-access` VTY configuration
command at the `pcu` VTY config node.

=== Configuring BSSGP flow control

BSSGP between SGSN and PCU contains a two-level nested flow control
mechanism:

. one global flow control instance for the overall (downlink) traffic
  from the SGSN to this PCU
. a per-MS flow control instance for each individual MS served by this
  PCU

Each of the flow control instance is implemented as a TBF (token bucket
filter).

==== Normal BSSGP Flow Control Tuning parameters

You can use the following commands at the `pcu` VTY config node to tune
the BSSGP flow control parameters:

`flow-control-interval <1-10>`::
	configure the interval (in seconds) between subsequent flow
	control PDUs from PCU to SGSN
`flow-control bucket-time <1-65534>`::
	set the target downlink maximum queueing time in centi-seconds.
	The PCU will attempt to adjust the advertised bucket size to match this
	target.

==== Extended BSSGP Flow Control Tuning parameters

There are some extended flow control related parameters at the `pcu` VTY
config node that override the automatic flow control as specified in the
BSSGP specification.  Use them with care!

`flow-control force-bvc-bucket-size <1-6553500>`::
	force the BVC (global) bucket size to the given number of octets
`flow-control force-bvc-leak-rate <1-6553500>`::
	force the BVC (global) bucket leak rate to the given number of bits/s
`flow-control force-ms-bucket-size <1-6553500>`::
	force the per-MS bucket size to the given number of octets
`flow-control force-ms-leak-rate <1-6553500>`::
	force the per-MS bucket leak rate to the given number of bits/s


=== Configuring LLC queue

The downlink LLC queue in the PCU towards the MS can be tuned with a
variety of parameters at the `pcu` VTY config node, depending on your
needs.

`queue lifetime <1-65534>`::
	Each downlink LLC PDU is assigned a lifetime by the SGSN, which
	is respected by the PDU *unless* you use this command to
	override the PDU lifetime with a larger value (in centi-seconds)
`queue lifetime infinite`::
	Never drop LLC PDUs, i.e. give them an unlimited lifetime.
`queue hysteresis <1-65535>`::
	When the downlink LLC queue is full, the PCU starts dropping
	packets.  Using this parameter, we can set the lifetime
	hysteresis in centi-seconds, i.e. it will continue discarding
	until "lifetime - hysteresis" is reached.
`queue codel`::
	Use the 'CoDel' (Controlled Delay) scheduling algorithm, which
	is designed to overcome buffer bloat.  It will use a default
	interval of 4 seconds.
`queue codel interval <1-1000>`::
	Use the 'CoDel' (Controlled Delay) scheduling algorithm, which
	is designed to overcome buffer bloat.  Use the specified
	interval in centi-seconds.
`queue idle-ack-delay <1-65535>`::
	Delay the request for an ACK after the last downlink LLC frame
	by the specified amount of centi-seconds.


=== Configuring MS power control

GPRS MS power control works completely different than the close MS power
control loop in circuit-switched GSM.

Rather than instructing the MS constantly about which transmit power to
use, some parameters are provided to the MS by which the MS-based power
control algorithm is tuned.

See 3GPP TS 05.08 for further information on the algorithm and the
parameters.

You can set those parameters at the `pcu` VTY config node as follows:

`gamma <0-62>`::
	Set the gamma parameter for MS power control in units of dB.

Parameter `ALPHA` is set on the BSC VTY configuration file on a per-BTS basis,
and forwarded by OsmoPCU to the MS through the SI13 received from the former
over PCUIF. OsmoPCU VTY command `alpha <0-10>` overrides the value received over
PCUIF to keep backward compatibility with existing config files, but it is
currently deprecated and its use is discouraged; one should configure it per-BTS
in OsmoBSC VTY instead.

=== Configuring Network Assisted Cell Change (NACC)

Network Assisted Cell Change, defined in 3GPP TS 44.060 sub-clause 8.8, is a
feature providing the MS aid when changing to a new cell due to autonomous
reselection. In summary, the MS informs the current cell its intention to change
to a new target cell, and the network decides whether to grant the intended cell
change or order a change to another neighbor cell. It also provides several
System Informations of the target cell to the MS to allow for quicker
reselection towards it.

OsmoPCU will automatically provide the required neighbor System Information when
the MS requests NACC towards a target cell also under the management of the same
OsmoPCU instance, since it already has the System Information of all BTS under
their control, obtained through PCUIF when the BTS registers against OsmoPCU, so
no specific user configuration is required here.

In general, OsmoPCU requires to gather the information from somewhere else
before being able to provide it to the MS requesting the NACC.

If OsmoPCU fails to gather the System Information, it will simply answer the MS
allowing the proposed changed but without previously providing the System
Information of the target cell.

==== Neighbor Address Resolution

First of all, it needs to translate the <ARFCN + BSIC> identity of the target
cell to change to, provided by the MS, into an identity that the Core Network
can use and understand to identify the target cell, which happens to be a key
composed of <RAI + Cell Identity>. This key is also named conveniently as
CGI-PS, since it actually equals to the Circuit Switch CGI + RAC.

In order to apply this target cell identity translation, OsmoPCU uses the
OsmoBSC Neighbor Resolution Service. This service is nowadays provided by means
of PCUIF container messages, which are transparently forwarded in both directions
by the BTS using the IPA multiplex of the OML connection against the BSC. No
specific configuration is required in any of the involved nodes, they should
behave properly out of the box.

These neighbor address resolutions (<ARFCN + BSIC> => <RAI + CI>) are by default
cached for a while, in order to avoid querying the BSC frequently. As a result,
the resolution time is also optimized.

.Example: Configure Neighbor Resolution cache and timeouts
----
pcu
 timer X1 500 <1>
 timer X0 60 <2>
----
<1> Time out if the BSC doesn't answer our resolution request after 500 ms
<2> Keep resolved neighbor addresses cached for 60 seconds

===== OsmoBSC CTRL interface (deprecated)

CAUTION: This interface is nowadays considered deprecated and should not be used
anymore. Any related VTY options should be dropped from configuration files, to
let OsmoPCU use the new interface instead. This section is kept here for a while
as a reference for old deployments using old versions of the programs.

This Neighbor Address Resolution Service was initially implemented by means of a
separate CTRL interface (see OsmoBSC User Manual), where OsmoPCU would create a
CTRL connection to the BSC each time an address resolution was required.

Older versions of OsmoBSC may not support the current Neighbor Address
Resolution Service over the IPA multiplex (see above). For those cases, OsmoPCU
can be configured to use the old deprecated CTRL interface.

By default, the use of this interface is not configured and hence disabled in
OsmoPCU. As a result, until configured, the network won't be able to provide the
System Information to the MS prior to allowing the change during NACC against
remote cells, which means the cell change will take longer to complete. In order
to configure the interface, the OsmoBSC IP address and port to connect to must
be configured in OsmoPCU VTY.

.Example: Configure Neighbor Resolution CTRL interface against OsmoBSC
----
pcu
 neighbor resolution 172.18.13.10 4248 <1>
----
<1> Port 4248 is the default and hence could be omitted in this case

==== System Information Resolution

Once OsmoPCU gains knowledge of the target cell's address in the Core Network,
it can query its System Information.

OsmoPCU will gather the requested System Information of target cells under its
control without need for any external query, since the System Information of all
BTSs it manages are received over PCUIF and stored internally in OsmoPCU.

For those targets cells not managed by the OsmoPCU instance, the query is
accomplished by using RIM procedures (NACC RAN-INFO application) over the Gb
interface against the SGSN that OsmoPCU is connected to. In its turn, the SGSN
will potentially forward this query to the PCU serving the target cell, which
will provide back the System Information of that cell.

The System Information received from external PCUs over RIM are by default
cached for a while in order to avoid querying the SGSN frequently and, as a
result, optimizing the resolution time too.

.Example: Configure System Information resolution
----
pcu
 timer X2 500 <1>
 timer X11 60 <2>
----
<1> Time out if the SGSN doesn't answer our RIM RAN-INFO request request after 500 ms
<2> Keep resolved remote neighbor System Information cached for 60 seconds

[[cfg_e1_line]]
=== Configuring E1 line for CCU access

Depending on the configuration the PCU may require direct access to a BTS CCU
(channel coding unit) via an E1 line. This is in particular the case when
OsmoPCU runs in co-location with OsmoBSC.

The exact timeslot configuration is passed to the PCU via the pcu_sock
interface. Only basic E1 line settings are required. However, it is important
that the E1 line number is the same as the E1 line number that is used in the
timeslot configuration of OsmoBSC.

.Example: Configure an E1 line
----
e1_input
 e1_line 0 driver dahdi
 e1_line 0 port 2
 no e1_line 0 keepalive
----

=== GPRS vs EGPRS considerations

==== Configuration

OsmoPCU can be configured to either:

- Allocate only GPRS TBFs to all MS (no EGPRS)
- Allocate EGPRS TBFs to EGPRS capable phones while still falling back to
  allocating GPRS TBFs on GPRS-only capable MS.

These two different modes of operation are selected by properly configuring the
Coding Schemes (see <<max_cs_mcs>>).

The first mode of operation (GPRS-only for all MS) can be accomplished
configuring OsmoPCU so that the resulting MCS set is empty. This can be done in
two ways:

- Announcing an empty MCS bit-mask over PCUIF to OsmoPCU:
  That's actually done automatically by OsmoBSC on BTS with VTY config set to
  `gprs mode gprs`.
- Configuring OsmoPCU to force an empty set by using VTY command `mcs max 0`.

Hence, if the resulting MCS bit-mask is not empty, (BSC configuring the BTS with
`gprs mode egprs` and OsmoPCU VTY containing something other than 'mcs max 0'),
EGPRS TBFs will be allocated for all MS announcing EGPRS capabilities.

It is important to remark that in order to use MCS5-9, the BTS must support
8-PSK modulation. Nevertheless, in case 8-PSK is not supported by the BTS, one
can still enable EGPRS and simply make sure 8-PSK MCS are never used by
configuring OsmoPCU with `mcs max 4 4`.

Similarly, a BTS may support 8-PSK modulation only on downlink, since it is
easier to implement than the uplink, together with the fact that higher downlink
throughput is usually more interesting from user point of view. In this
scenario, OsmoPCU can be configured to allow for full MCS range in downlink
while still preventing use of 8-PSK on the uplink: `mcs max 9 4`.

Some other interesting configurations to control use of EGPRS in the network
which lay outside OsmoPCU include:

- If `osmo-bts-trx` together with `osmo-trx` is used, remember to enable EGPRS
  support (OsmoTRX VTY `egprs enable`).

- It is possible to improve EGPRS performance (in particular, the TBF
  establishment timing) a bit by enabling 11-bit Access Burst support. This
  allows EGPRS capable phones to indicate their EGPRS capability, establishment
  cause, and multi-slot class directly in the Access Burst (OsmoTRX VTY
  `ext-rach enable`, OsmoBSC VTY `gprs egprs-packet-channel-request`).

NOTE: If you enable MCS5-9 you will also need an 8-PSK capable OsmoBTS+PHY,
which means `osmo-bts-sysmo` or `osmo-bts-litecell15` with their associated PHY,
or `osmo-bts-trx` with `osmo-trx` properly configured.

==== GPRS+EGPRS multiplexing

Both EGPRS and GPRS-only capable MS can be driven concurrently in the same PDCH
timeslot by the PCU, hence no special configuration is required per timeslot
regarding this topic; OsmoPCU scheduler takes care of the specific requirements
when driving MS with different capabilities.

These specific requirements translate to some restrictions regarding which
Coding Schemes can be used at given frame numbers, and hence which kind of
RLCMAC blocks can be sent, which means serving a GPRS-only MS in a PDCH may end
up affecting slightly the downlink throughput of EGPRS capable MS.

Throughput loss based on MS capabilities with TBF attached to a certain PDCH
timeslot:

All UEs are EGPRS capable::
 No throughput loss, since all data is sent using EGPRS, and EGPRS control
 messages are used when appropriate.

All UEs are GPRS-only (doesn't support EGPRS)::
 No throughput loss, since all data and control blocks use GPRS.

Some UEs are GPRS-only, some EGPRS::
In general EGPRS capable UEs will use EGPRS, and GPRS-only UEs will use GPRS,
with some restrictions affecting throughput of EGPRS capable UEs:
- Whenever a GPRS-only MS is to be polled to send uplink data to PCU, then a
downlink RLCMAC block modulated using GMSK must be sent, which means that if the
scheduler selects a EGPRS MS for downlink on that block it will force sending of
data with MCS1-4 (if it's new data, if it's a retransmission it cannot be
selected since MCS from original message cannot be changed). In the worst case
if no control block needs to be sent or no new data in MCS1-4 is available to
send, then an RLCMAC Dummy Block is sent.
- For synchronization purposes, each MS needs to receive an RLCMAC block which
it can fully decode at least every 360ms, which means the scheduler must enforce
a downlink block in CS1-4 every 360ms, that is, every 18th RLCMAC block. In
general this is not a big issue since anyway all control RLCMAC blocks are
encoded in CS1, so in case any control block is sent from time to time it's
accomplished and there's no penalty. However, if only EGPRS downlink data is sent
over that time frame, then the scheduler will force sending a RLCMAC Dummy
Block.

[[gsmtap]]
=== Configuring GSMTAP tracing

In addition to being able to obtain pcap protocol traces of the NS/BSSGP
communication and the text-based logging from the OsmoPCU software, there is
also the capability of tracing all communication on the radio interface related
to PS. To do so, OsmoPCU can encapsulate MAC blocks (23-155 byte messages at the
L2-L1 interface depending on coding scheme) into _GSMTAP_ and send them via
UDP/IP. At that point, they can be captured with utilities like *tcpdump* or
*tshark* for further analysis by the *wireshark* protocol analyzer.

In order to activate this feature, you first need to make sure to specify
the remote address of _GSMTAP_ host in the configuration file.  In most
cases, using 127.0.0.1 for passing the messages over the loopback (`lo`)
device will be sufficient:

.Example: Enabling GSMTAP Um-frame logging to localhost
----
pcu
 gsmtap-remote-host 127.0.0.1 <1>
----
<1> Destination address for _GSMTAP_ Um-frames

NOTE: Changing this parameter at run-time will not affect the existing
_GSMTAP_ connection, full program restart is required.

NOTE: Command line parameters `-i` and `--gsmtap-ip` have been deprecated.

OsmoPCU can selectively trace such messages based on different categories, for
both Ul and Dl. For a complete list of cateogry values, please refer to the
_OsmoPCU VTY reference manual_ <<vty-ref-osmopcu>>.

For example, to enable GSMTAP tracing for all DL EGPRS rlcmac data blocks, you
can use the `gsmtap-category dl-data-egprs` command at the `pcu` node of the
OsmoPCU VTY.

.Example: Enabling  GSMTAP for for all DL EGPRS rlcmac data blocks
----
OsmoPCU> enable
OsmoPCU# configure terminal
OsmoPCU(config)# pcu
OsmoPCU(pcu)# gsmtap-category dl-data-egprs
OsmoPCU(trx)# write <1>
----
<1> the `write` command will make the configuration persistent in the
configuration file.  This is not required if you wish to enable GSMTAP
only in the current session of OsmoPCU.

De-activation can be performed similarly by using the `no gsmtap-category
dl-data-egprs` command at the `pcu` node of the OsmoPCU VTY.

It may be useful to enable all categories with a few exceptions, or vice versa
disable everything using one command.  For this purpose, the VTY provides
`gsmtap-category enable-all` and `gsmtap-category disable-all` commands.

.Example: Enabling all categoriess except _dl-dummy_
----
pcu
 gsmtap-category enable-all <1>
 no gsmtap-category dl-dummy <2>
----
<1> Enable all available SAPIs
<2> Exclude DL RLCMAC blocks

From the moment they are enabled via VTY, GSMTAP messages will be
generated and sent in UDP encapsulation to the IANA-registered UDP port
for GSMTAP (4729) of the specified remote address.