* General Commands:: General Commands
* Architecture and Core Commands:: Architecture and Core Commands
* JTAG Commands:: JTAG Commands
+* Boundary Scan Commands:: Boundary Scan Commands
* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
@b{Flash Programing:} Flash writing is supported for external CFI
compatible NOR flashes (Intel and AMD/Spansion command set) and several
-internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3, and
+internal flashes (LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
STM32x). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
@* See: @url{http://www.signalyzer.com}
@item @b{evb_lm3s811}
@* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
+@item @b{luminary_icdi}
+@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug Interface (ICDI) Board, included in the Stellaris LM3S9B90 and LM3S9B92 Evaluation Kits.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@item @b{Commands}
@* At the OpenOCD telnet command line (or via the GDB mon command) one
can type a Tcl for() loop, set variables, etc.
+Some of the commands documented in this guide are implemented
+as Tcl scripts, from a @file{startup.tcl} file internal to the server.
@item @b{Historical Note}
@* JIM-Tcl was introduced to OpenOCD in spring 2008.
A simple way to organize them all involves keeping a
single directory for your work with a given board.
When you start OpenOCD from that directory,
-it searches there first for configuration files
+it searches there first for configuration files, scripts,
and for code you upload to the target board.
It is also the natural place to write files,
such as log files and data you download from the board.
Likewise, the @command{arm9tdmi vector_catch} command (or
its @command{xscale vector_catch} sibling) can be a timesaver
during some debug sessions, but don't make everyone use that either.
-Keep those kinds of debugging aids in your user config file.
+Keep those kinds of debugging aids in your user config file,
+along with messaging and tracing setup.
+(@xref{Software Debug Messages and Tracing}.)
TCP/IP port configuration is another example of something which
is environment-specific, and should only appear in
set _CPUTAPID 0x3f0f0f0f
@}
@end example
+@c but 0x3f0f0f0f is for an str73x part ...
@emph{Remember:} Board config files may include multiple target
config files, or the same target file multiple times
examination of the instruction and data bus activity. Trace
activity is controlled through an ``Embedded Trace Module'' (ETM)
on one of the core's scan chains. The ETM emits voluminous data
-through a ``trace port''. (@xref{ARM Tracing}.)
+through a ``trace port''. (@xref{ARM Hardware Tracing}.)
If you are using an external trace port,
configure it in your board config file.
If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
@section Configuration Stage
@cindex configuration stage
-@cindex configuration command
+@cindex config command
When the OpenOCD server process starts up, it enters a
@emph{configuration stage} which is the only time that
certain commands, @emph{configuration commands}, may be issued.
-Those configuration commands include declaration of TAPs
+In this manual, the definition of a configuration command is
+presented as a @emph{Config Command}, not as a @emph{Command}
+which may be issued interactively.
+
+Those configuration commands include declaration of TAPs,
+flash banks,
+the interface used for JTAG communication,
and other basic setup.
The server must leave the configuration stage before it
may access or activate TAPs.
breakpoints if the memory map has been set up for flash regions.
@end deffn
-@deffn {Config command} gdb_detach (@option{resume}|@option{reset}|@option{halt}|@option{nothing})
+@deffn {Config Command} gdb_detach (@option{resume}|@option{reset}|@option{halt}|@option{nothing})
Configures what OpenOCD will do when GDB detaches from the daemon.
Default behaviour is @option{resume}.
@end deffn
@anchor{gdb_flash_program}
-@deffn {Config command} gdb_flash_program (@option{enable}|@option{disable})
+@deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
The default behaviour is @option{enable}.
@end deffn
-@deffn {Config command} gdb_memory_map (@option{enable}|@option{disable})
+@deffn {Config Command} gdb_memory_map (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when
requested. GDB will then know when to set hardware breakpoints, and program flash
using the GDB load command. @command{gdb_flash_program enable} must also be enabled
@xref{gdb_flash_program}.
@end deffn
-@deffn {Config command} gdb_report_data_abort (@option{enable}|@option{disable})
+@deffn {Config Command} gdb_report_data_abort (@option{enable}|@option{disable})
Specifies whether data aborts cause an error to be reported
by GDB memory read packets.
The default behaviour is @option{disable};
in case the vendor provides unique IDs and more than one FT2232 device
is connected to the host.
If not specified, serial numbers are not considered.
+(Note that USB serial numbers can be arbitrary Unicode strings,
+and are not restricted to containing only decimal digits.)
@end deffn
@deffn {Config Command} {ft2232_layout} name
@item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface,
either for the local Cortex-M3 (SRST only)
or in a passthrough mode (neither SRST nor TRST)
+@item @b{luminary_icdi} Luminary In-Circuit Debug Interface (ICDI) Board
@item @b{flyswatter} Tin Can Tools Flyswatter
@item @b{icebear} ICEbear JTAG adapter from Section 5
@item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
@defun jtag_rclk fallback_speed_kHz
@cindex RTCK
-This Tcl proc (defined in startup.tcl) attempts to enable RTCK/RCLK.
+This Tcl proc (defined in @file{startup.tcl}) attempts to enable RTCK/RCLK.
If that fails (maybe the interface, board, or target doesn't
support it), falls back to the specified frequency.
@example
@option{str912}, to support more than one chip of each type.
@xref{Config File Guidelines}.
-At this writing there is only a single command to work with
-scan chains, and there is no support for enumerating
-TAPs or examining their attributes.
+@deffn Command {jtag names}
+Returns the names of all current TAPs in the scan chain.
+Use @command{jtag cget} or @command{jtag tapisenabled}
+to examine attributes and state of each TAP.
+@example
+foreach t [jtag names] @{
+ puts [format "TAP: %s\n" $t]
+@}
+@end example
+@end deffn
@deffn Command {scan_chain}
Displays the TAPs in the scan chain configuration,
each TAP's instruction register can also change.
@end deffn
-@c FIXME! there should be commands to enumerate TAPs
-@c and get their attributes, like there are for targets.
-@c "jtag cget ..." will handle attributes.
-@c "jtag names" for enumerating TAPs, maybe.
+@c FIXME! "jtag cget" should be able to return all TAP
+@c attributes, like "$target_name cget" does for targets.
@c Probably want "jtag eventlist", and a "tap-reset" event
@c (on entry to RESET state).
In older code, JTAG TAPs were numbered from 0..N.
This feature is still present.
However its use is highly discouraged, and
-should not be counted upon.
-Update all of your scripts to use TAP names rather than numbers.
+should not be relied on; it will be removed by mid-2010.
+Update all of your scripts to use TAP names rather than numbers,
+by paying attention to the runtime warnings they trigger.
Using TAP numbers in target configuration scripts prevents
reusing those scripts on boards with multiple targets.
@end quotation
flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
@end example
+@c "cfi part_id" disabled
@end deffn
@subsection Internal Flash (Microcontrollers)
@end example
@end deffn
+@deffn {Flash Driver} at91sam3
+@cindex at91sam3
+All members of the AT91SAM3 microcontroller family from
+Atmel include internal flash and use ARM's Cortex-M3 core. The driver
+currently (6/22/09) recognizes the AT91SAM3U[1/2/4][C/E] chips. Note
+that the driver was orginaly developed and tested using the
+AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in
+the family was cribbed from the data sheet. @emph{Note to future
+readers/updaters: Please remove this worrysome comment after other
+chips are confirmed.}
+
+The AT91SAM3U4[E/C] (256K) chips have 2 flash banks, the other chips
+(3U[1/2][E/C]) have 1 flash bank. In all cases the flash banks are at
+the following fixed locations:
+
+@example
+# Flash bank 0 - all chips
+flash bank at91sam3 0x00080000 0 1 1 $_TARGETNAME
+# Flash bank 1 - only 256K chips
+flash bank at91sam3 0x00100000 0 1 1 $_TARGETNAME
+@end example
+
+Internally, the AT91SAM3 flash memory is organized as follows.
+Unlike the AT91SAM7 chips, these are not used as parameters
+to the @command{flash bank} command:
+
+@itemize
+@item @emph{N-Banks:} 256K chips have 2 banks, others have 1 bank.
+@item @emph{Bank Size:} 128K/64K Per flash bank
+@item @emph{Sectors:} 16 or 8 per bank
+@item @emph{SectorSize:} 8K Per Sector
+@item @emph{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes.
+@end itemize
+
+The AT91SAM3 driver adds some additional commands:
+
+@deffn Command {at91sam3 gpnvm}
+@deffnx Command {at91sam3 gpnvm clear} number
+@deffnx Command {at91sam3 gpnvm set} number
+@deffnx Command {at91sam3 gpnvm show} [@option{all}|number]
+With no parameters, @command{show} or @command{show all},
+shows the status of all GPNVM bits.
+With @command{show} @var{number}, displays that bit.
+
+With @command{set} @var{number} or @command{clear} @var{number},
+modifies that GPNVM bit.
+@end deffn
+
+@deffn Command {at91sam3 info}
+This command attempts to display information about the AT91SAM3
+chip. @emph{First} it read the @code{CHIPID_CIDR} [address 0x400e0740, see
+Section 28.2.1, page 505 of the AT91SAM3U 29/may/2009 datasheet,
+document id: doc6430A] and decodes the values. @emph{Second} it reads the
+various clock configuration registers and attempts to display how it
+believes the chip is configured. By default, the SLOWCLK is assumed to
+be 32768 Hz, see the command @command{at91sam3 slowclk}.
+@end deffn
+
+@deffn Command {at91sam3 slowclk} [value]
+This command shows/sets the slow clock frequency used in the
+@command{at91sam3 info} command calculations above.
+@end deffn
+@end deffn
+
@deffn {Flash Driver} at91sam7
-All members of the AT91SAM7 microcontroller family from Atmel
-include internal flash and use ARM7TDMI cores.
-The driver automatically recognizes a number of these chips using
-the chip identification register, and autoconfigures itself.
+All members of the AT91SAM7 microcontroller family from Atmel include
+internal flash and use ARM7TDMI cores. The driver automatically
+recognizes a number of these chips using the chip identification
+register, and autoconfigures itself.
@example
flash bank at91sam7 0 0 0 0 $_TARGETNAME
plane (of up to 256KB), and it will be used automatically when you issue
@command{flash erase_sector} or @command{flash erase_address} commands.
-@deffn Command {at91sam7 gpnvm} bitnum (set|clear)
+@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
bit for the processor. Each processor has a number of such bits,
used for controlling features such as brownout detection (so they
flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
lpc2000_v2 14765 calc_checksum
@end example
+
+@deffn {Command} {lpc2000 part_id} bank
+Displays the four byte part identifier associated with
+the specified flash @var{bank}.
+@end deffn
@end deffn
@deffn {Flash Driver} lpc288x
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x options_write} num (SWWDG|HWWDG) (RSTSTNDBY|NORSTSTNDBY) (RSTSTOP|NORSTSTOP)
+@deffn Command {stm32x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
Writes the stm32 option byte with the specified values.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@example
flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
@end example
+
+@deffn Command {str7x disable_jtag} bank
+Activate the Debug/Readout protection mechanism
+for the specified flash bank.
+@end deffn
@end deffn
@deffn {Flash Driver} str9x
@section Daemon Commands
+@deffn {Command} exit
+Exits the current telnet session.
+@end deffn
+
+@c note EXTREMELY ANNOYING word wrap at column 75
+@c even when lines are e.g. 100+ columns ...
+@c coded in startup.tcl
+@deffn {Command} help [string]
+With no parameters, prints help text for all commands.
+Otherwise, prints each helptext containing @var{string}.
+Not every command provides helptext.
+@end deffn
+
@deffn Command sleep msec [@option{busy}]
Wait for at least @var{msec} milliseconds before resuming.
If @option{busy} is passed, busy-wait instead of sleeping.
These commands are available when
OpenOCD is built with @option{--enable-ioutil}.
-They are mainly useful on embedded targets;
-PC type hosts have complementary tools.
+They are mainly useful on embedded targets,
+notably the ZY1000.
+Hosts with operating systems have complementary tools.
@emph{Note:} there are several more such commands.
+@deffn Command append_file filename [string]*
+Appends the @var{string} parameters to
+the text file @file{filename}.
+Each string except the last one is followed by one space.
+The last string is followed by a newline.
+@end deffn
+
+@deffn Command cat filename
+Reads and displays the text file @file{filename}.
+@end deffn
+
+@deffn Command cp src_filename dest_filename
+Copies contents from the file @file{src_filename}
+into @file{dest_filename}.
+@end deffn
+
+@deffn Command ip
+@emph{No description provided.}
+@end deffn
+
+@deffn Command ls
+@emph{No description provided.}
+@end deffn
+
+@deffn Command mac
+@emph{No description provided.}
+@end deffn
+
@deffn Command meminfo
Display available RAM memory on OpenOCD host.
Used in OpenOCD regression testing scripts.
@end deffn
+@deffn Command peek
+@emph{No description provided.}
+@end deffn
+
+@deffn Command poke
+@emph{No description provided.}
+@end deffn
+
+@deffn Command rm filename
+@c "rm" has both normal and Jim-level versions??
+Unlinks the file @file{filename}.
+@end deffn
+
+@deffn Command trunc filename
+Removes all data in the file @file{filename}.
+@end deffn
+
@anchor{Memory access}
@section Memory access commands
@cindex memory access
(@option{bin}, @option{ihex}, or @option{elf})
@end deffn
+@deffn Command {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
+Displays image section sizes and addresses
+as if @var{filename} were loaded into target memory
+starting at @var{address} (defaults to zero).
+The file format may optionally be specified
+(@option{bin}, @option{ihex}, or @option{elf})
+@end deffn
+
@deffn Command {verify_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
Verify @var{filename} against target memory starting at @var{address}.
The file format may optionally be specified
@end deffn
@section Misc Commands
-@cindex profiling
+@cindex profiling
@deffn Command {profile} seconds filename
Profiling samples the CPU's program counter as quickly as possible,
which is useful for non-intrusive stochastic profiling.
Saves up to 10000 sampines in @file{filename} using ``gmon.out'' format.
@end deffn
+@deffn Command {version}
+Displays a string identifying the version of this OpenOCD server.
+@end deffn
+
+@deffn Command {virt2phys} virtual_address
+Requests the current target to map the specified @var{virtual_address}
+to its corresponding physical address, and displays the result.
+@end deffn
+
@node Architecture and Core Commands
@chapter Architecture and Core Commands
@cindex Architecture Specific Commands
Some of those operations don't fit well in that framework, so they are
exposed here as architecture or implementation (core) specific commands.
-@anchor{ARM Tracing}
-@section ARM Tracing
+@anchor{ARM Hardware Tracing}
+@section ARM Hardware Tracing
+@cindex tracing
@cindex ETM
@cindex ETB
Control masking (disabling) interrupts during target step/resume.
@end deffn
-@section Target DCC Requests
+@anchor{Software Debug Messages and Tracing}
+@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
+@cindex tracing
@cindex libdcc
@cindex DCC
-OpenOCD can handle certain target requests; currently debugmsgs
+OpenOCD can process certain requests from target software. Currently
@command{target_request debugmsgs}
-are only supported for arm7_9 and cortex_m3.
+is supported only for @option{arm7_9} and @option{cortex_m3} cores.
+These messages are received as part of target polling, so
+you need to have @command{poll on} active to receive them.
+They are intrusive in that they will affect program execution
+times. If that is a problem, @pxref{ARM Hardware Tracing}.
+
+See @file{libdcc} in the contrib dir for more details.
+In addition to sending strings, characters, and
+arrays of various size integers from the target,
+@file{libdcc} also exports a software trace point mechanism.
+The target being debugged may
+issue trace messages which include a 24-bit @dfn{trace point} number.
+Trace point support includes two distinct mechanisms,
+each supported by a command:
+
+@itemize
+@item @emph{History} ... A circular buffer of trace points
+can be set up, and then displayed at any time.
+This tracks where code has been, which can be invaluable in
+finding out how some fault was triggered.
+
+The buffer may overflow, since it collects records continuously.
+It may be useful to use some of the 24 bits to represent a
+particular event, and other bits to hold data.
+
+@item @emph{Counting} ... An array of counters can be set up,
+and then displayed at any time.
+This can help establish code coverage and identify hot spots.
+
+The array of counters is directly indexed by the trace point
+number, so trace points with higher numbers are not counted.
+@end itemize
-See libdcc in the contrib dir for more details.
Linux-ARM kernels have a ``Kernel low-level debugging
via EmbeddedICE DCC channel'' option (CONFIG_DEBUG_ICEDCC,
depends on CONFIG_DEBUG_LL) which uses this mechanism to
deliver messages before a serial console can be activated.
+This is not the same format used by @file{libdcc}.
+Other software, such as the U-Boot boot loader, sometimes
+does the same thing.
@deffn Command {target_request debugmsgs} [@option{enable}|@option{disable}|@option{charmsg}]
Displays current handling of target DCC message requests.
These messages may be sent to the debugger while the target is running.
The optional @option{enable} and @option{charmsg} parameters
both enable the messages, while @option{disable} disables them.
+
With @option{charmsg} the DCC words each contain one character,
as used by Linux with CONFIG_DEBUG_ICEDCC;
otherwise the libdcc format is used.
@end deffn
+@deffn Command {trace history} (@option{clear}|count)
+With no parameter, displays all the trace points that have triggered
+in the order they triggered.
+With the parameter @option{clear}, erases all current trace history records.
+With a @var{count} parameter, allocates space for that many
+history records.
+@end deffn
+
+@deffn Command {trace point} (@option{clear}|identifier)
+With no parameter, displays all trace point identifiers and how many times
+they have been triggered.
+With the parameter @option{clear}, erases all current trace point counters.
+With a numeric @var{identifier} parameter, creates a new a trace point counter
+and associates it with that identifier.
+
+@emph{Important:} The identifier and the trace point number
+are not related except by this command.
+These trace point numbers always start at zero (from server startup,
+or after @command{trace point clear}) and count up from there.
+@end deffn
+
+
@node JTAG Commands
@chapter JTAG Commands
@cindex JTAG Commands
Consult the documentation for the TAP(s) you are working with.
@end itemize
+@node Boundary Scan Commands
+@chapter Boundary Scan Commands
+
+One of the original purposes of JTAG was to support
+boundary scan based hardware testing.
+Although its primary focus is to support On-Chip Debugging,
+OpenOCD also includes some boundary scan commands.
+
+@section SVF: Serial Vector Format
+@cindex Serial Vector Format
+@cindex SVF
+
+The Serial Vector Format, better known as @dfn{SVF}, is a
+way to represent JTAG test patterns in text files.
+OpenOCD supports running such test files.
+
+@deffn Command {svf} filename [@option{quiet}]
+This issues a JTAG reset (Test-Logic-Reset) and then
+runs the SVF script from @file{filename}.
+Unless the @option{quiet} option is specified,
+each command is logged before it is executed.
+@end deffn
+
+@section XSVF: Xilinx Serial Vector Format
+@cindex Xilinx Serial Vector Format
+@cindex XSVF
+
+The Xilinx Serial Vector Format, better known as @dfn{XSVF}, is a
+binary representation of SVF which is optimized for use with
+Xilinx devices.
+OpenOCD supports running such test files.
+
+@quotation Important
+Not all XSVF commands are supported.
+@end quotation
+
+@deffn Command {xsvf} (tapname|@option{plain}) filename [@option{virt2}] [@option{quiet}]
+This issues a JTAG reset (Test-Logic-Reset) and then
+runs the XSVF script from @file{filename}.
+When a @var{tapname} is specified, the commands are directed at
+that TAP.
+When @option{virt2} is specified, the @sc{xruntest} command counts
+are interpreted as TCK cycles instead of microseconds.
+Unless the @option{quiet} option is specified,
+messages are logged for comments and some retries.
+@end deffn
+
@node TFTP
@chapter TFTP
@cindex TFTP
@end itemize
OpenOCD commands can consist of two words, e.g. "flash banks". The
-startup.tcl "unknown" proc will translate this into a Tcl proc
+@file{startup.tcl} "unknown" proc will translate this into a Tcl proc
called "flash_banks".
@section OpenOCD specific Global Variables
@item @b{arm7_9 fast_writes}
@cindex arm7_9 fast_writes
@*Use @command{arm7_9 fast_memory_access} instead.
+@xref{arm7_9 fast_memory_access}.
@item @b{endstate}
@cindex endstate
@*An buggy old command that would not really work since background polling would wipe out the global endstate
-@xref{arm7_9 fast_memory_access}.
@item @b{arm7_9 force_hw_bkpts}
@*Use @command{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
for flash if the GDB memory map has been set up(default when flash is declared in
Code Review / openocd.git / blobdiff