RC1000-PP. Function Reference Manual

Transcription

1 RC1000-PP Function Reference Manual

2 RC1000-PP Function Reference Manual Microsoft and MS-DOS are registered trademarks and Windows, Windows 95, Windows 98 and Windows NT are trademarks of Microsoft Corporation. This manual was written by Matthew Bowen. Celoxica Limited. All rights reserved. Version 1.22 ii

3 Celoxica Ltd Table of Contents Conventions... v 1. INTRODUCTION About This Manual About the Software HOST FUNCTION REFERENCE Introduction PP1000GetCards PP1000OpenCard PP1000OpenFirstCard PP1000CloseCard PP1000GetCardInfo PP1000RequestMemoryBank PP1000ReleaseMemoryBank PP1000GetBankStatus PP1000SetClockRate PP1000StopVClock PP1000StartVClock PP1000StepVClock PP1000SetTimeout PP1000ResetFPGA PP1000ConfigureFromFile PP1000LoadFile PP1000RegisterImage PP1000LockImage PP1000ConfigureFPGA PP1000FreeImage PP1000ReadBack PP1000SetGPO PP1000ReadGPI PP1000WriteControl PP1000ReadStatus PP1000SetupDMAChannel PP1000Setup2DDMAChannel PP1000SetupSelectMapChannel PP1000DoDMA PP1000CloseDMAChannel PP1000InstallErrorHandler PP1000StatusToString FPGA MACRO REFERENCE Introduction PP1000ReadBank# PP1000WriteBank# PP1000RequestMemoryBank PP1000ReleaseMemoryBank PP1000SetLEDs iii

4 RC1000-PP Function Reference Manual PP1000LEDOn PP1000LEDOff PP1000ReadControl PP1000WriteStatus PP1000SetGPI PP1000ReadGPO iv

5 Celoxica Ltd Conventions A number of conventions are used in this document. These conventions are detailed below. Warning Message. These messages warn you that actions may damage your hardware. Handy Note. These messages draw your attention to crucial pieces of information. Hexadecimal numbers appear in this document. They are prefixed with 0x (in common with standard C syntax). Sections of code or commands that you must type are given in typewriter font like this: void main(); Information about a type of object you must specify is given in italics like this: copy SourceFileName DestinationFileName v

6 RC1000-PP Function Reference Manual vi

7 1. Introduction

8 RC1000-PP Function Reference Manual 1.1 About This Manual This manual provides details of the functions provided in the RC1000-PP host support library. Details of usage of the support functions are given in the RC1000-PP Software User Guide and details of the hardware are given in the RC1000-PP Hardware Reference Manual. Extensive references are made throughout this document to these companion documents. This chapter gives an overview of the RC1000-PP system. Chapter 2 details the host support software functions. Chapter 3 details the FPGA support software functions. 1-2

9 Introduction 1.2 About the Software The RC1000-PP Support Software provides a host driver and library to simplify the process of initialising and talking to the hardware. A number of example programs and utilities are also provided to serve as a starting point for the development of your own applications. Refer to the RC1000-PP Software User Guide for details of these examples and utilities. The software provides a number of groups of host functions: Initialisation functions Functions to handle FPGA configuration files Functions to control the RC1000-PP programmable clocks Functions to transfer data to and from the RC1000-PP FPGA Functions to help with error checking and debugging The software support package comes in the form of a device driver and a static C library which can be linked to host programs and a set of Handel-C macros for use with FPGA programs. 1-3

10 RC1000-PP Function Reference Manual 1-4

11 2. Host Function Reference

12 RC1000-PP Function Reference Manual 2.1 Introduction This section of the manual details all the host functions provided by the RC1000-PP support software. The function prototypes and other definitions are provided in the include\pp1000.h header file which must be included at the start of your program. In addition, the header file defines a number of return codes. These codes are used to indicate whether the function succeeded or to return an error code if it did not. Each function description lists the codes that the function may return along with a brief description of the meaning of the code. 2-2

13 Host Function Reference The complete list of functions is: Function Name Page PP1000GetCards 2-4 PP1000OpenCard 2-5 PP1000OpenFirstCard 2-6 PP1000CloseCard 2-7 PP1000GetCardInfo 2-8 PP1000RequestMemoryBank 2-11 PP1000ReleaseMemoryBank 2-12 PP1000GetBankStatus 2-13 PP1000SetClockRate 2-14 PP1000StopVClock 2-16 PP1000StartVClock 2-17 PP1000StepVClock 2-18 PP1000SetTimeout 2-19 PP1000ResetFPGA 2-20 PP1000ConfigureFromFile 2-21 PP1000LoadFile 2-22 PP1000RegisterImage 2-23 PP1000LockImage 2-24 PP1000ConfigureFPGA 2-25 PP1000FreeImage 2-26 PP1000ReadBack 2-27 PP1000SetGPO 2-28 PP1000ReadGPI 2-29 PP1000WriteControl 2-30 PP1000ReadStatus 2-31 PP1000SetupDMAChannel 2-32 PP1000Setup2DDMAChannel 2-34 PP1000SetupSelectMapChannel 2-37 PP1000DoDMA 2-39 PP1000CloseDMAChannel 2-40 PP1000InstallErrorHandler 2-41 PP1000StatusToString

14 RC1000-PP Function Reference Manual PP1000GetCards PP1000_STATUS PP1000GetCards(unsigned long * NumCards, PP1000_DEVICE_COUNT ** CardIDs); NumCards CardIDs Pointer to location to receive number of cards in the system. Pointer to location to receive list of cards in the system. PP1000_SUCCESS PP1000_NO_DRIVER PP1000_INTERNAL_ERROR PP1000_NO_MEMORY Success. RC1000-PP driver is not installed. Error while talking to driver. Not enough memory to complete operation. This function is used to retrieve information about the number of RC1000-PP cards in a system. The function returns the total number of cards via the NumCards parameter. It also returns a list of the card IDs and the number of cards with each card ID via the CardIDs parameter. To display all the cards in a system you could use the following C code: unsigned long NumCards; PP1000_DEVICE_COUNT *Present; unsigned long Count; PP1000GetCards(&NumCards, &Present); printf("number of cards = %d\n", NumCards); for (Count=0; NumCards>0; Count++) { printf("card ID : %d, ", Present[Count].CardID); printf("number present : %d\n", Present[Count].Count); NumCards-=Present[Count].Count; } free(present); Note that it is the caller's responsibility to free the array pointed to by CardIDs. 2-4

