[ Table Of Contents | Keyword Index ]

ftd2jtag(n) 1.0 ftd2jtag "JTAG Control Interface"

NAME

ftd2jtag - JTAG Control via ftd2chan

TABLE OF CONTENTS

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    TRANSACTIONS
    COMMANDS
    VARIABLES
    EXAMPLES
    SEE ALSO
    KEYWORDS
    COPYRIGHT

SYNOPSIS

package require Tcl 8.5
package require ftd2jtag ?1.0?

ftd2jtag open ?vid? ?pid? ?serialno? ?mask?
ftd2jtag close
ftd2jtag speed clkdiv
ftd2jtag reset ?bitno?
ftd2jtag resetTAP
ftd2jtag beginTrans
ftd2jtag endTrans
ftd2jtag evalTrans script
ftd2jtag execInstr instruction ?bits?
ftd2jtag moveToState state
ftd2jtag scanIn bits ?final?
ftd2jtag scanOut value bits ?final?
ftd2jtag scanInOut value bits ?final?

DESCRIPTION

This manpage describes a set of commands that are used in conjunction with the ftd2chan package to implement a JTAG control interface via the MPSSE bitmode of the FTDI 2232 chip. This package consists of an ensemble of commands that implement basic JTAG scanning of data registers and executing JTAG instructions. Note that the package only allows a single JTAG interface to be open at a time.

TRANSACTIONS

Since JTAG uses serial bit streams to accomplish control, often a large amount of I/O is needed to effect any control at all. To that end, this package uses the normal Tcl channel buffering to accumulate output and it reads input in a single operation. In order to determine the I/O boundaries, the package implements a transaction notion. The ftd2jtag beginTrans and ftd2jtag endTrans commands encapsulate an I/O transaction. After invoking beginTrans, scripts are presumed to contain invocations of the subcommands that make JTAG I/O requests, namely:

It is neither meaningful nor allowed for the above commands to be executed outside of a transaction. The transaction is terminated by invoking the endTrans subcommand, at which time the output if flushed and the input is read.

COMMANDS

ftd2jtag open ?vid? ?pid? ?serialno? ?mask?
The open subcommand opens the USB device given by the vid, pid and serialno using the ftd2chan command. The channel is placed in MPSSE mode with mask as the I/O mask. The default values for vid, pid, serialno and mask are 0x403, 0xbcd9, {LM000001 A} and 0x8b, respectively. These defaults correspond to opening a Luminary Micro LM3S811 Evaluation Board. open also resets the JTAG TAP and sets the clocking frequency to 6 MHz.

ftd2jtag close
The close subcommand closes the currently open USB JTAG device.

ftd2jtag speed clkdiv
The speed sets the clock frequency of the FTDI 2232 chip. The clkdiv argument is a 16-bit clock divisor and the final frequency of the JTAG clocking is given by:

Clock Frequency = 12MHz / ((1 + clkdiv) * 2)

By default the ftd2jtag open command sets the clock frequency to 6 MHz (i.e. clkdiv is set to 0).

ftd2jtag reset ?bitno?
The reset subcommand forces a hard system reset by asserting the I/O bit given by bitno and then deasserting it. This command is only useful for system where a system line is tied to one of the I/O pins of the FTDI 2232 chip. The default value of bitno is 5 corresponding to the reset line attachment of the Luminar Micro LM3S811 Evaluation Board.

ftd2jtag resetTAP
The resetTAP subcommand drives the JTAG state machine from its current state to the Test-Logic-Reset state and resets all the internal state variables of the package. This command is useful for recovering from errors and setting the TAP and package internals to a well known state.

ftd2jtag beginTrans
The beginTrans subcommand starts a JTAG I/O transaction. See TRANSACTIONS for a description of the I/O model of this package.

ftd2jtag endTrans
The endTrans subcommand terminates a JTAG I/O transaction. See TRANSACTIONS for a description of the I/O model of this package. This command returns a list of integer values that are the results of the invocation of scanIn or scanInOut during the transaction.

