Release Notes for MPLAB^® C Compiler for PIC32 MCUs

v1.11(A)
May 2010

Table of Contents

1. Overview
2. GNU General Public License
3. Devices Supported
4. Installation
5. Compiler Documentation
6. What's New
7. Migration Issues
8. Documentation Updates
9. Fixed Issues
10. Limitations and Known Issues
11. Feature-Limited Editions and License Upgrades
12. Customer Support

1. Overview

   The 32-Bit language tools consist of a compiler (pic32-gcc.exe), an assembler (pic32-as.exe), a linker (pic32-ld.exe), and an archiver/ librarian (pic32-ar.exe). Additional tools distributed with this release include a binary to Intel[intl] Hex converter (pic32-bin2hex.exe) and miscellaneous binary utilities (pic32-strip.exe, pic32-strings.exe, pic32-readelf.exe, etc). In addition, the compiler utilizes a license manager (pic32-lm.exe) as part of the time-limited MPLAB C Compiler for PIC32 MCUs Standard Evaluation edition.

   As described in the user's guides, all of the language tools are sensitive to case on the command line, including the case of file names. In particular, the C compiler shell (pic32-gcc) requires that C source files be named on the command-line with a lower-case .c extension. If an upper-case .C filename extension is used, the compiler assumes that the file is a C++ file, which is not supported. Similarly, the compiler shell passes a file with an upper-case .S filename extension through the C preprocessor before passing it to the assembler, but it passes a file with a lower-case .s extension directly to the assembler.

2. GNU General Public License

   The MPLAB^® C Compiler for PIC32 MCUs tools are written and distributed under the GNU General Public License (GPL) which means that its source code is freely distributed and available to the public.

   The source for the tools under the GNU GPL may be downloaded separately from the Microchip WWW web page. You may read the GNU GPL in the file named COPYING located the docs subdirectory of your install directory. A general discussion of principles underlying the GPL may be found at www.gnu.org/copyleft.

   Support code provided for the header files, linker scripts, and runtime libraries are proprietary code and not covered under the GPL. See the full MPLAB C Compiler for PIC32 MCUs License Agreement for details.

3. Devices Supported

   The following PIC32MX devices are supported:

   Part Number	Part Number
   PIC32MX320F032H PIC32MX320F064H PIC32MX320F128H	. . PIC32MX320F128L
   PIC32MX340F128H PIC32MX340F256H PIC32MX340F512H	PIC32MX340F128L . .
   . .	PIC32MX360F256L PIC32MX360F512L
   PIC32MX420F032H	.
   PIC32MX440F128H PIC32MX440F256H PIC32MX440F512H	PIC32MX440F128L . .
   . .	PIC32MX460F256L PIC32MX460F512L
   PIC32MX534F064H	PIC32MX534F064L
   PIC32MX564F064H PIC32MX564F128H	PIC32MX564F064L PIC32MX564F128L
   PIC32MX575F256H PIC32MX575F512H	PIC32MX575F256L PIC32MX575F512L
   PIC32MX664F064H PIC32MX664F128H	PIC32MX664F064L PIC32MX664F128L
   PIC32MX675F256H PIC32MX675F512H	PIC32MX675F256L PIC32MX675F512L
   PIC32MX695F512H	PIC32MX695F512L
   PIC32MX764F128H	PIC32MX764F128L
   PIC32MX775F256H PIC32MX775F512H	PIC32MX775F256L PIC32MX775F512L
   PIC32MX795F512H	PIC32MX795F512L

   The PIC32MXGENERIC device is, as its name implies, a non-specific target that can be used to represent a generic core device.

4. Installation

   If using MPLAB IDE, be sure to install MPLAB IDE v8.10 or later before installing these tools.

   To install the MPLAB C Compiler for PIC32 MCUs tools, perform the following steps:

   1. Locate the setup program on the 'MPLAB C Compiler for PIC32 MCUs' CD ROM.
   2. Run the setup program.
   3. Follow the directions on the screen. To install the standard evaluation edition, leave the license-key field blank when prompted. To install the full standard edition, enter your full license key.
   4. If the installation program indicates that it is necessary, reboot your computer to complete the installation.
   5. When the installation is complete, verify that the executable directory has been correctly added to your PATH (i.e., if you chose to install the tools in the default directory, c:\Program Files\Microchip\MPLAB C32, then ensure that c:\Program Files\Microchip\MPLAB C32\bin has been added to your PATH. On some systems, the default path is c:\Program Files\Microchip\MPLAB C32 Suite.).

      From a Windows command prompt (cmd.exe), type: c:\>PATH

   To upgrade to a full standard-edition license from a lite or standard -evaluation edition license, follow the steps described in this section.

5. Compiler Documentation

   The following documents pertain to the MPLAB C Compiler for PIC32 MCUs. They may be installed in the compiler's doc subdirectory, but you should check Microchip's website for the latest revisions.

   • MPLAB^® C Compiler for PIC32 MCUs User's Guide (DS51686)
   • MPLAB^® 32-Bit Language Tools Libraries (DS51685)
   • Microchip PIC32MX Peripheral Library - Compiled Help (chm)
   • MPLAB^® MPLAB Assembler, Linker and Utilities for PIC32 MCUs User’s Guide (DS51833)

   Additional documentation on the GNU Assembler and Linker is available on the GNU Binutils v2.19 website.

