gbproxy-usermanual: Explain BSSGP/BVC handling

Related: SYS#5005
Change-Id: I383fcd3864a94177f13909c6b8c15648900d3201

3 files changed, 121 insertions, 5 deletions

diff --git a/doc/manuals/chapters/gbproxy-details.adoc b/doc/manuals/chapters/gbproxy-details.adoc
new file mode 100644
index 000000000..f77d40cf9
--- /dev/null
+++ b/doc/manuals/chapters/gbproxy-details.adoc
@@ -0,0 +1,113 @@
+[[chapter_details]]
+== Proxy details
+
+=== BVC handling
+
+This section describes in more detail how BVCs are handled in OsmoGbProxy
+
+If a BSS connects to OsmoGbProxy while the SGSN is not available it will
+acknowledge the BVC RESET on the signalling BVC, but ignore other messages
+(especially any PTP BVC RESET).
+
+.BSS connects to OsmoGbProxy
+[mscgen]
+----
+msc {
+    hscale="1.8";
+    bss1 [label="BSS1"], bss2 [label="BSS2"], gbproxy [label="GbProxy"], sgsn [label="SGSN"];
+    bss1 <=> gbproxy [label="NS link available"];
+    bss1 => gbproxy [label="BVC RESET (BVCI=0)"];
+    gbproxy => bss1 [label="BVC RESET ACK"];
+    bss1 -x gbproxy [label="PTP BVC RESET (ignored)"];
+}
+----
+
+As soon as the SGSN is reachable through NS OsmoGbProxy will send a BVC RESET
+to the signalling BVC towards the SGSN. After that completes it will reset the
+signalling BVC of all BSS connections. At this point the BSS will send a BVC
+RESET for its PTP BVCs which will be forwarded to the SGSN, similarly the PTP
+BVC RESET ACK from the SGSN will be sent back to the BSS.
+
+.SGSN connection to OsmoGbProxy
+[mscgen]
+----
+msc {
+    hscale="1.8";
+    bss1 [label="BSS1"], bss2 [label="BSS2"], gbproxy [label="GbProxy"], sgsn [label="SGSN"];
+    gbproxy <=> sgsn [label="NS link available"];
+    gbproxy => sgsn [label="BVC RESET (BVCI=0)"];
+    sgsn => gbproxy [label="BVC RESET ACK"];
+
+    gbproxy => bss1 [label="BVC RESET (BVCI=0)"];
+    bss1 => gbproxy [label="BVC RESET ACK"];
+    bss1 box bss1 [label="PTP BVCs need to be reset"];
+    bss1 => gbproxy [label="PTP BVC RESET (BVCI=x)"];
+    gbproxy => sgsn [label="PTP BVC RESET (BVCI=x)"];
+    sgsn => gbproxy [label="PTP BVC RESET ACK (BVCI=x)"];
+    gbproxy => bss1 [label="PTP BVC RESET ACK (BVCI=x)"];
+    bss2 <=> sgsn [label="BVCI x established"];
+}
+----
+
+The communication on the PTP BVC will then be forwarded between the BSS and the
+SGSN.
+
+If a BSS connects while the SGSN is up the PTP BVC RESET will directly be
+forwarded.
+
+.BSS connects to OsmoGbProxy
+[mscgen]
+----
+msc {
+    hscale="1.8";
+    bss1 [label="BSS1"], bss2 [label="BSS2"], gbproxy [label="GbProxy"], sgsn [label="SGSN"];
+    bss2 <=> gbproxy [label="NS link available"];
+    bss2 => gbproxy [label="BVC RESET (BVCI=0)"];
+    gbproxy => bss2 [label="BVC RESET ACK"];
+    bss2 => gbproxy [label="PTP BVC RESET (BVCI=y)"];
+    gbproxy => sgsn [label="PTP BVC RESET (BVCI=y)"];
+    sgsn => gbproxy [label="PTP BVC RESET ACK (BVCI=y)"];
+    gbproxy => bss2 [label="PTP BVC RESET ACK (BVCI=y)"];
+    bss2 <=> sgsn [label="BVCI y established"];
+}
+----
+
+If OsmoGbProxy looses the connection to the SGSN it will reset the signalling
+BVC of all BSS connections. This ensures that the BSS will not send traffic
+over a PTP BVC before its reset procedure has been completed.
+
+.SGSN connection fails
+[mscgen]
+----
+msc {
+    hscale="1.8";
+    bss1 [label="BSS1"], bss2 [label="BSS2"], gbproxy [label="GbProxy"], sgsn [label="SGSN"];
+    gbproxy <=> sgsn [label="NS link fails"];
+    gbproxy => bss1 [label="BVC RESET (BVCI=0)"];
+    gbproxy => bss2 [label="BVC RESET (BVCI=0)"];
+}
+----
+
+When the connection to the SGSN is eventually restored the signalling BVC
+between OsmoGbProxy and SGSN will be reset.
+
+After that completes OsmoGbProxy will reset the signalling BVC on all BSS NS
+connections and forward the PTP BVC RESET messages.
+
+.SGSN connection restored
+[mscgen]
+----
+msc {
+    hscale="1.8";
+    bss1 [label="BSS1"], bss2 [label="BSS2"], gbproxy [label="GbProxy"], sgsn [label="SGSN"];
+    gbproxy <=> sgsn [label="NS link available"];
+    gbproxy => sgsn [label="BVC RESET (BVCI=0)"];
+    sgsn => gbproxy [label="BVC RESET ACK"];
+    gbproxy => bss1 [label="BVC RESET (BVCI=0)"];
+    bss1 => gbproxy [label="BVC RESET ACK"];
+    bss1 box bss1 [label="PTP BVCs need to be reset"];
+    gbproxy => bss2 [label="BVC RESET (BVCI=0)"];
+    bss2 => gbproxy [label="BVC RESET ACK"];
+    bss2 box bss2 [label="PTP BVCs need to be reset"];
+}
+----
diff --git a/doc/manuals/chapters/gbproxy-overview.adoc b/doc/manuals/chapters/gbproxy-overview.adoc
index 580afae61..1564157ad 100644
--- a/doc/manuals/chapters/gbproxy-overview.adoc
+++ b/doc/manuals/chapters/gbproxy-overview.adoc
@@ -1,18 +1,18 @@
 [[chapter_overview]]
 == Overview
 
