ispVM System Linux

Installation and Setup Manual Rev. 3.0

ispVM System Overview

Lattice's ispVM System Download software has been the industry standard for supporting In-System
Programming on PC, UNIX, and Linux systems, ATE, and the IEEE 1149.1 Tool Suite. Although ispVM
System Download software is designed with an intuitive and user-friendly GUI, the user can also execute
the program without the GUI display at the prompt as described in the following sections.

Compatibility and Compliance

The ispVM System processes JEDEC, ISC Data, and FPGA bitstream files for Lattice devices, as well as
SVF files and 1532 compliant BSDL files for any PLD devices.
The ispVM System describes the JTAG/ISP chain configuration, which uses the Extensible Chain
Description Format (XCF), by adapting the Extensible Markup Language (XML), an industrial standard.
1
The ispVM System is backward compatible in that it accepts the DLD and WCH files, from ispDCD and
2
LatticePRO respectively, as imported chain files.

System Requirements
The following are the basic system requirements for the ispVM System Linux software:
• Intel Pentium or Pentium-compatible PC
• AMD Opteron system support (32-bit OS only)
• Kernel 2.6 or above
• 110 MB disk space
• 1024 x 768 graphics display
• HTML-compatible Web browser
NOTE: The ispVM System Linux software has only been tested on Red Hat Enterprise Linux version 4.0
operating system.

Installation Procedure
Extracting the ispVM System Installation
To extract the ispVM System, move the installation file to the directory where the user wants it installed.
The installation file name is ispvm_va_b_c_os.tar.gz, where a is the major revision number, b and c
are the minor revision numbers, and os is the target operating system (either UNIX or Linux). For
example, uncompress and unpack the Linux archive as follows:
gunzip ispvm_v17_0_linux.tar.gz
tar xf ispvm_v17_0_linux.tar
After the file has been extracted, it creates the ‘isptools/ispvmsystem’ directory and
ispVMInstallation.pdf. Under the ‘ispvmsystem’ directory, the ispvm, model300,
svfdebugger, and other ispVM System tools, and the ‘Database’, and ‘ispVMEmbedded’

1
ispDCD is Lattice legacy windows download program.
2
LatticePRO (VantisPRO) is the legacy windows download program inherited from Vantis after the
Lattice-Vantis merger.

Lattice Semiconductor Corp. Page 1 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

subdirectories are created. The ‘Database’ directory contains the device support information. The
‘ispVMEmbedded’ directory contains the ispVM embedded source code and executables.
Extracting the ispVM System Device Support Update (if available)
Before extracting the device support update, ispVM System must be installed, as discussed above in
Extracting the ispVM System Installation. To extract the ispVM System device support update, move the
update file to the isptools directory. The update file name is ispvm_va_b_c_os_update.tar.gz,
where a is the major revision number, b and c are the minor revision numbers, and os is the target
operating system (either UNIX or Linux). For example, uncompress and unpack the Linux update archive
as follows:
gunzip ispvm_v17_0_1_linux_update.tar.gz
tar xf ispvm_v17_0_1_linux_update.tar
After the file has been extracted, the ispVM System will be updated to the latest version.

Setup Procedure

Setting Environment Variables (C Shell)

Set the following environment variables in the user profile (.cshrc) in the user’s home directory.
ISPVM_DIR – the directory in which the ispVM System is installed.
LD_LIBRARY_PATH – the directory in which the ispVM System’s shared libraries are installed.
path – to locate the ispVM System and other ispVM System tools are installed.

For example, in the .cshrc file, add the following lines:

setenv ISPVM_DIR /usr/local/isptools/ispvmsystem
setenv LD_LIBRARY_PATH $ISPVM_DIR/lib:$LD_LIBRARY_PATH
set path=($ISPVM_DIR $path)

If the LD_LIBRARY_PATH and the path variables are not already defined, add the following lines instead:
setenv ISPVM_DIR /usr/local/isptools/ispvmsystem
setenv LD_LIBRARY_PATH $ISPVM_DIR/lib
set path=($ISPVM_DIR)