6. What's New

   New Features in v1.11

   • Builtin functions for CP0 register access -- This release introduces a few new compiler builtin functions that simplify access to the PIC32 coprocessor 0 (CP0) registers. Combine these new builtin functions with macros defined in the cp0defs.h and p32xxxx.h header files for easy access to the various CP0 registers.

     In earlier compiler releases, the p32xxxx.h header file defined _mfc0/_mtc0 preprocessor macros that utilized extended inline assembly to generate the mfco and mtc0 instructions. These _mfc0 and _mtc0 macros are updated to utilize the new builtin funtions instead of inline assembly.

     NOTE: To access these CP0 registers, the compiler must generate assembly instructions (mfc0 & mtc0) that are supported in only the mips32 ISA mode. Therefore, when calling one of these functions from a mips16 function, the compiler must generate extra code to switch from mips16 mode back to the base mips32 mode before executing the instruction and then back to mips16 mode after executing the instruction.

     Read More...

     • unsigned int __builtin_mfc0(reg,sel)

       Returns the value from the CP0 register reg,sel. (Move From Coprocessor 0.) Both reg and sel must be immediate values.

       Example 1:
       val = __builtin_mfc0 (12,0);

       Example 2:
       #include <cp0defs.h>
       void funct (void) {
          unsigned int val;
          val = __builtin_mfc0 (_CP0_STATUS,_CP0_STATUS_SELECT);
       }

     • void __builtin_mtc0(reg,sel,value)

       Move value into the CP0 registerreg,sel. (Move To Coprocessor 0.) Both reg and sel must be immediate values.

       Example 1:
       __builtin_mtc0 (12,0,0x00100000u);

       Example 2:
       #include <cp0defs.h>
       void funct (void) {
          unsigned int val;
          /* code here */
          __builtin_mtc0 (_CP0_STATUS,_CP0_STATUS_SELECT,val);
       }

     • unsigned int __builtin_mxc0(reg,sel,value)

       Exchange/Swap value and the CP0 register reg,sel. Move value to the CP0 register reg,sel and return the previous value. Both reg and sel must be immediate values.

       Example 1:
       oldval = __builtin_mxc0 (12,0,0x00100000u);

       Example 2:
       #include <cp0defs.h>
       void funct (void) {
          unsigned int newval, oldval;
          /* code here */
          oldval = __builtin_mxc0 (_CP0_STATUS,_CP0_STATUS_SELECT,newval);
       }

     • unsigned int __builtin_bcc0(reg,sel,clr)

       Bit clear non-zero bits from clr in the CP0 register reg,sel and return the previous value of the CP0 register. Both reg and sel must be immediate values.

       Example:
       #include <cp0defs.h>
       void funct (void) {
          unsigned int clear, oldval;
          /* code here */
          oldval = __builtin_bcc0 (_CP0_STATUS,_CP0_STATUS_SELECT,clear);
       }

       This is equivalent to
          oldval = __builtin_mfc0 (_CP0_STATUS,_CP0_STATUS_SELECT);
          __builtin_mtc0 (_CP0_STATUS,_CP0_STATUS_SELECT, oldval & ~(clear));
       but the bcc0 builtin may generate more efficient code, especially when called from mips16 mode.

     • unsigned int __builtin_bsc0(reg,sel,set)

       Bit set non-zero bits from set in the CP0 register reg,sel and return the previous value of the CP0 register. Both reg and sel must be immediate values.

       Example:
       #include <cp0defs.h>
       void funct (void) {
          unsigned int set, oldval;
          /* code here */
          oldval = __builtin_bsc0 (_CP0_STATUS,_CP0_STATUS_SELECT,set);
       }

       This is equivalent to
          oldval = __builtin_mfc0 (_CP0_STATUS,_CP0_STATUS_SELECT);
          __builtin_mtc0 (_CP0_STATUS,_CP0_STATUS_SELECT, oldval | (set));
       but the bsc0 builtin may generate more efficient code, especially when called from mips16 mode.

     • unsigned int __builtin_bcsc0(reg,sel,clr,set)

       Bit clear non-zero bits from clr and bit set non-zero bits from set in the CP0 register reg,sel. Return the previous value of the CP0 register. Both reg and sel must be immediate values.

       Example:
       #include <cp0defs.h>
       void funct (void) {
          unsigned int clr, set, oldval;
          /* code here */
          oldval = __builtin_bcsc0 (_CP0_STATUS,_CP0_STATUS_SELECT,clr,set);
       }

       This is equivalent to
          oldval = __builtin_mfc0 (_CP0_STATUS,_CP0_STATUS_SELECT);
          __builtin_mtc0 (_CP0_STATUS,_CP0_STATUS_SELECT, (oldval & ~(clr)) | (set));
       but the bcsc0 builtin may generate more efficient code, especially when called from mips16 mode.

   • Upgrade to binutils v2.19 -- The MPLAB Assembler, Linker, and Utilities for PIC32 MCUs are now based on GNU Binutils v2.19. This platform upgrade includes a few new features and bug fixes.

     • Assembler
       • Macros with a variable number of arguments are now supported. See the Binutils documentation for more information.
       • A redefinition of a macro now results in an error.
       • The assembler sources are now released under version 3 of the GNU General Public License.
     • Linker
       • Added a new linker command-line switch, --sort-section name|alignment, to sort sections by section name or maximum alignment.
       • Added SORT_BY_NAME and SORT_BY_ALIGNMENT to the linker script language to permit sorting sections by section name or section maximum alignment.
       • New switch: --print-gc-sections to list any sections removed by garabge collection.
       • Addded a new command-line option '--default-script=FILE' or '-dT FILE' which specifies a replacement for the built-in, default linker script.
       • Linker scripts support a new INSERT command that makes it easier to augment the default script.
       • Linker-script input-section filespecs may now specify a file within an archive by writing "archive:file".
       • The --sort-common switch now has an optional argument which specifies the direction of sorting.
       • The Linker sources are now released under version 3 of the GNU General Public License.
     • Binary Utilities
       • pic32-readelf can now display address ranges from .debug_range sections. This happens automatically when a DW_AT_range attribute is encountered. The command line switch --debug-dump=Ranges (or -wR) can also be used to display the contents of the .debug_range section.
       • pic32-objcopy recognizes two new options, --strip-unneeded-symbol and --strip-unneeded-symbols, namely for use together with the wildcard matching the original --strip-symbol/--strip-symbols provided, but retaining any symbols matching but needed by relocations.
       • Added -g/--section-groups to pic32-readelf to display section groups.
       • Added --globalize-symbol <name> and --globalize-symbols <filename> switches to pic32-objcopy to convert local symbols into global symbols.
       • Added -t/--section-details to pic32-readelf to display section details
       • Added -W/--dwarf to pic32-objdump to display the contents of the DWARF debug sections.
       • Added -wL switch to dump decoded contents of .debug_line.
       • Added -F switch to pic32-objdump to include file offsets in the disassembly.
       • Added -c switch to pic32-readelf to allow string dumps of archive symbol index.
       • Added -p switch to pic32-readelf to allow string dumps of sections.
       • The Binutils sources are now released under version 3 of the GNU General Public License.

   • RIPL Interrupt Priority Level specifier -- The v1.10 release introduced new Interrupt Priority Level specifiers. It also introduced a new default IPL behavior when the IPL specifier was omitted from the interrupt attribute. (See New Features in v1.10 below for more information.)

     The v1.11 release introduces an explicit specifier (RIPL) for this default behavior. You may use this RIPL specifier in either the interrupt pragma or the interrupt attribute to tell the compiler to use the runtime Requested Interrupt Priority Level from the CAUSE register as the new IPL.

     • Example 1:

       #pragma interrupt Timer1IntHandler RIPL vector 4

     • Example 2:

       void __attribute__((interrupt(RIPL), vector(1))) myISR (void)) { /* code */ }

   New Features in v1.10

   • Compiler licenses renamed -- The feature-limited compiler licenses have been renamed. The academic version is now the MPLAB C Compiler for PIC32 MCUs Lite edition. The evaluation version is now the MPLAB C Compiler for PIC32 MCUs Standard Evaluation edition. The full version is now the MPLAB C Compiler for PIC32 MCUs Standard edition (Part Number: SW006015). This is a name change only. See this section for more information on the features available for each edition.

   • Smart I/O -- This release introduces a new -msmart-io=[0|1|2] command-line option. This feature attempts to statically analyze format strings passed to printf, scanf, and the 'f' and 'v' variations of these functions. Uses of non floating-point format arguments will be converted to use an integer-only variation of the library function. For many applications, this feature can reduce program-memory usage.

     -msmart-io=0 disables this option, while -msmart-io=2 causes the compiler to be optimistic and convert function calls with variable or unknown format arguments. -msmart-io=1 is the safe default and will convert only when the compiler can prove that floating-point support is not required.

   • Interrupt Context-Saving Improvements -- New PIC32 devices introduced in this release (PIC32MX5, PIC32MX6, PIC3MX7) allow us to select, via configuration fuses, which priority will use the shadow register set. (Refer to the device datasheet to determine if your PIC32 device supports this feature.) This means that we must specify which context-saving mechanism to use for each interrupt service routine. We specify the mechanism as part of the IPL specifier passed in the interrupt attribute, __attribute__((interrupt([IPLn[AUTO|SOFT|SRS]]))), where n is in the range of 0..7, inclusive.

     NOTE: An incorrect IPLn value can cause incorrect nesting of interrupts, which could result in a stack overflow and eventually a bus-error exception. If you experience a bus-error exception related to an interrupt, double check that your IPLn value matches the IPL value set for the interrupt source.

     Read More...

     • IPL Specifiers

       • IPLnAUTO -- The compiler supports an IPLnAUTO IPL specifier that uses the runtime value in SRSCTL to determine whether it should use software or SRS context saving. The interrupt context-saving code generated for this specifier has a slightly higher latency, compared to IPLnSOFT or IPLnSRS, due to the instructions required to test the SRSCTL value. Example:
         void __attribute__((interrupt(IPL6AUTO), vector(1))) myISR (void)) { /* code */ }

       • IPLnSOFT -- The compiler will use software context saving for the IPLnSOFT specifier. Application code is responsible for applying the correct n interrupt-source priority value to the matching handler routine. Example:
         void __attribute__((interrupt(IPL6SOFT), vector(1))) myISR (void)) { /* code */ }

       • IPLnSRS -- The compiler will generate interrupt prologue and epilogue code utilizing shadow-register context saving for IPLnSRS. This IPL specifier results in the shortest interrupt context-saving latency. However, when using IPLnSRS, you must configure the corresponding interrupt source to use a shadow register set. On some devices, the shadow register set is tied to IPL7. On other devices, the shadow register set is configurable in a device configuration register (DEVCFG). Example:
         void __attribute__((interrupt(IPL6SRS), vector(1))) myISR (void)) { /* code */ }
         

       • single -- For single-vector interrupt mode, use single as the IPL parameter passed to the interrupt attribute. Example:
         void __attribute__((interrupt(single), vector(1))) myISR (void)) { /* code */ }

       • Default -- The compiler defaults to selecting the IPL value and shadow-register usage at runtime when the IPL specifier is omitted from the interrupt() attribute. Omitting the IPL specifier results in slightly larger interrupt context-saving latency. For mult-vector interrupt mode where the requested IPL value may change at runtime, use this default behavior. Example:
         void __attribute__((interrupt(), vector(1))) myISR (void)) { /* code */ }

     • Updated __ISR Macro -- The IPL specifier argument to the __ISR() macro, defined in <sys/attribs.h>, is now optional. With the IPL specifier omitted, the compiler defaults to selecting the IPL value and shadow-register usage at runtime.

       • Example 1
         void __ISR(_CORE_SOFTWARE_0_VECTOR, IPL3SRS) CoreSoftwareInt0Handler(void)
         This example creates an interrupt handler function for the core software interrupt 0 that has an interrupt priority level of three. The compiler places a dispatch function at the associated vector location. To reach this function, the core software interrupt flag and enable bits must be set, and the interrupt priority should be set to a level of three. The device configuration fuses must assign Shadow Register Set 1 to interrupt priority level three. The compiler generates code that assumes that register context will be saved in SRS1.

       • Example 2
         void __ISR(_CORE_SOFTWARE_0_VECTOR) CoreSoftwareInt0Handler(void)
         This example creates an interrupt handler function for the core software-interrupt 0 and uses the interrupt priority level from the runtime-requested IPL value. The compiler generates code that determines, at runtime, whether context should be saved on the stack by software or context was already saved in a shadow register set.

     • Latency improvements -- The interrupt context saving code has also been modified to improve latency. For instance, the HI/LO register saving code, when required, now appears later in the ISR prologue. This helps reduce stalls when an interrupt occurs during a DIV (divide) instruction.

   • APPIN/APPOUT Debugging Support -- New PIC32 devices being introduced in v1.10 (5XX, 6XX, 7XX) support the APPIN/APPOUT debugging feature. This PIC32 feature allows the target application to write text or data to an MPLAB IDE window without halting the target device. Similarly, you may use the display window to send text or data back to the target PIC32 device. This feature requires an MPLAB REAL ICE emulator or an MPLAB ICD 3 debugger.
     

     Read More...

     • -mappio-debug -- Use this command-line option to enable the APPIN/APPOUT debugging library functions for the ICD 3 debugger and REAL ICE emulator. This feature allows you to use the DBPRINTF and related functions and macros. Enable this option only when using a target PIC32 device that supports the APPIN/APPOUT feature.
     • Example Code --

       #include <p32xxxx.h>
       int main (void)
       {
           int num;
           char buf[256] ={0};
           DBINIT();
       
           while(1)
           {
             DBPRINTF ("Hello there!\n");
             DBPRINTF ("Enter a string\n");
       #if defined(__APPIO_DEBUG)
             DBSCANF ("%s", &buf[0]);
       #elif defined(PIC32_STARTER_KIT)
             DBGETS  (&buf[0],128);
       #endif
             DBPRINTF ("Entered \"%s\"\n\n", &buf[0]);
       
             printf ("Prints to UART2 by default or APPO when enabled\n");
           }
         return 0;
       }
       

   • Stack Limit symbol in built-in linker script -- The default linker script now provides an _SPLIM symbol that you can use from code to help detect a stack overflow at runtime. This symbol is associated with the lowest address of the space reserved for the stack.

     Read More...

     • Example Code --

       #include <stddef.h>
       #define _STACK_DEBUG 1
       #if (_STACK_DEBUG)
       #define stackcheck() _stackcheck(__FILE__, __LINE__)
       
       static inline __attribute__((always_inline))
       ptrdiff_t _stackcheck(const char *filename, unsigned int linenum)
       {
         extern void _SPLIM; /* From linker script */
       
         register void* stackptr __asm__("$sp");
       
         /* Compare the current stack pointer with the Stack Pointer Limit symbol, _SPLIM */
         if ((ptrdiff_t)stackptr <= (ptrdiff_t)&_SPLIM)
           {
               /* Handle stack overflow */
               while(1);
           }
         return ((ptrdiff_t)stackptr - (ptrdiff_t)&_SPLIM);
       }
       #else
       #define stackcheck() (void)0
       #endif
       
       unsigned char foo(unsigned char var);
       volatile unsigned int testval;
       
       int main (void)
       {
           unsigned char array[0x7A50];
           testval = 0;
       
           array[0] = 1;
           foo (array[0]);
       
           testval = 1;
           while(1);
       }
       unsigned char
       foo(unsigned char var)
       {
           stackcheck();
           return var+1;
       }
       

   • Predefined macro for Feature Set -- The compiler predefines a macro based on the features available for the selected device. These macros are intended to be used when writing code to take advantage of features available on newer devices while maintaining compatibility with older devices.

     Read More...

     • Examples
       PIC32MX795F512L would use __PIC32_FEATURE_SET__ == 795, and
       PIC32MX340F128H would use __PIC32_FEATURE_SET__ == 340.
       
       
     • Example Code --

       #if ((__PIC32_FEATURE_SET__ >= 500) &&
            (__PIC32_FEATURE_SET__ <= 799))
          { /* do stuff for 5XX, 6XX, 7XX families */ }
       #elif ((__PIC32_FEATURE_SET__ >= 300) &&
              (__PIC32_FEATURE_SET__ <= 499))
          { /* do stuff for 3XX, 4XX families */ }
       #elif ((__PIC32_FEATURE_SET__ >= 800) &&
              (__PIC32_FEATURE_SET__ < 1000))
          { /* do stuff for some future family */ }
       #endif
       
       

       
       
       

   New Features in v1.05

   • Student Edition renamed Evaluation Version -- The student edition has been renamed the evaluation version. This release also introduces a new academic version. For more information on the feature-limited version, see this section. (Note that the licenses have been renamed again for the v1.10 release.)
   • Improved 16- and 32-bit FFT functions in the DSP Library -- The FFT functions have been significantly improved and optimized for the PIC32 instruction set. See the 32-bit Language Tools Libraries document (DS51685) for more information. Please visit Microchip's website for the revision C of this document (DS51685C).
   • Binary Constants -- A sequence of binary digits preceded by 0b or 0B (the numeral '0' followed by the letter 'b' or 'B') is taken to be a binary integer. The binary digits consist of the numerals '0' and '1'. Note that this binary-constant syntax may not be accepted by other C compilers.
   • Linker Memory-Usage Report -- This optional, informational report allows you to easily determine the program- and data-memory usage of your application. It allows you to see how much space is used by the project being linked and how much space is available on the target device. The memory-usage report appears on stdout and in the optional map file.
     • Using this feature with MPLAB IDE 8.30 and earlier -- On the linker's tab of the project build options, select to Use Alternate Settings. Add the --report-mem option to the Alternate Settings field. The memory-usage report will appear in the output window after a project build. (This option will appear as a checkbox in later MPLAB IDE releases.)
     • Using this feature on the command prompt -- Add the --report-mem option to the linker's command line. If you are calling the linker via the compilation driver, use the driver's -Wl option to pass the --report-mem option to the linker. The memory-usage report will appear on stdout.
   • Improved malloc implementation -- This release contains a new malloc/free/realloc implementation based on the implementation written by Doug Lea and released to the public domain.
     • This is not the fastest, most space-conserving, most portable, or most tunable malloc ever written. However it is among the fastest while also being among the most space-conserving, portable and tunable. Consistent balance across these factors results in a good general-purpose allocator.
     • For a high-level description, see http://g.oswego.edu/dl/html/malloc.html
     • This implementation is also provided with the Newlib C Library.
   • Instruction Macros -- The p32xxxx.h include file now contains a Nop() macro that issues a superscalar SSNOP instruction.
   • gettimeofday() weak stub -- The time.h clock() and time() functions require a user-provided gettimeofday() helper function. The compiler's library now provides a weak stub implementation that allows the project link to complete without error, but you should provide your own implementation appropriate for your application.
   • Microchip DSP Compatibility Wrapper functions -- This release provides new DSP wrapper functions intended to ease the migration from the Microchip DSP library for dsPIC DSCs to the general DSP library for PIC32 MCUs. See the 32-Bit Language Tools Libraries (DS51685C) document for more information on these new wrapper functions.
   • Updated peripheral-library documentation -- The 32-bit peripheral library document is now distributed as a compiled help file (*.chm) rather than a PDF file.
   • Support for PWP configuration bits -- The config pragma now supports enabling the Program Write Protect bits. See the PIC32MX Config Settings help file for information on the setting name and available values for each device.