15 PP1000OpenCard Host Function Reference PP1000_STATUS PP1000OpenCard( PP1000_DEVICE_NUM CardID, PP1000_HANDLE * Card); CardID Card ID of card to open. Pointer to location to receive handle of open card. PP1000_SUCCESS PP1000_NULL_POINTER PP1000_INTERNAL_ERROR PP1000_NO_MEMORY PP1000_INVALID_CARDID PP1000_NO_FREE_CARDS Success. Card is a NULL pointer. Error while talking to driver. Not enough memory to complete operation. No cards with ID of CardID found. No free cards with ID of CardID found. This function is used to obtain a handle to an RC1000-PP card in the system. The card is identified by its card ID passed via the CardID parameter. In the event of there being more than one card with the same ID, the function will open the first card with the correct ID that it finds that has not already been opened. The handle returned in the Card parameter should be used in all further functions to access this board. When access to the card is no longer required, you should call the PP1000CloseCard() function to free the handle and allow other programs access to the card. 2-5

16 RC1000-PP Function Reference Manual PP1000OpenFirstCard PP1000_STATUS PP1000OpenFirstCard( PP1000_HANDLE * Card); Card Pointer to location to receive handle of open card. PP1000_SUCCESS PP1000_NULL_POINTER PP1000_INTERNAL_ERROR PP1000_NO_MEMORY PP1000_NO_FREE_CARDS Success. Card is a NULL pointer. Error while talking to driver. Not enough memory to complete operation. No free cards found. This function is used to obtain a handle to an RC1000-PP card in the system. The card opened is the first free card found in the system. This function should be used when it is not critical which card is opened or when there is only one card in the system. The handle returned in the Card parameter should be used in all further functions to access this board. When access to the card is no longer required, you should call the PP1000CloseCard() function to free the handle and allow other programs access to the card. 2-6

17 PP1000CloseCard Host Function Reference PP1000_STATUS PP1000CloseCard(PP1000_HANDLE Card); Card Handle of card to close. PP1000_SUCCESS PP1000_INVALID_HANDLE Success. Card is not a valid card handle. This function is used to close a handle for a card and free the card for use elsewhere. It should be called after an application has finished with the board to allow the support software to clean up. Card must be a valid handle returned by PP1000OpenCard() or PP1000OpenFirstCard(). 2-7

18 RC1000-PP Function Reference Manual PP1000GetCardInfo PP1000_STATUS PP1000GetCardInfo(PP1000_HANDLE Card, PP1000_CARD_INFO * Info); Card Info Handle of card to query. Pointer to card information structure to be filled in. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_NULL_POINTER PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Info is a NULL pointer. Error while talking to driver. This function is used to obtain information about an open card. The card information structure that is filled in is defined as follows: typedef struct { PP1000_DEVICE_NUM unsigned long unsigned long unsigned long unsigned long PP1000_FPGA_TYPE unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long } PP1000_CARD_INFO; CardID; PMC1Fitted; PMC2Fitted; RAMBankFitted[4]; RAMBankSpace[4]; FPGAType; PhysicalMemoryBase; *MemoryBase; BoardRevision; LogicRevision; SerialNum; Timeout; CardID is the ID of the card. This will be the value passed to PP1000OpenCard() if that function was used to open the card handle. PMC1Fitted and PMC2Fitted are non zero if the respective PMC site is occupied by a PMC compliant daughter module. RAMBankFitted[] is filled in with the size of each of the RAM banks on the board. The size is given in bytes. 2-8

19 Host Function Reference RAMBankSpace[] is filled in with the space assigned to each memory bank. This will be greater than or equal to the value in RAMBankFitted[]. These values should be used to determine the offset of each RAM bank. The size is given in bytes. FPGAType is filled in with the type of FPGA fitted to the board. Currently, this can be one of the following: PP1000_FPGA_4085XL PP1000_FPGA_40150XV PP1000_FPGA_40200XV PP1000_FPGA_40250XV PP1000_FPGA_V400 PP1000_FPGA_V600 PP1000_FPGA_V800 PP1000_FPGA_V1000 PP1000_FPGA_V1000E PP1000_FPGA_V1600E PP1000_FPGA_V2000E PP1000_FPGA_UNKNOWN PP1000_FPGA_UNKNOWN should only be returned when the card is not functioning correctly. PhysicalMemoryBase is filled in with the base address of the card's memory banks on the PCI bus. This can be used for card to card DMA transfers (see the PP1000Setup2DDMAChannel() function) or for direct access by another PCI bus master device. MemoryBase is filled in with a virtual pointer to the RAM banks on the RC1000-PP. This address may be used to read and write the SRAM on the board directly. Accesses should be made as 32 bit words and aligned to 32 bit boundaries. The size of the window is given by the sum of the 4 values in RAMBankSpace[]. Memory banks must be requested with the PP1000RequestMemoryBank() function before they can be accessed. BoardRevision and LogicRevision are filled in with version numbers for the board and glue logic. Version numbers are 8 bit hexadecimal numbers where the most significant nibble is the major version and the least significant nibble is the minor version. For example, version 2.3 is represented by 0x23. SerialNum is filled in with the serial number of the card. The serial number is factory set and is guaranteed to be a unique number. (The card ID can be set by the user and so there can be multiple cards with the same ID in one system). 2-9

20 RC1000-PP Function Reference Manual Timeout is filled in with the current value for the timeout on a card in milliseconds. The timeout is used by the library in blocking operations to return when the operation does not complete within the specified time. 2-10

