ZmodADC1410 Library User Guide

1. Overview

Digilent provides the ZmodADC1410 Library used to access ZmodADC1410 functionality.
It is part of a pack of libraries to handle the Zmod modules functionality. They cover both Linux and baremetal (standalone) platforms.
The Zmod Base Library implements the functionality that is common to all Zmods.
For each Zmod, separate libraries are implemented, based on the Zmod Base Library. This document describes the ZmodADC1410 Library.
The current usage instructions / demos are provided for the ZmodADC1410 attached to Eclypse board, still ZmodADC1410 can be attached to any Zynq board providing the SYZYGY connector.
The following image shows the overall structure of Zmod Libraries.

The ZmodADC1410 and Zmod Base Library run on the Zynq PS (processing system).
A ZmodADC1410 specific IP core needs to be instantiated in the programmable logic (PL). This IP core can be accessed from the Zynq PS through its registers. The IP core is able to communicate with the memory through a DMA engine. Each Zmod has one particular AXI DMA IP core associated.
Basically:

  • The ZMODADC1410 IP (labeled ZMOD_ADC in the above image) features an internal buffer.
  • The ZMODADC1410 IP acquires data (fills its internal buffer) from its on-board analog to digital converter device.
  • Eventually, the ZMODADC1410 IP waits for a trigger condition before starting the acquisition.
  • The ZMODADC1410 IP reports when its internal buffer is full.
  • The ZMODADC1410 Library initiates an AXI DMA receive transfer, transferring data from the IP's internal buffer into a memory buffer allocated by ZMODADC1410 Library. This buffer contains data for both channels.

Read more on ZMODADC1410 IP behaviour below in the page.

2. ZMODADC1410 Library Implementation Details

The ZMODADC1410 Library implementation uses the Zmod Base Library, which provides the needed functionality in order to access hardware resources in a consistent manner. No hardware related functionality is implemented on ZMODADC1410 Library.
The ZMODADC1410 Library implementation consists of:

  • a CPP class called ZMODADC1410 Class, derived(inherited) from ZMOD base class. ZMODADC1410 class is implemented in the zmodadc1410.h, zmodadc1410.cpp source files.
  • ZMODADC1410 specific registers and register fields definitions contained in the zmodadc1410.h header file.

2.1. ZMODADC1410 Class Constructor

The ZMODADC1410 class constructor calls the ZMOD base class constructor providing all the required parameters. For these parameters and how they can be obtained by the user, read ZMOD class Constructor / Destructor chapter.
The constructor also calls initCalib calibration initialziation function, providing the ZmodADC1410 unique ID and the length of the ZmodADC1410 calibration area (see Calibration functions of ZMOD class).

ZMODADC1410 class provides functions that implement the analog to digital converter function. Read ZMODADC1410 IP behaviour chapter for details about ZMODADC1410 IP functionality.
The acquisition related functions of ZMODADC1410 class are implemented using basic ZMOD class functionality.

  • The allocChannelsBuffer function allocates acquisition buffer, while the freeChannelsBuffer frees the allocated buffer. For these functions, the length is provided in number of elements in the acquisition buffer (each element has a 4-byte representation).
  • The channelData and signedChannelData functions extract 14-bit data for each channel, from one 32-bit value stored in the acquisition buffer.
  • the setTrigger function sets the trigger values for a specific channel, level, edge and window position.
  • the isBufferFull function reads the “buffer full” status bit.
  • the waitForBufferFullPolling function waits (blocks) until the “buffer full” status bit is set.
  • the enableBufferFullInterrupt function enables / disables the “buffer full” interrupt. Note that “buffer full” interrupt cannot be enabled on Linux.
  • the start and stop functions start and stop the acquisition process. For example, if the acquisition process is started and waiting for a trigger condition, the acquisition process can be stopped, the trigger condition can be modified and the acquisition process resumed.
  • the acquireTriggeredPolling function automates the process by calling some of the previously described functions. Processes:
    • sets the trigger condition details (channel, trigger mode, trigger value, window position)
    • starts the acquisition
    • waits until IP internal buffer is full - the IP status is checked by polling
    • transfers data from the internal buffer over the AXI DMA
  • the acquireImmediatePolling function is similar to the above mentioned function, the difference being that no trigger condition is defined.
  • the autoTestRamp function automates the following process:
    • configures the analog to digital converter into a ramp test mode. In this mode, it generates raising consecutive values in a ramp manner.
    • starts the acquireTriggeredPolling function
    • interprets the acquired data to be consistent with the ramp pattern, trigger condition, window position. It returns the status of this comparison.
  • the setGain function allows setting the gain (LOW / HIGH) corresponding to the values range (HIGH / LOW) for a specific channel.
  • the setCoupling function allows setting the coupling (AC / DC) for a specific channel.
  • the getVoltFromSignedRaw function converts a signed value (as element in the acquisition buffer) to a value in Volts.

