Initial user manual for osmo-e1d
Still quite incomplete, but significantly better than nothing. Change-Id: I42f8da1990092b5a3d8c63fde33e49978ad83281changes/22/30022/7
parent
533cf1e4d7
commit
03d9c3215c
44
configure.ac
44
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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
SUBDIRS = \
|
||||
examples \
|
||||
manuals \
|
||||
$(NULL)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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[]
|
||||
|
|
@ -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.
|
||||
|
|
@ -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>
|
||||
|
|
@ -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[]
|
||||
Loading…
Reference in New Issue