Document GPIO and SPI signals to FPGA

doc/fpga_firmware.md

@@ -23,6 +23,84 @@ LED3 is on when the timetagger is active (at least one event type is enabled).
 
 LED4 to LED7 are controlled by software via register `LED_STATE`.
 
+
+# GPIO signals
+
+The GPIO controller in the Zynq PS is internally connected to the FPGA.
+A few of the internal GPIO signals are used by the firmware.
+By manipulating these GPIO signals, the Linux system can reset the FPGA firmware and control specific features.
+
+| EMIO GPIO pin | Linux GPIO | Direction      | Description |
+|---------------|------------|----------------|-------------|
+| 0             | 54         | out (to FPGA)  | Global firmware reset |
+| 1             | 55         | in (from FPGA) | Reset status report |
+| 2             | 56         | out (to FPGA)  | ADC clock duty cycle stabilizer |
+
+### GPIO 0: Global firmware reset
+
+GPIO 0 drives a global reset signal to the FPGA firmware.
+
+- GPIO 0 is an output from the PS to the FPGA.
+- Driving this signal as `0` resets the FPGA firmware.
+- Driving this signal as `1` releases the firmware reset.
+
+This signal should be used to reset the FPGA during or after any manipulations
+of the ADC clock signal such as switching the ADC clock duty cycle stabilizer.
+
+After switching this signal to `1`, it may take approximately 1 ms
+for the FPGA to lock clocks and release its reset.
+
+**Note:** Any attempt to access firmware registers via the AXI bus while
+the FPGA is in reset, will crash the Zynq PS.
+For that reason, the output state of GPIO 0 must remain at `1` as long
+as any software is interacting with the FPGA.
+
+### GPIO 1: Reset status report
+
+GPIO 1 reports the reset status of the FPGA firmware.
+
+- GPIO 1 is an input to the PS from the FPGA.
+- The signal is `0` while the FPGA is in reset.
+- The signal is `1` if the FPGA reset has been released.
+
+### GPIO 2: ADC clock duty cycle stabilizer
+
+GPIO 2 drives the clock duty cycle stabilizer signal of the LTC2145 ADC.
+
+- GPIO 2 is an output from the PS to the FPGA.
+- Driving this signal as `0` disables the clock duty cycle stabilizer.
+- Driving this signal as `1` enables the clock duty cycle stabilizer.
+
+This signal is only supported on Red Pitaya boards with 2 input channels.
+
+This GPIO signal is asynchronously routed through the FPGA to the ADC.
+Changing the state of this signal may shift the phase of the ADC data clock.
+It must therefore only be changed while the FPGA firmware is in reset.
+
+
+# SPI signals
+
+The SPI controller `SPI0` in the Zynq PS is internally connected to the FPGA.
+The SPI signals from this controller are asynchronously routed through the FPGA to the LTC2145 ADCs.
+
+This feature is only supported on Red Pitaya boards with 4 input channels.
+Boards with 2 input channels do not provide access to the SPI bus of the ADC.
+
+The SPI signals are connected as follows:
+
+| SPI signal | Direction | Connection           |
+|------------|-----------|----------------------|
+| SCLK       | out       | SCK pin of both ADCs |
+| MOSI       | out       | SDI pin of both ADCs |
+| MISO       | in        | wired to `0`         |
+| SS[0]      | out       | CSn pin of ADC A     |
+| SS[1]      | out       | CSn pin of ADC B     |
+| SS[2]      | out       | not connected        |
+
+Note that programming the timing registers of the ADC, may shift the phase of the ADC data clock.
+It must therefore only be done while the FPGA firmware is in reset.
+
+
 # Analog acquisition chain
 
 The analog acquisition chain has 2 analog input signals (or 4 channels for a 4-channel device).