21 PP1000RequestMemoryBank Host Function Reference PP1000_STATUS PP1000RequestMemoryBank( PP1000_HANDLE Card, short Mask); Card Mask Handle of card to request memory banks from. Mask of banks to request. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_TIMEOUT PP1000_INTERNAL_ERROR PP1000_CARD_BUSY Success. Card is not a valid card handle. Operation timed out before banks were granted. Error while talking to driver. Error while accessing card. This function is used to request access to one or more memory banks on a card. The function will block and return only when the banks have been granted to the host or when a timeout occurs. Mask is a four bit value indicating which banks should be requested. Bit 0 (the LSB) should be set to 1 to request bank 0, bit 1 should be set to 1 to request bank 1 and so on. Banks cannot be granted to both the FPGA and host at the same time so you should ensure that banks are released by the FPGA program when trying to request them for the host. 2-11

22 RC1000-PP Function Reference Manual PP1000ReleaseMemoryBank PP1000_STATUS PP1000ReleaseMemoryBank( PP1000_HANDLE Card, short Mask); Card Mask Handle of card to request memory banks from. Mask of banks to release. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_TIMEOUT PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Operation timed out before banks were released. Error while talking to driver. This function is used to release ownership of one or more memory banks on a card. Mask is a four bit value indicating which banks should be released. Bit 0 (the LSB) should be set to 1 to release bank 0, bit 1 should be set to 1 to release bank 1 and so on. Banks cannot be granted to both the FPGA and host at the same time so you should ensure that banks are released by the host program when trying to request them for the FPGA. 2-12

23 PP1000GetBankStatus Host Function Reference PP1000_STATUS PP1000GetBankStatus( PP1000_HANDLE Card, short * MaskHost, short * MaskFPGA); Card MaskHost MaskFPGA Handle of card to query. Mask of banks currently owned by the host. Mask of banks currently owned by the FPGA. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_TIMEOUT PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Operation timed out before bank status could be queried. Error while talking to driver. This function is used to query the ownership of the memory banks on a card. Each mask is a four bit value indicating which banks are currently owned by the host or FPGA. Bit 0 (the LSB) is set to 1 to indicate ownership of bank 0, bit 1 is set to 1 to indicate ownership of bank 1 and so on. Banks cannot be granted to both the FPGA and host at the same time. MaskHost or MaskFPGA may be set to NULL in which case the respective information is not returned. 2-13

24 RC1000-PP Function Reference Manual PP1000SetClockRate PP1000_STATUS PP1000SetClockRate(PP1000_HANDLE Card, PP1000_CLOCK Clock, double Rate); Card Clock Rate Handle of card to set clock on. Identifier of clock to program. Frequency (in Hertz) to set clock to. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INVALID_CLOCK_RATE PP1000_INVALID_CLOCK PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Rate is out of range. Clock is invalid. Error while talking to driver. This function is used program one of the clocks on a card. The value of Clock can be either PP1000_MCLK or PP1000_VCLK. The RC1000-PP clocks are connected as follows: External Clock (J10) Clock Generator JP2 JP3 MCLK VCLK FPGA PCI Clock 2-14

25 Host Function Reference When the Clock parameter is set to PP1000_MCLK, the MCLK input is set to the frequency specified by the Rate parameter provided that JP2 is linking positions 2 and 3. When JP2 is in positions 1 and 2, the MCLK pin is fed from the clock in connector (J10). Refer to the hardware reference manual for further details of jumper settings. When the Clock parameter is set to PP1000_VCLK, the VCLK input is set to the frequency specified by the Rate parameter provided that JP3 is linking positions 1 and 2. When JP3 is in positions 2 and 3, the VCLK pin is fed from the local PCI bus clock which is set at 33MHz. Refer to the hardware reference manual for further details of jumper settings. Setting the rate of VCLK will automatically start the clock running. Refer to the PP1000StopVClock() function for details of how to stop the signal on the VCLK pin. The value of Rate can be anything between 400kHz (4x10 5 ) and 100MHz (1x10 8 ). The clock will be set to the closest obtainable frequency. You should avoid setting the MCLK and VCLK outputs from the clock generator to frequencies which are close together to avoid noise on the clock. 2-15

26 RC1000-PP Function Reference Manual PP1000StopVClock PP1000_STATUS PP1000StopVClock(PP1000_HANDLE Card); Card Handle of card to stop clock on. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Error while talking to driver. This function is used stop the signal on the VCLK input of the FPGA provided that JP3 is linking positions 1 and 2. When JP3 is in positions 2 and 3, the VCLK pin is fed from the local PCI bus clock which is set at 33MHz. Refer to the hardware reference manual for further details of jumper settings. When the VCLK signal is stopped, it will be held high until either the PP1000StartVClock() or PP1000SetClockRate() function is called. 2-16

27 PP1000StartVClock Host Function Reference PP1000_STATUS PP1000StartVClock(PP1000_HANDLE Card); Card Handle of card to start clock on. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Error while talking to driver. This function is used start the signal on the VCLK input of the FPGA provided that JP3 is linking positions 1 and 2. When JP3 is in positions 2 and 3, the VCLK pin is fed from the local PCI bus clock which is set at 33MHz. Refer to the hardware reference manual for further details of jumper settings. When the VCLK signal is started, it will return to the rate set by the last call to PP1000SetClockRate() with a parameter of PP1000_VCLK. 2-17

28 RC1000-PP Function Reference Manual PP1000StepVClock PP1000_STATUS PP1000StepVClock(PP1000_HANDLE Card); Card Handle of card to step clock on. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Error while talking to driver. This function is used to single step the signal on the VCLK input of the FPGA provided that JP3 is linking positions 1 and 2. When JP3 is in positions 2 and 3, the VCLK pin is fed from the local PCI bus clock which is set at 33MHz. Refer to the hardware reference manual for further details of jumper settings. Before the VCLK pin can be single stepped, it must be stopped with a call to PP1000StopVClock(). 2-18

