MPLAB® XC8 C Compiler User’s Guide for PIC® MCU 2012-2018 Microchip Technology Inc. DS50002737A 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 Trademarks applications and the like is provided only for your convenience The Microchip name and logo, the Microchip logo, AnyRate, AVR, and may be superseded by updates. It is your responsibility to AVR logo, AVR Freaks, BeaconThings, BitCloud, CryptoMemory, ensure that your application meets with your specifications. CryptoRF, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KEELOQ, MICROCHIP MAKES NO REPRESENTATIONS OR KEELOQ logo, Kleer, LANCheck, LINK MD, maXStylus, WARRANTIES OF ANY KIND WHETHER EXPRESS OR maXTouch, MediaLB, megaAVR, MOST, MOST logo, MPLAB, IMPLIED, WRITTEN OR ORAL, STATUTORY OR OptoLyzer, PIC, picoPower, PICSTART, PIC32 logo, Prochip OTHERWISE, RELATED TO THE INFORMATION, Designer, QTouch, RightTouch, SAM-BA, SpyNIC, SST, SST INCLUDING BUT NOT LIMITED TO ITS CONDITION, Logo, SuperFlash, tinyAVR, UNI/O, and XMEGA are registered QUALITY, PERFORMANCE, MERCHANTABILITY OR trademarks of Microchip Technology Incorporated in the U.S.A. FITNESS FOR PURPOSE. Microchip disclaims all liability and other countries. arising from this information and its use. Use of Microchip ClockWorks, The Embedded Control Solutions Company, devices in life support and/or safety applications is entirely at EtherSynch, Hyper Speed Control, HyperLight Load, IntelliMOS, the buyer’s risk, and the buyer agrees to defend, indemnify and mTouch, Precision Edge, and Quiet-Wire are registered hold harmless Microchip from any and all damages, claims, trademarks of Microchip Technology Incorporated in the U.S.A. suits, or expenses resulting from such use. No licenses are Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any conveyed, implicitly or otherwise, under any Microchip Capacitor, AnyIn, AnyOut, BodyCom, chipKIT, chipKIT logo, intellectual property rights unless otherwise stated. CodeGuard, CryptoAuthentication, CryptoCompanion, CryptoController, dsPICDEM, dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, Mindi, MiWi, motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, PureSilicon, QMatrix, RightTouch logo, REAL ICE, Ripple Blocker, SAM-ICE, Serial Quad I/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, 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 Microchip received ISO/TS-16949:2009 certification for its worldwide the U.S.A. headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California Silicon Storage Technology is a registered trademark of Microchip and India. The Company’s quality system processes and procedures Technology Inc. in other countries. are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and GestIC is a registered trademark of Microchip Technology analog products. In addition, Microchip’s quality system for the design Germany II GmbH & Co. KG, a subsidiary of Microchip Technology and manufacture of development systems is ISO 9001:2000 certified. Inc., in other countries. All other trademarks mentioned herein are property of their QUALITY MANAGEMENT SYSTEM respective companies. © 2012-2018, Microchip Technology Incorporated, All Rights CERTIFIED BY DNV Reserved. ISBN: 978-1-5224-2815-2 == ISO/TS 16949 == DS50002737A-page 2 2012-2018 Microchip Technology Inc. MPLAB® XC8 C COMPILER USER’S GUIDE FOR PIC Table of Contents Preface ........................................................................................................................... 5 Chapter 1. Compiler Overview 1.1 Introduction ................................................................................................... 11 1.2 Compiler Description and Documentation .................................................... 11 1.3 Device Description ....................................................................................... 12 Chapter 2. How To’s 2.1 Introduction ................................................................................................... 13 2.2 Installing and Activating the Compiler .......................................................... 13 2.3 Invoking the Compiler ................................................................................... 15 2.4 Writing Source Code .................................................................................... 17 2.5 Getting My Application to Do What I Want ................................................... 28 2.6 Understanding the Compilation Process ...................................................... 33 2.7 Fixing Code That Does Not Work ................................................................. 41 Chapter 3. XC8-CC Command-line Driver 3.1 Introduction ................................................................................................... 45 3.2 Invoking the Compiler ................................................................................... 46 3.3 The Compilation Sequence .......................................................................... 48 3.4 Runtime Files ............................................................................................... 51 3.5 Compiler Output ........................................................................................... 52 3.6 Compiler Messages ...................................................................................... 53 3.7 Option Descriptions ...................................................................................... 56 Chapter 4. C Language Features 4.1 Introduction ................................................................................................... 83 4.2 C Standard Compliance ............................................................................... 83 4.3 Device-Related Features .............................................................................. 86 4.4 Supported Data Types and Variables .......................................................... 95 4.5 Memory Allocation and Access .................................................................. 112 4.6 Operators and Statements ......................................................................... 120 4.7 Register Usage ........................................................................................... 122 4.8 Functions .................................................................................................... 123 4.9 Interrupts .................................................................................................... 131 4.10 Main, Runtime Startup and Reset ............................................................ 142 4.11 Libraries .................................................................................................... 146 4.12 Mixing C and Assembly Code .................................................................. 148 4.13 Optimizations ............................................................................................ 157 4.14 Preprocessing .......................................................................................... 159 4.15 Linking Programs ..................................................................................... 170 2012-2018 Microchip Technology Inc. DS50002737A-page 3 MPLAB® XC8 C Compiler User’s Guide for PIC Chapter 5. Macro Assembler 5.1 Introduction ................................................................................................. 179 5.2 MPLAB XC8 Assembly Language .............................................................. 180 5.3 Assembly-Level Optimizations ................................................................... 206 5.4 Assembly List Files ....................................................................................