7. New Features in v1.04

   • General DSP Library -- The DSP Library supports a variety of signal processing functions that have applicability in speech compression, echo cancellation, noise cancellation, channel equalization, audio decoding, and many other DSP and media applications. The library is highly optimized for the PIC32 MCU instruction set.
     • The DSP Library expects Q-type fixed-point arguments and produces Q-type results. The MPLAB C Compiler for PIC32 MCUs does not currently support converting float or double types to Q-types.
     • See the 32-Bit Language Tools Libraries (DS51685) for documentation on the DSP Library functions.
     • In the near future, a "dsPIC DSC DSP Algorithm Library" compatibility layer will be available. This compatibility layer makes the PIC32 DSP Library backwards compatible with the existing dsPIC DSC DSP Algorithm Library.
   • Vector attribute accepts parenthesized list of vector numbers -- The interrupt vector attribute now accepts a parenthesized list of one or more interrupt vector numbers. This means that you can now more easily generate multiple dispatch functions that target a single interrupt service routine as shown in the example below.
     #include <p32xxxx.h>
     #include <sys/attribs.h>
     void __ISR((_TIMER_1_VECTOR,_TIMER_2_VECTOR,_TIMER_3_VECTOR),ipl6) TimerISR(void);
   • Interrupt service routines forced to nomips16 -- The compiler will now force functions marked with the interrupt attribute to be nomips16. The compiler will emit a warning if it overrides the mips16 attribute or command-line default. Previous compiler releases stopped compilation with an error and required users to manually add the nomips16 attribute. Note that you should use the __ISR macro from the sys/attribs.h header rather than manually specify the interrupt attribute.
   • Trigonometric function refactorization -- A few trigonometric functions have been refactored for a smaller code-size footprint.

   New Features in v1.03

   • Optimized math library -- The floating-point math library provided with the compiler has been significantly optimized to take full advantage of the PIC32MCU instruction set. The improved library provides the greatest benefit for the more complex operations, offering a greater than 5x performance improvement over the 1.02 library for many operations and an even more significant improvement for some operations. In addition, single-precision math library functions are now available, giving users a choice between double- and single-precision operations. See math.h for more information.

   • Time-Limited Evaluation Version -- The new evaluation version provides full functionality for 60 days. After the evaluation version has expired, the compiler becomes feature limited. See this section for further details. (Note that this license has been renamed to the "Standard Evaluation Edition" for the v1.10 release.)

   • __C32_VERSION__ predefined macro -- The C compiler defines the constant __C32_VERSION__, giving a numeric value to the version identifier. This macro can be used to construct applications that take advantage of new compiler features while still remaining backward compatible with older versions. The value is based upon the major and minor version numbers of the current release. For example, release version 1.03 will have a __C32_VERSION__ definition of 103. This macro can be used, in conjunction with standard preprocessor comparison statements, to conditionally include/exclude various code constructs.

   • __ISR_SINGLE__ and __ISR_SINGLE_AT_VECTOR__ convenience macros -- The sys/attribs.h header file now provides two new macros intended to simplify the use of the single-vector interrupt mechanism. See the sys/attribs.h header file for more information.
     • The __ISR_SINGLE__ macro specifies a function as an interrupt-service routine in single-vector mode. This will place a jump at the single-vector location to the interrupt handler.
     • The __ISR_SINGLE_AT_VECTOR__ macro places the entire single-vector interrupt handler at the vector 0 location. The user is responsible for ensuring that the vector spacing is set to accommodate the size of the handler.

