path: root/README-DEVELOPERS.lyx

#LyX 1.5.5 created this file. For more info see http://www.lyx.org/
\lyxformat 276
\begin_document
\begin_header
\textclass article
\language english
\inputencoding auto
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\paperfontsize default
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\author "" 
\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
VCCX 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

toprammer_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
cmdReadStatusReg()
\end_layout

\begin_layout Standard
Reads the 
\begin_inset Quotes eld
\end_inset

status register
\begin_inset Quotes erd
\end_inset

 from the microcontroller.
 That register is used for buffering of status information and for buffering
 of data fetched from the FPGA.
\end_layout

\begin_layout Subsection
cmdReadStatusReg32()
\end_layout

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

\begin_layout Subsection
cmdReadStatusReg48()
\end_layout

\begin_layout Standard
Same as cmdReadStatusReg(), 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
cmdSetVCCXVoltage(voltage)
\end_layout

\begin_layout Standard
Set VCCX (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
cmdLoadVCCXLayout(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
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.
\end_layout

\begin_layout Subsection
cmdFPGAReadRaw(address)
\end_layout

\begin_layout Standard
Reads a byte from the FPGA and puts it into the microcontroller's status
 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 status register has an automagically incrementing
 pointer.
 So issueing several cmdFPGAReadRaw() in a row will result in all the bytes
 being put one after each other into the status register.
 The status register can hold up to 64 bytes.
 Reading the status register (cmdReadStatusReg()) will reset the automagic
 pointer to zero.
\end_layout

\begin_layout Subsection
cmdFPGAReadByte()
\end_layout

\begin_layout Standard
This is a shortcut to cmdFPGAReadRaw(0x10).
 In general it is used for payload data reading.
 Using cmdFPGAReadByte() instead of cmdFPGAReadRaw(0x10) is more efficient
 for payload reading, because on the USB bus the command is only one byte
 wide instead of two.
 So it uses up less space in the transmission queue and can thus speed up
 operation.
\end_layout

\begin_layout Subsection
cmdFlush()
\end_layout

\begin_layout Standard
Is believed to be kind of a flush command.
 However, there also are suspections that it has certain delay semantics,
 too.
 You usually don't have to call this directly.
\end_layout

\begin_layout Subsection
delay(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.
\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

.
 Note that this is not to be confused with cmdFlush(), which does some flushing
 tasks inside of the microcontroller.
\end_layout

\begin_layout Itemize
Commands are automatically flushed on cmdReadStatusReg() 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

chip_xxx.py
\begin_inset Quotes erd
\end_inset

 files, where xxx is the ID of the DUT.
 This file contains 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 provides some basic helper methods for algorithm implementation.
 It also 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
initializeChip() Called once on chip initialization.
 Reimplement this, if required.
\end_layout

\begin_layout Description
shutdownChip() Called once on chip shutdown.
 Reimplement this, if required
\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
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 Standard
After defining your 
\begin_inset Quotes eld
\end_inset

Chip
\begin_inset Quotes erd
\end_inset

-derived class you need to add it to the 
\begin_inset Quotes eld
\end_inset

supportedChips
\begin_inset Quotes erd
\end_inset

 array.
\end_layout

\begin_layout LyX-Code
supportedChips.append(Chip_MyDevice())
\end_layout

\begin_layout Section
Automatic layout generator
\end_layout

\begin_layout Standard
TODO
\end_layout

\end_body
\end_document