Microchip Technology SW006023-1N User Manuals

Table of Contents

• Documentation Conventions

  9
• Chapter 1. Compiler Overview

  13
• 1.1 Introduction

  13
• 1.2 Device Description

  13
• 1.3 Compiler Description and Documentation

  13
  • 1.3.1 Conventions

    13
  • 1.3.2 ANSI C Standards

    14
  • 1.3.3 Optimization

    14
  • 1.3.4 ANSI Standard Library Support

    14
  • 1.3.5 ISO/IEC C++ Standard

    14
  • 1.3.6 Compiler Driver

    14
  • 1.3.7 Documentation

    14
• 1.4 Compiler and Other Development Tools

  15
• Chapter 2. Common C Interface

  17
• 2.1 Introduction

  17
• 2.2 Background – The Desire for Portable Code

  17
  • 2.2.1 The ANSI Standard

    18
  • 2.2.2 The Common C Interface

    19
• 2.3 Using the CCI

  20
• 2.4 ANSI Standard Refinement

  21
  • 2.4.1 Source File Encoding

    21
    • 2.4.1.1 Example

      21
    • 2.4.1.2 Differences

      21
    • 2.4.1.3 Migration to the CCI

      21
  • 2.4.2 The Prototype for main

    21
    • 2.4.2.1 Example

      21
    • 2.4.2.2 Differences

      21
    • 2.4.2.3 Migration to the CCI

      21
  • 2.4.3 Header File Specification

    21
    • 2.4.3.1 Example

      21
    • 2.4.3.2 Differences

      22
    • 2.4.3.3 Migration to the CCI

      22
  • 2.4.4 Include Search Paths

    22
    • 2.4.4.1 Example

      22
    • 2.4.4.2 Differences

      22
    • 2.4.4.3 Migration to the CCI

      22
  • 2.4.5 The Number of Significant Initial Characters in an Identifier

    23
    • 2.4.5.1 Example

      23
    • 2.4.5.2 Differences

      23
    • 2.4.5.3 Migration to the CCI

      23
  • 2.4.6 Sizes of Types

    23
    • 2.4.6.1 Example

      23
    • 2.4.6.2 Differences

      23
    • 2.4.6.3 Migration to the CCI

      23
  • 2.4.7 Plain char Types

    24
    • 2.4.7.1 Example

      24
    • 2.4.7.2 Differences

      24
    • 2.4.7.3 Migration to the CCI

      24
  • 2.4.8 Signed Integer Representation

    24
    • 2.4.8.1 Example

      24
    • 2.4.8.2 Differences

      24
    • 2.4.8.3 Migration to the CCI

      24
  • 2.4.9 Integer conversion

    25
    • 2.4.9.1 Example

      25
    • 2.4.9.2 Differences

      25
    • 2.4.9.3 Migration to the CCI

      25
  • 2.4.10 Bit-wise Operations on Signed Values

    25
    • 2.4.10.1 Example

      25
    • 2.4.10.2 Differences

      25
    • 2.4.10.3 Migration to the CCI

      25
  • 2.4.11 Right-shifting Signed Values

    25
    • 2.4.11.1 Example

      25
    • 2.4.11.2 Differences

      26
    • 2.4.11.3 Migration to the CCI

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

    26
    • 2.4.12.1 Example

      26
    • 2.4.12.2 Differences

      26
    • 2.4.12.3 Migration to the CCI

      26
  • 2.4.13 Default Bit-field int Type

    26
    • 2.4.13.1 Example

      26
    • 2.4.13.2 Differences

      27
    • 2.4.13.3 Migration to the CCI

      27
  • 2.4.14 Bit-fields Straddling a Storage Unit Boundary

    27
    • 2.4.14.1 Example

      27
    • 2.4.14.2 Differences

      27
    • 2.4.14.3 Migration to the CCI

      27
  • 2.4.15 The Allocation Order of Bits-field

    27
    • 2.4.15.1 Example

      28
    • 2.4.15.2 Differences

      28
    • 2.4.15.3 Migration to the CCI

      28
  • 2.4.16 The NULL macro

    28
    • 2.4.16.1 Example

      28
    • 2.4.16.2 Differences

      28
    • 2.4.16.3 Migration to the CCI

      28
  • 2.4.17 Floating-point sizes

    28
    • 2.4.17.1 Example

      28
    • 2.4.17.2 Differences

      28
    • 2.4.17.3 Migration to the CCI

      28
