diff options
author | Harald Welte <laforge@osmocom.org> | 2022-11-02 22:35:06 +0100 |
---|---|---|
committer | laforge <laforge@osmocom.org> | 2022-11-07 10:26:37 +0000 |
commit | 03d9c3215c88aa41e5f9e5648ad9e0d022603489 (patch) | |
tree | 621c2d2321050111cd47b79e70079deb866c0ec2 | |
parent | 533cf1e4d70244c92086ae5b44d138cee6ffa694 (diff) |
Initial user manual for osmo-e1d
Still quite incomplete, but significantly better than nothing.
Change-Id: I42f8da1990092b5a3d8c63fde33e49978ad83281
-rw-r--r-- | configure.ac | 44 | ||||
-rw-r--r-- | doc/Makefile.am | 1 | ||||
-rw-r--r-- | doc/manuals/Makefile.am | 14 | ||||
-rw-r--r-- | doc/manuals/chapters/client-interface.adoc | 72 | ||||
-rw-r--r-- | doc/manuals/chapters/drivers.adoc | 85 | ||||
-rw-r--r-- | doc/manuals/chapters/overview.adoc | 105 | ||||
-rw-r--r-- | doc/manuals/chapters/running.adoc | 25 | ||||
-rw-r--r-- | doc/manuals/chapters/tdmoip.adoc | 68 | ||||
-rw-r--r-- | doc/manuals/osmoe1d-usermanual-docinfo.xml | 31 | ||||
-rw-r--r-- | doc/manuals/osmoe1d-usermanual.adoc | 43 |
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[] |