ZmodDAC1411 Library User Guide

1. Overview

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

The ZmodDAC1411 and Zmod Base Library run on the Zynq PS (processing system).
A ZmodDAC1411 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 associated one particular instance of AXI DMA IP core.
Basically:

  • The ZMODDAC1411 IP (labeled ZMOD_DAC in the above image) features an internal buffer.
  • The AXI DMA transmit (Memory Mapped to Stream) is initiated in the ZMODDAC1411 Library, sending the data from a memory buffer allocated by ZMODDAC1411 Library to the ZmodDAC1411 IP internal buffer.
  • The ZMODDAC1411 IP outputs the values from internal buffer to the DAC which generates the analog values. This is done in a repetitive manner.

Read more on ZMODDAC1411 IP behaviour.

2. ZMODDAC1411 Library Implementation Details

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

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

2.1. ZMODDAC1411 Class Constructor

The ZMODDAC1411 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 initialization function, providing the ZmodDAC1411 unique ID and the length of the calibration area (see Calibration functions of ZMOD class).

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

  • The allocChannelsBuffer function allocates data 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 arrangeChannelData and arrangeSignedChannelData functions place the 14-bit data corresponding to a specific channel in the 32-bit buffer value.
  • the setData function transfers the specified length of data from the specified buffer to the internal IP buffer. It automates the following process:
    • sets the AXI DMA transfer length
    • starts the AXI DMA transfer: transmit values from the specified buffer to the IP internal buffer
    • waits until AXI DMA transfer is completed
  • the resetOutputCounter function resets the counter used by DAC generate process.
  • the start and stop functions start and stop the DAC generate process.
  • the setOutputSampleFrequencyDivider function sets the Output Sample Frequency Divider. This is used by IP to implement lower output sample rate, by repeating each sample from buffer multiple times.
  • the setGain function allows setting the gain (LOW / HIGH) corresponding to the values range (LOW/ HIGH) for a specific channel.

The Calibration functions of ZMOD class chapter provides information about all the calibration functionality provided by the base ZMOD class.
The following functions are provided by the ZMODDAC1411 class in order to implement calibration functionality specific to ZmodDAC1411: The readUserCalib function calls the base class function readUserCalib in order to populate the calibration data, then interprets the calibration data as ZMODDAC1411 calibration, computes and sets the ZMODDAC1411 IP calibration coefficients.
The setCalibValues function allows the user to set the pair of calibration 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 - ZMODDAC1411 Specific

As explained in IP Register access functions of ZMOD class, the ZMOD class provides read/write register and read/write register bit field functions are provided, 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 ZMODDAC1411 are defined in the ZMODDAC1411 class header (zmoddac1411.h) and are prefixed by ZMODDAC1411_REG and ZMODDAC1411_REGFLD.
The following table lists the common and ZMODDAC1411 specific register definitions. The ZMODDAC1411 specific register definitions are highlighted in blue.

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
ZMODDAC1411_REGFLD_CR_DAC_EN 4 1 DAC_EN field of CR register
ZMODDAC1411_REGFLD_CR_TEST_MODE 5 1 TEST_MODE field of CR register
ZMODDAC1411_REGFLD_CR_OUT_ADDR_CNT_RST 6 1 OUT_ADDR_CNT_RST field of CR register
ZMODDAC1411_REGFLD_CR_DIV_RATE 16 14 DIV_RATE 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
ZMODDAC1411_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
ZMODDAC1411_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 ZMODDAC1411_REG_ADDR_TRIG ZMODDAC1411_REGFLD_TRIG_SC1_AC_DC 19 1 SC1_AC_DC field of TRIG register
ZMODDAC1411_REGFLD_TRIG_SC2_AC_DC 20 1 SC2_AC_DC field of TRIG register
0x24 ZMODDAC1411_REG_ADDR_SC1LGMULTCOEF ZMODDAC1411_REGFLD_SC1LGMULTCOEF_VAL 0 18 VAL field of SC1LGMULTCOEF register
0x28 ZMODDAC1411_REG_ADDR_SC1HGMULTCOEF ZMODDAC1411_REGFLD_SC1HGMULTCOEF_VAL 0 18 VAL field of SC1HGMULTCOEF register
0x2C ZMODDAC1411_REG_ADDR_SC1LGADDCOEF ZMODDAC1411_REGFLD_SC1LGADDCOEF_VAL 0 18 VAL field of SC1LGADDCOEF register
0x30 ZMODDAC1411_REG_ADDR_SC1HGADDCOEF ZMODDAC1411_REGFLD_SC1HGADDCOEF_VAL 0 18 VAL field of SC1HGADDCOEF register
0x34 ZMODDAC1411_REG_ADDR_SC2LGMULTCOEF ZMODDAC1411_REGFLD_SC2LGMULTCOEF_VAL 0 18 VAL field of SC2LGMULTCOEF register
0x38 ZMODDAC1411_REG_ADDR_SC2HGMULTCOEF ZMODDAC1411_REGFLD_SC2HGMULTCOEF_VAL 0 18 VAL field of SC2HGMULTCOEF register
0x3C ZMODDAC1411_REG_ADDR_SC2LGADDCOEF ZMODDAC1411_REGFLD_SC2LGADDCOEF_VAL 0 18 VAL field of SC2LGADDCOEF register
0x40 ZMODDAC1411_REG_ADDR_SC2HGADDCOEFF ZMODDAC1411_REGFLD_SC2HGADDCOEF_VAL 0 18 VAL field of SC2HGADDCOEF register

3. Library Usage

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

4. Background Knowledge

4.1. ZMODDAC1411 IP Behaviour