29 PP1000SetTimeout Host Function Reference PP1000_STATUS PP1000SetTimeout(PP1000_HANDLE Card, unsigned long Time); Card Time Handle of card to set timeout for. Length of timeout in milliseconds. PP1000_SUCCESS PP1000_INVALID_HANDLE Success. Card is not a valid card handle. The RC1000-PP support software uses timeouts on operations that can block to force completion of functions even if the operation is not complete. This function is used to set the length of the timeout used on a board. Timeouts may be disabled on a card by specifying a length of PP1000_TIMEOUT_INFINITE. 2-19

30 RC1000-PP Function Reference Manual PP1000ResetFPGA PP1000_STATUS PP1000ResetFPGA(PP1000_HANDLE Card); Card Handle of card with FPGA to reset. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INTERNAL_ERROR PP1000_TIMEOUT Success. Card is not a valid card handle. Error while talking to driver. Operation timed out before reset could complete. This function is used to pulse the F_RST_L pin on an FPGA. This pin can be used by the user FPGA program as a reset line since it has no effect on any other part of the RC1000-PP hardware or support software. 2-20

31 PP1000ConfigureFromFile Host Function Reference PP1000_STATUS PP1000ConfigureFromFile( PP1000_HANDLE Card, char *FileName); Handle FileName Handle of board to configure. Name of configuration image file. PP1000_SUCCESS Success. PP1000_FILE_NOT_FOUND Could not open file FileName. PP1000_FILE_ACCESS_ERROR Error while reading file. PP1000_INVALID_FILE File not in correct format. PP1000_NO_MEMORY Not enough memory to load file. PP1000_INVALID_PART_TYPE File is for an unrecognised FPGA. PP1000_FPGA_MISMATCH File is not for the FPGA fitted to this card. PP1000_INVALID_HANDLE Card is not a valid card handle. PP1000_INTERNAL_ERROR Error while talking to driver. PP1000_TIMEOUT Operation timed out before configuration could complete. This function is used to configure the FPGA on a card from a configuration image file. The file must be in Xilinx BIT format. The card to be configured is specified with the Card parameter which is obtained by a call to the PP1000OpenCard() or PP1000OpenFirstCard() function. The FileName parameter is a string containing the full name of the file to read. 2-21

32 RC1000-PP Function Reference Manual PP1000LoadFile PP1000_STATUS PP1000LoadFile(char *FileName, PP1000_IMAGE *Image); FileName Image Name of configuration image file. Pointer to location to receive configuration image handle. PP1000_SUCCESS PP1000_FILE_NOT_FOUND PP1000_FILE_ACCESS_ERROR PP1000_INVALID_FILE PP1000_NO_MEMORY PP1000_INVALID_PART_TYPE Success. Could not open file FileName. Error while reading file. File not in correct format. Not enough memory to load file. File is for an unrecognised FPGA. This function is used to load an FPGA configuration image into host RAM and obtains a handle for that image. This handle will be required by the PP1000ConfigureFPGA() function when you wish to configure the FPGA. The file must be in Xilinx BIT format. The FileName parameter is a string containing the full name of the file to read. The PP1000LoadFile() function will attempt to automatically determine the intended part type of the configuration image from the file. 2-22

33 PP1000RegisterImage Host Function Reference PP1000_STATUS PP1000RegisterImage(unsigned char *Buffer, unsigned long BufferLength, PP1000_IMAGE *Image); Buffer BufferLength Image Pointer to start of configuration image. Length of configuration image in bytes. Pointer to location to receive configuration image handle. PP1000_SUCCESS PP1000_NULL_POINTER PP1000_NO_MEMORY PP1000_INVALID_PART_TYPE Success. Image or Buffer is a NULL pointer. Not enough memory to create handle. Data is for an unrecognised FPGA. This function is used to register a configuration image with the support software and obtain a handle for that image. This handle will be required by the PP1000ConfigureFPGA() function when you wish to configure the FPGA. The FPGA part type is determined automatically from the buffer length. The gencfg utility can be used to generate suitable information for this function from a Xilinx.BIT file. Refer to the Software Reference Manual for details of this utility. 2-23

34 RC1000-PP Function Reference Manual PP1000LockImage PP1000_STATUS PP1000LockImage( PP1000_HANDLE Card, PP1000_IMAGE Image, PP1000_CHANNEL *Channel); Card Image Channel Handle of card to configure. Handle of configuration image. Pointer to location to receive DMA channel handle. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INVALID_IMAGE PP1000_INVALID_ALIGNMENT PP1000_NULL_POINTER PP1000_NO_MEMORY PP1000_LOCK_FAILED PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Image is not a valid handle. Host or card address is not 4 byte aligned. Channel is a NULL pointer. Not enough memory to create channel handle. Not enough physical memory to lock buffer. Error while talking to driver. This function is used to create a DMA channel handle for configuration of an FPGA. This handle can be passed to the PP1000DoDMA() function to perform the configuration. DMA configuration provides a faster method for configuring Virtex FPGAs. DMA configuration is only supported on version 2.0 PCBs with Virtex devices fitted and glue logic revision after

35 PP1000ConfigureFPGA Host Function Reference PP1000_STATUS PP1000ConfigureFPGA( PP1000_HANDLE Card, PP1000_IMAGE Image); Card Image Handle of card to configure. Handle of configuration image to use. PP1000_SUCCESS Success. PP1000_FPGA_MISMATCH File is not for the FPGA fitted to this card. PP1000_INVALID_HANDLE Card is not a valid card handle. PP1000_INVALID_IMAGE Image is not a valid handle. PP1000_INTERNAL_ERROR Error while talking to driver. PP1000_TIMEOUT Operation timed out before configuration could complete. This function is used to configure the FPGA on a card with a configuration image. The configuration image should be registered with the support software either with the PP1000LoadFile() function or with the PP1000RegisterImage() function. If there is an FPGA part mismatch between the configuration image and the FPGA on the card, PP1000_FPGA_MISMATCH will be returned. 2-25

