Microchip Technology SW006022-2N User Manuals

Table of Contents

• Table of Contents

  3
• Preface

  11
  • Introduction

    11
  • Document Layout

    12
  • Conventions Used

    13
  • Recommended Reading

    14
  • myMicrochip Personalized Notification Service

    15
  • The Microchip Web Site

    15
  • Microchip Forums

    16
  • Customer Support

    16
  • Document Revision History

    16
• Chapter 1. Compiler Overview

  17
  • 1.1 Introduction

    17
  • 1.2 Device Description

    17
  • 1.3 Compiler Description and Documentation

    17
    • 1.3.1 ANSI C Standard

      17
    • 1.3.2 Optimization

      17
    • 1.3.3 ANSI Standard Library Support

      18
    • 1.3.4 Flexible Memory Models

      18
    • 1.3.5 Attributes and Qualifiers

      18
    • 1.3.6 Compiler Driver

      18
    • 1.3.7 Documentation

      18
  • 1.4 Compiler and Other Development Tools

    19
• Chapter 2. Common C Interface

  21
  • 2.1 Introduction

    21
  • 2.2 Background – The Desire for Portable Code

    21
    • 2.2.1 The ANSI Standard

      22
    • 2.2.2 The Common C Interface

      23
  • 2.3 Using the CCI

    24
  • 2.4 ANSI Standard Refinement

    25
    • 2.4.1 Source File Encoding

      25
      • 2.4.1.1 Example

        25
      • 2.4.1.2 Differences

        25
      • 2.4.1.3 Migration to the CCI

        25
    • 2.4.2 The Prototype for main

      25
      • 2.4.2.1 Example

        25
      • 2.4.2.2 Differences

        25
      • 2.4.2.3 Migration to the CCI

        25
    • 2.4.3 Header File Specification

      25
      • 2.4.3.1 Example

        25
      • 2.4.3.2 Differences

        26
      • 2.4.3.3 Migration to the CCI

        26
    • 2.4.4 Include Search Paths

      26
      • 2.4.4.1 Example

        26
      • 2.4.4.2 Differences

        26
      • 2.4.4.3 Migration to the CCI

        26
    • 2.4.5 The number of Significant Initial Characters in an Identifier

      27
      • 2.4.5.1 Example

        27
      • 2.4.5.2 Differences

        27
      • 2.4.5.3 Migration to the CCI

        27
    • 2.4.6 Sizes of Types

      27
      • 2.4.6.1 Example

        27
      • 2.4.6.2 Differences

        27
      • 2.4.6.3 Migration to the CCI

        27
    • 2.4.7 Plain char Types

      28
      • 2.4.7.1 Example

        28
      • 2.4.7.2 Differences

        28
      • 2.4.7.3 Migration to the CCI

        28
    • 2.4.8 Signed Integer Representation

      28
      • 2.4.8.1 Example

        28
      • 2.4.8.2 Differences

        28
      • 2.4.8.3 Migration to the CCI

        28
    • 2.4.9 Integer conversion

      29
      • 2.4.9.1 Example

        29
      • 2.4.9.2 Differences

        29
      • 2.4.9.3 Migration to the CCI

        29
    • 2.4.10 Bit-wise Operations on Signed Values

      29
      • 2.4.10.1 Example

        29
      • 2.4.10.2 Differences

        29
      • 2.4.10.3 Migration to the CCI

        29
    • 2.4.11 Right-shifting Signed Values

      29
      • 2.4.11.1 Example

        29
      • 2.4.11.2 Differences

        30
      • 2.4.11.3 Migration to the CCI

        30
    • 2.4.12 Conversion of Union Member Accessed Using Member With Different Type

      30
      • 2.4.12.1 Example

        30
      • 2.4.12.2 Differences

        30
      • 2.4.12.3 Migration to the CCI

        30
    • 2.4.13 Default Bit-field int Type

      30
      • 2.4.13.1 Example

        30
      • 2.4.13.2 Differences

        31
      • 2.4.13.3 Migration to the CCI

        31
    • 2.4.14 Bit-fields Straddling a Storage Unit Boundary

      31
      • 2.4.14.1 Example

        31
      • 2.4.14.2 Differences

        31
      • 2.4.14.3 Migration to the CCI

        31
    • 2.4.15 The Allocation Order of Bits-field

      31
      • 2.4.15.1 Example

        32
      • 2.4.15.2 Differences

        32
      • 2.4.15.3 Migration to the CCI

        32
    • 2.4.16 The NULL macro

      32
      • 2.4.16.1 Example

        32
      • 2.4.16.2 Differences

        32
      • 2.4.16.3 Migration to the CCI

        32
    • 2.4.17 Floating-point sizes

      32
      • 2.4.17.1 Example

        32
      • 2.4.17.2 Differences

        32
      • 2.4.17.3 Migration to the CCI

        32
  • 2.5 ANSI Standard Extensions

    33
    • 2.5.1 Generic Header File

      33
      • 2.5.1.1 Example

        33
      • 2.5.1.2 Differences

        33
      • 2.5.1.3 Migration to the CCI

        33
    • 2.5.2 Absolute addressing

      33
      • 2.5.2.1 Example

        33
      • 2.5.2.2 Differences

        33
      • 2.5.2.3 Migration to the CCI

        34
      • 2.5.2.4 Caveats

        34
    • 2.5.3 Far Objects and Functions

      34
      • 2.5.3.1 Example

        34
      • 2.5.3.2 Differences

        34
      • 2.5.3.3 Migration to the CCI

        35
      • 2.5.3.4 Caveats

        35
    • 2.5.4 Near Objects

      35
      • 2.5.4.1 Example

        35
      • 2.5.4.2 Differences

        35
      • 2.5.4.3 Migration to the CCI

        36
      • 2.5.4.4 Caveats

        36
    • 2.5.5 Persistent Objects

      36
      • 2.5.5.1 Example

        36
      • 2.5.5.2 Differences

        36
      • 2.5.5.3 Migration to the CCI

        36
      • 2.5.5.4 Caveats

        36
    • 2.5.6 X and Y Data Objects

      37
      • 2.5.6.1 Example

        37
      • 2.5.6.2 Differences

        37
      • 2.5.6.3 Migration to the CCI

        37
      • 2.5.6.4 Caveats

        37
    • 2.5.7 Banked Data Objects

      37
      • 2.5.7.1 Example

        37
      • 2.5.7.2 Differences

        38
      • 2.5.7.3 Migration to the CCI

        38
      • 2.5.7.4 Caveats

        38
    • 2.5.8 Alignment of Objects

      38
      • 2.5.8.1 Example

        38
      • 2.5.8.2 Differences

        38
      • 2.5.8.3 Migration to the CCI

        38
      • 2.5.8.4 Caveats

        38
    • 2.5.9 EEPROM Objects

      39
      • 2.5.9.1 Example

        39
      • 2.5.9.2 Differences

        39
      • 2.5.9.3 Migration to the CCI

        39
      • 2.5.9.4 Caveats

        39
    • 2.5.10 Interrupt Functions

      39
      • 2.5.10.1 Example

        40
      • 2.5.10.2 Differences

        40
      • 2.5.10.3 Migration to the CCI

        41
      • 2.5.10.4 Caveats

        41
    • 2.5.11 Packing Objects

      42
      • 2.5.11.1 Example

        42
      • 2.5.11.2 Differences

        42
      • 2.5.11.3 Migration to the CCI

        42
      • 2.5.11.4 Caveats

        42
    • 2.5.12 Indicating Antiquated Objects

      43
      • 2.5.12.1 Example

        43
      • 2.5.12.2 Differences

        43
      • 2.5.12.3 Migration to the CCI

        43
      • 2.5.12.4 Caveats

        43
    • 2.5.13 Assigning Objects to Sections

      43
      • 2.5.13.1 Example

        43
      • 2.5.13.2 Differences

        44
      • 2.5.13.3 Migration to the CCI

        44
      • 2.5.13.4 Caveats

        44
    • 2.5.14 Specifying Configuration Bits

      45
      • 2.5.14.1 Example

        45
      • 2.5.14.2 Differences

        45
      • 2.5.14.3 Migration to the CCI

        45
      • 2.5.14.4 Caveats

        45
    • 2.5.15 Manifest Macros

      46
      • Table 2-1: Manifest macros defined by the CCI

        46
      • 2.5.15.1 Example

        46
      • 2.5.15.2 Differences

        46
      • 2.5.15.3 Migration to the CCI

        46
      • 2.5.15.4 Caveats

        46
    • 2.5.16 In-line Assembly

      47
      • 2.5.16.1 Example

        47
      • 2.5.16.2 Differences

        47
      • 2.5.16.3 Migration to the CCI

        47
      • 2.5.16.4 Caveats

        47
  • 2.6 Compiler Features

    48
    • 2.6.1 Enabling the CCI

      48
      • 2.6.1.1 Differences

        48
      • 2.6.1.2 Migration to the CCI

        48
      • 2.6.1.3 Caveats

        48
