summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--build/Makefile.asciidoc.inc17
-rw-r--r--common/chapters/counters-overview.adoc96
-rw-r--r--common/chapters/osmux/mgcp_extension_osmux.adoc115
-rw-r--r--common/chapters/osmux/mo_call_osmux_aoip.msc54
-rw-r--r--common/chapters/osmux/mo_call_osmux_sccplite.msc58
-rw-r--r--common/chapters/osmux/mo_call_osmux_sccplite_nat.msc77
-rw-r--r--common/chapters/osmux/network_osmux_aoip.dot32
-rw-r--r--common/chapters/osmux/network_osmux_sccplite.dot33
-rw-r--r--common/chapters/osmux/network_osmux_sccplite_nat.dot40
-rw-r--r--common/chapters/osmux/osmux.adoc141
-rw-r--r--common/chapters/trx_if.adoc295
-rw-r--r--configure.ac9
-rwxr-xr-xcontrib/jenkins.sh3
-rw-r--r--debian/changelog19
-rw-r--r--tests/Makefile.am5
15 files changed, 931 insertions, 63 deletions
diff --git a/build/Makefile.asciidoc.inc b/build/Makefile.asciidoc.inc
index fb44a63..7cb660f 100644
--- a/build/Makefile.asciidoc.inc
+++ b/build/Makefile.asciidoc.inc
@@ -17,6 +17,7 @@
# osmo_yada.pdf: yada/*.adoc yada/*.msc
BUILDDIR = $(OSMO_GSM_MANUALS_DIR)/build
+COMMONDIR = $(OSMO_GSM_MANUALS_DIR)/common
GIT_VERSION := $(shell git describe --abbrev=4 --dirty --always --tags)
GIT_DATE := $(shell $(OSMO_GSM_MANUALS_DIR)/build/unix-time-to-fmt.py `git log -n 1 "--pretty=%at" ../.`)
@@ -36,7 +37,7 @@ CLEAN_FILES += $(ASCIIDOC_NAME:%=%__*.png) $(ASCIIDOC_NAME:%=%__*.svg) $(ASCIIDO
CLEAN_FILES += $(ASCIIDOC_PDF) $(ASCIIDOC_NAME:%=%.html)
UPLOAD_FILES += $(ASCIIDOC_PDF)
-ASCIIDOC_OPTS := -f $(BUILDDIR)/mscgen-filter.conf -f $(BUILDDIR)/diag-filter.conf -f $(BUILDDIR)/docinfo-releaseinfo.conf -f $(BUILDDIR)/python2-filter.conf -a srcdir='$(srcdir)'
+ASCIIDOC_OPTS := -f $(BUILDDIR)/mscgen-filter.conf -f $(BUILDDIR)/diag-filter.conf -f $(BUILDDIR)/docinfo-releaseinfo.conf -f $(BUILDDIR)/python2-filter.conf -a srcdir='$(srcdir)' -a commondir='$(COMMONDIR)'
DBLATEX_OPTS := -s $(ASCIIDOCSTYLE) -P draft.mode=yes -P draft.watermark=0
ifeq (,$(BUILD_RELEASE))
@@ -53,8 +54,8 @@ all: $(ASCIIDOC_PDF)
$(ASCIIDOC_PDF): %.pdf: %.adoc %-docinfo.xml \
$(ASCIIDOC_DEPS) \
$(ASCIIDOCSTYLE) \
- $(OSMO_GSM_MANUALS_DIR)/common/*/*.adoc \
- $(OSMO_GSM_MANUALS_DIR)/common/images/* \
+ $(COMMONDIR)/*/*.adoc \
+ $(COMMONDIR)/images/* \
build common
# a2x can't use a different output file. To support out-of-tree builds,
@@ -72,14 +73,16 @@ $(ASCIIDOC_PDF): %.pdf: %.adoc %-docinfo.xml \
and remove three lines starting with '% \"DRAFT\" on first page'\n" \
|| true
TEXINPUTS="$(OSMO_GSM_MANUALS_DIR)" \
- a2x $(A2X_OPTS) $(notdir $<) || (echo "ERROR: a2x failed! Running asciidoc to get verbose errors..."; \
- asciidoc -v $(ASCIIDOC_OPTS) $(notdir $<); exit 1)
+ a2x -vv $(A2X_OPTS) $(notdir $<)
-check: $(ASCIIDOC_CHECKS)
+check:
+ if [ -n "$$ASCIIDOC_WARNINGS_CHECK" ]; then \
+ $(MAKE) $(ASCIIDOC_CHECKS); \
+ fi
$(ASCIIDOC_CHECKS): %.check: %.adoc %-docinfo.xml \
$(ASCIIDOCSTYLE) \
- $(OSMO_GSM_MANUALS_DIR)/common/chapters/*.adoc \
+ $(COMMONDIR)/chapters/*.adoc \
$(ASCIIDOC_DEPS) \
build common
diff --git a/common/chapters/counters-overview.adoc b/common/chapters/counters-overview.adoc
index fbdef30..8f9a29a 100644
--- a/common/chapters/counters-overview.adoc
+++ b/common/chapters/counters-overview.adoc
@@ -3,7 +3,7 @@
The following gives an overview of all the types of counters available:
-=== Osmo Counters
+=== Osmo Counters (deprecated)
Osmo counters are the oldest type of counters added to Osmocom projects.
They are not grouped.
@@ -26,12 +26,11 @@ The control interface command to get a counter (group) is:
rate_ctr.per_{sec,min,hour,day,abs}.<group_name>.<idx>.[counter_name]
-It is possible to get all counters from a group by omitting the counter name
+It is possible to get all counters in a group by omitting the counter name
=== Stat Item
-Stat items are a grouped replacement for osmo counters, but not many stat
-items are available yet.
+Stat items are a grouped replacement for osmo counters.
* Printed as part of VTY show stats
* Replacement for osmo counters
@@ -39,12 +38,91 @@ items are available yet.
* Grouped and indexed like rate counters
* Items have a unit
* Keeps a list of the last values measured, so could return an average, min,
- max, std. deviation
+ max, std. deviation. So far this is not implemented in any of the reporting
+ options.
-=== Stats Reporter
+=== Statistic Levels
+
+There are three levels on which a statistic can be aggregated in Osmocom
+projects: globally, per-peer and per-subscriber.
+
+==== Global
+
+These are global statistics.
+
+==== Peer
-Statsd stats reporter can send osmo counter, rate counter and stats item values to statsd
+These statistics relate to a peer the program connects to such as the NSVC in
+an SGSN.
-See the stats reporter command of the VTY reference for details on how to
-setup the connection to statsd.
+This level also includes reporting global statistics.
+
+==== Subscriber
+
+These statistics are related to an individual mobile subscriber. An example
+would be bytes transferred in an SGSN PDP context.
+
+This level also includes global and peer-based statistics.
+
+=== Stats Reporter
+The stats reporter periodically collects osmo counter, rate counter and
+stat item values and sends them to a backend. Currently implemented are
+outputting to the configured log targets and a statsd connector.
+
+==== Configuring a stats reporter
+
+Periodically printing the statistics to the log can be done in the following
+way:
+
+.Log statistics
+====
+
+----
+OsmoBSC> enable
+OsmoBSC# configure terminal
+OsmoBSC(config)# stats interval 60 <1>
+OsmoBSC(config)# stats reporter log <2>
+OsmoBSC(config-stats)# level global <3>
+OsmoBSC(config-stats)# enable <4>
+----
+====
+
+<1> The interval determines how often the statistics are reported.
+<2> Write the statistic information to any configured log target.
+<3> Report only `global` statistics (can be `global`, `peer`, or
+ `subscriber`).
+<4> Enable the reporter, `disable` will disable it again.
+
+The counter values can also be sent to any aggregation/visualization tool that
+understands the statsd format, for example a statsd server with graphite or
+prometheus using the statsd_exporter together with grafana.
+
+The statsd format is specified in https://github.com/b/statsd_spec
+
+.Report statistics to statsd
+====
+
+----
+OsmoBSC> enable
+OsmoBSC# configure terminal
+OsmoBSC(config)# stats interval 10
+OsmoBSC(config)# stats reporter statsd <1>
+OsmoBSC(config-stats)# prefix BSC1 <2>
+OsmoBSC(config-stats)# level subscriber <3>
+OsmoBSC(config-stats)# remote-ip 1.2.3.4 <4>
+OsmoBSC(config-stats)# remote-port 8125 <5>
+OsmoBSC(config-stats)# enable
+----
+====
+
+<1> Configure the statsd reporter.
+<2> Prefix the reported statistics. This is useful to distinguish statistics
+ from multiple instances of the same service.
+<3> Report only `global` statistics or include `peer` or `subscriber`
+ statistics as well.
+<4> IP address of the statsd server.
+<5> UDP port of the statsd server. Statsd by default listens to port 8125.
+
+Setting up a statsd server and configuring the visualization is beyond the
+scope of this document.
diff --git a/common/chapters/osmux/mgcp_extension_osmux.adoc b/common/chapters/osmux/mgcp_extension_osmux.adoc
new file mode 100644
index 0000000..c12e9ef
--- /dev/null
+++ b/common/chapters/osmux/mgcp_extension_osmux.adoc
@@ -0,0 +1,115 @@
+[[mgcp-extension-osmux]]
+=== Osmux and MGCP
+
+`X-Osmux` indicates to OsmoMGW that a given connection of an `rtpbridge`
+endpoint has to be configured in order to handle Osmux frames instead of RTP
+messages on the data plane.
+
+==== `X-Osmux` Format
+
+The value part of `X-Osmux` must be one integer in range [0..255], or
+alternatively only on request messages, an asterisk (*) if the value is not yet
+known.
+
+`X-Osmux` must be issued in the MGCP header section (typically as its last
+item), before the SDP section starts.
+
+`X-Osmux` can be included inside `CRCX` and `MDCX` request messages, as well as
+their respective response messages.
+
+In request messages, the value part of `X-Osmux` specifies the CID to be used by
+OsmoMGW to _send_ Osmux frames to the remote peer for that connection, also
+known as _sendCID_.
+
+In response messages, the value part of `X-Osmux` specifies the CID where
+OsmoMGW expect to _receive_ Osmux frames from the remote peer for that
+connection, also known as _recvCID_.
+
+.Example: `X-Osmux` format with a known CID 3.
+----
+X-Osmux: 3
+----
+
+.Example: `X-Osmux` format with a wildcard (not yet known) CID.
+----
+X-Osmux: *
+----
+
+==== `X-Osmux` Considerations
+
+If the MGCP client is willing to use Osmux for a given connection, it shall
+specify so during `CRCX` time, and not later. If at `CRCX` time the MGCP client
+doesn't yet know the _sendCID_, it can use an astersik (*) and provide
+_sendCID_ later within `MDCX` messages.
+
+All subsequent `MDCX` messages sent towards an Osmux connection must contain the
+original _sendCID_ sent during `CRCX`. The same way, all `MDCX` response shall
+contain the _recvCID_ sent during `CRCX`.
+
+The other required connection address parameters, such as IP address, port, and
+codecs, are negotiated through MGCP and SDP as usual, but in this case the IP
+address and port specific the Osmux socket IP address and port to use, that
+together with the Osmux CID conform the entire tuple identifying a Osmux stream.
+
+Since Osmux only supports AMR codec payloads, the SDP must specify use of AMR
+codec.
+
+.Example: `CRCX` message that instructs OsmoMGW to create an Osmux connection
+----
+CRCX 189 rtpbridge/1@mgw MGCP 1.0
+C: 36
+M: sendrecv
+X-Osmux: 2
+
+v=0
+o=- 36 23 IN IP4 172.18.2.20
+s=-
+c=IN IP4 1.2.3.4
+t=0 0
+m=audio 2342 RTP/AVP 112
+a=fmtp:112
+a=rtpmap:112 AMR/8000/1
+a=ptime:20
+----
+
+.Example: response to `CRCX` containing the <<recvCID>>
+----
+200 189 OK
+I: 07E41584
+X-Osmux: 2
+Z: rtpbridge/1@mgw
+
+v=0
+o=- foo 21 IN IP4 172.18.1.20
+s=-
+c=IN IP4 172.18.1.20
+t=0 0
+m=audio 11002 RTP/AVP 112
+a=rtpmap:112 AMR/8000
+a=ptime:20
+----
+
+==== `X-Osmux` Support
+
+`X-Osmux` is known to be supported by OsmoMGW on the MGCP server side, and by
+OsmoBSC as well as OsmoMSC on the MGCP client side (through libosmo-mgcp-cli).
+No other programs supporting this feature are known or envisioned at the time of
+writing this document.
+
+In OmoMGW, Osmux support is managed through VTY.
+
+.Example: Sample config file section with Osmux configuation
+----
+mgcp
+ ...
+ osmux on <1>
+ osmux bind-ip 172.18.1.20 <2>
+ osmux port 1984 <3>
+ osmux batch-factor 4 <4>
+ osmux dummy on <5>
+----
+<1> Allow clients to set allocate Osmux connections in `rtpbridge` endpoints, while still allowing RTP connections
+<2> Bind the Osmux socket to the provided IP address
+<3> Bind the Osmux socket to the provided UDP port
+<4> Batch up to 4 RTP payloads of the same stream on each Osmux frame
+<5> Periodically send Osmux dummy frames, useful to punch a hole in NATs and maintain connections opened.
diff --git a/common/chapters/osmux/mo_call_osmux_aoip.msc b/common/chapters/osmux/mo_call_osmux_aoip.msc
new file mode 100644
index 0000000..9cb2e50
--- /dev/null
+++ b/common/chapters/osmux/mo_call_osmux_aoip.msc
@@ -0,0 +1,54 @@
+# MO-call with Osmux enable on 3GPP AoIP
+msc {
+ hscale=2;
+ ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgw_bsc[label="OsmoMGW(bsc)"], m_sc[label="MSC"], mgw_msc[label="OsmoMGW(msc)"];
+
+ bsc <- m_sc [label="BSSMAP RESET (with extension IE: Osmux Support)"];
+ bsc -> m_sc [label="BSSMAP RESET ACK (with extension IE: Osmux Support)"];
+ ...;
+ ms box mgw_msc [label="We assume a SDCCH is already established"];
+ ...;
+
+ ms -> bsc [label="DTAP CM Service Request"];
+ bsc -> m_sc [label="Complete Layer 3 Information DTAP CM Service Request"];
+
+ # Allocate MGW/MSC Osmux endpoint
+ m_sc -> mgw_msc [label="MGCP CRCX rtpbridge/*@mgw, X-Osmux: *"];
+ mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 1, recvCID 5"];
+ mgw_msc -> m_sc [label="MGCP CRCX rtpbridge/1@mgw OK (MGW:1984, X-Osmux: 5)"];
+
+ bsc <- m_sc [label="BSSAP ASSGN REQ (3GPP AoIP, extension IE: Osmux CID 5)"];
+ bts <- bsc [label="RSL CHAN ACT"];
+ bts -> bsc [label="RSL CHAN ACT ACK"];
+ ms <- bsc [label="Assignment Command"];
+ ms -> bsc [label="Assignment Complete"];
+ ...;
+
+ # 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 -> mgw_bsc [label="MGCP CRCX rtpbridge/2@mgw (BTS:1000)"];
+ mgw_bsc box mgw_bsc [label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000"];
+ bsc <- mgw_bsc [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:2000)"];
+ bts <- bsc [label="IPA MDCX (MGW:2000)"];
+ bts box bts [label="Connect RTP socket to remote (MGW) RTP Port"];
+ bts -> bsc [label="IPA MDCX ACK"];
+ ...;
+
+ mgw_bsc <- bsc [label="MGCP CRCX rtpbridge/2@mgw (MSC:1984, X-Osmux: 5)"];
+ mgw_bsc box mgw_bsc [label="Bind to MGW-local Osmux Port (1985)\nConnect to MSC:1984\nAllocate new recvCID 7"];
+ mgw_bsc -> bsc [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:1985, X-Osmux: 7)"];
+ ...;
+
+ bsc -> m_sc [label="BSSAP ASSGN CMPL (3GPP AoIP MGW:1985, extension IE: Osmux CID 7)"];
+ m_sc box m_sc [label="Connect remote Osmux to MGW addr from ASSGN CMPL"];
+ m_sc -> mgw_msc [label="MGCP MDCX rtpbridge/1@mgw (MGW:1985, X-Osmux: 7)"];
+ m_sc <- mgw_msc [label="MGCP MDCX rtpbridge/1@mgw OK (X-Osmux: 5)"];
+ ...;
+
+ mgw_bsc <=> mgw_msc [label="Osmux Audio MGW:1985 MSC:1984, CID(uplink):5, CID(downlink):7"];
+ bts <=> mgw_bsc [label="RTP Audio BTS:1000 MGW:2000"];
+ ms <=> bts [label="Um Audio (bidirectional)"];
+ ms <-> m_sc [label="DTAP CC ALERTING"];
+}
diff --git a/common/chapters/osmux/mo_call_osmux_sccplite.msc b/common/chapters/osmux/mo_call_osmux_sccplite.msc
new file mode 100644
index 0000000..903da46
--- /dev/null
+++ b/common/chapters/osmux/mo_call_osmux_sccplite.msc
@@ -0,0 +1,58 @@
+# MO-call with Osmux enable on 3GPP AoIP using A/IP with IPA/SCCPlite
+msc {
+ hscale=2;
+ ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgw_bsc[label="OsmoMGW(bsc)"], m_sc[label="MSC"], mgw_msc[label="OsmoMGW(msc)"];
+
+ ms box m_sc [label="We assume a SDCCH is already established"];
+ ...;
+
+ ms -> bsc [label="DTAP CM Service Request"];
+ bsc -> m_sc [label="Complete Layer 3 Information DTAP CM Service Request"];
+ bsc <- m_sc [label="Connection Confirmed"];
+
+ # Allocate MGW/MSC Osmux endpoint
+ m_sc -> mgw_msc [label="MGCP CRCX *@mgw, X-Osmux: *"];
+ mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 1, recvCID 5"];
+ mgw_msc -> m_sc [label="MGCP CRCX rtpbridge/1@mgw OK (MGW:1984, X-Osmux: 5)"];
+
+ bsc <- m_sc [label="BSSAP ASSGN REQ (CIC:1)"];
+ bts <- bsc [label="RSL CHAN ACT"];
+ bts -> bsc [label="RSL CHAN ACT ACK"];
+ ms <- bsc [label="Assignment Command"];
+ ms -> bsc [label="Assignment Complete"];
+ ...;
+
+ # connect BTS RTP with BSC-MGW RTP, CIC is used as MGW endpoint
+ 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 -> mgw_bsc [label="MGCP CRCX 1@mgw (BTS:1000)"];
+ mgw_bsc box mgw_bsc [label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000"];
+ bsc <- mgw_bsc [label="MGCP CRCX 1@mgw OK (MGW:2000)"];
+ bts <- bsc [label="IPA MDCX (MGW:2000)"];
+ bts box bts [label="Connect RTP socket to remote (MGW) RTP Port"];
+ bts -> bsc [label="IPA MDCX ACK"];
+ ...;
+
+ bsc -> m_sc [label="BSSMAP ASSGN Complete"];
+ ...;
+
+ # MSC configures BSC-MGW MSC-side of the endpoint through MGCP UDP forwarding
+ mgw_bsc <- m_sc [label="MGCP CRCX 1@mgw (MSC:1984, X-Osmux: 5)"];
+ mgw_bsc box mgw_bsc [label="Bind to BTS-local Osmux Port (1985)\nAllocate new recvCID 7"];
+ mgw_bsc -> m_sc [label="MGCP CRCX 1@mgw OK (MGW:1985, X-Osmux: 7)"];
+ mgw_bsc <- m_sc [label="MGCP MDCX 1@mgw (recvonly) "];
+ mgw_bsc box mgw_bsc [label="Connect Osmux socket to remote (MSC) Osmux Port"];
+ mgw_bsc -> m_sc [label="MGCP MDCX 1@mgw OK"];
+ mgw_bsc <= mgw_msc [label="Osmux Audio MGW:1985 MSC:1984, CID(downlink):7"];
+ bts <= mgw_bsc [label="RTP Audio BTS:1000 MGW:2000"];
+ ms <= bts [label="Um Audio (unidirectional)"];
+ ms <- m_sc [label="DTAP CC ALERTING"];
+ ...;
+ mgw_bsc <- m_sc [label="MGCP MDCX 1@mgw (sndrecv) "];
+ mgw_bsc box mgw_bsc [label="Switch to bi-directional audio"];
+ mgw_bsc -> m_sc [label="MGCP MDCX 1@mgw OK"];
+ mgw_bsc <=> mgw_msc [label="Osmux Audio MGW:1985 MSC:1984, CID(uplink):5, CID(downlink):7"];
+ bts <=> mgw_bsc [label="RTP Audio BTS:1000 MGW:2000"];
+ ms <=> bts [label="Um Audio (bidirectional)"];
+}
diff --git a/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc b/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc
new file mode 100644
index 0000000..2aa8105
--- /dev/null
+++ b/common/chapters/osmux/mo_call_osmux_sccplite_nat.msc
@@ -0,0 +1,77 @@
+# MO-call with Osmux enable on 3GPP AoIP using A/IP with IPA/SCCPlite with a BSC-NAT between BSC and MSC
+msc {
+ hscale=2;
+ ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgw_bsc[label="OsmoMGW(bsc)"], bscnat[label="OsmoBSCNAT"], m_sc[label="MSC"], mgw_msc[label="OsmoMGW(msc)"];
+
+ ms box m_sc [label="We assume a SDCCH is already established"];
+ ...;
+
+ ms -> bsc [label="DTAP CM Service Request"];
+ bsc -> m_sc [label="Complete Layer 3 Information DTAP CM Service Request"];
+ bsc <- m_sc [label="Connection Confirmed"];
+
+ # Allocate MGW/MSC RTP endpoint
+ m_sc -> mgw_msc [label="MGCP CRCX *@mgw"];
+ mgw_msc box mgw_msc [label="Bind to MGW-local RTP Port (3000)\nAllocate new endpoint 1"];
+ mgw_msc -> m_sc [label="MGCP CRCX rtpbridge/1@mgw OK (MGW:3000)"];
+ bscnat <- m_sc [label="BSSAP ASSGN REQ (CIC:1)"];
+
+ # NAT: MGW/MSC Osmux endpoint
+ #bscnat -> bscnat [label="MGCP CRCX *@mgw, X-Osmux: *"];
+ mgw_msc box mgw_msc [label="Bind to MGW-local Osmux Port (1984)\nAllocate new endpoint 2, recvCID 5"];
+ #mgw_msc -> m_sc [label="MGCP CRCX rtpbridge/1@mgw OK (MGW:1984, X-Osmux: 5)"];
+ bsc <- bscnat [label="BSSAP ASSGN REQ (CIC:2)"];
+
+ bts <- bsc [label="RSL CHAN ACT"];
+ bts -> bsc [label="RSL CHAN ACT ACK"];
+ ms <- bsc [label="Assignment Command"];
+ ms -> bsc [label="Assignment Complete"];
+ ...;
+
+ # connect BTS RTP with BSC-MGW RTP, CIC is used as MGW endpoint
+ 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 -> mgw_bsc [label="MGCP CRCX 1@mgw (BTS:1000)"];
+ mgw_bsc box mgw_bsc [label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000"];
+ bsc <- mgw_bsc [label="MGCP CRCX 1@mgw OK (MGW:2000)"];
+ bts <- bsc [label="IPA MDCX (MGW:2000)"];
+ bts box bts [label="Connect RTP socket to remote (MGW) RTP Port"];
+ bts -> bsc [label="IPA MDCX ACK"];
+ #bsc -> mgw_bsc [label="MGCP MDCX 1@mgw (optional)"];
+ #bsc <- mgw_bsc [label="MGCP MDCX 1@mgw OK (optional)"];
+ ...;
+
+ bsc -> bscnat [label="BSSMAP ASSGN Complete"];
+ bscnat -> m_sc [label="BSSMAP ASSGN Complete"];
+ ...;
+
+ # MSC configures BSC-MGW MSC-side of the endpoint through MGCP UDP forwarding
+ bscnat <- m_sc [label="MGCP CRCX 1@mgw (MSC:3000)"];
+ bscnat box bscnat [label="Allocate new endpoint 2\nAllocate new recvCID 5\nBind to local Osmux Port (1984)\nBind to local RTP port 4000"];
+ mgw_bsc <- bscnat [label="MGCP CRCX 2@mgw (MSC:1984, X-Osmux: 5)"];
+ mgw_bsc -> bscnat [label="MGCP CRCX 2@mgw OK (MGW:1985, X-Osmux: 7)"];
+ bscnat -> m_sc [label="MGCP CRCX 1@mgw OK (MGW:4000)"];
+ bscnat <- m_sc [label="MGCP MDCX 1@mgw (recvonly) "];
+ mgw_bsc <- bscnat [label="MGCP MDCX 2@mgw (recvonly) "];
+ mgw_bsc box mgw_bsc [label="Connect Osmux socket to remote (MSC) Osmux Port"];
+ mgw_bsc -> bscnat [label="MGCP MDCX 2@mgw OK"];
+ bscnat -> m_sc [label="MGCP MDCX 1@mgw OK"];
+
+ bscnat <= mgw_msc [label="RTP Audio BSCNAT:4000 MGW:3000"];
+ mgw_bsc <= bscnat [label="Osmux Audio MGW:1985 BSCNAT:1984, CID(downlink):7"];
+ bts <= mgw_bsc [label="RTP Audio BTS:1000 MGW:2000"];
+ ms <= bts [label="Um Audio (unidirectional)"];
+ ms <- m_sc [label="DTAP CC ALERTING"];
+ ...;
+ bscnat <- m_sc [label="MGCP MDCX 1@mgw (sndrecv) "];
+ mgw_bsc <- bscnat [label="MGCP MDCX 2@mgw (sndrecv) "];
+ mgw_bsc box mgw_bsc [label="Switch to bi-directional audio"];
+ mgw_bsc -> bscnat [label="MGCP MDCX 2@mgw OK"];
+ bscnat -> m_sc [label="MGCP MDCX 1@mgw OK"];
+
+ bscnat <=> mgw_msc [label="RTP Audio BSCNAT:4000 MGW:3000"];
+ mgw_bsc <=> bscnat [label="Osmux Audio MGW:1985 MSC:1984, CID(uplink):5, CID(downlink):7"];
+ bts <=> mgw_bsc [label="RTP Audio BTS:1000 MGW:2000"];
+ ms <=> bts [label="Um Audio (bidirectional)"];
+}
diff --git a/common/chapters/osmux/network_osmux_aoip.dot b/common/chapters/osmux/network_osmux_aoip.dot
new file mode 100644
index 0000000..7531e6a
--- /dev/null
+++ b/common/chapters/osmux/network_osmux_aoip.dot
@@ -0,0 +1,32 @@
+digraph G {
+ rankdir = LR;
+ subgraph cluster_RAN {
+ OsmoBTS1 [label="OsmoBTS"];
+ OsmoBTS2 [label="OsmoBTS"];
+ OsmoBSC;
+ OsmoMGW [label="OsmoMGW\n(for BSC)"];
+
+ OsmoBTS1 -> OsmoBSC [label="Abis/IP", dir="both"];
+ OsmoBTS2 -> OsmoBSC [label="Abis/IP", dir="both"];
+ OsmoBSC -> OsmoMGW [label="MGCP", dir="both"];
+ { rank = same; OsmoBSC; OsmoMGW }
+
+ OsmoBTS1 -> OsmoMGW [label="RTP", dir="both"];
+ OsmoBTS2 -> OsmoMGW [label="RTP", dir="both"];
+
+ label = "RAN";
+ }
+ subgraph cluster_CN {
+ OsmoMGW1 [label="OsmoMGW\n(for MSC)"];
+ OsmoMSC [label="MSC\ne.g. OsmoMSC"];
+ Core [label="Other CN Elements"];
+ OsmoMSC -> Core [label="MAP/ISUP/SIP/GSUP", dir="both"];
+ OsmoMSC -> OsmoMGW1 [label="MGCP", dir="both"];
+ { rank = same; OsmoMSC; OsmoMGW1 }
+ OsmoMGW -> OsmoMGW1 [label="Osmux", dir="both", color=red];
+ OsmoMGW1 -> Core [label="RTP", dir="both"];
+ label = "CN";
+ }
+
+ OsmoBSC -> OsmoMSC [label="3GPP AoIP\nvia SIGTRAN/STP", dir="both"];
+}
diff --git a/common/chapters/osmux/network_osmux_sccplite.dot b/common/chapters/osmux/network_osmux_sccplite.dot
new file mode 100644
index 0000000..678a61e
--- /dev/null
+++ b/common/chapters/osmux/network_osmux_sccplite.dot
@@ -0,0 +1,33 @@
+digraph G {
+ rankdir = LR;
+ subgraph cluster_RAN {
+ OsmoBTS1 [label="OsmoBTS"];
+ OsmoBTS2 [label="OsmoBTS"];
+ OsmoBSC;
+ OsmoMGW [label="OsmoMGW\n(for BSC)"];
+
+ OsmoBTS1 -> OsmoBSC [label="Abis/IP", dir="both"];
+ OsmoBTS2 -> OsmoBSC [label="Abis/IP", dir="both"];
+ OsmoBSC -> OsmoMGW [label="MGCP (BTS side)", dir="both"];
+ { rank = same; OsmoBSC; OsmoMGW }
+
+ OsmoBTS1 -> OsmoMGW [label="RTP", dir="both"];
+ OsmoBTS2 -> OsmoMGW [label="RTP", dir="both"];
+
+ label = "RAN";
+ }
+ subgraph cluster_CN {
+ OsmoMGW1 [label="OsmoMGW\n(for MSC)"];
+ OsmoMSC [label="MSC\ne.g. OsmoMSC"];
+ Core [label="Other CN Elements"];
+ OsmoMSC -> Core [label="MAP/ISUP/SIP/GSUP", dir="both"];
+ OsmoMSC -> OsmoMGW1 [label="MGCP", dir="both"];
+ { rank = same; OsmoMSC; OsmoMGW1 }
+ OsmoMGW -> OsmoMGW1 [label="Osmux", dir="both", color=red];
+ OsmoMGW1 -> Core [label="RTP", dir="both"];
+ label = "CN";
+ }
+
+ OsmoBSC -> OsmoMSC [label="3GPP AoIP\nvia IPA/SCCPlite", dir="both"];
+ OsmoMGW -> OsmoMSC [label="MGCP (CN side)\n(IPA/UDP forwarding via BSC)", dir="both"];
+}
diff --git a/common/chapters/osmux/network_osmux_sccplite_nat.dot b/common/chapters/osmux/network_osmux_sccplite_nat.dot
new file mode 100644
index 0000000..021d0ec
--- /dev/null
+++ b/common/chapters/osmux/network_osmux_sccplite_nat.dot
@@ -0,0 +1,40 @@
+digraph G {
+ rankdir = LR;
+ subgraph cluster_RAN {
+ OsmoBTS1 [label="OsmoBTS"];
+ OsmoBTS2 [label="OsmoBTS"];
+ OsmoBSC;
+ OsmoMGW [label="OsmoMGW\n(for BSC)"];
+
+ OsmoBTS1 -> OsmoBSC [label="Abis/IP", dir="both"];
+ OsmoBTS2 -> OsmoBSC [label="Abis/IP", dir="both"];
+ OsmoBSC -> OsmoMGW [label="MGCP (BTS side)", dir="both"];
+ { rank = same; OsmoBSC; OsmoMGW }
+
+ OsmoBTS1 -> OsmoMGW [label="RTP", dir="both"];
+ OsmoBTS2 -> OsmoMGW [label="RTP", dir="both"];
+
+ label = "RAN";
+ }
+ subgraph cluster_BSCNAT {
+ OsmoBSCNAT;
+ label = "BSCNAT";
+ }
+ subgraph cluster_CN {
+ OsmoMGW1 [label="OsmoMGW\n(for MSC)"];
+ OsmoMSC [label="MSC\ne.g. OsmoMSC"];
+ Core [label="Other CN Elements"];
+ OsmoMSC -> Core [label="MAP/ISUP/SIP/GSUP", dir="both"];
+ OsmoMSC -> OsmoMGW1 [label="MGCP", dir="both"];
+ { rank = same; OsmoMSC; OsmoMGW1 }
+ OsmoMGW -> OsmoBSCNAT [label="Osmux", dir="both", color=red];
+ OsmoMGW1 -> Core [label="RTP", dir="both"];
+ label = "CN";
+ }
+
+ OsmoBSC -> OsmoBSCNAT [label="3GPP AoIP\nvia IPA/SCCPlite", dir="both"];
+ OsmoMGW -> OsmoBSCNAT [label="MGCP (CN side)\n(IPA/UDP forwarding via BSC)", dir="both"];
+ OsmoBSCNAT -> OsmoMSC [label="3GPP AoIP\nvia IPA/SCCPlite", dir="both"];
+ OsmoBSCNAT -> OsmoMSC [label="MGCP\nvia UDP", dir="both"];
+ OsmoBSCNAT -> OsmoMGW1 [label="RTP", dir="both"];
+}
diff --git a/common/chapters/osmux/osmux.adoc b/common/chapters/osmux/osmux.adoc
new file mode 100644
index 0000000..5e53b60
--- /dev/null
+++ b/common/chapters/osmux/osmux.adoc
@@ -0,0 +1,141 @@
+== Osmux
+
+`Osmux` is a protocol aimed at multiplexing and transmitting voice and
+signalling traffic from multiple sources in order to reduce the overall
+bandwidth consumption. This feature becomes specially meaningful in case of
+satellite based GSM systems, where the transmission cost on the back-haul is
+relatively expensive. In such environment, even seemingly small protocol
+optimizations, eg. message batching and trunking, can result in significant cost
+reduction.
+
+Full reference document for the osmux protocol can be found here:
+http://ftp.osmocom.org/docs/latest/osmux-reference.pdf
+
+In Osmocom satellite based GSM networks, the satellite link is envisioned to be
+in between the BSS and the core network, that is, between the BSC and the MSC
+(or BSC-NAT). Hence, Osmocom components can make use of `Osmux` protocol to
+multiplex payload audio streams from call legs between OsmoBSC and OsmoMSC (or
+OsmoBSCNAT). The MGW attached those components need of course also be aware of
+`Osmux` existence in order to properly set up the audio data plane.
+
+=== Osmux and NAT
+
+It is quite usual for satellite based links to use NATs, which means any or both
+of the two components at each side of the satellite link (BSC and MSC/BSC-NAT)
+may end up being behind a NAT and being unable to provide the real public
+address to its peer on the other side of the satellite.
+
+As a result, upon call parameter negotiation (RTP/Osmux IP address and port),
+those parameters won't be entirely useful and some specific logic needs to be
+introduced into the network components to circumvent the NAT under those cases.
+
+For instance, if the BSC and its co-located MGW (BSC/MGW from now on) is under a
+NAT, it may end up providing its private address and port as RTP/Osmux
+parameters to the MSC/MGW through GSM protocols, but MSC will fail to send any
+message to that tuple because of the NAT or routing issues (due to IP address
+being a private address). In that scenario, MSC/MGW needs to be aware that
+there's a NAT and wait until an RTP/Osmux message arrives from the BSC/MGW host.
+It then can, from that message source IP address and port (and CID in case of
+Osmux), discover the real public IP address and port of the peer (BSC/MGW). From
+that point on, the BSC/MGW punched a hole in the NAT (its connection table is
+updated) and MSC/MGW is able to send data back to it on that connection.
+
+Moreover, NATs tend to drop connections from their connection tables after some
+inactivity time, meaning a peer may receive notice about the other end not being
+available while it actually is. This means the GSM network needs to be
+configured in a way to ensure inactivity periods are short enough that this
+cannot occur. That's the reason why OsmoMGW provides the `osmux dummy` VTY
+command to enable sending dummy packets from time to time to keep the
+connections alive.
+
+=== CID allocation
+
+Each peer (BSC/MGW and MSC/MGW) allocates its own _recvCID_, and receives from
+the peer through the used GSM protocol the peer's _recvCID_, which becomes
+the local _sendCID_ for that connection.
+
+----
+BSC/MGW(recvCID=Y,sendCID=?)<-X--MSC/MGW(recvCID=X,sendCID=?)
+BSC/MGW(recvCID=Y,sendCID=X)--Y->MSC/MGW(recvCID=X,sendCID=Y)
+----
+
+This way each peer is responsible for allocating and managing their own local
+address (CID) space. This is basically the same that happens with regular IP
+address and port in the RTP case (and those also apply when Osmux is used, but
+an extra identifier, the CID, is allocated).
+
+In an ideal scenario, without NAT, each BSC/MGW would have a public,
+differentiated and unique IP and port set tuple, And MSC/MGW should be able to
+identify messages coming from them by easily matching source IP address, port
+(and CID in Osmux case) against the parameters negotiated during call set up.
+
+In this kind of scenario, MSC/MGW could easily open and manage one Osmux socket
+per BSC (based on SDP IPaddr and port parameters), with same `<localIPaddr,
+localPort>` tuple, allowing for 256 Osmux CIDs per BSC and hence call legs per
+BSC. Each of the peers could actually have more than one Osmux socket towards
+the other peer, by using a pool of ports or IP addresses, so there's really not
+limit if required as long as there's a way to infer the initially negotiated
+`<srcIP, srcPort, dstIP, dstPort, sendCID>` tuple from the received audio
+packets.
+
+However, due to some constrains from in between NATs explained in section above,
+BSC/MGW IP address and port are not a priory known, and could change between
+different connections coming from it. As a result, it is difficult to infer the
+entire tuple, so for now MGW needs to allocate its Osmux _recvCID_ in a clever
+way, in order to be able to identify the full tuple from it.
+
+Hence, currently OsmoMGW CID allocation implementation shares CID between all
+connections, which means it can only handle up to 256 concurrent Osmux
+connections (call legs).
+
+Future work in OsmoMGW (https://osmocom.org/issues/4092[OS#4092]) plans to use a
+set of local ports for Osmux sockets instead of only 1 currently used. This way
+local ports can be matched against specific `<remoteIP, remotePort>` tuples and
+have an entire 256 Osmux CID space per `<remoteIP, remotePort>` (aka per peer).
+
+=== 3GPP AoIP network setup with Osmux
+
+[[fig-network-osmux-aoip]]
+.Sample node diagram of a 3GPP AoIP network with Osmux enabled
+[graphviz]
+----
+include::network_osmux_aoip.dot[]
+----
+
+.MO-call with Osmux enable on 3GPP AoIP
+[mscgen]
+----
+include::mo_call_osmux_aoip.msc[]
+----
+
+=== SCCPLite network setup with Osmux
+
+[[fig-network-osmux-sccplite]]
+.Sample node diagram of a 3GPP AoIP using A/IP with IPA/SCCPlite network with Osmux enabled
+[graphviz]
+----
+include::network_osmux_sccplite.dot[]
+----
+
+.MO-call with Osmux enable on 3GPP AoIP using A/IP with IPA/SCCPlite
+["mscgen"]
+----
+include::mo_call_osmux_sccplite.msc[]
+----
+
+=== SCCPLite network setup with Osmux + BSC-NAT
+
+[[fig-network-osmux-sccplite-nat]]
+.Sample node diagram of a 3GPP AoIP using A/IP with IPA/SCCPlite network and BSC-NAT with Osmux enabled
+[graphviz]
+----
+include::network_osmux_sccplite_nat.dot[]
+----
+
+.MO-call with Osmux enable on 3GPP AoIP using A/IP with IPA/SCCPlite with a BSC-NAT between BSC and MSC
+["mscgen"]
+----
+include::mo_call_osmux_sccplite_nat.msc[]
+----
+
+include::mgcp_extension_osmux.adoc[]
diff --git a/common/chapters/trx_if.adoc b/common/chapters/trx_if.adoc
index b684b7b..6dd680b 100644
--- a/common/chapters/trx_if.adoc
+++ b/common/chapters/trx_if.adoc
@@ -1,44 +1,53 @@
[[trx_if]]
== TRX Manager UDP socket interface
-This is the protocol used between `osmo-trx` and `osmo-bts-trx`.
+This is the protocol used between `osmo-trx` (the transceiver) and
+`osmo-bts-trx` (the BTS or core).
-Each TRX Manager UDP socket interface represents a single ARFCN. Each of these
-per-ARFCN interfaces is a pair of UDP sockets, one for control and one for data.
-Given a base port B (5700), the master clock interface is at port P=B. The
-TRX-side control interface for C(N) is on port P=B+2N+1 and the data interface
-is on an odd numbered port P=B+2N+2. The corresponding core-side interface for
-every socket is at P+100. For any given build, the number of ARFCN interfaces
-can be fixed.
+Each TRX Manager UDP socket interface represents a single transceiver (ARFCN).
+Each of these channels is a pair of UDP sockets, one for control (`TRXC`) and
+one for data (`TRXD`). Additionally, there's a separate global socket managing
+the Master Clock Interface, shared among all channels.
+
+Given a base port `B` (5700), and a set of channels `0..N`, the ports related to
+a channel `0 <= X <= N` are:
+* The Master clock interface is located on port `P=B`.
+* The `TRXC` interface for channel `X` is located on port `P=B+2X+1`
+* The `TRXD` interface for channel `X` is located on port `P=B+2X+2`.
+
+The corresponding interface for every socket is at `P+100` on the BTS side.
[[trx_if_clock_ind]]
=== Indications on the Master Clock Interface
-The master clock interface is output only (from the radio).
+The master clock interface is output only (uplink, from the radio to the BTS).
Messages are "indications".
-CLOCK gives the current value of the transceiver clock to be used by the core.
-This message is sent whenever a trasmission packet arrives that is too late or
-too early. The clock value is NOT the current transceiver time. It is a time
-setting the the core should use to give better packet arrival times.
+CLOCK gives the current value of the transceiver clock to be used by the BTS.
+This message is usually sent around once per second (217 GSM frames), but can be
+sent at any time. The clock value is NOT the current transceiver time. It is a
+time setting that the BTS should use to give better packet arrival times. The
+initial clock value is taken randomly, and then increased over time as the
+transceiver submits downlink packets to the radio.
----
IND CLOCK <totalFrames>
----
[[trx_if_control]]
-=== Commands on the Per-ARFCN Control Interface
+=== TRXC protocol
-The per-ARFCN control interface uses a command-reponse protocol. Commands are
-NULL-terminated ASCII strings, one per UDP socket. Each command has a
-corresponding response.
+The per-ARFCN control interface uses a command-response protocol. Each command
+has a corresponding response. Commands are sent in downlink direction (BTS ->
+TRX), and responses are sent in uplink direction (TRX -> BTS). Commands and
+responses are NULL-terminated ASCII strings.
-Every command is of the form:
+Every command is structured this way:
----
CMD <cmdtype> [params]
----
-
The `<cmdtype>` is the actual command.
Parameters are optional depending on the commands type.
+
Every response is of the form:
----
RSP <cmdtype> <status> [result]
@@ -46,7 +55,6 @@ RSP <cmdtype> <status> [result]
The `<status>` is 0 for success and a non-zero error code for failure.
Successful responses may include results, depending on the command type.
-
==== Power Control
`POWEROFF` shuts off transmitter power and stops the demodulator.
@@ -55,11 +63,11 @@ CMD POWEROFF
RSP POWEROFF <status>
----
-`POWERON` starts the transmitter and starts the demodulator. Initial power
+`POWERON` starts the transmitter and starts the demodulator. Initial power
level is very low. This command fails if the transmitter and receiver are not
yet tuned. This command fails if the transmit or receive frequency creates a
conflict with another ARFCN that is already running. If the transceiver is
-already on, it response with success to this command.
+already on, it answers successfully to this command.
----
CMD POWERON
RSP POWERON <status>
@@ -102,7 +110,7 @@ RSP TXTUNE <status> <kHz>
==== Timeslot Control
-`SETSLOT` sets the format of the uplink timeslots in the ARFCN.
+`SETSLOT` sets the format of a given uplink timeslot in the ARFCN.
The `<timeslot>` indicates the timeslot of interest.
The `<chantype>` indicates the type of channel that occupies the timeslot.
A chantype of zero indicates the timeslot is off.
@@ -111,48 +119,247 @@ CMD SETSLOT <timeslot> <chantype>
RSP SETSLOT <status> <timeslot> <chantype>
----
-=== Messages on the per-ARFCN Data Interface
+Here's the list of channel combinations and related values (`<chantype>`):
+
+.List of channel combinations and related values (`<chantype>`)
+[options="header"]
+|===
+| value | Channel Combination
+|0| Channel is transmitted, but unused
+|1| TCH/FS
+|2| TCH/HS, idle every other slot
+|3| TCH/HS
+|4| Downlink: FCCH + SCH + CCCH + BCCH, Uplink: RACH
+|5| Downlink: FCCH + SCH + CCCH + BCCH + SDCCH/4 + SACCH/4, Uplink: RACH+SDCCH/4
+|6| Downlink: CCCH+BCCH, Uplink: RACH
+|7| SDCCH/8 + SACCH/8
+|8| TCH/F + FACCH/F + SACCH/M
+|9| TCH/F + SACCH/M
+|10| TCH/FD + SACCH/MD
+|11| PBCCH+PCCCH+PDTCH+PACCH+PTCCH
+|12| PCCCH+PDTCH+PACCH+PTCCH
+|13| PDTCH+PACCH+PTCCH
+|===
+
+==== TRXD header version negotiation
+
+Messages on DATA interface may have different header formats, defined by a
+version number, which can be negotiated on the control interface. By default,
+the Transceiver will use the legacy header version (0).
+
+The header format negotiation can be initiated by the BTS using 'SETFORMAT'
+command. If the requested version is not supported by the transceiver, status
+code of the response message should indicate a preferred (basically, the latest)
+version. The format of this message is the following:
+----
+CMD SETFORMAT <timeslot> <ver_req>
+RSP SETFORMAT <ver_resp> <ver_req>
+----
+
+where:
+* `<ver_req>` is the requested version (suggested by the BTS),
+* `<ver_rsp>` is either the applied version if matches `<ver_req>`, or a
+ preferred version if `<ver_req>` is not supported.
+
+If the transceiver indicates `<ver_rsp>` different than `<ver_req>`, the BTS is
+supposed to re-initiate the version negotiation using the suggested `<ver_rsp>`.
+For example:
+
+----
+ BTS -> TRX: CMD SETFORMAT 2
+ BTS <- TRX: RSP SETFORMAT 1 2
+
+ BTS -> TRX: CMD SETFORMAT 1
+ BTS <- TRX: RSP SETFORMAT 1 1
+----
+
+If no suitable `<ver_rsp>` is found, or the `<ver_req>` is incorrect, the status
+code in the response shall be `-1`.
+
+As soon as `<ver_rsp>` matches `<ver_req>` in the response, the process of
+negotiation is complete. Changing the header version is supposed to be done
+before `POWERON`, but can be also done afterwards.
+
+=== TRXD protocol
Messages on the data interface carry one radio burst per UDP message.
-==== Received Data Burst
+==== Uplink Data Burst
+
+Uplink data burst message structure differs from version 0 to 1. Basically,
+version 1 contains an extended header with regards to version 0, and the final
+padding existence is completely dropped.
+.TRXDv0 Uplink data burst message structure
[packetdiag]
----
{
colwidth = 32
node_height = 40
- 0: T
- 1-4: FN
- 5: A
- 6-7: C
- 8-155: Payload
+ 0-3: VER(0)
+ 4: RES
+ 5-7: TN
+ 8-39: FN
+ 40-47: RSSI
+ 48-63: TOA256
+ 64-95: ...Payload...
+ 96-97: PAD
}
----
-* _T_: timeslot index
-* _FN_: GSM frame number, big endian
-* _A_: RSSI in -dBm
-* _C_: correlator timing offset in 1/256 symbol steps, 2's-comp, big endian
-* _Payload_: 148 bytes soft symbol estimates, 0 -> definite "0", 255 -> definite "1"
+.TRXDv1 Uplink data burst message structure
+[packetdiag]
+----
+{
+ colwidth = 32
+ node_height = 40
-==== Transmit Data Burst
+ 0-3: VER(1)
+ 4: RES
+ 5-7: TN
+ 8-39: FN
+ 40-47: RSSI
+ 48-63: TOA256
+ 64-71: MTS
+ 72-87: C/I
+ 88-127: ...Payload...
+}
+----
+VER: 4 bits::
+TRXD header version, v0 and v1 are specified so far.
+
+TN: 3 bits::
+Timeslot number.
+
+RES: 1 bit::
+Reserved, shall be 0. It can be used in the future to extend the TDMA TN range
+to (0..15), in case anybody would need to transfer UMTS bursts.
+
+FN: 32 bits (4 bytes)::
+GSM frame number, big endian.
+
+RSSI: 8 bits (1 byte)::
+Received Signal Strength Indication in -dBm, encoded without the negative sign.
+
+TOA256: 16 bits (2 bytes)::
+Timing of Arrival in units of 1/256 of symbol, big endian.
+
+MTS: 8 bits (1 byte)::
+Contains the Modulation and Training Sequence information. See <<coding-mts>>
+for more information on the encoding.
+
+C/I: 16 bits (2 bytes)::
+Contains the Carrier-to-Interference ratio in centiBels, big endian. The C/I
+value is computed from the training sequence of each burst, where the "ideal"
+training sequence is compared to the actual training sequence and the result
+expressed in centiBels.
+
+Payload: 148 bytes for GSM, 444 bytes for EDGE::
+Contains the uplink burst. Unlike the downlink bursts, the uplink bursts are
+designated using the soft-bits notation, so the receiver can indicate its
+assurance from 0 to -127 that a given bit is 1, and from 0 to +127 that a given
+bit is 0. The Viterbi algorithm allows to approximate the original sequence of
+hard-bits (1 or 0) using these values. Each soft-bit (-127..127) of the burst is
+encoded as an unsigned value in range (0..255) respectively using the constant
+shift. This way:
+* 0 -> definite "0"
+* 255 -> definite "1".
+
+PAD: 2 bits (optional)::
+Padding at the end, historical reasons (OpenBTS inheritance). Bits can take any
+value, but 0 is preferred. Only expected on TRXDv0 headers.
+
+[[coding-mts]]
+===== Coding of MTS: Modulation and Training Sequence info
+
+3GPP TS 45.002 version 15.1.0 defines several modulation types, and a few sets
+of training sequences for each type. The most common are GMSK and 8-PSK (which
+is used in EDGE).
+
+.MTS field structure
+----
++-----------------+---------------------------------------+
+| 7 6 5 4 3 2 1 0 | bit numbers (value range) |
++-----------------+---------------------------------------+
+| X . . . . . . . | IDLE / nope frame indication (0 or 1) |
++-----------------+---------------------------------------+
+| . X X X X . . . | Modulation, TS set number (see below) |
++-----------------+---------------------------------------+
+| . . . . . X X X | Training Sequence Code (0..7) |
++-----------------+---------------------------------------+
+----
+
+IDLE / nope frame indication::
+The bit number 7 (MSB) is set to high when either nothing has been detected, or
+during IDLE frames, so noise levels can be delivered, and avoid clock gaps on
+the BTS side. Other bits are ignored, and should be set to low (`0`) in this
+case.
+
+Modulation and TS set number::
+GMSK has 4 sets of training sequences (see tables 5.2.3a-d), while 8-PSK (see
+tables 5.2.3f-g) and the others have 2 sets. Access and Synchronization bursts
+also have several synchronization sequences.
+
+.Modulation and TS set number
+----
++-----------------+---------------------------------------+
+| 7 6 5 4 3 2 1 0 | bit numbers (value range) |
++-----------------+---------------------------------------+
+| . 0 0 X X . . . | GMSK, 4 TS sets (0..3) |
++-----------------+---------------------------------------+
+| . 0 1 0 X . . . | 8-PSK, 2 TS sets (0..1) |
++-----------------+---------------------------------------+
+| . 0 1 1 X . . . | AQPSK, 2 TS sets (0..1) |
++-----------------+---------------------------------------+
+| . 1 0 0 X . . . | 16QAM, 2 TS sets (0..1) |
++-----------------+---------------------------------------+
+| . 1 0 1 X . . . | 32QAM, 2 TS sets (0..1) |
++-----------------+---------------------------------------+
+| . 1 1 X X . . . | RESERVED (0) |
++-----------------+---------------------------------------+
+----
+
+Training Sequence Code::
+The Training Sequence Code used to decode an Access or a Synchronization burst.
+This field hence doesn't apply for Normal bursts.
+
+==== Downlink Data Burst
+
+.TRXD Downlink data burst message structure
[packetdiag]
----
{
colwidth = 32
node_height = 40
- 0: T
- 1-4: FN
- 5: A
- 6-153: Payload
+ 0-3: VER
+ 4: RES
+ 5-7: TN
+ 8-39: FN
+ 40-47: PWR
+ 48-95: ...Payload...
}
----
-* _T_: timeslot index
-* _FN_ GSM frame number, big endian
-* _A_: transmit level wrt ARFCN max, -dB (attenuation)
-* _Payload_: 148 bytes output symbol values, 0 & 1
+VER: 4 bits::
+TRXD header version, v0 and v1 are specified so far.
+
+TN: 3 bits::
+Timeslot number.
+
+RES: 1 bit::
+Reserved, shall be 0. It can be used in the future to extend the TDMA TN range
+to (0..15), in case anybody would need to transfer UMTS bursts.
+
+FN: 32 bits (4 bytes)::
+GSM frame number, big endian.
+
+PWR: 8 bits (1 byte)::
+Contains the relative (to the full-scale amplitude) transmit power level in dB.
+The absolute value is set on the control interface.
+
+Payload: 148 bytes for GSM, 444 bytes for EDGE::
+Contains the downlink burst. Each hard-bit (1 or 0) of the burst is represented
+using one byte (0x01 or 0x00 respectively).
diff --git a/configure.ac b/configure.ac
index 9858af6..1017e9c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -28,6 +28,15 @@ then
AC_MSG_ERROR("missing dependencies!")
fi
+# Asciidoc warnings check (OS#4140)
+AC_ARG_ENABLE(asciidoc_warnings_check,
+ [AS_HELP_STRING(
+ [--enable-asciidoc-warnings-check],
+ [Fail the build if asciidoc prints any warnings]
+ )],
+ [asciidoc_warnings_check=$enableval], [asciidoc_warnings_check="no"])
+AM_CONDITIONAL([ASCIIDOC_WARNINGS_CHECK], [test x"$asciidoc_warnings_check" = x"yes"])
+
AC_OUTPUT(
osmo-gsm-manuals.pc
Makefile
diff --git a/contrib/jenkins.sh b/contrib/jenkins.sh
index 7d4d8df..cf709b2 100755
--- a/contrib/jenkins.sh
+++ b/contrib/jenkins.sh
@@ -12,9 +12,10 @@ fi
osmo-clean-workspace.sh
autoreconf -fi
-./configure
+./configure --enable-asciidoc-warnings-check
$MAKE $PARALLEL_MAKE
$MAKE $PARALLEL_MAKE check
$MAKE $PARALLEL_MAKE distcheck
+$MAKE maintainer-clean
osmo-clean-workspace.sh
diff --git a/debian/changelog b/debian/changelog
index 65f1046..4b35c12 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,22 @@
+osmo-gsm-manuals-dev (0.2.0) unstable; urgency=medium
+
+ [ Oliver Smith ]
+ * contrib/jenkins.sh: run "make maintainer-clean"
+ * tests: pick up subdirs inside common/chapters
+ * Makefile.asciidoc.inc: always run verbose asciidoc
+ * Makefile.asciidoc.inc: warnings check not default
+
+ [ Pau Espin Pedrol ]
+ * Makefile.asciidoc.inc: Export commondir attribute to asciidoc files
+ * common: Introduce Osmux documentation
+ * common: trx_if.adoc: Improve documentation
+ * common: trx_if.adoc: Add documentation about TRXDv1 and SETFORMAT
+
+ [ Daniel Willmann ]
+ * counters-overview: Add a section about the stats reporter
+
+ -- Pau Espin Pedrol <pespin@sysmocom.de> Thu, 08 Aug 2019 12:07:24 +0200
+
osmo-gsm-manuals-dev (0.1.1) unstable; urgency=medium
[ Daniel Willmann ]
diff --git a/tests/Makefile.am b/tests/Makefile.am
index 7dc9544..b2f579d 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -9,7 +9,8 @@ OSMO_GSM_MANUALS_NO_INSTALL = 1
# Generate adoc file that includes all chapters
ASCIIDOC = test-usermanual.adoc
ASCIIDOC_DEPS =
-$(ASCIIDOC): $(OSMO_GSM_MANUALS_DIR)/common/chapters/*.adoc
+COMMON_CHAPTERS = $(shell find $(OSMO_GSM_MANUALS_DIR)/common/chapters -name '*.adoc')
+$(ASCIIDOC): $(COMMON_CHAPTERS)
echo ":gfdl-enabled:" > $@
echo ":program-name: Test" >> $@
echo "" >> $@
@@ -17,7 +18,7 @@ $(ASCIIDOC): $(OSMO_GSM_MANUALS_DIR)/common/chapters/*.adoc
echo "====================================" >> $@
echo "Oliver Smith <osmith@sysmocom.de>" >> $@
echo "" >> $@
- for chapter in $(OSMO_GSM_MANUALS_DIR)/common/chapters/*.adoc; do \
+ for chapter in $(COMMON_CHAPTERS); do \
echo "include::$${chapter}[]" >> $@; \
done;
CLEAN_FILES = $(ASCIIDOC)