The ZmodDAC1411 IP directly interfaces with the ZmodDAC1411 device performing an initial configuration and providing an easy to use interface that the upper level IPs or the PS can use to transfer data or configuration information. This interface is composed of control and status registers that the library functions can access for configuration purposes and a stream channel that can be connected to a DMA engine for high bandwidth data transfers.
The intended use case of this IP is to load a predefined number of samples in its internal buffer, calibrate them and pass them to the ZmodDAC1411 for digital to analog conversion. This sequence is defined as the “generate process”. The output buffer is addressed by a counter that resets to 0 when it reaches the buffer length programmed by software. The internal buffer length is set through the IP registers. The output address counter resets after the last buffer sample, implementing a repeated generate process of values from the buffer.
The internal buffer has a maximum length of 0x3FFE (2^14 - 1) samples and is 32-bit wide, accommodating both ZMODDAC1411 channels. The internal buffer length is set through the IP registers.
When the generate process is stopped, the output address counter maintains its value, meaning that when the generate process is resumed the samples sequence will follow the last generated ones. The output address counter can be reset, meaning that next time when the generate process is resumed the samples sequence will start with the first sample in the buffer.
Before starting the DAC generate process, the ZMODDAC1411 Library transfer functions populate the internal buffer. For this, the ZMODDAC1411 Library initiates an AXIDMA-MM2S (AXIDMA transmit) transfer, transferring data from a memory buffer allocated by ZMODDAC1411 Library in the system memory.
The ZmodDAC1411 IP supports two gain range settings: HIGH and LOW. The HIGH output RANGE of the DAC (-5 to +5 V) corresponds to a HIGH gain selection in the setGain() function of the zmoddac1411 library, while the LOW output RANGE of the DAC(-1.25V to +1.25V) corresponds to a LOW gain setting value of the gain parameter. For more details about the output ranges of the module, consult the ZMODDAC1411 Reference Manual
The ZMODDAC1411 IP implements a calibration block that eliminates the offset and gain errors introduced by hardware. The raw calibration coefficients are stored in the ZmodDAC1411’s nonvolatile memory (flash). The ZmodDAC1411 library initialization functions read the raw values of the gain and offset calibration coefficients from the Zmod’s nonvolatile memory, processes them, and configure the calibration registers. The calibration registers further control the calibration block in the IP’s data path. By default, the IP’s buffer output address counter runs at 100MHz corresponding to a sample rate of 100MSPS on both channels. The default sample rate can be divided by programming the Output Sample Frequency Divider IP setting.
For more details on ZmodDAC1411 IP interface read ZMODDAC1411 IP User Guide.
Read more on Parameters chapter for more details.

4.2. Parameters set

Term Meaning
channel DAC channels provided by ZmodDAC1411:
0 - channel 1
1 - channel 2
internal buffer length The length of the ZmodDAC1411 IP internal buffer.
Maximum value = 0x3FFE
MM2S Memory Mapped to Stream
The AXI DMA Transmit mode
transfer length The number of samples to be transferred over AXI DMA.
It has the same value as the internal buffer length.
coupling The coupling for ZmodDAC1411:
0 - DC Coupling
1 - AC Coupling

5. Library Demos

  • Download the git repository containing the libraries and demos using the below command:
git clone --recursive https://github.com/Digilent/Eclypse-Z7-SW.git -b zmod_dac/master
Download the DAC Demo files
ZMODDAC1411 Demo Files

5.1 Linux Demo

The DAC Linux demo performs a simple DAC test, using simple ramp values populated in the buffer
Function called from main is dacRampDemo(), with the following parameters:

  • offset - the voltage offset for the generated ramp - default is 2V
  • amplitude - the amplitude for the generated ramp - default is 3V
  • step - the step between two generated samples - default is 10mV
  • channel - the channel where samples were acquired - default is channel 1
  • frequencyDivider - the output frequency divider - default is 2
  • gain - the gain for the channel - default is high range

This function further calls specific ZmodDAC library functions, which prepare the data to be sent to DAC module, send it and start the module
The generated signal will be a 2V offset, 3V amplitude Ramp.

The user is able to dynamically change the parameters values of dacRampDemo() 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 ZmodDAC1411_Demo_Linux.

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 DAC1411, power supply and USB cable. We recommend using a Scope instrument of your choice, together with BNC - SMA adapters, to visualize the analog signal generated by the DAC.
  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=dac, in order to use the git branch containing only the DAC Demo projects.
  5. Boot the Petalinux using the UART terminal
  6. Run the demo project from within SDK application
  7. Connect the scope to the ZmodDAC channel 1
  8. Visualize the data acquired on the Scope screen
  9. Further use and analyze the data received

5.2 Baremetal Demo

ZmodDAC1411 Baremetal Demo is functionally identical with the Linux demo. The DAC Baremetal demo performs a simple DAC test, using simple ramp values populated in the buffer
Function called from main is dacRampDemo(), with the following parameters:

  • offset - the voltage offset for the generated ramp - default is 2V
  • amplitude - the amplitude for the generated ramp - default is 3V
  • step - the step between two generated samples - default is 10mV
  • channel - the channel where samples were acquired - default is channel 1
  • frequencyDivider - the output frequency divider - default is 2
  • gain - the gain for the channel - default is high range

This function further calls specific ZmodDAC library functions, which prepare the data to be sent to DAC module, send it and start the module
The generated signal will be a 2V offset, 3V amplitude Ramp.

The user could change the parameters values of dacRampDemo() 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 ZmodDAC1411_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 DAC1411, power supply and USB cable. We recommend using a Scope instrument of your choice, together with BNC - SMA adapters, to visualize the analog signal generated by the DAC.
  3. Run the demo project from within SDK application
  4. Start the Scope with the Channel1 of the ZmodDAC1411 connected to it and visualize the signal generated by the DAC.
  5. Further use and analyze the data received