• 2.5 ANSI Standard Extensions

  29
  • 2.5.1 Generic Header File

    29
    • 2.5.1.1 Example

      29
    • 2.5.1.2 Differences

      29
    • 2.5.1.3 Migration to the CCI

      29
  • 2.5.2 Absolute addressing

    29
    • 2.5.2.1 Example

      29
    • 2.5.2.2 Differences

      29
    • 2.5.2.3 Migration to the CCI

      30
    • 2.5.2.4 Caveats

      30
  • 2.5.3 Far Objects and Functions

    30
    • 2.5.3.1 Example

      30
    • 2.5.3.2 Differences

      30
    • 2.5.3.3 Migration to the CCI

      31
    • 2.5.3.4 Caveats

      31
  • 2.5.4 Near Objects

    31
    • 2.5.4.1 Example

      31
    • 2.5.4.2 Differences

      31
    • 2.5.4.3 Migration to the CCI

      32
    • 2.5.4.4 Caveats

      32
  • 2.5.5 Persistent Objects

    32
    • 2.5.5.1 Example

      32
    • 2.5.5.2 Differences

      32
    • 2.5.5.3 Migration to the CCI

      32
    • 2.5.5.4 Caveats

      32
  • 2.5.6 X and Y Data Objects

    33
    • 2.5.6.1 Example

      33
    • 2.5.6.2 Differences

      33
    • 2.5.6.3 Migration to the CCI

      33
    • 2.5.6.4 Caveats

      33
  • 2.5.7 Banked Data Objects

    33
    • 2.5.7.1 Example

      33
    • 2.5.7.2 Differences

      34
    • 2.5.7.3 Migration to the CCI

      34
    • 2.5.7.4 Caveats

      34
  • 2.5.8 Alignment of Objects

    34
    • 2.5.8.1 Example

      34
    • 2.5.8.2 Differences

      34
    • 2.5.8.3 Migration to the CCI

      34
    • 2.5.8.4 Caveats

      34
  • 2.5.9 EEPROM Objects

    35
    • 2.5.9.1 Example

      35
    • 2.5.9.2 Differences

      35
    • 2.5.9.3 Migration to the CCI

      35
    • 2.5.9.4 Caveats

      35
  • 2.5.10 Interrupt Functions

    35
    • 2.5.10.1 Example

      36
    • 2.5.10.2 Differences

      36
    • 2.5.10.3 Migration to the CCI

      36
    • 2.5.10.4 Caveats

      37
  • 2.5.11 Packing Objects

    37
    • 2.5.11.1 Example

      37
    • 2.5.11.2 Differences

      37
    • 2.5.11.3 Migration to the CCI

      38
    • 2.5.11.4 Caveats

      38
  • 2.5.12 Indicating Antiquated Objects

    38
    • 2.5.12.1 Example

      38
    • 2.5.12.2 Differences

      38
    • 2.5.12.3 Migration to the CCI

      38
    • 2.5.12.4 Caveats

      38
  • 2.5.13 Assigning Objects to Sections

    39
    • 2.5.13.1 Example

      39
    • 2.5.13.2 Differences

      39
    • 2.5.13.3 Migration to the CCI

      39
    • 2.5.13.4 Caveats

      40
  • 2.5.14 Specifying Configuration Bits

    40
    • 2.5.14.1 Example

      40
    • 2.5.14.2 Differences

      40
    • 2.5.14.3 Migration to the CCI

      40
    • 2.5.14.4 Caveats

      40
  • 2.5.15 Manifest Macros

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

      41
    • 2.5.15.1 Example

      41
    • 2.5.15.2 Differences

      41
    • 2.5.15.3 Migration to the CCI

      41
    • 2.5.15.4 Caveats

      41
  • 2.5.16 In-line Assembly

    42
    • 2.5.16.1 Example

      42
    • 2.5.16.2 Differences

      42
    • 2.5.16.3 Migration to the CCI

      42
    • 2.5.16.4 Caveats

      42
• 2.6 Compiler Features

  43
  • 2.6.1 Enabling the CCI

    43
    • 2.6.1.1 Differences

      43
    • 2.6.1.2 Migration to the CCI

      43
    • 2.6.1.3 Caveats

      43
• Chapter 3. Compiler Command Line Driver

  45
• 3.1 Introduction

  45
• 3.2 Invoking the Compiler

  45
  • 3.2.1 Driver Command Line Format

    45
    • Table 3-1: Compiler-Related Environmental Variables

      46
  • 3.2.2 Input File Types

    48
    • Table 3-2: File Names

      48
