The following example runs on ZTEX USB FPGA boards and gives an impression of the benefits of the macro approach of the ZTEX EZ-USB SDK.

The firmware (defined in ucecho.c) declares Endpoint 2 and Endpoint 4 (both 512 bytes, double buffered, bulk transfer, belong to interface 0). All data that is written to Endpoint 4 is converted to uppercase by the FPGA and can be read back from Endpoint 2.

The Bitstream for the FPGA configuration is defined in fpga/ucecho.vhd. The FPGA reads one byte per clock cycle from port PC, converts it to uppercase and writes it to port PB.

The driver (defined in ucecho.java) uploads the the Firmware (ucecho.ihx) to the EZ-USB Microcontroller and the Bitstream (fpga/ucecho.bin) to the FPGA if necessary, sends user string to the device and reads them back.

Uploading the Firmware to EEPROM is also supported by the firmware (e.g. using the FWLoader utility).

The example is a part of the package and may serve a good starting point for own projects.

This is the C source code for the firmware:

#include[ztex-conf.h]   // Loads the configuration macros, see ztex-conf.h for the available macros
#include[ztex-utils.h]  // include basic functions
 
// Cypress vendor ID and product ID may only (!) be used for experimental purposes
SET_VPID(0x4b4,0x8613);         
 
// define endpoints 2 and 4, both belong to interface 0 (in/out are from the point of view of the host)
EP_CONFIG(2,0,BULK,IN,512,2);    
EP_CONFIG(4,0,BULK,OUT,512,2);   
 
// identify as ZTEX USB FPGA Module 1.2  (Important for FPGA configuration)
IDENTITY_UFM_1_2(1.0.0.0,0);     
 
// give them a nice name
#define[PRODUCT_STRING]["ucecho for USB FPGA boards"]
 
// this is called automatically after FPGA configuration
#define[POST_FPGA_CONFIG][POST_FPGA_CONFIG
        OEC = 255;
]
 
// include the main part of the firmware kit, define the descriptors, ...
#include[ztex.h]
 
 
void main(void) 
{
    WORD i,size;
 
// init everything
    init_USB();
 
    EP2CS &= ~bmBIT0;   // stall = 0
    SYNCDELAY; 
    EP4CS &= ~bmBIT0;   // stall = 0
 
    SYNCDELAY;          // first two packages are waste
    EP4BCL = 0x80;      // skip package, (re)arm EP4
    SYNCDELAY;
    EP4BCL = 0x80;      // skip package, (re)arm EP4
 
    while (1) { 
        if ( !(EP4CS & bmBIT2) ) {                              // EP4 is not empty
            size = (EP4BCH << 8) | EP4BCL;
            if ( size>0 && size<=512 && !(EP2CS & bmBIT3)) {    // EP2 is not full
                for ( i=0; i<size; i++ ) {
                    IOC = EP4FIFOBUF[i];        // data from EP4 is converted to uppercase by the FPGA ...
                    EP2FIFOBUF[i] = IOB;        // ... and written back to EP2 buffer
                } 
                EP2BCH = size >> 8;
                SYNCDELAY; 
                EP2BCL = size & 255;            // arm EP2
            }
            SYNCDELAY; 
            EP4BCL = 0x80;                      // skip package, (re)arm EP4
        }
    }
}

This is the VHDL source code for the FPGA bitstream:

library ieee;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;
 
entity ucecho is
   port(
      pc      : in unsigned(7 downto 0);
      pb      : out unsigned(7 downto 0);
      CLK     : in std_logic
   );
end ucecho;
 
 
--signal declaration
architecture RTL of ucecho is
 
begin
    dpUCECHO: process(CLK)
    begin
         if CLK' event and CLK = '1' then
	    if ( pc >= 97 ) and ( pc <= 122)
	    then
		pb <= pc - 32;
	    else
		pb <= pc;
	    end if;
	end if;
    end process dpUCECHO;
 
end RTL;

This is the Java source code for the driver:

import java.io.*;
import java.util.*;
 
import ch.ntb.usb.*;
 
import ztex.*;
 
