@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
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.
@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 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
Code Review / openocd.git / blobdiff