====== ZmodDAC1411 Library User Guide ======
===== 1. Overview =====
Digilent provides the ZmodDAC1411 Library used to access [[https://digilent.com/shop/zmod-awg-1411-2-channel-14-bit-arbitrary-waveform-generator-awg-module/|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:zmodbaselibraryuserguide|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.
{{ :reference:programmable-logic:eclypse-z7:zmod_dev-board_structure_-_dac.png}}
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|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:zmodbaselibraryuserguide#zmod_class|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:zmodbaselibraryuserguide#zmod_class_constructordestructor|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 [[zmod:zmodbaselibraryuserguide#calibration_functions_of_zmod_class|Calibration functions of ZMOD class]]).
===== 2.2. DAC Signal Generation Related Functions of ZMODDAC1411 Class =====
ZMODDAC1411 class provides functions that implement the digital to analog converter function.
Read [[#zmoddac1411_ip_behaviour|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.
===== 2.3. Calibration Related Functions of ZMODDAC1411 Class =====
The [[/zmod/zmodbaselibraryuserguide#calibration_functions_of_zmod_class|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 [[zmod:zmodbaselibraryuserguide#ip_register_access_functions_of_zmod_class|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 [[zmod:zmodbaselibraryuserguide#library_usage|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 [[zmod:awg:reference-manual|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 [[https://github.com/Digilent/vivado-library/blob/zmod/v1/2019.1-2/ip/Zmods/AXI_Zmod_DAC1411/doc/ZmodDAC1411AxiAdapter.pdf|ZMODDAC1411 IP User Guide]].\\
Read more on [[#parameters_set|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 |**M**emory **Ma**pped to **S**tream\\ 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 ^
| @#22b14c:[[https://github.com/Digilent/Eclypse-Z7-SW/tree/zmod_dac/master|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:
- Install the demo and libraries files, as indicated in the [[/zmod/zmodbaselibraryuserguide#environment_setup|Environment Setup]] section of the Base Library User Guide.
- 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.
- Load the Petalinux image on the SD card and plug it in the SD card slot on the Eclypse board
- 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.
- Boot the Petalinux using the UART terminal
- Run the demo project from within SDK application
- Connect the scope to the ZmodDAC channel 1
- Visualize the data acquired on the Scope screen
- 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:
- Install the demo and libraries files, as indicated in the [[/zmod/zmodbaselibraryuserguide#environment_setup|Environment Setup]] section of the Base Library User Guide.
- 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.
- Run the demo project from within SDK application
- Start the Scope with the Channel1 of the ZmodDAC1411 connected to it and visualize the signal generated by the DAC.
- Further use and analyze the data received
----