X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=cc7f6c8247c6d6c464817db190648b57681b9846;hp=ee94b24a4a470e8da3caa4d0562290e5e93415f8;hb=6819468a78ce9f0835a9063d93bc839f3d55eb84;hpb=c4113b5f3da6bfbc544648cfdde6d3df01b0d7b4 diff --git a/doc/openocd.texi b/doc/openocd.texi index ee94b24a4a..cc7f6c8247 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -3119,13 +3119,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} @@ -4133,22 +4126,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 @@ -4162,18 +4139,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". @@ -4669,6 +4634,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 @@ -5236,7 +5203,7 @@ supported.} @deffn {Flash Driver} lpc2000 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, LPC4300 and LPC54100 +the LPC800, LPC1500, LPC1700, LPC1800, LPC2000, LPC4000 and LPC54100 microcontroller families from NXP. @quotation Note @@ -5253,15 +5220,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, -LPC8xx, LPC13xx and LPC17xx +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!), @@ -5495,11 +5463,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.} @@ -5508,12 +5475,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. @@ -7664,6 +7631,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 @@ -8670,6 +8724,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