X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=b3fe8540435b49ae197478645600ed1b7fe4eb68;hb=b0fe92dba7c01adc25e5fe3552253a4a8c69ae1a;hp=34f1bb6539a169940d8d3883fdaa9f9a0366ff84;hpb=4c0c6ebf02bbeeb7f6c6811a512f68b0594277c0;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 34f1bb6539..b3fe854043 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -298,7 +298,6 @@ The OpenOCD Bug Tracker is hosted on SourceForge: @cindex dongles @cindex FTDI @cindex wiggler -@cindex zy1000 @cindex printer port @cindex USB Adapter @cindex RTCK @@ -307,12 +306,7 @@ Defined: @b{dongle}: A small device that plugs into a computer and serves as 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 @@ -334,26 +328,6 @@ Ethernet port needed? 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 @@ -2155,9 +2129,6 @@ disables the gdb server. 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. @@ -3225,20 +3196,6 @@ The string will be of the format "DDDD:BB:SS.F" such as "0000:65:00.1". @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. @@ -8288,66 +8245,6 @@ with handlers for that event. @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 @@ -8869,29 +8766,6 @@ how the event caused trouble. @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 @@ -9114,23 +8988,6 @@ cables (FT2232), but might be unsafe if used with targets running at very low 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 @@ -9184,18 +9041,6 @@ shown in bits 38..33 of table 9-9 in the ARM920T TRM. (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 @@ -9503,60 +9348,145 @@ Selects whether interrupts will be processed when single stepping @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 @@ -9585,12 +9515,20 @@ baud with our custom divisor to get 12MHz) @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