--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.
+
OpenOCD starts by processing the configuration commands provided
on the command line or in @file{openocd.cfg}.
@xref{Configuration Stage}.
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
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
@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
@section Flash Configuration Commands
@cindex flash configuration
-@deffn {Config Command} {flash bank} driver base size chip_width bus_width target [driver_options]
+@deffn {Config Command} {flash bank} name driver base size chip_width bus_width target [driver_options]
Configures a flash bank which provides persistent storage
for addresses from @math{base} to @math{base + size - 1}.
These banks will often be visible to GDB through the target's memory map.
see the driver-specific documentation.
@itemize @bullet
+@item @var{name} ... may be used to reference the flash bank
+in other flash commands.
@item @var{driver} ... identifies the controller driver
associated with the flash bank being declared.
This is usually @code{cfi} for external flash, or else
plus some additional configuration that's done after
OpenOCD has initialized.
-@deffn {Config Command} {nand device} controller target [configparams...]
+@deffn {Config Command} {nand device} name controller target [configparams...]
Declares a NAND device, which can be read and written to
after it has been configured through @command{nand probe}.
In OpenOCD, devices are single chips; this is unlike some
configuration files, not interactively.
@itemize @bullet
+@item @var{name} ... may be used to reference the NAND bank
+in other commands.
@item @var{controller} ... identifies the controller driver
associated with the NAND device being declared.
@xref{NAND Driver List}.
@deffn Command reg [(number|name) [value]]
Access a single register by @var{number} or by its @var{name}.
+The target must generally be halted before access to CPU core
+registers is allowed. Depending on the hardware, some other
+registers may be accessible while the target is running.
@emph{With no arguments}:
list all available registers for the current target,
showing number, name, size, value, and cache status.
+For valid entries, a value is shown; valid entries
+which are also dirty (and will be written back later)
+are flagged as such.
@emph{With number/name}: display that register's value.
@emph{With both number/name and value}: set register's value.
+Writes may be held in a writeback cache internal to OpenOCD,
+so that setting the value marks the register as dirty instead
+of immediately flushing that value. Resuming CPU execution
+(including by single stepping) or otherwise activating the
+relevant module will flush such values.
Cores may have surprisingly many registers in their
Debug and trace infrastructure:
@example
> reg
-(0) r0 (/32): 0x0000D3C2 (dirty: 1, valid: 1)
-(1) r1 (/32): 0xFD61F31C (dirty: 0, valid: 1)
-(2) r2 (/32): 0x00022551 (dirty: 0, valid: 1)
+===== ARM registers
+(0) r0 (/32): 0x0000D3C2 (dirty)
+(1) r1 (/32): 0xFD61F31C
+(2) r2 (/32)
...
-(164) ETM_CONTEXTID_COMPARATOR_MASK (/32): \
- 0x00000000 (dirty: 0, valid: 0)
+(164) ETM_contextid_comparator_mask (/32)
>
@end example
@end deffn
@end deffn
-@section ARMv4 and ARMv5 Architecture
-@cindex ARMv4
-@cindex ARMv5
+@section Generic ARM
+@cindex ARM
-These commands are specific to ARM architecture v4 and v5,
-including all ARM7 or ARM9 systems and Intel XScale.
+These commands should be available on all ARM processors.
They are available in addition to other core-specific
commands that may be available.
-@deffn Command {armv4_5 core_state} [@option{arm}|@option{thumb}]
+@deffn Command {arm core_state} [@option{arm}|@option{thumb}]
Displays the core_state, optionally changing it to process
either @option{arm} or @option{thumb} instructions.
The target may later be resumed in the currently set core_state.
that is not currently supported in OpenOCD.)
@end deffn
-@deffn Command {armv4_5 disassemble} address [count [@option{thumb}]]
+@deffn Command {arm disassemble} address [count [@option{thumb}]]
@cindex disassemble
Disassembles @var{count} instructions starting at @var{address}.
If @var{count} is not specified, a single instruction is disassembled.
If @option{thumb} is specified, or the low bit of the address is set,
-Thumb (16-bit) instructions are used;
+Thumb2 (mixed 16/32-bit) instructions are used;
else ARM (32-bit) instructions are used.
(Processors may also support the Jazelle state, but
those instructions are not currently understood by OpenOCD.)
+
+Note that all Thumb instructions are Thumb2 instructions,
+so older processors (without Thumb2 support) will still
+see correct disassembly of Thumb code.
+Also, ThumbEE opcodes are the same as Thumb2,
+with a handful of exceptions.
+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 {armv4_5 reg}
+@deffn Command {arm reg}
Display a table of all banked core registers, fetching the current value from every
-core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
-register value.
+core mode if necessary.
@end deffn
+@section ARMv4 and ARMv5 Architecture
+@cindex ARMv4
+@cindex ARMv5
+
+The ARMv4 and ARMv5 architectures are widely used in embedded systems,
+and introduced core parts of the instruction set in use today.
+That includes the Thumb instruction set, introduced in the ARMv4T
+variant.
+
@subsection ARM7 and ARM9 specific commands
@cindex ARM7
@cindex ARM9
These commands are specific to ARM7 and ARM9 cores, like ARM7TDMI, ARM720T,
ARM9TDMI, ARM920T or ARM926EJ-S.
-They are available in addition to the ARMv4/5 commands,
+They are available in addition to the ARM commands,
and any other core-specific commands that may be available.
@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
-@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
-@emph{This is intended for use while debugging OpenOCD; you probably
-shouldn't use it.}
+@deffn Command {arm7_9 semihosting} [@option{enable}|@option{disable}]
+Display status of semihosting, after optionally changing that status.
-Writes a 32-bit @var{word} to register @var{num} (from 0 to 16)
-as used in the specified @var{mode}
-(where e.g. mode 16 is "user" and mode 19 is "supervisor";
-the M4..M0 bits of the PSR).
-Registers 0..15 are the normal CPU registers such as r0(0), r1(1) ... pc(15).
-Register 16 is the mode-specific SPSR,
-unless the specified mode is 0xffffffff (32-bit all-ones)
-in which case register 16 is the CPSR.
-The write goes directly to the CPU, bypassing the register cache.
-@end deffn
-
-@deffn {Debug Command} {arm7_9 write_xpsr} word (@option{0}|@option{1})
-@emph{This is intended for use while debugging OpenOCD; you probably
-shouldn't use it.}
-
-If the second parameter is zero, writes @var{word} to the
-Current Program Status register (CPSR).
-Else writes @var{word} to the current mode's Saved PSR (SPSR).
-In both cases, this bypasses the register cache.
-@end deffn
-
-@deffn {Debug Command} {arm7_9 write_xpsr_im8} byte rotate (@option{0}|@option{1})
-@emph{This is intended for use while debugging OpenOCD; you probably
-shouldn't use it.}
-
-Writes eight bits to the CPSR or SPSR,
-first rotating them by @math{2*rotate} bits,
-and bypassing the register cache.
-This has lower JTAG overhead than writing the entire CPSR or SPSR
-with @command{arm7_9 write_xpsr}.
+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
These commands are available to ARM720T based CPUs,
which are implementations of the ARMv4T architecture
based on the ARM7TDMI-S integer core.
-They are available in addition to the ARMv4/5 and ARM7/ARM9 commands.
+They are available in addition to the ARM and ARM7/ARM9 commands.
@deffn Command {arm720t cp15} regnum [value]
Display cp15 register @var{regnum};
These commands are available to ARM920T based CPUs,
which are implementations of the ARMv4T architecture
built using the ARM9TDMI integer core.
-They are available in addition to the ARMv4/5, ARM7/ARM9,
-and ARM9TDMI commands.
+They are available in addition to the ARM, ARM7/ARM9,
+and ARM9 commands.
@deffn Command {arm920t cache_info}
Print information about the caches found. This allows to see whether your target
These commands are available to ARM926ej-s based CPUs,
which are implementations of the ARMv5TEJ architecture
based on the ARM9EJ-S integer core.
-They are available in addition to the ARMv4/5, ARM7/ARM9,
-and ARM9TDMI commands.
+They are available in addition to the ARM, ARM7/ARM9,
+and ARM9 commands.
The Feroceon cores also support these commands, although
they are not built from ARM926ej-s designs.
Print information about the caches found.
@end deffn
-@deffn Command {arm926ejs cp15} opcode1 opcode2 CRn CRm regnum [value]
-Accesses cp15 register @var{regnum} using
-@var{opcode1}, @var{opcode2}, @var{CRn}, and @var{CRm}.
-If a @var{value} is provided, that value is written to that register.
-Else that register is read and displayed.
-@end deffn
-
@subsection ARM966E specific commands
@cindex ARM966E
These commands are available to ARM966 based CPUs,
which are implementations of the ARMv5TE architecture.
-They are available in addition to the ARMv4/5, ARM7/ARM9,
-and ARM9TDMI commands.
+They are available in addition to the ARM, ARM7/ARM9,
+and ARM9 commands.
@deffn Command {arm966e cp15} regnum [value]
Display cp15 register @var{regnum};
@cindex Debug Access Port
@cindex DAP
These commands are specific to ARM architecture v7 Debug Access Port (DAP),
-included on cortex-m3 and cortex-a8 systems.
+included on Cortex-M3 and Cortex-A8 systems.
They are available in addition to other core-specific commands that may be available.
@deffn Command {dap info} [num]
If @var{value} is defined, first assigns that.
@end deffn
-@subsection ARMv7-A specific commands
-@cindex ARMv7-A
-
-@deffn Command {armv7a disassemble} address [count [@option{thumb}]]
-@cindex disassemble
-Disassembles @var{count} instructions starting at @var{address}.
-If @var{count} is not specified, a single instruction is disassembled.
-If @option{thumb} is specified, or the low bit of the address is set,
-Thumb2 (mixed 16/32-bit) instructions are used;
-else ARM (32-bit) instructions are used.
-With a handful of exceptions, ThumbEE instructions are the same as Thumb2;
-ThumbEE disassembly currently has no explicit support.
-(Processors may also support the Jazelle state, but
-those instructions are not currently understood by OpenOCD.)
-@end deffn
-
-
@subsection Cortex-M3 specific commands
@cindex Cortex-M3