// *****************************************************************************
// ******* ParameterException **************************************************
// *****************************************************************************
// Exception the prints a help message
class ParameterException extends Exception {
    public final static String helpMsg = new String (
                "Parameters:\n"+
                "    -d <number>       Device Number (default: 0)\n" +
                "    -f                Force uploads\n" +
                "    -p                Print bus info\n" +
                "    -h                This help" );
 
    public ParameterException (String msg) {
        super( msg + "\n" + helpMsg );
    }
}
 
// *****************************************************************************
// ******* Test0 ***************************************************************
// *****************************************************************************
class UCEcho extends Ztex1v1 {
 
// ******* UCEcho **************************************************************
// constructor
    public UCEcho ( ZtexDevice1 pDev ) throws UsbException, ZtexDescriptorException {
        super ( pDev );
    }
 
// ******* claimInterface ******************************************************
// claims interface 0
    public void claimInterface ( ) throws UsbException{
        if ( LibusbJava.usb_claim_interface(handle(), 0) < 0 )
            throw new UsbException("Claiming interface 0 failed: " + LibusbJava.usb_strerror());
    }
 
// ******* releaseInterface ****************************************************
// releases interface 0
    public void releaseInterface ( ) {
        LibusbJava.usb_release_interface(handle(), 0);
    }
 
// ******* echo ****************************************************************
// writes a string to Endpoint 4, reads it back from Endpoint 2 and writes the output to System.out
    public void echo ( String input ) throws UsbException {
        byte buf[] = input.getBytes(); 
        int i = LibusbJava.usb_bulk_write(handle, 4, buf, buf.length, 1000);
        if ( i<0 )
            throw new UsbException("Error sending data: " + LibusbJava.usb_strerror());
        System.out.println("Send "+i+" bytes: `"+input+"'" );
 
        try {
            Thread.sleep( 10 );
        }
            catch ( InterruptedException e ) {
        }
 
        buf = new byte[1024];
        i = LibusbJava.usb_bulk_read(handle, 2, buf, 1024, 1000);
        if ( i<0 )
            throw new UsbException("Error receiving data: " + LibusbJava.usb_strerror());
        System.out.println("Read "+i+" bytes: `"+new String(buf,0,i)+"'" );  
    }
 
// ******* main ****************************************************************
    public static void main (String args[]) {
 
        int devNum = 0;
        boolean force = false;
 
        try {
// init USB stuff
            LibusbJava.usb_init();
 
// scan the USB bus
            ZtexScanBus1 bus = new ZtexScanBus1( ZtexDevice1.cypressVendorId, ZtexDevice1.cypressProductId, true, false, 1);
            if ( bus.numberOfDevices() <= 0) {
                System.err.println("No devices found");
                System.exit(0);
            }
 
// scan the command line arguments
            for (int i=0; i<args.length; i++ ) {
                if ( args[i].equals("-d") ) {
                    i++;
                    try {
                        if (i>=args.length) throw new Exception();
                        devNum = Integer.parseInt( args[i] );
                    } 
                    catch (Exception e) {
                        throw new ParameterException("Device number expected after -d");
                    }
                }
                else if ( args[i].equals("-f") ) {
                    force = true;
                }
                else if ( args[i].equals("-p") ) {
                    bus.printBus(System.out);
                    System.exit(0);
                }
                else if ( args[i].equals("-h") ) {
                        System.err.println(ParameterException.helpMsg);
                        System.exit(0);
                }
                else throw new ParameterException("Invalid Parameter: "+args[i]);
            }
 
 
// create the main class            
            UCEcho ztex = new UCEcho ( bus.device(devNum) );
 
// upload the firmware if necessary
            if ( force || ! ztex.valid() || ! ztex.dev().productString().equals("ucecho for USB FPGA boards")  ) {
                ztex.uploadFirmware( "ucecho.ihx", force );
            }
 
// upload the bitstream if necessary
            if ( force || ! ztex.getFpgaConfiguration() ) {
                System.out.println("FPGA configuration time: " + ztex.configureFpga( "fpga/ucecho.bin" , force ) + " ms");
            } 
 
 
// claim interface 0
            ztex.claimInterface();
 
// read string from stdin and write it to USB device
            String str = "";
            BufferedReader reader = new BufferedReader( new InputStreamReader( System.in ) );
            while ( ! str.equals("quit") ) {
                System.out.print("Enter a string or `quit' to exit the program: ");
                str = reader.readLine();
                ztex.echo(str);
                System.out.println("");
            }
 
// release interface 0
            ztex.releaseInterface();    
 
        }
        catch (Exception e) {
            System.out.println("Error: "+e.getLocalizedMessage() );
        } 
   } 
 
}