-=== About OsmoGbPROXY
+=== About OsmoGbProxy
 
-OsmoGbPROXY is the Osmocom proxy for the 3GPP Gb interface.  The Gb
+OsmoGbProxy is the Osmocom proxy for the 3GPP Gb interface.  The Gb
 interface is defined by 3GPP as the protocol between the BSS and the
 SGSN inside the 2G/2.5G/2.75G packet switched network domain.
 
 As Osmocom implements a BTS-colocated PCU, there are potentially many
 Gb interface connections between all those many PCUs in the network
 and the SGSN.  This can be cumbersome to configure/maintain at the
-SGSN sine.
+SGSN side.
 
-OsmoGbPROXY aggregates many PCU-facing Gb connections into one Gb
+OsmoGbProxy aggregates many PCU-facing Gb connections into one Gb
 connection to the SGSN.  This is achieved by
 
 * maintaining sepaate NS-VCs on the PCU side and on the SGSN side
@@ -21,11 +21,12 @@ connection to the SGSN.  This is achieved by
 * having some special handling for the signaling BVC (BVCI=0) which is
   shared among all the PCUs connected to the proxy
 
+
 === Data Model
 
 ==== gbproxy_config
 
-This contains the parsed configuration of the OsmoGbPROXY.
+This contains the parsed configuration of the OsmoGbProxy.
 
 ==== gproxy_peer
 
diff --git a/doc/manuals/osmogbproxy-usermanual.adoc b/doc/manuals/osmogbproxy-usermanual.adoc
index c4e0b9d0b..c93ebecf9 100644
--- a/doc/manuals/osmogbproxy-usermanual.adoc
+++ b/doc/manuals/osmogbproxy-usermanual.adoc
@@ -9,6 +9,8 @@ include::./common/chapters/preface.adoc[]
 
 include::{srcdir}/chapters/gbproxy-overview.adoc[]
 
+include::{srcdir}/chapters/gbproxy-details.adoc[]
+
 include::{srcdir}/chapters/gbproxy-running.adoc[]
 
 include::{srcdir}/chapters/gbproxy-control.adoc[]