Release Notes for MPLAB® C Compiler for PIC32 MCUs

v2.01
August 2011

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. Known Issues
  11. Editions and License Upgrades
  12. Customer Support


  1. Overview

    The 32-Bit language tools consist of a compiler (pic32-gcc), an assembler (pic32-as), a linker (pic32-ld), and an archiver/ librarian (pic32-ar). Additional tools distributed with this release include a binary to Intel[intl] Hex converter (pic32-bin2hex) and miscellaneous binary utilities (pic32-strip, pic32-strings, pic32-readelf, etc). In addition, the compiler utilizes a license manager (pic32-lm) 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 COPYING3.GPL 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 Part Number Part Number
    PIC32MX110F016B
    PIC32MX110F016C
    PIC32MX110F016D
    PIC32MX120F032B
    PIC32MX120F032C
    PIC32MX120F032D
    PIC32MX210F016B
    PIC32MX210F016C
    PIC32MX210F016D
    PIC32MX220F032B
    PIC32MX220F032C
    PIC32MX220F032D
    PIC32MX320F032H
    PIC32MX320F064H
    PIC32MX320F128H
    PIC32MX320F128L
    PIC32MX340F128H
    PIC32MX340F128L
    PIC32MX340F256H
    PIC32MX340F512H
    PIC32MX360F256L
    PIC32MX360F512L
    PIC32MX420F032H
    PIC32MX440F128H
    PIC32MX440F128L
    PIC32MX440F256H
    PIC32MX440F512H
    PIC32MX460F256L
    PIC32MX460F512L
    PIC32MX534F064H
    PIC32MX534F064L
    PIC32MX564F064H
    PIC32MX564F064L
    PIC32MX564F128H
    PIC32MX564F128L
    PIC32MX575F256H
    PIC32MX575F256L
    PIC32MX575F512H
    PIC32MX575F512L
    PIC32MX664F064H
    PIC32MX664F064L
    PIC32MX664F128H
    PIC32MX664F128L
    PIC32MX675F256H
    PIC32MX675F256L
    PIC32MX675F512H
    PIC32MX675F512L
    PIC32MX695F512H
    PIC32MX695F512L
    PIC32MX764F128H
    PIC32MX764F128L
    PIC32MX775F256H
    PIC32MX775F256L
    PIC32MX775F512H
    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 on Windows

    If using MPLAB IDE, be sure to install MPLAB IDE v8.10 (or later) or MPLAB X beta 7 (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\mplabc32\<version>, then ensure that c:\Program Files\Microchip\mplabc32\<version>\bin has been added to your PATH.

      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.

    1 Other CHM files may be available from the main CHM file by clicking a link (such as for Interrupts). When you do this, a Security Warning dialog may display. Click on Open to view the CHM file.

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

  6. What's New

    New Features in v2.01

    • New device support -- This release introduces support for several new PIC32MX1 and MX2 devices.

    • unsupported(message) attribute -- Use the unsupported(message) attribute to emit a message whenever an unsupported function or variable is used.

      __attribute__((unsupported("this feature is not supported on this device"))) void function(void);

    New Features in v2.00

    • Upgrade to GCC 4.5.1 technology -- The MPLAB C compiler is now based on the GNU Compiler Collection (GCC) v4.5.1. This new base technology introduces a new optimization framework that allows for significantly improved generated code efficiency, resulting in both an improved code-size footprint and a faster execution speed.

    • Upgrade to Binutils 2.20 -- The MPLAB ASM32 assembler, LINK32 linker, and binary utilities are now based on GNU Binutils 2.20.

    • address(addr) C Attribute for functions and variables -- The address attribute specifies an absolute virtual address for the function or variable. Be sure to specify the address attribute using an appropriate virtual address. For data variables, the address is typically in the range [0xA0000000,0xA00FFFFC]. For program functions, the address is typically in the range [0x9D000000,0x9D0FFFFC]. A linker relocation error may indicate an out-of-range address.

      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(0xA0001000)));
      int bar __attribute__((section("mysection")));
      int baz __attribute__((section("mysection")));
      __attribute__((address(0x9D00800))) void funky (char* parm)

      Note that the "small" data and bss (.sdata, .sbss, etc.) sections used for GP-relative addressing are mapped in the built-in linker script. This is because "small" data variables must be grouped together so that they are within range of the more efficient GP-relative addressing mode. To avoid conflict with these linker-script mapped sections, choose high addresses for your absolute-address variables.

      Read More...

    • space(space) C Attribute for Variables -- Normally, the compiler allocates variables in general data space. Use the space attribute to direct the compiler to allocate a variable in a specific memory space. In this release, the compiler accepts two space attributes: prog and data. The prog space tells the toolchain to allocate the variable to the program memory space (the memory region named kseg0_program_memory in the linker script). The data space tells the toolchain to allocate the variable to the data memory space (region kseg1_data_mem).

      Note that when combining the space attribute with the address attribute, the section will be placed at the address specified in the address attribute, but the generated code will use the specified space attribute. The application code must ensure that the combination makes sense for the application.

      unsigned int foo __attribute__((space(prog))) = 1;
      unsigned int vb __attribute__((space(data))) = 2;
      unsigned int baz __attribute__((space(data)));
    • ramfunc C Attribute for Functions -- This new attribute places a function into data memory. Previous releases relied on a magic section name, .ramfunc, and data-memory mapping in the linker script. The new ramfunc attribute places the function at the highest appropriately aligned address. Note that due to ramfunc alignment and placement requirements, the address attribute should not be used with the ramfunc attribute. The presence of a ramfunc section causes the linker to emit the symbols necessary for the crt0.S startup code to initialize the bus matrix appropriately. Use this new attribute along with the far/longcall attribute.

      __attribute__((ramfunc,section(".ramfunc"),far,unique_section)) unsigned int myramfunct (void)
      {
        // code
      }

      A macro in the sys/attribs.h header file makes the attributes simple to use:
      #include <sys/attribs.h>
      __longramfunc__ unsigned int myramfunct (void)
      {
        // code
      }

    • persistent C Attribute for Variables -- The new persistent attribute specifies that the variable should not be initialized or cleared at startup. Use a variable with the persistent attribute to store state information that will remain valid after a device reset. The persistent attribute causes the compiler to place the variable in special .bss-like section that does not get cleared by the default startup code. Because the section is always in data space, this attribute is not compatible with the space() attribute.

      int last_mode __attribute__((persistent));

    • -mtext="scn-name" Compiler Command-line Option -- Specifying -mtext=scn-name will cause text (program code) to be placed in a section named scn-name rather than the default .text section. No white spaces should appear around the =. This command can be useful when developing a bootloader.

      pic32-gcc bootloader.c -mtext="MySectionName,address(0x9D001000)" -mprocessor=32MX795F512L

    • New .section Assembly-code Directive -- The .section directive now accepts a list of attributes rather than a set of quoted flags. Quoted section flags are now deprecated.

      Read More...

    • Linker Allocation Algorithm -- In order to effectively make use of memory with the presence of absolute sections, the linker now uses a best-fit allocator. Note that many standard sections, previously mapped in the default built-in linker script, are now handled by the best-fit allocator. Please see the Migration Issues topic below for important information regarding application-specific linker scripts and startup code.

      Linker allocation steps

      1. Mapping input sections to output sections
      2. Assigning output sections to regions
      3. Allocating unmapped sections

      Read More...

    • Data Initialization using a Template and Updated Startup Code -- The linker now generates a data-initialization template (.dinit section) that the startup code uses to initialize variables in data sections. In previous releases, initialized data sections were sequentially allocated so a simple block copy was sufficient. However, since this release supports variables at absolute addresses, a new data-initialization template is required to initialize non-contiguous data sections.

      The linker places the initialization template in the .dinit section. The crt0.S startup code has been updated to initialize data using the new template rather than a block copy. The old startup code will not initialize data properly using this version of the language tools.

    • Stack and heap allocation -- The stack and heap are now dynamically generated. Previous releases used output sections specified in the linker script to allocate the stack and heap. The linker now finds the largest available gap in memory and uses that gap for the heap and stack.

      As in earlier versions, the _min_stack_size and _min_heap_size linker symbols define the minimum size of the stack and the size of the heap. The size specified for the heap is the exact size to be allocated while the size allocated for the stack is the minimum size allocated.

      The linker-generated memory usage report now displays these dynamically allocated stack and heap areas. Because the stack expands in size to use the entire gap, the total is not added in to the total data memory usage. Only the minimum stack size specified by the application is added to the total.

      pic32-gcc sourcecode.c -Wl,--defsym,_min_stack_size=2048,--defsym,_min_heap_size=1024

      pic32-gcc object1.o object2.o -Wl,--defsym,_min_heap_size=1024,--report-mem -omyproject.elf

    New Features in v1.12

    New Features in v1.11(b)

    New Features in v1.11(a)

    New Features in v1.10

    New Features in v1.05

  7. New Features in v1.04

    New Features in v1.03

  8. Migration Issues

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

    Migrating to Version v2.00

    • Compiler
      • Custom Startup Code -- This release of the toolchain introduces data initialization using a .dinit template and associated startup code. Previous releases relied on a block copy in the startup code that copied from the .data section located in program memory to the .data section allocated in data memory. If your project uses custom startup code and initialized data, replace the block copy in your custom startup code with initialization code utilizing the .dinit template. A copy of the updated default startup code is located in the /pic32-libs/libc/startup/crt0.S file installed with the compiler.

      • Placement of the mips16/nomips16 Function Attribute -- The mips16 and nomips16 function attributes are now declaration attributes rather than type attributes. This means that they should be placed at the beginning of a declaration rather than on the type. The compiler will emit a warning message if the attribute should be moved.

        __attribute__((mips16)) unsigned int *funct1 (void) { /* code */ }

    • Linker
      • Custom Linker Script -- To make effective use of absolute sections and the new best-fit allocator, standard program-memory and data-memory sections should not be mapped in the linker script. The built-in linker script no longer maps most standard sections such as the .text, .data, .bss, or .ramfunc section. By not mapping these sections in the linker script, we allow these sections to be allocated using the new best-fit allocator rather than the sequential allocator. Sections that are unmapped in the linker script can flow around absolute sections whereas sections that are linker-script mapped are grouped together and allocated sequentially, potentially causing conflicts with absolute sections.

        Note that the "small" data and bss (.sdata, .sbss, etc.) sections are still mapped in the built-in linker script. This is because "small" data variables must be grouped together so that they are within range of the more efficient GP-relative addressing mode. To avoid conflict with these linker-script mapped sections, choose high addresses for your absolute-address variables.

        New debug information should be mapped to 0 in the linker script. The linker script should map the new .debug_ranges, .debug_pubtypes, and .gnu.attributes sections in the linker script so that they do not get allocated to program or data memory. You can do this by adding two lines to your custom linker script. In the existing linker script, find the output-section command within the SECTIONS block where the other .debug sections are mapped. Add the two lines for .debug_ranges and .debug_pubtypes.

        /* SGI/MIPS DWARF 2 extensions */
        .debug_weaknames 0 : { *(.debug_weaknames) }
        .debug_funcnames 0 : { *(.debug_funcnames) }
        .debug_typenames 0 : { *(.debug_typenames) }
        .debug_varnames 0 : { *(.debug_varnames) }
        .debug_pubtypes 0 : { *(.debug_pubtypes) }
        .debug_range    0 : { *(.debug_ranges) }
        .gnu.attributes 0 : { KEEP (*(.gnu.attributes)) }

        /DISCARD/ : { *(.rel.dyn) }
        /DISCARD/ : { *(.note.GNU-stack) }

        A copy of the updated built-in linker script is located in /pic32mx/lib/ldscripts/elf32pic32mx.x.

    • Libraries
      • Peripheral Freeze (FRZ) bits -- The peripheral-library functions no longer modify the debug freeze bit for the corresponding peripheral. Use an in-circuit debugger or emulator to configure the peripheral to freeze when debugging, if required.

    • Installer
      • Default install location -- The installer now always defaults to installing in a standard installation path. If you do not wish to have multiple versions of the toolchain installed on your machine, uninstall the previous versions.

        Windows
        C:\Program Files\Microchip\mplabc32\<version>
        Linux
        /opt/microchip/mplabc32/<version>
        Mac OS X
        /Applications/microchip/mplabc32/<version>

    Migrating to Version v1.12

    Migrating to Version v1.11

    Migrating to Version v1.10

    Migrating to Version v1.05

    Migrating to Version v1.04

    Migrating to Version v1.03

    Migrating to Version v1.02

  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.

    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.

    Assembler/Linker/Utilities documentation updates

    This section describes pending updates to the MPLAB Assembler, Linker and Utilities for PIC32 MCUs User's Guide (DS51833) documentation. These changes will be incorporated into the next full revision of the documents.

  10. Fixed Issues

    The following issues have been resolved in this release

    Fixed in v2.01

    C32-491:
    The watchdog timer (WDT) should now clear correctly on devices when the WDT Enable config bit is set using the config pragma. MPLAB C32 v2.00 incorrectly set some unimplemented bits to '0' rather than '1', which could cause problems with the WDT.
    C32-490:
    The single-precision atan2(y,x) function now returns the correct -Pi/2 value for the boundary condition (y<0 && x==0)
    C32-489:
    Compatibility issues related to the BigInt_helper_C32.S assembly code file in the Microchip TCP/IP stack have been resolved.
    C32-487:
    The _UART2_BASE_ADDRESS definition in the PIC32MX3 and MX4 device-support header files have been corrected. This caused the UART2 peripheral library functions to write to unimplemented locations rather than the correct Special Function Register addresses.
    C32-483:
    The C runtime startup code now correctly clears global uninitialized variables allocated to the "common" section.
    C32-480:
    The malloc free() function now handles a NULL pointer more gracefully. In previous releases, calling free() with a NULL pointer could cause heap corruption. In addition, the malloc() function now uses a smaller block size. This results in more efficient heap usage for most embedded applications.
    BIN32-79:
    The linker no longer marks the .sdata section as LOADable. In the MPLAB C32 v2.00 release, the .sdata section appeared in the hex file causing a problem for some hex file consumers.
    BIN32-77:
    The linker no longer causes a segmentation fault on projects that use the .rel.dyn section. Dynamic relocations are not yet supported.
    BIN32-76:
    The linker no longer emits symbols causing the bus matrix to be initialized when ram functions do not exist in the project. MPLAB C32 v2.00 always initialized the bus matrix, potentially causing runtime problems for projects using a custom linker script with a data section that did not end on a 2K aligned address.

    Fixed in v2.00

    C32-412:
    Peripheral library function-like macros related to 32-bit timers TMR23 and TMR45 are restored. In the v1.12 release, these macros were unavailable and caused a link error for application code that attempted to use them. These macros are now again available on appropriate devices.
    C32-391:
    Some errors related to smart-io version 2 are now corrected. In the v1.12 release, some uses of formatted IO functions could cause a linker error along the lines of "undefined reference to `_fprintf_s' ". This error has been corrected for v2.00.
    C32-390:
    Library functions asprintf() and vasprintf() should now link correctly.
    BIN32-73:
    A potential linker hang/crash related to smart IO has been corrected.

    Fixed in v1.12

    Fixed in v1.11

    Fixed in v1.10

    Fixed in v1.05

    Fixed in v1.04

    Fixed in v1.03

    Fixed in v1.02

  11. Known Issues

    The current known issues are as follows.

    Compiler

    C32-345
    The compiler will "terminate in an unusual way" if the Windows TEMP environment variable is set to an invalid directory. You can correct your TEMP environment variable in the Windows Control Panel (Control Panel -> System -> Advanced -> Environment Variables). TEMP should point to an appropriate directory for temporary files.
    C32-463
    The compiler may terminate with an internal error when a mips16 attributed function is inlined in a non-mips16 function or vice versa. This can happen at optimization levels -O2 or -O3. To get around this problem, combine the noinline attribute with your mips16 and/or nomips16 function attribute. The noinline attribute prevents the function from being inlined into another function of a different ISA mode.

    Assembler

    BIN32-68
    The assembler may emit an error, 'Macro used $at after".set noat"', for a macro/synthesized instruction even when the synthesized instruction does not use the $at register. A workaround is to replace the macro instruction with the actual instructions.

    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 source code.

    C32-479
    When combining the -fno-short-double and -mno-float compiler options and calling a scanf() or related function, the linker may emit an error indicating undefined references to _dstrtod and strtof. You are not likely to see this issue because combining -fno-short-double, which requests a 64-bit double type, with -mno-float, which disables floating-point support, is not common.

    Possible workaround:
    Remove the either the -fno-short-double or -mno-float option.

    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. Editions and License Upgrades

    Standard Evaluation Edition

    Microchip provides a free Standard Evaluation edition of the MPLAB C Compiler for PIC32 MCUs. The standard evaluation edition of the compiler provides additional functionality for 60 days. After the evaluation period has expired, the compiler becomes reverts to the lite edition, 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 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://www.microchip.com/support, 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

    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://www.microchip.com/support

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

    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