X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=5977c40944f871d53c665dee0a075697532f005f;hb=2934ac454e32b21b1bd624189745d9f21ee79b46;hp=372683a9ccc2e1313f1d47339479ed22c77f2bac;hpb=1eae39b40d5338e96194ad3c83949718a857a2a2;p=openocd.git

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 372683a9cc..5977c40944 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2408,11 +2408,10 @@ This driver is for adapters using the MPSSE (Multi-Protocol Synchronous Serial
 Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H.
 
 The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device,
-bypassing intermediate libraries like libftdi of D2XX.
+bypassing intermediate libraries like libftdi or D2XX.
 
-A major improvement of this driver is that support for new FTDI based adapters
-can be added competely through configuration files, without the need to patch
-and rebuild OpenOCD.
+Support for new FTDI based adapters can be added competely through
+configuration files, without the need to patch and rebuild OpenOCD.
 
 The driver uses a signal abstraction to enable Tcl configuration files to
 define outputs for one or several FTDI GPIO. These outputs can then be
@@ -2421,6 +2420,12 @@ are reserved for nTRST, nSRST and LED (for blink) so that they, if defined,
 will be used for their customary purpose. Inputs can be read using the
 @command{ftdi_get_signal} command.
 
+To support SWD, a signal named SWD_EN must be defined. It is set to 1 when the
+SWD protocol is selected. When set, the adapter should route the SWDIO pin to
+the data input. An SWDIO_OE signal, if defined, will be set to 1 or 0 as
+required by the protocol, to tell the adapter to drive the data output onto
+the SWDIO pin or keep the SWDIO pin Hi-Z, respectively.
+
 Depending on the type of buffer attached to the FTDI GPIO, the outputs have to
 be controlled differently. In order to support tristateable signals such as
 nSRST, both a data GPIO and an output-enable GPIO can be specified for each
@@ -2439,9 +2444,8 @@ These interfaces have several commands, used to configure the driver
 before initializing the JTAG scan chain:
 
 @deffn {Config Command} {ftdi_vid_pid} [vid pid]+
-The vendor ID and product ID of the adapter. If not specified, the FTDI
-default values are used.
-Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
+The vendor ID and product ID of the adapter. Up to eight
+[@var{vid}, @var{pid}] pairs may be given, e.g.
 @example
 ftdi_vid_pid 0x0403 0xcff8 0x15ba 0x0003
 @end example
@@ -2702,6 +2706,26 @@ Reset the current configuration.
 @deffn {Command} {jlink config write}
 Write the current configuration to the internal persistent storage.
 @end deffn
+@deffn {Command} {jlink emucom write <channel> <data>}
+Write data to an EMUCOM channel. The data needs to be encoded as hexadecimal
+pairs.
+
+The following example shows how to write the three bytes 0xaa, 0x0b and 0x23 to
+the EMUCOM channel 0x10:
+@example
+> jlink emucom write 0x10 aa0b23
+@end example
+@end deffn
+@deffn {Command} {jlink emucom read <channel> <length>}
+Read data from an EMUCOM channel. The read data is encoded as hexadecimal
+pairs.
+
+The following example shows how to read 4 bytes from the EMUCOM channel 0x0:
+@example
+> jlink emucom read 0x0 4
+77a90000
+@end example
+@end deffn
 @deffn {Config} {jlink usb} <@option{0} to @option{3}>
 Set the USB address of the interface, in case more than one adapter is connected
 to the host. If not specified, USB addresses are not considered. Device
@@ -2912,6 +2936,27 @@ pinout.
 
 @end deffn
 
+@deffn {Interface Driver} {openjtag}
+OpenJTAG compatible USB adapter.
+This defines some driver-specific commands:
+
+@deffn {Config Command} {openjtag_variant} variant
+Specifies the variant of the OpenJTAG adapter (see @uref{http://www.openjtag.org/}).
+Currently valid @var{variant} values include:
+
+@itemize @minus
+@item @b{standard} Standard variant (default).
+@item @b{cy7c65215} Cypress CY7C65215 Dual Channel USB-Serial Bridge Controller
+(see @uref{http://www.cypress.com/?rID=82870}).
+@end itemize
+@end deffn
+
+@deffn {Config Command} {openjtag_device_desc} string
+The USB device description string of the adapter.
+This value is only used with the standard variant.
+@end deffn
+@end deffn
+
 @section Transport Configuration
 @cindex Transport
 As noted earlier, depending on the version of OpenOCD you use,
@@ -4122,15 +4167,19 @@ The value should normally correspond to a static mapping for the
 
 @anchor{rtostype}
 @item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
-@var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{ThreadX}|
-@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}|@option{mqx}|
-@option{uCOS-III}
+@var{rtos_type} can be one of @option{auto}, @option{eCos},
+@option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS},
+@option{embKernel}, @option{mqx}, @option{uCOS-III}
 @xref{gdbrtossupport,,RTOS Support}.
 
 @item @code{-defer-examine} -- skip target examination at initial JTAG chain
 scan and after a reset. A manual call to arp_examine is required to
 access the target for debugging.
 
+@item @code{-ap-num} @var{ap_number} -- set DAP access port for target,
+@var{ap_number} is the numeric index of the DAP AP the target is connected to.
+Use this option with systems where multiple, independent cores are connected
+to separate access ports of the same DAP.
 @end itemize
 @end deffn
 
@@ -4707,8 +4756,10 @@ the flash bank defined at address 0x1fc00000. Any cmds executed on
 the virtual banks are actually performed on the physical banks.
 @example
 flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME
-flash bank vbank0 virtual 0xbfc00000 0 0 0 $_TARGETNAME $_FLASHNAME
-flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME
+flash bank vbank0 virtual 0xbfc00000 0 0 0 \
+           $_TARGETNAME $_FLASHNAME
+flash bank vbank1 virtual 0x9fc00000 0 0 0 \
+           $_TARGETNAME $_FLASHNAME
 @end example
 @end deffn
 
@@ -4774,8 +4825,8 @@ Since signaling between JTAG and SPI is compatible, all that is required for
 a proxy bitstream is to connect TDI-MOSI, TDO-MISO, TCK-CLK and activate
 the flash chip select when the JTAG state machine is in SHIFT-DR. Such
 a bitstream for several Xilinx FPGAs can be found in
-@file{contrib/loaders/flash/fpga/xilinx_bscan_spi.py}. It requires migen
-(@url{http://github.com/m-labs/migen}) and a Xilinx toolchain to build.
+@file{contrib/loaders/flash/fpga/xilinx_bscan_spi.py}. It requires
+@uref{https://github.com/m-labs/migen, migen} and a Xilinx toolchain to build.
 
 This flash bank driver requires a target on a JTAG tap and will access that
 tap directly. Since no support from the target is needed, the target can be a
@@ -4798,7 +4849,8 @@ For the bitstreams generated from @file{xilinx_bscan_spi.py} this is the
 target create $_TARGETNAME testee -chain-position $_CHIPNAME.fpga
 set _XILINX_USER1 0x02
 set _DR_LENGTH 1
-flash bank $_FLASHNAME spi 0x0 0 0 0 $_TARGETNAME $_XILINX_USER1 $_DR_LENGTH
+flash bank $_FLASHNAME spi 0x0 0 0 0 \
+           $_TARGETNAME $_XILINX_USER1 $_DR_LENGTH
 @end example
 @end deffn
 
@@ -4904,7 +4956,8 @@ and the second bank starts after the first.
 # Flash bank 0
 flash bank $_FLASHNAME ambiqmicro 0 0x00040000 0 0 $_TARGETNAME
 # Flash bank 1 - same size as bank0, starts after bank 0.
-flash bank $_FLASHNAME ambiqmicro 0x00040000 0x00040000 0 0 $_TARGETNAME
+flash bank $_FLASHNAME ambiqmicro 0x00040000 0x00040000 0 0 \
+           $_TARGETNAME
 @end example
 
 Flash is programmed using custom entry points into the bootloader.
@@ -5178,8 +5231,10 @@ with @code{x} treated as wildcard and otherwise case (and any trailing
 characters) ignored.
 
 @example
-flash bank $@{_FLASHNAME@}0 fm4 0x00000000 0 0 0 $_TARGETNAME S6E2CCAJ0A
-flash bank $@{_FLASHNAME@}1 fm4 0x00100000 0 0 0 $_TARGETNAME S6E2CCAJ0A
+flash bank $@{_FLASHNAME@}0 fm4 0x00000000 0 0 0 \
+           $_TARGETNAME S6E2CCAJ0A
+flash bank $@{_FLASHNAME@}1 fm4 0x00100000 0 0 0 \
+           $_TARGETNAME S6E2CCAJ0A
 @end example
 @emph{The current implementation is incomplete. Protection is not supported,
 nor is Chip Erase (only Sector Erase is implemented).}
@@ -7404,6 +7459,17 @@ requests by using a special SVC instruction that is trapped at the
 Supervisor Call vector by OpenOCD.
 @end deffn
 
+@deffn Command {arm semihosting_fileio} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Display status of semihosting fileio, after optionally changing that
+status.
+
+Enabling this option forwards semihosting I/O to GDB process using the
+File-I/O remote protocol extension. This is especially useful for
+interacting with remote files or displaying console messages in the
+debugger.
+@end deffn
+
 @section ARMv4 and ARMv5 Architecture
 @cindex ARMv4
 @cindex ARMv5
@@ -8815,7 +8881,11 @@ end
 @anchor{gdbrtossupport}
 
 OpenOCD includes RTOS support, this will however need enabling as it defaults to disabled.
-It can be enabled by passing @option{-rtos} arg to the target @xref{rtostype,,RTOS Type}.
+It can be enabled by passing @option{-rtos} arg to the target. @xref{rtostype,,RTOS Type}.
+
+@xref{Threads, Debugging Programs with Multiple Threads,
+Debugging Programs with Multiple Threads, gdb, GDB manual}, for details about relevant
+GDB commands.
 
 @* An example setup is below: