* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
-* Upgrading:: Deprecated/Removed Commands
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
echo [format "set p15 0x%04x, 0x%08x" $regs $value]
- arm11 mcr $TARGETNAME 15 [expr ($regs>>12)&0x7] \
+ 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
@end deffn
@anchor{Flash Driver List}
-@section Flash Drivers, Options, and Commands
+@section Flash Driver List
As noted above, the @command{flash bank} command requires a driver name,
and allows driver-specific options and behaviors.
Some drivers also activate driver-specific commands.
Frequently the first such chip is used to boot the system.
Your board's @code{reset-init} handler might need to
configure additional chip selects using other commands (like: @command{mww} to
-configure a bus and its timings) , or
+configure a bus and its timings), or
perhaps configure a GPIO pin that controls the ``write protect'' pin
on the flash chip.
The CFI driver can use a target-specific working area to significantly
flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
@end example
+
+To configure one bank of 32 MBytes
+built from two sixteen bit (two byte) wide parts wired in parallel
+to create a thirty-two bit (four byte) bus with doubled throughput:
+
+@example
+flash bank cfi 0x00000000 0x02000000 2 4 $_TARGETNAME
+@end example
+
@c "cfi part_id" disabled
@end deffn
@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
@end deffn
@anchor{NAND Driver List}
-@section NAND Drivers, Options, and Commands
+@section NAND Driver List
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
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 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.
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 mcr} pX opc1 CRn CRm opc2 value
-Write @var{value} to a coprocessor @var{pX} register
-passing parameters @var{CRn},
-@var{CRm}, opcodes @var{opc1} and @var{opc2},
-and the MCR instruction.
-(The difference beween this and the MCR2 instruction is
-one bit in the encoding, effecively a fifth parameter.)
-@end deffn
-
@deffn Command {arm11 memwrite burst} [value]
Displays the value of the memwrite burst-enable flag,
which is enabled by default. Burst writes are only used
If @var{value} is defined, first assigns that.
@end deffn
-@deffn Command {arm11 mrc} pX opc1 CRn CRm opc2
-Read a coprocessor @var{pX} register passing parameters @var{CRn},
-@var{CRm}, opcodes @var{opc1} and @var{opc2},
-and the MRC instruction.
-(The difference beween this and the MRC2 instruction is
-one bit in the encoding, effecively a fifth parameter.)
-Displays the result.
-@end deffn
-
@deffn Command {arm11 step_irq_enable} [value]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
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
@section OpenOCD specific Global Variables
-@subsection HostOS
-
Real Tcl has ::tcl_platform(), and platform::identify, and many other
-variables. JimTCL, as implemented in OpenOCD creates $HostOS which
+variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which
holds one of the following values:
@itemize @bullet
is jim, not real tcl).
@end quotation
-@node Upgrading
-@chapter Deprecated/Removed Commands
-@cindex Deprecated/Removed Commands
-Certain OpenOCD commands have been deprecated or
-removed during the various revisions.
-
-Upgrade your scripts as soon as possible.
-These descriptions for old commands may be removed
-a year after the command itself was removed.
-This means that in January 2010 this chapter may
-become much shorter.
-
-@itemize @bullet
-@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
-@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
-target configuration). @xref{gdb_breakpoint_override}.
-@item @b{arm7_9 sw_bkpts}
-@*On by default. @xref{gdb_breakpoint_override}.
-@item @b{daemon_startup}
-@*this config option has been removed, simply adding @option{init} and @option{reset halt} to
-the end of your config script will give the same behaviour as using @option{daemon_startup reset}
-and @option{target cortex_m3 little reset_halt 0}.
-@item @b{dump_binary}
-@*use @option{dump_image} command with same args. @xref{dump_image}.
-@item @b{flash erase}
-@*use @option{flash erase_sector} command with same args. @xref{flash erase_sector}.
-@item @b{flash write}
-@*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
-@item @b{flash write_binary}
-@*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
-@item @b{flash auto_erase}
-@*use @option{flash write_image} command passing @option{erase} as the first parameter. @xref{flash write_image}.
-
-@item @b{jtag_device}
-@*use the @command{jtag newtap} command, converting from positional syntax
-to named prefixes, and naming the TAP.
-@xref{jtag newtap}.
-Note that if you try to use the old command, a message will tell you the
-right new command to use; and that the fourth parameter in the old syntax
-was never actually used.
-@example
-OLD: jtag_device 8 0x01 0xe3 0xfe
-NEW: jtag newtap CHIPNAME TAPNAME \
- -irlen 8 -ircapture 0x01 -irmask 0xe3
-@end example
-
-@item @b{jtag_speed} value
-@*@xref{JTAG Speed}.
-Usually, a value of zero means maximum
-speed. The actual effect of this option depends on the JTAG interface used.
-@itemize @minus
-@item wiggler: maximum speed / @var{number}
-@item ft2232: 6MHz / (@var{number}+1)
-@item amt jtagaccel: 8 / 2**@var{number}
-@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
-@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
-@comment end speed list.
-@end itemize
-
-@item @b{load_binary}
-@*use @option{load_image} command with same args. @xref{load_image}.
-@item @b{run_and_halt_time}
-@*This command has been removed for simpler reset behaviour, it can be simulated with the
-following commands:
-@smallexample
-reset run
-sleep 100
-halt
-@end smallexample
-@item @b{target} <@var{type}> <@var{endian}> <@var{jtag-position}>
-@*use the create subcommand of @option{target}.
-@item @b{target_script} <@var{target#}> <@var{eventname}> <@var{scriptname}>
-@*use <@var{target_name}> configure -event <@var{eventname}> "script <@var{scriptname}>"
-@item @b{working_area}
-@*use the @option{configure} subcommand of @option{target} to set the work-area-virt, work-area-phy, work-area-size, and work-area-backup properties of the target.
-@end itemize
-
@node FAQ
@chapter FAQ
@cindex faq