icE1usb: update manual to reflect firmware 0.2 (GPS-DO, 2 ports)
Change-Id: I9dac5b9479af37270dc13e334a278f91f260c7ce
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 @@
=== 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 @@
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 @@
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,5 +1,13 @@
<revhistory>
<revision>
+ <revnumber>2</revnumber>
+ <date>January 17, 2022</date>
+ <authorinitials>HW</authorinitials>
+ <revremark>
+ Update documentation to firmware 0.2 (GPS-DO, second E1 port)
+ </revremark>
+ </revision>
+ <revision>
<revnumber>1</revnumber>
<date>December 13, 2020</date>
<authorinitials>HW</authorinitials>
@@ -24,7 +32,7 @@
</authorgroup>
<copyright>
- <year>2020</year>
+ <year>2020-2022</year>
<holder>sysmocom - s.f.m.c. GmbH</holder>
</copyright>