Initial user manual for osmo-e1d

Still quite incomplete, but significantly better than nothing.

Change-Id: I42f8da1990092b5a3d8c63fde33e49978ad83281

10 files changed, 488 insertions, 0 deletions

diff --git a/configure.ac b/configure.ac
index dbfd230..be8a094 100644
--- a/configure.ac
+++ b/configure.ac
@@ -75,6 +75,49 @@ then
 	CPPFLAGS="$CPPFLAGS $WERROR_FLAGS"
 fi
 
+
+# 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_ARG_ENABLE([external_tests],
 		AC_HELP_STRING([--enable-external-tests],
 				[Include the VTY/CTRL tests in make check [default=no]]),
@@ -118,6 +161,7 @@ AC_OUTPUT(
 	contrib/osmo-e1d.spec
 	doc/Makefile
 	doc/examples/Makefile
+	doc/manuals/Makefile
 	src/Makefile
 	src/octoi/Makefile
 	include/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8acb8f8..3cb405e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,3 +1,4 @@
 SUBDIRS = \
 	  examples \
+	  manuals \
 	  $(NULL)
diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
new file mode 100644
index 0000000..d389a6e
--- /dev/null
+++ b/doc/manuals/Makefile.am
@@ -0,0 +1,14 @@
+EXTRA_DIST = \
+    osmoe1d-usermanual.adoc \
+    osmoe1d-usermanual-docinfo.xml \
+    chapters \
+    $(NULL)
+
+if BUILD_MANUALS
+  ASCIIDOC = osmoe1d-usermanual.adoc
+  ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc
+  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+
+  OSMO_REPOSITORY = osmo-e1d
+  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
+endif
diff --git a/doc/manuals/chapters/client-interface.adoc b/doc/manuals/chapters/client-interface.adoc
new file mode 100644
index 0000000..5f5b523
--- /dev/null
+++ b/doc/manuals/chapters/client-interface.adoc
@@ -0,0 +1,72 @@
+[[e1dp]]
+== Client Interface
+
+This chapter documents the _Client interface_ which is used by
+application programs wanting to send and/or receive data on the E1
+circuits served by `osmo-e1d`.
+
+The interface is based on a `unix domain socket` and works in the
+following way:
+
+* `osmo-e1d` implements the server side of a unix domain socket
+
+* the application program acts as a client program establishing a socket
+  connection to the e1d unix domain socket
+* the application program preforms operations such as opening of a
+  specific E1 timeslot on a spcific line/interface.
+* `osmo-e1d` passes a file descriptor from the daemon to the client
+  application
+* the client application can read/write data from/to the E1 timeslot via
+  this file descriptor
+
+This architecture was chosen to allow for the _one file descriptor per
+timeslot_ paradigm that is known from other drivers, such as DAHDI.
+
+Each timeslot of each line on each interface can theoretically be opened
+by a different program.  This permits for example control/user plane
+splits like a signaling gateway + media gateway implemented as separate
+processes.
+
+When opening a timeslot, the client specifies the _mode_.
+
+* In _RAW mode_, the transparent 64kBps bit-stream is passed over the
+  per-timeslot file descriptor.  This is mostly used for B-channels /
+  user traffic.
+* In _HDLC-FCS mode_, a (software) HDLC processor is instantiated. It
+  performs flag sequence detection/generation and bit-stuffing.  This is
+  mostly used for D-channels / signalling.
+
+Details about the messaging on the unix domain socket can be found in
+the definitions contained in the `include/osmocom/e1d/proto.h` header
+file, as well as the doxygen API documentation generated from it.
+
+=== `libosmo-e1d` client library
+
+To simplify interfacing `osmo-e1d` from an application, there is a
+companion library called `libosmo-e1d`.
+
+It contains functions implementing the above-mentioned client interface
+protocol and prevents the application developer from having to implement
+the low-level bits of this interface.
+
+The library is licensed under GNU LGPL-3.0-or-later, which is a weak
+copyleft license that permits using the library from non-open-source /
+proprietary applications.
+
+The library offers the following functions:
+
+* initialization / teardown
+** `osmo_e1dp_client_create()`
+** `osmo_e1dp_client_destroy()`
+* information querying
+** `osmo_e1dp_client_intf_query()`
+** `osmo_e1dp_client_line_query()`
+** `osmo_e1dp_client_ts_query()`
+* configuration
+** `osmo_e1dp_client_line_config()`
+* opening of timeslots
+** `osmo_e1dp_client_ts_open()`
+** `osmo_e1dp_client_ts_open_force()`
+
+Details about those functions can be found in the definitions contained
+in the `include/osmocom/e1d/proto_clnt.h` header file.
diff --git a/doc/manuals/chapters/drivers.adoc b/doc/manuals/chapters/drivers.adoc
new file mode 100644
index 0000000..e4a3858
--- /dev/null
+++ b/doc/manuals/chapters/drivers.adoc
@@ -0,0 +1,85 @@
+[[drivers]]
+== E1 drivers
+
+`osmo-e1d` was primarily developed for the icE1usb hardware, but also
+supports some other drivers by now.
+
+
+=== The `usb` driver for icE1usb and e1-tracer
+
+The `usb` driver implements the USB interface first implemented by the
+`icE1usb` hardware.
+
+For more information on the `icEusb`, please see its related user
+manual, published at https://downloads.osmocom.org/docs/latest/icE1usb-usermanual.pdf
+
+Each `icEusb` device implements one E1 interface with up to two E1
+lines.  Note that supporting two E1 lines is only supported on very few
+select USB host controllers. In most cases, your USB host controller
+will only permit using one of the two lines.
+
+==== Configuration
+
+`osmo-e1d` will automatically detect any supported USB devices when
+starting up. It will dynamically allocate E1 interface and E1 line
+numbers to those USB devices.  However, the order is not guaranteed and
+particularly in case you have multiple devices, it is strongly
+recommended to use _static configuration_.
+
+In this static configuration, you would have a block like
+
+.Example configuration snippet for an icE1usb
+----
+ interface 2 icE1usb
+  usb-serial dc697407e7881531
+----
+
+This way you reserve/allocate the E1 interface number 2 for the icE1usb
+with serial number dc697407e7881531.  The Serial number is unique and
+stored in the iSerial string of the USB device descriptor.  You can for
+example use `lsusb -v -d 1d50: | grep iSerial` to obtain it, or check
+the `dmesg` kernel log after plugging in a device.
+
+==== Using the `usb` driver with `e1-tracer`
+
+The same driver has been slightly extended to also support the passive,
+bi-directional `e1-tracer` hardware.  The configuration and use is
+identical to the use with the `icE1usb`, with the notable difference
+that a passive tracer can obviously only receive data from E1, but not
+transmit.  The two directions of a E1 circuit are represented as two
+lines in `osmo-e1d`.
+
+=== The `vpair` driver for virtual E1 circuits
+
+Sometimes it is useful to be able to interface multiple E1-using
+applications without a real E1 circuit or any hardware whatsoever.
+
+This can be used in automatic / virtualized software testing, but also
+in case a legacy application is migrate away from real physical E1
+circuits.
+
+==== Configuration
+
+The configuration of the `vpair` driver is relatively simple.  It
+consists of a single `virtual-e1-pair` command.
+
+.Example configuration snippet for a virtual E1 pair with one E1 line
+----
+e1d
+ virtual-e1-pair 1
+----
+
+The above example will create a virtual pair of E1 interfaces, each
+of those interface with one E1 line.
+
+.Log output of the example configuration for 1 virtual pair
+----
+intf_line.c:184 (I0) Created
+intf_line.c:285 (I0:L0) Created
+intf_line.c:184 (I1) Created
+intf_line.c:285 (I1:L0) Created
+----
+
+You can subsequently use the Lines just like you would use physical E1
+lines.  Any data you transmit on one line will be received on the other
+line, and vice versa.
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..0b17357
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,105 @@
+== Overview
+
+=== About this manual
+
+This manual should help you getting started with the `osmo-e1d` software.
+It will cover aspects of configuring and running `osmo-e1d` as well as some
+introduction about its internal architecture and external interfaces.
+
+=== About `osmo-e1d`
+
+`osmo-e1d` is a driver (implemented as userspace daemon) for a variety of hardware
+related to the E1 (TDM) interface, such as
+
+* the `icEusb` USB attached E1 interface
+* the `e1-tracer` USB attached passive E1 tracer
+
+=== Credits
+
+`osmo-e1d` was originally developed in 2019 by Sylvain Munaut alongside
+the icE1usb project. It subsequently got improved and extended by Harald
+Welte.
+
+=== Architecture
+
+`osmo-e1d` is a driver system for E1 circuits, which are sometimes also called
+primary rate (PRI). It typically sits between an E1 hardware interface beneath
+it and application software above it.
+
+.How osmo-e1d fits in the overall system architecture
+[graphviz]
+----
+digraph G{
+  //rankdir = LR;
+  Application -> loa;
+  pipe -> e1d [style=dashed];
+  loa -> e1d;
+
+  e1d -> HW;
+  e1d -> vpair;
+
+  HW -> BTS;
+
+  {rank=same;
+   Application [label="Application\nosmo-nitb / osmo-bsc"];
+   pipe [label="osmo-e1d-pipe\nfor testing", style=dashed];
+  }
+  e1d [label="osmo-e1d", color=red];
+  loa [label="libosmo-abis\ne1_input"];
+  HW [label="E1 Hardware"];
+  vpair [label="Virtual E1 pair"];
+}
+----
+
+Contrary to older E1 drivers such as DAHDI or mISDN, `osmo-e1d` runs entirely in userspace,
+without a need for kernel drivers.  This is obviously less computationally efficient,
+but has other advantages, such as working on unmodified Linux kernels / operating systems,
+and with a lower risk of software bugs affecting overall system
+stability.  Particularly at low E1 port density and modern hardware, the
+lower efficiency is not expected to make a big difference.
+
+==== E1 Interfaces
+
+In `osmo-e1d` language, an _E1 Interface_ is some kind of underlying hardware that contains one or more
+_Lines_.  Interfaces are numbered from 0..N and are often abbreviated e.g. as `I0` for Interface 0.
+
+==== E1 Lines
+
+In `osmo-e1d` language, an _E1 Line_ represents one single E1 circuit within an _E1 Interface_.
+
+=== Hardware support
+
+`osmo-e1d` currently supports the following hardware:
+
+* Osmocom icE1usb
+* Osmocom e1-tracer
+* Virtual pair of E1 circuits
+
+==== icE1usb
+
+The Osmocom icE1usb is an OSHW implementation of a USB-attached hardware
+interface for up to two E1 circuits (lines).
+
+For more information on the Osmocom icE1usb, see
+
+* data sheet: https://www.sysmocom.de/downloads/icE1usb_data_sheet.pdf
+* project wiki: https://osmocom.org/projects/e1-t1-adapter/wiki/ICE40_E1_USB_interface
+* user manual: https://ftp.osmocom.org/docs/latest/icE1usb-usermanual.pdf
+* product page: https://www.sysmocom.de/products/lab/icE1usb
+
+==== e1-tracer
+
+The Osmocom e1-tracer is an OSHW implementation of a passive,
+high-impedance bi-directional E1 tap/tracer/sniffer.  It can be used to
+capture traffic on an unmodified E1 interface.
+
+For more information on the Osmocom e1-tracer, see
+
+* project wiki: https://osmocom.org/projects/e1-t1-adapter/wiki/E1_tracer
+* user manual: https://ftp.osmocom.org/docs/latest/e1tracer-usermanual.pdf
+
+==== vpair
+
+The osmo-e1d _vpair_ is not actual hardware, but a virtual pair of E1
+interfaces.  It can be used to test E1-using applications without
+involving a hardware E1 circuit.
diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc
new file mode 100644
index 0000000..f1841fd
--- /dev/null
+++ b/doc/manuals/chapters/running.adoc
@@ -0,0 +1,25 @@
+[[running]]
+== Running osmo-e1d
+
+The `osmo-e1d` executable offers the following command-line arguments:
+
+=== SYNOPSIS
+
+*osmo-e1d* [-h] [-d 'DBGMASK'] [-c 'CONFIGFILE']
+
+=== OPTIONS
+
+*-h, --help*::
+        Print a short help message about the supported options.
+*-V, --version*::
+        Print the version of osmo-e1d.
+*-d, --debug 'DBGMASK','DBGLEVELS'*::
+        Set the log subsystems and levels for logging to stderr. This
+        has mostly been superseded by VTY-based logging configuration,
+        see <<logging>> for further information.
+*-c, --config-file 'CONFIGFILE'*::
+        Specify the file and path name of the configuration file to be
+        used. If none is specified, use `osmo-bsc.cfg` in the current
+        working directory.
+
+include::../common/snippets/systemd.adoc[]
diff --git a/doc/manuals/chapters/tdmoip.adoc b/doc/manuals/chapters/tdmoip.adoc
new file mode 100644
index 0000000..862cd76
--- /dev/null
+++ b/doc/manuals/chapters/tdmoip.adoc
@@ -0,0 +1,68 @@
+[[octoi]]
+== OCTOI TDMoIP mode
+
+Instead of providing a programmatic client interface (<<client>>) enabling
+external applications timeslot-granular access to the data of a E1 line,
+`osmo-e1d` also supports an entirely separate mode of operation:
+_TDMoIP using the OCTOI (Osmocom Community TDMoIP) protocol_.
+
+In this mode of operation, osmo-e1d acts as interface between an E1 line
+and a remote system over UDP/IP.  This allows you to transparently pass
+an E1 line over an IP network such as the Internet.
+
+`osmo-e1d` can operate either as client or as server for the OCTOI protocol.
+
+=== osmo-e1d as OCTOI client
+
+Below is an example configuration snippet for operating as an OCTOI client.
+
+.Configuration snippet for operating as an OCTOI client
+----
+e1d
+ interface 0 icE1usb
+  usb-serial dc697407e7881531
+  line 0
+   mode e1oip <1>
+octoi-client 192.168.7.2 10013 <2>
+ local-bind 0.0.0.0 3333 <3>
+ account foobar <4>
+  mode ice1usb
+  ice1usb serial-number dc697407e7881531 <5>
+  ice1usb line-number 0
+----
+<1> we specify that Interface 0 Line 0 (I0:L0) of the icE1usb device with serial number dc697407e7881531 shall
+    be used in `e1oip` mode.
+<2> we instantiate an OCTOI client to the remote IP 192.168.7.2 / UDP port 10013
+<3> we specify to bind locally to INADDR_ANY and local UDP port 3333
+<4> we specify the account/user name to tell the server is `foobar`
+<5> we specify that this OCTOI client instance shall use the icE1usb device with the given serial number. This
+    must match the serial number used above when configuring the icE1usb line mode.
+
+There can of course be any number of E1 interfaces/lines and clients; the example just shows one for clarity.
+
+=== osmo-e1d as OCTOI server
+
+Below is an example configuration snippet for operating as an OCTOI server.
+
+.Configuration snippet for operating as an OCTOI server
+----
+e1d
+ interface 0 icE1usb
+  usb-serial dc697407e7881531
+  line 0
+   mode e1oip <1>
+octoi-server
+ local-bind 0.0.0.0 10013 <2>
+ account foobar <3>
+  mode ice1usb
+  ice1usb serial-number dc697407e7881531 <4>
+  ice1usb line-number 0
+----
+<1> we specify that Interface 0 Line 0 (I0:L0) of the icE1usb device with serial number dc697407e7881531 shall
+    be used in `e1oip` mode.
+<2> we bind the OCTOI server to UDP port 9999 of INADDR_ANY
+<3> we specify a user account `foobar`
+<4> we connect the user account `foobar` to the icE1usb serial number / line number specified above
+
+There can of course be any number of E1 interfaces/lines and user accounts; the example just shows one for
+clarity.
diff --git a/doc/manuals/osmoe1d-usermanual-docinfo.xml b/doc/manuals/osmoe1d-usermanual-docinfo.xml
new file mode 100644
index 0000000..714989b
--- /dev/null
+++ b/doc/manuals/osmoe1d-usermanual-docinfo.xml
@@ -0,0 +1,31 @@
+
+<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>2016-2022</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>
+</legalnotice>
diff --git a/doc/manuals/osmoe1d-usermanual.adoc b/doc/manuals/osmoe1d-usermanual.adoc
new file mode 100644
index 0000000..58bd20f
--- /dev/null
+++ b/doc/manuals/osmoe1d-usermanual.adoc
@@ -0,0 +1,43 @@
+:gfdl-enabled:
+
+osmo-e1d User Manual
+====================
+Harald Welte <hwelte@sysmocom.de>
+
+include::./common/chapters/preface.adoc[]
+
+include::{srcdir}/chapters/overview.adoc[]
+
+include::./common/chapters/installation.adoc[]
+
+include::{srcdir}/chapters/running.adoc[]
+
+include::{srcdir}/chapters/client-interface.adoc[]
+
+include::{srcdir}/chapters/drivers.adoc[]
+
+include::{srcdir}/chapters/tdmoip.adoc[]
+
+//include::{srcdir}/chapters/control.adoc[]
+
+include::./common/chapters/counters-overview.adoc[]
+
+//include::{srcdir}/chapters/counters.adoc[]
+
+include::./common/chapters/vty.adoc[]
+
+include::./common/chapters/logging.adoc[]
+
+//include::{srcdir}/chapters/configuration.adoc[]
+
+include::./common/chapters/vty_cpu_sched.adoc[]
+
+//include::./common/chapters/control_if.adoc[]
+
+include::./common/chapters/port_numbers.adoc[]
+
+include::./common/chapters/bibliography.adoc[]
+
+include::./common/chapters/glossary.adoc[]
+
+include::./common/chapters/gfdl.adoc[]