boards: st: address recent OpenOCD deprecation of HLA interface #97638

etienne-lms · 2025-10-15T14:47:01Z

This change aims to address a compatibility issue with recent OpenOCD pre-release and what is planned in OpenOCD v1.0.0 planned end of 2025. OpenOCD commit 34ec5536c0ba ("stlink: deprecate HLA support") [1] was merged in December 2024 after release tag 0.12.0 and before coming release v1.0.0. It deprecates the legacy HLA driver interface (also called transport) in favor to the generic DAP interface that is supported by ST-Link firmware v2.1 and later.

Since the referred commit, OpenOCD config script must source a new config file (interface/stlink-hla.cfg) in order to select hla_swd transport. This change breaks many ST-Link based OpenOCD config files of Zephyr. Alternatively, already existing interface/stlink-dap.cfg can be used with dapdirect_swd interface to use direct DAP/SWD interface.

To overcome the issue and support older and newer OpenOCD releases, this change uses OpenOCD native board config script files when available or if none, we select the dapdirect_swd transport ID that is supported since a long time and still maintained thank to OpenOCD native interface/stlink-dap.cfg config script file.

One may potentially face connection issues if using both a recent OpenOCD tool and an ST-Link adapter that embeds a old ST-Link firmware v1.x. This ST-Link firmware only supports HLA interface. This situation may happen with old STM32 L0/L1/L4/F4 Nucleo/Discovery boards or with old ST-Link adapter devices. ST-Link firmware v1.0 do not support DAP direct SWD interface. In such a case, either upgrade the ST-Link firmware (see STM32CubeProgrammer guide), or revert the change made here to explicitly use hla_swd transport based on stlink-hla.cfg. Alternatively, use an older OpenOCD release which may not be desired.

Link: https://sourceforge.net/p/openocd/code/ci/34ec5536c0ba3315bc5a841244bbf70141ccfbb4/ [1]

etienne-lms · 2025-10-15T14:49:45Z

I plan to create dedicated P-Rs, per board vendor, for non-ST boards also affected by this OpenOCD change.
I initially plan to create 1 P-R per board vendor. If a single P-R to cover them all is preferred, feel free to tell me.

erwango

In last paragraph of the first commit message:

You should probably mention that such fw version is not shipped since X years.
Also, providing a first good version would allow users to quickly recognize they are in the
good case (v2j24 as provided in openocd commit message) would be nice.

erwango · 2025-10-20T16:03:12Z

boards/st/b_l072z_lrwan1/support/openocd.cfg


-transport select hla_swd
+# If you use a recent OpenOCD release (strictly after release tag v0.12.0)
+# and your targets embeds an ST-Link firmware v1 and you cannot upgrade it,


Suggested change

# and your targets embeds an ST-Link firmware v1 and you cannot upgrade it,

# and your targets embeds an ST-Link firmware earlier than v2j24 and you cannot upgrade it,

Apply everywhere

Ok, thanks. I've updated, also taking @mathieuchopstm proposal into consideration.

erwango · 2025-10-20T16:04:47Z

doc/releases/migration-guide-4.3.rst

