path: root/README-DEVELOPERS.lyx

#LyX 2.0 created this file. For more info see http://www.lyx.org/
\lyxformat 413
\begin_document
\begin_header
\textclass article
\use_default_options false
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize default
\use_hyperref false
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\use_mathdots 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 0
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title
Toprammer - Developers guide
\end_layout

\begin_layout Section
Definitions
\end_layout

\begin_layout Description
DUT Device Under Test.
 The device put into the ZIF socket of the programmer
\end_layout

\begin_layout Description
VPP Programming voltage for the DUT (usually 12V)
\end_layout

\begin_layout Description
VCC Supply voltage for the DUT
\end_layout

\begin_layout Description
GND Ground for the DUT
\end_layout

\begin_layout Description
ZIF Zero Insert Force socket of the programmer.
\end_layout

\begin_layout Section
TOP2049 device hardware
\end_layout

\begin_layout Standard
The TOP2049 consists of four basic hardware parts
\end_layout

\begin_layout Itemize
USB interface (PDIUSBD12 chip)
\end_layout

\begin_layout Itemize
Microcontroller (Megawin MPC89E52A)
\end_layout

\begin_layout Itemize
FPGA (Xilinx Spartan2 XC2S15)
\end_layout

\begin_layout Itemize
VCC/GND/VPP supply circuitry
\end_layout

\begin_layout Standard
The microcontroller's job is to initialize and communicate to the FPGA and
 set up the VCC/GND/VPP supply circuitry.
 The microcontroller can receive commands via USB interface to do these
 things.
\end_layout

\begin_layout Section
Communicating with the programmer via USB
\end_layout

\begin_layout Standard
In the 
\begin_inset Quotes eld
\end_inset

main
\begin_inset Quotes erd
\end_inset

 module there is the 
\begin_inset Quotes eld
\end_inset

class TOP
\begin_inset Quotes erd
\end_inset

 which is used for communication with the programmer device.
 The class has various methods for hardware access:
\end_layout

\begin_layout Subsection
cmdRequestVersion()
\end_layout

\begin_layout Standard
Reads the programmer identification and versioning string and returns it.
\end_layout

\begin_layout Subsection
getOscillatorHz()
\end_layout

\begin_layout Standard
Returns the frequency (in Hz) of the oscillator connected to the FPGA clk
 pin.
\end_layout

\begin_layout Subsection
getBufferRegSize()
\end_layout

\begin_layout Standard
Returns the size of the 
\begin_inset Quotes eld
\end_inset

buffer register
\begin_inset Quotes erd
\end_inset

.
\end_layout

\begin_layout Subsection
cmdReadBufferReg(nrBytes=all)
\end_layout

\begin_layout Standard
Reads the 
\begin_inset Quotes eld
\end_inset

buffer register
\begin_inset Quotes erd
\end_inset

 from the microcontroller.
 That register is used for buffering of data fetched from the FPGA.
 If nrBytes is not specified, it reads the whole register.
\end_layout

\begin_layout Subsection
cmdReadBufferReg8()
\end_layout

\begin_layout Standard
Same as cmdReadBufferReg(), but just returns a 8bit int which was formed
 by the first 1 byte of the register.
\end_layout

\begin_layout Subsection
cmdReadBufferReg16()
\end_layout

\begin_layout Standard
Same as cmdReadBufferReg(), but just returns a 16bit int which was formed
 by the first 2 bytes of the register (little endian).
\end_layout

\begin_layout Subsection
cmdReadBufferReg32()
\end_layout

\begin_layout Standard
Same as cmdReadBufferReg(), but just returns a 32bit int which was formed
 by the first 4 bytes of the register (little endian).
\end_layout

\begin_layout Subsection
cmdReadBufferReg48()
\end_layout

\begin_layout Standard
Same as cmdReadBufferReg(), but just returns a 48bit int which was formed
 by the first 6 bytes of the register (little endian).
\end_layout

