Stm32cubeide Eclipse

Why a new plug-in?

By default, Eclipse supports OpenOCD via the GDB Hardware Debuggingplug-in, which starts OpenOCD not as a separate daemon, but as apipe end. This is functional, but restricts it even further.

STM32CubeIDE is an advanced C/C development platform with peripheral configuration, code generation, code compilation, and debug features for STM32 microcontrollers and microprocessors. It is based on the Eclipse ® /CDT framework and GCC toolchain for the development. The result of the above command is a clean build of the given project configuration from the given workspace. Warning: special care must be observed when entering the path to workspace, since Eclipse will not complain if the workspace does not exist, instead it will create a new one at the given location and then most probably complain that the project is missing.

Based on the experience with the J-Link plug-in, we decided to adda separate OpenOCD plug-in, with full configuration pages. War thunder register.

In early 2015, a step further was performed, with the addition ofthe GNU MCU Eclipse OpenOCD subproject, a new distribution of OpenOCD.In 2019 it was migrated to the xPack project.

Unfortunately SWD support in the current OpenOCD version (0.8.x) isnot that great, and we could not yet figure out a way to get the SWOtracing info out of OpenOCD, so currently there is no special tracingwindow available.


Before being able to use any JTAG probe with OpenOCD, you must separately install:

  • the OpenOCD debugging plug-in
  • the GDB debugger (client) application, as part of a GNU toolchain
  • the OpenOCD as a GDB server
  • any drivers required for the JTAG probe (for example FTDI drivers).

If you did not do it yet, please follow the instructions in thexPack OpenOCD install page and returnwhen completed.

The presence of a GDB as part of a GNU toolchain is mandatory, and itis recommended that the version of the GDB client matches the toolchain.Generally only debugging .elf applications is possible, and theseapplications must be compiled to include GNU compatible debugginginformation (like dwarf).

Non-GNU toolchains

Debugging applications generated by non-GNU toolchains(like the obsolete Arm CC), although not completely excluded,is not supported.

How to use the OpenOCD plug-in

Define the OpenOCD folder location

Before starting work with OpenOCD, it is recommended to define thepath to the folder where OpenOCD executables are located.

  • in the Eclipse menu, go to (Window →) PreferencesMCUGlobal OpenOCD Path (or Workspace OpenOCD Path)

  • click the Restore Defaults button
  • the plug-in will suggest the default values computed when Eclipsestarted; if a new version of OpenOCD was installed while Eclipse wasactive, restart Eclipse and click again the Restore Defaults button
  • check the Executable field; it must define the name of the commandline OpenOCD executable; in most cases it should be set correctly; if not,edit it to match the correct name;
  • check the Folder field; it must point to the actual folder wherethe OpenOCD tools were installed on your platform, for example C:UsersilgAppDataRoamingxPacksOpenOCD<version>binon Windows, /Users/ilg/opt/xPacks/openocd/<version>/bin on macOSand GNU/Linux
  • click the OK button

By default, the GDB server is defined as${openocd_path}/${openocd_executable}; these two macros areautomatically set by the above preference page; for portabilityreasons, it is recommended to define the path to the OpenOCD relativeto this variable in all your debug configurations, to have a singleplace to update the path when you want to use another version ofthe OpenOCD tools installed in a different location.

Create the debugger configuration

Being a standard debugger, this plug-in also uses the Eclipsestandard method of creating debugger configurations for eachapplication. After you successfully build your application,you can create a new debug configuration following these steps:

  • select the project (don’t skip it, this is important, see later)
  • build it and ensure the executable file is available
  • expand the Debug/Release folder and select the new executable file
  • in the Eclipse menu, go to RunDebug Configurations… orselect the down arrow at the right of the bug icon
  • double click on the GDB OpenOCD Debugging group, or select itand click the top leftmost New button

  • a multi-tab page will be displayed
  • if you started this procedure with the executable file selected,the first tab, named Main, should be already filled in with theproject name (for example blink1) and the application file name andlocation (for example Debug/blink1.elf).

  • click the second tab, named Debugger, which contains theconfiguration options required to start the GDB server and the GDB client

  • the only field that usually requires attention is the OpenOCDSetup Other options:, where you should add one or moreconfiguration scripts; for example, for the STM32F4DISCOVERYboard, the field should read -f board/stm32f4discovery.cfg