ftd2jtag evalTrans script
The evalTrans subcommand is a convenience command that evaluates script in the context of the invoking procedure as if script were surrounded by invocations of beginTrans and endTrans. See TRANSACTIONS for a description of the I/O model of this package. script may be an arbitrary Tcl script, but is presumed to invoke package commands that post JTAG I/O requests. After script is evaluated, all JTAG output is flushed and any requested input is read. This command returns a list of integer values requested by the invocations of scanIn or scanInOut in script. Transactions are not nestable.

ftd2jtag execInstr instruction ?bits?
The execInstr subcommand moves the TAP to the Scan-IR state and scans out the JTAG instruction given by instruction. By default instructions are four bits long, but may specified to be bits number of bits in length. All JTAG instructions should be executed using this command because it keeps a cache of the current value of the JTAG instruction register and will elide superfluous Instruction Register scans from the I/O stream.

ftd2jtag moveToState state
The moveToState command clocks the JTAG TAP in order to arrive at the state given by state. state must be one of the six stable JTAG states given by:

This command keeps track of the current JTAG TAP state and constructs the necessary clocking of the Test Mode Selector (TMS) to arrive at the requested state.

ftd2jtag scanIn bits ?final?
The scanIn subcommand requests bits number of bits of data be scanned in from the JTAG TAP while writing no output. The final argument determines if this scan completes acquisition of the underlying register, i.e. if the next JTAG operation will move to a new TAP state. If missing and by default final is true, indicating that the invocation of scanIn completes the scanning of the register. If final is false, then the scanIn is assumed to acquire only part of the underlying register and subsequent scanning will occur before moving to a new TAP state. Each invocation of scanIn will result in one value containing the requested number of bits being returned from the enclosing evalTrans command. The returned value contains the scanned bits as the least significant bits. Using final allows parts of a register to be scanned into separate values of the transaction.

ftd2jtag scanOut value bits ?final?
The scanOut subcommand requests the least significant bits number of bits of value be scanned out of the JTAG TAP while reading no output. The final argument has the same meaning as for scanIn.

ftd2jtag scanInOut value bits ?final?
The scanInOut subcommand requests the least significant bits number of bits of value be scanned out of the JTAG TAP while simultaneously reading bits number of bits of input. The final argument has the same meaning as for scanIn. Each invocation of scanInOut will result in one value being returned from the enclosing evalTrans command.

VARIABLES

The variable ::ftd2jtag::ioDebug may be set to a value that will cause trace output of the low level I/O. This is primarily useful for debugging the ftd2jtag package itself. If ::ftd2jtag::ioDebug is set to 1, then a simple dump of the raw I/O bytes to stdout is enabled. If ::ftd2jtag::ioDebug is set to 2, then the debug output includes information regarding how the JTAG TAP state changes are made and how the input and output values are scanned.

EXAMPLES

The following examples assume that JTAG device has been opened using ftd2jtag open command.

To read the IDCODE for a chip:

 
set idcode [ftd2jtag evalTrans {
    ftd2jtag execInst 0xe ; # IDCODE instruction value
    ftd2jtag moveToState SD
    ftd2jtag scanIn 32
}]
puts [format %#x $idcode]

==> 0x2ba00477 ; # IDCODE for the JTAG Debug Port on a LM3S811

To read the ARM Debug Access Port (a 35 bit register) on the LM3S811:

 
set trans [ftd2jtag evalTrans {
    ftd2jtag execInst 0xa ; # DPACC instruction

    ftd2jtag moveToState SD
    ftd2jtag scanOut 1 3 false ; # read request
    ftd2jtag scanOut 0 32

    ftd2jtag moveToState SD ; # scan again to get result
    ftd2jtag scanIn 3 false ; # ack
    ftd2jtag scanIn 32 ; # register read result
}]

==> 2 0 ; # OK acknowledgement value, 0 Debug Port value

SEE ALSO

ftd2chan

KEYWORDS

JTAG , USB

COPYRIGHT

Copyright © 2007 by G. Andrew Mangogna