indicate there will be no more requests and the connection with the remote
driver should be closed.
-These five functions are encoded in ascii by assigning a single character to
+These five functions are encoded in ASCII by assigning a single character to
each possible request. The assignments are:
B - Blink on
t - Reset 1 0
u - Reset 1 1
-The read response is encoded in ascii as either digit 0 or 1.
+The read response is encoded in ASCII as either digit 0 or 1.
*/
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
+integrity for distribution by attempting to use the package in the same
manner as a user.
These checks includes the following steps:
macro to pass any e as parameters to the following helper function:
The subsequent blocks of code are a normal C function that can do
-anything, so only complex commands deserve should use comamnd helper
+anything, so only complex commands deserve should use command helper
functions. In this respect, this example uses one to demonstrate how --
not when -- they should be used.
- See @subpage primerlatex and @ref stylelatex.
- The Manual:
- Focuses on developing the OpenOCD software.
- - Details the architecutre, driver interfaces, and processes.
+ - Details the architecture, driver interfaces, and processes.
- Provides "full" coverage of C source code (work-in-progress).
- Written using Doxygen C language conventions (i.e. in comments).
- Created with 'make doxygen'.
===============
First, there is a "for" loop - at level 0
-{level 0 means: out side of a proc/function}
+{level 0 means: outside of a procedure/function}
This means it is evaluated when the file is parsed.
5) Goto Step 2.
As show, each of these items are in {curly-braces}. This means they
-are passed as they are - KEY-POINT: un evaluated to the FOR
+are passed as they are - KEY-POINT: unevaluated to the FOR
command. Think of it like escaping the backticks in Bash so that the
-"under-lying" command can evaluate the contents. In this case, the FOR
+"underlying" command can evaluate the contents. In this case, the FOR
COMMAND.
== END: SIDEBAR: About The FOR command ==
you think. But here's how:
First - the line is parsed - for {braces}. In this case, there are
-none. The, the parser looks for [brackets] and finds them. The,
+none. Then, the parser looks for [brackets] and finds them. The
parser then evaluates the contents of the [brackets], and replaces
-them. It is alot this bash statement.
+them. It is similar to this bash statement.
EXPORT vn=`date`
In line 1, we dynamically created a variable name. Here, we are
assigning it a value. Lastly Line 3 we force the variable to be
-global, not "local" the the "for command body"
+global, not "local" within the "for command body"
===============
The PROCS
Again, this is at "level 0" so it is a global function. (Yes, TCL
supports local functions, you put them inside of a function}
-You'll see in some cases, I nest [brackets] alot and in others I'm
+You'll see in some cases, I nest [brackets] a lot and in others I'm
lazy or wanted it to be more clear... it is a matter of choice.
===============
RWX - the access ability.
WIDTH - the accessible width.
- ie: Some regions of memory are not 'word'
+ i.e.: Some regions of memory are not 'word'
accessible.
The function "address_info" - given an address should
error [format string...]
}
-The "IF" command expects either 2 params, or 4 params.
+The "IF" command expects either 2 or 4 parameters.
=== Sidebar: About "commands" ===
The 2nd (optional) is where to put the error message.
CATCH returns 0 on success, 1 for failure.
- The "![catch command]" is self explaintory.
+ The "![catch command]" is self explanatory.
The 3rd parameter to IF must be exactly "else" or "elseif" [I lied
And - if it does - I call the function.
-In "C" it is alot like using: 'sprintf()' to construct a function name
+In "C" it is a lot like using: 'sprintf()' to construct a function name
string, then using "dlopen()" and "dlsym()" to look it up - and get a
function pointer - and calling the function pointer.
The "CHIP" file has defined some variables in a proper form.
-ie: AT91C_BASE_US0 - for usart0,
+i.e.: AT91C_BASE_US0 - for usart0,
AT91C_BASE_US1 - for usart1
... And so on ...
In this case, I'm trying to figure out what USARTs exist.
Step 1 - is to determine if the NAME has been defined.
-ie: Does AT91C_BASE_USx - where X is some number exist?
+i.e.: Does AT91C_BASE_USx - where X is some number exist?
The "info exists VARNAME" tells you if the variable exists. Then -
inside the IF statement... There is another loop. This loop is the
were produced as part of creating the archive.
-# Because they have been formally released by the project, users
don't need to try a random work-in-process revision. Releasing
- involves spending some time specifically on quality improvments,
+ involves spending some time specifically on quality improvements,
including bugfixing source code and documentation.
-# They provide developers with the flexibility needed to address
larger issues, which sometimes involves temporary breakage.
0.3.0-rc1-dev-00015-gf37c9b8-dirty
-indicates a development tree based on git revison f37c9b8
+indicates a development tree based on git revision f37c9b8
(a truncated version of a SHA1 hash) with some non-git
patches applied (the <em>dirty</em> tag). This information
can be useful when tracking down bugs.
- Last updates for the release, including the release tag (you
will need to "git push --tags").
- Updates opening the merge window
- - At this point, it's OK for commiters to start pushing changes
+ - At this point, it's OK for committers to start pushing changes
which have been held off until the next release. (Any bugfixes to
this release will be against a bug-fix release branch starting from
the commit you tagged as this release, not mainline.)
Both of these variations make automatic commits and tags in your
repository, so you should be sure to run it on a cloned copy before
-proceding with a live release.
+proceeding with a live release.
@subsection releasescriptopts Release Script Options
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
- readable output is expected to change inbetween versions
+ readable output is expected to change in between versions
of OpenOCD. The output from flash_banks may not be
in the preferred form for the client. The client then
has two choices a) parse the output from flash_banks
In many ways, people had talked about the need for some type of
high-level interface to OpenOCD, because they only had two choices:
- the ability to script: via an external program the actions of OpenOCD.
-- the ablity to write a complex internal commands: native 'commands'
+- the ability to write a complex internal commands: native 'commands'
inside of OpenOCD was complicated.
Fundamentally, the basic problem with both of those would be solved
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,
-allowing simple front-ends to be (a) cross-platform (b) languag
+allowing simple front-ends to be (a) cross-platform (b) language
agnostic, and (c) easy to develop and use.
Simple ASCII protocols are easy. For example, HTTP, FTP (control), and
well-known, and they do not require high-speed or high-volume. They
also support a high degree of interoperability with multiple systems.
They are not human-centric protocols; more correctly, they are rigid,
-terse, simple ASCII protocols that are emensely parsable by a script.
+terse, simple ASCII protocols that are easily 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
A lot has been said about various "widigit-foo-gui-library is so
wonderful". Please refer back to the domino and spider web problem of
dependencies. Sure, you may well know the WhatEver-GUI library, but
-most others will not (including the next contributer to OpenOCD).
+most others will not (including the next contributor to OpenOCD).
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.
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
+device with a built-in HTTP server. Later, they were willing to both
contribute and integrate most of that work into the main tree.
@subsection serverdocsother Other Options Considered
-What if a web browser is not acceptable ie: You want to write your own
+What if a web browser is not acceptable i.e.: You want to write your own
front gadget in Eclipse, or KDevelop, or PerlTK, Ruby, or what ever
the latest and greatest Script De Jour is.
something written in 2 different languages? A "SWIG" front-end is
unlikely to help that situation.
-@subsection serverdoccombined Combined: Socket & WebServer Benifits
+@subsection serverdoccombined Combined: Socket & WebServer Benefits
Seriously think about this question: What script language (or compiled
language) today cannot talk directly to a socket? Every thing in the
like it talk to the built in TCL server? Yes, absolutely! We are on to
something here.
-@subsection serverdocplatforms Platform Permuntations
+@subsection serverdocplatforms Platform Permutations
Look at some permutations where OpenOCD can run; these "just work" if
the Socket Approach is used.
-- Linux/Cygwin/MinGw/MacOSx/FreeBSD development Host Locally
+- Linux/Cygwin/MinGW/MacOSX/FreeBSD development Host Locally
- OpenOCD with some dongle on that host
-- Linux/Cygwin/MingW/MacOS/FreeBSD development host
-- DONGLE: tcpip based ARM-Linux perhaps at91rm9200 or ep93xx.c, running openocd.
+- Linux/Cygwin/MinGW/MacOS/FreeBSD development host
+- DONGLE: TCP/IP based ARM-Linux perhaps at91rm9200 or ep93xx.c, running openocd.
-- Windows cygwin/X desktop environment.
+- Windows Cygwin/X desktop environment.
- Linux development host (via remote X11)
-- Dongle: "eb93xx.c" based linux board
+- Dongle: "eb93xx.c" based Linux board
@subsection serverdocfuture Development Scale Out
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
+Maybe this can be done via Eclipse, but not all developers use Eclipse.
+Many developers 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..
One could create a simple: <b>Click here to display memory</b> or maybe
<b>click here to display the UART REGISTER BLOCK</b>; click again and see
-each register explained in exquisit detail.
+each register explained in exquisite detail.
For an STM32, one could create a simple HTML page, with simple
substitution text that the simple web server use to substitute the
every peripheral register on the target platform.
That also is transportable, regardless of the OpenOCD host
-platform: Linux/X86, Linux/ARM, FreeBSD, Cygwin, MingW, or MacOSX.
+platform: Linux/X86, Linux/ARM, FreeBSD, Cygwin, MinGW, or MacOSX.
You could even port OpenOCD to an Android system and use it as a
bit-banging JTAG Adapter serving web pages.
@section stylefunc Functions
-- static inline functions should be prefered over macros:
+- static inline functions should be preferred over macros:
@code
/** do NOT define macro-like functions like this... */
#define CUBE(x) ((x) * (x) * (x))
-# @c struct_name::member_name should be used to reference structure
fields in the documentation (e.g. @c flash_driver::name).
-# URLS get converted to markup automatically, without any extra effort.
- -# new pages can be linked into the heirarchy by using the @c \@subpage
+ -# new pages can be linked into the hierarchy by using the @c \@subpage
command somewhere the page(s) under which they should be linked:
-# use @c \@ref in other contexts to create links to pages and sections.
-# Use good Doxygen mark-up:
- Doxygen creates such pages for files automatically, but no content
will appear on them for those that only contain manual pages.
- The \@file block should provide useful meta-documentation to assist
- techincal writers; typically, a list of the pages that it contains.
+ technical writers; typically, a list of the pages that it contains.
- For example, the @ref styleguide exists in @c doc/manual/style.txt,
which contains a reference back to itself.
-# The \@file and \@page commands should begin on the same line as
is a guide for how and why to use each feature or mechanism of OpenOCD.
It is also the reference manual for all commands and options involved
in using them, including interface, flash, target, and other drivers.
-At this time, it is the only user-targetted documentation; everything
+At this time, it is the only documentation for end users; everything
else is addressing OpenOCD developers.
There are two key audiences for the User's Guide, both developer based.
Processor will do the action for us : it can for example read internal state (register values),
and send us back the information via EJTAG memory (dmseg), or it can take some data from dmseg and write it into the registers or RAM.
-Every time when it sees address (i.e. when this address is the part of the opcode it is executing, wether it is instruction or data fetch)
-that falls into dmseg, processor stalls. That acutally meand that CPU stops it's pipeline and it is waitning for dongle to take some action.
+Every time when it sees address (i.e. when this address is the part of the opcode it is executing, whether it is instruction or data fetch)
+that falls into dmseg, processor stalls. That actually means that CPU stops it's pipeline and it is waiting for dongle to take some action.
CPU is now either waiting for dongle to take some data from dmseg (if we requested for CPU do give us internal state, for example),
or it will wait for some data from dongle (if it needs following instruction because it did previous, or if the operand address of the currently executed opcode
falls somewhere (anywhere) in dmseg (0xff..ff20000 - 0xff..ff2fffff)).
-Bit PNnW describes character of CPU access to EJTAG memory (the memry where dongle puts/takes data) - CPU can either READ for it (PNnW == 0) or
+Bit PNnW describes character of CPU access to EJTAG memory (the memory where dongle puts/takes data) - CPU can either READ for it (PNnW == 0) or
WRITE to it (PNnW == 1).
By reading PNnW bit OpenOCD will know if it has to send (PNnW == 0) or to take (PNnW == 1) data (from dmseg, via dongle).
Once action from dongle has been done, i.e. after the data is taken/put, OpenOCD can signal to CPU to proceed with executing the instruction.
This can be the next instruction (if previous was finished before pending), or the same instruction - if for example CPU was waiting on dongle
-to give it an operand, because it saw in the instruction opcode that operand address is somewhere in dmseg. That prowoked the CPU to stall (it tried operand fetch to dmseg and stopped),
+to give it an operand, because it saw in the instruction opcode that operand address is somewhere in dmseg. That provoked the CPU to stall (it tried operand fetch to dmseg and stopped),
and PNnW bit is 0 (CPU does read from dmseg), and PrAcc is 1 (CPU is pending on dmseg access).
@subsection spracc SPrAcc
We have to pass this code to CPU via dongle via dmseg.
-After debug exception CPU will find itself stalling at the begining of the dmseg. It waits for the first instruction from dongle.
+After debug exception CPU will find itself stalling at the beginning of the dmseg. It waits for the first instruction from dongle.
This is MIPS32_MTC0(15,31,0), so CPU saves C0 and continues to addr 0xFF20 0001, which falls also to dmseg, so it stalls.
Dongle proceeds giving to CPU one by one instruction in this manner.
However, things are not so simple. If you take a look at the program, you will see that some instructions take operands. If it has to take
-operand from the address in dmseg, CPU will stall witing for the dongle to do the action of passing the operand and signal this by putting PrAcc to 0.
-If this operand is somewhere in RAM, CPU will not stall (it stalls only on dmseg), but it will just take it and proceed to nex instruction. But since PC for next instruction
+operand from the address in dmseg, CPU will stall waiting for the dongle to do the action of passing the operand and signal this by putting PrAcc to 0.
+If this operand is somewhere in RAM, CPU will not stall (it stalls only on dmseg), but it will just take it and proceed to next instruction. But since PC for next instruction
points to dmseg, it will stall, so that dongle can pass next instruction.
-Some instuctions are jumps (if these are jumps in dmseg addr, CPU will jump and then stall. If this is jump to some address in RAM, CPU will jump and just proceed -
+Some instructions are jumps (if these are jumps in dmseg addr, CPU will jump and then stall. If this is jump to some address in RAM, CPU will jump and just proceed -
will not stall on addresses in RAM).
To have information about CPU is currently (does it stalls wanting on operand or it jumped somewhere waiting for next instruction),
@endcode
i.e. if CPU is stalling on addresses in dmseg that are reserved for input parameters, we can conclude that it actually tried to take (read)
-parametar from there, and saw that address of param falls in dmseg, so it stopped. Obviously, now dongle have to give to it operand.
+parameter from there, and saw that address of parameter falls in dmseg, so it stopped. Obviously, now dongle have to give to it operand.
Similarly, mips32_pracc_exec_write() describes CPU writes into EJTAG memory (dmseg).
-Obvioulsy, code is RO, and CPU can change only parameters :
+Obviously, code is RO, and CPU can change only parameters :
@code
mips_ejtag_set_instr(ctx->ejtag_info, EJTAG_INST_DATA);
};
@endcode
-In the begining and the end of the handler we have fuction prologue (save the regs that will be clobbered) and epilogue (restore regs),
+In the beginning and the end of the handler we have function prologue (save the regs that will be clobbered) and epilogue (restore regs),
and in the very end, after all the xfer have been done, we do jump to the MIPS32_PRACC_TEXT address, i.e. Debug Exception Vector location.
We will use this fact (that we came back to MIPS32_PRACC_TEXT) to verify later if all the handler is executed (because when in RAM,
-processor do not stall - it executes all instructions untill one of them do not demand access to dmseg (if one of it's opernads is there)).
+processor do not stall - it executes all instructions until one of them do not demand access to dmseg (if one of it's operands is there)).
This handler is put into the RAM and executed from there, and not instruction by instruction, like in previous simple write
(mips_m4k_write_memory()) and read (mips_m4k_read_memory()) functions.
and there it will stall - because it will see that one of the operands have to be fetched from dmseg (EJTAG memory, in this case FASTDATA memory segment).
-This handler is loaded in the RAM, ath the reserved location "work_area". This work_area is configured in OpenOCD configuration script and should be selected
+This handler is loaded in the RAM, at the reserved location "work_area". This work_area is configured in OpenOCD configuration script and should be selected
in that way that it is not clobbered (overwritten) by data we want to write-in using FASTDATA.
What is executed instruction by instruction which is passed by dongle (via EJATG memory) is small jump code, which jumps at the handler in RAM.
CPU stalls on dmseg when receiving these jmp_code instructions, but once it jumps in RAM, CPU do not stall anymore and executes bunch of handler instructions.
-Untill it comes to the first instruction which has an operand in FASTDATA area. There it stalls and waits on action from probe.
+Until it comes to the first instruction which has an operand in FASTDATA area. There it stalls and waits on action from probe.
It happens actually when CPU comes to this loop :
@code
}
@endcode
-Each time when OpenOCD fills data to CPU (via dongle, via dmseg), CPU takes it and proceeds in executing the endler. However, since handler is in a assembly loop,
+Each time when OpenOCD fills data to CPU (via dongle, via dmseg), CPU takes it and proceeds in executing the handler. However, since handler is in a assembly loop,
CPU comes to next instruction which also fetches data from FASTDATA area. So it stalls.
Then OpenOCD fills the data again, from it's (OpenOCD's) loop. And this game continues untill all the data has been filled.
-After the last data has beend given to CPU it sees that it reached the end address, so it proceeds with next instruction. However, rhis instruction do not point into dmseg, so
+After the last data has been given to CPU it sees that it reached the end address, so it proceeds with next instruction. However, this instruction do not point into dmseg, so
CPU executes bunch of handler instructions (all prologue) and in the end jumps to MIPS32_PRACC_TEXT address.
-On it's side, OpenOCD checks in CPU has jumped back to MIPS32_PRACC_TEXT, which is the confirmation that it correclty executed all the rest of the handler in RAM,
-and that is not stuck somewhere in the RAM, or stalling on some acces in dmseg - that would be an error :
+On it's side, OpenOCD checks in CPU has jumped back to MIPS32_PRACC_TEXT, which is the confirmation that it correctly executed all the rest of the handler in RAM,
+and that is not stuck somewhere in the RAM, or stalling on some access in dmseg - that would be an error :
@code
address = 0;
Note: A failure may have a recoverable (and even expected) cause like slow target execution of the load loop. Other failures may be due to unexpected more troublesome causes like an exception while in debug mode or a target hang on a bad target memory access.
-Shifted out SPrAcc bit inform us that there was CPU access pendingand that it can be complete.
+Shifted out SPrAcc bit inform us that there was CPU access pending and that it can be complete.
Basically, we should do following procedure :
If some FASTDATA write fails, OpenOCD will continue with it's loop (on the host side), but CPU will rest pending (on the target side)
waiting for correct FASTDATA write.
-Since OpenOCD goes ahead, it will eventually finish it's loop, and proceede to check if CPU took all the data. But since CPU did not took all the data,
+Since OpenOCD goes ahead, it will eventually finish it's loop, and proceed to check if CPU took all the data. But since CPU did not took all the data,
it is still turns in handler's loop in RAM, stalling on Fastdata area so this check :
@code
fails, and that gives us enough information of the failure.
-In this case, we can lower the JTAG frquency and try again, bacuse most probable reason of this failure is that we tried FASTDATA upload before CPU arrived to rise PrAcc (i.e. before it was pending on access).
+In this case, we can lower the JTAG frequency and try again, because most probable reason of this failure is that we tried FASTDATA upload before CPU arrived to rise PrAcc (i.e. before it was pending on access).
However, the reasons for failure might be numerous : reset, exceptions which can occur in debug mode, bus hangs, etc.
If lowering the JTAG freq does not work either, we can fall back to more robust solution with patch posted below.
To summarize, FASTDATA communication goes as following :
--# CPU jumps to Debug Exception Vector Location 0xFF200200 in dmseg and it stalls, pending and waiting for EJTAG to give it first debug instruction and signall it by putting PrAcc to "0"
+-# CPU jumps to Debug Exception Vector Location 0xFF200200 in dmseg and it stalls, pending and waiting for EJTAG to give it first debug instruction and signal it by putting PrAcc to "0"
-# When PrAcc goes to "0" CPU execute one opcode sent by EJTAG via DATA reg. Then it pends on next access, waiting for PrAcc to be put to "0" again
-# Following this game, OpenOCD first loads handler code in RAM, and then sends the jmp_code - instruction by instruction via DATA reg, which redirects CPU to handler previously set up in RAM
--# Once in RAM CPU does not pend on any instruction, but it executes all handler instructions untill first "fetch" to Fastdata area - then it stops and pends.
+-# Once in RAM CPU does not pend on any instruction, but it executes all handler instructions until first "fetch" to Fastdata area - then it stops and pends.
-# So - when it comes to any instruction (opcode) in this handler in RAM which reads (or writes) to Fastdata area (0xF..F20.0000 to 0xF..F20.000F), CPU stops (i.e. stalls access).
I.e. it stops on this lw opcode and waits to FASTDATA TAP command from the probe.
-# CPU continues only if OpenOCD shifted in SPrAcc "0" (and if the PrAcc was "1"). It shifts-out "1" to tell us that it was OK (processor was stalled, so it can complete the access),
and that it continued execution of the handler in RAM.
-# If PrAcc was not "1" CPU will not continue (go to next instruction), but will shift-out "0" and keep stalling on the same instruction of my handler in RAM.
--# When Fastdata loop is finished, CPU executes all following hadler instructions in RAM (prologue).
--# In the end of my handler in RAM, I jumps back to begining of Debug Exception Vector Location 0xFF200200 in dmseg.
+-# When Fastdata loop is finished, CPU executes all following handler instructions in RAM (prologue).
+-# In the end of my handler in RAM, I jumps back to beginning of Debug Exception Vector Location 0xFF200200 in dmseg.
-# When it jumps back to 0xFF200200 in dmseg processor stops and pends, waiting for OpenOCD to send it instruction via DATA reg and signal it by putting PrAcc to "0".
*/
@section targetnotarmppc PowerPC
-there exists open source implementations of powerpc
+there exists open source implementations of PowerPC
target manipulation, but there hasn't been a lot
of activity in the mailing list.
projects / openocd / commitdiff