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...)
---
doc/openocd.texi | 393 +++++++++++++++++++++++++++++------------------------
1 file changed, 216 insertions(+), 177 deletions(-)
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...)
---
doc/openocd.texi | 393 +++++++++++++++++++++++++++++------------------------
1 file changed, 216 insertions(+), 177 deletions(-)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1302,39 +1302,26 @@ use @var{enable} see these errors report
@node Interface - Dongle Configuration
@chapter Interface - Dongle Configuration
-Interface commands are normally found in an interface configuration
-file which is sourced by your openocd.cfg file. These commands tell
-OpenOCD what type of JTAG dongle you have and how to talk to it.
-...@section Simple Complete Interface Examples
-...@b{a Turtelizer FT2232 Based JTAG Dongle}
-...@verbatim
-#interface
-interface ft2232
-ft2232_device_desc "Turtelizer JTAG/RS232 Adapter A"
-ft2232_layout turtelizer2
-ft2232_vid_pid 0x0403 0xbdc8
-...@end verbatim
-...@b{a SEGGER Jlink}
-...@verbatim
+JTAG 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.
+
+...@example
+source [find interface/olimex-jtag-tiny.cfg]
+...@end example
+
+These commands tell
+OpenOCD what type of JTAG adapter you have, and how to talk to it.
+A few cases are so simple that you only need to say what driver to use:
+
+...@example
# jlink interface
interface jlink
-...@end verbatim
-...@b{a Raisonance RLink}
-...@verbatim
-# 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
+...@end example
+
+Most adapters need a bit more configuration than that.
+
@section Interface Configuration
@@ -1353,180 +1340,232 @@ Returns the name of the interface driver
@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}
-...@* PC parallel port bit-banging (Wigglers, PLD download cable, ...)
+...@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
-...@item @b{amt_jtagaccel}
-...@* Amontec Chameleon in its JTAG Accelerator configuration connected to a PC's EPP
-mode parallel port
+...@deffn {Config Command} rtck [...@option{enable}|@option{disable}]
+Displays status of RTCK option.
+Optionally sets that option first.
+...@end deffn
+...@end deffn
-...@item @b{ft2232}
-...@* FTDI FT2232 (USB) based devices using either the open-source libftdi or the binary only
-FTD2XX driver. The FTD2XX is superior in performance, but not available on every
-platform. The libftdi uses libusb, and should be portable to all systems that provide
-libusb.
+...@deffn {Interface Driver} {arm-jtag-ew}
+Olimex ARM-JTAG-EW USB adapter
+This has one driver-specific command:
-...@item @b{ep93xx}
-...@*cirrus Logic EP93xx based single-board computer bit-banging (in development)
+...@deffn Command {armjtagew_info}
+Logs some status
+...@end deffn
+...@end deffn
-...@item @b{presto}
-...@* ASIX PRESTO USB JTAG programmer.
+...@deffn {Interface Driver} {at91rm9200}
+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}
-...@* usbprog is a freely programmable USB adapter.
+...@deffn {Interface Driver} {dummy}
+A dummy software-only driver for debugging.
+...@end deffn
-...@item @b{gw16012}
-...@* Gateworks GW16012 JTAG programmer.
+...@deffn {Interface Driver} {ep93xx}
+Cirrus Logic EP93xx based single-board computer bit-banging (in development)
+...@end deffn
-...@item @b{jlink}
-...@* Segger jlink USB adapter
+...@deffn {Interface Driver} {ft2232}
+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}
-...@* Raisonance RLink USB adapter
+...@deffn {Config Command} {ft2232_device_desc} description
+Provides the USB device description (the @emph{iProduct string})
+of the FTDI FT2232 device. If not
+specified, the FTDI default value is used. This setting is only valid
+if compiled with FTD2XX support.
+...@end deffn
-...@item @b{vsllink}
-...@* vsllink is part of Versaloon which is a versatile USB programmer.
+...@deffn {Config Command} {ft2232_serial} serial-number
+Specifies the @var{serial-number} of the FTDI FT2232 device to use,
+in case the vendor provides unique IDs and more than one FT2232 device
+is connected to the host.
+If not specified, serial numbers are not considered.
+...@end deffn
-...@item @b{arm-jtag-ew}
-...@* Olimex ARM-JTAG-EW USB adapter
+...@deffn {Config Command} {ft2232_layout} name
+Each vendor's FT2232 device can use different GPIO signals
+to control output-enables, reset signals, and LEDs.
+Currently valid layout @var{name} values include:
+...@itemize @minus
+...@item @b{axm0432_jtag} Axiom AXM-0432
+...@item @b{comstick} Hitex STR9 comstick
+...@item @b{cortino} Hitex Cortino JTAG interface
+...@item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface
+(bypassing onboard processor), no TRST or SRST signals on external connector
+...@item @b{flyswatter} Tin Can Tools Flyswatter
+...@item @b{icebear} ICEbear JTAG adapter from Section 5
+...@item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
+...@item @b{m5960} American Microsystems M5960
+...@item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
+...@item @b{oocdlink} OOCDLink
+...@c oocdlink ~= jtagkey_prototype_v1
+...@item @b{sheevaplug} Marvell Sheevaplug development kit
+...@item @b{signalyzer} Xverve Signalyzer
+...@item @b{stm32stick} Hitex STM32 Performance Stick
+...@item @b{turtelizer2} egnite Software turtelizer2
+...@item @b{usbjtag} "USBJTAG-1" layout described in the OpenOCD diploma thesis
@end itemize
+...@end deffn
-...@subsection parport options
+...@deffn {Config Command} {ft2232_vid_pid} [vid pid]+
+The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
+default values are used.
+Currently, up to eight [...@var{vid}, @var{pid}] pairs may be given, e.g.
+...@example
+ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
+...@end example
+...@end deffn
-...@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
+...@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
+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
+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.
+...@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:
-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
+...@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}
-...@cindex dlc5
-The Xilinx Parallel cable III.
-...@item @b{triton}
-...@cindex triton
-The parallel port adapter found on the 'Karo Triton 1 Development Board'.
+...@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{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
+...@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 deffn
-...@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
+...@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
-...@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
-if compiled with FTD2XX support.
+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
-...@b{todo:} Confirm the following: On Windows the name needs to end with
-a ``space A''? Or not? It has to do with the FTD2xx driver. When must
-this be added and when must it not be added? Why can't the code in the
-interface or in OpenOCD automatically add this if needed? -- Duane.
+...@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
-...@item @b{ft2232_serial} <@var{serial-number}>
-...@cindex ft2232_serial
-...@*the serial number of the FTDI FT2232 device. If not specified, the FTDI default
-values are used.
-...@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
-...@item @b{usbjtag}
-"USBJTAG-1" layout described in the original OpenOCD diploma thesis
-...@item @b{jtagkey}
-Amontec JTAGkey and JTAGkey-Tiny
-...@item @b{signalyzer}
-Signalyzer
-...@item @b{olimex-jtag}
-Olimex ARM-USB-OCD
-...@item @b{m5960}
-American Microsystems M5960
-...@item @b{evb_lm3s811}
-Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST or
-SRST signals on external connector
-...@item @b{comstick}
-Hitex STR9 comstick
-...@item @b{stm32stick}
-Hitex STM32 Performance Stick
-...@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
+For example, the interface configuration file for a
+classic ``Wiggler'' cable might look something like this:
-...@item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}>
-...@*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.
@example
-ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
+interface parport
+parport_port 0xc8b8
+parport_cable wiggler
@end example
-...@item @b{ft2232_latency} <@var{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
-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
-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.
-...@end itemize
+...@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}
@section JTAG Speed
_______________________________________________
Openocd-development mailing list
[email protected]
https://lists.berlios.de/mailman/listinfo/openocd-development
