timvideos/hdmi2usb-fx2-firmware

HDMI2USB firmware for the Cypress FX2 found on the Digilent Atlys and Numato Opsis boards.

HDMI2USB-fx2-firmware

This repository contains the firmware used in the HDMI2USB project on the Cypress FX2 chip found on boards such as the Numato Opsis and the Digilent Atlys boards.

Firmware is generally compiled with SDDC 3.6 and the sdas8051 assembler. Older versions might work but have been known to generate incorrect firmware.

microload

microload is firmware which loads a second stage firmware from an FPGA via I2C.

In microload every program byte counts and thus is hand coded in assembly.

The firemware is used on the Numato Opsis board to allows the FPGA to switch the FX2 functionality.

eeprom-unconfigured

eeprom-unconfigured will cause the Cypress FX2 which boot with a given VID/PID and then wait for full firmware to be loaded via USB.

JTAG

The JTAG firmware is used to allow loading gateware onto an FPGA.

• ixo-usb-jtag

HDMI2USB UVC+CDC

This is the primary firmware for HDMI2USB functionality.

The firmware is responsible for transporting the video data off of the FPGA. It does this by enumerating as a USB Video Class device; a standard way of interfacing devices such as webcams to a host. Linux, Windows and OS X all include support out of the box for reading taking to such devices.

The firmware is also used for control and debugging of the system, through a USB Communications Class Device. This is a common way of attaching serial ports to the system, and under Linux it can be accessed at /dev/ttyUSBX.

Cypress EZ-USB FX2LP

FIXME: Put some documentation about the FX2 here.

Cypress EZ-USB FX2LP

Cypress’s EZ-USB® FX2LP™ (CY7C68013A/14/15/16A) is a low power, highly integrated USB 2.0 microcontroller. FX2LP has a fully configurable General Programmable Interface (GPIF™) and master/slave endpoint FIFO (8-bit or 16-bit data bus), which provides an easy and glueless connection to popular interfaces such as ATA, UTOPIA, EPP, PCMCIA, DSP, and most processors.

Boards

Numato Opsis

• FX2 - CY7C68013A_100AC - 100 pin version

• EEPROM - 24AA02E48 - 256bytes (128 usable)

• Bank A/Port A, Bank B/Port B, Bank C/Port D, Bank F/Port C, Bank H/RDY+CTRL - FPGA IO Pins

• Bank G/Port E connected to FPGA JTAG.

• 2 x Hardware UARTs

• 1 x Interrupts?

• Further Documentation

Digilent Atlys

• FX2 - CY7C68013A-56 - 56 pin version

• EEPROM - 24AA128 - 16kbytes

• Bank A/Port A, Bank B/Port B, RDY+CTRL - FPGA IO Pins

• Bank C/Port D connected to FPGA JTAG.

• Further Documentation

Building

make load-fx2

will build and flash the FX2 firmware. This requires the hdmi2usb-mode-switch command, which on Debian Stretch and later can be installed using the hdmi2usb-mode-switch package, otherwise see HDMI2USB-mode-switch. It also requires SDCC.

By default the firmware will be built for the Opsis board. This can be changed by passing BOARD=atlys to make to build for the Atlys boards. The audio firmware also supports BOARD=fx2miniboard for building for the Cypress EZ-USB FX2LP.

To build the docs, doxygen is required. Then run

make docs

There are three ways to run hdmi2usb-mode-switch:

1. As root
2. Install the unbind-helper as a setuid binary
3. Install the udev-rules which sets the permissions of the unbind.

hdmi2usb-fx2-firmware's Issues

Port examples/leds to Opsis & Atlys boards

Add support for the CY7C68013A Mini dev board

For developing FX2 firmware, you can get most of the way using the cheap "dev boards" you can get on eBay and other distributors.

Figure out why serial number reading in the FX2 firmware isn't working on the Opsis

From @mithro on June 8, 2016 7:49

Currently when loading the FX2 firmware on Opsis we are still getting the "fallback" serial number reported in the USB information.

[1905564.963987] usb 3-4.3: New USB device found, idVendor=2a19, idProduct=5442
[1905564.963992] usb 3-4.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[1905564.963995] usb 3-4.3: Product: HDMI2USB.tv - Numato Opsis Board
[1905564.963998] usb 3-4.3: Manufacturer: TimVideos.us
[1905564.964000] usb 3-4.3: SerialNumber: 0123456789abcdef

It is working on the shipping firmware;

