zcy
/
tinyriscv-openocd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: fix html anchor xref links 

makeinfo has a long outstanding bug that means @anchors are not correctly
formatted for split html, see:
http://lists.gnu.org/archive/html/bug-texinfo/2012-06/msg00000.html

The issue relates to using spaces or hyphens in the @anchor name.
Issue also reported via Trac #44

Change-Id: Id72e23375dd167674b2ae5b314e8242b90a72a5f
Signed-off-by: Spencer Oliver <spen@spen-soft.co.uk>
Reviewed-on: http://openocd.zylin.com/1244
Tested-by: jenkins
Reviewed-by: Freddie Chopin <freddie.chopin@gmail.com>
__archive__
Spencer Oliver 2013-03-14 21:38:19 +00:00 committed by Andreas Fritiofson
parent 1da9e595ec
commit b7e0cd48f0
1 changed files with 119 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

241
doc/openocd.texi
View File

@ -321,8 +321,8 @@ RTCK support? Also known as ``adaptive clocking''
@section Stand alone Systems
@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/33-zylin-zy1000-jtag-probe} Technically, not a
dongle, but a standalone box. The ZY1000 has the advantage that it does
@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/33-zylin-zy1000-jtag-probe}
Technically, not a dongle, but a standalone box. The ZY1000 has the advantage that it does
not require any drivers installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
and has a built in relay to power cycle targets remotely.
@ -428,7 +428,9 @@ AT91SAM764 internally.
@end itemize
@section USB RLINK based
Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form on the STM32 Primer, permanently attached to the JTAG lines. It also exists on the STM32 Primer2, but that is wired for SWD and not JTAG, thus not supported.
Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form on the STM32 Primer,
permanently attached to the JTAG lines. It also exists on the STM32 Primer2, but that is wired for
SWD and not JTAG, thus not supported.
@itemize @bullet
@item @b{Raisonance RLink}
@ -699,7 +701,7 @@ you'll probably need more project-specific setup.
OpenOCD starts by processing the configuration commands provided
on the command line or, if there were no @option{-c command} or
@option{-f file.cfg} options given, in @file{openocd.cfg}.
@xref{Configuration Stage}.
@xref{configurationstage,,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.
@ -723,8 +725,8 @@ itself), use the @option{-d} command line switch. This sets the
@option{debug_level} to "3", outputting the most information,
including debug messages. The default setting is "2", outputting only
informational messages, warnings and errors. You can also change this
setting from within a telnet or gdb session using @command{debug_level
<n>} (@pxref{debug_level}).
setting from within a telnet or gdb session using @command{debug_level<n>}
(@pxref{debuglevel,,debug_level}).
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
@ -934,7 +936,7 @@ need help from OpenOCD to discover what's on the board.
Once you find the JTAG TAPs, you can just search for appropriate
target and board
configuration files ... or write your own, from the bottom up.
@xref{Autoprobing}.
@xref{autoprobing,,Autoprobing}.
@item You can often reuse some standard config files but
need to write a few new ones, probably a @file{board.cfg} file.
@ -986,7 +988,7 @@ and @command{cortex_m3 vector_catch}) can be a timesaver
during some debug sessions, but don't make everyone use that either.
Keep those kinds of debugging aids in your user config file,
along with messaging and tracing setup.
(@xref{Software Debug Messages and Tracing}.)
(@xref{softwaredebugmessagesandtracing,,Software Debug Messages and Tracing}.)
@item
You might need to override some defaults.
@ -996,7 +998,7 @@ 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}.
a user config file. @xref{tcpipports,,TCP/IP Ports}.
@end itemize
@section Project-Specific Utilities
@ -1153,7 +1155,7 @@ Your application may want to deliver various debugging messages
over JTAG, by @emph{linking with a small library of code}
provided with OpenOCD and using the utilities there to send
various kinds of message.
@xref{Software Debug Messages and Tracing}.
@xref{softwaredebugmessagesandtracing,,Software Debug Messages and Tracing}.
@end itemize
@ -1482,8 +1484,8 @@ In summary the board files should contain (if present)
@enumerate
@item One or more @command{source [target/...cfg]} statements
@item NOR flash configuration (@pxref{NOR Configuration})
@item NAND flash configuration (@pxref{NAND Configuration})
@item NOR flash configuration (@pxref{norconfiguration,,NOR Configuration})
@item NAND flash configuration (@pxref{nandconfiguration,,NAND Configuration})
@item Target @code{reset} handlers for SDRAM and I/O configuration
@item JTAG adapter reset configuration (@pxref{Reset Configuration})
@item All things that are not ``inside a chip''
@ -1619,7 +1621,7 @@ are included here.
Instead, look at the board config files distributed with OpenOCD.
If you have a boot loader, its source code will help; so will
configuration files for other JTAG tools
(@pxref{Translating Configuration Files}).
(@pxref{translatingconfigurationfiles,,Translating Configuration Files}).
@end quotation
Some of this code could probably be shared between different boards.
@ -1643,7 +1645,7 @@ access uses the CPU or to prevent conflicting CPU access.
Before your @code{reset-init} handler has set up
the PLLs and clocking, you may need to run with
a low JTAG clock rate.
@xref{JTAG Speed}.
@xref{jtagspeed,,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
@ -1671,19 +1673,21 @@ also supports it. Otherwise use @command{adapter_khz}.
Set the slow rate at the beginning of the reset sequence,
and the faster rate as soon as the clocks are at full speed.
@anchor{The init_board procedure}
@anchor{theinitboardprocedure}
@subsection The init_board procedure
@cindex init_board procedure
The concept of @code{init_board} procedure is very similar to @code{init_targets} (@xref{The init_targets procedure}.)
- it's a replacement of ``linear'' configuration scripts. This procedure is meant to be executed when OpenOCD enters run
stage (@xref{Entering the Run Stage},) after @code{init_targets}. The idea to have spearate @code{init_targets} and
@code{init_board} procedures is to allow the first one to configure everything target specific (internal flash,
internal RAM, etc.) and the second one to configure everything board specific (reset signals, chip frequency,
reset-init event handler, external memory, etc.). Additionally ``linear'' board config file will most likely fail when
target config file uses @code{init_targets} scheme (``linear'' script is executed before @code{init} and
@code{init_targets} - after), so separating these two configuration stages is very convenient, as the easiest way to
overcome this problem is to convert board config file to use @code{init_board} procedure. Board config scripts don't
The concept of @code{init_board} procedure is very similar to @code{init_targets}
(@xref{theinittargetsprocedure,,The init_targets procedure}.) - it's a replacement of ``linear''
configuration scripts. This procedure is meant to be executed when OpenOCD enters run stage
(@xref{enteringtherunstage,,Entering the Run Stage},) after @code{init_targets}. The idea to have
spearate @code{init_targets} and @code{init_board} procedures is to allow the first one to configure
everything target specific (internal flash, internal RAM, etc.) and the second one to configure
everything board specific (reset signals, chip frequency, reset-init event handler, external memory, etc.).
Additionally ``linear'' board config file will most likely fail when target config file uses
@code{init_targets} scheme (``linear'' script is executed before @code{init} and @code{init_targets} - after),
so separating these two configuration stages is very convenient, as the easiest way to overcome this
problem is to convert board config file to use @code{init_board} procedure. Board config scripts don't
need to override @code{init_targets} defined in target config files when they only need to to add some specifics.
Just as @code{init_targets}, the @code{init_board} procedure can be overriden by ``next level'' script (which sources
@ -1864,7 +1868,7 @@ $_TARGETNAME configure -work-area-phys 0x00200000 \
-work-area-size 0x4000 -work-area-backup 0
@end example
@anchor{Define CPU targets working in SMP}
@anchor{definecputargetsworkinginsmp}
@subsection Define CPU targets working in SMP
@cindex SMP
After setting targets, you can define a list of targets working in SMP.
@ -1887,7 +1891,7 @@ In SMP only one GDB instance is created and :
@item resume command triggers the write context and the restart of all targets in the list.
@item following a breakpoint: the target stopped by the breakpoint is displayed to the GDB session.
@item dedicated GDB serial protocol packets are implemented for switching/retrieving the target
displayed by the GDB session @pxref{Using openocd SMP with GDB}.
displayed by the GDB session @pxref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}.
@end itemize
The SMP behaviour can be disabled/enabled dynamically. On cortex_a8 following
@ -1963,7 +1967,7 @@ 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}.
@xref{jtagspeed,,JTAG Speed}.
@quotation Important
When you are debugging code that runs right after chip
@ -1973,17 +1977,19 @@ OpenOCD verifies the scan chain after reset,
look at how you are setting up JTAG clocking.
@end quotation
@anchor{The init_targets procedure}
@anchor{theinittargetsprocedure}
@subsection The init_targets procedure
@cindex init_targets procedure
Target config files can either be ``linear'' (script executed line-by-line when parsed in configuration stage,
@xref{Configuration Stage},) or they can contain a special procedure called @code{init_targets}, which will be executed
when entering run stage (after parsing all config files or after @code{init} command, @xref{Entering the Run Stage}.)
Such procedure can be overriden by ``next level'' script (which sources the original). This concept faciliates code
reuse when basic target config files provide generic configuration procedures and @code{init_targets} procedure, which
can then be sourced and enchanced or changed in a ``more specific'' target config file. This is not possible with
``linear'' config scripts, because sourcing them executes every initialization commands they provide.
Target config files can either be ``linear'' (script executed line-by-line when parsed in
configuration stage, @xref{configurationstage,,Configuration Stage},) or they can contain a special
procedure called @code{init_targets}, which will be executed when entering run stage
(after parsing all config files or after @code{init} command, @xref{enteringtherunstage,,Entering the Run Stage}.)
Such procedure can be overriden by ``next level'' script (which sources the original).
This concept faciliates code reuse when basic target config files provide generic configuration
procedures and @code{init_targets} procedure, which can then be sourced and enchanced or changed in
a ``more specific'' target config file. This is not possible with ``linear'' config scripts,
because sourcing them executes every initialization commands they provide.
@example
### generic_file.cfg ###
@ -2007,12 +2013,13 @@ proc init_targets @{@} @{
@}
@end example
The easiest way to convert ``linear'' config files to @code{init_targets} version is to enclose every line of ``code''
(i.e. not @code{source} commands, procedures, etc.) in this procedure.
The easiest way to convert ``linear'' config files to @code{init_targets} version is to
enclose every line of ``code'' (i.e. not @code{source} commands, procedures, etc.) in this procedure.
For an example of this scheme see LPC2000 target config files.
The @code{init_boards} procedure is a similar concept concerning board config files (@xref{The init_board procedure}.)
The @code{init_boards} procedure is a similar concept concerning board config files
(@xref{theinitboardprocedure,,The init_board procedure}.)
@subsection ARM Core Specific Hacks
@ -2025,7 +2032,7 @@ Some ARM cores are equipped with trace support, which permits
examination of the instruction and data bus activity. Trace
activity is controlled through an ``Embedded Trace Module'' (ETM)
on one of the core's scan chains. The ETM emits voluminous data
through a ``trace port''. (@xref{ARM Hardware Tracing}.)
through a ``trace port''. (@xref{armhardwaretracing,,ARM Hardware Tracing}.)
If you are using an external trace port,
configure it in your board config file.
If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
@ -2053,7 +2060,7 @@ Examples:
@item pxa270 - again - CS0 flash - it goes in the board file.
@end itemize
@anchor{Translating Configuration Files}
@anchor{translatingconfigurationfiles}
@section Translating Configuration Files
@cindex translation
If you have a configuration file for another hardware debugger
@ -2100,7 +2107,7 @@ The commands here are commonly found in the openocd.cfg file and are
used to specify what TCP/IP ports are used, and how GDB should be
supported.
@anchor{Configuration Stage}
@anchor{configurationstage}
@section Configuration Stage
@cindex configuration stage
@cindex config command
@ -2126,7 +2133,7 @@ may access or activate TAPs.
After it leaves this stage, configuration commands may no
longer be issued.
@anchor{Entering the Run Stage}
@anchor{enteringtherunstage}
@section Entering the Run Stage
The first thing OpenOCD does after leaving the configuration
@ -2184,7 +2191,7 @@ This is done by calling @command{jtag arp_init}
(or @command{jtag arp_init-reset}).
@end deffn
@anchor{TCP/IP Ports}
@anchor{tcpipports}
@section TCP/IP Ports
@cindex TCP port
@cindex server
@ -2246,16 +2253,16 @@ the port @var{number} defaults to 4444.
When specified as zero, this port is not activated.
@end deffn
@anchor{GDB Configuration}
@anchor{gdbconfiguration}
@section GDB Configuration
@cindex GDB
@cindex GDB configuration
You can reconfigure some GDB behaviors if needed.
The ones listed here are static and global.
@xref{Target Configuration}, about configuring individual targets.
@xref{Target Events}, about configuring target-specific event handling.
@xref{targetconfiguration,,Target Configuration}, about configuring individual targets.
@xref{targetevents,,Target Events}, about configuring target-specific event handling.
@anchor{gdb_breakpoint_override}
@anchor{gdbbreakpointoverride}
@deffn {Command} gdb_breakpoint_override [@option{hard}|@option{soft}|@option{disable}]
Force breakpoint type for gdb @command{break} commands.
This option supports GDB GUIs which don't
@ -2264,7 +2271,7 @@ GDB behaviour is not sufficient. GDB normally uses hardware
breakpoints if the memory map has been set up for flash regions.
@end deffn
@anchor{gdb_flash_program}
@anchor{gdbflashprogram}
@deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
@ -2277,7 +2284,7 @@ requested. GDB will then know when to set hardware breakpoints, and program flas
using the GDB load command. @command{gdb_flash_program enable} must also be enabled
for flash programming to work.
Default behaviour is @option{enable}.
@xref{gdb_flash_program}.
@xref{gdbflashprogram,,gdb_flash_program}.
@end deffn
@deffn {Config Command} gdb_report_data_abort (@option{enable}|@option{disable})
@ -2287,7 +2294,7 @@ The default behaviour is @option{disable};
use @option{enable} see these errors reported.
@end deffn
@anchor{Event Polling}
@anchor{eventpolling}
@section Event Polling
Hardware debuggers are parts of asynchronous systems,
@ -2328,7 +2335,7 @@ which is normally done in the background.
@deffn Command poll [@option{on}|@option{off}]
Poll the current target for its current state.
(Also, @pxref{target curstate}.)
(Also, @pxref{targetcurstate,,target curstate}.)
If that target is in debug mode, architecture
specific information about the current state is printed.
An optional parameter
@ -3038,7 +3045,7 @@ The Serial Peripheral Interface (SPI) is a general purpose transport
which uses four wire signaling. Some processors use it as part of a
solution for flash programming.
@anchor{JTAG Speed}
@anchor{jtagspeed}
@section JTAG Speed
JTAG clock setup is part of system setup.
It @emph{does not belong with interface setup} since any interface
@ -3057,7 +3064,7 @@ 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}.
@xref{targetevents,,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.
@ -3094,7 +3101,7 @@ 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}.
@xref{faqrtck,,FAQ RTCK}.
If your system uses RTCK, you won't need to change the
JTAG clocking after setup.
Not all interfaces, boards, or targets support ``rtck''.
@ -3122,7 +3129,7 @@ Every system configuration may require a different reset
configuration. This can also be quite confusing.
Resets also interact with @var{reset-init} event handlers,
which do things like setting up clocks and DRAM, and
JTAG clock rates. (@xref{JTAG Speed}.)
JTAG clock rates. (@xref{jtagspeed,,JTAG Speed}.)
They can also interact with JTAG routers.
Please see the various board files for examples.
@ -3179,9 +3186,9 @@ halted under debugger control before any code has executed.
This is the behavior required to support the @command{reset halt}
and @command{reset init} commands; after @command{reset init} a
board-specific script might do things like setting up DRAM.
(@xref{Reset Command}.)
(@xref{resetcommand,,Reset Command}.)
@anchor{SRST and TRST Issues}
@anchor{srstandtrstissues}
@section SRST and TRST Issues
Because SRST and TRST are hardware signals, they can have a
@ -3282,7 +3289,7 @@ of your combination of JTAG board and target in target
configuration scripts.
Information earlier in this section describes the kind of problems
the command is intended to address (@pxref{SRST and TRST Issues}).
the command is intended to address (@pxref{srstandtrstissues,,SRST and TRST Issues}).
As a rule this command belongs only in board config files,
describing issues like @emph{board doesn't connect TRST};
or in user config files, addressing limitations derived
@ -3401,7 +3408,7 @@ to find a sequence of operations that works.
@xref{JTAG Commands}.
When you find a working sequence, it can be used to override
@command{jtag_init}, which fires during OpenOCD startup
(@pxref{Configuration Stage});
(@pxref{configurationstage,,Configuration Stage});
or @command{init_reset}, which fires during reset processing.
You might also want to provide some project-specific reset
@ -3511,7 +3518,7 @@ Here's what the scan chain might look like for a chip more than one TAP:
@end verbatim
OpenOCD can detect some of that information, but not all
of it. @xref{Autoprobing}.
of it. @xref{autoprobing,,Autoprobing}.
Unfortunately those TAPs can't always be autoconfigured,
because not all devices provide good support for that.
JTAG doesn't require supporting IDCODE instructions, and
@ -3534,7 +3541,7 @@ and so forth.
Note that @emph{the order in which TAPs are declared is very important.}
It must match the order in the JTAG scan chain, both inside
a single chip and between them.
@xref{FAQ TAP Order}.
@xref{faqtaporder,,FAQ TAP Order}.
For example, the ST Microsystems STR912 chip has
three separate TAPs@footnote{See the ST
@ -3610,7 +3617,6 @@ reusing those scripts on boards with multiple targets.
@section TAP Declaration Commands
@c shouldn't this be(come) a {Config Command}?
@anchor{jtag newtap}
@deffn Command {jtag newtap} chipname tapname configparams...
Declares a new TAP with the dotted name @var{chipname}.@var{tapname},
and configured according to the various @var{configparams}.
@ -3658,7 +3664,7 @@ linked in to the scan chain after a reset using either TRST
or the JTAG state machine's @sc{reset} state.
You may use @code{-enable} to highlight the default state
(the TAP is linked in).
@xref{Enabling and Disabling TAPs}.
@xref{enablinganddisablingtaps,,Enabling and Disabling TAPs}.
@item @code{-expected-id} @var{number}
@*A non-zero @var{number} represents a 32-bit IDCODE
which you expect to find when the scan chain is examined.
@ -3673,7 +3679,7 @@ tell when the scan chain it sees isn't right. These values
are provided in vendors' chip documentation, usually a technical
reference manual. Sometimes you may need to probe the JTAG
hardware to find these values.
@xref{Autoprobing}.
@xref{autoprobing,,Autoprobing}.
@item @code{-ignore-version}
@*Specify this to ignore the JTAG version field in the @code{-expected-id}
option. When vendors put out multiple versions of a chip, or use the same
@ -3711,7 +3717,6 @@ a TCL string which is evaluated when the event is triggered.
The @code{cget} subcommand returns that handler.
@end deffn
@anchor{TAP Events}
@section TAP Events
@cindex events
@cindex TAP events
@ -3760,7 +3765,7 @@ jtag configure CHIP.jrc -event post-reset @{
@end example
@anchor{Enabling and Disabling TAPs}
@anchor{enablinganddisablingtaps}
@section Enabling and Disabling TAPs
@cindex JTAG Route Controller
@cindex jrc
@ -3848,7 +3853,7 @@ for querying the state of the JTAG taps.
@end quotation
@end deffn
@anchor{Autoprobing}
@anchor{autoprobing}
@section Autoprobing
@cindex autoprobe
@cindex JTAG autoprobe
@ -3924,7 +3929,7 @@ and so forth.
This chapter discusses how to set up GDB debug targets for CPUs.
You can also access these targets without GDB
(@pxref{Architecture and Core Commands},
and @ref{Target State handling}) and
and @ref{targetstatehandling,,Target State handling}) and
through various kinds of NAND and NOR flash commands.
If you have multiple CPUs you can have multiple such targets.
@ -4042,7 +4047,7 @@ since there's a command to list them.
However, there is currently no way to list what target variants
are supported (other than by reading the OpenOCD source code).
@anchor{target types}
@anchor{targettypes}
@deffn Command {target types}
Lists all supported target types.
At this writing, the supported CPU types and variants are:
@ -4089,7 +4094,7 @@ reflect design generations;
while names like ARMv4, ARMv5, ARMv6, and ARMv7
reflect an architecture version implemented by a CPU design.
@anchor{Target Configuration}
@anchor{targetconfiguration}
@section Target Configuration
Before creating a ``target'', you must have added its TAP to the scan chain.
@ -4107,7 +4112,7 @@ command, created as part of target creation.
The two main things to configure after target creation are
a work area, which usually has target-specific defaults even
if the board setup code overrides them later;
and event handlers (@pxref{Target Events}), which tend
and event handlers (@pxref{targetevents,,Target Events}), which tend
to be much more board-specific.
The key steps you use might look something like this
@ -4160,7 +4165,7 @@ using the @code{-chain-position @var{dotted.name}} configparam.
This name is also used to create the target object command,
referred to here as @command{$target_name},
and in other places the target needs to be identified.
@item @var{type} ... specifies the target type. @xref{target types}.
@item @var{type} ... specifies the target type. @xref{targettypes,,target types}.
@item @var{configparams} ... all parameters accepted by
@command{$target_name configure} are permitted.
If the target is big-endian, set it here with @code{-endian big}.
@ -4189,7 +4194,7 @@ used to access this target.
whether the CPU uses big or little endian conventions
@item @code{-event} @var{event_name} @var{event_body} --
@xref{Target Events}.
@xref{targetevents,,Target Events}.
Note that this updates a list of named event handlers.
Calling this twice with two different event names assigns
two different handlers, but calling it twice with the
@ -4324,20 +4329,20 @@ foreach name [target names] @{
@end example
@end deffn
@anchor{target curstate}
@anchor{targetcurstate}
@deffn Command {$target_name curstate}
Displays the current target state:
@code{debug-running},
@code{halted},
@code{reset},
@code{running}, or @code{unknown}.
(Also, @pxref{Event Polling}.)
(Also, @pxref{eventpolling,,Event Polling}.)
@end deffn
@deffn Command {$target_name eventlist}
Displays a table listing all event handlers
currently associated with this target.
@xref{Target Events}.
@xref{targetevents,,Target Events}.
@end deffn
@deffn Command {$target_name invoke-event} event_name
@ -4365,7 +4370,7 @@ Writes the specified @var{word} (32 bits),
at the specified address @var{addr}.
@end deffn
@anchor{Target Events}
@anchor{targetevents}
@section Target Events
@cindex target events
@cindex events
@ -4528,7 +4533,7 @@ boot loader, operating system, or other data.
@item GDB Flashing
@* Flashing via GDB requires the flash be configured via ``flash
bank'', and the GDB flash features be enabled.
@xref{GDB Configuration}.
@xref{gdbconfiguration,,GDB Configuration}.
@end enumerate
Many CPUs have the ablity to ``boot'' from the first flash bank.
@ -4537,7 +4542,7 @@ so that it can't boot.
JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
board by (re)installing working boot firmware.
@anchor{NOR Configuration}
@anchor{norconfiguration}
@section Flash Configuration Commands
@cindex flash configuration
@ -4555,7 +4560,7 @@ in other flash commands. A number is also available.
associated with the flash bank being declared.
This is usually @code{cfi} for external flash, or else
the name of a microcontroller with embedded flash memory.
@xref{Flash Driver List}.
@xref{flashdriverlist,,Flash Driver List}.
@item @var{base} ... Base address of the flash chip.
@item @var{size} ... Size of the chip, in bytes.
For some drivers, this value is detected from the hardware.
@ -4605,13 +4610,13 @@ but most don't bother.
@cindex flash reading
@cindex flash writing
@cindex flash programming
@anchor{Flash Programming Commands}
@anchor{flashprogrammingcommands}
One feature distinguishing NOR flash from NAND or serial flash technologies
is that for read access, it acts exactly like any other addressible memory.
This means you can use normal memory read commands like @command{mdw} or
@command{dump_image} with it, with no special @command{flash} subcommands.
@xref{Memory access}, and @ref{Image access}.
@xref{memoryaccess,,Memory access}, and @ref{imageaccess,,Image access}.
Write access works differently. Flash memory normally needs to be erased
before it's written. Erasing a sector turns all of its bits to ones, and
@ -4637,9 +4642,8 @@ For such systems, erasing and writing may require sector protection to be
disabled first.
Examples include CFI flash such as ``Intel Advanced Bootblock flash'',
and AT91SAM7 on-chip flash.
@xref{flash protect}.
@xref{flashprotect,,flash protect}.
@anchor{flash erase_sector}
@deffn Command {flash erase_sector} num first last
Erase sectors in bank @var{num}, starting at sector @var{first}
up to and including @var{last}.
@ -4679,14 +4683,12 @@ each block, and the specified length must stay within that bank.
@end deffn
@comment no current checks for errors if fill blocks touch multiple banks!
@anchor{flash write_bank}
@deffn Command {flash write_bank} num filename offset
Write the binary @file{filename} to flash bank @var{num},
starting at @var{offset} bytes from the beginning of the bank.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@anchor{flash write_image}
@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
@ -4739,7 +4741,7 @@ This command will first query the hardware, it does not print cached
and possibly stale information.
@end deffn
@anchor{flash protect}
@anchor{flashprotect}
@deffn Command {flash protect} num first last (@option{on}|@option{off})
Enable (@option{on}) or disable (@option{off}) protection of flash sectors
in flash bank @var{num}, starting at sector @var{first}
@ -4756,7 +4758,7 @@ programmer. The only required parameter is @option{filename}, the others are opt
@xref{Flash Programming}.
@end deffn
@anchor{Flash Driver List}
@anchor{flashdriverlist}
@section Flash Driver List
As noted above, the @command{flash bank} command requires a driver name,
and allows driver-specific options and behaviors.
@ -5601,7 +5603,8 @@ Write the binary file @var{filename} to mflash bank @var{num}, starting at
@chapter Flash Programming
OpenOCD implements numerous ways to program the target flash, whether internal or external.
Programming can be acheived by either using GDB @ref{Programming using GDB}, or using the cmds given in @ref{Flash Programming Commands}.
Programming can be acheived by either using GDB @ref{programmingusinggdb,,Programming using GDB},
or using the cmds given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
@*To simplify using the flash cmds directly a jimtcl script is available that handles the programming and verify stage.
OpenOCD will program/verify/reset the target and shutdown.
@ -5693,7 +5696,7 @@ is larger than 0xffffffff, the largest 32-bit unsigned integer.)
Some larger devices will work, since they are actually multi-chip
modules with two smaller chips and individual chipselect lines.
@anchor{NAND Configuration}
@anchor{nandconfiguration}
@section NAND Configuration Commands
@cindex NAND configuration
@ -5719,7 +5722,7 @@ configuration files, not interactively.
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}.
@xref{nanddriverlist,,NAND Driver List}.
@item @var{target} ... names the target used when issuing
commands to the NAND controller.
@comment Actually, it's currently a controller-specific parameter...
@ -5936,7 +5939,7 @@ bypassing hardware ECC logic.
with the wrong ECC data can cause them to be marked as bad.
@end deffn
@anchor{NAND Driver List}
@anchor{nanddriverlist}
@section NAND Driver List
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
@ -6171,7 +6174,7 @@ Useful in connection with script files
Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
@end deffn
@anchor{debug_level}
@anchor{debuglevel}
@deffn Command debug_level [n]
@cindex message level
Display debug level.
@ -6205,7 +6208,7 @@ the initial log output channel is stderr.
Add @var{directory} to the file/script search path.
@end deffn
@anchor{Target State handling}
@anchor{targetstatehandling}
@section Target State handling
@cindex reset
@cindex halt
@ -6302,7 +6305,7 @@ Single-step the target at its current code position,
or the optional @var{address} if it is provided.
@end deffn
@anchor{Reset Command}
@anchor{resetcommand}
@deffn Command reset
@deffnx Command {reset run}
@deffnx Command {reset halt}
@ -6393,7 +6396,7 @@ Unlinks the file @file{filename}.
Removes all data in the file @file{filename}.
@end deffn
@anchor{Memory access}
@anchor{memoryaccess}
@section Memory access commands
@cindex memory access
@ -6437,13 +6440,11 @@ Otherwise, or if the optional @var{phys} flag is specified,
@var{addr} is interpreted as a physical address.
@end deffn
@anchor{Image access}
@anchor{imageaccess}
@section Image loading commands
@cindex image loading
@cindex image dumping
@anchor{dump_image}
@deffn Command {dump_image} filename address size
Dump @var{size} bytes of target memory starting at @var{address} to the
binary file named @var{filename}.
@ -6465,7 +6466,6 @@ target programming performance as I/O and target programming can easily be profi
separately.
@end deffn
@anchor{load_image}
@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}|@option{s19}] @option{min_addr} @option{max_length}]
Load image from file @var{filename} to target memory offset by @var{address} from its load address.
The file format may optionally be specified
@ -6514,7 +6514,7 @@ at @var{address} for @var{length} bytes.
This is a software breakpoint, unless @option{hw} is specified
in which case it will be a hardware breakpoint.
(@xref{arm9 vector_catch}, or @pxref{xscale vector_catch},
(@xref{arm9vectorcatch,,arm9 vector_catch}, or @pxref{xscalevectorcatch,,xscale vector_catch},
for similar mechanisms that do not consume hardware breakpoints.)
@end deffn
@ -6565,7 +6565,7 @@ OpenOCD packages most such operations in its standard command framework.
Some of those operations don't fit well in that framework, so they are
exposed here as architecture or implementation (core) specific commands.
@anchor{ARM Hardware Tracing}
@anchor{armhardwaretracing}
@section ARM Hardware Tracing
@cindex tracing
@cindex ETM
@ -6628,7 +6628,7 @@ ETM setup is coupled with the trace port driver configuration.
@deffn {Config Command} {etm config} target width mode clocking driver
Declares the ETM associated with @var{target}, and associates it
with a given trace port @var{driver}. @xref{Trace Port Drivers}.
with a given trace port @var{driver}. @xref{traceportdrivers,,Trace Port Drivers}.
Several of the parameters must reflect the trace port capabilities,
which are a function of silicon capabilties (exposed later
@ -6769,7 +6769,7 @@ Starts trace data collection.
Stops trace data collection.
@end deffn
@anchor{Trace Port Drivers}
@anchor{traceportdrivers}
@subsection Trace Port Drivers
To use an ETM trace port it must be associated with a driver.
@ -6948,7 +6948,6 @@ unsafe, especially with targets running at very low speeds. This command was int
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}]
Displays the value of the flag controlling use of memory writes and reads
that don't check completion of the operation.
@ -6988,7 +6987,7 @@ Such cores include the ARM920T, ARM926EJ-S, and ARM966.
@c 23-oct-2009: doesn't work _consistently_ ... as if the ICE
@c versions have different rules about when they commit writes.
@anchor{arm9 vector_catch}
@anchor{arm9vectorcatch}
@deffn Command {arm9 vector_catch} [@option{all}|@option{none}|list]
@cindex vector_catch
Vector Catch hardware provides a sort of dedicated breakpoint
@ -7213,7 +7212,7 @@ The image @var{type} may be one of
@option{mem}, or @option{builder}.
@end deffn
@anchor{xscale vector_catch}
@anchor{xscalevectorcatch}
@deffn Command {xscale vector_catch} [mask]
@cindex vector_catch
Display a bitmask showing the hardware vectors to catch.
@ -7232,7 +7231,6 @@ The mask bits correspond with bit 16..23 in the DCSR:
@end example
@end deffn
@anchor{xscale vector_table}
@deffn Command {xscale vector_table} [(@option{low}|@option{high}) index value]
@cindex vector_table
@ -7384,10 +7382,10 @@ Using @option{vectreset} is a safe option for all current Cortex-M3 cores.
This however has the disadvantage of only resetting the core, all peripherals
are uneffected. A solution would be to use a @code{reset-init} event handler to manually reset
the peripherals.
@xref{Target Events}.
@xref{targetevents,,Target Events}.
@end deffn
@anchor{Software Debug Messages and Tracing}
@anchor{softwaredebugmessagesandtracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
@cindex tracing
@ -7403,7 +7401,7 @@ is supported only for @option{arm7_9} and @option{cortex_m3} cores.
These messages are received as part of target polling, so
you need to have @command{poll on} active to receive them.
They are intrusive in that they will affect program execution
times. If that is a problem, @pxref{ARM Hardware Tracing}.
times. If that is a problem, @pxref{armhardwaretracing,,ARM Hardware Tracing}.
See @file{libdcc} in the contrib dir for more details.
In addition to sending strings, characters, and
@ -7477,7 +7475,7 @@ or after @command{trace point clear}) and count up from there.
@chapter JTAG Commands
@cindex JTAG Commands
Most general purpose JTAG commands have been presented earlier.
(@xref{JTAG Speed}, @ref{Reset Configuration}, and @ref{TAP Declaration}.)
(@xref{jtagspeed,,JTAG Speed}, @ref{Reset Configuration}, and @ref{TAP Declaration}.)
Lower level JTAG commands, as presented here,
may be needed to work with targets which require special
attention during operations such as reset or initialization.
@ -7789,7 +7787,7 @@ Setting up GDB to work with OpenOCD can involve several components:
@itemize
@item The OpenOCD server support for GDB may need to be configured.
@xref{GDB Configuration}.
@xref{gdbconfiguration,,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,
@ -7803,7 +7801,6 @@ cross-development for ARM on an x86 PC, instead of using the native
x86 @command{gdb} command you might use @command{arm-none-eabi-gdb}
if that's the tool chain used to compile your code.
@anchor{Connecting to GDB}
@section Connecting to GDB
@cindex Connecting to GDB
Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
@ -7920,7 +7917,7 @@ using @command{gdb -x filename}.
@section Programming using GDB
@cindex Programming using GDB
@anchor{Programming using GDB}
@anchor{programmingusinggdb}
By default the target memory map is sent to GDB. This can be disabled by
the following OpenOCD configuration option:
@ -7934,7 +7931,7 @@ working area.
Informing GDB of the memory map of the target will enable GDB to protect any
flash areas of the target and use hardware breakpoints by default. This means
that the OpenOCD option @command{gdb_breakpoint_override} is not required when
using a memory map. @xref{gdb_breakpoint_override}.
using a memory map. @xref{gdbbreakpointoverride,,gdb_breakpoint_override}.
To view the configured memory map in GDB, use the GDB command @option{info mem}
All other unassigned addresses within GDB are treated as RAM.
@ -7960,8 +7957,8 @@ $_TARGETNAME configure -event EVENTNAME BODY
To verify any flash programming the GDB command @option{compare-sections}
can be used.
@anchor{Using openocd SMP with GDB}
@section Using openocd SMP with GDB
@anchor{usingopenocdsmpwithgdb}
@section Using OpenOCD SMP with GDB
@cindex SMP
For SMP support following GDB serial protocol packet have been defined :
@itemize @bullet
@ -7990,8 +7987,8 @@ print $_core
#jc packet is sent and result is affected in $
@end example
@item by the usage of GDB maintenance command as described in following example (2
cpus in SMP with core id 0 and 1 @pxref{Define CPU targets working in SMP}).
@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with
core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}).
@example
# toggle0 : force display of coreid 0
@ -8104,7 +8101,7 @@ is jim, not real tcl).
@chapter FAQ
@cindex faq
@enumerate
@anchor{FAQ RTCK}
@anchor{faqrtck}
@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
@cindex RTCK
@cindex adaptive clocking
@ -8357,7 +8354,7 @@ processed. Such commands include @command{nand probe} and everything
else that needs to write to controller registers, perhaps for setting
up DRAM and loading it with code.
@anchor{FAQ TAP Order}
@anchor{faqtaporder}
@item @b{JTAG TAP Order} Do I have to declare the TAPS in some
particular order?