Add information for debugging ZMK to the docs.

[BrainWart]

This issue is holding all information about setting up debugging related to ZMK.

The focus for debugging seems to be towards VS Code however, this should not be taken as the rule. Other debugging setups are welcome.

---

I've created a launch.json file the includes different tests in it to allow the developer to pick the test they want to debug. I haven't had the chance to debug the file or any settings, however. Maybe a file could be created within the docs to help people set something like this up?

https://gist.github.com/BrainWart/5a300bb150ba2289448e2027a5dd6578

To get the list of tests on Windows with PowerShell, I used get-childitem . -recurse -filter *.snapshot | select-object FullName > .\tests.txt within the tests folder and then manually cleaned up the items from there.

@mcrosson

[BrainWart]

I found the plugin vsCodeFilePicker. Seems like it would get close to what we need. Maybe create a PR for their plugin to allow us to drop some directories from the relative path.

    "inputs": [
      {
        "id": "testName",
        "type": "command",
        "command": "filePicker.pick",
        "args": {
            "masks": "app/tests/**/keycode_events.snapshot",
            "display": "dirRelativePath",
            "output": "dirRelativePath"
        }
      }
    ]

[mcrosson]

no usb passthrough with docker desktop

https://docs.docker.com/desktop/faqs/

[schengnz]

Native-Posix/Integration Test interactive debugging with VS Code

• Install GDB -- If you are using container mode, from the VS Code terminal, follow Debian instructions http://www.gdbtutorial.com/tutorial/how-install-gdb
• VS Code: No extra extensions necessary -- Microsoft C/C++ extension should be pre-installed
• From VS Code, follow @Okke instructions to create a new launch profile. You would need to change the program path

  {
  "version": "0.2.0",
  "configurations": [
      {
          "name": "build/tests/combo/press-release-long-combo/zephyr/zmk.exe",
          "type": "cppdbg",
          "request": "launch",
          "program": "/home/okke/dev/zmk/app/build/tests/combo/press-release-long-combo/zephyr/zmk.exe",
          "args": [],
          "stopAtEntry": false,
          "cwd": "${workspaceFolder}",
          "environment": [],
          "externalConsole": false,
          "MIMode": "gdb",
          "setupCommands": [
              {
                  "description": "Enable pretty-printing for gdb",
                  "text": "-enable-pretty-printing",
                  "ignoreFailures": true
              }
          ]
      }
  ],
  }

[schengnz]

I tried modifying launch.json to use file-picker extension as per BrainWart's suggestion, but that does not work. So for now we would have to modify launch.json manually for each target integration test.

[schengnz]

joelspadin (Rinh)Today at 12:04 PM On the topic of debugging actual hardware with VS Code, this is a config that worked for me with an nRF dev kit's built-in j-link (no cortex debug extension needed):

{
    "configurations": [
        {
            "name": "whatever", 
            "type": "cppdbg", 
            "request": "launch", 
            "program": "${workspaceFolder}\\build\\...\\thebinaryfile", 
            "cwd": "${workspaceFolder}\\build\\...", 
            "targetArchitecture": "arm", 
            "MIMode": "gdb", 
            "miDebuggerPath": "C:\\path\\to\\your\\toolchain's\\arm-none-eabi-gdb.exe", 
            "setupCommands": [
                {
                    "text": "-enable-pretty-printing", 
                    "description": "Enable pretty printing for gdb", 
                    "ignoreFailures": true
                }
            ],
            "serverStarted": "Connected to target", 
            "debugServerArgs": "-device <PUT_THE_NRF_CHIP_HERE> -endian little -if SWD -localhostonly -select USB -speed 4000 -noir", 
            "debugServerPath": "C:\\Program Files (x86)\\SEGGER\\JLink_V640\\JLinkGDBServerCL.exe", 
            "miDebuggerServerAddress": "localhost:2331"
        }
    ]
}

(Requires Microsoft's C++ extension and the Segger J-Link GDB server.)

[schengnz]

If we cannot solve the out-of-the-box device debugging with the container-based setup, we should improve the documentation for native Windows+WSL2 and native Linux setup, to cover interactive debugging on device & interactive debugging for integration tests.

[schengnz]

Turns out WSL2 does not support USB pass through either. https://github.com/microsoft/WSL/issues/5158

[schengnz]

One very hacky solution would be for Windows-based people to run two tool chains:

• For integration test/native_posix use @KemoNine 's container approach - this is known to work
• For on-device debugging use native Windows toolchain a la @joelspadin (Rinh) - this is known to work Best of the two worlds, by having to embrace both worlds.

Another approach would be dual-boot Windows/Linux :D

[joelspadin]

Another option is if we can run JLinkGDBServerCL.exe outside the container and forward the port it uses into the container, then it should be possible to get GDB inside the container to connect to the native server.

Setting that up may not be trivial, but if we can find a consistent way to do it, then we can also write a VS Code extension to automate the process that runs natively to launch the GDB server. If we need to do anything more complex than just running an extension command, a second extension running in the container that communicates with the native one may also be needed.

[joelspadin]

Some extra info for the GDB launch config in https://github.com/zmkfirmware/zmk/issues/714#issuecomment-789293302: for the program property, it looks like you want to point it at app/<build-dir>/zephyr/zmk.elf.

You can also run JLinkGDBServer.exe, set it up for your chip using a GUI, and then it will list the matching command line arguments. Paste those into debugServerArgs.