osmobsc-usermanual: Add Chapter with AoIP message flow examples

Change-Id: I001d5f85c95098269b5f129b0c53c3544b96ffb0

4 files changed, 215 insertions, 0 deletions

diff --git a/doc/manuals/chapters/aoip-flows.adoc b/doc/manuals/chapters/aoip-flows.adoc
new file mode 100644
index 000000000..dd9f809c3
--- /dev/null
+++ b/doc/manuals/chapters/aoip-flows.adoc
@@ -0,0 +1,107 @@
+== AoIP message flow examples
+
+The flow diagrams / ladder diagrams of this section are intended to
+provide some examples on how AoIP procedures work.  We hope they will be
+useful in understanding the interface better and aid in debugging any
+related issues.
+
+=== AoIP interface bring-up
+
+This Figure shows the exchange of messages of a BSC when it is
+establishing its AoIP interface from scratch, for example because it has
+just been started up.  We assume the BSC/CN has already been fully
+brought up, so no SCTP/M3U*A bring-up between MSC and STP is dieplayed.
+
+The diagram shows only one possible scenario.
+
+Depending on the MSC implementation, in between the BSC and the MSC
+there may be either
+
+* a dedicated STP (or multiple replicated STPs)
+* no dedicated STP, as the functionality is implemented inside the MSC
+* an entire SS7 network between BSC and MSC, with multiple STP, SGW,
+  elements switching messages from the BSCs to the MSCs.
+
+The configuration details that need to be known to the BSC at start-up
+time are:
+
+* at SCTP level
+** remote IP addresses to which it should establish a SCTP association
+** SCTP port number for M3UA at the STP
+* at M3UA level
+** routing key (0 for none)
+** local BSC-side SS7 point code
+** remote MSC-side SS7 point code
+
+There possibly may be more configuration details, such as
+
+* multiple local and/or remote IP addresses for SCTP multi-homing
+* a fixed local (BSC side) IP address and/or SCTP port (default:
+  dynamic/random)
+
+.AoIP interface bring-up between BSC and MSC
+[mscgen]
+----
+include::../message-sequences/a_interface_bringup.msc[]
+----
+
+For the purpose of clairty, SCTP-level acknowledgement chunks are not
+shown.  Those are automatically generated by the receiver for every
+DATA chunk received in order to confirm its reception and to allow the
+transmitter to re-transmit in case of packet loss.
+
+==== SCTP multi-homing
+
+If SCTP multi-homing is used, the additional IP addresses are typically
+exchanged via additional information elements in the INIT/INIT_ACK
+chunks at connection establishment.  They may also change at a later
+point.
+
+==== MSC pooling
+
+If there is MSC pooling configured, there is typically still only one
+M3UA ASP / SCTP association.  The different MSCs are addressed on the
+SCCP point-code level.  It's the STPs job to route the messages based
+on point codes to the respective MSC.
+
+The BSC will try to establish BSSAP to each of the MSCs in the pool,
+using a separate BSSAP reset procedure to each of the pool members
+point code.
+
+See the Chapter _MSC Pooling_ in the OsmoBSC user manual for
+configuration examples of this situation.
+
+
+=== MO call establishment on AoIP with user plane
+
+The following figure shows a simplified version of the messages between
+MS, OsmoBTS, OsmoBSC, OsmoMGW@BSC, MSC[-Server] and MSC-MGW in during
+the establishment and release of a MO voice call.  Particular focus
+is given on messages related to the establishment of the RTP based
+user plane.
+
+The fact whether or not the RAN or the CN use media gateways, how they
+control their respective media gateway, and whether there are multiple
+media gateways for load distribution is a private implementation detail
+of either RAN or CN.  Either side does not need to know the
+internal structure of the other side, since the RTP endpoint parameters
+are signaled for each call individually over the A interface.
+
+The signaling between the BSC-colocated MGW and OsmoBSC is IETF MGCP
+(Media Gateway Control Protocol).
+
+The signaling between the MSC[-Server] and the MGW is internal to the
+CN. It is typically based on MEGACO/H.248.
+
+As only the BSC and the MSC exchange 3GPP specified signaling messages,
+there is no direct interaction between the RAN and the CN side MGW.
+They only exchange RTP and associated RTCP.
+
+In many real deployments, OsmoMGW will have a different IP address on
+the BTS/Abis facing interface than on the MSC/A facing interface.  As
+a simplification, this has been omitted in the figure.
+
+[mscgen]
+----
+include::../message-sequences/mo_call-bsc-msc-mgw-aoip.msc[]
+----
diff --git a/doc/manuals/message-sequences/a_interface_bringup.msc b/doc/manuals/message-sequences/a_interface_bringup.msc
new file mode 100644
index 000000000..165262167
--- /dev/null
+++ b/doc/manuals/message-sequences/a_interface_bringup.msc
@@ -0,0 +1,31 @@
+msc {
+	hscale=2;
+	bsc[label="BSC"], stp[label="STP"], _msc[label="MSC"];
+
+	|||;
+	||| [label="We assume the MSC is already well connected to the STP and MGW(CN)"];
+
+	--- [label="SCTP/IP level establishment"];
+	bsc =>> stp [label="SCTP INIT"];
+	bsc <<= stp [label="SCTP INIT_ACK"];
+	bsc =>> stp [label="SCTP COOKIE_ECHO"];
+	bsc <<= stp [label="SCTP COOKIE_ACK"];
+	||| [label="SCTP payload can now be carried over the link"];
+	|||;
+	|||;
+	--- [label="M3UA level establishment (over SCTP)"];
+	bsc =>> stp [label="M3UA ASPUP"];
+	bsc <<= stp [label="M3UA ASPUP_ACK"];
+	bsc =>> stp [label="M3UA ASPAC (routing context)"];
+	bsc <<= stp [label="M3UA ASPAC_ACK (routing context)"];
+	bsc <<= stp [label="M3UA NTFY (AS-ACTIVE)"];
+	||| [label="M3UA payload can now be carried over the link"];
+	|||;
+	--- [label="BSSMAP level establishment (over SCCP/M3UA/SCTP)"];
+	bsc =>> _msc [label="BSSMAP RESET (OPC=BSC, DPC=MSC)"];
+	bsc <<= _msc [label="BSSMAP RESET ACK (OPC=MSC, DPC=BSC)"];
+	||| [label="BSSMAP connection-oriented data can now be exchanged"];
+	|||;
+	--- [label="Repeat BSSMAP level establishment (to other MSCs in the pool)"];
+	|||;
+}
diff --git a/doc/manuals/message-sequences/mo_call-bsc-msc-mgw-aoip.msc b/doc/manuals/message-sequences/mo_call-bsc-msc-mgw-aoip.msc
new file mode 100644
index 000000000..55fd6cd2f
--- /dev/null
+++ b/doc/manuals/message-sequences/mo_call-bsc-msc-mgw-aoip.msc
@@ -0,0 +1,75 @@
+# MO-Call with OsmoBTS + OsmoBSC with true 3GPP AoIP
+msc {
+	hscale=2;
+	ms [label="MS"], bts [label="OsmoBTS\n1.1.1.1"], bsc[label="OsmoBSC"], mgcp[label="OsmoMGW@BSC\n3.3.3.3"], m_sc[label="MSC"], mgw_m[label="MGW@MSC\n5.5.5.5"];
+
+	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 -> mgw_m	[label="Request allocation of local RTP port"];
+	m_sc <- mgw_m	[label="Respond with RTP port the MGW bound to (5.5.5.5:4000)"];
+	bsc <- m_sc 	[label="BSSAP ASSIGN REQ (3GPP AoIP, CN RTP IP/Port 5.5.5.5:4000)"];
+	bts <- bsc 	[label="RSL CHAN ACT (TCH)"];
+	bts -> bsc 	[label="RSL CHAN ACT ACK"];
+	ms <-> bsc	[label="RR Assignment of TCH"];
+	...;
+
+	# connect BTS RTP with BSC-MGW RTP
+	bts <- bsc	[label="IPA CRCX"];
+	bts box bts	[label="Bind to BTS-local RTP Port (1.1.1.1:1000)"];
+	bts -> bsc	[label="IPA CRCX ACK (1.1.1.1:1000)"];
+	bsc -> mgcp	[label="MGCP CRCX rtpbridge/2@mgw (1.1.1.1:1000)"];
+	mgcp box mgcp	[label="Bind to MGW-local RTP Port (3.3.3.3:2000)\nConnect to 1.1.1.1:1000"];
+	bsc <- mgcp	[label="MGCP CRCX rtpbridge/2@mgw OK (3.3.3.3:2000)"];
+	bts <- bsc	[label="IPA MDCX (3.3.3.3:2000)"];
+	bts box bts	[label="Connect RTP socket to remote (MGW) RTP Port"];
+	bts -> bsc	[label="IPA MDCX ACK"];
+	bsc -> mgcp	[label="MGCP MDCX rtpbridge/2@mgw (optional)"];
+	bsc <- mgcp	[label="MGCP MDCX rtpbridge/2@mgw OK (optional)"];
+	...;
+
+	mgcp <- bsc	[label="MGCP CRCX rtpbridge/2@mgw (5.5.5.5:4000)"];
+	mgcp box mgcp	[label="Bind to MGW-local RTP Port (3.3.3.3:3000)\nConnect to 5.5.5.5:4000"];
+	mgcp -> bsc	[label="MGCP CRCX rtpbridge/2@mgw OK (3.3.3.3:3000)"];
+	...;
+
+	bsc -> m_sc	[label="BSSAP ASSIGN CMPL (3GPP AoIP 3.3.3.3:3000)"];
+	m_sc -> mgw_m	[label="Request MGW to connect RTP to remote endpoint 3.3.3.3:3000"];
+	mgw_m box mgw_m [label="Connect RTP to 3.3.3.3:3000"];
+	...;
+
+	mgcp <=> mgw_m	[label="RTP Audio 3.3.3.3:3000 5.5.5.5:4000"];
+	bts <=> mgcp	[label="RTP Audio 1.1.1.1:1000 3.3.3.3: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"];
+	m_sc -> mgw_m	[label="Request release RTP port/termination"];
+	mgw_m box mgw_m	[label="Release RTP port 5.5.5.5:4000"];
+	bsc -> m_sc	[label="BSSMAP CLEAR COMPL"];
+	bsc <- m_sc	[label="SCCP RLSD"];
+	bsc -> m_sc	[label="SCCP RLC"];
+	...;
+	mgcp <- bsc	[label="MGCP DLCX rtpbridge/2@mgw"];
+	mgcp box mgcp	[label="Release MSC-facing local RTP port (3.3.3.3:3000)"];
+	mgcp -> bsc	[label="MGCP DLCX rtpbridge/2@mgw OK"];
+
+	mgcp <- bsc	[label="MGCP DLCX rtpbridge/2@mgw"];
+	mgcp box mgcp	[label="Release BTS-facing local RTP port (3.3.3.3:2000)"];
+	mgcp -> bsc	[label="MGCP DLCX rtpbridge/2@mgw OK"];
+
+	bts <- bsc	[label="IPA DLCX"];
+	bts box bts	[label="Release BTS-local RTP port (1.1.1.1:1000)"];
+	bts -> bsc	[label="IPA DLCX OK"];
+}
diff --git a/doc/manuals/osmobsc-usermanual.adoc b/doc/manuals/osmobsc-usermanual.adoc
index 3c80cee1c..a084a51be 100644
--- a/doc/manuals/osmobsc-usermanual.adoc
+++ b/doc/manuals/osmobsc-usermanual.adoc
@@ -46,6 +46,8 @@ include::{srcdir}/chapters/osmux_bsc.adoc[]
 
 include::./common/chapters/vty_cpu_sched.adoc[]
 
+include::{srcdir}/chapters/aoip-flows.adoc[]
+
 include::./common/chapters/port_numbers.adoc[]
 
 include::./common/chapters/bibliography.adoc[]