• 3.3 The C Compilation Sequence

  49
  • 3.3.1 Single-step C Compilation

    49
    • 3.3.1.1 Compiling a Single C File

      49
    • 3.3.1.2 Compiling Multiple C Files

      50
  • 3.3.2 Multi-step C Compilation

    51
• 3.4 The C++ Compilation Sequence

  51
  • 3.4.1 Single-step C++ Compilation

    51
    • 3.4.1.1 Compiling a Single C++ File

      51
  • 3.4.2 Compiling Multiple C and C++ files

    54
• 3.5 Runtime Files

  55
  • 3.5.1 Library Files

    55
    • 3.5.1.1 Standard Libraries

      56
    • 3.5.1.2 User-defined libraries

      57
  • 3.5.2 Peripheral Library Functions

    57
• 3.6 Start-up and Initialization

  58
• 3.7 Compiler Output

  58
  • 3.7.1 Output Files

    58
    • Table 3-3: File Names

      58
  • 3.7.2 Diagnostic Files

    59
• 3.8 Compiler Messages

  60
• 3.9 Driver Option Descriptions

  60
  • Table 3-4: PIC32MX Device-Specific Options

    61
  • Table 3-5: Kind-of-Output Control Options

    62
  • Table 3-6: C Dialect Control Options

    63
  • Table 3-7: C++ Dialect Control Options

    64
  • Table 3-8: Warning and Error Options Implied by All Warnings

    65
  • Table 3-9: Warning and Error Options Not Implied by All Warnings

    69
  • Table 3-10: Debugging Options

    72
  • Table 3-11: General Optimization Options

    72
  • Table 3-12: Specific Optimization Options

    73
  • Table 3-13: Machine-Independent Optimization Options

    76
  • Table 3-14: Preprocessor Options

    78
  • Table 3-15: Assembly Options

    81
  • Table 3-16: Linking Options

    81
  • Table 3-17: Directory Search Options

    82
  • Table 3-18: Code Generation Convention Options

    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 CP0 Register Definitions Header File

    85
• 4.4 Stack

  86
  • 4.4.1 Configuration Bit Access

    86
• 4.5 Using SFRs From C Code

  88
  • 4.5.1 CP0 Register Definitions

    89
  • 4.5.2 CP0 Register Field Definitions

    89
  • 4.5.3 CP0 Access Macros

    89
  • 4.5.4 Address Translation Macros

    90
• Chapter 5. ANSI C Standard Issues

  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 Statement Differences

    91
  • 5.2.3 Expression Differences

    91
• 5.3 Implementation-defined behavior

  92
• Chapter 6. Supported Data Types and Variables

  93
• 6.1 Introduction

  93
• 6.2 Identifiers

  93
• 6.3 Data Representation

  93
• 6.4 Integer Data Types

  94
• 6.5 Floating-Point Data Types

  96
  • Table 6-1: Floating-point format example IEEE 754

    96
  • Table 6-2: Ranges of floating-point type values

    97
• 6.6 Structures and Unions

  98
  • 6.6.1 Structure and Union Qualifiers

    98
  • 6.6.2 Bit Fields in Structures

    98
• 6.7 Pointer Types

  100
  • 6.7.1 Combining Type Qualifiers and Pointers

    100
  • 6.7.3 Function Pointers

    101
    • 6.7.3.1 Special Pointer Targets

      101
• 6.8 Complex Data Types

  102
• 6.9 Constant Types and Formats

  102
  • Table 6-3: Radix formats

    102
  • Table 6-4: Suffixes and assigned types

    102
• 6.10 Standard Type Qualifiers

  104
  • 6.10.1 Const Type Qualifier

    104
  • 6.10.2 Volatile Type Qualifier

    104
• 6.11 Compiler-Specific Qualifiers

  105
• 6.12 Variable Attributes

  105
• Chapter 7. Memory Allocation and Access

  109
• 7.1 Introduction

  109
• 7.2 Address Spaces

  109
• 7.3 Variables in Data Memory

  110
  • 7.3.1 Non-auto Variable Allocation

    110
  • 7.3.3 Non-auto Variable Size Limits

    111
  • 7.3.4 Changing the Default Non-auto Variable Allocation

    111
• 7.4 Auto Variable Allocation and Access

  112
  • 7.4.1 Local Variable Size Limits

    113
• 7.5 Variables in Program Memory

  113
  • 7.5.1 Size Limitations of const Variables

    114
  • 7.5.2 Changing the Default Allocation

    114