The following functions are only defined for Baremetal platform, because the ZMODADC1410 IP Buffer full interrupt is not implemented on Linux:

  • the acquireTriggeredInterrupt function automates the following process:
    • sets the trigger condition details (channel, trigger mode, trigger value, window position)
    • starts the acquisition
    • waits until IP internal buffer is full - the buffer full is checked by waiting for buffer full interrupt;
    • transfers data from the internal buffer over the AXI DMA.
  • the acquireImmediateInterrupt function is similar to the above mentioned function, the difference being that no trigger condition is defined.

The Calibration functions of ZMOD class chapter provides information about all the calibration functionality provided by the base ZMOD class.
The readUserCalib function calls the base class function readUserCalib in order to populate the calibration data, then interprets the calibration data as ZMODADC1410 calibration, computes and sets the ZMODADC1410 IP calibration coefficients.
The ZMODADC1410 class provides setCalibValues function that allows the user to set the calibration pair values (gain, additive) for a specific channel (1, 2) and gain (LOW, HIGH). This function only changes the calibration data image, so in order to actually apply the changes, the writeUserCalib function must be called.

The writeUserCalib function should be used very careful, as it may alter the calibration values. Note that calibration values can be always restored using restoreFactoryCalib function.

2.4. Register Definitions - ZMODADC1410 Specific

As explained in the IP Register access functions of ZMOD class, the ZMOD class provides read/write register and read/write register bit field functions, both in signed and unsigned versions: readReg, writeReg, readRegFld, writeRegFld, readSignedRegFld and writeSignedRegFld.
The registers and register bit fields common to all Zmods are defined in the base class header zmod.h and are prefixed by ZMOD_REG and ZMOD_REGFLD.
The registers and register bit fields specific to ZMODADC1410 are defined in the ZMODADC1410 class header (zmodadc1410.h) and are prefixed by ZMODADC1410_REG and ZMODADC1410_REGFLD.
The following table lists the common and ZMODADC1410 specific register definitions. The ZMODADC1410 specific register definitions are highlighted in green.

