1759 lines
78 KiB
C
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__ */
|