Note: When setting an LD_LIBRARY_PATH, do not use a tilde (~) anywhere in the designated path.

After the LD_LIBRARY_PATH and path variables are updated, the user is required to login again, or
resource the profile before continuing. This will set the environment variables. To resource the user
profile, type “source ~/.cshrc” at the prompt. Type env and look for the ISPVM_DIR and
LD_LIBRARY_PATH lines to ensure they are pointing to the appropriate directories in which ispVM was
extracted to.

Lattice Semiconductor Corp. Page 2 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

Setting Environment Variables (BA Shell)

Set the following environment variables in the user profile (.bashrc) in the user’s home directory.
ISPVM_DIR – the directory in which the ispVM System is installed.
LD_LIBRARY_PATH – the directory in which the ispVM System’s shared libraries are installed.
path – to locate the ispVM System and other ispVM System tools are installed.

For example, in the .bashrc file, add the following lines:

ISPVM_DIR = /usr/local/isptools/ispvmsystem
export ISPVM_DIR
LD_LIBRARY_PATH = $LD_LIBRARY_PATH:$ISPVM_DIR/lib
export LD_LIBRARY_PATH
PATH = $PATH:$ISPVM_DIR
export PATH

If the LD_LIBRARY_PATH and the path variables are not already defined, add the following lines instead:
ISPVM_DIR = /usr/local/isptools/ispvmsystem
export ISPVM_DIR
LD_LIBRARY_PATH = $ISPVM_DIR/lib
export LD_LIBRARY_PATH
PATH = $ISPVM_DIR
export PATH

Note: When setting an LD_LIBRARY_PATH, do not use a tilde (~) anywhere in the designated path.

After the LD_LIBRARY_PATH and path variables are updated, the user is required to login again, or
resource the profile before continuing. This will set the environment variables. To resource the user
profile, type “source ~/.bashrc” at the prompt. Type env and look for the ISPVM_DIR and
LD_LIBRARY_PATH lines to ensure they are pointing to the appropriate directories in which ispVM was
extracted to.

Lattice Semiconductor Corp. Page 3 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

Setting Up the Hardware

Parallel Port Cable Configuration
IMPORTANT: Before using the ispDOWNLOAD parallel port cable, the workstation’s parallel port must be
enabled and have the correct read/write permission. Please contact the system administrator if the
parallel port is not enabled or does not have the correct read/write permission.
You can check the current permissions of the parallel port by navigating to the /dev directory and doing a
lookup on the port.
cd /dev
ls –l parport0
There are two main ways to give read/write permission to the parallel port.
The first is to give read/write permission to the parallel port to anyone that has access to that machine.
The second is more secure, where only selected individuals will have read/write permission to the parallel
port that has access to that machine.
Below are the descriptions on how to setup parallel port zero to have read/write permission.
A. How to give parallel port zero read/write permission to everyone.
Log in as root or have root permission to make the following change:
1. Log in as root.
2. Go to the /dev directory.
cd /dev <return>
3. Give read/write permission to parallel port zero (parport0).
chmod 666 parport0 <return>
B. How to give parallel port zero read/write permission to selected individuals.
There are two files to change on the machine to give selected individuals read/write permission to
parallel port zero. Both files are located in the /etc directory. The two files are “group” and
“nsswitch.conf”.
1. Log in as root.
2. Go to the /dev directory.
cd /dev <return>
3. Give read/write permission to parallel port zero (parport0) to owner and group.
chmod 660 parport0 <return>
4. Go to the /etc directory.
cd /etc <return>
5. Using your favorite text editor, edit the file “group”.
6. Add the login name for all the users you want to give read/write permission for parallel port zero
by adding the login names to the “lp:x:7:” line. This line may vary from system to system. Two
examples are shown below.

Lattice Semiconductor Corp. Page 4 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

