Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jedrzejboczar/nvim-dap-cortex-debug

Extension for nvim-dap providing integration with VS Code's cortex-debug
https://github.com/jedrzejboczar/nvim-dap-cortex-debug

Last synced: about 2 months ago
JSON representation

Extension for nvim-dap providing integration with VS Code's cortex-debug

Awesome Lists containing this project

README 

        
[![Lint](https://github.com/jedrzejboczar/nvim-dap-cortex-debug/actions/workflows/lint.yml/badge.svg)](https://github.com/jedrzejboczar/nvim-dap-cortex-debug/actions/workflows/lint.yml)



# nvim-dap-cortex-debug



An extension for [nvim-dap](https://github.com/mfussenegger/nvim-dap) providing integration with VS Code's [cortex-debug](https://github.com/Marus/cortex-debug) debug adapter.



## Features



- [x] Launch nvim-dap sessions using cortex-debug's `launch.json`

- [x] Support J-Link and OpenOCD

- [ ] Support other GDB servers (#mightwork)

- [x] Globals and Static variable scopes

- [x] Cortex Core Register Viewer (shown under "Registers" scope)

- [ ] Peripheral Register Viewer from SVD file

- [ ] SWO decoding

- [x] SEGGER RTT using OpenOCD/J-Link (currently only "console")

- [x] Raw Memory Viewer

- [ ] Dissassembly viewer

- [ ] RTOS support

- [x] Integration with [nvim-dap-ui](https://github.com/rcarriga/nvim-dap-ui): RTT output

- [x] Download cortex-debug with [mason.nvim](https://github.com/williamboman/mason.nvim)



## Installation



Requirements:



* [cortex-debug](https://github.com/Marus/cortex-debug)

* [node](https://nodejs.org/en/) (to start cortex-debug)

* [appropriate toolchain and debugger](https://github.com/Marus/cortex-debug#installation)



To use this plugin you must first install [cortex-debug](https://github.com/Marus/cortex-debug) VS Code extension.

There are a several options:



* If you're using [mason.nvim](https://github.com/williamboman/mason.nvim) then just `:MasonInstall cortex-debug`

* Install it in VS Code and point `extension_path` to appropriate location.

* Download the extension from [releases](https://github.com/Marus/cortex-debug/releases) and unzip the `.vsix` file (it is just a zip archive)

* [Clone the repo and build from sources](https://github.com/Marus/cortex-debug#how-to-build-from-sources).



Make sure that the `extension_path` (see [Configuration](#configuration)) is correct.

With the default value of `nil` nvim-dap-cortex-debug will try to detect the path from mason.nvim

from the default VS Code extensions path.

Otherwise configure it yourself - it should be the path to the directory in which `dist/debugadapter.js` is located.

In most cases the directory will be named `marus25.cortex-debug-x.x.x` (so there should be a

`marus25.cortex-debug-x.x.x/dist/debugadapter.js` file).



Example using [packer.nvim](https://github.com/wbthomason/packer.nvim):



```lua

use { 'jedrzejboczar/nvim-dap-cortex-debug', requires = 'mfussenegger/nvim-dap' }

```



## Configuration



Call `require('dap-cortex-debug').setup { ... }` in your config.

Available options (with default values):



```lua

require('dap-cortex-debug').setup {

    debug = false,  -- log debug messages

    -- path to cortex-debug extension, supports vim.fn.glob

    -- by default tries to guess: mason.nvim or VSCode extensions

    extension_path = nil,

    lib_extension = nil, -- shared libraries extension, tries auto-detecting, e.g. 'so' on unix

    node_path = 'node', -- path to node.js executable

    dapui_rtt = true, -- register nvim-dap-ui RTT element

    -- make :DapLoadLaunchJSON register cortex-debug for C/C++, set false to disable

    dap_vscode_filetypes = { 'c', 'cpp' },

    rtt = {

        buftype = 'Terminal', -- 'Terminal' or 'BufTerminal' for terminal buffer vs normal buffer

    },

}

```



This will configure nvim-dap adapter (i.e. assign to `dap.adapters['cortex-debug']`) and set up required nvim-dap listeners.



Now define nvim-dap configuration for debugging, the format is the same as for

[cortex-debug](https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md).

You can use a `launch.json` file (see

[nvim-dap launch.json](https://github.com/mfussenegger/nvim-dap/blob/e71da68e59eec1df258acac20dad206366506438/doc/dap.txt#L276)

for details) or define the configuration in Lua.

When writing the configuration in Lua you may write the whole table manually or use one of the helper functions defined in

[dap-cortex-debug.lua](https://github.com/jedrzejboczar/nvim-dap-cortex-debug/blob/master/lua/dap-cortex-debug.lua) which sets

up some default values that get overwritten by the passed table, e.g.



```lua

local dap_cortex_debug = require('dap-cortex-debug')

require('dap').configurations.c = {

    dap_cortex_debug.openocd_config {

        name = 'Example debugging with OpenOCD',

        cwd = '${workspaceFolder}',

        executable = '${workspaceFolder}/build/app',

        configFiles = { '${workspaceFolder}/build/openocd/connect.cfg' },

        gdbTarget = 'localhost:3333',

        rttConfig = dap_cortex_debug.rtt_config(0),

        showDevDebugOutput = false,

    },

}

```






which should be equivalent to the following:



```lua

local dap_cortex_debug = require('dap-cortex-debug')

require('dap').configurations.c = {

    {

        name = 'Example debugging with OpenOCD',

        type = 'cortex-debug',

        request = 'launch',

        servertype = 'openocd',

        serverpath = 'openocd',

        gdbPath = 'arm-none-eabi-gdb',

        toolchainPath = '/usr/bin',

        toolchainPrefix = 'arm-none-eabi',

        runToEntryPoint = 'main',

        swoConfig = { enabled = false },

        showDevDebugOutput = false,

        gdbTarget = 'localhost:3333',

        cwd = '${workspaceFolder}',

        executable = '${workspaceFolder}/build/app',

        configFiles = { '${workspaceFolder}/build/openocd/connect.cfg' },

        rttConfig = {

            address = 'auto',

            decoders = {

                {

                    label = 'RTT:0',

                    port = 0,

                    type = 'console'

                }

            },

            enabled = true

        },

    }

}

```






GDB server output can be seen in `cotex-debug://gdb-server-console` buffer. It is hidden by default,

use `:buffer` or some buffer picker to open it. If RTT logging is enabled, a terminal buffer with

the output will be opened (with the name `cortex-debug://rtt:PORT` where `PORT` is `rttConfig.decoders[i].port`).



### DAP UI



This extension registers custom DAP UI element `rtt` for viewing RTT channel output, e.g.



```lua

require('dapui').setup {

    layouts = {

        {

            position = 'left',

            size = 96,

            elements = {

                { id = 'scopes', size = 0.4 },

                { id = 'rtt', size = 0.6 },

            },

        },

        -- (...)

    },

}

```



## Troubleshooting



To verify common problems run [checkhealth](https://neovim.io/doc/user/pi_health.html#pi_health.txt):

```vim

:checkhealth dap-cortex-debug

```



## Implementation notes



[cortex-debug](https://github.com/Marus/cortex-debug) implements

[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/specification) server,

so it should be possible to use it with [nvim-dap](https://github.com/mfussenegger/nvim-dap)

which is a DAP client. However, there are some extensions to DAP that cortex-debug uses, which have

to be implemented separately to make it work with nvim-dap.



Cortex-debug [is split into two parts](https://github.com/Marus/cortex-debug#how-to-debug): frontend

and backend. Backend is what acts as DAP server and does most of the job, fronted is mostly used for

preparing configuration data and implementing additional functionality like RTT logging or SVD viewer.

For more details see [Cortex Debug: Under the hood](https://github.com/Marus/cortex-debug/wiki/Cortex-Debug:-Under-the-hood).



This plugin tries to reimplement cortex-debug frontend. It:



* takes the launch configuration, fills in missing keys, sets default values and checks config correctness;

  see `adapter.lua` (backend expects a complete configuration - no missing values)

* starts a server to which the output from gdb-server will be sent; this output is displayed in a terminal buffer

  (`cortex-debug://gdb-server-console`)

* if RTT is enabled, the plugin connects via TCP and shows RTT output in a terminal buffer

* hooks into nvim-dap event/command listeners to handle cortex-debug's custom events and fix some existing

  incompatibilities



Implementing a missing cortex-debug feature most likely requires implementing some of the custom events

and displaying the output in Neovim buffers.