|
|
Appendix E
Using the Command Line Interface
This chapter gives specific information about using jtagprog in a workstation or PC environment to perform JTAG operations. You can use jtagprog to download, read back, verify design configuration data for any device, and to probe internal logic states of an CPLD design.
JTAG Programmer batch software support the following capabilities.
JTAG Programmer allows you to download a design to the CPLD on the target system.
JTAG Programmer can verify CPLD configuration by comparing it to the original JEDEC programming file after configuring an CPLD.
You can program multiple CPLDs connected on a boundary-scan chain.
You can apply test vectors from a JEDEC file through the boundary-scan TAP to CPLDs using the INTEST instruction.
This appendix contains the following sections:
Using JTAG Programmer Batch Version Software
This section describes the JTAG Programmer files and commands.
JTAG Programmer Files
You must become familiar with the following files, which are used by the JTAG Programmer software.
design.jed
The design.jed file contains the configuration information for the target design in JEDEC 3-C standard formats. The file is generated by the fitter software. This file may optionally contain functional test vectors to do functional verification of XC9500/XL/XV devices.
jtagprogrammer.pro
The jtagprogrammer.pro file contains the default values for all JTAG Programmer options: part, design, baud, and port. These option values are updated at the end of every JTAG Programmer session. For JTAG Programmer to recognize a jtagprogrammer.pro file, it must be located in the current working directory.
batch_file.cmd
The batch files are text files used to execute commands in the batch mode, and the extension ".cmd" is required.
device.bsd
The bsd files contain Boundary Scan Description Language (BSDL) specifications of the operation of the boundary-scan logic of a given device. For any non-XC9500/XL/XV device in your boundary-scan chain, you are required to supply this file.
Invoking JTAG Programmer
You can start JTAG Programmer using interactive commands from the system shell. This mode offers additional commands for download and readback and also allows you to probe the internal logic states of the target system device.
Downloading
You can download a design after connecting the cable to the host system and target system. To download a design, enter the following command at the operating system prompt.
jtagprog
When you do not specify any options, the JTAG Programmer software selects the port where the cable is connected and sets the baud rate to the maximum allowed by the platform. You can modify the communication port and baud rate by changing the appropriate settings in the xchecker.pro file.
To download in an interactive mode, enter the following command at the system prompt.
jtagprog
You see the following message on the screen:
JTAGProgrammer: version x1_1.0 Copyright: 1991-1996 Cable ID type is 'XCHECKER' Cable is connected to '/dev/ttya' Baud rate is 38400
To specify the number, type, names and order of devices in the boundary-scan chain:
part part_type:design_name
To erase and program the a design, enter this command string:
program design_name
Verifying
After you have properly configured a device, you can verify its configuration and compare it to your original design.
In most applications, verification is not needed, but this feature can be helpful with designs that experience extremely unstable or noisy VCC conditions.
To execute a readback after the device has been in operation, use the interactive commands, as follows:
jtagprog
This command invokes the interactive mode, and the [JTAGProgrammer::(#)] 
prompt appears (the "#" in the prompt string is the current command number).
[JTAGProgrammer::(#)] part part_type:design_name
The part commands identifies the number the number, type, name and order of devices in the boundary-scan chain. In this case there is one device only. Then to program the device, enter:
[JTAGProgrammer::(#)] program design_name
The program command downloads design.jed to the target device. If you want a readback after the target device is in operation, you can execute the Verify command.
[JTAGProgrammer::(#)] verify design_name
This command initiates a readback, and compares the data to the design.jed file.
You may also execute the program and verify operations in one step by typing:
[JTAGProgrammer::(#)] program -v design_name
Command-Line Options
This section describes the JTAG Programmer command-line options. The data files are configuration bitstream files in JEDEC format. When you do not specify any options or data files, the system defaults to the interactive mode.
The command-line syntax is as follows:
jtagprog options
You can abbreviate all options to the minimum number of distinctive characters in the option name.
Commands and options are not case-sensitive.
-batch Batch Mode Operation
Syntax: -batch bat_file.cmd
Abbreviation : b
The Batch option executes commands in batch mode. The bat_file must have a ".cmd" extension and contain valid JTAG Programmer commands, including interactive commands. You can add comments to files by using the # symbol, either on the command line or on a new line.
-h The Help Option
Syntax: -help
Abbreviation: h
The Help option displays command line usage information.
-log Specify Log File Name
Syntax: -log filename.log
Abbreviation: -l
Captures all output to the specified log file.
-port Specify Port Name
Syntax: -port portname
Abbreviation: po
The Specify Port Name option identifies the port connection for the XChecker cable. If you do not specify this option, the default option AUTO, searches for the cable connected to any port, parallel or serial. Valid ports for supported platforms are listed in Table E-1.
Valid Ports for the XChecker Cable
| Platform | Communication Ports | |||
|---|---|---|---|---|
| IBM PC | com1 | com2 | lpt1* | lpt2* |
| Sun | /dev/ttya** | /dev/ttyb** | ||
| HP | /dev/tty00 | /dev/tty01 | ||
*Use with the parallel download cable only.
**ttya and ttyb must be readable and writable to ensure a proper connection.
Interactive Mode Commands
This section describes the JTAG Programmer interactive mode commands. To use the interactive mode commands, you enter jtagprog at the system prompt.
You can abbreviate the commands using the least number of distinctive characters, as with the command line options, but you must use at least two characters. You can repeat the previous command using either an equal sign, "=," or an exclamation point, "!."
Autoconfigure - Identify Chain Composition
Syntax: autoconfigure
Abbreviation: autoc
This command queries all the devices in the chain and attempts t o identify the boundary-scan chain composition using the IDCODE instruction. The command returns a list of devices in the chain and their position with device 1 being closest to the system TDI. Parts that have not implemented IDCODE or those parts whose IDCODE is unrecognized will be identified as unknown devices.
Batch - Execute in Batch Mode
Syntax: batch bat_file.cmd
Abbreviation: bat
The Batch command executes commands in a batch mode. The bat_file must have a ".cmd" extension and contain valid JTAG Programmer commands. Use the pound sign, "#" to precede comment lines in the batch file.
Examples
The following examples show two methods of using the Batch command from the JTAG Programmer prompt:
batch bat_file.cmd
bat_file.cmd
Baud - Specify Baud Rate
Syntax : baud baud_rate
Abbreviation: bau
The Baud command specifies a communication baud rate. At initialization, the fastest baud rate for your host system is automatically selected. Table E-2 lists the valid baud rates.
Valid Baud Rates
| Platform | Baud Rate | ||
|---|---|---|---|
| 9600 | 19200 | 38400 | |
| IBM PC | X | X | X |
| Sun | X | X | X |
| HP 700 | X | X | X |
Dump
Syntax: dump [-h] part_name -j file_name
The dump command will read the contents of a part and create a JEDEC file with the results. The file created will default to part_name.jed. Optionally, you may specify your own name using the -j flag. The part_name must have been specified with the part command.
The -h flag specifies that all untargeted parts should use HIGHZ mode as the BYPASS method. This will float all untargeted device output pins and can reduce system noise in active environments.
Erase
Syntax: erase [-f] [-h] part_name
This command erases the programmed contents of the specified part. The part_name must have been specified with the part command. The option -f is used to reset write-protect.
The -h flag specifies that all untargeted parts should use HIGHZ mode as the BYPASS method. This will float all untargeted device output pins and can reduce system noise in active environments.
Exit - Terminate Session
Syntax: exit
Abbreviation: exi
The Exit command terminates the current JTAG Programmer session, asks you whether to save current program options in the xchecker.pro file, and returns you to the system shell.
Functest
Syntax : functest [-h] part_name [-j file_name]
The functest command will run the functional vectors in the associated JEDEC file (file_name) on the specified device (part_name) using the intest command. If the part_name is the same as the JEDEC file_name, then the file_name does not need to be specified. The part_name must have been specified with the part command.
The -h flag specifies that all untargeted parts should use HIGHZ mode as the BYPASS method. This will float all untargeted device output pins and can reduce system noise in active environments.
Help - Online Help
Syntax : help topic
Abbreviation: he
The Help command displays online help for the topic requested in 24-line segments. Enter y to scroll forward to the next 24 lines. Enter n to exit Help.
Id_loop - Idcode Looping
Syntax: id_loop -n [number_of_loops] part_name
This command is used to perform idcode looping to debug noise problems in the boundary scan chain.
Opgroup - Setup Group for Concurrent Operations
Syntax: opgroup groupname partname:jedec_file
This command is used to set up groups of devices for concurrent operations. Each group specified must have a unique name and can include any number of devices in the boundary-scan chain. The devices are identified by using the partname specified in the part command. You may optionally specify a full path name to the jedec file for each partname.
The opgroup command can be invoked only after a part command has been issued.
The groupname designated in the opgroup command can be used in place of the partname in the erase, program or verify commands to execute concurrent operations on all devices in that group.
Part - Specify Device Chain
Syntax: part device_type:part_name device_type:part_name ...
Abbreviation : pa
This command must be executed first. It describes the devices in the chain to the software. The device_type is used to find the BSDL file associated with each part. BSDL files must be named device_type.bsd. The part_name is an arbitrary name to associate with the device instance in the chain. It will usually be the proper name (the file name without the extension) of the JEDEC file associated with the device at that location in the boundary-scan chain, although it could be anything. The boundary scan chain order must start with the closest device to TDI, and proceed in order through the chain until it reaches the last device, which is closest to TDO. When multiple "part" commands are issued, the information associated with the very last is maintained.
Partinfo
Syntax: partinfo [-h] -id -signature -checksum part_name -j jedec_file_name
The partinfo command returns the manufacturer's identification (id), the user signature (-signature) or the device checksum (-checksum) for a particular part_name. Any or all of the three switches may be specified in a single command. The part_name must have been specified in the part command. When calculating the checksum the JEDEC file should be specified as well to indicate the expected checksum.
The -h flag specifies that all untargeted parts should use HIGHZ mode as the BYPASS method. This will float all untargeted device output pins and can reduce system noise in active environments.
If you use the partinfo command with the -signature option when generating an SVF file, use the -u option to specify the expected usercode.
Port - Specify Download/Readback Port
Syntax: port portname
Abbreviation: po
The port command specifies the download/readback port. Table 3-5 lists the valid entries; the ports listed in bold face are the defaults. If the port is defined as Auto, all ports are scanned to search for a cable.
Valid Ports for the Parallel, XChecker Cable and MultiLINX Cables
| Platform | Communication Ports | ||||
|---|---|---|---|---|---|
| IBM PC | com1 | com2 | lpt1* | lpt2* | usb*** |
| Sun | /dev/ttya** | /dev/ttyb** | |||
| HP | /dev/tty00 | /dev/tty01 | |||
*Use with the parallel download cable only.
**ttya and ttyb must be readable and writable to ensure a proper connection.
***only on Win98 Systems
Program
Syntax: program [-v] [-t] [-s] [-p] [-h] [-i] [-l] [-m] part_name [-j file_name]
This command programs the specified part. If the part_name is the same as the JEDEC file_name, then the file_name does not need to be specified. The part_name must have been set in the part command. There are four options that may be specified (individually or together):
-v after programming the device reads back the contents and verifies that they agree with the associated JEDEC file.
-t executes a functional test after programming using the vectors contained in the associated JEDEC file.
-s sets data security in the device. This disables readback of the device's programmed contents. The device must be erased to reprogram it.
-p sets data protect in the device. This disables over-write of the device`s programmed contents. The device cannot be erased or re-programmed.
-b skips the erase of the device prior to programming.
-h specifies that all untargeted parts should use HIGHZ mode as the BYPASS method. This will float all untargeted device output pins and can reduce system noise in active environments.
-i specifies info only. This is used with proms and indicates that only info bits are being programmed.
-l loads FPGA. This is used to load FPGA at the end of configuration.
-m selects map/parallel mode. This is used to configure the prom to seek out data in parallel mode.
Quit - Terminate Session
Syntax: quit
Abbreviation: qu
The Quit command terminates the current JTAG Programmer session and asks you whether to save current program options in the xchecker.pro file.
Save - Save Option Settings
Syntax: save
Abbreviation: saThe Save command saves the settings of four interactive command results in the jtagprogrammer.pro file; baud rate (Baud command), design name (Load command), device type (Parttype command) and port name (Port command).At initialization, JTAG Programmer reads the jtagprogrammer.pro file to set up the defaults for the current session. This file must be in the current directory or in the XILINX environment search path. JTAG Programmer updates the profile information at the end of every session. The jtagprogrammer.pro file is created when you exit from your first JTAG Programmer session.
Settings - Display Settings
Syntax: settingsAbbreviation: seThe Settings command provides a listing of the following information; the port name, the baud rate, the type of cable, the design name, the part type and package type, the clock source, and hardware trigger status. It also lists the number of clocks for the first and subsequent snapshots, the number of signals defined in the probe list, and the number of signals defined in the display list.
Sys - Temporarily Exit to Operating System
Syntax: sysAbbreviation: noneThe Sys command allows you to temporarily exit from JTAG Programmer to the operating system prompt. Enter exit to return to JTAG Programmer.
Verify - Verify Target CPLD Bitstream
Syntax: verify [-h] part_name [-j file_name]Abbreviation: veThis command reads back the configuration registers of the specified part and compares its contents against the JEDEC file. If the part_name is the same as the JEDEC file_name, the file_name does not need to be specified.The -h flag specifies that all untargeted parts should use HIGHZ mode as the BYPASS method. This will float all untargeted device output pins and can reduce system noise in active environments.
