X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=7a9b090d0119c5a1bd0ffae8e4a27ee2dead4e3b;hb=6a78c8581d81665969f24563faccd220de517961;hp=25554f87a4014fa3499238c4cb2274283dc1e53c;hpb=c999fcef3e96fbdb5226b0913bddf29365566ce8;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 25554f87a4..7a9b090d01 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -536,16 +536,8 @@ 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. The XDS110 -stand-alone probe has the additional ability to supply voltage to the target -board via its AUX FUNCTIONS port. Use the -@command{xds110_supply_voltage } command to set the voltage. 0 turns -off the supply. Otherwise, the supply can be set to any value in the range 1800 -to 3600 millivolts. -@* Link: @url{http://processors.wiki.ti.com/index.php/XDS110} -@* Link: @url{http://processors.wiki.ti.com/index.php/XDS_Emulation_Software_Package#XDS110_Support_Utilities} +@* 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 @section IBM PC Parallel Printer Port Based @@ -618,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 @@ -1028,7 +1020,7 @@ will help support users of any board using that chip. @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 @@ -1482,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. @@ -3131,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). @@ -3289,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. @@ -4400,34 +4433,41 @@ Lists all supported target types. At this writing, the supported CPU types are: @itemize @bullet -@item @code{arm11} -- this is a generation of ARMv6 cores -@item @code{arm720t} -- this is an ARMv4 core with an MMU -@item @code{arm7tdmi} -- this is an ARMv4 core -@item @code{arm920t} -- this is an ARMv4 core with an MMU -@item @code{arm926ejs} -- this is an ARMv5 core with an MMU -@item @code{arm966e} -- this is an ARMv5 core -@item @code{arm9tdmi} -- this is an ARMv4 core +@item @code{aarch64} -- this is an ARMv8-A core with an MMU. +@item @code{arm11} -- this is a generation of ARMv6 cores. +@item @code{arm720t} -- this is an ARMv4 core with an MMU. +@item @code{arm7tdmi} -- this is an ARMv4 core. +@item @code{arm920t} -- this is an ARMv4 core with an MMU. +@item @code{arm926ejs} -- this is an ARMv5 core with an MMU. +@item @code{arm946e} -- this is an ARMv5 core with an MMU. +@item @code{arm966e} -- this is an ARMv5 core. +@item @code{arm9tdmi} -- this is an ARMv4 core. @item @code{avr} -- implements Atmel's 8-bit AVR instruction set. (Support for this is preliminary and incomplete.) -@item @code{cortex_a} -- this is an ARMv7 core with an MMU -@item @code{cortex_m} -- this is an ARMv7 core, supporting only the -compact Thumb2 instruction set. -@item @code{aarch64} -- this is an ARMv8-A core with an MMU -@item @code{dragonite} -- resembles arm966e +@item @code{avr32_ap7k} -- this an AVR32 core. +@item @code{cortex_a} -- this is an ARMv7-A core with an MMU. +@item @code{cortex_m} -- this is an ARMv7-M core, supporting only the +compact Thumb2 instruction set. Supports also ARMv6-M and ARMv8-M cores +@item @code{cortex_r4} -- this is an ARMv7-R core. +@item @code{dragonite} -- resembles arm966e. @item @code{dsp563xx} -- implements Freescale's 24-bit DSP. (Support for this is still incomplete.) +@item @code{dsp5680xx} -- implements Freescale's 5680x DSP. @item @code{esirisc} -- this is an EnSilica eSi-RISC core. The current implementation supports eSi-32xx cores. -@item @code{fa526} -- resembles arm920 (w/o Thumb) -@item @code{feroceon} -- resembles arm926 -@item @code{mem_ap} -- this is an ARM debug infrastructure Access Port without a CPU, through which bus read and write cycles can be generated; it may be useful for working with non-CPU hardware behind an AP or during development of support for new CPUs. -@item @code{mips_m4k} -- a MIPS core -@item @code{xscale} -- this is actually an architecture, -not a CPU type. It is based on the ARMv5 architecture. -@item @code{openrisc} -- this is an OpenRISC 1000 core. -The current implementation supports three JTAG TAP cores: +@item @code{fa526} -- resembles arm920 (w/o Thumb). +@item @code{feroceon} -- resembles arm926. +@item @code{hla_target} -- a Cortex-M alternative to work with HL adapters like ST-Link. @item @code{ls1_sap} -- this is the SAP on NXP LS102x CPUs, allowing access to physical memory addresses independently of CPU cores. +@item @code{mem_ap} -- this is an ARM debug infrastructure Access Port without a CPU, through which bus read and write cycles can be generated; it may be useful for working with non-CPU hardware behind an AP or during development of support for new CPUs. +@item @code{mips_m4k} -- a MIPS core. +@item @code{mips_mips64} -- a MIPS64 core. +@item @code{nds32_v2} -- this is an Andes NDS32 v2 core. +@item @code{nds32_v3} -- this is an Andes NDS32 v3 core. +@item @code{nds32_v3m} -- this is an Andes NDS32 v3m core. +@item @code{or1k} -- this is an OpenRISC 1000 core. +The current implementation supports three JTAG TAP cores: @itemize @minus @item @code{OpenCores TAP} (See: @url{http://opencores.org/project@comma{}jtag}) @item @code{Altera Virtual JTAG TAP} (See: @url{http://www.altera.com/literature/ug/ug_virtualjtag.pdf}) @@ -4438,6 +4478,13 @@ And two debug interfaces cores: @item @code{Advanced debug interface} (See: @url{http://opencores.org/project@comma{}adv_debug_sys}) @item @code{SoC Debug Interface} (See: @url{http://opencores.org/project@comma{}dbg_interface}) @end itemize +@item @code{quark_d20xx} -- an Intel Quark D20xx core. +@item @code{quark_x10xx} -- an Intel Quark X10xx core. +@item @code{riscv} -- a RISC-V core. +@item @code{stm8} -- implements an STM8 core. +@item @code{testee} -- a dummy target for cases without a real CPU, e.g. CPLD. +@item @code{xscale} -- this is actually an architecture, +not a CPU type. It is based on the ARMv5 architecture. @end itemize @end deffn @@ -4590,7 +4637,8 @@ The value should normally correspond to a static mapping for the @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 @@ -4900,6 +4948,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 @@ -5093,6 +5145,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} @@ -5597,7 +5662,7 @@ at91samd bootloader 16384 @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} @@ -5704,7 +5769,7 @@ The AT91SAM4L driver adds some additional commands: @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 @@ -5745,7 +5810,7 @@ processor to be halted. @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} @@ -6413,7 +6478,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 @@ -8163,8 +8228,8 @@ in which case it will be a hardware breakpoint. for similar mechanisms that do not consume hardware breakpoints.) @end deffn -@deffn Command {rbp} address -Remove the breakpoint at @var{address}. +@deffn Command {rbp} @option{all} | address +Remove the breakpoint at @var{address} or all breakpoints. @end deffn @deffn Command {rwp} address @@ -8328,7 +8393,7 @@ and any buffered trace data is invalidated. @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), @@ -8676,7 +8741,7 @@ and any other core-specific commands that may be available. @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. @@ -9657,6 +9722,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 @@ -10138,18 +10338,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 @@ -10171,7 +10384,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 @@ -10306,7 +10519,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. @@ -10344,6 +10557,7 @@ Currently supported rtos's include: @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 @@ -10380,6 +10594,8 @@ _mqx_kernel_data, MQX_init_struct. 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