Compilation

The compilation process is automated using the make utility. Projects are build using the command

make [<target 1> [<target 2> ...]] 

If no target is specified, make will build the complete project. The main targets are listed below.

This page gives a detailed view of the compilation process.

The build rules (i.e. the rules the the make utility) are defined in Makefiles (see GNU make for a documentation). All standard build rules for the EZ-USB are defined in Makefile.mk in the top level directory of the package. This file can be included in Makefiles of own/new projects.

The anatomy of such a Makefile will look like (makefile of the ucecho example):

#########################
# configuration section #
#########################
 
# Defines the location of the EZ-USB SDK
ZTEXPREFIX=../../..
 
# The name of the jar archive
JARTARGET=UCEcho.jar
# Java Classes that have to be build 
CLASSTARGETS=UCEcho.class
# Extra dependencies for Java Classes
CLASSEXTRADEPS=
 
# ihx files (FX2 firmware ROM files) that have to be build 
IHXTARGETS=ucecho-fx2.ihx
# Extra Dependencies for ihx files
IHXEXTRADEPS=
 
# img files (FX3 firmware ROM files) that have to be build 
IMGTARGETS=ucecho-fx3.img 
EXTRA_C_SOURCES=
EXTRA_A_SOURCES=
 
# Extra files that should be included into the jar archive
# e.g. firmware images, FPGA bitstream
EXTRAJARFILES=ucecho-fx3.img ucecho-fx2.ihx
 
################################
# DO NOT CHANAGE THE FOLLOWING #
################################
# Includes the main Makefile
include $(ZTEXPREFIX)/Makefile.mk

Makefiles of this style support the following main targets:

Supported variables are described in the comments of Makefile.mk in the top level directory of the SDK:

# ZTEXPREFIX
#   Defines the location of the EZ-USB SDK
#   Must be defined!
#   Example: ZTEXPREFIX=../../..
#
# JARTARGET
#   The name of the jar archive
#   Example: JARTARGET=UCEcho.jar
#
# CLASSTARGETS
#   Java Classes that have to be build 
#   Example: CLASSTARGETS=UCEcho.class
#
# CLASSEXTRADEPS
#   Extra dependencies for Java Classes
#   Example: CLASSEXTRADEPS:=$(wildcard $(ZTEXPREFIX)/java/ztex/*.java)
#
# IHXTARGETS
#   FX2 ihx files (firmware ROM files) that have to be build 
#   Example: IHXTARGETS=ucecho.ihx
#
# IHXEXTRADEPS
#   Extra Dependencies for ihx files
#   Example: IHXEXTRADEPS:=$(wildcard $(ZTEXPREFIX)/fx2/*.h)
#
# IMGTARGETS
#   FX3 img files (firmware ROM files) that have to be build 
#   Example: IMGTARGETS=ucecho.img
#
# IMGEXTRA_C_SOURCES
#   extra C sources
#
# IMGEXTRA_A_SOURCES
#   extra Assembler sources
#
# EXTRAJARFILES
#   Extra files that should be included into the jar archive
#   Example: EXTRAJARFILES=ucecho.ihx fpga/ucecho.bin
#
# EXTRAJARFLAGS
#   Extra flags for the jar command
#   Example: EXTRAJARFLAGS=-C com
#
# EXTRACLEANFILES
#   Extra files that should be cleaned by target "clean"
#
# EXTRADISTCLEANFILES
#   Extra files that should be cleaned by target "distclean"

There are a few global configuration variables (currently only installation paths) which have to be set in Makefile.conf in the top level directory of your SDK installation. These variables are described in the Compiling Tutorial

The host software is built using the Java compiler javac. If the location of javac is not in the PATH environment variable by default (Linux) it has to be appended manually (Windows), either globally, by executing

export PATH=$PATH:<directory of javac>

before calling make, or by inserting the line

PATH:=$(PATH):<directory of javac>

into the Makefile.

The standard rules for building the host software and for generating a .jar archive are defined in Makefile.mk in the top level directory of the EZ-USB SDK, see the Makefile section above. Additional files (e.g. FPGA bitstream, firmware ROM file) which should be included into the .jar archive can be specified using the EXTRAJARFILES variable.

If you want to compile the host software without using the SDK Makefiles you must ensure that the directories $PREFIX/libusbJava and $PREFIX/libusbJava are in the classpath (e.g. by specifying the -cp flag.

Compiling the firmware for the EZ-USB microcontroller is a multi step process controlled by the bmpsdcc.sh bash script in the bin directory of the SDK package. In particular bmpsdcc.sh

1. calls the macro processor and assembles the source code into one single temporary source file with the extension .tmp.c.
2. This big .tmp.c file is compiled using sdcc.
3. Then bmpsdcc.sh checks whether the device descriptors are word aligned as required by the hardware. If not, a byte is padded before the descriptors and the source code is compiled again.

The syntax of bmpsdcc.sh is

bmpsdcc.sh <C file> <bmp flags> <sdcc flags>

where

• <C file> denotes the main source file (see the ucecho example),
• <bmp flgas> denotes a list of additional parameters for the macro processor bmp -- babel macro processor given in quotes, e.g. the include search path
• <sdcc flags> denotes a list of additional parameters for sdcc given in quotes.

The standard rules for building the firmware using bmpsdcc.sh are defined in Makefile.mk in the top level directory of the EZ-USB SDK, see the Makefile section above.

The ZTEX SDK uses the Cypress EZ-USB FX3 SDK for compiling FX3 Firmware. Building process is the same. It is even possible to build the ZTEX firmware using the IDE delivered with the Cypress SDK (also see the Software requirements). You just need to ensure that the files in directory fx3 of the ZTEX SDK can be found.

Solution: Make sure that configuration variables are set up correctly, see the Compiling Tutorial

The macro processor bmp assembles the source files into one single temporary source file with .tmp.c extension. In order make backtracings of the errors possible bmp adds line meta informations to the .tmp.c files which are analyzed by sdcc. Unfortunately these line information can be ambiguous, in particular if there is a macro behind the location and on the same line where the error occurs.

Usually this happens when there is a “//” comment on the same line where the error occurs. (Background: “//” is a macro which prevents that the comment text is expanded. This is necessary in order to allow to comment out macros.)

Solution: The line informations can be suppressed by setting the LINEINFO environment variable to “no”, i.e. by executing

export LINEINFO=no

before calling make or bmpsdcc.sh, respectively. The error then can be located in the .tmp.c file.

Execute

export LINEINFO=""

in order to switch line informations on again.