\begin_layout Subsection
cmdSetVPPVoltage(voltage)
\end_layout

\begin_layout Standard
Set VPP (programming voltage) to the specified voltage.
 Voltage is a floating point number.
\end_layout

\begin_layout Subsection
cmdSetVCCVoltage(voltage)
\end_layout

\begin_layout Standard
Set VCC (DUT supply voltage) to the specified voltage.
 Voltage is a floating point number.
\end_layout

\begin_layout Subsection
cmdLoadGNDLayout(layoutID)
\end_layout

\begin_layout Standard
Load a ZIF-socket GND-layout.
 You usually don't want to call this directly.
 Use an autogenerated layout instead.
\end_layout

\begin_layout Subsection
cmdLoadVPPLayout(layoutID)
\end_layout

\begin_layout Standard
Load a ZIF-socket VPP-layout.
 You usually don't want to call this directly.
 Use an autogenerated layout instead.
\end_layout

\begin_layout Subsection
cmdLoadVCCLayout(layoutID)
\end_layout

\begin_layout Standard
Load a ZIF-socket VCC-layout.
 You usually don't want to call this directly.
 Use an autogenerated layout instead.
\end_layout

\begin_layout Subsection
cmdEnableZifPullups(enable)
\end_layout

\begin_layout Standard
Enable (True) or disable (False) the pullups for all signals on the ZIF
 socket.
 Default is disabled.
\end_layout

\begin_layout Subsection
cmdFPGAWrite(address, byte)
\end_layout

\begin_layout Standard
Writes a byte to the FPGA using 
\begin_inset Quotes eld
\end_inset

address
\begin_inset Quotes erd
\end_inset

 for address latching and 
\begin_inset Quotes eld
\end_inset

byte
\begin_inset Quotes erd
\end_inset

 as payload data.
 Note that address 0x10 is fast-tracked and uses one byte less on the USB
 bus.
 So it is potentially faster.
\end_layout

\begin_layout Subsection
cmdFPGARead(address)
\end_layout

\begin_layout Standard
Reads a byte from the FPGA and puts it into the buffer register.
 
\begin_inset Quotes eld
\end_inset

address
\begin_inset Quotes erd
\end_inset

 is used for address latching on the FPGA.
 The microcontroller's buffer register has an automagically incrementing
 pointer.
 So issueing several cmdFPGARead() in a row will result in all the bytes
 being put one after another into the buffer register.
 The buffer register does have a limited size.
 Overflowing it crashes the programmer, requireing a physical USB disconnect
 to recover.
 Call getBufferRegSize() to get the size of the buffer register.
 Reading the buffer register (cmdReadBufferReg()) will reset the automagic
 pointer to zero.
 Note that address 0x10 is fast-tracked and uses one byte less on the USB
 bus.
 So it is potentially faster.
\end_layout

\begin_layout Subsection
cmdDelay(seconds)
\end_layout

\begin_layout Standard
Send a delay command to the programmer.
 The Programmer will perform the delay.
 A value up to 0.5 seconds is possible.
 Note that the actual value will be rounded up to the next possible wait
 interval value.
 Use this for short (microsecond or low millisecond) delays.
 Note that this does _not_ flush the command queue.
\end_layout

\begin_layout Subsection
hostDelay(seconds)
\end_layout

\begin_layout Standard
Sends all queued commands to the device and waits for 
\begin_inset Quotes eld
\end_inset

seconds
\begin_inset Quotes erd
\end_inset

.
 
\begin_inset Quotes eld
\end_inset

seconds
\begin_inset Quotes erd
\end_inset

 is a floating point number.
 The delay is performed on the host computer by simply not sending commands
 to the programmer for the time specified after flushing the command queue.
\end_layout

\begin_layout Section
TX command queueing
\end_layout

\begin_layout Standard
All commands transmitted to the device are not sent immediately, but queued
 in software and sent later.
 This is done to speed up device access significantly.
 The command transmission queue has several flushing conditions:
\end_layout

