@* 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.
@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.
@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.
Code Review / openocd.git / blobdiff