ZTEX core API for C
Host software API for ZTEX FPGA Boards for C
ztex.h File Reference

The Core API for C. More...

#include <sys/types.h>
#include <libusb-1.0/libusb.h>

Go to the source code of this file.

Data Structures

struct  ztex_device_info
 A structure with information about the device. More...
 

Functions

int ztex_scan_bus (char *sbuf, int sbuflen, libusb_device **devs, int op, int id_vendor, int id_product, int busnum, int devnum, char *sn, char *ps)
 Scans the bus and performs certain operations on it. More...
 
int ztex_get_device_info (libusb_device_handle *handle, ztex_device_info *info)
 Get device information. More...
 
int ztex_print_device_info (char *sbuf, int sbuflen, const ztex_device_info *info)
 Print device info to a string. More...
 
int ztex_get_fpga_config (libusb_device_handle *handle)
 Get device information. More...
 
char * ztex_find_bitstream (const ztex_device_info *info, const char *path, const char *name)
 Search for bitstream at standard locations. More...
 
int ztex_upload_bitstream (char *sbuf, int sbuflen, libusb_device_handle *handle, const ztex_device_info *info, FILE *fd, int bs)
 Upload bitstream to volatile memory. More...
 
int ztex_default_gpio_ctl (libusb_device_handle *handle, int mask, int value)
 Reads and modifies the 4 GPIO pins. More...
 
int ztex_default_reset (libusb_device_handle *handle, int leave)
 Assert the reset signal. More...
 
int ztex_default_lsi_set1 (libusb_device_handle *handle, uint8_t addr, uint32_t val)
 Send data to the low speed interface of default firmwares. More...
 
int ztex_default_lsi_set2 (libusb_device_handle *handle, uint8_t addr, const uint32_t *val, int length)
 Send data to the low speed interface of default firmwares. More...
 
int ztex_default_lsi_set3 (libusb_device_handle *handle, const uint8_t *addr, const uint32_t *val, int length)
 Send data to the low speed interface of default firmwares. More...
 
int64_t ztex_default_lsi_get1 (libusb_device_handle *handle, uint8_t addr)
 Read data from the low speed interface of default firmwares. More...
 
int ztex_default_lsi_get2 (libusb_device_handle *handle, uint8_t addr, uint32_t *val, int length)
 Read data from the low speed interface of default firmwares. More...
 

Detailed Description

The Core API for C.

An Introduction can be found in the Mainpage

Function Documentation

◆ ztex_default_gpio_ctl()

int ztex_default_gpio_ctl ( libusb_device_handle *  handle,
int  mask,
int  value 
)

Reads and modifies the 4 GPIO pins.

Parameters
handledevice handle
maskBitmask for the pins which are modified. 1 means a bit is set. Only the lowest 4 bits are significant.
valueThe bit values which are to be set. Only the lowest 4 bits are significant.
Returns
current values of the GPIO's or <0 if an USB error occurred

◆ ztex_default_lsi_get1()

int64_t ztex_default_lsi_get1 ( libusb_device_handle *  handle,
uint8_t  addr 
)

Read data from the low speed interface of default firmwares.

It's implemented as a SRAM-like interface and is typically used used to read/write configuration data, debug information or other things. This function reads one register.

Parameters
handledevice handle
addrThe address. Valid values are 0 to 255.
Returns
The unsigned register value (32 Bits) or <0 if an error occurred.

◆ ztex_default_lsi_get2()

int ztex_default_lsi_get2 ( libusb_device_handle *  handle,
uint8_t  addr,
uint32_t *  val,
int  length 
)

Read data from the low speed interface of default firmwares.

It's implemented as a SRAM-like interface and is typically used used to read/write configuration data, debug information or other things. This function reads a sequential set of registers.

Parameters
handledevice handle
addrThe start address. Valid values are 0 to 255. Address is wrapped from 255 to 0.
valThe array where to store the register data with a word width of 32 Bit.
lengthThe amount of register to be read.
Returns
0 on success or <0 if an USB error occurred

◆ ztex_default_lsi_set1()

int ztex_default_lsi_set1 ( libusb_device_handle *  handle,
uint8_t  addr,
uint32_t  val 
)

Send data to the low speed interface of default firmwares.

It's implemented as a SRAM-like interface and is typically used used to read/write configuration data, debug information or other things. This function sets one register.

Parameters
handledevice handle
addrThe address. Valid values are 0 to 255.
valThe register data with a width of 32 bit.
Returns
0 on success or <0 if an USB error occurred

◆ ztex_default_lsi_set2()

