doc: not all debug adapters are "dongles"

Talk more about "debug adapters" instead of only "dongles".  Not all
adapters are discrete widgets; some are integrated onto boards.  If
we only talk about "dongles" we rule out many valid setups, and help
confuse some users (who may be using Dongle-free environments).

Also start bringing out the point that JTAG isn't the only transport
protocol, even though OpenOCD historically presumes "all is JTAG".
(Not all debug adapters are JTAG adapters, or JTAG-only adapters.)

Plus a few minor fixes (spelling etc) in the vicinity of those changes,
and updates about FT2232H clocking issues (they can go faster than the
older chips, and can support adaptive clocking).

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

diff --git a/doc/manual/server.txt b/doc/manual/server.txt
index 5250f7f1139a92e1fddcb689f58da7708a336678..f75f1d1d3d9ecc83c1cab057853fde45fb4a6106 100644 (file)
--- a/doc/manual/server.txt
+++ b/doc/manual/server.txt
@@ -207,7 +207,7 @@ upon it, sometimes that is the only scheme available.
 
 As a small group of developers, supporting all the platforms and
 targets in the debugger will be difficult, as there are enough problem
 
 As a small group of developers, supporting all the platforms and
 targets in the debugger will be difficult, as there are enough problem

-with the plethora of Dongles, Chips, and different target boards.
+with the plethora of Adapters, Chips, and different target boards.

 Yes, the TCL interface might be suitable, but it has not received much
 love or attention.  Perhaps it will after you read and understand this.
 
 Yes, the TCL interface might be suitable, but it has not received much
 love or attention.  Perhaps it will after you read and understand this.
 


@@ -235,7 +235,7 @@ different host-side GDB..
 Sure - a <em>man on a mission</em> can make that work.  The GUI might be
 libopenocd + Perl/TK, or maybe an Eclipse Plug-in.
 That is a development support nightmare for reasons described
 Sure - a <em>man on a mission</em> can make that work.  The GUI might be
 libopenocd + Perl/TK, or maybe an Eclipse Plug-in.
 That is a development support nightmare for reasons described

-above. We have enough support problems as it is with targets, dongles,
+above. We have enough support problems as it is with targets, adapters,

 etc.
 
 @section serverdocshttpbg HTTP Server Background
 etc.
 
 @section serverdocshttpbg HTTP Server Background


@@ -270,8 +270,8 @@ 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.
 
 That also is transportable, regardless of the OpenOCD host
 platform: Linux/X86, Linux/ARM, FreeBSD, Cygwin, MingW, or MacOSX.

-You could even port OpenOCD to an Google Android and use it as a
-bit-bang dongle JTAG serving web pages.
+You could even port OpenOCD to an Android system and use it as a
+bit-banging JTAG Adapter serving web pages.

 
 @subsection serverdocshtmladv Advanced HTML Pages
 
 
 @subsection serverdocshtmladv Advanced HTML Pages
 

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 507498faa6140d48ec2f07f1e03bf62f03fbd044..f9f9b68e34f742df8aa5878b5bb75058c7a8af77 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -61,13 +61,13 @@ Free Documentation License''.
 @menu
 * About::                            About OpenOCD
 * Developers::                       OpenOCD Developer Resources
 @menu
 * About::                            About OpenOCD
 * Developers::                       OpenOCD Developer Resources

-* JTAG Hardware Dongles::            JTAG Hardware Dongles
+* Debug Adapter Hardware::           Debug Adapter Hardware

 * About JIM-Tcl::                    About JIM-Tcl
 * Running::                          Running OpenOCD
 * OpenOCD Project Setup::            OpenOCD Project Setup
 * Config File Guidelines::           Config File Guidelines
 * Daemon Configuration::             Daemon Configuration
 * About JIM-Tcl::                    About JIM-Tcl
 * Running::                          Running OpenOCD
 * OpenOCD Project Setup::            OpenOCD Project Setup
 * Config File Guidelines::           Config File Guidelines
 * Daemon Configuration::             Daemon Configuration

-* Interface - Dongle Configuration:: Interface - Dongle Configuration
+* Debug Adapter Configuration:: Debug Adapter Configuration

 * Reset Configuration::              Reset Configuration
 * TAP Declaration::                  TAP Declaration
 * CPU Configuration::                CPU Configuration
 * Reset Configuration::              Reset Configuration
 * TAP Declaration::                  TAP Declaration
 * CPU Configuration::                CPU Configuration


@@ -111,15 +111,47 @@ The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
 in-system programming and boundary-scan testing for embedded target
 devices.
 
 in-system programming and boundary-scan testing for embedded target
 devices.
 