Example 1:
Change:
lp:x:7:
To:
lp:x:7:user_name1,user_name2,etc
Example 2:
Change:
lp:x:7:daemon,lp
To:
lp:x:7:daemon,lp,user_name1,user_name2,etc
Where user_name1, etc. is the login name for all the users you want to give read/write
permission for parallel port zero. Save the changes and close the “group” file.
7. Using your favorite text editor, edit the file “nsswitch.conf”.
8. Look at the group line. Make sure “files” is there.
Example:
group: files nis
9. If “files” is there then you’re done. You may need to reboot for the changes to take affect.

USB Cable Configuration

The ispVM System software can directly access USB devices using libusb, which accesses the USB file
system. To verify that you have the USB library installed, do the following:
1. Plug in the USB cable.
2. Type /sbin/lsusb on the command line
You should see an entry similar to the following:
> Bus 002 Device 002: ID 1134:8001
3. If you receive an error when you type /sbin/lsusb, you probably do not have libusb installed.
To install the libusb, go to:
http://libusb.sourceforge.net/
4. Unplug the cable.
Two types of installations are available for the USB cable: automatic and manual. We recommend that
you follow the instructions for the automatic setup first. If you encounter any issues or would like a more
customized setup, proceed with the manual instructions. Both methods require that you have root access
and are able to log in as super user.
NOTE: The USB cable must be disconnected from the PC when performing the installations.

Lattice Semiconductor Corp. Page 5 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

USB Driver Setup on RedHat Linux Enterprise 5 and Above

Automated UDEV Method Configuration:

The automated configuration script adds lines in the file /etc/udev/udev.conf, creates the file
/etc/udev/usb/rules.d/10-local.rules and /etc/security/console.perms.d/lattice.perms.
1. Navigate to the directory where you installed the ispVM System. The default directory is
isptools/ispvmsystem.
2. Grant execute permissions to the udevsetup.sh script by typing the following command:
sudo chmod 755 udevsetup.sh
3. Make sure that you are in the directory where the udevsetup.sh script is located.
4. Type the following command to execute the script:
sudo ./udevsetup.sh
The script should terminate with a “Setup successful” output.

Manual UDEV Method Configuration:

1. Create a working file called 10-local.rules
2. Add the following information to the 10-local.rules file
#Lattice
BUS=="usb",ACTION=="add",SYSFS{idVendor}=="1134",SYSFS{idProduct}=="800
1", \ MODE==”0660”,OWNER==”root”,SYMLINK+="lattice-%n"
• Note: Make sure everything after BUS== is on one line
3. Copy the file into /etc/udev/rules.d/10-local.rules directory. If a file by this name already exists
simply append the working file to it.
sudo cp 10-local.rules /etc/udev/rules.d/.
Or if the file already exists
sudo cat 10-local.rules >>/etc/udev/rules.d/10-local.rules

4. Create a working file called lattice.perms

5. Add the following information to the lattice.perms file:
<lattice>=/dev/lattice*
<console>0660 <lattice>0660 root
• Note: Make sure to enter a new line after lattice*

6. Copy the file into /etc/security/console.perms.d directory

sudo cp lattice.perms /etc/security/console.perms.d/.
Or if the file already exists
sudo cat lattice.perms >>/etc/security/console.perms.d/lattice.perms

7. Make the new UDEV settings active

sudo skill -HUP udevd
Correctly configured UDEV will create new entries into the /dev directory each time a Lattice
programming cable is attached to the system. The programming cable will be owned by the user
currently logged in at the console.
When you edit the file, pay attention to the spacing since some statements are sensitive to the
omission of spaces.

Lattice Semiconductor Corp. Page 6 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

Below is the link of the documentation on how to setup UDEV rules for Red Hat for more information
http://www.redhat.com/magazine/002dec04/features/udev/

USB Driver Setup on RedHat Linux Enterprise 5 and Below

Automated Hot Plug Method Configuration:

The automated configuration script adds a line in the file /etc/hotplug/usb.usermap and creates
the file /etc/hotplug/usb/usbcable.
5. Navigate to the directory where you installed the ispVM System. The default directory is
isptools/ispvmsystem.
6. Grant execute permissions to the usbsetup.sh script by typing the following command:
chmod 777 usbsetup.sh
7. Log in as root (super user) with the following command:
su
8. Make sure that you are in the directory where the usbsetup.sh script is located.
9. Type the following command to execute the script:
./usbsetup.sh
The script should terminate with a “Setup successful” output.

Manual Hot Plug Method Configuration:

If you received an error message with the automated configuration, use the following manual
configuration instructions. You can also use this method for a customized setup.
4. Log in as root (super user) with the following command:
su
5. Edit the /etc/hotplug/usb.usermap file by appending the following line to the end of the file:
usbcable 0x0003 0x1134 0x8001 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00
0x00 0x00000000
6. Use one of the following methods to create the script that will be executed each time the usb
device is inserted:
• Manually create the /etc/hotplug/usb/usbcable file.
In the following example, the device is owned by “root,” the group is assigned to “usbusers,”
and the device is readable and writable by both “root” and “usbusers.”
#!/bin/bash
if [ “${ACTION}” = “add” ] && [ -f “${DEVICE}” ]
then
chown root “${DEVICE}”
chgrp usbusers “${DEVICE}”
chmod 660 “${DEVICE}”
fi

Lattice Semiconductor Corp. Page 7 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

When you create the usbcable file, pay attention to the spacing since some statements are
sensitive to the omission of spaces.
• Copy the Linux usbcam file and save it as usbcable.
On most versions of Linux, a usbcam script is available that changes the device ownership to
the user who inserts the cable and logs into the console. The usbcam script is located in the
same /etc/hotplug/ directory.
If you prefer to use this script, copy the usbcam file and save it as usbcable.
7. Grant the script execute permission
chmod 755 usbcable
NOTE: The USB cable must be removed and reinserted whenever one user logs out and another user
logs in. Otherwise, the system will still recognize the previous user as the owner of the cable, and an error
message will be generated.
FTDI USB Host Chip Configuration
libftd2xx- A library (using libusb) to talk to FTDI's UART/FIFO chips including the popular bitbang mode.
ispVM using the libftd2xx.so.0.4.13 version which included under ispvmsystem\Drivers\FTDIUSBDriver
directory.

Installation:

1. Go to the ispvmsystem\Drivers\FTDIUSBDriver directory

2. As root user copy the following files to /usr/local/lib

cp libftd2xx.so.0.4.13 /usr/local/lib

3. Change directory to /usr/local/lib

cd /usr/local/lib

4. make symbolic links to these files using the following commands:

ln -s libftd2xx.so.0.4.13 libftd2xx.so

5. Change directory to /usr/lib

cd /usr/lib

6. make symbolic links to these files using the following commands:

ln -s /usr/local/lib/libftd2xx.so.0.4.13 libftd2xx.so

7. Add the following line to /etc/fstab:

none /proc/bus/usb usbdevfs defaults,devmode=0666 0 0
There have been reports that you may need to use the following command for some distros
none /proc/bus/usb usbdevfs defaults,mode=0666 0 0 (use usbfs in 2.6 kernels)

8. Remount all in the fstab file

mount -a

If you have problems with this check with usbview (search on the internet for application or it can be sent
to you by ftdi) to check the usb file system is mounted properly.

Lattice Semiconductor Corp. Page 8 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

Starting the ispVM System Download Software

To start the ispVM System Download UNIX or Linux GUI, type “ispvm” at the prompt.
Note: ispVM was compiled using gcc version 4.1.2

Using the ispVM System Command Line

The following shows the syntax for the ispVM system UNIX or Linux command line:

Syntax
<drive>:\<ispvm directory>\ispVM [-help] |
-infile “<input file path>”
[-logfile “<log file path>” ]
<-processtype <turbo | sequential>
-cabletype < lattice [-portaddress <0x0378 | 0x0278 | 0x03bc | 0x<custom address> > ] |
usb [-portaddress <ezusb-0 | ezusb-1 | ezusb-2 | ezusb-3 |
ezusb-4 | ezusb-5 | ezusb-6 | ezusb-7 |
ezusb-8 | ezusb-9 | ezusb-10 > ] |
usb2 [-portaddress <ftusb-0 | ftusb-1 | ftusb-2 | ftusb-3 |
ftusb-4 | ftusb-5 > ] |
]>|
-outfiletype <-svf [-outfile “<output file path>” ] |
-svf_rev_c [-outfile “<output file path>” ] |
-svf_rev_d [-outfile “<output file path>” ] |
-svf_rev_c_d [-outfile “<output file path>” ] |
-vme12 [-outfile “<output file path>” ] |
-vme11 [-outfile “<output file path>” ] |
-vme10 [-outfile “<output file path>” ] |
-vme9 [-outfile “<output file path>” ] |
-vme8 [-outfile “<output file path>” ] |
-slim [-algofile “<output file path>” -datafile “<output file path>” ] >
-slim1 [-algofile “<output file path>” -datafile “<output file path>” ] >
-slim2 [-algofile “<output file path>” -datafile “<output file path>” ] >
-cpu [-outfile “<output file path>” ] |
-stp [-outfile “<output file path>” ] |
-encryption
>
[-o | -w]
Example
ispvm -infile “../demo/demo.xcf” -processtype turbo -cabletype lattice -portaddress
0x0278
ispvm -infile “../demo/demo.xcf” -outfiletype -svf
ispvm -infile “../demo/demo.xcf” -key -hex \"000000004C6174746963652053656D69\"

Description

Input File (required)

-infile filename.xcf – Chain Configuration File (.xcf). If the file path includes spaces, enclose
the path in quotes.
-infile filename.dld – Configuration Setup File (.dld). If the file path includes spaces, enclose
the path in quotes.

Lattice Semiconductor Corp. Page 9 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

Process Type (optional)

-processtype sequential – Process using Sequential mode
-processtype turbo – Process Using Turbo mode
Default is process using Sequential mode. This option is only valid when processing directly to the cable. It is
not valid with the –outfiletype option.

Cable Type (optional)

-cabletype lattice – Lattice parallel port ispDOWNLOAD cable
-cabletype usb – Lattice USB port ispDOWNLOAD cable
-cabletype usb2 – FTDI USB Host chip cable
Default is Lattice parallel port ispDOWNLOAD cable.

Parallel Port Address (optional)

-portaddress 0x0378 – LPT1 parallel port
-portaddress 0x0278 – LPT2 parallel port
-portaddress 0x03BC – LPT3 parallel port
-portaddress 0x<custom address> – Custom parallel port address
Default is 0x0378 LPT1 parallel port.

USB Port Address (optional)

-portaddress ezusb-0 - ezusb-15 – USB cable number 0 through 15
Default is Ezusb-0. Only valid with the USB port cables
-portaddress ftusb-0 - ftusb-9 – USB cable number 0 through 9
Default is ftusb-0. Only valid with the FTDI USB Host chip cables

Process Output (optional)

-outfiletype -svf – Generate Lattice SVF file format
-outfiletype -svf_rev_c –Generate Revision C SVF Format
-outfiletype -svf_rev_d –Generate Revision D SVF Format
-outfiletype -svf_rev_c_d –Generate Revision C and D SVF Format
-outfiletype -vme12 – Generate VME file version 12
-outfiletype -vme11 – Generate VME file version 11
-outfiletype -vme10 – Generate VME file version 10
-outfiletype –vme9 – Generate VME file version 9
-outfiletype –vme8 – Generate VME file version 8
-outfiletype –slim – Generate a Slim VME file version 1.3
-outfiletype –slim1 – Generate a Slim VME file version 1.2
-outfiletype –slim2 – Generate a Slim VME file version 1.1
-outfiletype –cpu – Generate a sysCONFIG embedded bitstream
-outfiletype –stp – Generate a STAPL (The Jam Standard Test and Programming
Language) file format