int ztex_default_lsi_set2 ( libusb_device_handle *  handle,
uint8_t  addr,
const uint32_t *  val,
int  length 
)

Send data to the low speed interface of default firmwares.

It's implemented as a SRAM-like interface and is typically used used to read/write configuration data, debug information or other things. This function sets a sequential set of registers.

Parameters
handledevice handle
addrThe starting address address. Valid values are 0 to 255. Address is wrapped from 255 to 0.
valThe register data array with a word width of 32 bit.
lengthThe length of the data array.
Returns
0 on success or <0 if an USB error occurred

◆ ztex_default_lsi_set3()

int ztex_default_lsi_set3 ( libusb_device_handle *  handle,
const uint8_t *  addr,
const uint32_t *  val,
int  length 
)

Send data to the low speed interface of default firmwares.

It's implemented as a SRAM-like interface and is typically used used to read/write configuration data, debug information or other things. This function sets a sequential set of registers.

Parameters
handledevice handle
addrThe register addresses. Valid values are 0 to 255.
valThe register data array with a word width of 32 bit.
lengthThe length of the data array.
Returns
0 on success or <0 if an USB error occurred

◆ ztex_default_reset()

int ztex_default_reset ( libusb_device_handle *  handle,
int  leave 
)

Assert the reset signal.

Parameters
handledevice handle
leaveif >0, the signal is left active. Otherwise only a short impulse is sent.
Returns
0 on success or <0 if an USB error occurred

◆ ztex_find_bitstream()

char* ztex_find_bitstream ( const ztex_device_info info,
const char *  path,
const char *  name 
)

Search for bitstream at standard locations.

Parameters
infodevice information, used for determining locations of the SDK examples, ignored if NULL
pathadditional path to search, ignored if NULL
namewithout suffix '.bit'
Returns
the file name or NULL no file found

◆ ztex_get_device_info()

int ztex_get_device_info ( libusb_device_handle *  handle,
ztex_device_info info 
)

Get device information.

Parameters
handledevice handle
infostructure where device information are stored.
Returns
the error code or 0, if no error occurs.

◆ ztex_get_fpga_config()

int ztex_get_fpga_config ( libusb_device_handle *  handle)

Get device information.

Parameters
handledevice handle
Returns
<0 if an USB error occurred, 0 if unconfigured, 1 if configured

◆ ztex_print_device_info()

int ztex_print_device_info ( char *  sbuf,
int  sbuflen,
const ztex_device_info info 
)

Print device info to a string.

The output may be truncated and is always null-terminated.

Parameters
sbufstring buffer for output
sbuflenlength of the string buffer
infostructure where device information are stored.
Returns
length of the output string (may be truncated)

◆ ztex_scan_bus()

int ztex_scan_bus ( char *  sbuf,
int  sbuflen,
libusb_device **  devs,
int  op,
int  id_vendor,
int  id_product,
int  busnum,
int  devnum,
char *  sn,
char *  ps 
)

Scans the bus and performs certain operations on it.

Parameters
devsA null terminated list of devices
opOperation to perform. <0: print bus and ignore filters, 0: find a device using the filters, >0 print all devices matching the filters
id_vendor,id_productFilter by USB ID's that specify the device, ignored if negative
busnum,devnumFilter by bus number and device address, ignored if negative
snFilter by serial number, ignored if NULL
psFilter by product string, ignored if NULL
Returns
The device index if filter result unique, otherwise -1
Parameters
devsA null terminated list of devices
opOperation to perform. <0: print bus and ignore filters, 0: find a device using the filters, >0 print all devices matching the filters
id_vendor,id_productFilter by USB ID's that specify the device, ignored if negative
busnum,devnumFilter by bus number and device address, ignored if negative
snFilter by serial number, ignored if NULL
psFilter by product string, ignored if NULL
sbufstring buffer for output
sbuflenlength of the string buffer
Returns
The device index if filter result unique, otherwise -1

◆ ztex_upload_bitstream()

int ztex_upload_bitstream ( char *  sbuf,
int  sbuflen,
libusb_device_handle *  handle,
const ztex_device_info info,
FILE *  fd,
int  bs 
)

Upload bitstream to volatile memory.

Parameters
sbufstring buffer for error messages
sbuflenlength of the string buffer
handledevice handle
infodevice information, used for determining high speed configuration settings, ignored if NULL
fdFile to read from. I/O errors are ignored.
bs0: disable bit swapping, 1: enable bit swapping, all other values: automatic detection of bit order.
Returns
-1 if an error occurred, otherwise 0. Error messages are printed to sbuf.