Using Breakpoints to Debug Your Code

Last modified by Microchip on 2025/08/27 12:13

Overview

A breakpoint is a mechanism for pausing the application during a debug session. When the application is paused, you have the opportunity to view and modify data variables, non-volatile memory data and device registers. 

Breakpoints fall into two broad categories: hardware breakpoints and software breakpoints. At the Integrated Development Environment (IDE) level, both types will appear to work the same way but there are differences in their implementations behind the scenes.

Hardware Breakpoints

Hardware breakpoints are versatile in their ability to suspend program execution. These breakpoints are limited in number by the target microcontroller's hardware. To determine the number of breakpoints available for a specific target MCU, in MPLAB X IDE:

  1. Select Help > Release Notes.
  2. Under Debug Features Support click on Hardware Tool Debug Features by Device. A table will pop open.
  3. In the table, search for your device to determine the number of breakpoints.

Software Breakpoints

As the name implies, software breakpoints are implemented in software and are therefore not limited by the hardware. You can use as many as you need, but they only support breaking on program memory events using Line and Address breakpoints.

To use software breakpoints, they must first be enabled. Software breakpoints are only supported by debuggers.

Breakpoints Window

The Breakpoints Window displays all breakpoints that have been set in all open MPLAB X IDE projects. From this window, you can create a new breakpoint by clicking on the "New Breakpoint" line.pngicon in the left sidebar. You can also modify the properties of an existing breakpoint by right-clicking on the breakpoint and selecting the desired option from the popup menu.

Breakpoints Window

Breakpoint Type Definitions

Each of the Integrated Development Environment's (IDE) six breakpoint types will pause the application when a certain set of criteria are met. MPLAB X IDE supports the following breakpoint types:

Line Breakpoint Suspends program execution when it reaches a specific line in the source code. When a line breakpoint is set, its address is compared to the program counter during each instruction cycle. If a match occurs, the program is suspended and control is turned over to the debugger.
Address BreakpointActivates when a specific address of program memory is executed.  An address breakpoint differs from a line breakpoint when a single line of source code requires multiple lines of machine language instructions to execute. Address breakpoints allow the application to be paused on specific assembly language instructions. 
Data BreakpointActivates when a specific data memory (RAM) is accessed under certain criteria.  Data breakpoints can be triggered when an address is written to or read from.  Data breakpoints can also be set to activate when a specific value is read from or written to data RAM.
Event BreakpointBreaks when a specific device event occurs, such as Watchdog Timeout, Reset, or Sleep Instruction execution.
Sequence BreakpointBreaks when two separate breakpoint criteria occur in an ordered sequence.
Tuple Breakpoint Also known as "ANDed Breakpoint", breaks when a specified data breakpoint and a specific address breakpoint are both set. Tuple breakpoints are useful in determining if a certain value was read by or written by a specific application function.

Back to Top

Line Breakpoint

Line breakpoints can be used for the following:

  • View machine state at a particular point in the program's execution
  • Determine if a line of code is ever reached
  • Determine whether some software or hardware event has occurred
  • Check program logic or calculation results
  • Inject "what if" test values into a program

A line breakpoint differs from an address breakpoint in that a line breakpoint works at the source level while an address breakpoint works at the machine level.

Back to Top

Set a Line Breakpoint

To set a line breakpoint, click on the line number in the glyph margin of the editor.

If it is a valid location for a breakpoint (i.e. there is machine code associated with the line of source code) then a red, square icon line.png will replace the line number and the entire line of code will be highlighted with the same color as the square.

Set a line breakpoint

