First version of icE1usb user manual
Change-Id: Ia04890cf3b321f8cb01e3c513a730031e76376b9
diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile
new file mode 100644
index 0000000..1bd4b6e
--- /dev/null
+++ b/doc/manuals/Makefile
@@ -0,0 +1,9 @@
+OSMO_GSM_MANUALS_DIR:=$(shell pkg-config osmo-gsm-manuals --variable=osmogsmmanualsdir)
+
+sdcdir = .
+
+ASCIIDOC = icE1usb-usermanual.adoc
+include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+icE1usb-usermanual.pdf: chapters/*.adoc
+
+include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
diff --git a/doc/manuals/chapters/firmware.adoc b/doc/manuals/chapters/firmware.adoc
new file mode 100644
index 0000000..d0542bd
--- /dev/null
+++ b/doc/manuals/chapters/firmware.adoc
@@ -0,0 +1,137 @@
+[[firmware]]
+== icE1usb Firmware
+
+The icE1usb _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)
+
+icE1usb 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 icE1usb 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`
+
+1. 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 icE1usb boot loader enumerates as VID:PID `1d50:6145`, while the
+normal application firmware enumerates as `1d50:6144`,
+
+You can for example use `lsusb` to check the VID:PID:
+
+----
+$ lsusb -d 1d50:
+Bus 001 Device 042: ID 1d50:6145<1> OpenMoko, Inc. icE1usb
+$ sudo dfu-util -d 1d50:6145 -e <2>
+...
+$ lsusb -d 1d50:
+Bus 001 Device 043: ID 1d50:6144<3> OpenMoko, Inc. icE1usb (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 currently be found at the personal developer
+directory of tnt at https://people.osmocom.org/tnt/e1/
+
+A more official download location will be provided shortly.
+
+==== Upgrading the FPGA gateware
+
+Gateware files are called `icE1usb-*.bin`.
+
+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:6144 -a 0 -D icE1usb-202010-bd3999e96.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 `fw_app*.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:6144 -a 1 -D fw_app-202011-4d9a04e2.bin -R` to perform the upgrade.
+
+.Typical output during upgrade of the firmware
+----
+$ sudo dfu-util -d 1d50:6144 -a 1 -D ./fw_app.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:6144
+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:6145 OpenMoko, Inc. icE1usb
+----
+
+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:6145] ver=0003, devnum=44, cfg=1, intf=1, path="1-2", alt=0, name="DFU runtime", serial="dc697407e7881531"
+----
+
+
+=== Use of the E1 Interface LEDs
+
+Each E1 interface has two LEDs integrated into the RJ45 connector.
+
+FIXME: describe how they are used.
+
+=== Use of the Multi-Color RGB LED
+
+FIXME: describe how it is used.
diff --git a/doc/manuals/chapters/gateware.adoc b/doc/manuals/chapters/gateware.adoc
new file mode 100644
index 0000000..03487e1
--- /dev/null
+++ b/doc/manuals/chapters/gateware.adoc
@@ -0,0 +1,13 @@
+[[gateware]]
+== icE1usb Gateware
+
+The icE1usb _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.
+
+As an OSHW project, all of it is available in source code format
+at https://git.osmocom.org/osmo-e1-hardware/tree/gateware/icE1usb
+
+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/hardware.adoc b/doc/manuals/chapters/hardware.adoc
new file mode 100644
index 0000000..4b2f694
--- /dev/null
+++ b/doc/manuals/chapters/hardware.adoc
@@ -0,0 +1,119 @@
+[[hardware]]
+== icE1usb Hardware
+
+The icE1usb Hardware consists of a single circuit board (in an optional
+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]
+
+=== Schematics
+
+As icE1usb is an OSHW (Open Source Hardware) project, the full schematics
+and design files are publicly available.
+
+The design files in KiCAD formwa are available at https://git.osmocom.org/osmo-e1-hardware/tree/hardware/icE1usb
+
+PDF rendered schematics are available at https://git.osmocom.org/osmo-e1-hardware/plain/hardware/icE1usb/r1.0/icE1usb.pdf
+
+=== Connectors
+
+==== X5A and X5B: E1 Interface Connectors
+
+On one side of the PCB there are two RJ45 connectors next to each other.
+
+Those are the two E1 line interfaces. The interfaces are of symmetric
+120 Ohms type.
+
+Assuming the board is oriented with the tab of the RJ45 connectors facing
+up:
+
+* Interface 0 is on the right side
+* Interface 1 is on the left side (next to the button)
+
+The pin-out of the connectors can be swapped between TE and NT mode using
+the J4 and J5 jumper blocks on the circuit board.
+
+A GSM BTS typically implements TE pin-out, while the icE1usb should then
+use NT mode pin-out if no cross-over cable is used.
+
+.Pin-out of RJ45 E1 connectors
+[options="header"]
+|===
+| Pin | Function (TE) | Function (NT Mode)
+| 1 | Rx | Tx
+| 2 | Rx | Tx
+| 3 | not used | not used
+| 4 | Tx | Rx
+| 5 | Tx | Rx
+| 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!
+
+==== X4: USB Connector
+
+The USB connector is a USB Type C connector. However, it only carries
+USB 1.1 full-speed signals. 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 icE1usb)
+* Ring: Rx input of PC (Tx output of icE1usb)
+* Shield: GND
+
+A compatible cable can be sourced from the sysmocom web-shop at
+http://shop.sysmocom.de/.
+
+==== X1: GPS Antenna Connector
+
+The GPS antenna connector is a female SMA connector.
+
+You can connect most standard active GPS antennas with built-in LNA.
+
+icE1us provide phantom voltage.
+
+The use of a GPS antenna is only required when you need a high precision
+clock reference for the 2.048 MHz E1 bit clock, e.g. to provide a clock
+reference to a cellular base station on the A-bis interface.
+
+==== X3: GPIO / Extension Connector
+
+This is a RJ45 connector adjacent to the USB connector.
+
+It is currently unused and reserved for future use.
+
+
+[[hw-pushbutton]]
+=== Pushbutton
+
+This is a push-button next to the _E1 interface '1'_. 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 can be used to force booting into the DFU loader in order to
+recover from a broken firmware installation.
+
+
+=== Multi-Color LED
+
+Above the USB-C connector, there is a multi-color RGB LED.
+
+This LED is used by the firmware to indicate a variety of status
+information. Pleas see the firmware documentation in <<firmware>>.
diff --git a/doc/manuals/chapters/host-software.adoc b/doc/manuals/chapters/host-software.adoc
new file mode 100644
index 0000000..8af1018
--- /dev/null
+++ b/doc/manuals/chapters/host-software.adoc
@@ -0,0 +1,34 @@
+== Host Software
+
+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`.
+
+=== `osmo-e1d`
+
+`osmo-e1d` utilizes `libusb` to talk to the icE1usb hardware and offers
+a unix domain socket based interface to application software.
+
+Software such as `osmo-bsc` and `osmo-mgw` can interface `osmo-e1d` via
+the `libosmo-abis` support for `osmo-e1d`.
+
+More information about `osmo-e1d` can be found at its homepage
+https://osmocom.org/projects/osmo-e1d/wiki
+
+=== Other software
+
+you can interface 3rd party applications with osmo-e1d in the following
+ways:
+
+* by adding support for `osmo-e1d`, e.g. via `libosmo-e1d` to the
+ respective appliation
+* by implementing a device driver for whatever hardware interface (e.g.
+ for DAHDI) supported by your software
+* by directly implementing the USB interface exposed by icE1usb in your
+ software
+
+Should you require any related development/porting services, please do
+not hesitate to reach out to sysmocom.
+
diff --git a/doc/manuals/icE1usb-usermanual.adoc b/doc/manuals/icE1usb-usermanual.adoc
new file mode 100644
index 0000000..5cfeef6
--- /dev/null
+++ b/doc/manuals/icE1usb-usermanual.adoc
@@ -0,0 +1,17 @@
+:gfdl-enabled:
+
+icE1usb User Manual
+===================
+Harald Welte <hwelte@sysmocom.de>
+
+include::./common/chapters/preface.adoc[]
+
+include::./chapters/hardware.adoc[]
+
+include::./chapters/gateware.adoc[]
+
+include::./chapters/firmware.adoc[]
+
+include::./chapters/host-software.adoc[]
+
+include::./common/chapters/gfdl.adoc[]