summaryrefslogtreecommitdiffstats log msg author committer range
 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 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898  #LyX 2.0 created this file. For more info see http://www.lyx.org/ \lyxformat 413 \begin_document \begin_header \textclass article \use_default_options false \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global \font_roman default \font_sans default \font_typewriter default \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 \font_tt_scale 100 \graphics default \default_output_format default \output_sync 0 \bibtex_command default \index_command default \paperfontsize default \use_hyperref false \papersize default \use_geometry false \use_amsmath 1 \use_esint 1 \use_mhchem 1 \use_mathdots 1 \cite_engine basic \use_bibtopic false \use_indices false \paperorientation portrait \suppress_date false \use_refstyle 0 \index Index \shortcut idx \color #008000 \end_index \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \paragraph_indentation default \quotes_language english \papercolumns 1 \papersides 1 \paperpagestyle default \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \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 VCC 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 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 getOscillatorHz() \end_layout \begin_layout Standard Returns the frequency (in Hz) of the oscillator connected to the FPGA clk pin. \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 cmdSetVCCVoltage(voltage) \end_layout \begin_layout Standard Set VCC (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 cmdLoadVCCLayout(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 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 another into the buffer register. The buffer register does have a limited size. Overflowing it crashes the programmer, requireing a physical USB disconnect to recover. Call getBufferRegSize() to get the size of the buffer register. 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 libtoprammer/chips \begin_inset Quotes erd \end_inset module. The files in that module contain the top-half algorithm implementation. The files are named after the chip ID. Make sure to update the __init__.py of the module when adding algorithm implementations. The top-half files contain 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 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 generic algorithm GenericAlgorithms.simpleTest 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 Description readRAM() Read the Random Access Memory. Reimplement this, if your DUT has RAM and supports reading it. \end_layout \begin_layout Description writeRAM() Write the Random Access Memory. Reimplement this, if your DUT has RAM and supports writing to it. \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 Generic top-half algorithms \end_layout \begin_layout Standard The Python class \begin_inset Quotes eld \end_inset GenericAlgorithms \begin_inset Quotes erd \end_inset in the generic_algorithms.py file provides several generic chip access algorithm s that can be used in the \begin_inset Quotes eld \end_inset Chip \begin_inset Quotes erd \end_inset methods. \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/fpga/src/ subdirectory and execute the "create.sh" script: \end_layout \begin_layout LyX-Code ./create.sh bitfile_name \end_layout \begin_layout Standard Where "bitfile_name" is the name of the new chip's bitfile. (That often matches the chip-ID). Now go to libtoprammer/fpga/src/bitfile_name/ and implement the bottom-half algorithm in the bitfile_name.v Verilog file. To build the .BIT file from the Verilog sources, go to the libtoprammer/fpga/ directory and execute: \end_layout \begin_layout LyX-Code ./build.sh bitfile_name \end_layout \begin_layout Standard If you omit the \begin_inset Quotes eld \end_inset bitfile_name \begin_inset Quotes erd \end_inset , all bitfiles will be rebuilt. The resulting .BIT file will be copied to the libtoprammer/fpga/bin/ directory, after build finished successfully. \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 for 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 chipPinVCC 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 VPP pin on the chip package and _not_ on the ZIF socket. So if your chip datasheet tells you that VPP is on pin 1, you pass a 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 GND pin on the chip package and _not_ on the ZIF socket. So if your chip datasheet tells you that GND is on pin 5, you pass a 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 \begin_inset Quotes eld \end_inset class Chip \begin_inset Quotes erd \end_inset methods can be used to enable or disable a layout: \end_layout \begin_layout Description applyVCC(on) This method enables or disables (depending on the \begin_inset Quotes eld \end_inset on \begin_inset Quotes erd \end_inset parameter) the VCC layout. Enabling the layout means that the VCC pin will be actively driven by the configured VCC voltage. Disabling the layout will tristate the driver. \end_layout \begin_layout Description applyVPP(on,packagePinsToTurnOn) This method enables or disables (depending on the \begin_inset Quotes eld \end_inset on \begin_inset Quotes erd \end_inset parameter) the VPP 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 \begin_inset Quotes eld \end_inset on \begin_inset Quotes erd \end_inset parameter) the GND 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