stlink: deprecate HLA support

The STLink API that supports dap-direct is available from STLink
firmware v2j24, published in early 2015.
We can reasonably expect that any old STLink still in use today
has got at least one firmware update during the last 10 years.

Most of the board files in upstream OpenOCD still use the STLink
in HLA mode. This limits the test coverage of the dap-direct code,
which was introduced in OpenOCD v0.11.0.

- Rename interface/stlink.cfg as interface/stlink-hla.cfg to still
  provide support for HLA, adding a deprecated message.

- Rename interface/stlink-dap.cfg as interface/stlink.cfg to make
  dap-direct the default trasport.

- Add a redirect file interface/stlink-dap.cfg for users that have
  out-of-tree custom board files.

- Update all the board files to the new setup.

- Remove STLink HLA mentions from the documentation, while adding
  a reference to interface/stlink-hla.cfg

Checkpatch-ignore: LONG_LINE
Change-Id: I99366bb03cd3b83f8f408514e657f30e59813063
Signed-off-by: Antonio Borneo <[email protected]>
Reviewed-on: https://review.openocd.org/c/openocd/+/8523
Tested-by: jenkins
Reviewed-by: Andrzej Sierżęga <[email protected]>

Author: borneoa

doc/openocd.texi

@@ -2489,7 +2489,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 (stlink, ti-icdi), jlink, kitprog, opendus,
+arm-jtag-ew, cmsis_dap, esp_usb_jtag, ft232r, ftdi, hla (ti-icdi), jlink, kitprog, opendus,
 openjtag, osbdm, presto, rlink, st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
 @end deffn
 
@@ -3206,23 +3206,14 @@ version reported is V2.J21.S4.
 Currently Not Supported.
 @end deffn
 
-@deffn {Config Command} {hla layout} (@option{stlink}|@option{icdi}|@option{nulink})
+@deffn {Config Command} {hla layout} (@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.
@@ -3232,9 +3223,12 @@ passed as is to the underlying adapter layout handler.
 @anchor{st_link_dap_interface}
 @deffn {Interface Driver} {st-link}
 This is a driver that supports STMicroelectronics adapters ST-LINK/V2
-(from firmware V2J24), STLINK-V3 and STLINK-V3PWR, thanks to a new API that provides
+(from 2015 firmware V2J24), STLINK-V3 and STLINK-V3PWR, thanks to a new API that provides
 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 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
 (e.g. firmware V2J29 has 3 as maximum AP number, while V2J32 has 8).
@@ -10677,7 +10671,7 @@ baud with our custom divisor to get 12MHz)
 @item OpenOCD invocation line:
 @example
 openocd -f interface/stlink.cfg \
--c "transport select hla_swd" \
+-c "transport select dapdirect_swd" \
 -f target/stm32l1.cfg \
 -c "stm32l1.tpiu configure -protocol uart" \
 -c "stm32l1.tpiu configure -traceclk 24000000 -pin-freq 12000000" \

tcl/board/st_b-l475e-iot01a.cfg

@@ -6,7 +6,7 @@
 # This is for using the onboard STLINK
 source [find interface/stlink.cfg]
 
-transport select hla_swd
+transport select dapdirect_swd
 
 # increase working area to 96KB
 set WORKAREASIZE 0x18000

tcl/board/st_nucleo_8l152r8.cfg

@@ -3,7 +3,7 @@
 # This is a ST NUCLEO 8L152R8 board with a single STM8L152R8T6 chip.
 # http://www.st.com/en/evaluation-tools/nucleo-8l152r8.html
 
-source [find interface/stlink-dap.cfg]
+source [find interface/stlink.cfg]
 
 transport select swim
 

tcl/board/st_nucleo_8s208rb.cfg

@@ -3,7 +3,7 @@
 # This is a ST NUCLEO 8S208RB board with a single STM8S208RBT6 chip.
 # https://www.st.com/en/evaluation-tools/nucleo-8s208rb.html
 
-source [find interface/stlink-dap.cfg]
+source [find interface/stlink.cfg]
 
 transport select swim
 

tcl/board/st_nucleo_f0.cfg

@@ -10,7 +10,7 @@
 
 source [find interface/stlink.cfg]
 
-transport select hla_swd
+transport select dapdirect_swd
 
 source [find target/stm32f0x.cfg]
 

tcl/board/st_nucleo_f103rb.cfg

@@ -5,7 +5,7 @@
 
 source [find interface/stlink.cfg]
 
-transport select hla_swd
+transport select dapdirect_swd
 
 source [find target/stm32f1x.cfg]
 

tcl/board/st_nucleo_f3.cfg

@@ -5,7 +5,7 @@
 
 source [find interface/stlink.cfg]
 
-transport select hla_swd
+transport select dapdirect_swd
 
 source [find target/stm32f3x.cfg]
 

tcl/board/st_nucleo_f4.cfg

@@ -8,7 +8,7 @@
 
 source [find interface/stlink.cfg]
 
-transport select hla_swd
+transport select dapdirect_swd
 
 source [find target/stm32f4x.cfg]
 

tcl/board/st_nucleo_f7.cfg

@@ -5,7 +5,7 @@
 
 source [find interface/stlink.cfg]
 
-transport select hla_swd
+transport select dapdirect_swd
 
 source [find target/stm32f7x.cfg]
 

tcl/board/st_nucleo_g0.cfg

@@ -12,7 +12,7 @@
 
 source [find interface/stlink.cfg]
 
-transport select hla_swd
+transport select dapdirect_swd
 
 source [find target/stm32g0x.cfg]