doc/e1-tracer: Add an initial e1-tracer user manual

Change-Id: I9413195d69325ba74b3993e6ec7a1fc7628b5dd1
This commit is contained in:
Harald Welte 2022-11-01 09:32:22 +01:00
parent 6fc0ad3c7e
commit 1d12caa521
10 changed files with 694 additions and 1 deletions

View File

@ -2,8 +2,9 @@ OSMO_GSM_MANUALS_DIR:=$(shell ./osmo-gsm-manuals-dir.sh)
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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1021 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.0 MiB