X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=5a803d2c7b61a83101cfab3484763b78cd28fe9c;hp=9f9753930aebb6da8bf24fae75c884f01336b1d8;hb=f3b1405fddf0b32af27ad3894841f7d1702d8e5a;hpb=7f000f824bb405d3985256b123f3e4b55dc43b6b diff --git a/doc/openocd.texi b/doc/openocd.texi index 9f9753930a..5a803d2c7b 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -1447,49 +1447,49 @@ When a chip has multiple TAPs (maybe it has both ARM and DSP cores), the target config file defines all of them. @example $ ls target -aduc702x.cfg lpc1763.cfg -am335x.cfg lpc1764.cfg -amdm37x.cfg lpc1765.cfg -ar71xx.cfg lpc1766.cfg -at32ap7000.cfg lpc1767.cfg -at91r40008.cfg lpc1768.cfg -at91rm9200.cfg lpc1769.cfg -at91sam3ax_4x.cfg lpc1788.cfg -at91sam3ax_8x.cfg lpc17xx.cfg -at91sam3ax_xx.cfg lpc1850.cfg -at91sam3nXX.cfg lpc2103.cfg -at91sam3sXX.cfg lpc2124.cfg -at91sam3u1c.cfg lpc2129.cfg -at91sam3u1e.cfg lpc2148.cfg -at91sam3u2c.cfg lpc2294.cfg -at91sam3u2e.cfg lpc2378.cfg -at91sam3u4c.cfg lpc2460.cfg -at91sam3u4e.cfg lpc2478.cfg -at91sam3uxx.cfg lpc2900.cfg -at91sam3XXX.cfg lpc2xxx.cfg -at91sam4sd32x.cfg lpc3131.cfg -at91sam4sXX.cfg lpc3250.cfg -at91sam4XXX.cfg lpc4350.cfg -at91sam7se512.cfg lpc4350.cfg.orig -at91sam7sx.cfg mc13224v.cfg -at91sam7x256.cfg nuc910.cfg -at91sam7x512.cfg omap2420.cfg -at91sam9260.cfg omap3530.cfg -at91sam9260_ext_RAM_ext_flash.cfg omap4430.cfg -at91sam9261.cfg omap4460.cfg -at91sam9263.cfg omap5912.cfg -at91sam9.cfg omapl138.cfg -at91sam9g10.cfg pic32mx.cfg -at91sam9g20.cfg pxa255.cfg -at91sam9g45.cfg pxa270.cfg -at91sam9rl.cfg pxa3xx.cfg -atmega128.cfg readme.txt -avr32.cfg samsung_s3c2410.cfg -c100.cfg samsung_s3c2440.cfg -c100config.tcl samsung_s3c2450.cfg -c100helper.tcl samsung_s3c4510.cfg -c100regs.tcl samsung_s3c6410.cfg -cs351x.cfg sharp_lh79532.cfg +aduc702x.cfg lpc1764.cfg +am335x.cfg lpc1765.cfg +amdm37x.cfg lpc1766.cfg +ar71xx.cfg lpc1767.cfg +at32ap7000.cfg lpc1768.cfg +at91r40008.cfg lpc1769.cfg +at91rm9200.cfg lpc1788.cfg +at91sam3ax_4x.cfg lpc17xx.cfg +at91sam3ax_8x.cfg lpc1850.cfg +at91sam3ax_xx.cfg lpc2103.cfg +at91sam3nXX.cfg lpc2124.cfg +at91sam3sXX.cfg lpc2129.cfg +at91sam3u1c.cfg lpc2148.cfg +at91sam3u1e.cfg lpc2294.cfg +at91sam3u2c.cfg lpc2378.cfg +at91sam3u2e.cfg lpc2460.cfg +at91sam3u4c.cfg lpc2478.cfg +at91sam3u4e.cfg lpc2900.cfg +at91sam3uxx.cfg lpc2xxx.cfg +at91sam3XXX.cfg lpc3131.cfg +at91sam4sd32x.cfg lpc3250.cfg +at91sam4sXX.cfg lpc4350.cfg +at91sam4XXX.cfg lpc4350.cfg.orig +at91sam7se512.cfg mc13224v.cfg +at91sam7sx.cfg nuc910.cfg +at91sam7x256.cfg omap2420.cfg +at91sam7x512.cfg omap3530.cfg +at91sam9260.cfg omap4430.cfg +at91sam9260_ext_RAM_ext_flash.cfg omap4460.cfg +at91sam9261.cfg omap5912.cfg +at91sam9263.cfg omapl138.cfg +at91sam9.cfg pic32mx.cfg +at91sam9g10.cfg pxa255.cfg +at91sam9g20.cfg pxa270.cfg +at91sam9g45.cfg pxa3xx.cfg +at91sam9rl.cfg readme.txt +atmega128.cfg samsung_s3c2410.cfg +avr32.cfg samsung_s3c2440.cfg +c100.cfg samsung_s3c2450.cfg +c100config.tcl samsung_s3c4510.cfg +c100helper.tcl samsung_s3c6410.cfg +c100regs.tcl sharp_lh79532.cfg +cs351x.cfg sim3x.cfg davinci.cfg smp8634.cfg dragonite.cfg spear3xx.cfg dsp56321.cfg stellaris.cfg @@ -1524,6 +1524,7 @@ lpc1754.cfg ti_dm6446.cfg lpc1756.cfg tmpa900.cfg lpc1758.cfg tmpa910.cfg lpc1759.cfg u8500.cfg +lpc1763.cfg @end example @item @emph{more} ... browse for other library files which may be useful. For example, there are various generic and CPU-specific utilities. @@ -2953,6 +2954,16 @@ Save the current configuration to the internal persistent storage. @deffn {Config} {jlink pid} val Set the USB PID of the interface. As a configuration command, it can be used only before 'init'. @end deffn +@deffn {Config} {jlink serial} serial-number +Set the @var{serial-number} of the interface, in case more than one adapter is connected to the host. +If not specified, serial numbers are not considered. + +Note that there may be leading zeros in the @var{serial-number} string +that will not show in the Segger software, but must be specified here. +Debug level 3 output contains serial numbers if there is a mismatch. + +As a configuration command, it can be used only before 'init'. +@end deffn @end deffn @deffn {Interface Driver} {parport} @@ -3077,6 +3088,7 @@ which are not currently documented here. @end quotation @end deffn +@anchor{hla_interface} @deffn {Interface Driver} {hla} This is a driver that supports multiple High Level Adapters. This type of adapter does not expose some of the lower level api's @@ -3108,13 +3120,6 @@ The vendor ID and product ID of the device. Execute a custom adapter-specific command. The @var{command} string is passed as is to the underlying adapter layout handler. @end deffn - -@deffn {Config Command} {trace} source_clock_hz [output_file_path] -Enable SWO tracing (if supported). The source clock rate for the -trace port must be specified, this is typically the CPU clock rate. If -the optional output file is specified then raw trace data is appended -to the file, and the file is created if it does not exist. -@end deffn @end deffn @deffn {Interface Driver} {opendous} @@ -3166,11 +3171,20 @@ displays the names of the transports supported by this version of OpenOCD. @end deffn -@deffn Command {transport select} transport_name +@deffn Command {transport select} @option{transport_name} Select which of the supported transports to use in this OpenOCD session. -The transport must be supported by the debug adapter hardware and by the -version of OpenOCD you are using (including the adapter's driver). -No arguments: returns name of session's selected transport. + +When invoked with @option{transport_name}, attempts to select the named +transport. The transport must be supported by the debug adapter +hardware and by the version of OpenOCD you are using (including the +adapter's driver). + +If no transport has been selected and no @option{transport_name} is +provided, @command{transport select} auto-selects the first transport +supported by the debug adapter. + +@command{transport select} always returns the name of the session's selected +transport, if any. @end deffn @subsection JTAG Transport @@ -3181,6 +3195,12 @@ JTAG transports expose a chain of one or more Test Access Points (TAPs), each of which must be explicitly declared. JTAG supports both debugging and boundary scan testing. Flash programming support is built on top of debug support. + +JTAG transport is selected with the command @command{transport select +jtag}. Unless your adapter uses @ref{hla_interface,the hla interface +driver}, in which case the command is @command{transport select +hla_jtag}. + @subsection SWD Transport @cindex SWD @cindex Serial Wire Debug @@ -3190,6 +3210,12 @@ Debug Access Point (DAP, which must be explicitly declared. SWD is debug-oriented, and does not support boundary scan testing. Flash programming support is built on top of debug support. (Some processors support both JTAG and SWD.) + +SWD transport is selected with the command @command{transport select +swd}. Unless your adapter uses @ref{hla_interface,the hla interface +driver}, in which case the command is @command{transport select +hla_swd}. + @deffn Command {swd newdap} ... Declares a single DAP which uses SWD transport. Parameters are currently the same as "jtag newtap" but this is @@ -3201,11 +3227,6 @@ Wire Control Register (WCR). No parameters: displays current settings. @end deffn -@subsection CMSIS-DAP Transport -@cindex CMSIS-DAP -CMSIS-DAP is an ARM-specific transport that is used to connect to -compilant debuggers. - @subsection SPI Transport @cindex SPI @cindex Serial Peripheral Interface @@ -4122,22 +4143,6 @@ are examples; and there are many more. Several commands let you examine the list of targets: -@deffn Command {target count} -@emph{Note: target numbers are deprecated; don't use them. -They will be removed shortly after August 2010, including this command. -Iterate target using @command{target names}, not by counting.} - -Returns the number of targets, @math{N}. -The highest numbered target is @math{N - 1}. -@example -set c [target count] -for @{ set x 0 @} @{ $x < $c @} @{ incr x @} @{ - # Assuming you have created this function - print_target_details $x -@} -@end example -@end deffn - @deffn Command {target current} Returns the name of the current target. @end deffn @@ -4151,18 +4156,6 @@ foreach t [target names] @{ @end example @end deffn -@deffn Command {target number} number -@emph{Note: target numbers are deprecated; don't use them. -They will be removed shortly after August 2010, including this command.} - -The list of targets is numbered starting at zero. -This command returns the name of the target at index @var{number}. -@example -set thename [target number $x] -puts [format "Target %d is: %s\n" $x $thename] -@end example -@end deffn - @c yep, "target list" would have been better. @c plus maybe "target setdefault". @@ -4376,7 +4369,7 @@ 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{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}|@option{mqx} @xref{gdbrtossupport,,RTOS Support}. @end itemize @@ -4658,6 +4651,8 @@ when reset disables PLLs needed to use a fast clock. @* After all targets have resumed @item @b{resumed} @* Target has resumed +@item @b{trace-config} +@* After target hardware trace configuration was changed @end itemize @node Flash Commands @@ -4911,7 +4906,7 @@ comamnd or the flash driver then it defaults to 0xff. @end deffn @anchor{program} -@deffn Command {program} filename [verify] [reset] [offset] +@deffn Command {program} filename [verify] [reset] [exit] [offset] This is a helper script that simplifies using OpenOCD as a standalone programmer. The only required parameter is @option{filename}, the others are optional. @xref{Flash Programming}. @@ -5157,6 +5152,20 @@ Atmel include internal flash and use ARM's Cortex-M4 core. This driver uses the same cmd names/syntax as @xref{at91sam3}. @end deffn +@deffn {Flash Driver} at91sam4l +@cindex at91sam4l +All members of the AT91SAM4L microcontroller family from +Atmel include internal flash and use ARM's Cortex-M4 core. +This driver uses the same cmd names/syntax as @xref{at91sam3}. + +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. +@end deffn +@end deffn + @deffn {Flash Driver} at91sam7 All members of the AT91SAM7 microcontroller family from Atmel include internal flash and use ARM7TDMI cores. The driver automatically @@ -5223,10 +5232,10 @@ supported.} @end deffn @deffn {Flash Driver} lpc2000 -All members of the LPC11(x)00 and LPC1300 microcontroller families and most members -of the LPC1700, LPC1800, LPC2000 and LPC4300 microcontroller families from NXP -include internal flash and use Cortex-M0 (LPC11(x)00), Cortex-M3 (LPC1300, LPC1700, -LPC1800), Cortex-M4 (LPC4300) or ARM7TDMI (LPC2000) cores. +This is the driver to support internal flash of all members of the +LPC11(x)00 and LPC1300 microcontroller families and most members of +the LPC800, LPC1500, LPC1700, LPC1800, LPC2000, LPC4000 and LPC54100 +microcontroller families from NXP. @quotation Note There are LPC2000 devices which are not supported by the @var{lpc2000} @@ -5242,12 +5251,16 @@ which must appear in the following order: @item @var{variant} ... required, may be @option{lpc2000_v1} (older LPC21xx and LPC22xx) @option{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx) -@option{lpc1700} (LPC175x and LPC176x) +@option{lpc1700} (LPC175x and LPC176x and LPC177x/8x) @option{lpc4300} - available also as @option{lpc1800} alias (LPC18x[2357] and LPC43x[2357]) +@option{lpc800} (LPC8xx) @option{lpc1100} (LPC11(x)xx and LPC13xx) +@option{lpc1500} (LPC15xx) +@option{lpc54100} (LPC541xx) +@option{lpc4000} (LPC40xx) or @option{auto} - automatically detects flash variant and size for LPC11(x)00, -LPC1300 and LPC1700 +LPC8xx, LPC13xx, LPC17xx and LPC40xx @item @var{clock_kHz} ... the frequency, in kiloHertz, at which the core is running @item @option{calc_checksum} ... optional (but you probably want to provide this!), @@ -5481,11 +5494,10 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @deffn {Flash Driver} stellaris -All members of the Stellaris LM3Sxxx microcontroller family from -Texas Instruments -include internal flash and use ARM Cortex M3 cores. -The driver automatically recognizes a number of these chips using -the chip identification register, and autoconfigures itself. +All members of the Stellaris LM3Sxxx, LM4x and Tiva C microcontroller +families from Texas Instruments include internal flash. The driver +automatically recognizes a number of these chips using the chip +identification register, and autoconfigures itself. @footnote{Currently there is a @command{stellaris mass_erase} command. That seems pointless since the same effect can be had using the standard @command{flash erase_address} command.} @@ -5494,12 +5506,12 @@ standard @command{flash erase_address} command.} flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME @end example -@deffn Command {stellaris recover bank_id} -Performs the @emph{Recovering a "Locked" Device} procedure to -restore the flash specified by @var{bank_id} and its associated -nonvolatile registers to their factory default values (erased). -This is the only way to remove flash protection or re-enable -debugging if that capability has been disabled. +@deffn Command {stellaris recover} +Performs the @emph{Recovering a "Locked" Device} procedure to restore +the flash and its associated nonvolatile registers to their factory +default values (erased). This is the only way to remove flash +protection or re-enable debugging if that capability has been +disabled. Note that the final "power cycle the chip" step in this procedure must be performed by hand, since OpenOCD can't do it. @@ -5710,6 +5722,30 @@ flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME @end example @end deffn +@deffn {Flash Driver} sim3x +All members of the SiM3 microcontroller family from Silicon Laboratories +include internal flash and use ARM Cortex M3 cores. It supports both JTAG +and SWD interface. +The @var{sim3x} driver tries to probe the device to auto detect the MCU. +If this failes, it will use the @var{size} parameter as the size of flash bank. + +@example +flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 0 0 $_TARGETNAME +@end example + +There are 2 commands defined in the @var{sim3x} driver: + +@deffn Command {sim3x mass_erase} +Erases the complete flash. This is used to unlock the flash. +And this command is only possible when using the SWD interface. +@end deffn + +@deffn Command {sim3x lock} +Lock the flash. To unlock use the @command{sim3x mass_erase} command. +@end deffn + +@end deffn + @subsection str9xpec driver @cindex str9xpec @@ -5822,6 +5858,14 @@ configuration registers as well. It must be noted that this command works only for chips that do not have factory pre-programmed region 0 code. @end deffn + +@deffn {Flash Driver} mrvlqspi +This driver supports QSPI flash controller of Marvell's Wireless +Microcontroller platform. + +The flash size is autodetected based on the table of known JEDEC IDs +hardcoded in the OpenOCD sources. +@end deffn @end deffn @section mFlash @@ -5893,7 +5937,7 @@ Programming can be acheived by either using GDB @ref{programmingusinggdb,,Progra or using the cmds given in @ref{flashprogrammingcommands,,Flash Programming Commands}. @*To simplify using the flash cmds directly a jimtcl script is available that handles the programming and verify stage. -OpenOCD will program/verify/reset the target and shutdown. +OpenOCD will program/verify/reset the target and optionally shutdown. The script is executed as follows and by default the following actions will be peformed. @enumerate @@ -5902,7 +5946,7 @@ The script is executed as follows and by default the following actions will be p @item @code{flash write_image} is called to erase and write any flash using the filename given. @item @code{verify_image} is called if @option{verify} parameter is given. @item @code{reset run} is called if @option{reset} parameter is given. -@item OpenOCD is shutdown. +@item OpenOCD is shutdown if @option{exit} parameter is given. @end enumerate An example of usage is given below. @xref{program}. @@ -5911,11 +5955,11 @@ An example of usage is given below. @xref{program}. # program and verify using elf/hex/s19. verify and reset # are optional parameters openocd -f board/stm32f3discovery.cfg \ - -c "program filename.elf verify reset" + -c "program filename.elf verify reset exit" # binary files need the flash address passing openocd -f board/stm32f3discovery.cfg \ - -c "program filename.bin 0x08000000" + -c "program filename.bin exit 0x08000000" @end example @node NAND Flash Commands @@ -6456,8 +6500,10 @@ Useful in connection with script files (@command{script} command and @command{target_name} configuration). @end deffn -@deffn Command shutdown -Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other). +@deffn Command shutdown [@option{error}] +Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, +other). If option @option{error} is used, OpenOCD will return a +non-zero exit code to the parent process. @end deffn @anchor{debuglevel} @@ -7618,6 +7664,93 @@ fix CSW_SPROT from register AP_REG_CSW on selected dap. Defaulting to 0. @end deffn +@subsection ARMv7-M specific commands +@cindex tracing +@cindex SWO +@cindex SWV +@cindex TPIU +@cindex ITM +@cindex ETM + +@deffn Command {tpiu config} (@option{disable} | ((@option{external} | @option{internal @var{filename}}) @ + (@option{sync @var{port_width}} | ((@option{manchester} | @option{uart}) @var{formatter_enable})) @ + @var{TRACECLKIN_freq} [@var{trace_freq}])) + +ARMv7-M architecture provides several modules to generate debugging +information internally (ITM, DWT and ETM). Their output is directed +through TPIU to be captured externally either on an SWO pin (this +configuration is called SWV) or on a synchronous parallel trace port. + +This command configures the TPIU module of the target and, if internal +capture mode is selected, starts to capture trace output by using the +debugger adapter features. + +Some targets require additional actions to be performed in the +@b{trace-config} handler for trace port to be activated. + +Command options: +@itemize @minus +@item @option{disable} disable TPIU handling; +@item @option{external} configure TPIU to let user capture trace +output externally (with an additional UART or logic analyzer hardware); +@item @option{internal @var{filename}} configure TPIU and debug adapter to +gather trace data and append it to @var{filename} (which can be +either a regular file or a named pipe); +@item @option{sync @var{port_width}} use synchronous parallel trace output +mode, and set port width to @var{port_width}; +@item @option{manchester} use asynchronous SWO mode with Manchester +coding; +@item @option{uart} use asynchronous SWO mode with NRZ (same as +regular UART 8N1) coding; +@item @var{formatter_enable} is @option{on} or @option{off} to enable +or disable TPIU formatter which needs to be used when both ITM and ETM +data is to be output via SWO; +@item @var{TRACECLKIN_freq} this should be specified to match target's +current TRACECLKIN frequency (usually the same as HCLK); +@item @var{trace_freq} trace port frequency. Can be omitted in +internal mode to let the adapter driver select the maximum supported +rate automatically. +@end itemize + +Example usage: +@enumerate +@item STM32L152 board is programmed with an application that configures +PLL to provide core clock with 24MHz frequency; to use ITM output it's +enough to: +@example +#include + ... + ITM_STIM8(0) = c; + ... +@end example +(the most obvious way is to use the first stimulus port for printf, +for that this ITM_STIM8 assignment can be used inside _write(); to make it +blocking to avoid data loss, add @code{while (!(ITM_STIM8(0) & +ITM_STIM_FIFOREADY));}); +@item An FT2232H UART is connected to the SWO pin of the board; +@item Commands to configure UART for 12MHz baud rate: +@example +$ setserial /dev/ttyUSB1 spd_cust divisor 5 +$ stty -F /dev/ttyUSB1 38400 +@end example +(FT2232H's base frequency is 60MHz, spd_cust allows to alias 38400 +baud with our custom divisor to get 12MHz) +@item @code{itmdump -f /dev/ttyUSB1 -d1} +@item @code{openocd -f interface/stlink-v2-1.cfg -c "transport select +hla_swd" -f target/stm32l1.cfg -c "tpiu config external uart off +24000000 12000000"} +@end enumerate +@end deffn + +@deffn Command {itm port} @var{port} (@option{0}|@option{1}|@option{on}|@option{off}) +Enable or disable trace output for ITM stimulus @var{port} (counting +from 0). Port 0 is enabled on target creation automatically. +@end deffn + +@deffn Command {itm ports} (@option{0}|@option{1}|@option{on}|@option{off}) +Enable or disable trace output for all ITM stimulus ports. +@end deffn + @subsection Cortex-M specific commands @cindex Cortex-M @@ -8468,6 +8601,7 @@ Currently supported rtos's include: @item @option{linux} @item @option{ChibiOS} @item @option{embKernel} +@item @option{mqx} @end itemize @quotation Note @@ -8491,6 +8625,8 @@ rlist, ch_debug, chSysInit. @item embKernel symbols Rtos::sCurrentTask, Rtos::sListReady, Rtos::sListSleep, Rtos::sListSuspended, Rtos::sMaxPriorities, Rtos::sCurrentTaskCount. +@item mqx symbols +_mqx_kernel_data, MQX_init_struct. @end table For most RTOS supported the above symbols will be exported by default. However for @@ -8624,6 +8760,28 @@ Remember that most of the OpenOCD commands need to be prefixed with See @file{contrib/rpc_examples/} for specific client implementations. +@section Tcl RPC server notifications +@cindex RPC Notifications + +Notifications are sent asynchronously to other commands being executed over +the RPC server, so the port must be polled continuously. + +Target event, state and reset notifications are emitted as Tcl associative arrays +in the following format. + +@verbatim +type target_event event [event-name] +type target_state state [state-name] +type target_reset mode [reset-mode] +@end verbatim + +@deffn {Command} tcl_notifications [on/off] +Toggle output of target notifications to the current Tcl RPC server. +Only available from the Tcl RPC server. +Defaults to off. + +@end deffn + @node FAQ @chapter FAQ @cindex faq