It is not to be confused with the FTDI based adapters that were originally fitted to their
evaluation boards. This is the adapter fitted to the Stellaris LaunchPad.
+@section USB Nuvoton Nu-Link
+Nuvoton has an adapter called @b{Nu-Link}.
+It is available either as stand-alone dongle and embedded on development boards.
+It supports SWD, serial port bridge and mass storage for firmware update.
+Both Nu-Link v1 and v2 are supported.
+
@section USB CMSIS-DAP based
ARM has released a interface standard called CMSIS-DAP that simplifies connecting
debuggers to ARM Cortex based targets @url{http://www.keil.com/support/man/docs/dapdebug/dapdebug_introduction.htm}.
@* Link: @url{http://www.keil.com/ulink1/}
@item @b{TI XDS110 Debug Probe}
-@* The XDS110 is included as the embedded debug probe on many Texas Instruments
-LaunchPad evaluation boards. The XDS110 is also available as a stand-alone USB
-debug probe with the added capability to supply power to the target board. The
-following commands are supported by the XDS110 driver:
-@*@deffn {Config Command} {xds110 serial} serial_string
-Specifies the serial number of which XDS110 probe to use. Otherwise, the first
-XDS110 found will be used.
-@end deffn
-@*@deffn {Config Command} {xds110 supply} voltage_in_millivolts
-Available only on the XDS110 stand-alone probe. Sets the voltage level of the
-XDS110 power supply. A value of 0 leaves the supply off. Otherwise, the supply
-can be set to any value in the range 1800 to 3600 millivolts.
-@end deffn
-@*@deffn {Command} {xds110 info}
-Displays information about the connected XDS110 debug probe (e.g. firmware
-version).
-@end deffn
-@* Further information can be found at the following sites:
@* Link: @url{https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds110.html}
@* Link: @url{https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds_software_package_download.html#xds110-support-utilities}
@end itemize
@* Link: @url{http://github.com/fjullien/jtag_vpi}
@item @b{xlnx_pcie_xvc}
-@* A JTAG driver exposing Xilinx Virtual Cable over PCI Express to OpenOCD as JTAG interface.
+@* A JTAG driver exposing Xilinx Virtual Cable over PCI Express to OpenOCD as JTAG/SWD interface.
@end itemize
@end quotation
@item
-You may may need to write some C code.
+You may need to write some C code.
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
board files may need to distinguish between instances of a chip.
@item @code{ENDIAN} ...
By default @option{little} - although chips may hard-wire @option{big}.
-Chips that can't change endianess don't need to use this variable.
+Chips that can't change endianness don't need to use this variable.
@item @code{CPUTAPID} ...
When OpenOCD examines the JTAG chain, it can be told verify the
chips against the JTAG IDCODE register.
This type of adapter does not expose some of the lower level api's
that OpenOCD would normally use to access the target.
-Currently supported adapters include the STMicroelectronics ST-LINK and TI ICDI.
+Currently supported adapters include the STMicroelectronics ST-LINK, TI ICDI
+and Nuvoton Nu-Link.
ST-LINK firmware version >= V2.J21.S4 recommended due to issues with earlier
versions of firmware where serial number is reset after first use. Suggest
using ST firmware update utility to upgrade ST-LINK firmware even if current
Specifies the serial number of the adapter.
@end deffn
-@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi})
+@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi}|@option{nulink})
Specifies the adapter layout to use.
@end deffn
This is the Keil ULINK v1 JTAG debugger.
@end deffn
+@deffn {Interface Driver} {xds110}
+The XDS110 is included as the embedded debug probe on many Texas Instruments
+LaunchPad evaluation boards. The XDS110 is also available as a stand-alone USB
+debug probe with the added capability to supply power to the target board. The
+following commands are supported by the XDS110 driver:
+
+@deffn {Config Command} {xds110 serial} serial_string
+Specifies the serial number of which XDS110 probe to use. Otherwise, the first
+XDS110 found will be used.
+@end deffn
+
+@deffn {Config Command} {xds110 supply} voltage_in_millivolts
+Available only on the XDS110 stand-alone probe. Sets the voltage level of the
+XDS110 power supply. A value of 0 leaves the supply off. Otherwise, the supply
+can be set to any value in the range 1800 to 3600 millivolts.
+@end deffn
+
+@deffn {Command} {xds110 info}
+Displays information about the connected XDS110 debug probe (e.g. firmware
+version).
+@end deffn
+@end deffn
+
@deffn {Interface Driver} {xlnx_pcie_xvc}
This driver supports the Xilinx Virtual Cable (XVC) over PCI Express.
It is commonly found in Xilinx based PCI Express designs. It allows debugging
-fabric based JTAG devices such as Cortex-M1/M3 microcontrollers. Access to this is
+fabric based JTAG/SWD devices such as Cortex-M1/M3 microcontrollers. Access to this is
exposed via extended capability registers in the PCI Express configuration space.
For more information see Xilinx PG245 (Section on From_PCIE_to_JTAG mode).
which uses four wire signaling. Some processors use it as part of a
solution for flash programming.
+@anchor{swimtransport}
+@subsection SWIM Transport
+@cindex SWIM
+@cindex Single Wire Interface Module
+The Single Wire Interface Module (SWIM) is a low-pin-count debug protocol used
+by the STMicroelectronics MCU family STM8 and documented in the
+@uref{https://www.st.com/resource/en/user_manual/cd00173911.pdf, User Manual UM470}.
+
+SWIM does not support boundary scan testing nor multiple cores.
+
+The SWIM transport is selected with the command @command{transport select swim}.
+
+The concept of TAPs does not fit in the protocol since SWIM does not implement
+a scan chain. Nevertheless, the current SW model of OpenOCD requires defining a
+virtual SWIM TAP through the command @command{swim newtap basename tap_type}.
+The TAP definition must precede the target definition command
+@command{target create target_name stm8 -chain-position basename.tap_type}.
+
@anchor{jtagspeed}
@section JTAG Speed
JTAG clock setup is part of system setup.
@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}, @option{nuttx}
+@option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx},
+@option{RIOT}
@xref{gdbrtossupport,,RTOS Support}.
@item @code{-defer-examine} -- skip target examination at initial JTAG chain
@deffn Command {at91samd dsu_reset_deassert}
This command releases internal reset held by DSU
and prepares reset vector catch in case of reset halt.
-Command is used internally in event event reset-deassert-post.
+Command is used internally in event reset-deassert-post.
@end deffn
@deffn Command {at91samd nvmuserrow}
@deffn Command {at91sam4l smap_reset_deassert}
This command releases internal reset held by SMAP
and prepares reset vector catch in case of reset halt.
-Command is used internally in event event reset-deassert-post.
+Command is used internally in event reset-deassert-post.
@end deffn
@end deffn
@deffn Command {atsame5 dsu_reset_deassert}
This command releases internal reset held by DSU
and prepares reset vector catch in case of reset halt.
-Command is used internally in event event reset-deassert-post.
+Command is used internally in event reset-deassert-post.
@end deffn
@deffn Command {atsame5 userpage}
@end deffn
@deffn Command {nrf5 info}
-Decodes and shows informations from FICR and UICR registers.
+Decodes and shows information from FICR and UICR registers.
@end deffn
@end deffn
@itemize
@item @var{type} ... describing how data accesses are traced,
-when they pass any ViewData filtering that that was set up.
+when they pass any ViewData filtering that was set up.
The value is one of
@option{none} (save nothing),
@option{data} (save data),
@deffn Command {arm7_9 dbgrq} [@option{enable}|@option{disable}]
Displays the value of the flag controlling use of the
-the EmbeddedIce DBGRQ signal to force entry into debug mode,
+EmbeddedIce DBGRQ signal to force entry into debug mode,
instead of breakpoints.
If a boolean parameter is provided, first assigns that flag.
@item @code{-g}
@* If specified then this is a "general" register. General registers are always
read by OpenOCD on context save (when core has just been halted) and is always
-transfered to GDB client in a response to g-packet. Contrary to this,
+transferred to GDB client in a response to g-packet. Contrary to this,
non-general registers are read and sent to GDB client on-demand. In general it
is not recommended to apply this option to custom registers.
@end deffn
@deffn {Command} {arc jtag set-core-reg} regnum value
-This command is similiar to @command{arc jtag set-aux-reg} but is for core
+This command is similar to @command{arc jtag set-aux-reg} but is for core
registers.
@end deffn
@end deffn
@deffn {Command} {arc jtag get-core-reg} regnum
-This command is similiar to @command{arc jtag get-aux-reg} but is for core
+This command is similar to @command{arc jtag get-aux-reg} but is for core
registers.
@end deffn
+@section STM8 Architecture
+@uref{http://st.com/stm8/, STM8} is a 8-bit microcontroller platform from
+STMicroelectronics, based on a proprietary 8-bit core architecture.
+
+OpenOCD supports debugging STM8 through the STMicroelectronics debug
+protocol SWIM, @pxref{swimtransport,,SWIM}.
@anchor{softwaredebugmessagesandtracing}
@section Software Debug Messages and Tracing
@item
A socket (TCP/IP) connection is typically started as follows:
@example
-target remote localhost:3333
+target extended-remote localhost:3333
@end example
This would cause GDB to connect to the gdbserver on the local pc using port 3333.
-It is also possible to use the GDB extended remote protocol as follows:
+The extended remote protocol is a super-set of the remote protocol and should
+be the preferred choice. More details are available in GDB documentation
+@url{https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html}
+
+To speed-up typing, any GDB command can be abbreviated, including the extended
+remote command above that becomes:
@example
-target extended-remote localhost:3333
+tar ext :3333
@end example
+
+@b{Note:} If any backward compatibility issue requires using the old remote
+protocol in place of the extended remote one, the former protocol is still
+available through the command:
+@example
+target remote localhost:3333
+@end example
+
@item
A pipe connection is typically started as follows:
@example
-target remote | openocd -c "gdb_port pipe; log_output openocd.log"
+target extended-remote | openocd -c "gdb_port pipe; log_output openocd.log"
@end example
This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout).
Using this method has the advantage of GDB starting/stopping OpenOCD for the debug
@example
$ arm-none-eabi-gdb example.elf
-(gdb) target remote localhost:3333
+(gdb) target extended-remote localhost:3333
Remote debugging using localhost:3333
...
(gdb) monitor reset halt
If you switched gdb_memory_map off, you may want to setup GDB memory map
manually or issue @command{set mem inaccessible-by-default off}
-Now you can issue GDB command @command{target remote ...} and inspect memory
+Now you can issue GDB command @command{target extended-remote ...} and inspect memory
of a running target. Do not use GDB commands @command{continue},
@command{step} or @command{next} as they synchronize GDB with your target
and GDB would require stopping the target to get the prompt back.
@item @option{mqx}
@item @option{uCOS-III}
@item @option{nuttx}
+@item @option{RIOT}
@item @option{hwthread} (This is not an actual RTOS. @xref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}.)
@end itemize
OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty
@item nuttx symbols
g_readytorun, g_tasklisttable
+@item RIOT symbols
+sched_threads, sched_num_threads, sched_active_pid, max_threads, _tcb_name_offset
@end table
For most RTOS supported the above symbols will be exported by default. However for
projects / fw / openocd / blobdiff