It is also possible to access the device with other programming languages. In this case the firmware must be loaded using the FWLoader utility included in the SDK.

The C source code of the host software is:

/*!
   UCEcho -- C host software for ucecho examples
   Copyright (C) 2009-2010 ZTEX e.K.
   http://www.ztex.de
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License version 3 as
   published by the Free Software Foundation.
 
   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   General Public License for more details.
 
   You should have received a copy of the GNU General Public License
   along with this program; if not, see http://www.gnu.org/licenses/.
!*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <usb.h>
 
#define BUFSIZE  256
 
struct usb_device *device;
usb_dev_handle *handle;
char buf[BUFSIZE];
 
// find the first ucecho device
struct usb_device *find_device ()
{
    struct usb_bus *bus_search;
    struct usb_device *device_search;
 
    bus_search = usb_busses;
    while (bus_search != NULL)
    {
	device_search = bus_search->devices;
    	while (device_search != NULL)
	{
	    if ( (device_search->descriptor.idVendor == 0x221a) && (device_search->descriptor.idProduct == 0x100) ) 
	    {
		handle = usb_open(device_search);
		usb_get_string_simple(handle, device_search->descriptor.iProduct, buf, BUFSIZE);
		if ( ! strncmp("ucecho", buf , 6 )  )
		    return device_search;
		usb_close(handle);
	    }
	    device_search = device_search->next;
	}
        bus_search = bus_search->next;
    }
 
    return NULL;
}
 
// main
int main(int argc, char *argv[])
{
    usb_init();						// initializing libusb
    usb_find_busses();					// ... finding busses
    usb_find_devices();					// ... and devices
 
    device = find_device();				// find the device (hopefully the correct one)
 
    if ( device == NULL ) {				// nothing found
	fprintf(stderr, "Cannot find ucecho device\n");
	return 1;
    }
 
    if (usb_claim_interface(handle, 0) < 0) {
	fprintf(stderr, "Error claiming interface 0: %s\n", usb_strerror());
	return 1;
    }
 
    while ( strcmp("QUIT", buf) ) {
	// read string from stdin
	printf("Enter a string or `quit' to exit the program: ");
	scanf("%s", buf);
 
	// write string to ucecho device 
	int i = usb_bulk_write(handle, 0x04, buf, strlen(buf)+1, 1000);
	if ( i < 0 ) {
	    fprintf(stderr, "Error sending data: %s\n", usb_strerror());
	    return 1;
	}
	printf("Send %d bytes: `%s'\n", i , buf);
 
	// read string back from ucecho device 
	i = usb_bulk_read(handle, 0x82, buf, BUFSIZE, 1000);
	if ( i < 0 ) {
	    fprintf(stderr, "Error readin data: %s\n", usb_strerror());
	    return 1;
	}
	printf("Read %d bytes: `%s'\n", i , buf);
 
    }
 
    usb_release_interface(handle, 0);
    usb_close(handle);
    return 0;
}

It follows an example call with output:

stefan@ws2:/drv_a2/usb-fpga/ztex-1.1/examples/usb-fpga-1.2/ucecho$ java -cp UCEcho.jar UCEcho
FPGA configuration time: 1353 ms
Enter a string or `quit' to exit the program: Hello world!
Send 12 bytes: `Hello world!'
Read 12 bytes: `HELLO WORLD!'

Enter a string or `quit' to exit the program: quit
Send 4 bytes: `quit'
Read 4 bytes: `QUIT'