From 5ef9f852e5491550ce957464c82065cf47d690a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnim=20L=C3=A4uger?= Date: Sun, 30 Dec 2007 18:14:08 +0000 Subject: [PATCH] added BSDL documentation to doc/UrJTAG.txt removed README.svf -> moved to UrJTAG.txt git-svn-id: https://urjtag.svn.sourceforge.net/svnroot/urjtag/trunk@907 b68d4a1b-bc3d-0410-92ed-d4ac073336b7 --- jtag/ChangeLog | 1 + jtag/README.svf | 148 -------------------------------------------- jtag/doc/ChangeLog | 4 ++ jtag/doc/UrJTAG.txt | 146 +++++++++++++++++++++++++++++++++++++++++-- 4 files changed, 147 insertions(+), 152 deletions(-) delete mode 100644 jtag/README.svf diff --git a/jtag/ChangeLog b/jtag/ChangeLog index 467d1b8e..84f9541d 100644 --- a/jtag/ChangeLog +++ b/jtag/ChangeLog @@ -1,5 +1,6 @@ 2007-12-30 Arnim Laeuger + * README.svf: contents moved to doc/UrJTAG.txt, file deleted * data/Makefile.am (nobase_dist_pkgdata_DATA): fixed merge results * many files: integration of BSDL parser * data/xilinx/PARTS: added xc2v80-fg256,xc2v250-fg256,xc2v1000-fg256 diff --git a/jtag/README.svf b/jtag/README.svf deleted file mode 100644 index 1df1177c..00000000 --- a/jtag/README.svf +++ /dev/null @@ -1,148 +0,0 @@ -SVF Player for JTAG Tools -~~~~~~~~~~~~~~~~~~~~~~~~~ - -This README describes the SVF player of the UrJTAG software package. - -The player has been developed according to the "Serial Vector Format -Specification", Revision E, 8 March 1999 issued by ASSET InterTech, Inc. The -full specification can be found at - - http://www.asset-intertech.com/support/svf.pdf - - -Copyright ---------- - -SVF player is copyright 2004, Arnim Laeuger. - -Parser and lexer are also copyright 2002, CDS at http://www-csd.ijs.si -They have been reused from the "Experimental Boundary Scan" project at - - http://ebsp.sourceforge.net/ - -The SVF player is free software, covered by the GNU General Public License, -and you are welcome to change it and/or distribute copies of it under certain -conditions. There is absolutely no warranty for this software. -Please read the file COPYING for more info. - - -Usage ------ - -The SVF player operates on a single part in the scan chain. Therefore, you -have to bring up the jtag software, specify a cable and detect the scan -chain beforehand. - -The player will establish a new instruction called "SIR" and a new register -called "SDR". They are used internally by the respective SVF commands and are -reassigned with new values as the player advances through the file. It is not -recommended to use them outside of the SVF player as their content is dynamic. - - -Example session: - -jtag> cable ppdev /dev/parport0 DLC5 -Initializing Xilinx DLC5 JTAG Parallel Cable III on ppdev port /dev/parport0 - -jtag> detect -IR length: 5 -Chain length: 1 -Device Id: 10010000101000100000000010010011 - Manufacturer: Xilinx - Part: XC2S300E-PQ208 - Stepping: 9 - Filename: /usr/local/share/jtag/xilinx/xc2s300e-pq208/xc2s300e-pq208 - -jtag> part - -jtag> svf - -jtag> instruction BYPASS - -jtag> part - -jtag> svf - -jtag> instruction BYPASS - -... - - -It is recommended to set the part's instruction register to BYPASS although -most SVF files do this at the end. By setting the instruction explicitely to -BYPASS the output of the print command will always show meaningful -information. - -The SVF player will issue messages when situations arise that cannot be -handled. These messages are classified as warnings or errors depending on -whether the player can continue operation (warning) or not (error). - -In case the TDO parameter of an SDR command leads to a mismatch the player -issues a warning and continues. If the player should abort in this case then -specify 'stop' at the svf command. - - -Limitations and Deficiencies ----------------------------- - -Several limitations exist for the SVF player. - -It has been tested with files generated by these tools so far: - + Xilinx ISE WebPack 6.3.02i - 9.1.02i - + Altera Quartus II 4.1sp1 - 7.0 - -Configuration for these devices has been tested so far: - + Altera EPC1C12Q240 - + Altera MAX3032, EPM3032ALC44 - + Altera MAX3064, EPM3064ALC44 - + Altera MAX7032, EPM7032SLC44 - + Altera MAX7064, EPM7064SLC44, EPM7064STC44 - + Xilinx Spartan-IIE, XC2S300E-PQ208 - + Xilinx Spartan-3, XC3S1000-FG456, XC3S5000-FG900 - -The implementation of some SVF commands has deficiencies. - - HIR, HDR - Commands not supported. - Their functionality should be covered by the part concept of JTAG Tools. - - - PIO - Command not supported. - - - PIOMAP - Command not supported. - - - RUNTEST - SCK not supported. - The maximum time constraint is not guaranteed. - - - SIR - No check is done against the TDO parameter. - - - TRST - Parameters Z and ABSENT are not supported. - - - TIR, TDR - Commands not supported. - Their functionality should be covered by the part concept of JTAG Tools. - -Operation can be slowed down significantly when the FREQUENCY command has -been specified. -This is not a problem of the SVF player itself but seem to happen when the -frequency of UrJTAG is set to a value larger than 0. Configuration takes -very long although the maximum allowed frequency is 10 MHz. -Consider to comment out the FREQUENCY command at the beginning of the SVF -file. - - -Contact -------- - -Sharing your experience with this software is highly welcome. - -Please direct issues either to the urjtag-development mailinglist at - - https://lists.sourceforge.net/lists/listinfo/urjtag-development - -or contact me directly - - arniml users.sourceforge.net diff --git a/jtag/doc/ChangeLog b/jtag/doc/ChangeLog index 1cb8c394..3b45fe2f 100644 --- a/jtag/doc/ChangeLog +++ b/jtag/doc/ChangeLog @@ -1,3 +1,7 @@ +2007-12-30 Arnim Laeuger + + * UrJTAG.txt (Example): Added contents from README.svf, new section on BSDL + 2007-12-15 Kolja Waschk * fdl.txt, gpl.txt: licenses as plain text files diff --git a/jtag/doc/UrJTAG.txt b/jtag/doc/UrJTAG.txt index e98a61c6..455db5be 100644 --- a/jtag/doc/UrJTAG.txt +++ b/jtag/doc/UrJTAG.txt @@ -80,20 +80,30 @@ Currently there are at least three tools available to do that; included with UrJTAG is "bsdl2jtag". Please ask on the mailing list in case of problems with that. Please also send proven working files back to this project. -We're working on implementing native BSDL support in UrJTAG itself, so that -BSDL files do not have to be converted into UrJTAG format anymore. +Starting with post-0.7 releases, UrJTAG contains a BSDL subsystem that +retrieves the descriptions for chips in the chain from BSDL files on the +fly. Be aware that this feature is currently experimental and may not work +with every BSDL file yet. ==== SVF files ==== The SVF file format contains a number of high level commands to drive the jtag bus. For example you can shift the IR or DR and even check for the results. -The Xilinxs impact tool allows you to write this file to program devices. +The Xilinxs impact and Altera QuartusII tools allow you to write this file to +program devices. -SVF is documented in http://www.asset-intertech.com/support/svf.pdf +The player has been developed according to the "Serial Vector Format +Specification", Revision E, 8 March 1999 issued by ASSET InterTech, Inc. The +full specification can be found at +http://www.asset-intertech.com/support/svf.pdf UrJTAG features an "SVF player" that can read SVF files and perform the described actions on the bus. +SVF parser and lexer are also copyright 2002, CDS at http://www-csd.ijs.si/. +They have been reused from the "Experimental Boundary Scan" project at +http://ebsp.sourceforge.net/. + ==== JAM/STAPL files ==== Another format for describing actions over JTAG interfaces is STAPL, actually @@ -454,6 +464,7 @@ example usage. *bit*:: define new BSR bit *bus*:: change active bus +*bsdl*:: manage BSDL files *cable*:: select JTAG cable *detect*:: detect parts on the JTAG chain *detectflash*:: detect parameters of flash chips attached to a part @@ -588,6 +599,133 @@ particular core inside the chip (e.g. ARM7TDMI), but doesn't tell about the actual manufacturer of the chip. In such case, the data for the part has to be included manually. See also the documentation for the "include" command. +==== Highlevel commands ==== + +===== svf ===== + +The SVF player operates on a single part in the scan chain. Therefore, you +have to bring up the jtag software, specify a cable and detect the scan +chain beforehand. + +The player will establish a new instruction called "SIR" and a new register +called "SDR". They are used internally by the respective SVF commands and are +reassigned with new values as the player advances through the file. It is not +recommended to use them outside of the SVF player as their content is dynamic. + +An example session: + + jtag> cable ppdev /dev/parport0 DLC5 + Initializing Xilinx DLC5 JTAG Parallel Cable III on ppdev port /dev/parport0 + jtag> detect + IR length: 5 + Chain length: 1 + Device Id: 10010000101000100000000010010011 + Manufacturer: Xilinx + Part: XC2S300E-PQ208 + Stepping: 9 + Filename: /usr/local/share/jtag/xilinx/xc2s300e-pq208/xc2s300e-pq208 + jtag> part + jtag> svf + jtag> instruction BYPASS + jtag> shift ir + jtag> part + jtag> svf + jtag> instruction BYPASS + jtag> shift ir + +It is recommended to set the part's instruction register to BYPASS although +most SVF files do this at the end. By setting the instruction explicitely to +BYPASS the output of the print command will always show meaningful +information. + +The SVF player will issue messages when situations arise that cannot be +handled. These messages are classified as warnings or errors depending on +whether the player can continue operation (warning) or not (error). +In case the TDO parameter of an SDR command leads to a mismatch the player +issues a warning and continues. If the player should abort in this case then +specify 'stop' at the svf command. + +.Limitations and Deficiencies +***************************** +Several limitations exist for the SVF player. + +It has been tested so far with files generated by these tools: + + - Xilinx ISE WebPack 6.3.02i - 9.1.02i + - Altera Quartus II 4.1sp1 - 7.0 + +Configuration for these devices has been tested so far: + + - Altera EPC1C12Q240 + - Altera MAX3032, EPM3032ALC44 + - Altera MAX3064, EPM3064ALC44 + - Altera MAX7032, EPM7032SLC44 + - Altera MAX7064, EPM7064SLC44, EPM7064STC44 + - Xilinx Spartan-IIE, XC2S300E-PQ208 + - Xilinx Spartan-3, XC3S1000-FG456, XC3S5000-FG900 + +The implementation of some SVF commands has deficiencies. + + - HIR, HDR commands not supported. + + Their functionality should be covered by the part concept of JTAG Tools. + - PIO command not supported. + - PIOMAP command not supported. + - RUNTEST SCK not supported. + + The maximum time constraint is not guaranteed. + - SIR + + No check is done against the TDO parameter. + - TRST + + Parameters Z and ABSENT are not supported. + - TIR, TDR commands not supported. + + Their functionality should be covered by the part concept of JTAG Tools. + +Operation can be slowed down significantly when the FREQUENCY command has +been specified. This is not a problem of the SVF player itself but seem to +happen when the frequency of UrJTAG is set to a value larger than 0. +Configuration takes very long although the maximum allowed frequency is 10 MHz. +Consider to comment out the FREQUENCY command at the beginning of the SVF file. +***************************** + +===== bsdl ===== + +The 'bsdl' command is used to set up and test the underlying BSDL subsystem of +UrJTAG. + +Whenever 'detect' encounters a new part, a configuration process is +started. This involves matching the retrieved IDCODE against the part +descriptions in /usr/share/urjtag as described above. However, before this +database is searched for a suitable description, the BSDL subsystem is started +and searches for BSDL file that matches this device. If it finds a matching +file, traversal of the /usr/share/urjtag database is skipped. If not, then +this standard process follows. + +To tell the BSDL subsytem where to look for BSDL files, the 'bsdl path +pathlist' command has to be issued prior to 'detect'. The contents of +'pathlist' must be a semicolon-separated list of directories where BSDL files +are located. This list is stored by 'bsdl path' and used lateron when 'detect' +calls the BSDL subsystem. + +IMPORTANT: The BSDL subsystem applies the first BSDL file that parses without +errors and contains the correct IDCODE. Scanning the specified directories +happens in extactly the given order. Inside a directory however, the order +depends largely on your filesystem's behavior. + +Further details of the 'bsdl' command: + + - bsdl path [;[;]] + + set paths for locating BSDL files + - bsdl debug on|off + + switches debug messages on or off + - bsdl test [file] + + reads file (if specified) or all files found via 'bsdl path' and + prints a short status, an active part is not required + - bsdl dump [file] + + reads file (if specified) or all files found via 'bsdl path' and + prints all configuration commands, an active part is not required + +TIP: The 'bsdl dump file' command implements the same functionality as +bsdl2jtag. + ==== Unsupported commands ==== ===== setdevice =====