Add new Manual "OsmoBSC CBSP Protocol Specification"

This document decribes the level of CBSP support in the codebase.

Related: SYS#5945

Change-Id: I2e18e167281fac3abaf380089ff883738ebaa0a0

5 files changed, 266 insertions, 1 deletions

diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
index c86f21563..8b2a8eff9 100644
--- a/doc/manuals/Makefile.am
+++ b/doc/manuals/Makefile.am
@@ -1,10 +1,13 @@
 EXTRA_DIST = aoip-mgw-options.adoc \
     aoip-mgw-options-docinfo.xml \
+    osmobsc-cbsp.adoc \
+    osmobsc-cbsp-docinfo.xml \
     osmobsc-usermanual.adoc \
     osmobsc-usermanual-docinfo.xml \
     osmobsc-vty-reference.xml \
     osmux-reference.adoc \
     osmux-reference-docinfo.xml \
+    cbsp \
     chapters \
     message-sequences \
     mgw \
@@ -13,9 +16,10 @@ EXTRA_DIST = aoip-mgw-options.adoc \
     vty
 
 if BUILD_MANUALS
-  ASCIIDOC = osmobsc-usermanual.adoc osmux-reference.adoc aoip-mgw-options.adoc
+  ASCIIDOC = osmobsc-usermanual.adoc osmobsc-cbsp.adoc osmux-reference.adoc aoip-mgw-options.adoc
   include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
   osmobsc-usermanual.pdf: $(srcdir)/chapters/*.adoc $(srcdir)/chapters/*.dot
+  osmobsc-cbsp.pdf: $(srcdir)/cbsp/*.adoc #$(srcdir)/cbsp/*.dot $(srcdir)/abis/*.msc
   aoip-mgw-options.pdf: $(srcdir)/aoip-mgw-options.adoc $(srcdir)/mgw/*.msc
 
   VTY_REFERENCE = osmobsc-vty-reference.xml
diff --git a/doc/manuals/cbsp/messages.adoc b/doc/manuals/cbsp/messages.adoc
new file mode 100644
index 000000000..d595b958f
--- /dev/null
+++ b/doc/manuals/cbsp/messages.adoc
@@ -0,0 +1,73 @@
+== CBSP Messages
+
+=== List of Messages
+
+The following tables list the CBSP messages used by OsmoBSC BSC-CBC interface,
+grouped by their level of compliance with 3GPP TS 48.049.
+
+==== Messages Compliant With TS 48.049
+
+Specific additions and limitations apply, see the linked sections.
+
+.Messages compliant with TS 48.049
+[options="header",cols="10%,20%,45%,5%,20%"]
+|===
+| TS 48.049 § | This document § | Message | <-/-> | Received/Sent by OsmoBSC
+| 8.1.3.1  | - | WRITE-REPLACE | <- | Received
+| 8.1.3.2  | - | WRITE-REPLACE COMPLETE | -> | Sent
+| 8.1.3.3  | - | WRITE-REPLACE FAILURE | -> | Sent
+| 8.1.3.4  | - | KILL | <- | Received
+| 8.1.3.5  | - | KILL COMPLETE | -> | Sent
+| 8.1.3.6  | - | KILL FAILURE | -> | Sent
+| 8.1.3.10 | - | MESSAGE STATUS QUERY | <- | Received
+| 8.1.3.11 | - | MESSAGE STATUS QUERY COMPLETE | -> | Sent
+| 8.1.3.12 | - | MESSAGE STATUS QUERY FAILURE | -> | Sent
+| 8.1.3.16 | - | RESET | <- | Received
+| 8.1.3.17 | - | RESET COMPLETE | -> | Sent
+| 8.1.3.18 | <<RESET_FAILURE>> | RESET FAILURE | -> | Sent
+| 8.1.3.18a | <<KEEP_ALIVE>> | KEEP-ALIVE | <- | Received
+| 8.1.3.18b | - | KEEP-ALIVE COMPLETE | -> | Sent
+| 8.1.3.19 | <<RESTART>> | RESTART | -> | Sent
+|===
+
+==== Messages Not Implemented by OsmoBSC
+
+.3GPP TS 48.049 messages not implemented by OsmoBSC
+[options="header",cols="30%,45%,5%,20%"]
+|===
+| TS 48.049 § | Message | <-/-> | Received/Sent by OsmoBSC
+| 8.1.3.7  | LOAD QUERY | <- | Received
+| 8.1.3.8  | LOAD QUERY COMPLETE | -> | Sent
+| 8.1.3.9  | LOAD QUERY FAILURE | -> | Sent
+| 8.1.3.13 | SET-DRX | <- | Received
+| 8.1.3.14 | SET-DRX COMPLETE | -> | Sent
+| 8.1.3.15 | SET-DRX FAILURE | -> | Sent
+| 8.1.3.20 | FAILURE | -> | Sent
+| 8.1.3.21 | ERROR INDICATION | -> | Sent
+|===
+
+
+=== Message Limitation Details
+
+[[RESET_FAILURE]]
+==== RESET FAILURE
+
+Encoding of this message is implemented, but there is currently no
+condition in the OsmoBSC code that would make a RESET operation fail on
+an existing cell, except if the CBC were to identify
+a non-existent cell in its _Cell List IE_.
+
+[[KEEP_ALIVE]]
+==== KEEP-ALIVE
+
+The message is received and generates a corresponding KEEP-ALIVE
+COMPLETE answer.  However, the _Keep Alive Repetition Period IE_ is not
+interpreted.
+
+[[RESTART]]
+==== RESTART
+
+The RESTART message is sent only at the time of establishment of every
+CBSP link.  It is not sent when subsequent cells become available during
+runtime of the CBSP link.
+
diff --git a/doc/manuals/cbsp/procedures.adoc b/doc/manuals/cbsp/procedures.adoc
new file mode 100644
index 000000000..192014916
--- /dev/null
+++ b/doc/manuals/cbsp/procedures.adoc
@@ -0,0 +1,83 @@
+== CBSP Procedures
+
+=== List of Procedures
+
+The following tables list the CBSP procedures used by the OsmoBSC BSC-CBC interface,
+grouped by their level of compliance with 3GPP TS 48.049.
+
+==== Procedures Compliant With TS 48.049
+
+Specific additions and limitations apply, see the linked sections.
+
+.Procedures compliant with TS 48.049
+[options="header",cols="10%,20%,40%,30%"]
+|===
+| TS 48.049 § | This document § | Procedure | Originated/Terminated by OsmoBSC
+| 7.2 | <<PROC_WRITE_REPLACE>> | Write-Replace | Terminated
+| 7.3 | - | Kill | Terminated
+| 7.5 | - | Message Status Query | Terminated
+| 7.7a | <<PROC_KEEP_ALIVE>> | Keep Alive | Terminated
+| 7.8 | <<RESTART_IND>> | Restart Indication | Originated
+|===
+
+
+[[PROC_WRITE_REPLACE]]
+===== Write-Replace
+
+Procedures for _Write_ and _Replace_ of CBS messages as per 3GPP TS 48.049 Section 7.2.2.2
+are fully supported.
+
+Procedures for _Write_ and _Replace_ of ETWS messages as per 3GPP TS
+48.059 Section 7.2.2.2 are fully supported.  Transmission of the ETWS
+Primary Notification is implemented as follows, assuming related support
+is present in the related BTS and PCU software (true for OsmoBTS >= 1.2.0
+and OsmoPCU >= 0.8.0):
+
+* broadcast to MS in idle mode / packet idle mode by sending a
+  vendor-specific A-bis RSL message to each affected BTS.  A
+  vendor-specific mechanism is needed as 3GPP TS 48.058 does not specify
+  any standard message for this.  See the section on _Osmocom ETWS
+  Command_ in <<osmobts-abis-spec>> for more details.
+* broadcast to MS in dedicated mode by sending the ETWS PN via every
+  currently active dedicated channel (SDCCH, FACCH) within the affected
+  BTSs.
+
+As an additional clarification to 3GPP TS 48.049, OsmoBSC rejects (via
+WRITE-REPLACE FAILURE) any _write_ procedure for an emergency message if
+there already is another emergency message active in a cell.  The
+_replace_ procedure must be used (by specifying the _Old Serial Number
+IE_) if the only existing emergency message of a cell shall be replaced.
+
+[[PROC_KEEP_ALIVE]]
+===== Keep-Alive
+
+The Keep-Alive procedure is implemented only in as far as incoming
+Keep-Alive requests are responded to.
+
+The BSC currently does not use the _Keep Alive Repetition Period IE_.
+This is permitted as 3GPP TS 48.049 states the information _may_ be used
+by the BSC.
+
+[[PROC_RESTART_IND]]
+===== Restart Indication
+
+Restart indications are currently only sent whenever any BSC-CBC link is
+established.  They are not sent once subsequent cells become available
+or are re-initialized due to A-bis link failure.
+
+However, CBSP state for both CBS and Emergency messages is kept
+persistent in the BSC and if cells reboot / restart during the duration
+of a CBS / emergency message, they will resume broadcasts as expected.
+
+
+==== Procedures Not Implemented by OsmoBSC
+
+.3GPP TS 48.049 procedures not implemented by OsmoBSC
+[options="header",cols="30%,40%,30%"]
+|===
+| TS 48.049 § | Procedure | Originated/Terminated by OsmoBSC
+| 7.4 | Load Status Enquiry | Terminated
+| 7.6 | Set DRX | Terminated
+| 7.9 | Failure Indication | Originated
+| 7.10 | Error Indication | Originated
+|===
diff --git a/doc/manuals/osmobsc-cbsp-docinfo.xml b/doc/manuals/osmobsc-cbsp-docinfo.xml
new file mode 100644
index 000000000..a86fd286e
--- /dev/null
+++ b/doc/manuals/osmobsc-cbsp-docinfo.xml
@@ -0,0 +1,36 @@
+
+<authorgroup>
+  <author>
+    <firstname>Harald</firstname>
+    <surname>Welte</surname>
+    <email>hwelte@sysmocom.de</email>
+    <authorinitials>HW</authorinitials>
+    <affiliation>
+      <shortaffil>sysmocom</shortaffil>
+      <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+      <jobtitle>Managing Director</jobtitle>
+    </affiliation>
+  </author>
+</authorgroup>
+
+<copyright>
+  <year>2022</year>
+  <holder>sysmocom - s.f.m.c. GmbH</holder>
+</copyright>
+
+<legalnotice>
+  <para>
+	Permission is granted to copy, distribute and/or modify this
+	document under the terms of the GNU Free Documentation License,
+	Version 1.3 or any later version published by the Free Software
+	Foundation; with no Invariant Sections, no Front-Cover Texts,
+	and no Back-Cover Texts.  A copy of the license is included in
+	the section entitled "GNU Free Documentation License".
+  </para>
+  <para>
+	The Asciidoc source code of this manual can be found at
+	<ulink url="https://git.osmocom.org/osmo-bsc/">
+		https://git.osmocom.org/osmo-bsc/
+	</ulink>
+  </para>
+</legalnotice>
diff --git a/doc/manuals/osmobsc-cbsp.adoc b/doc/manuals/osmobsc-cbsp.adoc
new file mode 100644
index 000000000..89af8dfcc
--- /dev/null
+++ b/doc/manuals/osmobsc-cbsp.adoc
@@ -0,0 +1,69 @@
+:gfdl-enabled:
+
+OsmoBSC CBSP Protocol Specification
+===================================
+Harald Welte <hwelte@sysmocom.de>
+
+== Introduction
+
+This document describes the CBSP interface of *OsmoBSC* as spoken on the
+BSC-CBC interface. Based on 3GPP TS 48.049 <<3gpp-ts-48-049>>, this document indicates
+which of the 3GPP specified CBSP messages and IEs are implemented
+according to 3GPP specifications, which of these are not or not fully
+implemented, as well as OsmoBSC-specific extensions to the CBSP
+interface not specified by 3GPP.
+
+For details on the standard CBSP messages and IE definitions,
+please refer to the 3GPP documents.
+
+.3GPP document versions referred to by this document
+[cols="20%,80%"]
+|===
+|3GPP TS 48.049 | version 12.0.0 Release 12
+|===
+
+.IETF documents referred to by his document
+[cols="20%,80%"]
+|===
+|IETF RFC 793 | Transmission Control Protocol
+|===
+
+== Overview
+
+The OsmoBSC BSC-CBC interface consists of CBSP messages transmitted over
+TCP.
+
+The default TCP destination port number is TCP port 48049; this can be
+changed by configuration, as described in the OsmoBSC user manual
+<<userman-osmobsc>> and/or VTY reference manual <<vty-ref-osmobsc>>.
+
+.TCP port numbers used by OsmoBTS Abis/IP
+[options="header",width="50%",cols="35%,65%"]
+|===
+|TCP Port Number|Usage
+|48049|CBSP
+|===
+
+OsmoBSC implements both _TCP server_ and _TCP client_ role; it is hence
+configurable whether the CBC establishes the TCP connection to the BSC
+(BSC in _TCP server_ role) or if the BSC establishes the TCP connection
+to the CBC (BSC in _TCP client_ role).
+
+Currently, only transport of TCP via IPv4 is implemented.
+
+Any IP-capable link-layer protocol implemented in the underlying Linux
+operating system can be used to transport the IP/TCP/CBSP of OsmoBSC.
+
+
+include::{srcdir}/cbsp/procedures.adoc[]
+
+include::{srcdir}/cbsp/messages.adoc[]
+
+
+include::./common/chapters/port_numbers.adoc[]
+
+include::./common/chapters/bibliography.adoc[]
+
+include::./common/chapters/glossary.adoc[]
+
+include::./common/chapters/gfdl.adoc[]