doc/e1-tracer: Add an initial e1-tracer user manual
Change-Id: I9413195d69325ba74b3993e6ec7a1fc7628b5dd1
diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile
index 63bd422..53cb8ff 100644
--- a/doc/manuals/Makefile
+++ b/doc/manuals/Makefile
@@ -2,8 +2,9 @@
srcdir = .
-ASCIIDOC = icE1usb-usermanual.adoc
+ASCIIDOC = icE1usb-usermanual.adoc e1-tracer-usermanual.adoc
include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
icE1usb-usermanual.pdf: chapters/icE1usb/*.adoc
+e1-tracer-usermanual.pdf: chapters/e1-tracer/*.adoc
include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
diff --git a/doc/manuals/chapters/e1-tracer/firmware.adoc b/doc/manuals/chapters/e1-tracer/firmware.adoc
new file mode 100644
index 0000000..737f30a
--- /dev/null
+++ b/doc/manuals/chapters/e1-tracer/firmware.adoc
@@ -0,0 +1,199 @@
+[[firmware]]
+== e1-tracer Firmware
+
+The e1-tracer _firmware_ is a small amount of bare-iron software running
+on the picoRISCV soft-core of the _gateware_.
+
+It mainly consists of drivers for the no2e1 E1 Framer IP core and the
+no2usb USB Device IP core which are part of the gateware described in
+<<gateware>>.
+
+=== Firmware Upgrade (DFU)
+
+e1-tracer contains support for the USB DFU (Device Firmware Upgrade)
+standard.
+
+As such, you can use any USB DFU compliant utility to upgrade the
+firmware of the e1-tracer device.
+
+DFU mode can be entered in two ways:
+
+1. by performing a DFU detach from the normal application firmware
+ (obviously that requires a [still] working firmware present on the
+ device). To do so, please use `dfu-util -e`
+
+2. by pushing the push-button (see <<hw-pushbutton>>) during power-up.
+ Simply disconnect the USB cable, then push that button and keep it
+ pushed while re-attaching the USB cable.
+
+The e1-tracer boot loader enumerates as VID:PID `1d50:6150`, while the
+normal application firmware enumerates as `1d50:6151`,
+
+You can for example use `lsusb` to check the VID:PID:
+
+.Example output of `dfu-util` on a system with e1-tracer attached
+----
+$ lsusb -d 1d50:
+Bus 001 Device 042: ID 1d50:6151<1> OpenMoko, Inc. e1-tracer
+$ sudo dfu-util -d 1d50:6151 -e <2>
+...
+$ lsusb -d 1d50:
+Bus 001 Device 043: ID 1d50:6150<3> OpenMoko, Inc. e1-tracer (DFU)
+----
+<1> initially the device is in normal runtime mode
+<2> we use `dfu-util -e` to switch to DFU mode
+<3> we can see, the device is now in DFU mode
+
+==== Obtaining firmware upgrades
+
+The latest firmware can be found at
+https://ftp.osmocom.org/binaries/e1-tracer/firmware/latest/
+a backlog of earlier builds can be found at
+https://ftp.osmocom.org/binaries/e1-tracer/firmware/all/
+
+The latest gateware can currently only be found at the personal developer
+directory of tnt at https://people.osmocom.org/tnt/e1-tracer/e1-tracer-gw-c7566442.bin
+A more official download location for the gateware will be provided shortly.
+
+==== Upgrading the FPGA gateware
+
+Gateware files are called `e1-tracer-gw-*.bin`. (without 'fw' in the name)
+
+The gateware can be upgraded by accessing the DFU _altsetting 0_ using `dfu-util` *`-a 0`*
+
+Assuming you already are in DFU mode, you would typically use a command
+like `dfu-util -d 1d50:6150 -a 0 -D e1-tracer-gw-c7566442.bin -R` to perform the upgrade.
+
+NOTE: The `-R` will switch the device back to runtime mode after the
+upgrade. If you want to upgrade the firmware in the same session, skip
+the `-R` in the above command.
+
+==== Upgrading the picoRISCV firmware
+
+Firmware files are called `e1_tracer-fw*.bin`.
+
+The firmware can be upgraded by accessing the DFU _altsetting 1_ using `dfu-util` *`-a 1`*
+
+Assuming you already are in DFU mode, you would typically use a command
+like `dfu-util -d 1d50:6150 -a 1 -D e1_tracer-fw-0.1-132-ga0df047.bin -R` to perform the upgrade.
+
+.Typical output during upgrade of the firmware
+----
+$ sudo dfu-util -d 1d50:6150 -a 1 -D e1_tracer-fw-0.1-132-ga0df047.bin -R
+dfu-util 0.9
+
+Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
+Copyright 2010-2016 Tormod Volden and Stefan Schmidt
+This program is Free Software and has ABSOLUTELY NO WARRANTY
+Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
+
+dfu-util: Invalid DFU suffix signature
+dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
+Opening DFU capable USB device...
+ID 1d50:6150
+Run-time device DFU version 0101
+Claiming USB DFU Interface...
+Setting Alternate Setting #1 ...
+Determining device status: state = dfuIDLE, status = 0
+dfuIDLE, continuing
+DFU mode device DFU version 0101
+Device returned transfer size 4096
+Copying data from PC to DFU device
+Download [=========================] 100% 11256 bytes
+Download done.
+state(2) = dfuIDLE, status(0) = No error condition is present
+Done!
+Resetting USB to switch back to runtime mode
+----
+
+As the `-R` option was used, the device will reset and re-enumerate in
+the newly programmed firmware.
+
+You can verify this as follows:
+
+----
+$ lsusb -d 1d50:
+Bus 001 Device 042: ID 1d50:6151 OpenMoko, Inc. e1-tracer
+----
+
+or alternatively:
+
+----
+$ dfu-util -l -d 1d50:
+dfu-util 0.9
+
+Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
+Copyright 2010-2016 Tormod Volden and Stefan Schmidt
+This program is Free Software and has ABSOLUTELY NO WARRANTY
+Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
+
+Found Runtime: [1d50:6151] ver=0003, devnum=44, cfg=1, intf=1, path="1-2", alt=0, name="DFU runtime", serial="dc697407e7881531"
+----
+
+
+=== Use of the LEDs
+
+==== LOS LEDs
+
+Each E1 channel has one red *LOS LED*. They are red if either
+
+* the E1 framer has not yet been initialized (done by starting host software)
+* there is an actual LOS (Loss of Signal) condition in the respective direction
+
+
+==== Multi-Color RGB STATUS LED
+
+The multi-color RGB *STATUS LED* is used to indicate overall hardware/firmware status.
+
+[options="header",cols="10,10,60"]
+|===
+|Color | Pattern | Meaning
+|Red | On | E1 interface not active (no host software?)
+|Red | Blinking | E1 interface active, but error status (CRC, alignment)
+|Green | On | E1 Receiver B aligned
+|Green | Blinking | E1 Receiver A attempting to align
+|Blue | On | E1 Receiver B aligned
+|Blue | Blinking | E1 Receiver B attempting to align
+|Cyan | On | E1 Receiver A+B aligned
+|Cyan | Blinking | E1 Receiver A+B attempting to align
+|===
+
+
+
+=== Firmware - USB Host Interface
+
+The e1-tracer firmware provides a USB 1.1 full-speed (FS) device with two configurations
+
+* legacy configuration (for use with `e1-tracer-record`)
+** 2 interfaces
+*** combined interface for both E1 directions
+*** DFU (device firmware upgrade)
+* `osmo-e1d` compatible configuration
+* 2 interfaces
+** E1 direction A->B
+** E1 direction A<-B
+
+The configurations and interfaces have self-explanatory string descriptors like
+
+----
+ iInterface 8 E1 Direction A
+ iInterface 9 E1 Direction B
+----
+
+==== e1d compatible configuration: E1 ports
+
+There are two physical E1 ports in the e1-tracer. Each represents one direction
+of the traced E1 circuit. Each is exposed via its own USB _interface_.
+
+Each port/direction (USB _interface_) contains two _altsettings_:
+
+* one altsetting with no data endpoints (E1 tracing disabled, this is the default)
+* one altsetting with isochronous IN/OUT endpoints (E1 tracing enabled)
+
+In order to activate one E1 port, the driver must perform a USB standard
+request to activate the _enabled_ altsetting.
+
+==== DFU (Device Firmware Upgrade)
+
+There's a DFU interface available in order to update the e1-tracer
+gateware and firmware. For more information, see above.
diff --git a/doc/manuals/chapters/e1-tracer/gateware.adoc b/doc/manuals/chapters/e1-tracer/gateware.adoc
new file mode 100644
index 0000000..e0dc871
--- /dev/null
+++ b/doc/manuals/chapters/e1-tracer/gateware.adoc
@@ -0,0 +1,16 @@
+[[gateware]]
+== e1-tracer Gateware
+
+The e1-tracer _gateware_ is where pretty much everything happens,
+from the E1 Line Interface Unit to the E1 Framer/Deframer, the
+picoRISCV soft-core running the [[firmware]] as well as the USB
+device peripheral talking to the host PC.
+
+The gateware is stored in binary form on the device-internal
+non-volatile memory (SPI flash). It is field-upgradeable via USB.
+
+As an OSHW project, all of it is available in source code format
+at https://git.osmocom.org/osmo-e1-hardware/tree/gateware/e1-tracer
+
+Please use `git clone --recursive` when cloning the git repository
+so you get all of the sub-modules for the various soft-cores.
diff --git a/doc/manuals/chapters/e1-tracer/hardware.adoc b/doc/manuals/chapters/e1-tracer/hardware.adoc
new file mode 100644
index 0000000..1ba48df
--- /dev/null
+++ b/doc/manuals/chapters/e1-tracer/hardware.adoc
@@ -0,0 +1,123 @@
+[[hardware]]
+== e1-tracer Hardware
+
+The e1-tracer Hardware consists of a single circuit board, mechanically
+either assembled into a desktop enclosure (KOH variant) or into a 3U component
+carrier module (BGT variant).
+
+image::images/e1_tracer-bgt-front.jpg[width=400,title="e1-tracer BGT variant"]
+image::images/e1_tracer-koh1.jpg[width=400,title="e1-tracer KOH variant"]
+
+
+It's main building blocks are:
+
+* an iCE40 FPGA
+* two E1 Line Interface Unit ICs
+* two E1 line interface analog (transformers, biasing networks and ESD protection)
+
+=== Schematics / Board Layout
+
+As e1-tracer is an OSHW (Open Source Hardware) project, the full schematics
+and design files are publicly available.
+
+The design files in EAGLE format are available at https://git.osmocom.org/osmo-e1-hardware/tree/hardware/e1-tracer
+
+PDF rendered schematics are available at https://gitea.osmocom.org/retronetworking/osmo-e1-hardware/raw/branch/master/hardware/e1-tracer/e1-tracer_sch.pdf
+
+=== Connectors / LEDs
+
+image::images/e1-tracer-plate.png[width=400,title="front side of e1-tracer"]
+
+From left to right, there are the following LED indcators, connectors and buttons:
+
+* LED block with 4 LED's
+* Primary E1 Port (E1 A)
+* Secondary E1 Port (E1 B)
+* Serial Console Connector
+* USB Connector
+* Bootloader Button
+
+==== LEDs
+
+The left-most column of LEDs consists of two red *LOS LEDs*.
+They indicate a LOS (Loss Of Signal) condition for the respective E1 direction. It is normal for the LEDs to be illuminated even in presence of a valid E1 signal until the host software has fully initialized the firmware for the first time after power-up.
+
+The right column of LEDs consists of two further LEDs:
+
+* a multi-color *STATUS LED* on the top
+* a green *POWER LED* on the bottom
+
+The *STATUS LED* is used by the firmware to indicate a variety of status
+information. Pleas see the firmware documentation in <<firmware>>.
+
+The green *POWER LED* is illuminated as soon as the device has DC power.
+
+==== J1A and J1B: E1 Interface Connectors
+
+There are two RJ45 connectors next to each other.
+
+Those are the connections for your symmetric 120 Ohms E1 interface
+circuit. You insert the e1-tracer into your E1 link. The two ports are
+internally wired straight-through, so you can insert the e1-tracer into
+your E1 link.
+
+The actual tracing functionality is implemented via a high-impedance
+tap, which will not disturb the normal E1 communications link. The link
+remains unaffected even if the e1-tracer is unpowered.
+
+.Pin-out of RJ45 E1 connectors
+[options="header"]
+|===
+| Pin | Function (TE) | Function (NT Mode)
+| 1 | Pair A | Pair A
+| 2 | Pair A | Pair A
+| 3 | not used | not used
+| 4 | Pair B | Pair B
+| 5 | Pair B | Pair B
+| 7 | not used | not used
+| 8 | not used | not used
+|===
+
+NOTE: E1 cables use RJ45 like Ethernet, but Ethernet cables have a
+different pin-out. Particularly, you cannot use an Ethernet cross-over
+cable as an E1 cross-over!
+
+==== X1: USB Connector
+
+The USB connector is a USB Mini B connector. The e1-tracer uses
+USB 1.1 full-speed signals. As the e1-tracer is a bus-powered device,
+5V DC power is also sourced from this connector.
+
+==== X2: Serial Console Connector
+
+The serial console is used for development and debugging. It uses an
+Osmocom-style 2.5mm stereo TRS jack.
+
+The serial console uses 3.3V CMOS logic levels
+
+The serial console uses a rate of 1000000 bps.
+
+The pin-out is as follows:
+
+* Tip: Tx output from PC (Rx input of e1-tracer)
+* Ring: Rx input of PC (Tx output of e1-tracer)
+* Shield: GND
+
+A compatible cable can be sourced from the sysmocom web-shop at
+http://shop.sysmocom.de/.
+
+Note that CP2102 based cables require special programming to support
+the baud rate of 1000000 (as opposed to the more standard 921600).
+
+[[hw-pushbutton]]
+=== Bootloader Button
+
+There is a push-button next to the _USB B connector_. It is recessed
+to protect against accidental use. You will need to use a paper clip,
+pen tip or other similar object to push it.
+
+The button, when pressed while power-up, can be used to force booting
+into the DFU loader in order to recover from a broken firmware
+installation.
+
+
diff --git a/doc/manuals/chapters/e1-tracer/host-software.adoc b/doc/manuals/chapters/e1-tracer/host-software.adoc
new file mode 100644
index 0000000..585c4d2
--- /dev/null
+++ b/doc/manuals/chapters/e1-tracer/host-software.adoc
@@ -0,0 +1,291 @@
+== Host Software
+
+Host Software is software running on the USB host computer to which the
+e1-tracer is attached.
+
+At the time of this writing, there are two options:
+
+* legcay tools from the `software/e1-tracer` sub-directory of the `osmo-e1-hardware.git` repository
+* `osmo-e1d`
+
+=== Legacy Software
+
+The legacy software was the initial software developed for the
+e1-tracer. Its purpose was raw trace recording for later offline
+analysis.
+
+The source code of this software can be found in the
+`software/e1-tracer` sub-directory of the `osmo-e1-hardware.git`
+repository at https://gitea.osmocom.org/retronetworking/osmo-e1-hardware
+
+==== e1-tracer-record
+
+The `e1-tracer-record` program is used to create on-disk recordings of the
+full E1 interface in both directions.
+
+You can use `e1-trace-record` to obtain a raw recording using the osmo-e1-tracer.
+
+Once the program is started, it will open the USB device (via libusb), enable it
+and subsequently store all received E1 frames to a file on disk. The disk file format
+is a custom format containing chunks of data, each prefixed by a header containing
+metadata such as the receive timestamp and the direction of the data.
+
+The program supports the following command line arguments:
+
+.Command line arguments of `e1-tracer-record` program
+----
+ `-o FILE` the name of the output file to which the recording is to be stored.
+ `-a` append (instead of overwrite) the output file, if it already exists.
+ `-m` set the PHY into monitor (high-impedance) mode. You should always enable this.
+ `-r` use SCHED_RR *realtime* scheduling to reduce the likelihood of lost data on overloaded systems
+----
+
+A typical invocation of the program would look like this:
+
+ `e1-trace-record -o /tmp/my_recording.e1cap -m -r`
+
+There are some additional low-level tuning parameters (`-n` and `-p`), but you should not need those
+under normal operation.
+
+==== e1cap file format
+
+The recording file format consists of *chunks* of data. Each chunk contains a number of E1 frames in one
+direction of the line.
+
+The chunk header is prefixed with a 32bit magic value 0xE115600D, followed by two 64bit values as timestamp
+(seconds and microseconds), followed by a 16bit length value and an 8 bit USB endpoint number. The USB
+endpoint number signifies the direction; it can be either 0x81 or 0x82.
+
+.Definition of chunk header
+----
+struct e1_chunk_hdr {
+ uint32_t magic;
+ struct {
+ uint64_t sec;
+ uint64_t usec;
+ } time;
+ int16_t len;
+ uint8_t ep;
+} __attribute__((packed));
+----
+
+After the chunk header is a concatenation of multiple E1 frames, each 32bytes long (one byte for each timeslot
+in the frame).
+
+
+=== `osmo-e1d`
+
+`osmo-e1d` was originally implemented as a host software stack for the
+icE1usb E1 USB interface, which is _terminating_ an E1 link and allows
+receive and transmit use by external software.
+
+More recently, `osmo-e1d` and the e1-tracer firmware have been made
+compatible. This means that `osmo-e1d` can now be used by applications
+to get raw trace data from individual E1 timeslots in real-time using
+the same API/interface that was originally designed for icE1usb.
+
+The e1-tracer appears to `osmo-e1d` as one _interface_ which two
+_lines_. Each _line_ represents one direction of the E1
+traffic.
+
+In theory, `osmo-e1d` should work on any operating system with libusb
+support for isochronous transfers. However, official support is limited
+to GNU/Linux at this point.
+
+More information about `osmo-e1d` can be found at its homepage
+https://osmocom.org/projects/osmo-e1d/wiki
+
+==== Example osmo-e1d configuration / start-up
+
+.Sample config file (pass as `-c /path/to/my/osmo-e1d.cfg` when starting osmo-e1d)
+----
+log stderr
+ logging filter all 1
+ logging color 1
+ logging print category-hex 0
+ logging print category 1
+ logging print level 1
+ logging timestamp 0
+ logging print file 1 last
+ logging level e1d info
+ logging level linp info
+e1d
+----
+
+.Sample output of osmo-e1d starting with above config file and one e1-tracer attached to USB
+----
+DLGLOBAL NOTICE Available via telnet 127.0.0.1 4269 (telnet_interface.c:100)
+DE1D NOTICE No configuration for e1-tracer serial 'dc696c80532f7d34' found, auto-generating it (usb.c:868)
+DE1D NOTICE (I0) Created (intf_line.c:184)
+DE1D NOTICE (I0:L0) Created (intf_line.c:285)
+DE1D NOTICE (I0:L0) Activated (intf_line.c:319)
+DE1D NOTICE (I0:L1) Created (intf_line.c:285)
+DE1D NOTICE (I0:L1) Activated (intf_line.c:319)
+----
+
+This means that a single e1-tracer device was found, and that it has been designated *interface 0* with *line 0* and *line 1* within that interface.
+
+You can introspect the `osmo-e1d` state using its VTY interface:
+
+.Example VTY output when telnet-ing into the osmo-e1d VTY port 4269
+----
+$ telnet localhost 4269
+Trying 127.0.0.1...
+Connected to localhost.
+Escape character is '^]'.
+Welcome to the osmo-e1d VTY interface
+
+(C) 2019-2022 by Sylvain Munaut, Harald Welte and contributors
+osmo-e1d> show line <1>
+Interface #0 (dc696c80532f7d34), Line #0, Mode CHANNELIZED:
+ TS00: Mode off, FD -1, Peer PID -1
+ TS01: Mode off, FD -1, Peer PID -1
+ TS02: Mode off, FD -1, Peer PID -1
+ TS03: Mode off, FD -1, Peer PID -1
+ TS04: Mode off, FD -1, Peer PID -1
+ TS05: Mode off, FD -1, Peer PID -1
+ TS06: Mode off, FD -1, Peer PID -1
+ TS07: Mode off, FD -1, Peer PID -1
+ TS08: Mode off, FD -1, Peer PID -1
+ TS09: Mode off, FD -1, Peer PID -1
+ TS10: Mode off, FD -1, Peer PID -1
+ TS11: Mode off, FD -1, Peer PID -1
+ TS12: Mode off, FD -1, Peer PID -1
+ TS13: Mode off, FD -1, Peer PID -1
+ TS14: Mode off, FD -1, Peer PID -1
+ TS15: Mode off, FD -1, Peer PID -1
+ TS16: Mode off, FD -1, Peer PID -1
+ TS17: Mode off, FD -1, Peer PID -1
+ TS18: Mode off, FD -1, Peer PID -1
+ TS19: Mode off, FD -1, Peer PID -1
+ TS20: Mode off, FD -1, Peer PID -1
+ TS21: Mode off, FD -1, Peer PID -1
+ TS22: Mode off, FD -1, Peer PID -1
+ TS23: Mode off, FD -1, Peer PID -1
+ TS24: Mode off, FD -1, Peer PID -1
+ TS25: Mode off, FD -1, Peer PID -1
+ TS26: Mode off, FD -1, Peer PID -1
+ TS27: Mode off, FD -1, Peer PID -1
+ TS28: Mode off, FD -1, Peer PID -1
+ TS29: Mode off, FD -1, Peer PID -1
+ TS30: Mode off, FD -1, Peer PID -1
+ TS31: Mode off, FD -1, Peer PID -1
+ Counters for each line in e1d:
+ Rx Signal Lost: 0 (0/s 0/m 0/h 0/d)
+ Rx Alignment Lost: 0 (0/s 0/m 0/h 0/d)
+ E1 Rx CRC Errors: 0 (0/s 0/m 0/h 0/d)
+ E1 Rx Overflow: 0 (0/s 0/m 0/h 0/d)
+ E1 Tx Underflow: 0 (0/s 0/m 0/h 0/d)
+ Rx Frames Reporting Remote CRC Error: 0 (0/s 0/m 0/h 0/d)
+ Rx Frames Reporting Remote Alarm: 0 (0/s 0/m 0/h 0/d)
+ E1 Tx Frames multiplexed: 0 (0/s 0/m 0/h 0/d)
+ E1 Rx Frames demultiplexed: 143680 (8000/s 142560/m 0/h 0/d)
+Interface #0 (dc696c80532f7d34), Line #1, Mode CHANNELIZED:
+ TS00: Mode off, FD -1, Peer PID -1
+ TS01: Mode off, FD -1, Peer PID -1
+ TS02: Mode off, FD -1, Peer PID -1
+ TS03: Mode off, FD -1, Peer PID -1
+ TS04: Mode off, FD -1, Peer PID -1
+ TS05: Mode off, FD -1, Peer PID -1
+ TS06: Mode off, FD -1, Peer PID -1
+ TS07: Mode off, FD -1, Peer PID -1
+ TS08: Mode off, FD -1, Peer PID -1
+ TS09: Mode off, FD -1, Peer PID -1
+ TS10: Mode off, FD -1, Peer PID -1
+ TS11: Mode off, FD -1, Peer PID -1
+ TS12: Mode off, FD -1, Peer PID -1
+ TS13: Mode off, FD -1, Peer PID -1
+ TS14: Mode off, FD -1, Peer PID -1
+ TS15: Mode off, FD -1, Peer PID -1
+ TS16: Mode off, FD -1, Peer PID -1
+ TS17: Mode off, FD -1, Peer PID -1
+ TS18: Mode off, FD -1, Peer PID -1
+ TS19: Mode off, FD -1, Peer PID -1
+ TS20: Mode off, FD -1, Peer PID -1
+ TS21: Mode off, FD -1, Peer PID -1
+ TS22: Mode off, FD -1, Peer PID -1
+ TS23: Mode off, FD -1, Peer PID -1
+ TS24: Mode off, FD -1, Peer PID -1
+ TS25: Mode off, FD -1, Peer PID -1
+ TS26: Mode off, FD -1, Peer PID -1
+ TS27: Mode off, FD -1, Peer PID -1
+ TS28: Mode off, FD -1, Peer PID -1
+ TS29: Mode off, FD -1, Peer PID -1
+ TS30: Mode off, FD -1, Peer PID -1
+ TS31: Mode off, FD -1, Peer PID -1
+ Counters for each line in e1d:
+ Rx Signal Lost: 0 (0/s 0/m 0/h 0/d)
+ Rx Alignment Lost: 0 (0/s 0/m 0/h 0/d)
+ E1 Rx CRC Errors: 0 (0/s 0/m 0/h 0/d)
+ E1 Rx Overflow: 0 (0/s 0/m 0/h 0/d)
+ E1 Tx Underflow: 0 (0/s 0/m 0/h 0/d)
+ Rx Frames Reporting Remote CRC Error: 0 (0/s 0/m 0/h 0/d)
+ Rx Frames Reporting Remote Alarm: 0 (0/s 0/m 0/h 0/d)
+ E1 Tx Frames multiplexed: 0 (0/s 0/m 0/h 0/d)
+ E1 Rx Frames demultiplexed: 143648 (8000/s 142560/m 0/h 0/d)
+----
+<1> typing `show line` will produce the below output, indicating that all timeslots are currently _off_ and 8000 E1 frames per second are received from both lines (i.e. directions)
+
+Other applications on the system can not connect to `osmo-e1d` and open individual timeslots either in _RAW_ or in _HDLC-FCS_ mode.
+
+An example program is included, it is called `osmo-e1d-pipe`. Using this program, you can get a raw output of an individual timeslot.
+
+.Command line reference of `osmo-e1d-pipe` utility
+----
+$ ./osmo-e1d-pipe --help
+ -h --help This help message
+ -p --path PATH Path of the osmo-e1d control socket
+ -i --interface <0-255> E1 Interface Number
+ -l --line <0-255> E1 Line Number
+ -t --timeslot <0-31> E1 Timeslot Number
+ -m --mode (RAW|HDLC-FCS) E1 Timeslot Mode
+ -f --force Force open of the timeslot (may disconnect other client)
+ -r --read FILE Read from FILE instead of STDIN
+----
+
+.Sample output of one direction of a raw B-channel
+----
+$./osmo-e1d-pipe -i 0 -l 0 -t 3 -m RAW -r /dev/zero | hexdump -v
+0000000 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000010 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000020 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000030 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000040 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000050 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000060 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000070 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000080 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+0000090 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+00000a0 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5 d5d5
+...
+----
+
+.Sample output of one direction of a HDLC-FCS D-channel
+----
+$ ./osmo-e1d-pipe -i 0 -l 1 -t 16 -m hdlc-fcs -r /dev/zero | hexdump -v
+0000000 0102 027f 7f01 0102 027f 7f01 0102 027f
+0000010 7f01 0102 027f 7f01 0102 027f 7f01 0102
+0000020 027f 7f01 0102 027f 7f01 0102 027f 7f01
+0000030 0102 027f 7f01 0102 027f 7f01 0102 027f
+0000040 7f01 0102 027f 7f01 0102 027f 7f01 0102
+----
+
+
+
+=== Other / 3rd party software
+
+you can interface 3rd party applications with osmo-e1d in the following
+mutually exclusive ways:
+
+* by adding support for `osmo-e1d`, e.g. via `libosmo-e1d` to the
+ respective application. This way your application can receive traffic
+ one a per-timeslot basis.
+* by directly implementing the USB protocol exposed by e1-tracer in your
+ software. This is definitely more effort, as you have to parse the
+ entire E1 frames, implement software HDLC decoders, etc. - all of
+ which are already present in `osmo-e1d`
+* by post-processing the raw disk recordings generated by the
+ `e1-trace-recorder` program.
+
+Should you require any related development/porting services, please do
+not hesitate to reach out to sysmocom.
diff --git a/doc/manuals/e1-tracer-usermanual-docinfo.xml b/doc/manuals/e1-tracer-usermanual-docinfo.xml
new file mode 100644
index 0000000..04cccc7
--- /dev/null
+++ b/doc/manuals/e1-tracer-usermanual-docinfo.xml
@@ -0,0 +1,46 @@
+<revhistory>
+ <revision>
+ <revnumber>1</revnumber>
+ <date>October 31, 2022</date>
+ <authorinitials>HW</authorinitials>
+ <revremark>
+ Initial user manual version
+ </revremark>
+ </revision>
+</revhistory>
+
+<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>2020-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 no Invariant Sections, 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>
+ <para>
+ The Asciidoc source code of this manual can be found at
+ <ulink url="http://git.osmocom.org/osmo-gsm-manuals/">
+ http://git.osmocom.org/osmo-gsm-manuals/
+ </ulink>
+ </para>
+</legalnotice>
diff --git a/doc/manuals/e1-tracer-usermanual.adoc b/doc/manuals/e1-tracer-usermanual.adoc
new file mode 100644
index 0000000..4cea7c1
--- /dev/null
+++ b/doc/manuals/e1-tracer-usermanual.adoc
@@ -0,0 +1,17 @@
+:gfdl-enabled:
+
+e1-tracer User Manual
+===================
+Harald Welte <hwelte@sysmocom.de>
+
+include::./common/chapters/preface.adoc[]
+
+include::./chapters/e1-tracer/hardware.adoc[]
+
+include::./chapters/e1-tracer/gateware.adoc[]
+
+include::./chapters/e1-tracer/firmware.adoc[]
+
+include::./chapters/e1-tracer/host-software.adoc[]
+
+include::./common/chapters/gfdl.adoc[]
diff --git a/doc/manuals/images/e1-tracer-plate.png b/doc/manuals/images/e1-tracer-plate.png
new file mode 100644
index 0000000..dc604d7
--- /dev/null
+++ b/doc/manuals/images/e1-tracer-plate.png
Binary files differ
diff --git a/doc/manuals/images/e1_tracer-bgt-front.jpg b/doc/manuals/images/e1_tracer-bgt-front.jpg
new file mode 100644
index 0000000..d1e5179
--- /dev/null
+++ b/doc/manuals/images/e1_tracer-bgt-front.jpg
Binary files differ
diff --git a/doc/manuals/images/e1_tracer-koh1.jpg b/doc/manuals/images/e1_tracer-koh1.jpg
new file mode 100644
index 0000000..fe880e8
--- /dev/null
+++ b/doc/manuals/images/e1_tracer-koh1.jpg
Binary files differ