\begin_layout Itemize
Commands can be flushed explicitely using the 
\begin_inset Quotes eld
\end_inset

flushCommands()
\begin_inset Quotes erd
\end_inset

 method of 
\begin_inset Quotes eld
\end_inset

class TOP
\begin_inset Quotes erd
\end_inset

.
 
\end_layout

\begin_layout Itemize
Commands are automatically flushed on cmdReadBufferReg() before reading
 the data from the device.
 This is to ensure sequential consistency of the commands.
\end_layout

\begin_layout Itemize
Commands are flushed on various voltage-layout operations.
\end_layout

\begin_layout Standard
You usually do not need to flush commands explicitely.
\end_layout

\begin_layout Section
Implementing a new chip (DUT) algorithm
\end_layout

\begin_layout Standard
The reading and programming algorithms for the chips (DUTs) are separated
 into two parts:
\end_layout

\begin_layout Itemize
Low level FPGA bottom-half
\end_layout

\begin_layout Itemize
High level Python code top-half
\end_layout

\begin_layout Standard
The FPGA bottom-half implements the basic operations (fetching data from
 DUT.
 Writing data to DUT.
 etc...).
 It may also implement timingcritical parts of the algorithm.
 Everything else is implemented in the high level Python code, that lives
 on the other end of the USB line.
\end_layout

\begin_layout Subsection
Python top-half implementation
\end_layout

\begin_layout Standard
The DUT specific top-half lives in the 
\begin_inset Quotes eld
\end_inset

libtoprammer/chips
\begin_inset Quotes erd
\end_inset

 module.
 The files in that module contain the top-half algorithm implementation.
 The files are named after the chip ID.
 Make sure to update the __init__.py of the module when adding algorithm
 implementations.
 The top-half files contain a class derived from the 
\begin_inset Quotes eld
\end_inset

Chip
\begin_inset Quotes erd
\end_inset

 class.
 The 
\begin_inset Quotes eld
\end_inset

Chip
\begin_inset Quotes erd
\end_inset

 class defines the interface that is to be re-implemented in the derived
 subclass.
 This interface consists of the following methods:
\end_layout

\begin_layout Description
shutdownChip() Called once on chip shutdown.
 The default implementation turns off all voltages.
 There's usually no need to override that.
\end_layout

\begin_layout Description
readSignature() Read the DUT signature and return it.
 Reimplement this, if your DUT supports signature reading.
\end_layout

\begin_layout Description
erase() Erase the DUT.
 Reimplement this, if your DUT supports electrical erasing.
\end_layout

\begin_layout Description
test() Run an optional unit-test on the chip.
 The generic algorithm GenericAlgorithms.simpleTest may be used to implement
 this method.
\end_layout

\begin_layout Description
readProgmem() Read the program memory and return it.
 Reimplement this, if your DUT has program memory and supports reading it.
\end_layout

\begin_layout Description
writeProgmem(image) Write the program memory.
 Reimplement this, if your DUT has program memory and supports writing it.
\end_layout

\begin_layout Description
readEEPROM() Read the (E)EPROM memory and return it.
 Reimplement this, if your DUT has (E)EPROM memory and supports reading
 it.
\end_layout

\begin_layout Description
writeEEPROM() Write the (E)EPROM memory.
 Reimplement this, if your DUT has (E)EPROM memory and supports writing
 it.
\end_layout

\begin_layout Description
readFuse() Read the Fuse memory and return it.
 Reimplement this, if your DUT has Fuses and supports reading them.
\end_layout

\begin_layout Description
writeFuse() Write the Fuse memory.
 Reimplement this, if your DUT has Fuses and supports writing them.
\end_layout

\begin_layout Description
readLockbits() Read the Lockbit memory and return it.
 Reimplement this, if your DUT has Lockbits and supports reading them.
\end_layout

\begin_layout Description
writeLockbits() Write the Lockbit memory.
 Reimplement this, if your DUT has Lockbits and supports writing them.
\end_layout