Note: it is mandatory to enter a reference to a configurationscript here, otherwise the debug session will not start. Use theOpenOCD documentation for details on how to start OpenOCD for various boards.

  • Windows notice: due to a platform specific issue, on Windows it isnot possible to disable the Allocate console for OpenOCD
  • click the third tab, named Startup, which contains somespecific OpenOCD options used to configure the debug session;defaults are generally enough

  • the order of sections/fields reflect the order commands aresent to GDB; for example the above generates:
  • select the Common tab, set the Save as: field toShared file and accept the current project name

  • this will arrange for the debug configuration to be saved inthe project, not in the workspace storage

  • click the Apply button
  • click the Close button

Start a debug session

Before starting a debug session, be sure that:

  • the JTAG probe is connected to the computer; if the connectionis via USB, use a high speed USB port, preferably directly to thecomputer, not via hubs which share the bandwidth with other trafficintensive devices, like disks, wi-fi, video cameras, etc.
  • the wide JTAG flat cable is connected both to the JTAG probeand to the target device
  • the target device is powered on

With all the above steps completed properly, you can start thedebug session:

  • in the Eclipse menu, go to RunDebug Configurations…
  • if necessary, expand the GDB OpenOCD Debugging group
  • select the newly defined configuration
  • click the Debug button

Alternatively, for later sessions, you can use the bug specificicon. Do not press it directly, since it will not behave asexpected; instead, click the down arrow button:

This will open a new window where you can select the desireddebug configuration:

If everything is ok, after a few seconds required to start the server,to allow it to connect to the target, start the gdb client, downloadthe application and start the debugging session, you should seesomething like this:

Since the first breakpoint was set in the Debugger tab tomain, the execution stopped right at the beginning of themain() function, which in this case is a tracing printf().

Debug operations

Once the debug session started and execution stopped in thefirst breakpoint (by default set at the beginning of the main()function), you can perform any debug operation you need.

The most common operations are:

  • single step over one source instruction (click the Step Over button)
  • single step into the next function called (click the Step Into button)
  • single step out of the current function (click the Step Return button)
  • set breakpoints (click the grey side area at the left of the source lines)
  • run (click the Resume button)
  • halt a running program (click the Suspend button)
  • inspect processor registers (use the Registers view)
  • inspect memory (use the Memory view)

For more details please read theRunning and debugging projectssection in the Eclipse documentation.

View consoles

Each debug process has a dedicated console, to display its standardoutput and standard error, or to get input for the standard input.

To see the console of any process, select the process in the topleft window. For example the gdb client console might look like this:

The semihosting tracing messages are displayed in the same windowas the OpenOCD output:

Show console when standard out/error change

This is the default Eclipse behaviour when multiple consoles areactive, to automatically switch to the latest updated. In our case,especially when the tracing console is also active, the focus willjump between windows, making things impossible to follow.

This mode can be identified by the status of the buttons on the rightside of the Debugging view.

To make the display stable on the desired console, disable bothbuttons. To switch between consoles, select them either in thetop left Debug view, or using the right button, as shown above.

The Restart button

Apparently not a big deal, but quite useful for repeated debugsessions, the Restart button can be used at any time duringa debug session, and the result is that a reset is dispatched tothe target board via the JTAG/SWD interface and the debug sessionis restarted.

Note: Due to some bugs in Eclipse, the implementation of thissimple button has encountered several problems. Depending onthe version you are using, the first time you click this buttonyou might get a message box informing that the button was notenabled. Ignore this message, close the message box and clickthe button again, this time it’ll be effective.