36 RC1000-PP Function Reference Manual PP1000FreeImage PP1000_STATUS PP1000FreeImage(PP1000_IMAGE Image); Image Handle of configuration image. PP1000_SUCCESS PP1000_INVALID_IMAGE Success. Image is not a valid handle. This function is used to free the handle of an FPGA configuration image when it is no longer required. 2-26

37 PP1000ReadBack Host Function Reference PP1000_STATUS PP1000ReadBack( PP1000_HANDLE Card, void * Buffer, unsigned long BufferLength); Card Buffer BufferLength Handle of card to read back from. Buffer to store readback data in. Length of buffer in bytes. PP1000_SUCCESS Success. PP1000_INVALID_HANDLE Card is not a valid card handle. PP1000_INTERNAL_ERROR Error while talking to driver. PP1000_TIMEOUT Operation timed out before configuration could complete. PP1000_NULL_POINTER Buffer is NULL. PP1000_INVALID_ARGUMENT BufferLength is 0. This function is used to read back the configuration data from the FPGA. The raw readback data is stored into the buffer pointed to by Buffer up to a maximum of BufferLength bytes. Readback is not supported on version 1.0 PCBs. 2-27

38 RC1000-PP Function Reference Manual PP1000SetGPO PP1000_STATUS PP1000SetGPO(PP1000_HANDLE Card, unsigned long Value); Card Value Handle of card to set value of GPO on. Non-zero to set GPO, zero to clear GPO. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Error while talking to driver. This function is used to set the state of the general purpose output (GPO or USERO) pin. When Value is non-zero, this pin on the FPGA will be set to 1, when Value is zero, this pin on the FPGA will be set to zero. This pin can be read on the FPGA using the PP1000ReadGPO() Handel-C macro expression. 2-28

39 PP1000ReadGPI Host Function Reference PP1000_STATUS PP1000ReadGPI(PP1000_HANDLE Card, unsigned long *Value); Card Value Handle of card to read GPI pin from. Pointer to location to receive value from GPI pin. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_NULL_POINTER PP1000_INTERNAL_ERROR Success. Card is not a valid card handle. Value is NULL. Error while talking to driver. This function is used to read the state of the general purpose input (GPI) pin. The location pointed to by Value will be set to 1 if the FPGA has set the GPI pin or zero if the FPGA has cleared the GPI pin. The FPGA can set the state of the GPI pin using the PP1000SetGPI() Handel-C macro procedure. 2-29

40 RC1000-PP Function Reference Manual PP1000WriteControl PP1000_STATUS PP1000WriteControl(PP1000_HANDLE Card, unsigned char Control); Card Control Handle of card to write to. Value to write to card. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_TIMEOUT PP1000_INTERNAL_ERROR PP1000_CARD_BUSY Success. Card is not a valid card handle. Operation timed out before FPGA read from control port. Error while talking to driver. Error while accessing card. This function is used to write to the control port on a card. The function will block until the FPGA has read from the control port. The FPGA can read from the control port using the PP1000ReadControl() Handel-C macro procedure. 2-30

41 PP1000ReadStatus Host Function Reference PP1000_STATUS PP1000ReadStatus(PP1000_HANDLE Card, unsigned char *Status); Card Status Handle of card to read from. Pointer to location to receive value from status port. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_TIMEOUT PP1000_INTERNAL_ERROR PP1000_CARD_BUSY Success. Card is not a valid card handle. Operation timed out before FPGA wrote to status port. Error while talking to driver. Error while talking to driver. This function is used to read from the status port on a card. The function will block until the FPGA has written to the status port. The FPGA can write to the status port using the PP1000WriteStatus() Handel-C macro procedure. Status may be a NULL pointer in which case the synchronisation between FPGA and host will occur but the data will be dropped. 2-31

42 RC1000-PP Function Reference Manual PP1000SetupDMAChannel PP1000_STATUS PP1000SetupDMAChannel( PP1000_HANDLE Card, void *HostAddress, unsigned long CardOffset, unsigned long Length, PP1000_DMA_DIRECTION Direction, PP1000_CHANNEL *Channel); Card HostAddress CardOffset Length Direction Channel Handle of card to DMA to or from. Pointer to buffer on host to DMA to/from. Offset into RC1000-PP RAM to DMA to/from. Number of bytes to transfer. Direction of transfer. Pointer to location to receive DMA channel handle. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INVALID_ALIGNMENT PP1000_INVALID_DIRECTION PP1000_NULL_POINTER PP1000_INTERNAL_ERROR PP1000_NO_MEMORY PP1000_LOCK_FAILED Success. Card is not a valid card handle. Host or card address is not 4 byte aligned. Direction is not PP1000_LOCAL2PCI or PP1000_PCI2LOCAL. Channel is a NULL pointer. Error while talking to driver. Not enough memory to create channel handle. Not enough physical memory to lock buffer. This function is used to prepare a user buffer for DMA transfers to or from a card. The buffer is locked in physical memory ready for transfers by the DMA controller on the RC1000-PP. HostAddress points to the user host buffer. This address must be aligned to a 4 byte boundary. CardOffset specifies the offset (in bytes) into the card memory to DMA to/from. This offset must be 4 byte aligned. 2-32

43 Host Function Reference Length specifies how many bytes should be transferred. This value must be 4 byte aligned. Direction should be set to PP1000_PCI2LOCAL for a transfer from host to card or PP1000_LOCAL2PCI for a transfer from card to host. The channel handle returned by this function can be used in future calls to PP1000DoDMA(). Keeping DMA channels open for a long period of time can degrade system performance. You should call PP1000CloseDMAChannel() as soon as possible to minimise these effects 2-33

