--pipe | -p use pipes when talking to gdb
@end verbatim
-By default OpenOCD reads the file configuration file @file{openocd.cfg}
-in the current directory. To specify a different (or multiple)
-configuration file, you can use the ``-f'' option. For example:
+By default OpenOCD reads the configuration file @file{openocd.cfg}.
+To specify a different (or multiple)
+configuration file, you can use the @option{-f} option. For example:
@example
openocd -f config1.cfg -f config2.cfg -f config3.cfg
@end example
+Configuration files and scripts are searched for in
+@enumerate
+@item the current directory,
+@item any search dir specified on the command line using the @option{-s} option,
+@item @file{$HOME/.openocd} (not on Windows),
+@item the site wide script library @file{$pkgdatadir/site} and
+@item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}.
+@end enumerate
+The first found file with a matching file name will be used.
+
+@section Simple setup, no customization
+
+In the best case, you can use two scripts from one of the script
+libraries, hook up your JTAG adapter, and start the server ... and
+your JTAG setup will just work "out of the box". Always try to
+start by reusing those scripts, but assume you'll need more
+customization even if this works. @xref{OpenOCD Project Setup}.
+
+If you find a script for your JTAG adapter, and for your board or
+target, you may be able to hook up your JTAG adapter then start
+the server like:
+
+@example
+openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
+@end example
+
+You might also need to configure which reset signals are present,
+using @option{-c 'reset_config trst_and_srst'} or something similar.
+If all goes well you'll see output something like
+
+@example
+Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
+For bug reports, read
+ http://openocd.berlios.de/doc/doxygen/bugs.html
+Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
+ (mfg: 0x23b, part: 0xba00, ver: 0x3)
+@end example
+
+Seeing that "tap/device found" message, and no warnings, means
+the JTAG communication is working. That's a key milestone, but
+you'll probably need more project-specific setup.
+
+@section What OpenOCD does as it starts
+
OpenOCD starts by processing the configuration commands provided
-on the command line or in @file{openocd.cfg}.
+on the command line or, if there were no @option{-c command} or
+@option{-f file.cfg} options given, in @file{openocd.cfg}.
@xref{Configuration Stage}.
At the end of the configuration stage it verifies the JTAG scan
chain defined using those commands; your configuration should
those channels.
If you are having problems, you can enable internal debug messages via
-the ``-d'' option.
+the @option{-d} option.
Also it is possible to interleave JIM-Tcl commands w/config scripts using the
@option{-c} command line switch.
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
-Search paths for config/script files can be added to OpenOCD by using
-the @option{-s <search>} switch. The current directory and the OpenOCD
-target library is in the search path by default.
-
For details on the @option{-p} option. @xref{Connecting to GDB}.
Note! OpenOCD will launch the GDB & telnet server even if it can not
and then starting the OpenOCD server.
You also need to configure that server so that it knows
about that adapter and board, and helps your work.
+You may also want to connect OpenOCD to GDB, possibly
+using Eclipse or some other GUI.
@section Hooking up the JTAG Adapter
For Ethernet, consult the documentation and your network administrator.
For USB based JTAG adapters you have an easy sanity check at this point:
-does the host operating system see the JTAG adapter?
+does the host operating system see the JTAG adapter? If that host is an
+MS-Windows host, you'll need to install a driver before OpenOCD works.
@item @emph{Connect the adapter's power supply, if needed.}
This step is primarily for non-USB adapters,
single directory for your work with a given board.
When you start OpenOCD from that directory,
it searches there first for configuration files, scripts,
+files accessed through semihosting,
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.
@itemize @bullet
+@item @b{ARM Semihosting}...
+@cindex ARM semihosting
+When linked with a special runtime library provided with many
+toolchains@footnote{See chapter 8 "Semihosting" in
+@uref{http://infocenter.arm.com/help/topic/com.arm.doc.dui0203i/DUI0203I_rvct_developer_guide.pdf,
+ARM DUI 0203I}, the "RealView Compilation Tools Developer Guide".
+The CodeSourcery EABI toolchain also includes a semihosting library.},
+your target code can use I/O facilities on the debug host. That library
+provides a small set of system calls which are handled by OpenOCD.
+It can let the debugger provide your system console and a file system,
+helping with early debugging or providing a more capable environment
+for sometimes-complex tasks like installing system firmware onto
+NAND or SPI flash.
+
@item @b{ARM Wait-For-Interrupt}...
Many ARM chips synchronize the JTAG clock using the core clock.
Low power states which stop that core clock thus prevent JTAG access.
Some chips have specific ways the TRST and SRST signals are
managed. In the unusual case that these are @emph{chip specific}
and can never be changed by board wiring, they could go here.
+For example, some chips can't support JTAG debugging without
+both signals.
+
+Provide a @code{reset-assert} event handler if you can.
+Such a handler uses JTAG operations to reset the target,
+letting this target config be used in systems which don't
+provide the optional SRST signal, or on systems where you
+don't want to reset all targets at once.
+Such a handler might write to chip registers to force a reset,
+use a JRC to do that (preferable -- the target may be wedged!),
+or force a watchdog timer to trigger.
+(For Cortex-M3 targets, this is not necessary. The target
+driver knows how to use trigger an NVIC reset when SRST is
+not available.)
Some chips need special attention during reset handling if
they're going to be used with JTAG.
after the target's TAP has been reset, providing a
@code{reset-deassert-post} event handler that writes a chip
register to report that JTAG debugging is being done.
+Another would be reconfiguring the watchdog so that it stops
+counting while the core is halted in the debugger.
JTAG clocking constraints often change during reset, and in
some cases target config files (rather than board config files)
echo [format "set p15 0x%04x, 0x%08x" $regs $value]
- mcr 15 [expr ($regs>>12)&0x7] \
+ arm mcr 15 [expr ($regs>>12)&0x7] \
[expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \
[expr ($regs>>8)&0x7] $value
@}
Those handlers are Tcl procedures you can provide, which are invoked
at particular points in the reset sequence.
+@emph{When SRST is not an option} you must set
+up a @code{reset-assert} event handler for your target.
+For example, some JTAG adapters don't include the SRST signal;
+and some boards have multiple targets, and you won't always
+want to reset everything at once.
+
After configuring those mechanisms, you might still
find your board doesn't start up or reset correctly.
For example, maybe it needs a slightly different sequence
Here's what the scan chain might look like for a chip more than one TAP:
@verbatim
- TapName Enabled IdCode Expected IrLen IrCap IrMask Instr
--- ------------------ ------- ---------- ---------- ----- ----- ------ -----
- 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0 0 0x...
- 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x1 0 0xc
- 2 omap5912.unknown Y 0x00000000 0x00000000 8 0 0 0xff
+ TapName Enabled IdCode Expected IrLen IrCap IrMask
+-- ------------------ ------- ---------- ---------- ----- ----- ------
+ 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0x01 0x03
+ 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x01 0x0f
+ 2 omap5912.unknown Y 0x00000000 0x00000000 8 0x01 0x03
@end verbatim
+OpenOCD can detect some of that information, but not all
+of it. @xref{Autoprobing}.
Unfortunately those TAPs can't always be autoconfigured,
because not all devices provide good support for that.
JTAG doesn't require supporting IDCODE instructions, and
exiting the OpenOCD configuration stage,
but systems with a JTAG router can
enable or disable TAPs dynamically.
-In addition to the enable/disable status, the contents of
-each TAP's instruction register can also change.
@end deffn
@c FIXME! "jtag cget" should be able to return all TAP
reference manual. Sometimes you may need to probe the JTAG
hardware to find these values.
@xref{Autoprobing}.
+@item @code{-ignore-version}
+@*Specify this to ignore the JTAG version field in the @code{-expected-id}
+option. When vendors put out multiple versions of a chip, or use the same
+JTAG-level ID for several largely-compatible chips, it may be more practical
+to ignore the version field than to update config files to handle all of
+the various chip IDs.
@item @code{-ircapture} @var{NUMBER}
@*The bit pattern loaded by the TAP into the JTAG shift register
on entry to the @sc{ircapture} state, such as 0x01.
be detected and the normal reset behaviour used.
@end itemize
@item @code{dragonite} -- resembles arm966e
+@item @code{dsp563xx} -- implements Freescale's 24-bit DSP.
+(Support for this is still incomplete.)
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core. This supports one variant:
@code{pxa27x} ... instruction register length is 7 bits
@item @code{pxa250}, @code{pxa255},
@code{pxa26x} ... instruction register length is 5 bits
+@item @code{pxa3xx} ... instruction register length is 11 bits
@end itemize
@end itemize
@end deffn
@itemize @bullet
@item What should happen when GDB connects? Should your target reset?
@item When GDB tries to flash the target, do you need to enable the flash via a special command?
+@item Is using SRST appropriate (and possible) on your system?
+Or instead of that, do you need to issue JTAG commands to trigger reset?
+SRST usually resets everything on the scan chain, which can be inappropriate.
@item During reset, do you need to write to certain memory locations
to set up system clocks or
to reconfigure the SDRAM?
+How about configuring the watchdog timer, or other peripherals,
+to stop running while you hold the core stopped for debugging?
@end itemize
All of the above items can be addressed by target event handlers.
@item @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
after @command{reset_init} was triggered
-but before SRST alone is re-asserted on the tap.
+but before either SRST alone is re-asserted on the scan chain,
+or @code{reset-assert} is triggered.
+@item @b{reset-assert}
+@* Issued as part of @command{reset} processing
+after @command{reset-assert-pre} was triggered.
+When such a handler is present, cores which support this event will use
+it instead of asserting SRST.
+This support is essential for debugging with JTAG interfaces which
+don't include an SRST line (JTAG doesn't require SRST), and for
+selective reset on scan chains that have multiple targets.
@item @b{reset-assert-post}
@* Issued as part of @command{reset} processing
-when SRST is asserted on the tap.
+after @code{reset-assert} has been triggered.
+or the target asserted SRST on the entire scan chain.
@item @b{reset-deassert-pre}
@* Issued as part of @command{reset} processing
-when SRST is about to be released on the tap.
+after @code{reset-assert-post} has been triggered.
@item @b{reset-deassert-post}
@* Issued as part of @command{reset} processing
-when SRST has been released on the tap.
+after @code{reset-deassert-pre} has been triggered
+and (if the target is using it) after SRST has been
+released on the scan chain.
@item @b{reset-end}
@* Issued as the final step in @command{reset} processing.
@ignore
@comment the REAL name for this command is "ocd_flash_banks"
@comment less confusing would be: "flash list" (like "nand list")
@deffn Command {flash banks}
-Prints a one-line summary of each device declared
-using @command{flash bank}, numbered from zero.
+Prints a one-line summary of each device that was
+declared using @command{flash bank}, numbered from zero.
Note that this is the @emph{plural} form;
the @emph{singular} form is a very different command.
@end deffn
+@deffn Command {flash list}
+Retrieves a list of associative arrays for each device that was
+declared using @command{flash bank}, numbered from zero.
+This returned list can be manipulated easily from within scripts.
+@end deffn
+
@deffn Command {flash probe} num
Identify the flash, or validate the parameters of the configured flash. Operation
depends on the flash type.
with the current XScale trace support, or should be
shared with eventual Nexus-style trace module support.
-At this writing (September 2009) only ARM7 and ARM9 support
+At this writing (November 2009) only ARM7, ARM9, and ARM11 support
for ETM modules is available. The code should be able to
work with some newer cores; but not all of them support
this original style of JTAG access.
@end itemize
@end deffn
-@deffn Command {etm trigger_percent} [percent]
-This displays, or optionally changes, the trace port driver's
-behavior after the ETM's configured @emph{trigger} event fires.
-It controls how much more trace data is saved after the (single)
-trace trigger becomes active.
-
-@itemize
-@item The default corresponds to @emph{trace around} usage,
-recording 50 percent data before the event and the rest
-afterwards.
-@item The minimum value of @var{percent} is 2 percent,
-recording almost exclusively data before the trigger.
-Such extreme @emph{trace before} usage can help figure out
-what caused that event to happen.
-@item The maximum value of @var{percent} is 100 percent,
-recording data almost exclusively after the event.
-This extreme @emph{trace after} usage might help sort out
-how the event caused trouble.
-@end itemize
-@c REVISIT allow "break" too -- enter debug mode.
-@end deffn
-
@subsection ETM Trace Operation
After setting up the ETM, you can use it to collect data.
Associates the ETM for @var{target} with the ETB at @var{etb_tap}.
You can see the ETB registers using the @command{reg} command.
@end deffn
+@deffn Command {etb trigger_percent} [percent]
+This displays, or optionally changes, ETB behavior after the
+ETM's configured @emph{trigger} event fires.
+It controls how much more trace data is saved after the (single)
+trace trigger becomes active.
+
+@itemize
+@item The default corresponds to @emph{trace around} usage,
+recording 50 percent data before the event and the rest
+afterwards.
+@item The minimum value of @var{percent} is 2 percent,
+recording almost exclusively data before the trigger.
+Such extreme @emph{trace before} usage can help figure out
+what caused that event to happen.
+@item The maximum value of @var{percent} is 100 percent,
+recording data almost exclusively after the event.
+This extreme @emph{trace after} usage might help sort out
+how the event caused trouble.
+@end itemize
+@c REVISIT allow "break" too -- enter debug mode.
+@end deffn
+
@end deffn
@deffn {Trace Port Driver} oocd_trace
ThumbEE disassembly currently has no explicit support.
@end deffn
+@deffn Command {arm mcr} pX op1 CRn CRm op2 value
+Write @var{value} to a coprocessor @var{pX} register
+passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and using the MCR instruction.
+(Parameter sequence matches the ARM instruction, but omits
+an ARM register.)
+@end deffn
+
+@deffn Command {arm mrc} pX coproc op1 CRn CRm op2
+Read a coprocessor @var{pX} register passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and the MRC instruction.
+Returns the result so it can be manipulated by Jim scripts.
+(Parameter sequence matches the ARM instruction, but omits
+an ARM register.)
+@end deffn
+
@deffn Command {arm reg}
Display a table of all banked core registers, fetching the current value from every
core mode if necessary.
speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
+@deffn Command {arm7_9 semihosting} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Display status of semihosting, after optionally changing that status.
+
+Semihosting allows for code executing on an ARM target to use the
+I/O facilities on the host computer i.e. the system where OpenOCD
+is running. The target application must be linked against a library
+implementing the ARM semihosting convention that forwards operation
+requests by using a special SVC instruction that is trapped at the
+Supervisor Call vector by OpenOCD.
+@end deffn
+
@subsection ARM720T specific commands
@cindex ARM720T
@cindex tracing
@cindex libdcc
@cindex DCC
-OpenOCD can process certain requests from target software. Currently
-@command{target_request debugmsgs}
+OpenOCD can process certain requests from target software, when
+the target uses appropriate libraries.
+The most powerful mechanism is semihosting, but there is also
+a lighter weight mechanism using only the DCC channel.
+
+Currently @command{target_request debugmsgs}
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.
@cindex GDB
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
+Setting up GDB to work with OpenOCD can involve several components:
+
+@itemize
+@item OpenOCD itself may need to be configured. @xref{GDB Configuration}.
+@item GDB itself may need configuration, as shown in this chapter.
+@item If you have a GUI environment like Eclipse,
+that also will probably need to be configured.
+@end itemize
+
+Of course, the version of GDB you use will need to be one which has
+been built to know about the target CPU you're using. It's probably
+part of the tool chain you're using. For example, if you are doing
+cross-development for ARM on an x86 PC, instead of using the native
+x86 @command{gdb} command you might use @command{arm-none-eabi-gdb}
+if that's the tool chain used to compile your code.
@anchor{Connecting to GDB}
@section Connecting to GDB
To list the available OpenOCD commands type @command{monitor help} on the
GDB command line.
+@section Configuring GDB for OpenOCD
+
OpenOCD supports the gdb @option{qSupported} packet, this enables information
to be sent by the GDB remote server (i.e. OpenOCD) to GDB. Typical information includes
packet size and the device's memory map.
+You do not need to configure the packet size by hand,
+and the relevant parts of the memory map should be automatically
+set up when you declare (NOR) flash banks.
+
+However, there are other things which GDB can't currently query.
+You may need to set those up by hand.
+As OpenOCD starts up, you will often see a line reporting
+something like:
-Previous versions of OpenOCD required the following GDB options to increase
-the packet size and speed up GDB communication:
@example
-set remote memory-write-packet-size 1024
-set remote memory-write-packet-size fixed
-set remote memory-read-packet-size 1024
-set remote memory-read-packet-size fixed
+Info : lm3s.cpu: hardware has 6 breakpoints, 4 watchpoints
@end example
-This is now handled in the @option{qSupported} PacketSize and should not be required.
+
+You can pass that information to GDB with these commands:
+
+@example
+set remote hardware-breakpoint-limit 6
+set remote hardware-watchpoint-limit 4
+@end example
+
+With that particular hardware (Cortex-M3) the hardware breakpoints
+only work for code running from flash memory. Most other ARM systems
+do not have such restrictions.
@section Programming using GDB
@cindex Programming using GDB
Code Review / openocd.git / blobdiff