Release Notes for 16-Bit Language Tools for MPLAB® IDE
v3.12
12 Jan 2009

Table of Contents
  1. Overview
  2. GNU General Public License
  3. Devices Supported
  4. Installation
  5. 16-Bit Assembler/Linker Documentation
  6. What's New in this Release
  7. Migration Issues
  8. Documentation Updates
  9. Fixed Issues
  10. Limitations
  11. Environment Variables Modified
  12. Customer Support

  1. Overview

    2. The 16-Bit language tools consist of an assembler (pic30-as.exe) and a linker (pic30-ld.exe). These tools are sometimes referred to as the "ASM30 Suite". The user's guide describes additional utilities that are not supported by the MPLAB IDE and therefore are not supplied in this release.

    The 16-bit language tool official names are:

    • MPLAB Assembler for PIC24 MCUs and dsPIC DSCs (formerly MPLAB ASM30)
    • MPLAB Object Linker for PIC24 MCUs and dsPIC DSCs (formerly MPLAB LINK30)
    • MPLAB Object Archiver/Librarian for PIC24 MCUs and dsPIC DSCs (formerly MPLAB LIB30)

  2. GNU General Public License

    3. With the exceptions noted below, the 16-bit 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 top level of your install directory. A general discussion of principles underlying the GPL may be found at www.gnu.org/copyleft.

    Exceptions to the GNU GPL:

    • pic30-lm
    • pic30-pa
    • sim30

    Support code provided for the header files, linker scripts, and runtime libraries are also exceptions to the GPL, and therefore not covered under the GPL.

  3. Devices Supported

    4. The following PIC24 F KA devices are supported:

    4K devices 8K devices 16K devices
    PIC24F08KA101 PIC24F16KA101
    PIC24F08KA102 PIC24F16KA102
    PIC24F04KA200
    PIC24F04KA201

    The following PIC24 F GA devices are supported:

    16K devices 32K devices 48K devices 64K devices 96K devices 128K devices 192K devices 256K devices
    PIC24FJ16GA002 PIC24FJ32GA002 PIC24FJ48GA002 PIC24FJ64GA002
    PIC24FJ16GA004 PIC24FJ32GA004 PIC24FJ48GA004 PIC24FJ64GA004
    PIC24FJ64GA006 PIC24FJ96GA006 PIC24FJ128GA006
    PIC24FJ64GA008 PIC24FJ96GA008 PIC24FJ128GA008
    PIC24FJ64GA010 PIC24FJ96GA010 PIC24FJ128GA010
    PIC24FJ32GA102 PIC24FJ64GA102
    PIC24FJ32GA104 PIC24FJ64GA104
    PIC24FJ128GA106 PIC24FJ192GA106 PIC24FJ256GA106
    PIC24FJ128GA108 PIC24FJ192GA108 PIC24FJ256GA108
    PIC24FJ128GA110 PIC24FJ192GA110 PIC24FJ256GA110

    The following PIC24 F GB devices are supported:

    32K devices 64K devices 128K devices 192K devices 256K devices
    PIC24FJ32GB002 PIC24FJ64GB002
    PIC24FJ32GB004 PIC24FJ64GB004
    PIC24FJ64GB106 PIC24FJ128GB106 PIC24FJ192GB106 PIC24FJ256GB106
    PIC24FJ64GB108 PIC24FJ128GB108 PIC24FJ192GB108 PIC24FJ256GB108
    PIC24FJ64GB110 PIC24FJ128GB110 PIC24FJ192GB110 PIC24FJ256GB110

    The following PIC24 H GP devices are supported:

    12K devices 16K devices 32K devices 64K devices 128K devices 256K devices
    PIC24HJ12GP201
    PIC24HJ12GP202 PIC24HJ32GP202 PIC24HJ64GP202 PIC24HJ128GP202
    PIC24HJ32GP204 PIC24HJ64GP204 PIC24HJ128GP204
    PIC24HJ64GP206[A] PIC24HJ128GP206[A] PIC24HJ256GP206[A]
    PIC24HJ64GP210[A] PIC24HJ128GP210[A] PIC24HJ256GP210[A]
    PIC24HJ32GP302
    PIC24HJ16GP304 PIC24HJ32GP304
    PIC24HJ128GP306[A]
    PIC24HJ128GP310[A]
    PIC24HJ64GP502 PIC24HJ128GP502
    PIC24HJ64GP504 PIC24HJ128GP504
    PIC24HJ64GP506[A] PIC24HJ128GP506[A]
    PIC24HJ64GP510[A] PIC24HJ128GP510[A]
    PIC24HJ256GP610[A]

    The following dsPIC30 devices are supported:

    30F10xx 30F20xx 30F30xx 30F40xx 30F50xx 30F60xx
    dsPIC30F1010 dsPIC30F2010 dsPIC30F3010 dsPIC30F6010[A]
    dsPIC30F2011 dsPIC30F3011 dsPIC30F4011 dsPIC30F5011 dsPIC30F6011[A]
    dsPIC30F2012 dsPIC30F3012 dsPIC30F4012 dsPIC30F6012[A]
    dsPIC30F3013 dsPIC30F4013 dsPIC30F5013 dsPIC30F6013[A]
    dsPIC30F3014 dsPIC30F6014[A]
    dsPIC30F5015 dsPIC30F6015
    dsPIC30F5016
    dsPIC30F2020
    dsPIC30F2023

    The following dsPIC33F GP devices are supported:

    12K devices 16K devices 32K devices 64K devices 128K devices 256K devices
    dsPIC33FJ12GP201
    dsPIC33FJ12GP202 dsPIC33FJ32GP202 dsPIC33FJ64GP202 dsPIC33FJ128GP202
    dsPIC33FJ32GP204 dsPIC33FJ64GP204 dsPIC33FJ128GP204
    dsPIC33FJ64GP206[A] dsPIC33FJ128GP206[A]
    dsPIC33FJ32GP302
    dsPIC33FJ16GP304 dsPIC33FJ32GP304
    dsPIC33FJ64GP306[A] dsPIC33FJ128GP306[A]
    dsPIC33FJ64GP310[A] dsPIC33FJ128GP310[A]
    dsPIC33FJ256GP506[A]
    dsPIC33FJ256GP510[A]
    dsPIC33FJ64GP706[A] dsPIC33FJ128GP706[A]
    dsPIC33FJ64GP708[A] dsPIC33FJ128GP708[A]
    dsPIC33FJ64GP710[A] dsPIC33FJ128GP710[A] dsPIC33FJ256GP710[A]
    dsPIC33FJ64GP802 dsPIC33FJ128GP802
    dsPIC33FJ64GP804 dsPIC33FJ128GP804

    The following dsPIC33F GS devices are supported:

    6K devices 16K devices 32K devices 64K devices
    dsPIC33FJ06GS101
    dsPIC33FJ06GS102
    dsPIC33FJ06GS202
    dsPIC33FJ16GS402
    dsPIC33FJ16GS404
    dsPIC33FJ32GS406 dsPIC33FJ64GS406
    dsPIC33FJ16GS502
    dsPIC33FJ16GS504
    dsPIC33FJ32GS606 dsPIC33FJ64GS606
    dsPIC33FJ32GS608 dsPIC33FJ64GS608
    dsPIC33FJ32GS610 dsPIC33FJ64GS610

    The following dsPIC33F MC devices are supported:

    12K devices 16K devices 32K devices 64K devices 128K devices 256K devices
    dsPIC33FJ12MC201
    dsPIC33FJ12MC202 dsPIC33FJ32MC202 dsPIC33FJ64MC202 dsPIC33FJ128MC202
    dsPIC33FJ32MC204 dsPIC33FJ64MC204 dsPIC33FJ128MC204
    dsPIC33FJ32MC302
    dsPIC33FJ16MC304 dsPIC33FJ32MC304
    dsPIC33FJ64MC506[A] dsPIC33FJ128MC506[A]
    dsPIC33FJ64MC508[A]
    dsPIC33FJ64MC510[A] dsPIC33FJ128MC510[A] dsPIC33FJ256MC510[A]
    dsPIC33FJ64MC706[A] dsPIC33FJ128MC706[A]
    dsPIC33FJ128MC708[A]
    dsPIC33FJ64MC710[A] dsPIC33FJ128MC710[A] dsPIC33FJ256MC710[A]
    dsPIC33FJ64MC802 dsPIC33FJ128MC802
    dsPIC33FJ64MC804 dsPIC33FJ128MC804

    The following 'virtual' devices are supported:

    • generic-16bit - this device can be used to represent a generic core device (no peripherals of any kind)

  4. Installation

    5. The 16-bit language tools are installed with the MPLAB IDE installer.

  5. 16-Bit Assembler/Linker Documentation

    6. The following document pertains to the 16-bit assembler and linker. It may be installed as part of the full product or downloaded from Microchip's Web-site:

    • MPLAB Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs User's Guide (DS51317)

    We refer to this document throughout this README in somewhat familiar terms.

    Updates to these manuals, that have not made it into (virtual) print, can be found later in this README.

  6. What's New in this Release.

    7. v3.12

    This version includes support for 57 new devices:

    PIC24F04KA200
    PIC24FJ32GA102 PIC24FJ32GA104 PIC24FJ32GB002 PIC24FJ32GB004
    PIC24FJ64GA102 PIC24FJ64GA104 PIC24FJ64GB002 PIC24FJ64GB004
    PIC24HJ64GP206A PIC24HJ64GP210A PIC24HJ64GP506A PIC24HJ64GP510A
    PIC24HJ128GP206A PIC24HJ128GP210A PIC24HJ128GP306A PIC24HJ128GP310A PIC24HJ128GP506A PIC24HJ128GP510A
    PIC24HJ256GP206A PIC24HJ256GP210A PIC24HJ256GP610A
    dsPIC33FJ32GS406 dsPIC33FJ32GS606 dsPIC33FJ32GS608 dsPIC33FJ32GS610
    dsPIC33FJ64GP206A dsPIC33FJ64GP306A dsPIC33FJ64GP310A dsPIC33FJ64GP706A dsPIC33FJ64GP708A dsPIC33FJ64GP710A
    dsPIC33FJ64GS406 dsPIC33FJ64GS606 dsPIC33FJ64GS608 dsPIC33FJ64GS610
    dsPIC33FJ64MC506A dsPIC33FJ64MC508A dsPIC33FJ64MC510A dsPIC33FJ64MC706A dsPIC33FJ64MC710A
    dsPIC33FJ128GP206A dsPIC33FJ128GP306AdsPIC33FJ128GP310A dsPIC33FJ128GP706A dsPIC33FJ128GP708A dsPIC33FJ128GP710A
    dsPIC33FJ128MC506A dsPIC33FJ128MC510A dsPIC33FJ128MC706A dsPIC33FJ128MC708A dsPIC33FJ128MC710A
    dsPIC33FJ256GP506A dsPIC33FJ256GP510A dsPIC33FJ256GP710A
    dsPIC33FJ256MC510A dsPIC33FJ256MC710A

    Linker

    • The memory usage report (which appears in the map file as well as console output) has changed in two ways. First, sections marked noload will now appear in the report, and will count towards the total memory used. In the unusual case where two noload sections have been declared at the same address, the total memory value will be distorted.

      Second, the Program Memory report will only show sections actually defined in memory region "program". Previously, the reset vector and interrupt vector tables were included in this section of the report. However, these sections are defined in separate memory regions, and their appearance in the report can be confusing since these sections are not really part of the application code, which is otherwise variable in size.

      To clarify the second change, headings in the usage report now include the origin and length as defined in the linker script. For example:

        Program Memory  [Origin = 0x100, Length = 0x3ff00] 

  section                    address   length (PC units)   length (bytes) (dec) 
  -------                    -------   -----------------   -------------------- 
  .text                        0x100               0x56e           0x825  (2085) 
  .const                       0x66e                 0x6             0x9  (9) 
  .dinit                       0x674                0x82            0xc3  (195) 
  .text                        0x6f6                 0xa             0xf  (15) 
  .isr                         0x700                 0x2             0x3  (3) 

                       Total program memory used (bytes):          0x903  (2307) <1%

    Disassembler

    • The disassembly listing generated by pic30-objdump has been improved. Instead of representing the target address of branch and DO instructions as a PC-relative offset (using a "dot expression"), the absolute target address will be displayed. If a label at the target address can be identified, it will be displayed also. For example, a previous listing:

        f8 ff 3a        bra       NZ, . + 0xFFFFFFF2
  b8 ff 07        rcall     . + 0xFFFFFF72

      is now displayed as:

        f8 ff 3a        bra       NZ, 0x4F4 <.L26>
  b8 ff 07        rcall     0x46C <_fclose>

    v3.11

    The default stack guard band has been increased from 8 to 16 bytes, to adequately handle stack overflow exceptions that may occur from certain instruction sequences. The size of the guard band can also be specified with a new linker option. See Migration Issues for details.

    v3.10 (C) Support Update

    This support update to version 3.10 includes updates to the following device files:
    dsPIC33FJ06GS101, dsPIC33FJ06GS102, dsPIC33FJ06GS202, dsPIC33FJ16GS402, dsPIC33FJ16GS404, dsPIC33FJ16GS502, and dsPIC33FJ16GS504

    A customer can determine if this update has been installed by examining the C30 version string. A version string is displayed by executing the following command: 

           pic30-gcc --version
    The version string before update is: (dsPIC30, Microchip v3.10) (B)
    The version string after update is: (dsPIC30, Microchip v3.10) (C)

    v3.10

    This version includes support for 5 new devices: PIC24F04KA201, PIC24F08KA101, PIC24F08KA102, PIC24F16KA101, and PIC24F16KA102.

    See Migration Issues for information about how existing projects may be affected.

    Assembler

    • A new directive .memory can be used to define external memory regions. Sections may be assigned to memory regions by using the memory section attribute. See chapter 6 of MPLAB Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs User's Guide for details.

    Linker

    • Several improvements to the linker memory allocator, especially with regards to absolute sections and psv sections. For example, absolute sections may be defined in source code to reside at any address. The sequential memory allocator will avoid absolute sections, if necessary.
    • The linker allocates external memory regions as defined in C or assembly language. Each memory region includes a unique address space into which sections may be allocated. See chapter 10 of MPLAB Assembler, Linker and Utilities for PIC24 MCUs and dsPIC DSCs User's Guide for details.
    • The definition of output section .text in linker scripts includes a new input section named .user_init. This section is used by the compiler to generate activation code for user_init sections. The expression *(.text) has been removed, allowing application code to flow around psv sections as necessary, instead of always being allocated in a single large block. The new definition is: 
        .text :
  {
        *(.init);
        *(.user_init);
        *(.handle);
        *(.libc) *(.libm) *(.libdsp);  /* keep together in this order */
        *(.lib*);
  } >program
    • The linker script command language supports a new command OPTIONAL which is analogous to INPUT, except that no error occurs if the input file or library can not be found. An exact input file may be specified, or an abbreviated library file name with the -l prefix.

  7. Migration Issues

    8. Migrating to Version 3.12

    No significant migration issues have been identified. However, the format of link map files and disassembly listings has changed slightly (see What's New for details.) Custom tools or scripts which post-process such files may need modifications to accomodate these changes.

    Migrating to Version 3.11

    The default stack guard band has been increased from 8 to 16 bytes. This results in a corresponding decrease of usable stack space available to applications. To faciltiate the recovery of lost stack space, or to specify a larger guard band for non-trivial exception handlers, a new linker option has been added. For example, to restore stack allocation to match previous versions:

         --stackguard=8

    Migrating to Version 3.10

    • Installation Directory has been Re-organized

      The installation directory structure has changed to support multiple product configurations. The most significant change is that device support files (such as include files, and linker scripts) have been organized into folders based on product family. For example, all device-specific header files were previously located in support\inc. Now they may be found in support\PIC24F\inc for 24F devices or support\dsPIC33F\inc for 33F devices, etc.

      MPLAB IDE will report "File not found" for support files referenced by projects in the old locations. MPLAB IDE v8.10 or later provides an easy way to resolve such problems. Simply right-click on the missing project files and select "Locate Missing File" or "Remove". In most cases MPLAB IDE will locate the missing project file automatically. If the missing file is a standard linker script, then removing the file will suffice, since standard linker scripts are included automatically in MPLAB IDE v8.0 or later. If the missing file is a device-specific library, then removing the file will also suffice, since standard linker scripts now include peripheral libraries automatically.

      The bin folder has also changed. Tools that are specific to the object file format have been moved to a lower level. This change should not impact existing projects, since these tools should always be invoked by the generic versions which are located in the standard location.

    • Memory Map has been Simplified

      The linker's best-fit allocator will merge output sections with the same name whenever it is convenient to do so. This will change the memory usage report and link map. For example, several adjacent sections named .bss will now be merged into one.

      Section .text will flow around section .const (or other psv sections) as necessary. To facilitate this new behaviour, the expression *(.text) has been removed from the definition of output section .text in linker scripts. This may change the organization of sections in program memory, since .text will now be allocated in multiple chunks if necessary. Existing projects which depend on a single .text section can revert to the previous behaviour by restoring the definition of output section .text.

  8. Documentation Updates

    9. None

  9. Fixed Issues

    10. v3.12

      Assembler

    • BIN30-148 - Assembler rejects psv section defined twice with absolute address
    • BIN30-149 - error with _FBS macro on dsPIC33FxxGS devices

      • Linker

    • BIN30-123 - Memory usage report does not include "noload" sections but the map file does
    • BIN30-137 - Percent used calculation in program memory is slightly inaccurate for non-30F devices
    • BIN30-146 - "noload" sections do not appear in the memory usage report
    • BIN30-147 - Linker should warn if absolute section crosses a region boundary
    • BIN30-150 - Linker option "boot=no_write_protect" is rejected for all devices

      • Disassembler

    • BIN30-153 - pic30-objdump (-d option) may display same label at two addresses

    v3.11

      Linker

    • BIN30-141 - Stack overflow guard band is not large enough
    • BIN30-142 - Can't create maximum size auto_psv section
    • BIN30-143 - arrays larger than 16K are not cleared at startup

    v3.10

      Assembler

    • BIN30-119 - ELF/DWARF: can't debug multiple sections in assembly
    • BIN30-118 - need better error checking for DSP square and accumulate

      Linker

    • BIN30-30/25966 - Functions with the address attribute may cause a link error.

      Previously, some addresses were invalid for the address attribute, notably those that are used for the .handle, .libc, .libm, .libdsp and other .lib sections. Sequential sections will now avoid functions with the address attribute.

    • BIN30-77 - Not enough contiguous memory for section .const.

      Previously, applications with large amounts of auto_psv data could fail to link on certain devices, even though the total amount of memory used did not exceed the flash capacity. The new linker does a better job of allocating psv sections, including section .const. Also, input sections .text have been removed from linker scripts, allowing the best-fit allocator to flow them around psv sections as necessary.

    • BIN30-127 - Not enough memory for heap, when upgrading from 2.30 to 3.02

      • In v3.0x, variables with an alignment requirement larger than their size consumed additional memory. This has been corrected.

    • BIN30-115 - Linker rejects FGS settings for certain devices
    • BIN30-117 - Invalid Config bit warning seen when building a project with FGS settings

  10. Limitations

    11. The current limitations are as follows:

      Assembler

    • Arguments to the address() section attribute must be even.
    • The default section alignment is 2**1. Therefore the minimum section length is 2 bytes in data memory, and 2 PC units (3 bytes) in program memory.
    • BIN30-3/15741 - The .lcomm directive causes incorrect source line numbers in the assembler listing file.
    • BIN30-5/20016 - Special operators should not accept odd offsets in program memory.
    • BIN30-8/21797 - The .align directive changes section alignment regardless of max-skip.
    • BIN30-10/23306 - The option -g does not work with any section other than .text.
    • BIN30-17/25555 - Cannot generate code for goto $-2.
    • BIN30-22/28477- Unexpected results using .equiv as value for another .equiv.

      The following example is not encoded correctly:

           .equiv var1,root+1
     .equiv var2,var1
     .word var1  ; encodes root+1
     .word var2  ; encodes root

      This can happen when the value specified in .equiv is the name of an SFR high byte such as _LATBH, which is defined in the processor include files as an .equiv. The workaround in this case would be to refer to the base register itself, i.e. _LATB+1

    • BIN30-92 - Can't set breakpoints in pre-processed assembly file (COFF-only)
    • BIN30-101 - Multiple .equs to undefined symbol causes internal error in the assembler

      The following assembly statements will cause a failure:

      .equ foo,bar
.equ baz,foo
.word baz

      In this example, bar is an undefined symbol, while foo and baz are indirect references to bar. The second level of indirection is causing the failure. The following sequences work fine:

      .equ foo,bar
.word foo ; one level of indirection

.equ bar,9
.equ foo,bar
.equ baz,foo
.word baz ; two levels of indirection to a literal constant
    • BIN30-145 - DWARF or ELF linker error with assembly .equ directive

      The assembler .equ directive can be used to define a symbolic name for a constant or for an external symbol. It does not work with register names. However, the assembler does not recognize this error and attempts to continue processing. With the ELF object format, equating a register name causes the symbol table to be corrupted. This corruption can result in a DWARF error (if symbolic debugging is selected) or the linker error "undefined reference to 'no symbol'".

      For arbitrary text substitution (including register names) use the #define C preprocessor directive. If the assembly source file name ends in .S, the C preprocessor will be invoked before assembly, provided the C language toolsuite is selected.

      • Linker

    • BIN30-23/28952 - Multiple definition error with custom linker script

      If a linker script is modified to place the .text section from one object file before all the others, multiple definition errors can result. When this occurs the linker acts as if the section was included twice. The workaround is to specify a full pathname, or *, before the object file name:

                   /*
             ** User Code and Library Code
             */
             .text :
             {
                *(.init);
                *(.user_init);
                *(.handle);
                *(.libc) *(.libm) *(.libdsp);  /* keep together in
                                                  this order */
                *(.lib*);
                myfile.o(.text);   /* this form causes error */
                *myfile.o(.text);  /* this form works OK */
             } >program

  11. Environment Variables Modified

    12. This installation makes no changes to the way environment variables have been updated previously.

    Modified environment variables are identified as part of the installation procedure and are documented in the manuals.

  12. Customer Support


    13. 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