stlink: simplify the use of deprecated HLA transport

Commit 34ec553 ("stlink: deprecate HLA support") makes hard
to use the still functional HLA transport with the stlink listed
in board config files.
Now that the prefixes 'hla_' and 'dapdirect_' has been dropped
from the transport name, allow overriding the transport by using
the 'stlink-hla' script in front of the board file, e.g.:

	openocd -f interface/stlink-hla.cfg -f board/st_nucleo_f4.cfg

Revert the documentation changes of the change above.
Improve the documentation to explain how to use the compatibility
HLA mode.
Improve the error message in stlink driver to guide the user to
update the stlink firmware and to use the compatibility HLA mode.

Change-Id: I5d0bc7954511692cebe024bda2aaa72767b97681
Signed-off-by: Antonio Borneo <[email protected]>
Reviewed-on: https://review.openocd.org/c/openocd/+/8679
Tested-by: jenkins

Author: borneoa

doc/openocd.texi

@@ -2497,7 +2497,7 @@ This command is only available if your libusb1 is at least version 1.0.16.
 Specifies the @var{serial_string} of the adapter to use.
 If this command is not specified, serial strings are not checked.
 Only the following adapter drivers use the serial string from this command:
-arm-jtag-ew, cmsis_dap, esp_usb_jtag, ft232r, ftdi, hla (ti-icdi), jlink, kitprog, opendus,
+arm-jtag-ew, cmsis_dap, esp_usb_jtag, ft232r, ftdi, hla (stlink, ti-icdi), jlink, kitprog, opendus,
 openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
 @end deffn
 
@@ -3205,23 +3205,35 @@ that OpenOCD would normally use to access the target.
 
 Currently supported adapters include the STMicroelectronics ST-LINK, TI ICDI
 and Nuvoton Nu-Link.
+
 ST-LINK firmware version >= V2.J21.S4 recommended due to issues with earlier
 versions of firmware where serial number is reset after first use.  Suggest
 using ST firmware update utility to upgrade ST-LINK firmware even if current
 version reported is V2.J21.S4.
+The ST-LINK firmware update utility is available for download from
+@url{https://www.st.com/en/development-tools/stsw-link007.html, ST website}.
 
 @deffn {Config Command} {hla device_desc} description
 Currently Not Supported.
 @end deffn
 
-@deffn {Config Command} {hla layout} (@option{icdi}|@option{nulink})
+@deffn {Config Command} {hla layout} (@option{stlink}|@option{icdi}|@option{nulink})
 Specifies the adapter layout to use.
 @end deffn
 
 @deffn {Config Command} {hla vid_pid} [vid pid]+
 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.
@@ -3236,6 +3248,11 @@ directly access the arm ADIv5 DAP.
 
 The older API that requires HLA transport is deprecated and will be dropped
 from OpenOCD. In mean time it's still available by using @file{interface/stlink-hla.cfg}.
+The HLA interface file can be put as first command line argument to
+force using is in place of the default DAP API.
+@example
+openocd -f interface/stlink-hla.cfg -f board/st_nucleo_f4.cfg
+@end example
 
 The new API provide access to multiple AP on the same DAP, but the
 maximum number of the AP port is limited by the specific firmware version

src/jtag/drivers/stlink_usb.c

@@ -5143,7 +5143,12 @@ static int stlink_dap_init(void)
 
 	if ((mode != STLINK_MODE_DEBUG_SWIM) &&
 		!(stlink_dap_handle->version.flags & STLINK_F_HAS_DAP_REG)) {
-		LOG_ERROR("ST-Link version does not support DAP direct transport");
+		LOG_ERROR("The firmware in the ST-Link adapter only supports deprecated HLA.");
+		LOG_ERROR("Please consider updating the ST-Link firmware with a version");
+		LOG_ERROR("newer that V2J24 (2015), available for downloading on ST website:");
+		LOG_ERROR("  https://www.st.com/en/development-tools/stsw-link007.html");
+		LOG_ERROR("In mean time, you can re-run OpenOCD for ST-Link HLA as:");
+		LOG_ERROR("  openocd -f interface/stlink-hla.cfg ...");
 		return ERROR_FAIL;
 	}
 	return ERROR_OK;

tcl/interface/stlink.cfg

@@ -10,6 +10,12 @@
 # SWIM transport is natively supported
 #
 
+if { [adapter name] == "hla" } {
+	# Deprecated HLA adapter driver already selected.
+	# Quit silently, as the ST-LINK driver already complains.
+	return
+}
+
 adapter driver st-link
 st-link vid_pid 0x0483 0x3744 0x0483 0x3748 0x0483 0x374b 0x0483 0x374d 0x0483 0x374e 0x0483 0x374f 0x0483 0x3752 0x0483 0x3753 0x0483 0x3754 0x0483 0x3755 0x0483 0x3757