summaryrefslogtreecommitdiffstats
path: root/README-DEVELOPERS.lyx
blob: c263f774e97e654e0d33a16c5f60b9950f91b86d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
#LyX 1.6.7 created this file. For more info see http://www.lyx.org/
\lyxformat 345
\begin_document
\begin_header
\textclass article
\use_default_options false
\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
\use_hyperref false
\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 "" 
\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
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
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
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 microcontroller's 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 each other into the buffer register.
 The buffer register can hold up to 64 bytes.
 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

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
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 convenience wrapper genericTest(self, readFunc, writeFunc, size) 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 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
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/bit/src/ subdirectory and execute the "create.sh" script:
\end_layout

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

\begin_layout Standard
Where "name_of_chip" is the name of the new chip.
 Now go to libtoprammer/bit/src/name_of_chip/ and implement the bottom-half
 algorithm in the name_of_chip.v Verilog file.
 To build the .BIT file from the Verilog sources, go to the libtoprammer/bit/
 directory and execute:
\end_layout

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

\begin_layout Standard
(if you omit the chipname, all chips will be rebuilt).
\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 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
chipPinVCCX 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 VCC pin on the chip package and _not_ on the
 ZIF socket.
 So if your chip datasheet tells you that VCC is on pin 1, you pass an 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 VCC pin on the chip package and _not_ on the
 ZIF socket.
 So if your chip datasheet tells you that VCC is on pin 5, you pass an 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 methods can be used to apply or disable a layout:
\end_layout

\begin_layout Description
applyVCCX(on) This method enables or disables (depending on the parameter)
 a layout.
 Enabling the layout means that the VCCX pin will be actively driven by
 the configured VCCX voltage.
 Disabling the layout will tristate the driver.
\end_layout

\begin_layout Description
applyVPP(on,packagePinsToTurnOn) This method enables or disables (depending
 on the parameter) a 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 parameter)
 a 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
bues.ch cgit interface