add new target into openocd

Hi I am new at openocd. I want to program samL11E15A (programming via swd) in my custom board. I could program it with atmel studio using ATMEL-ICE hardware in windows. Now i want to program the chip by openocd and i do not know which /interface/? config file I have to use, or I have to write my openocd.cfg for config interface and target.

OpenOCD does not know how to talk the Black Magic Debug remote protocol, but also, that isn't necessary. We're presuming you're using a debug adaptor running this project's firmware - in this case, you already have a complete debug server ready to go in the adaptor. You only need to connect into the adaptor with GDB (Throw OOCD out the window, not relevant) and then do a SWD scan (monitor swd_scan) and attach to your target (attach 1). This is all covered in the getting started guide on the project website.

OpenOCD works with dumb adaptors like the ST-Link, J-Link, or something that talks CMSIS-DAP. Those require external software like Black Magic Debug App or OOCD to function and debug targets. Black Magic Debug, however, is a complete GDB server in a dongle w/ BMDA only necessary to work with dumb adaptors or talk with targets that have not had support built into the firmware but which are supported.

Please note, we are not certain that the ATSAML11E15A is supported by the firmware right now, however debugging will still work. Adding support for the Flash interface on that target should be reasonably straight forward though if missing.

Hi Thank you for your answer. I use Ubuntu for my project. I used Black magic Debug firmware on a stm32 blue pill board and I could program another stm32 board with that. but my problem was adding a new target and programming a new target that is not supported by Black magic Debug firmware so i used openocd for adding a new target and new interface. Firstly I have a basic question: ST-Link, J-Link ,... are only adapters to make the right electrical connection or the firmware of these adapters are important. I mean that when i want to program a new target using openocd (for example SAML) i have to only change openocd or the firmware of the adapter has to be changed and the firmware of ST-Link, J-Link, ... have to support my new target. secondly in your answer: we are not certain that the ATSAML11E15A is supported by the firmware right now Which firmware do you mean?

sincerely Maryam Rahmati

On Mon, Sep 16, 2024 at 1:18 PM Rachel Mant @.***> wrote:

OpenOCD does not know how to talk the Black Magic Debug remote protocol, but also, that isn't necessary. We're presuming you're using a debug adaptor running this project's firmware - in this case, you already have a complete debug server ready to go in the adaptor. You only need to connect into the adaptor with GDB (Throw OOCD out the window, not relevant) and then do a SWD scan (monitor swd_scan) and attach to your target (attach 1). This is all covered in the getting started https://black-magic.org/getting-started.html guide on the project website.

OpenOCD works with dumb adaptors like the ST-Link, J-Link, or something that talks CMSIS-DAP. Those require external software like Black Magic Debug App or OOCD to function and debug targets. Black Magic Debug, however, is a complete GDB server in a dongle w/ BMDA only necessary to work with dumb adaptors or talk with targets that have not had support built into the firmware but which are supported.

Please note, we are not certain that the ATSAML11E15A is supported by the firmware right now, however debugging will still work. Adding support for the Flash interface on that target should be reasonably straight forward though if missing.

— Reply to this email directly, view it on GitHub https://github.com/blackmagic-debug/blackmagic/issues/1932#issuecomment-2352456183, or unsubscribe https://github.com/notifications/unsubscribe-auth/A4NCX3DEZVY2RWFMJ336JOTZW2SNBAVCNFSM6AAAAABOI4YT7OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGNJSGQ2TMMJYGM . You are receiving this because you authored the thread.Message ID: @.***>

You seem to have hyper-fixated on OpenOCD, and that's clouding the picture badly, so let us try and walk you back a little and fill things in a bit. Note that OOCD is not the only host-side debug server option and the firmware on the adaptor you use does matter significantly as it defines the communications protocol between host and dongle and if a host-side debug server is even necessary in the first place.

There are 3-4 moving pieces in embedded debugging each of which can be permutated:

