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:programmable-logic:eclypse-z7:zmodlibuserguide [2019/12/03 14:11]
Cristian Fatu
reference:programmable-logic:eclypse-z7:zmodlibuserguide [2019/12/05 10:34] (current)
Ana-Maria-Eliza Balas [3. Hardware abstraction implementation]
Line 7: Line 7:
  
  
-====== Library structure ====== +====== ​1. Overview ====== 
-===== ZMOD base class =====+This document describes the structure of the Zmod Library ​implementation. The implementation is not finalized, still the structure ​is (largely) definitive. 
 +Objectives:​ 
 +- provide consistent approach among the different Zmods 
 +- provide consistent approach among different hardware platforms: baremetal and linux 
 +- give full access to the IP implementing at lower level the Zmod functionality 
 + 
 +====== 2. Approach ​====== 
 +The library is implemented using CPP app. The techniques involved are not too complicated,​ so that they can be understood by average technicians:​ 
 +  - Simple inheritance 
 +  - Some simple virtual functions, easy to understand as they will be well documented 
 +  - Multiple headers implementing definitions for different levels 
 + 
 +====== 3. Hardware abstraction implementation ====== 
 +The implemented functionality is targeted for separate hardware platforms: linux and baremetal. The  [[#​zmod_class|ZMOD class]] functionality calls Zmod IP related functionality and DMA related functionality which are implemented differently on the two above mentioned platforms. A hardware abstraction layer is implemented,​ hiding under it all the hardware related specific. 
 +These are the details of this approach: 
 +  * The functionality dependent to the hardware platform is developed outside the [[#​zmod_class|ZMOD class]], as global functions called hardware dependencies functions. 
 +  * The Zmod folder contains two hardware dependencies headers: dma.h and reg.h. They contain declarations for hardware dependencies functions. The hardware dependencies functions prototypes are identical for both hardware platforms so these 2 header files are common for both platforms. The hardware dependencies functions are implemented in the baremetal and linux folders, detailed in the next paragraph:​ 
 +  * The Zmod folder contain two folders corresponding to each specific hardware platform: baremetal and linux. The source files in these folders implement the hardware dependencies functions. These functions are declared in the hardware dependencies headers explained at the previous paragraph. These source files content is guarded (using #ifdef and #ifndef accordingly) using a project level definition called LINUX_APP, ensuring that for a specific platform each function is implemented exactly once. The LINUX_APP define is only defined for Linux type project. The folders are structured on separate folders: dma and reg (eventually intc). Read more on [[#​zmod_ip_related_functionality|Zmod IP related functionality]] and [[#​dma_related_functionality|DMA related functionality]]. 
 + 
 +====== 4. Library structure ====== 
 +===== 4.1. Delivery structure ===== 
 + 
 +The library is delivered as one package of sources (structured on different folders), to be included (or linked) in the linux or baremetal projects. 
 + 
 +We deliver the following hierarchy, delivered as a Xilinx SDK workspace:​ 
 +  * One folder Zmod containing:​ 
 +    * Zmod sources: zmod.cpp, zmod.h 
 +    * Platform dependencies common includes: dma.h, reg.h. These headers exposed the dma and register access functions that are dependent to the hardware platform (linux / 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 
 +      * baremetal 
 +  * One folder ZmodADC1410 containing:​ 
 +    * ZmodADC1410 sources: zmodadc1410.cpp,​ zmodadc1410.h 
 +  * One folder ZmodADC1410_LinuxTest corresponding to the Linux project  
 +    * Contains a linked folder Zmod, linked to WORKSPACE_LOC\Zmod location 
 +    * Contains a linked folder ZmodADC1410,​ linked to WORKSPACE_LOC\ZmodADC1410 location 
 +    * Contains a main file, specific to the linux app 
 +  * One folder ZmodADC1410_BaremetalTest corresponding to the Baremetal project 
 +    * Contains a linked folder Zmod, linked to WORKSPACE_LOC\Zmod location 
 +    * Contains a linked folder ZmodADC1410,​ linked to WORKSPACE_LOC\ZmodADC1410 location 
 +    * Contains a main file, specific to the baremetal app 
 +  * One folder ZmodADC1410_BaremetalTest_bsp corresponding to the Baremetal project bsp. 
 +Discussions were held about delivering a library object (shared object for linux). No decision has been written down. 
 + 
 +===== 4.2. Library implementation details ===== 
 + 
 +This chapter details some implementation decisions.  
 + 
 +==== 4.2.1 ZMOD class ====
 This class is implemented as a base class of the classes corresponding to the individual Zmods ([[#​zmodadc1410_class|ZMODADC1410 class]], [[#​zmoddac1411_class|ZMODDAC1411 class]]). It implements the functionality common to all Pmods. This class is implemented as a base class of the classes corresponding to the individual Zmods ([[#​zmodadc1410_class|ZMODADC1410 class]], [[#​zmoddac1411_class|ZMODDAC1411 class]]). It implements the functionality common to all Pmods.
 It uses register definitions detailed in [[#​register_definitions|Register Definitions]] chapter. It uses register definitions detailed in [[#​register_definitions|Register Definitions]] chapter.
-===== ZMODADC1410 class ===== +  * implements the functionality common to all Zmods 
-===== ZmodDAC1411 class ===== +  * implements the base class for Zmod objects (class ZMOD) - in the zmod.h and zmod.cpp source files 
-====== Register definitions ======+  * it uses definitions for the common Zmod registers and register fields implemented in the zmod.h source file 
 +  * it can transfer data over AXIDMA in one direction (S2MM or MM2S). 
 +    * functionality implemented:​ 
 +      * read / write register Zmod / DMA 
 +      * read / write register fields 
 +      * initialization of AXI DMA and interrupt controller 
 +    * configure / launch AXIDMA transfer in the corresponding direction. 
 +    * virtual function to process the eventual interrupts based on common status fields 
 +  * the class implementation is not hardware dependent. See [[#​hardware_abstraction_implementation|Hardware abstraction implementation]] for more details. 
 + 
 +=== ZMODADC1410 class === 
 +  * implements functionality for a specific Zmod, based on its IP core (ZmodADC1410 Xilinx IP core). 
 +  * ZMODADC1410 class is inherited from [[#​zmod_class|ZMOD class]]. 
 +  * ZMODADC1410 class is implemented in the zmodadc1410.h,​ zmodadc1410.cpp source files. 
 +  * ZMODADC1410 class uses definitions for the specific ZMODADC1410 registers and register fields implemented in the zmodadc1410.h file. 
 + 
 +=== ZmodDAC1411 class === 
 +==== 4.2.2. ​Register definitions ==== 
 +The library defines a set of registers, according to Zmod IP register space. A register is defined as the offset to be added over the Zmod base address. 
 +A register field is a group of bits inside one register, defined as a triplet of: 
 +  * register address 
 +  * lsb_bit 
 +  * number of bits 
 + 
 +The registers and register fields common to all Zmods are defined in the base class header zmod.h and are prefixed by ZMOD_REG and ZMOD_REGFLD 
 +The registers and register fields specific to a certain Zmod will be defined in the specific class header (for example zmodadc1410.h) and are prefixed by Zmod specific ​ (ZMODADC1410_REG and ZMODADC1410_REGFLD,​ for example for ZMODADC1410 Zmod). 
 ^ Address ​                     ^ Register ​                                                  ^ Field                                                                                                                                                                             |||| ^ Address ​                     ^ Register ​                                                  ^ Field                                                                                                                                                                             ||||
 | :::                          | :::                                                        ^ Field name                                                   ^ Start bit                  ^ Length ​                    ^ Description ​                                                ^ | :::                          | :::                                                        ^ Field name                                                   ^ Start bit                  ^ Length ​                    ^ Description ​                                                ^
Line 19: Line 93:
 | :::                          | :::                                                        | ZMOD_REGFLD_CR_CMD_READ_EN ​                                  | 2                          | 1                          | CMD_READ_EN field of CR register ​                           | | :::                          | :::                                                        | ZMOD_REGFLD_CR_CMD_READ_EN ​                                  | 2                          | 1                          | CMD_READ_EN field of CR register ​                           |
 | :::                          | :::                                                        | ZMOD_REGFLD_CR_INTR_EN ​                                      | 3                          | 1                          | INTR_EN field of CR register ​                               | | :::                          | :::                                                        | ZMOD_REGFLD_CR_INTR_EN ​                                      | 3                          | 1                          | INTR_EN field of CR register ​                               |
-| :::                          | :::                                                        | ZMOD_REGFLD_CR_RUNSTOP ​                                      | 4                          | 1                          | RUNSTOP field of CR register ​                               |+| :::                          | :::                                                        | <color #22b14c>ZMOD_REGFLD_CR_RUNSTOP</​color> ​                                      | <color #22b14c>4</​color> ​                         ​| ​<color #22b14c>1</​color> ​                         ​| ​<color #22b14c>RUNSTOP field of CR register</​color> ​                               | 
 +| :::                          | :::                                                        | <color #​22b14c>​ZMOD_REGFLD_CR_TEST_MODE</​color> ​                                      | <color #​22b14c>​5</​color> ​                         | <color #​22b14c>​1</​color> ​                         | <color #​22b14c>​TEST_MODE field of CR register</​color> ​                               |
 | :::                          | :::                                                        | ZMOD_REGFLD_CR_RST ​                                          | 31                         | 1                          | RST field of CR register ​                                   | | :::                          | :::                                                        | ZMOD_REGFLD_CR_RST ​                                          | 31                         | 1                          | RST field of CR register ​                                   |
 | 0x04                         | ZMOD_REG_ADDR_SR ​                                          | ZMOD_REGFLD_SR_TX_DONE ​                                      | 0                          | 1                          | TX_DONE field of SR register ​                               | | 0x04                         | ZMOD_REG_ADDR_SR ​                                          | ZMOD_REGFLD_SR_TX_DONE ​                                      | 0                          | 1                          | TX_DONE field of SR register ​                               |
Line 50: Line 125:
 | <color #​22b14c>​0x40</​color> ​ | <color #​22b14c>​ZMODADC1410_REG_ADDR_SC2HGADDCOEFF </​color> ​ | <color #​22b14c>​ZMODADC1410_REGFLD_SC2HGADDCOEF_VAL</​color> ​ | <color #​22b14c>​0</​color> ​  | <color #​22b14c>​18</​color> ​ | <color #​22b14c>​VAL field of SC2HGADDCOEF register</​color> ​ | | <color #​22b14c>​0x40</​color> ​ | <color #​22b14c>​ZMODADC1410_REG_ADDR_SC2HGADDCOEFF </​color> ​ | <color #​22b14c>​ZMODADC1410_REGFLD_SC2HGADDCOEF_VAL</​color> ​ | <color #​22b14c>​0</​color> ​  | <color #​22b14c>​18</​color> ​ | <color #​22b14c>​VAL field of SC2HGADDCOEF register</​color> ​ |
  
 +==== 4.2.3. Prefabricated functionality ====
 +
 +The functionality described in previous chapter is enough to implement any functionality. Still, the specific Zmod classes will provide functions that implement specific common actions/​tasks,​ to be utilized by the Zmod library users (or even to be taken as an implementation example). These functions solely rely on the above-mentioned functions.
 +**Prefabricated functionality in ZMOD class**
 +  * startDMATransfer – initiates and starts an AXIDMA transfer for a specific length
 +**Prefabricated functionality in ZMODADC1410 class**
 +  * SetTrigger – sets the trigger values for a specific channel, level, edge
 +  * AcquireTriggered_Poll <to be later detailed>​
 +    * sets the acquisition details (trigger, window position)
 +    * starts the acquisition
 +    * waits (by polling) until ZmodADC1410 reports buffer full
 +    * initiates the AXIDMA-S2MM (AXIDMA receive) transfer
 +    * waits (by polling) until AXIDMA-S2MM reports transaction complete
 +    * displays the data over the terminal. As the ADC is on ramp mode, the displayed data can be noticed as consecutive values starting at the trigger level.
 +  * AcquireTriggered_Int <to be later detailed>​
 +    * the interrupts (AXIDMA-S2MM and ZmodADC1410 buffer full) are enabled.
 +    * sets the acquisition details (trigger, window position)
 +    * starts the acquisition
 +    * when the buffer full interrupt is handled, the AXIDMA-S2MM (AXIDMA receive) transfer is initiated.
 +    * when the AXIDMA-S2MM interrupt is handled, an AXIDMA-S2MM complete flag is raised.
 +    * waits (by polling) until AXIDMA-S2MM complete flag is raised
 +    * displays the data over the terminal. As the ADC is on ramp mode, the displayed data can be noticed as consecutive values starting at the trigger level.
 +
 +
 +==== 4.2.4. Zmod IP related functionality ====
 +This chapter details how the [[#​zmod_class|ZMOD class]] accesses the specific Zmod IP core related functionality.
 +Basically, this functionality allows:
 +  * initialization / de-initialization of the IP core
 +  * write and read Zmod registers.
 +This functionality is hardware dependent, as explained in the [[#​hardware_abstraction_implementation|Hardware abstraction implementation]].
 +The functions are declared in the Zmod\reg.h header and are implemented in the Zmod\linux\reg\reg.c and Zmod\baremetal\reg\reg.c source files, corresponding to the linux and baremetal platform.
 +The IP core is identified by its (hardware) base address.
 +The **linux implementation** uses UIO (/​sys/​class/​uio) devices or each IP. The initialization function identifies the right UIO device and maps its address space. The write and read functions use direct (pointer) access to the mapped memory.
 +The **baremetal implementation** uses Xil_Out32 and Xil_In32 functions for the write and read implementations.
 +**Zmod IP interrupt** is handled for baremetal using functionality defined in [[#​dma_related_functionality|DMA related functionality]] (baremetal implementation).
 +**Zmod IP interrupt** is not handled for linux. Polling method is used instead.
 +
 +==== 4.2.5. DMA related functionality ====
 +This chapter details how the [[#​zmod_class|ZMOD class]] accesses the specific AXIDMA related functionality.
 +Basically, this functionality allows:
 +  * initialization / de-initialization of the AXIDMA module.
 +  * transfer in one direction over AXIDMA.
 +  * answer if a (launched) AXIDMA transfer is complete
 +This functionality is hardware dependent, as explained in the [[#​hardware_abstraction_implementation|Hardware abstraction implementation]].
 +The functions are declared in the Zmod\dma.h header and are implemented in the Zmod\linux\dma\dma.c and Zmod\baremetal\dma\dma.c source files, corresponding to the linux and baremetal platform.
 +A DMA instance is identified by its (hardware) base address. FIXME <This is in work, for linux implementation>​. \\
 +The Zmod class stores a pointer to an environment structure that completely identifies a DMA instance (apart from DMA object it also contains transfer buffer and other data).
 +
 +The **linux implementation** uses libaxidma devices for each AXIDMA instance. The initialization function creates the needed axidma environment data: initializes AXIDMA, allocates transfer buffer, associates channel, associates DMA transfer complete handler. ​
 +The DMA transfer function simply calls libaxidma transfer function (axidma_oneway_transfer). When AXIDMA transfer completes, a handler is called which marks the transfer as complete.
 +The **baremetal implementation** uses XAxiDma. The initialization function creates the needed axidma environment data: initializes XAxiDma, allocates transfer buffer, associates DMA transfer complete handler. As a difference to linux approach, it also associates a callback (handler) function for the Zmod IP interrupt. It uses interrupt controller to handle interrupt related functions, therefore intc.h and intc.c source files are included in the Zmod/​baremetal/​intc folder.
 +The DMA transfer function sets the appropriate XAxiDma registers, using the XAxiDma instance base address.
 +
 +
 +====== 5. Project settings ======
 +
 +This chapter details the configuration needed for the baremetal or linux projects.
 +It is assumed that Zmod and specific folders for Zmods (ZmodADC1410 for example) are placed in the SDK workspace root folder.
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +===== 5.1. Linux project =====
 +==== 1. Link Zmod folder ====
 +    * Under src folder, Right Mouse button option New / Folder
 +    * select Advanced
 +    * Link to alternate location (Linked Folder)
 +    * Variables... / Select WORKSPACE_LOC
 +    * Extend... / Select Zmod folder
 +
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​programmable-logic:​eclypse-z7:​zmod6_1_1.png?​500 |}}
 +</​WRAP></​WRAP>​
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +==== 2. For each used Zmod, link its folder. For example, link ZmodADC1410 folder. ====
 +    * Under src folder, Right Mouse button option New / Folder
 +    * select Advanced
 +    * Link to alternate location (Linked Folder)
 +    * Variables... / Select WORKSPACE_LOC
 +    * Extend... / Select ZmodADC1410 folder
 +
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​programmable-logic:​eclypse-z7:​zmod6_1_2.png?​500 |}}
 +</​WRAP>​ </​WRAP> ​
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +==== 3. Define LINUX_APP ====
 +    * In the Project Explorer, right mouse button on the project, “C/C++ Build Settings”
 +    * In the “C/C++ Build” group, select “Settings” category
 +    * Add LINUX_APP definition (using the ‘+’ button)
 +
 +
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​programmable-logic:​eclypse-z7:​zmod6_1_3.png?​500 |}}
 +</​WRAP>​ </​WRAP> ​
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +==== 4. Add SYSROOT Environment variable ====
 +    * In the Project Explorer, right mouse button on the project, “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/​cristian/​eclypse/​os/​build/​tmp/​sysroots/​plnx-zynq7”
 +
 +**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:​programmable-logic:​eclypse-z7:​zmod6_1_4.png?​500 |}}
 +</​WRAP>​ </​WRAP> ​
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +==== 5. 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” category
 +    * Add the following directories:​
 +      * **//​${SYSROOT}/​usr/​include//​**
 +      * **//​${CWD}/​../​../​Zmod//​**
 +      * **//​${CWD}/​../​../​ZmodADC1410//​**
 +
 +
 +
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​programmable-logic:​eclypse-z7:​zmod6_1_5.png?​500 |}}
 +</​WRAP>​ </​WRAP> ​
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +==== 6. Define libraries and library 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++ linker”/​”Libraries” category
 +    * 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:​programmable-logic:​eclypse-z7:​zmod6_1_6.png?​500 |}}
 +</​WRAP>​ </​WRAP> ​
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +==== 7. Add “--sysroot” project setting ====
 +    * 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++ linker”/​”Miscelaneous” category
 +    * In the Linker Flags field add “--sysroot= ${SYSROOT}”
 +
 +
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​programmable-logic:​eclypse-z7:​zmod6_1_7.png?​500 |}}
 +</​WRAP>​ </​WRAP> ​
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +===== 5.2. Baremetal project =====
 +==== 1. Link Zmod folder ====
 +    * Under src folder, Right Mouse button option New / Folder
 +    * Select Advanced
 +    * Link to alternate location (Linked Folder)
 +    * Variables... / Select WORKSPACE_LOC
 +    * Extend... / Select Zmod folder
 +
 +
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​programmable-logic:​eclypse-z7:​zmod6_2_1.png?​500 |}}
 +</​WRAP></​WRAP>​
 +
 +----
 +
 +<WRAP GROUP> <WRAP COLUMN HALF>
 +==== 2. For each used Zmod, link its folder. For example, link ZmodADC1410 folder. ====
 +    * Under src folder, Right Mouse button option New / Folder
 +    * Select Advanced
 +    * Link to alternate location (Linked Folder)
 +    * Variables... / Select WORKSPACE_LOC
 +    * Extend... / Select ZmodADC1410 folder
 +
 +
 +</​WRAP>​ <WRAP COLUMN HALF>
 +{{ :​reference:​programmable-logic:​eclypse-z7:​zmod6_2_2.png?​500 |}}
 +</​WRAP>​ </​WRAP> ​
 +
 +----
 +===== 6. Use cases =====
 +==== 6.1. Use the ZmodLIB with one of the Zmods provided by Digilent (ADC1410 or DACXXXX) ====
 +This use case is similar to the provided demo:
 +- instantiate objects on corresponding class 
 +\\
 +**//​Example://​**
 +<​code>​ZMODADC1410 z1(XPAR_AXI_ZMODADC1410_0_S00_AXI_BASEADDR,​ XPAR_AXI_DMA_0_BASEADDR);</​code>​
 +- call read / write register fields of that Zmod
 +\\
 +**//​Example://​**
 +<​code>​ z1.WriteRegFld(ZMODADC1410_REGFLD_TRIG_LEVEL,​ level);</​code>​
 +- call prefabricated functions:
 +\\
 +**//​Example://​**
 +<​code>​ z1.SetTrigger(channel,​ level, edge);</​code>​
 +
 +==== 6.2. Write module for new Zmod ====
 +  * Create another object class inherited from ZMOD class
 +  * Define specific register / register fields in the header file
 +
 +FIXME   ** Things to be done **
 +
 +- implement object for DAC Zmod (we don’t have an IP yet)\\
 +- document the library and sources\\
 +- other things that for sure will occur\\
 +- test the IPs under different situations\\