8. Migration Issues

   The following changes may affect migration from older versions of the compiler.

   Migrating to Version v1.11

   • Linker
   • • Allocation of orphan sections -- Orphan sections are sections present in the input files which are not explicitly placed into the output file by the linker script. The linker will still copy these sections into the output file, but it has to guess as to where they should be placed. The linker uses a simple heuristic to do this. It attempts to place orphan sections after non-orphan sections of the same attribute, such as code vs data, loadable vs non-loadable, etc. If there is not enough room to do this then it places at the end of the file.

       If an orphaned section's name is representable as a C identifier then the linker will automatically PROVIDE two symbols: __start_SECNAME and __end_SECNAME, where SECNAME is the name of the section. These indicate the start address and end address of the orphaned section respectively. Note: most section names are not representable as C identifiers because they contain a `.' character.

       Note: In previous releases, the linker allocated orphan sections at a high address, after all other sections had been allocated. This is no longer the case and applications should not rely on orphan sections being uninitialized.

   • Default Linker Script
   • • New .persist section -- The default linker script now provides a .persist section between the .stack section and the .ramfunc section. This section is not initialized or zeroed on startup. If your project used a custom section for this purpose, you can now utilize this new .persist section that is specifically mapped outside of the .bss and .data sections.
       
       Example:
       unsigned int __attribute__((section(".persist"))) flag;

   Migrating to Version v1.10

   • Interrupt context saving
     • IPL specifier -- In prior compiler releases, the interrupt service-routine prologue code determined the IPL value from the runtime RIPL value. This meant that the IPL specifier value in the interrupt attribute or interrupt pragma did not have to exactly match the actual IPL value for the interrupt source. The interrupt service routine worked correctly, even when there was a discrepancy in the IPL value.

       The interrupt prologue code generated by this release of the compiler uses the IPL value as specified in the interrupt attribute or interrupt pragma. An incorrect IPLn value can cause incorrect nesting of interrupts, which could result in a stack overflow and eventually a bus-error exception. If you experience a bus-error exception related to an interrupt, double check that your IPLn value matches the IPL value set for the interrupt source.

       Some applications may require an interrupt priority that changes at runtime. In this case, omit the IPL specifier from the interrupt attribute as shown in the examples below. e.g.
         void __attribute__((interrupt(), vector(1))) myISR1 (void)) { /* code */ }
         void __ISR(_CORE_SOFTWARE_0_VECTOR) CoreSoftwareInt0Handler(void) { /* code */ }

       Currently, the interrupt pragma does not support interrupt priority levels that change at runtime. In this case, convert the interrupt pragma to an interrupt attribute as described above. For instance:

       #pragma interrupt foo ipl3 vector 4
       void foo (void) { /* code */ }
       

       becomes

       void __attribute__((interrupt(), vector(4))) foo (void) { /* code */ }
       

   • STDIO
     • BUFSIZ -- The input buffer size has been reduced from 1024 to 64 bytes. Use the setvbuf() function to specify another buffer if your application requires a buffer of another size.
     • STDOUT_BUFSIZ -- The stdout default-buffer size has been reduced from 128 bytes to 32 bytes. Use the setvbuf() function to specify another buffer if your application requires a buffer of another size.
   • Device support
     • PIC32MX4xx devices -- The UPLLIDIV configuration fuse settings were incorrectly named DIV_7 and DIV_8 for several PIC32MX4XX devices. They are now correctly named DIV_10 and DIV_12, respectively. Code using the older names will fail to compile. Update your code to use the new setting names.
   • Documentation
     • Peripheral Library documentation now provided as a help file -- The peripheral library documentation is now provided as a CHM file rather than a PDF file. Older versions of the compiler installer added a link to the PDF file in MPLAB IDE's online help. To remove this outdated link, run the uninstall facility in Windows Add/Remove Programs to completely uninstall the compiler. Then re-run the v1.10 compiler installer.

   Migrating to Version v1.05

   • DSP Library
     • FFT setup functions -- The FFT setup functions, mips_fft16_setup() and mips_fft32_setup(), are now deprecated. The FFT functions now load precalculated coefficients so these setup functions are no longer required. Please visit Microchip's website for the revision C of the 32-bit Libraries document (DS51685C).

   Migrating to Version v1.04

   • Device-support files
     • Device specific IRQ macro definitions -- The IRQ macro definitions, such as _CORE_TIMER_IRQ, have moved from the ppic32mx.h header file to the device-specific header file (e.g. proc/p32mx460f512l.h). This change should not affect most applications because they should include the generic p32xxxx.h file.

   Migrating to Version v1.03

   • Peripheral Library
     • Modified SYSTEMConfigXXX functions to use revised flash speed of 30 MHz. If you are currently using a SYSTEMConfigXXX function, your application will automatically use the new flash-speed specification.
   • Examples
     • Modified all plib_examples to use SYSTEMConfig() function. This function allows users to selectively configure certain parameters only.

   Migrating to Version v1.02

   • Processor Header files
     • Removed Extended Mode (XM bit) in DMA controller
   • Peripheral Library - See the Microchip PIC32MX Peripheral Library compiled help (*.chm) for details
     
     • DMA Extended mode is removed. The maximum transfer length is now 256 bytes, even for memory copy and CRC functions.
     • Symbols DMA_OPEN_NORM and DMA_OPEN_EXT used in the DmaChnOpen() call were removed. A new symbol, DMA_OPEN_DEFAULT was added.
       
     • A new function, DmaGetMaxTcferSize() was added, to return the maximum supported size of a transfer, variant dependent. Right now, only 256 bytes transfer size supported.
       
     • DmaChnSetExtTxfer() was removed, no longer relevant.
       
     • DMA_CTL_EXT_EN was removed from the low level access routines
     • SYSTEMConfig() function was added to enable user-specified configuration for a given system frequency.