The debugger itself - typically GDB, but could also be LLDB or a Vendor-specific product. For the debug servers talked about, however, these are the only two options.
The debug server - this is what OpenOCD is, and also what Black Magic Debug is (although BMD crosses into the next item too), you only need one of these and this is what you connect into from GDB. It talks to the debug adaptor (or in BMD's case absent BMDA.. is the debug adaptor) using a protocol specific to the firmware running on the adaptor.
The debug adaptor - this is what BMP, ST-Link, J-Link and friends are. Depending on the firmware being run, this means they either:
- Are a debug server in their own right (BMP, and things running the firmware from this project) but can talk this project's remote protocol (for use with Black Magic Debug App (BMDA), OpenOCD does not know how to talk this protocol)
- Talk a dumb debugging protocol - this covers J-Link, CMSIS-DAP and FTDI adaptors
- Talk a semi-smart debugging protocol - this is an ST-Link running ST's firmware, but not Black Magic Debug, as that's the first category of debug adaptors.
The debug target - this is the thing you want to debug, in your case that's a ATSAML11.

If you want to add support for the ATSAML11 to Black Magic Debug, you want to use BMDA with your debug adaptor and implement the support into the ATSAMD target implementation. This is what our comment about whether the firmware supports it or not was to do with.

BMD itself is a fully config-less debug server that combines a debug server directly into the adaptor, eliminating the need for external software like OpenOCD. It makes use of automatic detection and configuration of the target with integral target support to provide debugging and Flash reprogramming support. Debug is always possible with supported architectures regardless of specific target support.

Again, OpenOCD does not know how to talk BMD's remote protocol for using the debug adaptor as a semi-dumb adaptor, so for that you need BMDA which replaces OpenOCD as a host-side debug server. When running the firmware from this project on a ST-Link, it ceases to be a ST-Link talking the ST-Link protocol, and becomes a Black Magic Probe talking the BMD remote protocol + GDB remote protocol.

Note: (semi-)dumb adaptors (things like ST-Links running ST's firmware, and J-Links) are only providing access to the debug bus (JTAG/SWD) via a firmware-specific protocol to talk with targets and have to be told by the host what to do to actually talk with any target and do debug stuff. This is the role that BMDA and OpenOCD specifically fulfil.

Hi Thank you very much for your good answer. Actually, I have an educational project that I want to make a universal programmer (or debugger) that I could add a new target to if I want. When I was researching it ,I saw some stuff about openocd and Black Magic Debug. If you know any server debug please let me know.

On Mon, Sep 16, 2024 at 11:51 PM Rachel Mant @.***> wrote:

You seem to have hyper-fixated on OpenOCD, and that's clouding the picture badly, so let us try and walk you back a little and fill things in a bit. Note that OOCD is not the only host-side debug server option and the firmware on the adaptor you use does matter significantly as it defines the communications protocol between host and dongle and if a host-side debug server is even necessary in the first place.

There are 3-4 moving pieces in embedded debugging each of which can be permutated:

The debugger itself - typically GDB, but could also be LLDB or a Vendor-specific product. For the debug servers talked about, however, these are the only two options.

The debug server - this is what OpenOCD is, and also what Black Magic Debug is (although BMD crosses into the next item too), you only need one of these and this is what you connect into from GDB. It talks to the debug adaptor (or in BMD's case absent BMDA.. is the debug adaptor) using a protocol specific to the firmware running on the adaptor.

The debug adaptor - this is what BMP, ST-Link, J-Link and friends are. Depending on the firmware being run, this means they either:

Are a debug server in their own right (BMP, and things running the firmware from this project) but can talk this project's remote protocol (for use with Black Magic Debug App (BMDA), OpenOCD does not know how to talk this protocol)

Talk a dumb debugging protocol - this covers J-Link, CMSIS-DAP and FTDI adaptors

Talk a semi-smart debugging protocol - this is an ST-Link running ST's firmware, but not Black Magic Debug, as that's the first category of debug adaptors.

The debug target - this is the thing you want to debug, in your case that's a ATSAML11.

If you want to add support for the ATSAML11 to Black Magic Debug, you want to use BMDA with your debug adaptor and implement the support into the ATSAMD target implementation https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/samd.c. This is what our comment about whether the firmware supports it or not was to do with.

BMD itself is a fully config-less debug server that combines a debug server directly into the adaptor, eliminating the need for external software like OpenOCD. It makes use of automatic detection and configuration of the target with integral target support to provide debugging and Flash reprogramming support. Debug is always possible with supported architectures regardless of specific target support.

Again, OpenOCD does not know how to talk BMD's remote protocol for using the debug adaptor as a semi-dumb adaptor, so for that you need BMDA which replaces OpenOCD as a host-side debug server. When running the firmware from this project on a ST-Link, it ceases to be a ST-Link talking the ST-Link protocol, and becomes a Black Magic Probe talking the BMD remote protocol + GDB remote protocol.

Note: (semi-)dumb adaptors (things like ST-Links running ST's firmware, and J-Links) are only providing access to the debug bus (JTAG/SWD) via a firmware-specific protocol to talk with targets and have to be told by the host what to do to actually talk with any target and do debug stuff. This is the role that BMDA and OpenOCD specifically fulfil.

— Reply to this email directly, view it on GitHub https://github.com/blackmagic-debug/blackmagic/issues/1932#issuecomment-2353893312, or unsubscribe https://github.com/notifications/unsubscribe-auth/A4NCX3HBDWWBBSS4CHB23I3ZW44WLAVCNFSM6AAAAABOI4YT7OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGNJTHA4TGMZRGI . You are receiving this because you authored the thread.Message ID: @.***>

Both are debug servers, and BMD itself is quite an easy project to add new targets to - much easier than OpenOCD in our honest opinion having tried to do both prior to taking maintainership of BMD.

The target driver guide needs updating to talk about ADIv6 and RISC-V Debug, but is otherwise entirely correct and valid still and gives a strong basis to work from. BMDA's test mode and verbosity can be used as in blackmagic -tv 5 (SWD) or blackmagic -tjv 5 (JTAG) to get diagnostics on what BMD is making of a target and what paths scan and discovery has gone through.

As long as you have the Technical Reference Manual (TRM) for your device and possibly also an Application Note on how its Flash programming works, writing Flash routines to program the device is reasonably straight-forward. You can also use one of the existing target implementations in BMD itself as a guide for how to go about this.

you are right, working with BMD is easier than OpenOCD, but in the target driver guide https://black-magic.org/hacking/target-drivers.html said that:

The generic logic for Cortex-M parts which is found in target/cortexm.c https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/cortexm.c. Please note, this presently supports the ARMv6-M and ARMv7-M profiles only.

The generic logic for Cortex-A parts which is found in target/cortexa.c https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/cortexa.c. Please note, this presently supports the ARMv7-M profile only.

Since the OpenOCD User’s Guide ( 26 August 2024 ) said that a lot of architecture of ARM , Nand Flash and Nor Flash supported, I had decided to try Open OCD but it was difficult. Now I try to use BMD again and I try to add a new target.

sincerely rahmati

On Sun, Sep 22, 2024 at 6:08 PM Rachel Mant @.***> wrote:

Both are debug servers, and BMD itself is quite an easy project to add new targets to - much easier than OpenOCD in our honest opinion having tried to do both prior to taking maintainership of BMD.

The target driver guide https://black-magic.org/hacking/target-drivers.html needs updating to talk about ADIv6 and RISC-V Debug, but is otherwise entirely correct and valid still and gives a strong basis to work from. BMDA's test mode and verbosity can be used as in blackmagic -tv 5 (SWD) or blackmagic -tjv 5 (JTAG) to get diagnostics on what BMD is making of a target and what paths scan and discovery has gone through.

As long as you have the Technical Reference Manual (TRM) for your device and possibly also an Application Note on how its Flash programming works, writing Flash routines to program the device is reasonably straight-forward. You can also use one of the existing target implementations in BMD itself as a guide for how to go about this.

— Reply to this email directly, view it on GitHub https://github.com/blackmagic-debug/blackmagic/issues/1932#issuecomment-2366819076, or unsubscribe https://github.com/notifications/unsubscribe-auth/A4NCX3ALHFVQ6IGOV3ZLS5DZX3I7ZAVCNFSM6AAAAABOI4YT7OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGNRWHAYTSMBXGY . You are receiving this because you authored the thread.Message ID: @.***>

Both of those notes are now out of date and need updating (this is part of the "guide needs updating" comment before). The Cortex-M support handles ARMv6-M through ARMv8-M, the Cortex-A/R support (now found in cortexar.c) supports both ARMv7-A/R and ARMv8-A/R cores. That makes all modern (Cortex) ARM cores supported.

blackmagic-debug / blackmagic

add new target into openocd #1932

The generic logic for Cortex-M parts which is found in target/cortexm.c https://github.com/blackmagic-debug/blackmagic/blob/main/src/target/cortexm.c. Please note, this presently supports the ARMv6-M and ARMv7-M profiles only.