1.   ispCODE Version 3.04 and ispCODE Version 4.0

This readme file explains what is included on this disk, and
how you can use these utilities. It also documents the part
of ispCODE that can be modified.

ispCODE Version 3.04 in the file ispcode3.c supports all 
of Lattice Semiconductor's 5 Volt ispLSI devices.

ispCODE Version 4.0 in the file ispcode4.c supports all 
of Lattice Semiconductor's 3.3 Volt ispLSI devices. 

2.   Who Should Use ispCODE?

ispCODE is intended to help you customize the isp
programming process if the standard Lattice Semiconductor
IBM-PC compatible software is unable to meet your needs. 
Some examples of non-standard needs are:

1. Using a platform other than the parallel port of a PC.
2. Using a customized user interface.
3. Use of the UES feature in ispLSI devices for board
   serialization (adding unique device serial numbers to 
   the UES, to uniquely identify the board).

If you can program using the standard PC parallel port, 
then Lattice Semiconductor recommends that you use either 
the Windows or DOS download software. An up-to-date copy 
of these packages are maintained on the Lattice Semiconductor 
BBS ((503)693-0215) under the filename of ISPDAISY.ZIP.  
You can find documentation for the download software in the 
Lattice Semiconductor ISP Manual.  You can order this manual 
from the Lattice Semiconductor at 888-ISP-PLDS (888-477-7537).

If you want to use the command line version of the download
software, the program express.exe is included in this diskette
for you. 


3.    Files on this Disk

dld2isp.exe     : converts JEDEC files to ispSTREAM format for all
                  ispLSI devices.
express.exe     : command line programming utility
gds             : directory containing gds assembler
ispcode3.c      : C source code for all 5 volt ispLSI devices.
lattice.h       : header file for use in ispcode.c and ispcode4.c
readme.txt      : this readme file
turbo.exe       : compiled ispcode3.c
ispcode4.c      : C source code for all 3.3 volt ispLSI devices.
jturbo.exe      : compiled ispcode4.c


3.1. Express: Command Line Programming Utility

express.exe is a DOS command line utility that allows you to
program a daisy chain of devices sequentially. It does not
support parallel programming.

The operations supported by express.exe version 1.3 are:

    PV     Program and Verify.
    V      Verify only.
    NOP    Bypass the device.
    C      Calculate the pattern checksum of the device.
    E      Erase the device only.
    RS     Read the pattern and UES from the device and
           save it in a JEDEC file.
    RU     Read and display the UES from the device.
           (Added to V1.3)

The devices supported by express.exe version 1.3 are:
     GDS14              2064
     GDS18              2096
     GDS22              2128
     22V10              1016E
     1016               1032E
     1024               1048E
     1032               3192   (Added to V1.3)
     1048               2032LV (Added to V1.3)
     1048C              6192   (Added to V1.3)
     2032
     3256

 Note: ispLSI 2032LV devices can only be daisychained together
       with other ispLSI 2032LV devices. It can't be daisychained
       together with the other devices listed above. Please send
       e-mail to howardt@latticesemi.com for details and solutions.
     

4.   Design Flow Using ispCODE

The ispCODE reads the Lattice Semiconductor Bitstream file 
format instead of directly using JEDEC files. Included in this 
disk is the executable file DLD2ISP, which will accept a DLD file, 
and convert the JEDEC files listed in the DLD file to a single
Bitstream file.

The DLD file defines the device ordering, device type, and JEDEC 
files for a daisy chain configuration of ISP devices. The Bitstream 
file is created on a PC, and may then be transferred to the platform 
on which you will be programming the ISP devices.


4.1. Recommended Debugging Approach

The evaluation/design download option of Lattice Semiconductor's
DOS download software version 1.3 and the Run option of Lattice 
Semiconductor's Window download software version 1.3 are recommended 
for debugging isp programming problems. If command line version is 
needed, then use express.exe.


4.2. Creating the DLD File

The DLD file is the Lattice Semiconductor standard approach for 
defining the configuration of a daisy chain. The format of the file 
is straightforward: each line contains the device type, followed by 
an operation code, followed by a JEDEC file name. An example is shown 
below:

GDS22   PV      GDS22.jed
1016    PV      1016.jed
22V10   PV      22v10.jed
1032    PV      1032.jed

This DLD file represents this daisy chain:

<- from programming                            to programming ->
   signal generator                            signal generator
     +-----+       +-----+       +-----+       +-----+
SDI  |     |sdo sdi|     |sdo sdi|     |sdo sdi|     |  SDO
 --->|  1  |------>| 2   |------>| 3   |------>| 4   |---->
     |     |       |     |       |     |       |     |
     +-----+       +-----+       +-----+       +-----+
     ispGDS22      ispLSI 1016   ispGAL22v10   ispLSI 1032


You can create this file manually with an ASCII text editor,
or automatically with Lattice Semiconductor Download software. 
You must keep the following rules in mind when creating the DLD file:

1. The lines in the DLD file correspond to the position of
   the device in the chain, with the first device (the device
   whose SDI is connected to the programming port of your
   hardware) corresponding to the first line in the file.