\begin_layout Description
readRAM() Read the Random Access Memory.
 Reimplement this, if your DUT has RAM and supports reading it.
\end_layout

\begin_layout Description
writeRAM() Write the Random Access Memory.
 Reimplement this, if your DUT has RAM and supports writing to it.
\end_layout

\begin_layout Standard
After defining your 
\begin_inset Quotes eld
\end_inset

Chip
\begin_inset Quotes erd
\end_inset

-derived class you need to register it.
 This is done by defining a ChipDescription():
\end_layout

\begin_layout LyX-Code
ChipDescription(Chip_MyDevice, bitfile = 
\begin_inset Quotes eld
\end_inset

bitfileID
\begin_inset Quotes erd
\end_inset

, chipID = 
\begin_inset Quotes eld
\end_inset

myChipID
\begin_inset Quotes erd
\end_inset

)
\end_layout

\begin_layout Standard
The chip class (_not_ an instance of it) is passed as first parameter.
 The ID string of the required bitfile is past as second parameter.
 A chipID might also be passed.
 If the chipID is omitted, the bitfileID is used as chipID.
 There are more optional parameters to ChipDescription().
 See the inline sourcecode documentation for details.
\end_layout

\begin_layout Subsection
Generic top-half algorithms
\end_layout

\begin_layout Standard
The Python class 
\begin_inset Quotes eld
\end_inset

GenericAlgorithms
\begin_inset Quotes erd
\end_inset

 in the generic_algorithms.py file provides several generic chip access algorithm
s that can be used in the 
\begin_inset Quotes eld
\end_inset

Chip
\begin_inset Quotes erd
\end_inset

 methods.
\end_layout

\begin_layout Subsection
FPGA bottom-half implementation
\end_layout

\begin_layout Standard
For the FPGA part you need to get the Xilinx development suite (ISE) version
 10.1 service pack 3.
 The "WebPACK", which is sufficient for our purposes, can be downloaded
 for free (as in beer) from the Xilinx homepage:
\end_layout

\begin_layout LyX-Code
http://www.xilinx.com/support/download/index.htm
\end_layout

\begin_layout Standard
To create a new sourcecode template fileset for a new chip, go to the libtopramm
er/fpga/src/ subdirectory and execute the "create.sh" script:
\end_layout

\begin_layout LyX-Code
./create.sh bitfile_name
\end_layout

\begin_layout Standard
Where "bitfile_name" is the name of the new chip's bitfile.
 (That often matches the chip-ID).
 Now go to libtoprammer/fpga/src/bitfile_name/ and implement the bottom-half
 algorithm in the bitfile_name.v Verilog file.
 To build the .BIT file from the Verilog sources, go to the libtoprammer/fpga/
 directory and execute:
\end_layout

\begin_layout LyX-Code
./build.sh bitfile_name
\end_layout

\begin_layout Standard
If you omit the 
\begin_inset Quotes eld
\end_inset

bitfile_name
\begin_inset Quotes erd
\end_inset

, all bitfiles will be rebuilt.
 The resulting .BIT file will be copied to the libtoprammer/fpga/bin/ directory,
 after build finished successfully.
\end_layout

\begin_layout Section
Automatic layout generator
\end_layout

\begin_layout Standard
The automatic layout generator (layout_generator.py) can be used to automatically
 generate a VCC/VPP/GND layout.
 The generator will then tell you how to insert the chip into the ZIF socket.
 The advantage of using the autogenerator instead of hardcoding the VCC/VPP/GND
 connections in the chip implementation is that the autogenerated layout
 is portable between TOPxxxx programmers and it is much easier to implement.
 You do not have to search for a chip position in the ZIF socket that fits
 the device constraints.
 The autogenerator will do it for you.
\end_layout

\begin_layout Standard
The chip interface of the autogenerator is embedded into 
\begin_inset Quotes eld
\end_inset

class Chip
\begin_inset Quotes erd
\end_inset

.
 So you don't have to work with 