44 RC1000-PP Function Reference Manual PP1000Setup2DDMAChannel PP1000_STATUS PP1000Setup2DDMAChannel( PP1000_HANDLE Card, void *HostAddress, unsigned long HostPitch, unsigned long HostSpace, unsigned long CardOffset, unsigned long CardPitch, unsigned long Width, unsigned long Height, PP1000_DMA_DIRECTION Direction, PP1000_CHANNEL *Channel); Card HostAddress HostPitch HostSpace CardOffset CardPitch Width Height Direction Channel Handle of card to DMA to or from. Pointer to buffer on host to DMA to/from. Number of bytes between line start points in host buffer. Flag specifying whether HostAddress is a virtual or physical address. Offset into RC1000 RAM to DMA to/from. Number of bytes between line start points in card memory. Width of 2D transfer in bytes. Height of 2D transfer. Direction of transfer. Pointer to location to receive DMA channel handle. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INVALID_ALIGNMENT PP1000_INVALID_DIRECTION Success. Card is not a valid card handle. Host or card address is not 4 byte aligned. Direction is not PP1000_LOCAL2PCI or PP1000_PCI2LOCAL. PP1000_INVALID_ADDRESS_SPACE HostSpace is not PP1000_VIRTUAL or PP1000_PHYSICAL. PP1000_NULL_POINTER PP1000_INTERNAL_ERROR PP1000_NO_MEMORY Channel is a NULL pointer. Error while talking to driver. Not enough memory to create channel handle. 2-34

45 Host Function Reference (continued) PP1000_LOCK_FAILED Not enough physical memory to lock buffer. This function is used to prepare a user buffer for 2 dimensional DMA transfers to or from a card. The buffer is locked in physical memory ready for transfers by the DMA controller on the RC1000- PP. HostAddress points to the user host buffer. This address must be aligned to a 4 byte boundary. The address can either be a virtual address (i.e. a pointer to a user buffer) or a PCI physical address. Use of a physical address allows the RC1000-PP to directly DMA to or from a second PCI device. The HostSpace flag should be set to PP1000_VIRTUAL if HostAddress is a virtual address or PP1000_PHYSICAL if HostAddress is a physical address. Direct card to card transfers are made possible by retrieving the physical address returned by PP1000GetCardInfo() for the slave card and passing that base address (plus any required offset) into this function as the HostAddress parameter. The DMA controller on the card whose handle is passed into the PP1000Setup2DDMAChannel() function will then be used as a PCI bus master to transfer the data. Care should be taken when DMAing to or from a physical address as using an illegal physical address can hang the host computer. HostPitch specifies the number of bytes between the start of the lines of the transfer in the host buffer. This value must be a multiple of 4 bytes. CardOffset specifies the offset (in bytes) into the card memory to DMA to/from. This offset must be 4 byte aligned. CardPitch specifies the number of bytes between the start of the lines of the transfer in the card memory. This value must be a multiple of 4 bytes. Width specifies the width of the 2D transfer in bytes. This value must be 4 byte aligned. Height specifies the number of lines to transfer. 2-35

46 RC1000-PP Function Reference Manual Direction should be set to PP1000_PCI2LOCAL for a transfer from host or remote card to this card or PP1000_LOCAL2PCI for a transfer from this card to host or remote card. The channel handle returned by this function can be used in future calls to PP1000DoDMA(). Keeping DMA channels open for a long period of time can degrade system performance. You should call PP1000CloseDMAChannel() as soon as possible to minimise these effects A 2D transfer can be illustrated with the following figure. Start Address Height Width Pitch The buffer to be transferred is described by 4 parameters: start address, line pitch, width and height. The source and destination width and height must be the same and are both set to the values of the Width and Height parameters. The source and destination base addresses and line pitches can be set separately. 2-36

47 PP1000SetupSelectMapChannel Host Function Reference PP1000_STATUS PP1000SetupSelectMapChannel( void *HostAddress, unsigned long Length, PP1000_DMA_DIRECTION Direction, PP1000_CHANNEL *Channel); Card HostAddress Length Direction Channel Handle of card to DMA to or from. Pointer to buffer on host to DMA to/from. Number of bytes to transfer. Direction of transfer. Pointer to location to receive DMA channel handle. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INVALID_ALIGNMENT PP1000_INVALID_DIRECTION PP1000_NULL_POINTER PP1000_INTERNAL_ERROR PP1000_NO_MEMORY PP1000_LOCK_FAILED Success. Card is not a valid card handle. Host or card address is not 4 byte aligned. Direction is not PP1000_LOCAL2PCI or PP1000_PCI2LOCAL. Channel is a NULL pointer. Error while talking to driver. Not enough memory to create channel handle. Not enough physical memory to lock buffer. This function is used to prepare a user buffer for DMA transfers to or from the SelectMap port of a Virtex FPGA. The SelectMap port can be used for partial configuration of or partial readback from the FPGA. HostAddress points to the user host buffer. This address must be aligned to a 4 byte boundary. The address must be a virtual address (i.e. a pointer to a user buffer). Length specifies the number of bytes to transfer. This value must be 4 byte aligned. 2-37

48 RC1000-PP Function Reference Manual Direction should be set to PP1000_PCI2LOCAL for a transfer from host or remote card to this card or PP1000_LOCAL2PCI for a transfer from this card to host or remote card. The channel handle returned by this function can be used in future calls to PP1000DoDMA(). Partial configuration of a device requires the transfer of a set of commands to the SelectMap port followed by a buffer of configuration data. Refer to the Xilinx documentation for details of the commands required. Partial readback of a device requires the transfer of a set of commands to the SelectMap port followed by reading of a buffer of data from the SelectMap port. Refer to the Xilinx documentation for details of the commands required. Keeping DMA channels open for a long period of time can degrade system performance. You should call PP1000CloseDMAChannel() as soon as possible to minimise these effects This function is only supported on version 2.0 PCBs with Virtex devices fitted and glue logic revision after 1.8. Care should be taken when partially configuring FPGAs as damage to the device may result from using incorrect data. Refer to the Xilinx datasheet for details of partial configuration and readback. 2-38