• 7.6 Variables in Registers

  114
• 7.7 Dynamic Memory Allocation

  114
• 7.8 Memory Models

  114
• Chapter 8. Operators and Statements

  117
• 8.1 Introduction

  117
• 8.2 Integral Promotion

  117
• 8.3 Type References

  118
• 8.4 Labels as Values

  119
• 8.5 Conditional Operator Operands

  120
• 8.6 Case Ranges

  120
• Chapter 9. Register Usage

  121
• 9.1 Introduction

  121
• 9.2 Register Usage

  121
• 9.3 Register Conventions

  121
  • Table 9-1: Register Conventions

    121
• Chapter 10. Functions

  123
• 10.1 Writing Functions

  123
• 10.2 Function Attributes and Specifiers

  123
  • 10.2.1 Function Attributes

    123
• 10.3 Allocation of Function Code

  127
• 10.4 Changing the Default Function Allocation

  127
• 10.5 Function Size Limits

  128
• 10.6 Function Parameters

  128
  • Table 10-1: Registers Required

    128
• 10.7 Function Return Values

  130
• 10.8 Calling Functions

  130
• 10.9 Inline Functions

  130
• Chapter 11. Interrupts

  133
• 11.1 Introduction

  133
• 11.2 Interrupt Operation

  133
• 11.3 Writing an Interrupt Service Routine

  134
  • 11.3.1 Interrupt Attribute

    134
    • 11.3.3.1 __ISR(V, IPL)

      135
    • 11.3.3.2 __ISR_AT_VECTOR(v, IPL)

      136
    • 11.3.3.3 Interrupt-Vector Macros

      137
• 11.4 Associating a Handler Function with an Exception Vector

  139
  • 11.4.1 Vector Attribute

    139
  • 11.4.3 Vector Pragma

    140
• 11.5 Exception Handlers

  141
  • 11.5.1 Bootstrap Exception

    141
  • 11.5.2 General Exception

    141
• 11.6 Interrupt Service Routine Context Switching

  141
  • 11.6.1 Context Restoration

    142
• 11.7 Latency

  142
• 11.8 Nesting Interrupts

  142
• 11.9 Enabling/Disabling Interrupts

  142
• 11.10 ISR Considerations

  142
• Chapter 12. Main, Runtime Start-up and Reset

  143
• 12.1 Introduction

  143
• 12.2 The Main Function

  143
• 12.3 Runtime Start-up Code

  143
  • 12.3.1 Jump to NMI Handler if an NMI Occurred

    144
    • 12.3.5.2 Hardware Enable Register (HWREna – CP0 Register 7, Select 0)

      149
    • 12.3.5.3 Bad Virtual Address Register (BadVAddr – CP0 Register 8, Select 0)

      149
    • 12.3.5.4 Count Register (Count – CP0 Register 9, Select 0)

      150
    • 12.3.5.5 Compare Register (Compare – CP0 Register 11, Select 0)

      150
    • 12.3.5.7 Interrupt Control Register (IntCtl – CP0 Register 12, Select 1)

      150
    • 12.3.5.8 Shadow Register Control Register (SRSCtl – CP0 Register 12, Select 2)

      151
    • 12.3.5.9 Shadow Register Map Register (SRSMap – CP0 Register 12, Select 3)

      151
    • 12.3.5.11 Exception Program Counter (EPC – CP0 Register 14, Select 0)

      151
    • 12.3.5.12 Processor Identification Register (PRId – CP0 Register 15, Select 0)

      152
    • 12.3.5.15 Trace Control Register (TraceControl – CP0 Register 23, Select 1)

      153
    • 12.3.5.16 Trace Control 2 Register (TraceControl2 – CP0 Register 23, Select 2)

      153
    • 12.3.5.18 TraceBPC Register (TraceBPC – CP0 Register 23, Select 4)

      153
    • 12.3.5.19 Debug2 Register (Debug2 – CP0 Register 23, Select 5)

      154
    • 12.3.5.20 Debug Exception Program Counter (DEPC – CP0 Register 24, Select 0)

      154
    • 12.3.5.22 Debug Exception Save Register (DeSave – CP0 Register 31, Select 0)

      154
  • 12.3.7 Change Location of Exception Vectors

    155
  • 12.3.8 Call the C++ initialization code

    155
  • 12.3.9 Call Main

    155
• 12.4 The On Reset Routine

  157
  • 12.4.1 Clearing Objects

    157
