Home

User Manual - TEWS TECHNOLOGIES

1. cat proc devices Character devices 1 mem 250 tdrv015drv cat proc iomem 00000000 0000ffff reserved 00010000 0009fbff System RAM fe000000 fe7fffff PCI Bus 0000 02 fe000000 fe7fffff PCI Bus 0000 03 fe000000 fe7fffff PCI Bus 0000 06 fe400000 fe7fffff 0000 06 00 0 fe400000 fe7fffFff TDRVO15 TDRV015 SW 82 Linux Device Driver Page 75 of 75
2. include tdrvOl5api h TDRV0O15_HANDLI hdl TDRV0O15_STATUS result EI unsigned char pBuf pPlb x allocate a 64KB DMA buffer in host RAM result tdrv015GetDmaBuf hdl 0x10000 amp pBuf if result TDRV0O15_OK handle error transfer 64KB data from PLB DDRB to a buffer in host RAM Wait at least 1 second for completion Wi pPlb unsigned char 0x20000000 result tdrv015DmaFpgaToHost hdl pPlb pBuf 0x10000 1000 if result TDRV0O15_OK handle error TDRV015 SW 82 Linux Device Driver Page 49 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID HANDLE The specified device handle is invalid TDRV015_ ERR_INVAL Not a valid SDRAM address range TDRV015 ERR BUSY Unable to gain exclusive access to the DMA controller within the specified time TDRV015_ERR_NOMEM Unable to allocate memory for DMA descriptor list TDRV015_ ERR IO A DMA error has occurred TDRV015_ ERR_TIMEOUT The specified timeout occurred TDRV015 SW 82 Linux Device Driver Page 50 of 75 TEWS amp TECHNOLOGIES 3 4 2 tdrv015DmaHostToFpga NAME tdrv015DmaHostToF pga initiate DMA transfer from PCI bus to FPGA on chip bus SYNOPSIS TDRV015_ STATUS tdrv015DmaHostToFpga TDRV015_ HANDLE hdl unsi
3. TENSES The Embedded I O Company TECHNOLOGIES TDRV015 SW 82 Linux Device Driver Reconfigurable FPGA Version 2 0 x User Manual Issue 2 0 1 August 2015 TEWS TECHNOLOGIES GmbH Am Bahnhof 7 25469 Halstenbek Germany Phone 49 0 4101 40580 Fax 49 0 4101 4058 19 e mail info tews com www tews com TDRV015 SW 82 Linux Device Driver Reconfigurable FPGA Supported Modules TAMC631 TPLDO01 TAMC640 TPLDOO2 TAMC641 TPLDOO3 TAMC651 TPLDO04 TPMC632 TPLDOO5 TENSE TECHNOLOGIES This document contains information which is proprietary to TEWS TECHNOLOGIES GmbH Any reproduction without written permission is forbidden TEWS TECHNOLOGIES GmbH has made any effort to ensure that this manual is accurate and complete However TEWS TECHNOLOGIES GmbH reserves the right to change the product described in this document at any time without notice TEWS TECHNOLOGIES GmbH is not liable for any damage arising out of the application or use of the device described herein 2011 2015 by TEWS TECHNOLOGIES GmbH Issue Date 1 0 0 March 14 2011 1 0 1 Supported Modules added September 30 2011 2 0 0 New API implemented March 7 2012 2 0 1 Include statement in Example Codes corrected August 18 2015 Reference to Engineering Documentation removed TDRV015 SW 82 Linux Device Driver Page 2 of 75 TEWS amp TECHNOLOGIES Table of Contents 1 DIVO UG TO IN WEE 4 2 ene ER a e EN 5 2 1 Build and install the De
4. This function writes the specified number of items to the PCI BAR space by using 32 bit accesses The values are written in big endian order that means on Intel x86 architectures the multi byte data will be byte swapped The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 38 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address PCI Address Type TDRV015 Resource Register 0 MEM TDRV015 RES MEM_1 1 MEM not used TDRV015 RES MEM 2 2 MEM not used TDRV015 RES M
5. result tdrv015ReadBE32 hdl TDRVO15_RES_MEM_1 offset NUM dataBuf if result TDRV0O15_OK handle error TDRV015 SW 82 Linux Device Driver Page 24 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015_ERR_ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 25 of 75 TEWS amp TECHNOLOGIES 3 2 5 tdrv015ReadLE32 NAME tdrv015ReadLE32 read 32 bit values from PCI BAR space in little endian order SYNOPSIS TDRV015_STATUS tdrv015ReadLE32 TDRV015_ HANDLE hdl int pciResource int offset int numltems unsigned int pData DESCRIPTION This function reads the specified number of items from the PCI BAR space by using 32 bit accesses The values are returned as little endian values that means on Intel x86 architectures the multi byte data will not be byte swapped The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the co
6. int threadPriority int stackSize unsigned int interruptMask FUNCINTCALLBACK callbackFunction void funcparam TDRV015_HANDLE pCallbackHandle DESCRIPTION This function registers a user callback function which is executed after detection of the specified interrupt source It is possible to register multiple callback functions to one or a set bit mask of interrupt sources The callback function is executed in a thread context so using TDRV015 device driver functions and system functions is allowed The callback function should be kept as short as possible The specified callback function is executed with the occurred interrupt bits and the specified function parameter as function arguments Additionally a status value is passed to the callback function which reflects the result of the involved API functions The delay between an incoming interrupt and the execution of the callback function is system dependent and is most likely several microseconds PARAMETERS hal This value specifies the device handle to the hardware module retrieved by a call to the corresponding open function threadPriority This parameter specifies the priority to be used for the callback thread Possible values are Value Description TDRV015_ PRIORITY_NORMAL Normal thread priority 0 TDRV015_ PRIORITY_HIGH Higher thread priority 1 TDRV015_ PRIORITY_LOW Lower thread priority 1 Other values might be possible see also Linux PTHREAD d
7. unsigned char dataBuf NUM dataBuf 0 OxAA dataBuf 1 0x55 offset 0x40000 xx write 64KB to the DDRB memory page result tdrv01l5Write8 hdl if result TDRV0O15_OK handle error TDRV015 SW 82 Linux Device Driver TDRV0O15_RE S_ME MI offset NUM dataBuf Page 30 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015 ERR ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 31 of 75 TEWS amp TECHNOLOGIES 3 2 7 tdrv015WriteBE16 NAME tdrv015WriteBE16 write 16 bit values to the PCI BAR space big endian order SYNOPSIS TDRV015_STATUS tdrv015WriteBE16 TDRV015_ HANDLE hdl int pciResource int offset int numlitems unsigned short pData DESCRIPTION This function writes the specified number of items to the PCI BAR space by using 16 bit accesses The values are written in big endian order that means on Intel x86 architectures the multi byte data will be byte swapped The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR sp
8. 3 1 3 tdrv015GetPcilnfo NAME tdrv015GetPcilnfo get information of the module PCI header SYNOPSIS TDRV015_ STATUS tdrv015GetPcilnfo TDRV015_ HANDLE hdl TDRV015_PCIINFO_BUF pPcilnfoBuf DESCRIPTION This function returns information of the module PCI header in the provided data buffer PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pPcilnfoBuf This argument is a pointer to the structure TDRVO15_ PCIINFO_BUF that receives information of the module PCI header typedef struct unsigned short vendorld unsigned short deviceld unsigned short subSystemld unsigned short subSystemVendorld int pciBusNo int pciDevNo int pciFuncNo TDRV015_PCIINFO_BUF vendorld PCI module vendor ID deviceld PCI module device ID TDRV015 SW 82 Linux Device Driver Page 12 of 75 TEWS amp TECHNOLOGIES subSystemld PCI module sub system ID subSystemVendorld PCI module sub system vendor ID pciBusNo Number of the PCI bus where the module resides pciDevNo PCI device number pciFuncNo PCI function number EXAMPLE include tdrv0l5api h TDRV0O15_HANDLE hdl TDRVO15_STATUS result TDRVO15_PCIINFO_BUF pciInfoBuf get module PCI information result tdrv015GetPcilInfo hdl amp pciInfoBuf if result TDRV0O15_OK handle error RETURN VALUE On success TDRV015_
9. items 16 bit to write pData This argument is a pointer to an unsigned short buffer with the data items to write The allocated space must be large enough to hold the specified amount of data EXAMPLE define NUM 0x8000 TDRV0O15_HANDLE hdl include tdrv0l5api h TDRVO15_STATUS result int offset unsigned short dataBuf NUM dataBuf 0 OxAA55 dataBuf 1 0x55AA offset 0x30000 xx write 64KB to the DDRA memory page result tdrv015WriteL E16 hdl if result TDRV0O15_OK handle error TDRV015 SW 82 Linux Device Driver TDRV0O15_RE S _ME MI offset NUM dataBuf Page 36 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015 ERR ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 37 of 75 TEWS amp TECHNOLOGIES 3 2 9 tdrv015WriteBE32 NAME tdrv015WriteBE32 write 32 bit values to the PCI BAR space big endian order SYNOPSIS TDRV015_STATUS tdrv015WriteBE32 TDRV015_ HANDLE hdl int pciResource int offset int numlitems unsigned short pData DESCRIPTION
10. 015_ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015_ERR_ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 16 of 75 TEWS amp TECHNOLOGIES 3 2 2 tdrv015ReadBE16 NAME tdrv015ReadBE16 read 16 bit values from PCI BAR space in big endian order SYNOPSIS TDRV015_STATUS tdrv015ReadBE16 TDRV015_ HANDLE hdl int pciResource int offset int numlitems unsigned short pData DESCRIPTION This function reads the specified number of items from the PCI BAR space by using 16 bit accesses The values are returned as big endian values that mean on Intel x86 architectures the multi byte data will be byte swapped The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RE
11. 5 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 20 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address PCI Address Type TDRV015 Resource Register 0 MEM TDRV015 RES MEM_1 1 MEM not used TDRV015 RES MEM 2 2 MEM not used TDRV015 RES MEM 3 offset This argument specifies the start offset within the PCI BAR space numlitems This argument specifies the number of items 16 bit to read pData This argument is a pointer to an unsigned short buffer which will be filled with the specified number of items from the PCI BAR space The allocated space must be large enough to hold the specified amount of data EXAMPLE include tdrv0l5api h define NUM 0x8000 TDRVO15_HANDLE hdl TDRVO15_STATUS result int offset unsigned short dataBuf NUM offset 0x30000 xx read 64KB from the DDRA memory page Wi result tdrv015ReadLE16 hdl TDRVO15_RES_MEM_1 offset NUM dataBuf if result TDRV0O15_OK
12. ANDLE hdl unsigned char pSrcAddr unsigned char pDestAddr unsigned int numBytes int timeout DESCRIPTION This function initiates a DMA transfer from a FPGA on chip bus resource e g SDRAM banks to the PCI bus of the host system by using the DMA controller of the infrastructure module Depending on the timeout parameter the function will be blocked until the transfer has finished or the function returns immediately after starting the transfer PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pSrcAddr This argument specifies a valid 32 bit DMA source start address in the FPGA on chip bus space e g SDRAM bank pDestAdar This argument specifies a valid 32 bit DMA destination start address in the host PCI bus space e g host RAM space The destination address must be a valid PCI bus address To allocate a DMA buffer in the host RAM the function tdrv015GetDmaBuf should be used numBytes This argument specifies the number of bytes to transfer TDRV015 SW 82 Linux Device Driver Page 48 of 75 TEWS amp TECHNOLOGIES timeout This value specifies the timeout in milliseconds the user is willing to wait for this operation to complete The granularity depends on the used operating system Specify O to return immediately after initiating the DMA transfer without aborting it Specify 1 to wait indefinitely for completion EXAMPLE
13. ATUS result int offset unsigned int dataBuf NUM offset 0 read all registers from the control component ey result tdrv015ReadLE32 hdl TDRVO15_RES_MEM_1 offset NUM dataBuf if result TDRV0O15_OK handle error TDRV015 SW 82 Linux Device Driver Page 27 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015_ERR_ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 28 of 75 TEWS amp TECHNOLOGIES 3 2 6 tdrv015Write8 NAME tdrv015Write8 write 8 bit values to the PCI BAR space SYNOPSIS TDRV015_STATUS tdrv015Write8 TDRV015_ HANDLE hdl int pciResource int offset int numlitems unsigned char pData DESCRIPTION This function writes the specified number of items to the PCI BAR space by using single byte 8 bit accesses The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the correspo
14. EM 3 offset This argument specifies the start offset within the PCI BAR space numlitems This argument specifies the number of items 32 bit to write pData This argument is a pointer to an unsigned short buffer with the data items to write The allocated space must be large enough to hold the specified amount of data EXAMPLE include tdrv0l5api h TDRVO15_HANDLE hdl TDRVO15_STATUS result int offset unsigned int data data 0x10020000 PLB DDRA address space offset 0x20004 memory controller device register ik adjust the selected memory page from DDRA to 0x10020000 by setting the DDRA memory address register in the memory controller device WI result tdrv015WriteBE32 hdl TDRVO15_RES_MEM_ TI offset 1 amp data if result TDRV0O15_OkK handle error TDRV015 SW 82 Linux Device Driver Page 39 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015_ERR_ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 40 of 75 TEWS amp TECHNOLOGIES 3 2 10 tdrv015Wri
15. ESCRIPTION This function returns the status of the DMA controller namely if a transfer is in progress or if an error has occurred This function can be used to check if a DMA transfer has already been completed An occurred error is cleared after execution of this function PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pDmaStatus This argument is a pointer to an unsigned int buffer where the status of the DMA controller is returned Possible values are Value Description TDRV015_ DMASTAT_READY DMA controller is ready for a new transfer TDRV015_DMASTAT_BUSY DMA controller is busy with a transfer TDRV015_ DMASTAT_ ERROR An error has occurred during the last DMA transfer TDRV015 SW 82 Linux Device Driver Page 54 of 75 TEWSS amp TECHNOLOGIES EXAMPLE include tdrv0l5api h TDRVO15_HANDLE hdl TDRV0O15_STATUS result unsigned int dmaStatus get status of DMA controller result tdrv015DmaGetStatus hdl amp dmaStatus if result TDRV0O15_OK handle error RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ERR_INVALID_ HANDLE The specified device handle is invalid TDRV015 SW 82 Linux Device Driver Page 55 of 75 TEWS amp TECHN
16. EXAMPLE define NUM 0x8000 TDRV0O15_HANDLE hdl include tdrv0l5api h TDRVO15_STATUS result int offset unsigned short dataBuf NUM dataBuf 0 OxAA55 dataBuf 1 0x55AA offset 0x30000 xx write 64KB to the DDRA memory page result tdrv0O15WriteB E16 hdl if result TDRV0O15_OK handle error TDRV015 SW 82 Linux Device Driver TDRV0O15_RE S _ME MI offset NUM dataBuf Page 33 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015_ERR_ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 34 of 75 TEWS amp TECHNOLOGIES 3 2 8 tdrv015WriteLE16 NAME tdrv015WriteLE16 write 16 bit values to the PCI BAR space in little endian order SYNOPSIS TDRV015_STATUS tdrv015WriteLE16 TDRV015_ HANDLE hdl int pciResource int offset int numlitems unsigned short pData DESCRIPTION This function writes the specified number of items to the PCI BAR space by using 16 bit accesses The values are written in little endian order that means o
17. MA memory depends on the specific system environment PARAMETERS hdl This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function size This argument specifies the number of bytes to allocate pPtr This argument is a pointer to an unsigned char pointer that receives the start address of the DMA buffer TDRV015 SW 82 Linux Device Driver Page 58 of 75 TEWS amp TECHNOLOGIES EXAMPLE include tdrv0l5api h TDRVO15_HANDLE hdl TDRV0O15_STATUS result unsigned char pBuf allocate a 2MB DMA buffer in host RAM result tdrv015GetDmaBuf hdl 0x00200000 amp pBuf if result TDRV0O15_OK handle error RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_HANDLE The specified device handle is invalid TDRV015 ERR NOMEM Unable to allocate memory TDRV015 SW 82 Linux Device Driver Page 59 of 75 TEWS amp TECHNOLOGIES 3 4 6 tdrv015FreeDmaBuf NAME tdrv015FreeDmaBuf free previously allocated DMA buffer SYNOPSIS TDRV015_STATUS tdrv015FreeDmaBuf TDRV015_ HANDLE hdl unsigned char pPtr DESCRIPTION This function frees a DMA buffer which was previously allocated with tdrv015GetDmaBuf PARAMETERS hal This argument specifies the device handle to the h
18. OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_ HANDLE The specified device handle is invalid TDRV015 SW 82 Linux Device Driver Page 13 of 75 TEWSS amp TECHNOLOGIES 3 2 Device Access Functions 3 2 1 tdrv015Read8 NAME tdrv015Read8 read 8 bit values from PCI BAR space SYNOPSIS TDRV015_STATUS tdrv015Read8 TDRV015_ HANDLE hdl int pciResource int offset int numlitems unsigned char pData DESCRIPTION This function reads the specified number of items from the PCI BAR space by using single byte 8 bit accesses The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM E Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory ar
19. OLOGIES 3 4 4 tdrv015DmaStop NAME tdrv015DmaStop abort an active DMA transfer SYNOPSIS TDRV015_ STATUS tdrv015DmaStop TDRV015_ HANDLE hdl DESCRIPTION This function aborts an active DMA transfer and causes a reset of the DMA controller PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function EXAMPLE include tdrv0l5api h TDRVO15_HANDLE hdl TDRVO15_STATUS result stop DMA transfer 7 result tdrv015DmaStop hdl if result TDRV015_0K handle error TDRV015 SW 82 Linux Device Driver Page 56 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_HANDLE The specified device handle is invalid TDRV015 SW 82 Linux Device Driver Page 57 of 75 TEWS amp TECHNOLOGIES 3 4 5 tdrv015GetDmaBuf NAME tdrv015GetDmaBuf allocate DMA buffer in host RAM SYNOPSIS TDRV015_STATUS tdrv015GetDmaBuf TDRV015_ HANDLE hdl unsigned int size unsigned char pPtr DESCRIPTION This function allocates the specified amount of non cached PCI bus accessible memory in the Host RAM The allocated memory can be freed with the function tdrv015FreeDmaBuf The maximum amount of contiguous D
20. S MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 17 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address PCI Address Type TDRV015 Resource Register 0 MEM TDRV015 RES MEM_1 1 MEM not used TDRV015 RES MEM 2 2 MEM not used TDRV015 RES MEM 3 offset This argument specifies the start offset within the PCI BAR space numlitems This argument specifies the number of items 16 bit to read pData This argument is a pointer to an unsigned short buffer which will be filled with the specified number of items from the PCI BAR space The allocated space must be large enough to hold the specified amount of data EXAMPLE include tdrv0l5api h define NUM 0x8000 TDRVO15_HANDLE hdl TDRVO15_STATUS result int offset unsigned short dataBuf NUM offset 0x30000 xx read 64KB from the DDRA memory page Wi result tdrv015ReadBE16 hdl TDRVO15_RES_MEM_1 offset NUM dataBuf if result TDRV0O15_OkK handle error TDRV015 SW 82 Linux Device Driver Page 18 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is r
21. V015 SW 82 Linux Device Driver Page 70 of 75 TEWS amp TECHNOLOGIES 3 6 Endian Conversion Functions The following conversion functions can be used to develop endian neutral software especially for direct access to mapped PCI resources 3 6 1 endian_be16 NAME endian_be16 big endian conversion function SYNOPSIS unsigned short endian_be16 unsigned short u16value DESCRIPTION This function converts a short integer value 16 bit from the native CPU endian order to big endian order That means on Intel x86 architectures the value will be byte swapped as opposed to PowerPC architectures PARAMETERS u1l6value This argument specifies the data to convert EXAMPLE include tdrv0Ol5api h unsigned short pRawData bigEndianData setup pRawData pointer to the correct location first bigEndianData endian_bel6 pRawData RETURN VALUE This function returns the passed value in the big endian order TDRV015 SW 82 Linux Device Driver Page 71 of 75 TEWS amp TECHNOLOGIES 3 6 2 endian_le16 NAME endian_le16 little endian conversion function SYNOPSIS unsigned short endian_le16 unsigned short u16value DESCRIPTION This function converts a short integer value 16 bit from the native CPU endian order to little endian order That means on PowerPC architectures the value will be byte swapped as opposed to Intel x86 architectures PARAMETERS ul6valu
22. ace PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 32 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address Register 0 MEM 1 MEM n 2 MEM n offset PCI Address Type ot used ot used TDRV015 Resource TDRV015_RES_MEM_1 TDRV015_RES_MEM_2 TDRV015_RES_MEM_3 This argument specifies the start offset within the PCI BAR space numitems This argument specifies the number of items 16 bit to write pData This argument is a pointer to an unsigned short buffer with the data items to write The allocated space must be large enough to hold the specified amount of data
23. alid TDRV015_ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015_ERR_ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 43 of 75 TEWS amp TECHNOLOGIES 3 3 Resource Mapping Functions 3 3 1 tdrv015PciResourceMap NAME tdrv015PciResourceMap map a PCI resource directly into the process context SYNOPSIS TDRV015_ STATUS tdrv015PciResourceMap TDRV015_HANDLE hdl int pciResource unsigned char pPtr unsigned int pSize DESCRIPTION This function maps the specified PCI resource of the hardware module directly into the process context The retrieved pointer can be used for direct non cached register access PARAMETERS hdl This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015_RES_MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM E Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area The Base Address Register usage is programmable and can be changed by modify
24. api h TDRVO15_HANDLI hdl TDRVO15_STATUS result unsigned char pBuf pPlb PI allocate a 2MB DMA buffer in host RAM result tdrv015GetDmaBuf hdl 0x00200000 amp pBuf if result TDRVO015_OK handle error fill data buffer transfer 2MB data from host RAM to PLB DDRA Wait up to 10 seconds for completion Wi pPlb unsigned char 0x10000000 result tdrv015DmaHostToFpga hdl pBuf pPlb 0x00200000 if result TDRV0O15_OK handle error 10000 TDRV015 SW 82 Linux Device Driver Page 52 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015 ERR_INVALID_ HANDLE The specified device handle is invalid TDRV015_ ERR_INVAL Not a valid SDRAM address range TDRV015 ERR BUSY Unable to gain exclusive access to the DMA controller within the specified time TDRV015_ ERR NOMEM Unable to allocate memory for DMA descriptor list TDRV015 ERR IO A DMA error has occurred TDRV015 ERR_TIMEOUT The specified timeout occurred TDRV015 SW 82 Linux Device Driver Page 53 of 75 TEWS amp TECHNOLOGIES 3 4 3 tdrv015DmaGetStatus NAME tdrv015DmaGetStatus read the status of the DMA controller SYNOPSIS TDRV015_ STATUS tdrv015DmaGetStatus TDRV015_ HANDLE hdl unsigned int pDmaStatus D
25. ardware module retrieved by a call to the corresponding open function pPtr This argument is a pointer to the buffer to free EXAMPLE include tdrv0l5api h TDRV0O15_HANDLE hdl TDRVO15_STATUS result unsigned char pBuf result tdrv015FreeDmaBuf hdl pBuf if result TDRV0O15_OkK handle error TDRV015 SW 82 Linux Device Driver Page 60 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_HANDLE The specified device handle is invalid TDRV015 SW 82 Linux Device Driver Page 61 of 75 TEWS amp TECHNOLOGIES 3 5 Interrupt Functions 3 5 1 tdrv015InterruptWait NAME tdrv015InterruptWait Wait for incoming Local Interrupt Source SYNOPSIS TDRV015_ STATUS tdrv015interruptW ait TDRV015_ HANDLE hdl unsigned int interruptMask unsigned int plnterruptOccurred int timeout P DESCRIPTION This function enables the specified local interrupt sources and waits for interrupts on the specified local interrupt sources After an interrupt has arrived the corresponding occurred local interrupt source is disabled inside the Infrastructure Module IM Multiple functions may wait for the same interrupt source to occur The delay between an incoming interrupt and the return of the
26. ation it is possible to define a major number for the driver To change the major number edit the file tdrv015def h change the following symbol to appropriate value and enter make install to create a new driver TDRV015_ MAJOR Valid numbers are in range between 0 and 255 A value of 0 means dynamic number allocation Example define TDRV015_ MAJOR 122 Be sure that the desired major number isn t used by other drivers Please check proc devices to see which numbers are free TDRV015 SW 82 Linux Device Driver Page 7 of 75 TEWS amp TECHNOLOGIES 3 API Documentation 3 1 General Functions 3 1 1 tdrv015Open NAME tdrv015Open open a device SYNOPSIS TDRV015_HANDLE tdrv015Open char DeviceName DESCRIPTION Before I O can be performed to a device a device handle must be opened by a call to this function If the legacy TDRV015 driver is used this function will also install the legacy driver and create devices with the first call The VxBus TDRV015 driver will be installed automatically by the VxBus system The tdrv015Open function can be called multiple times e g in different tasks PARAMETERS DeviceName This parameter points to a null terminated string that specifies the name of the device The first TDRV015 device is named dev tdrv015_0 the second device is named dev tdrv015_1 and so on EXAMPLE include tdrv0l5api h TDRV015_HANDLE hdl open t
27. configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address PCI Address Type TDRV015 Resource Register 0 MEM TDRV015 RES MEM_1 1 MEM not used TDRV015 RES MEM 2 2 MEM not used TDRV015 RES MEM 3 offset This argument specifies the start offset within the PCI BAR space numlitems This argument specifies the number of items 32 bit to write pData This argument is a pointer to an unsigned short buffer with the data items to write The allocated space must be large enough to hold the specified amount of data EXAMPLE include tdrv0l5api h TDRVO15_HANDLE hdl TDRVO15_STATUS result int offset unsigned int data data 0x10020000 PLB DDRA address space offset 0x20004 memory controller device register ik adjust the selected memory page from DDRA to 0x10020000 by setting the DDRA memory address register in the memory controller device WI result tdrv01l5WriteLE32 hdl TDRVO15_RES_MEM_1 offset 1 amp data if result TDRV0O15_OkK handle error TDRV015 SW 82 Linux Device Driver Page 42 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ERR_INVALID_HANDLE The specified device handle is inv
28. described function is system dependent and is most likely several microseconds If a faster response lower interrupt latency to an interrupt request is required an interrupt callback function Fehler Verweisquelle konnte nicht gefunden werden should be installed to handle the interrupt PARAMETERS hal This value specifies the device handle to the hardware module retrieved by a call to the corresponding open function interruptMask This parameter specifies specific interrupt bits to wait for The interrupt bits correspond to the Infrastructure Module s Interrupt Pending Register bits described in the FDK user manual Please refer to the hardware user manual for further information on the possible interrupt bits The function returns if at least one of the specified interrupt sources is detected TDRV015 SW 82 Linux Device Driver Page 62 of 75 TEWS amp TECHNOLOGIES plnterruptOccurred If at least one of the specified interrupt sources occurs the value is returned through this pointer The interrupt bits correspond to the Infrastructure Module s Interrupt Pending Register bits described in the FDK user manual Please refer to the hardware user manual for further information on the possible interrupt bits timeout This value specifies the timeout in milliseconds the function will wait for the interrupt to arrive The granularity depends on the operating system To wait indefinitely specify 1 as timeout
29. e This argument specifies the data to convert EXAMPLE include tdrv0l5api h unsigned short pRawData littleEndianData setup pRawData pointer to the correct location first littleEndianData endian_lel6 pRawData RETURN VALUE This function returns the passed value in the little endian order TDRV015 SW 82 Linux Device Driver Page 72 of 75 TEWS amp TECHNOLOGIES 3 6 3 endian_be32 NAME endian_be32 big endian conversion function SYNOPSIS unsigned int endian_be32 unsigned short u32value DESCRIPTION This function converts an integer value 32 bit from the native CPU endian order to big endian order That means on Intel x86 architectures the value will be byte swapped as opposed to PowerPC architectures PARAMETERS u32value This argument specifies the data to convert EXAMPLE include tdrv0l5api h unsigned short pRawData bigEndianData setup pRawData pointer to the correct location first bigEndianData endian_be32 pRawData RETURN VALUE This function returns the passed value in the big endian order TDRV015 SW 82 Linux Device Driver Page 73 of 75 TEWS amp TECHNOLOGIES 3 6 4 endian_le32 NAME endian_le32 little endian conversion function SYNOPSIS unsigned short endian_le32 unsigned short u32value DESCRIPTION This function converts an integer value 32 bit from the nativ
30. e CPU endian order to little endian order That means on PowerPC architectures the value will be byte swapped as opposed to Intel x86 architectures PARAMETERS u32value This argument specifies the data to convert EXAMPLE include tdrv0l5api h unsigned short pRawData littleEndianData setup pRawData pointer to the correct location first littleEndianData endian_le32 pRawData RETURN VALUE This function returns the passed value in the little endian order TDRV015 SW 82 Linux Device Driver Page 74 of 75 TENSE TECHNOLOGIES 4 Diagnostic If the TDRV015 does not work properly it is helpful to get some status information from the driver respective kernel The Linux proc file system provides information about kernel resources driver devices and so on The following screen dumps displays information of a correct running TDRV015 driver see also the proc man pages lspci v 06 00 0 Bridge TEWS Technologies GmbH Device 8277 Subsystem TEWS Technologies GmbH Device 8277 Flags bus master fast devsel latency 0 IRQ 17 Memory at fe400000 32 bit non prefetchable size 4M Capabilities 40 Power Management version 3 Capabilities 48 Message Signalled Interrupts Mask 64bit Queue 0 0 Enable Capabilities 58 Express Endpoint MSI 00 Kernel driver in use TEWS TECHNOLOGIES TDRVO15 Device Driver Kernel modules tdrv015drv
31. e function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_ HANDLE The specified TDRV015_ HANDLE is invalid TDRV015_ ERR_INVAL Function or callback handle pointer is NULL TDRV015 ERR _NODEV Failed to allocate a callback handle TDRV015 ERR TASK CREATE Creation of the callback thread task failed TDRV015 SW 82 Linux Device Driver Page 68 of 75 TEWS amp TECHNOLOGIES 3 5 3 tdrv015InterruptUnregisterCallback NAME tdrv015InterruptUnregisterCallback Unregister a User Callback Function SYNOPSIS TDRV015_ STATUS tdrv015interruptUnregisterCallback TDRV015_HANDLE hdl DESCRIPTION This function unregisters a previously registered user callback thread or ISR function PARAMETERS hal This value specifies the callback handle retrieved by a call to the corresponding register function EXAMPLE include tdrv0l5api h TDRVO15_HANDLE callbackHdl TDRVO15_STATUS result Je Unregister a callback function Wi result tdrv015InterruptUnregisterCallback callbackHdl if result TDRV0O15_OK OK else handle error TDRV015 SW 82 Linux Device Driver Page 69 of 75 TEWSS amp TECHNOLOGIES RETURNS On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID HANDLE The specified callback handle is invalid TDR
32. ea TDRV015 SW 82 Linux Device Driver Page 14 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address PCI Address Type TDRV015 Resource Register 0 MEM TDRV015 RES MEM_1 1 MEM not used TDRV015 RES MEM 2 2 MEM not used TDRV015 RES MEM 3 offset This argument specifies the start offset within the PCI BAR space numlitems This argument specifies the number of items 8 bit to read pData This argument is a pointer to an unsigned char buffer which will be filled with the specified number of items from the PCI BAR space The allocated space must be large enough to hold the specified amount of data EXAMPLE include tdrv0l5api h define NUM 0x10000 TDRVO15_HANDLE hdl TDRVO15_STATUS result int offset unsigned char dataBuf NUM offset 0x30000 read 64KB from the DDRA memory page Wi result tdrv015Read8 hdl TDRVO15_RES_ MEM 1 offset NUM dataBuf if result TDRV0O15_OK handle error TDRV015 SW 82 Linux Device Driver Page 15 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error code Description TDRV
33. er independent library include tpmodule h Driver independent library header file include tpxxxhwdep h HAL library header file include tpxxxhwdep c HAL library source file In order to perform an installation extract all files of the archive TDRV015 SW 82 SRC tar gz to the desired target directory The command tar xzvf TDRV015 SW 82 SRC tar gz will extract the files into the local directory e Login as root and change to the target directory e Copy tdrv015 h to usr include 2 1 Build and install the Device Driver e Login as root e Change to the target directory e To create and install the driver in the module directory ib modules lt version gt misc enter make install e To update the device driver s module dependencies enter depmod aq TDRV015 SW 82 Linux Device Driver Page 5 of 75 TEWS amp TECHNOLOGIES 2 2 Uninstall the Device Driver e Login as root e Change to the target directory e To remove the driver from the module directory lib modules lt version gt misc enter make uninstall 2 3 Install Device Driver into the running Kernel e To load the device driver into the running kernel login as root and execute the following commands modprobe tdrv015drv e After the first build or if you are using dynamic major device allocation it is necessary to create new device nodes on the file system Please execute the script file makenode to do this If your kernel has enabled a device file sy
34. esenteeyenedereescencits a a aa aa aa a aa a 41 3 3 Resource Mapping Functions sccccccseceeeeeeeeeeeeeeeeeeeeneesesesneeseeenneeseeenneeseeesneeseseseeeseseseeeseeeenes 44 3 3 1 tdrvO TOPCIRESOUCE MAD saneescaccccssnacetinaraacvedtaancanadhancvceupabduncehannvcdbnaxeatellhanivcehsancetcenannrednans 44 3 3 2 tdrvO 1 Dbcibesourcellnmap tenisie anesi nad raniad aaeei aaaea 46 3 4 DMA Fun Gtiois sasiss iieccces ce cdsesae ounces esctcvaduccccdetcvacavencude ieutcuatavucuncsstes soudexeGeccconcs suetevucedouanassvevcuenecctse 48 3 4 1 mt 1SDmaF pgal OHOS Tsaa aa a aS 48 3 4 2 TOrVO1 SDMAH OST lee EE 51 3 4 3 elo 15D Ma Get EE 54 3 4 4 TOPVO1 SDMAStOp EE 56 3 4 5 TArVOT5 Get DMB Ub EE 58 3 4 6 TOrVOTSFre DIMAB UT igisi annaa aaae ai aaia 60 3 5 Iimerrupt Functions inns ccc cies seed cscs secs ces eed cneta cee sets dec euttncencentdccucnntadie 62 3 5 1 tdrvO 1 SINterruptWy TEE 62 3 5 2 Wlrv Blnterruptbiegietertallback Thread 65 3 5 3 tdrv0 15InterruptUnregisterCallack cccceccceceeeceeeeeeeeeeseeeeeseaeeeeaeeseneeeseaeessaeeeeneeeeaees 69 3 6 Endian Conversion Functions cccccesssssssceeceeeensnnsscaneeseeeensnnasceeeeseeesnsensacoeseseesennensanonsenees 71 3 6 1 endian DOM EE 71 3 6 2 endian le KE 72 3 6 3 endian DOS EE 73 3 6 4 endian BT 74 4 er Lan le 75 TDRV015 SW 82 Linux Device Driver Page 3 of 75 TEWS amp TECHNOLOGIES 1 Introduction The TDRV015 SW 82 Linux device driver allows the o
35. eturned In the case of an error the appropriate error code is returned by the function ERROR CODES Error code Description TDRV015_ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015_ERR_ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 19 of 75 TEWS amp TECHNOLOGIES 3 2 3 tdrv015ReadLE16 NAME tdrv015ReadLE16 read 16 bit values from PCI BAR space in little endian order SYNOPSIS TDRV015_STATUS tdrv015ReadLE16 TDRV015_ HANDLE hdl int pciResource int offset int numlitems unsigned short pData DESCRIPTION This function reads the specified number of items from the PCI BAR space by using 16 bit accesses The values are returned as little endian values that means on Intel x86 architectures the multi byte data will not be byte swapped The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV01
36. gned char pSrcAddr unsigned char pDestAddr unsigned int numBytes int timeout DESCRIPTION This function initiates a DMA transfer from the PCI bus of the host system to a FPGA on chip bus resource e g SDRAM banks by using the DMA controller of the infrastructure module Depending on the timeout parameter the function will be blocked until the transfer has finished or the function returns immediately after starting the transfer PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pSrcAddr This argument specifies a valid 32 bit DMA source start address in the host PCI bus space e g host RAM space The destination address must be a valid PCI bus address To allocate a DMA buffer in the host RAM the function tdrv015GetDmaBuf should be used pDestAdadr This argument specifies a valid 32 bit DMA destination start address in the FPGA on chip bus space e g SDRAM bank numBytes This argument specifies the number of bytes to transfer timeout This value specifies the timeout in milliseconds the user is willing to wait for this operation to complete The granularity depends on the used operating system Specify O to return immediately after initiating the DMA transfer without aborting it Specify 1 to wait indefinitely for completion TDRV015 SW 82 Linux Device Driver Page 51 of 75 TEWSS TECHNOLOGIES EXAMPLE include tdrv0l5
37. handle error TDRV015 SW 82 Linux Device Driver Page 21 of 75 TEWS amp TECHNOLOGIES RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ERR_INVAL The specified access range exceeds PCI BAR limits TDRV015_ERR_ACCESS The specified PCI resource is not available TDRV015 SW 82 Linux Device Driver Page 22 of 75 TEWS amp TECHNOLOGIES 3 2 4 tdrv015ReadBE32 NAME tdrv015ReadBE32 read 32 bit values from PCI BAR space in big endian order SYNOPSIS TDRV015_STATUS tdrv015ReadBE32 TDRV015_ HANDLE hdl int pciResource int offset int numltems unsigned int pData DESCRIPTION This function reads the specified number of items from the PCI BAR space by using 32 bit accesses The values are returned as big endian values that means on Intel x86 architectures the multi byte data will be byte swapped The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In genera
38. he specified devic hdl tdrv0150pen dev tdrv015_0 TDRV015 SW 82 Linux Device Driver Page 8 of 75 TEWS amp TECHNOLOGIES if hdl NULL handle open error RETURNS A device handle or NULL if the function fails An error code will be stored in errno ERROR CODES The error codes are stored in errno The error code is a standard error code set by the I O system TDRV015 SW 82 Linux Device Driver Page 9 of 75 TEWS amp TECHNOLOGIES 3 1 2 tdrv015Close NAME tdrvO15Close close a device SYNOPSIS TDRV015_ STATUS tdrv015Close TDRV015_HANDLE hdl DESCRIPTION This function closes a previously opened device PARAMETERS hal This value specifies the device handle to the hardware module retrieved by a call to the corresponding open function EXAMPLE include tdrv0l5api h TDRVO15_HANDLE hdl TDRV0O15_STATUS result close the device Wi result tdrv015Close hdl if result TDRVO15_OK handle close error TDRV015 SW 82 Linux Device Driver Page 10 of 75 TEWS amp TECHNOLOGIES RETURNS On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_HANDLE The specified device handle is invalid TDRV015 SW 82 Linux Device Driver Page 11 of 75 TEWS amp TECHNOLOGIES
39. ing the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used TDRV015 SW 82 Linux Device Driver Page 44 of 75 TENSE TECHNOLOGIES PCI Base Address PCI Address Type TDRV015 Resource Register 0 MEM TDRV015 RES MEM_1 1 MEM not used TDRV015 RES MEM_2 2 MEM not used TDRV015 RES MEM 3 pPtr This argument is a pointer to an unsigned char pointer that receives the start address of the mapped PCI resource pSize This argument returns the size of the mapped PCI resource in bytes EXAMPLE include tdrv0l5api h TDRVO15_HANDLE hdl TDRVO15_STATUS result unsigned char pReg unsigned int size map first memory PCI resource RI result tdrv015PciResourceMap hdl TDRVO15_RES_ MEM 1 amp pReg amp size if result TDRV0O15_OkK handle error RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015 ERR_INVALID HANDLE The specified device handle is invalid TDRV015 ERR ACCESS Specified PCI resource not available TDRV015 ERR NOMEM Unable to allocate memory TDRV015 SW 82 Linux Device Driver Page 45 of 75 TEWS amp 3 3 2 tdrv015PciResourceUnmap NAME tdrv015PciResourceUnmap unmap a previously mapped PCI resource SYNOPSIS TDRV015_ STATUS tdrv015PciResourceUnma
40. l a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 23 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address PCI Address Type TDRV015 Resource Register 0 MEM TDRV015 RES MEM_1 1 MEM not used TDRV015 RES MEM 2 2 MEM not used TDRV015 RES MEM 3 offset This argument specifies the start offset within the PCI BAR space numlitems This argument specifies the number of items 32 bit to read pData This argument is a pointer to an unsigned int buffer which will be filled with the specified number of items from the PCI BAR space The allocated space must be large enough to hold the specified amount of data EXAMPLE include tdrv0l5api h define NUM 4 TDRVO15_HANDLE hdl TDRVO15_STATUS result int offset unsigned int dataBuf NUM offset 0 read all registers from the control component ey
41. n Intel x86 architectures the multi byte data will not be byte swapped The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 35 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address Register 0 MEM 1 MEM n 2 MEM n offset PCI Address Type ot used ot used TDRV015 Resource TDRV015_RES_MEM_1 TDRV015_RES_MEM_2 TDRV015_RES_MEM_3 This argument specifies the start offset within the PCI BAR space numitems This argument specifies the number of
42. nding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 29 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address PCI Address Type Register 0 MEM 1 MEM not used 2 MEM not used offset TDRV015 Resource This argument specifies the start offset within the PCI BAR space numitems This argument specifies the number of items 8 bit to write pData TDRV015_RES_MEM_1 TDRV015_RES_MEM_2 TDRV015_RES_MEM_3 This argument is a pointer to an unsigned char buffer with the data items to write The allocated space must be large enough to hold the specified amount of data EXAMPLE include tdrv0l5api h define NUM 0x10000 TDRV0O15_HANDLE hdl TDRVO15_STATUS result int offset
43. ocumentation TDRV015 SW 82 Linux Device Driver Page 65 of 75 TEWS amp TECHNOLOGIES stackSize This parameter specifies the stack size to be used for the callback thread The value is specified in bytes interruptMask This parameter specifies specific interrupt bits to wait for The interrupt bits correspond to the Infrastructure Module s Interrupt Pending Register bits described in the FDK user manual Please refer to the hardware user manual for further information on the possible interrupt bits The callback function is executed if at least one of the specified interrupt sources occurred callbackFunction This parameter is a function pointer to the user callback function The callback function pointer is defined as follows typedef void FUNCINTCALLBACk TDRV015_ HANDLE hdl unsigned int interruptOccurred void param TDRV015 STATUS status hal This parameter specifies a device handle which can be used for hardware access or other API functions by the callback function interruptOccurred This parameter is a 32bit value reflecting the occurred interrupts It is useful if the callback function handles multiple interrupt sources The interrupt bits correspond to the Infrastructure Module s Interrupt Pending Register bits described in the FDK user manual Please refer to the hardware user manual for further information on the possible interrupt bits param This parameter is the user specified f
44. oid param TDRVO15_STATUS status Register callback function for TIMERO UINTPO ik Use a normal priority and 64KB stack interruptMask 1 lt lt 16 result tdrv015InterruptRegisterCallbackThread hdl TDRVO15_PRIORITY_NORMAL 0x10000 interruptMask callback_TIMERO amp userDataArea amp callbackHandle if result TDRV0O15_OK handle error Initialize and start the Timer function using register accesses Refer to the FDK documentation for register description TDRV015 SW 82 Linux Device Driver Page 67 of 75 TEWS amp TECHNOLOGIES Callback Function using API Functions for Register Access void callback_TIMERO TDRV015_HANDLE hdl unsigned int interruptOccurred void param TDRVO15_STATUS status TDRVO15_ STATUS result USER_DATA_AREA pUsrData USER_DATA_AREA param unsigned int u32value if status TDRVO15_OK handle error status printf Timer 0 Interrupt n Acknowledge TIMERO interrupt source by writing to xx Timer Based Interrupt Status Register offset may differ u32value 1 lt lt 0 result tdrv015WriteBE32 hdl TDRVO15_RES_MEM_1 0x1002C 1 amp u32value handle errors return RETURNS On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by th
45. p TDRV015_HANDLE hdl unsigned char pPtr DESCRIPTION This function unmaps a previously mapped PCI resource freeing the system resources used for this mapping PARAMETERS hdl This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pPtr This argument is a pointer to an unsigned char pointer that represents the start address of the previously mapped PCI resource This pointer must have been received from the corresponding mapping function TDRV015 SW 82 Linux Device Driver Page 46 of 75 TEWSS amp TECHNOLOGIES EXAMPLE include tdrv0l5api h TDRVO15_HANDLE hdl TDRV0O15_STATUS result unsigned char pReg unmap a previously mapped PCI resource result tdrv015PciResourceUnmap hdl pReg if result TDRV0O15_OK handle error RETURN VALUE On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_HANDLE The specified device handle is invalid TDRV015_ ERR_INVAL Invalid pointer specified TDRV015 SW 82 Linux Device Driver Page 47 of 75 TEWSS TECHNOLOGIES 3 4 DMA Functions 3 4 1 tdrv015DmaFpgaToHost NAME tdrv015DmaFpgaToHost initiate DMA transfer from FPGA on chip bus to host PCI bus SYNOPSIS TDRV015_ STATUS tdrv015DmaFpgaToHost TDRV015_ H
46. parameter EXAMPLE include tdrv0Ol5api h TDRVO15_HANDLI hdl TDRVO15_ STATUS result Gl unsigned int interruptMask unsigned int interruptOccurred xx Wait at least 5 seconds for incoming interrupts on UINTPO and or UINTP1 Wi interruptMask 1 lt lt 17 1 lt lt 16 result tdrv01l5InterruptWait hdl interruptMask amp interruptOccurred 5000 if result TDRV0O15_OK Interrupt arrived Se Now acknowledge interrupt source in FPGA logic K to clear the Local Interrupt Source Use tdrv015Read and tdrv015Write functions for register access KC else handle error TDRV015 SW 82 Linux Device Driver Page 63 of 75 TEWS amp TECHNOLOGIES RETURNS On success TDRV015_OK is returned In the case of an error the appropriate error code is returned by the function ERROR CODES Error Code Description TDRV015_ ERR_INVALID_ HANDLE The specified TDRV015 HANDLE is invalid TDRV015_ERR_NORESOURCE Failed to allocate resources for the wait job TDRV015_ ERR_TIMEOUT The specified timeout occurred TDRV015 SW 82 Linux Device Driver Page 64 of 75 TEWS amp TECHNOLOGIES 3 5 2 tdrv015InterruptRegisterCallbackThread NAME tdrv015InterruptRegisterCallbackThread Register a User Callback Function for Interrupt Handling SYNOPSIS TDRV015_ STATUS tdrv015interruptRegisterCallback Thread TDRV015_ HANDLE hdl
47. peration of the TDRV015 compatible devices conforming to the Linux I O system specification This includes a device independent basic I O interface with open close and ioctl functions The TDRV015 SW 82 device driver was designed to demonstrate the usage of main functions of the supported FPGA platform example application e g TPLDOO01 The TDRV015 SW 82 device driver requires Message Signaled Interrupt MSI support Please make sure that your specific Linux kernel and system environment properly support MSI The TDRV015 SW 82 Linux device driver was designed to demonstrate the usage of main functions of the supported FPGA platform example application e g TPLD001 The well documented device driver software can be used as base for customized FPGA platform applications The TDRV015 SW 82 device driver supports the following features Read write access to FPGA registers 8 16 32 bit big endian DMA transfer from PCI bus to FPGA PLB bus and vice versa Resource allocation for supported modules Wait for interrupts Register Callback functions for interrupt handling Driver functions are thread safe as long as unique handles are used VVVVVV The TDRV015 SW 82 supports the modules listed below TAMC631 Spartan 6 AMC with FMC Module Slot AMC with TPLD001 FPGA Platform Example TAMC640 Virtex 5 AMC with FMC Slot AMC with TPLD002 FPGA Platform Example TAMC641 High Performance Virtex 5 AMC with FMC Slot AMC with TPLD003 FPGA Pla
48. rresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 26 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge configuration Therefore the following table is just an example how the PCI Base Address Registers could be used PCI Base Address PCI Address Type TDRV015 Resource Register 0 MEM TDRV015 RES MEM_1 1 MEM not used TDRV015 RES MEM 2 2 MEM not used TDRV015 RES MEM 3 offset This argument specifies the start offset within the PCI BAR space numlitems This argument specifies the number of items 32 bit to read pData This argument is a pointer to an unsigned int buffer which will be filled with the specified number of items from the PCI BAR space The allocated space must be large enough to hold the specified amount of data EXAMPLE include tdrv0l5api h define NUM 4 TDRVO15_HANDLE hdl TDRVO15_ST
49. stem devfs or sysfs with udev then you have to skip running the makenode script Instead of creating device nodes from the script the driver itself takes creating and destroying of device nodes in its responsibility sh makenode On success the device driver will create a minor device for each TDRV015 device found The first TDRV015 device can be accessed with device node dev tdrv015_0 the second module with device node dev tdrv015_1 and so on The assignment of device nodes to physical TDRV015 modules depends on the search order of the PCI bus driver 2 4 Remove Device Driver from the running Kernel e To remove the device driver from the running kernel login as root and execute the following command modprobe r tdrv015drv If your kernel has enabled devfs or sysfs udev all dev tdrv015_x nodes will be automatically removed from your file system after this Be sure that the driver isn t opened by any application program If opened you will get the response tdrv015drv Device or resource busy and the driver will still remain in the system until you close all opened files and execute modprobe r again TDRV015 SW 82 Linux Device Driver Page 6 of 75 TEWSS amp TECHNOLOGIES 2 5 Change Major Device Number This paragraph is only for Linux kernels without dynamic device file system installed The TDRV015 driver uses dynamic allocation of major device numbers per default If this isn t suitable for the applic
50. teLE32 NAME tdrv015WriteLE32 write 32 bit values to the PCI BAR space in little endian order SYNOPSIS TDRV015_STATUS tdrv015WriteLE32 TDRV015_HANDLE hdl int pciResource int offset int numitems unsigned short pData DESCRIPTION This function writes the specified number of items to the PCI BAR space by using 32 bit accesses The values are written in little endian order that means on Intel x86 architectures the multi byte data will not be byte swapped The register sets of FPGA on chip bus slave devices and DRAM memory areas can be accessed via addressable data regions in PCI BAR space PARAMETERS hal This argument specifies the device handle to the hardware module retrieved by a call to the corresponding open function pciResource This parameter specifies the desired PCI Memory resource to be used for this access In general a PCI target PCle bridge supports up to six base address registers Following values are possible Value Description TDRV015 RES MEM_1 First found PCI Memory area TDRV015 RES MEM 2 Second found PCI Memory area TDRV015 RES MEM 3 Third found PCI Memory area TDRV015 RES MEM 4 Fourth found PCI Memory area TDRV015 RES MEM 5 Fifth found PCI Memory area TDRV015 RES MEM 6 Sixth found PCI Memory area TDRV015 SW 82 Linux Device Driver Page 41 of 75 TEWS amp TECHNOLOGIES The Base Address Register usage is programmable and can be changed by modifying the PCle bridge
51. tform Example TAMC651 Spartan 6 FPGA AMC for MTCA 4 Rear I O AMC with TPLD004 FPGA Platform Example TPMC632 Reconfigurable FPGA PMC with TPLD005 FPGA Platform Example In this document all supported modules and devices will be called TDRV015 Specials for a certain device will be advised To get more information about the features and use of supported devices it is recommended to read the manuals listed below Specific Hardware User manual Related FPGA Development Kit FDK documentation TDRV015 SW 82 Linux Device Driver Page 4 of 75 TEWS amp TECHNOLOGIES 2 Installation The directory TDRV015 SW 82 on the distribution media contains the following files TDRV015 SW 82 2 0 1 pdf This manual in PDF format TDRV015 SW 82 SRC tar gz GZIP compressed archive with driver source code ChangeLog txt Release history Release txt Information about the Device Driver Release The GZIP compressed archive TDRV015 SW 82 SRC tar gz contains the following files and directories Directory path tdrv015 tdrv015 c Driver source code tdrv015def h Driver include file tdrv015 h Driver include file for application program Makefile Device driver make file makenode Script for device node creation api tdrv015api h API include file api tdrv015api c API source file example tdrv015exa c Example application example Makefile Example application makefile include config h Driver independent library header file include tpmodule c Driv
52. uncparam value see below which has been specified on callback registration This value can be used to pass a pointer to a specific control structure to supply the callback function with specific information status This parameter hands over interrupt callback status information The callback function needs to check this parameter If the specified interrupt source has occurred properly and no errors were detected this parameter is TDRV015_OK If this parameter differs from TDRV015_OK an internal error has been detected and the callback handling is stopped The callback function must implement an appropriate error handling funcparam This value specifies a user parameter which will be handed over to the callback function on execution This parameter can be used to pass a pointer to a specific control structure used by the callback function TDRV015 SW 82 Linux Device Driver Page 66 of 75 TEWS amp TECHNOLOGIES pCallbackHandle This value specifies a pointer to a handle where the callback handle will be returned This callback handle must be used to unregister a callback function EXAMPLE include tdrvOl5api h TDRV0O15_HANDLI hdl TDRV015_STATUS result EI unsigned int interruptMask USER_DATA_AREA userDataArea TDRV0O15_ HANDLE callbackHandle forward declaration of callback functions void callback_TIMERO TDRVO15_HANDLE hdl unsigned int interruptOccurred v
53. vice Drivel c cccccccssecscecececesecesesesesesesesesesesesesesesesesesesesesesesnsesesesnsess 5 2 2 Uninstall the Device Driver sissies ccecce cca eege des teed eee ee os deh ox ov kee oc cn geed cs ot EES Ee oc on Eege e odes 6 2 3 Install Device Driver into the running Kernel cccesseeeseeeeeeeseeeeeeseeneeseseeneeseseenenenseenenenseenenes 6 2 4 Remove Device Driver from the running Kernel ceccceeeeeeeeeeeeeeeeeeenneneeeeeeeeeeeseneeneneneeeees 6 2 5 Change Major Device Number cccsccsseeeseeeeeeeeeeeeneesnaesenneneneeeeseaeseseeseseaeeneeeeseaesaneaeenseaeeseeeeas 7 3 API DOCUMENTATION ccc cssseccccessseecccensseeccceasseeecoasseseocnasseseeonassesenenasseseooaasees 8 SCH EEA ECHO eebe 8 3 1 1 tdrvO1 e EE 8 3 1 2 TOPVOT ele CEET 10 3 1 3 tdrvO ELE e le e BEE 12 3 2 Device AGCESS FUNCTIONS i icc ccd est ce ch Een ee EE tebe EE enin eed nce ci da eden aves ee be ens ce KEEN edad dei anini iaiia 14 3 2 1 TOPVOT SRA LEE 14 3 2 2 TAPVOT 5S REAG EE 17 3 2 3 TOrVOTSREAGLEI G o cccncctsscccsucssccssaverecesvenecciiunssueusubeatecnewaccucubayecabuvadeenesbanvecsvewadensdvanedadtenss 20 3 2 4 TOPVO TS REAUBES KEE 23 3 2 5 TOPVOT SREAGMES EE 26 3 2 6 TOPVO 1 SW MCB EE 29 3 2 7 trO TSW MC a EE 32 3 2 8 TOrVOTS Write LE TEE 35 3 2 9 TOPVO TS Write BES 2 es cdccccvesccunnsstevnsevesc can segediueevascdeulanddunues aaae a a ai aii aaora 38 S210 fdrVOTSWritelLE 2 chiicionceeissteneuts cetecbu

User Manual - TEWS TECHNOLOGIES

Contents

Download Pdf Manuals

Related Search

Related Contents