X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=9f20e391d272230c199f2c77ced75213d85ab1f3;hb=e8cfdd4a7208c4c2e7713eff46edecb4abbe37d6;hp=250db326f2a64b4f39ee03213a6f312a0f88f9f8;hpb=d6541a811dc32beafbb388a01289366f1f31fc00;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 250db326f2..9f20e391d2 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -536,24 +536,6 @@ debuggers to ARM Cortex based targets @url{http://www.keil.com/support/man/docs/ @* 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 @@ -628,7 +610,7 @@ produced, PDF schematics are easily found and it is easy to make. @* 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 @@ -1492,7 +1474,7 @@ While the default is normally provided by the chip manufacturer, 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. @@ -3141,10 +3123,33 @@ opendous-jtag is a freely programmable USB adapter. 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). @@ -3299,6 +3304,24 @@ The Serial Peripheral Interface (SPI) is a general purpose transport 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. @@ -4924,6 +4947,10 @@ when reset disables PLLs needed to use a fast clock. @* After all targets have resumed @item @b{resumed} @* Target has resumed +@item @b{step-start} +@* Before a target is single-stepped +@item @b{step-end} +@* After single-step has completed @item @b{trace-config} @* After target hardware trace configuration was changed @end itemize @@ -5117,6 +5144,19 @@ each block, and the specified length must stay within that bank. @end deffn @comment no current checks for errors if fill blocks touch multiple banks! +@deffn Command {flash mdw} addr [count] +@deffnx Command {flash mdh} addr [count] +@deffnx Command {flash mdb} addr [count] +Display contents of address @var{addr}, as +32-bit words (@command{mdw}), 16-bit halfwords (@command{mdh}), +or 8-bit bytes (@command{mdb}). +If @var{count} is specified, displays that many units. +Reads from flash using the flash driver, therefore it enables reading +from a bank not mapped in target address space. +The flash bank to use is inferred from the @var{address} of +each block, and the specified length must stay within that bank. +@end deffn + @deffn Command {flash write_bank} num filename [offset] Write the binary @file{filename} to flash bank @var{num}, starting at @var{offset} bytes from the beginning of the bank. If @var{offset} @@ -6437,7 +6477,7 @@ code. @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 @@ -9681,6 +9721,141 @@ Perform a 32-bit DMI read at address, returning the value. Perform a 32-bit DMI write of value at address. @end deffn +@section ARC Architecture +@cindex ARC + +Synopsys DesignWare ARC Processors are a family of 32-bit CPUs that SoC +designers can optimize for a wide range of uses, from deeply embedded to +high-performance host applications in a variety of market segments. See more +at: http://www.synopsys.com/IP/ProcessorIP/ARCProcessors/Pages/default.aspx. +OpenOCD currently supports ARC EM processors. +There is a set ARC-specific OpenOCD commands that allow low-level +access to the core and provide necessary support for ARC extensibility and +configurability capabilities. ARC processors has much more configuration +capabilities than most of the other processors and in addition there is an +extension interface that allows SoC designers to add custom registers and +instructions. For the OpenOCD that mostly means that set of core and AUX +registers in target will vary and is not fixed for a particular processor +model. To enable extensibility several TCL commands are provided that allow to +describe those optional registers in OpenOCD configuration files. Moreover +those commands allow for a dynamic target features discovery. + + +@subsection General ARC commands + +@deffn {Config Command} {arc add-reg} configparams + +Add a new register to processor target. By default newly created register is +marked as not existing. @var{configparams} must have following required +arguments: + +@itemize @bullet + +@item @code{-name} name +@*Name of a register. + +@item @code{-num} number +@*Architectural register number: core register number or AUX register number. + +@item @code{-feature} XML_feature +@*Name of GDB XML target description feature. + +@end itemize + +@var{configparams} may have following optional arguments: + +@itemize @bullet + +@item @code{-gdbnum} number +@*GDB register number. It is recommended to not assign GDB register number +manually, because there would be a risk that two register will have same +number. When register GDB number is not set with this option, then register +will get a previous register number + 1. This option is required only for those +registers that must be at particular address expected by GDB. + +@item @code{-core} +@*This option specifies that register is a core registers. If not - this is an +AUX register. AUX registers and core registers reside in different address +spaces. + +@item @code{-bcr} +@*This options specifies that register is a BCR register. BCR means Build +Configuration Registers - this is a special type of AUX registers that are read +only and non-volatile, that is - they never change their value. Therefore OpenOCD +never invalidates values of those registers in internal caches. Because BCR is a +type of AUX registers, this option cannot be used with @code{-core}. + +@item @code{-type} type_name +@*Name of type of this register. This can be either one of the basic GDB types, +or a custom types described with @command{arc add-reg-type-[flags|struct]}. + +@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 +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 itemize + +@end deffn + +@deffn {Config Command} {arc add-reg-type-flags} -name name flags... +Adds new register type of ``flags'' class. ``Flags'' types can contain only +one-bit fields. Each flag definition looks like @code{-flag name bit-position}. +@end deffn + +@anchor{add-reg-type-struct} +@deffn {Config Command} {arc add-reg-type-struct} -name name structs... +Adds new register type of ``struct'' class. ``Struct'' types can contain either +bit-fields or fields of other types, however at the moment only bit fields are +supported. Structure bit field definition looks like @code{-bitfield name +startbit endbit}. +@end deffn + +@deffn {Command} {arc get-reg-field} reg-name field-name +Returns value of bit-field in a register. Register must be ``struct'' register +type, @xref{add-reg-type-struct} command definition. +@end deffn + +@deffn {Command} {arc set-reg-exists} reg-names... +Specify that some register exists. Any amount of names can be passed +as an argument for a single command invocation. +@end deffn + +@subsection ARC JTAG commands + +@deffn {Command} {arc jtag set-aux-reg} regnum value +This command writes value to AUX register via its number. This command access +register in target directly via JTAG, bypassing any OpenOCD internal caches, +therefore it is unsafe to use if that register can be operated by other means. + +@end deffn + +@deffn {Command} {arc jtag set-core-reg} regnum value +This command is similar to @command{arc jtag set-aux-reg} but is for core +registers. +@end deffn + +@deffn {Command} {arc jtag get-aux-reg} regnum +This command returns the value storded in AUX register via its number. This commands access +register in target directly via JTAG, bypassing any OpenOCD internal caches, +therefore it is unsafe to use if that register can be operated by other means. + +@end deffn + +@deffn {Command} {arc jtag get-core-reg} regnum +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 @cindex Linux-ARM DCC support @@ -10162,18 +10337,31 @@ OpenOCD can communicate with GDB in two ways: @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 @@ -10195,7 +10383,7 @@ Most programs would be written into flash (address 0) and run from there. @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 @@ -10330,7 +10518,7 @@ set remote interrupt-on-connect off 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.