• Chapter 3. Compiler Command-Line Driver

  49
  • 3.1 Introduction

    49
  • 3.2 Invoking the Compiler

    50
    • 3.2.1 Drive Command-Line Format

      50
    • 3.2.2 Environment Variables

      50
    • 3.2.3 Input File Types

      51
  • 3.3 The Compilation Sequence

    52
    • 3.3.1 The Compiler Applications

      52
    • 3.3.2 Single-Step Compilation

      54
      • 3.3.2.1 Compiling a Single File

        54
      • 3.3.2.2 Compiling Multiple Files

        55
    • 3.3.3 Multi-Step Compilation

      55
    • 3.3.4 Assembly Compilation

      56
  • 3.4 Runtime Files

    57
    • 3.4.1 Library Files

      57
      • 3.4.1.1 Standard Libraries

        57
      • 3.4.1.2 User-Defined libraries

        57
    • 3.4.2 Startup and Initialization

      57
  • 3.5 Compiler Output

    58
    • 3.5.1 Output Files

      58
    • 3.5.2 Diagnostic Files

      58
  • 3.6 Compiler Messages

    59
  • 3.7 Driver Option Descriptions

    60
    • 3.7.1 Options Specific to 16-Bit Devices

      60
    • 3.7.2 Options for Controlling the Kind of Output

      62
    • 3.7.3 Options for Controlling the C Dialect

      63
    • 3.7.4 Options for Controlling Warnings and Errors

      64
    • 3.7.5 Options for Debugging

      70
    • 3.7.6 Options for Controlling Optimization

      71
    • 3.7.7 Options for Controlling the Preprocessor

      76
    • 3.7.8 Options for Assembling

      79
    • 3.7.9 Options for Linking

      79
    • 3.7.10 Options for Directory Search

      82
    • 3.7.11 Options for Code Generation Conventions

      82
  • 3.8 MPLAB IDE Toolsuite Equivalents

    83
