From 3a4de0fc11ee7a6bbe561bbb1219f6e85412d2d3 Mon Sep 17 00:00:00 2001 From: Michael Buesch Date: Sat, 27 Feb 2010 22:25:09 +0100 Subject: Add basic developers documentation Signed-off-by: Michael Buesch --- README-DEVELOPERS.lyx | 522 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 522 insertions(+) create mode 100644 README-DEVELOPERS.lyx (limited to 'README-DEVELOPERS.lyx') 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 -- cgit v1.2.3