Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
@end quotation
@end copying
@cindex dongles
@cindex FTDI
@cindex wiggler
-@cindex zy1000
@cindex printer port
@cindex USB Adapter
@cindex RTCK
an adapter .... [snip]
In the OpenOCD case, this generally refers to @b{a small adapter} that
-attaches to your computer via USB or the parallel port. One
-exception is the Ultimate Solutions ZY1000, packaged as a small box you
-attach via an ethernet cable. The ZY1000 has the advantage that it does not
-require any drivers to be installed on the developer PC. It also has
-a built in web interface. It supports RTCK/RCLK or adaptive clocking
-and has a built-in relay to power cycle targets remotely.
+attaches to your computer via USB or the parallel port.
@section Choosing a Dongle
RTCK support (also known as ``adaptive clocking'')?
@end enumerate
-@section Stand-alone JTAG Probe
-
-The ZY1000 from Ultimate Solutions is technically not a dongle but a
-stand-alone JTAG probe that, unlike most dongles, doesn't require any drivers
-running on the developer's host computer.
-Once installed on a network using DHCP or a static IP assignment, users can
-access the ZY1000 probe locally or remotely from any host with access to the
-IP address assigned to the probe.
-The ZY1000 provides an intuitive web interface with direct access to the
-OpenOCD debugger.
-Users may also run a GDBSERVER directly on the ZY1000 to take full advantage
-of GCC & GDB to debug any distribution of embedded Linux or NetBSD running on
-the target.
-The ZY1000 supports RTCK & RCLK or adaptive clocking and has a built-in relay
-to power cycle the target remotely.
-
-For more information, visit:
-
-@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/210-zylin-zy1000-main}
-
@section USB FT2232 Based
There are many USB JTAG dongles on the market, many of them based
Today's most common case is a dongle with a JTAG cable on one side
(such as a ribbon cable with a 10-pin or 20-pin IDC connector)
and a USB cable on the other.
-Instead of USB, some cables use Ethernet;
+Instead of USB, some dongles use Ethernet;
older ones may use a PC parallel port, or even a serial port.
@enumerate
When using "pipe", also use log_output to redirect the log
output to a file so as not to flood the stdin/out pipes.
-The -p/--pipe option is deprecated and a warning is printed
-as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log".
-
Any other string is interpreted as named pipe to listen to.
Output pipe is the same name as input pipe, but with 'o' appended,
e.g. /var/gdb, /var/gdbo.
Pairs of vendor IDs and product IDs of the device.
@end deffn
+@deffn {Config Command} {hla_stlink_backend} (usb | tcp [port])
+@emph{ST-Link only:} Choose between 'exclusive' USB communication (the default backend) or
+'shared' mode using ST-Link TCP server (the default port is 7184).
+
+@emph{Note:} ST-Link TCP server is a binary application provided by ST
+available from @url{https://www.st.com/en/development-tools/st-link-server.html,
+ST-LINK server software module}.
+@end deffn
+
@deffn {Command} {hla_command} command
Execute a custom adapter-specific command. The @var{command} string is
passed as is to the underlying adapter layout handler.
@emph{Note:} Either these same adapters and their older versions are
also supported by @ref{hla_interface, the hla interface driver}.
+@deffn {Config Command} {st-link backend} (usb | tcp [port])
+Choose between 'exclusive' USB communication (the default backend) or
+'shared' mode using ST-Link TCP server (the default port is 7184).
+
+@emph{Note:} ST-Link TCP server is a binary application provided by ST
+available from @url{https://www.st.com/en/development-tools/st-link-server.html,
+ST-LINK server software module}.
+
+@emph{Note:} ST-Link TCP server does not support the SWIM transport.
+@end deffn
+
@deffn {Config Command} {st-link serial} serial
Specifies the serial number of the adapter.
@end deffn
@end deffn
@end deffn
-@deffn {Interface Driver} {ZY1000}
-This is the Zylin ZY1000 JTAG debugger.
-@end deffn
-
-@quotation Note
-This defines some driver-specific commands,
-which are not currently documented here.
-@end quotation
-
-@deffn Command power [@option{on}|@option{off}]
-Turn power switch to target on/off.
-No arguments: print status.
-@end deffn
-
@deffn {Interface Driver} {bcm2835gpio}
This SoC is present in Raspberry Pi which is a cheap single-board computer
exposing some GPIOs on its expansion header.
@end itemize
And two debug interfaces cores:
@itemize @minus
-@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})
+@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.
@* After target hardware trace configuration was changed
@end itemize
+@quotation Note
+OpenOCD events are not supposed to be preempt by another event, but this
+is not enforced in current code. Only the target event @b{resumed} is
+executed with polling disabled; this avoids polling to trigger the event
+@b{halted}, reversing the logical order of execution of their handlers.
+Future versions of OpenOCD will prevent the event preemption and will
+disable the schedule of polling during the event execution. Do not rely
+on polling in any event handler; this means, don't expect the status of
+a core to change during the execution of the handler. The event handler
+will have to enable polling or use @command{$target_name arp_poll} to
+check if the core has changed status.
+@end quotation
+
@node Flash Commands
@chapter Flash Commands
required (see 'set' command).
@example
-flash bank $_FLASHNAME stmqspi 0x90000000 0 0 0 $_TARGETNAME 0xA0001000
-flash bank $_FLASHNAME stmqspi 0x70000000 0 0 0 $_TARGETNAME 0xA0001400
+flash bank $_FLASHNAME stmqspi 0x90000000 0 0 0 \
+ $_TARGETNAME 0xA0001000
+flash bank $_FLASHNAME stmqspi 0x70000000 0 0 0 \
+ $_TARGETNAME 0xA0001400
@end example
There are three specific commands
To check basic communication settings, issue
@example
-stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 1 0x05; stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 1 0x05
+stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 1 0x05
+stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 1 0x05
@end example
for single flash mode or
@example
-stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 2 0x05; stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 2 0x05
+stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 2 0x05
+stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 2 0x05
@end example
for dual flash mode. This should return the status register contents.
@example
flash bank $_FLASHNAME ath79 0xbf000000 0 0 0 $_TARGETNAME
-# When using multiple chipselects the base should be different for each,
-# otherwise the write_image command is not able to distinguish the
-# banks.
+# When using multiple chipselects the base should be different
+# for each, otherwise the write_image command is not able to
+# distinguish the banks.
flash bank flash0 ath79 0xbf000000 0 0 0 $_TARGETNAME cs0
flash bank flash1 ath79 0x10000000 0 0 0 $_TARGETNAME cs1
flash bank flash2 ath79 0x20000000 0 0 0 $_TARGETNAME cs2
NVMUSERROW: 0xFFFFFC5DD8E0C788
# Write 0xFFFFFC5DD8E0C788 to user row
>at91samd nvmuserrow 0xFFFFFC5DD8E0C788
-# Write 0x12300 to user row but leave other bits and low byte unchanged
+# Write 0x12300 to user row but leave other bits and low
+# byte unchanged
>at91samd nvmuserrow 0x12345 0xFFF00
@end example
@end deffn
USER PAGE: 0xAEECFF80FE9A9239
# Write
>atsame5 userpage 0xAEECFF80FE9A9239
-# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other bits unchanged
-# (setup SmartEEPROM of virtual size 8192 bytes)
+# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other
+# bits unchanged (setup SmartEEPROM of virtual size 8192
+# bytes)
>atsame5 userpage 0x4200000000 0x7f00000000
@end example
@end deffn
apart from the base address.
@example
-flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 $_TARGETNAME
+flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 \
+ $_TARGETNAME
@end example
@end deffn
PSoC6 is equipped with NOR Flash so erased Flash reads as 0x00.
@example
-flash bank main_flash_cm0 psoc6 0x10000000 0 0 0 $@{TARGET@}.cm0
-flash bank work_flash_cm0 psoc6 0x14000000 0 0 0 $@{TARGET@}.cm0
-flash bank super_flash_user_cm0 psoc6 0x16000800 0 0 0 $@{TARGET@}.cm0
-flash bank super_flash_nar_cm0 psoc6 0x16001A00 0 0 0 $@{TARGET@}.cm0
-flash bank super_flash_key_cm0 psoc6 0x16005A00 0 0 0 $@{TARGET@}.cm0
-flash bank super_flash_toc2_cm0 psoc6 0x16007C00 0 0 0 $@{TARGET@}.cm0
-
-flash bank main_flash_cm4 psoc6 0x10000000 0 0 0 $@{TARGET@}.cm4
-flash bank work_flash_cm4 psoc6 0x14000000 0 0 0 $@{TARGET@}.cm4
-flash bank super_flash_user_cm4 psoc6 0x16000800 0 0 0 $@{TARGET@}.cm4
-flash bank super_flash_nar_cm4 psoc6 0x16001A00 0 0 0 $@{TARGET@}.cm4
-flash bank super_flash_key_cm4 psoc6 0x16005A00 0 0 0 $@{TARGET@}.cm4
-flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 $@{TARGET@}.cm4
+flash bank main_flash_cm0 psoc6 0x10000000 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank work_flash_cm0 psoc6 0x14000000 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank super_flash_user_cm0 psoc6 0x16000800 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank super_flash_nar_cm0 psoc6 0x16001A00 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank super_flash_key_cm0 psoc6 0x16005A00 0 0 0 \
+ $@{TARGET@}.cm0
+flash bank super_flash_toc2_cm0 psoc6 0x16007C00 0 0 0 \
+ $@{TARGET@}.cm0
+
+flash bank main_flash_cm4 psoc6 0x10000000 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank work_flash_cm4 psoc6 0x14000000 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank super_flash_user_cm4 psoc6 0x16000800 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank super_flash_nar_cm4 psoc6 0x16001A00 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank super_flash_key_cm4 psoc6 0x16005A00 0 0 0 \
+ $@{TARGET@}.cm4
+flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 \
+ $@{TARGET@}.cm4
@end example
psoc6-specific commands
Example usage:
@example
-# swap bank 1 and bank 2 in dual bank devices, by setting SWAP_BANK_OPT bit in OPTSR_PRG
+# swap bank 1 and bank 2 in dual bank devices
+# by setting SWAP_BANK_OPT bit in OPTSR_PRG
stm32h7x option_write 0 0x20 0x8000000 0x8000000
@end example
@end deffn
flash bank $_FLASHNAME stm32l4x 0 0 0 0 $_TARGETNAME
@end example
+If you use OTP (One-Time Programmable) memory define it as a second bank
+as per the following example.
+@example
+flash bank $_FLASHNAME stm32l4x 0x1FFF7000 0 0 0 $_TARGETNAME
+@end example
+
+@deffn Command {stm32l4x otp} num (@option{enable}|@option{disable}|@option{show})
+Enables or disables OTP write commands for bank @var{num}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
Note that some devices have been found that have a flash size register that contains
an invalid value, to workaround this issue you can override the probed value used by
the flash driver. However, specifying a wrong value might lead to a completely
@end quotation
@end deffn
-@section I/O Utilities
-
-These commands are available when
-OpenOCD is built with @option{--enable-ioutil}.
-They are mainly useful on embedded targets,
-notably the ZY1000.
-Hosts with operating systems have complementary tools.
-
-@emph{Note:} there are several more such commands.
-
-@deffn Command append_file filename [string]*
-Appends the @var{string} parameters to
-the text file @file{filename}.
-Each string except the last one is followed by one space.
-The last string is followed by a newline.
-@end deffn
-
-@deffn Command cat filename
-Reads and displays the text file @file{filename}.
-@end deffn
-
-@deffn Command cp src_filename dest_filename
-Copies contents from the file @file{src_filename}
-into @file{dest_filename}.
-@end deffn
-
-@deffn Command ip
-@emph{No description provided.}
-@end deffn
-
-@deffn Command ls
-@emph{No description provided.}
-@end deffn
-
-@deffn Command mac
-@emph{No description provided.}
-@end deffn
-
-@deffn Command meminfo
-Display available RAM memory on OpenOCD host.
-Used in OpenOCD regression testing scripts.
-@end deffn
-
-@deffn Command peek
-@emph{No description provided.}
-@end deffn
-
-@deffn Command poke
-@emph{No description provided.}
-@end deffn
-
-@deffn Command rm filename
-@c "rm" has both normal and Jim-level versions??
-Unlinks the file @file{filename}.
-@end deffn
-
-@deffn Command trunc filename
-Removes all data in the file @file{filename}.
-@end deffn
-
@anchor{memoryaccess}
@section Memory access commands
@cindex memory access
@end deffn
-@deffn {Trace Port Driver} oocd_trace
-This driver isn't available unless OpenOCD was explicitly configured
-with the @option{--enable-oocd_trace} option. You probably don't want
-to configure it unless you've built the appropriate prototype hardware;
-it's @emph{proof-of-concept} software.
-
-Use the @option{oocd_trace} driver if you are configuring an ETM that's
-connected to an off-chip trace connector.
-
-@deffn {Config Command} {oocd_trace config} target tty
-Associates the ETM for @var{target} with a trace driver which
-collects data through the serial port @var{tty}.
-@end deffn
-
-@deffn Command {oocd_trace resync}
-Re-synchronizes with the capture clock.
-@end deffn
-
-@deffn Command {oocd_trace status}
-Reports whether the capture clock is locked or not.
-@end deffn
-@end deffn
-
@anchor{armcrosstrigger}
@section ARM Cross-Trigger Interface
@cindex CTI
speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
-@subsection ARM720T specific commands
-@cindex ARM720T
-
-These commands are available to ARM720T based CPUs,
-which are implementations of the ARMv4T architecture
-based on the ARM7TDMI-S integer core.
-They are available in addition to the ARM and ARM7/ARM9 commands.
-
-@deffn Command {arm720t cp15} opcode [value]
-@emph{DEPRECATED -- avoid using this.
-Use the @command{arm mrc} or @command{arm mcr} commands instead.}
-
-Display cp15 register returned by the ARM instruction @var{opcode};
-else if a @var{value} is provided, that value is written to that register.
-The @var{opcode} should be the value of either an MRC or MCR instruction.
-@end deffn
-
@subsection ARM9 specific commands
@cindex ARM9
(Not all registers can be written.)
@end deffn
-@deffn Command {arm920t cp15i} opcode [value [address]]
-@emph{DEPRECATED -- avoid using this.
-Use the @command{arm mrc} or @command{arm mcr} commands instead.}
-
-Interpreted access using ARM instruction @var{opcode}, which should
-be the value of either an MRC or MCR instruction
-(as shown tables 9-11, 9-12, and 9-13 in the ARM920T TRM).
-If no @var{value} is provided, the result is displayed.
-Else if that value is written using the specified @var{address},
-or using zero if no other address is provided.
-@end deffn
-
@deffn Command {arm920t read_cache} filename
Dump the content of ICache and DCache to a file named @file{filename}.
@end deffn
@end deffn
-@subsection ARMv7-M specific commands
+@subsection ARM CoreSight TPIU and SWO 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} | @var{:port} | -)}) @
- (@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
+ARM CoreSight 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
+through TPIU or SWO modules 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.
+ARM CoreSight provides independent HW blocks named TPIU and SWO each with its
+own functionality. Embedded in Cortex-M3 and M4, ARM provides an optional HW
+block that includes both TPIU and SWO functionalities and is again named TPIU,
+which causes quite some confusion.
+The registers map of all the TPIU and SWO implementations allows using a single
+driver that detects at runtime the features available.
-Some targets require additional actions to be performed in the
-@b{trace-config} handler for trace port to be activated.
+The @command{tpiu} is used for either TPIU or SWO.
+A convenient alias @command{swo} is available to help distinguish, in scripts,
+the commands for SWO from the commands for TPIU.
-Command options:
+@deffn Command {swo} ...
+Alias of @command{tpiu ...}. Can be used in scripts to distinguish the commands
+for SWO from the commands for TPIU.
+@end deffn
+
+@deffn Command {tpiu create} tpiu_name configparams...
+Creates a TPIU or a SWO object. The two commands are equivalent.
+Add the object in a list and add new commands (@command{@var{tpiu_name}})
+which are used for various purposes including additional configuration.
+
+@itemize @bullet
+@item @var{tpiu_name} -- the name of the TPIU or SWO object.
+This name is also used to create the object's command, referred to here
+as @command{$tpiu_name}, and in other places where the TPIU or SWO needs to be identified.
+@item @var{configparams} -- all parameters accepted by @command{$tpiu_name configure} are permitted.
+
+You @emph{must} set here the AP and MEM_AP base_address through @code{-dap @var{dap_name}},
+@code{-ap-num @var{ap_number}} and @code{-baseaddr @var{base_address}}.
+@end itemize
+@end deffn
+
+@deffn Command {tpiu names}
+Lists all the TPIU or SWO objects created so far. The two commands are equivalent.
+@end deffn
+
+@deffn Command {tpiu init}
+Initialize all registered TPIU and SWO. The two commands are equivalent.
+These commands are used internally during initialization. They can be issued
+at any time after the initialization, too.
+@end deffn
+
+@deffn Command {$tpiu_name cget} queryparm
+Each configuration parameter accepted by @command{$tpiu_name configure} can be
+individually queried, to return its current value.
+The @var{queryparm} is a parameter name accepted by that command, such as @code{-dap}.
+@end deffn
+
+@deffn Command {$tpiu_name configure} configparams...
+The options accepted by this command may also be specified as parameters
+to @command{tpiu create}. Their values can later be queried one at a time by
+using the @command{$tpiu_name cget} command.
+
+@itemize @bullet
+@item @code{-dap} @var{dap_name} -- names the DAP used to access this
+TPIU. @xref{dapdeclaration,,DAP declaration}, on how to create and manage DAP instances.
+
+@item @code{-ap-num} @var{ap_number} -- sets DAP access port for TPIU,
+@var{ap_number} is the numeric index of the DAP AP the TPIU is connected to.
+
+@item @code{-baseaddr} @var{base_address} -- sets the TPIU @var{base_address} where
+to access the TPIU in the DAP AP memory space.
+
+@item @code{-protocol} (@option{sync}|@option{uart}|@option{manchester}) -- sets the
+protocol used for trace data:
@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} | @var{:port} | -)} configure TPIU and debug adapter to
-gather trace data then:
+@item @option{sync} -- synchronous parallel trace output mode, using @var{port_width}
+ data bits (default);
+@item @option{uart} -- use asynchronous SWO mode with NRZ (same as regular UART 8N1) coding;
+@item @option{manchester} -- use asynchronous SWO mode with Manchester coding.
+@end itemize
+@item @code{-event} @var{event_name} @var{event_body} -- assigns an event handler,
+a TCL string which is evaluated when the event is triggered. The events
+@code{pre-enable}, @code{post-enable}, @code{pre-disable} and @code{post-disable}
+are defined for TPIU/SWO.
+A typical use case for the event @code{pre-enable} is to enable the trace clock
+of the TPIU.
+
+@item @code{-output} (@option{external}|@option{:}@var{port}|@var{filename}|@option{-}) -- specifies
+the destination of the trace data:
@itemize @minus
-@item append it to a regular file or a named pipe if @var{filename} is specified.
-@item listen to a TCP/IP port if @var{:port} is specified, then broadcast the trace data over this port.
-@item if '-' is specified, OpenOCD will forward trace data to @command{tcl_trace} command.
-@*@b{Note:} while broadcasting to file or TCP, the forwarding to @command{tcl_trace} will remain active.
+@item @option{external} -- configure TPIU/SWO to let user capture trace
+output externally, either with an additional UART or with a logic analyzer (default);
+@item @option{-} -- configure TPIU/SWO and debug adapter to gather trace data
+and forward it to @command{tcl_trace} command;
+@item @option{:}@var{port} -- configure TPIU/SWO and debug adapter to gather
+trace data, open a TCP server at port @var{port} and send the trace data to
+each connected client;
+@item @var{filename} -- configure TPIU/SWO and debug adapter to
+gather trace data and append it to @var{filename}, which can be
+either a regular file or a named pipe.
@end itemize
-@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.
+@item @code{-traceclk} @var{TRACECLKIN_freq} -- mandatory parameter.
+Specifies the frequency in Hz of the trace clock. For the TPIU embedded in
+Cortex-M3 or M4, this is usually the same frequency as HCLK. For protocol
+@option{sync} this is twice the frequency of the pin data rate.
+
+@item @code{-pin-freq} @var{trace_freq} -- specifies the expected data rate
+in Hz of the SWO pin. Parameter used only on protocols @option{uart} and
+@option{manchester}. Can be omitted to let the adapter driver select the
+maximum supported rate automatically.
+
+@item @code{-port-width} @var{port_width} -- sets to @var{port_width} the width
+of the synchronous parallel port used for trace output. Parameter used only on
+protocol @option{sync}. If not specified, default value is @var{1}.
+
+@item @code{-formatter} (@option{0}|@option{1}) -- specifies if the formatter
+should be enabled. Parameter used only on protocol @option{sync}. If not specified,
+default value is @var{0}.
@end itemize
+@end deffn
+
+@deffn Command {$tpiu_name enable}
+Uses the parameters specified by the previous @command{$tpiu_name configure}
+to configure and enable the TPIU or the SWO.
+If required, the adapter is also configured and enabled to receive the trace
+data.
+This command can be used before @command{init}, but it will take effect only
+after the @command{init}.
+@end deffn
+
+@deffn Command {$tpiu_name disable}
+Disable the TPIU or the SWO, terminating the receiving of the trace data.
+@end deffn
+
+
Example usage:
@enumerate
@item OpenOCD invocation line:
@example
openocd -f interface/stlink.cfg \
- -c "transport select hla_swd" \
- -f target/stm32l1.cfg \
- -c "tpiu config external uart off 24000000 12000000"
+-c "transport select hla_swd" \
+-f target/stm32l1.cfg \
+-c "stm32l1.tpiu configure -protocol uart" \
+-c "stm32l1.tpiu configure -traceclk 24000000 -pin-freq 12000000" \
+-c "stm32l1.tpiu enable"
@end example
@end enumerate
-@end deffn
+
+@subsection ARMv7-M specific commands
+@cindex tracing
+@cindex SWO
+@cindex SWV
+@cindex ITM
+@cindex ETM
@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
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.
+at: @url{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
@item
A pipe connection is typically started as follows:
@example
-target extended-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
@item ThreadX symbols
_tx_thread_current_ptr, _tx_thread_created_ptr, _tx_thread_created_count.
@item FreeRTOS symbols
-@c The following is taken from recent texinfo to provide compatibility
-@c with ancient versions that do not support @raggedright
-@tex
-\begingroup
-\rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax
+@raggedright
pxCurrentTCB, pxReadyTasksLists, xDelayedTaskList1, xDelayedTaskList2,
pxDelayedTaskList, pxOverflowDelayedTaskList, xPendingReadyList,
uxCurrentNumberOfTasks, uxTopUsedPriority.
-\par
-\endgroup
-@end tex
+@end raggedright
@item linux symbols
init_task.
@item ChibiOS symbols
@item mqx symbols
_mqx_kernel_data, MQX_init_struct.
@item uC/OS-III symbols
-OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty
+OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty.
@item nuttx symbols
-g_readytorun, g_tasklisttable
+g_readytorun, g_tasklisttable.
@item RIOT symbols
-sched_threads, sched_num_threads, sched_active_pid, max_threads, _tcb_name_offset
+@raggedright
+sched_threads, sched_num_threads, sched_active_pid, max_threads,
+_tcb_name_offset.
+@end raggedright
@end table
For most RTOS supported the above symbols will be exported by default. However for