dynamic timeslots: add BSC level config instructions

Add high level description on and a config example for dynamic timeslots in a
new chapter featured in the OsmoBSC and OsmoNITB manuals.

From the OsmoBTS manual's chapter on dynamic timeslots, add references to the
above.

Change-Id: I44ff1e4c2340c65ff23e85408fc6d6a45ea9e046

2 files changed, 127 insertions, 3 deletions

diff --git a/OsmoBTS/chapters/dynamic-timeslots.adoc b/OsmoBTS/chapters/dynamic-timeslots.adoc
index 29dff5b..7c43d18 100644
--- a/OsmoBTS/chapters/dynamic-timeslots.adoc
+++ b/OsmoBTS/chapters/dynamic-timeslots.adoc
@@ -7,11 +7,14 @@ channel configurations, initiated by the BSC via (non-standard) Abis messages
 The Abis message handling for dynamic timeslots is independent of the BTS
 model. However, dynamic switchover will only work for BTS models that implement
 the internal API to reconnect a timeslot (_bts_model_ts_disconnect()_ and
-_bts_model_ts_connect()_).  Currently, these BTS models support dynamic
-timeslots:
+_bts_model_ts_connect()_, see also <<osmobts_hardware_support>>).
+
+Currently, these OsmoBTS models support dynamic timeslots:
 
 * _osmo-bts-sysmo_
 * _osmo-bts-litecell15_
 * _osmo-bts-trx_
 
-See also <<osmobts_hardware_support>>.
+Dynamic timeslots are driven by the BSC and need to be configured there. When
+using OsmoBSC or OsmoNITB, see the BTS configuration chapter on dynamic
+timeslots in <<userman-osmobsc>> or <<userman-osmonitb>>, respectively.
diff --git a/common/chapters/bts.adoc b/common/chapters/bts.adoc
index c9fda7f..80c91d6 100644
--- a/common/chapters/bts.adoc
+++ b/common/chapters/bts.adoc
@@ -267,3 +267,124 @@ Configures the remote (SGSN side) UDP port for the NS-over-UDP link.
 
 Configures the various GPRS NS related timers.  Please check the GPRS NS
 specification for the detailed meaning of those timers.
+
+
+=== Dynamic Timeslot Configuration (TCH / PDCH)
+
+A dynamic timeslot is in principle a voice timeslot (TCH) that is used to serve
+GPRS data (PDCH) when no voice call is active on it. This enhances GPRS
+bandwidth while no voice calls are active, which is dynamically scaled down as
+voice calls need to be served. This is a tremendous improvement in service over
+statically assigning a fixed number of timeslots for voice and data.
+
+Dynamic timeslots work both with OsmoNITB as well as with OsmoBSC driven by a
+third-party MSC. The causality is as follows: to establish a voice call, the
+MSC requests a logical channel of a given TCH kind from the BSC. The BSC
+assigns such a channel from a BTS' TRX's timeslot of its choice. The knowledge
+that a given timeslot is dynamic exists only on the BSC level. When the MSC
+asks for a logical channel, the BSC may switch off PDCH on a dynamic timeslot
+and then assign a logical TCH channel on it. Hence, though compatibility with
+the BTS needs to be ensured, any MSC is compatible with dynamic timeslots by
+definition.
+
+OsmoBSC and OsmoNITB support two kinds of dynamic timeslot handling, configured
+via the `network` / `bts` / `trx` / `timeslot` / `phys_chan_config`
+configuration. Not all BTS models support dynamic channels.
+
+[[dyn_ts_compat]]
+.Dynamic timeslot support by various BTS models
+[cols="50%,25%,25%"]
+|===
+|                    |`TCH/F_TCH/H_PDCH` |`TCH/F_PDCH`
+|ip.access nanoBTS   |-                  |supported
+|Ericsson RBS        |supported          |-
+|sysmoBTS using _osmo-bts-sysmo_ |supported |supported
+|various SDR platforms using _osmo-bts-trx_ |supported |supported
+|Nutaq Litecell 1.5 using _osmo-bts-litecell15_ |supported |supported
+|Octasic OctBTS using _osmo-bts-octphy_ | -  | -
+|===
+
+The _OsmoBTS Abis Protocol Specification_ <<osmobts-abis-spec>> describes the
+non-standard RSL messages used for these timeslot kinds.
+
+NOTE: Same as for dedicated PDCH timeslots, you need to enable GPRS and operate
+a PCU, SGSN and GGSN to provide the actual data service.
+
+==== Osmocom Style Dynamic Timeslots (TCH/F_TCH/H_PDCH)
+
+Timeslots of the `TCH/F_TCH/H_PDCH` type dynamically switch between TCH/F,
+TCH/H and PDCH, depending on the channel kind requested by the MSC. The RSL
+messaging for `TCH/F_TCH/H_PDCH` timeslots is compatible with Ericsson RBS.
+
+BTS models supporting this timeslot kind are shown in <<dyn_ts_compat>>.
+
+NOTE: At the time of writing, OsmoNITB disables TCH/F on this timeslot type due
+to transcoding limitations. Operation of OsmoBSC with a third-party MSC is not
+affected by this limitation. See https://osmocom.org/issues/1778.
+
+==== ip.access Style Dynamic Timeslots (TCH/F_PDCH)
+
+Timeslots of the `TCH/F_PDCH` type dynamically switch between TCH/F and PDCH.
+The RSL messaging for `TCH/F_PDCH` timeslots is compatible with ip.access
+nanoBTS.
+
+BTS models supporting this timeslot kind are shown in <<dyn_ts_compat>>.
+
+==== Avoid PDCH Exhaustion
+
+To avoid disrupting GPRS, configure at least one timeslot as dedicated PDCH.
+With only dynamic timeslots, a given number of voice calls would convert all
+timeslots to TCH, and no PDCH timeslots would be left for GPRS service.
+
+==== Dynamic Timeslot Configuration Examples
+
+This is an extract of an _osmo-nitb_ or _openbsc_ config file. A timeslot
+configuration with five Osmocom style dynamic timeslots and one dedicated PDCH
+may look like this:
+
+----
+network
+ bts 0
+  trx 0
+   timeslot 0
+    phys_chan_config CCCH+SDCCH4
+   timeslot 1
+    phys_chan_config SDCCH8
+   timeslot 2
+    phys_chan_config TCH/F_TCH/H_PDCH
+   timeslot 3
+    phys_chan_config TCH/F_TCH/H_PDCH
+   timeslot 4
+    phys_chan_config TCH/F_TCH/H_PDCH
+   timeslot 5
+    phys_chan_config TCH/F_TCH/H_PDCH
+   timeslot 6
+    phys_chan_config TCH/F_TCH/H_PDCH
+   timeslot 7
+    phys_chan_config PDCH
+----
+
+With the ip.access nanoBTS, only `TCH/F_PDCH` dynamic timeslots are supported,
+and hence a nanoBTS configuration may look like this:
+
+----
+network
+ bts 0
+  trx 0
+   timeslot 0
+    phys_chan_config CCCH+SDCCH4
+   timeslot 1
+    phys_chan_config SDCCH8
+   timeslot 2
+    phys_chan_config TCH/F_PDCH
+   timeslot 3
+    phys_chan_config TCH/F_PDCH
+   timeslot 4
+    phys_chan_config TCH/F_PDCH
+   timeslot 5
+    phys_chan_config TCH/F_PDCH
+   timeslot 6
+    phys_chan_config TCH/F_PDCH
+   timeslot 7
+    phys_chan_config PDCH
+----