2012 Microchip Technology Inc. DS52071B
MPLAB® XC16 C Compiler
User’s Guide
DS52071B-page 2 2012 Microchip Technology Inc.
Information contained in this publication regarding device
applications a nd the like is p ro vid ed only for your convenien ce
and may be supe rseded by up da t es . I t is y o u r r es ponsibility 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, PIC START,
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, M XLAB , 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 T echnology Incorporated
in the U.S.A.
All other trademarks mentioned herein are property of their
respective companies.
© 2012, Microchip Technology Incorporat ed, Printed in the
U.S.A., All Rights Reserved.
Printed on recycled paper.
ISBN: 978-1-62076-467-1
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 Digit al 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.
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 ds PIC® DSCs, KEELOQ® code hopping
devices, Serial EEPROMs, microperiph erals, nonvolatile memory and
analog products. In addition, Microchip’s quality system for the design
and manufacture of development systems is ISO 9001:2000 certified.
QUALITY MANAGEMENT S
YSTEM
CERTIFIED BY DNV
== ISO/TS 16949 ==
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 3
Table of Contents
Preface .........................................................................................................................11
Chapter 1. Compiler Overview
1.1 Introduction ...................................................................................................17
1.2 De vice D escrip t io n .................... ........... ................ ............... ................ ......... 17
1.3 Co m p ile r Desc riptio n an d D o cu ment a tion ... .. ........... ............................. .......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
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 Usi n g the C CI .. ...... ........... ................ ........... ........... ............... ........... ........... . 24
2.4 ANSI Standard Refinement ..........................................................................25
2.4.1 Source File Encoding ................................................................................25
2.4.2 The Prototype for main ..............................................................................25
2.4.3 Header File Specification ..........................................................................25
2.4.4 Include Search Paths ................................................................................26
2.4.5 The number of Significant Initial Characters in an Identifier ......................27
2.4.6 Sizes of Types ...........................................................................................27
2.4.7 Plain char Types ........................................................................................28
2.4.8 Signed Integer Representation ..................................................................28
2.4.9 Integer conversion .....................................................................................29
2.4.10 Bit-wise Operations on Signed Values ....................................................29
2.4.11 Right-shifting Signed Values ...................................................................29
2.4.12 Conversion of Union Member Accessed Using Member
With Different Type .. ....... ...... ...... ....... ...... ....... ...... .................... ...... .......30
2.4.13 Default Bit-f ield int Type ......... ...... ....... ...... ....... ...... ....... ................... .......30
2.4.14 Bit-fields Straddling a Storage Unit Boundary .........................................31
2.4.15 The Allocation Order of Bits-field .............................................................31
2.4.16 The NULL macro .....................................................................................32
2.4.17 Floating -poi nt sizes ...................... ....... ................... ....... ................... .......32
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 4 2012 Microchip Technology Inc.
2.5 ANSI Standard Extensions ........................................................................... 33
2.5.1 Generic Header File ...................................................................................33
2.5.2 Absolute addressing ..................................................................................33
2.5.3 Far Objects and Functions .........................................................................34
2.5.4 Near Objects ..............................................................................................35
2.5.5 Persistent Objects ......................................................................................36
2.5.6 X and Y Data Objects ................................................................................37
2.5.7 Banked Data Objects .................................................................................37
2.5.8 Alignment of Objects ..................................................................................38
2.5.9 EEPROM Objects ......................................................................................39
2.5.10 Interrupt Functions ........... ....... ...... ...... .................... ...... .................... ...... .3 9
2.5.11 Packing Object s ............................ ................... ....... ................... ..............4 2
2.5.12 Indica ting Anti qua ted Objec ts .................... ................... .................... .......4 3
2.5.13 Assigning Objects to Sections .................................................................43
2.5.14 Specifying Configuration Bits ...................................................................45
2.5.15 Manifest Mac ros .. ....... ...... ....... ...... ...... ....... ...... ....... ................... ....... ....... 4 6
2.5.16 In-line Asse mbly .. ....... ...... ....... ...... ...... ....... ................... ....... ................... .4 7
2.6 Co m p ile r Fe a tures .............. ........... ............... ........... ............ ............... .......... 4 8
2.6.1 Enabling the CCI ........................................................................................48
Chapter 3. Compiler Command-Line Driver
3.1 Introduction ................................................................................................... 49
3.2 Invoki n g the C o m p ile r .. ........... ........... ........... ................ ........... ........... .......... 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.3 Multi-Step Compilation ...............................................................................55
3.3.4 Assembly Compilation ...............................................................................56
3.4 Ru ntime F ile s ... ................ ........... ........... ............... ........... ........... ........... ...... 57
3.4.1 Library Files ...............................................................................................57
3.4.2 Startup and Initialization .............................................................................57
3.5 Co m p ile r Outpu t .... .. ........... ........... ............... ........... ............ ............... .......... 58
3.5.1 Output Files ................................................................................................58
3.5.2 Diagnostic Files ..........................................................................................58
3.6 Compiler Messages ...................................................................................... 59
Table of Cont ents
2012 Microchip Technology Inc. DS52071B-page 5
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
4.1 Introduction ...................................................................................................85
4.2 Device Support .............................................................................................85
4.3 Device Header Files .....................................................................................85
4.3.1 Register Definition Files ............................................................................85
4.4 Sta c k ...... .. .. ................ ........... ........... ............... ........... ........... ........... ............ 8 6
4.5 Co nfigu r ation B it A c ce s s ..... .. .................... ............... .................... ............... . 86
4.6 Usi n g SF Rs ..... .. ........... ............... ........... ........... ............ ............... ........... ..... 87
4.7 Bit-Rever sed and Mo dulo Addressing .......... .. ........... .. ........... ......................89
Chapter 5. Differences Between MPLAB XC16 and ANSI C
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
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 Fl o a tin g - P o in t D a ta T ype s ....... .. ....... ........... ............... ................ ............... ... 9 5
6.5 Structur es and Unions ..................... ........... .................... ........... ...................96
6.5.1 Structure and Union Qualifiers ..................................................................96
6.5.2 Bit-Fields in Structures ..............................................................................96
6.6 Poi n te r Type s .. .. ....... ........... ............... ........... ........... ................ ........... ......... 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
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 6 2012 Microchip Technology Inc.
6.9 Standard Type Qualifiers ............................................................................ 103
6.9.1 Const Type Qualifier ................................................................................103
6.9.2 Volatile Type Qualifier ..............................................................................103
6.10 Com p ile r -S p e c if ic typ e Q u a lif ie rs .... ....... ........... ........... ........... ........... ...... 104
6.10.1 __psv__ Type Qualifi er ........... ...... ...... .................... ...... .................... .....104
6.10.2 __prog __ Type Qualifier ............... ...... ....... ...... ....... ...... ....... ...... ............10 4
6.10.3 __eds__ Type Qualifier ..........................................................................105
6.10.4 __pack _u ppe r_by te Type Quali fier ............ ...... ....... ...... .................... .....105
6.10.5 __pmp__ Type Qualifier .........................................................................105
6.10.6 __external__ Type Qualifier ...................................................................106
6.11 V a riab le Attribu t e s ..... ........... ................ ........... ........... ............... ........... .... 1 0 7
Chapter 7. Memory Allocation and Access
7.1 Introduction ................................................................................................. 117
7.2 Add r e s s S p a ce s .... ...... ........... ................ ............... ................ ............... ...... 117
7.3 Variables in Data Space Memory ............................................................... 118
7.3.1 Non-Auto Variable Allocation and Access ...............................................118
7.3.2 Auto Variable Allocation and Access .......................................................121
7.3.3 Changing Auto Variable Allocation ..........................................................124
7.4 Var ia b le s in Pr o g ra m S p a ce . ....... ........... ........... ............... ........... ........... .... 1 2 5
7.4.1 Allocation and Access of Program Memory Objects ................................125
7.4.2 Access of objects in Program Memory ....................................................127
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 Ext e rn a l M e m o r y A c ce s s .. ...... ................ ............... ................ ............... ...... 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.4 An External Example ...............................................................................135
7.7 Extended Data Space Access .................................................................... 136
7.8 Pac k in g D a ta S to re d in Fl ash ............... ............... ................ ........... ............ 1 3 7
7.8.1 Packed Example ......................................................................................137
7.8.2 Usage Considerations ..............................................................................137
7.8.3 Addressing Information ............................................................................138
7.9 Allo c a tion of V a ria b les to R e gi s t ers ... ................ ........... ............... ............... 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 Dyna m i c M e m ory All o ca t io n . ....... ............... ................ ............... ........... .... 1 4 1
7.12 Mem o ry M o d el s ... .. .. ................ ........... ........... ........... ............... ........... ...... 142
7.12.1 Near or Far Data ....................................................................................143
Table of Cont ents
2012 Microchip Technology Inc. DS52071B-page 7
Chapter 8. Operators and Statements
8.1 Introduction .................................................................................................145
8.2 Bui lt-In F u n ct io n s . .. ........... ........... ........... ................ ........... ........... .............. 145
8.3 Inte g ral Pr om o tion .... ........... ........... ........... ........... ............... ........... ........... . 145
Chapter 9. Regist er Usage
9.1 Introduction .................................................................................................147
9.2 Re giste r V a ri a bl e s . ... ........... ............... ............... ............ ............... .............. 147
9.3 Ch an g ing R e g is te r Co n t en ts . .. ............... .................... ......................... .......148
Chapter 10. Functions
10.1 Intr o d uc t io n .......... ........... ........... ................ ........... ........... ........... .............. 149
10.2 Wri tin g F u nc t io n s ........ ............... ................ ............... ........... ................ ..... 149
10.2.1 Functio n Specifiers ....................... ....... ...... .................... ................... .....149
10.2.2 Functio n Attribu tes ................. ...... ....... ...... ....... ...... ....... ...... ....... ...... .....149
10.3 F u n c tion Siz e Limit s ... ........... ............... ................ ............... ........... .......... 1 5 6
10.4 Allocation of Function Code .....................................................................156
10.5 Changing the Default Function Allocation ................................................157
10.6 Inlin e F u nc t io n s .......... ........... ............... ................ ............... ........... .......... 158
10.7 Mem o ry M o d el s ... ... .. ........... ............... ........... ........... ........... ................ ..... 159
10.7.1 Near or Far Code ..................................................................................160
10.8 Function Call Conventions .......................................................................161
10.8.1 Functio n Parame ters . ....... ...... ...... ....... ...... ....... ...... .................... ...... .....16 1
10.8.2 Return Value .......................... ...... ....... ...... ....... ................... ..................163
10.8.3 Preserving Registers Across Function Calls .........................................163
Chapter 11. Interrupts
11.1 Intr o d uc t io n .......... ........... ........... ................ ........... ........... ........... .............. 165
11.2 Inte r ru p t O p e ration ... .. ....... ........... ........... ............... ........... ........... ........... . 1 6 6
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 ........ ................... ...... .................... ...... .................... ...... .....16 7
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 I n te r ru p t S e rv ic e R o ut in e C on t e x t S av i ng ... ........... ................ .................. 180
11.6 N es t in g In te rr u p ts ... ...... ........... ........... ................ ........... ........... ........... ..... 180
11.7 Enabling/Disabling Interrupts ...................................................................181
11.8 ISR Co ns ider a ti on s ............. ............... ................ ............... ........... ............ 1 8 2
11.8.1 Sharing Memory with Mainline Code .....................................................182
11.8.2 PSV Usage with Interrupt Service Routines ..........................................186
11.8.3 Latenc y ... ...... ....... ...... ....... ...... ................... ....... ................... ....... ...........18 6
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 8 2012 Microchip Technology Inc.
Chapter 12. Main, Runtime Startup and Reset
12.1 Intr o d uc t io n ..... ........... ........... ........... ................ ........... ........... ........... ........ 1 8 7
12.2 T h e m a in F u n c ti o n .............. ................ ............... ................ ............... ........ 1 8 7
12.3 Runtime Startup and Initialization ............................................................. 187
Chapter 13. Mixing C and Assembly Code
13.1 Intr o d uc t io n ..... ........... ........... ........... ................ ........... ........... ........... ........ 1 8 9
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
Chapter 15. Opti mizations
15.1 Intr o d uc t io n ..... ........... ........... ........... ................ ........... ........... ........... ........ 1 9 9
Chapter 16. Preprocessing
16.1 Intr o d uc t io n ..... ........... ........... ........... ................ ........... ........... ........... ........ 2 0 1
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 ............. ...... ....... ...... ...... ....... ................... ....... ...... ............20 4
16.5 P rag ma s vs . A tt rib u t e s ... ........... ............... ........... ........... ........... ............... 2 0 5
Chapter 17. Linking Programs
17.1 Intr o d uc t io n ..... ........... ........... ........... ................ ........... ........... ........... ........ 2 0 7
17.2 Def a ul t Me m o r y Sp aces ... .. ........... ........... ................ ........... ........... .......... 2 0 7
17.3 Repl a ci n g L ib r ary Sym b o ls ................. ............... .................... ............... .... 2 0 9
17.4 Linker-Defined Symbols ...........................................................................209
17.5 Def a ul t Li nker Sc rip t ....... .. .. ........... ........... ........... ................ ........... .......... 210
Table of Cont ents
2012 Microchip Technology Inc. DS52071B-page 9
Appendix A. Implementation-Defined Behavior
A.1 Introduction ................................................................................................211
A.2 Tra n s la tion ... ... .. ........... ........... ............... ........... ............ ............... ........... ... 2 1 2
A.3 En viron me n t .... .. ........... ............... ........... ................ ............... ................ ..... 212
A.4 Identifiers ...................................................................................................213
A.5 Ch a ra c te r s ............... ........... ........... ............... ........... ........... ........... ............ 2 13
A.6 Integers ......................................................................................................214
A.7 Flo a ting Po in t .. .. ....... ........... ............... ........... ........... ................ ........... ....... 2 1 5
A.8 Arrays a nd P o in te r s .............. ........... ............... ........... ........... ........... .......... 2 1 5
A.9 Re g is te r s ...... ... ...... ................ ........... ........... ........... ............... ........... .......... 216
A.10 Structures, Unions, Enumerations and Bit Fields ....................................216
A.11 Q u a lif ie rs ....... .. .. ........... ................ ........... ........... ........... ............... ........... . 216
A.12 D e clara tors . ....... ................ ............... ............... ............ ............... .............. 216
A.13 S ta te ment s . ... ...... ................ ........... ........... ............... ........... ........... .......... 217
A.14 P re p ro c e s s in g Di re c ti ve s .. ...... ........... ........... ................ ........... ........... ..... 217
A.15 Libra r y F u n ct io n s ..... .. .. ........... ................ ............... ................ ........... ....... 2 1 8
A.16 Signals .....................................................................................................219
A.17 Streams and Files ....................................................................................220
A.18 tm p f ile .... .. .. ............ ........... ........... ............... ........... ........... ........... ............ 2 21
A.19 errno ..... .. .. ................ ........... ............... ................ ............... ........... ............ 2 2 1
A.20 M e m o ry ............. ................ ........... ........... ............... ........... ........... ........... . 221
A.21 ab o rt ... .. ...... ............ ............... ........... ........... ................ ........... ........... ....... 2 2 1
A.22 ex it ....... .. ....... ........... ............... ................ ............... ................ ........... ....... 2 2 1
A.23 ge ten v ............. ............... ................ ............... ........... ................ ............... . 221
A.24 sy s te m .. .. .. ................ ........... ........... ............... ........... ........... ................ ..... 221
A.25 strer ro r ..... .. ....... ................ ............... ............... ............ ............... .............. 222
Appendix B. Diagnostics
B.1 Introduction ................................................................................................223
B.2 Errors ... .. .. ........... ........... ................ ........... ........... ........... ............... ........... . 223
B.3 Warnin gs .................. ........... ........... ........... ........... ........... ...... ........... .......... 242
Appendix C. GNU Free Documentation License
C.1 Pre a m b l e ... .. ... ........... ............... ................ ............... ........... ................ ....... 2 6 3
C.2 Applicability and Definitions .......................................................................263
C.3 Ve rb a ti m C opy ing ................. ........... ........... ........... ............... ........... .......... 265
C.4 Copying in Quantity ...................................................................................265
C.5 Mo d if ication s ....... .. ....... ........... ............... ........... ............ ............... ........... ... 2 6 6
C.6 Co m b in in g Do c ument s .................. ............... ................ ........... ............... ... 2 6 7
C.7 Co lle c tion s of D o cu ment s ... ........... ............... ........... ................ ............... ... 2 6 7
C.8 Aggregation with Independent Works ........................................................267
C.9 Tra n s la tion ............... ............... ........... ........... ........... ................ ........... ....... 2 6 8
C.10 T er m i na t io n .................. ........... ................ ........... ........... ............... ........... . 268
C.11 F ut u re R e visio n s of th is Lic e ns e ................. ................ ................... .......... 268
C.12 R e lic e n s in g ... .. ........... ........... ........... ............... ............ ........... ........... ....... 2 6 9
Appendix D. ASCII Character Set ............................................................................271
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 10 2012 Microchip Technology Inc.
Appendix E. Deprecated Features
E.1 Introduction ................................................................................................ 273
E.2 Predefined Constants ................................................................................ 273
E.3 Va ria b l e s in Spe c ified Reg i sters . ...... ................ ........... ........... ........... ........ 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
F.1 Introduction ................................................................................................ 277
F.2 Bu ilt-In F u n ct io n Desc ripti on s ..... ........... ............... ................ ........... .......... 279
Appendix G. XC16 Configuration Settings
G.1 Introduction ................................................................................................ 305
Glossary .....................................................................................................................307
Index ...........................................................................................................................327
Worldwide Sales and Service ...................................................................................338
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 11
Preface
INTRODUCTION
MPLAB XC16 C Compiler documentation and support information is discussed in the
sections below:
• Document Lay out
• Conventions Used
• Recommended Reading
• myMicrochip Personalized Notification Service
• The Microchip Web Site
• Microchip Fo rums
• Customer Support
NOTICE TO CUSTOMERS
All documentation becomes dated, and this manual is no exception. Microchip tools and documenta-
tion are constantly evolving to meet customer needs, so some actual dialogs and/or tool descriptions
may differ from those in this document.
For the most up-to-date information on development tools, see the MPLAB® IDE or MPL AB X I DE
Help. Select the Help menu and then “Topics” or “Help Contents” to open a list of available Help files.
For the most current PDFs, please refer to our web site (http://www.microchip.com). Documents are
identified by “DSXXXXXA”, where “XXXXX” is the document number and “A” is the revision level of
the document. This number is located on the bottom of each page, in front of the page number.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 12 2012 Microchip Technology Inc.
DOCUMENT LAYOUT
This document describes how to use GNU language tools to write code for 16-bit
applications. The document layout is as follows:
•Chapter 1. “Compiler Overvie w ” – describes the compiler, development tools
and feature set.
•Chapter 3. “Compiler Command-Line Driver” – describes how to use the
compiler from the command line.
•Chapter 5. “Differences Between MPLAB XC16 and ANSI C” – describes the
differences between the C language supported by the compiler syntax and the
standard ANSI-89 C.
•Chapter 4. “Device-Re lat ed Fea tures” – describes the compiler header and
register definition files, as well as how to use with SFRs.
•Chapter 6. “Supported Data Types and Variables” – describes the compiler
integer, floating point and pointer data types.
•Chapter 7. “Memory Allocation and Access” – describes the compiler run-time
model, including information on sections, initialization, memory models, the
software stack and much more.
•Chapter 8. “Operators and Statements” – discusses operators and statements.
•Chapter 9. “Registe r Usage” – explains how to access and use SFRs.
•Chapter 10. “Functions” – details available functions.
•Chapter 11. “Interr up ts” – describes how to use interrupts.
•Chapter 12. “Main, Runtime Startup and Reset” – describes important
elements of C code.
•Chapter 14. “Libr ary Routi nes” – explains how to use libraries.
•Chapter 13. “Mixing C and Assembly Code” – provides guidelines to using the
compiler with 16-bit assembly language modules.
•Chapter 15. “Opt imizat ion s” – describes optimization options.
•Chapter 16. “Prep r oces sin g” – details preprocessing operation.
•Chapter 17. “Linki ng Pr ogr ams” – explains how linking works.
•Appendix A. “Implementation-Defined Behavior” – details compiler-specific
parameters described as implementation-defined in the ANSI standard.
•Appendix B. “Diagnostics” – lists error and warning messages generated by
the compiler.
•Appendix C. “MPLAB XC16 vs. MPLAB XC8” – contains the ASCII character
set.
•Appendix C. “GNU Free Document ation License” – usage license for the Free
Software Foundation.
•Appendix E. “Deprecated Features” – details features that are considered
obsolete.
•Appendix F. “Built-in Functions” – lists the built-in functions of the C compiler.
•Appendix G. “XC16 Configuration Settings” – information about configuration
settings macros.
Preface
2012 Microchip Technology Inc. DS52071B-page 13
CONVENTIONS USED
The following conventions may appear in this documentation:
DOCUMENTATION CONVENTIONS
Description Represents Examples
Arial font:
Italic characters Referenced book s MPLAB® IDE User’s Guide
Emphasized text ...is the only comp iler ...
Initial caps A window the Output window
A dialog the Settings dialog
A menu selection select Enable Programmer
Quotes A field name in a window or
dialog “Save project before build”
Underlined, italic text with
right angle bracket A menu path File>Save
Bold characters A dialog button Click OK
A tab Click the Power tab
Text in angle brackets < > A key on the keyboard Press <Enter>, <F1>
Courier font:
Plain Courier Sample source code #define START
File names autoexec.bat
File paths c:\mcc18\h
Keywords _asm, _endasm, static
Command-line options -Opa+, -Opa-
Bit values 0, 1
Constants 0xFF, ’A’
Italic Courier A variable argument file.c, where file can be
any valid file name
Square brackets [ ] Optional arguments mpasmwin [options]
file [options]
Curly brackets and pipe
characte r: { | } Choice of mutually exclusi v e
arguments; an OR selection errorlevel {0|1}
Ellipses... Replaces repeated text var_name [,
var_name...]
Represents code supplied by
user void main (void)
{ ...
}
Sidebar Text Device Dependent.
This feature is not supported
on all devices. Devices sup-
ported will be listed in the title
or text.
xmemory attribute
DD
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 14 2012 Microchip Technology Inc.
RECOMMENDED READING
This documentation describes how to use the MPLAB XC16 C Compiler. Other useful
documents are listed below. The following Microchip documents are available and
recommended as supplemental reference resources.
Release Notes (Readme Files)
For the latest information on Microchip tools, read the associated Release Notes
(HTML files) included with the software.
MPLAB® Assembler, Linker and Utilities for PIC24 MCUs and dsPIC® DSCs
User’s Guide (DS5 1317 )
A guide to using the 16-bit assembler, object linker, object archiver/librarian and various
utilities.
16-Bit Language Tools Libraries (DS51456)
A descriptive listing of libraries available for Microchip 16-bit devices. This includes
standard (including math) libraries and C compiler built-in functions. DSP and 16-bit
peripheral libraries are described in Release Notes provided with each peripheral
library type.
Device-Specific Documentation
The Microchip website contains many documents that describe 16-bit device functions
and features. Among these are:
• Individual and family data sheets
• Family reference manuals
• Programmer’s reference manuals
C Standards Information
American National Standard for Information Systems – Programming Language – C.
American National Standards Institute (ANSI), 11 West 42nd. Street, New York,
New York, 10036.
This standard specifies the form and establishes the interpretation of programs
expressed in the programming language C. Its purpose is to promote portability,
reliabi lity, maintainabili ty and efficie nt exe cution of C language progr am s on a
variety of co mputing systems.
C Reference Manuals
Harbison, Samuel P. and Steele, Guy L., C A Reference Manual, Fourth Edition,
Prentice-Hall, Englewood Cliffs, N.J. 07632.
Kernighan, Brian W. and Ritchie, Dennis M., The C Programming Language, Second
Edition. Prentice Hall, Englewood Cliffs, N.J. 07632.
Kochan, Steven G., Programming In ANSI C, Revised Edition. Hayden Books,
Indianapolis, Indiana 46268.
Plauger, P.J., The Standard C Library, Prentice-Hal l, Eng le wood Cliffs, N.J. 07632.
Van Sickle, Ted., Programming Microcont rollers in C, First Edition. LLH Technology
Publishing, Eagle Rock, Virginia 24085.
Preface
2012 Microchip Technology Inc. DS52071B-page 15
myMICROCHIP PERSONALIZED NOTIFICATION SERVICE
Microchip's personal notification service helps keep customers current on their
Microchip products of interest. Subscribers will receive e-mail notification whenever
there are changes, updates, revisions or errata related to a specified product family or
development tool.
Please visit http://www .microchip.com/pcn to begin the registration process and select
your preferences to receive personalized notifications. A FAQ and registration details
are available on the page, which can be opened by selecting the link above.
When you are selecting your preferences, choosing “Development Systems” will pop-
ulate the list with available development tools. The main categories of tools are listed
below:
•Compilers – The lat est infor mation o n Microc hip C compil ers, as semblers , linkers
and other language tools. These include all MPLAB C compilers; all MPLAB
assemblers (including MPASM™ assembler); all MPLAB linkers (including
MPLINK™ object linker); and all MPLAB librarians (including MPLIB™ object
librarian).
•Emulators – The latest information on Microchip in-circuit emulators.These
include the MPLAB REAL ICE™ and MPLAB ICE 2000 in-circuit emulators
•In-Circuit Debuggers – The latest information on Microchip in-circuit debuggers.
These include the MPLAB ICD 2 and 3 in-circuit debuggers and PICkit™ 2 and 3
debug exp ress .
•MPLAB® IDE/MPLAB X IDE – The latest information on Microchip MPLAB IDE,
the Windows® Integrated Development Environment, or MPLAB X IDE, the open
source, cross-platform Integrated Development Environment. These lists focus on
the IDE, Project Manager, Editor and Simulator, as well as general editing and
debugging features.
•Programmers – The latest information on Microchip programmers. These include
the device (production) programmers MPLAB REAL ICE in-circuit emulator,
MPLAB ICD 3 in-circuit debugger , MPLAB PM3 and development (nonproduction)
programmers MPLAB ICD 2 in-circuit debugger, PICSTART® Plus and PICkit 2
and 3.
•St arter/Demo Boards – These include MPLAB S tarter Kit boards, PICDEM demo
boards, and various other evaluation boards.
THE MICROCHIP WEB SITE
Microchip provides online support via our web site at http://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 seminar s and even ts, listings of Microchip sales offices,
distributors and factory representatives
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 16 2012 Microchip Technology Inc.
MICROCHIP FORUMS
Microchip provides additional online support via our web forums at
http://www.microchip.com/forums. Currently available forums are:
• Developm ent Tools
•8-bit PIC MCUs
• 16-bit PIC MCUs
• 32-bit PIC MCUs
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. See our web site
for a complete, up-to-date listing of sales offices.
Technical support is available through the web site at http://support.microchip.com.
Documentation errors or comments may be emailed to docerrors@microchip.com.
DOCUMENT REVISION HISTORY
Revision A (April 2012)
Initial release of this document.
Revision B (July 2012)
•Chapter 2. “Common C Interface” was added.
• Figure 3-1 "Software Development Tools Data Flow" was updated.
• Table 3-16 "Linking Options" now includes the -fill option.
• Added the -pack_upper_byte qualifier information in
Section 6.10.4 “__pack_upper_byte Type Qualifier” and
Section 7.8 “Packing Data Stored in Flash”.
• Added DBRP AG/PSVP AG preservation bullet under Sect ion 10.8 “Fun ction Call
Conventions”
• Fixed code syntax in Section 11.4 “Specifying the Interrupt Vector”.
• Fixed Eval Editi on des cr ipti on under Chapter 15. “Optimizations”.
• Added "volatile" to SFR registers in Appendix F. “Built-in Functions”.
• Added built-in functions __builtin_write_CRYOTP and
__builtin_write_NVM_secure in Appendix F. “Built-in Functions”.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 17
Chapter 1. Compiler Overview
1.1 INTRODUCTION
The MPLAB XC16 C compiler is defined and described in the following topics:
• Device Des crip t io n
• Compiler Description and Documentation
• Compiler and Other Development Tools
1.2 DEVICE DESCRIPTION
The MPLAB XC16 C compiler fully supports all Microchip 16-bit devices:
• The dsPIC® family of digital signal controllers combines the high performance
required in digital signal processor (DSP) applications with standard microcon-
troller (MCU ) f eatu res need ed for embed ded app li cat ion s.
• The PIC24 family of MCUs are identical to the dsPIC DSCs with the exception that
they do not have the digital signal controller module or that subset of instructions.
They are a subset, and are high-performance MCUs intended for applications that
do not require the power of the DSC capabilities.
1.3 COMPILER DESCRIPTION AND DOCUMENTATION
The MPLAB XC16 C compiler is a full-featured, optimizing compiler that translates
standard ANSI C programs into 16-bit device assembly language source. The compiler
also supports many command-line options and language extensions that allow full
access to the 16-bit device hardware capabilities, and affords fine control of the com-
piler code generator.
The compiler is a port of the GNU Compiler Collection (GCC) compiler from the Free
Software Foundation
This key features of the compiler are discussed in the following sections.
1.3.1 ANSI C Standard
The compiler is a fully validated compiler that conforms to the ANSI C standard as
defined by the ANSI specification (ANSI x3.159-1989) and described in Kernighan and
Ritchie’s The C Programming Language (second edition). The ANSI standard includes
extensions to the original C definition that are now standard features of the language.
These extensions enhance portability and offer increased capability. In addition,
language extensions for dsPIC DSC embedded-control applications are included.
1.3.2 Optimization
The compiler uses a set of sophisticated optimization passes that employ many
advanced techniques for generating efficient, compact code from C source. The
optimization passes include high-level optimizations that are applicable to any C code,
as well as 16-bit devi ce - speci fi c opti mi zat ion s that take adva ntage of the particul ar
features of the device architecture.
For more on optimizations, see Chapter 15. “Optimizations”.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 18 2012 Microchip Technology Inc.
1.3.3 ANSI Standard Library Support
The compiler is distributed with a complete ANSI C standard library . All library functions
have been validated, and conform to the ANSI C library standard. The library includes
functions for string manipulation, dynamic memory allocation, data conversion, time-
keeping and math functions (trigonometric, exponential and hyperbolic). The standard
I/O functions for file handling are also included, and, as distributed, they support full
access to the host file system using the command-line simulator. The fully functional
source code for the low-level file I/O functions is provided in the compiler distribution,
and may be used as a starting point for applications that require this capability.
1.3.4 Flexible Memory Models
The compiler supports both large and small code and data models. The small code
model takes advantage of more efficient forms of call and branch instructions, while the
small data model supports the use of compact instructions for accessing data in SFR
space.
The compiler supports two models for accessing constant data. The “constants in data”
mode l u se s d a t a m em o ry, whic h i s in i ti a li ze d by th e ru n -t im e li br ary. The “c on stants i n
code” model uses program memory, which is accessed through the Program Space
Visibility (PSV) window.
1.3.5 Attributes and Qualifiers
The compiler keyword __attribute__ allows you to specify special attributes of
variables, structure fields or functions. This keyword is followed by an attribute
specification inside double parentheses, as in:
int last_mode __attribute__ ((persistent));
In other compilers, qualifiers are used to create qualified types:
persistent int last_mode;
The MPLAB XC16 C Compiler does have some non-standard qualifiers described in
Section 6.10 “Compiler-Specific type Qualifiers” .
Generally speaking, qualifiers indicate how an object should be accessed, whereas
attributes indicate where objects are to be located. Attributes also have many other
purposes.
1.3.6 Compiler Driver
The compiler includes a powerful command-line driver program. Using the driver
program, application programs can be compiled, assembled and linked in a single step.
1.3.7 Documentation
The compiler is supported under both the MPLAB IDE v8.xx and above, and the
MPLAB X IDE. For simplicity, both IDEs are referred to throughout the book as simply
MPLAB IDE.
Features that are unique to specific devices, and therefore specific compilers, are
noted with a “DD” icon next to the section and text that identifies the specific devices to
which the information applies (see the Preface).
Compiler Overview
2012 Microchip Technology Inc. DS52071B-page 19
1.4 COMPILER AND OTHER DEVELOPMENT TOOLS
The compiler works with many other Microchip tools including:
• MPLAB XC16 Assembler and Linker - see the MPLAB Assembler , Linker and Util-
ities for PIC24 MCUs and dsPIC DSCs User’s Guide (DS51317).
• MPLAB IDE v8.xx and MPLAB X IDE
• Th e MPLAB SIM Simulator and MPLAB X Simulator
• All Microchip debug tools and programmers
• Demonstration boards and Starter kits that support 16-bit devices
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 20 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 21
Chapter 2. Common C Interface
2.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. For example,
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.
The CCI assumes that your source code already conforms to the ANSI Standard. If you
intend to use the CCI, it is your responsibility to write code that conforms. Legacy proj-
ects will need to be migrated to achieve conformance. 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.
The following topics are examined in this chapter of the MPLAB XC16 C Compiler
User’s Guide:
• ANSI Standard Extensions
• Using the CCI
• ANSI Standard Refinement
• ANSI Standard Extensions
2.2 BACKGROUND – THE DESIRE FOR PORTABLE CODE
All programmers want to write portable source code.
Portability means that the same source code can be compiled and run in a different
execution environment than that for which it was written. Rarely can code be one hun-
dred percent portable, but the more tolerant it is to change, the less time and effort it
takes to have it running in a new environment.
Embedded engineers typically think of code portability as being across target devices,
but this is only part of the situation. The same code could be compiled for the same
target but with a different compiler. Differences between those compilers might lead to
the code failing at compile time or runtime, so this must be considered as well.
You may only write code for one target device and only use one brand of compiler , but
if there is no regulation of the compiler’s operation, simply updating your compiler
version may change your code’s behavior.
Code must be portable across targets, tools, and time to be truly flexible.
Clearly, this portability cannot be achieved by the programmer alone, since the com-
piler vendors can base their products on different technologies, implement different fea-
tures and code syntax, or improve the way their product works. Many a great compiler
optimization has broken many an unsuspecting project.
S tandards for the C language have been developed to ensure that change is managed
and code is more portable. The American National Standards Institute (ANSI) pub-
lishes standards for many disciplines, including programming languages. The ANSI C
Standard is a universally adopted standard for the C programming language.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 22 2012 Microchip Technology Inc.
2.2.1 The ANSI Standard
The ANSI C S tandard has to reconcile two opposing goals: freedom for compilers ven-
dors to target new devices and improve code generation, with the known functional
operation of source code for programmers. If both goals can be met, source code can
be made portable.
The standard is implemented as a set of rules which detail not only the syntax that a
conforming C program must follow, but the semantic rules by which that program will
be interpreted. Thus, for a compiler to conform to the standard, it must ensure that a
conforming C program functions as described by the standard.
The standard describes implementation, the set of tools and the runtime environment
on which the code will run. If any of these change, e.g., you build for, and run on, a dif-
ferent target device, or if you update the version of the compiler you use to build, then
you are using a different implementation.
The standard uses the term behavior to mean the external appearance or action of the
program. It has nothing to do with how a program is encoded.
Since the standard is trying to achieve goals that could be construed as conflicting,
some specifications appear somewhat vague. For example, the standard states that an
int type must be able to hold at least a 16-bit value, but it does not go as far as saying
what the size of an int actually is; and the action of right-shifting a signed integer can
produce different results on different implementations; yet, these different results are
still ANSI C compliant.
If the standard is too strict, device architectures may not allow the compiler to conform.1
But, if it is too weak, programmers would see wildly differing results within different
compilers and architectures, and the standard would loose its effectiveness.
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.
Unspecified behavior
The standard provides two or more possibilities and imposes no further requirements
on which possi bi li ty is chosen in any part ic ula r instance.
Undefined behavior
This is behavior for which the standard imposes no requirements.
Code that strictly conforms to the standard does not produce output that is dependent
on any unspecified, undefined, or implementation-defined behavior. The size of an
int, which we used as an example earlier, falls into the category of behavior that is
defined by implementation. That is to say , the size of an int is defined by which com-
piler is being used, how that compiler is being used, and the device that is being tar-
geted.
All the MPLAB XC compilers conform to the ANS X3.159-1989 Standard for program-
ming languages (with the exception of the XC8 compiler’s inability to allow recursion,
as mentioned in the footnote). This is commonly called the C89 Standard. Some fea-
tures from the later standard, C99, are also supported.
1. Case in point: The mid-range PIC® microcontrollers do not have a data stack. Because a compiler
targeting this device cannot implement recursion, it (strictly speaking) cannot conform to the ANSI
C Standard. This example illustrate a situation in which the standard is too strict for mid-range
devices and tools.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 23
For freestanding implementations – or for what we typically call embedded applications
– the standard allows non-standard extensions to the language, but obviously does not
enforce how they are specified or how they work. When working so closely to the
device hardware, a programmer needs a means of specifying device setup and inter-
rupts, as well as utilizing the often complex world of small-device memory
architectures. This cannot be offered by the standard in a consistent way.
While the ANSI C Standard provides a mutual understanding for programmers and
compiler vendors, 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. Both of these circumstances can have an impact on code por-
tability.
2.2.2 The Common C Interface
The Common C Interface (CCI) supplements the ANSI C S tandard and makes it easier
for programmers to achieve consistent outcomes on all Microchip devices when using
any of the MPLAB XC C compilers.
It delivers the following improvements, all designed with portability in mind.
Refinement of the ANSI C Standard
The CCI documents specific behavior for some code in which actions are implemen-
tation-defined behavior under the ANSI C Standard. For example, the result of
right-shifting a signed integer is fully defined by the CCI. Note that many
implementation-defined items that closely couple with device characteristics, such as
the size of an int, are not defined by the CCI.
Consistent syntax for non-standard extensions
The CCI non-standard extensions are mostly implemented using keywords with a uni-
form syntax. They replace keywords, macros and attributes that are the native com-
piler implementation. The interpretation of the keyword may differ across each com-
piler, and any arguments to the keywords may be device specific.
Coding guidelines
The CCI may indicate advice on how code should be written so that it can be ported
to other devices or compilers. While you may choose not to follow the advice, it will
not conform to the CCI.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 24 2012 Microchip Technology Inc.
2.3 USING THE CCI
The CCI allows enhanced portability by refining implementation-defined behavior and
standardizing the syntax for extensions to the language.
The CCI is something you choose to follow and put into effect, thus it is relevant for new
projects, although you may choose to modify existing projects so they conform.
For your project to conform to the CCI, you must do the following things.
Enable the CCI
Select the MPLAB IDE widget Use CCI Syntax in your project, or use the
command-line option that is equivalent.
Include <xc.h> in every module
Some CCI features are only enabled if this header is seen by the compiler.
Ensure ANSI compliance
Code that does not conform to the ANSI C Standard does not confirm to the CCI.
Observe refinements to ANSI by the CCI
Some ANSI implementation-defined behavior is defined explicitly by 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. These items are seg-
regated into those that refine the standard, those that deal with the ANSI C Standard
extensions, and other miscellaneous compiler options and usage. Guidelines are indi-
cated with th ese items.
If any implementation-defined behavior or any non-standard extension is not discussed
in this document, then it is not part of the CCI. For example, GCC case ranges, label
addresses and 24-bit short long types are not part of the CCI. Programs which use
these features do not conform to the CCI. The compiler may issue a warning or error
to indicate when you use a non-CCI feature and the CCI is enabled.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 25
2.4 ANSI STANDARD REFINEMENT
The following topics describe how the CCI refines the implementation-defined
behaviors outlined in the ANSI C Standard.
2.4.1 Source File Encoding
Under the CCI, a source file must be written using characters from the 7-bit ASCII set.
Lines may be terminated using a line feed ('\n') o r carriage return ('\r') that is immedi-
ately followed by a line fe ed . Escaped characters may be used in character constants
or string literals to represent extended characters not in the basic character set.
2.4.1.1 EXAMPLE
The following shows a string constant being defined that uses escaped characters.
const char myName[] = "Bj\370rk\n";
2.4.1.2 DIFFERENCES
All compilers have used this character set.
2.4.1.3 MIGRATION TO THE CCI
No action required.
2.4.2 The Prototype for main
The prototype for the main() function is
int main(void);
2.4.2.1 EXAMPLE
The following shows an examp le of how main() might be defined
int main(void)
{while(1)
process();
}
2.4.2.2 DIFFERENCES
The 8-bit compilers used a void return type for this function.
2.4.2.3 MIGRATION TO THE CCI
Each program has one definition for the main() function. Confirm the return type for
main() in all projects previously compiled for 8-bit targets.
2.4.3 Header File Specification
Header file specifications that use directory separators do not conform to the CCI.
2.4.3.1 EXAMPLE
The followi ng examp le sho ws two confor ming inc l ude direc ti ve s.
#include <usb_main.h>
#include "global.h"
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 26 2012 Microchip Technology Inc.
2.4.3.2 DIFFERENCES
Header file specifications that use directory separators have been allowed in previous
versions of all compilers. Compatibility problems arose when Windows-style separa-
tors “\” were used and the code compiled under other host operating systems. Under
the CCI, no directory specifiers should be used.
2.4.3.3 MIGRATION TO THE CCI
Any #include di rectives that use directory sep arators in the header file specifications
should be changed. Remove all but the header file name in the directive. Add the direc-
tory path to the compiler’s include search path or MPLAB IDE equivalent. This will force
the compiler to search the directories specified with this option.
For example, the following code:
#include <inc/lcd.h>
should be changed to:
#include <lcd.h>
and the path to the inc directory added to the compiler’s header search path in your
MPLAB IDE project properties, or on the command-line as follows:
-Ilcd
2.4.4 Include Search Paths
When you include a header file under the CCI, the file should be discoverable in the
paths searched by the compiler detailed below.
For any header files specified in angle bracket delimiters < >, the search paths should
be those specified by -I options (or the equivalent MPLAB IDE option), then the stan-
dard compiler include directories. The -I options are searched in the order in which
they are specified.
For any file specified in quote characters " ", the search paths should first be the cur-
rent working directory . In the case of an MPLAB X project, the current working directory
is the directory in which the C source file is located. If unsuccessful, the search paths
should be the same directories searched when the header files is specified in angle
bracket delimiters.
Any other options to specify search paths for header files do not conform to the CCI.
2.4.4.1 EXAMPLE
If including a header file as in the following directive
#include "myGlobals.h"
The header file should be locatable in the current working directory, or the paths spec-
ifie d b y an y -I options, or the standard compiler directories. If it is located elsewhere,
this does not conform to the CCI.
2.4.4.2 DIFFERENCES
The compiler operation under the CCI is not changed. This is purely a coding guide line.
2.4.4.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), and use the -I option in place of this. Ensure the
header file can be found in the directories specified in this section.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 27
2.4.5 The number of Significant Initial Characters in an Iden tifier
At least the first 255 characters in an identifier (internal and external) are significant.
This extends upon the requirement of the ANSI C Standard which states a lower num-
ber of significant characters are used to identify an object.
2.4.5.1 EXAMPLE
The following example shows two poorly named variables, but names which are
considered unique under the CCI.
int stateOfPortBWhenTheOperatorHasSelectedAutomaticModeAndMotorIsRunningFast;
int stateOfPortBWhenTheOperatorHasSelectedAutomaticModeAndMotorIsRunningSlow;
2.4.5.2 DIFFERENCES
Former 8-bit compilers used 31 significant characters by default, but an option allowed
this to be extended.
The 16- and 32-bit compilers did not impose a limit on the number of significant char-
acters.
2.4.5.3 MIGRATION TO THE CCI
No action required. You may take advantage of the less restrictive naming scheme.
2.4.6 Sizes of Types
The sizes of the basic C types, for example char, int and long, are not fully defined
by the CCI. These types, by design, reflect the size of registers and other architectural
features in the target device. They allow the device to efficiently access objects of this
type. The ANSI C St andard does, however, indicate minimum requirements for these
types, as specified in <limits.h>.
If you need fixed-size types in your project, use the types defined in <stdint.h>, e.g.,
uint8_t or int16_t. These types are consistently defined across all XC compilers,
even outside of the CCI.
Essentially , 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; or those that have a fixed size,
regardless of the target.
2.4.6.1 EXAMPLE
The following example shows the definition of a variable, native, whose size will allow
efficient access on the target device; and a variable, fixed, wh os e si ze is clearl y i n di -
cated and remains fixed, even though it may not allow efficient access on every device.
int native;
int16_t fixed;
2.4.6.2 DIFFERENCES
This is consistent with previous types implemented by the compiler.
2.4.6.3 MIGRATION TO THE CCI
If you require a C type that has a fixed size, regardless of the target device, use one of
the types defined by <stdint.h>.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 28 2012 Microchip Technology Inc.
2.4.7 Plain char Types
The type of a plain char is unsigned char . It is generally recommended that all def-
initions for the char type explicitly state the signedness of the object.
2.4.7.1 EXAMPLE
The following example
char foobar;
defines an unsigned char object called foobar.
2.4.7.2 DIFFERENCES
The 8-bit compilers have always treated plain char as an unsigned type.
The 16- and 32-bit compilers used signed char as the default plain char type. The
-funsigned-char option on those compilers changed the default type to be
unsigned char.
2.4.7.3 MIGRATION TO THE CCI
Any definition of an object defined as a plain char and using the 16- or 32-bit compilers
needs review. Any plain char that was intended to be a signed quantity should be
replaced with an explicit definition, for example.
signed char foobar;
You may use the -funsigned-char option on XC16/32 to change the type of plain
char, but since this option is not supported on XC8, the code is not strictly conforming.
2.4.8 Signed Integer Representation
The value of a signed integer is determined by taking the two’s complement of the inte-
ger.
2.4.8.1 EXAMPLE
The following shows a variable, test, that is assigned the value -28 decimal.
signed char test = 0xE4;
2.4.8.2 DIFFERENCES
All compilers have represented signed integers in the way described in this section.
2.4.8.3 MIGRATION TO THE CCI
No action required.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 29
2.4.9 Integer conversion
When converting an integer type to a signed integer of insufficient size, the original
value is truncated from the most-significant bit to accommodate the target size.
2.4.9.1 EXAMPLE
The following shows an assignment of a value that will be truncated.
signed char destination;
unsigned int source = 0x12FE;
destination = source;
Under the CCI, the value of destination after the alignment will be -2 (i.e., the bit
pattern 0xFE).
2.4.9.2 DIFFERENCES
All compilers have performed integer conversion in an identical fashion to that
described in this section.
2.4.9.3 MIGRATION TO THE CCI
No action required.
2.4.10 Bit-wise Operations on Signed Values
Bitwise operations on signed values act on the two’s complement representation,
including the sign bit. See also Section 2.4.11 “Right-shif ting Signed Values”.
2.4.10.1 EXAMPLE
The following shows an example of a negative quantity involved in a bitwise AND oper-
ation.
signed char output, input = -13;
output = input & 0x7E;
Under the CCI, the value of output after the assignment will be 0x72.
2.4.10.2 DIFFERENCES
All compilers have performed bitwise operations in an identical fashion to that
described in this section.
2.4.10.3 MIGRATION TO THE CCI
No action required.
2.4.11 Right-shifting Signed Values
Right-shifting a signed value will involve sign extension. This will preserve the sign of
the original value.
2.4.11.1 EXAMPLE
The following shows an example of a negative quantity involved in a bitwise AND
operation.
signed char input, output = -13;
output = input >> 3;
Under the CCI, the value of output after the assignment will be -2 (i.e., the bit pattern
0xFE).
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 30 2012 Microchip Technology Inc.
2.4.11.2 DIFFERENCES
All compilers have performed right shifting as described in this section.
2.4.11.3 MIGRATION TO THE CCI
No action required.
2.4.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 identi-
fier to try to access the contents of another (whether any conversion is applied to the
result) is implementation-defined behavior in the standard. In the CCI, no conversion is
applied and the bytes of the union object are interpreted as an object of the type of the
member being accessed, without regard for alignment or other possible invalid condi-
tions.
2.4.12.1 EXAMPLE
The following shows an example of a union defining several members.
union {
signed char code;
unsigned int data;
float offset;
} foobar;
Code that attempts to extract offset by reading data is not guaranteed to read the
correct value.
float result;
result = foobbar.data;
2.4.12.2 DIFFERENCES
All compilers have not converted union members accessed via other members.
2.4.12.3 MIGRATION TO THE CCI
No action required.
2.4.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 . This is quite different to other objects where the types int,
signed and signed int are synonymous. It is recommended that the signedness of
the bit-field be explicitly stated in all bit-field definitions.
2.4.13.1 EXAMPLE
The following shows an example of a structure tag containing bit-fields which are
unsigned integers and with the size specified.
struct OUTPUTS {
int direction :1;
int parity :3;
int value :4;
};
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 31
2.4.13.2 DIFFERENCES
The 8-bit compilers have previously issued a warning if type int was used for bit-fields,
but would implement the bit-field with an unsigned int type.
The 16- and 32-bit compilers have implemented bit-fields defined using int as having
a signed int type, unless the option -funsigned-bitfields was specified.
2.4.13.3 MIGRATION TO THE CCI
Any code that defines a bit-field with the plain int type should be reviewed. If the inten-
tion was for these to be signed quantities, then the type of these should be changed to
signed int, for example, in:
struct WAYPT {
int log :3;
int direction :4;
};
the bit-field type should be changed to signed int, as in:
struct WAYPT {
signed int log :3;
signed int direction :4;
};
2.4.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. In the CCI, bit-fields will not straddle a storage unit boundary;
a new storage unit will be allocated to the structure, and padding bits will fill the gap.
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.g., int) from which the bit-field type is derived. On 8-bit
compilers this unit is 8-bits in size; for 16-bit compilers, it is 16 bits; and for 32-bit com-
pilers, it is 32 bits in size.
2.4.14.1 EXAMPLE
The following shows a structure containing bit-fields being defined.
struct {
unsigned first : 6;
unsigned second :6;
} order;
Under the CCI and using XC8, the storage allocation unit is byte sized. The bit-field
second, will be allocated a new storage unit since there are only 2 bits remaining in
the first storage unit in which first is allocated. The size of this structure, order, will
be 2 bytes.
2.4.14.2 DIFFERENCES
This allocation is identical with that used by all previous compilers.
2.4.14.3 MIGRATION TO THE CCI
No action required.
2.4.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. In the CCI, the first bit defined will be the least significant bit of the storage
unit in which it will be allocated.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 32 2012 Microchip Technology Inc.
2.4.15.1 EXAMPLE
The following shows a structure containing bit-fields being defined.
struct {
unsigned lo : 1;
unsigned mid :6;
unsigned hi : 1;
} foo;
The bit-field lo will be assigned the least significant bit of the storage unit assigned to
the structure foo. The bit-field mid will be assigned the next 6 least significant bits, and
hi, the most significant bit of that same storage unit byte.
2.4.15.2 DIFFERENCES
This is identical with the previous operation of all compilers.
2.4.15.3 MIGRATION TO THE CCI
No action required.
2.4.16 The NULL macro
The NULL macro is defined in <stddef.h>; however, its definition is implementa-
tion-defined behavior. Under the CCI, the definition of NULL is the expression (0).
2.4.16.1 EXAMPLE
The following shows a pointer being assigned a null pointer constant via the NULL
macro.
int * ip = NULL;
The value of NULL, (0), is implicitly cast to the destination type.
2.4.16.2 DIFFERENCES
The 32-bit compilers previously assigned NULL the expression ((void *)0).
2.4.16.3 MIGRATION TO THE CCI
No action required.
2.4.17 Floating-point sizes
Under the CCI, floating-point types must not be smaller than 32 bits in size.
2.4.17.1 EXAMPLE
The following shows the definition for outY, which will be at least 32-bit in size.
float outY;
2.4.17.2 DIFFERENCES
The 8-bit compilers have allowed the use of 24-bit float and double types.
2.4.17.3 MIGRATION TO THE CCI
When using 8-bit compilers, the float and double type will automatically be made
32 bits in size once the CCI mode is enabled. Review any source code that may have
assumed a float or double type and may have been 24 bits in size.
No migration is required for other compilers.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 33
2.5 ANSI STANDARD EXTENSIONS
The following topics describe how the CCI provides device-specific extensions to the
standard.
2.5.1 Generic Header File
A single header file <xc.h> must be used to declare all compiler- and device-specific
types and SFRs. You must include this file into every module to conform with the CCI.
Some CCI definitions depend on this header being seen.
2.5.1.1 EXAMPLE
The following shows this header file being included, thus allowing conformance with the
CCI, as well as allowing access to SFRs.
#include <xc.h>
2.5.1.2 DIFFERENCES
Some 8-bit compilers used <htc.h> as the equivalent header. Previous versions of
the 16- and 32-bit compilers used a variety of headers to do the same job.
2.5.1.3 MIGRATION TO THE CCI
Change:
#include <htc.h>
used previously in 8-bit compiler code, or family-specific header files as in the following
examples:
#include <p32xxxx.h>
#include <p30fxxxx.h>
#include <p33Fxxxx.h>
#include <p24Fxxxx.h>
#include "p30f6014.h"
to:
#include <xc.h>
2.5.2 Absolute addressing
Variables and functions can be placed at an absolute address by using the __at()
construct.qualifier Note that XC16/32 may require the variable or function to be placed
in a special section for absolute addressing to work. Stack-based (auto and parame-
ter) variables cannot use the __at() specifier.
2.5.2.1 EXAMPLE
The following shows two variables and a function being made absolute.
int scanMode __at(0x200);
const char keys[] __at(123) = { ’r’, ’s’, ’u’, ’d’};
int modify(int x) __at(0x1000) {
return x * 2 + 3;
}
2.5.2.2 DIFFERENCES
The 8-bit compilers have used an @ symbol to specify an absolute address.
The 16- and 32-bit compilers have used the address attribute to specify an object’s
address.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 34 2012 Microchip Technology Inc.
2.5.2.3 MIGRATION TO THE CCI
Avoid making objects and functions absolute if possible.
In XC8, change absolute object definitions such as the following example:
int scanMode @ 0x200;
to:
int scanMode __at(0x200);
In XC16/32, change code such as:
int scanMode __attribute__(address(0x200)));
to:
int scanMode __at(0x200);
2.5.2.4 CAVEATS
If the __at() and __section() specifiers are both applied to an object when using
XC8, the __section() specifier is currently ignored.
2.5.3 Far Objects and Functions
The __far qualifier may be used to indicate that variables or functions may be located
in ‘far memory’. Exactly what constitutes far memory is dependent on the target device,
but it is typically memory that requires more complex code to access. Expressions
involving far-qualified objects may generate slower and larger code.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this qualifier.
Some devices may not have such memory implemented, in which case, use of this
qualifier will be ignored. Stack-based (auto and parameter) variables cannot use the
__far specifier.
2.5.3.1 EXAMPLE
The following shows a variable and function qualified using __far.
__far int serialNo;
__far int ext_getCond(int selector);
2.5.3.2 DIFFERENCES
The 8-bit compilers have used the qualifier far to indicate this meaning. Functions
could not be qualified as far.
The 16-bit compilers have used the far attribute with both variables and functions.
The 32-bit compilers have used the far attribute with functions, only.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 35
2.5.3.3 MIGRATION TO THE CCI
For 8-bit compilers, change any occurrence of the far qualifie r, as in the foll owi ng
example:
far char template[20];
to __far, i.e., __far char template[20];
In the 16- and 32-bit compilers, change any occurrence of the far attribute, as in the
following
void bar(void) __attribute__ ((far));
int tblIdx __attribute__ ((far));
to
void __far bar(void);
int __far tblIdx;
2.5.3.4 CAVEATS
None.
2.5.4 Near Objects
The __near qualifier may be used to indicate that variables or functions may be
located in ‘near memory’. Exactly what constitutes near memory is dependent on the
target device, but it is typically memory that can be accessed with less complex code.
Expressions involving near-qualified objects may be faster and result in smaller code.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this qualifier.
Some devices may not have such memory implemented, in which case, use of this
qualifier will be ignored. Stack-based (auto and parameter) variables cannot use the
__near specifier.
2.5.4.1 EXAMPLE
The following shows a variable and function qualified using __near.
__near int serialNo;
__near int ext_getCond(int selector);
2.5.4.2 DIFFERENCES
The 8-bit compilers have used the qualifier near to indicate this meaning. Functions
could not be qualified as near.
The 16-bit compilers have used the near attribute with both variables and functions.
The 32-bit compilers have used the near attribute for functions, only.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 36 2012 Microchip Technology Inc.
2.5.4.3 MIGRATION TO THE CCI
For 8-bit compilers, change any occurrence of the near qualifier, as in the following
example:
near char template[20];
to __near, i.e., __near char template[20];
In 16- and 32-bit compilers, change any occurrence of the near attribute, as in the fol-
lowing
void bar(void) __attribute__ ((near));
int tblIdx __attribute__ ((near));
to
void __near bar(void);
int __near tblIdx;
2.5.4.4 CAVEATS
None.
2.5.5 Persistent Objects
The __persistent qualifier may be used to indicate that variables should not be
cleared by the runtime startup code.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this qualifier.
2.5.5.1 EXAMPLE
The following shows a variable qualified using __persistent.
__persistent int serialNo;
2.5.5.2 DIFFERENCES
The 8-bit compilers have used the qualifier, persistent, to indicate this meaning.
The 16- and 32-bit compilers have used the persistent attribute with variables to
indicate they were not to be cleared.
2.5.5.3 MIGRATION TO THE CCI
With 8-bit compilers, change any occurrence of the persistent qualifier , as in the fol-
lowing example:
persistent char template[20];
to __persistent, i.e., __persistent char template[20];
For the 16- and 32-bit compilers, change any occurrence of the persistent attribute,
as in the following
int tblIdx __attribute__ ((persistent));
to
int __persistent tblIdx;
2.5.5.4 CAVEATS
None.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 37
2.5.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. Exactly what constitutes X and Y memory is depen-
dent on the target device, but it is typically memory that can be accessed independently
on separate buses. Such memory is often required for some DSP instructions.
Use the native keywords discussed in the Differences section to look up information on
the semantics of these qualifiers.
Some devices may not have such memory implemented; in which case, use of these
qualifiers will be ignored.
2.5.6.1 EXAMPLE
The following shows a variable qualified using __xdata, as well as another variable
qualified with __ydata.
__xdata char data[16];
__ydata char coeffs[4];
2.5.6.2 DIFFERENCES
The 16-bit compilers have used the xmemory and ymemory space attribute with
variables.
Equivalent specifiers have never been defined for any other compiler.
2.5.6.3 MIGRATION TO THE CCI
For 16-bit compilers, change any occurrence of the space attributes xmemory or
ymemory, as in the following example:
char __attribute__((space(xmemory)))template[20];
to __xdata, or __ydata, i.e., __xdata char template[20];
2.5.6.4 CAVEATS
None.
2.5.7 Banked Data Objects
The __bank(num) qualifier may be used to indicate that variables may be located in
a particular data memory bank. The number , num, represents the bank number . Exactly
what constitutes banked memory is dependent on the target device, but it is typically a
subdivision of data memory to allow for assembly instructions with a limited address
width field.
Use the native keywords discussed in the Differences section to look up information on
the semantics of these qualifiers.
Some devices may not have banked data memory implemented, in which case, use of
this qualifier will be ignored. The number of data banks implemented will vary from one
device to another.
2.5.7.1 EXAMPLE
The following shows a variable qualified using __bank().
__bank(0) char start;
__bank(5) char stop;
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 38 2012 Microchip Technology Inc.
2.5.7.2 DIFFERENCES
The 8-bit compil ers ha ve used the fo ur qua lifie rs bank0, bank1, bank2 and bank3 to
indicate the same, albeit more limited, memory placement.
Equivalent specifiers have never been defined for any other compiler.
2.5.7.3 MIGRATION TO THE CCI
For 8-bit compilers, change any occurrence of the bankx qualifiers, as in the following
example:
bank2 int logEntry;
to __bank(, i.e., __bank(2) int logEntry;
2.5.7.4 CAVEATS
None.
2.5.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. The align-
ment term must be a power of two. Positive values request that the object’s start
address be aligned; negative values imply the object’s end address be aligned.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this specifier.
2.5.8.1 EXAMPLE
The following shows variables qualified using __align() to ensure they end on an
address that is a multiple of 8, and start on an address that is a multiple of 2,
respectively.
__align(-8) int spacer;
__align(2) char coeffs[6];
2.5.8.2 DIFFERENCES
An alignment feature has never been implemented on 8-bit compilers.
The 16- and 32-bit compilers used the aligned attribute with variables.
2.5.8.3 MIGRATION TO THE CCI
For 16- and 32-bit compilers, change any occurrence of the aligned attribute, as in
the following example:
char __attribute__((aligned(4)))mode;
to __align, i.e., __align(4) char mode;
2.5.8.4 CAVEATS
This feature is not yet implemented on XC8.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 39
2.5.9 EEPROM Objects
The __eeprom quali fier may be used to in dicate tha t variab les shoul d be posit ioned in
EEPROM.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this qualifier.
Some devices may not implement EEPROM. Use of this qualifier for such devices will
generate a warning. Stack-based (auto and parameter) variables cannot use the
__eeprom specifier.
2.5.9.1 EXAMPLE
The following shows a variable qualified using __eeprom.
__eeprom int serialNos[4];
2.5.9.2 DIFFERENCES
The 8-bit compilers have used the qualifier , eeprom, to indicate this meaning for some
devices.
The 16-bit compilers have used the space attribute to allocate variables to the memory
space used for EEPROM.
2.5.9.3 MIGRATION TO THE CCI
For 8-bit compilers, change any occurrence of the eeprom qualifier , as in the following
example:
eeprom char title[20];
to __eeprom, i.e., __eeprom char title[20];
For 16-bit compilers, change any occurrence of the eedata space attribute, as in the
following
int mainSw __attribute__ ((space(eedata)));
to
int __eeprom mainSw;
2.5.9.4 CAVEATS
XC8 does not implement the __eeprom qualifiers for any PIC18 devices; this qualifier
will work as expected for other 8-bit devices.
2.5.10 Interrupt Functions
The __interrupt(type) specifier may be used to indicate that a function is to act
as an interrupt service routine. The type is a comma-separated list of keywords that
indicate information about the interrupt function.
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)
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 40 2012 Microchip Technology Inc.
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.
Some devices may not implement interrupts. Use of this qualifier for such devices will
generate a warning. If the argument to the __interrupt specifier does not make
sense for the target device, a warning or error will be issued by the compiler.
2.5.10.1 EXAMPLE
The following shows a function qualified using __interrupt.
__interrupt(low_priority) void getData(void) {
if (TMR0IE && TMR0IF) {
TMR0IF=0;
++tick_count;
}
}
2.5.10.2 DIFFERENCES
The 8-bit compilers have used the interrupt and low_priority qualifiers to indi-
cate this meaning for some devices. Interrupt routines were by default high priority.
The 16- and 32-bit compilers have used the interrupt attribute to define interrupt
functions.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 41
2.5.10.3 MIGRATION TO THE CCI
For 8-bit compilers, change any occurrence of the interrupt qualifier, as in the
following examples:
void interrupt myIsr(void)
void interrupt low_priority myLoIsr(void)
to the following, respectively
void __interrupt(high_priority) myIsr(void)
void __interrupt(low_priority) myLoIsr(void)
For 16-bit compilers, change any occurrence of the interrupt attribute, as in the fol-
lowing example:
void __attribute__((interrupt,auto_psv,(irq(52)))) myIsr(void);
to
void __interrupt(auto_psv,(irq(52)))) myIsr(void);
For 32-bit compilers, the __interrupt() keyword takes two parameters, the vector
number and the (optional) IPL value. Change code which uses the interrupt attri-
bute, similar to these examples:
void __attribute__((vector(0), interrupt(IPL7AUTO), nomips16))
myisr0_7A(void) {}
void __attribute__((vector(1), interrupt(IPL6SRS), nomips16))
myisr1_6SRS(void) {}
/* Determine IPL and context-saving mode at runtime */
void __attribute__((vector(2), interrupt(), nomips16))
myisr2_RUNTIME(void) {}
to
void __interrupt(0,IPL7AUTO) myisr0_7A(void) {}
void __interrupt(1,IPL6SRS) myisr1_6SRS(void) {}
/* Determine IPL and context-saving mode at runtime */
void __interrupt(2) myisr2_RUNTIME(void) {}
2.5.10.4 CAVEATS
None.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 42 2012 Microchip Technology Inc.
2.5.11 Packing Objects
The __pack spec if i er ma y be us ed t o i n di cat e t h at s tr uc t ur es should not us e m em o ry
gaps to align structure members, or that individual structure members should not be
aligned.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this specifier.
Some compilers may not pad structures with alignment gaps for some devices and use
of this specifier for such devices will be ignored.
2.5.11.1 EXAMPLE
The following shows a structure qualified using __pack as well as a structure where
one member has been explicitly packed.
__pack struct DATAPOINT {
unsigned char type;
int value;
} x-point;
struct LINETYPE {
unsigned char type;
__pack int start;
long total;
} line;
2.5.11.2 DIFFERENCES
The __pack specifier is a new CCI specifier available with XC8. This specifier has no
apparent effect since the device memory is byte addressable for all data objects.
The 16- and 32-bit compilers have used the packed attrib ute to indica te t hat a struc-
ture member was not aligned with a memory gap.
2.5.11.3 MIGRATION TO THE CCI
No migration is required for XC8.
For 16- and 32-bit compilers, change any occurrence of the packed attribute, as in the
following example:
struct DOT
{char a;
int x[2] __attribute__ ((packed));
};
to:
struct DOT
{char a;
__pack int x[2];
};
Alternatively, you may pack the entire structure, if required.
2.5.11.4 CAVEATS
None.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 43
2.5.12 Indicating Antiquated Objects
The __deprecate specifier may be used to indicate that an object has limited longev-
ity and should not be used in new designs. It is commonly used by the compiler vendor
to indicate that compiler extensions or features may become obsolete, or that better
features have been developed and which should be used in preference.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this specifier.
2.5.12.1 EXAMPLE
The following shows a function which uses the __deprecate keyword.
void __deprecate getValue(int mode)
{
//...
}
2.5.12.2 DIFFERENCES
No deprecate feature was implemented on 8-bit compilers.
The 16- and 32-bit compilers have used the deprecated attribute (note different spell-
ing) to indicate that objects should be avoided if possible.
2.5.12.3 MIGRATION TO THE CCI
For 16- and 32-bit compilers, change any occurrence of the deprecated attribute, as
in the following example:
int __attribute__(deprecated) intMask;
to:
int __deprecate intMask;
2.5.12.4 CAVEATS
None.
2.5.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, using the XC8 terminology). This is typically used when
the object has special and unique linking requirements which cannot be addressed by
existing compiler features.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this specifier.
2.5.13.1 EXAMPLE
The following shows a variable which uses the __section keyword.
int __section("comSec") commonFlag;
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 44 2012 Microchip Technology Inc.
2.5.13.2 DIFFERENCES
The 8-bit compilers have used the #pragma psect directive to redire ct obje cts to a
new section, or psect. The operation of the __section() specifier is different to this
pragma in several ways, described below.
Unlike with the pragma, the new psect created with __section() does not inherit the
flags of the psect in which the object would normally have been allocated. This means
that the new psect can be linked in any memory area, including any data bank. The
compiler will also make no assumptions about the location of the object in the new sec-
tion. Objects redirected to new psects using the pragma must always be linked in the
same memory area, albeit at any address in that area.
The __section() specifier allows objects that are initialized to be placed in a different
psect. Initialization of the object will still be performed even in the new psect. 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), which will contain the initial values. The
pragma cannot be used with objects that are initialized.
Objects allocated a different psect with __section() will be cleared by the runtime
startup code, unlike objects which use the pragma.
Y ou must reserve memory , and locate via a linker option, for any new psect created with
a __section() specifier in the current XC8 compiler implementation.
The 16- and 32-bit compilers have used the section attribute to indicate a different
destination section name. The __section() specifier works in a similar way to the
attribute.
2.5.13.3 MIGRATION TO THE CCI
For XC8, change any occurrence of the #pragma psect directive, such as
#pragma psect text%%u=myText
int getMode(int target) {
//...
}
to the __section() specifier, as in
int __section ("myText") getMode(int target) {
//...
}
For 16- and 32-bit compilers, change any occurrence of the section attribute, as in
the following example:
int __attribute__((section("myVars"))) intMask;
to:
int __section("myVars") intMask;
2.5.13.4 CAVEATS
With XC8, the __section() specifier cannot be used with any interrupt function.
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 45
2.5.14 Specifying Configuration Bits
The #pragma config directive may be used to program the configuration bits for a
device. The pragma has the form:
#pragma config setting = state|value
#pragma config register = value
where setting is a configuration setting descriptor (e.g., WDT), state is a descriptive
value (e.g., ON) and value is a numerical value. The register token may represent a
whole config ur ati on word reg ister, e.g., CONFIG1L.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this directive.
2.5.14.1 EXAMPLE
The following shows configuration bits being specified using this pragma.
#pragma config WDT=ON, WDTPS = 0x1A
2.5.14.2 DIFFERENCES
The 8-bit compilers have used the __CONFIG() macro for some targets that did not
already have support for the #pragma config .
The 16-bit compilers have used a number of macros to specify the configuration set-
tings.
The 32-bit compilers supported the use of #pragma config .
2.5.14.3 MIGRATION TO THE CCI
For the 8-bit compilers, change any occurrence of the __CONFIG() macro, such as
__CONFIG(WDTEN & XT & DPROT)
to the #pragma config directive, as in
#pragma config WDTE=ON, FOSC=XT, CPD=ON
No migration is required if the #pragma config was already used.
For the 16-bit compilers, change any occurrence of the _FOSC() or _FBORPOR()
macros attribute, as in the following example:
_FOSC(CSW_FSCM_ON & EC_PLL16);
to:
#pragma config FCKSMEM = CSW_ON_FSCM_ON, FPR = ECIO_PLL16
No migration is required for 32-bit code.
2.5.14.4 CAVEATS
None.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 46 2012 Microchip Technology Inc.
2.5.15 Manifest Macros
The CCI defines the general form for macros that manifest the compiler and target
device characteristics. These macros can be used to conditionally compile alternate
source code based on the compiler or the target device.
The macros and macro families are details in Table 2-1.
2.5.15.1 EXAMPLE
The following shows code which is conditionally compiled dependent on the device
having EEPROM memory.
#ifdef __XC16__
void __interrupt(__auto_psv__) myIsr(void)
#else
void __interrupt(low_priority) myIsr(void)
#endif
2.5.15.2 DIFFERENCES
Some of these CCI macros are new (for example __CCI__), and others have different
names to previous symbols with identical meaning (for example __18F452 is now
__18F452__).
2.5.15.3 MIGRATION TO THE CCI
Any code which uses compiler-defined macros will need review. Old macros will con-
tinue to work as expected, but they are not compliant with the CCI.
2.5.15.4 CAVEATS
None.
TABLE 2-1: MANIFEST MACROS DEFINED BY THE CCI
Name Meaning if defined Example
__XC__ Compiled with an MPLAB XC compiler __XC__
__CCI__ Compiler is CCI compliant and CCI enforce-
ment is enabled __CCI__
__XC##__ The spe cific XC co mp iler u sed (## c an be 8,
16 or 32)__XC8__
__DEVICEFAMILY__ The family of the selected target device __dsPIC30F__
__DEVICENAME__ The selected target device name __18F452__
Common C Interface
2012 Microchip Technology Inc. DS52071B-page 47
2.5.16 In-line Assembly
The asm() statement may be used to insert assembly code in-line with C code. The
argument is a C string literal which represents a single assembly instruction. Obviously ,
the instructions contained in the argument are device specific.
Use the native keywords discussed in the Differences section to look up information on
the semantics of this statement.
2.5.16.1 EXAMPLE
The following shows a MOVLW instruction being inserted in-line.
asm("MOVLW _foobar");
2.5.16.2 DIFFERENCES
The 8-bit compilers have used either the asm() or #asm ... #endasm constructs to
insert in-line assembly code.
This is the same syntax used by the 16- and 32-bit compilers.
2.5.16.3 MIGRATION TO THE CCI
For 8-bit compilers change any instance of #asm ... #endasm so that each instruction
in this #asm block is placed in its own asm() statement, for example:
#asm
MOVLW 20
MOVWF _i
CLRF Ii+1
#endasm
to
asm("MOVLW20");
asm("MOVWF _i");
asm("CLRFIi+1");
No migration is required for the 16- or 32-bit compilers.
2.5.16.4 CAVEATS
None.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 48 2012 Microchip Technology Inc.
2.6 COMPILER FE ATURES
The following items detail compiler options and features that are not directly associated
with source code that
2.6.1 Enabling the CCI
It is assumed you are using the MPLAB X IDE to build projects that use the CCI. The
widget in the MPLAB X IDE Project Properties to enable CCI conformance is Use CCI
Syntax in the Compiler category. A widget with the same name is available in MPLAB
IDE v8 under the Compiler tab.
If you are not using this IDE, then the command-line options are --CCI for XC8 or
-mcci for XC16/32.
2.6.1.1 DIFFERENCES
This option has never been implemented previously.
2.6.1.2 MIGRATION TO THE CCI
Enable the option.
2.6.1.3 CAVEATS
None.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 49
Chapter 3. Compiler Command-Line Driver
3.1 INTRODUCTION
The compiler command-line driver (xc16-gcc) is the application that invokes the oper-
ation of the MPLAB XC16 C Compiler . The driver compiles, assembles and links C and
assembly language modules and library archives. Most of the compiler command-line
options are common to all implementations of the GCC toolset. A few are specific to
the compiler and will be discussed below.
The compiler driver also may be used with MPLAB IDE. Compiler options are selected
in the GUI and passed to the compiler driver for execution.
Topics concerning the command-line use of the driver are discussed below. For more
on how to use the compiler with MPLAB IDE, please refer to the MPLAB Assembler,
Linker and Utilities for PIC24 MCUs and dsPIC DSCs User’s Guide (DS51317).
• Invoking the Compiler
• The Compilation Sequence
• Runtime Files
• Compiler Output
• Compiler Messages
• Driver Option Descriptions
• MPLAB IDE Toolsuite Equivalents
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 50 2012 Microchip Technology Inc.
3.2 INVOKING THE COMPILER
The compiler is invoked and run on the command line as specified in the next section.
Additionally, environmental variables and input files used by the compiler are discussed
in the following sections.
3.2.1 Drive Command-Line Format
The basic form of the compiler command line is:
xc16-gcc [options] files
where:
options: See Section 3.7 “Driver Option Descriptions” for available options.
files: See Section 3.2.3 “Input File Types” for details.
It is assumed in this manual that the compiler applications are either in the console’s
search path, see Section 3.2.2 “Environment V ariables”, or the full path is specified
when executing any application.
It is conventional to supply options (identified by a leading dash “-”) before the file
names, although this is not mandatory.
The files may be any mixture of C and assembler source files, and precompiled inter-
mediate files, such as relocatable object (.o) files. The order of the files is not impor-
tant, except that it may affect the order in which code or data appears in memory.
For example, to compile, assemble and link the C source file hello.c, creating a relo-
catable object output, hello.out.
xc16-gcc -mcpu=30f2010 -o hello.out hello.c
3.2.2 Environment Variables
The variables in this section are optional, but, if defined, they will be used by the
compiler. The compiler driver, or other subprogram, may choose to determine an
appropriate value for some of the following environment variables if they are unset. The
driver, or other subprogram, takes advantage of internal knowledge about the
installation of the compiler. As long as the installation structure remains intact, with all
subdirectories and executables remaining in the same relative position, the driver or
subprogram will be able to determine a usable value.
Note: Command line options and file name extensions are case-sensitive.
TABLE 3-1: COMPILER-RELATED ENVIRONMENTAL VARIABLES
Variable Definition
XC16_C_INCLUDE_P
ATH
PIC30_C_INCLUDE_
PATH
This var iab le’ s val ue is a sem icolo n-sep arate d list of dir ectorie s, muc h
like PATH. When the compiler searches for header files, it tries the
directories listed in the variable, after the directories specified with -I
but before the standard header file directories.
If the envir onm ent variab le is und efined , the pr eprocess or choos es an
appropriate value based on the standard installation. By default, the
following directories are searched for include files:
<install-path>\include and
<install-path>\support\h
XC16_COMPILER_
PATH
PIC30_COMPILER_
PATH
The value of t he variab le is a semicolon-separated list of directories,
much like PATH. The com pile r tries the di rectori es th us sp ecifi ed when
searching for subprograms, if it can’t find the subprograms using
PIC30_EXEC_PREFIX.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 51
3.2.3 Input File Types
The compilation driver distinguishes source files, intermediate files and library files
solely by the file type, or extension. It recognizes the following file extensions, which
are case-sensitive.
There are no compiler restrictions imposed on the names of source files, but be aware
of case, name-length and other restrictions imposed by your operating system. If you
are using an IDE, avoid assembly source files whose basename is the same as the
basename of any project in which the file is used. This may result in the source file
being overwritten by a temporary file during the build process.
The terms “source file” and “module” are often used when talking about computer
programs. They are often used interchangeably, but they refer to the source code at
different points in the compilation sequence.
XC16_EXEC_
PREFIX
PIC30_EXEC_
PREFIX
If the environment variable is set, it specifies a prefix to use in the
nam es of subpr ograms executed by the compiler. No d irectory
delimiter is added when this prefix is combined with the name of a
subprogram, but you can specify a prefix that ends with a slash if you
wish. If the compiler cannot find the subprogram using the specified
prefix, it tries looking i n your PATH environment va riable.
If the environment variable is not set or set to an empty value, the
compiler driver chooses an appropriate value based on the standard
installation. If the installation has not been modified, this will result in
the driver being able to lo cate the required subprograms .
Other prefixes specified with the -B command line option take
precedence over the user- or driver-defined value of the variable.
Under normal circumstances it is best to leave this value undefined
and let the driver locate subprograms itself.
XC16_LIBRARY_
PATH
PIC30_LIBRARY_
PATH
This vari able’ s value i s a sem icolon-s ep arate d list of direct orie s, much
like PATH. This variable specifies a list of directories to be passed to
the linker. The driver’s default evaluation of this variable is:
<install-path>\lib; <install-path>\support\gld.
XC16_OMF
PIC30_OMF S pe cifies the OMF (Object Module Format) to be us ed by the compiler .
By default, the tools create ELF object files. If the environment
variabl e ha s the va lue coff, the tools will create COFF object files.
TMPDIR If the variable is set, it specifies the directory to use for temporary files.
The compiler uses temporary files to hold the output of one stage of
compilation that is to be used as input to the next stage: for example,
the output of the preprocessor, which is the input to the compiler
proper.
TABLE 3-2: FILE NAMES
Extensions Definition
file.c A C so urce file tha t must be prep rocessed.
file.h A header file (not to be compiled or linked).
file.i A C source file that should not be preprocessed.
file.o An object file.
file.p A pre procedural-abstraction assembly language file.
file.s Asse mb ler co de.
file.S Assemb ler code that must be prep roc ess ed.
other A file to be passed to the linker.
TABLE 3-1: COMPILER-RELATED ENVIRONMENTAL VARIABLES
Variable Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 52 2012 Microchip Technology Inc.
A source file is a file that contains all or part of a program. Source files are initially
passed to the preprocessor by the driver.
A module is the output of the preprocessor, for a given source file, after inclusion of any
header files (or other source files) which are specified by #include preprocessor
directives. These modules are then passed to the remainder of the compiler applica-
tions. Thus, a module may consist of several source and header files. A module is also
often referred to as a translation unit. These terms can also be applied to assembly
files, as they too can include other header and source files.
3.3 THE COMPILATION SEQUENCE
How the compiler operates with other applications and how to perform different types
of compilations is discussed in the following sections.
3.3.1 The Compiler Applicati ons
The MPLAB XC16 C Compiler compiles C source files, producing assembly language
files. These compiler-generated files are assembled and linked with other object files
and libraries to produce the final application program in executable ELF or COFF file
format. The ELF or COFF file can be loaded into the MPLAB IDE, where it can be
tested and debugged, or the conversion utility can be used to convert the ELF or COFF
file to Intel® hex format, suitable for loading into the command-line simulator or a device
programmer. See Figure 3-1 for an overview of the software development data flow.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 53
FIGURE 3-1: SOFTWARE DEVELOPMENT TOOLS DATA FLOW
The driver program will call the required internal compiler applications. These applica-
tions are shown as the smaller boxes inside the large driver box. The temporary file pro-
duced by each application can also be seen in this diagram.
Table 3-3 lists the compiler applications. The names shown are the names of the exe-
cutables, which can be found in the bin directory under the compiler’s installation
directory. Your PATH environment variable should include this directory.
Object File Libraries
(*.a)
Assembler
Linker
C Source Files
(*.c)
C Compiler
Assembly Source
File s (*.S)
Debug File
(*.cof,*.elf)
Archiver (Librarian)
Compiler
Driver
Program
MPLAB® X IDE
Debug Tool
Source Files (*.s)
Object Files
(*.o)
Command-Line
Simulator
Linker Script File(1)
(*.ld)
Executable File
(*.hex) MPLAB X IDE
Programmer
bin2hex Utility
Output File
(*.out)
Note 1: The linker can choose the correct linker script file for your project.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 54 2012 Microchip Technology Inc.
3.3.2 Single-Step Compilati on
A single command-line instruction can be used to compile one file or multiple files.
3.3.2.1 COMPILING A SINGLE FILE
This section demonstrates how to compile and link a single file. For the purpose of this
discussion, it is assumed the compiler is installed in the standard directory location and
that your P A TH or other environment variables (see Section 3.2.2 “Environment V ari-
ables”) are set up in such a way that the full compiler path need not be specified when
you run the compiler.
The following is a simple C program that adds two numbers.
Create the following program with any text editor and save it as ex1.c.
#include <xc.h>
int main(void);
unsigned int Add(unsigned int a, unsigned int b);
unsigned int x, y, z;
int
main(void)
{
x = 2;
y = 5;
z = Add(x,y);
return 0;
}
unsigned int
Add(unsigned int a, unsigned int b)
{
return(a+b);
}
The first line of the program includes the header file xc.h, which will include the appro-
priate header files that provides definitions for all special function registers on the target
device. For more information on header files, see Section 4.3 “Device Header Files”.
Compile the program by typing the following at the prompt in your favorite terminal.
xc16-gcc -mcpu=30f2010 -o ex1.out ex1.c
The command-line option -o ex1.out names the output executable file (if the -o
option is not specified, then the output file is named a.out). The executable file may
be loaded into the MPLAB IDE.
TABLE 3-3: COMPILER APPLICATION NAMES
Name Description
xc16-gcc Command line driver; the interface to the compiler
xc16-cc1 Code generator (elf by default)
xc16-as Assembler (based on the target device)
xc16-ld Linker
xc16-bin2hex Conversion utility to create HEX files
xc16-strings String extractor utility
xc16-strip Symbol stripper utility
xc16-nm Symbol list utility
xc16-ar Archiver/Librarian
xc16-objdump Object file display utility
xc16-ranlib Archive indexer utility
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 55
If a hex file is required, for example, to load into a device programmer, then use the
following command:
xc16-bin2hex ex1.out
This creates an Intel hex file named ex1.hex.
3.3.2.2 COMPILING MULTIPLE FILES
Move the Add() function into a file called add.c to demonstrate the use of multiple
files in an application. That is:
File 1
/* ex1.c */
#include <xc.h>
int main(void);
unsigned int Add(unsigned int a, unsigned int b);
unsigned int x, y, z;
int main(void)
{
x = 2;
y = 5;
z = Add(x,y);
return 0;
}
File 2
/* add.c */
#include <xc.h>
unsigned int
Add(unsigned int a, unsigned int b)
{
return(a+b);
}
Compile both files in the one command by typing the following in your terminal program.
xc16-gcc -mcpu=30f2010 -o ex1.out ex1.c add.c
This command compiles the modules ex1.c and add.c. The compiled modules are
linked with the compiler libraries and the executable file ex1.out is created.
3.3.3 Multi -Step Compilation
Make utilities and integrated development environments, such as MPLAB IDE, allow
for an incremental build of projects that contain multiple source files. When building a
project, they take note of which source files have changed since the last build and use
this information to speed up compilation.
For example, if compiling two source files, but only one has changed since the last
build, the intermediate file corresponding to the unchanged source file need not be
regenerated.
If the compiler is being invoked using a make utility, the make file will need to be con-
figured to recognized the different intermediate file format and the options used to gen-
erate the intermediate files. Make utilities typically call the compiler multiple times: once
for each source file to generate an intermediate file, and once to perform the second
stage compi lat ion .
You may also wish to generate intermediate files to construct your own library files,
although xc16-gcc is capable of constructing libraries so this is typically not neces-
sary. See MPLAB Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs
User’s Guide (DS5131 7) for more information on library creation.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 56 2012 Microchip Technology Inc.
For example, the files ex1.c and add.c are to be compiled using a make utility. The
command lines that the make utility should use to compile these files might be some-
thing like:
xc16-gcc -mcpu=30f6014 -c ex1.c
xc16-gcc -mcpu=30f6014 -c add.c
xc16-gcc -mcpu=30f6014 -o ex1 ex1.o add.o
The -c option will compile the named file into the intermediate (object) file format, but
not link. Once all files are compiled as specified by the make, then the resultant object
files are linked in the final step to create the final output ex1. The above example uses
the command-line driver, xc16-gcc, to perform the final link step. You can explicitly
call the linker application, xc16-ld, but this is not recommended. When driving the linker
application, you must specify linker options, not driver options. For more on using the
linker, see MPLAB Asse mbl er, Linker and Util it ies for PIC24 MCUs and ds PIC DSCs
User’s Guide (DS5131 7) .
When compiling debug code, the object module format (OMF) must be consistent for
compilation, assembly and linking. The ELF/DW ARF format is used by default but the
COFF format may also be selected using -omf=coff or the environmental variable
XC16_OMF.
3.3.4 Assembly Compilation
A mix of C and assembly code can be compiled together using the compiler
(Figure 3-1). For more details, see Chapter 13. “Mixing C and Assembly Code”.
Additionally, the compiler may be used to generate assembly code (.s) from C code
(.c) using the -S option. The assembly output may then be used in subsequent com-
pilation using the command-line driver.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 57
3.4 RUNTIME FILES
The compiler uses the following files in addition to source, linker and header files.
3.4. 1 Libr a ry F ile s
The compiler may include library files into the output per Figure 3-1.
By default, xc16-gcc will search directories under the compiler installation directory
for library files that are required during compilation.
3.4.1.1 STANDARD LIBRARIES
The C standard libraries contain a standardized collection of functions, such as string,
math and input/output routines. The range of these functions are described in the
“16-Bit Language Tool Libraries” (DS 5 1 4 56).
3.4.1.2 USER-DEFINED LIBRARIES
Users may create their own libraries. Libraries are useful for bundling and precompiling
selected functions so that application file management is easier and application com-
pilation times are shorter.
Libraries can be created manually using the compiler and the librarian. To create files
that may then be used as input to the 16-bit librarian (xc16-ar), use th e -c compiler
option to stop compilation before the linker stage. For information on using the librarian,
see the MPLAB Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs
User’s Guide (DS5131 7) .
User-created libraries that should be searched when building a project can be listed on
the command line along with the source files.
As with Standard C library functions, any functions contained in user-defined libraries
should have a declaration added to a header file. It is common practice to create one
or more header files that are packaged with the library file. These header files can then
be included into source code when required.
Library files specified on the command line are scanned first for unresolved symbols,
so these files may redefine anything that is defined in the C standard libraries.
3.4.2 Startup and Initialization
Two startup modules are available to initialize the C runtime environment:
• The primary startup module (crt0.o) which is linked by default (or the -Wl,
--data-init option.)
• The alternate startup module (crt1.o) which is linked when the -Wl,
--no-data-init option is specified (no data initialization.)
These modules are included in the libpic30-omf.a archive/library . Multiple versions
of these modules exist in order to support architectural differences between device
families. The compiler automatically uses the correct module.
For more information on the startup modules, see Section 12.3 “Runtime Startup
and Initialization”.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 58 2012 Microchip Technology Inc.
3.5 COMPILER OUTPUT
There are many files created by the compiler during the compilation. A large number of
these are intermediate files are deleted after compilation is complete, but many remain
and are used for programming the device or for debugging purposes.
3.5.1 Output Files
The compilation driver can produce output files with the following extensions, which are
case-sensitive.
The names of many output files use the same base name as the source file from which
they were deri ved. For example the source fi le input.c will create an object file called
input.o when the -c option is used.
The default output file is a ELF file called a.out, unless you override that name using
the -o option.
If you are using an IDE, such as MPLAB IDE, to specify options to the compiler, there
is typically a project file that is created for each application. The name of this project is
used as the base name for project-wide output files, unless otherwise specified by the
user. However check the manual for the IDE you are using for more details.
The compiler is able to directly produce a number of the output file formats which are
used by Microc hi p deve lop ment tools.
The default behavior of xc16-gcc is to produce a ELF output. T o make changes to the
files output or the file names, see S ect ion 3.7 “Driver Op tio n Descr ip ti ons ”.
3.5.2 Diagnostic Fil es
T wo valuable files produced by the compiler are the assembly list file, produced by the
assembler, and the map file, produced by the linker.
The assembly list file contains the mapping between the original source code and the
generated assembly code. It is useful for information such as how C source was
encoded, or how assembly source may have been optimized. It is essential when con-
firming if compiler-produced code that accesses objects is atomic, and shows the
region in which all objects and code are placed.
The option to create a listing file in the assembler is -a. There are many variants to this
option, which may be found in the MPLAB Assembler, Linker and Utilities for PIC24
MCUs and dsPIC DSCs User’s Guide (DS51317). T o pass the option from the compiler,
see Section 3.7.8 “Options for Assembling”.
TABLE 3-4: FILE NAMES
Extensions Definition
file.hex Executable file
file.cof COF debug file (default)
file.elf ELF debug file
file.o Object file (intermediate file)
file.S Assembly code file (required preprocessing)
file.s Assembly code file (intermediate file)
file.i Prep rocessed file (int ermediate file)
file.p Preprocedure abstraction assembly language file (intermediate file)
file.map Map fil e
Note: Throughout this manual, the term project name will refer to the name of the
project created in the IDE.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 59
There is one list file produced for each build. Thus, if you require a list file for each
source file, these files must be compiled separately, see Section 3.3.3 “Multi-Step
Compilation”. This is the case if you build using MPLAB IDE. Each list file will be
assigned the module name and extension .lst.
The map fi le shows info rmatio n relati ng to wher e object s were posi tioned in memory. It
is useful for confirming if user-defined linker options were correctly processed, and for
determining the exact placement of objects and functions.
The linker option to create a map file in the linker application is -Map file, which may
be found in the MP LA B Assembler, Linker and Utilit ies for PIC24 M CUs and dsPIC
DSCs User’s Guide (DS51317). To specify the option from the command-line driver,
see Section 3.7.9 “Options for Linking”.
There is one map file produced when you build a project, assuming the linker was exe-
cuted and ran to completion.
3.6 COMPILER MESSAGES
Compiler output messages for errors, warnings or comments as discussed in Appen-
dix B. “Diagnostics”.
For information on options that control compiler output of errors, warnings or com-
ments, see Section 3.7.4 “Options for Controlling Warnings and Errors”.
There are no pragmas that directly control messages issued by the compiler.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 60 2012 Microchip Technology Inc.
3.7 DRIVER OPTION DESCRIPTIONS
The compiler has many options for controlling compilation, all of which are
case-sensitive. They have been grouped, as shown below , according to their function.
Remember, these are options for the command-line driver; options for the linker,
assembler or any other application can be found in the MPLAB Assembler, Linker and
Utilities for PIC24 MCUs and dsPIC DSCs User’s Guide (DS51317).
• Options Specific to 16-Bit Devices
• Options for Controlling the Kind of Output
• Options for Controlling the C Dialect
• Options for Controlling Warnings and Errors
• Options for Debugging
• Options for Controlling Optimization
• Options for Controlling the Preprocessor
• Options for Assembling
• Options for Linking
• Options for Directory Search
• Options for Code Generation Conventions
3.7.1 Options S pecific to 16-Bit Devices
For more information on the memory models, see Section 7.12 “Memory Models”.
TABLE 3-5: 16-BIT DEVICE-SPECIFIC OPTIONS
Option Definition
-mconst-in-code Put const qualified variables in the auto_psv space. The compiler
will access these variables using the PSV window. (This is the
default.)
-mconst-in-data Put const qualified variables in the data memory space.
-mconst-in-
auxflash When combined with -mconst-in-code, put call const qualified file
scope variables into auxil iary FLASH . All module s with auxil iary FL ASH
should be compiled with this option; otherwise a link error may occur.
-merrata=
id[,id]* This option en abl es sp ec ific errata work arounds id en tifi ed b y id. Valid
values for id change from time to time and may not be required for a
particular variant. An id of list will display the currently supported
errata identifiers along with a brief description of the errata. An id of
all will enable all currently supported errata work arounds.
-mfillupper Specif y the up per byt e of variab les st ored int o space(prog) secti ons.
The fillupper attribute will perform the same function on individual
variables.
Note 1: The procedure abstractor behaves as the inverse of inlining f unctions. The pass is
designed to extract common code sequences from multiple sites throughout a
translation unit and place them into a common area of code. Although this option
generall y does not improve the run -tim e p erformance of the g ene rate d c ode , it can
reduce the code size significantly. Programs compiled with -mpa can be harder to
debug; it is not recommended that this option be used while debugging using the
COFF object format.
The procedure abstractor is invoked as a separate phase of compilation, after the
production of an assembly file. This phase does not optimize across translation
unit s. When the procedure-o ptimizing ph ase is enabl ed, inline as sembly code must
be limited to valid machine instructions. Invalid machine instructions or instruction
sequen ces , or asse mb ler dire ct ives (sectioni ng directives, ma cros, include files,
etc.) must not be used, or the procedure abstraction phase will fail, inhibiting the
creation of an output file.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 61
-mlarge-arrays Specifies that arrays may be larger than the default maximum size of
32K. See Section 4.7 “Bit-Reversed and Modulo Addressing” for
more information.
-mlarge-code Compile using the large code model. No assumptions are made about
the locality of called functions.
When this option is chosen, single functions that are larger than 32k
are not supported and may cause assembly-time errors since all
branches inside of a function are of the short form.
-mlarge-data Compile using the large data model. No assumptions are made about
the location of static and external variables.
-mcpu=
target This option selects the target processor ID (and communicates it to the
assem bler and linker if tho se tools are invo ked). This optio n aff ects how
some predefined constants are set; see Section 16.4 “Predefined
Macro Names” for mo re info rmation. A full list of accepted targ et s can
be seen in the Readme.htm file that came with the release.
-mpa(1) Enable the procedure abstraction optimization. There is no limit on the
nesting level.
Optimization levels depend on the compiler edition (see Chapter
15. “Optimizations”.)
-mpa=n(1) Enable the procedure ab stract ion optimi zation up to level n. If n is ze ro,
the opt imizatio n is disabled. If n is 1, first level of abstractio n is allowed;
that is, instruction sequences in the source code may be abstracted
into a subr outine . If n is 2, a second level of abs tracti on is allowe d; tha t
is, instructions that were put into a subroutine in the first level may be
abst ract ed int o a subrou tin e one lev el dee per. This p att ern co ntin ues
for larger values of n. The net effect is to limit the subroutine call nest-
ing depth to a maximum of n.
Optimization levels depend on the compiler edition (see Chapter
15. “Optimizations”.)
-mno-pa(1) Do not enable the procedure abstraction optimization.
(This is the default.)
-mno-isr-warn By defa ult the compi ler will prod uce a warni ng if the __interrupt__
is not attached to a recognized interrupt vector name. This option will
disable that feature.
-omf Selects the OMF (Object Mo dule Form at) t o be used by the c ompiler.
The omf specifier can be one of the following:
elf Produce ELF object files. (This is the default.)
coff Produce COFF object files.
The debugging format used for ELF object files is DWARF 2.0.
-msmall-code Compile using the small code model. Called functions are assumed to
be proximate (within 32 Kwords of the caller). (This is the default.)
TABLE 3-5: 16-BIT DEVICE-SPECIFIC OPTIONS (CONTINUED)
Option Definition
Note 1: The procedure abstractor behaves as the inverse of inlining f unctions. The pass is
designed to extract common code sequences from multiple sites throughout a
translation unit and place them into a common area of code. Although this option
generall y does not improve the run -tim e p erformance of the g ene rate d c ode , it can
reduce the code size significantly. Programs compiled with -mpa can be harder to
debug; it is not recommended that this option be used while debugging using the
COFF object format.
The procedure abstractor is invoked as a separate phase of compilation, after the
production of an assembly file. This phase does not optimize across translation
unit s. When the procedure-o ptimizin g phase is enabl ed, inli ne assembly code must
be limited to valid machine instructions. Invalid machine instructions or instruction
sequen ces , or asse mb ler dire ct ives (sectioni ng dire ctives, macro s, inc lu de files,
etc.) must not be used, or the procedure abstraction phase will fail, inhibiting the
creat ion of an output file .
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 62 2012 Microchip Technology Inc.
3.7.2 Options for Controlling the Kind of Output
The following options control the kind of output produced by the compiler.
-msmall-data Compile using the small data model. All static and external variables
are assumed to be located in the lower 8 KB of data memory space.
(This is the default.)
-msmall-scalar Like -msmall-data, except that only static and external scalars are
assumed to be in the lower 8 KB of data memory space. (This is the
default.)
-mtext=name Specifying -mtext=name will cause text (program code) to be placed
in a section nam ed name rather than the default .text secti on. No
white spaces should appear around the =.
-mauxflash Place all code from the current translation unit into auxiliary FLASH.
This option is only available on devices that have auxiliary FLASH.
-msmart-io
[=0|1|2] This option attempts to statically analyze format strings passed to
printf, scanf an d the ‘f’ and ‘v’ vari ations of th ese funct ions. Uses of
nonfloating point format arguments will be converted to use an
integer -only variation of the libr ary funct ions.
-msmart-io=0 disa bles this option, w hile -msmart-io=2 cau ses the
compiler to be optimistic and convert function calls with variable or
unknow n form at argu me nt s . -msmart-io=1 is the default and will
only convert the literal values it can prove.
TABLE 3-6: KIND-OF-OUTPUT CONTROL OPTIONS
Option Definition
-c Compile or assemble the source files, but do not link. The default file extension
is .o.
-E Stop af ter the prepro cessing st age, i .e., before runnin g the comp iler pro per. The
default output file is stdout.
-o file Place the output in file.
-S Stop after compilation proper (i.e., before invoking the assembler). The default
output file extension is .s.
-v Print the commands executed during each stage of compilation.
TABLE 3-5: 16-BIT DEVICE-SPECIFIC OPTIONS (CONTINUED)
Option Definition
Note 1: The procedure abstractor behaves as the inverse of inlining f unctions. The pass is
designed to extract common code sequences from multiple sites throughout a
translation unit and place them into a common area of code. Although this option
generall y does not improve the run -tim e p erformance of the g ene rate d c ode , it can
reduce the code size significantly. Programs compiled with -mpa can be harder to
debug; it is not recommended that this option be used while debugging using the
COFF object format.
The procedure abstractor is invoked as a separate phase of compilation, after the
production of an assembly file. This phase does not optimize across translation
unit s. When the procedure-o ptimizing ph ase is enabl ed, inline as sembly code must
be limited to valid machine instructions. Invalid machine instructions or instruction
sequen ces , or asse mb ler dire ct ives (sectioni ng directives, ma cros, include files,
etc.) must not be used, or the procedure abstraction phase will fail, inhibiting the
creation of an output file.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 63
3.7.3 Options for Control ling the C Dialect
The following options define the kind of C dialect used by the compiler.
-x You can specify the input language explicitly with the -x option:
-x language
Specify explicitly the language for the following input files (rather than
letting the compiler choose a default based on the file name suffix). This option
applies to all following input files until the next -x option.
The following values are supported by the compiler:
c c-header cpp-output
assembler assembler-with-cpp
-x none
Turn off any specification of a language, so that subsequent files are handled
accord ing to th eir file name suf f ixes. This is the defaul t behav ior but is neede d if
another -x option has been used.
For exam ple:
xc16-gcc -x assembler foo.asm bar.asm -x none main.c
mabonga.s
Without the -x none, the compiler will assume all the input files are for the
assembler.
--help Print a description of the command line options.
TABLE 3-7: C DIALECT CONTROL OPTIONS
Option Definition
-ansi Support all (and only) ANSI-standard C programs.
-aux-info filename Output to the gi ven file n ame prototy ped d eclara tions for a ll
functions declared and/or defined in a translation unit,
including those in header files. This option is silently
ignored in any language other than C. Besides
declarati ons , the file indic ate s, in com m ents, the origin of
each decl aration (source fi le and lin e), whe ther the dec lara-
tion was implicit, prototyped or unprototyped (I, N for new
or O for old, respectively, in the first character after the line
number and the colon), and whether it came from a
declaration or a definition (C or F, respectively, in the
following character). In the case of function definitions, a
K&R-style list of a rgument s followe d by their declarations is
also provid ed, ins id e comme nt s , af ter the dec la rati on.
-ffreestanding Assert that compilation takes place in a freestanding
environment. This implies -fno-builtin. A freestanding
environment is one in which the standard library may not
exist, and prog ram st a rtup may not nec es sarily be at mai n.
The most obvious example is an OS kernel. This is
equivale nt to -fno-hosted.
-fno-asm Do not recognize asm, inline or typeof as a keyword,
so that code can use these words as identifiers. You can
use the keywords __asm__, __inline__ and
__typeof__ instead.
-ansi implies -fno-asm.
-fno-builtin
-fno-builtin-function Don’t recognize built-in functions that do not begin with
__builtin_ as prefix.
-fsigned-char Let the type char be signed, like signed char.
(This is the default.)
TABLE 3-6: KIND-OF-OUTPUT CONTROL OPTIONS (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 64 2012 Microchip Technology Inc.
3.7.4 Options for Controlling Warnings and Errors
Warnings are diagnostic messages that report constructions that are not inherently
erroneous but that are risky or suggest there may have been an error.
You can request many specific warnings with options beginning -W, for example,
-Wimplicit, to request warnings on implicit declarations. Each of these specific
warning options also has a negative form beginning -Wno- to turn off warnings, for
example, -Wno-implicit. This manual lists only one of the two forms, whichever is
not the default.
The following options control the amount and kinds of warnings produced by the
compiler.
-fsigned-bitfields
-funsigned-bitfields
-fno-signed-bitfields
-fno-unsigned-bitfields
These options control whether a bit field is signed or
unsigned, when the declaration does not use either signed
or unsigned. By default, such a bit field is signed, unless
-traditional is used , in which case bi t fields are a lways
unsigned.
-funsigned-char Let the type char be unsigned, like unsigned char.
TABLE 3-8: WARNING/ERROR OPTIONS IMPLIED BY -WALL
Option Definition
-fsyntax-only Check the code for syntax, but don’t do anything beyond that.
-pedantic Issue all the warnings demanded by strict ANSI C; reject all
programs that use forbidden extensions.
-pedantic-errors Like -pedantic, except that errors are produced rather than
warnings.
-w Inhibit all warning messages.
-Wall All of the -W options listed in this table combined. This enables
all the warnings about constructions that some users consider
questionable, and that are easy to avoid (or modify to prevent
the warning), even in conjunction with macros.
-Wchar-subscripts Warn if an array subscript has type char.
-Wcomment
-Wcomments Warn whenever a comment-start sequence /* appears in a /*
comment, or whenever a Backslash-Newline appears in a //
comment.
-Wdiv-by-zero Warn about compile-time integer division by zero. To inhibit the
warning messages, use -Wno-div-by-zero. Floatin g poin t
division by zero is not warned about, as it can be a legitimate
way of ob taining infinities and NaN s.
(This is the default.)
-Werror-implicit-
function-declaration Give an error whenever a function is used before being
declared.
-Wformat Check calls to printf and scanf, etc., to make sure that the
arguments supplied have types appropriate to the format string
specified.
-Wimplicit Equivalent to specifying both -Wimplicit-int and
-Wimplicit-function-declaration.
-Wimplicit-function-
declaration Give a warning whenever a function is used before being
declared.
-Wimplicit-int Warn when a declaration does not specify a type.
TABLE 3-7: C DIALECT CONTROL OPTIONS (CONTINUED)
Option Definition
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 65
-Wmain Warn if the type of main is su spicious. main should be a func-
tion with exte rnal lin ka ge, re turn ing int, taking either zero, two
or three arguments of appropriate types.
-Wmissing-braces Warn if an ag gregat e o r unio n init ializ er is not fu lly b racke ted. In
the following example, the initializer for a is not fully bracketed,
but that for b is fully bracketed.
int a[2][2] = { 0, 1, 2, 3 };
int b[2][2] = { { 0, 1 }, { 2, 3 } };
-Wmultichar
-Wno-multichar Warn if a multi-character character constant is used.
Usually, such constants are typographical errors. Since they
have imp lementati on-defined va lues, they sho uld not be used in
portable code. The following example illustrates the use of a
multi-character character constant:
char
xx(void)
{
return('xx');
}
-Wparentheses Warn if parentheses are omitted in certain contexts, such as
when the re is an a ss ign me nt in a conte xt wh ere a truth val ue i s
expected, or when operators are nested whose precedence
people often find confusing.
-Wreturn-type Warn whenever a function is defined with a return-type that
default s to int. Als o warn about any return st atement with no
return-value in a function whose return-type is not void.
TABLE 3-8: WARNING/ERROR OPTIONS IMPLIED BY -WALL (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 66 2012 Microchip Technology Inc.
-Wsequence-point Warn about code that may have undefined semantics because
of violations of sequence point rules in the C standard.
The C standard defines the order in which expressions in a C
program are evaluated in terms of sequence points, which rep-
resent a partial ordering between the execution of parts of the
program: those executed before the sequence point and those
executed after it. These occur after the evaluation of a full
expression (one which is not part of a larger expression), after
the evaluation of the first operand of a &&, ||, ? : or ,
(comma) o pera tor, bef ore a func ti on i s c all ed (but a fter the e val-
uation of its arguments and the expression denoting the called
function), and in certain other places. Other than as expressed
by the sequence point rules, the order of evaluation of subex-
pressions of an ex pression is not specified. All these rules
describe only a partial order rather than a total order, since, for
example, if two functions are called within one expression with
no sequence point between them, the order in which the func-
tions are called is not specified. However, the standards com-
mittee has ruled that function calls do not overlap.
It is not specified, when, between sequence points
modifications to the values of objects take effect. Programs
whose behavior depends on this have undefined behavior; the
C standard specifies that “Between the previous and next
sequence point, an object shall have its stored value modified,
at most once, by the evalu ati on of an exp res si on. Furt herm ore ,
the prior value shall be read only to determine the value to be
stored.” If a program breaks these rules, the results on any par-
ticular imp lemen tation are entirely unpredi ct a ble.
Examples of code with undefined behavior are a = a++;,
a[n] = b[n++] and a[i++] = i;. Some more complicated
cases are not diagnosed by this option, and it may give an
occasi onal fa lse po sitiv e resu lt, b ut in g eneral it has been f ound
fairly effective at detecting this sort of problem in programs.
-Wswitch Warn w henever a switch st ate me nt has an in dex of enu me ral
type and lacks a case for one or more of the named codes of
that enum eration . (Th e pres ence of a de fault l abel p revents this
warning.) case labels outside the enumeration range also pro-
voke warnings w hen this option is used.
-Wsystem-headers Print warning messages for constructs found in system header
files. Warnings from system headers are normally suppressed,
on the assumption that they usually do not indicate real prob-
lems and would only make the compiler output harder to read.
Using this command line option tells the compiler to emit warn-
ings from system headers as if they occurred in user code.
However, note that using -Wall in conjunction with this option
will not warn about unknown pragmas in system headers; for
that, -Wunknown-pragmas must also be used.
-Wtrigraphs Warn if any trigraphs are encountered (assuming they are
enabled).
TABLE 3-8: WARNING/ERROR OPTIONS IMPLIED BY -WALL (CONTINUED)
Option Definition
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 67
The following -W options are not implied by -Wall. Some of them warn about construc-
tions that users generally do not consider questionable, but which occasionally you
might wish to check for . Others warn about constructions that are necessary or hard to
avoid in some cases, and there is no simple way to modify the code to suppress the
warning.
-Wuninitialized Warn if an automatic variable is used without first being
initialized.
These wa rnings are possi ble only wh en optimizat ion is enable d,
because they require data flow information that is computed
only when optim iz ing .
These warnings occur only for variables that are candidates for
register allocati on. Ther efore, they do not occur fo r a variable
that is declared volatile, or whose address is taken, or
whose size is other than 1, 2, 4 or 8 bytes. Also, they do not
occur for structures, unions or arrays, even when they are in
registers.
Note tha t there m ay be no warn ing abo ut a v ariable that i s used
only to compute a value that itself is never used, because such
computations may be deleted by data flow analysis before the
warnin gs are printed.
-Wunknown-pragmas Warn when a #pragma directive is encountered which is not
understoo d by the com piler. If this com mand line option is used,
warnings will even be issued for unknown pragmas in system
header files. This is not the case if the warnings were only
enabled by the -Wall command line option.
-Wunused Warn whenever a variable is unused aside from its declaration,
whenever a function is declared static but never defined, when-
ever a label is declared but not used, and whenever a state-
ment computes a result that is explicitly not used.
In order to get a warning about an unused function parameter,
both -W and -Wunused must be specified.
Casting an expression to void suppresses this warning for an
expression. Similarly, the unused attribute suppresses this
warnin g for unused variables, parameters and labels.
-Wunused-function Warn whene ver a st atic functio n is dec lared but n ot de fined or a
non-inline stat ic fun cti on is unu se d.
-Wunused-label Warn whenever a label is declared but not used. To suppress
this warning, use the unused attribute (see
Section 6.11 “ Variable Attributes”).
-Wunused-parameter Warn whenever a function parameter is unused aside from its
declaration. To suppress this warning, use the unused attribute
(see Section 6.11 “Variable Attributes”).
-Wunused-variable Warn whenever a local variable or non-constant static variable
is unused aside from its declaration. To suppress this warning,
use the unused attribute (see Section 6.11 “Variable Attri-
butes”).
-Wunused-value Warn whenever a statement computes a result that is explicitly
not used. To suppress this warning, cast the expression to
void.
TABLE 3-8: WARNING/ERROR OPTIONS IMPLIED BY -WALL (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 68 2012 Microchip Technology Inc.
TABLE 3-9: WARNING/ERROR OPTIONS NOT IMPLIED BY -WALL
Option Definition
-W Print extra warning messages for these events:
• A nonvolatile automatic variable might be changed by a
call to longjmp. These warnings are possible only in
optimizing compilation. The compiler sees only the calls
to setjmp. It cannot kno w wher e longjmp will be called;
in fact, a signal handler could call it at any point in the
code. As a result, a warning may be generated even
when there is in fact no problem, because longjmp
cannot in fact be called at the place that would cause a
problem.
• A function could exit both via return value; and
return;. Completing the function body without passing
any return st ate me nt is trea ted as return;.
• An expression-statement or the left-hand side of a
comma expression contains no side effects. To suppress
the warning, cast the unused expression to void. For
example, an expression such as x[i,j] will cause a
warning, but x[(void)i,j] will not.
• An un sig ned val ue is co mpared against zero with < or <=.
• A com par iso n like x<=y<=z appe ars; thi s is eq uival ent to
(x<=y ? 1 : 0) <= z, which is a different interpretation
from that of ordinary mathematical notation.
• Storage-class specifiers like static are not the first
things in a declaration. According to the C Standard, this
usage is obsolescent.
•If -Wall or -Wunused is also specified, warn about
unused argu ments .
• A comp arison b etween signed a nd unsigned values coul d
produce an incorrect result when the signed value is
converted to unsigned. (But don’t warn if
-Wno-sign-compare is also specified.)
• An aggregate has a partly bracketed initializer. For
exampl e, the fol lowing cod e would ev oke suc h a warning ,
becaus e braces are mi ss ing around the initializer for x.h:
struct s { int f, g; };
struct t { struct s h; int i; };
struct t x = { 1, 2, 3 };
• An aggregate has an initializer that does not initialize all
members. For example, the following code would cause
such a warning, because x.h would be implicitly
initialized to zero :
struct s { int f, g, h; };
struct s x = { 3, 4 };
-Waggregate-return Warn if any functions that return structures or unions are
defined or cal led .
-Wbad-function-cast Warn whenev er a fu nc tio n ca ll is c as t to a non-match ing typ e.
For example, warn if int foof() is cast to anything *.
-Wcast-align Warn w henever a pointe r is cast, such that the required
alignment of the target is increased. For example, warn if a
char * is cast to an int * .
-Wcast-qual Warn whenever a pointer is cast, so as to remove a type
qualifier from the target type. For example, warn if a
const char * is cast to an ordinary char *.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 69
-Wconversion Warn if a prototype causes a type conversion that is different
from what would happen to the same argument in the
absence of a prototype. This includes conversions of fixed
point to f loa ting an d vice v ersa, a nd con versi ons ch angin g the
width or signedness of a fixed point argument, except when
the same as the default promotion.
Also, warn if a negative integer constant expression is
imp lici tly converted to an unsigned type. For example, warn
about the assignment x = -1 if x is unsigned. But do not
warn about explicit casts like (unsigned) -1.
-Werror Make all warnings into errors.
-Winline Warn if a function can not be inlined, and either it was
declared as inline, or else the -finline-functions option
was given.
-Wlarger-than-len Warn whenever an objec t of larger than len bytes is defined.
-Wlong-long
-Wno-long-long Warn if long long type is used. This is defau lt. To inhibit the
warning messages, use -Wno-long-long. Flags
-Wlong-long and -Wno-long-long are ta ken int o account
only when -pedantic flag is used.
-Wmissing-declarations Warn if a global function is defined without a previous
declaration. Do so even if the definition itself provides a
prototype.
-Wmissing-
format-attribute If -Wformat is enabled, also warn about functions that might
be candidates for format attributes. Note these are only possi-
ble candidates, not absolute ones. This option has no effect
unless -Wformat is enabled.
-Wmissing-noreturn Warn about functions that might be candidates for attribute
noreturn. These are only possible candidates, not absolute
ones. Care should be taken to manually verify functions.
Actually, do not ever return before adding the noreturn attri-
bute; otherwise subtle code generation bugs could be intro-
duced.
-Wmissing-prototypes Warn if a global function is defined without a previous
prototype declaration. This warning is issued even if the
definiti on itself provides a prot oty pe. (This opti on can be us ed
to detec t globa l func tions t hat are n ot d eclared i n heade r files .)
-Wnested-externs Warn if an extern declaration is encountered within a
function.
-Wno-deprecated-
declarations Do not warn about uses of functions, variables and types
marked as deprecated by using the deprecated attribute.
-Wpadded Warn if padding is included in a structure, either to align an
element of the structure or to align the whole structure.
-Wpointer-arith Warn about anything that depends on the size of a function
type or of void. The compiler as sign s these t ypes a siz e of 1,
for conveni en ce in calculat ion s with void * pointers and
pointers to functions.
-Wredundant-decls Warn if anything is declared more than once in the same
scope, even in cases where multiple declaration is valid and
changes nothing.
-Wshadow Warn whenever a local variable shadows another local
variable.
TABLE 3-9: WARNING/ERROR OPTIONS NOT IMPLIED BY -WALL
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 70 2012 Microchip Technology Inc.
3.7.5 Options for Debugging
The following options are used for debugging.
-Wsign-compare
-Wno-sign-compare Warn when a comparison between signed and unsigned
values coul d produ ce an inc orre ct resu lt w hen the signe d
value is converted to unsigned. This warning is also enabled
by -W; to get the other warnings of -W without this warning,
use -W -Wno-sign-compare.
-Wstrict-prototypes Warn if a fu nction is decla red or defined wi thout spe cifyi ng the
argument types. (An old-style function definition is permitted
withou t a wa rning i f preced ed by a decl aration which s peci fies
the argument types.)
-Wtraditional Warn about certain constructs that behave differently in
traditional and ANSI C.
• Macro arguments occurring within string constants in the
macro body. These would substitute the argument in
traditional C, but are part of the constant in ANSI C.
• A function declared external in one block and then used
after the end of the block.
• A switch statement has an operand of type long.
• A nonstatic function declaration follows a static one. This
construct is not accepted by some traditional C compilers.
-Wundef Warn if an undefined identifier is evaluated in an #if
directive.
-Wwrite-strings Giv e string con stant s the type const char[length] so that
copying the address of one into a non-const char * pointer
will get a warning. T hese war nings will help you find at
compile time code that you can try to write into a string
constant, but only if you have been very careful about using
const in dec larations an d prototypes. Otherwise, it will just b e
a nuisance, which is why -Wall does not reques t these
warnings.
TABLE 3-10: DEBUGGING OPTIONS
Option Definition
-g Produce debugging information.
The com piler suppor t s the use of -g with -O making it pos sibl e to deb ug opt i-
mized code. The shortcuts taken by optimized code may occasionally pro-
duce surprising results:
• Some declared variables may not exist at all;
• Flow of control may briefly move unexpectedly;
• Some s t ate me nts may not be ex ecu ted becaus e they c om pu te const ant
results or their values were already at hand;
• Some statements m ay execute in different places becaus e they wer e
moved out of loops.
Nevertheless it proves possible to debug optimized output. This makes it
reasonable to use the optimizer for programs that might have bugs.
-Q Makes the compiler print out each function name as it is compiled, and print
some statistics about each pass when it finishes.
TABLE 3-9: WARNING/ERROR OPTIONS NOT IMPLIED BY -WALL
Option Definition
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 71
3.7.6 Options for Control ling Optimization
The following options control compiler optimizations. Optimization levels available depend
on the compiler edition (see Chapter 15. “Optimization s”.)
The following options control specific optimizations. The -O2 option turns on all of
these optimizations except -funroll-loops, -funroll-all-loops and
-fstrict-aliasing.
-save-temps Don ’t del ete int erm edi ate files. Pla ce them i n th e c urren t di rec tory an d n ame
them based on the source file. Thus, compiling foo.c with -c
-save-temps would produce the following files:
foo.i (preprocessed file)
foo.p (pre procedure abstraction assembly language file)
foo.s (assembl y lan gua ge file )
foo.o (object file)
TABLE 3-11: GENERAL OPTIMIZATION OPTIONS
Option Edition Definition
-O0 All Do not optimi ze . (This is the default.)
Without -O, the compiler’s goal is to reduce the cost of compilation
and to make debugging produce the expected results. Statements
are inde pe nde nt: if yo u sto p the pro gram with a break poi nt bet we en
statements, you can then assign a new value to any variable or
change the program counter to any other statement in the function
and get exactly the results you would expect from the source code.
The compi ler only alloc ates variables declared register in regis-
ters.
-O
-O1 All Optimize. Optimizing compilation takes somewhat longer, and a lot
more host memory for a large function.
With -O, the compiler tries to reduce code size and execution time.
When -O is specified, the compiler turns on -fthread-jumps and
-fdefer-pop. The compiler turns on -fomit-frame-pointer.
-O2 STD, PRO Optimize even more. The compiler performs nearly all supported
optimiz ati on s that do not inv ol ve a space-speed trade -off. -O2 turns
on all optional optimizations except for loop unrolling (-fun-
roll-loops), functi on inlining (-finline-functions), and strict
aliasing optimizations (-fstrict-aliasing). It also turns on
Frame Point er elimination (-fomit-frame-pointer). As com-
pared to -O, this option increases both compilation time and the
performan ce of the generat ed cod e.
-O3 PRO Opt imiz e yet more. -O3 turns on all optimizations specified by -O2
and also turns on the inline-functions option.
-Os PRO Optimize for size. -Os enables all -O2 optimiz ati ons that do no t typ i-
cally increase code size. It also performs further optimizations
designed to reduce code size.
TABLE 3-10: DEBUGGING OPTIONS (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 72 2012 Microchip Technology Inc.
You can use the following flags in the rare cases when “fine-tuning” of optimizations to
be perform ed is desired .
TABLE 3-12: SPECIFIC OPTIMIZATION OPTIONS
Option Definition
-falign-functions
-falign-functions=n Align the start of functions to the next power-of-two greater than
n, skipping up to n bytes. For instance,
-falign-functions=32 aligns functions to the next 32-byte
boundary, but -falign-functions=24 would align to the next
32-byte b oundary only if this ca n be don e by sk ipp ing 23 by tes or
less.
-fno-align-functions and -falign-functions=1 are
equivalent and mean that functions will not be aligned.
The assembler only supports this flag when n is a power of two;
so n is rounded up. If n is no t speci fied, use a machine-d ependent
default.
-falign-labels
-falign-labels=nAlign all branch targets to a power-of-two boundary, skipping up
to n bytes like -falign-functions. This option can easily
make code slower, because it must insert dummy operations for
when the branch target is reached in the usual flow of the code.
If -falign-loops or -falign-jumps are applicable and are
greater than this value, then their values are used instead.
If n is not specified, use a machine-dependent default which is
very likely to be 1, mea ning no alignment.
-falign-loops
-falign-loops=nAlign loops to a power-of-two boundary, skipping up to n bytes
like -falign-functions. The hope is that the loop will be exe-
cuted many times, which will make up for any execution of the
dummy operations.
If n is not specified, use a machine-dependent default.
-fcaller-saves Enabl e values to be allo cated in regi sters that will be cl obbered by
function calls, by emitting extra instructions to save and restore
the registe rs around such ca lls. Such alloc ation is done only wh en
it seems to result in better code than would otherwise be pro-
duced.
-fcse-follow-jumps In c om mon s ube xp res si on eli mi nat ion, scan through jum p ins truc -
tions when the target of the jump is not reached by any other
path. For example, when CSE encounters an if statement with
an else clause, CSE will follow the jump when the condition
tested is false.
-fcse-skip-blocks This is similar to -fcse-follow-jumps, but causes CSE to fol-
low jumps which conditionally skip over blocks. When CSE
encounters a simple if statement with no else clause,
-fcse-skip-blocks caus es CSE to follow the jump aro und the
body of the if.
-fexpensive-
optimizations Perform a number of minor optimizations that are relatively
expensive.
-ffunction-sections
-fdata-sections Place eac h fun cti on or data i tem into it s own section in th e output
file. The name of the function or the name of the data item deter-
mines the se ction’ s name in the out put fil e.
Only use these options when there are significant benefits f or
doing so. When you specify these options, the assembler and
linker may create larger object and executable files and will also
be slower.
-fgcse Perform a global common subexpression elimination pass. This
pass also performs global constant and copy propagation.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 73
-fgcse-lm When -fgcse-lm is enabled, global common subexpression
elimination will attempt to move loads which are only killed by
stores in to th em selves. This al lows a lo op c ontai nin g a lo ad /store
sequence to be changed to a load outside the loop, and a
copy/s tore within the loo p.
-fgcse-sm When -fgcse-sm is enabled, a store motion pass is run after
global common subexpression elimination. This pass will attempt
to move stores out of loops. When used in conjunction with
-fgcse-lm, loops containing a load/store sequence can be
changed to a load before the loop and a store after the loop.
-fno-defer-pop Always pop the arguments to each function call as soon as that
function returns. The compiler normally lets arguments accumu-
late on the stack for several function calls and pops them all at
once.
-fno-peephole
-fno-peephole2 Disable machine specific peephole optimizations. Peephole opti-
mizations occur at various points during the compilation.
-fno-peephole disables peephole optimization on machine
instructions, while -fno-peephole2 disables high level peep-
hole optimizations. To disable pee phole enti rely, use both o pti ons .
-foptimize-
register-move
-fregmove
Attemp t to reas si gn r egi ster numbe rs i n m ov e in stru ctions and as
operands of other simple instructions in order to maximize the
amount of register tying.
-fregmove and -foptimize-register-moves ar e the same
optimization.
-frename-registers Attempt to avoid false dependencies in scheduled code by mak-
ing use of registers left over after register allocation. This optimi-
zation will most benefit processors with lots of registers. It can,
howev er, make debugging impossib le, since varia ble s wi ll no lon-
ger stay in a “home register”.
-frerun-cse-after-
loop Rerun common subexpression elimination after loop
optimizations has been performed.
-frerun-loop-opt Run the loop optimizer twice.
-fschedule-insns Attempt to reorder instructions to eliminate dsPIC® DSC
Read-After-Write stalls (see the “dsPIC30F Family Reference
Manual” (DS70046) for more details). Typically improves
performance with no impact on code size.
-fschedule-insns2 Simi lar to -fschedule-insns, but request s an additiona l p as s
of instruction scheduling after register allocation has been done.
-fstrength-reduce Perform the optimizations of loop strength reduction and
elimination of iteration variables.
TABLE 3-12: SPECIFIC OPTIMIZATION OPTIONS (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 74 2012 Microchip Technology Inc.
-fstrict-aliasing Allows the compiler to assume the strictest aliasing rules applica-
ble to the language being compiled. For C, this
activates optimizations based on the type of expressions. In par-
ticular, an object of one type is assumed never to reside at the
same address as an object of a different type, unless the types
are almost the same. For example, an unsigned int can alias
an int, but not a void* or a double. A chara cter t ype may ali as
any other type .
Pay special attention to code like this:
union a_union {
int i;
double d;
};
int f() {
union a_union t;
t.d = 3.0;
return t.i;
}
The practice of reading from a different union member than the
one most recently written to (called “type-punning”) is common.
Even with -fstrict-aliasing, type-punning is allowed, pro-
vided the memory is accessed through the union type. So, the
code above will work as expected. However, this code might not:
int f() {
a_union t;
int* ip;
t.d = 3.0;
ip = &t.i;
return *ip;
}
-fthread-jumps Perform optimizations where a check is made to see if a jump
branches to a location where another comparison subsumed by
the first is found. If so, the first branch is redirected to either the
destination of the second branch or a point immediately following
it, depending on whether the condition is known to be true or
false.
-funroll-loops Perform the optimization of loop unrolling. This is only done for
loops whose number of iterations can be determined at compile
time or run time. -funroll-loops implies both
-fstrength-reduce and -frerun-cse-after-loop.
-funroll-all-loops Perform the optimization of loop unrolling. This is done for all
loops and usually makes programs run more slowly.
-funroll-all-loops implies -fstrength-reduce, as well
as -frerun-cse-after-loop.
TABLE 3-12: SPECIFIC OPTIMIZATION OPTIONS (CONTINUED)
Option Definition
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 75
Options of the form -fflag specify machine-independent flags. Most flags have both
positive and negative forms; the negative form of -ffoo would be -fno-foo. In the
table below, only one of the forms is listed (the one that is not the default.)
TABLE 3-13: MACHINE-INDEPENDENT OPTIMIZATION OPTIONS
Option Definition
-finline-functions I ntegrate all s impl e func tions into th eir cal lers. The comp iler
heuristically decides which functions are simple enough to
be worth integrating in this way. If all calls to a given func-
tion are integrated, and the function is declared static,
then the function is normally not output as assembler code
in its own right.
-finline-limit=n By default, the compiler limits the size of functions that can
be inlined. This flag allows the control of this limit for func-
tions that are explicitly marked as inline (i.e., marked with
the inline keywor d). n is the size of functions that can be
inlined in number of pseudo instructions (not counting
parameter handling). The default value of n is 10000.
Increasing this value can result in more inlined code at the
cost of compilation time and memory consumption.
Decreasing usually makes the compilation faster and less
code will be inlined (which presumably means slower
programs). This option is particularly useful for programs
that use inli ning.
Note: Pseudo instruction represents, in this particular con-
text, an abstract measurement of function’s size. In no way
does it represent a count of assembly instructions and as
such, its exact meaning might change from one release of
the compiler to an another.
-fkeep-inline-functions Even if all calls to a given function are integrated, and the
func tion is declared static, output a separate run time
callable version of the function. This switch does not affect
extern inline functions.
-fkeep-static-consts Emit variables declared static const when optimization isn’t
turned on, even if the var iables aren’t refe renced.
The compiler enables this option by default. If you want to
force the compiler to check if the variable was referenced,
regardless of whether or not optimization is turned on, use
the -fno-keep-static-consts option.
-fno-function-cse Do not put function addresses in registers; make each
instruction that calls a constant function contain the
functio n’s address explicitl y.
This option results in less efficient code, but some strange
hack s that alt er the assembler output may be confused by
the optimizations performed when this option is not used.
-fno-inline Do not pay attention to the inline keyword. Normally this
option is used to keep the compiler from expanding any
functions inline. If optimization is not enabled, no functions
can be expanded inline.
-fomit-frame-pointer Do not keep the Frame Pointer in a register for functions
that d on’t need one. This av oids the inst ructions to sav e, set
up and restore Frame Pointers; it also makes an extra reg-
ister available in many functions.
-foptimize-sib-
ling-calls Optimize sibling and tail recursive calls.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 76 2012 Microchip Technology Inc.
3.7.7 Options for Control ling the Preprocessor
The following options control the compiler preprocessor.
TABLE 3-14: PREPROCESSOR OPTIONS
Option Definition
-Aquestion (answer)Assert the ans wer answer for questi on question, in case it is
tested with a preprocessing conditional such as #if
#question(answer). -A- disables the standard assertions
that normally describe the target machine.
For example, the function prototype for main might be declared
as follows:
#if #environ(freestanding)
int main(void);
#else
int main(int argc, char *argv[]);
#endif
A -A command-line option could then be used to select
between the two prototypes. For example, to select the first of
the two, the following command-line option could be used:
-Aenviron(freestanding)
-A -predicate =answer Can cel an asse rtion wi th the p redi cate predicate and ans wer
answer.
-A predicate =answer Make an assertion with the predicate predicate and answer
answer. This form is preferred to the older form
-A predicate(answer), which is still supported, because it
does not use shell special characters.
-C Tell the preprocessor not to discard comments. Used with the
-E option.
-dD Tell the preprocessor to not remove macro definitions into the
output, in their proper sequence.
-Dmacro Define macro macro with the string 1 as its definition.
-Dmacro=defn Define macro macro as defn. All instances of -D on the
command line are processed before any -U options.
-dM Tell the preprocessor to output only a list of the macro
definitions that are in effect at the end of preprocessing. Used
with the -E option.
-dN Like -dD except that the macro arguments and contents are
omitted. Only #define name is included in the output.
-fno-show-column Do not print column numbers in diagnostics. This may be
necessary if diagnostics are being scanned by a program that
does not understand the column numbers, such as dejagnu.
-H Print the nam e o f e ach header fi le us ed, in ad dit ion to other n or-
mal activ ities.
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 77
-I- Any directories you spec ify with -I options before the -I-
options are searched only for the case of #include "file";
they are not searc hed for #include <file>.
If additional directories are specified with -I options after the
-I-, these directories are searched for all #include
directives. (Ordinarily all -I di rectories are used this way.)
In addition, the -I- option inhibits the use of the current
directory (where the current input file came from) as the first
search direc tory for #include "file". There is no way to
override this effect of -I-. With -I. you can spe ci f y se arc h in g
the directory that was current when the compiler was invoked.
That is not exactly the same as what the preprocessor does by
default, but it is often satisfactory.
-I- does not inhibit the use of the standard system directories
for header files. Thus, -I- and -nostdinc are independent.
-Idir Add the directory dir to the head of the list of directories to be
searched for header files. This can be used to override a
system header file, substituting your own version, since these
directories are searched before the system header file
directories. If you use more than one -I option, the directories
are scanned in left-to-right order; the standard system
directories come after.
-idirafter dir Add the directory dir to the second include path. The
directories on the second include path are searched when a
header file is not found in any of the directories in the main
include path (the one that -I adds to).
-imacros file Proces s file as inp ut, disc arding the result ing outp ut, before pro-
cessing the regular input file. Because the output generated
from the file is discarded, the only effect of -imacros file is
to make the macros defined in file available for use in the main
input.
Any -D and -U options on the command line are always
processed before -imacros file, regardless of the order in
which they are written. All the -include and -imacros
options are processed in the order in which they are written.
-include file Process file as input before processing the regular input file. In
effect, the contents of file are compiled first. Any -D and -U
options on the command line are always processed before
-include file, regardless of the orde r in which the y are writ-
ten. A ll the -include and -imacros optio ns are processed in
the order in which they are written.
-iprefix prefix Specify prefix as the prefix for subsequent -iwithprefix
options.
-isystem dir Add a directory to the beginning of the second include path,
marking it as a system directory, so that it gets the same special
treatment as is applied to the standard system directories.
-iwithprefix dir Add a directory to the second include path. The directory’s
name is made by concatenating prefix and dir, where prefix
was specified previously with -iprefix. If a prefix has not yet
been specified, the directory containing the installed passes of
the compiler is used as the default.
-iwithprefixbefore
dir Add a directory to the main include path. The directory’s name
is made by concatenating prefix and dir, as in the case of
-iwithprefix.
TABLE 3-14: PREPROCESSOR OPTIONS (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 78 2012 Microchip Technology Inc.
-M Tell the preprocessor to output a rule suitable for make describ-
ing the dependencies of each object file. For each source file,
the preprocessor outputs one make-rule whose target is the
object file name for that source file and whose dependencies
are all the #include header files it uses. This rule may be a
single line or may be continued with \-newline if it is long. The
list of rules is printed on standard output instead of the prepro-
cessed C prog ram.
-M implie s -E (see Section 3.7.2 “Options for Cont rolling the
Kind of Output”).
-MD Like -M but the dependency information is written to a file and
compil ati on co ntin ues . The file cont ai nin g the dep end enc y inf or-
mation is given the same name as the source file with a .d
extension.
-MF file When us ed wi th -M or -MM, specifies a file in which to write the
dependencies. If no -MF switch is given, the preprocessor
sends the rules to the same place it would have sent
preprocessed output.
When used with the driver options, -MD or -MMD, -MF,
overrides the default dependency output file.
-MG Treat missing header file s as gen erated files and assu me they
live in the same directory as the source file. If -MG is specified,
then either -M or -MM must al so be specified. -MG is not
supported with -MD or -MMD.
-MM Like -M but the output mentions only the user header files
included with #include “file”. System header files included
with #include <file> are omitted.
-MMD Like -MD except mention only user header files, not system
header files.
-MP This opti on i nstruct s CPP to a dd a phony ta rget for ea ch depen-
dency o t her than the main f ile , ca us ing each t o de pen d on noth-
ing. These dummy rules work around errors make gives if you
remove header files without updating the make-file to match.
This is typical output:
test.o: test.c test.h
test.h:
-MQ Same as -MT, but it quotes any characters which are special to
make.
-MQ '$(objpfx)foo.o' gives $$(objpfx)foo.o:
foo.c
The default target is automatically quoted, as if it were given
with -MQ.
-MT target Change the target of the rule emitted by dependency
generation. By default, CPP takes the name of the main input
file, including any path, de letes any fil e suffix such as .c, and
appends the platform’s usual object suffix. The result is the
target.
An -MT option will set the target to be exactly the string you
specify. If you want multiple targets, you can specify them as a
single argu me nt t o -MT, or use multiple -MT options.
For example:
-MT '$(objpfx)foo.o' might give $(objpfx)foo.o:
foo.c
TABLE 3-14: PREPROCESSOR OPTIONS (CONTINUED)
Option Definition
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 79
3.7.8 Options for Assembling
The following options control assembler operations. For more on available options, see
the MPLAB Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs User’s
Guide (DS51317).
3.7.9 Options for Linking
-nostdinc Do not search the standard system directories for header files.
Only t he dire ctorie s you ha ve s pecifi ed with -I options (a nd the
current directory, if appropriate) are searched. (See
Section 3.7.10 “Options for Directory Search”) for
information on -I.
By usin g both -nostdinc and -I-, the include-f ile search path
can be limited to only those directories explicitly specified.
-P Tell the preprocessor not to generate #line directives. Used
with the -E option (see Section 3.7.2 “Options for
Controlling the Kind of Output”).
-trigraphs Support ANSI C trigraphs. The -ansi option also has this
effect.
-Umacro Undefine macro macro. -U options are evaluated after all -D
options, but before any -include and -imacros options.
-undef Do not predefi ne any nons t an dard macro s (inc lu ding
architecture flags).
TABLE 3-15: ASSEMBLY OPTIONS
Option Definition
-Wa,option Pass option as an option to the assembler. If option contains
commas, it is split into multiple options at the commas.
For example, to generate an assembly list file, use -Wa,-a.
TABLE 3-14: PREPROCESSOR OPTIONS (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 80 2012 Microchip Technology Inc.
If any of the options -c, -S or -E are used, the linker is not run and object file names
should not be used as arguments. For more on available options, see the MPLAB
Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs User’s Guide
(DS51317).
TABLE 3-16: LINKING OPTIONS
Option Definition
--fill=options Fill unused program memory. The format is:
--fill=[wn:]expression[@address[:end_address] |
unused]
address and end_address will sp ecify the r ange of pr ogram me mory
addresse s to fill. If end_address is no t provided then the expression
will be writt en to the specif ic mem ory loc ation a t addres s address. The
optional literal value unused may be specified to indicate that all
unused mem ory will be fille d. If non e of the location p aram et ers are pro-
vided, all unused memory will be filled. expression will describe how
to fill the specified memory. The following options are available:
A single value
xc16-ld --fill=0x12345678@unused
Range of values
xc16-ld --fill=1,2,3,4,097@0x9d000650:0x9d000750
An incrementing value
xc16-ld --fill=7+=911@unused
By default, the linker will fill using data that is instruction-word length.
For 16-bit devices, the default fill width is 24 bits. However, you may
specif y the value w idth us ing [wn:], whe re n is the fill v alue's wid th a nd
n belongs to [1, 3].
Multip le fil l optio ns ma y be s pecif ied on the comm and li ne; the lin ker wil l
always process fill options at specific locations first.
--gc-sections Remove dead functions from code at link time.
Support is for ELF projects only. In order to make the best use of this
feature, add the -ffunction-sections option to the compiler
command line.
-Ldir Add director y dir to the list of directories to be searched for libraries
specified by the command-line option -l.
-legacy-libc Use legacy include files and libraries (v3.24 and before).
The format of include file and libraries changed in v3.25 to match
HI-TECH C compiler format .
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 81
-llibrary Search the library named library when linking.
The linker searches a standard list of directories for the library, which is
actually a fil e n am ed liblibrary.a. The linker then uses this file as if
it had been specified precisely by name.
It makes a difference where in the command you write this option; the
linker pr ocesses librarie s and obj ect file s in the orde r they ar e spec ified.
Thus, foo.o -lz bar.o search es li brar y z after file foo.o but before
bar.o. If bar.o refers to functions in libz.a, those function s ma y not
be loaded.
The directories searched include several standard system directories,
plus any that you specify with -L.
Normally the files found this way are library files (archive files whose
members a re object file s). The linker handles an arch ive file by sca nning
through it for members which define symbols that have so far been
referenced but not defined. But if the file that is found is an ordinary
object file, it is linked in the usual fashion. The only difference between
using an -l option (e.g., -lmylib) and specifying a file name (e.g.,
libmylib.a) is that -l searches several directo ries, as specified.
By default the linker is directed to search:
<install-path>\lib
for libraries specified with the -l option.
This behavior can be overridden using the environment variables
defined in Section 16.4 “Predefined Macro Names”.
-nodefaultlibs Do not use the s tan da rd syst em lib raries w hen li nking . Only the librarie s
you sp ecify will be pas sed to the linke r . Th e compil er may gen erate ca lls
to memcmp, memset and memcpy. These ent ries are usua lly resol ved by
entries in the standard compiler libraries. These entry points should be
supplied through some other mechanism when this option is specified.
-nostdlib Do not us e the standard system st artup file s or libraries when lin king. No
startup files and only the libraries you specify will be passed to the
linker. The compiler may generate calls to memcmp, memset and
memcpy. These entries are usually resolved by entries in standard
compiler libraries. These entry points should be supplied through some
other mechanism when this option is specified.
-s Remove all symbol table and relocation information from the
executable.
-T script Specify th e linker sc ript file, script, to be us ed at link tim e. This opt ion
is translated into the equivalent -T linker option .
-u symbol Pretend symbol is undefined to force linking of library modules to
define the symbol. It is legitimate to use -u multiple times with different
symbols to force loading of additional library modules.
-Wl,option Pass option as an option to the linker. If option contains commas, it
is split into multiple options at the commas.
For example, to generate a m ap file, use -W1, -Map=Project.map.
-Xlinker option Pass option as an option to the linker. You can use this to supply
system-specific linker options that the compiler does not know how to
recognize.
TABLE 3-16: LINKING OPTIONS (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 82 2012 Microchip Technology Inc.
3.7.10 Options for Directory Search
The following options specify to the compiler where to find directories and files to
search.
3.7.11 Options for Code Generation Conventions
Options of the form -fflag specify machine-independent flags. Most flags have both
positive and negative forms; the negative form of -ffoo would be -fno-foo. In the
table below, only one of the forms is listed (the one that is not the default.)
TABLE 3-17: DIRECTORY SEARCH OPTIONS
Option Definition
-specs=file Process fi le af ter the comp ile r read s in the s tandard specs file, in
order to override the defaults that the xc16-gcc driver program
uses when determining what switches to pass to xc16-cc1,
xc16-as, xc16-ld, etc. More than one -specs=file can be
specified on the command line, and they are processed in order,
from left to right.
TABLE 3-18: CODE GENERATION CONVENTION OPTIONS
Option Definition
-fargument-alias
-fargument-noalias
-fargument-
noalias-global
S pe cify the pos sible relati onship s among p arameters and betwe en
parameters and global data.
-fargument-alias specifies that arguments (parameters) ma y
alias each other and may alias global storage.
-fargument-noalias specifies that arguments do not alias
each other, but may alias global storage.
-fargument-noalias-global sp ecifies th at a r gum en t s do n ot
alias each other and do not alias global storage.
Each language will automatically use whatever option is required
by the language standard. You should not need to use these
options yourself.
-fcall-saved-reg Treat the register named reg as an allocatable re gis ter saved by
functions. It may be allocated even for temporaries or variables
that live across a call. Functions compiled this way will save and
restore the register reg if they use it.
It is an error to used this flag with the Frame Pointer or Stack
Pointer. Use of this flag for other registers that have fixed perva-
sive roles in the machine’s execution model will produce disas-
trous results.
A different sort of disaster will result from the use of this flag for a
register in which function values may be returned.
This flag should be used consistently through all modules.
-fcall-used-reg Treat the register named reg as an allocatable register tha t is
clobbered by function calls. It may be allocated for temporaries or
variabl es that do not liv e across a call. Fun ctions com piled this way
will not save and restore the register reg.
It is an error to use this flag with the Frame Pointer or Stack
Pointer. Use of this flag for other registers that have fixed perva-
sive roles in the machine’s execution model will produce disas-
trous results.
This flag should be used consistently through all modules.
-ffixed-reg Treat the register named reg as a fixed regi ster; generated c ode
should never refer to it (except perhaps as a Stack Pointer, Frame
Pointer or in some other fixed role).
reg must be the name of a register, e.g., -ffixed-w3.
-fno-ident Ignore the #ident directi ve .
Compiler Command-Line Driver
2012 Microchip Technology Inc. DS52071B-page 83
3.8 MPLAB IDE TOOLSUITE EQUIVALENTS
For information on related compiler options in MPLAB IDE, see the MPLAB Assembler ,
Linker and Utilities for PIC24 MCUs and dsPIC DSCs User’s Guide (DS51317).
-fpack-struct Pack all structure members together without holes. Usually you
would not want to use this option, since it makes the code
sub-opti mal, and t he of fset s of str ucture membe rs won’t agree wit h
system libraries.
The dsPIC® DSC device requires that words be aligned on even
byte boundaries, so care must be taken when using the packed
attribu te to avoid run time add ressing errors.
-fpcc-struct-
return Return short struct and union values in me mory like long er
ones, rather than in registers. This convention is less efficient, but
it has the advantage of allowing capability between the 16-bit com-
piler compiled files and files compiled with other compilers.
Short structures and unions are those whose size and alignment
match that of an integer type.
-fno-short-double By de faul t, th e c om pil er u ses a double type equi va len t to float.
This option makes double equivalent to long double. Mixing
this option across modules can have unexpected results if
modules share double data either directly through argument
passage or indirectly through shared buffer space. Libraries
provided with the product function with either switch setting.
-fshort-enums Allocate to an enum type only as many bytes as it needs for the
declared range of possible values. Specifically, the enum type will
be equivalent to the smallest integer type which has enough room.
-fverbose-asm
-fno-verbose-asm Put ex tra comment ary info rmation in the genera ted assem bly code
to make it more readable.
-fno-verbose-asm, the default, causes the extra information to
be omitted and is useful when comparing two assembler files.
-fvolatile Consider all memory references through pointers to be volatile.
-fvolatile-global Consider all memory references to external and global data items
to be volatile. The use of this switch has no effect on static data.
-fvolatile-static Consider all memory references to static data to be volatile.
TABLE 3-18: CODE GENERATION CONVENTION OPTIONS (CONTINUED)
Option Definition
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 84 2012 Microchip Technology Inc.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 85
Chapter 4. Device-Related Features
4.1 INTRODUCTION
The MPLAB XC16 C Compiler provides some features that are purely device-related.
• Device Sup por t
• Device Head er Files
•Stack
• Configuration Bit Access
• Using SFRs in MCUs
• Bit-Reversed and Modulo Addressing
4.2 DEVICE SUPPORT
As discussed in Chapter 1. “Compiler Overview”, the compiler supports all Microchip
16-bit devices; dsPIC30/33 digital signal controls (DSCs) and PIC24 microcontrollers
(MCUs).
To determine the device support for your version of the compiler, consult the release
notes file, README.html, in the installation folder. For MPLAB IDE users, select
Help>Release Notes.
4.3 DEVICE HE ADER FILES
One header file that is typically included in each C source file you will write is xc.h, a
generic header file that will include other device- and architecture-specific header files
when you build your project.
Inclusion of this file will allow access to SFRs via special variables, as well as macros
which allow special memory access or inclusion of special instructions.
Avoid including chip-specific header files into your code, as this will reduce portability.
However , device-specific compiler header files are stored in the support\family\h
directory for reference.
For information about assembly include files (*.inc), see the assembler
documentation.
4.3.1 Register Definition Files
The processor header files described in Section 4.5 “Configuration Bit Access”
name all SFRs for each part, but they do not define the addresses of the SFRs. A sep-
arate set of device-specific linker script files, one per part, is distributed in the
support\family\gld directory. These linker script files define the SFR addresses.
To use one of these files, specify the linker command-line option:
-T p30fxxxx.gld
where xxxx corresponds to the device part number.
For example, assuming that there is a file named app2010.c that contains an appli-
cation for the dsPIC30F2010 part, then it may be compiled and linked using the
following command line:
xc16-gcc -mcpu=30f2010 -o app2010.out -T p30f2010.gld app2010.c
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 86 2012 Microchip Technology Inc.
The -o command-line option names the output executable file, and the -T option gives
the linker script name for the dsPIC30F2010 part. If p30f2010.gld is not found in the
current directory , the linker searches in its known library paths. The default search path
inc ludes all locations of preinstalled libraries and linker scripts.
You should copy the appropriate linker script file (supplied with the compiler) into your
project directory before any project-specific modifications are made.
4.4 STACK
The 16-bit devices use what is referred to in this user’s guide as a “software stack”. This
is the typical stack arrangement employed by most computers and is ordinary data
memory accessed by a push-and-pop type instruction and a stack pointer register . The
term “hardware stack” is used to describe the stack employed by Microchip 8-bit
devices, which is only used for storing function return addresses.
The 16-bit devices dedicate register W15 for use as a software Stack Pointer. All
processor stack operations, including function calls, interrupts and exceptions, use the
software stack. The stack grows upward, towards higher memory addresses.
The dsPIC DSC device also supports stack overflow detection. If the Stack Pointer
Limit register, SPLIM, is initialized, the device will test for overflow on all stack opera-
tion s. If an overfl ow sho uld occ ur , the pr ocesso r will in itia te a st ack er ror ex cepti on. By
default, this will result in a processor Reset. Applications may also install a stack error
exception handler by defining an interrupt function named _StackError. See Chap-
ter 11. “Interrupts” for details.
The C run-time startup module initializes the Stack Pointer (W15) and the Stack Pointer
Limit register during the startup and initialization sequence. The initial values are
normally provided by the linker , which allocates the largest stack possible from unused
data memory. The location of the stack is reported in the link map output file.
Applications can ensure that at least a minimum-sized stack is available with the
--stack linker command-line option. See the MPLAB Asse mbl er, Li nker and U til ities
for PIC24 MCUs and dsPIC DSCs User’s Guide (DS51317) for details.
Alternatively , a stack of specific size may be allocated with a user-defined section from
an assembly source file. In the following example, 0x100 bytes of data memory are
reserved for the stack:
.section *,data,stack
.space 0x100
The linker will allocate an appropriately sized section and initialize __SP_init and
__SPLIM_init so that the run-time startup code can properly initialize the stack. Note
that since this is a normal assembly code section, attributes such as address may be
used to further define the stack. Please see the MPLAB Assembler , Linker and Utilities
for PIC24 MCUs and dsPIC DSCs User’s Guide (DS51317) for more information.
4.5 CONFIGURATION BIT ACCES S
Microchip devices have several locations which contain the configuration bits or fuses.
These bits specify fundamental device operation, such as the oscillator mode, watch-
dog timer, programming mode and code protection. Failure to correctly set these bits
may result in code failure or a non-running device.
Configuration settings macros are provided that can be used to set configuration bits.
For details, see Appendix G. “XC16 Configuration Settings”.
Device-Related Features
2012 Microchip Technology Inc. DS52071B-page 87
4.6 USING SFRS
The Special Function Registers (SFRs) are registers which control aspects of the MCU
operation or that of peripheral modules on the device. These registers are device mem-
ory 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
addr es s of th e re gi ste r. These variables can be ac ce ssed like an y or di na ry C varia bl e
so that no special syntax is required to access SFRs.
The SFR variable identifiers are predefined in header files and are accessible once you
have included the <xc.h> header file (see Section 4.3 “Device Header Files”) into
your source code. Structures with bit-fields are also defined so you may access bits
within a register in your source code.
A linker script file for the appropriate device must be linked into your project to ensure
the SFR variable identifiers are linked to the correct address. MPLAB IDE will link in a
default linker script, but a linker script file must be explicitly specified if you are driving
the command-line toolchain. Linker scripts have a .gld extension (e.g.
p30F6014.gld) and basic files are provided with the compiler.
The convention in the processor header files is that each SFR is named, using the
same name that appears in the data sheet for the part – for example, CORCON for the
Core Control register. If the register has individual bits that might be of interest, then
there will also be a structure defined for that SFR, and the name of the structure will be
the same as the SFR name, with “bits” appended. For example, CORCONbits for the
Core Control register . The individual bits (or bit fields) are named in the structure using
the names in the data sheet – for example PSV for the PSV bit of the CORCON
register.
Here is the complete definition of CORCON (subject to change):
/* CORCON: CPU Mode control Register */
extern volatile unsigned int CORCON __attribute__((__sfr__));
typedef struct tagCORCONBITS {
unsigned IF :1; /* Integer/Fractional mode */
unsigned RND :1; /* Rounding mode */
unsigned PSV :1; /* Program Space Visibility enable */
unsigned IPL3 :1;
unsigned ACCSAT :1; /* Acc saturation mode */
unsigned SATDW :1; /* Data space write saturation enable */
unsigned SATB :1; /* Acc B saturation enable */
unsigned SATA :1; /* Acc A saturation enable */
unsigned DL :3; /* DO loop nesting level status */
unsigned :4;
} CORCONBITS;
extern volatile CORCONBITS CORCONbits __attribute__((__sfr__));
See MPLAB Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs User’s
Guide (DS51317) for more information on using linker scripts.
For example, the following is a sample real-time clock. It uses an SFR, e.g. TMR1, as
well as bits within an SFR, e.g. T1CONbits.TCS. Descriptions for these SFRs are
found in the p30F6014.h file (this file will automatically be included by <xc.h> so you
do not need to include this into your source code). This file would be linked with the
device specific linker script which is p30F6014.gld.
Note: The symbols CORCON and CORCONbits refer to the same register and will
resolve to the same address at link time.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 88 2012 Microchip Technology Inc.
EXAMPLE 4-1: SAMPLE REAL-TIME CLOCK
/*
** Sample Real Time Clock for dsPIC
**
** Uses Timer1, TCY clock timer mode
** and interrupt on period match
*/
#include <xc.h>
/* Timer1 period for 1 ms with FOSC = 20 MHz */
#define TMR1_PERIOD 0x1388
struct clockType
{
unsigned int timer; /* countdown timer, milliseconds */
unsigned int ticks; /* absolute time, milliseconds */
unsigned int seconds; /* absolute time, seconds */
} volatile RTclock;
void reset_clock(void)
{
RTclock.timer = 0; /* clear software registers */
RTclock.ticks = 0;
RTclock.seconds = 0;
TMR1 = 0; /* clear timer1 register */
PR1 = TMR1_PERIOD; /* set period1 register */
T1CONbits.TCS = 0; /* set internal clock source */
IPC0bits.T1IP = 4; /* set priority level */
IFS0bits.T1IF = 0; /* clear interrupt flag */
IEC0bits.T1IE = 1; /* enable interrupts */
SRbits.IPL = 3; /* enable CPU priority levels 4-7*/
T1CONbits.TON = 1; /* start the timer*/
}
void __attribute__((__interrupt__,__auto_psv__)) _T1Interrupt(void)
{ static int sticks=0;
if (RTclock.timer > 0) /* if countdown timer is active */
RTclock.timer -= 1; /* decrement it */
RTclock.ticks++; /* increment ticks counter */
if (sticks++ > 1000)
{ /* if time to rollover */
sticks = 0; /* clear seconds ticks */
RTclock.seconds++; /* and increment seconds */
}
IFS0bits.T1IF = 0; /* clear interrupt flag */
return;
}
Device-Related Features
2012 Microchip Technology Inc. DS52071B-page 89
4.7 BIT-REV ERSED AND MODULO ADDRESSIN G
Bit-reversed and modulo addressing is supported on all dsPIC devices.
Bit-reversed addressing is used for simplifying and speeding-up the writes to X-space
data arrays in FFT (Fast Fourier Transform) algorithms. When enabled, pre-increment
or post-increment addressing modes will reverse the lower order address bits used by
instructions.
Modulo, or circular , addressing provides an automated means to support circular data
buffers using the dsPIC hardware. When used, software no longer needs to perform
data address boundary checks on arrays.
The compiler does not directly support the use of bit-reversed and modulo addressing;
that is, it cannot generate code from C source that assumes these addressing modes
are enabled when accessing memory. If either of these addressing modes are set up
on the target device, then it is the programmer’s responsibility to ensure that the com-
piler does not use those registers that are specified to use either modulo or bit-reversed
addressing as pointers. Particular care must be exercised if interrupts can occur while
one of these addressing modes is enabled.
It is possible to define arrays in C that will be suitably aligned in memory for modulo
addressing by hand-written assembly language functions. The aligned attribute may
be used to define arrays that are positioned for use as incrementing modulo buffers.
Initialization of the start and end addresses, as well as the registers that modulo
address is applied must be written by hand to match the array specification. The
reverse attribute may be used to define arrays that are positioned for use as decre-
menting modulo buffers. For more information on these attributes, see
Section 10.2.1 “Function Specifiers”. For more information on bit-reversed or mod-
ulo addressing, see Chapter 3 of the “dsPIC30F Family Reference Manual” (DS70046).
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 90 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 91
Chapter 5. Differe nces Between MPLAB XC16 and ANSI C
This compiler conforms to the ANS X3.159-1989 Standard for programming languages.
This is commonly called the C89 Standard. It is referred to as the ANSI C Standard in
this manual. Some features from the later standard C99 are also supported.
• Divergence from the ANSI C Standard
• Extensions to the ANSI C Standard
• Implementation-Defined Behavior
5.1 DIVERGENCE FROM THE ANSI C STANDARD
There are no divergences from the ANSI C standard.
5.2 EXTENSIONS TO THE ANSI C STANDARD
The MPLAB XC16 C Compiler provides extensions to the ANSI C standard in these
areas: keywords and expressions.
5.2.1 Keyword Differences
The new keywords are part of the base GCC implementation and the discussions in the
referenced sections are based on the standard GCC documentation, tailored for the
specific syntax and semantics of the 16-bit compiler port of GCC.
• Specifying Attributes of Variables – Section 6.11 “Variable Attributes”
• Specifying Attributes of Functions – Section 10.2.1 “Function Specifiers”
• Inline Functions – Section 10.6 “Inline Functions”
• Variables in Specified Registers – Section 7.9 “Allocation of Variables to Reg-
isters”
• Comple x Numb ers – Section 6.7 “Complex Data Types”
5.2.2 Expression Differences
Expression differences are:
• Binary Constants – Section 6.8 “Literal Constant Types and Formats”.
5.3 IMPLEMENTATION-DEFINED BEHAVIOR
Certain features of the ANSI C standard have implementation-defined behavior. This
means that the exact behavior of some C code can vary from compiler to compiler.
The exact behavior of the MPLAB XC16 C Compiler is detailed throughout this
documentation, and is fully summarized in Appendix A. “Implementation-Defined
Behavior”.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 92 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 93
Chapter 6. Supp orte d Da ta Type s and Variables
6.1 INTRODUCTION
The MPLAB XC16 C Compiler supports a variety of data types and qualifiers (attri-
butes). These data types and variables are discussed here. For information on where
variables are stored in memory, see Chapter 7. “Memory Allocation and Access”.
• Identifiers
• Integer Data Types
• Floating-Point Data Types
• St ructu res and Uni ons
• Pointer Types
• Comple x Data Types
• Literal Constant Types and Formats
• Standard Type Qualifiers
• Compiler-Specific type Qualifiers
• Variable Attributes
6.2 IDENTIFIERS
A C variable identifier (as well as a function identifier) 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 the MPLAB
Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs User’s Guide
(DS51317).
Identifier s are case se ns iti ve, so main is different from Main.
All characters are significant in an identifier, although identifiers longer than 31
characters in length are less portable.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 94 2012 Microchip Technology Inc.
6.3 INTEGER DATA TYPES
Table 6-1 shows integer data types that are supported in the compiler. All unspecified
or signed integer data types are arithmetic type signed integer. All unsigned integer
data types are arithmetic type unsigned integer.
There is no type for sto ring si ngl e bit quan tities .
All integer values are specified in little endian format, which means:
• The least significant byte (LSB) is stored at the lowest address
• The least significant bit (LSb) is stored at the lowest-numbered bit position
As an example, the long value of 0x12345678 is stored at address 0x100 as foll ows:
As another example, the long value of 0x12345678 is stored in registers w4 and w5:
Signed values are stored as a two’s complement integer value.
Preprocessor macros that specify integer minimum and maximum values are available
after including <limits.h> in your source code, located by default in:
<install directory>\include
As the size of data types is 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.
For information on implementation-defined behavior of integers, see
Section A.6 “Integers”.
6.3.1 Double-Word Integers
The compiler supports data types for integers that are twice as long as long int.
Simply write long long int for a signed integer, or unsigned long long int
for an unsigned integer . To make an integer constant of type long long int, add the
suffix LL to the integer. To make an integer constant of type unsigned long long
int, add the suffix ULL to the integer.
You can use these types in arithmetic like any other integer types.
TABLE 6-1: INTEGER DATA TYPES
Type Bits Min Max
char, signed char 8 -128 127
unsigned char 80255
short, signed short 16 -32768 32767
unsigned short 16 0 65535
int, signed int 16 -32768 32767
unsigned int 16 0 65535
long, signed long 32 -231 231 - 1
unsigned long 32 0 232 - 1
long long*, signed long long* 64 -263 263 - 1
unsigned long long* 64 0 264 - 1
* ANSI-89 extension
0x100 0x101 0x102 0X103
0x78 0x56 0x34 0x12
w4 w5
0x5678 0x1234
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 95
6.3.2 char Types
The compiler supports data types for char, which defaults to signed char. An option
can be used to use unsigned char as the defaul t, see Section 3.7.3 “Options for
Controlling the C Dialect”.
It is a common misconception that the C char types are intended purely for ASCII char-
acter manipulation. This is not true; indeed, the C language makes no guarantee that
the default character representation is even ASCII (however , this implementation does
use ASCII as the character representation). The char types are sim ply the smalle st 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 XC16 C Compiler, the char types will commonly be
used for a number of purposes: as 8-bit integers, as storage for ASCII characters, and
for access to I/O locations.
6.4 FLOATING-POINT DATA TYPES
The compiler uses the IEEE-754 format. Table 6-2 shows floating point data types that
are supported. All floating point data types are arithmetic type real.
All floating point values are specified in little endian format, which means:
• The least significant byte is stored at the lowest address
• The least significant bit is stored at the lowest-numbered bit position
As an example, the double value of 1.2345678 is stored at address 0x100 as follows:
As another example, the long value of 1.2345678 is stored in registers w4 and w5:
Floating-point types are always signed and the unsigned keyword is illegal when
specifying a floating-point type.
Preprocessor macros that specify valid ranges are available after including
<float.h> in your source code.
For information on implementation-defined behavior of floating point numbers, see
section Section A.7 “Floating Point”.
TABLE 6-2: FLOATING POINT DATA TYPES
Type Bits E Min E Max N Min N Max
float 32 -126 127 2-126 2128
double* 32 -126 127 2-126 2128
long double 64 -1022 1023 2-1022 21024
E = Exponent
N = No rmalized (appr oximate)
* double is equivalent to long double if -fno-short-double is used.
0x100 0x101 0x102 0X103
0x51 0x06 0x9E 0x3F
w4 w5
0x0651 0x3F9E
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 96 2012 Microchip Technology Inc.
6.5 STRUCTURES AND UNIONS
MPLAB XC16 C Compiler supports struct and union types. Structures and unions
only differ in the memory offset applied to each member.
These types will be at least 1 byte wide. Bit-fields are fully supported in structures.
S tructures and unions may be passed freely as function arguments and function return
values. Pointers to structures and unions are fully supported.
Implementation-defined behavior of structures, unions and bit-fields is described in
Section A.10 “Structures, Unions, Enumerations and Bit Fields”.
6.5.1 Structure and Union Qualifiers
The MPLAB XC16 C Compiler supports the use of type qualifiers on structures. When
a qualifier is applied to a structure, all of its members will inherit this qualification. In the
following example, the structure is qualified const.
const struct foo {
int number;
int *ptr;
} record = { 0x55, &i };
In this case, the entire structure may be placed into the program space where each
member will be read-only. Remember that all members are usually initialized if a
structure is const as they cannot be initialized at runtime.
If the members of the structure were individually qualified const, but the structure was
not, then the structure would be positioned into RAM, but each member would be still
be read-only. Compare the following structure with the one above.
struct {
const int number;
int * const ptr;
} record = { 0x55, &i};
6.5.2 Bit-Fields in Structures
The MPLAB XC16 C Compiler fully supports bit-fields in structures.
Bit-fields are, by default, signed int. They may be made an unsigned int bit field
by using a command line option, see Section 3.7.3 “Options for Controlling the C
Dialect”.
The first bit defined will be the LSb of the word in which it will be stored.
The compiler supports bit fields with any bit size, up to the size of the underlying type.
Any integral type can be made into a bit f ield. Th e allocation does not no rmally cross a
bit boundary natural to the underlying type.
For example:
struct foo {
long long i:40;
int j:16;
char k:8;
} x;
struct bar {
long long I:40;
char J:8;
int K:16;
} y;
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 97
struct foo will have a size of 10 bytes using the c ompiler. i will be allocated at bit
offset 0 (through 39). There will be 8 bits of padding before j, allocated at bit offset 48.
If j were allocated at the next available bit offset, 40, it would cross a storage boundary
for a 16 bit integer . k will be allocated after j, at bit offset 64. The structure will contain
8 bits of padding at the end to maintain the required alignment in the case of an array.
The alignment is 2 bytes because the largest alignment in the structure is 2 bytes.
struct bar will have a size of 8 bytes using the compiler. I will be allocated at bit
offset 0 (through 39). There is no need to pad before J because it will not cross a
storage boundary for a char. J is allocated at bit offset 40. K can be allocated starting
at bit offset 48, completing the structure without wasting any space.
Unnamed bit-fields may be declared to pad out unused space between active bits in
control registers. For example:
struct foo {
unsigned lo : 1;
unsigned : 6;
unsigned hi : 1;
} x;
A structure with bit-fields may be initialized by supplying a comma-separated list of ini-
tial values for each field. For example:
struct foo {
unsigned lo : 1;
unsigned mid : 6;
unsigned hi : 1;
} x = {1, 8, 0};
S tructures with unnamed bit fields may be initialized. No initial value should be supplied
for the unnamed members, for example:
struct foo {
unsigned lo : 1;
unsigned : 6;
unsigned hi : 1;
} x = {1, 0};
will initialize the members lo and hi correctly.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 98 2012 Microchip Technology Inc.
6.6 POINTER TYPES
There are two basic pointer types supported by the MPLAB XC16 C Compiler: data
pointers and function pointers. Data pointers hold the addresses of variables which can
be indirectly read, and possibly indirectly written, by the program. Function pointers
hold the address of an executable function which can be called indirectly via the pointer .
6.6.1 Combining Type Qualifiers and Pointers
It is helpful to first review the ANSI C standard conventions for definitions of pointer
types.
Pointers can be qualified like any other C object, but care must be taken when doing
so as there are two quantities associated with pointers. The first is the actual pointer
itself, which is treated like any ordinary C variable and has memory reserved for it. The
second is the target, or targets, that the pointer references, or to which the pointer
points. The general form of a pointer definition looks like the following:
target_type_&_qualifiers * pointer’s_qualifiers pointer’s_name;
Any qualifiers to the right of the * (i.e., next to the pointer’ s name) relate to the pointer
variable itself. The type and any qualifiers to the left of the * relate to the pointer’s tar-
gets. This makes sense since it is also the * operator that dereferences a pointer , which
allows you to get from the pointer variable to its current target.
Here are three examples of pointer definitions using the volatile qualifier . The fields
in the definitions have been highlighted with spacing:
volatile int * vip ;
int * volatile ivp ;
volatile int * volatile vivp ;
The first example is a pointer called vip. It contains the address of int objects that
are qualified volatile. The pointer itself – the variable that holds the address – is not
volatile; however, the objects that are accessed when the pointer is dereferenced
are treated as being volatile. In other words, the target objects accessible via the
pointer may be externally modified.
The second example is a pointer called ivp which also contains the address of int
objects. In this example, the pointer itself is volatile, that is, the address the pointer
contains may be externally modified; however, the objects that can be accessed when
dereferencing the pointer are not volatile.
The last example is of a pointer called vivp which is itself qualified volatile, and
which also holds the address of volatile objects.
Bear in mind that one pointer can be assigned the addresses of many objects; for
example, a pointer that is a parameter to a function is assigned a new object address
every time the function is called. The definition of the pointer must be valid for every
target address assigned.
Note: Care must be taken when describing pointers. Is a “const pointer” a pointer
that points to const object s, or a po int er t hat is const itself? You can talk
about “pointers to const” and “const pointers” to help clarify the definition,
but such terms may not be universally understood.
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 99
6.6.2 Data Pointers
All standard data pointers are 16 bits wide. This is sufficient to access the full data
memory space.
These pointers are also able to access const-qualified objects, although in the pro-
gram memory space, const-qualified objects appear in a unique memory range in the
data space using the PSV window . In this case, the -mconst-in-data option should
not be in force (see Section 3.7.1 “Options Specific to 16-Bit Devices”.)
Pointers which access the managed PSV space are 32-bits wide. The extra space
allows these pointers to access any PSV page.
A set of special purpose, 32-bit data pointers are also available. See Chapter
7. “ Me mo ry Alloca tion an d Access” for more information.
6.6.3 Function Pointers
The MPLAB XC16 C Compiler fully supports pointers to functions, which allows func-
tions to be called indirectly. Function pointers are always 16 bits wide.
In the small code model (up to 32 kWords of code), 16-bit wide function pointers can
access any function location. In the large code model, which supports more than 32
kWords of code, pointers hold the address of a GOTO instruction in a lookup table.
These instructions are able to reach any memory location, but the lookup table itself is
located in the lower program memory, thus allowing the pointers themselves to remain
as 16-bit wide variables.
As function pointers are only 16-bits wide, these pointers cannot point beyond the first
64K of FLASH. Should the address of a function that is allocated beyond the first 64K
of FLASH be taken, the linker will arrange for a handle section to be generated. The
handle section will always be allocated within the first 64K. Each handle provides a
level of indirection which allows 16-bit pointers to access the full range of FLASH. This
operation may be disable with the --no-handles linke r opti o n .
6.6.4 S pecial Pointer Target s
Pointers and integers are not interchangeable. Assigning an integer value to a pointer
will generate a warning to this effect. For example:
const char * cp = 0x123; // the compiler will flag this as bad code
There is no information in the integer , 0x123, relating to the type, size or memory loca-
tion of the destination. Avoid assigning an integer (whether it be a constant or variable)
to a pointer at all times. Addresses assigned to pointers should be derived from the
address operator “&“ that C provides.
In instances where you need to have a pointer reference a seemingly arbitrary address
or address range, consider defining an object or label at the desired location. If the
object is defined in assembly code, use a C declaration (using the extern keywor d)
to create a C object which links in with the external object and whose address can be
taken.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 100 2012 Microchip Technology Inc.
Take care when comparing (subtracting) pointers. For example:
if(cp1 == cp2)
; take appropriate action
The ANSI C standard only allows pointer comparisons when the two pointer targets are
the same object. The address may extend to one element past the end of an array.
Comparisons of pointers to integer constants are even more risky, for example:
if(cp1 == 0x246)
; take appropriate action
A NULL pointer is the one instance where a constant value can be safely assigned to a
pointer. A NULL pointer is numerically equal to 0 (zero), but since they do not guarantee
to point to any valid object and should not be dereferenced, this is a special case
imposed by the ANSI C standard. Comparisons with the macro NULL are also allowed.
6.7 COMPLEX DATA TYPES
The compiler supports complex data types. You can declare both complex integer
types and complex floating types, using the keyword __complex__.
For example, __complex__ float x; declares x as a variable whose real part and
imaginary part are both of type float. __complex__ short int y; declares y to
have real and ima ginar y parts of type short int.
To write a constant with a complex data type, use the suffix ‘i’ or ‘j’ (either one; they
are equivalent). For example, 2.5fi has type __complex__ float and 3i has type
__complex__ int. Such a constant is a purely imaginary value, but you can form
any complex value you like by adding one to a real constant.
To extract the real part of a complex-valued expression exp, write __real__ exp.
Similarly, use __imag__ to extract the imaginary part. For example;
__complex__ float z;
float r;
float i;
r = __real__ z;
i = __imag__ z;
The operator, ~, performs complex conjugation when used on a value with a complex
type.
The compiler can allocate complex automatic variables in a noncontiguous fashion; it’s
even possible for the real part to be in a register while the imaginary part is on the stack
(or vice-versa). The debugging information format has no way to represent noncontig-
uous allocations like these, so the compiler describes noncontiguous complex
variables as two separate variables of noncomplex type. If the variable’s actual name
is foo, the two fictitious variables are named foo$real and foo$imag.
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 101
6.8 LITERAL CONSTANT TY PES AND FORMATS
A literal constant is used to represent a numerical value in the source code; for exam-
ple, 123 is a constant. Like any value, a literal constant must have a C type. In addition
to a literal constant’s type, the actual value can be specified in one of several formats.
The format of integral literal constants specifies their radix. MPLAB XC16 supports the
ANSI standard radix specifiers as well as ones which enables binary constants to be
specifi ed in C code.
The formats used to specify the radices are given in Table 6-3. The letters used to spec-
ify binary or hexadecimal radices are case insensitive, as are the letters used to specify
the hexadecimal digits.
Any integral literal constant will have a type of int, long int or long long int,
so that the type can hold the value without overflow . Literal constants specified in octal
or hexadecimal may also be assigned a type of unsigned int, unsigned long
int or unsigned long long int if the signed counterparts are too small to hold
the value.
The default types of literal constants may be changed by the addition of a suffix after
the digits, e.g. 23U, wher e U is the suffix. Table 6-4 shows the possible combination of
suffixes and the types that are considered when assigning a type. So, for example, if
the suffix l is specified and the value is a decimal literal constant, the compiler will
assign the type long int, if that type will hold the lineal constant; otherwise, it will
assigned long long int. If the literal constant was specified as an octal or
hexadecimal constant, then unsigned types are also considered.
TABLE 6-3: RADIX FORMATS
Radix Format Example
binary 0b number or 0B number 0b10011010
octal 0 number 0763
decimal number 129
hexadecimal 0x number or 0X number 0x2F
TABLE 6-4: SUFFIXES AND ASSIGNED TYPES
Suffix Decimal Octal or Hexadecimal
u or U unsigned int
unsigned long int
unsigned long long int
unsigned int
unsigned long int
unsigned long long int
l or L long int
long long int long int
unsigned long int
long long int
unsigned long long int
u or U, and l or L unsigned long int
unsigned long long int unsigned long int
unsigned long long int
ll or LL long long int long long int
unsigned long long int
u or U, and ll or LL unsigned long long int unsigned long long int
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 102 2012 Microchip Technology Inc.
Here is an example of code that may fail because the default type assigned to a literal
constant is not appropriate:
unsigned long int result;
unsigned char shifter;
void main(void)
{shifter = 20;
result = 1 << shifter;
// code that uses result
}
The literal constant 1 will be assigned an int type; hence the result of the shift opera-
tion will be an int and the upper bits of the long variab le, result, can never be set,
regardless of how much the literal constant is shifted. In this case, the value 1 shifted
left 20 bits will yield the result 0, not 0x100000.
The following uses a suffix to change the type of the literal constant, hence ensure the
shift result has an unsigned long type.
result = 1UL << shifter;
Floating-point literal constants have double type unless suffixed by f or F, in which
case it is a float constant. The suffixes l or L specif y a long double type. In
MPLAB XC16, the double type equates to a 32-bit float type. The command line
option, -fno-short-double, may be use to specify double as a 64-bit long
double type.
Character literal constants are enclosed by single quote characters, ’, for example
’a’. A character literal constant has int type, although this may be optimized to a
char type later in the compilation.
Multi-byte character literal constants are supported by this implementation.
S tring constants, or string literals, are enclosed by double quote characters ", for exam-
ple "hello world". The type of string literal constants is const char * and the
character that make up the string may be stored in the program memory.
To comply with the ANSI C standard, the compiler does not support the extended char-
acter set in characters or character arrays. Instead, they need to be escaped using the
backslash character, as in the following example:
const char name[] = "Bj\xf8k";
printf("%s's Resum\xe9", name); \\ prints "Bjørk's Resumé"
Defining and initializing a non-const array (i.e. not a pointer definition) with a string,
for example:
char ca[]= "two"; // "two" different to the above
is a special case and produces an array in data space which is initialized at startup with
the string "two", whereas a string literal constant used in other contexts represents an
unnamed array, accessed directly from its storage location.
The compiler will use the same storage location and label for strings that have identical
character sequences, except where the strings are used to initialize an array residing
in the data space as shown in the last statement in the previous example.
T wo adjacent string literal constants (i.e. two strings separated only by white space) are
concatenated by the C preprocessor. Thus:
const char * cp = "hello " "world";
will assign the pointer with the address of the string "hello world ".
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 103
6.9 STANDARD TYPE QUALIFIERS
Type qualifiers provide additional information regarding how an object may be used.
The MPLAB XC16 compiler supports both ANSI C qualifiers and additional special
qualifiers which are useful for embedded applications and which take advantage of the
PIC MCU and dsPIC DSC architectures.
6.9.1 Const Type Qualifier
The compiler supports the use of the ANSI type qualifiers const and volatile.
The const type qualifier is used to tell the compiler that an object is read only and will
not be modified. If any attempt is made to modify an object declared const, the
compiler will issue a warning or error.
User-defined objects declared const are placed, by default, in the program space and
may be accessed via the program visibility space, see Section 7.4 “V ariables in Pro-
gram Spa ce”. Usually a const object must be initialized when it is declared, as it
cannot be assigned a value at any point at runtime. For example:
const int version = 3;
will define version as being an int variable that will be placed in the program mem-
ory, will always contain the value 3, and which can never be modified by the program.
The memory model -mconst-in-data will allocate const-qualified objects in data
space, which may be writable.
6.9.2 Volatile Type Qualifier
The volatile type qualifier is used to tell the compiler that an object cannot be guar-
anteed to retain its value between successive accesses. 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.
Any SFR which can be modified by hardware or which drives hardware is qualified as
volatile, and any variables which may be modified by interrupt routines should use
this qualifier as well. For example:
extern volatile unsigned int INTCON1 __attribute__((__sfr__));
The code produced by the compiler to access volatile objects may be different to
that to access ordinary variables, and typically the code will be longer and slower for
volatile objects, so only use this qualifier if it is necessary. However failure to use
this qualifier when it is required may lead to code failure.
Another use of the volatile keyword is to prevent variables being removed if they
are not used in the C source. If a non-volatile variable is never used, or used in a
way that has no effect on the program’s function, then it may be removed before code
is generated by the compiler.
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. For example the entire
statement:
PORTB;
will produce assembly code the reads PORTB, but does nothing with this value. This is
useful for some peripheral registers that require reading to reset the state of interrupt
flags. Normally such a statement is not encoded as it has no effect.
Some variables are treated as being volatile even though they may not be qualified
in the source code. See Chapter 13. “Mixing C and Assembly Code” if you have
assembly code in your project.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 104 2012 Microchip Technology Inc.
6.10 COMPILER -SPECIFIC TYPE QUALIFIERS
The MPLAB XC16 C Compiler supports special type qualifiers, all of which allow the
user to control how variables are accessed.
6.10.1 __psv__ Type Qualifier
The __psv__ qualifier can be applied to variables or pointer targets that have been
allocated to the program memory space. It indicates how the variable or pointer targets
will be accessed/read. Allocation of variables to the program memory space is a sepa-
rate process and is made using the space attribute, so this qualifier is often used in
conjunction with that attribute when the variable is defined. For example:
__psv__ unsigned int __attribute__((space(psv))) myPSVvar = 0x1234;
__psv__ char * myPSVpointer;
The pointer in this example does not use the space attribute as it is located in data
memory, but the qualifier indicates how the pointer targets are to be accessed. For
more information on the space attribute and how to allocate variables to the Flash
memory, see Section 6.11 “Variable Attributes”. For basic information on the
memory layout and how program memory is accessed by the device, see
Section 7.2 “Address Spaces”.
When variables qualified as __psv__ are read, the compiler will manage the selection
of the program memory page visible in the data memory window. This means that you
do not need to adjust the PSVPAG SFR explicitly in your source code, but the gener-
ated code may be slightly less efficient than that produced if this window was managed
by hand.
The compiler will assume that any object or pointer target qualified with __psv__ will
wholly fit within a single PSV page. Such is the case for objects allocated memory using
the psv or auto_psv space attribute. If this is not the case, then you should use the
__prog__ qualifier (see Section 6.10.2 “__prog__ Type Qualifier”) and an
appropriate space attribute.
6.10.2 __prog__ Type Qualifier
The __prog__ qualifier is similar to the __psv__ qualifier (see
Section 6.10.1 “__psv__ Type Qualifier”), but indicates to the compiler that the qual-
ified variable or pointer target may straddle PSV pages. As a result, the compiler will
generate code so these qualified objects can be read correctly, regardless of which
page they are allocated to. This code may be longer than that to access variables or
pointer targets which are qualified __psv__. For example:
__prog__ unsigned int __attribute__((space(prog))) myPROGvar = 0x1234;
__prog__ char * myPROGpointer;
The pointer in this example does not use the space attribute as the it is located in data
memory, but the qualifier indicates how the pointer targets are to be accessed. For
more information on the space attribute and how to allocate variables to the Flash
memory, see Section 6.11 “Variable Attributes”. And, see Section 7.2 “Address
Spaces” for basic information on the memory layout and how program memory is
accessed by the device.
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 105
6.10.3 __eds__ Type Qualifier
The __eds__ qualifier indicates that the qualified object has been located in an EDS
accessible memory space and that the compiler should manage the appropriate regis-
ters used to access this memory.
When used with pointers, it implies that the compiler should make few assumptions as
to the memory space in which the pointer target is located and that the target may be
in one of several memory spaces, which include: space(data) (and its subsets), eds,
space(eedata), space(prog), space(psv), space(auto_psv), and on some
devices space(pmp). Not all devices support all memory spaces. For example
__eds__ unsigned int __attribute__((eds)) myEDSvar;
__eds__ char * myEDSpointer;
The compiler will automatically assert the page attribute to scalar variable declarations;
this allows the compiler to generate more efficient code when accessing larger data
types. Remember , scalar variables do not include structures or arrays. To force paging
of a structure or array, please manually use the page attribute and the co mpi le r will
prevent the object from crossing a page boundary.
For read access to __eds__ qualified variables will automatically manipulate the
PSVPAG or DSRPAG register (as appropriate). For devices that support extended data
space memory, the compiler will also manipulate the DSWPAG register.
For more on this qualifier, see Section 7.7 “Extended Data S pace Access”.
6.10.4 __pack_upper_byte Type Qualifier
This qualifier allows the use of the upper byte of Flash memory for data storage. For
16-bit devices, a 24-bit word is used in Flash memory. The architecture supports the
mapping of areas of Flash into the data space, but this mapping is only 16 bits wide to
fit in with data space dimensions, unless the __pack_upper_byte qualifier is used.
For more information on this qualifier, see Section 7.8 “Packing Data Stored in
Flash”.
6.10.5 __pmp__ Type Qualifier
This qualifier may be used with those devices that contain a Parallel Master Port (PMP)
peripheral, which allows the connection of various memory and non-memory devices
directly to the device. When variables or pointer targets qualified with __pmp__ are
accessed, the compiler will generate the appropriate sequence for accessing these
objects via the PMP peripheral on the device. For example:
__pmp__ int auxDevice
__attribute__((space(pmp(external_PMP_memory))));
__pmp__ char * myPMPpointer;
In addition to the qualifier , the int variable uses a memory space which would need to
be predefined. The pointer in this example does not use the space attribute as the it is
located in data memory, but the qualifier indicates how the pointer targets are to be
accessed. For more information on the space attribute, see Section 6.11 “Variable
Attributes”. For basic information on the memory layout and how program memory is
accessed by the device, see Section 7.2 “Address Spaces”.
For more on the qualifier, see Section 7.5 “Parallel Master Port Access”.
Note: Some devices use DSRPAG to represent extended read access to FLASH
or the extended data space (EDS)
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 106 2012 Microchip Technology Inc.
6.10.6 __exter nal__ Type Qualifier
This qualifier is used to indicate that the compiler should access variables or pointer
targets which have been located in external memory . These memories include any that
have been attached to the device, but which are not, or cannot, be accessed using the
parallel master port (PMP) peripheral (see Section 6.10.5 “__pmp__ Type Quali-
fier”.) Access of objects in external memory is similar to that for PMP access, but the
routines that do so are fully configurable and, indeed, need to be defined before any
access can take place. See Section 7.6 “External Memory Access” for full informa-
tion on how the memory space are configured and access routines are defined.
The qualifier is used as in the following example.
__external__ int external_array[256]
__attribute__((space(external(external_memory))));
__external__ char * myExternalPointer;
In addition to the qualifier , the array uses a memory space which would need to be pre-
defined. The pointer in this example does not use the space attribute as the it is
located in data memory, but the qualifier indicates how the pointer targets are to be
accessed. For more information on the space attribute, see Section 6.11 “Variable
Attributes”. For basic information on the memory layout and how program memory is
accessed by the device, see Section 7.2 “Address Spaces”.
For more on the qualifier, see Sectio n 7.6 “External Memory Acces s”.
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 107
6.11 VARIABLE ATTRIBUTES
The MPLAB XC16 C Compiler uses attributes to indicate memory allocation, type and
other configuration for variables, structure members and types. Other attributes are
available for functions, and these are described in Section 10.2.2 “Function Attri-
butes”. Qualifiers, listed in Section 6.10 “Compiler-Specific type Qualifiers”, are
used independently to attributes. They only indicate how objects are accessed, but
must be used where necessary to ensure correct code operation.
The compiler keyword __attribute__ allows you to specify the attributes of objects.
This keyword is followed by an attribute specification inside double parentheses. The
following attributes are currently supported for variables:
•address (addr)
• aligned (alignment)
•boot
•deprecated
• eds
•fillupper
•far
•mode (mode)
•near
•noload
•page
•packed
•persistent
•reverse (alignment)
•section ("section-name")
•secure
•sfr (address)
•space (space)
•transparent_union
•unordered
•unsupported(message)
•unused
•weak
You may also specify attributes with __ (double underscore) preceding and following
each keyword (e.g., __aligned__ instead of aligned). This allows you to use them
in header files without being concerned about a possible macro of the same name.
To specify multiple attributes, separate them by commas within the double
parentheses, for example:
__attribute__ ((aligned (16), packed)).
Note: It is important to use variable attributes consistently throughout a project.
For example, if a variable is defined in file A with the far attribute, and
declared extern in file B without far, then a link error may result.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 108 2012 Microchip Technology Inc.
address (addr)
The address attribute specifies an absolute address for the variable. This attribute
can be used in conjunction with a section attribute. This can be used to start a group
of variables at a specific address:
int foo __attribute__((section("mysection"),address(0x900)));
int bar __attribute__((section("mysection")));
int baz __attribute__((section("mysection")));
A variable with the address attribute cannot be placed into the auto_psv spac e (see
the space() attribute or the -mconst-in-code option); attempts to do so will cause
a warning and the compiler will place the variable into the PSV space. If the variable is
to be placed into a PSV section, the address should be a program memory address.
aligned (alignment)
This attribute specifies a minimum alignment for the variable, measured in bytes. The
alignment must be a power of two. For example, the declaration:
int x __attribute__ ((aligned (16))) = 0;
causes the compiler to allocate the global variable x on a 16-byte boundary. On the
dsPIC DSC device, this could be used in conjunction with an asm expression to access
DSP instructions and addressing modes that require aligned operands.
As in the preceding example, you can explicitly specify the alignment (in bytes) that you
wish the compiler to use for a given variable. Alternatively, you can leave out the
alignment factor and just ask the compiler to align a variable to the maximum useful
alignment for the dsPIC DSC device. For example, you could write:
short array[3] __attribute__ ((aligned));
Whenever you leave out the alignment factor in an aligned attribute specification, the
compiler automatically sets the alignment for the declared variable to the largest
alignment for any data type on the target machine – which in the case of the dsPIC DSC
device is two bytes (one word).
The aligned attribute can only increase the alignment; you can decrease it by spec-
ifying packed (see below). The aligned attribute conflicts with the reverse attribute.
It is an error condition to specify both.
The aligned attribute can be c ombined with the section attribute. This will allow the
alignment to take place in a named section. By default, when no section is specified,
the compiler will generate a unique section for the variable. This will provide the linker
with the best opportunity for satisfying the alignment restriction without using internal
padding that may happen if other definitions appear within the same aligned section.
boot
This attribute can be used to define protected variables in Boot Segment (BS) RAM:
int __attribute__((boot)) boot_dat[16];
Variables defined in BS RAM will not be initialized on startup. Therefore all variables in
BS RAM must be initialized using inline code. A diagnostic will be reported if initial
values are specified on a boot variable.
An example of initialization is as follows:
int __attribute__((boot)) time = 0; /* not supported */
int __attribute__((boot)) time2;
void __attribute__((boot)) foo()
{
time2 = 55; /* initial value must be assigned explicitly */
}
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 109
deprecated
The deprecated attribute causes the declaration to which it is attached to be specially
recognized by the compiler. When a deprecated function or variable is used, the
compiler will emit a warning.
A deprecated definition is still defined and, therefore, present in any object file. For
example, compiling the following file:
int __attribute__((__deprecated__)) i;
int main() {
return i;
}
will produce the warni ng:
deprecated.c:4: warning: `i’ is deprecated (declared
at deprecated.c:1)
i is still defined in the resulting object file in the normal way.
eds
In the attribute context, the eds (extended data space) attribute indicates to the com-
piler that the variable will be allocated anywhere within data memory . V ariables with this
attribute will likely also the __eds__ type qualifier (see Section 7.7 “Extended Data
Space Access”) for the compiler to properly generate the correct access sequence.
Not that the __eds__ qualifier and the eds attribute are closely related, but not identi-
cal. On some devices, eds may need to be specified when allocating variables into cer-
tain memory spaces such as space (ymemory) or space (dma) as this memory
may only exist in the extended data space.
fillupper
This attribute can be used to specify the upper byte of a variable stored into a
space(prog) section.
For example:
int foo[26] __attribute__((space(prog),fillupper(0x23))) = { 0xDEAD };
will fill the upper bytes of array foo with 0x23, instead of 0x00. foo[0] will still be
initialized to 0xDEAD.
The command line option -mfillupper=0x23 will perform the same function.
far
The far attribute tells the compiler that the variable will not necessarily be allocated in
near (first 8 KB) data space, (i.e., the variable can be located anywhere in data memory
between 0x0000 and 0x7FFF).
mode (mode)
This attribute specifies the data type for the declaration as whichever type corresponds
to the mode mode. This in effect lets you request an integer or floating point type
according to its width. Valid values for mode are as follows:
Mode Width Compiler Type
QI 8 bits char
HI 16 bi ts int
SI 32 bi ts long
DI 64 bi ts long long
SF 32 bi ts float
DF 64 bi ts long double
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 110 2012 Microchip Technology Inc.
This attribute is useful for writing code that is portable across all supported compiler tar-
gets. For example, the following function adds two 32-bit signed integers and returns a
32-bit signed integer result:
typedef int __attribute__((__mode__(SI))) int32;
int32
add32(int32 a, int32 b)
{
return(a+b);
}
You may also specify a mode of byte or __byte__ to indicate the mode correspond-
ing to a one-byte integer , word or __word__ for the mode of a one-word integer , and
pointer or __pointer__ for the mode used to represent pointers.
near
The near attribute tells the compiler that the variable is allocated in near data space
(the first 8 KB of data memory). Such variables can sometimes be accessed more
efficiently than variables not allocated (or not known to be allocated) in near data
space.
int num __attribute__ ((near));
noload
The noload attribute indicates that space should be allocated for the variable, but that
initial values should not be loaded. This attribute could be useful if an application is
designed to load a variable into memory at run time, such as from a serial EEPROM.
int table1[50] __attribute__ ((noload)) = { 0 };
page
The page attribute places variable definitions into a specific page of memory . The page
size depends on the type of memory selected by a space attribute. Objects residing in
RAM will be constrained to a 32K page while objects residing in Flash will be con-
strained to a 64K page (upper byte not included).
unsigned int var[10] __attribute__ ((space(auto_psv)));
The space(auto_psv) or space(psv) attribute will use a single memory page by
default.
__eds__ unsigned int var[10] __attribute__ ((eds, page));
When dealing with eds, please refer to Section 7.7 “Extended Data Sp ace Access”
for more information.
packed
The packed attribute specifies that a structure member should have the smallest
possible alignment unless you specify a larger value with the aligned attribute.
Here is a structure in which the member x is packed, so that it immediately follows a,
with no padding for alignment:
struct foo
{
char a;
int x[2] __attribute__ ((packed));
};
Note: The device architecture requires that words be aligned on even byte
boundaries, so care must be taken when using the packed attribute to
avoid run-time addressing errors.
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 111
persistent
The persistent attribute specifies that the variable should not be initialized or
cleared at startup. A variable with the persistent attribute could be used to store state
information that will remain valid after a device Reset.
int last_mode __attribute__ ((persistent));
Persistent data is not normally initialized by the C run-time. However, from a
cold-restart, persistent data may not have any meaningful value. This code example
shows how to safely initialize such data:
#include <p24Fxxxx.h>
int last_mode __attribute__((persistent));
int main()
{
if ((RCONbits.POR == 0) &&
(RCONbits.BOR == 0)) {
/* last_mode is valid */
} else {
/* initialize persistent data */
last_mode = 0;
}
}
reverse (alignment)
The reverse attribute specifies a minimum alignment for the ending address of a
variable, plus one. The alignment is specified in bytes and must be a power of two.
Reverse-aligned variables can be used for decrementing modulo buffers in dsPIC DSC
assembly language. This attribute could be useful if an application defines variables in
C that will be accessed from assembly language.
int buf1[128] __attribute__ ((reverse(256)));
The reverse attribute conflicts with the aligned and section attributes. An attempt
to name a section for a reverse-aligned variable will be ignored with a warning. It is an
error condition to specify both reverse and aligned for the same variable. A variable
with the reverse attribute cannot be placed into the auto_psv space (see the
space() attribute or the -mconst-in-code option); attempts to do so will cause a
warning and the compiler will place the variable into the PSV space.
section ("section-name")
By default, the compiler places the objects it generates in sections such as .data and
.bss. The section attribute allows you to override this behavior by specifying that a
variable (or function) lives in a particular section.
struct a { int i[32]; };
struct a buf __attribute__((section("userdata"))) = {{0}};
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 112 2012 Microchip Technology Inc.
secure
This attribute can be used to define protected variables in Secure Segment (SS) RAM:
int __attribute__((secure)) secure_dat[16];
Variables defined in SS RAM will not be initialized on startup. Therefore all variables in
SS RAM must be initialized using inline code. A diagnostic will be reported if initial
values are specified on a secure variable.
String literals can be assigned to secure variables using inline code, but they require
extra processing by the compiler. For example:
char *msg __attribute__((secure)) = "Hello!\n"; /* not supported */
char *msg2 __attribute__((secure));
void __attribute__((secure)) foo2()
{
*msg2 = "Goodbye..\n"; /* value assigned explicitly */
}
In this case, storage must be allocated for the string literal in a memory space which is
accessible to the enclosing secure function. The compiler will allocate the string in a
psv constant section designated fo r the secure segment.
sfr (address)
The sfr attribute tells the compiler that the variable is an SFR and may also specify
the run-time address of the variable, using the address parameter.
extern volatile int __attribute__ ((sfr(0x200)))u1mod;
The use of the extern specifier is required in order to not produce an error.
space (space)
Normally, the compiler allocates variables in general data space. The space attribute
can be used to direct the compiler to allocate a variable in specific memory spaces.
Memory spaces are discussed further in Section 7.2 “Address Spaces”. The
following arguments to the space attribute are accepted:
data
Allocate the variable in general data space. Variables in general data space can
be accessed using ordinary C statements. This is the default allocation.
xmemory - dsPIC30F, dsPIC33EP/F DSCs only
Allocate the variable in X data space. V ariables in X data space can be accessed
using ordinary C statements. An example of xmemory space allocation is:
int x[32] __attribute__ ((space(xmemory)));
ymemory - dsPIC30F, dsPIC33EP/F DSCs only
Allocate the variable in Y data space. V ariables in Y data space can be accessed
using ordinary C statements. An example of ymemory space allocation is:
int y[32] __attribute__ ((space(ymemory)));
Note: By convention, the sfr attribute is used only in processor header files. To
define a general user variable at a specific address use the address attri-
bute in conjunction with near or far to specify the correct addressing
mode.
DD
DD
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 113
prog
Allocate the variable in program space, in a section designated for executable
code. Variables in program space can not be accessed using ordinary C
statements. They must be explicitly accessed by the programmer , usually using
table-access inline assembly instructions, the program space visibility window, or
by the methods described in Section 7.4.2 “Access of objects in Program
Memory”.
auto_psv
Allocate the variable in program space, in a compiler-managed section
designated for automatic program space visibility window access. Variables in
auto_psv space can be read (but not written) using ordinary C statements, and
are subject to a maximum of 32K total space allocated. When specifying
space(auto_psv), it is not possible to assign a section name using the sec-
tion attribute; any section name will be ignored with a warning. A variable in the
auto_psv space cannot be placed at a specific address or given a reverse
alignment.
dma - PIC24EP/H MCUs, dsPIC33EP/F DSCs only
Allocate the variable in DMA memory. Variables in DMA memory can be
accessed using ordinary C statements and by the DMA peripheral.
__builtin_dmaoffset() and __builtin_dmapage() can be used to find
the correct offset for configuring the DMA peripheral. See Appendix F. “Built-in
Functions” for details.
#include <p24Hxxxx.h>
unsigned int BufferA[8] __attribute__((space(dma)));
unsigned int BufferB[8] __attribute__((space(dma)));
int main()
{
DMA1STA = __builtin_dmaoffset(BufferA);
DMA1STB = __builtin_dmaoffset(BufferB);
/* ... */
}
psv
Allocate the variable in program space, in a section designated for program space
visibility window access. The linker will locate the section so that the entire vari-
able can be accessed using a single setting of the PSVPAG register. Variables in
PSV space are not manag ed by the compiler and can not be accessed using ordi-
nary C statemen ts. They must be explicitly accessed by the programmer , usually
using table-access inline assembly instructions, or using the program space
visibility window.
eedata - PIC24F, dsPIC30F/33F DSCs only
Allocate the variable in EEData space. Variables in EEData space can not be
accessed using ordinary C statements. They must be explicitly accessed by the
programmer, usually using table-access inline assembly instructions, or using
the program space visibility window.
pmp
Allocate the variable in off chip memory associated with the PMP peripheral. For
complete details please see Section 7.5 “Parallel Master Port Access”.
Note: Variables placed in the auto_psv section are not loaded into data
memory at startup. This attribute may be useful for reducing RAM
usage.
DD
DD
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 114 2012 Microchip Technology Inc.
external
Allocate the variable in a user defined memory space. For complete details
please see Section 7.6 “External Memory Access”.
transparent_union
This attribute, attached to a function parameter which is a union, means that the
corresponding argument may have the type of any union member , but the argument is
passed as if its type were that of the first union member . The argument is passed to the
function using the calling conventions of the first member of the transparent union, not
the calling conventions of the union itself. All members of the union must have the same
machine representation; this is necessary for this argument passing to work properly.
unordered
The unordered attribute indicates that the placement of this variable may move
relative to other variables within the current C source file.
const int __attribute__ ((unordered)) i;
unsupported(message)
This attribute will display a custom message when the object is used.
int foo
__
attribute
__
((unsupported
(“This object is unsupported”
));
Access to foo will generate a warning message.
unused
This attribute, attached to a variable, means that the variable is meant to be possibly
unused. The compiler will not produce an unused variable warning for this variable.
weak
The weak attribute causes the declaration to be emitted as a weak symbol. A weak
symbol may be superseded by a global definition. When weak is applied to a reference
to an external symbol, the symbol is not required for linking. For example:
extern int __attribute__((__weak__)) s;
int foo() {
if (&s) return s;
return 0; /* possibly some other value */
}
In the above program, if s is not defined by some other module, the program will still
link but s will not be given an address. The conditional verifies that s has been defined
(and returns its value if it has). Otherwise ‘0’ is returned. There are many uses for this
feature, mostly to provide generic code that can link with an optional library.
The weak attribute may be applied to functions as well as variables:
extern int __attribute__((__weak__)) compress_data(void *buf);
int process(void *buf) {
if (compress_data) {
if (compress_data(buf) == -1) /* error */
}
/* process buf */
}
In the above code, the function compress_data will be use d only if it is li nked in from
some other module. Deciding whether or not to use the feature becomes a link-time
decision, not a comp il e time decis io n.
Supported Data Types and Variables
2012 Microchip Technology Inc. DS52071B-page 115
The affect of the weak attribute on a definition is more complicated and requires
multiple files to describe:
/* weak1.c */
int __attribute__((__weak__)) i;
void foo() {
i = 1;
}
/* weak2.c */
int i;
extern void foo(void);
void bar() {
i = 2;
}
main() {
foo();
bar();
}
Here the definition in weak2.c of i causes the symbol to become a strong definition.
No link error is emitted and both i’s refer to the same storage location. Storage is
allocated for weak1.c’s version of i, but this space is not accessible.
There is no check to ensure that both versions of i have the same type; changing i in
weak2.c to be of type float will still allow a link, but the behavior of function foo will
be unexpected. foo will write a value into the least significant portion of our 32-bit float
value. Conversely, changing the type of the weak definition of i in weak1.c to type
float may cause disastrous results. We will be writing a 32-bit floating point value into
a 16-bit integer allocation, overwriting any variable stored immediately after our i.
In t he cases wh ere on ly weak definitions exist, the linker will choose the storage of the
first such definition. The remaining definitions become in-accessible.
The behavior is identical, regardless of the type of the symbol; functions and variables
behave in the same manner.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 116 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 117
Chapter 7. Memory Allocation and Access
7.1 INTRODUCTION
There are two broad groups of RAM-based variables: auto/parameter variables, which
are allocated to some form of stack, and global/static variables, which are positioned
freely throughout the data memory space. The memory allocation of these two groups
is discussed separately in the following sections.
• Address Spaces
• Variables in Data Space Memory
• Variables in Program Space
• Parallel Master Port Access
• External Memory Access
• Extended Data Space Access
• Packing Data Stored in Flash
• Allocation of Variables to Registers
• Variables in EEPROM
• Dynamic Memory Allocation
• Memory Models
7.2 ADDRESS SPACES
The 16-bit devices are a combination of traditional PIC® Microcontroller (MCU) fea-
tures (peripherals, Harvard architecture, RISC) and new DSP capabilities (dsPIC DSC
devices). These devices have two distinct memory regions:
• Program Memory contains executable code and optionally constant data.
• Data Memory contains external variables, static variables, the system stack and
file registers. Data memory consists of near data, which is memory in the first 8
KB of the data memory space, and far data, which is in the upper 56 KB of data
memory space.
Although the program and data memory regions are distinctly separate, the
dsPIC30F/33F and PIC24F/H families of processors contain hardware support for
accessing data from within program Flash using a hardware feature that is commonly
called Program S pace Visibility (PSV). More detail about how PSV works can be found
in device data sheets or family reference manuals. Also, see Section 7.3 “Variables
in Data Space Memory” and Section 11.8.2 “PSV Usage with Interrupt Service
Routines”.
Briefly, the architecture allows the mapping of one 32K page of Flash into the upper
32K of the data address space via the Special Function Register (SFR) PSVPAG.
Devices that support Extended Data Space (EDS) map using the DSRPAG register
instead. Also it is possible to map FLASH and other areas. See
Section 7.7 “Extended Data Space Access” for more details.
By default the compiler only supports direct access to one single PSV page, referred
to as the auto_psv space. In this model, 16-bit data pointers can be used. However,
on larger devices, this can make it difficult to manage large amounts of constant data
stored in Flash.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 118 2012 Microchip Technology Inc.
The extensions presented here allow the definition of a variable as being a ‘managed’
PSV variable. This means that the compiler will manipulate both the offset (within a
PSV page) and the page itself. As a consequence, data pointers must be 32 bits. The
compiler will probably generate more instructions than the single PSV page model, but
that is the price being paid to buy more flexibility and shorter coding time to access
larger amounts of data in Flash.
7.3 VARIABLES IN DATA SPACE MEMORY
Most variables are ultimately positioned into the data space memory. The exceptions
are non-auto variables which are qualified as const and may be placed in the pro-
gram memory space.
Due to the fundamentally different way in which auto variables and non-auto vari-
ables are allocated memory , they are discussed separately . To use the C language ter-
minology, these two groups of variables are those with ‘automatic storage duration’ and
those with ‘permanent storage duration’, respectively.
The terms “local” and “global” are commonly used to describe variables, but are not
ones defined by the language standard. The term “local variable” is often taken to mean
a variable which has scope inside a function, and “global variable” is one which has
scope throughout the entire program. However, the C language has three common
scopes: block, file (i.e. internal linkage) and program (i.e. external linkage). So using
only two terms to describe these can be confusing.
For example, a static variable defined outside a function has scope only in that file,
so it is not globally accessible, but it can be accessed by more than one function inside
that file, so it is not local to any one function either.
In terms of memory allocation, variables are allocated space based on whether it is an
auto or not; hence the grouping in the following sections.
7.3.1 Non-Auto Variable Allocation and Access
Non-auto (static and external) variables have permanent storage duration and
are located by the compiler into the data space memory. The compiler will also allocate
non-auto const-qualified variables (see Section 6.9.1 “Const T ype Qualifier”) into
the data space memory if the constants-in-data memory model is selected; otherwise,
they are located in program memory.
7.3.1.1 DEFAULT ALLOCATION OF NON-AUTO VARIABLES
The c omp il er con s id er s se ver a l cat e gor i es of static and external variable, which all
relate to the value the variable should contain at the time the program begins, that is,
those that should be cleared at program startup (uninitialized variables), and those that
should hold a non-zero value (initialized variables), and those that should not be altered
at all at program startup (persistent variables). Those objects qualified as const are
usually assigned an initial value since they are read-only. If they are not assigned an
initial value, they are grouped with the other uninitialized variables.
Data placed in RAM may be initialized at startup by copying initialized values from pro-
gram memory.
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 119
7.3.1.2 STATIC VARIABLES
All static variables have permanent storage duration, even those defined inside a
function which are “local static” variables. Local static variables only have scope in
the function or block in which they are defined, but unlike auto variables, their memory
is reserved for the entire duration of the program. Thus they are allocated memory like
other non-auto variables. Static variables may be accessed by other functions via
pointers since they have permanent duration.
Variables which are static are guaranteed to retain their value between calls to a
function, unless explicitly modified via a pointer.
Variables which are static and which are initialized only have their initial value
assigned once during the program’s execution. Thus, they may be preferable over ini-
tialized auto objects which are assigned a value every time the block in they are
defined begins execution. Any initialized static variables are initialized in the same way
as other non-auto initialized objects by the runtime startup code, see
Section 3.4.2 “Startup and Initialization”.
7.3.1.3 NON-AUTO VARIABLE SIZE LIMITS
The compiler option -mlarge-arrays allows you to define and access arrays larger
than 32K. You must ensure that there is enough space to allocate such an array by
nominating a memory space large enough to contain such an object.
Using this option will have some effect on how code is generated as it effects the defi-
nition of the size_t type, increasing it to an unsigned long int. If used as a global
option, this will affect many operations used in indexing (making the operation more
complex). Using this option locally may effect how variables can be accessed. With
these considerations in mind, using large arrays is requires careful planning. This sec-
tion discusses some techniq ues for its use.
Two things occur when the -mlarge-arrays option is selected:
1. The compiler generates code in a different way for accessing arrays.
2. The compiler defines the size_t type to be unsigned long int.
Item 1 can have a negative effect on code size, if used throughout the whole program.
It is possible to only compile a single module with this option and have it work, but there
are limitations which will be discussed shortly.
Item 2 affects the calling convention when external functions receive or return objects
of type size_t. The compiler provides libraries built to handle a larger size_t and
these objects will be selected automatically by the linker (provided they exist).
Mixing -mlarge-arrays and normal-sized arr ays together is relatively straightfor-
ward and might be the best way to make use of this feature. There are a few usage
restrictions: functions defined in such a module should not call external routines that
use size_t, and functions defined in such a module should not receive size_t as a
parameter.
For example, one could define a large array and an accessor function which is then
used by other code modules to access the array. The benefit is that only one module
needs to be compiled with -mlarge-array with the defect that an accessor is
required to access the array. This is useful in cases where compiling the whole program
with -mlarge-arrays will have negative effect on code size and speed.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 120 2012 Microchip Technology Inc.
A code example for this would be:
file1.c
/* to be compiled -mlarge-arrays */
__prog__ int array1[48000] __attribute__((space(prog)));
__prog__ int array2[48000] __attribute__((space(prog)));
int access_large_array(__prog__ int *array, unsigned long index) {
return array[index];
}
file2.c
/* to be compiled without -mlarge-arrays */
extern __prog__ int array1[] __attribute__((space(prog)));
extern __prog__ int array2[] __attribute__((space(prog)));
extern int access_large_array(__prog__ int *array,
unsigned long index);
main() {
fprintf(stderr,"Answer is: %d\n", access_large_array(array1,
39543));
fprintf(stderr,"Answer is: %d\n", access_large_array(array2,
16));
}
7.3.1.4 CHANGING NON-AUTO VARIABLE ALLOCATION
As described in Section 7.2 “Address Spaces”, the compiler arranges for data to be
placed into sections, depending on the memory model used and whether or not the
data is initialized. When modules are combined at link time, the linker determines the
starting addresses of the various sections based on their attributes.
Cases may arise when a specific variable must be located at a specific address, or
within some range of addresses. The easiest way to accomplish this is by using the
address attribute, described in Chapter 5. “Differences Between MPLAB XC16
and ANSI C”. For example, to locate variable Mabonga at address 0x1000 in data
memory:
int __attribute__ ((address(0x1000))) Mabonga = 1;
A group of common variables may be allocated into a named section, complete with
address specifications:
int __attribute__ ((section("mysection"), address(0x1234))), foo;
7.3.1.5 DATA MEMORY ALLOCATION MACROS
Macros that may be used to allocate space in data memory are discussed below. There
are two types: those that require an argument and those that do not.
The following macros require an argument N that specifies alignment. N must be a
power of two, with a minimum value of 2.
#define _XBSS(N) __attribute__((space(xmemory), aligned(N)))
#define _XDATA(N) __attribute__((space(xmemory), aligned(N)))
#define _YBSS(N) __attribute__((space(ymemory), aligned(N)))
#define _YDATA(N) __attribute__((space(ymemory), aligned(N)))
#define _EEDATA(N) __attribute__((space(eedata), aligned(N)))
For example, to declare an uninitialized array in X memory that is aligned to a 32-byte
address:
int _XBSS(32) xbuf[16];
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 121
To declare an initialized array in data EEPROM without special alignment:
int _EEDATA(2) table1[] = {0, 1, 1, 2, 3, 5, 8, 13, 21};
The following macros do not require an argument. They can be used to locate a
variable in persistent data memory or in near data memory.
#define _PERSISTENT __attribute__((persistent))
#define _NEAR __attribute__((near))
For example, to declare two variables that retain their values across a device Reset:
int _PERSISTENT var1,var2;
7.3.2 Auto Variable Allocati on and Acces s
This section discusses allocation of auto variables (those with automatic storage dura-
tion). This also include function parameter variables, which behave like auto variables,
as well as temporary variables defined by the compiler.
The auto (short for automatic) variables are the default type of local variable. Unless
explicitly declared to be static, a local variable will be made auto. The auto key-
word may be used if desired.
auto variables, as their name suggests, automatically come into existence when a
block is executed and then disappear once the block exits. Since they are not in exis-
tence for the entire duration of the program, 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.
Typically such variables are stored on some sort of a data stack, which can easily allo-
cate then deallocate memory as required by each function. The stack is discussed in
Section 7.3.2.1 “Software Stack”.
The the standard qualifiers: const and volatile may both be used with auto vari -
ables and these do not affect how they are positioned in memory. This implies that a
local const-qual ified obje ct is still a n auto object and, as such, will be allocated mem-
ory on the stack, not in the program memory like with non-auto const objects.
7.3.2.1 SOFTWARE STACK
The dsPIC DSC device dedicates register W15 for use as a software S tack Pointer . All
processor stack operations, including function calls, interrupts and exceptions, use the
software stack. The stack grows upward, towards higher memory addresses.
The dsPIC DSC device also supports stack overflow detection. If the Stack Pointer
Limit register, SPLIM, is initialized, the device will test for overflow on all stack opera-
tion s. If an overfl ow sho uld occ ur , the pr ocesso r will in itia te a st ack er ror ex cepti on. By
default, this will result in a processor Reset. Applications may also install a stack error
exception handler by defining an interrupt function named _StackError. See Chap-
ter 11. “Interrupts” for details.
The C run-time startup module initializes the Stack Pointer (W15) and the Stack Pointer
Limit register during the startup and initialization sequence. The initial values are
normally provided by the linker , which allocates the largest stack possible from unused
data memory. The location of the stack is reported in the link map output file.
Applications can ensure that at least a minimum-sized stack is available with the
--stack linker command-line option. See the MPLAB Asse mbl er, Li nker and U til ities
for PIC24 MCUs and dsPIC DSCs User’s Guide (DS51317) for details.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 122 2012 Microchip Technology Inc.
Alternatively , a stack of specific size may be allocated with a user-defined section from
an assembly source file. In the following example, 0x100 bytes of data memory are
reserved for the stack:
.section *,data,stack
.space 0x100
The linker will allocate an appropriately sized section and initialize __SP_init and
__SPLIM_init so that the run-time startup code can properly initialize the stack. Note
that since this is a normal assembly code, section attributes such as address may be
used to further define the stack. Please see the MPLAB Assembler , Linker and Utilities
for PIC24 MCUs and dsPIC DSCs User’s Guide (DS51317) for more information.
7.3.2.2 T HE C STACK USA G E
The C compiler uses the software stack to:
• Allocate automatic variables
• Pass arguments to functions
• Save the processor status in interrupt functions
• Save function return address
• Store temporary results
• Save registers across function calls
The run-time stack grows upward from lower addresses to higher addresses. The
compiler uses two working registers to manage the stack:
• W15 – This is the Stack Pointer (SP). It points to the top of stack which is defined
to be the first unused location on the stack.
• W14 – This is the Frame Pointer (FP). It points to the current function’s frame.
Each function, if required, creates a new frame at the top of the stack from which
automatic and temporary variables are allocated. The compiler option
-fomit-frame-pointer can be used to restrict the use of the FP.
FIGURE 7-1: STACK AND FRAME POINTERS
The C run-time startup modules (crt0.o and crt1.o in libpic30-omf.a) initialize
the S tack Pointer W15 to point to the bottom of the stack and initialize the Stack Pointer
Limit register to point to the top of the stack. The stack grows up and if it should grow
beyond the value in the Stack Pointer Limit register, then a stack error trap will be taken.
The user may initialize the Stack Pointer Limit register to further restrict stack growth.
The following diagrams illustrate the steps involved in calling a function. Executing a
CALL or RCALL instruction pushes the return address onto the software stack. See
Figure 7-2.
Stack grows
toward
greater
addresses
SP (W15)
FP (W14)
Function Frame
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 123
FIGURE 7-2: CALL OR RCALL
The called function (callee) can now allocate space for its local context (Figure 7-3).
FIGURE 7-3: CALLEE SPACE ALLOCATION
Finally, any callee-saved registers that are used in the function are pushed
(Figure 7-4).
Stack grows
toward
greater
addresses
SP (W15)
FP (W14)
Return addr [23:16]
Return addr [15:0]
Parameter 1
:
Parameter n-1
Parameter n
Caller Frame
Stack grows
toward
greater
addresses
SP (W15)
FP (W14)
Local Variables
Return addr [15:0]
Parameter 1
:
Parameter n-1
Parameter n
Caller Frame
Return addr [23:16]
and Temporaries
Previous FP
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 124 2012 Microchip Technology Inc.
FIGURE 7-4: PUSH CALLEE-SAVE D REGISTERS
7.3.2.3 AUTO VARIABLE SIZE LIMITS
If a program requires large objects that should not be accessible to the entire program,
consider leaving them as local objects, but using the static specif ier. Such varia bles
are still local to a function, but are no longer auto and are allocated permanent storage
which is not in the software stack.
The auto objects are subject to the similar constraints as non-auto objects in terms
of maximum size, but they are allocated to the software stack rather than fixed memory
locations. Section 7.3.1.3 “Non-Auto V ariable Size Limits” which describes defining
and using large arrays is also applicable to auto objects.
7.3.3 Changing Auto Variable Allocation
As auto variables are dynamically allocated space in the software stack, using the
address attribute or other mechanisms to have them allocated at a non-default location
is not permitted.
Stack grows
toward
greater
addresses
SP (W15)
FP (W14)
Callee-Saved
Return addr [15:0]
Parameter 1
:
Parameter n-1
Parameter n
Caller Frame
Return addr [23:16]
Registers
Previous FP
Local Variables
and Temporaries
[W14+n] accesses
local context
[W14-n] accesses
function parameters
stack-based
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 125
7.4 VARIABLES IN PROGRAM SPACE
The 16-bit core families of processors contain hardware support for accessing data
from within program Flash using a hardware feature that is commonly called Program
Space Visibility (PSV). More detail about how PSV works can be found in device data
sheets or family reference manuals. Also, see Section 7.4.1 “Allocation and Access
of Program Memory Objects” and Section 11.8.2 “PSV Usage with Interrupt Ser-
vice Routines”.
Briefly, the architecture allows the mapping of one 32K page of Flash into the upper
32K of the data address space via the Special Function Register (SFR) PSVPAG or
DSRP AG. By default the compiler only supports direct access to one single PSV page,
referred to as the auto_psv space. In this model, 16-bit data pointers can be used.
However, this can make it difficult to manage large amounts of constant data stored in
Flash on larger devices.
When the option -mconst-in-code is enabled, const-qua lified varia ble s that ar e
not auto are placed in program memory. Any auto variables qualified const are
placed on the stack along with other auto variabl es.
Any const-qualified (auto or no n-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.
A const object is usually defined with initial values, as the program cannot write to
these objects at runtime. However this is not a requirement. An uninitialized const
object is allocated space along with other uninitialized RAM variables, but is still
read-only. Here are examples of const object definitions.
const char IOtype = ’A’; // initialized const object
const char buffer[10]; // I reserve memory in RAM
See Chapter 13. “Mixing C and Assembly Code” for the equivalent assembly sym-
bols that are used to represent const-qualified variables in program memory.
7.4.1 Allocatio n and Access of Program Memory Objects
There are many objects that are allocated to program memory by the compiler . The fol-
lowing sections indicate those objects and how they are allocated to their final memory
location by the compiler and how they are accessed.
7.4.1.1 STRING AND CONST OBJECTS
By default, the compiler will automatically arrange for strings and const-qualified
initialized variables to be allocated in the auto_psv section, which is mapped into the
PSV window. Specify the -mconst-in-data option to direct the compiler not to use
the PSV window and these objects will be allocated along with other RAM-based vari-
ables.
In the default memory model, the PSV page is fixed to one page which is represented
by the auto_psv memory space. Accessing the single auto PSV page is efficient as
no page manipulation is required. Additional FLASH may be accessed using the tech-
niques introduced in section Section 7.4.2.1 “Managed PSV Access”.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 126 2012 Microchip Technology Inc.
7.4. 1.2 CONST-QUALIFIED VARIABLES IN SECURE FLASH
const-qualified variables with initializers can be supported in secure Flash segments
using PSV constant sections managed by the compiler. For example:
const int __attribute__((boot)) time_delay = 55;
If the const qualifier was omitted from the definition of time_delay, this statement
would be rejected with an error message. (Initialized variables in secure RAM are not
supported).
Since the const qualifier has been specified, variable time_delay can be allocated
in a PSV constant section that is owned by the boot segment. It is also possible to spec-
ify the PSV constant section explicitly with the space(auto_psv) attrib ute :
int __attribute__((boot,space(auto_psv))) bebop = 20;
Pointer variables initialized with string literals require special processing. For example:
char * const foo __attribute__((boot)) = "eek";
The compiler will recognize that string literal "eek" must be allocated in the same PSV
constant secti on as pointe r vari abl e foo.
Regardless of whether you have selected the constants-in-code or constants-in-data
memory model, the compiler will create and manage PSV constant sections as needed
for secure segments. Support for user-managed PSV sections is maintained through
an object compatibility model explained below.
Upon entrance to a boot or secure function, PSVPAG will be set to the correct value.
This value will be restored after any external function call.
7.4.1.3 STRI NG LIT E RAL S AS ARGUM ENTS
In addition to being used as initializers, string literals may also be used as function
arguments. For example:
myputs("Enter the Dragon code:\n");
Here allocation of the string literal depends on the surrounding code. If the statement
appears in a boot or secure function, the literal will be allocated in a corresponding PSV
constant section. Otherwise it will be placed in general (non-secure) memory,
according to the constants memory model.
Recall that data stored in a secure segment cannot be read by any other segment. For
example, it is not possible to call the standard C library function puts() with a string
that has been allocated in a secure segment. Therefore literals which appear as func-
tion arguments can only be passed to functions in the same security segment. This is
also true for objects referenced by pointers and arrays. Simple scalar types such as
char, int, and float, which are passed by value, may be passed to functions in
different segments.
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 127
7.4.2 Access of objects in Program Memory
Allocating objects to program memory and accessing them are considered as two sep-
arate issues. The compiler requires that you qualify variables to indicate how they are
accessed. You can choose to have the compiler manage access of these objects, or
do this yourself, which can be more efficient, but more complex.
7.4.2.1 MANAGED PSV ACCESS
The compiler introduces several new qualifiers (CV -qualifiers for the language lawyers
in the audience). Like a const volatile qualifier, the new qualifiers can be applied
to objects or pointer targets. These qualifiers are:
•__psv__ for accessing objects that do not cross a PSV boundary, such as those
allocated in space(auto_psv) or space(psv)
•__prog__ for accessing objects that may cross a PSV boundary, specifically
those allocated in space(prog), but it may be applied to any object in Flash
•__eds__ for accessing objects that may be in FLASH or the extended data
space (for devices with > 32K of RAM), see __eds__ in Section 7.7 “Extended
Data Space Access”.
Typically there is no need to specify __psv__ or __prog__ for an object placed in
space(auto_psv).
Defining a variable in a compiler managed Flash space is accomplished by:
__psv__ unsigned int FLASH_variable __attribute__((space(psv)));
Reading from the variable now will cause the compiler to generate code that adjusts
the appropriate PSV page SFR as necessary to access the variable correctly. These
qualifie rs can equall y decor ate pointe r s:
__psv__ unsigned int *pFLASH;
produces a pointer to something in PSV, which can be assigned to a managed PSV
object in the normal way. For example:
pFLASH = &FLASH_variable;
7.4.2.2 OBJEC T COMPATIBI LIT Y MODE L
Since functions in secure segments set PSVPAG to their respective psv constant sec-
tions, a convention must be established for managing multiple values of the PSVPAG
register . In previous versions of the compiler , a single value of PSVP AG was set during
program startup if the default constants-in-code memory model was selected. The
compiler relied upon that preset value for accessing const variables and string literals,
as well as any variables specifically nominated with space(auto_psv).
MPLAB XC16 provides support for multiple values of PSVPAG. Variables declared with
space(auto_psv) may be combined with secure segment constant variables and/or
managed psv variables in the same source file. Precompiled objects that assume a
single, pre-set value of PSVPAG are link-compatible with objects that define secure seg-
ment psv constants or managed psv variables.
Even though PSVPAG is considered to be a compiler-managed resource, there is no
change to the function calling conventions.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 128 2012 Microchip Technology Inc.
7.4.2.3 ISR CONSIDERATIONS
A data access using managed PSV pointers is definitely not atomic, meaning it can
take several instructions to complete the access. Care should be taken if an access
should not be interrupted.
Furthermore an Interrupt Service Routine (ISR) never really knows what the current
state of the PSVPAG register will be. Unfortunately the compiler is not really in any posi-
tion to determine whether or not this is important in all cases.
The compiler will make the simplifying assumption that the writer of the interrupt service
routine will know whether or not the automatic, compiler managed PSVPAG is required
by the ISR. This is required to access any constant data in the auto_psv space or any
string literals or constants when the default -mconst-in-code option is selected.
When defining an interrupt service routine, it is best to specify whether or not it is nec-
essary to assert the default setting of the PSVPAG SFR.
This is achieved by adding a further attribute to the interrupt function definition:
•auto_psv - the compiler will set the PSVPAG register to the correct value for
accessing the auto_psv space, ensuring that it is restored when exiting the ISR
•no_auto_psv - the compiler will not set the PSVPAG register
For example:
void __attribute__((interrupt, no_auto_psv)) _T1Interrupt(void) {
IFS0bits.T1IF = 0;
}
The choice is provided so that, if you are especially conscious of interrupt latency, you
may select the best option. Saving and setting the PSVPAG will consume approximately
3 cycles at the entry to the function and one further cycle to restore the setting upon
exit from the function.
Note that boot or secure interrupt service routines will use a different setting of the
PSVPAG register for their constant data.
7.4.3 Size Limitations of Program Memory Variables
Arrays of any type (including arrays of aggregate types) can be qualified const and
placed in the program memory. So too can structure and union aggregate types, see
Section 6.5 “Structu res and Unions”. These objects can often become large in size
and may affect memory allocation.
For objects allocated in a compiler-managed PSV window (auto_psv space) the total
memory available for allocation is limited by the size of the PSV window itself. Thus no
single object can be larger than the size of the PSV window, and all such objects must
not total larger than this window.
The variables allocated to program memory are subject to similar constraints as data
space objects in terms of maximum size, but they are allocated to the larger program
space rather than data space memory . Section 7.3.1.3 “Non-Auto V ariable Size Lim-
its” which describes defining and using large arrays is also applicable to objects in pro-
gram space memory.
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 129
7.4.4 Changing Program Memory Variable Allo cation
The variables allocated to program memory can, to some degree, be allocated to alter-
nate memory locations. Section 7.3.1.4 “Changing Non-Auto Variable Allocation”
describes alternate addresses and sections also applicable to objects in the program
memory space. Note that you cannot use the address attribute for objects that are in
the auto_psv space.
The space attribute can be used to define variables that are positioned for use in the
PSV window. To specify certain variables for allocation in the compiler-managed PSV
space, use attribute space(auto_psv). To allocate variables for PSV access in a
section not managed by the compiler, use attribute space(psv). For more information
on these attributes, see Chapter 5. “Differe nces Bet ween MPLAB XC1 6 and ANSI
C”.
For example, to place a variable in the auto_psv space, which will cause storage to
be al locat ed in Fla sh in a conven ient wa y to be access ed by a single PSVPAG setting,
specify:
unsigned int FLASH_variable __attribute__((space(auto_psv)));
Other user spaces that relate to Flash are available:
•space(psv) - a PSV space that the compiler does not access automatically
•space(prog) - any location in Flash that the compiler does no t access autom atically
Note that both the psv and auto_psv sp aces are appropriately blocked or aligned so
that a single PSVPAG setting is suitable for accessing the entire variable.
For more on PSV usage, see the MP LAB As se mbl er, Linker and Util it ies for PIC24
MCUs and dsPIC DSCs User’s Guide (DS51317).
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 130 2012 Microchip Technology Inc.
7.5 PARALLEL MASTER PORT ACCESS
Some devices contain a Parallel Master Port (PMP) peripheral which allows the con-
nection of various memory and non-memory devices directly to the device. Access to
the peripheral is controlled via a selection of peripherals. More information about this
peripheral can be found in the Family Reference Manual or device-specific data sheets.
The peripheral can require a substantial amount of configuration, depending upon the
type and brand of memory device that is connected. This configuration is not done
automatically by the compiler.
The extensions presented here allow the definition of a variable as PMP. This means
that the compiler will communicate with the PMP peripheral to access the variable.
To use this feature:
• Initialize PMP - define the initialization function: void __init_PMP(void)
• Declare a New Memory Space
• Define Variables within PMP Space
7.5.1 Initialize PMP
The PMP peripheral requires initialization before any access can be properly pro-
cessed. Consult the appropriate documentation for the device you are interfacing to
and the data sheet for 16-bit device you are using.
If PMP is used, the toolsuite will call void __init_PMP(void) during normal C
run-time initialization. If a customized initialization is being used, please ensure that this
function is called.
This function should make the necessary settings in the PMMODE and PMCON SFRs.
In particular:
• The peripheral should not be configured to generate interrupts:
PMMODEbits.IRQM = 0
• The peripheral should not be configured to generate increments:
PMMODEbits.INCM = 0
The compiler will modify this setting during run-time as needed.
• The peripheral should be initialized to 16-bit mode:
PMMODEbits.MODE16 = 1
The compiler will modify this setting during run-time as needed.
• The peripheral should be configured for one of the MASTER modes:
PMMODEbits.MODE = 2 or PMMODEbits.MODE = 3
• Set the wait-states PMMODEbits.WAITB, PMMODEbits.WAITM, and
PMMODEbits.WAITE as appropriate for the device being connected.
• The PMCON SFR should be configured as appropriate making sure that the chip
sele ct functi on bits PMCONbits.CSF match the information communicated to the
com piler when defining memory spaces.
A partial example might be:
void __init_PMP(void) {
PMMODEbits.IRQM = 0;
PMMODEbits.INCM = 0;
PMMODEbits.MODE16 = 1;
PMMODEbits.MODE = 3;
/* device specific configuration of PMMODE and PMCCON follows */
}
Note: PMP attributes are not supported on devices with EPMP. Use Extended
Data Space (EDS ) instead. See Sectio n 7.7 “Extended Data Space
Access”.
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 131
7.5.2 Declare a New Memory Space
The compiler toolsuite requires information about each additional memory being
attached via the PMP. In order for the 16-bit device linker to be able to properly assign
memory, information about the size of memory available and the number of
chip-selects needs to be provided.
In Chapter 5. “Differences Between MPLAB XC16 and ANSI C” the new pmp mem-
ory space was introduced. This attribute serves two purposes: declaring extended
memory spaces and assigning C variable declarations to external memory (this will be
covered in the next subsection).
Declaring an extended memory requires providing the size of the memory. You may
optionally assign the memory to a particular chip-select pin; if none is assigned it will
be assumed that chip-selects are not being used. These memory declarations look like
normal external C declarations:
extern int external_PMP_memory
__attribute__((space(pmp(size(1024),cs(0)))));
Above we defined an external memory of size 1024 bytes and there are no
chip-selects. The compiler only supports one PMP memory unless chip-selects are
being used:
extern int PMP_bank1 __attribute__((space(pmp(size(1024),cs(1)))));
extern int PMP_bank2 __attribute__((space(pmp(size(2048),cs(2)))));
Above PMP_bank1 will be activated using chip-select pin 1 (address pin 14 will be
asserted when accessing variables in this bank). PMP_bank2 will be activated using
chip-select pin 2 (address pin 15 will be asserted).
Note that when using chip-selects, the largest amount of memory is 16 Kbytes per
bank. It is recommended that the declaration appear in a common header file so that
the declaration is available to all translation units.
7.5.3 Define Variables within PMP Space
The pmp space attribute is also used to assign individual variables to the space. This
requires that the memory space declaration to be present. Given the declarations in the
previous subsection, the following variable declarations can be made:
__pmp__ int external_array[256]
__attribute__((space(pmp(external_PMP_memory))));
external_array will be alloca ted in the pr eviously decla re d memo ry
external_PMP_memory. If there is only one PMP memory, and chip-selects are not
being used, it is possible to leave out the explicit reference to the memory. It is good
practice, however, to always make the memory explicit which would lead to code that
is more easily maintained.
Note that, like managed PSV pointers, we have qualified the variable with a new type
qualifier __pmp__. When attached to a variable or pointer it instructs the compiler to
generate the correct sequence for access via the PMP peripheral.
Now that a variable has been declared it may be accessed using normal C syntax. The
compiler will generate code to correctly communicate with the PMP peripheral.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 132 2012 Microchip Technology Inc.
7.6 EXTERNAL MEMORY ACCESS
Not all of Microchip’s 16-bit devices have a parallel master port peripheral (see
Section 7.5 “Parallel Master Port Access”), and not all memories are suitable for
attaching to the PMP (serial memories sold by Microchip, for example). The toolsuite
provides a more general interface to, what is known as, external memory , although, as
will be seen, the memory does not have to be external.
Like PMP access, the tool-chain needs to learn about external memories that are being
attached. Unlike PMP access, however, the compiler does not know how to access
these memories. A mechanism is provided by which an application can specify how
such memories should be accessed.
Addresses of external objects are all 32 bits in size. The largest attachable memory is
64K (16 bits); the other 16 bits in the address is used to uniquely identify the memory.
A total of 64K (16 bits) of these may be (theoretically) attached.
To use this feature, work through the following sections.
7.6.1 Declare a New Memory Space
This is very similar to declaring a new memory space for PMP access.
The 16-bit toolsuite requires information about each external memory. In order for
16-bit device linker to be able to properly assign memory, information about the size of
memory available and, optionally the origin of the memory, needs to be provided.
In Chapter 5. “Differences Between MPLAB XC16 and ANSI C” the external
memory space was introduced. This attribute serves two purposes: declaring extended
memory spaces and assigning C variable declarations to external memory (this will be
covered in the next subsection).
Declaring an extended memory requires providing the size of the memory. You may
optionally specify an origin for this memory; if none is specified 0x0000 will be
assumed.
extern int external_memory
__attribute__((space(external(size(1024)))));
Above an external memory of size 1024 bytes is defined. This memory can be uniquely
identified by its given name of external_memory.
7.6.2 Define Variables Within an External Space
The external space attribute is also used to assign individual variables to the space.
This requires that the memory space declaration to be present. Given the declarations
in the previous subsection, the following variable declarations can be made:
__external__ int external_array[256]
__attribute__((space(external(external_memory))));
external_array will be allocated in the previous declared memory
external_memory.
Note that, like managed PSV objects, we have qualified the variable with a new type
qualifier __external__. When attached to a variable or pointer target, it instructs the
compiler to generate the correct sequence to access these objects.
Once an external memory variable has been declared, it may be accessed using nor-
mal C syntax. The compiler will generate code to access the variable via special helper
functions that the programmer must define. These are covered in the next subsection.
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 133
7.6.3 Define How to Access Memory Spaces
References to variables placed in external memories are controlled via the use of sev-
eral helper functions. Up to five functions may be defined for reading and five for writ-
ing. One of these functions is a generic routine and will be called if any of the other four
are not defined but are required. If none of the functions are defined, the compiler will
generate an error message. A brief example will be presented in the next subsection.
Generally, defining the individual functions will result in more efficient code generation.
7.6.3.1 FUNCTIONS FOR READING
read_external
void __read_external(unsigned int address,
unsigned int memory_space,
void *buffer,
unsigned int len)
This function is a generic Read function and will be called if one of the next functions
are required but not defined. This function should perform the steps necessary to fill
len bytes of memory in the buffer from the external memory named memory_space
starting at address address.
read_external8
unsigned char __read_external8(unsigned int address,
unsigned int memory_space)
Read 8 bits from external memory space memory_space starting from address
address. The compiler would like to call this function if trying to access an 8-bit sized
object.
read_external16
unsigned int __read_external16(unsigned int address,
unsigned int memory_space)
Read 16 bits from external memory space memory_space starting fr om addres s
address. The compiler would like to call this function if trying to access an 16-bit sized
object.
read_external32
unsigned long __read_external32(unsigned int address,
unsigned int memory_space)
Read 32 bits from external memory space memory_space starting fr om addres s
address. The compiler would like to call this function if trying to access a 32-bit sized
object, such as a long or float type.
read_external64
unsigned long long __read_external64(unsigned int address,
unsigned int memory_space)
Read 64 bits from external memory space memory_space starting fr om addres s
address. The compiler would like to call this function if trying to access a 64-bit sized
object, such as a long long or long double type.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 134 2012 Microchip Technology Inc.
7.6.3.2 FUNCTIONS FOR WRITING
write_external
void __write_external(unsigned int address,
unsigned int memory_space,
void *buffer,
unsigned int len)
This function is a generic Write function and will be called if one of the next functions
are required but not defined. This function should perform the steps necessary to write
len bytes of memory from the buffer to the external memory named memory_space
starting at address address.
write_external8
void __write_external8(unsigned int address,
unsigned int memory_space,
unsigned char data)
Write 8 bits of data to external memory space memory_space starting from address
address. The compiler would like to call this function if trying to write an 8-bit sized
object.
write_external16
void __write_external16(unsigned int address,
unsigned int memory_space,
unsigned int data)
W rite 16 bits of data to external memory space memory_space starting from address
address. The compiler would like to call this function if trying to write an 16-bit sized
object.
write_external32
void __write_external32(unsigned int address,
unsigned int memory_space,
unsigned long data)
W rite 32 bits of data to external memory space memory_space starting from address
address. The compiler would like to call this function if trying to write a 32-bit sized
object, such as a long or float type.
write_external64
void __write_external64(unsigned int address,
unsigned int memory_space,
unsigned long long data)
W rite 64 bits of data to external memory space memory_space starting from address
address. The compiler would like to call this function if trying to write a 64-bit sized
object, such as a long long or long double type.
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 135
7.6.4 An External Example
The following snippets of example come from a working example (in the Examples
folder.)
This example implements, using external memory, addressable bit memory. In this
case each bit is stored in real data memory, not off chip. The code will define an
external memory of 512 units and map accesses using the appropriate read and
write function to one of 64 bytes in local data memory.
First the external memory is defined:
extern unsigned int bit_memory
__attribute__((space(external(size(512)))));
Next appropriate read and write functions are defined. These functions will make use
of an array of memory that is reserved in the normal way.
static unsigned char real_bit_memory[64];
unsigned char __read_external8(unsigned int address,
unsigned int memory_space) {
if (memory_space == bit_memory) {
/* an address within our bit memory */
unsigned int byte_offset, bit_offset;
byte_offset = address / 8;
bit_offset = address % 8;
return (real_bit_memory[byte_offset] >> bit_offset) & 0x1;
} else {
fprintf(stderr,"I don't know how to access memory space: %d\n",
memory_space);
}
return 0;
}
void __write_external8(unsigned int address,
unsigned int memory_space,
unsigned char data) {
if (memory_space == bit_memory) {
/* an address within our bit memory */
unsigned int byte_offset, bit_offset;
byte_offset = address / 8;
bit_offset = address % 8;
real_bit_memory[byte_offset] &= (~(1 << bit_offset));
if (data & 0x1) real_bit_memory[byte_offset] |=
(1 << bit_offset);
} else {
fprintf(stderr,"I don't know how to access memory space: %d\n",
memory_space);
}
}
These functions work in a similar fashion:
• if acce ss in g bit_memory, then
- determine the correct byte offset and bit offset
- read or write the appropriate place in the real_bit_memory
• otherwise access another memory (whose access is unknown)
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 136 2012 Microchip Technology Inc.
With the two major pieces of the puzzle in place, generate some variables and
accesses:
__external__ unsigned char bits[NUMBER_OF_BITS]
__attribute__((space(external(bit_memory))));
// inside main
__external__ unsigned char *bit;
bit = bits;
for (i = 0; i < 512; i++) {
printf("%d ",*bit++);
}
Apart from the __external__ CV-qualifiers, ordinary C statements can be used to
define and access variables in the external memory space.
7.7 EXTE NDED DATA SPACE ACCE SS
Qualifying a variable or pointer target as being accessible through the extended data
space window allows you to easily access objects that have been placed in a variety of
different memory spaces. These include: space(data) (and its subsets), eds,
space(eedata), space(prog), space(psv), space(auto_psv), and on some
devices space(pmp). Not all devices support all memory spaces.
To use this feature:
• declare an object in an appropriate memory space
• qualify the object with the __eds__ qualifier
For example:
__eds__ int var_a __attribute__((space(prog)));
__eds__ int var_b [10] __attribute__((eds));
__eds__ int *var_c;
__eds__ int *__eds__ *var_d __attribute__((space(psv)));
var_a - declares an int in Flash that is automatically accessed
var_b - declares an array of ints, located in eds; the elements of the array are auto-
matically accessed
var_c - declares a pointer to an int, where the destination may exist in any one of the
memory spaces supported by Extended Data S pace pointers and will be automatically
accessed upon dereference; the pointer itself must live in a normal data space
var_d - declares a pointer to an int, where the destination may exist in any one of the
memory spaces supported by Extended Data S pace pointers and will be automatically
accessed upon dereference; the pointer value exists in Flash and is also automatically
accessed.
The compiler will automatically assert the page attribute to scalar variable declarations;
this allows the compiler to generate more efficient code when accessing larger data
types. Remember , scalar variables do not include structures or arrays. To force paging
of a structure or array, please manually use the page attribute and the co mpi ler w ill
prevent the object from crossing a page boundary.
For read access to __eds__ qualified variables, the compiler will automatically manip-
ulate the PSVPAG or DSRPAG register as appropriate. For devices that support
extended data space memory, the compiler will also manipulate the DSWPAG register.
Note: Some devices use DSRPAG to represent extended read access to FLASH
or the extended data space (EDS)
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 137
7.8 PACKING DATA STORED IN FLASH
The 16-bit core families use a 24-bit Flash word size. The architecture supports the
mapping of areas of Flash into the data space, as discussed in Section 7.4 “Variables
in Program Space”. Unfortunately this mapping is only 16 bits wide to fit in with data
space dimensions.
The compiler supports using the upper byte of Flash via packed storage. Use of this
upper byte can offer a code-size savings for large structures, but this is more expensive
to access. The type-qualifier __pack_upper_byte added to a declaration indicates
that the variable should be placed into Flash memory and use the upper byte. Unlike
other qualifiers in use with MPLAB XC16 C Compiler , such as __psv__, this qualifier
combines placement and access control.
7.8.1 Packed Example
__pack_upper_byte char message[] = "Hello World!\n";
will allocate the message string into Flash memory in such a way that the upper byte
of memory contains valid data.
There are no restrictions to the types of __pack_upper_byte data . The compi ler will
'pack' structures as if __attribute__((packed)) had also been specified. This fur-
ther eliminates wasted space due to padding.
Like other extended type qualifiers, the __pack_upper_byte type qualifier enforces
a unique addressing space on the compiler; therefore, it is important to maintain this
qualifier when passing values as parameters. Do not be tempted to cast away the
__pack_upper_byte qualifier – it won't work.
7.8.2 Usage Considerations
When using this qualifier, consider the following:
1. __pack_upper_byte data is best used for large data sets that do not need to
be accessed frequently or that do not have important access timing.
2. Sequential accesses to __pack_upper_byte dat a objec ts wil l improv e acces s
performance.
3. A version of mempcy is defined in libpic30.h, and its prototype is:
void _memcpy_packed(void *dst, __pack_upper_byte void *src,
unsigned int len);
4. The following style of declaration is invalid for packed memory:
__pack_upper_byte char *message = "Hello World!\n";
Here, message is a pointer to __pack_upper_byte space, but the string "Hello
World!\n", is in normal const data space, which is no t compatible with
__pack_upper_byte. There is no standard C way to specify a different source
address space for the literal string. Instead declare message as an object (such
as an array declaration in Section 7.8.1 “Packed Example”).
5. The TBLPAG SFR may be corrupted during access of a packed variable.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 138 2012 Microchip Technology Inc.
7.8.3 Addressing Information
The upper byte of Flash does not have a unique address, which is a requirement for C.
Therefore, the compiler has to invent one. The tool chain remaps Flash to linear
addresses for all bytes starting with program address word 0. This means that the real
Flash address of a __pack_upper_byte variable will not be the address that is stored
in a pointer or symbol table. The Flash address can be determined by:
1. word offset = address div 3
2. program address offset = word offset * 2
3. byte offset = address mod 3
The byte to reference is located in Flash at <it>program address offset</it>.
The remapped addressing scheme for __pack_upper_byte objects prevents the
compiler from accepting fixed address requests.
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 139
7.9 ALLOCATION OF VARIABLES TO REGISTERS
You may specify a fixed register assignment for a particular C variable. It is not recom-
mended that this be done.
Accumulator registers are not allocated by the compiler so it is safe to allocate them
using the following syntax:
volatile register int Accum_A asm(“A”);
No other register should be allocated.
7.10 VARIABLES IN EEPROM
The compiler provides some convenience macro definitions to allow placement of data
into the devices EE data area. This can be done quite simply:
int _EEDATA(2) user_data[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
user_data will be placed in the EE data space (space(eedata)) reserving 10 words
with the given initial values.
The device provides two ways for programmers to access this area of memory . The first
is via the program space visibility window. The second is by using special machine
instructions (TBLRDx).
7.10.1 Accessing EEDATA via User Managed PSV
The compiler normally manages the PSV window to access constants stored in
program memory. If this is not the case, the PSV window can be used to access
EEDATA memory.
To use the PSV window:
• The psv page register must be set to the appropriate address for the program
memory to be accessed. For EE data this will be 0xFF, but it is best to use the
__builtin_psvpage() function.
• In some devices, the PSV window should also b e enabled by setting the PSV bit
in the CORCON register. If this bit is not set, uses of the PSV window will always
read 0x000 0.
EXAMPLE 7-1: EEDATA ACCESS VIA PSV
#include <xc.h>
int main(void) {
PSVPAG = __builtin_psvpage(&user_data);
CORCONbits.PSV = 1;
/* ... */
if (user_data[2]) ;/* do something */
}
These steps need only be done once. Unless psv page is changed, variables in EE
data space may be read by referring to them as normal C variables, as shown in the
example.
Note: Using variables specified in compiler-allocated registers - fixed registers -
is usually unnecessary and occasionally dangerous. This feature is
deprecated and not recommended.
DD
Note: This access model is not compatible with the compiler-managed PSV
(-mconst-in-code) model. You should be careful to prevent conflict.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 140 2012 Microchip Technology Inc.
7.10.2 Accessing EEDATA Using TBLRDx Instructions
The TBLRDx instructions are not directly supported by the compiler, but they can be
used via inline assembly or compiler built-in functions. Like PSV accesses, a 23-bit
address is formed from an SFR value and the address encoded as part of the instruc-
tion. To access the same memory as given in the previous example, the following code
may be used:
To use the TBLRDx instructions:
• The TBLPAG register must be set to the appropriate address for the program
memory to be accessed. For EE data, this will be 0x7F, but it is best to use the
__builtin_tblpage() function.
• The TBLRDx instruction can be accessed from an __asm__ statement or through
one of the __builtin_tblrd functions; refer to the “dsPIC30F/33F
Programmer’s Reference Manual” (DS70157) for information on this instruction.
EXAMPLE 7-2: EEDATA ACCESS VIA TABLE READ
#include <p30Fxxxx.h>
#define eedata_read(src, offset, dest) { \
register int eedata_addr; \
register int eedata_val; \
\
eedata_addr = __builtin_tbloffset(&src)+offset; \
eedata_val = __builtin_tblrdl(eedata_addr); \
dest = eedata_val; \
}
char user_data[] __attribute__((space(eedata))) = { /* values */ };
int main(void) {
int value;
TBLPAG = __builtin_tblpage(&user_data);
eedata_read(user_data,2*sizeof(user_data[0]), value);
if (value) ; /* do something */
}
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 141
7.10.3 Accessing EEDATA Using Managed Access
On most device the EE Data space is part of the program address space. Therefore
EEData can be accessed automatically using one of the managed access qualifiers
__psv__ or __eds__.
EXAMPLE 7- 3: EXAMPLE 6-2 USING MANAGED PS V ACCES S
#include <p30Fxxxx.h>
__eds__ char user_data[] __attribute__((space(eedata))) = { /* values
*/ };
int main(void) {
int value;
value = user_data[0];
if (value) ; /* do something */
}
7.10.4 Additional Sources of Information
The device Family Reference Manuals have an excellent discussion on using the Flash
program memory and EE data memory provided. These manuals also have information
on run-time programming of both program memory and EE data memory.
There are many library routines provided with the compiler. See the 16-Bit Language
Tools Libraries (DS51456) manual for more information.
7.11 DYNAMIC MEMORY ALLOCATION
The C run-time heap is an uninitialized area of data memory that is used for dynamic
memory allocation using the standard C library dynamic memory management
functions, calloc, malloc and realloc. If you do not use any of these functions,
then you do not need to allocate a heap. By default, a heap is not created.
If you do want to use dynamic memory allocation, either directly, by calling one of the
memory allocation functions, or indirectly, by using a standard C library input/output
function, then a heap must be created. A heap is created by specifying its size on the
linker command line, using the --heap linker command-line option. An example of
allocating a heap of 512 bytes using the command line is:
xc16-gcc foo.c -Wl,--heap=512
The linker allocates the heap immediately below the stack.
You can use a standard C library input/output function to create open files (fopen). If
you open files, then the heap size must include 40 bytes for each file that is simultane-
ously open. If there is insufficient heap memory, then the open function will return an
error indicator . For each file that should be buffered, 4 bytes of heap space is required.
If there is insufficient heap memory for the buffer , then the file will be opened in unbuf-
fered mode. The default buffer can be modified with setvbnft.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 142 2012 Microchip Technology Inc.
7.12 MEMORY MODELS
The compiler supports several memory models. Command-line options are available
for selecting the optimum memory model for your application, based on the specific
dsPIC DSC device part that you are using and the type of memory usage.
TABLE 7-1: MEMORY MODEL COMMAND LINE OPTIONS
The command-line options apply globally to the modules being compiled. Individual
variables and functions can be declared as near, far or in eds to better control the
code generation. For information on setting individual variable or function attributes,
see Section 6.11 “Variable Attributes” and Sec tion 10.2. 1 “Function Specifiers” .
Option Memory Definition Description
-msmall-data Up to 8 KB of data memory.
This is the default. Permits use of PIC18 like instructions
for accessing data memory.
-msmall-scalar Up to 8 KB of data memory.
This is the default. Permits use of PIC18 like instructions
for accessing sc al ars in data memory.
-mlarge-data Grea ter than 8 KB of data
memory. Uses indirection for data references.
-msmall-code Up to 32 kWor ds of program
memory. This is the default. Function po inters will not go thro ugh a
jump tab le. Function calls use RCALL
instruction.
-mlarge-code Greater than 32 kWords of
program memory. Function pointers might go through a
jump tab le. Function calls use CALL
instruction.
-mconst-in-data Constants located in data
memory. Values copied from pr ogram memory
by startup code.
-mconst-in-code Constants located in program
memory. This is the default. Values ar e accessed via Program
Space Visibility (PSV) data window.
-mconst-in-aux-
flash Constants in auxiliary FLASH Values are accessed via Program
Space visibility window.
Memory Allocation and Acces s
2012 Microchip Technology Inc. DS52071B-page 143
7.12.1 Near or Far Data
If variables are allocated in the near data space, the compiler is often able to generate
better (more compact) code than if the variables are not allocated in near data. If all
variables for an application can fit within the 8 KB of near data, then the compiler can
be requested to place them there by using the default -msmall-data command line
option when compiling each module. If the amount of data consumed by scalar types
(no arrays or structures) totals less than 8 KB, the default -msmall-scalar, com-
bined with -mlarge-data, may be used. This requests that the compiler arrange to
have just the scalars for an application allocated in the near data space.
If neither of these global options is suitable, then the following alternatives are
available.
1. It is possible to compile some modules of an application using the
-mlarge-data or -mlarge-scalar command line options. In this case, only
the variables used by those modules will be allocated in the far data section. If
this alternative is used, then care must be taken when using externally defined
variables. If a variable that is used by modules compiled using one of these
options is defined externally, then the module in which it is defined must also be
compiled using the same option, or the variable declaration and definition must
be tagged with the far attribute.
2. If the command line options -mlarge-data or -mlarge-scalar have been
used, then an individual variable may be excluded from the far data space by
tagging it with the near attribute.
3. Instead of using command-line options, which have module scope, individual
variables may be placed in the far data section by tagging them with the far
attribute.
The linker will produce an error message if all near variables for an application cannot
fit in the 8K near data space.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 144 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 145
Chapter 8. Operators and Statements
8.1 INTRODUCTION
The MPLAB XC16 C Compiler supports all the ANSI operators. The exact results of
some of these are implementation defined and this behavior is fully documented in
Appendix A. “Implementation-Defined Behavior”. The following sections illustrate
code operations that are often misunderstood as well as additional operations that the
compile r is capable of per formi ng.
• Built-I n Functio ns
• Integral Promotion
8.2 BUILT-IN FUNC TIONS
Built-in functions give the C programmer access to assembler operators or machine
instructions that are currently only accessible using inline assembly , but are sufficiently
useful that they are applicable to a broad range of applications. Built-in functions are
coded in C source files syntactically like function calls, but they are compiled to
assembly code that directly implements the function, and usually do not involve func-
tion calls or library routines.
For more on built-in functions, see Appendix F. “Built-in Functions”.
8.3 INTEGRAL PROMOTION
When there is more than one operand to an operator , they typically must be of exactly
the same type. The compiler will automatically convert the operands, if necessary, so
they do have the same type. The conversion is to a “larger” type so there is no loss of
information; however , the change in type can cause different code behavior to what is
sometimes expected. These form the standard type conversions.
Prior to these type conversions, some operands are unconditionally converted to a
larger type, even if both operands to an operator have the same type. This conversion
is called integral promotion and is part of Standard C behavior. The compiler performs
these integral promotions where required, and there are no options that can control or
disable this operation. If you are not aware that the type has changed, the results of
some expr essi ons are not what would nor mal ly be expe cte d.
Integral promotion is the implicit conversion of enumerated types, signed or
unsigned varieties of char, short int or bit-field types to either signed int or
unsigned int. If the result of the conversion can be represented by an signed int,
then that is the destination type, otherwise the conversion is to unsigned int .
Consider the following example.
unsigned char count, a=0, b=50;
if(a - b < 10)
count++;
The unsigned char result o f a - b is 206 (which is not less than 10), but both a and
b are converted to signed int via integral promotion before the subtraction takes
place. 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.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 146 2012 Microchip Technology Inc.
If the result of the subtraction is to be an unsigned quantity, then apply a cast. For
example:
if((unsigned int)(a - b) < 10)
count++;
The comparison is then done using unsigned int, in this case, and the body of the
if() would not be executed.
Another problem that frequently occurs is with the bitwise compliment operator , ~. This
operator toggles each bit within a value. Consider the following code.
unsigned char count, c;
c = 0x55;
if( ~c == 0xAA)
count++;
If c contains the value 0x55, it often assumed that ~c will produce 0xAA, however the
result is 0xFF AA and so the comparison in the above example would fail. The compiler
may be able to issue a mismatched comparison error to this effect in some circum-
stances. Again, a cast could be used to change this behavior.
The consequence of integral promotion as illustrated above is that operations are not
performed with char -type operands, but with int -type operands. However there are
circumstances when the result of an operation is identical regardless of whether the
operands are of type char or int. In these cases, the compiler will not perform the
integral promotion so as to increase the code efficiency. Consider the following exam-
ple.
unsigned char a, b, c;
a = b + c;
S trictly speaking, this statement requires that the values of b and c should be promoted
to unsigned int, the addition performed, the result of the addition cast to the type of
a, and then the assignment can take place. 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 addi ti on of th es e val ues with out pr omot ion, af te r the unsigned int result was
converted back to unsigned char, the final result would be the same. If an 8-bit addi-
tion is more efficient than a 16-bit addition, the compiler will encode the former.
If, in the above example, the type of a was unsigned int, then integral promotion
would have to be performed to comply with the ANSI C standard.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 147
Chapter 9. Register Usage
9.1 INTRODUCTION
Certain registers play import roles in the C runtime environment. Therefor creating
code concerning these registers requires knowledge about their use by the compiler.
• Register Variables
• Changing Register Contents
9.2 REGISTER VARIABLES
Register variables use one or more working registers, as shown in Table 9.1.
TABLE 9.1: REGISTER CONVENTIONS
Variable Working Register
char, signed char, unsigned char W0-W13, and W14 if not used as a Frame
Pointer.
short, signed short, unsigned
short W0-W13, and W14 if not used as a Frame
Pointer.
int, signed int,unsigned int W0-W13, and W14 if not used as a Frame
Pointer.
void * (or any pointer) W0-W13, and W14 i f not used as a Frame
Pointer.
long, signed long, unsigned long A pair of contiguous registers, the first of which
is a regis ter from the set {W 0, W2, W4, W6, W8,
W10, W12}. T he lower-numbered register
contains the least signif icant 16 bits of the value.
long long, signed long long,
unsigned long long A quadruplet of contiguous registers, the first of
which is a register from the set {W0, W4, W8}.
The lower-numbered register contains the least
significant 16 bits of the value. Successively
high er-n u mb er ed registers conta in successively
more significant bits.
float A pair of contiguous registers, the first of which
is a regis ter from the set {W 0, W2, W4, W6, W8,
W10, W12}. T he lower-numbered register
contains the least significant 16 bits of the
significant.
double* A pair of contiguous registers, the first of which
is a regis ter from the set {W 0, W2, W4, W6, W8,
W10, W12}. T he lower-numbered register
contains the least significant 16 bits of the
significant.
long double A quadruplet of contiguous registers, the first of
which is a register from the set {W0, W4, W8}.
The lower-numbered register contains the least
significant 16 bits of the significant.
structure 1 contiguous regi st er per 2 bytes in the
structure.
* double is equivalent to long double if -fno-short-double is used.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 148 2012 Microchip Technology Inc.
9.3 CHANGING REGISTER CONTENTS
The assembly generated from C source code by the compiler will use certain registers
that are present on the 16-bit device. Most importantly , the compiler assumes that noth-
ing other than code it generates can alter the contents of these registers. So if the
assembly loads a register with a value and no subsequent code generation requires
this register , 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 managed by the compiler are: W0-W15,
RCOUNT, STATUS (SR), and PSVPAG or DSRPAG
The state of these register must never be changed directly by C code, or by any assem-
bly code in-line with C code. The following example shows a C statement and in-line
assembly that violates these rules and changes the ZERO bit in the STATUS register.
#include <xc.h>
void badCode(void)
{
asm (“mov #0, w8”);
WREG9 = 0;
}
The compiler is unable to interpret the meaning of in-line assembly code that is encoun-
tered in C code. Nor does it associate a variable mapped over an SFR to the actual
register itself. 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.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 149
Chapter 10. Functions
10.1 INTRODUCTION
The compiler supports C code functions and handles assembly code functions, as dis-
cussed in the following topics:
• Writing Functions
• Function Size Limits
• Allocation of Function Code
• Changing the Default Function Allocation
• Inline Functions
• Memory Models
• Function Call Conventions
10.2 WRITING FUNCTIONS
Implementation and special features associated with functions are discussed in the fol-
lowing sections.
10.2.1 Function Specifiers
The only specifier that has any effect on functions is static.
A function defined using the static specifier only affects the scope of the function, i.e.
limits the places in the source code where the function may be called. Functions that
are static may only be directly called from code in the file in which the function is
defined. This specifier does not change the way the function is encoded.
10.2.2 Function Attributes
The keyword __attribute__ allows you to specify special attributes when making a
declaration. This keyword is followed by an attribute specification inside double
parentheses. The following attributes are currently supported for functions:
•address (addr)
•alias ("target")
•auto_psv, no_auto_psv
•boot
•const
•deprecated
•far
•format (archetype, string-index, first-to-check)
•format_arg (string-index)
• interrupt [ ( [ save(list) ] [, irq(irqid) ] [,
altirq(altirqid)] [, preprologue(asm) ] ) ]
•near
•no_instrument_function
•noload
•noreturn
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 150 2012 Microchip Technology Inc.
•section ("section-name")
•secure
•shadow
•unsupported("message")
•unused
•user_init
•weak
You may also specify attributes with __ (double underscore) preceding and following
each keyword (e.g., __shadow__ instead of shadow). This allows you to use them in
header files without being concerned about a possible macro of the same name.
Multiple attributes may be specified in a declaration by separating them by commas
within the double parentheses or by immediately following an attribute declaration with
another attribute declarat ion.
address (addr)
The address attribute specifies an absolute address for the function.
void __attribute__ ((address(0x100))) foo() {
...
}
Alternatively, you may define the address in the function prototype:
void foo() __attribute__ ((address(0x100)));
alias ("target")
The alias attribute causes the declaration to be emitted as an alias for another symbol,
which must be specified.
Use of this attribute results in an external reference to target, which must be resolved
during the link phase.
auto_psv, no_auto_psv
The auto_psv attribute, when combined with the interrupt attribute, will cause the
compiler to generate additional code in the function prologue to set the psv page SFR
to the correct value for accessing space(auto_psv) (or constants in the con-
stants-in-code memory model) variables. Use this option when using 24-bit pointers
and an interrupt may occur while the psv page has been modified and the interrupt rou-
tine, or a function it calls, uses an auto_psv variable. Compare this with
no_auto_psv.
The no_auto_psv attribute, when combined with the interrupt attribute, will cause the
compiler to not generate additional code for accessing space(auto_psv) (or con-
stants in the constants-in-code memory model) variables. Use this option if none of the
conditions under auto_psv hold true.
If neither auto_psv nor no_auto_psv option is specified for an interrupt routine, the
compiler will issue a warning and assume auto_psv.
Functions
2012 Microchip Technology Inc. DS52071B-page 151
boot
This attribute directs the compiler to allocate a function in the boot segment of program
Flash.
For example, to declare a protected function:
void __attribute__((boot)) func();
An optional argument can be used to specify a protected access entry point within the
boot segment. The argument may be a literal integer in the range 0 to 31 (except 16),
or the word unused. Integer arguments correspond to 32 instruction slots in the seg-
ment access area, which occupies the lowest address range of each secure segment.
The value 16 is excluded because access entry 16 is reserved for the secure segment
interrupt vect or. The value unused is used to specify a function for all of the unused
slo ts in the access area.
Access entry points facilitate the creation of application segments from different ven-
dors that are combined at run time. They can be specified for external functions as well
as locally defined functions. For example:
/* an external function that we wish to call */
extern void __attribute__((boot(3))) boot_service3();
/* local function callable from other segments */
void __attribute__((secure(4))) secure_service4()
{
boot_service3();
}
To specify a secure interrupt handler, use the boot attribute in combination with the
interrupt attribute:
void __attribute__((boot,interrupt)) boot_interrupts();
When an access entry point is specified for an external secure function, that function
need not be included in the project for a successful link. All references to that function
will be resolved to a fixed location in Flash, depending on the security model selected
at link time.
When an access entry point is specified for a locally defined function, the linker will
insert a branch instruction into the secure segment access area. The exception is for
access entry 16, which is represented as a vector (i.e, an instruction address) rather
than an instruction. The actual function definition will be located beyond the access
area; therefore the access area will contain a jump table through which control can be
transferred from another security segment to functions with defined entry points.
Note: In order to allocate functions with the boot or secure attribute, memory
for the boot and/or secure segment must be reserved. This can be accom-
plished by setting configuration words in source code, or by specifying
linker command options. For more information, see Chapter 8.8, “Options
that Specify CodeGuard Security Features”, in the linker manual
(DS51317).
If attributes boot or secure are used, and memory is not reserved, then a
link error will result.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 152 2012 Microchip Technology Inc.
Automatic variables are owned by the enclosing function and do not need the boot
attribute. They may be assigned initial values, as shown:
void __attribute__((boot)) chuck_cookies()
{
int hurl;
int them = 55;
char *where = "far";
splat(where);
/* ... */
}
Note that the initial value of where is based on a string literal which is allocated in the
PSV cons tant secti on .boot_const. The compiler will set the psv page SFR to the
correct value upon entrance to the function. If necessary, the compiler will also restore
it after the call to splat().
const
Many functions do not examine any values except their arguments, and have no effects
except the return value. Such a function can be subject to common subexpression
elimination and loop optimization just as an arithmetic operator would be. These
functions should be declared with the attribute const. For example:
int square (int) __attribute__ ((const int));
says that the hypothetical function square is safe to call fewer times than the program
says.
Note that a function that has pointer arguments and examines the data pointed to must
not be declared const. Likewise, a function that calls a non-const function usually
must not be const. It does not make sense for a const function to have a void return
type.
deprecated
See Section 6.1 1 “Variable Attributes” for information on the deprecated attribute.
far
The far attribute tells the compiler that the function may be located too far away to use
short call instruction.
format (archetype, string-index, first-to-check)
The format attribute specifies that a function takes printf, scanf or strftime
style arguments which should be type-checked against a format string. For example,
consider the declaration:
extern int
my_printf (void *my_object, const char *my_format, ...)
__attribute__ ((format (printf, 2, 3)));
This causes the compiler to check the arguments in calls to my_printf for
consistency with the printf style format string argument my_format.
The parameter archetype determines how the format string is interpreted, and should
be one of printf, scanf or strftime. The parameter string-index specifies
which argument is the format string argument (arguments are numbered from the left,
starting from 1), while first-to-check is the number of the first argument to check
against the format string. For functions where the arguments are not available to be
checked (such as vprintf), specify the third parameter as zero. In this case, the
compiler only checks the format string for consistency.
Functions
2012 Microchip Technology Inc. DS52071B-page 153
In the previous example, the format string (my_format) is the second argument of the
function my_print, and the arguments to check start with the third argument, so the
correct parameters for the format attribute are 2 and 3.
The format attribute allows you to identify your own functions that take format strings
as arguments, so that the compiler can check the calls to these functions for errors. The
compiler always checks formats for the ANSI library functions printf, fprintf,
sprintf, scanf, fscanf, sscanf, strftime, vprintf, vfprintf and
vsprintf, whenever such warnings are requested (using -Wformat), so there is no
need to modify the header file stdio.h.
format_arg (string-index)
The format_arg attribute specifies that a function takes printf or scanf style
arguments, modifies it (for example, to translate it into another language), and passes
it to a printf or scanf style function. For example, consider the declaration:
extern char *
my_dgettext (char *my_domain, const char *my_format)
__attribute__ ((format_arg (2)));
This causes the compiler to check the arguments in calls to my_dgettext, whose
result is passed to a printf, scanf or strftime type function for consistency with
the printf style format string argument my_format.
The parameter string-index specifies which argument is the format string
argument (starting from 1).
The format-arg attribute allows you to identify your own functions which modify
format strings, so that the compiler can check the calls to printf, scanf or
strftime function, whose operands are a call to one of your own functions.
interrupt [ ( [ save(list) ] [, irq(irqid) ]
[, altirq(altirqid)] [, preprologue(asm) ] ) ]
Use this option to indicate that the specified function is an interrupt handler . The compiler
will generate function prologue and epilogue sequences suitable for use in an interrupt
handler when this attribute is present. The optional parameter save specifies a li st of
variables to be saved and restored in the function prologue and epilogue, respectively.
The optional parameters irq and altirq specif y interrupt vecto r table I D’s t o be used.
The op t ion al p a r amet e r preprologue specifie s asse mb ly code th at is to be emi tte d
before the compil er-g en er a ted p r ol og ue cod e. See Chapter 11. “Interrupts” for a full
description, including examples.
When usi ng th e interrupt attribute, please specify either auto_psv or
no_auto_psv. If none is specified a warning will be produced and auto_psv will be
assumed.
near
The near attribute tells the compiler that the function can be called using a more
efficient form of the call instruction.
no_instrument_function
If the command line option -finstrument-function is given, profiling function calls
will be generated at entry and exit of most user-compiled functions. Functions with this
attribute will not be so instrumented.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 154 2012 Microchip Technology Inc.
noload
The noload attribute indicates that space should be allocated for the function, but that
the actual code should not be loaded into memory. This attribute could be useful if an
application is designed to load a function into memory at run time, such as from a serial
EEPROM.
void bar() __attribute__ ((noload)) {
...
}
noreturn
A few standard library functions, such as abort and exit, cannot return. The com-
piler knows this automatically. Some programs define their own functions that never
return. You can declare them noreturn to tell the compiler this fact. For example:
void fatal (int i) __attribute__ ((noreturn));
void
fatal (int i)
{
/* Print error message. */
exit (1);
}
The noreturn keyword tells the compiler to assume that fatal cannot return. It can
then optimize without regard to what would happen if fatal ever did retur n. This
makes slightly better code. Also, it helps avoid spurious warnings of uninitialized
variables.
It does not make sense for a noreturn function to have a return type other than void.
section ("section-name")
Normally, the compiler places the code it generates in the .text section. S ome times ,
however, you need additional sections, or you need certain functions to appear in
special sections. The section attribute specifies that a function lives in a particular
section. For example, consider the declaration:
extern void foobar (void) __attribute__ ((section (".libtext")));
This puts the function foobar in the .libtext section.
The linker will allocate the saved named section sequentially. This might allow you to
ensure code is locally referent to each other, even across modules. This can ensure
that calls are near enough to each other for a more efficient call instruction.
secure
This attribute directs the compiler to allocate a function in the secure segment of
program Flash.
For example, to declare a protected function:
void __attribute__((secure)) func();
An optional argument can be used to specify a protected access entry point within the
secure segment. The argument may be a literal integer in the range 0 to 31 (except
16), or the word unused. Integer arguments correspond to 32 instruction slots in the
segment access area, which occupies the lowest address range of each secure seg-
ment. The value 16 is excluded because access entry 16 is reserved for the secure
segment interrupt vector. The value unused is used to specify a function for all of the
unused slots in the access area.
Functions
2012 Microchip Technology Inc. DS52071B-page 155
Access entry points facilitate the creation of application segments from different ven-
dors that are combined at run time. They can be specified for external functions as well
as locally defined functions. For example:
/* an external function that we wish to call */
extern void __attribute__((boot(3))) boot_service3();
/* local function callable from other segments */
void __attribute__((secure(4))) secure_service4()
{
boot_service3();
}
To specif y a se cure in terru pt han dler, us e the secure attribute in combination with the
interrupt attribute:
void __attribute__((secure,interrupt)) secure_interrupts();
When an access entry point is specified for an external secure function, that function
need not be included in the project for a successful link. All references to that function
will be resolved to a fixed location in Flash, depending on the security model selected
at link time.
When an access entry point is specified for a locally defined function, the linker will
insert a branch instruction into the secure segment access area. The exception is for
access entry 16, which is represented as a vector (i.e, an instruction address) rather
than an instruction. The actual function definition will be located beyond the access
area; therefore the access area will contain a jump table through which control can be
transferred from another security segment to functions with defined entry points.
Automatic variables are owned by the enclosing function and do not need the secure
attribute. They may be assigned initial values, as shown:
void __attribute__((secure)) chuck_cookies()
{
int hurl;
int them = 55;
char *where = "far";
splat(where);
/* ... */
}
Note that the initial value of where is based on a string literal which is allocated in the
PSV constant section .secure_const. The compiler will set PSVPAG to the correct
value upon entrance to the function. If necessary, the compiler will also restore
PSVPAG after the call to splat().
shadow
The shadow attribute causes the compiler to use the shadow registers rather than the
software stack for saving registers. This attribute is usually used in conjunction with the
interrupt attribute.
void __attribute__ ((interrupt, shadow)) _T1Interrupt (void);
Note: In order to allocate functions with the boot or secure attribute, memory
for the boot and/or secure segment must be reserved. This can be accom-
plished by setting configuration words in source code, or by specifying
linker command options. For more information, see Chapter 8.8, “Options
that Specify CodeGuard Security Features”, in the linker manual
(DS51317).
If attributes boot or secure are used, and memory is not reserved, then a
link error will result.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 156 2012 Microchip Technology Inc.
unsupported("message")
This attribute will display a custom message when the object is used.
int foo
__
attribute
__
((unsupported
(“This object is unsupported”
));
Access to foo will generate a warning message.
unused
This attribute, attached to a function, means that the function is meant to be possibly
unused. The compiler will not produce an unused function warning for this function.
user_init
The user_init attribute may be applied to any non-interrupt function with void
parameter and return types. Applying this attribute will cause default C start-up mod-
ules to call this function before the user main is executed. There is no guarantee of
ordering, so these functions cannot rely on other user_init functions having been
previously run; these functions will be called after PSV and data initialization. A
user_init may still be called by the executing program. For example:
void __attribute__((user_init)) initialize_me(void) {
// perform initalization sequence alpha alpha beta
}
weak
See Section 6.11 “Variable Attributes” for information on the weak attribute.
10.3 FUNCTION SIZE LIMITS
For all devices, the code generated for a function may become larger than one page in
size, limited only by the available program memory . However , functions that yield code
larger than a page may not be as efficient due to longer call sequences to jump to and
call destinations in other pages. See 10.4 “Allocation of Function Code” for more
details.
10.4 ALLOCATION OF FUNCTION CODE
Code associated with functions is always placed in the program memory of the target
device. As described in Section 7.2 “Address Spaces”, the compiler arranges for
code to be placed in the .text section, depending on the memory model used and
whether or not the data is initialized. When modules are combined at link time, the
linker determines the starting addresses of the various sections based on their attri-
butes.
Functions
2012 Microchip Technology Inc. DS52071B-page 157
10.5 CHANGING THE DEFAULT FUNCTION ALLOCATION
Cases may arise when a specific function must be located at a specific address, or
within some range of addresses. The easiest way to accomplish this is by using the
address attribute, described in Section 10. 2.1 “Function Specifiers”. F or example,
to locate function PrintString at address 0x8000 in program memory:
int __attribute__ ((address(0x8000))) PrintString (const char *s);
Another way to locate code is by placing the function into a user-defined section, and
specifying the starting address of that section in a custom linker script. This is done as
follows:
1. Modify the code declaration in the C source to specify a user-defined section.
2. Add the user-defined section to a custom linker script file to specify the starting
address of the section.
For example, to locate the function PrintString at address 0x8000 in program
memory, first declare the function as follows in the C source:
int __attribute__((__section__(".myTextSection")))
PrintString(const char *s);
The section attribute specifies that the function should be placed in a section named
.myTextSection, rather than the default .text section. It does not specify where
the user-defined section is to be located. That must be done in a custom linker script,
as follows. Using the device-specific linker script as a base, add the following section
definition:
.myTextSection 0x8000 :
{
*(.myTextSection);
} >program
This specifies that the output file should contain a section named .myTextSection
starting at location 0x8000 and containing all input sections named.myTextSection.
Since, in this example, there is a single function PrintString in that section, then the
function will be located at address 0x8000 in program memory.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 158 2012 Microchip Technology Inc.
10.6 INLINE FUNCTIONS
By declaring a function inline, you can direct the compiler to integrate that function’s
code into the code for its callers. This usually makes execution faster by eliminating the
function-call overhead. In addition, if any of the actual argument values are constant,
their known values may permit simplifications at compile time, so that not all of the
inline function’s code needs to be included. The effect on code size is less predictable.
Machine code may be larger or smaller with inline functions, depending on the
particular case.
To declare a function inline, use the inline keyword in its declaration, like this:
inline int
inc (int *a)
{
(*a)++;
}
(If you are using the -traditional option or the -ansi option, write __inline__
instead of inline.) You can also make all “simple enough” functions inline with the
command-line option -finline-functions. The compiler heuristically decides
which functions are simple enough to be worth integrating in this way, based on an
estimate of the function’s size.
Certain usages in a function definition can make it unsuitable for inline substitution.
Among these usages are: use of varargs, use of alloca, use of variab le-siz ed dat a,
use of computed goto and use of nonlocal goto. Using the command-line option
-Winline will warn when a function marked inline could not be substituted, and will
give the reason for the failure.
In co mpiler syntax, the inline keyword does not affect the linkage of the function.
When a function is both inline and static, if all calls to the function are integrated
into the caller and the function’s address is never used, then the function’s own
assembler code is never referenced. In this case, the compiler does not actually output
assembler code for the function, unless you specify the command-line option
-fkeep-inline-functions. Some calls cannot be integrated for various reasons
(in particular, calls that precede the function’s definition cannot be integrated and
neither can recursive calls within the definition). If there is a nonintegrated call, then the
function is compiled to assembler code as usual. The function must also be compiled
as usual if the program refers to its address, because that can’t be inlined. The compiler
will only eliminate inline functions if they are declared to be static and if the function
definition precedes all uses of the function.
When an inline function is not static, then the compiler must assume that there
may be calls from other source files. Since a global symbol can be defined only once
in any program, the function must not be defined in the other source files, so the calls
therein ca nnot be integr ate d. There fore, a non- static inline function is always
compiled on its own in the usual fashion.
Note: Function inlining will only take place when the function’s definition is visible
at the call site (not just the prototype). In order to have a function inlined into
more than one source file, the function definition may be placed into a
header file that is included by each of the source files.
Note: The inline keyword will only be recognized with -finline or
optimizations enabled.
Functions
2012 Microchip Technology Inc. DS52071B-page 159
If you specify both inline and extern in the function definition, then the definition is
used only for inlining. In no case is the function compiled on its own, not even if you
refer to its address explicitly . Such an address becomes an external reference, as if you
had only declared the function and had not defined it.
This combination of inline and extern has a similar effect to a macro. Put a function
definition in a header file with these keywords and put another copy of the definition
(lacking inline and extern) in a library file. The definition in the header file will cause
most calls to the function to be inlined. If any uses of the function remain, they will refer
to the single copy in the library.
Inline, like regular, is a suggestion and may be ignored.
10.7 MEMORY MODELS
The compiler supports several memory models. Command-line options are available
for selecting the optimum memory model for your application, based on the specific
dsPIC DSC device part that you are using and the type of memory usage.
TABLE 10-1: MEMORY MODEL COMMAND LINE OPTIONS
The command-line options apply globally to the modules being compiled. Individual
variables and functions can be declared as near, far or eds to better control the code
generation. For information on setting individual variable or function attributes, see
Section 6.11 “Variable Attributes” and Section 10.2.1 “Function Specifiers”.
Option Memory Definition Description
-msmall-data Up to 8 KB of data memory.
This is the default. Permits use of PIC18 like instructions
for accessing data memory.
-msmall-scalar Up to 8 KB of data memory.
This is the default. Permits use of PIC18 like instructions
for accessing sc al ars in data memory.
-mlarge-data Grea ter than 8 KB of data
memory. Uses indirection for data references.
-msmall-code Up to 32 Kwords of program
memory. This is the default. Function po inters will not go thro ugh a
jump tab le. Function calls use RCALL
instruction.
-mlarge-code Grea ter than 32 Kw ords of
program memory. Function pointers might go through a
jump tab le. Function calls use CALL
instruction.
-mconst-in-data Constants located in data
memory. Values copied from pr ogram memory
by startup code.
-mconst-in-code Constants located in program
memory. This is the default. Values ar e accessed via Program
Space Visibility (PSV) data window.
-mconst-in-aux-
flash Constants in auxiliary FLASH Values are accessed via Program
Space visibility window.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 160 2012 Microchip Technology Inc.
10.7.1 Near or Far Code
Functions that are near (within a radius of 32 kWords of each other) may call each other
more efficiently than those which are not. If it is known that all functions in an applica-
tion are n ear , then the default -msmall-code command line option can be used when
compiling each module to direct the compiler to use a more efficient form of the function
call.
If this default option is not suitable, then the following alternatives are available:
1. It is possible to compile some modules of an application using the
-msmall-code command line option. In this case, only function calls in those
modules will use a more efficient form of the function call.
2. If the -msmall-code command-line option has been used, then the compiler
may be directed to use the long form of the function call for an individual function
by tagging it with the far attribute.
3. Instead of using command-line options, which have module scope, the compiler
may be directed to call individual functions using a more efficient form of the
function call by tagging their declaration and definition with the near attrib ute.
4. Group locally referent code together by using named sections or keep this code
in common translation units.
The linker will produce an error message if the function declared to be near cannot be
reached by one of its callers using a more efficient form of the function call.
Functions
2012 Microchip Technology Inc. DS52071B-page 161
10.8 FUNCTION CALL CONVENTIONS
When calling a function:
• Registers W0-W7 are caller saved. The calling function must preserve these val-
ues before the function call if their value is required subsequently from the func-
tion call. The stack is a good place to preserve these values.
• Registers W8-W14 are callee saved. The function being called must save any of
these registers it will m odify.
• Registers W0-W4 are used for function return values.
• Registers W0-W7 are used for argument transmission.
• DBRPAG/PSVPAG should be preserved if the -mconst-in-code (auto_psv)
memory model is being used.
TABLE 10-2: REGISTERS REQUIRED
Parameters are placed in the first aligned contiguous register(s) that are available. The
calling function must preserve the parameters, if required. S tructures do not have any
alignment restrictions; a structure parameter will occupy registers if there are enough
registers to hold the entire structure. Function results are stored in consecutive
registers, beginning with W0.
10.8.1 Function Parameters
The first eight working registers (W0-W7) are used for function parameters.Parameters
are allocated to registers in left-to-right order, and a parameter is assigned to the first
available register that is suitably aligned.
In the following example, all parameters are passed in registers, although not in the
order that they appear in the declaration. This format allows the compiler to make the
most efficient use of the available parameter registers.
EXAMPLE 10-1: FUNCT ION CALL MODEL
void
params0(short p0, long p1, int p2, char p3, float p4, void *p5)
{
/*
** W0 p0
** W1 p2
** W3:W2 p1
** W4 p3
** W5 p5
** W7:W6 p4
*/
...
Data Type Number of Registers Required
char 1
int 1
short 1
pointer 1
long 2 (contiguous – aligned to even numbered register)
float 2 (contiguous – aligned to even numbered register)
double* 2 (contiguous – aligned to even numbered register)
long double 4 (contiguous – aligned to quad numbered register)
structure 1 register per 2 bytes in structure
* double is equivalent to long double if -fno-short-double is used.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 162 2012 Microchip Technology Inc.
}
The next example demonstrates how structures are passed to functions. If the
complete structure can fit in the available registers, then the structure is passed via
registers; otherwise the structure argument will be placed onto the stack.
EXAMPLE 10-2: FUNCT ION CALL MODEL, PASSING STRUCTURES
typedef struct bar {
int i;
double d;
} bar;
void
params1(int i, bar b) {
/*
** W0 i
** W1 b.i
** W5:W2 b.d
*/
}
Parameters corresponding to the ellipses (...) of a variable-length argument list are not
allocated to registers. Any parameter not allocated to registers is pushed onto the
stack, in right-to-left order.
In the next example, the structure parameter cannot be placed in registers because it
is too large. However, this does not prevent the next parameter from using a register
spot.
Functions
2012 Microchip Technology Inc. DS52071B-page 163
EXAMPLE 10-3: FUNCTIO N CALL MODEL, STACK BASED ARGUMENTS
typedef struct bar {
double d,e;
} bar;
void
params2(int i, bar b, int j) {
/*
** W0 i
** stack b
** W1 j
*/
}
Accessing arguments that have been placed onto the stack depends upon whether or
not a Frame Pointer has been created. Generally the compiler will produce a Frame
Pointer (unless told not to do so), and stack-based parameters will be accessed via the
Frame Pointer register (W14). In the preceding example, b will be accessed from
W14-22. The Frame Pointer offset of negative 22 has been calculated (refer to
Figure 7-4) by removing 2 bytes for the previous FP, 4 bytes for the return address,
followed by 16 bytes for b.
When no Frame Pointer is used, the assembly programmer must know how much stack
space has been used since entry to the procedure. If no further stack space is used,
the calculation is similar to Example 10-3. b would be accessed via W15-20; 4 bytes
for the return address and 16 bytes to access the start of b.
10.8.2 Return Value
Function return values are returned in W0 for 8- or 16-bit scalars, W1:W0 for 32-bit
scalars, and W3:W2:W1:W0 for 64-bit scalars. Aggregates are returned indirectly
through W0, which is set up by the function caller to contain the address of the
aggregate value.
10.8.3 Preservi ng Registers Across Function Calls
The compiler arranges for registers W8-W15 to be preserved across ordinary function
calls. Registers W0-W7 are available as scratch registers. For interrupt functions, the
compiler arranges for all necessary registers to be preserved, namely W0-W15 and
RCOUNT.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 164 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 165
Chapter 11. Interrupts
11.1 INTRODUCTION
Interrupt processing is an important aspect of most microcontroller applications.
Interrupts may be used to synchronize software operations with events that occur in
real time. When interrupts occur, the normal flow of software execution is suspended
and special functions are invoked to process the event. At the completion of interrupt
processing, previous context information is restored and normal execution resumes.
This chapter presents an overview of interrupt processing. The following items are
discussed:
•Interrupt Operation – An overview of how interrupts operate.
•Writing an Interrupt Service Routine – You can designate one or more C
functions as Interrupt Service Routines (ISRs) to be invoked by the occurrence of
an interrupt. For best performance in general, place lengthy calculations or opera-
tions that require library calls in the main application. This strategy optimizes
performance and minimizes the possibility of losing information when interrupt
events occur rapidly.
•Specifying the Interrupt Vector – The 16-bi t devices use inter rupt vectors to
transfer application control when an interrupt occurs. An interrupt vector is a
dedicated location in program memory that specifies the address of an ISR.
Applications must contain valid function addresses in these locations to use
interrupts.
•Interrupt Se rvice Routine Context Saving – To handle returning from an
interrupt to code in the same conditional state as before the interrupt, context
information from specific registers must be saved.
•Nesting Interrupts – The time between when an interrupt is called and when the
first ISR instruction is executed is the latency of the interrupt.
•Enabling/Disabling Interrupts – How interrupt priorities are determined.
Enabling and disabling interrupt sources occurs at two levels: globally and individ-
ually.
•ISR Considerations– Sharing memory with mainline code, PSV usage with ISRs,
and calling functions within ISRs.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 166 2012 Microchip Technology Inc.
11.2 INTERRUPT OPERATION
The compiler incorporates features allowing interrupts to be fully handled from C code.
Interrupt functions are often called ISRs.
The 16-bit devices allow interrupts to be generated from many interrupt sources. Most
sources have their own dedicated interrupt vector collated in an interrupt vector table
(IVT). Each vector consists of an address at which is found the entry point of the inter-
rupt service routine. Some of the interrupt table vector locations are for traps, which are
nonmaskable interrupts which deal with erroneous operation of the device, such as an
address error.
On some devices, an alternate interrupt vector table (AIVT) is provided, which allow
independent interrupt vectors to be specified. This table can be enabled when required,
forcing ISR addresses to be read from the AIVT rather than the IVT.
Interrupts have a priority associated with them. This can be independently adjusted for
each interrupt source. When more than interrupt with the same priority are pending at
the same time, the intrinsic priority , or natural order priority , of each source comes into
play . The natural order priority is typically the same as the order of the interrupt vectors
in the IVT.
The compiler provides full support for interrupt processing in C or inline assembly code.
Interrupt code is the name given to any code that executes as a result of an interrupt
occurring. Interrupt code completes at the point where the corresponding return from
interrupt instruction is executed.
This contrasts with main-line code, which, for a freestanding application, is usually the
main part of the program that executes after Reset.
11.3 WRITING AN INTERRUPT SERVICE ROUTINE
Following the guidelines in this section, you can write all of your application code,
including your interrupt service routines, using only C language constructs.
11.3.1 Guidelines for Writing ISRs
The following guidelines are suggested for writing ISRs:
• declare ISRs with no parameters and a void return type (mandatory)
• do not let ISRs be called by main line code (mandatory)
• do not let ISRs call other functions (recommended)
A 16-bit device ISR is like any other C function in that it can have local variables and
access global variables. However, an ISR needs to be declared with no parameters
and no return value. This is necessary because the ISR, in response to a hardware
interrupt or trap, is invoked asynchronously to the mainline C program (that is, it is not
called in the normal way, so parameters and return values don’t apply).
ISRs should only be invoked through a hardware interrupt or trap and not from other C
functions. An ISR uses the return from interrupt (RETFIE) instruction to exit from the
function rather than the normal RETURN instruct ion. Using a RETFIE instruction out of
context can corrup t processor resources, such as the Sta tus register.
Finally, ISRs should avoid calling other functions. This is recommended because of
latency issues. See Section 11.6 “Nesting Interrupts” for more information.
Interrupts
2012 Microchip Technology Inc. DS52071B-page 167
11.3 .2 Syntax for Writ in g ISR s
To declare a C function as an interrupt handler, tag the function with the interrupt attri-
bute (see § 2.3 for a description of the __attribute__ keyword) . The sy ntax of the
interrupt attribute is:
__attribute__((interrupt [(
[ save(symbol-list)]
[, irq(irqid)]
[, altirq(altirqid)]
[, preprologue(asm)]
)]
))
The interrupt attribute name and the parameter names may be written with a pair
of underscore characters before and after the name. Thus, interrupt and
__interrupt__ are equivalent, as are save and __save__.
The optional save parameter names a list of one or more variables that are to be saved
and restored on entry to and exit from the ISR. The list of names is written inside paren-
theses, with the names separated by commas.
You should arrange to save global variables that may be modified in an ISR if you do
not want the value to be exported. Global variables accessed by an ISR should be
qualified volatile.
The optional irq parameter allows you to place an interrupt vector at a specific
interrupt, and the optional altirq parameter allows you to place an interrupt vector at
a specified alternate interrupt. Each parameter requires a parenthesized interrupt ID
number. (See Section 11.4 “Specifying the Interrupt Vector” for a list of interrupt
IDs.)
The optional preprologue parameter allows you to insert assembly-language
statements into the generated code immediately before the compiler-generated
function prolo gue .
When using the interrupt attribute, please specify either auto_psv or
no_auto_psv. If none is specified a warning will be produced and auto_psv will be
assumed.
11.3.3 Coding ISRs
The following prototype declares function isr0 to be an interrupt handler:
void __attribute__((__interrupt__,__auto_psv__)) isr0(void);
As this prototype indicates, interrupt functions must not take parameters nor may they
return a value. The compiler arranges for all working registers to be preserved, as well
as the S tatus register and the Repeat Count register , if necessary . Other variables may
be saved by naming them as parameters of the interrupt attribute. For example, to
have the compiler automatically save and restore the variables, var1 and var2, use
the following prototype:
void __attribute__((__interrupt__,__auto_psv__
(__save__(var1,var2)))) isr0(void);
To request the compiler to use the fast context save (using the push.s and pop.s
instructions), tag the function with the shadow attribute (see Section 10.2.1 “Function
Specifiers”). For example:
void __attribute__((__interrupt__,__auto_psv__, __shadow__))
isr0(void);
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 168 2012 Microchip Technology Inc.
11.3.4 Using Macros to Declare Simple ISRs
If an interrupt handler does not require any of the optional parameters of the interrupt
attribute, then a simplified syntax may be used. The following macros are defined in the
device-specific header files:
#define _ISR __attribute__((interrupt))
#define _ISRFAST __attribute__((interrupt, shadow))
For example, to declare an interrupt handler for the timer0 interrupt:
#include <p30fxxxx.h>
void _ISR _INT0Interrupt(void);
To declare an interrupt handler for the SPI1 interrupt with fast context save:
#include <p30fxxxx.h>
void _ISRFAST _SPI1Interrupt(void);
Interrupts
2012 Microchip Technology Inc. DS52071B-page 169
11.4 SPECIFYING THE INTERRUPT VECTOR
Many 16-bit devices have two interrupt vector tables – a primary and an alternate table
– each containing several exception vectors.
The exception sources have associated with them a primary and alternate exception
vector, each occupying a program word, as shown in the tables below. The alternate
vector name is used when the ALTIVT bit is set in the INTCON2 register.
To field an interrupt, a function’s address must be placed at the appropriate address in
one of the vector tables, and the function must preserve any system resources that it
uses. It must return to the foreground task using a RETFIE processor instruction.
Interrupt functions may be written in C. When a C function is designated as an interrupt
handler, the compiler arranges to preserve all the system resources that the compiler
uses, and to return from the function using the appropriate instruction. The compiler
can optionally arrange for the interrupt vector table to be populated with the interrupt
function’s address.
To arrange for the compiler to fill in the interrupt vector to point to the interrupt function,
name the function as denoted in the preceding table. For example, the stack error
vector will automatically be filled if the following function is defined:
void __attribute__((__interrupt__,__auto_psv__)) _StackError(void);
Note the use of the leading underscore. Similarly, the alternate stack error vector will
automatically be filled if the following function is defined:
void __attribute__((__interrupt__,__auto_psv__))
_AltStackError(void);
Again, note the use of the leading underscore.
For all interrupt vectors without specific handlers, a default interrupt handler will be
installed. The default interrupt handler is supplied by the linker and simply resets the
device. An application may also provide a default interrupt handler by declaring an
interrupt function with the name _DefaultInterrupt.
The last nine interrupt vectors in each table do not have predefined hardware functions.
The vectors for these interrupts may be filled by using the names indicated in the
preceding table, or , names more appropriate to the application may be used, while still
filling the appropriate vector entry by using the irq or altirq parameter of the
interrupt attribute. For example, to specify that a function should use primary interrupt
vector 52, use the following:
void __attribute__((__interrupt__,__auto_psv__,__irq__(52)))
MyIRQ(void);
Similarly, to specify that a function should use alternate interrupt vector 52, use the fol-
lowing:
void __attribute__((__interrupt__,__auto_psv__,__altirq__(52)))
MyAltIRQ(void);
Note: A device Reset is not handled through the interrupt vector table. Instead,
on device Reset, the program counter is cleared. This causes the processor
to begin execution at address zero. By convention, the linker script
constructs a GOTO instruction at that location which transfers control to the
C run-time startup module.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 170 2012 Microchip Technology Inc.
The irq/altirq number can be one of the interrupt request numbers 45 to 53. If the
irq parameter of the interrupt attribute is used, the compiler creates the external
symbol name __Interruptn, where n is the vector number. Therefore, the C
identifiers _Interrupt45 through _Interrupt53 are reserved by the compiler. In
the same way, if the altirq parameter of the interrupt attribute is used, the compiler
creates the external symbol name __AltInterruptn, wher e n is the vecto r number.
Therefore, the C identifiers _AltInterrupt45 through _AltInterrupt53 are
reserved by the compiler.
11.4.1 Non-SMPS dsPIC30F DSCs Interrupt Vectors
Most dsPIC30F DSCs are not Switch Mode Power Supply (SMPS) devices. Consult
your device data sheet to see if it is an SMPS device.
TABLE 11-1: INTERRUPT VECTORS – NON-SMPS dsPIC30F DSCs
IRQ# Primary Name Alternate Name Vector Function
N/A _ReservedTrap0 _AltReservedTrap0 Reserved
N/A _OscillatorFail _AltOscillatorFail Oscillator fail trap
N/A _AddressError _AltAddressErr or Address error trap
N/A _StackError _AltStackError Stack error trap
N/A _MathError _AltMathError Math error trap
N/A _ReservedTrap5 _AltReservedTrap5 Reserved
N/A _ReservedTrap6 _AltReservedTrap6 Reserved
N/A _ReservedTrap7 _AltReservedTrap7 Reserved
0 _INT0Interrupt _AltINT0Interrupt INT0 External interrupt 0
1 _IC1Interrupt _AltIC1Interrupt IC1 Input Capture 1
2 _OC1Interrupt _AltOC1Interrupt OC1 Output Compare 1
3 _T1Interrupt _AltT1Interrupt TMR1 Timer 1 expired
4 _IC2Interrupt _AltIC2Interrupt IC2 Input Capture 2
5 _OC2Interrupt _AltOC2Interrupt OC2 Output Compare 2
6 _T2Interrupt _AltT2Interrupt TMR2 Timer 2 expired
7 _T3Interrupt _AltT3Interrupt TMR3 Timer 3 expired
8 _SPI1Interrupt _AltSPI1Interrupt SPI1 Serial Peripheral Interface 1
9 _U1RXInterrupt _AltU1RXInterrupt UART1RX Uart 1 Receiver
10 _U1TXInterrupt _Al tU1TXInter rupt UART1TX Uart 1 Transmi tter
11 _ADCInterrupt _AltADCInterrupt ADC convert completed
12 _NVMInterr upt _AltNVMInter rupt NMM NVM write co mpleted
13 _SI2CInterrupt _AltSI2CI nterrupt Slave I 2C™ interrupt
14 _MI2C Interrupt _AltMI2CInterrupt Master I2C interrupt
15 _CNInterrupt _AltCNInterrupt CN Input change interrupt
16 _INT1Interrupt _AltINT1Interrupt INT1 External interrupt 0
17 _IC7Interrupt _AltIC7I nterru pt IC7 Inpu t Capture 7
18 _IC8Interrupt _AltIC8I nterru pt IC8 Inpu t Capture 8
19 _OC3Interrupt _AltOC3Interrupt OC3 Output Compare 3
20 _OC4Interrupt _AltOC4Interrupt OC4 Output Compare 4
21 _T4Interrupt _Alt T4Interrupt TMR4 Timer 4 expired
22 _T5Interrupt _Alt T5Interrupt TMR5 Timer 5 expired
23 _INT2Interrupt _AltINT2Interrupt INT2 External interrupt 2
24 _U2R XInterrupt _AltU2 RXIn terrup t UART2RX Uart 2 Receiver
25 _U2TXInterrupt _Al tU2TXInter rupt UART2TX Uart 2 Transmi tter
DD
Interrupts
2012 Microchip Technology Inc. DS52071B-page 171
26 _SPI2Interrupt _AltSPI2Interrupt SPI2 Serial Peripheral Interface 2
27 _C1Interrupt _AltC1Interrupt CAN1 combined IRQ
28 _IC3Interrupt _AltIC3I nterru pt IC3 Inpu t Capture 3
29 _IC4Interrupt _AltIC4I nterru pt IC4 Inpu t Capture 4
30 _IC5Interrupt _AltIC5I nterru pt IC5 Inpu t Capture 5
31 _IC6Interrupt _AltIC6I nterru pt IC6 Inpu t Capture 6
32 _OC5Interrupt _AltOC5Interrupt OC5 Output Compare 5
33 _OC6Interrupt _AltOC6Interrupt OC6 Output Compare 6
34 _OC7Interrupt _AltOC7Interrupt OC7 Output Compare 7
35 _OC8Interrupt _AltOC8Interrupt OC8 Output Compare 8
36 _INT3Interrupt _AltINT3Interrupt INT3 External interrupt 3
37 _INT4Interrupt _AltINT4Interrupt INT4 External interrupt 4
38 _C2Interrupt _AltC2Interrupt CAN2 combined IRQ
39 _PWMInterrupt _AltPWMInterrupt PWM period ma tch
40 _QEIInterrupt _AltQEIInterrupt QEI position counter compare
41 _DCIInterrupt _AltDCIInterrupt DCI CODEC transfer completed
42 _LVDInterrupt _AltLVDInterrupt PLVD low voltage detected
43 _FLTAInterrupt _AltFLTA Interrupt FLTA MCPWM fault A
44 _FLTBInterrupt _AltFLTBInterrupt FLTB MCPWM fault B
45 _Interrupt45 _AltInterrupt45 Reserved
46 _Interrupt46 _AltInterrupt46 Reserved
47 _Interrupt47 _AltInterrupt47 Reserved
48 _Interrupt48 _AltInterrupt48 Reserved
49 _Interrupt49 _AltInterrupt49 Reserved
50 _Interrupt50 _AltInterrupt50 Reserved
51 _Interrupt51 _AltInterrupt51 Reserved
52 _Interrupt52 _AltInterrupt52 Reserved
53 _Interrupt53 _AltInterrupt53 Reserved
TABLE 11-1: INTERRUPT VECTORS – NON-SMPS dsPIC30F DSCs
IRQ# Primary Name Alternate Name Vector Function
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 172 2012 Microchip Technology Inc.
11.4.2 SMPS dsPIC30F DSCs Interrupt Vectors
Most dsPIC30F MCUs are not Switch Mode Power Supply (SMPS) devices. Consult
your device data sheet to see if it is an SMPS device.
TABLE 11-2: INTERRUPT VECTORS – SMPS dsPIC30F DSCs
IRQ# Primary Name Alternate Name Vector Function
N/A _ReservedTrap0 _AltReservedTrap0 Reserved
N/A _OscillatorFail _AltOscillatorFail Oscillator fail trap
N/A _AddressError _AltAddressErr or Address error trap
N/A _StackError _AltStackError Stack error trap
N/A _MathError _AltMathError Math error trap
N/A _ReservedTrap5 _AltReservedTrap5 Reserved
N/A _ReservedTrap6 _AltReservedTrap6 Reserved
N/A _ReservedTrap7 _AltReservedTrap7 Reserved
0 _INT0Interrupt _AltINT0Interrupt INT0 External interrupt 0
1 _IC1Interrupt _AltIC1Interrupt IC1 Input Capture 1
2 _OC1Interrupt _AltOC1Interrupt OC1 Output Compare 1
3 _T1Interrupt _AltT1Interrupt TMR1 Timer 1 expired
4 _Interrupt4 _AltInterrupt4 Reserved
5 _OC2Interrupt _AltOC2Interrupt OC2 Output Compare 2
6 _T2Interrupt _AltT2Interrupt TMR2 Timer 2 expired
7 _T3Interrupt _AltT3Interrupt TMR3 Timer 3 expired
8 _SPI1Interrupt _AltSPI1Interrupt SPI1 Serial periphe ral interface 1
9 _U1RXInterrupt _AltU1RXInterrupt UART1RX Uart 1 Receiver
10 _U1TXInterrupt _Al tU1TXInter rupt UART1TX Uart 1 Transmi tter
11 _ADCInterrupt _AltADCInterrupt ADC Convert completed
12 _NVMInterrupt _AltNVMInterrupt NVM wri te completed
13 _SI2CInterrupt _AltSI2CI nterrupt Slave I 2C™ interrupt
14 _MI2C Interrupt _AltMI2CInterrupt Master I2C interrupt
15 _Interrupt15 _AltInterrupt15 Reserved
16 _INT1Interrupt _AltINT1Interrupt INT1 External interrupt 1
17 _INT2Interrupt _AltINT2Interrupt INT2 External interrupt 2
18 _PWMSpEvent
MatchInterrupt _AltPWMSpEvent
MatchInterrupt PWM special event interrupt
19 _PWM1Interrupt _AltPWM1Interr upt PWM period match 1
20 _PWM2Interrupt _AltPWM2Interr upt PWM period match 2
21 _PWM3Interrupt _AltPWM3Interr upt PWM period match 3
22 _PWM4Interrupt _AltPWM4Interr upt PWM period match 4
23 _Interrupt23 _AltInterrupt23 Reserved
24 _Interrupt24 _AltInterrupt24 Reserved
25 _Interrupt25 _AltInterrupt25 Reserved
26 _Interrupt26 _AltInterrupt26 Reserved
27 _CNInterrupt _AltCNInterrupt Input Change Notification
28 _Interrupt28 _AltInterrupt28 Reserved
29 _CMP1Interrupt _AltCMP1Interrupt Analog comparator interrupt 1
30 _CMP2Interrupt _AltCMP2Interrupt Analog comparator interrupt 2
31 _CMP3Interrupt _AltCMP3Interrupt Analog comparator interrupt 3
32 _CMP4Interrupt _AltCMP4Interrupt Analog comparator interrupt 4
DD
Interrupts
2012 Microchip Technology Inc. DS52071B-page 173
33 _Interrupt33 _AltInterrupt33 Reserved
34 _Interrupt34 _AltInterrupt34 Reserved
35 _Interrupt35 _AltInterrupt35 Reserved
36 _Interrupt36 _AltInterrupt36 Reserved
37 _ADCP0Interrupt _AltADCP0Interrupt ADC Pair 0 conversion complete
38 _ADCP1Interrupt _AltADCP1Interrupt ADC Pair 1 conversion complete
39 _ADCP2Interrupt _AltADCP2Interrupt ADC Pair 2 conversion complete
40 _ADCP3Interrupt _AltADCP3Interrupt ADC Pair 3 conversion complete
41 _ADCP4Interrupt _AltADCP4Interrupt ADC Pair 4 conversion complete
42 _ADCP5Interrupt _AltADCP5Interrupt ADC Pair 5 conversion complete
43 _Interrupt43 _AltInterrupt43 Reserved
44 _Interrupt44 _AltInterrupt44 Reserved
45 _Interrupt45 _AltInterrupt45 Reserved
46 _Interrupt46 _AltInterrupt46 Reserved
47 _Interrupt47 _AltInterrupt47 Reserved
48 _Interrupt48 _AltInterrupt48 Reserved
49 _Interrupt49 _AltInterrupt49 Reserved
50 _Interrupt50 _AltInterrupt50 Reserved
51 _Interrupt51 _AltInterrupt51 Reserved
52 _Interrupt52 _AltInterrupt52 Reserved
53 _Interrupt53 _AltInterrupt53 Reserved
TABLE 11-2: INTERRUPT VECTORS – SMPS dsPIC30F DSCs (CONTINUED)
IRQ# Primary Name Alternate Name Vector Function
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 174 2012 Microchip Technology Inc.
11.4.3 PIC24F MCUs Interrupt Vectors
The table below specifies the interrupt vectors for these 16-bit devices.
TABLE 11-3: INTERRUPT VECTORS - PIC24F MCUs
IRQ# Primary Name Alternate Name Vector Function
N/A _ReservedTrap0 _AltReservedTrap0 Reserved
N/A _OscillatorFail _AltOscillatorFail Oscillator fail trap
N/A _AddressError _AltAddressErr or Address error trap
N/A _StackError _AltStackError Stack error trap
N/A _MathError _AltMathError Math error trap
N/A _ReservedTrap5 _AltReservedTrap5 Reserved
N/A _ReservedTrap6 _AltReservedTrap6 Reserved
N/A _ReservedTrap7 _AltReservedTrap7 Reserved
0 _INT0Interrupt _AltINT0Interrupt INT0 External interrupt 0
1 _IC1Interrupt _AltIC1Interrupt IC1 Input Capture 1
2 _OC1Interrupt _AltOC1Interrupt OC1 Output Compare 1
3 _T1Interrupt _AltT1Interrupt TMR1 Timer 1 expired
4 _Interrupt4 _AltInterrupt4 Reserved
5 _IC2Interrupt _AltIC2Interrupt IC2 Input Capture 2
6 _OC2Interrupt _AltOC2Interrupt OC2 Output Compare 2
7 _T2Interrupt _AltT2Interrupt TMR2 Timer 2 expired
8 _T3Interrupt _AltT3Interrupt TMR3 Timer 3 expired
9 _SPI1ErrInterrupt _AltSPI1ErrInterrupt SPI1 error interrupt
10 _SPI 1Interrupt _AltSPI1Interrupt SPI1 transfer co mpleted inte rrup t
11 _U1RXInterrupt _AltU1RXInterrupt UART1RX Uart 1 Receiver
12 _U1TXInterrupt _Al tU1TXInter rupt UART1TX Uart 1 Transmi tter
13 _ADC1Interrupt _AltADC1Int errupt ADC 1 convert co mpleted
14 _Interrupt14 _AltInterrupt14 Reserved
15 _Interrupt15 _AltInterrupt15 Reserved
16 _SI2C1Interrupt _AltSI2C1Interrupt Slave I2C™ interrupt 1
17 _MI2C1Interrupt _AltMI2C1Interrupt Master I2C interrupt 1
18 _CompInterrupt _AltCompInterrupt Comparator interr upt
19 _CNInterrupt _AltCNInterrupt CN Input change interrupt
20 _INT1Interrupt _AltINT1Interrupt INT1 External interrupt 1
21 _Interrupt21 _AltInterrupt21 Reserved
22 _Interrupt22 _AltInterrupt22 Reserved
23 _Interrupt23 _AltInterrupt23 Reserved
24 _Interrupt24 _AltInterrupt24 Reserved
25 _OC3Interrupt _AltOC3Interrupt OC3 Output Compare 3
26 _OC4Interrupt _AltOC4Interrupt OC4 Output Compare 4
27 _T4Interrupt _Alt T4Interrupt TMR4 Timer 4 expired
28 _T5Interrupt _Alt T5Interrupt TMR5 Timer 5 expired
29 _INT2Interrupt _AltINT2Interrupt INT2 External interrupt 2
30 _U2R XInterrupt _AltU2 RXIn terrup t UART2RX Uart 2 Receiver
31 _U2TXInterrupt _Al tU2TXInter rupt UART2TX Uart 2 Transmi tter
32 _SPI2ErrInterrupt _AltSPI2ErrInterrupt SPI2 error interrupt
33 _SPI 2Interrupt _AltSPI2Interrupt SPI2 transfer co mpleted inte rrup t
34 _Interrupt34 _AltInterrupt34 Reserved
DD
Interrupts
2012 Microchip Technology Inc. DS52071B-page 175
35 _Interrupt35 _AltInterrupt35 Reserved
36 _Interrupt36 _AltInterrupt36 Reserved
37 _IC3Interrupt _AltIC3I nterru pt IC3 Inpu t Capture 3
38 _IC4Interrupt _AltIC4I nterru pt IC4 Inpu t Capture 4
39 _IC5Interrupt _AltIC5I nterru pt IC5 Inpu t Capture 5
40 _Interrupt40 _AltInterrupt40 Reserved
41 _OC5Interrupt _AltOC5Interrupt OC5 Output Compare 5
42 _Interrupt42 _AltInterrupt42 Reserved
43 _Interrupt43 _AltInterrupt43 Reserved
44 _Interrupt44 _AltInterrupt44 Reserved
45 _PMPInterrupt _AltPMPInterrupt Parallel master port interrupt
46 _Interrupt46 _AltInterrupt46 Reserved
47 _Interrupt47 _AltInterrupt47 Reserved
48 _Interrupt48 _AltInterrupt48 Reserved
49 _SI2C2Interrupt _AltSI2C2Interrupt Slave I2C™ interrupt 2
50 _MI2C2Interrupt _AltMI2C2Interrupt Master I2C interrupt 2
51 _Interrupt51 _AltInterrupt51 Reserved
52 _Interrupt52 _AltInterrupt52 Reserved
53 _INT3Interrupt _AltINT3Interrupt INT3 External interrupt 3
54 _INT4Interrupt _AltINT4Interrupt INT4 External interrupt 4
55 _Interrupt55 _AltInterrupt55 Reserved
56 _Interrupt56 _AltInterrupt56 Reserved
57 _Interrupt57 _AltInterrupt57 Reserved
58 _Interrupt58 _AltInterrupt58 Reserved
59 _Interrupt59 _AltInterrupt59 Reserved
60 _Interrupt60 _AltInterrupt60 Reserved
61 _Interrupt61 _AltInterrupt61 Reserved
62 _RTCCInterrupt _AltRTCCInterrupt Real-Time Clock And Calender
63 _Interrupt63 _AltInterrupt63 Reserved
64 _Interrupt64 _AltInterrupt64 Reserved
65 _U1ErrInterrupt _AltU1ErrInterrupt UART1 error interrupt
66 _U2ErrInterrupt _AltU2ErrInterrupt UART2 error interrupt
67 _CRCInterrupt _AltCRCInterrupt Cyclic Redundancy Check
68 _Interrupt68 _AltInterrupt68 Reserved
69 _Interrupt69 _AltInterrupt69 Reserved
70 _Interrupt70 _AltInterrupt70 Reserved
71 _Interrupt71 _AltInterrupt71 Reserved
72 _Interrupt72 _AltInterrupt72 Reserved
73 _Interrupt73 _AltInterrupt73 Reserved
74 _Interrupt74 _AltInterrupt74 Reserved
75 _Interrupt75 _AltInterrupt75 Reserved
76 _Interrupt76 _AltInterrupt76 Reserved
77 _Interrupt77 _AltInterrupt77 Reserved
78 _Interrupt78 _AltInterrupt78 Reserved
79 _Interrupt79 _AltInterrupt79 Reserved
TABLE 11-3: INTERRUPT VECTORS - PIC24F MCUs (CONTINUED)
IRQ# Primary Name Alternate Name Vector Function
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 176 2012 Microchip Technology Inc.
80 _Interrupt80 _AltInterrupt80 Reserved
81 _Interrupt81 _AltInterrupt81 Reserved
82 _Interrupt82 _AltInterrupt82 Reserved
83 _Interrupt83 _AltInterrupt83 Reserved
84 _Interrupt84 _AltInterrupt84 Reserved
85 _Interrupt85 _AltInterrupt85 Reserved
86 _Interrupt86 _AltInterrupt86 Reserved
87 _Interrupt87 _AltInterrupt87 Reserved
88 _Interrupt88 _AltInterrupt88 Reserved
89 _Interrupt89 _AltInterrupt89 Reserved
90 _Interrupt90 _AltInterrupt90 Reserved
91 _Interrupt91 _AltInterrupt91 Reserved
92 _Interrupt92 _AltInterrupt92 Reserved
93 _Interrupt93 _AltInterrupt93 Reserved
94 _Interrupt94 _AltInterrupt94 Reserved
95 _Interrupt95 _AltInterrupt95 Reserved
96 _Interrupt96 _AltInterrupt96 Reserved
97 _Interrupt97 _AltInterrupt97 Reserved
98 _Interrupt98 _AltInterrupt98 Reserved
99 _Interrupt99 _AltInterrupt99 Reserved
100 _Interrupt100 _AltInterrupt100 Reserved
101 _Interrupt101 _AltInterrupt101 Reserved
102 _Interrupt102 _AltInterrupt102 Reserved
103 _Interrupt103 _AltInterrupt103 Reserved
104 _Interrupt104 _AltInterrupt104 Reserved
105 _Interrupt105 _AltInterrupt105 Reserved
106 _Interrupt106 _AltInterrupt106 Reserved
107 _Interrupt107 _AltInterrupt107 Reserved
108 _Interrupt108 _AltInterrupt108 Reserved
109 _Interrupt109 _AltInterrupt109 Reserved
110 _Interrupt110 _AltInterrupt110 Reserved
111 _Interrupt111 _AltInterrupt111 Reserved
112 _Interrupt112 _AltInterrupt112 Reserved
113 _Interrupt113 _AltInterrupt113 Reserved
114 _Interrupt114 _AltInterrupt114 Reserved
115 _Interrupt115 _AltInterrupt115 Reserved
116 _Interrupt116 _AltInterrupt116 Reserved
117 _Interrupt117 _AltInterrupt117 Reserved
TABLE 11-3: INTERRUPT VECTORS - PIC24F MCUs (CONTINUED)
IRQ# Primary Name Alternate Name Vector Function
Interrupts
2012 Microchip Technology Inc. DS52071B-page 177
11.4.4 dsPIC33F DSCs/PIC24H MCUs Interrupt Vectors
The table below specifies the interrupt vectors for these 16-bit devices.
TABLE 11-4: INTERRUPT VECTORS - dsPIC33F DSCs/PIC24H MCUs
IRQ# Primary Name Alternate Name Vector Function
N/A _ReservedTrap0 _AltReservedTrap0 Reserved
N/A _OscillatorFail _AltOscillatorFail Oscillator fail trap
N/A _AddressError _AltAddressErr or Address error trap
N/A _StackError _AltStackError Stack error trap
N/A _MathError _AltMathError Math error trap
N/A _DMACError _AltDMACError DMA conflict error trap
N/A _ReservedTrap6 _AltReservedTrap6 Reserved
N/A _ReservedTrap7 _AltReservedTrap7 Reserved
0 _INT0Interrupt _AltINT0Interrupt INT0 External interrupt 0
1 _IC1Interrupt _AltIC1Interrupt IC1 Input Capture 1
2 _OC1Interrupt _AltOC1Interrupt OC1 Output Compare 1
3 _T1Interrupt _AltT1Interrupt TMR1 Timer 1 expired
4 _DMA0Interrupt _AltDMA0Interrupt DMA 0 interrupt
5 _IC2Interrupt _AltIC2Interrupt IC2 Input Capture 2
6 _OC2Interrupt _AltOC2Interrupt OC2 Output Compare 2
7 _T2Interrupt _AltT2Interrupt TMR2 Timer 2 expired
8 _T3Interrupt _AltT3Interrupt TMR3 Timer 3 expired
9 _SPI1ErrInterrupt _AltSPI1ErrInterrupt SPI1 error interrupt
10 _SPI 1Interrupt _AltSPI1Interrupt SPI1 transfer co mpleted inte rrup t
11 _U1RXInterrupt _AltU1 RXIn terrup t UART1RX Uart 1 Receiver
12 _U1TXInterrupt _Al tU1TXInter rupt UART1TX Uart 1 Transmi tter
13 _ADC1Interrupt _Alt ADC1Int erru pt ADC 1 convert completed
14 _DMA1Interrupt _AltDMA1Interrupt DMA 1 interrupt
15 _Interrupt15 _AltInterrupt15 Reserved
16 _SI2C1Interrupt _AltSI2C1Interrupt Slave I2C™ interrupt 1
17 _MI2C1Interrupt _AltMI2C1Interrupt Master I2C interrupt 1
18 _Interrupt18 _AltInterrupt18 Reserved
19 _CNInterrupt _AltCNInterrupt CN Input change interrupt
20 _INT1Interrupt _AltINT1Interrupt INT1 External interrupt 1
21 _ADC2Interrupt _Alt ADC2Int erru pt ADC 2 convert completed
22 _IC7Interrupt _AltIC7I nterru pt IC7 Inpu t Capture 7
23 _IC8Interrupt _AltIC8I nterru pt IC8 Inpu t Capture 8
24 _DMA2Interrupt _AltDMA2Interrupt DMA 2 interrupt
25 _OC3Interrupt _AltOC3Interrupt OC3 Output Compare 3
26 _OC4Interrupt _AltOC4Interrupt OC4 Output Compare 4
27 _T4Interrupt _Alt T4Interrupt TMR4 Timer 4 expired
28 _T5Interrupt _Alt T5Interrupt TMR5 Timer 5 expired
29 _INT2Interrupt _AltINT2Interrupt INT2 External interrupt 2
30 _U2R XInterrupt _AltU2 RXIn terrup t UART2RX Uart 2 Receiver
31 _U2TXInterrupt _Al tU2TXInter rupt UART2TX Uart 2 Transmi tter
32 _SPI2ErrInterrupt _AltSPI2ErrInterrupt SPI2 error interrupt
33 _SPI 2Interrupt _AltSPI2Interrupt SPI2 transfer co mpleted inte rrup t
34 _C1RxRdyInterrupt _AltC1 RxRdyInterrupt CAN1 receive data re ady
DD
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 178 2012 Microchip Technology Inc.
35 _ C1 Int errup t _AltC1I nterrupt CAN1 completed interrupt
36 _DMA3Interrupt _AltDMA3Interrupt DMA 3 interrupt
37 _IC3Interrupt _AltIC3I nterru pt IC3 Inpu t Capture 3
38 _IC4Interrupt _AltIC4I nterru pt IC4 Inpu t Capture 4
39 _IC5Interrupt _AltIC5I nterru pt IC5 Inpu t Capture 5
40 _IC6Interrupt _AltIC6I nterru pt IC6 Inpu t Capture 6
41 _OC5Interrupt _AltOC5Interrupt OC5 Output Compare 5
42 _OC6Interrupt _AltOC6Interrupt OC6 Output Compare 6
43 _OC7Interrupt _AltOC7Interrupt OC7 Output Compare 7
44 _OC8Interrupt _AltOC8Interrupt OC8 Output Compare 8
45 _Interrupt45 _AltInterrupt45 Reserved
46 _DMA4Interrupt _AltDMA4Interrupt DMA 4 interrupt
47 _T6Interrupt _Alt T6Interrupt TMR6 Timer 6 expired
48 _T7Interrupt _Alt T7Interrupt TMR7 Timer 7 expired
49 _SI2C2Interrupt _AltSI2C2Interrupt Slave I2C interrupt 2
50 _MI2C2Interrupt _AltMI2C2Interrupt Master I2C interrupt 2
51 _T8Interrupt _Alt T8Interrupt TMR8 Timer 8 expired
52 _T9Interrupt _Alt T9Interrupt TMR9 Timer 9 expired
53 _INT3Interrupt _AltINT3Interrupt INT3 External interrupt 3
54 _INT4Interrupt _AltINT4Interrupt INT4 External interrupt 4
55 _C2RxRdyInterrupt _AltC2 RxRdyInterrupt CAN2 receive data re ady
56 _ C2 Int errup t _AltC2I nterrupt CAN2 completed interrupt
57 _PWMInterrupt _AltPWMInterrupt PWM period ma tch
58 _QEIInterrupt _AltQEIInterrupt QEI position counter compare
59 _DCIErrInterrupt _AltDCIErrInterrupt DCI CODEC error interrupt
60 _DCIInterrupt _AltDCIInterrupt DCI CODEC transfer done
61 _DMA5Interrupt _AltDMA5Interrupt DMA channel 5 interrupt
62 _Interrupt62 _AltInterrupt62 Reserved
63 _FLTAInterrupt _A ltFLTAI nterrupt FLTA MCP WM fault A
64 _FLTBInterrupt _AltFLTBInterrupt FLTB MCPWM fault B
65 _U1ErrInterrupt _AltU1ErrInterrupt UART1 error interrupt
66 _U2ErrInterrupt _AltU2ErrInterrupt UART2 error interrupt
67 _Interrupt67 _AltInterrupt67 Reserved
68 _DMA6Interrupt _AltDMA6Interrupt DMA channel 6 interrupt
69 _DMA7Interrupt _AltDMA7Interrupt DMA channel 7 interrupt
70 _C1TxReqInterrupt _AltC1TxReqIn terr upt CAN1 tra nsmit data request
71 _C2TxReqInterrupt _AltC2TxReqIn terr upt CAN2 tra nsmit data request
72 _Interrupt72 _AltInterrupt72 Reserved
73 _Interrupt73 _AltInterrupt73 Reserved
74 _Interrupt74 _AltInterrupt74 Reserved
75 _Interrupt75 _AltInterrupt75 Reserved
76 _Interrupt76 _AltInterrupt76 Reserved
77 _Interrupt77 _AltInterrupt77 Reserved
78 _Interrupt78 _AltInterrupt78 Reserved
79 _Interrupt79 _AltInterrupt79 Reserved
TABLE 11-4: INTERRUPT VECTORS - dsPIC33F DSCs/PIC24H MCUs
IRQ# Primary Name Alternate Name Vector Function
Interrupts
2012 Microchip Technology Inc. DS52071B-page 179
80 _Interrupt80 _AltInterrupt80 Reserved
81 _Interrupt81 _AltInterrupt81 Reserved
82 _Interrupt82 _AltInterrupt82 Reserved
83 _Interrupt83 _AltInterrupt83 Reserved
84 _Interrupt84 _AltInterrupt84 Reserved
85 _Interrupt85 _AltInterrupt85 Reserved
86 _Interrupt86 _AltInterrupt86 Reserved
87 _Interrupt87 _AltInterrupt87 Reserved
88 _Interrupt88 _AltInterrupt88 Reserved
89 _Interrupt89 _AltInterrupt89 Reserved
90 _Interrupt90 _AltInterrupt90 Reserved
91 _Interrupt91 _AltInterrupt91 Reserved
92 _Interrupt92 _AltInterrupt92 Reserved
93 _Interrupt93 _AltInterrupt93 Reserved
94 _Interrupt94 _AltInterrupt94 Reserved
95 _Interrupt95 _AltInterrupt95 Reserved
96 _Interrupt96 _AltInterrupt96 Reserved
97 _Interrupt97 _AltInterrupt97 Reserved
98 _Interrupt98 _AltInterrupt98 Reserved
99 _Interrupt99 _AltInterrupt99 Reserved
100 _Interrupt100 _AltInterrupt100 Reserved
101 _Interrupt101 _AltInterrupt101 Reserved
102 _Interrupt102 _AltInterrupt102 Reserved
103 _Interrupt103 _AltInterrupt103 Reserved
104 _Interrupt104 _AltInterrupt104 Reserved
105 _Interrupt105 _AltInterrupt105 Reserved
106 _Interrupt106 _AltInterrupt106 Reserved
107 _Interrupt107 _AltInterrupt107 Reserved
108 _Interrupt108 _AltInterrupt108 Reserved
109 _Interrupt109 _AltInterrupt109 Reserved
110 _Interrupt110 _AltInterrupt110 Reserved
111 _Interrupt111 _AltInterrupt111 Reserved
112 _Interrupt112 _AltInterrupt112 Reserved
113 _Interrupt113 _AltInterrupt113 Reserved
114 _Interrupt114 _AltInterrupt114 Reserved
115 _Interrupt115 _AltInterrupt115 Reserved
116 _Interrupt116 _AltInterrupt116 Reserved
117 _Interrupt117 _AltInterrupt117 Reserved
TABLE 11-4: INTERRUPT VECTORS - dsPIC33F DSCs/PIC24H MCUs
IRQ# Primary Name Alternate Name Vector Function
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 180 2012 Microchip Technology Inc.
11.5 INTERRUPT SERVICE ROUTINE CONTEXT SAVING
Interrupts, by their very nature, can occur at unpredictable times. Therefore, the
interrupted code must be able to resume with the same machine state that was present
when the interrupt occurred.
To properly handle a return from interrupt, the setup (prologue) code for an ISR function
automatically saves the compiler-managed working and special function registers on
the stack for later restoration at the end of the ISR. You can use the optional save
parameter of the interrupt attribute to specify additional variables and SFRs to be
saved and restored.
In certain applications, it may be necessary to insert assembly statements into the ISR
immediately prior to the compiler-generated function prologue. For example, it may be
required that a semaphore be incremented immediately on entry to an interrupt service
routine. This can be done as follows:
void __attribute__((__interrupt__,__auto_psv__(__preprologue__
("inc _semaphore")))) isr0(void);
The context switch leads to latency in interrupt code execution, as described in
Section 11.8.3 “Latency”.
11.6 NESTING INTERRUPTS
The 16-bit devices support nested interrupts. Since processor resources are saved on
the stack in an ISR, nested ISRs are coded in just the same way as non-nested ones.
Nested interrupts are enabled by clearing the NSTDIS (nested interrupt disable) bit in
the INTCON1 register . Note that this is the default condition as the 16-bit device comes
out of Reset with nested interrupts enabled. Each interrupt source is assigned a priority
in the Interrupt Priority Control registers (IPCn).
An interrupt is vectored if the priority of the interrupt source is greater than the current
CPU priority level.
Interrupts
2012 Microchip Technology Inc. DS52071B-page 181
11.7 ENABLING/DISABLING INTERRUPTS
Each interrupt source can be individually enabled or disabled. One interrupt enable bit
for each IRQ is allocated in the Interrupt Enable Control registers (IECn). Set tin g an
interrupt enable bit to one (1) enables the corresponding interrupt; clearing the interrupt
enable bit to zero (0) disables the corresponding interrupt. When the device comes out
of Reset, all interrupt enable bits are cleared to zero. In addition, the processor has a
disable interrupt instruction (DISI) that can disable all interrupts for a specified number
of instruction cycles.
The DISI instruction can be used in a C program through the use of:
__builtin_disi
For example:
__builtin_disi(16);
will emit the specified DISI instruction at the point it appears in the source program. A
disadvantage of using DISI in this way is that the C programmer cannot always be
sure how the C compiler will translate C source to machine instructions, so it may be
difficult to determine the cycle count for the DISI instruction. It is possible to get around
this difficulty by bracketing the code that is to be protected from interrupts by DISI
instructions, the first of which sets the cycle count to the maximum value, and the
second of which sets the cycle count to zero. For example,
__builtin_disi(0x3FFF); /* disable interrupts */
/* ... protected C code ... */
__builtin_disi(0x0000); /* enable interrupts */
An alternative approach is to write directly to the DISICNT register to enable interrupts.
The DISICNT register may be modified only after a DISI instruction has been issued
and if the contents of the DISICNT register are not zero.
__builtin_disi(0x3FFF); /* disable interrupts */
/* ... protected C code ... */
DISICNT = 0x0000; /* enable interrupts */
For some applications, it may be necessary to disable level 7 interrupts as well. These
can only be disabled through the modification of the COROCON IPL field. The provided
support files contain some useful preprocessor macro functions to help you safely
modify the IPL value. These macros are:
SET_CPU_IPL(ipl)
SET_AND_SAVE_CPU_IPL(save_to, ipl)
RESTORE_CPU_IPL(saved_to)
For example, you may wish to protect a section of code from interrupt. The following
code will adjust the current IPL setting and resto r e the IPL to its previous value.
void foo(void) {
int current_cpu_ipl;
SET_AND_SAVE_CPU_IPL(current_cpu_ipl, 7); /* disable interrupts */
/* protected code here */
RESTORE_CPU_IPL(current_cpu_ipl);
}
Note: Traps, such as the address error trap, cannot be disabled. Only IRQs can
be disabled .
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 182 2012 Microchip Technology Inc.
11.8 ISR CONSIDERATIONS
The following sections describe how to ensure your interrupt code works as expected.
11.8.1 Sharing Memory with Mainline Code
Exercise cauti on when modifying the same va riable within a main or low-priority ISR
and a high-priority ISR. Higher priority interrupts, when enabled, can interrupt a multiple
instruction sequence and yield unexpected results when a low-priority function has cre-
ated a multiple instruction Read-Modify-Write sequence accessing that same variable.
Therefore, embedded systems must implement an “atomic” operation to ensure that
the intervening high-priority ISR will not write to the variable from which the low-priority
ISR has just read, but not yet completed its write.
An atomic operation is one that cannot be broken down into its constituent parts – it
cannot be interrupted. Depending on which architecture is involved, not all C expres-
sions translate into an atomic operation. On dsPIC DSC devices, these expressions
mainly fall into the following categories: 32-bit expressions, floating point arithmetic,
division, and operations on multi-bit bitfields. Other factors will determine whether or
not an atomic operation will be generated, such as memory model settings,
optimization level and resource availability.
Consider the general expression:
foo = bar op baz;
The operator (op) may or may not be atomic, based on the architecture of the device.
In any event, the compiler may not be able to generate the atomic operation in all
instances, depending on factors that may include the following:
• availability of an appropriate atomic machine instruction
• resource availability - special registers or other constraints
• optimization level, and other options that affect data/code placement
Without knowledge of the architecture, it is reasonable to assume that the general
expression requires two reads, one for each operand and one write to store the result.
Several difficulties may arise in the presence of interrupt sequences, depending on the
particular application.
Interrupts
2012 Microchip Technology Inc. DS52071B-page 183
11.8.1.1 DEVELOPMENT ISSUES
Here are some examples of the issues that should be considered:
EXAMP LE 11-1 : bar MUST MATCH baz
When it is required that bar and baz match (i.e., are updated synchronously with each
other), there is a possible hazard if either bar or baz can be updated within a higher
priority interrupt expression. Here are some sample flow sequences:
1. Safe:
read bar
read baz
perform operation
write back result to foo
2. Unsafe:
read bar
interrupt modifies baz
read baz
perform operation
write back result to foo
3. Safe:
read bar
read baz
interrupt modifies bar or baz
perform operation
write back result to foo
The first is safe because any interrupt falls outside the boundaries of the expression.
The second is unsafe because the application demands that bar and baz be updated
synchronously with each other . The third is probably safe; foo will possibly have an old
value, but the value will be consistent with the data that was available at the start of the
expression.
EXAMPL E 11-2: TYP E OF foo, bar AND baz
Another variation depends upon the type of foo, bar and baz. The operations, “read
bar”, “read baz”, or “write back result to foo”, may not be atomic, depending upon the
architecture of the target processor . For example, dsPIC DSC devices can read or write
an 8-bit, 16-bit, or 32-bit quantity in 1 (atomic) instruction. But, a 32-bit quantity may
require two instructions depending upon instruction selection (which in turn will depend
upon optimization and memory model settings). Assume that the types are long and
the compiler is unable to choose atomic operations for accessing the data. Then the
access becomes:
read lsw bar
read msw bar
read lsw baz
read msw baz
perform operation (on lsw and on msw)
perform operation
write back lsw result to foo
write back msw result to foo
Now there are more possibiliti es for an update of bar or baz to cause unexpected data.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 184 2012 Microchip Technology Inc.
EXAMPLE 11 -3: BIT FIELDS
A th ird cau se for concer n are bi t fiel ds. C a llows m emory to be al locat ed at th e bit l evel,
but does not define any bit operations. In the purest sense, any operation on a bit will
be treated as an operation on the underlying type of the bit field and will usually require
some operations to extract the field from bar and baz or to insert the field into foo.
The important consideration to note is that (again depending upon instruction architec-
ture, optimization levels and memory settings) an interrupted routine that writes to any
portion of the bit field where foo resides ma y be cor rupt ibl e. Thi s is par ticu larl y app a r-
ent in the case where one of the operands is also the destination.
The dsPIC DSC instruction set can operate on 1 bit atomically. The compiler may select
these instructions depending upon optimization level, memory settings and resource
availability.
EXAMPLE 11-4: CACHED MEMORY VALUES IN REGISTERS
Finally, the compiler may choose to cache memory values in registers. These are often
referred to as register variables and are particularly prone to interrupt corruption, even
when an operation involving the variable is not being interrupted. Ensure that memory
resources shared between an ISR and an interruptible function are designated as
volatile. This will inform the compiler that the memory location may be updated
out-of-line from the serial code sequence. This will not protect against the effect of
non-atomic operations, but is never-the-less important.
11.8.1.2 DEVELOPMENT SOLUTIONS
Here are some strategies to remove potential hazards:
• Design the software system such that the conflicting event cannot occur. Do not
share memory between ISRs and other functions. Make ISRs as simple as
possible and move the real work to main code.
• Use care when sharing memory and, if possible, avoid sharing bit fields which
contain multiple bits.
• Protect non-atomic updates of shared memory from interrupts as you would
protect critical sections of code. The following macro can be used for this purpose:
#define INTERRUPT_PROTECT(x) { \
char saved_ipl; \
\
SET_AND_SAVE_CPU_IPL(saved_ipl,7); \
x; \
RESTORE_CPU_IPL(saved_ipl); } (void) 0;
This macro disables interrupts by increasing the current priority level to 7,
performing the desired statement and then restoring the previous priority level.
Interrupts
2012 Microchip Technology Inc. DS52071B-page 185
11.8.1.3 APPLICATION EXAMPLE
The following example highlights some of the points discussed in this section:
void __attribute__((interrupt))
HigherPriorityInterrupt(void) {
/* User Code Here */
LATGbits.LATG15 = 1; /* Set LATG bit 15 */
IPC0bits.INT0IP = 2; /* Set Interrupt 0
priority (multiple
bits involved) to 2 */
}
int main(void) {
/* More User Code */
LATGbits.LATG10 ^= 1; /* Potential HAZARD -
First reads LATG into a W reg,
implements XOR operation,
then writes result to LATG */
LATG = 0x1238; /* No problem, this is a write
only assignment operation */
LATGbits.LATG5 = 1; /* No problem likely,
this is an assignment of a
single bit and will use a single
instruction bit set operation */
LATGbits.LATG2 = 0; /* No problem likely,
single instruction bit clear
operation probably used */
LATG += 0x0001; /* Potential HAZARD -
First reads LATG into a W reg,
implements add operation,
then writes result to LATG */
IPC0bits.T1IP = 5; /* HAZARD -
Assigning a multiple bitfield
can generate a multiple
instruction sequence */
}
A statement can be protected from interrupt using the INTERRUPT_PROTECT macro
provided above. For this example:
INTERRUPT_PROTECT(LATGbits.LATG15 ^= 1); /* Not interruptible by
level 1-7 interrupt
requests and safe
at any optimization
level */
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 186 2012 Microchip Technology Inc.
11.8.2 PSV Usage with Interrupt Service Routines
The introduction of managed psv pointers and CodeGuard Security psv constant sec-
tions in compiler v3.0 means that ISRs cannot make any assumptions about the setting
of PSVPAG. This is a migration issue for existing applications with ISRs that reference
the auto_psv constants section. In previous versions of the compiler , the ISR could
assume that the correct value of PSVPAG was set during program startup (unless the
programmer had explicitly changed it.)
To help mitigate this problem, two new function attributes will be introduced: auto_psv
and no_auto_psv. If an ISR references const variables or string literals using the
constants-in-code memory model, the auto_psv attribute should be added to the
function definition. This attribute will cause the compiler to preserve the previous con-
tents of PSVPAG and set it to section .const. Upon exit, the previous value of
PSVPAG will be restored. For example:
void __attribute__((interrupt, auto_psv)) myISR()
{
/* This function can reference const variables and
string literals with the constants-in-code memory model. */
}
The no_auto_psv attribute is used to indicate that an ISR does not reference the
auto_psv constants section. If neither attribute is specified, the compiler assumes
auto_psv and inserts the necessary instructions to ensure correct operation at run
time. A warning diagnostic message is also issued that alerts the user to the migration
issue, and to the possibility of reducing interrupt latency by specifying the
no_auto_psv attribute.
11.8.3 Latency
There are two elements that affect the number of cycles between the time the interrupt
source occurs and the execution of the first instruction of your ISR code. These factors
are:
•Processor Servicing of Interrupt – the amount of time it takes the processor to
recognize the interrupt and branch to the first address of the interrupt vector. To
determine this value refer to the processor data sheet for the specific processor
and interrupt source being used.
•ISR Code – although an interrupt function may call other functions, whether they
be user-defined functions, library functions or implicitly called functions to imple-
ment a C operation, the compiler cannot know, in general, which resources are
used by the called function. As a result, the compiler will save all the working reg-
isters and RCOUNT, even if they are not all used explicitly in the ISR itself. The
increased latency associated with the call does not lend itself to fast response
times.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 187
Chapter 12. Main , Runtime Star tup and Re set
12.1 INTRODUCTION
When creating C code, there are elements that are required to ensure proper program
operation: a main function must be present; startup code to initialize and clear vari-
ables, to set up registers and the processor; and Reset conditions need to be handled.
The following topics are discussed in this section:
• T he m ai n Function
• Runtime Startup and Initialization
12.2 THE main FUNCTION
The identifier main is special. It is must be used as the name of a function that will be
the first function to execute in a program. Y ou must always have one and only one func-
tion called main() in your programs. Code associated with main(), however, is not
the first code to execute after Reset. Additional code provided by the compiler and
known as the runtime startup code is executed first and is responsible for transferring
control to the main() function.
The prototype that shoul d be used for main() is as follows.
int main(void);
12.3 RUNTIME STARTUP AND INITIALIZATION
A C program requires certain objects to be initialized and the processor to be in a
particular state before it can begin execution of its function main(). It is the job of the
runtime startup code to perform these tasks, specifically (and in no particular order):
• Initialization of global variables assigned a value when defined
• Initialization of the stack
• Clearing of non-initialized global variables
• General setup of registers or processor state
T wo C run- time sta rtup modu les are incl uded in the libpic30-omf.a archive/library .
The entry point for both startup modules is __reset. The linker scripts construct a
GOTO __reset instruction at location 0 in program memory, which transfers control
upon device Reset.
The primary startup module (crt0.o) is linked by default and performs the following:
1. The S tack Pointer (W15) and S tack Pointer Limit register (SPLIM) are initialized,
using values provided by the linker or a custom linker script. For more
information, see Section 4.4 “Stack”.
2. If a .const section is defined, it is mapped into the program space visibility
window by initializing the PSV page and CORCON registers, as appropriate, if
const-in-code memory mode is used or variables have been explicitly
allocated to space(auto_psv).
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 188 2012 Microchip Technology Inc.
3. The data initialization template is read, causing all uninitialized objects to be
cleared, and all initialized objects to be initialized with values read from program
memory. The data initialization template is created by the linker.
4. If the application has defined user_init functions (see
Section 10.2.2 “Function Attr ibutes”), these are invoked. The order of
execution depends on link order.
5. The function main() is called with no parameters.
6. If main() returns, the processor will reset.
The alternate startup module (crt1.o) is linked when the -Wl, --no-data-init
option is specified. It performs the same operations, except for step (3), which is
omitted. The alternate startup module is smaller than the primary module, and can be
selected to conserve program memory if data initialization is not required.
Source code (in dsPIC DSC assembly language) for both modules is provided in the
<xc16 install directory>\src directory . The startup modules may be modified
if necessary . For example, if an application requires main to be called with parameters,
a conditional assembly directive may be changed to provide this support.
Note: Persistent data is never cleared or initialized.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 189
Chapter 13. Mixing C and Assembly Code
13.1 INTRODUCTION
This section describes how to use assembly language and C modules together. It gives
examples of using C variables and functions in assembly code and examples of using
assembly language variables and functions in C.
Items discus se d are:
•Mixing Assembly Language and C Variables and Functions – separate
assembly language modules may be assembled, then linked with compiled C
modules.
•Using Inline Assembly Language – assembly language instructions may be
embedded directly into the C code. The inline assembler supports both simple
(non-parameterized) assembly language statement, as well as extended
(parameterized) statements (where C variables can be accessed as operands of
an assemb l er in str u cti on).
•Predefined Assembly Macros – a list of predefined assembly-code macros to be
used in C code is provided.
13.2 MIXING ASSEMB LY LANGUAGE AND C VARIABLES AND FUNCTIONS
The following guidelines indicate how to interface separate assembly language
modules with C modules.
• Follow the register conventions described in 9.2 “Register Variables”. In particu-
lar, registers W0-W7 are used for parameter passing. An assembly language
function will receive parameters, and should pass arguments to called functions,
in these registers.
• Functions not called during interrupt handling must preserve registers W8-W15.
That is, the values in these registers must be saved before they are modified and
restored before returning to the calling function. Registers W0-W7 may be used
without restoring their values.
• Interrupt functions must preserve all registers. Unlike a normal function call, an
interrupt may occur at any point during the execution of a program. When return-
ing to the normal program, all registers must be as they were before the interrupt
occurred.
• Variables or functions declared within a separate assembly file that will be
referenced by any C source file should be declared as global using the assembler
directive.global. External symbols should be preceded by at least one
underscore. The C function main is named _main in assembly and conversely an
assembly symbol _do_something will be referenced in C as do_something.
Undeclared symbols used in assembly files will be treated as externally defined.
The following example shows how to use variables and functions in both assembly
language and C regardless of where they were originally defined.
The file ex1.c defines foo and cVariable to be used in the assembly language file.
The C file also shows how to call an assembly function, asmFunction, and how to
access the assembly defined variable, asmVariable.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 190 2012 Microchip Technology Inc.
Example s in thi s Sec tio n:
• Mixing C and Assembly
• Calling an Assembly Function in C
EXAMPLE 13-1: MIXING C AND ASSEMBLY
/*
** file: ex1.c
*/
extern unsigned int asmVariable;
extern void asmFunction(void);
unsigned int cVariable;
void foo(void)
{
asmFunction();
asmVariable = 0x1234;
}
The file ex2.s defines asmFunction and asmVariable as required for use in a
linked application. The assembly file also shows how to call a C function, foo, and how
to access a C defined variable, cVariable.
;
; file: ex2.s
;
.text
.global _asmFunction
_asmFunction:
mov #0,w0
mov w0,_cVariable
return
.global _main
_main:
call _foo
return
.bss
.global _asmVariable
.align 2
_asmVariable: .space 2
.end
In the C file, ex1.c, external references to symbols declared in an assembly file are
declared usi ng the standar d extern keyword; note that asmFunction, or
_asmFunction in the assembl y sou rce, is a void function and is declared
accordingly.
In the assembly file, ex1.s, the symbols _asmFunction, _main and _asmVariable
are made globally visible through the use of the .global assembler directive and can
be accessed by any other source file. The symbol _main is only referenced and not
declared; therefore, the assembler takes this to be an external reference.
The following compiler example shows how to call an assembly function with two
parameters. The C function main in call1.c calls the asmFunction in call2.s
with two parameters.
Mixing C and Assembly Code
2012 Microchip Technology Inc. DS52071B-page 191
EXAMPLE 13-2: CALLING AN ASSEMBLY FUNCTION IN C
/*
** file: call1.c
*/
extern int asmFunction(int, int);
int x;
void
main(void)
{
x = asmFunction(0x100, 0x200);
}
The assembly-language function sums its two parameters and returns the result.
;
; file: call2.s
;
.global _asmFunction
_asmFunction:
add w0,w1,w0
return
.end
Parameter passing in C is detailed in Section 10.8.2 “Return V alue”. In the preceding
example, the two integer arguments are passed in the W0 and W1 registers. The
integer return result is transferred via register W0. More complicated parameter lists
may require different registers and care should be taken in the hand-written assembly
to follow the guidelines.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 192 2012 Microchip Technology Inc.
13.3 USING INLINE ASSEMBLY LANGUAGE
Within a C function, the asm statement may be used to insert a line of assembly
language code into the assembly language that the compiler generates. Inline
assembly has two forms: simple and extended.
In the simple form, the assembler instruction is written using the syntax:
asm ("instruction");
where instruction is a valid assembly-language construct. If you are writing inline
assembly in ANSI C programs, write __asm__ instead of asm.
In an extended assembler instruction using asm, the operands of the instruction are
specified using C expressions. The extended syntax is:
asm("template" [ : [ "constraint"(output-operand) [ , ... ] ]
[ : [ "constraint"(input-operand) [ , ... ] ]
[ "clobber" [ , ... ] ]
]
]);
You must specify an assembler instruction template, plus an operand constraint
string for each operand. The template specifies the instruction mnemonic, and
optionally placeholders for the operands. The constraint strings specify operand
constraints, for example, that an operand must be in a register (the usual case), or that
an operand must be an immediate value.
Constraint letters and modifiers supported by the compiler are listed in Table 13-1 and
Table respectively.
TABLE 13-1: CONSTRAINT LETTERS SUPPORTED BY THE COMPILER
Note: Only a single string can be passed to the simple form of inline
assembly.
Letter Constraint
aClaims WREG
bDivide support register W1
cMultiply support register W2
dGeneral purp os e dat a regi st ers W1-W14
eNon-divide support registers W2-W14
gAny register, memory or immediate integer operand is allowed, except for
registers that are not general registers.
iAn immediate integer operand (one with constant value) is allowed. This
incl ude s sy mb olic co nstants w hos e val ue s w i ll be known only at as sembly ti me .
rA register operand is allowed provided that it is in a general register.
vAWB register W13
wAccumulator register A-B
xx prefetch registers W8-W9
yy prefetch registers W10-W11
zMAC prefetch registers W4-W7
0, 1, … ,
9An operand that matches the specified operand number is allowed. If a digit is
used together with letters within the same alternative, the digit should come
last.
By default, %n represents the first register for the operand (n). To ac cess the
second, third, or fourth register, use a modifier letter.
TA near or far data operand.
UA near data operand.
Mixing C and Assembly Code
2012 Microchip Technology Inc. DS52071B-page 193
TABLE 13-2: CONSTRAINT MODIFIERS SUPPORTED BY THE COMPILER
Exam pl es in thi s Section:
• Passing C Variables
• Clobbering Registers
• Using Multiple Assembler Instructions
• Using ‘&’ to Prevent Input Register Clobbering
• Matching Operands
• Naming Operands
• V olatile asm Statements
• Using Required Registers
• Handling Values Larger Than int
EXAMPLE 13-3: PASSING C VARIABLES
This example demonstrates how to use the swap instruction (which the compiler does
not generally use):
asm ("swap %0" : "+r"(var));
Here var is the C expression for the operand, which is both an input and an output
operand. The operand is constrained to be of type r, which denotes a register operand.
The + in +r indicates that the operand is both an input and output operand.
Each operand is described by an operand-constraint string that is followed by the C
expression in parentheses. A colon separates the assembler template from the first
output operand, and another separates the last output operand from the first input, if
any. Commas separate output operands and separate inputs.
If there are no output operands, but there are input operands; then, there must be two
consecutive colons surrounding the place where the output operands would go. The
compiler requires that the output operand expressions must be L-values. The input
operands need not be L-values. The compiler cannot check whether the operands
have data types that are reasonable for the instruction being executed. It does not
parse the assembler instruction template and does not know what it means, or whether
it is valid assembler input. The extended asm feature is most often used for machine
instructions that the compiler itself does not know exist. If the output expression cannot
be directly addressed (for example, it is a bit field), the constraint must allow a register .
In that case, the compiler will use the register as the output of the asm, and then store
that register into the output. If output operands are write-only , the compiler will assume
that the values in these operands before the instruction are dead and need not be
generated.
Modifier Constraint
=Means that this operand is write-only for this instruction: the previous value is dis-
carded and replaced by output data.
+Means that this operand is both read and written by the instruction.
&Means that this operand is an earlyclobber operand, which is modified before
the instruction is finished using the input operands. Therefore, this operand may
not lie in a register that is used as an input operand or as part of any memory
address.
dSecond register for operand number n, i.e., %dn..
qFourth register for operand number n, i.e., %qn..
tThird register for operand number n, i.e., %tn..
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 194 2012 Microchip Technology Inc.
EXAMPLE 13- 4: CLO BBERING REGISTERS
Some instructions clobber specific hard registers. To describe this, write a third colon
after the input operands, followed by the names of the clobbered hard registers (given
as strings separated by commas). Here is an example:
asm volatile ("mul.b %0"
: /* no outputs */
: "U" (nvar)
: "w2");
In this case, the operand nvar is a character variable declared in near data space, as
specified by the “U” constraint. If the assembler instruction can alter the flags (condition
code) register, add “cc” to the list of clobbered registers. If the assembler instruction
modifies memory in an unpredictable fashion, add “memory” to the list of clobbered
registers. This will cause the compiler to not keep memory values cached in registers
across the assembler instruction.
EXAMPLE 13-5: USING MULTIPLE ASSEMBLER INSTRUCTIONS
You can put multiple assembler instructions together in a single asm templat e,
separa ted with newlines (written as \n). The input operands and the output operands’
addresses are ensured not to use any of the clobbered registers, so you can read and
write the clobbered registers as many times as you like. Here is an example of multiple
instructions in a template; it assumes that the subroutine _foo accepts argum ents in
registers W0 and W1:
asm ("mov %0,w0\nmov %1,W1\ncall _foo"
: /* no outputs */
: "g" (a), "g" (b)
: "W0", "W1");
In this example, the constraint strings “g” indicate a general operand.
EXAMPLE 13-6: USING ‘&’ TO PREVENT INPUT REGISTER CLOBBERING
Unless an output operand has the & constraint modifier , the compiler may allocate it in
the same register as an unrelated input operand, on the assumption that the inputs are
consumed before the outputs are produced. This assumption may be false if the
assembler code actually consists of more than one instruction. In such a case, use &
for each output operand that may not overlap an input operand. For example, consider
the following function:
int
exprbad(int a, int b)
{
int c;
__asm__("add %1,%2,%0\n sl %0,%1,%0"
: "=r"(c) : "r"(a), "r"(b));
return(c);
}
The intention is to compute the value (a + b) << a. However, as written, the value
computed may or may not be this value. The correct coding informs the compiler that
the operand c is modified before the asm instruction is finished using the input
operands, as follows:
int
exprgood(int a, int b)
{
int c;
Mixing C and Assembly Code
2012 Microchip Technology Inc. DS52071B-page 195
__asm__("add %1,%2,%0\n sl %0,%1,%0"
: "=&r"(c) : "r"(a), "r"(b));
return(c);
}
EXAMPLE 13-7: MATCH ING OPERANDS
When the assembler instruction has a read-write operand, or an operand in which only
some of the bits are to be changed, you must logically split its function into two separate
operands: one input operand and one write-only output operand. The connection
between them is expressed by constraints that say they need to be in the same location
when the instruction executes. You can use the same C expression for both operands
or different expressions. For example, here is the add instruction with bar as its
read-only source operand and foo as its read-write destination:
asm ("add %2,%1,%0"
: "=r" (foo)
: "0" (foo), "r" (bar));
The constraint “0” for operand 1 says that it must occupy the same location as operand
0. A digit in constraint is allowed only in an input operand and must refer to an output
operand. Only a digit in the constraint can ensure that one operand will be in the same
place as another. The mere fact that foo is the value of both operands is not enough
to ensure that they will be in the same place in the generated assembler code. The
following would not work:
asm ("add %2,%1,%0"
: "=r" (foo)
: "r" (foo), "r" (bar));
Various optimizations or reloading could cause operands 0 and 1 to be in different
registers. For example, the compiler might find a copy of the value of foo in one
register and use it for operand 1, but generate the output operand 0 in a different
register (copying it afterward to foo’s own address).
EXAMPLE 13-8: NAMI NG OPERANDS
It is also possible to specify input and output operands using symbolic names that can
be referenced within the assembler code template. These names are specified inside
square brackets preceding the constraint string, and can be referenced inside the
assembler code template using %[name] instead of a percentage sign followed by the
operand number. Using named operands, the above example could be coded as
follows:
asm ("add %[foo],%[bar],%[foo]"
: [foo] "=r" (foo)
: "0" (foo), [bar] "r" (bar));
EXAMPLE 13-9: VOLATILE ASM STATEMENTS
You can prevent an asm instruction from being deleted, moved significantly, or
combined, by writing the keyword volatile after the asm. For example:
#define disi(n) \
asm volatile ("disi #%0" \
: /* no outputs */ \
: "i" (n))
In this case, the constraint letter “i” denotes an immediate operand, as required by the
disi instruction.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 196 2012 Microchip Technology Inc.
EXAMPLE 13-10 : USING REQUIRED REGIS TERS
Some instructions in the dsPIC DSC instruction set require operands to be in a partic-
ular register or groups of registers. Table 13-1 lists some constraint letters that may be
appropriate to satisfy the constraints of the instruction that you wish to generate.
If the constraints are not sufficient or you wish to nominate particular registers for use
inside asm statements, you may use the register-nominating extensions provided by
the compiler to support you (and reduce the need to mark registers as clobbered) as
the following code snippet shows. This snippet uses a fictitious instruction that has
some odd registe r requi re men ts:
{ volatile register int in1 asm("w7");
volatile register int in2 asm("w9");
volatile register int out1 asm("w13");
volatile register int out2 asm("w0");
in1 = some_input1;
in2 = some_input2;
__asm__ volatile ("funky_instruction %2,%3,%0; = %1" :
/* outputs */ "=r"(out1), "=r"(out2) :
/* inputs */ "r"(in1), "r"(in2));
/* use out1 and out2 in normal C */
}
In this example, funky_instruction has one explicit output, out1, and one implicit
output, out2. Both have been placed in the asm template so that the compiler can
track the register usage properly (though the implicit output is in a comment statement).
The input shown is normal. Otherwise, the extended register declarator syntax is used
to nominate particular hard registers which satisfy the constraints of our fictitious
funky_instruction.
EXAMPLE 13-11: HANDLING VALUES LARGER THAN INT
Constraint letters and modifiers may be used to identify various entities with which it is
acceptable to replace a particular operand, such as %0 in:
asm("mov %1, %0" : "r"(foo) : "r"(bar));
This example indicates that the value stored in foo should be moved into bar. The
example code performs this task unless foo or bar are larger than an int.
By default, %0 represents the first register for the operand (0). To access the second,
third, or fourth register, use a modifier letter specified in Table .
13.4 PREDEFINED ASSEMBLY MACROS
Some macros used to insert assembly code in C are defined once you include <xc.h>.
The macros are: Nop(), ClrWdt(), Sleep() and Idle(). The latter two insert the
PWRSAV instructi on with an argument of #0 and #1, re spec tiv ely.
Note: It is recommended to use constraint letters rather than fixed register assign-
ments.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 197
Chapter 14. Library Routines
Many library functions or routines (and any associated variables) will be automatically
linked into a program once they have been referenced in your source code. The use of
a function from one library file will not include any other functions from that library. Only
used library functions will be linked into the program output and consume memory.
Library and precompiled object files are stored in the compiler’s installation directory
structure.
Your program will require declarations for any functions or symbols used from libraries.
These are contained in the standard C header (.h) files. Header files are not library
files and the two files types should not be confused. Library files contain precompiled
code, typically functions and variable definitions; the header files provide declarations
(as opposed to definitions) for functions, variables and types in the library files, as well
as other preprocessor macros.
The include directories, under the compiler’s installation directory, are where the
compiler stores the standard C library system header files. The installation will
automatically locate its bundled include files.
Some libraries require manual inclusion in your project, or require special options to
use. See the 16-Bit Language T ools Libraries (DS51456) for questions about particular
libraries.
Libraries which are found automatically include:
• Standard C library
• dsPIC30 support libraries
• Standard IEEE floating point library
• Device per ip her al libr ary
EXAMPLE 14-1: US ING THE MATH LIBRARY
#include <math.h> // declare function prototype for sqrt
void main(void)
{
double i;
// sqrt referenced; sqrt will be linked in from library file
i = sqrt(23.5);
}
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 198 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 199
Chapter 15. Optimizations
15.1 INTRODUCTION
Different MPLAB XC16 C Compiler editions support different levels of optimization.
Some editions are free to download and others must be purchased.
The compiler is available in the the following editions:
Setting Optimization Levels
Different optimizations may be set ranging from no optimization to full optimization,
depending on your compiler edition. When debugging code, you may prefer not to
optimize your code to ensure expected program flow.
For details on compiler options used to set optimizations, see Section 3.7.6 “Options
for Controlling Optimization”.
Edition Cost Description
Professional (PR O) Yes Implemented with the highest optimizations and
performan ce lev el s.
Standard (STD) Yes Implemented with ample optimizations levels and high per-
formance levels.
Free No Implemented with the most restrictions on code
optimizations.
Evaluation (EV AL) No PRO edition enabled for 60 days; afterward reverts to Free
edition.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 200 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 201
Chapter 16. Preprocessing
16.1 INTRODUCTION
All C source files are preprocessed before compilation. The -E option can be used to
preprocess and then stop the compilation. See Section 3.7.2 “Options for
Controlling the Kind of Output”.
Assembler files can also be preprocessed if the file extension is .S rather than .s (see
Section 3.2.3 “Input File Types” .)
Items discussed in this section are:
• C Language Comments
• Preproces sing Directives
• Predefined Macro Names
• Pragmas vs. Attributes
16.2 C LANGUAGE COMMENTS
The MPLAB XC16 C Compiler supports standard C comments, as well as C++ style
comments. Both types are illustrated in the following table.
16.3 PREPROCESSING DIRECTIVES
The compiler accepts several specialized preprocessor directives in addition to the
standard directives. All of these are listed in Table 16-1.
Comment Syntax Description Example
/* */ St a ndard C code comm ent.
Used for one or more lines. /* This is line 1
This is line 2 */
// C++ code comment. Used for
one line only. // This is line 1
// This is line 2
TABLE 16-1: PREPROCESSOR DIRECTIVES
Directive Meaning Example
#define Defi ne prep roc es so r macro #define SIZE 5
#define FLAG
#define add(a,b) ((a)+(b))
#elif Short for #else #if see #ifdef
#else Conditionally include source lines see #if
#endif Termin ate conditional source inclus ion see #if
#error Generate an error message #error Size too big
#if Include source lines if constant
expression true #if SIZE < 10
c = process(10)
#else
skip();
#endif
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 202 2012 Microchip Technology Inc.
Macro expansion using arguments can use the # character to convert an argument to
a string, and the ## sequence to concatenate arguments. If two expressions are being
concatenated, consider using two macros in case either expression requires substitu-
tion itself, so for example
#define paste1(a,b) a##b
#define paste(a,b) paste1(a,b)
lets you use the paste macro to concatenate two expressions that themselves may
require further expansion. Remember that once a macro identifier has been expanded,
it will not be expanded again if it appears after concatenation.
For implementation-defined behavior of preprocessing directives, see
Section A.14 “Preprocessing Directives”.
16.4 PREDEF INED MACRO NAMES
The compiler predefines several macros which can be tested by conditional directives
in source code. Constants that have been deprecated may be found in Appendix
E. “Deprecated Features”.
16.4.1 Compiler Versi on Ma cro
The compiler will define the constant __XC16_VERSION__ , giving a numeric va lue to
the version identifier. This can be used to take advantage of new compiler features
while remaining backwardly compatible with older versions.
The value is based upon the major and minor version numbers of the current release.
For example, release version 1.00 will have a __XC16_VERSION__ definition of 1000.
This macro can be used, in conjunction with standard preprocessor comparison state-
ments, to conditionally include/exclude various cod e cons tructs.
The current definition of __XC16_VERSION__ can be discovered by adding
--version to the command line, or by inspecting the README.html file that came
with the release.
#ifdef Include source lines if preprocessor
symbol defined #ifdef FLAG
do_loop();
#elif SIZE == 5
skip_loop();
#endif
#ifndef Include source lines if preprocessor
symbol not defined #ifndef FLAG
jump();
#endif
#include Inclu de tex t file into sourc e #include <stdio.h>
#include "project.h"
#line Specify line number and file name for
listing #line 3 final
#pragma Compiler specific options Refer to Section 16.5 “Pragmas vs.
Attributes”
#undef Undefines preproce ssor symbol #undef FLAG
#warning Generate a warning message #warning Length not set
TABLE 16-1: PREPROCESSOR DIRECTIVES (CONTINUED)
Directive Meaning Example
Preprocessing
2012 Microchip Technology Inc. DS52071B-page 203
16.4.2 Output Types Macros
The following symbols define the output type produced by the compiler.
16.4.3 Target Device Macros
The following symbols define the device family being targeted during the build.
In addition, the compiler defines a symbol based on the target device set with -mcpu=.
For example, -mcpu=30F6014, which defines the symbol __dsPIC30F6014__.
16.4.4 Device Features Macros
The following symbols are defined if device features are enabled.
TABLE 16-2: OUTPUT TYPES MACROS
New Symbol Old Symbol Description Defined with -ansi
command-line option?
XC16 C30 If defined, 16-bit
compiler is in use. No
__XC16 __C30 Yes
__XC16__ __C30__ Yes
XC16ELF C30ELF If defined, compiler
is producing ELF
output.
No
__XC16ELF __C30ELF Yes
__XC16ELF__ __C30ELF__ Yes
XC16COFF C30COFF If defined, compiler
is producing COFF
output.
No
__XC16COFF __C30COFF Yes
__XC16COFF__ __C30COFF__ Yes
TABLE 16-3: TARGET DEVICE FAMILY MACROS/SYMBOLS
Symbol Description
__dsPIC30F__ dsPIC30F target device family.
__dsPIC33E__ dsPIC3 3E target device family.
__dsPIC33F__ dsPIC33F target device family.
__PIC24E__ PIC24E target device family.
__PIC24F__ PIC24FJ target device family.
__PIC24FK__ PIC24FK target device family.
__PIC24H__ PIC24H target device family.
TABLE 16-4: DEVICE FEATURES MACROS/SYMBOLS
Symbol Description
__HAS_DSP__ Device has a DSP engine.
__HAS_EEDATA__ Device has EEDATA memory.
__HAS_DMA__ Device has DMA memory.
__HAS_DMA_DMAV2__ Device has DMA V2 memory.
__HAS_CODEGUARD__ Device has CodeGuard™ Security.
__HAS_PMP__ Device has Parallel Master Port.
__HAS_PMPV2__ Device has Parallel Master Port V2.
__HAS_PMP_ENHANCED__ Device has Enhanced Parallel Master Port.
__HAS_EDS__ Device has Extended Data Space.
__HAS_5VOLTS__ Device is a 5-volt device.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 204 2012 Microchip Technology Inc.
16.4.5 Other Macros
The following symbols define other features.
TABLE 16-5: OTHER MACROS/SYMBOLS
Symbol Description
__FILE__ Current file name as a C string.
__LINE__ Current line number as a C string.
__DATE__ Curr ent date as a C string.
Preprocessing
2012 Microchip Technology Inc. DS52071B-page 205
16.5 PRAGMAS VS. ATTRIBUTES
The MPLAB XC16 C Compiler uses non-ANSI attributes instead of pragmas or qualifi-
ers to locate variables and functions in memory. As a comparison, the PIC18 MCU C
Compiler - also called MPLAB C18 - uses pragmas for sections (code, romdata,
udata, idata), interrupts (high-priority and low-priority) and variable locations (bank,
section). The former HI-TECH C Compiler for PIC18 MCUs and the newer MPLAB XC8
compiler use qualifiers or pragmas to perform the same actions.
If you are used to using a PIC18 compiler , this section will show how to use XC16 attri-
butes inste ad. For more on attr ibu tes , see Section 6.11 “Variable Attributes” and
Section 10.2.1 “Function Specifiers”.
TABLE 16-6: C18 PRAGMAS VS. ATTRIBUTES
TABLE 16-7: PICC18 PRAGMAS AND QUALIFIERS VS. ATTRIBUTES
EXAMPLE 16-1: SPECIFY AN UNINITIALIZED VARIABLE IN A USER SECTION
IN DATA MEMORY
where oldbss is the name of the psect (section) in which the variable would normally
be placed.
EXAMPL E 16-2: LO CATE THE VARIABLE MABONGA AT ADDRESS 0X100 IN
DATA MEMORY
Pragma (MPLAB C18) Attribute (MPLAB XC16)
#pragma udata [name]__attribute__ ((section ("name")))
#pragma idata [name]__attribute__ ((section ("name")))
#pragma romdata [name]__attribute__ ((space (auto_psv)))
#pragma code [name]__attribute__ ((section ("name"),
space (prog)))
#pragma interruptlow __attribute__ ((interrupt))
#pragma interrupt __attribute__ ((interrupt, shadow))
#pragma varlocate bank NA*
#pragma varlocate name NA*
*16-bit devices do not have banks.
PICC18 Attribute (MPLAB XC16)
#pragma psect old=new __attribute__ ((section ("name")))
const const or
__attribute__ ((space (auto_psv)))
interrupt low_priority __attribute__ ((interrupt))
interrupt __attribute__ ((interrupt, shadow))
PICC18 #pragma psect oldbss=mybss
int gi;
C18 #pragma udata mybss
int gi;
XC16 int __attribute__((__section__(".mybss"))) gi;
PICC18 int Mabonga @ 0x100;
C18 #pragma idata myDataSection=0x100;
int Mabonga = 1;
XC16 int __attribute__((address(0x100))) Mabonga = 1;
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 206 2012 Microchip Technology Inc.
EXAMPLE 16-3: SPECIFY A VARIABLE TO BE PLACED IN PROGRAM
MEMORY
EXAMPLE 16-4: LO CATE THE FUNCTION PRINTSTRING AT ADDRESS
0X8000 IN PROGRAM MEMORY
EXAMPL E 16-5: COMP IL ER AUTOMATICALLY SAVES AND RESTORES THE
VARIABLES VAR1 AND VAR2
PICC18 const char my_const_array[10] = {0,1,2,3,4,5,6,7,8,9};
C18 #pragma romdata const_table
const rom char my_const_array[10] =
{0,1,2,3,4,5,6,7,8,9};
XC16 const or
__attribute__((space(auto_psv)))
char my_const_array[10] = {0,1,2,3,4,5,6,7,8,9};
PICC18 int PrintString(const char *s)@ 0x8000 {...}
C18 #pragma code myTextSection=0x8000;
int PrintString(const char *s){...}
XC16 int __attribute__((address(0x8000))) PrintString
(const char *s) {...}
PICC18 No equivalent
C18 #pragma interrupt isr0 save=var1, var2
void isr0(void)
{
/* perform interrupt function here */
}
XC16 void __attribute__((__interrupt__(__save__(var1,var2))))
isr0(void)
{
/* perform interrupt function here */
}
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 207
Chapter 17. Linking Programs
17.1 INTRODUCTION
The compiler will automatically invoke the linker unless the compiler has been
requested to stop after producing an intermediate file.
The linker will run with options that are obtained from the command-line driver . These
options specify the memory of the device and how objects should be placed in the
memory. Device-specific linker scripts are used.
The linker operation can be controlled using the driver, see Section 3.7.9 “Options for
Linking” for more information.
The linker creates a map file which details the memory assigned and some objects
within the code. The map file is the best place to look for memory information. See
MPLAB Assembler , Linker and Utilities for PIC24 MCUs and dsPIC DSCs User’s Guide
(DS51317) for an explanation of the detailed information in this file.
• Default Memory Spaces
• Replacing Library Symbols
• Linker-De fin ed Sy mbo ls
• Default Linker Script
17.2 DEFAULT MEMORY SPACES
The compiler defines several special purpose memory spaces to match architectural
features of 16-bit devices. S tatic and external variables may be allocated in the special
purpose memory spaces through use of the space attribute, described in
Section 6.11 “Variable Attributes”.
data
General data space. Variables in general data space can be accessed using ordinary
C statements. This is the default allocation.
xmemory - dsPIC30F, dsPIC33EP/F devices only
X data address space. Variables in X data space can be accessed using ordinary C
statements. X data address space has special relevance for DSP-oriented libraries
and/or assembly language instructions.
ymemory - dsPIC30F, dsPIC33EP/F devices only
Y data address space. Variables in Y data space can be accessed using ordinary C
statements. Y data address space has special relevance for DSP-oriented libraries
and/or assembly language instructions.
DD
DD
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 208 2012 Microchip Technology Inc.
prog
General progra m sp ace, which is normally reserved for executable code. Variables in
this program space can not be accessed using ordinary C statements. They must be
explicitly accessed by the programmer, usually using table-access inline assembly
instructions, using the program space visibility window, or by qualifying with
__prog__.
auto_psv
A compiler-managed area in program space, designated for program space visibility
window access. Variables in this space can be read (but not written) using ordinary C
statements and are subject to a maximum of 32K total space allocated.
psv
Program space, designated for program space visibility window access. Variables in
PSV space are not managed by the compiler and can not be accessed using ordinary
C statements. They must be explicitly accessed by the programmer, usually using
table-access inline assembly instructions, or using the program space visibility window.
V ariables in PSV space can be accessed using a single setting of the PSVP AG register
or by qualifying with __psv__.
eedata - EEDATA capable devices only
Data EEPROM space, a region of 16-bit wide non-volatile memory located at high
addresses in program memory. Variables in eedata space can not be accessed using
ordinary C statements. They must be explicitly accessed by the programmer, usually
using table-access inline assembly instructions, or using the program space visibility
window . The __HAS_EEDATA__ manifest constant is defined for devices that support
EEDATA.
dma - DMS capable devices only
DMA memory. Variables in DMA memory can be accessed using ordinary C statements
and by the DMA peripheral. The __HAS_DMA__ manifest constant is defined for
devices that support DMA.
DD
DD
Linking Programs
2012 Microchip Technology Inc. DS52071B-page 209
17.3 REPLACING LIBRA RY SYMBOLS
The MPLAB XC16 C Compiler comes with a librarian which allows you to unpack a
library file and replace modules with your own modified versions. See the MPLAB
Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs User’s Guide
(DS51317). However, you can easily replace a library module that is linked into your
program without having to do this.
If you add to your project a source file which contains the definition for a routine with
the same name as a library routine, then the library routine will be replaced by your rou-
tine.
When trying to resolve a symbol (a function name, or variable name, for example) the
compiler first scans all the source modules for the definition. Only if it cannot resolve
the symbol in these files does it then search the library files.
If the symbol is defined in a source file, the compiler will never actually search the librar-
ies for this symbol and no error will result even if the symbol was present in 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.
Another method is to use the weak attribute when declaring a symbol. A weak symbol
may be superseded by a global definition. When weak is applied to a reference to an
external symbol, the symbol is not required for linking.
The weak attribute may be applied to functions as well as variables. Code may be writ-
ten such that the function will be used only if it is linked in from some other module.
Deciding whether or not to use the feature becomes a link-time decision, not a compile
time deci sion.
For more information on the weak attribute, see Section 6.11 “Variable Attributes”.
17.4 LINKER-DEFINED SY MBOLS
The 16-bit linker defines several symbols that may be used in your C code develop-
ment. Please see the MPLAB Assembler, Linker and Utilities for PIC24 MCUs and
dsPIC DSCs User’s Guide (DS51317) for more information.
A useful address symbol, _PROGRAM_END, is def i ne d in program me mo ry to m ar k t he
highest address used by a CODE or PSV section. It should be referenced with the
address operator (&) in a built-in function call that accepts the address of an object in
program memory. This symbol can be used by applications as an end point for check-
sum calculati ons.
For example:
unsigned int end_page, end_offset;
_prog_addressT big_addr;
end_page = __builtin_tblpage(&_PROGRAM_END);
end_offset = __builtin_tbloffset(&_PROGRAM_END);
_init_prog_address(big_addr, _PROGRAM_END);
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 210 2012 Microchip Technology Inc.
17.5 DEFAULT LINKER SCRIPT
The command line always requires a linker script. However, if no linker script is
specified in an MPLAB IDE project, the IDE will use the device linker script file
(device.gld) included with the compiler as the default linker script. This
device-specific file contains information such as:
• Memory region definitions
• Program, data and debug sections mapping
• Interrupt and alternate interrupt vector table maps
• SF R equa tes
• Base addresses for various peripherals
Linker scripts may be found, by default, in:
<install-dir>\support\DeviceFamily\gld
where DeviceFamily is the 16-bit device family, such as dsPIC30F.
To use a custom linker script in your project, simply add that file to the command line
or the project in the “Linker Script” (MPLAB IDE v8) or “Linker Files” (MPLAB X IDE)
folder.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 211
Appe ndix A. Imple mentation-Defined Behavior
A.1 INTRODUCTION
This section offers implementation-defined behavior of the MPLAB XC16 C Compiler.
The ISO standard for C requires that vendors document the specifics of
“implementation defined” features of the language.
Items discus se d are:
• Translation
• Environment
• Identifiers
•Characters
• Integers
• Floating Point
• Arrays and Pointers
•Registers
• S tructures, Unions, Enumerations and Bit Fields
• Qualifiers
•Declarators
• Statements
• Preproces sing Directives
• Library Functions
• Signals
• Streams and Files
•tmpfile
• errno
•Memory
• abort
•exit
• getenv
• system
•strerror
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 212 2012 Microchip Technology Inc.
A.2 TRANSLATION
Implementation-Defined Behavior for Translation is covered in section G.3.1 of the
ANSI C Standard.
Is each non-empty sequence of white-space characters, other than new line, retained
or is it replaced by one space character? (ISO 5.1.1.2)
It is replaced by one space character.
How is a diagnostic message identified? (ISO 5.1.1.3)
Diagnostic messages are identified by prefixing them with the source file name and line
number corresponding to the message, separated by colon characters (‘:’).
Are there different classes of message? (ISO 5.1.1.3)
Yes.
If yes, what are they? (ISO 5.1.1.3)
Errors, which inhibit production of an output file, and warnings, which do not inhibit
production of an outp ut file.
What is the transla tor return stat us code for each cl as s of message? (ISO 5.1.1.3 )
The return status code for errors is 1; for warnings it is 0.
Can a level of diagnostic be controlled? (ISO 5.1.1.3)
Yes.
If yes, what form does the control take? (ISO 5.1.1.3)
Compiler command line options may be used to request or inhibit the generation of
warning mess ages .
A.3 ENVIRONMENT
Implementation-Defined Behavior for Environment is covered in section G.3.2 of the
ANSI C Standard.
What library facilities are available to a freestanding program? (ISO 5.1.2.1)
All of the facilities of the standard C library are available, provided that a small set of
functions is customized for the environment, as described in the “Run Time Libraries”
section.
Describe program termination in a freestanding environment. (ISO 5.1.2.1)
If the function main returns or the function exit is called, a HALT instruction is executed
in an infinite loop. This behavior is customizable.
Describe the arguments (parameters) passed to the function main? (ISO 5.1.2.2.1)
No parameters are passed to main.
Which of the following is a valid interactive device: (ISO 5.1.2.3)
Asynchronous terminal No
Paired display and keyboard No
Inter program connection No
Other, please describe? None
Implementation-Defined Behavior
2012 Microchip Technology Inc. DS52071B-page 213
A.4 IDENTIFIERS
Implementation-Defined Behavior for Identifiers is covered in section G .3.3 of the ANSI
C Standard.
How many characters beyond thirty-one (31) are significant in an identifier without
external linkage? (ISO 6.1.2)
All characters are significant.
How many characters beyond six (6) are significant in an identifier with external
linkage? (ISO 6.1.2)
All characters are significant.
Is case significant in an identifier with external linkage? (ISO 6.1.2)
Yes.
A.5 CHARACTERS
Implementation-Defined Behavior for Characters is covered in section G.3.4 of the
ANSI C Standard.
Detail any source and execution characters which are not explicitly specified by the
Standard? (ISO 5.2.1)
None.
List escape sequence value produced for listed sequences. (ISO 5.2.2)
TABLE A-1: ESCAPE SEQUENCE CHARACTERS AND VALUES
How many bits are in a character in the execution character set? (ISO 5.2.4.2)
8.
What is the mapping of members of the source character sets (in character and string
literals) to members of the execution character set? (ISO 6.1.3.4)
The identity function.
What is the equivalent type of a plain char? (ISO 6.2.1.1)
Either (user defined). The default is signed char. A compiler command-line option
may be used to make the default unsigned char.
Sequence Value
\a 7
\b 8
\f 12
\n 10
\r 13
\t 9
\v 11
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 214 2012 Microchip Technology Inc.
A.6 INTEGERS
Implementation-Defined Behavior for Integers is covered in section G.3.5 of the ANSI
C Standard.
The following table describes the amount of storage and range of various types of
integers: (ISO 6.1.2.5)
What is the result of converting an integer to a shorter signed integer, or the result of
converting an unsigned integer to a signed integer of equal length, if the value cannot
be represented? (ISO 6.2.1.2)
There is a loss of significance. No error is signaled.
What are the results of bitwise operations on signed integers? (ISO 6.3)
Shift operators retain the sign. Other operators act as if the operand(s) are unsigned
integers.
What is the sign of the remainder on integer division? (ISO 6.3.5)
+
What is the result of a right shift of a negative-valued signed integral type? (ISO 6.3.7)
The sign is retained.
TABLE A-2: INTEGER TYPES
Designation Size (bits) Range
char 8 -128 … 127
signed char 8 -128 … 127
unsigned char 8 0 … 255
short 16 -32768 … 32767
signed short 16 -32768 … 32767
unsigned short 16 0 … 65535
int 16 -32768 … 32767
signed int 16 -32768 … 32767
unsigned int 16 0 … 65535
long 32 -2147483648 … 2147438647
signed long 32 -2147483648 … 2147438647
unsigned long 32 0 … 4294867295
Implementation-Defined Behavior
2012 Microchip Technology Inc. DS52071B-page 215
A.7 FLOATING POINT
Implementation-Defined Behavior for Floating Point is covered in section G.3.6 of the
ANSI C Standard.
Is the scaled value of a floating constant that is in the range of the representable value
for its type, the nearest representable value, or the larger representable value immedi-
ately adjacent to the nearest representable value, or the smallest representable value
immediately adjacent to the nearest representable value? (ISO 6.1.3.1)
The nearest representable value.
The following table describes the amount of storage and range of various types of
floating point numbers: (ISO 6.1.2.5)
What is the direction of truncation, when an integral number is converted to a
floating-point number, that cannot exactly represent the original value? (ISO 6.2.1.3)
Down.
What is the direction of truncation, or rounding, when a floating-point number is
converted to a narrower floating-point number? (ISO 6.2.1.4)
Down.
A.8 ARRAYS AND POINTERS
Implementation-Defined Behavior for Arrays and Pointers is covered in section G.3.7
of the ANSI C Standard.
What is the type of the integer required to hold the maximum size of an array that is,
the type of the size of operator, size_t? (ISO 6.3.3.4, ISO 7.1.1)
unsigned int.
What is the size of integer required for a pointer to be converted to an integral type?
(ISO 6.3.4)
16 bits.
What is the result of casting a pointer to an integer, or vice versa? (ISO 6.3.4)
The mapping is the identity function.
What is the type of the integer required to hold the difference between two pointers to
members of the same array, ptrdiff_t? (ISO 6.3.6, ISO 7.1.1)
unsigned int.
TABLE A-3: FLO ATING-POINT TYPES
Designation Size (bits) Range
float 32 1.175494e-38 … 3.40282346e+38
double* 32 1.175494e-38 … 3.40282346e+38
long double 64 2.22507385e-308 … 1.79769313e+308
* double is equivalent to long double if -fno-short-double is used.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 216 2012 Microchip Technology Inc.
A.9 REGISTERS
Implementation-Defined Behavior for Registers is covered in section G.3.8 of the ANSI
C Standard.
To what extent does the storage class specifier register actually effect the storage
of objects in registers? (ISO 6.5.1)
If optimization is disabled, an attempt will be made to honor the register storage
class; otherwise, it is ignored.
A.10 STRUCTURES, UNIONS, ENUMERATIONS AND BIT FIELDS
Implementation-Defined Behavior for Structures, Unions, Enumerations and Bit Fields
is covered in sections A.6.3.9 and G.3.9 of the ANSI C Standard.
What are the results if a member of a union object is accessed using a member of a
different type? (ISO 6.3.2.3)
No conversions are applied.
Describe the padding and alignment of members of structures? (ISO 6.5.2.1)
Chars are byte-aligned. All other objects are word-aligned.
What is the equivalent type for a plain int bit field? (ISO 6.5.2.1)
User defined. By default, signed int bit field. May be made an unsigned int bit
field using a command line option.
What is the order of allocation of bit fields within an int? (ISO 6.5.2.1)
Bits are allocated from least-significant to most-significant.
Can a bit field straddle a storage-unit boundary? (ISO 6.5.2.1)
Yes.
Which integer type has been chosen to represent the values of an enumeration type?
(ISO 6.5.2.2)
int.
A.11 QUALIFIERS
Implementation-Defined Behavior for Qualifiers is covered in section G.3.10 of the
ANSI C Standard.
Describe what action constitutes an access to an object that has volatile-qualified type?
(ISO 6.5.3)
If an object is named in an expression, it has been accessed.
A.12 DECLARATORS
Implementation-Defined Behavior for Declarators is covered in section G.3.11 of the
ANSI C Standard.
What is the maximum number of declarators that may modify an arithmetic, structure,
or union type? (ISO 6.5.4)
No limit.
Implementation-Defined Behavior
2012 Microchip Technology Inc. DS52071B-page 217
A.13 STATEMENTS
Implementation-Defined Behavior for Statements is covered in section G.3.12 of the
ANSI C Standard.
What is the maximum number of case values in a switch statement? (ISO 6.6.4.2)
No limit.
A.14 PR EPROCESSING DIR ECTIVES
Implementation-Defined Behavior for Preprocessing Directives is covered in section
G.3.13 of the ANSI C Standard.
Does the value of a single-character character constant in a constant expression, that
controls conditional inclusion, match the value of the same character constant in the
execution character set? (ISO 6.8.1)
Yes.
Can such a character constant have a negative value? (ISO 6.8.1)
Yes.
What method is used for locating includable source files? (ISO 6.8.2)
The preprocessor searches the current directory, followed by directories named using
command-line options.
How are headers identified, or the places specified? (ISO 6.8.2)
The headers are identified on the #include directive, enclosed between < and >
delimiters, or between “ and ” delimiters. The places are specified using command-line
options.
Are quoted names supported for includable source files? (ISO 6.8.2)
Yes.
What is the mapping between delimited character sequences and external source file
names? (ISO 6.8.2)
The identity function.
Describe the behavior of each recognized #pragma directive. (ISO 6.8.6)
What are the definitions for __ DATE __ and __ TIME __ respectively, when the date
and time of translation are not available? (ISO 6.8.8)
Not applicable. The compiler is not supported in environments where these functions
are not available.
TABLE A-4: #PRAGMA BEHAVIOR
Pragma Behavior
#pragma code section-name Names the code section.
#pragma code Resets the name of the code section to its default
(viz., .text).
#pragma idata section-name Names t he initialized data section.
#pragma idata Resets the name of the initialized data section to its
default value (viz., .data).
#pragma udata section-name Names the uninitialized data section.
#pragma udata Resets the name of the uninitialized data section to
its default value (viz., .bss).
#pragma interrupt
function-name Designates function-name as an interrupt function.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 218 2012 Microchip Technology Inc.
A.15 LIBRARY FUNCTIONS
Implementation-Defined Behavior for Library Functions is covered in section G.3.14 of
the ANSI C Standard.
What is the null pointer constant to which the macro NULL expands? (ISO 7.1.5)
0.
How is the diagnostic printed by the assert function recognized, and what is the
termination behavior of this function? (ISO 7.2)
The assert function prints the file name, line number and test expression, separated by
the colon character (‘:’). It then calls the abort function.
What characters are tested for by the isalnum, isalpha, iscntrl, islower, isprint and
isupper functions? (ISO 7.3.1)
What values are returned by the mathematics functions after a domain errors?
(ISO 7.5.1)
NaN.
Do the mathematics functions set the integer expression errno to the value of the
macro ERANGE on underflow range errors? (ISO 7.5.1)
Yes.
Do you get a domain error or is zero returned when the fmod function has a second
argument of zero? (ISO 7.5.6.4)
Domain error.
TABLE A-5: CHARACTERS TESTED BY IS FUNCTIONS
Function Characters tested
isalnum One of the letters or digits: isalpha or isdigit.
isalpha One of the letters : islower or isupper.
iscntrl One of the five standard motion control characters, backspace and alert:
\f, \n, \r, \t, \v, \b, \a.
islower One of the letters ‘a’ through ‘z’.
isprint A graphic character or the space character: isalnum or ispunct or
space.
isupper One of the letters ‘A’ through ‘Z’.
ispunct One of the characters: ! " # % & ' ( ) ; < = > ? [ \ ] * + , - . / : ^
Implementation-Defined Behavior
2012 Microchip Technology Inc. DS52071B-page 219
A.16 SIGNALS
What is the set of signals for the signal function? (ISO 7.7.1.1)
Describe the parameters and the usage of each signal recognized by the signal
function. (ISO 7.7.1.1)
Application defined.
Describe the default handling and the handling at program startup for each signal
recognized by the signal function? (ISO 7.7.1.1)
None.
If the equivalent of signal (sig,SIG_DFL) is not executed prior to the call of a signal han-
dler, what blocking of the signal is performed? (ISO 7.7.1.1)
None.
Is the default handling reset if a SIGILL signal is received by a handler specified to the
signal function? (ISO 7.7.1.1)
No.
TABLE A-6: SIGNAL FUNCTION
Name Description
SIGABRT Abnormal termination.
SIGINT Receipt of an interactive attention signal.
SIGILL Detection of an invalid function image.
SIGFPE An erroneous arithmetic operation.
SIGSEGV An invalid access to storage.
SIGTERM A termination request sent to the program.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 220 2012 Microchip Technology Inc.
A.17 STREAMS AND FILES
Does the last line of a text stream require a terminating new line character? (ISO 7.9.2)
No.
Do space characters, that are written out to a text stream immediately before a new line
character, appear when the stream is read back in? (ISO 7.9.2)
Yes.
How many null characters may be appended to data written to a binary stream?
(ISO 7.9.2)
None.
Is the file position indicator of an append mode stream initially positioned at the start or
end of the file? (ISO 7.9.3)
Start.
Does a write on a text stream cause the associated file to be truncated beyond that
point? (ISO 7.9.3)
Application defined.
Describe the characteristics of file buffering. (ISO 7.9.3)
Fully buffered.
Can zero-length file actually exist? (ISO 7.9.3)
Yes.
What are the rules for composing a valid file name? (ISO 7.9.3)
Application defined.
Can the same file be open multiple times? (ISO 7.9.3)
Application defined.
What is the effect of the remove function on an open file? (ISO 7.9.4.1)
Application defined.
What is the effect if a file with the new name exists prior to a call to the rename function?
(ISO 7.9.4.2)
Application defined.
What is the form of the output for %p conver sion in the fprintf function? (ISO 7.9.6.1)
A hexadeci ma l rep re se ntation.
What form does the input for %p conversion in the fscanf funct ion t ake ? (ISO 7.9.6. 2)
A hexadeci ma l rep re se ntation.
Implementation-Defined Behavior
2012 Microchip Technology Inc. DS52071B-page 221
A.18 TMPFILE
Is an open temporary file removed if the program terminates abnormally? (ISO 7.9.4.3)
Yes.
A.19 ERRNO
What value is the macro errno set to by the fgetpos or ftell function on failure?
(ISO 7.9.9.1, (ISO 7.9.9.4)
Application defined.
What is the format of the messages generated by the perror function? (ISO 7.9.10.4)
The argument to perror, followed by a colon, followed by a text description of the
value of errno.
A.20 MEMORY
What is the behavior of the calloc, malloc or realloc function if the size requested
is zero? (ISO 7.10.3)
A block of zero length is allocated.
A.21 ABORT
What happens to open and temporary files when the abort function is called?
(ISO 7.10.4.1)
Nothing.
A.22 EXIT
What is the status returned by the exit function if the value of the argument is other than
zero, EXIT_SUCCESS, or EXIT_FAILURE? (ISO 7.10.4.3)
The value of the argument.
A.23 GETENV
What limitations are there on environment names? (ISO 7.10.4.4)
Application defined.
Describe the method used to alter the environment list obtained by a call to the getenv
function. (ISO 7.10.4.4)
Application defined.
A.24 SYSTEM
Describe the format of the string that is passed to the system function. (ISO 7.10.4.5)
Application defined.
What mode of execution is performed by the system function? (ISO 7.10.4.5)
Application defined.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 222 2012 Microchip Technology Inc.
A.25 STRERROR
Describe the format of the error message output by the strerror function.
(ISO 7.11.6.2)
A plain char ac ter stri ng .
List the contents of the error message strings returned by a call to the strerror
function. (ISO 7.11.6.2)
TABLE A-7: ERROR MESSAGE STRINGS
Errno Message
0No error
EDOM Domain error
ERANGE Range error
EFPOS File positioning error
EFOPEN File open error
nnn Error #nnn
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 223
Appendix B. Diagnostics
B.1 INTRODUCTION
This appendix lists the most common diagnostic messages generated by the MPLAB
XC16 C Compiler.
The compiler can produce two kinds of diagnostic messages: Errors and Warnings.
Each kind has a different purpose.
• Error messages report problems that make it impossible to compile your program.
The compiler reports errors with the source file name, and the line number where
the problem is apparent.
• W arning messages report other unusual conditions in your code that may indicate
a problem, although compilation can (and does) proceed. W arning messages also
report the source file name and line number, but include the text warning: to
distinguish them from error messages.
Warnings may indicate danger points that should be checked to ensure that your
program performs as directed. A warning may signal that obsolete features or
non-standard features of the compiler are being used. Many warnings are issued
only if you ask for them with one of the -W options (for instance,-Wall requests a
variety of useful warnings).
In rare instances, the compiler may issue an internal error message report. This
signifies that the compiler itself has detected a fault that should be reported to
Microchip Support. Details on contacting support are located in the
Section “Preface”.
B.2 ERRORS
Symbols
\x used with no following HEX digits
The escape sequence \x should be followed by hex digits.
‘&’ constraint used with no register c lass
The asm statement is invalid.
‘%’ constraint us ed with last operand
The asm statement is invalid.
#elif after #else
In a preprocessor conditional, the #else clause must appear after any #elif clauses.
#elif without #if
In a preprocessor conditional, the #if must be used before using the #elif.
#else after #else
In a preprocessor conditional, the #else clause must appear only once.
#else without #if
In a preprocessor conditional, the #if must be used before using the #else.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 224 2012 Microchip Technology Inc.
#endif without #if
In a preprocessor conditional, the #if must be used before using the #endif.
#error ‘message’
This error appears in response to a #error directive.
#if with no expression
An expression that evaluates to a constant arithmetic value was expected.
#include expects “FILENAME” or <FILENAME>
The file name for the #include is missing or incomplete. It must be enclosed by quotes
or angle brackets.
‘#’ is not followed by a macro p arameter
The stringsize operator, ‘#’ must be followed by a macro argument name.
‘#keyword’ expects “FILENAME” or <FILENAME>
The specified ‘#keyword’ expects a quoted or bracketed file name as an argument.
‘#’ is not followed by a macro p arameter
The ‘#’ operator should be followed by a macro argument name.
‘##’ cannot appear at either end of a macro expansion
The concatenation operator, ‘##’ may not appear at the start or the end of a macro
expansion.
A
a parameter list with an ellipsis can’t match an empty parameter name list
declaration
The declaration and definition of a function must be consistent.
“symbol” after #line is not a positive integer
#line is expecting a source line number which must be positive.
aggregate value used where a complex was expected
Do not use aggregate values where complex values are expected.
aggregate value used where a float was expected
Do not use aggregate values where floating-point values are expected.
aggregate value used where an integer was expected
Do not use aggregate values where integer values are expected.
alias arg not a string
The argument to the alias attribute must be a string that names the target for which the
current identifier is an alias.
alignment may not be specified for ‘identifier’
The aligned attribute may only be used with a variable.
‘__alignof’ applied to a bit-field
The ‘__alignof’ operator may not be applied to a bit-field.
alternate interrupt vector is not a constant
The interrupt vector number must be an integer constant.
alternate interrupt vector number n is not valid
A valid inter r upt ve cto r num ber is req uired.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 225
ambiguous abbreviation argument
The specified command-line abbreviation is ambiguous.
an argument type that has a default promotion can’t match an empty p ar ameter
name list declaration.
The declaration and definition of a function must be consistent.
args to be formatted is not ...
The first-to-check index argument of the format attribute specifies a parameter that is
not declared ‘…’.
argument ‘identifier’ doesn’t match prototype
Function argument types should match the function’s prototype.
argument of ‘asm’ is not a constant string
The argument of ‘asm’ must be a constant string.
argument to ‘-B’ is missing
The directory name is missing.
argument to ‘-l’ is missing
The library name is missing.
argument to ‘-specs’ is missing
The name of the specs file is missing.
argument to ‘-specs=’ is missing
The name of the specs file is missing.
argument to ‘-x’ is missing
The language name is missing.
argument to ‘-Xlinker’ is missing
The argument to be passed to the linker is missing.
arithmetic on pointer to an incomplete type
Arithmetic on a pointer to an incomplete type is not allowed.
array index in non-array initializer
Do not use array indices in non-array initializers.
array size missing in ‘identifier’
An arra y size is missing.
array subscript is not an integer
Array subscrip ts must be integers.
‘asm’ operand constraint incompatible with operand size
The asm statement is invalid.
‘asm’ operand requires impossible reload
The asm statement is invalid.
asm template is not a string constant
Asm templates must be string constants.
assertion without predicate
#assert or #unassert must be followed by a predicate, which must be a single identifier .
‘attribute’ attribute applies only to functions
The attribute ‘attribute’ may only be applied to functions.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 226 2012 Microchip Technology Inc.
B
bit-field ‘identifier’ has invalid type
Bit-fields must be of enumerated or integral type.
bit-field ‘identifier’ width not an integer constant
Bit-field widths must be integer constants.
both long and short specified for ‘identifier’
A variable cannot be of type long and of type short.
both signed and unsigned specified for ‘identifier’
A variable cannot be both signed and unsigned.
braced-group within expression allowed only inside a function
It is illegal to have a braced-group within expression outside a function.
break statement not within loop or switch
Break statements must only be used within a loop or switch.
__builtin_longjmp second argument must be 1
__builtin_longjmp requires its second argument to be 1.
C
called object is not a function
Only functions may be called in C.
cannot convert to a pointer type
The expression cannot be converted to a pointer type.
cannot put object with volatile field into register
It is not legal to put an object with a volatile field into a register.
cannot reload integer constant operand in ‘asm’
The asm statement is invalid.
cannot specify both near and far attributes
The attributes near and far are mutually exclusive, only one may be used for a function
or variable.
cannot take address of bit-field ‘identifier’
It is not legal to attempt to take address of a bit-field.
can’t open ‘file’ for writing
The system cannot open the specified ‘file’. Possible causes are not enough disk
space to open the file, the directory does not exist, or there is no write permission in the
destination directory.
can’t set ‘attribute’ attribute after definition
The ‘attribute’ attribute must be used when the symbol is defined.
case label does not reduce to an intege r constant
Case labels must be compile-time integer constants.
case label not within a switch statement
Case labels must be within a switch statement.
cast specifies array type
It is not permissible for a cast to specify an array type.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 227
cast specifies function type
It is not permissible for a cast to specify a function type.
cast to union type from type not pr esent in union
When casting to a union type, do so from type present in the union.
char-array initialized from wide string
Char-arrays should not be initialized from wide strings. Use ordinary strings.
file: compiler compiler not installed on this system
Only the C compiler is distributed; other high-level languages are not supported.
complex invalid for ‘identifier’
The complex qualifier may only be applied to integral and floating types.
conflicting types for ‘identifier’
Multiple, inconsistent declarations exist for identifier.
continue statement not within loop
Continue statements must only be used within a loop.
conversion to non-scalar type requested
Type conversion must be to a scalar (not aggregate) type.
D
data type of ‘name’ isn’t suitable for a register
The data type does not fit into the requested register.
declaration for parameter ‘identifier’ but no such parameter
Only parameters in the parameter list may be declared.
declaration of ‘identifier’ as array of functions
It is not legal to have an array of functions.
declaration of ‘identifier’ as array of voids
It is not legal to have an array of voids.
‘identifier’ declared as function returning a function
Functions may not return functions.
‘identifier’ declared as function returning an array
Functions may not return arrays.
decrement of pointer to unknown structure
Do not decrement a pointer to an unknown structure.
‘default’ label not within a switch statement
Default case labels must be within a switch statement.
‘symbol’ defined both normally and as an alias
A ‘symbol’ can not be used as an alias for another symbol if it has already been
defined.
‘defined’ cannot be used as a macro name
The macro name cannot be called ‘defined’.
dereferencing pointer to incomplete type
A dereferenced pointer must be a pointer to an incomplete type.
division by zero in #if
Division by zero is not computable.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 228 2012 Microchip Technology Inc.
duplicate cas e valu e
Case values must be unique.
duplicate lab el ‘identifier’
Labels must be unique within their scope.
duplicate macro parameter ‘symbol’
‘symbol’ has been used more than once in the parameter list.
duplicate member ‘identifier’
Structures may not have duplicate members.
duplicate (or overlapping) case value
Case ranges must not have a duplicate or overlapping value. The error message ‘this
is the first entry overlapping that value’ will provide the location of the first occurrence
of the duplicate or overlapping value. Case ranges are an extension of the ANSI
standard for the compiler.
E
elements of array ‘identifier’ h ave inco mplete ty pe
Array elements should have complete types.
empty character constant
Empty character constants are not legal.
empty file name in ‘#keyword’
The file name specified as an argument of the specified #keyword is empty.
empty index range in initializer
Do not use empty index ranges in initializers
empty scalar initializer
Scalar initializers must not be empty.
enumerator value for ‘identifier’ not integer constant
Enumerator values must be integer constants.
error closing ‘file’
The system cannot close the specified ‘file’. Possible causes are not enough disk
space to write to the file or the file is too big.
error writing to ‘file’
The system cannot write to the specified ‘file’. Possible causes are not enough disk
space to write to the file or the file is too big.
excess elements in char array initializer
There are more elements in the list than the initializer value states.
excess elements in struct initializer
Do not use excess elements in structure initializers.
expression statement has incomplete type
The type of the expression is incomplete.
extra brace group at end of initializer
Do not place extra brace groups at the end of initializers.
extraneous argument to ‘option’ option
There are too many arguments to the specified command-line option.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 229
F
‘identifier’ fails to be a typedef or built in type
A data type must be a typedef or built-in type.
field ‘identifier’ declared as a function
Fields may not be declared as functions.
field ‘identifier’ has incomplete type
Fields must have complete types.
first argument to __builtin _choose_expr not a consta nt
The first argument must be a constant expression that can be determined at compile
time.
flexible array member in otherwise empty struct
A flexible array member must be the last element of a structure with more than one
named member.
flexible array member in union
A flexible array member cannot be used in a union.
flexible array member not at end of struct
A flexible array member must be the last element of a structure.
‘for’ loop initial declaration used out side C99 mode
A ‘for’ loop initial declaration is not valid outside C99 mode.
format string arg follows the args to be formatted
The arguments to the format attribute are inconsistent. The format string argument
index must be less than the index of the first argument to check.
format string arg not a string type
The format string index argument of the format attribute specifies a parameter which is
not a string type.
format string has invalid operand number
The operand number argument of the format attribute must be a compile-time constant.
function definit ion declared ‘register’
Function definitions may not be declared ‘register’.
function definit ion declared ‘typedef’
Function definitions may not be declared ‘typedef’.
function does not return string type
The format_arg attribute may only be used with a function which return value is a string
type.
function ‘identifier’ is initialized like a variable
It is not legal to initialize a function like a variable.
function re turn type cannot be function
The return type of a function cannot be a function.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 230 2012 Microchip Technology Inc.
G
global register variable follows a function definition
Global register variables should precede function definitions.
global register variable has initial value
Do not specify an initial value for a global register variable.
global register variable ‘identifier’ used in nested function
Do not use a global register variable in a nested function.
H
‘identifier’ has an incomplete type
It is not legal to have an incomplete type for the specified ‘identifier’.
‘identifier’ has both ‘extern’ and initializer
A variabl e declar ed ‘extern’ cannot be initialized.
hexadecimal floating constant s require an exponent
Hexadecimal floating constants must have exponents.
I
implicit declaration of function ‘identifier’
The function identifier is used without a preceding prototype declaration or function
definition.
impossible register constraint in ‘asm’
The asm statement is invalid.
incompatible type for argument n of ‘identifier’
When calling functions in C, ensure that actual argument types match the formal
para meter types.
incompatible type for argument n of indirect function call
When calling functions in C, ensure that actual argument types match the formal
para meter types.
incompatible types in operation
The types used in operation must be compatible.
incomplete ‘name’ option
The option to the command-line parameter name is incomplete.
inconsistent operand constraints in an ‘asm’
The asm statement is invalid.
increment of pointer to unknown structure
Do not increment a pointer to an unknown structure.
initializer element is not computable at load time
Initializer elements must be computable at load time.
initializer element is not constant
Initializer elements must be constant.
initializer fails to determine size of ‘identifier’
An arra y initializer fails to determine its size.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 231
initializer for static variable is not constant
Static variable initializers must be constant.
initializer for static variable uses complica te d arithme tic
Static variable initializers should not use complicated arithmetic.
input operand constraint contains ‘constraint’
The specified constraint is not valid for an input operand.
int-array initialized from non-wide string
Int-arrays should not be initialized from non-wide strings.
interrupt functions must not take parameters
An interrupt function cannot receive parameters. void must be used to state explicitly
that the argument list is empty.
interrupt functions must return void
An interrupt function must have a return type of void. No other return type is allowed.
interrupt modifier ‘name’ unknown
The compiler was expecting ‘irq’, ‘altirq’ or ‘save’ as an interrupt attribute modifier.
interrupt modifier syntax error
There is a syntax error with the interrupt attribute modifier.
interrupt pragma must have file scope
#pragma interrupt must be at file scope.
interrupt save modifier syntax error
There is a syntax error with the ‘save’ modifier of the interrupt attribute.
interrupt vector is not a constant
The interrupt vector number must be an integer constant.
interrupt vector number n is not valid
A valid inter r upt ve cto r num ber is req uired.
invalid #ident directive
#ident should be followed by a quoted string literal.
invalid arg to ‘__builtin_frame_address’
The argument should be the level of the caller of the function (where 0 yields the frame
address of the current function, 1 yields the frame address of the caller of the current
function, and so on) and is an integer literal.
invalid arg to ‘__builtin_return_address’
The level argument must be an integer literal.
invalid argument for ‘name’
The compiler was expecting ‘data’ or ‘prog’ as the space attribute parameter.
invalid character ‘character’ in #if
This message appears when an unprintable character, such as a control character,
appears after #if.
invalid initial value for member ‘name’
Bit-field ‘name’ can only be initialized by an integer.
invalid initializer
Do not use invalid initializers.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 232 2012 Microchip Technology Inc.
Invalid location qualifier: ‘symbol’
Expecting ‘sfr’ or ‘gpr’, which are ignored on dsPIC DSC devices, as location qualifiers.
invalid operands to binary ‘operator’
The operands to the specified binary operator are invalid.
Invalid option ‘option’
The specified command-line option is invalid.
Invalid option ‘symbol’ to interrupt pragma
Expecting shadow and/or save as options to interrupt pr agma.
Invalid option to interrupt pragma
Garbage at the end of the pragma.
Invalid or missing function name from interrupt pragma
The interrupt pragma requires the name of the function being called.
Invalid or missing section name
The section name must start with a letter or underscore (‘_’) and be followed by a
sequence of letters, underscores and/or numbers. The names ‘access’, ‘shared’ and
‘overlay’ have special meaning.
invalid preprocessing directive #‘directive’
Not a valid preprocessing directive. Check the spelling.
invalid preprologue argument
The preprologue option is expecting an assembly statement or statements for its
argument enclosed in double quotes.
invalid register name for ‘name’
File scope variable ‘name’ declared as a register variable with an illegal register name.
invalid register name ‘name’ for register variable
The specified name is not the name of a register.
invalid save variable in interrupt pragma
Expecting a symbol or symbols to save.
invalid storage class for function ‘identifier’
Functions may not have the ‘register’ storage class.
invalid suffix ‘suffix’ on integer constant
Integer constants may be suffixed by the letters ‘u’, ‘U’, ‘l’ and ‘L’ only.
invalid suffix on floating constant
A floating constant suffix may be ‘f’, ‘F’, ‘l’ or ‘L’ only . If there are two ‘L’s, they must be
adjacent and the same case.
invalid type argument of ‘operator’
The type of the argument to operator is in va li d.
invalid type modifier within pointer declarator
Only const or volatile may be used as type modifiers within a pointer declarator.
invalid use of array with unspecified bounds
Arrays with unspecified bounds must be used in valid ways.
invalid use of incomplete typedef ‘typedef’
The specified typedef is being used in an invalid way; this is not allowed.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 233
invalid use of undefined type ‘type identifier’
The specified type is being used in an invalid way; this is not allowed.
invalid use of void expression
Void expressions must not be used.
“name” is not a valid filename
#line requires a valid file name.
‘filename’ is too large
The specified file is too large to process the file. Its probably larger than 4 GB, and the
preprocessor refuses to deal with such large files. It is required that files be less than
4GB in size.
ISO C forbids data definition with no type or storage class
A type specifier or storage class specifier is required for a data definition in ISO C.
ISO C requires a named argument before ‘...’
ISO C requires a named argument before ‘...’.
L
label label referenced out side of any function
Labels may only be referenced inside functions.
label ‘label’ used but not defined
The specified label is used but is not defined.
language ‘name’ not recognized
Permissible languages include: c assembler none.
filename: linker input file unused because linking not done
The specified filename was specified on the command line, and it was taken to be a
linker input file (since it was not recognized as anything else). However, the link step
was not run. Therefore, this file was ignored.
long long long is too long for GCC
The compiler supports integers no longer than long long.
long or short specified with char for ‘identifier’
The long and short qualifiers cannot be used with the char type.
long or short specified with floating type for ‘identifier’
The long and short qualifiers cannot be used with the float type.
long, short, signed or unsigned invalid for ‘identifier’
The long, short and signed qualifiers may only be used with integral types.
M
macro names must be identifiers
Macro names must start with a letter or underscore followed by more letters, numbers
or underscores.
macro parameters must be comma-separated
Commas are required between parameters in a list of parameters.
macro ‘name’ passed n arguments, but takes just n
Too many arguments were passed to macro ‘name’.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 234 2012 Microchip Technology Inc.
macro ‘name’ requires n arguments, but only n given
Not enough arguments were passed to macro ‘name’.
matching constraint not valid in output operand
The asm statement is invalid.
‘symbol’ may not appear in macro p arameter list
‘symbol’ is not allowed as a parameter.
Missing ‘=’ for ‘save’ in interrupt pragma
The save parameter requires an equal sign before the variable(s) are listed. For
example, #pragma interrupt isr0 save=var1,var2
missing ‘(’after predicate
#assert or #unassert expects parentheses around the answer. For example:
ns#assert PREDICATE (ANSWER)
missing ‘(’ in expression
Parentheses are not matching, expecting an opening parenthesis.
missing ‘)’ after “defined”
Expecting a closing parenthesis.
missing ‘)’ in expression
Parentheses are not matching, expecting a closing parenthesis.
missing ‘)’ in macro parameter list
The macro is expecting parameters to be within parentheses and separated by
commas.
missing ‘)’ to complete answer
#assert or #unassert expects parentheses around the answer.
missing argument to ‘option’ option
The specified command-line option requires an argument.
missing binary operator before token ‘token’
Expecting an operator before the ‘token’.
missing terminating ‘character’ character
Missing terminating character such as a single quote ‘, double quote ” or right angle
bracket >.
missing terminating > character
Expecting terminating > in #include directive.
more than n operands in ‘asm’
The asm statement is invalid.
multiple default labels in one switch
Only a single default label may be specified for each switch.
multiple parameters named ‘identifier’
Parameter names must be unique.
multiple storage classes in declaration of ‘identifier’
Each declaration should have a single storage class.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 235
N
negative width in bit-field ‘identifier’
Bit-field widths may not be negative.
nested function ‘name’ declared ‘extern’
A nested functi on ca nnot be decla red ‘extern’.
nested redefinition of ‘identifier’
Nested redefinitions are illegal.
no data type for mode ‘mode’
The argument mode specified for the mode attribute is a recognized GCC machine
mode, but it is not one that is implemented in the compiler.
no include pa th in which to find ‘name’
Cannot find include file ‘name’.
no macro name given in #‘directive’ directive
A macro name must follow the #define, #undef, #ifdef or #ifndef directives.
nonconstant array index in initializer
Only constant array indices may be used in initializers.
non-prototype definition here
If a function prototype follows a definition without a prototype, and the number of
arguments is inconsistent between the two, this message identifies the line number of
the non-prototype definition.
number of arguments doesn’t match prototype
The number of function arguments must match the function’s prototyp e.
O
operand constraint contains incorrectly positioned ‘+’ or ‘=’.
The asm statement is invalid.
operand constraints for ‘asm’ differ in number of alternatives
The asm statement is invalid.
operator “defined” requires an identifier
“defined ” is expecti ng an iden tif ier.
operator ‘symbol’ has no right operand
Preprocessor operator ‘symbol’ requires an operand on the right side.
output number n not directly addressable
The asm statement is invalid.
output operand constraint lacks ‘=’
The asm statement is invalid.
output operand is constant in ‘asm’
The asm statement is invalid.
overflow in enumeration values
Enumeration values must be in the range of ‘int’.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 236 2012 Microchip Technology Inc.
P
parameter ‘identifier’ decla red vo id
Parameters may not be declared void.
parameter ‘identifier’ has incomplete type
Parameters must have complete types.
parameter ‘identifier’ has jus t a forwar d declarat ion
Parameters must have complete types; forward declarations are insufficient.
parameter ‘identifier’ is initialized
It is not legal to initialize parameters.
parameter name missing
The macro was expecting a parameter name. Check for two commas without a name
between.
parameter name missing from parameter list
Paramet er names must be inc lu ded in the parameter list.
parameter name omitted
Parameter names may not be omitted.
param types given both in param list and separately
Parameter types should be given either in the parameter list or separately , but not both.
parse error
The source line cannot be parsed; it contains errors.
pointer value used where a complex value was expected
Do not use pointer values where complex values are expected.
pointer value used where a floating point value was expected
Do not use pointer values where floating-point values are expected.
pointers are not permitted as case values
A case value must be an integer-valued constant or constant expression.
predicate must be an identifier
#assert or #unassert require a single identifier as the predicate.
predicate’s answer is empty
The #assert or #unassert has a predicate and parentheses but no answer inside the
parentheses, which is required.
previous declaration of ‘identifier’
This message identifies the location of a previous declaration of identifier that conflicts
with the current declaration.
identifier previously declared here
This message identifies the location of a previous declaration of identifier that conflicts
with the current declaration.
identifier previously defined here
This message identifies the location of a previous definition of identifier that conflicts
with the current definition.
prototype declaration
Identifies the line number where a function prototype is declared. Used in conjunction
with other error messages.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 237
R
redeclaration of ‘identifier’
The identifier is multiply declar ed.
redeclaration of ‘enum identifier’
Enums may not be redeclared.
‘identifier’ redeclared as different kind of symbol
Multiple, inconsistent declarations exist for identifier.
redefinition of ‘identifier’
The identifier is multiply defined.
redefinition of ‘struct identifier’
Structs may not be redefined.
redefinition of ‘union identifier’
Unions may not be redefined.
register name given for non-register variable ‘name’
Attempt to map a register to a variable which is not marked as register.
register name not specified for ‘name’
File scope variable ‘name’ declared as a register variable without providing a register.
register specified for ‘name’ isn’t suitable for data type
Alignment or other restrictions prevent using requested register.
request for member ‘identifier’ in something not a structure or union
Only structure or unions have members. It is not legal to reference a member of
anything else, since nothing else has members.
requested alignment is not a constant
The argument to the aligned attribute must be a compile-time constant.
requested alignment is not a power of 2
The argument to the aligned attribute must be a power of two.
requested alignment is too large
The alignment size requested is larger than the linker allows. The size must be 4096
or less and a power of 2.
return type is an incomplete type
Return types must be complete.
S
save variable ‘name’ index not constant
The subscript of the array ‘name’ is not a constant integer.
save variable ‘name’ is not word aligned
The object being saved must be word aligned
save variable ‘name’ size is not even
The object being saved must be evenly sized.
save variable ‘name’ size is not known
The object being saved must have a known size.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 238 2012 Microchip Technology Inc.
section attribute cannot be specified for local variables
Local variables are always allocated in registers or on the stack. It is therefore not legal
to attempt to place local variables in a named section.
section attribute not allowed for identifier
The section attribute may only be used with a function or variable.
section of identifier conflicts with previous declaration
If multiple declarations of the same identifier specify the section attribute, then the
value of the attribute must be consistent.
sfr address ‘address’ is not valid
The address must be less than 0x2000 to be valid.
sfr address is not a constant
The sfr address must be a constant.
‘size of’ applied to a bit-field
‘sizeof’ must not be applied to a bit-field.
size of array ‘identifier’ has non-integer type
Array size specifiers must be of integer type.
size of array ‘identifier’ is negative
Array sizes may not be negative.
size of array ‘identifier’ is too large
The specified array is too large.
size of variable ‘variable’ is too large
The maximum size of the variable can be 32768 bytes.
storage class specified for parameter ‘identifier’
A storage class may not be specified for a parameter.
storage size of ‘identifier’ isn’t constant
Storage size must be compile-time constants.
storage size of ‘identifier’ isn’t known
The size of identifier is incompletely specified.
stray ‘character’ in program
Do not place stray ‘character’ characters in the source program.
strftime formats cannot format arguments
While using the attribute format when the archetype parameter is strftime, the third
parameter to the attribute, which specifies the first parameter to match against the
format string, should be 0. strftime style functions do not have input values to match
against a format string.
structure has no member named ‘identifier’
A structure member named ‘identifier ’ is referenced; but the referenced structure
contains no such member. This is not allowed.
subscripted value is neither array nor pointer
Only arrays or pointers may be subscripted.
switch quantity not an integer
Switch quantities must be integers
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 239
symbol ‘symbol’ not defined
The symbol ‘symbol’ needs to be declared before it may be used in the pragma.
syntax error
A syntax error exists on the specified line.
syntax error ‘:’ without preceding ‘?’
A ‘:’ must be preceded by ‘?’ in the ‘?:’ operator.
T
the only valid combination is ‘long double’
The long qualifier is the only qualifier that may be used with the double type.
this built-in requires a frame pointer
__builtin_return_address requires a frame pointer. Do not use the
-fomit-frame-pointer option.
this is a previous declaration
If a label is duplicated, this message identifies the line number of a preceding
declaration.
too few arguments to function
When calling a function in C, do not specify fewer arguments than the function requires.
Nor should you specify too many.
too few arguments to function ‘identifier’
When calling a function in C, do not specify fewer arguments than the function requires.
Nor should you specify too many.
too many alternatives in ‘asm’
The asm statement is invalid.
too many arguments to function
When calling a function in C, do not specify more arguments than the function requires.
Nor should you specify too few.
too many arguments to function ‘identifier’
When calling a function in C, do not specify more arguments than the function requires.
Nor should you specify too few.
too many decimal points in number
Expecting only one decimal point.
top-level declaration of ‘identifier’ specifies ‘auto’
Auto variables can only be declared inside functions.
two or more data types in declaration of ‘identifier’
Each identifier may have only a single data type.
two types specified in one empty declaration
No more that one type should be specified.
type of formal parameter n is incomplete
Specify a complete type for the indicated parameter.
type mismatch in conditional expression
Types in conditional expressions must not be mismatched.
typedef ‘identifier’ is initialized
It is not legal to initialize typedef’s. Use __typeof__ instead.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 240 2012 Microchip Technology Inc.
U
‘identifier’ undeclared (first use in this function)
The specified identifier must be declared.
‘identifier’ undeclared here (not in a function)
The specified identifier must be declared.
union has no member named ‘identifier’
A union member named ‘identifier’ is referenced, but the referenced union contains no
such member. This is not allowed.
unknown field ‘identifier’ specified in initializer
Do not use unknown fields in initializers.
unknown machine mode ‘mode’
The argument mode specified for the mode attribute is not a recognized machine
mode.
unknown register name ‘name’ in ‘asm’
The asm statement is invalid.
unrecognized format specifier
The argument to the format attribute is invalid.
unrecognized option ‘-option’
The specified command-line option is not recognized.
unrecognized option ‘option’
‘option’ is not a known option.
‘identifier’ used prior to declaration
The identifier is used prior to its declaration.
unterminated #‘name’
#endif is expected to terminate a #if, #ifdef or #ifndef conditional.
unterminated argument list invoking macro ‘name’
Evaluation of a function macro has encountered the end of file before completing the
macro expansion.
unterminated comment
The end of file was reached while scanning for a comment terminator.
V
‘va_start’ used in function with fixed args
‘va_start’ should be used only in functions with variable argument lists.
variable ‘identifier’ has initializer but incomplete type
It is not legal to initialize variables with incomplete types.
variable or field ‘identifier’ declared void
Neither variables nor fields may be declared void.
variable-sized object may not be initialized
It is not legal to initialize a variable-sized object.
virtual memory exhausted
Not enough memory left to write error message.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 241
void expression between ‘(‘ and ’)’
Expecting a constant expression but found a void expression between the
parentheses.
‘void’ in parameter list must be the entire list
If ‘void’ appears as a parameter in a parameter list, then there must be no other
parameters.
void value not ignored as it ought to be
The value of a void function should not be used in an expression.
W
warning: -pipe ignored because -save-temps specified
The -pipe option cannot be used with the -save-temps option.
warning: -pipe ignored because -time specified
The -pipe option cannot be used with the -time option.
warning: ‘-x spec’ after last input file has no effect
The ‘-x’ command line option affects only those files named after its on the command
line; if there are no such files, then this option has no effect.
weak declaration of ‘name’ must be public
Weak symbols must be externally visible.
weak declaration of ‘name’ must precede definition
‘name’ was defined and then declared weak.
wrong number of arguments specified for attribute attribute
There are too few or too many arguments given for the attribute named ‘attribute’.
wrong type argument to bit-complement
Do not use the wrong type of argument to this operator.
wrong type argument to decrement
Do not use the wrong type of argument to this operator.
wrong type argument to increment
Do not use the wrong type of argument to this operator.
wrong type argument to unary exclamation mark
Do not use the wrong type of argument to this operator.
wrong type argument to unary minus
Do not use the wrong type of argument to this operator.
wrong type argument to unary plus
Do not use the wrong type of argument to this operator.
Z
zero width for bit-fie ld ‘identifier’
Bit-fields may not have zero width.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 242 2012 Microchip Technology Inc.
B.3 WARNINGS
Symbols
‘/*’ within comment
A comment mark was found within a comment.
‘$’ character(s) in identifier or number
Dollar signs in identifier names are an extension to the standard.
#‘directive’ is a GCC extension
#warning, #include_next, #ident, #import, #assert and #unassert directives are GCC
extensions and are not of ISO C89.
#import is obsolete, use an #ifndef wrapper in the header file
The #import directive is obsolete. #import was used to include a file if it hadn’t already
been included. Use the #ifndef directive instead.
#include_next in primary source file
#include_next starts searching the list of header file directories after the directory in
which the current file was found. In this case, there were no previous header files so it
is starting in the primary source file.
#pragma pack (pop) encountered without matching #pragma pack (push, <n>)
The pack(pop) pragma must be paired with a pack(push) pragma, which must precede
it in the source file.
#pragma pack (pop, identifier) encountered without matching #pragma pack
(push, identifier, <n>)
The pack(pop) pragma must be paired with a pack(push) pragma, which must precede
it in the source file.
#warning: message
The directive #warning causes the preprocessor to issue a warning and continue
preprocessing. The tokens following #warning are used as the warning message.
A
absolute address specification ignored
Ignoring the absolute address specification for the code section in the #pragma
statement because it is not supported in the compiler. Addresses must be specified in
the linker script and code sections can be defined with the keyword __attribute__.
address of register variable ‘name’ requested
The register specifier prevents taking the address of a variable.
alignment must be a small power of two, not n
The alignment parameter of the pack pragma must be a small power of two.
anonymous enum declared inside parameter list
An anonymous enum is declared inside a function parameter list. It is usually better
programming practice to declare enums outside parameter lists, since they can never
become complete types when defined inside parameter lists.
anonymous struct declared inside parameter list
An anonymous struct is declared inside a function parameter list. It is usually better
programming practice to declare structs outside parameter lists, since they can never
become complete types when defined inside parameter lists.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 243
anonymous union declared inside parameter list
An anonymous union is declared inside a function parameter list. It is usually better
programming practice to declare unions outside parameter lists, since they can never
become complete types when defined inside parameter lists.
anonymous variadic macros were introduced in C99
Macros which accept a variable number of arguments is a C99 feature.
argument ‘identifier’ might be clobbered by ‘longjmp’ or ‘vfork’
An argument might be changed by a call to longjmp. These warnings are possible only
in optimizing compilation.
array ‘identifier’ assumed to have one element
The length of the specified array was not explicitly stated. In the absence of information
to the contrary, the compiler assumes that it has one element.
array subscript has type ‘char’
An array subscript has type ‘char’.
array type has incomplete element type
Array types should not have incomplete element types.
asm operand n probably doesn’t match constraints
The specified extended asm operand probably doesn’t match its constraints.
assignmen t of read-on ly member ‘name’
The member ‘name’ was declared as const and cannot be modified by assignment.
assignm ent of read-on ly var iable ‘name’
‘name’ was declared as const and cannot be modified by assignment.
‘identifier’ attribute directive ignored
The named attribute is not a known or supported attribute, and is therefore ignored.
‘identifier’ attribute does not apply to types
The named attribute may not be used with types. It is ignored.
‘identifier’ attribute ignored
The named attribute is not meaningful in the given context, and is therefore ignored.
‘attribute’ attribute only applies to function types
The specified attribute can only be applied to the return types of functions and not to
other declarations.
B
backslash and newline separated by space
While processing for escape sequences, a backslash and newline were found
separated by a space.
backslash-newline at end of file
While processing for escape sequences, a backslash and newline were found at the
end of the file.
bit-field ‘identifier’ type invalid in ISO C
The type used on the specified identifier is not valid in ISO C.
braces around scalar initializer
A redundant set of braces around an initializer is supplied.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 244 2012 Microchip Technology Inc.
built-in function ‘identifier’ declared as non-function
The specified function has the same name as a built-in function, yet is declared as
something other than a function.
C
C++ style comments are not allowed in ISO C89
Use C style comments ‘/*’ and ‘*/’ instead of C++ style comments ‘//’.
call-clobbered register used for global register variable
Choose a register that is normally saved and restored by function calls (W8-W13), so
that library routines will not clobber it.
cannot inline function ‘main’
The function ‘main’ is declared with the inline attribute. This is not supported, since
main must be called from the C start-up code, which is compiled separately.
can’t inline call to ‘identifier’ called from here
The compiler was unable to inline the call to the specified function.
case value ‘n’ not in enumerated type
The controlling expression of a switch statement is an enumeration type, yet a case
expression has the value n, which does not correspond to any of the enumeration
values.
case value ‘value’ not in enumerated type ‘name’
‘value’ is an extra switch case that is not an element of the enumerated type ‘name’.
cast does not match function type
The return type of a function is cast to a type that does not match the function’s type.
cast from pointer to integer of different size
A pointer is cast to an integer that is not 16 bits wide.
cast increases required alignment of target type
When comp ili ng with the -Wcast-align command-line option, the compiler verifies
that casts do not increase the required alignment of the target type. For example, this
warning message will be given if a pointer to char is cast as a pointer to int, since the
aligned for char (byte alignment) is less than the alignment requirement for int (word
alignment).
character constant too long
Character constants must not be too long.
comma at end of enumerator list
Unnecessary comma at the end of the enumerator list.
comma operator in operand of #if
Not expecting a comma operator in the #if directive.
comp aring floating point with == or != is unsafe
Floating-point values can be approximations to infinitely precise real numbers. Instead
of testing for equality, use relational operators to see whether the two values have
ranges that overlap.
comparison between pointer and integer
A pointer type is being compared to an integer type.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 245
comparison between signed and unsigned
One of the operands of a comparison is signed, while the other is unsigned. The signed
operand will be treated as an unsigned value, which may not be correct.
comparison is always n
A comparison involves only constant expressions, so the compiler can evaluate the run
time result of the comparison. The result is always n.
comparison is always n due to width of bit-field
A comparison involving a bit-field always evaluates to n bec ause of the width of the
bit-field.
comparison is always false due to limited range of data type
A comparison will always evaluate to false at run time, due to the range of the data
types.
comparison is always true due to limited range of data type
A comparison will always evaluate to true at run time, due to the range of the data
types.
comparison of promoted ~unsigned with constant
One of the operands of a comparison is a promoted ~unsigned, while the other is a
constant.
comparison of promoted ~unsigned with unsigned
One of the operands of a comparison is a promoted ~unsigned, while the other is
unsigned.
comp arison of unsigned expression >= 0 is always true
A comparison expression compares an unsigned value with zero. Since unsigned
values cannot be less than zero, the comparison will always evaluate to true at run
time.
comp arison of unsigned expression < 0 is always false
A comparison expression compares an unsigned value with zero. Since unsigned
values cannot be less than zero, the comparison will always evaluate to false at run
time.
comparisons like X<=Y<=Z do not have their mathematical meaning
A C expression does not necessarily mean the same thing as the corresponding
mathematical expression. In particular , the C expression X<=Y<=Z is not equivalent to
the mathematical expression X Y Z.
conflicting types for built-in function ‘identifier’
The specified function has the same name as a built-in function but is declared with
conflicting types.
const declaration for ‘identifier’ follows non-const
The specified identifier was declared const after it was previously declared as
non-const.
control reaches end of non-void function
All exit paths from non-void function should return an appropriate value. The compiler
detected a case where a non-void function terminates, without an explicit return value.
Therefore, the return value might be unpredictable.
conversion lacks type at end of format
When checking the argument list of a call to printf, scanf, etc., the compiler found that
a format field in the format string lacked a type specifier.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 246 2012 Microchip Technology Inc.
concatenation of string literals with __FUNCTION__ is depre cated
__FUNCTION__ will be handled the same way as __func__ (which is de fined by the
ISO standard C99). __func__ is a variable, not a string literal, so it does not catenate
with other string literals.
conflicting types for ‘identifier’
The specified identifier has multiple, inconsistent declarations.
D
data definition has no type or storage class
A data definition was detected that lacked a type and storage class.
data qualifier ‘qualifier’ ignored
Data qualifiers, which include ‘access’, ‘shared’ and ‘overlay’, are not used in the com-
piler, but are there for compatibility with the MPLAB C Compiler for PIC18 MCUs.
declaration of ‘identifier’ has ‘extern’ and is initialized
Externs should not be initialized.
declaration of ‘identifier’ shadows a parameter
The specified identifier declaration shadows a parameter, making the parameter
inaccessible.
declaration of ‘identifier’ shadows a symbol from the parameter list
The specified identifier declaration shadows a symbol from the parameter list, making
the symbol inaccessible.
declaration of ‘identifier’ shadows global declaration
The specified identifier declaration shadows a global declaration, making the global
inaccessible.
‘identifier’ declared inline after being called
The specified function was declared inline after it was called.
‘identifier’ declared inline after its definition
The specified function was declared inline after it was defined.
‘identifier’ declared ‘static’ but never defined
The specified function was declared static, but was never defined.
decrement of read-only member ‘name’
The member ‘name’ was declared as const and cannot be modified by decrementing.
decrement of read-only variable ‘name’
‘name’ was declared as const and cannot be modified by decrementing.
‘identifier’ defined but not used
The specified function was defined, but was never used.
deprecated use of label at end of compound statement
A label should not be at the end of a statement. It should be followed by a statement.
dereferencing ‘void *’ pointer
It is not correct to dereference a ‘void *’ pointer. Cast it to a pointer of the appropriate
type before dereferencing the pointer.
division by zero
Compile-time division by zero has been detected.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 247
duplicate ‘const’
The ‘const’ qualifier should be applied to a declaration only once.
duplicate ‘res t rict’
The ‘restrict’ qualifier should be applied to a declaration only once.
duplicate ‘vo latile ’
The ‘volatile’ qualifier should be applied to a declaration only once.
E
embedded ‘\0’ in format
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the format string contains an embedded ‘\0’ (zero), which can cause early termination
of format string processing.
empty body in an else-statement
An else statement is empty.
empty body in an if-statement
An if statement is empt y.
empty declaration
The declaration contains no names to declare.
empty range sp ecified
The range of values in a case range is empty, that is, the value of the low expression
is greater than the value of the high expression. Recall that the syntax for case ranges
is case low ... high:.
‘enum identifier’ declared inside parameter list
The specified enum is declared inside a function parameter list. It is usually better
programming practice to declare enums outside parameter lists, since they can never
become complete types when defined inside parameter lists.
enum defined inside parms
An enum is defined inside a function parameter list.
enumeration value ‘identifier’ not handled in switch
The controlling expression of a switch statement is an enumeration type, yet not all
enumeration values have case expressions.
enumeration values exceed range of largest integer
Enumeration values are represented as integers. The compiler detected that an
enumeration range cannot be represented in any of the compiler integer formats,
includi ng the lar ge st such format.
excess elements in array initializer
There are more elements in the initializer list than the array was declared with.
excess elements in scalar initializer");
There should be only one initializer for a scalar variable.
excess elements in struct initializer
There are more elements in the initializer list than the structure was declared with.
excess element s in union initializer
There are more elements in the initializer list than the union was declared with.
extra semicolon in struct or union specifie d
The structure type or union type contains an extra semicolon.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 248 2012 Microchip Technology Inc.
extra tokens at end of #‘directive’ directive
The compiler detected extra text on the source line containing the #‘directive’ directive.
F
-ffunction-sections may affect debugging on some targets
You may have problems with debugging if you specify both the -g option and the
-ffunction-sections option.
first argument of ‘identifier’ should be ‘int’
Expecting declaration of first argument of specified identifier to be of type int.
floating constant exceeds range of ‘double’
A floating-point constant is too large or too small (in magnitude) to be represented as
a ‘double’.
floating constant exceeds range of ‘float’
A floating-point constant is too large or too small (in magnitude) to be represented as
a ‘float’.
floating constant exceeds range of ‘long double’
A floating-point constant is too large or too small (in magnitude) to be represented as
a ‘long double’.
floating point overflow in expression
When folding a floating-point constant expression, the compiler found that the
expression overflowed, that is, it could not be represented as float.
‘type1’ format, ‘type2’ arg (arg ‘num’)
The format is of type ‘type1’, but the argument being passed is of type ‘type2’.
The argument in question is the ‘num’ argument.
format argument is not a pointer (arg n)
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the specified argument number n was not a pointer , san the format specifier indicated
it should be.
format argument is not a pointer to a pointer (arg n)
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the specifi ed argument number n was not a pointer san the format specifier indicated
it should be.
fprefetch-loop-arrays not supported for this target
The option to generate instructions to prefetch memory is not supported for this target.
function call has aggregate value
The return value of a function is an aggregate.
function declaration isn’t a prototype
When compiling with the -Wstrict-prototypes command-line option, the compiler
ensures that function prototypes are specified for all functions. In this case, a function
definition was encountered without a preceding function prototype.
function declared ‘noreturn’ has a ‘return’ st atement
A function was declared with the noreturn attribute-indicating that the function does not
return-yet the function contains a return statement. This is inconsistent.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 249
function might be possible candidate for attribute ‘noreturn’
The compiler detected that the function does not return. If the function had been
declared with the ‘noreturn’ attribute, then the compiler might have been able to
generate better code.
function returns address of local variable
Functions should not return the addresses of local variables, since, when the function
returns, the local variables are de-allocated.
function returns an aggregate
The return value of a function is an aggregate.
function ‘name’ redeclared as inline
previous declaration of function ‘name’ with attribute noinline
Function ‘name’ was declared a second time with the keyword ‘inline’, which now
allows the function to be considered for inlining.
function ‘name’ redeclared with attribute noinline
previous declaration of function ‘name’ was inline
Function ‘name’ was declared a second time with the noinline attribute, which now
causes it to be ineligible for inlining.
function ‘identifier’ was previously declared within a block
The specified function has a previous explicit declaration within a block, yet it has an
implicit declaration on the current line.
G
GCC does not yet properly implement ‘[*]’ array declarators
Variable length arrays are not currently supported by the compiler.
H
hex escape sequence out of range
The hex sequence must be less than 100 in hex (256 in decimal).
I
ignoring asm-specifier for non-static local variable ‘identifier’
The asm-specifier is ignored when it is used with an ordinary, non-register local
variable.
ignoring invalid multibyte character
When parsing a multibyte character, the compiler determined that it was invalid. The
invalid character is ignored.
ignoring option ‘option’ due to invalid debug level specification
A debug option was used with a debug level that is not a valid debug level.
ignoring #pragma identifier
The specified pragma is not supported by the compiler, and is ignored.
imaginary constants are a GCC extention
ISO C does not allow imaginary numeric constants.
implicit declaration of function ‘identifier’
The specified function has no previous explicit declaration (definition or function
prototype), so the compiler makes assumptions about its return type and parameters.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 250 2012 Microchip Technology Inc.
increment of read-only member ‘name’
The member ‘name’ was declared as const and cannot be modified by incrementing.
increment of read-only variable ‘name’
‘name’ was declared as const and cannot be modified by incrementing.
initialization of a flexible array member
A flexible array member is intended to be dynamically allocated not statically.
‘identifier’ initialized and declared ‘extern’
Externs should not be initialized.
initializer element is not constant
Initializer elements should be constant.
inline function ‘name’ given attribute noinline
The function ‘name’ has been declared as inline, but the noinline attribute prevents the
function from being considered for inlining.
inlining failed in call to ‘identifier’ called from here
The compiler was unable to inline the call to the specified function.
integer constant is so large that it is unsigned
An integer constant value appears in the source code without an explicit unsigned
modifier , yet the number cannot be represented as a signed int; therefore, the compiler
automatically treats it as an unsigned int.
integer constant is too large for ‘type’ type
An integer constant should not exceed 2^32 - 1 for an unsigned long int, 2^63 - 1 for a
long long int or 2^64 - 1 for an unsigned long long int.
integer overflow in expr ession
When folding an integer constant expression, the compiler found that the expression
overflowed; that is, it could not be represented as an int.
invalid application of ‘sizeof’ to a function type
It is not recommended to apply the sizeof operator to a function type.
invalid application of ‘sizeof’ to a void type
The sizeof operator should not be applied to a void type.
invalid digit ‘digit’ in octal constant
All digits must be within the radix being used. For instance, only the digits 0 thru 7 may
be used for the octal radix.
invalid second arg to __builtin_prefetch; using zero
Second argument must be 0 or 1.
invalid storage class for function ‘name’
‘auto’ storage class should not be used on a function defined at the top level. ‘static’
storage class should not be used if the function is not defined at the top level.
invalid third arg to __builtin_prefetch; using zero
Third argument must be 0, 1, 2, or 3.
‘identifier’ is an unrecognized format function type
The specified identifier, used with the format attribute, is not one of the recognized
format function types printf, scanf, or strftime.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 251
‘identifier’ is narrower than values of its type
A bit-field member of a structure has for its type an enumeration, but the width of the
field is insufficient to represent all enumeration values.
‘storage class’ is not at beginning of declaration
The specified storage class is not at the beginning of the declaration. Storage classes
are required to come first in declarations.
ISO C does not allow extra ‘;’ outside of a function
An extra ‘;’ was found outside a function. This is not allowed by ISO C.
ISO C does not support ‘++’ and ‘--’ on complex types
The increment operator and the decrement operator are not supported on complex
types in ISO C.
ISO C does not support ‘~’ for complex conjugation
The bitwise negation operator cannot be use for complex conjugation in ISO C.
ISO C does not support complex integer types
Complex integer types, such as __complex__ short int, are not supported in ISO C.
ISO C does not support plain ‘complex’ meaning ‘double complex’
Using __complex__ without another modifier is equivalent to ‘complex double’ which
is not supported in ISO C.
ISO C does not support the ‘char’ ‘kind of format’ format
ISO C does not support the specification character ‘char’ for the specified ‘kind of
format’.
ISO C doesn’t support unnamed structs/unions
All structures and/or unions must be named in ISO C.
ISO C forbids an empty source file
The file contains no functions or data. This is not allowed in ISO C.
ISO C forbids empty initializer braces
ISO C expects initializer values inside the braces.
ISO C forbids nested functions
A function has been defined inside another function.
ISO C forbids omitting the middle term of a ?: expression
The conditional expression requires the middle term or expression between the ‘?’ and
the ‘:’.
ISO C forbids qualified void function return type
A qualifier may not be used with a void function return type.
ISO C forbids range expressions in switch statements
S pecifying a range of consecutive values in a single case label is not allowed in ISO C.
ISO C forbids subscripting ‘register’ array
Subscripting a ‘register’ array is not allowed in ISO C.
ISO C forbids taking the address of a label
Taking the address of a label is not allowed in ISO C.
ISO C forbids zero-size array ‘name’
The array size of ‘name’ must be larger than zero.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 252 2012 Microchip Technology Inc.
ISO C restricts enumerator values to range of ‘int’
The range of enumerator values must not exceed the range of the int type.
ISO C89 forbids compound literals
Compound literals are not valid in ISO C89.
ISO C89 forbids mixed declarations and code
Declarations should be done first before any code is written. It should not be mixed in
with the code.
ISO C90 does not suppo rt ‘[*]’ array declarators
Variable length arrays are not supported in ISO C90.
ISO C90 does not suppo rt complex types
Complex types, such as __complex__ float x, are not supported in ISO C90.
ISO C90 does not support flexible array members
A flexible array member is a new feature in C99. ISO C90 does not support it.
ISO C90 does not support ‘long long’
The long long type is not supported in ISO C90.
ISO C90 does not support ‘static’ or type qualifiers in parameter array
declarators
When using an array as a parameter to a function, ISO C90 does not allow the array
declarator to use ‘static’ or type qualifiers.
ISO C90 does not support the ‘char’ ‘function’ format
ISO C does not support the specification character ‘char’ for the specified function
format.
ISO C90 does not support the ‘modifier’ ‘function’ length modifier
The specified modifier is not supported as a length modifier for the given function.
ISO C90 forbids variable-size array ‘name’
In ISO C90, the number of elements in the array must be specified by an integer
constant expr essi on.
L
label ‘identifier’ defined but not used
The specified label was defined, but not referenced.
large integer implicitly truncated to unsigned type
An integer constant value appears in the source code without an explicit unsigned
modifier , yet the number cannot be represented as a signed int; therefore, the compiler
automatically treats it as an unsigned int.
left-hand operand of comma expression has no effect
One of the operands of a comparison is a promoted ~unsigned, while the other is
unsigned.
left shift count >= width of type
Shift counts should be less than the number of bits in the type being shifted. Otherwise,
the shift is meaningless, and the result is undefined.
left shift count is negative
Shift counts should be positive. A negative left shift count does not mean shift right;
it is meaningl es s.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 253
library function ‘identifier’ declared as non-function
The specified function has the same name as a library function, yet is declared as
something other than a function.
line number out of range
The limit for the line number for a #line directive in C89 is 32767 and in C99 is
2147483647.
‘identifier’ locally external but globally static
The specified identifier is locally external but globally static. This is suspect.
location qualifier ‘qualifier’ ignored
Location qualifiers, which include ‘grp’ and ‘sfr’, are not used in the compiler, but are
there for compatibility with MPLAB C Compiler for PIC18 MCUs.
‘long’ switch expression not converted to ‘int’ in ISO C
ISO C does not convert ‘long’ switch expr ess io ns to ‘int’.
M
‘main’ is usually a function
The identifier main is usually used for the name of the main entry point of an
application. The compiler detected that it was being used in some other way, for
example, as the name of a variable.
‘operation’ makes integer from pointer without a cast
A pointer has been implicitly converted to an integer.
‘operation’ makes pointer from integer without a cast
An integer has been implicitly converted to a pointer.
malformed ‘#pragma pack-ignored’
The syntax of the pack pragma is incorrect.
malformed ‘#pragma pack(pop[,id])-ignored’
The syntax of the pack pragma is incorrect.
malformed ‘#pragma pack(push[,id],<n>)-ignored’
The syntax of the pack pragma is incorrect.
malformed ‘#pragma weak-ignor ed’
The syntax of the weak pragma is incorrect.
‘identifier’ might be used uninitialized in this function
The compiler detected a control path though a function which might use the specified
identifier before it has been initialized.
missing braces around initializer
A required set of braces around an initializer is missing.
missing initializer
An initializer is missing.
modification by ‘asm’ of read-only variable ‘identifier’
A const variable is the left-hand-side of an assignment in an ‘asm’ statement.
multi-character character constant
A character constant contains more than one character.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 254 2012 Microchip Technology Inc.
N
negative integer implicitly converted to unsigned type
A negative integer constant value appears in the source code, but the number cannot
be represented as a signed int; therefore, the compiler automatically treats it as an
unsigned int.
nested extern declaration of ‘identifier’
There are nested extern definitions of the specified identifier.
no newline at end of file
The last line of the source file is not terminated with a newline character.
no previous declaration for ‘identifier’
When comp ili ng with the -Wmissing-declarations command-line option, the
compiler ensures that functions are declared before they are defined. In this case, a
function definition was encountered without a preceding function declaration.
no previous prototype for ‘identifier’
When comp ili ng with the -Wmissing-prototypes command-line option, the
compiler ensures that function prototypes are specified for all functions. In this case, a
function definition was encountered without a preceding function prototype.
no semicolon at end of struct or union
A semicolon is missing at the end of the structure or union declaration.
non-ISO-standard escape sequence, ‘seq’
‘seq’ is ‘\e’ or ‘\E’ and is an extension to the ISO standard. The sequence can be used
in a string or character constant and stands for the ASCII character <ESC>.
non-static declaration for ‘identifier’ follows static
The specified identifier was declared non-static after it was previously declared as
static.
‘noreturn’ function does return
A function declared with the noreturn attribute returns. This is inconsistent.
‘noreturn’ function returns non-void value
A function declared with the noreturn attribute returns a non-void value. This is
inconsistent.
null format string
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the format string was missing.
O
octal escape sequence out of range
The octal sequence must be less than 400 in octal (256 in decimal).
output constraint ‘constraint’ for operand n is not at the beginning
Output constraints in extended asm should be at the beginning.
overflow i n constant expressi on
The constant expression has exceeded the range of representable values for its type.
overflow in implicit constant conversion
An implicit constant conversion resulted in a number that cannot be represented as a
signed int; therefore, the compiler automatically treats it as an unsigned int.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 255
P
parameter has incomplete type
A function parameter has an incomplete type.
parameter names (without types) in function declaration
The function declaration lists the names of the parameters but not their types.
parameter points to incomplete type
A function parameter points to an incomplete type.
parameter ‘identifier’ points to incomplete type
The specified function parameter points to an incomplete type.
p assing arg ‘number’ of ‘name’ as complex rather than floating due to prototype
The prototype declares argument ‘number’ as a complex, but a float value is used so
the compiler converts to a complex to agree with the prototype.
passing arg ‘number’ of ‘name’ as complex rather than integer due to prototype
The prototype declares argument ‘number’ as a complex, but an integer value is used
so the compiler converts to a complex to agree with the prototype.
p assing arg ‘number’ of ‘name’ as floating rather than complex due to protot ype
The prototype declares argument ‘number’ as a f loat, but a complex value is used so
the compiler converts to a float to agree with the prototype.
passing arg ‘number’ of ‘name’ as ‘float’ rather than ‘double’ due to prototype
The prototype declares argument ‘number’ as a float, but a double value is used so the
compiler converts to a float to agree with the prototype.
passing arg ‘number’ of ‘name’ as floating rather than integer due to prototype
The prototype declares argument ‘number’ as a float, but an integer value is used so
the compiler converts to a float to agree with the prototype.
passing arg ‘number’ of ‘name’ as integer rather than complex due to prototype
The prototype declares argument ‘number’ as an in te ger, bu t a c omp lex val ue is us ed
so the compiler converts to an integer to agree with the prototype.
passing arg ‘number’ of ‘name’ as integer rather than floating due to prototype
The prototype declares argument ‘number’ as an integer, but a float value is used so
the compiler converts to an integer to agree with the prototype.
pointer of type ‘void *’ used in arithmetic
A pointer of type ‘void’ has no size and should not be used in arithmetic.
pointer to a function used in arithmetic
A pointer to a function should not be used in arithmetic.
previous declaration of ‘identifier’
This warning message appears in conjunction with another warning message. The
previous message identifies the location of the suspect code. This message identifies
the first declaration or definition of the identifier.
previous implicit declaration of ‘identifier’
This warning message appears in conjunction with the warning message “type
mismatch with previous implicit declaration”. It locates the implicit declaration of the
identifier that conflicts with the explicit declaration.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 256 2012 Microchip Technology Inc.
R
“name” reasserted
The answer for "name" has been duplicated.
“name” redefined
“name” was previously defined and is being redefined now.
redefinition of ‘identifier’
The specified identifier has multiple, incompatible definitions.
redundant redeclaration of ‘identifier’ in same scope
The specified identifier was re-declared in the same scope. This is redundant.
register used for two global register variables
Two global register variables have been defined to use the same register.
repeated ‘flag’ flag in format
When checking the argument list of a call to strftime, the compiler found that there was
a flag in the format string that is repeated.
When checking the argument list of a call to printf, scanf, etc., the compiler found that
one of the flags { ,+,#,0,-} was repeated in the format string.
return-type defaults to ‘int’
In the absence of an explicit function return-type declaration, the compiler assumes
that the function returns an int.
return type of ‘name’ is not ‘int’
The compiler is expecting the return type of ‘name’ to be ‘int’.
‘return’ with a value, in function returning void
The function was declared as void but returned a value.
‘return’ with no value, in function re turning non-void
A function declared to return a non-void value contains a return statement with no
value. This is inconsistent.
right shift count >= width of type
Shift counts should be less than the number of bits in the type being shifted. Otherwise,
the shift is meaningless, and the result is undefined.
right shift count is negative
Shift counts should be positive. A negative right shift count does not mean shift left; it
is meaningless.
S
second argument of ‘identifier’ should be ‘char **’
Expecting second argument of specified identifier to be of type ‘char **’.
second parameter of ‘va_start’ not last named argument
The second parameter of ‘va_start’ must be the last named argument.
shadowing built-in function ‘identifier’
The specified function has the same name as a built-in function, and consequently
shadows the bui lt- i n funct ion.
shadowing library function ‘identifier’
The specified function has the same name as a library function, and consequently
shado ws the libr ar y func tio n.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 257
shift count >= width of type
Shift counts should be less than the number of bits in the type being shifted. Otherwise,
the shift is meaningless, and the result is undefined.
shift count is negative
Shift counts should be positive. A negative left shift count does not mean shift right, nor
does a negative right shift count mean shift left; they are meaningless.
size of ‘name’ is larger than n bytes
Using -Wlarger-than-len will produce the above warning when the size of ‘name’
is larger than the len bytes define d.
size of ‘identifier’ is n bytes
The size of the specified identifier (which is n bytes) is larger than the size specified
with the -Wlarger-than-len command-line option.
size of return value of ‘name’ is larger than n bytes
Using -Wlarger-than-len will produce the above warning when the size of the
return value of ‘name’ is larger than the len bytes defined.
size of return value of ‘identifier’ is n bytes
The size of the return value of the specified function is n bytes, which is larger than the
size specified with the -Wlarger-than-len command-line option.
spurious trailing ‘%’ in format
When checking the argument list of a call to printf, scanf, etc., the compiler found that
there was a spurious trailing ‘%’ character in the format string.
statement with no effect
A statement has no effect.
static declaration for ‘identifier’ follows non-static
The specified identifier was declared static after it was previously declared as
non-static.
string lengt h ‘n’ is greater than the length ‘n’ ISO Cn compilers are required to
support
The maximum string length for ISO C89 is 509. The maximum string length for ISO C99
is 4095.
‘struct identifier’ declared inside parameter list
The specified struct is declared inside a function parameter list. It is usually better
programming practice to declare structs outside parameter lists, since they can never
become complete types when defined inside parameter lists.
struct has no members
The structure is empty, it has no members.
structure defined inside parms
A union is defined inside a function parameter list.
style of line directive is a GCC extension
Use the format ‘#line linenum’ for traditional C.
subscript has type ‘char’
An array subscript has type ‘char’.
suggest explicit braces to avoid ambiguous ‘else’
A nested if statement has an ambiguous else clause. It is recommended that braces be
used to remove the ambiguity.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 258 2012 Microchip Technology Inc.
suggest hiding #directive from traditional C with an indented #
The specified directive is not traditional C and may be ‘hidden’ by indenting the #.
A directive is ignored unless its # is in column 1.
suggest not using #elif in traditional C
#elif should not be used in traditional K&R C.
suggest parentheses around assignment used as truth value
When assignments are used as truth values, they should be surrounded by
parentheses, to make the intention clear to readers of the source program.
suggest parentheses around + or - inside shift
suggest parentheses around && within ||
suggest parentheses around arithmetic in operand of |
suggest parentheses around comparison in operand of |
suggest parentheses around arithmetic in operand of ^
suggest parentheses around comparison in operand of ^
suggest parentheses around + or - in operand of &
suggest parentheses around comparison in operand of &
While operator precedence is well defined in C, sometimes a reader of an expression
might be required to expend a few additional microseconds in comprehending the
evaluation order of operands in an expression if the reader has to rely solely upon the
precedence rules, without the aid of explicit parentheses. A case in point is the use of
the ‘+’ or ‘-’ operator inside a shift. Many readers will be spared unnecessary effort if
parentheses are use to clearly express the intent of the programmer , even though the
intent is unambiguous to the programmer and to the compiler.
T
‘identifier’ takes only zero or two arguments
Expecting zero or two arguments only.
the meaning of ‘\a’ is different in traditional C
When the -wtraditional option is used, the escape sequence ‘\a’ is not recognized
as a meta-sequence: its value is just ‘a’. In non-traditional compilation, ‘\a’ represents
the ASCII BEL character.
the meaning of ‘\x’ is different in traditional C
When the -wtraditional option is used, the escape sequence ‘\x’ is not recognized
as a meta-sequence: its value is just ‘x’. In non-traditional compilation, ‘\x’ introduces
a hexadecimal escape sequence.
third argument of ‘identifier’ should probably be ‘char **’
Expecting third argument of specified identifier to be of type ‘char **’.
this function may return with or without a value
All exit paths from non-void function should return an appropriate value. The compiler
detected a case where a non-void function terminates, sometimes with and sometimes
without an explicit return value. Therefore, the return value might be unpredictable.
this target machine does not have delayed branches
The -fdelayed-branch option is not supported.
too few arguments for format
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the number of actual arguments was fewer than that required by the format string.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 259
too many arguments for format
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the number of actual arguments was more than that required by the format string.
traditional C ignores #‘directive’ with the # indented
Traditionally, a directive is ignored unless its # is in column 1.
traditional C rejects initialization of unions
Unions cannot be initialized in traditional C.
traditional C rejects the ‘ul’ suffix
Suffix ‘u’ is not valid in traditional C.
traditional C rejects the unary plus operator
The unary plus operator is not valid in traditional C.
trigraph ??char converted to char
Trigraphs, which are a three-character sequence, can be used to represent symbols
that may be missing from the keyboard. Trigraph sequences convert as follows:
trigraph ??char ignored
Trigraph sequence is being ignored. char can be (, ), <, >, =, /, ', !, or -
type defaults to ‘int’ in declaration of ‘identifier’
In the absence of an explicit type declaration for the specified identifier, the compiler
assumes that its type is int.
type mismatch with previous external decl
previous external decl of ‘identifier’
The type of the specified identifier does not match the previous declaration.
type mismatch with previous implicit declaration
An explicit declaration conflicts with a previous implicit declaration.
type of ‘identifier’ defaults to ‘int’
In the absence of an explicit type declaration, the compiler assumes that identifier’s
type is int.
type qualifiers ignored on function return type
The type qualifier being used with the function return type is ignored.
U
undefining ‘defined’
‘defined’ cannot be used as a macro name and should not be undefined.
undefining ‘name’
The #undef directive was used on a previously defined macro name ‘name’.
union cannot be made transparent
The transparent_union attribute was applied to a union, but the specified variable
does not satisfy the requirements of that attribute.
‘union identifier’ declared inside parameter list
The specified union is declared inside a function parameter list. It is usually better
programming practice to declare unions outside parameter lists, since they can never
become complete types when defined inside parameter lists.
??( = [ ??) = ] ??< = { ??> = } ??= = # ??/ = \ ??' = ^ ??! = | ??- = ~
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 260 2012 Microchip Technology Inc.
union defined inside parms
A union is defined inside a function parameter list.
union has no members
The union is empty, it has no members.
unknown conversion type character ‘character’ in format
When checking the argument list of a call to printf, scanf, etc., the compiler found that
one of the conversion characters in the format string was invalid (unrecognized).
unknown conversion type character 0xnumber in format
When checking the argument list of a call to printf, scanf, etc., the compiler found that
one of the conversion characters in the format string was invalid (unrecognized).
unknown escape sequence ‘sequence’
‘sequence’ is not a valid escape code. An escape code must start with a ‘\’ and use
one of the following characters: n, t, b, r, f, b, \, ', ", a, or ?, or it must be a numeric
sequence in octal or hex. In octal, the numeric sequence must be less than 400 octal.
In hex, the numeric sequence must start with an ‘x’ and be less than 100 hex.
unnamed struct/union that defines no instances
struct/union is empty and has no name.
unreachable code at beginning of identifier
There is unreachable code at beginning of the specified function.
unrecognized gcc debugging option: char
The ‘char’ is not a valid letter for the -dletters debugging option.
unused parameter ‘identifier’
The specified function parameter is not used in the function.
unused variable ‘name’
The specified variable was declared but not used.
use of ‘*’ and ‘flag’ together in format
When checking the argument list of a call to printf, scanf, etc., the compiler found that
both the flags ‘*’ and ‘flag’ appear in the format string.
use of C99 long long integer constants
Integer constants are not allowed to be declared long long in ISO C89.
use of ‘length’ len g t h m o difier wi t h ‘type’ type ch aracter
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the specified length was incorrectly used with the specified type.
‘name’ used but never defined
The specified function was used but never defined.
‘name’ used with ‘spec’ ‘function’ format
‘name’ is not valid with the conversion specification ‘spec’ in the format of the specified
function.
useless keyword or type name in empty declaration
An empty declaration contains a useless keyword or type name.
Diagnostics
2012 Microchip Technology Inc. DS52071B-page 261
V
__VA_ARGS__ can only appear in the expansion of a C99 variadic macro
The predefined macro __VA_ARGS should be used in the substitution part of a macro
definition using ellipses.
value computed is not used
A value computed is not used.
variable ‘name’ declared ‘inline’
The keyword ‘inline’ should be used with functions only.
variable ‘%s’ might be clobbered by ‘longjmp’ or ‘vfork’
A non-volatile automatic variable might be changed by a call to longjmp. These
warnings are possible only in optimizing compilation.
volatile register variables don’t work as you might wish
Passing a variable as an argument could transfer the variable to a different register
(w0-w7) than the one specified (if not w0-w7) for argument transmission. Or the
compiler may issue an instruction that is not suitable for the specified register and may
need to temporarily move the value to another place. These are only issues if the
specified register is modified asynchronously (i.e., though an ISR).
W
-Wformat-extra-args ignored without -Wformat
-Wformat must be specified to use -Wformat-extra-args.
-Wformat-nonliteral ignored without -Wformat
-Wformat must be specified to use -Wformat-nonliteral.
-Wformat-security ignored without -Wformat
-Wformat must be specified to use -Wformat-security.
-Wformat-y2k ignored without -Wformat
-Wformat must be specified to use.
-Wid-clash-LEN is no longer supported
The option -Wid-clash-LEN is no longer supported.
-Wmissing-format-attribute ignored without -Wformat
-Wformat must be specified to use -Wmissing-format-attribute.
-Wuninitialized is not supported without -O
Optimization must be on to use the -Wuninitialized option.
‘identifier’ was declared ‘extern’ and later ‘static’
The specified identifier was previously declared ‘extern’ and is now be ing decl ared as
static.
‘identifier’ was declared implicitly ‘extern’ and later ‘static’
The specified identifier was previously declared impl icitly ‘extern’ and is now being
declared as static.
‘identifier’ was previously implicitly declared to return ‘int’
There is a mismatch against the previous implicit declaration.
‘identifier’ was used with no declaration before its definition
When compiling with the -Wmissing-declarations command-line option, the
compiler ensures that functions are declared before they are defined. In this case, a
function definition was encountered without a preceding function declaration.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 262 2012 Microchip Technology Inc.
‘identifier’ was used with no prototype before its definition
When comp ili ng with the -Wmissing-prototypes command-line option, the
compiler ensures that function prototypes are specified for all functions. In this case, a
function call was encountered without a preceding function prototype for the called
function.
writing into constant object (arg n)
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the specified argument number n was a const object that the format specifier indicated
should be written into.
Z
zero-length identifier format string
When checking the argument list of a call to printf, scanf, etc., the compiler found that
the format string was empty (“ ”).
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 263
Appendix C. GNU Free Documentation License
GNU Free Documentation License
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
<http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies of this license document,
but changing it is not allowed.
C.1 PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and use-
ful document “free” in the sense of freedom: to assure everyone the effective freedom
to copy and redistribute it, with or without modifying it, either commercially or noncom-
mercially . Secondarily , this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for modifications made by
others.
This License is a kind of “copyleft”, which means that derivative works of the document
must themselves be free in the same sense. It complements the GNU General Public
License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because
free software needs free documentation: a free program should come with manuals
providing the same freedoms that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License principally for
works whose purpose is instruction or reference.
C.2 APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice
placed by the copyright holder saying it can be distributed under the terms of this
License. Such a notice grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The “Document”, below, refers to
any such manual or work. Any member of the public is a licensee, and is addressed as
“you”. You accept the license if you copy, modify or distribute the work in a way requir-
ing permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a
portion of it, either copied verbatim, or with modifications and/or translated into another
language.
A “Secondary Section” is a named appendix or a front-matter section of the Document
that deals exclusively with the relationship of the publishers or authors of the Document
to the Document's overall subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document is in part a textbook of
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 264 2012 Microchip Technology Inc.
mathematics, a Secondary Section may not explain any mathematics.) The relation-
ship could be a matter of historical connection with the subject or with related matters,
or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated,
as being those of Invariant Sections, in the notice that says that the Document is
released under this License. If a section does not fit the above definition of Secondary
then it is not allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant Sections then there
are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover
Texts or Back-Cover Texts, in the notice that says that the Document is released under
this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented
in a format whose specification is available to the general public, that is suitable for
revising the document straightforwardly with generic text editors or (for images com-
posed of pixels) generic paint programs or (for drawings) some widely available draw-
ing editor , and that is suitable for input to text formatters or for automatic translation to
a variety of formats suitable for input to text formatters. A copy made in an otherwise
Transparent file format whose markup, or absence of markup, has been arranged to
thwart or discourage subsequent modification by readers is not T ransparent. An image
format is not Transparent if used for any substantial amount of text. A copy that is not
“Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without
markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly avail-
able DTD, and standard-conforming simple HTML, PostScript or PDF designed for
human modification. Examples of transparent image formats include PNG, XCF and
JPG. Opaque formats include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or processing tools
are not generally available, and the machine-generated HTML, PostScript or PDF pro-
duced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following
pages as are needed to hold, legibly , the material this License requires to appear in the
title page. For works in formats which do not have any title page as such, “Title Page”
means the text near the most prominent appearance of the work's title, preceding the
beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to
the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is
precisely XYZ or contains XYZ in parentheses following text that translates XYZ in
another language. (Here XYZ stands for a specific section name mentioned below,
such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Pre-
serve the Title” of such a section when you modify the Document means that it remains
a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that
this License applies to the Document. These Warranty Disclaimers are considered to
be included by reference in this License, but only as regards disclaiming warranties:
any other implication that these Warranty Disclaimers may have is void and has no
effect on the meaning of this License.
GNU Free Documentation License
2012 Microchip Technology Inc. DS52071B-page 265
C.3 VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or non-
commercially, provided that this License, the copyright notices, and the license notice
saying this License applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. Y ou may not use technical
measures to obstruct or control the reading or further copying of the copies you make
or distribute. However, you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow the conditions in sec-
tion 3.
You may also lend copies, under the same conditions stated above, and you may pub-
licly display copies.
C.4 COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of
the Document, numbering more than 100, and the Document's license notice requires
Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover , and Back-Cover Texts on the
back cover. Both covers must also clearly and legibly identify you as the publisher of
these copies. The front cover must present the full title with all words of the title equally
prominent and visible. You may add other material on the covers in addition. Copying
with changes limited to the covers, as long as they preserve the title of the Document
and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly , you should put the
first ones listed (as many as fit reasonably) on the actual cover, and continue the rest
onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100,
you must either include a machine-readable Transparent copy along with each Opaque
copy , or state in or with each Opaque copy a computer-network location from which the
general network-using public has access to download using public-standard network
protocols a complete Transparent copy of the Document, free of added material. If you
use the latter option, you must take reasonably prudent steps, when you begin distri-
bution of Opaque copies in quantity, to ensure that this Transparent copy will remain
thus accessible at the stated location until at least one year after the last time you dis-
tribute an Opaque copy (directly or through your agents or retailers) of that edition to
the public.
It is requested, but not required, that you contact the authors of the Document well
before redistributing any large number of copies, to give them a chance to provide you
with an updated version of the Document.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 266 2012 Microchip Technology Inc.
C.5 MODIFICATIONS
You may copy and distribute a Modified V ersion of the Document under the conditions
of sections 2 and 3 above, provided that you release the Modified Version under pre-
cisely this License, with the Modified Version filling the role of the Document, thus
licensing distribution and modification of the Modified V ersion to whoever possesses a
copy of it. In addition, you must do these things in the Modified Version:
a) Use in the Title Page (and on the covers, if any) a title distinct from that of the
Document, and from those of previous versions (which should, if there were any ,
be listed in the History section of the Document). You may use the same title as
a previous version if the original publisher of that version gives permission.
b) List on the Title Page, as authors, one or more persons or entities responsible for
authorship of the modifications in the Modified Version, together with at least five
of the principal authors of the Document (all of its principal authors, if it has fewer
than five), unless they release you from this requirement.
c) State on the T itle page the name of the publisher of the Modified V ersion, as the
publisher.
d) Preserve all the copyright notices of the Document.
e) Add an appropriate copyright notice for your modifications adjacent to the other
copyright notices.
f) Include, immediately after the copyright notices, a license notice giving the public
permission to use the Modified Version under the terms of this License, in the
form shown in the Addendum below.
g) Preserve in that license notice the full lists of Invariant Sections and required
Cover Texts given in the Documen t's lic ense notice.
h) Include an unaltered copy of this License.
i) Preserve the section Entitled “History”, Preserve its Title, and add to it an item
stating at least the title, year , new authors, and publisher of the Modified V ersion
as given on the Title Page. If there is no section Entitled “History” in the Docu-
ment, create one stating the title, year, authors, and publisher of the Document
as given on its Title Page, then add an item describing the Modified Version as
stated in the previou s sen ten ce.
j) Preserve the network location, if any , given in the Document for public access to
a Transparent copy of the Document, and likewise the network locations given in
the Document for previous versions it was based on. These may be placed in the
“History” section. You may omit a network location for a work that was published
at least four years before the Document itself, or if the original publisher of the
version it refers to gives permission.
k) For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title
of the section, and preserve in the section all the substance and tone of each of
the contributor acknowledgements and/or dedications given therein.
l) Preserve all the Invariant Sections of the Document, unaltered in their text and
in their titles. Section numbers or the equivalent are not considered part of the
section titles.
m) Delete any section Entitled “Endorsements”. Such a section may not be included
in the Modified Version.
n) Do not retitle any existing section to be Entitled “Endorsements” or to conflict in
title with any Invariant Section. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as
Secondary Sections and contain no material copied from the Document, you may at
your option designate some or all of these sections as invariant. To do this, add their
titles to the list of Invariant Sections in the Modified Version's license notice. These titles
must be distinct from any other section titles.
GNU Free Documentation License
2012 Microchip Technology Inc. DS52071B-page 267
You may add a section Entitled “Endorsements”, provided it contains nothing but
endorsements of your Modified V ersion by various parties--for example, statements of
peer review or that the text has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of
up to 25 words as a Back-Cover Text, to the end of the list of Cover T exts in the Modified
Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or by arrangement
made by the same entity you are acting on behalf of, you may not add another; but you
may replace the old one, on explicit permission from the previous publisher that added
the old one.
The author(s) and publisher(s) of the Document do not by this License give permission
to use their names for publicity for or to assert or imply endorsement of any Modified
Version.
C.6 COMBINING DOCUMENTS
You may combine the Document with other documents released under this License,
under the terms defined in section 4 above for modified versions, provided that you
include in the combination all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your combined work in its license
notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical
Invariant Sections may be replaced with a single copy. If there are multiple Invariant
Sections with the same name but different contents, make the title of each such section
unique by adding at the end of it, in parentheses, the name of the original author or pub-
lisher of that section if known, or else a unique number. Make the same adjustment to
the section titles in the list of Invariant Sections in the license notice of the combined
work.
In the combination, you must combine any sections Entitled “History” in the various
original documents, forming one section Entitled “History”; likewise combine any sec-
tion s En tit led “Ack now led geme nt s”, an d any sect ion s En titl ed “ Ded ica tio ns”. You m ust
delete all sections Entitled “Endorsements”.
C.7 COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released
under this License, and replace the individual copies of this License in the various doc-
uments with a single copy that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually
under this License, provided you insert a copy of this License into the extracted docu-
ment, and follow this License in all other respects regarding verbatim copying of that
document.
C.8 AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent
documents or works, in or on a volume of a storage or distribution medium, is called an
“aggregate” if the copyright resulting from the compilation is not used to limit the legal
rights of the compilation's users beyond what the individual works permit. When the
Document is included in an aggregate, this License does not apply to the other works
in the aggregate which are not themselves derivative works of the Document.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 268 2012 Microchip Technology Inc.
If the Cover Text requirement of section 3 is applicable to these copies of the Docu-
ment, then if the Document is less than one half of the entire aggregate, the Docu-
ment's Cover Texts may be placed on covers that bracket the Document within the
aggregate, or the electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole aggregate.
C.9 TRANSLATION
Translation is considered a kind of modifi cation, so you may distribute translations of
the Document under the terms of section 4. Replacing Invariant Sections with transla-
tions requires special permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the original versions of these
Invariant Sections. You may include a translation of this License, and all the license
notices in the Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions of those notices
and disclaimers. In case of a disagreement between the translation and the original
version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “His-
tory”, the requirement (section 4) to Preserve its Title (section 1) will typically require
changing the actual title.
C.10 TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly
provided under this License. Any attempt otherwise to copy, modify, sublicense, or dis-
tribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular
copyright holder is reinstated (a) provisionally, unless and until the copyright holder
explicitly and finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means prior to 60 days
after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if
the copyright holder notifies you of the violation by some reasonable means, this is the
first time you have received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after your receipt of the
notice.
Termination of your rights under this section does not terminate the licenses of parties
who have received copies or rights from you under this License. If your rights have
been terminated and not permanently reinstated, receipt of a copy of some or all of the
same material does not give you any rights to use it.
C.11 FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free
Documentation License from time to time. Such new versions will be similar in spirit to
the present version, but may differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number . If the Document
specifies that a particular numbered version of this License “or any later version”
applies to it, you have the option of following the terms and conditions either of that
specified version or of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version number of this
License, you may choose any version ever published (not as a draft) by the Free Soft-
GNU Free Documentation License
2012 Microchip Technology Inc. DS52071B-page 269
ware Foundation. If the Document specifies that a proxy can decide which future ver-
sions of this License can be used, that proxy's public statement of acceptance of a
version permanently authorizes you to choose that version for the Document.
C.12 RELICENSING
“Massive Multi-author Collaboration Site” (or “MMC Site”) means any World Wide Web
server that publishes copyrightable works and also provides prominent facilities for
anybody to edit those works. A public wiki that anybody can edit is an example of such
a server. A “Massive Multi-author Collaboration” (or “MMC”) contained in the site
means any set of copyrightable works thus published on the MMC site.
“CC- BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license pub-
lished by Creative Commons Corporation, a not-for-profit corporation with a principal
place of business in San Francisco, California, as well as future copyleft versions of that
license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of
an other Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works
that were first published under this License somewhere other than this MMC, and sub-
sequently incorporated in whole or in part into the MMC, (1) had no cover texts or invari-
ant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under
CC-BY-SA on the same site at any time before August 1, 2009,provided the MMC is
eligible for relicensing.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 270 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 271
Appendix D. ASCII Character Set
TABLE D-1: ASCII CHARACTER SET
Mo st Si gnificant Character
Least
Significant
Character
Hex01 2 34567
0NUL DLE Space 0 @ P ‘ p
1SOH DC1 ! 1 A Q a q
2STX DC2 " 2 B R b r
3ETX DC3 # 3 C S c s
4EOT DC4 $ 4 D T d t
5ENQ NAK % 5 E U e u
6ACK SYN & 6 F V f v
7Bell ETB ’ 7 G W g w
8BS CAN ( 8 H X h x
9HT EM ) 9 I Y i y
ALF SUB * : J Z j z
BVT ESC + ; K [ k {
CFF FS , < L \ l |
DCR GS - = M ] m }
ESO RS . > N ^ n ~
FSI US / ? O _ o DEL
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 272 2012 Microchip Technology Inc.
NOTES:
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 273
Append ix E. Dep recated Features
E.1 INTRODUCTION
The features described below are considered to be obsolete and have been replaced
with more advanced functionality. Projects which depend on deprecated features will
work properly with versions of the language tools cited. The use of a deprecated
feature will result in a warning; programmers are encouraged to revise their projects in
order to eliminate any dependency on deprecated features. Support for these features
may be removed entirely in future versions of the language tools.
Deprecated features covered are:
• Predefined Constants
• Variables in Specified Registers
• Changing Non-Auto Variable Allocation
E.2 PREDEFINED CONSTANTS
The following preprocessing symbols are defined by the compiler.
The ELF-specific version of the compiler defines the following preprocessing symbols.
The COFF-specific version of the compiler defines the following preprocessing
symbols.
For the most current information, see Section 16.4 “Predefined Macro Names”.
Symbol Defined with -ansi command-line option?
dsPIC30 No
__dsPIC30 Yes
__dsPIC30__ Yes
Symbol Defined with -ansi command-line option?
dsPIC30ELF No
__dsPIC30ELF Yes
__dsPIC30ELF__ Yes
Symbol Defined with -ansi command-line option?
dsPIC30COFF No
__dsPIC30COFF Yes
__dsPIC30COFF__ Yes
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 274 2012 Microchip Technology Inc.
E.3 VARIABLES IN SPECIFIED REGISTERS
The compiler allows you to put a few global variables into specified hardware registers.
You can also specify the register in which an ordinary register variable should be
allocated.
• Global register variables reserve registers throughout the program. This may be
useful in programs such as programming language interpreters which have a
couple of global variables that are accessed very often.
• Local register variables in specific registers do not reserve the registers. The
compiler’s data flow analysis is capable of determining where the specified
registers contain live values, and where they are available for other uses. Stores
into local register variables may be deleted when they appear to be unused.
References to local register variables may be deleted, moved or simplified.
These local variables are sometimes convenient for use with the extended inline
assembly (see Chapter 13. “Mixing C and Assembly Code”), if you want to write one
output of the assembler instruction directly into a particular register . (This will work pro-
vided the register you specify fits the constraints specified for that operand in the inline
assembly statement).
E.3.1 Defining Global Register Variables
You can define a global register variable like this:
register int *foo asm ("w8");
Here w8 is the name of the register which should be used. Choose a register that is
normally saved and restored by function calls (W8-W13), so that library routines will not
clobber it.
Defining a global register variable in a certain register reserves that register entirely for
this use, at least within the current compilation. The register will not be allocated for any
other purpose in the functions in the current compilation. The register will not be saved
and restored by these functions. S tores into this register are never deleted even if they
would appear to be dead, but references may be deleted, moved or simplified.
It is not safe to access the global register variables from signal handlers, or from more
than one thread of control, because the system library routines may temporarily use the
register for other things (unless you recompile them especially for the task at hand).
It is not safe for one function that uses a global register variable to call another such
function foo by way of a third function lose that was compiled without knowledge of
this variable (i.e., in a source file in which the variable wasn’t declared). This is because
lose might save the register and put some other value there. For example, you can’t
expect a global register variable to be available in the comparison-function that you
pass to qsort, since qsort might have put something else in that register. This
problem can be avoided by recompiling qsort with the same global register variable
definition.
If you want to recompile qsort or other source files that do not actually use your global
register variable, so that they will not use that register for any other purpose, then it
suffices to specify the compiler command-line option -ffixed-reg. You need not
actually add a global register declaration to their source code.
Note: Using too many registers, in particular register W0, may impair the ability of
the 16-bit compiler to compile. It is not recommended that registers be
placed into fixed registers.
Deprecated F eatures
2012 Microchip Technology Inc. DS52071B-page 275
A function that can alter the value of a global register variable cannot safely be called
from a function compiled without this variable, because it could clobber the value the
caller expects to find there on return. Therefore, the function that is the entry point into
the part of the program that uses the global register variable must explicitly save and
restore the value that belongs to its caller.
The library function longjmp will restore to each global register variable the value it
had at the time of the setjmp.
All global register variable declarations must precede all function definitions. If such a
declaration appears after function definitions, the register may be used for other
purposes in the preceding functions.
Global register variables may not have initial values, because an executable file has no
means to supply initial content s for a register.
E.3.2 Specifying Registers for Local Variables
You can define a local register variable with a specified register like this:
register int *foo asm ("w8");
Here w8 is the name of the register that should be used. Note that this is the same
syntax used for defining global register variables, but for a local variable it would appear
within a function.
Defining such a register variable does not reserve the register; it remains available for
other uses in places where flow control determines the variable’s value is not live.
Using this feature may leave the compiler too few available registers to compile certain
functions.
This option does not ensure that the compiler will generate code that has this variable
in the register you specify at all times. You may not code an explicit reference to this
register in an asm statement and assume it will always refer to this variable.
Assignments to local register variables may be deleted when they appear to be
unused. References to local register variables may be deleted, moved or simplified.
E.4 CHANGING NON-AUTO VARIABLE ALLOCATION
Another way to locate data is by placing the variable into a user-defined section, and
specifying the starting address of that section in a custom linker script. This is done as
follows:
1. Modify the data declaration in the C source to specify a user-defined section.
2. Add the user-defined section to a custom linker script file to specify the starting
address of the section.
For example, to locate the variable Mabonga at address 0x1000 in data memory, first
declare the variable as follows in the C source:
int __attribute__((__section__(".myDataSection"))) Mabonga =
1;
The section attribute specifies that the variable should be placed in a section
named.myDataSection, rather than the default .data section. It does not specify
where the user-defined section is to be located. Again, that must be done in a custom
linker script, as follows. Using the device-specific linker script as a base, add the fol-
lowing section definition:
.myDataSection 0x1000 :
{
*(.myDataSection);
} >data
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 276 2012 Microchip Technology Inc.
This specifies that the output file should contain a section named.myDataSection
starting at location 0x1000 and containing all input sections named.myDataSection.
Since, in this example, there is a single variable Mabonga in that section, then the
variable will be located at address 0x1000 in data memory.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 277
Appendix F. Built-in Functions
F.1 INTRODUCTION
This appendix lists the built-in functions that are specific to MPLAB XC16 C Compiler.
Built-in functions give the C programmer access to assembler operators or machine
instructions that are currently only accessible using inline assembly , but are sufficiently
useful that they are applicable to a broad range of applications. Built-in functions are
coded in C source files syntactically like function calls, but they are compiled to
assembly code that directly implements the function, and do not involve function calls
or library routines.
There are a number of reasons why providing built-in functions is preferable to
requiring programmers to use inline assembly. They include the following:
1. Providing built-in functions for specific purposes simplifies coding.
2. Certain optimizations are disabled when inline assembly is used. This is not the
case for built-in functions.
3. For machine instructions that use dedicated registers, coding inline assembly
while avoiding register allocation errors can require considerable care. The
built-in functions make this process simpler as you do not need to be concerned
with the particular register requirements for each individual machine instruction.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 278 2012 Microchip Technology Inc.
Built-In Function List
__builtin_addab __builtin_mulss
__builtin_add __builtin_mulsu
__builtin_btg __builtin_mulus
__builtin_clr __builtin_muluu
__builtin_clr_prefetch __builtin_nop
__builtin_write_CRYOTP __builtin_psvpage
__builtin_disi __builtin_psvoffset
__builtin_divf __builtin_readsfr
__builtin_divmodsd __builtin_return_address
__builtin_divmodud __builtin_sac
__builtin_divsd __builtin_sacr
__builtin_divud __builtin_sftac
__builtin_dmapage __builtin_subab
__builtin_dmaoffset __builtin_tbladdress
__builtin_ed __builtin_tblpage
__builtin_edac __builtin_tbloffset
__builtin_edspage __builtin_tblrdh
__builtin_edsoffset __builtin_tblrdl
__builtin_fbcl __builtin_tblwth
__builtin_lac __builtin_tblwtl
__builtin_mac __builtin_write_NVM
__builtin_modsd __builtin_write_NVM_secure
__builtin_modud __builtin_write_PWMSFR
__builtin_movsac __builtin_write_RTCWEN
__builtin_mpy __builtin_write_OSCCONL
__builtin_mpyn __builtin_write_OSCCONH
__builtin_msc
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 279
F.2 BUILT-IN FUNCTION DESCRIPTIONS
This section describes the programmer interface to the compiler built-in functions. Since the functions are
“built in”, there are no header files associated with them. Similarly, there are no command-line switches
associated with the built-in functions – they are always available. The built-in function names are chosen
such that they belong to the compiler’s namespace (they all have the prefix __builtin_), so they will not
conflict with function or variable names in the programmer’s namespace.
__builtin_addab
Description: Add accumulators A and B with the result written back to the specified accumulator. For
example:
volatile register int result asm("A");
volatile register int B asm("A");
result = __builtin_addab(result,B);
will generate:
add A
Prototype: int __builtin_addab(int Accum_a, int Accum_b);
Argument: Accum_a First accumulator to add.
Accum_b Second accumulator to add.
Return Value: Returns the addition result to an accumulator.
Assembler Operator/
Machine Instruction: add
Error Messages An error message will be displayed if the result is not an accumulator register.
__builtin_add
Description: Add value to the accumu lator sp ecifie d by result with a shift s pecifi ed by lit eral shif t. For
example:
volatile register int result asm("A");
int value;
result = __builtin_add(result,value,0);
If value is held in w0, the following will be generated:
add w0, #0, A
Prototype: int __builtin_add(int Accum,int value,
const int shift);
Argument: Accum Accumulator to add.
value Integer number to add to accumulator value.
shift Amount to shif t res ult ant accumul ato r value .
Return Value: Returns the shifted addition result to an accumulator.
Assembler Operator/
Machine Instruction: add
Error Messages An error message will be displayed if:
• the result is not an accumulator register
• argument 0 is not an accumulator
• the shift value is not a literal within range
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 280 2012 Microchip Technology Inc.
__builtin_btg
Description: This function will generate a btg machine instruction.
Some examples include:
int i; /* near by default */
int l __attribute__((far));
struct foo {
int bit1:1;
} barbits;
int bar;
void some_bittoggles() {
register int j asm("w9");
int k;
k = i;
__builtin_btg(&i,1);
__builtin_btg(&j,3);
__builtin_btg(&k,4);
__builtin_btg(&l,11);
return j+k;
}
Note that t ak in g the add res s of a variable in a regist er will pro duc e w arni ng by the co mpi le r
and cause the register to be saved onto the stack (so that its address may be taken); this
form is not reco mmended. Thi s caution only ap plies to variables ex plicitly pla ced in registers
by the programmer.
Prototype: void __builtin_btg(unsigned int *, unsigned int 0xn);
Argument: *A pointer to the data item for which a bit should be toggled.
0xnA literal value in the range of 0 to 15.
Return Value: Returns a btg machine instruction.
Assembler Operator/
Machine Instruction: btg
Error Messages An error message will be displayed if the parameter values are not within range
__builtin_clr
Description: Clear the specified accumulator. For example:
volatile register int result asm("A");
result = __builtin_clr();
will generate:
clr A
Prototype: int __builtin_clr(void);
Argument: None
Return Value: Returns the cleared value result to an accumulator.
Assembler Operator/
Machine Instruction: clr
Error Messages An error message will be displayed if the result is not an accumulator register.
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 281
__builtin_clr_prefetch
Description: Clear an accumulator and prefetch data ready for a future MAC operation.
xptr may be null to signify no X prefetch to be performed, in which case the values of
xincr and xval are ignored, but required.
yptr may be null to signify no Y prefetch to be performed, in which case the values of
yincr and yval are ignored, but required.
xval and yval nominate the address of a C variable where the prefetched value will be
stored.
xincr and yincr may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value.
If AWB is non null, the other accumulator will be written back into the referenced variable.
For example:
volatile register int result asm("A");
volatile register int B asm("B");
int x_memory_buffer[256]
__attribute__((space(xmemory)));
int y_memory_buffer[256]
__attribute__((space(ymemory)));
int *xmemory;
int *ymemory;
int awb;
int xVal, yVal;
xmemory = x_memory_buffer;
ymemory = y_memory_buffer;
result = __builtin_clr(&xmemory, &xVal, 2,
&ymemory, &yVal, 2, &awb, B);
might generate:
clr A, [w8]+=2, w4, [w10]+=2, w5, w13
The compi ler may need to spill w1 3 to ensure that it is availab le for the write -back. It may be
recommended to users that the register be claimed for this purpose.
After this instruction:
• result will be cleared
•xVal will contain x_memory_buffer[0]
•yVal will contain y_memory_buffer[0]
•xmemory and ymemory will be incremented by 2, ready for the next mac operation
Prototype: int __builtin_clr_prefetch(
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr, int *AWB,
int AWB_accum);
Argument: xptr Integer pointer to x prefetch.
xval Integer value of x prefetch.
xincr Integer increment value of x prefetch.
yptr Integer pointer to y prefetch.
yval Integer value of y prefetch.
yincr Integer increment value of y prefetch.
AWB Accumulator write back location.
AWB_accum Accumul ato r to write back.
Return Value: Returns the cleared value result to an accumulator.
Assembler Operator/
Machine Instruction: clr
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•xval is a null value but xptr is not null
•yval is a null value but yptr is not null
•AWB_accum is not an accumulator and AWB is not null
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 282 2012 Microchip Technology Inc.
__builtin_write_CRYOTP
Description: Initiates a write to the Crypto OTP by issuing the correct unlock sequence and setting the
CRYWR bit.
Interrupts may need to be disable for proper operation.
This builtin function can be us ed a s a p art of a complex se quence di sc us se d in the data
sheet or family reference manual.
See this documentation for more information.
Prototype: void __builtin_write_CRYOTP(void);
Argument: None.
Return Value: None.
Assembler Operator/
Machine Instruction: mov #0x55, Wn
mov Wn, _CRYKEY
mov #0xAA, Wn
mov Wn, _CRYKEY
bset _CRYCON, #15
nop
nop
Error Messages None.
__builtin_disi
Description: Disables all interrupts for a specified number of instruction cycles. See
Section 11.7 “Enabling/Disabling Interrup ts”.
Will emit the specified DISI instruction at the point it appears in the source program: disi
#<disi_count>
Prototype: void __builtin_disi(int disi_count);
Argument: disi_count instructio n cycle count. Must be a literal integer between 0 and 163 83.
Return Value: N/A
Assembler Operator/
Machine Instruction: disi.f
__builtin_divf
Description: Computes the quotient num / den. A math error exception occurs if den is zero. Functi on
arguments are unsigned, as is the function result.
Prototype: unsigned int __builtin_divf(unsigned int num,
unsigned int den);
Argument: num numerator
den denominator
Return Value: Returns the unsigned integer value of the quotient num / den.
Assembler Operator/
Machine Instruction: div.f
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 283
__builtin_divmodsd
Description: Issues the 1 6-bi t arch itectu re’ s nat ive s igned di vide suppo rt with the same re str iction s giv en
in the “ dsPIC30F/33F Programmer’s Referen ce Manual” (DS70 157). Notab ly, if the quotient
does not fit into a 16-bit result, the results (including remainder) are unexpected. This form
of the built-in function will capture both the quotient and remainder.
Prototype: signed int __builtin_divmodsd(
signed long dividend, signed int divisor,
signed int *remainder);
Argument: dividend number to be divided
divisor number to divide by
remainder pointer to remainder
Return Value: Quotient and remainder.
Assembler Operator/
Machine Instruction: divmodsd
Error Messages None.
__builtin_divmodud
Description: Issues the 16-bit architecture’s native unsigned divide support with the same restrictions
given in the “dsPIC30F/33F Programmer’s Reference Manual” (DS70157). Notably, if the
quotient does not fit into a 16-bit result, the results (including remainder) are unexpected.
This form of the built-in function will capture both the quotient and remainder.
Prototype: unsigned int __builtin_divmodud(
unsigned long dividend, unsigned int divisor,
unsigned int *remainder);
Argument: dividend number to be divided
divisor number to divide by
remainder pointer to remainder
Return Value: Quotient and remainder.
Assembler Operator/
Machine Instruction: divmodud
Error Messages None.
__builtin_divsd
Description: Computes the quotient num / den. A math error exception occurs if den is zero . Function
argument s a re s igned, as is the func tion re sult. T he com mand-lin e o ption -Wconversions
can be used to detect unexpected sign conversions.
Prototype: int __builtin_divsd(const long num, const int den);
Argument: num numerator
den denominator
Return Value: Returns the signed integer value of the quotient num / den.
Assembler Operator/
Machine Instruction: div.sd
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 284 2012 Microchip Technology Inc.
__builtin_divud
Description: Computes the quotient num / den. A math error exception occurs if den is zero. Functi on
arguments are unsigned, as is the function result. The command-line option -Wconver-
sions can be used to detect unexpected sign conversions.
Prototype: unsigned int __builtin_divud(const unsigned
long num, const unsigned int den);
Argument: num numerator
den denominator
Return Value: Returns the unsigned integer value of the quotient num / den.
Assembler Operator/
Machine Instruction: div.ud
__builtin_dmapage
Description: Obtains the page number of a symbol within DMA memory.
For example:
unsigned int result;
char buffer[256] __attribute__((space(dma)));
result = __builtin_dmapage(&buffer);
Might generate:
mov #dmapage(buffer), w0
Prototype: unsigned int __builtin_dmapage(const void *p);
Argument: *p pointer to DMA address value
Return Value: Returns the page number of a variable located in DMA memory.
Assembler Operator/
Machine Instruction: dmapage
Error Messages An error message will be displayed if the parameter is not the address of a global symbol.
__builtin_dmaoffset
Description: Obtains the offset of a symbol within DMA memory.
For example:
unsigned int result;
char buffer[256] __attribute__((space(dma)));
result = __builtin_dmaoffset(&buffer);
Might generate:
mov #dmaoffset(buffer), w0
Prototype: unsigned int __builtin_dmaoffset(const void *p);
Argument: *p pointer to DMA address value
Return Value: Returns the offset to a variable located in DMA memory.
Assembler Operator/
Machine Instruction: dmaoffset
Error Messages An error message will be displayed if the parameter is not the address of a global symbol.
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 285
__builtin_ed
Description: Squares sqr, returning it as the result. Also prefetches data for future square operation by
computing **xptr - **yptr and storing the result in *distance.
xincr and yincr may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value.
For example:
volatile register int result asm("A");
int *xmemory, *ymemory;
int distance;
result = __builtin_ed(distance,
&xmemory, 2,
&ymemory, 2,
&distance);
might generate:
ed w4*w4, A, [w8]+=2, [W10]+=2, w4
Prototype: int __builtin_ed(int sqr, int **xptr, int xincr,
int **yptr, int yincr, int *distance);
Argument: sqr Integer squared value.
xptr Integer pointer to pointer to x prefetch.
xincr Integer increment value of x prefetch.
yptr Integer pointer to pointer to y prefetch.
yincr Integer increment value of y prefetch.
distance Integer pointer to distance.
Return Value: Returns the squared result to an accumulator.
Assembler Operator/
Machine Instruction: ed
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•xptr is nu ll
•yptr is nu ll
•distance is null
__builtin_edac
Description: Squares sqr and sums with the nominated accumulator register, returning it as the result.
Also prefetches data for future square operation by computing **xptr - **yptr and stor-
ing the result in *distance.
xincr and yincr may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value.
For example:
volatile register int result asm("A");
int *xmemory, *ymemory;
int distance;
result = __builtin_ed(result, distance,
&xmemory, 2,
&ymemory, 2,
&distance);
might generate:
edac w4*w4, A, [w8]+=2, [W10]+=2, w4
Prototype: int __builtin_edac(int Accum, int sqr,
int **xptr, int xincr, int **yptr, int yincr,
int *distance);
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 286 2012 Microchip Technology Inc.
Argument: Accum Accumulator to sum.
sqr Integer squared value.
xptr Integer pointer to pointer to x prefetch.
xincr Integer increment value of x prefetch.
yptr Integer pointer to pointer to y prefetch.
yincr Integer increment value of y prefetch.
distance Integer pointer to distance.
Return Value: Returns the squared result to specified accumulator.
Assembler Operator/
Machine Instruction: edac
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•Accum is not an accumulator register
•xptr is nu ll
•yptr is nu ll
•distance is null
__builtin_edspage
Description: Returns the eds page number of the object whose address is given as a parameter. The
argument p must be the addres s of an ob jec t in an Extended Da t a Spac e (E DS); otherwise
an error message is produced and the compilation fails. See the space attribute in
Section 2.3.1 “Specifying Attributes of Variables”.
Prototype: unsigned int __builtin_edspage(const void *p);
Argument: pobject address
Return Value: Returns the eds page number of the object whose address is given as a parameter.
Assembler Operator/
Machine Instruction: edspage
Error Messages The following error message is produced when this function is used incorrectly:
“Argument to __builtin_edspage() is not the address of an object in extended data
space”.
The argument must be an explicit object address.
For example, if obj is object in an executable or read-only secti on, the f ollowin g syntax is
valid:
unsigned page = __builtin_edspage(&obj);
__builtin_edac
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 287
__builtin_edsoffset
Description: Returns the e ds p age offset of the objec t whos e a ddre ss is giv en a s a parameter. The argu-
ment p must be the address of an object in an Extended Data Space (EDS); otherwise an
error message is produced and the compilation fails. See the space attribute in
Section 2.3.1 “Specifying Attributes of Variables”.
Prototype: unsigned int __builtin_edsoffset(const void *p);
Argument: pobject address
Return Value: Returns the eds page number offset of the object whose address is given as a parameter.
Assembler Operator/
Machine Instruction: edsoffset
Error Messages The following error message is produced when this function is used incorrectly:
“Argument to __builtin_edsoffset() is not the address of an object in extended data
space”.
The argument must be an explicit object address.
For example, if obj is object in an executable or read-only secti on, the f ollowin g syntax is
valid:
unsigned page = __builtin_edsoffset(&obj);
__builtin_fbcl
Description: Finds th e f irs t b it change fr om le f t i n value. This is useful for dynamic scaling of fixed-point
data. For example:
int result, value;
result = __builtin_fbcl(value);
might generate:
fbcl w4, w5
Prototype: int __builtin_fbcl(int value);
Argument: value Integer number to check for change.
Return Value: Returns a literal value sign extended to represent the number of bits to shift left.
Assembler Operator/
Machine Instruction: fbcl
Error Messages None.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 288 2012 Microchip Technology Inc.
__builtin_lac
Description: Shifts value by shift (a liter al betwee n -8 and 7) and retu rns the value to b e stored into the
accumulator register. For example:
volatile register int result asm("A");
int value;
result = __builtin_lac(value,3);
Might generate:
lac w4, #3, A
Prototype: int __builtin_lac(int value, int shift);
Argument: value Integer number to be shifted.
shift Literal amount to shift.
Return Value: Returns the shifted addition result to an accumulator.
Assembler Operator/
Machine Instruction: lac
Error Messages An error message will be displayed if:
• the result is not an accumulator register
• the shift value is not a literal within range
__builtin_mac
Description: Computes a x b and sums with accumulator; also prefetches data ready for a future MAC
operation.
xptr may be null to signify no X prefetch to be performed, in which case the values of
xincr and xval are ignored, but required.
yptr may be null to signify no Y prefetch to be performed, in which case the values of
yincr and yval are ignored, but required.
xval and yval nominate the address of a C variable where the prefetched value will be
stored.
xincr and yincr may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value.
If AWB is non null, the other accumulator will be written back into the referenced variable.
For example:
volatile register int result asm("A");
volatile register int B asm("B");
int *xmemory;
int *ymemory;
int xVal, yVal;
result = __builtin_mac(result, xVal, yVal,
&xmemory, &xVal, 2,
&ymemory, &yVal, 2, 0, B);
might generate:
mac w4*w5, A, [w8]+=2, w4, [w10]+=2, w5
Prototype: int __builtin_mac(int Accum, int a, int b,
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr, int *AWB,
int AWB_accum);
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 289
Argument: Accum Accumulator to sum.
aInteger multiplicand.
bInteger multiplier.
xptr Integer pointer to pointer to x prefetch.
xval Integer pointer to value of x prefetch.
xincr Integer increment value o f x prefetch.
yptr Integer pointer to pointer to y prefetch.
yval Integer pointer to value of y prefetch.
yincr Integer increment value o f y prefetch.
AWB Accumulator write-back location.
AWB_accum Accumulator to write-back.
Return Value: Returns the cleared value result to an accumulator.
Assembler Operator/
Machine Instruction: mac
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•Accum is not an accumulator register
•xval is a null value but xptr is not null
•yval is a null value but yptr is not null
•AWB_accum is not an accumulator register and AWB is not null
__builtin_modsd
Description: Issues the 1 6-bi t arch itectu re’ s nat ive s igned di vide suppo rt with the same re str iction s giv en
in the “ dsPIC30F/33F Programmer’s Referen ce Manual” (DS70 157). Notab ly, if the quotient
does not fit into a 16-bit result, the results (including remainder) are unexpected. This form
of the built-in function will capture only the remainder.
Prototype: signed int __builtin_modsd(signed long dividend,
signed int divisor);
Argument: dividend number to be divided
divisor number to divide by
Return Value: Remainder.
Assembler Operator/
Machine Instruction: modsd
Error Messages None.
__builtin_modud
Description: Issues the 16-bit architecture’s native unsigned divide support with the same restrictions
given in the “dsPIC30F/33F Programmer’s Reference Manual” (DS70157). Notably, if the
quotient does not fit into a 16-bit result, the results (including remainder) are unexpected.
This form of the built-in function will capture only the remainder.
Prototype: unsigned int __builtin_modud(unsigned long dividend,
unsigned int divisor);
Argument: dividend number to be divided
divisor number to divide by
Return Value: Remainder.
Assembler Operator/
Machine Instruction: modud
Error Messages None.
__builtin_mac (Continued)
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 290 2012 Microchip Technology Inc.
__builtin_movsac
Description: Computes nothing, but prefetches data ready for a future MAC operation.
xptr may be null to signify no X prefetch to be performed, in which case the values of
xincr and xval are ignored, but required.
yptr may be null to signify no Y prefetch to be performed, in which case the values of
yincr and yval are ignored, but required.
xval and yval nominate the address of a C variable where the prefetched value will be
stored.
xincr and yincr may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value.
If AWB is non null, the other accumulator will be written back into the referenced variable.
For example:
volatile register int result asm("A");
int *xmemory;
int *ymemory;
int xVal, yVal;
result = __builtin_movsac(&xmemory, &xVal, 2,
&ymemory, &yVal, 2, 0, 0);
might generate:
movsac A, [w8]+=2, w4, [w10]+=2, w5
Prototype: int __builtin_movsac(
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr, int *AWB
int AWB_accum);
Argument: xptr Integer pointer to pointer to x prefetch.
xval Integer pointer to value of x prefetch.
xincr Integer increment value of x prefetch.
yptr Integer pointer to pointer to y prefetch.
yval Integer pointer to value of y prefetch.
yincr Integer increment value of y prefetch.
AWB Accumulator write back location.
AWB_accum Accumul ato r to write back.
Return Value: Returns prefetch data.
Assembler Operator/
Machine Instruction: movsac
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•xval is a null value but xptr is not null
•yval is a null value but yptr is not null
•AWB_accum is not an accumulator register and AWB is not null
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 291
__builtin_mpy
Description: Computes a x b ; also prefetches data ready for a future MAC operation.
xptr may be null to signify no X prefetch to be performed, in which case the values of
xincr and xval are ignored, but required.
yptr may be null to signify no Y prefetch to be performed, in which case the values of
yincr and yval are ignored, but required.
xval and yval nominate the address of a C variable where the prefetched value will be
stored.
xincr and yincr may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value.
For example:
volatile register int result asm("A");
int *xmemory;
int *ymemory;
int xVal, yVal;
result = __builtin_mpy(xVal, yVal,
&xmemory, &xVal, 2,
&ymemory, &yVal, 2);
might generate:
mpy w4*w5, A, [w8]+=2, w4, [w10]+=2, w5
Prototype: int __builtin_mpy(int a, int b,
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr);
Argument: aInteger multiplicand.
bInteger multiplier.
xptr Integer pointer to pointer to x prefetch.
xval Integer pointer to value of x prefetch.
xincr Integer increment value of x prefetch.
yptr Integer pointer to pointer to y prefetch.
yval Integer pointer to value of y prefetch.
yincr Integer increment value of y prefetch.
AWB Integer pointer to accumulator selection.
Return Value: Returns the value of a x b.
Assembler Operator/
Machine Instruction: mpy
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•xval is a null value but xptr is not null
•yval is a null value but yptr is not null
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 292 2012 Microchip Technology Inc.
__builtin_mpyn
Description: Computes -a x b ; also prefetches data ready for a future MAC operation.
xptr may be null to signify no X prefetch to be performed, in which case the values of
xincr and xval are ignored, but required.
yptr may be null to signify no Y prefetch to be performed, in which case the values of
yincr and yval are ignored, but required.
xval and yval nominate the address of a C variable where the prefetched value will be
stored.
xincr and yincr may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value.
For example:
volatile register int result asm("A");
int *xmemory;
int *ymemory;
int xVal, yVal;
result = __builtin_mpy(xVal, yVal,
&xmemory, &xVal, 2,
&ymemory, &yVal, 2);
might generate:
mpy.n w4*w5, A, [w8]+=2, w4, [w10]+=2, w5
Prototype: int __builtin_mpyn(int a, int b,
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr);
Argument: aInteger multiplicand.
bInteger multiplier.
xptr Integer pointer to pointer to x prefetch.
xval Integer pointer to value of x prefetch.
xincr Integer increment value of x prefetch.
yptr Integer pointer to pointer to y prefetch.
yval Integer pointer to value of y prefetch.
yincr Integer increment value of y prefetch.
AWB Integer pointer to accumulator selection.
Return Value: Returns the value of -a x b.
Assembler Operator/
Machine Instruction: mpyn
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•xval is a null value but xptr is not null
•yval is a null value but yptr is not null
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 293
__builtin_msc
Description: Computes a x b and subtracts from accumulator; also prefetches data ready for a future
MAC operati on.
xptr may be null to signify no X prefetch to be performed, in which case the values of
xincr and xval are ignored, but required.
yptr may be null to signify no Y prefetch to be performed, in which case the values of
yincr and yval are ignored, but required.
xval and yval nominate the address of a C variable where the prefetched value will be
stored.
xincr and yincr may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value.
If AWB is non null, the other accumulator will be written back into the referenced variable.
For example:
volatile register int result asm("A");
int *xmemory;
int *ymemory;
int xVal, yVal;
result = __builtin_msc(result, xVal, yVal,
&xmemory, &xVal, 2,
&ymemory, &yVal, 2, 0, 0);
might generate:
msc w4*w5, A, [w8]+=2, w4, [w10]+=2, w5
Prototype: int __builtin_msc(int Accum, int a, int b,
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr, int *AWB,
int AWB_accum);
Argument: Accum IAccumulator to sum.
aInteger multiplicand.
bInteger multiplier.
xptr Integer pointer to pointer to x prefetch.
xval Integer pointer to value of x prefetch.
xincr Integer increment value of x prefetch.
yptr Integer pointer to pointer to y prefetch.
yval Integer pointer to value of y prefetch.
yincr Integer increment value of y prefetch.
AWB Accumulator write back location.
AWB_accum Accumul ato r to write back.
Return Value: Returns the value of accumulator minus the result of a x b.
Assembler Operator/
Machine Instruction: msc
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•Accum is not an accumulator register
•xval is a null value but xptr is not null
•yval is a null value but yptr is not null
•AWB_accum is not an accumulator register and AWB is not null
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 294 2012 Microchip Technology Inc.
__builtin_mulss
Description: Computes the product p0 x p1. Function arguments are signed integers, and the function
result is a signed long integer. The command-line option -Wconversions can be used to
detect unexpected sign conversions.
For example:
volatile register int a asm("A");
signed long result;
const signed int p0, p1;
const unsigned int p2, p3;
result = __builtin_mulss(p0,p1);
a = __builtin_mulss(p0,p1);
Prototype: signed long __builtin_mulss(const signed int p0, const signed int
p1);
Argument: p0 multiplicand
p1 multiplier
Return Value: Returns the signed long integer value of the product p0 x p1. The value can either be
returned into a variable of type signed long or directly into an accumulator register.
Assembler Operator/
Machine Instruction: mul.ss
__builtin_mulsu
Description: Computes the product p0 x p1. Function arguments are integers with mixed signs, and the
function res ul t is a si gne d l ong integer. The com m and -li ne o ption -Wconversions can be
used to detect unexpected sign conversions. This function supports the full range of
addressing modes of the instruction, including immediate mode for operand p1.
For example:
volatile register int a asm("A");
signed long result;
const signed int p0, p1;
const unsigned int p2, p3;
result = __builtin_mulsu(p0,p2);
a = __builtin_mulsu(p0,p2);
Prototype: signed long __builtin_mulsu(const signed int p0, const unsigned int
p1);
Argument: p0 multiplicand
p1 multiplier
Return Value: Returns the signed long integer value of the product p0 x p1. The value can either be
returned into a variable of type signed long or directly into an accumulator register.
Assembler Operator/
Machine Instruction: mul.su
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 295
__builtin_mulus
Description: Computes the product p0 x p1. Function arguments are integers with mixed signs, and the
function res ul t is a signe d l ong in tege r. T he c om m and -lin e o pti on -Wconversions ca n be
used to detect unexpected sign conversions. This function supports the full range of
addressing modes of the instruction.
For example:
volatile register int a asm("A");
signed long result;
const signed int p0, p1;
const unsigned int p2, p3;
result = __builtin_mulus(p2,p0);
a = __builtin_mulus(p2,p0);
Prototype: signed long __builtin_mulus(const unsigned int p0, const signed int
p1);
Argument: p0 multiplicand
p1 multiplier
Return Value: Returns the signed long integer value of the product p0 x p1. The value can either be
returned into a variable of type signed long or directly into an accumulator register.
Assembler Operator/
Machine Instruction: mul.us
__builtin_muluu
Description: Comput es the pro duct p0 x p1. Function arg ument s are unsign ed integers , and the function
result is an unsign ed long in teger . The comma nd-line opt ion -Wconversions can be used
to detect unexpected sign conversions. This function supports the full range of addressing
modes of the instruction, including immediate mode for operand p1.
For example:
volatile register int a asm("A");
unsigned long result;
const signed int p0, p1;
const unsigned int p2, p3;
result = __builtin_muluu(p2,p3);
a = __builtin_muluu(p2,p3);
Prototype: unsigned long __builtin_muluu(const unsigned int p0, const unsigned
int p1);
Argument: p0 multiplicand
p1 multiplier
Return Value: Returns the signed long integer value of the product p0 x p1. The value can either be
returned into a variable of type unsigned long or directly into an accumulator register.
Assembler Operator/
Machine Instruction: mul.uu
__builtin_nop
Description: Generates a nop instruction .
Prototype: void __builtin_nop(void);
Argument: None.
Return Value: Returns a no operation (nop).
Assembler Operator/
Machine Instruction: nop
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 296 2012 Microchip Technology Inc.
__builtin_psvpage
Description: Returns the psv page number of the object whose address is given as a parameter. The
argument p must be the address of an object in an EE data, PSV or executable memory
space; otherwise an error message is produced and the compilation fails. See the space
attribute in Section 2.3.1 “Specifying Attributes of Variables”.
Prototype: unsigned int __builtin_psvpage(const void *p);
Argument: pobject address
Return Value: Returns the psv page number of the object whose address is given as a parameter.
Assembler Operator/
Machine Instruction: psvpage
Error Messages The following error message is produced when this function is used incorrectly:
“Argument to __builtin_psvpage() is not the address of an object in code, psv, or eed-
ata section”.
The argument must be an explicit object address.
For example, if obj is object in an executable or read-only secti on, the f ollowin g syntax is
valid:
unsigned page = __builtin_psvpage(&obj);
__builtin_psvoffset
Description: Returns the p s v p ag e offset of the object whos e address is give n as a p a r am ete r. The argu-
ment p must be the address of an object in an EE data, PSV or executable memory space;
otherwise an error message is produced and the compilation fails. See the space attribute
in Section 2.3.1 “Specifying Attributes of Variables”.
Prototype: unsigned int __builtin_psvoffset(const void *p);
Argument: pobject address
Return Value: Returns the psv page number offset of the object whose address is given as a parameter.
Assembler Operator/
Machine Instruction: psvoffset
Error Messages The following error message is produced when this function is used incorrectly:
“Argument to __builtin_psvoffset() is not the address of an object in code, psv, or
eedata section”.
The argument must be an explicit object address.
For example, if obj is object in an executable or read-only secti on, the f ollowin g syntax is
valid:
unsigned page = __builtin_psvoffset(&obj);
__builtin_readsfr
Description: Reads the SFR.
Prototype: unsigned int __builtin_readsfr(const void *p);
Argument: pobject address
Return Value: Returns the SFR.
Assembler Operator/
Machine Instruction: readsfr
Error Messages The following error message is produced when this function is used incorrectly:
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 297
__builtin_return_address
Description: Returns the return address of the current function, or of one of its callers. For the level
argument, a value of 0 yields the return address of the current function, a value of 1 yields
the return addres s of th e cal ler of t he curr ent fun ction, and s o forth. When l evel excee ds the
current stack depth, 0 will be returned. This function should only be used with a non-zero
argument for debugging purposes.
Prototype: int __builtin_return_address (const int level);
Argument: level Number of frames to scan up the call stack.
Return Value: Returns the re turn addr ess of the current fun c tion, or of one of its callers.
Assembler Operator/
Machine Instruction: return_address
__builtin_sac
Description: Shifts value by shift (a literal between -8 and 7) and returns the value.
For example:
volatile register int value asm("A");
int result;
result = __builtin_sac(value,3);
Might generate:
sac A, #3, w0
Prototype: int __builtin_sac(int value, int shift);
Argument: value Integer number to be shifted.
shift Literal amount to shift.
Return Value: Returns the shifted result to an accumulator.
Assembler Operator/
Machine Instruction: sac
Error Messages An error message will be displayed if:
• the result is not an accumulator register
• the shift value is not a literal within range
__builtin_sacr
Description: Shifts value by shift (a literal between -8 and 7) and returns the value which is rounded
using the rounding mode determined by the CORCONbits.RND control bit.
For example:
volatile register int value asm("A");
int result;
result = __builtin_sac(value,3);
Might generate:
sac.r A, #3, w0
Prototype: int __builtin_sacr(int value, int shift);
Argument: value Integer number to be shifted.
shift Literal amount to shift.
Return Value: Returns the shifted result to CORCON register.
Assembler Operator/
Machine Instruction: sacr
Error Messages An error message will be displayed if:
• the result is not an accumulator register
• the shift value is not a literal within range
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 298 2012 Microchip Technology Inc.
__builtin_sftac
Description: Shifts acc umulator by shift. The valid sh ift range is -16 to 16.
For example:
volatile register int result asm("A");
int i;
result = __builtin_sftac(result,i);
Might generate:
sftac A, w0
Prototype: int __builtin_sftac(int Accum, int shift);
Argument: Accum Accumulator to shift.
shift Amount to shift.
Return Value: Returns the shifted result to an accumulator.
Assembler Operator/
Machine Instruction: sftac
Error Messages An error message will be displayed if:
• the result is not an accumulator register
•Accum is not an accumulator register
• the shift value is not a literal within range
__builtin_subab
Description: Subtracts accumulators A and B with the result written back to the specified accumulator.
For example:
volatile register int result asm("A");
volatile register int B asm("B");
result = __builtin_subab(result,B);
will generate:
sub A
Prototype: int __builtin_subab(int Accum_a, int Accum_b);
Argument: Accum_a Accumulator from which to subtract.
Accum_b Accumulator to subtract.
Return Value: Returns the subtraction result to an accumulator.
Assembler Operator/
Machine Instruction: sub
Error Messages An error message will be displayed if the result is not an accumulator register.
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 299
__builtin_tbladdress
Description: Returns a val ue tha t represent s t he ad dress of an object i n prog ram m emory. The arg ument
p must be the addre ss of an object in an EE dat a , PSV or ex ecutable mem ory spa ce ; oth er-
wise an error message is produced and the compilation fails. See the space attribute in
Section 2.3.1 “Specifying Attributes of Variables”.
Prototype: unsigned long __builtin_tbladdress(const void *p);
Argument: pobject address
Return Value: Returns an unsigned long value that represents the address of an object in program
memory.
Assembler Operator/
Machine Instruction: tbladdress
Error Messages The following error message is produced when this function is used incorrectly:
“Argument to __builtin_tbladdress() is not the address of an object in code, psv, or
eedata section”.
The argument must be an explicit object address.
For example, if obj is object in an executable or read-only secti on, the f ollowin g syntax is
valid:
unsigned long page = __builtin_tbladdress(&obj);
__builtin_tblpage
Description: Returns the table page number of the object whose address is given as a parameter. The
argument p must be the address of an object in an EE data, PSV or executable memory
space; otherwise an error message is produced and the compilation fails. See the space
attribute in Section 2.3.1 “Specifying Attributes of Variables”.
Prototype: unsigned int __builtin_tblpage(const void *p);
Argument: pobject address
Return Value: Returns the table page number of the object whose address is given as a parameter.
Assembler Operator/
Machine Instruction: tblpage
Error Messages The following error message is produced when this function is used incorrectly:
“Argument to __builtin_tblpage() is not the address of an object in code, psv, or eed-
ata section”.
The argument must be an explicit object address.
For example, if obj is object in an executable or read-only secti on, the f ollowin g syntax is
valid:
unsigned page = __builtin_tblpage(&obj);
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 300 2012 Microchip Technology Inc.
__builtin_tbloffset
Description: Returns the table page offset of the object whose address is given as a parameter. The
argument p must be the address of an object in an EE data, PSV or executable memory
space; otherwise an error message is produced and the compilation fails. See the space
attribute in Section 2.3.1 “Specifying Attributes of Variables”.
Prototype: unsigned int __builtin_tbloffset(const void *p);
Argument: pobject address
Return Value: Returns the table page number offset of the object whose address is given as a parameter.
Assembler Operator/
Machine Instruction: tbloffset
Error Messages The following error message is produced when this function is used incorrectly:
“Argument to __builtin_tbloffset() is not the address of an object in code, psv, or
eedata section”.
The argument must be an explicit object address.
For example, if obj is object in an executable or read-only secti on, the f ollowin g syntax is
valid:
unsigned page = __builtin_tbloffset(&obj);
__builtin_tblrdh
Description: Issues the tblrdh.w instruction to read a word from Flash or EEDATA memory. You must
set up the TBLPAG to point to the appropriate page. To do this, you may make use of
__builtin_tbloffset() and __builtin_tblpage().
Please refer to the data sheet or dsPIC Family Reference Manual for complete details
regarding reading and writing program Flash.
Prototype: unsigned int __builtin_tblrdh(unsigned int offset);
Argument: offset desired memory offset
Return Value: None.
Assembler Operator/
Machine Instruction: tblrdh
Error Messages None.
__builtin_tblrdl
Description: Issues the tblrdl.w instruction to read a word from Flash or EEDATA memory. You must
set up the TBLPAG to point to the appropriate page. To do this, you may make use of
__builtin_tbloffset() and__builtin_tblpage().
Please refer to the data sheet or “dsPIC30F Family Reference Manual” (DS70046) for com-
plete details regarding reading and writing program Flash.
Prototype: unsigned int __builtin_tblrdl(unsigned int offset);
Argument: offset desired memory offset
Return Value: None.
Assembler Operator/
Machine Instruction: tblrdl
Error Messages None.
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 301
__builtin_tblwth
Description: Issues the tblwth.w instruction to write a word to Flash or EEDA TA memory . You must set
up the TBLPAG to point to the appropriate page. To do this, you may make use of
__builtin_tbloffset() and __builtin_tblpage().
Please refer to the data sheet or “dsPIC30F Family Reference Manual” (DS70046) for com-
plete details regarding reading and writing program Flash.
Prototype: void __builtin_tblwth(unsigned int offset
unsigned int data);
Argument: offset desired memory offset
data data to be writ ten
Return Value: None.
Assembler Operator/
Machine Instruction: tblwth
Error Messages None.
__builtin_tblwtl
Description: Issues the tblrdl.w instruction to write a word to Flash or EEDA TA memory . You must set
up the TBLPAG to point to the appropriate page. To do this, you may make use of
__builtin_tbloffset() and __builtin_tblpage().
Please refer to the data sheet or “dsPIC30F Family Reference Manual” (DS70046) for com-
plete details regarding reading and writing program Flash.
Prototype: void __builtin_tblwtl(unsigned int offset
unsigned int data);
Argument: offset desired memory offset
data data to be writ ten
Return Value: None.
Assembler Operator/
Machine Instruction: tblwtl
Error Messages None.
__builtin_write_NVM
Description: Enables th e Fla sh for writ ing by issuin g the co rrect unl ock s equenc e and en ablin g the Wri te
bit of the NVMCON register.
Interrupts may need to be disable for proper operation.
This builtin function can be us ed a s a p art of a complex se quence di sc us se d in the data
sheet or family reference manual.
See this documentation for more information.
Prototype: void __builtin_write_NVM(void);
Argument: None.
Return Value: None.
Assembler Operator/
Machine Instruction: mov #0x55, Wn
mov Wn, _NVMKEY
mov #0xAA, Wn
mov Wn, _NVMKEY
bset _NVMCON, #15
nop
nop
Error Messages None.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 302 2012 Microchip Technology Inc.
__builtin_write_NVM_secure
Description: Enables the Flash for writing by issuing an unlock sequence specified by two keys and
enabling the Write bit of the NVMCON register.
Interrupts may need to be disable for proper operation.
This builtin function can be us ed a s a p art of a complex se quence di sc us se d in the data
sheet or family reference manual.
See this documentation for more information.
Prototype: void __builtin_write_NVM_secure(unsigned int key1,
unsigned int key2);
Argument: key1 first key in the NVM unlock sequence
key2 second key in the NVM unlock sequence
Return Value: None.
Assembler Operator/
Machine Instruction: Depending on the lcoatin of the keys:
mov W0, Wn
mov Wn, _NVMKEY
mov W1, Wn
mov Wn, _NVMKEY
bset _NVMCON, #15
nop
nop
Error Messages None.
__builtin_write_PWMSFR
Description: Writes the PWM unlock sequence to the SFR pointed to by PWM_KEY and then writes
value to the SFR pointed to by PWM_sfr.
Prototype: void __builtin_write_PWMSFR(volatile unsigned int *PWM_sfr,
unsigned int value, volatile unsigned int *PWM_KEY);
Argument: PWM_sfr register to be written
value value to write
PWM_KEY hardware unlock key location
Return Value: None.
Assembler Operator/
Machine Instruction: mov #<it>PWM_KEY</it>, w3
mov #<it>value</it>, w2
mov #0x4321, w1
mov #0xABCD, w0
mov w1,[w3]
mov w0,[w3]
mov w2,[w3]
Error Messages None.
Examples Example 1:
__builtin_write_PWMSFR(&PWM1CON1, 0x123, &PWM1KEY);
Example 2:
__builtin_write_PWMSFR(&P1FLTACON, 0x123, &PWMKEY);
The choice of PWM_KEY may depend upon architecture.
Built-in Functions
2012 Microchip Technology Inc. DS52071B-page 303
__builtin_write_RTCWEN
Description: Used to write to the RTCC Timer by implementing the unlock sequence by writing the cor-
rect unlock values to NVMKEY and then setting the RTCWREN bit of RCFGCAL SFR.
Interrupts may need to be disable for proper operation.
This builtin function can be us ed a s a p art of a complex se quence di sc us se d in the data
sheet or family reference manual.
See this documentation for more information.
Prototype: void __builtin_write_RTCWEN(void);
Argument: None.
Return Value: None.
Assembler Operator/
Machine Instruction: mov #0x55, Wn
mov Wn, _NVMKEY
mov #0xAA, Wn
mov Wn, _NVMKEY
bset _RCFGCAL, #13
nop
nop
Error Messages None.
__builtin_write_OSCCONL
Description: Unlocks and writes its argument to OSCCONL.
Interrupts may need to be disable for proper operation.
This builtin function can be us ed a s a p art of a complex se quence di sc us se d in the data
sheet or family reference manual.
See this documentation for more information.
Prototype: void __builtin_write_OSCCONL(unsigned char value);
Argument: value character to be written
Return Value: None.
Assembler Operator/
Machine Instruction*: mov #0x46, w0
mov #0x57, w1
mov #_OSCCON, w2
mov.b w0, [w2]
mov.b w1, [w2]
mov.b value, [w2]
Error Messages None.
* The exact sequence may be different.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 304 2012 Microchip Technology Inc.
__builtin_write_OSCCONH
Description: Unlocks and writes its argument to OSCCONH.
Interrupts may need to be disable for proper operation.
This builtin function can be us ed a s a p art of a complex se quence di sc us se d in the data
sheet or family reference manual.
See this documentation for more information.
Prototype: void __builtin_write_OSCCONH(unsigned char value);
Argument: value character to be written
Return Value: None.
Assembler Operator/
Machine Instruction*: mov #0x78, w0
mov #0x9A, w1
mov #_OSCCON+1, w2
mov.b w0, [w2]
mov.b w1, [w2]
mov.b value, [w2]
Error Messages None.
* The exact sequence may be different.
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 305
Appendix G. XC16 Configuration Settings
G.1 INTRODUCTION
Configuration Settings macros are provided that can be used to set configuration bits.
For example, to set the FOSC bit using a macro, the following line of code can be
inserted before the beginning of your C source code:
_FOSC(CSW_FSCM_ON & EC_PLL16);
This would enable the external clock with the PLL set to 16x and enable clock switching
and fail-safe cl oc k mon itori ng.
Similarly, to set the FBORPOR bit:
_FBORPOR(PBOR_ON & BORV_27 & PWRT_ON_64 & MCLR_DIS);
This would enable Brown-out Reset at 2.7 Volts and initialize the Power-up timer to 64
milliseconds and configure the use of the MCLR pin for I/O.
Configuration Settings macros are defined in compiler header files for each device.
Please refer to your device’s header files for a complete listing of related macros.
Header files are located, by default, in:
C:\Program Files\Microchip\mplabxc16\v1.0\support\device\h
where device is the 16-bit device family you are using.
EXAMPLE G-1: P33FJ128MC510.H HEADER FILE - FWDT REGISTER
/*-----------------------------------------------------------------
* MPLAB-Cxx dsPIC33FJ128MC510 processor header
*
* (c) Copyright 1999-2010 Microchip Technology, All rights reserved
*-----------------------------------------------------------------*/
:
:
/* Register FWDT (0xf8000a) */
extern __attribute__((space(prog))) int _FWDT;
#define _FWDT(x) __attribute__((section("__FWDT.sec"),space(prog)))
int _FWDT = (x);
/*
** Only one invocation of FWDT should appear in a project,
** at the top of a C source file (outside of any function).
**
** The following constants can be used to set FWDT.
** Multiple options may be combined, as shown:
**
** _FWDT( OPT1_ON & OPT2_OFF & OPT3_PLL )
**
** Watchdog Timer:
** FWDTEN_OFF Disabled
** FWDTEN_ON Enabled
**
** Windowed WDT:
** WINDIS_ON Enabled
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 306 2012 Microchip Technology Inc.
** WINDIS_OFF Disabled
**
** Watchdog prescaler:
** WDTPRE_PR32 1:32
** WDTPRE_PR128 1:128
**
** Watchdog postscaler:
** WDTPOST_PS1 1:1
** WDTPOST_PS2 1:2
** WDTPOST_PS4 1:4
** WDTPOST_PS8 1:8
** WDTPOST_PS16 1:16
** WDTPOST_PS32 1:32
** WDTPOST_PS64 1:64
** WDTPOST_PS128 1:128
** WDTPOST_PS256 1:256
** WDTPOST_PS512 1:512
** WDTPOST_PS1024 1:1,024
** WDTPOST_PS2048 1:2,048
** WDTPOST_PS4096 1:4,096
** WDTPOST_PS8192 1:8,192
** WDTPOST_PS16384 1:16,384
** WDTPOST_PS32768 1:32,768
**
*/
#define FWDTEN_OFF 0xFF7F
#define FWDTEN_ON 0xFFFF
#define WINDIS_ON 0xFFBF
#define WINDIS_OFF 0xFFFF
#define WDTPRE_PR32 0xFFEF
#define WDTPRE_PR128 0xFFFF
#define WDTPOST_PS1 0xFFF0
#define WDTPOST_PS2 0xFFF1
#define WDTPOST_PS4 0xFFF2
#define WDTPOST_PS8 0xFFF3
#define WDTPOST_PS16 0xFFF4
#define WDTPOST_PS32 0xFFF5
#define WDTPOST_PS64 0xFFF6
#define WDTPOST_PS128 0xFFF7
#define WDTPOST_PS256 0xFFF8
#define WDTPOST_PS512 0xFFF9
#define WDTPOST_PS1024 0xFFFA
#define WDTPOST_PS2048 0xFFFB
#define WDTPOST_PS4096 0xFFFC
#define WDTPOST_PS8192 0xFFFD
#define WDTPOST_PS16384 0xFFFE
#define WDTPOST_PS32768 0xFFFF
MPLAB® XC16 C COMPILER
USER’S GUIDE
2012 Microchip Technology Inc. DS52071B-page 307
Glossary
A
Absolute Section
A section with a fixed (absolute) address that cannot be changed by the linker.
Access Memory
PIC18 Only – Special registers on PIC18 devices that allow access regardless of the
setting of the Bank Select Register (BSR).
Access Entry Points
Access entry points provide a way to transfer control across segments to a function
which may not be defined at link time. They support the separate linking of boot and
secure application segments.
Address
Value that identifies a location in memory.
Alphabetic Character
Alphabetic characters are those characters that are letters of the arabic alphabet
(a,b,…,z,A,B, …,Z).
Alphanumeric
Alphanumeric characters are comprised of alphabetic characters and decimal digits
(0,1, …, 9).
ANDed Breakpoints
Set up an ANDed condition for breaking, i.e., breakpoint 1 AND breakpoint 2 must
occur at the same time before a program halt. This can only be accomplished if a data
breakpoint and a program memory breakpoint occur at the same time.
Anonymous Structure
16-bit C Compiler – An unnamed structure.
PIC18 C Compiler – An unnamed structure that is a member of a C union. The mem-
bers of an anonymous structure may be accessed as if they were members of the
enclosing union. For example, in the following code, hi and lo are members of an
anonymous structure inside the union caster.
union castaway
int intval;
struct {
char lo; //accessible as caster.lo
char hi; //accessible as caster.hi
};
} caster;
ANSI
American National Standards Institute is an organization responsible for formulating
and approving standards in the United States.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 308 2012 Microchip Technology Inc.
Application
A set of software and hardware that may be controlled by a PIC® microcontroller.
Archive/Archiver
An archive/library is a collection of relocatable object modules. It is created by assem-
bling multiple source files to object files, and then using the archiver/librarian to com-
bine the object files into one archive/library file. An archive/library can be linked with
object modules and other archives/libraries to create executable code.
ASCII
American St andard Code for Information Interchange is a character set encoding that
uses 7 binary digits to represent each character. It includes upper and lower case
letters, digits, symbols and control characters.
Assembly/Assembler
Assembly is a programming language that describes binary machine code in a sym-
bolic form. An assembler is a language tool that translates assembly language source
code into machine code.
Assign ed Sec tion
A section which has been assigned to a target memory block in the linker command file.
Asynchronously
Multiple events that do not occur at the same time. This is generally used to refer to
interrupts that may occur at any time during processor execution.
Asynchronous Stimulus
Data generated to simulate external inputs to a simulator device.
Attribute
Characteristics of variables or functions in a C program which are used to describe
machine-specific properties.
Attribute, Section
Characteristics of sections, such as “executable”, “readonly”, or “data” that can be
specified as flags in the assembler .section directive.
B
Binary
The base two numbering system that uses the digits 0-1. The rightmost digit counts
ones, the next counts multiples of 2, then 22 = 4, etc.
Bookmarks
Use bookmarks to easily locate specific lines in a file.
Under the Edit menu, select Bookmarks to manage bookmarks. Toggle (enable /
disable) a bookmark, move to the next or previous bookmark, or clear all bookmarks.
Breakpoint
Hardware Breakpoint: An event whose execution will cause a halt.
Software Breakpoint: An address where execution of the firmware will halt. Usually
achieved by a special break instruction.
Build
Compile and link all the source files for an application.
Glossary
2012 Microchip Technology Inc. DS52071B-page 309
C
C\C++
C is a general-purpose programming language which features economy of expression,
modern control flow and data structures, and a rich set of operators. C++ is the
object-oriented version of C.
Calibration Memory
A special function register or registers used to hold values for calibration of a PIC micro-
controller on-board RC oscillator or other device peripherals.
Central Processing Unit
The part of a device that is responsible for fetching the correct instruction for execution,
decoding that instruction, and then executing that instruction. When necessary , it works
in conjunction with the arithmetic logic unit (ALU) to complete the execution of the
instruction. It controls the program memory address bus, the data memory address
bus, and accesses to the stack.
Clean
Clean removes all intermediary project files, such as object, hex and debug files, for
the active project. These files are recreated from other files when a project is built.
COFF
Common Object File Format. An object file of this format contains machine code,
debugging and other information.
Command Line Interface
A means of communication between a program and its user based solely on textual
input and output.
Compiler
A program that translates a source file written in a high-level language into machine
code.
Conditional Assembly
Assembly language code that is included or omitted based on the assembly-time value
of a specified expression.
Conditional Compilation
The act of compiling a program fragment only if a certain constant expression, specified
by a preprocess or directive, is true.
Configuration Bits
Special-purpose bits programmed to set PIC microcontroller modes of operation. A
Configuration bit may or may not be preprogrammed.
Control Directives
Directives in assembly language code that cause code to be included or omitted based
on the assembly-time value of a specified expression.
CPU
See Central Processing Unit.
Cross Reference File
A file that references a table of symbols and a list of files that references the symbol. If
the symbol is defined, the first file listed is the location of the definition. The remaining
files contain references to the symbol.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 310 2012 Microchip Technology Inc.
D
Data Directives
Data directives are those that control the assembler’s allocation of program or data
memory and provide a way to refer to data items symbolically; that is, by meaningful
names.
Data Memory
On Microchip MCU and DSC devices, data memory (RAM) is comprised of General
Purpose Registers (GPRs) and S pecial Function Registers (SFRs). Some devices also
have EEPROM data memory.
Debug/Debugger
See ICE/ICD.
Debugging Information
Compiler and assembler options that, when selected, provide varying degrees of infor-
mation used to debug application code. See compiler or assembler documentation for
details on selecting debug options.
Deprecate d Feat ures
Features that are still supported for legacy reasons, but will eventually be phased out
and no longer used.
Device Programmer
A tool used to program electrically programmable semiconductor devices such as
microcontrollers.
Digital Signal Controller
A A digital signal controller (DSC) is a microcontroller device with digital signal process-
ing capability, i.e., Microchip dsPIC DSC devices.
Digital Signal Processing\Digital Signal Processor
Digital signal processing (DSP) is the computer manipulation of digital signals, com-
monly analog signals (sound or image) which have been converted to digital form (sam-
pled). A digital signal processor is a microprocessor that is designed for use in digital
signal pr oc essi ng.
Directives
Statements in source code that provide control of the language tool’s operation.
Download
Download is the process of sending data from a host to another device, such as an
emulator, programmer or target board.
DWARF
Debug With Arbitrary Record Format. DWARF is a debug information format for ELF
files.
E
EEPROM
Electrically Erasable Programmable Read Only Memory. A special type of PROM that
can be erased electrically. Data is written or erased one byte at a time. EEPROM
retains its contents even when power is turned off.
ELF
Executable and Linking Format. An object file of this format contains machine code.
Debugging and other information is specified in with DWARF. ELF/DWARF provide
better debugging of optimized code than COFF.
Glossary
2012 Microchip Technology Inc. DS52071B-page 311
Emulation/Emulator
See ICE/ICD.
Endianness
The ordering of bytes in a multi-byte object.
Environment
MPLAB PM3 – A folder containing files on how to program a device. This folder can be
transferred to a SD/MMC card.
Epilogue
A portion of compiler-generated code that is responsible for deallocating stack space,
restoring registers and performing any other machine-specific requirement specified in
the runtime model. This code executes after any user code for a given function,
immediately prior to the function return.
EPROM
Erasable Programmable Read Only Memory. A programmable read-only memory that
can be erased usually by exposure to ultraviolet radiation.
Error/Error File
An error reports a problem that makes it impossible to continue processing your pro-
gram. When possible, an error identifies the source file name and line number where
the problem is apparent. An error file contains error messages and diagnostics gener-
ated by a language tool.
Event
A description of a bus cycle which may include address, data, pass count, external
input, cycle type (fetch, R/W), and time stamp. Events are used to describe triggers,
breakpoints and interrupts.
Executable Code
Software that is ready to be loaded for execution.
Export
Send data out of the MPLAB IDE in a standardized format.
Expressions
Combinations of constants and/or symbols separated by arithmetic or logical
operators.
Extended Data Space (EDS)
Additional data memory available on some PIC24 MCU devices. The EDS includes any
additional internal extended data memory not accessible by the lower 32 Kbytes data
address space, any external memory through EPMP, and the Program S pace Visibility
(PSV).
Extended Microcontroller Mod e
In extended microcontroller mode, on-chip program memory as well as external mem-
ory is available. Execution automatically switches to external if the program memory
address is greater than the internal memory space of the PIC18 device.
Extended Mode (PIC18 MCUs)
In Extended mode, the compiler will utilize the extended instructions (i.e., ADDFSR,
ADDULNK, CALLW, MOVSF, MOVSS, PUSHL, SUBFSR and SUBULNK) and the indexed
with literal offset addressing.
External Label
A label that has extern al lin ka ge.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 312 2012 Microchip Technology Inc.
Extern al Lin kag e
A function or variable has external linkage if it can be referenced from outside the
module in which it is defined.
Exte rnal Symbol
A symbol for an identifier which has external linkage. This may be a reference or a
definition.
External Symbol Resolu ti on
A process performed by the linker in which external symbol definitions from all input
modules are collected in an attempt to resolve all external symbol references. Any
external symbol references which do not have a corresponding definition cause a linker
error to be reported.
External Input Line
An external input signal logic probe line (TRIGIN) for setting an event based upon
external signals.
External RAM
Off-chip Read/Write memory.
F
Fatal Error
An error that will halt compilation immediately. No further messages will be produced.
File Registers
On-chip data memory, including General Purpose Registers (GPRs) and Special
Function Registers (SFRs).
Filter
Determine by selection what data is included/excluded in a trace display or data file.
Flash
A type of EEPROM where data is written or erased in blocks instead of bytes.
FNOP
Forced No Operation. A forced NOP cycle is the second cycle of a two-cycle instruc-
tion. Since the PIC microcontroller architecture is pipelined, it prefetches the next
instruction in the physical address space while it is executing the current instruction.
However, if the current instruction changes the program counter, this prefetched
instruction is explicitly ignored, causing a forced NOP cycle.
Frame Pointer
A pointer that references the location on the stack that separates the stack-based
arguments from the stack-based local variables. Provides a convenient base from
which to access local variables and other values for the current function.
Free-Standing
An implementation that accepts any strictly conforming program that does not use
complex types and in which the use of the features specified in the library clause (ANSI
‘89 standard clause 7) is confined to the contents of the standard headers <float.h>,
<iso646.h>, <limits.h>, <stdarg.h>, <stdbool.h>, <stddef.h> and
<stdint.h>.
G
GPR
General Purpose Register. The portion of device data memory (RAM) available for
general use.
Glossary
2012 Microchip Technology Inc. DS52071B-page 313
H
Halt
A stop of program execution. Executing Halt is the same as stopping at a breakpoint.
Heap
An area of memory used for dynamic memory allocation where blocks of memory are
allocated and freed in an arbitrary order determined at runtime.
Hex Code\Hex File
Hex code is executable instructions stored in a hexadecimal format code. Hex code is
contained in a hex file.
Hexadecimal
The base 16 numbering system that uses the digits 0-9 plus the letters A-F (or a-f). The
digits A-F represent hexadecimal digits with values of (decimal) 10 to 15. The rightmost
digit counts ones, the next counts multiples of 16, then 162 = 256, etc.
High Level Language
A language for writing programs that is further removed from the processor than
assembly.
I
ICE/ICD
In-Circuit Emulator/In-Circuit Debugger: A hardware tool that debugs and programs a
target device. An emulator has more features than an debugger, such as trace.
In-Circuit Emulation/In-Circuit Debug: The act of emulating or debugging with an in-cir-
cuit emulator or debugger.
-ICE/-ICD: A device (MCU or DSC) with on-board in-circuit emulation or debug circuitry .
This device is always mounted on a header board and used to debug with an in-circuit
emulator or debugger.
ICSP
In-Circuit Serial Programming. A method of programming Microchip embedded
devices using serial communication and a minimum number of device pins.
IDE
Integrated Development Environment, as in MPLAB IDE.
Identifier
A function or va riabl e name .
IEEE
Institute of Electrical and Electronics Engineers.
Import
Bring data into the MPLAB IDE from an outside source, such as from a hex file.
Initialized Data
Data which is defined with an initial value. In C,
int myVar=5;
defines a variable which will reside in an initialized data section.
Instruction Set
The collection of machine language instructions that a particular processor
understands.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 314 2012 Microchip Technology Inc.
Instructions
A sequence of bits that tells a central processing unit to perform a particular operation
and can contain data to be used in the operation.
Internal Linkage
A function or variable has internal linkage if it can not be accessed from outside the
module in which it is defined.
International Organization for Sta ndardization
An organization that sets standards in many businesses and technologies, including
computing and communications. Also known as ISO.
Interrupt
A signal to the CPU that suspends the execution of a running application and transfers
control to an Interrupt Service Routine (ISR) so that the event may be processed. Upon
completion of the ISR, normal execution of the application resumes.
Interrupt Handler
A routine that processes special code when an interrupt occurs.
Interrupt Service Request (IRQ)
An event which causes the processor to temporarily suspend normal instruction exe-
cution and to start executing an interrupt handler routine. Some processors have
several interrupt request events allowing different priority interrupts.
Interrupt Service Routine (ISR)
Language tools – A function that handles an interrupt.
MPLAB IDE – User-generated code that is entered when an interrupt occurs. The loca-
tion of the code in program memory will usually depend on the type of interrupt that has
occurred.
Interrupt Vector
Address of an interrupt service routine or interrupt handler.
L
L-value
An expression that refers to an object that can be examined and/or modified. An l-value
expression is used on the left-hand side of an assignment.
Latency
The time between an event and its response.
Library/Librarian
See Archive/Archiver.
Linker
A language tool that combines object files and libraries to create executable code,
resolving references from one module to another.
Linker Script Files
Linker script files are the command files of a linker. They define linker options and
describe available memory on the target platform.
Listing Directives
Listing directives are those directives that control the assembler listing file format. They
allow the spec ifi ca tio n of titles , paginati on and othe r listi ng co ntr ol .
Glossary
2012 Microchip Technology Inc. DS52071B-page 315
Listing File
A listing file is an ASCII text file that shows the machine code generated for each C
source statement, assembly instruction, assembler directive, or macro encountered in
a source file.
Little Endian
A data ordering scheme for multibyte data whereby the least significant byte is stored
at the lower addresses.
Local Label
A local label is one that is defined inside a macro with the LOCAL directive. These
labels are particular to a given instance of a macro’s instantiation. In other words, the
symbols and labels that are declared as local are no longer accessible after the ENDM
macro is encountered.
Logic Probes
Up to 14 logic probes can be connected to some Microchip emulators. The logic probes
provide external trace inputs, trigger output signal, +5V, and a common ground.
Loop-Back Test Board
Used to test the functionality of the MPLAB REAL ICE in-circuit emulator.
LVDS
Low Voltage Differential Signaling. A low noise, low-power, low amplitude method for
high-speed (gigabits per second) data transmission over copper wire.
With standard I/0 signaling, data storage is contingent upon the actual voltage level.
Voltage level can be affected by wire length (longer wires increase resistance, which
lowers voltage). But with L VDS, data storage is distinguished only by positive and neg-
ative voltage values, not the voltage level. Therefore, data can travel over greater
lengths of wire while maintaining a clear and consistent data stream.
Source: http://www.webopedia.com/TERM/L/LVDS.html.
M
Machine Code
The representation of a computer program that is actually read and interpreted by the
processor. A program in binary machine code consists of a sequence of machine
instructions (possibly interspersed with data). The collection of all possible instructions
for a particular processor is known as its “instruction set”.
Machine Language
A set of instructions for a specific central processing unit, designed to be usable by a
processo r with out bei ng trans lat ed.
Macro
Macro instruction. An instruction that represents a sequence of instructions in abbrevi-
ated form.
Macro Directives
Directives that control the execution and data allocation within macro body definitions.
Makefile
Export to a file the instructions to Make the project. Use this file to Make your project
outside of MPLAB IDE, i.e., with a make.
Make Project
A command that rebuilds an application, recompiling only those source files that have
changed since the last complete compilation.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 316 2012 Microchip Technology Inc.
MCU
Microcontroller Unit. An abbreviation for microcontroller. Also uC.
Memory Model
For C compilers, a representation of the memory available to the application. For the
PIC18 C compiler , a description that specifies the size of pointers that point to program
memory.
Message
Text displayed to alert you to potential problems in language tool operation. A message
will not stop operation.
Microcontroller
A highly integrated chip that contains a CPU, RAM, program memory, I/O ports and
timers.
Microcontroller Mode
One of the possible program memory configurations of PIC18 microcontrollers. In
microcontroller mode, only internal execution is allowed. Thus, only the on-chip pro-
gram memory is available in microcontroller mode.
Microprocessor Mode
One of the possible program memory configurations of PIC18 microcontrollers. In
microprocessor mode, the on-chip program memory is not used. The entire program
memory is mapped externally.
Mnemonics
Text instructions that can be translated directly into machine code. Also referred to as
opcodes.
MPASM™ Assembler
Microchip Technology’s relocatable macro assembler for PIC microcontroller devices,
KeeLoq® devices and Microchip memory devices.
MPLAB Language Tool for Device
Microchip’s C compilers, assemblers and linkers for specified devices. Select the type
of language tool based on the device you will be using for your application, e.g., if you
will be creating C code on a PIC18 MCU, select the MPLAB C Compiler for PIC18
MCUs.
MPLAB ICD
Microchip’s in-circuit debuggers that works with MPLAB IDE. See ICE/ICD.
MPLAB IDE
Microchip’s Integrated Development Environment. MPLAB IDE comes with an editor,
project manager and simulator.
MPLAB PM3
A device programmer from Microchip. Programs PIC18 microcontrollers and dsPIC
digital signal controllers. Can be used with MPLAB IDE or stand-alone. Replaces
PRO MATE II.
MPLAB REAL ICE™ In-Circuit Emulator
Microchip’s next-generation in-circuit emulators that works with MPLAB IDE. See
ICE/ICD.
MPLAB SIM
Microchip’s simulator that works with MPLAB IDE in support of PIC MCU and dsPIC
DSC devices.
Glossary
2012 Microchip Technology Inc. DS52071B-page 317
MPLIB™ Object Librarian
Microchip’s librarian that can work with MPLAB IDE. MPLIB librarian is an object librar-
ian for use with COFF object modules created using either MP ASM assembler (mpasm
or mpasmwin v2.0) or MPLAB C18 C compiler.
MPLINK™ Object Linker
MPLINK linker is an object linker for the Microchip MPASM assembler and the Micro-
chip C18 C compiler . MPLINK linker also may be used with the Microchip MPLIB librar-
ian. MPLINK linker is designed to be used with MPLAB IDE, though it does not have to
be.
MRU
Most Recently Used. Refers to files and windows available to be selected from MPLAB
IDE main pull down menus.
N
Native Data Size
For Native trace, the size of the variable used in a Watch window must be of the same
size as the selected device’s data memory: bytes for PIC18 devices and words for
16-bit devices.
Nesting Depth
The maximum level to which macros can include other macros.
Node
MPLAB IDE project component.
Non-Extended Mode (PIC18 MCUs)
In Non-Extended mode, the compiler will not utilize the extended instructions nor the
indexed with literal offset addressing.
Non Real Time
Refers to the processor at a breakpoint or executing single-step instructions or MPLAB
IDE being run in simulator mode.
Non-Volatile Storage
A storage device whose contents are preserved when its power is off.
NOP
No Operation. An instruction that has no effect when executed except to advance the
program counter.
O
Object Code/Object File
Object code is the machine code generated by an assembler or compiler. An object file
is a file containing machine code and possibly debug information. It may be immedi-
ately executable or it may be relocatable, requiring linking with other object files, e.g.,
libraries, to produce a complete executable program.
Object File Directives
Directives that are used only when creating an object file.
Octal
The base 8 number system that only uses the digits 0-7. The rightmost digit counts
ones, the next digit counts multiples of 8, then 82 = 64, etc.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 318 2012 Microchip Technology Inc.
Off-Chip Memory
Off-chip memory refers to the memory selection option for the PIC18 device where
memory may reside on the target board, or where all program memory may be supplied
by the emulator. The Memory tab accessed from Options>Development Mode pro-
vides the Off-Chip Memory selection dialog box.
Opcodes
Operational Codes. See Mnemonics.
Operators
Symbols, like the plus sign ‘+’ and the minus sign ‘-’, that are used when forming
well-defined expressions. Each operator has an assigned precedence that is used to
determine order of evaluation.
OTP
One Time Programmable. EPROM devices that are not in windowed packages. Since
EPROM needs ultraviolet light to erase its memory, only windowed devices are eras-
able.
P
Pass Counter
A counter that decrements each time an event (such as the execution of an instruction
at a particular address) occurs. When the pass count value reaches zero, the event is
satisfied. You can assign the Pass Counter to break and trace logic, and to any
sequential event in the complex trigger dialog.
PC
Person al Comp ute r or Progra m Counte r.
PC Host
Any PC running a supported Windows operating system.
Persistent Data
Data that is never cleared or initialized. Its intended use is so that an application can
preserve data across a device Reset.
Phantom Byte
An unimplemented byte in the dsPIC architecture that is used when treating the 24-bit
instruction word as if it were a 32-bit instruction word. Phantom bytes appear in dsPIC
hex files.
PIC MCUs
PIC microcontrollers (MCUs) refers to all Microchip microcontroller families.
PICkit 2 and 3
Microchip’s developmental device programmers with debug capability through Debug
Express. See the Readme files for each tool to see which devices are supported.
Plug-ins
The MPLAB IDE has both built-in components and plug-in modules to configure the
system for a variety of software and hardware tools. Several plug-in tools may be found
under the Tools menu.
Pod
The enclosure for an in-circuit emulator or debugger. Other names are “Puck”, if the
enclosure is round, and “Probe”, not be confused with logic probes.
Glossary
2012 Microchip Technology Inc. DS52071B-page 319
Power-on-Reset Emulation
A software randomization process that writes random values in data RAM areas to
simulate uninitialized values in RAM upon initial power application.
Pragma
A directive that has meaning to a specific compiler. Often a pragma is used to convey
implementation-defined information to the compiler . MPLAB C30/XC16 uses attributes
to convey this information.
Precedence
Rules that define the order of evaluation in expressions.
Prod ucti o n Pr og r a mm e r
A production programmer is a programming tool that has resources designed in to pro-
gram devices rapidly . It has the capability to program at various voltage levels and com-
pletely adheres to the programming specification. Programming a device as fast as
possible is of prime importance in a production environment where time is of the
essence as the application circuit moves through the assembly line.
Profile
For MPLAB SIM simulator, a summary listing of executed stimulus by register.
Program Counter
The location that contains the address of the instruction that is currently executing.
Program Counter Unit
16-bit assembler – A conceptual representation of the layout of program memory. The
program counter increments by 2 for each instruction word. In an executable section,
2 program counter units are equivalent to 3 bytes. In a read-only section, 2 program
counter units are equivalent to 2 bytes.
Program Memory
MPLAB IDE – The memory area in a device where instructions are stored. Also, the
memory in the emulator or simulator containing the downloaded target application firm-
ware.
16-bit assembler/compiler – The memory area in a device where instructions are
stored.
Project
A project contains the files needed to build an application (source code, linker script
files, etc.) along with their associations to various build tools and build options.
Prologue
A portion of compiler-generated code that is responsible for allocating stack space, pre-
serving registers and performing any other machine-specific requirement specified in
the runtime model. This code executes before any user code for a given function.
Prototype System
A term referring to a user's target application, or target board.
PWM Signals
Pulse Width Modulation Signals. Certain PIC MCU devices have a PWM peripheral.
Q
Qualifier
An address or an address range used by the Pass Counter or as an event before
another operation in a complex trigger.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 320 2012 Microchip Technology Inc.
R
Radix
The number base, hex, or decimal, used in specifying an address.
RAM
Random Access Memory (Data Memory). Memory in which information can be
accessed in any order.
Raw Dat a
The binary representation of code or data associated with a section.
Read Only Memory
Memory hardware that allows fast access to permanently stored data but prevents
addition to or modification of the data.
Real Time
When an in-circuit emulator or debugger is released from the halt state, the processor
runs in Real Time mode and behaves exactly as the normal chip would behave. In Real
Time mode, the real time trace buffer of an emulator is enabled and constantly captures
all selected cycles, and all break logic is enabled. In an in-circuit emulator or debugger ,
the processor executes in real time until a valid breakpoint causes a halt, or until the
user halts the execution.
In the simulator, real time simply means execution of the microcontroller instructions as
fast as they can be simulated by the host CPU.
Real-Time Watch
A W atch window where the variables change in real-time as the application is run. See
individual tool documentation to determine how to set up a real-time watch. Not all tools
support real-time watches.
Recursive Calls
A function that calls itself, either directly or indirectly.
Recursion
The concept that a function or macro, having been defined, can call itself. Great care
should be taken when writing recursive macros; it is easy to get caught in an infinite
loop where there will be no exit from the recursion.
Reentrant
A function that may have multiple, simultaneously active instances. This may happen
due to either direct or indirect recursion or through execution during interrupt
processing.
Relaxation
The process of converting an instruction to an identical, but smaller instruction. This is
usef ul for savi ng on co de size. MP LAB ASM3 0 currentl y knows how to RELAX a CALL
instruction into an RCALL instruction. This is done when the symbol that is being called
is within +/- 32k instruction words from the current instruction.
Relocatable
An object whose address has not been assigned to a fixed location in memory.
Relocatable Section
16-bit assembler – A section whose address is not fixed (absolute). The linker assigns
addresses to relocatable sections through a process called relocation.
Glossary
2012 Microchip Technology Inc. DS52071B-page 321
Relocation
A process performed by the linker in which absolute addresses are assigned to relo-
catable sections and all symbols in the relocatable sections are updated to their new
addresses.
ROM
Read Only Memory (Program Memory). Memory that cannot be modified.
Run
The command that releases the emulator from halt, allowing it to run the application
code and change or respond to I/O in real time.
Run-time Model
Describes the use of target architecture resources.
S
Scenario
For MPLAB SIM simulator, a particular setup for stimulus control.
Section
A portion of an application located at a specific address of memory.
Section Attribute
A characteristic ascribed to a section (e.g., an access section).
Sequenced Breakpoints
Breakpoints that occur in a sequence. Sequence execution of breakpoints is
bottom-up; the last breakpoint in the sequence occurs first.
Serialized Quick Turn Programming
Serialization allows you to program a serial number into each microcontroller device
that the Device Programmer programs. This number can be used as an entry code,
password or ID number.
Shell
The MPASM assembler shell is a prompted input interface to the macro assembler.
There are two MPASM assembler shells: one for the DOS version and one for the
Windows version.
Simulator
A software progr am that mod els th e operati on of devi c es.
Single Step
This command steps though code, one instruction at a time. After each instruction,
MPLAB IDE updates register windows, watch variables, and status displays so you can
analyze and debug instruction execution. You can also single step C compiler source
code, but instead of executing single instructions, MPLAB IDE will execute all assembly
level instructions generated by the line of the high level C statement.
Skew
The information associated with the execution of an instruction appears on the proces-
sor bus at different times. For example, the executed opcodes appears on the bus as
a fetch during the execution of the previous instruction, the source data address and
value and the destination data address appear when the opcodes is actually executed,
and the destination data value appears when the next instruction is executed.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 322 2012 Microchip Technology Inc.
The trace buffer captures the information that is on the bus at one instance. Therefore,
one trace buffer entry will contain execution information for three instructions. The num-
ber of captured cycles from one piece of information to another for a single instruction
execution is referred to as the skew.
Skid
When a hardware breakpoint is used to halt the processor, one or more additional
instructions may be executed before the processor halts. The number of extra
instructions executed after the intended breakpoint is referred to as the skid.
Source Code
The form in which a computer program is written by the programmer. Source code is
written in a formal programming language which can be translated into machine code
or executed by an interpreter.
Source File
An ASCII text file containing source code.
Special Function Registers (SFRs)
The portion of data memory (RAM) dedicated to registers that control I/O processor
functions, I/O status, timers or other modes or peripherals.
SQTP
See Serialized Quick Turn Programming.
Sta ck, Hardw ar e
Locations in PIC microcontroller where the return address is stored when a function call
is made.
Sta ck, So ftware
Memory used by an application for storing return addresses, function parameters, and
local variables. This memory is typically managed by the compiler when developing
code in a high-level language.
MPLAB Starter Kit for Device
Microchip’s starter kits contains everything needed to begin exploring the specified
device. View a working application and then debug and program you own changes.
Static RAM or SRAM
Static Random Access Memory. Program memory you can read/write on the target
board that does not need refreshing frequently.
Status Bar
The S t atus Bar is located on the bottom of the MPLAB IDE window and indicates such
current information as cursor position, development mode and device, and active tool
bar.
Step Into
This command is the same as Single S tep. S tep Into (as opposed to S tep Over) follows
a CALL instruction into a subroutine.
Step Over
S tep Over allows you to debug code without stepping into subroutines. When stepping
over a CALL instruction, the next breakpoint will be set at the instruction after the CALL.
If for some reason the subroutine gets into an endless loop or does not return properly ,
the next breakpoint will never be reached. The Step Over command is the same as
Single Step except for its handling of CALL instructions.
Glossary
2012 Microchip Technology Inc. DS52071B-page 323
Step Out
Step Out allows you to step out of a subroutine which you are currently stepping
through. This command executes the rest of the code in the subroutine and then stops
execution at the return address to the subroutine.
Stimulus
Input to the simulator, i.e., data generated to exercise the response of simulation to
external signals. Often the data is put into the form of a list of actions in a text file.
Stimulus may be asynchronous, synchronous (pin), clocked and register.
Stopwatch
A counter for measuring execution cycles.
Storage Class
Determines the lifetime of the memory ass oc iat ed with the ide ntified object.
Storage Qualifier
Indicates special properties of the objects being declared (e.g., const).
Symbol
A symbol is a general purpose mechanism for describing the various pieces which
comprise a program. These pieces include function names, variable names, section
names, file names, struct/enum/union tag names, etc. Symbols in MPLAB IDE refer
mainly to variable names, function names and assembly labels. The value of a symbol
after linking is its value in memory.
Symbol, Absolute
Represents an immediate value such as a definition through the assembly .equ
directive.
System Window Control
The system window control is located in the upper left corner of windows and some dia-
logs. Clicking on this control usually pops up a menu that has the items “Minimize,”
“Maximize,” and “Close.”
T
Target
Refers to user hardware.
Target Application
Software residing on the target board.
Target Board
The circuitry and programmable device that makes up the target application.
Target Processor
The microcontroller device on the target application board.
Template
Lines of text that you build for inserting into your files at a later time. The MPLAB Editor
stores templates in template files.
Tool Bar
A row or column of icons that you can click on to execute MPLAB IDE functions.
Trace
An emulator or simulator function that logs program execution. The emulator logs pro-
gram execution into its trace buffer which is uploaded to MPLAB IDE’s trace window.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 324 2012 Microchip Technology Inc.
Trace Memor y
Trace memory contained within the emulator. Trace memory is sometimes called the
trace buffer.
Trace Mac ro
A macro that will provide trace information from emulator data. Since this is a software
trace, the macro must be added to code, the code must be recompiled or reassembled,
and the target device must be programmed with this code before trace will work.
Trigger Output
Trigger output refers to an emulator output signal that can be generated at any address
or address range, and is independent of the trace and breakpoint settings. Any number
of trigger output points can be set.
Trigraphs
Three-character sequences, all starting with ??, that are defined by ISO C as
replacements for single characters.
U
Unassigned Section
A section which has not been assigned to a specific target memory block in the linker
command file. The linker must find a target memory block in which to allocate an
unassigned section.
Uninitialized Data
Data which is defined without an initial value. In C,
int myVar;
defines a variable which will reside in an uninitialized data section.
Upload
The Upload function transfers data from a tool, such as an emulator or programmer , to
the host PC or from the target board to the emulator.
USB
Universal Serial Bus. An external peripheral interface standard for communication
between a computer and external peripherals over a cable using bi-serial transmission.
USB 1.0/1.1 supports data transfer rates of 12 Mbps. Also referred to as high-speed
USB, USB 2.0 supports data rates up to 480 Mbps.
V
Vector
The memory locations that an application will jump to when either a Reset or interrupt
occurs.
W
Warning
MPLAB IDE – An alert that is provided to warn you of a situation that would cause phys-
ical damage to a device, software file, or equipment.
16-bit assembler/compiler – Warnings report conditions that may indicate a problem,
but do not halt processing. In the compiler, warning messages report the source file
name and line number, but include the text ‘warning:’ to distinguish them from error
messages.
Watch Variable
A variable that you may monitor during a debugging session in a Watch window.
Glossary
2012 Microchip Technology Inc. DS52071B-page 325
Watch Window
Watch windows contain a list of watch variables that are updated at each breakpoint.
Watchdog Timer (W DT)
A timer on a PIC microcontroller that resets the processor after a selectable length of
time. The WDT is enabled or disabled and set up using Configuration bits.
Workbook
For MPLAB SIM stimulator, a setup for generation of SCL stimulus.
MPLAB® XC16 C Compiler User’s Guide
DS52071B-page 326 2012 Microchip Technology Inc.
NOTES:
2012 Microchip Technology Inc. DS52071B-page 327
MPLAB® XC16 C COMPILER
USER’S GUIDE
Symbols
__align qualifier........................................................ 38
__bank qualifier........................................................ 37
__builtin_add.......................................................... 279
__builtin_addab...................................................... 279
__builtin_btg........................................................... 280
__builtin_clr............................................................ 280
__builtin_clr_prefect............................................... 281
__builtin_disi .......................................................... 282
__builtin_divf.......................................................... 282
__builtin_divmodsd ................................................ 283
__builtin_divmodud................................................ 283
__builtin_divsd ....................................................... 283
__builtin_divud....................................................... 284
__builtin_dmaoffset................................................ 284
__builtin_dmapage................................................. 284
__builtin_ed............................................................ 285
__builtin_edac........................................................ 285
__builtin_edsoffset................................................. 287
__builtin_edspage.................................................. 286
__builtin_fbcl.......................................................... 287
__builtin_lac........................................................... 288
__builtin_mac......................................................... 288
__builtin_modsd..................................................... 289
__builtin_modud..................................................... 289
__builtin_movsac ................................................... 290
__builtin_mpy......................................................... 291
__builtin_mpyn....................................................... 292
__builtin_msc......................................................... 293
__builtin_mulss ...................................................... 294
__builtin_mulsu ...................................................... 294
__builtin_mulus...................................................... 295
__builtin_muluu...................................................... 295
__builtin_nop.......................................................... 295
__builtin_psvoffset ................................................. 296
__builtin_psvpage.................................................. 296
__builtin_readsfr..................................................... 296
__builtin_return_address........................................ 297
__builtin_sac.......................................................... 297
__builtin_sacr......................................................... 297
__builtin_sftac........................................................ 298
__builtin_subab...................................................... 298
__builtin_tbladdress............................................... 299
__builtin_tbloffset................................................... 300
__builtin_tblpage.................................................... 299
__builtin_tblrdh....................................................... 300
__builtin_tblrdl........................................................ 300
__builtin_tblwth ...................................................... 301
__builtin_tblwtl........................................................ 301
__builtin_write_CRYOTP....................................... 282
__builtin_write_NVM ..............................................301
__builtin_write_NVM_secure .................................302
__builtin_write_OSCCONH....................................304
__builtin_write_OSCCONL ....................................303
__builtin_write_PWMSFR ......................................302
__builtin_write_RTCWEN ......................................303
__deprecate qualifier................................................43
__eeprom qualifier ...................................................39
__far qualif ier .................... ..... ...... ...... ..... .................34
__interrupt qualifier ..................................................39
__near qualifier ........................................................35
__pack qualifier........................................................42
__persisten qualifier.................................................36
__section qualifier....................................................43
__XC16_VERSION__............................................202
__xdata qualifier.......................................................37
__ydata qualifier.......................................................37
.bss................................................................. 111, 217
.const......................................................................187
.data ............................................................... 111, 217
.text ...................................................62, 154, 156, 217
#define .....................................................................76
#ident .......................................................................82
#if .............................................................................70
#include.............................................................. 77, 78
#include directive .....................................................52
#line..........................................................................79
#pragma....................................................67, 205, 217
Numerics
0b binary radix specifier.........................................101
16-Bit Specific Options.............................................60
A
-A..............................................................................76
abort............................................................... 154, 221
absolute functions ....................................................33
absolute variables ....................................................33
address Attribute............................................ 108, 150
alias Attribute .........................................................150
aligned Attribute.....................................................108
Alignment ........................................108, 111, 161, 216
-ansi ............................................................63, 79, 158
ANSI C Standard............... ..... ...... ...... ..... .................17
ANSI C standard.................... ...... ...... ..... .................22
conformance .....................................................91
implementation-defined behaviour....................91
ANSI C, Strict.................... ..... ................. ...... ..... ......64
ANSI Standard Library Support................................18
ANSI-89 extension...................................................94
Archiver....................................................................53
Index
DS52071B-page 328 2012 Microchip Technology Inc.
MPLAB
®
XC16 C Compiler User’s Guide
arrays
initialization .....................................................102
Arrays and Pointers................................................215
ASCII Character Set...............................................271
ASCII characters......................................................95
extended .........................................................102
asm ................................................................ 108, 192
asm C statement......................................................47
Assembler ................................................................53
assembly list files .....................................................58
Assembly Options....................................................79
-Wa ...................................................................79
assembly source files...............................................51
Assembly, Inline.....................................................192
Assembly, Mixing with C........................................189
Atomic Operat ion ............... ................. ...... ..... ...... ..182
attribute .............................................18, 107, 149, 205
Attribute, Function
address ...........................................................150
alias.................................................................150
boot.................................................................151
const ...............................................................152
deprecated......................................................152
far....................................................................152
format..............................................................152
format_arg.......................................................153
interrupt............................................153, 167, 180
near.................................................................153
no_instrument_function...................................153
noload ............................................................. 154
noreturn..................................................... 69, 154
section..............................................154, 157, 275
secure .............................................................154
shadow.................................................... 155, 167
unsupported....................................................156
unused ............................................................ 156
user_init ..........................................................156
weak................................................................156
Attribute, Variable................................ ...... ..... ........107
address ...........................................................108
aligned ............................................................108
boot.................................................................108
deprecated......................................................109
eds .................................................................. 109
far.....................................................109, 143, 160
fillupper ...........................................................109
mode............................................................... 109
near..................................................110, 143, 160
noload ............................................................. 110
packed ............................................................110
persistent ........................................................111
reverse............................................................111
section.............................................................111
secure .............................................................112
sfr....................................................................112
space ..............................................................112
transparent_union...........................................114
unordered........................................................114
unsupported....................................................114
unused ............................................................ 114
weak................................................................114
auto variab les................ ..... ...... ..... .................118, 121
memory allocation......................................121–??
auto_psv Space........................................................60
Automatic Variable..................................... 67, 68, 122
-aux-info ...................................................................63
B
-B..............................................................................51
binary constants
C code.............................................................101
Bit Fields...........................................................64, 216
Bit fields..................................................................184
bit-fields...................................................30, 31, 96–??
bitwise complement operator .................................146
boot Attribute...................... ...... ..... ...... ...... .....108, 151
Built-In Functions
__builtin_add...................................................279
__builtin_addab...............................................279
__builtin_btg....................................................280
__builtin_clr.....................................................280
__builtin_clr_prefect........................................281
__builtin_disi ...................................................282
__builtin_divf...................................................282
__builtin_divmodsd .........................................283
__builtin_divmodud.........................................283
__builtin_divsd ................................................283
__builtin_divud................................................284
__builtin_dmaoffset.........................................284
__builtin_dmapage..........................................284
__builtin_ed.....................................................285
__builtin_edac.................................................285
__builtin_edsoffset..........................................287
__builtin_edspage...........................................286
__builtin_fbcl...................................................287
__builtin_lac....................................................288
__builtin_mac..................................................288
__builtin_modsd..............................................289
__builtin_modud..............................................289
__builtin_movsac ............................................290
__builtin_mpy..................................................291
__builtin_mpyn................................................292
__builtin_msc..................................................293
__builtin_mulss ...............................................294
__builtin_mulsu...............................................294
__builtin_mulus...............................................295
__builtin_muluu...............................................295
__builtin_nop...................................................295
__builtin_psvoffset ..........................................296
__builtin_psvpage...........................................296
__builtin_readsfr..............................................296
__builtin_return_address.................................297
__builtin_sac...................................................297
__builtin_sacr..................................................297
__builtin_sftac.................................................298
__builtin_subab...............................................298
__builtin_tbladdress........................................299
__builtin_tbloffset............................................300
__builtin_tblpage.............................................299
__builtin_tblrdh................................................300
__builtin_tblrdl.................................................300
2012 Microchip Technology Inc. DS52071B-page 329
Index
__builtin_tblwth............................................... 301
__builtin_tblwtl ................................................ 301
__builtin_write_CRYOTP................................ 282
__builtin_write_NVM....................................... 301
__builtin_write_NVM_secure.......................... 302
__builtin_write_OSCCONH............................. 304
__builtin_write_OSCCONL............................. 303
__builtin_write_PWMSFR............................... 302
__builtin_write_RTCWEN............................... 303
C
-C............................................................................. 76
-c.........................................................................62, 80
C Dialect Control Options......................................... 63
-ansi.................................................................. 63
-aux-info............................................................ 63
-ffreestanding.................................................... 63
-fno-asm............................................................ 63
-fno-builtin......................................................... 63
-fno-signed-bitfields .......................................... 64
-fno-unsigned-bitfields ...................................... 64
-fsigned-bitfields................................................ 64
-fsigned-char..................................................... 63
-funsigned-bitfields............................................ 64
-funsigned-char................................................. 64
-traditional....................................................... 158
C Stack Usage....................................................... 122
C standard libraries.................................................. 57
C, Mixing with Assembly........................................ 189
Cast...............................................................67, 68, 69
casting.................................................................... 146
CCI........................................................................... 23
char....................................... 63, 64, 94, 109, 147, 161
char data types ...................................................28, 95
character constants
in C .................................................................102
Characters ............................................................. 213
Code Generation Conventions Options ................... 82
-fargument-alias................................................ 82
-fargument-noalias............................................ 82
-fargument-noalias-global................................. 82
-fcall-saved ....................................................... 82
-fcall-used ......................................................... 82
-ffixed................................................................ 82
-fno-ident........................................................... 82
-fno-short-double .............................................. 83
-fno-verbose-asm.............................................. 83
-fpack-struct...................................................... 83
-fpcc-struct-return ............................................. 83
-fshort-enums.................................................... 83
-fverbose-asm................................................... 83
-fvolatile ............................................................ 83
-fvolatile-global.................................................. 83
-fvolatile-static................................................... 83
Code Size, Reduce.............................................6 0, 71
Coding ISRs........................................................... 167
COFF ..................................................................52, 53
Command Line Options ........................................... 49
Command-Line Compiler......................................... 49
Command-Line Options........................................... 60
Command-Line Simulator.............................18, 52, 53
Comments.......................................................... 64, 76
common compiler interface......................................23
Common Sube xpression Elim ina tio n....72, 73, 74, 152
compilation
incremental builds.............................................55
Compiler...................................................................53
Command-Line .................................................49
Driver .......................................................... 18, 53
Overview...........................................................17
Compiler Description................................................17
Compiling Multiple Files...........................................55
Complex
Data Types......................................................100
Floating Types ................................................100
Integer Types..................................................100
complex..................................................................100
const Attribute........................................................152
const objects
initialization .....................................................103
const qualifier................................................. 103, 128
Constants
Predefined............................................... 202, 273
constants
C specifiers.....................................................101
character.........................................................102
string, see string literals.................................. 102
conversion between types......................................145
CORCON......................................................... 87, 187
Customer Support....................................................16
D
-D ..................................................................76, 77, 79
data memory..................... ..... ................. ...... ..... ....118
Data Memory Allocation.........................................120
Data Memory Space ...................................60, 62, 141
Data Memory Space, Near.....................................110
Data Type...............................................................109
Complex..........................................................100
data types
size of................................................................27
Data, Packed..........................................................137
-dD ...........................................................................76
Debugging Information.............................................70
Debugging Options ..................................................70
-g.......................................................................70
-Q......................................................................70
-save-temps......................................................71
Declarators.............................................................216
Defining Gl oba l Register Varia bl es........................274
depreca ted Attrib ute............... ...................69, 109, 152
Development Tools.................................................. 19
Device Support Files................................................85
diagnostic files..........................................................58
Diagnostics.............................................................223
Directories.......................................................... 77, 79
Directory Search Options.........................................82
-B ......................................................................51
-specs= ............................................................. 82
-dM...........................................................................76
-dN ...........................................................................76
DS52071B-page 330 2012 Microchip Technology Inc.
MPLAB
®
XC16 C Compiler User’s Guide
Documentation.........................................................17
Conventions......................................................13
Layout ............................................................... 12
double .................................................83, 95, 147, 161
driver
input files...........................................................50
driver option
CCI....................................................................48
PRE.................................................................201
driver options............................................................50
dsPIC-Specific Options
-mauxflash ........................................................62
-mconst-in-auxflash...........................................60
-mconst-in-code ................................................ 60
-mconst-in-data.................................................60
-mcpu................................................................61
-merrata ............................................................60
-mfillupper .........................................................60
-mlarge-arrays...................................................61
-mlarge-code.....................................................61
-mlarge-data......................................................61
-mno-isr-warn....................................................61
-mno-pa.............................................................61
-momf=..............................................................61
-mpa..................................................................61
-mpa=................................................................61
-msmall-code ....................................................61
-msmall-data .....................................................62
-msmall-scalar...................................................62
-msmart-io.........................................................62
-mtext=..............................................................62
DWARF....................................................................61
E
-E.......................................................62, 76, 78, 79, 80
eds Attribute...... ...... ...... ..... ................. ...... ..... ........109
EEDATA.................................................................121
EEPROM, data .......................................................121
ELF..................................................................... 52, 61
Enabling/Disabling Interrupts.................................181
Enumerations.........................................................216
Environment...........................................................212
Environment Variables
PIC30_C_INCLUDE_PATH..............................50
PIC30_COMPILER_PATH................................50
PIC30_LIBRARY_ PATH..................................51
TMPDIR ............................................................51
XC16_C_INCLUDE_PATH...............................50
XC16_COMPILER_PATH.................................50
XC16_EXEC_PREFIX ......................................51
XC16_LIBRARY_ PATH...................................51
errno.......................................................................221
Error Control Options
-pedantic-errors.................................................64
-Werror..............................................................69
-Werror-implicit-function-declaration.................64
Errors .....................................................................223
Escape Sequ enc es.................. ..... .........................213
Excepti on Vect ors............................... ...... ..... ...... ..169
exit..........................................................................221
extended character set...........................................102
Extensions................................................................78
extern ......................................................... 69, 75, 159
External Sym bo ls .......................... ...... ...... ..... ........189
F
F constant su ffix................. ....................................102
-falign-functions........................................................72
-falign-labels.............................................................72
-falign-loops..............................................................72
far Attribute..............................109, 143, 152, 160, 192
Far Data Space......................................................143
-fargument-alias .......................................................82
-fargument-noalias ...................................................82
-fargument-noalias-global.........................................82
-fcaller-saves............................................................72
-fcall-saved...............................................................82
-fcall-used.................................................................82
-fcse-follow-jumps ....................................................72
-fcse-skip-blocks.......................................................72
-fdata-sections..........................................................72
-fdefer-pop. See -fno-defer
-fexpensive-optimizations.........................................72
-ffixed................................................................ 82, 274
-ffreestanding ...........................................................63
-ffunction-sections....................................................72
-fgcse........................................................................72
-fgcse-lm...................................................................73
-fgcse-sm..................................................................73
File Extens ion s............................................... ...... ....51
File Naming Conventio n...................... ...... ..... ...... ....50
file types
input ..................................................................50
Files........................................................................220
--fill............................................................................80
fillupper Attribute ....................................................109
-finline-functions....................................69, 71, 75, 158
-finline-limit...............................................................75
-finstrument-functions.............................................153
-fkeep-inline-functions ...................................... 75, 158
-fkeep-static-consts..................................................75
Flags, Positive and Negative..............................75, 82
float..............................................83, 95, 109, 147, 161
Floating.....................................................................95
Floating Point .........................................................215
Floating Types, Complex........................................100
floating - poi nt con st ant suf fix es. ..... ...... ...... .............102
-fno.....................................................................75, 82
-fno-asm...................................................................63
-fno-builtin.................................................................63
-fno-defer-pop...........................................................73
-fno-function-cse.......................................................75
-fno-ident ..................................................................82
-fno-inline..................................................................75
-fno-keep-static-consts.............................................75
-fno-peephole...........................................................73
-fno-peephole2.........................................................73
-fno-short-double......................................................83
-fno-show-column.....................................................76
-fno-signed-bitfields..................................................64
-fno-unsigned-bitfields..............................................64
-fno-verbose-asm.....................................................83
2012 Microchip Technology Inc. DS52071B-page 331
Index
-fomit-frame-pointer.............................................71, 75
-foptimize-register-move .......................................... 73
-foptimize-sibling-calls.............................................. 75
format Attribute ...................................................... 152
format_arg Attribute ............................................... 153
-fpack-struct ............................................................. 83
-fpcc-struct-return..................................................... 83
Frame Pointer (W14)...................................75, 82, 122
-fregmove................................................................. 73
-frename-registers.................................................... 73
-frerun-cse-after-loop ..........................................73, 74
-frerun-loop-opt ........................................................ 73
-fschedule-insns....................................................... 73
-fschedule-insns2..................................................... 73
-fshort-enums........................................................... 83
-fsigned-bitfields....................................................... 64
-fsigned-char............................................................ 63
-fstrength-reduce.................................................73, 74
-fstrict-aliasing.....................................................71, 74
-fsyntax-only............................................................. 64
-fthread-jumps.....................................................71, 74
Function
Call Conventions............................................. 161
Calls, Preserving Registers............................. 163
Parameters ..................................................... 161
Pointers....................................................142, 159
function
parameters...................................................... 121
pointers............................................................. 99
size limits ........................................................ 156
specifiers......................................................... 149
functions
absolute ............................................................ 33
static ............................................................... 149
-funroll-all-loops ..................................................71, 74
-funroll-loops .......................................................71, 74
-funsigned-bitfields................................................... 64
-funsigned-char........................................................ 64
-fverbose-asm.......................................................... 83
-fvolatile.................................................................... 83
-fvolatile-global......................................................... 83
-fvolatile-static.......................................................... 83
G
-g.............................................................................. 70
--gc-sections ............................................................ 80
general regi ste rs............... ..... ...... ...... ................ .... 192
getenv .................................................................... 221
Global Register Variables ...................................... 274
Guidelines for Writing ISRs........................... ..... .... 166
H
-H............................................................................. 76
header file
search pat h.......... ...... ....................................... 26
Header Files................................ 50, 51, 76, 77, 78, 79
header files .......................................................25, 197
--heap..................................................................... 141
--help........................................................................ 63
Hex File.................................................................... 55
hexadecimal constants
C code.............................................................101
High-Priority Interrupts...........................................182
I
-I....................................................................50, 77, 79
-I-........................................................................ 77, 79
Identifiers................................................................ 213
identifiers
unique length of ................................................27
-idirafter....................................................................77
-imacros ............................................................. 77, 79
imag .......................................................................100
Implementation-Defined Behavior..........................211
implementation-defined behaviour...........................91
-include............................................................... 77, 79
incremental builds....................................................55
Inhibit Warnings .......................................................64
Inline......................................................69, 71, 75, 192
inline................................................................. 75, 158
Inline Functions......................................................158
input files..................................................................50
int ......................................................94, 109, 147, 161
Integer....................................................................192
Behavior..........................................................214
Types, Comp le x.................... ...... ..... ...... .........100
integer constants....................................................101
integer suffixes.......................................................101
integral promotion ..................................................145
intermediate files......................................................50
Internet Address, Microchip .....................................15
Interrupt
Enabling/Disabling..........................................181
Functions ........................................................189
Handling..........................................................189
High Priority ....................................................182
Latency ...........................................................180
Low Priority.....................................................182
Nesting............................................................180
Priority.............................................................180
Protection From ..............................................184
Request...........................................................170
Service Routi ne Conte xt Saving............ ..... ....180
Vectors............................................................169
Vectors, Writi ng............... ...... ..........................169
interrupt Attrib ute............... ......153, 155, 167, 180, 205
-iprefix ......................................................................77
IRQ.........................................................................170
ISR Coding.............................................................167
Guidelines for Writing......................................166
Syntax for Writing............................................167
Writing.............................................................166
-isystem....................................................................77
-iwithprefix................................................................77
-iwithprefixbefore......................................................77
DS52071B-page 332 2012 Microchip Technology Inc.
MPLAB
®
XC16 C Compiler User’s Guide
L
-L..............................................................................80
-l ...............................................................................81
L constant suffix.....................................................101
Large Code Model....................................................61
Large Data Model.....................................................61
Latency...................................................................180
-legacy-libc...............................................................80
lib directo ry........ ................. ...... ..... ...... .....................57
Librarian ...................................................................53
librarian ..................................................................209
libraries
replaci ng mo dul es in......... ..... ...... ...................209
user defined......................................................57
Library .............................................................. 81, 197
ANSI Standard............ ...... ..... ................. ...... ....18
Functions ........................................................218
limits.h header file.............................................. 94, 95
Linker ................................................................. 53, 81
Linker Script ....................................................... 85, 87
Linking Options ........................................................79
--fill ....................................................................80
--gc-sections .....................................................80
-L.......................................................................80
-l........................................................................81
-legacy-libc........................................................80
-nodefaultlibs.....................................................81
-nostdlib ............................................................81
-s.......................................................................81
-u.......................................................................81
-Wl.....................................................................81
-Xlinker..............................................................81
LL, Suffix..................................................................94
Local Register Variables................................ 274, 275
long ...................................................94, 109, 147, 161
long double..................................83, 95, 109, 147, 161
long long..............................................69, 94, 109, 147
long long int..............................................................94
Loop Optimization..................................................152
Loop Optimizer.........................................................73
Loop Unrolling..........................................................74
Low-Priority Interrupts............................................182
M
-M.............................................................................78
Mabonga ........................................................ 205, 275
macro ....................................................76, 77, 79, 159
MacrosData Memory Allocation .............................120
main function.................................................... 25, 187
main-li ne co de......... ...... .........................................166
make files.................................................................55
map files...................................................................58
-mauxflash................................................................62
-mconst-in-auxflash...................................60, 142, 159
-mconst-in-code.........................................60, 142, 159
-mconst-in-data .........................................60, 142, 159
-mcpu .......................................................................61
-MD ..........................................................................78
Memory ..................................................................221
memory allocation..................................................117
data memory..................... ..... ................. ...... ..118
function code...................................................156
non-auto variables...........................................118
static variables ............ ...... ..... ...... ................. ..119
Memory Models........................................ 18, 142, 159
-mconst-in-auxflash.................................142, 159
-mconst-in-code ......................................142, 159
-mconst-in-data ....................................... 142, 159
-mlarge-code...........................................142, 159
-mlarge-data............................................142, 159
-msmall-code...........................................142, 159
-msmall-data ...........................................142, 159
-msmall-scalar.........................................142, 159
Memory Spaces .....................................................119
-merrata....................................................................60
-MF...........................................................................78
-mfillupper.................................................................60
-MG ..........................................................................78
Mixing Assembly Lang uage and C Va riables and Func-
tions....................................................................189
-mlarge-arrays..........................................................61
-mlarge-code ............................................ 61, 142, 159
-mlarge-data............................................. 61, 142, 159
-MM..........................................................................78
-MMD........................................................................78
-mno-isr-warn...........................................................61
-mno-pa....................................................................61
mode Attribute........................................................109
modules....................................................................52
-momf=.....................................................................61
-MP...........................................................................78
-mpa.........................................................................61
-mpa=.......................................................................61
-MQ ..........................................................................78
-msmall-code.....................................61, 142, 159, 160
-msmall-data......................................62, 142, 143, 159
-msmall-scalar...................................62, 142, 143, 159
-msmart-io................................................................62
-MT...........................................................................78
-mtext= .....................................................................62
myMicrochip Personalized Notification Service........15
N
Near and Far Code .................................................160
Near and Far Data..........................................143, 160
near Attribute...........................110, 143, 153, 160, 192
Near Data Section..................................................143
Near Data Space....................................................194
Nesting Interrupts...................................................180
no_instrument_function Attribute............................153
-nodefaultlibs............................................................81
noload Attribute..............................................110, 154
non-volatile RAM....................................................103
noreturn Attribute..............................................69, 154
-nostdinc.............................................................77, 79
-nostdlib....................................................................81
NULL macro.............................................................32
NULL pointers ........................................................100
2012 Microchip Technology Inc. DS52071B-page 333
Index
O
-O........................................................................70, 71
-o.........................................................................54, 62
-O0........................................................................... 71
-O1........................................................................... 71
-O2........................................................................... 71
-O3........................................................................... 71
Object File............................ 52, 53, 72, 78, 80, 81, 197
Optimization............................................................. 17
Optimization Control Options................................... 71
-falign-functions ................................................ 72
-falign-labels ..................................................... 72
-falign-loops ...................................................... 72
-fcaller-saves .................................................... 72
-fcse-follow-jumps............................................. 72
-fcse-skip-blocks............................................... 72
-fdata-sections.................................................. 72
-fexpensive-optimizations ................................. 72
-ffunction-sections............................................. 72
-fgcse................................................................ 72
-fgcse-lm........................................................... 73
-fgcse-sm.......................................................... 73
-finline-functions................................................ 75
-finline-limit........................................................ 75
-fkeep-inline-functions....................................... 75
-fkeep-static-consts........................................... 75
-fno-defer-pop................................................... 73
-fno-function-cse............................................... 75
-fno-inline.......................................................... 75
-fno-peephole.................................................... 73
-fno-peephole2.................................................. 73
-fomit-frame-pointer .......................................... 75
-foptimize-register-move................................... 73
-foptimize-sibling-calls....................................... 75
-fregmove.......................................................... 73
-frename-registers ............................................ 73
-frerun-cse-after-loop........................................ 73
-frerun-loop-opt................................................. 73
-fschedule-insns................................................ 73
-fschedule-insns2.............................................. 73
-fstrength-reduce .............................................. 73
-fstrict-aliasing................................................... 74
-fthread-jumps................................................... 74
-funroll-all-loops ................................................ 74
-funroll-loops..................................................... 74
-O...................................................................... 71
-O0.................................................................... 71
-O1.................................................................... 71
-O2.................................................................... 71
-O3.................................................................... 71
-Os.................................................................... 71
Optimization, Loop............................................73, 152
Optimization, Peephole............................................ 73
Options
16-Bit Specific................................................... 60
Assembling ....................................................... 79
C Dialect Control............................................... 63
Code Generation Conventions ......................... 82
Debugging ........................................................ 70
Directory Search............................................... 82
Linking...............................................................79
Optimization Control ......................................... 71
Output Control...................................................62
Preprocessor Control........................................76
Warnings and Errors Control ............................64
-Os ...........................................................................71
Output Control Options ............................................62
-c.......................................................................62
-E ......................................................................62
--help.................................................................63
-o.......................................................................62
-S ......................................................................62
-v.......................................................................62
-x.......................................................................63
output files
names of......... ..... ...... ..... ..................................58
P
-P..............................................................................79
packed Attribute............................................... 83, 110
Packing Data Stored in Flash.................................137
Parameters, Function.............................................161
parameters, see function, parameters
PATH........................................................................53
-pedantic ............................................................ 64, 69
-pedantic-errors........................................................64
Peephole Optimization.............................................73
persist ent Attrib ute....................... ...... ..... ...... ......... 111
persist ent dat a................... ................. ..... ...... . 121, 188
PIC30_C_INCLUDE_PATH.....................................50
PIC30_COMPILER_PATH.......................................50
PIC30_LIBRARY_ PATH.........................................51
pic30-gcc..................................................................49
pointer............................................................ 147, 161
comparisons....................................................100
definitions.......................................................... 98
qualifiers............................................................98
types .................................................................98
Pointers....................................................................69
Frame.......................................................... 75, 82
Function.................................................. 142, 159
Stack.................................................................82
pointers ...............................................................98–??
assigning integers.............................................99
function .............................................................99
Predefined Constants..................................... 202, 273
prefix ........................................................................77
preprocessing.........................................................201
Preprocessi ng Direc tiv es ................... ..... ...... ..... ....217
Preprocessor Control Options..................................76
-A ......................................................................76
-C......................................................................76
-D......................................................................76
-dD....................................................................76
-dM....................................................................76
-dN....................................................................76
-fno-show-column .............................................76
-H......................................................................76
-I........................................................................77
-I-.......................................................................77
-idirafter.............................................................77
DS52071B-page 334 2012 Microchip Technology Inc.
MPLAB
®
XC16 C Compiler User’s Guide
-imacros ............................................................77
-include .............................................................77
-iprefix ............................................................... 77
-isystem.............................................................77
-iwithprefix.........................................................77
-iwithprefixbefore...............................................77
-M......................................................................78
-MD ...................................................................78
-MF....................................................................78
-MG...................................................................78
-MM...................................................................78
-MMD ................................................................78
-MQ...................................................................78
-MT....................................................................78
-nostdinc ...........................................................79
-P ......................................................................79
-trigraphs...........................................................79
-U......................................................................79
-undef................................................................79
preprocessor macros
predefined.........................................................46
Preserving Registers Across Function Calls..........163
Procedural Abstraction.............................................61
Processor ID ............................................................61
Program Memory Pointers............................. 142, 159
project nam e ...................... ...... ................. ..... ...... ....58
projects................................................................55–??
PSV Usage.................... ................ ...... ...... ..... ........139
PSV Window........... ...... ..... ...... .......125, 139, 142, 159
Q
-Q .............................................................................70
qualifier
__align ..............................................................38
__bank .............................................................. 37
__deprecate......................................................43
__eeprom..........................................................39
__far..................................................................34
__interrupt.........................................................39
__near...............................................................35
__pack ..............................................................42
__persistent ......................................................36
__section...........................................................43
__xdata ............................................................. 37
__ydata ............................................................. 37
auto.................................................................121
const ....................................................... 103, 128
volatile.............................................................103
Qualifiers................................................................216
qualifiers............................................................103–??
and auto variables...........................................121
and structures...................................................96
R
radix specifiers
C code.............................................................101
RAW Dependenc y.............. ...... ..... ...... ................. ....73
Reading, Reco mm en ded .... ................. ...... ..... ..........14
read-only variables.................................................103
real .........................................................................100
Reduce Code Size............................................. 60, 71
Register
Behavior..........................................................216
Definition Files...................................................85
register ...........................................................274, 275
registers
used by functions............................................148
replacing library modules .......................................209
Reset...................................................... 169, 180, 181
Return Type................... ..... ................. ...... ..... ...... ....65
Return Value ............................ ..... ...... ...... .............163
reverse Attrib ute....................... ..... ...... ...... ..... ........111
runtime sta rtup code...................... ................. ...... ..187
S
-S........................................................................62, 80
-s ..............................................................................81
-save-temps..............................................................71
Scalars ...........................................................142, 159
Scheduling................................................................73
section......................................................................72
section Attribute.......................111, 154, 157, 205, 275
secure Attribute....... ...... ..... ...... ................. .....112, 154
SFR.............................................................. 18, 54, 85
sfr Attribute.............................................................112
SFRs ........................................................................87
shadow Attribute ..................................... 155, 167, 205
short ......................................................... 94, 147, 161
Signals....................................................................219
signed ch ar.............. ...... ..... ...... ..... ................. ...... ....94
signed int...... ..... ...... ...... ..... ......................................94
signed lon g... ..... ...... ...... ..... ................. ...... ..... ..........94
signed lon g long................. ...... ................. ..... ...... ....94
signed sh ort.............................. ..... ...... ...... ...............94
Simulator, Command-Line............................ 18, 52, 53
size limits
const variables................................................128
Small Code Model..............................................18, 61
Small Data Model...............................................18, 62
Software Stack....................................... 121, 122, 155
source file s.............. ...... ..... ...... ................................52
space Attribute ............................................... 112, 205
Special Function Registers...............................54, 180
special function registers, see SFRs
Specifying Registers for Local Variables................275
-specs=.....................................................................82
SPLIM............................................................... 86, 121
Stack ......................................................................180
C Usage..........................................................122
Pointer (W15).......................82, 86, 121, 122, 187
Pointer Limit Register (SPLIM).......... 86, 121, 187
Software..................................................121, 122
Standard I/O Functions ............................................18
Startup
and Initialization ................................................57
Module, Alternate......................................57, 188
Module, Primary........................................ 57, 187
Modules...........................................................122
Statements.............................................................217
static.........................................................................83
static functi ons............... ..... ................. ...... ..... ...... ..149
static variables........................................................119
2012 Microchip Technology Inc. DS52071B-page 335
Index
storage dura tio n.......... ...... ..... ................. ...... ..... .... 118
Streams.................................................................. 220
strerror ................................................................... 222
string literals........................................................... 102
storage loc ati on .............. ...... ................. ..... .... 102
type of............................................................. 102
stru ct types, see structu res
structure..........................................................147, 161
structure bit-fields..................................................... 96
structure qualifiers.................................................... 96
Structures............................................................... 216
structures ................................................................. 96
bit-field s in............ ...... ..... ...... ................. ..... ...... 96
Suffix LL................................................................... 94
Suffix ULL ................................................................ 94
switch....................................................................... 66
symbol...................................................................... 81
Syntax Check........................................................... 64
Syntax for Writing ISRs.......................................... 167
system.................................................................... 221
System Header Files...........................................66, 78
T
-T.............................................................................. 85
TBLRD ................................................................... 140
temporary variables ............................................... 121
TMPDIR ................................................................... 51
tmpfile .................................................................... 221
-traditional .........................................................64, 158
Traditional C............................................................. 70
Translation ............................................................. 212
translation units........................................................52
transparent_union Attribute.................................... 114
Trigraphs.............................................................66, 79
-trigraphs.................................................................. 79
Type Conversion...................................................... 69
type conversions.................................................... 145
U
-U..................................................................76, 77, 79
-u.............................................................................. 81
U constant suffix .................................................... 101
ULL, Suffix ............................................................... 94
unamed bit-fields...................................................... 97
-undef....................................................................... 79
Underscore .....................................................167, 189
Unions.................................................................... 216
unions
qualifiers ........................................................... 96
unnamed structure members................................... 97
unordered Attribute................................................ 114
Unroll Loop............................................................... 74
unsigned char .......................................................... 94
unsigned int.............................................................. 94
unsigned long........................................................... 94
unsigned long long................................................... 94
unsigned long long int.............................................. 94
unsigned short ......................................................... 94
unsupported Attribute......................................114, 156
unused Attribute........................................67, 114, 156
Unused Function Parameter.................................... 67
Unused Variable.......................................................67
unused va riables
removing.........................................................103
USB........................................................................324
user_init Attribute...................................................156
User-Defined Data Section ....................................275
User-Defined Text Section............................. 157, 275
Using Inline Assembly Language...........................192
V
-v..............................................................................62
Variable Attrib ute s.............................. ..... ...... ..... ....107
variables
absolute ............................................................33
auto.................................................................121
static................................................................119
storage dura tio n..............................................118
Variables in Specified Registers ............................274
void.........................................................................147
volatile......................................................................83
volatile qualifier ......................................................103
W
-W....................................................64, 67, 68, 70, 223
-w .............................................................................64
W Registers....................... ..... ................. ...... . 161, 189
W14........................................................................122
W15........................................................................122
-Wa...........................................................................79
-Waggregate-return..................................................68
-Wall........................................................64, 67, 68, 70
Warnings................................................................242
Warnings and Errors Control Options......................64
-fsyntax-only......................................................64
-pedantic...........................................................64
-pedantic-errors.................................................64
-W .....................................................................68
-w......................................................................64
-Waggregate-return...........................................68
-Wall..................................................................64
-Wbad-function-cast..........................................68
-Wcast-align......................................................68
-Wcast-qual.......................................................68
-Wchar-subscripts.............................................64
-Wcomment.......................................................64
-Wconversion....................................................69
-Wdiv-by-zero....................................................64
-Werror..............................................................69
-Werror-implicit-function-declaration.................64
-Wformat...........................................................64
-Wimplicit ..........................................................64
-Wimplicit-function-declaration..........................64
-Wimplicit-int .....................................................64
-Winline.............................................................69
-Wlarger-than-...................................................69
-Wlong-long.......................................................69
-Wmain..............................................................65
-Wmissing-braces.............................................65
-Wmissing-declarations..................................... 69
-Wmissing-format-attribute................................69
-Wmissing-noreturn...........................................69
DS52071B-page 336 2012 Microchip Technology Inc.
MPLAB
®
XC16 C Compiler User’s Guide
-Wmissing-prototypes .......................................69
-Wmultichar.......................................................65
-Wnested-externs..............................................69
-Wno-long-long .................................................69
-Wno-multichar..................................................65
-Wno-sign-compare...........................................70
-Wpadded .........................................................69
-Wparentheses..................................................65
-Wpointer-arith ..................................................69
-Wredundant-decls............................................69
-Wreturn-type....................................................65
-Wsequence-point.............................................66
-Wshadow.........................................................69
-Wsign-compare................................................70
-Wstrict-prototypes............................................70
-Wswitch ...........................................................66
-Wsystem-headers............................................66
-Wtraditional......................................................70
-Wtrigraphs .......................................................66
-Wundef ............................................................70
-Wuninitialized...................................................67
-Wunknown-pragmas........................................67
-Wunused..........................................................67
-Wunused-function............................................67
-Wunused-label.................................................67
-Wunused-parameter........................................67
-Wunused-value................................................67
-Wunused-variable............................................67
-Wwrite-strings..................................................70
Warnings, Inhibit ......................................................64
Watchdog Timer.....................................................325
-Wbad-function-cast.................................................68
-Wcast-align .............................................................68
-Wcast-qual..............................................................68
-Wchar-subscripts .................................................... 64
-Wcomment..............................................................64
-Wconversion ...........................................................69
-Wdiv-by-zero...........................................................64
weak Attribute ............... ................................. 114, 156
Web Site, Microchip .................................................15
-Werror.....................................................................69
-Werror-implicit-function-declaration ........................64
-Wformat .....................................................64, 69, 153
-Wimplicit..................................................................64
-Wimplicit-function-declaration.................................64
-Wimplicit-int.............................................................64
-Winline ............................................................ 69, 158
-Wl............................................................................81
-Wlarger-than-..........................................................69
-Wlong-long..............................................................69
-Wmain.....................................................................65
-Wmissing-braces.....................................................65
-Wmissing-declarations............................................69
-Wmissing-format-attribute.......................................69
-Wmissing-noreturn..................................................69
-Wmissing-prototypes...............................................69
-Wmultichar..............................................................65
-Wnested-externs.....................................................69
-Wno- .......................................................................64
-Wno-deprecated-declarations.................................69
-Wno-div-by-zero......................................................64
-Wno-long-long.........................................................69
-Wno-multichar.........................................................65
-Wno-sign-compare............................................68, 70
-Wpadded.................................................................69
-Wparentheses.........................................................65
-Wpointer-arith..........................................................69
-Wredundant-decls...................................................69
-Wreturn-type ...........................................................65
Writing an Interrupt Service Routine ......................166
Writing the Interrupt Vector ....................................169
-Wsequence-point....................................................66
-Wshadow ................................................................69
-Wsign-compare.......................................................70
-Wstrict-prototypes...................................................70
-Wswitch...................................................................66
-Wsystem-headers...................................................66
-Wtraditional.............................................................70
-Wtrigraphs...............................................................66
-Wundef....................................................................70
-Wuninitialized..........................................................67
-Wunknown-pragmas.........................................66, 67
-Wunused...........................................................67, 68
-Wunused-function...................................................67
-Wunused-label........................................................67
-Wunused-parameter ...............................................67
-Wunused-value .......................................................67
-Wunused-variable...................................................67
-Wwrite-strings .........................................................70
X
-x ..............................................................................63
XC16_C_INCLUDE_PATH ......................................50
XC16_COMPILER_PATH........................................50
XC16_EXEC_PREFIX..............................................51
XC16_LIBRARY_ PATH ..........................................51
XC16_VERSION....................................................202
-Xlinker.....................................................................81
2012 Microchip Technology Inc. DS52071B-page 337
Index
NOTES:
DS52071B-page 338 2012 Microchip Technology Inc.
AMERICAS
Corporate Office
2355 West Chandler Blvd.
Chandler, AZ 85224-6199
Tel: 480-792-7200
Fax: 480-792-7277
Techn ica l Support:
http://www.microchip.com/
support
Web Address:
www.microchip.com
Atlanta
Duluth, GA
Tel: 678-957-9614
Fax: 678-957-1455
Boston
Westborough, MA
Tel: 774-760-0087
Fax: 774-760-0088
Chicago
Itasc a , IL
Tel: 630-285-0071
Fax: 630-285-0075
Cleveland
Independence, OH
Tel: 216-447-0464
Fax: 216-447-0643
Dallas
Addison, TX
Tel: 972-818-7423
Fax: 972-818-2924
Detroit
Farmington Hills, MI
Tel: 248-538-2250
Fax: 248-538-2260
Indianapolis
Noblesville, IN
Tel: 317-773-8323
Fax: 317-773-5453
Los A n ge les
Mission Viejo, CA
Tel: 949-462-9523
Fax: 949-462-9608
Santa Clara
Santa Clara, CA
Tel: 408-961-6444
Fax: 408-961-6445
Toronto
Mississauga, Ontario,
Canada
Tel: 905-673-0699
Fax: 905-673-6509
ASIA/PACIFIC
Asia Pacific Office
Suites 3707-14, 37th Floor
Tower 6, The Gateway
Harbour City, Kowloon
Hong Kong
Tel: 852-2401-1200
Fax: 852-2401-3431
Australia - Sydney
Tel: 61-2-9868-6733
Fax: 61-2-9868-6755
China - Beijing
Tel: 86-10-8569-7000
Fax: 86-10-8528-2104
China - Chengdu
Tel: 86-28-8665-5511
Fax: 86-28-8665-7889
China - Chongqing
Tel: 86-23-8980-9588
Fax: 86-23-8980-9500
China - Hangzhou
Tel: 86-571-2819-3187
Fax: 86-571-2819-3189
China - Hong Kong SAR
Tel: 852-2401-1200
Fax: 852-2401-3431
China - Nanjing
Tel: 86-25-8473-2460
Fax: 86-25-8473-2470
China - Qingdao
Tel: 86-532-8502-7355
Fax: 86-532-8502-7205
China - Shanghai
Tel: 86-21-5407-5533
Fax: 86-21-5407-5066
China - Shenyang
Tel: 86-24-2334-2829
Fax: 86-24-2334-2393
China - Shenzhen
Tel: 86-755-8203-2660
Fax: 86-755-8203-1760
China - Wuhan
Tel: 86-27-5980-5300
Fax: 86-27-5980-5118
China - Xian
Tel: 86-29-8833-7252
Fax: 86-29-8833-7256
China - Xiamen
Tel: 86-592-2388138
Fax: 86-592-2388130
China - Zhuhai
Tel: 86-756-3210040
Fax: 86-756-3210049
ASIA/PACIFIC
India - Bangalore
Tel: 91-80-3090-4444
Fax: 91-80-3090-4123
India - New Delhi
Tel: 91-11-4160-8631
Fax: 91-11-4160-8632
India - Pune
Tel: 91-20-2566-1512
Fax: 91-20-2566-1513
Japan - Osaka
Tel: 81-66-152-7160
Fax: 81-66-152-9310
Japan - Yokohama
Tel: 81-45-471- 6166
Fax: 81-45-471-6122
Korea - Daegu
Tel: 82-53-744-4301
Fax: 82-53-744-4302
Korea - Seoul
Tel: 82-2-554-7200
Fax: 82-2-558-5932 or
82-2-558-5934
Malaysia - Kuala Lumpur
Tel: 60-3-6201-9857
Fax: 60-3-6201-9859
Malaysia - Penang
Tel: 60-4-227-8870
Fax: 60-4-227-4068
Philippines - Manila
Tel: 63-2-634-9065
Fax: 63-2-634-9069
Singapore
Tel: 65-6334-8870
Fax: 65-6334-8850
Taiwan - Hsin Chu
Tel: 886-3-5778-366
Fax: 886-3-5770-955
Taiwan - Ka ohs iung
Tel: 886-7-536-4818
Fax: 886-7-330-9305
Taiwan - Taipei
Tel: 886-2-2500-6610
Fax: 886-2-2508-0102
Thailand - Bangkok
Tel: 66-2-694-1351
Fax: 66-2-694-1350
EUROPE
Austria - Wels
Tel: 43-7242-2244-39
Fax: 43-7242-2244-393
Denmark - Cop e nha gen
Tel: 45-4450-2828
Fax: 45-4485-2829
France - Paris
Tel: 33-1-69-53-63-20
Fax: 33-1-69-30-90-79
Germany - Munich
Tel: 49-89-627-144-0
Fax: 49-89-627-14 4-44
Italy - Milan
Tel: 39-0331-742611
Fax: 39-0331-466781
Netherlands - Drunen
Tel: 31-416-690399
Fax: 31-416-690340
Spain - Madrid
Tel: 34-91-708-08-90
Fax: 34-91-708-08 -91
UK - Wokingham
Tel: 44-118-921- 5869
Fax: 44-118-921-5820
Worldwide Sales and Service
11/29/11
