15 files changed:
Basic Installation
==================
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.
configure script. Run ./bootstrap in the openocd directory to have all
necessary files generated.
documentation.
4. You can remove the program binaries and object files from the
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
=====================
Compilers and Options
=====================
The Flash module provides the following APIs:
The Flash module provides the following APIs:
- @subpage flashnand
- @subpage flashtarget
- @subpage flashnand
- @subpage flashtarget
- includes the Cable/TAP API (commands starting with @c tap_)
- @subpage jtagdriver
- 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)
- declared in @c src/jtag/minidriver.h
- used @a only by the core and minidriver implementations:
- @c jtag_driver.c (in-tree OpenOCD drivers)
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
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
These checks includes the following steps:
-# Unpack the project archive into its expected directory.
These checks includes the following steps:
-# Unpack the project archive into its expected directory.
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
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
@c Doxyfile.in into the @c Doxyfile used by <code>make doxygen</code>.
@section primerdoxyoocd OpenOCD Input Files
New files containing valid Doxygen markup that are placed in or under
that directory will be detected and included in The Manual automatically.
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
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
/** @page primerjtag OpenOCD JTAG Primer
/** @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.
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).
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
just a logical interface that allows a uniform channel for communication.
See @par
and @par
http://www.inaccessnetworks.com/projects/ianjtag/jtag-intro/jtag-state-machine-large.png
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.
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.
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
-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.
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
-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:
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"
0 1 1 0 0
which puts every chip in the chain into the "Shift IR state"
-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
each chip [110] [010] [110]
The order is reversed, because we shift out the least significant bit
which puts us in the "Shift DR state".
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
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.
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
TDI (holding TMS to 0):
0 1 0 1 0 1 1 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
-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
simultaneously on TDO.
That's JTAG in a nutshell. On top of this, you need to get specs for
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,
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
- use 'svn diff' to review the changes and produce a patch.
It is important to minimize the changes to only those lines that contain
<code>svn diff</code>. Overlapping patches will be discussed in the
next section.
<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
@subsection primerpatchprops Subversion Properties
svn diff foo | unix2dos | patch -R
@endcode
svn diff foo | unix2dos | patch -R
@endcode
@todo Does Subversion's treatment of line-endings for files marked with
svn:eol-style=native continue to pose the problems described here, or
@todo Does Subversion's treatment of line-endings for files marked with
svn:eol-style=native continue to pose the problems described here, or
set x "2 * 6"
set foo([expr $x]) "twelve"
set x "2 * 6"
set foo([expr $x]) "twelve"
**************************************************
***************************************************
=== TCL TOUR ===
**************************************************
***************************************************
=== TCL TOUR ===
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
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.
The "for" command takes 4 parameters.
(1) The "initial command" to execute.
(2) NAME( array )
And the array must have some specific names:
( <idx>, THING )
(2) NAME( array )
And the array must have some specific names:
( <idx>, THING )
- Where: THING is one of:
+ Where: THING is one of:
RWX - the access ability.
WIDTH - the accessible width.
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
accessible.
The function "address_info" - given an address should
-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]
All read memory - and return the contents.
[ FIXME: 7/5/2008 - I need to create "memwrite" functions]
**************************************************
***************************************************
=== TCL TOUR ===
**************************************************
***************************************************
=== TCL TOUR ===
FOO_linux = "Penguins rule"
FOO_winXP = "Broken Glass"
FOO_mac = "I like cat names"
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}}
# Pick one
BUILD = linux
#BUILD = winXP
#BUILD = mac
FOO = ${FOO_${BUILD}}
The "double [set] square bracket" thing is the TCL way, nothing more.
----
The "double [set] square bracket" thing is the TCL way, nothing more.
----
The "IF" command expects either 2 params, or 4 params.
=== Sidebar: About "commands" ===
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"
Take a look at the internals of "jim.c"
Look for the function: Jim_IfCoreCommand()
And all those other "CoreCommands"
You'll notice - they all have "argc" and "argv"
Yea, the entire thing is done that way.
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"
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.
=== END: Sidebar: About "commands" ===
Parameter 1 to the IF command is expected to be an expression.
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.
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.
CATCH returns 0 on success, 1 for failure.
The "![catch command]" is self explaintory.
be joined by exactly the words "else" or "elseif".
The 4th parameter contains:
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
"error [format STRING....]"
This lets me modify the previous lower level error by tacking more
function pointer - and calling the function pointer.
In this case - I execute a dynamic command. You can do some cool
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.
The "CHIP" file has defined some variables in a proper form.
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 ...
AT91C_BASE_US1 - for usart1
... And so on ...
With that little bit of code - I now have a bunch of functions like:
show_US0, show_US1, show_US2, .... etc ...
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 show_US0_MR, show_US0_IMR ... etc...
And - I have this for every USART... without having to create tons of
boiler plate yucky code.
And - I have this for every USART... without having to create tons of
boiler plate yucky code.
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,
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,
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.
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.
release. This section presents guidelines for scheduling key points
where the community must be informed of changing conditions.
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
might describe some of the key milestones of the new release cycle:
- T minus one month: start of new development cycle
The following steps should be followed to produce each release:
-# Produce final patches to the trunk (or release branch):
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.
- 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.
svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
@endverbatim
- For bug-fix releases produced in their respective branch, a tag
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
@verbatim
svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
@endverbatim
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,
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.
Target scripts can contain new procedures that end users may
tinker to their needs without really understanding 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.
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
tms is handled.
- replace some parts of the current command line handler.
This is only to simplify the implementation of OpenOCD
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
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
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
or b) write a small piece of tcl to output the
flash_banks output to a more suitable form. The latter may
be simpler.
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
@section scriptingexternal External scripting
The embedded Jim Tcl interpreter in OpenOCD is very limited
- the ablity to write a complex internal commands: native 'commands'
inside of OpenOCD was complicated.
- 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
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.
What follows hopefully shows how the plans to solve these problems
materialized and help to explain the grand roadmap plan.
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
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,
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,
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
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;
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
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
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
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
During 2008, Duane Ellis created some TCL scripts to display peripheral
register contents. For example, look at the sam7 TCL scripts, and the
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
A good example of this is display/view the peripheral registers on
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.
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..
accept such an interface. The next developer reading this might be
using Insight (GDB-TK) - and somebody else - DDD..
* 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.
*
* 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
* @returns The value(s) returned, or possible error conditions.
*/
@endverbatim
@endverbatim
For an example, the Doxygen source for this Style Guide can be found in
@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
*/
/** @page styletexinfo Texinfo Style Guide
This page provides some style guidelines for using Perl, a scripting
language used by several small tools in the tree:
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.
@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.
@section targetnotarmsupport Target Support
target.h is relatively CPU agnostic and
@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
instruction set specific.
Non-CPU targets are also supported, but there isn't
The actual physical layer is a relatively modest part
of the total OpenOCD system.
The actual physical layer is a relatively modest part
of the total OpenOCD system.
@section targetnotarmppc PowerPC
there exists open source implementations of powerpc
@section targetnotarmppc PowerPC
there exists open source implementations of powerpc
.B OpenOCD
is an on\-chip debugging, in\-system programming and boundary\-scan
testing tool for various 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.
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.
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.
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.
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.
OpenOCD supports various different types of JTAG interfaces/programmers,
please check the \fIopenocd\fR info page for the complete list.
.SH "OPTIONS"
OpenOCD supports various different types of JTAG interfaces/programmers,
please check the \fIopenocd\fR info page for the complete list.
.SH "OPTIONS"
.B "\-f, \-\-file <filename>"
Use configuration file
.BR <filename> .
.B "\-f, \-\-file <filename>"
Use configuration file
.BR <filename> .
arguments. If this option is omitted, the config file
.B openocd.cfg
in the current working directory will be used.
arguments. If this option is omitted, the config file
.B openocd.cfg
in the current working directory will be used.
.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.
.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.
.B "\-d, \-\-debug <debuglevel>"
Set debug level. Possible values are:
.B "\-d, \-\-debug <debuglevel>"
Set debug level. Possible values are:
.RB " * " 1 " (warnings)"
.RB " * " 1 " (warnings)"
.RB " * " 2 " (informational messages)"
.RB " * " 2 " (informational messages)"
.RB " * " 3 " (debug messages)"
.RB " * " 3 " (debug messages)"
The default level is
.BR 2 .
The default level is
.BR 2 .
.B "\-l, \-\-log_output <filename>"
Redirect log output to the file
.BR <filename> .
Per default the log output is printed on
.BR stderr .
.B "\-l, \-\-log_output <filename>"
Redirect log output to the file
.BR <filename> .
Per default the log output is printed on
.BR stderr .
.B "\-c, \-\-command <cmd>"
Run the command
.BR <cmd> .
.B "\-c, \-\-command <cmd>"
Run the command
.BR <cmd> .
.B "\-p, \-\-pipe"
Use pipes when talking to gdb.
.B "\-p, \-\-pipe"
Use pipes when talking to gdb.
.B "\-h, \-\-help"
Show a help text and exit.
.B "\-h, \-\-help"
Show a help text and exit.
.B "\-v, \-\-version"
Show version information and exit.
.SH "BUGS"
.B "\-v, \-\-version"
Show version information and exit.
.SH "BUGS"
.B http://openfacts.berlios.de/index-en.phtml?title=Open_On-Chip_Debugger
.SH "AUTHORS"
Please see the file AUTHORS.
.B http://openfacts.berlios.de/index-en.phtml?title=Open_On-Chip_Debugger
.SH "AUTHORS"
Please see the file AUTHORS.
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).
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).
There are several things you should keep in mind when choosing a dongle.
There are several things you should keep in mind when choosing a dongle.
@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?
@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?
wires, or an "octopus" connector, to convert pinouts.
@item @b{Connection} Does your computer have the USB, printer, or
Ethernet port needed?
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
@end enumerate
@section Stand alone Systems
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
@* Link: @url{http://tools.asix.net/prg_presto.htm}
@item @b{Versaloon-Link}
@* Link: @url{http://tools.asix.net/prg_presto.htm}
@item @b{Versaloon-Link}
@option{srst_gates_jtag} indicates that asserting SRST gates the
JTAG clock. This means that no communication can happen on JTAG
@option{srst_gates_jtag} indicates that asserting SRST gates the
JTAG clock. This means that no communication can happen on JTAG
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
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
The target specific "dangerous" optimisation tweaking options may come and go
as more robust and user friendly ways are found to ensure maximum throughput
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:
Typically the "fast enable" is specified first on the command line:
@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
@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
@end deffn
@subsection ARM7 and ARM9 specific commands
@end deffn
@subsection ARM7 and ARM9 specific commands
@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
@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
This feature is enabled by default on most ARM9 cores,
including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
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
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
@end deffn
@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
gdb_memory_map disable
@end example
For this to function correctly a valid flash configuration must also be set
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
working area.
Informing GDB of the memory map of the target will enable GDB to protect any
information as an argument to each proc.
There are three main types of return values: single value, name value
information as an argument to each proc.
There are three main types of return values: single value, name value
Name value pair. The proc 'foo' below returns a name/value pair
Name value pair. The proc 'foo' below returns a name/value pair
puts "Name: $name, Value: $value"
}
@end verbatim
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.
Lists returned must be relatively small. Otherwise a range
should be passed in to the proc in question.
variables. JimTCL, as implemented in OpenOCD creates $HostOS which
holds one of the following values:
variables. JimTCL, as implemented in OpenOCD creates $HostOS which
holds one of the following values:
@item @b{winxx} Built using Microsoft Visual Studio
@item @b{linux} Linux is the underlying operating sytem
@item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
@item @b{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.
that ``deep sleeps'' at 32kHz between every keystroke. It can be
painful.
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!
In order to make use of this, your JTAG dongle must support the RTCK
feature. Not all dongles support this - keep reading!
@item @b{Win32 Pathnames} Why don't backslashes work in Windows paths?
OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @}
@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.
@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():
@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
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
@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
@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
@item @b{JTAG Reset Config} I get the following message in the OpenOCD console (or log file):
@item @b{JTAG Reset Config} I get the following message in the OpenOCD console (or log file):
@node Tcl Crash Course
@chapter Tcl Crash Course
@node Tcl Crash Course
@chapter Tcl Crash Course
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
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
Commands are executed like this:
Commands are executed like this:
@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.
@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.
@enumerate
@item The SET command creates 2 variables, X and Y.
@item The double [nested] EXPR command performs math
@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.
@* Refer to Rule #1
@item The format command is executed, producing a single string
@* Refer to Rule #1.
#4 DANGER DANGER DANGER
$_TARGETNAME configure -event foo "puts \"Time: [date]\""
@end example
#4 DANGER DANGER DANGER
$_TARGETNAME configure -event foo "puts \"Time: [date]\""
@end example
@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
@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
OpenOCD comes with a target configuration script library. These scripts can be
used as-is or serve as a starting point.
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.
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
The command line below uses the example parport configuration script
that ship with OpenOCD, then configures the str710.cfg target and
Linking to existing account procedure
If you already have an account and want to add another login method
you
MUST first sign in with your existing account and
then change URL to read
https://review.openocd.org/login/?link
to get to this page again but this time it'll work for linking. Thank you.
SSH host keys fingerprints
1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=.. |
|+o.. . |
|*.o . . |
|+B . . . |
|Bo. = o S |
|Oo.+ + = |
|oB=.* = . o |
| =+=.+ + E |
|. .=o . o |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)
Code Review / openocd.git / commitdiff