Debug Adapter for MPLAB®

Welcome! We are working hard to improve your experience and appreciate your patience and support. Features and functionality will remain in active development. Your feedback is invaluable to us. Please report any bugs or suggestions for enhancements.

✨ Features

The Debug Adapter for MPLAB is responsible for:

Installing the debugger component from the MPLAB® X IDE
Creating debug configurations based on the MPLAB project openend
Managing tool support files

Some of the debug features supported are:

Debug launch
Line and function breakpoints
Pause and Continue
Step in/out/over
Inspecting variables in scope
Inspecting CPU registers
Callstack
Variable watches

🏃‍♀️ Getting started

There are a couple of ways to start a debugging session.

Launch a single file

If you have a file open, and it is part of one or more MPLAB project configurations, just go to the Run menu and select Start Debugging (F5). In the debugger selection, select the MPLAB Debugger option. If the file is part of multiple project configurations, select which configuration you want to launch into. Select the debug tool you want to use, and then the debug session will launch.

Launching a debug session on an open file

Using an automatic debug configuration

If you want to launch a single MPLAB project configuration, go to the Run and Debug window, and select Show all automatic debug configurations. In the dropdown, select the MPLAB Debugger... option. Select the configuration and the workspace that you want to launch. Select the tool to use, and the debug session will start.

Launching a debug session with automatic configuration

Creating a launch.json file

The most flexible and configurable way to start a debug session is to create a launch.json file that describes one or more of your launch configurations.

Go to the Run and Debug tab, and select create a launch.json file. Select the workspace to use, then select the MPLAB Debugger. This will generate one launch configuration for each project configuration. The tool is not selected, but leaving the placeholder will mean that you are asked when you launch.

Select the launch configuration you want and the session will launch.

Launching a debug session with generated launch.json

The launch.json file is meant to be customized. For instance, you can change the tool to use, what interface to connect over, and a lot of other settings. The example below takes the two launch configurations that were created, changes one to use a development kit, and the other to use the MPLAB Simulator. Then both are launched.

Launching a debug session with configured launch.json

Memory view

To access raw memory, a viewer extension is required. We recommend using Memory Inspector from Eclipse CDT Cloud.

Memory references

To access non-linear memory, a concept of memory references is used.

For devices with linear memory, this is just the base address of the memory to view. For devices with non-linear memory, such as AVRs, either use a linearized address or a scoped address. To find the addressing applicable for a specific device, open the Debug Console and run

memory -references

The above command will list the base ranges for the device currently being debugged.

To list available commands, run

help -?

Accessing USB devices under Linux and WSL

The debug agent used for the mplab-core-da debugger uses udev to configure attached USB devices to get the correct permissions for accessing them.

UDEV

If your environment does not have udev installed, make sure that it is. It should be running as a service, so can be checked for instance by querying systemd or whatever service manager that is being used.

$ systemctl status udev
● systemd-udevd.service - Rule-based Manager for Device Events and Files
     Loaded: loaded (/usr/lib/systemd/system/systemd-udevd.service; static)
    Drop-In: /usr/lib/systemd/system/systemd-udevd.service.d
             └─syscall-architecture.conf
     Active: active (running) since Fri 2024-07-19 06:41:41 MST; 1h 4min ago
 Invocation: 6d60678ee58747daa0b4ecdf9dbf97a5
TriggeredBy: ● systemd-udevd-control.socket
             ● systemd-udevd-kernel.socket
       Docs: man:systemd-udevd.service(8)
             man:udev(7)
   Main PID: 688 (systemd-udevd)
     Status: "Processing with 40 children at max"
      Tasks: 1
     Memory: 4.4M
     CGroup: /system.slice/systemd-udevd.service
             └─udev
               └─688 /usr/lib/systemd/systemd-udevd

If udev is not available, check with your package manager how to install it.

Forwarding USB devices to WSL2

Forwarding USB devices are described in Connect USB devices.

Once the device has been forwarded, it should appear under lsusb:

$ lsusb
Bus 001 Device 002: ID 03eb:2141 Atmel Corp. ICE debugger
Bus 001 Device 003: ID 04d8:9015 Microchip Technology, Inc. ICD 4 In-Circuit Debugger

Ensure correct access permission

Once the device appears under lsusb, ensure that udev configured the device correctly by looking at what Bus and Device index the attached USB device has, and check the permissions on that node under /dev/bus/usb/.

$ lsusb
Bus 001 Device 003: ID 04d8:9015 Microchip Technology, Inc. ICD 4 In-Circuit Debugger
$ ls -la /dev/bus/usb/001/003
crw-rw-rw- 1 root root 189, 2 Jul 19 06:52 /dev/bus/usb/001/003

Note the rw-rw-rw part inidicating read-write access.

Running the List connected tools command now should list the connected tools in the Output pane.

06:52:43.558: [info]: Tools connected:
ICD 4     BUR212372451 Microchip Technology Incorporated
Atmel-ICE J41800034538 Atmel Corp.

Requirements

MPLAB Services

🐞 Feedback and issue reporting

Go to mplabfeedback.microchip.com to report issues and suggest enhancements.

📝 License Information

The MPLAB® Extensions for Visual Studio Code are distributed under a non-exclusive software license agreement provided by Microchip Technology Inc. To review the complete terms and conditions governing the use of this software, please consult the "license" file included with this package.