BSC: Add series of message sequence charts about MGCP handling

Change-Id: Id5948677d23a58ce112b57f91bea953a93baab4c

7 files changed, 353 insertions, 1 deletions

diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile
index e12d3e283..93c7b81c5 100644
--- a/doc/manuals/Makefile
+++ b/doc/manuals/Makefile
@@ -15,13 +15,14 @@ docbooktotypes = pdf
 # htmlcss =
 
 TOPDIR := ..
-ASCIIDOCS := osmobsc-usermanual osmux-reference
+ASCIIDOCS := osmobsc-usermanual osmux-reference aoip-mgw-options
 
 include $(TOPDIR)/build/Makefile.asciidoc.inc
 include $(TOPDIR)/build/Makefile.inc
 
 osmobsc-usermanual.pdf: chapters/*.adoc
 osmux-reference.pdf: osmux-reference.adoc
+aoip-mgw-options.pdf: aoip-mgw-options.adoc
 
 clean:
 	-rm -rf $(cleanfiles)
@@ -29,6 +30,9 @@ clean:
 	-rm osmobsc-usermanual__*.svg
 	-rm osmobsc-usermanual*.check
 	-rm osmux-reference*.check
+	-rm aoip-mgw-options*.png
+	-rm aoip-mgw-options*.svg
+	-rm aoip-mgw-options*.check
 
 gen-bsc-vty-docbook: FORCE
 	$(call command,xsltproc -o generated/combined1.xml \
diff --git a/doc/manuals/aoip-mgw-options-docinfo.xml b/doc/manuals/aoip-mgw-options-docinfo.xml
new file mode 100644
index 000000000..080959443
--- /dev/null
+++ b/doc/manuals/aoip-mgw-options-docinfo.xml
@@ -0,0 +1,47 @@
+<revhistory>
+  <revision>
+    <revnumber>0.1</revnumber>
+    <date>31 May 2017</date>
+    <authorinitials>Harald Welte</authorinitials>
+    <revremark>
+       Initial version of the proposal for internal discussion.
+    </revremark>
+  </revision>
+</revhistory>
+
+<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>2017</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 the Invariant Sections being just 'Foreword',
+	'Acknowledgements' and 'Preface', with 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="http://git.osmocom.org/osmo-gsm-manuals/">
+		http://git.osmocom.org/osmo-gsm-manuals/
+	</ulink>
+  </para>
+</legalnotice>
diff --git a/doc/manuals/aoip-mgw-options.adoc b/doc/manuals/aoip-mgw-options.adoc
new file mode 100644
index 000000000..8ce3b91a5
--- /dev/null
+++ b/doc/manuals/aoip-mgw-options.adoc
@@ -0,0 +1,77 @@
+= OsmoBSC A / SCCPlite / 3GPP AoIP Options
+
+== Introduction
+
+This document serves as a paper to illustrate the different
+configurations of OsmoBSC in terms of integration with BTSs and MSCs.
+
+The document should accompany us in the 2017 development cycle which
+includes the _death of the NITB_, i.e. the move away from OsmoNITB to
+having OsmoBSC in all configurations, whether with a
+proprietary/external MSC or with OsmoMSC.
+
+Particular attention is spent on the user plane, including aspects
+such as
+
+* user plane transport address handling
+* use of MGCP (Media Gateway Control Protocol)
+* the (required) evolution of `osmo-bsc_mgcp`
+* not loosing classic TDM (E1/T1) BTS support when moving from
+  OsmoNITB to split OsmoBSC + OsmoMSC setup
+
+
+== Overview
+
+=== Classic GSM RAN with E1 based Abis and E1 A
+
+This configuration was actually never supported by OpenBSC, as E1 BTS
+support was so far for NITB only, but not for OsmoBSC.
+
+[mscgen]
+----
+include::mgw/classic-bsc.msc[]
+----
+
+=== OsmoBSC 2010-2017: IPA-style A over SCCPlite
+
+This configuration was introduced as early as 2010 in OpenBSC.  It
+allowed the use of IP based BTSs (ip.access nanoBTS as well as all the
+OsmoBTS supported BTS models) in combination with third-party MSCs
+implementing a pre-standard, proprietary way of transporting the A
+interface over IP at a time where the 3GPP specifications only allowed
+classic TDM transport.
+
+[mscgen]
+----
+include::mgw/osmo-bsc-old-sccplite.msc[]
+----
+
+
+=== OsmoBSC 2017+: 3GPP AoIP + Abis/IP
+
+Release 7 of 3GPP included an official specification on how an
+interoperable A-over-IP (AoIP) interface shall look like.
+
+As more modern MSCs at operators tend to favor implementing 3GPP AoIP
+rather than the proprietary SCCPlite based A interface, it becomes
+neccessary for OsmoBSC to support this.
+
+At the same time, for compatibility reasons, the classic SCCPlite
+support shall be kept, if possible with reasonable effort.
+
+[mscgen]
+----
+include::mgw/osmo-bsc-new-mgw.msc[]
+----
+
+
+=== OsmoBSC 2017+: 3GPP AoIP + Abis/E1
+
+Since OsmoNITB will soon be deprecated, we will use OsmoBSC in all
+Osmocom GSM ntework setups, requiring the support for classic E1/T1
+based BTSs from OsmoBSC.
+
+[mscgen]
+----
+include::mgw/osmo-bsc-new-mgw-e1.msc[]
+----
diff --git a/doc/manuals/mgw/classic-bsc.msc b/doc/manuals/mgw/classic-bsc.msc
new file mode 100644
index 000000000..56d288997
--- /dev/null
+++ b/doc/manuals/mgw/classic-bsc.msc
@@ -0,0 +1,39 @@
+# MO Call on a classic E1 Abis BTS with classic E1 A BSC
+# not actually supported by OsmoBSC (nor planned), for refrence only
+msc {
+	hscale=2;
+	ms [label="MS"], bts [label="E1 BTS"], bsc[label="OsmoBSC"], trau[label="TRAU"], m_sc[label="MSC"]; 
+
+	ms box m_sc	[label="We assume a SDCCH is already established"];
+	...;
+
+	ms -> m_sc	[label="DTAP CC SETUP"];
+	ms <- m_sc	[label="DTAP CC CALL PROCEEDING"];
+
+	bsc <- m_sc 	[label="BSSAP ASSGN REQ"];
+	bsc box m_sc	[label="E1 TS for PCM specified by CIC"];
+	bts <- bsc 	[label="RSL CHAN ACT"];
+	bts -> bsc 	[label="RSL CHAN ACT ACK"];
+	bts box bsc	[label="E1 TS + 16k sub-slot configured for given lchan"];
+	ms <-> bsc	[label="Assignment"];
+	bsc -> m_sc	[label="BSSAP ASSGN CMPL"];
+
+	...;
+	trau <- m_sc	[label="PCM Audio in full E1 slot"];
+	bts <- trau	[label="A-bis TRAU frames on 16k sub-slot"];
+
+	...;
+	ms <- m_sc	[label="DTAP CC CONNECT"];
+	ms -> m_sc	[label="DTAP CC CONNECT ACK"];
+	trau <-> m_sc	[label="PCM Audio in full E1 slot"];
+	bts <-> trau	[label="A-bis TRAU frames on 16k sub-slot"];
+	---		[label="Voice Call in Progress"];
+	ms <- m_sc	[label="DTAP CC DISCONNET"];
+	ms <- m_sc	[label="DTAP CC RELEASE"];
+	ms <- m_sc	[label="DTAP CC RELEASE COMPL"];
+	...;
+	bsc <- m_sc	[label="BSSMAP CLEAR CMD"];
+	bsc -> m_sc	[label="BSSMAP CLEAR COMPL"];
+	bsc <- m_sc	[label="SCCP RLSD"];
+	bsc -> m_sc	[label="SCCP RLC"];
+}
diff --git a/doc/manuals/mgw/osmo-bsc-new-mgw-e1.msc b/doc/manuals/mgw/osmo-bsc-new-mgw-e1.msc
new file mode 100644
index 000000000..7912a73f5
--- /dev/null
+++ b/doc/manuals/mgw/osmo-bsc-new-mgw-e1.msc
@@ -0,0 +1,50 @@
+# MO-Call with E1 BTS + OsmoBSC with true 3GPP AoIP (planned
+# osmo-bsc_mgcp has to be extended to true MGW functionality!
+msc {
+	hscale=2;
+	ms [label="MS"], bts [label="E1 BTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-bsc_mgcp"], m_sc[label="MSC"];
+
+	ms box m_sc	[label="We assume a SDCCH is already established"];
+	...;
+
+	ms -> m_sc	[label="DTAP CC SETUP"];
+	ms <- m_sc	[label="DTAP CC CALL PROCEEDING"];
+
+	m_sc box m_sc	[label="Bind arbitrary local port (4000)"];
+	bsc <- m_sc 	[label="BSSAP ASSGN REQ (3GPP AoIP MSC:4000)"];
+	bts <- bsc 	[label="RSL CHAN ACT"];
+	bts -> bsc 	[label="RSL CHAN ACT ACK"];
+	ms <-> bsc	[label="Assignment"];
+	...;
+
+	mgcp <- bsc	[label="MGCP CRCX ts1/ss2@abis (MSC:4000)"];
+	mgcp box mgcp	[label="Bind to MGW-local RTP Port (3000)\nConnect to MSC:4000"];
+	mgcp -> bsc	[label="MGCP CRCX ts1/ss2@a OK (MGW:3000)"];
+	...;
+
+	bsc -> m_sc	[label="BSSAP ASSGN CMPL (3GPP AoIP MGW:3000)"];
+	m_sc box m_sc	[label="Connect remote RTP to MGW addr from ASSGN CMPL"];
+	...;
+
+	mgcp <=> m_sc	[label="RTP Audio MGW:3000 MSC:4000"];
+	bts <=> mgcp	[label="TRAU Frame Audio (E1 TS1 SS2)"];
+	ms <=> bts	[label="Um Audio (bidirectional)"];
+	ms <-> m_sc	[label="DTAP CC ALERTING"];
+	...;
+
+	ms <- m_sc	[label="DTAP CC CONNECT"];
+	ms -> m_sc	[label="DTAP CC CONNECT ACK"];
+	---		[label="Voice Call in Progress"];
+	ms <- m_sc	[label="DTAP CC DISCONNET"];
+	ms <- m_sc	[label="DTAP CC RELEASE"];
+	ms <- m_sc	[label="DTAP CC RELEASE COMPL"];
+	...;
+	bsc <- m_sc	[label="BSSMAP CLEAR CMD"];
+	bsc -> m_sc	[label="BSSMAP CLEAR COMPL"];
+	bsc <- m_sc	[label="SCCP RLSD"];
+	bsc -> m_sc	[label="SCCP RLC"];
+	...;
+	mgcp <- bsc	[label="MGCP DLCX ts1/ss2@a"];
+	mgcp box mgcp	[label="Release MSC-facing local RTP port (3000)"];
+	mgcp -> bsc	[label="MGCP DLCX ts1/ss2@a OK"];
+}
diff --git a/doc/manuals/mgw/osmo-bsc-new-mgw.msc b/doc/manuals/mgw/osmo-bsc-new-mgw.msc
new file mode 100644
index 000000000..2bab84dec
--- /dev/null
+++ b/doc/manuals/mgw/osmo-bsc-new-mgw.msc
@@ -0,0 +1,71 @@
+# MO-Call with OsmoBTS + OsmoBSC with true 3GPP AoIP (planned)
+msc {
+	hscale=2;
+	ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-bsc_mgcp"], m_sc[label="MSC"];
+
+	ms box m_sc	[label="We assume a SDCCH is already established"];
+	...;
+
+	ms -> m_sc	[label="DTAP CC SETUP"];
+	ms <- m_sc	[label="DTAP CC CALL PROCEEDING"];
+
+	m_sc box m_sc	[label="Bind arbitrary local port (4000)"];
+	bsc <- m_sc 	[label="BSSAP ASSGN REQ (3GPP AoIP MSC:4000)"];
+	bts <- bsc 	[label="RSL CHAN ACT"];
+	bts -> bsc 	[label="RSL CHAN ACT ACK"];
+	ms <-> bsc	[label="Assignment"];
+	...;
+
+	# connect BTS RTP with BSC-MGW RTP
+	bts <- bsc	[label="IPA CRCX"];
+	bts box bts	[label="Bind to BTS-local RTP Port (1000)"];
+	bts -> bsc	[label="IPA CRCX ACK (BTS:1000)"];
+	bsc -> mgcp	[label="MGCP CRCX 2@abis (BTS:1000)"];
+	mgcp box mgcp	[label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000"];
+	bsc <- mgcp	[label="MGCP CRCX 2@abis OK (MGW:2000)"];
+	bts <- bsc	[label="IPA MDCX 2@abis (MGW:2000)"];
+	bts box bts	[label="Connect RTP socket to remote (MGW) RTP Port"];
+	bts -> bsc	[label="IPA MDCX 2@abis ACK"];
+	#bsc -> mgcp	[label="MGCP MDCX 2@abis (optional)"];
+	#bsc <- mgcp	[label="MGCP MDCX 2@abis OK (optional)"];
+	...;
+
+	mgcp <- bsc	[label="MGCP CRCX 1@a (MSC:4000)"];
+	mgcp box mgcp	[label="Bind to MGW-local RTP Port (3000)\nConnect to MSC:4000"];
+	mgcp -> bsc	[label="MGCP CRCX 1@a OK (MGW:3000)"];
+	...;
+
+	bsc -> m_sc	[label="BSSAP ASSGN CMPL (3GPP AoIP MGW:3000)"];
+	m_sc box m_sc	[label="Connect remote RTP to MGW addr from ASSGN CMPL"];
+	...;
+
+	mgcp <=> m_sc	[label="RTP Audio MGW:3000 MSC:4000"];
+	bts <=> mgcp	[label="RTP Audio BTS:1000 MGW:2000"];
+	ms <=> bts	[label="Um Audio (bidirectional)"];
+	ms <-> m_sc	[label="DTAP CC ALERTING"];
+	...;
+
+	ms <- m_sc	[label="DTAP CC CONNECT"];
+	ms -> m_sc	[label="DTAP CC CONNECT ACK"];
+	---		[label="Voice Call in Progress"];
+	ms <- m_sc	[label="DTAP CC DISCONNET"];
+	ms <- m_sc	[label="DTAP CC RELEASE"];
+	ms <- m_sc	[label="DTAP CC RELEASE COMPL"];
+	...;
+	bsc <- m_sc	[label="BSSMAP CLEAR CMD"];
+	bsc -> m_sc	[label="BSSMAP CLEAR COMPL"];
+	bsc <- m_sc	[label="SCCP RLSD"];
+	bsc -> m_sc	[label="SCCP RLC"];
+	...;
+	mgcp <- bsc	[label="MGCP DLCX 1@a"];
+	mgcp box mgcp	[label="Release MSC-facing local RTP port (3000)"];
+	mgcp -> bsc	[label="MGCP DLCX 1@a OK"];
+
+	bsc -> mgcp	[label="MGCP DLCX 2@abis"];
+	mgcp box mgcp	[label="Release BTS-facing local RTP port (2000)"];
+	bsc <- mgcp	[label="MGCP DLCX 2@abis OK"];
+
+	bts <- bsc	[label="IPA DLCX"];
+	bts box bts	[label="Release BTS-local RTP port (1000)"];
+	bts -> bsc	[label="IPA DLCX OK"];
+}
diff --git a/doc/manuals/mgw/osmo-bsc-old-sccplite.msc b/doc/manuals/mgw/osmo-bsc-old-sccplite.msc
new file mode 100644
index 000000000..f7298bfac
--- /dev/null
+++ b/doc/manuals/mgw/osmo-bsc-old-sccplite.msc
@@ -0,0 +1,64 @@
+# MO-Call with OsmoBTS + OsmoBSC using A/IP with IPA/SCCPlite
+# Supported since 2010 using osmo-bsc + osmo-bsc_nat
+msc {
+	hscale=2;
+	ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-bsc_mgcp"], m_sc[label="MSC"]; 
+
+	ms box m_sc	[label="We assume a SDCCH is already established"];
+	...;
+
+	ms -> m_sc	[label="DTAP CC SETUP"];
+	ms <- m_sc	[label="DTAP CC CALL PROCEEDING"];
+
+	bsc <- m_sc 	[label="BSSAP ASSGN REQ"];
+	bts <- bsc 	[label="RSL CHAN ACT"];
+	bts -> bsc 	[label="RSL CHAN ACT ACK"];
+	ms <-> bsc	[label="Assignment"];
+	bsc -> m_sc	[label="BSSAP ASSGN CMPL"];
+
+	...;
+	bts <- bsc	[label="IPA CRCX"];
+	bts box bts	[label="Bind to BSC-local RTP Port"];
+	bts -> bsc	[label="IPA CRCX ACK"];
+	bts <- bsc	[label="IPA MDCX"];
+	bts box bts	[label="Connect RTP socket to remote (bsc_mgcp) RTP Port"];
+	bts -> bsc	[label="IPA MDCX ACK"];
+
+	mgcp <- m_sc	[label="MGCP CRCX"];
+	mgcp box mgcp	[label="Bind to BTS-local RTP Port"];
+	mgcp -> m_sc	[label="MGCP CRCX OK"];
+	mgcp <- m_sc	[label="MGCP MDCX (recvonly) "];
+	mgcp box mgcp	[label="Connect RTP socket to remote (MSC) RTP Port"];
+	mgcp -> m_sc	[label="MGCP MDCX OK"];
+	mgcp <= m_sc	[label="RTP Audio"];
+	bts <= mgcp	[label="RTP Audio"];
+	ms <= bts	[label="Um Audio (unidirectional)"];
+	ms <- m_sc	[label="DTAP CC ALERTING"];
+
+	...;
+	mgcp <- m_sc	[label="MGCP MDCX (sndrecv) "];
+	mgcp box mgcp	[label="Switch to bi-directional audio"];
+	mgcp -> m_sc	[label="MGCP MDCX OK"];
+	mgcp <=> m_sc	[label="RTP Audio"];
+	bts <=> mgcp	[label="RTP Audio"];
+	ms <=> bts	[label="Um Audio (bidirectional)"];
+	...;
+	ms <- m_sc	[label="DTAP CC CONNECT"];
+	ms -> m_sc	[label="DTAP CC CONNECT ACK"];
+	mgcp <- m_sc	[label="MGCP MDCX (sndrecv) "];
+	mgcp box mgcp	[label="Why?"];
+	mgcp -> m_sc	[label="MGCP MDCX OK"];
+	---		[label="Voice Call in Progress"];
+	ms <- m_sc	[label="DTAP CC DISCONNET"];
+	ms <- m_sc	[label="DTAP CC RELEASE"];
+	ms <- m_sc	[label="DTAP CC RELEASE COMPL"];
+	...;
+	bsc <- m_sc	[label="BSSMAP CLEAR CMD"];
+	bsc -> m_sc	[label="BSSMAP CLEAR COMPL"];
+	bsc <- m_sc	[label="SCCP RLSD"];
+	bsc -> m_sc	[label="SCCP RLC"];
+	...;
+	mgcp <- m_sc	[label="MGCP DLCX"];
+	mgcp box mgcp	[label="Release local RTP port"];
+	mgcp -> m_sc	[label="MGCP DLCX OK"];
+}