Firmware

Most logic signals on Urukul are routed from and to the EEM connectors via a Xilinx FPGA configured with gateware which causes it to act as a CPLD. This gateware needs to be loaded onto Urukul (see below).

The compatibility mapping between Urukul hardware and latest release-tagged QUARTIQ bitstreams is as follows.

Hardware Version	CPLD Version (git tag)	CPLD proto_rev
v1.0	v1.3.1	0x8
v1.1	v1.3.1	0x8
v1.2	v1.3.1	0x8
v1.3	v1.3.1	0x8
v1.4	v1.4.0	0x8
v1.5	v1.4.0	0x8

The CPLD gateware contains a register called proto_rev that is incremented for breaking changes in the CPLD register layout. At runtime ARTIQ checks if the CPLD artiq_rev is supported. Starting 3/13/2018 ARTIQ requires proto_rev = 0x08. Earlier versions of ARTIQ require earlier versions of the CPLD gateware with different values of proto_rev.

Note that ARTIQ also emits the error Urukul proto_rev mismatch if the CPLD register can't be read as is the case if the EEM connectors are ordered incorrectly.

DIP Switch

SW1 is a configuration-dependent dip switch.

DIP [1234]	Configuration
[0000]	default for firmware in this repository
[1100]	SuServo

Flashing

Flashing can be done using a Xilinx-compatable JTAG programmer such as the Digilent JTAG-HS2. The follow software tool chains are compatible with the JTAG-HS2.

Flashing with Digilent Adept Windows tool

• Digilent Adept Windows tool. Launch Adept 2, select "Initialise Chain" and it should show the CPLD (for v1.3 this is XC2C128). There is then the option to browse for file, select the urukul.jed built for your hardware, and then hit program.

Flashing with x3cprog

The following instructions are for Linux. Copy the map file xc2c128.map to your machine.

Install x3cprog on your Linux machine. This repository has a .deb compatible with Ubuntu 18.04.

Confirm that the JTAG-HS2 adapter is recognized by your system kernel.

$ dmesg  
usb 1-10.3.4: New USB device found, idVendor=0403, idProduct=6014, bcdDevice= 9.00  `

Confirm that the JTAG-HS2 adapter is recognized by x3cprog

$ xc3sprog -c jtaghs2 -v  
                       
Cable jtaghs2 type ftdi VID 0x0403 PID 0x6014 Desc "Digilent USB Device" dbus data e8 enable eb cbus data 00 data 60
Using Libftdi, Using JTAG frequency   6.000 MHz from undivided clock
No JTAG Chain found

Connect JTAG-HS2 to the Urukul JTAG port. Apply power to the Urukul EEM.

$ xc3sprog -c jtaghs2 -v 
Cable jtaghs2 type ftdi VID 0x0403 PID 0x6014 Desc "Digilent USB Device" dbus data e8 enable eb cbus data 00 data 60
Using Libftdi, Using JTAG frequency   6.000 MHz from undivided clock
JTAG chainpos: 0 Device IDCODE = 0x16d8c093	Desc: XC2C128_TQ144
JTAG loc.:   0  IDCODE: 0x16d8c093  Desc:                  XC2C128_TQ144 Rev: A  IR length:  8
USB transactions: Write 6 read 3 retries 0

Flash

$ xc3sprog -c jtaghs2 -v -p 0 urukul.jed -m xc2c128.map
Cable jtaghs2 type ftdi VID 0x0403 PID 0x6014 Desc "Digilent USB Device" dbus data e8 enable eb cbus data 00 data 60
Using Libftdi, Using JTAG frequency   6.000 MHz from undivided clock
JTAG chainpos: 0 Device IDCODE = 0x16d8c093	Desc: XC2C128_TQ144
Programming row  81                                        
Verify: Success                                        
USB transactions: Write 421 read 417 retries 899

Building Gateware

The gateware for Urukul is maintained here. Xilinx ISE and migen are required.

$ git clone https://github.com/quartiq/urukul

For earlier hardware releases checkout the corresponding git tag.

$ git checkout v1.3.1

To build the drivers, first link path to the Xilinx drivers and then run build.

$ source /opt/Xilinx/14.7/ISE_DS/settings64.sh

$ make

This creates the CPLD gateware in folder build/urukul.jed.