Address Register Bit Field
Bit Field name Start bit Length Description
0x00 ZMOD_REG_ADDR_CR ZMOD_REGFLD_CR_CMD_RUNSTP 1 1 CMD_RUNSTP field of CR register
ZMOD_REGFLD_CR_CMD_READ_EN 2 1 CMD_READ_EN field of CR register
ZMOD_REGFLD_CR_INTR_EN 3 1 INTR_EN field of CR register
ZMODADC1410_REGFLD_CR_RUNSTOP 4 1 RUNSTOP field of CR register
ZMODADC1410_REGFLD_CR_TEST_MODE 5 1 TEST_MODE field of CR register
ZMOD_REGFLD_CR_RST 31 1 RST field of CR register
0x04 ZMOD_REG_ADDR_SR ZMOD_REGFLD_SR_TX_DONE 0 1 TX_DONE field of SR register
ZMOD_REGFLD_SR_CMD_RUNNING 2 1 CMD_RUNNING field of SR register
ZMOD_REGFLD_SR_CMD_TX_COUNT 3 7 CMD_TX_COUNT field of SR register
ZMODADC1410_SR_BIT_BUF_FULL 21 1 BUF_FULL field of SR register
0x08 ZMOD_REG_ADDR_IER ZMOD_REGFLD_IER_CMD_TX_DONE 0 1 CMD_TX_DONE field of IER register
ZMOD_REGFLD_IER_CMD_RX_DONE 1 1 CMD_RX_DONE field of IER register
ZMOD_REGFLD_IER_CMD_TX_RX_ERROR 2 4 CMD_TX_RX_ERROR field of IER register
ZMODADC1410_REGFLD_IER_BUF_FULL 21 1 BUF_FULL field of IER register
0x14 ZMOD_REG_ADDR_AXIS_S2MM_LENGTH ZMOD_REGFLD_AXIS_S2MM_LENGTH_LENGTH 0 26 LENGTH field of AXIS_S2MM_LENGTH register
0x18 ZMOD_REG_ADDR_AXIS_MM2S_LENGTH ZMOD_REGFLD_AXIS_MM2S_LENGTH_LENGTH 0 26 LENGTH field of AXIS_MM2S_LENGTH register
0x1C ZMODADC1410_REG_ADDR_TRIG ZMODADC1410_REGFLD_TRIG_CHANNEL 0 2 CHANNEL field of TRIG register
ZMODADC1410_REGFLD_TRIG_MODE 2 2 MODE field of TRIG register
ZMODADC1410_REGFLD_TRIG_EDGE 4 1 EDGE field of TRIG register
ZMODADC1410_REGFLD_TRIG_LEVEL 5 14 LEVEL field of TRIG register
ZMODADC1410_REGFLD_TRIG_SC1_AC_DC 19 1 SC1_AC_DC field of TRIG register
ZMODADC1410_REGFLD_TRIG_SC2_AC_DC 20 1 SC2_AC_DC field of TRIG register
ZMODADC1410_REGFLD_TRIG_SC1_HG_LG 21 1 SC1_HG_LG field of TRIG register
ZMODADC1410_REGFLD_TRIG_SC2_HG_LG 22 1 SC2_HG_LG field of TRIG register
ZMODADC1410_REGFLD_TRIG_SYNC 23 4 SYNC field of TRIG register
0x20 ZMODADC1410_REG_ADDR_WINDOW ZMODADC1410_REGFLD_WINDOW_WND 0 24 WND field of WINDOW register
0x24 ZMODADC1410_REG_ADDR_SC1LGMULTCOEF ZMODADC1410_REGFLD_SC1LGMULTCOEF_VAL 0 18 VAL field of SC1LGMULTCOEF register
0x28 ZMODADC1410_REG_ADDR_SC1HGMULTCOEF ZMODADC1410_REGFLD_SC1HGMULTCOEF_VAL 0 18 VAL field of SC1HGMULTCOEF register
0x2C ZMODADC1410_REG_ADDR_SC1LGADDCOEF ZMODADC1410_REGFLD_SC1LGADDCOEF_VAL 0 18 VAL field of SC1LGADDCOEF register
0x30 ZMODADC1410_REG_ADDR_SC1HGADDCOEF ZMODADC1410_REGFLD_SC1HGADDCOEF_VAL 0 18 VAL field of SC1HGADDCOEF register
0x34 ZMODADC1410_REG_ADDR_SC2LGMULTCOEF ZMODADC1410_REGFLD_SC2LGMULTCOEF_VAL 0 18 VAL field of SC2LGMULTCOEF register
0x38 ZMODADC1410_REG_ADDR_SC2HGMULTCOEF ZMODADC1410_REGFLD_SC2HGMULTCOEF_VAL 0 18 VAL field of SC2HGMULTCOEF register
0x3C ZMODADC1410_REG_ADDR_SC2LGADDCOEF ZMODADC1410_REGFLD_SC2LGADDCOEF_VAL 0 18 VAL field of SC2LGADDCOEF register
0x40 ZMODADC1410_REG_ADDR_SC2HGADDCOEFF ZMODADC1410_REGFLD_SC2HGADDCOEF_VAL 0 18 VAL field of SC2HGADDCOEF register

3. Library Usage

The ZMODADC1410 library is delivered as part of the Zmod libraries pack.
The library usage is similar for all Zmod libraries, and it is explained in the Library usage chapter of Zmod Base Library user guide.

4. Background Knowledge

4.1. ZMODADC1410 IP Behaviour