2. The maximum number of devices supported in a daisy
   chain is currently set to 60 in all Lattice Semiconductor 
   download tools.

3. You can only use a restricted set of operations in the
   DLD file if you use dld2isp.exe to generate the
   ispSTREAM file (.isp file) for ispCODE V3.04.

     PV:  Program and Verify
     PU:  Program and verify with UES data from sources
          other than the JEDEC files.
     V:   Verify only
     NOP: Bypass the device.

   Note: ispCODE V4.0 does not support the operation PU.

Valid device names are:
     GDS14              2064
     GDS18              2096
     GDS22              2128
     22V10              1016E
     1016               1032E
     1024               1048E
     1032               3192
     1048               6192
     1048C              2032LV
     2032
     3256

To generate the ispSTREAM file, type the following at the 
DOS prompt:

   dld2isp design_name.dld.

The ispSTREAM file generated will be design_name.isp.

If the size of your daisy chain is so large that dld2isp.exe
displays the message

                  "Not Enough PC Memory" 

you can either request a dld2isp.exe from Lattice Semiconductor
Applications  which will use extended memory, or use a multiple 
DLD strategy.

The multiple DLD approach requires that you break the
programming operation into two or more Bitstream files,
and program different sets of devices with each Bitstream
file. You can accomplish this by using the NOP code for
devices you want to skip. 

For example, if you decide to break the programming operation 
into two Bitstream files, then you would create two DLD files, 
with NOPs for the first set of devices in the DLD file. Then, 
create another DLD file with NOPs for the second set of devices.  
The first Bitstream file would then program only the second set 
of devices (since the first set is NOP), and the second Bitstream 
file would only program the first set of devices.


4.2.1.    Controlling UES Programming

The "PU" operation is available only from ispCODE version 3.04, 
and allows you to customize the use of the powerful UES feature 
of ispLSI devices for your specific application and manufacturing 
flow. This field causes the ispCODE to save the UES information 
in char *ues, a string that contains all the device UES information.

Use the following procedure to customize the UES writing
procedure:

1. Use the PU code in the DLD file for each device that
   will have its UES changed.
2. Modify the program_ues routine to modify the UES with
   your desired value.

The char *ues contains the UES string that was read from the
devices prior to their erasure. The UES will be written back
out to the devices from program_ues routine. If you want to
change the UES, then change it at a point in the code prior
to the printf statement in the first few lines.


4.3. Using the UES

The UES is a user-defined section of bits in the Lattice
Semiconductor device which you can use to store any sort of 
information such as a board serial number or device version 
number. The UES is normally part of the device JEDEC file. 
Although the JEDEC file is an ASCII text file, and can be 
edited with a text editor, Lattice Semiconductor recommends 
that you  use the UES editor in the Lattice Semiconductor 
Window or DOS download software. Using the download software 
to edit the JEDEC file insures that any necessary corrections 
to the pattern and transmission checksums will be made (the 
UES of the ispGDS devices and ispGAL devices is included in 
the pattern checksum calculation, but not for ispLSI devices).


4.3.1.    Considerations When Manually Adding the Checksum

The JEDEC standard allows UES data to be entered in ASCII, 
HEX, and binary format, and to be inserted right after the 
pattern checksum. You can use a text editor to edit the JEDEC 
files directly. Please note that while the pattern checksum is 
not affected, the transmission checksum will be incorrect. So
the transmission checksum should be changed to 0000 to comply
with JEDEC standard. For example:

1. UES in ASCII Format
    CXXXX*
    UA UES IN ASCII*
    <etx>0000

2. UES in HEX Format
    CXXXX*
    UH01234567890ABCDEF*
    <etx>0000

3. UES in Binary Format
    CXXXX*
    U010100010*
    <etx>0000

Example JEDEC file:

This is a JEDEC compatible fuse file.
DESIGN NAME :  PAL61-3.lif
PART NAME   :  ispLSI1048-70LQ
CREATED BY  :  PDS+ FUSEGEN Version 1.50  9/8/93
CREATED DATE:  Wed Jun 26 14:23:20 1996
*QP120
*QF57600
*G0
*F0
*L00000
11......
........
11......
*CD079
uaA_MSG           <- Insert the U field here.
*0000


5.   ispCODE Source Code

Version 3 of ispCODE is set of C routines to read a
Bitstream file and program a chain of ISP devices
simultaneously. Since all the complex work is done by the
DLD2ISP routine when the Bitstream file is created, the
resulting ispCODE is relatively simple.

Most of the code is a state machine which parses the
Bitstream file. This state machine portion should not be
modified. The only portions of the ispCODE that you can
modify safely are the routine to read and write from the
port, and the routine to implement timing.


5.1. Modifying the Port Assignment

The ispCODE uses the standard routines inp and outp to read
and write to the port. If you wish to redirect the I/O to a
different address, then you need to create your own inp and
outp routines, and link them in with the ispCODE.

One way to do this is to make a global search and replace of
"inp" and "outp" with your own I/O routine names. Then, create 
your own I/O functions with these new names. By renaming "inp" 
and "outp" to these new names, you will redirect all I/O through 
your own functions.


