Cell Broadcast: CBSP and CBCH scheduling support

This adds code to handle CBSP (Cell Broadcast Service Protocol)
from the CBC (Cell Broadcast Centre), as well as BSC-internal data
structures for scheduling the various SMSCB on the CBCH of each BTS.

There are currently one known shortcoming in the code: We don't yet
verify if keepalives are received within repetition period.

Change-Id: Ia0a0de862a104d0f447a5d6e56c7c83981b825c7

3 files changed, 160 insertions, 5 deletions

diff --git a/doc/manuals/chapters/smscb.adoc b/doc/manuals/chapters/smscb.adoc
new file mode 100644
index 000000000..f7469a375
--- /dev/null
+++ b/doc/manuals/chapters/smscb.adoc
@@ -0,0 +1,82 @@
+[[smscb]]
+== SMSCB (Cell Broadcast)
+
+OsmoBSC supports SMS Cell Broadcast (SMSCB) services (CBS).  This
+includes the CBSP protocol to interact with a CBC (Cell Broadcast
+Centre) such as OsmoCBC, as well as the scheduling of SMSCB messages on
+both the BASIC and EXTENDED CBCH and transmission of related RSL
+messages to the attached BTS.
+
+More high-level information can be found at
+https://en.wikipedia.org/wiki/Cell_Broadcast and the related
+specification is <<3gpp-ts-23-041>>.
+
+In order to use SMSCB with OsmoBSC, you will need to
+
+* Configure the CBSP server and/or client
+* Use a channel combination including a CBCH on the BTSs
+
+=== Enabling a CBCH channel combination
+
+On the Um interface, SMSCB are transmitted via the CBCH (Cell Broadcast
+Channel).  The CBCH is a separate downlink-only logical channel which
+must be activated on any of the BTSs requiring CBSP support.
+
+The channel combination is configured in the `timeslot` node of each TRX.
+
+The two `phys_chan_config` supporting CBCH are `CCCH+SDCCH4+CBCH` and
+`SDCCH/8+CBCH`.  Please note that the CBCH steals one of the SDCCH, so
+a SDCCH/4 will only have three remaining SDCCH, and a SDCCH/8 will
+have only seven remaining SDCCH.
+
+=== Configuring the CBSP connection
+
+CBSP is the protocol between BSC and CBC.  It operates over TCP.
+
+According to 3GPP TS 48.049, a BSC typically operates as a TCP server,
+and the CBC connects as TCP client.  This would require the CBC to have
+out-of-band knowledge of all the BSCs in the network (and their IP
+addresses).
+
+In order to comply with the specifications, OsmoBSC supports this mode
+of operation as CBSP TCP server.  However, to make network operation and
+configuration more simple, it also can operate in TCP client mode,
+connecting to the CBC.  This way the all the BSCs need to know is the CBC IP
+address, but not vice-versa.
+
+The BSC can operate both CBSP TCP server and CBSP TCP client mode in
+parallel.
+
+The CBC related configuration of OsmoBSC can be found in the `cbc` configuration
+node of the VTY interface.
+
+.Example: Configure CBSP TCP client to connect to CBC at 1.2.3.4:48049
+----
+OsmoBSC> enable
+OsmoBSC# configure terminal
+OsmoBSC(config)# cbc
+OsmoBSC(config-cbc)# remote-ip 1.2.3.4
+OsmoBSC(config-cbc)# remote-port 48049
+OsmoBSC(config-cbc)# end
+----
+
+.Example: Disable CBSP TCP client
+----
+OsmoBSC> enable
+OsmoBSC# configure terminal
+OsmoBSC(config)# cbc
+OsmoBSC(config-cbc)# no remote-ip
+OsmoBSC(config-cbc)# end
+----
+
+.Example: Configure CBSP TCP server to listen for CBC at 127.0.0.2:9999
+----
+OsmoBSC> enable
+OsmoBSC# configure terminal
+OsmoBSC(config)# cbc
+OsmoBSC(config-cbc)# listen-ip 127.0.0.2
+OsmoBSC(config-cbc)# listen-port 9999
+OsmoBSC(config-cbc)# end
+----
+
+For more details on the available configuration commands, please check the OsmoBSC VTY Reference.
diff --git a/doc/manuals/osmobsc-usermanual.adoc b/doc/manuals/osmobsc-usermanual.adoc
index 766a11f40..26f49da03 100644
--- a/doc/manuals/osmobsc-usermanual.adoc
+++ b/doc/manuals/osmobsc-usermanual.adoc
@@ -24,6 +24,8 @@ include::./common/chapters/bsc.adoc[]
 
 include::{srcdir}/chapters/handover.adoc[]
 
+include::{srcdir}/chapters/smscb.adoc[]
+
 include::./common/chapters/counters-overview.adoc[]
 
 include::{srcdir}/chapters/counters.adoc[]
@@ -34,8 +36,6 @@ include::./common/chapters/control_if.adoc[]
 
 include::{srcdir}/chapters/control.adoc[]
 