9. Documentation Updates

   Library documentation updates

   This section describes pending updates to the MPLAB^® 32-Bit Language Tools Libraries documentation. These changes will be incorporated into the next full revision of the documents.

   • BUFSIZ -- The BUFSIZ definition in stdio.h has been reduced to 64.

   Compiler documentation updates

   This section describes pending updates to the MPLAB C Compiler for PIC32 documentation. These changes will be incorporated into the next full revision of the documents.

   • Binary Constants -- A sequence of binary digits preceded by 0b or 0B (the numeral '0' followed by the letter 'b' or 'B') is taken to be a binary integer. The binary digits consist of the numerals '0' and '1'. For example, the (decimal) number 255 can be written as 0b11111111. Like other integer constants, a binary constant may be suffixed by the letter 'u' or 'U', to specify that it is unsigned. A binary constant may also be suffixed by the letter 'l' or 'L', to specify that it is long. Similarly, the suffix 'll' or 'LL' denotes a long long binary constant. Note that this binary-constant syntax may not be accepted by other C compilers.
   • __VERSION__ predefined macro -- The __VERSION__ macro expands to a string constant describing the compiler in use. Do not rely on its contents having any particular form, but it should contain at least the release number. Use the __C32_VERSION__ macro for a numeric version number.
   • Interrupt-vector macros -- Each processor-support header file (e.g. \pic32mx\include\proc\p32mx360f512l.h) provides a macro for each interrupt-vector number. When used in conjunction with the __ISR() macro provided by the sys\attribs.h header file, these macros help make an interrupt service routine easier to write and maintain. Example: void __ISR (_TIMER_1_VECTOR, ipl7) Timer1Handler (void);

10. Fixed Issues

    The following issues have been resolved in this release

    Fixed in v1.11(A)

    BIN32-62:

    The default linker script now discards the unnecessary ".rel.dyn" output section. Previously, this section could cause the linker and pic32-bin2hex utility to generate an invalid hex file. When importing this invalid hex file, MPLAB IDE v8.xx would display an error indicating "The parameter is incorrect."

    Fixed in v1.11

    C32-318:

    IPLnSOFT interrupts nested in IPLnSRS interrupts now preserve the stack pointer across register sets. Previously, nested interrupts with shadow register set 1 assigned to a lower priority ISR (e.g. IPL1SRS) could cause stack pointer corruption. The most common symptom of stack corruption is a general exception after returning from the ISR. Thanks to A. Chen for reporting this issue via http://support.microchip.com

    C32-314:

    The default general-exception context-saving code now allocates sufficient stack space for the number of general registers that it saves. The previous default code did not allocate sufficient space and resulted in stack corruption following a general exception. This made recovering from a general exception impossible when using the default context-saving code.

    C32-312:

    The compiler no longer generates an extraneous instruction a function epilogue for non-interrupt function where no additional stack space needs to be deallocated. The v1.10 release incorrectly generated a useless addiu sp,sp,0 instruction. Thanks to Slawek Piotrowski for reporting this issue on the Microchip web forum.

    C32-300:

    The compiler now maintains an 8-byte alignment for the stack pointer for all functions including interrupt service routines. In prior compiler releases, when a function taking a variable number of arguments was called from an interrupt service routine and an 8-byte variable was passed as an argument, the generated code could cause a general exception. Thanks to Leon van Snippenberg of AVIX for reporting this issue.

    C32-298:

    A constant infinite loop within an IPLxAUTO interrupt service routine no longer causes an internal compiler error.

    C32-297:

    The CP0 access macros in cp0defs.h no longer cause an exception when used in a mips16 function. These access macros now use the new CP0 builtin functions described in the New Features in v1.11 section above.

    C32-292:

    The compiler now properly ignores the -mips16 and higher-level optimization options when they are passed together to a compiler operating with a limited-functionality license such as a lite-mode license or an expired standard evaluation license. Previous releases emitted a correct warning followed by an incorrect error.

    BIN32-44:

    The pic32-size utility now reports the size of COMMON section correctly as part of the bss section usage.

    Fixed in v1.10

    C32-267:

    The '0' (zero-fill) flag for the output-format conversion specifiers (used with the printf functions), now properly causes zero filling when used with floating-point conversions. (e.g. printf("%010.2f",foo); )

    C32-266:

    A 'naked' attributed function containing a function call no longer causes a compiler crash when building with optimizations enabled.

    C32-252:

    The SoftReset() peripheral library function now works correctly on devices that do not use DMA, such as the PIC32MX320F032H.

    C32-224:

    In stdlib.h, MB_CUR_MAX is now correctly defined as 1.

    DAYHLD-10:

    The UPLLIDIV configuration fuse settings were incorrectly named DIV_7 and DIV_8 for several PIC32MX4XX devices. They are now correctly named DIV_10 and DIV_12, respectively.

    Fixed in v1.05

    C32-064:

    Code generated using -Os -mips16 and a very large number of common subexpressions now compiles correctly.

    C32-232:

    Interrupt context-saving code now preserves the assembler temporary ($at) register. While the compiler does not use this register for standard C code, the general DSP library or the optimized math library use this register.

    Peripheral Library:

    The peripheral-library source files listed below contain fixes and improvements. See the updated peripheral-library documentation for further details.

    • pic32mx/include/peripheral/int.h
    • pic32mx/include/peripheral/incap.h
    • pic32mx/include/peripheral/nvm.h
    • pic32mx/include/peripheral/dma.h
    • pic32mx/include/peripheral/ports.h
    • pic32mx/include/peripheral/uart.h
    • pic32mx/include/peripheral/i2c.h
    • pic32mx/include/peripheral/outcompare.h
    • pic32mx/include/peripheral/cmp.h
    • pic32mx/include/peripheral/timer.h
    • pic32mx/include/peripheral/reset.h
    • pic32mx/include/peripheral/pcache.h
    • pic32mx/include/peripheral/system.h
    • pic32mx/include/peripheral/bmx.h
    • pic32-libs/peripheral/nvm/source/nvm_operation_lib.c
    • pic32-libs/peripheral/i2c/source/idle_i2c2_lib.c

    C32-42:

    The compiler now emits a more useful diagnostic message when multiple -mprocessor options appear on the command line.

    Fixed in v1.04

    No significant fixed issues for this release

    Fixed in v1.03

    BIN32-30:

    Assertion statements in the linker scripts now correctly compare the size of an exception vector to the vector spacing.

    C32-179:

    The gmtime() library function now links without error. In previous releases, the linker would complain about an undefined reference to 'offtime_r'

    C32-172:

    The config pragma now defaults the DEVCFG0 MSb to zero.

    C32-171:

    The first call to getchar() now calls _mon_getc(). The previous implementation treated the initial STDIN character as an ungetc() pushed-back character.

    C32-164:

    The device-specific header files now use '__asm__' rather than 'asm' when mapping each SFR struct to it's symbol name. Previous versions of these files did not compile when building with the compiler's -ansi option.

    C32-147:

    The interrupt attribute now properly accepts an uppercase IPLx value. Earlier compiler versions could reject the uppercase IPLx with an internal error.

    Fixed in v1.02

    C32-119:

    Removed pipeline interlock in ISR handling

    C32-141:

    Large malloc() calls no longer generate a general exception vector instead of returning a NULL pointer.

    C32-144:

    Interrupt macro now sets nomips16

    C32-145:

    Include C startup code source is now provided in the standard distribution

    C32-151:

    IPL7 prologue code now sets incorrect bits in status register

