summaryrefslogtreecommitdiffstats
path: root/README-DEVELOPERS.lyx
blob: 414c462cc7c6d36e963b872a5c9f966f7e2d2fe7 (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
#LyX 1.6.5 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
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 register it.
 This is done by calling RegisteredChip():
\end_layout

\begin_layout LyX-Code
RegisteredChip(Chip_MyDevice, 
\begin_inset Quotes eld
\end_inset

bitfileID
\begin_inset Quotes erd
\end_inset

)
\end_layout

\begin_layout Standard
The class (_not_ an instance of it) is passed as first parameter.
 The ID string of the required bitfile is past as second parameter.
\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
 9.2i.
 It can be downloaded as "WebPACK" for free (as in beer) from the Xilinx
 homepage in the "archive" section.
\end_layout

\begin_layout LyX-Code
http://www.xilinx.com/support/download/i92linwp.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.
\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) 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.
\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

\begin_layout Description
regenerateVoltageLayouts(chipPackage,chipPinVCCX,chipPinsVPP,chipPinGND)
 This method lets you regenerate the voltage layouts.
 That is useful, if you need to change one or more of the layouts for different
 programming tasks.
 For example it is common that VPP may be required on distinct pins for
 different operations.
 Note that it is not required to pass the auto-layout parameters to the
 __init__() constructor, if you plan to use this method instead.
 The parameters to this method match the parameters to the __init__() constructo
r.
 See above for a detailled description of these parameters.
\end_layout

\end_body
\end_document
bues.ch cgit interface