interesting
/
riscv-openocd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

David Brownell <david-b@pacbell.net>: 

Convert the Interface/Dongle Config chapter's section
on drivers to use the @deffn syntax, and integrate the
presentation of the driver-specific commands with the
relevant driver.  Alphabetize.

Cross-checked against the code ... several adapters were
not listed, and a few commands weren't.

(Maintainers for the versaloon and zy1000 drivers would be
good candidates to add the commands missing from those
sections...)


git-svn-id: svn://svn.berlios.de/openocd/trunk@2035 b42882b7-edfa-0310-969c-e2dbd0fdcd60
This commit is contained in:
zwelch 2009-06-04 00:54:25 +00:00
parent b619b7466f
commit 99fbbdc9c4
1 changed files with 218 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

397
doc/openocd.texi
View File

@ -1302,39 +1302,26 @@ use @var{enable} see these errors reported.
@node Interface - Dongle Configuration @node Interface - Dongle Configuration
@chapter Interface - Dongle Configuration @chapter Interface - Dongle Configuration
Interface commands are normally found in an interface configuration JTAG Adapters/Interfaces/Dongles are normally configured
file which is sourced by your openocd.cfg file. These commands tell through commands in an interface configuration
OpenOCD what type of JTAG dongle you have and how to talk to it. file which is sourced by your @file{openocd.cfg} file, or
@section Simple Complete Interface Examples through a command line @option{-f interface/....cfg} option.
@b{A Turtelizer FT2232 Based JTAG Dongle}
@verbatim @example
#interface source [find interface/olimex-jtag-tiny.cfg]
interface ft2232 @end example
ft2232_device_desc "Turtelizer JTAG/RS232 Adapter A"
ft2232_layout turtelizer2 These commands tell
ft2232_vid_pid 0x0403 0xbdc8 OpenOCD what type of JTAG adapter you have, and how to talk to it.
@end verbatim A few cases are so simple that you only need to say what driver to use:
@b{A SEGGER Jlink}
@verbatim @example
# jlink interface # jlink interface
interface jlink interface jlink
@end verbatim @end example
@b{A Raisonance RLink}
@verbatim Most adapters need a bit more configuration than that.
# rlink interface
interface rlink
@end verbatim
@b{Parallel Port}
@verbatim
interface parport
parport_port 0xc8b8
parport_cable wiggler
jtag_speed 0
@end verbatim
@b{ARM-JTAG-EW}
@verbatim
interface arm-jtag-ew
@end verbatim
@section Interface Configuration @section Interface Configuration
@ -1353,180 +1340,232 @@ Returns the name of the interface driver being used.
@section Interface Drivers @section Interface Drivers
Currently supported interface drivers are: Each of the interface drivers listed here must be explicitly
enabled when OpenOCD is configured, in order to be made
available at run time.
@itemize @minus @deffn {Interface Driver} {amt_jtagaccel}
Amontec Chameleon in its JTAG Accelerator configuration,
connected to a PC's EPP mode parallel port.
This defines some driver-specific commands:
@item @b{parport} @deffn {Config Command} {parport_port} number
@* PC parallel port bit-banging (Wigglers, PLD download cable, ...) Specifies either the address of the I/O port (default: 0x378 for LPT1) or
the number of the @file{/dev/parport} device.
@end deffn
@item @b{amt_jtagaccel} @deffn {Config Command} rtck [@option{enable}|@option{disable}]
@* Amontec Chameleon in its JTAG Accelerator configuration connected to a PC's EPP Displays status of RTCK option.
mode parallel port Optionally sets that option first.
@end deffn
@end deffn
@item @b{ft2232} @deffn {Interface Driver} {arm-jtag-ew}
@* FTDI FT2232 (USB) based devices using either the open-source libftdi or the binary only Olimex ARM-JTAG-EW USB adapter
FTD2XX driver. The FTD2XX is superior in performance, but not available on every This has one driver-specific command:
platform. The libftdi uses libusb, and should be portable to all systems that provide
libusb.
@item @b{ep93xx} @deffn Command {armjtagew_info}
@*Cirrus Logic EP93xx based single-board computer bit-banging (in development) Logs some status
@end deffn
@end deffn
@item @b{presto} @deffn {Interface Driver} {at91rm9200}
@* ASIX PRESTO USB JTAG programmer. Supports bitbanged JTAG from the local system,
presuming that system is an Atmel AT91rm9200
and a specific set of GPIOs is used.
@c command: at91rm9200_device NAME
@c chooses among list of bit configs ... only one option
@end deffn
@item @b{usbprog} @deffn {Interface Driver} {dummy}
@* usbprog is a freely programmable USB adapter. A dummy software-only driver for debugging.
@end deffn
@item @b{gw16012} @deffn {Interface Driver} {ep93xx}
@* Gateworks GW16012 JTAG programmer. Cirrus Logic EP93xx based single-board computer bit-banging (in development)
@end deffn
@item @b{jlink} @deffn {Interface Driver} {ft2232}
@* Segger jlink USB adapter FTDI FT2232 (USB) based devices over one of the userspace libraries.
These interfaces have several commands, used to configure the driver
before initializing the JTAG scan chain:
@item @b{rlink} @deffn {Config Command} {ft2232_device_desc} description
@* Raisonance RLink USB adapter Provides the USB device description (the @emph{iProduct string})
of the FTDI FT2232 device. If not
@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
@end itemize
@subsection parport options
@itemize @bullet
@item @b{parport_port} <@var{number}>
@cindex parport_port
@*Either the address of the I/O port (default: 0x378 for LPT1) or the number of
the @file{/dev/parport} device
When using PPDEV to access the parallel port, use the number of the parallel port:
@option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
you may encounter a problem.
@item @b{parport_cable} <@var{name}>
@cindex parport_cable
@*The layout of the parallel port cable used to connect to the target.
Currently supported cables are
@itemize @minus
@item @b{wiggler}
@cindex wiggler
The original Wiggler layout, also supported by several clones, such
as the Olimex ARM-JTAG
@item @b{wiggler2}
@cindex wiggler2
Same as original wiggler except an led is fitted on D5.
@item @b{wiggler_ntrst_inverted}
@cindex wiggler_ntrst_inverted
Same as original wiggler except TRST is inverted.
@item @b{old_amt_wiggler}
@cindex old_amt_wiggler
The Wiggler configuration that comes with Amontec's Chameleon Programmer. The new
version available from the website uses the original Wiggler layout ('@var{wiggler}')
@item @b{chameleon}
@cindex chameleon
The Amontec Chameleon's CPLD when operated in configuration mode. This is only used to
program the Chameleon itself, not a connected target.
@item @b{dlc5}
@cindex dlc5
The Xilinx Parallel cable III.
@item @b{triton}
@cindex triton
The parallel port adapter found on the 'Karo Triton 1 Development Board'.
This is also the layout used by the HollyGates design
(see @uref{http://www.lartmaker.nl/projects/jtag/}).
@item @b{flashlink}
@cindex flashlink
The ST Parallel cable.
@item @b{arm-jtag}
@cindex arm-jtag
Same as original wiggler except SRST and TRST connections reversed and
TRST is also inverted.
@item @b{altium}
@cindex altium
Altium Universal JTAG cable.
@end itemize
@item @b{parport_write_on_exit} <@var{on}|@var{off}>
@cindex parport_write_on_exit
@*This will configure the parallel driver to write a known value to the parallel
interface on exiting OpenOCD
@end itemize
@subsection amt_jtagaccel options
@itemize @bullet
@item @b{parport_port} <@var{number}>
@cindex parport_port
@*Either the address of the I/O port (default: 0x378 for LPT1) or the number of the
@file{/dev/parport} device
@end itemize
@subsection ft2232 options
@itemize @bullet
@item @b{ft2232_device_desc} <@var{description}>
@cindex ft2232_device_desc
@*The USB device description of the FTDI FT2232 device. If not
specified, the FTDI default value is used. This setting is only valid specified, the FTDI default value is used. This setting is only valid
if compiled with FTD2XX support. if compiled with FTD2XX support.
@end deffn
@b{TODO:} Confirm the following: On Windows the name needs to end with @deffn {Config Command} {ft2232_serial} serial-number
a ``space A''? Or not? It has to do with the FTD2xx driver. When must Specifies the @var{serial-number} of the FTDI FT2232 device to use,
this be added and when must it not be added? Why can't the code in the in case the vendor provides unique IDs and more than one FT2232 device
interface or in OpenOCD automatically add this if needed? -- Duane. is connected to the host.
If not specified, serial numbers are not considered.
@end deffn
@item @b{ft2232_serial} <@var{serial-number}> @deffn {Config Command} {ft2232_layout} name
@cindex ft2232_serial Each vendor's FT2232 device can use different GPIO signals
@*The serial number of the FTDI FT2232 device. If not specified, the FTDI default to control output-enables, reset signals, and LEDs.
values are used. Currently valid layout @var{name} values include:
@item @b{ft2232_layout} <@var{name}>
@cindex ft2232_layout
@*The layout of the FT2232 GPIO signals used to control output-enables and reset
signals. Valid layouts are
@itemize @minus @itemize @minus
@item @b{usbjtag} @item @b{axm0432_jtag} Axiom AXM-0432
"USBJTAG-1" layout described in the original OpenOCD diploma thesis @item @b{comstick} Hitex STR9 comstick
@item @b{jtagkey} @item @b{cortino} Hitex Cortino JTAG interface
Amontec JTAGkey and JTAGkey-Tiny @item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface
@item @b{signalyzer} (bypassing onboard processor), no TRST or SRST signals on external connector
Signalyzer @item @b{flyswatter} Tin Can Tools Flyswatter
@item @b{olimex-jtag} @item @b{icebear} ICEbear JTAG adapter from Section 5
Olimex ARM-USB-OCD @item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
@item @b{m5960} @item @b{m5960} American Microsystems M5960
American Microsystems M5960 @item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
@item @b{evb_lm3s811} @item @b{oocdlink} OOCDLink
Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST or @c oocdlink ~= jtagkey_prototype_v1
SRST signals on external connector @item @b{sheevaplug} Marvell Sheevaplug development kit
@item @b{comstick} @item @b{signalyzer} Xverve Signalyzer
Hitex STR9 comstick @item @b{stm32stick} Hitex STM32 Performance Stick
@item @b{stm32stick} @item @b{turtelizer2} egnite Software turtelizer2
Hitex STM32 Performance Stick @item @b{usbjtag} "USBJTAG-1" layout described in the OpenOCD diploma thesis
@item @b{flyswatter}
Tin Can Tools Flyswatter
@item @b{turtelizer2}
egnite Software turtelizer2
@item @b{oocdlink}
OOCDLink
@item @b{axm0432_jtag}
Axiom AXM-0432
@item @b{cortino}
Hitex Cortino JTAG interface
@end itemize @end itemize
@end deffn
@item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}> @deffn {Config Command} {ft2232_vid_pid} [vid pid]+
@*The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
default values are used. Multiple <@var{vid}>, <@var{pid}> pairs may be given, e.g. default values are used.
Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
@example @example
ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003 ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
@end example @end example
@item @b{ft2232_latency} <@var{ms}> @end deffn
@*On some systems using FT2232 based JTAG interfaces the FT_Read function call in
@deffn {Config Command} {ft2232_latency} ms
On some systems using FT2232 based JTAG interfaces the FT_Read function call in
ft2232_read() fails to return the expected number of bytes. This can be caused by ft2232_read() fails to return the expected number of bytes. This can be caused by
USB communication delays and has proved hard to reproduce and debug. Setting the USB communication delays and has proved hard to reproduce and debug. Setting the
FT2232 latency timer to a larger value increases delays for short USB packets but it FT2232 latency timer to a larger value increases delays for short USB packets but it
also reduces the risk of timeouts before receiving the expected number of bytes. also reduces the risk of timeouts before receiving the expected number of bytes.
The OpenOCD default value is 2 and for some systems a value of 10 has proved useful. The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
@end deffn
For example, the interface config file for a
Turtelizer JTAG Adapter looks something like this:
@example
interface ft2232
ft2232_device_desc "Turtelizer JTAG/RS232 Adapter"
ft2232_layout turtelizer2
ft2232_vid_pid 0x0403 0xbdc8
@end example
@end deffn
@deffn {Interface Driver} {gw16012}
Gateworks GW16012 JTAG programmer.
This has one driver-specific command:
@deffn {Config Command} {parport_port} number
Specifies either the address of the I/O port (default: 0x378 for LPT1) or
the number of the @file{/dev/parport} device.
@end deffn
@end deffn
@deffn {Interface Driver} {jlink}
Segger jlink USB adapter
@c command: jlink_info
@c dumps status
@c command: jlink_hw_jtag (2|3)
@c sets version 2 or 3
@end deffn
@deffn {Interface Driver} {parport}
Supports PC parallel port bit-banging cables:
Wigglers, PLD download cable, and more.
These interfaces have several commands, used to configure the driver
before initializing the JTAG scan chain:
@deffn {Config Command} {parport_cable} name
The layout of the parallel port cable used to connect to the target.
Currently valid cable @var{name} values include:
@itemize @minus
@item @b{altium} Altium Universal JTAG cable.
@item @b{arm-jtag} Same as original wiggler except SRST and
TRST connections reversed and TRST is also inverted.
@item @b{chameleon} The Amontec Chameleon's CPLD when operated
in configuration mode. This is only used to
program the Chameleon itself, not a connected target.
@item @b{dlc5} The Xilinx Parallel cable III.
@item @b{flashlink} The ST Parallel cable.
@item @b{lattice} Lattice ispDOWNLOAD Cable
@item @b{old_amt_wiggler} The Wiggler configuration that comes with
some versions of
Amontec's Chameleon Programmer. The new version available from
the website uses the original Wiggler layout ('@var{wiggler}')
@item @b{triton} The parallel port adapter found on the
``Karo Triton 1 Development Board''.
This is also the layout used by the HollyGates design
(see @uref{http://www.lartmaker.nl/projects/jtag/}).
@item @b{wiggler} The original Wiggler layout, also supported by
several clones, such as the Olimex ARM-JTAG
@item @b{wiggler2} Same as original wiggler except an led is fitted on D5.
@item @b{wiggler_ntrst_inverted} Same as original wiggler except TRST is inverted.
@end itemize @end itemize
@end deffn
@deffn {Config Command} {parport_port} number
Either the address of the I/O port (default: 0x378 for LPT1) or the number of
the @file{/dev/parport} device
When using PPDEV to access the parallel port, use the number of the parallel port:
@option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
you may encounter a problem.
@end deffn
@deffn {Config Command} {parport_write_on_exit} (on|off)
This will configure the parallel driver to write a known
cable-specific value to the parallel interface on exiting OpenOCD
@end deffn
For example, the interface configuration file for a
classic ``Wiggler'' cable might look something like this:
@example
interface parport
parport_port 0xc8b8
parport_cable wiggler
@end example
@end deffn
@deffn {Interface Driver} {presto}
ASIX PRESTO USB JTAG programmer.
@c command: presto_serial str
@c sets serial number
@end deffn
@deffn {Interface Driver} {rlink}
Raisonance RLink USB adapter
@end deffn
@deffn {Interface Driver} {usbprog}
usbprog is a freely programmable USB adapter.
@end deffn
@deffn {Interface Driver} {vsllink}
vsllink is part of Versaloon which is a versatile USB programmer.
@quotation Note
This defines quite a few driver-specific commands,
which are not currently documented here.
@end quotation
@end deffn
@deffn {Interface Driver} {ZY1000}
This is the Zylin ZY1000 JTAG debugger.
@quotation Note
This defines some driver-specific commands,
which are not currently documented here.
@end quotation
@end deffn
@anchor{JTAG Speed} @anchor{JTAG Speed}
@section JTAG Speed @section JTAG Speed