11. Limitations and Known Issues

    The current limitations are as follows.

    Compiler

    No significant issues reported.

    Assembler

    No significant issues reported.

    Linker

    BIN32-58

    The linker may emit an unfriendly error message when it encounters a case where it cannot switch ISA modes between mips16 and mips32 in a function call. The error message is "jump to stub routine which is not jal". This condition can occur when a mips32 function's final statement is a call to a mips16 function and compiler optimizations are enabled.

    Example:
    extern void bar (void);
    void foo (void);
    void foo (void)
    {
        bar();
    }
    The file containing bar() was compiled with -mips16 and the file containing foo() was compiled with -O2 but not -mips16. This means that the call to bar() must change ISA modes. Also, the call to bar() is the last statement in the foo() function.

    Possible workarounds include

    1. Use the mips16/nomips16 function attribute to make the caller function and the callee function the same ISA mode. Usually, this means applying the __attribute__((mips16)) or __attribute__((nomips16)) to the caller function to make it match the callee. This eliminates the need for a mode switch when calling the function.

       The example above becomes:
       extern void bar (void);
       void __attribute__((mips16)) foo (void);
       void __attribute__((mips16)) foo (void)
       {
           bar();
       }

    2. If your particular instance of this problem is caused by the tail sibling-call optimization, use the -fno-optimize-sibling-calls option when compiling the caller function. In MPLAB IDE v8.xx, you can add this option to your project's alternate settings. This will prevent the compiler converting your 'jal' call into a 'j' branch, which cannot change ISA modes.

    A future release of the linker will emit a more friendly and useful error message.

    Libraries and Device-Support Files

    C32-319

    GenericTypeDefs.h defines common data types (such as BYTE, BOOL, UINT16, etc.) that may conflict with definitions in non-Microchip code when using Microchip libraries. When conflicts occur, it will cause compilation errors in the Microchip-provided libraries or in the non-Microchip libraries (depending on which library first defines the data type).

    Possible workaround:
    Remove conflicting definitions from non-Microchip code.

    Documentation

    MPLAB C Compiler for PIC32 MCUs User's Guide (DS1686B)

    Section 5.6 Function Calling Convention - This section states that "The Stack Pointer is always aligned on a 4-byte boundary." This statement is incorrect. The Stack Pointer is always aligned on an 8-byte boundary.