• Chapter 4. Device-Related Features

  85
  • 4.1 Introduction

    85
  • 4.2 Device Support

    85
  • 4.3 Device Header Files

    85
    • 4.3.1 Register Definition Files

      85
  • 4.4 Stack

    86
  • 4.5 Configuration Bit Access

    86
  • 4.6 Using SFRs

    87
  • 4.7 Bit-Reversed and Modulo Addressing

    89
• Chapter 5. Differences Between MPLAB XC16 and ANSI C

  91
  • 5.1 Divergence from the ANSI C Standard

    91
  • 5.2 Extensions to the ANSI C Standard

    91
    • 5.2.1 Keyword Differences

      91
    • 5.2.2 Expression Differences

      91
  • 5.3 Implementation-Defined Behavior

    91
• Chapter 6. Supported Data Types and Variables

  93
  • 6.1 Introduction

    93
  • 6.2 Identifiers

    93
  • 6.3 Integer Data Types

    94
    • 6.3.1 Double-Word Integers

      94
    • 6.3.2 char Types

      95
  • 6.4 Floating-Point Data Types

    95
  • 6.5 Structures and Unions

    96
    • 6.5.1 Structure and Union Qualifiers

      96
    • 6.5.2 Bit-Fields in Structures

      96
  • 6.6 Pointer Types

    98
    • 6.6.1 Combining Type Qualifiers and Pointers

      98
    • 6.6.2 Data Pointers

      99
    • 6.6.3 Function Pointers

      99
    • 6.6.4 Special Pointer Targets

      99
  • 6.7 Complex Data Types

    100
  • 6.8 Literal Constant Types and Formats

    101
  • 6.9 Standard Type Qualifiers

    103
    • 6.9.1 Const Type Qualifier

      103
    • 6.9.2 Volatile Type Qualifier

      103
  • 6.10 Compiler-Specific type Qualifiers

    104
    • 6.10.1 __psv__ Type Qualifier

      104
    • 6.10.2 __prog__ Type Qualifier

      104
    • 6.10.3 __eds__ Type Qualifier

      105
    • 6.10.4 __pack_upper_byte Type Qualifier

      105
    • 6.10.5 __pmp__ Type Qualifier

      105
    • 6.10.6 __external__ Type Qualifier

      106
  • 6.11 Variable Attributes

    107