[1905693.473306] usb 3-4.3: New USB device found, idVendor=2a19, idProduct=5442
[1905693.473310] usb 3-4.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[1905693.473313] usb 3-4.3: Product: HDMI2USB.tv - Numato Opsis Board
[1905693.473315] usb 3-4.3: Manufacturer: TimVideos.us
[1905693.473317] usb 3-4.3: SerialNumber: ffffd8803956c79a
[1905693.492402] uvcvideo: Found UVC 1.00 device HDMI2USB.tv - Numato Opsis Board (2a19:5442)
[1905693.493315] uvcvideo: UVC non compliance - GET_DEF(PROBE) not supported. Enabling workaround.
[1905693.494804] cdc_acm 3-4.3:1.2: ttyACM0: USB ACM device

JTAG mode is also working;

[1905520.002403] usb 3-4.3: New USB device found, idVendor=16c0, idProduct=06ad
[1905520.002408] usb 3-4.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[1905520.002412] usb 3-4.3: Product: Opsis (JTAG Mode)
[1905520.002428] usb 3-4.3: Manufacturer: Numato
[1905520.002430] usb 3-4.3: SerialNumber: ffffd8803956c79a

Copied from original issue: timvideos/HDMI2USB-litex-firmware#264

Import good cdc-acm serial emulation firmware

Create a microload that works on the Atlys and Opsis board

Currently microload firmware only works on the Opsis. It loads stuff via the hardware I2C controller with the FPGA emulation something like an EEPROM.

This doesn't work on the Atlys because the FPGA isn't connected to the I2C control lines.

Instead we could use the FIFO interface and a flag IO. The flag pin could also be used for reset.

File licensing issues

Background: See PR #23, this comment.
The following files are licensed under a license that prevents us using the Linux headers with them:

• read-seralno.h - LGPLv3+
• makestuff.h - LGPLv3+
• debug.h - LGPLv3+
• lstParse.py - LGPLv3+
• defs.h - LGPLv3+
• app.c - LGPLv3+
• examples/serial/serial.c - LGPLv3+
• {hdmi2usb,examples}/Makefile - LGPLv3+

Refactor / rewrite the version embedding code

There is much better version embedding stuff in the C firmware found HDMI2USB-litex-firmware repo. See https://github.com/timvideos/HDMI2USB-litex-firmware/blob/master/firmware/version_data.sh

This embeds the proper git version info and such.

Set up travis building of this repo

We should be building the firmware on every commit.

The travis code for the HDMI2USB-litex-firmware is here ->
https://github.com/timvideos/HDMI2USB-litex-firmware/blob/master/.travis.yml

Import ixo-usb-jtag firmware and cleanup

Add 1080p30 resolution in the FX2 firmware

From @enjoy-digital on January 25, 2016 18:46

Gateware now supports 1080p30, it would be good to have this resolution available in the FX2 firmware.

Copied from original issue: timvideos/HDMI2USB-litex-firmware#190

Transfer information from Google Doc to this repo

There is a lot of information about the FX2 in this Google Doc.

This information should probably be in this repo.

Particularly important is the "Board Connections" section which documents the Atlys / Opsis connection to the FX2.

UVC non compliance - GET_DEF(PROBE) not supported

From @mithro on January 10, 2016 6:14

From @CarlFK on March 31, 2015 22:45

so that v4l2-compliance doesn't error:

$ v4l2-compliance -d /dev/video1

    fail: v4l2-test-controls.cpp(513): g_ext_ctrls worked even when no controls are present
test VIDIOC_G/S/TRY_EXT_CTRLS: FAIL

And we don't get the note in dmesg:

[ 5188.310191] usb 2-1.3: new high-speed USB device number 7 using ehci-pci
[ 5188.403409] usb 2-1.3: New USB device found, idVendor=1d50, idProduct=60b7
[ 5188.403417] usb 2-1.3: New USB device strings: Mfr=1, Product=2, SerialNumber=0
[ 5188.403422] usb 2-1.3: Product: HDMI2USB
[ 5188.403425] usb 2-1.3: Manufacturer: JANI
[ 5188.403900] uvcvideo: Found UVC 1.00 device HDMI2USB (1d50:60b7)
[ 5188.404196] uvcvideo: UVC non compliance - GET_DEF(PROBE) not supported. Enabling workaround.

https://github.com/timvideos/HDMI2USB/blob/master/cypress/uvc.c#L94

             // case UVC_GET_DEF:
             // FIXME: Missing this case causes the following errors
             // uvcvideo: UVC non compliance - GET_DEF(PROBE) not supported. Enabling workaround.

Copied from original issue: timvideos/HDMI2USB-jahanzeb-firmware#120

Copied from original issue: timvideos/HDMI2USB-litex-firmware#148

Create a common Makefile for fx2 firmware

