Introduction
This documentation is for WRTCLK firmware version 0.5. Older firmware versions are not supported.
The most recent PDF version of this document is available here.
An online version of the WRTCLK documentation is here
Information about the different firmware releases can be found in the builds.txt file.
Overview
WRTCLK is an FPGA firmware that can translate between different timestamp and clock distribution protocols.
The current version of the firmware is built for the EXPLODER3 hardware from GSI (experiment electronics department).
The following protocols are supported in the firmware
| Protocol | Base frequency | Input | Output |
|---|---|---|---|
| BuTiS 2-wire (Schakel) | 200 MHz | yes | yes (internal) |
| Ratatime | 100 MHz | (deactivated) | yes |
| Rataclock for PLL | 25 MHz | yes | yes |
| Rataclock for any FPGA | 6.25 MHz | no | yes |
The optical White Rabbit protocol is not supported directly. To synchronize WRTCLK with White Rabbit, a certified receiver must be used to convert to the BuTiS 2-wire (Schakel) protocol.
Inputs/outputs
The figure below shows all signals that are accepted and generated by the WRTCLK firmware on the EXPLODER3 hardware.

Configuration
The configuration of WRTCLK can be changed using the 6 RES jumpers.
Rataclock duty cycle (RES1)
The PLLs of rataclock receivers have somewhat strict requirements for the duty cycle of the received rataclock signal. However, the EXPLODER3 hardware differs slightly from one production run to the next, affecting the signal timing on the LEMO outputs. This variation in signal timing makes it impossible to produce a good rataclock output signal on all EXPLODER3 modules with a fixed duty cycle.
The RES1 jumper selects between two different settings for the rataclock output duty cycle. Check with a scope connected to the output, which setting produces the better signal.
A good rataclock signal is one, where the duty cycle of the short pulses is between 30% and 40%, and where the duty cycle of the long pulses is between 60% and 70%.
Clock source (RES2/RES3)
The main clock of WRTCLK runs at a frequency of 200 MHz. All other clocks are derived from this 200 MHz clock. The clock source switches (RES2/RES3) allow choosing between different sources for the main clock.
| Setting | RES2 | RES3 | Clock source |
|---|---|---|---|
| 0 | 0 | 0 | Internal oscillator |
| 1 | 1 | 0 | Rataclock input (LEMO 1) |
| 2 | 0 | 1 | BuTiS input (Schakel) (LVDS 1) |
Note: If a clock source other than the internal oscillator is selected, but no clock signal is applied at the respective input, then WRTCLK will not function properly.
LED display (RES4)
The 8 colored LEDs on the side of the EXPLODER3 case have different meaning depending on the RES4 switch setting.
| RES4 | LED mode |
|---|---|
| 0 | BuTiS status / Rataclock status |
| 1 | Timestamp counters |
When RES4 is in OFF/OPEN position, information about the BuTiS input signals is displayed. When a BuTiS signal is connected, LED1 should toggle about 3 times per second. LED2 should light up green. LED3 should stay off. LED8 should toggle about once per second.
| RES4 | LED | Color | Meaning |
|---|---|---|---|
| 0 | 1 | white | BuTiS clock counter (bit 26) |
| 2 | green | BuTiS receiver synced OK | |
| 3 | blue | BuTiS error | |
| 4 | red | Rataclock receiver status bit 0 | |
| 5 | white | Rataclock receiver status bit 1 | |
| 6 | green | Rataclock receiver sync lost bit 1 | |
| 7 | blue | Rataclock receiver sync lost bit 2 | |
| 8 | red | BuTiS receiver timestamp (bit 30) |
When RES4 is in ON/CLOSED position, information about the internal timestamp counters is displayed. This can be used to check synchronicity between the different timestamps.
| RES4 | LED | Color | Meaning |
|---|---|---|---|
| 1 | 1 | white | internal timestamp bit 29 |
| 2 | green | internal timestamp bit 30 | |
| 3 | blue | rataclock receiver timestamp bit 29 | |
| 4 | red | rataclock receiver timestamp bit 30 | |
| 5 | white | BuTiS receiver timestamp bit 29 | |
| 6 | green | BuTiS receiver timestamp bit 30 | |
| 7 | blue | ratatime receiver timestamp bit 29 | |
| 8 | red | ratatime receiver timestamp bit 30 |
Timestamp source (RES5/RES6)
The switches RES5 and RES6 allow to choose between several timestamp sources. This setting should normally follow the setting for the clock source, but it may be useful to make an independent selection.
| Setting | RES5 | RES6 | Timestamp source |
|---|---|---|---|
| 0 | 0 | 0 | Internal rataclock sender |
| 1 | 0 | 1 | External rataclock receiver |
| 2 | 1 | 0 | External BuTiS receiver |
| 3 | 1 | 1 | External ratatime receiver |
Serial connection (RES7/RES8)
WRTCLK implements a serial communication interface (UART) on the RES7 and RES8 pins. RES7+ is used as serial input (RX, receiver), and RES8+ as serial output (TX, transmitter). The RES7- and RES8- pins can be used as common ground.
Electrical signaling is similar to RS-232, so any standard USB-to-serial adapter can be attached to these pins and can then communicate with the WRTCLK firmware.
Serial connection properties
The UART uses these settings:
| Property | Value |
|---|---|
| baud rate | 115200 baud |
| stop bits | 1 |
| parity | none |
| byte size | 8 bits |
Serial protocol
WRTCLK continuously sends status updates in a fixed message format. Every message is 20 bytes long. The message format is described in the table below:
| Byte | Meaning |
|---|---|
| 0 | "0", fixed |
| 1 | "1", fixed |
| 2 | bitmask of configuration jumpers (RES1-RES7) |
| 3 | firmware version, hexadecimal |
| 4 | bitmask of VHDL configuration bits |
| 5 | bits 7-2: BuTiS receiver timestamp |
| bit 1: BuTiS synced state | |
| bit 0: BuTiS error | |
| 6 | rataclock receiver status (3-5) / sync lost (0-2) |
| 7 | bits 0-3: PLL lock status |
| 8 | ratatime receiver status |
| 9 | LED status (BuTiS / rataclock) |
| 10 | received character 0 |
| 11 | received character 1 |
| 12 | received character 2 |
| 13 | received character 3 |
| 14 | "E", fixed |
| 15 | "x", fixed |
| 16 | selected timestamp, bits 32-39 |
| 17 | selected timestamp, bits 40-47 |
| 18 | selected timestamp, bits 48-55 |
| 19 | selected timestamp, bits 56-63 |
The VHDL configuration bits reflect which parts have been included in the WRTCLK firmware during build-time.
| VHDL Config Bit | Meaning |
|---|---|
| 0 | Use ratatime sender |
| 1 | Use ratatime receiver |
| 2 | Use UART input |
| 3 | Use UART output |
| 4 | Use rataclock sender |
| 5 | Use BuTiS sender |
| 6 | Use BuTiS receiver |
| 7 | Use T5NS sender |
The 'received characters' show the last 4 characters, that have been successfully received on the UART RX input.
Firmware update
The firmware may be updated either via the internal JTAG port (using a GSI PROMO-8 adapter) or the external JTAG port (micro-USB).
The easiest way is to use a Digilent HS2 programming adapter and a micro-USB cable to connect to the external JTAG port.
Use Xilinx Impact to connect with the adapter to JTAG and load the firmware into the on-board flash memory.
EXPLODER flash
The on-board flash memmory is an SPI memory chip of type M25P128-VME6GB. The ID code as reported by impact is 202018.
PROMO adapter
When using the PROMO adapter, its dials must be set to these values: SELA1=1, SELZ1=8.
USB JTAG port
An adapter (cable) is needed from the programming adapter to the micro-USB port. Only a 5-wire USB cable may be used for this purpose (most cables only have 4 wires).
The pin mapping is shown in the table below:
| Digilent HS2 | USB wire | USB meaning | micro-USB pin |
|---|---|---|---|
| 1 TMS | white | D- | 2 |
| 2 TDO | red | VCC | 1 |
| 3 TDI | green | D+ | 3 |
| 4 TCK | black | GND | 5 |
| 5 GND | shield | - | - |
| 6 VCC | yellow | ID | 4 |
Using the EXPLODER HS2 JTAG adapter (see below) the Digilent HS2 programmer can be directly connected to the EXPLODER USB JTAG port.
WRTCLK/EXPLODER adapter boards
For convenience, some adapter PCBs have been designed.
EXPLODER HS2 JTAG
This is the adapter that allows plugging the Digilent HS2 adapter directly into the JTAG micro-USB port of the EXPLODER.
HDMI IDC
This adapter converts allows plugging the white rabbit / BuTiS signal from a PEXARIA or VETAR module directly into the ANY_IN input of the EXPLODER. It converts from an HDMI connector to the 16 pin IDC socket.
RES adapter for WRTCLK
The EXPLODER RES port is usually configured with jumpers that are placed / removed on the different pins. The RES adapter for WRTCLK provides 6 onboard switches to replace the jumpers and allows to connect a USB-UART serial adapter that connects to the RX/TX pins of the RES port. 3 sets of switches allow to set the pin mapping from the USB-UART adapter to the RES port.
KiCAD design files
Design files (KiCAD format) are available here for download.