arm_tpiu_swo: add support for independent TPIU and SWO

This is supposed to replace big part of armv7m_trace.[ch], since
TPIU is not only the one implemented in Cortex-M3 and M4.

Change-Id: I7588d16cbefe9cdb371c52fb0aa5cdfb48518804
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: http://openocd.zylin.com/5858
Tested-by: jenkins

doc/openocd.texi

@@ -9503,13 +9503,146 @@ 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
+
+ARM CoreSight provides several modules to generate debugging
+information internally (ITM, DWT and ETM). Their output is directed
+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.
+
+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.
+
+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.
+
+@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{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 @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 @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
+
+
+TODO: remove the old tpiu commands
 
 @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})) @
@@ -9585,13 +9718,22 @@ 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
 from 0). Port 0 is enabled on target creation automatically.

src/openocd.c

@@ -38,6 +38,7 @@
 #include <pld/pld.h>
 #include <target/arm_cti.h>
 #include <target/arm_adi_v5.h>
+#include <target/arm_tpiu_swo.h>
 #include <rtt/rtt.h>
 
 #include <server/server.h>
@@ -173,6 +174,10 @@ COMMAND_HANDLER(handle_init_command)
 		return ERROR_FAIL;
 	command_context_mode(CMD_CTX, COMMAND_EXEC);
 
+	/* in COMMAND_EXEC, after target_examine(), only tpiu or only swo */
+	if (command_run_line(CMD_CTX, "tpiu init") != ERROR_OK)
+		return ERROR_FAIL;
+
 	/* initialize telnet subsystem */
 	gdb_target_add_all(all_targets);
 
@@ -255,6 +260,7 @@ static struct command_context *setup_command_handler(Jim_Interp *interp)
 		&pld_register_commands,
 		&cti_register_commands,
 		&dap_register_commands,
+		&arm_tpiu_swo_register_commands,
 		NULL
 	};
 	for (unsigned i = 0; NULL != command_registrants[i]; i++) {
@@ -355,6 +361,7 @@ int openocd_main(int argc, char *argv[])
 
 	flash_free_all_banks();
 	gdb_service_free();
+	arm_tpiu_swo_cleanup_all();
 	server_free();
 
 	unregister_all_commands(cmd_ctx, NULL);

src/target/Makefile.am

@@ -113,6 +113,7 @@ ARM_DEBUG_SRC = \
 	%D%/etm.c \
 	$(OOCD_TRACE_FILES) \
 	%D%/etm_dummy.c \
+	%D%/arm_tpiu_swo.c \
 	%D%/arm_cti.c
 
 AVR32_SRC = \
@@ -214,6 +215,7 @@ ARC_SRC = \
 	%D%/etb.h \
 	%D%/etm.h \
 	%D%/etm_dummy.h \
+	%D%/arm_tpiu_swo.h \
 	%D%/image.h \
 	%D%/mips32.h \
 	%D%/mips64.h \

src/target/arm_tpiu_swo.h

@@ -0,0 +1,9 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+#ifndef OPENOCD_TARGET_ARM_TPIU_SWO_H
+#define OPENOCD_TARGET_ARM_TPIU_SWO_H
+
+int arm_tpiu_swo_register_commands(struct command_context *cmd_ctx);
+int arm_tpiu_swo_cleanup_all(void);
+
+#endif /* OPENOCD_TARGET_ARM_TPIU_SWO_H */