5.2. Modifying the Timing Routine

It is critical that you meet the minimum pulse requirements
specified for the different ISP devices. The ispCODE calls a
single routine,  pulse_width, whenever a delay needs to be
made. This routine is passed as an argument that indicates the
number of milliseconds to wait. You may need to modify this
to work in a non-PC environment. It is important that your
version of pulse_width guarantees that the wait period is at
least as long as the argument specified. It is not critical
if the pulse width is exceeded  by a few hundred milliseconds.

The timing routine is called Pulse_Width. The calibration
procedures the routine goes through is used to compensate for
the problems that occur when running in a DOS box under Windows.
If you are not running a DOS box, you may be able to simplify
the timing procedures. Of course, it is your responsibility to
insure that the minimum pulse width times are met, regardless of
the method you use.  If minimum pulse widths are not met, device
programming may not be reliable.

Note that none of these routines guarantee that a pulse width
will not be exceeded. If running as a DOS box or Windows
application, you can be interrupted by another task, and the
pulse time may be larger than specified.


5.2.1.    DOS Only Using the Borland Compiler

The Borland compiler supplies a DOS routine called "delay"
that is accurate to within 1 ms. You can simply replace the
code in Pulse_Width with a call to delay instead, PROVIDING
that you never run the application in a DOS box. We have
measured the delay function and proven it does not work
reliably when used in an application that is running in a
DOS box.

You can put a check in your code to help insure it does not
run as a DOS box. When running in a DOS box under Windows
3.1, the environmental variable "windir" is set (as lower
case!) by Windows. Therefore, you can do a check using
getenv("windir") to see if you are running in a DOS box, and
then insure that delay is not used in that case.


5.2.2.    Windows Only

Windows 3.1 provides the multimedia services to give you
high resolution timing under Windows. If you are compiling
this as a Windows application, then include the "mmsystem.h"
header file, and implement a delay function like this:

start_time=time(NULL);             // get starting time in
                                   // seconds
timeBeginPeriod(1);                // set to one millisecond
current_time=timeGetTime();        // get the current value
while((timeGetTime()-current_time)<delay_time){
   NULL;                           // hog cpu time until
                                   // finished
}
timeEndPeriod(1);                  // free up this timer


5.2.3.    Alternative DOS Box Timing Approach

A somewhat more complicated way of controlling timing when
running in a DOS box is to use the Virtual Timer Devices
(VTD) services available from Windows. Note that this
procedure will not work when running strictly as a DOS
application -- you can use the getenv("windir") approach
explained above to see if you are running as a DOS or DOS 
box application.

You can get a 32 bit time count, incremented every
millisecond, from the VTD services by using an assembly
routine like the following:


        .MODEL large
        .DATA
vtd_addr        DD 0
        .CODE
        .386
        PUBLIC _read_timer_doswin

_read_timer_doswin     PROC

;
; this routine avoids the problems with Windows virtualizing
; the timer ports. Instead, this routine uses the VTD to get
; a 32 timer value.
;
       mov ax, 1684h                  ; get VTD address
       mov bx, 5h
       int 2fh
       mov word ptr [vtd_addr],di     ; save the address
       mov word ptr [vtd_addr+2],es
       mov ax, 0101h                  ; get current system
                                      ; time in ms
       call DWORD PTR [vtd_addr]

       ;
       ; return the values in eax in dx, ax
       ;

       mov edx, eax
       shr edx, 16                    ; return 32 bit time
                                      ; count
       ret

_read_timer_doswin       ENDP
       END

An example C program that uses this routine is shown below:

#include <stdio.h>
#include <dos.h>
void delay(unsigned int);
extern "C" unsigned long int read_timer_doswin(void);

// If C++ compiler is used, use extern to prevent name mangling

main (){
int i;

// generate an 80ms square wave on the parallel port

     for(i=0;i<=1000;i++){
          outportb(0x378,0xff);
          delay(80);
          outportb(0x378,0x00);
          delay(80);
     }
}

void delay(unsigned int wait_ms){
unsigned long int start,stop;
     start=read_timer_doswin();
     printf("%lu\n",start);
     while (read_timer_doswin()-start < wait_ms){
          NULL;
     }
}


6. ispGDS Compiler

Please read the Readme.txt file in the GDS Sub-directory for
details and the Lattice Semiconductor Data Book for more
information.

Programming ispGDS Devices
==========================

For programming ispGDS devices, please use ISP Daisy Chain
Download Software version 1.0/1.1/1.2 and connect the
ispDOWNLOAD Cable with the parallel port of an IBM compatible
PC. The GDS_PROG.EXE is no longer included with this software
package.


7. APPLICATIONS HOTLINE

If you have ispCODE questions, please call the Lattice 
Semiconductor Applications Hotline at (888)477-7537 and 
ask to speak with an applications engineer regarding ispCODE, 
or send e-mail to howardt@latticesemi.com.  Lattice Semiconductor
also maintains a BBS at (503)693-0215, which will contain the 
latest versions of ispCODE, documentation, bug reports, and a 
variety of other information and utilities.




