@section Choosing a Dongle
-There are three things you should keep in mind when choosing a dongle.
+There are several things you should keep in mind when choosing a dongle.
-@enumerate
-@item @b{Voltage} What voltage is your target? 1.8, 2.8, 3.3, or 5V? Does your dongle support it?
-@item @b{Connection} Printer Ports - Does your computer have one?
-@item @b{Connection} Is that long printer bit-bang cable practical?
-@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
+@enumerate
+@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
+Does your dongle support it? You might need a level converter.
+@item @b{Pinout} What pinout does your target board use?
+Does your dongle support it? You may be able to use jumper
+wires, or an "octopus" connector, to convert pinouts.
+@item @b{Connection} Does your computer have the USB, printer, or
+Ethernet port needed?
+@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
@end enumerate
@section Stand alone Systems
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
-@item @b{USB - Presto}
+@item @b{USB - Presto}
@* Link: @url{http://tools.asix.net/prg_presto.htm}
@item @b{Versaloon-Link}
and the MacGraigor Wiggler. There are many clones and variations of
these on the market.
+Note that parallel ports are becoming much less common, so if you
+have the choice you should probably avoid these adapters in favor
+of USB-based ones.
+
@itemize @bullet
@item @b{Wiggler} - There are many clones of this.
--pipe | -p use pipes when talking to gdb
@end verbatim
-By default OpenOCD reads the file configuration file ``openocd.cfg''
+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:
@example
- openocd -f config1.cfg -f config2.cfg -f config3.cfg
+openocd -f config1.cfg -f config2.cfg -f config3.cfg
@end example
-Once started, OpenOCD runs as a daemon, waiting for connections from
-clients (Telnet, GDB, Other).
+OpenOCD starts by processing the configuration commands provided
+on the command line or in @file{openocd.cfg}.
+@xref{Configuration Stage}.
+At the end of the configuration stage it verifies the JTAG scan
+chain defined using those commands; your configuration should
+ensure that this always succeeds.
+Normally, OpenOCD then starts running as a daemon.
+Alternatively, commands may be used to terminate the configuration
+stage early, perform work (such as updating some flash memory),
+and then shut down without acting as a daemon.
+
+Once OpenOCD starts running as a daemon, it waits for connections from
+clients (Telnet, GDB, Other) and processes the commands issued through
+those channels.
If you are having problems, you can enable internal debug messages via
the ``-d'' option.
When you write config files, separate the reusable parts
(things every user of that interface, chip, or board needs)
from ones specific to your environment and debugging approach.
+@itemize
+@item
For example, a @code{gdb-attach} event handler that invokes
the @command{reset init} command will interfere with debugging
early boot code, which performs some of the same actions
that the @code{reset-init} event handler does.
+
+@item
Likewise, the @command{arm9tdmi vector_catch} command (or
@cindex vector_catch
its siblings @command{xscale vector_catch}
along with messaging and tracing setup.
(@xref{Software Debug Messages and Tracing}.)
+@item
+You might need to override some defaults.
+For example, you might need to move, shrink, or back up the target's
+work area if your application needs much SRAM.
+
+@item
TCP/IP port configuration is another example of something which
is environment-specific, and should only appear in
a user config file. @xref{TCP/IP Ports}.
+@end itemize
@section Project-Specific Utilities
@subsection JTAG Clock Rate
Before your @code{reset-init} handler has set up
-the PLLs and clocking, you may need to use
-a low JTAG clock rate; then you'd increase it later.
-(The rule of thumb for ARM-based processors is 1/8 the CPU clock.)
+the PLLs and clocking, you may need to run with
+a low JTAG clock rate.
+@xref{JTAG Speed}.
+Then you'd increase that rate after your handler has
+made it possible to use the faster JTAG clock.
+When the initial low speed is board-specific, for example
+because it depends on a board-specific oscillator speed, then
+you should probably set it up in the board config file;
+if it's target-specific, it belongs in the target config file.
+
+For most ARM-based processors the fastest JTAG clock@footnote{A FAQ
+@uref{http://www.arm.com/support/faqdev/4170.html} gives details.}
+is one sixth of the CPU clock; or one eighth for ARM11 cores.
+Consult chip documentation to determine the peak JTAG clock rate,
+which might be less than that.
+
+@quotation Warning
+On most ARMs, JTAG clock detection is coupled to the core clock, so
+software using a @option{wait for interrupt} operation blocks JTAG access.
+Adaptive clocking provides a partial workaround, but a more complete
+solution just avoids using that instruction with JTAG debuggers.
+@end quotation
+
If the board supports 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}.
@code{reset-deassert-post} event handler that writes a chip
register to report that JTAG debugging is being done.
+JTAG clocking constraints often change during reset, and in
+some cases target config files (rather than board config files)
+are the right places to handle some of those issues.
+For example, immediately after reset most chips run using a
+slower clock than they will use later.
+That means that after reset (and potentially, as OpenOCD
+first starts up) they must use a slower JTAG clock rate
+than they will use later.
+@xref{JTAG Speed}.
+
+@quotation Important
+When you are debugging code that runs right after chip
+reset, getting these issues right is critical.
+In particular, if you see intermittent failures when
+OpenOCD verifies the scan chain after reset,
+look at how you are setting up JTAG clocking.
+@end quotation
+
@subsection ARM Core Specific Hacks
If the chip has a DCC, enable it. If the chip is an ARM9 with some
used to specify what TCP/IP ports are used, and how GDB should be
supported.
+@anchor{Configuration Stage}
@section Configuration Stage
@cindex configuration stage
@cindex config command
After it leaves this stage, configuration commands may no
longer be issued.
+The first thing OpenOCD does after leaving the configuration
+stage is to verify that it can talk to the scan chain
+(list of TAPs) which has been configured.
+It will warn if it doesn't find TAPs it expects to find,
+or finds TAPs that aren't supposed to be there.
+You should see no errors at this point.
+If you see errors, resolve them by correcting the
+commands you used to configure the server.
+Common errors include using an initial JTAG speed that's too
+fast, and not providing the right IDCODE values for the TAPs
+on the scan chain.
+
@deffn {Config Command} init
This command terminates the configuration stage and
enters the normal command mode. This can be useful to add commands to
oscillators used, the chip, the board design, and sometimes
power management software that may be active.
-The speed used during reset can be adjusted using pre_reset
-and post_reset event handlers.
+The speed used during reset, and the scan chain verification which
+follows reset, can be adjusted using a @code{reset-start}
+target event handler.
+It can then be reconfigured to a faster speed by a
+@code{reset-init} target event handler after it reprograms those
+CPU clocks, or manually (if something else, such as a boot loader,
+sets up those clocks).
@xref{Target Events}.
+When the initial low JTAG speed is a chip characteristic, perhaps
+because of a required oscillator speed, provide such a handler
+in the target config file.
+When that speed is a function of a board-specific characteristic
+such as which speed oscillator is used, it belongs in the board
+config file instead.
+In both cases it's safest to also set the initial JTAG clock rate
+to that same slow speed, so that OpenOCD never starts up using a
+clock speed that's faster than the scan chain can support.
+
+@example
+jtag_rclk 3000
+$_TARGET.cpu configure -event reset-start @{ jtag_rclk 3000 @}
+@end example
If your system supports adaptive clocking (RTCK), configuring
JTAG to use that is probably the most robust approach.
speeds. The speed actually used won't be faster
than the speed specified.
-As a rule of thumb, if you specify a clock rate make
-sure the JTAG clock is no more than @math{1/6th CPU-Clock}.
-This is especially true for synthesized cores (ARMxxx-S).
+Chip data sheets generally include a top JTAG clock rate.
+The actual rate is often a function of a CPU core clock,
+and is normally less than that peak rate.
+For example, most ARM cores accept at most one sixth of the CPU clock.
Speed 0 (khz) selects RTCK method.
@xref{FAQ RTCK}.
@end deffn
@defun jtag_rclk fallback_speed_kHz
+@cindex adaptive clocking
@cindex RTCK
This Tcl proc (defined in @file{startup.tcl}) attempts to enable RTCK/RCLK.
If that fails (maybe the interface, board, or target doesn't
@option{combined} implies both @option{srst_pulls_trst} and
@option{trst_pulls_srst}.
+@option{srst_gates_jtag} indicates that asserting SRST gates the
+JTAG clock. This means that no communication can happen on JTAG
+while SRST is asserted.
+
The optional @var{trst_type} and @var{srst_type} parameters allow the
driver mode of each reset line to be specified. These values only affect
JTAG interfaces with support for different driver modes, like the Amontec
@deffn Command {jtag cget} dotted.name @option{-event} name
@deffnx Command {jtag configure} dotted.name @option{-event} name string
-At this writing this mechanism is used only for event handling,
-and the only two events relate to TAP enabling and disabling.
+At this writing this mechanism is used only for event handling.
+Three events are available. Two events relate to TAP enabling
+and disabling, one to post reset handling.
The @code{configure} subcommand assigns an event handler,
a TCL string which is evaluated when the event is triggered.
The @code{cget} subcommand returns that handler.
-The two possible values for an event @var{name}
-are @option{tap-disable} and @option{tap-enable}.
+The three possible values for an event @var{name} are @option{tap-disable}, @option{tap-enable} and @option{post-reset}.
So for example, when defining a TAP for a CPU connected to
a JTAG router, you should define TAP event handlers using
... jtag operations using CHIP.jrc
@}
@end example
+
+If you need some post reset action, you can do:
+
+@example
+jtag configure CHIP.cpu -event post-reset @{
+ echo "Reset done"
+ ... jtag operations to be done after reset
+@}
+@end example
@end deffn
@deffn Command {jtag tapdisable} dotted.name
which OpenOCD needs to know about.
@item @code{-work-area-backup} (@option{0}|@option{1}) -- says
-whether the work area gets backed up; by default, it doesn't.
+whether the work area gets backed up; by default,
+@emph{it is not backed up.}
When possible, use a working_area that doesn't need to be backed up,
since performing a backup slows down operations.
+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 @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
after SRST and/or TRST were activated and deactivated,
-but before reset is asserted on the tap.
+but before SRST alone is re-asserted on the tap.
@item @b{reset-assert-post}
@* Issued as part of @command{reset} processing
-when reset is asserted on the tap.
+when SRST is asserted on the tap.
@item @b{reset-deassert-pre}
@* Issued as part of @command{reset} processing
-when reset is about to be released on the tap.
-
-For some chips, this may be a good place to make sure
-the JTAG clock is slow enough to work before the PLL
-has been set up to allow faster JTAG speeds.
+when SRST is about to be released on the tap.
@item @b{reset-deassert-post}
@* Issued as part of @command{reset} processing
-when reset has been released on the tap.
+when SRST has been released on the tap.
@item @b{reset-end}
@* Issued as the final step in @command{reset} processing.
@ignore
This is where you would configure PLLs and clocking, set up DRAM so
you can download programs that don't fit in on-chip SRAM, set up pin
multiplexing, and so on.
+(You may be able to switch to a fast JTAG clock rate here, after
+the target clocks are fully set up.)
@item @b{reset-start}
@* Issued as part of @command{reset} processing
before either SRST or TRST are activated.
+
+This is the most robust place to switch to a low JTAG clock rate, if
+SRST disables PLLs needed to use a fast clock.
@ignore
@item @b{reset-wait-pos}
@* Currently not used
@deffn {Flash Driver} lpc2000
Most members of the LPC1700 and LPC2000 microcontroller families from NXP
-include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
+include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
+
+@quotation Note
+There are LPC2000 devices which are not supported by the @var{lpc2000}
+driver:
+The LPC2888 is supported by the @var{lpc288x} driver.
+The LPC29xx family is supported by the @var{lpc2900} driver.
+@end quotation
+
The @var{lpc2000} driver defines two mandatory and one optional parameters,
which must appear in the following order:
@end example
@end deffn
+@deffn {Flash Driver} lpc2900
+This driver supports the LPC29xx ARM968E based microcontroller family
+from NXP.
+
+The predefined parameters @var{base}, @var{size}, @var{chip_width} and
+@var{bus_width} of the @code{flash bank} command are ignored. Flash size and
+sector layout are auto-configured by the driver.
+The driver has one additional mandatory parameter: The CPU clock rate
+(in kHz) at the time the flash operations will take place. Most of the time this
+will not be the crystal frequency, but a higher PLL frequency. The
+@code{reset-init} event handler in the board script is usually the place where
+you start the PLL.
+
+The driver rejects flashless devices (currently the LPC2930).
+
+The EEPROM in LPC2900 devices is not mapped directly into the address space.
+It must be handled much more like NAND flash memory, and will therefore be
+handled by a separate @code{lpc2900_eeprom} driver (not yet available).
+
+Sector protection in terms of the LPC2900 is handled transparently. Every time a
+sector needs to be erased or programmed, it is automatically unprotected.
+What is shown as protection status in the @code{flash info} command, is
+actually the LPC2900 @emph{sector security}. This is a mechanism to prevent a
+sector from ever being erased or programmed again. As this is an irreversible
+mechanism, it is handled by a special command (@code{lpc2900 secure_sector}),
+and not by the standard @code{flash protect} command.
+
+Example for a 125 MHz clock frequency:
+@example
+flash bank lpc2900 0 0 0 0 $_TARGETNAME 125000
+@end example
+
+Some @code{lpc2900}-specific commands are defined. In the following command list,
+the @var{bank} parameter is the bank number as obtained by the
+@code{flash banks} command.
+
+@deffn Command {lpc2900 signature} bank
+Calculates a 128-bit hash value, the @emph{signature}, from the whole flash
+content. This is a hardware feature of the flash block, hence the calculation is
+very fast. You may use this to verify the content of a programmed device against
+a known signature.
+Example:
+@example
+lpc2900 signature 0
+ signature: 0x5f40cdc8:0xc64e592e:0x10490f89:0x32a0f317
+@end example
+@end deffn
+
+@deffn Command {lpc2900 read_custom} bank filename
+Reads the 912 bytes of customer information from the flash index sector, and
+saves it to a file in binary format.
+Example:
+@example
+lpc2900 read_custom 0 /path_to/customer_info.bin
+@end example
+@end deffn
+
+The index sector of the flash is a @emph{write-only} sector. It cannot be
+erased! In order to guard against unintentional write access, all following
+commands need to be preceeded by a successful call to the @code{password}
+command:
+
+@deffn Command {lpc2900 password} bank password
+You need to use this command right before each of the following commands:
+@code{lpc2900 write_custom}, @code{lpc2900 secure_sector},
+@code{lpc2900 secure_jtag}.
+
+The password string is fixed to "I_know_what_I_am_doing".
+Example:
+@example
+lpc2900 password 0 I_know_what_I_am_doing
+ Potentially dangerous operation allowed in next command!
+@end example
+@end deffn
+
+@deffn Command {lpc2900 write_custom} bank filename type
+Writes the content of the file into the customer info space of the flash index
+sector. The filetype can be specified with the @var{type} field. Possible values
+for @var{type} are: @var{bin} (binary), @var{ihex} (Intel hex format),
+@var{elf} (ELF binary) or @var{s19} (Motorola S-records). The file must
+contain a single section, and the contained data length must be exactly
+912 bytes.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Example:
+@example
+lpc2900 write_custom 0 /path_to/customer_info.bin bin
+@end example
+@end deffn
+
+@deffn Command {lpc2900 secure_sector} bank first last
+Secures the sector range from @var{first} to @var{last} (including) against
+further program and erase operations. The sector security will be effective
+after the next power cycle.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Secured sectors appear as @emph{protected} in the @code{flash info} command.
+Example:
+@example
+lpc2900 secure_sector 0 1 1
+flash info 0
+ #0 : lpc2900 at 0x20000000, size 0x000c0000, (...)
+ # 0: 0x00000000 (0x2000 8kB) not protected
+ # 1: 0x00002000 (0x2000 8kB) protected
+ # 2: 0x00004000 (0x2000 8kB) not protected
+@end example
+@end deffn
+
+@deffn Command {lpc2900 secure_jtag} bank
+Irreversibly disable the JTAG port. The new JTAG security setting will be
+effective after the next power cycle.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Examples:
+@example
+lpc2900 secure_jtag 0
+@end example
+@end deffn
+@end deffn
+
@deffn {Flash Driver} ocl
@emph{No idea what this is, other than using some arm7/arm9 core.}
@end deffn
@deffn Command {nand list}
-Prints a one-line summary of each device declared
+Prints a summary of each device declared
using @command{nand device}, numbered from zero.
Note that un-probed devices show no details.
+@example
+> nand list
+#0: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
+ blocksize: 131072, blocks: 8192
+#1: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
+ blocksize: 131072, blocks: 8192
+>
+@end example
@end deffn
@deffn Command {nand probe} num
@end itemize
@end deffn
-@deffn Command {nand erase} num offset length
+@deffn Command {nand erase} num [offset length]
@cindex NAND erasing
@cindex NAND programming
Erases blocks on the specified NAND device, starting at the
specified @var{offset} and continuing for @var{length} bytes.
Both of those values must be exact multiples of the device's
block size, and the region they specify must fit entirely in the chip.
+If those parameters are not specified,
+the whole NAND chip will be erased.
The @var{num} parameter is the value shown by @command{nand list}.
@b{NOTE:} This command will try to erase bad blocks, when told
chips from Texas Instruments.
It takes three extra parameters:
address of the NAND chip;
-hardware ECC mode to use (hwecc1, hwecc4, hwecc4_infix);
+hardware ECC mode to use (@option{hwecc1},
+@option{hwecc4}, @option{hwecc4_infix});
address of the AEMIF controller on this processor.
@example
nand device davinci dm355.arm 0x02000000 hwecc4 0x01e10000
The target specific "dangerous" optimisation tweaking options may come and go
as more robust and user friendly ways are found to ensure maximum throughput
-and robustness with a minimum of configuration.
+and robustness with a minimum of configuration.
Typically the "fast enable" is specified first on the command line:
or 5 seconds if there is no parameter, for the target to halt
(and enter debug mode).
Using 0 as the @var{ms} parameter prevents OpenOCD from waiting.
+
+@quotation Warning
+On ARM cores, software using the @emph{wait for interrupt} operation
+often blocks the JTAG access needed by a @command{halt} command.
+This is because that operation also puts the core into a low
+power mode by gating the core clock;
+but the core clock is needed to detect JTAG clock transitions.
+
+One partial workaround uses adaptive clocking: when the core is
+interrupted the operation completes, then JTAG clocks are accepted
+at least until the interrupt handler completes.
+However, this workaround is often unusable since the processor, board,
+and JTAG adapter must all support adaptive JTAG clocking.
+Also, it can't work until an interrupt is issued.
+
+A more complete workaround is to not use that operation while you
+work with a JTAG debugger.
+Tasking environments generaly have idle loops where the body is the
+@emph{wait for interrupt} operation.
+(On older cores, it is a coprocessor action;
+newer cores have a @option{wfi} instruction.)
+Such loops can just remove that operation, at the cost of higher
+power consumption (because the CPU is needlessly clocked).
+@end quotation
+
@end deffn
@deffn Command resume [address]
@deffn Command {armv4_5 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.
+register value.
@end deffn
@subsection ARM7 and ARM9 specific commands
@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
instead of breakpoints. This should be
-safe for all but ARM7TDMI--S cores (like Philips LPC).
+safe for all but ARM7TDMI--S cores (like Philips LPC).
This feature is enabled by default on most ARM9 cores,
including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
Enable or disable memory writes and reads that don't check completion of
the operation. This provides a huge speed increase, especially with USB JTAG
cables (FT2232), but might be unsafe if used with targets running at very low
-speeds, like the 32kHz startup clock of an AT91RM9200.
+speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
and display the result.
@end deffn
-@subsection ARM9TDMI specific commands
-@cindex ARM9TDMI
+@subsection ARM9 specific commands
+@cindex ARM9
-Many ARM9-family CPUs are built around ARM9TDMI integer cores,
-or processors resembling ARM9TDMI, and can use these commands.
+ARM9-family cores are built around ARM9TDMI or ARM9E (including ARM9EJS)
+integer processors.
Such cores include the ARM920T, ARM926EJ-S, and ARM966.
+For historical reasons, one command shared by these cores starts
+with the @command{arm9tdmi} prefix.
+This is true even for ARM9E based processors, which implement the
+ARMv5TE architecture instead of ARMv4T.
+
@c 9-june-2009: tried this on arm920t, it didn't work.
@c no-params always lists nothing caught, and that's how it acts.
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 mcr} p1 p2 p3 p4 p5
-Read coprocessor register
+@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]
If @var{value} is defined, first assigns that.
@end deffn
-@deffn Command {arm11 mrc} p1 p2 p3 p4 p5 value
-Write coprocessor register
+@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 no_increment} [value]
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
gdb_memory_map disable
@end example
For this to function correctly a valid flash configuration must also be set
-in OpenOCD. For faster performance you should also configure a valid
+in OpenOCD. For faster performance you should also configure a valid
working area.
Informing GDB of the memory map of the target will enable GDB to protect any
information as an argument to each proc.
There are three main types of return values: single value, name value
-pair list and lists.
+pair list and lists.
Name value pair. The proc 'foo' below returns a name/value pair
-list.
+list.
@verbatim
puts "Name: $name, Value: $value"
}
@end verbatim
-
+
Lists returned must be relatively small. Otherwise a range
should be passed in to the proc in question.
variables. JimTCL, as implemented in OpenOCD creates $HostOS which
holds one of the following values:
-@itemize @bullet
+@itemize @bullet
@item @b{winxx} Built using Microsoft Visual Studio
@item @b{linux} Linux is the underlying operating sytem
@item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
that ``deep sleeps'' at 32kHz between every keystroke. It can be
painful.
-@b{Solution #1 - A special circuit}
+@b{Solution #1 - A special circuit}
In order to make use of this, your JTAG dongle must support the RTCK
feature. Not all dongles support this - keep reading!
In most simple terms: Often the JTAG clock must be 1/10 to 1/12 of
the target clock speed. But what that ``magic division'' is varies
-depending on the chips on your board. @b{ARM rule of thumb} Most ARM
-based systems require an 8:1 division. @b{Xilinx rule of thumb} is
-1/12 the clock speed.
+depending on the chips on your board.
+@b{ARM rule of thumb} Most ARM based systems require an 6:1 division;
+ARM11 cores use an 8:1 division.
+@b{Xilinx rule of thumb} is 1/12 the clock speed.
Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
sleep''. If you are careful - 98% of your problems can be debugged
this way.
+Note that on ARM you may need to avoid using the @emph{wait for interrupt}
+operation in your idle loops even if you don't otherwise change the CPU
+clock rate.
+That operation gates the CPU clock, and thus the JTAG clock; which
+prevents JTAG access. One consequence is not being able to @command{halt}
+cores which are executing that @emph{wait for interrupt} operation.
+
To set the JTAG frequency use the command:
@example
- # Example: 1.234MHz
- jtag_khz 1234
+# Example: 1.234MHz
+jtag_khz 1234
@end example
@item @b{Win32 Pathnames} Why don't backslashes work in Windows paths?
OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @}
-around Windows filenames.
+around Windows filenames.
@example
> echo \a
@item @b{Data Aborts} When debugging with OpenOCD and GDB (plain GDB, Insight, or Eclipse),
I get lots of "Error: arm7_9_common.c:1771 arm7_9_read_memory():
-memory read caused data abort".
+memory read caused data abort".
The errors are non-fatal, and are the result of GDB trying to trace stack frames
beyond the last valid frame. It might be possible to prevent this by setting up
@b{Also note:} If you have a multi-threaded operating system, they
often do not @b{in the intrest of saving memory} waste these few
-bytes. Painful...
+bytes. Painful...
@item @b{JTAG Reset Config} I get the following message in the OpenOCD console (or log file):
@node Tcl Crash Course
@chapter Tcl Crash Course
-@cindex Tcl
+@cindex Tcl
Not everyone knows Tcl - this is not intended to be a replacement for
learning Tcl, the intent of this chapter is to give you some idea of
Commands are executed like this:
-@enumerate
+@enumerate
@item Parse the next line into (argc) and (argv[]).
@item Look up (argv[0]) in a table and call its function.
@item Repeat until End Of File.
@enumerate
@item The SET command creates 2 variables, X and Y.
@item The double [nested] EXPR command performs math
-@* The EXPR command produces numerical result as a string.
+@* The EXPR command produces numerical result as a string.
@* Refer to Rule #1
@item The format command is executed, producing a single string
@* Refer to Rule #1.
#4 DANGER DANGER DANGER
$_TARGETNAME configure -event foo "puts \"Time: [date]\""
@end example
-@enumerate
+@enumerate
@item The $_TARGETNAME is an OpenOCD variable convention.
@*@b{$_TARGETNAME} represents the last target created, the value changes
each time a new target is created. Remember the parsing rules. When
OpenOCD comes with a target configuration script library. These scripts can be
used as-is or serve as a starting point.
-The target library is published together with the OpenOCD executable and
+The target library is published together with the OpenOCD executable and
the path to the target library is in the OpenOCD script search path.
-Similarly there are example scripts for configuring the JTAG interface.
+Similarly there are example scripts for configuring the JTAG interface.
The command line below uses the example parport configuration script
that ship with OpenOCD, then configures the str710.cfg target and
Code Review / openocd.git / blobdiff