[
Table Of Contents
| Keyword Index
]
armdbg(n) 1.0 armdbg "ARM Debug Port Access"
armdbg - JTAG Access to the ARM Debug Port
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
TRANSACTIONS
COMMANDS
VARIABLES
DEBUG PORT CONTROL/STATUS FIELDS
ACCESS PORT CONTROL/STATUS FIELDS
EXAMPLES
SEE ALSO
KEYWORDS
COPYRIGHT
package require Tcl 8.5
package require armdbg ?1.0?
This manpage describes a set of commands that are used in conjunction
with the ftd2jtag package to implement JTAG access
to the on-chip Debug Access Port for ARM processors.
The package is an ensemble of commands that fall into four broad
categories.
- Control and Status Commands
-
The ensemble commands,
attach,
romTable,
idcode
and
abort
are used for controlling the Debug Port and querying its status.
- Block Commands
-
The ensemble commands,
readBytes,
readHalfWords,
readWords,
writeBytes,
writeHalfWords,
writeWords
fillBytes,
fillHalfWords
and
fillWords
read and write sequential memory locations using the automatic address
incrementing capablity of the Access Port.
- Transaction Commands
-
The ensemble commands,
ackTrans
and
pipelineTrans
are used to form transaction sequences with the access port.
See TRANSACTIONS below for a description of the manner in which
the access port transactions operate.
- Debug Port Access Commands
-
The ensemble commands,
setDP_CSW,
setAP_CSW,
setAP_TAR,
getDPReg,
getAPReg
and
setAPReg
form the basic Debug and Access Port I/O requests.
These requests are executed in the context of a transaction.
The JTAG versions of the Debug Port and Access Port for an ARM processor
are 35-bit quantities.
The most significant 32-bits are the value of a register accessed via the
port.
The three least significant bits are used as a command/address value when
written and as an acknowledgement value when read.
When an acknowlegement value is read,
it is indicative of the completion status of the previous command.
The acknowledgement value can be either 2 indicating OK/FAULT or 1 indicating
WAIT.
It does not state whether or not the previous port access was successful, only
if the port access has been completed and the result is available.
If the acknowledgement value is WAIT,
new commands are ignored and the port must be rescanned until an OK/FAULT
acknowledgement is returned.
Thus in those situations where it is necessary to know that a particular port
access has definitely completed, accounting for the acknowledgement is
required
Because it is necessary to rescan the port to obtain the result of a
read command,
it is more efficient to preform port accesses in
sets where a subsequent access is used to retrieve any result of
the previous access.
The Debug Port also supports another form of access that does not require
evaluating the acknowledgement values.
Evaluating the acknowledgement value implies making many small I/O transactions
and there are many circumstances (e.g. reading a block of memory)
where it is sufficient to know if the entire set of port accesses succeeded
or not.
The Debug Port uses the notion of a sticky overrun bit to accomplish
this.
In this mode of operation,
a long set of port accesses can be made without evaluating the acknowledgement
value.
If the port would have returned a WAIT acknowledgement, then all
subsequent port accesses are discarded and the STICKYORUN bit is set
to indicate the overrun condition.
ARM documentation strongly suggests that debuggers need to be able to
pad the I/O stream in such a way that the speed of the requests closely
matches the ability of the system to fullfill the requests minimizing the
likelyhood of an overrun.
This package supports these two different methods of port access via the
ackTrans and pipelineTrans commands.
Port accesses performed via the ackTrans command evaluate each
acknowledgment value and rescan the command if a WAIT is encountered.
This type of transaction can be used to insure that the value of one register
has definitely been established before the next port access is made.
This is the usual semantics required for sequential control situations.
Port accesses performed via the pipelineTrans perform all the
output in one block followed by reading all the input in one block
(i.e. in one ftd2jtag transaction) and the transaction
succeeds if no overrun occurred during the set of port accesses.
- armdbg attach
-
The armdbg attach command initialized the Debug Port
and the package internals for subsequent access.
This command should be called first before any other commands
in this package.
This command assumes that ftd2jtag open has already been
called to establish the JTAG connection to the target.
- armdbg romTable
-
The armdbg romTable command returns the contents of the
Debug Port ROM Table.
The ROM Table is an internal data structure that gives the address
in memory of key system debug blocks.
The value returned by the command is a dictionary keyed by
system debug block name.
The keys of the returned dictionary for an ARM Cortex-M3
include at least:
and may include an EMT block.
- armdbg idcode
-
The armdbg idcode command returns the Debug Port Id Code as a
dictionary of keyed by field names.
The returned field names are:
- PARTNO == 0xBA00, indicating a JTAG Debug Port
- MANUFACTURER == 0x23B, indicating ARM as the manufacturer
- VERSION ==> chip version number
- armdbg abort
-
The armdbg abort command issues a Debug Port Abort command.
This command will abort the current Debug Port request should it hang
(e.g. should the access cause the system to hang).
- armdbg readBytes address count
-
The readBytes subcommand returns count number of sequential bytes
from the memory location given by address.
- armdbg readHalfWords address count
-
The readHalfWords subcommand returns count number of
sequential bytes from the memory location given by address
as 16-bit half words.
The address must be half word aligned and count must be a
multiple of two.
- armdbg readWords address count
-
The readWords subcommand returns count number of
sequential bytes from the memory location given by address
as 32-bit words.
The address must be word aligned and count must be a
multiple of four.
- armdbg writeBytes address ?byte0 byte1 ...?
-
The writeBytes subcommand writes the byte values given by the byteN
arguments to sequential memory locations starting at address.
- armdbg writeHalfWords address ?halfWord0 halfWord1 ...?
-
The writeHalfWords subcommand writes the 16-bit half word values
given by the halfWordN arguments
to sequential even memory locations starting at address.
The starting address, address, must be half word aligned.
- armdbg writeWords address ?word0 word1 ...?
-
The writeWords subcommand writes the 32-bit word values
given by the wordN arguments
to sequential word aligned memory locations starting at address.
The starting address, address, must be word aligned.
- armdbg fillBytes address count value
-
The fillBytes subcommand writes the byte value given by value
to count number of sequential memory locations starting at address.
- armdbg fillHalfWords address count value
-
The fillHalfWords subcommand writes the 16-bit half word value given by
value to count number of sequential even memory locations
starting at address.
The staring address, address, must be even and count must be even.
- armdbg fillWords address count value
-
The fillWords subcommand writes the 32-bit word value given by
value to count number of sequential word aligned memory locations
starting at address.
The staring address, address, must be word aligned and count
must be a multiple of 4.
- armdbg ackTrans script ?xferMode? ?mask?
-
The ackTrans subcommand executes script in the context of the caller
and insures that each access to the Debug Port or Access Port is
completed by checking the acknowledgement value during the port access.
This command is useful in those circumstances where it is necessary to know
that one Debug Port operation has been completed before the next one is begun.
The return value of the command is a list containing all values returned
by commands in script that request register reads.
The xferMode may be one of NORMAL, VERIFY or COMPARE (default is NORMAL),
which controls the Transaction Mode setting of the Debug Port CSW.
The Transaction Mode settings other than NORMAL are used for pushed
operations.
The mask argument controls the MASKLANE field of the Debug Port CSW.
The MASKLANE values control which bytes in the word are used during
pushed operations.
The default value of mask is zero, insuring that all four bytes of
the byte lanes are used in the transaction.
Other value values are 4 bit values with a 1 in each bit position where
the byte lane is to be used in the pushed operation.
- armdbg pipelineTrans script ?xferMode? ?mask?
-
The pipelineTrans subcommand executes script in the context of
the caller using the sticky flags of the debug port to detect if
there were any overruns during the transaction.
This type of transaction is conducted in a single output / input operation
on the JTAG port.
This command is more efficient in terms of I/O but should only be used
where the success or completion can be judged as a whole (e.g.
when reading or writing a block of memory).
The return value of the command is a list containing all values returned
by commands in script that request register reads.
The xferMode and mask arguments have the same meaning as
for the ackTrans command.
- armdbg setDP_CSW ?field value ...?
-
The setDP_CSW subcommand sets the value of the Debug Port
Control/Status Word to be the values given in the field and value
arguments.
The arguments are given in pairs with the first being the name of a field
in the Debug Port CSW and the second being a value for that field.
See
DEBUG PORT CONTROL/STATUS FIELDS
below for a valid list of field names.
Changes to the Debug Port CSW should only be made via this command
as it caches the current value of the CSW and can elide superfluous
CSW change attempts from the I/O stream.
- armdbg setAP_CSW ?field value ...?
-
The setAP_CSW subcommand sets the value of the AHB Access Port
to that given by the field / value arguments.
The arguments are given in pairs with the first being the name of a field
in the Access Port CSW and the second being a value for that field.
See
ACCESS PORT CONTROL/STATUS FIELDS
below for a valid list of field names.
Changes to the Access Port CSW should only be made via this command
as it caches the current value of the CSW and can elide superfluous
CSW change attempts from the I/O stream.
- armdbg setAP_TAR value
-
The setAP_TAR subcommand sets the value of the Target Access Register
of the Access Port.
The TAR set the address of where the next access will be when the Access Port
Data Read/Write Register is accessed.
Changes to the Access Port TAR should only be made via this command
as it caches the current value of the TAR and can elide superfluous
TAR change attempts from the I/O stream.
- armdbg getDPReg DPRegName
-
The getDPReg subcommand posts a read for the Debug Port register
given by DPRegName.
The return value of the is the empty string, and the value of the register
is returned as part of the list of values returned from the enclosing
ackTrans or pipelinedTrans command.
Valid values of DPRegName are:
- armdbg getAPReg APRegName ?portSelect?
-
The getAPReg subcommand posts a read for the Access Port register
given by APRegName from the access port given by portSelect.
Only portSelect values of 0 are supported fully.
Valid values of APRegName are:
- DRW
- BD0
- BD1
- BD2
- BD3
- ROM
- IDR
- armdbg setAPReg APRegName value ?portSelect?
-
The setAPReg subcommand writes value to the Access Port
Register given by APRegName for the Access Port given by
portSelect.
Only portSelect values of 0 are supported fully.
Valid values of APRegName are:
- ::armdbg::regDebug
-
Setting the variable ::armdbg::regDebug to 1
will cause trace output from the package indicating which debug ports
are read or written.
This is primarily useful for debugging the armdbg package itself.
- ::armdbg::retryCount
-
During acknowledged transactions, the value of ::armdbg::retryCount
determines the maximum number of times a port access will be tried if
a WAIT acknowledgment is received.
The default value is 10.
- ::armdbg::rtiDelay
-
The variable ::armdbg::rtiDelay contains the number of
additional TAP state transitions to the Run-Test-Idle state that are
inserted into the output generated for a pipelineTrans command.
The default value is 1.
During a pipelined transaction and
after the data register is scanned, rtiDelay number of
additional TAP transitions to the RTI state are inserted.
This has the effect of increasing the time between when the Update Data
Register state and a subsequent Capture Data Register transition.
The package will automatically tune the value of rtiDelay during
pipelined transactions if any overruns are encountered.
Normally users do not need to adjust this values, however
if you experience overrun conditions during pipelined transactions,
then you may wish take control of the value of this variable.
The armdbg setDP_CSW command accepts field
names and field values that are used to construct the value of the
register.
The following is a list of valid Debug Port Control/Status field names.
Names follow the conventions in ARM documentation.
- CSYSPWRUPACK
- CSYSPWRUPREQ
- CDBGPWRUPACK
- CDBGPWRUPREQ
- CDBGRSTACK
- CDBGRSTREQ
- TRNCNT
- MASKLANE
- STICKYERR
- STICKYCMP
- TRNMODE
- STICKYORUN
- ORUNDETECT
The armdbg setAP_CSW command accepts field
names and field values that are used to construct the value of the
register.
The following is a list of valid Access Port Control/Status field names.
Names follow the conventions in ARM documentation.
- MASTERTYPE
- HPROT
- MODE
- TRANSINPROG
- DBGSTATUS
- ADDRINC
- SIZE
The following examples assume that JTAG device has been opened using
ftd2jtag open command and that the Debug Access Port has
been powered up by invoking armdbg attach.
To print out the ROM Table:
| |
array set romtbl [armdgb romTable]
foreach blk [lsort [array names romtbl]] {
puts "$blk = [format %#x $romtbl($blk)]"
}
DWT = 0xe0001000
FPB = 0xe0002000
IMT = 0xe0000000
NVIC = 0xe000e000
TPIU = 0xe0040000
|
To read the first four words of the exception vector table,
located at address 0:
| |
set addr 0
foreach word [armdbg readWords $addr 16] {
puts [format "%08x: %08x" $addr $word]
incr addr 4
}
00000000: 20000358
00000004: 000000f5
00000008: 000000f9
0000000c: 000000fb
|
ftd2chan, ftd2jtag
JTAG , USB
Copyright © 2007 by G. Andrew Mangogna