49 PP1000DoDMA Host Function Reference PP1000_STATUS PP1000DoDMA(PP1000_CHANNEL Channel); Channel DMA channel handle. PP1000_SUCCESS PP1000_INVALID_HANDLE PP1000_INVALID_CHANNEL PP1000_TIMEOUT PP1000_INTERNAL_ERROR PP1000_CARD_BUSY Success. Card has been closed. Channel is not a valid DMA channel handle. Operation timed out before DMA could complete. Error while talking to driver. Error while accessing card. This function is used to perform a DMA transfer with a given DMA channel handle. The handle must have been created previously with the PP1000SetupDMAChannel() or PP1000Setup2DDMAChannel() function. You must ensure that all memory banks required for the transfer have been requested with the PP1000RequestMemoryBanks() before attempting DMA transfers. 2-39

50 RC1000-PP Function Reference Manual PP1000CloseDMAChannel PP1000_STATUS PP1000CloseDMAChannel( PP1000_CHANNEL Channel); Channel DMA channel handle. PP1000_SUCCESS PP1000_INVALID_CHANNEL PP1000_TIMEOUT PP1000_INTERNAL_ERROR Success. Channel is not a valid DMA channel handle. Operation timed out before close of handle could complete. Error while talking to driver. This function is used to free a DMA channel handle that was created with the PP1000SetupDMAChannel() or PP1000Setup2DDMAChannel() functions. The user buffer is also unlocked by this function. 2-40

51 PP1000InstallErrorHandler Host Function Reference PP1000_STATUS PP1000InstallErrorHandler( PP1000_HANDLER_FUNCTION Handler); Handler Error handler function. PP1000_SUCCESS Success. This function is used to install a user defined function that will be called whenever the RC1000-PP support library encounters an error condition. The prototype of the handler function should be: void Handler(char *FnName, PP1000_STATUS Status); When this function is called, FnName will point to a string containing the name of the calling function and Status will contain the error code. Should the handler function return, the RC1000-PP function that generated the error will return to the main program with the same error condition. Passing NULL as the value for Handler will un-install the error handler. A suggested error handling function is as follows: void Handler(char *FnName, PP1000_STATUS Status) { unsigned char Buffer[1024]; PP1000StatusToString(Status, Buffer, sizeof(buffer)); printf("\n%s - %s\n", FnName, Buffer); } exit(1); 2-41

52 RC1000-PP Function Reference Manual PP1000StatusToString PP1000_STATUS PP1000StatusToString( PP1000_STATUS Status, char *String, unsigned long Length); Status String Length Return code to decode. Pointer to buffer to receive error string. Length of buffer to receive string. PP1000_SUCCESS PP1000_NULL_POINTER PP1000_INVALID_ARGUMENT Success. String is a NULL pointer. Length is zero. This function is used to obtain a text error string for a return code. The zero terminated string will be written into the buffer pointed to by String. The maximum length of the error string (including zero termination) will be Length bytes. If Status is not a recognised return code, a string of Unknown Error will be returned. 2-42

53 Host Function Reference 2-43

54

55 3. FPGA Macro Reference

56 RC1000-PP Function Reference Manual 3.1 Introduction This chapter details all the macros provided by the RC1000-PP Handel-C support software. The macros and other definitions are provided in the pp1000.h header file which must be included at the start of your Handel-C program. This file is located in one of the following directories: Include file PCB Revision FPGA types fpga\v100\pp1000.h V XL fpga\xc4000\pp1000.h V XL, 40150XV, 40200XV, 40250XV fpga\virtex\pp1000.h V2.0 V4.0 Virtex V400, V600, V800, V1000, V1000E, V1600E, V2000E, V405E, V812E Each macro description lists the arguments and widths required and values returned as well as timing details of the macros. Before including the pp1000.h header file you should define some pre-processor macros describing the configuration of the card. These macros are described in full in the Software Reference Manual and are summarised in the table below. Function Clock division factor Clock source External RAM width Macros to define PP1000_DIVIDE1 PP1000_DIVIDE3 PP1000_DIVIDE4 PP1000_CLOCK PP1000_8BIT_RAMS PP1000_32BIT_RAMS For example, to set the board up with a clock source of MCLK divided by 4 and with 32 bit access to the external memory banks, the following code should appear at the start of the Handel-C program. #define PP1000_DIVIDE4 #define PP1000_CLOCK PP1000_MCLK #define PP1000_32BIT_RAMS #include pp1000.h 3-2

57 FPGA Macro Reference The complete list of macros in the pp1000.h header file is: Macro Name Page PP1000ReadBank# 3-4 PP1000WriteBank# 3-5 PP1000RequestMemoryBank 3-6 PP1000ReleaseMemoryBank 3-7 PP1000SetLEDs 3-8 PP1000LEDOn 3-9 PP1000LEDOff 3-10 PP1000ReadControl 3-11 PP1000WriteStatus 3-12 PP1000SetGPI 3-13 PP1000ReadGPO

58 RC1000-PP Function Reference Manual PP1000ReadBank# PP1000ReadBank0(Reg, Addr); PP1000ReadBank1(Reg, Addr); PP1000ReadBank2(Reg, Addr); PP1000ReadBank3(Reg, Addr); Reg Register to read data into. Must be 8 or 32 bits wide. Addr Address to read data from. Must be 19, 21 or 23 bits wide. Reg is set to contents of memory bank. Execution Time One clock cycle. These macro procedures should be used to access the external memory banks on an RC1000-PP card. They can be used to access any banks in parallel but the memory banks must have been granted to the FPGA before an access is attempted. To request memory banks use the PP1000RequestMemoryBank() macro procedure. If the PP1000_8BIT_RAMS preprocessor macro was defined before the pp1000.h header file was included, Reg must be 8 bits wide and Addr must be 21 bits wide on a revision 1.0 PCB or 23 bits wide on a revision 2.0 PCB. The external RAM will then be accessed as byte wide memory. If the PP1000_32BIT_RAMS preprocessor macro was defined before the pp1000.h header file was included, Reg must be 32 bits wide and Addr must be 19 bits wide on a revision 1.0 PCB or 21 bits wide on a revision 2.0 PCB. The external RAM will then be accessed as 32 bit word wide memory. You should not attempt to read or write simultaneously from the same bank of memory in the same clock cycle. 3-4

