@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
Discuss and submit patches to this list.
-The @file{PATCHES} file contains basic information about how
+The @file{PATCHES.txt} file contains basic information about how
to prepare patches.
@itemize @bullet
+@item @b{Watchdog Timers}...
+Watchog timers are typically used to automatically reset systems if
+some application task doesn't periodically reset the timer. (The
+assumption is that the system has locked up if the task can't run.)
+When a JTAG debugger halts the system, that task won't be able to run
+and reset the timer ... potentially causing resets in the middle of
+your debug sessions.
+
+It's rarely a good idea to disable such watchdogs, since their usage
+needs to be debugged just like all other parts of your firmware.
+That might however be your only option.
+
+Look instead for chip-specific ways to stop the watchdog from counting
+while the system is in a debug halt state. It may be simplest to set
+that non-counting mode in your debugger startup scripts. You may however
+need a different approach when, for example, a motor could be physically
+damaged by firmware remaining inactive in a debug halt state. That might
+involve a type of firmware mode where that "non-counting" mode is disabled
+at the beginning then re-enabled at the end; a watchdog reset might fire
+and complicate the debug session, but hardware (or people) would be
+protected.@footnote{Note that many systems support a "monitor mode" debug
+that is a somewhat cleaner way to address such issues. You can think of
+it as only halting part of the system, maybe just one task,
+instead of the whole thing.
+At this writing, January 2010, OpenOCD based debugging does not support
+monitor mode debug, only "halt mode" debug.}
+
@item @b{ARM Semihosting}...
@cindex ARM semihosting
When linked with a special runtime library provided with many
You may want to @emph{disable that instruction} in source code,
or otherwise prevent using that state,
-to ensure you can get JTAG access at any time.
+to ensure you can get JTAG access at any time.@footnote{As a more
+polite alternative, some processors have special debug-oriented
+registers which can be used to change various features including
+how the low power states are clocked while debugging.
+The STM32 DBGMCU_CR register is an example; at the cost of extra
+power consumption, JTAG can be used during low power states.}
For example, the OpenOCD @command{halt} command may not
work for an idle processor otherwise.
If you disable all access through TCP/IP, you will need to
use the command line @option{-pipe} option.
-@deffn {Command} gdb_port (number)
+@deffn {Command} gdb_port [number]
@cindex GDB server
Specify or query the first port used for incoming GDB connections.
The GDB port for the
first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
-When specified as zero, this port is not activated.
+When specified as zero, GDB remote access ports are not activated.
@end deffn
-@deffn {Command} tcl_port (number)
+@deffn {Command} tcl_port [number]
Specify or query the port used for a simplified RPC
connection that can be used by clients to issue TCL commands and get the
output from the Tcl engine.
When specified as zero, this port is not activated.
@end deffn
-@deffn {Command} telnet_port (number)
+@deffn {Command} telnet_port [number]
Specify or query the
port on which to listen for incoming telnet connections.
This port is intended for interaction with one human through TCL commands.
Gateworks GW16012 JTAG programmer.
This has one driver-specific command:
-@deffn {Config Command} {parport_port} number
-Specifies either the address of the I/O port (default: 0x378 for LPT1) or
-the number of the @file{/dev/parport} device.
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
@end deffn
@end deffn
before initializing the JTAG scan chain:
@deffn {Config Command} {parport_cable} name
-The layout of the parallel port cable used to connect to the target.
+Set the layout of the parallel port cable used to connect to the target.
+This is a write-once setting.
Currently valid cable @var{name} values include:
@itemize @minus
@end itemize
@end deffn
-@deffn {Config Command} {parport_port} number
-Either the address of the I/O port (default: 0x378 for LPT1) or the number of
-the @file{/dev/parport} device
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
When using PPDEV to access the parallel port, use the number of the parallel port:
@option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
@end quotation
@end deffn
-@deffn {Config Command} {parport_write_on_exit} (on|off)
+@deffn {Config Command} {parport_write_on_exit} (@option{on}|@option{off})
This will configure the parallel driver to write a known
-cable-specific value to the parallel interface on exiting OpenOCD
+cable-specific value to the parallel interface on exiting OpenOCD.
@end deffn
For example, the interface configuration file for a
-classic ``Wiggler'' cable might look something like this:
+classic ``Wiggler'' cable on LPT2 might look something like this:
@example
interface parport
-parport_port 0xc8b8
+parport_port 0x278
parport_cable wiggler
@end example
@end deffn
@deffn {Interface Driver} {presto}
ASIX PRESTO USB JTAG programmer.
-@c command: presto_serial str
-@c sets serial number
+@deffn {Config Command} {presto_serial} serial_string
+Configures the USB serial number of the Presto device to use.
+@end deffn
@end deffn
@deffn {Interface Driver} {rlink}
The default behaviour if no option given is @option{separate},
indicating everything behaves normally.
@option{srst_pulls_trst} states that the
-test logic is reset together with the reset of the system (e.g. Philips
+test logic is reset together with the reset of the system (e.g. NXP
LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
the system is reset together with the test logic (only hypothetical, I
haven't seen hardware with such a bug, and can be worked around).
@itemize @bullet
@item @var{name} ... may be used to reference the flash bank
-in other flash commands.
+in other flash commands. A number is also available.
@item @var{driver} ... identifies the controller driver
associated with the flash bank being declared.
This is usually @code{cfi} for external flash, or else
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash erase_address} address length
+@deffn Command {flash erase_address} [@option{pad}] address length
Erase sectors starting at @var{address} for @var{length} bytes.
+Unless @option{pad} is specified, @math{address} must begin a
+flash sector, and @math{address + length - 1} must end a sector.
+Specifying @option{pad} erases extra data at the beginning and/or
+end of the specified region, as needed to erase only full sectors.
The flash bank to use is inferred from the @var{address}, and
the specified length must stay within that bank.
As a special case, when @var{length} is zero and @var{address} is
@command{flash erase_sector} or @command{flash erase_address} commands.
@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
-Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+Set or clear a ``General Purpose Non-Volatile Memory'' (GPNVM)
bit for the processor. Each processor has a number of such bits,
used for controlling features such as brownout detection (so they
are not truly general purpose).
plus some additional configuration that's done after
OpenOCD has initialized.
-@deffn {Config Command} {nand device} name controller target [configparams...]
+@deffn {Config Command} {nand device} name driver target [configparams...]
Declares a NAND device, which can be read and written to
after it has been configured through @command{nand probe}.
In OpenOCD, devices are single chips; this is unlike some
@itemize @bullet
@item @var{name} ... may be used to reference the NAND bank
-in other commands.
-@item @var{controller} ... identifies the controller driver
+in most other NAND commands. A number is also available.
+@item @var{driver} ... identifies the NAND controller driver
associated with the NAND device being declared.
@xref{NAND Driver List}.
@item @var{target} ... names the target used when issuing
@deffnx {NAND Driver} s3c2412
@deffnx {NAND Driver} s3c2440
@deffnx {NAND Driver} s3c2443
-These S3C24xx family controllers don't have any special
+@deffnx {NAND Driver} s3c6400
+These S3C family controllers don't have any special
@command{nand device} options, and don't define any
specialized commands.
At this writing, their drivers don't include @code{write_page}
They are available in addition to the ARM commands,
and any other core-specific commands that may be available.
-@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).
+@deffn Command {arm7_9 dbgrq} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of the
+the EmbeddedIce DBGRQ signal to force entry into debug mode,
+instead of breakpoints.
+If a boolean parameter is provided, first assigns that flag.
+
+This should be
+safe for all but ARM7TDMI-S cores (like NXP LPC).
This feature is enabled by default on most ARM9 cores,
including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
-@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
+@deffn Command {arm7_9 dcc_downloads} [@option{enable}|@option{disable}]
@cindex DCC
-Control the use of the debug communications channel (DCC) to write larger (>128 byte)
-amounts of memory. DCC downloads offer a huge speed increase, but might be
+Displays the value of the flag controlling use of the debug communications
+channel (DCC) to write larger (>128 byte) amounts of memory.
+If a boolean parameter is provided, first assigns that flag.
+
+DCC downloads offer a huge speed increase, but might be
unsafe, especially with targets running at very low speeds. This command was introduced
with OpenOCD rev. 60, and requires a few bytes of working area.
@end deffn
@anchor{arm7_9 fast_memory_access}
-@deffn Command {arm7_9 fast_memory_access} (@option{enable}|@option{disable})
-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
+@deffn Command {arm7_9 fast_memory_access} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of memory writes and reads
+that don't check completion of the operation.
+If a boolean parameter is provided, first assigns that flag.
+
+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.
@end deffn
based on the ARM7TDMI-S integer core.
They are available in addition to the ARM and ARM7/ARM9 commands.
-@deffn Command {arm720t cp15} regnum [value]
-Display cp15 register @var{regnum};
+@deffn Command {arm720t cp15} opcode [value]
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Display cp15 register returned by the ARM instruction @var{opcode};
else if a @var{value} is provided, that value is written to that register.
+The @var{opcode} should be the value of either an MRC or MCR instruction.
@end deffn
@subsection ARM9 specific commands
@deffn Command {arm920t cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
+This uses "physical access" and the register number is as
+shown in bits 38..33 of table 9-9 in the ARM920T TRM.
+(Not all registers can be written.)
@end deffn
@deffn Command {arm920t cp15i} opcode [value [address]]
-Interpreted access using cp15 @var{opcode}.
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Interpreted access using ARM instruction @var{opcode}, which should
+be the value of either an MRC or MCR instruction
+(as shown tables 9-11, 9-12, and 9-13 in the ARM920T TRM).
If no @var{value} is provided, the result is displayed.
Else if that value is written using the specified @var{address},
-or using zero if no other address is not provided.
+or using zero if no other address is provided.
@end deffn
@deffn Command {arm920t read_cache} filename
@deffn Command {arm966e cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
+The six bit @var{regnum} values are bits 37..32 from table 7-2 of the
+ARM966E-S TRM.
+There is no current control over bits 31..30 from that table,
+as required for BIST support.
@end deffn
@subsection XScale specific commands
Changes the address used for the specified target's debug handler.
@end deffn
-@deffn Command {xscale dcache} (@option{enable}|@option{disable})
+@deffn Command {xscale dcache} [@option{enable}|@option{disable}]
Enables or disable the CPU's data cache.
@end deffn
Dumps the raw contents of the trace buffer to @file{filename}.
@end deffn
-@deffn Command {xscale icache} (@option{enable}|@option{disable})
+@deffn Command {xscale icache} [@option{enable}|@option{disable}]
Enables or disable the CPU's instruction cache.
@end deffn
-@deffn Command {xscale mmu} (@option{enable}|@option{disable})
+@deffn Command {xscale mmu} [@option{enable}|@option{disable}]
Enables or disable the CPU's memory management unit.
@end deffn
-@deffn Command {xscale trace_buffer} (@option{enable}|@option{disable}) [@option{fill} [n] | @option{wrap}]
-Enables or disables the trace buffer,
-and controls how it is emptied.
+@deffn Command {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
+Displays the trace buffer status, after optionally
+enabling or disabling the trace buffer
+and modifying how it is emptied.
@end deffn
@deffn Command {xscale trace_image} filename [offset [type]]
@end deffn
@anchor{xscale vector_table}
-@deffn Command {xscale vector_table} [<low|high> <index> <value>]
+@deffn Command {xscale vector_table} [(@option{low}|@option{high}) index value]
@cindex vector_table
Set an entry in the mini-IC vector table. There are two tables: one for
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 memwrite burst} [value]
+@deffn Command {arm11 memwrite burst} [@option{enable}|@option{disable}]
Displays the value of the memwrite burst-enable flag,
-which is enabled by default. Burst writes are only used
-for memory writes larger than 1 word. Single word writes
-are likely to be from reset init scripts and those writes
-are often to non-memory locations which could easily have
-many wait states, which could easily break burst writes.
-If @var{value} is defined, first assigns that.
+which is enabled by default.
+If a boolean parameter is provided, first assigns that flag.
+Burst writes are only used for memory writes larger than 1 word.
+They improve performance by assuming that the CPU has read each data
+word over JTAG and completed its write before the next word arrives,
+instead of polling for a status flag to verify that completion.
+This is usually safe, because JTAG runs much slower than the CPU.
@end deffn
-@deffn Command {arm11 memwrite error_fatal} [value]
+@deffn Command {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
Displays the value of the memwrite error_fatal flag,
which is enabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that flag.
+When set, certain memory write errors cause earlier transfer termination.
@end deffn
-@deffn Command {arm11 step_irq_enable} [value]
+@deffn Command {arm11 step_irq_enable} [@option{enable}|@option{disable}]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
they are disabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that.
@end deffn
@deffn Command {arm11 vcr} [value]
included on Cortex-M3 and Cortex-A8 systems.
They are available in addition to other core-specific commands that may be available.
-@deffn Command {dap info} [num]
-Displays dap info for ap @var{num}, defaulting to the currently selected AP.
+@deffn Command {dap apid} [num]
+Displays ID register from AP @var{num},
+defaulting to the currently selected AP.
@end deffn
@deffn Command {dap apsel} [num]
Select AP @var{num}, defaulting to 0.
@end deffn
-@deffn Command {dap apid} [num]
-Displays id register from AP @var{num},
+@deffn Command {dap baseaddr} [num]
+Displays debug base address from MEM-AP @var{num},
defaulting to the currently selected AP.
@end deffn
-@deffn Command {dap baseaddr} [num]
-Displays debug base address from AP @var{num},
+@deffn Command {dap info} [num]
+Displays the ROM table for MEM-AP @var{num},
defaulting to the currently selected AP.
@end deffn
@deffn Command {dap memaccess} [value]
-Displays the number of extra tck for mem-ap memory bus access [0-255].
+Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
+memory bus access [0-255], giving additional time to respond to reads.
If @var{value} is defined, first assigns that.
@end deffn
Setting up GDB to work with OpenOCD can involve several components:
@itemize
-@item OpenOCD itself may need to be configured. @xref{GDB Configuration}.
-@item GDB itself may need configuration, as shown in this chapter.
+@item The OpenOCD server support for GDB may need to be configured.
+@xref{GDB Configuration}.
+@item GDB's support for OpenOCD may need configuration,
+as shown in this chapter.
@item If you have a GUI environment like Eclipse,
that also will probably need to be configured.
@end itemize
only work for code running from flash memory. Most other ARM systems
do not have such restrictions.
+Another example of useful GDB configuration came from a user who
+found that single stepping his Cortex-M3 didn't work well with IRQs
+and an RTOS until he told GDB to disable the IRQs while stepping:
+
+@example
+define hook-step
+mon cortex_m3 maskisr on
+end
+define hookpost-step
+mon cortex_m3 maskisr off
+end
+@end example
+
+Rather than typing such commands interactively, you may prefer to
+save them in a file and have GDB execute them as it starts, perhaps
+using a @file{.gdbinit} in your project directory or starting GDB
+using @command{gdb -x filename}.
+
@section Programming using GDB
@cindex Programming using GDB
holds one of the following values:
@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.
@item @b{cygwin} Running under Cygwin
+@item @b{darwin} Darwin (Mac-OS) is the underlying operating sytem.
+@item @b{freebsd} Running under FreeBSD
+@item @b{linux} Linux is the underlying operating sytem
@item @b{mingw32} Running under MingW32
+@item @b{winxx} Built using Microsoft Visual Studio
@item @b{other} Unknown, none of the above.
@end itemize
In digital circuit design it is often refered to as ``clock
synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
-operating at some speed, your target is operating at another. The two
-clocks are not synchronised, they are ``asynchronous''
+operating at some speed, your CPU target is operating at another.
+The two clocks are not synchronised, they are ``asynchronous''
-In order for the two to work together they must be synchronised. Otherwise
-the two systems will get out of sync with each other and nothing will
-work. There are 2 basic options:
+In order for the two to work together they must be synchronised
+well enough to work; JTAG can't go ten times faster than the CPU,
+for example. There are 2 basic options:
@enumerate
@item
-Use a special circuit.
+Use a special "adaptive clocking" circuit to change the JTAG
+clock rate to match what the CPU currently supports.
@item
-One clock must be some multiple slower than the other.
+The JTAG clock must be fixed at some speed that's enough slower than
+the CPU clock that all TMS and TDI transitions can be detected.
@end enumerate
@b{Does this really matter?} For some chips and some situations, this
-is a non-issue (i.e.: A 500MHz ARM926) but for others - for example some
-Atmel SAM7 and SAM9 chips start operation from reset at 32kHz -
-program/enable the oscillators and eventually the main clock. It is in
-those critical times you must slow the JTAG clock to sometimes 1 to
-4kHz.
-
-Imagine debugging a 500MHz ARM926 hand held battery powered device
-that ``deep sleeps'' at 32kHz between every keystroke. It can be
-painful.
+is a non-issue, like a 500MHz ARM926 with a 5 MHz JTAG link;
+the CPU has no difficulty keeping up with JTAG.
+Startup sequences are often problematic though, as are other
+situations where the CPU clock rate changes (perhaps to save
+power).
+
+For example, Atmel AT91SAM chips start operation from reset with
+a 32kHz system clock. Boot firmware may activate the main oscillator
+and PLL before switching to a faster clock (perhaps that 500 MHz
+ARM926 scenario).
+If you're using JTAG to debug that startup sequence, you must slow
+the JTAG clock to sometimes 1 to 4kHz. After startup completes,
+JTAG can use a faster clock.
+
+Consider also debugging a 500MHz ARM926 hand held battery powered
+device that enters a low power ``deep sleep'' mode, at 32kHz CPU
+clock, between keystrokes unless it has work to do. When would
+that 5 MHz JTAG clock be usable?
@b{Solution #1 - A special circuit}
-In order to make use of this, your JTAG dongle must support the RTCK
+In order to make use of this,
+both your CPU and your JTAG dongle must support the RTCK
feature. Not all dongles support this - keep reading!
-The RTCK signal often found in some ARM chips is used to help with
+The RTCK ("Return TCK") signal in some ARM chips is used to help with
this problem. ARM has a good description of the problem described at
this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked
28/nov/2008]. Link title: ``How does the JTAG synchronisation logic
Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
You can still debug the 'low power' situations - you just need to
-manually adjust the clock speed at every step. While painful and
-tedious, it is not always practical.
+either use a fixed and very slow JTAG clock rate ... or else
+manually adjust the clock speed at every step. (Adjusting is painful
+and tedious, and is not always practical.)
It is however easy to ``code your way around it'' - i.e.: Cheat a little,
have a special debug mode in your application that does a ``high power
Code Review / openocd.git / blobdiff