• Chapter 7. Memory Allocation and Access

  117
  • 7.1 Introduction

    117
  • 7.2 Address Spaces

    117
  • 7.3 Variables in Data Space Memory

    118
    • 7.3.1 Non-Auto Variable Allocation and Access

      118
      • 7.3.1.1 Default Allocation of Non-auto Variables

        118
      • 7.3.1.2 Static Variables

        119
      • 7.3.1.3 Non-Auto Variable Size Limits

        119
      • 7.3.1.4 Changing Non-Auto Variable Allocation

        120
      • 7.3.1.5 Data Memory Allocation Macros

        120
    • 7.3.2 Auto Variable Allocation and Access

      121
      • 7.3.2.1 Software Stack

        121
      • 7.3.2.2 The C Stack Usage

        122
      • 7.3.2.3 Auto Variable Size Limits

        124
    • 7.3.3 Changing Auto Variable Allocation

      124
  • 7.4 Variables in Program Space

    125
    • 7.4.1 Allocation and Access of Program Memory Objects

      125
      • 7.4.1.1 String and Const Objects

        125
      • 7.4.1.2 Const-qualified Variables in Secure Flash

        126
      • 7.4.1.3 String Literals as Arguments

        126
    • 7.4.2 Access of objects in Program Memory

      127
      • 7.4.2.1 Managed PSV Access

        127
      • 7.4.2.2 Object Compatibility Model

        127
      • 7.4.2.3 ISR Considerations

        128
    • 7.4.3 Size Limitations of Program Memory Variables

      128
    • 7.4.4 Changing Program Memory Variable Allocation

      129
  • 7.5 Parallel Master Port Access

    130
    • 7.5.1 Initialize PMP

      130
    • 7.5.2 Declare a New Memory Space

      131
    • 7.5.3 Define Variables within PMP Space

      131
  • 7.6 External Memory Access

    132
    • 7.6.1 Declare a New Memory Space

      132
    • 7.6.2 Define Variables Within an External Space

      132
    • 7.6.3 Define How to Access Memory Spaces

      133
      • 7.6.3.1 Functions for Reading

        133
      • 7.6.3.2 Functions for Writing

        134
    • 7.6.4 An External Example

      135
  • 7.7 Extended Data Space Access

    136
  • 7.8 Packing Data Stored in Flash

    137
    • 7.8.1 Packed Example

      137
    • 7.8.2 Usage Considerations

      137
    • 7.8.3 Addressing Information

      138
  • 7.9 Allocation of Variables to Registers

    139
  • 7.10 Variables in EEPROM

    139
    • 7.10.1 Accessing EEDATA via User Managed PSV

      139
    • 7.10.2 Accessing EEDATA Using TBLRDx Instructions

      140
    • 7.10.3 Accessing EEDATA Using Managed Access

      141
    • 7.10.4 Additional Sources of Information

      141
  • 7.11 Dynamic Memory Allocation

    141
  • 7.12 Memory Models

    142
    • 7.12.1 Near or Far Data

      143
• Chapter 8. Operators and Statements

  145
  • 8.1 Introduction

    145
  • 8.2 Built-In Functions

    145
  • 8.3 Integral Promotion

    145
• Chapter 9. Register Usage

  147
  • 9.1 Introduction

    147
  • 9.2 Register Variables

    147
  • 9.3 Changing Register Contents

    148
• Chapter 10. Functions

  149
  • 10.1 Introduction

    149
  • 10.2 Writing Functions

    149
    • 10.2.1 Function Specifiers

      149
    • 10.2.2 Function Attributes

      149
  • 10.3 Function Size Limits

    156
  • 10.4 Allocation of Function Code

    156
  • 10.5 Changing the Default Function Allocation

    157
  • 10.6 Inline Functions

    158
  • 10.7 Memory Models

    159
    • 10.7.1 Near or Far Code

      160
  • 10.8 Function Call Conventions

    161
    • 10.8.1 Function Parameters

      161
    • 10.8.2 Return Value

      163
    • 10.8.3 Preserving Registers Across Function Calls

      163
