laforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-e1-hardware/+/26926 )

Change subject: icE1usb: update manual to reflect firmware 0.2 (GPS-DO, 2 ports) ......................................................................

icE1usb: update manual to reflect firmware 0.2 (GPS-DO, 2 ports)

Change-Id: I9dac5b9479af37270dc13e334a278f91f260c7ce --- M doc/manuals/chapters/firmware.adoc M doc/manuals/chapters/hardware.adoc M doc/manuals/chapters/host-software.adoc M doc/manuals/icE1usb-usermanual-docinfo.xml 4 files changed, 93 insertions(+), 7 deletions(-)

Approvals: Jenkins Builder: Verified tnt: Looks good to me, but someone else must approve laforge: Looks good to me, approved

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>