Contents

Notice to Customers 1. Preface 1.1. Conventions Used in This Guide 1.2. Recommended Reading 2. Compiler Overview 2.1. Device Description 2.2. Compiler Description and Documentation 2.2.1. Conventions 2.2.2. ANSI C Standards 2.2.3. Optimization 2.2.4. ANSI Standard Library Support 2.2.5. ISO/IEC C++ Standard 2.2.6. Compiler Driver 2.2.7. Documentation 2.3. Compiler and Other Development Tools 3. Common C Interface 3.1. Background - The Desire for Portable Code 3.1.1. The ANSI Standard 3.1.2. The Common C Interface 3.2. Using the CCI 3.3. ANSI Standard Refinement 3.3.1. Source File Encoding 3.3.2. The Prototype for main 3.3.3. Header File Specification 3.3.4. Include Search Paths 3.3.5. The Number of Significant Initial Characters in an Identifier 3.3.6. Sizes of Types 3.3.7. Plain char Types 3.3.8. Signed Integer Representation 3.3.9. Integer Conversion 3.3.10. Bitwise Operations on Signed Values 3.3.11. Right-Shifting Signed Values 3.3.12. Conversion of Union Member Accessed Using Member with Different Type 3.3.13. Default Bit-field int Type 3.3.14. Bit-Fields Straddling a Storage Unit Boundary 3.3.15. The Allocation Order of Bit-Field 3.3.16. The NULL Macro 3.3.17. Floating-Point Sizes 3.4. ANSI Standard Extensions 3.4.1. Generic Header File 3.4.2. Absolute Addressing 3.4.3. Far Objects and Functions 3.4.4. Near Objects 3.4.5. Persistent Objects 3.4.6. X and Y Data Objects 3.4.7. Banked Data Objects 3.4.8. Alignment of Objects 3.4.9. EEPROM Objects 3.4.10. Interrupt Functions 3.4.11. Packing Objects 3.4.12. Indicating Antiquated Objects 3.4.13. Assigning Objects to Sections 3.4.14. Specifying Configuration Bits 3.4.15. Manifest Macros 3.4.16. In-Line Assembly 3.5. Compiler Features 3.5.1. Enabling the CCI 4. How To's 4.1. Installing and Activating the Compiler 4.1.1. How Do I Install and Activate My Compiler? 4.1.2. How Can I Tell if the Compiler has Activated Successfully? 4.1.3. Can I Install More Than One Version of the Same Compiler? 4.2. Invoking the Compiler 4.2.1. How Do I Compile from Within MPLAB X IDE? 4.2.2. How Do I Compile on the Command-Line? 4.2.3. How Do I Compile Using a Make Utility? 4.2.4. How Can I Select Which Compiler I Want to Build With? 4.2.5. How Can I Change the Compiler's Operating Mode? 4.2.6. How Do I Build Libraries? 4.2.7. How Do I Know What Compiler Options Are Available and What They Do? 4.2.8. How Do I Know What the Build Options in MPLAB X IDE Do? 4.2.9. What is Different About an MPLAB X IDE Debug Build? 4.3. Writing Source Code 4.3.1. C Language Specifics 4.3.1.1. When Should I Cast Expressions? 4.3.1.2. Can Implicit Type Conversions Change The Expected Results Of My Expressions? 4.3.1.3. How Do I Enter Non-English Characters Into My Program? 4.3.1.4. How Can I Use A Variable Defined In Another Source File? 4.3.1.5. How Do I Port My Code To Different Device Architectures? 4.3.2. Device-Specific Features 4.3.2.1. How Do I Set the Configuration Bits? 4.3.2.2. How Do I Determine the Cause of Reset? 4.3.2.3. How Do I Access SFRS? 4.3.2.4. How Do I Find The Names Used To Represent SFRs And Bits? 4.3.3. Memory Allocation 4.3.3.1. How Do I Position Variables at an Address I Nominate? 4.3.3.2. How Do I Position Functions at an Address I Nominate? 4.3.3.3. How Do I Place Variables in Program Memory? 4.3.3.4. How Do I Stop the Compiler From Using Certain Memory Locations? 4.3.4. Variables 4.3.4.1. Why Are My Floating-point Results Not Quite What I Am Expecting? 4.3.4.2. How Can I Access Individual Bits of a Variable? 4.3.4.3. How Long Can I Make My Variable and Macro Names? 4.3.5. Functions 4.3.5.1. What Is the Optimum Size for Functions? 4.3.5.2. How Do I Stop An Unused Function Being Removed? 4.3.5.3. How Do I Make a Function Inline? 4.3.6. Interrupts 4.3.6.1. How Do I Use Interrupts in C? 4.3.7. Assembly Code 4.3.7.1. How Should I Combine Assembly and C Code? 4.3.7.2. What Do I Need Other Than Instructions in an Assembly Source File? 4.3.7.3. How Do I Access C Objects from Assembly Code? 4.3.7.4. How Can I Access SFRs From Within Assembly Code? 4.3.7.5. What Things Must I Manage When Writing Assembly Code? 4.4. Getting My Application To Do What I Want 4.4.1. What Can Cause Glitches on Output Ports? 4.4.2. How Do I Link Bootloaders and Downloadable Applications? 4.4.3. What Do I Need to Do When Compiling to Use a Debugger? 4.4.4. How Do I Share Data Between Interrupt and Main-line Code? 4.4.5. How Can I Prevent Misuse of My Code? 4.4.6. How Do I Use Printf to Send Text to a Peripheral? 4.4.7. How Can I Implement a Delay in My Code? 4.4.8. How Can I Rotate a Variable? 4.5. Understanding the Compilation Process 4.5.1. What's the Difference Between the Free and PRO Modes? 4.5.2. How Can I Make My Code Smaller? 4.5.3. How Can I Reduce RAM Usage? 4.5.4. How Can I Make My Code Faster? 4.5.5. How Does the Compiler Place Everything in Memory? 4.5.6. How Can I Make My Interrupt Routine Faster? 4.5.7. How Big Can C Variables Be? 4.5.8. What Optimizations Will Be Applied to My Code? 4.5.9. What Devices are Supported by the Compiler? 4.5.10. How Do I Know What Code the Compiler Is Producing? 4.5.11. How Can I Tell How Big a Function Is? 4.5.12. How Do I Know What Resources Are Being Used by Each Function? 4.5.13. How Do I Find Out Where Variables and Functions Have Been Positioned? 4.5.14. Why Are Some Objects Positioned Into Memory That I Reserved? 4.5.15. How Do I Know How Much Memory Is Still Available? 4.5.16. How Do I Use Library Files in My Project? 4.5.17. How Do I Customize the C Runtime Startup Code? 4.5.18. What Optimizations Are Employed by the Compiler? 4.5.19. Why Do I Get Out-of-Memory Errors When I Select a Debugger? 4.5.20. How Do I Stop My Project's Checksum From Changing? 4.6. Fixing Code That Does Not Work 4.6.1. How Do I Set Up Warning/Error Messages? 4.6.2. How Do I Find the Code that Caused Compiler Errors or Warnings in My Program? 4.6.3. How Can I Stop Spurious Warnings From Being Produced? 4.6.4. Why Can’t I Even Blink an LED? 4.6.5. What Can Cause Corrupted Variables and Code Failure When Using Interrupts? 5. XC32 Toolchain and MPLAB X IDE 5.1. MPLAB X IDE and Tools Installation 5.2. MPLAB X IDE Setup 5.3. MPLAB X IDE Projects 5.4. Project Setup 5.4.1. XC32 (Global Options) 5.4.2. xc32-as (32-bit Assembler) 5.4.3. xc32-gcc (32-bit C Compiler) 5.4.4. xc32-g++ (32-bit C++ Compiler) 5.4.5. xc32-ld (32-Bit Linker) 5.4.6. Options Page Features 5.5. Project Example 5.5.1. Run the Project Wizard 5.5.2. Set Build Options 5.5.3. Build the Project 5.5.4. Output Files 5.5.5. Further Development 6. Command-line Driver 6.1. Invoking The Compiler 6.1.1. Driver Command-line Format 6.1.2. Environment Variables 6.1.3. Input File Types 6.2. The C Compilation Sequence 6.2.1. Single-Step C Compilation 6.2.1.1. Compiling a Single C File 6.2.1.2. Compiling Multiple C Files 6.2.2. Multi-Step C Compilation 6.3. The C++ Compilation Sequences 6.3.1. Single-step C++ Compilation 6.3.1.1. Compiling a Single C++ File 6.3.2. Compiling Multiple C and C++ Files 6.4. Runtime Files 6.4.1. Location and Naming Convention 6.4.2. Library Files 6.4.2.1. Standard Libraries 6.4.2.2. User-Defined Libraries 6.4.3. Peripheral Library Functions 6.4.4. Runtime Startup Code Location 6.4.5. Startup and Initialization 6.5. Compiler Output 6.5.1. Output Files 6.5.2. Diagnostic Files 6.6. Compiler Messages 6.7. Driver Option Descriptions 6.7.1. Options Specific to PIC32M Devices 6.7.2. Options for Controlling the Kind of Output 6.7.3. Options for Controlling the C Dialect 6.7.4. Options for Controlling the C++ Dialect 6.7.5. Options for Controlling Warning and Errors 6.7.6. Options for Debugging 6.7.7. Options for Controlling Optimization 6.7.8. Options for Controlling the Preprocessor 6.7.9. Options for Assembling 6.7.10. Options for Linking 6.7.11. Options for Directory Search 6.7.12. Options for Code Generation Conventions 7. ANSI C Standard Issues 7.1. Divergence Fom the ANSI C Standard 7.2. Extensions to the ANSI C Standard 7.2.1. Keyword Differences 7.2.2. Statement Differences 7.2.3. Expression Differences 7.3. Implementation-Defined Behavior 8. Device-Related Features 8.1. Device Support 8.2. Device Header Files 8.2.1. CP0 Register Definitions Header File 8.3. Stack 8.4. Configuration Bit Access 8.4.1. Syntax 8.4.2. Example 8.5. ID Locations 8.6. Using SFRs From C Code 8.6.1. CP0 Register Definitions 8.6.2. CP0 Register Field Definitions 8.6.3. CP0 Access Macros 8.6.4. Address Translation Macros 9. Supported Data Types and Variables 9.1. Identifiers 9.2. Data Representation 9.3. Integer Data Types 9.3.1. Signed and Unsigned Character Types 9.3.2. limits.h 9.4. Floating-Point Data Types 9.5. Structures and Unions 9.5.1. Structure and Union Qualifiers 9.5.2. Bit Fields in Structures 9.6. Pointer Types 9.6.1. Combining Type Qualifiers and Pointers 9.6.2. Data Pointers 9.6.3. Function Pointers 9.6.4. Special Pointer Targets 9.7. Complex Data Types 9.8. Constant Types and Formats 9.9. Standard Type Qualifiers 9.9.1. Const Type Qualifier 9.9.2. Volatile Type Qualifier 9.10. Compiler-Specific Qualifiers 9.11. Variable Attributes 10. Memory Allocation and Access 10.1. Address Spaces 10.2. Variables in Data Memory 10.2.1. Non-Auto Variable Allocation 10.2.2. Static Variables 10.2.3. Non-Auto Variable Size Limits 10.2.4. Changing the Default Non-Auto Variable Allocation 10.2.5. Data Memory Allocation Macros 10.3. Auto Variable Allocation and Access 10.4. Variables in Program Memory 10.4.1. Size Limitations of const Variables 10.4.2. Changing the Default Allocation 10.5. Variable in Registers 10.6. Application-Defined Memory Regions 10.6.1. Advantages of an Application-Defined Memory Region 10.6.2. Advantages of a Linker Script-Defined Memory Region 10.6.3. Using an Application-Defined Memory Region 10.7. Dynamic Memory Allocation 10.8. Memory Models 11. Fixed-Point Arithmetic Support 11.1. Enabling Fixed-Point Arithmetic Support 11.2. Data Types 11.3. External Definitions 11.4. SIMD Variables 11.5. Accessing Elements in SIMD Variables 11.6. Array Alignment and Data Layout 11.7. C Operators 11.7.1. Operations on Fixed-Point Variables 11.8. Operations on SIMD Variables 11.9. DSP Built-In Functions 11.10. DSP Control Register 11.11. Using Accumulators 11.12. Mixed-Mode Operations 11.12.1. Multiply "32-bit int * 32-bit int = 64-bit long long int" 11.12.2. Multiply and Add "32-bit int * 32-bit int + 64-bit long long = 64-bit long long int" 11.13. Auto-Vectorization to SIMD 11.14. FIR Filter Example Project 12. Operators and Statements 12.1. Integral Promotion 12.2. Type References 12.3. Labels as Values 12.4. Conditional Operator Operands 12.5. Case Ranges 13. Register Usage 13.1. Register Usage 13.2. Register Conventions 14. Functions 14.1. Writing Functions 14.2. Function Attributes and Specifiers 14.2.1. Function Attributes 14.3. Allocation of Function Code 14.4. Changing the Default Function Allocation 14.5. Function Size Limits 14.6. Function Parameters 14.7. Function Return Values 14.8. Calling Functions 14.9. Inline Functions 15. Interrupts 15.1. Interrupt Operation 15.2. Writing an Interrupt Service Routine 15.2.1. Interrupt Attribute 15.2.2. Interrupt Pragma 15.2.3. __ISR Macros 15.3. Associating a Handler Function with an Exception Vector 15.3.1. Vector Attribute 15.3.2. Interrupt-Pragma Vector Clause 15.3.3. Vector Pragma 15.4. Exception Handlers 15.4.1. Bootstrap Exception 15.4.2. General Exception 15.4.3. Simple TLB Refill Exception 15.4.4. Cache Error Exception 15.5. Interrupt Service Routine Context Switching 15.5.1. Context Restoration 15.6. Latency 15.7. Nesting Interrupts 15.8. Enabling/Disabling Interrupts 15.9. ISR Considerations 16. Main, Runtime Start-up and Reset 16.1. The Main Function 16.2. Runtime Start-Up Code 16.2.1. Switch to the Selected Instruction Set (ISA) Mode 16.2.2. Jump to NMI Handler (_nmi_handler) if an NMI Occurred 16.2.3. Initialize Stack Pointer and Heap 16.2.4. Initialize Global Pointer 16.2.5. Initialize of Clear Variable and RAM Functions Using the Data-Initialization Template 16.2.6. Initialize Bus Matrix Registers 16.2.7. Call "On Bootstrap" Procedure 16.2.8. Change Location of Exception Vectors 16.2.9. Call the C++ Initialization Code 16.2.10. Call Main 16.2.11. Symbols Required by Start-Up Code and C/C++ Library 16.2.12. Exceptions 16.3. The On Reset Routine 16.3.1. Clearing Objects 17. Library Routines 17.1. Using Library Routines 18. Mixing C/C++ and Assembly Language 18.1. Mixing Assembly Language and C Variables and Functions 18.2. Using Inline Assembly Language 18.2.1. Inline Examples 18.2.2. Equivalent Assembly Symbols 18.3. Predefined Macros 19. Optimizations 20. Preprocessing 20.1. C/C++ Language Comments 20.2. Preprocessor Directives 20.3. Pragma Directives 20.4. Predefined Macros 20.4.1. 32-Bit C/C++ Compiler Macros 20.4.2. SDE Compatibility Macros 20.4.3. Processor-Specific Macros 21. Linking Programs 21.1. Replacing Library Symbols 21.2. Linker-Defined Symbols 21.3. Default Linker Script 21.3.1. Output Format and Entry Points 21.3.2. Default Values for Minimum Stack and Heap Sizes 21.3.3. Processor Definitions Include File for PIC32MX Family 21.3.3.1. Inclusion of Processor-Specific Object File(s) 21.3.3.2. Optional Inclusion of Processor-Specific Peripheral Libraries 21.3.3.3. Base Exception Vector Address and Vector Spacing Symbols 21.3.3.4. Memory Address Equates 21.3.3.5. Memory Regions 21.3.3.6. Configuration Words Input/Output Section Map 21.3.4. Input/Output Section Map 21.3.4.1. .Config_<Address> Sections 21.3.4.2. .Reset Section 21.3.4.3. .bev_excpt Section 21.3.4.4. .dbg_excpt Section 21.3.4.5. .dbg_code Section 21.3.4.6. .app_excpt Section 21.3.4.7. .vector_0 .. .vector_63 Sections (PIC32MX Interrupt Vector Tables) 21.3.4.8. .vectors Section 21.3.4.9. .text Section 21.3.4.10. C++ Initilization Sections 21.3.4.11. .rodata Section 21.3.4.12. .sdata2 Section 21.3.4.13. .sbss2 Section 21.3.4.14. .dbg_data Section 21.3.4.15. .data Section 21.3.4.16. .got Section 21.3.4.17. .sdata Section 21.3.4.18. .lit8 Section 21.3.4.19. .lit4 Section 21.3.4.20. .sbss Section 21.3.4.21. .bss Section 21.3.4.22. .heap Section 21.3.4.23. .stack Section 21.3.4.24. .ramfunc Section 21.3.4.25. Stack Location 21.3.4.26. Debug Sections 21.3.4.27. Variables Allocated to L1 Cached Memory 21.3.4.28. .tlb_init_values Section 22. Embedded Compiler Compatibility Mode 22.1. Compiling in Compatibility Mode 22.2. Syntax Compatibility 22.3. Data Type 22.4. Operator 22.5. Extended Keywords 22.6. Intrinsic Functions 22.7. Pragmas 23. Implementation-Defined Behavior 23.1. Overview 23.2. Translation 23.3. Environment 23.4. Identifiers 23.5. Characters 23.6. Integers 23.7. Floating-Point 23.8. Arrays and Pointers 23.9. Hints 23.10. Structures, Unions, Enumerations, and Bit Fields 23.11. Qualifiers 23.12. Declarators 23.13. Statements 23.14. Pre-Processing Directives 23.15. Library Functions 23.16. Architecture 24. Deprecated Features 24.1. Variables in Specified Registers 24.2. Defining Global Register Variables 24.3. Specifying Registers for Local Variables 25. Built-In Functions 26. Built-In Function Descriptions 26.1. __builtin_bcc0(rn,sel,clr) 26.2. __builtin_bsc0(rn,sel,set) 26.3. __builtin_bcsc0(rn,sel,clr,set) 26.4. __builtin_clz(x) 26.5. __builtin_ctz(x) 26.6. __builtin_mips_cache(op,addr) 26.7. __builtin_mxc0(rn,sel,val) 26.8. __builtin_set_isr_state(unsigned int) 26.9. __builtin_software_breakpoint(void) 26.10. unsigned long__builtin_section_begin(quoted-section-name) 26.11. unsigned long __builtin_section_end(quoted-section-name) 26.12. unsigned long __builtin_section_size(quoted-section-name) 26.13. unsigned int __builtin_get_isr_state(void) 27. Built-In DSP Functions 28. ASCII Character Set 29. Document Revision History The Microchip Website Product Change Notification Service Customer Support Microchip Devices Code Protection Feature Legal Notice Trademarks Quality Management System Worldwide Sales and Service