Hiroshi Ito <ito@mlb.co.jp> typos

[openocd.git] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index dea019695e9744731101a3d282d7bb3d5eb52d97..66f8b1288bbdab9b475e0f3e44f4d51e92dab297 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -265,6 +265,8 @@ should be included:
 @option{--enable-vsllink}
 @item
 @option{--enable-rlink} - Raisonance.com dongle.
+@item
+@option{--enable-arm-jtag-ew} - Olimex ARM-JTAG-EW dongle.
 @end itemize
 
 @section Parallel Port Dongles
@@ -331,7 +333,12 @@ Cygwin/Linux LIBFTDI solution
 
 @itemize @bullet
 @item
-@option{--enable-gccwarnings} - enable extra gcc warnings during build
+@option{--enable-gccwarnings} - enable extra gcc warnings during build.
+Default is enabled.
+@item
+@option{--enable-release} - enable building of a openocd release, generally
+this is for developers. It simply omits the svn version string when the
+openocd @option{-v} is executed.
 @end itemize
 
 @node JTAG Hardware Dongles
@@ -440,6 +447,9 @@ Raisonance has an adapter called @b{RLink}.  It exists in a stripped-down form o
 
 @item @b{Versaloon-Link}
 @* Link: @url{http://www.simonqian.com/en/Versaloon}
+
+@item @b{ARM-JTAG-EW}
+@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
 @end itemize
 
 @section IBM PC Parallel Printer Port Based
@@ -1073,7 +1083,7 @@ first target will be gdb_port, the second target will listen on gdb_port + 1, an
 
 @section GDB Items
 @itemize @bullet
-@item @b{gdb_breakpoint_override} <@var{hard|soft|disabled}>
+@item @b{gdb_breakpoint_override} <@var{hard|soft|disable}>
 @cindex gdb_breakpoint_override
 @anchor{gdb_breakpoint_override}
 @*Force breakpoint type for gdb 'break' commands.
@@ -1087,7 +1097,7 @@ the same issue.
 
 @item @b{gdb_detach} <@var{resume|reset|halt|nothing}>
 @cindex gdb_detach
-@*Configures what OpenOCD will do when gdb detaches from the daeman.
+@*Configures what OpenOCD will do when gdb detaches from the daemon.
 Default behaviour is <@var{resume}>
 
 @item @b{gdb_memory_map} <@var{enable|disable}>
@@ -1139,6 +1149,10 @@ parport_port 0xc8b8
 parport_cable wiggler
 jtag_speed 0
 @end verbatim
+@b{ARM-JTAG-EW}
+@verbatim
+interface arm-jtag-ew
+@end verbatim
 @section Interface Conmmand
 
 The interface command tells OpenOCD what type of jtag dongle you are
@@ -1187,6 +1201,9 @@ libusb.
 
 @item @b{vsllink}
 @* vsllink is part of Versaloon which is a versatile USB programmer.
+
+@item @b{arm-jtag-ew}
+@* Olimex ARM-JTAG-EW usb adapter
 @comment - End parameters
 @end itemize
 @comment - End Interface
@@ -1504,9 +1521,12 @@ Tap Uses:
 parameters'', the required parameters are:
 @comment START REQUIRED
 @itemize @bullet
-@item @b{-irlen NUMBER} - the length in bits of the instruction register
-@item @b{-ircapture NUMBER} - the ID code capture command.
-@item @b{-irmask NUMBER} - the corresponding mask for the ir register.
+@item @b{-irlen NUMBER} - the length in bits of the instruction register, mostly 4 or 5 bits.
+@item @b{-ircapture NUMBER} - the IDCODE capture command, usually 0x01.
+@item @b{-irmask NUMBER} - the corresponding mask for the IR register. For
+some devices, there are bits in the IR that aren't used.  This lets you mask
+them off when doing comparisons.  In general, this should just be all ones for
+the size of the IR.
 @comment END REQUIRED
 @end itemize
 An example of a FOOBAR Tap
@@ -2240,8 +2260,8 @@ Use the standard str9 driver for programming. @xref{STR9 specific commands}.
 @subsubsection aduc702x options
 @cindex aduc702x options
 
-@b{flash bank aduc702x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
-@*aduc702x flash plugin require the flash @var{base}, @var{size} and @var{target#}.
+@b{flash bank aduc702x} 0 0 0 0 <@var{target#}>
+@*The aduc702x flash plugin works with Analog Devices model numbers ADUC7019 through ADUC7028.  The setup command only requires the @var{target#} argument (all devices in this family have the same memory layout).
 
 @subsection mFlash configuration
 @cindex mFlash configuration
@@ -3055,9 +3075,10 @@ To verify any flash programming the GDB command @option{compare-sections}
 can be used.
 
 @node TCL scripting API
-@chapter TCL scripting API
+@chapter TCL scripts
 @cindex TCL scripting API
-API rules
+@cindex TCL scripts
+@section API Rules
 
 The commands are stateless. E.g. the telnet command line has a concept
 of currently active target, the Tcl API proc's take this sort of state
@@ -3094,7 +3115,11 @@ Thus, to get the names of the associative array is easy:
 Lists returned must be relatively small. Otherwise a range
 should be passed in to the proc in question.
 
-Low level commands are prefixed with "openocd_", e.g. openocd_flash_banks
+@section Internal Low Level Commands
+
+By Low level, the intent is a human would not directly use these commands.
+
+Low level commands are (should be) prefixed with "openocd_", e.g. openocd_flash_banks
 is the low level API upon which "flash banks" is implemented.
 
 @itemize @bullet
@@ -3113,6 +3138,24 @@ OpenOCD commands can consist of two words, e.g. "flash banks". The
 startup.tcl "unknown" proc will translate this into a tcl proc
 called "flash_banks".
 
+@section OpenOCD specific Global Variables
+
+@subsection HostOS
+
+Real TCL has ::tcl_platform(), and platform::identify, and many other
+variables. JimTCL, as implimented in OpenOCD creates $HostOS which
+holds one of the following values.
+
+@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.
+@item @b{cygwin}   Running under Cygwin
+@item @b{mingw32}  Running under MingW32
+@item @b{other}    Unknown, none of the above.
+@end itemize
+
+Note: 'winxx' was choosen because today (March-2009) no distinction is made between Win32 and Win64.
 
 @node Upgrading
 @chapter Deprecated/Removed Commands
@@ -3184,24 +3227,29 @@ halt
 @*
 
 In digital circuit design it is often refered to as ``clock
-syncronization'' the JTAG interface uses one clock (TCK or TCLK)
+synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
 operating at some speed, your target is operating at another.  The two
-clocks are not syncronized, they are ``asynchronous''
+clocks are not synchronised, they are ``asynchronous''
 
-In order for the two to work together they must syncronize. Otherwise
+In order for the two to work together they must be synchronised. Otherwise
 the two systems will get out of sync with each other and nothing will
-work. There are 2 basic options. @b{1.} use a special circuit or
-@b{2.}  one clock must be some multile slower the the other.
+work. There are 2 basic options.
+@enumerate
+@item
+Use a special circuit.
+@item
+One clock must be some multiple slower the the other.
+@end enumerate
 
 @b{Does this really matter?} For some chips and some situations, this
-is a non-issue (ie: A 500mhz ARM926) but for others - for example some
-ATMEL SAM7 and SAM9 chips start operation from reset at 32khz -
+is a non-issue (ie: A 500MHz ARM926) but for others - for example some
+ATMEL SAM7 and SAM9 chips start operation from reset at 32kHz -
 program/enable the oscillators and eventually the main clock. It is in
 those critical times you must slow the jtag clock to sometimes 1 to
-4khz.
+4kHz.
 
-Imagine debugging that 500mhz arm926 hand held battery powered device
-that ``deep sleeps'' at 32khz between every keystroke. It can be
+Imagine debugging that 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} 
@@ -3213,14 +3261,14 @@ The RTCK signal often found in some ARM chips is used to help with
 this problem. ARM has a good description of the problem described at
 this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked
 28/nov/2008]. Link title: ``How does the jtag synchronisation logic
-work? / how does adaptive clocking working?''.
+work? / how does adaptive clocking work?''.
 
 The nice thing about adaptive clocking is that ``battery powered hand
 held device example'' - the adaptiveness works perfectly all the
 time. One can set a break point or halt the system in the deep power
 down code, slow step out until the system speeds up.
 
-@b{Solution #2 - Always works - but is slower}
+@b{Solution #2 - Always works - but may be slower}
 
 Often this is a perfectly acceptable solution.
 
@@ -3230,7 +3278,7 @@ depending upon the chips on your board. @b{ARM Rule of thumb} Most ARM
 based systems require an 8:1 division. @b{Xilinx Rule of thumb} is
 1/12 the clock speed.
 
-Note: Many FTDI2232C based JTAG dongles are limited to 6mhz.
+Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
 
 You can still debug the 'lower power' situations - you just need to
 manually adjust the clock speed at every step. While painful and
@@ -3244,7 +3292,7 @@ this way.
 To set the JTAG frequency use the command:
 
 @example
-        # Example: 1.234mhz
+        # Example: 1.234MHz
         jtag_khz 1234
 @end example
 
@@ -3390,7 +3438,7 @@ You can use the ``scan_chain'' command to verify and display the tap order.
 
 Many newer devices have multiple JTAG taps. For example: ST
 Microsystems STM32 chips have two taps, a ``boundary scan tap'' and
-``cortexM3'' tap.  Example: The STM32 reference manual, Document ID:
+``CortexM3'' tap.  Example: The STM32 reference manual, Document ID:
 RM0008, Section 26.5, Figure 259, page 651/681, the ``TDI'' pin is
 connected to the Boundary Scan Tap, which then connects to the
 CortexM3 Tap, which then connects to the TDO pin.