Initial user manual for osmo-e1d

Still quite incomplete, but significantly better than nothing.

Change-Id: I42f8da1990092b5a3d8c63fde33e49978ad83281
This commit is contained in:
Harald Welte 2022-11-02 22:35:06 +01:00 committed by laforge
parent 533cf1e4d7
commit 03d9c3215c
10 changed files with 488 additions and 0 deletions

View File

@ -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

View File

@ -1,3 +1,4 @@
SUBDIRS = \
examples \
manuals \
$(NULL)

14
doc/manuals/Makefile.am Normal file
View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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[]

View File

@ -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.

View File

@ -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>

View File

@ -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[]