Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 1 | [[firmware]] |
| 2 | == icE1usb Firmware |
| 3 | |
| 4 | The icE1usb _firmware_ is a small amount of bare-iron software running |
| 5 | on the picoRISCV soft-core of the _gateware_. |
| 6 | |
| 7 | It mainly consists of drivers for the no2e1 E1 Framer IP core and the |
| 8 | no2usb USB Device IP core which are part of the gateware described in |
| 9 | <<gateware>>. |
| 10 | |
| 11 | === Firmware Upgrade (DFU) |
| 12 | |
| 13 | icE1usb contains support for the USB DFU (Device Firmware Upgrade) |
| 14 | standard. |
| 15 | |
| 16 | As such, you can use any USB DFU compliant utility to upgrade the |
| 17 | firmware of the icE1usb device. |
| 18 | |
| 19 | DFU mode can be entered in two ways: |
| 20 | |
| 21 | 1. by performing a DFU detach from the normal application firmware |
| 22 | (obviously that requires a [still] working firmware present on the |
| 23 | device). To do so, please use `dfu-util -e` |
| 24 | |
Harald Welte | 90c842f | 2022-11-01 09:32:37 +0100 | [diff] [blame] | 25 | 2. by pushing the push-button (see <<hw-pushbutton>>) during power-up. |
Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 26 | Simply disconnect the USB cable, then push that button and keep it |
| 27 | pushed while re-attaching the USB cable. |
| 28 | |
Harald Welte | 6101b1b | 2021-03-30 15:22:24 +0200 | [diff] [blame] | 29 | The icE1usb boot loader enumerates as VID:PID `1d50:6144`, while the |
| 30 | normal application firmware enumerates as `1d50:6145`, |
Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 31 | |
| 32 | You can for example use `lsusb` to check the VID:PID: |
| 33 | |
| 34 | ---- |
| 35 | $ lsusb -d 1d50: |
| 36 | Bus 001 Device 042: ID 1d50:6145<1> OpenMoko, Inc. icE1usb |
| 37 | $ sudo dfu-util -d 1d50:6145 -e <2> |
| 38 | ... |
| 39 | $ lsusb -d 1d50: |
| 40 | Bus 001 Device 043: ID 1d50:6144<3> OpenMoko, Inc. icE1usb (DFU) |
| 41 | ---- |
| 42 | <1> initially the device is in normal runtime mode |
| 43 | <2> we use `dfu-util -e` to switch to DFU mode |
| 44 | <3> we can see, the device is now in DFU mode |
| 45 | |
| 46 | ==== Obtaining firmware upgrades |
| 47 | |
Harald Welte | 6c8858b | 2021-03-30 15:27:47 +0200 | [diff] [blame] | 48 | The latest firmware can be found at |
| 49 | https://ftp.osmocom.org/binaries/icE1usb/firmware/latest/ |
Harald Welte | 7d72b86 | 2022-11-01 09:33:15 +0100 | [diff] [blame] | 50 | a backlog of earlier builds can be found at |
| 51 | https://ftp.osmocom.org/binaries/icE1usb/firmware/all/ |
Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 52 | |
Harald Welte | 6c8858b | 2021-03-30 15:27:47 +0200 | [diff] [blame] | 53 | The latest gateware can currently only be found at the personal developer |
Harald Welte | ce1262f | 2022-02-23 21:26:32 +0100 | [diff] [blame] | 54 | directory of tnt at https://people.osmocom.org/tnt/ice1usb/icE1usb-202010-bd399e96.bin |
Harald Welte | 6c8858b | 2021-03-30 15:27:47 +0200 | [diff] [blame] | 55 | A more official download location for the gateware will be provided shortly. |
Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 56 | |
| 57 | ==== Upgrading the FPGA gateware |
| 58 | |
Harald Welte | 0b7f834 | 2021-03-30 15:27:59 +0200 | [diff] [blame] | 59 | Gateware files are called `icE1usb-*.bin`. (without 'fw' in the name) |
Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 60 | |
| 61 | The gateware can be upgraded by accessing the DFU _altsetting 0_ using `dfu-util` *`-a 0`* |
| 62 | |
| 63 | Assuming you already are in DFU mode, you would typically use a command |
| 64 | like `dfu-util -d 1d50:6144 -a 0 -D icE1usb-202010-bd3999e96.bin -R` to perform the upgrade. |
| 65 | |
| 66 | NOTE: The `-R` will switch the device back to runtime mode after the |
| 67 | upgrade. If you want to upgrade the firmware in the same session, skip |
| 68 | the `-R` in the above command. |
| 69 | |
| 70 | ==== Upgrading the picoRISCV firmware |
| 71 | |
Harald Welte | 0b7f834 | 2021-03-30 15:27:59 +0200 | [diff] [blame] | 72 | Firmware files are called `icE1usb-fw*.bin`. |
Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 73 | |
| 74 | The firmware can be upgraded by accessing the DFU _altsetting 1_ using `dfu-util` *`-a 1`* |
| 75 | |
| 76 | Assuming you already are in DFU mode, you would typically use a command |
| 77 | like `dfu-util -d 1d50:6144 -a 1 -D fw_app-202011-4d9a04e2.bin -R` to perform the upgrade. |
| 78 | |
| 79 | .Typical output during upgrade of the firmware |
| 80 | ---- |
| 81 | $ sudo dfu-util -d 1d50:6144 -a 1 -D ./fw_app.bin -R |
| 82 | dfu-util 0.9 |
| 83 | |
| 84 | Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. |
| 85 | Copyright 2010-2016 Tormod Volden and Stefan Schmidt |
| 86 | This program is Free Software and has ABSOLUTELY NO WARRANTY |
| 87 | Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ |
| 88 | |
| 89 | dfu-util: Invalid DFU suffix signature |
| 90 | dfu-util: A valid DFU suffix will be required in a future dfu-util release!!! |
| 91 | Opening DFU capable USB device... |
| 92 | ID 1d50:6144 |
| 93 | Run-time device DFU version 0101 |
| 94 | Claiming USB DFU Interface... |
| 95 | Setting Alternate Setting #1 ... |
| 96 | Determining device status: state = dfuIDLE, status = 0 |
| 97 | dfuIDLE, continuing |
| 98 | DFU mode device DFU version 0101 |
| 99 | Device returned transfer size 4096 |
| 100 | Copying data from PC to DFU device |
| 101 | Download [=========================] 100% 11256 bytes |
| 102 | Download done. |
| 103 | state(2) = dfuIDLE, status(0) = No error condition is present |
| 104 | Done! |
| 105 | Resetting USB to switch back to runtime mode |
| 106 | ---- |
| 107 | |
| 108 | As the `-R` option was used, the device will reset and re-enumerate in |
| 109 | the newly programmed firmware. |
| 110 | |
| 111 | You can verify this as follows: |
| 112 | |
| 113 | ---- |
| 114 | $ lsusb -d 1d50: |
| 115 | Bus 001 Device 042: ID 1d50:6145 OpenMoko, Inc. icE1usb |
| 116 | ---- |
| 117 | |
| 118 | or alternatively: |
| 119 | |
| 120 | ---- |
| 121 | $ dfu-util -l -d 1d50: |
| 122 | dfu-util 0.9 |
| 123 | |
| 124 | Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. |
| 125 | Copyright 2010-2016 Tormod Volden and Stefan Schmidt |
| 126 | This program is Free Software and has ABSOLUTELY NO WARRANTY |
| 127 | Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ |
| 128 | |
| 129 | Found Runtime: [1d50:6145] ver=0003, devnum=44, cfg=1, intf=1, path="1-2", alt=0, name="DFU runtime", serial="dc697407e7881531" |
| 130 | ---- |
| 131 | |
| 132 | |
| 133 | === Use of the E1 Interface LEDs |
| 134 | |
Harald Welte | 5276567 | 2020-12-15 18:35:42 +0100 | [diff] [blame] | 135 | Each E1 interface has two LEDs integrated into the RJ45 connector. They |
| 136 | are (starting to get) used by the firmware to indicate status |
| 137 | information to the user. |
Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 138 | |
Harald Welte | 5276567 | 2020-12-15 18:35:42 +0100 | [diff] [blame] | 139 | [options="header"] |
| 140 | |=== |
| 141 | |Color | Pattern | Meaning |
| 142 | |Green | Blinking (slow) | E1 Receiver attempting to align |
| 143 | |Green | On | E1 Receiver fully aligned |
| 144 | |=== |
| 145 | |
Harald Welte | d645d44 | 2020-12-14 19:20:38 +0100 | [diff] [blame] | 146 | |
| 147 | === Use of the Multi-Color RGB LED |
| 148 | |
| 149 | FIXME: describe how it is used. |
Harald Welte | 9df9995 | 2022-01-17 17:16:09 +0100 | [diff] [blame] | 150 | |
| 151 | |
| 152 | === Firmware <-> USB Host Interface |
| 153 | |
| 154 | The icE1usb firmware provides a USB 1.1 full-speed (FS) device with |
| 155 | |
| 156 | * one configuration |
| 157 | * 5 interfaces |
| 158 | ** E1 port 0 |
| 159 | ** E1 port 1 |
| 160 | ** CDC-ACM (control + data) |
| 161 | ** DFU (device firmware upgrade) |
| 162 | |
| 163 | The interfaces have self-explanatory string descriptors like |
| 164 | |
| 165 | ---- |
| 166 | iInterface 6 E1 port 0 |
| 167 | iInterface 8 E1 port 1 |
| 168 | iInterface 9 GPS (CDC control) |
| 169 | iInterface 10 GPS (CDC data) |
| 170 | iInterface 11 DFU runtime |
| 171 | ---- |
| 172 | |
| 173 | ==== E1 ports |
| 174 | |
| 175 | There are two physical E1 ports in the icE1usb. Each is exposed via its own USB _interface_. |
| 176 | |
| 177 | Each port (USB _interface_) contains two _altsettings_: |
| 178 | |
| 179 | * one altsetting with no data endpoints (E1 disabled, this is the default) |
| 180 | * one altsetting with isochronous IN/OUT endpoints (E1 enabled) |
| 181 | |
| 182 | In order to activate one E1 port, the driver must perform a USB standard |
| 183 | request to activate the _enabled_ altsetting. |
| 184 | |
| 185 | NOTE:: Please note that on many XHCI host controllers there seem to be |
| 186 | implementation flaws in the XHCI host controller firmware preventing the |
| 187 | activation of both icE1usb ports simultaneously. The XHCI controller |
| 188 | firmware erroneously claims that there is insufficient bus bandwidth. |
| 189 | However, the same icE1usb hardware/firmware works perfectly fine with |
Harald Welte | 4090182 | 2022-01-18 20:13:53 +0100 | [diff] [blame] | 190 | OHCI, UHCI and EHCI host controllers. See |
| 191 | https://osmocom.org/projects/e1-t1-adapter/wiki/Isochronous_USB_Issues for a user-maintained list of USB hosts / controllers and whether or not they work with two E1 ports. |
Harald Welte | 9df9995 | 2022-01-17 17:16:09 +0100 | [diff] [blame] | 192 | |
| 193 | As most modern [PC] hardware has XHCI host controllers, you need to |
| 194 | choose your hardware carefully if concurrent operation of both icE1usb |
| 195 | ports is required in your application. |
| 196 | |
| 197 | ==== CDC-ACM with GPS NMEA |
| 198 | |
| 199 | There's a CDC-ACM (virtual com port) interface available in the icE1usb. |
| 200 | This will be supported by the standard `cdc_acm` driver of your |
| 201 | operating system, and will expose a `/dev/ttyACMx` device on Linux. |
| 202 | |
| 203 | The port provides read-only access to the GPS receiver on-board the |
| 204 | icE1usb. You can use this to |
| 205 | |
| 206 | * determine the GPS fix (and hence 1PPS frequency reference) |
| 207 | availability |
| 208 | * obtain the GPS position of the device |
| 209 | |
| 210 | NOTE:: Write access to the GPS receiver is not permitted as the icE1usb |
| 211 | firmware needs to control the GPS receiver for frequency reference |
| 212 | purposes. |
| 213 | |
| 214 | ==== DFU (Device Firmware Upgrade) |
| 215 | |
| 216 | There's a DFU interface available in order to update the icE1usb |
| 217 | gateware and firmware. For more information, see [[firmware]] above. |