MPLAB® IDE User’s Guide © 2006 Microchip Technology Inc.
Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature.
MPLAB® IDE USER’S GUIDE Table of Contents Preface ........................................................................................................................... 1 Part 1 – MPLAB IDE Getting Started Chapter 1. What is MPLAB® IDE? 1.1 An Overview of Embedded Systems .............................................................. 9 1.2 The Development Cycle ............................................................................... 14 1.3 Project Manager ........................................
MPLAB® IDE User’s Guide Chapter 3. Walk-Through and Detailed Tutorial 3.1 Introduction ................................................................................................... 47 3.2 Selecting a Device ........................................................................................ 48 3.3 Setting Up Configuration Bits ....................................................................... 48 3.4 Creating Source Code with the Editor .........................................................
Table of Contents Chapter 6. Additional Features 6.1 Introduction ................................................................................................... 79 6.2 Configuration Bits ......................................................................................... 79 6.3 Watch Window ............................................................................................. 80 6.4 Breakpoints .................................................................................................
MPLAB® IDE User’s Guide Chapter 12. MPLAB IDE Windows 12.1 Introduction ............................................................................................... 123 12.2 Changing Window Data and Properties ................................................... 124 12.3 Code Display Window Symbols ............................................................... 128 12.4 Project Window ........................................................................................ 129 12.5 Output Window ..........
Table of Contents Chapter 13. MPLAB IDE Dialogs 13.1 Introduction ............................................................................................... 161 13.2 About MPLAB IDE Dialog ......................................................................... 162 13.3 Add Watch Dialog ..................................................................................... 162 13.4 Breakpoints Dialog ................................................................................... 163 13.
MPLAB® IDE User’s Guide Part 4 – MPLAB Editor Chapter 15. Using the Editor 15.1 Introduction ............................................................................................... 189 15.2 Configuring the Editor ............................................................................... 190 15.3 Working with Files .................................................................................... 193 15.4 Working with Text .......................................................................
Table of Contents Appendix A. ............................................................................................................... 257 Glossary ..................................................................................................................... 259 Index ........................................................................................................................... 273 Worldwide Sales and Service .........................................................................
MPLAB® IDE User’s Guide NOTES: DS51519B-page x © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Preface NOTICE TO CUSTOMERS All documentation becomes dated, and this manual is no exception. Microchip tools and documentation are constantly evolving to meet customer needs, so some actual dialogs and/or tool descriptions may differ from those in this document. Please refer to our web site (www.microchip.com) to obtain the latest documentation available. Documents are identified with a “DS” number. This number is located on the bottom of each page, in front of the page number.
MPLAB® IDE User’s Guide • Chapter 5: External Memory Handling – Describes how MPLAB IDE handles Microchip devices that allow the extension or replacement of program memory resources with external (off-chip) memory devices. • Chapter 6: Additional Features – Describes additional features of MPLAB IDE to aid in device setup, code debugging and general support.
Preface CONVENTIONS USED IN THIS GUIDE The following conventions may appear in this documentation: DOCUMENTATION CONVENTIONS Description Represents Examples Arial font: Italic characters Initial caps Referenced books MPLAB® IDE User’s Guide Emphasized text ...is the only compiler...
MPLAB® IDE User’s Guide RECOMMENDED READING This user's guide describes how to use MPLAB IDE. Other useful documents are listed below. The following Microchip documents are available and recommended as supplemental reference resources. Readme for MPLAB IDE For the latest information on using MPLAB IDE, read the “Readme for MPLAB IDE.htm” file (an HTML file) in the Readmes subdirectory of the MPLAB IDE installation directory.
Preface THE MICROCHIP WEB SITE Microchip provides online support via our web site at www.microchip.com. This web site is used as a means to make files and information easily available to customers.
MPLAB® IDE User’s Guide CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels: • • • • Distributor or Representative Local Sales Office Field Application Engineer (FAE) Technical Support Customers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document.
MPLAB® IDE USER’S GUIDE Part 1 – MPLAB IDE Getting Started Chapter 1. What is MPLAB® IDE? ................................................................................ 9 Chapter 2. A Basic Tutorial for MPLAB IDE ............................................................... 23 Chapter 3. Walk-Through and Detailed Tutorial ........................................................ 47 © 2006 Microchip Technology Inc.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 8 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 1. What is MPLAB® IDE? 1.1 AN OVERVIEW OF EMBEDDED SYSTEMS MPLAB IDE is a software program that runs on a PC to develop applications for Microchip microcontrollers. It is called an Integrated Development Environment, or IDE, because it provides a single integrated “environment” to develop code for embedded microcontrollers. Experienced embedded systems designers may want to skip ahead to Section 1.7 “Components of MPLAB IDE”. It is also recommended that Section 1.
MPLAB® IDE User’s Guide 1.1.3 Components of a Microcontroller The PICmicro MCU has program memory for the firmware, or coded instructions, to run a program. It also has “file register” memory for storage of variables that the program will need for computation or temporary storage. It also has a number of peripheral device circuits on the same chip. Some peripheral devices are called I/O ports.
What is MPLAB® IDE? The peripherals and the amount of memory an application needs to run a program largely determines which PICmicro MCU to use. Other factors might include the power consumed by the microcontroller and its “form factor,” i.e., the size and characteristics of the physical package that must reside on the target design. Example PICmicro® MCU DEVICE PACKAGE FIGURE 1-2: E E1 #leads=n1 p D1 D 2 1 B n CH x 45° α A c A2 L β φ A1 (F) 1.1.
MPLAB® IDE User’s Guide FIGURE 1-4: PICmicro® MCU DATA SHEET – INSTRUCTIONS (EXCERPT) 2. Compile, assemble and link the software using the assembler and/or compiler and linker to convert your code into “ones and zeroes” – machine code for the PICmicro MCUs. This machine code will eventually become the firmware (the code programmed into the microcontroller). 3. Test your code.
What is MPLAB® IDE? Step 1 is driven by the designer, although MPLAB IDE can help in modeling circuits and code so that crucial design decisions can be made. MPLAB IDE really helps with steps 2 through 4. Its Programmer’s Editor helps write correct code with the language tools of choice. The editor is aware of the assembler and compiler programming constructs and automatically “color-keys” the source code to help ensure it is syntactically correct.
MPLAB® IDE User’s Guide 1.2 THE DEVELOPMENT CYCLE The process for writing an application is often described as a development cycle, since it is rare that all the steps from design to implementation can be done flawlessly the first time. More often code is written, tested and then modified in order to produce an application that performs correctly.
What is MPLAB® IDE? 1.3 PROJECT MANAGER The project manager organizes the files to be edited and other associated files so they can be sent to the language tools for assembly or compilation, and ultimately to a linker. The linker has the task of placing the object code fragments from the assembler, compiler and libraries into the proper memory areas of the embedded controller, and ensure that the modules function with each other (or are “linked”).
MPLAB® IDE User’s Guide 1.4 LANGUAGE TOOLS Language tools are programs such as cross-assemblers and cross-compilers. Most people are familiar with language tools that run on a PC such as Visual Basic or C compilers. When using language tools for embedded systems, a “cross-assembler” or “cross-compiler” is used.
What is MPLAB® IDE? 1.5 TARGET DEBUGGING In a development environment, the execution of the code is tested on a debugger. The debugger can be a software program that simulates the operation of the microcontroller for testing, or it can be special instrumentation to analyze the program as it executes in the application. Simulators are built into MPLAB IDE so a program can be tested without any additional hardware.
MPLAB® IDE User’s Guide 1.6 DEVICE PROGRAMMING After the application has been debugged and is running in the development environment, it needs to be tested on its own. A device can be programmed with the in-circuit debugger or a device programmer. MPLAB IDE can be set to the programmer function, and the part can be “burned”. The target application can now be observed in its nearly final state. Engineering prototype programmers allow quick prototypes to be made and evaluated.
What is MPLAB® IDE? 1.7.2 Additional Optional Components for MPLAB IDE Optional components can be purchased and added to the MPLAB IDE: • Compiler Language Tools MPLAB C18 and MPLAB C30 C compilers from Microchip provide fully integrated, optimized code. Along with compilers from HI-TECH, IAR, microEngineering Labs, CCS and Byte Craft, they are invoked by the MPLAB IDE project manager to compile code that is automatically loaded into the target debugger for instant testing and verification.
MPLAB® IDE User’s Guide FIGURE 1-8: DEBUGGER>SETTINGS: LIMITATIONS TAB Press the Details button to show specific limitations of the device being debugged. From this display, help on general limitations related to the debugger can also be accessed. FIGURE 1-9: SIMULATOR LIMITATIONS DETAIL From the main MPLAB IDE Help menu, select Help>Topics to get a list of help on MPLAB IDE and all of its components. FIGURE 1-10: DS51519B-page 20 MPLAB® IDE HELP>TOPICS MENU © 2006 Microchip Technology Inc.
What is MPLAB® IDE? MPLAB IDE Help covers all aspects of MPLAB IDE and all of the Microchip tools. It can be viewed in an outline, as an index and with a search utility for help on any MPLAB IDE topic. It also directs users to other types of assistance, such as the Microchip Update Notification system. FIGURE 1-11: © 2006 Microchip Technology Inc.
MPLAB® IDE User’s Guide 1.10 MPLAB IDE UPDATES AND VERSION NUMBERING MPLAB IDE is an evolving program with thousands of users. Microchip is continually designing new microcontrollers with new features. Many new MPLAB IDE features come from customer requests and from internal usage. Continued new designs and the release of new microcontrollers ensure that MPLAB IDE will continue to evolve. MPLAB IDE is scheduled for a version update approximately every four months to add new device support and new features.
MPLAB® IDE USER’S GUIDE Chapter 2. A Basic Tutorial for MPLAB IDE 2.1 INTRODUCTION MPLAB Integrated Development Environment (IDE) is a comprehensive editor, project manager and design desktop for application development of embedded designs using Microchip PICmicro MCUs and dsPIC DSCs. The initial use of MPLAB IDE is covered here. How to make projects, edit code and test an application will be the subject of a short tutorial.
MPLAB® IDE User’s Guide 2.2 MPLAB IDE FEATURES AND INSTALLATION MPLAB IDE is a Windows® Operating System (OS) based Integrated Development Environment for the PICmicro MCU families and the dsPIC Digital Signal Controllers. The MPLAB IDE provides the ability to: • Create and edit source code using the built-in editor. • Assemble, compile and link source code. • Debug the executable logic by watching program flow with the built-in simulator or in real time with in-circuit emulators or in-circuit debuggers.
A Basic Tutorial for MPLAB IDE 2.2.2 Running MPLAB IDE To start MPLAB IDE, double click on the icon installed on the desktop after installation or select Start>Programs>Microchip>MPLAB IDE vx.xx>MPLAB IDE. A screen will display the MPLAB IDE logo followed by the MPLAB IDE desktop (Figure 2-1). FIGURE 2-1: © 2006 Microchip Technology Inc.
MPLAB® IDE User’s Guide 2.3 TUTORIAL OVERVIEW In order to create code that is executable by the target PICmicro MCU, source files need to be put into a project. The code can then be built into executable code using selected language tools (assemblers, compilers, linkers, etc.). In MPLAB IDE, the project manager controls this process. All projects will have these basic steps: • Select Device The capabilities of MPLAB IDE vary according to which device is selected.
A Basic Tutorial for MPLAB IDE 2.4 SELECTING THE DEVICE To show menu selections in this document, the menu item from the top row in MPLAB IDE will be shown after the menu name like this MenuName>MenuItem. To choose the Select Device entry in the Configure menu, it would be written as Configure>Select Device. Choose Configure>Select Device. In the Device dialog, select the PIC18F8722 from the list if it’s not already selected.
MPLAB® IDE User’s Guide 2.5 CREATING THE PROJECT The next step is to create a project using the Project Wizard. A project is the way the files are organized to be compiled and assembled. We will use a single assembly file for this project and a linker script. Choose Project>Project Wizard. From the Welcome dialog, click on Next> to advance. The next dialog (Step One) allows you to select the device, which we’ve already done. Make sure that it says PIC18F8722.
A Basic Tutorial for MPLAB IDE 2.6 SETTING UP LANGUAGE TOOLS Step Two of the Project Wizard sets up the language tools that are used with this project. Select “Microchip MPASM Toolsuite” in the Active Toolsuite list box. Then “MPASM” and “MPLINK” should be visible in the Toolsuite Contents box. Click on each one to see its location. If MPLAB IDE was installed into the default directory, the MPASM assembler executable will be: C:\Program Files\Microchip\MPASM Suite\mpasmwin.
MPLAB® IDE User’s Guide 2.7 NAMING THE PROJECT Step Three of the wizard allows you to name the project and put it into a folder. This sample project will be called MyProject. Using the Browse button, place the project in a folder named Projects32. Click Next>. FIGURE 2-5: DS51519B-page 30 PROJECT WIZARD – NAME PROJECT © 2006 Microchip Technology Inc.
A Basic Tutorial for MPLAB IDE 2.8 ADDING FILES TO THE PROJECT Step Four of the Project Wizard allows file selection for the project. A source file has not yet been selected, so we will use an MPLAB IDE template file. The template files are simple files that can be used to start a project. They have the essential sections for any source file, and contain information that will help you write and organize your code. There is one template file for each Microchip PICmicro MCU and dsPIC DSC device.
MPLAB® IDE User’s Guide FIGURE 2-7: PROJECT WIZARD – SELECT LINKER SCRIPT Make sure that your dialog looks like the picture above, with both checkboxes checked, then press Next> to finish the Project Wizard. The final screen of the Project Wizard is a summary showing the selected device, the toolsuite and the new project file name. FIGURE 2-8: DS51519B-page 32 PROJECT WIZARD – SUMMARY © 2006 Microchip Technology Inc.
A Basic Tutorial for MPLAB IDE After pressing the Finish button, review the Project Window on the MPLAB IDE desktop. It should look like Figure 2-9. If the Project Window is not open, select View>Project. FIGURE 2-9: TIP: © 2006 Microchip Technology Inc. PROJECT WINDOW Files can be added and projects saved by using the right mouse button in the project window. In case of error, files can be manually deleted by selecting them and using the right mouse click menu.
MPLAB® IDE User’s Guide 2.9 BUILDING THE PROJECT From the Project menu, we can assemble and link the current files. They don’t have any of our code in them yet, but this ensures that the project is set up correctly. To build the project, select either: • Project>Build All • Right click on the project name in the project window and select Build All • Click the Build All icon on the Project toolbar. Hover the mouse over icons to see pop-up text of what they represent.
A Basic Tutorial for MPLAB IDE 2.10 CREATING CODE Open the template file in the project by double clicking on its name in the Project Window, or by selecting it with the cursor and using the right mouse button to bring up the context menu: FIGURE 2-11: PROJECT CONTEXT MENU (RIGHT MOUSE CLICK) The file has some comments at the beginning, and this area can be used as a standard comment information header for the file.
MPLAB® IDE User’s Guide FIGURE 2-13: TEMPLATE FILE – MAIN When any source file is opened, you are automatically in the editor.
A Basic Tutorial for MPLAB IDE In this bit of code, we used three variables named COUNT, DVAR and DVAR2. These variables need to be defined in the template file in the UDATA_ACS section for uninitialized data using Access RAM. Using the Access bank will make the code simpler, as there will be no need to keep track of banks (banksel) for each variable. There is already one variable in this section of the template file, and ours can be added at the end using the same format.
MPLAB® IDE User’s Guide If the code did not assemble and link successfully, check the following items and then build the project again: • If the assembler reported errors in the Output window, double click on the error and MPLAB IDE will open the corresponding line in the source code with a green arrow in the left margin of the source code window. • Check the spelling and format of the code entered in the editor window.
A Basic Tutorial for MPLAB IDE Select the simulator as the debug execution tool. This is done from the Debugger>Select Tool pull down menu. After selecting MPLAB SIM, the following changes should be seen (see corresponding numbers in Figure 2-16). 1 The status bar on the bottom of the MPLAB IDE window should change to “MPLAB SIM”. 2 Additional menu items should now appear in the Debugger menu. 3 Additional toolbar icons should appear in the Debug Tool Bar.
MPLAB® IDE User’s Guide Next, select Debugger>Reset>Processor Reset and a green arrow shows where the program will begin. This was part of the template file. The first instruction in memory jumps to the label called Main, where your code was inserted. This instruction jumps over the PIC18XXXX vector areas in lower memory. FIGURE 2-17: CODE AFTER PROCESSOR RESET To single step through the application program, select Debugger>Step Into.
A Basic Tutorial for MPLAB IDE Next, press the Step Into icon or select Debugger>Step Into to single step to the code at Main. FIGURE 2-18: CODE AFTER STEP INTO In order to see if the code is operating as intended, sending incrementing values out PORTC, watch the values being sent to PORTC. Select View>Watch to bring up an empty Watch window. There are two pull downs on the top of the Watch window.
MPLAB® IDE User’s Guide The pull down on the right, allows symbols to be added from the program. Use this pull down to add the COUNT variable into the Watch window. Select COUNT from the list and then click Add Symbol to add it to the window. FIGURE 2-20: WATCH – SELECT VARIABLE “COUNT” The Watch window should now show the address, value and name of the two registers. At this point in the program, they will both be zero.
A Basic Tutorial for MPLAB IDE You could continue single stepping through the code, but instead, set a breakpoint just before the first value is sent out to PORTC. To set a breakpoint, put the cursor on the line following line: movwf PORTC ; display COUNT on PORTC and click the right mouse button. FIGURE 2-22: DEBUG CONTEXT MENU (RIGHT MOUSE CLICK ON LINE) Select Set Breakpoint from the context menu. A red “B” will show on the line. (You can also double click on a line to add a breakpoint.
MPLAB® IDE User’s Guide Select Debugger>Run to run the application. A text message “Running…” will briefly appear on the status bar before the application halts at this first breakpoint. The Watch window should now show that the variable COUNT was incremented by one, but since the breakpoint is at the line before the move to PORTC executes, PORTC still has a value of zero. FIGURE 2-24: WATCH – AT BREAKPOINT Press the Run icon to execute the code until it hits this point again.
A Basic Tutorial for MPLAB IDE Use Debugger>StopWatch to bring up the StopWatch dialog. Make sure that a single breakpoint is set at the movwf COUNT instruction, and then press Debugger>Reset and then Debugger>Run to halt at the movwf COUNT instruction. With the default processor frequency of 4 MHz, the StopWatch should show that it took 8 microseconds to reach the first breakpoint.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 46 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 3. Walk-Through and Detailed Tutorial 3.1 INTRODUCTION This walk-through and tutorial is designed to help both new and experienced application developers. Step-by-step instructions for developing with MPLAB IDE and various Microchip development tools are given, where each step first discusses general information and then provides a specific example of use. All step examples tie together to form an example application.
MPLAB® IDE User’s Guide 3.2 SELECTING A DEVICE To begin application development, select the Microchip device you wish to develop code for. To choose a device: 1. Select Configure>Select Device. 2. In the Select Device dialog, choose a device from the Device list box. Typing in the first few letters of the name will allow you to locate your device more quickly. The Microchip Tool Support section will reflect the available tool support for that device. 3. Click OK.
Walk-Through and Detailed Tutorial 3.4 CREATING SOURCE CODE WITH THE EDITOR Select File>New to open an empty editor window in which to type your source code. To save your work, select File>Save. For more on the editor, see Chapter 15. “Using the Editor”. Tutorial Step 3: Create/locate a folder (directory), using Windows Explorer, where you will place application project files. Then, type the following code into an MPLAB IDE editor window, or cut and paste from here. Save the file as cnt8722.
MPLAB® IDE User’s Guide 3.6 USING THE PROJECT WIZARD To create a new project in the current workspace, use the Project Wizard. • Select Project>Project Wizard. • The Project Wizard Welcome screen will appear. Click Next> to continue. • The Project Wizard Select a Device screen will appear. Verify that the device you have already selected using the Select Device dialog is shown here. To change the device, use the drop-down menu. Click Next> to continue.
Walk-Through and Detailed Tutorial 3.8 NAMING AND LOCATING THE PROJECT You will now enter a name and location for your new project. You should see two text boxes for entering the “Project Name” and “Project Directory”. To set the directory: • Type in the path to an existing directory. If you type in the path to a new directory, you will be prompted to create the directory when you click Next>. • Click Browse to browse to an existing directory or to one level above where you wish to place a new directory.
MPLAB® IDE User’s Guide The linker script files are as follows: Use PIC10/12/16 PIC24/dsPIC® DSC PIC18 General DevNum.lkr DevNum.lkr DevNum_e.lkr DevNum.lkr MPLAB® ICD 2 DevNumi.lkr DevNumi.lkr DevNumi_e.lkr DevNumi.lkr MPLAB ICE 2000* DevNum.lkr DevNum.lkr DevNum_e.lkr n/a MPLAB ICE 4000 n/a DevNum.lkr DevNum_e.lkr DevNume.lkr * Not all PIC18 MCUs supported on MPLAB ICE 2000. • DevNum – the number associated with the device, e.g., 18f8722.lkr for the PIC18F8722 device.
Walk-Through and Detailed Tutorial 3.11 VIEWING THE PROJECT WINDOW If it is not already open, open the Project window by selecting View>Project. The workspace name should be visible in the top bar of the Project window. The name of the project should be visible inside the Project window at the top of the display. A tree structure listing file types and any added files will appear below. For more on this window, see Section 12.4 “Project Window”.
MPLAB® IDE User’s Guide To override project settings for a particular project file, e.g., ProjFile1.asm, select Project>Build Options>ProjFile1.asm or right click on ProjFile1.asm in the Project window and select Build Options from the pop-up menu. • The File Settings dialog will open. • Click a specific language tool tab (e.g., MPASM Assembler) and set up operational features for that tool. • Click OK. Tutorial Step 11: Set up project build options: • Select Project>Build Options>Project.
Walk-Through and Detailed Tutorial 3.14 CHOOSING A DEBUGGER Choose a tool to help debug your code from Debugger>Select Tool. Microchip provides several types of debug tools: • MPLAB SIM simulator – Simulate device operation in software. • MPLAB ICD 2 in-circuit debugger – Debug your code in the device using an ICD and special Flash devices with built-in debug circuitry. See the Readme file in the MPLAB IDE directory for a list of supported devices.
MPLAB® IDE User’s Guide Tutorial Step 14: Reset your code (Debugger>Reset) and then run it by clicking the Run icon on the toolbar. (Hover your mouse over a toolbar icon to see its meaning.) Then stop the program by clicking the Halt icon. 3.16 VIEWING DEBUG WINDOWS Standard debug windows allow you to view the contents of program, data or other types of device memory to aid in the debugging of your application. These windows are always visible on the View menu.
Walk-Through and Detailed Tutorial The file register address of the symbols is listed first, followed by the symbol name and finally the value of the symbol. For more on Watch windows, see Section 6.3 “Watch Window”. Tutorial Step 16: You will first set up the Watch window: • Select COUNT from the symbol selection box at the top of the window. Click Add Symbol to add it to the Watch window list. If you want to quickly advance through the list, start typing COUNT after selecting the pull down icon.
MPLAB® IDE User’s Guide 3.19 CHOOSING A PROGRAMMER Once you have your code debugged and running smoothly, it is time to program a device and try it in your application. Select a programmer from Programmer>Select Programmer. The programmer you use will depend on the device that you wish to program. • PICSTART Plus and PICkit 1 or 2 development programmers – Used to program most PICmicro MCU devices in a development (nonproduction) environment.
MPLAB® IDE USER’S GUIDE Part 2 – MPLAB IDE Features Chapter 4. Projects and Workspaces ......................................................................... 61 Chapter 5. External Memory Handling ....................................................................... 75 Chapter 6. Additional Features ................................................................................... 79 Chapter 7. Integrated Language Tools .......................................................................
MPLAB® IDE User’s Guide NOTES: DS51519B-page 60 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 4. Projects and Workspaces 4.1 INTRODUCTION Two major features of MPLAB IDE are projects and workspaces. A project contains the files needed to build an application (source code, linker script files, etc.) along with their associations to various build tools and build options. A workspace contains information on the selected device, debug tool and/or programmer, open windows and their location and other IDE configuration settings.
MPLAB® IDE User’s Guide 4.2 USING THE PROJECT WIZARD The project wizard consists of several dialogs which will walk you through setting up your project. • • • • • • Project Wizard – Welcome Project Wizard – Select Device Project Wizard – Select a Language Toolsuite Project Wizard – Name Your Project Project Wizard – Add Files Project Wizard – Summary 4.2.1 Project Wizard – Welcome Select Project>Project Wizard to begin the setup wizard for projects.
Projects and Workspaces 4.2.4 Project Wizard – Name Your Project Step 3: Name Your Project – Enter a name and location for your new project. To set the directory: • Type in the path to an existing directory, or type in the path to a new directory, which will prompt you to create the directory when you click Next. • Click Browse to browse to an existing directory or to one level above where you wish to place a new directory. Click OK in the Browse for Folder dialog.
MPLAB® IDE User’s Guide 5. Enter files in the project by selecting Project>Add Files to Project, by right clicking on the project name in the Project window and selecting Add Files to Project, or by right clicking on the type of file in the Project window and selecting Add Files to enter that specific type of file. Note: You can add a file to a project, even if the file does not yet exist. This is useful for structuring a project before you actually developed the files.
Projects and Workspaces 4.5 PROJECT FOLDERS AND FILES Depending on how you have structured your project (see Section 4.4 “Setting Up a Project Structure – Relative Paths”) and how you have defined the project paths (Project>Build Options>Project, General tab), your project files may be all in the main project folder or spread out into separate subfolders. The structure represented in the Project window tree, however, will be based on which files you have specifically added to the project and the file type.
MPLAB® IDE User’s Guide TABLE 4-1: File Type Other Files* PROJECT FILE TYPES (CONTINUED) Example Files file.txt stim.scl 39582b.pdf Description Any file that does not fit into any of the other categories will end up in this one. You can add simulator files – SBS, STC, SCL – and double click on them to open the SCL Generator, Stimulus Controller, or editor, respectively. You can add project-specific data sheets (PDFs) to this location in the Project window.
Projects and Workspaces 4.6.1 Microsoft Visual Source Safe Having some knowledge of VSS and MPLAB IDE is necessary to use VSS from within MPLAB IDE. For more information on this version control system, please see the related web site. • Microsoft Visual Source Safe: http://www.microsoft.com Certain VSS files are required to be available locally (on your PC) for VSS to work with MPLAB IDE. If you are using VSS on a network drive, you will need to run NETSETUP.EXE to install the proper files on your PC. 4.
MPLAB® IDE User’s Guide An example of performing the checkout is listed below: $ cd DirABOVEWhereIWantMySrcTree $ cvs checkout MyProject cvs server: Updating MyProject U MyProject/main.c U MyProject/such-and-such-a-file.c U MyProject/foo.h It is important that you give this command from above the directory where you want your source tree to reside, because CVS will actually create the entire source tree within the current working directory. 4.6.3.
Projects and Workspaces 4.7 SETTING UP/CHANGING A PROJECT You can use the following steps to create a new project manually (using the Project Setup Wizard is recommended) or change an existing project's settings. • • • • • • • Create a New Project New Project Window Setting Up a Project – Set Up Language Tools Setting Up a Project – Choose Toolsuite Setting Up a Project – Add Files Setting Up a Project – Set Build Options Setting Up a Project – Save and Build 4.7.
MPLAB® IDE User’s Guide 4.7.3 Setting Up a Project – Set Up Language Tools To add language tools for use in the project, select Project>Set Language Tool Locations or right click on the project name in the Project window and select Set Language Tool Locations from the pop-up menu. • Click on a registered tool in a toolsuite to select it. • Type in the “Location” or browse to the location of the tool executable by clicking Browse. • Repeat this for each tool you wish to use in the project.
Projects and Workspaces 4.7.6 Setting Up a Project – Set Build Options MPLAB IDE has default settings for tools and files contained in a project. However, you may want or need to modify these settings. To set build options, select Project>Build Options>Project or right click on the project name in the Project window and select Build Options from the pop-up menu. • The Build Options dialog will open.
MPLAB® IDE User’s Guide 4.8 USING A SINGLE PROJECT AND WORKSPACE The most common configuration for application development in MPLAB IDE to is have one project in one workspace. If you wish to use an MPLAB IDE v5.xx-style project (not worry about workspaces), select Configure>Settings, Projects tab and check “Use one-to-one project-workspace model”. 1. Select the device you will use for development (Configure>Select Device). 2. Create/open and set up a project in the current workspace. 3. Build the project.
Projects and Workspaces 4.9.1 Setting Up Multiple Projects To set up the workspace to use multiple projects: 1. Select the device you will use for development (Configure>Select Device). 2. Create/open and set up the first project in the current workspace. 3. Make sure that the following options are selected. Then repeat #2 for each project you wish to add to the workspace.
MPLAB® IDE User’s Guide The last project opened in a workspace will automatically be set as the active project. To set a project as the active project, select Project>Set Active Project> projectname.mcp, where projectname.mcp is the project name, or right click on the project in the Project window and select Set As Active Project. The project name will appear in bold in the Project window. 4.9.
MPLAB® IDE USER’S GUIDE Chapter 5. External Memory Handling 5.1 INTRODUCTION Some Microchip devices allow the extension or replacement of program memory resources with external (off-chip) memory devices. MPLAB IDE handles this device feature as described here. • Configuration Bits and External Memory Setup • External Memory Enabled in MPLAB IDE • Program Memory Window 5.
MPLAB® IDE User’s Guide • The Extended Microcontroller mode allows access to both internal and external program memories as a single block. The device can access its entire on-chip program memory; above this, the device accesses external program memory up to the program counter accessible limit (see Section 5.2.4 “Program Counter”). Execution automatically switches between the two memories, as required. In all modes, the device has complete access to data RAM.
External Memory Handling 5.2.5 External Memory Interface The External Memory Interface is a feature that allows the microcontroller to access external memory devices (such as Flash, EPROM, SRAM, etc.) as program or data memory. PIC17 Devices When either Microprocessor or Extended Microcontroller mode is selected, PORTC, PORTD and PORTE are configured as the system bus. PORTC and PORTD are the multiplexed address/data bus and PORTE<2:0> is for the control signals.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 78 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 6. Additional Features 6.1 INTRODUCTION MPLAB IDE contains additional features to aid in device setup, code debugging and general support. • • • • • 6.2 Configuration Bits Watch Window Breakpoints High-Level Language Support Microchip Help CONFIGURATION BITS Configuration bits can be programmed (read as ‘0’), or left unprogrammed (read as ‘1’), to select various device configurations. Consult your device data sheet for more information. 6.2.
MPLAB® IDE User’s Guide 6.2.4 Setting for External Memory Use If your device supports external memory, and you select a mode which uses external memory in the Configuration bits, you will also need to set the amount of external memory used in the External Memory Settings dialog (Configure>External Memory). 6.
Additional Features To add a symbol to a Watch view: • Select the symbol from the drop-down list and then click Add Symbol. • Right click in the window and select Add to open the Add Watch dialog. Select the symbol from the drop-down list. Select the Format for the symbol value. Click Add Symbol. • Drag-and-drop a symbol from either the SFR, File Register or Editor window to the Watch window.
MPLAB® IDE User’s Guide 6.3.3 Deleting from a Watch View To delete an entry: • Click on the entry to select it, and then hit Delete. • Click on the entry to select it. Right click on the entry and select Delete. To delete (hide) a column: • Right click on the column header bar and select each checked header to delete. • Right click on the column header bar and select More to open the Watch dialog. On the Column Setting tab, uncheck each header to delete. Click OK.
Additional Features To import Watch variable values from a table: • Click on an entry to select the SFR/Symbol. Right click in the window and select Import Table. In the Table Setup dialog, check or change import information and click OK. 6.3.7 C Language Usage – Watch Window If you are developing your application code in C, the following features are available in the Watch window to you: • Bitfield value mouseover available.
MPLAB® IDE User’s Guide 6.3.9 Watch Window and Associated Dialogs The following MPLAB IDE windows and dialogs are associated with Watches: • • • • 6.4 Section 12.14 “Watch Window” Section 13.3 “Add Watch Dialog” Section 13.27 “Table Setup Dialog” Section 13.30 “Watch/Locals Dialog” BREAKPOINTS Breakpoints allow you to specify conditional program halts so that you may observe memory, register or variable values after a run-time execution.
Additional Features • When you delete a breakpoint in the Program Memory window on any line of assembly code that represents a single line of C code, the red breakpoint symbol will disappear next to the assembly code line but the yellow breakpoint symbol will remain next to the line of C code until all corresponding assembly code breakpoints are deleted. 6.4.4 Breakpoints and MPLAB ICD 2 MPLAB ICD 2 in-circuit debugger supports a limited amount of breakpoints.
MPLAB® IDE User’s Guide 6.6 MICROCHIP HELP Microchip Technology provides on-line HTML help for MPLAB IDE and each of its development tools. Select Help>Topics to bring up a list of available help files in the Help Topics dialog. 6.6.1 Types of Help Available Tool help is available from the MPLAB IDE Help menu. Help on specific dialog boxes or windows is available from those items. Limitations of a tool are available from the Settings dialog. 6.6.1.
Additional Features 6.6.2 Navigating in the Help Viewer The main features of the help viewer are shown below. FIGURE 6-2: HELP VIEWER – MAIN FEATURES previous view previous page next view Title Bar next page Button Bar View Pane Navigation Pane Browse Buttons Title Bar Displays the name of the current help file. Button Bar If you do not see a function you need on the button bar, click the Options button to see more available functions. • Show/Hide – Show or Hide the Navigation Pane.
MPLAB® IDE User’s Guide Navigation Pane To close this pane, click on the Hide button (which will change to a Show button) on the button bar. To view this pane, click on the Show button (which will change to a Hide button). • Contents tab – Click to view a functionally organized list of all Microchip Help topics. Click on the + next to a folder to open the folder and see the topics contained within. Click on a topic listed here to view it in the right pane of the viewer.
MPLAB® IDE USER’S GUIDE Chapter 7. Integrated Language Tools 7.1 INTRODUCTION MPLAB IDE is designed to work with many Microchip and third party language tools. These tools take your application code (written in assembly, C or BASIC language) and turn it into executable code that may be programmed on your selected Microchip device. For information on software/hardware development tools supported by MPLAB IDE, see Chapter 8. “Integrated Software/Hardware Tools”.
MPLAB® IDE User’s Guide 7.2.1 Selecting the Language Toolsuite Once a workspace is opened, a toolsuite can be selected from Project>Select Language Toolsuite. In some cases, MPLAB IDE will know where the various executables for the toolsuite are located, but sometimes these will need to be set manually before MPLAB IDE can use the tools.
Integrated Language Tools Microchip ASM30 Toolsuite This toolsuite includes the language tools MPLAB ASM30 assembler, MPLAB LINK30 object linker and MPLAB LIB30 object librarian. The executables for these files are pic30-as.exe, pic30-ld.exe and pic30-ar.exe, and are located in the dspic_tools\bin subdirectory of the main MPLAB IDE installation directory. For more information on these tools, see Section 7.3.2 “Microchip 16-Bit Language Tools”.
MPLAB® IDE User’s Guide Documentation Please find the following C compiler documentation on the MPLAB IDE CD-ROM (DS51123) or the Microchip web site: • • • • • “MPLAB® C18 C Compiler Getting Started” (DS51295) “MPLAB® C18 C Compiler User's Guide” (DS51288) “MPLAB® C18 C Compiler Libraries” (DS51297) “MPLAB® C17 C Compiler User's Guide” (DS51290) “MPLAB® C17 C Compiler Libraries” (DS51296) 7.3.
Integrated Language Tools 7.4 THIRD PARTY LANGUAGE TOOLS Currently supported third-party language tools in MPLAB IDE are: • • • • • • B Knudsen Data Language Tools Byte Craft Language Tools CCS Language Tools HI-TECH Language Tools IAR Language Tools microEngineering Labs Language Tools Other language tools supporting Microchip devices may be available from third parties. Please see the Microchip web site for a complete list of these suppliers. 7.4.
MPLAB® IDE User’s Guide • If you closed the previous dialog, select Project>Set Language Tool Locations. In the Set Language Tool Location dialog, find the toolsuite you will be using in the list and click on the first tool in this suite you will be using. • View the executable path in the Location of Selected Tool text box. If there is no location/path listed, enter one or browse for one. • Click OK until all language tool dialogs are closed. For more information, see the CCS web site (http://www.ccsinfo.
Integrated Language Tools 7.4.6 microEngineering Labs Language Tools MPLAB IDE supports the following microEngineering Labs language tools: Tool Name Executable Basic Compiler, most PICmicro® MCU devices PicBasic Compiler pb Basic Compiler, all PICmicro MCU devices PicBasic Pro Compiler pbp For more information, see the microEngineering Labs web site (http://www.melabs.com). © 2006 Microchip Technology Inc.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 96 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 8. Integrated Software/Hardware Tools 8.1 INTRODUCTION MPLAB IDE is designed to work with many Microchip and third party software/hardware development tools. For information on language tools supported by MPLAB IDE, see Chapter 7. “Integrated Language Tools”. • • • • • • • 8.2 Editors Simulators In-Circuit Emulators In-Circuit Debuggers Programmers Support Tools Third Party Tools EDITORS MPLAB IDE supports the MPLAB Editor.
MPLAB® IDE User’s Guide 8.4 IN-CIRCUIT EMULATORS The following Microchip in-circuit emulators are supported: Emulator Name MPLAB® ICE 2000 MPLAB ICE 4000 Devices Emulated* ® PICmicro MCUs PIC18 MCUs, dsPIC® DSCs * See the related Readme file in the MPLAB IDE installation directory for a list of supported devices. Help Files From the MPLAB IDE Help menu, select Topics and then select under Debuggers: • MPLAB ICE 2000 • MPLAB ICE 4000 Related Topics • Section 8.8 “Third Party Tools” 8.
Integrated Software/Hardware Tools Help Files From the MPLAB IDE Help menu, select Topics and then select under Programmers either: • MPLAB PM3 • PRO MATE II • PICSTART Plus Additionally, under Debuggers, you can select: • MPLAB ICD 2 Documentation Please find the following documentation on the MPLAB IDE CD-ROM (DS51123) or the Microchip web site. • “PICkit™ 1 Flash Starter Kit User's Guide” (DS40051) • “PICkit™ 2 Microcontroller Programmer User’s Guide” (DS51553) Related Topics • Section 8.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 100 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 9. MPLAB Macros 9.1 INTRODUCTION MPLAB IDE supports the creation of macros, or the recording and playback of keyboard and/or mouse operations. Once a macro has been created, it may be saved to a file for future use. • Using Macros • Macro Menu and Toolbar • Macros Dialog 9.2 USING MACROS To enable macros, select Tools>MPLAB Macros. A Macro menu and toolbar will appear on the desktop (see Section 9.3 “Macro Menu and Toolbar”). To disable macros, select Macros>Exit Macros.
MPLAB® IDE User’s Guide 9.3 MACRO MENU AND TOOLBAR The Macro menu contains the following functions: • • • • • Record Macro – Begin recording keystrokes and/or mouse movements. Stop Recording – End recording keystrokes and/or mouse movements. Play Macro – Play back keystrokes and/or mouse movements. Open Macro – Open a macro file. Save Macro – Save recorded keystrokes and/or mouse movements to a macro file. • Macro Options – Set macro options in a dialog. See Section 9.4 “Macros Dialog”.
MPLAB® IDE USER’S GUIDE Part 3 – MPLAB IDE Reference Chapter 10. MPLAB IDE Troubleshooting................................................................ 105 Chapter 11. MPLAB IDE Desktop.............................................................................. 109 Chapter 12. MPLAB IDE Windows ............................................................................ 123 Chapter 13. MPLAB IDE Dialogs............................................................................... 161 Chapter 14.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 104 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 10. MPLAB IDE Troubleshooting 10.1 INTRODUCTION This section is designed to help you troubleshoot any problems, errors or issues you encounter while using MPLAB IDE. If none of this information helps you, please see the Preface for ways to contact Microchip Technology. Topics covered are: • Common Problems/FAQ – A list of the most commonly-encountered problems and frequently asked questions. • Error Messages – A list of error messages produced by this tool.
MPLAB® IDE User’s Guide I cannot get my language tools to work with MPLAB IDE. You may need a newer version of the language tools to work with MPLAB IDE. Please go to our web site or third party web site to get the latest version of your language tool. I can't see all of the characters in the displays. When using a System Display Font Size of Large Fonts (125% normal), and selecting an Italic font, some characters may display truncated on the top-right border.
MPLAB IDE Troubleshooting I tried to Step Over / Step Out of a function/subroutine, and now my program is hung up. Stepping over or out of a function or subroutine will actually execute all or some of the code in that function/subroutine. Therefore, there is the potential to be caught in an endless loop. Select Halt to regain control in MPLAB IDE.
MPLAB® IDE User’s Guide Unresolved Breakpoints This message displays when breakpoints aren't set on a valid line, i.e., when breakpoints are set on optimized code, or code that does not have a valid assembly instruction associated with the breakpoint line. For information on how to fix an unresolved breakpoints, see Section 13.4 “Breakpoints Dialog”. 10.4 LIMITATIONS Some MPASM assembler limitations can appear to be MPLAB IDE limitations.
MPLAB® IDE USER’S GUIDE Chapter 11. MPLAB IDE Desktop 11.1 INTRODUCTION The MPLAB IDE desktop is a resizable window that operates independent of the rest of the menu items. The desktop consists of a menu bar, tool bars, a status bar and any open windows and/or dialogs. The bars are covered here. Windows and dialogs are discussed in Chapter 12. “MPLAB IDE Windows” and Chapter 13. “MPLAB IDE Dialogs” respectively.
MPLAB® IDE User’s Guide Open Opens an existing source file. You may select multiple files in the Open dialog (see Section 13.10 “File Management Dialog”) by clicking the filenames while holding down the CTRL or Shift key. Close Closes the active editor window. If the file has changed since it was saved last, you will be prompted to save changes. Save Saves the active editor window to disk under its original file name. Save As Opens the Save As dialog (see Section 13.
MPLAB IDE Desktop Exit Closes the MPLAB IDE application. 11.2.2 Edit Below are the menu items in the Edit menu. For more on the editor and the items shown here, see Chapter 15. “Using the Editor”. Undo Reverses the last change made to the active window. When there is no edit action to undo, the menu command is grayed out and you cannot select the command. Redo Reverses the effect of the most recent Undo operation in the active window.
MPLAB® IDE User’s Guide Advanced Advanced editing features. Includes making selected text all uppercase or lowercase, commented text or regular code, or indented or unindented text. In addition there is a Match function. Go to the brace that is the matching brace for the brace at the cursor. This function works for curly braces, parentheses, angle brackets and square brackets. Bookmarks Work with bookmarks.
MPLAB IDE Desktop Open Add an existing project to the workspace and set as active. Opens the Open Project dialog (see Section 13.10 “File Management Dialog”). Close Close the current project in the workspace. You will be prompted to save the current project before closing. Closing a project does not close the workspace. Use Edit>Workspace>Close to close the workspace. Set Active Project Select a project as the active project in the workspace. For more on active projects, see Section 4.
MPLAB® IDE User’s Guide Select Language Toolsuite Select the toolsuite you will use for your project, e.g., Microchip Toolsuite. (See Section 13.24 “Select Language Toolsuite Dialog”.) Set Language Tool Locations Set the paths/directories to the language tools you will be using in your project, i.e., match a language tool name in MPLAB IDE (ex: MPASM assembler) with an executable (ex: C:\Program Files\Microchip\MPASM Suite\mpasmwin.exe). (See Section 13.25 “Set Language Tool Location Dialog”.
MPLAB IDE Desktop Halt Halt (stop) the execution of program code. When you click Halt, status information is updated. Step Into Single step through program code. For assembly code, this command executes one instruction (single or multiple cycle instructions) and then halts. After execution of one instruction, all the windows are updated. For C code, this command executes one line of C code, which may mean the execution of one or more assembly instruction, and then halts.
MPLAB® IDE User’s Guide Enable Programmer Establish communications between MPLAB IDE and the programmer. This is grayed out if the programmer is already enabled. Disable Programmer End communications between MPLAB IDE and the programmer. This is grayed out if the programmer is already disabled. Program Program specified memory areas: program memory, Configuration bits, ID locations and/or EEPROM data.
MPLAB IDE Desktop RTOS Viewer If you have a Real-Time Operating System (RTOS) installed and included in your project, you can open the viewer. See Section 12.19 “RTOS Viewer Window”. Symbol Browser Open the Symbol Browser viewer to see the symbols in a tree format for your active project. See Section 12.20 “Symbol Browser”. AN908 ACIM Tuning Interface Use this interface in support of application note AN908 (DS00908). See the separate help file for this interface (Help>Topics, “Tools”).
MPLAB® IDE User’s Guide Tile Horizontally Arrange open windows in smaller sizes to fit next to each other horizontally. Tile Vertically Arrange open windows in smaller sizes to fit next to each other vertically. Arrange Icons Arrange all iconized windows on the bottom of the IDE. Window Sets Select a predefined window set. Create a set with “Create Window Set”. Delete a set with “Destroy Window Set”. Create Window Set Save the current window/toolbar layout to a file.
MPLAB IDE Desktop 11.3 MPLAB IDE TOOLBARS MPLAB IDE displays different toolbars depending on which features or tools you are using. The icons in these toolbars provide shortcuts to routine tasks. Toolbars Features • • • • • Click and drag the toolbar to make it a floating toolbar. Click and drag the toolbar to the top or sides of MPLAB IDE desktop to dock it. Click and drag the toolbar off the MPLAB IDE desktop. Hover the mouse pointer over an icon to pop up the icon name.
MPLAB® IDE User’s Guide 11.3.3 Debug Toolbar The Debug Toolbar currently contains button icons for the following functions: • • • • • • • Run – Run program Halt – Halt program execution Animate – Continually step into instructions – Halt using Debugger>Halt Step Into – Step into next instruction Step Over – Step over next instruction Step Out – Step out of subroutine Reset – Perform MCLR Reset Depending on the debug tool chosen, other icons may appear. 11.3.
MPLAB IDE Desktop 11.4 MPLAB IDE STATUS BAR The status bar provides up-to-date information on the status of your MPLAB IDE session. When an application is running, it displays “Running” and a progress bar.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 122 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 12. MPLAB IDE Windows 12.1 INTRODUCTION MPLAB IDE windows behave as normal Windows applications. Other standard Windows features include window sizing buttons and vertical and horizontal scroll bars. Additional MPLAB IDE window features are: • • • • In-place editing of data Dockable windows Click-and-drag to change window column width and order Right click (context) menu to change window font and color Most windows available in MPLAB IDE are listed under the View menu.
MPLAB® IDE User’s Guide 12.2 CHANGING WINDOW DATA AND PROPERTIES MPLAB IDE windows have some or all of the listed properties, depending on the type and use of the window. 12.2.1 Changing Window Data – Edit-in-Place or Choose from List MPLAB IDE window data may be edited as described below. If you cannot edit the data, then this information is not available for you to change. • Data may be edited “in place”, i.e., double click to select an item and then type in a new value.
MPLAB IDE Windows 12.2.2.2 MAKING WINDOWS DOCKABLE Windows may be made dockable by clicking on the window system menu (located in the upper left-hand corner of the window) and selecting “Dockable” from the drop-down menu. (This will select the “Dockable” feature.) FIGURE 12-2: 12.2.2.3 MAKE WINDOW DOCKABLE DOCKING/FLOATING DOCKABLE WINDOWS Dockable windows may be docked to the top or sides of the MPLAB IDE desktop by dragging them to the desired docking location.
MPLAB® IDE User’s Guide 12.2.2.4 UNDOCKING DOCKABLE WINDOWS Dockable windows may be undocked by double clicking on the gripper bar. FIGURE 12-4: UNDOCK WINDOW Gripper Bar 12.2.2.5 MAKING WINDOWS UNDOCKABLE Docked windows may be made undockable by right clicking on the gripper bar and selecting “Dockable” from the menu. (This will deselect the “Dockable” feature.
MPLAB IDE Windows 12.2.3.2 MAKE COLUMNS VISIBLE/INVISIBLE Columns can be made visible/invisible as follows: • Right click on any column head and check an item from the list to make it visible. • Right click on any column head and select More to open the window Properties dialog, Column Settings tab, (see Section 13.21 “Properties Dialog”) where you may set column visibility. • Right click in the window and select Properties. On the Column Settings tab, you may set column visibility. 12.2.3.
MPLAB® IDE User’s Guide 12.3 CODE DISPLAY WINDOW SYMBOLS In the gutter of some windows, the following symbols may appear: Current location (line of code) of the program counter. Program execution is halted (stopped). Location of the program counter before the program was run. Program is currently executing (running). Breakpoint set. Breakpoint disabled. Breakpoint set on an address. This symbol is displayed only in the file (editor) window, since one line of code could correspond to several addresses.
MPLAB IDE Windows 12.4 PROJECT WINDOW The Project window contains a summary of information about the project. Select View>Project to alternately view or close the Project window. The Files tab displays project files in a tree structure. The Symbols tab displays C code symbols, i.e., functions, variables, etc. • • • • • Project Window Display – Files Tab Project Window Menus – Files Tab Project Window Display – Symbols Tab Project Window Menus – Symbols Tab Project Window FAQ 12.4.
MPLAB® IDE User’s Guide 12.4.2 Project Window Menus – Files Tab Depending on where you click in the project window, different menus are available. • • • • Display Menu Project Menu File Type Menu File Menu 12.4.2.1 DISPLAY MENU If you right click on any open space in the project window, a menu with project display commands will be displayed. Refresh This command causes the IDE to go out and check the status of all the files in all projects.
MPLAB IDE Windows Save As Save the active project to a new location/name. See Section 13.22 “Save Project As Dialog”. Close Close/remove the selected project in the workspace. Add Files Insert files into the project. Depending on the type of file, MPLAB IDE will sort the files into the correct type within the project window tree. Note: Adding Header Files to the project window will not cause these files to be added to the project build. You must use a #include statement in your code.
MPLAB® IDE User’s Guide Add Files Insert files into the project. Depending on the type of file, MPLAB IDE will sort the files into the correct type within the project window tree. Note: Adding Header Files to the project window will not cause these files to be added to the project build. You must use a #include statement in your code. Filter Change the way files are filtered to determine file type. For example, to be able to add an assembly file with extension .a under Source Files, add .
MPLAB IDE Windows FIGURE 12-7: SYMBOL TREE GENERAL STRUCTURE workspace name project name symbol type symbols If the project name is in bold, it is the active project. If the project name is followed by an asterisk (e.g., c:\project1\project.mcp* ), either the project settings have changed or the project is new, and it needs to be saved. The code used to scan the project files and create this view is an OpenSource application named CTags (http://ctags.sourceforge.net).
MPLAB® IDE User’s Guide 12.4.5 Project Window FAQ How do I: Create/Update a project? See Section 4.3 “Creating/Updating any Project”. Build a project? Right click on the project in the workspace that you wish to build. In the menu, select Build All to build the entire project or Make to recompile/reassemble any changed files and then build. The results of this build will be loaded into program memory, even if the selected project is not the active project. Use projects with workspaces? See Chapter 4.
MPLAB IDE Windows 12.6 DISASSEMBLY LISTING WINDOW Select View>Disassembly Listing to view disassembled code in this window. Breakpoints may be set in code. See Section 6.4 “Breakpoints”. Code execution information may be displayed in the form of symbols in the gutter of the window. Note: COD files containing EEData may not work properly. Both the start of the program and EEData appear as Line 0 in the line number table. Below are the menu items in the Disassembly window right mouse button menu.
MPLAB® IDE User’s Guide 12.7 HARDWARE STACK WINDOW The Hardware Stack window displays the contents of the hardware stack. The number of available levels depends on the selected device. Note: If Disable Stack Overflow Warning is cleared, MPLAB IDE will display stack overflow and underflow warnings when they occur. This is not supported on all processor modules. • Hardware Stack Window Display • Hardware Stack Window Menu • Hardware Stack Window FAQ 12.7.
MPLAB IDE Windows 12.7.3 Hardware Stack Window FAQ How do I: Understand the Return Address information? See Section 12.7.1 “Hardware Stack Window Display” Pop the stack? Click on the right mouse button in the window to open a menu. Select Pop Stack. Set Top-of-Stack (TOS)? Click on the right mouse button in the window to open a menu. Select Set Top-of-Stack. 12.8 PROGRAM MEMORY WINDOW The Program Memory window displays locations in the range of program memory for the currently selected processor.
MPLAB® IDE User’s Guide • Label (Symbolic Only) – Opcode label in symbolic format. • Disassembly – A disassembled version of the opcode mnemonic. 12.8.1.3 PSV MIXED (dsPIC DSC/PIC24 DEVICES ONLY) This format displays program memory as opcode and the PSV area (CORCON register, PSV bit set). The window will have the following columns: • Debug Info – Information useful for debugging. A pointer shows the current location of the program counter. • Line – Reference line number.
MPLAB IDE Windows Center Debug Location Center the current PC line in the window. Cursor Tracks Debug Location Cursor (arrow) will track the current debug location. Find Find text specified in the Find dialog in this window. Find Next Find the next instance of Find text. repeats the last Find. + reverses the direction of the last Find. Go To Go to the specified item of the Go To dialog. (See Section 13.14 “Go To Dialog”.) Import Table Open the Import dialog (see Section 13.
MPLAB® IDE User’s Guide Fill program memory with a value? Right click in the window and select “Fill Memory” to open a dialog where you may enter fill data. Set a breakpoint? See Section 6.4 “Breakpoints”. 12.9 FILE REGISTERS WINDOW The File Register window displays all the file registers of the selected device. When a file register value changes, or the processor is interrogated, the data in the File Register window is updated. Note: To speed up debugging with certain hardware tools, close this window.
MPLAB IDE Windows 12.9.1.3 XY DATA (dsPIC DSC DEVICES ONLY) This format displays file register information as hex data. The window will have the following columns: • • • • Address – X hexadecimal address of the data. Y Bus – Y hexadecimal address of data, if supported. Data Blocks – Hexadecimal data, shown in 2-byte blocks. ASCII – ASCII representation of the corresponding line of data. For more information on dsPIC DSC devices, see “dsPIC30F Family Reference Manual” (DS70046). 12.9.
MPLAB® IDE User’s Guide Properties Select background colors for SRFs and unallocated memory. Also, set up generic window properties (see Section 13.21 “Properties Dialog”). 12.9.3 File Registers Window FAQ How do I: Fill all registers with a value? Right click in the window and select “Fill Registers” to open a dialog where you may enter fill data. 12.10 EEPROM WINDOW The EEPROM window displays EEPROM data for any microcontroller device that has EEPROM data memory (e.g., PIC16F84A).
MPLAB IDE Windows Export Table Open the Export As dialog (see Section 13.10 “File Management Dialog”). Fill Memory Fill memory from Start Address to End Address with the value in Data. See Section 13.11 “Fill Memory/Registers Dialog”. Output to File Write the displayed window contents to a text file. Uses a Save As dialog (see Section 13.10 “File Management Dialog”), with the addition of an “Output Range”.
MPLAB® IDE User’s Guide 12.11 MEMORY USAGE GAUGE This window displays the amount of program and data memory currently being used in the active project. Note: You must use the linker to generate your code for this gauge to work, i.e., a *.cof or *.elf debug file must be generated. percentage of memory used units* used units* available bytes used bytes available *Program memory units are dependent on device, e.g., words for the PIC16F877A, bytes for the PIC18F8720.
MPLAB IDE Windows 12.12.1 LCD Pixel Window Display For devices that support LCD output, you can view results of this by selecting View>LCD Pixel. • LCD display area LCD disabled: all LCD pixels will be background gray color LCD enabled: off (‘0’) LCD pixels will appear white and on (‘1’) LCD pixels will appear dark gray Note: You will have to enable LCD functionality through an LCD control register bit (e.g., for PIC16C924, set LCDCON register bit 7 (LCDEN) to ‘1’). Consult your device data sheet.
MPLAB® IDE User’s Guide Output to File Write the displayed window contents to a text file. Print Print the contents of the window. Refresh Refresh the data in this window. Properties Set up window properties. See Section 13.21 “Properties Dialog”. 12.12.3 LCD Pixel Window FAQ How do I: Enable LCD operation? Consult your device data sheet to determine the LCD control registers needed to set up LCD functionality (e.g., for PIC16C924, set LCDCON register bit 7 (LCDEN) to ‘1’ to enable).
MPLAB IDE Windows • Additional Columns – Hex, Decimal, Binary, Char You may add radix information to the display by right clicking on the column header bar. Variables may be rearranged using drag-and-drop. Window information may be sorted by column. Simply click on the column header to sort data according to that column. 12.13.2 Locals Window Menu Below are the menu items in the Locals window right mouse button menu. Close Close this window. Find Find text specified in the Find dialog in this window.
MPLAB® IDE User’s Guide 12.14 WATCH WINDOW The Watch window allows you to monitor program symbols while running your program. Up to four different watches may be set up on different tabs of this window. For more information on using this window, see Section 6.3 “Watch Window”. • Watch Window Display • Watch Window Menu • Watch Window FAQ 12.14.1 Watch Window Display Select any one of four Watch views by clicking on one of the tabs on the bottom of the window, i.e., Watch 1, Watch 2, Watch 3 or Watch 4.
MPLAB IDE Windows Save Watch Tab Save the contents of the currently selected Watch tab to a file. Load Watch Tab Load the contents of a file containing previously saved Watch information into the currently selected tab. Add Watch Tab Add a Watch tab to the Watch window. You can have as many as 16 Watch tabs. Rename Watch Tab Rename the currently selected Watch tab. Remove Watch Tab Remove the currently selected Watch tab. You can have no fewer than four Watch tabs. Import Table Save Watch data to a table.
MPLAB® IDE User’s Guide Load a previously saved Watch window? Click the right mouse button in the window to open a menu. Select Load Watch to load a previously saved watch into the currently selected watch. Or, select Import to load Watch values. Change the order of watch items? Simply drag-and-drop items where you want them in the watch list. Watch a single bit from a register? Set the variable format to binary. See Section 13.30 “Watch/Locals Dialog”.
MPLAB IDE Windows 12.16.1 SFRs Window Display Data is displayed in the following columns. • • • • • • Address – SFR hexadecimal address. SFR Name – Symbolic name for the SFR. Hex – Hexadecimal value, shown in 1-byte blocks. Decimal – Value in decimal format. Binary – Value in binary format. Char – Value in character format. 12.16.2 SFRs Window Menu Below are the menu items in the Special Function Registers right mouse button menu. Close Close this window.
MPLAB® IDE User’s Guide 12.16.3 SFRs Window FAQ How do I: Fill all registers with a value? Right click in the window and select “Fill Registers” to open a dialog where you may enter fill data. 12.17 TRACE MEMORY WINDOW The Trace memory window (under the View menu) helps you to monitor much of the processor operation. The Trace buffer is shared with the logic analyzer. To enable the tracing of all executing program lines to the Trace buffer, check the checkbox Debugger>Settings, Trace tab, Trace All.
MPLAB IDE Windows Source Code Pane Corresponding source code may be viewed in the lower portion of the Trace memory window by selecting “Show Source” from the Trace memory menu. Drag the window bar dividing the trace and source code to resize each portion. The source code may not be edited in this window. 12.17.2 Trace Window Menu Below are the menu items in the Trace memory right click menu. Close Close this window. Find Opens the Find dialog.
MPLAB® IDE User’s Guide Output to File Export the contents of the trace memory window to a file. Uses a Save As dialog (see Section 13.10 “File Management Dialog”), with the addition of cycle and tab information. Enter a “Start” and “End” cycle to write to the file. Also specify if the text is to be tab-delimited. Print Print the contents of the trace memory window. Refresh Refresh the viewable contents of the window. Properties Set up window properties. See Section 13.21 “Properties Dialog”. 12.17.
MPLAB IDE Windows Window Controls • Trigger Position – Three radio buttons allow you to specify where the trigger is to occur: at the start of capture, in the center of capture, or at the end of capture. • Trigger PC = – There are two methods of triggering the data capture. - Trigger PC = value – Trigger on value entered in text box. - Trigger Now – Trigger on clicking of this button. Current PC value is placed in the text box. - Trigger Clear – Clears the trigger value and data buffers for a new capture.
MPLAB® IDE User’s Guide Import/Export Table Import from or export to a logic data file. 12.18.3 Logic Analyzer FAQ How do I: Add a signal to the logic analyzer display? Click Channels and add the signal name, found under “Available Signals”. You may choose from individual pins or buses. Buses, or groups of pins, can be created by clicking Configure Bus(es). Click OK to see the signal appear on the logic analyzer display as a channel. For more information, see: • Section 13.
MPLAB IDE Windows For more information, see Section 6.2 “Configuration Bits”. • Configuration Bits Window Display • Configuration Bits Window Menu • Configuration Bits Window FAQ 12.21.1 Configuration Bits Window Display Selecting Configure>Configuration Bits opens the Configuration Bits window. Use this window to set Configuration bit values for your selected device. Note: These values are obtained when building a source file and are used to control the operation of the debug tool.
MPLAB® IDE User’s Guide Develop with Configuration bits set in code? To use only Configuration bits in code, i.e., initialization data, to develop your application: • Do not change any Configuration bit settings in the Configuration Bits window. • Configure>Settings, Program Loading tab, “Clear program memory upon loading a program” should be checked. 12.22 FILE (EDITOR) WINDOW A File window contains the source code for your application.
MPLAB IDE Windows Add Filter-in Trace Add filter-in trace tags on selected code text. See Section 15.5 “Working with Debug Features”. Close Close active window. Set/Remove Breakpoint Set or remove a breakpoint at the currently selected line. Enable/Disable Break Enable or disable a breakpoint at the currently selected line. Breakpoints Disable, enable or remove all breakpoints. Run to Cursor Run the program to the current cursor location. Formerly Run to Here.
MPLAB® IDE User’s Guide Advanced Set advanced text features. Make selected text all uppercase or lowercase, a comment or not a comment, indented or outdented or match it if a brace, bracket or parenthesis. Bookmark Manage bookmarks. Toggle (enable/disable) a bookmark, move to the next or previous bookmarks or clear all bookmarks. See MPLAB Editor on-line help for more on bookmarks. Code Folding For Code Folding enabled (Section 15.2.
MPLAB® IDE USER’S GUIDE Chapter 13. MPLAB IDE Dialogs 13.1 INTRODUCTION MPLAB IDE dialog boxes behave as normal Windows applications. The basic dialogs available in MPLAB IDE are listed below. Depending on the tools you have installed, other dialogs may be available.
MPLAB® IDE User’s Guide 13.2 ABOUT MPLAB IDE DIALOG Select Help>About MPLAB IDE to open the About MPLAB IDE dialog. This is an informational dialog. • Click the link “MPLAB Development Software Webpage” to go to the Microchip development tools webpage for software. • Click Copy to copy the Version Information to the PC clipboard. • Click OK to close the dialog.
MPLAB IDE Dialogs 13.4 BREAKPOINTS DIALOG Select Debugger>Breakpoints to open the Breakpoints dialog. You must select a debug tool before this option is available on the Debugger menu. Note: There are other ways to set breakpoints. See Section 6.4 “Breakpoints”. Dialog Description Break At: Enter the source code line number or address of a breakpoint. Hit to place the breakpoint in the list below. Program Memory Breakpoints List of breakpoints set in program memory.
MPLAB® IDE User’s Guide Fix unresolved breakpoints If you have set a breakpoint on a line of high-level language code (e.g., C code) that cannot be resolved (into assembly code), you will get a warning message. Also, in the breakpoint dialog, a yellow question mark will appear next to the unresolved breakpoint. Often optimized code will cause this problem. Rebuild your application without optimizing and try the breakpoint again.
MPLAB IDE Dialogs 13.6 CONFIGURE CHANNEL DIALOG Select pin and/or bus signals to be used by the Logic Analyzer window (see Section 12.18 “Logic Analyzer Window”). Pin signals show changes on individual pins. Bus signals show changes (in Hex) for multiple pins, as for a port. Each signal chosen will be given its own channel in the Logic Analyzer display. To add signals to a channel: • Select the type of signal to add from the pull down list: pin, bus or both.
MPLAB® IDE User’s Guide 13.8 EXPORT HEX FILE DIALOG The Export Hex File dialog is available from File>Export. Use Export to save program memory, a section of program memory, EEPROM memory, Configuration bits or user ID to a .hex file. There are two formats allowed. The INHX32 format should be used for most purposes. The INHX8S format saves the memory area as two files: one for the even bytes and one for the odd bytes.
MPLAB IDE Dialogs 13.10 FILE MANAGEMENT DIALOG A file management dialog allows you to manage source and project files. The types of file management dialogs in MPLAB IDE are: Input • Open dialog – Open an existing file, project or workspace or import an existing debug file. • Add Files to Project dialog – Insert source files into your project. • Import dialog – Import tabular data from a file into a memory window.
MPLAB® IDE User’s Guide 13.11 FILL MEMORY/REGISTERS DIALOG To fill memory with a value, right click in one of the windows below and select “Fill Memory”. • Section 12.8 “Program Memory Window” • Section 12.10 “EEPROM Window” To fill registers with a value, right click in one of the windows below and select “Fill Registers”. • Section 12.9 “File Registers Window” • Section 12.16 “Special Function Registers Window” Enter a “Start Address” and an “End Address” as the fill range.
MPLAB IDE Dialogs Examples POSIX [[:upper:]]TEMP RE Description [A-Z]TEMP Find and note all occurrences of strings beginning with letters A through Z and ending in TEMP, such as ATEMP, MTEMP or ZTEMP. register[^[:digit:]] register[^0-9] Find and note all occurrences of the string register that does not end in numbers 0 through 9, such as registerA. \( Find and note all occurrences of the left parenthesis. \( 13.
MPLAB® IDE User’s Guide 13.15 HELP TOPICS DIALOG Select Help>Topics to open the MPLAB IDE Help Topics dialog. Use this dialog to select a help file to display. Help files are arranged according to the type of development tool they describe, i.e., System, Language Tools, Debuggers, Programmers and (Other) Tools. You may only select one help file to open. Double click on your selection or click to select and then click OK to open the help file. Click Cancel to close the dialog without opening a help file.
MPLAB IDE Dialogs 13.19 PROJECT-DISPLAY PREFERENCES DIALOG Right click in an empty area of the Project Window and select Preferences from the pop-up menu to display the Project-Display Preferences dialog. Use this dialog to set preferences for the Project window. Dialog Description Display Project Nodes As Select how you want project file types displayed on the project tree, either as simply names, or names with paths.
MPLAB® IDE User’s Guide To Change Column Width • Make the window active. • Move the cursor over the line between columns until it changes to the resize cursor • Click and drag to widen or narrow the column. To Restore Default Settings • Click Defaults. 13.21.2 General Tab Set up the font and change color for all debug windows, i.e., what you set up here will globally determine settings for all debug (View menu) windows.
MPLAB IDE Dialogs 13.23 SELECT DEVICE DIALOG To choose a device for development, select Configure>Select Device to open the Select Device dialog. Dialog Description Device All devices currently supported by this version of MPLAB® IDE will be listed here. Select from the list or start typing in a device name. Device Family To narrow the list of devices under “Device”, select a grouping from “Device Family”. Selecting “ALL” will cause all supported devices to be listed.
MPLAB® IDE User’s Guide 13.24 SELECT LANGUAGE TOOLSUITE DIALOG Select Project>Select Language Toolsuite to open the Select Language Toolsuite dialog. You must have a project open before this option is selectable on the Project menu. Use this dialog to select the suite of language tools you will use in your project. See documentation for the language tools to ensure that they support the device you will be using. • Active Toolsuite – Select the toolsuite you will use.
MPLAB IDE Dialogs 13.26.1 Workspace Tab Select Configure>Settings and click the Workspace tab to set up Workspace options. A workspace contains information on the selected device, debug tool and/or programmer, open windows and their location and other IDE configuration settings. Option Description Automatically save workspace upon closing To automatically save the contents of an active workspace when closing MPLAB® IDE, select Yes. To not save the contents, select No.
MPLAB® IDE User’s Guide What Memory is to be Cleared Option Description Clear program memory upon loading a program Clear/Don't clear program memory on program load.Uncheck when using concurrent projects. Clear configuration bits upon loading a program Clear/Don't clear Configuration bit values on program load. Clear EE data upon loading a program Clear/Don't clear EEPROM data memory on program load. Clear user ID upon loading a program Clear/Don't clear the user ID value on program load. 13.26.
MPLAB IDE Dialogs E.g., Hot keys are assigned to an MPLAB ICD 2 debugger command and an MPLAB PM3 programmer command. However, MPLAB ICD 2 is not enabled when the keys are assigned, but MPLAB PM3 is. Therefore, only the MPLAB PM3 command would be applied. If both MPLAB ICD 2 and MPLAB PM3 are enabled, only the command first encountered in the hot key table will be applied. Note: Assigning a hot key to a command does not remove any prior command assignments of that hot key. 13.26.
MPLAB® IDE User’s Guide 13.27 TABLE SETUP DIALOG Right click in a window and select “Import Table” or “Export Table” to open the Table Setup dialog. Import or Export data from or to a table file. Export SFR/Symbol/Variable values to a file and then import them back as needed. Related windows/dialogs are: • • • • Section 12.13 “Locals Window” Section 12.14 “Watch Window” Section 13.3 “Add Watch Dialog” Section 13.
MPLAB IDE Dialogs 13.29 VERSION CONTROL DIALOG Select Project>Version Control to open the Version Control dialog. Set up your MPLAB IDE Project to use a version control system (VCS). • Version Control System – Select an available version control system from the drop-down list. • System – Set up the necessary parameters to use your selected VCS, if required. • For Project “project.mcp” – Set up the necessary project information for project project.mcp. For more on version control systems, see Section 4.
MPLAB® IDE User’s Guide Microsoft Visual SourceSafe For Project “project.mcp” Description SRCSAFE.INI file Specify the path to and name of the Visual SourceSafe initialization file for the database you will be using, e.g., C:\VSS\VSS_6.0\win32\scrsafe.ini. Click Browse to locate the file. VSS project path Specify the path within Visual SourceSafe to the project files, e.g., $/Project Files/Project2.
MPLAB IDE Dialogs 13.30.2 Preferences Tab This tab is used to select default settings for new symbols added to the window. Setting Description Float Format Select a floating-point format. • Use COFF float type – Use the information in the COFF file. This is the default. • IEEE 754 32-bit – Use with MPLAB® C18 (v2.40 and later), MPLAB C30 and HI-TECH ‘C’ with -D32x. • IEEE Modified 24-bit – Use with HI-TECH ‘C’ compilers with -D24x. • Microchip High:Low – Use with MPLAB C18 compilers before v2.40.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 182 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 14. MPLAB IDE Operational Reference 14.1 INTRODUCTION Reference information about the operation of MPLAB IDE is discussed here. • • • • 14.2 Command-Line Options Files Used by MPLAB IDE Saved Information File Locations COMMAND-LINE OPTIONS MPLAB IDE can be invoked through the command-line interface as follows: mplab [file] [/option] file = workspace.mcw Open the workspace workspace.mcw in MPLAB IDE. Any projects contained in the workspace will be opened also.
MPLAB® IDE User’s Guide TABLE 14-1: MPLAB® IDE DEFAULT EXTENSIONS (CONTINUED) Extension 14.
MPLAB IDE Operational Reference Registry The following information is saved in the registry file of the Windows OS: • • • • Language tool names and installation locations. Most items on the Configure>Settings, Workspace tab. All items on the Configure>Settings, Projects tab. Information on items that may be made visible/invisible in windows, e.g., columns, split windows, etc. INI Files The following information is saved in initialization (.ini) files: • Editor settings in the mpeditor.ini file.
MPLAB® IDE User’s Guide • • • • Promate II – PRO MATE II help and support files, and firmware. Readmes – Readme files for all tools. Simulator – MPLAB SIM help and support files. Utilities – Utilities for MPLAB IDE, including the USB driver preinstaller and cleaner, MPLAB ICE 4000 firmware updater (automatically run by MPLAB IDE if detected out-of-date), and the documentation viewer (Help>Version Notes). • VDI – Visual Device Initializer help and support files. MPLAB IDE Common Initialization files.
MPLAB® IDE USER’S GUIDE Part 4 – MPLAB Editor Chapter 15. Using the Editor..................................................................................... 189 © 2006 Microchip Technology Inc.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 188 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 15. Using the Editor 15.1 INTRODUCTION The MPLAB Editor is an integrated part of the MPLAB IDE Integrated Development Environment. The editor is always available when MPLAB IDE is running. The MPLAB IDE and MPLAB Editor are designed to provide developers with an easy and quick method to develop and debug firmware for Microchip Technology’s PICmicro microcontroller (MCU) and dsPIC digital signal controller (DSC) product families.
MPLAB® IDE User’s Guide 15.2 CONFIGURING THE EDITOR The editor may be configured using two dialogs: • Editor Options Dialog • Editor Color Customization Dialog 15.2.1 Editor Options Dialog You can set editor properties in the Editor Options dialog. Select Edit>Properties or right click in a file (editor) window and selecting Properties. • Editor Tab • Text Tab • Sizes Tab 15.2.1.1 EDITOR TAB Set up editor properties using the Editor tab on the Editor Options dialog as shown in Table 15-1.
Using the Editor 15.2.1.2 TEXT TAB Set up text properties using the Text tab on the Editor Options dialog. 15.2.1.2.1 Fonts • Select Font – Click to select the editor font. For Unicode-enabled operating systems only: In the National Language Code Page: field, select the value to be used to translate from Unicode text to ANSI. 15.2.1.2.2 Colors • Choose Colors – Click to select the context-sensitive colors in the Editor Color Customization Dialog. Determine the context under Text Mode.
MPLAB® IDE User’s Guide 15.2.2 Editor Color Customization Dialog You can set color options to be used by the editor in the Editor Options dialog, Text tab. The colors will be used for all files which will be opened subsequently having the same syntax type as the currently active source file. The color change dialog contains a list of specific symbol types which have their own coloring. The meaning of each kind of symbol type depends on the kind of file being colored.
Using the Editor 15.3 WORKING WITH FILES The following editor features are available for working with files: • • • • • • • Creating a New File Opening Files Printing Files Saving Files Closing Files Syntax Type Using Bookmarks 15.3.1 Creating a New File To create a new file: 1. Click the New File icon, select New from the File menu or press + . 2. A new window will open named “Untitled”. This is your new file. To give it the name you want it to have, select File>SaveAs. 15.3.
MPLAB® IDE User’s Guide 15.3.5 Closing Files There are several ways of closing a file, as shown below: • From the File Menu: - Make sure the window containing the file you want to close is the active window. - From the File menu, select Close. If the file has changed since it was saved last, you will be prompted to save your changes. • From the System Button on the file window, select Close. • Click the Close Button on the file window.
Using the Editor 15.4 WORKING WITH TEXT The following editor features are available for working with text: • • • • • • • • • • • • Selecting Text Moving to a Specific Line Cutting/Deleting Text Copying Text Pasting Text Finding Text Replacing Text Matching Braces Undoing Editor Actions Redoing Editor Actions Indent and Outdent Formatting Text 15.4.1 Selecting Text To select any block of characters: • With the mouse: - Click the mouse at one end of the text you wish to select.
MPLAB® IDE User’s Guide 15.4.2 Moving to a Specific Line No matter where the cursor is in a file, you can quickly move it to any line that you specify. To move to a specific location in the active window: 1. Select Goto Line from the Edit menu or press + . A Goto Line dialog displays. 2. Enter the line number in the dialog and click the OK button. The editor will move the cursor to the specified line and scroll to display the line, if necessary. Note: 15.4.
Using the Editor 15.4.5 Pasting Text You can paste any text contained in the Windows clipboard into a file in the MPLAB Editor. You can paste text that you have copied from the same file or from another application. Text must exist in the Windows clipboard before it can be pasted. To paste text from the Windows clipboard: 1. Move the caret to the point where you want to insert the text. 2. Click the Paste icon, select Paste from the Edit menu, press + or press + . Note: 15.4.
MPLAB® IDE User’s Guide 15.4.7 Replacing Text To find and replace text in a file: 1. Make sure the file you want to edit is open in the active window. 2. From the Edit menu, select Replace or press + . 3. If you selected text in the file before opening the Replace dialog, that text is displayed in the “Find What” field. If the text you want to replace is not displayed in the “Find What” field, enter the text you want replace. 4. In the “Replace With” field, enter the replacement text. 5.
Using the Editor 15.4.11.1 INDENTING Tabs or spaces will be inserted as specified in the Editor Options dialog. Single line 1. Move the caret to the start of the line you want to indent. 2. Make sure the editor is in Insert mode 3. Press once for each level you want to indent the line. Auto Indent New line automatically indented like the previous line. Block of lines 1. Select the lines in the block you want to indent. 2. Press once for each level you want to indent the lines in the block. 15.4.
MPLAB® IDE User’s Guide 15.5 WORKING WITH DEBUG FEATURES When a debugger is selected in MPLAB IDE, several code debugging features are available in the editor window. • Filter Trace • Breakpoints 15.5.1 Filter Trace You may set up a simple filter trace in the editor window. However, the debug tool trace feature must not be enabled to do this. Also, Filter-in and Filter-out trace are mutually exclusive, i.e., setting one will clear the other.
Using the Editor 15.6 KEYBOARD FEATURES The following keys are specified for the editor: • Shortcuts • Movement and Selection • Special Characters 15.6.1 Shortcuts The following keyboard shortcuts are available for the editor. To change shortcut key assignments, use Configure>Settings, Hot Keys tab. 15.6.1.
MPLAB® IDE User’s Guide 15.6.2 Movement and Selection The keyboard keystrokes shown in Table 15-2 may be used when editing text.
Using the Editor 15.7 EDITOR TROUBLESHOOTING This section is designed to help you troubleshoot any problems, errors or issues you encounter while using MPLAB Editor. 15.7.1 Common Problems/FAQ Some items in the context menu are disabled. Depending on your selection of debug and/or programmer tools, some items may not be applicable and so are grayed. Nothing happens when I press + . The text cursor must be on an opening/closing symbol when you press + .
MPLAB® IDE User’s Guide NOTES: DS51519B-page 204 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Part 5 – MPLAB SIM Chapter 16. Simulator Overview ............................................................................... 207 Chapter 17. Getting Started with MPLAB SIM ......................................................... 223 Chapter 18. Using Stimulus ...................................................................................... 229 Chapter 19. Using Stimulus – PIC17 Devices .......................................................... 241 Chapter 20.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 206 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 16. Simulator Overview 16.1 INTRODUCTION MPLAB SIM is a discrete-event simulator for: • PICmicro microcontroller (MCU) families • dsPIC Digital Signal Controller (DSC) families The simulator is integrated into MPLAB IDE integrated development environment. The MPLAB SIM debugging tool is designed to model operation of Microchip Technology's MCU and DSC devices to assist in debugging software for these devices.
MPLAB® IDE User’s Guide Program memory, or core, instruction length is used to group PICmicro MCUs. Data memory is 8-bit for these devices. At the time this documentation was produced, the following cores are associated with the listed devices: • • • • 12-bit Core – PIC12C5XX, PIC12CE5XX, PIC16X5X, PIC16C505 14-bit Core – PIC12C67X, PIC12CE67X, PIC12F629/675, PIC16 16-bit Core – PIC17 16-bit Core – PIC18 The 12-bit, 14-bit and 16-bit (PIC17) core devices have word-addressed program memory space.
Simulator Overview 16.3.2 12-Bit Core Device Simulation The following topics discuss the 12-bit core device features modeled in the simulator. • 12-bit Core CPU • 12-bit Core Peripherals 16.3.2.1 12-BIT CORE CPU Reset Conditions All Reset conditions are supported by the MPLAB SIM simulator. The Time-out (TO) and Power-down (PD) bits in the STATUS register reflect appropriate Reset condition. This feature is useful for simulating various power-up and time-out forks in your code.
MPLAB® IDE User’s Guide 16.3.3 14-Bit Core Device Simulation The following topics discuss the 14-bit core device features modeled in the simulator. • 14-bit Core Interrupts • 14-bit Core CPU • 14-bit Core Peripherals 16.3.3.1 14-BIT CORE INTERRUPTS The following interrupts are supported: • • • • • • • • • • Timer0 overflow Timer1 overflow Timer2 CCP1 CCP2 Change on Port RB <7:4> External interrupt from RB0/INT pin Comparators A/D complete EEPROM write complete 16.3.3.
Simulator Overview A WDT time-out is simulated when WDT is enabled, proper pre/postscaler is set and WDT actually overflows. On WDT time-out, the simulator will halt or Reset, depending on the selection in the Break Options tab of the Settings dialog. 16.3.3.3 14-BIT CORE PERIPHERALS Along with core support, MPLAB SIM supports the following peripheral modules, in addition to general purpose I/O.
MPLAB® IDE User’s Guide A/D Converter (Limited) All the registers, timing function and interrupt generation are implemented. The simulator, however, does not load any meaningful value into the A/D result register (ADRES) at the end of a conversion.To load meaningful data, use an injection file (see Section 18.2.5 “Register Injection”). A read of the A/D register will load this data into the register.
Simulator Overview 16.3.4.2 16-BIT CORE (PIC17) CPU Reset Conditions All Reset conditions are supported by the MPLAB SIM simulator. The Time out (TO) and Power-Down (PD) bits in the CPUSTA register reflect appropriate Reset condition. This feature is useful for simulating various power-up and time-out forks in the user code. A MCLR Reset during normal operation or during Sleep can easily be simulated by driving the MCLR pin low (and then high) via stimulus.
MPLAB® IDE User’s Guide Timer0 Timer0 and the interrupt it can generate on overflow is fully supported, and will increment by the internal or external clock. Delay from external clock edge to timer increment has also been simulated, as well as the interrupt latency period. Clock input must have a minimum high time of 1 TCY and a minimum low time of 1 TCY due to the stimulus file requirements. Timer1 and Timer2 Timer1 and Timer2 in its various modes is fully supported.
Simulator Overview 16.3.5.2 16-BIT CORE (PIC18) CPU Reset Conditions All Reset conditions are supported by the MPLAB SIM simulator. The Time out (TO) and Power-Down (PD) bits in the RCON register reflect appropriate Reset condition. This feature is useful for simulating various power-up and time-out forks in the user code. You cannot Reset by toggling MCLR using stimulus control. You must use Debugger> Reset>MCLR Reset.
MPLAB® IDE User’s Guide 16.3.5.4 16-BIT CORE (PIC18) PERIPHERALS Along with core support, MPLAB SIM supports the following peripheral modules, in addition to general purpose I/O: • • • • • • Timers CCP/ECCP Comparators (Limited) A/D Converter (Limited) USART EEPROM Data Memory The delays are implemented on all peripherals, but the interrupt latency is not. Timers Timer0 (and the interrupt it can generate on overflow) is fully supported, and will increment by the internal or external clock.
Simulator Overview A/D Converter (Limited) All the registers, timing function and interrupt generation are implemented. The simulator, however, does not load any meaningful value into the A/D result registers (ADRES) at the end of a conversion.To load meaningful data, use an injection file (see Section 18.2.5 “Register Injection”). A read of the A/D registers will load this data into the registers.
MPLAB® IDE User’s Guide 16.3.6.2 SYSTEM INTEGRATION BLOCK Reset Sources All Reset sources are supported by the MPLAB SIM simulator. Status bits from the RCON register are set or cleared differently in different Reset situations, as indicated in device data sheet. These bits are used in software to determine the nature of the Reset.
Simulator Overview 16.3.6.4 PERIPHERALS MPLAB SIM supports the following peripherals: • • • • • • • • • • Input Capture/Output Compare Change Notify Interrupts OSC control of IO Timers Ports Comparators PWM A/D Converter (Limited) UART (Limited) The delays are implemented on all peripherals, but the interrupt latency is not. A/D Converter (Limited) All the registers, timing function and interrupt generation are implemented.
MPLAB® IDE User’s Guide 16.4 SIMULATOR EXECUTION MPLAB SIM operation is specified in the following topics. • Execution Speed • Execution on Instruction Cycle Boundaries • I/O Timing 16.4.1 Execution Speed When MPLAB SIM is simulating running in real time, instructions are executing as quickly as the PC's CPU will allow. This is usually slower than the actual device would run at its rated clock speed.
Simulator Overview The following functions and peripherals are affected by simulation on instruction cycle boundaries: Note: Not all peripherals listed here are currently supported by the simulator. • Clock pulse inputs smaller than one cycle cannot be simulated even though timer prescalers are capable of accepting clock pulse inputs smaller than one cycle. • PWM output pulse resolution less than one cycle is not supported. • Compares greater than 8 bits are not supported.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 222 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 17. Getting Started with MPLAB SIM 17.1 INTRODUCTION If you are new to MPLAB IDE and the simulator, please refer to the tutorials in the MPLAB IDE documentation to help you set up MPLAB IDE for use with MPLAB SIM. Select Help>Topics and then “MPLAB IDE Help” in the dialog, or click the link below (and then “Open” if a security dialog appears).
MPLAB® IDE User’s Guide 17.5 USING THE STOPWATCH The stopwatch is useful for simple timing between program halts. Reach this dialog from Debugger>Stopwatch. Instruction Cycles and Time The simulator updates the “Instruction Cycles” and “Time” fields, including the Time units, as your program runs. PICmicro MCUs and dsPIC30F/PIC24F devices use 4 clock cycles per instruction to calculate time. dsPIC33F/PIC24H devices use 2 clock cycles per instruction to calculate time.
Getting Started with MPLAB SIM 17.7.1 PIC18F MCU USART Example – Setup Follow the steps below to set up the example. 1. Example code for demonstrating USART operation in the simulator is based on code found on the Microchip website under “PICDEM™ 2 example code” as “USART demo for the 18CXXX” (usart.asm). The updated code (usart2.asm) is listed in Section 17.7.4 “Updated PICDEM 2 Example Code”. 2. In MPLAB IDE, use the Project Wizard to create a project. - Select PIC18F452 as the device.
MPLAB® IDE User’s Guide 17.7.3 PIC18F MCU USART Example – SCL Stimulus To use SCL Stimulus input to simulate USART/UART operation, follow the steps below. Note: “Enable UART1 I/O” must be unchecked on the UART IO tab, Settings dialog (Debugger>Settings) or this method will not work. 1. Once the project is completed, you will need an input file to simulate USART signal input. - Select File>Open to open an editor window. - Enter message-based data for RCREG input (see Section 18.2.5.
Getting Started with MPLAB SIM ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION.
MPLAB® IDE User’s Guide bsf TXSTA,BRGH ; Select high baud rate bsf bsf RCSTA,SPEN RCSTA,CREN ; Enable Serial Port ; Enable continuous reception bcf bsf bsf bsf PIR1,RCIF PIE1,RCIE INTCON,PEIE INTCON,GIE ; ; ; ; Clear RCIF Interrupt Flag Set RCIE Interrupt Enable Enable peripheral interrupts Enable global interrupts ;************************************************************ ; Main loop Main goto Main ; loop to self doing nothing ;************************************************************ ;
MPLAB® IDE USER’S GUIDE Chapter 18. Using Stimulus 18.1 INTRODUCTION During simulation, the program being executed by the simulator may require stimuli from the outside. This stimulus could be a level change or a pulse to an I/O pin of a port. It could be a change to the values in an SFR (Special Function Register) or other data memory. In addition, stimulus may need to happen at a certain instruction cycle or time during the simulation.
MPLAB® IDE User’s Guide 18.2 SCL GENERATOR DIALOG Use the SCL Generator dialog to create synchronous stimulus using the behind-the-scenes, powerful Simulator Control Language (SCL). If you want to use only asynchronous stimulus, you may go directly to the Stimulus Controller Dialog to set this up. Otherwise, create the SCL stimulus file here, and then go to the Stimulus Controller dialog to attach it.
Using Stimulus SFR Values As Triggers Triggers and traces will ONLY occur when the SFR is updated by the user, not the peripheral. For example, the trigger dialog is set up to fire when TMR2 = 0x06. When TMR2 is incremented past 0x06, the trigger will not fire. However, if the following sequence is executed in user code: MOVLW 0X06 MOVWF TMR2 then the trigger will occur. 18.2.1 Pin/Register Actions Basic synchronous pin and/or register actions may be entered here.
MPLAB® IDE User’s Guide When h:m:s is chosen, values input in the Time column will have the following meanings: • • • • • • • 1 – means 1 second 1:00 – means 1 minute 60 – becomes 1:00 999 – becomes 16:39 9999999 – becomes 2777:46:39 1:5 – becomes 1:05 60:5 – becomes 1:00:05 The time value range is 0 to (2^31 – 1) seconds. Anything outside this range will be changed to the default (0 for the first tab and re-arm delay; 1 for the condition wait).
Using Stimulus As an example, set up a condition, COND1, such that when the value of register PORTC equals FF, stimulus defined in “Define Triggers” is applied 10 ms later. Note: If PORTC has an initial value of FF, or never changes to FF, the condition will never be met and no stimulus will be applied. EXAMPLE 18-1: 18.2.2.
MPLAB® IDE User’s Guide For the condition set up in the previous example, COND1, set up the following stimulus trigger: 1. Make the pin RB0 high for the first instance of the condition. 2. Wait 10 instruction cycles and check for the condition again. If and when it occurs, make pin RB0 high again. 3. Repeat step 2 until the program is halted. EXAMPLE 18-2: 18.2.2.3 MAKE PIN HIGH ON REGISTER VALUE “DEFINE CONDITIONS” WAIT VS.
Using Stimulus To Change the Order of Signals on the Pin/Register tab: • Click on the signal from the “Selected Signals” list. • Click either Move Up or Move Down to change order of this signal in the list. • Click OK. Its location will now be reflected in the order of the column heads on the associated Pin/Register tab. 18.2.4 Clock Stimulus Pulse (high and low) values applied to a pin is clocked stimulus as shown in Table 18-3. Clocked stimulus may be entered here.
MPLAB® IDE User’s Guide 18.2.5 Register Injection Registers may be injected with values set up in a file (see Table 18-4). Enter information for register injection here. For General Purpose Register injection, more than one byte may be injected (for arrays). Therefore, care must be taken to not overwrite data. TABLE 18-4: DEFINITIONS OF REGISTER INJECTIONS Item Definition Label Name the register injection you are specifying (optional).
Using Stimulus 18.2.5.2 MESSAGE-BASED DATA FILE DESCRIPTION Data in the file will be interpreted in packets as follows: • HEX-style – spaced, separated hexadecimal numbers will be treated as one packet, e.g., 05 07 6A 6B 105 107. Since the UART is 9-bits wide, receive values larger than 0x1FF will be masked off. • RAW-style – text between a pair of quotation characters (") will be treated as one packet, e.g.
MPLAB® IDE User’s Guide EXAMPLE 18-5: REGISTER STIMULUS FILE 2 wait 0 sec 61 62 63 20 6A 62 61 wait 200 ms // the following is equivalent to "the quick brown fox" "the quick brown " "fox" // CR-LF in a packet wait 20 sec 65 66 67 68 13 10 69 70 // 9-bit value in a packet wait 20 sec 165 166 167 168 wait 30 ms // the following is "012mix" 32 33 34 "mix" wait 100 ns // the following blank line is ignored 64 34 33 24 32 34 21 rand 15 20 sec 89 90 91 92 93 94 rand 0 100 min 11 22 33 18.2.
Using Stimulus 18.3 STIMULUS CONTROLLER DIALOG Use the Stimulus Controller dialog to control how stimulus is used by MPLAB SIM. Note: This dialog must be open for stimulus to be active. The Stimulus Controller dialog allows you to set up what stimulus is used and saves this information in a scenario. To open a new scenario, select Debugger>Stimulus Controller>New Scenario. To open an existing scenario for editing, select Debugger> Stimulus Controller >Open Scenario.
MPLAB® IDE User’s Guide 18.4 STIMULUS INPUT INTERACTION If a pin (e.g., RB1) assignment and a port (e.g., PORTB.RB) assignment happen on the same cycle, the port supersedes the pin assignment. But, if they happen on different cycles, you can mix and match pin and port assignment. In addition, you can use PORT injection with pin/port assignment. DS51519B-page 240 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Chapter 19. Using Stimulus – PIC17 Devices 19.1 INTRODUCTION Stimulus functions allow you to direct the simulator to apply artificial stimuli while debugging your code. You can set pins high or low and inject values directly into registers. Select Stimulus from the Debugger menu, then choose the tab for the stimulus type.
MPLAB® IDE User’s Guide Asynchronous Setup a) Click on “Pin” to select or change the pin on which stimulus will be applied. Available pin names are listed. The actual names depend on the device selected in MPLAB IDE. b) Click on “Action” to select or change a stimulus action. You may choose Pulse, High, Low or Toggle. c) Click on “Comments” to specify or change a comment which will be saved and restored in the pin stimulus file.
Using Stimulus – PIC17 Devices 19.2.3 Pin Stimulus Display Select Debugger>Stimulus and then click the Pin Stimulus tab to set up pin stimulus. Closing the Stimulus dialog disables stimulus. Note 1: 2: If any files are changed externally while in use by this dialog tab, the changes will NOT be reflected in the stimuli passed to the simulator. Changing stimulus files outside the Stimulus dialog is NOT recommended. Unsaved changes will be lost without notice when you close this dialog.
MPLAB® IDE User’s Guide • Action Type = Asynch: Pulse: Change the state of the pin to its opposite and return. High: Change the state of the pin to high. Low: Change the state of the pin to low. Toggle: Change to state of the pin to its opposite. Type = Synch: Clock • High cycles – number of cycles high state will be applied for Synch stimulus. • Low cycles – number of cycles low state will be applied for Synch stimulus. • Invert – inverts high and low cycles when checked for Synch stimulus.
Using Stimulus – PIC17 Devices 19.3.1.1 CREATING/EDITING A FILE STIMULUS FILE (.FSTI) A file stimulus file consists of one or more synchronous stimulus files (*.ssti) that will be applied to the simulator. To create a file stimulus file: 1. Create or open one or more synchronous stimulus files in the file list (below the tab). 2. Click Save Setup under File Stimulus. To edit an existing file stimulus file: 1. Click Load Setup under File Stimulus to open an existing file stimulus file. 2.
MPLAB® IDE User’s Guide PC Setup a) Click on “Trig Value” to set the PC address at which the trigger fires. b) From “Pin/Register”, choose the register to which the value in the next column will be applied when the trigger fires. The actual register names available depend on the device selected. Note: Do not choose a pin. It will not work with PC stimulus. Note: You cannot inject file values into port registers, e.g., PORTB. Use pin values. Also, you cannot inject file values into the W register.
Using Stimulus – PIC17 Devices 19.3.3 File Stimulus Display Select Debugger>Stimulus Controller and then click the File Stimulus tab to set up file stimulus. Closing the Stimulus dialog disables stimulus. Note 1: This is only available when the MPLAB SIM tool has been selected from the Debugger menu. 2: If any files are changed externally while in use by this dialog tab, the changes will NOT be reflected in the stimuli passed to the simulator.
MPLAB® IDE User’s Guide Buttons – File Stimulus These buttons enable you to save and restore combined file setups. • Save Setup saves the names of the files currently in the file list into a file. • Load Setup loads the filenames in a file into the file list, just as though you had added them individually. Note: There is currently no way to view the combined contents of a File Stimulus setup. Table Entries • Trigger On – choose between Cycles (Instruction Cycles) and PC (Program Counter).
MPLAB® IDE USER’S GUIDE Chapter 20. Simulator Troubleshooting 20.1 INTRODUCTION This section is designed to help you troubleshoot any problems, errors or issues you encounter while using MPLAB SIM. If none of this information helps you, please see Support for ways to contact Microchip Technology. • Common Problems/FAQ • Limitations 20.
MPLAB® IDE User’s Guide I cannot set conditional breakpoints Conditional breakpoints are not yet implemented. The symbolic breakpoints I set in the Breakpoint dialog do not work This dialog does not recognize symbolic address. However, if you enter a symbol name whose starting characters can be interpreted as a valid hex address, a breakpoint will be set at that address.
MPLAB® IDE USER’S GUIDE Chapter 21. Simulator Reference 21.1 INTRODUCTION Once MPLAB SIM has been selected as the debug tool in MPLAB IDE (Debugger> Select Tool>MPLAB SIM), the following simulator-specific features are available: • Debugging Functions • Settings Dialog • Settings Dialog – PIC17 Devices 21.2 DEBUGGING FUNCTIONS Simulator-specific debug items/functions are added to the following MPLAB IDE features: • • • • Debugger Menu View Menu Right Mouse Button Menus Toolbar and Status Bar 21.2.
MPLAB® IDE User’s Guide 21.2.2 View Menu In addition to the standard MPLAB IDE View menu items, the following items are unique to the simulator: Simulator Trace Display the window containing the current memory trace of your program's execution. For more information, see Section 17.3 “Using Simulator Trace”. Simulator Logic Analyzer Display the logic analyzer for selected signals. For more information, see Section 17.4 “Using the Simulator Logic Analyzer”. 21.2.
Simulator Reference Trace Options To trace all lines of an executing program for display in the trace window (and the related logic analyzer), check the “Trace All” checkbox. To stop program execution when the trace buffer is full, check “Break on Trace Buffer Full”. To see the trace window, select View>Simulator Trace. For more on tracing, see MPLAB IDE documentation on the Trace Memory window. To see the logic analyzer window, select View>Simulator Logic Analyzer.
MPLAB® IDE User’s Guide 21.3.3 SCL Options tab Select Debugger>Settings and then click the SCL Options tab. Set up SCL error screening options. For more on SCL, see Section 18.2 “SCL Generator Dialog”. Messages are displayed as they are generated in the Output window under the MPLAB SIM tab.
Simulator Reference 21.3.6 Limitations tab Select Debugger>Settings and then click the Limitation tab. This dialog presents known MPLAB SIM limitations for the device currently selected (Configure>Select Device). If you want additional information about device limitations, click Details. 21.4 SETTINGS DIALOG – PIC17 DEVICES Select Debugger>Settings to open the Settings dialog. Note: This is only available when the simulator has been selected from the Debugger Menu.
MPLAB® IDE User’s Guide WDT (Watchdog Timer) Options Choose one of the following to determine the simulator behavior when it detects WDT Time-out. • Break On WDT time-out • Reset on WDT time-out Note: 21.4.3 The WDT group is disabled if the WDT is disabled in the Configuration Bits window (Configure>Configuration Bits). Trace/Pins tab Select Debugger>Settings and then click the Trace/Pins tab. • MCLR Pull-up Enabled - If this is checked, MCLR Pull-up will be enabled.
MPLAB® IDE USER’S GUIDE Appendix A. Revision History A.1 REVISION HISTORY Revision A (10/2004) • Initial release of this document.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 258 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Glossary Absolute Section A section with a fixed (absolute) address that cannot be changed by the linker. Access Memory (PIC18 Only) Special registers on PIC18 devices that allow access regardless of the setting of the Bank Select Register (BSR). Address Value that identifies a location in memory. Alphabetic Character Alphabetic characters are those characters that are letters of the arabic alphabet (a, b, …, z, A, B, …, Z).
MPLAB® IDE User’s Guide Breakpoint, Software An address where execution of the firmware will halt. Usually achieved by a special break instruction. Build Compile and link all the source files for an application. C A general purpose programming language which features economy of expression, modern control flow and data structures and a rich set of operators.
Glossary Download Download is the process of sending data from a host to another device, such as an emulator, programmer or target board. DSC See Digital Signal Controller. EEPROM Electrically Erasable Programmable Read Only Memory. A special type of PROM that can be erased electrically. Data is written or erased one byte at a time. EEPROM retains its contents even when power is turned off.
MPLAB® IDE User’s Guide External Symbol A symbol for an identifier which has external linkage. This may be a reference or a definition. External Symbol Resolution A process performed by the linker in which external symbol definitions from all input modules are collected in an attempt to resolve all external symbol references. Any external symbol references which do not have a corresponding definition cause a linker error to be reported.
Glossary IDE Integrated Development Environment. MPLAB IDE is Microchip’s integrated development environment. Import Bring data into the MPLAB IDE from an outside source, such as from a hex file. Instruction Set The collection of machine language instructions that a particular processor understands. Instructions A sequence of bits that tells a central processing unit to perform a particular operation and can contain data to be used in the operation.
MPLAB® IDE User’s Guide Linker Script Files Linker script files are the command files of a linker. They define linker options and describe available memory on the target platform. Listing Directives Listing directives are those directives that control the assembler listing file format. They allow the specification of titles, pagination and other listing control.
Glossary Microprocessor Mode One of the possible program memory configurations of PIC17 and PIC18 microcontrollers. In microprocessor mode, the on-chip program memory is not used. The entire program memory is mapped externally. Mnemonics Text instructions that can be translated directly into machine code. Also referred to as Opcodes. MPASM Assembler Microchip Technology’s relocatable macro assembler for PICmicro microcontroller devices, KEELOQ devices and Microchip memory devices.
MPLAB® IDE User’s Guide MPLIB Object Librarian MPLIB librarian is an object librarian for use with COFF object modules created using either MPASM assembler (mpasm or mpasmwin v2.0) or MPLAB C1X C compilers. MPLINK Object Linker MPLINK linker is an object linker for the Microchip MPASM assembler and the Microchip MPLAB C17 or C18 C compilers. MPLINK linker also may be used with the Microchip MPLIB librarian. MPLINK linker is designed to be used with MPLAB IDE, though it does not have to be.
Glossary Pass Counter A counter that decrements each time an event (such as the execution of an instruction at a particular address) occurs. When the pass count value reaches zero, the event is satisfied. You can assign the Pass Counter to break and trace logic, and to any sequential event in the complex trigger dialog. PC Personal Computer or Program Counter. PC Host Any IBM or compatible personal computer running a supported Windows operating system.
MPLAB® IDE User’s Guide RAM Random Access Memory (Data Memory). Memory in which information can be accessed in any order. Raw Data The binary representation of code or data associated with a section. Real Time When released from the halt state in the emulator or MPLAB ICD mode, the processor runs in Real-Time mode and behaves exactly as the normal chip would behave.
Glossary Skid When a hardware breakpoint is used to halt the processor, one or more additional instructions may be executed before the processor halts. The number of extra instructions executed after the intended breakpoint is referred to as the skid. Source Code The form in which a computer program is written by the programmer. Source code is written in some formal programming language which can be translated into or machine code or executed by an interpreter.
MPLAB® IDE User’s Guide Symbol A symbol is a general purpose mechanism for describing the various pieces which comprise a program. These pieces include function names, variable names, section names, file names, struct/enum/union tag names, etc. Symbols in MPLAB IDE refer mainly to variable names, function names and assembly labels. The value of a symbol after linking is its value in memory. System Window Control The system window control is located in the upper left corner of windows and some dialogs.
Glossary Watch Variable A variable that you may monitor during a debugging session in a Watch window. Watch Window Watch windows contain a list of watch variables that are updated at each breakpoint. Watchdog Timer A timer on a PICmicro microcontroller that resets the processor after a selectable length of time. The WDT is enabled or disabled and set up using Configuration bits. WDT See Watchdog Timer. Workbook For MPLAB SIM stimulator, a setup for generation of SCL stimulus.
MPLAB® IDE User’s Guide NOTES: DS51519B-page 272 © 2006 Microchip Technology Inc.
MPLAB® IDE USER’S GUIDE Index A About...................................................................... 116 About MPLAB IDE Dialog ...................................... 162 Active Project ........................................................... 73 Add Files to Project Dialog..................................... 167 Add Watch Dialog .................................................. 162 Animate .................................................................. 114 Animation Tab ......................
MPLAB® IDE User’s Guide F I FAQ ................................................................ 203, 249 Favorites, Help ......................................................... 88 File Closing ............................................................ 194 Creating .......................................................... 193 Opening .......................................................... 193 Printing ............................................................ 193 Saving .........................
Index O R Open Dialog ........................................................... 167 Osc/Trace Tab ....................................................... 252 Outdent .................................................................. 198 Output Window ...................................................... 134 rand Command ...................................................... 237 Read Only Files...................................................... 190 Reading, Recommended ..............................
MPLAB® IDE User’s Guide Stimulus ................................................................. 229 SCL Generator ................................................ 230 Stimulus Controller.......................................... 239 Stimulus - PIC17 Devices....................................... 241 File .................................................................. 244 Pin ................................................................... 241 Stimulus Controller ....................................
Index NOTES: © 2006 Microchip Technology Inc.
WORLDWIDE SALES AND SERVICE AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPE Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://support.microchip.com Web Address: www.microchip.
