imi415
/
openocd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

David Brownell <david-b@pacbell.net>: 

Various bits of cleanup, mostly to match the style hints
I just got around to writing up.

 - Various @cindex improvements

 - Cross reference the command line options in a few spots,
   notably for @command{debug_level}

 - Clean the config file guidelines a bit:
    * They're for all users, not just integrators
    * Reference the interface config chapter
    * Don't emphasize command line usage here
    * Tweak board and target config introductory text

Plus two minor bits of cleanup:  remove most date references,
and refer to the reader as "you" not "the user".


git-svn-id: svn://svn.berlios.de/openocd/trunk@2271 b42882b7-edfa-0310-969c-e2dbd0fdcd60
This commit is contained in:
zwelch 2009-06-18 00:29:39 +00:00
parent 8ab9b6d39e
commit 6f4d876c88
1 changed files with 101 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
doc/openocd.texi
View File

@ -104,6 +104,8 @@ supported by a diverse community of software and hardware developers from
around the world.
@section What is OpenOCD?
@cindex TAP
@cindex JTAG
The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
in-system programming and boundary-scan testing for embedded target
@ -356,7 +358,11 @@ give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpack
@option{--with-ftd2xx-linux-tardir=PATH} - If using FTDICHIP.COM ft2232c driver
on Linux, give the directory where the Linux driver's TAR.GZ file was unpacked.
@item
@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static. Specifies how the FTDICHIP.COM libftd2xx driver should be linked. Note: 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. The 'shared' value is supported (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally.
@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static.
Specifies how the FTDICHIP.COM libftd2xx driver should be linked.
Note: 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}.
The 'shared' value is supported, however you must manually install the required
header files and shared libraries in an appropriate place.
@item
@option{--enable-presto_libftdi} - Enable building support for ASIX Presto programmer using the libftdi driver.
@item
@ -398,8 +404,9 @@ not available for all operating systems used with OpenOCD.
The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux)
TAR.GZ file. You must unpack them ``some where'' convient. As of this
writing (12/26/2008) FTDICHIP does not supply means to install these
files ``in an appropriate place'' As a result, there are two
writing FTDICHIP does not supply means to install these
files ``in an appropriate place''.
As a result, there are two
``./configure'' options that help.
Below is an example build process:
@ -476,7 +483,7 @@ openocd @option{-v} is executed.
@cindex zy1000
@cindex printer port
@cindex USB Adapter
@cindex rtck
@cindex RTCK
Defined: @b{dongle}: A small device that plugins into a computer and serves as
an adapter .... [snip]
@ -518,8 +525,6 @@ See: @url{http://www.ftdichip.com} for more information.
In summer 2009, USB high speed (480 Mbps) versions of these FTDI
chips are starting to become available in JTAG adapters.
As of 28/Nov/2008, the following are supported:
@itemize @bullet
@item @b{usbjtag}
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
@ -654,11 +659,9 @@ FlashLINK JTAG programing cable for PSD and uPSD}
@node Running
@chapter Running
@cindex running OpenOCD
@cindex --configfile
@cindex --debug_level
@cindex --logfile
@cindex --search
@cindex command line options
@cindex logfile
@cindex directory search
The @option{--help} option shows:
@verbatim
@ -696,8 +699,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 @option{debug_level
<n>} @xref{debug_level}.
setting from within a telnet or gdb session using @command{debug_level
<n>} (@pxref{debug_level}).
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
@ -851,8 +854,9 @@ file, including basic configuration plus any TCL procedures
to simplify your work.
@section User Config Files
@cindex config file
@cindex config file, user
@cindex user config file
@cindex config file, overview
A user configuration file ties together all the parts of a project
in one place.
@ -862,8 +866,10 @@ One of the following will match your situation best:
@item Ideally almost everything comes from configuration files
provided by someone else.
For example, OpenOCD distributes a @file{scripts} directory
(probably in @file{/usr/share/openocd/scripts} on Linux);
board and tool vendors can provide these too.
(probably in @file{/usr/share/openocd/scripts} on Linux).
Board and tool vendors can provide these too, as can individual
user sites; the @option{-s} command line option lets you say
where to find these files. (@xref{Running}.)
The AT91SAM7X256 example above works this way.
Three main types of non-user configuration file each have their
@ -1003,15 +1009,12 @@ involving considerably more than just a three stage bootloader.
@node Config File Guidelines
@chapter Config File Guidelines
This section/chapter is aimed at developers and integrators of
OpenOCD. These are guidelines for creating new boards and new target
configurations as of 28/Nov/2008.
This chapter is aimed at any user who needs to write a config file,
including developers and integrators of OpenOCD and any user who
needs to get a new board working smoothly.
It provides guidelines for creating those files.
However, you, the user of OpenOCD, should be somewhat familiar with
this section as it should help explain some of the internals of what
you might be looking at.
The user should find the following directories under @t{$(INSTALLDIR)/lib/openocd} :
You should find the following directories under @t{$(INSTALLDIR)/lib/openocd} :
@itemize @bullet
@item @b{interface}
@ -1033,43 +1036,43 @@ When a chip has multiple TAPs (maybe it has both ARM and DSP cores),
the target config file defines all of them.
@end itemize
@b{If needed...} The user in their ``openocd.cfg'' file or the board
file might override a specific feature in any of the above files by
setting a variable or two before sourcing the target file. Or adding
various commands specific to their situation.
The @file{openocd.cfg} user config
file may override features in any of the above files by
setting variables before sourcing the target file, or by adding
commands specific to their situation.
@section Interface Config Files
@cindex config file
The user should be able to source one of these files via a command like this:
The user config file
should be able to source one of these files via a command like this:
@example
source [find interface/FOOBAR.cfg]
Or:
openocd -f interface/FOOBAR.cfg
source [find interface/FOOBAR.cfg]
@end example
A preconfigured interface file should exist for every interface in use
today, that said, perhaps some interfaces have only been used by the
sole developer who created it.
A separate chapter gives information about how to set these up.
@xref{Interface - Dongle Configuration}.
Read the OpenOCD source code if you have a new kind of hardware interface
and need to provide a driver for it.
Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
@section Board Config Files
@cindex config file
@cindex config file, board
@cindex board config file
@b{Note: BOARD directory NEW as of 28/nov/2008}
The user should be able to source one of these files via a command like this:
The user config file
should be able to source one of these files via a command like this:
@example
source [find board/FOOBAR.cfg]
Or:
openocd -f board/FOOBAR.cfg
source [find board/FOOBAR.cfg]
@end example
The board file should contain one or more @t{source [find
The board config file should contain one or more @command{source [find
target/FOO.cfg]} statements along with any board specific things.
In summary the board files should contain (if present)
@ -1085,14 +1088,14 @@ In summary the board files should contain (if present)
@end enumerate
@section Target Config Files
@cindex config file
@cindex config file, target
@cindex target config file
The user should be able to source one of these files via a command like this:
Board config files should be able to source one or more
target config files via a command like this:
@example
source [find target/FOOBAR.cfg]
Or:
openocd -f target/FOOBAR.cfg
source [find target/FOOBAR.cfg]
@end example
In summary the target files should contain
@ -1100,23 +1103,41 @@ In summary the target files should contain
@enumerate
@item Set defaults
@item Add TAPs to the scan chain
@item Add CPU targets
@item Add CPU targets (includes GDB support)
@item CPU/Chip/CPU-Core specific features
@item On-Chip flash
@end enumerate
As a rule of thumb, a target file sets up only one chip.
For a microcontroller, that will often include a single TAP,
which is a CPU needing a GDB target; and its on-chip flash.
More complex chips may include multiple TAPs, and the target
config file may need to define them all before OpenOCD
can talk to the chip.
For example, some phone chips have JTAG scan chains that include
an ARM core for operating system use, a DSP,
another ARM core embedded in an image processing engine,
and other processing engines.
@subsection Important variable names
By default, the end user should never need to set these
variables. However, if the user needs to override a setting they only
need to set the variable in a simple way.
Most boards will have only one instance of a chip.
However, it should be easy to create a board with more than
one such chip.
Accordingly, we encourage some conventions for naming
variables associated with different TAPs, to promote
consistency and
so that board files can override target defaults, and
@itemize @bullet
@item @b{CHIPNAME}
@* This gives a name to the overall chip, and is used as part of the
tap identifier dotted name.
It's normally provided by the chip manufacturer.
@item @b{ENDIAN}
@* By default little - unless the chip or board is not normally used that way.
Chips that can't change endianness don't need to use this variable.
@item @b{CPUTAPID}
@* When OpenOCD examines the JTAG chain, it will attempt to identify
every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
@ -1142,22 +1163,15 @@ specific to that board and that target.
If the chip has 2 targets, use the names @b{_TARGETNAME0},
@b{_TARGETNAME1}, ... etc.
@b{Remember:} The ``board file'' may include multiple targets.
At no time should the name ``target0'' (the default target name if
none was specified) be used. The name ``target0'' is a hard coded name
- the next target on the board will be some other number.
In the same way, avoid using target numbers even when they are
permitted; use the right target name(s) for your board.
The user (or board file) should reasonably be able to:
@emph{Remember:} The ``board file'' may include multiple targets.
The user (or board) config file should reasonably be able to:
@example
source [find target/FOO.cfg]
$_TARGETNAME configure ... FOO specific parameters
source [find target/FOO.cfg]
$_TARGETNAME configure ... FOO specific parameters
source [find target/BAR.cfg]
$_TARGETNAME configure ... BAR specific parameters
source [find target/BAR.cfg]
$_TARGETNAME configure ... BAR specific parameters
@end example
@end itemize
@ -1169,7 +1183,7 @@ Thus the rule we follow in OpenOCD is this: Variables that begin with
a leading underscore are temporary in nature, and can be modified and
used at will within a ?TARGET? configuration file.
@b{EXAMPLE:} The user should be able to do this:
@b{EXAMPLE:} The user config file should be able to do this:
@example
# Board has 3 chips,
@ -1359,7 +1373,7 @@ needed. We welcome JIM Tcl improvements, not bloat.
@item @b{Scripts}
@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
command interpreter today (28/nov/2008) is a mixture of (newer)
command interpreter today is a mixture of (newer)
JIM-Tcl commands, and (older) the orginal command interpreter.
@item @b{Commands}
@ -1566,6 +1580,9 @@ MMU: disabled, D-Cache: disabled, I-Cache: enabled
@node Interface - Dongle Configuration
@chapter Interface - Dongle Configuration
@cindex config file, interface
@cindex interface config file
JTAG Adapters/Interfaces/Dongles are normally configured
through commands in an interface configuration
file which is sourced by your @file{openocd.cfg} file, or
@ -2138,6 +2155,7 @@ which sets up CPUs and exports them as GDB targets,
probes flash memory, performs low-level JTAG operations, and more.
@section Scan Chains
@cindex scan chain
TAPs are part of a hardware @dfn{scan chain},
which is daisy chain of TAPs.
@ -2232,6 +2250,7 @@ each TAP's instruction register can also change.
@c (on entry to RESET state).
@section TAP Names
@cindex dotted name
When TAP objects are declared with @command{jtag newtap},
a @dfn{dotted.name} is created for the TAP, combining the
@ -2330,6 +2349,8 @@ ID code could appear (for example, multiple versions).
@anchor{Enabling and Disabling TAPs}
@section Enabling and Disabling TAPs
@cindex TAP events
@cindex JTAG Route Controller
@cindex jrc
In some systems, a @dfn{JTAG Route Controller} (JRC)
is used to enable and/or disable specific JTAG TAPs.
@ -2422,6 +2443,8 @@ We'll start by looking at how to examine the targets you have,
then look at how to add one more target and how to configure it.
@section Target List
@cindex target, current
@cindex target, list
All targets that have been set up are part of a list,
where each member has a name.
@ -2498,6 +2521,9 @@ only relevant on boards which have more than one target.
@end deffn
@section Target CPU Types and Variants
@cindex target type
@cindex CPU type
@cindex CPU variant
Each target has a @dfn{CPU type}, as shown in the output of
the @command{targets} command. You need to specify that type
@ -2979,12 +3005,6 @@ used. (SPI flash must also be copied to memory before use.)
However, the documentation also uses ``flash'' as a generic term;
for example, ``Put flash configuration in board-specific files''.
@quotation Note
As of 28-nov-2008 OpenOCD does not know how to program a SPI
flash that a micro may boot from. Perhaps you, the reader, would like to
contribute support for this.
@end quotation
Flash Steps:
@enumerate
@item Configure via the command @command{flash bank}
@ -4012,8 +4032,12 @@ If @var{n} (from 0..3) is provided, then set it to that level.
This affects the kind of messages sent to the server log.
Level 0 is error messages only;
level 1 adds warnings;
level 2 (the default) adds informational messages;
level 2 adds informational messages;
and level 3 adds debugging messages.
The default is level 2, but that can be overridden on
the command line along with the location of that log
file (which is normally the server's standard output).
@xref{Running}.
@end deffn
@deffn Command fast (@option{enable}|@option{disable})
@ -4057,7 +4081,7 @@ the initial log output channel is stderr.
In this section ``target'' refers to a CPU configured as
shown earlier (@pxref{CPU Configuration}).
These commands, like many, implicitly refer to
a @dfn{current target} which is used to perform the
a current target which is used to perform the
various operations. The current target may be changed
by using @command{targets} command with the name of the
target which should become current.
@ -5743,8 +5767,8 @@ is a string}
parsed, but are NOT expanded or executed. @{Curly-Braces@} are like
'single-quote' operators in BASH shell scripts, with the added
feature: @{curly-braces@} can be nested, single quotes can not. @{@{@{this is
nested 3 times@}@}@} NOTE: [date] is perhaps a bad example, as of
28/nov/2008, Jim/OpenOCD does not have a date command.
nested 3 times@}@}@} NOTE: [date] is a bad example;
at this writing, Jim/OpenOCD does not have a date command.
@end itemize
@section Consequences of Rule 1/2/3/4
@ -5967,7 +5991,7 @@ $VARS and [square-brackets] are expanded later, when the EVENT occurs,
and the text is evaluated. In case #4, they are replaced before the
``Target Object Command'' is executed. This occurs at the same time
$_TARGETNAME is replaced. In case #4 the date will never
change. @{BTW: [date] is perhaps a bad example, as of 28/nov/2008,
change. @{BTW: [date] is a bad example; at this writing,
Jim/OpenOCD does not have a date command@}
@end enumerate
@subsection Global Variables