# Debugging with Eclipse

This topic explains how to setup and use [MCU Eclipse](https://gnu-mcu-eclipse.github.io/) with a _Segger Jlink adapter_ to debug PX4 running on NuttX (e.g. Pixhawk series boards).

## Required Hardware

* [J-Link EDU Mini](https://www.segger.com/products/debug-probes/j-link/models/j-link-edu-mini/)
* Adapter to connect Segger JLink to Flight Controller [SWD Debug Port](gdb_debugging/swd_debug) (debug port).
* Micro USB cable

## Installation

### PX4

Setup PX4 by following the normal guidelines:

* [Setup the PX4 Developer Environment/Toolchain](../getting_started/dev_env) for your platform (e.g. for Linux see: [Development Environment on Ubuntu LTS / Debian Linux](../getting_started/dev_env/dev_env_linux_ubuntu)).
* [Download PX4](../getting_started/building_px4) and optionally build it on the command line.

### Eclipse

To install _Eclipse_:

1. Download [Eclipse CDT for C/C++ Developers](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/) (MCU GitHub).
2. Extract the Eclipse folder and copy it anywhere (there is no need to run any install scripts).
3. Run _Eclipse_ and choose a location for your initial workbench.

### Segger Jlink Tools

To install the _Segger Jlink_ tools:

1. Download and run the [J-Link Software and Documentation Pack](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack) for your OS (Windows and Linux packages available).
   * On Linux the tools are installed in **/usr/bin**.

For more information, see: [https://gnu-mcu-eclipse.github.io/debug/jlink/install/](https://gnu-mcu-eclipse.github.io/debug/jlink/install/).

## First Use

1. Connect the _Segger JLink_ to the host computer and the [flight controller debug port](gdb_debugging/swd_debug) (via an adapter).
2. Power the flight controller.
3. Run _Eclipse_.
4. Add a source by choosing **File > Import > C/C++ > Existing Code as Makefile Project** and click **Next**.
5. Point it to the **PX4-Autopilot** folder and give it a name, then select _ARM Cross GCC_ in the _Toolchain for Indexer Settings_ and click **Finish**. Import takes a while, wait for it to complete.
6. Set the MCU settings: right-click on the top-level project in the Project Explorer, select _Properties_ then under MCU choose _SEGGER J-Link Path_. Set it as shown in the screenshot below. ![Eclipse: Segger J-Link Path](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-6fd36dd163343e56640ffb1daa733576479c5540%2Feclipse_segger_jlink_path.png?alt=media)
7. Update packs:
   * Click the small icon on the top right called _Open Perspective_ and open the _Packs_ perspective. ![Eclipse: Workspace](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-71b78ae4e090915e5f002f0cb352090fd91accd7%2Feclipse_workspace_perspective.png?alt=media)
   *   Click the **update all** button.

       :::tip This takes a VERY LONG TIME (10 minutes). Ignore all the errors about missing packages that pop up. :::

       ![Eclipse: Workspace Packs Perspective](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-c6f78b24d36aa245b54ddc343909ff814c1b0f06%2Feclipse_packs_perspective.jpg?alt=media)
   * The STM32Fxx devices are found in the Keil folder, install by right-clicking and then selecting **install** on the according device for F4 and F7.
8.  Setup debug configuration for target:

    * Right click project and open the _Settings_ (menu: **C/C++ Build > Settings**)
    * Choose the _Devices_ Tab, _Devices_ section (Not _Boards_).
    * Find the FMU chip you wish to debug.

    ![Eclipse: Select FMU in settings](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-303467ec61ef6905bfd0adef7dc4f2467625f4a9%2Feclipse_settings_devices_fmu.png?alt=media)
9. Select debug configurations with the small drop-down next to the bug symbol: ![Eclipse: Debug config](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-2e22e58f1d27f2e9318fb15db8bfe0de19a9d72f%2Feclipse_settings_debug_config.png?alt=media)
10. Then select _GDB SEGGER J-Link Debugging_ and then the **New config** button on the top left. ![Eclipse: GDB Segger Debug config](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-e094d5bbb2df584b3a62a82cda801b68f6efe523%2Feclipse_settings_debug_config_gdb_segger.png?alt=media)
11. Setup build config:

    * Give it a name and set the _C/C++ Application_ to the corresponding **.elf** file.
    * Choose _Disable Auto build_ :::note Remember that you must build the target from the command line before starting a debug session. :::

    ![Eclipse: GDB Segger Debug config](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-1909e8a617c63b1d728c5addf54195893dc1858d%2Feclipse_settings_debug_config_gdb_segger_build_config.png?alt=media)
12. The _Debugger_ and _Startup_ tabs shouldn’t need any modifications (just verify your settings with the screenshots below)

    ![Eclipse: GDB Segger Debug config: debugger tab](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-f3de787338e12c9a59c62651e0db026e186c69bf%2Feclipse_settings_debug_config_gdb_segger_build_config_debugger_tab.png?alt=media) ![Eclipse: GDB Segger Debug config: startup tab](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-795dca30799abd83adc9d34f5798956724f90139%2Feclipse_settings_debug_config_gdb_segger_build_config_startup_tab.png?alt=media)

## SEGGER Task-aware debugging

Task-aware debugging (also known as [thread-aware debugging](https://www.segger.com/products/debug-probes/j-link/tools/j-link-gdb-server/thread-aware-debugging/)) allows you to show the context of all running threads/tasks instead of just the stack current task. This is quite useful since PX4 tends to run many different tasks.

To enable this feature for use in Eclipse:

1. You first need to enable `CONFIG_DEBUG_TCBINFO` in the NuttX configuration for your build (to expose the TCB offsets).
   * Open a terminal in the root of your PX4-Autopilot source code
   *   In the terminal, open `menuconfig` using the appropriate make target for the build. This will be something like:

       ```
       make px4_fmu-v5_default boardguiconfig
       ```

       (See [PX4 Menuconfig Setup](../../hardware/porting_guide/porting_guide_config#px4-menuconfig-setup) for more information) on using the config tools).
   * Ensure that the _Enable TCBinfo struct for debug_ is selected as shown: ![NuttX: Menuconfig: CONFIG\_DEBUG\_TCBINFO](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-8438e544da4a73abf904f7537b9d24514b66fc4e%2Fnuttx_tcb_task_aware.png?alt=media)
2. Compile the **jlink-nuttx.so** library in the terminal by running the following command in the terminal: `make jlink-nuttx`
3.  Modify Eclipse to use this libary. In the _J-Link GDB Server Setup_ configuration, update **Other options** to include `-rtos /home/<PX4 path>/Tools/jlink-nuttx.so`, as shown in the image below.

    ![Eclipse: GDB Segger Debug config RTOS aware: debugger tab](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-011d18b30ef0fb9c8a256a0ddbc0c51beee6036a%2Feclipse_settings_debug_config_gdb_segger_task_aware.png?alt=media)
4.  When running the debugger you should see now multiple threads instead of just one:

    ![Eclipse: GDB Segger Debug config RTOS aware: debug session](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-65cd06e5db3ecd713eac00037e4941bfbb23bd16%2Feclipse_settings_debug_config_gdb_segger_task_aware_tasks.png?alt=media)

## Troubleshooting

### Target CPU not in Package Manager

If the target CPU does not appear in the package manager you may need these steps to get the register view working.

:::tip This should not generally happen (but anecdotally has been reported when connecting to an STM F7 controller). :::

Adding missing SVD files for the _Peripheral View_:

1. Find out where MCU Eclipse stores its packages (**Preferences > C/C++ > MCU Packages**): ![Eclipse: MCU Packages](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-af9ac4c1a9b172b480134c64dad77e43f90012cc%2Feclipse_mcu_packages.png?alt=media)
2. Download missing packages from: http://www.keil.com/dd2/Pack/
3. Open downloaded pack with a decompression tool, and extract the **.SVD** files from: **/CMSIS/SVD**.
4. Select desired **.SVD** file in: **Debug Options > GDB SEGGER JLink Debugging > SVD Path** ![Eclipse: SVD File path](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-192f20fd171cd7c85d79a3265562793cbe753b6b%2Feclipse_svd_file_path.png?alt=media)
