From 9df9995d2f7dc74246d97994635bc839507ba56f Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Mon, 17 Jan 2022 17:16:09 +0100 Subject: [PATCH] icE1usb: update manual to reflect firmware 0.2 (GPS-DO, 2 ports) Change-Id: I9dac5b9479af37270dc13e334a278f91f260c7ce --- doc/manuals/chapters/firmware.adoc | 67 ++++++++++++++++++++++ doc/manuals/chapters/hardware.adoc | 4 +- doc/manuals/chapters/host-software.adoc | 19 ++++-- doc/manuals/icE1usb-usermanual-docinfo.xml | 10 +++- 4 files changed, 93 insertions(+), 7 deletions(-) diff --git a/doc/manuals/chapters/firmware.adoc b/doc/manuals/chapters/firmware.adoc index 12c5710..1b440bd 100644 --- a/doc/manuals/chapters/firmware.adoc +++ b/doc/manuals/chapters/firmware.adoc @@ -145,3 +145,70 @@ information to the user. === Use of the Multi-Color RGB LED FIXME: describe how it is used. + + +=== Firmware <-> USB Host Interface + +The icE1usb firmware provides a USB 1.1 full-speed (FS) device with + +* one configuration +* 5 interfaces +** E1 port 0 +** E1 port 1 +** CDC-ACM (control + data) +** DFU (device firmware upgrade) + +The interfaces have self-explanatory string descriptors like + +---- + iInterface 6 E1 port 0 + iInterface 8 E1 port 1 + iInterface 9 GPS (CDC control) + iInterface 10 GPS (CDC data) + iInterface 11 DFU runtime +---- + +==== E1 ports + +There are two physical E1 ports in the icE1usb. Each is exposed via its own USB _interface_. + +Each port (USB _interface_) contains two _altsettings_: + +* one altsetting with no data endpoints (E1 disabled, this is the default) +* one altsetting with isochronous IN/OUT endpoints (E1 enabled) + +In order to activate one E1 port, the driver must perform a USB standard +request to activate the _enabled_ altsetting. + +NOTE:: Please note that on many XHCI host controllers there seem to be +implementation flaws in the XHCI host controller firmware preventing the +activation of both icE1usb ports simultaneously. The XHCI controller +firmware erroneously claims that there is insufficient bus bandwidth. +However, the same icE1usb hardware/firmware works perfectly fine with +OHCI, UHCI and EHCI host controllers. + +As most modern [PC] hardware has XHCI host controllers, you need to +choose your hardware carefully if concurrent operation of both icE1usb +ports is required in your application. + +==== CDC-ACM with GPS NMEA + +There's a CDC-ACM (virtual com port) interface available in the icE1usb. +This will be supported by the standard `cdc_acm` driver of your +operating system, and will expose a `/dev/ttyACMx` device on Linux. + +The port provides read-only access to the GPS receiver on-board the +icE1usb. You can use this to + +* determine the GPS fix (and hence 1PPS frequency reference) + availability +* obtain the GPS position of the device + +NOTE:: Write access to the GPS receiver is not permitted as the icE1usb +firmware needs to control the GPS receiver for frequency reference +purposes. + +==== DFU (Device Firmware Upgrade) + +There's a DFU interface available in order to update the icE1usb +gateware and firmware. For more information, see [[firmware]] above. diff --git a/doc/manuals/chapters/hardware.adoc b/doc/manuals/chapters/hardware.adoc index 4b2f694..8055e64 100644 --- a/doc/manuals/chapters/hardware.adoc +++ b/doc/manuals/chapters/hardware.adoc @@ -7,8 +7,8 @@ enclosure). It's main building blocks are: * an iCE40 FPGA -* Two E1 line interface (transformers, biasing networks and ESD protection) footnote:[Only one E1 line supported by firmware so far] -* a GPS receiver module with 1PPS output to the FPGA footnote:[GPS-DO supported by firmware yet] +* Two E1 line interface (transformers, biasing networks and ESD protection) footnote:[Second interface requires firmware >= 0.2 and OHCI/OHCI/EHCI host controller] +* a GPS receiver module with 1PPS output to the FPGA footnote:[Requires firmware >= 0.2] === Schematics diff --git a/doc/manuals/chapters/host-software.adoc b/doc/manuals/chapters/host-software.adoc index 356c897..4c8578e 100644 --- a/doc/manuals/chapters/host-software.adoc +++ b/doc/manuals/chapters/host-software.adoc @@ -3,13 +3,19 @@ Host Software is software running on the USB host computer to which the icE1usb is attached. -At the time of this writing, the only software implementing icE1usb -support is `osmo-e1d`. +At the time of this writing, there are two options for icE1usb driver interfaces: +`osmo-e1d` and `DAHDI`. === `osmo-e1d` -`osmo-e1d` utilizes `libusb` to talk to the icE1usb hardware and offers -a unix domain socket based interface to application software. +`osmo-e1d` is a pure user-space driver, not requiring any specific Linux kernel, +kernel patches or out-of-tree kernel modules. It utilizes `libusb` to +talk to the icE1usb hardware and offers a unix domain socket based +interface to application software. + +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. Software such as `osmo-bsc` and `osmo-mgw` can interface `osmo-e1d` via the `libosmo-abis` support for `osmo-e1d`. @@ -23,6 +29,11 @@ DAHDI (Digium Asterisk Hardware Driver Interface) is an extremely popular driver for a variety of POTS/PSTN and also TDM interface boards by originally Zaptel, later Digium and now most recently Sangoma. +DAHDI is available only for Linux, and is provided as source code for a +set of out-of-tree kernel modules. You must compile those modules for +each specific Linux kernel version you are using. Keep this in mind +when performing kernel upgrades and the like. + DAHDI is supported by a wide range of open source PBX / softswitch software, including Asterisk, FreeSWITCH and yate. diff --git a/doc/manuals/icE1usb-usermanual-docinfo.xml b/doc/manuals/icE1usb-usermanual-docinfo.xml index 1c7e7fd..246e014 100644 --- a/doc/manuals/icE1usb-usermanual-docinfo.xml +++ b/doc/manuals/icE1usb-usermanual-docinfo.xml @@ -1,4 +1,12 @@ + + 2 + January 17, 2022 + HW + + Update documentation to firmware 0.2 (GPS-DO, second E1 port) + + 1 December 13, 2020 @@ -24,7 +32,7 @@ - 2020 + 2020-2022 sysmocom - s.f.m.c. GmbH