Using Breakpoints to Debug Your Code

Last modified by Microchip on 2023/11/10 11:04

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.

Back to top

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.

Back to top

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

Back to top

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

Menu-Debugging-Breakpoints
Click image to enlarge.

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.

Line-Disable2.png
Click image to enlarge.

Back to top


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.

Line-Enable2.png
Click 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

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Line-Modify2.png
Click image to enlarge.

Modify the Properties

Change the properties as desired and click OK when done.

Line-Modify3.png
Click 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

Menu-NewBreakpoint.png
Click image to enlarge.

Choose Address Breakpoint Type
In the Breakpoint Type drop-down box, choose Address.
Address-Set2.png
Click image to enlarge.

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.

Address-Set3.png
Click image to enlarge.

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.
Address-Set4.png
Click image to enlarge.

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
BuildForDebug.png
Click image to enlarge.

Open the Disassembly Listing File
Main Menu:
Window > Debugging > Output > Disassembly Listing File
DisassemblyListingF.png
Click image to enlarge.

Search for a Line of C Code
Main Menu:
Edit > Find
Find.png
Click image to enlarge.

Find Address
Find line of assembly below that performs the desired action. Its address is in the far left column.
Address.png
Click image to enlarge.

Back to top


Clear/Remove an Address Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.
Address-Clear2.png
Click image to enlarge.

Back to top


Disable an Address Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5
Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Address-Disable2.png
Click image to enlarge.

Back to top


Enable an Address Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5
Menu-Debugging-Breakpoints.png
Click image to enlarge.

Enable the breakpoint.

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

Address-Enable2.png
Click image to enlarge.

Back to top


Modify an Address Breakpoint's Properties

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5
Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.
Address-Modify2.png
Click image to enlarge.

Modify the Properties
Change the properties as desired and click OK when done.
Address-Modify3.png
Click 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.

Set a Data Breakpoint

To set a data breakpoint, open the New Breakpoint Window

Main Menu:
Debug > New Breakpoint…

Keyboard:
Ctrl+Shift+F8

Menu-NewBreakpoint.png
Click image to enlarge.

Choose Data Breakpoint Type

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

Data-Set2.png
Click image to enlarge.

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.

Data-Set3.png
Click image to enlarge.

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.
Data-Set4.png
Click image to enlarge.

Close Window
Click OK

Back to top


Clear/Remove a Data Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5
Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.
Data-Clear2.png
Click image to enlarge.

Back to top


Disable a Data Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5
Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Data-Disable2.png
Click image to enlarge.

Back to top


Enable a Data Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5
Menu-Debugging-Breakpoints.png
Click image to enlarge.

Enable the breakpoint.

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

Data-Enable2.png
Click image to enlarge.

Back to top


Modify a Data Breakpoint's Properties

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5
Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.
Data-Modify2.png
Click image to enlarge.

Modify the Properties
Change the properties as desired and click OK when done.
Data-Modify3.png
Click 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

Set an Event Breakpoint

Open the New Breakpoint Window

Main Menu:
Debug > New Breakpoint…

Keyboard:
Ctrl+Shift+F8

Menu-NewBreakpoint.png
Click image to enlarge.

Choose Data Breakpoint Type
In the Breakpoint Type drop-down box, choose Event.
Event-Set2.png
Click image to enlarge.

Configure Breakpoint Settings
Check the box next to the desired events. When any one of these events occur, program execution will be suspended.
Event-Set3.png
Click image to enlarge.

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

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.
Event-Clear2.png
Click 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

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Event-Disable2.png
Click 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

Menu-Debugging-Breakpoints.png
Click image to enlarge.

Enable the breakpoint.

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

Event-Enable2.png
Click 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

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.
Event-Modify2.png
Click image to enlarge.

Modify the Properties
Change the properties as desired and click OK when done.
Event-Modify3.png
Click 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.

Set a Sequence Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Sequence-Set2.png
Click image to enlarge.

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.

Sequence-Set3.png
Click image to enlarge.

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.

Sequence-Set4.png
Click image to enlarge.

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.

Sequence-Set5.png
Click image to enlarge.

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).
Sequence-Set6.png
Click image to enlarge.

Back to top


Remove a Breakpoint from a Sequence

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Sequence-Remove2.png
Click image to enlarge.

Back to top


Clear/Remove a Sequence Breakpoint

Open Breakpoints Window

Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Sequence-Clear2.png
Click image to enlarge.

Back to top


Disable a Sequence Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Sequence-Disable2.png
Click image to enlarge.

Back to top


Enable a Sequence Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Sequence-Enable2.png
Click 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

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Sequence-Change2.png
Click 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

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Tuple-Set2.png
Click image to enlarge.

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-Set3.png
Click image to enlarge.

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.

Tuple-Set4.png
Click image to enlarge.

Complete Tuple

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

Tuple-Set5.png
Click image to enlarge.

Back to top


Remove a Breakpoint from a Tuple

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Tuple-Remove2.png
Click image to enlarge.

Back to top


Clear/Remove a Tuple Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Tuple-Clear2.png
Click image to enlarge.

Back to top


Disable a Tuple Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

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.

Tuple-Disable2.png
Click image to enlarge.

Back to top


Enable a Tuple Breakpoint

Open Breakpoints Window
Main Menu:
Window > Debugging > Breakpoints

Keyboard:
Alt+Shift+5

Menu-Debugging-Breakpoints.png
Click image to enlarge.

Enable the breakpoint.

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

Tuple-Enable2.png
Click image to enlarge.

Learn More

Back to top