• Chapter 13. Library Routines

  159
• 13.1 Using Library Routines

  159
• Chapter 14. Mixing C/C++ and Assembly Language

  161
• 14.1 Introduction

  161
• 14.2 Using Inline Assembly Language

  161
  • Table 14-1: Register Constraint Letters Supported by the Compiler

    162
  • Table 14-2: Integer Constraint Letters Supported by the Compiler

    162
  • Table 14-3: General Constraint Letters Supported by the Compiler

    162
  • Table 14-4: Constraint Modifiers Supported by the Compiler

    162
  • 14.2.1 Equivalent Assembly Symbols

    164
• 14.3 Predefined Assembly Macros

  164
  • Table 14-5: Predefined Macros

    164
• Chapter 15. Optimizations

  167
• 15.1 Introduction

  167
• Chapter 16. Preprocessing

  169
• 16.1 Introduction

  169
• 16.2 C/C++ Language Comments

  169
• 16.3 Preprocessor Directives

  169
  • Table 16-1: Preprocessor directives

    169
• 16.4 Pragma Directives

  171
• 16.5 Predefined Macros

  172
  • 16.5.1 32-Bit C/C++ Compiler Macros

    172
• Chapter 17. Linking Programs

  175
• 17.1 Introduction

  175
• 17.2 Replacing Library Symbols

  175
• 17.3 Linker-Defined Symbols

  175
• 17.4 Default Linker Script

  176
  • 17.4.1 Output Format and Entry Points

    176
    • 17.4.3.2 OPTIONAL Inclusion of Processor-Specific Peripheral Libraries

      178
    • 17.4.3.3 Base Exception Vector Address and Vector Spacing Symbols

      178
    • 17.4.4.2 .bev_excpt Section

      182
    • 17.4.4.3 .dbg_excpt Section

      182
    • 17.4.4.5 .app_excpt Section

      182
    • 17.4.4.6 .vector_0 .. .vector_63 Sections

      183
    • 17.4.4.7 .start-up Section

      183
    • 17.4.4.9 C++ Initialization Sections

      184
    • 17.4.4.10 .rodata Section

      185
    • 17.4.4.12 .sbss2 Section

      186
    • 17.4.4.14 .data Section

      186
    • 17.4.4.15 .got Section

      186
    • 17.4.4.16 .sdata Section

      187
    • 17.4.4.18 .lit4 Section

      187
    • 17.4.4.19 .sbss Section

      188
    • 17.4.4.21 .heap Section

      188
    • 17.4.4.23 .ramfunc Section

      189
    • 17.4.4.24 Stack Location

      189
• Appendix 18. Implementation-Defined Behavior

  191
• 18.1 Introduction

  191
• 18.2 Highlights

  191
• 18.3 Overview

  191
• 18.4 Translation

  192
• 18.5 Environment

  192
• 18.6 Identifiers

  193
• 18.7 Characters

  193
• 18.8 Integers

  194
• 18.9 Floating-Point

  194
• 18.10 Arrays and Pointers

  196
• 18.11 Hints

  196
• 18.12 Structures, Unions, Enumerations, and Bit fields

  197
• 18.13 Qualifiers

  197
• 18.14 Declarators

  198
• 18.15 Statements

  198
• 18.16 Pre-Processing Directives

  198
• 18.17 Library Functions

  199
• 18.18 Architecture

  202
• Appendix 19. ASCII Character Set

  203
  • Table 19-1: ASCII character set

    203
• Appendix 20. Deprecated Features

  205
• 20.1 Introduction

  205
• 20.2 Variables in Specified Registers

  205
  • Corporate Office

    238
  • Atlanta

    238
  • Boston

    238
  • Chicago

    238
  • Cleveland

    238
  • Fax: 216-447-0643

    238
  • Dallas

    238
  • Detroit

    238
  • Indianapolis

    238
  • Toronto

    238
  • Fax: 852-2401-3431

    238
  • Australia - Sydney

    238
  • China - Beijing

    238
  • China - Shanghai

    238
  • India - Bangalore

    238
  • Korea - Daegu

    238
  • Korea - Seoul

    238
  • Singapore

    238
  • Taiwan - Taipei

    238
  • Fax: 43-7242-2244-393

    238
  • Denmark - Copenhagen

    238
  • France - Paris

    238
  • Germany - Munich

    238
  • Italy - Milan

    238
  • Spain - Madrid

    238
  • UK - Wokingham

    238
  • Worldwide Sales and Service

    238