This version (22 Dec 2022 13:04) was approved by sergiu arpadi.
Table of Contents
SPI Engine Tutorial - PulSAR-ADC
The goal of this tutorial is to present the process of adding SPI Engine support for an ADI precision converter or family of converters using a few simple steps. The target carrier is the Digilent Cora-z7s board using a Pmod connector.
Evaluating the target device
The aim of this project is to provide support for a family of ADCs which come in the form of pulsar-adc-pmods. They all share the same interface and the same PCB, the differences being found in their performance. The table below offers a comparison between the timing parameters of the SPI interface for these devices. Using this table we can see how much they have in common and where the key differences are. All the values are for 3.3V VIO since the Cora-z7s is only 3.3V capable.
| Device | Resolution | KSPS | T_SPI_SCLK min [ns] | T_CONV max [ns] | T_CYC min [ns] | T_ACQ min [ns] |
|---|---|---|---|---|---|---|
| AD7942 | 14 | 250 | 18 | 2200 | 4000 | 1800 |
| AD7946 | 14 | 500 | 15 | 1600 | 2000 | 400 |
| AD7988-1 | 16 | 100 | 12 | 9500 | 1000 | 500 |
| AD7685 | 16 | 250 | 15 | 2200 | 4000 | 1800 |
| AD7687 | 16 | 250 | 10 | 2200 | 4000 | 1800 |
| AD7691 | 16 | 250 | 15 | 2200 | 4000 | 1800 |
| AD7686 | 16 | 500 | 15 | 1600 | 2000 | 400 |
| AD7693 | 16 | 500 | 15 | 1600 | 2000 | 400 |
| AD7988-5(B) | 16 | 500 | 12 | 1600 | 2000 | 400 |
| AD7988-5(C) | 16 | 500 | 12 | 1200 | 2000 | 800 |
| AD7980 | 16 | 1000 | 10 | 710 | 1000 | 290 |
| AD7983 | 16 | 1333 | 12 | 500 | 750 | 250 |
| AD7690 | 18 | 400 | 15 | 2100 | 2500 | 400 |
| AD7982 | 18 | 1000 | 12 | 710 | 1000 | 290 |
| AD7984 | 18 | 1333 | 12 | 500 | 750 | 250 |
The device with the most demanding timing specifications is the AD7984. It requires the highest amount of data (18 bit) to be read in the least amount of time (T_ACQ 250ns). The other devices will work with the same HDL by just using different “downgraded” configurations.
SPI Engine hierarchy instantiation
The SPI Engine can be implemented in two ways, either by placing and connecting each IP individually or by using the function provided by the spi_engine.tcl script https://github.com/analogdevicesinc/hdl/blob/master/library/spi_engine/scripts/spi_engine.tcl
Using the script ensures that the correct connections are being made and that the IP cores will receive the correct parameter configuration since certain parameters need to be set to the same value. The function takes the following argumets
proc spi_engine_create {{name "spi_engine"} {data_width 32} {async_spi_clk 1} {num_cs 1} {num_sdi 1} {sdi_delay 0} {echo_sclk 0}}
data_width will set the width of the data bus / data line used by the SPI engine to connect to the DMA and which serves the purpose of sending ADC sample data to the DDR memory. The data_width value will also set the maximum word length for the SPI transfer. Valid values are are 8/16/24/32. The DMA valid values are 16/32/64/128[…]. Since the Pulsar_ADC devices are all single SDI/SDO and some of them require 18bit transfers, this value will be rounded to 32bit.
async_spi_clk will chose the reference clock for the SPI Engine. Setting this parameter to 0 will configure the hierarchy to use the axi clock (100MHz) as the reference clock. Setting it to 1 will allow for an external referece clock (spi_clk). Because some devices need 80MHz SCLK, a 160MHz reference clock is required which implies an external reference.
num_cs selects the number of CS lines.
num_sdi selects the number of SDI lines.
sdi_delay The latch of the SDI line can be delayed with 1, 2 or 3 SPI core clock cycle. Needed for designs with high SCLK rate (>50MHz).
Configuration tcl code and result below:
source $ad_hdl_dir/library/spi_engine/scripts/spi_engine.tcl set data_width 32 set async_spi_clk 1 set num_cs 1 set num_sdi 1 set sdi_delay 1 set hier_spi_engine spi_pulsar_adc spi_engine_create $hier_spi_engine $data_width $async_spi_clk $num_cs $num_sdi $sdi_delay
SPI Engine reference clock
There are 3 categories of devices depending on the SPI interface clock (SCLK): 80 MHz, 50MHz (one device) and 40MHz. SCLK will be derived from the spi_clk reference signal using an internal prescaler with this formula
f_sclk = f_clk / ((div + 1) * 2)
Therefore a 160MHz reference clock will be needed for the 40 and 80MHz variants and 100MHz for the 50MHz SCLK. The axi_clkgen IP core will be used to obtain the 160MHz which will be the default value to ensure that the design bitstream meets timing. This IP can also be configured from software to output 100MHz.
ad_ip_instance axi_clkgen spi_clkgen ad_ip_parameter spi_clkgen CONFIG.CLK0_DIV 5 ad_ip_parameter spi_clkgen CONFIG.VCO_DIV 1 ad_ip_parameter spi_clkgen CONFIG.VCO_MUL 8
Clock source for IP and spi_clk connection
ad_connect $sys_cpu_clk spi_clkgen/clk ad_connect spi_clk spi_clkgen/clk_0 ad_connect spi_clk spi_pulsar_adc/spi_clk ad_connect spi_clk axi_pulsar_adc_dma/s_axis_aclk
AD7984 Timing diagram
The above image shows the wave forms for a particular operating mode supported by the device which will be implemented using the SPI Engine in offload mode.
Key timing characteristics
18 bit transfers 750 ns T_CYC 500 ns T_CONV 250 ns T_ACQ 12 ns T_SCLK @ >3V VIO (cora pmod is 3V3)
Sample rate control
The T_CYC parameter is the what sets the maximum sample rate (1/750 ⇒ 1333 KSPS). To achieve precise control over the the sample rate we will use a PWM generator (AXI PWM GEN) using the spi_clk as reference. The spi_clock is used to avoid clock domain crossing mechanisms which will introduce latency, decreasing the overall performance of the system.
ad_ip_instance axi_pwm_gen pulsar_adc_trigger_gen ad_ip_parameter pulsar_adc_trigger_gen CONFIG.PULSE_0_PERIOD 120 ad_ip_parameter pulsar_adc_trigger_gen CONFIG.PULSE_0_WIDTH 1 ad_connect spi_clk pulsar_adc_trigger_gen/ext_clk ad_connect $sys_cpu_clk pulsar_adc_trigger_gen/s_axi_aclk ad_connect sys_cpu_resetn pulsar_adc_trigger_gen/s_axi_aresetn ad_connect pulsar_adc_trigger_gen/pwm_0 $hier_spi_engine/offload/trigger
Since the AXI PWM IP core is connected to the system with AXI4 Lite, the software will be able to change the frequency of its output at any time. The resolution of the PWM period is the reference clock period (spi_clk) providing a wide range of options.
The PWM output will be used as a trigger signal for the offload IP core.
The CS signal will be used to drive CNV and will have the same frequency as the PWM-trgger signal.
DMA setup
DMA destination bus (connection to Zynq – DDR memory) shall always be 64 bit wide AXI4 MM and source bus shall be data_wdth * num_sdi = 32 bit, AXI4 Stream.
ad_ip_instance axi_dmac axi_pulsar_adc_dma ad_ip_parameter axi_pulsar_adc_dma CONFIG.DMA_TYPE_SRC 1 ad_ip_parameter axi_pulsar_adc_dma CONFIG.DMA_TYPE_DEST 0 ad_ip_parameter axi_pulsar_adc_dma CONFIG.CYCLIC 0 ad_ip_parameter axi_pulsar_adc_dma CONFIG.SYNC_TRANSFER_START 0 ad_ip_parameter axi_pulsar_adc_dma CONFIG.AXI_SLICE_SRC 0 ad_ip_parameter axi_pulsar_adc_dma CONFIG.AXI_SLICE_DEST 1 ad_ip_parameter axi_pulsar_adc_dma CONFIG.DMA_2D_TRANSFER 0 ad_ip_parameter axi_pulsar_adc_dma CONFIG.DMA_DATA_WIDTH_SRC $data_width //32 ad_ip_parameter axi_pulsar_adc_dma CONFIG.DMA_DATA_WIDTH_DEST 64
The system clock is used as destination clock and the spi_clk is used as source clock
ad_connect spi_clk axi_pulsar_adc_dma/s_axis_aclk ad_mem_hp1_interconnect $sys_cpu_clk axi_pulsar_adc_dma/m_dest_axi
System Top
This is a layer on top of the system_wrapper generated by Vivado used to instantiate IO buffers, I/ODDRs or to create some custom connections which would be harder to do in the block design. It also alows for more consistency across projects. In this particular case we use it to place an IO buffer for the ADC power down signal (pulsar_adc_spi_pd).
System Constraints
The system_constr.xdc file inside the carrier folder (/coraz7s/system_constr.xdc) is used for defining the physical FPGA pins used by this particular project (in this case the AD7984 ADC), excluding the “common” design for the carrier board which has a separate constraints file (i.e. DDR pins, Ethernet, UART etc). It also contains some timing constraints specific to the SPI Engine.
create_generated_clock -name spi_clk -source [get_pins -filter name=~*CLKIN1 -of [get_cells -hier -filter name=~*spi_clkgen*i_mmcm]] -master_clock clk_fpga_0 [get_pins -filter name=~*CLKOUT0 -of [get_cells -hier -filter name=~*spi_clkgen*i_mmcm]]
# relax the SDO path to help closing timing at high frequencies
set_multicycle_path -setup 8 -to [get_cells -hierarchical -filter {NAME=~*/data_sdo_shift_reg[*]}] -from [get_clocks spi_clk]
set_multicycle_path -hold 7 -to [get_cells -hierarchical -filter {NAME=~*/data_sdo_shift_reg[*]}] -from [get_clocks spi_clk]
set_multicycle_path -setup 8 -to [get_cells -hierarchical -filter {NAME=~*/execution/inst/left_aligned_reg*}] -from [get_clocks spi_clk]
set_multicycle_path -hold 7 -to [get_cells -hierarchical -filter {NAME=~*/execution/inst/left_aligned_reg*}] -from [get_clocks spi_clk]
Testbench
To check the overall performance of the design and also to expose any major bugs, the system can be tested using a testbench. https://github.com/analogdevicesinc/testbenches
The testbench framework is designed to use the same bd.tcl as the actual project
https://github.com/analogdevicesinc/testbenches/blob/main/pulsar_adc_pmdz/system_bd.tcl#L50
The setup assumes the testbenches repo is cloned inside the hdl repo. To build the testbench project simply run
make cfg1
from the hdl/testbenches/pulsar_adc_pmdz/ folder. Besides exposing possible bugs, using the testbench will provide the user with an early way of evaluating the timing of the design. The testbench can also be a very useful tool for IP development.
Evaluating the result
Due to the limits of the SPI Engine cores, T_CYC needs to be increased slightly over the minimum value, to ensure that the design meets the T_CONV minimum. This will slightly lower the maximum sample rate of the design from 1.333 MSPS to 1.322 MSPS.
Holding CS high for 500ns ensures that we always meet T_CONV minimum.
The 250ns minimum T_ACQ is alse met with a slightly higher value of 256.25ns.
Overall the project appears to be functional and ready for the next step in development, using software.
Software section
The section is still under development.
Additional Resources
resources/fpga/peripherals/spi_engine/tutorial.txt · Last modified: 22 Dec 2022 13:04 by sergiu arpadi