--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
@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
@}
you may encounter a problem.
@end deffn
+@deffn Command {parport_toggling_time} [nanoseconds]
+Displays how many nanoseconds the hardware needs to toggle TCK;
+the parport driver uses this value to obey the
+@command{jtag_khz} configuration.
+When the optional @var{nanoseconds} parameter is given,
+that setting is changed before displaying the current value.
+
+The default setting should work reasonably well on commodity PC hardware.
+However, you may want to calibrate for your specific hardware.
+@quotation Tip
+To measure the toggling time with a logic analyzer or a digital storage
+oscilloscope, follow the procedure below:
+@example
+> parport_toggling_time 1000
+> jtag_khz 500
+@end example
+This sets the maximum JTAG clock speed of the hardware, but
+the actual speed probably deviates from the requested 500 kHz.
+Now, measure the time between the two closest spaced TCK transitions.
+You can use @command{runtest 1000} or something similar to generate a
+large set of samples.
+Update the setting to match your measurement:
+@example
+> parport_toggling_time <measured nanoseconds>
+@end example
+Now the clock speed will be a better match for @command{jtag_khz rate}
+commands given in OpenOCD scripts and event handlers.
+
+You can do something similar with many digital multimeters, but note
+that you'll probably need to run the clock continuously for several
+seconds before it decides what clock rate to show. Adjust the
+toggling time up or down until the measured clock rate is a good
+match for the jtag_khz rate you specified; be conservative.
+@end quotation
+@end deffn
+
@deffn {Config Command} {parport_write_on_exit} (on|off)
This will configure the parallel driver to write a known
cable-specific value to the parallel interface on exiting OpenOCD
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
@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.
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}.
@end itemize
@end deffn
+@deffn Command {nand verify} num filename offset [option...]
+@cindex NAND verification
+@cindex NAND programming
+Verify the binary data in the file has been programmed to the
+specified NAND device, starting at the specified offset.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+Use a complete path name for @var{filename}, so you don't depend
+on the directory used to start the OpenOCD server.
+
+The @var{offset} must be an exact multiple of the device's page size.
+All data in the file will be read and compared to the contents of the
+flash, assuming it doesn't run past the end of the device.
+As with @command{nand write}, only full pages are verified, so any extra
+space in the last page will be filled with 0xff bytes.
+
+The same @var{options} accepted by @command{nand write},
+and the file will be processed similarly to produce the buffers that
+can be compared against the contents produced from @command{nand dump}.
+
+@b{NOTE:} This will not work when the underlying NAND controller
+driver's @code{write_page} routine must update the OOB with a
+hardward-computed ECC before the data is written. This limitation may
+be removed in a future release.
+@end deffn
+
@section Other NAND commands
@cindex NAND other commands
@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
Display contents of address @var{addr}, as
32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
or 8-bit bytes (@command{mdb}).
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
If @var{count} is specified, displays that many units.
-@var{phys} is an optional flag to indicate to use
-physical address and bypass MMU
(If you want to manipulate the data instead of displaying it,
see the @code{mem2array} primitives.)
@end deffn
@deffnx Command mwh [phys] addr halfword
@deffnx Command mwb [phys] addr byte
Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+@var{halfword} (16 bits), or @var{byte} (8-bit) value,
at the specified address @var{addr}.
-@var{phys} is an optional flag to indicate to use
-physical address and bypass MMU
+When the current target has an MMU which is present and active,
+@var{addr} is interpreted as a virtual address.
+Otherwise, or if the optional @var{phys} flag is specified,
+@var{addr} is interpreted as a physical address.
@end deffn
which are a function of silicon capabilties (exposed later
using @command{etm info}) and of what hardware is connected to
that port (such as an external pod, or ETB).
-The @var{width} must be either 4, 8, or 16.
-The @var{mode} must be @option{normal}, @option{multiplexted},
-or @option{demultiplexted}.
+The @var{width} must be either 4, 8, or 16,
+except with ETMv3.0 and newer modules which may also
+support 1, 2, 24, 32, 48, and 64 bit widths.
+(With those versions, @command{etm info} also shows whether
+the selected port width and mode are supported.)
+
+The @var{mode} must be @option{normal}, @option{multiplexed},
+or @option{demultiplexed}.
The @var{clocking} must be @option{half} or @option{full}.
+@quotation Warning
+With ETMv3.0 and newer, the bits set with the @var{mode} and
+@var{clocking} parameters both control the mode.
+This modified mode does not map to the values supported by
+previous ETM modules, so this syntax is subject to change.
+@end quotation
+
@quotation Note
You can see the ETM registers using the @command{reg} command.
Not all possible registers are present in every ETM.
@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 {armv4_5 reg}
+@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. 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}]
+@cindex ARM semihosting
+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
@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.
projects / fw / openocd / blobdiff