Jump to Navigation

MATLAB API

The software interface is provided by bindings for C/C++, Python, Matlab and Java. After installation all bindings are available in their respective runtime environments. The API is based on the notion of channels. RIFFA 2.0 can be configured to support between 1 - 12 independent channels. Each channel connects to an IP core and can be addressed by specifying the channel number from the user application. The channels are independent and thread safe. At most one thread should be used to access a single channel.

The Matlab bindings are exposed by using the Riffa class. You will need Matlab 2008a or greater. Below is a complete example and an API listing.

  1. fid=0
  2. channel = 0
  3.  
  4. data = int32([1:100]);
  5. riffa = Riffa(fid);
  6. sent = riffa.send(channel, data, 100, 0, 1, 0);
  7. [recvd, resp] = riffa.recv(channel, 100, 0);
  8. riffa.close();
 
This example first creates a Riffa object instance which also opens up FPGA with id 0. It then sends 400 bytes of data (100 4-byte words) to channel 0 with 0 destination offset, 0 timeout, and marks the transfer as last. The IP core on channel 0 is designed to send back some data. So the next call is to receive data from the same channel, up to 400 bytes, with 0 timeout.
 
Note a few things:
  1. Matlab does not support pass by reference; all data passed to the FPGA will be copied. This is unfortunate, but unavoidable in the Matlab environment. This is why the recv method does not take a variable as a receptacle for the returned data. Instead, up to length words of data are returned. The length parameter functions as an upper bound only.
  2. Casting the data variable to int32 is not necessary. It just helps the programmer to know how many bytes are used to represent each value in the array. It is also importantbecause the IP core designer will need to know how many and how to interpret that data.
  3. The timeout is set to 0. If there's a problem with the IP core logic, a 0 timeout will cause the program to wait forever.
  4. In practice, you'd want to check the return values to see how much data was sent and received. You'd also probably want some error handling.
 

Riffa(id)
 
Initializes the FPGA specified by id. On success, returns an instance of the Riffa class. On error, prints a message. Each FPGA must be opened before any channels can be accessed. Once opened, any number of threads can use the instance.
 
id - Identifier for the FPGA (in single FPGA installations, this is always 0).
 
Returns:
An integer descriptor or None.
 

[fpgaInfoList] = Riffa.list()
 
Populates and returns a FpgaInfoList object with information on all FPGAs registered in the system or prints a message on error. Print the FpgaInfoList object to see the information.
 
Returns:
A FpgaInfoList object on success or prints a message on error.

Riffa.close()
 
Cleans up memory/resources for the FPGA opened by the Riffa instance. Once closed, the Riffa instance can no longer be used.
 
Returns:
Nothing.
 

[sent] = Riffa.send(chnl, data, length, destoff, last, timeout)
 
Sends length words (4 byte words) from data to FPGA channel chnlThe FPGA channel will be sent lengthdestoff, and last. You can use array slicing (e.g. [m:n] syntax) to create a new array object to send a subset of data. The value of destoff is used to support sending of data across multiple send transactions. Note that only the low 31 bits of this value are sent. If last is 1, the channel should interpret the end of this send as the end of a transaction. If last is 0, the channel should wait for additional sends before the end of the transaction. If timeout is non-zero, this call will send data and wait up to timeout ms for the FPGA to respond (between packets) before timing out. If timeout is zero, this call may block indefinitely. Multiple threads sending on the same channel may result in corrupt data or error. This function is thread safe across channels. Returns the number of words sent. 
 
chnl - Channel number over which to communicate (0-11).
data - Object containing the data to send.
length - Length of data to send, in (32 bit) words. Thus a value of 4 means send 16 bytes. Not necessarily the number of elements from data to send.
destoff - Value sent to FPGA core to indicate where to start writing this data. Only the least significant 31 bits are sent (not all 32).
last - If 1, this transfer is the last in a sequence of transfers. If 0, this transfer is not the last in a sequence of transfers (more transfers to come).
timeout - Timeout value in ms. If 0, no timeout is specified. Otherwise, the PC will wait up to timeout ms in between PC/FPGA communications.
 
Returns:
The number of words sent.

[recvd, data] = Riffa.recv(chnl, length, timeout);
 
Receives data from the FPGA channel chnl to the data objectThe FPGA channel can send any amount of data, so the length value sets the upper bound on what to accept into a local variable. The FPGA will specify an offset value which will determine where received data will start being written. If the amount of data plus offset exceed the value of length, then the additional data will be discarded. If timeout is non-zero, this call will wait up to timeout ms for the FPGA to respond (between packets) before timing out. If timeout is zero, this call may block indefinitely. Multiple threads receiving on the same channel may result in corrupt data or error. This function is thread safe across channels. Returns the number of words received to the data array. 
 
chnl - Channel number over which to communicate (0-11).
length - Maximum length of data to receive, in (32 bit) words. Thus a value of 4 means receive no more than 16 bytes. Not necessarily the same as the number of elements received to data.
timeout - Timeout value in ms. If 0, no timeout is specified. Otherwise, the PC will wait up to timeout ms in between PC/FPGA communications.
 
Returns:
The number of words received to the data array and the the data array itself.

Riffa.reset();
 
Resets the state of the FPGA and all transfers across all channels. This is meant to be used as an alternative to rebooting if an error occurs while sending/receiving. Calling this function while other threads are sending or receiving will result in unexpected behavior.
 
Returns:
Nothing.


Main menu 2

Page | by Dr. Radut