12. Feature-Limited Editions and License Upgrades

    Time-Limited Standard Evaluation Edition

    Feature Limitations - Microchip provides a free time-limited Standard Evaluation edition of the MPLAB C Compiler for PIC32 MCUs. The standard evaluation edition of the compiler provides full functionality for 60 days. After the evaluation period has expired, the compiler becomes feature limited, and optimization features associated with levels -O2, -O3, and -Os are disabled. In addition, MIPS16 code generation is disabled. The compiler continues to accept the -O1 and -O0 optimization levels indefinitely.

    Installing the standard evaluation edition - To install the time-limited standard evaluation edition of the compiler, run the standard evaluation-edition installer and follow the on-screen instructions. If the installer asks for a license key, leave the field blank and continue.

    Upgrading to a standard-edition license - For applications requiring additional code efficiency, as well as full support via http://support.microchip.com, users are encouraged to upgrade to a full standard-edition compiler license. For further information on upgrading to a full standard-edition license (Part Number: SW006015), visit http://www.microchipdirect.com or contact your preferred Microchip distributor.

    Once you've obtained a standard-edition license key, run the Upgrader tool (pic32-upgrader\upgrader.exe) as a Windows administrator. After you enter your license key and press the Upgrade button, the license manager should then report the license upgrade status.

    Lite Edition

    Feature Limitations - Microchip provides a free Lite edition of the MPLAB C Compiler for PIC32 MCUs intended for use in projects where code efficiency is not critical. This edition of the compiler does not support optimization features associated with levels -O2, -O3, and -Os. In addition, this edition does not support MIPS16 code generation.

    Upgrading to the standard edition or standard evaluation edition - To take advantage of the advanced optimization and MIPS16 code generation features, you can upgrade to a standard edition or a 60-day standard evaluation edition. To upgrade to a full or 60-day standard evaluation edition, uninstall the lite edition using the normal Windows Add/Remove Programs feature. Next, install the standard edition or the standard evaluation edition by running the appropriate installer and following the on-screen instructions.

13. Customer Support

    Microchip provides online support via our home page at:
    http://www.microchip.com

    Technical support is available through the web site at:
    http://support.microchip.com

    A forum for discussion of Microchip products and tools is available at:
    http://forum.microchip.com

    Microchip PIC32 documentation and product info is available at:
    http://www.microchip.com/pic32

    MPLAB^® C Compiler for PIC32 MCUs updates and information are available at:
    http://www.microchip.com/c32