Default is process as set in XCF file.

Output File (optional)

Used with Process Output.
outputfilename.svf – SVF File Name (.svf)
outputfilename.vme – VME File Name (.vme)

Lattice Semiconductor Corp. Page 10 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

outputfilename.cpu – VME File Name (.cpu)

outputfilename.stp – VME File Name (.stp)

Default will use the .xcf or .dld file name. If the file path includes spaces, enclose the path in quotes.

Encryption Mode (optional)

-encryption: specify the advanced security options
[ -key specify the encryption key ]
[ -hex specify the encryption key in hex. 'hex_key' must be provided in hex and contain at most 32 characters ]
[ -ascii specify the encryption key in ASCII. 'ascii_key' must contain at most 16 characters ]
[ -protect specify the Flash protect key ]
[ -hex specify the Flash protect key in hex. 'hex_key' must be provided in hex and contain at most 16 characters ]
[ -ascii specify the Flash protect key in ASCII. 'ascii_key' must contain at most 8 characters ]

Process Mode (optional)

-h – Silent Mode
-o – Message Mode
Default is Silent mode.

Return Codes

Code Definition
0 Success
-1 Log file error
-2 Check configuration setup error
-3 Out of memory error
-4 NT driver error
-5 Cable not detected error
-6 Power detection error
-7 Device not valid error
-8 File not found error
-9 File not valid error
-10 Output file error
-11 Verification error
-12 Unsupported operation error
-13 File name error
-14 File read error
-15 Build SVP file error
-16 Build BJD file error
-17 Build SVF file error
-18 Build VME file error
-19 Build STAPL file error
-20 Build CPU file error
-21 Command line syntax error

Lattice Semiconductor Corp. Page 11 of 12

 ispVM System Linux
Installation and Setup Manual Rev. 3.0

Known Issues

1. A super user is required to change the permissions of the serial and parallel ports if the user does not
have proper read/write permission to the ports.
2. Using a serial port cable that is longer than six feet might cause inconsistent results.
3. ispDOWNLOAD Cable TRST Pin
Connecting the board’s TRST pin to the cable’s TRST pin is not recommended. If the board’s TRST
pin is connected to the cable’s TRST pin, instruct the ispVM System to drive the TRST pin high as
follows:
i. Select the Options menu item,
ii. Select Cable and I/O Port Setup,
iii. Check the TRST/Reset Pin Connected check box, and
iv. Select the Set High radio button.
If the proper option is not selected, the TRST pin will be driven low by the ispVM System.
Consequently, the BSCAN chain will not work because the chain is locked into RESET state.
4. ispDOWNLOAD Cable ISPEN Pin
The following pins should be grounded: the BSCAN pin of the 2000VE devices and the ENABLE pin
of MACH4A3/5-128/64, MACH4A3/5-64/64 and MACH4A3/5-256/128 devices. However, the user has
the option of having the BSCAN and ENABLE pins driven by the ISPEN pin from the cable, in which
case the ispVM System must be set to drive the ISPEN pin low as follows:
i. Select the Options menu item,
ii. Select Cable and I/O Port Setup,
iii. Check the ispEN/BSCAN Pin Connected check box, and
iv. Select the Set Low radio button.
5. ispVM System Linux currently does not support importing the WCH file.
6. ispVM System Linux Embedded (ispVME) currently only supports single device chains.
7. ispVM Linux VME Processor currently does not support Version 9 VME files.
8. ispVM Linux: When using the Usercode Editor, click the Read button before changing and saving the
new Usercode value.

Lattice Semiconductor Corp. Page 12 of 12