Using Breakpoints to Debug Your Code
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. The following document specifies the number of breakpoints available for a specific target MCU.
Hardware Tool Debug Features by Device >
MPLAB® X IDE will automatically use hardware breakpoints by default.
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" 
icon 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.
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 Breakpoint | Activates 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 Breakpoint | Activates 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 Breakpoint | Breaks when a specific device event occurs, such as Watchdog Timeout, Reset, or Sleep Instruction execution. |
| Sequence Breakpoint | Breaks 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. |
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
Set a Line Breakpoint
To set a line breakpoint, click on the line number in the glyph margin of the editor. |  |
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 
. 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.
Clear/Remove a Line Breakpoint
To clear a line breakpoint that you have previously set, click on the line breakpoint icon |  |
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
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.
Enable a Line Breakpoint
Open the Breakpoints window.
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
Enable the breakpoint.
Check the box next to the line breakpoint you want to enable.
Modify a Line Breakpoint's Properties
Open the Breakpoints window.
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Modify the Properties
Change the properties as desired and click OK when done.
For a line breakpoint, the only option available is a Pass Count. There are three options:
| Option | Description |
|---|---|
| Always Break | Breaks every time the program hits the specified line. |
| Break occurs Count instructions after Event | Breaks after the specified line is hit plus the number of instructions specified by Count. |
| Event must occur Count times | Breaks 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.
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).
Set an Address Breakpoint
Open the New Breakpoint Window
Main Menu:
Debug > New Breakpoint…
Keyboard:
Ctrl+Shift+F8
In the Breakpoint Type drop-down box, choose Address.
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.
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.
Click OK.
Determine a Line's Address Before Debug
Main Menu:
Debug > Discrete Debugger Operation > Build for Debugging
Main Menu:
Window > Debugging > Output > Disassembly Listing File
Main Menu:
Edit > Find
Find line of assembly below that performs the desired action. Its address is in the far left column.
Clear/Remove an Address Breakpoint
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Disable an Address Breakpoint
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Enable an Address Breakpoint
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
Enable the breakpoint.
Check the box next to the address breakpoint you want to enable.
Modify an Address Breakpoint's Properties
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
Right-click on the breakpoint whose properties you wish to modify and select Customize from the pop-up menu.
Change the properties as desired and click OK when done.
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.
Set a Data Breakpoint
To set a data breakpoint, open the New Breakpoint Window
Main Menu:
Debug > New Breakpoint…
Keyboard:
Ctrl+Shift+F8
Choose Data Breakpoint Type
In the Breakpoint Type drop-down box, choose Data.
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.
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.
Click OK
Clear/Remove a Data Breakpoint
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Disable a Data Breakpoint
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Enable a Data Breakpoint
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
Enable the breakpoint.
Check the box next to the data breakpoint you want to enable.
Modify a Data Breakpoint's Properties
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
Right click on the breakpoint whose properties you wish to modify and select Customize from the pop-up menu.
Change the properties as desired and click OK when done.
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
Set an Event Breakpoint
Open the New Breakpoint Window
Main Menu:
Debug > New Breakpoint…
Keyboard:
Ctrl+Shift+F8
In the Breakpoint Type drop-down box, choose Event.
Check the box next to the desired events. When any one of these events occur, program execution will be suspended.
Click OK
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
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.
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
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.
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
Enable the breakpoint.
Check the box next to the event breakpoint you want to enable.
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
Right click on the breakpoint whose properties you wish to modify and select Customize from the pop-up menu.
Change the properties as desired and click OK when done.
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.
Set a Sequence Breakpoint
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
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.
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.
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.
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).
Remove a Breakpoint from a Sequence
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Clear/Remove a Sequence Breakpoint
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Disable a Sequence Breakpoint
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Enable a Sequence Breakpoint
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Change the Order of a Sequence's Breakpoints
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
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.
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
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.
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.
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.
Complete Tuple
After adding both an address and a data breakpoint, it is now a functional tuple.
Remove a Breakpoint from a Tuple
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Clear/Remove a Tuple Breakpoint
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Disable a Tuple Breakpoint
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
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.
Enable a Tuple Breakpoint
Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints
Keyboard:
Alt+Shift+5
Enable the breakpoint.
Check the box next to the tuple breakpoint you want to enable.
