Browse Source

Numerous pedantic fixes to the User's Guide, including typo fixes,

grammar fixes and so on.

Change-Id: Iaeb603447ecd9f77f1d49ce77044431442f4f219
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Reviewed-on: http://openocd.zylin.com/1855
Reviewed-by: Bill Traynor <btraynor@gmail.com>
Tested-by: jenkins
Reviewed-by: Francois Lorrain <francois.lorrain@gmail.com>
Reviewed-by: Spencer Oliver <spen@spen-soft.co.uk>
tags/v0.8.0-rc1
Robert P. J. Day 10 years ago
committed by Spencer Oliver
parent
commit
647eeefb53
1 changed files with 53 additions and 51 deletions
  1. +53
    -51
      doc/openocd.texi

+ 53
- 51
doc/openocd.texi View File

@@ -99,8 +99,8 @@ Free Documentation License''.
@unnumbered About
@cindex about

OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
OpenOCD was created by Dominic Rath as part of a 2005 diploma thesis written
at the University of Applied Sciences Augsburg (@uref{http://www.hs-augsburg.de}).
Since that time, the project has grown into an active open-source project,
supported by a diverse community of software and hardware developers from
around the world.
@@ -129,7 +129,7 @@ they are called. (There are also product naming differences.)
These adapters are sometimes packaged as discrete dongles, which
may generically be called @dfn{hardware interface dongles}.
Some development boards also integrate them directly, which may
let the development board can be directly connected to the debug
let the development board connect directly to the debug
host over USB (and sometimes also to power it over USB).

For example, a @dfn{JTAG Adapter} supports JTAG
@@ -142,7 +142,7 @@ scan operations.

There are also @dfn{SWD Adapters} that support Serial Wire Debug (SWD)
signaling to communicate with some newer ARM cores, as well as debug
adapters which support both JTAG and SWD transports. SWD only supports
adapters which support both JTAG and SWD transports. SWD supports only
debugging, whereas JTAG also supports boundary scan operations.

For some chips, there are also @dfn{Programming Adapters} supporting
@@ -151,8 +151,8 @@ support for on-chip debugging or boundary scan.
(At this writing, OpenOCD does not support such non-debug adapters.)


@b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
based, parallel port based, and other standalone boxes that run
@b{Dongles:} OpenOCD currently supports many types of hardware dongles:
USB-based, parallel port-based, and other standalone boxes that run
OpenOCD internally. @xref{Debug Adapter Hardware}.

@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
@@ -160,11 +160,11 @@ ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
Cortex-M3 (Stellaris LM3, ST STM32 and Energy Micro EFM32) based cores to be
debugged via the GDB protocol.

@b{Flash Programing:} Flash writing is supported for external CFI
compatible NOR flashes (Intel and AMD/Spansion command set) and several
@b{Flash Programming:} Flash writing is supported for external
CFI-compatible NOR flashes (Intel and AMD/Spansion command set) and several
internal flashes (LPC1700, LPC1800, LPC2000, LPC4300, AT91SAM7, AT91SAM3U,
STR7x, STR9x, LM3, STM32x and EFM32). Preliminary support for various NAND flash
controllers (LPC3180, Orion, S3C24xx, more) controller is included.
controllers (LPC3180, Orion, S3C24xx, more) is included.

@section OpenOCD Web Site

@@ -218,10 +218,10 @@ documentation, as well as more conventional bug fixes and enhancements.
The resources in this chapter are available for developers wishing to explore
or expand the OpenOCD source code.

@section OpenOCD GIT Repository
@section OpenOCD Git Repository

During the 0.3.x release cycle, OpenOCD switched from Subversion to
a GIT repository hosted at SourceForge. The repository URL is:
a Git repository hosted at SourceForge. The repository URL is:

@uref{git://git.code.sf.net/p/openocd/code}

@@ -233,11 +233,11 @@ You may prefer to use a mirror and the HTTP protocol:

@uref{http://repo.or.cz/r/openocd.git}

With standard GIT tools, use @command{git clone} to initialize
With standard Git tools, use @command{git clone} to initialize
a local repository, and @command{git pull} to update it.
There are also gitweb pages letting you browse the repository
with a web browser, or download arbitrary snapshots without
needing a GIT client:
needing a Git client:

@uref{http://repo.or.cz/w/openocd.git}

@@ -260,7 +260,7 @@ processes, and similar documentation:

This document is a work-in-progress, but contributions would be welcome
to fill in the gaps. All of the source files are provided in-tree,
listed in the Doxyfile configuration in the top of the source tree.
listed in the Doxyfile configuration at the top of the source tree.

@section OpenOCD Developer Mailing List

@@ -291,16 +291,16 @@ using Trac for its bug database:
@cindex USB Adapter
@cindex RTCK

Defined: @b{dongle}: A small device that plugins into a computer and serves as
Defined: @b{dongle}: A small device that plugs into a computer and serves as
an adapter .... [snip]

In the OpenOCD case, this generally refers to @b{a small adapter} that
attaches to your computer via USB or the Parallel Printer Port. One
exception is the Zylin ZY1000, packaged as a small box you attach via
an ethernet cable. The Zylin ZY1000 has the advantage that it does not
attaches to your computer via USB or the parallel port. One
exception is the Ultimate Solutions ZY1000, packaged as a small box you
attach via an ethernet cable. The ZY1000 has the advantage that it does not
require any drivers to be installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
and has a built in relay to power cycle targets remotely.
and has a built-in relay to power cycle targets remotely.


@section Choosing a Dongle
@@ -316,17 +316,17 @@ Does your dongle support it? You might need a level converter.
@item @b{Pinout} What pinout does your target board use?
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
@item @b{Connection} Does your computer have the USB, parallel, or
Ethernet port needed?
@item @b{RTCK} Do you expect to use it with ARM chips and boards with
RTCK support? Also known as ``adaptive clocking''
RTCK support (also known as ``adaptive clocking'')?
@end enumerate

@section Stand-alone JTAG Probe

The ZY1000 from Ultimate Solutions is technically not a dongle but a
stand-alone JTAG probe that unlikemost dongles doesn’t require any drivers
running on the developers host computer.
stand-alone JTAG probe that, unlike most dongles, doesn't require any drivers
running on the developer's host computer.
Once installed on a network using DHCP or a static IP assignment, users can
access the ZY1000 probe locally or remotely from any host with access to the
IP address assigned to the probe.
@@ -340,16 +340,16 @@ to power cycle the target remotely.

For more information, visit:

@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/33-zylin-zy1000-jtag-probe}
@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/210-zylin-zy1000-main}

@section USB FT2232 Based

There are many USB JTAG dongles on the market, many of them are based
There are many USB JTAG dongles on the market, many of them based
on a chip from ``Future Technology Devices International'' (FTDI)
known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
See: @url{http://www.ftdichip.com} for more information.
In summer 2009, USB high speed (480 Mbps) versions of these FTDI
chips are starting to become available in JTAG adapters. Around 2012 a new
chips started to become available in JTAG adapters. Around 2012, a new
variant appeared - FT232H - this is a single-channel version of FT2232H.
(Adapters using those high speed FT2232H or FT232H chips may support adaptive
clocking.)
@@ -361,7 +361,7 @@ and one can be used for a UART adapter at the same time the
other one is used to provide a debug adapter.

Also, some development boards integrate an FT2232 chip to serve as
a built-in low cost debug adapter and usb-to-serial solution.
a built-in low-cost debug adapter and USB-to-serial solution.

@itemize @bullet
@item @b{usbjtag}
@@ -423,7 +423,7 @@ These devices also show up as FTDI devices, but are not
protocol-compatible with the FT2232 devices. They are, however,
protocol-compatible among themselves. USB-JTAG devices typically consist
of a FT245 followed by a CPLD that understands a particular protocol,
or emulate this protocol using some other hardware.
or emulates this protocol using some other hardware.

They may appear under different USB VID/PID depending on the particular
product. The driver can be configured to search for any VID/PID pair
@@ -477,9 +477,9 @@ They only work with ST Micro chips, notably STM32 and STM8.
@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
@end itemize

For info the original ST-LINK enumerates using the mass storage usb class, however
it's implementation is completely broken. The result is this causes issues under linux.
The simplest solution is to get linux to ignore the ST-LINK using one of the following methods:
For info the original ST-LINK enumerates using the mass storage usb class; however,
its implementation is completely broken. The result is this causes issues under Linux.
The simplest solution is to get Linux to ignore the ST-LINK using one of the following methods:
@itemize @bullet
@item modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
@item add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
@@ -519,7 +519,7 @@ evaluation boards. This is the adapter fitted to the Stellaris LaunchPad.

@section IBM PC Parallel Printer Port Based

The two well known ``JTAG Parallel Ports'' cables are the Xilnx DLC5
The two well-known ``JTAG Parallel Ports'' cables are the Xilinx DLC5
and the Macraigor Wiggler. There are many clones and variations of
these on the market.

@@ -597,9 +597,9 @@ command interpreter.
All commands presented in this Guide are extensions to Jim-Tcl.
You can use them as simple commands, without needing to learn
much of anything about Tcl.
Alternatively, can write Tcl programs with them.
Alternatively, you can write Tcl programs with them.

You can learn more about Jim at its website, @url{http://jim.berlios.de}.
You can learn more about Jim at its website, @url{http://jim.tcl.tk}.
There is an active and responsive community, get on the mailing list
if you have any questions. Jim-Tcl maintainers also lurk on the
OpenOCD mailing list.
@@ -621,7 +621,7 @@ enabled in OpenOCD.
@item @b{Scripts}
@* OpenOCD configuration scripts are Jim-Tcl Scripts. OpenOCD's
command interpreter today is a mixture of (newer)
Jim-Tcl commands, and (older) the orginal command interpreter.
Jim-Tcl commands, and the (older) original command interpreter.

@item @b{Commands}
@* At the OpenOCD telnet command line (or via the GDB monitor command) one
@@ -631,9 +631,9 @@ as Tcl scripts, from a @file{startup.tcl} file internal to the server.

@item @b{Historical Note}
@* Jim-Tcl was introduced to OpenOCD in spring 2008. Fall 2010,
before OpenOCD 0.5 release OpenOCD switched to using Jim Tcl
as a git submodule, which greatly simplified upgrading Jim Tcl
to benefit from new features and bugfixes in Jim Tcl.
before OpenOCD 0.5 release, OpenOCD switched to using Jim-Tcl
as a Git submodule, which greatly simplified upgrading Jim-Tcl
to benefit from new features and bugfixes in Jim-Tcl.

@item @b{Need a crash course in Tcl?}
@*@xref{Tcl Crash Course}.
@@ -701,10 +701,11 @@ customization even if this works. @xref{OpenOCD Project Setup}.

If you find a script for your JTAG adapter, and for your board or
target, you may be able to hook up your JTAG adapter then start
the server like:
the server with some variation of one of the following:

@example
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
openocd -f interface/ftdi/ADAPTER.cfg -f board/MYBOARD.cfg
@end example

You might also need to configure which reset signals are present,
@@ -767,10 +768,10 @@ correctly via e.g. GDB monitor commands in a GDB init script.
@chapter OpenOCD Project Setup

To use OpenOCD with your development projects, you need to do more than
just connecting the JTAG adapter hardware (dongle) to your development board
and then starting the OpenOCD server.
You also need to configure that server so that it knows
about that adapter and board, and helps your work.
just connect the JTAG adapter hardware (dongle) to your development board
and start the OpenOCD server.
You also need to configure your OpenOCD server so that it knows
about your adapter and board, and helps your work.
You may also want to connect OpenOCD to GDB, possibly
using Eclipse or some other GUI.

@@ -828,8 +829,9 @@ A USB, parallel, or serial port connector will go to the host which
you are using to run OpenOCD.
For Ethernet, consult the documentation and your network administrator.

For USB based JTAG adapters you have an easy sanity check at this point:
does the host operating system see the JTAG adapter? If that host is an
For USB-based JTAG adapters you have an easy sanity check at this point:
does the host operating system see the JTAG adapter? If you're running
Linux, try the @command{lsusb} command. If that host is an
MS-Windows host, you'll need to install a driver before OpenOCD works.

@item @emph{Connect the adapter's power supply, if needed.}
@@ -986,7 +988,7 @@ will help support users of any board using that chip.

@item
You may may need to write some C code.
It may be as simple as a supporting a new ft2232 or parport
It may be as simple as supporting a new FT2232 or parport
based adapter; a bit more involved, like a NAND or NOR flash
controller driver; or a big piece of work like supporting
a new chip architecture.
@@ -1548,7 +1550,7 @@ about a given board that user config files need to know.
In summary the board files should contain (if present)

@enumerate
@item One or more @command{source [target/...cfg]} statements
@item One or more @command{source [find target/...cfg]} statements
@item NOR flash configuration (@pxref{norconfiguration,,NOR Configuration})
@item NAND flash configuration (@pxref{nandconfiguration,,NAND Configuration})
@item Target @code{reset} handlers for SDRAM and I/O configuration
@@ -1746,16 +1748,16 @@ The concept of @code{init_board} procedure is very similar to @code{init_targets
(@xref{theinittargetsprocedure,,The init_targets procedure}.) - it's a replacement of ``linear''
configuration scripts. This procedure is meant to be executed when OpenOCD enters run stage
(@xref{enteringtherunstage,,Entering the Run Stage},) after @code{init_targets}. The idea to have
spearate @code{init_targets} and @code{init_board} procedures is to allow the first one to configure
separate @code{init_targets} and @code{init_board} procedures is to allow the first one to configure
everything target specific (internal flash, internal RAM, etc.) and the second one to configure
everything board specific (reset signals, chip frequency, reset-init event handler, external memory, etc.).
Additionally ``linear'' board config file will most likely fail when target config file uses
@code{init_targets} scheme (``linear'' script is executed before @code{init} and @code{init_targets} - after),
so separating these two configuration stages is very convenient, as the easiest way to overcome this
problem is to convert board config file to use @code{init_board} procedure. Board config scripts don't
need to override @code{init_targets} defined in target config files when they only need to to add some specifics.
need to override @code{init_targets} defined in target config files when they only need to add some specifics.

Just as @code{init_targets}, the @code{init_board} procedure can be overriden by ``next level'' script (which sources
Just as @code{init_targets}, the @code{init_board} procedure can be overridden by ``next level'' script (which sources
the original), allowing greater code reuse.

@example
@@ -3566,7 +3568,7 @@ TAPs serve many roles, including:

@itemize @bullet
@item @b{Debug Target} A CPU TAP can be used as a GDB debug target
@item @b{Flash Programing} Some chips program the flash directly via JTAG.
@item @b{Flash Programming} Some chips program the flash directly via JTAG.
Others do it indirectly, making a CPU do it.
@item @b{Program Download} Using the same CPU support GDB uses,
you can initialize a DRAM controller, download code to DRAM, and then


Loading…
Cancel
Save