In this lab you will work with a project containing four pre-written C source files. From the main() function you will be provided techniques on how to navigate between the files, how to locate the source code for a given function, how to easily find a variable’s definition, and how to determine the overall flow of a project. The lab concludes with a debugging tip which allows you to determine the sequence of function calls invoked when a break point is reached.
Hardware Tools (Optional)
|Tool|| About|| Purchase|
| Windows|| Linux|| Mac OSX|
Integrated Development Environment
The contents of the following zip file need to be placed in this directory:
| Windows|| Linux|| Mac OSX|
Project and Source Files
Close any open project by right clicking on the project name and selecting “Close”Click the Open Project icon
Browse to and open the project C:\MTT\TLS0101\Lab04.X
Resetting MPLAB® X IDE Windows
To help make the procedures in this page more closely resemble your experience we will close all existing source code and place the window locations to their default location. The easiest way to do this is to Reset the Windows
Windows -> Reset Windows
MPLAB X IDE will disappear for a second or two. When it returns you should notice changes to the graphical user interface setup
Open the Dashboard
The dashboard gives you an overview of the project features and settings. From this window you will be able to verify the processor being used, the simulation/programming tool, and the version of the compiler.
To open the dashboard click the mouse on top of the bar labeled Lab04 - Dashboard
Quite often as you start projects you will need to refer to the datasheet for the particular device being programmed. For a user connected to the internet, the Dashboard screen allows you to access and download the datasheet for the device being used.
Click on the “PDF” image in the left margin of the Dashboard window. When prompted select “HTML Browser Download from Microchip Website”
If you are connected to the internet you can observe your computer browser retrieve the datasheet for the PIC24FJ128GA010 family from www.microchip.com
Close the browser
Next, open the Source Files folder from the Projects Window
Highlight Lab04.c. The Navigation Window populates with the elements found in Lab04.c
From the Navigation Window double click on main()
You should observe the source code for Lab04.c open up and the “blue” bar go to the line of code corresponding to the item selected from the Navigation window
The program is an infinite loop in which data is input, modified, and output. After each output the main loop executes a delay function.
You may notice that the getInput(), the delay(), and the outputData() functions are all located in separate source files.
Highlight the main() function in the source window.
Right click and select Show Call Graph
Once the Call Graph opens observe the graphic representation of the functions called by main()
From this view you should be able to get some idea of how the project calls are linked.
On the left hand side of the Call Graph window you should see a hierarchy of the calls.
Open the graphics to the delay() function by clicking on the plus box (+) next to delay
You will notice the visual call graph change after the delay() function has been expanded.
Open both the getInput(), and outputData() functions from the hierarchy window and notice the changes to the call graph.
Rearranging the Call Graph
Quite often as you open Call Graph the visual becomes complex and somewhat confusing. You can manually re-arrange the visual elements in the Call Graph. To do so, hold the “Left Mouse” button down while moving an object.
Practice moving the objects in the Graph Window to match the graphic to the left. This graph illustrates how the function smallDelay() is called from three separate functions.
Navigating between Files and Functions
From the Call Graph Window double click on the box “main”. This will open up the source code file containing main() in Lab04.c
Observe the blue line over the function header for main()
While holding the Control Key (CTRL) down place the mouse over the call to getInput() in Lab04.c
Observe that a Hyperlink appears as well as a description of the object being highlighted.
With the CTRL button held, place the cursor over the call to getInput(); and left click the mouse
The getInput() function increments a local variable then calls the function smallDelay(). All the functions in this lab modify local variables. We will work with this project attribute later in this lab
Using the hyperlink navigate icon (CTRL+ click) and the “Return” icon navigate to delay(), outputData(), and calculate().
After a brief inspection it should become apparent the function “smallDelay()” is called from three separate functions.
Debugging a "Nested Function"
Quite often in PIC® MCU projects a single function may be called from a number of different functions. The challenge of using nested function calls commonly arises at debug time. If your debug routine were to cause you to reach a breakpoint in a nested routine such as smallDelay() you may need to answer the question “How did I get here?”.
Click on the line number to place a breakpoint on the line of code incrementing the smallDelayVar in delays.c
The project will build and a debug session will start
The simulation will pause at the beginning of main()
We are now ready to simulate.Click the Continue icon and watch the program proceed to the breakpoint in smallDelay().
You will see the code window stop with a green line over the line of code with the breakpoint.
You will also see a comment in the debug console window letting you know where the simulation halted. In this case the code stopped at line 5 in delays.c.
How did we get to the breakpoint? Who called smallDelay() this time? Under what conditions was this function called?
To determine who called a function we will introduce the Call Stack.
Open the call stack by:
When the call stack is first opened the contents may not be updated.To update the call stack window press the Continue icon.
The simulation has proceeded to the second instance of the break in smallDelay().
Observe the output of the call windowEach time a breakpoint is reached the call stack will let you know the active ‘thread’ of function calls. You will observe the function and line of code being executed. At any breakpoint you can see the ‘trail’ of function executions leading to the breakpoint
Click the Continue icon several more times and you will observe a pattern of the calls into smallDelay().
By looking at the output of the Call Stack window you should be able to see the code cycle through getInput(), outputData(), and delay();
OK so we know how we got here, but why did we get here?
What did the functions see that caused the jump to smallDelay() ?
To see what the calling functions see we will open up the Variable window to show us the local variable
Moving the Variables Window
To see what the calling functions see, we will open up the Variables window to show us the local variable
For this example we wish to move the Variables window out of the MPLAB® X frame and onto our desktop. While this example shows how to move the Variable Window any MPLAB® X window can be moved in this manner.
Grab the Variables Window by putting the mouse over the title bar and holding down the left mouse button. While keeping the left mouse button down drag the window completely away from MPLAB® X IDE. Deposit it onto your desktop by releasing the left mouse button.Reset the simulation by clicking the Reset icon.
Ensure the Call Stack window is openPlace the Variable Window where it can be seen
Click the Continue icon
The simulation will stop at the breakpoint within smallDelay(); The Variable window should display the smallDelayVar variable. The call stack will show the functions which called smallDelay().
Note: If the variables don’t appear in the Variables window toggle the upper left side button inside the Variables window.
From within the Call Stack Window double click on the line indicating getInput() called smallDelay()
Observe the Variables window change to display the local variable within the getInput() function. The source window will also show the calling function with a grey bar over the line of code calling the subroutine.
To put the Variables Window back into MPLAB X IDE grab the title of the Variables Window (NOT the large banner but the word “Variables”). While holding the left mouse button drag the window back into MPLAB X IDE. Before letting go of the left mouse button be sure you position the Variables Window where you want it to re-appear when it is opened. MPLAB X IDE will let you know where you are positioning a Window by display an orange outline.
HINT: Use the Window->Reset from step 2 of this lab if you experience trouble resetting the Window location manually