Basically, the ZMODADC1410 IP (labeled ZMOD_ADC Library block diagram of the Overview section) directly interfaces with the ZmodADC1410 device performing an initial configuration and providing an easy to use interface that the upper level IPs or software can use to transfer data or configuration information to the device. It exposes to the PS a set of command and status registers that the ZmodADC1410 library functions use to control the IP. The ZMODADC1410 Library uses these registers to control the IP and read its status.
Using these registers, the ADC acquisition can be configured, started or stopped. The ADC acquisition is composed of the following steps:

  • ADC output data is captured and decoded. The ZmodADC1410’s ADC multiplexes its 2 channels on one 14-bit wide double data rate (DDR) parallel interface. The ZmodADC1410 IP demultiplexes the input data channel and resynchronizes the received data with its internal clock.

The ZMODADC1410 IP supports two gain range settings: HIGH and LOW. The HIGH input RANGE of the ADC (-25 to +25 V) corresponds to a LOW gain selection in the library functions - using the gain parameter in the setGain() function of the zmodadc1410 library files, while the LOW input RANGE of the ADC (-1V to +1V) corresponds to a HIGH setting value of the gain parameter inside the library mentioned above.
The raw data exported by the ZMODADC1410 should be further analyzed considering the gain parameter setting used for the acquisition.

For more details about the input ranges of the module, consult the ZMODADC1410 Reference Manual

  • Sample data is calibrated by applying calibration coefficients. The ZMODADC1410 IP applies calibration coefficients over the digital values received from Analog to Digital converter, in order to compensate the offset and gain errors introduced by the ADC associated circuitry. For this, the IP provides calibration registers where the calibration coefficients are set. The ZmodADC1410 Library initialization functions available in the library reads the raw values for the gain and offset calibration coefficients from the Zmod’s nonvolatile memory, processes them, and configures the calibration registers.
  • The internal buffer is filled upon detecting a valid trigger condition. The trigger module allows setting the trigger channel, trigger mode, trigger edge, trigger level and window position. The internal buffer has a maximum length of 2^14 - 1 samples and is 32 bits wide, accommodating both ZmodADC1410 channels. The internal buffer length must be set using the IP registers.
  • Buffer data is transferred from the ZMODADC1410 IP internal buffer to system memory through a DMA engine. The ZMODADC1410 IP reports when its internal buffer is full. While the internal buffer is full, no new acquisition is performed. The ZMODADC1410 Library initiates an AXIDMA-S2MM (AXIDMA receive) transfer, transferring data from the ZMODADC1410 IP internal buffer into a memory buffer allocated by ZMODADC1410 Library. The transferred length must be set using the ZmodADC1410 IP registers and the AXI DMA IP registers. The ZMODADC1410 IP can be configured to raise a Buffer Full interrupt, still this interrupt can only be handled by baremetal hardware platform.

For more details on ZmodADC1410 IP interface consult the ZmodADC1410 IP User Guide.
Read more on Parameters chapter below for more details.

4.2. Parameters Set

Term Meaning
channel ADC channels provided by ZmodADC1410:
0 - channel 1
1 - channel 2
trigger level The value specified by the trigger condition
trigger mode The value indicating the trigger mode:
0 - normal
1 - no trigger
trigger edge The value indicating the trigger edge:
0 - rising
1 - falling
internal buffer length The length of the ZmodADC1410 IP internal buffer.
Maximum value = 0x3FFE
transfer length The number of samples to be transferred over AXI DMA.
It has the same value as the internal buffer length.
window position The position in the buffer where trigger condition is met.
Maximum value = internal buffer length.
S2MM Stream to Memory Mapped
The AXI DMA Receive mode
gain The gain setting, corresponding to a Low or High range of values
0 - LOW Gain
1 - HIGH gain
coupling The coupling for ZmodADC1410:
0 - DC Coupling
1 - AC Coupling

5. ADC Demos

  • Download the git repository containing the Demos using the below command:
git clone --recursive https://github.com/Digilent/Eclypse-Z7-SW.git -b zmod_adc/master
Download the ADC Demo files
ZMODADC1410 Demo Files

5.1 Linux Demo

The ADC Linux demo performs (repeatedly) un-triggered acquisitions and writes the data to a file and to the standard output.
The file only contains the content of one acquisition, as it is overwritten. Function called from main is adcDemo(), with the following parameters:

  • channel - the channel where samples were acquired - default is channel 1
  • gain - the gain for the channel - default is high range
  • length - the buffer length to be used - default is set to 400h