\begin_inset Quotes eld
\end_inset

class LayoutGenerator
\begin_inset Quotes erd
\end_inset

 directly.
 You'll do it through 
\begin_inset Quotes eld
\end_inset

class Chip
\begin_inset Quotes erd
\end_inset

 instead.
 So let's look at 
\begin_inset Quotes eld
\end_inset

class Chip
\begin_inset Quotes erd
\end_inset

s autogenerator interface.
\end_layout

\begin_layout Standard
The constructor (__init__()) has some autogenerator related parameters:
\end_layout

\begin_layout Description
chipPackage This parameter is a string identifying the package type of the
 DUT chip.
 It is something like 
\begin_inset Quotes eld
\end_inset

DIP28
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

DIP40
\begin_inset Quotes erd
\end_inset

, etc...
 .
 If this parameter is passed to the constructor, the autogenerator is enabled.
\end_layout

\begin_layout Description
chipPinVCC This parameter is an integer specifying the VCC pin on the chip
 package.
 Note that it specifies the VCC pin on the chip package and _not_ on the
 ZIF socket.
 So if your chip datasheet tells you that VCC is on pin 8, you pass an 8
 here.
\end_layout

\begin_layout Description
chipPinsVPP This parameter is an integer or a list of integers specifying
 the VPP pin(s) on the chip package.
 Note that it specifies the VPP pin on the chip package and _not_ on the
 ZIF socket.
 So if your chip datasheet tells you that VPP is on pin 1, you pass a 1
 here.
 If your chip needs multiple VPP voltages, just pass a list of pins.
 Specify all possible VPP pins here.
 Which pin is actually activated is decided later in applyVPP().
\end_layout

\begin_layout Description
chipPinGND This parameter is an integer specifying the GND pin on the chip
 package.
 Note that it specifies the GND pin on the chip package and _not_ on the
 ZIF socket.
 So if your chip datasheet tells you that GND is on pin 5, you pass a 5
 here.
\end_layout

\begin_layout Standard
After passing all parameters to the 
\begin_inset Quotes eld
\end_inset

class Chip
\begin_inset Quotes erd
\end_inset

 constructor, the autogenerator is initialized and ready to be used.
 The following 
\begin_inset Quotes eld
\end_inset

class Chip
\begin_inset Quotes erd
\end_inset

 methods can be used to enable or disable a layout:
\end_layout

\begin_layout Description
applyVCC(on) This method enables or disables (depending on the 
\begin_inset Quotes eld
\end_inset

on
\begin_inset Quotes erd
\end_inset

 parameter) the VCC layout.
 Enabling the layout means that the VCC pin will be actively driven by the
 configured VCC voltage.
 Disabling the layout will tristate the driver.
\end_layout

\begin_layout Description
applyVPP(on,packagePinsToTurnOn) This method enables or disables (depending
 on the 
\begin_inset Quotes eld
\end_inset

on
\begin_inset Quotes erd
\end_inset

 parameter) the VPP layout.
 Enabling the layout means that the VPP pins will be actively driven by
 the configured VPP voltage.
 Disabling the layout will tristate the driver.
 The first parameter 
\begin_inset Quotes eld
\end_inset

on
\begin_inset Quotes erd
\end_inset

 is a boolean to turn ON or OFF the VPP layout.
 The second parameter is an optional list of package-pin-numbers specifying
 which VPP is turned on.
 If the second parameter is not passed, all possible VPPs that were specified
 in the constructor are turned on.
 The second parameter is unused, if 
\begin_inset Quotes eld
\end_inset

on=False
\begin_inset Quotes erd
\end_inset

.
\end_layout

\begin_layout Description
applyGND(on) This method enables or disables (depending on the 
\begin_inset Quotes eld
\end_inset

on
\begin_inset Quotes erd
\end_inset

 parameter) the GND layout.
 Enabling the layout means that the GND pins will be actively driven by
 GND.
 Disabling the layout will tristate the driver.
\end_layout

\end_body
\end_document