@cindex logfile
@cindex directory search
+Properly installing OpenOCD sets up your operating system to grant it access
+to the JTAG adapters. On Linux, this usually involves installing a file
+in @file{/etc/udev/rules.d,} so OpenOCD has permissions. MS-Windows needs
+complex and confusing driver configuration for every peripheral. Such issues
+are unique to each operating system, and are not detailed in this User's Guide.
+
+Then later you will invoke the OpenOCD server, with various options to
+tell it how each debug session should work.
The @option{--help} option shows:
@verbatim
bash$ openocd --help
@end enumerate
The first found file with a matching file name will be used.
+@quotation Note
+Don't try to use configuration script names or paths which
+include the "#" character. That character begins Tcl comments.
+@end quotation
+
@section Simple setup, no customization
In the best case, you can use two scripts from one of the script
solution just avoids using that instruction with JTAG debuggers.
@end quotation
-If the board supports adaptive clocking, use the @command{jtag_rclk}
+If both the chip and the board support adaptive clocking,
+use the @command{jtag_rclk}
command, in case your board is used with JTAG adapter which
also supports it. Otherwise use @command{jtag_khz}.
Set the slow rate at the beginning of the reset sequence,
@cindex config file, interface
@cindex interface config file
+Correctly installing OpenOCD includes making your operating system give
+OpenOCD access to JTAG adapters. Once that has been done, Tcl commands
+are used to select which one is used, and to configure how it is used.
+
JTAG Adapters/Interfaces/Dongles are normally configured
through commands in an interface configuration
file which is sourced by your @file{openocd.cfg} file, or
@item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
@item @b{oocdlink} OOCDLink
@c oocdlink ~= jtagkey_prototype_v1
+@item @b{redbee-econotag} Integrated with a Redbee development board.
+@item @b{redbee-usb} Integrated with a Redbee USB-stick development board.
@item @b{sheevaplug} Marvell Sheevaplug development kit
@item @b{signalyzer} Xverve Signalyzer
@item @b{stm32stick} Hitex STM32 Performance Stick
may not be the fastest solution.
@b{NOTE:} Script writers should consider using @command{jtag_rclk}
-instead of @command{jtag_khz}.
+instead of @command{jtag_khz}, but only for (ARM) cores and boards
+which support adaptive clocking.
@deffn {Command} jtag_khz max_speed_kHz
A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
@end example
@end deffn
+@deffn Command {stellaris recover bank_id}
+Performs the @emph{Recovering a "Locked" Device} procedure to
+restore the flash specified by @var{bank_id} and its associated
+nonvolatile registers to their factory default values (erased).
+This is the only way to remove flash protection or re-enable
+debugging if that capability has been disabled.
+
+Note that the final "power cycle the chip" step in this procedure
+must be performed by hand, since OpenOCD can't do it.
+@quotation Warning
+if more than one Stellaris chip is connected, the procedure is
+applied to all of them.
+@end quotation
+@end deffn
+
@deffn {Flash Driver} stm32x
All members of the STM32 microcontroller family from ST Microelectronics
include internal flash and use ARM Cortex M3 cores.
@subsection Cortex-M3 specific commands
@cindex Cortex-M3
-@deffn Command {cortex_m3 disassemble} address [count]
-@cindex disassemble
-Disassembles @var{count} Thumb2 instructions starting at @var{address}.
-If @var{count} is not specified, a single instruction is disassembled.
-@end deffn
-
@deffn Command {cortex_m3 maskisr} (@option{on}|@option{off})
Control masking (disabling) interrupts during target step/resume.
@end deffn
@* Example: @b{ source [find FILENAME] }
@*Remember the parsing rules
@enumerate
-@item The FIND command is in square brackets.
-@* The FIND command is executed with the parameter FILENAME. It should
-find the full path to the named file. The RESULT is a string, which is
-substituted on the orginal command line.
-@item The command source is executed with the resulting filename.
-@* SOURCE reads a file and executes as a script.
+@item The @command{find} command is in square brackets,
+and is executed with the parameter FILENAME. It should find and return
+the full path to a file with that name; it uses an internal search path.
+The RESULT is a string, which is substituted into the command line in
+place of the bracketed @command{find} command.
+(Don't try to use a FILENAME which includes the "#" character.
+That character begins Tcl comments.)
+@item The @command{source} command is executed with the resulting filename;
+it reads a file and executes as a script.
@end enumerate
@subsection format command
@b{Where:} Generally occurs in numerous places.