This function further calls the writeADCData() function, which formats the data contained in the buffer and writes it to a file and to the standard output - SDK console.
The file is overwritten any time the function is called. It displays the acquired value (in mV), raw value (as 14 bits hexadecimal value) and time stamp within the buffer (in time units) on the UART terminal.
Parameters transmitted from the user further to library functions:

  • filename - the file name to contain the acquisition formatted data
  • acqBuffer - the buffer containing acquired data
  • channel - the channel where samples were acquired
  • gain - the gain for the channel
  • length - the buffer length to be used

The user is able to dynamically change the parameters values of adcDemo() function in order to analyze the module capabilities or use it in further projects. The application is contained in the generic workspace and is suggestively called ZmodADC1410_Demo_Linux. The location and name of the file containing one buffer acquisition is found in the location: /home/eclypse/buffer_data.csv

5.1.1 Functionality

Steps to run the Demo:

  1. Install the demo and libraries files, as indicated in the Environment Setup section of the Base Library User Guide.
  2. Connect the required hardware to the host PC: Eclypse board, Zmod ADC1410, power supply and USB cable. We recommend using a waveforms/signal generator of your choice, together with BNC - SMA adapters, to obtain the analog signal to be converted.
  3. Load the Petalinux image on the SD card and plug it in the SD card slot on the Eclypse board.
  4. Optionally, you can edit the uEnv.txt file on the SD card, prior to plug it in the Eclypse board SD slot: change the configuration to use from zmod=adc-dac to zmod=adc, in order to use the git branch containing only the ADC Demo projects.
  5. Connect the board to a Ethernet network using an Ethernet cable.
  6. Boot the Petalinux using the UART terminal, as instructed in the SD card image download section of the Base Library User Guide.
  7. Run the demo project from within SDK application. Follow the 3.2.1.1.3, 3.2.1.1.4 and 3.2.1.1.5 steps of the Base Library User Guide to setup the environment prior to run the project.
  8. Use the waveform/signal generator to send the ADC a signal to be converted: ex. DC signal of selected amplitude.
  9. Visualize the data acquired in either SDK console or .csv file.
  10. Further use and analyze the data received.

5.2 Baremetal Demo

The ADC Baremetal demo is in fact a simple ADC acquisition and test, performing a un-triggered acquisition. The demo also provides another function that is not called (testZMODADC1410Ramp_Auto) which puts the ADC in the test mode (ramp).
It also verifies the acquired data to be consistent with the conditions specified by the trigger settings. Function called from main is adcDemo(), with the following parameters:

  • channel - the channel where samples will be acquired - default is channel 1
  • gain - the gain for the channel - default is high range
  • length - the buffer length to be used - default is set to 400h

This function further calls the formatADCDataOverUART() function, which formats the data contained in the buffer and sends it over UART.
It displays the acquired value (in mV), raw value (as 14 bits hexadecimal value) and time stamp within the buffer (in time units) on the UART terminal.
Parameters transmitted from the user further to library functions:

  • padcZmod - pointer to the ZMODADC1410 class object
  • acqBuffer - the buffer containing acquired data
  • channel - the channel where samples were acquired
  • gain - the gain for the channel
  • length - the buffer length to be used

The user could change the parameters values of adcDemo() function in order to analyze the module capabilities or use it in further projects. The application is contained in the generic workspace and is suggestively called ZmodADC1410_Demo_Baremetal

5.2.1 Functionality

Steps to run the Demo:

  1. Install the demo and libraries files, as indicated in the Environment Setup section of the Base Library User Guide.
  2. Connect the required hardware to the host PC: Eclypse board, Zmod ADC1410, power supply and USB cable. We recommend using a waveforms/signal generator of your choice, together with BNC - SMA adapters, to obtain the analog signal to be converted.
  3. Run the demo project from within SDK application.
  4. Start the selected waveform/signal generator and select a DC signal of certain set amplitude.
  5. Open the PC UART terminal and visualize the data acquired: Sample value, Raw value and Time stamp.
  6. Further use and analyze the data received.