Sometimes you may not be able to set a breakpoint on a particular line. When this is the case, no breakpoint will appear, or it may appear with the broken breakpoint icon broken-line.png. There are a number of potential causes for this situation, including:

  • Compiler optimization is enabled above 0, which may result in code being rearranged, procedurally abstracted, or in some cases optimized out of existence. If there is no machine code below the C code, there is no place to set a breakpoint.
  • Some elements of C don't directly translate to machine code where they occur in the source code as can sometimes occur with an opening brace '{', compiler directives, and sometimes even looping keywords like while.

If you encounter this problem, in some cases it may help to insert a Nop(); (no operation) macro where you want a breakpoint, since this directly translates to a nop instruction in the machine code which is a perfectly valid place to set a breakpoint.

Back to Top

Clear/Remove a Line Breakpoint

To clear a line breakpoint that you have previously set, click on the line breakpoint icon line.pngin the glyph margin of the editor and it will be removed, revealing the line's number. Your program will no longer halt at this location.

Clear a breakpoint

Back to Top

Disable a Line Breakpoint

You can disable line breakpoints that you have set so that they will be remembered by MPLAB® X IDE but will no longer affect the program's execution. They can be re-enabled when you need them again.

Open the Breakpoints Window

Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open the Breakpoints windowClick image to enlarge.

Back to Top


Disable the Breakpoint

Uncheck the box next to the line breakpoint you want to disable. The IDE will remember its settings without affecting program execution.

Disable the breakpointClick image to enlarge.

Back to Top

Enable a Line Breakpoint

Open the Breakpoints Window

Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Back to Top


Enable the Breakpoint

Check the box next to the line breakpoint you want to enable.

Enable the breakpointClick image to enlarge.

Back to Top

Modify a Line Breakpoint's Properties

Open the Breakpoints Window

Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open the Breakpoints windowClick image to enlarge.

Back to Top


Open the Breakpoint's Properties Window

Right click on the breakpoint whose properties you wish to modify and select Customize from the pop-up menu.

Open the Breakpoint's Properties WindowClick image to enlarge.

Back to Top


Modify the Properties

Change the properties as desired and click OK when done.

Modify the PropertiesClick image to enlarge.

For a line breakpoint, the only option available is a Pass Count. There are three options:

OptionDescription
Always BreakBreaks every time the program hits the specified line.
Break occurs Count instructions after EventBreaks after the specified line is hit plus the number of instructions specified by Count.
Event must occur Count timesBreaks after the line has been hit the number of times specified by Count.

Always Break is the default condition. The other two options both accept one parameter called Count, which causes the break to occur later than the event that triggered it. For example, if you set the condition to 'Event must occur Count times' and specify a value of 5 for Count, then your program would have to hit that line 5 times before it would break.

Back to Top

Address Breakpoint

Address breakpoints can be used for the following:

  • View machine state when specific instruction is executed (assembly element of a line of C code).
  • View data read from or written to program memory by table read/write instructions.
  • Determine if a program memory location is ever reached (check program pointers).

Back to Top

Set an Address Breakpoint

Open the New Breakpoint Window

Main Menu:
Debug > New Breakpoint…
Keyboard:
Ctrl+Shift+F8

Open the New Breakpoint WindowClick image to enlarge.

Back to Top


Choose Address Breakpoint Type
In the Breakpoint Type drop-down box, choose Address.

Choose Address Breakpoint TypeClick image to enlarge.

Back to Top


Configure Breakpoint Settings

Enter a valid memory address in the Address box.

Next, choose the Breaks on condition. In most cases, you will want to use the default, Program Memory Execution. The other options are for triggering on table reads and table writes which make use of specific PIC® microcontroller or dsPIC® digital signal controller instructions. These settings are only useful if you explicitly use these table read/write instructions through inline assembly or assembly language files.

Configure Breakpoint SettingsClick image to enlarge.

Back to Top


Choose Pass Count Condition
The default Pass Count is Always Break where the program will halt each time the breakpoint's conditions are met.

Break occurs Count instructions after Event will halt the program by a specified number of instructions/instruction cycles after the breakpoint's conditions are met.

Event must occur Count times will halt the program after the breakpoint's conditions have been met a specified number of times.

Choose Pass Count ConditionClick image to enlarge.

Back to Top


Close Window
Click OK.

Back to Top

Determine a Line's Address Before Debug

Build for Debug
Main Menu:
Debug > Discrete Debugger Operation > Build for Debugging

Build for DebugClick image to enlarge.

Back to Top


Open the Disassembly Listing File
Main Menu:
Window > Debugging > Output > Disassembly Listing File

Open the Disassembly Listing FileClick image to enlarge.

Back to Top


Search for a Line of C Code
Main Menu:
Edit > Find

Search for a Line of C CodeClick image to enlarge.

Back to Top


Find Address
Find line of assembly below that performs the desired action. Its address is in the far left column.

Find AddressClick image to enlarge.

Back to Top

Clear/Remove an Address Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Delete the Breakpoint
Right click on the breakpoint you want to clear and select Delete from the popup menu.

If you want to remove all breakpoints, right click anywhere in the Breakpoints window and select Delete All from the popup menu.

Delete the BreakpointClick image to enlarge.

Back to Top

Disable an Address Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Disable the Breakpoint

Uncheck the box next to the address breakpoint you want to disable. The IDE will remember its settings without affecting program execution.

Disable the BreakpointClick image to enlarge.

Back to Top

Enable an Address Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Enable the Breakpoint

Check the box next to the address breakpoint you want to enable.

Enable the BreakpointClick image to enlarge.

Back to Top

Modify an Address Breakpoint's Properties

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Open the Breakpoints Properties Window
Right-click on the breakpoint whose properties you wish to modify and select Customize from the pop-up menu.

Open the Breakpoints Properties WindowClick image to enlarge.

Back to Top


Modify the Properties
Change the properties as desired and click OK when done.

Modify the PropertiesClick image to enlarge.

Back to Top

Data Breakpoint

Data breakpoints can be used for the following:

  • View the machine state when a variable is accessed (read or written).
  • View the machine state when a specific value is read or written to a variable (catch incorrect data).
  • Determine if a data memory location is ever accessed.

Although some Arm® Cortex® devices support value matches for data breakpoints, MPLAB X IDE does not support this functionality. Only simple access based breakpoints are supported.

Back to Top

Set a Data Breakpoint

To set a data breakpoint, Open the New Breakpoint Window

Main Menu:
Debug > New Breakpoint…
Keyboard:
Ctrl+Shift+F8

Open the New Breakpoint WindowClick image to enlarge.

Back to Top


Choose Data Breakpoint Type

In the Breakpoint Type drop-down box, choose Data.

Choose Data Breakpoint TypeClick image to enlarge.

Back to Top


Configure Breakpoint Settings
Choose a data memory location by its Symbol or its Address. If choosing by symbol, click on the Symbols button.

If you clicked the Symbols button:

To set a breakpoint on a global variable, select the Global Symbols radio button, then choose the variable name from the list.

To set a breakpoint on a Special Function Register (SFR), select the SFR radio button, then choose the register name from the list.

Click OK when done.

Configure Breakpoint SettingsClick image to enlarge.

Back to Top


Choose Pass Count Condition
The default Pass Count is Always Break where the program will halt each time the breakpoint's conditions are met.

Break occurs Count instructions after Event will halt the program by a specified number of instructions/instruction cycles after the breakpoint's conditions are met.

Event must occur Count times will halt the program after the breakpoint's conditions have been met a specified number of times.

Choose Pass Count ConditionClick image to enlarge.

Back to Top


Close Window
Click OK

Back to Top

Clear/Remove a Data Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Delete the Breakpoint
Right-click on the breakpoint you want to clear and select Delete from the popup menu.

If you want to remove all breakpoints, right-click anywhere in the Breakpoints window and select Delete All from the popup menu.

Delete the BreakpointClick image to enlarge.

Back to Top

Disable a Data Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Disable the Breakpoint

Uncheck the box next to the data breakpoint you want to disable. The IDE will remember its settings without affecting program execution.

Disable the BreakpointClick image to enlarge.

Back to Top

Enable a Data Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Enable the Breakpoint

Check the box next to the data breakpoint you want to enable.

Enable the BreakpointClick image to enlarge.

Back to Top

Modify a Data Breakpoint's Properties

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Open the Breakpoint's Properties Window
Right click on the breakpoint whose properties you wish to modify and select Customize from the pop-up menu.

Open Breakpoints WindowClick image to enlarge.

Back to Top


Modify the Properties
Change the properties as desired and click OK when done.

Modify the PropertiesClick image to enlarge.

Back to Top

Event Breakpoint

Event breakpoints can be used for the following:

  • View machine state after stack overflow/underflow
  • View machine state after watchdog timeout
  • Catch resets

Back to Top

Set an Event Breakpoint

Open the New Breakpoint Window

Main Menu:
Debug > New Breakpoint…

Keyboard:
Ctrl+Shift+F8

Open the New Breakpoint WindowClick image to enlarge.

Back to Top


Choose Data Breakpoint Type
In the Breakpoint Type drop-down box, choose Event.

Choose Data Breakpoint TypeClick image to enlarge.

Back to Top


Configure Breakpoint Settings
Check the box next to the desired events. When any one of these events occur, program execution will be suspended.

Configure Breakpoint SettingsClick image to enlarge.

Back to Top


Close Window
Click OK

Back to Top

Clear/Remove an Event Breakpoint

To clear/remove an event breakpoint that you have previously set:

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Delete the Breakpoint
Right click on the breakpoint you want to clear and select Delete from the popup menu.

If you want to remove all breakpoints, right click anywhere in the Breakpoints window and select Delete All from the popup menu.

Delete the BreakpointClick image to enlarge.

Back to Top

Disable an Event Breakpoint

You can disable event breakpoints that you have set so that they will be remembered by MPLAB X IDE, but will no longer affect the program's execution. They can be re-enabled when you need them again.

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Disable the Breakpoint

Uncheck the box next to the event breakpoint you want to disable. The IDE will remember its settings, but it will not affect program execution.

Disable the BreakpointClick image to enlarge.

Back to Top

Enable an Event Breakpoint

You can enable event breakpoints that you have previously set and then disabled so that they will once again affect the program's execution.

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Enable the Breakpoint

Check the box next to the event breakpoint you want to enable.

Enable the BreakpointClick image to enlarge.

Back to Top

Modify an Event Breakpoint's Properties

To modify the properties of a event breakpoint that you have previously set:

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Open the Breakpoints Properties Window
Right-click on the breakpoint whose properties you wish to modify and select Customize from the pop-up menu.

Open the Breakpoints Properties WindowClick image to enlarge.

Back to Top


Modify the Properties
Change the properties as desired and click OK when done.

Modify the PropertiesClick image to enlarge.

Back to Top

Sequence Breakpoint

Sequence breakpoints can be used to examine a machine state after a specific set of events have occurred in a specific order. For example, suspend program execution (i.e., break) after it has first passed line 25 ten times, then a value of 6 is written to the variable count, and finally, a sleep instruction is executed.

Back to Top

Set a Sequence Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Add First Breakpoint to Sequence

Right-click on the first breakpoint you want to add to a sequence and select Complex Breakpoint > Add to New Sequence… from the pop-up menu.

Add First Breakpoint to SequenceClick image to enlarge.

Back to Top


Name the Sequence

Give the sequence a name. This can be anything you want and is simply used to identify this sequence in the breakpoints window.

Name the SequenceClick image to enlarge.

Back to Top


Partially Complete Sequence

At this point, you have a sequence that contains one breakpoint. While it will work, it isn't truly a sequence until there are two or more breakpoints within the sequence.

Partially Complete SequenceClick image to enlarge.

Back to Top


Add Next Breakpoint to Sequence

Right click on the next breakpoint you want to add to the sequence. Select Complex Breakpoint > Move to MySequence… where MySequence is the name you provided in step 3.

Add Next Breakpoint to SequenceClick image to enlarge.

Back to Top


Complete Sequence
After adding a second breakpoint (of any simple type), it is now a functional sequence. However, you can repeat step 5 as many times as needed to insert additional breakpoints to the sequence.

Once you have added all the desired breakpoints to the sequence, you may need to change their order (see instructions below).

Complete SequenceClick image to enlarge.

Back to Top

Remove a Breakpoint from a Sequence

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Remove the Breakpoint

Right-click on the breakpoint you want to remove from the sequence and select Complex Breakpoint > Remove from MySequence from the pop-up menu, where MySequence is the name of the sequence containing the breakpoint you are removing.

Remove the BreakpointClick image to enlarge.

Back to Top

Clear/Remove a Sequence Breakpoint

Open Breakpoints Window

Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Delete the Breakpoint

Right-click on the breakpoint you want to clear and select Delete from the popup menu.

If you want to remove all breakpoints, right-click anywhere in the Breakpoints window and select Delete All from the popup menu.

Delete the BreakpointClick image to enlarge.

Back to Top

Disable a Sequence Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Disable the Breakpoint

Uncheck the box next to the sequence breakpoint you want to disable. The IDE will remember its settings without affecting program execution.

You can also disable just an individual breakpoint within the sequence by unchecking its box while leaving the sequence's box and all its other children's boxes checked.

Disable the BreakpointClick image to enlarge.

Back to Top

Enable a Sequence Breakpoint

Open Breakpoints Window

Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Enable the Breakpoint

Check the box next to the sequence breakpoint you want to enable.

If you only disabled individual breakpoints within the sequence, check their boxes to enable them.

Enable the BreakpointClick image to enlarge.

Back to Top

Change the Order of a Sequence's Breakpoints

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Move Breakpoint Up or Down

Right-click on a breakpoint within the sequence and select Complex Breakpoint > Move Up or Complex Breakpoint > Move Down from the pop-up menu.

Move Breakpoint Up or DownClick image to enlarge.

Back to Top

Tuple Breakpoint

Tuple breakpoints can be used to isolate a specific instance of a read or write to a register, when that register might be read or written from multiple program locations.

Tuple breakpoint example

Back to Top

Set a Tuple Breakpoint

To set a tuple breakpoint you must first have an address breakpoint and a data breakpoint set, then:

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Add Address Breakpoint to Tuple

Right-click on the address breakpoint you want to add to a tuple and select Complex Breakpoint > Add to New Tuple… from the pop-up menu.

Add Address Breakpoint to TupleClick image to enlarge.

Back to Top


Name the Tuple

Give the tuple a name. This can be anything you want and is simply used to identify this tuple in the breakpoints window.

Tuple Name WindowClick image to enlarge.

Back to Top


Add Data Breakpoint to Tuple

Right-click on the data breakpoint you want to add to the tuple. Select Complex Breakpoint > Move to MyTuple where MyTuple is the name you provided in step 3.

Name the TupleClick image to enlarge.

Back to Top


Complete Tuple

After adding both an address and a data breakpoint, it is now a functional tuple.

Complete TupleClick image to enlarge.

Back to Top

Remove a Breakpoint from a Tuple

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Remove the Breakpoint

Right-click on the breakpoint you want to remove from the tuple and select Complex Breakpoint > Remove from MyTuple from the pop-up menu, where MyTuple is the name of the sequence containing the breakpoint you are removing.

Remove the BreakpointClick image to enlarge.

Back to Top

Clear/Remove a Tuple Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Delete the Breakpoint

Right-click on the breakpoint you want to clear and select Delete from the popup menu.

If you want to remove all breakpoints, right-click anywhere in the Breakpoints window and select Delete All from the popup menu.

Delete the BreakpointClick image to enlarge.

Back to Top

Disable a Tuple Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Disable the Breakpoint

Uncheck the box next to the tuple breakpoint you want to disable. The IDE will remember its settings without affecting program execution.

Disable the BreakpointClick image to enlarge.

Back to Top

Enable a Tuple Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Open Breakpoints WindowClick image to enlarge.

Back to Top


Enable the Breakpoint

Check the box next to the tuple breakpoint you want to enable.

Enable the BreakpointClick image to enlarge.

Back to Top

Learn More

Back to Top