59 PP1000WriteBank# FPGA Macro Reference PP1000WriteBank0(Addr, Expr); PP1000WriteBank1(Addr, Expr); PP1000WriteBank2(Addr, Expr); PP1000WriteBank3(Addr, Expr); Addr Address to write data to. Must be 19, 21 or 23 bits wide. Expr Data to write to RAM. Must be 8 or 32 bits wide. None. Execution Time One clock cycle. These macro procedures should be used to access the external memory banks on an RC1000-PP card. They can be used to access any banks in parallel but the memory banks must have been granted to the FPGA before an access is attempted. To request memory banks use the PP1000RequestMemoryBank() macro procedure. If the PP1000_8BIT_RAMS preprocessor macro was defined before the pp1000.h header file was included, Expr must be 8 bits wide and Addr must be 21 bits wide on a revision 1.0 PCB or 23 bits wide on a revision 2.0 PCB. The external RAM will then be accessed as byte wide memory. If the PP1000_32BIT_RAMS preprocessor macro was defined before the pp1000.h header file was included, Expr must be 32 bits wide and Addr must be 19 bits wide on a revision 1.0 PCB or 21 bits wide on a revision 2.0 PCB. The external RAM will then be accessed as 32 bit word wide memory. You should not attempt to read or write simultaneously from the same bank of memory in the same clock cycle. 3-5

60 RC1000-PP Function Reference Manual PP1000RequestMemoryBank PP1000RequestMemoryBank(Mask); Mask Mask of banks to request. Must be 4 bits wide. None. Execution Time Blocks until all banks are granted to the FPGA. This macro procedure will request ownership of one or more memory banks and wait until those banks are granted to the FPGA before returning. Bit 0 (i.e. the LSB) of Mask should be set to 1 to request bank 0, bit 1 of Mask should be set to 1 to request bank 1 and so on. The requested bits are ORed with the current set of requested banks. Use the PP1000ReleaseMemoryBank() macro procedure to release ownership of memory banks. This macro procedure should not be called in parallel with itself or with the PP1000ReleaseMemoryBank() macro procedure. 3-6

61 PP1000ReleaseMemoryBank FPGA Macro Reference PP1000ReleaseMemoryBank(Mask); Mask Mask of banks to release. Must be 4 bits wide. None. Execution Time One clock cycle. This macro procedure will release ownership of one or more memory banks. Bit 0 (i.e. the LSB) of Mask should be set to 1 to release bank 0, bit 1 of Mask should be set to 1 to release bank 1 and so on. This macro procedure should not be called in parallel with itself or with the PP1000RequestMemoryBank() macro procedure. 3-7

62 RC1000-PP Function Reference Manual PP1000SetLEDs PP1000SetLEDs(Mask); Mask Mask of LED states. Must be 8 bits wide. None. Execution Time One clock cycle. This macro procedure will set the state of all 8 LEDs in a single clock cycle. Bit 0 of Mask (i.e. the LSB) corresponds to LED 0, bit 1 of Mask corresponds to LED 1 and so on. When a bit is set to 1, the LED will be switched on and when set to zero the LED will be switched off. This macro procedure should not be called in parallel with itself or with the PP1000LEDOn() or PP1000LEDOff() macro procedures. 3-8

63 PP1000LEDOn FPGA Macro Reference PP1000LEDOn(Index); Index Index of LED to switch on. Should be between 0 and 7 inclusive. None. Execution Time One clock cycle. This macro procedure will turn a single LED on. This macro procedure should not be called in parallel with itself or PP1000LEDOff() if Index is the same or with the PP1000SetLEDs() macro procedure. 3-9

64 RC1000-PP Function Reference Manual PP1000LEDOff PP1000LEDOff(Index); Index Index of LED to switch off. Should be between 0 and 7 inclusive. None. Execution Time One clock cycle. This macro procedure will turn a single LED off. This macro procedure should not be called in parallel with itself or PP1000LEDOn() if Index is the same or with the PP1000SetLEDs() macro procedure. 3-10

65 PP1000ReadControl FPGA Macro Reference PP1000ReadControl(Reg); Reg Register to receive value from control port. Must be 8 bits wide. Reg is set to value from control port. Execution Time Waits until data is written by host program. This macro procedure will read a byte from the control port. The control port can be written to by the PP1000WriteControl() function on the host. This macro procedure will wait until the host has written a value to the control port before completing. The host PP1000WriteControl() function will block until this macro procedure reads from the port. This macro procedure should not be called in parallel with itself. 3-11

66 RC1000-PP Function Reference Manual PP1000WriteStatus PP1000WriteStatus(Expr); Expr Expression to write to the status port. Must be 8 bits wide. None. Execution Time Waits until data is read by host program. This macro procedure will write a byte to the status port. The status port can be read with the PP1000ReadStatus() function on the host. This macro procedure will wait until the host has read the data from the control port before completing. The host PP1000ReadStatus() function will block until this macro procedure writes to the port. This macro procedure should not be called in parallel with itself. 3-12

67 PP1000SetGPI FPGA Macro Reference PP1000SetGPI(Expr); Expr Zero to clear GPI or USERI pin, non-zero to set GPI or USERI pin. None. Execution Time One clock cycle. This macro procedure will set the value of the GPI or USERI pin. The value on this pin can be read by the host PP1000ReadGPI() function. This macro procedure should not be called in parallel with itself. 3-13

68 RC1000-PP Function Reference Manual PP1000ReadGPO PP1000ReadGPO() None. Zero if GPO or USERO pin is low or one of GPO or USERO pin is high. Return value is one bit wide. Execution Time Zero clock cycles (macro expression). This macro expression returns the value on the GPO or USERO pin. The value on this pin can be set by the host PP1000SetGPO() function. 3-14