The J-Link hardware debugging Eclipse plug-in

Quicklinks

If you already know what are the features of the new plug-in and just want to know how to install/use it, you can directly skip to:

• J-Link install
• J-Link plug-in usage

Why a new plug-in?

Until now, debugging with the J-Link probe in Eclipse was done via the GDB Hardware Debugging Plug-in. For experimental projects it was more or less ok, but for serious development it was quite tedious. The missing features, that were added to this plug-in, are:

• transparent integration of the GDB server, automatically started/stopped for each debug session
• advanced graphical user interface to configure most GDB client and GDB server SEGGER specific options
• transparent integration of the semihosting and Serial Wire Viewer (SWV) window as a standard Eclipse console
• a functional restart button, to reset the target and restart the debugging session, without having to rewrite the executable image
• direct use of project toolchain definition (prefix, suffix, path) to simplify configuration of the GDB client
• macro based J-Link folder path definition, for simplified management of the GDB server location when upgrades to new SEGGER versions are released
• support for SWO registers configuration to match a given system clock frequency

Prerequisites

Before being able to use the J-Link probe with the GNU ARM Eclipse Plug-in, you must separately install:

• the J-Link debugging plug-in
• the GDB debugger (client) application
• the SEGGER J-Link GDB server and drivers.

If you did not do it yet, please follow the instructions in the J-Link install page and return when completed.

J-Link plug-in usage

Define the J-Link folder location

Before starting work with the J-Link tools, it is recommended to define a global variable with the path to the J-Link folder.

• in the Eclipse menu, go to Preferences → Run/Debug → String Substitutions
• click the New… button
• in the Name: field enter jlink_path
• in the Value: field enter the actual folder where the J-Link tools were installed on your platform, for example /Applications/SEGGER/JLink on OS X
• click the OK button

Define a global variable with the path to the J-Link tools.

It is recommended to define the path to the GDB server relative to this variable in all your debug configurations, to have a single place to update the path when a new version of the J-Link tools is released.

Create the debugger configuration

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

• select the project
• build it and ensure the executable file is available
• in the Eclipse menu, go to Run → Debug Configurations… or select the down arrow at the right of the bug icon.

Debug configurations menu

• select the GDB SEGGER J-Link Debugging group

J-Link Debug Configurations.

• click the top leftmost New button and a multi-tab page will be displayed
• if you started this procedure with the project selected and the project was previously built, the first tab, named Main, should be already filled in with the project name (for example blink1) and the application file name and location (for example Debug/blink1.elf).

The Main tab.

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

The J-Link Debugger tab.

• the only field that usually requires attention is the Device name, which must identify the processor family; usually it is the family name; if you do not know it for your processor, follow the link at the right and copy/paste the string from the SEGGER web page.
• note: due to some implementation issues in the startup sequence of the J-Link GDB server, which ignores the -noreset option and always issues a target reset, the Connect to running target option, although fully implemented in the plug-in, is not yet functional; we are working close with the SEGGER specialists to fix it as soon as possible.
• click the third tab, named Startup, which contains specific J-Link options used to configure the debug session

The J-Link Startup tab.

• if you built the project with retargetting support for ITM/SWO, enter the CPU frequency and the desired SWO sampling frequency; for this to work with J-Link, the SWO sampling frequency must be a submultiple of 6MHz (6000000, 3000000, 2000000, 1500000, 1000000, etc) and the CPU frequency must be a multiple of the SWO sampling frequency (these apparently very complicated requirements end up as a pre-scaler value in an ARM register).
• for most applications running from flash, leave the Pre-run reset and halt enabled, this will issue a new reset after programming the flash and just before starting execution. Due to some complicated technical details, when the debugger tries to reset some cores, execution cannot be halted immediately, and part of the initialisation routine is executed. Then the flash is written with the new application, it is not correct to directly start execution, since part of a foreign initialisation sequence, that is not part of the current application, was executed; to be sure the application starts correctly, it is necessary to issue a new reset. Please note that this does not apply for applications running from RAM, since the reset may damage the RAM content.
• select the Common tab, set the Save as: field to Shared file and accept the current project name

Shared debug configuration.

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

Debug configuration stored in the project.

• click the Apply button
• click the Close button

Start a debug session

Before starting a debug session, be sure that:

• the J-Link debugger is connected to a high speed USB port, preferably directly to the computer, not via hubs which share the bandwidth with other traffic intensive devices, like disks, wi-fi, video cameras, etc.
• the wide JTAG flat cable is connected both to the J-Link and the target device
• the target device is powered on

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

• in the Eclipse menu, go to Run → Debug Configurations…
• if necessary, expand the GDB SEGGER J-Link Debugging group
• select the newly defined configuration
• click the Debug button

Alternatively, you can use the bug specific icon. Do not press it directly, since it will not behave as expected; instead, click the down arrow button:

Down arrow debug.

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

Select the debug 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, download the application and start the debugging session, you should see something like this:

The new debug session, with three consoles.

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

To see the content of the other consoles, just select them in the top left window. For example the server console might look like this:

The GDB server console.

Similarly for the tracing console:

The tracing console.

Show console when standard out/error change

This is the default Eclipse behaviour when multiple consoles are active, to automatically switch to the latest updated. In our case, especially when the Semihosting/SWV console is also active, the focus will jump between windows, making things impossible to follow.

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

Show console when standard out/err changes.

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

The Restart button

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

The Restart button.

Using a remote GDB server

If, for any reason, you need to run the GDB server on a remote machine (for example the development board is connected via J-Link to a machine in your office, but you are in another location), you can still use the plug-in to run debugging session. For this to work, just disable Start the GDB server locally in theDebugger tab and instead of localhost for the Host name or IP address, enter the name or address where the GDB server can be accessed.

Then you must manually start the JLinkGDBServer process on the remote machine and only then you can start the debugging session.

Troubleshooting

Missing or wrong jlink_path

The first failure to start a debug session is missing to enter the J-Link path. Without it, the launching sequence will complain Cannot run program “/JLinkGDBServer”.

Cannot run the JLinkGDBServer.

Define the jlink_path as instructed above and the session should start properly.

Wrong device selection

If the devices that you selected in the plug-in does not match the device physically connected, the GDB server session fails and the entire debug session is cancelled. You can identify this case by studying the GDB server log.

Wrong device.

Select the device properly and the session should start properly.

J-Link hangups

Although SEGGER took special measures to avoid J-Link firmware hangups, in case you suspect such a situation (the JLinkGDBServer refuses to connect to the USB device, or to the target), it might help to power cycle the J-Link, by disconnecting and reconnecting the USB cable.

Cannot start applications running from RAM

Please be sure you disable the Pre-run reset and halt option in the Startup tab, this usually does not preserve the RAM content.

More info

Although the plug-in takes care of most of the configuration options, and provides reasonable defaults for the usual cases, it is recommended to read the SEGGER manuals, available from the Doc folder in the installation location or directly from the SEGGER J-Link page.