Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
reference:zmod:zmodbaselibraryuserguide [2020/01/16 14:09]
Ana-Maria-Eliza Balas [2.2.2. Linux project demonstration]
reference:zmod:zmodbaselibraryuserguide [2020/07/09 15:07] (current)
William Wadkins [3.1. Delivery Structure]
Line 4: Line 4:
 Digilent provides a set of libraries supporting Zmod modules on both Linux and baremetal (standalone) platforms.\\ ​ Digilent provides a set of libraries supporting Zmod modules on both Linux and baremetal (standalone) platforms.\\ ​
 The Zmod Base Library implements functionality common to all Zmods. For each Zmod, separate libraries are implemented,​ based on Zmod Base Library. \\  The Zmod Base Library implements functionality common to all Zmods. For each Zmod, separate libraries are implemented,​ based on Zmod Base Library. \\ 
-This document describes the Zmod Base Library structure and also addresses issues common to all Zmods (like the [[#​project_settings|Project Settings]]).\\  +This document describes the Zmod Base Library structure and also addresses issues common to all Zmods.\\  
-These instructions / demos are provided for the Zmods attached to an Eclypse board, still Zmods can be attached to any Zynq board providing the SYZYGY connector.\\ ​+These instructions / demos are provided for the Zmods attached to an Eclypse board, still Zmods can be attached to any Zynq board having a SYZYGY connector.\\ ​ 
 + 
 +The following block diagram shows the overall structure of Zmod Libraries.
  
-The following picture shows the overall structure of Zmod Libraries. 
 {{ :​reference:​programmable-logic:​eclypse-z7:​zmod_dev-board_structure_-_generic.png}} {{ :​reference:​programmable-logic:​eclypse-z7:​zmod_dev-board_structure_-_generic.png}}
  
Line 14: Line 15:
 In the Zynq PL (FPGA) there is an IP core specific to each Zmod. This IP core can be accessed from the Zynq PS through its registers. The IP core is able to communicate with the memory over the AXI DMA data bus. Each Zmod has associated one particular instance of AXI DMA IP core.\\ ​ In the Zynq PL (FPGA) there is an IP core specific to each Zmod. This IP core can be accessed from the Zynq PS through its registers. The IP core is able to communicate with the memory over the AXI DMA data bus. Each Zmod has associated one particular instance of AXI DMA IP core.\\ ​
 Communication over the AXI DMA is mastered by the Zmod libraries.\\ ​ Communication over the AXI DMA is mastered by the Zmod libraries.\\ ​
-The Zmod libraries contain two layers. The base layer is called Zmod Base Library and is the subject of this manual. It mainly deals with the functionality common to all Zmods and provides the platform abstraction layer, ensuring consistent implementation for the two supported platforms (Linux, ​baremetal), hiding under it all the platform related functionality.\\  +The Zmod libraries contain two layers. The base layer is called Zmod Base Library and is described under this page. It mainly deals with the functionality common to all Zmods and provides the platform abstraction layer, ensuring consistent implementation for the two supported platforms (Linux, ​Baremetal), hiding under it all the platform related functionality.\\  
-On the higher level there is a library specific to each Zmod. It relies ​on Zmod Base library and implements only the Zmod specific functionality and definitions.\\ ​+On the higher level there is a Zmod specific library. It is based on the Zmod Base library and implements only the Zmod specific functionality and definitions.\\ ​
 The Zmod Libraries ensure the following objectives are met:​\\ ​ The Zmod Libraries ensure the following objectives are met:​\\ ​
-  * Provide a consistent API to +  * Provide a consistent API to
     * different Zmods     * different Zmods
-    * different software platforms: Linux and baremetal, by implementing a platform abstraction layer at Zmod Base Library level +    * different software platforms: Linux and Baremetal, by implementing a platform abstraction layer at Zmod Base Library level
   * Implement at Zmod Base Library level all the functionality needed by Zmods:   * Implement at Zmod Base Library level all the functionality needed by Zmods:
-    * AXI DMA (see [[#​axi_dma_related_functionality|AXI DMA Related Functionality]]) +    * AXI DMA  
-    * Flash (see [[#​flash_related_functionality|Flash Related Functionality]]) +    * Flash  
-    * Communication with IP cores specific to each particular Zmod (see [[#ip_core_related_functionality|IP Core Related Functionality]])\\  +    * Communication with IP cores specific to each particular Zmod \\  
-The Zmod Base Library implementation consists of a CPP class called [[#​zmod_class|ZMOD Class]] which is the base class for inherited classes used for each particular Zmod.\\ Also, the Zmod Base Library implementation contains two separate folders: Linux and baremetalThey implement ​the [[#platform_abstraction_layer|Platform Abstraction Layer]]. + 
-\\ +The above mentioned topics are detailed and described in the next section ​[[#implementation_details|Implementation Details]].\\ 
 +The Zmod Base Library implementation consists of a C++ class called [[#​zmod_class|ZMOD Class]] which is the base class for inherited classes used for each particular Zmod.\\ Also, the Zmod Base Library implementation contains two separate folders: Linux and Baremetal. 
 + 
 + 
 +Consult ​the table in the right in order to proceed to the **Environment Setup** section. \\ 
 +Download the git files indicated below in order to access the Projects Files and Demos for the two Zmods: ADC1410 and DAC1411, together with the Base library files. 
 + 
 +<WRAP GROUP> <WRAP COLUMN HALF> 
 +Download source files: 
 +^ Library and Demo files                                                                ^  ZmodADC1410 Demo Files                                                                       ^ DAC1411 Demo Files                                                                            ^ 
 +| @#DECADE:[[https://​github.com/​Digilent/​Eclypse-Z7-SW/​tree/​zmod_adc_dac/​master|Base Zmod Library]] ​ | @#0000FF:​[[https://​github.com/​Digilent/​Eclypse-Z7-SW/​tree/​zmod_adc/​master|ZMODADC1410 Demo]]  | @#​22b14c:​[[https://​github.com/​Digilent/​Eclypse-Z7-SW/​tree/​zmod_dac/​master|ZMODDAC1411 Demo]] ​ | 
 + 
 + 
 +</​WRAP>​ <WRAP COLUMN HALF> 
 +Shortcut to Projects Setup section: 
 +^  Linux ^  Baremetal^ ​               
 +|  @#​95B9AF:​[[https://​reference.digilentinc.com/​reference/​zmod/​zmodbaselibraryuserguide#​linux_environment_project_setup|ADC/​DAC Import Project Linux]] | @#​C0EEBD:​[[https://​reference.digilentinc.com/​reference/​zmod/​zmodbaselibraryuserguide#​baremetal_project_setup|ADC/​DAC Import Project Baremetal]] ​      | 
 +|   ​@#​95B9AF:​[[https://​reference.digilentinc.com/​reference/​zmod/​zmodbaselibraryuserguide#​linux_environment_project_setup1|ADC/​DAC Create Project ​ Linux]] | @#​C0EEBD:​[[https://​reference.digilentinc.com/​reference/​zmod/​zmodbaselibraryuserguide#​baremetal_project_setup1|ADC/​DAC Create Project Baremetal]] ​      | 
 +</​WRAP>​ </​WRAP>​  
 + 
 +Clone the git repository containing the libraries and demos using the below command: 
 +<​code>​git clone --recursive https://​github.com/​Digilent/​Eclypse-Z7-SW.git -b zmod_adc_dac/​master</​code>​ 
 + 
 +Similar command for the Zmod specific demos
 For details on the Zmod specific libraries see the following documents: For details on the Zmod specific libraries see the following documents:
   * [[:​reference:​zmod:​zmodadc:​zmodadc1410libraryuserguide|]] ​   * [[:​reference:​zmod:​zmodadc:​zmodadc1410libraryuserguide|]] ​
   * [[:​reference:​zmod:​zmoddac:​zmoddac1411libraryuserguide|]]   * [[:​reference:​zmod:​zmoddac:​zmoddac1411libraryuserguide|]]
 +
 +For details on the Zmod API, see the following document:
 +  * [[https://​digilent.s3-us-west-2.amazonaws.com/​Software/​Zmod_Documentation/​v2019.1-1/​index.html|Zmod Library API Documentation]]
  
 ---- ----
-====== 2. Library Usage ====== +====== 2. Implementation Details ​====== 
-===== 2.1. Delivery Structure ​===== +===== 2.1. Platform Abstraction Layer ===== 
-The base library and demos are delivered as a 2019.1 Xilinx Vivado SDK workspace and are included in the following location: +The  [[#​zmod_class|ZMOD Class]] ​calls Zmod IP Cores related functionalityAXI DMA related functionality and Flash related functionality which are implemented differently on Linux and BaremetalThe platform abstraction layer provides a common API for both platforms.\\ ​ 
-  * [[https://​github.com/​Digilent/​Eclypse-Z7-SW/​tree/​zmod_adc_dac/​master|Base Zmod library]] +The Zmod folder contains these header files: reg.h, dma.h and flash.h ​which contain declarations for the platform dependent functions corresponding to IP Core registersAXI DMA and Flash. The functions ​prototypes ​are common for both platforms while their implementation resides in the Baremetal and Linux folders.\\  
-    * **zmodlib** folder containing:​ +The project level definition LINUX_APP ensures each function is implemented ​exactly once (all the Linux platform projects must define LINUX_APP).\\  
-      * [[#​zmod_class|ZMOD ​Base Class]] ​sources: zmod.cppzmod.h +Under the Linux and Baremetal ​folders ​there is a separate ​folder for each interface: reg, dma, flash, and intc (for Baremetal only).\\ For more details, read  the functionality ​described below in this section.\\  
-      * Platform dependencies common includes: reg.h, dma.h and flash.h. These headers expose ​the IP core register access, DMA and flash  ​functions ​that are dependent to the platform (Linux or baremetal)These functions will be implemented ​in the source files contained in the platform dependencies folders ​(Linux ​and baremetalshown below+ 
-      * Platform dependencies ​folders+==== 2.1.1. IP Core Related Functionality ==== 
-        * linux - contains ​separate ​folders that implement Linux platform related functionality ​(functions listed in platform dependencies common includes mentioned aboveon Linux platform +The IP core related functionality provides access to the registers of the IP core corresponding to a particular Zmod.\\  
-        * baremetal - contains separate folders that implement baremetal related ​functionality ​(functions listed ​in platform dependencies common includes mentioned above) on baremetal platform.  +This functionality allows
-    * For each Zmod, the folder containing its libraryFor example:  +  Initialization/​de-initialization of the IP core 
-      Folder ZmodADC1410 contains: +  Reading and writing Zmod registers
-        ZmodADC1410 sources: zmodadc1410.cpp,​ zmodadc1410.h +  Initialization and handling of the interrupts addressed by Zmod interrupt controller (only for Baremetal platform) 
-      Folder ZmodDAC1411 contains: +This functionality is platform dependentas explained in the [[#​platform_abstraction_layer|Platform Abstraction Layer]].\\  
-        * ZmodADC1411 sources: zmoddac1411.cppzmoddac1411.h +The prototype ​of these functions is placed ​in the Zmod/reg.file and is common to both Linux and Baremetal ​platforms. The implementation of these functions is in Zmod/​linux/​reg.c and Zmod/​baremetal/​reg.c respectively,​ exclusively depending on the project level definition LINUX_APP.\\  
-  * [[https://​github.com/​Digilent/​Eclypse-Z7-SW/​tree/​zmod_adc_dac/​master|Zmod ADC demo]] +<WRAP center round box 95%> 
-    * Folder ZmodADC1410_Demo_Linux contains the Linux demo project. Under src folder there are the following linked folders: +The Linux implementation uses UIO mapping to access ​the IP registers
-      * Folder **zmodlib** links to WORKSPACE_LOC\zmodlib.\\ The structure ​of **zmodlib** was detailed ​in the above paragraphs. +</​WRAP>​ 
-      * A main file implementing the Linux demo +<WRAP center round box 95%> 
-    * Folder ZmodADC1410_Demo_Baremetal contains the Baremetal ​projectUnder src folder there are the following linked folders: +The Baremetal implementation uses Xil_Out32 and Xil_In32 ​to access ​the IP registers.\\ ​ 
-      * Folder **zmodlib** links to WORKSPACE_LOC\zmodlib.\\ The structure of **zmodlib** was detailed in the above paragraphs+The Baremetal uses the Xilinx interrupt controller XIntc. The interrupt related implementation is implemented in Zmod/intc folder
-      * A main file, specific ​to the baremetal app +</WRAP> 
-    * One folder ZmodADC1410_Demo_Baremetal_bsp corresponding to the Baremetal project bsp+The initialization function takes the //IP base address// and the //IP interrupt number// as parameters. 
-  * [[https://github.com/Digilent/Eclypse-Z7-SW/tree/zmod_adc_dac/master|Zmod DAC demo]] +<WRAP center round box 95%> 
-    * Folder ZmodDAC1411_Demo_Linux contains the Linux demo project. Under src folder there are the following linked folders: +On Linuxthe IP base address is stored in /​sys/​class/​uio/​uio<​uio number>/​maps/​map<​map number>/​addr file. The <uio number> and <map number> are usually '​0'​. For Linux the IP core interrupt is not implemented,​ so -1 is used
-      * Folder **zmodlib** links to WORKSPACE_LOC\zmodlib.\\ The structure of **zmodlib** was detailed in the above paragraphs+</​WRAP>​ 
-      * A main file implementing the Linux demo +<WRAP center round box 95%> 
-    * Folder ZmodDAC1411_Demo_Baremetal contains ​the Baremetal project. Under src folder there are the following linked folders: +For baremetal, ​the //IP base address// and the //IP interrupt number// are specified in xparameters.h (in the bsp include files)For exampleXPAR_AXI_ZMODADC1410_0_S00_AXI_BASEADDR and XPAR_FABRIC_AXI_ZMODADC1410_0_IRQ_OUT_INTR.\\ ​ 
-      * Folder **zmodlib** links to WORKSPACE_LOC\zmodlib.\\ The structure of **zmodlib** was detailed ​in the above paragraphs. +</​WRAP>​ 
-      * A main filespecific to the baremetal app +The IP core related functionality is mainly called from [[#​ip__cores_register_access_functions_of_zmod_class|IP Cores Register Access Functions of ZMOD Class]]
-    * One folder ZmodDAC1411_Demo_Baremetal_bsp corresponding to the Baremetal project bsp.+
  
 ---- ----
 +==== 2.1.2. AXI DMA Related Functionality ====
 +The AXI DMA related functionality provides the ability to transfer data over AXI DMA.\\ ​
 +The functionality allows:
 +  * Initialization/​de-initialization of the AXI DMA module.
 +  * To allocate/​free the buffer used for data transfer.
 +  * To initiate one way AXI DMA transfers.
 +  * To inform when a transfer is complete.
 +This functionality is platform dependent, as explained in the [[#​platform_abstraction_layer|Platform Abstraction Layer]].\\ ​
 +The prototype of these functions is placed in the Zmod/dma.h file and is common to both Linux and baremetal platforms. The implementation of these functions is in Zmod/​linux/​dma.c and Zmod/​baremetal/​dma.c respectively,​ exclusively depending on the project level definition LINUX_APP.
 +<WRAP center round box 95%>
 +The Linux implementation uses libaxidma devices for each AXIDMA instance.
 +</​WRAP>​
 +<WRAP center round box 95%>
 +The Baremetal implementation uses the XAxiDma driver for each AXIDMA instance.
 +</​WRAP>​
 +The initialization function takes the //AXI DMA base address// and the //AXI DMA interrupt number// as parameters.
 +<WRAP center round box 95%>
 +For Linux, the //AXI DMA base address// can be found in the /​sys/​class/​uio/​uio<​uio number>/​maps/​map<​map number>/​addr file. The <uio number> and <map number> are usually '​0'​.\\ ​
 +The //AXI DMA interrupt// is implemented inside libaxidma, so -1 value can be provided for the AXI DMA interrupt number.
 +</​WRAP>​
 +<WRAP center round box 95%>
 +For Baremetal, the //AXI DMA base address// and the //AXI DMA interrupt number// are specified in xparameters.h file (in the bsp include files). For example XPAR_AXI_DMA_0_BASEADDR and XPAR_FABRIC_AXI_DMA_0_S2MM_INTROUT_INTR.
 +</​WRAP>​
 +The Zmod implementation uses one way AXI DMA transfers (S2MM or MM2S), so the transfer direction is set in the initialization function.\\ ​
 +The AXI DMA related functionality is mainly called from [[#​axi_dma_transfer_functions_of_zmod_class|AXI DMA Transfer Functions of ZMOD Class]].
  
-===== 2.2Environment Setup =====+---- 
 +==== 2.1.3. Flash Related Functionality ​==== 
 +The Flash related functionality provides access to the persistent memory (flash) placed on each Zmod. These functions handle calibration values.\\  
 +Their functionality allows: 
 +  * Flash module initialization/​de-initialization  
 +  * To read/write blocks of data from/to a specified address in flash. 
 +This functionality is platform dependent, as explained in the [[#​platform_abstraction_layer|Platform Abstraction Layer]].\\  
 +The prototype of these functions is placed in the Zmod/​flash.h file and is common to both Linux and Baremetal platforms. The implementation of these functions is in the Zmod/​linux/​flash.c and Zmod/​baremetal/​flash.c respectively,​ exclusively depending on the project level definition LINUX_APP. 
 +<WRAP center round box 95%> 
 +The Linux implementation uses /dev/i2c-0 device. 
 +</​WRAP>​ 
 +<WRAP center round box 95%> 
 +The Baremetal implementation uses XIicPs driver. 
 +</​WRAP>​ 
 +The initialization function takes the //Flash base address// as a parameter. 
 +<WRAP center round box 95%> 
 +For Linux, the //Flash base address// can be found in the /​sys/​bus/​i2c/​devices/​i2c-<​i2c number>/​name file by parsing its content for the address. The <i2c number> is usually '​0'​. For example, the content of /​sys/​bus/​i2c/​devices/​i2c-0/​name is "​Cadence I2C at e0005000",​ e0005000 being the needed Flash base address.  
 +</​WRAP>​ 
 +<WRAP center round box 95%> 
 +For Baremetal //Flash base address// is specified in xparameters.h (in the bsp include files). For example XPAR_PS7_I2C_1_BASEADDR. 
 +</​WRAP>​ 
 +The initialization function also requires the //address of slave I2C device// corresponding to the Zmod connector.\\ 
 +For Eclypse, the addresses of slave I2C devices are: 0x30 (corresponding to ZMOD A connector) and 0x31 (corresponding to ZMOD B connector). 
 +The Flash related functionality is mainly called from [[#​calibration_functions_of_zmod_class|Calibrations Functions of ZMOD Class]].
  
-This section contains ​the steps for setting the environment ​for [[#baremetal_project_demonstration ​Baremetal project demonstration]] and [[#linux_project_demonstration ​Linux project demonstration]] for both Zmod ADC and Zmod DAC.+---- 
 +===== 2.2 ZMOD Class ===== 
 +This is the base class for individual Zmod classes (for example ZMODADC1410 class or ZMODDAC1411 class). It implements the functionality common to all Zmods and all the functionality needed to access hardware resources, abstracting these details from the derived classes. 
 +It implements the following function members: 
 +  * [[##​zmod_class_constructordestructor|ZMOD Class Constructor / Destructor]]
 +  * [[#ip_cores_register_access_functions_of_zmod_class|IP Cores Register Access Functions of ZMOD Class]].  
 +  * [[#​axi_dma_transfer_functions_of_zmod_class|AXI DMA Transfer Functions of ZMOD Class]].  
 +  * [[#​calibration_functions_of_zmod_class|Calibrations Functions of ZMOD Class]].
  
-==== 2.2.1. ​Baremetal project demonstration ​==== +==== 2.2.1. ​ZMOD Class Constructor / Destructor ​==== 
-<WRAP GROUP> <WRAP COLUMN HALF> +The //ZMOD class constructor//​ initializes the hardware interfaces. It takes the following parameters: 
-=== 2.2.1.1Download ​the library ===+  * //IP core base address// and //IP core interrupt number//\\ See [[#​ip_core_related_functionality|Zmod IP Cores Related Functionality]] for how these values can be identified. 
 +  * //AXI DMA base address// and //AXI DMA interrupt number//\\ See [[#​axi_dma_related_functionality|AXI DMA Related Functionality]] for how these values can be identified. 
 +  * I2C address and Flash address\\ See [[#​flash_related_functionality|Flash Related Functionality]] for how these values can be identified. 
 +The //ZMOD class destructor//​ calls the destroy functions for the hardware interfaces, also freeing the dynamically allocated calibration data.
  
 +----
 +==== 2.2.2. IP Cores Register Access Functions of ZMOD Class ====
 +The ZMOD class provides initialization of the IP core related module, and access to IP core registers.\\ ​
 +To access IP core related functionality,​ the ZMOD class calls functions from the platform abstraction layer (see [[#​ip_core_related_functionality|IP Core Related Functionality]]).\\ ​
 +Thus read/write register and read/write register field functions are provided, both in signed and unsigned versions: //​readReg//,​ //​writeReg//,​ //​readRegFld//,​ //​writeRegFld//,​ //​readSignedRegFld//​ and //​writeSignedRegFld//​.\\ ​
 +A //​register'​s bit field// designates a number of contiguous bits inside an IP core register and is defined as a triplet of IP core register address, start bit, and end bit. Some register'​s bit fields can be common to all ZMODS (defined in the base class header file zmod.h) or specific to an individual Zmod (defined in the specific library header file, ZMODADC1410/​zmodadc1410.h for example). The register'​s bit fields definitions can be found on each specific Zmod library user guide.\\ ​
 +The ZMOD class also provides functions that allow sending and receiving commands to / from the chip on the specific ZMOD (for example sending commands to the ADC device on the ZmodADC1410 or to the DAC device on the ZmodDAC1411):​ //​sendCommand//​ and //​receiveCommand//​ functions.\\ ​
  
-  * Download ​the project demo with the below command:+---- 
 +==== 2.2.3. AXI DMA Transfer Functions of ZMOD Class ==== 
 +To access AXI DMA related functionality,​ the ZMOD class calls functions from the platform abstraction layer (see [[#​axi_dma_related_functionality|AXI DMA Related Functionality]]).\\  
 +The ZMOD class provides initialization and one way AXI DMA transfer functions.\\  
 +Also, ZMOD class provides data buffer allocation / de-allocation functions: //​allocDMABuffer//​ and //​freeDMABuffer//​.\\  
 +The //​setTransferSize//​ function allows setting the AXI DMA transfer size (in  bytes).\\  
 +The //​startDMATransfer//​ function starts an uni-directional (one way) AXI DMA transfer.\\  
 +The //​isDMATransferComplete//​ function informs when a transfer is complete. 
 + 
 +---- 
 +==== 2.2.4. Calibration Functions of ZMOD Class ==== 
 +To access the flash memory functionality,​ ZMOD class calls functions from the platform abstraction layer (see [[#​flash_related_functionality|Flash Related Functionality]]).\\  
 +The ZMOD class provides flash initialization and flash transfer functions.\\  
 +These functions are used to manage calibration values specific to each Zmod. They are computed during the Zmod manufacturing process and are stored in the Zmod persistent memory (flash) at specific addresses.\\  
 +The meaning of the content stored in flash memory is specific to each Zmod type, still there are common features: 
 +  * One set of calibration values is stored in the flash memory as an array of bytes, the first being a Zmod specific ID and the last being a checksum of previous bytes. 
 +  * Each Zmod stores in its flash memory two sets of calibration values: one set is called //user calibration//​ and can be modified by user, the other is called //factory calibration//​ and can never be modified. 
 +  * At manufacturing process each Zmod is calibrated. The values are saved as factory calibration and are also copied under user calibration. 
 +  * The user calibration values are used (by the Zmod libraries) to calibrate the Zmod. 
 +  * The user can decide at any time to restore the factory calibration by copying the values from factory calibration to the user calibration area. 
 +The //​initCalib//​ function initializes the calibration related data. It is normally called from the classes derived from ZMOD class, providing as parameter the Zmod ID and the length of the calibration area. The function allocates an array of bytes that will be used as calibration image. The classes derived from ZMOD class will interpret this image as specific calibration structure.\\  
 +The //​readUserCalib//​ function reads from flash an array of bytes from the flash address corresponding to the user calibration. The length of this array is the length of the calibration area. It returns specific errors if the first byte is different than the expected Zmod ID and if the last byte does not match the checksum of the previous bytes.\\  
 +The //​restoreFactoryCalib//​ function reads an array of bytes from the flash address corresponding to the factory calibration and writes the array of bytes to the flash address corresponding to the user calibration.\\  
 +The //​writeUserCalib//​ function writes an array of bytes to the flash address corresponding to the user calibration. Prior to writing, it fills the first byte with the Zmod ID and it computes the checksum on the last byte of the array of bytes to be written.  
 +\\   ​ 
 + 
 +---- 
 +====== 3. Library Usage ====== 
 +===== 3.1. Delivery Structure ===== 
 +The base library and demos are delivered as a 2019.1 Xilinx Vivado SDK workspace and the structure is presented below: 
 +  ​[[https://​github.com/​Digilent/​Eclypse-Z7-SW/​tree/​zmod_adc/​master|Zmod ADC demo]] 
 +      * Folder ZmodADC1410_Demo_Linux contains ​the Linux demo project. Under src folder there are the following linked folders: 
 +        * Folder **zmodlib** links to WORKSPACE_LOC\zmodlib.\\ The structure of **zmodlib** is detailed in the below paragraph. 
 +        * A main file implementing the Linux demo 
 +      * Folder ZmodADC1410_Demo_Baremetal contains the Baremetal project. Under src folder there are the following linked folders: 
 +        * Folder **zmodlib** links to WORKSPACE_LOC\zmodlib.\\ The structure of **zmodlib** is detailed in the below paragraph. 
 +        * A main file, specific to the baremetal app 
 +      * One folder ZmodADC1410_Demo_Baremetal_bsp corresponding to the Baremetal project bsp. 
 +  * [[https://​github.com/​Digilent/​Eclypse-Z7-SW/​tree/​zmod_dac/​master|Zmod DAC demo]] 
 +      * Folder ZmodDAC1411_Demo_Linux contains the Linux demo project. Under src folder there are the following linked folders: 
 +        * Folder **zmodlib** links to WORKSPACE_LOC\zmodlib.\\ The structure of **zmodlib** is detailed in the below paragraph. 
 +        * A main file implementing the Linux demo 
 +      * Folder ZmodDAC1411_Demo_Baremetal contains the Baremetal project. Under src folder there are the following linked folders: 
 +        * Folder **zmodlib** links to WORKSPACE_LOC\zmodlib.\\ The structure of **zmodlib** is detailed in the below paragraph. 
 +        * A main file, specific to the Baremetal app 
 +      * One folder ZmodDAC1411_Demo_Baremetal_bsp corresponding to the Baremetal project bsp. 
 +Under each of the above described demos, the **zmodlib** folder can be found, having the following structure:  
 +        - [[#​zmod_class|ZMOD Base Class]] sources: zmod.cpp, zmod.h 
 +        - Platform dependencies common includes: reg.h, dma.h and flash.h. These headers expose the IP core register access, DMA, and flash  functions that are dependent on the platform (Linux or Baremetal). These functions will be implemented in the source files contained in the platform dependencies folders (Linux and Baremetal) shown below. 
 +        - Platform dependencies folders: 
 +             * Linux - contains separate folders that implement Linux platform related functionality (functions listed in platform dependencies common includes mentioned above) on Linux platform.  
 +             * Baremetal - contains separate folders that implement Baremetal related functionality (functions listed in platform dependencies common includes mentioned above) on Baremetal platform.  
 +        - For each Zmod, the folder containing its library. For example:  
 +             * Folder ZmodADC1410 contains: 
 +               * ZmodADC1410 sources: zmodadc1410.cpp,​ zmodadc1410.h 
 +             * Folder ZmodDAC1411 contains: 
 +               * ZmodADC1411 sources: zmoddac1411.cpp,​ zmoddac1411.h 
 + 
 + 
 +===== 3.2. Environment Setup ===== 
 + 
 +This section contains the steps for setting the environment for [[#​baremetal_project_setup| Baremetal project setup]] and [[#​linux_environment_project_setup | Linux project setup]] for both Zmod ADC and Zmod DAC. 
 +Depending on the user needs, one can either use the projects we deliver in their own development process or use the libraries in their projects. If the second case is considered, the user should apply the below described settings to his project, in order to be able to build it. 
 + 
 +==== 3.2.1 Import Library and Demo Projects ==== 
 + 
 +The steps below need to be followed in order to obtain a complete SDK workspace and to be able to build and run any of the projects, in either Linux or Baremetal platforms. 
 +=== 3.2.1.1 Linux Environment Project Setup === 
 + 
 +/* For the Linux project demo, the operating system of the PC must be a Linux distri ​with Xilinx Vivado 2019.1 installed. \\ */ 
 +The ZmodADC1410_Demo_Linux and ZmodDAC1411_Demo_Linux are run from Xilinx SDK.\\ 
 +This step by step tutorial roughly follows the [[https://​xilinx-wiki.atlassian.net/​wiki/​spaces/​A/​pages/​18841623/​How+to+debug+Linux+Application+in+SDK+2019.1|How to debug Linux Application in SDK 2019.1]] by Xilinx, with some changes due to our Debian 10 rootfs. \\ 
 + 
 +<WRAP center round important 80%> 
 +The following steps are for the **Eclypse Z7** board. 
 +If a Zmod ADC is used, it should be attached to the Eclypse Z7's ZMOD A port. If a Zmod DAC is used, it should be attached to the Eclypse Z7's ZMOD B port. 
 +</​WRAP>​ 
 +<WRAP GROUP> <WRAP COLUMN HALF> 
 +== 3.2.1.1.1 Download the library == 
 +  * Download the git repository containing the libraries and demos using the below command:
  
-<​code>​git clone --recursive ​[email protected]github.com:Digilent/​Eclypse-Z7-SW.git -b zmod_adc_dac/​master</​code>​+<​code>​git clone --recursive ​https://github.com/Digilent/​Eclypse-Z7-SW.git -b zmod_adc_dac/​master</​code>​
    
 NOTE: If you choose to download the repository as ZIP, the folder **zmodlib** will not be populated and you will have to populate it manually. NOTE: If you choose to download the repository as ZIP, the folder **zmodlib** will not be populated and you will have to populate it manually.
Line 85: Line 256:
 {{ :​reference:​zmod:​capture1.png |}} {{ :​reference:​zmod:​capture1.png |}}
 </​WRAP></​WRAP>​ </​WRAP></​WRAP>​
 +
 +== 3.2.1.1.2 Download the SD Card Image ==
 +
 +    *  Download the latest eclypse-debian-buster-armhf-rfs.img_X.X.zip Petalinux image from the Eclypse Z7 git repository [[https://​github.com/​Digilent/​Eclypse-Z7/​releases|Releases]] and extract it on your PC.
 +      * You need to expand the Assets section to see the files.
 +    * Write the image to an SD card:
 +      * Linux: in a terminal window use the following command: <​code>​dd if=/​path/​to/​extracted/​image/​eclypse-debian-buster-armhf-rfs.img of=/​dev/​(sdX or mmcblkX} ​ && sync</​code>​
 +      * Windows: use [[https://​rufus.ie/​|Rufus]] or [[https://​sourceforge.net/​projects/​win32diskimager/​|Win32DiskImager]].
 +    * Connect the board to your Ethernet network.
 +    * Insert the SD card and boot the board. On first boot, the rootfs partition will resize to fill the SD card then reboot.
 +    * Open a Terminal and connect to the board via its USB-UART interface (labeled PROG). ​
 +    * Login with username: //eclypse// and password: //​eclypse//​.
  
 ---- ----
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.1.3 Add Vivado SDK workspace location ​ ==
  
-=== 2.2.1.2. Add Vivado SDK workspace location ​ === +  ​* The downloaded workspace contains demo applications for both Linux and Baremetal
- +
-  ​* The downloaded workspace contains demo applications for Linux and baremetal+
   * Open Vivado SDK 2019.1 and assign the workspace location to the project download location.   * Open Vivado SDK 2019.1 and assign the workspace location to the project download location.
-  * If you want to use the demo projects, open the desired Linux or baremetal ​demo project. The projects are already configured and ready to be used, except the Linux project where SYSROOT environment variable must be set according to [[#add_sysroot_environment_variable ​| Add SYSROOT Environment Variable]] section. +  * If you want to use the demo projects, open the desired Linux or Baremetal ​demo project. The projects are already configured and ready to be used, except the Linux project where SYSROOT environment variable must be set according to [[#add_sysroot_environment_variable_in_sdk ​| Add SYSROOT Environment Variable]] section.
-  * If you want to create your own project: +
-      * Create a new application project (Linux or baremetal). +
-      * Configure it as described on [[#​project_settings|Project Settings]] section.\\  +
-  +
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
Line 108: Line 285:
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-=== 2.2.1.3. Import library to Vivado SDK  ​===+== 3.2.1.1.Import library to Vivado SDK  ==
     * File -> Import     * File -> Import
  
Line 126: Line 303:
  
     * Select the project download location ​     * Select the project download location ​
- 
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
Line 133: Line 309:
  
 ---- ----
 +
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-=== 2.2.1.4Vivado ​SDK Project Explorer ===+== 3.2.1.1.5 Add SYSROOT Environment Variable in SDK ==
  
-    * If the user doesn't use the Linux demonstrations, ​the ZmodADC1410_Demo_Linux and ZmodDAC1411_Demo_Linux projects must be closed or deleted ​from Project Explorer ​(right-click on project ​name-> Close Project or Delete) +    *  ​Download ​the latest eclypse-debian-buster-armhf-sysroot_X.X.tar.xz (**.zip** for Windows ) sysroot from the Eclypse Z7 git repository's [[https://​github.com/​Digilent/​Eclypse-Z7/​releases|Releases]] page and extract it on your PC (the location of the extracted folder will be later used as the path for the SYSROOT Environment Variable) \\ **Note:** //You need to expand the Assets section ​from github to see the eclypse-debian-buster-armhf-sysroot_X.X.tar.xz and .zip files.// \\ **Windows only:** //When prompted whether to replace existing files, choose to replace.//​ 
-    * If the user wants to use the Linux demonstrations,​ then he must follow ​the steps from [[#​linux_project_demonstration|Linux project demonstration]] section.+    * In the SDK Project Explorerright click on the application ​project ​you wish to run, then click “C/C++ Build Settings” 
 +    * In the “C/C++ Build” group, select the “Environment” category 
 +    * Add the SYSROOT variable pointing ​to the location where eclypse-debian-buster-armhf-sysroot rootfs folder can be found. For example “/​home/​cosmin/​Documents/​eclypse-debian-buster-armhf-sysroot” \\ **Windows:​** //The SYSROOT environment variable if exists ​must be //Delete//d then re//Add//ed to the list, rather than //Edit//ing the existing variable.// 
 +    * Click OK and wait for the Project to build
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture6.png?450 |}}+{{ :​reference:​zmod:​capture2.2.2.2.png?450 |}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​
  
Line 146: Line 326:
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-=== 2.2.1.5Run the demo project === +== 3.2.1.1.6 Find the Board IP Address ​== 
-    * Make sure the board is connected to your PC and it is powered on. +    * In the UART Terminal ​connected to the board, log in with the username/​password combination eclypse/​eclypse ​ 
-    * Make sure the jumpers are set accordingly. +    * Run the following command: 
-    * Program ​the board: ​Xilinx -> Program FPGA+<​code>​ip a</​code>​ 
 +    * Copy the IP address of the board, example10.0.0.168
  
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​zmod:​capture2.2.2.3.png?​450 |}}
 +</​WRAP>​ </​WRAP> ​
 +
 +----
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.1.7 Establishing Connection to the Board ==
 +    * In the SDK Target Connections panel, open the Linux TCF Agent folder
 +    * Right click on Linux Agent [default] and click Edit
 +    * Enter the board IP address into the Host section
 +    * Click Test Connection to make sure that SDK can communicate with the TCF-agent on the board
 +    * Click OK
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture7.png?450 |}}+{{ :​reference:​zmod:​capture2.2.2.4.png?450 |}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​
 +
 +----
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.1.8 Run the Demo Project ==
  
-    * Run the demo applicationright-click on project ​name -> Run as -> Launch on Hardware(System Debugger)+    * To run the demo applicationright-click on Project ​name -> Run as -> Launch on Hardware(System Debugger)
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
 {{ :​reference:​zmod:​capture8.png?​450 |}} {{ :​reference:​zmod:​capture8.png?​450 |}}
 </​WRAP>​ </​WRAP>​ </​WRAP>​ </​WRAP>​
- 
 ---- ----
-==== 2.2.2. Linux project demonstration ==== 
-For the Linux project demo, the operating system of the PC must be a Linux distro with Xilinx Vivado 2019.1 installed. \\ 
-The ZmodADC1410_Demo_Linux and ZmodDAC1411_Demo_Linux are run from Xilinx SDK.\\ 
-On the development board with the attached Zmod(s) the user must use the following Linux image: 
-   * [[https://​github.com/​Digilent/​Eclypse-Z7/​releases|Eclypse Z7 image]] 
  
-<​WRAP ​center round important 60%+=== 3.2.1.2 Baremetal Project Setup === 
-Please follow the steps **2.2.1.1** to **2.2.1.3** in order to get the SDK workspace up and running. +<​WRAP ​GROUP> <WRAP COLUMN HALF
-The following steps are for the **Eclypse Z7** board. +== 3.2.1.2.1 ​Download ​the library ==
-</​WRAP>​+
  
-=== 2.2.2.1. Download the SD card image === +  ​* Download the demo project with the below command:
-    ​ Download the latest eclypse-debian-buster-armhf-rfs.img_X.X.zip image from [[https://​github.com/​Digilent/​Eclypse-Z7/​releases|here]] and extract it on your PC +
-      * You need to expand ​the Assets section to see the files +
-    * Write the image to an SD card +
-      * Linux: in a terminal window use the following ​command ​<​code>​dd if=/​path/​to/​extracted/​image/​eclypse-debian-buster-armhf-rfs.img of=/​dev/​(sdX or mmcblkX} ​ && sync</​code>​ +
-      * Windowsuse [[https://​rufus.ie/​|Rufus]] or [[https://​sourceforge.net/​projects/​win32diskimager/​|Win32DiskImager]] +
-    * Connect the board to your ethernet network +
-    * Insert the SD card and boot  the board. On first boot, the rootfs partition will resize to fill the SD card then reboot. +
-    * Open a Terminal and connect to the board via UART interface ​+
  
-----+<​code>​git clone --recursive https://​github.com/​Digilent/​Eclypse-Z7-SW.git -b zmod_adc_dac/​master</​code>​ 
 +  
 +NOTE: If you choose to download the repository as ZIP, the folder **zmodlib** will not be populated and you will have to populate it manually.
  
-<WRAP GROUP> <WRAP COLUMN HALF> +  ​The [[#​delivery_structure|delivery structure]] will be later used for the Vivado ​SDK workspace.
-=== 2.2.2.2. Add SYSROOT Environment Variable in the SDK ==== +
-    ​ ​Download the latest eclypse-debian-buster-armhf-sysroot_X.X.tar.gz sysroot from [[https://​github.com/​Digilent/​Eclypse-Z7/​releases|here]] and extract it on your PC (the location of the extracted folder ​will be later used as path for SYSROOT Environment Variable) +
-**Note: You need to expand the Assets section from github to see the eclypse-debian-buster-armhf-sysroot_X.X.tar.gz file.** +
-    * In the SDK Project Explorer, right click on the application project you wish to run, then select “C/C++ Build Settings” +
-    * In the “C/C++ Build” group, select “Environment” category +
-    * Add SYSROOT variable pointing to the location where eclypse-debian-buster-armhf-sysroot rootfs folder can be foundFor example “/​home/​cosmin/​Documents/​eclypse-debian-buster-armhf-sysroot” +
-    * Click on Ok and wait for the Project to build+
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture2.2.2.2.png?450 |}} +{{ :​reference:​zmod:​capture1.png |}} 
-</​WRAP>​ </​WRAP> ​+</​WRAP></​WRAP>​
  
 ---- ----
- 
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-==2.2.2.3. Find the Board IP address ==== +== 3.2.1.2.2 Add Vivado SDK workspace location  ​== 
-    In the UART Terminal of the board login with the username/​password eclypse:​eclypse ​ + 
-    Run the command +  ​The downloaded workspace contains demo applications for both Linux and Baremetal. ​ 
-<​code>​ip a</​code>​ +  Open Vivado SDK 2019.1 and assign the workspace location to the project download location. 
-    Copy the IP address of the board, example 10.0.0.168+  If you want to use the demo projects, open the desired Baremetal demo projectThe projects are already configured and ready to be used.
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture2.2.2.3.png?450 |}}+{{ :​reference:​zmod:​capture2.png |}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​
  
 ---- ----
- 
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-=== 2.2.2.4. Establishing connection ​to the board ==== +== 3.2.1.2.3 Import library ​to Vivado SDK  ​== 
-    * In the SDK Target Connections panel, open the Linux TCF Agent folder +    * File -> Import
-    * Right click on Linux Agent [default] and hit Edit +
-    * Write the board IP address in to the Host section +
-    * Click Test Connection to make sure that SDK can communicate with the TCF-agent on the board +
-    * Click OK+
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture2.2.2.4.png?450 |}}+{{ :​reference:​zmod:​capture3.png?350 |}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​
- 
----- 
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-=== 2.2.1.5. Run the demo project === 
  
-    * Run the demo application:​ right-click on Project name -> Run as -> Launch on Hardware(System Debugger)+    * Select General ​-> Existing Projects into Workspace ​-> Next
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture8.png?450 |}}+{{ :​reference:​zmod:​capture4.png?450 |}}
 </​WRAP>​ </​WRAP>​ </​WRAP>​ </​WRAP>​
  
----- +<WRAP GROUP> <WRAP COLUMN HALF>
-====== 3. Implementation Details ====== +
-===== 3.1. Platform Abstraction Layer ===== +
-The  [[#​zmod_class|ZMOD Class]] calls Zmod the IP related functionality,​ DMA related functionality and Flash related functionality ​  which are implemented differently on Linux and baremetal. The platform abstraction layer provides a common API for both platforms.\\  +
-The Zmod folder contains these header files: reg.h, dma.h and flash.h which contain declarations for the platform dependent functions corresponding to IP Core registers, AXIDMA and flash. The function prototypes are common for both platforms while the functions are implemented in the baremetal and Linux folders.\\  +
-The project level definition LINUX_APP ensures each function is implemented exactly once (all the Linux platform projects must define LINUX_APP, as explained in the [[#​project_settings|Project Settings]] section).\\  +
-Under the linux and baremetal folders there is a separate folder for each interface: reg, dma, flash, and intc (for baremetal only).\\ For more details, read  [[#​zmod_ip_related_functionality|Zmod IP Related Functionality]],​ [[#​flash_functionality|Flash Related Functionality]] and [[#​dma_related_functionality|DMA Related Functionality]].\\ ​+
  
-==== 3.1.1. IP Core Related Functionality ==== +    ​Select ​the project ​download location ​
-The IP core related functionality provides access to the registers of the IP core corresponding to a particular Zmod. This functionality is called from [[#​zmod_class|ZMOD Class]].\\  +
-This functionality allows: +
-  ​Initialization / de-initialization of the IP core +
-  * Reading and writing Zmod registers. +
-  * Initialization and handling of the interrupts raised by Zmod interrupts (only for Baremetal platform) +
-This functionality is platform dependent, as explained in the [[#​platform_abstraction_layer|Platform Abstraction Layer]].\\  +
-The header for these functions is Zmod/reg.h and is common to both Linux and baremetal platforms. The implementations of these functions are in Zmod/​linux/​reg.c and Zmod/​baremetal/​reg.c,​ exclusively depending on the project ​level definition LINUX_APP.\\  +
-<WRAP center round box 95%> +
-The Linux implementation uses UIO mapping to access the IP registers. +
-</​WRAP>​ +
-<WRAP center round box 95%> +
-The baremetal implementation uses Xil_Out32 and Xil_In32 to access the IP registers.\\  +
-The baremetal uses the XIlinx interrupt controller XIntc. The interrupt related implementation is implemented in Zmod/intc folder. +
-</​WRAP>​ +
-The initialization function takes the //IP base address// and the IP interrupt number as parameters. +
-<WRAP center round box 95%> +
-On Linux, the IP base address is stored in /​sys/​class/​uio/​uio<​uio number>/​maps/​map<​map number>/​addr file. The <uio number> and <map number> are usually '​0'​. For Linux the IP core interrupt is not implemented,​ so -1 is used. +
-</​WRAP>​ +
-<WRAP center round box 95%> +
-For baremetal, the IP base address and the IP interrupt number are specified in xparameters.h (in the bsp include files). For example, XPAR_AXI_ZMODADC1410_0_S00_AXI_BASEADDR and XPAR_FABRIC_AXI_ZMODADC1410_0_IRQ_OUT_INTR.\\  +
-</​WRAP>​ +
-The IP core related functionality is mainly called from [[#​ip_register_access_functions_of_zmod_class|IP Register Access Functions of ZMOD Class]]. ​+
  
----- 
-==== 3.1.2. AXI DMA Related Functionality ==== 
-The AXI DMA related functionality provides the ability to transfer data over AXI DMA. This functionality is called from [[#​zmod_class|ZMOD Class]].\\ ​ 
-The functionality allows: 
-  * Initialization / de-initialization of the AXI DMA module. 
-  * To allocate/​free the buffer used for data transfer. 
-  * To initiate one way AXI DMA transfers. 
-  * To inform when a transfer is complete 
-This functionality is platform dependent, as explained in the [[#​platform_abstraction_layer|Platform Abstraction Layer]].\\ ​ 
-The header for these functions is Zmod/dma.h and is common to both Linux and baremetal platforms. The implementations of these functions are in Zmod/​linux/​dma.c and Zmod/​baremetal/​dma.c,​ exclusively depending on the project level definition LINUX_APP. 
-<WRAP center round box 95%> 
-The Linux implementation uses libaxidma devices for each AXIDMA instance. 
-</​WRAP>​ 
-<WRAP center round box 95%> 
-The baremetal implementation uses the XAxiDma driver for each AXIDMA instance. 
-</​WRAP>​ 
-The initialization function takes the //AXI DMA base address// and the //AXI DMA interrupt number// as parameters. 
-<WRAP center round box 95%> 
-For Linux, the AXI DMA base address can be found in the /​sys/​class/​uio/​uio<​uio number>/​maps/​map<​map number>/​addr file. The <uio number> and <map number> are usually '​0'​.\\ ​ 
-The AXI DMA interrupt is implemented inside libaxidma, so -1 value can be provided for the AXI DMA interrupt number. 
-</​WRAP>​ 
-<WRAP center round box 95%> 
-For baremetal, the AXI DMA base address and the AXI DMA interrupt number are specified in xparameters.h file (in the bsp include files). For example XPAR_AXI_DMA_0_BASEADDR and XPAR_FABRIC_AXI_DMA_0_S2MM_INTROUT_INTR. 
-</​WRAP>​ 
-The Zmod implementation uses one way AXI DMA transfers (S2MM or MM2S), so the transfer direction is set in the initialization function. \\  
-The AXI DMA related functionality is mainly called from [[#​axi_dma_transfer_functions_of_zmod_class|AXI DMA Transfer Functions of ZMOD Class]]. 
  
----- +</​WRAP>​ <​WRAP ​COLUMN HALF
-==== 3.1.3. Flash Related Functionality ==== +{{ :​reference:​zmod:​capture5.png?450 |}} 
-The Flash related functionality provides access to the persistent memory (flash) placed on each Zmod. These functions are called from [[#​zmod_class|ZMOD Class]] in order to handle calibration values.\\  +</​WRAP>​ </​WRAP> ​
-This functionality allows: +
-  * Flash module initialization / de-initialization  +
-  * To read and write blocks of data from a specified address in flash. +
-This functionality is platform dependent, as explained in the [[#​platform_abstraction_layer|Platform Abstraction Layer]].\\  +
-The header for these functions is Zmod/​flash.h and is common to both Linux and baremetal platforms. The implementations of these functions are in Zmod/​linux/​flash.c and Zmod/​baremetal/​flash.c,​ exclusively depending on the project level definition LINUX_APP. +
-<WRAP center round box 95%> +
-The Linux implementation uses /dev/i2c-0 device. +
-</​WRAP>​ +
-<​WRAP ​center round box 95%+
-The baremetal implementation uses XIicPs driver+
-</​WRAP>​ +
-The initialization function takes the //Flash base address// as a parameter. +
-<WRAP center round box 95%> +
-For Linux, the Flash base address can be found in the /​sys/​bus/​i2c/​devices/​i2c-<​i2c number>/​name file by parsing its content for the adrress. The <i2c number> is usually '​0'​. For example, the content of /​sys/​bus/​i2c/​devices/​i2c-0/​name is "​Cadence I2C at e0005000",​ e0005000 being the needed Flash base address.  +
-</​WRAP>​ +
-<WRAP center round box 95%> +
-For baremetal Flash base address is specified in xparameters.h (in the bsp include files). For example XPAR_PS7_I2C_1_BASEADDR. +
-</​WRAP>​ +
-The Flash functionality also requires the //address of slave flash device//. This can be found in the carrier board reference manual, assigned to the specific SYZYGY connector where the Zmod is plugged.\\  +
-The flash related functionality is mainly called from [[#​calibration_functions_of_zmod_class|Calibrations Functions of ZMOD Class]].+
  
 ---- ----
-===== 3.2 ZMOD Class ===== +<WRAP GROUP> <WRAP COLUMN HALF> 
-This is the base class for individual Zmod classes (for example ZMODADC1410 class or ZMODDAC1411 class)It implements the functionality common to all Zmods and all the functionality needed to access hardware resources, abstracting these details from the classes inherited from it. +== 3.2.1.2.4 Vivado SDK Project Explorer ==
-It implements the following function members: +
-  * [[##​zmod_class_constructordestructor|ZMOD Class Constructor / Destructor]]. +
-  * [[#​ip_register_access_functions_of_zmod_class|IP Register Access Functions of ZMOD Class]].  +
-  * [[#​axi_dma_transfer_functions_of_zmod_class|AXI DMA Transfer Functions of ZMOD Class]].  +
-  * [[#​calibration_functions_of_zmod_class|Calibrations Functions of ZMOD Class]].+
  
-==== 3.2.1. ZMOD Class Constructor / Destructor ==== +  ​*  ​The ZmodADC1410_Demo_Linux ​and ZmodDAC1411_Demo_Linux projects must be closed or deleted from Project Explorer (right-click on project name-> Close Project or Delete)
-The //ZMOD class constructor//​ initializes the hardware interfaces. It takes the following parameters:​ +
-  ​IP core base address and IP core interrupt number\\ See [[#​ip_core_related_functionality|Zmod IP Related Functionality]] for how these values can be identified. +
-  * AXI DMA base address ​and AXI DMA interrupt number\\ See [[#​axi_dma_related_functionality|DMA Related Functionality]] for how these values can be identified. +
-  * I2C address and Flash address\\ See [[#​flash_related_functionality|Flash Related Functionality]] for how these values can be identified. +
-The //ZMOD class destructor//​ calls the destroy functions for the hardware interfaces, also freeing the dynamically allocated calibration data.+
  
----- +</​WRAP>​ <WRAP COLUMN HALF> 
-==== 3.2.2. IP Register Access Functions of ZMOD Class ==== +{{ :reference:zmod:capture6.png?450 |}} 
-The ZMOD class provides initialization of the IP core related module, and access to IP core registers.\\  +</WRAP> </WRAP> ​
-To access IP core related functionality,​ the ZMOD class calls functions from the platform abstraction layer (see [[#​ip_core_related_functionality|IP Core Related Functionality]]).\\  +
-Thus read/write register and read/write register field functions are provided, both in signed and unsigned versions//​readReg//,​ //​writeReg//,​ //​readRegFld//,​ //​writeRegFld//,​ //​readSignedRegFld//​ and //​writeSignedRegFld//​.\\  +
-A //register field// designates a number of contiguous bits inside an IP core register and is defined as a triplet of IP core register address, start bit, and end bit. The register fields can be common to all ZMODS (defined in the base class header file zmod.h) or specific to individual Zmods (defined in the specific library header file, ZMODADC1410/​zmodadc1410.h for example). The register field definitions can be found on each specific Zmod library user guide\\ ​ +
-The ZMOD class also provides functions that allow sending and receiving commands to from the chip on the specific ZMOD (for example sending commands to the ADC device on the ZmodADC1410 or to the DAC device on the ZmodDAC1411): ​//​sendCommand//​ and //​receiveCommand//​ functions.\\ ​+
  
 ---- ----
-===== 3.2.3. AXI DMA Transfer Functions of ZMOD Class ===== 
-To access AXI DMA related functionality,​ the ZMOD class calls functions from the platform abstraction layer (see [[#​axi_dma_related_functionality|AXI DMA Related Functionality]]).\\ ​ 
-The ZMOD class provides initialization and one way AXI DMA transfer functions.\\ ​ 
-Also, ZMOD class provides data buffer allocation / de-allocation functions: //​allocDMABuffer//​ and //​freeDMABuffer//​.\\ ​ 
-The //​setTransferSize//​ function allows setting the AXI DMA transfer size (in  bytes).\\ ​ 
-The //​startDMATransfer//​ function starts an uni-directional (one way) AXI DMA transfer.\\ ​ 
-The //​isDMATransferComplete//​ function informs when a transfer is complete. 
- 
----- 
-==== 3.2.4. Calibration Functions of ZMOD Class ==== 
-To access flash related functionality,​ ZMOD class calls functions from the platform abstraction layer (see [[#​flash_related_functionality|Flash Related Functionality]]).\\ ​ 
-The ZMOD class provides flash initialization and flash transfer functions.\\ ​ 
-These functions are used to manage calibration values specific to each Zmod. They are computed during the Zmod manufacturing process and are stored in the Zmod persistent memory (flash) at specific addresses.\\ ​ 
-The meaning of the content stored in flash is specific to each Zmod type, still there are common features: 
-  * One set of calibration values is stored in the flash memory as an array of bytes, the first being an Zmod specific ID and the last being a checksum of previous bytes. 
-  * Each Zmod stores in its flash two sets of calibration values: one set is called //user calibration//​ and can be modified by user, the other is called factory calibration and can never be modified. 
-  * At manufacturing process each Zmod is calibrated. The values are saved as factory calibration and are also copied under user calibration. 
-  * The user calibration values are used (by the Zmod libraries) to calibrate the Zmod. 
-  * The user can decide at any time to restore the factory calibration by copying the values from factory calibration to the user calibration area. 
-The //​initCalib//​ function initializes the calibration related data. It is normally called from the classes derived from ZMOD class, providing as parameter the Zmod ID and the length of the calibration area. The function allocates an array of bytes that will be used as calibration image. The classes derived from ZMOD class will interpret this image as specific calibration structure.\\ ​ 
-The //​readUserCalib//​ function reads from flash an array of bytes from the flash address corresponding to the user calibration. The length of this array is the length of the calibration area. It returns specific errors if the first byte is different than the expected Zmod ID and if the last byte does not match the checksum of the previous bytes.\\ ​ 
-The //​restoreFactoryCalib//​ function reads an array of bytes from the flash address corresponding to the factory calibration and writes the array of bytes to the flash address corresponding to the user calibration.\\ ​ 
-The //​writeUserCalib//​ function writes an array of bytes to the flash address corresponding to the user calibration. Prior to writing, it fills the first byte with the Zmod ID and it computes the checksum on the last byte of the array of bytes to be written. ​ 
-\\    
- 
- 
- 
- 
- 
- 
  
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.2.5. Run the demo project ==
 +    * Make sure the board is connected to your PC and it is powered on.
 +    * Make sure the jumpers are set accordingly.
 +    * Program the board: Xilinx -> Program FPGA
  
  
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​zmod:​capture7.png?​450 |}}
 +</​WRAP>​ </​WRAP> ​
 +<WRAP GROUP> <WRAP COLUMN HALF>
  
 +    * Run the demo application:​ right-click on project name -> Run as -> Launch on Hardware(System Debugger)
  
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​zmod:​capture8.png?​450 |}}
 +</​WRAP>​ </​WRAP>​
  
 ---- ----
-====== 4. Project Settings ====== 
  
-This chapter details the configuration needed for the baremetal or Linux projects.\\  +==== 3.2.2 Create New Project/Use libraries in your project ====
-It is assumed that Zmod and specific folders for Zmods (ZmodADC1410 for example) are placed in the SDK workspace root folder, as provided by Digilent (see [[#​delivery_structure|Delivery Structure]]). +
-For Linux projects please follow the section [[#2.2.2.1._download_the_SD_card_image | Download the SD card image]] ​+
  
 +This use case is needed when an SDK workspace is created by the user.
 +The steps below need to be followed in order to obtain a complete SDK workspace and to be able to build and run any of the projects, in either Linux or Baremetal platforms.
  
-<WRAP GROUP> <WRAP COLUMN HALF> +=== 3.2.2.1 Linux Environment ​Project ​Setup === 
-===== 4.1Linux Project ​===== +      ​ 
-==== 4.1.1. Link zmodlib Folder ​==== +== 3.2.2.1.1 Create New Project and Link zmodlib Folder == 
-    * Under src folder, ​Right Mouse button ​option New / Folder+ 
 +<WRAP GROUP> <WRAP COLUMN HALF> ​    
 +    It is assumed that Zmod and specific folders for Zmods (ZmodADC1410 for example) are placed in the SDK workspace root folder, as provided by Digilent (see [[#​delivery_structure|Delivery Structure]]). 
 +    * Create a new application project. 
 +    * Under src folder, ​right click option, select ​New / Folder
     * Select Advanced     * Select Advanced
     * Link to alternate location (Linked Folder)     * Link to alternate location (Linked Folder)
     * **Variables...** -> Select **WORKSPACE_LOC** -> Extend... -> Select **zmodlib** folder     * **Variables...** -> Select **WORKSPACE_LOC** -> Extend... -> Select **zmodlib** folder
- 
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture4.1.1.png |}}+{{ :​reference:​zmod:​capture4.2.1.png|}}
 </​WRAP></​WRAP>​ </​WRAP></​WRAP>​
  
-----+<WRAP GROUP> <WRAP COLUMN HALF> 
 +== 3.2.2.1.2 Add “--sysroot” Project Setting == 
 + 
 +    * In the Project Explorer, right click on the project name, select “C/C++ Build Settings” 
 +    * In the “C/C++ Build” group, select “Settings” category 
 +    * Select “ARM v7 Linux g++ linker”/​”Miscelaneous” node 
 +    * In the Linker Flags field add <​code>​--sysroot=${SYSROOT}</​code>​ 
 + 
 +</​WRAP>​ <WRAP COLUMN HALF> 
 +{{ :​reference:​zmod:​capture4.1.6.png |}} 
 +</​WRAP>​ </​WRAP> ​
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-==== 4.1.2. Define LINUX_APP ​==== +== 3.2.2.1.3 Define LINUX_APP == 
-    * In the Project Explorer, right mouse button ​on the project, “C/C++ Build Settings”+    * In the Project Explorer, right click on the project ​nameselect ​“C/C++ Build Settings”
     * In the “C/C++ Build” group, select “Settings” category     * In the “C/C++ Build” group, select “Settings” category
     * Select “ARM v7 Linux g++ compiler”/​”Symbols” node     * Select “ARM v7 Linux g++ compiler”/​”Symbols” node
     * Add LINUX_APP definition (using the ‘+’ button)     * Add LINUX_APP definition (using the ‘+’ button)
- 
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
 {{ :​reference:​zmod:​capture4.1.2.png |}} {{ :​reference:​zmod:​capture4.1.2.png |}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​
- 
----- 
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-==== 4.1.3. Add SYSROOT Environment Variable in the SDK ==== +== 3.2.2.1.Add SYSROOT Environment Variable in the SDK == 
-    * Download the latest eclypse-debian-buster-armhf-sysroot_X.X.tar.gz sysroot from [[https://​github.com/​Digilent/​Eclypse-Z7/​releases|here]] and extract it on your PC +    * Download the latest eclypse-debian-buster-armhf-sysroot_X.X.tar.gz sysroot from [[https://​github.com/​Digilent/​Eclypse-Z7/​releases|Releases]] and extract it on your PC 
-      * You need to expand the Assets section to see the file +      * You need to expand the Assets section ​of the git page to find the file mentioned above 
-    * In the Project Explorer, right mouse button ​on the project, “C/C++ Build Settings”+    * In the Project Explorer, right click on the project ​nameselect ​“C/C++ Build Settings”
     * In the “C/C++ Build” group, select “Environment” category     * In the “C/C++ Build” group, select “Environment” category
-    * Add SYSROOT variable pointing to the location where petalinux ​sysroot can be found. For example “/​home/​cosmin/​Documents/​eclypse-debian-buster-armhf-sysroot”+    * Add SYSROOT variable pointing to the location where Petalinux ​sysroot can be found. For example “/​home/​cosmin/​Documents/​eclypse-debian-buster-armhf-sysroot”
  
 **Note**: //In Petalinux 2019.1 in order to build the sysroot image is necessary to run the following command: // **Note**: //In Petalinux 2019.1 in order to build the sysroot image is necessary to run the following command: //
 <​code>​petalinux-build -c build-sysroots</​code>​ <​code>​petalinux-build -c build-sysroots</​code>​
- 
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture4.1.3.png|}}+{{ :​reference:​zmod:​addsysroot.png|}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​
- 
----- 
- 
-<WRAP GROUP> <WRAP COLUMN HALF> 
-==== 4.1.4. Define Include Directories ==== 
-    * In the Project Explorer, right mouse button on the project, “C/C++ Build Settings” 
-    * In the “C/C++ Build” group, select “Settings” category 
-    * Select “ARM v7 Linux g++ compiler”/​”Directories” node 
-    * Add the following directories:​ 
-      * **//​${SYSROOT}/​usr/​include//​** 
-      * **//​${CWD}/​../​../​zmodlib/​Zmod//​** 
-      * **//​${CWD}/​../​../​zmodlib/​ZmodADC1410//​** 
- 
- 
- 
-</​WRAP>​ <WRAP COLUMN HALF> 
-{{ :​reference:​zmod:​capture4.1.4.png |}} 
-</​WRAP>​ </​WRAP> ​ 
- 
----- 
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-==== 4.1.5Define Libraries and Library Directories ​==== +== 3.2.2.1.5 Define Libraries and Library Directories == 
-    * In the Project Explorer, right mouse button ​on the project, “C/C++ Build Settings”+    * In the Project Explorer, right click on the project ​nameselect ​“C/C++ Build Settings”
     * In the “C/C++ Build” group, select “Settings” category     * In the “C/C++ Build” group, select “Settings” category
     * Select “ARM v7 Linux g++ linker”/​”Libraries” node     * Select “ARM v7 Linux g++ linker”/​”Libraries” node
Line 469: Line 519:
 {{ :​reference:​zmod:​capture4.1.5.png|}} {{ :​reference:​zmod:​capture4.1.5.png|}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​
- 
----- 
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-==== 4.1.6. Add “--sysroot” Project Setting ==== +== 3.2.2.1.6 Define Include Directories ​== 
-    * In the Project Explorer, right mouse button ​on the project, “C/C++ Build Settings”+    * In the Project Explorer, right click on the project ​nameselect ​“C/C++ Build Settings”
     * In the “C/C++ Build” group, select “Settings” category     * In the “C/C++ Build” group, select “Settings” category
-    * Select “ARM v7 Linux g++ linker”/”Miscelaneous” node +    * Select “ARM v7 Linux g++ compiler”/”Directories” node 
-    * In the Linker Flags field add <​code>​--sysroot=${SYSROOT}</code>+    * Add the following directories:​ 
 +      * **//${SYSROOT}/usr/​include//​** 
 +      * **//​${CWD}/​../​../​zmodlib/​Zmod//​** 
 +      * **//​${CWD}/​../​../​zmodlib/​ZmodADC1410//​**
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture4.1.6.png |}}+{{ :​reference:​zmod:​capture4.1.4.png |}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​
  
 ---- ----
  
-<WRAP GROUP> <WRAP COLUMN HALF> +=== 3.2.2.2 Baremetal Project ​Setup=== 
-===== 4.2. Baremetal Project ​===== + 
-==== 4.2.1. Link zmodlib Folder ​==== +== 3.2.2.2.1 Create New Project and Link zmodlib Folder == 
-    * Under src folder, ​Right Mouse button ​option New / Folder+ 
 +<WRAP GROUP> <WRAP COLUMN HALF> ​    
 +    It is assumed that Zmod and specific folders for Zmods (ZmodADC1410 for example) are placed in the SDK workspace root folder, as provided by Digilent (see [[#​delivery_structure|Delivery Structure]]). 
 +    * Create a new application project. 
 +    * Under src folder, ​right click option, select ​New / Folder
     * Select Advanced     * Select Advanced
     * Link to alternate location (Linked Folder)     * Link to alternate location (Linked Folder)
     * **Variables...** -> Select **WORKSPACE_LOC** -> Extend... -> Select **zmodlib** folder     * **Variables...** -> Select **WORKSPACE_LOC** -> Extend... -> Select **zmodlib** folder
- 
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
 {{ :​reference:​zmod:​capture4.2.1.png|}} {{ :​reference:​zmod:​capture4.2.1.png|}}
 </​WRAP></​WRAP>​ </​WRAP></​WRAP>​
- 
----- 
  
 <WRAP GROUP> <WRAP COLUMN HALF> <WRAP GROUP> <WRAP COLUMN HALF>
-==== 4.2.2. Define Include Directories ​==== +== 3.2.2.2.2 Define Include Directories == 
-    * In the Project Explorer, right mouse button ​on the project, “C/C++ Build Settings”+    * In the Project Explorer, right click on the project ​nameselect ​“C/C++ Build Settings”
     * In the “C/C++ Build” group, select “Settings” category     * In the “C/C++ Build” group, select “Settings” category
-    * Select “ARM v7 Linux g++ compiler”/​”Directories” node+    * Select “ARM v7 g++ compiler”/​”Directories” node
     * Add the following directories:​     * Add the following directories:​
-      * **//​${SYSROOT}/​usr/​include//​** 
       * **//​${CWD}/​../​../​zmodlib/​Zmod//​**       * **//​${CWD}/​../​../​zmodlib/​Zmod//​**
       * **//​${CWD}/​../​../​zmodlib/​ZmodADC1410//​**       * **//​${CWD}/​../​../​zmodlib/​ZmodADC1410//​**
- 
- 
  
 </​WRAP>​ <WRAP COLUMN HALF> </​WRAP>​ <WRAP COLUMN HALF>
-{{ :​reference:​zmod:​capture4.1.4.png |}}+{{ :​reference:​zmod:​capture4.2.2.png |}}
 </​WRAP>​ </​WRAP> ​ </​WRAP>​ </​WRAP> ​