-@b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
-with the JTAG (IEEE 1149.1) compliant TAPs on your target board.
+It does so with the assistance of a @dfn{debug adapter}, which is
+a small hardware module which helps provide the right kind of
+electrical signaling to the target being debugged.  These are
+required since the debug host (on which OpenOCD runs) won't
+usually have native support for such signaling, or the connector
+needed to hook up to the target.
+
+Such debug adapters support one or more @dfn{transport} protocols,
+each of which involves different electrical signaling (and uses
+different messaging protocols on top of that signaling).  There
+are many types of debug adapter, and little uniformity in what
+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
+host over USB (and sometimes also to power it over USB).
+
+For example, a @dfn{JTAG Adapter} supports JTAG
+signaling, and is used to communicate
+with JTAG (IEEE 1149.1) compliant TAPs on your target board.

 A @dfn{TAP} is a ``Test Access Port'', a module which processes
 special instructions and data.  TAPs are daisy-chained within and
 A @dfn{TAP} is a ``Test Access Port'', a module which processes
 special instructions and data.  TAPs are daisy-chained within and

-between chips and boards.
+between chips and boards.  JTAG supports debugging and boundary
+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
+debugging, whereas JTAG also supports boundary scan operations.
+
+For some chips, there are also @dfn{Programming Adapters} supporting
+special transports used only to write code to flash memory, without
+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{JTAG Hardware Dongles}.
+OpenOCD internally. @xref{Debug Adapter Hardware}.

 
 @b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
 ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
 
 @b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
 ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and


