Lab 4 - Navigating Projects

 Objective

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.

 Materials

Hardware Tools (Optional)

Tool About Purchase
Explorer16-50px.png
Explorer 16
Development Board
ICD3-50px.png
MPLAB® ICD 3
In-Circuit Debugger

Software Tools

Tool About Installers
Installation
Instructions
Windows Linux Mac OSX
MPLAB® X
Integrated Development Environment
MPLAB® XC16
C Compiler

Exercise Files

The contents of the following zip file need to be placed in this directory:
C:\MTT\TLS0101

File Download
Installation
Instructions
Windows Linux Mac OSX
Project and Source Files

 Procedure

1

Open Lab04

Close any open project by right clicking on the project name and selecting “Close”

Click the Open Project Main_Open_Project.png icon

Browse to and open the project C:\MTT\TLS0101\Lab04.X

2

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

ResetWindows.png

MPLAB X IDE will disappear for a second or two. When it returns you should notice changes to the graphical user interface setup

MplabXGui.png
Clean and build the project Main_Rebuild_Project.png

3

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

Dashboard.png

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

pdf.png

Close the browser

4

Navigation Window

Next, open the Source Files folder from the Projects Window

SourceFiles.png

Highlight Lab04.c. The Navigation Window populates with the elements found in Lab04.c

Navigator.png

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.

Lab04Main.png

5

Call Graph

Highlight the main() function in the source window.

Right click and select Show Call Graph

ShowCallGraph.png

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.

CallGraph.png

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

MainCallGraph.png

You will notice the visual call graph change after the delay() function has been expanded.

OpenCallGraph.png

Open both the getInput(), and outputData() functions from the hierarchy window and notice the changes to the call graph.

FullCallGRaph.png

6

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.

RearrangedCallGraph.png

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.

7

Navigating between Files and Functions

SourceCode5.png

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()

Hyperlink.png

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.

OpenInput.png

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

GoBack.png
To return to the calling function select the “Go Back to..” Editor_Back.png button located near the upper left hand corner of the editor dialog box.

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.

8

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?”.

IncrementVar.png

Click on the line number to place a breakpoint on the line of code incrementing the smallDelayVar in delays.c

Lab4.png
Build a debug version of the project by selecting the Debug Project Main_Debug_Project.png icon.

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 Debug_Continue.png icon and watch the program proceed to the breakpoint in smallDelay().
DelayBreakpoint.png

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?

9

Call Stack

CallStack.png

To determine who called a function we will introduce the Call Stack.

Open the call stack by:
Windows->Debugging->Call Stack

OpenCallStack.png

When the call stack is first opened the contents may not be updated.

To update the call stack window press the ContinueDebug_Continue.png icon.

The simulation has proceeded to the second instance of the break in smallDelay().

Observe the output of the call window

Each 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 Debug_Continue.png 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();

Bonus Section

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

10

Moving the Variables Window

VariableWindow.png

To see what the calling functions see, we will open up the Variables window to show us the local variable

Select: Window->Debugging->Variables

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.

MoveVariableWindow.png

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 Debug_Reset.gif icon.

Ensure the Call Stack window is open

Place the Variable Window where it can be seen
Click the Continue Debug_Continue.png icon
ShowAllVariables.png

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.

getInput.png

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.

CallingFunction.png
Click Continue Debug_Continue.png and inspect the status of the calling function local variables by clicking on the function that called smallDelay() to see the Variables window populate.

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

End the debug session Debug_Finish_Debugger_Session.png

20th Annual
Microchip MASTERs Conference 2016
Register now - Deadline: July 29

JW Marriott Desert Ridge Resort-Phoenix, AZ

© 2016 Microchip Technology, Inc.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.