That's because there is no external memory (flash, DDR RAM), and
the board differences are encapsulated by application code.
+@item Maybe you don't know yet what your board looks like to JTAG.
+Once you know the @file{interface.cfg} file to use, you may
+need help from OpenOCD to discover what's on the board.
+Once you find the TAPs, you can just search for appropriate
+configuration files ... or write your own, from the bottom up.
+@xref{Autoprobing}.
+
@item You can often reuse some standard config files but
need to write a few new ones, probably a @file{board.cfg} file.
You will be using commands described later in this User's Guide,
that the @code{reset-init} event handler does.
@item
-Likewise, the @command{arm9tdmi vector_catch} command (or
+Likewise, the @command{arm9 vector_catch} command (or
@cindex vector_catch
its siblings @command{xscale vector_catch}
and @command{cortex_m3 vector_catch}) can be a timesaver
After it leaves this stage, configuration commands may no
longer be issued.
+@section Entering the Run Stage
+
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.
fast, and not providing the right IDCODE values for the TAPs
on the scan chain.
+Once OpenOCD has entered the run stage, a number of commands
+become available.
+A number of these relate to the debug targets you may have declared.
+For example, the @command{mww} command will not be available until
+a target has been successfuly instantiated.
+If you want to use those commands, you may need to force
+entry to the run stage.
+
@deffn {Config Command} init
This command terminates the configuration stage and
-enters the normal command mode. This can be useful to add commands to
-the startup scripts and commands such as resetting the target,
+enters the run stage. This helps when you need to have
+the startup scripts manage tasks such as resetting the target,
programming flash, etc. To reset the CPU upon startup, add "init" and
"reset" at the end of the config script or at the end of the OpenOCD
command line using the @option{-c} command line switch.
scan chain.
If that fails, it tries again, using a harder reset
from the overridable procedure @command{init_reset}.
+
+Implementations must have verified the JTAG scan chain before
+they return.
+This is done by calling @command{jtag arp_init}
+(or @command{jtag arp_init-reset}).
@end deffn
@anchor{TCP/IP Ports}
@end quotation
@end deffn
+@anchor{Autoprobing}
+@section Autoprobing
+@cindex autoprobe
+@cindex JTAG autoprobe
+
+TAP configuration is the first thing that needs to be done
+after interface and reset configuration. Sometimes it's
+hard finding out what TAPs exist, or how they are identified.
+Vendor documentation is not always easy to find and use.
+
+To help you get past such problems, OpenOCD has a limited
+@emph{autoprobing} ability to look at the scan chain, doing
+a @dfn{blind interrogation} and then reporting the TAPs it finds.
+To use this mechanism, start the OpenOCD server with only data
+that configures your JTAG interface, and arranges to come up
+with a slow clock (many devices don't support fast JTAG clocks
+right when they come out of reset).
+
+For example, your @file{openocd.cfg} file might have:
+
+@example
+source [find interface/olimex-arm-usb-tiny-h.cfg]
+reset_config trst_and_srst
+jtag_rclk 8
+@end example
+
+When you start the server without any TAPs configured, it will
+attempt to autoconfigure the TAPs. There are two parts to this:
+
+@enumerate
+@item @emph{TAP discovery} ...
+After a JTAG reset (sometimes a system reset may be needed too),
+each TAP's data registers will hold the contents of either the
+IDCODE or BYPASS register.
+If JTAG communication is working, OpenOCD will see each TAP,
+and report what @option{-expected-id} to use with it.
+@item @emph{IR Length discovery} ...
+Unfortunately JTAG does not provide a reliable way to find out
+the value of the @option{-irlen} parameter to use with a TAP
+that is discovered.
+If OpenOCD can discover the length of a TAP's instruction
+register, it will report it.
+Otherwise you may need to consult vendor documentation, such
+as chip data sheets or BSDL files.
+@end enumerate
+
+In many cases your board will have a simple scan chain with just
+a single device. Here's what OpenOCD reported with one board
+that's a bit more complex:
+
+@example
+clock speed 8 kHz
+There are no enabled taps. AUTO PROBING MIGHT NOT WORK!!
+AUTO auto0.tap - use "jtag newtap auto0 tap -expected-id 0x2b900f0f ..."
+AUTO auto1.tap - use "jtag newtap auto1 tap -expected-id 0x07926001 ..."
+AUTO auto2.tap - use "jtag newtap auto2 tap -expected-id 0x0b73b02f ..."
+AUTO auto0.tap - use "... -irlen 4"
+AUTO auto1.tap - use "... -irlen 4"
+AUTO auto2.tap - use "... -irlen 6"
+no gdb ports allocated as no target has been specified
+@end example
+
+Given that information, you should be able to either find some existing
+config files to use, or create your own. If you create your own, you
+would configure from the bottom up: first a @file{target.cfg} file
+with these TAPs, any targets associated with them, and any on-chip
+resources; then a @file{board.cfg} with off-chip resources, clocking,
+and so forth.
+
@node CPU Configuration
@chapter CPU Configuration
@cindex GDB target
@itemize @bullet
@item @code{arm11} -- this is a generation of ARMv6 cores
-@item @code{arm720t} -- this is an ARMv4 core
+@item @code{arm720t} -- this is an ARMv4 core with an MMU
@item @code{arm7tdmi} -- this is an ARMv4 core
-@item @code{arm920t} -- this is an ARMv5 core
-@item @code{arm926ejs} -- this is an ARMv5 core
+@item @code{arm920t} -- this is an ARMv5 core with an MMU
+@item @code{arm926ejs} -- this is an ARMv5 core with an MMU
@item @code{arm966e} -- this is an ARMv5 core
@item @code{arm9tdmi} -- this is an ARMv4 core
@item @code{avr} -- implements Atmel's 8-bit AVR instruction set.
(Support for this is preliminary and incomplete.)
-@item @code{cortex_a8} -- this is an ARMv7 core
+@item @code{cortex_a8} -- this is an ARMv7 core with an MMU
@item @code{cortex_m3} -- this is an ARMv7 core, supporting only the
compact Thumb2 instruction set. It supports one variant:
@itemize @minus
This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
be detected and the normal reset behaviour used.
@end itemize
+@item @code{dragonite} -- resembles arm966e
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core. This supports one variant:
@end deffn
@anchor{flash write_image}
-@deffn Command {flash write_image} [erase] filename [offset] [type]
+@deffn Command {flash write_image} [erase] [unlock] filename [offset] [type]
Write the image @file{filename} to the current target's flash bank(s).
A relocation @var{offset} may be specified, in which case it is added
to the base address for each section in the image.
@option{elf} (ELF file), @option{s19} (Motorola s19).
@option{mem}, or @option{builder}.
The relevant flash sectors will be erased prior to programming
-if the @option{erase} parameter is given.
-The flash bank to use is inferred from the @var{address} of
+if the @option{erase} parameter is given. If @option{unlock} is
+provided, then the flash banks are unlocked before erase and
+program. The flash bank to use is inferred from the @var{address} of
each image segment.
@end deffn
about what TAP is the current target, or about MMU configuration.
@end enumerate
-@deffn Command mdw addr [count]
-@deffnx Command mdh addr [count]
-@deffnx Command mdb addr [count]
+@deffn Command mdw [phys] addr [count]
+@deffnx Command mdh [phys] addr [count]
+@deffnx Command mdb [phys] addr [count]
Display contents of address @var{addr}, as
32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}),
or 8-bit bytes (@command{mdb}).
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
-@deffn Command mww addr word
-@deffnx Command mwh addr halfword
-@deffnx Command mwb addr byte
+@deffn Command mww [phys] addr word
+@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,
at the specified address @var{addr}.
+@var{phys} is an optional flag to indicate to use
+physical address and bypass MMU
@end deffn
This is a software breakpoint, unless @option{hw} is specified
in which case it will be a hardware breakpoint.
-(@xref{arm9tdmi vector_catch}, or @pxref{xscale vector_catch},
+(@xref{arm9 vector_catch}, or @pxref{xscale vector_catch},
for similar mechanisms that do not consume hardware breakpoints.)
@end deffn
@quotation Issues
ETM support may be buggy, and at least some @command{etm config}
parameters should be detected by asking the ETM for them.
+
+ETM trigger events could also implement a kind of complex
+hardware breakpoint, much more powerful than the simple
+watchpoint hardware exported by EmbeddedICE modules.
+@emph{Such breakpoints can be triggered even when using the
+dummy trace port driver}.
+
It seems like a GDB hookup should be possible,
-as well as triggering trace on specific events
+as well as tracing only during specific states
(perhaps @emph{handling IRQ 23} or @emph{calls foo()}).
+
There should be GUI tools to manipulate saved trace data and help
analyse it in conjunction with the source code.
It's unclear how much of a common interface is shared
with the current XScale trace support, or should be
shared with eventual Nexus-style trace module support.
+
At this writing (September 2009) only ARM7 and ARM9 support
for ETM modules is available. The code should be able to
work with some newer cores; but not all of them support
Declares the ETM associated with @var{target}, and associates it
with a given trace port @var{driver}. @xref{Trace Port Drivers}.
-Several of the parameters must reflect the trace port configuration.
+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}.
@deffn Command {etm info}
Displays information about the current target's ETM.
+This includes resource counts from the @code{ETM_CONFIG} register,
+as well as silicon capabilities (except on rather old modules).
+from the @code{ETM_SYS_CONFIG} register.
@end deffn
@deffn Command {etm status}
else if a @var{value} is provided, that value is written to that register.
@end deffn
-@deffn Command {arm720t mdw_phys} addr [count]
-@deffnx Command {arm720t mdh_phys} addr [count]
-@deffnx Command {arm720t mdb_phys} addr [count]
-Display contents of physical address @var{addr}, as
-32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
-or 8-bit bytes (@command{mdb_phys}).
-If @var{count} is specified, displays that many units.
-@end deffn
-
-@deffn Command {arm720t mww_phys} addr word
-@deffnx Command {arm720t mwh_phys} addr halfword
-@deffnx Command {arm720t mwb_phys} addr byte
-Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
-at the specified physical address @var{addr}.
-@end deffn
-
-@deffn Command {arm720t virt2phys} va
-Translate a virtual address @var{va} to a physical address
-and display the result.
-@end deffn
-
@subsection ARM9 specific commands
@cindex ARM9
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.
+@c 23-oct-2009: doesn't work _consistently_ ... as if the ICE
+@c versions have different rules about when they commit writes.
-@anchor{arm9tdmi vector_catch}
-@deffn Command {arm9tdmi vector_catch} [@option{all}|@option{none}|list]
+@anchor{arm9 vector_catch}
+@deffn Command {arm9 vector_catch} [@option{all}|@option{none}|list]
@cindex vector_catch
Vector Catch hardware provides a sort of dedicated breakpoint
for hardware events such as reset, interrupt, and abort.
@option{all} of the hardware vectors,
@option{none} of them,
or a list with one or more of the following:
-@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
+@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt}
@option{irq} @option{fiq}.
@end deffn
or using zero if no other address is not provided.
@end deffn
-@deffn Command {arm920t mdw_phys} addr [count]
-@deffnx Command {arm920t mdh_phys} addr [count]
-@deffnx Command {arm920t mdb_phys} addr [count]
-Display contents of physical address @var{addr}, as
-32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
-or 8-bit bytes (@command{mdb_phys}).
-If @var{count} is specified, displays that many units.
-@end deffn
-
-@deffn Command {arm920t mww_phys} addr word
-@deffnx Command {arm920t mwh_phys} addr halfword
-@deffnx Command {arm920t mwb_phys} addr byte
-Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
-at the specified physical address @var{addr}.
-@end deffn
-
@deffn Command {arm920t read_cache} filename
Dump the content of ICache and DCache to a file named @file{filename}.
@end deffn
Dump the content of the ITLB and DTLB to a file named @file{filename}.
@end deffn
-@deffn Command {arm920t virt2phys} va
-Translate a virtual address @var{va} to a physical address
-and display the result.
-@end deffn
-
@subsection ARM926ej-s specific commands
@cindex ARM926ej-s
Else that register is read and displayed.
@end deffn
-@deffn Command {arm926ejs mdw_phys} addr [count]
-@deffnx Command {arm926ejs mdh_phys} addr [count]
-@deffnx Command {arm926ejs mdb_phys} addr [count]
-Display contents of physical address @var{addr}, as
-32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
-or 8-bit bytes (@command{mdb_phys}).
-If @var{count} is specified, displays that many units.
-@end deffn
-
-@deffn Command {arm926ejs mww_phys} addr word
-@deffnx Command {arm926ejs mwh_phys} addr halfword
-@deffnx Command {arm926ejs mwb_phys} addr byte
-Writes the specified @var{word} (32 bits),
-@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
-at the specified physical address @var{addr}.
-@end deffn
-
-@deffn Command {arm926ejs virt2phys} va
-Translate a virtual address @var{va} to a physical address
-and display the result.
-@end deffn
-
@subsection ARM966E specific commands
@cindex ARM966E
@deffn Command {pathmove} start_state [next_state ...]
Start by moving to @var{start_state}, which
must be one of the @emph{stable} states.
+Unless it is the only state given, this will often be the
+current state, so that no TCK transitions are needed.
Then, in a series of single state transitions
(conforming to the JTAG state machine) shift to
each @var{next_state} in sequence, one per TCK cycle.
The @var{tap_state} names used by OpenOCD in the @command{drscan},
@command{irscan}, and @command{pathmove} commands are the same
-as those used in SVF boundary scan documents, except that some
-versions of SVF use @sc{idle} instead of @sc{run/idle}.
+as those used in SVF boundary scan documents, except that
+SVF uses @sc{idle} instead of @sc{run/idle}.
@itemize @bullet
@item @b{RESET} ... @emph{stable} (with TMS high);
messages are logged for comments and some retries.
@end deffn
+The OpenOCD sources also include two utility scripts
+for working with XSVF; they are not currently installed
+after building the software.
+You may find them useful:
+
+@itemize
+@item @emph{svf2xsvf} ... converts SVF files into the extended XSVF
+syntax understood by the @command{xsvf} command; see notes below.
+@item @emph{xsvfdump} ... converts XSVF files into a text output format;
+understands the OpenOCD extensions.
+@end itemize
+
+The input format accepts a handful of non-standard extensions.
+These include three opcodes corresponding to SVF extensions
+from Lattice Semiconductor (LCOUNT, LDELAY, LDSR), and
+two opcodes supporting a more accurate translation of SVF
+(XTRST, XWAITSTATE).
+If @emph{xsvfdump} shows a file is using those opcodes, it
+probably will not be usable with other XSVF tools.
+
+
@node TFTP
@chapter TFTP
@cindex TFTP
Code Review / openocd.git / blobdiff