@@ -234,8 +266,8 @@ using Trac for its bug database:
 @uref{https://sourceforge.net/apps/trac/openocd}
 
 
 @uref{https://sourceforge.net/apps/trac/openocd}
 
 

-@node JTAG Hardware Dongles
-@chapter JTAG Hardware Dongles
+@node Debug Adapter Hardware
+@chapter Debug Adapter Hardware

 @cindex dongles
 @cindex FTDI
 @cindex wiggler
 @cindex dongles
 @cindex FTDI
 @cindex wiggler


@@ -247,9 +279,9 @@ using Trac for its bug database:
 Defined: @b{dongle}: A small device that plugins into a computer and serves as
 an adapter .... [snip]
 
 Defined: @b{dongle}: A small device that plugins into a computer and serves as
 an adapter .... [snip]
 

-In the OpenOCD case, this generally refers to @b{a small adapater} one
-attaches to your computer via USB or the Parallel Printer Port.  The
-execption being the Zylin ZY1000 which is a small box you attach via
+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
 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
 an ethernet cable. The Zylin 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


@@ -261,6 +293,9 @@ and has a built in relay to power cycle targets remotely.
 There are several things you should keep in mind when choosing a dongle.
 
 @enumerate
 There are several things you should keep in mind when choosing a dongle.
 
 @enumerate

+@item @b{Transport} Does it support the kind of communication that you need?
+OpenOCD focusses mostly on JTAG.  Your version may also support
+other ways to communicate with target devices.

 @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?


@@ -268,7 +303,8 @@ Does your dongle support it?  You may be able to use jumper
 wires, or an "octopus" connector, to convert pinouts.
 @item @b{Connection} Does your computer have the USB, printer, or
 Ethernet port needed?
 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 expect to use it with ARM chips and boards with
+RTCK support? Also known as ``adaptive clocking''

 @end enumerate
 
 @section Stand alone Systems
 @end enumerate
 
 @section Stand alone Systems


@@ -286,7 +322,17 @@ 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
 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.
+chips are starting to become available in JTAG adapters.  (Adapters
+using those high speed FT2232H chips may support adaptive clocking.)
+
+The FT2232 chips are flexible enough to support some other
+transport options, such as SWD or the SPI variants used to
+program some chips. They have two communications channels,
+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 coast debug adapter and usb-to-serial solution.

 
 @itemize @bullet
 @item @b{usbjtag}
 
 @itemize @bullet
 @item @b{usbjtag}


@@ -303,11 +349,11 @@ chips are starting to become available in JTAG adapters.
 @* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
 bundle FT2232-based JTAG and SWD support, which can be used to debug
 the Stellaris chips.  Using separate JTAG adapters is optional.
 @* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
 bundle FT2232-based JTAG and SWD support, which can be used to debug
 the Stellaris chips.  Using separate JTAG adapters is optional.

-These boards can also be used as JTAG adapters to other target boards,
-disabling the Stellaris chip.
+These boards can also be used in a "pass through" mode as JTAG adapters
+to other target boards, disabling the Stellaris chip.

 @item @b{Luminary ICDI}
 @* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug
 @item @b{Luminary ICDI}
 @* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug

-Interface (ICDI) Boards are included in Stellaris LM3S9B90 and LM3S9B92
+Interface (ICDI) Boards are included in Stellaris LM3S9B9x

 Evaluation Kits.  Like the non-detachable FT2232 support on the other
 Stellaris eval boards, they can be used to debug other target boards.
 @item @b{olimex-jtag}
 Evaluation Kits.  Like the non-detachable FT2232 support on the other
 Stellaris eval boards, they can be used to debug other target boards.
 @item @b{olimex-jtag}


@@ -507,7 +553,7 @@ as Tcl scripts, from a @file{startup.tcl} file internal to the server.
 @cindex directory search
 
 Properly installing OpenOCD sets up your operating system to grant it access
 @cindex directory search
 
 Properly installing OpenOCD sets up your operating system to grant it access

-to the JTAG adapters.  On Linux, this usually involves installing a file
+to the debug adapters.  On Linux, this usually involves installing a file

 in @file{/etc/udev/rules.d,} so OpenOCD has permissions.  MS-Windows needs
 complex and confusing driver configuration for every peripheral.  Such issues
 are unique to each operating system, and are not detailed in this User's Guide.
 in @file{/etc/udev/rules.d,} so OpenOCD has permissions.  MS-Windows needs
 complex and confusing driver configuration for every peripheral.  Such issues
 are unique to each operating system, and are not detailed in this User's Guide.


@@ -798,7 +844,7 @@ Three main types of non-user configuration file each have their
 own subdirectory in the @file{scripts} directory:
 
 @enumerate
 own subdirectory in the @file{scripts} directory:
 
 @enumerate

-@item @b{interface} -- one for each kind of JTAG adapter/dongle
+@item @b{interface} -- one for each different debug adapter;

 @item @b{board} -- one for each different board
 @item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
 @end enumerate
 @item @b{board} -- one for each different board
 @item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
 @end enumerate


@@ -823,7 +869,8 @@ the board differences are encapsulated by application code.
 @item Maybe you don't know yet what your board looks like to JTAG.
 Once you know the @file{interface.cfg} file to use, you may
 need help from OpenOCD to discover what's on the board.
 @item Maybe you don't know yet what your board looks like to JTAG.
 Once you know the @file{interface.cfg} file to use, you may
 need help from OpenOCD to discover what's on the board.

-Once you find the TAPs, you can just search for appropriate
+Once you find the JTAG TAPs, you can just search for appropriate
+target and board

 configuration files ... or write your own, from the bottom up.
 @xref{Autoprobing}.
 
 configuration files ... or write your own, from the bottom up.
 @xref{Autoprobing}.
 


@@ -849,7 +896,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
 @item
 You may may need to write some C code.
 It may be as simple as a supporting a new ft2232 or parport

-based dongle; a bit more involved, like a NAND or NOR flash
+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.
 @end itemize
 controller driver; or a big piece of work like supporting
 a new chip architecture.
 @end itemize


@@ -1141,7 +1188,8 @@ with files including the ones listed here.
 Use them as-is where you can; or as models for new files.
 @itemize @bullet
 @item @file{interface} ...
 Use them as-is where you can; or as models for new files.
 @itemize @bullet
 @item @file{interface} ...

-think JTAG Dongle. Files that configure JTAG adapters go here.
+These are for debug adapters.
+Files that configure JTAG adapters go here.

 @example
 $ ls interface
 arm-jtag-ew.cfg          hitex_str9-comstick.cfg  oocdlink.cfg
 @example
 $ ls interface
 arm-jtag-ew.cfg          hitex_str9-comstick.cfg  oocdlink.cfg


@@ -1252,13 +1300,15 @@ should be able to source one of these files with a command like this:
 source [find interface/FOOBAR.cfg]
 @end example
 
 source [find interface/FOOBAR.cfg]
 @end example
 

-A preconfigured interface file should exist for every interface in use
-today, that said, perhaps some interfaces have only been used by the
-sole developer who created it.
+A preconfigured interface file should exist for every debug adapter
+in use today with OpenOCD.
+That said, perhaps some of these config files
+have only been used by the developer who created it.

 
 A separate chapter gives information about how to set these up.
 
 A separate chapter gives information about how to set these up.

-@xref{Interface - Dongle Configuration}.
-Read the OpenOCD source code if you have a new kind of hardware interface
+@xref{Debug Adapter Configuration}.
+Read the OpenOCD source code (and Developer's GUide)
+if you have a new kind of hardware interface

 and need to provide a driver for it.
 
 @section Board Config Files
 and need to provide a driver for it.
 
 @section Board Config Files


@@ -1987,16 +2037,26 @@ MMU: disabled, D-Cache: disabled, I-Cache: enabled
 @end example
 @end deffn
 
 @end example
 @end deffn
 

-@node Interface - Dongle Configuration
-@chapter Interface - Dongle Configuration
+@node Debug Adapter Configuration
+@chapter Debug Adapter Configuration

 @cindex config file, interface
 @cindex interface config file
 
 Correctly installing OpenOCD includes making your operating system give
 @cindex config file, interface
 @cindex interface config file
 
 Correctly installing OpenOCD includes making your operating system give

-OpenOCD access to JTAG adapters.  Once that has been done, Tcl commands
+OpenOCD access to debug adapters.  Once that has been done, Tcl commands

 are used to select which one is used, and to configure how it is used.
 
 are used to select which one is used, and to configure how it is used.
 

-JTAG Adapters/Interfaces/Dongles are normally configured
+@quotation Note
+Because OpenOCD started out with a focus purely on JTAG, you may find
+places where it wrongly presumes JTAG is the only transport protocol
+in use.  Be aware that recent versions of OpenOCD are removing that
+limitation.  JTAG remains more functional than most other transports.
+Other transports do not support boundary scan operations, or may be
+specific to a given chip vendor.  Some might be usable only for
+programming flash memory, instead of also for debugging.
+@end quotation
+
+Debug Adapters/Interfaces/Dongles are normally configured

 through commands in an interface configuration
 file which is sourced by your @file{openocd.cfg} file, or
 through a command line @option{-f interface/....cfg} option.
 through commands in an interface configuration
 file which is sourced by your @file{openocd.cfg} file, or
 through a command line @option{-f interface/....cfg} option.


@@ -2019,9 +2079,9 @@ Most adapters need a bit more configuration than that.
 
 @section Interface Configuration
 
 
 @section Interface Configuration
 

-The interface command tells OpenOCD what type of JTAG dongle you are
-using. Depending on the type of dongle, you may need to have one or
-more additional commands.
+The interface command tells OpenOCD what type of debug adapter you are
+using. Depending on the type of adapter, you may need to use one or
+more additional commands to further identify or configure the adapter.

 
 @deffn {Config Command} {interface} name
 Use the interface driver @var{name} to connect to the
 
 @deffn {Config Command} {interface} name
 Use the interface driver @var{name} to connect to the


@@ -7161,8 +7221,8 @@ that 5 MHz JTAG clock be usable?
 @b{Solution #1 - A special circuit}
 
 In order to make use of this,
 @b{Solution #1 - A special circuit}
 
 In order to make use of this,

-both your CPU and your JTAG dongle must support the RTCK
-feature. Not all dongles support this - keep reading!
+your CPU, board, and JTAG adapter must all support the RTCK
+feature. Not all of them support this; keep reading!

 
 The RTCK ("Return TCK") signal in some ARM chips is used to help with
 this problem. ARM has a good description of the problem described at
 
 The RTCK ("Return TCK") signal in some ARM chips is used to help with
 this problem. ARM has a good description of the problem described at


@@ -7198,7 +7258,9 @@ depending on the chips on your board.
 ARM11 cores use an 8:1 division.
 @b{Xilinx rule of thumb} is 1/12 the clock speed.
 
 ARM11 cores use 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: most full speed FT2232 based JTAG adapters are limited to a
+maximum of 6MHz.  The ones using USB high speed chips (FT2232H)
+often support faster clock rates (and adaptive clocking).

 
 You can still debug the 'low power' situations - you just need to
 either use a fixed and very slow JTAG clock rate ... or else
 
 You can still debug the 'low power' situations - you just need to
 either use a fixed and very slow JTAG clock rate ... or else

diff --git a/tcl/board/at91sam9g20-ek.cfg b/tcl/board/at91sam9g20-ek.cfg
index b0fe54620258b8c34c83d256b4c0ed9024863365..fb6068cc6369751044f568ed19a835c73c8c81d8 100644 (file)
--- a/tcl/board/at91sam9g20-ek.cfg
+++ b/tcl/board/at91sam9g20-ek.cfg
@@ -28,8 +28,9 @@ reset_config trst_and_srst
 
 jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID
 
 
 jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID
 

-# Use caution changing the delays listed below.  These seem to be affected by the board and type of
-# debugger dongle.  A value of 200 ms seems to work reliably for the configuration listed in the file header above.
+# Use caution changing the delays listed below.  These seem to be
+# affected by the board and type of JTAG adapter.  A value of 200 ms seems
+# to work reliably for the configuration listed in the file header above.

 
 jtag_nsrst_delay 200
 jtag_ntrst_delay 200
 
 jtag_nsrst_delay 200
 jtag_ntrst_delay 200