AstroFft

Account

Forgotten password

FPGA Software Driver Interface Specification for Bristol University

Radio Astronomy FFT Processor

AstroFFT

Preliminary

Reference swdriver2
Date 30/10/01
References Alpha Data FPGA FFT Processor Driver Interface Spec 1.5

Introduction

This is a specification for the software driver interface to the Alpha Data Virtex FPGA FFT processing board. It consists of a Linux compatible system driver for the Virtex FPGA processing board which has firmware compatible with the Alpha Data FPGA FFT processor Driver Interface Specification loaded.
The driver provides the following functionality:
  • Loads the FPGA with firmware.
  • Provides for setting modes on the FFT processing engine.
  • Provides for bus master DMA interrupt driven read of results data.
  • Multi-thread capable.
  • The driver is built upon the standard BEAM ADM-XRC FPGA driver.
The driver has been designed for use in the AstroFFT processing system where the FPGA is performing an FFT and magnitude averaging on data directly input to the FPGA from an analogue to digital convertor interface. It is also possible to directly use this driver for any other data pre-processing system running on the Alpha Data FPGA as long as the firmware interface matches the specification given in Alpha Data's FPGA FFT Processor Driver Interface Specification.

General

The driver is opened via the device file /dev/admxrc?, where ? is a number indicating the board number, using the normal open system function. Only one Linux process can open a particular boards driver at a time. If another process tries to open the driver it will receive the EBUSY error.
Once the driver has been opened, the controlling process can issue ioctl calls and perform data reads using the system's read function on the file descriptor returned from the open call.
Once the unit is finished with the close system call is used to close down the driver and board.
The driver supports the systems poll/select functionality so that the file descriptor can be added to a set of file descriptors that the process can sleep on awaiting an event.

Control Commands

The following control commands are provided by means of an ioctl interface.

FPGA_PROC_LOAD

This command resets and loads new firmware onto the FPGA. The command checks that the FPGA firmware is compatible with the Alpha Data FPGA FFT Processor Driver Interface specification and if so sets up the FPGA clock and enables these extensions. The ioctl's argument is a pointer to an FpgaProcLoad data structure containing the following parameters:
 
Type Name Description
uint size Number of bytes of data in the FPGA firmware.
void* data A pointer to a memory area containing the FPGA firmware.
int clock The master clock frequency to use for the FPGA
int dma Use bus master DMA for data access

The function will return 0 on success and -1 on error. The error number will be set to EINVAL if there is a problem with the firmware memory pointer, size or clock settings. It will be set to ENODEV if the firmware, once loaded, is incompatible with the Alpha Data FPGA FFT Processor Driver Interface Specification.

FPGA_PROC_MODE

This command sets up the FPGA processors mode state. The ioctl is passed an integer defining the process mode.the following parameters:
The function will return 0 on success and -1 on error. The error number will be set to EINVAL if there is a problem with the parameters passed.

FPGA_PROC_SETNPHASES

This command sets up the FPGA processors number of phases state. The ioctl is passed an integer defining the process mode.the following parameters:
The function will return 0 on success and -1 on error. The error number will be set to EINVAL if there is a problem with the parameters passed.

FPGA_PROC_START

This command will start the FPGA data processing.

FPGA_PROC_STOP

This command will stop the FPGA data processing.

Data Interface

Data is read from the FPGA by performing a conventional read system call. A process calling read will sleep awaiting the data. Once the required number of bytes of data has been received the read will return with the number of bytes of data read. If a signal occurs during the read the call will return the error EINTR. By default the data read will actually be performed using slave memory reads on FPGA FIFO interrupt signals. If the dma parameter is setup on loading the FPGA then reads will be performed by a bus master DMA operation. If there is a processing error, such as a FIFO overrun, then the read command will return the error EIO. If the processing run has been stopped then the read command will return the error ECANCELLED.
The driver supports the system poll/select functionality so that the file descriptor can be added to a set of file descriptors that the process can sleep on awaiting an event.
The driver provides multi-threaded support, so it is possible for one thread to perform a read call and another thread to start the FFT process running with an FPGA_START ioctl. This can eliminate the chance of a data overrun error in the case of fast processing systems with little on-board FIFO buffering.