There is a lot of code in examples/leds/Makefile and examples/serial/Makefile -- we should have something that can just be included.

Having the serial port open prevents video from streaming

From @xfxf on August 7, 2016 9:2

Steps to repo;

1. Connect the HDMI2USB
2. Connect to the serial port using flterm
3. Try and get video from the video device

On newer Ubuntu versions you are the following output while trying to get video;

[19325.775956] uvcvideo: Failed to set UVC probe control : -110 (exp. 26).
[19330.773331] uvcvideo: Failed to set UVC probe control : -110 (exp. 26).
[19335.770452] uvcvideo: Failed to set UVC probe control : -110 (exp. 26).
[19340.767697] uvcvideo: Failed to set UVC probe control : -110 (exp. 26).

If you then kill flterm, you can then get video from the video device if you wait long enough. The kernel output will look like this;

[19424.301449] uvcvideo: Failed to set UVC probe control : -110 (exp. 26).
[19429.298562] uvcvideo: Failed to set UVC probe control : -110 (exp. 26).
[19434.295781] uvcvideo: Failed to set UVC probe control : -110 (exp. 26).
[19443.310507] usb 2-1.1: reset high-speed USB device number 24 using ehci-pci

After the reset line, the video will start streaming in.

From the point you have gotten video you can have both the serial and video running. Stopping / starting the programs (the video or serial) has no effect.

It works first time if you do;

1. Connect the HDMI2USB
2. Try and get video from the video device
3. Connect to the serial port.

Copied from original issue: timvideos/HDMI2USB-litex-firmware#281

Rewrite the FX2 firmware to be understandable

From @mithro on January 10, 2016 6:30

The FX2 firmware is currently really hard to understand. We should rewrite it to make it easier to understand an extend.

This has been started by @mithro at https://github.com/mithro/HDMI2USB-misoc-firmware/tree/fx2-refactor

The big changes so far are;

• Using the Linux headers for ch9 and uvc constants.
• Using the Linux headers to build the descriptors.
  • See https://github.com/mithro/fx2lib-linux-headers
• Actually using comments and links to the spec documentation.
• Using C99 rather then C89.
• Start for actually support the UVC control commands.
  • Need to figure out a way to communicate the information to the FPGA.

Copied from original issue: timvideos/HDMI2USB-litex-firmware#149

Travis not pushing docs to gh-pages

According to the gh-pages branch, https://code.timvideos.us/HDMI2USB-fx2-firmware/, and the script generating the docs, Travis should be publishing the docs on every commit to master. It seems not to be currently doing so

Fill in all properties on document generation

See the following;

# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
# control system is used.

PROJECT_NUMBER         =

# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.

PROJECT_BRIEF          =

# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
# in the documentation. The maximum height of the logo should not exceed 55
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory.

PROJECT_LOGO           =

Create LED blinking test firmware

We need an FX2 firmware which flashes the LEDs connected to the FX2.

Add PTZ support to uvc device

From @mithro on January 10, 2016 6:35

From @shenki on September 3, 2014 5:37

It appears that the v4l2 uvcvideo device can support PTZ controls, and the kernel has support for this: https://lkml.org/lkml/2014/7/8/837

We should add support to our uvc device, and make the fx2 firmware pass on the commands through to the serial board that does PTZ control.

Copied from original issue: timvideos/HDMI2USB-jahanzeb-firmware#95

Copied from original issue: timvideos/HDMI2USB-litex-firmware#150

serial port drops characters

From @CarlFK on March 22, 2016 5:50

When I send characters too fast, most of them get dropped.

I think the problem was described as: there is no flow control.

Seems like there have been more than one work around.

Can this be fixed on the device side?

Copied from original issue: timvideos/HDMI2USB-litex-firmware#219

Expose I2C interfaces via USB

From @mithro on January 10, 2016 6:48

From @mithro on June 24, 2014 5:57

Exposing the EDID information and other I2C busses via the USB could be useful for debug an experimentation.

One solution would be to emulate the i2c_tiny_usb device. A driver for this device already exist in the Linux kernel. See http://www.harbaum.org/till/i2c_tiny_usb/index.shtml for more information.

Copied from original issue: timvideos/HDMI2USB-jahanzeb-firmware#48

Copied from original issue: timvideos/HDMI2USB-litex-firmware#157

Create FTDI emulation firmware

• https://github.com/mithro/fx2-ftdi-emulation
• https://docs.google.com/document/d/1o4jDru_V9IBvkkuhyQb1zBzm_QvzDBo2B5adP2bvahY/edit
• https://docs.google.com/document/d/1xGOBDtByU6D7ry2WnLUE_slqmjgId_JAscZK3gMCLug/edit