Using a remote GDB server

If, for any reason, you need to run the GDB server on a remotemachine (for example the development board is connected viaOpenOCD to a machine in your office, but you are in anotherlocation), you can still use the plug-in to run debugging session.For this to work, just disable Start the GDB server locallyin the Debugger tab and instead of localhost for theHost name or IP address, enter the name or address wherethe GDB server can be accessed.

Then you must manually start the OpenOCD process on the remotemachine and only then you can start the debugging session.


Missing or wrong openocd_path

The most common failure to start a debug session is a missing or incorrecOpenOCD path. Without it, the launching sequence willcomplain Cannot run program “/openocd”.

Stm32cubeide eclipse plugin

Define the openocd_path as instructed above and the sessionshould start properly.

Wrong configuration selection

Stm32cubeide Eclipse

If the configuration files that you selected in the plug-in doesnot match the device physically connected, the OpenOCD starts,but remains in a confused state. The session does not startand usually requires to restart Eclipse.

Select the correct device and the session should start properly.

Start OpenOCD manually

If you still fail to configure the plug-in to start OpenOCDautomatically, proceed as when using a remote GDB server, i.e.go to the Debugger tab and disable the Start OpenOCD locally,then start it manually in a separate terminal. Tweak the commandline options until you get the right behaviour, and then retrythe same options with the plug-in.

Quote the entire echo command

The syntax required by the OpenOCD echo command is a singlestring, in other words both echo and the message must be in thesame string. To achieve this in a shell, the string must be quoted:

Note: this command is used by the plug-in to detect when the GDBserver is initialised and ready to receive commands. It is notnecessary when starting OpenCOD manually.

Stm32cubeide Eclipse

Chase for hanged OpenOCD processes

One usual error case is to retry a debug session while a previousOpenOCD is still active (either running or hanged, started by aprevious run of the plug-in or manually). In this case the newOpenOCD has no chance to work, and the plug-in will mostcertainly fail, sometimes even without clear error messages.

Be sure you chase and kill all previous OpenOCD or GDB processes,using the system process inspector, before starting new debug sessions.

Compare with GDB Hardware Debugging

If you still cannot make it work, before filling any support tickets,please try to launch the debug session using the GDB HardwareDebugging plug-in, in the DSF launcher configuration (not theLegacy GDB Hardware Debugging Launcher). If you get the samebehaviour, the problem is OpenOCD related (OpenOCD is notoriousfor subtle bugs), and cannot be fixed in the plug-in.

If the GDB Hardware Debugging plug-in works and the GDB OpenOCDdebugging plug-in doesn’t, rerun both of them with the log enabled,on exactly the same executable, and compare the results. If you donot discover the problem, open a support ticket and attach the log files.

No GDB initialisation files loaded

For having a total control of the debugging session, the debuggingplug-ins start the GDB client process with the --nx option, whichprevents the execution of the commands found in any initializationfile; none of the standard files (system.gdbinit, ~/.gdbinit,./.gdbinit) are loaded.

To add more commands to the GDB initialisation sequence, use theCommands: field in the GDB Client Setup section.

All commands listed here are passed to the GDB client. Byconvention, commands prefixed with mon will be further passedfrom the GDB client to the GDB server, in this case the OpenOCD server.

Stm32cubeide Import Eclipse Project

Semihosting writes are very slow

Yes, unfortunately this is an OpenOCD limitation. Avoid writingto stderr, which is excruciatingly slow.

More details

Although the plug-in takes care of most of the configurationoptions, and provides reasonable defaults for the usual cases,it is recommended to read the OpenOCD manuals, available in thedoc folder of your install location.

Comments on the content of this page that might be useful for other readers are welcomed here. For question and general support, please use the project forums.

Stm32cubeide Vs Eclipse

Please enable JavaScript to view the comments powered by Disqus.