git-svn-id: svn://svn.berlios.de/openocd/trunk@2744 b42882b7-edfa-0310-969c-e2dbd0fdcd60tags/v0.3.0-rc0
@@ -16,7 +16,7 @@ possible using a Cygwin host. | |||
Basic Installation | |||
================== | |||
OpenOCD is distributed without autotools generated files, i.e. without a | |||
OpenOCD is distributed without autotools generated files, i.e. without a | |||
configure script. Run ./bootstrap in the openocd directory to have all | |||
necessary files generated. | |||
@@ -77,7 +77,7 @@ The simplest way to compile this package is: | |||
documentation. | |||
4. You can remove the program binaries and object files from the | |||
source code directory by typing `make clean'. | |||
source code directory by typing `make clean'. | |||
Compilers and Options | |||
===================== | |||
@@ -7,7 +7,7 @@ FMI, etc.). | |||
The Flash module provides the following APIs: | |||
- @subpage flashcfi | |||
- @subpage flashcfi | |||
- @subpage flashnand | |||
- @subpage flashtarget | |||
@@ -32,7 +32,7 @@ asynchronous transactions. | |||
- includes the Cable/TAP API (commands starting with @c tap_) | |||
- @subpage jtagdriver | |||
- @b private minidriver API | |||
- @b private minidriver API | |||
- declared in @c src/jtag/minidriver.h | |||
- used @a only by the core and minidriver implementations: | |||
- @c jtag_driver.c (in-tree OpenOCD drivers) | |||
@@ -144,7 +144,7 @@ implement new checks. | |||
The <code>make distcheck</code> command produces an archive of the | |||
project deliverables (using <code>make dist</code>) and verifies its | |||
integrity for distribution by attemptng to use the package in the same | |||
manner as a user. | |||
manner as a user. | |||
These checks includes the following steps: | |||
-# Unpack the project archive into its expected directory. | |||
@@ -90,7 +90,7 @@ provide detailed documentation for each option. | |||
To support out-of-tree building of the documentation, the @c Doxyfile.in | |||
@c INPUT values will have all instances of the string @c "@srcdir@" | |||
replaced with the current value of the make variable | |||
<code>$(srcdir)</code>. The Makefile uses a rule to convert | |||
<code>$(srcdir)</code>. The Makefile uses a rule to convert | |||
@c Doxyfile.in into the @c Doxyfile used by <code>make doxygen</code>. | |||
@section primerdoxyoocd OpenOCD Input Files | |||
@@ -105,7 +105,7 @@ that can be found under the @c doc/manual directory in the project tree. | |||
New files containing valid Doxygen markup that are placed in or under | |||
that directory will be detected and included in The Manual automatically. | |||
@section primerdoxyman Doxygen Reference Manual | |||
@section primerdoxyman Doxygen Reference Manual | |||
The full documentation for Doxygen can be referenced on-line at the project | |||
home page: http://www.doxygen.org/index.html. In HTML versions of this | |||
@@ -1,14 +1,14 @@ | |||
/** @page primerjtag OpenOCD JTAG Primer | |||
JTAG is unnecessarily confusing, because JTAG is often confused with | |||
JTAG is unnecessarily confusing, because JTAG is often confused with | |||
boundary scan, which is just one of its possible functions. | |||
JTAG is simply a communication interface designed to allow communication | |||
to functions contained on devices, for the designed purposes of | |||
initialisation, programming, testing, debugging, and anything else you | |||
JTAG is simply a communication interface designed to allow communication | |||
to functions contained on devices, for the designed purposes of | |||
initialisation, programming, testing, debugging, and anything else you | |||
want to use it for (as a chip designer). | |||
Think of JTAG as I2C for testing. It doesn't define what it can do, | |||
Think of JTAG as I2C for testing. It doesn't define what it can do, | |||
just a logical interface that allows a uniform channel for communication. | |||
See @par | |||
@@ -17,42 +17,42 @@ See @par | |||
and @par | |||
http://www.inaccessnetworks.com/projects/ianjtag/jtag-intro/jtag-state-machine-large.png | |||
The first page (among other things) shows a logical representation | |||
describing how multiple devices are wired up using JTAG. JTAG does not | |||
specify, data rates or interface levels (3.3V/1.8V, etc) each device can | |||
support different data rates/interface logic levels. How to wire them | |||
The first page (among other things) shows a logical representation | |||
describing how multiple devices are wired up using JTAG. JTAG does not | |||
specify, data rates or interface levels (3.3V/1.8V, etc) each device can | |||
support different data rates/interface logic levels. How to wire them | |||
in a compatible way is an exercise for an engineer. | |||
Basically TMS controls which shift register is placed on the device, | |||
between TDI and TDO. The second diagram shows the state transitions on | |||
Basically TMS controls which shift register is placed on the device, | |||
between TDI and TDO. The second diagram shows the state transitions on | |||
TMS which will select different shift registers. | |||
The first thing you need to do is reset the state machine, because when | |||
you connect to a chip you do not know what state the controller is in,you need | |||
to clock TMS as 1, at least 7 times. This will put you into "Test Logic | |||
Reset" State. Knowing this, you can, once reset, then track what each | |||
transition on TMS will do, and hence know what state the JTAG state | |||
The first thing you need to do is reset the state machine, because when | |||
you connect to a chip you do not know what state the controller is in,you need | |||
to clock TMS as 1, at least 7 times. This will put you into "Test Logic | |||
Reset" State. Knowing this, you can, once reset, then track what each | |||
transition on TMS will do, and hence know what state the JTAG state | |||
machine is in. | |||
There are 2 "types" of shift registers. The Instruction shift register | |||
and the data shift register. The sizes of these are undefined, and can | |||
change from chip to chip. The Instruction register is used to select | |||
which Data register/data register function is used, and the data | |||
There are 2 "types" of shift registers. The Instruction shift register | |||
and the data shift register. The sizes of these are undefined, and can | |||
change from chip to chip. The Instruction register is used to select | |||
which Data register/data register function is used, and the data | |||
register is used to read data from that function or write data to it. | |||
Each of the states control what happens to either the data register or | |||
Each of the states control what happens to either the data register or | |||
instruction register. | |||
For example, one of the data registers will be known as "bypass" this is | |||
(usually) a single bit which has no function and is used to bypass the | |||
chip. Assume we have 3 identical chips, wired up like the picture | |||
and each has a 3 bit instruction register, and there are 2 known | |||
instructions (110 = bypass, 010 = some other function) if we want to use | |||
"some other function", on the second chip in the line, and not change | |||
For example, one of the data registers will be known as "bypass" this is | |||
(usually) a single bit which has no function and is used to bypass the | |||
chip. Assume we have 3 identical chips, wired up like the picture | |||
and each has a 3 bit instruction register, and there are 2 known | |||
instructions (110 = bypass, 010 = some other function) if we want to use | |||
"some other function", on the second chip in the line, and not change | |||
the other chips we would do the following transitions. | |||
From Test Logic Reset, TMS goes: | |||
0 1 1 0 0 | |||
which puts every chip in the chain into the "Shift IR state" | |||
@@ -60,7 +60,7 @@ Then (while holding TMS as 0) TDI goes: | |||
0 1 1 0 1 0 0 1 1 | |||
which puts the following values in the instruction shift register for | |||
which puts the following values in the instruction shift register for | |||
each chip [110] [010] [110] | |||
The order is reversed, because we shift out the least significant bit | |||
@@ -70,18 +70,18 @@ first. Then we transition TMS: | |||
which puts us in the "Shift DR state". | |||
Now when we clock data onto TDI (again while holding TMS to 0) , the | |||
data shifts through the data registers, and because of the instruction | |||
registers we selected (some other function has 8 bits in its data | |||
Now when we clock data onto TDI (again while holding TMS to 0) , the | |||
data shifts through the data registers, and because of the instruction | |||
registers we selected (some other function has 8 bits in its data | |||
register), our total data register in the chain looks like this: | |||
0 00000000 0 | |||
The first and last bit are in the "bypassed" chips, so values read from | |||
them are irrelevant and data written to them is ignored. But we need to | |||
The first and last bit are in the "bypassed" chips, so values read from | |||
them are irrelevant and data written to them is ignored. But we need to | |||
write bits for those registers, because they are in the chain. | |||
If we wanted to write 0xF5 to the data register we would clock out of | |||
If we wanted to write 0xF5 to the data register we would clock out of | |||
TDI (holding TMS to 0): | |||
0 1 0 1 0 1 1 1 1 0 | |||
@@ -91,13 +91,13 @@ clock TMS: | |||
1 1 0 | |||
which updates the selected data register with the value 0xF5 and returns | |||
which updates the selected data register with the value 0xF5 and returns | |||
us to run test idle. | |||
If we needed to read the data register before over-writing it with F5, | |||
no sweat, that's already done, because the TDI/TDO are set up as a | |||
circular shift register, so if you write enough bits to fill the shift | |||
register, you will receive the "captured" contents of the data registers | |||
If we needed to read the data register before over-writing it with F5, | |||
no sweat, that's already done, because the TDI/TDO are set up as a | |||
circular shift register, so if you write enough bits to fill the shift | |||
register, you will receive the "captured" contents of the data registers | |||
simultaneously on TDO. | |||
That's JTAG in a nutshell. On top of this, you need to get specs for | |||
@@ -8,7 +8,7 @@ for OpenOCD contributors who are unfamiliar with the process. | |||
The standard method for creating patches requires developers to: | |||
- checkout the Subversion repository (or bring a copy up-to-date), | |||
- make the necessary modifications to a working copy, | |||
- check with 'svn status' to see which files will be modified/added, and | |||
- check with 'svn status' to see which files will be modified/added, and | |||
- use 'svn diff' to review the changes and produce a patch. | |||
It is important to minimize the changes to only those lines that contain | |||
@@ -67,7 +67,7 @@ patch, or you can specified specific files and directories when using | |||
<code>svn diff</code>. Overlapping patches will be discussed in the | |||
next section. | |||
The remainder of this section provides | |||
The remainder of this section provides | |||
@subsection primerpatchprops Subversion Properties | |||
@@ -110,7 +110,7 @@ The following series of commands will work: @par | |||
svn diff foo | unix2dos | patch -R | |||
@endcode | |||
This is not a bug. | |||
This is not a bug. | |||
@todo Does Subversion's treatment of line-endings for files marked with | |||
svn:eol-style=native continue to pose the problems described here, or | |||
@@ -115,7 +115,7 @@ Exception: The arrays. | |||
set x "2 * 6" | |||
set foo([expr $x]) "twelve" | |||
************************************************** | |||
*************************************************** | |||
=== TCL TOUR === | |||
@@ -133,7 +133,7 @@ This means it is evaluated when the file is parsed. | |||
In TCL, "FOR" is a funny thing, it is not what you think it is. | |||
Syntactically - FOR is a just a command, it is not language | |||
construct like for(;;) in C... | |||
construct like for(;;) in C... | |||
The "for" command takes 4 parameters. | |||
(1) The "initial command" to execute. | |||
@@ -215,7 +215,7 @@ All memory regions must have 2 things: | |||
(2) NAME( array ) | |||
And the array must have some specific names: | |||
( <idx>, THING ) | |||
Where: THING is one of: | |||
Where: THING is one of: | |||
CHIPSELECT | |||
BASE | |||
LEN | |||
@@ -224,7 +224,7 @@ All memory regions must have 2 things: | |||
RWX - the access ability. | |||
WIDTH - the accessible width. | |||
ie: Some regions of memory are not 'word' | |||
ie: Some regions of memory are not 'word' | |||
accessible. | |||
The function "address_info" - given an address should | |||
@@ -237,14 +237,14 @@ tell you about the address. | |||
MAJOR FUNCTION: | |||
== | |||
proc memread32 { ADDR } | |||
proc memread16 { ADDR } | |||
proc memread8 { ADDR } | |||
proc memread32 { ADDR } | |||
proc memread16 { ADDR } | |||
proc memread8 { ADDR } | |||
All read memory - and return the contents. | |||
[ FIXME: 7/5/2008 - I need to create "memwrite" functions] | |||
************************************************** | |||
*************************************************** | |||
=== TCL TOUR === | |||
@@ -265,13 +265,13 @@ In a makefile or shell script you may have seen this: | |||
FOO_linux = "Penguins rule" | |||
FOO_winXP = "Broken Glass" | |||
FOO_mac = "I like cat names" | |||
# Pick one | |||
BUILD = linux | |||
#BUILD = winXP | |||
#BUILD = mac | |||
FOO = ${FOO_${BUILD}} | |||
The "double [set] square bracket" thing is the TCL way, nothing more. | |||
---- | |||
@@ -290,7 +290,7 @@ Notice this IF COMMAND - (not statement) is like this: | |||
The "IF" command expects either 2 params, or 4 params. | |||
=== Sidebar: About "commands" === | |||
Take a look at the internals of "jim.c" | |||
Look for the function: Jim_IfCoreCommand() | |||
And all those other "CoreCommands" | |||
@@ -298,10 +298,10 @@ The "IF" command expects either 2 params, or 4 params. | |||
You'll notice - they all have "argc" and "argv" | |||
Yea, the entire thing is done that way. | |||
IF is a command. SO is "FOR" and "WHILE" and "DO" and the | |||
others. That is why I keep using the phase it is a "command" | |||
=== END: Sidebar: About "commands" === | |||
Parameter 1 to the IF command is expected to be an expression. | |||
@@ -315,7 +315,7 @@ CATCH - is an error catcher. | |||
You give CATCH 1 or 2 parameters. | |||
The first 1st parameter is the "code to execute" | |||
The 2nd (optional) is where to put the error message. | |||
CATCH returns 0 on success, 1 for failure. | |||
The "![catch command]" is self explaintory. | |||
@@ -325,7 +325,7 @@ above, the IF command can take many parameters they just have to | |||
be joined by exactly the words "else" or "elseif". | |||
The 4th parameter contains: | |||
"error [format STRING....]" | |||
This lets me modify the previous lower level error by tacking more | |||
@@ -346,7 +346,7 @@ string, then using "dlopen()" and "dlsym()" to look it up - and get a | |||
function pointer - and calling the function pointer. | |||
In this case - I execute a dynamic command. You can do some cool | |||
tricks with interpretors. | |||
tricks with interpretors. | |||
---------- | |||
@@ -380,7 +380,7 @@ Some assumptions: | |||
The "CHIP" file has defined some variables in a proper form. | |||
ie: AT91C_BASE_US0 - for usart0, | |||
ie: AT91C_BASE_US0 - for usart0, | |||
AT91C_BASE_US1 - for usart1 | |||
... And so on ... | |||
@@ -419,9 +419,9 @@ with the generated list of commands for the entire USART. | |||
With that little bit of code - I now have a bunch of functions like: | |||
show_US0, show_US1, show_US2, .... etc ... | |||
And show_US0_MR, show_US0_IMR ... etc... | |||
And - I have this for every USART... without having to create tons of | |||
boiler plate yucky code. | |||
@@ -113,7 +113,7 @@ tags and incrementing the version. | |||
The OpenOCD release process must be carried out on a periodic basis, so | |||
the project can realize the benefits presented in answer to the question, | |||
@ref releasewhy. | |||
@ref releasewhy. | |||
Starting with the 0.2.0 release, the OpenOCD project should produce a | |||
new minor release every month or two, with a major release once a year. | |||
@@ -132,7 +132,7 @@ beginning of the development cycle through the delivery of the new | |||
release. This section presents guidelines for scheduling key points | |||
where the community must be informed of changing conditions. | |||
If T is the time of the next release, then the following schedule | |||
If T is the time of the next release, then the following schedule | |||
might describe some of the key milestones of the new release cycle: | |||
- T minus one month: start of new development cycle | |||
@@ -190,7 +190,7 @@ Even with the release script, some steps require clear user intervention | |||
The following steps should be followed to produce each release: | |||
-# Produce final patches to the trunk (or release branch): | |||
-# Finalize @c NEWS file to describe the changes in the release | |||
-# Finalize @c NEWS file to describe the changes in the release | |||
- This file is Used to automatically post "blurbs" about the project. | |||
- This material should be produced during the development cycle. | |||
- Add a new item for each @c NEWS-worthy contribution, when committed. | |||
@@ -208,7 +208,7 @@ svn cp .../trunk .../branches/${RELEASE_BRANCH} | |||
svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG} | |||
@endverbatim | |||
- For bug-fix releases produced in their respective branch, a tag | |||
should be created in the repository: | |||
should be created in the repository: | |||
@verbatim | |||
svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG} | |||
@endverbatim | |||
@@ -5,7 +5,7 @@ | |||
The scripting support is intended for developers of OpenOCD. | |||
It is not the intention that normal OpenOCD users will | |||
use tcl scripting extensively, write lots of clever scripts, | |||
or contribute back to OpenOCD. | |||
or contribute back to OpenOCD. | |||
Target scripts can contain new procedures that end users may | |||
tinker to their needs without really understanding tcl. | |||
@@ -31,7 +31,7 @@ Default implementation of procedures in tcl/procedures.tcl. | |||
file format and structure of serialnumber. Tcl allows | |||
an argument to consist of e.g. a list so the structure of | |||
the serial number is not limited to a single string. | |||
- reset handling. Precise control of how srst, trst & | |||
- reset handling. Precise control of how srst, trst & | |||
tms is handled. | |||
- replace some parts of the current command line handler. | |||
This is only to simplify the implementation of OpenOCD | |||
@@ -42,7 +42,7 @@ Default implementation of procedures in tcl/procedures.tcl. | |||
that return machine readable output. These low level tcl | |||
functions constitute the tcl api. flash_banks is such | |||
a low level tcl proc. "flash banks" is an example of | |||
a command that has human readable output. The human | |||
a command that has human readable output. The human | |||
readable output is expected to change inbetween versions | |||
of OpenOCD. The output from flash_banks may not be | |||
in the preferred form for the client. The client then | |||
@@ -50,8 +50,8 @@ Default implementation of procedures in tcl/procedures.tcl. | |||
or b) write a small piece of tcl to output the | |||
flash_banks output to a more suitable form. The latter may | |||
be simpler. | |||
@section scriptingexternal External scripting | |||
The embedded Jim Tcl interpreter in OpenOCD is very limited | |||
@@ -32,14 +32,14 @@ high-level interface to OpenOCD, because they only had two choices: | |||
- the ablity to write a complex internal commands: native 'commands' | |||
inside of OpenOCD was complicated. | |||
Fundamentally, the basic problem with both of those would be solved | |||
Fundamentally, the basic problem with both of those would be solved | |||
with a script language: | |||
-# <b>Internal</b>: simple, small, and self-contained. | |||
-# <b>Cross Language</b>: script friendly front-end | |||
-# <b>Cross Host</b>: GUI Host interface | |||
-# <b>Cross Debugger</b>: GUI-like interface | |||
What follows hopefully shows how the plans to solve these problems | |||
materialized and help to explain the grand roadmap plan. | |||
@@ -64,7 +64,7 @@ file, allowing OpenOCD to avoid the spider web of dependent packages. | |||
The TCL Server port was added in mid-2008. With embedded TCL, we can | |||
write scripts internally to help things, or we can write "C" code that | |||
interfaces well with TCL. | |||
interfaces well with TCL. | |||
From there, the developers wanted to create an external front-end that | |||
would be @a very usable and that that @a any language could utilize, | |||
@@ -81,7 +81,7 @@ terse, simple ASCII protocols that are emensely parsable by a script. | |||
Thus, the TCL server -- a 'machine' type socket interface -- was added | |||
with the hope was it would output simple "name-value" pair type | |||
data. At the time, simple name/value pairs seemed reasonably easier to | |||
do at the time, though Maybe it should output JSON; | |||
do at the time, though Maybe it should output JSON; | |||
See here: | |||
@@ -101,11 +101,11 @@ How do we solve that problem? | |||
For example, Cygwin can be painful, Cygwin GUI packages want X11 | |||
to be present, crossing the barrier between MinGW and Cygwin is | |||
painful, let alone getting the GUI front end to work on MacOS, and | |||
Linux, yuck yuck yuck. Painful. very very painful. | |||
Linux, yuck yuck yuck. Painful. very very painful. | |||
What works easier and is less work is what is already present in every | |||
platform? The answer: A web browser. In other words, OpenOCD could | |||
serve out embedded web pages via "localhost" to your browser. | |||
serve out embedded web pages via "localhost" to your browser. | |||
Long before OpenOCD had a TCL command line, Zylin AS built their ZY1000 | |||
devince with a built-in HTTP server. Later, they were willing to both | |||
@@ -169,7 +169,7 @@ the Socket Approach is used. | |||
During 2008, Duane Ellis created some TCL scripts to display peripheral | |||
register contents. For example, look at the sam7 TCL scripts, and the | |||
stm32 TCL scripts. The hope was others would create more. | |||
stm32 TCL scripts. The hope was others would create more. | |||
A good example of this is display/view the peripheral registers on | |||
@@ -215,7 +215,7 @@ One reason might be, this adds one more host side requirement to make | |||
use of the feature. In other words, one could write a Python/TK | |||
front-end, but it is only useable if you have Python/TK installed. | |||
Maybe this can be done via Ecllipse, but not all developers use Ecplise. | |||
Many devlopers use Emacs (possibly with GUD mode) or vim and will not | |||
Many devlopers use Emacs (possibly with GUD mode) or vim and will not | |||
accept such an interface. The next developer reading this might be | |||
using Insight (GDB-TK) - and somebody else - DDD.. | |||
@@ -149,7 +149,7 @@ comments. | |||
* in blocks such as the one in which this example appears in the Style | |||
* Guide. See the Doxygen Manual for the full list of commands. | |||
* | |||
* @param foo For a function, describe the parameters (e.g. @a foo). | |||
* @param foo For a function, describe the parameters (e.g. @a foo). | |||
* @returns The value(s) returned, or possible error conditions. | |||
*/ | |||
@endverbatim | |||
@@ -229,7 +229,7 @@ This file contains the @ref pagename page. | |||
@endverbatim | |||
For an example, the Doxygen source for this Style Guide can be found in | |||
@c doc/manual/style.txt, alongside other parts of The Manual. | |||
@c doc/manual/style.txt, alongside other parts of The Manual. | |||
*/ | |||
/** @page styletexinfo Texinfo Style Guide | |||
@@ -344,7 +344,7 @@ Likewise, the @ref primerlatex for using this guide needs to be completed. | |||
This page provides some style guidelines for using Perl, a scripting | |||
language used by several small tools in the tree: | |||
-# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and | |||
-# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and | |||
@c .pm for modules) | |||
-# Pass files as script parameters or piped as input: | |||
- Do NOT code paths to files in the tree, as this breaks out-of-tree builds. | |||
@@ -37,7 +37,7 @@ mailing list | |||
@section targetnotarmsupport Target Support | |||
target.h is relatively CPU agnostic and | |||
the intention is to move in the direction of less | |||
the intention is to move in the direction of less | |||
instruction set specific. | |||
Non-CPU targets are also supported, but there isn't | |||
@@ -56,7 +56,7 @@ OpenOCD does not today have targets that use non-JTAG. | |||
The actual physical layer is a relatively modest part | |||
of the total OpenOCD system. | |||
@section targetnotarmppc PowerPC | |||
there exists open source implementations of powerpc | |||
@@ -8,19 +8,19 @@ boundary\-scan testing tool for ARM and MIPS systems | |||
.B OpenOCD | |||
is an on\-chip debugging, in\-system programming and boundary\-scan | |||
testing tool for various ARM and MIPS systems. | |||
.PP | |||
.PP | |||
The debugger uses an IEEE 1149\-1 compliant JTAG TAP bus master to access | |||
on\-chip debug functionality available on ARM based microcontrollers or | |||
system-on-chip solutions. For MIPS systems the EJTAG interface is supported. | |||
.PP | |||
.PP | |||
User interaction is realized through a telnet command line interface, | |||
a gdb (the GNU debugger) remote protocol server, and a simplified RPC | |||
connection that can be used to interface with OpenOCD's Jim Tcl engine. | |||
.PP | |||
.PP | |||
OpenOCD supports various different types of JTAG interfaces/programmers, | |||
please check the \fIopenocd\fR info page for the complete list. | |||
.SH "OPTIONS" | |||
.TP | |||
.TP | |||
.B "\-f, \-\-file <filename>" | |||
Use configuration file | |||
.BR <filename> . | |||
@@ -29,43 +29,43 @@ In order to specify multiple config files, you can use multiple | |||
arguments. If this option is omitted, the config file | |||
.B openocd.cfg | |||
in the current working directory will be used. | |||
.TP | |||
.TP | |||
.B "\-s, \-\-search <dirname>" | |||
Search for config files and scripts in the directory | |||
.BR <dirname> . | |||
If this option is omitted, OpenOCD searches for config files and scripts | |||
in the current directory. | |||
.TP | |||
.TP | |||
.B "\-d, \-\-debug <debuglevel>" | |||
Set debug level. Possible values are: | |||
.br | |||
.br | |||
.RB " * " 0 " (errors)" | |||
.br | |||
.br | |||
.RB " * " 1 " (warnings)" | |||
.br | |||
.br | |||
.RB " * " 2 " (informational messages)" | |||
.br | |||
.br | |||
.RB " * " 3 " (debug messages)" | |||
.br | |||
.br | |||
The default level is | |||
.BR 2 . | |||
.TP | |||
.TP | |||
.B "\-l, \-\-log_output <filename>" | |||
Redirect log output to the file | |||
.BR <filename> . | |||
Per default the log output is printed on | |||
.BR stderr . | |||
.TP | |||
.TP | |||
.B "\-c, \-\-command <cmd>" | |||
Run the command | |||
.BR <cmd> . | |||
.TP | |||
.TP | |||
.B "\-p, \-\-pipe" | |||
Use pipes when talking to gdb. | |||
.TP | |||
.TP | |||
.B "\-h, \-\-help" | |||
Show a help text and exit. | |||
.TP | |||
.TP | |||
.B "\-v, \-\-version" | |||
Show version information and exit. | |||
.SH "BUGS" | |||
@@ -95,6 +95,6 @@ Also, the OpenOCD wiki contains some more information and examples: | |||
.B http://openfacts.berlios.de/index-en.phtml?title=Open_On-Chip_Debugger | |||
.SH "AUTHORS" | |||
Please see the file AUTHORS. | |||
.PP | |||
.PP | |||
This manual page was written by Uwe Hermann <uwe@hermann\-uwe.de>. | |||
It is licensed under the terms of the GNU GPL (version 2 or later). |
@@ -252,7 +252,7 @@ and has a built in relay to power cycle targets remotely. | |||
There are several things you should keep in mind when choosing a dongle. | |||
@enumerate | |||
@enumerate | |||
@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V? | |||
Does your dongle support it? You might need a level converter. | |||
@item @b{Pinout} What pinout does your target board use? | |||
@@ -260,7 +260,7 @@ Does your dongle support it? You may be able to use jumper | |||
wires, or an "octopus" connector, to convert pinouts. | |||
@item @b{Connection} Does your computer have the USB, printer, or | |||
Ethernet port needed? | |||
@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking'' | |||
@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking'' | |||
@end enumerate | |||
@section Stand alone Systems | |||
@@ -344,7 +344,7 @@ Raisonance has an adapter called @b{RLink}. It exists in a stripped-down form o | |||
@item @b{USBprog} | |||
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604 | |||
@item @b{USB - Presto} | |||
@item @b{USB - Presto} | |||
@* Link: @url{http://tools.asix.net/prg_presto.htm} | |||
@item @b{Versaloon-Link} | |||
@@ -2098,7 +2098,7 @@ haven't seen hardware with such a bug, and can be worked around). | |||
@option{srst_gates_jtag} indicates that asserting SRST gates the | |||
JTAG clock. This means that no communication can happen on JTAG | |||
while SRST is asserted. | |||
while SRST is asserted. | |||
The optional @var{trst_type} and @var{srst_type} parameters allow the | |||
driver mode of each reset line to be specified. These values only affect | |||
@@ -4359,7 +4359,7 @@ individually overridden. | |||
The target specific "dangerous" optimisation tweaking options may come and go | |||
as more robust and user friendly ways are found to ensure maximum throughput | |||
and robustness with a minimum of configuration. | |||
and robustness with a minimum of configuration. | |||
Typically the "fast enable" is specified first on the command line: | |||
@@ -4919,7 +4919,7 @@ those instructions are not currently understood by OpenOCD.) | |||
@deffn Command {armv4_5 reg} | |||
Display a table of all banked core registers, fetching the current value from every | |||
core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current | |||
register value. | |||
register value. | |||
@end deffn | |||
@subsection ARM7 and ARM9 specific commands | |||
@@ -4934,7 +4934,7 @@ 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). | |||
safe for all but ARM7TDMI--S cores (like Philips LPC). | |||
This feature is enabled by default on most ARM9 cores, | |||
including ARM9TDMI, ARM920T, and ARM926EJ-S. | |||
@end deffn | |||
@@ -4952,7 +4952,7 @@ with OpenOCD rev. 60, and requires a few bytes of working area. | |||
Enable or disable memory writes and reads that don't check completion of | |||
the operation. This provides a huge speed increase, especially with USB JTAG | |||
cables (FT2232), but might be unsafe if used with targets running at very low | |||
speeds, like the 32kHz startup clock of an AT91RM9200. | |||
speeds, like the 32kHz startup clock of an AT91RM9200. | |||
@end deffn | |||
@deffn {Debug Command} {arm7_9 write_core_reg} num mode word | |||
@@ -5843,7 +5843,7 @@ the following OpenOCD configuration option: | |||
gdb_memory_map disable | |||
@end example | |||
For this to function correctly a valid flash configuration must also be set | |||
in OpenOCD. For faster performance you should also configure a valid | |||
in OpenOCD. For faster performance you should also configure a valid | |||
working area. | |||
Informing GDB of the memory map of the target will enable GDB to protect any | |||
@@ -5887,10 +5887,10 @@ of currently active target, the Tcl API proc's take this sort of state | |||
information as an argument to each proc. | |||
There are three main types of return values: single value, name value | |||
pair list and lists. | |||
pair list and lists. | |||
Name value pair. The proc 'foo' below returns a name/value pair | |||
list. | |||
list. | |||
@verbatim | |||
@@ -5913,7 +5913,7 @@ Thus, to get the names of the associative array is easy: | |||
puts "Name: $name, Value: $value" | |||
} | |||
@end verbatim | |||
Lists returned must be relatively small. Otherwise a range | |||
should be passed in to the proc in question. | |||
@@ -5949,7 +5949,7 @@ Real Tcl has ::tcl_platform(), and platform::identify, and many other | |||
variables. JimTCL, as implemented in OpenOCD creates $HostOS which | |||
holds one of the following values: | |||
@itemize @bullet | |||
@itemize @bullet | |||
@item @b{winxx} Built using Microsoft Visual Studio | |||
@item @b{linux} Linux is the underlying operating sytem | |||
@item @b{darwin} Darwin (mac-os) is the underlying operating sytem. | |||
@@ -6088,7 +6088,7 @@ Imagine debugging a 500MHz ARM926 hand held battery powered device | |||
that ``deep sleeps'' at 32kHz between every keystroke. It can be | |||
painful. | |||
@b{Solution #1 - A special circuit} | |||
@b{Solution #1 - A special circuit} | |||
In order to make use of this, your JTAG dongle must support the RTCK | |||
feature. Not all dongles support this - keep reading! | |||
@@ -6156,7 +6156,7 @@ jtag_khz 1234 | |||
@item @b{Win32 Pathnames} Why don't backslashes work in Windows paths? | |||
OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @} | |||
around Windows filenames. | |||
around Windows filenames. | |||
@example | |||
> echo \a | |||
@@ -6199,7 +6199,7 @@ settings in your PC BIOS (ECP, EPP, and different versions of those). | |||
@item @b{Data Aborts} When debugging with OpenOCD and GDB (plain GDB, Insight, or Eclipse), | |||
I get lots of "Error: arm7_9_common.c:1771 arm7_9_read_memory(): | |||
memory read caused data abort". | |||
memory read caused data abort". | |||
The errors are non-fatal, and are the result of GDB trying to trace stack frames | |||
beyond the last valid frame. It might be possible to prevent this by setting up | |||
@@ -6220,7 +6220,7 @@ remember to pop them off when the ISR is done. | |||
@b{Also note:} If you have a multi-threaded operating system, they | |||
often do not @b{in the intrest of saving memory} waste these few | |||
bytes. Painful... | |||
bytes. Painful... | |||
@item @b{JTAG Reset Config} I get the following message in the OpenOCD console (or log file): | |||
@@ -6342,7 +6342,7 @@ TODO. | |||
@node Tcl Crash Course | |||
@chapter Tcl Crash Course | |||
@cindex Tcl | |||
@cindex Tcl | |||
Not everyone knows Tcl - this is not intended to be a replacement for | |||
learning Tcl, the intent of this chapter is to give you some idea of | |||
@@ -6461,7 +6461,7 @@ control flow operators. | |||
Commands are executed like this: | |||
@enumerate | |||
@enumerate | |||
@item Parse the next line into (argc) and (argv[]). | |||
@item Look up (argv[0]) in a table and call its function. | |||
@item Repeat until End Of File. | |||
@@ -6609,7 +6609,7 @@ substituted on the orginal command line. | |||
@enumerate | |||
@item The SET command creates 2 variables, X and Y. | |||
@item The double [nested] EXPR command performs math | |||
@* The EXPR command produces numerical result as a string. | |||
@* The EXPR command produces numerical result as a string. | |||
@* Refer to Rule #1 | |||
@item The format command is executed, producing a single string | |||
@* Refer to Rule #1. | |||
@@ -6632,7 +6632,7 @@ substituted on the orginal command line. | |||
#4 DANGER DANGER DANGER | |||
$_TARGETNAME configure -event foo "puts \"Time: [date]\"" | |||
@end example | |||
@enumerate | |||
@enumerate | |||
@item The $_TARGETNAME is an OpenOCD variable convention. | |||
@*@b{$_TARGETNAME} represents the last target created, the value changes | |||
each time a new target is created. Remember the parsing rules. When | |||
@@ -6699,9 +6699,9 @@ foreach who @{A B C D E@} | |||
OpenOCD comes with a target configuration script library. These scripts can be | |||
used as-is or serve as a starting point. | |||
The target library is published together with the OpenOCD executable and | |||
The target library is published together with the OpenOCD executable and | |||
the path to the target library is in the OpenOCD script search path. | |||
Similarly there are example scripts for configuring the JTAG interface. | |||
Similarly there are example scripts for configuring the JTAG interface. | |||
The command line below uses the example parport configuration script | |||
that ship with OpenOCD, then configures the str710.cfg target and | |||