* 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
For example, the beginning of an SRAM block is likely to
be used by most build systems, but the end is often unused.
-@item @code{-work-area-size} @var{size} -- specify/set the work area
+@item @code{-work-area-size} @var{size} -- specify work are size,
+in bytes. The same size applies regardless of whether its physical
+or virtual address is being used.
@item @code{-work-area-phys} @var{address} -- set the work area
base @var{address} to be used when no MMU is active.
@item @code{-work-area-virt} @var{address} -- set the work area
base @var{address} to be used when an MMU is active.
+@emph{Do not specify a value for this except on targets with an MMU.}
+The value should normally correspond to a static mapping for the
+@code{-work-area-phys} address, set up by the current operating system.
@end itemize
@end deffn
@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.
those instructions are not currently understood by OpenOCD.)
@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;
@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
Code Review / openocd.git / blobdiff