+  deprecated recently (Decembrer 2024, see https://review.openocd.org/c/openocd/+/8523 and commit
+  https://sourceforge.net/p/openocd/code/ci/34ec5536c0ba3315bc5a841244bbf70141ccfbb4/). One may
+  face connection issues if using a recent OpenOCD tool (release tag stricly later v0.12.0) and
+  embeds an ST-Link firmware v1.x in its ST-Link adapter. In such a case, one needs to either


s/v1.x/earlier than v2j24

mathieuchopstm · 2025-10-20T16:00:34Z

boards/st/b_l072z_lrwan1/support/openocd.cfg

+# If you use a recent OpenOCD release (strictly after release tag v0.12.0)
+# and your targets embeds an ST-Link firmware v1 and you cannot upgrade it,
+# it is recommended to replace the 2 lines above with:
+#
+# source [find interface/stlink-hla.cfg]
+# transport select hla_swd


Is it merely recommended or is it necessary?

If I use a not recent OpenOCD release, what happens?

Proposed rework:

Suggested change

# If you use a recent OpenOCD release (strictly after release tag v0.12.0)

# and your targets embeds an ST-Link firmware v1 and you cannot upgrade it,

# it is recommended to replace the 2 lines above with:

#

# source [find interface/stlink-hla.cfg]

# transport select hla_swd

# If you use an OpenOCD version higher than 0.12.0 and your target embeds

# an ST-Link with firmware v1.x, connection will not work. It is recommended

# to upgrade the ST-Link firmware of the target; however, if not possible,

# the 2 lines above can be replaced with the following to connect successfully:

#

# source [find interface/stlink-hla.cfg]

# transport select hla_swd

Thanks for the rewording. I'll applied it.

boards/st/nucleo_wl55jc/support/openocd.cfg

mathieuchopstm · 2025-10-20T16:02:59Z

boards/st/stm32wb5mmg/support/openocd.cfg

-source [find target/stm32wbx.cfg]
-
-reset_config srst_only
+# OpenOCD nucleo_wb55/cfg matches stm32wb55mmg support


For consistency:

Suggested change

# OpenOCD nucleo_wb55/cfg matches stm32wb55mmg support

# OpenOCD st_nucleo_wb55k.cfg matches stm32wb55mmg support

mathieuchopstm · 2025-10-20T16:16:26Z

doc/releases/migration-guide-4.3.rst

+* STM32 boards OpenOCD configuration files have been changed to support latest OpenOCD as well as
+  older OpenOCD (v0.12.0 or older). The issue addressed is that HLA/SWD transport has been
+  deprecated recently (Decembrer 2024, see https://review.openocd.org/c/openocd/+/8523 and commit
+  https://sourceforge.net/p/openocd/code/ci/34ec5536c0ba3315bc5a841244bbf70141ccfbb4/). One may
+  face connection issues if using a recent OpenOCD tool (release tag stricly later v0.12.0) and
+  embeds an ST-Link firmware v1.x in its ST-Link adapter. In such a case, one needs to either
+  update its ST-Link firmware (recommended, refer the STM32CubeProgrammer tool documentation)
+  or change the OpenOCD configuration script to source "interface/stlink-hla.cfg" and select
+  "hla_swd" interface explicitly.


We can't say that files have been changed to support latest as well as older then 3 sentences later that old version don't work.

+ minor rewords

Suggested change

* STM32 boards OpenOCD configuration files have been changed to support latest OpenOCD as well as

older OpenOCD (v0.12.0 or older). The issue addressed is that HLA/SWD transport has been

deprecated recently (Decembrer 2024, see https://review.openocd.org/c/openocd/+/8523 and commit

https://sourceforge.net/p/openocd/code/ci/34ec5536c0ba3315bc5a841244bbf70141ccfbb4/). One may

face connection issues if using a recent OpenOCD tool (release tag stricly later v0.12.0) and

embeds an ST-Link firmware v1.x in its ST-Link adapter. In such a case, one needs to either

update its ST-Link firmware (recommended, refer the STM32CubeProgrammer tool documentation)

or change the OpenOCD configuration script to source "interface/stlink-hla.cfg" and select

"hla_swd" interface explicitly.

* STM32 boards OpenOCD configuration files have been changed to support latest OpenOCD versions

(> v0.12.0) in which the HLA/SWD transport has been deprecated (see

https://review.openocd.org/c/openocd/+/8523 and commit

https://sourceforge.net/p/openocd/code/ci/34ec5536c0ba3315bc5a841244bbf70141ccfbb4/).

Issues may be encountered when connecting to an ST-Link adapter running firmware v1.x

which does not support the new transport. In this case, the ST-Link firmware should

be upgraded or, if not possible, the OpenOCD configuration script should be changed to

source "interface/stlink-hla.cfg" and select the "hla_swd" interface explicitly.

+ maybe we should mention the latter must be done if running old OpenOCD?

Ok, thanks for the proposal. I've append a last sentence: "Backward compatibility with OpenOCD v0.12.0 or older is maintained.".

This change aims to address a compatibility issue with recent OpenOCD pre-release and what is planned in OpenOCD v1.0.0 planned end of 2025. OpenOCD commit 34ec5536c0ba ("stlink: deprecate HLA support") [1] was merged in December 2024 after release tag 0.12.0 and before coming release v1.0.0. It deprecates the legacy HLA driver interface (also called transport) in favor to the generic DAP interface that is supported by ST-Link firmware v2.1 (that is version v2j24) and later. Since the referred commit, OpenOCD config script must source a new config file (interface/stlink-hla.cfg) in order to select hla_swd transport. This change breaks many ST-Link based OpenOCD config files of Zephyr. Alternatively, already existing interface/stlink-dap.cfg can be used together with dapdirect_swd interface to use direct DAP interface. To overcome the issue and support older and newer OpenOCD releases, this change uses OpenOCD native board config script files when available or if none, we select the dapdirect_swd transport ID that is supported since a long time and still maintained thank to OpenOCD native interface/stlink-dap.cfg config script file. One may potentially face connection issues if using both a recent OpenOCD tool and an ST-Link adapter that embeds a old ST-Link firmware v1.x. This ST-Link firmware only supports HLA interface. It is not shipped by ST in ST-Link adapter since 2015. This situation however may happen with old STM32 L0/L1/L4/F4 Nucleo/Discovery boards or with old ST-Link adapter devices. ST-Link firmware v1.0 do not support DAP direct SWD interface. In such a case, either upgrade the ST-Link firmware (see STM32CubeProgrammer guide), or revert the change made here to explicitly use hla_swd transport based on stlink-hla.cfg. Alternatively, use an older OpenOCD release which may not be desired. Link: https://sourceforge.net/p/openocd/code/ci/34ec5536c0ba3315bc5a841244bbf70141ccfbb4/ [1] Signed-off-by: Etienne Carriere <[email protected]>

A recent change in OpenOCD deprecates ST-Link HLA interface requiring changes in some board OpenOCD configuration files in the Zephyr tree. Since this deprecation, in order to support old and recent OpenOCD tool we needed to change of debug driver interface for these boards, potentially causing trouble to user to have a recent OpenOCD and an old ST-Link adapter firmware. Therefore add an entry in the migration guide to give some hints on the potential issue and how to address it. Signed-off-by: Etienne Carriere <[email protected]>

etienne-lms · 2025-10-22T06:08:25Z

Updated with review comments addressed.

sonarqubecloud · 2025-10-22T06:28:38Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

erwango

I first commit 2 ST-Link firmware v1.0 mentions remain which would be good to be fixed. Non blocking though

mathieuchopstm

Non-blocking remarks:

mathieuchopstm · 2025-10-22T12:02:34Z

boards/st/nucleo_l152re/support/openocd.cfg

-source [find target/stm32l1x_dual_bank.cfg]
-
-reset_config srst_only
+# http://openocd.zylin.com/#/c/5829/ was merged in 2020


Nit: this could be dropped entirely (moved to commit message if anything)

Suggested change

# http://openocd.zylin.com/#/c/5829/ was merged in 2020

mathieuchopstm · 2025-10-22T12:05:29Z

doc/releases/migration-guide-4.3.rst

+  Issues may be encountered when connecting to an ST-Link adapter running firmware prior
+  v2j24 which do not support the new transport. In this case, the ST-Link firmware should
+  be upgraded or, if not possible, the OpenOCD configuration script should be changed to
+  source "interface/stlink-hla.cfg" and select the "hla_swd" interface explicitly.
+  Backward compatibility with OpenOCD v0.12.0 or older is maintained.


Nit:

Suggested change

Issues may be encountered when connecting to an ST-Link adapter running firmware prior

v2j24 which do not support the new transport. In this case, the ST-Link firmware should

be upgraded or, if not possible, the OpenOCD configuration script should be changed to

source "interface/stlink-hla.cfg" and select the "hla_swd" interface explicitly.

Backward compatibility with OpenOCD v0.12.0 or older is maintained.

Issues may be encountered when connecting to an ST-Link adapter running firmware prior

to version V2J24 which do not support the new transport. In this case, the ST-Link firmware should

be upgraded or, if not possible, the OpenOCD configuration script should be changed to

source "interface/stlink-hla.cfg" and select the "hla_swd" interface explicitly.

Backward compatibility with OpenOCD v0.12.0 or older is maintained.

(I'll let you re-align paragraph to fit length limit)

mathieuchopstm · 2025-10-22T12:06:28Z

boards/st/st25dv_mb1283_disco/support/openocd.cfg

+# If you use an OpenOCD version higher than 0.12.0 and your target embeds
+# an ST-Link firmware earlier than v2j24, connection will not work.
+# It is recommended to upgrade the ST-Link firmware of the target,
+# however, if not possible, the 2 lines above can be replaced with the
+# following to connect successfully:
+#
+# source [find interface/stlink-hla.cfg]
+# transport select hla_swd


Nit:

Suggested change

# If you use an OpenOCD version higher than 0.12.0 and your target embeds

# an ST-Link firmware earlier than v2j24, connection will not work.

# It is recommended to upgrade the ST-Link firmware of the target,

# however, if not possible, the 2 lines above can be replaced with the

# following to connect successfully:

#

# source [find interface/stlink-hla.cfg]

# transport select hla_swd

# If you use an OpenOCD version higher than 0.12.0 and your target embeds

# an ST-Link adapter running a firmware earlier than version V2J24, connection will not work.

# It is recommended to upgrade the ST-Link firmware of the target adapter;

# however, if not possible, the 2 lines above can be replaced with the

# following to connect successfully:

#

# source [find interface/stlink-hla.cfg]

# transport select hla_swd

(ditto; I'll let you realign paragraphs to fit length limit)

zephyrbot added area: Boards/SoCs platform: STM32 ST Micro STM32 Release Notes To be mentioned in the release notes labels Oct 15, 2025

zephyrbot requested review from FRASTM, GeorgeCGV, HoZHel, asm5878, cfriedt, djiatsaf-st, erwango, gautierg-st, jhedberg, kartben, marwaiehm-st and mathieuchopstm October 15, 2025 14:48

zephyrbot assigned erwango Oct 15, 2025

etienne-lms mentioned this pull request Oct 15, 2025

boards: OpenOCD deprecation of ST-Link HLA interface #97643

Open

etienne-lms force-pushed the stm32-openocd-hla branch from 3720fe4 to 5e77d4f Compare October 15, 2025 15:49

etienne-lms added this to the v4.3.0 milestone Oct 16, 2025

erwango requested changes Oct 20, 2025

View reviewed changes

mathieuchopstm reviewed Oct 20, 2025

View reviewed changes

etienne-lms added 2 commits October 22, 2025 08:06

etienne-lms force-pushed the stm32-openocd-hla branch from 5e77d4f to 6dd2f3e Compare October 22, 2025 06:07

erwango approved these changes Oct 22, 2025

View reviewed changes

mathieuchopstm approved these changes Oct 22, 2025

View reviewed changes

jhedberg merged commit b6b75d9 into zephyrproject-rtos:main Oct 22, 2025
26 checks passed

	# and your targets embeds an ST-Link firmware v1 and you cannot upgrade it,
	# and your targets embeds an ST-Link firmware earlier than v2j24 and you cannot upgrade it,

	# OpenOCD nucleo_wb55/cfg matches stm32wb55mmg support
	# OpenOCD st_nucleo_wb55k.cfg matches stm32wb55mmg support

boards: st: address recent OpenOCD deprecation of HLA interface #97638

boards: st: address recent OpenOCD deprecation of HLA interface #97638

Conversation

etienne-lms commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

etienne-lms commented Oct 15, 2025

Uh oh!

erwango left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

etienne-lms commented Oct 22, 2025

Uh oh!

sonarqubecloud bot commented Oct 22, 2025

Quality Gate passed

Uh oh!

erwango left a comment

Choose a reason for hiding this comment

Uh oh!

mathieuchopstm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

etienne-lms commented Oct 15, 2025 •

edited

Loading