NU32v2: Using the Simulator

From Mech
Jump to navigationJump to search

Introduction to the MPLAB Simulator

The MPLAB Simulator is a debugging tool that allows you to test code without programming it onto a PIC32. Simple debugging, such as watching the values of variables or registers, can be performed, as well as advanced features, such as simulating inputs from a UART. This tutorial will cover the basics of setting up the MPLAB simulator and how to run code inside a debugger using a slightly modified invest.c program that we saw in class.

Setting up MPLAB SIM

To run the sample code in the simulator,

  1. Download and unzip MPLAB_Invest_Example.zip
    1. verify that there are 5 files in the zip folder: invest.c, pic32_additions.c, pic32_additions.h, invest.mcp, and input.txt
  2. Launch the invest MPLAB project, invest.mcp
  3. Go to Debugger->Select Tool->MPLAB SIM
  4. Go to Debugger->Settings... and click on the "Uart1 IO" tab
  5. In the "Uart1 IO" tab
    1. click on "Enable Uart1 IO" checkbox
    2. in the "Input File" field, click the "Browse" button and add input.txt
    3. uncheck "Rewind Input"
    4. click on the "Window" radio button
    5. hit "OK" to change the settings and close the window
  6. Go to Project->Build Options...->Project, select the "MPLAB PIC32 Linker" tab and
    1. enter a heap size, 4096 bytes works for this example
    2. hit "OK" to change the settings and close the window
  7. Compile the program (you can press F10 or go to Project->Make)
  8. Run the debugger (press F9 or go to Debugger->Run)
  9. If you see text similar to what you saw in the first day of class scrolling by in the Output window, then everything is working correctly. Next, we'll briefly go over a few basic features of the debugger, but let's reset the debugger first.
  10. Halt the debugger by pressing F5 or Debugger->Halt
  11. Reset the simulation/microcontroller by pressing F6 or Debugger->Reset->Processor Reset

Working with the Debugger

The MPLAB debugger has several useful tools and commands. In this section, we will cover the following:

  • setting breakpoints
  • basic debugging commands: Halt, Reset, Step Into, Step Over, and Run
  • understanding the Locals window.

The Basic Debug Commands

The debug commands do the following:

Halt
stops the program at the next line of code to be executed
Reset
resets the PIC to its default state and starts the program from the very beginning
Step Into
executes the next valid C expression in your code and then halts the program
Step Over
If the next expression is a function call, then it executes that function and then halts the program. Otherwise, for non-function calls, this is equivalent to Step Into. IMPORTANT, if you don't have the source code for a function you should STEP OVER it. Not doing so can lead to MPLAB not responding to your commands.
Run
executes the program from the last executed expression until a breakpoint is encountered or Halt is selected

There are several ways to use the debugging commands (see Table 1)

Table 1: How to Access the Basic Debugging Commands
Halt Reset Step Into Step Over Run
Keyboard F5 F6 F7 F8 F9
Menubar Debugger->Halt Debugger->Reset->Processor Reset Debugger->Step Into Debugger->Step Over Debugger->Run
Debugger Toolbar TbDbgHalt.png TbDbgReset.png TbDbgStepInto.png TbDbgStepOver.png TbDbgRun.png


The walkthrough will use the keyboard shortcuts, but the other methods can be substituted for the shortcuts. Before we begin, make sure that invest.c is opened, line numbers are visible, and the debugger is not running and has been reset.

Debugging invest.c

  1. Set a breakpoint at line 104 in invest.c
  2. Press F9 to start the debugger
  3. Press F8 to Step Over the initUart1() function.
    • Notice how the debugger passed over this function. The code inside of it still executed! Alternatively, because we have access to the source code, we could have chosen to Step Into the function to see it in action. Instead, we step over it, because it contains code that we won't cover until later in the course.
    • The debugger has advanced the program to the next instruction in our main function (as denoted by the green arrow). The next instruction is a function call to getUserInput(...).
  4. Press F7 to Step Into getUserInput(...).
  5. Go to View->Locals, to bring up the Locals window.
  6. Press F8 once to advance the program
  7. In the Locals window, change the display of valid from hexadecimal to decimal by
  8. Keep pressing F8 until you hit line 145
    • the Locals window now display new values for valid and input. The new value for valid should equal 1 or "true" due to the assignment in line 142
    • a nice feature about a debugger is that you can change the value of any variable or array in real-time. The Locals window is one window where this is possible.
  9. Under the column "Value", double-click the field corresponding to the value of valid
  10. Change the value of valid from 1 to 782 and then press your enter key.
    • this won't affect the normal execution of the program because the value is still true
  11. Set another breakpoint in calculateGrowth(...) at line 175
  12. Press F9 to Run
  13. Press F9 again
    • the program has finished executing
  14. Press F5 to Halt the program
    • typically, this would stop at the next line of code to be executed, but we've reached the end of the program
  15. Press F6 to reset the program and start execution from the beginning of the program

At this point you've covered the basics of working with a debugger. Feel free to practice what you've learned by running through the program again. You could, for example, change the value of i in the calculateGrowth(...) for-loop while the loop is running, set extra breakpoints, etc.

If you want to delve deeper into the debugger or simulator consult the MPLAB help files. Further information about the debugger can be found in the "MPLAB IDE Features/Debug Features" section of the "MPLAB IDE" .chm help file under Help->Topics.... The MPLAB SIM .chm help file also contains interesting information about the simulator, like simulating other peripherals and timing your code.

Troubleshooting MPLAB SIM

MPLAB SIM isn't responding to any of my commands
MPLAB SIM isn't perfect and if it doesn't respond to a command after a period of time, it may be caught in an infinite loop. You may have to restart the simulator by selecting Debugger->Select Tool->None and then Debugger->Select Tool->MPLAB SIM. If that doesn't work exit MPLAB and start again.