Files
externals/linux/include/celoxica/rc.h
T
2017-10-04 14:16:02 -04:00

1759 lines
78 KiB
C

/****************************************************************
* *
* Copyright (C) 1991-2003 Celoxica Ltd. All rights reserved. *
* *
*****************************************************************
* *
* Project : PDK *
* Date : 07 MAR 2005 *
* File : rc.h *
* Author : Matthew Aubury (MA) *
* Contributors: *
* *
* Description: *
* RC support library public interface *
* *
* Date Version Author Reason for change *
* *
* 07 MAR 2005 1.00 MA Created from rc300.h *
* *
****************************************************************/
#ifndef __CELOXICA_RC_H__
#define __CELOXICA_RC_H__
#ifdef __cplusplus
extern "C" {
#endif
#include <stdio.h>
#include <stdint.h>
/*
* Compiler dependent types
*/
#ifdef __GNUC__
typedef long long rcint64;
#else
typedef __int64 rcint64;
#endif
typedef enum { RC_FALSE = 0, RC_TRUE = 1 } rcbool;
/*
* API import or export
*/
#if !(defined (LINUX) || defined (MINIRC))
#ifdef RC_EXPORTS
#define RC_API __declspec(dllexport)
#else
#define RC_API __declspec(dllimport)
#endif
#else
#define RC_API
#endif
/****************************************************************************
*
* Error handling
*
****************************************************************************
*
* typedef enum RCStatus;
*
* Description:
* The type of error codes returned by RC API functions.
* The error codes are as follows:
*
* Status Code Meaning
*
* RC_OK The function completed successfully.
* RC_NULL_POINTER A NULL pointer was passed as an argument
* where a valid pointer was required.
* RC_INVALID_BOARD The "Board" argument was invalid.
* RC_INVALID_VOLTAGE The "Voltage" argument was invalid.
* RC_INVALID_TEMPERATURE The "Temperature" argument was invalid.
* RC_INVALID_IMAGE The "Image" argument was invaild.
* RC_INVALID_DEVICE The "Device" argument was invalid
* RC_INVALID_FLASH The "Flash" argument was invalid
* RC_INVALID_FLASH_TYPE The flash is of the wrong type for the operation
* RC_INVALID_FLASH_INDEX The "Index" argument was invalid.
* RC_INVALID_FLASH_FILENAME The "Filename" argument was invalid
* RC_INVALID_START The "Start" argument was invalid.
* RC_INVALID_LENGTH The "Length" argument was invalid.
* RC_INVALID_TIMEOUT The requested timeout was invalid.
* RC_INVALID_CLOCK The "Clock" argument was invalid.
* RC_INVALID_CLOCKRATE The requested clock rate was invalid.
* RC_INVALID_ADDRESS The requested address range was invalid.
* RC_INVALID_RAM The "RAM" argument was invalid.
* RC_INVALID_PROPERTY The property index or key was invalid
* RC_INVALID_ETHPARAM The ethernet parameter was invalid
* RC_FIRMWARE_MISSING The board firmware has not been programmed.
* RC_SHORT_TRANSFER Fewer bytes were transferred than requested.
* RC_OUT_OF_MEMORY The library was unable to allocated a
* required piece of memory.
* RC_DRIVER_ERROR An unexpected error occurred at
* the driver layer.
* RC_NO_DEVICES No free boards could be located.
* RC_FILE_ERROR An error occurred accessing a file.
* RC_OPEN_ERROR An error occurred whilst "opening" an board.
* RC_READ_ERROR An error occurred whilst reading from
* a board.
* RC_WRITE_ERROR An error occurred whilst writing to a board.
* RC_IOCTL_ERROR An error occurred whilst performing an
* auxillary I/O operation on a board.
* RC_READ_TIMEOUT A timeout occurred whilst reading from
* a board.
* RC_WRITE_TIMEOUT A timeout occurred whilst writing to a
* board.
* RC_IOCTL_TIMEOUT A timeout occurred whilst performing an
* auxillary I/O operation on a board.
* RC_SET_MODE_ERROR An error occurred whilst switching between
* board operating modes.
* RC_ASSERT_NPROG_ERROR An error occurred whilst trying to clear
* the FPGA configuration.
* RC_CONFIGURATION_ERROR An error occurred during configuration
* (i.e. configuration failed).
* RC_NOT_CONFIGURED An operation requiring the FPGA to be
* configured was attempted when the FPGA
* was not configured.
* RC_NOT_HOST_CONTROL A "Host Control" operation was attempted
* when the FPGA was not configured to
* "Host Control" mode.
* RC_NO_HOST_CONTROL No "Host Control" resource was available
* for the device.
* RC_FLASH_FORMAT_ERROR The flash is not formatted in the
* expected way.
* RC_DEVICE_BUSY The device is already in use
* RC_ALIGNMENT_ERROR A length or address is not suitably aligned.
* RC_NOT_IMPLEMENTED The requested feature is not available in
* this implementation
*
****************************************************************************
*
* typedef RCErrorHandler;
* RCStatus RCSetErrorHandler (RCErrorHandler *ErrorHandler);
* RCStatus RCGetErrorHandler (RCErrorHandler **ErrorHandler);
* RCStatus RCSetDefaultErrorHandler (void);
*
* Arguments:
* ErrorHandler: pointer to a new error handler function
*
* Description:
* RCSetErrorHandler () sets the error handler to the
* specified function. The function must have type
* RCErrorHandler. The error handler is called whenever an
* API call is about to return with an error code (an
* RCStatus value other than RC_OK). This is a useful
* shortcut for catching errors, saving the effort of checking
* every return value. If NULL is passed as the ErrorHandler
* argument, then error catching is turned off.
*
* RCGetErrorHandler () returns the current error handler function.
*
* RCSetDefaultErrorHandler () sets a simple default handler
* that prints the error message to stderr and calls exit(1);
*
****************************************************************************
*
* RCStatus RCStatusToString (RCStatus Status, char **StringPtr);
*
* Arguments:
* Status: a status returned from an API call
* StringPtr: returned string version of status code
*
* Description:
* Convert an error code into a printable string. For file
* errors, further information is fetched from the global file
* error scope and added to the string. The StringPtr argument
* should be a pointer to a (char *). The value of
* (*StringPtr) will be updated to point to a constant
* string. This string should not be free()'d or modified in
* any way.
*
****************************************************************************
*
* Example:
*
* void MyHandler (const char *FunctionName, RCStatus Status)
* {
* char *Error = NULL;
*
* RCStatusToString (Status, &Error);
* fprintf (stderr, "ERROR: %s: %s\n", FunctionName, Error);
* exit (1);
* }
*
* int main (int argc, char *argv[])
* {
* RCSetErrorHandler (MyHandler);
*
* // ... errors after this point will be caught
* }
*
***************************************************************************/
typedef enum
{
RC_OK,
RC_NULL_POINTER,
RC_INVALID_BOARD,
RC_INVALID_VOLTAGE,
RC_INVALID_TEMPERATURE,
RC_INVALID_IMAGE,
RC_INVALID_DEVICE,
RC_INVALID_FLASH,
RC_INVALID_FLASH_TYPE,
RC_INVALID_FLASH_INDEX,
RC_INVALID_FLASH_FILENAME,
RC_INVALID_START,
RC_INVALID_LENGTH,
RC_INVALID_TIMEOUT,
RC_INVALID_CLOCK,
RC_INVALID_CLOCKRATE,
RC_INVALID_ADDRESS,
RC_INVALID_RAM,
RC_INVALID_PROPERTY,
RC_INVALID_ETHPARAM,
RC_INVALID_TRANSFER,
RC_FIRMWARE_MISSING,
RC_SHORT_TRANSFER,
RC_OUT_OF_MEMORY,
RC_DRIVER_ERROR,
RC_NO_DEVICES,
RC_FILE_ERROR,
RC_OPEN_ERROR,
RC_READ_ERROR,
RC_WRITE_ERROR,
RC_IOCTL_ERROR,
RC_READ_TIMEOUT,
RC_WRITE_TIMEOUT,
RC_IOCTL_TIMEOUT,
RC_SET_MODE_ERROR,
RC_ASSERT_NPROG_ERROR,
RC_CONFIGURATION_ERROR,
RC_NOT_CONFIGURED,
RC_NOT_HOST_CONTROL,
RC_NO_HOST_CONTROL,
RC_FLASH_FORMAT_ERROR,
RC_DEVICE_BUSY,
RC_SOFTWARE_MISMATCH,
RC_ALIGNMENT_ERROR,
RC_RESOURCE_EXHAUSTED,
RC_NOT_IMPLEMENTED
}
RCStatus;
typedef void (RCErrorHandler) (const char *FunctionName, RCStatus Status);
RC_API RCStatus RCSetErrorHandler (RCErrorHandler *ErrorHandler);
RC_API RCStatus RCGetErrorHandler (RCErrorHandler **ErrorHandler);
RC_API RCStatus RCSetDefaultErrorHandler (void);
RC_API RCStatus RCStatusToString (RCStatus Status, char **StringPtr);
/****************************************************************************
*
* FPGA image manipulation
*
****************************************************************************
*
* typedef ... RCImage;
* RCStatus RCImageLoad (const char *HostFilename, RCImage *ImagePtr);
* RCStatus RCImageCreate (const char *Data, unsigned int Len, RCImage *ImagePtr);
* RCStatus RCImageFree (RCImage Image);
*
* Arguments:
* HostFilename: filename of a valid FPGA configuration file
* ImagePtr: pointer to a variable capable of holding an RCImage
* Image: handle to a valid FPGA image
*
* Description:
* RCImageLoad() loads an FPGA configuration file into memory,
* allocating the necessary space and returning a handle to
* the image in (*ImagePtr). This image can be used by
* RCDeviceConfigureFromImage() to configure the FPGA.
*
* RCImageCreate() creates an RCImage from an array of data already in
* memory. A copy of the data will be taken.
*
* RCImageFree() should be used to free up the memory used by
* the image. This will render the Image handle invalid.
*
***************************************************************************/
typedef struct _RCImage *RCImage;
RC_API RCStatus RCImageLoad (const char *HostFilename, RCImage *ImagePtr);
RC_API RCStatus RCImageCreate (const char *Data, unsigned int Len, RCImage *ImagePtr);
RC_API RCStatus RCImageFree (RCImage Image);
/****************************************************************************
*
* Accessing boards
*
****************************************************************************
*
* typedef ... RCBoard;
* RCStatus RCBoardOpen (int Board, RCBoard *BoardPtr);
* RCStatus RCBoardClose (RCBoard Board);
*
* Arguments:
* BoardPtr: pointer to variable of type RCBoard
* Board: a handle to an open board
*
* Description:
* The function RCBoardOpen() is used to open the first
* available RC board attached to the system. A handle to the open
* board is returned in the value (*BoardPtr), and is of type
* RCBoard. This value is passed to all subsequent board
* specific functions. The function RCBoardClose() is used to
* close the board. The board can then be re-opened by another
* application. After calling RCBoardClose() the "Board"
* handle is invalidated and no other API functions should be
* called with it.
*
***************************************************************************/
typedef struct _RCBoard *RCBoard;
RC_API RCStatus RCBoardOpen (int Board, RCBoard *BoardPtr);
RC_API RCStatus RCBoardClose (RCBoard Board);
RC_API RCStatus RCBoardAllowMultipleAccess(RCBoard Board, int Allow);
RC_API int RCBoardCount (void);
/****************************************************************************
*
* Timeouts
*
****************************************************************************
*
* RCStatus RCBoardSetTimeout (RCBoard Board, int Milliseconds);
* RC_TIMEOUT_INFINITE
*
* Arguments:
* Board: a handle to an open board
* Milliseconds: a time interval, in milliseconds
*
* Description:
* Sets the timeout for communications with an open board. If
* the value of "Milliseconds" is zero, then operations such
* as RCUSBRead() and RCUSBWrite() will operate in
* non-blocking mode. If the value of "Milliseconds" is set to
* RC_TIMEOUT_INFINITE then operations will not timeout.
*
* Note that this timeout does not apply to flash
* transfers, which can take considerably longer than typical
* data transfers.
*
***************************************************************************/
RC_API RCStatus RCBoardSetTimeout (RCBoard Board, int Milliseconds);
#define RC_TIMEOUT_INFINITE ((unsigned int) -1)
/****************************************************************************
*
* Board information
*
****************************************************************************
*
* typedef enum RCBoardType;
*
* Description:
* The different types of board supported by the RC libary.
*
* Board Type Meaning
*
* RC_CELOXICA_RC10 Celoxica RC10
* RC_CELOXICA_RC240 Celoxica RC240
* RC_CELOXICA_RC250 Celoxica RC250
* RC_CELOXICA_RC300 Celoxica RC300
* RC_CELOXICA_RC340 Celoxica RC340
* RC_CELOXICA_RCFLEX Celoxica RCFLEX
* RC_CELOXICA_RCHTX Celoxica RCHTX
* RC_CELOXICA_PCIE_2X1 Celoxica 2x1G-110
* RC_CELOXICA_PCIE_4X1 Celoxica 4x1G-155
* RC_CELOXICA_PCIE_LOW_PROFILE_2X1 Celoxica 2x1G-LP-110
* RC_CELOXICA_PCIE_4X1B Celoxica 4x1G-110
* RC_CELOXICA_PCIE_2X10_110 Celoxica 2x10G-110
* RC_CELOXICA_PCIE_LOW_PROFILE_2X1_155 Celoxica 2x1G-LP-155
* RC_CELOXICA_PCIE_2X10_155 Celoxica 2x10G-155
* RC_CELOXICA_PCIE_4X10_240 Celoxica 4x10G-240
* RC_CELOXICA_PCIE_2X10_240 Celoxica 2x10G-240
* *
****************************************************************************
*
* RCStatus RCBoardTypeToString (RCBoardType Type, const char **StringPtr);
*
* Arguments:
* Type: a value from the RCBoardType enumeration
* StringPtr: returned string version of board type
*
* Description:
* Convert a board type code into a printable string. The
* StringPtr argument should be a pointer to a (char *). The
* value of (*StringPtr) will be updated to point to a
* constant string. This string should not be free()'d or
* modified in any way.
*
****************************************************************************
*
* RCStatus RCBoardGetType (RCBoard Board, RCBoardType *TypePtr);
* RCStatus RCBoardGetFirmwareVersion (RCBoard Board, int *FirmwareVersionPtr);
*
* Arguments:
* Board: a handle to an open board
* TypePtr: pointer to a variable of type RCBoardType
* FirmwareVersionPtr: pointer to an int
*
* Description:
* RCBoardGetType() returns the type of the open board in
* (*TypePtr). RCBoardGetFirmwareVersion() returns the version
* number of the firmware in (*FirmwareVersionPtr).
*
***************************************************************************/
// Warning! Do not remove entries from this enum without replacing them with a dummy value,
// ie RC_RESERVED_n.
typedef enum
{
RC_BOARD_UNKNOWN = -1,
RC_CELOXICA_RC10,
RC_CELOXICA_RC240,
RC_CELOXICA_RC250,
RC_CELOXICA_RC300,
RC_CELOXICA_RC340,
RC_CELOXICA_RCFLEX,
RC_RESERVED_0,
RC_RESERVED_1,
RC_RESERVED_2,
RC_CELOXICA_RCHTX,
RC_CELOXICA_PCIE_2X1, //10
RC_CELOXICA_PCIE_4X1, //11
RC_CELOXICA_PCIE_LOW_PROFILE_2X1, //12
RC_CELOXICA_PCIE_4X1B, //13
RC_CELOXICA_PCIE_2X10_110, //14
RC_CELOXICA_PCIE_LOW_PROFILE_2X1_155, //15
RC_CELOXICA_PCIE_2X10_155, //16
RC_CELOXICA_PCIE_4X10_240, //17
RC_CELOXICA_PCIE_2X10_240 //18
}
RCBoardType;
RC_API RCStatus RCBoardGetType (RCBoard Board, RCBoardType *TypePtr);
RC_API RCStatus RCBoardTypeToString (RCBoardType Type, const char **StringPtr);
RC_API RCStatus RCBoardGetFirmwareVersion (RCBoard Board, int *FirmwareVersionPtr);
RC_API RCStatus RCBoardGetFirstPort (int Board, int *FirstPort);
/****************************************************************************
*
* Monitoring
*
****************************************************************************
*
* RCStatus RCVoltageGetCount (RCBoard Board, int *VoltageCountPtr);
* RCStatus RCVoltageGet (RCBoard Board, int Voltage,
* double *Target, double *Actual);
*
* RCStatus RCTemperatureGetCount (RCBoard Board, int *TemperatureCountPtr);
* RCStatus RCTemperatureGet (RCBoard Board, int Temperature,
* const char **Name, double *Actual);
*
* Arguments:
* Board: a handle to an open board
* VoltageCountPtr: returned number of voltage monitors
* TemperatureCountPtr: returned number of temperature monitors
* Voltage: index into the voltage monitors
* Temperature: index into the temperature monitors
* Target: nominal voltage, in Volts
* Actual: returned measured voltage, in Volts
* Name: returned string name of temperature monitor
*
* Description:
* RCVoltageGetCount() and RCTemperatureGetCount() return the
* number of monitored voltages and temperatures respectively.
* RCVoltageGet() gets the target (nominal) and actual (measured)
* voltages on the power supply rails. RCTemperatureGet() returns
* the name of the temperature probe and the current temperature
* in degrees C. In either case, passing a NULL pointer for
* Target, Actual, or Name will result in that information
* not being returned.
*
***************************************************************************/
RC_API RCStatus RCVoltageGetCount (RCBoard Board, int *VoltageCountPtr);
RC_API RCStatus RCVoltageGet (RCBoard Board, int Voltage, double *Target, double *Actual);
RC_API RCStatus RCTemperatureGetCount (RCBoard Board, int *TemperatureCountPtr);
RC_API RCStatus RCTemperatureGet (RCBoard Board, int Temperature, const char **Name, double *Actual);
/****************************************************************************
*
* Clocks
*
****************************************************************************
*
* typedef enum RCClockType;
*
* Description:
* The different types of clocks.
*
* Clock Type Meaning
*
* RC_CLOCK_XTAL A fixed clock from a crystal
* RC_CLOCK_PLL_FIXED A fixed clock generated by a PLL
* RC_CLOCK_PLL_VARIABLE A variable clock generated by a PLL
*
****************************************************************************
*
* RCStatus RCClockGetCount (RCBoard Board, int *ClockCountPtr);
* RCStatus RCClockGetType (RCBoard Board, int Clock, RCClockType *TypePtr);
* RCStatus RCClockGetName (RCBoard Board, int Clock, const char **NamePtr);
*
* Arguments:
* Board: handle to an open board
* ClockCountPtr: returned number of on-board clocks
* Clock: index into the clocks
* TypePtr: returned type of a clock
* NamePtr: returned string name of the clock
*
* Description:
* RCClockGetCount() returns the number of on-board clocks.
* RCClockGetType() fetches the type of the numbered clock.
* RCClockGetName() fetches a printable name of the clock.
* The string pointed to by (*NamePtr) should not be
* modified or free()'d.
*
****************************************************************************
*
* RCStatus RCClockGetDefaultRate (RCBoard Board, int Clock, double *DefaultRate);
* RCStatus RCClockGetMinRate (RCBoard Board, int Clock, double *MinRate);
* RCStatus RCClockGetMaxRate (RCBoard Board, int Clock, double *MinRate);
* RCStatus RCClockGetRate (RCBoard Board, int Clock, double *ActualRate);
* RCStatus RCClockSetRate (RCBoard Board, int Clock,
* double TargetRate, double *ActualRate);
*
* Arguments:
* Board: handle to an open board
* Clock: index into the clocks
* DefaultRate: returned default clock rate, in MHz
* MinRate: returned minimum clock rate, in MHz
* MaxRate: returned maximum clock rate, in MHz
* TargetRate: a desired clock rate, in MHz
* ActualRate: returned achieved clock rate, in MHz
*
* Description:
* RCClockGetDefaultRate() returns the rate of a clock at
* power up time. RCClockGetMinRate() and RCClockGetMaxRate()
* return the range of clock frequencies achievable by a
* variable PLL clock. RCClockGetRate() returns the current
* clock rate, in MHz. RCClockSetRate() set the clock to the
* nearest rate possible to a desired rate, and returns the
* achieved rate. In this case, ActualRate may be NULL if the
* achieved value is not required.
*
***************************************************************************/
typedef enum
{
RC_CLOCK_XTAL,
RC_CLOCK_PLL_FIXED,
RC_CLOCK_PLL_VARIABLE
}
RCClockType;
RC_API RCStatus RCClockGetCount (RCBoard Board, int *ClockCountPtr);
RC_API RCStatus RCClockGetType (RCBoard Board, int Clock, RCClockType *TypePtr);
RC_API RCStatus RCClockGetName (RCBoard Board, int Clock, const char **NamePtr);
RC_API RCStatus RCClockGetDefaultRate (RCBoard Board, int Clock, double *DefaultRate);
RC_API RCStatus RCClockGetMinRate (RCBoard Board, int Clock, double *MinRate);
RC_API RCStatus RCClockGetMaxRate (RCBoard Board, int Clock, double *MinRate);
RC_API RCStatus RCClockGetRate (RCBoard Board, int Clock, double *ActualRate);
RC_API RCStatus RCClockSetRate (RCBoard Board, int Clock, double TargetRate, double *ActualRate);
/****************************************************************************
*
* Configurable devices
*
****************************************************************************
*
* typedef enum RCDeviceFamily;
*
* Description:
* The different types of device family.
*
* Device Family Meaning
*
* RC_ALTERA_CYCLONEII Altera Cyclone II
* RC_ALTERA_STRATIX Altera Stratix
* RC_ALTERA_STRATIXII Altera Stratix II
* RC_XILINX_SPARTAN3 Xilinx Spartan 3
* RC_XILINX_VIRTEXII Xilinx Virtex II
* RC_XILNIX_VIRTEX4 Xilinx Virtex 4
* RC_XILNIX_VIRTEX5 Xilinx Virtex 5
* RC_XILNIX_VIRTEX6 Xilinx Virtex 6
*
****************************************************************************
*
* RCStatus RCDeviceFamilyToString (RCDeviceFamily Family,
* const char **StringPtr);
*
* Arguments:
* Family: a value from the RCDeviceFamily enumeration
* StringPtr: return string version of device family.
*
* Description:
* Convert a device family code into a printable string. The
* StringPtr argument should be a pointer to a (char *). The
* value of (*StringPtr) will be updated to point to a
* constant string. This string should not be free()'d or
* modified in any way.
*
****************************************************************************
*
* typedef enum RCDeviceMode;
* RCStatus RCDeviceGetCount (RCBoard Board, int *DeviceCountPtr);
* RCStatus RCDeviceGetFamily (RCBoard Board, int Device,
* RCDeviceFamily *FamilyPtr);
* RCStatus RCDeviceGetPartNumber (RCBoard Board, int Device,
* const char **PartNumber);
* RCStatus RCDeviceGetMode (RCBoard Board, int Device,
* RCDeviceMode *Mode);
*
* Arguments:
* Board: handle to an open board
* DeviceCountPtr: returned number of on-board devices
* Device: index into the configurable devices
* FamilyPtr: returned device family
* PartNumber: returned string giving part number
* Mode: returned device operation mode
*
* Description:
* RCDeviceGetCount() returns the number of configurable
* devices on-board. RCDeviceGetFamily() returns the "device
* family" of a given device. RCDeviceGetPartNumber() returns
* a constant string giving the part number of the device
* (where possible). RCDeviceGetMode() returns the current
* operating mode of a device, one of:
*
* RC_DEVICE_MODE_CLEAR Not configured
* RC_DEVICE_MODE_USER Configured by the user
* RC_DEVICE_MODE_HOST_CONTROL In "host control" mode
*
****************************************************************************
*
* RCStatus RCDeviceClear (RCBoard Board, int Device);
* RCStatus RCDeviceConfigureFromImage (RCBoard Board, int Device,
* RCImage Image);
* RCStatus RCDeviceConfigureFromImageConditional
* (RCBoard Board, int Device,
* RCImage Image, int *Changed);
* RCStatus RCDeviceConfigureFromFile (RCBoard Board, int Device,
* const char *HostFilename);
* RCStatus RCDeviceConfigureFromFileConditional
* (RCBoard Board, int Device,
* const char *HostFilename,
* int *Changed);
* RCStatus RCDeviceConfigureFromFlashIndex (RCBoard Board, int Device,
* int Flash, int FlashIndex);
* RCStatus RCDeviceConfigureFromFlashFile (RCBoard Board, int Device,
* int Flash, const char *Filename);
* RCStatus RCDeviceConfigureHostControl (RCBoard Board, int Device);
*
* Arguments:
* Board: handle to an open board
* Device: index of the device to be configured
* Image: handle to a valid device image
* HostFilename: filename of a configuration file on the host
* Flash: index of the flash containing the configuration file
* FlashIndex: a file index in indexed flash
* Filename: filename of a configuration file in file flash
* Changed: indicates whether the device was reconfigured
*
* Description:
* RCDeviceClear() clears the current configuration (if any).
* RCDeviceConfigureFromImage() configures the device with a
* valid image, such as one loaded by RCImageLoad ().
* RCDeviceConfigureFromFile() configures the device from a
* file on disk. RCDeviceConfigureFromFlashIndex() configures
* the FPGA from a configuration stored in indexed flash (such
* as on the RC10 and RC300).
* RCDeviceConfigureFromFlashFile() configures the FPGA from a
* configuration stored in file flash (such as on the RC250 &
* RC340). RCDeviceConfigureHostControl() configures the FPGA
* to "Host Control" mode - see the functions RCRAMWrite() and
* RCRAMRead() for more information.
*
* The "conditional" versions of these functions will only reconfigure
* the device if the provided image is different to that currently
* in use.
*
***************************************************************************/
typedef enum
{
RC_DEVICE_UNKNOWN = -1,
RC_ALTERA_CYCLONEII,
RC_ALTERA_STRATIX,
RC_ALTERA_STRATIXII,
RC_XILINX_SPARTAN3,
RC_XILINX_VIRTEXII,
RC_XILINX_VIRTEX4,
RC_XILINX_VIRTEX5,
RC_XILINX_VIRTEX6,
}
RCDeviceFamily;
typedef enum
{
RC_DEVICE_MODE_CLEAR,
RC_DEVICE_MODE_USER,
RC_DEVICE_MODE_HOST_CONTROL
}
RCDeviceMode;
RC_API RCStatus RCDeviceGetCount (RCBoard Board, int *DeviceCountPtr);
RC_API RCStatus RCDeviceGetFamily (RCBoard Board, int Device, RCDeviceFamily *FamilyPtr);
RC_API RCStatus RCDeviceFamilyToString (RCDeviceFamily Family, const char **StringPtr);
RC_API RCStatus RCDeviceGetPartNumber (RCBoard Board, int Device, const char **PartNumber);
RC_API RCStatus RCDeviceGetMode (RCBoard Board, int Device, RCDeviceMode *Mode);
RC_API RCStatus RCDeviceClear (RCBoard Board, int Device);
RC_API RCStatus RCDeviceConfigureFromImage (RCBoard Board, int Device, RCImage Image);
RC_API RCStatus RCDeviceConfigureFromFile (RCBoard Board, int Device, const char *HostFilename);
RC_API RCStatus RCDeviceConfigureFromFlashIndex (RCBoard Board, int Device, int Flash, int FlashIndex);
RC_API RCStatus RCDeviceConfigureFromFlashFile (RCBoard Board, int Device, int Flash, const char *Filename);
RC_API RCStatus RCDeviceConfigureHostControl (RCBoard Board, int Device);
RC_API RCStatus RCDeviceConfigureFromImageConditional (RCBoard Board, int Device, RCImage Image, int *Changed);
RC_API RCStatus RCDeviceConfigureFromFileConditional (RCBoard Board, int Device, const char *HostFilename, int *Changed);
RC_API RCStatus RCDeviceConfigurationGetName (RCBoard Board, int Device, const char **Name);
RC_API RCStatus RCDeviceConfigurationGetDate (RCBoard Board, int Device, unsigned long *Date);
RC_API RCStatus RCDeviceConfigurationGetRevision (RCBoard Board, int Device, unsigned int *Revision);
RC_API RCStatus RCDeviceConfigurationGetVersion (RCBoard Board, int Device, unsigned int *Major,
unsigned int *Minor, unsigned int *Flags);
/****************************************************************************
*
* USB Data Communications
*
****************************************************************************
*
* RCStatus RCUSBWrite (RCBoard Board, int Bytes,
* const char *Buffer, int *BytesWritten);
* RCStatus RCUSBRead (RCBoard Board, int Bytes,
* char *Buffer, int *BytesRead);
* RCStatus RCUSBWriteFile (RCBoard Board, const char *Filename);
* RCStatus RCUSBReadFile (RCBoard Board, int Bytes,
* const char *Filename);
*
* Arguments:
* Board: handle to an open board
* Bytes: number of bytes to read or write
* Buffer: pointer to an unaligned area of memory
* BytesRead: pointer to variable which can hold the
* number of bytes actually read
* BytesWritten: pointer to variable which can hold the
* number of bytes actually written
* Filename: valid filename
*
* Description:
* RCUSBWrite() writes a block of bytes from memory over USB
* to an application running in the FPGA. The Handel-C
* application running in the FPGA can do a corresponding
* RCxUSBRead() to accept the data. RCUSBRead() reads a block
* of bytes from an application running in the FPGA to an area
* of memory on the host. The Handel-C application running in
* the FPGA should do corresponding RCxUSBWrite() calls to
* write the data. The number of bytes successfully
* transferred is returned in the values (*BytesWritten) and
* (*BytesRead) respectively. This pointer can be NULL if this
* value is not required. A short write or read caused by a
* timeout will also be indicated by a status value of
* RC_WRITE_TIMEOUT or RC_READ_TIMEOUT. However, if
* non-blocking mode is selected (by setting the timeout to 0)
* and if BytesRead/BytesWritten is not NULL then RC_OK is
* returned, to allow non-blocking transfers to occur without
* causing error conditions. RCUSBReadFile() and
* RCUSBWriteFile() are utility functions that transfer
* directly to and from files on the host PC.
*
***************************************************************************/
RC_API RCStatus RCUSBWrite (RCBoard Board, int Bytes, const char *Buffer, int *BytesWritten);
RC_API RCStatus RCUSBRead (RCBoard Board, int Bytes, char *Buffer, int *BytesRead);
RC_API RCStatus RCUSBWriteFile (RCBoard Board, const char *Filename);
RC_API RCStatus RCUSBReadFile (RCBoard Board, int Bytes, const char *Filename);
/****************************************************************************
*
* Register map
*
****************************************************************************
*
* RCStatus RCRegisterMapUpdate (RCBoard Board, RCRegisterMap *RegMap);
*
* Arguments:
* Board: handle to an open board
* RegMap: table of control and status registers
*
* Description:
* A simple means to map registers between host and FPGA. A
* call to RCRegisterMapUpdate writes all 32 Control registers
* (each 32-bits) to the FPGA, and reads back the status of
* all 32 Status registers. These are mapped inside the FPGA
* application by a call such as RC250RegisterMapRun(). Note
* that when using the register map no other USB data access
* is allowed.
*
***************************************************************************/
typedef struct
{
unsigned long Control[32];
unsigned long Status[32];
}
RCRegisterMap;
RC_API RCStatus RCRegisterMapUpdate (RCBoard Board, RCRegisterMap *RegMap);
/****************************************************************************
*
* RAM access
*
****************************************************************************
*
* RC_API RCStatus RCRAMGetCount (RCBoard Board, int *RAMCountPtr);
* RC_API RCStatus RCRAMGetType (RCBoard Board, int RAM, RCRAMType *TypePtr);
* RC_API RCStatus RCRAMGetDepth (RCBoard Board, int RAM, rcint64 *Depth);
* RC_API RCStatus RCRAMGetMaxAccess (RCBoard Board, int RAM,
* RCRAMAccess *MaxAccessPtr);
*
* Arguments:
* Board: handle to an open board
* RAMCountPtr: returned number of on-board RAMs
* RAM: index into the RAMs
* RCRAMType: returned type of a RAM
* Depth: returned depth of a RAM, in bytes
* MaxAccessPtr: returned host access permissions to a RAM
*
* Description:
* RCRAMGetCount() returns the number of banks of RAM
* on-board. RCRAMGetType() returns the type of a given bank
* of RAM, as follows:
*
* RC_SRAM_ASYNC Asynchronous SRAM (Static RAM)
* RC_SRAM_ZBT ZBT SRAM (Zero Bus Turnaround)
* RC_SRAM_QDR QDR SRAM (Quad Data Rate)
* RC_SRAM_QDRII QDR-II SRAM
* RC_DRAM_ASYNC Asynchronous DRAM (Dynamic RAM)
* RC_DRAM_SDR SDRAM (Synchronous DRAM)
* RC_DRAM_DDR DDR SDRAM (Double Data Rate)
*
* RCRAMGetDepth() gets the number of bytes in a RAM (where
* possible). RCRAMGetMaxAccess() returns the maximum host
* access permissions to a RAM, as follows:
*
* RC_RAM_NO_ACCESS RAM cannot be accessed from host
* RC_RAM_READ RAM can be read from the host
* RC_RAM_WRITE RAM can be written from the host
* RC_RAM_READ_WRITE RAM can be fully accessed from the host
* RC_RAM_HOST_CONTROL RAM can be accessed from the host,
* but only when in host control mode
*
****************************************************************************
*
* RCStatus RCRAMRead (RCBoard Board, int RAM, rcint64 Address,
* rcint64 Bytes, char *Buffer);
* RCStatus RCRAMWrite (RCBoard Board, int RAM, rcint64 Address,
* rcint64 Bytes, char *Buffer);
* RCStatus RCRAMReadFile (RCBoard Board, int RAM, rcint64 Address,
* rcint64 Bytes, const char *HostFilename);
* RCStatus RCRAMWriteFile (RCBoard Board, int RAM, rcint64 Address,
* const char *HostFilename);
*
* Arguments:
* Board: handle to an open board
* RAM: index into the RAMs (bank number)
* Address: a start address, in bytes
* Bytes: length of a transfer, in bytes
* Buffer: pointer to an area of memory to be transferred
*
* Description:
* This set of functions enables simple access to on-board
* RAM. They may require the FPGA to be in "Host Control"
* mode, which is achieved by calling
* RCDeviceConfigureHostControl(). In this case, users cannot
* access RAM when an application is running in the FPGA, but
* may use these functions to setup and read back data before
* and after an application has run.
* RCRAMRead() reads a block of memory from the numbered bank
* of RAM to an area of memory allocated by the user.
* RCRAMWrite() writes a block of memory to the numbered bank
* of RAM on the board at the offset (Address) requested.
* RCRAMReadFile() is a utility function that reads from
* RAM and writes to a file on the host. RCRAMWriteFile() is
* a utility that reads from a file on the host to the SRAM.
*
***************************************************************************/
typedef enum
{
RC_RAM_NO_ACCESS = 0x0,
RC_RAM_READ = 0x1,
RC_RAM_WRITE = 0x2,
RC_RAM_READ_WRITE = 0x3, /* logical OR of above two */
RC_RAM_HOST_CONTROL = 0x4
}
RCRAMAccess;
typedef enum
{
RC_SRAM_ASYNC,
RC_SRAM_ZBT,
RC_SRAM_QDR,
RC_SRAM_QDRII,
RC_DRAM_ASYNC,
RC_DRAM_SDR,
RC_DRAM_DDR
}
RCRAMType;
RC_API RCStatus RCRAMGetCount (RCBoard Board, int *RAMCountPtr);
RC_API RCStatus RCRAMGetType (RCBoard Board, int RAM, RCRAMType *TypePtr);
RC_API RCStatus RCRAMGetDepth (RCBoard Board, int RAM, rcint64 *Depth);
RC_API RCStatus RCRAMGetMaxAccess (RCBoard Board, int RAM, RCRAMAccess *MaxAccessPtr);
RC_API RCStatus RCRAMRead (RCBoard Board, int RAM, rcint64 Address, rcint64 Bytes, char *Buffer);
RC_API RCStatus RCRAMWrite (RCBoard Board, int RAM, rcint64 Address, rcint64 Bytes, char *Buffer);
RC_API RCStatus RCRAMReadFile (RCBoard Board, int RAM, rcint64 Address, rcint64 Bytes, const char *HostFilename);
RC_API RCStatus RCRAMWriteFile (RCBoard Board, int RAM, rcint64 Address, const char *HostFilename);
/****************************************************************************
*
* Flash access
*
****************************************************************************
*
* typedef enum RCFlashType;
* RCStatus RCFlashGetCount (RCBoard Board, int *FlashCountPtr);
* RCStatus RCFlashGetType (RCBoard Board, int Flash, RCFlashType *TypePtr);
*
* Arguments:
* Board: handle to an open board
* FlashCountPtr: returned number of on-board flash devices
* Flash: an index into the flash devices
* TypePtr: returned type of a flash device
*
* Description:
* RCFlashGetCount() returns the number of host accessible
* flash devices on board. RCFlashGetType() returns the type
* of a given flash device, in terms of the modes of access
* provided, as follows:
*
* RC_FLASH_INDEX Numbered (indexed) file access only
* RC_FLASH_FILE Named file access only
* RC_FLASH_BLOCK Raw block access only
* RC_FLASH_FILE_BLOCK Both file and block access provided
*
* RC10 and RC300 support RC_FLASH_INDEX. RC250 and RC340
* supports RC_FLASH_FILE_BLOCK. The relevant access
* functions below may only be used on the appropriate type of
* flash.
*
****************************************************************************
*
* RCStatus RCFlashIndexGetRange (RCBoard Board, int Flash,
* int *FirstPtr, int *LastPtr);
* RCStatus RCFlashIndexFormat (RCBoard Board, int Flash);
* RCStatus RCFlashIndexErase (RCBoard Board, int Flash, int Index);
* RCStatus RCFlashIndexAppend (RCBoard Board, int Flash, int Index,
* int Bytes, char *Buffer);
* RCStatus RCFlashIndexAppendFile (RCBoard Board, int Flash, int Index,
* const char *HostFilename);
* RCStatus RCFlashIndexGetLength (RCBoard Board, int Flash, int Index,
* int *BytesPtr);
* RCStatus RCFlashIndexRead (RCBoard Board, int Flash, int Index,
* int Start, int Bytes, char *Buffer,
* int *BytesRead);
* RCStatus RCFlashIndexReadFile (RCBoard Board, int Flash, int Index,
* const char *HostFilename);
* RCStatus RCFlashIndexValidate (RCBoard Board, int Flash, int Index,
* const void *Data, int Bytes, int *Valid);
* RCStatus RCFlashIndexValidateFile(RCBoard Board, int Flash, int Index,
* const char *HostFilename, int *ValidPtr);
* RCStatus RCFlashIndexValidateCLBFile (RCBoard Board, int Flash, int Index,
* const char *HostFilename, int *ValidPtr);
* Arguments:
* Board: handle to an open board
* Flash: an index into the flash devices
* FirstPtr: returned value of the first file index
* LastPtr: returned value of the last file index
* Index: file index to be accessed
* Bytes: number of bytes to be transferred
* Buffer: user allocated buffer of bytes
* BytesPtr: returned length of the file
* BytesRead: returned number of bytes actually read
* HostFileName: name of a file on the host
*
* Description:
* RCFlashIndexGetRange() gets the range of file index numbers that
* can be stored on flash. RCFlashIndexFormat() formats the flash,
* deleting all stored data. RCFlashIndexErase() erases the file
* at a given index (if any). RCFlashIndexAppend() appends a block
* of data to a given index. RCFlashIndexAppendFile() is a utility
* function that appends the contents of a file on disk to a given
* flash index. RCFlashIndexGetLength() gets the length of a file
* at a given index, or 0 if no file is present. RCFlashIndexRead()
* reads a block of data from an index and stores in in a user
* buffer. RCFlashIndexReadFile() is a utility function which reads
* an entire index and stores it in a file on the host.
*
****************************************************************************
*
* RCStatus RCFlashFileErase (RCBoard Board, int Flash,
* const char *Filename);
* RCStatus RCFlashFileAppend (RCBoard Board, int Flash,
* const char *Filename,
* int Bytes, char *Buffer);
* RCStatus RCFlashFileAppendFile (RCBoard Board, int Flash,
* const char *Filename,
* const char *HostFilename);
* RCStatus RCFlashFileGetLength (RCBoard Board, int Flash,
* const char *Filename, int *BytesPtr);
* RCStatus RCFlashFileRead (RCBoard Board, int Flash,
* const char *Filename,
* int Start, int Bytes,
* char *Buffer, int *BytesRead);
* RCStatus RCFlashFileReadFile (RCBoard Board, int Flash,
* const char *Filename,
* const char *HostFilename);
* RCStatus RCFlashFileAppendCLBFile(RCBoard Board, int Flash,
* const char *Filename,
* const char *HostFilename);
* Arguments:
* Board: handle to an open board
* Flash: an index into the flash devices
* Filename: name of a file in flash
* Bytes: number of bytes to be transferred
* Buffer: user allocated buffer of bytes
* BytesPtr: returned length of the file
* BytesRead: returned number of bytes actually read
* HostFileName: name of a file on the host
*
* Description:
* RCFlashFileErase() erases the named file (if it
* exists). RCFlashFileAppend() appends a block of data to a
* given file. RCFlashFileAppendFile() is a utility function
* that appends the contents of a file on disk to a given
* flash file. RCFlashFileGetLength() gets the length of a
* file, or 0 if the file does not exist. RCFlashFileRead()
* reads a block of data from an file and stores in in a user
* buffer. RCFlashFileReadFile() is a utility function which
* reads an entire flash file and stores it in a file on the
* host.
*
****************************************************************************
*
* RCStatus RCFlashBlockRead (RCBoard Board, int Flash, int BlockNumber, void *Buffer);
* RCStatus RCFlashBlockReadFile (RCBoard Board, int Flash, int BlockNumber, const char *HostFilename);
*
* Arguments:
* Board: handle to an open board
* Flash: an index into the flash devices
* BlockNumber: a raw block number
* Buffer: user allocated buffer of bytes
* HostFileName: name of a file on the host
*
* Description:
* RCFlashBlockRead() reads a raw block from flash and stores
* it in a user allocated buffer. RCFlashBlockReadFile() is a
* utility function which reads a block and stores it in a
* file on the host.
*
***************************************************************************/
typedef enum
{
RC_FLASH_INDEX = 0x1,
RC_FLASH_FILE = 0x2,
RC_FLASH_BLOCK = 0x4,
RC_FLASH_FILE_BLOCK = 0x6 /* logical OR of two above */
}
RCFlashType;
RC_API RCStatus RCFlashGetCount (RCBoard Board, int *FlashCountPtr);
RC_API RCStatus RCFlashGetType (RCBoard Board, int Flash, RCFlashType *TypePtr);
RC_API RCStatus RCFlashGetPresence (RCBoard Board, int *IsPresent);
RC_API RCStatus RCFlashIndexGetRange (RCBoard Board, int Flash, int *FirstPtr, int *LastPtr);
RC_API RCStatus RCFlashIndexFormat (RCBoard Board, int Flash);
RC_API RCStatus RCFlashIndexErase (RCBoard Board, int Flash, int Index);
RC_API RCStatus RCFlashIndexAppend (RCBoard Board, int Flash, int Index, int Bytes, char *Buffer);
RC_API RCStatus RCFlashIndexAppendFile (RCBoard Board, int Flash, int Index, const char *HostFilename);
RC_API RCStatus RCFlashIndexGetLength (RCBoard Board, int Flash, int Index, int *BytesPtr);
RC_API RCStatus RCFlashIndexRead (RCBoard Board, int Flash, int Index, int Start, int Bytes, char *Buffer, int *BytesRead);
RC_API RCStatus RCFlashIndexReadFile (RCBoard Board, int Flash, int Index, const char *HostFilename);
RC_API RCStatus RCFlashIndexValidate (RCBoard Board, int Flash, int Index, int Bytes, const void *Data, int *ValidPtr);
RC_API RCStatus RCFlashIndexValidateFile (RCBoard Board, int Flash, int Index, const char *HostFilename, int *ValidPtr);
RC_API RCStatus RCFlashIndexAppendCLBFile (RCBoard Board, int Flash, int Index, const char *HostFilename);
RC_API RCStatus RCFlashIndexValidateCLBFile (RCBoard Board, int Flash, int Index, const char *HostFilename, int *ValidPtr);
RC_API RCStatus RCFlashFileErase (RCBoard Board, int Flash, const char *Filename);
RC_API RCStatus RCFlashFileAppend (RCBoard Board, int Flash, const char *Filename, int Bytes, char *Buffer);
RC_API RCStatus RCFlashFileAppendFile (RCBoard Board, int Flash, const char *Filename, const char *HostFilename);
RC_API RCStatus RCFlashFileGetLength (RCBoard Board, int Flash, const char *Filename, int *BytesPtr);
RC_API RCStatus RCFlashFileRead (RCBoard Board, int Flash, const char *Filename, int Start, int Bytes, char *Buffer, int *BytesRead);
RC_API RCStatus RCFlashFileReadFile (RCBoard Board, int Flash, const char *Filename, const char *HostFilename);
RC_API RCStatus RCFlashBlockRead (RCBoard Board, int Flash, int BlockNumber, void *Buffer);
RC_API RCStatus RCFlashBlockReadFile (RCBoard Board, int Flash, int BlockNumber, const char *HostFilename);
/****************************************************************************
*
* FlashIndex directory access (RC10, RC300)
*
****************************************************************************
*
* typedef struct RCFlashIndexDirEntry;
* typedef RCFlashIndexDirEntry *RCFlashIndexDir;
* RCStatus RCFlashIndexReadDir (RCBoard Board, RCFlashIndexDir *DirPtr);
* RCStatus RCFlashIndexReadDirEntry (RCBoard Board, int Index,
* RCFlashIndexDirEntry *DirEntry);
* RCStatus RCFlashIndexFreeDir (RCFlashIndexDir Dir);
*
* Arguments:
* Board: handle to an open board
* Flash: an index into the flash devices
* DirPtr: returned complete directory
* Index: file index to be accessed
* DirEntry: returned directory entry
* Dir: directory to be free'd
*
* Description:
* These functions form a utility API for fetching directories
* of the contents of index flash. RCFlashIndexReadDir()
* allocates an array capable of holding directory entries for
* every file and scans each file in turn, filling in
* information for each file. RCFlashIndexReadDirEntry()
* reads an individual entry, filling the information into a
* RCFlashIndexDirEntry structre. The elements of this
* structure are as follows:
*
* Member Type Meaning
*
* Bytes int length of the file
* DesignName char * if a bit file, the design name, otherwise NULL
* PartName char * if a bit file, the part name, otherwise NULL
* Date char * if a bit file, the design date, otherwise NULL
* Time char * if a bit file, the design time, otherwise NULL
* Header char * if not bit file, up to the first 256 bytes of data
*
* RCFlashIndexFreeDir() frees an entire directory, including
* the contents of each DirEntry. RCFlashIndexFreeDirEntry()
* frees the members of a given entry (but does not free the
* structure itself).
*
***************************************************************************/
typedef struct
{
int Bytes;
char *DesignName;
char *PartName;
char *Date;
char *Time;
char *Header;
}
RCFlashIndexDirEntry;
typedef RCFlashIndexDirEntry *RCFlashIndexDir;
RC_API RCStatus RCFlashIndexReadDir (RCBoard Board, int Flash, RCFlashIndexDir *DirPtr);
RC_API RCStatus RCFlashIndexReadDirEntry (RCBoard Board, int Flash, int Index, RCFlashIndexDirEntry *DirEntry);
RC_API RCStatus RCFlashIndexFreeDir (RCBoard Board, int Flash, RCFlashIndexDir Dir);
RC_API RCStatus RCFlashIndexFreeDirEntry (RCFlashIndexDirEntry *DirEntry);
/****************************************************************************
*
* FlashFile directory access (RC250 and RC340)
*
****************************************************************************
*
* typedef struct RCFlashFileDirEntry;
* typedef struct RCFlashFileDir;
* RCStatus RCFlashFileReadDir (RCBoard Board, int Flash, RCFlashFileDir *DirPtr);
* RCStatus RCFlashFileFreeDir (RCFlashFileDir *DirPtr);
*
* Arguments:
* Board: handle to an open board
* Flash: an index into the flash devices
* DirPtr: returned complete directory, or directory to be free'd
*
* Description:
* These functions form a utility API for fetching directories
* of the contents of file based flash. RCFlashFileReadDir()
* scans the directory, allocates and fills in a structure of
* type RCFlashFileDir. Indexing the "Entry" element with a
* number between 0 and NumEntries-1 gives each directory
* entry in turn. Each directory entry consists of a length in
* bytes, and a name and extension in traditional "8.3" FAT
* filename format. RCFlashFileFreeDir() frees the memory
* allocated by RCFlashFileReadDir() when it is no longer
* needed.
*
***************************************************************************/
typedef struct
{
int Bytes;
char Name[9];
char Extension[4];
}
RCFlashFileDirEntry;
typedef struct
{
int NumEntries;
RCFlashFileDirEntry *Entry;
}
RCFlashFileDir;
RC_API RCStatus RCFlashFileReadDir (RCBoard Board, int Flash, RCFlashFileDir *DirPtr);
RC_API RCStatus RCFlashFileFreeDir (RCFlashFileDir *DirPtr);
/****************************************************************************
*
* Property access
*
****************************************************************************
*
* RCStatus RCPropertyGetCount (RCBoard Board, int *Count);
* RCStatus RCPropertyGetIndex (RCBoard Board, int Index, char **KeyPtr, char **ValuePtr);
* RCStatus RCPropertyGetKey (RCBoard Board, const char *Key, char **ValuePtr);
*
* Arguments:
* Board: handle to an open board
* Index: an index into the property list
* Key: key to look up in property list
* KeyPtr: returned key for index
* ValuePtr: returned value for index
*
* Description:
* These functions allow device-specific parameters to be queried.
* .
*
***************************************************************************/
RC_API RCStatus RCPropertyGetCount (RCBoard Board, int *Count);
RC_API RCStatus RCPropertyGetIndex (RCBoard Board, int Index, char **KeyPtr, char **ValuePtr, int *VerbosityPtr);
RC_API RCStatus RCPropertyGetKey (RCBoard Board, const char *Key, char **ValuePtr, int *VerbosityPtr);
/****************************************************************************
*
* Data Communications
*
****************************************************************************
*
* RCStatus RCWrite (RCBoard Board, unsigned int HardwareAddress,
* const void *Buffer, unsigned long Bytes,
* unsigned int Flags, unsigned int Timeout,
* unsigned long *BytesWritten);
*
* RCStatus RCRead (RCBoard Board, unsigned int HardwareAddress,
* void *Buffer, unsigned long Bytes,
* unsigned int Flags, unsigned int Timeout,
* unsigned long *BytesRead);
*
* Arguments:
* Board: handle to an open board
* HardwareAddress: address in user FPGA I/O space
* Bytes: number of bytes to read or write
* Buffer: pointer to an area of memory
* BytesRead: pointer to variable which can hold the
* number of bytes actually read
* BytesWritten: pointer to variable which can hold the
* number of bytes actually written
* Flags: board-specific: pass 0 for defaults
* Timeout: timeout in msecs, or RC_TIMEOUT_INFINITE
*
* Description:
* RCRead() and RCWrite() transfer data to and from an application
* running in the FPGA. In both cases, the buffer, hardware address
* and the number of bytes must be 32-bit-aligned.
*
* The number of bytes transferred will be returned via the pointer
* BytesRead/BytesWritten; this pointer may be NULL if this behaviour
* is not required.
*
* Flag: Effect:
*
* RC_IO_USE_DMA Transfers will use DMA where possible (default)
* RC_IO_USE_IOMAP Transfers must the I/O map
* RC_IO_WRAP_ADDRESS A transfer extending beyond the bounds of the
* hardware address space will wrap around to
* address zero. The default behaviour is to
* return an error for such a transfer.
* RC_IO_NO_FLUSH The architecture should be permitted to
* re-order this transfer with respect to others,
* and to combine or interleave the contents with
* those of other transfers.
* RC_IO_NO_INCREMENT All data should be read/written from the same
* hardware address. The word size used is
* implementation specific.
* RC_IO_CONTINUOUS The transfer should not end (regardless of the
* Bytes parameter) until RCDMAStop() is called.
* The RCDMAMapping used must be maximum size and
* page-aligned. Implemented only for
* RCDMAReadStart only.
*
***************************************************************************/
#define RC_IO_USE_IOMAP (1<<1)
#define RC_IO_WRAP_ADDRESS (1<<2)
#define RC_IO_NO_FLUSH (1<<3)
#define RC_IO_NO_INCREMENT (1<<4)
#define RC_IO_CONTINUOUS (1<<5)
#define RC_IO_USE_DMA (1<<6)
RC_API RCStatus RCWrite (RCBoard Board, unsigned int HardwareAddress,
const void *Buffer, unsigned long Bytes,
unsigned int Flags, unsigned int Timeout,
unsigned long *BytesWritten);
RC_API RCStatus RCRead (RCBoard Board, unsigned int HardwareAddress,
void *Buffer, unsigned long Bytes,
unsigned int Flags, unsigned int Timeout,
unsigned long *BytesRead);
/****************************************************************************
*
* DMA Buffers
*
****************************************************************************
*
* typedef RCDMAMapping;
*
* RCStatus RCDMABufferMap (RCBoard Board, void *Buffer, unsigned long Len,
* unsigned int Flags, RCDMAMapping *MappingPtr);
*
* RCStatus RCDMABufferUnmap (RCBoard Board, RCDMAMapping Mapping,
* unsigned long Len, unsigned int Flags);
*
* Arguments:
* Board: handle to an open board
* Buffer: pointer to a an area of memory
* (must be 32bit-aligned)
* Len: size of buffer in bytes
* (must be multiple of 4)
* Flags: board-specific: pass 0 for defaults
* MappingPtr: used to return a mapping handle
* Mapping: a mapping handle
*
* Description:
* RCDMABufferMap() makes the specified buffer available to the
* hardware for DMA operations. The parameter MappingPtr (which must
* be non-NULL) will receive a handle which may then be used for calls
* to the other RCDMA*() routines. The handle remains valid until it
* is passed to RCDMABufferUnmap(), or until the board is closed.
*
* Variables of type RCDMAMapping may be initialised to the value
* RCDMAMappingInvalid, which will never be equal to a valid mapping
* handle.
*
* The buffer must be aligned to a 32-bit (4-byte) boundary. GNU
* malloc guarantees 8-byte alignment (16-byte on 64-bit machines), so
* an unaltered pointer from malloc() is OK.
*
* Read or writes (from software) on a mapped buffer may have
* unexpected side effects due to the behaviour of the CPU cache. In
* particular:
*
* - any write must be followed by an RCDMAFlush(); data loss may occur
* if a DMA operation is in progress in the interval between the two
*
* - any read must be preceded by an RCDMAFlush(); old data may be read
* if a DMA operation is in progress in the interval between the two
*
***************************************************************************/
typedef struct _RCDMAMapping *RCDMAMapping;
#define RCDMAMappingInvalid ((RCDMAMapping) (-1))
RC_API RCStatus RCDMABufferMap (RCBoard board, void *Buffer,
unsigned long Len, unsigned int Flags,
RCDMAMapping *MappingPtr);
RC_API RCStatus RCDMABufferUnmap (RCBoard board, RCDMAMapping Mapping,
unsigned long Len, unsigned int Flags);
/****************************************************************************
*
* Device-owned DMA Buffers
*
****************************************************************************
*
* RCStatus RCDMABufferGet (RCBoard Board, unsigned int Index,
* volatile void **PtrPtr, unsigned long *LenPtr);
*
* RCStatus RCDMABufferRelease (RCBoard Board, unsigned int Index);
*
* Arguments:
* Board: handle to an open board
* Index: indicates which DMA buffer is to be retrieved
* PtrPtr: used to return a pointer to the DMA buffer
* Len: used to return the length of the DMA buffer
*
* Description:
* RCDMABufferGet() may be used to retrieve a device/driver-owned DMA
* buffer. Typically, this will have been allocated by the device
* driver during initialisation.
*
* RCDMABufferRelease() should be called when the buffer is no longer
* required.
*
* Access to device-owned DMA buffers is still subject to the caveats
* listed above for RCDMABufferMap().
*
***************************************************************************/
RC_API RCStatus RCDMABufferGet (RCBoard Board, unsigned int Index,
volatile void **PtrPtr, unsigned long *LenPtr);
RC_API RCStatus RCDMABufferRelease (RCBoard Board, unsigned int Index);
RC_API RCStatus RCDMACopyBuffer (RCBoard Board, unsigned int Index, unsigned int BufferIndex, void *Buffer, int *Length);
/****************************************************************************
*
* DMA Transfers
*
****************************************************************************
*
* typedef RCDMATransfer;
*
* RCStatus RCDMAReadStart (RCBoard Board, RCDMAMapping Mapping,
* unsigned int HardwareAddress, unsigned long Len,
* unsigned int Flags, RCDMATransfer *TransferPtr);
*
* RCStatus RCDMAWriteStart (RCBoard Board, RCDMAMapping Mapping,
* unsigned int HardwareAddress, unsigned long Len,
* unsigned int Flags, RCDMATransfer *TransferPtr);
*
* RCStatus RCDMAWait (RCBoard Board, RCDMATransfer Transfer,
* unsigned int Timeout, unsigned long *BytesRemaining);
*
* RCStatus RCDMAStop (RCBoard Board, RCDMATransfer Transfer);
*
* RCStatus RCDMAFlush (RCBoard Board, volatile void *Buffer,
* unsigned long Len);
*
* Arguments:
* Board: handle to an open board
* Mapping: an RCDMAMapping previously returned by
* RCDMABufferMap()
* HardwareAddress: address on the hardware at which to start reading
* (must be 32bit-aligned)
* Len: number of bytes to transfer
* (must be multiple of 4)
* Flags: board-specific: pass 0 for defaults. Refer to
* the RCRead/RCWrite documentation.
* Timeout: number of milliseconds to wait
* Transfer: handle representing a DMA transfer
* Buffer: pointer to a region of a DMA buffer
*
* Description:
* Several DMA transfers may be enqueued at any time, up to an
* implementation-specific maximum. Transfers are processed in strict
* order. Once created, a transfer handle is valid until it is
* successfully waited on (without timing out), or until the board is
* closed, at which point all transfers are stopped.
*
* Variables of type RCDMATransfer may be initialised to the value
* RCDMATransferInvalid, which will never be equal to a valid transfer
* handle.
*
* RCDMAReadStart() initiates a transfer from the specified hardware
* address to the buffer corresponding to the parameter "Mapping".
*
* RCDMAWriteStart() initiates a transfer to the specified hardware
* address from the buffer corresponding to the parameter "Mapping".
*
* RCDMAWait() blocks until either the transfer finishes or the timeout
* expires. If the former, the transfer handle is invalidated, and the
* resources associated with the transfer are freed. The DMA buffer
* remains mapped.
*
* RCDMAStop() requests that a transfer be cancelled. If the transfer
* is not currently being processed by the hardware, it will be de-
* queued, and a subsequent call to RCDMAWait() will return immediately
* Otherwise the DMA hardware will be asked to stop, and the transfer
* will complete (i.e. a subsequent RCDMAWait() will return) as soon as
* all pending requests have been responded to.
*
* RCDMAFlush operates on an area of memory; it need only be called on
* regions of a buffer touched by software while still mapped.
*
***************************************************************************/
typedef struct _RCDMATransfer *RCDMATransfer;
#define RCDMATransferInvalid ((RCDMATransfer) (-1))
RC_API RCStatus RCDMAReadStart (RCBoard Board, RCDMAMapping Mapping,
unsigned int HardwareAddress,
unsigned long Len, unsigned int Flags,
RCDMATransfer *TransferPtr);
RC_API RCStatus RCDMAWriteStart (RCBoard Board, RCDMAMapping Mapping,
unsigned int HardwareAddress,
unsigned long Len, unsigned int Flags,
RCDMATransfer *TransferPtr);
RC_API RCStatus RCDMAWait (RCBoard Board, RCDMATransfer Transfer,
unsigned int Timeout,
unsigned long *BytesRemaining);
RC_API RCStatus RCDMAStop (RCBoard Board, RCDMATransfer Transfer);
RC_API RCStatus RCDMAFlush (RCBoard Board, volatile void *Buffer,
unsigned long Len);
/****************************************************************************
*
* Direct I/O
*
****************************************************************************
*
* RCStatus RCIOMapGet (RCBoard Board, volatile void **PtrPtr,
* unsigned long *LenPtr);
* RCStatus RCIOMapRelease (RCBoard Board);
* RCStatus RCIOMapWriteBarrier (RCBoard Board);
*
* Arguments:
* Board: handle to an open board
* PtrPtr: used to return a pointer to the I/O map
* LenPtr: used to return the length of the I/O map
*
* Description:
* RCIOMapGet() returns a pointer to the I/O map. If non-NULL, LenPtr
* will be used to return the size of the I/O map in bytes. This
* requires the user FPGA to have been configured, and will prevent
* reconfiguration until RCIOMapRelease() is called. Multiple Get()
* calls will return the same pointer, and require a matching number of
* Release() calls to undo.
*
* The I/O map should always be accessed through a type marked with the
* C language "volatile" attribute, otherwise results are undefined.
* Accessing the map indirectly by passing it as a parameter to a
* library function does not absolve the user of this responsibility.
*
* RCIOMapWriteBarrier() inserts a barrier between a series of writes,
* forcing all preceding writes to be sent to the hardware before any
* writes which follow. For any sequence of transactions not broken
* up by a flush:
*
* - writes may be delayed and/or re-ordered arbitrarily
* - a series of writes the same address may be coalesced into one
*
***************************************************************************/
RC_API RCStatus RCIOMapGet (RCBoard Board, volatile void **PtrPtr,
unsigned long *LenPtr);
RC_API RCStatus RCIOMapRelease (RCBoard Board);
RC_API RCStatus RCIOMapWriteBarrier (RCBoard Board);
/****************************************************************************
*
* NIC Emulation
*
****************************************************************************
*
* RCStatus RCEthernetDeviceParamSet (RCBoard Board, unsigned int Port,
* RCEthernetDeviceParam Param,
* unsigned int Value);
*
* RCStatus RCEthernetReceiveStatus (RCBoard Board, unsigned int Port,
* unsigned short Status);
*
* RCStatus RCEthernetReceivePacket (RCBoard Board, unsigned int Port,
* void *Data, unsigned int Len);
*
* RCStatus RCEthernetReceiveTxDone (RCBoard Board, unsigned int Port,
* unsigned int Count);
*
* RCStatus RCEthernetMacAddressGet (RCBoard Board, unsigned int Port,
* unsigned char *Address);
*
* Arguments:
* Board: handle to an open board
* Port: ethernet interface ID (0 for first)
* Param: one of the following:
*
* RC_ETHERNET_TXBUFFER_OFFSET: base address of transmit buffer
* RC_ETHERNET_TXBUFFER_LENGTH: size of transmit buffer (in bytes)
* RC_ETHERNET_TXCOUNT_OFFSET: address of packet length register
* RC_ETHERNET_MAC_OFFSET: base address of MAC register
*
* Value: value to assign to Param (see above)
* Status: contents of PHY status register
* Data: pointer to a received raw ethernet frame
* Len: length of the received raw ethernet frame
* Count: number of packets transmitted
*
* Description:
* These routines allow the OS to use a board as if it were a standard
* Network Interface Card (NIC). It is intended to allow the board to
* run any protocol supported by the OS network stack, particularly
* network management protocols such as ARP, ICMP, IGMP, and DHCP. An
* application would usually process the vast majority of the traffic
* itself, passing anything unrecognised through to the OS.
* Applications which pass everything to the OS may see unfavourable
* performance under high network load.
*
* As a minumum, RCEthernetReceiveStatus() must be used to notify the
* library of changes in link state. An applications will usually
* call this function regularly, but infrequently (e.g. once per
* second).
*
* It is assumed that the application is managing communication with
* the card, and therefore has access to incoming packet data. To
* pass packet data to the OS's network stack, the application should
* use RCEthernetReceivePacket(). Note that a receive-only NIC might
* not receive unicast IP packets, as it will be unable to reply to
* ARP requests.
*
* To enable packet transmission, the application must first describe
* the register layout of the hardware (i.e. position and size of
* transmit buffer and transmit length register), using
* RCEthernetDeviceParamSet(). The specified hardware addresses may
* be written to by the OS at any time; an application should either
* perform all transmissions through the OS, or implement a second
* transmit buffer for its own use.
*
* Secondly, the application must indicate when each packet has been
* transmitted (i.e. when it is safe to transmit again), by calling
* RCEthernetReceiveTxDone(). The Count parameter should be set to
* '1'.
*
* Optionally, RCEthernetMacAddressGet() may be used to read the MAC
* address(es) used by the board. The Address pointer must point to
* a buffer at least large enough for a MAC address (six bytes).
*
***************************************************************************/
typedef enum {
RC_ETHERNET_TXBUFFER_OFFSET,
RC_ETHERNET_TXBUFFER_LENGTH,
RC_ETHERNET_TXCOUNT_OFFSET,
RC_ETHERNET_MAC_OFFSET,
} RCEthernetDeviceParam;
RC_API RCStatus RCEthernetDeviceParamSet (RCBoard Board, unsigned int Port, RCEthernetDeviceParam Param, unsigned int Value);
RC_API RCStatus RCEthernetReceiveStatus (RCBoard Board, unsigned int Port, unsigned short Status);
RC_API RCStatus RCEthernetReceivePacket (RCBoard Board, unsigned int Port, void *Data, unsigned int Len);
RC_API RCStatus RCEthernetReceiveTxDone (RCBoard Board, unsigned int Port, unsigned int Count);
RC_API RCStatus RCEthernetMacAddressGet (RCBoard Board, unsigned int Port, unsigned char *Address);
/****************************************************************************
*
* Progress Callbacks
*
****************************************************************************
*
* typedef ... RCProgressCallback;
*
* RCProgressCallback RCProgressDefault;
*
* RCStatus RCSetProgressCallback (RCProgressCallback CB);
*
* Arguments:
* CB: A progress callback
*
* Description:
* RCSetProgressCallback allows a function of type RCProgressCallback
* to be registered to receive progress updates for certain lengthy
* operations.
*
* Selecting RCProgressDefault will cause a simple progress counter
* to be output on stderr.
*
* Selecting NULL will cause progress information to be ignored.
*
***************************************************************************/
typedef void (*RCProgressCallback)(const char *Operation, double Progress);
extern RC_API RCProgressCallback RCProgressDefault;
extern RC_API RCProgressCallback RCProgressNone;
RC_API RCStatus RCSetProgressCallback (RCProgressCallback CB);
/****************************************************************************
*
* Reset
*
****************************************************************************
*
* RCStatus RCBoardReset (RCBoard Board);
*
* Arguments:
* Board: handle to an open board
*
* Description:
* Resets the bus interface for the specified board. FPGAs will not
* be cleared or reconfigured, but will be notified of the reset.
*
***************************************************************************/
RC_API RCStatus RCBoardReset (RCBoard Board);
RC_API RCStatus RCDMAReadStateInit (RCBoard Board, int Channel, unsigned int *WritePos, unsigned int *CreditAvailable);
RC_API RCStatus RCDMAReadStateAdvance (RCBoard Board, int Channel, unsigned int Advance, unsigned int *CreditReleased);
typedef const int *RCVersion;
const static int _RCVersionCurrent = 3;
const static RCVersion RCVersionCurrent = &_RCVersionCurrent;
RC_API int RCVersionCheck (RCVersion Expected, int Verbosity);
/****************************************************************************
*
* CLB Functions
*
****************************************************************************
*
* CLB_Data is a struct added to the beginning of
* bin files, making a clb file. acx can get this information
* with the -rcb command. clb files are written to the board
* using the -wcb flag, and created using the -mcb flag
*
*
***************************************************************************/
const static int CLB_Data_Version = 1;
typedef struct
{
uint32_t size;
uint32_t version;
RCBoardType boardType;
char strFile[32];
uint32_t svnRevision;
char strDate[32];
char strMD5[33];
} CLB_Data;
RC_API RCStatus MakeCLBFromBin(const char *strFileName, unsigned int boardType, unsigned int svnRev, const char* md5String);
RC_API RCStatus GetCLBInfo(const char *strFileName);
/***************************************************************************/
#ifdef __cplusplus
}
#endif
#endif /* __CELOXICA_RC_H__ */