X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=bb96a2e63e2bcd0966c80a17ef474935417f2fb1;hb=1e51cf049cfed3bc42a748d848210f8e4b472282;hp=8e1d1a8f60614d51c9d70fbc74d128f100dd4cd7;hpb=9253ce9baea6f7b5ef3fc53b4bc0cfbff48194f4;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 8e1d1a8f60..bb96a2e63e 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -81,7 +81,6 @@ Free Documentation License''. * 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 @@ -1503,7 +1502,7 @@ proc setc15 @{regs value@} @{ 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 @} @@ -1976,6 +1975,42 @@ When using PPDEV to access the parallel port, use the number of the parallel por 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 +@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 @@ -5052,9 +5087,11 @@ about what TAP is the current target, or about MMU configuration. 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 @@ -5063,10 +5100,12 @@ see the @code{mem2array} primitives.) @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 @@ -5256,11 +5295,23 @@ Several of the parameters must reflect the trace port capabilities, 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. @@ -5797,15 +5848,6 @@ Without arguments, the current settings are displayed. @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 @@ -5822,15 +5864,6 @@ which is enabled by default. 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; @@ -6507,91 +6540,6 @@ We should add support for a variable like Tcl variable 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