1.   ispCODE Version 3.01

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


2.   Who Should Use ispCODE?

ispCODE is intended to help you  to customize the isp
programming process  if the standard Lattice 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
   IBM-PC.
2. Using a customized user interface
3. Use of the UES feature of ispLSI devices for board
   serialization (adding unique device serial numbers to the UES,
   uniquely identifying the board).

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

3.   What's Changed Between Version 2 and Version 3 of
     ispCODE?

Lattice found that much of the flexibility that came with
ispCODE Version 2 was unused by most customers. Instead,
customer changes came in one of three areas:

1.   Development of a customized user interface
2.   Altering the parallel port addressing scheme
3.   Changing the timing method  for use on non-PC
     platforms.

Since most of the ispCODE in version 2 was dealing with
other functionality, Lattice removed this unneeded
complexity and moved this functionality into the Jedec to
Bitstream conversion utility. The ispCODE could then be
simplified to a software state machine that reads the
Bitstream file and sends the information out through the
parallel port. This also makes the ispCODE device-
independent - you only need to get the latest Jedec to
Bitstream conversion utility whenever new devices are
released.  The new Bitstream file format contains all the
device dependent information, freeing the ispCODE from
knowing any specifics about the devices.
The state machine code that interprets the Bitstream file should
not be changed. However, you may need to change the two routines
that deal with the parallel port access and timing, to meet
your platform requirements. These routines are clearly
commented in the source code.

4.    Files on this Disk

dld2isp.exe     : converts JEDEC files to ispSTREAM format
express.exe     : command line programming utility
gds             : directory containing gds assembler
ispcode.c       : C source code
lattice.h       : header file for use in ispcode.c
readme.txt      : this readme file
turbo.exe       : compiled ispcode.c

     4.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 are:

    PV     Program and Verify.
    V      Verify only.
    NOP    By Pass 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.

5.   Design Flow Using ispCODE

The ispCODE reads the Lattice 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 is the file that 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 you will be programming the
ISP devices on.

     5.1. Recommended Debugging Approach

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

     5.2. Creating the DLD File

The DLD is the Lattice 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 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's 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.01.

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

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

To generate the ispSTREAM file, on DOS prompt type:

   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 from Lattice Applications a dld2isp.exe
which will use extended memory, or use a multiple DLD strategy.

The multiple DLD approach requires that you break the
programming operation up 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.

          5.2.1.    Controlling UES Programming

The "PU" operation is available only from ispCODE version
3.01, 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.
Follow 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.


     5.3. Using the UES

The UES is a user-defined  section of bits in the Lattice
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 recommends that you  use the UES editor
in the Lattice 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).

     5.3.1.    Considerations When Manually Adding the
               Checksum

The JEDEC standard allows UES data be entered in ASCII, HEX
and binary format and 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 Dec 22 14:23:20 1993
*QP120
*QF57600
*G0
*F0
*L00000
11......
........
11......
*CD079
uaA_MSG           <- Insert the U field here.
*0000


6.   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.

     6.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.

     6.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 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 as 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.

          6.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.

          6.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

          6.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 won't work when running strictly as a DOS
application -- you can use the getenv("windir") approach
explained above to see if you're 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);

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

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;
     }
}


7. ispGDS Compiler

Please read the Readme.txt file in the GDS Sub-directory for
details and the Lattice Data Book, 1994, pg 6-57, for more
information.

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

For programming the 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.

8. APPLICATIONS HOTLINE

If you have ispCODE questions, please call the Lattice
Applications Hotline at (800)327-8425 and ask to speak with an
application engineer regarding ispCODE.  Lattice 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.




