falconia has uploaded this change for review.
beginning of twrtp documentation
Change-Id: I90976edfd8c66c2d1c5bc7939e0a49f725a02f3f
---
M Makefile.am
M configure.ac
A doc/Makefile.am
A doc/manuals/Makefile.am
A doc/manuals/twrtp-guide-docinfo.xml
A doc/manuals/twrtp-guide.adoc
6 files changed, 267 insertions(+), 1 deletion(-)
git pull ssh://gerrit.osmocom.org:29418/libosmo-netif refs/changes/91/39291/1
diff --git a/Makefile.am b/Makefile.am
index fd03b74..defd38e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,7 +1,7 @@
AUTOMAKE_OPTIONS = foreign dist-bzip2 1.6
ACLOCAL_AMFLAGS = -I m4
-SUBDIRS = include src examples utils tests
+SUBDIRS = include src doc examples utils tests
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = libosmo-netif.pc
diff --git a/configure.ac b/configure.ac
index 9b52901..8ee5a4d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -126,12 +126,56 @@
AC_PATH_PROG(DOXYGEN,doxygen,false)
AM_CONDITIONAL(HAVE_DOXYGEN, test $DOXYGEN != false && test "x$doxygen" = "xyes")
+# Generate manuals
+AC_ARG_ENABLE(manuals,
+ [AS_HELP_STRING(
+ [--enable-manuals],
+ [Generate manual PDFs [default=no]],
+ )],
+ [osmo_ac_build_manuals=$enableval], [osmo_ac_build_manuals="no"])
+AM_CONDITIONAL([BUILD_MANUALS], [test x"$osmo_ac_build_manuals" = x"yes"])
+AC_ARG_VAR(OSMO_GSM_MANUALS_DIR, [path to common osmo-gsm-manuals files, overriding pkg-config and "../osmo-gsm-manuals"
+ fallback])
+if test x"$osmo_ac_build_manuals" = x"yes"
+then
+ # Find OSMO_GSM_MANUALS_DIR (env, pkg-conf, fallback)
+ if test -n "$OSMO_GSM_MANUALS_DIR"; then
+ echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from env)"
+ else
+ OSMO_GSM_MANUALS_DIR="$($PKG_CONFIG osmo-gsm-manuals --variable=osmogsmmanualsdir 2>/dev/null)"
+ if test -n "$OSMO_GSM_MANUALS_DIR"; then
+ echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from pkg-conf)"
+ else
+ OSMO_GSM_MANUALS_DIR="../osmo-gsm-manuals"
+ echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (fallback)"
+ fi
+ fi
+ if ! test -d "$OSMO_GSM_MANUALS_DIR"; then
+ AC_MSG_ERROR("OSMO_GSM_MANUALS_DIR does not exist! Install osmo-gsm-manuals or set OSMO_GSM_MANUALS_DIR.")
+ fi
+
+ # Find and run check-depends
+ CHECK_DEPENDS="$OSMO_GSM_MANUALS_DIR/check-depends.sh"
+ if ! test -x "$CHECK_DEPENDS"; then
+ CHECK_DEPENDS="osmo-gsm-manuals-check-depends"
+ fi
+ if ! $CHECK_DEPENDS; then
+ AC_MSG_ERROR("missing dependencies for --enable-manuals")
+ fi
+
+ # Put in Makefile with absolute path
+ OSMO_GSM_MANUALS_DIR="$(realpath "$OSMO_GSM_MANUALS_DIR")"
+ AC_SUBST([OSMO_GSM_MANUALS_DIR])
+fi
+
AC_OUTPUT(
libosmo-netif.pc
include/Makefile
include/osmocom/Makefile
include/osmocom/netif/Makefile
src/Makefile
+ doc/Makefile
+ doc/manuals/Makefile
examples/Makefile
utils/Makefile
tests/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..f2c4de1
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = manuals
diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
new file mode 100644
index 0000000..800d0e1
--- /dev/null
+++ b/doc/manuals/Makefile.am
@@ -0,0 +1,9 @@
+EXTRA_DIST = twrtp-guide-docinfo.xml twrtp-guide.adoc
+
+if BUILD_MANUALS
+ ASCIIDOC = twrtp-guide.adoc
+ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+
+ OSMO_REPOSITORY = libosmo-netif
+ include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
+endif
diff --git a/doc/manuals/twrtp-guide-docinfo.xml b/doc/manuals/twrtp-guide-docinfo.xml
new file mode 100644
index 0000000..3537c23
--- /dev/null
+++ b/doc/manuals/twrtp-guide-docinfo.xml
@@ -0,0 +1,22 @@
+
+<authorgroup>
+ <author>
+ <firstname>Mychaela</firstname>
+ <surname>Falconia</surname>
+ <email>falcon@freecalypso.org</email>
+ <authorinitials>MNF</authorinitials>
+ <affiliation>
+ <shortaffil>SD2G</shortaffil>
+ <orgname>San Diego 2G Association</orgname>
+ <jobtitle>Founder and CTO</jobtitle>
+ </affiliation>
+ </author>
+</authorgroup>
+
+<legalnotice>
+ <para>
+ The author of this document is a stateless person who does not
+ participate in the institution of copyright. This document
+ is in the public domain.
+ </para>
+</legalnotice>
diff --git a/doc/manuals/twrtp-guide.adoc b/doc/manuals/twrtp-guide.adoc
new file mode 100644
index 0000000..2d1dce4
--- /dev/null
+++ b/doc/manuals/twrtp-guide.adoc
@@ -0,0 +1,190 @@
+= Guide to ThemWi RTP endpoint library
+
+The RTP implementation library described in this document was developed by
+Mother Mychaela N. Falconia under Themyscira Wireless branding and then
+contributed to Osmocom in 2025. It is currently under consideration for
+merging into `libosmo-netif`; once merged, it will be automatically available
+to any application that is built with the standard suite of Osmocom libraries.
+
+This document is written to describe the library as it will appear and
+function if the proposal to merge it into `libosmo-netif` is accepted.
+
+== Introduction
+
+ThemWi RTP endpoint library, consisting of `<osmocom/netif/twrtp.h>` and
+`<osmocom/netif/twjit.h>` blocks provided by `libosmo-netif`, is intended
+for interworking between an RTP stream and a fixed timing system such as
+GSM Um interface TCH or T1/E1 TDM. Such interworking consists of two
+fundamental elements:
+
+* In every fixed time quantum, the interworking element receives a unit of
+ speech or CSData media from the fixed source and emits an RTP packet
+ carrying that quantum of speech or CSData.
+
+* In the opposite direction, the fixed timing system requires a quantum of
+ speech or CSData to be fed to it on every tick without fail, yet the
+ interworking element has no control over when RTP packets may arrive
+ from the IP network. This direction of interworking requires a rather
+ complex element called a jitter buffer, an element whose design and
+ configuration always involves some trade-offs and compromises.
+
+=== Domain of application
+
+The present library is *not* intended to be an all-purpose implementation
+of IETF RFCs 3550 and 3551, supporting all possible RTP use cases as
+envisioned by IETF. Instead it is intended to support RTP _as it is used_
+in these two specific telecom network environments:
+
+* 3GPP networks that use RTP according to TS 26.102 and TS 48.103;
+
+* The way RTP is used to transport G.711 PSTN traffic across the public
+ Internet in what may be colloquially referred to as IP-PSTN.
+
+The two 3GPP specs referenced above prescribe a fixed packetization time
+of 20 ms for all codecs on AoIP interface. Furthermore, they stipulate
+that:
+
+* In the case of compressed speech transport, each RTP packet carries
+ exactly one frame of the speech codec in use;
+
+* In the case of uncompressed G.711 speech or CSData transport, each RTP
+ packet carries exactly 160 payload octets (20 ms worth) of what would
+ have been a 64 kbit/s timeslot in T1/E1 transport.
+
+This fixed-quantum property, namely the property that every RTP packet
+carries exactly one fixed quantum of speech or CSData, where the duration
+of this quantum is known at connection setup time and cannot suddenly
+change from one packet to the next, is required by the present ThemWi
+RTP endpoint library - this requirement constitutes a fundamental aspect
+of its architectural design.
+
+An RTP endpoint implementation library that imposes the just-described
+requirement is sufficient for the purpose of building IP-based GSM networks
+that follow 3GPP TS 48.103 (the requirements of that spec are in agreement
+with the library constraint), and it is also sufficient for interfacing
+to IP-PSTN by way of common commercial PSTN-via-SIP connectivity providers.
+
+In the case of IP-PSTN, the author of the present library has experience
+only with North American PSTN-via-SIP connectivity providers. In all
+of our operational experience so far, these IP-PSTN connectivity providers
+behave in ways that are fully compatible with the expectations of the
+present RTP library, as long as the following conditions are met:
+
+* No attempt is made to use any codecs other than PCMU or PCMA:
+ don't include any other codecs in the SDP offer, and send only SDP answers
+ that select either PCMU or PCMA out of the received multi-codec offer.
+
+* No attempt is made to use any other `ptime` besides the most common
+ industry standard of 20 ms.
+
+In all operational experience so far, incoming INVITE SDPs indicate either
+`a=ptime:20` or `a=maxptime:20`, and when we indicate `a=ptime:20` in all
+SDPs we send out, the IP-PSTN peer always sends us 20 ms RTP packets,
+as opposed to some other packetization interval which would break
+the fixed-quantum model assumed by the present RTP library.
+
+However, it needs to be acknowledged that the present library is *not*
+suitable for general-purpose, IETF-style applications outside of
+``walled garden'' 3GPP networks or the semi-walled environment of
+IP-PSTN with ``well-behaved'' entities: there are many behaviors that
+are perfectly legal per the RFCs, but are not supported by the present
+library. Having a peer send RTP with a packetization interval that is
+different from what we asked for via `ptime` attribute is one of those
+behaviors that is allowed by IETF, but not supported by this library.
+
+=== Configurable quantum duration and time scale
+
+For every RTP stream it handles, the library needs to know two key
+parameters:
+
+* The scale or ``clock rate'' used for RTP timestamps, i.e., how many
+ timestamp units equal one millisecond of physical time;
+
+* The ``quantum'' duration in milliseconds.
+
+*Quantum* is the term used in this RTP endpoint library for the unit
+of speech or CSData carried in one RTP packet. In Kantian philosophy terms,
+a quantum of speech or CSData is the thing-in-itself (a single codec frame,
+or a contiguous chunk of 160 PCM samples grabbed from an ISDN B channel),
+whereas the RTP packet that carries said quantum is one particular transport
+representation of that thing-in-itself.
+
+In most applications of this library (all 3GPP codecs other than AMR-WB,
+and all IP-PSTN applications in our experience so far), the time scale
+is 8000 timestamp units per second (or 8 per millisecond, as it appears
+in the actual APIs) and the time duration of a single quantum is 20 ms,
+hence one quantum equals 160 timestamp units.
+Both parameters (RTP timestamp clock rate in kHz and the number of ms
+per quantum) are configurable at the time of endpoint creation, allowing
+RTP endpoints for AMR-WB, or perhaps G.711 or CSData applications with
+different packetization times - but they cannot be changed later in
+the lifetime of an allocated endpoint.
+
+For ease of exposition, the rest of this document will assume that
+one quantum equals 20 ms in time or 160 RTP timestamp units. If these
+numbers are different in your application, substitute accordingly.
+
+== Jitter buffer model
+
+In the interworking direction from incoming RTP to the fixed timing system,
+the latter will poll the RTP endpoint (or more precisely, the jitter buffer
+portion thereof) for a quantum of media every 20 ms, whenever that quantum
+is required for transmission on GSM Um TCH or for TDM output etc.
+The job of the jitter buffer is to match previously received RTP packets
+to these fixed-timing output polls, while striving to meet these two
+conflicting goals:
+
+* Any time that elapses between an RTP packet being received and its
+ payload being passed as a quantum to the fixed timing system constitutes
+ added latency - which needs to be minimized.
+
+* IP-based transport always involves some jitter: the time delta between
+ the receipt of one RTP packet and the arrival of its successor is very
+ unlikely to be exactly equal to 20 ms every time. This jitter may be
+ already present in the RTP stream from its source if that source is
+ an IP-native BTS that does not pass through E1 Abis and thus exposes
+ the inherent jitter of GSM TDMA multiframe structure, but even if
+ the source is perfectly timed, some jitter will still be seen on the
+ receiving end. Depending on the actual amount of jitter seen in a
+ given deployment, it may be necessary to introduce some latency-adding
+ buffering in the receiving RTP endpoint - otherwise the function of
+ interworking to the fixed timing system at the destination will perform
+ poorly, as will be seen in the ensuing sections.
+
+This chapter covers the design and operation of `twjit`, the jitter buffer
+component of ThemWi RTP endpoint library.
+
+=== Flows and handovers
+
+In `twjit` terminology, a single RTP flow is a portion (or the whole)
+of an RTP stream that exhibits the following two key properties:
+
+* All packets have the same SSRC;
+
+* The RTP timestamp increment from each packet to the next always equals
+ the fixed quantum duration expressed in timestamp units, i.e., 160
+ in most practical applications.
+
+A handover in `twjit` terminology is a point in the incoming RTP stream
+at which either of the following events occurs:
+
+* An SSRC change is seen;
+
+* The RTP timestamp advances by an increment that is not an integral multiple
+ of the expected fixed quantum duration. In contrast, if an RTP timestamp
+ increment is seen that _is_ an integral multiple of the quantum, but that
+ integral multiple is more than one, and there is enough buffering in the
+ system such that this event is seen before the jitter buffer underruns,
+ such events are *not* treated as handovers: instead it is assumed to be
+ an occurrence of either packet loss or reordering.
+
+A handover in `twjit` is thus a transition from one flow to the next.
+This term was adopted because such transitions are expected to occur
+when an RTP stream belonging to a single call switches from one BSS endpoint
+to another (in the same BSS or in a different one) upon radio handover events
+in GSM and other cellular networks, but handovers in `twjit` sense can also
+occur in other applications that aren't GSM. For example, if an IP-PSTN peer
+we are conversing with suddenly decides, for its own reasons known only to
+itself, to change its SSRC or jump its RTP output timescale, our `twjit`
+instance will treat that event as a handover.
+
To view, visit change 39291. To unsubscribe, or for help writing mail filters, visit settings.