Differences

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

Link to this comparison view

zmod:zmodbaselibraryuserguide [2022/06/06 16:28] – add baud rate Arthur Brownzmod:zmodbaselibraryuserguide [2022/10/04 11:38] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +====== Zmod Base Library User Guide ======
 +
 +====== 1. Overview ======
 +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. \\ 
 +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 having a SYZYGY connector.\\ 
 +
 +**Note:** //At the time of writing, the ZmodADC1410 library only supports the Zmod Scope 1410-105 (formerly known as the Zmod ADC 1410.//
 +
 +The following block diagram shows the overall structure of Zmod Libraries.
 +
 +{{ :reference:programmable-logic:eclypse-z7:zmod_dev-board_structure_-_generic.png}}
 +
 +The Zmod libraries run in the Zynq PS (processing system).\\ 
 +The Zmod is physically attached on the SYZYGY connector of the development board (Eclypse).\\ 
 +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.\\ 
 +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 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:\\ 
 +  * Provide a consistent API to: 
 +    * different Zmods
 +    * 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:
 +    * AXI DMA 
 +    * Flash 
 +    * Communication with IP cores specific to each particular Zmod \\ 
 +
 +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:[[/zmod/zmodbaselibraryuserguide#linux_environment_project_setup|ADC/DAC Import Project Linux]] | @#C0EEBD:[[/zmod/zmodbaselibraryuserguide#baremetal_project_setup|ADC/DAC Import Project Baremetal]]       |
 +|   @#95B9AF:[[/reference/zmod/zmodbaselibraryuserguide#linux_environment_project_setup1|ADC/DAC Create Project  Linux]] | @#C0EEBD:[[/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:
 +  * [[zmod:scope:zmodadc1410libraryuserguide]] 
 +  * [[zmod:awg: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. Implementation Details ======
 +===== 2.1. Platform Abstraction Layer =====
 +The  [[#zmod_class|ZMOD Class]] calls Zmod IP Cores related functionality, AXI 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, AXI DMA and Flash. The functions prototypes are common for both platforms while their implementation resides 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).\\ 
 +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.\\ 
 +
 +==== 2.1.1. IP Core Related Functionality ====
 +The IP core related functionality provides access to the registers of the IP core corresponding to a particular Zmod.\\ 
 +This functionality allows:
 +  * Initialization/de-initialization of the IP core
 +  * Reading and writing Zmod registers.
 +  * Initialization and handling of the interrupts addressed by Zmod interrupt controller (only for Baremetal platform)
 +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/reg.h 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.\\ 
 +<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__cores_register_access_functions_of_zmod_class|IP Cores Register Access Functions of ZMOD Class]]. 
 +
 +----
 +==== 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.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]].
 +
 +----
 +===== 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. ZMOD Class Constructor / Destructor ====
 +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 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.\\ 
 +
 +----
 +==== 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 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.
 +
 +  * The [[#delivery_structure|delivery structure]] will be later used for the Vivado SDK workspace.
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture1.png |}}
 +</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>
 +== 3.2.1.1.3 Add Vivado SDK workspace location  ==
 +
 +  * The downloaded workspace contains demo applications for both Linux and Baremetal. 
 +  * 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_in_sdk | Add SYSROOT Environment Variable]] section.
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture2.png |}}
 +</WRAP> </WRAP> 
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.1.4 Import library to Vivado SDK  ==
 +    * File -> Import
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture3.png?350 |}}
 +</WRAP> </WRAP> 
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +
 +    * Select General -> Existing Projects into Workspace -> Next
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture4.png?450 |}}
 +</WRAP> </WRAP>
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +
 +    * Select the project download location 
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture5.png?450 |}}
 +</WRAP> </WRAP> 
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.1.5 Add SYSROOT Environment Variable in SDK ==
 +
 +    *  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.//
 +    * In the SDK Project Explorer, right 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>
 +{{ :reference:zmod:capture2.2.2.2.png?450 |}}
 +</WRAP> </WRAP> 
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.1.6 Find the Board IP Address ==
 +    * In the UART Terminal connected to the board, log in with the username/password combination eclypse/eclypse 
 +    * Run the following command:
 +<code>ip a</code>
 +    * Copy the IP address of the board, example: 10.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>
 +{{ :reference:zmod:capture2.2.2.4.png?450 |}}
 +</WRAP> </WRAP> 
 +
 +----
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.1.8 Run the Demo Project ==
 +
 +    * To 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>
 +----
 +
 +=== 3.2.1.2 Baremetal Project Setup ===
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.2.1 Download the library ==
 +
 +  * Download the demo project with the below command:
 +
 +<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.
 +
 +  * The [[#delivery_structure|delivery structure]] will be later used for the Vivado SDK workspace.
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture1.png |}}
 +</WRAP></WRAP>
 +
 +----
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.2.2 Add Vivado SDK workspace location  ==
 +
 +  * The downloaded workspace contains demo applications for both Linux and Baremetal. 
 +  * 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 Baremetal demo project. The projects are already configured and ready to be used.
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture2.png |}}
 +</WRAP> </WRAP> 
 +
 +----
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.2.3 Import library to Vivado SDK  ==
 +    * File -> Import
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture3.png?350 |}}
 +</WRAP> </WRAP> 
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +
 +    * Select General -> Existing Projects into Workspace -> Next
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture4.png?450 |}}
 +</WRAP> </WRAP>
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +
 +    * Select the project download location 
 +
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture5.png?450 |}}
 +</WRAP> </WRAP> 
 +
 +----
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.1.2.4 Vivado SDK Project Explorer ==
 +
 +  *  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)
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture6.png?450 |}}
 +</WRAP> </WRAP> 
 +
 +----
 +
 +<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>
 +
 +----
 +
 +==== 3.2.2 Create New Project/Use libraries in your project ====
 +
 +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.
 +
 +=== 3.2.2.1 Linux Environment Project Setup ===
 +      
 +== 3.2.2.1.1 Create New Project and Link zmodlib 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
 +    * Link to alternate location (Linked Folder)
 +    * **Variables...** -> Select **WORKSPACE_LOC** -> Extend... -> Select **zmodlib** folder
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture4.2.1.png|}}
 +</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>
 +== 3.2.2.1.3 Define LINUX_APP ==
 +    * 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++ compiler”/”Symbols” node
 +    * Add LINUX_APP definition (using the ‘+’ button)
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture4.1.2.png |}}
 +</WRAP> </WRAP> 
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.2.1.4 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|Releases]] and extract it on your PC
 +      * You need to expand the Assets section of the git page to find the file mentioned above
 +    * In the Project Explorer, right click on the project name, select “C/C++ Build Settings”
 +    * 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”
 +
 +**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>
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:addsysroot.png|}}
 +</WRAP> </WRAP> 
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.2.1.5 Define Libraries and Library Directories ==
 +    * 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”/”Libraries” node
 +    * Add the following library in the “Libraries (-l)” list:
 +      * uio
 +    * Add the following directories in the “Library search path (-L)” list:
 +      * **//${SYSROOT}/usr/lib//**
 +      * **//${SYSROOT}/lib//**
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture4.1.5.png|}}
 +</WRAP> </WRAP> 
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.2.1.6 Define Include Directories ==
 +    * 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++ 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> 
 +
 +----
 +
 +=== 3.2.2.2 Baremetal Project Setup===
 +
 +== 3.2.2.2.1 Create New Project and Link zmodlib 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
 +    * Link to alternate location (Linked Folder)
 +    * **Variables...** -> Select **WORKSPACE_LOC** -> Extend... -> Select **zmodlib** folder
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture4.2.1.png|}}
 +</WRAP></WRAP>
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +== 3.2.2.2.2 Define Include Directories ==
 +    * 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 g++ compiler”/”Directories” node
 +    * Add the following directories:
 +      * **//${CWD}/../../zmodlib/Zmod//**
 +      * **//${CWD}/../../zmodlib/ZmodADC1410//**
 +
 +</WRAP> <WRAP COLUMN HALF>
 +{{ :reference:zmod:capture4.2.2.png |}}
 +</WRAP> </WRAP> 
 +
 +----
 +
 +
 +
 +