-include::./common/chapters/cell-broadcast.adoc[]
-
 include::{srcdir}/chapters/osmux_bsc.adoc[]
 
 include::./common/chapters/port_numbers.adoc[]
diff --git a/doc/manuals/vty/bsc_vty_reference.xml b/doc/manuals/vty/bsc_vty_reference.xml
index 85c0cb7e7..6a3e4fb57 100644
--- a/doc/manuals/vty/bsc_vty_reference.xml
+++ b/doc/manuals/vty/bsc_vty_reference.xml
@@ -320,7 +320,7 @@
         <param name='MASK' doc='List of logging categories to log, e.g. &apos;abc:mno:xyz&apos;. Available log categories depend on the specific application, refer to the &apos;logging level&apos; command. Optionally add individual log levels like &apos;abc,1:mno,3:xyz,5&apos;, where the level numbers are LOGL_DEBUG=1 LOGL_INFO=3 LOGL_NOTICE=5 LOGL_ERROR=7 LOGL_FATAL=8' />
       </params>
     </command>
-    <command id='logging level (rll|mm|rr|rsl|nm|pag|meas|msc|ho|hodec|ref|nat|ctrl|filter|pcu|lcls|chan|ts|as|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats|lgsup|loap|lss7|lsccp|lsua|lm3ua|lmgcp|ljibuf|lrspro) (debug|info|notice|error|fatal)'>
+    <command id='logging level (rll|mm|rr|rsl|nm|pag|meas|msc|ho|hodec|ref|nat|ctrl|filter|pcu|lcls|chan|ts|as|cbs|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats|lgsup|loap|lss7|lsccp|lsua|lm3ua|lmgcp|ljibuf|lrspro) (debug|info|notice|error|fatal)'>
       <params>
         <param name='logging' doc='Configure logging' />
         <param name='level' doc='Set the log level for a specified category' />
@@ -343,6 +343,7 @@
         <param name='chan' doc='lchan FSM' />
         <param name='ts' doc='timeslot FSM' />
         <param name='as' doc='assignment FSM' />
+        <param name='cbs' doc='Cell Broadcast System' />
         <param name='lglobal' doc='Library-internal global log family' />
         <param name='llapd' doc='LAPD in libosmogsm' />
         <param name='linp' doc='A-bis Intput Subsystem' />
@@ -514,6 +515,22 @@
         <param name='all' doc='Display a list of all FSM instances of all finite state machine' />
       </params>
     </command>
+    <command id='show cbc'>
+      <params>
+        <param name='show' doc='Show running system information' />
+        <param name='cbc' doc='Display state of CBC / CBSP' />
+      </params>
+    </command>
+    <command id='show bts &lt;0-255&gt; smscb [(basic|extended)]'>
+      <params>
+        <param name='show' doc='Show running system information' />
+        <param name='bts' doc='Display information about a BTS' />
+        <param name='&lt;0-255&gt;' doc='BTS number' />
+        <param name='smscb' doc='SMS Cell Broadcast State' />
+        <param name='[basic]' doc='Show only information related to CBCH BASIC' />
+        <param name='[extended]' doc='Show only information related to CBCH EXTENDED' />
+      </params>
+    </command>
     <command id='show statistics'>
       <params>
         <param name='show' doc='Show running system information' />
@@ -971,7 +988,7 @@
         <param name='MASK' doc='List of logging categories to log, e.g. &apos;abc:mno:xyz&apos;. Available log categories depend on the specific application, refer to the &apos;logging level&apos; command. Optionally add individual log levels like &apos;abc,1:mno,3:xyz,5&apos;, where the level numbers are LOGL_DEBUG=1 LOGL_INFO=3 LOGL_NOTICE=5 LOGL_ERROR=7 LOGL_FATAL=8' />
       </params>
     </command>
-    <command id='logging level (rll|mm|rr|rsl|nm|pag|meas|msc|ho|hodec|ref|nat|ctrl|filter|pcu|lcls|chan|ts|as|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats|lgsup|loap|lss7|lsccp|lsua|lm3ua|lmgcp|ljibuf|lrspro) (debug|info|notice|error|fatal)'>
+    <command id='logging level (rll|mm|rr|rsl|nm|pag|meas|msc|ho|hodec|ref|nat|ctrl|filter|pcu|lcls|chan|ts|as|cbs|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats|lgsup|loap|lss7|lsccp|lsua|lm3ua|lmgcp|ljibuf|lrspro) (debug|info|notice|error|fatal)'>
       <params>
         <param name='logging' doc='Configure logging' />
         <param name='level' doc='Set the log level for a specified category' />
@@ -994,6 +1011,7 @@
         <param name='chan' doc='lchan FSM' />
         <param name='ts' doc='timeslot FSM' />
         <param name='as' doc='assignment FSM' />