• Chapter 11. Interrupts

  165
  • 11.1 Introduction

    165
  • 11.2 Interrupt Operation

    166
  • 11.3 Writing an Interrupt Service Routine

    166
    • 11.3.1 Guidelines for Writing ISRs

      166
    • 11.3.2 Syntax for Writing ISRs

      167
    • 11.3.3 Coding ISRs

      167
    • 11.3.4 Using Macros to Declare Simple ISRs

      168
  • 11.4 Specifying the Interrupt Vector

    169
    • 11.4.1 Non-SMPS dsPIC30F DSCs Interrupt Vectors

      170
    • 11.4.2 SMPS dsPIC30F DSCs Interrupt Vectors

      172
    • 11.4.3 PIC24F MCUs Interrupt Vectors

      174
    • 11.4.4 dsPIC33F DSCs/PIC24H MCUs Interrupt Vectors

      177
  • 11.5 Interrupt Service Routine Context Saving

    180
  • 11.6 Nesting Interrupts

    180
  • 11.7 Enabling/Disabling Interrupts

    181
  • 11.8 ISR Considerations

    182
    • 11.8.1 Sharing Memory with Mainline Code

      182
      • 11.8.1.1 Development Issues

        183
      • 11.8.1.2 Development Solutions

        184
      • 11.8.1.3 Application Example

        185
    • 11.8.2 PSV Usage with Interrupt Service Routines

      186
    • 11.8.3 Latency

      186
• Chapter 12. Main, Runtime Startup and Reset

  187
  • 12.1 Introduction

    187
  • 12.2 The main Function

    187
  • 12.3 Runtime Startup and Initialization

    187
• Chapter 13. Mixing C and Assembly Code

  189
  • 13.1 Introduction

    189
  • 13.2 Mixing Assembly Language and C Variables and Functions

    189
  • 13.3 Using Inline Assembly Language

    192
  • 13.4 Predefined Assembly Macros

    196
• Chapter 14. Library Routines

  197
• Chapter 15. Optimizations

  199
  • 15.1 Introduction

    199
• Chapter 16. Preprocessing

  201
  • 16.1 Introduction

    201
  • 16.2 C Language Comments

    201
  • 16.3 Preprocessing Directives

    201
  • 16.4 Predefined Macro Names

    202
    • 16.4.1 Compiler Version Macro

      202
    • 16.4.2 Output Types Macros

      203
    • 16.4.3 Target Device Macros

      203
    • 16.4.4 Device Features Macros

      203
    • 16.4.5 Other Macros

      204
  • 16.5 Pragmas vs. Attributes

    205
• Chapter 17. Linking Programs

  207
  • 17.1 Introduction

    207
  • 17.2 Default Memory Spaces

    207
  • 17.3 Replacing Library Symbols

    209
  • 17.4 Linker-Defined Symbols

    209
  • 17.5 Default Linker Script

    210
• Appendix A. Implementation-Defined Behavior

  211
  • A.1 Introduction

    211
  • A.2 Translation

    212
  • A.3 Environment

    212
  • A.4 Identifiers

    213
  • A.5 Characters

    213
  • A.6 Integers

    214
  • A.7 Floating Point

    215
  • A.8 Arrays and Pointers

    215
  • A.9 Registers

    216
  • A.10 Structures, Unions, Enumerations and Bit Fields

    216
  • A.11 Qualifiers

    216
  • A.12 Declarators

    216
  • A.13 Statements

    217
  • A.14 Preprocessing Directives

    217
  • A.15 Library Functions

    218
  • A.16 Signals

    219
  • A.17 Streams and Files

    220
  • A.18 tmpfile

    221
  • A.19 errno

    221
  • A.20 Memory

    221
  • A.21 abort

    221
  • A.22 exit

    221
  • A.23 getenv

    221
  • A.24 system

    221
  • A.25 strerror

    222
• Appendix B. Diagnostics

  223
  • B.1 Introduction

    223
  • B.2 Errors

    223
  • B.3 Warnings

    242
• Appendix C. GNU Free Documentation License

  263
  • C.1 Preamble

    263
  • C.2 Applicability and Definitions

    263
  • C.3 Verbatim Copying

    265
  • C.4 Copying in Quantity

    265
  • C.5 Modifications

    266
  • C.6 Combining Documents

    267
  • C.7 Collections of Documents

    267
  • C.8 Aggregation with Independent Works

    267
  • C.9 Translation

    268
  • C.10 Termination

    268
  • C.11 Future Revisions of this License

    268
  • C.12 Relicensing

    269
• Appendix D. ASCII Character Set

  271
• Appendix E. Deprecated Features

  273
  • E.1 Introduction

    273
  • E.2 Predefined Constants

    273
  • E.3 Variables in Specified Registers

    274
    • E.3.1 Defining Global Register Variables

      274
    • E.3.2 Specifying Registers for Local Variables

      275
  • E.4 Changing Non-Auto Variable Allocation

    275
• Appendix F. Built-in Functions

  277
  • F.1 Introduction

    277
  • F.2 Built-In Function Descriptions

    279
• Appendix G. XC16 Configuration Settings

  305
  • G.1 Introduction

    305
• Glossary

  307
• Index

  327
• Worldwide Sales and Service

  338