MPLAB® XC8 C Compiler User’s Guide

 2012 Microchip Technology Inc.

DS52053B

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. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. Microchip is willing to work with the customer who is concerned about the integrity of their code. Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.”

• •

Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act.

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

Trademarks The Microchip name and logo, the Microchip logo, dsPIC, KEELOQ, KEELOQ logo, MPLAB, PIC, PICmicro, PICSTART, PIC32 logo, rfPIC and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. FilterLab, Hampshire, HI-TECH C, Linear Active Thermistor, MXDEV, MXLAB, SEEVAL and The Embedded Control Solutions Company are registered trademarks of Microchip Technology Incorporated in the U.S.A. Analog-for-the-Digital Age, Application Maestro, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, dsPICworks, dsSPEAK, ECAN, ECONOMONITOR, FanSense, HI-TIDE, In-Circuit Serial Programming, ICSP, Mindi, MiWi, MPASM, MPLAB Certified logo, MPLIB, MPLINK, mTouch, Omniscient Code Generation, PICC, PICC-18, PICDEM, PICDEM.net, PICkit, PICtail, REAL ICE, rfLAB, Select Mode, Total Endurance, TSHARC, UniWinDriver, WiperLock and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. All other trademarks mentioned herein are property of their respective companies. © 2012, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. Printed on recycled paper.

ISBN: 978-1-62076-375-9

QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV

== ISO/TS 16949 ==
DS52053B-page 2

Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified.

 2012 Microchip Technology Inc.

MPLAB® XC8 C COMPILER USER’S GUIDE Table of Contents
Preface ........................................................................................................................... 7 Chapter 1. Compiler Overview
1.1 Introduction ................................................................................................... 11 1.2 Compiler Description and Documentation .................................................... 11 1.3 Device Description ....................................................................................... 12

Chapter 2. Common C Interface
2.1 Introduction ................................................................................................... 13 2.2 Background – The Desire for Portable Code ............................................... 13 2.3 Using the CCI ............................................................................................... 16 2.4 ANSI Standard Refinement .......................................................................... 17 2.5 ANSI Standard Extensions ........................................................................... 25 2.6 Compiler Features ........................................................................................ 39

Chapter 3. How To’s
3.1 Introduction ................................................................................................... 41 3.2 Installing and Activating the Compiler .......................................................... 41 3.3 Invoking the Compiler ................................................................................... 43 3.4 Writing Source Code .................................................................................... 46 3.5 Getting My Application to Do What I Want ................................................... 56 3.6 Understanding the Compilation Process ...................................................... 60 3.7 Fixing Code That Does Not Work ................................................................. 67

Chapter 4. XC8 Command-line Driver
4.1 Introduction ................................................................................................... 71 4.2 Invoking the Compiler ................................................................................... 72 4.3 The Compilation Sequence .......................................................................... 75 4.4 Runtime Files ............................................................................................... 81 4.5 Compiler Output ........................................................................................... 84 4.6 Compiler Messages ...................................................................................... 86 4.7 XC8 Driver Options ...................................................................................... 91 4.8 Option Descriptions ...................................................................................... 92 4.9 MPLAB IDE V8 Universal Toolsuite Equivalents ........................................ 117 4.10 MPLAB X Universal Toolsuite Equivalents ............................................... 124

Chapter 5. C Language Features
5.1 Introduction ................................................................................................. 131 5.2 ANSI C Standard Issues ............................................................................ 131 5.3 Device-Related Features ............................................................................ 133 5.4 Supported Data Types and Variables ........................................................ 143 5.5 Memory Allocation and Access .................................................................. 165

 2012 Microchip Technology Inc.

DS52053B-page 3

MPLAB® XC8 C Compiler User’s Guide
5.6 Operators and Statements ......................................................................... 179 5.7 Register Usage ........................................................................................... 181 5.8 Functions .................................................................................................... 182 5.9 Interrupts .................................................................................................... 189 5.10 Main, Runtime Startup and Reset ............................................................ 194 5.11 Library Routines ....................................................................................... 198 5.12 Mixing C and Assembly Code .................................................................. 200 5.13 Optimizations ............................................................................................ 208 5.14 Preprocessing .......................................................................................... 210 5.15 Linking Programs ..................................................................................... 222

Chapter 6. Macro Assembler
6.1 Introduction ................................................................................................. 241 6.2 Assembler Usage ....................................................................................... 241 6.3 Options ....................................................................................................... 242 6.4 MPLAB XC8 Assembly Language .............................................................. 246 6.5 Assembly-Level Optimizations ................................................................... 268 6.6 Assembly List Files ..................................................................................... 269

Chapter 7. Linker
7.1 Introduction ................................................................................................. 277 7.2 Operation .................................................................................................... 277 7.3 Relocation and Psects ................................................................................ 285 7.4 Map Files .................................................................................................... 286

Chapter 8. Utilities
8.1 Introduction ................................................................................................. 291 8.2 Librarian ..................................................................................................... 291 8.3 OBJTOHEX ................................................................................................ 295 8.4 CREF .......................................................................................................... 297 8.5 CROMWELL ............................................................................................... 300 8.6 HEXMATE .................................................................................................. 303

Appendix A. Library Functions Appendix B. Error and Warning Messages Appendix C. Implementation-Defined Behavior
C.1 Translation (G.3.1) ..................................................................................... 479 C.2 Environment (G.3.2) .................................................................................. 479 C.3 Identifiers (G.3.3) ....................................................................................... 480 C.4 Characters (G.3.4) ..................................................................................... 480 C.5 Integers (G.3.5) .......................................................................................... 481 C.6 Floating-Point (G.3.6) ................................................................................ 482 C.7 Arrays and Pointers (G.3.7) ....................................................................... 482 C.8 Registers (G.3.8) ....................................................................................... 482 C.9 Structures, Unions, Enumerations, and Bit-Fields (G.3.9) ......................... 483 C.10 Qualifiers (G.3.10) ................................................................................... 483 C.11 Declarators (G.3.11) ................................................................................ 483

DS52053B-page 4

 2012 Microchip Technology Inc.

C.12 Statements (G.3.12) ................................................................................ 483 C.13 Preprocessing Directives (G.3.13) ........................................................... 484 C.14 Library Functions (G.3.14) ....................................................................... 485

Glossary ..................................................................................................................... 487 Index ........................................................................................................................... 507 Worldwide Sales and Service .................................................................................. 518

 2012 Microchip Technology Inc.

DS52053B-page 5

MPLAB® XC8 C Compiler User’s Guide
NOTES:

DS52053B-page 6

 2012 Microchip Technology Inc.

MPLAB® XC8 C COMPILER 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. The numbering convention for the DS number is “DSXXXXXA”, where “XXXXX” is the document number and “A” is the revision level of the document. For the most up-to-date information on development tools, see the MPLAB® IDE online help. Select the Help menu, and then Topics to open a list of available online help files.

INTRODUCTION
This chapter contains general information that will be useful to know before using the MPLAB® XC8 C Compiler User’s Guide. Items discussed in this chapter include: • • • • • • • • Document Layout Conventions Used in this Guide Warranty Registration Recommended Reading The Microchip Web Site Development Systems Customer Change Notification Service Customer Support Document Revision History

DOCUMENT LAYOUT
This document describes how to use the MPLAB XC8 C Compiler. The manual layout is as follows: • • • • • • • • • • • • Chapter 1. Compiler Overview Chapter 3. How To’s Chapter 4. XC8 Command-line Driver Chapter 5. C Language Features Chapter 6. Macro Assembler Chapter 7. Linker Chapter 8. Utilities Appendix A. Library Functions Appendix B. Error and Warning Messages Appendix C. Implementation-Defined Behavior Glossary Index

 2012 Microchip Technology Inc.

DS52053B-page 7

MPLAB® XC8 C Compiler User’s Guide
CONVENTIONS USED IN THIS GUIDE
This manual uses the following documentation conventions: DOCUMENTATION CONVENTIONS
Description Arial font: Italic characters Initial caps Represents Referenced books Emphasized text A window A dialog A menu selection A field name in a window or dialog A menu path A dialog button A tab A number in verilog format, where N is the total number of digits, R is the radix and n is a digit. A key on the keyboard Sample source code Filenames File paths Keywords Command-line options Bit values Constants A variable argument Optional arguments Choice of mutually exclusive arguments; an OR selection Replaces repeated text Represents code supplied by user Examples MPLAB® IDE User’s Guide ...is the only compiler... the Output window the Settings dialog select Enable Programmer “Save project before build” File>Save Click OK Click the Power tab 4‘b0010, 2‘hF1

Quotes Underlined, italic text with right angle bracket Bold characters N‘Rnnnn

Text in angle brackets < > Courier New font: Plain Courier New

Press <Enter>, <F1> #define START autoexec.bat c:\mcc18\h _asm, _endasm, static -Opa+, -Opa0, 1 0xFF, ‘A’ file.o, where file can be any valid filename mcc18 [options] file [options] errorlevel {0|1} var_name [, var_name...] void main (void) { ... }

Italic Courier New Square brackets [ ] Curly brackets and pipe character: { | } Ellipses...

WARRANTY REGISTRATION
Please complete the enclosed Warranty Registration Card and mail it promptly. Sending in the Warranty Registration Card entitles users to receive new product updates. Interim software releases are available at the Microchip web site.

RECOMMENDED READING
This user’s guide describes how to use Chapter Name. Other useful documents are listed below. The following Microchip documents are available and recommended as supplemental reference resources.

DS52053B-page 8

 2012 Microchip Technology Inc.

Preface
Readme for Chapter Name For the latest information on using Chapter Name, read the “Readme for Chapter Name.txt” file (an ASCII text file) in the Readmes subdirectory of the MPLAB® IDE installation directory. The Readme file contains update information and known issues that may not be included in this user’s guide. Readme Files For the latest information on using other tools, read the tool-specific Readme files in the Readmes subdirectory of the MPLAB IDE installation directory. The Readme files contain update information and known issues that may not be included in this user’s guide.

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. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQs), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives

DEVELOPMENT SYSTEMS CUSTOMER CHANGE NOTIFICATION SERVICE
Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at www.microchip.com, click on Customer Change Notification and follow the registration instructions. The Development Systems product group categories are: • Compilers – The latest information on Microchip C compilers and other language tools. These include the MPLAB® C18 and MPLAB® C30 C compilers; MPASM™ and MPLAB® ASM30 assemblers; MPLINK™ and MPLAB LINK30 object linkers; and MPLIB™ and MPLAB® LIB30 object librarians. • Emulators – The latest information on Microchip in-circuit emulators.This includes the MPLAB® ICE 2000 and MPLAB ICE 4000. • In-Circuit Debuggers – The latest information on the Microchip In-Circuit Debugger, MPLAB® ICD 2. • MPLAB® IDE – The latest information on Microchip MPLAB IDE, the Windows® Integrated Development Environment for development systems tools. This list is focused on the MPLAB® IDE, MPLAB® SIM simulator, MPLAB® IDE Project Manager and general editing and debugging features. • Programmers – The latest information on Microchip programmers. These include the MPLAB® PM3 and PRO MATE® II device programmers and the PICSTART® Plus and PICkit™ 1 development programmers.

 2012 Microchip Technology Inc.

DS52053B-page 9

MPLAB® XC8 C Compiler 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. Technical support is available through the web site at: http://support.microchip.com

DOCUMENT REVISION HISTORY
Revision B (July 2012)
• • • • • • • • • • • • • • Added 'how tos' chapter. Expanded section relating to PIC18 erratas. Updated the section relating to compiler optimization settings. Updated MPLAB v8 and MPLAB X IDE project option dialogs. Added sections describing PIC18 far qualifier and inline function qualifier. Expanded section describing the operation of the main() function Expanded information about equivalent assembly symbols for Baseline parts. Updated the table of predefined macro symbols. Added section on #pragma addrqual Added sections to do with inline-ing functions Updated diagrams and text associated with call graphs in the list file Updated library function section to be consistent with packaged libraries Added new compiler warnings and errors. Added new chapter describing the Common Compiler Interface Standard (CCI)

Revision A (February 2012)
Initial release of this document.

DS52053B-page 10

 2012 Microchip Technology Inc.

2. “compiler” is often used to refer to the command-line driver.7 “XC8 Driver Options”. Free mode is available for unlicensed customers.2 COMPILER DESCRIPTION AND DOCUMENTATION The MPLAB® XC8 C Compiler is a free-standing. it will be attributed to the compiler. • Compiler Description and Documentation • Device Description 1. including 32. optimizing ANSI C compiler. It supports all 8-bit PIC® microcontrollers: PIC10.1 INTRODUCTION This chapter is an overview of the MPLAB XC8 C Compiler.1 Conventions Throughout this manual.  2012 Microchip Technology Inc. In a similar fashion. the term “compiler” is used. The Standard and PRO operating modes are licensed modes and require a serial number to enable them. Linux and Apple OS X. “compilation” refers to all or a selection of steps involved in generating source code into an executable binary image. the driver for the MPLAB XC8 C Compiler package is called xc8. as well as the PIC14000 device. When it is not important to identify which application performed an action. PIC16 and PIC18 series devices.and 64-bit Windows®. The compiler is available for several popular operating systems. 1. the collection of applications that comprise the MPLAB XC8 C Compiler. It can refer to all. Although specifically. The compiler is available in three operating modes: Free. Compiler Overview 1. Likewise. “compiler options” commonly relates to command-line driver options. including these topics. Accordingly. PIC12. or a subset of. The basic compiler operation. The modes only differ in the level of optimization employed by the compiler. supported devices and available memory are identical across all modes. The driver and its options are discussed in Section 4. DS52053B-page 11 . Standard or PRO.MPLAB® XC8 C COMPILER USER’S GUIDE Chapter 1.

addressing modes memory and registers whenever possible. DS52053B-page 12  2012 Microchip Technology Inc. as well. but incorporates additional instructions and features. It has larger data memory banks and program memory pages. Mid-Range. The following descriptions indicate the distinctions within those device cores: The baseline core uses a 12-bit-wide instruction set and is available in PIC10.3 DEVICE DESCRIPTION This compiler supports 8-bit Microchip PIC devices with baseline. The Enhanced Mid-Range core also uses a 14-bit-wide instruction set. It is available in PIC12. See Section 4.8. PIC12 and PIC16 part numbers. The Mid-Range core uses a 14-bit-wide instruction set that includes more instructions than the baseline core. PIC18 core devices have part numbers that begin with PIC18.MPLAB® XC8 C Compiler User’s Guide 1. The compiler takes advantage of the target device’s instruction set.21 “--CHIPINFO: Display List of Supported Devices” for information on finding the full list of devices supported by the compiler. . PIC14 and PIC16 part numbers. The PIC18 core instruction set is 16-bits wide and features additional instructions and an expanded register set. and PIC18 cores. Enhanced Mid-Range. There are both PIC12 and PIC16 part numbers that are based on the Enhanced Mid-Range core.

tools. but if there is no regulation of the compiler’s operation. The following topics are examined in this chapter of the MPLAB XC8 C Compiler User’s Guide: • • • • ANSI Standard Extensions Using the CCI ANSI Standard Refinement ANSI Standard Extensions 2. implement different features and code syntax. and time to be truly flexible. Embedded engineers typically think of code portability as being across target devices. Standards for the C language have been developed to ensure that change is managed and code is more portable. the less time and effort it takes to have it running in a new environment. but this is only part of the situation. Common C Interface 2. The same code could be compiled for the same target but with a different compiler. it is your responsibility to write code that conforms. A compiler option must also be set to ensure that the operation of the compiler is consistent with the interface when the project is built.2 BACKGROUND – THE DESIRE FOR PORTABLE CODE All programmers want to write portable source code.  2012 Microchip Technology Inc. this portability cannot be achieved by the programmer alone. For example. Code must be portable across targets. The American National Standards Institute (ANSI) publishes standards for many disciplines. Legacy projects will need to be migrated to achieve conformance. Portability means that the same source code can be compiled and run in a different execution environment than that for which it was written. Clearly. If you intend to use the CCI. since the compiler vendors can base their products on different technologies. DS52053A-page 13 . You may only write code for one target device and only use one brand of compiler. including programming languages. Rarely can code be one hundred percent portable. simply updating your compiler version may change your code’s behavior. CCI-conforming code would make it easier to port from a PIC18 MCU using the MPLAB XC8 C compiler to a PIC24 MCU using the MPLAB XC16 C compiler. Many a great compiler optimization has broken many an unsuspecting project. so this must be considered as well. The ANSI C Standard is a universally adopted standard for the C programming language.MPLAB® XC8 C COMPILER USER’S GUIDE Chapter 2. Differences between those compilers might lead to the code failing at compile time or runtime. The CCI assumes that your source code already conforms to the ANSI Standard. but the more tolerant it is to change. or improve the way their product works.1 INTRODUCTION The Common C Interface (CCI) is available with all MPLAB XC C compilers and is designed to enhance code portability between these compilers.

which we used as an example earlier. or if you update the version of the compiler you use to build. it must ensure that a conforming C program functions as described by the standard. Because a compiler targeting this device cannot implement recursion. it (strictly speaking) cannot conform to the ANSI C Standard. The standard uses the term behavior to mean the external appearance or action of the program. The standard describes implementation. but it does not go as far as saying what the size of an int actually is.. and the standard would loose its effectiveness. are also supported. yet. For example. and run on. .MPLAB® XC8 C Compiler User’s Guide 2.g. as mentioned in the footnote). but the semantic rules by which that program will be interpreted. It has nothing to do with how a program is encoded. Code that strictly conforms to the standard does not produce output that is dependent on any unspecified. 1. and the action of right-shifting a signed integer can produce different results on different implementations. falls into the category of behavior that is defined by implementation. The size of an int. these different results are still ANSI C compliant. Case in point: The mid-range PIC® microcontrollers do not have a data stack. for a compiler to conform to the standard.1 The ANSI Standard The ANSI C Standard has to reconcile two opposing goals: freedom for compilers vendors to target new devices and improve code generation.2. how that compiler is being used.1 But. If the standard is too strict. you build for. a different target device. then you are using a different implementation. the set of tools and the runtime environment on which the code will run. Thus. Unspecified behavior The standard provides two or more possibilities and imposes no further requirements on which possibility is chosen in any particular instance. Some features from the later standard. the size of an int is defined by which compiler is being used. e. This example illustrate a situation in which the standard is too strict for mid-range devices and tools. All the MPLAB XC compilers conform to the ANS X3. undefined. The standard organizes source code whose behavior is not fully defined into groups that include the following behaviors: Implementation-defined behavior This is unspecified behavior where each implementation documents how the choice is made. This is commonly called the C89 Standard. and the device that is being targeted. the standard states that an int type must be able to hold at least a 16-bit value.159-1989 Standard for programming languages (with the exception of the XC8 compiler’s inability to allow recursion. or implementation-defined behavior. some specifications appear somewhat vague. with the known functional operation of source code for programmers. device architectures may not allow the compiler to conform. source code can be made portable. Undefined behavior This is behavior for which the standard imposes no requirements. DS52053A-page 14  2012 Microchip Technology Inc. If both goals can be met. That is to say. Since the standard is trying to achieve goals that could be construed as conflicting. programmers would see wildly differing results within different compilers and architectures. C99. if it is too weak. The standard is implemented as a set of rules which detail not only the syntax that a conforming C program must follow. If any of these change.

DS52053A-page 15 .2 The Common C Interface The Common C Interface (CCI) supplements the ANSI C Standard and makes it easier for programmers to achieve consistent outcomes on all Microchip devices when using any of the MPLAB XC C compilers. When working so closely to the device hardware. are not defined by the CCI. While the ANSI C Standard provides a mutual understanding for programmers and compiler vendors. They replace keywords. the result of right-shifting a signed integer is fully defined by the CCI. macros and attributes that are the native compiler implementation. While you may choose not to follow the advice. all designed with portability in mind. It delivers the following improvements.Common C Interface For freestanding implementations – or for what we typically call embedded applications – the standard allows non-standard extensions to the language.  2012 Microchip Technology Inc. Note that many implementation-defined items that closely couple with device characteristics. Consistent syntax for non-standard extensions The CCI non-standard extensions are mostly implemented using keywords with a uniform syntax.2. This cannot be offered by the standard in a consistent way. such as the size of an int. as well as utilizing the often complex world of small-device memory architectures. programmers need to consider the implementation-defined behavior of their tools and the probability that they may need to use extensions to the C language that are non-standard. and any arguments to the keywords may be device specific. a programmer needs a means of specifying device setup and interrupts. Refinement of the ANSI C Standard The CCI documents specific behavior for some code in which actions are implementation-defined behavior under the ANSI C Standard. The interpretation of the keyword may differ across each compiler. it will not conform to the CCI. For example. Both of these circumstances can have an impact on code portability. but obviously does not enforce how they are specified or how they work. Coding guidelines The CCI may indicate advice on how code should be written so that it can be ported to other devices or compilers. 2.

thus it is relevant for new projects. then it is not part of the CCI. .h> in every module Some CCI features are only enabled if this header is seen by the compiler. you must do the following things. If any implementation-defined behavior or any non-standard extension is not discussed in this document. although you may choose to modify existing projects so they conform. These items are segregated into those that refine the standard. and other miscellaneous compiler options and usage. Ensure ANSI compliance Code that does not conform to the ANSI C Standard does not confirm to the CCI.MPLAB® XC8 C Compiler User’s Guide 2. Programs which use these features do not conform to the CCI. Use the CCI extensions to the language Use the CCI extensions rather than the native language extensions The next sections detail specific items associated with the CCI. label addresses and 24-bit short long types are not part of the CCI. For your project to conform to the CCI. Include <xc. Guidelines are indicated with these items. For example. The compiler may issue a warning or error to indicate when you use a non-CCI feature and the CCI is enabled. The CCI is something you choose to follow and put into effect. those that deal with the ANSI C Standard extensions. or use the command-line option that is equivalent. Enable the CCI Select the MPLAB IDE widget Use CCI Syntax in your project. GCC case ranges. Observe refinements to ANSI by the CCI Some ANSI implementation-defined behavior is defined explicitly by the CCI.3 USING THE CCI The CCI allows enhanced portability by refining implementation-defined behavior and standardizing the syntax for extensions to the language. DS52053A-page 16  2012 Microchip Technology Inc.

#include <usb_main.3 MIGRATION TO THE CCI No action required. 2.2 DIFFERENCES The 8-bit compilers used a void return type for this function.3 Header File Specification Header file specifications that use directory separators do not conform to the CCI.4.h"  2012 Microchip Technology Inc.h> #include "global. 2.2.Common C Interface 2. DS52053A-page 17 . 2.4.1 EXAMPLE The following example shows two conforming include directives. 2.4.4. Escaped characters may be used in character constants or string literals to represent extended characters not in the basic character set.1 Source File Encoding Under the CCI. const char myName[] = "Bj\370rk\n". 2. Lines may be terminated using a line feed ('\n') or carriage return ('\r') that is immediately followed by a line feed.4.2 The Prototype for main The prototype for the main() function is int main(void).4.2 DIFFERENCES All compilers have used this character set.1 EXAMPLE The following shows an example of how main() might be defined int main(void) { while(1) process().4. 2.2.4 ANSI STANDARD REFINEMENT The following topics describe how the CCI refines the implementation-defined behaviors outlined in the ANSI C Standard.2. 2.3. a source file must be written using characters from the 7-bit ASCII set.1.4.4. 2.1.1.1 EXAMPLE The following shows a string constant being defined that uses escaped characters. } 2. Confirm the return type for main() in all projects previously compiled for 8-bit targets.3 MIGRATION TO THE CCI Each program has one definition for the main() function.4. 2.

h" The header file should be locatable in the current working directory. 2. If unsuccessful. For any header files specified in angle bracket delimiters < >.4.2 DIFFERENCES Header file specifications that use directory separators have been allowed in previous versions of all compilers. the file should be discoverable in the paths searched by the compiler detailed below. the search paths should first be the current working directory.3. the search paths should be those specified by -I options (or the equivalent MPLAB IDE option). In the case of an MPLAB X project. Under the CCI. 2. This is purely a coding guide line. the search paths should be the same directories searched when the header files is specified in angle bracket delimiters. this does not conform to the CCI. . Remove all but the header file name in the directive.MPLAB® XC8 C Compiler User’s Guide 2. or on the command-line as follows: -Ilcd 2. Add the directory path to the compiler’s include search path or MPLAB IDE equivalent.3.1 EXAMPLE If including a header file as in the following directive #include "myGlobals.4 Include Search Paths When you include a header file under the CCI. This will force the compiler to search the directories specified with this option. 2. For example. If it is located elsewhere.4. or the standard compiler directories. or the paths specified by any -I options. and use the -I option in place of this. The -I options are searched in the order in which they are specified. the current working directory is the directory in which the C source file is located. For any file specified in quote characters " ".3 MIGRATION TO THE CCI Any #include directives that use directory separators in the header file specifications should be changed. then the standard compiler include directories. no directory specifiers should be used.4.2 DIFFERENCES The compiler operation under the CCI is not changed. 2. Any other options to specify search paths for header files do not conform to the CCI.h> should be changed to: #include <lcd.4.4.4.4. DS52053A-page 18  2012 Microchip Technology Inc. the following code: #include <inc/lcd.4.4.h> and the path to the inc directory added to the compiler’s header search path in your MPLAB IDE project properties. Compatibility problems arose when Windows-style separators “\” were used and the code compiled under other host operating systems. Ensure the header file can be found in the directories specified in this section.3 MIGRATION TO THE CCI Remove any option that specifies header file search paths other than the -I option (or the equivalent MPLAB IDE option).

2. are not fully defined by the CCI. by design.h>.1 EXAMPLE The following example shows two poorly named variables.4.4.5 The Number of Significant Initial Characters in an Identifier At least the first 255 characters in an identifier (internal and external) are significant. as specified in <limits. Essentially.6 Sizes of Types The sizes of the basic C types.g.5. indicate minimum requirements for these types. 2. These types are consistently defined across all XC compilers.and 32-bit compilers did not impose a limit on the number of significant characters. This extends upon the requirement of the ANSI C Standard which states a lower number of significant characters are used to identify an object. but names which are considered unique under the CCI. 2.6.4. 2. int stateOfPortBWhenTheOperatorHasSelectedAutomaticModeAndMotorIsRunningSlow. but an option allowed this to be extended. whose size is clearly indicated and remains fixed. the C language offers a choice of two groups of types: those that offer sizes and formats that are tailored to the device you are using. regardless of the target device.3 MIGRATION TO THE CCI No action required. int and long. or those that have a fixed size.3 MIGRATION TO THE CCI If you require a C type that has a fixed size. uint8_t or int16_t.Common C Interface 2. int native. and a variable. whose size will allow efficient access on the target device. int stateOfPortBWhenTheOperatorHasSelectedAutomaticModeAndMotorIsRunningFast.4.2 DIFFERENCES Former 8-bit compilers used 31 significant characters by default.5.h>. int16_t fixed. 2.4. regardless of the target.4. 2. even though it may not allow efficient access on every device. The ANSI C Standard does. The 16. reflect the size of registers and other architectural features in the target device. native. fixed.h>. for example char. If you need fixed-size types in your project. You may take advantage of the less restrictive naming scheme.5. These types. however. use the types defined in <stdint.6.6.. DS52053A-page 19 . even outside of the CCI. use one of the types defined by <stdint. They allow the device to efficiently access objects of this type. 2.4.2 DIFFERENCES This is consistent with previous types implemented by the compiler.4.  2012 Microchip Technology Inc. e.1 EXAMPLE The following example shows the definition of a variable.

4. It is generally recommended that all definitions for the char type explicitly state the signedness of the object.1 EXAMPLE The following shows a variable. the code is not strictly conforming.4. The 16.4.1 EXAMPLE The following example char foobar.2 DIFFERENCES The 8-bit compilers have always treated plain char as an unsigned type. You may use the -funsigned-char option on XC16/32 to change the type of plain char. 2. 2.8. that is assigned the value -28 decimal.4. defines an unsigned char object called foobar.2 DIFFERENCES All compilers have represented signed integers in the way described in this section.4.8.4. DS52053A-page 20  2012 Microchip Technology Inc. 2.3 MIGRATION TO THE CCI No action required. 2.or 32-bit compilers needs review.7. signed char foobar. . Any plain char that was intended to be a signed quantity should be replaced with an explicit definition.4.and 32-bit compilers used signed char as the default plain char type. for example.7 Plain char Types The type of a plain char is unsigned char.3 MIGRATION TO THE CCI Any definition of an object defined as a plain char and using the 16.4. test.8. signed char test = 0xE4. 2.8 Signed Integer Representation The value of a signed integer is determined by taking the two’s complement of the integer.7. 2. The -funsigned-char option on those compilers changed the default type to be unsigned char. but since this option is not supported on XC8.MPLAB® XC8 C Compiler User’s Guide 2. 2.7.

Under the CCI.10.11 “Right-shifting Signed Values”.Common C Interface 2.1 EXAMPLE The following shows an assignment of a value that will be truncated. the value of output after the assignment will be -2 (i.1 EXAMPLE The following shows an example of a negative quantity involved in a bitwise AND operation. 2. output = -13.9.e.10. See also Section 2.3 MIGRATION TO THE CCI No action required. This will preserve the sign of the original value.4.4. 2.e. signed char destination.4.11 Right-shifting Signed Values Right-shifting a signed value will involve sign extension. 2. the bit pattern 0xFE). the value of destination after the alignment will be -2 (i.10. 2.4. 2.10 Bit-wise Operations on Signed Values Bitwise operations on signed values act on the two’s complement representation.4.2 DIFFERENCES All compilers have performed bitwise operations in an identical fashion to that described in this section. DS52053A-page 21 .4. input = -13. the value of output after the assignment will be 0x72..4.  2012 Microchip Technology Inc.9. 2. the bit pattern 0xFE).3 MIGRATION TO THE CCI No action required.4.9 Integer conversion When converting an integer type to a signed integer of insufficient size. 2. output = input & 0x7E. signed char output. 2.4. output = input >> 3..11.4. destination = source.4. Under the CCI. including the sign bit.1 EXAMPLE The following shows an example of a negative quantity involved in a bitwise AND operation. the original value is truncated from the most-significant bit to accommodate the target size. 2.9. signed char input. Under the CCI. unsigned int source = 0x12FE.2 DIFFERENCES All compilers have performed integer conversion in an identical fashion to that described in this section.

parity :3. signed and signed int are synonymous. 2. Code that attempts to extract offset by reading data is not guaranteed to read the correct value. value :4.13.13 Default Bit-field int Type The type of a bit-field specified as a plain int will be identical to that of one defined using unsigned int. 2. 2.2 DIFFERENCES All compilers have performed right shifting as described in this section.11.4. 2.1 EXAMPLE The following shows an example of a structure tag containing bit-fields which are unsigned integers and with the size specified.4.4. unsigned int data. 2. OUTPUTS { direction :1.12.2 DIFFERENCES All compilers have not converted union members accessed via other members. result = foobbar. This is quite different to other objects where the types int.MPLAB® XC8 C Compiler User’s Guide 2.12 Conversion of Union Member Accessed Using Member With Different Type If a union defines several members of different types and you use one member identifier to try to access the contents of another (whether any conversion is applied to the result) is implementation-defined behavior in the standard. It is recommended that the signedness of the bit-field be explicitly stated in all bit-field definitions. float result. union { signed char code.11. float offset.data. } foobar.4.4. no conversion is applied and the bytes of the union object are interpreted as an object of the type of the member being accessed. In the CCI. 2. without regard for alignment or other possible invalid conditions.4.4.3 MIGRATION TO THE CCI No action required. struct int int int }.4.1 EXAMPLE The following shows an example of a union defining several members.3 MIGRATION TO THE CCI No action required. . 2.12.12. DS52053A-page 22  2012 Microchip Technology Inc.

13. unsigned second :6. } order. but would implement the bit-field with an unsigned int type. for example. it is 32 bits in size.14. and padding bits will fill the gap. 2. Under the CCI and using XC8. Note that the size of a storage unit differs with each compiler as this is based on the size of the base data type (e. The size of this structure. On 8-bit compilers this unit is 8-bits in size.2 DIFFERENCES This allocation is identical with that used by all previous compilers. bit-fields will not straddle a storage unit boundary. In the CCI. the bit-field type should be changed to signed int. then the type of these should be changed to signed int.13. 2. The bit-field second. 2. as in: struct WAYPT { signed int log :3.15 The Allocation Order of Bits-field The memory ordering of bit-fields into their storage unit is not specified by the ANSI C Standard.4.3 MIGRATION TO THE CCI Any code that defines a bit-field with the plain int type should be reviewed. the storage allocation unit is byte sized.4. will be allocated a new storage unit since there are only 2 bits remaining in the first storage unit in which first is allocated. DS52053A-page 23 .and 32-bit compilers have implemented bit-fields defined using int as having a signed int type.  2012 Microchip Technology Inc. int) from which the bit-field type is derived.4. In the CCI. The 16. and for 32-bit compilers. it is 16 bits. signed int direction :4. :3.g.4.3 MIGRATION TO THE CCI No action required. will be 2 bytes. order. }. 2.. unless the option -funsigned-bitfields was specified.14.4. If the intention was for these to be signed quantities. 2.2 DIFFERENCES The 8-bit compilers have previously issued a warning if type int was used for bit-fields.4.14. 2.1 EXAMPLE The following shows a structure containing bit-fields being defined.4. for 16-bit compilers.14 Bit-fields Straddling a Storage Unit Boundary Whether a bit-field can straddle a storage unit boundary is implementation-defined behavior in the standard.Common C Interface 2. the first bit defined will be the least significant bit of the storage unit in which it will be allocated. struct { unsigned first : 6. a new storage unit will be allocated to the structure. in: struct WAYPT { int log int direction }. :4.

unsigned mid :6.4. 2. 2. 2.16 The NULL macro The NULL macro is defined in <stddef.4. and hi.3 MIGRATION TO THE CCI No action required.h>.17.4.4.1 EXAMPLE The following shows a structure containing bit-fields being defined.16. unsigned hi : 1.16. the most significant bit of that same storage unit byte. The bit-field lo will be assigned the least significant bit of the storage unit assigned to the structure foo. floating-point types must not be smaller than 32 bits in size.4.4. } foo. The bit-field mid will be assigned the next 6 least significant bits. 2. 2.MPLAB® XC8 C Compiler User’s Guide 2. float outY. its definition is implementation-defined behavior. .15. No migration is required for other compilers. 2. is implicitly cast to the destination type. Review any source code that may have assumed a float or double type and may have been 24 bits in size. the definition of NULL is the expression (0). 2.15. DS52053A-page 24  2012 Microchip Technology Inc. Under the CCI.17.4.3 MIGRATION TO THE CCI No action required.2 DIFFERENCES The 32-bit compilers previously assigned NULL the expression ((void *)0). which will be at least 32-bit in size. (0).16.2 DIFFERENCES The 8-bit compilers have allowed the use of 24-bit float and double types.17 Floating-point sizes Under the CCI. however.1 EXAMPLE The following shows a pointer being assigned a null pointer constant via the NULL macro. 2.4.3 MIGRATION TO THE CCI When using 8-bit compilers.4. struct { unsigned lo : 1.4. int * ip = NULL.15.17. the float and double type will automatically be made 32 bits in size once the CCI mode is enabled.1 EXAMPLE The following shows the definition for outY.4. 2.2 DIFFERENCES This is identical with the previous operation of all compilers. 2. The value of NULL.

2.  2012 Microchip Technology Inc.h> 2. int scanMode __at(0x200). 2.5 ANSI STANDARD EXTENSIONS The following topics describe how the CCI provides device-specific extensions to the standard. 2.h> <p24Fxxxx.and device-specific types and SFRs.1 EXAMPLE The following shows two variables and a function being made absolute. ’s’. } 2.1. or family-specific header files as in the following examples: #include #include #include #include #include <p32xxxx. Some CCI definitions depend on this header being seen.and 32-bit compilers used a variety of headers to do the same job. const char keys[] __at(123) = { ’r’.2 DIFFERENCES The 8-bit compilers have used an @ symbol to specify an absolute address.h> "p30f6014.h> <p30fxxxx. ’d’}.1.2 Absolute addressing Variables and functions can be placed at an absolute address by using the __at() construct.5.h" to: #include <xc.h> MIGRATION TO THE CCI used previously in 8-bit compiler code.h> as the equivalent header. int modify(int x) __at(0x1000) { return x * 2 + 3.Common C Interface 2. thus allowing conformance with the CCI.1. ’u’. The 16.5.and 32-bit compilers have used the address attribute to specify an object’s address.qualifier Note that XC16/32 may require the variable or function to be placed in a special section for absolute addressing to work.5. 2.5.5. Stack-based (auto and parameter) variables cannot use the __at() specifier.5.2.2 DIFFERENCES Some 8-bit compilers used <htc.3 Change: #include <htc. as well as allowing access to SFRs.5. Previous versions of the 16. You must include this file into every module to conform with the CCI.1 Generic Header File A single header file <xc.2.h> 2. #include <xc. DS52053A-page 25 .1 EXAMPLE The following shows this header file being included.h> must be used to declare all compiler.h> <p33Fxxxx.

5.5. In XC8. . 2. Some devices may not have such memory implemented. Stack-based (auto and parameter) variables cannot use the __far specifier. but it is typically memory that requires more complex code to access. The 32-bit compilers have used the far attribute with functions. 2. Expressions involving far-qualified objects may generate slower and larger code. __far int ext_getCond(int selector). Functions could not be qualified as far.4 CAVEATS If the __at() and __section() specifiers are both applied to an object when using XC8. Use the native keywords discussed in the Differences section to look up information on the semantics of this qualifier. Exactly what constitutes far memory is dependent on the target device. change absolute object definitions such as the following example: int scanMode @ 0x200.3 MIGRATION TO THE CCI Avoid making objects and functions absolute if possible. to: int scanMode __at(0x200). 2.5.2.1 EXAMPLE The following shows a variable and function qualified using __far. use of this qualifier will be ignored. DS52053A-page 26  2012 Microchip Technology Inc. 2.5.3. the __section() specifier is currently ignored. only. __far int serialNo. In XC16/32. to: int scanMode __at(0x200).3.5.2 DIFFERENCES The 8-bit compilers have used the qualifier far to indicate this meaning.MPLAB® XC8 C Compiler User’s Guide 2.2. in which case. change code such as: int scanMode __attribute__(address(0x200))).3 Far Objects and Functions The __far qualifier may be used to indicate that variables or functions may be located in ‘far memory’. The 16-bit compilers have used the far attribute with both variables and functions.

use of this qualifier will be ignored.  2012 Microchip Technology Inc.3. int tblIdx __attribute__ ((far)).Common C Interface 2. as in the following example: far char template[20]. The 32-bit compilers have used the near attribute for functions.and 32-bit compilers.4.. Stack-based (auto and parameter) variables cannot use the __near specifier.5. Expressions involving near-qualified objects may be faster and result in smaller code. but it is typically memory that can be accessed with less complex code.3 MIGRATION TO THE CCI For 8-bit compilers. The 16-bit compilers have used the near attribute with both variables and functions.4 None. only.3. __far char template[20]. DS52053A-page 27 .2 DIFFERENCES The 8-bit compilers have used the qualifier near to indicate this meaning.4.5. CAVEATS 2. __near int serialNo. 2. Some devices may not have such memory implemented. Exactly what constitutes near memory is dependent on the target device. __near int ext_getCond(int selector). Functions could not be qualified as near. change any occurrence of the far qualifier. 2.4 Near Objects The __near qualifier may be used to indicate that variables or functions may be located in ‘near memory’. int __far tblIdx. i. Use the native keywords discussed in the Differences section to look up information on the semantics of this qualifier.e.5. in which case. 2. to __far. In the 16. to void __far bar(void).5.1 EXAMPLE The following shows a variable and function qualified using __near. change any occurrence of the far attribute.5. as in the following void bar(void) __attribute__ ((far)).

5. to int __persistent tblIdx.5.3 MIGRATION TO THE CCI With 8-bit compilers.5. to __near. persistent.and 32-bit compilers have used the persistent attribute with variables to indicate they were not to be cleared. i. int tblIdx __attribute__ ((near)).and 32-bit compilers. as in the following int tblIdx __attribute__ ((persistent)). to __persistent. Use the native keywords discussed in the Differences section to look up information on the semantics of this qualifier.4 None. change any occurrence of the persistent attribute. int __near tblIdx.5 Persistent Objects The __persistent qualifier may be used to indicate that variables should not be cleared by the runtime startup code. 2..5. __near char template[20].and 32-bit compilers.e. CAVEATS DS52053A-page 28  2012 Microchip Technology Inc. as in the following void bar(void) __attribute__ ((near)).4. change any occurrence of the near qualifier. as in the following example: persistent char template[20].MPLAB® XC8 C Compiler User’s Guide 2. to void __near bar(void).5. as in the following example: near char template[20]. 2. .2 DIFFERENCES The 8-bit compilers have used the qualifier.e. 2. For the 16.5. i.5.1 EXAMPLE The following shows a variable qualified using __persistent.5. __persistent char template[20].3 MIGRATION TO THE CCI For 8-bit compilers. change any occurrence of the near attribute. to indicate this meaning.4.5.4 None. 2. The 16. __persistent int serialNo.5. change any occurrence of the persistent qualifier.5.. 2. In 16. CAVEATS 2.

The number.6.5. Equivalent specifiers have never been defined for any other compiler.1 EXAMPLE The following shows a variable qualified using __bank(). __xdata char template[20]. Some devices may not have such memory implemented.5. Use the native keywords discussed in the Differences section to look up information on the semantics of these qualifiers. change any occurrence of the space attributes xmemory or ymemory. __bank(0) char start. represents the bank number.6 X and Y Data Objects The __xdata and __ydata qualifiers may be used to indicate that variables may be located in special memory regions. num.6. as well as another variable qualified with __ydata.7 Banked Data Objects The __bank(num) qualifier may be used to indicate that variables may be located in a particular data memory bank. but it is typically a subdivision of data memory to allow for assembly instructions with a limited address width field. 2.. 2. but it is typically memory that can be accessed independently on separate buses.5. __xdata char data[16]. 2.5. DS52053A-page 29 . Some devices may not have banked data memory implemented.7. in which case.3 MIGRATION TO THE CCI For 16-bit compilers.2 DIFFERENCES The 16-bit compilers have used the xmemory and ymemory space attribute with variables. __bank(5) char stop. in which case. as in the following example: char __attribute__((space(xmemory)))template[20]. Use the native keywords discussed in the Differences section to look up information on the semantics of these qualifiers. 2.6.5. Exactly what constitutes banked memory is dependent on the target device.e. or __ydata. 2.1 EXAMPLE The following shows a variable qualified using __xdata.4 None. __ydata char coeffs[4]. Exactly what constitutes X and Y memory is dependent on the target device.6. Such memory is often required for some DSP instructions. use of this qualifier will be ignored.Common C Interface 2. The number of data banks implemented will vary from one device to another. to __xdata.5.  2012 Microchip Technology Inc. i. use of these qualifiers will be ignored. CAVEATS 2.5.

bank2 and bank3 to indicate the same. to __align.5.5.5. Equivalent specifiers have never been defined for any other compiler.5.7. i. 2. __align(-8) int spacer. __align(2) char coeffs[6].8 Alignment of Objects The __align(alignment) specifier may be used to indicate that variables must be aligned on a memory address that is a multiple of the alignment specified.1 EXAMPLE The following shows variables qualified using __align() to ensure they end on an address that is a multiple of 8. bank1. Use the native keywords discussed in the Differences section to look up information on the semantics of this specifier. respectively. The 16.8. as in the following example: bank2 int logEntry.5.7. negative values imply the object’s end address be aligned. CAVEATS 2.and 32-bit compilers used the aligned attribute with variables. change any occurrence of the aligned attribute. . albeit more limited. The alignment term must be a power of two. DS52053A-page 30  2012 Microchip Technology Inc.5.8.2 DIFFERENCES The 8-bit compilers have used the four qualifiers bank0.5.3 MIGRATION TO THE CCI For 8-bit compilers. i.MPLAB® XC8 C Compiler User’s Guide 2..and 32-bit compilers. as in the following example: char __attribute__((aligned(4)))mode. 2.7.8.5. to __bank().e.e.8. 2. 2..4 None. change any occurrence of the bankx qualifiers.3 MIGRATION TO THE CCI For 16. 2. memory placement.2 DIFFERENCES An alignment feature has never been implemented on 8-bit compilers. and start on an address that is a multiple of 2. __bank(2) int logEntry.4 CAVEATS This feature is not yet implemented on XC8. 2. Positive values request that the object’s start address be aligned. __align(4) char mode.

e.5. Some devices may not implement EEPROM. __eeprom int serialNos[4]. The current interrupt types are: <empty> Implement the default interrupt function low_priority The interrupt function corresponds to the low priority interrupt source (XC8 – PIC18 only) high_priority The interrupt function corresponds to the high priority interrupt source (XC8)  2012 Microchip Technology Inc. as in the following int mainSw __attribute__ ((space(eedata))). Stack-based (auto and parameter) variables cannot use the __eeprom specifier.Common C Interface 2. DS52053A-page 31 . For 16-bit compilers. The 16-bit compilers have used the space attribute to allocate variables to the memory space used for EEPROM.9.9 EEPROM Objects The __eeprom qualifier may be used to indicate that variables should be positioned in EEPROM. The type is a comma-separated list of keywords that indicate information about the interrupt function. eeprom.10 Interrupt Functions The __interrupt(type) specifier may be used to indicate that a function is to act as an interrupt service routine. Use the native keywords discussed in the Differences section to look up information on the semantics of this qualifier.9. change any occurrence of the eeprom qualifier. 2. 2.9. to __eeprom.5. as in the following example: eeprom char title[20].2 DIFFERENCES The 8-bit compilers have used the qualifier.3 MIGRATION TO THE CCI For 8-bit compilers.5. 2.5. __eeprom char title[20]. change any occurrence of the eedata space attribute. 2. Use of this qualifier for such devices will generate a warning..9. to indicate this meaning for some devices. this qualifier will work as expected for other 8-bit devices.4 CAVEATS XC8 does not implement the __eeprom qualifiers for any PIC18 devices. to int __eeprom mainSw.5.1 EXAMPLE The following shows a variable qualified using __eeprom.5. i. 2.

++tick_count.10. The 16. } } 2. respectively void __interrupt(high_priority) myIsr(void) void __interrupt(low_priority) myLoIsr(void) For 16-bit compilers.auto_psv. If the argument to the __interrupt specifier does not make sense for the target device.5. as in the following examples: void interrupt myIsr(void) void interrupt low_priority myLoIsr(void) to the following.10. 2.1 EXAMPLE The following shows a function qualified using __interrupt. Some devices may not implement interrupts. DS52053A-page 32  2012 Microchip Technology Inc.and 32-bit compilers have used the interrupt attribute to define interrupt functions. Use of this qualifier for such devices will generate a warning.3 MIGRATION TO THE CCI For 8-bit compilers. change any occurrence of the interrupt attribute.10.5. 2. Interrupt routines were by default high priority. change any occurrence of the interrupt qualifier.5. a warning or error will be issued by the compiler. as in the following example: void __attribute__((interrupt.MPLAB® XC8 C Compiler User’s Guide save(symbol-list) Save on entry and restore on exit the listed symbols (XC16) irq(irqid) Specify the interrupt vector associated with this interrupt (XC16) altirq(altirqid) Specify the alternate interrupt vector associated with this interrupt (XC16) preprologue(asm) Specify assembly code to be executed before any compiler-generated interrupt code (XC16) shadow Allow the ISR to utilise the shadow registers for context switching (XC16) auto_psv The ISR will set the PSVPAG register and restore it on exit (XC16) no_auto_psv The ISR will not set the PSVPAG register (XC16) Use the native keywords discussed in the Differences section to look up information on the semantics of this specifier.2 DIFFERENCES The 8-bit compilers have used the interrupt and low_priority qualifiers to indicate this meaning for some devices. . __interrupt(low_priority) void getData(void) { if (TMR0IE && TMR0IF) { TMR0IF=0.(irq(52)))) myIsr(void).

interrupt(IPL7AUTO).  2012 Microchip Technology Inc.11. the __interrupt() keyword takes two parameters.Common C Interface to void __interrupt(auto_psv. For 32-bit compilers. nomips16)) myisr1_6SRS(void) {} /* Determine IPL and context-saving mode at runtime */ void __attribute__((vector(2).5. or that individual structure members should not be aligned. } line. the vector number and the (optional) IPL value.4 None. nomips16)) myisr0_7A(void) {} void __attribute__((vector(1). Use the native keywords discussed in the Differences section to look up information on the semantics of this specifier. __pack struct DATAPOINT { unsigned char type.11. 2. struct LINETYPE { unsigned char type. int value. This specifier has no apparent effect since the device memory is byte addressable for all data objects. Change code which uses the interrupt attribute.11 Packing Objects The __pack specifier may be used to indicate that structures should not use memory gaps to align structure members. CAVEATS 2. long total.5.10. __pack int start. similar to these examples: void __attribute__((vector(0).2 DIFFERENCES The __pack specifier is a new CCI specifier available with XC8.IPL7AUTO) myisr0_7A(void) {} void __interrupt(1. Some compilers may not pad structures with alignment gaps for some devices and use of this specifier for such devices will be ignored. } x-point.and 32-bit compilers have used the packed attribute to indicate that a structure member was not aligned with a memory gap.(irq(52)))) myIsr(void). interrupt().IPL6SRS) myisr1_6SRS(void) {} /* Determine IPL and context-saving mode at runtime */ void __interrupt(2) myisr2_RUNTIME(void) {} 2. The 16.1 EXAMPLE The following shows a structure qualified using __pack as well as a structure where one member has been explicitly packed.5. 2.5. DS52053A-page 33 . interrupt(IPL6SRS). nomips16)) myisr2_RUNTIME(void) {} to void __interrupt(0.

5.12.12. CAVEATS DS52053A-page 34  2012 Microchip Technology Inc.5.12.and 32-bit compilers. 2. if required. int x[2] __attribute__ ((packed)). 2. change any occurrence of the deprecated attribute. For 16.5.4 None.and 32-bit compilers. void __deprecate getValue(int mode) { //.12 Indicating Antiquated Objects The __deprecate specifier may be used to indicate that an object has limited longevity and should not be used in new designs.4 None. as in the following example: int __attribute__(deprecated) intMask. }. 2. to: int __deprecate intMask. Alternatively..5. 2.3 MIGRATION TO THE CCI For 16. to: struct DOT { char a. The 16.5.5.12.11. __pack int x[2]. .and 32-bit compilers have used the deprecated attribute (note different spelling) to indicate that objects should be avoided if possible. or that better features have been developed and which should be used in preference.1 EXAMPLE The following shows a function which uses the __deprecate keyword. Use the native keywords discussed in the Differences section to look up information on the semantics of this specifier. change any occurrence of the packed attribute.MPLAB® XC8 C Compiler User’s Guide 2.2 DIFFERENCES No deprecate feature was implemented on 8-bit compilers. }. as in the following example: struct DOT { char a. It is commonly used by the compiler vendor to indicate that compiler extensions or features may become obsolete.11.3 MIGRATION TO THE CCI No migration is required for XC8. CAVEATS 2. you may pack the entire structure.5.. } 2.

.1 EXAMPLE The following shows a variable which uses the __section keyword. to: int __section("myVars") intMask.and 32-bit compilers have used the section attribute to indicate a different destination section name. You must reserve memory. Unlike with the pragma. which will contain the initial values. int __section("comSec") commonFlag. the new psect created with __section() does not inherit the flags of the psect in which the object would normally have been allocated.5. including any data bank. The compiler will also make no assumptions about the location of the object in the new section. Use the native keywords discussed in the Differences section to look up information on the semantics of this specifier. using the XC8 terminology)..Common C Interface 2. or psect. } For 16.13. This means that the new psect can be linked in any memory area. DS52053A-page 35 . The 16. described below. albeit at any address in that area. The __section() specifier allows objects that are initialized to be placed in a different psect.5.2 DIFFERENCES The 8-bit compilers have used the #pragma psect directive to redirect objects to a new section. Objects redirected to new psects using the pragma must always be linked in the same memory area. 2.. Objects allocated a different psect with __section() will be cleared by the runtime startup code.13. unlike objects which use the pragma. change any occurrence of the section attribute. This is typically used when the object has special and unique linking requirements which cannot be addressed by existing compiler features.5. Initialization of the object will still be performed even in the new psect. for any new psect created with a __section() specifier in the current XC8 compiler implementation. The __section() specifier works in a similar way to the attribute. 2.3 MIGRATION TO THE CCI For XC8. and locate via a linker option. The operation of the __section() specifier is different to this pragma in several ways.5. This will require the automatic allocation of an additional psect (whose name will be the same as the new psect prefixed with the letter i). change any occurrence of the #pragma psect directive.13.  2012 Microchip Technology Inc. such as #pragma psect text%%u=myText int getMode(int target) { //. } to the __section() specifier. as in the following example: int __attribute__((section("myVars"))) intMask..13 Assigning Objects to Sections The __section() specifier may be used to indicate that an object should be located in the named section (or psect. 2. as in int __section ("myText") getMode(int target) { //. The pragma cannot be used with objects that are initialized.and 32-bit compilers.

5. CAVEATS 2. FPR = ECIO_PLL16 No migration is required for 32-bit code. FOSC=XT.4 None.15 Manifest Macros The CCI defines the general form for macros that manifest the compiler and target device characteristics. as in the following example: _FOSC(CSW_FSCM_ON & EC_PLL16).g. These macros can be used to conditionally compile alternate source code based on the compiler or the target device. The 16-bit compilers have used a number of macros to specify the configuration settings.3 MIGRATION TO THE CCI For the 8-bit compilers.MPLAB® XC8 C Compiler User’s Guide 2. WDTPS = 0x1A 2.2 DIFFERENCES The 8-bit compilers have used the __CONFIG() macro for some targets that did not already have support for the #pragma config. state is a descriptive value (e. 2. The macros and macro families are details in Table 2-1. 2.. WDT).14. as in #pragma config WDTE=ON. #pragma config WDT=ON. 2. The pragma has the form: #pragma config setting = state|value where setting is a configuration setting descriptor (e. to: #pragma config FCKSMEM = CSW_ON_FSCM_ON.14. the __section() specifier cannot be used with any interrupt function.14 Specifying Configuration Bits The #pragma config directive may be used to program the configuration bits for a device.5.14. change any occurrence of the __CONFIG() macro.5. TABLE 2-1: Name __XC__ MANIFEST MACROS DEFINED BY THE CCI Meaning if defined Compiled with an MPLAB XC compiler Example __XC__ DS52053A-page 36  2012 Microchip Technology Inc.14.5. For the 16-bit compilers.4 CAVEATS With XC8. change any occurrence of the _FOSC() or _FBORPOR() macros attribute.g. ON) and value is a numerical value. CPD=ON No migration is required if the #pragma config was already used..13. Use the native keywords discussed in the Differences section to look up information on the semantics of this directive. The 32-bit compilers supported the use of #pragma config.1 EXAMPLE The following shows configuration bits being specified using this pragma. .5. such as __CONFIG(WDTEN & XT & DPROT) to the #pragma config directive.5. 2.5.

16 or 32) The family of the selected target device The selected target device name Example __CCI__ __XC8__ __dsPIC30F__ __18F452__ 2.1 EXAMPLE The following shows code which is conditionally compiled dependent on the device having EEPROM memory.15. 2.4 None. DS52053A-page 37 .5.15.15.15.5.Common C Interface TABLE 2-1: Name __CCI__ __XC##__ __DEVICEFAMILY__ __DEVICENAME__ MANIFEST MACROS DEFINED BY THE CCI Meaning if defined Compiler is CCI compliant and CCI enforcement is enabled The specific XC compiler used (## can be 8. and others have different names to previous symbols with identical meaning (for example __18F452 is now __18F452__). CAVEATS  2012 Microchip Technology Inc. but they are not compliant with the CCI.5.5. Old macros will continue to work as expected.3 MIGRATION TO THE CCI Any code which uses compiler-defined macros will need review.2 DIFFERENCES Some of these CCI macros are new (for example __CCI__). 2. #ifdef __XC16__ void __interrupt(__auto_psv__) myIsr(void) #else void __interrupt(low_priority) myIsr(void) #endif 2.

5. 2. 2. The argument is a C string literal which represents a single assembly instruction.3 MIGRATION TO THE CCI For 8-bit compilers change any instance of #asm . . 2. #endasm constructs to insert in-line assembly code. 2. asm("MOVLW _foobar").16..1 EXAMPLE The following shows a MOVLW instruction being inserted in-line.16.4 None. asm("MOVWF _i"). Use the native keywords discussed in the Differences section to look up information on the semantics of this statement.16. the instructions contained in the argument are device specific.or 32-bit compilers.5.16. No migration is required for the 16. asm("CLRFIi+1").and 32-bit compilers.5.MPLAB® XC8 C Compiler User’s Guide 2.. CAVEATS DS52053A-page 38  2012 Microchip Technology Inc.5..2 DIFFERENCES The 8-bit compilers have used either the asm() or #asm . #endasm so that each instruction in this #asm block is placed in its own asm() statement.5. Obviously..16 In-line Assembly The asm() statement may be used to insert assembly code in-line with C code. This is the same syntax used by the 16. for example: #asm MOVLW 20 MOVWF _i CLRF Ii+1 #endasm to asm("MOVLW20").

Common C Interface 2. A widget with the same name is available in MPLAB IDE v8 under the Compiler tab. DS52053A-page 39 . The widget in the MPLAB X IDE Project Properties to enable CCI conformance is Use CCI Syntax in the Compiler category. then the command-line options are --CCI for XC8 or -mcci for XC16/32.1.6 COMPILER FEATURES The following items detail compiler options and features that are not directly associated with source code that 2. CAVEATS  2012 Microchip Technology Inc.6. If you are not using this IDE. 2.1.6. 2.6.1 DIFFERENCES This option has never been implemented previously.6. 2.1 Enabling the CCI It is assumed you are using the MPLAB X IDE to build projects that use the CCI.1.2 MIGRATION TO THE CCI Enable the option.3 None.

MPLAB® XC8 C Compiler User’s Guide NOTES: DS52053A-page 40  2012 Microchip Technology Inc. .

The guide Installing and Licensing MPLAB XC C Compilers (DS52059) is available on www.2 “Invoking the Compiler”) with the option --VER. print an informative banner and quit.00\bin\xc8" --ver The compiler should run. it is best to verify its operation outside of MPLAB IDE to isolate possible problems. If an error is displayed.2.microchip. That banner indicates the operating mode.com.2 How Can I Tell if the Compiler has Activated Successfully? If you think the compiler may not have installed correctly or is not working.1 INTRODUCTION This section contains help and references for situations that are frequently encountered when building projects for Microchip 8-bit devices. How To’s 3. Click the links at the beginning of each section to assist finding the topic relevant to your question.2 INSTALLING AND ACTIVATING THE COMPILER This section details questions that might arise when installing or activating the compiler. under Windows. 3. DS52053B-page 41 . Start here: • • • • • • Installing and Activating the Compiler Invoking the Compiler Writing Source Code Getting My Application to Do What I Want Understanding the Compilation Process Fixing Code That Does Not Work 3.MPLAB® XC8 C COMPILER USER’S GUIDE Chapter 3. So. replacing the path information with a path that is relevant to your installation.1 How Do I Install and Activate My Compiler? Installation and activation of the license are performed simultaneously by the XC compiler installer. It provides details on single-user and network licenses. This option instructs the compiler to print version information and exit.2. run the compiler driver xc8 (see Section 4. Confirm that the operating mode is the one you requested. Try running the compiler from the command line to check for correct operation. type the following line. Some topics are indexed in multiple sections. Note: if it is not activated properly. the compiler will continue to operate. "C:\Program Files\Microchip\xc8\v1. as well as how to activate a compiler for evaluation purposes. From your terminal or DOS-prompt. or the compiler indicates Free mode. • How Do I Install and Activate My Compiler? • How Can I Tell if the Compiler has Activated Successfully? • Can I Install More Than One Version of the Same Compiler? 3. but only in the Free mode.  2012 Microchip Technology Inc. then activation was not successful. for example. You do not actually have to compile code.

00 and 1. For example. Compilers should be installed into a directory whose name is related to the compiler version.10\ DS52053B-page 42  2012 Microchip Technology Inc.3. This is reflected in the default directory specified by the installer.3 Can I Install More Than One Version of the Same Compiler? Yes. and you can easily swap between version by changing options in MPLAB IDE. . the compilers and installation process has been designed to allow you to have more than one version of the same compiler installed. C:\Program Files\Microchip\xc8\v1. the 1. see Section 3.MPLAB® XC8 C Compiler User’s Guide 3.2.4 “How Can I Select Which Compiler I Want to Build With?”.00\ C:\Program Files\Microchip\xc8\v1.10 XC8 compilers would typically be placed in separate directories.

2 How Do I Compile on the Command-line? The compiler driver is called xc8 for all 8-bit PIC devices. you select the compiler you wish to use in the Configuration category in the Project Properties dialog.exe.7 “XC8 Driver Options”. Avoid running the individual compiler applications (such as the assembler or linker) explicitly. The files that can be passed to the driver are listed and described in Section 4. You can compile and link in the one command. in Windows.3. Generating object files as an intermediate file for multi-step compilation will defeat many of the advantages of this technology.1 How Do I Compile from Within MPLAB X IDE? See the documentation that comes with MPLAB X IDE for information on how to set up a project. This application should be invoked for all aspects of compilation.g.3.. even if your project is spread among multiple source files. e. The driver is introduced in Section 4.4 How Can I Select Which Compiler I Want to Build With? to ensure you are running the correct driver if you have more than one installed.3. This is described in Section 4. Note that each of these compiler categories have several Option categories. then the final compilation and link step to produce one binary output.How To’s 3. • • • • • • • • • • • • • How Do I Compile from Within MPLAB X IDE? How Do I Compile on the Command-line? How Do I Compile Using a Make Utility? How Can I Select Which Compiler I Want to Build With? How Can I Change the Compiler's Operating Mode? What Do I Need to Do When Compiling to Use a Debugger? How Do I Build Libraries? How Do I Use Library Files In My Project? How Do I Know What Compiler Options Are Available and What They Do? How Do I Know What the Build Options in MPLAB IDE do? What is Different About an MPLAB IDE Debug Build? How Do I Stop the Compiler Using Certain Memory Locations? What Optimizations Are Employed By The Compiler? 3.3 INVOKING THE COMPILER This section discusses how the compiler is run. The command-line options to the driver are detailed in Section 4. the compilation is usually performed as a two-step process: first generating the intermediate files. It includes information about how to get the compiler to do what you want in terms of options and the build process itself. both on the command-line and from the MPLAB IDE. 3.3. DS52053B-page 43 . See 3.2 “Invoking the Compiler”.p1 extension). 3. it is named xc8. The options for that compiler are then shown in the XC8 Compiler and XC8 Linker categories. not an object file.3 “Multi-Step Compilation”. The XC8 compiler uses a unique technology called OCG which uses a different intermediate file format to traditional compilers (including XC16 and XC32)The intermediate file format used by XC8 is a p-code file (. It is located in the bin directory of the compiler distribution.3 “Input File Types”.2.3.3 How Do I Compile Using a Make Utility? When compiling using a make utility (such as make).  2012 Microchip Technology Inc. If you have one or more XC8 compilers installed.

the controls for that compiler are then shown by selecting the XC8 global options. along with the accompanying header files. see Section 1. 3. see Section 4. Libraries are more convenient because there are fewer files to deal with. . For example: XC8 --chip=16f877a --output=lpp lcd. you can either make all the C source and header files available so other developers can copy these into their projects. However. see Section 4. You can only select modes that your license entitles you to use.2 “Compiler Description and Documentation”) can be specified as a command line option when building on the command line. The Free mode is always available. under the Optimizations option selector. there is a Project Properties selector in the XC8 compiler category. nor settings for configuration bits or any other such data. When you have functions and data that are commonly used in applications. 3. If you are building under MPLAB X IDE. Compiling code from a library is also be fractionally faster. A list of XC8 compilers is shown in the Compiler Toolchain. can be linked into a project.10. See Section 4.4 How Can I Select Which Compiler I Want to Build With? The compilation and installation process has been designed to allow you to have more than one compiler installed at the same time.c io. the old-style LIB libraries are used for library routines written in assembly source. libraries do need to be maintained. It is recommended that even these libraries be rebuilt if your project is moving to a new compiler version. You can create a project in MPLAB X IDE and then build this project with different compilers by simply changing a setting in the project properties. Standard or PRO.8. see Section 4.c utils. None of these files should contain a main() function. see Section 4.MPLAB® XC8 C Compiler User’s Guide 3.5 How Can I Change the Compiler's Operating Mode? The compiler’s operating mode (Free. DS52053B-page 44  2012 Microchip Technology Inc.3. Standard or PRO can be selected if you have purchased a license for those modes.37 “--MODE: Choose Compiler Operating Mode”. libraries can be built by listing all the files that are to be included into the library on the command line.3. To select which compiler is actually used when building a project under MPLAB X IDE.10 “-O: Specify Output File” or just rename the file. XC8 must use LPP libraries for library routines written in C.8.8. Note that each category has several panes which can be selected from a pull-down menu that is near the top of the pane. Use the --OUTPUT=lpp option. These reveal a pane of options on the right.lpp. Select the XC8 compiler you require. Alternatively you can bundle these source files up into a library which. Select the Configuration category in the Project Properties dialog (Conf: [default]).c creates a library file called lcd.1 “The Compiler Applications” for general information on the library types available and how they fit into the compilation process.6 How Do I Build Libraries? Note that XC8 uses a different code generation framework (OCG) which uses additional library files to those used by traditional compilers (including XC16 and XC32). go to the Project properties dialog. You can specify another name using the -O option. Once selected.3. XC8 Compiler and XC8 Linker categories. Using the compiler driver.2 “Compiler Category”. on the far right.44 “--OUTPUT= type: Specify Output File Type” to indicate that a library file is required.3.

see Section 4.3 “What Do I Need to Do When Compiling to Use a Debugger?”.3. 3. see Section 3. it will give specific information on that option. If you are compiling in MPLAB X IDE.How To’s 3. memory is always reserved if you select a debugger hardware tool in your project. DS52053B-page 45 . or in MPLAB IDE version 8.8 “Option Descriptions” in this user’s guide.8 “Option Descriptions”) has cross references. there are separate build buttons and menu items to build a project and debug a project.9 “MPLAB IDE V8 Universal Toolsuite Equivalents”).9 What is Different About an MPLAB IDE Debug Build? The Debug/Release pull-down widget in the MPLAB IDE version 8 toolbar indicates whether the build should be a debug or release build.10 “MPLAB X Universal Toolsuite Equivalents”) and MPLAB IDE version 8 (Section 4.3.7 How Do I Know What Compiler Options Are Available and What They Do? A list of all compiler options can be obtained by using the --HELP option on the command line.5. In MPLAB v8. memory will be reserved for your debugger (if selected) only when you perform a debug build.3. etc (see Section 5. but for the XC8 compiler. see Section 4. being an option name. see Section 4. There are many differences in terms of the IDE. If you give the --HELP option an argument.  2012 Microchip Technology Inc.9 “MPLAB IDE V8 Universal Toolsuite Equivalents”.10 “MPLAB X Universal Toolsuite Equivalents”.14. The main difference is the setting of a preprocessor macro called __DEBUG to be 1 when a debug is selected. This macro is not defined if it is not a debug build. You may make code in your source conditional on this macro using #ifdef directives. Some compiler errors are easier to track down after performing a debug build. to the corresponding section which relates to accessing that option from the IDE. In MPLAB X IDE.2 “Preprocessor Directives”) so that you can have your program behave differently when you are still in a development cycle. there is very little that is different between the two. In MPLAB X. 3. all options are all listed in Section 4. Alternatively. where appropriate. There are two separate sections for MPLAB X IDE (Section 4.33 “--HELP: Display Help”. The section in the user’s guide that lists all command-line driver options (Section 4.8.8 How Do I Know What the Build Options in MPLAB IDE do? The widgets and controls in the MPLAB IDE Build options in most instances map directly to one command-line driver option or suboption.

Most importantly. (int). unsigned int i.4. or remove it. for example.1 C Language Specifics This section discusses source code issues that are directly relates to the C language itself but which are commonly asked. The compiler will typically produce a warning concerning the potential loss of data by the truncation.MPLAB® XC8 C Compiler User’s Guide 3. Consider the example: unsigned long l. a long type is being assigned to a int type.1. conversion of one type to another must be done with caution and only when absolutely necessary. which may not be correct. the code will work the in the same way. . otherwise the contents of l will continue to be truncated by the assignment.This is called an implicit type conversion. then you must remember to adjust the cast. • • • • When Should I Cast Expressions? Can Implicit Type Conversions Change the Expected Results of My Expressions? How Do I Enter Non-english Characters Into My Program? How Can I Use a Variable Defined in Another Source File? WHEN SHOULD I CAST EXPRESSIONS? 3. The compiler will automatically perform a type conversion from the type of the expression on the right of the assignment operator (long) to the type of the lvalue on the left of the operator (int). The compiler knows the types of both operands and will perform the conversion accordingly. It has been subdivided into sections listed below. e. there is the potential for mistakes if the code is later changed. the type of i is changed to a long.4. In all cases.1 Expressions can be explicitly case using the cast operator -.g. if you had: i = (int)l.. the warning issued by the compiler will not be produced if the cast is in place. i = l. For example. if in future.4 WRITING SOURCE CODE This section presents issues pertaining to the source code you write. • • • • • • • C Language Specifics Device-Specific Features Memory Allocation Variables Functions Interrupts Assembly Code 3. Here. A cast to type int is not required and should not be used in the above example if a long to int conversion was intended. DS52053B-page 46  2012 Microchip Technology Inc. and the assignment will truncate the value in l.a type in round brackets. If you did use a cast. but.

1.e. see Section 5. So if i contained 7 and j contained 2. Changing the type of an operand can change the value of the final expression so it is very important that you understand the type C Standard conversion rules that apply when dealing with binary operators. This can also be the source of many problems.1 “Integral Promotion”. float fl. A declaration consists of the keyword extern in addition to the type and name of the variable as specified in its definition.2 “Auto Variable Allocation and access”).14.1. then adding a declaration for that variable in the current file will allow you to access it. the types of operands to binary operators are usually changed so that they have a common type as specified by the C Standard. extern int systemStatus.2.6.g.3 HOW DO I ENTER NON-ENGLISH CHARACTERS INTO MY PROGRAM? The ANSI standard and MPLAB XC8 do not support extended characters set in character and string literals in the source character set. If you wanted the division to be performed in a float format. The more warnings the compiler produces. i.4 HOW CAN I USE A VARIABLE DEFINED IN ANOTHER SOURCE FILE? Provided the variable defined in the other source file is not static (see Section 5.1.2.6 “Constant Types and Formats” to see how these characters can be entered using escape sequences.0) and then assigned to fl. the division will yield 3 and this will be implicitly converted to a float type (3.4.5. In this case integer division is performed..5. then a cast is necessary: fl = (float)i/j. This is part of the C language and your favorite C text will give you more information.1 “When Should I Cast Expressions?”.1 “Static Variables”) or auto (see Section 5. it will limit the scope of the variable to that function.5. In addition. the better chance you have of finding potential bugs in your code.How To’s Only use a cast in situations where the types used by the compiler are not the types that you require. fl = i/j. 3. The result assigned to fl now be 3. Often. if you place the declaration inside a function. See Section 5. An explicit cast may suppress warnings that might otherwise have been produced.1. see Section 3. The position of the declaration in the current file determines the scope of the variable. For example consider the result of a division assigned to a floating point variable: int i.1.  2012 Microchip Technology Inc. placed outside of a function allows access to the variable in all functions for the remainder of the current file.4. declarations are placed in header files and these are then #included into the C source code.2 “Preprocessor Directives”. then the rounded integer result is converted to a float format. 3.4. j. 3.4. DS52053B-page 47 . e. You can manually change the type of an operand by casting.2 CAN IMPLICIT TYPE CONVERSIONS CHANGE THE EXPECTED RESULTS OF MY EXPRESSIONS? Yes! The compiler will always use integral promotion and there is no way to disable this.4. (Casting either i or j will force the compiler to encode a floating-point division). see Section 5.

See Section 3.2 Device-Specific Features This section discusses the code that needs to be written to set up or control a feature that is specific to Microchip PIC devices. You can have the STATUS register saved into a location that is later accessible from C code so that the cause of Reset can be determined by the application once it is running again. Individual bit-wide variables are defined which are mapped over the bits in the SFR.3.4. 3.3. 3.3 HOW DO I DETERMINE THE CAUSE OF RESET ON MID-RANGE PARTS? The TO and PD bits in the STATUS register allow you to determine the cause of a Reset.1 These should be set in your code using either a macro or pragma. Earlier versions of MPLAB IDE allowed you to set these bits in a dialog.6 “Using SFRs From C Code”. see Section 5. Since these are C variables.10.4. they can be used like any other C variable and no new syntax is required to access these registers. Bit-fields are also available in structures which map over the SFR as a whole.3. However.5 “How Do I Find The Names Used to Represent SFRs and Bits?” if these names are not recognized.4.4 HOW DO I ACCESS SFRS? The compiler ships with header files.1. . that define variables which are mapped over the top of memory-mapped SFRs. DS52053B-page 48  2012 Microchip Technology Inc.4. • • • • • • How Do I Set the Configuration Bits? How Do I Use the PIC’s ID Locations? How Do I Determine the Cause of Reset on Mid-range Parts? How Do I Access SFRs? How Do I Stop the Compiler Using Certain Memory Locations? What Do I Need to Do When Compiling to Use a Debugger? HOW DO I SET THE CONFIGURATION BITS? 3. see Section 5.3. See Section 5. these bits are quickly overwritten by the runtime startup code that is executed before main is executed. Bits within SFRs can also be accessed.7 “ID Locations”.2.4. See Section 5.2. see Section 5.1 “Runtime Startup Code”.3 “Device Header Files”.4 “STATUS Register Preservation”. but MPLAB X IDE requires that they be specified in your source code.2.2.2.2 HOW DO I USE THE PIC’S ID LOCATIONS? There is a supplied macro or pragma that allows these values to be programmed.4.MPLAB® XC8 C Compiler User’s Guide 3. 3. See Section 5. The name assigned to the variable is usually the same as the name specified in the device data sheet.10. You can use either in your code.5 “Configuration Bit Access” for how these are set.

4.4 “Changing the Default Function Allocation”. see Section 5.6 “How Do I Fix a "Can’t find space.4 “Changing the Default Auto Variable Allocation” for information on moving auto variables.h> as this will include the definition for all the SFR variables and bits within those.3 • • • • • Memory Allocation Here are questions relating to how your source code affects memory allocation. The are typically left in the source file directory if you are compiling on the command line. Section 3.7.  2012 Microchip Technology Inc. DS52053B-page 49 .2 “Changing the Default Allocation” for moving program-space variables.4 “How Do I Access SFRs?”. These file have a ..5 HOW DO I FIND THE NAMES USED TO REPRESENT SFRS AND BITS? Special function registers and the bits within those are accessed via special variables that map over the register.4. How Do I Position Variables at an Address I Nominate? How Do I Position Functions at an Address I Nominate? How Do I Place Variables in Program Memory? How Do I Stop the Compiler Using Certain Memory Locations? Why are some objects positioned into memory that I reserved? HOW DO I POSITION VARIABLES AT AN ADDRESS I NOMINATE? 3.4..2." Error?”. but you must also ensure that absolute variables do not overlap. This means that the address you specify is used in preference to the variable’s symbol in generated code.2.5.4 “Absolute Variables”. by using the @ address construct. Variables placed in the middle of banks can cause havoc with the allocation of other variables and lead to "Can’t find space" errors.5. Since you nominate the address. see Section 5.3 “Changing the Default Non-Auto Variable Allocation” for moving non-auto variables and Section 5..5. Functions placed in the middle of pages can cause havoc with the allocation of other functions and lead to "Can’t find space" errors.5. by using the @ address construct.7.2 HOW DO I POSITION FUNCTIONS AT AN ADDRESS I NOMINATE? The easiest way to do this is to make the functions absolute. but an easier way is to look in any of the preprocessed files left behind after a previous compilation.4.pre extension and there will be one file with the same base name as each source file in your project. If you are compiling under MPLAB X IDE.3. however.3. you have full control over where objects are positioned.2.h> header file to find the device-specific header file which allows access to these special variables. see Section 3.4. This means that the address you specify is used in preference to the variable’s symbol in generated code. see Section 3. See also Section 5.1. Look in the preprocessed file for any source file that include <xc.2. Section 5." Error?”. You can work your way through the <xc. Since you nominate the address. or under build/default/debug for debug builds. the preprocessed file(s) are left under the build/default/production directory of your project for regular builds. but must also ensure that absolute functions do not overlap..How To’s 3.8. 3. the names of these variables sometimes differ from those indicated in the data sheet for the device you are using.3.6 “How Do I Fix a "Can’t find space. 3. you have full control over where functions are positioned.1 The easiest way to do this is to make the variable absolute.

so that they can be positioned at an address you nominate.4.3 HOW DO I PLACE VARIABLES IN PROGRAM MEMORY? The const qualifier implies that the qualified variable is read only. If you attempt to assign a value that is not in this set. the more values can be exactly represented in the set and the average error due to the rounding is reduced. Since floating-point variables only have a finite number of bits to represent the values they are assigned. but these options allow you to reserve parts of this memory. The --RAM and --ROM options allow you to adjust the ranges of data and program memory. In MPLAB X IDE set the Display Column Value As popup menu to IEEE float (24 bit). The more bits used by the mantissa in the floating-point variable.5. • • • • • • • • • • • Why Are My Floating-point Results Not Quite What I Am Expecting? How Can I Access Individual Bits of a Variable? How Long Can I Make My Variable and Macro Names? How Do I Share Data Between Interrupt and Main-line Code? How Do I Position Variables at an Address I Nominate? How Do I Place Variables in Program Memory? How Do I Place Variables in The PIC18’s External Program Memory? How Can I Rotate a Variable? How Do I Utilize All the RAM Banks on My Device? How Do I Utilize the Linear Memory on Enhanced Mid-range PIC Devices? How Do I Find Out Where Variables and Functions Have Been Positioned? WHY ARE MY FLOATING-POINT RESULTS NOT QUITE WHAT I AM EXPECTING? 3. . it is rounded to the nearest value.4 Variables This examines questions that relate to the definition and usage of variables and types within a program.3.8. make sure that if you are watching floating-point variables in MPLAB IDE that the type and size of these match how they are defined.8. Whenever floating-point arithmetic is performed.2 “Absolute Objects in Program Memory”. set the types to IEEE Float in both IDEs.3. all the available on-chip memory is available for use. when you build. see Section 5. see Section 4. The size of the floating point type can be adjusted for both float and double types. they will hold an approximation of their assigned value. Variables qualified const can also be made absolute.1 First. thus freeing valuable data RAM. As a consequence of this.48 “--RAM: Adjust RAM Ranges” and Section 4.4. If the variable is a 32-bit floating point object.4.4 HOW DO I STOP THE COMPILER USING CERTAIN MEMORY LOCATIONS? Memory can be reserved when you build. For 24-bit floating point variables (whether they have type float or double) ensure that the Format in the variable properties is set to IEEE float MPLAB IDE v8. see Section 5.24 “--DOUBLE: Select Kind of Double Types”.5. see Section 5.3 “Floating-Point Data Types”.31 “--FLOAT: Select Kind of Float Types” and Section 4.4. 3.MPLAB® XC8 C Compiler User’s Guide 3.4. A floating-point variable can only hold one of a set of discrete real number values. 3.4.3 “Variables in Program Space”.49 “--ROM: Adjust ROM Ranges”. See Section 4. rounding also occurs. DS52053B-page 50  2012 Microchip Technology Inc. This can also lead to results that do not appear to be correct.8.8. respectively. any variables (except for auto variables or function parameters) qualified const are placed in program memory.4. By default.

bit.2.4. or any bit within that variable independently (using var. bit) setbit(var. b5:1.2 “Bit-Fields in Structures”) can be defined.b0 through var. which will almost certainly lead to code failure.1 “Bit Data Types and Variables”) as well as bit-fields in structures.g.4.  2012 Microchip Technology Inc. set or clear the bits within the variable using a mask value and logical operations. respectively.4. but it does not actually state what this number is and it varies from compiler to compiler.2 HOW CAN I ACCESS INDIVIDUAL BITS OF A VARIABLE? There are several ways of doing this. struct { unsigned b0:1. b3:1.4. b2:1.byte). DS52053B-page 51 . For XC8. the first 255 characters are significant. but this can be reduced using the -N option. such as the following. b1:1. bit) ((var) & (1 <<(bit))) ((var) |= (1 << (bit))) ((var) &= ~(1 << (bit))) These. #define #define #define testbit(var. b4:1. as well as preprocessor macro names. Note that the compiler does support bit variables (see Section 5. the more portable your code.4.3 HOW LONG CAN I MAKE MY VARIABLE AND MACRO NAMES? The C Standard indicates that a only a number initial characters in an identifier are significant.bitv. set the corresponding bit in var. b6:1. } bitv. they are considered to represent the same object. bit) clrbit(var. Alternatively. e. } var.How To’s 3.4.8. test to see if bit number.bitv. b7:1. 3. Using the -N option allows the compiler to check that your identifiers conform to a specific length. union both { unsigned char byte. var.9 “-N: Identifier Length”. If two identifiers only differ in the nonsignificant part of the name. see Section 4.b7). This option affects variable and function names. The few character there are in your variable names.4. in the integer. The simplest and most portable way is to define an integer variable and use macros to read. is set. and clear the corresponding bit in var. This allows you to access byte as a whole (using var. a union of an integer variable and a structure with bit-fields (see Section 5.

and can encode. a large number of small functions. the smaller the function.8.3 “Allocation of Executable Code”.3 HOW DO I MAKE A FUNCTION INLINE? You can ask the compiler to inline a function by using the inline specifier. What is the Optimum Size For Functions? How Can I Tell How Big a Function Is? How Do I Know What Resources Are Being Used by Each Function? How Do I Find Out Where Variables and Functions Have Been Positioned? How Do I Use Interrupts in C? How Do I Stop An Unused Function Being Removed? How Do I Make a Function Inline? WHAT IS THE OPTIMUM SIZE FOR FUNCTIONS? 3. Do not confuse this specifier with the inline pragma (Section 5. 3. DS52053B-page 52  2012 Microchip Technology Inc. This is only a suggestion to the compiler and may not always be obeyed.5 • • • • • • • Functions This section examines questions that relate to functions. functions of such a size should be avoided and split into smaller routines where possible. Although the compiler will allow. In the embedded programming world. This is sufficient to prevent the function removal optimization from being performed.5.4 “The #pragma Intrinsic Directive”) which is for functions that have no corresponding source code and which will be specifically expanded by the code generator during compilation.4.5. the easier it is for the linker to allocate them to memory without errors. It is much easier to describe and debug the operation of a function which performs a small number of tasks and they typically have less side effects. With all devices. .12.14.4. PIC18 devices are less affected by internal memory paging and the instruction set allows for calls and jumps to any destination with no penalty.4.4. which can be the source of coding errors. see Section 5. The PIC10/12/16 devices use pages in the program memory which is where the function code is stored and executed.1 “Equivalent Assembly Symbols”). You only have to reference the symbol in this file.4.5. so a compromise is often necessary. If a function is so large as to cross a page boundary. the source code for functions should be kept small as this aids in readability and debugging.MPLAB® XC8 C Compiler User’s Guide 3.2 HOW DO I STOP AN UNUSED FUNCTION BEING REMOVED? If a C function’s symbol is referenced in hand-written assembly code. the function will never be removed. even if it is not called or never had its address taken in C code. see Section 5. Create an assembly source file and add this file to your project. may use the longer form of jump on each iteration.1 Generally speaking. functions whose size (the size of the assembly code they generate) exceeds that of a program memory page. or other code constructs that require jumps within that function. so the file can contain the following GLOBAL _myFunc where myFunc is the C name of the function in question (note the leading underscore in the assembly name. then loops. 3. and the calls necessary to execute them may result in excessive memory and stack usage. but you should still endeavor to keep functions as small as possible. The assembly call and jump sequences to locations in other pages are much longer than those made to destinations in the same page.3.

see Section 5. and PIC18 devices implement two separate interrupt vector locations and use a simple priority scheme. In C source code.6.4. Prior to any interrupt occurring. If necessary. “Library Functions”.1 Ideally. • How Do I Use Interrupts in C? • How Can I Make My Interrupt Routine Faster? • How Do I Share Data Between Interrupt and Main-line Code? 3.6 “How Can I Make My Interrupt Routine Faster?” for suggestions to enhance real-time performance.6. 3. Macros are already provided which in-line all these instructions.12.7 “Register Usage” for those registers used by the compiler.9. This offers some degree of protection from interaction between compiler-generated and hand-written assembly code. see Section 5. the function prototype must specify no parameters and a void return type.2 “#asm.4. mid-range devices utilize a single interrupt vector. If you wish to implement the low priority interrupt function on PIC18 devices. • • • • • How Should I Combine Assembly and C Code? What do I need Other than Instructions in an Assembly Source File? What do I need Other than Instructions in an Assembly Source File? How Can I Access SFRs From Within Assembly Code? What Things Must I Manage When Writing Assembly Code? HOW SHOULD I COMBINE ASSEMBLY AND C CODE? 3. See Section 5. Such functions save/restore program context before/after executing the function body code and a different return instruction is used. your program must ensure that peripherals are correctly configured and that interrupts are enabled. but see Section 3. Aside from the interrupt qualifier. you must specify the priority of interrupt sources by writing the appropriate SFRs. any hand-written assembly should be written as separate routines that can be called.How To’s 3.7. see Section 5.7 Assembly Code This section examines questions that arise when writing assembly code as part of a C project.1 HOW DO I USE INTERRUPTS IN C? First. Such code can be placed into a separate assembly module that can be added to your project. #endasm and asm()”.9. On PIC18 devices.4 “Enabling Interrupts”. SLEEP or CLRWDT.  2012 Microchip Technology Inc.9. see Section 5. be aware of what interrupt hardware is available on your target device. The code added in-line should ideally be limited to instructions such as NOP.12.1 “Integrating Assembly Language Modules”. Code inside the interrupt function can do anything you like. More complex in-line assembly that changes register contents and the device state can cause code failure if precautions are not taken and should be used with caution. a function can be written to act as the interrupt service routine by using the interrupt qualifier.1 “Writing an Interrupt Service Routine”. Baseline PIC devices do not implement interrupts at all. use the low_priority keyword as well as the interrupt qualifier. assembly code can be added in-line with C code using either of two methods.3 “Context Switching”. DS52053B-page 53 . There must be no more than one interrupt function for each interrupt vector implemented on the target device.6 Interrupts Interrupt and interrupt service routine questions are discussed in this section. see Section 5.4.4. see Appendix A.

This is done by one or more assembly instructions.1. Specifically specifying the volatile qualifier in C code is preferred as it makes it clear that external code may access the object.9. 3. Bank selection is not be required if the object is in common memory. There is no guarantee that you will be able to access symbols generated by the compilation of C code.12.2 “Volatile Type Qualifier”.3 “Interaction Between Assembly and C Code”. although no type information is present.4. defined in Section 6. This directive is not needed and should not be used if the symbol is defined in the same module as your assembly code.MPLAB® XC8 C Compiler User’s Guide 3. • Whenever accessing a RAM variable. Check your device data sheet to see the memory architecture of your device. This is the assembly equivalent of a C declaration.4.1 “GLOBAL” which is used to make symbols accessible across multiple source files.12.9. see Section 6.7. and the instructions and registers which control bank selection.4. Common directives required are mentioned below.4. Instruct the assembler that the symbol is defined elsewhere by using the GLOBAL assembler directive. 3.4.7. The BANKSEL pseudo instruction can be used to simplify this process. Any C variable accessed from assembly code will be treated as if it were qualified volatile.9. .4.7. Header files are provided with the compiler so that you do not need to define these yourselves.9 “Assembler Directives”. See Section 5.2 “Bank and Page Selection”.1 “GLOBAL”.15. see Section 6.2 WHAT DO I NEED OTHER THAN INSTRUCTIONS IN AN ASSEMBLY SOURCE FILE? Assembly code typically needs assembler directives as well as the instructions themselves.3 “PSECT” for information on the directive used to create and specify psects.4. The exact code is based on the device you are using and the location of the variable.5 WHAT THINGS MUST I MANAGE WHEN WRITING ASSEMBLY CODE? If you are hand-writing assembly code there are several things that you must take control of.7. see Section 6. The other commonly used directive is GLOBAL. and they are detailed in Section 5.7. see Section 5.4 HOW CAN I ACCESS SFRS FROM WITHIN ASSEMBLY CODE? The safest way to gain access to SFRs in assembly code is to have symbols defined in your assembly code that equate to the corresponding SFR address.4.4.1 “Program Sections” for general information on psects. even code that accesses the SFR you require.3. There is a mapping between the symbols used in the C source and those used in the assembly code generated from this source.3 HOW DO I ACCESS C OBJECTS FROM ASSEMBLY CODE? Most C objects are accessible from assembly code. The operation of all the directives are described in the subsections of Section 6.4. you must ensure that the bank of the variable is selected before you read or write the location. All assembly code must be placed in a psect so it can be manipulated as a whole by the linker and placed in memory. DS52053B-page 54  2012 Microchip Technology Inc. (which is called the access bank on PIC18 devices) or if you are using an instruction that takes a full address (such as the MOVFF instruction on PIC18 devices). Failure to select the correct bank will lead to code failure.2 “Accessing Registers from Assembly Code”. Your assembly should access the assembly-equivalent symbols which are detailed in Section 5. 3.

How To’s
• You must ensure that the address of the RAM variable you are accessing has been masked so that only the bank offset is being used as the instruction’s file register operand. This should not be done if you are using an instruction that takes a full address (such as the MOVFF instruction on PIC18 devices). Check your device data sheet to see what address operand instructions requires. Failure to mask an address may lead to a fixup error (see Section 3.7.8 “How Do I Fix a Fixup Overflow Error?”) or code failure. The BANKMASK macro can truncate the address for you, see Section 5.12.3.2 “Accessing Registers from Assembly Code”. • Before you call or jump to any routine, you must ensure that you have selected the program memory page of this routine using the appropriate instructions. You can either use the PAGESEL pseudo instruction, see Section 6.4.1.2 “Bank and Page Selection”, or the FCALL or LJMP pseudo instructions (not required on PIC18 devices), see Section 6.4.1.4 “Long Jumps and Calls” which will automatically add page selection instructions, if required. • You must ensure that any RAM used for storage has memory reserved. If you are only accessing variables defined in C code, then reservation is already done by the compiler. You must reserve memory for any variables you only use in the assembly code using an appropriate directive such as DS or DABS, see Section 6.4.9.10 “DS” or Section 6.4.9.11 “DABS”. It is often easier to define objects in C code rather than in assembly. • You must place any assembly code you write in a psect (see Section 6.4.9.3 “PSECT” for the directive to do this and Section 5.15.1 “Program Sections” for general information about psects). A psect you define may need flags (options) to be specified. Pay particular note to the delta, space and class flags (see Section 6.4.9.3.4 “Delta”, Section 6.4.9.3.13 “Space” and Section 6.4.9.3.3 “Class”). If these are not set correctly, compile errors or code failure will almost certainly result. If the psect specifies a class and you are happy with it being placed anywhere in the memory range defined by that class (see Section 7.2.1 “-Aclass =low-high,...”), it does not need any additional options to be linked; otherwise, you will need to link the psect using a linker option (see Section 7.2.19 “-Pspec” for the usual way to link psects and Section 4.8.7 “-L-: Adjust Linker Options Directly” which indicates how you can specify this option without running the linker directly). Assembly code that is placed in-line with C code will be placed in the same psect as the compiler-generated assembly and you should not place this into a separate psect. • You must ensure that any registers you write to in assembly code are not already in used by compiler-generated code. If you write assembly in a separate module, then this is less of an issue as the compiler will, by default, assume that all registers are used by these routines (see Section 5.7 “Register Usage”, registers). No assumptions are made for in-line assembly (see Section 5.12.2 “#asm, #endasm and asm()”) and you must be careful to save and restore any resources that you use (write) and which are already in use by the surrounding compiler-generated code.

 2012 Microchip Technology Inc.

DS52053B-page 55

MPLAB® XC8 C Compiler User’s Guide
3.5 GETTING MY APPLICATION TO DO WHAT I WANT
This section provides programming techniques, applications and examples. It also examines questions that relate to making an application perform a specific task. • • • • • • • • • • • What Can Cause Glitches on Output Ports? How Do I Link Bootloaders and Downloadable Applications? What Do I Need to Do When Compiling to Use a Debugger? How Can I Have Code Executed Straight After Reset? How Do I Share Data Between Interrupt and Main-line Code? How Can I Prevent Misuse of My Code? How Do I Use Printf to Send Text to a Peripheral? How Do I Calibrate the Oscillator on My Device? How Do I Place Variables in The PIC18’s External Program Memory? How Can I Implement a Delay in My Code? How Can I Rotate a Variable?

3.5.1

What Can Cause Glitches on Output Ports?

In most cases, this is caused by using ordinary variables to access port bits or the entire port itself. These variables should be qualified volatile. The value stored in a variable mapped over a port (hence the actual value written to the port) directly translates to an electrical signal. It is vital that the values held by these variables only change when the code intends them to, and that they change from their current state to their new value in a single transition. See Section 5.4.7.2 “Volatile Type Qualifier”. The compiler attempts to write to volatile variables in one operation.

3.5.2

How Do I Link Bootloaders and Downloadable Applications?

Exactly how this is done depends on the device you are using and your project requirements, but the general approach when compiling applications that use a bootloader is to allocate discrete program memory space to the bootloader and application so they have their own dedicated memory. In this way the operation of one cannot affect the other. This will require that either the bootloader or the application is offset in memory. That is, the Reset and interrupt location are offset from address 0 and all program code is offset by the same amount. On PIC18 devices, typically the application code is offset, and the bootloader is linked with no offset so that it populates the Reset and interrupt code locations. The bootloader Reset and interrupt code merely contains code which redirects control to the real Reset and interrupt code defined by the application and which is offset. On mid-range devices, this is not normally possible to perform when interrupts are being used. Consider offsetting all of the bootloader with the exception of the code associated with Reset, which must always be defined by the bootloader. The application code can define the code linked at the interrupt location. The bootloader will need to remap any application code that attempts to overwrite the Reset code defined by the bootloader. The option --CODEOFFSET, see Section 4.8.22 “--CODEOFFSET: Offset Program Code to Address”, allows the program code (Reset and vectors included) to be moved by a specified amount. The option also restricts the program from using any program memory from address 0 (Reset vector) to the offset address. Always check the map file, see Section 7.4.2 “Contents”, to ensure that nothing remains in reserved areas.

DS52053B-page 56

 2012 Microchip Technology Inc.

How To’s
The contents of the HEX file for the bootloader can be merged with the code of the application by adding the HEX file as a project file, either on the command line, or in MPLAB IDE. This results in a single HEX file that contains the bootloader and application code in the one image. HEX files are merged by the HEXMATE application, see Section 8.6 “HEXMATE”. Check for warnings from this application about overlap, which may indicate that memory is in use by both bootloader and the downloadable application.

3.5.3

What Do I Need to Do When Compiling to Use a Debugger?

You can use debuggers, such as ICD3 or REALICE, to debug code built with the XC8 compiler. These debuggers use some of the data and program memory of the device for its own use, so it is important that your code does not also use these resources. There is a command-line option, see Section 4.8.23 “--DEBUGGER: Select Debugger Type”, that can be used to tell the compiler which debugger is to be used. The compiler can then reserve the memory used by the debugger so that your code will not be located in these locations. In the MPLAB X IDE, the appropriate debugger option is specified if you perform a debug build. It will not be specified if you perform a regular Build Project or Clean and Build. In MPLAB IDE v8, it is recommended that you select Auto from the Debugger in the Linker tab of the Build Options dialog. This way, the debugger indicated to the compiler will be the same as that selected for the project. This option always has an effect. Select no debugger for a release build. Since some device memory is being used up by the debugger, there is less available for your program and it is possible that your code or data may no longer fit in the device when a debugger is selected. Note that which specific memory locations used by the debuggers is an attribute of MPLAB IDE, not the device. If you move a project to a new version of the IDE, the resources required may change. For this reason, you should not manually reserve memory for the debugger, or make any assumptions in your code as to what memory is used. A summary of the debugger requirements is available in the MPLAB IDE help files. To verify that the resources reserved by the compiler match those required by the debugger, do the following. Compile your code with and without the debugger selected and keep a copy of the map file produced for both builds. Compare the linker options in the map files and look for changes in the -A options, see Section 7.2.1 “-Aclass =low-high,...”. For example, the memory defined for the CODE class with no debugger might be specified by this option:
-ACODE=00h-0FFh,0100h-07FFh,0800h-0FFFhx3

and with the ICD3 selected as the debugger, it becomes:
-ACODE=00h-0FFh,0100h-07FFh,0800h-0FFFhx2,01800h-01EFFh

This shows that a memory range from 1F00 to 1FFF has been removed by the compiler and cannot be used by your program. See also Section 3.6.16 “Why are some objects positioned into memory that I reserved?”.

3.5.4

How Can I Have Code Executed Straight After Reset?

A special hook has been provided so you can easily add special "powerup" assembly code which will be linked to the Reset vector, see Section 5.10.2 “The Powerup Routine”. This code will be executed before the runtime startup code is executed, which in turn is executed before the main function, see Section 5.10 “Main, Runtime Startup and Reset”.

 2012 Microchip Technology Inc.

DS52053B-page 57

MPLAB® XC8 C Compiler User’s Guide
3.5.5 How Do I Share Data Between Interrupt and Main-line Code?
Variables accessed from both interrupt and main-line code can easily become corrupted or mis-read by the program. The volatile qualifier (see Section 5.4.7.2 “Volatile Type Qualifier”) tells the compiler to avoid performing optimizations on such variables. This will fix some of the issues associated with this problem. The other issues relates to whether the compiler/device can access the data atomically. With 8-bit PIC devices, this is rarely the case. An atomic access is one where the entire variable is accessed in only one instruction. Such access is uninterruptable. You can determine if a variable is being accessed atomically by looking at the assembly code the compiler produces in the assembly list file, see Section 6.6 “Assembly List Files”. If the variable is accessed in one instruction, it is atomic. Since the way variables are accessed can vary from statement to statement it is usually best to avoid these issues entirely by disabling interrupts prior to the variable being accessed in main-line code, then re-enable the interrupts afterwards, see Section 5.9.4 “Enabling Interrupts”.

3.5.6

How Can I Prevent Misuse of My Code?

First, many devices with flash program memory allow all or part of this memory to be write protected. The device configuration bits need to be set correctly for this to take place, see Section 5.3.5 “Configuration Bit Access” and your device data sheet. Second, you can prevent third-party code being programmed at unused locations in the program memory by filling these locations with a value rather than leaving them in their default unprogrammed state. You can chose a fill value that corresponds to an instruction or set all the bits so as the values cannot be further modified. (Consider what will happen if you program somehow reaches and starts executing from these filled values. What instruction will be executed?) The compiler’s HEXMATE utility (see Section 8.6 “HEXMATE”) has the capability to fill unused locations and this operation can be requested using a command-line driver option, see Section 4.8.30 “--FILL: Fill Unused Program Memory”. As HEXMATE only works with HEX files, this feature is only available when producing HEX/COF file outputs (as opposed to binary, for example), which is the default operation. And last, if you wish to make your library files or intermediate p-code files available to others but do not want the original source code to be viewable, then you can obfuscate the files using the --SHROUD option, see Section 4.8.54 “--SHROUD: Obfuscate P-code Files”

3.5.7

How Do I Use Printf to Send Text to a Peripheral?

The printf function does two things: it formats text based on the format string and placeholders you specify, and sends (prints) this formatted text to a destination (or stream), see Appendix A. “Library Functions”. The printf function performs all the formatting; then it calls a helper function, called putch, to send each byte of the formatted text. By customizing the putch function you can have printf send data to any peripheral or location, see Section 5.11.1 “The printf Routine”. You may choose the printf output go to an LCD, SPI module or USART, for example.

DS52053B-page 58

 2012 Microchip Technology Inc.

How To’s
A stub for the putch function can be found in the compiler’s sources directory. Copy it into your project then modify it to send the single byte parameter passed to it to the required destination. Before you can use printf, peripherals that you use will need to be initialized in the usual way. Here is an example of putch for a USART on a mid-range device.
void putch(char data) { while( ! TXIF) // check buffer continue; // wait till ready TXREG = data; // send data }

You can get printf to send to one of several destinations by using a global variable to indicate your choice. Have the putch function send the byte to one of several destinations based on the contents of this variable.

3.5.8

How Do I Calibrate the Oscillator on My Device?

Some devices allow for calibration of their internal oscillators, see your device data sheet. The runtime startup code generated by the compiler, see Section 5.10.1 “Runtime Startup Code”, will by default provide code that performs oscillator calibration. This can be disabled, if required, using an option, see Section 4.8.50 “--RUNTIME: Specify Runtime Environment”.

3.5.9

How Do I Place Variables in The PIC18’s External Program Memory?

If all you mean to do is place read-only variables in program memory, qualify them as const, see Section 5.5.3 “Variables in Program Space”. If you intend the variables to be located in the external program memory then use the far qualifier and specify the memory using the --RAM option, see Section 4.8.48 “--RAM: Adjust RAM Ranges”. The compiler will allow far-qualified variables to be modified. Note that the time to access these variables will be longer than for variables in the internal data memory. The access mode to external memory can be specified with an option, see Section 4.8.26 “--EMI: Select External Memory Interface Operating Mode”.

3.5.10

How Can I Implement a Delay in My Code?

If an accurate delay is required, or if there are other tasks that can be performed during the delay, then using a timer to generate an interrupt is the best way to proceed. If these are not issues in your code, then you can use the compiler’s in-built delay pseudo-functions: _delay, __delay_ms or __delay_us, see Appendix A. “Library Functions”. These all expand into in-line assembly instructions or a (nested) loop of instructions which will consume the specified number of cycles or time. The delay argument must be a constant and less than approximately 179,200 for PIC18 devices and approximately 50,659,000 for other devices. Note that these code sequences will only use the NOP instruction and/or instructions which form a loop. The alternate PIC18-only versions of these pseudo-functions, e.g., _delaywdt, may use the CLRWDT instruction as well. See also Appendix A. “Library Functions”.

3.5.11

How Can I Rotate a Variable?

The C language does not have a rotate operator, but rotations can be performed using the shift and bitwise OR operators. Since the PIC devices have a rotate instruction, the compiler will look for code expressions that implement rotates (using shifts and ORs) and use the rotate instruction in the generated output wherever possible, see Section 5.6.2 “Rotation”.

 2012 Microchip Technology Inc.

DS52053B-page 59

MPLAB® XC8 C Compiler User’s Guide
3.6 UNDERSTANDING THE COMPILATION PROCESS
This section tells you how to find out what the compiler did during the build process, how it encoded output code, where it placed objects, etc. It also discusses the features that are supported by the compiler. • • • • • • • • • • • • • • • • • • • • • • • What’s the Difference Between the Free, Standard and PRO Modes? How Can I Make My Code Smaller? How Can I Reduce RAM Usage? How Can I Make My Code Faster? How Does the Compiler Place Everything in Memory? How Can I Make My Interrupt Routine Faster? How Big Can C Variables Be? What Optimizations Will Be Applied to My Code? How Do I Utilize All the RAM Banks on My Device? How Do I Utilize the Linear Memory on Enhanced Mid-range PIC Devices? What Devices are Supported by the Compiler? How Do I Know What Code the Compiler Is Producing? How Do I Find Out What an Warning/error Message Means? How Can I Tell How Big a Function Is? How Do I Know What Resources Are Being Used by Each Function? How Do I Find Out Where Variables and Functions Have Been Positioned? Why are some objects positioned into memory that I reserved? How Do I Know How Much Memory Is Still Available? How Do I Build Libraries? What is Different About an MPLAB IDE Debug Build? How Do I Stop An Unused Function Being Removed? How Do I Use Library Files In My Project? What Optimizations Are Employed By The Compiler?

3.6.1

What’s the Difference Between the Free, Standard and PRO Modes?

These modes (see Section 1.2 “Compiler Description and Documentation”) mainly differ in the optimizations that are performed when compiling. Compilers operating in Free (formerly called Lite) and Standard mode can compile for all the same devices as supported by the Pro mode. The code compiled in Free and Standard mode can use all the available memory for the selected device. What will be different is the size and speed of the generated compiler output. Free mode output will be much less efficient when compared to that produced in Standard mode, which in turn will be less efficient than that produce when in Pro mode. All these modes use the OCG compiler framework, so the entire C program is compiled in one step and the source code does not need many non-standard extensions. There are a small number of command-line options disabled in Free mode, but these do not relate to code features; merely how the compiler can be executed. Most customers never need to use these options. The options are --GETOPTION Section 4.8.32 “--GETOPTION: Get Command-line Options” and --SETOPTION Section 4.8.53 “--SETOPTION: Set the Command-line Options For Application”.

DS52053B-page 60

 2012 Microchip Technology Inc.

How To’s
3.6.2 How Can I Make My Code Smaller?
There are a number of ways that this can be done, but results vary from one project to the next. Use the assembly list file, see Section 6.6 “Assembly List Files”, to observe the assembly code produced by the compiler to verify that the following tips are relevant to your code. Use the smallest data types possible as less code is needed to access these. (This also reduces RAM usage.) Note that a bit type and non-standard 24-bit integer type (short long) exists for this compiler. See Section 5.4 “Supported Data Types and Variables” for all data types and sizes. There are two sizes of floating-point type, as well, and these are discussed in the same section. Avoid floating-point if at all possible. Consider writing fixed-point arithmetic code. Use unsigned types, if possible, instead of signed types; particularly if they are used in expressions with a mix of types and sizes. Try to avoid an operator acting on operands with mixed sizes whenever possible. Whenever you have a loop or condition code, use a "strong" stop condition, i.e., the following:
for(i=0; i!=10; i++)

is preferable to:
for(i=0; i<10; i++)

A check for equality (== or !=) is usually more efficient to implement than the weaker < comparison. In some situations, using a loop counter that decrements to zero is more efficient than one that starts at zero and counts up by the same number of iterations. This is more likely to be the case if the loop index is a byte-wide type. So you might be able to rewrite the above as:
for(i=10; i!=0; i--)

There might be a small advantage in changing the order of function parameters so that the first parameter is byte sized. A register is used if the first parameter is byte-sized. For example consider:
char calc(char mode, int value);

over
char calc(int value, char mode);

Ensure that all optimizations are enabled, see Section 4.8.42 “--OPT: Invoke Compiler Optimizations”. Be aware of what optimizations the compiler performs (see Section 5.13 “Optimizations” and Section 6.5 “Assembly-Level Optimizations”) so you can take advantage of them and don’t waste your time manually performing optimizations in C code that the compiler already handles, e.g., don’t turn a multiply-by-4 operation into a shift-by-2 operation as this sort of optimization is already detected.

 2012 Microchip Technology Inc.

DS52053B-page 61

MPLAB® XC8 C Compiler User’s Guide
3.6.3 How Can I Reduce RAM Usage?
Use the smallest data types possible. (This also reduces code size as less code is needed to access these.) Note that a bit type and non-standard 24-bit integer type (short long) exists for this compiler. See Section 5.4 “Supported Data Types and Variables” for all data types and sizes. There are two sizes of floating-point type, as well, and these are discussed in the same section. Consider using auto variables over global or static variables as there is the potential that these may share memory allocated to other auto variables that are not active at the same time. Memory allocation of auto variables is made on a compiled stack, described in Section 5.5.2.2 “Auto Variable Allocation and access”. Rather than pass large objects to, or from, functions, pass pointers which reference these objects. This is particularly true when larger structures are being passed, but there might be RAM savings to be made even when passing long variables. Objects that do not need to change throughout the program can be located in program memory using the const qualifier, see Section 5.4.7.1 “Const Type Qualifier” and Section 5.5.3 “Variables in Program Space”. This frees up precious RAM, but slows execution. Ensure that all optimizations are enabled, see Section 4.8.42 “--OPT: Invoke Compiler Optimizations”. Be aware of which optimizations the compiler performs (see Section 5.13 “Optimizations”) so that you can take advantage of them and don’t waste your time manually performing optimizations in C code that the compiler already handles.

3.6.4

How Can I Make My Code Faster?

To a large degree, smaller code is faster code, so efforts to reduce code size often decrease execution time, see Section 3.6.2 “How Can I Make My Code Smaller?”. See also, Section 3.6.6 “How Can I Make My Interrupt Routine Faster?”. However, there are ways some sequences can be sped up at the expense of increased code size. One of the compiler optimization settings is for speed (the alternate setting is for space), so ensure this is selected, see Section 4.8.42 “--OPT: Invoke Compiler Optimizations”. This will use alternate output in some instances that is faster, but larger. Generally, the biggest gains to be made in terms of speed of execution come from the algorithm used in a project. Identify which sections of your program need to be fast. Look for loops that might be linearly searching arrays and choose an alternate search method such as a hash table and function. Where results are being recalculated, consider if they can be cached.

3.6.5

How Does the Compiler Place Everything in Memory?

In most situations, assembly instructions and directives associated with both code and data are grouped into sections, called psects, and these are then positioned into containers which represent the device memory. An introductory explanation into this process is given in Section 5.15.1 “Program Sections”. The exception is for absolute variables (see Section 5.5.4 “Absolute Variables”), which are placed at a specific address when they are defined and which are not placed in a psect.

DS52053B-page 62

 2012 Microchip Technology Inc.

How To’s
3.6.6 How Can I Make My Interrupt Routine Faster?
Consider suggestions made in Section 3.6.2 “How Can I Make My Code Smaller?” (code size) for any interrupt code. Smaller code is often faster code. In addition to the code you write in the ISR there is the code the compiler produces to switch context. This is executed immediately after an interrupt occurs and immediately before the interrupt returns, so must be included in the time taken to process an interrupt, see Section 5.9.3 “Context Switching”. This code is optimal in that only registers used in the ISR will be saved by this code. Thus, the less registers used in your ISR will mean potentially less context switch code to be executed. Mid-range devices have only a few registers that are used by the compiler, and there is little context switch code. Even fewer registers are considered for saving when compiling for enhanced mid-range device. PIC18 devices will benefit most from the above suggestion as they use a larger set of registers in generated code, see Section 5.7 “Register Usage”. Generally simpler code will require less resources than more complicated expressions. Use the assembly list file to see which registers are being used by the compiler in the interrupt code, see Section 6.6 “Assembly List Files”. Consider having the ISR simply set a flag and return. The flag can then be checked in main-line code to handle the interrupt. This has the advantage of moving the complicated interrupt-processing code out of the ISR so that it no longer contributes to its register usage. Always use the volatile qualifier (see Section 5.4.7.2 “Volatile Type Qualifier”for variables shared by the interrupt and main-line code, see Section 3.5.5 “How Do I Share Data Between Interrupt and Main-line Code?”.

3.6.7

How Big Can C Variables Be?

This question specifically relates to the size of individual C objects, such as arrays or structures. The total size of all variables is another matter. To answer this question you need to know in which memory space the variable will be located. Objects qualified const will be located in program memory; other objects will be placed in data memory. Program memory object sizes are discussed in Section 5.5.3.1 “Size Limitations of Const Variables”. Objects in data memory are broadly grouped into autos and non-autos and the size limitations of these objects, respectively, are discussed in Section 5.5.2.3 “Size Limits of Auto Variables” and Section 5.5.2.1.2 “Non-Auto Variable Size Limits”.

3.6.8

What Optimizations Will Be Applied to My Code?

The optimizations in OCG compilers can broadly be broadly grouped into C-level and assembly level optimizations. These are described in Section 5.13 “Optimizations” and can be controlled by he option detailed in Section 4.8.42 “--OPT: Invoke Compiler Optimizations”.

3.6.9

How Do I Utilize All the RAM Banks on My Device?

The compiler will automatically use all the available RAM banks on the device you are programming. It is only if you wish to alter the default memory allocation that you need take any action. Special bank qualifiers, see Section “--RAM=default,+20000-2FFFF.”, and an option (see Section 4.8.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”) to indicate how these qualifiers are interpreted are used to manually allocate variables. Note that there is no guarantee that all the memory on a device can be utilized as data and code is packed in sections, or psects.

 2012 Microchip Technology Inc.

DS52053B-page 63

MPLAB® XC8 C Compiler User’s Guide
3.6.10 How Do I Utilize the Linear Memory on Enhanced Mid-range PIC Devices?

The linear addressing mode is a means of accessing the banked data memory as one contiguous and linear block, see Section 5.5.1 “Address Spaces”. Use of the linear memory is fully automatic. Objects that are larger than a data bank can be defined in the usual way and will be accessed using the linear addressing mode, see Section 5.5.2.3 “Size Limits of Auto Variables” and Section 5.5.2.1.2 “Non-Auto Variable Size Limits”. If you define absolute objects at a particular location in memory, you can use a linear address, if you prefer, or the regular banked address, see Section 5.5.4.1 “Absolute Variables in Data Memory”.

3.6.11

What Devices are Supported by the Compiler?

Support for new devices usually takes place with each compiler release. To find whether a device is supported by your compiler, you can do several things, see also Section 5.3.1 “Device Support”. • HTML listings are provided in the compiler’s docs directory. Open these in your favorite web browser. They are called pic_chipinfo.html and pic18_chipinfo.html. • Run the compiler driver on the command line (see Section 4.2 “Invoking the Compiler”) with the --CHIPINFO option, see Section 4.8.21 “--CHIPINFO: Display List of Supported Devices”. A full list of all devices is printed to the screen.

3.6.12

How Do I Know What Code the Compiler Is Producing?

The assembly list file (see Section 6.6 “Assembly List Files”) shows the assembly output for almost the entire program, including library routines linked in to your program, as well a large amount of the runtime startup code, see Section 5.10.1 “Runtime Startup Code”. The list file is produced by default if you are using MPLAB IDE. If you are using the command-line, the option --ASMLIST will produce this file for you, see Section 4.8.17 “--ASMLIST: Generate Assembler List Files”. The assembly list file will have a .lst extension. The list file shows assembly instructions, some assembly directives and information about the program, such as the call graph, see Section 6.6.6 “Call Graph”, pointer reference graph, see Section 6.6.5 “Pointer Reference Graph” and information for every function. Not all assembly directives are shown in the list file if the assembly optimizers are enabled (they are produced in the intermediate assembly file). Temporarily disable the assembly optimizers (Section 4.8.42 “--OPT: Invoke Compiler Optimizations”) if you wish to see all the assembly directives produced by the compiler.

3.6.13

How Can I Tell How Big a Function Is?

This size of a function (the amount of assembly code generated for that function) can be determined from the assembly list file, see Section 6.6 “Assembly List Files”, or a ’funclist’ file generated by the compiler. Recent compilers define a symbol whose assigned value is equal to the size of the function. The symbol has the form __size_of_func, where func is the name of the function. The units of this symbol will be the same as the addressability of the program memory for the particular device: words for PIC10/12/16 and bytes for PIC18. You can also search for the labels that mark the beginning and end of the function. The function starts at the label _func:, where func is the name of the function, and ends just prior to the label __end_of_func. For example, the function main may have associated symbols __size_of_main, _main and __end_of_main. These will be found in the symbol table at the end of the assembly list file.

DS52053B-page 64

 2012 Microchip Technology Inc.

that are linked anywhere inside these class ranges and so are affected by these reservation options.2. see Section 6. memory location and size is available in a file called funclist.3. This information indicates what registers the function used.22 “--CODEOFFSET: Offset Program Code to Address”. and how many bytes of data memory it requires.. parameter and temporary variables used by a function may overlap with those from other functions as these are placed in a compiled stack by the compiler.3. Psects that hold code associated with Reset and interrupts can be shifted using the --CODEOFFSET option.6. DS52053B-page 65 . See also. An introduction to psects is given in Section 5.3.6 “Assembly List Files”.15. see Section 5. Note that auto.. Some psects are explicitly placed at an address rather than being linked anywhere in an address range.”). e.2.  2012 Microchip Technology Inc.16 Why are some objects positioned into memory that I reserved? The memory reservation options.4 “How Do I Stop the Compiler Using Certain Memory Locations?” will adjust the range of addresses associated with classes used by the linker. Most variables and function are placed into psects. 3.15 How Do I Find Out Where Variables and Functions Have Been Positioned? You can determine where variables and functions have been positioned from either the assembly list file. see Section 5.5.1 “Program Sections”.8.How To’s The list of functions. 2012 0 30 This indicates that generated assembly code associated with the function. what functions it calls (this is also found in the call graph. see Section 6. see Section 5. see Section 6.4 “Map Files”.2.19 “-Pspec”) and -A (Section 7. to see if psects have been linked explicitly or if they are linked anywhere in a class. which are the symbols shown in both of these files. Such a psect will not be affected by the --ROM option. The symbol associated with a variable is assigned the address of the lowest byte of the variable. see Section 3. for functions it is the address of the first instruction generated for that function.13 “Space”).15.1 “-Aclass =low-high.3 “Class”). the psect that holds the code to be executed at Reset is always linked to address 0 because that is where the Reset location is defined to be for 8-bit devices. Check the assembly list file.g. even if you use it to reserve memory address 0.6 “Call Graph”).4.4 “Map Files”. 3.4. the linker options -p (Section 7.1 “Equivalent Assembly Symbols”. see Section 6..6 “Assembly List Files”.1 “Program Sections”.12.3.6 “Assembly List Files”.4. or the map file. _main: CODE. see Section 4.9.2. 3.6.9.) There is a mapping between C identifiers and the symbols used in assembly code. was located at address 2012 (decimal) in address space number 0 (see Section 6. all symbols (including locals) are listed in the assembly list file. see Section 7.6.1 “Compiled Stack Operation”. and was 30 (again decimal) words/bytes long. was placed in the CODE linker class (see Section 6. main.6. but only for the code represented by that list file. Check the linker options in the map file. to determine the names of psects that hold objects and code. (Each assembly module has its own list file. see Section 7. including library functions.14 How Do I Know What Resources Are Being Used by Each Function? In the assembly list file there is information printed for every C function. Only global symbols are shown in the map file.. Each function will have a line similar to the following.

23 “--DEBUGGER: Select Debugger Type”).6 “How Do I Fix a "Can’t find space.6 “How Do I Build Libraries?” for information on how you build your own library files.45 “--PASS1: Compile to P-code”). To use one or more library files that were built by yourself or a colleague. i.8. The IDE will ensure that they are passed to the compiler at the appropriate point in the build sequence. See Section 3.2.6." Error?”) The "UNUSED ADDRESS RANGES" section.5 “Unused Address Ranges” in the map file indicates exactly what memory is still available in each linker class. For example: xc8 --chip=16f1937 main.3 “What Do I Need to Do When Compiling to Use a Debugger?” DS52053B-page 66  2012 Microchip Technology Inc.18 How Do I Use Library Files In My Project? See Section 3. such as the REAL ICE or ICD3. or the IDE equivalent..c int.6.e.5 “Assembly-Level Optimizations”. in the order in which they should be searched. the memory required for debugging is removed from that available to your project. When you select a debugger using the compiler’s --DEBUGGER option (Section 4. . Small blocks of free memory cannot be used for larger objects and so out-of-memory errors may be produced even though the total amount of memory free is apparently sufficient for the objects to be positioned.. they will be searched in the order specified in the command line.4..6.8. respectively. The LPP libraries do not need to be specified if you are compiling to an intermediate file. (See Section 3. using the --PASS1 option (see Section 4. neither of these features indicate whether this memory is one contiguous block or broken into many small chunks.6. so you never need to control these files.8.8.5.42 “--OPT: Invoke Compiler Optimizations”. include them in the list of files being compiled on the command line. It also indicated the largest contiguous block in that class if there are memory bank or page divisions. but if there is more than one library file.3.17 How Do I Know How Much Memory Is Still Available? Although the memory summary printed by the compiler after compilation (see Section 4. The options that control optimization are described in Section 4. The library files can be specified in any position in the file list relative to the source files.19 What Optimizations Are Employed By The Compiler? Optimizations are employed at both the C and assembly level of compilation.20 Why Do I Get Out-of-memory Errors When I Select a Debugger? If you use a hardware tool debugger.c lcd.7. The compiler will automatically include any applicable standard library into the build process when you compile. add the library file(s) to the Libraries folder that will shown in your project.13 “Optimizations” and Section 6. see Section 7.lpp If you are using MPLAB X IDE to build a project. 3.56 “--SUMMARY: Select Memory Summary Output Type” options) or the memory gauge available in MPLAB IDE both indicate the amount of memory used and the amount still available.MPLAB® XC8 C Compiler User’s Guide 3. 3. This is described in Section 5. these require memory for the on-board debug executive. 3.

6. In some instances. see Section 4. This number also allows you to control message behavior using options and pragmas.." Error? • How Do I Fix a "Can’t generate code. “Error and Warning Messages”." Error? • How Do I Fix a Fixup Overflow Error? • Invoking the Compiler • Invoking the Compiler • What Can Cause Corrupted Variables and Code Failure When Using Interrupts? • Why are some objects positioned into memory that I reserved? 3. // oops .  2012 Microchip Technology Inc. or which build but do not work as expected. then you can double-click the message and have the editor take you to the offending line. the error is reported on the line of code following the line that needs attention.7.5 “Changing Message Behavior”. • How Do I Find Out What an Warning/error Message Means? • How Do I Find the Code that Caused Compiler Errors Or Warnings in My Program? • How Can I Stop Spurious Warnings from Being Produced? • Why Can’t I Even Blink an LED? • How Do I Know If the Stack Has Overflowed? • How Do I Fix a "Can’t find space..7. The compiler prints with each message a unique ID number in brackets..6 “Compiler Messages”. listed in the messages chapter. where the error is a syntax error relating to the source code. It is possible that the compiler may not be able to determine that there is an error until it has started to scan to statement following. and possibly sample code that might trigger such an error. the error might come from the assembler.2 How Do I Find the Code that Caused Compiler Errors Or Warnings in My Program? In most instances. not the code generator. 3..forgot the semicolon The missing semicolon on the assignment statement will be flagged on the following line that contains the if() statement. If the source being compiled is an assembly module. see Section 4. In either case. Use this number to look up the message in the manual.1 How Do I Find Out What an Warning/error Message Means? Each warning or error message has a description. This is because a C statement is allowed to extend over multiple lines of the source file. If you are compiling in MPLAB IDE. the message produced by the compiler indicates the offending line of code.7 FIXING CODE THAT DOES NOT WORK This section examines issues relating to projects that do not build due to compiler errors. see Appendix B.. remember that the information in the error relates to some problem is the assembly code. the error directly indicates the line of assembly that triggered the error. In other cases.How To’s 3. So in the following code input = PORTB if(input>6) // . But identifying the offending code is not always so easy. not the C code. If the assembly code was derived from a C source file then the compiler will try to indicate the line in the C source file that corresponds to the assembly that is at fault.. DS52053B-page 67 .

1 “Messaging Overview”. Turn off any other features that may cause device Reset until your test program is working. If the device is resetting.4 Why Can’t I Even Blink an LED? Even if you have set up the TRIS register and written a value to the port.3 “The Compilation Sequence”.5 “Configuration Bit Access”. .3. it may never reach the lines of code in your program that blink the LED. If you need to see the assembly code generated by the compiler. • The device pins used by the port bits are often multiplexed with other peripherals.7. To determine the application that generated the error or warning. “Error and Warning Messages”. the device clock may not even be running. • If the internal oscillator is being used.7. “Library Functions”) so that the device does not reset. • Make sure that the device’s configuration registers are set up correctly. see Section 6.3 How Can I Stop Spurious Warnings from Being Produced? Warnings indicate situations that could possibly lead to code failure. see the map file discussed in Section 7.6. The port function tables shown in your device data sheets will show other uses for each pin that will help you identify peripherals to investigate. then your LED will never operate as expected. 3. Knowing the application that produced the error makes it easier to track down the problem.6 “Assembly List Files”. see Section 5. DS52053B-page 68  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide Finally. Always check your code to confirm that it is not a possible source of error and in cases where this is so. see Section 5. see Section 4.5. 3. is the name of the application that produced this message. A pin might be connected to a bit in a port. for example. there are errors that do not relate to any particular line of code at all.6. If the pin connected to your LED is not internally connected to the port you are using.4 “Map Files”. If the configuration bits that specify the oscillator source are wrong. look in the assembly list file. for example.3.14. An error in a compiler option or a linker error are examples of these. there are several ways that warnings can be hidden. take a note of its unique number printed in the message. In many situations the code is valid and the warning is superfluous. All the configuration features are described in your device data sheet. on the right in brackets. there is no one particular line of code that is at fault. see Section 4. If the program defines too many variables. At the top of each message description.4. the program as a whole uses too much data. • The warning level threshold can be adjusted so that only warnings of a certain importance are printed. Make sure that you explicitly specify every bit in these registers and don’t just leave them in their default state. • Either turn off the watch dog timer in the configuration bits or clear the watch dog timer in your code (see Section Appendix A.6 “Using SFRs From C Code” and your device data sheet. or it might the output of a comparator. a pragma can be used to inhibit a warning with a specified ID for certain lines of source code. Note that the name and line number of the last processed file and source may be printed in some situations even though that code is not the direct source of the error. or it might be an analog input. The compiler application names are indicated in 4. in addition to configuration bits there may be SFRs you need to initialize to set the oscillator frequency and modes. see Appendix B. For information on where the linker attempted to position objects. see Section 5.11 “The #pragma warning Directive”. and check the message section of the manual. there are several things that can prevent such a seemingly simple program from working.1 “Disabling Messages” • All warnings with a specified ID can be inhibited • In some situations.

this message can be issued when seemingly there is enough memory remaining. Check the device literature for more detailed information. usually allows the compilation to continue. If the nesting of function calls and interrupts is too deep.5 How Do I Know If the Stack Has Overflowed? The 8-bit PIC devices have a limited hardware stack that is only used for function (and interrupt function) return addresses. Due to memory paging. Rather than read and write the port directly. when required. 3. the stack will overflow (wraps around and overwrites previous entries).How To’s • Make sure you do not have a "read-modify-write" problem.7. “Error and Warning Messages” for more information on your particular error number.. However. or splitting a statement into several smaller statements. Code will then fail at a later point — sometimes much later in the call sequence — when it accesses the corrupted return address." Error? This is a catch-all message which is generated if the compiler has exhausted all possible means of compiling a C expression. it can only assume the worst case and may report that overflow is possible even though it is not. Since the runtime behavior of the program cannot be determined by the compiler. After modifications are complete.3. such as an LED. You may see that setting one bit turns off another or other unusual events.50 “--RUNTIME: Specify Runtime Environment” and the stackcall suboption. They all relate to there being no free space large enough to place a block of data or instructions. or an expression that requires more registers or resources than are available at that point in the code. no overflow should go undetected if the program is written entirely in C. Create your own latch by using a temporary variable. particularly if the port outputs are driving large loads. In any case. copy the latch as a whole to the port. swap to a method of calling that does not need the hardware stack (PIC10/12/16 devices only). A call graph shows the call hierarchy and depth that the compiler has determined.. see Section 6.. banking or other fragmentation.6.. see Appendix B. The inability to compile the code may be a deficiency in the compiler. make modifications to the latch variable. To understand the information in this graph.6 How Do I Fix a "Can’t find space.8. see Section 5.6 “Call Graph”. see Section 4. This means you are never reading the port to modify it. but all essentially imply a similar situation. This graph is shown in the assembly list file. 3. simplifying the offending expression.7. If the device you are using does not have a separate "latch" register (as is the case with mid-range PIC devices) this problem can occur. See Appendix B.4 “Stack”.  2012 Microchip Technology Inc. 3.7 How Do I Fix a "Can’t generate code.7. Assembly code that uses the stack is not considered by the compiler and this must be taken into account. You may need to use another variable to hold the intermediate results of complicated expressions. This is more likely to occur on baseline devices. You have some degree of control over what happens when the stack depth has apparently overflowed. The compiler attempts to track stack depth and." Error? There are a number of different variants of this message. “Error and Warning Messages”. DS52053B-page 69 . It does not usually indicate a fault in your code.

4. When writing assembly. See Section 3. For example. DS52053B-page 70  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide 3.7. then corruption can occur. In most cases.7. it is the programmer’s responsibility to add instructions to select the destination bank and then mask the address being used in the instruction. the linker will be unable to encode the large address value into the instruction and this error will be generated. a mid-range device instruction only allows for file addresses in the range of 0 to 0x7F. is specified with one of these instructions. if such a device has 4 data banks of RAM. It is important to remember that this is an issue with an assembly instruction and you need to find the instruction at fault before you can proceed. when the symbol is replaced with its final value. “Error and Warning Messages” for specific details as to how to track down the offending instruction. See the relevant error number in Appendix B.8 How Do I Fix a Fixup Overflow Error? Fixup — the process of replacing a symbolic reference with an actual address — can overflow if the address assigned to the symbol is too large to fit in the address field of the assembly instruction. However.7. If the compiler optimizes access to a variable or access is interrupted by an interrupt routine.5 “How Do I Share Data Between Interrupt and Main-line Code?” for more information. If the symbol of a variable that will be located at address 1D0. these errors are caused by hand-written assembly code.5 “What Things Must I Manage When Writing Assembly Code?”. for example. If a full unmasked address is specified with these instructions. the address of variables can range from 0 to 0x1FF. Most 8-bit PIC assembly instructions specify a file address that is an offset into the currently selected memory bank. .9 What Can Cause Corrupted Variables and Code Failure When Using Interrupts? This is usually caused by having variables used by both interrupt and main-line code. this value will not fit in the address field of the instruction.5. see Section 3. 3.

and link steps. Although the internal compiler applications can be called explicitly from the command line. the IDE will ultimately call xc8. the files that the driver can accept and produce.1 INTRODUCTION The name of the command-line driver is xc8. XC8 Command-line Driver 4. XC8 can be invoked to perform all aspects of compilation.MPLAB® XC8 C COMPILER USER’S GUIDE Chapter 4. DS52053B-page 71 . The following topics are examined in this chapter of the MPLAB XC8 C Compiler User’s Guide: • • • • • • • • Invoking the Compiler The Compilation Sequence Runtime Files Compiler Output Compiler Messages XC8 Driver Options MPLAB IDE V8 Universal Toolsuite Equivalents MPLAB X Universal Toolsuite Equivalents  2012 Microchip Technology Inc. including C code generation. This chapter describes the steps the driver takes during compilation. The relationship between these command-line options and the controls in the MPLAB IDE Build Options dialog is also described. Even if an IDE is used to assist with compilation. as well as the command-line options that control the compiler’s operation. assembly. the xc8 driver is the recommended way to use the compiler as it hides the complexity of all the internal applications used and provides a consistent interface for all compilation steps.

Object files are seldom used with the MPLAB XC8 C Compiler. However. It is customary to declare options (identified by a leading dash “-” or double dash “–”) before the files’ names. it may affect the order in which code or data appears in memory. unless assembly source modules are in the project.c isr.2.c After it is saved.. in addition to the standard C libraries.2.e. --chip=16F877A -m \ --opt=all -g \ main. this is not mandatory.7 “XC8 Driver Options”. While the order in which the files are listed is not important. along with corresponding descriptions of the options. It is customary to insert the Libraries list after the list of source file names. However. 4. 4. In the following example. . as well as the files that it can read.3 “Multi-Step Compilation” is recommended.1.2 INVOKING THE COMPILER This section explain how to invoke xc8 on the command line. which should be immediately followed (i. familiarity with the unique intermediate p-code file format as described in Section 4. If you are building code using a make system. which are simply skipped by the driver. no intermediate space character) by the name of the file containing the command-line arguments that are intended for the driver.MPLAB® XC8 C Compiler User’s Guide 4. The file may contain blank lines. The use of a command file means that compiler options and source code filenames can be permanently stored for future reference without the complexity of creating a make utility.1 Driver Command-line Format xc8 has the following basic command format.1 LONG COMMAND LINES The xc8 driver is capable of processing command lines exceeding any operating system limitation if the driver is passed options via a command file. this is not mandatory. the compiler may be invoked with the following command: xc8 @xyz. The files may be an assortment of C and assembler source files.p1) files.obj) files or p-code (. The compiler’s location can be added to the search path when installing the compiler by selecting the Add to environment checkbox at the appropriate time during the installation. The order of these files will determine the order in which they are searched. it is assumed that the compiler applications are in the console’s search path or that the full path is specified when executing an application. and may affect the name of some of the output files. a command file xyz. xc8 [options] files [libraries] Throughout this manual. The formats of the options are supplied in Section 4.3. Each command-line argument must be separated by one or more spaces and may extended to several lines by using a space and backslash character to separate lines. Libraries is a list of user-defined object code or p-code library files that will be searched by the code generator (in the case of p-code libraries) or the linker (for object code libraries).cmd DS52053B-page 72  2012 Microchip Technology Inc. such as relocatable object (. The command file is specified by the @ symbol. and precompiled intermediate files.cmd was constructed in a text editor and contains both the options and file names that are required to compile a project.

etc. The compiler looks for the XML with a name . along with other configuration settings. DS52053B-page 73 . This allows you to run the compiler driver without specifying the full compiler path with the driver name.as or .asm . Alphabetic case of the extension is not important from the compiler’s point of view. the compiler tries to open the file /etc/xc.2 Environment Variables When hosted on a Windows environment. 3.obj . TABLE 4-1: . 4. 2. If none of these methods finds the XML file. If the HOME environment variable is not defined. 4. The MPLAB IDE allows the compiler to be selected via a dialog and execution of the compiler does not depend on the PATH variable. When running the compiler on the command line.asm extensions.c . Under Linux and Apple OS X environments. If this variable is not defined. the compiler then searches for an environment variable called HOME. this variable should contain the full path to the XML file (including the file’s name).as or . the compiler searches for the XML file in the following ways: 1. On non-Windows hosts. The directories specified in the PATH variable do not override the information contained in the registry or XML file. the compiler uses the registry to store information relating to the compiler installation directory and activation details. intermediate files and library files solely by the file type. Assembler files can use either .xml.2.XC8 Command-line Driver 4. you may wish to set the PATH environment variable. an error is generated. assembler and linker.xc.hex XC8 INPUT FILE TYPES File Type C source file p-code file p-code library file Assembler source file Relocatable object code file Relocatable object library file Intel HEX file Meaning This means.xml in the directory indicated by the HOME variable.lpp . described above. This variable typically contains the path to the user’s home directory. but most operating system shells are case sensitive.  2012 Microchip Technology Inc. to locate the internal compiler applications. such as the parser. or extension.3 Input File Types xc8 distinguishes source files. for example. That information is required whether the compiler is run on the command line or from within an IDE. it uses the registry or XML file.lib . Once the driver is running.c extension. The compiler looks for the presence of an environment variable called XC_XML. the registry is replaced by an XML file which stores the same information. If present.2. Recognized file types are listed in Table 4-1. that a C source file must have a .p1 . Note that the directories specified by the PATH variable are only used to locate the compiler driver.

. They may contain C code. but be aware of case. avoid assembly source files whose basename is the same as the basename of any project in which the file is used.MPLAB® XC8 C Compiler User’s Guide There are no compiler restrictions imposed on the names of source files. Source files are initially passed to the preprocessor by the driver. Thus. All preprocessor directives and commands (with the exception of some commands for debugging) have been removed from these files. The terms “source file” and “module” are often used when talking about computer programs. but they refer to the source code at different points in the compilation sequence. as they can include other header and source files. name-length and other restrictions imposed by your operating system. for a given source file. This may result in the source file being overwritten by a temporary file during the build process. DS52053B-page 74  2012 Microchip Technology Inc. A module is also often referred to as a translation unit. a module may be the amalgamation of several source and header files. If you are using an IDE. A source file is a file that contains all or part of a program. after inclusion of any header files (or other source files) which are specified by #include preprocessor directives. A module is the output of the preprocessor. These terms can also be applied to assembly files. They are often used interchangeably. as well as preprocessor directives and commands. These modules are then passed to the remainder of the compiler applications.

lpp . some of the internal applications come in a PIC18 and PIC10/12/16 variant. FIGURE 4-1: COMPILER APPLICATIONS AND FILES p-code libraries . This operation is transparent and xc8 may be considered as “the driver” which does all the work.as assembly source files relocatable object file .1 The Compiler Applications The main internal compiler applications and files are illustrated in Figure 4-1.as parser code generator assembler debug file cromwell linker objtohex hexmate . This section looks at when these internal applications are executed and how this relates to the build process of multiple source files.obj p-code files .p1 Command-line driver processed files (module) C source files . DS52053B-page 75 . You may be satisfied just knowing that C source files (shown on the far left) are passed to the compiler and the resulting output files (shown here as a HEX and COFF debug file on the far right) are produced.c .c preprocessor p or . there are many internal applications that are called to do the work. You can consider the large underlying box to represent the whole compiler. This section should be of particular interest if you are using a make system to build projects.3 THE COMPILATION SEQUENCE When you compile a project.cof . which is controlled by the command line driver.pre p-code files .3. The temporary file produced by each application can also be seen in this diagram. An understanding of the internal operation of the compiler. The driver will call the required compiler applications. xc8. internally there are many applications and temporary files being produced. 4.obj . The appropriate application is executed based on the target device.hex hex file object libraries hex . These applications are shown as the smaller boxed inside the large driver box.obj absolute object file relocatable object files . In fact. To simplify the compiler design. does assist with using the tool. however. the xc8 driver delegates the build commands to one of two command-line drivers: PICC or PICC18.XC8 Command-line Driver 4.hex files  2012 Microchip Technology Inc.lib .p1 assembly file .h hex hex file . while not necessary.

DS52053B-page 76  2012 Microchip Technology Inc. both of which are passed initially to the linker. The names shown are the names of the executables. P1. assembly source files are passed straight to the assembler application1 and are not processed at all by the code generator. You can see that any p-code files (. The compiler can accept more than just C source files. . which is run right at the end of the compilation sequence.c files) are first passed to the C preprocessor. Assembly file will be preprocessed before being passed to the assembler if the -P option is selected. The output of this application are . on the top and bottom. They are processed by these applications and then the application output joins the normal flow indicated in the diagram.lib extension). The applications are executed in the order specified and temporary files are used to pass the output of one application to the next. C source files (.hex extension). Some of the temporary files shown in this diagram are actually preserved and can be inspected after compilation has concluded. These files are then passed to the parser application.obj extension) and object libraries (.obj extension) is passed to the linker in the usual way. being passed to different compilation applications.pre files. There are also driver options to request that the compilation sequence stop after a particular application and the output of that application becomes the final output. which produces a p-code file output with extension . called HEXMATE.p1 extension) or p-code libraries (. For example. The output of the assembler (an object file with . and these files can be seen in this diagram.lpp extension) that are supplied on the command line are initially passed to the code generator.MPLAB® XC8 C Compiler User’s Guide Table 4-2 lists the compiler applications.p1. 1. which are passed to one of the utility applications. the interface to the compiler HEXMATE LIBR DUMP CREF For example. and even HEX files (. Other examples of input files include object files (. Table 4-1 lists all the possible input file types. which can be found in the bin directory under the compiler’s installation directory. TABLE 4-2: COMPILER APPLICATION NAMES Description Text file formatter The C preprocessor C code parser Code generator (based on the target device) Assembler (based on the target device) Linker Conversion utility to create HEX files Debug file converter HEX file utility Librarian Object file viewer Cross reference utility Name CLIST CPP P1 CGPIC or CGPIC18 ASPIC or ASPIC18 HLINK OBJTOHEX CROMWELL xc8 (calls PICC or PICC18) Command line driver. CPP.

The first stage involves processing of each source file separately. but internally we can consider this compilation as consisting of two stages.2 Single-Step Compilation Figure 4-1 showed us the files that are generated by each application and the order in which these applications are executed.p1 extension) file output by the parser. sees the entire project source code via the intermediate files. This method of compilation is shown in Figure 4-3 and shows that the code generator is executed once for each source file. (For clarity the CPP and P1 applications have been represented by the same block in the diagram. Always use p-code files as the intermediate file format if you are using a make system to build projects. these could be compiled with a single command. The MPLAB XC16 and XC32 compilers work in this fashion.XC8 Command-line Driver FIGURE 4-2: MULTI-FILE COMPILATION Intermediate files C file preprocess & parse pcode C file preprocess & parse pcode code generation assemble link library files First stage of compilation Second stage of compilation 4.  2012 Microchip Technology Inc. The second stage involves combining all these intermediate files and further processing to form the final output. The intermediate file used by xc8 is the p-code (. which is then passed to the subsequent applications that produce the final output. The desirable attribute of this method of compilation is that the code generator. If these files are called main. Traditional compilers have always used intermediate files that are object files output by the assembler. such as: xc8 --chip=16F877A main. As indicated in the diagram. DS52053B-page 77 . CPP and then P1 are executed to form this intermediate file. These intermediate object files are then combined by the linker and further processed to form the final output. and generating some sort of intermediate file for each source file.c io.c and io. Using object files as the intermediate file format with MPLAB XC8 C Compiler will defeat many features the compiler uses to optimize code. so there will be one p-code file produced for each C source file. Thus the code generator can only analyze that part of the project that is contained in the source file currently being compiled. which is the main application that transforms from the C to the assembly domain.c.) In the second stage. the code generator reads in all the intermediate p-code files and produces a single assembly file output.3. as is the case shown in Figure 4-2. Consider the case when there are two C source files that form a complete project and that are to be compiled.c This command will compile the two source files all the way to the final output. An intermediate file is a particular temporary file that is produced and marks the mid point between the first and second stage of compilation. However this does not indicate how these applications are executed when there is more than one source file being compiled.

as c_sb. unless you use the --NODEL option (see Section 4. To perform this in a single step. Note that some generated files may be in a different directory to your project source files. The output of the code generator.c. As discussed in Section 4. as well as the assembly source file (mdef.lpp) will be passed to the code generator.as).lpp are to be compiled. a HEX file and Microchip COFF file are produced as the final output. For example.c io.43 “--OUTDIR: Specify a Directory For Output Files” and Section 4. along with the p-code library file (c_sb. this can still be achieved with just one invocation of the compiler driver.40 “--NODEL: Do Not Remove Temporary Files”) which preserves all generated files except the run-time start-up file. IDEs (such as MPLAB® IDE) and make utilities must be employed to achieve incremental builds.lpp As shown in Figure 4-1 and Figure 4-2.3.as and c_sb.c and io.8.MPLAB® XC8 C Compiler User’s Guide FIGURE 4-3: THE TRADITIONAL COMPILATION SEQUENCE Intermediate files C file preprocess & parse code generation assemble . but most other temporary files are deleted. the following command line could be used.c. The driver will recompile all source files.8. Unless otherwise specified. main.obj files C file preprocess & parse code generation assemble .3 “The Compilation Sequence”. the driver will pass each input file to the appropriate compiler application. DS52053B-page 78  2012 Microchip Technology Inc. will be passed to the assembler. mdef. io.obj files link First stage of compilation library files Second stage of compilation When compiling files of mixed types. regardless of whether they have changed since the last build.c) will be compiled to intermediate p-code files. the files.41 “--OBJDIR: Specify a Directory For Intermediate Files” which can both control the destination for some output files. See also Section 4. these.3 “Multi-Step Compilation”. xc8 --chip=16F877A main. the two C files (main.8. See Section 4. All intermediate files remain after compilation has completed. .c mdef.

When building a project. The command lines that the make utility should use to compile these files might be something like: xc8 --chip=16F877A --pass1 main. Always use p-code files as the intermediate file format if you are using a make system to build projects.c are to be compiled using a make utility. and once to perform the second stage compilation. so this is typically not necessary.XC8 Command-line Driver 4.44 “--OUTPUT= type: Specify Output File Type” for more information on library creation. xc8 is capable of constructing libraries in a single step.3. the make file will need to be configured to recognized the different intermediate file format and the options used to generate the intermediate files.p1 io. the intermediate file corresponding to the unchanged source file need not be regenerated. The option --PASS1 (Section 4.c xc8 --chip=16F877A main.c xc8 --chip=16F877A --pass1 io. if compiling two source files. For example. allow for an incremental build of projects that contain multiple source files.8. or fully rebuild a project (Clean and Build Project icon). MPLAB IDE is aware of the different compilation sequence employed by xc8 and takes care of this for you. but only one has changed since the last build.  2012 Microchip Technology Inc. DS52053B-page 79 . Make utilities typically call the compiler multiple times: once for each source file to generate an intermediate file. so the above command lines do not violate this requirement. When using the --PASS1 option the code generator is not being invoked. the files main. such as MPLAB IDE. For example. Using object files as the intermediate file format with MPLAB XC8 C Compiler will defeat many features the compiler uses to optimize code.c and io. See Section 4. they take note of which source files have changed since the last build and use this information to speed up compilation.p1 If is important to note that the code generator needs to compile all p-code or p-code library files associated with the project in the one step. From MPLAB IDE you can select an incremental build (Build Project icon). This will leave the p-code intermediate file behind on successful completion.45 “--PASS1: Compile to P-code”) is used to tell the compiler that compilation should stop after the parser has executed. You may also wish to generate intermediate files to construct your own library files. If the compiler is being invoked using a make utility.3 Multi-Step Compilation Make utilities and IDEs. However.8.

see Section 4. This pass is part of the process by which the printf library function is customized. . along with any other objects files that are part of the project. The -C option (see Section 4.1 “-C: Compile to Object File”) is used to generate object files and halt compilation after the assembly step.3. 4.3 “Interaction Between Assembly and C Code”. as has been described earlier. Assembly files are traditionally processed after C code. see Section 5. i.e.3. These files. DS52053B-page 80  2012 Microchip Technology Inc.1 INTERMEDIATE FILES AND ASSEMBLY SOURCE The intermediate file format associated with assembly source files is the same as that used in traditional compilers. 4. This pass is only associated with scanning the C source code for printf placeholder usage and you will see the code generator being executed if you select the verbose option when you build.1 “The printf Routine” for more details.4 Compilation of Assembly Source Since the code generator performs many tasks that were traditionally performed by the linker.3.8.11. the order of compilation is as shown in Figure 4-4.5 Printf Check An extra execution of the code generator is performed prior to the actual code generation phase. an object file (. are then scanned by the command-line driver and information is then passed to the code generator when it subsequently builds the C files.MPLAB® XC8 C Compiler User’s Guide 4. FIGURE 4-4: C file COMPILATION SEQUENCE WITH ASSEMBLY FILES preprocess & parse preprocess & parse pcode C file pcode library files ASM file code generation assemble link assemble driver OBJ file Any assembly source files are first assembled to form object files. When assembly source is present.15 “-V: Verbose Compile”. but it is necessary to have this performed first so that specific information contained in the assembly code can be conveyed to the code generator.12. Assembly files are never passed to the code generator and so the code generator technology does not alter the way these files are compiled. The specific information passed to the code generator is discussed in more detail in Section 5.8.4.. there could be complications when assembly source is present in a project.obj extension).

The libraries also contain C routines that are implicitly called by the output code of the code generator. it is discussed with the other runtime files in the following sections.lpp. however as it is very closely associated with the runtime startup module. and other driver options.1 Library Files The names of the C standard library files appropriate for the selected target device. math and input/output routines. and object code libraries (.1 STANDARD LIBRARIES The C standard libraries contain a standardized collection of functions. etc. All the libraries are present in the lib directory of the compiler installation. and that may not directly correspond to a C function call in the source code.1.4 RUNTIME FILES In addition to the C and assembly source files specified on the command line. there are also compiler-generated source files and pre-compiled library files which might be compiled into the project by the driver. nor a library routine.1 “The printf Routine” for information on how the printf function is customized when you build a project.. Although it is considered a library function.11. It is fully defined by the user. such as string. • options indicate hyphen-separated names to indicate variants of the library to accommodate different compiler options or modes. “Library Functions”.4. Strictly speaking. htc for HI-TECH C compatibility. the printf function’s code is not found in these library files.lib files) are used by the linker. For example. 4. • family can either be pic18 for PIC18 devices. the power-up routine is neither a compiler-generated source. d32 for 32-bit doubles. 4.  2012 Microchip Technology Inc. By default. integer division and type conversions. e. etc. The range of these functions are described in Appendix A. or pic for all other 8-bit PIC devices • type indicates the sort of library functionality provided and may be stdlib for the standard library functions. are determined by the driver and passed to the code generator and linker. These files contain: • • • • • • C Standard library routines Implicitly called arithmetic routines User-defined library routines The runtime startup code The powerup routine The printf routine.lpp libraries) are used by the code generator. P-code libraries (. Search this directory for the full list of all libraries supplied. You do not need to manually include library files into your project.g. These are routines that perform tasks such as floating-point operations. where the following apply. DS52053B-page 81 . xc8 will search the lib directory under the compiler installation directory for library files that are required during compilation. or trace. C source code for this function is generated from a special C template file that is customized after analysis of the user’s C code. See Section “PRINTF.XC8 Command-line Driver 4.lpp. VPRINTF” for more information on using the printf library function and Section 5. Most library routines are derived from p-code libraries. the standard library for baseline and midrange devices using 24-bit double types is pic-stdlib-d24.4. The library name format is family-type-options.

1.2 “Librarian” for more information on the librarian and creating library files using this application. any functions contained in user-defined libraries should have a declaration added to a header file. see. It is common practice to create one or more header files that are packaged with the library file. See Section 8. it will be called startup. precompiled routine.MPLAB® XC8 C Compiler User’s Guide 4.10.44 “--OUTPUT= type: Specify Output File Type”. file will be deleted unless you indicate otherwise in the Project Properties dialog. so these files may redefine anything that is defined in the C standard libraries. Rather than the traditional method of linking in a generic. the MPLAB XC8 C Compiler determines what runtime startup code is required from the user’s program and then generates this code each time you build. The default operation of the driver is to keep the startup module. The file created by the driver may be deleted after compilation. . Library files are more easy to manage and may result in faster compilation times. See also Section 5. User-created libraries that should be searched when building a project can be listed on the command line along with the source files. Library files specified on the command line are scanned first for unresolved symbols. As with Standard C library functions.8. These header files can then be included into source code when required. Both the driver and code generator are involved in generating the runtime startup code.4.1 “Runtime Startup Code” details specifically what actions are taken by this code and how it interacts with programs you write. If you are using an IDE to perform the compilation the destination directory may be dictated by the IDE itself. Section 5. and this operation can be controlled with the keep suboption to the --RUNTIME option. if using MPLAB IDE to build. Several versions of a library may need to be created to allow it to be used for different projects.2 Startup and Initialization A C program requires certain objects to be initialized and the device to be in a particular state before it can begin execution of its function main.2 USER-DEFINED LIBRARIES User-defined libraries may be created and linked in with programs as required. such as clearing uninitialized C variables and copying initialized C variables. however. If the startup module is kept.as and will be located in the current working directory. but must be compatible with the target device and options for a particular project. Libraries can be created manually using the compiler and the librarian. The runtime startup code is regenerated every time you build a project. Alternatively.4. This code is output along with the rest of the C program.15. MPLAB X IDE store this file in the dist/default/production directory in your project directory. The driver creates the code which handles device setup and this code is placed into a separate assembly startup module. library files can be created directly from the compiler by specifying a library output using the --OUTPUT option. 4. LIBR.4 “Replacing Library Modules”. see Section 4. The code generator produces code which initializes the C environment. It is the job of the runtime startup code to perform these tasks. DS52053B-page 82  2012 Microchip Technology Inc.

some aspects of the runtime code can be controlled.10. you should use power-up feature described later in Section 5. using the --RUNTIME option.  2012 Microchip Technology Inc.10.8. Section 4.2 “The Powerup Routine”.1 “Runtime Startup Code” which describes the functional aspects of the code contained in this module and its effect on program operation.XC8 Command-line Driver Generation of the runtime startup code is an automatic process which does not require any user interaction. if required. however. but If you require any special initialization to be performed immediately after reset. DS52053B-page 83 .50 “--RUNTIME: Specify Runtime Environment” describes the use of this option. See Section 5. The runtime startup code is executed before main.

The default output file types can be controlled by compiler options. their base name is derived from the first C source file listed on the command line. or the base name (file name without extension) of the first C source file specified on the command line. The default behavior of xc8 is to produce a Microchip format COFF and Intel HEX output. . in addition to the HEX file.. the base names of these files will be the project name. Some of the output files contain project-wide information and are not directly associated with any one particular input file.sym extension) produced by the linker.5. the source file input. 4. such as MPLAB X IDE.c will create a p-code file called input. The compiler is able to directly produce a number of the output file formats which are used by the 8-bit PIC development tools. Unless changed by a driver option.g.5 COMPILER OUTPUT There are many files created by the compiler during the compilation. the term project name will refer to either the name of the project created in the IDE.5 “CROMWELL”) to produce the output debug files. and the SYM file contains address information. are combined by the CROMWELL application (see Section 8. The File Type column lists the filename extension which will be used for the output file. The extensions used by these files are fixed and are listed together with this option’s description in Section 4. e.8. the map file. Note: Throughout this manual.5. such as COFF and ELF files. The COFF file is used by debuggers to obtain debugging information about the project. the name is based on the first input file (regardless of type) on the command line.g. but many remain and are used for programming the device. If there are no files of this type specified. A large number of these are intermediate files and some are deleted after compilation is complete. there is typically a project file that is created for each application. or for debugging purposes. to specify options to the compiler. If the names of these output files are not specified by a compiler option. DS52053B-page 84  2012 Microchip Technology Inc.1 SYMBOL FILES xc8 creates two symbol files which are used to generate the debug output files. and the SDB file (.44 “--OUTPUT= type: Specify Output File Type”. 4. However check the manual for the IDE you are using for more details. These are the SYM files (. For example. such as the COFF file. e.p1. Table 4-14 shows all output format options available with xc8 using the --OUTPUT option. The SDB file contains type information. If you are using an IDE..MPLAB® XC8 C Compiler User’s Guide 4.1 Output Files The names of many output files use the same base name as the source file from which they were derived.These two files. The name of this project is used as the base name for project-wide output files.1. the --OUTPUT option. unless otherwise specified by the user.sdb extension) produced by the code generator.

It is essential when confirming if compiler-produced code that accesses objects is atomic. produced by the linker. and the map file. It also shows all the unused memory areas in a device and memory fragmentation. see Section 6. or how assembly source may have been optimized. assuming the linker was executed and ran to completion.5. The map file shows information relating to where objects were positioned in memory. The compiler options --ASMLIST (Section 4.15.XC8 Command-line Driver 4.8 “-M: Generate Map File”) specifies generation of a map file. and for determining the exact placement of objects and functions.5 “Assembly-Level Optimizations” for more information on the contents of this file. DS52053B-page 85 . It is useful for confirming if user-defined linker options were correctly processed. See Section 7.1 “Program Sections”.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”) generates a list file.map extension. and the -M option (Section 4.2 Diagnostic Files Two valuable files produced by the compiler are the assembly list file.  2012 Microchip Technology Inc. It is useful for information such as how C source was encoded. produced by the assembler. and which will be assigned the project name and extension . and shows the psects in which all objects and code are placed.8.4 “Map Files” for complete information on the contents of this file. There is one map file produced when you build a project. including C library files. The file will be assigned the project name and . see Section 5. One additional list file is produced for each assembly source file compiled in the project. For an introductory guide to psects. The assembly list file contains the mapping between the original source code and the generated assembly code.lst. And.8. There is one list file produced for the entire C program.

4. the alert system can read the message type and the string to be displayed from the MDF.6 COMPILER MESSAGES All compiler applications.6. its number is looked up in the MDF that corresponds to the currently selected language. five from the code generator.29 “--ERRORS: Maximum Number of Errors”. messages with a particular number can be disabled. xc8. DS52053B-page 86  2012 Microchip Technology Inc. If a message is an error. which are stored in the dat directory in the compiler’s installation directory.6. Although the information in the MDF can be modified with any text editor. Once found.2 “Message Language”. use textual messages to report feedback during the compilation process. The language of messages can be altered as discussed in Section 4. as described in the same section.MPLAB® XC8 C Compiler User’s Guide 4. thus specifying a maximum of five errors will allow up to five errors from the parser.1 “Disabling Messages”. there are several other pieces of information that may be displayed. The messaging system is described in this section and a complete list of all warning and error messages can be found in Appendix B. such as the message number. A pragma can also be used to disable a particular message number within specific lines of code.3 “Message Type” and the type can be overridden by the user. . etc. These methods are explained in Section 4. When a message is requested by a compiler application. so that only those which the user considers significant will be displayed. which allows consistency during all stages of the compilation process.6.8.6. see Section 4.1 Messaging Overview A message is referenced by a unique number which is passed to the messaging system by the compiler application that needs to convey the information. “Error and Warning Messages”. etc. In addition to the actual message string. the name of the file for which the message is applicable. compilation of the current module will cease.5. After a certain number of errors has been reached. five from the linker. five from the driver. a counter is incremented. A centralized messaging system is used to produce the messages. Provided the message is enabled and it is not a warning message whose level is below the current warning threshold. In addition. this is not recommended. The user is also able to set a threshold for warning message importance. the file’s line number and the application that issued the message. This counter is reset for each internal compiler application. Message behavior should only be altered using the options and pragmas described in the following sections. The message string corresponding to this number is obtained from Message Description Files (MDF). including the command-line driver. the message string will be displayed. The default number of errors that will cause this termination can be adjusted by using the --ERRORS option. There are several different message types which are described in Section 4.

XC8 Command-line Driver 4. however. but is unusual and may lead to a runtime failure of the code. see Section 4.txt MDF name If a language other than English is selected. The code or situation that triggered the warning should be investigated. Compilation will be attempted for the remaining source code in the current module. Error Messages indicate source code that is illegal or that compilation of this code cannot take place. compilation of the current module will continue. These are described below along with the compiler’s behavior when encountering a message of each type.  2012 Microchip Technology Inc. but no additional modules will be compiled and the compilation process will then conclude. the message in the requested language will be displayed. under Windows. Warning Messages indicate source code or some other situation that can be compiled.2 Message Language xc8 supports more than one language for displayed messages. DS52053B-page 87 .6. Fatal Error Messages indicate a situation that cannot allow compilation to proceed and which requires the compilation process to stop immediately. or in the XML configuration file on other systems. On subsequent builds.txt de_msgs. and the message cannot be found in the appropriate non-English MDF. Advisory Messages convey information regarding a situation the compiler has encountered or some action the compiler is about to take. Compilation will continue as normal after such a message is issued. otherwise. it may be changed permanently by using the --LANG option together with the --SETUP option which will store the default language in either the registry. If an English message string is not present. Table 4-3 shows the MDF applicable for the currently supported languages. a message similar to: error/warning (*) generated.6. the default language used will be that specified. the alert system tries to find the message in the English MDF. the default language can be specified when installing the compiler. Under Windows. but no description available where * indicates the message number that was generated that will be printed.8.35 “--LANG: Specify the Language for Messages”. Alternatively. The information is being displayed “for your interest” and typically requires no action to be taken. There is one MDF for each language supported. TABLE 4-3: English German French SUPPORTED LANGUAGES Language en_msgs.3 Message Type There are four types of messages. 4. The default language may be changed on the command line using the --LANG option.txt fr_msgs. as will compilation of any remaining modules.

6. This format can vary from one compiler application to another. as DOS interprets a single percent character as an argument and will not pass this on to the compiler.4 Message Format By default. Some messages relate to issues in driver options which are in no way associated with any source code. The names of these environment variables are given in Table 4-4. Using this option produces messages that are better suited to machine parsing. which is less directly associated with any particular line of code. messages are printed in a human-readable format. the driver first checks to see if special environment variables have been set. the format dictated by these variables are used as a template for all messages produced by all compiler applications.8. The general form of messages produced when using the -E option is: filename line: (message number) message string (type) The -E option also has another effect.28 “--ERRFORMAT: Define Format for Compiler Messages”. in turn.3 “-E: Redirect Compiler Errors to a File”.8. and are less user-friendly. These options take a string as their argument. which are discussed below. . --WARNFORMAT and --ERRFORMAT.MPLAB® XC8 C Compiler User’s Guide 4. The driver option -E (with or without a filename) alters the format of all displayed messages. see Section 4. the parser) are typically able to pinpoint the area of interest down to a position on a particular line of C source code. There are several ways of changing the format in which message are displayed. as their variable counterparts. Some applications (for example. DS52053B-page 88  2012 Microchip Technology Inc. The option strings are formatted. See Section 4. Typically each message is displayed on a single line. may be overridden by the driver options: --MSGFORMAT. whereas other applications. such as the linker. Printf-like placeholders can be placed within the string to allow the message format to be customized. If so. can at best only indicate a module name and record number. two percent characters will need to be used to specify the placeholders. TABLE 4-4: MESSAGING ENVIRONMENT VARIABLES Variable HTC_MSG_FORMAT HTC_WARN_FORMAT HTC_ERR_FORMAT Effect All advisory messages All warning messages All error and fatal error messages The value of these environment variables are strings that are used as templates for the message format. When used. TABLE 4-5: %a %c %f %l %n %s MESSAGING PLACEHOLDERS Placeholder Column number Filename Line number Message number Message string (from MDF) Replacement Application name If these options are used in a DOS batch file. For example: SET HTC_ERR_FORMAT="file %%f: line %%l" Environment variables. and can use the same placeholders. The placeholders and what they represent are indicated in Table 4-5. since each application reports information about different file formats.

If the -E option is now used and the compiler issues the same messages. but.c: main() 17: ip = &b. but that of the error message was not. main. the message number (362) substituted the %n placeholder. as shown. The application name (parser) was substituted for the %a placeholder.c: 12: (362) redundant "&" applied to array (warning) (492) attempt to position absolute psect "text" is illegal (error) The user now uses the --WARNFORMAT in the following fashion: --WARNFORMAT="%a %n %l %f %s" When recompiled. ^ (362) redundant "&" applied to array (warning) (492) attempt to position absolute psect "text" is illegal Notice that the parser message format identifies the particular line and position of the offending source code. respectively). etc. DS52053B-page 89 . produces a warning from the parser and an error from the linker (numbered 362 and 492. the compiler will output: main.  2012 Microchip Technology Inc. the following output will be displayed: parser 362 12 main. a project is compiled. The warning format now follows the specification of the environment variable.XC8 Command-line Driver For example.c redundant "&" applied to array (492) attempt to position absolute psect "text" is illegal (error) Notice that the format of the warning was changed.

To specify an error message number in the --MSGDISABLE command. however. This pragma will only affect warnings that are produced by either the parser or the code generator. Warnings may also be disabled by using the --MSGDISABLE option.2 It is also possible to change the type of some messages. This option takes a comma-separated list of message numbers.8. .4.59 “--WARN: Set Warning Level”.5 Changing Message Behavior Both the attributes of individual messages and general settings for the messaging system can be modified during compilation.6. Some warning messages can also be disabled by using the warning pragma. Those warnings listed are disabled and will never be issued.5. the number must be followed by :off to ensure that it is disabled. This can only be done for messages generated by the parser or code generator. regardless of the current warning level threshold.e.5. CHANGING MESSAGE TYPES 4.MPLAB® XC8 C Compiler User’s Guide 4.14. The higher the number. There are both driver options and C pragmas that can be used to achieve this.. The default threshold is 0 which implies that only warnings with a warning level of 0 or higher will be displayed by default. For example: --MSGDISABLE=195:off will disable error number 195. Always use extreme caution when exercising these options. The information in this option is propagated to all compiler applications. errors directly associated with C code. so its effect will be observed during all stages of the compilation process. i. 4.8.11 “The #pragma warning Directive” for more information on this pragma. See Section 5.4. see Section 4.14. a more verbose form of the command is required to confirm the action. This number is specified in the MDF and ranges from -9 to 9. Any warnings whose level is below that of the current threshold are not displayed. see Section 4. Warning messages can be disabled by adjusting the warning level threshold using the --WARN driver option. the more important the warning.38 “--MSGDISABLE: Disable Warning Messages”.1 DISABLING MESSAGES Each warning message has a default number indicating a level of importance. Error messages can also be disabled.6.11 “The #pragma warning Directive” for more information on this pragma. See Section 5.6. Note: Disabling error or warning messages in no way fixes the condition which triggered the message. DS52053B-page 90  2012 Microchip Technology Inc.

for example: -C.33 “--HELP: Display Help”. “-”. =. if you are compiling from within the MPLAB X IDE.7. Multi-letter. to indicate that they should be excluded.XC8 Command-line Driver 4. If you are compiling from within the MPLAB X IDE. the default operation – in fact this cannot be disabled – is to always produce an assembly list file. always check that all options are explicitly specified. issue explicit options to the compiler (unless changed in the Project Properties dialog). Some commonly used suboptions include default.1 Default Options If you run the compiler driver from the command line and do not specify the option for a feature. unless you specify the --ASMLIST option on the command line. the driver can determine that the option --DOUBLE.-asm indicates that the default optimization be used. or word. For example: --OPT=default. for example: -Ddebug. see 4. by default. or a minus character “-”. For example: --OPT=none will turn off all optimizers. +. which represent the default specification that would be used if this option was absent altogether. See the –-HELP option. and none. for example: --ASMLIST. For example: --OPT=-asm is the same as the previous example. and these options may be different to those that are the default on the command line.1 GENERAL OPTION FORMATS All single letter options are identified by a leading dash character. If the first character after the equal sign is + or -. Some single letter options specify an additional data field which follows the option name immediately and without any whitespace. for example. 4. to indicate that they are in addition to the other suboptions present.8. options have two leading dash characters.0. which indicates that all suboptions should be disabled. for example: --OUTPUT=hex. You can check what the default behavior is by using the --HELP=option on the command line. it will. for more information about options and suboptions. but that the assembler optimizer should be disabled. The exact format of the options varies and are described in detail in the following sections. is not a -D option followed by the argument OUBLE. options are written in upper case and suboptions are in lower case. If you are compiling the same project from the command line and from the MPLAB X IDE.cof.33 “--HELP: Display Help”. all. You can also specify the default suboption to double-dash options which will also invoke the default behavior. (Because of the double dash. 4. the default operation of the compiler is to not produce an assembly list file.7 XC8 DRIVER OPTIONS This section looks at the general form of xc8 command-line options and what action the compiler will perform if no option is specified for a certain feature. Some suboptions may be prefixed with a plus character.  2012 Microchip Technology Inc. it will default to a certain state.8. In this manual. which indicates that all the available suboptions should be enabled as if they had each been listed.) Some of these word options use suboptions which typically appear as a comma-separated list following an equal character.7. then the default keyword is implied. However. For example. DS52053B-page 91 . Section 4.

assembler and linker. . however command shells in most operating systems are case sensitive when it comes to names of files. xc8.8 OPTION DESCRIPTIONS Most aspects of the compilation can be controlled using the command-line driver. such as the code generator. xc8 recognizes the compiler options which are tabled below and are explained in detail in the sections following. The case of the options is not important. The driver will configure and execute all required applications.MPLAB® XC8 C Compiler User’s Guide 4. TABLE 4-6: -C -Dmacro -Efilename -G[filename] -Ipath -Largument -M[filename] -Nnumber -Ofile -P -Q -S -Umacro -V --ADDRQUAL=qualifier --ASMLIST --CCI --CHAR=type --CHECKSUM=specification --CHIP=device --CHIPINFO --CODEOFFSET=value --DEBUGGER=type --DOUBLE=size --ECHO --EMI=mode --ERRATA=type --ERRFORMAT=format --ERRORS=number --FILL=specification --FLOAT=size --GETOPTION=argument --HELP=option --HTML=file --LANG=language --MEMMAP=mapfile --MODE=mode DRIVER OPTIONS Option Meaning Compile to object file and stop Define preprocessor macro symbol Redirect compile errors Generate symbolic debug information Specify include path Set linker option Generate map file Specify identifier length Specify output filename and type Preprocess assembly source Quiet mode Compile to assembly file and stop Undefine preprocessor macro symbol Verbose mode Specify address space qualifier handling Generate assembly list file Enforce and expect CCI rules Default character type (defunct) Calculate a checksum and store the result in program memory Select target device Print device information Specify ROM offset address Set debugger environment Size of double type Echo command line Select external memory interface operating mode Specify errata workarounds Set error format Set maximum number of errors Specify a ROM-fill value for unused memory Size of float type Get advanced options Help Generate HTML debug files Specify language Display memory map Choose operating mode DS52053B-page 92  2012 Microchip Technology Inc.

3.1 -C: Compile to Object File The -C option is used to halt compilation after executing the assembler. DS52053B-page 93 . leaving a relocatable object file as the output. see Section 4.  2012 Microchip Technology Inc.3 “Multi-Step Compilation” for more information on generating and using intermediate files. Use --PASS1 to generate intermediate files from C source.45 “--PASS1: Compile to P-code”.XC8 Command-line Driver TABLE 4-6: DRIVER OPTIONS (CONTINUED) Option --MSGDISABLE=list --MSGFORMAT=specification --NODEL --NOEXEC --OBJDIR=path --OPT=optimizations --OUTDIR=path --OUTPUT=path --PASS1 --PRE --PROTO --RAM=ranges --ROM=ranges --RUNTIME=options --SCANDEP --SERIAL=specification --SETOPTION=argument --SETUP=specification --SHROUD --STRICT --SUMMARY=type --TIME --VER --WARN=number Meaning Disable warning messages Set advisory message format Do not remove temporary files Do not execute compiler applications Set object files directory Control optimization Set output directory Set output formats Produce intermediate p-code file and stop Produce preprocessed source files and stop Generate function prototypes Adjust RAM ranges Adjust ROM ranges Specify runtime options Scan for dependencies Insert a hexadecimal code or serial number Set advanced options Setup the compiler Shroud (obfuscate) generated p-code files Use strict ANSI keywords Summary options Report compilation times Show version information Set warning threshold level --WARNFORMAT=specification Set warning format 4. It is frequently used when compiling assembly source files using a make utility. See Section 4.8. It cannot be used unless all C source files are present on the command line.8.

the command: xc8 --CHIP=16F877AA -Ddebug -Dbuffers=10 test. use the -E option to create the file then use -E+ when compiling all the other source files. warnings.err -C asmcode. exactly as if it had been defined using a #define directive in the source code. at the start of the error filename.E option as follows: xc8 --CHIP=16F877AA -Eproject. to compile a number of files with all errors combined into a file called project. use: "-DMY_STRING=\\\"hello world\\\"" (you must include the quote characters around the entire option as there is a space character in the macro definition).err x. The first is to change the format of displayed messages.err -O --PASS1 main. or -Dmacro= text which is equivalent to: #define macro text where text is the textual substitution required.c If you wish to compile several files and combine all of the errors generated into a single text file.3 -E: Redirect Compiler Errors to a File This option has two purposes.6 “Compiler Messages” has more information regarding this option as well as an overview of the messaging system and other related driver options. 4.c and redirect all errors to x. See Section 4. This option may take one of two forms.2 -D: Define Macro The -D option is used to define a preprocessor macro on the command line. +. For example. (including the quote characters) in the Windows environment. DS52053B-page 94  2012 Microchip Technology Inc. The second is to optionally allow messages to be directed to a file as some editors do not allow the standard command line redirection facilities to be used when invoking the compiler.c xc8 --CHIP=16F877AA -E+project.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. The general form of messages produced with the -E option in force is: filename line_number: (message number) message string (type) If a filename is specified immediately after -E. Thus. . to compile x.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. -Dmacro which is equivalent to: #define macro 1 placed at the top of each module compiled using this option. it is treated as the name of a file to which all messages (errors.err.8. To pass the C string. use: -DMY_STRING=\"hello\ world\".c with macros defined exactly as if the C source code had included the directives: #define #define debug 1 buffers 10 Defining macros as C string literals requires bypassing any interpretation issues in the operating system that is being used.c xc8 --CHIP=16F877AA -E+project.c will compile test.err -O --PASS1 part1.MPLAB® XC8 C Compiler User’s Guide 4.8.as Section 4.err. use the command: xc8 --CHIP=16F877AA -Ex. For example. "hello world".) will be printed.c The -E option also allows errors to be appended to an existing file by specifying an addition character. etc. for example: xc8 --CHIP=16F877AA -E+x. you could use the . Under Linux or Mac OS X.err y.

lib. simply include the libraries’ names on the command line along with your source files.c will search the directories c:\include and d:\myapp\include for any header files included into the source code.sym extension) for use with supported debuggers and simulators such as MPLAB IDE. See Section 4. These default search paths are searched after any user-specified directories have been searched.6 -L: Scan Library The -L option is used to specify additional libraries which are to be scanned by the linker.lib are added. DS52053B-page 95 . The directory can either be an absolute or relative path.4 “INCLUDE”.8. even if no -I option is present. As indicated. If header filenames are specified using quote characters rather than angle brackets.4.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4.  2012 Microchip Technology Inc. scan the library pic42c-l. If no filename is given. not the project directory. the option -Gtest. the symbol file will have the project name (see Section 4. For example: xc8 --CHIP=16F877AA -C -Ic:\include -Id:\myapp\include test. Note that if compiling within MPLAB IDE.10. 4.8.4 -G: Generate Source-Level Symbol File The -G option allows specification of the filename used for the source-level symbol file (. allowing additional versions of standard library functions to be accessed. The argument to -L is a library keyword to which the prefix pic. See Section 6. and the suffix .5 “Compiler Output”. as in #include "lcd. All libraries must be located in the lib directory of the compiler installation directory. for example. Thus the option -Ll when compiling for a 16F877A will.XC8 Command-line Driver 4. 4.sym. See also Section 4. Symbol files generated using the -G option include source-level information for use with source-level debuggers.h". numbers representing the device range.5 -I: Include Search Path Use -I to specify an additional directory to search for header files which have been included using the #include directive.lib and the option -Lxx will scan a library called pic42c-xx. The -I option can be used more than once if multiple directories are to be searched. and an extension of . number of ROM pages and the number of RAM banks.sym.2 “Invoking the Compiler”). The compiler’s include directory containing all standard header files is always searched. This option has no effect for files that are included into assembly source using the assembly INCLUDE directive. For example. or add these to your project. If you wish the linker to scan libraries whose names do not follow the above naming convention or whose locations are not in the lib subdirectory.8. then the current working directory is searched in addition to the compiler’s include directory. Libraries specified using the -L option are scanned before the standard C library. the argument to the -L option is not a complete library filename.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. then search the default include directory.sym generates a symbol file called test. the search path is relative to the output directory.

if a default linker option was: -preset_vec=00h. Take care with command-line options.15.init. and perform the appropriate operation. you must add driver options (not linker options). with the extension . The linker will then process this option.MPLAB® XC8 C Compiler User’s Guide 4.8 -M: Generate Map File The -M option is used to request the generation of a map file. then the name of the map file will have the project name (see Section 4. similarly the driver cannot interpret linker options. when. The default option that you are deleting or replacing must contain an equal character. If there are no characters following the first equal character in the -L option. but the -pinit linker option would be removed entirely.9.map.intentry. the -N option will be passed on to the linker without any subsequent interpretation by the driver.14. as may be the case if the program contains hand-written assembly code which contains user-defined psects (see 6. For example. For example. the text will be passed directly to the linker without being interpreted by xc8. See Section 7. If the string starting from the first character after the -L up to the first equal character. then no replacement will be made for the default linker options that will be deleted. Section 4. The -L option is especially useful when linking code which contains non-standard program sections (or psects). This option can also be used to replace default linker options. it would be necessary to invoke the linker manually to allow the linker options to be adjusted. if the option -L-N is specified. then (the reference to the psect or class name in the default option. it is always the command-line driver.4 “Map Files” for information regarding the content of these files.end_init the driver option -L-pinit=100h would result in the following options being passed to the linker: -pinit=100h -preset_vec=00h. In most situations. No warning is generated if such a default linker option cannot be found. The -L option is a means of allowing a linker option to be specified via a driver option. Without this -L option. matches a psect or class name in the default options. "=".1 “Program Sections”).3 “The Compilation Sequence”).6 “-L: Scan Library”. If no filename is specified with the option. If -L is followed immediately by text starting with a dash character “-”. . the driver option -L-pinit= will adjust the default options passed to the linker. xc8. that is being executed.3 “PSECT” and Section 5. it is assumed the option is the library scan option.4.7 -L-: Adjust Linker Options Directly The -L driver option can be used to specify an option which will be passed directly to the linker. are deleted) that default linker option is replaced by the option specified by the -L. The map file is generated by the linker and includes detailed information about where objects are located in memory.4. as above.8. These driver options will be used by the driver to generate the appropriate linker options during the linking process. This option is on by default when compiling from within MPLAB X IDE and using the Universal Toolsuite.8. Note the end_init linker option has been removed entirely. or C code which uses the #pragma psect directive (see 5. it is invoked. If you need to add alternate linker settings in the Linker category in the Project Properties dialogue. If the -L option is not followed immediately by a dash character.8. For example. 4. The linker cannot interpret command-line driver options. and if. DS52053B-page 96  2012 Microchip Technology Inc. and the remainder of that option.8 “The #pragma psect Directive”).

.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. such as #include.3 “The Compilation Sequence”.8. DS52053B-page 97 . such as macro names. The -O option can also change the directory in which the output file is located by including the required path before the filename.8. See Section 4. if the option -Oc:\project\output\first is used. and C-style comments with assembler code. assembler files are not preprocessed. thus allowing the use of preprocessor directives. See Section 4. and can be adjusted to a minimum of 31. see Section Section 4. If the --STRICT option is used. see Section 4. etc. and SYM file creation (-G. The default length is also 255. The options that specify MAP file creation (-M. 4. By default. Code which uses a longer identifier length will be less portable. Note that if -O specifies a path which is inconsistent with the path specified in the --OUTDIR option.12 -Q: Quiet Mode This option places the compiler in a quiet mode which suppresses the Microchip Technology Incorporated copyright notice from being displayed. This option also controls the significant length of identifiers used by the preprocessor. this will result in an error.8.4 “-G: Generate Source-Level Symbol File”) override any name or path information provided by -O relevant to the MAP and SYM file.10 -O: Specify Output File This option allows the basename of the output file(s) to be specified. Any extension supplied with the filename will be ignored. If no -O option is given. such as the HEX file. The files whose names are affected by this option are those files that are not directly associated with any particular source file.8.9 -N: Identifier Length This option allows the significant C identifier length (used by functions and variables) to be decreased from the default value of 255.XC8 Command-line Driver 4.11 -P: Preprocess Assembly Files The -P option causes assembler source files to be preprocessed before they are assembled. see Section 4. To change the directory in which all output and intermediate files are written.8.  2012 Microchip Technology Inc. Valid sizes for this option are from 32 to 255. the base name of output file(s) will be the same as the project name. and will be placed in the directory c:\project\output.8 “-M: Generate Map File”). use the --OUTDIR option. For example.43 “--OUTDIR: Specify a Directory For Output Files”. 4. will use the base name first.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. see Section 4. This will then also specify the output directory for any files produced by the linker or subsequently run applications. The option has no effect for all other values. the default significant identifier length is reduced to 31.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. 4.8.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. Any relative paths specified are with respect to the current working directory. the MAP and HEX file. MAP file and SYM file.8.

The name of the compiler application being executed will be displayed. When used.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.14 -U: Undefine a Macro The -U option.c will produce an assembly file called test. is equivalent to: #undef draft placed at the top of each module compiled using this option.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”) in that it does not contain op-codes or addresses and it may be used as a source file in subsequent compilations. The command xc8 --CHIP=16F877A -S test. the compiler will display the command lines used to invoke each of the compiler applications described in Section 4. The file produced by this option differs to that produced by the --ASMLIST option (see Section 4.MPLAB® XC8 C Compiler User’s Guide 4. if there is more than one compiler installed. -Udraft. To take advantage of the benefits of the compilation technology in the compiler.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.15 -V: Verbose Compile The -V option specifies verbose compilation.8. This option takes the form -Umacro. DS52053B-page 98  2012 Microchip Technology Inc.8. it must compile and link all the C source code in a single step. the inverse of the -D option. which contains the assembly code generated from test. is used to undefine predefined macros. This option is useful for checking assembly code output by the compiler. however this should only be done for exploratory reasons. it will display the full path to each compiler application as well as the full command-line arguments.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. for example. . If this option is used twice (-V -V).3 “The Compilation Sequence”. One assembly file will be generated for all the C source code.8.as.13 -S: Compile to Assembler Code The -S option stops compilation after generating an assembly output file. plus all the command-line arguments to this application. 4.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. This option is useful for confirming options and files names passed to the compiler applications. See Section 4. This would be useful to ensure that the correct compiler installation is being executed. but is not a valid assembly source file. including p-code library code. See the --PASS1 option (Section 4.45 “--PASS1: Compile to P-code”) to generate intermediate files if you wish to compile code using a two-step process or use intermediate files.8. where macro is the name of the macro to be undefined The option. 4. The assembly list file is more human readable. The generated file is valid assembly code which could be passed to xc8 as a source file.8. See Section 4.c.

17 --ASMLIST: Generate Assembler List Files The --ASMLIST option tells xc8 to generate assembler listing files for the C and assembly source modules being compiled. DS52053B-page 99 . In the case of listings for C source code.16 --ADDRQUAL: Set Compiler Response to Memory Qualifiers The --ADDRQUAL option indicates the compiler’s response to non-standard memory qualifiers in C source code.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. TABLE 4-7: Selection require request ignore reject COMPILER RESPONSES TO MEMORY QUALIFIERS Response The qualifiers will be honored. On PIC18 devices. See Section 6. The same information is shown in the list files for assembly source code.4. due to the additional information placed in these files. The qualifiers will be honored.XC8 Command-line Driver 4. etc.5 “Assembly-Level Optimizations” for full information regarding the content of these files. 4.8. For example.) Code or options that do not conform to the CCI standard will be flagged by compiler warnings. i.18 --CCI: Enforce and Expect CCI Conformance Enabling this option will request the compiler to check all source code and compiler options for compliance with the Common Compiler Interface (CCI) standard. the list file shows both the original C code and the corresponding assembly code generated by the compiler. but silently ignore them if they cannot be met.  2012 Microchip Technology Inc. One assembly list file is produced for the entire C program. 4. By default these qualifiers are ignored. The near qualifier is affected by this option. cannot be used as assembly source files. Using this option allows these qualifiers to be interpreted differently by the compiler.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. This option is on by default when compiling under MPLAB IDE. For more information. Additionally. bank2. one assembly list file is produced for each assembly source file in the project. an error will be issued. including code from the C library functions. The qualifiers will be ignored and code compiled as if they were not used. bank1. they are accepted without error. and for other 8-bit devices. See Section 4. If the qualifiers are encountered. Assembly list files use a .2 “Startup and Initialization”.8. if possible. an error will be immediately generated.8. see Section 4. but have no effect..) are affected. The suboptions are detailed in Table 4-7.e.lst extension and. when using the option --ADDRQUAL=request the compiler will try to honor any non-standard qualifiers. including the runtime startup code. Code that complies with this standard is portable across all MPLAB XC compilers. this option also affects the far qualifier. (The document describing the CCI standard is pending at the time of this user’s guide’s writing. No error will be generated if they cannot be followed. If they cannot be met. the bankx qualifiers (bank0.

or device.code=c][. The checksum calculations are performed by the HEXMATE application. To see a list of supported devices that can be used with this option. The selectable algorithms are described in Table 8-9. algorithm=n select one of the checksum algorithms implemented in HEXMATE. DS52053B-page 100  2012 Microchip Technology Inc. Fletcher’s algorithm will be used. The names listed are those chips defined in the chipinfo file and which may be used with the --CHIP option.19 --CHECKSUM: Calculate a Checksum This option will perform a checksum over the address range specified and store the result at the destination address specified.offset=][.width=1.algorithm=8 will calculate a 1 byte checksum from address 0x800 to 0xfff and store this at address 0x20. Result widths from one to four bytes are permitted. hexadecimal constants. unused locations within the specified address range will be filled with FFFh for baseline devices. code=nn is a hexadecimal code that will trail each byte in the checksum result.8. Compiler execution will terminate after this list has been printed.algorith m=a] Additional specifications are appended as a comma-separated list to this option.21 “--CHIPINFO: Display List of Supported Devices”. A negative width will store the result in little-endian byte order.20 --CHIP: Define Device This option must be used to specify the target device.5 “-CK”. This can allow each byte of the checksum result to be embedded within an instruction. -CHECKSUM=start-end@destination[. 3FFFh for mid-range devices.6. The information in this driver option is passed to the HEXMATE application when it is executed. The start. for the compilation.8. Such specifications are: width=n selects the width of the checksum result in bytes. The general form of this option is as follows. This is the only compiler option that is mandatory when compiling code. end and destination attributes are. .MPLAB® XC8 C Compiler User’s Guide 4. For example: --checksum=800-fff@20. use the --CHIPINFO option described in Section 4. offset=nnnn specifies an initial value or offset to be added to this checksum.21 --CHIPINFO: Display List of Supported Devices The --CHIPINFO option displays a list of devices the compiler supports. This is to remove any unknown values from the equation and ensure the accuracy of the checksum result. or FFFF for PIC18 devices.1. 4. See Section 8. If an accompanying --FILL option has not been specified. 4. by default.width=w][.8.8.

XC8 Command-line Driver 4. if the option --CODEOFFSET=600 is specified. because memory resources are not being used by the tool. such as bootloaders. in the case of mid-range PIC devices.  2012 Microchip Technology Inc. TABLE 4-8: none icd2 icd3 pickit2 pickit3 realice SELECTABLE DEBUGGERS Suboption Debugger selected No debugger (default) MPLAB® ICD 2 MPLAB ICD 3 PICkit™ 2 PICkit 3 MPLAB REAL ICE™ in-circuit emulator For example: xc8 --CHIP=16F877AA --DEBUGGER=icd2 main. Such a conflict would lead to runtime failure. see Section 4. then the debugger option can be set to none. MPLAB X IDE should automatically apply this option for debug builds only once you have indicated the hardware tool in the Project Preferences. the interrupt vector will be moved from address 4 to 0x604.8. No code will be placed between address 0 and 0x600. it is necessary to shift the program image to an alternative address.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. all code psects (including Reset and interrupt vectors and constant data) will be adjusted to the address specified. if the MPLAB ICD 3 is only being used as a programmer).49 “--ROM: Adjust ROM Ranges”.23 --DEBUGGER: Select Debugger Type This option is intended for use for compatibility with development tools which can act as a debugger. See Section 4. See Section 4.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. but is not necessary.8. A leading 0x.8. DS52053B-page 101 . xc8 supports several debuggers and using this option will configure the compiler to conform to the requirements of that selected. or a trailing h hexadecimal specifier can be used.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. This option is used to specify a base address for the program code image and to reserve memory from address 0 to that specified in the option. The address is assumed to be a hexadecimal constant. If the debugging features of the development tool are not to be used (for example. the Reset vector will be moved from address 0 to address 0x600. or to the addresses 0x608 and 0x618 for PIC18 devices. When using this option. This option differs from the --ROM option in that it will move the code associated with the Reset and interrupt vectors which cannot be done using the --ROM option. For example.22 --CODEOFFSET: Offset Program Code to Address In some circumstances. The possible selections for this option are defined in Table 4-8.c Choosing the correct debugger is important as they can use memory resources that could otherwise be used by the project if this option is omitted. 4.

TABLE 4-9: wordwrite byteselect bytewrite EXTERNAL MEMORY INTERFACE MODES Mode Operation 16-bit word write mode (default) 16-bit byte select mode 8-bit byte write mode The selected mode will affect the code generated when writing to the external data interface. These modes are represented by those specified in Table 4-9.MPLAB® XC8 C Compiler User’s Guide 4. In byte select or byte write modes.8. DS52053B-page 102  2012 Microchip Technology Inc. Note that this option does not pre-configure the device for operation in the selected mode. . By default the compiler will choose the truncated IEEE754 24-bit implementation for double types. See your device data sheet for the registers and settings that are used to configure the device’s external interface mode.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. dummy reads and writes may be added to ensure that an even number of bytes are always written.24 --DOUBLE: Select Kind of Double Types This option allows the kind of double-precision floating-point types to be selected. With this option. See Section 4.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. 4. this can be changed to the full 32-bit IEEE754 implementation. In word write mode.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.8. The interface can operate in 16-bit modes. See Section 4.8. Each token of the command line will be printed on a separate line and will appear in the order in which they are placed on the command line.25 --ECHO: Echo Command Line Before Processing Use of this option will result in the driver command line being echoed to the stdout stream before compilation commences. dummy reads and writes are not generated and can result in more efficient code. word write and byte select mode or in an 8-bit mode: byte write mode. 4.26 --EMI: Select External Memory Interface Operating Mode The external memory interface available on some PIC18 devices can be operated in several modes.

but this set can be adjusted by using this option and the arguments presented in Table 4-10. Corruptible instruction fetch. if the 4000.27 --ERRATA: Specify Errata Workarounds This option allows specification of software workarounds to documented silicon errata issues.14.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. Apply FFFFh (NOP) at required locations.XC8 Command-line Driver 4. but to specifically disable the jump across 4000 errata. RAM contents can corrupt if async. for example. use the following. DS52053B-page 103 . To disable all software workarounds.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. The bit position is set if the errata is applied. use the following. A default set of errata issues apply to each device. Each errata listed in Table 4-10 represents a bit position in the value. That is.8. reset and bsr15 errata were applied. Reset occur during write access.  2012 Microchip Technology Inc. with the top most errata in the table the least significant. TABLE 4-10: Symbol 4000 fastints lfsr minus40 reset bsr15 daw eedatard eeadr ee_lvd fl_lvd tblwtint fw4000 resetram fetch ERRATA WORKAROUNDS Workaround Program mem accesses/jumps across 4000h address boundary Fast interrupt shadow registers corruption Broken LFSR instruction Program memory reads at -40 degrees GOTO instruction cannot exist at Reset vector Flag problems when BSR holds value 15 Broken DAW instruction Read EEDAT in immediate instruction after RD set Don't set RD bit immediately after loading EEADR LVD must stabilise before writing EEPROM LVD must stabilise before writing Flash Clear interrupt registers before tblwt instruction Flash write exe must act on opposite side of 4000h boundary. At present workarounds are only employed for PIC18 devices. See Section 4.-4000 A preprocessor macro ERRATA_TYPES (see Section 5. --ERRATA=default. the value assigned to ERRATA_TYPES would be 0x31.3 “Predefined Macros”) is set to a value to indicate the errata applied. --ERRATA=none To apply the default set of workarounds.

This option utilizes the features of the HEXMATE application. 0xBEF2 . This standard format is perfectly acceptable to a person reading the error output. --FILL=0xDEAD. then you will need to explicitly use the HEXMATE application.e. up to 20 error messages will be displayed by each application. It recommended that you do not adjust the message formats if compiling using this IDE. 0xBECF. that the unused tag which can be specified with the driver option does not exist in the HEXMATE options.e. respectively. • fill_expr can use the syntax (where const and increment are n-byte constants): .const fill memory with a repeating constant. 0xBEF1..const+=increment fill memory with an incrementing constant.const. This driver feature allows you to compile and fill unused locations in one step.const. which adjust the format of warning and advisory messages. This option allows the exact format of printed error messages to be specified using special placeholders embedded within a message template. i.29 --ERRORS: Maximum Number of Errors This option sets the maximum number of errors each compiler application. --FILL=w1:1 with fill every byte with the value 0x01. will display before execution is terminated.MPLAB® XC8 C Compiler User’s Guide 4. 4. 0xBEEF .. 0xBEEF. i. The usage of the driver option is: --FILL=[const_width:]fill_expr[@address[:end_address]] where: • const_width has the form wn and signifies the width (n bytes) of each constant in fill_expr. the default behavior of the compiler is to display any errors in a “human readable” form.0xBEEF DS52053B-page 104  2012 Microchip Technology Inc.0xBEEF becomes 0xDEAD...e.30 --FILL: Fill Unused Program Memory This option allows specification of a hexadecimal opcode that can be used to fill all unused program memory locations.6 “Compiler Messages” for full details of the messaging system employed by xc8.const-=increment fill memory with a decrementing constant. Note.8. If you prefer not to use the driver option and prefer to fill unused locations after compilation. If const_width is not specified. . --FILL=0xBEEF becomes 0xBEEF.8. also. the default value is the native width of the architecture. but is not generally usable with environments which support compiler error handling. By default. This section is also applicable to the --WARNFORMAT and --MSGFORMAT options. 0xBEEF.const fill memory with a list of repeating constants.28 --ERRFORMAT: Define Format for Compiler Messages If the --ERRFORMAT option is not used. the format of the compiler messages is automatically configured to what the IDE expects.6 “Compiler Messages” for full details of the messaging system employed by xc8. --fill=0xBEEF+=1 becomes 0xBEEF... That is. i. 4. i.. as well as the driver. See Section 4..0xDEAD.e. which is the default operation. See Section 4. Note the corresponding option in HEXMATE is -FILL (one leading dash) as opposed to the drivers --FILL option. If you are compiling using MPLAB IDE.8.0xBEEF. 0xBEDF. 0xBEF0. 0xBEBF . so it is only available when producing a HEX output file. and the placeholders which can be used with this option. --fill=0xBEEF-=0x10 becomes 0xBEEF.

.txt 4. 4.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. and which suboptions are enabled by default. for example: --GETOPTION=hlink.. The driver will expand this to the appropriate ranges and pass these to HEXMATE. so for example 1234 is a decimal value.37 “--MODE: Choose Compiler Operating Mode”). The types available to be selected are given in Table 4-11. decimal or hexadecimal.8.@address fill a specific address with fill_expr. To find out more about a particular option. --FILL=0xBEEF@0:0xFF puts 0xBEEF in unused addresses between 0 and 255 All constants can be expressed in (unsigned) binary. and is disabled when the compiler is operating in Free mode (see Section 4. The options are then saved into the given file.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE..8. as per normal C syntax. The option --HELP will display all options available.e. --FILL=0xBEEF@unused fills all unused memory with 0xBEEF.  2012 Microchip Technology Inc. i. This option is not required for most projects.8.e. i. the available suboptions.33 --HELP: Display Help This option displays information on the xc8 compiler options. See Section 4.@unused (or nothing) fill all unused memory with fill_expr. DS52053B-page 105 . 0xFF00 is hexadecimal and FF00 is illegal. use the option’s name as a parameter.32 --GETOPTION: Get Command-line Options This option is used to retrieve the command line options which are used for named compiler application. See also the --DOUBLE option in Section 4.options.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.31 --FLOAT: Select Kind of Float Types This option allows the size of float types to be selected.XC8 Command-line Driver • The options following fill_expr result in the following behavior: .e. --FILL=0xBEEF@0x1000 puts 0xBEEF at address 1000h . The options take an application name and a filename to store the options.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. For example: xc8 --help=warn will display more detailed information about the --WARN option.@address:end_address fill a range of memory with fill_expr. i. TABLE 4-11: double 24 32 FLOATING-POINT SELECTIONS Suboption 24-bit float (default) 32-bit float (IEEE754) Effect Size of float matches size of double type See Section 4. . octal.8.8. 4.24 “--DOUBLE: Select Kind of Double Types”.

german. This command would display the memory summary which is normally produced at the end of compilation by the driver. i.MPLAB® XC8 C Compiler User’s Guide 4. Each file icon is clickable and will open with the contents of that file. Some messages are only ever printed in English regardless of the language specified with this option. English is the default language unless this has been changed at installation. The files are stored in a directory called html.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. For legacy projects.37 --MODE: Choose Compiler Operating Mode This option selects the basic operating mode of the compiler. The list of all preprocessor macros (preprocessor icon) and a graphical memory usage map (Linker icon) provide information that is not otherwise readily accessible. Table 4-12 shows those languages currently supported. see Section 4. see Section 4. See Section 4.map --summary=psect. for example: xc8 --memmap=size..8. 4. DS52053B-page 106  2012 Microchip Technology Inc.2 “Message Language”.34 --HTML: Generate HTML Diagnostic Files This option will generate a series of HTML files that can be used to explore the compilation results of the latest build. instead of in the normal way through the command-line driver. Use this option at all stages of compilation to ensure files associated with all compilation stages are generated.html. The available types are pro.8.8.file This option is seldom required. deutsch SUPPORTED LANGUAGES Suboption English (default) French German Language 4. For more information. and even binary files open in a human-readable form.35 --LANG: Specify the Language for Messages This option allows the compiler to be configured to produce error. This is available for all intermediate files.8. A compiler operating in PRO mode uses full optimization and produces the smallest code size. warning and some advisory messages in languages other than English. TABLE 4-12: en. 4. The top level file (which can be opened with your favorite web browser) is called index.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. Each application icon can also be clicked to show a page containing information about that application’s options and build results.56 “--SUMMARY: Select Memory Summary Output Type”. the mode lite is accepted to mean the Free operating mode. The index page is a graphical representation of the compilation process. or by the use of the --SETUP option. The information printed is controlled by the --SUMMARY option. and Free mode only uses a minimum optimization level and will produce relatively large code. but would be useful if the linker is being driven explicitly. english fr.36 --MEMMAP: Display Memory Map This option will display a memory map for the map file specified with this option. .class. std and free. Standard mode uses limited optimizations. french.6. located in the output directory.e.8. francais de.

but not the PRO mode.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.43 “--OUTDIR: Specify a Directory For Output Files” and Section 4.10 “-O: Specify Output File” for more information.8.8. This option will not set the location of output files. See Section 4.40 --NODEL: Do Not Remove Temporary Files Specifying --NODEL when building will instruct xc8 not to remove the intermediate and temporary files that were created during the build process. For example if you have purchased a Standard compiler license. then all warnings are disabled. see Section 4. DS52053B-page 107 . See Section 4. See Section 4.6 “Compiler Messages” for full information on the compiler’s messaging system. 4.39 --MSGFORMAT: Set Advisory Message Format This option sets the format of advisory messages produced by the compiler.41 --OBJDIR: Specify a Directory For Intermediate Files This option allows a directory to be nominated in xc8 to locate its intermediate files. intermediate files will be created in the current working directory. 4.8.8.XC8 Command-line Driver Only those modes permitted by the compiler license status will be accepted.38 --MSGDISABLE: Disable Warning Messages This option allows warning or advisory messages to be disabled during compilation of a project.8. 4. If this option is omitted.28 “--ERRFORMAT: Define Format for Compiler Messages” and Section 4. Warning and error messages are controlled separately by other options.8.6. If the message list is specified as 0. 4.8.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4.  2012 Microchip Technology Inc. the format of the compiler messages is automatically configured to what the IDE expects.6 “Compiler Messages”. that compiler may be run in Standard or Free mode. See Section 4. The messagelist is a comma-separated list of warning numbers that are to be disabled. instead use --OUTDIR.60 “--WARNFORMAT: Set Warning Message Format” for information on changing the format of these sorts of messages.5 “Changing Message Behavior” for other ways to disable messages. It recommended that you do not adjust the message formats if compiling using this IDE.8. it will be ignored by this option. If you are compiling using MPLAB IDE. See Section 4. For full information on the compiler’s messaging system. If the number of an error is specified.

See also Section 4. These optimizations affect procedural abstraction.MPLAB® XC8 C Compiler User’s Guide 4.8. DS52053B-page 108  2012 Microchip Technology Inc. Table 4-13 lists the available optimization types. By contrast. the space and asm optimizations are enabled (see below). the space optimization is enabled.8. If all optimizations are requested. an optimization that is enabled by default. the asm control allows for optimization of assembly code that was derived from C code. If speed and space suboptions are both specified. If this option is not specified. Enabling the debug suboption may restrict some optimizations that would otherwise normally take place and which would affect debugging.42 --OPT: Invoke Compiler Optimizations The --OPT option allows control of all the compiler optimizers. or it is specified as --OPT=all. for example: --OPT=asm will only enable some assembler optimizations.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4.8.10 “-O: Specify Output File” for more information.41 “--OBJDIR: Specify a Directory For Intermediate Files” and Section 4. Space optimizations are the default. Optimizations may be disabled by using --OPT=none. The speed and space suboptions are contradictory. If this option is omitted. which is performed by the assembler. . which are otherwise not optimized by the compiler. or individual optimizers may be controlled.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.8. TABLE 4-13: asm asmfile debug speed space all none OPTIMIZATION OPTIONS Function Select optimizations of assembly code derived from C source (default) Select optimizations of assembly source files Favor accurate debugging over optimization Favor optimizations that result in faster code Favor optimizations that result in smaller code (default) Enable all compiler optimizations Do not use any compiler optimizations Option name Note that different suboptions control assembler optimizations of assembly source files and intermediate assembly files produced from C source code. See Section 4. and other optimizations at the code generation stage. then speed optimizations takes precedence. Some compiler optimizations may affect the ability to debug code.43 --OUTDIR: Specify a Directory For Output Files This option allows a directory to be nominated for xc8 to locate its output files. The asmfile selection optimizes assembly source files. 4. output files will be created in the current working directory.

c lcd_data.44 --OUTPUT= type: Specify Output File Type This option allows the type of the output file(s) to be specified. Hence specifying an output file format list containing. if required. but only after the code generator has scanned the project for printf() usage. More than one output format may be specified by supplying a comma-separated list of tags.8. If you wish to see the preprocessed source for the printf() family of functions. the output file’s name will be the same as the project name (see Section 4. the code generator will not execute and no printf() code will be processed. TABLE 4-14: lib lpp intel tek aahex mot bin mcof OUTPUT FILE FORMATS File format Object library file P-code library file Intel HEX (default) Tektronic American Automation symbolic HEX file Motorola S19 HEX file Binary file Microchip COFF (default) Type tag So. then stop compilation. for example: lib or all will prevent the other formats from being created. Thus. DS52053B-page 109 .) 4. however the compiler is able to generate library files in one step.45 --PASS1: Compile to P-code The --PASS1 option is used to generate p-code intermediate files (.44 “--OUTPUT= type: Specify Output File Type” for specifying a library output file type. If this option is omitted. Such files need to be generated if creating p-code library files. This may be useful to ensure that preprocessor macros have expanded to what you think they should. This is useful when sending files to a colleague or to obtain technical support without having to send all the header files.  2012 Microchip Technology Inc.pre.c files that can be passed to the compiler for subsequent processing.c lcd_msgs. The source for this function is customized by the compiler.8.XC8 Command-line Driver 4.46 --PRE: Produce Preprocessed Source Code The --PRE option is used to generate preprocessed C source files (also called modules or translation units) with an extension . do not use this option. as the –-PRE option stops compilation after the preprocessor stage.8.3 “The Compilation Sequence”). Not all formats are supported by Microchip development tools.8.c will compile the three names files into an LPP (p-code) library. Those output file types which specify library formats stop the compilation process before the final stages of compilation are executed. If no --OUTPUT option is specified. 4. See Section 4. the preprocessed source for printf() will be automatically retained in the file doprnt. The available output file format are shown in Table 4-14.p1 file) from the parser. for example: xc8 --CHIP=16F877AA --OUTPUT=lpp lcd_init.pre.pre files are renamed to . If the . which may reside in many directories. Use of this option can also create C source files which do not require any separate header files.

47 --PROTO: Generate Prototypes The --PROTO option is used to generate .include these in a header file */ #if PROTOTYPES extern int add(int *.pro containing the following declarations which may then be edited as necessary: /* Prototypes from test.pro file produced will have the same base name as the corresponding source file. } void printlist(int * list.h> add(arg1.pro files may also contain static declarations for functions which are local to a source file. extern void printlist(int *. These static declarations should be edited into the start of the source file.c xc8 will produce test. extern void printlist(). putchar(’\n’).pro file should be edited into a global header file. int count) { while (count--) printf("d " *list++). The extern declarations from each . The . To demonstrate the operation of the --PROTO option.c: #include <stdio.8. { return *arg1 + *arg2. #else /* PROTOTYPES */ extern int add(). enter the following source code as file test. int * arg2.c */ /* extern functions . int). #endif /* PROTOTYPES */ DS52053B-page 110  2012 Microchip Technology Inc. } If compiled with the command: xc8 --CHIP=16F877AA --PROTO test. int *). Prototype files contain both ANSI C-style prototypes and old-style C function declarations within conditional compilation blocks.MPLAB® XC8 C Compiler User’s Guide 4. which can then be included into all the C source files in the project. Each .pro files containing both ANSI C and K&R style function declarations for all functions within the specified source files. . arg2) int * arg1.

use: --RAM=0-ff This option may also be used to reserve memory ranges already defined as on-chip memory in the chipinfo file. and hence any object which is in a psect is placed in this class. this option specifies the areas of memory that may be used by writable (RAM-based) objects.. See Section 4. -.XC8 Command-line Driver 4. see Section 5. supply a range prefixed with a minus character. Strictly speaking. which is specified for the target device. The output that will be placed in the ranges specified by this option are typically variables that a program defines. The default memory will include all the on-chip RAM specified for the target PIC10/12/16 device. use the following option. DS52053B-page 111 . for example: --RAM=default.1 “Program Sections”..e. The default RAM memory for each target device is specified in the chipinfo file. --RAM=default. Any objects contained in a psect that are explicitly placed at a memory address by the linker (see Section 7. For example.  2012 Microchip Technology Inc. For example.2.48 --RAM: Adjust RAM Ranges This option is used to adjust the default RAM.+20000-20fff This option will adjust the memory ranges used by linker classes. PICC18. This option is also used to specify RAM for far objects on PIC18 devices.-100-103 will use all the defined on-chip memory. use: --RAM=default. Typically this option is used to reserve memory (reduce the amount of memory available). see Section 7.15.1 “-Aclass =low-high.+100-1ff This will add the range from 100h to 1ffh to the on-chip memory. These objects are stored in the PIC18 extended memory. are not affected by the option.2.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. Any additional memory specified with this option whose address is above the on-chip program memory is assumed to be extended memory implemented as RAM.19 “-Pspec”) i. and not necessarily those areas of memory which contain physical RAM. thus this option only needs be used if there are special memory requirements.INI (for all other 8-bit devices). To only use an external range and ignore any on-chip memory. are not placed into a memory class. to specify an additional range of memory to that already present on-chip. Specifying additional memory that is not in the target device will typically result in a successful compilation. For an introductory guide to psects.. to indicate that RAM has been implemented in the extended memory space at addresses 0x20000 to 0x20fff.8.”. To do this.INI (for PIC18 devices) or PICC.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. but may lead to code failures at runtime.. but not use the addresses in the range from 100h to 103h for allocation of RAM objects.

.. PICC18. To do this supply a range prefixed with a minus character. Note that some psects must be linked above a threshold address.49 --ROM: Adjust ROM Ranges This option is used to change the default ROM which is specified for the target device. The runtime environment encapsulates any code that is present at runtime which has not been defined by the user. See Section 4.. -. and hence any object which is in a psect placed in this class.MPLAB® XC8 C Compiler User’s Guide 4.15. This option will adjust the memory ranges used by linker classes. instead supplied by the compiler. to specify an additional range of memory to that on-chip. The default ROM memory for each target device is specified in the chipinfo file.1 “-Aclass =low-high.19 “-Pspec”). Using this option to remove the upper memory ranges may make it impossible to place these psects. To only use an external range and ignore any on-chip memory.e. The default memory will include all the on-chip ROM specified for the target PIC10/12/16 device.INI (for PIC18 devices) or PICC. but may lead to code failures at runtime. thus this option only needs to be used if there are special memory requirements. and not necessarily those areas of memory which contain physical ROM. When producing code that may be downloaded into a system via a bootloader. DS52053B-page 112  2012 Microchip Technology Inc.8. use: --ROM=100-2ff This option may also be used to reserve memory ranges already defined as on-chip memory in the chip configuration file. 4. see Section 5. For example. Typically this option is used to reserve memory (reduce the amount of memory available). All required runtime features are enabled by default and this option is not required for normal compilation. but not use the addresses in the range from 100h to 1ffh for allocation of ROM objects. this option specifies the areas of memory that may be used by read-only (ROM-based) objects.+100-2ff This will add the range from 100h to 2ffh to the on-chip memory.8.2.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. are not affected by the option.. Any objects which are contained in a psect that are explicitly placed at a memory address by the linker (see Section 7. For an introductory guide to psects. are not placed into a memory class.50 --RUNTIME: Specify Runtime Environment The --RUNTIME option is used to control what is included as part of the runtime environment. most notably some psects that hold const data. Specifying additional memory that is not in the target device will typically result in a successful compilation. the destination memory may be some sort of (volatile) RAM.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. use: --ROM=default. i. typically as library code or compiler-generated source files.1 “Program Sections”.2.INI (for all other 8-bit devices). . for example: --ROM=default. The output that will be placed in the ranges specified by this option are typically executable code and any data variables that are qualified as const. see Section 7.”. Strictly speaking.-100-1ff will use all the defined on-chip memory.

For mid-range and baseline devices. DS52053B-page 113 . Off Time-out STATUS bits at start (PIC10/12/16 only) up.4 “STATUS Register Preservation” for how this feature is used. The code present in the main program module that clears uninitialized variables.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. which is included by default. are padded out to 16 byte lengths and will align on 16 byte boundaries.1. then called via a look-up table. The usable suboptions include those shown in Table 4-15.Oscillator will be calibrated with Not value tor calibration value. plib Whether the peripheral library The peripheral library will be linked On is linked in. See 5. Uninitialized variables are cleared and will contain 0 at main(). Default State On clib On clear On Configuration bits not specified will Off be assigned a default value. On source file (startup.as) is deleted after compilation. (PIC10/12/16 devices only. The inclusion of library files into the output code by the linker. (PIC10/12/16 only) oscval: Set the internal clock oscilla.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. in to the build.) config See Section 4. Programming the device with default config bytes On (+) Implies The ROM image is copied into RAM and initialized variables will contain their initial value at main().10.  2012 Microchip Technology Inc. (PIC18 only) download Conditioning of the Intel HEX Data records in the Intel HEX file Off file for use with bootloaders. value supplied. will clobber the contents of the STATUS register. TABLE 4-15: Suboption init RUNTIME ENVIRONMENT SUBOPTIONS Controls The code present in the main program module that copies the ROM-image of initial values to RAM variables. stackcall Allow function calls to use a Functions called via CALL instrucOff table look-up method once tion while stack not exhausted. Library files are linked into the output. no_startup Whether the startup module is Startup module will not be linked Off linked in with user-defined in.XC8 Command-line Driver Note that the code that clears or initializes variables. (PIC18 only) resetbits Preserve Power-down and STATUS bits are preserved. osccal Initialize the oscillator with the Oscillator will be calibrated. then you must enable the resetbits suboption as well. the hardware stack has filled. if you need to check the cause of Reset using the TO or PD bits in this register. Startup code will not assume Reset values in certain registers. (PIC10/12/16 specified only) keep Whether the start-up module The start-up module is not deleted. code. On oscillator constant.

The dependency file lists those files on which the source file is dependant. this is not desirable as almost all applications are critical to the success of the build process. A typical task for this option might be to position a serial number in program memory. to store a one byte value. . Disabling a critical application will result in catastrophic failure. or obfuscated. This option is functionally identical to the corresponding HEXMATE option.6. Compilation will stop after the preprocessing stage if this option is used. However. See Section 4. Dependencies result when one file is #included into another.8.MPLAB® XC8 C Compiler User’s Guide 4. and which can be referenced from C code as _serial0. The general form of this option is: as follows. This option is not required for most projects. The byte-width of data to store is determined by the byte-width of the hexcode parameter in the option. remember to declare it.53 --SETOPTION: Set the Command-line Options For Application This option is used to supply alternative command line options for the named application when compiling.dep and .8. 4. To store the same value as a four byte quantity use --SERIAL=00000000@1000. C comments. at program memory address 1000h. If the file parameter is specified as off.52 --SERIAL: Store a Value At This Program Memory Address This option allows a hexadecimal code to be stored at a particular address in program memory. DS52053B-page 114  2012 Microchip Technology Inc.file where the app component specifies the application that will receive the new options. 4. and the file component specifies the name of the file that contains the additional options that will be passed to the application.d dependency files are generated. so that the original source code cannot be reconstructed from the distributed files. To enable access to this symbol. which are normally included into these files.dep file. The driver will also define a label at the location where the value was stored. it is permissible to skip a non-critical application such as CLIST or HEXMATE if the final results are not reliant on their function.15 “-SERIAL”.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.8. 4.d file format is used by GCC-based compilers and contains the same information as the .51 --SCANDEP: Scan for Dependencies When this option is used. use --SERIAL=00@1000. For more detailed information and advanced controls that can be used with this option. In most cases.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. If specifying more than one option to a component. refer to Section 8. . For example. This option can also be used to remove an application from the build sequence. execution of the named application will be skipped. as well as line numbers and variable names will be removed. 0.8. --SETOPTION=app.1. The . each option must be entered on a new line in the option file.54 --SHROUD: Obfuscate P-code Files This option should be used in situations where either p-code files or p-code libraries are to be distributed and are built from confidential source code. for example: extern const int _serial0.

A psect summary may be shown by enabling the psect suboption. This shows the total memory usage for all memory spaces. Be warned that use of this option may cause problems with some standard header files (e. these keywords are changed to include two underscore characters at the beginning of the keyword (for example. DS52053B-page 115 .56 --SUMMARY: Select Memory Summary Output Type Use this option to select the type of memory summary that is displayed after compilation. non-standard keywords.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE. If the --STRICT option is used.58 --VER: Display the Compiler’s Version Information The --VER option will display what version of the compiler is running and then exit the compiler. (default) A summary of all classes in each memory space will be shown. 4.g.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.8. A concise summary of memory used will be shown. Thus if you use this option. a memory summary is shown.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4. TABLE 4-16: psect mem class hex file MEMORY SUMMARY SUBOPTIONS Controls A summary of psect names and the addresses where they were linked will be shown. Table 4-16 shows what summary types are available.8. not persistent.8. The output printed when compiling normally corresponds to the mem setting. A summary of addresses and HEX files which make up the final output file will be shown. or if the mem suboption is selected.8. you will need to use the qualifier __persistent in your code. 4. This shows individual psects.  2012 Microchip Technology Inc. By default.h>) as they contain special keywords.. 4.55 --STRICT: Strict ANSI Conformance The --STRICT option is used to enable strict ANSI C conformance of all special. and the memory ranges they cover.XC8 Command-line Driver 4. <xc. after they have been grouped by the linker. See Section 4. __persistent) so as to strictly conform to the ANSI standard.57 --TIME: Report Time Taken For Each Phase of Build Process Adding the --TIME option when building generates a summary which shows how much time each stage of the build process took to complete. Suboption See Section 4. Summary information will be shown on screen and saved to a file. The MPLAB XC8 C compiler supports various special keywords (for example the persistent type qualifier).

MPLAB® XC8 C Compiler User’s Guide
4.8.59 --WARN: Set Warning Level
The --WARN option is used to set the compiler warning level threshold. Allowable warning levels range from -9 to 9. The warning level determines how pedantic the compiler is about dubious type conversions and constructs. Each compiler warning has a designated warning level; the higher the warning level, the more important the warning message. If the warning message’s warning level exceeds the set threshold, the warning is printed by the compiler. The default warning level threshold is 0 and will allow all normal warning messages. Use this option with care as some warning messages indicate code that is likely to fail during execution, or compromise portability. Warning message can be individually disabled with the --MSGDISABLE option, see Section 4.8.38 “--MSGDISABLE: Disable Warning Messages”. See also Section 4.6 “Compiler Messages” for full information on the compiler’s messaging system. See Section 4.9 “MPLAB IDE V8 Universal Toolsuite Equivalents” or Section 4.10 “MPLAB X Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.

4.8.60

--WARNFORMAT: Set Warning Message Format

This option sets the format of warning messages produced by the compiler. See Section 4.8.28 “--ERRFORMAT: Define Format for Compiler Messages” for more information on this option. For full information on the compiler’s messaging system, see Section 4.6 “Compiler Messages”. If you are compiling using MPLAB IDE, the format of the compiler messages is automatically configured to what the IDE expects. It recommended that you do not adjust the message formats if compiling using this IDE.

DS52053B-page 116

 2012 Microchip Technology Inc.

XC8 Command-line Driver
4.9 MPLAB IDE V8 UNIVERSAL TOOLSUITE EQUIVALENTS
When compiling from within Microchip’s MPLAB IDE, it is still the compiler’s command-line driver, xc8, that is being executed and compiling the program. The Universal Toolsuite plugin manages the MPLAB IDE Build Options dialog that is used to access the compiler options, and most of these graphical controls ultimately adjust the driver’s command-line options. You can see the command-line options being used when building in the Output window in MPLAB IDE. The following dialogs and descriptions identify the mapping between the dialog controls and command-line options. As the toolsuite is universal across all HI-TECH-branded compilers, not all options are applicable for the MPLAB XC8 C Compiler. If you are compiling with MPLAB X IDE, see Section 4.10 “MPLAB X Universal Toolsuite Equivalents”. Screen captures of the MPLAB IDE graphical user interface are presented on the pages that follow. Detailed descriptions of the tabs, options and selections are also included.

 2012 Microchip Technology Inc.

DS52053B-page 117

MPLAB® XC8 C Compiler User’s Guide
4.9.1 Directories Tab
The options in this dialog control the output and search directories for some files. See Figure 4-5 in conjunction with the following command line option equivalents. FIGURE 4-5: THE DIRECTORIES TAB

1 2

1. The output directory: This selection uses the buttons and fields grouped in the bracket to specify an output directory for files output by the compiler. This selection is handled internally by MPLAB IDE and does not use a driver option; however, it is functionally equivalent to the --OUTDIR driver option (see Section 4.8.43 “--OUTDIR: Specify a Directory For Output Files”). 2. Include Search path: This selection uses the buttons and fields grouped in the bracket to specify include (header) file search directories. See Section 4.8.5 “-I: Include Search Path”.

DS52053B-page 118

 2012 Microchip Technology Inc.

XC8 Command-line Driver
4.9.2 Compiler Tab
The options in this dialog control the aspects of compilation up to code generation. See Figure 4-6 in conjunction with the following command line option equivalents. 1. Define macros: The buttons and fields grouped in the bracket can be used to define preprocessor macros. See Section 4.8.2 “-D: Define Macro”. 2. Undefine macros: The buttons and fields grouped in the bracket can be used to undefine preprocessor macros. See Section 4.8.14 “-U: Undefine a Macro”. 3. Preprocess assembly: The checkbox controls whether assembly source files are scanned by the preprocessor. See Section 4.8.11 “-P: Preprocess Assembly Files”. FIGURE 4-6: THE COMPILER TAB

1

2

3

5 6

4

7

4. Optimization settings: These controls are used to adjust the different optimizations the compiler employs. See Section 4.8.42 “--OPT: Invoke Compiler Optimizations”. 5. Identifier length: This selector controls the maximum identifier length in C source. See Section 4.8.9 “-N: Identifier Length”.

 2012 Microchip Technology Inc.

DS52053B-page 119

MPLAB® XC8 C Compiler User’s Guide
6. Verbose: This checkbox controls whether the full command-lines for the compiler applications are displayed when building. See Section 4.8.15 “-V: Verbose Compile”. 7. Warning level: This selector allows the warning level print threshold to be set. See Section 4.8.59 “--WARN: Set Warning Level”. 8. Operation Mode: This selector allows the user to force another available operating mode (e.g., Free, Standard or PRO) other than the default. See Section 4.8.37 “--MODE: Choose Compiler Operating Mode” 9. Address Qualifier: This selector allows the user to select the behavior of the address qualifier. See Section 4.8.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”

4.9.3

Linker Tab

The options in this dialog control the link step of compilation. See Figure 4-7 in conjunction with the following command line option equivalents. FIGURE 4-7: THE LINKER TAB

2 3 4 5 6 7 1 8 9 10 11 12 13

14

15

DS52053B-page 120

 2012 Microchip Technology Inc.

XC8 Command-line Driver
1. Runtime options: These checkboxes control the many runtime features the compiler can employ. See Section 4.8.50 “--RUNTIME: Specify Runtime Environment”. 2. Fill: This field allows a fill value to be specified for unused memory locations. See Section 4.8.30 “--FILL: Fill Unused Program Memory”. 3. Codeoffset: This field allows an offset for the program to be specified. See Section 4.8.22 “--CODEOFFSET: Offset Program Code to Address”. 4. Checksum: This field allows the checksum specification to be specified. See Section 4.8.17 “--ASMLIST: Generate Assembler List Files”. 5. Errata: This field allows control over which software workarounds are employed for errata issues. See Section 4.8.27 “--ERRATA: Specify Errata Workarounds”. 6. Vectors: Not applicable. 7. Callgraph: Not applicable. 8. Debugger: This selector allows the type of hardware debugger to be chosen. See Section 4.8.23 “--DEBUGGER: Select Debugger Type”. 9. Trace type: Not yet implemented. Only native trace implemented. 10. Stack size: Not applicable. 11. Heap size: Not applicable. 12. Frequency: Not applicable. 13. Extend address 0 in HEX file: This option specifies that the intel HEX file should have initialization to zero of the upper address. See Section 4.8.44 “--OUTPUT= type: Specify Output File Type”. 14. Interrupt options: Not applicable. 15. Summary Options: These checkboxes control which summaries are printed after compilation. See Section 4.8.56 “--SUMMARY: Select Memory Summary Output Type”.

 2012 Microchip Technology Inc.

DS52053B-page 121

MPLAB® XC8 C Compiler User’s Guide
4.9.4 Global Tab
The options in this dialog control aspects of compilation that are applicable throughout code generation and link steps — the second stage of compilation. See Figure 4-8 in conjunction with the following command line option equivalents. FIGURE 4-8: THE GLOBAL TAB

1 2 3 4 5

6 7 8 9 10

11

1. Memory model: Not applicable. 2. Double float: This selector allows the size of the double type to be selected. See Section 4.8.24 “--DOUBLE: Select Kind of Double Types”. 3. Float: This selector allows the size of the float type to be selected. See Section 4.8.31 “--FLOAT: Select Kind of Float Types”. 4. Use strict calls: Not applicable. 5. RAM ranges: This field allows the default RAM (data space) memory used to be adjusted. See Section 4.8.48 “--RAM: Adjust RAM Ranges”. 6. Code pointer size: Not applicable.

DS52053B-page 122

 2012 Microchip Technology Inc.

XC8 Command-line Driver
7. External memory: This option affect the code generated when accessing the external data interface on applicable PIC18 devices. See Section 4.8.26 “--EMI: Select External Memory Interface Operating Mode”. 8. Instruction set: Not applicable. 9. Printf: Not applicable. 10. ROM ranges: This field allows the default ROM (program space) memory used to be adjusted. See Section 4.8.49 “--ROM: Adjust ROM Ranges”. 11. Additional command-line options: Use this field to add in driver options in addition to those specified by the Build Options widgets. These options will only be passed to the driver during the second compiler (code generation and link) pass, see Section 4.3.2 “Single-Step Compilation”.

 2012 Microchip Technology Inc.

DS52053B-page 123

MPLAB® XC8 C Compiler User’s Guide
4.10 MPLAB X UNIVERSAL TOOLSUITE EQUIVALENTS
When compiling under the MPLAB X IDE, it is still the compiler’s command-line driver that is being executed and compiling the program. The MPLAB XC8 compiler plugins controls the MPLAB X IDE Properties dialog that is used to access the compiler options, however these graphical controls ultimately adjust the command-line options passed to the command-line driver when compiling. You can see the command-line options being used when building in MPLAB X IDE in the Output window. The following dialogs and descriptions identify the mapping between the MPLAB X IDE dialog controls and command-line options. If you are using MPLAB IDE v8, see Section 4.9 “MPLAB IDE V8 Universal Toolsuite Equivalents”.

4.10.1

Global Category

The panel in this category, shown in Figure 4-9, controls settings which apply to the entire project. FIGURE 4-9: GLOBAL OPTIONS

1 2 3 4 5

1. Size of Double: This selector allows the size of the double type to be selected. See Section 4.8.24 “--DOUBLE: Select Kind of Double Types”. 2. Size of Float: This selector allows the size of the float type to be selected. See Section 4.8.31 “--FLOAT: Select Kind of Float Types”. 3. External memory: This option allows specification of how external memory access is performed. This only affects those devices which can access external memory. See Section 4.8.26 “--EMI: Select External Memory Interface Operating Mode”. 4. RAM ranges: This field allows the default RAM (data space) memory used to be adjusted. See Section 4.8.48 “--RAM: Adjust RAM Ranges”. 5. ROM ranges: This field allows the default ROM (program memory space) memory used to be adjusted. See Section 4.8.49 “--ROM: Adjust ROM Ranges”.

DS52053B-page 124

 2012 Microchip Technology Inc.

XC8 Command-line Driver
4.10.2 Compiler Category
The panels in this category control aspects of compilation of C source. 4.10.2.1 PREPROCESSING AND MESSAGES

These options relate to the C preprocessor and messages produced by the compiler (see Section 4.6 “Compiler Messages” for more information). See Figure 4-10 in conjunction with the following command-line option equivalents. FIGURE 4-10: PREPROCESSING AND MESSAGES OPTIONS

1 2 3 4 5 6 7 8

1. Define macros: The buttons and fields grouped in the bracket can be used to define preprocessor macros. See Section 4.8.2 “-D: Define Macro”. 2. Undefine macros: The buttons and fields grouped in the bracket can be used to undefine preprocessor macros. See Section 4.8.14 “-U: Undefine a Macro”. 3. Preprocess assembly: This checkbox controls whether assembly source files are scanned by the preprocessor. See Section 4.8.11 “-P: Preprocess Assembly Files”. 4. Identifier length: This selector is currently not implemented. See Section 4.8.9 “-N: Identifier Length”. 5. Include Directories: This selection uses the buttons and fields grouped in the bracket to specify include (header) file search directories. See Section 4.8.5 “-I: Include Search Path”. 6. Strict ANSI Conformance: This forces the compiler to reject any non-standard keywords. See Section 4.8.55 “--STRICT: Strict ANSI Conformance”. 7. Verbose: This checkbox controls whether the full command-lines for the compiler applications are displayed when building. See Section 4.8.15 “-V: Verbose Compile”. 8. Warning level: This selector allows the warning level print threshold to be set. See Section 4.8.59 “--WARN: Set Warning Level”.

 2012 Microchip Technology Inc.

DS52053B-page 125

Address Qualifier: This selector allows the user to select the behavior of the address qualifiers. speed/space and debug).8. Select an optimizations set (--OPT suboptions: all or none).2 OPTIMIZATION These options. See Section 4. shown in Figure 4-11. The operating mode will affect OCG-optimizations FIGURE 4-11: OPTIMIZATIONS OPTIONS 1 { 2 3 FIGURE 4-12: E COMPILER CATEGORY DS52053B-page 126  2012 Microchip Technology Inc.2. 3.42 “--OPT: Invoke Compiler Optimizations”. See Section 4.37 “--MODE: Choose Compiler Operating Mode”.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”. 1. std or pro) other than the default.8. . or any of the custom options below (--OPT suboptions: asm. relate to optimizations performed by the compiler.8.10. See Section 4. Optimization controls: These controls adjust the optimizations employed by the compiler. Operation Mode: This selector allows the user to force another available operating mode (free.MPLAB® XC8 C Compiler User’s Guide 4. 2. asmfile.

download. init.XC8 Command-line Driver 4. no_startup. Respectively. config. stackcall.1 RUNTIME All the widgets in Figure 4-13 correspond to suboptions of the --RUNTIME option.10. DS52053B-page 127 . 4.8. see Section 4. FIGURE 4-13: RUNTIME OPTIONS  2012 Microchip Technology Inc. keep. resetbits. osccal. clib and plib suboptions of the --RUNTIME option.10.3 Linker Category The options in this dialog control the aspects of the second stage of compilation including code generation and linking. oscval.3.50 “--RUNTIME: Specify Runtime Environment”. these map to the clear.

see Section 4. Display memory usage after compilation: These checkboxes allow you to specify what information is displayed after compilation. 2. 1.34 “--HTML: Generate HTML Diagnostic Files”.2 REPORTING These options. shown in Figure 4-14 relate to information produced during and after compilation.MPLAB® XC8 C Compiler User’s Guide 4. Create HTML files: This will create HTML files summarizing the previous build. The correspond to the psect.10. Create Summary File: Selecting this checkbox will send the information you have selected above to a file as well as to the standard output.56 “--SUMMARY: Select Memory Summary Output Type”.56 “--SUMMARY: Select Memory Summary Output Type”.8.8. This corresponds to the file suboption to the --SUMMARY option. mem and hex suboptions to the --SUMMARY option. class. see Section 4.3. 3. see Section 4. .8. FIGURE 4-14: REPORTING OPTIONS 1 { 2 3 FIGURE 4-15: ADDITIONAL OPTIONS 1 2 3 4 5 6 7 DS52053B-page 128  2012 Microchip Technology Inc.

8. Errata: This allows customization of the errata workarounds applied by the compiler.30 “--FILL: Fill Unused Program Memory”.8.XC8 Command-line Driver 4. shown in Figure 4-15 relate to miscellaneous options. see Section 4.3 ADDITIONAL These options.22 “--CODEOFFSET: Offset Program Code to Address”. see Section 4. see Section 4. DS52053B-page 129 .27 “--ERRATA: Specify Errata Workarounds”.10. see Section 4.8. 1.  2012 Microchip Technology Inc. 6.44 “--OUTPUT= type: Specify Output File Type”.8. Trace type: Not yet implemented.52 “--SERIAL: Store a Value At This Program Memory Address”.8. see Section 4. Serial: This option allows you to specify a string which can be inserted into your output HEX file.19 “--CHECKSUM: Calculate a Checksum”.8.3. Codeoffset: This field allows an offset for the program to be specified. See Section 4. Only native trace supported. 4. Fill: This field allows a fill value to be specified for unused memory locations. 5. 2. Checksum: This field allows the checksum specification to be specified. 3. Extend address 0 in HEX file: This option specifies that the intel HEX file should have initialization to zero of the upper address.

MPLAB® XC8 C Compiler User’s Guide NOTES: DS52053B-page 130  2012 Microchip Technology Inc. .

9. Runtime Startup and Reset Library Routines Mixing C and Assembly Code Optimizations Preprocessing Linking Programs 5. The compiler can make functions called from main-line and interrupt code appear to be reentrant via a duplication feature. DS52053B-page 131 .2. 5. Due to limited memory and no hardware implementation of a data stack. The exact behavior of the compiler is detailed throughout this manual. • • • • • • • • • • • • • • ANSI C Standard Issues Device-Related Features Supported Data Types and Variables Memory Allocation and Access Operators and Statements Register Usage Functions Interrupts Main.2. recursion is not supported and functions are not reentrant.2 ANSI C STANDARD ISSUES This compiler conforms to the ISO/IEC 9899:1990 Standard for programming languages. Some features from the later standard C99 are also supported. See Section 5. C Language Features 5.  2012 Microchip Technology Inc.MPLAB® XC8 C COMPILER USER’S GUIDE Chapter 5. This is commonly called the C90 Standard. 5.1 Divergence from the ANSI C Standard The C language implemented on MPLAB XC8 C Compiler diverges from the ANSI C Standard in one area: function recursion.2. Some violations to the ANSI C Standard are indicated below in Section 5.1 “Divergence from the ANSI C Standard”. This chapter documents the special language features which are specific to these devices. It is referred to as the ANSI C Standard in this manual. This means that the exact behavior of some C code can vary from compiler to compiler.5 “Function Duplication”.1 INTRODUCTION MPLAB XC8 C Compiler supports a number of special features and extensions to the C language which are designed to ease the task of producing ROM-based applications for 8-bit PIC devices.2 Implementation-Defined behavior Certain features of the ANSI C standard have implementation-defined behavior. and is fully summarized in Appendix C. “Implementation-Defined Behavior”.

DS52053B-page 132  2012 Microchip Technology Inc. A separate document (pending at the time of this writing) describes the interface. If you choose to write code which conforms to this standard. Alternatively. .18 “--CCI: Enforce and Expect CCI Conformance”) should be enabled. This will to indicate that the compiler should enforce conformance.3 Common Compiler Interface Standard This compiler conforms to the Microchip XC compiler Common Compiler Interface standard (CCI). This is a further refinement of the ANSI standard that attempts to standardize implementation-defined behavior and non-standard extensions across the entire MPLAB XC compiler family.MPLAB® XC8 C Compiler User’s Guide 5.2. you may continue to write code using the non-standard ANSI extensions provided by the compiler.8. a compiler option (see Section 4.

From MPLAB IDE (v8). open the Build Options dialog. DS52053B-page 133 . Ensure you set the configuration bits to use the PIC18 legacy instruction mode when appropriate. towards the center of the dialog. These are detailed in the following sections.8. Both these files are located in the DOCS directory under your compiler’s installation directory. The extended instruction mode available on some PIC18 devices is not currently supported.3.1 Device Support MPLAB XC8 C Compiler aims to support all 8-bit PIC devices. 5.html for a list of all supported baseline or mid-range device.html for all PIC18 devices. more detailed information my be shown about each device. There are several ways you can check if the compiler you are using supports a particular device.  2012 Microchip Technology Inc.21 “--CHIPINFO: Display List of Supported Devices”). However.2 Instruction Set Support The compiler support all instruction sets for PIC10/12/16 devices as well as the standard (legacy) PIC18 instruction set. the same information can be obtained.C Language Features 5. See Figure 5-1 for the relevant fields in this dialog. If you use the -V option in addition to the --CHIPINFO option. Open the files pic_chipinfo. select the compiler you wish to use. Select the Driver tab. A list of all devices will be printed. FIGURE 5-1: SHOWING SUPPORTED DEVICES From the command line. A list of all devices supported by that compiler will be shown in the Selected Driver Information and Supported Device area. 5.3.3 DEVICE-RELATED FEATURES MPLAB XC8 has several features which relate directly to the 8-bit PIC architectures and instruction sets. or pic18_chipinfo. In the Available Drivers field. Run the compiler you wish to use and pass it the option --CHIPINFO (See Section 4. new devices in these families are frequently released. You can also see the supported devices in your favorite web browser.

1. It is only used for function return addresses and cannot be used for program data.2 “Accessing Registers from Assembly Code”.4 Stack The 8-bit PIC devices use what is referred to in this user’s guide as a hardware stack.3. Optimizations and the use of interrupts can decrease or increase the stack depth used by a program over that determined by the compiler.12. See Section 5.and 32-bit devices allow the use of what is referred to in their respective user’s guides as a software stack.2. .and architecture-specific header files when you build your project.6 “Call Graph”. This is the typical stack arrangement employed by most computers and is ordinary data memory accessed by some sort of push and pop instructions. Avoid including chip-specific header files into your code as this will reduce portability. and a stack pointer register. otherwise. The code generator may also produce warnings if the maximum stack depth is exceeded. The header files shipped with the compiler are specific to that compiler version. which also use levels of the stack. For information about assembly include files (. see Section 5. particularly if you modify these files. This enables an alternate means of calling functions to prevent stack overflow. Inclusion of this file will allow access to SFRs via special variables.50 “--RUNTIME: Specify Runtime Environment”.h> and is a generic header file that will include other device. see Section 6. as well as macros which allow special memory access or inclusion of special instructions.1 “Compiled Stack Operation” for information on how this is achieved.6. This will indicate the stack levels at each function call and can be used as a guide to stack depth.inc). A call graph is provided by the code generator in the assembler list file. 5.8. be aware that they may not be compatible with future versions of the compiler. like CLRWDT. Nesting function calls too deeply will overflow the stack. Future compiler versions may ship with modified header files. Both of these are guides to stack usage.Microchip 16.3 Device Header Files There is one header file that is typically included into each C source file you write.2. If you copy compiler header files into your project.3. see Section 4. Legacy projects may continue to use the <htc. DS52053B-page 134  2012 Microchip Technology Inc.h> header file. You must ensure that the maximum hardware stack depth is not exceeded.MPLAB® XC8 C Compiler User’s Guide 5. The file is <xc.1 The compiler implements a compiled stack for auto variables. The compiler can be made to manage stack usage for some devices using the stackcall suboption to the --RUNTIME compiler option.3. This stack is limited in depth and cannot be manipulated directly. It is important to take into account implicitly called library functions and interrupts.5. code may fail.

C Language Features 5. Failure to correctly set these bits may result in code failure.5 Configuration Bit Access The PIC devices have several locations which contain the configuration bits or fuses. __CONFIG(FCMEN).h> __CONFIG(WDTDIS & XT & UNPROTECT). or a non-running device. watchdog timer. Open the file pic18_chipinfo.. The settings and values associated with PIC18 devices can be determined from an HTML guide. WDT. and state is a textual description of the desired state. which is located in the DOCS directory of your compiler installation. programming mode and code protection. OFF. for example: #pragma config CONFIG1L = 0x8F The upper and lower half of each register must be programmed separately. Check your device data sheet for more information. // Program config.3. (Pragmas will also be introduced for other 8-bit devices in future releases. each subsequent invocation of __CONFIG() will modify the next configuration word in sequence.g. For example. e. The configuration bits for baseline and mid-range devices can be set with the __CONFIG macro which was supported in HI-TECH C. The value field is a numerical value that can be used in preference to a descriptor.g. Click on your target device and it will show you the settings and values that are appropriate with this pragma.h> in your source file. these bits may be set using a configuration pragma. #pragma config WDT = ON #pragma config WDT = 1 #pragma config WDTPS = 0x1A // turn on watchdog timer // an alternate form of the above // specify the timer postscale value One pragma can be used to program several settings by separating each setting-value pair with a comma. word 1  2012 Microchip Technology Inc. For devices that have more than one configuration word. for example: #include <xc.. For PIC18 devices. as in the following. ensure you include <xc. e. the above could be specified with one pragma. These bits specify fundamental device operation.html. To use this macro.) The pragma has the following forms. DS52053B-page 135 .h> __CONFIG(WDTDIS & HS & UNPROTECT). WDTPS = 0x1A Rather than specify individual settings. Consider the following PIC18-only examples. #pragma config setting = state|value #pragma config register = value where setting is a configuration setting descriptor. such as the oscillator mode. the entire register may be programmed with one numerical value. #pragma config WDT=ON. Typically this might look like: #include <xc.

MPLAB® XC8 C Compiler User’s Guide
5.3.5.1 LEGACY SUPPORT FOR PIC18 DEVICES You may continue to use the PIC18 configuration macros for legacy projects. The compiler supports the __CONFIG and __PROG_CONFIG macros which allow configuration bit symbols or a configuration word value, respectively, to be specified. The __CONFIG macro used for PIC18 devices takes an additional argument being the number of the configuration word location. For example:
__CONFIG(2, BW8 & PWRTDIS & WDTPS1 & WDTEN); // specify symbols

or you can specify a literal value if your prefer:
__PROG_CONFIG(1, 0xFE57); // specify a literal constant value

You cannot use the setting symbols in the __PROG_CONFIG macro, nor can you use a literal value in the __CONFIG macro. The configuration locations do not need to be programmed in order. Use the pragma in preference to the macros for new projects. To use these macros, ensure you include <xc.h> in your source file. Symbols for the macros can be found in the .cfgmap files contained in the dat/cfgmap directory of your compiler installation. 5.3.5.2 CONFIGURATION CONSIDERATIONS

Neither the config pragma nor the __CONFIG macro produce executable code. They should both be placed outside function definitions so as not to interfere with the operation of the function’s code. MPLAB IDE v8 has a dialog (Config>Configuration bits...) which also allows configuration bits to be specified when the device is programmed. If the check box for “Configuration Bits Set in Code” in this dialog is checked, any configuration bits specified in your code using the __CONFIG macro are ignored and those in the dialog used instead. Ensure the source of the configuration bit settings is known when working with an MPLAB IDE v8 project. MPLAB X IDE does not allow the configuration bits to be adjusted. They must be specified in your source code using the pragma (or legacy macro). All the bits in the configuration words should be programmed to prevent erratic program behavior. Do not leave them in their default/unprogrammed state. Not all configuration bits have a default state of logic high; some have a logic low default state. Consult your device data sheet for more information.

DS52053B-page 136

 2012 Microchip Technology Inc.

C Language Features
5.3.6 Using SFRs From C Code
The Special Function Registers (SFRs) are registers which control aspects of the MCU operation or that of peripheral modules on the device. Most of these registers are memory mapped, which means that they appear at, and can be accessed using, specific addresses in the device’s data memory space. Individual bits within some registers control independent features. Some registers are read-only; some are write-only. See your device data sheet for more information. Memory-mapped SFRs are accessed by special C variables that are placed at the address of the register. (Variables that are placed at specific addresses are called absolute variables and are described in Section 5.5.4 “Absolute Variables”.) These variables can be accessed like any ordinary C variable so that no special syntax is required to access SFRs. The SFR variables are predefined in header files and are accessible once you have included the <xc.h> header file (see Section 5.3.3 “Device Header Files”) into your source code. Both bit variables and structures with bit-fields are defined, so you may use either of them in your source code to access bits within a register. The names given to the C variables that map over registers and bits within those registers are based on the names specified in the device data sheet. However, as there can be duplication of some bit names within registers, there may be differences in the nomenclature. The names of the structures that hold the bit-fields will typically be those of the corresponding register followed by bits. For example, the following shows code that includes the generic header file, clears PORTA as a whole, sets bit 0 of PORTA using a bit variable and sets bit 2 of PORTA using the structure/bit-field definitions.
#include <xc.h> void main(void) { PORTA = 0x00; RA0 = 1; PORTAbits.RA2 = 1; }

To confirm the names that are relevant for the device you are using, check the device-specific header file that <xc.h> will include for the definitions of each variable. These files will be located in the include directory of the compiler and will have a name that represents the device. There is a one-to-one correlation between device and header file name that will be included by <xc.h>, e.g., when compiling for a PIC16LF1826 device, <xc.h> will include the header file <pic16lf1826.h>. Remember that you do not need to include this chip-specific file into your source code; it is automatically included by <xc.h>. Care should be taken when accessing some SFRs from C code or from assembly inline with C code. Some registers are used by the compiler to hold intermediate values of calculations, and writing to these registers directly can result in code failure. The compiler does not detect when SFRs have changed as a result of C or assembly code that writes to them directly. The list of registers used by the compiler and further information can be found in Section 5.7 “Register Usage”. SFRs associated with peripherals are not used by the compiler to hold intermediate results and can be changed as you require. Always ensure that you confirm the operation of peripheral modules from the device data sheet.

 2012 Microchip Technology Inc.

DS52053B-page 137

MPLAB® XC8 C Compiler User’s Guide
5.3.6.1 SPECIAL BASELINE/MID-RANGE REGISTER ISSUES Some SFRs are not memory mapped, do not have a corresponding variable defined in the device specific header file, and cannot be directly accessed from C code. For example, the W register is not memory mapped on baseline devices. Some devices use OPTION and TRIS registers, that are only accessible via special instructions and that are also not memory mapped. See Section 5.3.9 “Baseline PIC MCU Special Instructions” on how these registers are accessed by the compiler. 5.3.6.2 SPECIAL PIC18 REGISTER ISSUES

Some of the SFRs associated with the PIC18 can be grouped to form multi-byte values, e.g., the TMRxH and TMRxL register combined form a 16-bit timer count value. Depending on the device and mode of operation, there may be hardware requirements to read these registers in certain ways, e.g., often the TMRxL register must be read before trying to read the TMRxH register to obtain a valid 16-bit result. Although it is possible to define a word-sized C variable to map over such registers, i.e., an int variable TMRx that maps over both TMRxL and TMRxH, the order in which the compiler would read the bytes of such an object will vary from expression to expression. Some expressions require that the Most Significant Byte (MSB) is read first; others start with the Least Significant Byte (LSB) first. It is recommended that the existing SFR definitions in the chip header files be used. Each byte of the SFR should be accessed directly, and in the required order, as dictated by the device data sheet. This results in a much higher degree of portability. The following code copies the two timer registers into a C unsigned variable count for subsequent use.
count = TMR0L; count += TMR0H << 8;

Macros are also provided to perform reading and writing of the more common timer registers. See the macros READTIMERx and WRITETIMERx in Appendix A. “Library Functions”. These guarantee the correct byte order is used.

DS52053B-page 138

 2012 Microchip Technology Inc.

C Language Features
5.3.7 ID Locations
The 8-bit PIC devices have locations outside the addressable memory area that can be used for storing program information, such as an ID number. For PIC18 devices, the config pragma is also used to place data into these locations by using a special register name. The pragma is used as follows.
#pragma config IDLOCx = value

where x is the number (position) of the ID location, and value is the nibble or byte which is to be positioned into that ID location. If value is larger than the maximum value allowable for each location on the target device, the value will be truncated and a warning message issued. The size of each ID location varies from device to device. See your device data sheet for more information. For example:
#pragma config IDLOC0 = 1 #pragma config IDLOC1 = 4

will attempt fill the first two ID locations with 1 and 4. One pragma can be used to program several locations by separating each register-value pair with a comma. For example, the above could also be specified as shown below.
#pragma config IDLOC0 = 1, IDLOC1 = 4

The config pragma does not produce executable code and so should ideally be placed outside function definitions. The compiler also has legacy support for the __IDLOC macro. This macro must be used for baseline and mid-range devices. The macro is used in a manner similar to:
#include <xc.h> __IDLOC(x);

where x is a list of nibbles which are positioned into the ID locations. Only the lower four bits of each ID location is programmed, so the following:
__IDLOC(15F0);

will attempt to fill ID locations with the values: 1, 5, F and 0. To use this macro, ensure you include <xc.h> in your source file. The __IDLOC macro does not produce executable code and so should ideally be placed outside function definitions. Some devices permit programming up to seven bits within each ID location. The __IDLOC() macro is not suitable for such devices and the __IDLOC7(a,b,c,d) macro should be used instead. The parameters a to d are the values to be programmed. The values can be entered in either decimal or hexadecimal format, such as:
__IDLOC7(0x7f,1,70,0x5a);

It is not appropriate to use the __IDLOC7() macro on a device that does not permit seven-bit programming of ID locations.

 2012 Microchip Technology Inc.

DS52053B-page 139

MPLAB® XC8 C Compiler User’s Guide
5.3.8 Bit Instructions
Wherever possible, the MPLAB XC8 C Compiler will attempt to use bit instructions, even on non-bit integer values. For example, when using a bitwise operator and a mask to alter a bit within an integral type, the compiler will check the mask value to determine if a bit instruction can achieve the same functionality.
unsigned int foo; foo |= 0x40;

will produce the instruction:
BSF _foo,6

To set or clear individual bits within integral type, the following macros could be used:
#define bitset(var, bitno) #define bitclr(var, bitno) ((var) |= 1UL << (bitno)) ((var) &= ~(1UL << (bitno)))

To perform the same operation on foo as above, the bitset macro could be employed as follows:
bitset(foo,6);

5.3.9

Baseline PIC MCU Special Instructions

The Baseline devices have some registers which are not in the normal SFR space and cannot be accessed using an ordinary file instruction. These are the OPTION and TRIS registers. Both registers are write-only and cannot be used in expression that read their value. They can only be accessed using special instructions which the compiler will use automatically. The definition of the variables that map to these registers make use of the control qualifier. This qualifier informs the compiler that the registers are outside of the normal address space and that a different access method is required. You should not use this qualifiers for any other registers. When you write to either of these SFR variables, the compiler will use the appropriate instruction to load the value. So, for example, to load the TRIS register, the following code:
TRIS = 0xFF;

may be encoded by the compiler as:
MOVLW 0ffh TRIS

Those PIC devices which have more than one output port may have definitions for objects: TRISA, TRISB and TRISC, depending on the exact number of ports available. This objects are used in the same manner as described above.

DS52053B-page 140

 2012 Microchip Technology Inc.

C Language Features
5.3.9.1 OSCILLATOR CALIBRATION CONSTANTS Some Baseline and Mid-range devices come with an oscillator calibration constant which is pre-programmed into the device’s program memory. This constant can be read from program memory and written to the OSCCAL register to calibrate the internal RC oscillator. On some Baseline PIC devices, the calibration constant is stored as a MOVLW instruction at the top of program memory, e.g. the PIC10F509 device. On Reset, the program counter is made to point to this instruction and it is executed first before the program counter wraps around to 0x0000, which is the effective Reset vector for the device. The default runtime startup routine (see Section 5.10.1 “Runtime Startup Code”) will automatically include code to load the OSCCAL register with the value contained in WREG after Reset on such devices. No other code is required. For other chips, such as the 12F629 device, the oscillator constant is also stored at the top of program memory, but as a RETLW instruction. The compiler’s startup code will automatically generate code to retrieve this value and do the configuration. For other chips, such as PIC12F629 device, the oscillator constant is also stored at the top of program memory, but as a RETLW instruction. The compiler’s startup code will automatically generate code to retrieve this value and perform the configuration. At runtime, the calibration value stored as a RETLW instruction may be read using the ‘function’ __osccal_val(),as a label is assigned the RETLW instruction address. A prototype for the function is provided in <xc.h>. For example:
calVal = __osccal_val();

Loading of the calibration value can be turned off via the osccal suboption to the --RUNTIME option (see Section 4.8.50 “--RUNTIME: Specify Runtime Environment”). At runtime, this calibration value may be read using the macro _READ_OSCCAL_DATA(). To be able to use this macro, make sure that <xc.h> is included into the relevant modules of your program. This macro returns the calibration constant which can then be stored into the OSCCAL register, as follows:
OSCCAL = _READ_OSCCAL_DATA();

Note:

The location which stores the calibration constant is never code protected and will be lost if you reprogram the device. Thus, if you are using a windowed or Flash device, the calibration constant must be saved from the last ROM location before it is erased. The constant must then be reprogrammed at the same location along with the new program and data. If you are using an in-circuit emulator (ICE), the location used by the calibration RETLW instruction may not be programmed. Calling the _READ_OSCCAL_DATA() macro will not work and will almost certainly not return correctly. If you wish to test code that includes this macro on an ICE, you will have to program a RETLW instruction at the appropriate location in program memory. Remember to remove this instruction when programming the actual part so you do not destroy the calibration value.

 2012 Microchip Technology Inc.

DS52053B-page 141

MPLAB® XC8 C Compiler User’s Guide
5.3.10 REAL ICE Support
The compiler supports log and trace functions (instrumented trace) when using Microchip’s REAL ICE debugger. See the REAL ICE documentation for more information on the instrumented trace features. Only native trace is currently supported by the compiler. Not all devices support instrumented trace, and the IDE you are using also needs to have instrumented trace support for your target device, as well. The log and trace macro calls need to be added by hand to your source code in MPLAB IDE. They have the following form.
__TRACE(id); __LOG(id, expression);

MPLAB IDE v8 will automatically substitute an appropriate value for id when you compile; however, you may specify these by hand if required. The trace id should be a constant in the range of 0x40 to 0x7f, and the log id is a constant in the range of 0x0 to 0x7f. Each macro should be given a unique number so that it can be properly identified. The same valid number can be used for both trace and log macros. The expression can be any integer or 32-bit floating point expression. Typically, this expression is simply a variable name so the variable’s contents are logged. Macros should be placed in the C source code at the desired locations. They will trigger information to be sent to the debugger and IDE when they are executed. Adding trace and log macros will increase the size of your code as they contribute to the program image that is downloaded to the device. Here is an example of these macros that you might add.
inpStatus = readUser(); if(inpStatus == 0) { __TRACE(id); recovery(); } __LOG(id, inpStatus);

DS52053B-page 142

 2012 Microchip Technology Inc.

C Language Features
5.4 SUPPORTED DATA TYPES AND VARIABLES
5.4.1 Identifiers

A C variable identifier (the following is also true for function identifiers) is a sequence of letters and digits, where the underscore character “_” counts as a letter. Identifiers cannot start with a digit. Although they may start with an underscore, such identifiers are reserved for the compiler’s use and should not be defined by your programs. Such is not the case for assembly domain identifiers, which often begin with an underscore, see Section 5.12.3.1 “Equivalent Assembly Symbols”. Identifiers are case sensitive, so main is different to Main. Not every character is significant in an identifier. The maximum number of significant characters can be set using an option, see Section 4.8.9 “-N: Identifier Length”. If two identifiers differ only after the maximum number of significant characters, then the compiler will consider them to be the same symbol.

5.4.2

Integer Data Types

The MPLAB XC8 compiler supports integer data types with 1, 2, 3 and 4 byte sizes as well as a single bit type. Table 5-1 shows the data types and their corresponding size and arithmetic type. The default type for each type is underlined. TABLE 5-1:
bit signed char unsigned char signed short unsigned short signed int unsigned int signed short long unsigned short long signed long unsigned long signed long long unsigned long long

INTEGER DATA TYPES
Size (bits) 1 8 8 16 16 16 16 24 24 32 32 32 32 Arithmetic Type Unsigned integer Signed integer Unsigned integer Signed integer Unsigned integer Signed integer Unsigned integer Signed integer Unsigned integer Signed integer Unsigned integer Signed integer Unsigned integer

Type

The bit and short long types are non-standard types available in this implementation. The long long types are C99 Standard types. All integer values are represented in little endian format with the Least Significant bit (LSb) at the lower address. If no signedness is specified in the type, then the type will be signed except for the char types which are always unsigned. The bit type is always unsigned and the concept of a signed bit is meaningless.

 2012 Microchip Technology Inc.

DS52053B-page 143

MPLAB® XC8 C Compiler User’s Guide
Signed values are stored as a two’s complement integer value. The range of values capable of being held by these types is summarized in Table 5-2 The symbols in this table are preprocessor macros which are available after including <limits.h> in your source code. As the size of data types are not fully specified by the ANSI Standard, these macros allow for more portable code which can check the limits of the range of values held by the type on this implementation. The macros associated with the short long type are non-standard macros available in this implementation; those associated with the long long types are defined by the C99 Standard. TABLE 5-2:
Symbol CHAR_BIT CHAR_MAX CHAR_MIN SCHAR_MAX SCHAR_MIN UCHAR_MAX SHRT_MAX SHRT_MIN USHRT_MAX INT_MAX INT_MIN UINT_MAX SHRTLONG_MAX SHRTLONG_MIN USHRTLONG_MAX LONG_MAX LONG_MIN ULONG_MAX LLONG_MAX LLONG_MIN ULLONG_MAX Bits per char Max. value of a char Min. value of a char Max. value of a signed char Min. value of a signed char Max. value of an unsigned char Max. value of a short Min. value of a short Max. value of an unsigned short Max. value of an int Min. value of a int Max. value of an unsigned int Max. value of a short long Min. value of a short long Max. value of a long Min. value of a long Max. value of an unsigned long Max. value of a long long Min. value of a long long Max. value of an unsigned long long

RANGES OF INTEGER TYPE VALUES
Meaning 8 127 -128 127 -128 255 32767 -32768 65535 32767 -32768 65535 8388607 -8388608 2147483647 -2147483648 4294967295 2147483647 -2147483648 4294967295 Value

Max. value of an unsigned short long 16777215

Macros are also available in <stdint.h> which define values associated with fixed-width types. When specifying a signed or unsigned short int, short long int, long int or long long int type, the keyword int may be omitted. Thus a variable declared as short will contain a signed short int and a variable declared as unsigned short will contain an unsigned short int. It is a common misconception that the C char types are intended purely for ASCII character manipulation. However, the C language makes no guarantee that the default character representation is even ASCII. (This implementation does use ASCII as the character representation.) The char types are the smallest of the multi-bit integer sizes, and behave in all respects like integers. The reason for the name “char” is historical and does not mean that char can only be used to represent characters. It is possible to freely mix char values with values of other types in C expressions. With the MPLAB XC8 C Compiler, the char types are used for a number of purposes – as 8-bit integers, as storage for ASCII characters, and for access to I/O locations.

DS52053B-page 144

 2012 Microchip Technology Inc.

C Language Features
5.4.2.1 BIT DATA TYPES AND VARIABLES The MPLAB XC8 C Compiler supports bit integral types which can hold the values 0 or 1. Single bit variables may be declared using the keyword bit, for example:
bit init_flag;

These variables cannot be auto or parameters to a function, but can be qualified static, allowing them to be defined locally within a function. For example:
int func(void) { static bit flame_on; // ... }

A function may return a bit object by using the bit keyword in the function’s prototype in the usual way. The 1 or 0 value will be returned in the carry flag in the STATUS register. The bit variables behave in most respects like normal unsigned char variables, but they may only contain the values 0 and 1, and therefore provide a convenient and efficient method of storing flags. Eight bit objects are packed into each byte of memory storage, so they don’t consume large amounts of internal RAM. Operations on bit objects are performed using the single bit instructions (bsf and bcf) wherever possible, thus the generated code to access bit objects is very efficient. It is not possible to declare a pointer to bit types or assign the address of a bit object to any pointer. Nor is it possible to statically initialize bit variables so they must be assigned any non-zero starting value (i.e., 1) in the code itself. Bit objects will be cleared on startup, unless the bit is qualified persistent. When assigning a larger integral type to a bit variable, only the LSb is used. For example, if the bit variable bitvar was assigned as in the following:
int data = 0x54; bit bitvar; bitvar = data;

it will be cleared by the assignment since the LSb of data is zero. This sets the bit type apart from the C99 Standard __Bool, which is a boolean type, not a 1-bit wide integer. The __Bool type is not supported on the MPLAB XC8 compiler. If you want to set a bit variable to be 0 or 1 depending on whether the larger integral type is zero (false) or non-zero (true), use the form:
bitvar = (data != 0);

The psects in which bit objects are allocated storage are declared using the bit PSECT directive flag, see Section 6.4.9.3 “PSECT”. All addresses specified for bit objects and psects will be bit addresses. Take care when comparing these addresses to byte addresses used by all other variables. If the xc8 flag --STRICT is used, the bit keyword becomes unavailable.

 2012 Microchip Technology Inc.

DS52053B-page 145

where: • Sign is the sign bit which indicates if the number is positive or negative • The exponent is 8 bits which is stored as excess 127 (i. Table 5-3 shows the data types and their corresponding size and arithmetic type. The 32-bit format is used for double values if the --DOUBLE=32 option is used and for float values if --FLOAT=32 is used.MPLAB® XC8 C Compiler User’s Guide 5. This format is described in Table 5-4. • Mantissa is the mantissa. . Floating point is implemented using either a IEEE 754 32-bit format.e. to hold values of these types. TABLE 5-3: float double long double FLOATING-POINT DATA TYPES Size (bits) 24 or 32 24 or 32 same as double Real Real Real Arithmetic Type Type For both float and double values. where the implied bit is zero. the 24-bit format is the default. The options --FLOAT=24 and --DOUBLE=24 can also be used to specify this explicitly. respectively. Floating-point types are always signed and the unsigned keyword is illegal when specifying a floating-point type. which is to the right of the radix point. or a modified (truncated) 24-bit form of this. The value of this number is (-1)sign x 2(exponent-127) x 1. TABLE 5-4: Format IEEE 754 32-bit modified IEEE 754 24-bit x x FLOATING-POINT FORMATS Sign Biased exponent xxxx xxxx xxxx xxxx Mantissa xxx xxxx xxxx xxxx xxxx xxxx xxx xxxx xxxx xxxx DS52053B-page 146  2012 Microchip Technology Inc. There is an implied bit to the left of the radix point which is always 1 except for a zero value. All floating-point values are represented in little endian format with the LSb at the lower address.and 32-bit floating-point types.4.3 Floating-Point Data Types The MPLAB XC8 compiler supports 24. an exponent of 0 is stored as 127). A zero value is indicated by a zero exponent. Types declared as long double will use the same format as types declared as double.. Variables may be declared using the float and double keywords. mantissa.

TABLE 5-5: Format 32-bit FLOATING-POINT FORMAT EXAMPLE IEEE 754 Number Biased exponent 11111011b (251) 1. It is important to remember that not every floating-point value can be represented by a finite sized floating-point number. for example.C Language Features Here are some examples of the IEEE 754 32-bit formats shown in Table 5-5. but the values that can be exactly represented by this format are more widely spaced. This implies that C code which compares floating-point type may not behave as expected.0) PORTA++.142395019531) Decimal 2.. which has a higher precision. It also can exactly store 95000.h> in your source code.  2012 Microchip Technology Inc. the bit to the left of the radix point) is the implied bit. The floating-point number is then given by: -1021241. The size of the exponent in the number dictates the range of values that the number can hold.0 and it is impossible to represent any value in between these two in such a type as it will be rounded. Note that the Most Significant Bit (MSb) of the mantissa column (i.e. Take the binary number to the right of the decimal point in the mantissa.302447676659. However.0100110101101101 0011011b (1.77000e+37 — 36.302447676659) 1. the next highest number it can represent is 95002. it can exactly store the value 95000. if you are using a 24-bit wide floating-point type. The next highest value which can be represented is (approximately) 95000.557 — 7DA6B69Bh 24-bit 42123Ah 10000100b (132) Use the following process to manually calculate the 32-bit example in Table 5-5. if(myFloat == 95001. The sign bit is zero. For example: volatile float myFloat. DS52053B-page 147 .00781. and the size of the mantissa relates to the spacing of each value that can be represented exactly.302447676659 which becomes: 12. which is assumed to be 1 unless the exponent is zero (in which case the float is zero). Thus the 24-bit format allows for values with approximately the same range of values representable by the 32-bit format.77000e+37 Binary floating-point values are sometimes misunderstood.0. so the exponent is 251-127=124. Convert this to decimal and divide it by 223 where 23 is the number of bits taken up by the mantissa.0 as a value.001001000111010b (1. The characteristics of the floating-point formats are summarized in Table 5-6.126764793256e+371. Compare this to a 32-bit floating-point type. Add 1 to this fraction. The symbols in this table are preprocessor macros which are available after including <float. to give 0.302447676659 which is approximately equal to: 2. // value will be rounded // this line will be executed! in which the result of the if() expression will be true.0.mantissa 1. So. myFloat = 95002. even though it appears the two values being compared are different. the biased exponent is 251.

n such that FLT_RADIXn-1 is -125 a normalized float value -37 128 38 24-bit Value 2 0 -125 -37 128 38 24 1.0 3. these macros allow for more portable code which can check the limits of the range of values held by the type on this implementation. FLT_MAX represents the maximum floating-point value of the float type. . n such that 10n is a normalized float value XXX_MANT_DIG XXX_EPSILON Number of FLT_RADIX mantissa 16 digits The smallest number which added to 1. n such that 10n is a normalized float value XXX_MAX_EXP Max. n such that FLT_RADIXn-1 is a normalized float value XXX_MAX_10_EXP Max.0 does not yield 1.MPLAB® XC8 C Compiler User’s Guide Two sets of macros are available for float and double types. So.05176e-05 DS52053B-page 148  2012 Microchip Technology Inc. As the size and format of floating-point data types are not fully specified by the ANSI Standard. respectively. DBL_MAX represents the same values for the double type. TABLE 5-6: Symbol XXX_RADIX XXX_ROUNDS XXX_MIN_EXP RANGES OF FLOATING-POINT TYPE VALUES Meaning Radix of exponent representation 2 Rounding mode for addition 0 Min. It can have two values depending on whether float is a 24 or 32 bit wide format.19209e-07 32-bit Value XXX_MIN_10_EXP Min. for example. where XXX represents FLT and DBL.

all of its members will inherit this qualification. int * const ptr. DS52053B-page 149 .1 STRUCTURE AND UNION QUALIFIERS The compiler supports the use of type qualifiers on structures. The members of structures and unions may not be objects of type bit. Pointers to structures and unions are fully supported. In the following example the structure is qualified const.4 Structures and Unions MPLAB XC8 C Compiler supports struct and union types. } record = { 0x55.4. Structures and unions may be passed freely as function arguments and function return values. When a qualifier is applied to a structure. struct { const int number. Structures and unions only differ in the memory offset applied to each member. but each member would be read-only. the entire structure will be placed into the program space and each member will be read-only.4. const struct { int number.C Language Features 5. int *ptr. Compare the following structure with the above. Remember that all members are usually initialized if a structure is const as they cannot be initialized at runtime. but bit-fields are fully supported. &i }. In this case. } record = { 0x55. 5. These types will be at least 1 byte wide.4.  2012 Microchip Technology Inc. If the members of the structure were individually qualified const. then the structure would be positioned into RAM. &i }. but the structure was not.

For example. hi will be bit 7 of address 10H. if dummy is never referenced. lo : 1. even though it is usual to use the type unsigned int in the definition. Bit-fields are always allocated within 8-bit words. The LSb of dummy will be bit 1 of address 10H and the MSb of dummy will be bit 6 of address 10h. the structure above could have been declared as: struct { unsigned unsigned unsigned } foo. Unnamed bit-fields may be declared to pad out unused space between active bits in control registers. otherwise. A bit-field that has a size of 0 is a special case. the field lo will be bit 0 of address 10H. For example. A structure with bit-fields may be initialized by supplying a comma-separated list of initial values for each field. a new byte is allocated within the structure. it is allocated within the current 8-bit unit if it will fit.MPLAB® XC8 C Compiler User’s Guide 5. 0}. for example: struct { unsigned unsigned unsigned } foo = {1. will initialize the members lo and hi correctly. : 6. lo hi : 1. if any.4. hi : 1.4. If foo was ultimately linked at address 10H. the declaration: struct { unsigned unsigned unsigned } foo. The Standard indicates that no further bit-field is to be packed into the allocation unit in which the previous bit-field.2 BIT-FIELDS IN STRUCTURES MPLAB XC8 C Compiler fully supports bit-fields in structures. 8. : 6. hi : 1. lo : 1. 0}. . hi : 1. Structures with unnamed bit-fields may be initialized. No initial value should be supplied for the unnamed members. mid : 6. dummy : 6. : 1. For example: struct { unsigned unsigned unsigned } foo = {1. was placed. Bit-fields can never cross the boundary between 8-bit allocation units. The first bit defined will be the LSb of the word in which it will be stored. lo : 1. When a bit-field is declared. will produce a structure occupying 1 byte. DS52053B-page 150  2012 Microchip Technology Inc.

the union is not named and its members accessed as if they are part of the structure.C Language Features The MPLAB XC8 compiler supports anonymous unions. These unions can be used when placing inside structures. These are unions with no identifier and whose members can be accessed without referencing the enclosing union.} Here.. double y. Anonymous unions are not part of any C Standard and so their use limits the portability of any code.. }. For example: struct { union { int x. void main(void) { aaa.  2012 Microchip Technology Inc. // . DS52053B-page 151 .x = 99. } aaa.

The last example is of a pointer called vivp which is itself qualified volatile.4. The first is the actual pointer itself. a pointer that is a parameter to a function is assigned a new object address every time the function is called. The fields in the definitions have been highlighted with spacing: volatile int * int * volatile volatile int * volatile vip . the address the pointer contains may be externally modified. The definition of the pointer must be valid for every target address assigned. however. The type and any qualifiers to the left of the * relate to the pointer’s targets. which is treated like any ordinary C variable and has memory reserved for it. Is a “const pointer” a pointer that points to const objects. as a result. In this example. the objects that can be accessed when dereferencing the pointer are not volatile. Here are three examples of pointer definitions using the volatile qualifier. Any qualifiers to the right of the * (i. or a pointer that is const itself? You can talk about “pointers to const” and “const pointers” to help clarify the definition. the pointer itself is volatile. the target objects accessible via the pointer may be externally modified.4. next to the pointer’s name) relate to the pointer variable itself. This makes sense since it is also the * operator that dereferences a pointer.. The second example is a pointer called ivp which also contains the address of int objects.5 Pointer Types There are two basic pointer types supported by the MPLAB XC8 C Compiler: data pointers and function pointers. or targets. but such terms may not be universally understood. that is. ivp .MPLAB® XC8 C Compiler User’s Guide 5. vivp . The second is the target. The standard qualifiers const and volatile can still be used and have their usual meaning. by the program. . and possible indirectly written. however. and. or to which the pointer points. Function pointers hold the address of an executable function which can be called indirectly via the pointer. Pointers can be qualified like any other C object. Note: Care must be taken when describing pointers. To conserve memory requirements and reduce execution time. which allows you to get from the pointer variable to its current target.1 COMBINING TYPE QUALIFIERS AND POINTERS It is helpful to first review the ANSI C standard conventions for definitions of pointer types. Data pointers hold the addresses of variables which can be indirectly read. The general form of a pointer definition looks like the following: target_type_&_qualifiers * pointer’s_qualifiers pointer’s_name.e. pointers are made different sizes and formats. but care must be taken when doing so as there are two quantities associated with pointers. the size of each pointer is optimal for its intended usage in the program. for example. The pointer itself — the variable that holds the address — is not volatile. the objects that are accessed when the pointer is dereferenced are treated as being volatile. It contains the address of int objects that are qualified volatile. The MPLAB XC8 C Compiler uses sophisticated algorithms to track the assignment of addresses to all pointers. that the pointer references. The first example is a pointer called vip. Despite this. non-standard qualifiers are not required when defining pointer variables. Bear in mind that one pointer can be assigned the addresses of many objects. 5. and which also holds the address of volatile objects. In other words.5. DS52053B-page 152  2012 Microchip Technology Inc.

The C code must convey the required information to the compiler. particularly with arrays or structures. The size and format of the address held by each pointer is based on this information. initialization of pointers when they are defined. This information is specific to each pointer defined in the program. There is no mechanism by which the programmer can specify the style of pointer required (other than by the assignments to the pointer). • A 16-bit pointer capable of accessing the entire data memory space • An 8-bit pointer capable of accessing up to 256 bytes of program space data • A 16-bit pointer capable of accessing up to 64 kbytes of program space data • A 16-bit mixed target space pointer capable of accessing the entire data space memory and up to 64 kbytes of program space data For PIC18 devices: • • • • • • An 8-bit pointer capable of accessing the access bank A 16-bit pointer capable of accessing the entire data memory space An 8-bit pointer capable of accessing up to 256 bytes of program space data A 16-bit pointer capable of accessing up to 64 kbytes of program space data A 24-bit pointer capable of accessing the entire program space A 16-bit mixed target space pointer capable of accessing the entire data space memory and up to 64 kbytes of program space data • A 24-bit mixed target space pointer capable of accessing the entire data space memory and the entire program space Each data pointer will be allocated one of the available classifications after preliminary scans of the source code.. such as those indicated below. for example.  2012 Microchip Technology Inc. For baseline and mid-range devices: • An 8-bit pointer capable of accessing common memory and two consecutive banks. DS52053B-page 153 . etc. The compiler tracks the memory location of all targets.5. or structures or arrays. It must be possible to increment a pointer so it can access all the elements of an array. as well as the size of all targets to determine the size and scope of a pointer. a set of all possible targets the pointer can address is maintained. assignment of one pointer to another. This includes assignment of the addresses of objects to pointers. and when pointers are used to access basic objects. banks 0 and 1. or banks 7 and 8. and takes into account when pointers are ordinary variables and function parameters. There are several pointer classifications used with the MPLAB XC8 C Compiler.2 DATA POINTERS The MPLAB XC8 compiler monitors and records all assignments of addresses to each data pointer the program contains. e.C Language Features 5. thus two pointers with the same C type may hold addresses of different sizes and formats due to the way the pointers were used in the program. The size of a target is important as well.4. When more than one address is assigned to a pointer at different places in the code.g.

. like near and bank2. If the compiler allocates the variable i (defined in main()) to bank 0 data memory. This takes place without any modification to the source code. have no effect. code that uses j } The pointer. // allocated to bank 0 in this example // allocated to bank 2 in this example int getValue(const int * ip) { return *ip. which is described in Section 6. One positive aspect of tracking pointer targets is less of a dependence on pointer qualifiers. // .. The standard qualifiers const and volatile must still be used in pointer definitions to indicate a read-only or externally-modifiable target object. respectively. and should be avoided. j. // . are not required to indicate pointer targets. and the code used to dereference the pointer will change accordingly. now has targets that are in bank 0 and in bank 2. As the program is developed. x. which is controlled by the option described in Section 4. Consider the following mid-range device program in the early stages of development. Omitting these qualifiers will result in more portable and readable code. this is in strict accordance with the ANSI C standard. DS52053B-page 154  2012 Microchip Technology Inc. Non-standard qualifiers. another variable. The main() function now looks like: int i. it will also be noted that the pointer ip (parameter to getValue()) only points to one object that resides in bank 0 of the data memory. It consists of the following code: int i. and reduce the chance of extraneous warnings being issued by the compiler. // . int x. } void main(void) { j = getValue(&i). ip. ip.. is defined and (unknown to the programmer) is allocated space in bank 2 data memory. The generated code that dereferences ip in getValue() will be generated assuming that the address can only be to an object in bank 0.. In this case.17 “--ASMLIST: Generate Assembler List Files”.6.To be able to accommodate this situation. ip.MPLAB® XC8 C Compiler User’s Guide Information about the pointers and their targets are shown in the pointer reference graph. int getValue(const int * ip) { return *ip. code that uses j } A pointer. code that uses j j = getValue(&x).. . The pointer target type uses the qualifier const because we do not want the pointer to be used to write to any objects whose addresses are passed to the function. the pointer..8. j.5 “Pointer Reference Graph”. } void main(void) { j = getValue(&i). The const qualification serves no other purpose and does not alter the format of the pointer variable. is made an 8-bit wide data pointer. This graph is printed in the assembly list file. is a parameter to the function getValue(). the pointer is made 16 bits wide. However.

it indicates that the address is of something in program memory. the MSb of the address (i..1 Pointers to Both Memory Spaces When a pointer is assigned the address of one or more objects that have been allocated memory in the data space. DS52053B-page 155 . To extend the mid-range device example given in Section 5. are determined. int i. clear indicates an object in the data memory. bit number 21 indicates the memory space that the address references. Again. int getValue(const int * ip) { return *ip. The function getValue() is now called with the address of an object that resides in the program memory.e. code that uses j j = getValue(&type).C Language Features 5.5. the code is now developed further. If assembly code references a C pointer.5. The remainder of this address represents the full address in the indicated memory space. Note that for efficiency reasons.4. in the case of baseline or mid-range programs. for PIC18 programs. The encoding of these pointer types are as follows. the compiler will force that pointer to become a 16-bit mixed target space pointer.2 “Data Pointers”. the pointer will fall into one of the mixed target space pointers listed in Section 5. it indicates an object in the program memory. code that uses j } Again.. the targets to the pointer.2 “Data Pointers”. otherwise. // .. bit number 15) indicates the memory space that the address references.4. if it is clear. even if assignments (of a correctly formatted address) are made to the pointer in the assembly code. this takes place without any change in the definition of the pointer. and access either space accordingly..2..  2012 Microchip Technology Inc. If this bit is set.. // allocated to bank 0 in this example int x. the meaning of the memory space bit is the opposite to that for baseline and mid-range devices. j. The generated code to dereference the pointer will be such that it can determine the required memory space from the address.5. and the address will be encoded so that the target memory space can be determined at runtime. the address is of a data space memory object. ip. and also assigned the address of one or more const objects.. For the Baseline/Mid-range 16-bit mixed target space pointer. These pointer types have unrestricted access to all memory areas and will operate correctly. // allocated to bank 2 in this example const int type = 0x3456.4. it indicates that the address is of an object residing in data memory. // . or a 24-bit mixed target space pointer. and now the pointer is made of the class that can access both data and program memory. code that uses j j = getValue(&x). // . The remainder of this address represents the full address in the indicated memory space. as shown. If this bit is set. For the PIC18 16-bit mixed target space pointer. For the PIC18 24-bit mixed target space pointer. } void main(void) { j = getValue(&i). any address above the highest data space address is that of an object in the program space memory.

function pointers are always one byte in size and hold an offset into a jump table that is output by the compiler. as well as all their targets. You may be tempted to write code such as: const char * cp.5.5 “Pointer Reference Graph”) will show function pointers. which acts like a lookup table. The label to which the endless loop will jump is called fpbase. the const qualifier on the object (not the pointer) indicates the target is located in program memory space. .4. For PIC18 devices. relating to the type. If there is no C object defined at the destination address. then define or declare an object at this address which can be used for this purpose. The pointer size is purely based on the amount of program memory available on the target device. function pointers are either 16 or 24 bits wide.MPLAB® XC8 C Compiler User’s Guide 5. // the compiler will flag this as bad code There is no information in the integer constant. One notable runtime feature for baseline and mid-range devices is that a function pointer which contains NULL (the value 0) and is used to call a function indirectly will cause the code to become stuck in a loop which branches to itself. The array size and type indicates the size of the pointer target. // what resides at 0x900??? and increment the pointer over the data.4 SPECIAL POINTER TARGETS Pointers and integers are not interchangeable. size or memory location of the destination.4.6. The pointer reference graph (described in Section 6. This endless loop can be used to detect this erroneous situation. The targets will be names of functions that could possibly be called via the pointer. This is an easier process to undertake compared to that associated with data pointers as all function instructions must reside in program memory. A pointer is used to read this data. There is a very good chance of code failure if pointers are assigned integer addresses and dereferenced. Assigning an integer constant to a pointer will generate a warning to this effect. cp = &inputData. 5. However. which allows functions to be called indirectly. a checksum for 1000 memory locations starting at address 0x900 in program memory is to be generated. the compiler can determine the size of the target and the memory space.5. This jump table contains jumps to the destination functions. Is 0x123 an address in data memory or program memory? How big is the object found at address 0x123? Always take the address of a C object when assigning an address to a pointer. Typically calling a function via a NULL function would result in the code crashing or some other unexpected behavior. const char inputData[1000] @ 0x900. // cp is incremented over inputData and used to read values there In this case. As with data pointers. For example. in addition to data pointers.3 FUNCTION POINTERS The MPLAB XC8 compiler fully supports pointers to functions. cp = 0x900. a much better solution is this: const char * cp. DS52053B-page 156  2012 Microchip Technology Inc. particularly for PIC devices that have more than one memory space. 0x123. the target assigned to function pointers is tracked. For baseline and mid-range devices. These are often used to call one of several function addresses stored in a user-defined C array. For example: const char * cp = 0x123. Make sure the size of the object matches the range of the memory locations that are to be accessed by the pointer.

Take care when comparing (subtracting) pointers. If NULL is the only value assigned to a pointer. char inputData[10] @ 0x90. A NULL pointer is the one instance where a constant value can be assigned to a pointer and this is handled correctly by the compiler.C Language Features Note that the const array does not need initial values to be specified in this instance. see Section 5. for example: if(cp1 == 0x246) .1 “Const Type Qualifier” and can reside over the top of other objects at these addresses.4. DS52053B-page 157 . // take appropriate action Never compare pointers with integer constants. One exception is that the address may extend to one element past the end of an array. // take appropriate action The ANSI C standard only allows pointer comparisons when the two pointer targets are the same object. Comparisons with the macro NULL are also allowed. the following code could be used. cp = &inputData. If the pointer has to access objects in data memory. A NULL pointer is numerically equal to 0 (zero). For example: if(cp1 == cp2) . const char * cp.7. // cp is incremented over inputData and used to read values there User-defined absolute objects will not be cleared by the runtime startup code and can be placed over the top of other absolute variables. but this is a special case imposed by the ANSI C standard. you need to define a different object to act as a dummy target. For example.  2012 Microchip Technology Inc. if the checksum was to be calculated over 10 bytes starting at address 0x90 in data memory. Comparisons of pointers to integer constants are even more risky. the pointer will be made as small as possible.

where U is the suffix. long int or long long int. if the suffix l is specified and the value is a decimal constant. it will assigned long long int. and l or L ll or LL u or U. Constants specified in octal or hexadecimal may also be assigned a type of unsigned int. as are the letters used to specify the hexadecimal digits. TABLE 5-7: binary octal decimal hexadecimal RADIX FORMATS Format 0b number or 0B number 0 number number 0x number or 0X number 0763 129 0x2F Example 0b10011010 Radix Any integral constant will have a type of int. otherwise. Table 5-8 shows the possible combination of suffixes and the types that are considered when assigning a type.6. 5. for example. and ll or LL unsigned long int unsigned long long int long long int unsigned long long int DS52053B-page 158  2012 Microchip Technology Inc. as well as ones which enables binary constants to be specified in C code. For example 123 is a constant. If the constant was specified as an octal or hexadecimal constant. MPLAB XC8 supports the ANSI standard radix specifiers. the actual value can be specified in one of several formats.MPLAB® XC8 C Compiler User’s Guide 5. In addition to a constant’s type.g. So. a constant must have a C type. The formats used to specify the radices are given in Table 5-7. so that the type can hold the value without overflow. The default types of constants may be changed by the addition of a suffix after the digits.4.4. 23U. e. The letters used to specify binary or hexadecimal radices are case insensitive. then unsigned types are also considered.. .6 Constant Types and Formats A constant is used to represent an immediate value in the source code. the compiler will assign the type long int. if that type will hold the constant. as opposed to a variable that could hold the same value. unsigned long int or unsigned long long int if the signed counterparts are too small to hold the value. TABLE 5-8: Suffix u or U SUFFIXES AND ASSIGNED TYPES Decimal unsigned int unsigned long int unsigned long long int long int long long int Octal or Hexadecimal unsigned int unsigned long int unsigned long long int long int unsigned long int long long int unsigned long long int unsigned long int unsigned long long int long long int unsigned long long int unsigned long long int l or L u or U. Like any value.1 INTEGRAL CONSTANTS The format of integral constants specifies their radix.

result = 1 << shifter. // code that uses result } The constant 1 (one) will be assigned an int type. DS52053B-page 159 .C Language Features Here is an example of code that may fail because the default type assigned to a constant is not appropriate: unsigned long int result. hence ensure the shift result has an unsigned long type. hence the result of the shift operation will be an int. The suffixes l or L specify a long double type which is considered an identical type to double by MPLAB XC8. in which case it is a float constant. unsigned char shifter.  2012 Microchip Technology Inc. 5. not 0x100000. The following uses a suffix to change the type of the constant. void main(void) { shifter = 20. the value 1 shifted left 20 bits will yield the result 0. regardless of how much the constant is shifted.4. In this case. result = 1UL << shifter. Even though this result is assigned to the long variable. result.6. it can never become larger than the size of an int.2 FLOATING-POINT CONSTANT Floating-point constants have double type unless suffixed by f or F.

or string literals. Thus: const char * cp = "hello" "world". "hello". DS52053B-page 160  2012 Microchip Technology Inc. For example: char ca[]= "hello world\n". for example ’a’. Two adjacent string constants (i. Instead. 6) == 0) fred = 0.. as in the previous examples.e. they need to be escaped using the backslash character. The MPLAB XC8 compiler will use the same storage location and label for strings that have identical character sequences. "world") == 0) fred--. const char * cp = "hello world\n". hence the warning. The type of string constants is const char * and the character that make up the string are stored in the program memory. .4. as in the following example: const char name[] = "Bj\370rk". rather than assign the address of the characters to a pointer. To comply with the ANSI C standard..4. two strings separated only by white space) are concatenated by the compiler. for example “hello world”. not a pointer) with a string is an exception. To prevent yourself from trying to overwrite the string. "hello world") == 0) fred++. are enclosed by double quote characters “. ’. the compiler does not support the extended character set in characters or character arrays. the characters in the string “world” and the last 6 characters of the string “hello world” (the last character is the nul terminator character) would be represented by the same characters in memory. Defining and initializing an array (i. See also Section 5. qualifier the pointer target as follows. printf("%s's Resum\351". as are all objects qualified const. \\ prints "Bjørk's Resumé" Multi-byte character constants are not supported by this implementation. The string characters cannot be modified. name). will actually copy the string characters into the RAM array.e. if(strcmp(scp. The string “hello” would not overlap with the same characters in the string “hello world” as they differ in terms of the placement of the nul character. A character constant has int type. if(strcmp(scp. for example: char * cp = "hello world\n". except where the strings are used to initialize an array residing in the data space. but the array is both readable and writable. will assign the pointer with the address of the string “hello world “.5.6. although this may be later optimized to a char type by the compiler.3 CHARACTER AND STRING CONSTANTS Character constants are enclosed by single quote characters. in the code snippet if(strncmp(scp. but this type of pointer allows writes to take place.1 “Combining Type Qualifiers and Pointers”. String constants. The string literal remains read-only.MPLAB® XC8 C Compiler User’s Guide 5. For example. A common warning relates to assigning a string literal to a pointer that does not specify a const target.

const char checksumRange[0x100] @ 0x800. However.4. as it cannot be assigned a value at any point at runtime. and which can never be modified by the program. const int tableDef[] @ 0x100 = { 0.7. DS52053B-page 161 . Usually uninitialized const objects will be defined as absolute as in the following example.  2012 Microchip Technology Inc. The MPLAB XC8 compiler supports both ANSI C qualifiers and additional special qualifiers which are useful for embedded applications and which take advantage of the 8-bit PIC MCU architecture. then it may be removed before code is generated by the compiler. If any attempt is made to modify an object declared const.7 Standard Type Qualifiers Type qualifiers provide additional information regarding how an object may be used.7. uninitialized const objects can be defined and are useful if you need to place an object in program memory over the top of other objects at a particular location. and typically the code will be longer and slower for volatile objects. 4}. will always contain the value 3.1 CONST TYPE QUALIFIER MPLAB XC8 supports the use of the ANSI type qualifiers const and volatile. and any variables which may be modified by interrupt routines should use this qualifier as well. will define version as being an int variable that will be placed in the program memory.C Language Features 5. 2. 5. 1. or used in a way that has no effect on the program’s function. Another use of the volatile keyword is to prevent variables being removed if they are not used in the C source. failure to use this qualifier when it is required may lead to code failure. The const type qualifier is used to tell the compiler that an object is read only and will not be modified. the compiler will issue a warning or error. Objects qualified const may be absolute.4. Usually a const object must be initialized when it is declared. The @ address construct is used to place the object at the specified address in program memory as in the following example which places the object tableDef at address 0x100.4. For example: volatile static unsigned int TACTL @ 0x160.2 VOLATILE TYPE QUALIFIER The volatile type qualifier is used to tell the compiler that an object cannot be guaranteed to retain its value between successive accesses. User-defined objects declared const are placed in a special psect linked into the program space. The volatile qualifier does not guarantee that any access will be atomic. The code produced by the compiler to access volatile objects may be different to that to access ordinary variables. which is often not the case with the 8-bit PIC MCU architecture. 3. However. If a non-volatile variable is never used. Any SFR which can be modified by hardware or which drives hardware is qualified as volatile. 5. so only use this qualifier if it is necessary. will define the object checksumRange as a 0x100 byte array of characters located at address 0x800 in program memory. This prevents the optimizer from eliminating apparently redundant references to objects declared volatile because it may alter the behavior of the program to do so. For example: const int version = 3. All these devices can only access a maximum of 1 byte of data per instruction. This definition will not place any data in the HEX file.

This common memory can be used to reduce code size and execution times as the bank selection instructions that are normally required to access data in banked memory are not required when accessing the common memory. This is useful for some peripheral registers that require reading to reset the state of interrupt flags. } /* must be static */ If the xc8 option. you should write: void test(void) { static persistent int intvar.. if it is present at all. The near type qualifier can be used to place non-auto variables in common memory. 5. any persistent variables will be stored in a different area of memory to other variables. 5. For example the entire statement: PORTB. DS52053B-page 162  2012 Microchip Technology Inc. See Section 5. See 5. This type qualifier may not be used on variables of class auto. In addition. Different psects are used to hold these objects.12. .8 Special Type Qualifiers The MPLAB XC8 C Compiler supports special type qualifiers to allow the user to control placement of static and extern class variables into particular address spaces. will produce assembly code the reads PORTB.4. however. // . for example if C variables are accessed in hand-written assembly code that assumes that they are located in this memory. The persistent type qualifier is used to qualify variables that should not be cleared by the runtime startup code. Mid-range and baseline devices have very small amounts of this memory. statically defined local variables may be qualified persistent. Normally such a statement is not encoded as it has no effect.4. Some variables are treated as being volatile even though they may not be qualified in the source code.4. The compiler automatically uses the common memory for frequently accessed user-defined variables so this qualifier would only be needed for special memory placement of objects. there are occasions where it is desired for some data to be preserved across a Reset.. However. This is consistent with the definition of the C language.15. See your device data sheet for more information. --STRICT is used. any C variables that are not explicitly initialized are cleared on startup.2 “Compiler-Generated Psects” for more information. For example.8. PIC18 devices refer to this memory as the access bank memory.MPLAB® XC8 C Compiler User’s Guide A C statement that consists only of a volatile variable’s name will produce code that reads the variable’s memory location and discards the result. this type qualifier is changed to __persistent.8. PIC18 devices have substantially more common memory. but the amount differs between devices.3.4 “Undefined Symbols” if you have assembly code in your project. 5.2 NEAR TYPE QUALIFIER Some of the 8-bit PIC architectures implement data memory which can be always accessed regardless of the currently selected bank. but does nothing with this value.1 PERSISTENT TYPE QUALIFIER By default.

see Section 4. Note that the compiler may store some temporary objects in the common memory. thus. Access of far variables are less efficient than that of internal variables and will result in larger. which determines its effect. 5. On supported devices. bank2 and bank3 type qualifiers are recognized by the compiler and allow some degree of control of the placement of objects in the device’s data memory banks. so these qualifiers are not normally needed.8. Based on this option’s settings.  2012 Microchip Technology Inc. Qualifiers which are ignored will not produce an error or warning. DS52053B-page 163 . as in: void myFunc(void) { static near unsigned char local_fred. If the xc8 option. this qualifier may be binding or ignored (which is the default operation). Objects qualified near cannot be auto or parameters to a function. This qualifier is controlled by the compiler option --ADDRQUAL.8.4. but will have no effect. Qualifiers which are ignored will not produce an error or warning. these qualifiers are only accepted for portability and have no effect on variable placement. which determines its effect on PIC18 devices. slower code. The compiler assumes that variables will be located in RAM which is implemented in this memory space. as in: void myFunc(void) { static far unsigned char local_far.4 BANK0.3 FAR TYPE QUALIFIER The far type qualifier is used to place non-auto variables into the program memory space for those PIC18 devices which can support external memory. BANK1. BANK2 AND BANK3 TYPE QUALIFIERS The bank0. Note that not all PIC18 devices support external memory in their program memory space and. Here is an example of an unsigned int object placed into the device’s external program memory space: far unsigned int farvar. this type qualifier is changed to __near. Section 4.C Language Features This qualifier is controlled by the compiler option --ADDRQUAL. but can be qualified static.8.8. bank1. 5. allowing them to be defined locally within a function. this qualifier may be binding or ignored (which is the default operation). For example. When compiling for PIC18 targets.48 “--RAM: Adjust RAM Ranges”. Based on this option’s settings. Objects qualified far cannot be auto or parameters to a function. so not all of this space may be available for user-defined variables.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”. It will be ignored when compiling for PIC10/12/16 targets.4. Here is an example of an unsigned char object qualified as near: near unsigned char fred.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”. this type qualifier is changed to __far. The compiler automatically allocates variables to all data banks.8. the far qualifier is not applicable to all PIC18 devices.+20000-2FFFF. --STRICT is used. the address range where the additional memory will be mapped must first be specified with the --RAM option. If the --STRICT is used. but can be qualified static. but will have no effect. allowing them to be defined locally within a function. on other devices they can be used to define C objects that are assumed to be located in certain memory banks by hand-written assembly code. to map additional data memory from 20000h to 2FFFFh use --RAM=default. see Section 4.

Objects qualified with any of these qualifiers cannot be auto or parameters to a function. which determines their effect. Check your device data sheet for more information. as in: void myFunc(void) { static bank1 unsigned char play_mode. Objects qualified with this qualifier cannot be auto or parameters to a function. --STRICT is used. allowing them to be defined locally within a function. Based on this option’s settings. as in: void myFunc(void) { static eeprom unsigned char inputData[3]. These qualifiers are controlled by the compiler option --ADDRQUAL. Qualifiers which are ignored will not produce an error or warning.5 EEPROM TYPE QUALIFIER The eeprom type qualifier is recognized by the compiler for baseline and mid-range devices only and indicates that objects should be placed in the EEPROM memory.4.8. If the --STRICT option is used. this qualifier is changed to __eeprom.8. __bank1. bank qualifiers to allow placement into these upper banks are not currently available. allowing them to be defined locally within a function. but can be qualified static. DS52053B-page 164  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide Although a few devices implement more than 4 banks of data RAM. 5.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”. __bank2 and __bank3. If the xc8 option. . The generated code to access eeprom-qualified variables will be much longer and slower than code to access RAM-based variables. Not all devices implement EEPROM memory. these qualifiers may be binding or ignored (which is the default operation). but will have no effect. but can be qualified static. these qualifiers are changed to __bank0. see Section 4.

when compiling for these devices.5. The compiler always tries to use this memory if possible. Objects defined when using PIC18 devices can also typically use the entire data memory. access to objects in this memory is typically faster and produces smaller code.3 “Size Limits of Auto Variables” and Section 5. but mid-range and baseline devices have SFRs at the lower addresses of each bank. but all objects located here will be read-only. respectively.  2012 Microchip Technology Inc. Some devices also implement EEPROM. There are several ways the different device families locate and read data from this memory. which has a separate data memory (RAM) and program memory space (often flash). Since no code is required to select a bank before accessing these locations. which are allocated to some form of stack. 5. 5. One bank is “selected” by setting one or more bits in an SFR. the maximum allowable size of objects typically increases. the general purpose memory becomes fragmented and this limits the size of most C objects.1 Address Spaces All 8-bit PIC devices have a Harvard architecture. which allows the general purpose memory to be accessed as one contiguous chunk.2. and global/static variables. which are placed in the program memory space. Due to the location of SFRs in these devices.2 Variables in Data Space Memory Most variables are ultimately positioned into the data space memory.2 “Non-Auto Variable Size Limits”. but data can also be located here. The Enhanced mid-range devices overcome this fragmentation by allowing a linear addressing mode.5 MEMORY ALLOCATION AND ACCESS There are two broad groups of RAM-based variables: auto/parameter variables. which are positioned freely throughout the data memory space at static locations. To use the C language terminology.5. This memory is called common memory. The memory allocation of these two groups is discussed separately in the following sections. Thus. these two groups of variables are those with automatic storage duration and those with permanent storage duration. Some devices only have one bank but many have more than one. and hence it is often referred to as the access bank memory. they are discussed separately. The exception is the PIC18 instruction MOVFF.) Most instructions which access a data address use only the offset into the currently selected bank to access data. Many devices have several bytes which can be accessed regardless of which bank is currently selected. Both the general purpose RAM and SFRs both share the same data space and may appear in all available memory banks. or eeprom qualified variables. which takes a full banked address and operates independently of the selected bank. Due to the fundamentally different way in which auto variables and non-auto variables are allocated memory. The data memory uses banking to increase the amount of available memory (referred to in the data sheets as the general purpose register file) without having to increase the assembly instruction width. See Section 5.2.5. The exceptions are non-auto variables which are qualified as const. The PIC18 data sheets refer to the bank in which this memory is stored as the access bank. PIC18 devices have all SFRs in the one data bank. The program memory space is primarily for executable code.C Language Features 5.5. (Consult your device data sheet for the exact operation of the device you are using.1. DS52053B-page 165 .

this will also be considered for variables. data These psects contain the RAM image of any initialized variables. NON-AUTO VARIABLE ALLOCATION 5..2 “Compiler-Generated Psects”. but it will not know the exact location within that bank.MPLAB® XC8 C Compiler User’s Guide Note: The terms “local” and “global” are commonly used to describe variables. A full list of all psect names are in Section 5. They are not cleared or otherwise modified at startup. Each variable category has a corresponding psect which is used to hold the output code which reserves memory for each variable. during compilation.1 Non-auto variables (those with permanent storage duration) are located by the compiler into any of the available data banks.8. This section also lists other variants of these psects and indicates where these psect must be linked. but it can be accessed by more than one function inside that file. This memory may be limited in size and may be reserved for special use. and “global variable” is one which has scope throughout the entire program. either.. which all relate to the value the variable should contain by the time the program begins. but are not ones defined by the language Standard. the base name of data space psects is always used in conjunction with a linker class name to indicate the RAM bank in which the psect will be positioned.2 “Compiler-Generated Psects” for more information on how initial values are assigned to the variables. so only a few variables may be allocated to it.5. so it is not local to any one function. the C language has three common scopes: block.1 “Program Sections” for an introductory guide to psects. Runtime Startup and Reset”.+20000-2FFFF. See Section “--RAM=default. which are assigned a non-zero initial value when they are defined and which must have a value copied to them by the runtime startup code.2. . if the compiler detects that the psect has become too large for the free space in a bank). variables will be located in other banks via different psects. internal linkage) and program (i. so it is not globally accessible. Qualifiers are not required to have these variables placed in banks other than bank 0 but can be used if you want to force a variable to a particular bank.e. nv These psects are used to store variables qualified persistent. The term “local variable” is often taken to mean a variable which has scope inside a function. so using only two terms to describe these can be confusing. If common memory is available on the target device. See Section 5. As described in Section 5.15.15. whose values should not be altered by the runtime startup code.” and Section 4.. The compiler considers three categories of non-auto variables. The compiler will attempt to locate all variables in one bank (i. bss These psects contain any uninitialized variables. DS52053B-page 166  2012 Microchip Technology Inc. Thus. a static variable defined outside a function has scope only in that file. For example.e. the code generator can determine which bank will hold each variable and encode the output accordingly. or variables which should be cleared by the runtime startup code. See also Section 5. place all variables in the psect destined for this bank). which are not assigned a value when they are defined.. file (i.10 “Main. The base name of each psect category is tabulated below.15. However. external linkage). but if this fills (i. This is done in a two-stage process: placing each variable into an appropriate psect and later linking that psect into a predetermined bank.e.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers” for more information on how to do this.e.

unless explicitly modified via a pointer. When compiling for enhanced mid-range PIC devices. even those defined inside a function which are “local static” variables. but unlike auto variables.1 “Equivalent Assembly Symbols”. All non-auto variables.2. When compiling for PIC18 devices.1 “Equivalent Assembly Symbols” for more information on the mapping between C. Local static variables only have scope in the function or block in which they are defined. see Section 4.1 Static Variables All static variables have permanent storage duration. Note that the special function registers (which reside in the data memory space) or memory reservations in general purpose RAM may prevent objects from being allocated contiguous memory in the one bank.4. 5. See Section 5. 5.1 “Static Variables”.12.2. In this case objects that are smaller than the size of a RAM bank may also be allocated across multi-banks. These objects can often become large in size and may affect memory allocation.1. Static variables may be accessed by other functions via pointers since they have permanent duration. Single objects that will not fit into any of the available general purpose RAM ranges will be allocated memory in several RAM banks and accessed using the device’s linear GPR (general purpose RAM). they may be preferable over initialized auto objects which are assigned a value every time the block in they are defined begins execution. discussed in Section 5.4 “Structures and Unions”. not the total amount of memory remaining.and assembly-domain symbols. the size of an object is also typically limited only by the data memory available. So too are the structure and union aggregate types. Any initialized static variables are initialized in the same way as other non-auto initialized objects by the runtime startup code. Variables which are static and which are initialized only have their initial value assigned once during the program’s execution.3.1.3. Variables which are static are guaranteed to retain their value between calls to a function. The assembly symbols used to access static objects in assembly code are discussed in Section 5.5. the size of an object (array or aggregate object) is typically limited only by the total available data memory. On baseline and other mid-range devices.2 Non-Auto Variable Size Limits Arrays of any type (including arrays of aggregate types) are fully supported by the compiler. arrays and structures are limited to the maximum size of the available GPR memory in each RAM bank. see 5. Objects can span several data banks.2. The generated code to access multi-bank objects will always be slower and the associated code size will be larger than for objects fully contained within a single RAM bank. Thus they are allocated memory like other non-auto variables.  2012 Microchip Technology Inc.2 “Startup and Initialization”. An error will result if an array is defined which is larger than this size.4.12. their memory is reserved for the entire duration of the program.C Language Features Note that the data psect used to hold initialized variables is the psect that holds the RAM variables themselves.5. Thus. There is a corresponding psect (called idata) that is placed into program memory (so it is non-volatile) and which is used to hold the initial values that are copied to the RAM variables by the runtime startup code. always use their lexical name with a leading underscore character as the assembly identifier used for this object. DS52053B-page 167 .1. except for static variables.5.

or defining absolute variables in the middle of data banks (see Section 5.1. So.2.MPLAB® XC8 C Compiler User’s Guide With any device.8.5 “Eeprom Type Qualifier”) can be used to allocate variables to the EEPROM.1 “Const Type Qualifier”). DS52053B-page 168  2012 Microchip Technology Inc. The code generate makes assumptions as to the location of these psects and if you move them to a location that breaks these assumptions. then the const specifier should be used (see Section 5.14.4 “Absolute Variables”.5. see Section 5. . they are no longer placed in a psect and do not follow the normal memory allocation procedure. See Section 5.4. Non-auto can also be placed at specific positions by using the psect pragma. This allows individual variables to be explicitly positioned in memory at an absolute address.3 Changing the Default Non-Auto Variable Allocation There are several ways in which non-auto variables can be located in locations other than those chosen by the compiler. The psects in which the different categories of non-auto variables (the nv. further restricts the contiguous memory in the data banks and may reduce the maximum size of objects you can define. typically these psects can only be moved within the data bank in which they were allocated by default.4 “Absolute Variables”).48 “--RAM: Adjust RAM Ranges”). Once variables are made absolute.2.10 “Main. For example if you wish to place variables in the program memory space.4.48 “--RAM: Adjust RAM Ranges” for information on how to do this. The decision whether variables should be positioned this way or using absolute variables should be based on the location requirements. The eeprom qualifier (see 5.8. If only a few non-auto variables are to be located at specific addresses in data space memory.7. If you wish to prevent variables from using one or more data memory locations so that these locations can be used for some other purpose. Runtime Startup and Reset” for more information on changing the default linker options for psects. bss and data psects described in Section 5. However. See Section 4.5.8 “The #pragma psect Directive”.1 “Non-Auto Variable Allocation”) can be shifted as a whole by changing the default linker options. reserving memory in general purpose RAM (see Section 4. code may fail. if such memory exists on your target device.8. you could move all the persistent variables. for example. Absolute variables are described in Section 5. Variables can be placed in other memory spaces by the use of qualifiers. their address is hard coded in generated output code. you are best reserving the memory using the memory adjust options.5. 5. then the variables can be made absolute.4.5.

12.2.2 AUTO VARIABLE ALLOCATION AND ACCESS This section discusses allocation of auto variables (those with automatic storage duration). When a compiled stack is used. Each auto object is referenced in assembly code using a special symbol defined by the code generator. in contrast to parameters which are always allocated memory based on their lexical order. The auto (short for automatic) variables are the default type of local variable. See Section 5.C Language Features 5.5. which can easily allocate then deallocate memory as required by each function. there is the possibility to reclaim memory they use when the variables are not in existence and allocate it to other variables in the program. will be allocated memory in the compiled stack in the data space memory.15. if the compiler detects that the stack psect has become too large).e. 5. This also include function parameter variables.1 Compiled Stack Operation A compiled stack consists of fixed memory areas that are usable by each function’s stack-based variables. Since they are not in existence for the entire duration of the program. The standard qualifiers: const and volatile may both be used with auto variables and these do not affect how they are positioned in memory. The compiler will try to locate the stack in one data bank.2. you must use these symbols. Typically such variables are stored on some sort of a data stack. This is done is a similar fashion to the way non-auto variables are assigned memory: a psect is used to hold the stack and this psect is placed into the available data memory by the linker. an alternative stack construct is implemented by the compiler.2 “Compiler-Generated Psects” for the limitations associated with where this psect can be linked. The auto variables defined in a function will not necessarily be allocated memory in the order declared.2. Temporary variables defined by the compiler also fall into this group. as such. and as a result.2. the stack itself is then allocated memory in the data space. The auto keyword may be used if desired.2.5. Unless explicitly declared to be static. functions are not re-entrant since stack-based variables in each function will use the same fixed area of memory every time the function is invoked. The stack mechanism employed is known as a compiled stack and is fully described in Section 5. If accessing auto variables defined in C source code. the base name is always used in conjunction with a linker class name to indicate the RAM bank in which the psect will be positioned.1 “Compiled Stack Operation”. as their name suggests. not in the program memory like with non-auto const objects.5. DS52053B-page 169 . The devices can only use their hardware stack for function return addresses and have no instructions which allow data to be placed onto this stack. All devices targeted by the compiler do not have a data stack that can be operated in this fashion. The psect base name used to hold the compiled stack is called cstack. then disappear once the function returns. a local variable will be made auto. auto variables for one function may be allocated in many RAM banks.  2012 Microchip Technology Inc. and like with non-auto variable psects. They are identical to autos except they are defined by the compiler. it can build up the stack into several components (each with their own psect) and link each in a different bank. have no C name. In fact. but if this fills (i. automatically come into existence when a function is executed.. which behave like auto variables in terms of their storage duration and scope. The auto variables. As a result. This implies that a local const-qualified object is still an auto object and. Once auto variables have been allocated a relative position in the compiled stack. which are discussed in Section 5. not the programmer.3 “Interaction Between Assembly and C Code”.

F3() and F4() are only ever called by main-line code. but the other two functions make no calls. F4 is indented one level under F1. . return 55. The term interrupt code refers to any code that is executed as a result of an interrupt being generated. DS52053B-page 170  2012 Microchip Technology Inc. The call graph for main() indicates these calls. } the function F4() will always appear in the call graph.MPLAB® XC8 C Compiler User’s Guide Fundamental to the generation of the compiled stack is the call graph. FIGURE 5-2: FORMATION OF CALL GRAPH main { F1(…). F5() and F6() are called by interrupt code. The term main-line code is often used. } Analysis of program Figure 5-2 shows sections of a program being analyzed by the code generator to form a call graph. If the exact code for function F1() looked like: int F1(void) { if(PORTA == 44) return F4(). isr(). F1() calls F4(). } F2 F3 isr F5 F6 isr { F5(…). The symbols F1. i. F2(). F2 and F3 are all indented one level under main. the call graph indicates all functions that might be called. even though it is conditionally executed in the actual source code. In the original source code. Interrupt functions which are executed when a hardware interrupt occurs. Thus. A root function is typically not called. In the diagram. which defines a tree-like hierarchy of function calls. F6(…). There will be one graph produced for each root function. F1().e it shows what functions may be called by each function. in the above figure. F2() and F3(). and refers to any code that is executed as a result of the main() function being executed. and it too has a separate graph generated. The function main() is an example of a root function that will be in every project. there is also an interrupt function. are another example. F3(…). the function main() calls F1(). F2(…). This is a static call graph which shows all possible calls. } Call graph main F1 F4 code generator F1 { F4(…). In the above figure. but which is executed via other means and contains a program entry point.

In the example shown in the figure. in fact F1() calls F4(). or base values. you can see that the APB for main() is allocated unique memory. Memory can be saved if the following point is observed: If two functions are never active at the same time. Our example also has an interrupt function. the memory taken up by the APBs for F1() and F4() are unique and do not overlap. The parameters to the function are first grouped in an order strictly determined by the lexical order in which they appear in the source code. F3() and F1() are never active at the same time. the auto objects may be placed in any order. however. which has two parameters. The function main() will always be active and so its APB can never overlap with that of another function. in the compiled stack. however. these blocks are assigned positions. then their APBs can be overlapped. Being the root of a graph. Then. and its call graph is used to assemble the APBs for any interrupt code in the same way. The APBs are formed for all functions in the program. In the compiled stack. the exact location of each object is not important at this point and we can represent this memory by one block — the APB for this function. auto and temporary variables. F2(). Each block is referred to as an auto-parameter block (APB). F2() and F3() are all placed on top of each other and the same base value in the compiled stack. Once these variables have been grouped. by analyzing the call graph. a and b. F4() and F1() are active at the same time. DS52053B-page 171 . FIGURE 5-3: FORMATION OF THE COMPILED STACK Formation of auto-parameter block (APB) for function F2 1 int a a . and one auto variable. The blocks for F1().  2012 Microchip Technology Inc. isr(). These are then followed by any auto objects.C Language Features Figure 5-3 graphically shows an example of how the compiled stack is formed. c. So we see memory for a is followed by that for b and lastly c. int int b b) { F2(int char c . isr() will always be allocated unique memory. The figure shows the APB being formed for function F2(). However. } a b c F2 2 Analysis of call graph main F1 main compiled stack 1 F1 F2 F 2 F4 4 isr F5 5 3 F4 F3 F 3 F2 F3 isr F5 F6 F6 F 6 Overlap of non-concurrently active APBs to form compiled stack Each function in the program is allocated a block of memory for its parameter. and the APBs for interrupt functions will be allocated memory following. F1() must return before F2() or F3() can be called by main().

This block can then be placed into the device’s memory by the linker. with each block being positioned in a different bank of memory. The process of building these components of the stack is the same. DS52053B-page 172  2012 Microchip Technology Inc. but are no longer auto and have fewer size limitations. This limits the size of objects within the stack to the maximum free space of the bank in which it is allocated. Runtime Startup and Reset” for more information on changing the default linker options for psects. They are allocated memory as described in Section 5. for all devices. including PIC18 and Enhanced mid-range PIC MCUs. See Section 5. but each function may have more than one APB and these will be allocated to one of the stack components based on the remaining memory in the component’s destination bank.MPLAB® XC8 C Compiler User’s Guide The end result is a block of memory which forms the compiled stack. if the stack becomes too large for this space. 5.5. See Section 5. However. Thus the total size of the stack is roughly limited only by the available memory on the device.5. code may fail. The psects in which the auto variables reside can be shifted as a whole by changing the default linker options. Such variables are still local to a function. Human readable symbols are defined by the code generator which can be used to access auto and parameter variables in the compiled stack from assembly code. The more auto variables in the stack. the more restrictive the space is to large objects.3 Size Limits of Auto Variables The compiled stack is built up as one contiguous block which can be placed into one of the available data banks. but if this fills.5. there is no means to move individual variables. consider leaving them as local objects. each allocated to a different bank).2. you can have more than one component. these psects can only be moved within the data bank in which they were allocated by default. it will consider other banks. . it is not efficient to access auto variables within the compiled stack using the linear memory of Enhanced mid-range devices. If a program requires large objects that should not be accessible to the entire program. so the maximum amount of GPR available in each bank is typically less than the bank size for these devices. Thus.2.10 “Main. but using the static specifier. nor can they be moved using the #pragma psect directive. Recall that SFRs on mid-range devices are usually present in each data bank. However. They cannot be made absolute. if required. The code generate makes assumptions as to the location of these psects and if you move them to a location that breaks these assumptions. 5. it can be assembled into several blocks.4 CHANGING THE DEFAULT AUTO VARIABLE ALLOCATION As auto variables are placed in a stack. each component of the compiled stack must fit entirely within one bank of data memory on the target device (however. the compiled stack may be built up into components. Unlike with non-auto variables.12. For devices with more than one bank of data memory. The compiler will try to allocate the compiled stack in one bank.1 “Non-Auto Variable Allocation”. each located in a different memory bank.2.3 “Interaction Between Assembly and C Code” for full information between C domain and assembly domain symbols.

Enhanced mid-range PIC devices can directly read their program memory. However. as the program cannot write to these objects at runtime.3 Variables in Program Space The only variables that are placed into program memory are those that are not auto and which have been qualified const. const char buffer[10]. // initialized const object // I just define a label The data held by non-auto const variables is placed in one of several psects. This can be read using table read instructions. Data can be stored as individual bytes in the program memory of PIC18 devices. On all devices. or label. Here are examples of const object definitions.5. const char IOtype = ’A’. For these devices. On some 8-bit PIC devices.15. The most efficient access method can be selected by the compiler when the data needs to be read. Any const-qualified (auto or non-auto) variable will always be read-only and any attempt to write to these in your source code will result in an error being issued by the compiler.2 “Compiler-Generated Psects” for the limitations associated with where these psects can be linked.C Language Features 5. See Section 5. and all components of the compiled stack will only ever be located in the data space memory. A const object is usually defined with initial values. The code associated with the access is also larger. Uninitialized const objects are often made absolute. this is not a requirement. the compiler stores data in the program memory by means of RETLW instructions which can be called.4 “Absolute Variables”. although the compiler will still usually store data as RETLW instructions. See Section 5.3 “Interaction Between Assembly and C Code” for the equivalent assembly symbols that are used to represent const-qualified variables in program memory. DS52053B-page 173 . or directly read the operand to the instruction (the LSB of the RETLW instruction). based on the target device.12. This way the compiler can either produce code that can call these instructions to obtain the program memory data as with the ordinary mid-range devices. An uninitialized const object can be defined to define a symbol. Any auto variables qualified const are placed in the compiled stack along with other auto variables. accessing data located in program memory is much slower than accessing objects in the data memory. see Section 5. and which will return a byte of data in the W register.  2012 Microchip Technology Inc. but not make a contribution to the output file. The compiler will generate the code necessary to make it appear that program memory is being read directly.5. the program space is not directly readable by the device.

the maximum size of a single const object is 255 bytes. The mid-range devices include a larger routine. you can define as many const objects as required provided the total size does not exceed the available program memory size of the device. there is also code required to be able to access const-qualified data in the program memory space. However. Once variables are made absolute.5.4 “Absolute Variables”. there are limitations in where these psects can be moved to. regardless of the amount or number of const-qualified objects. you may need additional program memory space over the size of the object itself. Runtime Startup and Reset” for more information on changing the default linker options for these psects. the maximum size of a const-qualified object is limited only by the available program memory. For baseline PIC devices. These devices also use additional code that accesses the const data. This allows individual variables to be explicitly positioned in memory at an absolute address.4 “Structures and Unions”. For all other 8-bit devices. . Note that as well as other program code. Absolute variables are described in Section 5. but this is typically small.8.1 SIZE LIMITATIONS OF CONST VARIABLES Arrays of any type (including arrays of aggregate types) can be qualified const and placed in the program memory.8 “The #pragma psect Directive”.3. you are best reserving the memory using the memory adjust options.49 “--ROM: Adjust ROM Ranges” for information on how to do this. regardless of the amount or number of const-qualified objects. 5. Variables in program memory can also be placed at specific positions by using the psect pragma.5.2 CHANGING THE DEFAULT ALLOCATION If you only intend to prevent all variables from using one or more program memory locations so that you can use those locations for some other purpose. see 5. However. then the variables can be made absolute.3. see Section 5. they are no longer placed in a psect and do not follow the normal memory allocation procedure. DS52053B-page 174  2012 Microchip Technology Inc. The decision whether variables should be positioned this way or using absolute variables should be based on the location requirements. This additional code to access the const data is only included once. The psects in which the different categories of non-auto const variables can be shifted as a whole by changing the default linker options. PIC18 devices need additional code each time an object is accessed. If only a few non-auto const variables are to be located at specific addresses in program space memory.4. but this code is also only included once. Thus. So too can structure and union aggregate types. See Section 5. their address is hard coded in generated output code. These objects can often become large in size and may affect memory allocation.4.5.14.10 “Main. See Section 4.MPLAB® XC8 C Compiler User’s Guide 5.

 2012 Microchip Technology Inc. it is clear that inputBuffer should placed at address 0x2000 in the linear address space.4. The compiler will not locate ordinary variables over the top of absolutes.C Language Features 5. then assign them a value at a suitable point in your main-line code.5. will declare a variable called Portvar located at 06h in the data memory.1 “Compiled Stack Operation”.1 ABSOLUTE VARIABLES IN DATA MEMORY Absolute variables are primarily intended for equating the address of a C identifier with a special function register. Define the absolute variables.5. DS52053B-page 175 . The compiler does not make any checks for overlap of absolute variables with other absolute variables. When compiling for an enhanced mid-range PIC device. and will use the linear GPR memory implemented on these devices. Absolute variables in RAM cannot be initialized when they are defined. Such a variables is known as an absolute variables. There is no harm in defining more than one absolute variable to live at the same address if this is what you require. The auto variables cannot be made absolute as they are located in a compiled stack. The address specified for absolute objects on these devices may either be the traditional banked memory address or the linear address. 5. For example: volatile unsigned char Portvar @ 0x06.5. but can be used to place ordinary variables at an absolute address in data memory. try to place them at either end of a memory bank or page so that the remaining free memory is not fragmented into smaller chunks. the memory allocated for some objects may be spread over multiple RAM banks. so this must be considered when choosing the variable locations. In the following example: int inputBuffer[100] @ 0x2000. it is clear which address is intended. so there is no overlap between these objects. Avoid absolute objects if at all possible. The compiler will reserve storage for this object (if the address falls into general-purpose RAM) and will equate the variable’s identifier to that address. which is address 0x20 in bank 0 RAM in the traditional banked address space. Note: Defining absolute objects can fragment memory and may make it impossible for the linker to position other objects. Such objects will only ever be accessed indirectly in assembly code. If absolute objects must be defined.4 Absolute Variables Most variables can be located at an absolute address by following its declaration with the construct @ address.2. See Section 5. where address is the location in memory where the variable is to be positioned.2. As the linear addresses start above the largest banked address. A linear address (which can be mapped back to the ordinary banked address) will be used with these objects internally by the compiler. See the device data sheet for exact details regarding your selected device.

For example: const int settings[] @ 0x200 = { 1. The EEPROM access methods are described in the following sections. For convenience. 4. 5.2 ABSOLUTE OBJECTS IN PROGRAM MEMORY Non-auto objects qualified const can also be made absolute in the same way. 6.5. The macro may be called multiple times to define the required amount of EEPROM data. 1. Using absolute variables is the easiest method. but offers all the flexibility of the linker to position the new psect into memory. the macro _EEPROMSIZE represents the number of bytes of EEPROM available on the target device. The decision whether variables should be positioned this way or using absolute variables should be based on the location requirements. . Each value should be a byte in size. 5.5 Variables in EEPROM For devices with on-chip EEPROM. #include <xc. but only allows placement at an address which must be known prior to compilation. 3.8 “The #pragma psect Directive”. see Section 5.5. The psect pragma is more complex. 5.MPLAB® XC8 C Compiler User’s Guide 5. DS52053B-page 176  2012 Microchip Technology Inc. That latter is useful when you only need to define a label in program memory without making a contribution to the output file. will place the array settings at address 0x200 in the program memory. or use block-access routines to read or write EEPROM. for example.5.14. You can. it is used for pre-loading EEPROM contents at program time only. 50.5. or that they be placed after other psects. 100 }. Variables can also be placed at specific positions by using the psect pragma. The macro has eight parameters. You can defined named variables in this memory space. This macro cannot used to write to EEPROM locations during runtime. the compiler offers several methods of accessing this memory. Both initialized and uninitialized const objects can be made absolute. The macro is used as follows. 5. specify that variables reside at a fixed address. or that the they be placed anywhere in a compiler-defined or user-defined range of address.4. It is recommended that the macro be placed outside any function definition. the __EEPROM_DATA() macro can be used to place initial values into the HEX file ready for programming.4. 10. Unused values should be specified with zero. representing eight data values. however.1 EEPROM INITIALIZATION For those devices that support external programming of their EEPROM data area. the address will indicate an address in program memory.h> __EEPROM_DATA(0. 7). 2.

The prototypes for these functions are as below. DS52053B-page 177 . _EEPROMSIZE. this macro does not wait for any concurrent EEPROM writes to complete before proceeding to select and read EEPROM. In the case of the baseline and mid-range macro EEPROM_READ().2 EEPROM ACCESS FUNCTIONS The library functions eeprom_read() and eeprom_write().h> unsigned char eeprom_read(unsigned char address). The new data written to EEPROM will become valid at a later time. For example: xc. EEPROM_READ(address) EEPROM_WRITE(address. value) The EEPROM_READ macro returns the byte read. The eeprom_write() function will initiate the process of writing to EEPROM and this process will not have completed by the time that eeprom_write() returns. These functions test and wait for any concurrent writes to EEPROM to conclude before performing the required operation. in conjunction with some of these access methods. #include <xc. with the exception of some timing issues described below. The usage of these macros for all devices is as follows.C Language Features 5.5. See your device data sheet for exact information about EEPROM on your target device. 5. If it cannot be guaranteed that all writes to EEPROM have completed at the time of calling EEPROM_READ(). and write to. but note that their repeated use will increase code size. This symbol defines the number of EEPROM bytes available for the selected chip. Use the macro forms of these routines for faster execution and to save a level of stack.5.  2012 Microchip Technology Inc. On PIC18 devices. there is another very important difference from the function version to note. The PIC18 version of these macros purely call the function equivalents. // read from EEPROM at address value = EEPROM_READ(address). void eeprom_write(unsigned char address. can be called to read from. It may also be convenient to use the preprocessor symbol. Those for other 8-bit PIC devices perform similar operations to their function counterparts. the EEPROM during program execution. these functions are derived from the peripheral library. Unlike eeprom_read().3 EEPROM ACCESS MACROS Macro version of the EEPROM functions are also provided. unsigned char value).5. the appropriate flag should be polled prior to executing EEPROM_READ().h // wait for end-of-write before EEPROM_READ while(WR) continue.5.

there is little advantage in using them. and that this memory is banked. With MPLAB XC8.MPLAB® XC8 C Compiler User’s Guide 5. can make code more efficient. code compiled for PIC18 devices also does not utilise registers other than that described below.5. See Section 5. (heap-based allocation using malloc. . and as these registers must be frequently used by generated code for other purposes.6 Variables in Registers Allocating variables to registers. etc. 5. Some arguments are passed to functions in the W register rather than in a memory location. At present. There are very few registers available for caching of variables on PIC baseline and mid-range devices. The wasteful nature of dynamic memory allocation does not suit itself to the 8-bit PIC device architectures.8 Memory Models MPLAB XC8 C Compiler does not use fixed memory models to alter allocation of variables to memory. The register keyword (which can only be used with auto variables) is silently ignored and has no effect on memory allocation of variables. there is no direct control of placement of variables in registers. This is due to the limited amount of data memory. rather than to a memory location. The cost involved in loading variables into registers would far outweigh any advantage of accessing the register.5. Memory allocation is fully automatic and there are no memory model controls. these values will typically be stored back to memory by code inside the function so that W can be used by code associated with that function.8.5.5 “Function Size Limits” for more information as to which parameter variables may use registers.7 Dynamic Memory Allocation Dynamic memory allocation. DS52053B-page 178  2012 Microchip Technology Inc. however.) is not supported on any 8-bit device. 5.

otherwise the conversion is to unsigned int. For example: if((unsigned int)(a . The following sections illustrate code operations that are often misunderstood as well as additional operations that the compiler is capable of performing. Again. the change in type can cause different code be ha vi our to what is sometimes expected.b < 10) count++.1 Integral Promotion When there is more than one operand to an operator. The conversion is to a “larger” type so there is no loss of information. The result of the subtraction with these data types is -50 (which is less than 10) and hence the body of the if() statement is executed. and the body of the if() would not be executed.C Language Features 5. “Implementation-Defined Behavior”. if(a . Consider the following example. c. Implementation-defined behavior is fully documented in Appendix C. the result is 0xFFAA and so the comparison in the above example would fail. signed or unsigned varieties of char.b) < 10) count++.b is 206 (which is not less than 10). however. The compiler may be able to issue a mismatched comparison error to this effect in some circumstances. even if both operands to an operator have the same type. If the result of the conversion can be represented by an signed int. Integral promotion is the implicit conversion of enumerated types. they typically must be of exactly the same type. If the result of the subtraction is to be an unsigned quantity. The exact results of some of these are implementation defined. short int or bit-field types to either signed int or unsigned int. Another problem that frequently occurs is with the bitwise compliment operator. Prior to these type conversions. it often assumed that ~c will produce 0xAA. The unsigned char result of a . b=50. The compiler will automatically convert the operands. the results of some expressions are not what would normally be expected. however. ~. unsigned char count. These form the standard type conversions. Consider the following code.  2012 Microchip Technology Inc. a=0. if necessary. but both a and b are converted to signed int via integral promotion before the subtraction takes place. 5. some operands are unconditionally converted to a larger type. unsigned char count.6. so they do have the same type. If c contains the value 0x55. This conversion is called integral promotion and is part of Standard C be ha vi our. The compiler performs these integral promotions where required. DS52053B-page 179 . c = 0x55.6 OPERATORS AND STATEMENTS The MPLAB XC8 C Compiler supports all the ANSI operators. If you are not aware that the type has changed. in this case. if( ~c == 0xAA) count++. then that is the destination type. a cast could be used to change this behavior. then apply a cast. and there are no options that can control or disable this operation. This operator toggles each bit within a value. The comparison is then done using unsigned int.

then integral promotion would have to be performed to comply with the ANSI C standard. A rotate left of 2 bits would be implemented with code like: c = (c << 2) | (c >> 6). In these cases. Strictly speaking. a = b + c. b. the rotate will be implemented.2 Rotation The C language does not specify a rotate operator. the compiler will not perform the integral promotion so as to increase the code efficiency. DS52053B-page 180  2012 Microchip Technology Inc. the compiler will encode the former. the final result would be the same. See Section 5. the addition performed. the type of a was unsigned int. unsigned char a. Each switch statement is assigned its strategy independently. after the unsigned int result was converted back to unsigned char. Consider this example. if c is unsigned and non-volatile. By default. the result of the addition cast to the type of a. 5. c. there are circumstances when the result of an operation is identical regardless of whether the operands are of type char or int.4. If the optimization cannot be applied. this statement requires that the values of b and c should be promoted to unsigned int. However.14. If. which also lists the available strategy types. but typically with shifts and a bitwise OR operation. it does allow shifts.4 “Switch Statement Information”. however. or this code is ported to another compiler. in the above example. 5. Even if the result of the unsigned int addition of the promoted values of b and c was different to the result of the unsigned char addition of these values without promotion. and then the assignment can take place. For the following code: c = (c << 1) | (c >> 7). the compiler will detect that the intended operation is a rotate left of 1 bit and will encode the output using the PIC MCU rotate instructions. There may be more than one strategy associated with each type. The type of strategy can be indicated by using the #pragma switch directive.10 “The #pragma switch Directive”. If an 8-bit addition is more efficient than a 16-bit addition.MPLAB® XC8 C Compiler User’s Guide The consequence of integral promotion as illustrated above is that operations are not performed with char -type operands. .6. the compiler chooses a strategy based on the case values that are used inside the switch statement.6. This code optimization will also work for integral types larger than a char. but with int -type operands. See Section 6.3 Switch Statements The compiler may encode switch statements using one of several strategies.6. The compiler will detect expressions that implement rotate operations using shift and logical operators and compile them efficiently. There is information printed in the assembly list file for each switch statement detailing the value being switched and the case values listed.

Most importantly. Writing to an SFR register using either of these two methods will not flag the register as having changed and may lead to code failure. TABLAT PRODL.h> bcf ZERO_bit . do not write using inline assembly code #endasm process(c). The following example shows a C statement and inline assembly that violates these rules and changes the ZERO bit in the STATUS register. If any of the applicable registers listed are used by interrupt code. #include <xc.C Language Features 5.3 “Context Switching”. // do not write using C code c = read(). TBLPTRU. FSR1L. or by any assembly code inline with C code.7 REGISTER USAGE The assembly generated from C source code by the compiler will use certain registers in the PIC MCU register set. Nor does it associate a variable mapped over an SFR to the actual register itself. PCLATU BSR FSR FSR0L. #asm #include <caspic. See Section 5. FSR2H TBLPTRL. the compiler assumes that nothing other than code it generates can alter the contents of these registers.h> void getInput(void) { ZERO = 0x1.  2012 Microchip Technology Inc. So if compiler-generated assembly code loads a register with a value and no subsequent code requires this register. FSR0H. either in hardware or software.9. the compiler will assume that the contents of the register are still valid later in the output sequence. The registers that are special and which are used by the compiler are listed in Table 5-9 TABLE 5-9: All 8-bit devices All 8-bit devices All mid-range devices All PIC18 devices Enhanced mid-range and PIC18 devices Non-enhanced mid-range devices Enhanced mid-range and PIC18 devices All PIC18 devices All PIC18 devices All PIC18 devices REGISTERS USED BY THE COMPILER Applicable devices W STATUS PCLATH PCLATH. TBLPTRH. PRODH Register name The state of these registers must never be changed directly by C code. } MPLAB XC8 is unable to interpret the register usage of inline assembly code that is encountered in C code. DS52053B-page 181 . FSR1H FSR2L. they will be saved and restored when an interrupt occurs.

1.13 “How Can I Tell How Big a Function Is?”). It will also reduce the hardware stack usage as no call instruction is actually executed.8. If inlining takes place. The compiler may be able to inline the body of the function specified if certain conditions are met. This is performed at the assembly code level. A warning is also issued if it is not inlined successfully.2 INLINE SPECIFIER The inline function specifier is a recommendation that calls to the specified function be as fast as possible.1. in the usual way. Inlining will only take place if the assembly optimizers are enabled.e. DS52053B-page 182  2012 Microchip Technology Inc.1 “Writing an Interrupt Service Routine”. Implementation and special features associated with functions are discussed in the following sections. You should only consider this specifier for functions which generate small amounts of assembly code. inline int combine(int x. This specifier does not change the way the function is encoded.. Note that the amount of C code in the body of a function is not a good indicator of the size of the assembly code which it generates (see Section 3. Your code should not make any assumption about whether inlining was successful and which assembly code associated with the function is being executed. Non-standard qualifiers are discussed below.3 “Interaction Between Assembly and C Code”.9. A function may not be inlined if it itself contains inline assembly.MPLAB® XC8 C Compiler User’s Guide 5.12.1 INTERRUPT SPECIFIER The interrupt specifier indicates that the function is an interrupt service routine and that it is to be encoded specially to suit this task. this may also prevent inlining of the function. } All function calls to any function that was inlined by the compiler will be encoded as if the call was replaced with the body of the called function. If the assembly for the function contains certain assembly sequences. A warning will be generated if the function references static objects. int y) { return 2*x-y.1 Function Specifiers Functions may. 5. since the call and return sequences associated with the call will be eliminated. see 5. code size may be reduced if the assembly code associated with the body of the inlined function is very small and the function itself is not output. limits the places in the source code where the function may be called. to comply with the ANSI Standard. The following is an example of a function which has been made a candidate for inlining. The equivalent symbol used in assembly code to represent the function may change it the function is static. 5.8 FUNCTIONS Functions may be written in the usual way in accordance with the C language. Functions that are static may only be directly called from code in the file in which the function is defined.8. Code size will increase if the body of the inlined function is larger than the call/return sequence it replaces and that function is called more than once. The function itself may still be encoded by the compiler even if it is inlined. use the standard specifier static. i. If inlining takes place. 5.6. this will increase the program’s execution speed.8. Interrupt functions are described in detail in 5. Any stack reduction is not reflected in the call graphs shown in the assembly list file as this file is generated before inlining takes place. . A function defined using the static specifier only affects the scope of the function.

see Section 5. On baseline and mid-range devices. If this symbol is not defined. the compiler may use a symbol to represent the memory locations used to store these values. Usually.g. or from the assembly code. The value can be determined from the map file of the external build. 5. This defines the base address of the parameter area for an extern function extReadFn to be 0x20. This memory is still sequential (addresses are contiguous across a page boundary). look for the symbol ?_funcName.C Language Features This specifier performs the same task as the #pragma inline directive.4 “The #pragma Intrinsic Directive”.14. This error can be used to verify the name being used by the compiler to encode the call. if required. For example: #asm GLOBAL ?0x200 ?0x200 EQU 0x55 #endasm Note that the return value of a function (if used) shares the same locations assigned to any parameters to that function and both use the same symbol. but in such a circumstance. If this function takes arguments or returns a value. for example calling a function at address 0x200 will require the definition of the symbol ?0x200 to be the location of the parameter/return value location for the function.8. e.8. see Section 5.6 “Function Parameters” and Section 5. For example. the corresponding symbol must be defined by your code and assigned the value of the appropriate memory location. the compiler will use the value of the constant in the symbol name. the assembly code could be contained directly in an assembly module.2 External Functions If a call to a function that is defined outside the program C source code is required (it may be part of code compiled separately.. but if the function is external and not encoded by the compiler.8. the bootloader. It can be defined in the program which makes the call via a simple EQU directive in assembler. DS52053B-page 183 .3 Allocation of Executable Code Code associated with functions is always placed in the program memory of the target device. you will need to provide a declaration of the function so that the compiler knows how to encode the call. the following snippet of code could be placed in the C source: #asm GLOBAL ?_extReadFn ?_extReadFn EQU 0x20 #endasm Alternatively. If an argument or return value is used and this will be stored in memory. 5. which compiled the function. If the function was written in C. where funcName is the name of the function.7 “Function Return Values” to determine if a register or memory locations are used in this transfer. but the paging means that any call or jump from code  2012 Microchip Technology Inc.4. the compiler will issue an undefined symbol error. the program memory is paged (compare: banking used in the data memory space). then the symbol value must be manually defined. the compiler defines this symbol when it encodes the C function. or in assembly code). It is not recommended to call the function indirectly by casting an integer to a function pointer.8.

The following example of an absolute function will place the function at address 400h: int mach_status(int mode) @ 0x400 { /* function body */ } If you check the assembly list file you will see the function label and the first assembly instruction associated with the function located at 0x400.10 “Main.. You can use either the assembly list file (see 6. A full list of all program-memory psects psect names are listed in Section 5. Such functions are called absolute functions. . This can be accomplished by using an @ address construct in a similar fashion to that used with absolute variables. textn These psects (where n is a decimal number) contain all other executable code that does not require a special link location. it may be split into a text102_split_1 and a text102_split_2 psect. text98. but you should be aware that if the code associated with a function does become larger than one page in size.4 “Map Files”) to confirm that the function was moved as you expect. The generated code associated with each function is initially placed in its own psect by the compiler.8.2.1 “Program Sections”. where n is a number. The CALL and GOTO instruction are two-word instructions and their destinations are not limited. Some optimizations and features are not applied to this psect. PIC18 devices do not implement any program memory paging.49 “--ROM: Adjust ROM Ranges” for information on how to do this. is placed in this psect. 5. psects may be merged later in the compilation process so that more than one function may contribute to a psect. maintext The generated code associated with the special function.15.MPLAB® XC8 C Compiler User’s Guide in one page to a label in another must use a longer sequence of instructions to accomplish this. main. A split psect will have a name of the form textn_split_s. See your device data sheet for more information on the program memory and instruction set. The assembly code associated with a C function can be placed at an absolute address.4 Changing the Default Function Allocation If you only intend to prevent functions from using one or more program memory locations so that you can use those locations for some other purpose. So. for example. These text psects are linked anywhere in the program memory (see 5. functions within the same psect can use a shorter form of call and jump to labels so it is advantageous to merge the code for as many functions into the same psect. if the text102 psect exceeds the size of a page. but this is not based on any paging boundaries. The relative branch instructions have a limited range. see Section 5. Runtime Startup and Reset”). e.5 “Assembly-Level Optimizations”) or the map file (see 7. you are best reserving the memory using the memory adjust options. DS52053B-page 184  2012 Microchip Technology Inc. If the size of a psect that holds the code associated with a function exceeds the size of a page. These psects have names such as textn. See Section 4. However.8. The base name of each psect category is tabulated below.1 “Program Space Psects”.g. This process is fully automatic. the efficiency of that code may drop fractionally due to any longer jump and call instruction sequences being used to transfer control to code in other pages. it may be split by the assembler optimizer. When the program memory us paged.15.

The interrupt context switch code that precedes the function code will not be relocated as it must be linked to the interrupt vector. 5.8 “The #pragma psect Directive”.3 “Allocation of Executable Code” for more details. The parameters are grouped along with the function’s auto variables in the APB and are placed in the compiled stack. A full list of all psect names are listed in Section 5. 5. which may be useful for designing applications such as bootloaders. The psect name has the form below..8.22 “--CODEOFFSET: Offset Program Code to Address” for information on how to move Reset and interrupt vector locations. or in the called function’s parameter memory in its auto-parameter block (APB).e.C Language Features If this construct is used with interrupt functions it will only affect the position of the code associated with the interrupt function body.4.14. you can specify that functions reside at a fixed address. DS52053B-page 185 .8..10 “Main. see Section 5. but only allows placement at an address which must be known prior to compilation. like structures.8. the code generated for a function is only limited only by the available program memory. See 5.8. the function that is to be called).2. The parameter variables will be referenced as an offset from the symbol ?_function. these functions may not be as efficient due to longer call sequences to jump to and call destinations in other pages. code associated with it will appear in the psect called _rv_text. the generated code associated with absolute functions is still placed in a psect. xxx_text Defines the psect for a function that has been made absolute. For example. This applies to basic types and to aggregate types. but typically an argument is the actual value that is passed to the function and a parameter is the variable defined by the function to store the argument. Runtime Startup and Reset”. See Section 5. If the first parameter is one byte in size.1 “Compiled Stack Operation” for detailed information on the compiled stack.6 Function Parameters MPLAB XC8 uses a fixed convention to pass arguments to a function. All other parameters are passed in the APB. it is passed in the W register. but offers all the flexibility of the linker to position the new psect into memory. where function is the name of the function in which the parameter is defined (i.2. i. placed at an address. xxx will be the assembly symbol associated with the function. See also Section4. but the psect is dedicated to that function only. Functions can also be placed at specific positions by using the psect pragma. The psect pragma is more complex.5. however. The method used to pass the arguments depends on the size and number of arguments involved.5 Function Size Limits For all devices. The compiler will either pass arguments in the W register. Unlike absolute variables. or that the they be placed anywhere in a compiler-defined or user-defined range of addresses. Using absolute functions is the easiest method. For example if the function rv() is made absolute.e. Functions may become larger than one page in size on paged devices.  2012 Microchip Technology Inc. The decision whether functions should be positioned this way or using absolute functions should be based on the location requirements. or that they be placed after other psects. Note: The names “argument” and “parameter” are often used interchangeably.

void test(char a. move literal 0x8 into. See Section 4. . . The parameters for functions that take a variable argument list (defined using an ellipsis in the prototype and which are called non-prototyped parameters) are placed in the parameter memory. parameter variables are allocated memory strictly in the order in which they appear in the function’s prototype. The function test() will receive the parameter b in its function auto-parameter block and a in the W register. the following ANSI-style function. which may require additional instructions. The above example does not consider data memory banking or program memory paging. The auto variables for a function can be allocated across multiple banks and in any order. A call to this function: test(xyz.17 “--ASMLIST: Generate Assembler List Files” for the option that generates this file. the parameter b is held in the memory locations ?_test (LSB) and ?_test+1 (MSB). for example.8. int b). DS52053B-page 186  2012 Microchip Technology Inc. . .. can always be examined in the assembly list file.w (_test) . along with named parameters. This means that the parameters will always be placed in the same memory bank. The exact code used to call a function. would generate code similar to: MOVLW MOVWF CLRF MOVF CALL 08h ?_test ?_test+1 _xyz.MPLAB® XC8 C Compiler User’s Guide Unlike auto variables. Take. or the code used to access a parameters from within a function. the auto-parameter memory locations for the 16-bit parameter move xyz into the W register In this example.. This is useful if you are writing an assembly routine that must call a function with parameters. 8). or accept arguments when it is called.

This feature is not available for PIC18 devices. automatically swap to using a method that involves the use of a lookup table and which does not require use of the hardware stack. This means of calling functions allows functions to be nested deeply without overflowing the limited stack available on baseline and mid-range devices. the address of the parameter area is also placed in the FSR0 register. but for other 8-bit devices.8 Calling Functions All 8-bit devices use a hardware stack for function return addresses. a function is reached by a jump (not a call) directly to its address. If this suboption is disabled (the default state).7 Function Return Values Function return values are passed to the calling function using either the W register. See Section 4. CALL assembly instructions are used to transfer control to a C function when it is called. Values larger than a byte are returned in the function’s parameter memory area. the compiler will issue a warning to indicate that this is the case. The stack usage grows if a called function calls another before returning. The depth of this stack varies from device to device.8. however. DS52053B-page 187 . or the function’s parameter memory in its auto-parameter block. function return addresses will be destroyed and the code will eventually fail. Before this is done the address of a special “return” instruction (implemented as a jump instruction) is stored in a temporary location inside the called function. instead of issuing a warning. where the depth of the stack will be exceeded by a call. When the lookup method is being employed. this is the only way in which calls are made. Eight-bit values are returned from a function in the W register. with the least significant word (lsw) in the lowest memory location. Having return values also located in the same memory as that used by the parameters can reduce the code size for functions that return a modified copy of their parameter. This return instruction will be able to return control back to the calling function. the compiler will.8.8. the function: int return_16(void) { return 0x1234. If the hardware stack overflows. } will exit with the code similar to: MOVLW MOVWF MOVLW MOVWF RETURN 34h (?_return_16) 12h (?_return_16)+1 For PIC18 targets returning values greater than 4 bytes in size. For example. the compiler can swap to an alternate way of making calls. For PIC18 devices.50 “--RUNTIME: Specify Runtime Environment” for details on this option. Each function calls uses one level of stack. it does come at the expense of memory and program speed. If the stackcall suboption is enabled. This stack level is freed after the called routine executes a RETURN instruction. as detailed below. The stackcall suboption to the --RUNTIME option controls how the compiler behaves when the compiler detects that the hardware stack is about to overflow due to too many nested calls. Typically. 5.  2012 Microchip Technology Inc.C Language Features 5.

8. DS52053B-page 188  2012 Microchip Technology Inc. The compiler will make no assumptions about the selected bank when such routines return. .MPLAB® XC8 C Compiler User’s Guide 5.5. even across function calls to other functions. The compiler will not be able to track the bank selected by routines written in assembly. The “Tracked objects” section associated with each function and which is shown in the assembly list file relates to this bank tracking mechanism. See Section 5. See 6. return with any RAM bank selected. the compiler will use this information to try to remove redundant bank selection instructions which might otherwise be inserted into the generated code. and may. even if they are called from C code.1 BANK SELECTION WITHIN FUNCTIONS A function can.8.5 “Assembly-Level Optimizations” for more information of the content of these files. The compiler tracks the bank selections made in the generated code associated with each function. If the bank that is selected when a function returns can be determined.1 “Address Spaces” for more information on RAM banks.

PIC18 devices have two separate interrupt vectors and a priority scheme to dictate which interrupt code is executed. use the qualifier low_priority in addition to interrupt in the function definition. is usually the main part of the program that executes after Reset. This is the only function prototype that makes sense for an interrupt function since they are never directly called in the source code. An interrupt function must be declared as type void interrupt and may not have parameters. both user-defined and library functions. Enhanced mid-range and PIC18 devices. Note: Baseline devices do not utilize interrupts and so the following sections are only applicable for mid-range. including functions called from the ISR and library code. If the xc8 option --STRICT is used. There may be many sources of interrupt that share the same interrupt vector.1 Writing an Interrupt Service Routine The function qualifier interrupt may be applied to a C function definition so that it will be executed once the interrupt occurs. there are other flags that can disable each interrupt priority. This contrasts with main-line code. the interrupt keyword becomes __interrupt. Interrupt functions must not be called directly from C code (due to the different return instruction that is used). Interrupt functions are often called Interrupt Service Routines. Each mid-range device interrupt source typically has a control flag in an SFR which can disable that interrupt source. or ISRs. On PIC18 devices. DS52053B-page 189 . There is only one interrupt vector on mid-range and Enhanced mid-range devices. An error will result if there are more interrupt functions than interrupt vectors in a program. Regardless of the source of the interrupt. The interrupt function must then contain code to determine the source of the interrupt before proceeding. Peripherals are associated one of the interrupt priorities (vectors) through settings in the peripheral’s SFRs. generating code to save and restore any registers used and return using a special instruction. This address is a attribute of the device and cannot be changed. but they themselves may call other functions. Interrupt code completes at the point where the corresponding return from interrupt instruction is executed. the device will vector to one specific location in program memory and execution continues from that address. In addition to the global interrupt enable flag. Individual interrupt sources can be disabled via a control flag in an SFR associated with that interrupt source. which. To create a low-priority interrupt function. interrupt functions default to being high priority.  2012 Microchip Technology Inc. 5. There is no priority of interrupt sources. but there is only ever one interrupt function associated with each vector.9 INTERRUPTS The MPLAB XC8 compiler incorporates features allowing interrupts to be fully handled from C code. Interrupt code is the name given to any code that executes as a result of an interrupt occurring. for a freestanding application. The compiler will process the interrupt function differently to any other functions. Check your device data sheet for full information how your device handles interrupts.C Language Features 5.9. The two interrupts are designated as low and high priority. In addition there is a global interrupt enable flag that can disable all interrupts sources and ensure that an interrupt can never occur.

} // process any other low priority sources here } 5. tick_count = 0. if required } Code generated by the compiler will be placed at the interrupt vector address which will execute this function after any context switch that is required. ++tick_count.2 Specifying the Interrupt Vector The interrupt function(s) cannot be changed at runtime. return. . in this case a timer. void interrupt tc_int(void) { if (TMR0IE && TMR0IF) { TMR0IF=0. Notice that the code in the interrupt function checks for the source of the interrupt. That is. DS52053B-page 190  2012 Microchip Technology Inc. int tick_count. The following is an example of a low priority interrupt function that could be written for PIC18 devices. void interrupt low_priority tc_clr(void) { if (TMR1IE && TMR1IF) { TMR1IF=0.MPLAB® XC8 C Compiler User’s Guide An example of an interrupt function is shown here. An error will result if there are more interrupt functions than interrupt vectors in a program. Checking the interrupt enable flag is required since interrupt flags associated with a peripheral may be asserted even if the peripheral is not configured to generate an interrupt. by looking at the interrupt flag bit (TMR0IE) and the interrupt flag bit (TMR0IF). return.9. } // process other interrupt sources here. you cannot have alternate interrupt functions and select which will be active during program execution.

must be saved in code generated by the compiler. It is not used by all devices. Thus. if you include inline assembly code into an interrupt function. DS52053B-page 191 . or any of the functions that it calls (based on the call graph generated by the compiler). a compiler temporary location that acts like a pseudo register. If the W register is to be saved by the compiler. 5.3 5. By default.3. Some errata workarounds also prevent the use of the shadow registers see Section 4. On mid-range devices.  2012 Microchip Technology Inc.3. STATUS.9.C Language Features 5. Most registers to be saved are allocated memory in the interrupt function’s auto area. The same is true for any assembly routines called by the interrupt code. 1. The order of restoration is the reverse to that used when context is saved. FSR and PCLATH registers and the BTEMP1 pseudo register must be saved by code produced by the compiler. See Section 5. The only register that may need to be saved is BTEMP11. and saves these appropriately. For the low priority PIC18 interrupts. the compiler will not use the shadow registers if compiling for the MPLAB ICD debugger.9. This makes interrupt functions on Enhanced mid-range PIC devices very fast and efficient. If the device for which the code is written does not have common memory. a byte is reserved in all RAM banks for the storage location for W register. Any registers or compiler temporary objects used by the interrupt function. as the debugger itself utilizes these shadow registers. you may have to add extra assembly code to save and restore any registers or locations used. Assembly code placed inline within the interrupt function is not scanned for register usage. Other mid-range PIC processors only save the entire PC (excluding the PCLATH register) when an interrupt occurs. if required. the W register is stored in BTEMP0. The BTEMP register is a memory location allocated by the compiler. The compiler determines exactly which registers and objects are used by an interrupt function. all registers that has been used by the interrupt code will be saved by software. the PIC18 high-priority interrupt function will utilize its internal shadow register to save the W.27 “--ERRATA: Specify Errata Workarounds”. it may be stored to memory reserved in the common RAM. or context switch code. Note that for some older devices. BSR and FSRx registers in hardware (using special shadow registers) and hence these registers do not need to be saved by software. All other used registers are saved in software. a pseudo register. They can be treated like any other auto variable and use the same assembly symbols. STATUS. but it is treated like a register for code generation purposes.9.2 CONTEXT RESTORATION Any objects saved by software are automatically restored by software before the interrupt function returns. The W.1 Context Switching CONTEXT SAVING ON INTERRUPTS Some registers are automatically saved by the hardware when an interrupt occurs. This is the context save. or when the shadow registers cannot be used. STATUS and BSR registers.8.7 “Register Usage” for the registers that must be saved and restored either by hardware or software when an interrupt occurs. Enhanced mid-range PIC devices save the W. other than those saved by the hardware.

The duplicated code and data uses different symbols and are allocated different memory. in a program the function main calls a function called input. MPLAB XC8 has a feature which will duplicate the output associated with any function called from more than one call tree in the program’s call graph. and the interrupt will call the duplicated function’s output.. However. if defined. Duplicated PIC18 functions use the prefixes i1 and i2 for the low.2.5 Function Duplication It is assumed by the compiler that an interrupt may occur at any time. These macros are ei(). and di().2.9.5. and the code would need to be reverted if it was ported to a compiler which did support reentrancy. The identifiers consists of the same name used in the original output prefixed with i1. To illustrate. DS52053B-page 192  2012 Microchip Technology Inc. ei(). Interrupts are automatically re-enabled by hardware on execution of the RETFIE instruction. As all functions are not reentrant (because of the dependance on the compiled stack for local objects.9. // A/D interrupts will be used // all peripheral interrupts are enabled // enable all interrupts // disable all interrupts Note: Never re-enable interrupts inside the interrupt function itself. which disable or mask all interrupts.h>. These macros should be used once the appropriate interrupt enable bits for the interrupts that are required in a program have been enabled.and high-priority interrupts. which enable or unmask all interrupts. This is similar to the process you would need to undertake if this feature was not implemented in the compiler: the C function could be duplicated by hand. there is no duplication of the C source code itself. once you have included <xc. you would have to maintain both functions. For example: ADIE = 1. given different names and one called from main-line code. 5. The compiler-generated duplicate will have unique identifiers for the assembly symbols used within it. see Section 5. PEIE = 1. and one tree for the interrupt function. The output of the function called from main-line code will not use any prefixes and the assembly names will be those normally used.4 Enabling Interrupts Two macros are available. respectively.. On all devices. // . which control the masking of all available interrupts. if a function appears to be called by an interrupt function and by main-line code this could lead to code failure. Re-enabling interrupts inside an interrupt function may result in code failure.MPLAB® XC8 C Compiler User’s Guide 5. they affect the GIE bit in the INTCON register. . The duplication takes place only in the called function’s output.1 “Compiled Stack Operation”). Main-line code will call the original function’s output. so are fully independent. This function is also called by an interrupt function. di(). There will be one call tree associated with main-line code. the other from the interrupt function.

Code associated with library functions are duplicated in the same way. See Section 5. if an interrupt occurs when executing the function. such as those that perform division or floating-point operations associated with C operators. These symbols will also be seen in the map file symbol table. DS52053B-page 193 . This also applies to implicitly called library routines. The pragma will only affect the first function whose definition follows. if the function read is only ever called from main-line code when the interrupts are disabled.C Language Features Examination of the assembly list file will show assembly code for both the original and duplicate function outputs. For mid-range devices.and high-priority interrupt functions. the generated output will use the symbol ??_input. It is not sufficient to disable the interrupts inside the function after it has been called. This should only be done if the source code guarantees that an interrupt cannot occur while the function is being called from any main-line code. use the pragma twice to specify both levels 1 and 2. To disable duplication for both interrupt priorities. will show the calls made to both of these functions as if they were independently written. // turn off interrupts read(IN_CH1). The following function will not be duplicated if it is also called from the low.or high-priority interrupt functions. The output corresponding to the C function input() will use the assembly label _input. The corresponding label used by the duplicate function will be i1_input. for PIC18 devices it can be 1 or 2 for the low. If the original function makes reference to a temporary variable. 5. // re-enable interrupts The level value specified indicates for which interrupt the function will not be duplicated. #pragma interrupt_level 1 #pragma interrupt_level 2 int timestwo(int a) { return a * 2.5. respectively. then duplication of the function can be prevented if it is also called from an interrupt function as follows.4 “Enabling Interrupts” for more information on how interrupts may be disabled. This feature allows the programmer to use the same source code with compilers that use either reentrant or non-reentrant models. Typically this would be achieved by disabling interrupts before calling the function. The pragma is: #pragma interrupt_level 1 The pragma should be placed before the definition of the function that is not to be duplicated.. }  2012 Microchip Technology Inc. this function would typically be called as follows: di(). The call graph.. the level should always be 1. in the assembly list file.9. ei(). } In main-line code.9. compared to ??i1_input for the duplicate output. Even local labels within the function output will be duplicated in the same way. the code may fail. It does not handle cases where functions are called recursively. For example. #pragma interrupt_level 1 int read(char device) { // .1 DISABLING DUPLICATION The automatic duplication of the function may be inhibited by the use of a special pragma.

and known as the runtime startup code. if used The beginning of the runtime startup code. This is the first function to execute in your program. TABLE 5-10: Label reset_vec powerup start start_initialization SIGNIFICANT ASSEMBLY LABELS Location At the Reset vector location (0x0) The beginning of the powerup routine. This essentially performs a software Reset. The following sections detail exactly what the runtime startup code actually does. but If you require any special initialization to be performed immediately after Reset. For example. . so that execution of the function will never terminate. specifically (and in no particular order): • Initialization of global variables assigned a value when defined • Clearing of non-initialized global variables • General setup of registers or device state Rather than the traditional method of linking in a generic. you should use power-up feature described later in Section 5. precompiled routine.10. Add a loop construct (such as a while(1)) that will never terminate either around your code in main() or at the end of your code. Note that the state of registers after a software Reset may be different to that after a hardware Reset. Additional code provided by the compiler.MPLAB® XC8 C Compiler User’s Guide 5. Code associated with main(). MPLAB XC8 uses a more efficient method which actually determines what runtime startup code is required from the user’s program. You must always have one and only one function called main() in your programs. is not the first code to execute after Reset.e.2 “Startup and Initialization”. is executed first and is responsible for transferring control to the main() function. void main(void) { // your code goes here // finished that. RUNTIME STARTUP AND RESET The identifier main is special.1 Runtime Startup Code A C program requires certain objects to be initialized and the device to be in a particular state before it can begin execution of its function main(). the Reset vector for all 8-bit PIC devices. however. a return statement inside main() is executed.10 MAIN.2 “The Powerup Routine”. in the C output code. i. Details of the files used and how the process can be controlled are described in Section 4. } 5. The compiler inserts special code at the end of main() which is executed if this function ends. It is the job of the runtime startup code to perform these tasks. The following table lists the significant assembly labels used by the startup and powerup code.10. in startup. It is recommended that the main() function does not end. The runtime startup code is executed before main().as The beginning of the C initialization startup code. now just wait for interrupts while(1) continue.4. DS52053B-page 194  2012 Microchip Technology Inc. or code execution reaches the main()’s terminating right brace. The actions and control of this code is described in the following sections. This special code causes execution to jump to address 0.

With some devices.10.  2012 Microchip Technology Inc. This task is also performed by the runtime startup code. For example: --RUNTIME=default. void main(void) { . See Section 5. Variables whose contents should be preserved over a Reset. Such uninitialized objects will only require space to be reserved in RAM where they will reside and be accessed during program execution (runtime). You can choose to have a copy of this register taken so that it can later be examined. should be qualified with the persistent qualifier. DS52053B-page 195 . The runtime startup code will copy all the blocks of initial values from program memory to RAM so that the variables will contain the correct values before main() is executed. and space for the variable reserved in RAM it will reside and be accessed during program execution (runtime). 5.2 “Compiler-Generated Psects”.. void main(void) {. int output. see Section 5.10. If objects are initialized.10. Code relying on variables containing their initial value will fail.1.2 CLEARING OBJECTS Those non-auto objects which are not initialized must be cleared before execution of the program begins. int input = 88.. they require code to be positioned in the function in which they are defined to perform their initialization. Note: Initialized auto variables can impact on code performance. As a result.4 “STATUS Register Preservation” for more information. the TO and PD bits in this register are required to determine the cause of Reset.e. or even power off. It is possible that the initial value of an auto object may change on each instance of the function and so the initial values cannot be stored in program memory and copied. Consider using global or static objects instead. Such variables are linked at a different area of memory and are not altered by the runtime startup code in any way. for example input in the following example.15. This action can be omitted by disabling the init suboption of --RUNTIME. Since auto objects are dynamically created. Initialized variables are those which are not auto objects and which are assigned an initial value in their definition.. placed in the HEX file). particularly if the objects are large in size.8.4.1. initialized auto objects are not considered by the runtime startup code but are instead initialized by assembly code in each function output. the contents of initialized variables will be unpredictable when the program begins execution.-init With this part of the runtime startup code absent..C Language Features 5.1.. The psects used for storing these components are described in Section 5. the runtime startup code which performs this will destroy the contents of the STATUS register. Such initialized objects have two components: their initial value (0x0088 in the above example) stored in program memory (i. for example output in the following example.1 INITIALIZATION OF OBJECTS One task of the runtime startup code is to ensure that any initialized variables contain their initial value before the program begins execution.1 “Persistent Type Qualifier”. Uninitialized variables are those which are not auto objects and which are not assigned a value in their definition.

MPLAB® XC8 C Compiler User’s Guide The psects used for storing these components are described in Section 5. If objects are initialized. Variables whose contents should be preserved over a Reset should be qualified with persistent.4 “STATUS Register Preservation” for more information. .10.3 OSCILLATOR CALIBRATION Some PIC devices come with an oscillator calibration constant which is pre-programmed into the device’s program memory.2 “Compiler-Generated Psects” and typically have a name based on the initialism “bss” (Block Started by Symbol).3. if required. This constant can be written to the OSCCAL register to calibrate the internal RC oscillator. See Section 5. DS52053B-page 196  2012 Microchip Technology Inc.1. see Section 5. See Section 5. the TO and PD bits in this register are required to determine the cause of Reset. Code is automatically placed in the runtime startup code to load this calibration value. 5.1. Such variables are linked at a different area of memory and are not altered by the runtime startup code in any way.10.15. With some devices. the runtime startup code that performs this will destroy the contents of the STATUS register.1 “Persistent Type Qualifier” for more information.8.1 “Oscillator Calibration Constants”.9. You can choose to have a copy of this register taken so that it can later be examined. The runtime startup code will clear all the memory location occupied by uninitialized variables so they will contain zero before main() is executed.4.

1 “Equivalent Assembly Symbols” for more details of the mapping. Refer to comments in this file for more details. No special linker options or other code is required. The state of these bits can be examined after recovering from a Reset condition to determine the cause of the Reset.4. provided the code in this routine is contained in a psect called powerup.2 The Powerup Routine Some hardware configurations require special initialization.4 STATUS REGISTER PRESERVATION The resetbits suboption of the --RUNTIME option (see 4.9. See Section 5. The file should be copied to your working directory. These can be accessed from C code using the declarations: extern bit __powerdown. For correct operation (when using the default compiler-generated runtime startup code). the code must end with a GOTO instruction to the label called start. In the above symbols. and the assembly equivalent symbols use three. 5. The compiler defines the assembly symbols ___powerdown and ___timeout to represent the bit address of the Power-down and Time-out bits within the STATUS register and can be used if required.C Language Features 5. This variable can be accessed from C code using the declaration: extern unsigned char __resetbits. As with all user-defined assembly code.12. any code inside this file must take into consideration program memory paging and/or data memory banking.3.as which is located in the sources directory of your compiler distribution. The compiler will detect if you have defined a powerup routine and will automatically use it. See Section 6. A template powerup routine is provided in the file powerup.10. The entire STATUS register is saved to an assembly variable ___resetbits. often within the first few instruction cycles after Reset. To achieve this there is a hook to the Reset vector provided via the powerup routine.10. modified and included into your project as a source file. The program’s entry point is already defined by the runtime startup code. as well as any applicable errata issues for the device you are using.8. See Section 4.2 “END” for more information on this assembler directive. so this should not be specified in the power-up routine with the END directive (if used). note that the C variables use two leading underscore characters. extern bit __timeout.1. This routine can be supplied in a user-defined assembler module that will be executed immediately after Reset.  2012 Microchip Technology Inc. DS52053B-page 197 .9 “MPLAB IDE V8 Universal Toolsuite Equivalents” for use of this option in MPLAB IDE.50 “--RUNTIME: Specify Runtime Environment”) preserves some of the bits in the STATUS register before being clobbered by the remainder of the runtime startup code.

The parser and code generator analyze the C source code.c module that is linked into the program will only contain code that handles printing of decimal integers. variables and types in the library files. thus creating a custom printf() function for the project being compiled. The printf() function is generated from a special C template file that is customized after analysis of the user’s C code.1 The printf Routine The code associated with the printf function is not precompiled into the library files.h) files. The doprnt. The new call looks like: printf(”output is %6d”). the placeholders that were specified in the printf() format strings are collated to produce a list of the desired functionality of the final function. The template file is found in the lib directory of the compiler distribution and is called doprnt. For example. Consider now that the code is changed and another call to printf() is added.MPLAB® XC8 C Compiler User’s Guide 5. it links in the function for sqrt into your program. After parsing.h> void main(void) { double i. the header files provide declarations (as opposed to definitions) for functions. #include <math. // sqrt referenced.c file is then preprocessed with the those macros specified by the preliminary analysis. sqrt will be linked in from library file i = sqrt(23. but with the more advanced features included as conditional code which can be utilized via preprocessor macros that are defined when it (along with your code) is compiled. if a program contains one call to printf().11 LIBRARY ROUTINES 5. Header files are not library files and the two files types should not be confused. } // declare function prototype for sqrt 5. Now the compiler will detect that additional code to handle printing decimal integers to a specific width must be enabled as well.11. . as well as other preprocessor macros. Your program will require declarations for any functions or symbols used from libraries. typically functions and variable definitions. so the compiler searches the libraries to find a definition there. Only used library functions will be linked into the program output and consume memory. In the following example.c. It contains a minimal implementation of the printf() function.0. the definition for sqrt is not contained in source code. The compiler will note that only the %d placeholder is used and the doprnt. These are contained in the standard C header (. The use of a function from one library file will not include any other functions from that library.5).11. Once found. VPRINTF” for more information on using the printf library function. Library files contain precompiled code.c is then combined with the remainder of the C program in the final code generation step.1 USING LIBRARY ROUTINES Library functions (and any associated variables) will be automatically linked into a program once they have been referenced in your source code. DS52053B-page 198  2012 Microchip Technology Inc. See Section “PRINTF. searching for calls to the printf function. which looks like: printf(”input is: %d”). the p-code output derived from doprnt. For all calls.

6). 4. This module. the compiler could determine that. the actual printf() code used by a program can be observed. DS52053B-page 199 . the size of the code generated for the printf() function will increase. and so it forces a more complete version of printf() to be generated. If the format string in a call to printf() is not a string literal as above. the compiler can look at the number and type of the additional arguments to printf() (those following the format string expression) to determine which placeholders could be valid. the driver will leave behind the pre-processed version of doprnt. No aspect of this operation is user-controllable (other than by adjusting the calls to printf() ). will show the C code that will actually be contained in the printf routine. for example. no floating-point placeholders are required and omit these from being included in the printf() function output. In particular. then the compiler will not be able to reliably predict the printf() usage. even without being able to scan printf() placeholders. if printf() was called as follows: printf(myFormatString. If compiling a program using printf().C Language Features As more features of printf() are detected. This enables the size and complexity of the generated printf() routine to be kept to a minimum even in this case.pre in your working directory. their type must match that of the placeholders. However. As this code has been pre-processed. indentation and comments will have been stripped out as part of the normal actions taken by the C pre-processor. As the arguments after the format string are non-prototyped parameters. called doprnt. For example. however. but is rather a pointer to a string.  2012 Microchip Technology Inc. the compiler can still make certain assumptions regarding the usage of the function.c.

2 “Compiler-Generated Psects”). see Section 4.asm source files included into your project.MPLAB® XC8 C Compiler User’s Guide 5. You may see a psect. a suitable psect for the executable assembly code (See Section 5. By default. We will create our own text psect based on the psect the compiler uses. Most compiler-generated executable code is placed in psects called textn. Use global variables for additional arguments.15. the compiler may perform different optimizations a these are based on the entire program. See Section 5.3 “Interaction Between Assembly and C Code” for a complete description of mappings between C and assembly identifiers. (see Section 5. The following are guidelines that must be adhered to when writing a C-callable assembly routine.) • Select a name (label) for the routine using a leading underscore character • Ensure that the routine’s label is globally accessible from other modules • Select an appropriate C-equivalent prototype for the routine on which argument passing can be modelled • Limit arguments and return values to single byte-sized objects (Assembly routines may not define variables that reside in the compiled stack. An assembly routine is required which can add an 8-bit quantity passed to the routine with the contents of PORTB and return this as an 8-bit quantity. such as the following. where n is a number. Optimization can be enabled by using the --OPT option.15. If assembly must be added.class=CODE. rather than in-lining it in C code. such modules are not optimized by the assembler optimizer. As the project is developed. Check the assembly list file to see how the text psects normally appear for assembly generated from C code.delta=2 DS52053B-page 200  2012 Microchip Technology Inc. or including it as inline assembly in a C module. Note: The more assembly code a project contains.local. Assembly code may need revision if the compiler is updated due to differences in the way the updated compiler may work. The process is the same for other devices. A mapping is performed on the names of all C functions and non-static global variables. generated by the code generator when compiling for baseline or mid-range devices.42 “--OPT: Invoke Compiler Optimizations”. the more difficult and time consuming will be its maintenance.12. . PSECT text0.12. or define. They will be assembled and combined into the output image using the linker.1 “Program Sections” for an introductory guide to these. use a signature value to enable type checking when the function is called • Use bank selection instructions and mask addresses of any variable symbols The following example goes through these steps for a mid-range device.as or .8. These factors do not affect code written in C.12 MIXING C AND ASSEMBLY CODE Assembly language code can be mixed with C code using two different techniques: writing assembly code and placing it into a separate assembler module. • Select. it is preferable to write this as a self-contained routine in a separate assembly module.) • Optionally.1 Integrating Assembly Language Modules Entire functions may be coded in assembly language as separate . 5.

class=CODE. as the optimizer removes these values from the assembly list file.delta=2 Let’s assume we would like to call this routine add in the C domain. you do not need to adjust the default linker options to have the psect correctly placed in memory. If we had chosen add as the assembly routine.9. which means that it is distinct from other psects with the same name. then it could never be called from C code. Check the assembly list file for the signature value of such a function. the data space is byte addressable.8. The last option. This indicates that the memory space in which the psect will be placed is word addressable (value of 2).6 “Function Parameters” for the convention used to pass parameters. but instructions must be word-aligned.4.  2012 Microchip Technology Inc. This flag is not important in this example and can be omitted. The name of the assembly routine is the label that we will place at the beginning of the assembly code.local. by using the GLOBAL assembler directive (Section 6. so make this label globally accessible. You will need to turn the assembler optimizer off for this step. but the reloc (alignment) flag is set to 2.4. is also very important. This psect is called text0.C Language Features See Section 6.9. In assembly domain we must choose the name _add as this then maps to the C identifier add.local. The C-equivalent prototype to this routine would look like: unsigned char add(unsigned char). the delta value.class=CODE. For PIC18 devices.9. the delta value is 1 (which is the default setting). so we have for our mid-range example: PSECT mytext.4. We simply need to choose a different name. _add: We need to be able to call this from other modules. we can determine the signature value.4217 The W register will be used for passing in the argument. program memory is byte addressable. to ensure that the section starts on a word-aligned address.reloc=2 In this case. as the psect name in which we will place out routine. GLOBAL _add By compiling a dummy C function with a similar prototype to this assembly routine.21 “SIGNAT”) can be used.1 “GLOBAL”). Signature values are not mandatory. It lives in the CODE class.3 “PSECT” for detailed information on the flags used with the PSECT assembler directive. We determine that the following SIGNAT directive (Section 6. SIGNAT _add. PSECT text0. With this flag in place. This flag is important as it means it will be automatically placed in the area of memory set aside for code. The label we would use would look like this. See Section 5. The PIC10/12/16 program memory space is word addressable. so you will see code such as the following. DS52053B-page 201 . if required. It is flagged local. so we might choose the name mytext. but allow for additional type checking to be made by the linker.

tell the linker how it should be called . result = add(5). a declaration for the routine must be provided. void main(void) { volatile unsigned char result. W is loaded by the calling function. make _add globally accessible .12. #endasm and asm() Assembly instructions may also be directly embedded inline into C code using the directives #asm.delta=2 .. Typically one instruction is placed in the string.local. The asm(). (e. This form looks and behaves like a C statement. select the bank of this object ADDWF BANKMASK(PORTB).8. statement is used to embed assembler instructions inline with C code. DS52053B-page 202  2012 Microchip Technology Inc. although you can place them there if you prefer.class=CODE. However. The instructions are placed in a string inside what look like function call brackets.. asm(“MOVLW 55\nMOVWF _x”). The #asm and #endasm directives are used to start and end a block of assembly instructions which are to be embedded into the assembly output of the code generator. our routine to add to ints and return the result _add: . The #asm block is not syntactically part of the C program. Here is a C code snippet that declares the operation of the assembler routine. #include <xc.2 #asm. everything following will be placed into the mytext psect PSECT mytext. the result is already in the required location (W)so we can . BANKSEL (PORTB) . and thus it does not obey normal C flow-of-control rules. To call an assembly routine from C code.11 “-P: Preprocess Assembly Files”. the assembly file must be preprocessed as we have used the C preprocessor #include directive.4217 . then calls the routine. . just return immediately RETURN To compile this.MPLAB® XC8 C Compiler User’s Guide Here is an example of the complete routine for a mid-range device which could be placed into an assembly file and added to your project. This ensures that the compiler knows how to encode the function call in terms of parameters and return values. add parameter to port . #endasm or the statement asm().inc> GLOBAL _add SIGNAT _add. This means that you should not use this form of inline assembly inside C constructs like if(). } // call the assembly routine 5.g.w . // declare the assembly routine so it can be correctly called extern unsigned char add(unsigned char a). See Section 4. The BANKSEL directive and BANKMASK macro have been used to ensure that the correct bank was selected and that all addresses are masked to the appropriate size. but you can specify more than one assembly instruction by separating the instructions with a \n character.) Code will be more readable if you one place one instruction in each statement and use multiple statements. this is the easiest means of adding multiple assembly instructions. and hence do not need to be inside the mytext psect. although no call takes place. The GLOBAL and SIGNAT directives do not generator code. while() and for() statements.

 2012 Microchip Technology Inc. before compilation of C source files begin. 5. There are also precautions that must be followed to ensure that assembly code does not interfere with the assembly generated from C code. asm(“BCF 0.5 “Function Duplication”.C Language Features You may use the asm() form of inline assembly at any point in the C source code as it will correctly interact with all C flow-of-control structures. The code generator cannot scan the assembler code for register usage and so will remain unaware if registers are clobbered or used by the assembly code.3”). this does not apply to labels defined in hand-written. The following example shows both methods used: unsigned int var. This information is used to ensure the code generator takes into account requirement of the assembly code. DS52053B-page 203 . BCF 0. it may be duplicated. If you are in doubt as to which registers are being used in surrounding code. you should not define assembly labels in inline assembly if the containing function might be duplicated. void main(void) { var = 1. asm(“RLF (_var)&07fh”). Remember that as the rest of the program changes. When using inline assembler code.3 Interaction Between Assembly and C Code MPLAB XC8 C Compiler incorporates several features designed to allow C code to obey requirements of user-defined assembly code. } inline assembly code is never optimized by the assembler optimizer. #asm // like this.7 “Register Usage”.. compile your program with the --ASMLIST option (see Section 4...16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”) and examine the assembler code generated by the compiler. Thus.8.9. See Section 4. The command-line driver ensures that all user-defined assembly files have been processed first.12. great care must be taken to avoid interacting with compiler-generated code. If a C function is called from main-line and interrupt code.. asm(“RLF (_var+1)&07fh”). inline assembly code in C functions.3.3 BANKSEL(_var) RLF (_var)&07fh RLF (_var+1)&07fh #endasm // do it again the other way. see Section 5. The registers used by the compiler are explained in Section 5. Although a special prefix is used to ensure that labels generated by the compiler are not duplicated.4 “Compilation of Assembly Source” for further information on the compile sequence. the registers and code strategy used by the compiler will change as well. asm(“BANKSEL _var”). The driver is able to read and analyze certain information in the relocatable object files and pass this information to the code generator.

So the function main() will define an assembly label _main. The first function will generate an assembly label _result.c and the other in lcd. it is quite distinct to the main symbol used in C code and they refer to different locations. The code associated with this label is simply a long jump (see Section 6. If the C variable is qualified static. a program contains the definition for two static functions. and functionName is the name of the function. you must be aware of this limitation in the device and the way the compiler works around it for C functions.4 “Long Jumps and Calls”) to the actual function body located elsewhere and identified by the label _add. The same rules apply to non-local static variables as to static functions. DS52053B-page 204  2012 Microchip Technology Inc. both called add. The second will generate the label lcd@result. The first function will generate an assembly label _add. is a chance that there could be more than one variable in the program with exactly the same C name. entry__add: LJMP _add The label entry__add is the function’s entry point and will always be located in a special psect linked in the first half of a program memory page. add(). Baseline PIC devices may use alternate assembly domain symbols for functions. The name of a non-auto C variable also maps to an assembler label that will have the same name. then in assembly the symbols can be accessed using the symbols read@output and update@output.4. The destinations of call instructions on these devices are limited to the first half of a program memory page. If a C function is qualified static. and another static variable with the same name defined in the function update. again.c and the other in lcd. where fileName is the name of the file that contains the variable. So.c. compiled for a baseline device. So the variable result will define an assembly label: _result. both called result. This mapping is such that an “ordinary” symbol defined in the assembly domain cannot interfere with an “ordinary” symbol in the C domain. So for example. The name of the first variable will map to a symbol prepended with an underscore. respectively. there.c. . For example. encodes functions in two parts. where fileName is the name of the file that contains the function. If there is more than one local static variable (i. The second will generate the label lcd@add. For example a program contains the definition for two static variables.1 EQUIVALENT ASSEMBLY SYMBOLS Most C symbols map to an corresponding assembly equivalent.12.1.3.MPLAB® XC8 C Compiler User’s Guide 5.e. it is defined inside a function definition) then all the variables will have an assembly name of the form: functionName@variableName. The name of a C function maps to an assembly label that will have the same name. but with an underscore prepended. as illustrated in the following example of a C function. Hand-written assembly code should always call the entry__funcName label rather than the usual assembly-equivalent function label. the subsequent symbols will have the form: fileName@variableName. but with an underscore prepended. If you plan to call routines from assembly code. and there is more than one static function in the program with exactly the same name. The compiler. if the symbol main is defined in the assembly domain. thus. the name of the first function will map to the usual assembly symbol and the subsequent functions will map to a special symbol with the form: fileName@functionName.. if there is a static variable called output in the function read. One lives in the file main. and variableName is the name of the variable. One lives in the file main.

if the function main defines an auto variable called foobar.4 “INCLUDE”) or use the C preprocessor’s #include directive. e.h>. Function return values have no C identifier associated with them. As there is no corresponding C variable. they will be accessed as an offset from the symbol ??_main. The symbols in this header file look similar to the identifiers used in the C domain when including <xc. then an offset is added to the symbol to access each byte. DS52053B-page 205 . ?_getPort+1.10.. To make accessing of parameter and auto variables easier. So for example. make sure you compile with the -P driver option to preprocess assembly files. SFR definitions will not automatically be accessible. getPort returns a value. EECON1. That symbol is ??_funcName.8. PORTA. If the compiler creates temporary variables to hold intermediate results. The symbol has the form: functionName@variableName. see Section 4. and they contain definitions for static variables of the same name.bitNumber. RA0 is defined as PORTA.11 “-P: Preprocess Assembly Files”. Bits within registers are defined as the registerName. if they are present. The assembly header file <xc.class=CODE. Here is an example of a mid-range assembly module that uses SFRs. If this return value is more than one byte in size. but not recommended as the wrong variable may be accessed or the wrong function called. special equates are defined which map a unique symbol to each variable. it will be located the address held by the assembly symbol ?_getPort. So for example. (see Section 6. 5. but will map to the same memory location.C Language Features If there is more than one static function with the same name. The return value for a function shares the same memory as that function’s parameter variables.inc> GLOBAL _setports PSECT text. Thus. if the function main uses temporary variables. if a function. Include the file using the assembler’s INCLUDE directive. Thus. They are different symbols in different domains.3. where funcName is the function in which the symbol is being used. then the assembly symbol for that parameter is read@channel. the assembly symbol is based on the symbol that represents the auto block for the function plus an offset. The assembly symbol used for return values has the form ?_funcName. e. these will behave like auto variables. Function parameters use the same symbol mapping as auto variables. where funcName is the name of the function returning the value.12. etc.4..delta=2 _setports: MOVLW 0xAA BANKSEL (PORTA) MOVWF BANKMASK(PORTA) BANKSEL (PORTB) BSF RB1  2012 Microchip Technology Inc. the symbol main@foobar can be used in assembly code to access this C variable. Having two static variables or functions with the same name is legal. Do not use this file for assembly inline with C code as it will clash with definitions in <xc.inc> can be used to gain access to these register definitions. If you are using the latter method. #include <xc.local.h>.2 ACCESSING REGISTERS FROM ASSEMBLY CODE If writing separate assembly modules. then the assembly symbol used for these variables will be of the form: fileName@functionName@variableName. If a function called read has a parameter called channel.0.g.g.

The linker handles all of the allocation into program memory.9. the names assigned to bit variables within the registers will include the suffix _bit.4 “Compilation of Assembly Source”.space=1. PSECT flags. There is non comparable file for PIC18 devices. specifically psects defined using the abs and ovrld.3 “PSECT” for information on this directive.3.4 “ORG” for important information on this directive.9. you can specify a non-zero starting address by using the ORG directive. An assembly code files defines a table that must be located at address 0x110 in the data space. 5. #asm MOVLW BANKSEL MOVWF BANKSEL BSF #endasm 0xAA (PORTA) BANKMASK(PORTA) (PORTB) RB1_bit Care must be taken to ensure that you do not destroy the contents of registers that are holding intermediate values of calculations. As this psect is flagged as being abs and ovlrd. MPLAB XC8 is able to determine the address bounds of absolute psects and uses this information to ensure that the code produced from C source by the code generator does not use memory required by the assembly code. relates to absolute psects.MPLAB® XC8 C Compiler User’s Guide If you wish to access register definitions from assembly that is inline with C code.abs. a memory range from address 0x110 to 0x12F in memory space 1 is noted as being used. see Section 4.class=RAM.ovlrd ORG 110h lookup: DS 20h An absolute psect always starts at address 0. This file can only be used with baseline and mid-range devices.h> into the assembly code. The code generator will reserve any memory used by the assembly code prior to compiling C source. So for example. The symbols used for register names will be the same as those defined by <xc. DS52053B-page 206  2012 Microchip Technology Inc. this file is assembled and the resulting relocatable object file scanned for absolute psects.3.3 ABSOLUTE PSECTS Some of the information that is extracted from the initial compilation of assembly code. Some registers are used by the compiler and writing to these registers directly can result in code failure. the example given previously could be rewritten as inline assembly as follows.4. the bounds and space of the psect will be noted — in this case. This information is passed to the code generator to ensure that this address range is not used by the assembly generated from the C code. however. The assembly file contains: PSECT lkuptbl. Here is an example of how this works. For such psects.inc>. only the psects located in data memory need be defined in this way. When the project is compiled. . and so for hand-written assembly. see Section 6. The list of registers used by the compiler and further information can be found in Section 5. a different header file is available for this purpose. See Section 6. Include the header file <caspic.4.7 “Register Usage”. The code generator does not detect when SFRs have changed as a result of assembly code that writes to them.12.

4 “Compilation of Assembly Source”.3. To work around this issue. in assembly code. For example. the variable is automatically marked as being volatile.3 “Interaction Between Assembly and C Code”).4 UNDEFINED SYMBOLS If a variable needs to be accessible from both assembly and C source code. see Section 4. The following PIC18 example illustrates the assembly code accessing this variable. The code generator is informed of these symbols.class=CODE. and then use it.12.7.3. and if they are encountered in the C code. and the corresponding assembly symbol _input (see Section 5. _raster PSECT text.4. In this case.local.w The compiler knows of the mapping between the C symbol input. These will be symbols that are used.12. but it is easier to do so in C source code. the code generator would remove the variable believing it is unused. see Section 5. it can be defined in assembly code. but not defined.C Language Features 5. In this instance the C variable input will not be removed and be treated as if it was qualified volatile. The assembly module(s) can simply declare this symbol using the GLOBAL assembler directive. A problem could occur if there is a variable defined in C source.2 “Volatile Type Qualifier”. if a C program defines a global variable as follows: int input. but is only ever referenced in the assembly code. The linker would be unable to resolve the symbol referenced by the assembly code and an error will result. This action has the same effect as qualifying the variable volatile in the source code. even if they appear to be unused throughout the program.  2012 Microchip Technology Inc. DS52053B-page 207 . GLOBAL _input. but this variable is only ever used in assembly code. Variables qualified as volatile will never be removed by the code generator. MPLAB XC8 also searches assembly-derived object files for symbols which are undefined. if required.reloc=2 _raster: MOVF _input.

unless the variable is volatile. A warning is produced if an unused variable is encountered. you might find that some lines of code are optimized. The C-level optimizations are performed early during the code generation phase and so have flow-on benefits: performing one optimizations may mean that another can then be applied. In Standard mode. Objects qualified volatile will never be removed. Unused return expressions in a function are removed.13 OPTIMIZATIONS The optimizations in MPLAB XC8 compiler can broadly be broadly grouped into C-level optimizations performed on the source code before conversion into assembly. The entire function is removed. Some of these optimizations are integral to the code generation process and so cannot be disabled via an option.7. as if it was never present in the original source code. Referencing a function’s assembly-domain symbol in a separate hand-written assembly module will prevent it being removed.MPLAB® XC8 C Compiler User’s Guide 5. As a result. Redundant assignments to variables not subsequently used are removed. Even if they are enabled. Suggestions as to how specific optimizations can be defeated are given in the sections below. The code associated with calculation of the return value will be removed. The assembly code need only use the symbol in the GLOBAL directive. DS52053B-page 208  2012 Microchip Technology Inc. will not appear in any list or map file. Unused variables in a program are removed. there is typically little impact on source-level debugging of programs. they may only be applied if very specific conditions are met. but others are not. see Section 5. and you will not be able to set a breakpoint on that line in the debugger. and will not be present in debug information. nor has had its address taken. As these optimizations are applied before the debug information has been produced. Uninitialized global variables are assumed to contain zero prior to any assignment to them. and so will not be observable in the debugger. No code will be produced for it and you will not be able to set a breakpoint on any line in the function in the debugger. Taking the address of a variable or referencing its assembly-domain symbol in hand-written assembly code also constitutes use of the variable. some of these optimizations are disabled. A function is considered unused if it is not called. Propagation of constants is performed where the numerical contents of a variable can be determined. directly or indirectly.2 “Volatile Type Qualifier”. The main C-level optimizations which simplify or change the C expressions are listed below. as if it was never present in the original source code. No code will be produced for it. and assembly-level optimizations performed on the assembly code generated by the compiler. .4. and particularly Free mode. Unused functions in a program are removed. The return value is considered unused if the result of all calls to that function discard the return value. Variables removed will not have memory reserved for them. Variables which are not volatile and whose value can be exactly determined are replaced with the numerical value. The assignment statement is completely removed. and the function will be encoded as if its return type was void.

However. Check the assembly list file to see if registers are using in the routine being debugged. such as MPLAB IDE. The assembly-level optimizations are described in Section 6. if a variable is located in a register IDEs.C Language Features Variables assigned a value before being read are not cleared or initialized by the runtime startup code.8.  2012 Microchip Technology Inc.4.5 “Assembly-Level Optimizations”. so this optimization will speed execution of the program startup. see Section 5. This is due to a limitation in the file format used to pass debug information to the IDE (which is currently COFF). may indicate incorrect values in their Watch view.1 “Persistent Type Qualifier”. DS52053B-page 209 . As C-level optimizations are performed before debug information is produced. This applies to data and function pointers. Dereferencing pointers with only target can be replaced with direct access of the target object. All persistent objects are not cleared by the runtime startup code. Only non-auto variables are considered and if they are assigned a value before other code can read their value. they are treated as being persistent. they tend to have less impact on debugging information.

46 “--PRE: Produce Preprocessed Source Code”.1 C Language Comments The MPLAB XC8 C compiler supports standard C comments.11 “-P: Preprocess Assembly Files”.8. See Section 4. . The --PRE option can be used to preprocess and then stop the compilation.2 Preprocessor Directives MPLAB XC8 accepts several specialized preprocessor directives in addition to the standard directives. C++ code comment. If two expressions are being concatenated.14. 5. Used for one or more lines.MPLAB® XC8 C Compiler User’s Guide 5. Remember also that once a macro identifier has been expanded. as well as C++ style comments.pre extension and the same base name as the source file from which it is derived. Macro expansion using arguments can use the # character to convert an argument to a string. Both types are illustrated in the following table. All of these are listed in Table 5-11 on the next page. and the ## sequence to concatenate arguments.b) a##b __paste1(a.b) #define __paste(a. Assembler files can also be preprocessed if the -P driver option is issued. Used for one line only. It will have a . The preprocessed file is not deleted after compilation. consider using two macros in case either expression requires substitution itself. Example /* This is line 1 This is line 2 */ // This is line 1 // This is line 2 5.8.14. DS52053B-page 210  2012 Microchip Technology Inc. so for example #define __paste1(a.14 PREPROCESSING All C source files are preprocessed before compilation. Comment Syntax /* */ // Description Standard C code comment. See Section 4.b) lets you use the paste macro to concatenate two expressions that themselves may require further expansion. it will not be expanded again if it appears after concatenation.

respectively.  2012 Microchip Technology Inc.4 “Pragma Directives” #undef FLAG #warning Length not set Example #elif #else #endasm #endif #error #if Short for #else #if Conditionally include source lines Terminate inline assembly Terminate conditional source inclusion Generate an error message Include source lines if constant expression true #ifdef Include source lines if preprocessor symbol defined #ifndef Include source lines if preprocessor symbol not defined Include text file into source Specify line number and filename for listing (Where nn is a number) short for #line nn Compiler specific options Undefines preprocessor symbol Generate a warning message #include #line #nn #pragma #undef #warning The type and conversion of numeric values in the preprocessor domain is the same as in the C domain. So for example #define MAX 1000*1000 and #define MAX 1000*1000L will define the values 0x4240 and 0xF4240. #endif #ifdef FLAG do_loop(). but acquire one as soon as they are converted by the preprocessor. #elif SIZE == 5 skip_loop(). Preprocessor values do not have a type.h> #include “project.h” #line 3 final #20 Refer to Section 5. do nothing # Generate error if condition false #assert SIZE > 10 Signifies the beginning of inline assem.C Language Features TABLE 5-11: Directive # #assert #asm #define PREPROCESSOR DIRECTIVES Meaning Preprocessor null directive. DS52053B-page 211 . #endif #ifndef FLAG jump(). #endif #include <stdio.14.b) ((a)+(b)) see #ifdef see #if see #asm see #if #error Size too big #if SIZE < 10 c = process(10) #else skip().#asm MOVLW FFh bly #endasm Define preprocessor macro #define SIZE 5 #define FLAG #define add(a. Overflow may be avoided by using a constant suffix. For example. Expressions may overflow their allocated type in the same way that C expressions may overflow. an L after the number indicates it should be interpreted as a long once converted.

etc. see _PROGMEM below.g. e. To indicate the type of flash memory employed by the target device. _16F877 Assigned 0.00 will be represented by 1000. The symbols listed in Table 5-12 show the more common symbols defined by the drivers. To indicate the compiler’s version number multiplied by 1000. To indicate the number of banks of data memory implemented.14. Assigned 1 to indicate that the code is generated for use with the Microchip MPLAB ICD.3 Predefined Macros The compiler drivers define certain symbols to the preprocessor.. v1. TABLE 5-12: Symbol __CHIPNAME __DATABANK __DATE__ __FILE__ __FLASHTYPE PREDEFINED MACROS When set When chip selected Usage To indicate the specific chip type selected. Indicates MPLAB XC compiler for Microchip in use. To indicate whether device has common RAM area. Indicates the address at which the STATUS register will be saved To indicate the current time.g. 08:06:31. Indicates MPLAB XC compiler for Microchip 8-bit devices in use. To indicate the specific chip type selected. __MPLAB_PICKITX__ If compiling for MPLAB® PICKIT 2/3 __MPLAB_REALICE__ If compiling for MPLAB® REALICE __RESETBITS_ADDR __TIME__ __XC __XC8 __XC8_VERSION If --RUNTIME option request STATUS register save Always Always Always Always _CHIPNAME _BANKBITS_ _BANKCOUNT_ _COMMON_ When chip selected Always Always If common RAM present DS52053B-page 212  2012 Microchip Technology Inc.Identifies which bank the EEDmented ATA/PMDATA register is found Always Always If flash memory is implemented To indicate the current date.g. May 21 2004 To indicate this source file being preprocessed. e.. allowing conditional compilation based on chip type. 2 or 4 available banks or RAM. e. . 2 or 3. Assigned 1 to indicate that the code is generated for use with the Microchip MPLAB PICKIT 2 or PICKIT 3 Assigned 1 to indicate that the code is generated for use with the Microchip MPLAB REALICE.g. e. To indicate this source line number.ICD 2 or ICD 3. Indicates device a ’J’ series part ® __LINE__ __J_PART __MPLAB_ICDX__ Always If PIC18 device If compiling for MPLAB ICD or MPLAB ICD 2/3 debugger (where X is empty.MPLAB® XC8 C Compiler User’s Guide 5. __16F877 If eeprom or flash memory imple.. 1 or 2 to indicate 1.. e..g.

To indicate that the 4000 word boundary errata is applied _HTC_VER_MAJOR_ _HTC_VER_MINOR_ _HTC_VER_PATCH_ _HTC_VER_PLVL_ _MPC_ _OMNI_CODE_ _PIC12 _PIC12E _PIC14 _PIC14E Always Always Always Always If baseline (12-bit instruction) device If enhanced baseline (12-bit instruction) device If mid-range (14-bit instruction) device If Enhanced mid-range (14 bit instruction) device If PIC18 (16-bit instruction) device If compiling for mid-range device with flash memory _PIC18 _PROGMEM_ _RAMSIZE _ROMSIZE EEPROMSIZE If PIC18 device Always Always ERRATA_4000_BOUND If the ERRATA_4000 applies ARY  2012 Microchip Technology Inc. 3 (block write with manual erase) To indicate how many bytes of data memory are available To indicate how many words of program memory are available. To indicate selected device is an enhanced baseline PIC devices. 1 or 2 to indicate 1. of the compiler’s version number. 2 (block write with auto erase). To indicate the type of flash memory employed by the target device. 2 or 4 available banks or general purpose RAM. To indicate selected device is an Enhanced mid-range PIC devices. DS52053B-page 213 .To indicate target device may tor calibration register require oscillator calibration Always Indicates which of PRO. Indicates compiling using an OCG compiler. To indicate the patch level of the compiler’s version number. Indicates compiling for Microchip PIC® MCU family. Values of 2. Indicates PIC18 family Size of flash erase block Size of flash write block Assigned 0.C Language Features TABLE 5-12: Symbol _EEPROMSIZE _ERRATA_TYPES Always If PIC18 device PREDEFINED MACROS (CONTINUED) When set Usage To indicate how many bytes of EEPROM are available. respectively. 0 (read only). Standard or Free compiler is in use. To indicate the whole or decimal component. 1 or 0 are assigned respectively. see --ERRATA option Section 4. To indicate selected device is a mid-range PIC devices. To indicate selected device is an PIC18 devices. To indicate selected device is a baseline PIC devices.8. _FAMILY_FAMILY_ If PIC18 device _FLASH_ERASE_SIZE Always _FLASH_WRITE_SIZE Always _GPRBITS_ Always _HAS_OSCVAL_ _HTC_EDITION_ If the target device has an oscilla. Values 0xFF (unknown).27. To indicate how many bytes of EEPROM are available. Indicates the errata workarounds being applied. 0xF0 (none). 1(word write with auto erase).

These are implemented through the use of the ANSI standard #pragma facility.407 DS52053B-page 214  2012 Microchip Technology Inc. . 3 for MPLAB ICD 3.14. A list of the keywords is given in Table 5-13.fsr Directive Specify code generation for #pragma switch direct switch statements Control messaging parameters #pragma warning disable 299. Assigned 1 to indicate that the code is generated for use with the Microchip MPLAB ICD 1. Those keywords not discussed elsewhere are detailed below. TABLE 5-13: addrqual config inline intrinsic interrupt_level pack printf_check psect regsused switch warning PRAGMA DIRECTIVES Meaning Specify action of qualifiers Specify configuration bits Inline function if possible Specify function is inline Allow call from interrupt and main-line code Specify structure packing Enable printf-style format string checking Rename compiler-generated psect Specify registers used by function Example #pragma addrqual=require #pragma config WDT=ON #pragma inline(getPort) #pragma intrinsic(_delay) #pragma interrupt_level 1 #pragma pack 1 #pragma printf_check(printf) const #pragma psect nvBANK0=my_nvram #pragma regsused myFunc wreg. The format of a pragma is: #pragma keyword options where keyword is one of a set of keywords.4 Pragma Directives There are certain compile-time directives that can be used to modify the behavior of the compiler. Each symbol.MPLAB® XC8 C Compiler User’s Guide TABLE 5-12: Symbol HI_TECH_C MPLAB_ICD Always If compiling for MPLAB® ICD or MPLAB ICD 2/3 debugger PREDEFINED MACROS (CONTINUED) When set Usage To indicate that the C language variety is HI-TECH C compatible. is equated to 1 unless otherwise stated. Assigned 2 for MPLAB ICD 2. 5. some of which are followed by certain options. if defined.

the last pragma determines the compiler’s response. if required.6 THE #PRAGMA PACK DIRECTIVE All 8-bit PIC devices can only perform byte accesses to memory and so do not require any alignment of memory objects within structures. The directive is only usable with special functions that the code generator will expand internally. This pragma is an in-code equivalent to the --ADDRQUAL option and both use the same arguments.4.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”. Such functions do not have corresponding source code and are handled specially by the compiler. The pragma has effect over the entire C program and should be issued once.  2012 Microchip Technology Inc. See the inline function specifier for that operation.4. This pragma will have no effect when used. See Section 5. See Section 5.14. in Section 5.4.C Language Features 5.1 THE #PRAGMA ADDRQUAL DIRECTIVE This directive allows you to control the compiler’s response to non-standard memory qualifiers.5 “Configuration Bit Access” for full details.2 “Inline Specifier”. see. For example: #pragma addrqual=require bank2 int foobar.4.2 THE #PRAGMA CONFIG DIRECTIVE This directive allows the device configuration bits to be specified for PIC18 target devices. e. 5.4 THE #PRAGMA INTRINSIC DIRECTIVE The #pragma intrinsic directive is used to indicate to the compiler that a function will be inlined intrinsically by the compiler.5 The #pragma interrupt_level directive can be used to prevent function duplication of functions called from main-line and interrupt code. 5.5. 5.1.14. DS52053B-page 215 .14.4.14.14.1 “Disabling Duplication” for more information.14. see Section 4. If the pragma is issued more than once.8. 5. THE #PRAGMA INTERRUPT_LEVEL DIRECTIVE 5.g the _delay function.8. This pragma has the same effect as using the inline function specifier. Note: Use of this pragma with a user-defined function does not mean that function will be inlined and an error will result.4.3 THE #PRAGMA INLINE DIRECTIVE The #pragma inline directive indicates to the compiler that calls to the specified function should be as fast as possible.3.9.

but the new psect must be linked into the same bank. If the name of the standard psect that is being redirected contains a counter (e.2 “Compiler-Generated Psects”. You may also use this for any user-defined function that accepts printf -style format strings. These psects must be assembled in a particular order and the use of this pragma to redirect some of their content will destroy this order. The qualifier following the function name is to allow automatic conversion of pointers in variable argument lists. e. DS52053B-page 216  2012 Microchip Technology Inc. regardless of the counter value. you could use: #pragma psect text%%u=lookupfunc int lookup(char ind) { . 5. . but sometimes it is necessary to redirect variables or code into different psects when a special memory configuration is desired. See Section 4.h> includes the directive: #pragma printf_check(printf) const to enable this checking for printf(). This is fine for most applications. Although the format string is interpreted at runtime. Standard psects that make reference to a bank number are not using a counter and do not need the placeholder to match.7 THE #PRAGMA PRINTF_CHECK DIRECTIVE Certain library functions accept a format string followed by a variable number of arguments in the manner of printf(). it can be compile-time checked for consistency with the remaining arguments. however.g. The above example would cast any pointers to strings in RAM to be pointers of the type (const char *) Note that the warning level must be set to -1 or below for this option to have any visible effect. For example.).4. use: #pragma psect bssBANK1=sharedObj int foobar.g. you can explicitly position this new psect without affecting the placement of anything in the original psect. Use of this pragma with RAM-based psects that are intended to be linked into a particular RAM bank is acceptable. This pragma should not be used for any of the data psects (data or idata) that hold initialized variables.MPLAB® XC8 C Compiler User’s Guide 5. the redirect an uninitialized variable from bank 1 memory. text1. For example. text0. text2.. This psect will be identical to standardPsect in terms of its flags and attributes. The general form of this pragma looks like: #pragma psect standardPsect=newPsect and instructs the code generator that anything that would normally appear in the standard psect standardPsect.8 THE #PRAGMA PSECT DIRECTIVE Normally the object code generated by the compiler is broken into the standard psects.59 “--WARN: Set Warning Level”.. will now appear in a new psect called newPsect.15. For an introductory guide to psects. it will have a unique name. see Section 5. This is described in 5. Thus. to remap a C function. text%%u.15.14. etc.8. This will match any psect.. for example the system header file <stdio. Some code and data compiler-generated psects may be redirected using a #pragma psect directive.1 “Program Sections”. Linking the new psect to a different bank may lead to code failure. the placeholder %%u should be used in the name of the psect at the position of the counter.4. This directive enables this checking for the named function..14.

Check either the assembly list file or the map file with the pragma in place to ensure that the mapping has worked as expected and that the function or variable has been linked at the address specified. text13 text12 maintext text14 07E5 07E4 07ED 07E8  2012 Microchip Technology Inc. you cannot redirect the standard psect for some of the module. Any given psect should only be redirected once in a particular module. then swap back to using the standard psect for the remainder of the source code. Note that the location of objects and functions may vary with the target device and compiler options selected. That is.. Consider this crude program that consists of several functions. Symbol Table _getInput _init _main _masher . } int masher(int val) { return val. init(). For example. The pragma should typically be placed at the top of the source file.5 “Assembly-Level Optimizations”) to determine the psect in which the function or object is normally positioned. It is recommended that the code or variables to be separated be placed in a source file all to themselves so they are easily distinguished.. define the function or object in the usual way and without this pragma. DS52053B-page 217 . #include <xc. } } The programmer decides that the function masher() is to be linked at a particular address and they do not want to make the function absolute. the map file shows the symbol associated with the function and the psect in which it is located. while(1) { input = getInput(). } void main(void) { int input. Now check the assembly list file (see 6. masher(input).h> void init(void) { } int getInput(void) { return PORTA. The programmer first compiles they code and checked either the assembly list file or map file to find the psect in which masher is normally found. To determine the psect in which the function or object is normally located.C Language Features This pragma affects the entire module in which it is located. regardless of the position of the pragma in the file.

DS52053B-page 218  2012 Microchip Technology Inc. The psect pragma is more complex... The source code for the masher() function is removed from this source file and placed in is own file. Using absolute functions and variables is the easiest method. Symbol Table _getInput _init _main _masher . After recompiling. Note that its address has not changed. .. see Section 5. } After recompiling. Note that the addresses of other functions have not been affected by the pragma in this example..7 “-L-: Adjust Linker Options Directly” for information on controlling the linker from the driver or in MPLAB IDE.MPLAB® XC8 C Compiler User’s Guide So it is allocated to a textn psect.4 “Changing the Default Function Allocation”. See 5. The updated map file now shows the following. “Linker” for the features and options available when linking. For example. The decision whether functions or variables should be positioned using absolutes or via the psect pragma should be based on the location requirements. #pragma psect text%%u=myMasherPsect int masher(int val) { return val. but offers all the flexibility of the linker to position the new psect into memory. See also 4. text13 text12 maintext myMasherPsect 07E5 07E4 07ED 07E8 The programmer now uses the driver option -L-pmyMasherPsect=1000h to locate this psect at the desired location.8. text13 text12 maintext myMasherPsect 07E5 07E4 07ED 1000 Variables can also be placed at specific positions by making them absolute. Symbol Table _getInput _init _main _masher . The same is also true for functions. the function is now located in its own psect. The psect pragma is then applied so that this new file contains the following. or that the psect be placed anywhere in a compiler-defined or user-defined range of address. the map file now shows the following.8.5. or that they be placed after other psects. but only allows placement at an address which must be known prior to compilation. See Chapter 7.4 “Absolute Variables”. you can specify that functions or variables reside at a fixed address.

#pragma regsused search wreg status fsr0 to indicate that this routine used the W register. and registerList is a space-separated list of registers names. DS52053B-page 219 .9 THE #PRAGMA REGSUSED DIRECTIVE The #pragma regsused directive allows the programmer to indicate register usage for functions that will not be “seen” by the code generator. For example. Here.4. but in these cases the register usage of these functions can be accurately determined by the compiler and the pragma is not required. In the C source. if the routine does in fact use these registers. the compiler chooses how switch statements will be encoded to produce the smallest possible code size. The compiler will determine only those registers and objects which need to be saved for an interrupt function defined and use of this pragma allows the code generator to also determine register usage for routines written in assembly code.14. 5. STATUS and FSR0.C Language Features 5. for example if they were written in assembly code. The code generator may use any of these registers to hold values across a function call. The general form of the switch pragma is: #pragma switch switchType where switch_type is one of the available switch types (the only switch type currently implemented for PIC18 devices is space) listed in Table 5-14. Hence. the compiler will assume that the external function uses all registers. The general form of the pragma is: #pragma regsused routineName registerList where routineName is the C equivalent name of the function or routine whose register usage is being defined. It has no effect when used with functions defined in C code. if required. unreliable program execution may eventuate. we may write: extern void search(void).14. The register names are not case sensitive and a warning will be produced if the register name is not recognized. FSR0 expands to both FSR0L and FSR0H. These could be listed individually.10 THE #PRAGMA SWITCH DIRECTIVE Normally. If this pragma is not used. TABLE 5-14: speed space time auto direct (deprecated) simple (deprecated) SWITCH TYPES switch type description Use the fastest switch method Use the smallest code size method Use a fixed delay switch method Use smallest code size method (default) Use a fixed delay switch method Sequential xor method  2012 Microchip Technology Inc.4. The #pragma switch directive can be used to force the compiler to use a different coding strategy. Those registers not listed are assumed to be unused by the function or routine. A blank list indicates that the specified function or routine uses no registers. a routine called _search is written in PIC18 assembly code. as shown in Table 5-9.

The time taken to execute each case is the same. #pragma warning disable 359 readp(&i).e. such as warnings and errors. see Section 4. The position of the pragma is only significant for the parser. The following example shows the warning associated with assigning the address of a const object to a pointer to non-const objects. The state of those warnings which have been disabled can preserved and recalled using the warning push and warning pop pragmas.4. #pragma warning pop Here the state of the messaging system is saved by the warning push pragma. errors directly associated with C code.14. i... i.11. For full information on the massaging system employed by the compiler. then after the source code which triggers the warning.11 THE #PRAGMA WARNING DIRECTIVE This pragma allows control over some of the compiler’s messages. so this is useful where timing is an issue.1 The Warning Disable Pragma Some warning messages can be disabled by using the warning disable pragma. #pragma warning enable 359 } This same affect would be observed using the following code. Pushes and pops can be nested to allow a large degree of control over the message behavior. There is information printed in the assembly list file for each switch statement showing the chosen strategy. DS52053B-page 220  2012 Microchip Technology Inc. a parser warning number may be disabled for one section of the code to target specific instances of the warning.14.e. see Section 6. Such code normally produces warning number 359. This pragma will only affect warnings that are produced by the parser or the code generator. The auto option may be used to revert to the default behavior. This pragma affects all subsequent code. Specific instances of a warning produced by the code generator cannot be individually controlled and the pragma will remain in force during compilation of the entire module. int readp(int * ip) { return *ip.6.MPLAB® XC8 C Compiler User’s Guide Specifying the time option to the #pragma switch directive forces the compiler to generate a table look-up style switch method.g state machines. the state of the messaging system is retrieved by using the warning pop pragma. .6 “Compiler Messages”. void main(void) { unsigned char c. #pragma warning push #pragma warning disable 359 readp(&i).4. } const int i = 'd'. 5. e. 5.4 “Switch Statement Information”. Warning 359 is disabled.

C Language Features 5.14.  2012 Microchip Technology Inc. } Compilation of this code would result in an error. This is only possible by the use of the warning pragma and only affects messages generated by the parser or code generator. not the usual warning. The position of the pragma is only significant for the parser. DS52053B-page 221 . i..4.11.2 The Warning Error/warning Pragma It is also possible to change the type of some messages. or immediately if the maximum error count has been reached. The error will force compilation to cease after the current module has concluded. #pragma warning error 359 readp(&i). a parser message number may have its type changed for one section of the code to target specific instances of the message. void main(void) { unsigned char c.e. The following example shows the warning produced in the previous example being converted to an error for the instance in the function main(). Specific instances of a message produced by the code generator cannot be individually controlled and the pragma will remain in force during compilation of the entire module.

as well as any special packing instructions.1. The label on the box indicates the destination city and country. but this is only required in special circumstances.1 AN ANALOGY Our analogy is based around a company which sells components.1 Program Sections There is a lot of confusion as to what psects (program sections) actually are and even more confusion as to how they are placed in memory. the collated boxes in each holding bay are first wrapped in plastic to keep them together. These options specify the memory of the device and how the psects should be placed in the memory. The required components are collected and placed in a box of sufficient size. The linker will run with options that are obtained from the command-line driver. These bundles are then placed into a shipping container bound for that country.15 LINKING PROGRAMS The compiler will automatically invoke the linker unless the compiler has been requested to stop after producing an intermediate file. a packing machine reads the labels on the boxes and sorts them by destination city. As there might be more than one destination city in the same country. And so ends another productive day in the warehouse. At the other end of the conveyor belt. Such an understanding is vital for assembly programmers and understanding “Can’t find space” error messages issued by the linker.7 “-L-: Adjust Linker Options Directly” for more information. See Section 7. The linker options passed to the linker can be adjusted by the user. The consignments are sent from a central warehouse in shipping containers to a regional office and then delivered to the customer. The box is labelled then placed on a conveyor belt. The map file is the best place to look for memory information. 5. Like all analogies. you should have a better understanding of: • Why assembly code has to be packed and manipulated in sections • Why the linker packs sections into classes rather than the device memory • Why a “Can’t find space” error message may be issued even though there is plenty of space left in a device’s memory 5. it can be misleading and can only be taken so far. . but it relates the main principles of code generation. the linker and sections back to something that you should understand.15.) The linker creates a map file which details the memory assigned to psects and some objects within the code. and serves as an introduction to how compilers must generate code and have it allocated into memory. a robot assembles each order. all the boxes destined for the same city are collated into one holding bay.4 “Map Files” for a detailed explanation of the detailed information in this file. Thus. there could be many bundles placed in the same container. Once the day’s order are all processed. No linker scripts are used.MPLAB® XC8 C Compiler User’s Guide 5.8. In the warehouse. DS52053B-page 222  2012 Microchip Technology Inc. By the end of this section. The following aside takes the form of an analogy and examples. Customers throughout the world place orders for these components.15. See Section 4.

but the compiled code is always allocated to one of several memory areas. but the components are always shipped to one of several countries. the warehouse is likened to the compiler. Both these processes are compared in Figure 5-4.15.@ 0x0 global ?_frexp ?_frexp: . and assembles the components to fulfill that order. the compiler reads (variable and function) definitions in a C program and generates the assembly code to implement each definition.1. . the linker.2 THE COMPILER EQUIVALENT Let’s now look at the similarities and differences between this situation and the compilation process. nor after the compilation process – that is another story. . ‧‧‧ i n tr e s u l t . f l o a ts c a l e . FIGURE 5-4: THE WAREHOUSE AND COMPILER SIDE BY SIDE ORDER 1 3 x TSC235 ORDER 2 2 x RC123a 1 x TSD87 2 x XAM99 10 x TD66 R P ‧‧‧ i f ( i n>4 ) s c a l e=0 .w movwf (??_main+0+0+1) movlw 12 movwf (??_main+0+0+2) u60: movf (??_main+0+0).1.w movwf (??_main+0+0+1) movlw 12 movwf (??_main+0+0+2) u60: movf (??_main+0+0). In the same way. it is arranging them in conceptual containers.class=BANK0.w movwf fsr0 linker In this analogy. 3 bytes @ 0x0 PSECT bssBANK0. it is just putting them into containers in the warehouse. This analogy is not concerned with what happens outside the warehouse.C Language Features 5. and the packing machine. DS52053B-page 223 .@ 0x0 global ?___ftmul ?___ftmul: .class=BANK0. the linker is not actually placing sections in the device’s memory.@ 0x0 global ___ftmul@f1 ___ftmul@f1: . code generator PSECT cstackBANK0.2. The following sections detail points relevant at different stages of the process.  2012 Microchip Technology Inc.class=CODE movlw (?_barrr2)&0ffh movwf fsr0 movlw (?_srv)&0ffh movwf (??_main+0+0) movf fsr0. Orders arrive at the warehouse randomly.w PSECT text. An order from a customer may be for any number of components. which turns the C code into assembly code. i n t g e t D a t ( v o i d ){ .15.1 Orders and Source Code Both the warehouse and compiler take descriptions of something and use this to produce the final product: The warehouse receives orders. each C definition may require few or many assembly instructions or directives to be produced.space=1 global __pcstackBANK0 __pcstackBANK0: global ?___ftge ?___ftge: . Source code (variables and functions) can also be written in any order. The packing machine is not actually delivering the bundles of boxes. 5. The robot is akin to the compiler’s code generator application. In the same way. which is responsible for arranging how everything will appear in memory.space=1 global __pbssCOMMON __pbssCOMMON: _c: ds 1 _more: ds 8 PSECT text.class=CODE fcall _srv movlw (?_barrr2)&0ffh movwf fsr0 movlw (?_srv)&0ffh movwf (??_main+0+0) movf fsr0.

MPLAB® XC8 C Compiler User’s Guide
5.15.1.2.2 Boxes, Labels and Sections In our analogy, the components for each order are placed in a box. In the same way, the assembly output generated is also placed into boxes, called program sections (or psects, for short). There are several reasons why code is placed in a section. • • • • • The generated assembly code is more manageable. The ordering of the code sequence within the section is preserved. The ordering of sections with the same name are preserved. Code is easily sorted based on where it needs to reside in memory. Only one command is required to locate an entire section into memory.

Any code sequence that must be contiguous is placed in the one section. The output of the compiler will typically appear in many different sections, but all sections with the same name will collate in the order in which they are produced. The compiler has a list of section names and chooses a section based on the code it is generating, see 5.15.2 “Compiler-Generated Psects”. A section is not a physical box, but rather a special directive is used in the assembly code to define the start of each section. The directive signifies the end of the previous box and the start of a new box. A section can hold any amount of assembly code and can even be empty. Both the warehouse boxes and compiler sections are labeled and in both instances, the label indicates a destination rather than the contents. In Figure 5-4 color is used to identify the destination city of a box, or the name of a section. Figure 5-5 shows what a typical box label might look like. The packing machine in the warehouse is only concerned with packing boxes in containers and so, other than the city and country, the customer’s actual address is not important here. FIGURE 5-5: A TYPICAL BOX LABEL

BOX paris,country=FRANCE,fragile
Figure 5-6 shows an example of the assembly directive that is used to start a new section. The city name is now a section name and the destination country a linker class. FIGURE 5-6: THE SECTION DIRECTIVE AS A BOX LABEL
the name of this box special packing instructions for this box

PSECT bss0,class=BANK0,space=1,reloc=4
close the previous box, start a new box the container this box must be packed in

DS52053B-page 224

 2012 Microchip Technology Inc.

C Language Features
5.15.1.2.3 Down the Conveyor Belt and Object files Once the robot has assembled an order and placed the components in a box, the contents of the box are no longer relevant, and the remaining activities in the warehouse only deal with boxes. It is a similar situation in the compiler: Once assembly code has been placed into a section, the instructions are no longer relevant during the link process. The linker only handles sections and is oblivious to each section’s contents.1 5.15.1.2.4 Sorting Boxes and Sections In the warehouse, all the boxes are sorted by destination city. Once the day’s orders have been processed, all these similar boxes are wrapped so they can be easily kept together. The concept is the same in the compiler domain: Sections are sorted based on the section’s name, and are merged into one larger section by the linker. The order in which the sections come together strictly follows the order in which they are produced. 5.15.1.2.5 Loading the Containers and Classes In the warehouse, the bundled boxes are loaded into the shipping containers. One or more shipping containers will be provided for each country. If there are orders for more than one city in the same country, then the bundled boxes for those cities can share the same container (as long as there is room). The linker does a similar thing: It arranges the collated sections in the classes. Typically, several sections are placed in each class. The classes represent the device memory, but might take into account addressing modes or banking/paging restrictions present in the target device. Classes are often smaller than the memory space in which they are theoretically located. Think of a large cargo ship. Although the ship may be very long, the biggest object it can hold is determined by the size of the shipping containers it transports. The shipping company may not be able to carry an item due to size constraints even though the item is a fraction the size of the vessel. 5.15.1.3 SECTIONS AT WORK

Now that we have a basic understanding of the concepts, let’s work through a simple example to help see how these work when compiling. An engineer has written a program. Exactly what it does or how it is written is not important. The target device has only one bank of RAM and one page of flash. In our very simplified example, the compiler will choose from the sections listed in Table 5-15. This table also shows the linker class associated with each section and the memory location in the device the class represents.

1.Inside the compiler there are actually a few steps between the code generator and linker. Assembly code is first passed to the assembler; however, the object files produced, and which are passed to the linker, preserve all the sections and can be ignored in this exercise. The assembler optimizer can change alter assembly instructions, but this is only after reading and interpreting the code – something the linker cannot do. Modified code is still functionally identical to the original. Other optimizations can further merge or split sections, but this is not important in a basic understanding of the concepts.

 2012 Microchip Technology Inc.

DS52053B-page 225

MPLAB® XC8 C Compiler User’s Guide
TABLE 5-15:
Section name text bss0 data0 idata

SECTION NAMES FOR OUR SIMPLE EXAMPLE
Contents Executable code Variables that need to be cleared Variables that need to be initialized Initialized variable’s values Linker class CODE BANK0 BANK0 CODE Memory location Flash RAM RAM Flash

The code generator starts to read the program description in C and produces the assembly code required to implement this on the target device. The first thing the code generator encounters is the C definition for a variable with no initial value. All variables like this will be kept together so that clearing them at startup will be easier and more efficient. The code generator outputs the directive that starts a new section. Its internal table of section names indicates that bss0 is the appropriate choice and that this section is placed in the BANK0 class. The directive looks like this.
PSECT bss0,class=BANK0

Code follows this directive to define the variable: It merely consists of a label and another directive to reserve the required amount of memory. Altogether, this might look like:
PSECT bss0,class=BANK0 myVariable: DS 2 ; reserve 2 bytes for this object

The code generator continues and sees yet another uninitialized variable. As this variable will also use the same section, the code generator can keep adding to the current section and so immediately outputs another label and directive to reserve memory for the second variable. Now a function definition is encountered in the C source. The code generator sees that output now needs to be placed in the text section and outputs the following directive.
PSECT text,class=CODE

This directive ends the bss0 section and starts the text section. Any code following will be contained in the text section. Code associated with the function is generated and placed into this section. Moving on, the code generator encounters a variable which is initialized with a value. These variables will have their initial values stored in flash and copied as a block into the RAM space allocated to them. By using one section for the RAM image and another for the initial values, the compiler can ensure that all the initial values will align after linking, as the sections will be collated in order. The compiler first outputs the directive for the section with the name data0. It then outputs a label and directive to reserve memory for the variable in RAM. It next changes to the idata section which will hold all the initial values. Code is output that will place the initial value in this section. Notice that the code associated with initialized variables is output into two separate sections.
PSECT data0,class=BANK0 _StartCount: DS 2 ; space in RAM for the variable PSECT idata,class=CODE DB 012h ;initial values places as bytes DB 034h ; which will be copied to RAM later

The code generator reads yet another initialized variable. It selects the data0 section, outputs the label and memory reservation directive, then selects the idata section and stores the initial value.

DS52053B-page 226

 2012 Microchip Technology Inc.

C Language Features
This process continues until all the program has been generated. The output is passed to the linker (via the assembler) which then looks for the sections it contains. The linker sorts each section as it is encountered. All text sections are collated, as well as the bss0, data0 and idata sections. The order in which they will be assembled will match the order in which they are passed to the linker, which in turn will be the order in which they were produced by the code generator. There is now one collated text, bss0, data0 and idata section. These sections are now located in memory. The linker is passed options (from the compiler driver) which define the linker classes and the memory ranges they represent, see Section 7.2.1 “-Aclass =low-high,...”1. For our device, the linker options might look like this.
-ACODE=0-7ffh -ABANK0=20h-6fh

So for example, the BANK0 class covers memory from 20h to 6fh. You can see all the options passed to the linker in the map file, see Section 7.4 “Map Files”. The linker “fits” each section into the memory associated with the class it is associated with. It might, for example, place the text section at address 0 in the CODE class, then immediately follow it with the idata section at address 374h, for example. The bss0 and data0 sections will similarly be placed in the BANK0 class. All the sections are now allocated an address within a class. The addresses of symbols can now be determined and ultimately a hex file is produced. The compiler’s job is over. 5.15.1.4 MORE ADVANCED TOPICS

Let’s look at more complex issues with linking now that we understand the basics. 5.15.1.4.1 Allocation at Specific Locations We have seen in the preceding analogy that the linker places sections in their corresponding class when it comes time to determine where they will live in memory. This is how most sections are linked, but there are some exceptions. Code to be executed on Reset or an interrupt are examples. They cannot just be placed anywhere in a class; they must be located at specific addresses. So how are these positioned by the linker? Any code that is to be linked at a particular address is placed in a section in the usual way. These sections will even have a class associated with them, but allocation anywhere in this class can be overridden by a special linker option which tells the linker to place the section at a specific address. In terms of our previous analogy, think of the special linker options as being explicit instructions given to the packing machine as to where in a container to place the box. We will see in the next example the linker options to place a section explicitly.
-preset_vec=0h -pint_text=04h

Note that if a section is linked in this way, the linker will follow these instructions strictly. It will warn if it is asked to place a section over the top of another, but since there is no container, which essentially represents a memory range, the linker cannot check for sections extending past the device’s memory limits. 5.15.1.4.2 Where Classes and Containers Differ Containers and linker classes differ in one important aspect: Linker classes are conceptual and merely represent the memory of a device; they are not physical storage.

1.Remember these are linker options and you cannot pass these straight to the compiler driver. You can, however, encapsulate these options in the driver’s -L- options, see Section 4.8.7 “-L-: Adjust Linker Options Directly”.

 2012 Microchip Technology Inc.

DS52053B-page 227

MPLAB® XC8 C Compiler User’s Guide
The compiler can, and often does, use more than one class to represent the same memory range. This is illustrated in Section 5.15.1.5 “More Advanced Sections at Work” where the example uses CODE and CONST classes for flash memory. Although classes may cover the same range, typically the size of the containers vary. This allows code with different restrictions and requirements to be accommodated. When the memory ranges of classes overlap, allocating to one will also mark as being used memory from the other. In fact, when any memory is allocated by the linker by whatever means, it checks each class to see if it covers this memory and marks it as being used. This is quite a difference concept to physical containers. 5.15.1.4.3 Multi-bin containers Linker classes usually define one memory range, but there are instances where a class defines multiple memory ranges. You can think of this as several separate containers, but all with identical shipping destinations. Memory ranges in the class do not need to be contiguous. The compiler typically uses a multi-range class to represent program memory that is paged. The boundaries in the memory ranges coincide with the page boundaries. This prevents sections from crossing a page boundary. The compiler could use a similar class for banked RAM, but code can be considerably reduced in size if the destination bank of each variable is known by the code generator. You will usually see a separate class defined for each bank, and dedicated sections that are associated with these classes. The code generator will allocate a bank for each variable and choose a section destined for the class that represents that bank. 5.15.1.5 MORE ADVANCED SECTIONS AT WORK

Let’s build on the previous example. Our target device now has two banks of RAM and two pages of flash, and Table 5-16 shows the extended list of sections the compiler now uses. These sections reference new classes, also shown in the table. TABLE 5-16:
Section name textn bss0 bss1 data0 idata reset_vec const init int_text

SECTION NAMES FOR OUR EXTENDED EXAMPLE
Contents Executable code Variables that need to be cleared Variables that need to be cleared Variables that need to be initialized Initialized variable’s values Code associated with Reset Read-only variables Runtime startup code Interrupt function code Linker class CODE BANK0 BANK1 BANK0 CODE CODE CONST CODE CODE Memory location Flash RAM RAM RAM Flash Flash Flash Flash Flash

The compiler operates as it did in the previous example, selecting and producing a section directive prior to generating the assembly code associated with the C source currently being compiled.

DS52053B-page 228

 2012 Microchip Technology Inc.

C Language Features
The assembly code associated with ordinary functions is still placed in a “text” section, but as there are now two pages of flash, we have to ensure that both pages can be used. If each function was placed into the same section, they will be merged by the linker and that section would grow until it is too large to fit into either page. To ensure that all the “text” sections do not merge, each function is placed in its own unique numbered section: text0, text1, text2, etc. As these sections do not have the same name, they will not be merged by the linker. The linker option to define the CODE class might now look like:
-ACODE=0-7ffhx2

which tells the linker that CODE represents two pages of memory: one from 0 to 7ffh and another from 800h to fffh. This specification indicates that there is some sort of memory boundary that occurs at address 800h (the devices internal memory page) and is very different to a class definition that reads -ACODE=0-fffh, which covers the same memory range, but which does not have the boundary. The linker will try allocating each textx section to one page (class memory range); if it does not fit, it will try the other. If an interrupt function is encountered, the int_text section is selected for this code. As this is separate to the sections used to hold ordinary functions, it can be linked explicitly at the interrupt vector location. Assuming that the interrupt vector is at address 4, the linker option to locate this section might look like the following, see Section 7.2.19 “-Pspec”.
-pint_text=4h

For simplicity in this example, initialized variables are treated as they were in the previous example, even though there are now two RAM banks; i.e., they are always allocated in the first bank of RAM. In the previous example we ignored the code that would have copied the initial values from flash into RAM. This code is executed after Reset and before the function main, and forms part of the runtime startup code. It reads each initial value from flash and writes this to the corresponding variable in the RAM space. Provided the order in which the variables are allocated memory in RAM matches the order their initial values are allocated in flash, a single loop can be used to perform the copy. Even though the variables might be defined at many places in the source code, the order in memory of each variable and value will be preserved since the compiler uses sections to hold the code associated with each. This runtime startup code is output into a section called init. Code which jumps to the runtime startup codes is placed in the reset_vec section, which is linked to the Reset location. By linking these sections in the same page, the jump from one section to another will be shorter and faster. The linker options to make this happen might look like:
-preset_vec=0 -pinit=int_text

which says that the Reset vector code is linked to address 0 (which is the Reset vector location) and that the init section, which contains the runtime startup code, should be linked immediately after the interrupt code in the int_text section. If the int_text section is empty; i.e., there is no interrupt code defined in the program, then init will be placed at address 4.

 2012 Microchip Technology Inc.

DS52053B-page 229

MPLAB® XC8 C Compiler User’s Guide
Previously all uninitialized variables were placed in the bss0 section. Now the code generator first checks that there will actually be enough room in bank 0 memory before doing so. If not, it chooses the bss1 section that will ultimately be linked into bank 1 memory. The code generator keeps track of any object allocated to RAM so it can maintain the amount of free memory in each RAM bank. For these variables, the linker allocates the sections to memory, but it is the code generator that decides which section will be used by each variable. Thus, both applications play a part in the memory allocation process. In this example, we also consider const variables which are stored in flash, not RAM. Each byte of data is encapsulated in a RETLW instruction that return the byte in the W register. Code is needed to access each byte of a variable or array. One way of doing this is a “computed goto” which involves loading the W register with an offset into the block of data and adding this to the PC.(The Microchip application note AN556 has examples of how this can be done for several devices.) A computed goto requires that the destination address (the result of adding W and PC) must not cross over a 256 word boundary (i.e., the addresses 100h, 200h, 300h, etc.). This requirement can be met using sections and a class. In this example a new class, called CONST, is created and defined as follows
-ACONST=0-0ffhx16

which is to say that CONST is a container 100h long, but there are 16 of them one after the other in memory, so 0-ffh is one container, 100-1ffh is another, etc. We have the compiler place all the RETLW instructions and the computed goto code into the const section, which are linked into this class. The section can be located in any of the 16 containers, but must fit entirely within one. In this example, the compiler only allows one block of const data. It could be made to allow many by having each block of const data in a unique numbered section as we did for the text sections (e.g., const1, const2, etc.). Thus each sections could remain independent and be allocated to any memory bin of the CONST class. 5.15.1.6 EXPLAINING COMMON LINKER ERRORS AND PROBLEMS

We can also use our knowledge to help explain some common linker problems and error messages. 5.15.1.6.1 Not Finding Space A common linker error is, “can’t find x words for psect ’abc’ in class ’XYZ’,” which we can now think of as, “can’t find 3 cubic feet for the boxes ’paris’ in container ’FRANCE’.” The most obvious reason for this error is that the containers have been steadily filling and have finally run out of free space, i.e., the total amount of code or data you need to store exceeds the amount of memory on the device. Another reason is that a box is larger than the container(s) in which it has to be placed. If this is the case, the section will never fit, even if the entire memory space is empty. This situation might occur when defining a very large C function, RAM or const array resulting in an abnormally large section. Other possible sources include large switch statements or even a switch with too many case labels.

DS52053B-page 230

 2012 Microchip Technology Inc.

C Language Features
The hold of a ship or aircraft might be a very large space, but freight is always packed into shipping containers and it is the size of the shipping container that dictates the maximum size of a object that can be transported. In the same way, the total amount of memory on a target device is irrelevant if sections must first be allocated to a class. Classes may seem restrictive, but without them, code will typically be less efficient or may simply fail to work altogether. The computed goto is a good example. If the table of instructions in a computed goto crosses a 100h boundary, it will fail due to the limited jump range of the instruction set. This space error may also occur if there are many free spaces remaining in containers, but none are large enough to hold the section. This can be confusing since the total amount of free space may be larger than the section to be placed. In the same way that boxes cannot be removed from a bundle or unpacked, if a section does not fit into any remaining space, it cannot be split by the linker and an error will result. The error message indicates that largest free space that is still available. In the same way that the label on a box may indicate special packing instructions, e.g., “fragile – pack at the top of the container”, or “this way up”, etc, a section can also indicate special memory allocation instructions. One of the most common requirements is that a section must start on an address boundary, see the reloc PSECT flag in Section 6.4.9.3.11 “Reloc”. If a section has to fit into a class, but also has to be aligned on an address, this makes it much more difficult to locate and increases the chance that this error is produced. This is also the case if other sections or objects have been placed in the middle of a container, as we saw in Section 5.15.1.4.1 “Allocation at Specific Locations”. 5.15.1.6.2 Not Being Shipped in the Right Container Clearly, boxes will not be delivered correctly if they are placed in the wrong container. So too, code may not run if it is placed in the wrong class or address. The compiler will always ensure that code and data is allocated correctly, but it is possible to manually change linker options. The code generator assumes that sections will be located in certain memory areas and the code it generates may rely on this being the case. Typically, sections placed in RAM must remain in the bank in which they were originally destined. Sections containing executable code maybe more forgiving, but some have very specific requirements. Remember, the linker will allow any allocation you indicate; it has no way of checking if what you tell it is correct. Always take care if you override linker options and reposition a section. Section 5.15.2 “Compiler-Generated Psects” lists the common sections used by the compiler. it also indicates restrictions on how these sections may be linked. 5.15.1.6.3 Doing Things by Hand So far we have discussed assembly code produced by the code generator and how it is linked into memory; now, we consider hand-written assembly. Imagine that in the warehouse an order is not processed by the robot, but by a human worker. The components ordered are assembled by hand, packed in a box by hand and then placed on the conveyor belt along with those boxes packed by the robot. This is quite similar to when there is hand-written assembly code in a project: the linker is passed a number of sections, some created by the code generator and some by a human. Mistakes can be made by the warehouse worker or the assembly programmer. In the warehouse, the worker might not use a box and place the components loose on the conveyor belt, or a box might be used but it is not labelled, or it might be labelled incorrectly. In the compiler’s domain, assembly code may be written without a section, or it is in a section but with the wrong (or no) class, or the section may have incorrect allocation instructions.

 2012 Microchip Technology Inc.

DS52053B-page 231

MPLAB® XC8 C Compiler User’s Guide
If assembly code is not in a section, the compiler will actually place it into a default section. But since there are no specific instructions as to what to do with this section, it could be linked anywhere. Such sections are like boxes labelled “ship to anywhere you want”. As a rule of thumb, put all assembly code inside a section, but some directives (e.g., GLOBAL or EQU) do not generate code and can be placed anywhere. The easiest way to write and locate hand-written assembly code is to associate the section you create with an existing linker class that represents a suitable memory area. This means the default linker options do not need to be altered. The association is made using the class flag of the PSECT directive, see Section 6.4.9.3.3 “Class”. If a section is to be placed at an explicit address rather than having it placed anywhere in a class, the class flag should still be used. A list of linker classes and the memory they represent is given in Section 5.15.3 “Default Linker Classes”. Even if you place your code into a section and use an appropriate class, other flags may be necessary to correctly link the code. The most important section flags are the delta, see Section 6.4.9.3.4 “Delta”, reloc, see Section 6.4.9.3.11 “Reloc” and space, see 6.4.9.3.13 “Space” flags. If these are incorrectly specified, the code not be positioned correctly and will almost certainly fail.

5.15.2

Compiler-Generated Psects

The code generator places code and data into psects (program sections) with standard names, which are subsequent positioned by the default linker options. The linker does not treat these compiler-generated psects any differently to a psect that has been defined by yourself. A psect can be created in assembly code by using the PSECT assembler directive (see Section 6.4.9.3 “PSECT”). The code generator uses this directive to direct assembly code it produces into the appropriate psect. For an introductory guide to psects, see Section 5.15.1 “Program Sections”. Some psects, in particular the data memory psects, use special naming conventions. For example, take the bss psect. The name bss is historical. It holds uninitialized variables. However, there may be some uninitialized variables that will need to be located in bank 0 data memory; others may need to be located in bank 1 memory. As these two groups of variables will need to be placed into different memory banks, they will need to be in separate psects so they can be independently controlled by the linker. In addition, the uninitialized variables that are bit variables need to be treated specially so they need their own psect. So there are a number of different psects that all use the same base name, but which have prefixes and suffixes to make them unique. The general form of these psect names is:
[bit]psectBaseNameCLASS[div]

where psectBaseName is the base name of the psect, such as bss. The CLASS is a name derived from the linker class (see Section 7.2.1 “-Aclass =low-high,...”) in which the psect will be linked, e.g., BANK0. The prefix bit is used if the psect holds bit variables. So there may be psects like: bssBANK0, bssBANK1 and bitbssBANK0 defined by the compiler to hold the uninitialized variables. If locations in a bank are reserved or are taken up by absolute objects for example, a psect cannot be formed over the entire bank. Instead, a separate psect will be used to represent the free memory on either side of the used memory. The letters l (elle) and h are used as the div field in the psect name to indicate if it is the lower or higher division. Thus you might see bssBANK0l and bssBANK0h psects if a split took place. If you are unsure which psect holds an object or code in your project, check the assembly list file (see Section 6.6.1 “General Format” The contents of these psects are described below, listed by psect base name.

DS52053B-page 232

 2012 Microchip Technology Inc.

C Language Features
5.15.2.1 PROGRAM SPACE PSECTS checksum This is a psect that is used to mark the position of a checksum that has been requested using the --CHECKSUM option, see Section 4.8.17 “--ASMLIST: Generate Assembler List Files”. The checksum value is added after the linker has executed so you will not see the contents of this psect in the assembly list file, nor specific information in the map file. Linking this psect at a non-default location will have no effect on where the checksum is stored, although the map file will indicate it located at the new address. Do not change the default linker options relating to this psect. cinit Used by the C initialization runtime startup code. Code in this psect is output by the code generator along with the generated code for the C program and does not appear in the runtime startup assembly module. This psect can be linked anywhere within a program memory page, provided it does not interfere with the requirements of other psects. config Used to store the configuration words. This psect must be stored in a special location in the HEX file. Do not change the default linker options relating to this psect. const These PIC18-only psects hold objects that are declared const and string literals which are not modifiable. It is used when the total amount of const data in a program exceeds 64k. This psect can be linked anywhere within a program memory page, provided it does not interfere with the requirements of other psects. eeprom (PIC18: eeprom_data) Used to store initial values in the EEPROM memory. Do not change the default linker options relating to this psect. idata These psects contain the ROM image of any initialized variables. These psects are copied into the data psects at startup. In this case, the class name is used to describe the class of the corresponding RAM-based data psect. These psects will be stored in program memory, not the data memory space. These psects are implicitly linked to a location that is anywhere within the CODE linker class. The linker options can be changed allowing this psect to be placed at any address within a program memory page, provided it does not interfere with the requirements of other psects. idloc Used to store the ID location words. This psect must be stored in a special location in the HEX file. Do not change the default linker options relating to this psect. init Used by assembly code in the runtime startup assembly module. The code in this and the cinit define the runtime startup code. PIC18 devices also use an end_init psect, which contains the code which transfers control to the main function. If no interrupt code is defined code from the Reset vector may “fall through” into this psect. It is recommended that the default linker options relating to this psect are not changed in case this situation is in effect. intcode, intcodelo Are the psects which contains the executable code for the high-priority (default) and low-priority interrupt service routines, respectively. These psects are linked to interrupt vector at address 0x8 and 0x18, respectively. Do not change the default linker options relating to these psects. See Section 4.8.22 “--CODEOFFSET: Offset Program Code to Address” if you want to move code when using a bootloader.

 2012 Microchip Technology Inc.

DS52053B-page 233

smallconst These psects hold objects that are declared const and string literals which are not modifiable. Used when the total amount of const data in a program exceeds 255 bytes. Used when the total amount of const data in a program is less than 255 bytes. Do not change the default linker options relating to this psect as it must be linked to the Reset vector location of the target device. provided it does not interfere with the requirements of other psects. Do not change the default linker options relating to this psect. This psect is linked into ROM. the location of the psect must be above the highest RAM address. reset_vec This psect contains code associated with the Reset vector. the location of the psect must be above the highest RAM address. (PIC18 devices use the intcode psects. maintext This psect will contain the assembly code for the main() function. Do not change the default linker options relating to this psect. this is a psect used to store jump addresses and function return values. This psect can be linked anywhere in the lower 64k of program memory. See the --CODEOFFSET option Section 4. provided it does not cross a 0x100 boundary or interfere with the requirements of other psects. The code for main() is segregated as it contains the program entry point. This psect can be linked anywhere in the program memory. . See the --CODEOFFSET option Section 4. but does not exceed 64k. Do not change the default linker options relating to this psect as it must be linked to the Reset vector location of the target device. reset_wrap For baseline PIC devices.MPLAB® XC8 C Compiler User’s Guide intentry Contains the entry code for the interrupt service routine which is linked to the interrupt vector. this psect contains code which is executed after the device PC has wrapped around to address 0x0 from the oscillator calibration location at the top of program memory. This psect can be linked anywhere in the program memory.8. Do not change the default linker options relating to this psect.) This psect must be linked at the interrupt vector. For PIC18 devices. Do not change the default linker options relating to this psect as the runtime startup code may “fall through” into this psect which requires that it be linked immediately after this code. DS52053B-page 234  2012 Microchip Technology Inc. strings The strings psect is used for const objects. provided it does not cross a 0x100 boundary and it does not interfere with the requirements of other psects. This code saves the necessary registers and jumps to the main interrupt code in the case of mid-range devices. It also includes all unnamed string literals. powerup Contains executable code for a user-supplied power-up routine. For PIC18 devices.22 “--CODEOFFSET: Offset Program Code to Address” if you want to move code when using a bootloader. since the contents do not need to be modified.8.22 “--CODEOFFSET: Offset Program Code to Address” if you want to move code when using a bootloader. for enhanced mid-range devices this psect will contain the interrupt function body. mediumconst These PIC18-only psects hold objects that are declared const and string literals which are not modifiable. jmp_tab Only used for the baseline processors.

 2012 Microchip Technology Inc. They are not cleared or otherwise modified at startup.5.e. DS52053B-page 235 . These psects may be linked anywhere in their targeted memory bank and should not overlap any common (unbanked memory) that the device supports if it is a banked psect. xxx will be the assembly symbol associated with the function. code associated with it will appear in the psect called _rv_text. data These psects contain the RAM image of any initialized variables.. i.C Language Features stringtext The stringtext psect is used for const objects when compiling for baseline devices. This psect is linked into ROM. These psects may be linked anywhere in their targeted memory bank and should not overlap any common (unbanked memory) that the device supports if it is a banked psect. the linker options that position them should not be changed.2. textn These psects (where n is a decimal number) contain all other executable code that does not require a special link location.2 DATA SPACE PSECTS nv These psects are used to store variables qualified persistent. xxx_text Defines the psect for a function that has been made absolute. These psects may be linked anywhere in their targeted memory bank and should not overlap any common (unbanked memory) that the device supports if it is a banked psect. These psects can be linked anywhere in the program memory. On the stack are auto and parameter variables for the entire program. 5.4 “Absolute Variables” for information on the compiled stack. As these psects are already placed at the address indicated in the C source code. provided they does not interfere with the requirements of other psects. bss These psects contain any uninitialized variables. cstack These psects contain the compiled stack. See 5. since the contents do not need to be modified.15. This psect must be linked within the first half of each program memory page. For example if the function rv() is made absolute. placed at an address. These psects may be linked anywhere in their targeted memory bank and should not overlap any common (unbanked memory) that the device supports if it is a banked psect.

a psect may be explicitly placed into a class using a linker option. Classes may represent a single memory range.19 “-Pspec”. STRCODE defines a single memory range that covers the entire program memory. It is useful for psects whose content can appear in any page and can cross page boundaries.8.49 “--ROM: Adjust ROM Ranges” and Section 4. it is useful for psects whose contents cannot span a 0x100 word boundary. it is useful for psects whose contents cannot span a 0x100 word boundary... When specifying a debugger. Not all classes may be present for each device. This is to accommodate psects whose contents were compiled under assumptions about where they would be located in memory. Thus. see Section 4. Memory allocated from one class will also be reserved from other classes that specify the same memory. For an introductory guide to psects and linker classes. it can only be used by code that is accessed via a jump table. To the linker.” passed to the linker by the compiler driver. it is typically used for psects containing executable code. see Section 5. each 0x100 words long and aligned on a 0x100 boundary.23 “--DEBUGGER: Select Debugger Type”.1 “Program Sections”.3 Default Linker Classes The linker uses classes to represent memory ranges.3. On baseline devices. Alternatively. The classes are defined by linker options. it is useful for psects whose contents cannot span a 0x100 word boundary. Thus. Never change or remove address boundaries specified by a class definition option.1 PROGRAM MEMORY CLASSES CODE consists of ranges that map to the pages on the target device.15. there is no significance to a class name or the memory it defines. the address where one range ends and the other begins forms a boundary and psects placed in the class can never cross such boundaries. see Section 4. STRING consists of ranges that are 0x100 words long and aligned on a 0x100 boundary. CONST consists of ranges that are 0x100 words long and aligned on a 0x100 boundary. but will be divided into different ranges and have different boundaries. 5. ENTRY is used mainly by baseline devices for psects containing executable code that is accessed via a CALL instruction (calls can only be to the first half of a page). see Section 7. memory may also be removed from the ranges associated with some classes so that this memory is not used by your program. such as an ICD.1 “-Aclass =low-high.. The class is defined in such a way that it is the size of a page. or multiple ranges.8.8. This class is also used in mid-range devices and will consist of many ranges.MPLAB® XC8 C Compiler User’s Guide 5.4.15. Memory will be subtracted from these classes if using the --ROM or --RAM options. Thus.9. Although you can manually adjust the ranges associated with a class.2. this is not recommended. see Section 6. Below are the linker classes that may be defined by the compiler. The association is made using the class flag of the PSECT directive.15. to reserve memory. .3 “Class”.48 “--RAM: Adjust RAM Ranges”. but psects it holds will be positioned so that they start in the first half of the page.3.2. Thus. see Section 7. Even if two ranges are contiguous. Psects are typically allocated space in the class they are associated with. You will see classes that cover the same addresses. DS52053B-page 236  2012 Microchip Technology Inc.

the compiler will never actually search the libraries for this symbol. However. These classes would not typically be used by programmers as they do not represent general purpose RAM. if present. 5. It is suitable for any psect whose contents are accessed using linear addressing. Thus.15. it is useful for psects that must be placed in general purpose RAM. No error will result if the symbol was present in both your source code and the library files.15. but excluding any common (unbanked) memory.4 Replacing Library Modules The MPLAB XC8 C compiler comes with a librarian. This is due to the way the compiler scans source and library files. Thus.3. LIBR.2 “Librarian”. it is useful for psects that must be placed in general-purpose banked RAM. EEDATA consists of a single range that covers the EEPROM memory of the target device. This class would typically be used for psects that contain data that is to be programmed into the EEPROM. but can be placed in any bank or the common memory.3 MISCELLANEOUS CLASSES CONFIG consists of a single range that covers the memory reserved for configuration bit data in the hex file. or variable name. IDLOC consists of a single range that covers the memory reserved for ID location data in the hex file. then the library routine will be replaced by your routine. SFRx (where x is a bank number) each consists of a single range that covers the SFR memory in that bank. This class would not typically be used by programmers as it does not represent general purpose RAM. 5. When trying to resolve a symbol (a function name. If the symbol is defined in a source file. for example) the compiler first scans all the source modules for the definition. BANKx (where x is a bank number) each consist of a single range that covers the general purpose RAM in that bank. DS52053B-page 237 .2 DATA MEMORY CLASSES RAM consist of ranges that cover all the general purpose RAM memory of the target device. ABS1 consist of ranges that cover all the general purpose RAM memory of the target device. you can easily replace a library module that is linked into your program without having to do this. which allows you to unpack a library file and replace modules with your own modified versions. See Section 8.3. BIGRAM consists of a single memory range that is designed to cover the linear data memory of enhanced mid-range devices.C Language Features 5. If you add to your project a source file which contains the definition for a routine with the same name as a library routine. but excluding any common (unbanked) memory. including any common (unbanked) memory. This class would not typically be used by programmers as it does not represent general purpose RAM. Only if it cannot resolve the symbol in these files does it then search the library files. This may not be true if a symbol is defined twice in source files and an error may result if there is a conflict in the definitions. COMMON consists of a single memory range that covers the common (unbanked) RAM.15. if present.  2012 Microchip Technology Inc. but can be placed in any bank.

then a different signature will be generated and the linker will report a signature mis-match which will alert you to the possible existence of incompatible calling conventions. the signature for a function with one char argument and a char return value would be generated. You cannot replace a C library function with an equivalent written in assembly code using the above method.obj file which associates the signature value 4217 with symbol _widget. To determine the correct value. DS52053B-page 238  2012 Microchip Technology Inc. If this directive is copied into the assembly source file which contains the _widget code. MPLAB XC8 is only likely to issue a mismatch error from the linker when the routine is either a precompiled object file or an assembly routine. it will associate the correct signature with the function and the linker will be able to check for correct argument passing. . not the linker.5 Signature Checking The compiler automatically produces signatures for all functions. This signature is generated and placed the object code whenever a function is referenced or defined. but both these applications work in the way described above in resolving library symbols.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”).4217 The SIGNAT directive tells the assembler to include a record in the . which will indicate a discrepancy between how the function is defined.15. The simplest method of determining the correct signature for a function is to write a dummy C function with the same prototype and check the assembly list file using the --ASMLIST option (see Section 4. Where a call to _widget is made in the C code. At link time. In order to match the correct signature. the source code for widget needs to contain an assembler SIGNAT directive which defines the same signature value.8. The prototype used to call this function from C would be: extern char widget(char). It is sometimes necessary to write assembly language routines which are called from C using an extern declaration. A signature is a 16-bit value computed from a combination of the function’s return data type. you would write the following code into a dummy file: char widget(char arg1) { } The resultant assembler code seen in the assembly list file includes the following line: SIGNAT _widget. If this is required. 5.MPLAB® XC8 C Compiler User’s Guide All library source code is written in C. suppose you have an assembly language routine called _widget which takes a char argument and returns a char. The value 4217 is the correct signature for a function with one char argument and a char return value. Such assembly language functions should include a signature which is compatible with the C prototype used to call them. the number of its parameters and other information affecting the calling sequence for the function. If a C source file contains the declaration: extern char widget(long). For example. the linker will report any mismatch of signatures. you will need to use the librarian to edit or create a new library file. and the p-code library files that contain these library routines are actually passed to the code generator. Other function mismatches are reported by the code generator.

the link address plus the size) is represented by the symbol __Hname. These symbols can be used in code. __LbssBANK0 is the low bound of the bssBANK0 psect.12. The highest address of a psect (i. Not all psects are assigned these symbols.  2012 Microchip Technology Inc. for example: GLOBAL __Lidata and C code could use them by declaring a symbol such as the following. Psect names may change from one device to another. For example. in particular those that are not placed in memory by a -P linker option. Note that there is only one leading underscore in the C domain. extern char * _Lidata. As the symbol represents an address.19 “-Pspec”. if required. DS52053B-page 239 . See Section 7.3.15. the load start address is represented by the symbol __Bname.2.1 “Equivalent Assembly Symbols”. If the psect has different load and link addresses. Assembly code can use these symbol by globally declaring them. The link address of a psect can be obtained from the value of a global symbol with name __Lname (two leading underscores) where name is the name of the psect. a pointer is the typical type choice.e.6 Linker-Defined Symbols The linker defines some special symbols that can be used to determine where some psects where linked in memory.. see Section 5.C Language Features 5.

.MPLAB® XC8 C Compiler User’s Guide NOTES: DS52053B-page 240  2012 Microchip Technology Inc.

assembly listing and etc. see Section 4. Note that the assembler will not produce any messages unless there are errors or warnings – there are no “assembly completed” messages. Thus you will see the terms assembly language (or just assembly). Typically the command-line driver. It is available to run on Windows. assembler directive and assembler optimizer. All command-line options are recognized in either upper or lower case. The operation and assembler directives are almost identical for both assemblers. The usage of the assembler is similar under all of available operating systems. xc8. The basic command format is shown: ASPIC[18] [ options ] files files is a space-separated list of one or more assembler source files. This chapter describes the usage of the assembler and the directives (assembler pseudo-ops and controls) accepted by the assembler in the source files.  2012 Microchip Technology Inc.53 “--SETOPTION: Set the Command-line Options For Application”.. The appropriate assembler application is invoked when you use the compiler driver to build projects. Although the term “assembler” is almost universally used to describe the tool which converts human-readable mnemonics into machine code. i. Where more than one source file is specified. no default extensions or suffixes are assumed. or when they are specified using the command-line driver option --SETOPTION. The files must be specified in full. the assembler treats them as a single module. options is an optional space-separated list of assembler options. DS52053B-page 241 . both “assembler” and “assembly” are used to describe the source code which such a tool reads. however. a single assembly will be performed on the concatenation of all the source files specified. or double dashes in the case of multi-letter options.1 INTRODUCTION Two macro assemblers are included with the MPLAB XC8 C Compiler to assemble source files for all 8-bit PIC devices. The following topics are examined in this chapter of the user’s guide: • • • • • Assembler Usage Options MPLAB XC8 Assembly Language Assembly-Level Optimizations Assembly List Files 6. The assembler options must be specified on the command line before any files. the options for the assembler are supplied here for instances where the assembler is being called directly. and ASPIC for all other 8-bit devices. Macro Assembler 6.2 ASSEMBLER USAGE The assembler is called ASPIC18 for PIC18 devices. is used to invoke the assembler as it can be passed assembler source files as input.MPLAB® XC8 C COMPILER USER’S GUIDE Chapter 6. each with a dash – as the first character in the case of single letter options. but assembler options. The latter is more common and is used in this manual to describe the language.8. Linux and Mac OS X systems.e.

3. 6.3 OPTIONS The command line options recognized by ASPIC[18] are given in Table 6-1.1 -A: Generate Assembly File An assembler file will be produced if this option is used rather than the usual object file format. DS52053B-page 242  2012 Microchip Technology Inc.opt. TABLE 6-1: Option -A -Cchipinfo -E[file | digit] -Flength -H -I -L[listfile ] -N -O -Ooutfile -R -Twidth -V -VER=version -Wlevel -X --CHIP=device --DISL=list --EDF=path --EMAX=number --OPT=optimization --VER ASPIC[18] COMMAND-LINE OPTIONS Meaning Produce assembler output Define the chipinfo file Set error destination/format Specify listing page length Output HEX values for constants List macro expansions Produce listing Disable merging optimizations Perform optimization Specify object name Specify non-standard ROM Specify listing page width Produce line number info Specify full version information for list file title Set warning level threshold No local symbols in OBJ file Specify device name Specify disabled messages Specify message file location Specify maximum number of errors Specify optimization type Print version number and stop 10 No message disabled 0 80 No line numbers 66 Decimal values Don’t list macros No listing Merging optimizations enabled No optimization srcfile. This file specifies information about the currently selected device. The chipinfo file is called picc. and a full description of each option followings.ini 6. By default the output file will an extension . unless the -Ooutfile output option is used to specify another name.obj Default Produce object code dat\picc[18].ini and can be found in the dat directory in the compiler’s installation directory. This is useful when checking the optimized assembler produced using the -O optimization option.2 -C: Specify Chip Info File Specify the chipinfo file to use.MPLAB® XC8 C Compiler User’s Guide 6. .3.

The -E option with no argument will make the assembler use an alternate format for error and warning messages. the command-line driver and the --ASMLIST driver option..3. If listfile is specified then the listing will be written to that file. see Section 4. Each page will begin with a header and title. the assembler listing output is continuous. Specifying a filename as argument will force the assembler to direct error and warning messages to a file with the name specified. The -L option is still necessary to produce an actual listing output. This option affects both the assembly list file. 6.3. The output may be formatted into pages of varying lengths.3.8 -O: Optimize Assembly This requests the assembler to perform optimization on the assembly code.5 -H: Print Hexadecimal Constant This option specifies that output constants should be shown as hexadecimal values rather than decimal values. 6. Debug information for assembler code generated from C source code may become unreliable in debuggers when this option is used. as the assembler must make an additional pass over the input code. 6. as well as assembly output. The length is specified in a number of lines.3.3.e.6 -I: List Macro Expansions This option forces listing of macro expansions and unassembled conditionals which would otherwise be suppressed by a NOLIST assembler control.3 -E: Specify Error Format/File The default format for an error message is in the form: filename: line: message where the error of type message occurred on line line of the file filename. The -F option allows a page length to be specified.3. otherwise it will be written to the standard output. 6.7 -L: Generate an Assembly Listing This option requests the generation of an assembly listing file.Macro Assembler 6. Note that the use of this option slows the assembly process down. when requested.  2012 Microchip Technology Inc. if specified. This option is applied if compiling using xc8. A zero value of length implies pageless output. i. This option can be applied if compiling using xc8.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers”. see Section 4.42 “--OPT: Invoke Compiler Optimizations”. 6. DS52053B-page 243 . the command-line driver and the --OPT driver option.4.10 “Assembler Controls”.8.4 -F: Specify Page Length By default the assembly listing format is pageless.8. see Section 6.

see Section 4. to be passed to the assembler.9 -O: Specify Output File By default the assembler determines the name of the object file to be created by stripping any suffix or extension from the first source filename and appending .38 “--MSGDISABLE: Disable Warning Messages”.e. The -O option allows the user to override the default filename and specify a new name for the object file. The device type can also be indicated by use of the device directive in the assembler source file. in characters. . including optional text to indicate beta builds or release candidate builds. This information is only used in the title of the assembly list file and is not reflected in the output to the --VER option. 6. i. This option is applied if compiling using xc8. including local symbols. See Section 4.3. 6. symbols that are neither public or external. width should be a decimal number greater than 41. This option should not be used when assembling an assembly file produced by the code generator. not the intermediate assembly code.3..12 -VER:Specify Version Information This option allows the full version information. debug information should relate back to the original C source.3.14 --CHIP: Specify Device Name This option defines the device which is being used. DS52053B-page 244  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide 6.3. thereby reducing the file size. 6.obj. This option is applied if compiling using xc8. Such information may be used by debuggers. xc8. see Section 4. to disable particular message numbers.6 “Compiler Messages” for full information about the compiler’s messaging system. In that case. Note that the line numbers will correspond with assembler code lines in the assembler file. the command-line driver and the --MSGDISABLE driver option.4.8.9.20 “PROCESSOR”.3.8. description 6. the command-line driver and the --CHIP driver option. see Section 6. You can also add your own processors to the compiler via the compiler’s chipinfo file.20 “--CHIP: Define Device”. The default width is 80 characters.3. 6.15 --DISL: Disable Messages This option is mainly used by the command-line driver. The -X option will prevent the local symbols from being included in the object file.10 -T: Specify Listing Page Width This option allows specification of the assembly list file page width.13 -X: Strip Local Symbols The object file created by the assembler contains symbol information.3.11 -V: Produce Assembly Debug Information This option will include line number and filename information in the object file produced by the assembler. 6. It takes a comma-separate list of message numbers that will be disabled during compilation.

6. See Section 4. DS52053B-page 245 . to specify the maximum number of errors that can be encountered before the assembler terminates.6 “Compiler Messages” for full information about the compiler’s messaging system.18 --OPT: Specify Optimization Type This option complements the assembler -O option and indicates specific information about optimizations required. The suboptions: speed. 6. even if other options and files are present on the command line.3.29 “--ERRORS: Maximum Number of Errors”. see Section 4.17 --EMAX: Specify Maximum Number of Errors This option is mainly used by the command-line driver. xc8. The default number is 10 errors.3.Macro Assembler 6.3. space and debug may be specified to indicate preferences related to procedural abstraction. xc8.19 --VER: Print Version Number This option prints information relating to the version and build of the assembler application. See Section 4. 6. The default file is located in the dat directory in the compiler’s installation directory.6 “Compiler Messages” for full information about the compiler’s messaging system.  2012 Microchip Technology Inc.16 --EDF: Set Message File Path This option is mainly used by the command-line driver.3. The assembler will terminate after processing this option. This option is applied if compiling using xc8. the command-line driver and the --ERRORS driver option. disabled when speed is set. to specify the path of the message description file.8. The debug suboption limits the application of some optimizations which otherwise may severely corrupt debug information used by debuggers. Abstraction is enabled when the space option is set.

and the file register is selected when using the ".1" to specify the destination for the result of that operation. The same assembler application is used for compiler-generated intermediate assembly and hand-written assembly source code. . DS52053B-page 246  2012 Microchip Technology Inc. Although the PIC17 family instruction set is supported at the assembler level. ASPIC[18] uses the more-readable operands ". and pseudo instructions that can be used in addition to the device instruction set. or the common memory prefix.4.w" operand. For example: MOVF _foo. The ". The assembler will determine from the address that access bank memory is being accessed. Additional mnemonics and assembler directives are documented in this section.c" operand indicates that the address is in the common memory. The following details changes to the instruction format.MPLAB® XC8 C Compiler User’s Guide 6. the code generator cannot produce code for these devices so no C projects can target these devices.4. The assembler also uses the destination select operand ". These operands and prefix affect the RAM access bit in the instruction.3 If the instruction does not specify a destination select operand. The W register is selected as the destination when using the ". the common memory destination selectors ". 6.c BTFSC c:_foo. These operands and prefix are not applicable with operands to the MOVFF instruction.b" to indicate that PIC18 instructions should use the bank select register (BSR) when accessing the specified file register address. the instruction will used banked access.f" operand or if no destination operand is specified.f destination is optional The numerical destination operands cannot be used with ASPIC[18].1 Assembly Instruction Deviations The MPLAB XC8 assembler uses a slightly modified form of assembly language to that specified by the Microchip data sheets.1. which is known as the access bank on PIC18 devices. All opcode mnemonics and operand syntax are specific to the target device. is described below.4 MPLAB XC8 ASSEMBLY LANGUAGE The source language accepted by the macro assembler. These deviations can be used in assembly code in-line with C code or in hand-written assembly modules.w ADDWF _foo.f" to specify the destination register. an operand may be preceded by the characters "c:" to indicate that the address resides in common memory. The case of the letter in the destination operand in not important. 6.0" or ". which takes two untruncated addresses and which always works independently of the BSR.1 DESTINATION LOCATION Certain PIC instructions use the operands ". ASPIC[18].f . Alternatively. If an instruction address is absolute and the address is within the access bank.c" or "c:" are not required.the . For example: ADDWF _foo.w" and ".

b MOVWF BANKMASK(_foo) . For example: MOVLW 20 BANKSEL(_foobar) MOVWF _foobar&07fh .shadow registers copied .defaults to banked access Notice that first two instruction have the RAM access bit (bit 8 of the op-code) cleared. or use a MOVLP instruction in the case of enhanced mid-range PIC devices. The op codes for these instructions. an absolute location and then to an address represented by an identifier. 6EE5 6E55 0105 6F16 6F16 MOVWF 0FE5h MOVWF _bar.  2012 Microchip Technology Inc. are shown.write to access bank location 0xFE5 . assuming that the address assigned to _foo is 0x516 and to _bar is 0x55. For example: FCALL _getInput PAGESEL $ . the PAGESEL pseudo instruction can be used to generate code to select the page of the address operand. This replaces the "0" and "1" operands indicated in the device data sheet.c BANKSEL(_foo) MOVWF BANKMASK(_foo). As the directive could expand to more than one instruction. 0011 0010 RETFIE f RETFIE .1. Depending on the target device.2 BANK AND PAGE SELECTION The BANKSEL pseudo instruction can be used to generate instructions to select the bank of the operand specified. the generated code will either contain one or more instructions to set/clear bits in the appropriate register.Macro Assembler For example. For the current page. The following examples show both forms and the opcodes they generate.select bank for next file instruction .write data and mask address In the same way.write to access bank location 0x55 .return without copy The baseline and mid-range devices do not allow such a syntax. Depending on the target device.set up BSR to access _foo . The operand should be the symbol or address of an object that resides in the data memory.4. 6. you can use the location counter. but that it is set in the last two instructions.1.3 INTERRUPT RETURN MODE The RETFIE PIC18 instruction may be followed by "f" (no comma) to indicate that the shadow registers should be retrieved and copied to their corresponding registers on execution. Support is purely to allow easy migration across the 8-bit devices. $.4. 6. the generated code will either contain one or more bit instructions to set/clear bits in the appropriate register. the following instructions show the W register being moved to first. DS52053B-page 247 . it should not immediately follow a BTFSX instruction. as the operand.select this page This directive is accepted when compiling for PIC18 targets but has no effect and does not generate any code.write to _foo (banked) . As this pseudo instruction can expand to more than one instruction on mid-range or baseline parts. the registers are not updated from the shadow registers. it should not immediately follow a BTFSX instruction on those devices. or use a MOVLB instruction (in the case of enhanced mid-range or PIC18 devices). Without this modifier.

. the assembler may change a relative branch instruction to be a relative branch with the opposite condition over a GOTO instruction. Bits are also set/cleared in this register after the call to reselect the page which was selected before the FCALL. This replaces the ".Whether the page selection instructions are generated. These instructions have a limited jump range compared to the GOTO instruction.g.4.5 RELATIVE BRANCHES The PIC18 devices implement conditional relative branch instructions.next may become: BNZ l18 GOTO error l18: . a previous FCALL/LJMP instruction. The mnemonics are FCALL and LJMP. a BTFSC instruction. Note that in some instance. . and immediately after.MPLAB® XC8 C Compiler User’s Guide 6. You can see that the FCALL instruction has expanded to five instructions. DS52053B-page 248  2012 Microchip Technology Inc. the additional code to set the PCLATH bits may be optimized away. 13 14 15 0079 007A 007F 3021 120A 120A 3400 158A 118A 2000 movlw fcall retlw 33 _phantom 0 Since FCALL and LJMP instructions may expand into more than one instruction.f" to indicate that the W.1. Page selection instructions may appear immediately before the call or jump. see Section 4. On PIC18 devices. but also ensure the instructions necessary to set the bits in PCLATH (for mid-range devices) or STATUS (for baseline devices) will be generated when the destination is in another page of program memory.1" syntax indicated on the device data sheet. or be generated as part of. 6. STATUS and BSR registers should be pushed to their respective shadow registers.next This is functionally identical and is performed so that the conditional branch can use the same destination range as the GOTO instruction. e. For example: BZ error . Unoptimized FCALL and LJMP instruction will always generate page selection code.42 “--OPT: Invoke Compiler Optimizations”. The following mid-range PIC example shows an FCALL instruction in the assembly list file. e.g. is dependent on the surrounding source code.. the regular CALL instruction may be followed by a ". BZ. these mnemonics are present purely for compatibility with smaller 8-bit devices and are always expanded as regular PIC18 CALL and GOTO instructions. These additional mnemonics should be used where possible as they make assembly code independent of the final position of the routines that are to be executed.4 LONG JUMPS AND CALLS The assembler recognizes several mnemonics which expand into regular PIC MCU assembly instructions. If the call or jump is determined to be within the current page. these instructions expand into regular CALL and GOTO instructions respectively.1. Note that assembly code that is added in-line with C code is never optimized and assembly modules require a specific option to enable optimization. On PIC18 devices. BNZ. and exactly where they will be located.8. In this example there are two bit instructions which set/clear bits in the PCLATH register. they should never be preceded by an instruction that can skip.4. On baseline and mid-range parts.

4 Comments An assembly comment is initiated with a semicolon that is not part of a string or character constant. comment .3 Characters The character set used is standard 7 bit ASCII.3.3. 6.4. The third format is only legal with certain assembler directives.  2012 Microchip Technology Inc. 6..2 Statement Formats Legal statement formats are shown in Table Section Table 6-2: “ASPIC[18] Statement Formats”. DS52053B-page 249 .2 SPECIAL CHARACTERS There are a few characters that are special in certain contexts.Macro Assembler 6. then it may also contain lines that form valid preprocessor directives.4. See Section 5.14. If the assembly file is first processed by the C preprocessor. The name field is mandatory and should also contain one identifier.4. comment Field2 Field3 Field4 6.11 “-P: Preprocess Assembly Files”.1 DELIMITERS All numbers and identifiers must be delimited by white space. TABLE 6-2: Format # Format 1 Format 2 Format 3 Format 4 Format 5 ASPIC[18] STATEMENT FORMATS Feild1 label: label: name . or precede a mnemonic as shown in the second format. see Section 4. the character & is used for token concatenation. Tabs are treated as equivalent to spaces. Within a macro body. comment only empty line mnemonic pseudo-op operands operands . 6. but not mnemonics and reserved words.8. non-alphanumeric characters or the end of a line.11 “-P: Preprocess Assembly Files”.1 “C Language Comments” for more information on the format for these directives. such as MACRO. should contain one identifier.4. In a macro argument list. if present. Alphabetic case is significant for identifiers. There is no limitation on what column or part of the line in which any part of the statement should appear.8. A label may appear on a line of its own. escape it by using && instead. SET and EQU.4. If the assembly file is first processed by the C preprocessor. To use the bitwise & operator within a macro body. The label field is optional and. the angle brackets < and > are used to quote macro arguments.. see Section 4. */ and // syntax. then the file may also contain C or C++ style comments using the standard /* .

4.e.g. optimizations may be made to assembler instructions before the function call which load the W register redundantly. Hexadecimal digits are accepted in either upper or lower case.4. real numbers are accepted in the usual format. These comments are typically used by the assembler optimizer. The comment string .5 6. and are interpreted as IEEE 32-bit format. In expressions. o or q Digits 0 to 9 followed by D. but the opening and closing quotes must be the same. DS52053B-page 250  2012 Microchip Technology Inc. Other radices may be specified by a trailing base specifier as given in Table 6-3. 6. d or nothing Digits 0 to 9. A to F preceded by Ox or followed by H or h ASPIC[18] NUMBERS AND BASES Format Hexadecimal numbers must have a leading digit (e..1 Constants NUMERIC CONSTANTS The assembler performs all arithmetic with signed 32-bit precision. as a lower case b is used for temporary (numeric) label backward references.. Accesses to this location which appear to be redundant will not be removed by the assembler optimizer if this string is present.wreg free is placed on some CALL instructions.4. Either single quotes ’ or double quotes " may be used. i.volatile is used to indicate that the memory location being accessed in the instruction is associated with a variable that was declared as volatile in the C source code. This comment string may also be used in hand-written assembly source to achieve the same effect for locations defined and accessed in assembly code.2 CHARACTER CONSTANTS AND STRINGS A character constant is a single character enclosed in single quotes ’. Multi-character constants.5. 6. The comment string . The string indicates that the W register was not loaded with a function parameter. it is not in use. TABLE 6-3: Radix Binary Octal Decimal Hexadecimal Digits 0 and 1 followed by B Digits 0 to 7 followed by O.4. The default radix for all numbers is 10.MPLAB® XC8 C Compiler User’s Guide 6. or strings. Q. . If this string is present. Note that a binary constant must have an upper case B following it. are a sequence of characters. not including carriage return or newline characters.5. enclosed within matching quotes.1 SPECIAL COMMENT STRINGS Several comment strings are appended to compiler-generated assembly instructions by the code generator. 0ffffh) to differentiate them from identifiers.4.

A symbol may contain any number of characters drawn from the alphabetics. nor will the assembler issue any warnings if a symbol is used in more than one context. An identifier that begins with at least one underscore character can be accessed from C code.2 ASSEMBLER-GENERATED IDENTIFIERS Where a LOCAL directive is used in a macro block.4.6.g. The instruction and addressing mode syntax provide all the information necessary for the assembler to generate correct code. _. but other than this. Thus: GOTO $ . a relative jump destination can be specified. Identifiers that do not begin with an underscore can only be accessed from the assembly domain. No special syntax is needed or provided to define the addresses of bits or any other data type. The names of psects (program sections) and ordinary symbols occupy separate. 6. keywords. The first character of an identifier may not be numeric.Macro Assembler 6. numerics and the special characters dollar. words or sports cars. the assembler will generate a unique symbol to replace each specified identifier in each expansion of that macro. Fred is not the same symbol as fred. 6.. e.1 SIGNIFICANCE OF IDENTIFIERS Users of other assemblers that attempt to implement forms of data typing for identifiers should note that this assembler attaches no significance to any symbol.endless loop will represent code that will jump to itself and form an endless loop. $.1 “Equivalent Assembly Symbols” for the mapping between the C and assembly domains. Some examples of identifiers are shown here: An_identifier an_identifier an_identifier1 $ ?$_12345 An identifier cannot be one of the assembler directives.3. This symbol expands to the address of the currently executing instruction (which is different to the address contained in the program counter (PC) register when executing this instruction). the assembler does not care whether a symbol is used to represent bytes.4.4.3 LOCATION COUNTER The current location within the active program section is accessible via the symbol $. Care must be taken with such symbols that they do not interact with C code identifiers. question mark. ? and underscore. The user should avoid defining symbols with the same form. 6.4.  2012 Microchip Technology Inc. DS52053B-page 251 . By using this symbol and an offset.6.6 Identifiers Assembly identifiers are user-defined symbols representing memory locations or numbers. and places no restrictions or expectations on the usage of a symbol. These unique symbols will have the form ??nnnn where nnnn is a 4 digit number. or psect flags.12. The case of alphabetics is significant.6. overlapping name spaces. See Section 5.

as these devices have word-addressable program memory. Labels are not assigned a value until link time. A label definition consists of any valid assembly identifier followed by a colon. or . This cannot occur with PIC18 assembly code as the colon is mandatory. Here are two examples of legitimate labels interspersed with assembly code. For example: GOTO MOVLW MOVWF $+2 8 _foo . . Regardless of how they are defined. :. GOTO $+2 will jump to the following instruction.11 “-P: Preprocess Assembly Files”. All offsets are rounded down to the nearest multiple of 2. The appropriate file can be included by add the line: #include <xc. see Section 4. Note that the colon following the label is mandatory for PIC18 assembly. the offset to this symbol represents the number of bytes from the current location. As PIC18 instructions must be word aligned.. On PIC18 devices.. which use byte addressable program memory.8. frank: MOVLW 1 GOTO fin simon44: CLRF _input Here.to here for baseline and mid-range devices will skip the MOVLW instruction on baseline or mid-range devices. Thus the code: mistake: MOVLW 23h MOVWF 37h REUTRN .MPLAB® XC8 C Compiler User’s Guide Any address offset added to $ has the native addressability of the target device.. 6. For PIC18 instructions. and simon44 the address of the CLRF instruction.e. the assembler list file produced by the assembler will always show labels on a line by themselves.skip.6.4. the offset is the number of instructions away from the current location.inc> to the assembler source file. act like a NOP instruction. the compiler would report an error when reached the line containing REUTRN. DS52053B-page 252  2012 Microchip Technology Inc.4. . These header files contain EQU declarations for all byte or multi-byte sized registers and #define macros for named bits within byte registers. which was intended to be the RETURN instruction. 6. the offset to the location counter should be a multiple of 2. Note that the file must be included using a C pre-processor directive and hence the option to preprocess assembly files must be enabled when compiling. Mistyped assembly instructions can sometimes be treated as labels without an error message being issued. So for baseline and mid-range devices.to here for PIC18 devices. oops defines a symbol called REUTRN. The definition may appear on a line by itself or be positioned before a statement.5 SYMBOLIC LABELS A label is a symbolic alias which is assigned a value equal to the current address within the current psect.6. Symbols which are not interpreted as instructions are assumed to be labels. the label frank will ultimately be assigned the address of the MOVLW instruction. but is recommended in assembly for all other devices. This header file contains appropriate commands to ensure that the header file specific for the target device is included into the source file. i.4 REGISTER SYMBOLS Code in assembly modules may gain access to the special function registers by including pre-defined assembly header files.

Like variables..1 “GLOBAL” for more information. rather than using an absolute address with other instructions.w DB inp>>8 MOVLW inp shr 2. The operators listed may all be freely combined in both constant and relocatable expressions. e.w MOVLW not 055h.4. e. They may be used by code located before their definition. The operators allowable in expressions are listed in Table 6-4.4. use the GLOBAL directive. so the results of expressions involving relocatable identifiers may not be resolved until link time. 6. +).w MOVF inp|1.  2012 Microchip Technology Inc.g. strings and operators. Expressions can be made up of numbers. labels have scope.w DB inp rol 1 DB inp ror 1 DW float24(3.g. TABLE 6-4: * + / = or eq > or gt >= or ge < or lt <= or le <> or ne low high highword mod & ^ | not << or shl >> or shr rol ror float24 nul ASPIC[18] OPERATORS Purpose Multiplication Addition Subtraction Division Equality Signed greater than Signed less than Signed less than or equal to Signed not equal to Low byte of operand High byte of operand High 16 bits of operand Modulus Bitwise AND Bitwise XOR (exclusive or) Bitwise OR Bitwise complement Shift left Shift right Rotate left Rotate right 24-bit version of real operand Tests if macro argument is null BRA $+1 DB 5-2 MOVLW 100/4 IF inp eq 66 IF inp > 40 IF inp < 40 IF inp le 66 IF inp <> 40 MOVLW low(inp) MOVLW high(1008h) DW highword(inp) MOVLW 77mod4 CLRF inp&0ffh MOVF inp^80. See Section 6. To make a label accessible in other modules.Macro Assembler Labels may be used (and are preferred) in assembly code.7 Expressions The operands to instructions and directives are comprised of expressions. By default. Thus they can be used as the target location for jump-type instructions or to load an address into a register. not) or binary (two operands. they may be used anywhere in the module in which they are defined. DS52053B-page 253 . identifiers.3) Example MOVLW 4*33..9. The linker permits relocation of complex expressions.w Operator Signed greater than or equal to IF inp ge 66 The usual rules governing the syntax of expressions apply. Operators can be unary (one operand.

or even where spread over several modules. The assembler associates no significance to the name of a psect and the linker is also not aware of which psects are compiler-generated or which are user-defined. Unless defined as abs (absolute).15.1 “Program Sections”. The PSECT assembler directive is used to define a psect. are used in a similar way to instruction mnemonics. or psects. They are a way of grouping together parts of a program (via the psect’s name) even though the source code may not be physically adjacent in the source file. For an introductory guide to psects. It takes as arguments a name and an optional comma-separated list of flags.4. 6. are simply a section of code or data. See Section 5. psects are relocatable. “Linker” has more information on the operation of the linker and on options that can be used to control psect placement in memory. these directives do not generate instructions.8 Program Sections Program sections. TABLE 6-5: Directive GLOBAL END PSECT ORG EQU SET DB DW DDW DS DABS IF ELSIF ELSE ENDIF FNCALL FNROOT MACRO ENDM LOCAL ALIGN BANKSEL ASPIC[18] ASSEMBLER DIRECTIVES Purpose Make symbols accessible to other modules or allow reference to other modules’ symbols End assembly Declare or resume program section Set location counter within current psect Define symbol value Define or re-define symbol value Define constant byte(s) Define constant word(s) Define double-width constant word(s) (PIC18 devices only) Reserve storage Define absolute storage Conditional assembly Alternate conditional assembly Alternate conditional assembly End conditional assembly Inform the linker that one function calls another Inform the linker that a function is the “root” of a call graph Macro definition End macro definition Define local tabs Align output to the specified boundary Generate code to select bank of operand DS52053B-page 254  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide 6.4. .2 “Compiler-Generated Psects” for a list of all psects that the code generator defines.9 Assembler Directives Assembler directives. A psect is identified by a name and has several attributes. and are detailed below in the following sections. DW and DDW directives place data bytes into the current psect. The DB. Code or data that is not explicitly placed into a psect will become part of the default (unnamed) psect. The directives are listed in Table 6-5. Chapter 7. With the exception of PAGESEL and BANKSEL. see Section 5. or pseudo-ops.15.

This is stored in a start record in the object file produced by the assembler. As only one start address can be specified for each project. they are made references to public symbols defined in external modules. If the symbols are defined within the current module.4. Whether this is of any use will depend on the linker. they are made public. that expression will be used to define the entry point of the program. but if present should be at the very end of the program.4. If the symbols are not defined in the current module.9.lab2. If an expression is supplied as an argument. It will terminate the assembly and not even blank lines should follow this directive. but may use the END directive with no entry point in any file.1 GLOBAL The GLOBAL directive declares a list of comma-separated symbols. you normally do not need to define this address. DS52053B-page 255 .do not define entry point  2012 Microchip Technology Inc.2 END The END directive is optional.lab3 6.Macro Assembler TABLE 6-5: Directive PAGESEL PROCESSOR REPT IRP IRPC SIGNAT ASPIC[18] ASSEMBLER DIRECTIVES (CONTINUED) Purpose Generate set/clear instruction to set PCLATH bits for this page Define the particular chip for which this file is to be assembled.defines the entry point or END . For example: END start_label . and again in the module that uses the symbol to link in with the external definition. Repeat a block of code n times Repeat a block of code with a list Repeat a block of code with a character list Define function signature 6. For example: GLOBAL lab1. Thus to use the same symbol in two modules the GLOBAL directive must be used at least twice: once in the module that defines the symbol to make that symbol public.9. The default runtime startup code defined by the compiler will contain an END directive with a start address.

size=100h. a psect name cannot be one of the assembler directives.3. not byte addresses. See also Section 6. it is to start at location 0.. . so a psect may use the same identifier as an ordinary assembly identifier.4.3 PSECT The PSECT directive declares or resumes a program section. however.3. keywords. 6. a comma-separated list of flags.2 Bit The bit flag specifies that a psect holds objects that are 1 bit long. For an introductory guide to psects.9. or psect flags. TABLE 6-6: Flag abs bit class=name delta=size global Psect is absolute Psect holds bit objects Specify class name for psect Size of an addressing unit Psect is global (default) PSECT FLAGS Meaning limit=address local merge=allow ovrld pure reloc=boundary size=max space=area split=allow with=psect Upper address limit of psect Psect is not global Allow or prevent merging of this psect Psect will overlap same psect in other modules Psect is to be read-only Start psect on specified boundary Maximum size of psect Represents area in which psect will reside Allow or prevent splitting of this psect Place psect in the same page as specified psect Some examples of the use of the PSECT directive follow: PSECT fred PSECT bill. optionally. The psect name is in a separate name space to ordinary assembly symbols. the flags need not be repeated and will be propagated from the earlier declaration.9 “Ovrld”.4.9. This does not mean that this module’s contribution to the psect will start at 0. The directive takes as argument a name and. An abs-flagged psect is not relocatable and an error will result if a linker option is issued that attempts to place such a psect at any location.4.abs.1 Abs The abs flag defines the current psect as being absolute.class=CODE.MPLAB® XC8 C Compiler User’s Guide 6.e. Such psects will have a scale value of 8 to indicate that there are 8 addressable units to each byte of storage and all addresses associated with this psect will be bit address.4 “Map Files”. then an error will be generated. i. since other modules may contribute to the same psect.delta=2 6.3.1 “Program Sections”.15. However.9. see Section 7.9. DS52053B-page 256  2012 Microchip Technology Inc.4. Once a psect has been declared it may be resumed later by another PSECT directive. The scale value is indicated in the map file. The allowed flags are listed in Table 6-6 and specify attributes of the psect.ovrld. If two PSECT directives are encountered with contradicting flags. see Section 5.global PSECT joh.

If this limit is exceeded when it is positioned in memory. A class is a range of addresses in which psects may be placed. This is the default delta value.  2012 Microchip Technology Inc. merging is only performed on code-based psects (text psects). That is to say. Class names are used to allow local psects to be located at link time.9. they reference the same psect.. 6.4.4 Delta The delta flag defines the size of the addressable unit.9. an error will be generated.6 Limit The limit flag specifies a limit on the highest address to which a psect may extend. Typically. each address in program memory requires 2 bytes of data in the HEX file to define their contents. the psect may be merged if other psect attributes allow it and the optimizer can see an advantage doing so..4. or not specified.5 Global A psect defined as global will be combined with other global psects with the same name at link time.4..3.2. even one in another module. Where there are two local psects in the one module.3. unless the local flag is used.4. the program memory space is word addressable. hence psects in this space must use a delta of 1.4.9.9.7 Local A psect defined as local will not be combined with other local psects from other modules at link time. The redefinition of a psect with conflicting delta values can lead to phase errors being issued by the assembler.3.1 “-Aclass =low-high. even if there are others with the same name. The association of a class with a psect that you have defined typically means that you do not need to supply a custom linker option to place it in memory. If this flag is not specified. 6.9. 6.3 Class The class flag specifies a corresponding linker class name for this psect. See Section 7. then merging will not take place. 6. A local psect may not have the same name as any global psect.” for information on how linker classes are defined. If assigned the value 1.9. the psect will never be merged by the assembly optimizer during optimizations.8 Merge This flag can be assigned 0 or 1. so a delta of 1 (the default) should be used for all psects on these devices. 6. Psects are considered global by default. Thus addresses in the HEX file will not match addresses in the program memory.3. since they cannot always be referred to by their own name in a -P linker option (as would be the case if there are more than one local psect with the same name). DS52053B-page 257 .3.4.Macro Assembler 6. Psects are grouped from all modules being linked. Class names are also useful where psects need only be positioned anywhere within a range of addresses rather than at a specific address. All memory spaces on PIC18 devices are byte addressable. The data memory space on these devices is byte addressable. the number of data bytes which are associated with each address. With PIC mid-range and baseline devices. When assigned 0.3. hence psects in this space must use a delta of 2. In other words.

then the splitability of this psect is based on whether the psect can be merged.14 Split This flag can be assigned 0 or 1. 6.4. 6. All other sections. program memory uses a space value of 0.8 “Merge”. This flag in combination with the abs flag (see Section 6.4.4. rather than concatenated at link time.4.. If this flag is not specified. or not specified. Devices which have a banked data space do not use different space values to identify each bank.MPLAB® XC8 C Compiler User’s Guide 6.1 “Abs”) defines a truly absolute psect.9. 6. If assigned the value 1. can use the default reloc value of 1.4. the psect may be split if other psect attributes allow it and the psect is too large to fit in available memory.9. 6.4. etc. e.15 With The with flag allows a psect to be placed in the same page with another psect.10 Pure The pure flag instructs the linker that this psect will not be modified at runtime and may therefore. i..3.3. For example the flag with=text will specify that this psect should be placed in the same page as the text psect. 6. When assigned 0. so a reloc value of 2 must be used for any psect that contains executable code.3.12 Size The size flag allows a maximum size to be specified for the psect.3.9. The term withtotal refers to the sum of the size of each psect that is placed “with” other psects. 6.e.4. but which are distinct.3. On all 8-bit PIC devices.9 Ovrld A psect defined as ovrld will have the contribution from each module overlaid. is a different location to the data memory address 0.g.9.3. For example a device with a bank size of 0x80 bytes will uses address 0 to 0x7F to represent objects in bank 0. DS52053B-page 258  2012 Microchip Technology Inc. PIC18 instructions must be word aligned.13 Space The space flag is used to differentiate areas of memory which have overlapping addresses.9.9. a psect within which any symbols defined are absolute.9.9.3. see Section 6.11 Reloc The reloc flag allows specification of a requirement for alignment of the psect on a particular boundary. Psects which are positioned in program memory and data memory have a different space value to indicate that the program space address 0.4. and data space memory uses a space of 1.3. for example. This flag is of limited usefulness since it depends on the linker and target system enforcing it. . the psect will never be split by the assembly optimizer during optimizations. size=100h. This will be checked by the linker after psects have been combined from all modules. For example the flag reloc=100h would specify that this psect must start on an address that is a multiple of 100h.4. A full address which includes the bank number is used for objects in this space and so each location can be uniquely identified. and all sections for all other devices. for example.9.3. and then addresses 0x80 to 0xFF to represent objects in bank 1. be placed in ROM.

1 “C Language Comments”. overlaid psect.4.1 “C Language Comments”. For example: thomas SET 0h This directive performs a similar function to the preprocessor’s #define directive.4. Only if the psect in which this directive is placed is absolute and overlaid will the location counter be moved to the address specified.5 “EQU”) except that allows a symbol to be re-defined without error.9.this is guaranteed to reside at address 50h 6. see Section 7. place them in a psect of their own and link this at the required address using the linkers -P option.ovrld ORG 50h .9. DS52053B-page 259 .5 EQU This pseudo-op defines a symbol and equates its value to an expression. For example: ORG 100h will move the location counter to the beginning of the current psect plus 100h.4.Macro Assembler 6. which is not determined until link time. or a value referencing the current psect. the directive must be used from within an absolute.6 “SET” which allows for redefinition of values. see Section 5. To place objects at a particular address. see Section 5.2. For example thomas EQU 123h The identifier thomas will be given the value 123h. EQU is legal only when the symbol has not previously been defined.4. In either case the current location counter is set to the value determined by the argument. Note: The much-abused ORG directive does not move the location counter to the absolute address you specify.9.abs. The actual location will not be known until link time.14. The argument to ORG must be either an absolute value. See also Section 6. This means that the addresses set with ORG are relative to the base address of the psect. For example: PSECT absdata. It is not possible to move the location counter backward. 6.9. The ORG directive is not commonly required in programs.9. This directive performs a similar function to the preprocessor’s #define directive.6 SET This pseudo-op is equivalent to EQU (Section 6.  2012 Microchip Technology Inc. In order to use the ORG directive to set the location counter to an absolute value.14.19 “-Pspec”.4 ORG The ORG directive changes the value of the location counter within the current psect.4.

4. 3664h.2.9. memory locations.Reserve 23 bytes of memory . except that it assembles expressions into double-width (32-bit) words.1. as it will be for baseline and mid-range devices (see Section 6.4 “Delta”).9.9 DDW The DDW directive operates in a similar fashion to DW. A variable is typically defined by using a label and then the DS directive to reserve locations at the label location. each of which will be assembled into one byte and assembled into consecutive memory locations.9.4 “Delta”). ’A’ 6. Note that because the size of an address unit in the program memory is 2 bytes (see Section 6. If used in a psect linked into the program memory.MPLAB® XC8 C Compiler User’s Guide 6.4. but not place anything in the HEX file output. it will move the location counter. Example: DW -1. So the above example will define bytes padded to the following words.3. 12345678h. Examples: alabel: DB ’X’. This directive is typically used to reserve memory location for RAM-based objects in the data memory.3.4.7 DB The DB directive is used to initialize storage as bytes. . except that it assembles expressions into 16-bit words.4. 0058 0001 0002 0003 0004 But on PIC18 devices (PSECT directive’s delta flag should be 1) no padding will occur and the following data will appear in the HEX file.10 DS This directive reserves. the DS pseudo-op will actually reserve an entire word.9. If the size of an address unit in the program memory is 2 bytes.9. The argument is a comma-separated list of expressions.3. The single argument is the number of bytes to be reserved.4.8 DW The DW directive operates in a similar fashion to DB. 58 01 02 03 04 6. Example: DDW ’d’. Examples: alabel: DS 23 xlabel: DS 2+3 . but does not initialize. the DB pseudo-op will initialise a word with the upper byte set to zero. 0 6.Reserve 5 bytes of memory DS52053B-page 260  2012 Microchip Technology Inc.4.9.4.

The code generator issues a DABS directive for every user-defined absolute C variable.9. The linker reads this DABS-related information from object files and will ensure that the reserved address are not used for other memory placement. if ABC is non-zero. ELSIF or ENDIF will be assembled.Macro Assembler 6.11 DABS This directive allows one or more bytes of memory to be reserved at the specified address.3. not just within the current psect.4. At an ELSE the sense of the conditional compilation will be inverted. The argument to IF and ELSIF should be an absolute expression. These directives do not implement a runtime conditional statement in the same way that the C statement if() does. address.13 “Space”). then the code following it up to the next matching ELSE.9. and bytes is the number of bytes that is to be reserved. If both ABC and DEF are zero. DS52053B-page 261 . Indeed. Conditional assembly blocks may be nested. For example: IF ABC GOTO aardvark ELSIF DEF GOTO denver ELSE GOTO grapes ENDIF In this example. ELSE AND ENDIF These directives implement conditional assembly. the third GOTO instruction will be assembled. Note in the above example.12 IF.4.4. the second GOTO instruction will be assembled but the first and third will not.  2012 Microchip Technology Inc. only one GOTO instruction will appear in the output.9. these directives can be placed anywhere in the assembly code and do not contribute to the currently selected psect in any way. 6. ELSIF. If the expression is zero then the code up to the next matching ELSE or ENDIF will be skipped. while an ENDIF will terminate the conditional assembly block. bytes where memorySpace is a number representing the memory space in which the reservation will take place. If ABC is zero and DEF is non-zero. The memory space number is the same as the number specified with the space flag option to psects (see Section 6. If it is non-zero. the first GOTO instruction will be assembled but not the second or third. which one will be determined by the values assigned to ABC and DEF. or for any variables that have been allocated an address by the code generator. address is the address at which the reservation will take place. The general form of the directive is: DABS memorySpace. This directive differs to the DS directive in that it can be used to reserve memory at any location. they are evaluated at compile time.

.4. argument was supplied See Section 6.14 “LOCAL” for use of unique local labels within macros. If it is desired to include a comma (or other delimiter such as a space) in an argument then angle brackets < and > may be used to quote If an argument is preceded by a percent sign. argument was not supplied.10.13 MACRO AND ENDM These directives provide for the definition of assembly macros.the literal value to load arg2 . etc..5 “EQU” for simple association of a value with an identifier.. When the macro is used. DS52053B-page 262  2012 Microchip Technology Inc. for example: IF nul . value MOVLW value MOVWF PORT&port ENDM will load PORTA if port is A when called.14.9. The MACRO directive should be preceded by the macro name and optionally followed by a comma-separated list of formal arguments. Expansion of the macro in the listing file can be shown by using the EXPAND assembler control. the macro name should be used in the same manner as a machine opcode..9. see Section 6.. A comment may be suppressed within the expansion of a macro (thus saving space in the macro storage) by opening the comment with a double semicolon.MPLAB® XC8 C Compiler User’s Guide 6. optionally with arguments. this macro will expand to the 2 instructions in the body of the macro.e. The nul operator may be used within a macro to test a macro argument.4. the argument list must be comma-separated. Thus: movlf 2. which can also work with arguments. By default. or Section 5.. ENDIF arg3 .arg2 MOVLW arg1 MOVWF arg2 mod 080h ENDM When used. with the formal parameters substituted by the arguments. This is useful if evaluation of the argument inside the macro body would yield a different result. .. ELSE . rather than as a string.9. as the macro was invoked.4. that argument will be evaluated as an expression and passed as a decimal number.macro: . the assembly list file will show macro in an unexpanded format.1 “C Language Comments” for the preprocessor’s #define macro directive.args: .. See Section 6. . For example: . but is removed in the actual expansion.the NAME of the source variable Move a literal value into a nominated file register movlf MACRO arg1.descr: movlf arg1 . followed by a list of arguments to be substituted for the formal parameters.4. For example: loadPort MACRO port.3 “EXPAND”. i. When invoking a macro.tempvar expands to: MOVLW 2 MOVWF tempvar mod 080h The & character can be used to permit the concatenation of macro arguments with other text. %. .

The boundary is specified as a number of bytes following the directive. For example.9.  2012 Microchip Technology Inc. The ALIGN directive can also be used to ensure that a psect’s length is a multiple of a certain number.w ENDM will expand to: ADDWF fred.11 “Reloc” for psect alignment.Macro Assembler 6. the label more would expand to ??0002 and multiply defined symbol errors will be averted. See Section 6.9. the following could be used.4. Any symbols listed after the LOCAL directive will have a unique assembler generated symbol substituted for them when the macro is expanded. to the specified offset boundary within the current psect.4. 6. For example: down MACRO count LOCAL more more: DECFSZ count GOTO more ENDM when expanded will include a unique assembler generated label in place of more.w ADDWF fred. the psect would have a length that was always an even number of bytes long. if the above ALIGN directive was placed at the end of a psect. i. For example: down foobar expands to: ??0001 DECFSZ foobar GOTO ??0001 If invoked a second time.9. then expands it a number of times as determined by its argument.4. For example.. alignment is done within the current psect.17 “IRP and IRPC”.15 ALIGN The ALIGN directive aligns whatever is following. 6..9.e.14 LOCAL The LOCAL directive allows unique labels to be defined for each expansion of a given macro.16 REPT The REPT directive temporarily defines an unnamed macro. ALIGN 2 Note that what follows will only begin on an even absolute address if the psect begins on an even address.9.3.4.4. DS52053B-page 263 .w See also Section 6.w ADDWF fred. to align output to a 2 byte (even) address within a psect. data storage or code etc. For example: REPT 3 ADDWF fred.

The operand should be the symbol or address of an object that resides in the data memory. The IRPC directive is similar. the list is a conventional macro argument list.19 PAGESEL This directive can be used to generate code to select the page of the address operand.18 BANKSEL This directive can be used to generate code to select the bank of the operand.9.17 IRP AND IRPC The IRP and IRPC directives operate in a similar way to REPT. For example: IRP number. for example: PROCESSOR 16F877 This directive will override any device selected by any command-line option.MPLAB® XC8 C Compiler User’s Guide 6.9. it is repeated once for each member of an argument list.6F00h DW number ENDM would expand to: DW 4865h DW 6C6Ch DW 6F00h Note that you can use local labels and angle brackets in the same manner as with conventional macros.4865h. See Section 6. or using the assembler’s --CHIP option.20 “--CHIP: Define Device”. but can also be set with this directive.4. In the case of IRP. The device name is typically set using the --CHIP option to the command-line driver xc8. see Section 6. instead of repeating the block a fixed number of times.1. 6.14 “--CHIP: Specify Device Name”.8.1. however.4.9. see Section 4.4.9. See Section 6. 6.4. DS52053B-page 264  2012 Microchip Technology Inc. in the case or IRPC.3.2 “Bank and Page Selection”.4.20 PROCESSOR The output of the assembler may vary depending on the target device.ABC DB ’char’ ENDM will expand to: DB ’A’ DB ’B’ DB ’C’ 6.4.6C6Ch. For example: IRPC char. it is each character in one argument. For each repetition the argument is substituted for one formal parameter. except it substitutes one character at a time from a string of non-space characters.2 “Bank and Page Selection”. .

Some keywords are followed by one or more arguments. Use the SIGNAT directive if you want to write assembly language routines which are called from C. The SIGNAT directive is used by MPLAB XC8 to enforce link time checking of C function prototypes and calling conventions. For example: SIGNAT _fred. < able listing output listopt >] Start a new page in the listing output Add blank lines to listing Specify the subtitle of the program Specify the title of the program OPT PAGE OPT SPACE 3 OPT SUBTITLE “< subtitle >” OPT TITLE “< title >” The default options are listed with an asterisk (*)  2012 Microchip Technology Inc.4.4. ASMOPT_OFF COND*.16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers” and Section 6. This will be shown in the assembly list file. At link time the linker checks that all signatures defined for a particular label are the same and produces an error if they are not.OPT LIST [< listopt >. If a different signature value for _fred is present in any object file.8. DS52053B-page 265 .. These keywords have no significance anywhere else in the program.8192 will associate the signature value 8192 with the symbol _fred.Macro Assembler 6. NOLIST PAGE SPACE SUBTITLE TITLE Note 1: ASPIC[18] ASSEMBLER CONTROLS Meaning Start and stop assembly optimizations Include/do not include conditional code in the listing Expand/do not expand macros in the listing output Textually include another source file Format OPT ASMOPT_OFF . The control is invoked by the directive OPT followed by the control name. NOEXPAND INCLUDE LIST*. NOCOND EXPAND.21 SIGNAT This directive is used to associate a 16-bit signature value with a label. the linker will report an error. The easiest way to determine the correct signature value for a routine is to write a C routine with the same prototype as the assembly routine and check the signature value determined by the code generator. and each is described further below. .10 Assembler Controls Assembler controls may be included in the assembler source to control assembler operation.5 “Assembly-Level Optimizations”. For example: OPT EXPAND A list of keywords is given in Table 6-7.protected code OPT ASMOPT_ON OPT COND OPT EXPAND OPT INCLUDE < pathname > Define options for listing output/dis.. TABLE 6-7: Control ASMOPT_ON. 6..9. see Section 4.

the LIST control may includes options to control the assembly and the listing. for example: OPT INCLUDE "options.10. dec or oct. column) width. the code generated by macro expansions will appear in the listing output.MPLAB® XC8 C Compiler User’s Guide 6. Set the device type. See also the driver option -P in Section 4.4. The options are listed in Table 6-8.4. 6. the LIST control on its own will turn the listing on.4.4. the pathname must specify the exact location. Set the page length. DS52053B-page 266  2012 Microchip Technology Inc. Truncate listing output lines. . The INCLUDE control must be the last control keyword on the line. 6.4.10.1 ASMOPT_OFF AND ASMOPT_ON These controls allow the assembler optimizer to be selectively disabled for sections of assembly code. Turn macro expansion on or off.8 “NOLIST”..5 LIST If the listing was previously turned off using the NOLIST control. List Option See also the NOLIST control in Section 6.6 “NOCOND”.4.4. Set the default radix to HEX.10.e. The default wraps lines.7 “NOEXPAND”.10.10.h" The driver does not pass any search paths to the assembler.10.4 INCLUDE This control causes the file specified by pathname to be textually included at that point in the assembly file.4. until a subsequent ASMOPT_ON control is encountered. See also the NOCOND control in Section 6. See also the NOEXPAND control in Section 6.1 “C Language Comments”). so if the include file is not located in the working directory. 6. 6. No code will be modified after an ASMOPT_OFF control.11 “-P: Preprocess Assembly Files” which forces the C preprocessor to preprocess assembly file.10.8.14. such as #include (see Section 5.2 COND Any conditional code will be included in the listing output.10. thus allowing use of preprocessor directives. TABLE 6-8: c= nnn n= nnn t= ON|OFF p=< device > r=< radix > x= ON|OFF LIST CONTROL OPTIONS Default 80 59 OFF n/a HEX OFF Description Set the page (i.3 EXPAND When EXPAND is in effect. Alternatively.

10. See also the TITLE control in Section 6.10.4. See also the SUBTITLE control in Section 6. 6. See also the XREF control in Section 6.7 NOEXPAND The NOEXPAND control disables macro expansion in the assembly list file. A Control-L (form feed) character will also cause a new page when encountered in the source.8.10.12 “SUBTITLE”.10.9.10.10.4.3 “EXPAND”.10. 6.4. DS52053B-page 267 .4.4.14 “XREF”. See also the EXPAND control in Section 6.  2012 Microchip Technology Inc.4.10.10.23 “--DEBUGGER: Select Debugger Type”). The macro call will be listed instead.4.10 PAGE The PAGE control causes a new page to be started in the listing output. 6.4. The utility CREF should be used to actually generate the formatted cross-reference listing.4. 6.10. 6.2 “COND”.4.4.10.13 “TITLE”.8 NOLIST This control turns the listing output off from this point onward.12 SUBTITLE The SUBTITLE control defines a subtitle to appear at the top of every listing page.13 “MACRO and ENDM”.6 NOCOND Using this control will prevent conditional code from being included in the assembly list file output.10. 6.14 XREF The XREF control is equivalent to the driver command line option --CR (see Section 4.4. 6.5 “LIST”.4. but under the title.11 SPACE The SPACE control will place a number of blank lines in the listing output as specified by its parameter.9 NOXREF The NOXREF control will disable generation of the raw cross reference file. See also the COND control in Section 6.13 TITLE This control keyword defines a title to appear at the top of every listing page.Macro Assembler 6. See also the LIST control in Section 6.10. It causes the assembler to produce a raw cross reference file. 6.4.4. Assembly macro are discussed in Section 6.10.4. The string should be enclosed in single or double quotes. The string should be enclosed in single or double quotes.10.

The optimizations that can be performed by the assembler include the following.4. Procedural abstraction is performed on assembly code sequences that appear more than once.8. and an instruction moves W to an address (MOVWF). which a small impact on code speed. see Section 4. and a call to this routine will replace every instance of the original code sequence. The latter code can be optimized if required. The assembler optimizations can drastically reduce code size. if possible. this might be replaceable with a CLRF instruction. The presence of any label is considered a possible entry point and code following a label is always considered reachable. For example. each instruction – hence the name. but to not perform optimizations on hand-written assembly source modules. This will reduce code size considerable. e. DS52053B-page 268  2012 Microchip Technology Inc. Code within the same psect is guaranteed to be located in the same program memory page. Peephole optimizations are performed on every instruction. Unreachable code is removed.42 “--OPT: Invoke Compiler Optimizations”. This will speed code execution. where x is a number.MPLAB® XC8 C Compiler User’s Guide 6. although typically have little effect on RAM usage. and immediately around..8. primarily to tidy the output related to conditional code sequences that follow a generic template and which can leave jump instructions that jump to other jump instructions.1 “Assembly Instruction Deviations”.42 “--OPT: Invoke Compiler Optimizations”. without a significant increase in code size. Psect merging may be performed to allow other optimizations to take place. Code using the LJMP and FCALL instructions will benefit from this optimization. Assembly which is added in-line (see Section 5. instructions after a return instruction.13 “Optimizations”.g.5 ASSEMBLY-LEVEL OPTIMIZATIONS The assembler performs optimizations on assembly code in addition to those optimizations performed by the code generator directly on the C code.2 “#asm. see Section 5. Only very small routines (typically a few instructions) will be changed so that code size is not impacted. The xc8 driver by default instructs the assembler to optimizer assembly code that is generated from C code.12. These optimizations consider the state of execution at. . see Section 6. Code may become orphaned by other optimizations and cannot be reached during normal execution. In-lining of small routines so that a call to that routine is not required. and so calls and jumps within the psect do not need to have the page selection bits set before executing. PLx. This is essentially a reverse in-lining process. Jump-to-jump type optimizations are made. #endasm and asm()”) with C code is never optimized. Assembly optimizations can often interfere with debugging in tools such as MPLAB IDE and it may be necessary to disable them when debugging code. They either alter or delete one or more instructions at each step. if W is known to contain the value 0. The code sequence is abstracted into a callable routines will use a label. see Section 4.

In addition. The list file is in a human readable form and cannot take any further part in the compilation sequence. Provided the link stage has successfully concluded. local variable information. There will also be one file produced for each assembly source file. see Section 4. 6. the listing file will be updated by the linker so that it contains absolute addresses and symbol values.c: 121: chan &= 0x07.sp2_inpADC.8. Section 4. This information relates to register usage.8. There is one assembly list file produce by the assembler for each assembly file passed to it.reg3] instruction operands address .as. that containing some of the runtime startup file.sp2_inpADC. typically called startup. functions called and the calling function. There is typically at least one assembly file in each project. although these directives are included in the true assembly output files. ========= function _ADC_start ends ======== ======= 2 0243 0243 0244 0245 0252 3 00A3 3007 05A3 0008 assembly  2012 Microchip Technology Inc. instruction operands op code instruction operands 5 . instructions.42 “--OPT: Invoke Compiler Optimizations” gives more information on controlling the optimizers. and exact op codes of.17 “--ASMLIST: Generate Assembler List Files”. FIGURE 6-1: 1 768 769 770 771 772 773 774 775 776 777 778 GENERAL FORM OF ASSEMBLY LISTING FILE 4 . This file will also contains some of the C initialization that forms part of the runtime startup code. the assembler optimizer simplifies some expressions and removes some assembler directives from the listing file for clarity.sp2_inpADC. the assembly output may be different to assembly source code and so is still useful for assembly programming. The line numbers purely relate to the assembly list file and are not associated with the lines numbers in the C or assembly source files.c: 128: } instruction source comment . and so there will be one file produced for all the C source code in a project. It differs from an assembly output file in that it contains address and op-code data.sp2_inpADC. The assembly list file shows the assembly output produced by the compiler for both C and assembly source code. Any assembly that begins with a semicolon indicates it is a comment added by the code generator. Thus you may use the assembler list file to determine the position of. If you are using the assembly list file to look at the code produced by the compiler. or is a comment inserted by the code generator to explain some action taken. DS52053B-page 269 .6 ASSEMBLY LIST FILES The assembler will produce an assembly list file if instructed. If the assembler optimizers are enabled. you may wish to turn off the assembler optimizer so that all the compiler-generated directives are shown in this file. Regs used in _ADC_start: [reg0. The xc8 driver option --ASMLIST is typically used to request generation of such a file.1 General Format The format of the main listing has the form as shown in Figure 6-1. Before the output for each function there is detailed information regarding that function summarized by the code generator. Re-enable the optimizer when continuing development.Macro Assembler 6. including p-code based library code.c: 119: void ADC_start(unsigned char chan) . Such comments contain either the original source code which corresponds to the generated assembly.c: 120: { _ADC_start: line number .6.

It indicates the name of the psect in which it resides. is general information relating to the resources used by that function.MPLAB® XC8 C Compiler User’s Guide 6.3 “PSECT”.3 Function Information For each C function.1 “Compiled Stack Operation”.5 “Pointer Types”.6. printed before the function’s assembly label (search for the function’s name immediately followed by a colon. DS52053B-page 270  2012 Microchip Technology Inc. hence. a location of 42[BANK0] means that the variables was located in the bank 0 memory space and that it appears at an offset of 42 bytes into the compiled stack component in this space. change in the function. This information shows the actual number of bytes assigned to each pointer variable. For example.5. For labels (symbols). The auto and parameter section of this information is especially useful as the size of pointers is dynamic. Look for the first PSECT assembler directive above this code. as well as the address associated with the symbol.6.9. but special comments follow.5 “Pointer Reference Graph”. A typical print out is shown in Figure 6-2: “Function Information”.6. This name associate with this directive is the psect in which the code is placed.2 Psect Information The assembly list file can be used to determine the name of the psect in which a data object or section of code has been placed by the compiler. Functions which use a non-reentrant model are those which allocate auto and parameter variables to a compiled stack and which are. not reentrant. :).4. see Section 6. check the symbol table at the end of the file. The locations shown use the format offset[space]. find the code in the list file. or did not. see Section 6. The tracked objects is generally not used. . The hardware stack information shows how many stack levels were taken up by this function alone and the total levels used by this function and any functions it calls. For other code. It also indicates the bank selection bits that did. these are often accompanied by the targets the pointer can reference after the arrow ->.2. Whenever pointer variables are shown. Most of the information is self explanatory. It indicates the known state of the currently selected RAM bank on entry to the function and at its exit points. see Section 5. see Section 5.2. 6.4. You can usually search for the C statement associated with the code.

___altofl 10 4093 . fsr0l.. 4 9 Hardware stack levels required when called: 4090 . This function is called by: 4096 . _main 7 selected GPR bank on entry and exit rant model r 4097 12 . ___awmod 11 6 registers that the function code used 4095 .0. location and type of return value 4094 .. cstack 4078 .2. -> inputData(2). Params: 0 0 0 0 4084 .. location and type of parameters 4091 .. Temps: 0 5 0 0 4086 . cp 1 41[BANK0 ] PTR unsigned char 4073 .. On entry : 17F/0 4080 . None void 4076 . location and type of auto variables 4092 .. 4074 ..... Unchanged: FFE00/0 4082 .c" 2 3 Parameters: 4067 . 7 Tracked objects: 4079 . x 2 46[BANK0 ] volatile int 4 4072 . pclath. None 4069 . Type 5 Return value: Size Location 4075 . line 29 in file "draw. Locals: 0 7 0 0 8 4085 . Hardware stack levels used: 1 2 file name and line number of definition 4089 ... ___awdiv 5 size... lll 4 42[BANK0 ] long 4071 .. 6 Registers used: 4077 . status.... Size Location Type 4068 .. This function calls: 3 size.. Totals: 0 12 0 0 1 function's name 4087 . On exit : 0/0 4081 ... This function uses a non-reentrant 8 RAM memory summary for entire function 9 hardware stack requirements 10 functions called by this function 11 which functions call this function 12 how the function was encoded  2012 Microchip Technology Inc...Total ram usage: 12 bytes 4088 .. wreg. DS52053B-page 271 .. Auto vars: Size Location Type 4070 . 1 *************** function _render ***************** 4065 .. _lrv 4 size.... fsr0h... status. Defined at: 4066 ..Macro Assembler FIGURE 6-2: FUNCTION INFORMATION 4064 .. Data sizes: COMMON BANK0 BANK1 BANK2 4083 .

Switch size 1. The compiler determines the appropriate strategy.timer_count(BANK0[2]). Largest target is 2 -> task. Range of values is 0 to 254 switch strategies available: Name Instructions Cycles simple_byte 13 7 (average) jumptable 260 6 (fixed) rangetable 259 6 (fixed) spacedrange 516 9 (fixed) locatedrange 255 3 (fixed) Chosen strategy egy e gy is simple_byte 2 3 4 1 size of the switched value 2 number and range of the case values 3 all switch strategies and their attributes 4 the strategy choosen for this switch statement 6. For example. . There are several strategies the compiler can use for switch statements. The information printed will look similar to that shown in Figure 6-3.6.6.MPLAB® XC8 C Compiler User’s Guide 6. and which is local to the function timer_intr().10 “The #pragma switch Directive”.4 Switch Statement Information Along with the generated code for each switch statement is information about how that statement was encoded. . timer_intr@task_tmr PTR unsigned int size(1).4. . . . There is only one target to this pointer and it is the member timer_count in the structure called task. . DS52053B-page 272  2012 Microchip Technology Inc.5 Pointer Reference Graph Other important information contained in the assembly list file is the pointer reference graph (look for pointer list with targets: in the list file). FIGURE 6-3: 206 207 208 209 210 211 212 213 214 215 SWITCH STATEMENT INFORMATION 1 .14. the following shows a pointer called task_tmr in the C code.6. It is a pointer to an unsigned int and it is one byte wide. see Section 5. . . or you can indicate a preference for a particular type of strategy using a pragma. The size and type of each target is indicated as well as the size and type of the pointer variable itself. see Section 5. The pointer reference graph shows both pointers to data objects and pointers to functions. Number of cases is 4. .3 “Switch Statements”. This target variable resides in the BANK0 class and is two bytes wide. requested type "space" . This is a list of each and every pointer contained in the program and each target the pointer can reference through the program.

DS52053B-page 273 . such as function parameters and auto variables.Macro Assembler 6..6.2.2. which is primarily used to allow overlapping of functions’ auto-parameter blocks (APBs). This is produced for target devices that use a compiled stack to facilitate local variables.1 “Compiled Stack Operation” for more detailed information on compiled stack operation. 6. Interrupt functions will form separate trees.6 Call Graph The other important information block in the assembly list file is the call graph (look for Call Graph Tables: in the list file). or may have been called. The following information can be obtained from studying the call graph. and which are called spontaneously • The functions that the linker deemed were called. main() is always a root of a call tree. A typical call graph may look that shown inFigure 6-4.1 These features are discussed below. The call graph in the list file shows the information collated and interpreted by the code generator.5. FIGURE 6-4: CALL GRAPH FORM Call Graph Tables: --------------------------------------------------------------------------------(Depth) Function Calls Base Space Used Autos Params Refs --------------------------------------------------------------------------------(0) _main 12 12 0 34134 43 BANK0 5 5 0 0 BANK1 7 7 0 _aOut _initSPI --------------------------------------------------------------------------------(1) _aOut 2 0 2 68 2 BANK0 2 0 2 _SPI _GetDACValue (ARG) --------------------------------------------------------------------------------(1) _initSPI 0 0 0 0 --------------------------------------------------------------------------------(2) _SPI 2 2 0 23 0 BANK0 2 2 0 . thus the function main() appears as the symbol _main. Estimated maximum stack depth 6 --------------------------------------------------------------------------------- The graph starts with the function main().6. • The functions in the program that are “root” nodes marking the top of a call tree.6. Note that the function name will always be shown in the assembly form.. See Section 5. during program execution • The program’s hierarchy of function calls • The size of the auto and parameter areas within each function’s APB • The offset of each function’s APB within the compiled stack • The estimated call tree depth.  2012 Microchip Technology Inc.

• The assembler optimizer may have replaced function calls with jumps to functions. It defines no parameters (main() never has parameters). If a is always true. the figure tells us main()has 6 bytes of memory allocated at an offset of 4 in the compiled stack section that lives in common memory. it shows that some of the local objects for main() are placed in the common memory. For example. i. For example. The arrows in the figure highlight this indentation. No definitive value can be given for the program’s total stack usage for several reasons: • Certain parts of the call tree may never be reached. This break down is shown under the memory summary line for each function. • The assembler’s procedural abstraction optimizations may have added in calls to abstracted routines. or may call. and temporaries are defined by the compiler. After each tree in the call graph. In this example. } will list foo() and bar() under test(). There is a total of 24 references in the assembly code to local objects in main(). code such as: int test(int a) { if(a) foo(). • The contribution of interrupt (or other) trees to the main() tree cannot be determined as the point in main’s call tree at which the interrupt (or other function invocation) will occur cannot be known. there is an indication of the maximum call (stack) depth that might be realized by that tree.) DS52053B-page 274  2012 Microchip Technology Inc. it can have components placed in multiple memory spaces to utilize all available memory of the target device. In the orange box for main() you can see that it defines 10 auto and temporary variable.MPLAB® XC8 C Compiler User’s Guide All the functions that main() calls.. reducing that tree’s stack usage. These have been grouped in the orange box in the figure. rv().e. The only difference between an auto and temporary variable is that auto variables are defined by the programmer. reducing that tree’s stack usage. but there is a possibility that the function was called. are shown below. A function’s inclusion into the call graph does not imply the function was actually called. It also has 4 bytes of memory allocated in bank 0 memory at an offset of 16 in the bank 0 compiled stack component. but both behave in the same way. In addition to these functions there is information relating to the memory allocated in the compiled stack for main(). The Base value indicates the offset that block has in the respective section of the compiled stack. temporary and parameter variables defined in main(). The Used column indicates how many bytes of memory are used by each section of the compiled stack and the Space column indicates in which space that has been placed. Rather than the compiled stack being one memory allocation in one memory space. then the function bar() will never be called even though it appears in the call graph. else bar(). rvx() and rvy(). This may be used as a guide to the stack usage of the program. This memory will be used for auto. but others are placed in bank 0 data RAM. as either may be called. . Indentation is used to indicate the maximum depth that function reaches in the call graph. Below the information for main() (outside the orange box) you will see the same information repeated for the functions that main() called. (Checks are made to ensure this does not exceed the maximum stack depth.

This information may be presented as follows..6. . Reducing the memory usage of these will have no impact on the memory usage of the entire program.. this warning. too. If you can reduce the memory usage of these functions in the corresponding memory space. For the above reasons..  2012 Microchip Technology Inc. ___flsub->___fladd In this example. then you will affects the program’s total memory usage in that memory space. The memory used by functions that are not in the critical path will overlap entirely with that in the critical path. The exact memory usage of each function is shown in the call graph tables. which calls fladd. indicates the critical path for the main function (the root of one call graph) in bank 0 memory. 6. _foobar->___flsub . DS52053B-page 275 .Macro Assembler The code generator also produces a warning if the maximum stack depth appears to have been exceeded. Essentially. and each of these will appear for every memory space the device defines. it shows that of all the call graph paths starting from the function main. Critical Paths under _main in BANK0 . the path in which main calls foobar. which.. A critical path here represents the biggest range of APBs stacked together in as a contiguous block. 3793 3794 3795 3796 3797 .2 CALL GRAPH CRITICAL PATHS Immediately prior to the call graph tables in the list file are the critical paths for memory usage identified in the call graphs. There will be one call graph for the function main and another for each interrupt function. which calls flsub.6. Look for a line similar to Critical Paths under _main in BANK0. _main->_foobar . A critical path is printed for each memory space and for each call graph. is using the largest block of memory in bank 0 RAM.. is intended to be a only a guide to potential stack problems. for this example. it identifies those functions whose APBs are contributing to the program’s memory usage in that particular memory space.

MPLAB® XC8 C Compiler User’s Guide NOTES: DS52053B-page 276  2012 Microchip Technology Inc. .

Linker 7. the best way to start is to copy the linker arguments constructed by the compiler driver. the linker. The compiler often makes assumptions about the way in which the program will be linked. The options recognized by the linker are listed in Table 7-1 and discussed in the following paragraphs. The application name of the linker is HLINK. and the usage of.MPLAB® XC8 C COMPILER USER’S GUIDE Chapter 7..obj file with only symbol records Specify calculation for segment selectors Generate symbol file Generate enhanced symbol file Option  2012 Microchip Technology Inc.2 OPERATION A command to the linker takes the following form: hlink [options] files The options are zero or more linker options. The files is one or more object files. and should be attempted only by those with a sound knowledge of the compiler and linking in general. as the compiler driver. and zero or more object code library names (. If the psects are not linked correctly. If it is absolutely necessary to use the linker directly. P-code libraries (. will automatically execute the linker with all necessary arguments.lpp extension) are always passed to the code generator application and cannot be passed to the linker.. The following topics are examined in this chapter of the MPLAB XC8 C Compiler User’s Guide: • Operation • Relocation and Psects • Map Files 7. -Cx -Cpsect=class -Cbaseaddr -Dclass=delta -Dsymfile -Eerrfile -F -G spec -H symfile -H+ symfile LINKER COMMAND-LINE OPTIONS Effect Use 8086 style segment:offset address form Specify address ranges for a class Call graph options Specify a class name for a global psect Produce binary output file based at baseaddr Specify a class delta value Produce old-style symbol file Write error messages to errfile Produce . TABLE 7-1: -8 -Aclass=low-high . DS52053B-page 277 . This will ensure that the necessary startup module and arguments are present.1 INTRODUCTION This chapter describes the theory behind.. xc8. and modify them as appropriate. In most instances it will not be necessary to invoke the linker directly. code failure may result.lib extension). each of which modifies the behavior of the linker in some way. Using the linker directly is not simple.

bss.MAP \ -Ptext=0. In this fashion. \ X. DS52053B-page 278  2012 Microchip Technology Inc. 765FH will be treated as a HEX number.obj file Preserve segment relocation items in . a link command file called x.OBJ Z. the number will be interpreted as a decimal value. a trailing H. HLINK commands of almost unlimited length may be issued. By default. or h. and start boundary for a class of psects Pre-enter symbol in table as undefined Use file avmap to generate an Avocet format symbol file Set warning level (-9 to 9) Set map file width (>=10) Remove any local symbols from the symbol file Remove trivial local symbols from the symbol file Specify disabled messages Specify message file location Specify maximum number of errors Do not relocate list file Print version number and stop Option If the standard input is a file then this file is assumed to contain the command-line argument.OBJ may be passed to the linker by one of the following: hlink @x.lnk hlink < x.bound] -Usymbol -Vavmap -Wwarnlev -Wwidth -X -Z --DISL=list --EDF=path --EMAX=number --NORLF --VER LINKER COMMAND-LINE OPTIONS (CONTINUED) Effect Ignore undefined symbols Set maximum number of errors before aborting Prevent overlaying function parameter and auto areas Preserve relocation items in .lnk and containing the following text: -Z -OX. should be added.MPLAB® XC8 C Compiler User’s Guide TABLE 7-1: -I -J num -K -L -LM -N -Nc -Ns -Mmapfile -Ooutfile -Pspec -Qprocessor -S -Sclass=limit[. Lines may be broken by leaving a backslash \ at the end of the preceding line.nvram=bss/. To force interpretation as a HEX number. for example. .lnk Several linker options require memory addresses or sizes to be specified.OBJ -MX.OBJ Y.data=0/. The syntax for all these is similar.obj file Sort symbol table in map file by address order Sort symbol table in map file by class address order Sort symbol table in map file by space address order Generate a link map in the named file Specify name of output file Specify psect addresses and ordering Specify the device type (for cosmetic reasons only) Inhibit listing of symbols in symbol file Specify address limit. For example.

2 -Cx This option is now obsolete. each 64k bytes in size. The delta value should be a number and represents the number of bytes per addressable unit of objects within the psects.4 -Dclass=delta This option allows the delta value for psects that are members of the specified class to be defined.2.4 “Delta”. 7. starting from address zero.2.1 -Aclass =low-high.3.3.9. Most psects do not need this option as they are defined with a delta value.2. they may be specified with a repeat count following an x character.2..3 -Cpsect=class This option will allow a psect to be associated with a specific class. An old-style symbol file is an ASCII file. See Section 6. The -A option does not specify the memory space associated with the address. thus this may result in different psect placement to the case where the option -ACODE=0-0FFFFFh had been specified.. This option will make the linker write all error messages to the specified file instead of the screen. 7. For example: -ACODE=0-0FFFFhx16 specifies that there are 16 contiguous ranges.13 “Space”.3 “Class”. Normally this is not required on the command line since psect classes are specified in object files.9. See Section 6.4.  2012 Microchip Technology Inc.2. Even though the ranges are contiguous.19 “-Pspec”) but sometimes it is desirable to have a class of psects linked into more than one non-contiguous address range. 7.9.3. Under DOS there is no convenient way to redirect this to a file (the compiler drivers will redirect standard error if standard output is redirected). which does not include boundaries on 64k multiples.2. see Section 6. For example: -ACODE=1020h-7FFEh. unless they are specifically linked otherwise. Normally psects are linked according to the information given to a -P option (see Section 7. 7.. no psect will straddle a 64k boundary. which is the default standard error destination.4. 7.Linker 7. This option allows a number of address ranges to be specified as a class.8000h-BFFEh specifies that psects in the class CODE are to be linked into the given address ranges. Where there are a number of identical.6 -Eerrfile Error messages from the linker are written to the standard error stream. the space value of the psect is then assigned to the class. where each line has the link address of the symbol followed by the symbol name.4. contiguous address ranges. DS52053B-page 279 .2.5 -Dsymfile Use this option to produce an old-style symbol file. Once a psect is allocated to a class.

in addition to the standard symbol file. The optional argument symfile specifies the name of the file to receive the data.sym. which provides.9.. then subtract 4”. The -G option allows an alternate method for calculating the segment selector.4. The default file name is l.2.. and adding rather than subtracting a constant.11 “Reloc”. leaving only the symbol records.9 -Hsymfile This option will instruct the linker to generate a symbol file. this is then linked with the files for the other project. see Section 6. This means “Take the load address of the psect. This format is recommended if the code is to be run in conjunction with a debugger. 20. This option can be used when part of one project (i.4. See Section 7. multiply by 8 then add 4”. which is based on the reloc= flag value given to psects at the assembler level. .2 “Psect Information Listed by Module”. This form can be modified by substituting N for A. or bank-switched psects. The argument to -G is a string similar to: A /10h-4h where A represents the load address of the segment and / represents division. 12. 7. and symbol information. as might be the case with a bootloader and application.8 -Gspec When linking programs using segmented.10 -H+symfile This option will instruct the linker to generate an enhanced symbol file.3.7 -F Normally the linker will produce an object file that contains both program code and data bytes.2. The files for one project are compiled using this linker option to produce a symbol-only object file.e. For example: N*8+4 means “take the segment number. class names associated with each symbol and a segments section which lists each class name and the range of memory it occupies. . there are two ways the linker can assign segment addresses.sym. The default file name is l. The result is the segment selector.MPLAB® XC8 C Compiler User’s Guide 7. The optional argument symfile specifies a file to receive the symbol file. to each segment.2.2.. DS52053B-page 280  2012 Microchip Technology Inc. or selectors.2. A segment is defined as a contiguous group of psects where each psect in sequence has both its link and load address concatenated with the previous psect in the group. The -F option will suppress data and code bytes from the output file. By default the segment selector will be generated by dividing the base load address of the segment by the relocation quantum of the segment. Sometimes it is desired to produce a symbol-only object file that can be used again in a subsequent linker run to supply symbol values. The segment address or selector for the segment is the value derived when a segment type relocation is processed by the linker. divide by 10 HEX. The selector of each psect is shown in the map file. which is allocated by the linker. a separate build) is to be shared with other. This particular example would allocate segment selectors in the sequence 4. The token N is replaced by the ordinal number of the segment. for the number of segments defined. 7. * for / (to represent multiplication). 7.

For debugging purposes.  2012 Microchip Technology Inc. 7. in which case a default will apply. or on the standard output if the file name is omitted.11 -I Usually failure to resolve a reference to an undefined symbol is a fatal error.2. 7. The format of the map file is illustrated in Section Section 7.2. but only segment relocations. and this option should not be used.2. 7.16 -Mmapfile This option causes the linker to generate a link map in the named file. In some circumstances a further “relocation” of the program will be done at load time.psect=lnkaddr/ldaddr. 7. Use of this option will override the default. this feature can be disabled with this option. but the -J option allows this to be altered. This is the case for OCG (PRO-Standard-Free mode) compilers. or class.obj. and a minimum value.17 -N. 7. however.12 -Jerrcount The linker will stop processing object files after a certain number of errors (other than warnings). The argument to the -P option consists basically of comma -separated sequences thus: -Ppsect =lnkaddr+min/ldaddr+min. All values may be omitted. doing so will increase the data memory requirements.15 -LM Similar to the above option. 7. 7. This option has no effect when compiled stack allocation is performed by the code generator. based on the value of the symbol.2. The -N option will cause it to be sorted numerically. the linker will try and overlay function auto and parameter blocks to reduce the total amount of RAM required. but essentially each psect is listed with its desired link and load addresses.Linker 7.2. There are several variations.. The default output file name is l. The -L option will generate in the output file one null relocation record for each relocation record in the input.2. DS52053B-page 281 . since the file is now absolute.. Use of this option will cause undefined symbols to be treated as warnings instead.13 -K For older compilers that use a compiled stack. The default number is 10. 7.18 -Ooutfile This option allows specification of an output file name for the linker..2. this preserves relocation records in the output file. depending on previous values.19 -Pspec Psects are linked together and assigned addresses based on information supplied to the linker via -P options.2.2. The -Ns and -Nc options work similarly except that the symbols are grouped by either their space value. -Ns and-Nc By default the symbol table in the map file will be sorted by name.4 “Map Files”.14 -L When the linker produces an output file it does not usually preserve any relocation information.

”) have been used to specify address ranges for a class then this class name may be used in place of a link or load address.E000h-FFFEh -Pdata=C000h/CODE This will link data at C000h. This will explicitly concatenate the current psect with the previously specified psect. Multiple -P options are processed in order. Note here the use of two -P options. .bss the text psect is linked at 100h (its load address defaults to the same).bss/.data.1 “-Aclass =low-high. it will be derived from the top of the previous psect. is preceded by a + sign. For example: -Ptext=0. The data psect will be linked (and loaded) at an address which is 100 HEX plus the length of the text psect. and data will have a load address starting after the end of text.data.bss will cause both text and data to have a link address of zero. The load address may be replaced with a dot character. Note that in this case the data psect will still be assembled into one contiguous block. or special tokens. DS52053B-page 282  2012 Microchip Technology Inc. will be required for other psects. data linked at 8000h but loaded after text. This tells the linker to set the load address of this psect to the same as its link address. For example. bss is linked and loaded at 8000h plus the size of data. text will have a load address of zero. This means that if there are two or more psects in class CODE.. but find space to load it in the address ranges associated with the CODE class. It sets a minimum value for the link or load address. the bss psect will concatenate with the data psect. If -A options (see Section 7.11 “Reloc”). For example: -ACODE=8000h-BFFEh. an error will result. and space will be found in one of the address ranges.4. for example.data=0/. whereas other psects in the class CODE will be distributed into the address ranges wherever they will fit. or the names of other psects. it defaults to the same as the link address. This allows a range to be specified with the -A option without knowing in advance how much of the lower part of the range. If a psect’s link address is omitted.heap This example shows text at zero..”. Any psects allocated by a -P option will have their load address range subtracted from the address ranges associate with classes in the same memory space.data=8000h/. If no sufficiently large space is available in this class. If the link address is a negative number. Similarly. but no address is supplied after it. for example: -Ptext=0. classes. “. and nvram and heap are concatenated with bss. data then text with the top of the text psect appearing at address 0ffh.9.2.3. in the following: -Ptext=100h. Psects following a negative address will be placed before the first psect in memory. rounded up as necessary if the data psect has a reloc value associated with it (see Section 6. the psect is linked in reverse order with the top of the psect appearing at the specified address minus one. The link or load address may also be the name of another (previously linked) psect. they may be intermixed in the address ranges.MPLAB® XC8 C Compiler User’s Guide If present. The bss psect will concatenate with data in terms of both link and load addresses. The address will be calculated as described below. the minimum value. The link and load addresses are either numbers. -Pnvram=bss. If the slash / character is supplied. but if it is less than the minimum then it will be set equal to the minimum. min.bss will link in ascending order bss.. If the load address is omitted entirely. Again: -Ptext=-100h. the load address will concatenate with the previous psect.

Segment information is still included. and followed by a digit string. 7.2. See Section 7. 7. This is useful for linking entirely from libraries.2 “Psect Information Listed by Module”. -SFARCODE=6000h. followed by a digit string. 7. The argument to this option is a string describing the device. The following example places a limit on the maximum address of the CODE class of psects to one less than 400h.4.22 -Sclass =limit[. see Section 6. This option will suppress from the symbol file all local symbols that have the form of a single alphabetic character. 7.2. in the range -9 to 9.2.6 “Limit”).1000h 7. The -Z option will strip any local symbols starting with one of these letters. 7.25 -Wnum The -W option can be used to set the warning level. this must be set in assembler code using the psect limit flag. If the bound (boundary) argument is used.27 -Z Some local symbols are compiler generated and not of interest in debugging. -SCODE=400h Note that to set an upper limit to a psect.bound] A class of psects may have an upper address limit associated with it. 7.2.2.24 -Vavmap To produce an Avocet format symbol file.  2012 Microchip Technology Inc. The set of letters that can start a trivial symbol is currently “klfLSu“. -W9 will suppress all warning messages.4. DS52053B-page 283 . The avmap file will normally be supplied with the compiler. for values of num >= 10. -W0 is the default. Global symbols will always appear in the symbol file. the linker needs to be given a map file to allow it to map psect names to Avocet memory identifiers. There are no behavioral changes attributable to the device type.Linker The final link and load address of psects are shown in the map file. or created automatically by the compiler driver as required.2. or the width of the map file.2.26 -X Local symbols can be suppressed from a symbol file with this option. but with an upper address limit of 6000h.2.23 -Usymbol This option will enter the specified symbol into the linker’s symbol table as an undefined symbol.3. This example below places the FARCODE class of psects at a multiple of 1000h. the class of psects will start on a multiple of the bound address. This is purely for information placed in the map file.9.21 -S This option prevents symbol information relating from being included in the symbol file produced by the linker. 7. Setting the warning level to -9 (-W-9) will give the most comprehensive warning messages.20 -Qprocessor This option allows a device type to be specified. or for linking a module from a library where the ordering has been arranged so that by default a later module will be linked.2.

xc8. DS52053B-page 284  2012 Microchip Technology Inc. 7. xc8.30 --EMAX=number: Specify Maximum Number of Errors This option is mainly used by the command-line driver. the command-line driver and the --MSGDISABLE driver option. This option is normally using by the command line driver. when performing pre-link stages. If you are attempting to resolve fixup errors.6 “Compiler Messages” for full information about the compiler’s messaging system. See Section 4.31 --NORLF: Do Not Relocate List File Use of this option prevents the linker applying fixups to the assembly list file produced by the assembler.6 “Compiler Messages” for full information about the compiler’s messaging system.8. then this option will be disabled when building. to specify the path of the message description file. see Section 4. 7.2. This macro is set when choosing a Debug build in MPLAB IDE. It takes a comma-separate list of message numbers that will be disabled during compilation.2. This option is applied if compiling using xc8.2. The default file is located in the dat directory in the compiler’s installation directory. If the compiler driver detects the presence of a preprocessor macro __DEBUG which is equated to 1. to disable particular message numbers.6 “Compiler Messages” for full information about the compiler’s messaging system. 7.MPLAB® XC8 C Compiler User’s Guide 7.28 --DISL=message numbers Disable Messages This option is mainly used by the command-line driver. but is omitted when performing the final link step so that the list file shows the final absolute addresses. this option should be disabled so as to fixup the assembly list file and allow absolute addresses to be calculated for this file.38 “--MSGDISABLE: Disable Warning Messages”.29 --EDF=message file: Set Message File Path This option is mainly used by the command-line driver. even if other options and files are present on the command line. to specify the maximum number of errors that can be encountered before the assembler terminates. See Section 4.29 “--ERRORS: Maximum Number of Errors”.8.2. The default number is 10 errors. so always have this selected if you encounter such errors. See Section 4. 7.2.32 --VER: Print Version Number This option printed information relating to the version and build of the linker. xc8. This option is applied if compiling using xc8. see Section 4. xc8. the command-line driver and the --ERRORS driver option. The linker will terminate after processing this option. .

but can be changed. The default linker options rarely need adjusting. using the driver option -L-. these will also be passed to the linker. see Section 4. DS52053B-page 285 . The target device memory specification is passed to the linker by the way of linker options. size *.7 “-L-: Adjust Linker Options Directly”. We are now in a position to look at the fundamental tasks the linker performs. A lot of the information in object files relates to psects.4.Linker 7. Existing object files. so essentially we only need consider the format of object files. including C library code. or object file libraries can also be specified in a project. but there is only ever one file produced.3 RELOCATION AND PSECTS This section looks at the input files that the linker has to work with. This is a process called fixup. There is only one of these files since the code generator compiles and combines all the C code of the program and produces just the one assembly output. and others. The output file will consist of the information from all input object files merged together. One will be produced from all the C code in the project. Each record has a type that indicates what sort of information it holds. for example. See Section “(477) fixup overflow in expression (location 0x* (0x*+*). If there are assembly source files in the project. value 0x*) (Linker)” for information on finding the cause of these errors. if required and with caution.8. then there will also be one object file produced for each source file and these will be passed to the linker.4.8 “Program Sections” for an introductory guide. See Section 6. The output of the linker is also an object file. The bulk of each object file consists of psect records containing the executable code and variables etc. Everything that contributes to the program is located in a psect. There are no linker scripts or means of specifying options in any source file. The library files are a collection of object files packaged into a single unit. and if present. Each object file consists of a number of records. program debugging information. The relocation records also specify how the values are to be determined. Some record types hold general information about the target device and its configuration.  2012 Microchip Technology Inc. Relocation consists of placing the psect data into the memory of the target device. either instructions or data. These options are generated by the command-line driver. There is a particular record type that is used to hold the data in psects.lib extension). The other file passed to the linker will be the object code produced from the runtime startup code. xc8. A linker fixup overflow error can occur if the value determined by the linker is too large to fit in the “hole” reserved for the value in the psect. The file is absolute since relocation will have been performed by the linker. The linker can read both relocatable object files and object-file libraries (. see Section 4. Once psects are placed at actual memory locations. there is a corresponding relocation record that indicates which bytes (or bits) in the psect record need to be adjusted once relocation is complete. Psects are an assembly domain construct and are essentially a block of something. other records types may hold data. symbolic references made in the psects data can be replaced with absolute values. For each psect record in the object file. which are: • combining all the relocatable object files into one • relocation of psects contained in the object files into memory • fixup of symbolic references in the psects There is typically at least two object files that are passed to the linker.2 “Startup and Initialization”.

DS52053B-page 286  2012 Microchip Technology Inc.1 Generation If compilation is being performed via an IDE such as HI-TIDE or MPLAB IDE. . Map files are produced by the linker. should appear after the Machine type entry. if the linker ultimately reports too many errors then it did not run to completion.2 • • • • • • • • • Contents The sections in the map file. and the map file will be either not created or not complete.29 “--ERRORS: Maximum Number of Errors”) on the command line to increase the number of errors before the linker exits.MPLAB® XC8 C Compiler User’s Guide 7.1 GENERAL INFORMATION At the top of the map file is general information relating to the execution of the linker. Map files use the extension . 7.4.2. this should not be of concern.4. a map file is generated by default without you having to adjust the compiler options. The device selected with the --CHIP option (Section 4. The object code version relates to the file format used by relocatable object files produced by the assembler.16 “-Mmapfile”. along with explanatory text. The linker will still produce a map file even if it encounters errors.8. see Section 7.8.4.4 MAP FILES The map file contains information relating to the relocation of psects and the addresses assigned to symbols within those psects. Unless either the assembler or linker have been updated independently. However. When analyzing a program. 7. 7. which will allow you to use this file to track down the cause of the errors. If you are using the driver from the command line then you’ll need to use the -M option to request that the map file be produced. If the compilation process is stopped before the linker is executed. in order of appearance. are as follows. The compiler name and version number A copy of the command line used to invoke the linker The version number of the object code in the first file linked The machine type A psect summary sorted by the psect’s parent object file A psect summary sorted by the psect’s CLASS A segment summary Unused address ranges summary The symbol table Portions of an example map file. then no map file is produced. are shown in the following sections.20 “--CHIP: Define Device”) or that select in your IDE. You can use the --ERRORS option (see Section 4.2.map. always confirm the compiler version number shown in the map file if you have more than one compiler version installed to ensure the desired compiler is being executed.

based on the selected target device and the specified driver options.0A0h-0EFh. If the default linker options must be changed.init. see Section 4. See Section 5.00/dat/en_msgs. if you ask the driver to reserve an area of memory. and information about that psect.txt -cs -h+main. --edf=/home/jeff/Microchip/XC8/1. they rarely need adjusting from their default settings.option.obj Object code version is 3. The linker deals with two kinds of addresses: link and load.7 “-L-: Adjust Linker Options Directly”.Linker A typical map file may begin something like the following. these are linker options and not command-line driver options.0120h-016Fh. The object file corresponding to the runtime startup code is normally present in this list.01A0h-01EFh \ -AABS1=020h-07Fh. In the latter case. DS52053B-page 287 . Shown are all the psects (under the Name column) that were linked into the program from each object file.intentry.sym -z \ -Q16F946 -ol.01A0h-01EFh -ASFR0=00h-01Fh \ -ASFR1=080h-09Fh -ASFR2=0100h-011Fh -ASFR3=0180h-019Fh \ -preset_vec=00h. These object files include both files generated from source modules and those that were extracted from object library files (.0120h-016Fh. there will only be one object file representing the entire C part of the program.15.10 Machine type is 16F946 The Linker command line shows all the command-line options and files that were passed to the linker for the last build. You can often confirm that driver options were valid by looking at the linker options in the map file. Note that since the code generator combines all C source files (and p-code libraries). Fortunately. The linker options are necessarily complex.2.end_init -ppowerup=CODE -pfunctab=CODE \ -ACONFIG=02007h-02007h -pconfig=CONFIG -DCONFIG=2 -AIDLOC=02000h-02003h \ -pidloc=IDLOC -DIDLOC=2 -AEEDATA=00h-0FFh/02100h -peeprom_data=EEDATA \ -DEEDATA=2 -DCODE=2 -DSTRCODE=2 -DSTRING=2 -DCONST=2 -DENTRY=2 -k \ startup.obj main. This example has been cut down for clarity. 7.8. The information in this section of the map file can be used to confirm that a module is making a contribution to the output file and to determine the exact psects that each module defines. This section is heralded by the line that contains the headings: Name Link Load Length Selector Space Scale Under this on the far left is a list of object files. For example.  2012 Microchip Technology Inc. and information regarding the psects these modules defined. Generally speaking the link address of a psect is the address by which it will be accessed at run time.4.obj -Mmain. this can be done indirectly through the driver using the driver -L. you should see a change in the linker options used. They are formed by the command-line driver. Remember.map -ver=XC8 -ACONST=00h-0FFhx32 \ -ACODE=00h-07FFhx4 -ASTRCODE=00h-01FFFh -AENTRY=00h-0FFhx32 \ -ASTRING=00h-0FFhx32 -ACOMMON=070h-07Fh -ABANK0=020h-06Fh \ -ABANK1=0A0h-0EFh -ABANK2=0120h-016Fh -ABANK3=01A0h-01EFh \ -ARAM=020h-06Fh. If you use this option. the name of the library file is printed before the object file list.1 “Program Sections” for an introductory explanation of psects.lib extension).0A0h-0EFh. always confirm the change appears correctly in the map file. xc8.2 PSECT INFORMATION LISTED BY MODULE The next section in the map file lists those modules that made a contribution to the output.

13 “Space”.obj Name text bss rbit Link 3A 4B 50 Load 3A 4B A Length Selector 22 30 10 4B 2 0 Space 0 1 1 Scale 8 This indicates that one of the files that the linker processed was called ext.4. and so do not occupy the same memory. its link address is in units of bits. . See Section 6.as. The psect rbit contains bit objects. see Section 6. with separate memory spaces (such as the PIC10/12/16 devices).). the load address is irrelevant and is instead used to hold the link address (in bit units) converted into a byte address. For Harvard architecture machines. This section is heralded by the line that contains the headings: TOTAL Name Link Load Length Under this are the class names followed by those psects which belong to this class. This is left blank if the scale is 1 and will show 8 for psects that hold bit objects. this field must be used in conjunction with the address to specify an exact storage location. DS52053B-page 288  2012 Microchip Technology Inc. Their space flags are the same.3. This shows the contribution to the program from program-wide psects. For example. and a space of 1 indicates the data memory.2.9.e. The Scale of a psect indicates the number of address units per byte.3 “Class”.3. A space of 0 indicates the program memory.4. These psects are the same as those listed by module in the above section.9. The load address field of rbit psect displays the link address converted to byte units. this seems to be a problem given that text is 22 words long. The load address of psects that hold bits is used to display the link address converted into units of bytes. If a psect is used to hold bits. however.MPLAB® XC8 C Compiler User’s Guide The load address.. just a different presentation. (This may have been derived from C code or a source file called ext. which is often the same as the link address. rather than the load address. At first glance. as indicated by the space flag (0 for text and 1 for bss). Underneath the object file list there may be a label COMMON. 7. in particular that used by the compiled stack. which is 8. is the address at which the psect will start within the output file (HEX or binary file etc.) This object file contained a text psect. there is no new information contained in this section. 50h/8 => Ah. but since rbit contains bit objects. See Section 6. they are in different memory areas.4. The Space field is important as it indicates the memory space in which the psect was placed.3.2 “Bit”. ext. at first glance there seems there could be an issue with rbit linked over the top of bss. i.obj. Again. The Length of the psect is shown in the units used by that psect.3 PSECT INFORMATION LISTED BY CLASS The next section in the map file shows the same psect information but grouped by the psects’ class. the following appears in a map file. The psect text was linked at address 3A and bss at address 4B. The Selector is less commonly used and is of no concern when compiling for PIC devices. and this can be confirmed by looking it the scale value. as well as psects called bss and rbit.9.4.

they are defined by the linker during the link process.5 UNUSED ADDRESS RANGES The last of the memory summaries show the memory is has not been allocated.g. DS52053B-page 289 .6 “Linker-Defined Symbols”. A segment is conceptual grouping of contiguous psects in the same memory space. thus the total free space is not simply the addition of all the unused ranges. As always with the linker. See Section 5. There is no information encoded into a symbol to indicate whether it represents code or data. and the value (usually an address) which the symbol has been assigned. Typically this section of the map file can be ignored by the user. Linker-defined symbols act like EQU directives. each range is printed on a separate line.1 “GLOBAL” for more information. Note that the memory associated with a class can overlap that in others.. however. See Section 5.12. There is no segment assembler directive and segments cannot be controlled in any way. 7.9.Linker 7. Each symbol is shown with the psect in which they are placed. and are used by the linker as an aid in psect placement.4 SEGMENT LISTING The class listing in the map file is followed by a listing of segments. any C derived symbol is shown with its assembler equivalent symbol name. Any paging boundaries within a class are not displayed. This section follows the heading: UNUSED ADDRESS RANGES and is followed by a list of classes and the memory still available in each class. but the column Largest block shows the largest contiguous free space which takes into account any paging in the memory range. and no definition for them will appear in any source or intermediate file. The linker is aware of any memory allocated by the code generator (for absolute variables). nor in which memory space it resides. This section has a heading: Symbol Table and is followed by two columns in which the symbols are alphabetically listed. The symbols listed in this table are: • Global assembly labels • Global EQU /SET assembler directive labels • Linker-defined symbols Assembly symbols are made global via the GLOBAL assembler directive.4.2. This section is heralded by the line that contains the headings: SEGMENTS Name Load Length Top Selector Space Class The name of a segment is derived from the psect in the contiguous group with the lowest link address.2.4. This can lead to confusion with the psect with the same name. If you are looking to see why psects cannot be placed into memory (e.15. If there is more than one memory range available in a class. and so this free space is accurate. see Section 6.4.2. Do not read psect information from this section of the map file. cant-find-space type errors) then this important information to study. and is hence unused.  2012 Microchip Technology Inc.6 SYMBOL TABLE The final section in the map file list global symbols that the program defines.3 “Interaction Between Assembly and C Code”.4. 7.

16 “--ADDRQUAL: Set Compiler Response to Memory Qualifiers” for information on generating these files.8. Note that a symbol table is also shown in each assembler list file.) These differ to that shown in the map file in that they list also list local symbols. and only show symbols defined in the corresponding module. or any symbols that are defined using an EQU directive in assembly. . DS52053B-page 290  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide If the psect of a symbol is shown as (abs). Such is the case for absolute C variables. (See Section 4. this implies that the symbol is not directly associated with a psect.

This all minimizes disk I/O when linking.1 INTRODUCTION This chapters discusses some of the utility applications that are bundled with the compiler.MPLAB® XC8 C COMPILER USER’S GUIDE Chapter 8. or object code libraries (. Some of these applications may not be normally invoked when building. DS52053B-page 291 . but a directory of the modules and symbols in the library is maintained at the beginning of a library file.2. 8.  2012 Microchip Technology Inc. It should be noted that the library format is not a general purpose archiving mechanism as is used by some other compiler systems. seeking over the others.obj extension). This has the advantage that the format may be optimized toward speeding up the linkage process. and not all the modules.2 LIBRARIAN The librarian program.lpp extension) from p-code files (. With both library types.lib extension) from object files (. The following applications are described in this chapter of the MPLAB XC8 C Compiler User’s Guide: • • • • • Librarian OBJTOHEX CREF CROMWELL HEXMATE 8. Object code libraries should be used for assembly code that is to be built into a library. P-code libraries should be only created if all the library source code is written in C. Since this directory is smaller than the sum of the modules. but can be manually executed to perform certain tasks. on the first pass the linker can perform faster searches just reading the directory.1 The Library Format The modules in a library are simply concatenated. LIBR. only those modules required by a program will be extracted and included in the program output. Utilities 8. The reasons you might want to use a library in a project are: • there will be fewer files to link • the file content will be accessed faster • libraries uses less disk space The librarian can build p-code libraries (. On the second pass it need read only those modules which are required.p1 extension). has the function of combining several files into a single file known as a library.

or referenced but undefined. When using the d key letter.lib [file1. These are listed in Table 8-1. it will be created. extracting or deleting modules. the modules listed must be object files. the names of the modules to be replaced or extracted must be specified. In this instance. If the r key is used and the library does not exist. Adding a file to a library is performed by requesting the librarian to replace it in the library. The following files.MPLAB® XC8 C Compiler User’s Guide 8. see Section 4. When replacing or extracting modules. such as MPLAB IDE.lpp [file1.p1.obj .obj file2. the global symbols defined or referenced within.2. The m and s key letters will list the named modules and. k.2 Using the Librarian Library files can be built directly using the command-line driver. In this case the driver will invoke LIBR with the appropriate options saving you from having to use the librarian directly. You may wish to perform this step manually.] The options are zero or more librarian options which affect the output of the program. an empty list of modules means all the modules in the library. the modules listed must be p-code files. The librarian cannot be called from IDEs. for example. Since it is not present. denotes the command requested of the librarian (replacing. TABLE 8-2: LIBRARIAN KEY LETTER COMMANDS Key r d x m s o Replace modules Delete modules Extract modules List modules List modules with symbols Re-order modules Meaning The first file name listed after the key is the name of the library file to be used. .8. in the case of the s key letter.. A D or U letter is used to indicate whether each symbol is defined in the module. The librarian program is called LIBR. TABLE 8-1: LIBRARIAN COMMAND-LINE OPTIONS Option -P width -W Specify page width Suppress non-fatal errors Effect A key letter.44 “--OUTPUT= type: Specify Output File Type”.p1 file2. As with the r and x key letters. all the modules in the library will be replaced or extracted respectively.. listing modules or symbols). it is an error not to give any module names.] file.. and the formats of commands to it are as follows: LIBR [options] LIBR [options] k k file. or you may need to look at the contents of library files. These commands are listed in Table 8-2. if required. are the modules of the library required by the command specified. If you are building a p-code library. If you are building an object file library. DS52053B-page 292  2012 Microchip Technology Inc.. the module will be appended to the library. the named modules will be deleted from the library. This section shows how the librarian can be executed from the command-line. If no names are supplied.

libr <lib.p1 lists the global symbols in the modules ctime. If standard input is redirected from a file. LIBR will prompt for input.obj c.obj 6.obj from the library lcd.lib a.obj b. 8.2.obj will perform much the same as if the object files had been typed on the command line.obj and c.Utilities The o key takes a list of module names and re-orders the matching modules in the library file so that they have the same order as the one listed on the command line.obj 8.2.p1.3 Supplying Arguments Since it is often necessary to supply many object file arguments to LIBR. b.1 EXAMPLES Here are some examples of usage of the librarian. When updating a library the order of the modules is preserved. Any new modules added to a library after it has been created will be appended to the end.obj 5.cmd LIBR will read input from lib.lpp ctime.lib: LIBR d lcd. Using the command above without specifying the module name will list all the symbols defined (or undefined) in the library. The ordering of the modules in a library is significant to the linker. LIBR will take input from the file. If the standard input is attached to the console. as shown here: ctime. the module defining the symbol should come after the module referencing the symbol.obj 3.  2012 Microchip Technology Inc. This allows a virtually unlimited length command to be given to LIBR.2.obj.2.obj 2.lib 1. The following command: LIBR s pic-stdlib-d24.cmd. Multiple line input may be given by using a backslash as a continuation character on the end of a line. The libr> prompts were printed by LIBR itself. For example: libr libr> r file. arguments will be read from standard input if no command-line arguments are given.4 Ordering of Libraries The librarian creates libraries with the modules in the order in which they were given on the command line. Modules that are not listed are left in their existing order. If a library contains a module which references a symbol defined in another module in the same library.p1 D D D D D _moninit _localtime _gmtime _asctime _ctime The D letter before each symbol indicates that these symbols are defined by the module. 8. the remainder of the text was typed as input. and will appear after the re-ordered modules. without prompting. The following command deletes the object modules a. DS52053B-page 293 . and execute the command found therein.obj \ libr> 4.

2. while some represent a harmless occurrence which will nonetheless be reported unless the -W option was used. In this case all warning messages will be suppressed. .5 Error Messages LIBR issues various error messages. most of which represent a fatal error.MPLAB® XC8 C Compiler User’s Guide 8. DS52053B-page 294  2012 Microchip Technology Inc.

To force interpretation as a HEX number.m Produce a CP/M-86 output file Produce an ATDOS . The inputfile defaults to l.default value is 0FFh Produce an Intel HEX file with linear addressed extended records. S28 or S37 format) Produce an output file for Minix Produce an output file for an Atari ST. Pass relocation information into the output file (used with . any address will be interpreted as a decimal value.n. Specify message file location Specify maximum number of errors OBJTOHEX COMMAND-LINE OPTIONS Meaning --EDF --EMAX --MSGDISABLE Specify disabled messages --VER Print version number and stop If outputfile is omitted it defaults to l.g. where n is the maximum number of bytes per record and m specifies the record size rounding. with optional stack size Include relocation information in the output file Write a symbol file into file Produce a Tektronix HEX file. Except where noted. should be added. including various HEX formats. Non-rounded records are zero padded to a multiple of m. 765FH will be treated as a HEX number.bin depending on whether the -b option is used.atx output file Produce a binary file with offset of base. This allows conversion of object files as produced by the linker into a variety of different formats.obj Read a list of checksum specifications from ckfile or standard input Produce a COD file Produce an MS-DOS .exe file Fill unused memory with words of value fill .obj. Produce an extended TekHEX file. or h. Produce a COFF output file Produce a UBROF format file Reverse the order of words and long words in the output file Format either Motorola or Intel HEX file.Utilities 8. Any other format required must be produced by running the utility program OBJTOHEX.  2012 Microchip Technology Inc. TABLE 8-3: Option -8 -A -Bbase -Cckfile -D -E -Ffill -I -L -M -N -Pstk -R -Sfile -T -TE -U -UB -V . DS52053B-page 295 .. The options for OBJTOHEX are listed in Table 8-3. a trailing H. e.exe files) Produce a Motorola HEX file (S19.3 OBJTOHEX The linker is capable of producing object files as output. The program is invoked thus: OBJTOHEX [options] inputfile outputfile All of the arguments are optional. Default file name is l. m itself must be a multiple of 2.HEX or l.

each line describing one checksum. then add 1FFFH to the sum. For example: 0005-1FFF 3-4 +1FFF This will sum the bytes in 5 through 1FFFH inclusive. DS52053B-page 296  2012 Microchip Technology Inc. the value will be used to initialize the checksum. where1 should be less than where2. addr2.MPLAB® XC8 C Compiler User’s Guide 8. The syntax of a checksum line is: addr1-addr2 where1-where2 +offset All of addr1. The checksum is initialized with 1FFFH to provide protection against an all zero ROM. this should be 1FFFH. For the ROM in question. For a checksum stored low byte first. The initialization value may. For an 8 bit checksum these two addresses should be the same. or a ROM misplaced in memory. low byte in 3. Such a specification says that the bytes at addr1 through to addr2 inclusive should be summed and the sum placed in the locations where1 through where2 inclusive. use HEXMATE’s checksum tools. and vice versa. . however. but if supplied. where2 and offset are HEX numbers. be used in any desired fashion. A run time check of this checksum would add the last address of the ROM being checksummed into the checksum. the OBJTOHEX checksum specification allows automated checksum calculation and takes the form of several lines. without the usual H suffix. The 16 bit checksum will be placed in locations 3 and 4.6 “HEXMATE”.3. Otherwise it is initialized to zero.1 Checksum Specifications If you are generating a HEX file output. For other file formats. The +offset value is optional. described in Section 8. where1.

 2012 Microchip Technology Inc.. The default is 66 lines.4. For example. The assembler will generate a raw cross-reference file with a -C assembler option or a XREF control line. CREF.h>. A raw cross-reference file is produced with the --CR command-line driver option. The -F option allows specification of a path name prefix that will be used to exclude any symbols defined in a file whose path name begins with that prefix. 8. e. <stdio. is used to format raw cross-reference information produced by the compiler or the assembler into a sorted listing.1 -Fprefix It is often desired to exclude from the cross-reference listing any symbols defined in a system header file.g. TABLE 8-4: -Fprefix -Hheading -Llen -Ooutfile -Pwidth -Sstoplist -Xprefix --EDF --EMAX --MSGDISABLE --VER CREF COMMAND-LINE OPTIONS Option Meaning Exclude symbols from files with a pathname or filename starting with prefix Specify a heading for the listing file Specify the page length for the listing file Specify the name of the listing file Set the listing width Read file stoplist and ignore any symbols listed.. The default heading is the name of the first raw cross-ref information file specified. e. 8. A backslash at the end of the line will be interpreted to mean that more command lines follow.4.3 -Llen Specify the length of the paper on which the listing is to be produced. The general form of the CREF command is: cref [options] files where options is zero or more options as described below and files is one or more raw cross-reference files. if the listing is to be printed on 55 line paper you would use a -L55 option.Utilities 8.g. CREF will accept wildcard filenames and I/O redirection.2 -Hheading The -H option takes a string as an argument which will be used as a header in the listing. 8. Exclude any symbols starting with prefix Specify message file location Specify maximum number of errors Specify disabled messages Print version number and stop Each option is described in more detail in the following sections.4 CREF The cross reference list utility. Long command lines may be supplied by invoking CREF with no arguments and typing the command line in response to the cref> prompt. CREF takes the options listed in Section Table 8-4: “CREF Command-line Options”. DS52053B-page 297 .4. -F\ will exclude any symbols from all files with a path name starting with \.

6 -Sstoplist The -S option should have as its argument the name of a file containing a list of symbols not to be listed in the cross-reference. 8.4. one per line in the file.7 -Xprefix The -X option allows the exclusion of symbols from the listing. 8. This option is applied if compiling using xc8.5 -Pwidth This option allows the specification of the width to which the listing is to be formatted.8. Symbols should be listed. For example.6 “Compiler Messages” for full information about the compiler’s messaging system. based on a prefix given as argument to -X. if it was desired to exclude all symbols starting with the character sequence xyz then the option -Xxyz would be used. Alternatively outfile may be specified as the output file name.8.MPLAB® XC8 C Compiler User’s Guide 8.8 --EDF=message file: Set Message File Path This option is mainly used by the command-line driver.g.4 -Ooutfile Allows specification of the output file name. Multiple stoplists may be supplied with multiple -S options.38 “--MSGDISABLE: Disable Warning Messages”. .. It takes a comma-separate list of message numbers that will be disabled during compilation.4. see Section 4.4. e. See Section 4.29 “--ERRORS: Maximum Number of Errors”. 8. xc8. the command-line driver and the --MSGDISABLE driver option. to specify the maximum number of errors that can be encountered before CREF terminates. The default file is located in the dat directory in the compiler’s installation directory. This option is applied if compiling using xc8.4. -XX0 would exclude any symbols starting with the letter X followed by a digit. 8.6 “Compiler Messages” for full information about the compiler’s messaging system. xc8. xc8. The default is 80 columns. e. If a digit appears in the character sequence then this will match any digit in the symbol.g. DS52053B-page 298  2012 Microchip Technology Inc.4. See Section 4.6 “Compiler Messages” for full information about the compiler’s messaging system. the command-line driver and the --ERRORS driver option. The default number is 10 errors. 8. -P132 will format the listing for a 132 column printer. Use the C domain symbols. to disable particular message numbers.9 --EMAX=number: Specify Maximum Number of Errors This option is mainly used by the command-line driver.10 --MSGDISABLE=message numbers Disable Messages This option is mainly used by the command-line driver. to specify the path of the message description file. By default the listing will be written to the standard output and may be redirected in the usual manner. See Section 4.4. see Section 4..4. 8.

 2012 Microchip Technology Inc. CREF will terminate after processing this option.Utilities 8.4. even if other options and files are present on the command line.11 --VER: Print Version Number This option prints information relating to the version and build of CREF. DS52053B-page 299 .

The output formats available are shown in Table 8-5. The options are further described in the following paragraphs. TABLE 8-6: CROMWELL COMMAND-LINE OPTIONS Option -Pname[. The general form of the CROMWELL command is: CROMWELL [options] inputFiles -okey [outputFile] where options can be any of the options shown in Table 8-6. .5 CROMWELL The CROMWELL utility converts code and symbol files into different formats. TABLE 8-5: cod coff elf eomf51 hitech icoff ihex mcoff omf51 pe s19 CROMWELL FORMAT TYPES Key Bytecraft COD file COFF file format ELF/DWARF file Extended OMF-51 format HI-TECH Software format ICOFF file format Intel HEX file format Microchip COFF file format OMF-51 file format P&E file format Motorola HEX file format Format The CROMWELL application is automatically executed by the command-line driver when required. DS52053B-page 300  2012 Microchip Technology Inc. CROMWELL automatically searches for the SDB files and reads those if they are found. The inputFiles are typically the HEX and SYM file. These files are typically used by debuggers and allow source-level debugging of code.MPLAB® XC8 C Compiler User’s Guide 8. The following information is required if running the application manually.architecture] -N -D -C -F -Okey -Ikey -L -E -B -M -V --EDF=path --EMAX=number --MSGDISABLE=list --VER Description Device name and architecture Identify code classes Dump input file Identify input files only Fake local symbols as global Set the output format Set the input format List the available formats Strip file extensions Specify big-endian byte ordering Strip underscore character Verbose mode Specify message file location Specify maximum number of errors Specify disabled messages Print version number and stop The outputFile (optional) is the name of the output file.

The key can be any of the types listed in Table 8-5.5.Utilities 8. 8. CROMWELL may use this in the generation of the output format selected.3 -D The -D option is used to display details about the named input file in a human-readable format.architecture] The -P options takes a string which is the name of the device used.5.1 -Pname[. For example.  2012 Microchip Technology Inc. The input file can be one of the file types as shown in Table 8-5. Note that to produce output in COFF format an additional argument to this option which also specifies the device architecture is required. DS52053B-page 301 .5. 8.ENTRY. The names of the classes are specified as a comma-separated list. this option can be used to force all local symbols to be represented as global symbols.CONST. CROMWELL requires that the names of the program memory space psect classes be provided.6 -Okey This option specifies the format of the output file.7 -Ikey This option can be used to specify the default input file format.architecture. See the map file (Section 7. 8. If the file is recognized. a confirmation of its type will be displayed. which are usually binary files.5.5.STRING. COFF). Hence for this format the usage of this option must take the form: -Pname.5.g. This option is useful if you need to check the contents of the file.5.4 -C This option will attempt to identify if the specified input files are one of the formats as shown in Table 8-5. 8.. mid-range devices typically requires -NCODE. The key can be any of the types listed in Table 8-5.4 “Map Files”) to determine which classes the linker uses. Table 8-7 enumerates the architectures supported for producing COFF files. 8.5 -F When generating a COD file. The may be useful where an emulator cannot read local symbol information from the COD file. TABLE 8-7: PIC12 PIC14 PIC14E PIC16 PIC18 PIC24 PIC30 ARCHITECTURE ARGUMENTS Architecture Description Microchip baseline PIC® MCU chips Microchip mid-range PIC MCU chips Microchip Enhanced mid-range PIC MCU chips Microchip high-end (17CXXX) PIC MCU chips Microchip PIC18 chips Microchip PIC24F and PIC24H chips Microchip dsPIC30 and dsPIC33 chips 8.2 -N To produce some output file formats (e.

5. 8. This option is applied if compiling using xc8.13 --EDF=message file: Set Message File Path This option is mainly used by the command-line driver.5. Also.15 --MSGDISABLE=message numbers Disable Messages This option is mainly used by the command-line driver.10 -B In formats that support different endian types.5. to specify the maximum number of errors that can be encountered before CROMWELL terminates.29 “--ERRORS: Maximum Number of Errors”. 8. Also. see Section 4.9 -E Use this option to tell CROMWELL to ignore any filename extensions that were given. DS52053B-page 302  2012 Microchip Technology Inc.6 “Compiler Messages” for full information about the compiler’s messaging system. even if other options and files are present on the command line. use this option to specify big-endian byte ordering. The default number is 10 errors. 8. the command-line driver and the --ERRORS driver option. see Section 4. xc8.MPLAB® XC8 C Compiler User’s Guide 8. the command-line driver and the --MSGDISABLE driver option.5.5. A list similar to that given in Table 8-5 will be shown.8 -L Use this option to show what file format types are supported. The default file is located in the dat directory in the compiler’s installation directory. It takes a comma-separate list of message numbers that will be disabled during compilation. CROMWELL will terminate after processing this option. xc8. 8.8. see Section 4.11 -M When generating COD files this option will remove the preceding underscore character from symbols.6 “Compiler Messages” for full information about the compiler’s messaging system. 8. see Section 4. Also.5. 8.12 -V Turns on verbose mode that displays information about which operations CROMWELL is performing.6 “Compiler Messages” for full information about the compiler’s messaging system. to disable particular message numbers.5. .38 “--MSGDISABLE: Disable Warning Messages”. 8. 8. This option is applied if compiling using xc8.5. to specify the path of the message description file.5.14 --EMAX=number: Specify Maximum Number of Errors This option is mainly used by the command-line driver. xc8. see Section 4. The default extension will be used instead.16 --VER: Print Version Number This option prints information relating to the version and build of CROMWELL.8.

INHX8M) Detect specific or partial opcode sequences within a HEX file Find/replace specific or partial opcode sequences Provide a map of addresses used in a HEX file Change or fix the length of data records in a HEX file..g.Utilities 8. • Storage of a string (e. time stamp) at a fixed address. and that provides the facility to: • • • • • • • • • Calculate and store variable-length checksum values Fill unused memory locations with known data sequences Merge multiple Intel HEX files into one output file Convert INHX32 files to other INHX formats (e. • Storage of a serial number at a fixed address..g. initialize EEPROM) • Detecting usage of a buggy/restricted instruction • Adjusting HEX file to meet requirements of particular bootloaders  2012 Microchip Technology Inc. Validate checksums within Intel HEX files.. Typical applications for HEXMATE might include: • Merging a bootloader or debug module into a main application at build time • Calculating a checksum over a range of program memory and storing its value in program memory or EEPROM • Filling unused memory locations with an instruction to send the PC to a known location if it gets lost. DS52053B-page 303 . • Store initial values at a particular memory address (e. HEXMATE is a post-link stage utility which is automatically invoked by the compiler driver.6 HEXMATE The HEXMATE utility is a program designed to manipulate Intel HEX files.g.

HEX] [options] Where file1. however. Note that any integral values supplied to the HEXMATE options should be entered as hexadecimal values without leading 0x or trailing h characters. unless specified otherwise in the -ADDRESSING option. Store an ASCII string at a fixed address Store an ASCII string at a fixed address using string packing Adjust warning sensitivity Prefix to any option to overwrite other data in its address range if necessary Option The input parameters to HEXMATE are now discussed in greater detail. its usage is: HEXMATE [specs.]file1. then no merging takes place. Table 8-8 lists the command line options that HEXMATE accepts. This is primarily to merge in HEX files with the output generated by the source files..MPLAB® XC8 C Compiler User’s Guide 8. the following details the options available when running this application. there are some xc8 options which directly map to HEXMATE options.DELETE -FIND..HEX through to fileN. TABLE 8-8: -ADDRESSING -BREAK -CK -FILL -FIND -FIND. Note also that any address fields specified in these options are to be entered as byte addresses.6.. If HEXMATE is to be run directly. xc8.]fileN.HEX [[specs.HEX form a list of input Intel HEX files to merge using HEXMATE.REPLACE -FORMAT -HELP -LOGFILE -Ofile -SERIAL -SIZE -STRING -STRPACK -W + HEXMATE COMMAND-LINE OPTIONS Effect Set address fields in all HEXMATE options to use word addressing or other Break continuous data so that a new record begins at a set address Calculate and store a checksum value Program unused locations with a known value Search and notify if a particular code sequence is detected Remove the code sequence if it is detected (use with caution) Replace the code sequence with a new code sequence Specify maximum data record length or select INHX variant Show all options or display help message for specific option Save HEXMATE analysis of output and various results to a file Specify the name of the output file Store a serial number or code sequence at a fixed address Report the number of bytes of data contained in the resultant HEX image.. DS52053B-page 304  2012 Microchip Technology Inc. If only one HEX file is specified. but other functionality is specified by additional options. and so other functionality can be requested without having to run HEXMATE explicitly on the command line... [specs.. .1 HEXMATE Command Line Options HEXMATE is automatically called by the command line driver. For other functionality..]file2.HEX .

1. This option will allow specification of addressing modes from one byte per address to four bytes per address. If any of these addresses are encountered in the HEX file.1.hex as input.6. 8. the -ADDRESSING option is used. the one specified with a + prefix will take priority.1 SPECIFICATIONS.1. For example: r100-1FFs2000. In these cases it would be much simpler to be able to enter address-components in the device’s native format. Be careful when shifting sections of executable code. A range restriction can be applied with the specification rStart-End. If. The affect of this setting is global and all HEXMATE options will now interpret addresses according to this setting.6. The list of specifications will then be separated from the filename by a comma. 8. Using the + operator informs HEXMATE that if more than one data source tries to store data to the same address. the current data record will conclude and a new data record will recommence from the nominated address.3 -ADDRESSING By default.6. An address shift can be applied with the specification sOffset. The offset can be either positive or negative. the option -ADDRESSING=2 will configure HEXMATE to interpret all command line address fields as word addresses. Additional specifications can be applied to each HEX file to put restrictions or conditions on how this file should be processed. the data obtained from that source will be forced into the output file and will overwrite another other data existing at that address range.4 -BREAK This option takes a comma-separated list of addresses. a device’s program memory naturally used a 16-bit (2 byte) word-addressing format.  2012 Microchip Technology Inc. DS52053B-page 305 . For example: r100-1FF.FILENAME.HEX +-STRING@1000=”My string” Ordinarily. HEXMATE will issue an error if two sources try to store differing data at the same location. for example. all address arguments in HEXMATE options expect that values will be entered as byte addresses.hex will use myfile. If an address shift is used. If any specifications are used they must precede the filename.1. For example: +input. A range restriction will cause only the address data falling within this range to be used. but only process data which is addressed within the range 100h-1FFh (inclusive) from that file. This option takes exactly one parameter which configures the number of bytes contained per address location.Utilities 8. 8.HEX Intel HEX files that can be processed by HEXMATE should be in either INHX32 or INHX8M format.6. Program code should only be shifted if it is position independent. data read from this HEX file will be shifted (by the offset specified) to a new address when generating the output. Some HEX file readers depend on this. In some device architectures the native addressing format may be something other than byte addressing. To facilitate this.myfile.HEX will shift the block of data from 100h-1FFh to the new address range 2100h-21FFh.2 + PREFIX When the + operator precedes an argument or input file.myfile. This can be useful to use new data records to force a distinction between functionally different areas of program space.

This can allow each byte of the checksum result to be embedded within an instruction.6. the result will be stored in big-endian byte order. TABLE 8-9: -4 -3 -2 -1 1 2 3 4 7 8 HEXMATE CHECKSUM ALGORITHM SELECTION Selector Algorithm description Subtraction of 32 bit values from initial value Subtraction of 24 bit values from initial value Subtraction of 16 bit values from initial value Subtraction of 8 bit values from initial value Addition of 8 bit values from initial value Addition of 16 bit values from initial value Addition of 24 bit values from initial value Addition of 32 bit values from initial value Fletcher’s checksum (8 bit) Fletcher’s checksum (16 bit) DS52053B-page 306  2012 Microchip Technology Inc. • Width is optional and specifies the byte-width of the checksum result.MPLAB® XC8 C Compiler User’s Guide 8. If a positive width is requested. The result will be two bytes wide. the result will be 2 bytes wide and stored in little-endian byte order. If the width is left unspecified. The checksum value will be offset by 2100h. A typical example of the use of the checksum option is: -CK=0-1FFF@2FFE+2100w2 This will calculate a checksum over the range 0-1FFFh and program the checksum result at address 2FFEh. the default checksum algorithm used is 8 bit addition (1). • Algorithm is an integer to select which HEXMATE algorithm to use to calculate the checksum result. • offset is an optional initial value to add to the checksum result. Results can be calculated for byte-widths of 1 to 4 bytes. This value cannot be within the range of calculation. A list of selectable algorithms are given in Table 8-9. A negative width will cause the result to be stored in little-endian byte order. • destination is the address where the checksum result will be stored.5 -CK The -CK option is for calculating a checksum. . The usage of this option is: -CK=start-end@destination [+offset][wWidth][tCode][gAlogithm] where: • start and end specify the address range over which the checksum will be calculated. If unspecified.1. • Code is a hexadecimal code that will trail each byte in the checksum result.

e. -FILL=w1:1 with fill every byte with the value 0x01.1.6 -FILL The -FILL option is used for filling unused memory locations with a known value. • Align is optional.const fill memory with a repeating constant. -FILL=0xDEAD. -FILL=0xBEEF@0x1000 puts 0xBEEF at address 1000h . 0xBEDF. if present. i. i. The usage of this option is: -FILL=[const_width:]fill_expr[@address[:end_address]] where: • const_width has the form wn and signifies the width (n bytes) of each constant in fill_expr. Defining a title will make log-reports and messages more descriptive and more readable. 8.. • Mask is optional.7 -FIND This option is used to detect and log occurrences of an opcode or partial code sequence. 0xBECF.e. as per normal C syntax.Utilities 8. 0xBEF2 . i. for example.const fill memory with a list of repeating constants..1. i. A title will not affect the actual search results. 0xBEF1..const-=increment fill memory with a decrementing constant.e. 0xBEF0. i. 0xBEEF.const.. • Title is optional.e. i. The usage of this option is: -FIND=Findcode [mMask]@Start-End [/Align][w][t”Title”] where: • Findcode is the hexadecimal code sequence to search for and is entered in little endian byte order.@address:end_address fill a range of memory with fill_expr.0xBEEF • The options following fill_expr result in the following behavior: . 0xBEBF . -FILL=0xBEEF becomes 0xBEEF. will cause HEXMATE to issue a warning whenever the code sequence is detected.const.. -FILL=0xBEEF+=1 becomes 0xBEEF.6. That is. It specifies that a code sequence can only match if it begins on an address which is a multiple of this value. 0xBEEF .. 0xFF00 is hexadecimal and FF00 is illegal.0xBEEF. 1234 is a decimal value... It allows a title to be given to this code sequence. the default value is the native width of the architecture.e.0xDEAD. It specifies a bit mask applied over the Findcode value to allow a less restrictive search. -FILL=0xBEEF-=0x10 becomes 0xBEEF.6. • Start and End limit the address range to search. 0xBEEF. • fill_expr can use the syntax (where const and increment are n-byte constants): . -FILL=0xBEEF@0:0xFF puts 0xBEEF in unused addresses between 0 and 255 All constants can be expressed in (unsigned) binary.@address fill a specific address with fill_expr. If const_width is not specified. decimal or hexadecimal..0xBEEF becomes 0xDEAD.const+=increment fill memory with an incrementing constant.e.  2012 Microchip Technology Inc.. octal. It is entered in little endian byte order. DS52053B-page 307 . • w.

DELETE If the DELETE form of the -FIND option is used. Any messaging or reports generated by HEXMATE will refer to this opcode by the name.6. .8 -FIND.6. In this next example. If HEXMATE is generating a log file. The option -FIND=3412@0-7FFF/2w will detect the code sequence 1234h when aligned on a 2 (two) byte address boundary. any matching sequences will be removed.. between 0h and 7FFFh. This may be useful if. 8. -FIND accepts whole bytes of HEX data from 1 to 8 bytes in length. with new codes.REPLACE=Code [mMask] where: • Code is a little endian hexadecimal code to replace the sequences that match the -FIND criteria.1. • Mask is an optional bit mask to specify which bits within Code will replace the code sequence that has been matched. DS52053B-page 308  2012 Microchip Technology Inc. w indicates that a warning will be issued each time this sequence is found. where x is any digit. -FIND can be used in conjunction with REPLACE or DELETE (as described below).. any matching sequences will be replaced. the option is the same as in last example but the code sequence being matched is masked with 000Fh. ADDXY as this was the title defined for this search. is must be of equal byte-width to the opcode it is applied to.. This function should be used with extreme caution and is not normally recommended for removal of executable code.9 -FIND. it is only necessary to modify 4 bits within a 16-bit instruction. -FIND=3412M0F00@0-7FFF/2wt”ADDXY”.MPLAB® XC8 C Compiler User’s Guide Here are some examples. or partially replaced. it will contain the results of all searches. so HEXMATE will search for any of the opcodes 123xh. The remaining 12 bits can masked and be left unchanged. Optionally. If a byte-mask is used. 8....REPLACE If the REPLACE form of the -FIND option is used. The usage for this sub-option is: -FIND..1... for example.

11 -HELP Using -HELP will list all HEXMATE options. For example: -HELP=string will show additional help for the -STRING HEXMATE option. with 16 being the default. By entering another HEXMATE option as a parameter of -HELP will show a detailed help message for the given option.6. no less.10 -FORMAT The -FORMAT option can be used to specify a particular variant of INHX format or adjust maximum record length.log. Appropriate use of -FILL can ensure that there are no gaps in the data for the address range being programmed. The usage of this option is: -FORMAT=Type [. 8. This is possible by combining the -FORMAT with -FILL options.Utilities 8.6.6.Length] where: • Type specifies a particular INHX format to generate. Now consider if the same bootloader also required every data record to contain eight bytes of data. DS52053B-page 309 . This is a requirement of some device programmers. by generating the HEX file in INHX8M format the operation might succeed. • Length is optional and sets the maximum number of bytes per data record. Note that INHX032 is not an actual INHX format. The HEXMATE option to do this would be -FORMAT=INHX8M.12 -LOGFILE The -LOGFILE option saves HEX file statistics to the named file. Consider the case of a bootloader trying to download an INHX32 file which fails because it cannot process the extended address records which are part of the INHX32 standard. no more.1. For example: -LOGFILE=output. The possible types that are supported by this option are listed in Table 8-10. TABLE 8-10: Type INHX8M INHX32 INHX032 INHX TYPES USED IN -FORMAT OPTION Description Cannot program addresses beyond 64K Can program addresses beyond 64K with extended linear address records INHX32 with initialization of upper address to zero 8.log will analyze the HEX file that HEXMATE is generating and save a report to a file named output. and that any data in the HEX file outside of this range can be safely disregarded.  2012 Microchip Technology Inc. You know that this bootloader can only program data addressed within the range 0 to 64k.1.1. just modify the previous option to become -FORMAT=INHX8M. To set the maximum length of data records to eight bytes. Selection of this type generates an INHX32 file but will also initialize the upper address information to zero.8. This will satisfy the minimum data length requirement. In this case. A valid length is between 1 and 16.

The size will also be recorded in the log file if one has been requested.hex will save the resultant output to program.16 -SIZE Using the -SIZE option will report the number of bytes of data within the resultant HEX image to standard output. or the first repetition thereof. 8. • Increment is optional and allows the value of Code to change by this value with each repetition (if requested). The usage of this option is as follows: -MASK=hexcode@start-end Where hexcode is a hexadecimal value that will be ANDed with data within the start to end address range.14 -OFILE The generated Intel HEX output will be created in this file. but by doing so it will replace the input file entirely.13 -MASK Use this option to logically AND a memory range with a particular bitmask. The usage of this option is: -SERIAL=Code [+/-Increment]@Address [+/-Interval][rRepetitions] where: • Code is a hexadecimal value to store and is entered in little endian byte order. Multibyte mask values can be entered in little endian byte order.6.MPLAB® XC8 C Compiler User’s Guide 8. For example: -Oprogram. • Address is the location to store this code.1. Subsequent codes will appear at address intervals of +10h and the code value will change in increments of +2h. • Interval is optional and specifies the address shift per repetition of this code. Another example: -SERIAL=0000+2@1000+10r5 will store 5 codes. The output file can take the same name as one of its input files. beginning with value 0000 at address 1000h.1. For example: -SERIAL=000001@EFFE will store HEX code 00001h to address EFFEh.6.hex.6.1.15 -SERIAL This option will store a particular HEX value at a fixed address.1. 8. . • Repetitions is optional and specifies the number of times to repeat this code. 8. This is used to ensure that the unimplemented bits in program words (if any) are left blank.6. DS52053B-page 310  2012 Microchip Technology Inc.

This is known as string packing.6. For example: -STRING@1000=”My favorite string” will store the ASCII data for the string. The second difference is that -STRING’s t specifier is not applicable with the -STRPACK option. 8. The usage of this option is: -STRING@Address [tCode]=”Text” where: • Address is the location to store this string.18 -STRPACK This option performs the same function as -STRING but with two important differences. • Text is the string to convert to ASCII and embed. This can allow the bytes of the string to be encoded within an instruction. DS52053B-page 311 .  2012 Microchip Technology Inc.1.Utilities 8. And again: -STRING@1000t34=”My favorite string” will store the same string with every byte in the string being trailed with the HEX code 34h. Pairs of 7 bit characters are then concatenated and stored as a 14 bit word rather than in separate bytes.6. only the lower seven bits from each character are stored. • Code is optional and allows a byte sequence to trail each byte in the string.1. My favorite string (including the nul character terminator) at address 1000h.17 -STRING The -STRING option will embed an ASCII string at a fixed address. This is usually only useful for devices where program space is addressed as 14 bit words (PIC10/12/16 devices). Firstly.

MPLAB® XC8 C Compiler User’s Guide NOTES: DS52053B-page 312  2012 Microchip Technology Inc. .

MPLAB® XC8 C COMPILER USER’S GUIDE Appendix A. The macro assumes the argument is a16-bit value. which will be used to program the configuration bits. DS52053B-page 313 . or the equivalent prototype for macros. __CONFIG (BASELINE & MID-RANGE DEVICES) Synopsis #include <xc. The synopsis indicates the header file in which a declaration or definition for function or macro is found. __IDLOC7(). Library Functions The functions and preprocessor macros within the standard compiler library are alphabetically listed in this chapter. Example #include <xc. It also shows the function prototype for functions.h> __CONFIG(RC & UNPROTECT) void main (void) { } See also __EEPROM_DATA(). 16-bit masks have been defined to describe each programmable attribute available on each device. CONFIG() (PIC18)  2012 Microchip Technology Inc.h> __CONFIG(data) Description This macro is used to program the configuration fuses that set the device’s operating modes. Multiple attributes can be selected by ANDing them together.h>. These masks can be found in the chip-specific header files included via <xc. __IDLOC().

An error will result if these macros are used without defining oscillator frequency symbol or if the delay period requested is too large. . In order to achieve this.WDTPS16 & BORV45) __CONFIG(4. these macros require the prior definition of preprocessor symbol _XTAL_FREQ.RC & OSCEN) __CONFIG(2. Use the #pragma config for new projects. This macro is used to program the configuration fuses that set the device’s operating modes. CONFIG() (baseline & mid-range devices) __DELAY_MS.h>. Multiple attributes can be selected by ANDing them together. then the 16-Bit value it is to update it with. __IDLOC7(). Example #include <xc. These macros simply wrap around _delay(n) and convert the time based request into instruction cycles based on the system frequency. See also _delay() DS52053B-page 314  2012 Microchip Technology Inc. The macro accepts the number corresponding to the configuration register it is to program.MPLAB® XC8 C Compiler User’s Guide __CONFIG (PIC18) Synopsis #include <xc. These masks can be found in the chip-specific header files included via <xc. DEBUGEN) void main (void) { } See also __EEPROM_DATA().h> __CONFIG(1. the macros __delay_ms(x) and __delay_us(x) are provided. __IDLOC(). data) Description This macro is provided for legacy support only. __DELAY_US Synopsis __delay_ms(x) __delay_us(x) // request a delay in milliseconds // request a delay in microseconds Description As it is often more convenient request a delay in time-based terms rather than in cycle counts. This symbol should be defined as the oscillator frequency (in Hertz) used by the system.h> __CONFIG(num. 16-bit masks have been defined to describe each programmable attribute available on each device.

F and 0 in the ID registers */ __IDLOC(15F0).0x01.0x02.c.h> __EEPROM_DATA(0x00.0x0D.0x04. DS52053B-page 315 .0x0B.h> /* will store 1. Use the #pragma config for new projects. The macro must be given blocks of 8 bytes to write each time it is called.h) Description This macro is used to store initial values into the device’s EEPROM registers at the time of programming.0x05. each time it is used.0x03.b. and can be called repeatedly to store multiple blocks.0x06. This macro places data into the device’s special locations outside of addressable memory reserved for ID. 5.h> __EEPROM_DATA(a. This would be useful for storage of serial numbers etc.0x0C.Library Functions __EEPROM_DATA Synopsis #include <xc.0x09.0x0A.0x0E. Example #include <xc.0x0F) void main (void) { } See also __CONFIG() __IDLOC Synopsis #include <xc.f.d.h> __IDLOC(x) Description This macro is provided for legacy support only.0x07) __EEPROM_DATA(0x08. __EEPROM_DATA() will begin writing to EEPROM address zero.g.e. void main (void) { }  2012 Microchip Technology Inc. Example #include <xc. and will auto-increment the address written to by 8. The macro will attempt to write 4 nibbles of data to the 4 locations reserved for ID purposes.

000 instructions). This would be useful for storage of serial numbers etc. See also __IDLOC(). This macro places data into the device’s special locations outside of addressable memory reserved for ID. The macro will attempt to write 7 bits of data to each of the 4 locations reserved for ID purposes.d) Description This macro is provided for legacy support only. For very large delays.h> /* will store 7Fh.1. Example #include <xc.c. 1 and 5Ah in the ID registers */ __IDLOC(0x7F. An error will result if the delay period requested is too large (approximately 50.659. Use the #pragma config for new projects.b. . Refer to the device data sheet to see whether this macro can be used on your particular device.h> void _delay(unsigned long cycles). __CONFIG() _DELAY() Synopsis #include <xc. DS52053B-page 316  2012 Microchip Technology Inc. __CONFIG() __IDLOC7 Synopsis #include <xc. void main (void) { } Note Not all devices permit 7 bit programming of the ID locations.h> __IDLOC7(a. this routine expands to an inline assembly delay sequence. The sequence will consist of code that delays for the number of instruction cycles that is specified as the argument.0x5A). 70. When called. call this function multiple times. The argument must be a literal constant.70.MPLAB® XC8 C Compiler User’s Guide See also __IDLOC7(). Description This is an inline function that is expanded by the code generator.

Description This is an inline function that is expanded by the code generator. Example #include <xc. DS52053B-page 317 . __delay_ms() _DELAY3() Synopsis #include <xc.h> void main (void) { control |= 0x80. __delay_us(). // delay for 30 cycles control &= 0x7F.h> void main (void) { control |= 0x80.h> int abs (int j) Description The abs() function returns the absolute value of j. this routine expands to an inline assembly delay sequence.  2012 Microchip Technology Inc. _delay(10).Library Functions Example #include <xc.The sequence will consist of code that delays for 3 times the number of cycles that is specified as argument.h> void _delay3(unsigned char cycles). // delay for 10 cycles control &= 0x7F. The argument can be a byte-sized constant or variable. _delay(10). When called. } See Also _delay ABS Synopsis #include <stdlib. } See Also _delay3().

atan().h> void main (void) { int a = -5. ACOS Synopsis #include <math. atan2() Return Value An angle in radians. a.141592. a). cos(). } See Also labs(). it is passed a value in the range -1 to +1. a. and returns an angle in radians whose cosine is equal to that value.h> #include <stdio. fabs() Return Value The absolute value of j. asin().1) { a = acos(i)*180. i.h> #include <stdlib.h> double acos (double f) Description The acos() function implements the inverse of cos().0/3. printf(“acos(%f) = %f degrees\n”. i += 0. */ void main (void) { float i. for(i = -1.h> /* Print acos() values for -1 to 1 in degrees. printf(“The absolute value of %d is %d\n”. i.MPLAB® XC8 C Compiler User’s Guide Example #include <stdio. in the range 0 to  DS52053B-page 318  2012 Microchip Technology Inc.e. } } See Also sin(). tan().0 . abs(a))..0. i < 1. Example #include <math. .

DS52053B-page 319 . The width of each field in the string is fixed. converts it to a struct tm with localtime(). The time() function will need to be provided by the user (see time() for details).h> #include <time.Library Functions ASCTIME Synopsis #include <time. and returns an angle in radians whose sine is equal to that value. See time() for more details.h> void main (void) { time_t clock. The example gets the current time. tp = localtime(&clock). struct tm * tp.  2012 Microchip Technology Inc. localtime(). gmtime(). ASIN Synopsis #include <math.. time() Return Value A pointer to the string. and returns a 26 character string describing the current date and time in the format: Sun Sep 16 01:03:52 1973\n\0 Note the newline at the end of the string. pointed to by its argument.h> double asin (double f) Description The asin() function implements the converse of sin(). Note The example will require the user to provide the time() routine as it cannot be supplied with the compiler. asctime(tp)).h> char * asctime (struct tm * t) Description The asctime() function takes the time broken down into the struct tm structure. i.e. } See Also ctime(). it is passed a value in the range -1 to +1. Example #include <stdio. it then converts this to ASCII and prints it. printf(“%s”. time(&clock).

in the range . . For example.0 .1) { a = asin(i)*180. even if you do not modify it. Include the source file containing this function.h> void ptrfunc (struct xyz * tp) { assert(tp != 0).MPLAB® XC8 C Compiler User’s Guide Example #include <math. } } See Also sin(). An assert() routine may be used to ensure at run time that an assumption holds true.h> void assert (int e) Description This macro is used for debugging purposes.h> #include <stdio. A fuller discussion of the uses of assert() is impossible in limited space. for(i = -1. i < 1.) will need to be implemented by the user. If at run time the expression evaluates to false. a. } Note The underlying routine _fassert(. printf(“asin(%f) = %f degrees\n”. and the expression used as an argument to it.h> void main (void) { float i. ASSERT Synopsis #include <assert. i. DS52053B-page 320  2012 Microchip Technology Inc.0/3. into your project and then rebuild. Example #include <assert. the basic method of usage is to place assertions liberally throughout your code at points where correct operation of the code depends upon certain conditions being true initially. cos(). atan2() Return Value An angle in radians. By default this prints information using printf(). tan().. acos(). i += 0. a). the following statement asserts that tp is not equal to NULL: assert(tp). This routine should be inspected to ensure it meets your application needs. The assert() macro depends on the implementation of the function _fassert(). but it is closely linked to methods of proving program correctness. the program will abort with a message identifying the source file and line number of the assertion. atan().141592..0. The _fassert() function is not built into any library file.

asin().e.  2012 Microchip Technology Inc. %f) is %f\n”. Example #include <stdio.h> #include <math.h> void main (void) { printf(“atan2(%f.h> void main (void) { printf(“atan(%f) is %f\n”. atan() Return Value The arc tangent of y/x.0. acos(). -10. ATAN2 Synopsis #include <math. tan(). i. 10. 1.5. double x) Description This function returns the arc tangent of y/x.0)). tan().h> double atan (double x) Description This function returns the arc tangent of its argument. } See Also sin(). -10.h> double atan2 (double x. cos().Library Functions ATAN Synopsis #include <math. asin().0.h> #include <math. DS52053B-page 321 . cos().5)). it returns an angle ‘e’ in the range . atan2() Return Value The arc tangent of its argument. atan(1.. atan2(10. } See Also sin(). Example #include <stdio.. acos().0.

atol(). If no number is found in the string. It then converts an ASCII representation of a decimal number to an integer. strtod() Return Value A double precision floating-point number. skipping leading blanks.h> double atof (const char * s) Description The atof() function scans the character string passed to it.h> void main (void) { char buf[80].h> int atoi (const char * s) Description The atoi() function scans the character string passed to it. i).h> #include <stdio. The number may be in decimal. . printf(“Read %s: converted to %f\n”. buf.MPLAB® XC8 C Compiler User’s Guide ATOF Synopsis #include <stdlib. i = atof(buf). } See Also atoi(). 0. normal floating point or scientific notation. DS52053B-page 322  2012 Microchip Technology Inc. double i. Example #include <stdlib. skipping leading blanks and reading an optional sign. It then converts an ASCII representation of a number to a double. gets(buf).0 will be returned. ATOI Synopsis #include <stdlib.

If no number is found in the string. buf. gets(buf). int i.Library Functions Example #include <stdlib.h> #include <stdio. } See Also atoi(). It then converts an ASCII representation of a decimal number to a long integer. DS52053B-page 323 . i = atoi(buf).  2012 Microchip Technology Inc. 0 will be returned. i). i = atol(buf). long i. Example #include <stdlib. atol() Return Value A signed integer. If no number is found in the string. printf(“Read %s: converted to %ld\n”. atof().h> void main (void) { char buf[80]. skipping leading blanks. gets(buf). buf. atof() Return Value A long integer. ATOL Synopsis #include <stdlib. printf(“Read %s: converted to %d\n”.h> void main (void) { char buf[80].h> #include <stdio. } See Also xtoi().h> long atol (const char * s) Description The atol() function scans the character string passed to it. i). 0 will be returned.

} See Also qsort() Return Value A pointer to the matched array element (if there is more than one matching element. vp->value).value).h> #include <string. ((const struct value *)p2)->name). } void main (void) { char inbuf[80]. Example #include <stdlib. If no match is found. void * base. Note The comparison function must have the correct prototype. val_cmp). values.MPLAB® XC8 C Compiler User’s Guide BSEARCH Synopsis #include <stdlib. sizeof values[0]. size_t n_memb.h> #include <stdio. } qsort(values. const void * p2) { return strcmp(((const struct value *)p1)->name. int val_cmp (const void * p1. if(!vp) printf(“Item ’fred’ was not found\n”). while(gets(inbuf)) { sscanf(inbuf. &values[i]. i++. It uses a binary search algorithm. any of these may be returned). struct value * vp. i = 0. else printf(“Item ’fred’ has value %d\n”. int i. int value. calling the function pointed to by compar to compare elements in the array. int (*compar)(const void *.”%s %d”. a null is returned.h> void * bsearch (const void * key. i. . sizeof values[0]. i.h> struct value { char name[40]. } values[100]. size_t size. DS52053B-page 324  2012 Microchip Technology Inc. vp = bsearch(“fred”. const void *)) Description The bsearch() function searches a sorted array for an element matching a particular key. values[i]. val_cmp).name.

with a carriage return or line feed (newline) terminating the function. void main (void) { for(. scanf(“%lf” &j). cputs(“Type ’exit’ to finish\n”). with backspace deleting the previously typed character.h> char buffer[80]. } CGETS Synopsis #include <conio. j. } }  2012 Microchip Technology Inc. ceil(j)). DS52053B-page 325 . The collected string is null terminated.h> void main (void) { double j. they are buffered.h> #include <math. “exit” == 0) break.h> #include <string.Library Functions CEIL Synopsis #include <math.h> char * cgets (char * s) Description The cgets() function will read one line of input from the console into the buffer passed as an argument. As characters are read. if(strcmp(buffer. Other characters are placed in the buffer. It does so by repeated calls to getche(). and ctrl-U deleting the entire line typed so far. Example #include <stdio. printf(“The ceiling of %lf is %lf\n”. Example #include <conio.h> double ceil (double f) Description This routine returns the smallest whole number not less than f.) { cgets(buffer)..

Example #include <xc.h> CLRWDT(). sin(i*C). } See Also sin(). for(i = 0 .h> double cos (double f) Description This function yields the cosine of its argument. putch().0 void main (void) { double i.MPLAB® XC8 C Compiler User’s Guide See Also getch(). } COS Synopsis #include <math. cos = %f\n”. The cosine is calculated by expansion of a polynomial series approximation. i += 10) printf(“sin(%3.141592/180. cos(i*C)). i. acos().h> void main (void) { WDTCON=1.h> #define C 3. CLRWDT Synopsis #include <xc.0 . . atan(). Example #include <math. /* enable the WDT */ CLRWDT(). i <= 180. asin().0f) = %f. cputs() Return Value The return value is the character passed as the sole argument. atan2() DS52053B-page 326  2012 Microchip Technology Inc. getche().h> #include <stdio. tan(). which is an angle in radians. Description This macro is used to clear the device’s internal watchdog timer.

 2012 Microchip Technology Inc.h> double cosh (double f) double sinh (double f) double tanh (double f) Description These functions are the implement hyperbolic equivalents of the trigonometric functions. Example #include <stdio. } Return Value The function cosh() returns the hyperbolic cosine value. printf(“%f\n”. In an embedded system cputs() and puts() are equivalent.h> void main (void) { printf(“%f\n”.h> #include <math.Library Functions Return Value A double in the range -1 to +1. DS52053B-page 327 . tanh(1. rather than using file I/O. sin() and tan(). printf(“%f\n”. TANH Synopsis #include <math.h> void cputs (const char * s) Description The cputs() function writes its argument string to the console. It calls putch() repeatedly.5)). On a hosted system cputs() differs from puts() in that it writes to the console directly. The function sinh() returns the hyperbolic sine value.5)). cos(). cosh(1. SINH. outputting carriage returns before each newline in the string. The function tanh() returns the hyperbolic tangent value. sinh(1. CPUTS Synopsis #include <conio.5)). COSH.

h> char buffer[80]. void main (void) { for(. time() Return Value A pointer to the string.. See time() for more detail. time(&clock). asctime().MPLAB® XC8 C Compiler User’s Guide Example #include <conio. . } } See Also cputs(). DS52053B-page 328  2012 Microchip Technology Inc. Note The example will require the user to provide the time() routine as one cannot be supplied with the compiler. “exit” == 0) break.h> #include <time. ctime(&clock)). if(strcmp(buffer. puts().h> char * ctime (time_t * t) Description The ctime() function converts the time in seconds pointed to by its argument to a string of the same form as described for asctime(). } See Also gmtime().h> #include <string.h> void main (void) { time_t clock. putch() CTIME Synopsis #include <time. cputs(“Type ’exit’ to finish\n”. localtime(). printf(“%s”.) { cgets(buffer). Example #include <stdio. Thus the example program prints the current time and date.

Library Functions DEVICE_ID_READ() Synopsis #include <xc. and there is no need to call di() in an interrupt function. id_value = device_id_read(). DS52053B-page 329 . unsigned int device_code. /* lower 5 bits represent revision number * upper 11 bits identify device */ device_code = (id_value >> 5). The ei() macro should never be called in an interrupt function. These are implemented as macros. Note The device_id_read() is applicable only to those devices which are capable of reading their own program memory. DI.h> unsigned int device_id_read(void). If this was not done. This code can be used to identify the device and its revision number. if the interrupt occurred between accesses to successive words of the count value. revision_no = (unsigned char)(id_value & 0x1F). Example #include <xc. unsigned char revision_no. } See Also flash_read(). config_read() Return Value device_id_read() returns the 16-Bit factory-programmed device id code used to identify the device type and its revision number.h> void main (void) { unsigned int id_value. Description This function returns the device ID code that is factory-programmed into the chip.  2012 Microchip Technology Inc. it would be possible to return an incorrect value. EI Synopsis #include <xc. The example shows the use of ei() and di() around access to a long variable that is modified during an interrupt.h> void ei (void) void di (void) Description The di() and ei() routines disable and re-enable interrupts respectively.

ldiv(). int denom) Description The div() function computes the quotient and remainder of the numerator divided by the denominator. DS52053B-page 330  2012 Microchip Technology Inc. 66). EEPROM ROUTINES Description These functions are now supplied in the peripheral library. Example #include <stdlib. di().h> #include <stdio. See the peripheral library documentation for full information on this library function.quot. .h> void main (void) { div_t x. x = div(12345. ei().*/ DIV Synopsis #include <stdlib. x. uldiv() Return Value Returns the quotient and remainder into the div_t structure. x. return val. } See Also udiv(). remainder = %d\n”. to ensure consistency. void interrupt tick (void) { count++. val = count.h> div_t div (int numer. } /* Disable interrupts around access to count. printf(“quotient = %d.MPLAB® XC8 C Compiler User’s Guide Example #include <xc.rem).h> long count. } long getticks (void) { long val.

at x.h> double eval_poly (double x.e. const double * d.Library Functions EVAL_POLY Synopsis #include <math. y. ‘e’ to the power of ‘f’. for example: y = x*x*d2 + x*d1 + d0. double d[3] = {1. for(f = 0.h> #include <math. f += 1. 2).h> void main (void) { double f.0f = %f\n”. DS52053B-page 331 . 3. whose coefficients are contained in the array d. i.h> void main (void) { double x. The order of the polynomial is passed in n. Example #include <math. y).h> double exp (double f) Description The exp() routine returns the exponential function of its argument.1. exp(f)).2. 2.5. EXP Synopsis #include <math. } Return Value A double value. d. Example #include <stdio..0 . } See Also log(). pow()  2012 Microchip Technology Inc.0) printf(“e to %1. log10().7}. printf(“The polynomial evaluated at %f is %f\n”. f <= 5 . y = eval_poly(x. f. x = 2. x. being the polynomial evaluated at x.h> #include <stdio. int n) Description The eval_poly() function evaluates a polynomial.

floor( 1. printf("%f\n". Example #include <stdio. labs() FLASH ROUTINES Description These functions are now supplied in the peripheral library. floor( -1.5)). Example #include <stdio.h> void main (void) { printf("%f %f\n".h> double floor (double f) Description This routine returns the largest whole number not greater than f. fabs(-1. } DS52053B-page 332  2012 Microchip Technology Inc.5). FLOOR Synopsis #include <math. See the peripheral library documentation for full information on this library function.MPLAB® XC8 C Compiler User’s Guide FABS Synopsis #include <math. . fabs(1.h> #include <math.5)). } See Also abs().h> void main (void) { printf("%f\n".h> #include <math.5 )).h> double fabs (double f) Description This routine returns the absolute value of its double argument.

h> void main (void) { double f. } Return Value The floating-point remainder of x/y. int * p) Description The frexp() function breaks a floating-point number into a normalized fraction and an integral power of 2. and f equals x times 2 raised to the power stored in *p. &i). The integer is stored into the int object pointed to by p. rem = fmod(x. int i.34.h> void main (void) { double rem.1). FREXP Synopsis #include <math. x = 12. Example #include <math. i). printf("23456.h> #include <stdio. x.34. Example #include <math.Library Functions FMOD Synopsis #include <math. f.34 = %f * 2^%d\n".0) or zero. } See Also ldexp()  2012 Microchip Technology Inc. 1.5.h> double fmod (double x. If f is zero. both parts of the result are zero. DS52053B-page 333 .h> double frexp (double f. double y) Description The function fmod returns the remainder of x/y as a floating-point quantity. f = frexp(23456. 2. Its return value x is in the interval (0.

int * status) Description The function ftoa converts the contents of f into a string which is stored into a buffer which is then return. } See Also getche(). getchar() DS52053B-page 334  2012 Microchip Technology Inc. } See Also strtol(). buf). utoa().MPLAB® XC8 C Compiler User’s Guide FTOA Synopsis #include <stdlib. Example #include <conio. float input = 12. &status). and return this value. itoa().h> void main (void) { char * buf. int status.h> #include <stdio. GETCH Synopsis #include <conio. void main (void) { result = getch(). Typically this function will read one byte of data from a peripheral that is associated with stdin. buf = ftoa(input.h> char result. Example #include <stdlib.h> char * ftoa (float f.h> char getch (void) Description The getch() function is provided as an empty stub which can be completed as each project requires. ultoa() Return Value This routine returns a reference to the buffer into which the result is written. . printf("The buffer holds %s\n".34.

} See Also getch(). and return this value.h> char getche (void) Description The getche() function is provided as an empty stub which can be completed as each project requires. } See Also getc().h> char result. Unlike getch(). Example #include <conio. getchar() GETCHAR Synopsis #include <stdio. while((c = getchar()) != EOF) putchar(c). Example #include <stdio. Typically this function will read one byte of data from a peripheral that is associated with stdin. DS52053B-page 335 . getche() Note This routine calls getche().h> int getchar (void) Description The getchar() routine usually reads from stdin. but is implemented as a call to getche().h> void main (void) { int c. it echoes this character received. void main (void) { result = getche().Library Functions GETCHE Synopsis #include <conio.  2012 Microchip Technology Inc.

the 32-bit floating-point parameters). or NULL on end-of-file.h> double get_cal_data (const unsigned char * code_ptr) Description This function returns the 32-bit floating-point calibration data from the PIC MCU 14000 calibration space. VHTHERM and KTC (that is. . freopen(). DS52053B-page 336  2012 Microchip Technology Inc. KBG. GET_CAL_DATA Synopsis #include <xc. puts() Return Value It returns its argument.h> char * gets (char * s) Description The gets() function reads a line from standard input into the buffer at s. if(gets(buf)) puts(buf). The buffer is null terminated. deleting the newline (compare: fgets()). Example #include <stdio. printf("Type a line: "). } See Also fgets(). Editing (with backspace) is available.MPLAB® XC8 C Compiler User’s Guide GETS Synopsis #include <stdio. and results in getche() being called repeatedly to get characters.h> void main (void) { char buf[80]. In an embedded system. Only use this function to access KREF. gets() is equivalent to cgets(). FOSC and TWDT can be accessed directly as they are bytes.

struct tm * tp.h> struct tm * gmtime (time_t * t) Description This function converts the time pointed to by t which is in seconds since 00:00:00 on Jan 1. GMTIME Synopsis #include <time. /* Get the WDT time-out. asctime(). Example #include <stdio. localtime() Return Value Returns a structure of type tm.h. } Return Value The value of the calibration parameter Note This function can only be used on the PIC14000. into a broken down time stored in a structure as defined in time.Library Functions Example #include <xc. /* Get the slope reference ratio. */ x = get_cal_data(KREF).h> void main (void) { double x.  2012 Microchip Technology Inc. The structure is defined in the ‘Data Types’ section. tp = gmtime(&clock). 1970. DS52053B-page 337 .h> void main (void) { time_t clock. time().h> #include <time. */ y = TWDT. tp->tm_year+1900). unsigned char y. printf("It’s %d in London\n". } See Also ctime(). time(&clock).

if isascii(c) is true or if c = EOF.h> void main (void) { char buf[80]. Synopsis #include <ctype. i = 0. defined in ctype. buf). AL. See time() for more detail. ISALNUM. int i. ISDIGIT. ISLOWER. gets(buf). . test the supplied character for membership in one of several overlapping groups of characters.h> #include <stdio. tab or newline is in A-Z is in 0-9 or a-f or A-F Example #include <ctype. Note that all except isascii() are defined for c. while(isalnum(buf[i])) i++. buf[i] = 0. isalnum(c) isalpha(c) isascii(c) iscntrl(c) isdigit(c) islower(c) isprint(c) isgraph(c) ispunct(c) isspace(c) isupper(c) isxdigit(c) c c c c c c c c c c c c is in 0-9 or a-z or A-Z is in A-Z or a-z is a 7 bit ascii character is a control character is a decimal digit is in a-z is a printing char is a non-space printable character is not alphanumeric is a space. } DS52053B-page 338  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide Note The example will require the user to provide the time() routine as one cannot be supplied with the compiler. ISALPHA. printf("’%s’ is the word\n".h> int int int int int int int int int int int int isalnum (char isalpha (char isascii (char iscntrl (char isdigit (char islower (char isprint (char isgraph (char ispunct (char isspace (char isupper (char isxdigit(char c) c) c) c) c) c) c) c) c) c) c) c) Description These macros.h. ET.

h> char * itoa (char * buf. tolower(). if(isdig(buf[0])) printf(" type detected\n").h> int isdig (int c) Description The isdig() function tests the input character c to see if is a decimal digit (0 – 9) and returns true is this is the case. buf is assumed to reference a buffer which has sufficient space allocated to it. ITOA Synopsis #include <stdlib. ultoa()  2012 Microchip Technology Inc. int base) Description The function itoa converts the contents of val into a string which is stored into buf. int val. DS52053B-page 339 . utoa().Library Functions See Also toupper(). } See Also strtol(). false otherwise. 1234. 16). ltoa(). printf("The buffer holds %s\n". toascii() ISDIG Synopsis #include <ctype. a non-zero value otherwise. } See Also isdigit() (listed under isalnum()) Return Value Zero if the character is a decimal digit. buf).h> void main (void) { char buf[] = "1998a". The conversion is performed according to the radix specified in base. Example #include <ctype.h> void main (void) { char buf[10]. itoa(buf.h> #include <stdio. Example #include <stdlib.

h> int labs (long int j) Description The labs() function returns the absolute value of long value j.h> #include <stdio.h> void main (void) { double f. printf("1. a.h> void main (void) { long int a = -5.0. 10). } See Also abs() Return Value The absolute value of j. the integer i is added to the exponent of the floating-point f and the resultant returned. Example #include <stdio. LABS Synopsis #include <stdlib. int i) Description The ldexp() function performs the inverse of frexp() operation. printf("The absolute value of %ld is %ld\n". LDEXP Synopsis #include <math.h> #include <stdlib. f). f = ldexp(1. . } See Also frexp() DS52053B-page 340  2012 Microchip Technology Inc.0 * 2^10 = %f\n".h> double ldexp (double f.MPLAB® XC8 C Compiler User’s Guide Return Value This routine returns a copy of the buffer into which the result is written. Example #include <math. labs(a)).

printf("Quotient = %ld. LDIV Synopsis #include <stdlib. On systems where it is not possible to predetermine this value. lt.quot. udiv() Return Value Returns a structure of type ldiv_t LOCALTIME Synopsis #include <time.h> struct tm * localtime (time_t * t) Description The localtime() function converts the time pointed to by t which is in seconds since 00:00:00 on Jan 1. computing the quotient and the remainder. 12345). lt. Example #include <stdlib.Library Functions Return Value The return value is the integer i added to the exponent of the floating-point value f. into a broken down time stored in a structure as defined in time.h. DS52053B-page 341 . Its absolute value is the largest integer which is less than the absolute value of the mathematical quotient. The sign of the quotient is the same as that of the mathematical quotient.  2012 Microchip Technology Inc. uldiv(). } See Also div(). lt = ldiv(1234567. localtime() will return the same result as gmtime(). the difference being that the arguments and the members of the returned structure are all of type long int. The ldiv() function is similar to the div() function.h> ldiv_t ldiv (long number. The routine localtime() takes into account the contents of the global integer time_zone. long denom) Description The ldiv() routine divides the numerator by the denominator.h> void main (void) { ldiv_t lt.rem). 1970. This should contain the number of minutes that the local time zone is westward of Greenwich. remainder = %ld\n".h> #include <stdio.

f. .h> #include <time. f += 1. Note The example will require the user to provide the time() routine as one cannot be supplied with the compiler. struct tm * tp. wday[tp->tm_wday]).h> void main (void) { double f.0) printf("log(%1. "Wednesday".h> char * wday[] = { "Sunday". asctime().h> #include <stdio. "Tuesday". printf("Today is %s\n". "Saturday" }.0 . log(f)). for(f = 1. f <= 10. } See Also exp(). The function log10() returns the logarithm to base 10 of f. pow() DS52053B-page 342  2012 Microchip Technology Inc. LOG. tp = localtime(&clock). See time() for more detail.MPLAB® XC8 C Compiler User’s Guide Example #include <stdio. LOG10 Synopsis #include <math.h> double log (double f) double log10 (double f) Description The log() function returns the natural logarithm of f.0 . "Monday". "Thursday". time(&clock). time() Return Value Returns a structure of type tm.0f) = %f\n". } See Also ctime(). "Friday". Example #include <math. void main (void) { time_t clock.

void inner (void) { longjmp(jb. Breach of this rule will cause errors. } printf("setjmp returned 0 . inner(). the function that called setjmp() must still be active when longjmp() is called. LONGJMP Synopsis #include <setjmp. in conjunction with setjmp(). printf("calling inner. due to the use of a stack containing invalid data.Library Functions Return Value Zero if the argument is negative. exit(0). } void main (void) { int i. This should normally be non-zero. to distinguish it from the genuine setjmp() call. 5)..h> #include <stdlib. The val argument to longjmp() will be the value apparently returned from the setjmp(). provides a mechanism for non-local goto’s. longjmp() may be called with the same jmp_buf argument from an inner level of execution. To use this facility. To return to this level of execution..\n"). setjmp() should be called with a jmp_buf argument in some outer level function.  2012 Microchip Technology Inc.h> #include <setjmp.h> void longjmp (jmp_buf buf. int val) Description The longjmp() function. if(i = setjmp(jb)) { printf("setjmp returned %d\n" i). DS52053B-page 343 .good\n").h> jmp_buf jb. printf("inner returned . Example #include <stdio. However.bad!\n"). The call from setjmp() will return 0. } See Also setjmp() Return Value The longjmp() routine never returns.

h> #include <stdio. Breach of this rule will cause disaster. it searches a block of memory specified by length for a particular byte. size_t length) Description The memchr() function is similar to strchr() except that instead of searching null-terminated strings. ultoa() Return Value This routine returns a copy of the buffer into which the result is written. the value of the byte to be searched for.h> void * memchr (const void * block. . int val. MEMCHR Synopsis #include <string. 12345678L. utoa().MPLAB® XC8 C Compiler User’s Guide Note The function which called setjmp() must still be active when longjmp() is called. buf). and the length of the block. LTOA Synopsis #include <stdlib. 16). printf("The buffer holds %s\n". The conversion is performed according to the radix specified in base. DS52053B-page 344  2012 Microchip Technology Inc. Example #include <stdlib. Its arguments are a pointer to the memory to be searched.h> void main (void) { char buf[10]. buf is assumed to reference a buffer which has sufficient space allocated to it. A pointer to the first occurrence of that byte in the block is returned. due to the use of a stack containing invalid data. } See Also strtol(). ltoa(buf. itoa(). long val.h> char * ltoa (char * buf. int base) Description The function ltoa converts the contents of val into a string which is stored into buf.

0x23}. else printf("Equal\n"). if(!cp) printf("Not found\n"). cow[1] = 3. if(i < 0) printf("Less than\n"). 5. 0x6789. cow[0] = 1. void main (void) { char * cp. MEMCMP Synopsis #include <string.h> void main (void) { int buf[10]. buf[2] = 4. cp . 0x89. }  2012 Microchip Technology Inc. 3*sizeof(int)). size_t n) Description The memcmp() function compares two blocks of memory.h> int memcmp (const void * s1. else if(i > 0) printf("Greater than\n"). i = memcmp(buf. and returns a signed value similar to strncmp(). const void * s2.h> unsigned int ary[] = {1.(char *)ary).h> #include <stdio.Library Functions Example #include <string. cow[10]. of length n. Example #include <stdio. cow. Unlike strncmp() the comparison does not stop on a null character. sizeof ary). i. buf[0] = 1. buf[1] = 3. cp = memchr(ary. cow[2] = 5. NULL otherwise. DS52053B-page 345 .h> #include <string. else printf("Found at offset %u\n". } See Also strchr() Return Value A pointer to the first byte matching the argument if one exists.

memset() Return Value The memcpy() routine returns its first argument. strchr(). strchr().h> void main (void) { char buf[80]. 10). memcpy() DS52053B-page 346  2012 Microchip Technology Inc. memset(). 0. See Also strncpy(). sizeof buf). printf("buf = ’%s’\n".MPLAB® XC8 C Compiler User’s Guide See Also strncpy(). memchr() Return Value Returns negative one. "A partial string".h> void * memcpy (void * d. strchr(). } See Also strncpy(). buf). strncmp(). . strncmp(). MEMCPY Synopsis #include <string. it will copy forwards or backwards as appropriate to correctly copy one block to another that overlaps it. strncmp(). MEMMOVE Synopsis #include <string. memset(buf. equal to or greater than the string pointed to by s2 in the collating sequence.h> #include <stdio. That is. size_t n) Description The memmove() function is similar to the function memcpy() except copying of overlapping blocks is handled correctly. depending on whether s1 points to string which is less than. const void * s2. memcpy(buf. Example #include <string. size_t n) Description The memcpy() function copies n bytes of memory starting from the location pointed to by s to the block of memory pointed to by d.h> void * memmove (void * s1. rather than all bytes up to a null terminator. The result of copying overlapping blocks is undefined. const void * s. zero or one. The memcpy() function differs from strcpy() in that it copies a specified number of bytes.

Example #include <string. strchr(). memcpy(). "This is a string". printf("buf = ’%s’\n".Library Functions Return Value The function memmove() returns its first argument. memset(abuf. size_t n) Description The memset() function fills n bytes of memory starting at the location pointed to by s with the byte c. } See Also strncpy().h> void main (void) { char abuf[20]. int c. MEMSET Synopsis #include <string. abuf). memchr() MKTIME Synopsis #include <time.  2012 Microchip Technology Inc. strncmp(). 5).h> #include <stdio. 1970. ’x’. DS52053B-page 347 . or returns -1 if the time cannot be represented.h> time_t mktime (struct tm * tmptr) Description The mktime() function converts and returns the local calendar time referenced by the tm structure tmptr into a time being the number of seconds passed since Jan 1.h> void * memset (void * s. strcpy(abuf.

or -1 if this time cannot be represented. asctime() Return Value The time contained in the tm structure represented as the number of seconds since the 1970 Epoch. MODF Synopsis #include <math.tm_year = 83. birthday.h> double modf (double value.tm_sec = 0. Example #include <math. The integral part is stored as a double in the object pointed to by iptr.tm_mday = 5.17 would be split into the integral part (-3) and the fractional part (-0. mktime(&birthday)).h> #include <stdio. .17).tm_min = birthday. f_val.tm_hour = birthday. } See Also ctime(). f_val = modf( -3. // the 5th of May 1983 birthday. birthday. For example. printf("you were born approximately %ld seconds after the unix epoch\n".17. each having the same sign as value.tm_mon = 5. DS52053B-page 348  2012 Microchip Technology Inc. double * iptr) Description The modf() function splits the argument value into integral and fractional parts. &i_val).h> #include <stdio. birthday.MPLAB® XC8 C Compiler User’s Guide Example #include <time. } Return Value The signed fractional part of value. -3.h> void main (void) { double i_val.h> void main (void) { struct tm birthday.

Description Execute NOP instruction here. } }  2012 Microchip Technology Inc. DS52053B-page 349 .Library Functions NOP Synopsis #include <xc.h> NOP(). Example #include <xc.h> void crude_delay(unsigned char x) { while(x--){ NOP(). /* Do nothing for 3 cycles */ NOP(). The NOP instruction is sometimes required during some sensitive sequences in hardware. NOP(). This is often useful to fine tune delays or create a handle for breakpoints.

PRINTF.h> double pow (double f. f. It relies on the putch() function to determine the destination of stdout. f += 1.h> int printf (const char * fmt.0 .h> #include <stdio. as well as code to initialize any peripherals used by this routine. . f. f)). Example #include <math. log10().h> #include <stdarg. f <= 10. operating on stdout. A stub for putch can be found in the sources directory of the compiler. } See Also log().) #include <stdio.0 . double p) Description The pow() function raises its first argument.. for(f = 1. pow(2. to the power p. DS52053B-page 350  2012 Microchip Technology Inc..MPLAB® XC8 C Compiler User’s Guide POW Synopsis #include <math. exp() Return Value f to the power of p. va_list va_arg) Description The printf() function is a formatted output routine.0) printf("pow(2. %1. TXREG = data.0f) = %f\n".h> int vprintf (const char * fmt. } Include the source file for putch into your project once it is complete. void putch(char data) { while( ! TXIF) continue. The putch() function must be written as part of each project. A typical putch routine to send one byte to the USART may need to be written similar to the following.h> void main (void) { double f. . VPRINTF Synopsis #include <stdio.

The vprintf() function is similar to printf() but takes a variable argument list rather than a list of arguments. A hash character (#) preceding the width indicates that an alternate format is to be used. and may be used to force leading zeroes. Any other characters used as conversion specifications will be printed. in a field m characters wide. See the description of va_start() for more information on variable argument lists. the precision indicates a minimum number of digits to be output. When the alternate format is specified.4x will print at least 4 HEX digits in an 8 wide field. For integer formats. Where right adjustment of a numeric conversion is specified. c The argument is assumed to be a single character and is printed literally. The nature of the alternate format is discussed below. then one integer argument will be taken from the list to provide that value. each of which is used to print out one of the argument list values. Any trailing zeros after the decimal point will be removed. e.m is the total width and n is the number of digits after the decimal point. Preceding the key letter with an l indicates that the value argument is a long integer. In those cases.  2012 Microchip Technology Inc.. followed by a list of zero or more arguments. s Print a string . the presence of the hash character has no effect. and a leading 0x or 0X for the HEX format. If the precision is zero. blank padding is performed at the left or right as specified. unsigned otherwise. In the format string are conversion specifications.in radices 8. in the format %*d. it will also be removed. An example of using vprintf() follows. The precision value is the total number of digits to print. Where the field width is larger than required for the conversion. the decimal point will be omitted unless the alternate format is specified. Each conversion specification is of the form %m. and if no digits remain after the decimal point. The n specification is an optional precision specification (introduced by the dot) and c is a letter specifying the type of the conversion.the value argument is assumed to be a character. A minus sign (’-’) preceding m indicates left rather than right adjustment of the converted value in the field. then padding will be performed with zeroes rather than blanks. The types of conversion are: f Floating point . Not all formats have alternates. For example. 16. If the character * is used in place of a decimal constant. Otherwise similar to f. DS52053B-page 351 .f as would be printed when using x. a leading zero will be supplied for the octal format.g.nc where the percent symbol % introduces a conversion. o x X u d Integer conversion . At most n characters from the string will be printed. and the first digit of m is 0. whichever gives maximum precision in minimum width. If n is omitted it defaults to 6. The conversion is signed in the case of d. 10 and 10 respectively. followed by an optional width specification m. with leading zeros inserted to make up this number if required. e Print the corresponding argument in scientific notation. 16.Library Functions The printf() routine is passed a format string. %8. g Use e or f format. Thus % will produce a single percent sign. The letter X prints out hexadecimal numbers using the upper case letters A-F rather than a.

"a1234567890"). PUTCH Synopsis #include <conio. s). error("testing 1 2 %d". prints size as hexadecimal. Typically this function will accept one byte of data and send this to a peripheral which is associated with stdout. printf("Name = %. yields ’xx 4’ /* vprintf example */ #include <stdio. ap). 23). i).. va_start(ap.) { va_list ap. where size is a long. size).MPLAB® XC8 C Compiler User’s Guide Example printf("Total = %4d%". printf("Error: "). va_end(ap). i = 3.. yields ’Total = 23%’ printf("Size is %lx". . 4). putchar(’\n’). } See Also sprintf() Return Value The printf() and vprintf() functions return the number of characters written to stdout. yields ’Name = a1234567’ printf("xx%*d".h> void putch (char c) Description The putch() function is provided as an empty stub which can be completed as each project requires. 3. } void main (void) { int i. . DS52053B-page 352  2012 Microchip Technology Inc.h> int error (char * s. vprintf(s.8s".

putchar(’\n’). putch(’\n’).h> char * x = "This is a string". or EOF if an error occurred. and is defined in stdio. while(*x) putch(*x++). freopen(). getc().h> int putchar (int c) Description The putchar() function calls putch() to print one character to stdout. } See Also printf(). cp = x. } See Also putc(). void main (void) { char * cp. DS52053B-page 353 .  2012 Microchip Technology Inc. cp = x. fclose() Return Value The character passed as argument. while(*x) putchar(*x++). void main (void) { char * cp.h.h> char * x = "This is a string". putchar() PUTCHAR Synopsis #include <stdio. Example #include <stdio.Library Functions Example #include <conio.

The null character terminating the string is not copied.h> int puts (const char * s) Description The puts() function writes the string s to the stdout stream. gets().h> void main (void) { puts("Hello. QSORT Synopsis #include <stdlib. int (*func)(const void *. equal to zero or less than zero respectively. freopen(). } See Also fputs(). DS52053B-page 354  2012 Microchip Technology Inc. const void *)) Description The qsort() function is an implementation of the quicksort algorithm.h> void qsort (void * base. appending a newline. each of length width bytes. fclose() Return Value EOF is returned on error. size_t nel. It sorts an array of nel items.MPLAB® XC8 C Compiler User’s Guide PUTS Synopsis #include <stdio. Example #include <stdio. The argument func is a pointer to a function used by qsort() to compare items. located contiguously in memory at base. If the first item is considered to be greater than. zero otherwise. size_t width. world!"). . equal to or less than the second then func should return a value greater than zero. It calls func with s to two items to be compared.

The algorithm will produce a deterministic sequence if started from the same point. sortem). 23.h> int array[] = { 567.  2012 Microchip Technology Inc. 456.*(int *)p2. 1024. 567.h> int rand (void) Description The rand() function is a pseudo-random number generator.h> #include <stdlib. for(i = 0 . The example shows use of the time() function to generate a different starting point for the sequence each time. It returns an integer in the range 0 to 32767. which changes in a pseudo-random fashion on each call. RAND Synopsis #include <stdlib. const void * p2) { return *(int *)p1 . const void *) For example. qsort(aray. and must be prototyped. sizeof array[0]. } void main (void) { register int i. i != sizeof array/sizeof array[0] . int sortem (const void * p1. sizeof array/sizeof array[0]. The starting point is set using the srand() call.Library Functions Example #include <stdio. 66 }. 17. array[i]). i++) printf("%d\t". it must accept two const void * parameters. putchar(’\n’). DS52053B-page 355 . } Note The function parameter must be a pointer to a function of type similar to: int func (const void *.

h> double round (double x) Description The round function round the argument to the nearest integer value. } See Also trunc() DS52053B-page 356  2012 Microchip Technology Inc.h> void main (void) { time_t toc. i++) printf("%d\t". See time() for more detail. rounded.5678. Values midway between integer values are rounded up. srand((int)toc). Example #include <math.h> #include <time. i != 10 . putchar(’\n’). time(&toc). for(i = 0 . } See Also srand() Note The example will require the user to provide the time() routine as one cannot be supplied with the compiler.h> #include <stdio. . but in floating-point format. ROUND Synopsis #include <math.MPLAB® XC8 C Compiler User’s Guide Example #include <stdlib. input = 1234. int i. rounded = round(input).h> void main (void) { double input. rand()).

printf("calling inner. 5).h> jmp_buf jb.. } See Also longjmp() Return Value The setjmp() function returns zero after the real call. i). void inner (void) { longjmp(jb. inner(). Example #include <stdio. exit(0). if(i = setjmp(jb)) { printf("setjmp returned %d\n". } void main (void) { int i. See longjmp() for further information.  2012 Microchip Technology Inc.Library Functions SETJMP Synopsis #include <setjmp.h> double sin (double f) Description This function returns the sine function of its argument. and non-zero if it apparently returns after a call to longjmp().\n"). } printf("setjmp returned 0 .h> int setjmp (jmp_buf buf) Description The setjmp() function is used with longjmp() for non-local goto’s.good\n").h> #include <setjmp. SIN Synopsis #include <math. printf("inner returned . DS52053B-page 357 .h> #include <stdlib.bad!\n")..

0f) = %f\n".h> int vsprintf (char * buf.) #include <stdio.h> extern void init(void). atan2() Return Value Sine vale of f. cos(i*C)).h> #include <stdio. Example #include <xc. va_list ap) DS52053B-page 358  2012 Microchip Technology Inc. void main (void) { init(). const char * fmt.. const char * fmt.h> SLEEP(). printf("cos(%3. asin(). i += 10) printf("sin(%3. ..141592/180. /* enable peripherals/interrupts */ while(1) SLEEP().h> #include <stdarg. Description This macro is used to put the device into a low-power standby mode.h> #define C 3. acos().MPLAB® XC8 C Compiler User’s Guide Example #include <math. i. . } See Also cos().0f) = %f\n". SLEEP Synopsis #include <xc. i <= 180. sin(i*C)). tan().0 void main (void) { double i. VSPRINTF Synopsis #include <stdio.h> int sprintf (char * buf. } /* save power while nothing happening */ SPRINTF. for(i = 0 . atan(). i.0 .

See Also printf().  2012 Microchip Technology Inc. i <= 20.h> void main (void) { double i. and the number of characters in the buffer will be returned. Note A domain error occurs if the argument is negative and errno will be set to EDOM. The resultant string will be null terminated. the characters are placed in the buffer at buf. implements a square root routine using Newton’s approximation. i += 1.Library Functions Description The sprintf() function operates in a similar fashion to printf(). Example #include <math. except that instead of placing the converted output on the stdout stream.1f = %f\n". sscanf() Return Value Both these routines return the number of characters placed into the buffer.h> double sqrt (double f) Description The function sqrt().0 . The vsprintf() function is similar to sprintf() but takes a variable argument list parameter rather than a list of arguments. } See Also exp() Return Value Returns the value of the square root. for(i = 0 . sqrt(i)). DS52053B-page 359 .0) printf("square root of %. See the description of va_start() for more information on variable argument lists. SQRT Synopsis #include <math. i.h> #include <stdio.

MPLAB® XC8 C Compiler User’s Guide SRAND Synopsis #include <stdlib. DS52053B-page 360  2012 Microchip Technology Inc. i++) printf("%d\t". } See Also rand() SSCANF. Example #include <stdlib. fscanf(). for(i = 0 .h> void main (void) { time_t toc. time(&toc). va_list ap) Description The sscanf() function operates in a similar manner to scanf(). . sprintf() Return Value Returns the value of EOF if an input failure occurs. putchar(’\n’). . srand((int)toc).. they are taken from the string at buf.h> #include <stdarg. This provides a mechanism for varying the starting point of the pseudo-random sequence yielded by rand(). i != 10 .h> #include <stdio. rand()).) #include <stdio.h> int vsscanf (const char * buf. const char * fmt. const char * fmt..h> int sscanf (const char * buf. int i.h> #include <time. The vsscanf() function takes an argument. except that instead of the conversions being taken from stdin. See Also scanf(). See the description of va_start() for more information on variable argument lists.h> void srand (unsigned int seed) Description The srand() function initializes the random number generator accessed by rand() with the given seed. else returns the number of input items. rather than a list of arguments. VSSCANF Synopsis #include <stdio.

strcpy(buffer. The argument s1 must point to a character array big enough to hold the resultant string.. otherwise NULL is returned.. STRCHR. printf("string = \"%s\"\n". STRICHR Synopsis #include <string. * s2. s2). int c) char * strichr (const char * s.Library Functions STRCAT Synopsis #include <string. char * s1. end of line". buffer).h> #include <stdio. "Start of line"). a pointer to that character is returned. The strichr() function is the case-insensitive version of this function. DS52053B-page 361 . printf("Length = %d\n". strcat(s1.h> char * strchr (const char * s.  2012 Microchip Technology Inc. const char * s2) Description This function appends (concatenates) string s2 to the end of string s1. The result will be null terminated.h> char * strcat (char * s1. strncat(). } See Also strcpy(). Example #include <string.h> void main (void) { char buffer[256]. s2 = ". strlen(buffer)). strcmp(). s1 = buffer. strlen() Return Value The value of s1 is returned. If one is found. int c) Description The strchr() function searches the string s for an occurrence of the character c.

h> int strcmp (const char * s1. Note Although the function takes an integer argument for the character. const char * s2) Description The strcmp() function compares its two.h> void main (void) { int i.. c). Example #include <string. const char * s2) int stricmp (const char * s1. else printf("No character was found in string"). or NULL if the character does not exist in the string. } See Also strrchr(). only the lower 8 bits of the value are used. STRCMP. "ABc")) < 0) printf("ABC is less than ABc\n"). else if(i > 0) printf("ABC is greater than ABc\n"). if(strchr(temp. if((i = strcmp("ABC". The comparison is done with the standard collating sequence. c)) printf("Character %c was found in string\n". else printf("ABC is equal to ABc\n"). null terminated. strcmp() Return Value A pointer to the first match found. string arguments and returns a signed integer to indicate whether s1 is less than. which is that of the ASCII character set.". } DS52053B-page 362  2012 Microchip Technology Inc. The stricmp() function is the case-insensitive version of this function.MPLAB® XC8 C Compiler User’s Guide Example #include <strings.h> #include <stdio. char c = ’s’.h> #include <stdio. .. equal to or greater than s2. STRICMP Synopsis #include <string. strlen().h> void main (void) { static char temp[] = "Here it is.

h> void main (void) { char buffer[256]. strlen() Return Value The destination buffer s1 is returned. * s2. strncmp(). the return value is negative.h> char * strcpy (char * s1. end of line". const char * s2) Description This function copies a null terminated string s2 to a character array pointed to by s1..Library Functions See Also strlen().. s2). printf("Length = %d\n". const char * s2) Description The strcspn() function returns the length of the initial segment of the string pointed to by s1 which consists of characters NOT from the string pointed to by s2. strlen(buffer)). strcat() Return Value A signed integer less than.e. char * s1. buffer). s2 = ".. i.  2012 Microchip Technology Inc. STRCPY Synopsis #include <string. strcpy(buffer. STRCSPN Synopsis #include <string. or positive. s1 = buffer. "Start of line"). The destination array must be large enough to hold the entire string. including the null terminator. DS52053B-page 363 . equal to or greater than zero. Note Other C implementations may use a different collating sequence. strcpy(). printf("string = \"%s\"\n". strlen().h> size_t strcspn (const char * s1. do not test explicitly for negative one (-1) or one (1). Example #include <string. zero.h> #include <stdio. strcat(). strcat(s1. } See Also strncpy().

printf("%d\n". s2).h> #include <stdio. set)). strcspn("xxxbcadefs". strcat(s1.. strcspn("1234567890".h> #include <string. s2 = ". strlen(buffer)). } Return Value The number of characters preceding the null terminator.. strcspn("abcdevwxyz". buffer). printf("%d\n". s1 = buffer.h> void main (void) { char buffer[256]. STRLEN Synopsis #include <string. printf("%d\n".h> size_t strlen (const char * s) Description The strlen() function returns the number of characters in the string s. set)). printf("Length = %d\n". not including the null terminator. strcpy(buffer. char * s1. Example #include <string. DS52053B-page 364  2012 Microchip Technology Inc. set)). .h> void main (void) { static char set[] = "xyz". * s2. "Start of line"). } See Also strspn() Return Value Returns the length of the segment. end of line". printf("string = \"%s\"\n".MPLAB® XC8 C Compiler User’s Guide Example #include <stdio.

strcat(). size_t n) Description This function appends (concatenates) string s2 to the end of string s1. buffer). STRNICMP Synopsis #include <string. The comparison is done with the standard collating sequence. printf("string = \"%s\"\n".h> #include <stdio. printf("Length = %d\n". up to a maximum of n characters. strlen() Return Value The value of s1 is returned. and returns a signed integer to indicate whether s1 is less than. null terminated. char * s1. 5). strncat(s1. s2 = ".Library Functions STRNCAT Synopsis #include <string. Example #include <string. s2. "Start of line"). end of line". s1 must point to a character array big enough to hold the resultant string. const char * s2. size_t n) Description The strncmp() function compares its two.. const char * s2. equal to or greater than s2. size_t n) int strnicmp (const char * s1.h> char * strncat (char * s1.h> void main (void) { char buffer[256]. const char * s2.. string arguments.  2012 Microchip Technology Inc. STRNCMP. DS52053B-page 365 .h> int strncmp (const char * s1. strcpy(buffer. strlen(buffer)). } See Also strcpy(). which is that of the ASCII character set. At most n characters will be copied. s1 = buffer. and the result will be null terminated. strcmp(). The strnicmp() function is the case-insensitive version of this function. * s2.

zero. equal to or greater than zero. printf("Length = %d\n". s2). * s2. Note Other C implementations may use a different collating sequence. . const char * s2.e. or positive. do not test explicitly for negative one (-1) or one (1). 6). "Start of line". strcpy(). The destination array must be large enough to hold the entire string.h> char * strncpy (char * s1. At most n characters are copied.. end of line". } DS52053B-page 366  2012 Microchip Technology Inc.. i. "abcxyz". the return value is negative. size_t n) Description This function copies a null terminated string s2 to a character array pointed to by s1.h> #include <stdio. strncpy(buffer. i = strncmp("abcxyz". strcat() Return Value A signed integer less than. Example #include <string. STRNCPY Synopsis #include <string. including the null terminator.h> #include <string. printf("string = \"%s\"\n". strcat(s1.. strlen(buffer)). s1 = buffer. If string s2 is longer than n then the destination string will not be null terminated.h> void main (void) { char buffer[256]. char * s1. s2 = ". buffer). else if(i > 0) printf("String 2 less than string 1\n"). else printf("String 2 is greater than string 1\n").MPLAB® XC8 C Compiler User’s Guide Example #include <stdio. if(i == 0) printf("The strings are equal\n").h> void main (void) { int i. strcmp(). 6). } See Also strlen().

If successful it returns a pointer to that occurrence. const char * s2) Description The strpbrk() function returns a pointer to the first occurrence in string s1 of any character from string s2.h> char * strpbrk (const char * s1. int c) char * strrichr (char * s.h> #include <string. "aeiou"). The strrichr() function is the case-insensitive version of this function. while(str != NULL) { printf("%s\n". STRRCHR. int c) Description The strrchr() function is similar to the strchr() function.". but searches from the end of the string rather than the beginning. strcmp() Return Value The destination buffer s1 is returned.  2012 Microchip Technology Inc.h> void main (void) { char * str = "This is a string. STRRICHR Synopsis #include <string. STRPBRK Synopsis #include <string. str). str = strpbrk(str+1. i.h> char * strrchr (char * s. or NULL if no character found. strlen()..e. Example #include <stdio. otherwise it returns NULL. } } Return Value to the first matching character.Library Functions See Also strcpy(). or a null if no character from s2 exists in s1. DS52053B-page 367 . it locates the last occurrence of the character c in the null terminated string s. strcat().

str). STRISTR Synopsis #include <string. STRSTR.h> void main (void) { char * str = "This is a string. Example #include <stdio. const char * s2) DS52053B-page 368  2012 Microchip Technology Inc. strlen(). } } See Also strchr(). strcmp(). } See Also strcspn() Return Value The length of the segment. ’s’). const char * s2) Description The strspn() function returns the length of the initial segment of the string pointed to by s1 which consists entirely of characters from the string pointed to by s2. STRSPN Synopsis #include <string.".MPLAB® XC8 C Compiler User’s Guide Example #include <stdio.h> #include <string.h> void main (void) { printf("%d\n". or NULL if none is found.h> size_t strspn (const char * s1. strcat() Return Value A pointer to the character. printf("%d\n".h> char * strstr (const char * s1. "This")). str = strrchr(str+1. strspn("This is a string". const char * s2) char * stristr (const char * s1. . while(str != NULL) { printf("%s\n". strcpy().h> #include <string. strspn("This is a string". "this")).

} See Also atof() Return Value Returns a double representing the floating-point value of the converted input string. Example #include <stdio. The stristr() routine is the case-insensitive version of this function. If res is not NULL.27". in2.h> double strtok (const char * s. STRTOD Synopsis #include <stdlib. strstr("This is a string". Example #include <stdio. This function converts the first occurrence of a substring of the input that is made up of characters of the expected form after skipping leading white-space characters.h> #include <string. %f\n". double in1.h> #include <strlib.h> void main (void) { printf("%d\n". in2). it will be made to point to the first character after the converted sub-string.7 char * end. DS52053B-page 369 . printf("in comps: %f. "str")). in1. const char ** res) Description Parse the string s converting it to a double floating-point type.Library Functions Description The strstr() function locates the first occurrence of the sequence of characters in the string pointed to by s2 in the string pointed to by s1. in2 = strtod(end. in1 = strtod(buf. 23. } Return Value to the located string or a null if the string was not found. NULL).  2012 Microchip Technology Inc. &end).h> void main (void) { char buf[] = "35.

h> char * strtok (char * s1. &end. For subsequent calls to strtok(). which terminates the current token. These calls start searching from the end of the last token found. in2). const char ** res. char * end. in2. Example #include <stdio.h> #include <strlib. %ld\n". The inter-token separator character is overwritten by a null character. printf("in (decimal): %ld.h> void main (void) { char buf[] = "0X299 0x792". int base) Description Parse the string s converting it to a long integer type. 16). or NULL if no tokens were found. or NULL if no further tokens were found. NULL. } See Also strtod() Return Value Returns a long int representing the value of the converted input string using the specified base. The radix of the input is determined from base. DS52053B-page 370  2012 Microchip Technology Inc. If this is zero.h> double strtol (const char * s. s1 should be set to a NULL. then the radix defaults to base 10. long in1. and again return a pointer to the first character of the next token. The first call must have the string s1. in2 = strtol(end. in1 = strtol(buf. const char * s2) Description A number of calls to strtok() breaks the string s1 (which consists of a sequence of zero or more text tokens separated by one or more characters from the separator string s2) into its separate tokens. 16). STRTOK Synopsis #include <string. it will be made to point to the first character after the converted sub-string. If res is not NULL. . in1. This function converts the first occurrence of a substring of the input that is made up of characters of the expected form after skipping leading white-space characters.MPLAB® XC8 C Compiler User’s Guide STRTOL Synopsis #include <stdlib. This call returns a pointer to the first character of the first token.

141592/180. i <= 180. sep_tok). while(ptr != NULL) { printf("%s\n".". or a null if no token was found. ptr = strtok(NULL. char buf[] = "This is a string of words.  2012 Microchip Technology Inc. for(i = 0 .h> void main (void) { char * ptr.h> #include <stdio.h> #include <string. Example #include <math. asin(). atan2() Return Value The tangent of f.?! " ptr = strtok(buf. i. atan(). Note The separator string s2 may be different from call to call. tan(i*C)). char * sep_tok = ". sep_tok).h> #define C 3.Library Functions Example #include <stdio.h> double tan (double f) Description The tan() function calculates the tangent of f. TAN Synopsis #include <math. ptr). acos(). cos(). DS52053B-page 371 . } } Return Value Returns a pointer to the first character of a token.0 void main (void) { double i.0f) = %f\n". i += 10) printf("tan(%3.0 . } See Also sin().

1970. If the argument t is not equal to NULL. asctime() Return Value This routine when implemented will return the current time in seconds since 00:00:00 on Jan 1. } See Also ctime(). this function should return the current time in seconds since 00:00:00 on Jan 1. . The functions toupper() and tolower() return their arguments if it is not an alphabetic character. time(&clock). gmtime().h> time_t time (time_t * t) Description This function is not provided as it is dependent on the target system supplying the current time.h> void main (void) { time_t clock. printf("%s". TOLOWER. Note The time() routine is not supplied. ctime(&clock)).h> #include <time. the same value is stored into the object pointed to by t. Example #include <stdio. This function will be user implemented.h> char toupper (int c) char tolower (int c) char toascii (int c) Description The toupper() function converts its lower case alphabetic argument to upper case. 1970.MPLAB® XC8 C Compiler User’s Guide TIME Synopsis #include <time. the tolower() routine performs the reverse conversion and the toascii() macro returns a result that is guaranteed in the range 0-0177. DS52053B-page 372  2012 Microchip Technology Inc. When implemented. localtime(). TOASCII Synopsis #include <ctype. if required the user will have to implement this routine to the specifications outlined above. TOUPPER.

TRUNC Synopsis #include <math. } See Also round() UDIV Synopsis #include <stdlib. } See Also islower(). that is not larger in magnitude than the argument. } printf("n"). in floating-point format. int i. tolower(array1[i])).i < strlen(array1).5678. storing the results into a udiv_t structure which is returned. isascii(). rounded = trunc(input). et.h> #include <string. Example #include <math. isupper(). al. rounded.Library Functions Example #include <stdio.  2012 Microchip Technology Inc. for(i=0. unsigned denom) Description The udiv() function calculate the quotient and remainder of the division of number and denom. ++i) { printf("%c". DS52053B-page 373 .h> void main (void) { double input.h> void main (void) { char * array1 = "aBcDE".h> int udiv (unsigned num.h> double trunc (double x) Description The trunc function rounds the argument to the nearest integer value. input = 1234.h> #include <ctype.

. storing the results into a uldiv_t structure which is returned. unsigned num = 1234. unsigned long num = 1234. div().h> void main (void) { udiv_t result. den). } See Also uldiv(). Example #include <stdlib. unsigned long denom) Description The uldiv() function calculate the quotient and remainder of the division of number and denom. den = 7.MPLAB® XC8 C Compiler User’s Guide Example #include <stdlib. result = udiv(num.h> void main (void) { uldiv_t result. udiv(). div() Return Value Returns the quotient and remainder as a uldiv_t structure. ldiv() Return Value Returns the quotient and remainder as a udiv_t structure. unsigned val. den). ULDIV Synopsis #include <stdlib.h> int uldiv (unsigned long num. den = 7. UTOA Synopsis #include <stdlib.h> char * utoa (char * buf. result = uldiv(num. } See Also ldiv(). int base) DS52053B-page 374  2012 Microchip Technology Inc.

16). a variable of type va_list should be declared.h> void va_start (va_list ap.). parmN) type va_arg (ap. In this example the function expects the subsequent parameters to be s to char. ultoa() Return Value This routine returns a copy of the buffer into which the result is written.. as it is the starting point for access to further parameters. The right most parameter to the function (shown as parmN) plays an important role in these macros. it should be accessed by va_arg(ap. ltoa(). the variable previously defined and a type name which is the type that the next parameter is expected to be. VA_START. In a function taking variable numbers of arguments.. printf("The buffer holds %s\n". VA_ARG. 1234. For example. buf). but note that the compiler is not aware of this. then the macro va_start() invoked with that variable and the name of parmN. if a character argument has been passed.  2012 Microchip Technology Inc. where type and number of arguments supplied to the function are not known at compile time. VA_END Synopsis #include <stdarg.Library Functions Description The function utoa() converts the unsigned contents of val into a string which is stored into buf. Note that any arguments thus accessed will have been widened by the default conventions to int. This will initialize the variable to allow subsequent calls of the macro va_arg() to access successive parameters. } See Also strtol(). int) since the char will have been widened to int. DS52053B-page 375 . The conversion is performed according to the radix specified in base. type) void va_end (va_list ap) Description These macros are provided to give access in a portable way to parameters to a function represented in a prototype by the ellipsis symbol (.h> #include <stdio. Example #include <stdlib. utoa(buf. unsigned int or double. An example is given below of a function taking one integer parameter.h> void main (void) { char buf[10]. and it is the programmers responsibility to ensure that correct arguments are supplied. Each call to va_arg() requires two arguments. buf is assumed to reference a buffer which has sufficient space allocated to it. itoa(). followed by a number of other parameters.

DS52053B-page 376  2012 Microchip Technology Inc. "Line 3").. and converts an ASCII representation of a hexadecimal number to an integer. . a).) { va_list ap. zero will be returned. buf. } XTOI Synopsis #include <stdlib. "Line 1". printf("Read %s: converted to %x\n". i = xtoi(buf).h> #include <stdarg. } void main (void) { pf(3. } See Also atoi() Return Value An unsigned integer. while(a--) puts(va_arg(ap.h> void pf (int a. int i.. va_start(ap.h> unsigned xtoi (const char * s) Description The xtoi() function scans the character string passed to it.h> void main (void) { char buf[80]. gets(buf). "Line 2".h> #include <stdio. char *)). If no number is found in the string. skipping leading blanks reading an optional sign. . Example #include <stdlib. va_end(ap).MPLAB® XC8 C Compiler User’s Guide Example #include <stdio. i).

(3) malformed error information on line *. or the message issue has not been translated into the selected language.8. You should attempt to resolve errors or warnings in the order in which they are produced. Most messages have been assigned a unique number which appears in brackets before each message description. for example: /* no #endif was found in this module */  2012 Microchip Technology Inc. The number of errors that can be accepted can be controlled using the --ERRORS option. This is the complete and historical message set covering all former HI-TECH C compilers and all compiler versions. } /* error flagged here */ (Preprocessor) A #if or similar block was not terminated with a matching #endif. in file *(all applications) The compiler has attempted to load the messages for the selected language. The use of * in the error message is used to represent a string that the compiler will substitute that is specific to that particular error. In some cases examples of code or options that could trigger the error are given. See Section 4. The name of the application(s) that could have produced the messages are listed in brackets opposite the error message. Error and Warning Messages This chapter lists the MPLAB XC8 C Compiler error. Note that one problem in your C or assembler source code may trigger more than one error message. Un-numbered messages appear toward the end and are sorted alphabetically. MESSAGES 1-249 (1) too many errors (*) (all applications) The executing compiler application has encountered too many errors and will exit immediately. DS52053B-page 377 . but the compiler applications that would normally be executed in due course will not be run. but there is no description available in the message description file (MDF) to print. but no description available (all applications) The executing compiler application has emitted a message (advisory/warning/error). Not all messages shown here may be relevant for the compiler version you are using.29 “--ERRORS: Maximum Number of Errors”. warning and advisory messages with an explanation of each message.MPLAB® XC8 C COMPILER USER’S GUIDE Appendix B. Other uncompiled source files will be processed. (2) error/warning (*) generated. but the message description file (MDF) was corrupted and could not be read correctly. The messages shown here are sorted by their number. (100) unterminated #if[n][def] block from line * #if INPUT void main(void) { run(). This may be because the MDF is out of date. and which is also printed by the compiler when the message is issued.

This is a programmer induced error. This is normally used to check compile time defines etc. If there is an apparently corresponding #if line. . #endif /* the #endif above terminated the #if */ (103) #error: * (Preprocessor) This is a programmer generated error. for example: void cleardog(void) { clrwdt #endasm /* in-line assembler ends here. for example: #ifdef FOO result = foo. but there was no previous matching #asm. These can only follow a #if. there is a directive causing a deliberate error. (104) preprocessor #assert failure (Preprocessor) The argument to a preprocessor #assert directive has evaluated to zero. #assert SIZE == 4 /* size should never be 4 */ (105) no #asm before #endasm (Preprocessor) A #endasm operator has been encountered. for example: #asm MOVE r0. #else result = bar. for example: #ifdef FOO result = foo. #elif defined(NEXT) result = next(0). Check for a missing or misspelled #endasm directive. #else or #endif directive must be preceded by a matching #if line. previous #asm must be closed before opening another SLEEP #endasm DS52053B-page 378  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide (101) #* may not follow #else (Preprocessor) A #else or #elif has been used in the same conditional block as a #else. or improperly terminated comments. only where did it begin? */ } (106) nested #asm directives (Preprocessor) It is not legal to nest #asm directives. #endif /* the #else above terminated the #if */ (102) #* must be in an #if (Preprocessor) The #elif. but first check as to why the directive is there. #endif result = bar. #elif defined(NEXT) result = next(0). Remove the directive to remove the error. check for things like extra #endif’s. #0aah #asm .

for example: (115) recursive preprocessor macro definition of "*" defined by "*" (Preprocessor) The named macro has been defined in such a manner that expanding it causes a recursive expansion of itself. It is probably a misspelling of a pre-device # directive. #ifdef and #ifndef must have an argument. The argument to #include must be a valid file name. while the argument to #ifdef or #ifndef should be a single name. for example: #define FOO(a. and the closing quote or bracket must be present. Contact Microchip Technical Support if the preprocessor is being executed by a compiler driver. either enclosed in double quotes "" or angle brackets < >. 2b) /* 2b is not to be! */ (113) unterminated string in preprocessor macro body (Preprocessor. usage: cpp [input [output]] (Preprocessor) CPP should be invoked with at most two file arguments.should be: #include <stdio. It must start with a letter. for example: #indef DEBUG /* oops -.Error and Warning Messages (107) illegal # directive "*" (Preprocessor. If you want to deliberately redefine a macro. */ #define ONE one (112) #define syntax error (Preprocessor) A macro definition has a syntax error. Parser) The compiler does not understand the # directive.h /* oops -. DS52053B-page 379 . The argument to #if should be an expression.that should be #undef DEBUG */ (108) #if[n][def] without an argument (Preprocessor) The preprocessor directives #if. There should be nothing else on the line other than comments. use #undef first to remove the original definition. for example: #if /* oops -. for example: #define ONE 1 /* elsewhere: */ /* Is this correct? It will overwrite the first definition. This could be due to a macro or formal parameter name that does not start with a letter or a missing closing parenthesis.h> */ (110) too many file arguments. for example: #include stdio.no argument to check */ output = 10. #else output = 20. (114) illegal #undef argument #undef 6YYY /* this isn’t a valid symbol name */ (Preprocessor) The argument to #undef must be a valid name. (111) redefining preprocessor macro "*" (Preprocessor) The macro specified is being redefined. Spaces should not be included. Assembler) A macro definition contains a string that lacks a closing quote. #endif (109) #include syntax error (Preprocessor) The syntax of the filename argument to #include is invalid. to something different to the original definition. ). 2b) bar(a.  2012 Microchip Technology Inc.

for example: #if ((A) + (B) /* oops -. Simplify the expression – it probably contains too many parenthesized subexpressions. It is possible for very complex expressions to overflow this. b) func(a+b) FUNC(5. for example: #if FOO BAR /* oops -. . The line number given is the line where the macro argument started.did you mean: #if FOO == BAR ? */ (118) stack overflow processing #if expression (Preprocessor) The preprocessor filled up its expression evaluation stack in a #if expression. for example: #if YYY /* what are these characters doing here? */ int m.MPLAB® XC8 C Compiler User’s Guide (116) end of file within preprocessor macro argument from line * (Preprocessor) A macro argument has not been terminated. digits and those comprising the acceptable operators. Check the expression for correct parenthesizing. 6. This probably means the closing parenthesis has been omitted from a macro invocation. (119) invalid expression in #if line (Preprocessor) This is an internal compiler error. Valid characters are the letters. I think */ #define ADDED #endif (123) misplaced "?" or ":".a missing ). /* oops -. #endif DS52053B-page 380  2012 Microchip Technology Inc. for example: #define FUNC(a. (122) unbalanced parenthesis at operator "*" (Preprocessor) The evaluation of a #if expression found mismatched parentheses. previous operator is "*" (Preprocessor) A colon operator has been encountered in a #if expression that does not match up with a corresponding ? operator. Simplify the expression. This error is most probably caused by omission of an operator.where is the closing bracket? */ (117) misplaced constant in #if (Preprocessor) A constant in a #if expression should only occur in syntactically correct places. Contact Microchip Technical Support with details. for example: #if FOO * % BAR == 4 #define BIG #endif /* what is "* %" ? */ (121) expression stack overflow at operator "*" (Preprocessor) Expressions in #if lines are evaluated using a stack with a size of 128. for example: #if XXX : YYY /* did you mean: #if COND ? XXX : YYY */ (124) illegal character "*" in #if (Preprocessor) There is a character in a #if expression that has no business being there. (120) operator "*" in incorrect context (Preprocessor) An operator has been encountered in a #if expression that is incorrectly placed (two binary operators are not separated by a value).

Valid characters are the letters. for example: #if ^S YYY int m. for example: #if FOO == \34 #define BIG #endif (Preprocessor) (130) unknown type "*" in #[el]if sizeof() (Preprocessor) An unknown type was used in a preprocessor sizeof(). The name must start with a letter and should be enclosed in parentheses. The preprocessor can only evaluate sizeof() with basic types. for example: (129) unexpected "\" in #if The backslash is incorrect in the #if statement. for example: #if sizeof(unt) == 2 i = 0xFFFF. */ #if sizeof(signed unsigned int) == 2 i = 0xFFFF.Error and Warning Messages (125) illegal character (* decimal) in #if (Preprocessor) There is a non-printable character in a #if expression that has no business being there. #endif /* what is this control characters doing here? */ (126) strings can’t be used in #if /* no string operations allowed by the preprocessor */ #if MESSAGE > "hello" #define DEBUG #endif (Preprocessor) The preprocessor does not allow the use of strings in #if expressions. #endif (128) illegal operator in #if #if FOO = 6 (Preprocessor) /* oops -. DS52053B-page 381 . Check for correct syntax. that is the error. for example: /* To sign.defined expects a name. #endif /* should be: #if sizeof(int) == 2 */ (131) illegal type combination in #[el]if sizeof() (Preprocessor) The preprocessor found an illegal type combination in the argument to sizeof() in a #if expression. or pointers to basic types. or not to sign. digits and those comprising the acceptable operators. #endif  2012 Microchip Technology Inc. for example: /* oops -. not an expression */ #if defined(a&b) input = read(). for example: (127) bad syntax for defined() in #[el]if (Preprocessor) The defined() pseudo-function in a preprocessor expression requires its argument to be a single name.should that be: #if FOO == 5 ? */ A #if expression has an illegal operator.

the operands must be tokens containing only letters and digits. #endif // oops . (137) strange character "*" after ## (Preprocessor) A character has been seen after the token catenation operator ## that is neither a letter nor a digit. I’m not sure where I end. Since the result of this operator must be a legal token.MPLAB® XC8 C Compiler User’s Guide (132) no type specified in #[el]if sizeof() (Preprocessor) Sizeof() was used in a preprocessor #if expression. This is an internal error. for example: xc8 @communds should that be: xc8 @commands DS52053B-page 382  2012 Microchip Technology Inc. Code Generator. #endif /* oops -. b) a ## ’b (139) end of file in comment (Preprocessor) End of file was encountered inside a comment. for example: /* Here the comment begins.size of what? */ (133) unknown type code (0x*) in #[el]if sizeof() (Preprocessor) The preprocessor has made an internal error in evaluating a sizeof() expression. Probable causes are mismatched parentheses and similar things. Check for a missing closing comment flag. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. the operands must be tokens containing only letters and digits. . b) a ## ’b (138) strange character (*) after ## (Preprocessor) An unprintable character has been seen after the token catenation operator ## that is neither a letter nor a digit.should be: #if sizeof(int) == 2 (135) unknown operator (*) in #if (Preprocessor) The preprocessor has tried to evaluate an expression with an operator it does not understand. Confirm the spelling and path of the file specified on the command line. Preprocessor. for example: #if sizeof(int == 2) i = 0xFFFF. Check for a malformed type specifier. Assembler) The command file specified could not be opened for reading. (134) syntax error in #[el]if sizeof() (Preprocessor) The preprocessor found a syntax error in the argument to sizeof in a #if expression. though } (140) can’t open * file "*": * (Driver. for example: /* the ’ character will not lead to a valid token */ #define cc(a. but no type was specified. This is an internal error. Since the result of this operator must be a legal token. for example: #if sizeof() i = 0. for example: /* the ’ character will not lead to a valid token */ #define cc(a. or pointer to a simple type. The argument to sizeof() in a preprocessor expression must be a valid simple type.

(158) invalid disable in preprocessor macro "*" (Preprocessor) This is an internal compiler error. #ifdef etc. Contact Microchip Technical Support with details. The number of directories specified with the driver is too great. this is unlikely to happen. (152) bad dp/nargs in openpar(): c = * (Preprocessor) This is an internal compiler error. Since this buffer is 4096 bytes long. (157) can’t allocate * bytes of memory (Code Generator. DS52053B-page 383 .  2012 Microchip Technology Inc. Contact Microchip Technical Support with details.Error and Warning Messages (141) can’t open * file "*": * (Any) An output file could not be created. (146) #include filename too long (Preprocessor) (Preprocessor) A filename constructed while looking for an include file has exceeded the length of an internal buffer. Contact Microchip Technical Support with details. (155) work buffer overflow concatenating "*" (Preprocessor) This is an internal compiler error. blocks may only be nested to a maximum of 32. Contact Microchip Technical Support with details. (159) too many calls to unget() (Preprocessor) This is an internal compiler error. (150) illegal "__" preprocessor macro "*" (Preprocessor) This is an internal compiler error. This table is normally 32768 bytes long. This buffer is normally 4096 bytes long. Contact Microchip Technical Support with details. as per the C Standard. (151) too many arguments in preprocessor macro expansion (Preprocessor) There were too many arguments supplied in a macro invocation. Assembler) This is an internal compiler error. (147) too many #include directories specified (Preprocessor) A maximum of 7 directories may be specified for the preprocessor to search for include files. Contact Microchip Technical Support with details. (149) preprocessor macro work area overflow (Preprocessor) (Preprocessor) The total length of a macro expansion has exceeded the size of an internal table. Thus any macro expansion must not expand into a total of more than 32K bytes. (156) work buffer "*" overflow (Preprocessor) This is an internal compiler error. (144) too many nested #if blocks #if . (153) out of space in preprocessor macro * argument expansion (Preprocessor) A macro argument has exceeded the length of an internal buffer. Contact Microchip Technical Support with details. The maximum number allowed is 31. Confirm the spelling and path of the file specified on the command line. (148) too many arguments for preprocessor macro A macro may only have up to 31 parameters.

If the latter. This warning can be avoided with code like: #ifdef SYM #undef SYM #endif /* only undefine if defined */ DS52053B-page 384  2012 Microchip Technology Inc. the case of each does not exactly match. (169) strange character (*) after ## There is an unexpected character after #. for example: #if defined(END) #define NEXT #endif END /* END would be better in a comment here */ (164) #include filename "*" was converted to lower case (Preprocessor) The #include file name had to be converted to lowercase before it could be opened. See message 166. (162) #warning: * (Preprocessor. This warning may be disabled with some compilers. Driver) This warning is either the result of user-defined #warning preprocessor directive or the driver encountered a problem reading the map file. int . The extra text will be ignored. but a warning is issued. however. specifying #include "code.should be: #include <stdio. For example. (168) unknown option "*" The option given to the component which caused the error is not recognized.c if it is found. short . long . . It is preferable (and in accordance with Standard C) to enclose the text as a comment. (170) symbol "*" in undef was never defined (Preprocessor) (Preprocessor) (Any) The symbol supplied as argument to #undef was not already defined. "*" unused Preprocessor) There were too many values supplied to the -S preprocessor option.MPLAB® XC8 C Compiler User’s Guide (161) control line "*" within preprocessor macro expansion (Preprocessor) A preprocessor control line (one starting with a #) has been encountered while expanding a macro. contact Microchip Technical Support with details (163) unexpected text in control line ignored (Preprocessor) This warning occurs when extra characters appear on the end of a control line.c" will include Code. In Linux versions this warning could occur if the file wasn’t found. for example: #include <STDIO. (167) too many values specified with -S option. The values passes to this option represent the sizes of char . This should not happen if the preprocessor is being invoked by the compiler driver. float and double types. (166) too few values specified with option "*" (Preprocessor) The list of values to the preprocessor (CPP) -S option is incomplete.h> */ (165) #include filename "*" does not match actual name (check upper/lower case) (Preprocessor) In Windows versions this means the file to be included actually exists and is spelt the same way as the #include filename. This should not happen.H> /* oops -.

must have a new line at the end. and in fact will be rejected by later passes of the compiler. Each line. for example: #define str(x) #y /* oops -. for example: output = 0. where did this line go? */  2012 Microchip Technology Inc. /* next comment: hey.Error and Warning Messages (171) wrong number of preprocessor macro arguments for "*" (* instead of *) (Preprocessor) A macro has been invoked with the wrong number of arguments. (177) symbol "*" in -U option was never defined (Preprocessor) A macro name specified in a -U option to the preprocessor was not initially defined. DS52053B-page 385 . #endif /* divide by 0: was this what you were intending? */ (176) missing newline (Preprocessor) A new line is missing at the end of the line. its value has been taken as zero. you will need to define a special macro to do it.only two arguments required */ (172) formal parameter expected after # (Preprocessor) The stringization operator # (not to be confused with the leading # used for preprocessor control lines) must be followed by a formal macro parameter. b) (a+b) ADD(1. 2. for example: #if foo/0 int a. for example: #if CHAR == ’ab’ #define MULTI #endif (175) division by zero in #if. (173) undefined symbol "*" in #if. for example: #define ADD(a. This warning may be disabled with some compilers. 3) /* oops -. there is a division by zero which has been treated as yielding zero. This problem is normally introduced by editors. including the last line.did you mean x instead of y? */ If you need to stringize a token. For the purposes of this expression. /* a comment that was left unterminated flag = TRUE. for example: #define __mkstr__(x) #x then use __mkstr__(token) wherever you need to convert a token into a string. zero result assumed (Preprocessor) Inside a #if expression. (179) nested comments (Preprocessor) This warning is issued when nested comments are found.g. 0 used (Preprocessor) A symbol on a #if expression was not a defined preprocessor macro. A nested comment may indicate that a previous closing comment marker is missing or malformed. and thus cannot be undefined. Example: #if FOO+BAR /* e. FOO was never #defined */ #define GOOD #endif (174) multi-byte constant "*" isn’t portable (Preprocessor) Multi-byte constants are not portable.

union or array to another type. (185) function does not take arguments (Parser. struct TEST * sp. for example: (184) calling an interrupt function is illegal (Parser) A function qualified interrupt can’t be called from other functions.MPLAB® XC8 C Compiler User’s Guide (180) unterminated comment in included file (Preprocessor) Comments begun inside an included file must end inside the included file. for example: struct TEST test. for example: struct LAYOUT layout. (181) non-scalar types can’t be converted to other types You can’t convert a structure. It can only be called by a hardware (or software) interrupt. but it is called here with one or more arguments.e. This is because an interrupt function has special function entry and exit code that is appropriate only for calling from an interrupt. /* int cannot be converted to struct */ Note that even if a structure only contains an int . layout = i. add(5. Code Generator) This function has no parameters. d. b. for example: /* this call needs more arguments */ DS52053B-page 386  2012 Microchip Technology Inc. } /* oops -parameter should not be here */ (186) too many function arguments This function does not accept as many arguments as there are here. An interrupt function can call other non-interrupt functions. /* b is not a function -did you mean a = b*(c+d) ? */ (Parser) Only a function or function pointer can be the subject of a function call. int b). void add(int a. ? */ (Parser) (182) illegal conversion between types (Parser) This expression implies a conversion between incompatible types.did you mean: sp = &test. add(5). c. int i. i. /* call has too many arguments */ (Parser) (187) too few function arguments void add(int a. void main(void) { int input. sp = test. (183) function or function pointer required int a. input). a = b(c+d). . 7. (Parser) This function requires more arguments than are provided in this call. /* oops -. for example: int get_value(void). for example. and vice versa. input = get_value(6). a conversion of a structure type into an integer.. it cannot be assigned to an int variable. int b).

/* oops -. not an array or a structure) or the type void. /* oops -exactly which element do you mean? */ (Parser) An index expression must be either integral or an enumerated value. or you have some other syntax error. eh? */ (Parser) (190) illegal type for index expression int i. but has not been defined or declared. i.e. for example: (196) struct/union required A structure or union identifier is required before a dot "." ." or arrow ("->"). Check for spelling errors if you think it has been defined. The error is flagged on the line at which the code first starts to make no sense. (193) not a variable identifier "*" (Parser) This identifier is not a variable. /* the closing parenthesis is missing here */ /* the error is flagged here */ (195) expression syntax a /=% b. was expected here.maybe that should be: a /= b. for example: int a. int array[12. ). for example: (191) cast type must be scalar or void (Parser) A typecast (an abstract type declarator enclosed in parentheses) must denote a type which is either scalar (i.5]. } (189) illegal type for array dimension An array dimension must be either an integral type or an enumerated value.e.maybe: lip = (long *)input */ (192) undefined identifier "*" (Parser) This symbol has been used in the program.twelve and a half elements. This may be a statement following the incomplete expression. /* oops -. for example: if(a == b b = 0. for example: lip = (long [])input. a.b = 9..a is not a structure */ (Parser) (197) struct/union member expected A structure or union member name must follow a dot ". it may be some other kind of object. This may indicate you have left out this character in an expression. for example: int a. switch(input) { case a: /* oops! can’t use variable as part of a case label */ input++. /* oops -. (Parser)  2012 Microchip Technology Inc. i = array[3.. */ (Parser) This expression is badly formed and cannot be parsed by the compiler.Error and Warning Messages (188) constant expression required (Parser) In this context an expression is required that can be evaluated to a constant at compile time. DS52053B-page 387 . (194) ")" expected (Parser) A closing parenthesis. array[10]. /* oops -.5]. a label.

it can’t be written to */ A typecast does not yield an lvalue. /* oops -. int * ip. This operation is one of those.a = 0. while statements or to boolean operators like ! and && must be a scalar integral type. for example: bit b. for example: int * proc(register int in) { int * ip = &in. if(format) /* this operand must be a scaler type */ format.. array = ip. int * ip. /* oops -cannot take the address of a bit object */ DS52053B-page 388  2012 Microchip Technology Inc. for example: struct FORMAT format. for example: /* the contents of c cast to int is only a intermediate value */ (int)c = 1.you can’t take the address of a literal */ (202) only lvalues may be assigned to or modified (Parser) Only an lvalue (i. and thus it is illegal to attempt to take the address of it by applying the & operator. (200) taking the address of a register variable is illegal (Parser) A variable declared register may not have storage allocated for it in memory.e. } (201) taking the address of this object is illegal (Parser) The expression which was the operand of the & operator is not one that denotes memory storage (“an lvalue”) and therefore its address can not be defined. you can write this using pointers: *(int *)&c = 1 (203) illegal operation on bit variable (Parser) Not all operations on bit variables are supported. for example: ip = &8. /* oops -. /* array isn’t a variable.in may not have an address to take */ return ip. . However. an identifier or expression directly denoting addressable storage) can be assigned to or otherwise modified. for example: struct WHAT what. ip = &b. /* a definition for WHAT was never seen */ (Parser) (199) logical type required (Parser) The expression used as an operand to if. for example: int array[10].MPLAB® XC8 C Compiler User’s Guide (198) undefined struct/union "*" The specified structure or union tag is undefined. char c.

 2012 Microchip Technology Inc. as an operand to an arithmetic operator. (211) taking sizeof bit is illegal (Parser) It is illegal to use the sizeof operator with the C bit type. (210) bad size list (Parser) (Parser) This is an internal compiler error. Any return statement should not be followed by an expression. This specifies the alignment of each member within the structure. i. * cp2. return 1. /* either run should not be void. or remove the 1 */ } (205) integral type required This operator requires operands that are of integral type only. char * cp. Therefore its usage with the bit type make no sense and is an illegal operation. Use this with caution as some processors enforce alignment and will not operate correctly if word fetches are made on odd boundaries. (207) simple type required for "*" (Parser) A simple type (i.. cp = flag ? ip : cp2.Error and Warning Messages (204) void function can’t return a value (Parser) A void function cannot return a value. Contact Microchip Technical Support with details. (212) missing number after pragma "pack" (Parser) The pragma pack requires a decimal number as argument. not an array or structure) is required as an operand to this operator. (206) illegal use of void expression (Parser) (Parser) A void expression has no value and therefore you can’t use it anywhere an expression with a value is required. for example: #pragma pack /* what is the alignment value */ Maybe you meant something like: #pragma pack 2 (214) missing number after pragma "interrupt_level" (Parser) The pragma interrupt_level requires an argument to indicate the interrupt level. When used against a type the sizeof operator gives the number of bytes required to store an object that type. or 1 or 2 or PIC18 devices.e..e. DS52053B-page 389 . It will be the value 1 for mid-range devices. /* result of ? : will be int * or char * */ (Parser) Maybe you meant something like: cp = flag ? (char *)ip : cp2. (209) type conflict The operands of this operator are of incompatible types. for example: void run(void) { step(). for example: int * ip. (208) operands of "*" not same type The operands of this operator are of different pointer.

234e.this requires an psect to redirect */ maybe you meant something like: #pragma psect text=specialtext (218) missing name after pragma "inline" (Parser) The inline pragma expects the name of a function to follow. i. for example: /* oops -. using the digit 8 in an octal number. for example: i = 0bf000. . or HEX digits A-F in a decimal number. (220) exponent expected float f. The function name must be recognized by the code generator for it to be expanded. f = 1. (Parser) A floating-point constant must have at least one digit after the e or E. for example: #pragma printf_check /* what function is to be checked? */ Maybe you meant something like: #pragma printf_check sprintf Pragmas for all the standard printf-like function are already contained in <stdio. for example: #pragma inline /* what is the function name? */ maybe you meant something like: #pragma inline memcpy (219) missing name after pragma "printf_check" (Parser) The printf_check pragma expects the name of a function to follow. An octal number is denoted by the digit string commencing with a zero. while a HEX number starts with “0X” or “0x”. For example: int a = 058.h>.MPLAB® XC8 C Compiler User’s Guide (215) missing argument to pragma "switch" #pragma switch /* oops -. for example: (222) binary digit expected A binary digit was expected following the 0b format specifier.this requires a switch mode */ (Parser) The pragma switch requires an argument of auto.f000 is not a base two value */ (Parser) (223) digit out of range (Parser. /* oops -.what is the exponent? */ (221) hexadecimal digit expected a = 0xg6. /* leading 0 implies octal which has digits 0 .7 */ DS52053B-page 390  2012 Microchip Technology Inc.e... for example: maybe you meant something like: #pragma switch simple (216) missing argument to pragma "psect" (Parser) The pragma psect requires an argument of the form oldname = newname where oldname is an existing psect name known to the compiler. for example: #pragma psect /* oops -. other functions are not altered. This specifies printf-style format string checking for the function. direct or simple.was that meant to be a = 0xf6 ? */ (Parser) After 0x should follow at least one of the HEX digits 0-9 and A-F or a-f. Assembler) A digit in this number is out of range of the radix for the number. /* oops -. and newname is the desired new name.

/* oops -. (230) missing argument to -A (Parser) This is an internal compiler error. (225) missing character in character constant The character inside the single quotes is missing. (232) missing argument to -I (Parser) This is an internal compiler error. (An ellipsis is used in function prototypes to indicate a variable number of parameters. Contact Microchip Technical Support with details.. for example: c = ’12’. (231) unknown qualifier "*" given to -I (Parser) This is an internal compiler error. or it was meant to be a structure member operator which would require you remove one dot." (Parser) The only context in which two successive dots may appear is as part of the ellipsis symbol. for example: c = a.. Contact Microchip Technical Support with details. (233) bad -Q option "*" (Parser) This is an internal compiler error. /* the character value of what? */ (Parser) (226) char const too long (Parser) A character constant enclosed in single quotes may not contain more than one character. Likely a directive has been misspelled in your code somewhere." expected after ". /* oops -. Contact Microchip Technical Support with details. used to associate an absolute address with a variable.) Either .Error and Warning Messages (224) illegal "#" directive (Parser) An illegal # preprocessor has been detected. (228) illegal character (*) (Parser) This character is illegal in the C code.  2012 Microchip Technology Inc. Contact Microchip Technical Support with details. (236) simple integer expression required (Parser) A simple integral expression is required after the operator @. digits and those comprising the acceptable operators. char LOCK @ address. for example: char c = ". DS52053B-page 391 . was meant to be an ellipsis symbol which would require you to add an extra dot. Contact Microchip Technical Support with details. (234) close error (Parser) This is an internal compiler error.did you mean c = ’a’. Valid characters are the letters. for example: int address. ? */ (229) unknown qualifier "*" given to -A (Parser) This is an internal compiler error.only one character may be specified */ (227) ". Contact Microchip Technical Support with details. which must have 3 dots.

but four initializers */ int ivals[3] = { 2.uint is a type. for example: int a. but not recommended.g: double d. for example: int twice(int a) { return a*2. } DS52053B-page 392  2012 Microchip Technology Inc. switch(d) { /* oops -. for example: /* three elements. e. but defined with different scopes are legal. for example: int iarray[10] = {{’a’. 8}. } /* only one prototype & definition of rv can exist */ long twice(long a) { return a*2.MPLAB® XC8 C Compiler User’s Guide (237) function "*" redefined (Parser) More than one definition for a function has been encountered in this module. It cannot be defined again. (240) too many initializers (Parser) There are too many initializers for this object. Check the number of initializers against the object definition (array or structure). . ’b’.0’: d = 0. /* a filescope variable called "a" */ /* attempting to define another of the same name */ Note that variables with the same name. 6. Check for the correct placement and number of braces and commas. /* oops -. ’c’}. Function overloading is illegal. (241) initialization syntax (Parser) The initialization of this object is syntactically incorrect. because it does not reserve any storage that can be initialized. 4. (239) identifier "*" redefined (from line *) (Parser) This identifier has already been defined in the same scope.this must be integral */ case ’1.one two many {s */ (242) illegal type for switch expression (Parser) A switch operation must have an expression that is either an integral type or an enumerated value. } (238) illegal initialization (Parser) You can’t initialize a typedef declaration. for example: /* oops -. not a variable */ typedef unsigned int uint = 99. int a.

} /* oops -. but there is no enclosing switch statement. default: b = 10. while break can only be used inside those loops or a switch statement. for or do while loop. If there is a switch statement before this case label. /* this should be inside the switch */ (244) "default" case redefined (Parser) There is only allowed to be one default label in a switch statement. case ’1’: if(count>MAX) count= 0. See message 246.this shouldn’t be here */ break. there may be one too many closing braces in the switch code which would prematurely terminate the switch statement. break. for example: switch(input) { case ’0’: count++. (246) case label not in switch (Parser) A case label has been encountered. } /* oops! this shouldn’t be here and closed the switch */ break. break.Error and Warning Messages (243) inappropriate break/continue (Parser) A break or continue statement has been found that is not enclosed in an appropriate control structure. case ’2’: /* error flagged here */  2012 Microchip Technology Inc. for example: switch(input) { case 0: if(output == 0) input = 0xff. If there is a switch statement before this default label. break. A continue can only be used inside a while. A default label is only legal inside the body of a switch statement. DS52053B-page 393 . /* if this is the default case.. there may be one too many closing braces in the switch code which would prematurely terminate the switch statement. for example: switch(a) { default: b = 9. You have more than one. */ /* then what is this? */ (245) "default" case not in switch (Parser) A label has been encountered called default but it is not enclosed by a switch statement. A case label may only appear inside the body of a switch statement..

for example: start: if(a > 256) goto end.MPLAB® XC8 C Compiler User’s Guide (247) duplicate label "*" (Parser) The same name is used for a label more than once in this function. although it may well not be the last one. but the preceding function has not been ended with a closing brace.. It is acceptable to redeclare the size of an array that was previously declared with a zero dimension. (249) probable missing "}" in previous block (Parser) The compiler has encountered what looks like a function or other declaration. /* oops -. if(a > b) { c = 0. long int b) /* hmmm -. /* error flagged here */ /* which start label do I jump to? */ (248) inappropriate "else" (Parser) An else keyword has been encountered that cannot be associated with an if statement. for example: /* here is a comment which I have forgotten to close. for example: extern int array[5]. int). This probably means that a closing brace has been omitted from somewhere in the previous function.. not just the block that encloses a label. but not otherwise.which is right? */ { /* error flagged here */ return sin(b/a). for example: void set(char a) { PORTA = a. } DS52053B-page 394  2012 Microchip Technology Inc. This may mean there is a missing brace or other syntactic error. Note that the scope of labels is the entire function. } /* the closing brace was left out here */ /* error flagged here */ MESSAGES 250-499 (251) array dimension redeclared (Parser) An array dimension has been declared as a different non-zero value from its previous declaration.. /* . start: if(a == 0) goto start.has it 5 or 10 elements? */ (252) argument * conflicts with prototype (Parser) The argument specified (argument 0 is the left most argument) of this function definition does not agree with a previous prototype for this function. void clear(void) { PORTA = 0. for example: /* this is supposedly calc’s prototype */ extern int calc(int. that will be closed here. int array[10].. thus removing the "if" */ else /* my "if" has been lost */ c = 0xff. int calc(int a. .

For example: typedef volatile int vint. b. for example: struct { int a. (256) too much indirection A pointer declaration may only have 16 levels of indirection. (255) not a member of the struct/union "*" (Parser) This identifier is not a member of the structure or union type with which it used here. int a.this results in two volatile qualifiers */ volatile vint very_vol.Error and Warning Messages (253) argument list conflicts with prototype (Parser) The argument list in a function definition is not the same as a previous prototype for that function. } input. not both */ (260) undefined enum tag "*" This enum tag has not been defined. for example: struct { int a. (259) can’t be qualified both far and near It is illegal to qualify a type as both far and near. int b) { return a + b. Remove the redundant qualifier. Check that the number and types of the arguments are all the same. int b. for example: far near int spooky. DS52053B-page 395 .choose far or near. This can occur either directly or through the use of a typedef. /* oops -. extern int calc(int). int calc(int a. } /* this is supposedly calc’s prototype */ /* hmmm -. for example: enum WHAT what. /* a definition for WHAT was never seen */ (Parser) (261) struct/union member "*" redefined (Parser) This name of this member of the struct or union has already been used in this struct or union. (Parser) /* oops -.d) /* oops -there is no member d in this structure */ return. if(data. } data. c. Contact Microchip Technical Support with details. for example: (258) duplicate qualifier (Parser) There are two occurrences of the same qualifier in this type specification. /* oops -.which is right? */ /* error flagged here */ (254) undefined *: "*" (Parser) This is an internal compiler error. (257) only "register" storage class allowed void process(static int input) (Parser) (Parser) The only storage class allowed for a function parameter is register.a different name is required here */  2012 Microchip Technology Inc.

for example: struct { unsigned first: /* oops -. char b7:1. */ (264) bad bitfield type A bit-field may only have a type of int (or unsigned). /* these must be part of an int. } freg. } ms. int get(int). /* 4 bits wide */ /* another 4 bits */ (266) storage class illegal (Parser) A structure or union member may not be given a storage class. not char */ (Parser) (265) integer constant expected (Parser) A colon appearing after a member name in a structure declaration indicates that the member is a bit-field. struct { int a. DS52053B-page 396  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide (262) struct/union "*" redefined A structure or union has been defined more than once. . unsigned second: 4. } my_struct. } . An integral constant must appear after the colon to define the number of bits in the bit-field. If this was meant to be a structure with bit-fields. */ unsigned second. /* should be a pointer: int (*get)(int). } ms. for example: struct { int a. Its storage class is determined by the storage class of the structure. It may be a pointer to a function. /* was this meant to be the same name as above? */ (Parser) (263) members can’t be functions (Parser) A member of a structure or a union may not be a function. then the following illustrates an example: struct { unsigned first : 4. for example: struct { /* no additional qualifiers may be present with members */ static int first. for example: struct FREG { char b0:1. } object. for example: struct { int a.should be: unsigned first. } my_struct. char :6.

. Only one storage class should appear in a declaration." illegal in non-prototype argument list (Parser) The ellipsis symbol may only appear as the last item in a prototyped argument list. /* which is it? */ (274) type can’t be unsigned A floating-point type cannot be made unsigned. b.Error and Warning Messages (267) bad storage class (Code Generator) The code generator has encountered a variable definition whose storage class is invalid. /* what? */ (Parser) (273) type can’t be both signed and unsigned (Parser) The type modifiers signed and unsigned cannot be used together in the same declaration. for example: register int gi. K&R-style non-prototype function definitions.. . /* is it int or float? */ (Parser) (270) variable can’t have storage class "register" (Parser) Only function parameters or auto variables may be declared using the register qualifier. /* what? */ (Parser) (275) ". /* so is it static or extern? */ (269) inconsistent type Only one basic type may appear in a declaration. /* what? */ (Parser) (272) type can’t be short Only int can be modified with short. } (271) type can’t be long Only int and float can be qualified with long.. b. for example: signed unsigned int confused. } (268) inconsistent storage class (Parser) A declaration has conflicting storage classes. i. long char lc.) int a. for example: short float sf. for example: unsigned float uf. nor may it appear after argument names that do not have types. for example: int float if. as they have opposite meaning.e. For example: /* K&R-style non-prototyped function definition */ int kandr(a.. /* this cannot be qualified register */ int process(register int input) /* this is okay */ { return input + gi.. /* auto not permitted with global variables */ int power(static int a) /* parameters may not be static */ { return foo * a. for example: auto int foo. It may not appear on its own. for example: extern static int where. DS52053B-page 397 . {  2012 Microchip Technology Inc.

e. b) int b.e.e. (282) functions can’t return arrays (Parser) A function can return only a scalar (simple) type or a structure. All succeeding dimensions must be present as a constant expression.should be: int (* farray[])(). Note the many parentheses that are necessary to make the parts of the declaration bind correctly. for example: int plus(int a. } (284) invalid dimension (Parser) This is an internal compiler error. It is not acceptable to just have an identifier. for example: /* can’t have two parameters called "a" */ int calc(int a.. for example: /* oops -. define an array of pointers to functions. for example: int * farray[](). It cannot return an array. . only names inside the parentheses and the argument types in a declaration list before the start of the function body). for example: int arr[][7] */ int get_element(int arr[2][]) { return array[1][6]. int a) (279) initialization of function arguments is illegal (Parser) A function argument can’t have an initializer in a declaration. for example: /* This should be.MPLAB® XC8 C Compiler User’s Guide (276) type specifier required for prototyped argument (Parser) A type specifier is required for a prototyped argument. */ (281) functions can’t return functions (Parser) A function cannot return a function. (280) arrays of functions are illegal (Parser) You cannot define an array of functions. however. DS52053B-page 398  2012 Microchip Technology Inc...a is prototyped. with types inside the parentheses) or all K&R style args (i. You can. the first) dimension in a multi-dimension array may not be assigned a value. { return a + b. (277) can’t mix prototyped and non-prototyped arguments (Parser) A function declaration can only have all prototyped arguments (i. } /* oops -.a is initialized when proc is called */ extern int proc(int a = 9). A function returning a pointer to a function could be declared like this: int (* (name()))(). The initialization of the argument happens when the function is called and a value is provided for the argument by the calling function. Contact Microchip Technical Support with details. b is not */ (278) argument "*" redeclared (Parser) The specified argument is declared more than once in the same argument list. (283) dimension required (Parser) Only the most significant (i. /* oops -. It can return a function pointer.

e. (290) illegal function qualifier(s) (Parser) A qualifier has been applied to a function which makes no sense in this context. (287) arrays of bits or pointers to bit are illegal It is not legal to have an array of bits. Contact Microchip Technical Support with details. for example: /* variables cannot be qualified interrupt */ interrupt int input. } (291) K&R identifier "*" not an argument (Parser) This identifier that has appeared in a K&R style argument declarator is not listed inside the parentheses after the function name. This may indicate that you have forgotten a star * that is indicating that the function should return a pointer to a qualified object.no pointers to bit variables */ (Parser) (288) only functions may be void A variable may not be void.Error and Warning Messages (285) no identifier in declaration (Parser) The identifier is missing in this declaration. Examine the declaration and find a way to simplify it.no bit arrays */ /* wrong -. for example: int a. so perhaps a "*" has been omitted from the declaration. const or volatile. */ { } (292) function parameter may not be a function (Parser) A function parameter may not be a function.  2012 Microchip Technology Inc. so will anybody maintaining the code. If the compiler finds it too complex. /* oops -. for example: bit barray[10]. for example: void interrupt(void) { } /* what is the name of this function? */ (286) declarator too complex (Parser) This declarator is too complex for the compiler to handle.. Some qualifier only make sense when used with an lvalue. /* this makes no sense */ (Parser) (289) only functions may be qualified "interrupt" (Parser) The qualifier interrupt may not be applied to anything except a function. DS52053B-page 399 . /* wrong -. It may be a pointer to a function. Only a function can be void. or a pointer to bit variable. for example: int process(input) int unput. This error can also occur where the compiler has been confused by such things as missing closing braces. (293) bad size in index_type() (Parser) This is an internal compiler error. for example: const char ccrv(void) /* const * char ccrv(void) perhaps? */ { /* error flagged here */ return ccip. i.that should be int input. void b. bit * bp.

(306) can’t allocate * bytes of memory for * (Code Generator) This is an internal compiler error. Reduce the number of symbols in your program.MPLAB® XC8 C Compiler User’s Guide (294) can’t allocate * bytes of memory (Code Generator. The maximum allowable number of case labels in any one switch statement is 511. run(). Contact Microchip Technical Support with details. as it attempts to sort and merge strings. Contact Microchip Technical Support with details. #55 [r1]. Contact Microchip Technical Support with details. (298) end of file in #asm (Preprocessor) An end of file has been encountered inside a #asm block. (303) can’t allocate * bytes of memory (line *) (Parser) The parser was unable to allocate memory for the longest string encountered. Hexmate) This is an internal compiler error. (297) bad argument (*) to tysize() (Parser) This is an internal compiler error. Try reducing the number or length of strings in this module. . (307) too many qualifier names (Parser) This is an internal compiler error. for example: void main(void) { init(). Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. (295) expression too complex (Parser) This expression has caused overflow of the compiler’s internal stack and should be re-arranged or split into two expressions. Contact Microchip Technical Support with details. DS52053B-page 400  2012 Microchip Technology Inc. (296) out of memory (Objtohex) This could be an internal compiler error. This probably means the #endasm is missing or misspelled. r0 /* oops -.where is the #endasm */ (300) unexpected end of file An end-of-file in a C module was encountered unexpectedly. for example: #asm MOV MOV } r0. (302) can’t reopen "*": * (Parser) This is an internal compiler error. Contact Microchip Technical Support with details. /* is that it? What about the close brace */ (Parser) (301) end of file on string file (Parser) This is an internal compiler error. (308) too many case labels in switch (Code Generator) There are too many case labels in this switch statement. (309) too many symbols (Assembler) There are too many symbols for the assembler’s symbol table.

10) * 2. 4. was expected here.no closing brace */ (317) "(" expected (Parser) An opening parenthesis . (312) "*" expected The indicated token was expected by the parser. for . /* oops -.. for example: process(carray[idx). for example: /* the function block must follow. /* should be: if(a == b) */ (318) string expected (Parser) The operand to an asm statement must be a string enclosed in parentheses. This must be the first token after a while . for example: char carray[4] = { 1. */ (311) closing quote expected A closing quote was expected for the indicated string. /* error flagged here */ } (316) "}" expected (Parser) A closing brace was expected here.where is the semicolon? */ } /* error is flagged here */ Note: Omitting a semicolon from statements not preceding a close brace or keyword typically results in some other error being issued for the following code which the parser assumes to be part of the original statement. for example: asm(nop). This error may be the result of a initialized array missing the closing brace . for example: while(a) { b = a-.e. for example: /* oops! no opening brace after the prototype */ void process(char c) return max(c. /* that should be asm("nop"). do or asm keyword. DS52053B-page 401 . 3. argument names but no types inside the parentheses) a function body is expected to follow. if ./* oops -. not a semicolon */ int get_value(a. /* oops -should be: process(carray[idx]). (314) ". (. b). 2. (315) "{" expected (Parser) An opening brace was expected here.Error and Warning Messages (310) "]" expected (Parser) A closing square bracket was expected in an array declaration or an expression using an array index. for example: if a == b b = 0. This error may be the result of a function definition missing the opening brace .  2012 Microchip Technology Inc." expected (Parser) A semicolon is missing from a statement. A close brace or keyword was found following a statement with no terminating semicolon . (313) function body expected (Parser) (Parser) (Parser) Where a function declaration is encountered with K&R style arguments (i.

(325) error in printf-style format string (Parser) There is an error in the format string here. /* this is not how you define a structure */ You might mean something like: struct { int a. 2L). */ (323) struct/union tag or "{" expected (Parser) An identifier denoting a structure or union or an opening brace must follow a struct or union keyword. for example: printf("%lx". two }. median). this will cause unexpected behavior at run time. low.a valid C label must follow a goto */ (Parser) (322) enum tag or "{" expected (Parser) After the keyword enum must come either an identifier that is or will be defined as an enum tag. for example: printf("%l". This often occurs when a semicolon is accidentally typed instead of a colon.%d". } if(i > 5) end(). but may represent an incorrect format string. /* this is not BASIC -. or an opening brace. The string has been interpreted as a printf() style format string. Check the number and order of format specifiers and corresponding arguments. for example: if(a) goto 20.MPLAB® XC8 C Compiler User’s Guide (319) while expected The keyword while is expected at the end of a do statement.missed a placeholder? */ printf("%d . for example: enum 1.maybe: printf("%ld". for example: enum {one=1. for example: struct int a. for example: /* oops -. This is harmless. high. */ (326) long int argument required in printf-style format string (Parser) A long argument is required for this format specifier. lll). } my_struct. for example: switch(input) { case 0. (324) too many arguments for printf-style format string (Parser) There are too many arguments for this format string. and it is not syntactically correct. (Parser) /* do the block while what condition is true? */ /* error flagged here */ (320) ":" expected (Parser) A colon is missing after a case label. . /* oops -. for example: do { func(i++). /* should be. 2). lll). 2. state = NEW. or after the keyword default. If not corrected. /* oops -. // maybe you meant: printf("%lx". DS52053B-page 402  2012 Microchip Technology Inc.that should have been: case 0: */ (321) label identifier expected An identifier denoting a label must appear after goto.

44.should that be const not cinst? */ #pragma printf_check(printf) cinst (335) unknown pragma "*" An unknown pragma directive was encountered. 1.%d".23). Check the number and order of format specifiers and corresponding arguments. for example: printf("%llx". printf("%f". This would result in a garbage value being printed or converted at run time. and requires a floating-point expression. for example: /* oops -.0). 2LL).should that be #pragma strings const ? */ #pragma strings cinst (334) unrecognized qualifier name after "printf_check" (Parser) The #pragma printf_check was passed a qualifier that could not be identified. (328) int argument required in printf-style format string (Parser) An integral argument is required for this printf-style format specifier. for example: printf("%d". low). for example: printf("%d .the level is too high */ void interrupt isr(void) { /* isr code goes here */ } (333) unrecognized qualifier name after "strings" (Parser) The pragma strings was passed a qualifier that was not identified. DS52053B-page 403 . /* oops! where is the other value to print? */ (332) "interrupt_level" should be 0 to 7 (Parser) The pragma interrupt_level must have an argument from 0 to 7. For example: #pragma interrupt_level 9 /* oops -. Check the number and order of format specifiers and corresponding arguments. // maybe you meant: printf("%llx". (331) too few arguments for printf-style format string (Parser) There are too few arguments for this format string. for example: /* oops -. /* should be: printf("%f". PIC18 devices can use levels 1 or 2. 44). Check the number and order of format specifiers and corresponding arguments. Check for missing or extra format specifiers or arguments to printf. Note that MPLAB XC8 does not provide direct support for a long long integer type. */ (330) pointer to * argument required in printf-style format string (Parser) A pointer argument is required for this format specifier. /* wrong number or wrong placeholder */ (329) double argument required in printf-style format string (Parser) The printf format specifier corresponding to this argument is %f or similar. mid-range devices only use level 1. for example: #pragma rugsused myFunc w /* I think you meant regsused */ (Parser)  2012 Microchip Technology Inc. 2).Error and Warning Messages (327) long long int argument required in printf-style format string (Parser) A long long argument is required for this format specifier. however.

’5’] */ (343) implicit return at end of non-void function (Parser) A function which has been declared to return a value has an execution path that will allow it to reach the end of the function body. since to initialise an object it is necessary to define (i.. . which can cause problems for include files. Some editors will create such files. return. for example: int mydiv(double a. for example: char * cp = "hi" "there". Check that this is the desired result. how can it be initialized? */ (340) string not terminated by null character (Parser) A char array is being initialized with a string literal larger than the array. ’4’. allocate storage for) it. ’2’. /* what about when b is 0? */ } /* warning flagged here */ (344) non-void function returns no value (Parser) A function that is declared as returning a value has a return statement that does not specify a return value. for example: char foo[5] = "12345". /* if it’s extern and not allocated storage. for example: extern int other = 99.MPLAB® XC8 C Compiler User’s Guide (336) string concatenation across lines (Parser) Strings on two lines will be concatenated. for example: int get_value(void) { if(flag) return val++.e. but it could not be created. i.e. foo = [’1’. Either insert a return statement with a value. /* the string stored in foo won’t have a null terminating. int b) { if(b != 0) return a/b. The ANSI C standard requires all source files to consist of complete lines only. declare it void. Check that all file path names are correct. (339) initializer in extern declaration (Parser) A declaration containing the keyword extern has an initializer. /* this is okay. or if the function is not to return a value. but is it what you had intended? */ (337) line does not have a newline on the end (Parser) The last line in the file is missing the newline (operating system dependent character) from the end. (338) can’t create * file "*" (Any) The application tried to create or open the named file. /* what is the return value in this instance? */ } DS52053B-page 404  2012 Microchip Technology Inc. This overrides the extern storage class. Hence there is insufficient space in the array to safely append a null terminating character. thus returning without a value. ’3’.

This can lead to strange behavior of your program or signature errors at link time. This is legal but is invariably not desirable as it restricts the scope of the function declaration to the function body. it will no longer have the earlier declaration and thus will be unable to check that the declarations are consistent. flag = FINISHED. An auto variable may be qualified with static . always declare extern variables and functions outside any other functions. but it is then no longer auto. /* warning flagged here */ { } This would be better written: int process(int input) { }  2012 Microchip Technology Inc. /* local blockscope input */ a = input.. As a general rule.Error and Warning Messages (345) unreachable code (Parser) This section of code will never be executed. It is preferable to use prototype declarations for all functions. (349) non-prototyped function declaration for "*" (Parser) A function has been declared using old-style (K&R) arguments. } (348) auto variable "*" should not be qualified (Parser) An auto variable should not have qualifiers such as near or far associated with it.e. again subverting the compiler’s type checking. because there is no execution path by which it could be reached. Its storage class is implicitly defined by the stack organization. for example: int input. DS52053B-page 405 . one outside and preceding the current function or block). For example: int process(int a) { /* this would be better outside the function */ extern int away. /* how does this loop finish? */ /* how do we get here? */ (346) declaration of "*" hides outer declaration (Parser) An object has been declared that has the same name as an outer declaration (i. /* this will use the local variable. It will also hide any previous declarations of the same thing. This means that if the compiler encounters another declaration. for example: int process(input) int input. /* input has filescope */ void process(int a) { int input. Is this right? */ (347) external declaration inside function (Parser) A function contains an extern declaration. but can lead to accidental use of one variable when the outer one was intended. return away + a. use or definition of the extern object later in the same file. for example: while(1) process(). This is legal.

This may result in truncation of the pointer and loss of information. depending on the memory model in use. A typecast will make this warning go away. /* if sc contains 0xff. Note that the symbols rcsid and sccsid are never reported as being unused. ui = sc. this will result in the signed value being first sign-extended to a signed number the size of the target type. for example: signed char sc. int i. (352) float parameter coerced to double (Parser) Where a non-prototyped function has a parameter declared as float. This is because the default C type conversion conventions provide that when a floating-point number is passed to a non-prototyped function. If you do not want this to take place. unsigned int ui. DS52053B-page 406  2012 Microchip Technology Inc. . it will be converted to double. Either this object is redundant.MPLAB® XC8 C Compiler User’s Guide (350) unused * "*" (from line *) (Parser) The indicated object was never used in the function or module being compiled. To ensure this does not happen. Under the ANSI C “value preserving” rules. (355) implicit signed to unsigned conversion (Parser) A signed number is being assigned or otherwise converted to a larger unsigned type. This is probably due to the array not having an explicit dimension in the extern declaration. or the code that was meant to use it was excluded from compilation or misspelled the name of the object. then indicate that this is so by a cast: i = (int)dd. (356) implicit conversion of float to integer (Parser) A floating-point value has been assigned or otherwise converted to an integral type. for example: double inc_flt(f) float f. the compiler converts this into a double float. ui will contain 0xffff for example */ will perform a sign extension of the char variable to the longer type. It is important that the function declaration be consistent with this convention. or a default pointer has been assigned to a pointer qualified near. first convert the signed value to an unsigned equivalent. { return f * 2. This could result in truncation of the floating-point value. (354) possible pointer truncation (Parser) A pointer qualified far has been assigned to a default pointer or a pointer qualified near. then converted to unsigned (which involves no change in bit pattern). for example: ui = (unsigned char)sc. /* is this really what you meant? */ If you do intend to use an expression like this. double dd. use a cast. i = dd. Thus an unexpected sign extension can occur. } /* f will be converted to double */ /* warning flagged here */ (353) sizeof external array "*" is zero (Parser) The size of an external array evaluates to zero.

but which have different qualifiers. indicate your intention by a cast: i = (int)ip.  2012 Microchip Technology Inc. /* is this correct? */ This is common way of accessing bytes within a multi-byte variable.did you mean i = *ip ? */ If you do intend to use an expression like this. use a typecast to inform the compiler that you want the conversion and the warning will be suppressed. To indicate that this is the intended operation of the program. /* that’s better */ This warning may also occur when converting between pointers to objects which have the same type.e.did you mean ip = &i ? */ If you do intend to use an expression like this. pointing to a particular kind of object) has been converted into a pointer of a different type. but almost certainly not what you intend.. This may also mean you have forgotten the & address operator. use a typecast to inform the compiler that you want the conversion and the warning will be suppressed. but if this is genuinely what you want to do.Error and Warning Messages (357) illegal conversion of integer to pointer (Parser) An integer has been assigned to or otherwise converted to a pointer type. for example: int * ip. ip = i. i = ip. but if this is genuinely what you want to do. /* oops -. then this warning is quite valid. /* that’s better */ Omitting a qualifier from a pointer type is often disastrous. but if this is genuinely what you want to do. but what sort of characters? */ cp = "I am a string of characters". cp = "I am a string of characters". /* yes. If the default type for string literals is const char * . cp = &input. This should be written: const char * cp. use a typecast to inform the compiler that you want the conversion and the warning will be suppressed. This may also mean you have forgotten the * dereference operator. DS52053B-page 407 . /* oops -. (358) illegal conversion of pointer to integer (Parser) A pointer has been assigned to or otherwise converted to a integral type. then indicate that this is so by a cast: ip = (int *)i. (359) illegal conversion between pointer types (Parser) A pointer of one type (i. char * cp. for example: long input. use a cast: cp = (char *)&input. for example: int * ip. int i. int i. for example: char * cp. This will usually mean you have used the wrong variable. This will usually mean you have used the wrong variable. This will usually mean you have used the wrong variable.

bar = foo. The solution is to ensure that all functions are defined or at least declared before use. the compiler will automatically declare the function to be of type int . void main(void) { void(*bar)(void). i = input[-2]. Since using the name of an array gives its address anyway. This warning will not be issued when accessing an array element via a pointer variable. this is unnecessary and has been ignored. out = 0. /* oops -. void main(void) { /* by here a prototype for set should have seen */ set(10L. } (362) redundant "&" applied to array (Parser) The address operator & has been applied to an array.MPLAB® XC8 C Compiler User’s Guide (360) array index out of bounds (Parser) An array is being indexed with a constant value that is less than zero. the & is redundant. it should be preceded with the keywords extern or static as appropriate. For example: /* I may prevent an error arising from calls below */ void set(long a. * ip. const int out = 1234. /* both assignments are equivalent */ bar = &foo. The effect of attempting to modify such an object is compiler specific. 6). Since using the name of a function gives its address anyway. this is unnecessary and has been ignored. not a variable. i = ip[-2]. input[10]. preferably with prototyped parameters. /* "out" is read only */ /* oops -writing to a read-only object */ DS52053B-page 408  2012 Microchip Technology Inc. /* array is a constant. with unspecified (K&R style) parameters. causing a compiler error. /* the & is redundant */ } (364) attempt to modify object qualified * (Parser) Objects declared const or code may not be assigned to or modified in any other way by your program. int b). for example: extern void foo(void).this element doesn’t exist */ /* this is okay */ (361) function declared implicit int (Parser) Where the compiler encounters a function call of a function whose name is presently undefined. (363) redundant "&" or "*" applied to function address (Parser) The address operator “&” has been applied to a function. it is possible that its type and arguments will be different from the earlier implicit declaration. for example: int array[5]. for example: int i. int * ip. . ip = &input[5]. or greater than or equal to the number of elements in the array. If a definition of the function is subsequently encountered. */ ip = &array. If it is necessary to make a forward declaration of a function.

. } (368) array dimension on "*[]" ignored (Preprocessor) An array dimension on a function parameter has been ignored because the argument is actually converted to a pointer when passed. can’t be static (Parser) This function was already declared extern. } . possibly through an implicit declaration. since the storage associated with automatic variables becomes invalid when the function returns. If a bit-field is declared to be type int. /* oops -.this must be unsigned */ (370) illegal basic type. int b) { PORTA = a + b. 6). } /* now it finds out otherwise */ static void set(long a. */ set(10L. the compiler still treats it as unsigned. DS52053B-page 409 . (367) identifier is already extern. } (366) operands of "*" not same pointer type (Parser) The operands of this operator are of different pointer types. auto) variable. for example: /* here ling is assumed to be int */ unsigned char bar = (unsigned ling) ’a’. } (369) signed bitfields not supported (Parser) Only unsigned bit-fields are supported. but this redeclaration is invalid. use a typecast to suppress the error message. signed int value: 7.. but if the code is actually what you intended. /* returning this is dangerous. void main(void) { /* at this point the compiler assumes set is extern.. It has now been redeclared static.g. int assumed (Parser) The basic type of a cast to a qualified basic type couldn’t not be recognized and the basic type was assumed to be int. Either remove the dimension from the parameter. the pointer could be dereferenced */ return &c. or define the parameter using pointer syntax. for example: /* param should be: "int array[]" or "int *" */ int get_first(int array[10]) { /* warning flagged here */ return array[0].  2012 Microchip Technology Inc. Thus arrays of any size may be passed. This is likely to be an error. This probably means you have used the wrong pointer.Error and Warning Messages (365) pointer to non-static object returned (Parser) This function returns a pointer to a non-static (e. for example: struct { signed int sign: 1. for example: char * get_addr(void) { char c.

(382) incomplete record: type = *. /* don’t let the compiler make assumptions. which is not allowed when using a compiled stack. and has thus been interpreted as an identifier. Is the file or a file by this name already in use? (379) bad record type "*" (Linker) This is an internal compiler error. i. Contact Microchip Technical Support with details. (373) implicit signed to unsigned conversion (Parser) An unsigned type was expected where a signed type was given and was implicitly cast to unsigned. This could mean you have left out the comma between two identifiers in a declaration list. for example: char c. Contact Microchip Technical Support with details.MPLAB® XC8 C Compiler User’s Guide (371) missing basic type. Contact Microchip Technical Support with details. for example: unsigned int foo = -1." expected (Parser) A comma was expected here. /* (signed) assumed to be (signed int) */ (375) unknown FNREC type "*" (Linker) This is an internal compiler error. length = * (Dump. or that it has been truncated. . /* the above initialization is implicitly treated as: unsigned int foo = (unsigned) -1. DS52053B-page 410  2012 Microchip Technology Inc. int assumed (Parser) This declaration does not include a basic type. /* ditto. It may also mean that the immediately preceding type name is misspelled. but it is preferable to include a basic type to make it clear what is intended. Contact Microchip Technical Support with details. */ (374) missing basic type. /* thinks: chat & b are unsigned. (378) can’t create * file "*" (Hexmate) This type of file could not be created. Contact Microchip Technical Support with details. Ensure the object file is a valid object file. (381) record "*" too long (*) (Linker) This is an internal compiler error. This probably means the program has indirect recursion. use: extern int func(int). for example: int i = (signed) 2. Xstrip) This message is produced by the DUMP or XSTRIP utilities and indicates that the object file is not a valid object file. This declaration is not illegal.. but where is the comma? */ unsigned chat b. int assumed (Parser) The basic type of a cast to a qualified basic type was missing and assumed to be int. so int has been assumed. (380) unknown record type (*) (Linker) This is an internal compiler error. */ (372) ". use : int i */ func(). for example: unsigned char a. (376) bad non-zero node in call graph (Linker) The linker has encountered a top level node in the call graph that is referenced from lower down in the call graph.

refer to Section Section 7. This cannot be done. (388) duplicate -M option (Linker) The map file name has been specified to the linker for a second time. (392) missing argument to -U The -U (undefine) option needs an argument. (398) output file can’t be also an input file (Linker) The linker has detected an attempt to write its output file over one of its input files. The arguments of separate -p options may be combined and separated by commas. (384) assertion failed: file *.8 “-M: Generate Map File” for information on the correct syntax for this option. Otherwise this may be an internal compiler error and you should contact Microchip Technical Support with details. ensure that only one instance of this option is present on the command line.obj files. DS52053B-page 411 . line *. (394) duplicate -D or -H option (Linker) (Linker) (Linker) (Linker) The symbol file name has been specified to the linker for a second time. (395) missing argument to -J (Linker) The maximum number of errors before aborting must be specified following the -j linker option.8. This should not occur if you are using a compiler driver. The arguments specify how the segment addresses are calculated.  2012 Microchip Technology Inc. Contact Microchip Technical Support with details. because it needs to simultaneously read and write input and output files.Error and Warning Messages (383) text record has length (*) too small (Linker) This is an internal compiler error. Parser) This is an internal compiler error. If invoking the linker manually. or a -p option was not followed by any arguments. See Section 4. Contact Microchip Technical Support with details. (387) illegal or too many -G options (Linker) There has been more than one linker -g option.lib (Linker) Improper usage of the command-line linker. ensure that only one instance of either of these options is present on the command line. (393) missing argument to -W The -W option (listing width) needs a numeric argument. expression * (Linker. If invoking the linker manually.2 “Operation” for more details. (397) usage: hlink [-options] files. or another -o option has been encountered. (390) missing argument to -P (Linker) There have been too many -p options passed to the linker. A -o option to the linker must be immediately followed by a filename with no intervening space. or the -g option did not have any arguments following. (391) missing argument to -Q The -Q linker option requires the machine type for an argument. If you are invoking the linker directly. (389) illegal or too many -O options (Linker) This linker -o flag is illegal. This should not occur if you are using a compiler driver.

Cromwell) (Objtohex) (Objtohex) A write error occurred on the named file.3 “OBJTOHEX” for more details.3 “OBJTOHEX” for more details.m HEX length/rounding option is invalid. (415) text offset too low in COFF file (Objtohex) (Linker) This is an internal compiler error. see Section 8. Contact Microchip Technical Support with details. (413) write error on "*" (Assembler.m HEX length/rounding option is invalid. This could be an internal compiler error and you should contact Microchip Technical Support with details. . 10 or 16. (405) bad record size rounding value to -<digits> (Objtohex) The second value to the OBJTOHEX -n. (408) bad argument to -B (Objtohex) This option requires an integer argument in either base 8. If you are invoking this command-line tool directly. Contact Microchip Technical Support with details.3 “OBJTOHEX” for more details. (412) text does not start at 0 Code in some things must start at zero. 10 or 16. (416) bad character (*) in extended TEKHEX line (Objtohex) This is an internal compiler error. (409) bad argument to -P (Objtohex) This option requires an integer argument in either base 8. If you are invoking objtohex directly then see Section 8. The object code format of an object file is invalid. If you are invoking objtohex directly. Contact Microchip Technical Support with details. Ensure it is a valid object file. Contact Microchip Technical Support with details. (403) bad -E option: "*" (Objtohex) This is an internal compiler error. (402) bad argument to -F (Objtohex) The -F option for objtohex has been supplied an invalid argument. refer to Section 8.MPLAB® XC8 C Compiler User’s Guide (400) bad object code format (Linker) This is an internal compiler error. (406) bad argument to -A (Objtohex) This is an internal compiler error. (407) bad argument to -U (Objtohex) This is an internal compiler error. This probably means you have run out of disk space. Otherwise this may be an internal compiler error and you should contact Microchip Technical Support with details. (410) bad combination of options The combination of options supplied to OBJTOHEX is invalid. (404) bad maximum length value to -<digits> (Objtohex) The first value to the OBJTOHEX -n. DS52053B-page 412  2012 Microchip Technology Inc. Contact Microchip Technical Support with details. (414) read error on "*" The linker encountered an error trying to read this file. Here it doesn’t. Linker. Otherwise this may be an internal compiler error and you should contact Microchip Technical Support with details. Contact Microchip Technical Support with details.

Contact Microchip Technical Support with details if the object file was created by the compiler. Contact Microchip Technical Support with details. The object file output of the linker is absolute. (425) incomplete record (Objtohex. Contact Microchip Technical Support with details. Contact Microchip Technical Support if the object file was generated by the compiler. The checksum list is read from standard input in response to an option.  2012 Microchip Technology Inc. (420) too many relocation items (Objtohex) This is an internal compiler error. This is either an invalid object file. (423) illegal record type (Linker) There is an error in an object file. (422) no end record (Linker) This object file has no end record. If you are invoking objtoexe directly then check this argument. 10 or 16. (421) too many segments (Objtohex) This is an internal compiler error. (419) object file is not absolute (Objtohex) The object file passed to OBJTOHEX has relocation items in it. (430) bad checksum specification A checksum list supplied to OBJTOHEX is syntactically incorrect. Contact Microchip Technical Support with details. (428) too many segment fixups (Objtohex) This is an internal compiler error. or an internal error in the linker. (427) syntax error in checksum list (Objtohex) There is a syntax error in a checksum list read by OBJTOHEX. Contact Microchip Technical Support with details. DS52053B-page 413 .Error and Warning Messages (417) seek error in "*" (Linker) This is an internal compiler error. not absolute. or that the linker or OBJTOHEX have been given invalid options. Libr) The object file passed to OBJTOHEX or the librarian is corrupted. (418) image too big (Objtohex) This is an internal compiler error. (429) bad segment fixups (Objtohex) This is an internal compiler error. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. This may indicate it is the wrong object file. This probably means it is not an object file. (424) record too long (Objtohex) This is an internal compiler error. Contact Microchip Technical Support with details. Otherwise this may be an internal compiler error and you should contact Microchip Technical Support with details. (431) bad argument to -E (Objtoexe) (Objtohex) This option requires an integer argument in either base 8. The object output files from the assembler are relocatable. Contact Microchip Technical Support with details.

giving address ranges to the linker. -Ctext=ROM. Case in not important for any number or radix. in decimal. Decimal is the default. (441) bad -A spec: "*" (Linker) The format of a -A specification.. for example: -GA/f0+10 (Linker) Did you forget the radix? -GA/f0h+10 (436) psect "*" re-orged This psect has had its start address specified more than once.3 “OBJTOHEX” for more details. giving a delta value to a class. Change some global symbols to local symbols to reduce the number of symbols. is invalid. If you are invoking objtohex directly. (438) bad size in -S option (Linker) The address given in a -S specification is invalid: it should be a valid number. for example: -ACODE What is the range for this class? Maybe you meant: -ACODE=0h-1fffh DS52053B-page 414  2012 Microchip Technology Inc. for example: What is the delta value for this class? Maybe you meant something like: -DCODE=2 (440) bad delta value in -D spec (Linker) The delta value supplied to a -D specification is invalid. is invalid. e. octal or hexadecimal radix. A leading 0x may also be used for hexadecimal. (434) too many symbols (*) (Linker) There are too many symbols in the symbol table.2. which has a limit of * symbols.3 “-Cpsect=class” for more information.MPLAB® XC8 C Compiler User’s Guide (432) usage: objtohex [-ssymfile] [object-file [exe-file]] (Objtohex) Improper usage of the command-line tool objtohex. This value should an integer of base 8. for example: -SCODE=f000 Did you forget the radix? -SCODE=f000h (439) bad -D spec: "*" -DCODE (Linker) The format of a -D specification. (435) bad segment selector "*" The segment specification option (-G) to the linker is invalid. for octal. See Section 7. or H for HEX. . 10 or 16. refer to Section 8. (437) missing "=" in class spec (Linker) (Linker) A class spec needs an = sign. The radix is specified by a trailing O.g. Otherwise this may be an internal compiler error and you should contact Microchip Technical Support with details.

. for octal. -. Decimal is the default. in decimal. DS52053B-page 415 ..2. The radix is specified by a trailing O (for octal) or H for HEX.” for more information. for example: -AROM=1000h maybe you meant: -AROM=1000h-1fffh (445) bad high address "*" in -A spec (Linker) The high address given in a -A specification is invalid: it should be a valid number. for example: -ACODE=0h-ffff Did you forget the radix? -ACODE=0h-ffffh See Section 7. in decimal. octal or hexadecimal radix. or H for HEX. for example: -AENTRY=0-0FFh-1FF Did you forget the radix? -AENTRY=0-0FFh-1FFh  2012 Microchip Technology Inc. octal or hexadecimal radix. for example: -ACODE= What is the range for this class? Maybe you meant: -ACODE=0h-1fffh (443) bad low address "*" in -A spec (Linker) The low address given in a -A specification is invalid: it should be a valid number..1 “-Aclass =low-high. (446) bad overrun address "*" in -A spec (Linker) The overrun address given in a -A specification is invalid: it should be a valid number. Case in not important for any number or radix. A leading 0x may also be used for hexadecimal. Case in not important for any number or radix. between the high and low addresses in a -A linker option. giving address ranges to the linker.Error and Warning Messages (442) missing address in -A spec (Linker) The format of a -A specification. for example: -ACODE=1fff-3fffh Did you forget the radix? -ACODE=1fffh-3fffh (444) expected "-" in -A spec (Linker) There should be a minus sign. is invalid. octal or hexadecimal radix. The radix is specified by a trailing O. A leading 0x may also be used for hexadecimal. in decimal. A leading 0x may also be used for hexadecimal. Decimal is default. Decimal is default. The radix is specified by a trailing O (for octal) or H for HEX. Case in not important for any number or radix.

for example: -ACODE=0h-3fffh/a000 Did you forget the radix? -ACODE=0h-3fffh/a000h (448) bad repeat count "*" in -A spec The repeat count given in a -A specification is invalid. for example: -pbss=f000 Did you forget the radix? -pbss=f000h (452) bad "+" (minimum address) format in -P option (Linker) The minimum address specification in the linker’s -p option is badly formatted. The radix is specified by a trailing O (for octal) or H for HEX. but is not defined in any module within the program. for example: -AENTRY=0-0FFhxf (Linker) Did you forget the radix? -AENTRY=0-0FFhxfh (449) syntax error in -A spec: * The -A spec is invalid. in decimal. A leading 0x may also be used for hexadecimal. . DS52053B-page 416  2012 Microchip Technology Inc. Decimal is default.MPLAB® XC8 C Compiler User’s Guide (447) bad load address "*" in -A spec (Linker) The load address given in a -A specification is invalid: it should be a valid number. (451) bad psect origin format in -P option (Linker) The origin format in a -p option is not a validly formed decimal. for example: -pbss=data+f000 Did you forget the radix? -pbss=data+f000h (453) missing number after "%" in -P option (Linker) The % operator in a -p option (for rounding boundaries) must have a number after it. A valid -A spec should be something like: -AROM=1000h-1FFFh (450) psect "*" was never defined (Linker) (Linker) This psect has been listed in a -P option. octal or HEX number. octal or hexadecimal radix. A HEX number must have a trailing H. Case in not important for any number or radix. nor is it the name of an existing psect.

/1000h Both of these options are valid and equivalent. if necessary. Contact Microchip Technical Support with details. DS52053B-page 417 . Contact Microchip Technical Support with details. Contact Microchip Technical Support if this is not handwritten assembler code." in -P option (Linker) The link and load address of a psect have both been specified with a dot character. if a psect must be on a 4K byte boundary. (466) undefined symbol "*" in FNINDIR record (Linker) The linker has found an undefined symbol in the FNINDIR record for a non-reentrant function. * The creation of the output file failed when removing an intermediate file. you could not start it at 100H. (459) remove failed. error: *. Contact Microchip Technical Support if this is not handwritten assembler code. Code Generator) (xstrip) (xstrip) This is an internal compiler error. (460) rename failed. (467) undefined symbol "*" in FNADDR record (Linker) The linker has found an undefined symbol in the FNADDR record for a non-reentrant function. However. for example: -Pmypsect=1000h/. the following usage is ambiguous: -Pmypsect=. Check the relocatability of the psect and correct the -p option./.Error and Warning Messages (454) link and load address can’t both be set to ". For example. (468) undefined symbol "*" in FNCALL record (Linker) The linker has found an undefined symbol in the FNCALL record for a non-reentrant function. (456) psect "*" not loaded on 0x* boundary (Linker) This psect has a relocatability requirement that is not met by the load address given in a -p option.  2012 Microchip Technology Inc. error: *. What is the link or load address of this psect? (455) psect "*" not relocated on 0x* byte boundary (Linker) This psect is not relocated on the required boundary. (465) undefined symbol "*" in FNBREAK record (Linker) The linker has found an undefined symbol in the FNBREAK record for a non-reentrant function. * The creation of the output file failed when renaming an intermediate file. (461) can’t create * file "*" (Assembler. (464) missing key in avmap file (Linker) This is an internal compiler error. Contact Microchip Technical Support if this is not handwritten assembler code. Only one of these addresses may be specified in this manner. -Pmypsect=. Contact Microchip Technical Support if this is not handwritten assembler code.

Contact Microchip Technical Support if this is not handwritten assembler code. } (472) non-reentrant function "*" appears in multiple call graphs: rooted at "*" and "*" (Linker) This function can be called from both main-line code and interrupt code. Contact Microchip Technical Support if this is not handwritten assembler code. /* scan is called from an interrupt function */ } void process(int a) { scan(a). (470) undefined symbol "*" in FNSIZE record (Linker) The linker has found an undefined symbol in the FNSIZE record for a non-reentrant function. } #pragma interrupt_level 1 void interrupt bar(void) { // this function never calls foo() } DS52053B-page 418  2012 Microchip Technology Inc.. One or more of these functions has statically allocated local variables (compiled stack). or recode to avoid using local variables or parameters. . for example: #pragma interrupt_level 1 void foo(void) { . /* scan is also called from main-line code */ } (473) function "*" is not called from specified interrupt_level (Linker) The indicated function is never called from an interrupt function of the same interrupt level. for example: int test(int a) { if(a == 5) { /* recursion may not be supported by some compilers */ return test(a++). Either use the reentrant keyword (if supported with this compiler) or recode to avoid recursion. } return 0. or duplicate the function. Use the reentrant keyword.MPLAB® XC8 C Compiler User’s Guide (469) undefined symbol "*" in FNROOT record (Linker) The linker has found an undefined symbol in the FNROOT record for a non-reentrant function. for example: void interrupt my_isr(void) { scan(6). (471) recursive function calls: (Linker) These functions (or function) call each other recursively. if this compiler supports it..

Note that a size which is not a multiple of 8 bits will be rounded up to the nearest byte size. then clearly this value cannot be inserted into the instruction. is typically the only information needed to track down the cause of this error.Error and Warning Messages (474) no psect specified for function variable/argument allocation (Linker) The FNCONF assembler directive which specifies to the linker information regarding the auto/parameter block was never seen.obj. This would be typically be the output of compiling main. See the following error message (477) for more information. 7 8 9 07FC 07FD 07FE 0E21 6FFC 0012 MOVLW 33 MOVWF _foo RETURN and to confirm.e. This error may imply that the correct run-time startup module was not linked. The location (loc) of the instruction (0x1FD). This takes place after positioning the psects (program sections or blocks) into the available memory on the target device. The causes for this can be many. Generate an assembler list file for the appropriate module. i. size *. This is supplied in the standard runtime files if necessary. value 0x*) (Linker) Fixup is the process conducted by the linker of replacing symbolic references to variables etc. however. Consider the following error message. the instruction causing the problem takes an 8-bit offset into a bank of memory. size 1. DS52053B-page 419 . but clearly the address 0x1FC exceeds this size. size *. Badly written C code can also generate assembler that ultimately generates fixup overflow errors. For example. Fixup overflow is when the value determined for a symbol is too large to fit within the allocated space within the assembler instruction. and the value which is the actual value the symbol represents. main. a 7 bit space in an instruction will be shown as 1 byte. the size (in bytes) of the field in the instruction for the value (1). you can identify the record. and is included in the standard runtime startup code which is normally linked into every program. This directive should be specified only once. Ensure you have used the FNCONF directive if the runtime startup module is hand-written. Look for the address specified in the error message. (477) fixup overflow in expression (location 0x* (0x*+*). in an assembler instruction with an absolute value. (475) conflicting FNCONF records (Linker) The linker has seen two conflicting FNCONF directives. value 0x*) (Linker) The linker was asked to relocate (fixup) an item that would not fit back into the space after relocation.obj: 8: Fixup overflow in expression (loc 0x1FD (0x1FC+1). This tells you the file in which you should be looking. if an assembler instruction has an 8-bit field to hold an address and the linker determines that the symbol that has been used to represent this address has the value 0x110. you do not normally need to do this.c or main. (476) fixup overflow referencing * * (location 0x* (0x*+*). Symbol Table _foo 01FC _main 07FF Fri Aug 12 13:17:37 2004 In this example.. Maybe the instruction should have been written as:  2012 Microchip Technology Inc. value 0x7FC) This indicates that the file causing the problem was main. If you use the DUMP utility to examine the object file. but hand-written assembler code is always the first suspect.as. The next number (8 in this example) is the record number in the object file that was causing the problem. look for the symbol referenced in the assembler instruction at this address in the symbol table at the bottom of the same file.

for example: _next: MOVE r0. Check what declarations for the function are visible in the two modules specified and make sure they are compatible. (482) symbol "*" is defined more than once in "*" (Linker) (Assembler) This symbol has been defined in more than one place.MPLAB® XC8 C Compiler User’s Guide MOVWF (_foo&0ffh) which masks out the top bits of the address containing the bank information. Note that C identifiers often have an underscore prepended to their name after compilation. oops -. incorrectly qualified pointers are an common trigger. If the assembler instruction that caused this error was generated by the compiler. i. Contact Microchip Technical Support with details. The names of the modules are given in the error message. (484) psect "*" can’t be in classes "*" and "*" (Linker) A psect cannot be in more than one class. This means it has been declared differently. You will then need to examine the C code for possible errors. r0 _next: . value 0x* > limit 0x*) (Linker) This is an internal compiler error. for example: psect final. (478) * range check failed (location 0x* (0x*+*). char type) { (481) common symbol "*" psect conflict A common symbol has been defined to be in more than one psect..class=CODE finish: /* elsewhere: */ psect final. in turn. This is either due to assembler modules with conflicting class= options to the PSECT directive.e. (480) function signatures do not match: * (*): 0x*/0x* (Linker) The specified function has different signatures in different modules. has been equated to the first symbol. #55 MOVE [r1]. for example: extern int get_value(int in). Contact Microchip Technical Support with details. /* and in another module: */ /* this is different to the declaration */ int get_value(int in. it may have been prototyped in one module and not another.class=ENTRY DS52053B-page 420  2012 Microchip Technology Inc. (483) symbol "*" can’t be global (Linker) This is an internal compiler error. or use of the -C option to the linker. in the assembler list file look back up the file from the instruction at fault to determine which C statement has generated this instruction.choose a different name The linker will issue this warning if the symbol (C or assembler) was defined multiple times in different modules. . The assembler will issue this error if a symbol is defined more than once in the same module. (479) circular indirect definition of symbol "*" (Linker) The specified symbol has been equated to an external symbol which.

Names such as bss or data refer to variable blocks.class=CODE. In other words. (488) psect "*" memory space redefined: */* (Linker) A global psect has been defined in two different memory spaces. The error message indicates the name of the psect that the linker was attempting to position and the segment name which is typically the name of a class which is defined with a linker -A option. the size of the program or the program’s data has exceeded the total amount of space on the selected device. Section 5. (487) psect "*" type redefined: */* (Linker) (Linker) This psect has had its type defined differently by different modules.class=RAM. for example: psect spdata. some part of your device’s memory has completely filled. if they are the same psect. This error indicates that the linker was unable to find an area of free memory large enough to accommodate one of the psects.space=1 (489) psect "*" memory delta redefined: */* A global psect has been defined with two different delta values.Error and Warning Messages (485) unknown "with" psect referenced by psect "*" (Linker) The specified psect has been placed with a psect using the psect with flag. if they are the same class. place them in the same memory space using the space psect flag.delta=2 finish: .delta=1 (Linker) (490) class "*" memory space redefined: */* (Linker) A class has been defined in two different memory spaces. then the size of the specified psect must be reduced. i. First. linking 386 flat model code with 8086 real mode code.class=RAM. This error can be due to two reasons.space=0 ds 6 . DS52053B-page 421 . or include.class=CODE.with=rext .  2012 Microchip Technology Inc. Either rename one of the classes or.. If this is the case. place them in the same memory space. elsewhere: psect final.class=CODE.15. The psect it has been placed with does not exist. (491) can’t find 0x* words for psect "*" in segment "*" (Linker) One of the main tasks the linker performs is positioning the blocks (or psects) of code and data that is generated from the program into the memory available for the target device. Either rename one of the psects or. Typically psect names which are. text relate to program code. This probably means you are trying to link incompatible object modules. elsewhere: psect spdata.e. for example: psect starttext.2 “Compiler-Generated Psects” lists each compiler-generated psect and what it contains. for example: psect final. was that meant to be with text? (486) psect "*" selector value redefined The selector value for this psect has been defined more than once.

If the name is not present. Thus. UNUSED ADDRESS RANGES CODE RAM 00000244-0000025F 00001000-0000102f 00300014-00301FFB In the CODE segment. this requires splitting a function into two or more smaller functions (which may call each other). This applies whether the compiled code uses a hardware or compiled stack. The linker is unable to split psects in this situation. To find out what memory is still available. Notice. then all the memory available for this psect has been allocated. the linker cannot place part of a psect at one location and part somewhere else. look for the name of the segment specified in the error message. The program may need to be rewritten so that it needs less variables. (If the string Call graph: is not present in the map file. If the default linker options must be changed. . (493) origin of psect "*" is defined more than once (Linker) The origin of this psect is defined more than once.MPLAB® XC8 C Compiler User’s Guide The second cause of this message is when the total amount of memory needed by the psect being positioned is sufficient. Section 4.) If a data psect needs to be split into smaller psects. Psects containing code can be reduced by using all the compiler’s optimizations.8. see Section 4. Determine the size of each block and compare this with the number of words specified in the error message. or restructuring the program.7 “-L-: Adjust Linker Options Directly”. the programmer has little control over their operation. that the total amount of memory available is larger than 0x34 bytes. see Section 4. That is. or remove the -P linker option. (492) attempt to position absolute psect "*" is illegal (Linker) This psect is absolute and should not have an address specified in a -P option. If a code psect must be split into two or more small psects. Memory allocation for auto variables is entirely handled by the compiler. the definitions for variables will need to be moved to new modules or more evenly spread in the existing modules. Neither of these are large enough to accommodate the psect text which is 0x34 bytes long. there is 0x1c (0x25f-0x244+1) bytes of space available in one block and 0x30 available in another block. These functions may need to be placed in new modules. Either remove the abs psect flag.option. but that this memory is fragmented in such a way that the largest contiguous block is too small to accommodate the psect.8 “-M: Generate Map File” for information on how to generate a map file. this can be done indirectly through the driver using the driver -L.8. after receiving the message: Can’t find 0x34 words (0x34 withtotal) for psect text in segment CODE (error) look in the map file for the ranges of unused memory. there will be one address range specified under this segment for each free block of memory. Other than reducing the number of these variables used. however. generate and look in the map file. There is most likely more than one -p linker option specifying this psect. If it is present. Search for the string UNUSED ADDRESS RANGES. then the compiled code uses a hardware stack.8. Psects containing data may be reduced when invoking the compiler optimizations. For example.8 “-M: Generate Map File” has information on interpreting the map file’s call graph if the compiler you are using uses a compiled stack. Under this heading. the linker must be able to find a contiguous block of memory large enough for every psect. If this is the cause of the error. then the psect must be split into smaller psects if possible. but the effect is less dramatic. DS52053B-page 422  2012 Microchip Technology Inc.

(499) undefined symbol: (Assembler. The runtime startup code defines the entry point. This means they are for different device types.  2012 Microchip Technology Inc. end of file and define entry point . This could be due to spelling error.Error and Warning Messages (494) bad -P format "*/*" (Linker) The -P option given to the linker is malformed. when that psect was also defined using a with psect flag. These errors could be due to spelling error. Check that you are using the correct linker. or failure to link an appropriate module. or failure to link an appropriate module. for example: powerup: goto start END powerup . (504) object code version is greater than *. This option specifies placement of a psect. Contact Microchip Technical Support if the object file if you have not patched the linker. Linker) The symbol following is undefined at link time. (497) psect "*" exceeds max size: *h > *h (Linker) The psect has more bytes in it than the maximum allowed as specified using the size psect flag. (501) program entry point is defined more than once (Linker) There is more than one entry point defined in the object files given the linker. (498) psect "*" exceeds address limit: *h > *h (Linker) The maximum address of the psect exceeds the limit placed on it using the limit psect flag.* (Linker) The object code version of an object module is higher than the highest version the linker is known to work with. Contact Microchip Technical Support with details. MESSAGES 500-749 (500) undefined symbols: (Linker) A list of symbols follows that were undefined at link time. End entry point is specified after the END directive. other files that use END should not define another entry point (502) incomplete * record body: length = * (Linker) An object file contained a record with an illegal size. DS52053B-page 423 . for example: -Ptext=10g0h Maybe you meant: -Ptext=10f0h (495) use of both "with=" and "INCLASS/INCLASS" allocation is illegal (Linker) It is not legal to specify both the link and location of a psect as within a class. This probably means the file is truncated or not an object file. Either the psect needs to be linked at a different location or there is too much code/data in the psect. (503) ident records do not match (Linker) The object files passed to the linker do not have matching ident records.

In this case. the routines are linked in a special sequence so that program execution falls through from one routine to the next. This probably means the file is corrupted or not an object file. (511) bad complex range check (Linker) This is an internal compiler error. Contact Microchip Technical Support if the object file was generated by the compiler. check your source code. or that there is an internal error in the assembler or linker. This probably means the file is corrupted or not an object file. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details if the object file was created by the compiler. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. (520) function "*" is never called (Linker) This function is never called. Probably means an object file is corrupted. . Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. (515) unknown symbol type * (Linker) This is an internal compiler error. (512) unknown complex operator 0x* (Linker) This is an internal compiler error. Contact Microchip Technical Support with details. (510) complex relocation not supported for -R or -L options (Linker) The linker was given a -R or -L option with file that contain complex relocation. (507) unexpected end of file in object file (Linker) This is an internal compiler error. (513) bad complex relocation (Linker) The linker has been asked to perform complex relocation that is not syntactically correct.. This either means you are using a linker that is out of date. but space could be saved by removing it. although they are actually execute. This may not represent a problem.*-*-1 (Linker) This is an internal compiler error. (516) text record has bad length: *-*-(*+1) < 0 (Linker) This is an internal compiler error. (506) object file record too long: *+* (Linker) This is an internal compiler error. (508) relocation offset (*) out of range 0. (514) illegal relocation type: * (Linker) An object file contained a relocation record with an illegal relocation type. (521) call depth exceeded by function "*" (Linker) The call graph shows that functions are nested to a depth greater than specified. Contact Microchip Technical Support with details if the object file was created by the compiler.MPLAB® XC8 C Compiler User’s Guide (505) no end record found inobject file (Linker) An object file did not contain an end record. Contact Microchip Technical Support with details. If you believe this function should be called. Some assembler library routines are never called. DS52053B-page 424  2012 Microchip Technology Inc. (509) illegal relocation size: * (Linker) There is an error in the object code format read by the linker.

(594) undefined symbol: (Linker) (Linker) The symbol following is undefined at link time. For warning levels.2 “-N”. It has been linked at the end of the program. but it will link faster if better ordered. The linker would be trying to fixup the list file so that it will contain absolute addresses. (528) no start record. (599) No psect classes given for COFF write (Cromwell) CROMWELL requires that the program memory psect classes be specified to produce a COFF file. (596) segment "*" (*-*) overlaps segment "*" (*-*) (Linker) The named segments have overlapping code or data. (523) argument to -W option (*) illegal and ignored (Linker) The argument to the linker option -w is out of range. the range is -9 to 9. It will still link correctly. this may be an internal compiler error and you should contact Microchip Technical Support with details. For the map file width. Alternatively. (529) usage: objtohex [-Ssymfile] [object-file [HEX-file]] (Objtohex) Improper usage of the command-line tool objtohex. entry point defaults to zero (Linker) None of the object files passed to the linker contained a start record. This option controls two features. (524) unable to open list file "*": * (Linker) The named list file could not be opened.Error and Warning Messages (522) library "*" is badly ordered (Linker) This library is badly ordered. This could be due to spelling error. (595) undefined symbols: (Linker) A list of symbols follows that were undefined at link time. (593) can’t find 0x* words (0x* withtotal) for psect "*" in segment "*" See message (491). remove the assembler list file generation option from the link step. The start address of the program has been set to zero. or failure to link an appropriate module. but it is recommended that you define a start address in your startup module by using the END directive. space (*) ignored (Linker) The limit to the number of address spaces (specified with the PSECT assembler directive) is currently 16. DS52053B-page 425 .3 “OBJTOHEX” for more details. This may be harmless. Ensure that an assembler list file was generated during the compilation stage. If you are invoking objtohex directly then refer to Section 8. Check the addresses being assigned by the -P linker option. the range is greater than or equal to 10. (526) psect "*" not specified in -P option (first appears in "*") (Linker) This psect was not specified in a -P or -A option to the linker.  2012 Microchip Technology Inc. Otherwise. which is probably not where you wanted it. (525) too many address (memory) spaces. These errors could be due to spelling error. Ensure that you are using the -N option as per Section 8.5. or failure to link an appropriate module.

P&E or HI-TECH.architecture]” and that the architecture specified matches one of those in Table 8-7.1 “-Pname[. (606) inconsistent symbol tables (Cromwell) This is an internal compiler error.sym -ocot (Cromwell) and output file type of cot. (613) no output file format specified The output format must be specified to CROMWELL. COFF. Contact Microchip Technical Support with details. (603) ambiguous file format name "*" (Cromwell) (Cromwell) The input or output format specified to CROMWELL is ambiguous. . OMF51. (Cromwell) (Cromwell) (Cromwell) (Cromwell) DS52053B-page 426  2012 Microchip Technology Inc. (608) bad path specification (Cromwell) This is an internal compiler error. (607) inconsistent line number tables (Cromwell) This is an internal compiler error. (604) unknown file format name "*" The output format specified to CROMWELL is unknown. Contact Microchip Technical Support with details. Intel HEX. (609) missing device spec after -P The -p option to CROMWELL must specify a device name. did you mean cof? (605) did not recognize format of input file (Cromwell) The input file to CROMWELL is required to be COD. Ensure that you are using the -P option as per Section 8. Contact Microchip Technical Support with details. Motorola HEX.5. (614) no input files specified CROMWELL must have an input file to convert. (602) null file format name The -I or -O option to CROMWELL must specify a file format. for example: cromwell -m -P16F877 main.MPLAB® XC8 C Compiler User’s Guide (600) No chip arch given for COFF write (Cromwell) CROMWELL requires that the chip architecture be specified to produce a COFF file. (610) missing psect classes after -N (Cromwell) (Cromwell) CROMWELL requires that the -N option be given a list of the names of psect classes. (611) too many input files To many input files have been specified to be converted by CROMWELL. Ensure that you are using the -P option as per Table 8-7. These formats are specified with the -i key and -o key options respectively.HEX main. (612) too many output files To many output file formats have been specified to CROMWELL. (601) Unknown chip arch "*" for COFF write (Cromwell) The chip architecture specified for producing a COFF file isn’t recognized by CROMWELL.

(624) bad class in type compare (Cromwell) This is an internal compiler error. Contact Microchip Technical Support with details. (627) missing "*" in SDB file "*" line * column * (Cromwell) This is an internal compiler error. Contact Microchip Technical Support with details. (630) invalid syntax for prefix list in SDB file "*" (Cromwell) This is an internal compiler error. (626) string lookup failed in COFF: get_string() (Cromwell) This is an internal compiler error. (631) syntax error at token "*" in SDB file "*" line * column * (Cromwell) This is an internal compiler error. (620) filename index out of range in line number record The COD file has an invalid value in the specified record. Contact Microchip Technical Support with details. Microchip COFF. Confirm the spelling and path of the file specified on the command line. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. Confirm the spelling and path of the file specified on the command line. DS52053B-page 427 . Contact Microchip Technical Support with details. (632) can’t handle address size (*) (Cromwell) This is an internal compiler error. Contact Microchip Technical Support with details. (619) I/O error reading symbol table The COD file has an invalid format in the specified record. (618) error reading COD file data (Cromwell) An error occurred reading the input COD file. (625) too many files in COFF file (Cromwell) This is an internal compiler error.Error and Warning Messages (616) option -Cbaseaddr is illegal with options -R or -L (Linker) The linker option -Cbaseaddr cannot be used in conjunction with either the -R or -L linker options. (633) unknown symbol class (*) (Cromwell) CROMWELL has encountered a symbol class in the symbol table of a COFF.  2012 Microchip Technology Inc. or ICOFF file which it can’t identify. Contact Microchip Technical Support with details. (629) bad storage class "*" in SDB file "*" line * column * (Cromwell) This is an internal compiler error. (622) too many type entries (Cromwell) This is an internal compiler error. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. (621) error writing ELF/DWARF section "*" on "*" (Cromwell) (Cromwell) (Cromwell) An error occurred writing the indicated section to the given file. (623) bad class in type hashing (Cromwell) This is an internal compiler error.

(638) version mismatch: 0x* expected The input Microchip COFF file wasn’t produced using CROMWELL. (671) argument to -T should be in range 1 to 64 (Clist) The argument to the -T option to specify tab size was not in the expected range. (637) unknown prefix "*" in SDB file "*" (Cromwell) This is an internal compiler warning. (639) zero bit width in Microchip optional header (Cromwell) (Cromwell) The optional header in the input Microchip COFF file indicates that the program or data memory spaces are zero bits wide. (678) case 55 on pic17! (Code Generator) This is an internal compiler error. (670) bad argument to -T (Clist) The argument to the -T option to specify tab size was not present or correctly formed.  2012 Microchip Technology Inc. Contact Microchip Technical Support with details. (673) missing filename after * option (Objtohex) The indicated option requires a valid file name. Hexmate) A checksum error was found at the specified line in the specified Intel HEX file. (677) set_fact_bit on pic17! (Code Generator) This is an internal compiler error. The HEX file may be corrupt. (668) prefix list did not match any SDB types (Cromwell) This is an internal compiler error. (680) bad format for -P option (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. The option expects a decimal integer argument. Ensure that the filename argument supplied to this option exists and is spelt correctly. Contact Microchip Technical Support with details. Contact Microchip Technical Support if the HEX file was generated by the compiler. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details.MPLAB® XC8 C Compiler User’s Guide (634) error dumping "*" (Cromwell) Either the input file to CROMWELL is of an unsupported type or that file cannot be dumped to the screen. The option expects a decimal integer argument ranging from 1 to 64 inclusive. Contact Microchip Technical Support with details. DS52053B-page 428 . (669) prefix list matched more than one SDB type (Cromwell) This is an internal compiler error. (674) too many references to "*" (Cref) This is an internal compiler error. (635) invalid HEX file "*" on line * (Cromwell) The specified HEX file contains an invalid line. (679) unknown extraspecial: * (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details. (636) checksum error in Intel HEX file "*" on line * (Cromwell.

Contact Microchip Technical Support with details. (684) bank 2 and 3 variables are not supported by the PICC Lite compiler (Code Generator) A variable with an absolute address located in bank 2 or 3 was detected. (692) interrupt function "*" may only have one interrupt level (Code Generator) (Code Generator) Only one interrupt level may be associated with an interrupt function. for example: void interrupt isr(void) @ 0x10 { /* isr code goes here */ } This construct is not required for mid-range PIC devices. Contact Microchip Technical Support with details. (685) bad putwsize() (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details.Error and Warning Messages (681) bad common spec in -P option (Code Generator) This is an internal compiler error. (688) bad popreg "*" (Code Generator) This is an internal compiler error. (686) bad switch size (*) (Code Generator) This is an internal compiler error. For example: #pragma interrupt_level 0 #pragma interrupt_level 1 void interrupt isr(void) { /* which is it to be: 0 or 1? */  2012 Microchip Technology Inc. This compiler only supports devices from these architecture families. (691) interrupt functions not implemented for 12 bit PIC MCU The 12-bit range of PIC MCU processors do not support interrupts. This compiler does not support code generation of variables in these banks. (682) this architecture is not supported by the PICC™ Lite compiler (Code Generator) A target device other than baseline. Contact Microchip Technical Support with details. DS52053B-page 429 . Contact Microchip Technical Support with details. This pragma may be used more than once on main-line functions that are called from interrupt functions. This compiler does not support code generation of variables in this bank. (689) unknown predicate "*" (Code Generator) This is an internal compiler error. mid-range or highend was specified. (683) bank 1 variables are not supported by the PICC Lite compiler (Code Generator) A variable with an absolute address located in bank 1 was detected. An @ address is required with the interrupt definition to indicate with which vector this routine is associated. Contact Microchip Technical Support with details. (687) bad pushreg "*" (Code Generator) This is an internal compiler error. (690) interrupt function requires address (Code Generator) The high end PIC devices support multiple interrupts. Check to ensure that only one interrupt_level pragma has been used with the function specified.

for example: (Code Generator) switch(input) { } /* there is nothing to match the value of input */ (700) truncation of enumerated value (Code Generator) An enumerated value larger than the maximum value supported by this compiler was detected and has been truncated. #pragma interrupt_level 2 /* oops -. BIG=0x99999999 } test_case.. for example: enum { ZERO. /* oops -bb = (a > 66). case ’0’: /* then what is this case? */ b--. (701) unreasonable matching depth (Code Generator) This is an internal compiler error. } (Code Generator) There are two case labels with the same value in this switch statement. DS52053B-page 430  2012 Microchip Technology Inc.MPLAB® XC8 C Compiler User’s Guide (693) interrupt level may only be 0 (default) or 1 (Code Generator) The only possible interrupt levels are 0 or 1. return bb. Contact Microchip Technical Support with details. for example: bit proc(int a) { bit bb. for example: (696) out-of-range case label (*) (Code Generator) This case label is not a value that the controlling expression can yield. */ (699) no case labels in switch There are no case labels in this switch statement. (697) non-constant case label (Code Generator) A case label in this switch statement has a value which is not a constant.only 0 or 1 */ void interrupt isr(void) { /* isr code goes here */ } (694) no interrupt strategy available (Code Generator) The device does not support saving and subsequent restoring of registers during an interrupt service routine. ONE. and thus this label will never be selected. } this should be: static bit bb. (695) duplicate case label (*) switch(in) { case ’0’: /* if this is case ’0’.. break. Check to ensure that all interrupt_level pragmas use these levels. If you require a bit variable with scope local to a block of code or function. . qualify it static. (698) bit variables must be global or static (Code Generator) A bit variable cannot be of type auto. break. */ b++.

(710) bad U usage (Code Generator) This is an internal compiler error. code which writes to a const-qualified object is illegal and will result in warning messages. (715) bad pragma "*" (Code Generator) The code generator has been passed a pragma directive that it does not understand. Contact Microchip Technical Support with details.Error and Warning Messages (702) regused(): bad arg to G (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details. using a temporary variable to hold an intermediate result. For example.  2012 Microchip Technology Inc. Contact Microchip Technical Support with details. Simplifying the expression. i. Contact Microchip Technical Support with details of this message. (709) metaregister "*" can’t be used directly (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details. but the code generator may unsuccessfully try to produce code to perform the write. (705) bad which (*) after I (Code Generator) This is an internal compiler error. For successful code generation.e. (712) can’t generate code for this expression (Code Generator) This error indicates that a C expression is too difficult for the code generator to actually compile. This error may also be issued if the code being compiled is unusual. DS52053B-page 431 .. Contact Microchip Technical Support with details. (708) bad mod "+" for how = "*" (Code Generator) This is an internal compiler error. (703) bad GN (Code Generator) This is an internal compiler error. (704) bad RET_MASK (Code Generator) This is an internal compiler error. may work around this message. Contact Microchip Technical Support with details. (707) bad SX (Code Generator) This is an internal compiler error.. (706) bad which in expand() (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details. (713) bad initialization list (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details.e. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. This implies that the pragma you have used is not implemented for the target device. (711) bad how in expand() (Code Generator) This is an internal compiler error. registers or temporary memory locations) available. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. (714) bad intermediate code (Code Generator) This is an internal compiler error. the code generator must know how to compile an expression and there must be enough resources (i.

Contact Microchip Technical Support with details. (728) bad op "*" in confloat() (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details.MPLAB® XC8 C Compiler User’s Guide (716) bad argument to -M option "*" (Code Generator) The code generator has been passed a -M option that it does not understand. Contact Microchip Technical Support with details if required. Contact Microchip Technical Support with details. /* oops! b1 must be assigned after its definition */ (Code Generator) DS52053B-page 432  2012 Microchip Technology Inc.* (Code Generator) The intermediate code file produced by P1 is not the correct version for use with this code generator. (730) bad op "*" ( Code Generator) This is an internal compiler error. (726) bad op "*" in uconval() (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. (729) bad op "*" in conval() (Code Generator) This is an internal compiler error. (721) element count must be constant expression (Code Generator) This is an internal compiler error. (727) bad op "*" in bconfloat() (Code Generator) This is an internal code generator error. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. This should not happen if it is being invoked by a standard compiler driver. Contact Microchip Technical Support with details. should be *. (731) expression error with reserved word (Code Generator) This is an internal compiler error. (718) incompatible intermediate code version. This is either that incompatible versions of one or more compilers have been installed in the same directory. . or a temporary file error has occurred leading to corruption of a temporary file. (720) multiple free: * (Code Generator) This is an internal compiler error. Contact Microchip Technical Support with details. for example: bit b1 = 1. If it refers to a long path name. (724) bad op (*) in revlog() (Code Generator) This is an internal compiler error. since C cannot have nested functions! Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. (723) function definitions nested too deep (Code Generator) This error is unlikely to happen with C code. (732) initialization of bit types is illegal Variables of type bit cannot be initialized. change it to something shorter. Check the setting of the TEMP environment variable. (722) bad variable syntax in intermediate code (Code Generator) This is an internal compiler error.

/* oops -.that’s larger than 8 bits wide */ (742) function "*" argument evaluation overlapped (Linker) A function call involves arguments which overlap between two functions. (740) zero dimension array is illegal (Code Generator) The code generator has been passed a declaration that results in an array having a zero dimension. /* Offending call */ } char fn2(char fred) { return fred + fn3(5.Error and Warning Messages (733) bad string "*" in pragma "psect" (Code Generator) The code generator has been passed a pragma psect directive that has a badly formed string. } where fn1 is calling fn3 . The program structure should be modified to prevent this type of call sequence. } object. char three) { return one+two+three. (741) bitfield too large (* bits) struct { unsigned flag : 1. This could occur with a call like: void fn1(void) { fn3( 7. which in turn calls fn3. (737) unknown argument "*" to pragma "switch" (Code Generator) The #pragma switch directive has been used with an invalid switch code generation method. the same size as the storage unit width. (Code Generator) The maximum number of bits in a bit-field is 8. DS52053B-page 433 .1. Possible arguments are: auto . This pragma must be followed by a number representing the maximum allowed stack size.  2012 Microchip Technology Inc. Contact Microchip Technical Support with details. char two. simple and direct. for example: #pragma psect text /* redirect text psect into what? */ Maybe you meant something like: #pragma psect text=special_text (734) too many "psect" pragmas Too many #pragma psect directives have been used. unsigned cont : 6. fn2(9)). } char fn3(char one. (735) bad string "*" in pragma "stack_size" (Code Generator) (Code Generator) The argument to the stack_size pragma is malformed. fn2(3). (739) error closing output file (Code Generator) The compiler detected an error when closing a file.0). and two arguments are evaluated by calling fn2 . unsigned value : 12.

but not initialized (Code Generator) An object has been qualified as const. . (747) unrecognized option "*" to -Z (Code Generator) This is an internal compiler error. As this object cannot be written by the C program. DS52053B-page 434  2012 Microchip Technology Inc. (746) object "*" qualified const.a has never been assigned a value */ process().MPLAB® XC8 C Compiler User’s Guide (743) divide by zero (Code Generator) An expression involving a division by zero has been detected in your code. if(a) /* oops -. Contact Microchip Technical Support with details. Contact Microchip Technical Support with details. this may imply the initial value was accidently omitted. } (749) unknown register name "*" used with pragma (Linker) This is an internal compiler error. (745) nodecount = * (Code Generator) (Code Generator) This is an internal compiler error. but has a size of zero. Since it is an auto variable. (748) variable "*" may be used before set (Code Generator) This variable may be used before it has been assigned a value. for example: void main(void) { int a. Contact Microchip Technical Support with details. but there is no initial value supplied at the definition. this will result in it having a random value. (744) static object "*" has zero size A static object has been declared.

c = -1. but a signed int cannot hold the value 32880. The most common code to trigger this warning is assignments to signed data types. Therefore the result of the multiplication must also be a signed int value. regardless of variable size. This will produce an undefined result on many processors. if(a || b) b++. The constant is equal to 255 and is outside this range. /* oops -. a = b + c. c. /* assume ints are 16 bits wide */ /* this should be okay. DS52053B-page 435 . c can only be assigned values -128 to 127. For example: signed char c. This is non-portable code and is flagged as having undefined results by the C Standard. int b. therefore this is always true */ (751) arithmetic overflow in constant expression (Code Generator) A constant expression has been evaluated by the code generator that has resulted in a value that is too big for the type of the expression. but a warning is produced. but it must do so following all the ANSI C rules. i = 240 * 137. If you mean to set all bits in this variable. Why? Because 240 and 137 and both signed int values. right? */ A quick check with your calculator reveals that 240 * 137 is 32880 which can easily be stored in an unsigned int. /* int to char conversion may result in truncation */ (753) undefined shift (* bits) (Code Generator) An attempt has been made to shift a value by a number of bits equal to or greater than the number of bits in the data type. As a signed 8-bit quantity. /* a is 6. and without warning. /* force at least one operand to be unsigned */ (752) conversion to shorter data type (Code Generator) Truncation may occur in this expression as the lvalue is of shorter type than the rvalue. c = 0xFF. For example: unsigned int i. which sets all the bits in the variable.that shifts the entire value out */  2012 Microchip Technology Inc. for example: char a. (Both operands are constant values so the code generator can evaluate this expression at compile time. then use either of: c = ~0x0. Check the expression for missing or badly placed parentheses. This warning can also be triggered by intermediate values overflowing.Error and Warning Messages MESSAGES 750-999 (750) constant operand to || or && (Code Generator) One operand to the logical operators || or && is a constant. a = 6. input <<= 33.) The following code forces the multiplication to be performed with an unsigned result: i = 240u * 137. for example: { int a. for example: int input. This message may also occur if the global optimizer is enabled and one of the operands is an auto or static local variable whose value has been tracked by the code generator.

This warning may also be issued because you have written something like while(1). This will be some sort of comparison involving a variable and a constant expression.MPLAB® XC8 C Compiler User’s Guide (754) bitfield comparison out of range (Code Generator) This is the result of comparing a bit-field with a value when the value is out of range of the bit-field. comparing a 2-bit bit-field to the value 5 will never be true as a 2-bit bit-field has a range from 0 to 3.. /* mask can hold values 0 to 3 */ } value. That is. for example: a /= 0. For the code generator to issue this message. a = 5. For C code that compares these variables to constants. causing the evaluation to yield a value different to what you expected. int compare(void) { return (value.) always follows the same path. use for(. always perform the true statement */ if(a == 4) b = 6. /* divide by 0: was this what you were intending */ (757) constant conditional branch (Code Generator) A conditional branch (generated by an if . b. To produce an infinite loop. This warning may indicate more than an optimization made by the compiler. the result of the comparison can be deduced at compile time and the output code hard coded to avoid the comparison. it may be that other functions (particularly interrupt functions) may modify it and so tracking the variable cannot be performed. /* test can } (755) divide by zero (Code Generator) A constant expression that was being evaluated involved a division by zero. . for example: { int a. /* this can never be false. If a was a global variable. then immediately sets b to 6.). possibly at higher level than 1. and the warning level threshold may need to be lower than the default level of 0. for . No code will be produced for the comparison if(a == 4). while statement etc. For example: struct { unsigned mask : 2. DS52053B-page 436  2012 Microchip Technology Inc. will produce code that sets a to 5. It may indicate an expression with missing or badly placed parentheses.mask == 6). The global optimizer keeps track of the contents of local variables for as long as is possible during a function. the variable must have local scope (either auto or static local) and the global optimizer must be enabled.

where a constant is being assigned to a variable. will assign the value 4 to a. then immediately checked to see if it is equal to 10. (759) expression generates no code (Code Generator) This expression generates no output code. which checks to see if a is equal to 4. but not do anything with the value read. always perform the true statement */ if(a = 4) b = 6. always perform the true statement */ if(a == 4) b = 6. This may mean you have inadvertently used an assignment = instead of a compare ==. but has no effect at all */ Some devices require that special function register need to be read to clear hardware flags. only on the subsequent passes. /* this can never be false. and no effect on the value of the expression. Did you mean: /* this can never be false. To accommodate this. b. the comparison code cannot be removed. in some instances the code generator does produce code for a statement which only consists of a variable ID. In this case the code generator can again pick up that a is assigned the value 0. as the value of the assignment is always true. fred. for example: int a. c. a++) b = func(a). for example: int fred. (760) portion of expression has no effect (Code Generator) Part of this expression has no side effects. b. then . (758) constant conditional branch: possible use of "=" instead of "==" (Code Generator) There is an expression inside an if or other conditional construct. Check for things like leaving off the parentheses in a function call. Because a is modified during the for loop. was that meant to be a comma? */  2012 Microchip Technology Inc. b.c. /* this is valid.Error and Warning Messages A similar situation arises with for loops. This may happen for variables which are qualified as volatile. for example: { int a. but it will speed program execution. /* "b" has no effect. DS52053B-page 437 . but the code generator will adjust the code so that the comparison is not performed on the first pass of the loop. a!=10. for example: int a. /* this loop must iterate at least once */ for(a=0. This may not reduce code size. the comparison can be omitted and the assignment to b always made. a = b. Typically the output code will read the variable.

.MPLAB® XC8 C Compiler User’s Guide (761) sizeof yields 0 (Code Generator) The code generator has taken the size of an object and found it to be zero. i.a = 0x12. If you require a pointer to an array of objects of unknown length. because an unsigned value can never be less than zero. } input_grp.0x13 to large for 3-bit wide object DS52053B-page 438  2012 Microchip Technology Inc. object */ /* oops -. if(c > 300) /* oops -. for example: unsigned char c. unsigned b : 5. for example: a = 8 ? b : c. input_grp. This almost certainly indicates an error in your declaration of a pointer. */ /* oops -. such that the comparison will always be true or false. for example: struct INPUT { unsigned a : 3. /* this is the same as saying a = b. you only need a pointer to a single object that can then be indexed or incremented. (766) degenerate signed comparison (Code Generator) There is a comparison of a signed value with the most negative value possible for this type.how can this be true? */ close(). you may have declared a pointer to a zero length array. for example: struct INPUT { unsigned a : 3. for example: char c. } input_grp. if(c >= 0) will always be true. because an 8 bit signed char has a maximum negative value of -128. thus the result of the tertiary operator ?: will always be the same.e.a |= 0x13. (762) constant truncated when assigned to bitfield (Code Generator) A constant value is too large for a bitfield structure member to which it is being assigned.. (765) degenerate unsigned comparison (Code Generator) There is a comparison of an unsigned value with zero. unsigned b : 5. for example: unsigned char c. */ (764) mismatched comparison (Code Generator) A comparison is being made between a variable or expression and a constant value which is not in the range of possible values for that expression. which will always be true or false. In general.0x12 cannot fit into a 3-bit wide (763) constant left operand to "? :" operator (Code Generator) The left operand to a conditional operator ? is constant. (767) constant truncated to bitfield width (Code Generator) A constant value is too large for a bit-field structure member on which it is operating. pointers to arrays are of little use. input_grp. if(c >= -128) will always be true.

Error and Warning Messages (768) constant relational expression (Code Generator) There is a relational expression that will always be true or false. (769) no space for macro definition The assembler has run out of memory. (773) macro expansions nested too deep (Assembler) Macro expansions in the assembler are nested too deep. there is no hierarchy. Contact Microchip Technical Support with details. what a program! (781) can’t enter abs psect (Assembler) (Assembler) (Assembler) (Assembler) (Assembler) This is an internal compiler error. The with flag is an attribute of a psect and indicates that this psect must be placed in the same memory page as the specified psect. DS52053B-page 439 . (783) "with" psects are cyclic (Assembler) If Psect A is to be placed “with” Psect B. (780) too many psects defined There are too many psects defined! Boy. and Psect B is to be placed “with” Psect A. for example. or comparing a variable with a value greater than the largest number it can represent. Remove a with flag from one of the psect declarations. for example: unsigned int a. The maximum number of open macros and include files is 30. (776) can’t allocate space for object "*" (offs: *) The assembler has run out of memory. (offs: *) The assembler has run out of memory. (785) too many temporary labels (Assembler) There are too many temporary labels in this assembler file.class=CODE. This. Contact Microchip Technical Support with details.  2012 Microchip Technology Inc. (784) overfreed (Assembler) This is an internal compiler error. may be the result of comparing an unsigned number with a negative value. The limit is 30 macros and include files nested at one time.with=basecode which will define a psect called my_text and place this in the same page as the psect basecode. Such an assembler declaration may look like: psect my_text. if(a == -10) /* if a is unsigned.local. (777) can’t allocate space for opnd structure within object "*". The assembler allows a maximum of 2000 temporary labels. (772) include files nested too deep (Assembler) (Assembler) Macro expansions and include file handling have filled up the assembler’s internal stack. (774) too many macro parameters There are too many macro parameters on this macro definition. Contact Microchip Technical Support with details. (782) REMSYM error (Assembler) This is an internal compiler error. how can it be -10? */ b = 9.

(788) invalid character "*" in number (Assembler) A number contained a character that was not part of the range 0-9 or 0-F. (802) invalid address after END directive (Assembler) The start address of the program which is specified after the assembler END directive must be a label in the current file. -2 copies of this code? */ r0. #a1 LOCAL a1 . Note that a temporary label must have a number >= 0. [r1]++ (Assembler) The argument to a REPT directive must be greater than zero. Contact Microchip Technical Support with details. (803) undefined temporary label (Assembler) A temporary label has been referenced that is not defined.MPLAB® XC8 C Compiler User’s Guide (787) can’t handle "v_rtype" of * in copyexpr (Assembler) This is an internal compiler error. DS52053B-page 440  2012 Microchip Technology Inc. Contact Microchip Technical Support with details. for example: (800) undefined symbol "*" (Assembler) The named symbol is not defined in this module. (794) invalid number syntax (Assembler) The syntax of a number is invalid. oops -. Note that angle brackets (“< >”) are used to quote macro arguments. the macro parameter cannot be used with local ENDM (799) REPT argument must be >= 0 REPT -2 MOVE ENDM . or other malformed numbers. (797) syntax error in LOCAL argument (Assembler) A symbol defined using the LOCAL assembler directive in an assembler macro is syntactically incorrect. and has not been specified GLOBAL. (790) end of file inside conditional (Assembler) END-of-FILE was encountered while scanning for an “endif” to match a previous “if”. (796) use of LOCAL outside macros is illegal (Assembler) The LOCAL directive is only legal inside macros. for example: mmm MACRO a1 MOVE r0. (798) macro argument may not appear after LOCAL (Assembler) The list of labels after the directive LOCAL may not include any of the formal parameters to the macro. It defines local labels that will be unique for each invocation of the macro. (793) unterminated macro argument (Assembler) An argument to a macro is not terminated. for example. . This. Ensure that all symbols and all other assembler identifiers conform with the assembly language of the target device. (801) range check too complex (Assembler) This is an internal compiler error. can be use of 8 or 9 in an octal number.

If you have not manually edited the chip info file. DS52053B-page 441 . (808) bad size in add_reloc() (Assembler) This is an internal compiler error. (815) syntax error in chipinfo file at line * The chipinfo file contains non-standard syntax at the specified line. (819) duplicate ZEROREG for "*" in chipinfo file at line * (Assembler) The chipinfo file has a device section with multiple ZEROREG values. Contact Microchip Technical Support with details. or via the LIST assembler directive. contact Microchip Technical Support with details. (816) duplicate ARCH specification in chipinfo file "*" at line * (Assembler. contact Microchip Technical Support with details. Driver) An chip architecture (family) that is unknown was encountered when reading the chip INI file. Only one BANKS value is allowed.  2012 Microchip Technology Inc. Only one ARCH value is allowed. Contact Microchip Technical Support with details. (817) unknown architecture in chipinfo file at line * (Assembler. (814) device type not defined (Assembler) The device must be defined either from the command line (eg. Only one ZEROREG value is allowed. This may be an internal compiler error. (820) duplicate SPAREBIT for "*" in chipinfo file at line * (Assembler) The chipinfo file has a device section with multiple SPAREBIT values. contact Microchip Technical Support with details. (809) unknown addressing mode (*) An unknown addressing mode was used in the assembly file. If you have not manually edited the chip info file. (821) duplicate INTSAVE for "*" in chipinfo file at line * (Assembler) The chipinfo file has a device section with multiple INTSAVE values. If you have not manually edited the chip info file. (806) attempted to get an undefined object (*) (Assembler) This is an internal compiler error. If you have not manually edited the chip info file. Only one SPAREBIT value is allowed. (811) "cnt" too large (*) in display() (Assembler) (Assembler) This is an internal compiler error. (807) attempted to set an undefined object (*) (Assembler) This is an internal compiler error.Error and Warning Messages (804) write error on object file (Assembler) The assembler failed to write to an object file. Contact Microchip Technical Support with details. If you have not manually edited the chip info file. Driver) (Assembler) The chipinfo file has a device section with multiple ARCH values. Only one INTSAVE value is allowed. Contact Microchip Technical Support with details. contact Microchip Technical Support with details. (818) duplicate BANKS for "*" in chipinfo file at line * (Assembler) The chipinfo file has a device section with multiple BANKS values. via the device assembler directive. Contact Microchip Technical Support with details. contact Microchip Technical Support with details. -16c84).

If you have not manually edited the chip info file. (823) duplicate START for "*" in chipinfo file at line * (Assembler) The chipinfo file has a device section with multiple START values. Only one START value is allowed. (827) too many COMMON lines in chipinfo file for "*" (Assembler) There are too many lines specifying common (access bank) memory in the chip configuration file. Contact Microchip Technical Support if you have not modified the chipinfo INI file. contact Microchip Technical Support with details. Any less will not allow a properly formatted listing to be produced. contact Microchip Technical Support with details. for example: LIST C=10 . The architecture of the device must be specified. (829) unrecognized line in chipinfo file at line * (Assembler) The chipinfo file contains a device section with an unrecognized line. (830) missing ARCH specification for "*" in chipinfo file (Assembler) The chipinfo file has a device section without an ARCH values. Driver) The second HEX number specified in the COMMON field in the chipinfo file must be greater in value than the first. Only one LIB value is allowed. (834) page width must be >= 60 (Assembler) (Assembler) The listing page width must be at least 60 characters. contact Microchip Technical Support with details. (824) duplicate LIB for "*" in chipinfo file at line * (Assembler) The chipinfo file has a device section with multiple LIB values. (826) inverted ram bank in chipinfo file at line * (Assembler. Contact Microchip Technical Support if the chipinfo file has not been modified. (828) inverted common bank in chipinfo file at line * (Assembler. (833) no valid entries in chipinfo file The chipinfo file contains no valid device descriptions. If you have not manually edited the chip info file. (832) empty chip info file "*" (Assembler) The chipinfo file contains no data. the page width will need to be wider than this DS52053B-page 442  2012 Microchip Technology Inc. If you have not manually edited the chip info file. Contact Microchip Technical Support if the INI has not been edited. If you have not manually edited the chip info file.MPLAB® XC8 C Compiler User’s Guide (822) duplicate ROMSIZE for "*" in chipinfo file at line * (Assembler) The chipinfo file has a device section with multiple ROMSIZE values. Only one ROMSIZE value is allowed. Driver) The second HEX number specified in the RAM field in the chipinfo file must be greater in value than the first. Reduce the number of values. contact Microchip Technical Support with details. . (825) too many RAMBANK lines in chipinfo file for "*" (Assembler) The chipinfo file contains a device section with too many RAMBANK fields.

oops -. (841) bad source/destination for movfp/movpf instruction (Assembler) The absolute address specified with the MOVFP/MOVPF instruction is too large. DS52053B-page 443 . This is probably due to bizarre use of macros or conditional assembly. (846) relocation error (Assembler) It is not possible to add together two relocatable quantities.choose a different name The linker will issue this warning if the symbol (C or assembler) was defined multiple times in different modules. (836) no file arguments (Assembler) The assembler has been invoked without any file arguments. The names of the modules are given in the error message. (847) operand error (Assembler) The operand to this opcode is invalid. r1 ENDM getval EQU 55h . #55 [r1]. and two relocatable addresses in the same psect may be subtracted. Setting this length to zero is allowed and turns off paging altogether. (839) relocation too complex (Assembler) The complex relocation in this expression is too big to be inserted into the object file. A constant may be added to a relocatable value. for example: _next: MOVE MOVE _next: r0. It cannot assemble anything. r0 .  2012 Microchip Technology Inc. For example: getval MACRO MOV r0. (840) phase error (Assembler) The assembler has calculated a different value for a symbol on two different passes. (843) a macro name can’t also be an EQU/SET symbol (Assembler) (Assembler) An EQU or SET symbol has been found with the same name as a macro. Note that C identifiers often have an underscore prepended to their name after compilation. (842) bad bit number A bit number must be an absolute expression in the range 0-7. The assembler will issue this error if a symbol is defined more than once in the same module. oops -. The default value is zero (pageless). This is not allowed. (845) symbol "*" defined more than once (Assembler) (Assembler) This symbol has been defined in more than one place. An absolute value must be used in various places where the assembler must know a value at assembly time.choose a different name to the macro (844) lexical error An unrecognized character or token has been seen in the input.Error and Warning Messages (835) form length must be >= 15 (Assembler) The form length specified using the -F length option must be at least 15 lines. Check your assembler reference manual for the proper form of operands for this instruction.

(851) illegal destination The destination (either .local. try: LIST C=80 (860) page width must be >= 49 (Assembler) The page width suboption to the LIST assembler directive must specify a width of at least 49. elsewhere: psect text.class=CODE . (855) ORG argument must be a positive constant (Assembler) An argument to the ORG assembler directive must be a positive constant or a symbol which has been equated to a positive constant. constant must be decimal and positive.16 (Assembler) (Assembler) The radix specified using the RADIX assembler directive must be in the range from 2 (binary) to 16 (hexadecimal). (859) argument to C option must specify a positive constant (Assembler) The parameter to the LIST assembler control’s C= option (which sets the column width of the listing output) must be a positive decimal constant number. (853) invalid size for FNSIZE directive (Assembler) The assembler FNSIZE assembler directive arguments must be positive constants. (852) radix must be from 2 .MPLAB® XC8 C Compiler User’s Guide (848) symbol has been declared EXTERN (Assembler) An assembly label uses the same name as a symbol that has already been declared as EXTERN. for example: LIST N=-3 .f or .class=CODE MOVE r2. r4 (Linker) The global flag is the default for a psect if its scope is not explicitly stated. for example: psect text. (850) PAGESEL not usable with this device (Assembler) (Assembler) The PAGESEL pseudo-instruction is not usable with the device selected. text is implicitly global MOVE r0.w ) is not correct for this instruction. . (857) psect may not be local and global A local psect may not have the same name as a global psect. (861) argument to N option must specify a positive constant (Assembler) The parameter to the LIST assembler control’s N option (which sets the page length for the listing output) must be a positive constant number. for example: ORG -10 /* this must a positive offset to the current psect */ (856) ALIGN argument must be a positive constant (Assembler) The align assembler directive requires a non-zero positive integer argument. (849) illegal instruction for this device The instruction is not supported by this device. r1 . page length must be positive DS52053B-page 444  2012 Microchip Technology Inc. for example: LIST C=a0h .

for example: PSECT text. (863) symbol can’t be both extern and public (Assembler) If the symbol is declared as extern.class=RAM. negative delta value doesn’t make (869) psect flag "delta" redefined (Assembler) The ’DELTA’ option of a psect has been redefined more than once in the same module.reloc=-4 . for example: psect test.space=-1 .Error and Warning Messages (862) symbol is not external (Assembler) A symbol has been declared as EXTRN but is also defined in the current module.size=-200 .class=RAM. (864) argument to "size" psect flag must specify a positive constant (Assembler) The parameter to the PSECT assembler directive’s size option must be a positive constant number. (870) argument to "pad" psect flag must specify a positive constant (Assembler) The parameter to the PSECT assembler directive’s ’PAD’ option must be a non-zero positive integer.class=CODE.class=CODE. space values start at zero  2012 Microchip Technology Inc.delta=-2 sense .size=500 (866) argument to "reloc" psect flag must specify a positive constant (Assembler) The parameter to the PSECT assembler directive’s reloc option must be a positive constant number. the reloc must be positive (867) psect flag "reloc" redefined (Assembler) The reloc flag to the PSECT assembler directive is different from a previous PSECT directive. a negative size? (865) psect flag "size" redefined (Assembler) The size flag to the PSECT assembler directive is different from a previous PSECT directive. (871) argument to "space" psect flag must specify a positive constant (Assembler) The parameter to the PSECT assembler directive’s space option must be a positive constant number.size=400 . for example: PSECT text. If it is declared as public. it is to be exported from the current module. for example: PSECT text. for example: psect spdata. It is not possible for a symbol to be both. elsewhere: psect spdata.reloc=4 .class=CODE. for example: psect spdata. elsewhere: psect spdata. DS52053B-page 445 .reloc=8 (868) argument to "delta" psect flag must specify a positive constant (Assembler) The parameter to the PSECT assembler directive’s DELTA option must be a positive constant number.class=CODE. it is to be imported.class=RAM.class=RAM.

class=CODE Look for other psect definitions that specify a different class name. (878) -S option used: "*" ignored (Driver) The indicated assembly file has been supplied to the driver in conjunction with the -S option. for example: psect spdata. A psect’s class is specified via a flag as in the following: psect text. Contact Microchip Technical Support with details. This could be caused a number of things.class=RAM. An assembler specific example: MOV r0. is syntactically correct for your host operating system and it exists.MPLAB® XC8 C Compiler User’s Guide (872) psect flag "space" redefined (Assembler) The space flag to the PSECT assembler directive is different from a previous PSECT directive. ’12’ specifies two characters (876) syntax error (Assembler) A syntax error has been detected. (Driver) (Driver) DS52053B-page 446  2012 Microchip Technology Inc. A psect’s with option is specified via a flag as in the following: psect bss. The driver really has nothing to do since the file is already an assembly file.space=0 . (874) a psect may only have one "with" option (Assembler) A psect can only be placed with one other psect.class=RAM. The psect was defined differently at this point than when it was defined elsewhere. Use "* –HELP" for help Improper command-line usage of the of the compiler’s driver. Ensure that the directory argument to this option is spelt correctly.space=1 (873) a psect may only be in one class (Assembler) You cannot assign a psect to more than one class. #’12’ . (883) setup failed (Driver) The compiler was not successfully setup using the --setup driver option. (880) invalid number of parameters. but was found to be greater than one character or none at all. (881) setup succeeded The compiler has been successfully setup using the --setup driver option. .with=data Look for other psect definitions that specify a different with psect name. (875) bad character constant in expression (Assembler) The character constant was expected to consist of only one character. elsewhere: psect spdata. (877) yacc stack overflow (Assembler) This is an internal compiler error.

xml if the directory ’/etc ’ is writable and there is no . The memory usage map file is generated by the driver when the driver option --summary=file is used. The driver will search the following configuration files in order: • the file specified by the environment variable XC_XML • the file /etc/xc. (895) can’t request and specify options in the one command (Driver) The usage of the driver options --getoption and --setoption is mutually exclusive. (890) contact Microchip to purchase and re-activate this compiler (Driver) (Driver) The evaluation period of this demo installation of the compiler has expired. c. p1. The HEX usage map file is generated by the driver when the driver option --summary=file is used. Ensure that the file is not open in another application. you sincerely believe the evaluation period has ended prematurely.xc. however.xc. contact Microchip technical support. Only files with the extensions as. (893) can’t open HEX usage map file "*": * (Driver) The driver was unable to open the indicated file. obj. You will need to purchase the compiler to re-activate it. (894) unknown source file type "*" (Driver) The extension of the indicated input file could not be determined. lib or HEX are identified by the driver.xml file in your home directory • the file . Ensure that the file is not open in another application. DS52053B-page 447 . usb. then the above error will occur. The psect usage map file is generated by the driver when the driver option --summary=file is used. If. (897) no memory ranges specified for program space (Driver) No on-chip or external memory ranges have been specified for the program space memory for the device specified. (891) can’t open psect usage map file "*": * (Driver) The driver was unable to open the indicated file.Error and Warning Messages (884) please ensure you have write permissions to the configuration file (Driver) The compiler was not successfully setup using the --setup driver option because the driver was unable to access the XML configuration file. (889) this * compiler has expired The demo period for this compiler has concluded. (896) no memory ranges specified for data space (Driver) No on-chip or external memory ranges have been specified for the data space memory for the device specified. Ensure that the file is not open in another application. (892) can’t open memory usage map file "*": * (Driver) The driver was unable to open the indicated file. Ensure that you have write permission to this file.  2012 Microchip Technology Inc.xml file in your home directory If none of the files can be located.

Parser. This issue and its solution are detailed in the section of this manual that specifically discusses this option. (918) *: no match (Preprocessor. (917) argument too long (Preprocessor. If you are using the --setoption option ensure that the name of the file is spelt correctly and that it exists. . Linker. Code Generator. (907) unknown memory space tag "*" in "*" option specification (Driver) A parameter to this memory option was a string but did not match any valid tags. Objtohex) The code generator could not allocate any more memory. Contact Microchip Technical Support with details. Refer to the section of this manual that describes this option to see what tags (if any) are valid for this device. Parser) This is an internal compiler error. Running the driver with the –CHIPINFO option will display a list of all chips that could be selected to build for. use "* –CHIPINFO" to see available chip names (Driver) The driver was invoked without selecting what chip to build for. (913) "*" option may cause compiler errors in some standard header files (Driver) Using this option will invalidate some of the qualifiers used in the standard header files. Parser) This is an internal compiler error. Other messages should have been reported by the subcomponent to explain the problem that was encountered. Assembler) (Driver) The chip configuration file was able to be opened but it was empty. resulting in errors. Try re-installing the compiler. Does the file exist? Try re-installing the compiler. (920) empty chipinfo file (Driver. (905) illegal application specified in "*" option (Driver) The application given to this option is not understood or does not belong to the compiler. DS52053B-page 448  2012 Microchip Technology Inc. (919) * in chipinfo file "*" at line * The specified parameter in the chip configuration file is illegal. (904) illegal format specified in "*" option (Driver) The usage of this option was incorrect. (908) exit status = * (Driver) One of the subcomponents being executed encountered a problem and returned an error code.MPLAB® XC8 C Compiler User’s Guide (899) can’t open option file "*" for application "*": * (Driver) An option file specified by a --getoption or --setoption driver option could not be opened. Confirm correct usage with –HELP or refer to the part of the manual that discusses this option. (902) no chip name specified. (900) exec failed: * (Driver) The subcomponent listed failed to execute. Contact Microchip Technical Support with details. (915) no room for arguments (Preprocessor. If you are using the --getoption option ensure that this file can be created at the given location or that it is not in use by any other application.

but the parameter did not conform to this syntax. expected to be found after ’@’ or ’<’ on the command line was not found. (925) extraneous argument to "*" option (Driver) This option does not accept additional data. (924) missing argument to "*" option (Driver) This option expects more data but none was given. This may just be a simple spelling error. If not. –HELP to look up what suboptions are permitted here. Check the usage of this option. but this suboption is not understood. (929) bad "*" option ranges (Driver) This option was expecting a parameter in a range format (start_of_range-end_of_range). (931) command file not specified (Driver) Command file to this application. (928) bad "*" option value (Driver.Error and Warning Messages (922) chip "*" not present in chipinfo file "*" (Driver) The chip selected does not appear in the compiler’s chip configuration file. Contact Microchip to see whether support for this device is available or it is necessary to upgrade the version of your compiler. The presence of any other characters will result in this error. If you are getting this message while building through a third party IDE. an Intel HEX file is expected to contain only ASCII representations of hexadecimal digits. Check the usage of this option. (942) unexpected character on line * of file "*" (Hexmate) File contains a character that was not valid for this type of file. Assembler) (Driver) The indicated option was expecting a valid hexadecimal integer argument. DS52053B-page 449 . colons (:) and line formatting. (939) no file arguments (Driver) The driver has been invoked with no input files listed on its command line.  2012 Microchip Technology Inc. perhaps the IDE could not verify the source files to compile or object files to link and withheld them from the command line. (923) unknown suboption "*" (Driver) This option can take suboptions. (926) duplicate "*" option This option can only appear once. For example. Run the driver with –HELP or refer to the driver’s chapter in this manual to verify the correct usage of this option. (941) bad "*" assignment. Follow the usage supplied by the message and ensure that the option has been formed correctly and completely. the file may be corrupt. USAGE: ** (Hexmate) (Objtohex) An option to HEXMATE was incorrectly used or incomplete. but appeared more than once. yet additional data was given. (930) bad "*" option specification (Driver) The parameters to this option were not specified correctly. (940) *-bit checksum * placed at * Presenting the result of the requested checksum calculation.

DS52053B-page 450  2012 Microchip Technology Inc. Ensure that the serial number can be stored in the number of bytes permissible by this option. (958) too many input files specified. (953) unknown -HELP sub-option: * (Hexmate) Invalid sub-option passed to -HELP. (963) checksum range includes voids or unspecified memory locations (Hexmate) Checksum range had gaps in data content. This can happen if the checksum result was to be stored within the address range of the checksum calculation. More than one source using the ’+’ specifier store data at the same address. (960) unexpected record type (*) on line * of "*" (Hexmate) Intel HEX file contained an invalid record type. (956) -SERIAL value must be between 1 and * bytes long (Hexmate) The serial number being stored was out of range. * file maximum (Hexmate) Too many file arguments have been used. Filling unused locations with a known value will correct this. (945) checksum range (*h to *h) contained an indeterminate value (Hexmate) The range for this checksum calculation contained a value that could not be resolved. The actual data stored there may not be what you expect. Check the parameters to the -CKSUM option. If the two named sources of conflict are the same source. (964) unpaired nibble in -FILL value will be truncated (Hexmate) The hexadecimal code given to the FILL option contained an incomplete byte. (949) start of checksum range must be less than end of range (Hexmate) The -CKSUM option has been given a range where the start is greater than the end. (951) start of fill range must be less than end of range (Hexmate) The -FILL option has been given a range where the start is greater than the end. use the ’+’ specifier.MPLAB® XC8 C Compiler User’s Guide (944) data conflict at address *h between * and * (Hexmate) Sources to Hexmate request differing data to be stored to the same address. The parameters may be incomplete or entered in the wrong order. (948) checksum result width must be between 1 and 4 bytes (Hexmate) The requested checksum byte size is illegal. (962) forced data conflict at address *h between * and * (Hexmate) Sources to HEXMATE force differing data to be stored to the same address. Check the spelling of the sub-option or use -HELP with no sub-option to list all options. Try merging these files in several stages rather than in one command. The incomplete byte (nibble) will be disregarded. The parameters may be incomplete or entered in the wrong order. Checksum results must be within 1 to 4 bytes wide. To force one data source to override the other. then the source may contain an error. The runtime calculated checksum is likely to differ from the compile-time checksum due to gaps/unused byes within the address range that the checksum is calculated over. Consult the Intel HEX format specification for valid record types. .

(970) character not valid at this point in format specifier The printf() style format specifier has an illegal character. (967) unused function definition "*" (from line *) (Parser) The indicated static function was never called in the module being compiled. TWO}. or the code that was meant to call it was excluded from compilation or misspelled the name of the function. (978) this identifier is already an enum tag (Parser) This identifier following a struct or union keyword is already the tag for an enumerated type. /* oops -. (969) end of string in format specifier The format specifier for the printf() style function is malformed. (976) field width not valid at this point (Parser) A field width may not appear at this point in a printf() type format specifier. struct IN { int a. (971) type modifiers not valid with this format Type modifiers may not be used with this format. b. and thus should only follow the keyword enum. DS52053B-page 451 . the function cannot be called from other modules so this warning implies the function is never used. option will be ignored This option currently is not available and will be ignored.Error and Warning Messages (965) -STRPACK option not yet implemented. Either the function is redundant. (975) invalid format specifier or type modifier (Parser) (Parser) (Parser) The format specifier or modifier in the printf-style string is illegal for this particular format. (968) unterminated string A string constant appears not to have a closing quote missing. Being static. (974) type modifier already specified This type modifier has already be specified in this type. }. (966) no END record for HEX file "*" (Hexmate) (Hexmate) Intel HEX file did not contain a record of type END.IN is already defined */  2012 Microchip Technology Inc. (972) only modifiers "h" and "l" valid with this format (Parser) (Parser) (Parser) (Parser) (Assembler) Only modifiers h (short ) and l (long ) are legal with this printf format specifier. The HEX file may be incomplete. for example: enum IN {ONE=1. (973) only modifier "l" valid with this format The only modifier that is legal with this format is l (for long).

(983) storage class redeclared (Parser) A variable previously declared as being static . Contact Microchip Technical Support with details.MPLAB® XC8 C Compiler User’s Guide (979) this identifier is already a struct tag (Parser) This identifier following a union or enum keyword is already the tag for a structure. /* oops -. for example: struct IN { int a. . char a. for example: int a. (986) enum member redeclared (Parser) (Parser) A member of an enumeration is defined twice or more with differing values. enum IN {ONE=1. has now be redeclared as extern. for example: union IN { int a. }.what is the correct type? */ (985) qualifiers redeclared This function or variable has different qualifiers in different declarations. and thus should only follow the keyword struct. enum IN {ONE=1. DS52053B-page 452  2012 Microchip Technology Inc. (984) type redeclared (Parser) The type of this function or object has been redeclared. }.IN is already defined */ (981) pointer required A pointer is required here. This can occur because of two incompatible declarations. /* oops -. /* oops -. TWO}. not a pointer to a structure */ (Parser) (982) unknown op "*" in nxtuse() (Assembler) This is an internal compiler error. /* data is a structure. or because an implicit declaration is followed by an incompatible declaration. Does the member appear twice in the same list or does the name of the member appear in more than one enum list? (987) arguments redeclared (Parser) The data types of the parameters passed to this function do not match its prototype. (988) number of arguments redeclared (Parser) The number of arguments in this function declaration does not agree with a previous declaration of the same function. b. and thus should only follow the keyword union. TWO}.IN is already defined */ (980) this identifier is already a union tag (Parser) This identifier following a struct or enum keyword is already the tag for a union. b. for example: struct DATA data. data->a = 9.

This would mean code from this module would have to be placed before the beginning of the file! Check for missing psect directives in assembler files. about_three = 3. (990) modulus by zero in #if. the compilation speed will be slower. /* no non-int values allowed */ (992) can’t find op (Assembler) This is an internal compiler error. values may be assigned to the members. the compilation speed will be slower. (995) some command-line options are disabled. (994) some command-line options are disabled and compilation is delayed (Driver) The compiler is operating in demo mode. Some command-line options are disabled. DS52053B-page 453 .  2012 Microchip Technology Inc. for example: #define ZERO 0 #if FOO%ZERO /* this will have an assumed result of 0 */ #define INTERESTING #endif (991) integer expression required (Parser) In an enum declaration. but the -C option has been used to specify that a binary output file is to be created that is mapped to this address. (993) some command-line options are disabled (Driver) The compiler is operating in demo mode. compilation is delayed (Driver) The compiler is operating in demo mode. code size is limited to 16kB. zero result assumed (Preprocessor) A modulus operation in a #if expression has a zero divisor. and the maximum allowed code size is limited to 16 KB. two. Some command-line options are disabled.Error and Warning Messages (989) module has code below file base of *h (Linker) This module has code below the address given.12}. Contact Microchip Technical Support with details. Some command-line options are disabled. for example: enum {one = 1. The result has been assumed to be zero. but the expression must evaluate to a constant of type int.

(1024) syntax error in chipinfo file "*" at line * The chip configuration file contains a syntax error at the line specified.error code (*) The compiler did not activated successfully. take care and refer to the comments at the beginning of this file for a description on what type of values are expected here. (1028) activation was not successful . but. (1026) missing architecture in chipinfo file "*" at line * (Assembler) The chipinfo file has a device section without an ARCH values. If you are modifying this file yourself. . (Driver) (Driver) DS52053B-page 454  2012 Microchip Technology Inc. it did not appear for this chip. take care and refer to the comments at the beginning of this file for a description on what type of values are expected here. (1025) unknown architecture in chipinfo file "*" at line * (Driver) (Driver) The attribute at the line indicated defines an architecture that is unknown to this compiler. Contact Microchip Technical Support if the chipinfo file has not been modified. (1019) duplicate "