+        <param name='cbs' doc='Cell Broadcast System' />
         <param name='lglobal' doc='Library-internal global log family' />
         <param name='llapd' doc='LAPD in libosmogsm' />
         <param name='linp' doc='A-bis Intput Subsystem' />
@@ -1356,6 +1374,16 @@
         <param name='all' doc='Display a list of all FSM instances of all finite state machine' />
       </params>
     </command>
+    <command id='show bts &lt;0-255&gt; smscb [(basic|extended)]'>
+      <params>
+        <param name='show' doc='Show running system information' />
+        <param name='bts' doc='Display information about a BTS' />
+        <param name='&lt;0-255&gt;' doc='BTS number' />
+        <param name='smscb' doc='SMS Cell Broadcast State' />
+        <param name='[basic]' doc='Show only information related to CBCH BASIC' />
+        <param name='[extended]' doc='Show only information related to CBCH EXTENDED' />
+      </params>
+    </command>
     <command id='show statistics'>
       <params>
         <param name='show' doc='Show running system information' />
@@ -1735,6 +1763,11 @@
         <param name='e1_input' doc='Configure E1/T1/J1 TDM input' />
       </params>
     </command>
+    <command id='cbc'>
+      <params>
+        <param name='cbc' doc='Configure CBSP Link to Cell Broadcast Centre' />
+      </params>
+    </command>
     <command id='msc [&lt;0-1000&gt;]'>
       <params>
         <param name='msc' doc='Configure MSC details' />
@@ -1833,7 +1866,7 @@
         <param name='[last]' doc='Log source file info at the end of a log line. If omitted, log source file info just before the log text.' />
       </params>
     </command>
-    <command id='logging level (rll|mm|rr|rsl|nm|pag|meas|msc|ho|hodec|ref|nat|ctrl|filter|pcu|lcls|chan|ts|as|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats|lgsup|loap|lss7|lsccp|lsua|lm3ua|lmgcp|ljibuf|lrspro) (debug|info|notice|error|fatal)'>
+    <command id='logging level (rll|mm|rr|rsl|nm|pag|meas|msc|ho|hodec|ref|nat|ctrl|filter|pcu|lcls|chan|ts|as|cbs|lglobal|llapd|linp|lmux|lmi|lmib|lsms|lctrl|lgtp|lstats|lgsup|loap|lss7|lsccp|lsua|lm3ua|lmgcp|ljibuf|lrspro) (debug|info|notice|error|fatal)'>
       <params>
         <param name='logging' doc='Configure logging' />
         <param name='level' doc='Set the log level for a specified category' />
@@ -1856,6 +1889,7 @@
         <param name='chan' doc='lchan FSM' />
         <param name='ts' doc='timeslot FSM' />
         <param name='as' doc='assignment FSM' />
+        <param name='cbs' doc='Cell Broadcast System' />
         <param name='lglobal' doc='Library-internal global log family' />
         <param name='llapd' doc='LAPD in libosmogsm' />
         <param name='linp' doc='A-bis Intput Subsystem' />
@@ -4930,4 +4964,43 @@
       </params>
     </command>
   </node>
+  <node id='config-cbc'>
+    <name>config-cbc</name>
+    <command id='remote-ip A.B.C.D'>
+      <params>
+        <param name='remote-ip' doc='IP Address of the Cell Broadcast Centre' />
+        <param name='A.B.C.D' doc='IP Address of the Cell Broadcast Centre' />
+      </params>
+    </command>
+    <command id='no remote-ip'>
+      <params>
+        <param name='no' doc='Negate a command or set its defaults' />
+        <param name='remote-ip' doc='Remove IP address of CBC; disables outbound CBSP connections' />
+      </params>
+    </command>
+    <command id='remote-port &lt;1-65535&gt;'>
+      <params>
+        <param name='remote-port' doc='TCP Port number of the Cell Broadcast Centre (Default: 48049)' />
+        <param name='&lt;1-65535&gt;' doc='TCP Port number of the Cell Broadcast Centre (Default: 48049)' />
+      </params>
+    </command>
+    <command id='listen-port &lt;1-65535&gt;'>
+      <params>
+        <param name='listen-port' doc='Local TCP port at which BSC listens for incoming CBSP connections from CBC' />
+        <param name='&lt;1-65535&gt;' doc='Local TCP port at which BSC listens for incoming CBSP connections from CBC' />
+      </params>
+    </command>
+    <command id='no listen-port'>
+      <params>
+        <param name='no' doc='Negate a command or set its defaults' />
+        <param name='listen-port' doc='Remove CBSP Listen Port; disables inbound CBSP connections' />
+      </params>
+    </command>
+    <command id='listen-ip A.B.C.D'>
+      <params>
+        <param name='listen-ip' doc='Local IP Address where BSC listens for incoming CBC connections (Default: 0.0.0.0)' />
+        <param name='A.B.C.D' doc='Local IP Address where BSC listens for incoming CBC connections' />
+      </params>
+    </command>
+  </node>
 </vtydoc>