summaryrefslogtreecommitdiffstats
path: root/README-DEVELOPERS.lyx
diff options
context:
space:
mode:
authorMichael Buesch <mb@bu3sch.de>2010-02-27 22:25:09 +0100
committerMichael Buesch <mb@bu3sch.de>2010-02-27 22:25:09 +0100
commit3a4de0fc11ee7a6bbe561bbb1219f6e85412d2d3 (patch)
treecb83a294ffc7710c013b3769a96bf4a09206349c /README-DEVELOPERS.lyx
parentec18f9d69c4e21669e35a672f967f597985cc1bd (diff)
downloadtoprammer-3a4de0fc11ee7a6bbe561bbb1219f6e85412d2d3.tar.xz
toprammer-3a4de0fc11ee7a6bbe561bbb1219f6e85412d2d3.zip
Add basic developers documentation
Signed-off-by: Michael Buesch <mb@bu3sch.de>
Diffstat (limited to 'README-DEVELOPERS.lyx')
-rw-r--r--README-DEVELOPERS.lyx522
1 files changed, 522 insertions, 0 deletions
diff --git a/README-DEVELOPERS.lyx b/README-DEVELOPERS.lyx
new file mode 100644
index 0000000..10eb508
--- /dev/null
+++ b/README-DEVELOPERS.lyx
@@ -0,0 +1,522 @@
+#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
bues.ch cgit interface