MPLAB® XC32 Assembler, Linker, Utilities Guide Datasheet by Microchip Technology

View All Related Products | Download PDF Datasheet
6‘ MICRDCHIP
2013 Microchip Technology Inc. DS50002186A
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
Users Guide
YSTEM
2013 Microchip Technology Inc. DS50002186A-page 2
Information contained in this publication regarding device
applications and the like is provided only for your convenience
and may be superseded by updates. It is your responsibility to
ensure that your application meets with your specifications.
MICROCHIP MAKES NO REPRESENTATIONS OR
WARRANTIES OF ANY KIND WHETHER EXPRESS OR
IMPLIED, WRITTEN OR ORAL, STATUTORY OR
OTHERWISE, RELATED TO THE INFORMATION,
INCLUDING BUT NOT LIMITED TO ITS CONDITION,
QUALITY, PERFORMANCE, MERCHANTABILITY OR
FITNESS FOR PURPOSE. Microchip disclaims all liability
arising from this information and its use. Use of Microchip
devices in life support and/or safety applications is entirely at
the buyer’s risk, and the buyer agrees to defend, indemnify and
hold harmless Microchip from any and all damages, claims,
suits, or expenses resulting from such use. No licenses are
conveyed, implicitly or otherwise, under any Microchip
intellectual property rights.
Note the following details of the code protection feature on Microchip devices:
Microchip products meet the specification contained in their particular Microchip Data Sheet.
Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the
intended manner and under normal conditions.
There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our
knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data
Sheets. Most likely, the person doing so is engaged in theft of intellectual property.
Microchip is willing to work with the customer who is concerned about the integrity of their code.
Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not
mean that we are guaranteeing the product as “unbreakable.”
Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our
products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts
allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act.
Microchip received ISO/TS-16949:2009 certification for its worldwide
headquarters, design and wafer fabrication facilities in Chandler and
Tempe, Arizona; Gresham, Oregon and design centers in California
and India. The Company’s quality system processes and procedures
are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping
devices, Serial EEPROMs, microperipherals, nonvolatile memory and
analog products. In addition, Microchip’s quality system for the design
and manufacture of development systems is ISO 9001:2000 certified.
QUALITY MANAGEMENT S
YSTEM
CERTIFIED BY DNV
== ISO/TS 16949 ==
Trademarks
The Microchip name and logo, the Microchip logo, dsPIC,
FlashFlex, KEELOQ, KEELOQ logo, MPLAB, PIC, PICmicro,
PICSTART, PIC32 logo, rfPIC, SST, SST Logo, SuperFlash
and UNI/O are registered trademarks of Microchip Technology
Incorporated in the U.S.A. and other countries.
FilterLab, Hampshire, HI-TECH C, Linear Active Thermistor,
MTP, SEEVAL and The Embedded Control Solutions
Company are registered trademarks of Microchip Technology
Incorporated in the U.S.A.
Silicon Storage Technology is a registered trademark of
Microchip Technology Inc. in other countries.
Analog-for-the-Digital Age, Application Maestro, BodyCom,
chipKIT, chipKIT logo, CodeGuard, dsPICDEM,
dsPICDEM.net, dsPICworks, dsSPEAK, ECAN,
ECONOMONITOR, FanSense, HI-TIDE, In-Circuit Serial
Programming, ICSP, Mindi, MiWi, MPASM, MPF, MPLAB
Certified logo, MPLIB, MPLINK, mTouch, Omniscient Code
Generation, PICC, PICC-18, PICDEM, PICDEM.net, PICkit,
PICtail, REAL ICE, rfLAB, Select Mode, SQI, Serial Quad I/O,
Total Endurance, TSHARC, UniWinDriver, WiperLock, ZENA
and Z-Scale are trademarks of Microchip Technology
Incorporated in the U.S.A. and other countries.
SQTP is a service mark of Microchip Technology Incorporated
in the U.S.A.
GestIC and ULPP are registered trademarks of Microchip
Technology Germany II GmbH & Co. KG, a subsidiary of
Microchip Technology Inc., in other countries.
All other trademarks mentioned herein are property of their
respective companies.
© 2013, Microchip Technology Incorporated, Printed in the
U.S.A., All Rights Reserved.
Printed on recycled paper.
ISBN: 978-1-62077-521-9
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 3
Table of Contents
Preface ........................................................................................................................... 7
Part 1 – MPLAB XC32 Assembler
Chapter 1. Assembler Overview
1.1 Introduction ................................................................................................... 15
1.2 Assembler and Other Development Tools ................................................... 15
1.3 Feature Set ................................................................................................... 16
1.4 Input/Output Files ......................................................................................... 17
Chapter 2. Assembler Command-Line Options
2.1 Introduction ................................................................................................... 23
2.2 Assembler Interface Syntax ......................................................................... 23
2.3 Compilation-Driver Interface Syntax ............................................................. 24
2.4 Options that Modify the Listing Output ......................................................... 25
2.5 Options that Control Informational Output .................................................... 37
2.6 Options that Control Output File Creation .................................................... 38
2.7 Assembler Symbol-Definition and Search-Path Options .............................. 39
2.8 Compilation-Driver and Preprocessor Options ............................................. 40
Chapter 3. MPLAB XC32 Assembly Language
3.1 Introduction ................................................................................................... 41
3.2 Internal Preprocessor ................................................................................... 42
3.3 Source Code Format .................................................................................... 43
3.4 Special Characters ....................................................................................... 48
3.5 Symbols ........................................................................................................ 51
3.6 Giving Symbols Other Values ...................................................................... 52
3.7 The Special DOT Symbol ............................................................................. 52
3.8 Expressions .................................................................................................. 53
3.9 Operators ..................................................................................................... 53
3.10 Special Operators ....................................................................................... 55
Chapter 4. Assembler Directives
4.1 Introduction ................................................................................................... 57
4.2 Directives that Define Sections .................................................................... 58
4.3 Directives that Initialize Constants ............................................................... 62
4.4 Directives that Declare Symbols .................................................................. 64
4.5 Directives that Define Symbols .................................................................... 65
4.6 Directives that Modify Section Alignment ..................................................... 66
4.7 Directives that Format the Output Listing ..................................................... 68
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 4 2013 Microchip Technology Inc.
4.8 Directives that Control Conditional Assembly .............................................. 69
4.9 Directives for Substitution/Expansion ........................................................... 71
4.10 Directives that Include Other Files ............................................................. 75
4.11 Directives that Control Diagnostic Output .................................................. 76
4.12 Directives for Debug Information ................................................................ 77
4.13 Directives that Control Code Generation .................................................... 79
Chapter 5. Assembler Errors/Warnings/Messages
5.1 Introduction ................................................................................................... 81
5.2 Fatal Errors ................................................................................................... 82
5.3 Errors ............................................................................................................ 83
5.4 Warnings ...................................................................................................... 90
5.5 Messages ..................................................................................................... 94
Part 2 – MPLAB XC32 Object Linker
Chapter 6. Linker Overview
6.1 Introduction ................................................................................................... 97
6.2 Linker and Other Development Tools ........................................................... 97
6.3 Feature Set ................................................................................................... 98
6.4 Input/Output Files ......................................................................................... 98
Chapter 7. Linker Command-Line Interface
7.1 Introduction ................................................................................................. 105
7.2 Linker Interface Syntax ............................................................................... 106
7.3 Compilation-Driver Linker Interface Syntax ................................................ 107
7.4 Options that Control Output File Creation .................................................. 108
7.5 Options that Control Run-time Initialization ................................................ 113
7.6 Options that Control Multilib Library Selection ........................................... 114
7.7 Options that Control Informational Output .................................................. 115
7.8 Options that Modify the Link Map Output ................................................... 118
Chapter 8. Linker Scripts
8.1 Introduction ................................................................................................. 119
8.2 Overview of Linker Scripts .......................................................................... 120
8.3 Command Line Information ........................................................................ 120
8.4 Default Linker Script ................................................................................... 121
8.5 Adding a Custom Linker Script to an MPLAB X IDE Project ...................... 123
8.6 Linker Script Command Language ............................................................. 124
8.7 Expressions in Linker Scripts ..................................................................... 140
Chapter 9. Linker Processing
9.1 Introduction ................................................................................................. 147
9.2 Overview of Linker Processing ................................................................... 148
9.3 Linker Allocation ......................................................................................... 150
9.4 Global and Weak Symbols ......................................................................... 153
9.5 Initialized Data ............................................................................................ 154
Table of Contents
2013 Microchip Technology Inc. DS50002186A-page 5
9.6 Stack Allocation .......................................................................................... 157
9.7 Heap Allocation .......................................................................................... 157
9.8 PIC32MX Interrupt Vector Tables .............................................................. 158
9.9 Interrupt Vector Tables for PIC32 MCUs Featuring Dedicated Programmable
Variable Offsets .................................................................................... 159
Chapter 10. Linker Examples
10.1 Introduction ............................................................................................... 163
10.2 Highlights .................................................................................................. 163
10.3 Memory Addresses and Relocatable Code .............................................. 164
10.4 Locating a Variable at a Specific Address ................................................ 165
10.5 Locating a Function at a Specific Address ............................................... 165
10.6 Locating and Reserving Program Memory ............................................... 166
Chapter 11. Linker Errors/Warnings
11.1 Introduction ............................................................................................... 167
11.2 Fatal Errors ............................................................................................... 168
11.3 Errors ........................................................................................................ 169
11.4 Warnings .................................................................................................. 172
Part 3 – 32-Bit Utilities (including the Archiver/Librarian)
Chapter 12. MPLAB XC32 Object Archiver/Librarian
12.1 Introduction ............................................................................................... 175
12.2 Archiver/Librarian and Other Development Tools .................................... 176
12.3 Feature Set ............................................................................................... 177
12.4 Input/Output Files ..................................................................................... 177
12.5 Syntax ...................................................................................................... 177
12.6 Options ..................................................................................................... 178
12.7 Scripts ...................................................................................................... 180
Chapter 13. Other Utilities
13.1 Introduction ............................................................................................... 183
13.2 xc32-bin2hex Utility .................................................................................. 184
13.3 xc32-nm Utility .......................................................................................... 185
13.4 xc32-objdump Utility ................................................................................. 188
13.5 xc32-ranlib Utility ...................................................................................... 191
13.6 xc32-size Utility ........................................................................................ 192
13.7 xc32-strings Utility .................................................................................... 194
13.8 xc32-strip Utility ........................................................................................ 195
Part 4 – Appendices
Appendix A. Deprecated Features
A.1 Introduction ................................................................................................ 199
A.2 Assembler Directives that Define Sections ................................................ 200
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 6 2013 Microchip Technology Inc.
Appendix B. Useful Tables
B.1 Introduction ................................................................................................ 201
B.2 ASCII Character Set .................................................................................. 201
B.3 Hexadecimal to Decimal Conversion ......................................................... 202
Appendix C. GNU Free Documentation License
Glossary .....................................................................................................................205
Index ...........................................................................................................................225
Worldwide Sales and Service ...................................................................................234
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 7
Preface
INTRODUCTION
This chapter contains general information that is useful to know before using 32-bit
language tools. Items discussed include:
Document Layout
Conventions Used in this Guide
Recommended Reading
The Microchip Web Site
myMicrochip Personalized Notification Service
Customer Support
NOTICE TO CUSTOMERS
All documentation becomes dated, and this manual is no exception. Microchip tools and
documentation are constantly evolving to meet customer needs, so some actual dialogs
and/or tool descriptions may differ from those in this document. Please refer to our web site
(www.microchip.com) to obtain the latest documentation available.
Documents are identified with a “DS” number. This number is located on the bottom of each
page, in front of the page number. The numbering convention for the DS number is
“DSXXXXXXXXA”, where “XXXXXXXX” is the document number and “A” is the revision level
of the document.
For the most up-to-date information on development tools, see the MPLAB® X IDE online help.
Select the Help menu, and then Topics to open a list of available online help files.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 8 2013 Microchip Technology Inc.
DOCUMENT LAYOUT
This document describes how to use GNU language tools to write code for 32-bit
applications. The document layout is as follows:
Part 1 – MPLAB XC32 Assembler
Chapter 1. Assembler Overview – gives an overview of assembler operation.
Chapter 2. Assembler Command-Line Options – details command-line options
for the assembler.
Chapter 3. MPLAB XC32 Assembly Language – discusses the source
language used by the macro assembler.
Chapter 4. Assembler Directives – describes the assembler commands in the
source code.
Chapter 5. Assembler Errors/Warnings/Messages – provides a descriptive list
of the errors, warnings and messages.
Part 2 – MPLAB XC32 Object Linker
Chapter 6. Linker Overview – gives an overview of linker operation.
Chapter 7. Linker Command-Line Interface – details command-line options for
the linker.
Chapter 8. Linker Scripts – describes how to generate and use linker scripts to
control linker operation.
Chapter 9. Linker Processing – discusses how the linker builds an application
from input files.
Chapter 10. Linker Examples – includes a number of 32-bit-specific linker
examples.
Chapter 11. Linker Errors/Warnings – provides a descriptive list of the errors
and warnings.
Part 3 – 32-Bit Utilities (including the Archiver/Librarian)
Chapter 12. MPLAB XC32 Object Archiver/Librarian details command-line
options for the archiver/librarian.
Chapter 13. Other Utilities – details the other utilities and their operation.
Part 4 – Appendices
Appendix A. Deprecated Features – discusses the features considered
obsolete.
Appendix B. Useful Tables – lists some useful tables: the ASCII character set
and hexadecimal to decimal conversion.
Appendix C. GNU Free Documentation License – details the license
requirements for using the GNU language tools.
File>Save
Preface
2013 Microchip Technology Inc. DS50002186A-page 9
CONVENTIONS USED IN THIS GUIDE
The following conventions may appear in this documentation:
DOCUMENTATION CONVENTIONS
Description Represents Examples
Arial font:
Italic characters Referenced books MPLAB® X IDE User’s Guide
Emphasized text ...is the only compiler...
Initial caps A window the Output window
A dialog the Settings dialog
A menu selection select Enable Programmer
Quotes A field name in a window or
dialog
“Save project before build”
Underlined, italic text with
right angle bracket
A menu path File>Save
Bold characters A dialog button Click OK
A tab Click the Power tab
Text in angle brackets < > A key on the keyboard Press <Enter>, <F1>
Courier font:
Plain Courier Sample source code #define START
Filenames autoexec.bat
File paths c:\mcc18\h
Keywords _asm, _endasm, static
Command-line options -Opa+, -Opa-
Bit values 0, 1
Constants 0xFF, ’A’
Italic Courier A variable argument file.o, where file can be
any valid filename
Square brackets [ ] Optional arguments mpasmwin [options]
file [options]
Curly brackets and pipe
character: { | }
Choice of mutually exclusive
arguments; an OR selection
errorlevel {0|1}
Ellipses... Replaces repeated text var_name [,
var_name...]
Represents code supplied by
user
void main (void)
{ ...
}
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 10 2013 Microchip Technology Inc.
RECOMMENDED READING
This documentation describes how to use 32-bit language tools. Other useful
documents are listed below. The following Microchip documents are available and
recommended as supplemental reference resources.
Readme Files
For the latest information on Microchip tools, read the associated Readme files (HTML
files) included with the software.
MPLAB® XC32 C/C++ Compiler User's Guide (DS51686)
A guide to using the 32-bit C compiler. The 32-bit linker is used with this tool.
32-Bit Language Tools Libraries (DS51685)
A descriptive listing of libraries available for Microchip 32-bit devices. This includes
standard (including math) libraries and compiler built-in functions. 32-bit peripheral
libraries are described in HTML files provided with each peripheral library type.
Device-Specific Documentation
The Microchip website contains many documents that describe 32-bit device functions
and features. Among these are:
Individual and family data sheets
Family reference manuals
Programmer’s reference manuals
Preface
2013 Microchip Technology Inc. DS50002186A-page 11
THE MICROCHIP WEB SITE
Microchip provides online support via our web site at www.microchip.com. This web
site is used as a means to make files and information easily available to customers.
Accessible by using your favorite Internet browser, the web site contains the following
information:
Product Support – Data sheets and errata, application notes and sample
programs, design resources, user’s guides and hardware support documents,
latest software releases and archived software
General Technical Support – Frequently Asked Questions (FAQs), technical
support requests, online discussion groups, Microchip consultant program
member listing
Business of Microchip – Product selector and ordering guides, latest Microchip
press releases, listing of seminars and events, listings of Microchip sales offices,
distributors and factory representatives
myMICROCHIP PERSONALIZED NOTIFICATION SERVICE
Microchip's personal notification service helps keep customers current on their
Microchip products of interest. Subscribers will receive e-mail notification whenever
there are changes, updates, revisions or errata related to a specified product family or
development tool.
Please visit http://www.microchip.com/pcn to begin the registration process and select
your preferences to receive personalized notifications. A FAQ and registration details
are available on the page, which can be opened by selecting the link above.
When you are selecting your preferences, choosing “Development Systems” will
populate the list with available development tools. The main categories of tools are
listed below:
Compilers – The latest information on Microchip C compilers, assemblers, linkers
and other language tools. These include all MPLAB C compilers; all MPLAB
assemblers (including MPASM™ assembler); all MPLAB linkers (including
MPLINK™ object linker); and all MPLAB librarians (including MPLIB™ object
librarian).
Emulators The latest information on the Microchip MPLAB REAL ICE™
In-Circuit Emulator.
In-Circuit Debuggers – The latest information on Microchip MPLAB ICD 3
In-Circuit Debugger and PICkit™ 3 In-Circuit Debugger/Programmer.
MPLAB® X IDE – The latest information on Microchip MPLAB X IDE, the Inte-
grated Development Environment for development systems tools. This list is
focused on the MPLAB X IDE, MPLAB X IDE Project Manager, MPLAB X Editor
and MPLAB X SIM simulator, as well as general editing and debugging features.
Programmers – The latest information on Microchip programmers. These include
the device (production) programmers MPLAB REAL ICE in-circuit emulator,
MPLAB ICD 3 In-Circuit Debugger, MPLAB PM3 and development
(non-production) programmers PICkit 3 In-Circuit Debugger/Programmer.
Starter/Demo Boards – These include MPLAB Starter Kit boards, PICDEM™
demonstration boards, and various other evaluation boards.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 12 2013 Microchip Technology Inc.
CUSTOMER SUPPORT
Users of Microchip products can receive assistance through several channels:
Distributor or Representative
Local Sales Office
Field Application Engineer (FAE)
Technical Support
Customers should contact their distributor, representative or field application engineer
(FAE) for support. Local sales offices are also available to help customers. A listing of
sales offices and locations is included in the back of this document.
Technical support is available through the web site at: http://support.microchip.com.
Documentation errors or comments may be emailed to docerrors@microchip.com.
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 13
Part 1 – MPLAB XC32 Assembler
Chapter 1. Assembler Overview ................................................................................. 15
Chapter 2. Assembler Command-Line Options ........................................................ 23
Chapter 3. MPLAB XC32 Assembly Language.......................................................... 41
Chapter 4. Assembler Directives ................................................................................ 57
Chapter 5. Assembler Errors/Warnings/Messages................................................... 81
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 14 2013 Microchip Technology Inc.
NOTES:
6‘ MICROCHIP Assembler 4 { Archwer1berzflzn)] 4 l { ]
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 15
Chapter 1. Assembler Overview
1.1 INTRODUCTION
MPLAB® XC32 Assembler (xc32-as) produces relocatable machine code from sym-
bolic assembly language for the PIC32 MCU family of devices. The assembler is a
Windows® operating system console application that provides a platform for develop-
ing assembly language code. The assembler is a port of the GNU assembler from the
Free Software Foundation.
Topics covered in this chapter are:
Assembler and Other Development Tools
Feature Set
Input/Output Files
1.2 ASSEMBLER AND OTHER DEVELOPMENT TOOLS
MPLAB XC32 Assembler translates user assembly source files. In addition, the
MPLAB XC32 C/C++ Compiler uses the assembler to produce its object file.
After the C preprocessor processes the assembly source file (*.S), the assembler gen-
erates a relocatable object file that can then be put into an archive or linked with other
relocatable object files and archives to create an executable file. See Figure 1-1 for an
overview of the tools process flow.
FIGURE 1-1: TOOLS PROCESS FLOW
Object File Libraries
(*.a)
Assembler
Linker
C Source Files
(*.c)
C Compiler
Source Files (*.s)
Assembly Source
Files (*.S)
Object Files
(*.o)
Executable File
(*.elf)
Archiver (Librarian)
Command Line
Simulator
Compiler
Driver
Program
MPLAB® IDE
Debug Tool
Linker Script
(*.ld)
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 16 2013 Microchip Technology Inc.
1.3 FEATURE SET
Notable features of the assembler include:
Support for the MIPS32, MIPS16e and microMIPS instruction sets
Support for ELF object format
Available for Linux®, OS X®, and and Windows operating systems
Rich Directive Set
Flexible Macro Language
Command-Line Interface
Integrated component of MPLAB X IDE
Assembler Overview
2013 Microchip Technology Inc. DS50002186A-page 17
1.4 INPUT/OUTPUT FILES
Standard assembler input and output files are listed below.
Unlike the MPASM™ Assembler (for use with 8-bit PIC® MCUs), MPLAB XC32 Assem-
bler does not generate error files, hex files, or symbol and debug files. The XC32
assembler is capable of creating a listing file and a relocatable object file (that may or
may not contain debugging information). MPLAB Linker for PIC32 MCUs is used with
the assembler to produce the final object files, map files and a final executable file for
debugging with MPLAB X IDE (see Figure 1-1).
1.4.1 Source Files
The assembler accepts, as input, a source file that consists of PIC32 instructions,
assembler directives and comments. A sample source file is shown in Example 1-1.
EXAMPLE 1-1: SAMPLE ASSEMBLER CODE
Updated example code:
#include <xc.h>
#define IOPORT_BIT_7 (1 << 7)
.global main /* define all global symbols here */
.text
/* define which section (for example "text")
* does this portion of code resides in. Typically,
* all your code will reside in .text section as
* shown below.
*/
.set noreorder
/* This is important for an assembly programmer. This
* directive tells the assembler not to optimize
* the order of the instructions as well as not to insert
* 'nop' instructions after jumps and branches.
*/
/*********************************************************************
* main()
* This is where the PIC32 start-up code will jump to after initial
* set-up.
********************************************************************/
Extension Description
Input
.S Assembly source file to be preprocessed (recommended)
.s Source File
Output
.o Object File
.1st Listing File
Note: Microchip Technology strongly suggests an .S extension for assembly
source files. This will enable you to easily use the C compiler driver without
having to specify the option to tell the driver that the file should be treated
as an assembly file. The capitalized S also indicates that the source file
should be preprocessed by the C preprocessor before being passed to the
assembler. See theMPLAB XC32 C/C++ Compiler User’s Guide”
(DS51686) for more details on the C compiler driver.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 18 2013 Microchip Technology Inc.
.ent main /* directive that marks symbol 'main' as function in the ELF
* output
*/
main:
/* Call function to clear bit relevant to pin 7 of port A.
* The 'jal' instruction places the return address in the $ra
* register.
*/
ori a0, $0, IOPORT_BIT_7
jal mPORTAClearBits
nop
/* endless loop */
endless:
j endless
nop
.end main /* directive that marks end of 'main' function and its
* size in the ELF output
*/
/*********************************************************************
* mPORTAClearBits(int bits)
* This function clears the specified bits of IOPORT A.
*
* pre-condition: $ra contains return address
* Input: Bit mask in $a0
* Output: none
* Side effect: clears bits in IOPORT A
********************************************************************/
.ent mPORTAClearBits
mPORTAClearBits:
/* function prologue - save registers used in this function
* on stack and adjust stack-pointer
*/
addiu sp, sp, -4
sw s0, 0(sp)
la s0, LATACLR
sw a0, 0(s0) /* clear specified bits */
/* function epilogue - restore registers used in this function
* from stack and adjust stack-pointer
*/
lw s0, 0(sp)
addiu sp, sp, 4
/* return to caller */
jr ra
nop
.end mPORTAClearBits
Assembler Overview
2013 Microchip Technology Inc. DS50002186A-page 19
1.4.2 Object File
The assembler creates a relocatable ELF object file. The object files do not have
addresses resolved, yet, and must be linked, before they can be used for an
executable.
By default, the name of the object file created is a.out. Specify the -o option (see
Chapter 2. “Assembler Command-Line Options”) on the command line to override
the default name.
1.4.3 Listing File
The assembler has the capability to produce a listing file. The listing file is not an abso-
lute listing file, and the addresses that appear in the listing are relative to the start of its
section.
By default, the listing file is displayed on standard output. Specify the -a=<file>
option (see Chapter 2. “Assembler Command-Line Options”) on the command line
to send the listing file to a specified file.
A listing file produced by the assembler is composed of the elements listed below.
Example 1-2 shows a sample listing file.
1.4.3.1 HEADER
The header contains the name of the assembler, the name of the file being assembled,
and a page number. This is not shown if the -an option is specified.
1.4.3.2 TITLE
The title line contains the title specified by the .title directive. This is not shown if
the -an option is specified.
1.4.3.3 SUBTITLE
The subtitle line contains the subtitle specified by the .sbttl directive. This is not
shown if the -an option is specified.
1.4.3.4 HIGH-LEVEL SOURCE
High-level source will be present if the -ah option is given to the assembler. The format
for high-level source is:
<line #>:<filename> **** <source>
For example:
1:hello.c **** #include <stdio.h>
1.4.3.5 ASSEMBLER SOURCE
Assembler source will be present if the -al option is given to the assembler. The
format for assembler source is:
<line #> <addr> <encoded bytes> <source>
For example:
35 0000 80000434 ori $a0, $zero, IOPORT_BIT_7
Note 1: Line numbers may be repeated.
2: Addresses are relative to sections in this module and are not absolute.
3: Instructions are encoded in “little endian” order.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 20 2013 Microchip Technology Inc.
1.4.3.6 SYMBOL TABLE
A symbol table is present if the -as option is given to the assembler. A list of defined
symbols and a list of undefined symbols will be given.
The defined symbols will have the format:
DEFINED SYMBOLS
<filename>:<line #> <section>:<addr> <symbol>
For example:
DEFINED SYMBOLS
foo.S:79 .text:00000000 main
foo.S:107 .text:00000014 mPORTAClearBits
The undefined symbols will have the format:
UNDEFINED SYMBOLS
<symbol>
For example:
UNDEFINED SYMBOLS
WDTCON
WDTCONCLR
EXAMPLE 1-2: SAMPLE ASSEMBLER LISTING FILE
GAS LISTING foo.s page 1
1 # 1 "foo.S"
2 # 1 "<built-in>"
1 .nolist
0
0
3 .list
4
5 #define IOPORT_BIT_7 (1 << 7)
6
8 .global baz /* define all global symbols here */
9
10 /* define which section (for example "text")
11 * does this portion of code resides in.
12 * Typically, all of your code will reside in
* the .text section as shown.
14 */
15 .text
16
17 /* This is important for an assembly programmer.
18 * This directive tells the assembler not to
19 * optimize the order of the instructions
20 * as well as not to insert 'nop' instructions
21 * after jumps and branches.
22 */
23 .set noreorder
24
25 .ent baz /* directive that marks symbol 'baz' as
26 * a function in ELF output
27 */
28
29 baz:
30
31 /* Call function to clear bit relevant to pin
32 * 7 in port A. The 'jal' instruction places
Assembler Overview
2013 Microchip Technology Inc. DS50002186A-page 21
33 * the return address in $ra.
34 */
35 0000 80000434 ori $a0, $zero, IOPORT_BIT_7
36 0004 0500000C jal mPORTAClearBits
37 0008 00000000 nop
38
39 /* endless loop */
40 endless:
41 000c 03000008 j endless
42 0010 00000000 nop
43
44 .end baz /* directive that marks end of 'baz'
45 * function and registers size in ELF
46 * output
47 */
DEFINED SYMBOLS
*ABS*:00000000 foo.S
*ABS*:00000001 __DEBUG
foo.S:56 .text:00000014 mPORTAClearBits
foo.S:38 .text:0000000c endless
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 22 2013 Microchip Technology Inc.
NOTES:
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 23
Chapter 2. Assembler Command-Line Options
2.1 INTRODUCTION
MPLAB XC32 Assembler (xc32-as) may be used on the host PC's command-line
interface (e.g., cmd.exe) as well as with the MPLAB X IDE project manager.
The MPLAB X IDE project manager automatically calls the assembler (via the xc32-gcc
compilation driver) when building a project. Many of the commonly used options listed
here are available as check boxes on the MPLAB X IDE project build-options dialog.
However, for a more advanced option, you may have to specify the option in the “Alter-
nate Settings” field of the dialog. After you build a project in MPLAB X IDE, the output
window shows the options passed to the assembler.
Topics covered in this chapter are:
Assembler Interface Syntax
Compilation-Driver Interface Syntax
Options that Modify the Listing Output
Options that Control Informational Output
Options that Control Output File Creation
Assembler Symbol-Definition and Search-Path Options
Compilation-Driver and Preprocessor Options
2.2 ASSEMBLER INTERFACE SYNTAX
The assembler command line may contain options and file names. Options may appear
in any order and may be before, after or between file names. The order of file names
determines the order of assembly.
xc32-as [options|sourcefiles]...
--’ (two hyphens) by itself names the standard input file explicitly, as one of the files
for the assembler to translate. Except for ‘--’, any command line argument that begins
with a hyphen (-’) is an option. Each option changes the behavior of the assembler,
but no option changes the way another option works.
Some options require exactly one file name to follow them. The file name may either
immediately follow the option’s letter or it may be the next command line argument. For
example, to specify an output file named test.o, either of the following options would
be acceptable:
-o test.o
-otest.o
Note: command-line options are case sensitive.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 24 2013 Microchip Technology Inc.
2.3 COMPILATION-DRIVER INTERFACE SYNTAX
The compilation-driver program (xc32-gcc) preprocesses, compiles, assembles, and
links C and assembly-language modules and library archives. This driver orchestrates
the build process so that you often don't need to know which individual programs pre-
process, compile, assemble, and link. The driver calls the appropriate individual tools
to complete the requested build process.
In practice, the assembler is usually invoked via xc32-gcc, which determines that it
should assemble an input file by its *.S or *.s filename extension. The compilation
driver sends a file with a *.S (upper case) extension through the CPP-style preproces-
sor before it passes the file to the assembler while the driver sends a file with a *.s
(lower case) extension directly to the assembler.
The basic form of the compilation-driver command line is:
xc32-gcc [options] files
To pass an assembler option from the compilation driver to the assembler, use the
-Wa,option option. The option argument should not contain white space.
EXAMPLE 2-1: EXAMPLE COMPILATION-DRIVER COMMAND LINE
xc32-gcc -mprocessor=32MX360F512L -I"./include" ASMfile.S
-o"ASMfile.o" -DMYMACRO=1 -Wa,-ah="ASMfile.lst"
For additional information on the compilation driver, see the “MPLAB XC32 C/C++
Compiler User’s Guide” (DS51686).
Note: Command-line options and filename extensions are case sensitive.
Note: To use the xc32-gcc compilation driver from MPLAB X IDE, be sure to
select the XC32 Compiler Toolchain for your project.
Assembler Command-Line Options
2013 Microchip Technology Inc. DS50002186A-page 25
2.4 OPTIONS THAT MODIFY THE LISTING OUTPUT
The following options are used to control the listing output. A listing file is helpful for
debugging and general analysis of code operation. Use the following options to
construct a listing file with information that you find useful.
-a[suboption] [=file]
--listing-lhs-width num
--listing-lhs-width2 num
--listing-rhs-width num
--listing-cont-lines num
2.4.1 -a[suboption] [=file]
The -a option enables listing output. The -a option supports the following sub options
to further control what is included in the assembly listing:
If no sub-options are specified, the default sub-options used are hls; the -a option by
itself requests high-level, assembly, and symbolic listing. You can use other letters to
select specific options for the listing output.
The letters after the -a may be combined into one option. So for example instead of
specifying -al -an on the command line, you could specify -aln.
-ac Omit false conditionals
-ad Omit debugging directives
-ah Include high-level source
-al Include assembly
-am Include macro expansions
-an Omit forms processing
-as Include symbols
-a=file Output listing to specified file (must be in current directory).
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 26 2013 Microchip Technology Inc.
2.4.1.1 -ac
-ac omits false conditionals from a listing. Any lines that are not assembled because
of a false .if or .ifdef (or the .else of a true .if or .ifdef) will be omitted from
the listing. Example 2-2 shows a listing where the -ac option was not used.
Example 2-3 shows a listing for the same source where the -ac option was used.
EXAMPLE 2-2: LISTING FILE GENERATED WITH -al COMMAND LINE
OPTION
GAS LISTING asm.s page 1
1 # 1 "asm.S"
2 # 1 "<built-in>"
1 .data
0
2 .if 0
3 .if 1
4 .endif
5 .long 0
6 .if 0
7 .long 0
8 .endif
9 .else
10 .if 1
11 .endif
12 0000 02000000 .long 2
13 .if 0
14 .long 3
15 .else
16 0004 04000000 .long 4
17 .endif
18 .endif
19 .if 0
20 .long 5
21 .elseif 1
22 .if 0
23 .long 6
24 .elseif 1
25 0008 07000000 .long 7
26 .endif
27 .elseif 1
28 .long 8
29 .else
30 .long 9
31 .endif
Assembler Command-Line Options
2013 Microchip Technology Inc. DS50002186A-page 27
EXAMPLE 2-3: LISTING FILE GENERATED WITH -alc COMMAND LINE
OPTION
GAS LISTING asm.s page 1
1 # 1 "asm.S"
2 # 1 "<built-in>"
1 .data
0
0
2 .if 0
9 .else
10 .if 1
11 .endif
12 0000 02000000 .long 2
13 .if 0
15 .else
16 0004 04000000 .long 4
17 .endif
18 .endif
19 .if 0
21 .elseif 1
22 .if 0
24 .elseif 1
25 0008 07000000 .long 7
26 .endif
27 .elseif 1
29 .else
31 .endif
Note: Some lines omitted due to -ac option.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 28 2013 Microchip Technology Inc.
2.4.1.2 -ad
-ad omits debugging directives from the listing. This option is useful when processing
compiler-generated assembly code containing debugging information, the compiler-
generated debugging directives will not clutter the listing. Example 2-4 shows a listing
using both the d and h sub-options. Compared to using the h sub-option alone (see the
next section), the listing is much cleaner.
EXAMPLE 2-4: LISTING FILE GENERATED WITH -alhd COMMAND LINE
OPTION
GAS LISTING test.s page 1
1 .section .mdebug.abi32
2 .previous
10 .Ltext0:
11 .align2
12 .globlmain
13 .LFB0:
14 .file 1 "src\\test.c"
1:src/test.c **** #include <xc.h>
2:src/test.c **** volatile unsigned int testval;
3:src/test.c ****
4:src/test.c **** int
5:src/test.c **** main (void)
6:src/test.c **** {
15 .loc 1 6 0
16 .setnomips16
17 .entmain
18 main:
19 .frame$fp,8,$31# vars= 0, regs= 1/0, args= 0, gp= 0
20 .mask0x40000000,-8
21 .fmask0x00000000,0
22 .setnoreorder
23 .setnomacro
24
25 0000 F8FFBD27 addiu$sp,$sp,-8
26 .LCFI0:
27 0004 0000BEAF sw$fp,0($sp)
28 .LCFI1:
29 0008 21F0A003 move$fp,$sp
30 .LCFI2:
7:src/test.c **** testval += 1;
31 .loc 1 7 0
32 000c 0000828F lw$2,%gp_rel(testval)($28)
33 0010 01004224 addiu$2,$2,1
34 0014 000082AF sw$2,%gp_rel(testval)($28)
8:src/test.c **** return 0;
35 .loc 1 8 0
36 0018 21100000 move$2,$0
9:src/test.c **** }
37 .loc 1 9 0
38 001c 21E8C003 move$sp,$fp
39 0020 0000BE8F lw$fp,0($sp)
40 0024 0800BD27 addiu$sp,$sp,8
41 0028 0800E003 j$31
42 002c 00000000 nop
Assembler Command-Line Options
2013 Microchip Technology Inc. DS50002186A-page 29
43
44 .setmacro
45 .setreorder
46 .endmain
47 .LFE0:
49
50 .commtestval,4,4
88 .Letext0:
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 30 2013 Microchip Technology Inc.
2.4.1.3 -ah
-ah requests a high-level language listing. High-level listings require that the assembly
source code was generated by a compiler, a debugging option like -g was given to the
compiler, and that assembly listings (-al) are also requested. -al requests an output
program assembly listing. Example 2-5 shows a listing that was generated using the
-alh command line option.
EXAMPLE 2-5: LISTING FILE GENERATED WITH -alh COMMAND LINE
OPTION
GAS LISTING tempfile.s page 1
1 .section .mdebug.abi32
2 .previous
3 .section.debug_abbrev,"",@progbits
4 .Ldebug_abbrev0:
5 .section.debug_info,"",@progbits
6 .Ldebug_info0:
7 .section.debug_line,"",@progbits
8 .Ldebug_line0:
9 0000 34000000 .text
11 .align2
12 .globlmain
13 .LFB0:
14 .file 1 "src/test.c"
1:src/test.c **** #include <xc.h>
2:src/test.c **** volatile unsigned int testval;
3:src/test.c ****
4:src/test.c **** int
5:src/test.c **** main (void)
6:src/test.c **** {
15 .loc 1 6 0
16 .setnomips16
17 .entmain
18 main:
19 .frame$sp,0,$31 # vars= 0, regs= 0/0, args= 0, gp= 0
20 .mask0x00000000,0
21 .fmask0x00000000,0
22 .setnoreorder
23 .setnomacro
24
7:src/test.c **** testval += 1;
25 .loc 1 7 0
26 0000 0000848F lw$4,%gp_rel(testval)($28)
8:src/test.c **** return 0;
9:src/test.c **** }
27 .loc 1 9 0
28 0004 21100000 move$2,$0
29 .loc 1 7 0
30 0008 01008324 addiu$3,$4,1
31 000c 000083AF sw$3,%gp_rel(testval)($28)
32 .loc 1 9 0
33 0010 0800E003 j$31
34 0014 00000000 nop
Assembler Command-Line Options
2013 Microchip Technology Inc. DS50002186A-page 31
35
36 .setmacro
37 .setreorder
38 .endmain
39 .LFE0:
40 .sizemain, .-main
41
42 .commtestval,4,4
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 32 2013 Microchip Technology Inc.
2.4.1.4 -al
-al requests an assembly listing. This sub-option may be used with other sub-options.
See the other examples in this section.
2.4.1.5 -am
-am expands macros in a listing. Example 2-6 shows a listing where the -am option
was not used. Example 2-7 shows a listing for the same source where the -am option
was used.
EXAMPLE 2-6: LISTING FILE GENERATED WITH -al COMMAND LINE
OP
TION
GAS LISTING foo.s page 1
1 # 1 "foo.S"
2 # 1 "<built-in>"
1 .macro sum from=0, to=5
0
0
2 .long \from
3 .if \to-\from
4 sum "(\from+1)",\to
5 .endif
6 .endm
7
8 .data
9 0000 00000000 .long 0
10 0004 0A000000 sum 10, 14
10 0B000000
10 0C000000
10 0D000000
10 0E000000
11 0018 00000000 .long 0
Assembler Command-Line Options
2013 Microchip Technology Inc. DS50002186A-page 33
EXAMPLE 2-7: LISTING FILE GENERATED WITH -alm COMMAND LINE
OPTION
GAS LISTING foo.s page 1
1 # 1 "foo.S"
2 # 1 "<built-in>"
1 .macro sum from=0, to=5
0
0
2 .long \from
3 .if \to-\from
4 sum "(\from+1)",\to
5 .endif
6 .endm
7
8 .data
9 0000 00000000 .long 0
10 sum 10, 14
10 0004 0A000000 > .long 10
10 > .if 14-10
10 > sum "(10+1)",14
10 0008 0B000000 >> .long (10+1)
10 >> .if 14-(10+1)
10 >> sum "((10+1)+1)",14
10 000c 0C000000 >>> .long ((10+1)+1)
10 >>> .if 14-((10+1)+1)
10 >>> sum "(((10+1)+1)+1)",14
10 0010 0D000000 >>>> .long (((10+1)+1)+1)
10 >>>> .if 14-(((10+1)+1)+1)
10 >>>> sum "((((10+1)+1)+1)+1)",14
10 0014 0E000000 >>>>> .long ((((10+1)+1)+1)+1)
10 >>>>> .if 14-((((10+1)+1)+1)+1)
10 >>>>> sum "(((((10+1)+1)+1)+1)+1)",14
10 >>>>> .endif
10 >>>> .endif
10 >>> .endif
10 >> .endif
10 > .endif
11 0018 00000000 .long 0
Note: > signifies expanded macro instructions.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 34 2013 Microchip Technology Inc.
2.4.1.6 -an
-an turns off all forms processing that would be performed by the listing directives
.psize, .eject, .title and .sbttl. Example 2-8 shows a listing where the -an
option was not used. Example 2-9 shows a listing for the same source where the -an
option was used.
EXAMPLE 2-8: LISTING FILE GENERATED WITH -al COMMAND LINE
OPTION
GAS LISTING foo.s page 1
User's Guide Example
Listing Options
1 # 1 "foo.S"
2 # 1 "<built-in>"
1 .text
0
0
2 .title "User's Guide Example"
3 .sbttl "Listing Options"
GAS LISTING foo.s page 2
User's Guide Example
Listing Options
4 .psize 10
5
6 0000 01001A3C lui $k0, 1
7 0004 02001A3C lui $k0, 2
8 0008 03001A3C lui $k0, 3
9 .eject
GAS LISTING foo.s page 3
User's Guide Example
Listing Options
10 000c 04001A3C lui $k0, 4
11 0010 05001A3C lui $k0, 5
EXAMPLE 2-9: LISTING FILE GENERATED WITH -aln COMMAND LINE
OPTION
1 # 1 "foo.S"
2 # 1 "<built-in>"
1 .text
0
0
2 .title "User's Guide Example"
3 .sbttl "Listing Options"
4 .psize 10
5
6 0000 01001A3C lui $k0, 1
7 0004 02001A3C lui $k0, 2
8 0008 03001A3C lui $k0, 3
9 .eject
10 000c 04001A3C lui $k0, 4
11 0010 05001A3C lui $k0, 5
Assembler Command-Line Options
2013 Microchip Technology Inc. DS50002186A-page 35
2.4.1.7 -as
-as requests a symbol table listing. Example 2-10 shows a listing that was generated
using the -as command line option. Note that both defined and undefined symbols are
listed.
EXAMPLE 2-10: LISTING FILE GENERATED WITH -as COMMAND LINE
OPTION
GAS LISTING example.s page 1
DEFINED SYMBOLS
*ABS*:00000000 src\example.c
example.s:18 .text:00000000 main
*COM*:00000004 testval
UNDEFINED SYMBOLS
bar
2.4.1.8 -a=file
=file defines the name of the output file. This file must be in the current directory.
2.4.2 --listing-lhs-width num
The --listing-lhs-width option is used to set the width of the output data column
of the listing file. By default, this is set to 1 word. The following line is extracted from a
listing. The output data column is in bold text.
2 0000 54686973 .ascii "This is an example"
2 20697320
2 616E2065
2 78616D70
2 6C650000
If the option --listing-lhs-width 2 is used, then the same line will appear as
follows in the listing:
2 0000 54686973 20697320 .ascii "This is an example"
2 616E2065 78616D70
2 6C650000
2.4.3 --listing-lhs-width2 num
The --listing-lhs-width2 option is used to set the width of the continuation lines
of the output data column of the listing file. By default, this is set to 1. If the specified
width is smaller than the first line, this option is ignored. The following lines are
extracted from a listing. The output data column is in bold.
2 0000 54686973 .ascii "This is an example"
2 20697320
2 616E2065
2 78616D70
2 6C650000
If the option --listing-lhs-width2 3 is used, then the same line will appear as
follows in the listing:
2 0000 54686973 .ascii "This is an example"
2 20697320 616E2065 78616D70
2 6C650000
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 36 2013 Microchip Technology Inc.
2.4.4 --listing-rhs-width num
The --listing-rhs-width option is used to set the maximum width in characters
of the lines from the source file. By default, this is set to 100. The following lines are
extracted from a listing that was created without using the --listing-rhs-width
option. The text in bold are the lines from the source file.
2 0000 54686973 .ascii "This line is long"
2 206C696E
2 65206973
2 206C6F6E
2 67000000
If the option --listing-rhs-width 22 is used, then the same line will appear as
follows in the listing:
2 0000 54686973 .ascii "This line is
2 206C696E
2 65206973
2 206C6F6E
2 67000000
The line is truncated (not wrapped) in the listing, but the data is still there.
2.4.5 --listing-cont-lines num
The --listing-cont-lines option is used to set the maximum number of continu-
ation lines used for the output data column of the listing. By default, this is 8. The fol-
lowing lines are extracted from a listing that was created without using the
--listing-cont-lines option. The text in bold shows the continuation lines used
for the output data column of the listing.
2 0000 54686973 .ascii "This is a long character
sequence"
2 20697320
2 61206C6F
2 6E672063
2 68617261
Notice that the number of bytes displayed matches the number of bytes in the ASCII
string; however, if the option --listing-cont-lines 2 is used, then the output
data will be truncated after 2 continuation lines as shown below.
2 0000 54686973 .ascii "This is a long character
sequence"
2 20697320
2 61206C6F
Assembler Command-Line Options
2013 Microchip Technology Inc. DS50002186A-page 37
2.5 OPTIONS THAT CONTROL INFORMATIONAL OUTPUT
The options in this section control how information is output. Errors, warnings and
messages concerning code translation and execution are controlled through several of
the options in this section.
Any item in parentheses shows the short method of specifying the option, e.g.,
--no-warn also may be specified as -W.
2.5.1 --fatal-warnings
Warnings are treated as if they were errors.
2.5.2 --no-warn (-W)
Warnings are suppressed. If you use this option, no warnings are issued. This option
only affects the warning messages. It does not change how your file is assembled.
Errors are still reported.
2.5.3 --warn
Warnings are issued, if appropriate. This is the default behavior.
2.5.4 -J
No warnings are issued about signed overflow.
2.5.5 --help
The assembler will show a message regarding the command line usage and options.
The assembler then exits.
2.5.6 --target-help
The assembler will show a message regarding the PIC32 target-specific command-line
options. The assembler then exits.
2.5.7 --version
The assembler version number is displayed. The assembler then exits.
2.5.8 --verbose (-v)
The assembler version number is displayed. The assembler does not exit. If this is the
only command line option used, then the assembler will print out the version and wait
for entry of the assembly source through standard input. Use <CTRL>-D to send an
EOF character to end assembly.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 38 2013 Microchip Technology Inc.
2.6 OPTIONS THAT CONTROL OUTPUT FILE CREATION
The options in this section control how the output file is created. For example, to
change the name of the output object file, use -o.
Any item in parentheses shows the short method of specifying the option, e.g.,
--keep-locals may be specified as -L also.
2.6.1 -g
Generate symbolic debugging information.
2.6.2 --keep-locals (-L)
Keep local symbols, i.e., labels beginning with .L (upper case only). Normally you do
not see such labels when debugging, because they are intended for the use of
programs (like compilers) that compose assembler programs. Normally both the
assembler and linker discard such symbols. This option tells the assembler to retain
those symbols in the object files.
2.6.3 -o objfile
Name the object file output objfile. In the absence of errors, there is always one
object file output when you run the assembler. By default, it has the name a.out. Use
this option (which takes exactly one filename) to give the object file a different name.
Whatever the object file is called, the assembler overwrites any existing file with the
same name.
2.6.4 -Z
Generate object file even after errors. After an error message, the assembler normally
produces no output. If for some reason, you are interested in object file output even
after the assembler gives an error message, use the -Z option. If there are any errors,
the assembler continues anyway, and writes an object file after a final warning
message of the form “n errors, m warnings, generating bad object file”.
2.6.5 -MD file
Write dependency information to file. The assembler can generate a dependency
file. This file consists of a single rule suitable for describing the dependencies of the
main source file. The rule is written to the file named in its argument. This feature can
be used in the automatic updating of makefiles.
Assembler Command-Line Options
2013 Microchip Technology Inc. DS50002186A-page 39
2.7 ASSEMBLER SYMBOL-DEFINITION AND SEARCH-PATH OPTIONS
The options in this section perform functions not defined in previous sections.
2.7.1 --defsym sym=value
Define symbol sym to given value.
2.7.2 -I dir
Use this option to add dir to the list of directories that the assembler searches for files
specified in .include directives. You may use -I as many times as necessary to
include a variety of paths. The current working directory is always searched first; after
that, the assembler searches any -I directories in the same order as they were
specified (left to right) on the command line.
When passed directly to the assembler, this option affects the search path used by the
assembler's .include directive. To affect the search path used by the C preprocessor
for a #include directive, pass the corresponding option to the xc32-gcc compilation
driver.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 40 2013 Microchip Technology Inc.
2.8 COMPILATION-DRIVER AND PREPROCESSOR OPTIONS
The compilation-driver (xc32-gcc) and C preprocessor options in this section may be
useful for assembly-code projects. The compilation driver will pass the options to the
preprocessor as required. See the “MPLAB XC32 C/C++ Compiler User’s Guide”
(DS51686) for more information on the compilation driver and for a more
comprehensive list of driver options.
2.8.1 -mprocessor=device
Selects the device for which to compile (e.g., -mprocessor=32MX360F512L).
2.8.2 -Wa,option
Pass option as an option to the assembler. If option contains commas, it is split into
multiple assembler options at the commas. The option argument must not contain
white space.
2.8.3 -Dmacro=defn
Define macro macro as defn. All instances of -D on the command line are processed
before any -U options.
2.8.4 -Dmacro
Define macro macro as 1. All instances of -D on the command line are processed
before any -U options.
2.8.5 -Umacro
Undefine macro macro. -U options are evaluated after all -D options, but before any
-include and -imacros options.
2.8.6 -I dir
Add the directory dir to the head of the list of directories to be searched for #include
preprocessor header files. This can be used to override a system header file, substitut-
ing your own version, since these directories are searched before the system header
file directories. If you use more than one -I option, the directories are scanned in
left-to-right order. The standard system directories come after.
When passed to the compilation driver, this option affects the search path used by the
preprocessor's #include directive. To affect the search path used by the assembler's
.include directive, pass the corresponding option to the assembler using the -Wa
option.
2.8.7 -save-temps
Do not delete intermediate files. Place them in the current directory and name them
based on the source file. Thus, compiling foo.c with -c -save-temps would
produce the following files:
foo.i (preprocessed file)
foo.s (assembly language file)
foo.o (object file)
2.8.8 -v
Print the commands executed during each stage of compilation.
2.8.9 --help
Print a description of the command-line options.
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 41
Chapter 3. MPLAB XC32 Assembly Language
3.1 INTRODUCTION
The source language accepted by the macro assembler is described here. All opcode
mnemonics and operand syntax are specific to the target device. The same assembler
application is used for compiler-generated intermediate assembly and hand-written
assembly source code.
Topics covered in this chapter are:
Internal Preprocessor
Source Code Format
Special Characters
•Symbols
Giving Symbols Other Values
The Special DOT Symbol
• Expressions
• Operators
Special Operators
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 42 2013 Microchip Technology Inc.
3.2 INTERNAL PREPROCESSOR
The assembler has an internal preprocessor. The internal processor performs the
following actions.
1. Adjusts and removes extra white space. It leaves one space or tab before the
keywords on a line, and turns any other white space on the line into a single
space.
2. Removes all comments, replacing them with a single space, or an appropriate
number of new lines.
3. Converts character constants into the appropriate numeric value.
If you have a single character (e.g., ‘b’) in your source code, it will be changed to
the appropriate numeric value. If you have a syntax error that occurs at the single
character, the assembler will not display ‘b’, but instead display the first digit of
the decimal equivalent.
For example, if you had .global mybuf, ‘b’ in your source code, the error mes-
sage would say “Error: Rest of line ignored. First ignored character is ‘9’.” Notice
the error message says ‘9’. This is because the ‘b’ was converted to its decimal
equivalent 98. The assembler is actually parsing .global mybuf,98
The internal processor does not perform the following actions.
1. macro preprocessing
2. include file handling
3. anything else you may get from your C compiler’s preprocessor
You can do include file preprocessing with the .include directive. See Chapter
4. “Assembler Directives”.
You can use the C compiler driver to get other C-style preprocessing by giving the input
file a .S suffix. See the “MPLAB XC32 C/C++ Compiler User’s Guide” (DS51686) for
more information.
If the first line of an input file is #NO_APP or if you use the -f option, white space and
comments are not removed from the input file. Within an input file, you can ask for white
space and comment removal in certain portions by putting a line that says #APP before
the text that may contain white space or comments, and putting a line that says
#NO_APP after this text. This feature is mainly intended to support assembly
statements in compilers whose output is otherwise free of comments and white space.
Note: Excess white space, comments and character constants cannot be used
in the portions of the input text that are not preprocessed.
MPLAB XC32 Assembly Language
2013 Microchip Technology Inc. DS50002186A-page 43
3.3 SOURCE CODE FORMAT
Assembly source code consists of statements and white spaces.
White space is one or more spaces or tabs. White space is used to separate pieces of
a source line. White space should be used to make your code easier for people to read.
Unless within character constants, any white space means the same as exactly one
space.
Each statement has the following general format and is followed by a new line.
[label:][mnemonic[operands] ][; comment]
OR
[label:][directive[arguments] ][; comment]
• Label
•Mnemonic
•Directive
• Operands
•Arguments
•Comments
3.3.1 Label
A label is one or more characters chosen from the set composed of all letters, digits,
the underline character (_), and the period (.). Labels may not begin with a decimal
digit, except for the special case of a local symbol. (See Section 3.5.1 “Local Sym-
bols” for more information.) Case is significant. There is no length limit; all characters
are significant.
Label definitions must be immediately followed by a colon. A space, a tab, an end of
line, or assembler mnemonic or directive may follow the colon.
Label definitions may appear on a line by themselves and will reference the next
address.
The value of a label after linking is the absolute address of a location in memory.
3.3.2 Mnemonic
Mnemonics tell the assembler which machine instructions to assemble. For example,
addition (ADD), jumps (J), or loads (LUI). Unlike labels that you create yourself, mne-
monics are provided by the PIC32 MCU assembly language. Mnemonics are not case
sensitive.
See the data sheet of your target PIC32 MCU for more details on the CPU
instruction-set mnemonics available for the device.
The assembler also supports a number of synthesized/macro instructions intended to
make writing assembly code easier. The LI (load immediate) instruction is an example
of a synthetic macro instruction. The assembler generates two machine instructions to
load a 32-bit constant value into a register from this single synthetic instruction.
[label:] [mnemonic [operands] ] [; comment]
OR
[label:] [directive [arguments] ] [; comment]
Note: Excess white space, comments and character constants cannot be used in
the portions of the input text that are not preprocessed.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 44 2013 Microchip Technology Inc.
3.3.3 Assembler Syntax
The assembler synthesizes instructions for:
• A 32-bit Load Immediate
• A load from a memory location
• An extended branch conditional
• A two-operand form of some three-operand instructions
• An unaligned load/store instruction
Assembly directives, such as .set noat, .set nomacro, and .set noreorder,
disable these normally helpful features for cases where you require full control over the
generated code. See Section 4.13 “Directives that Control Code Generation”.
3.3.4 Directive
Assembler directives are commands that appear in the source code but are not trans-
lated directly into machine code. Directives are used to control the assembler, its input,
output and data allocation. The first character of a directive is a dot (.). More details
are provided in Chapter 4. “Assembler Directives” on the available directives.
3.3.5 Operands
Each machine instruction takes from 0 up to 4 operands. (See the appropriate data
sheet of your target PIC32 MCU for a full list of machine instructions.) These operands
give information to the instruction on the data that should be used and the storage loca-
tion for the instruction. Operands must be separated from mnemonics by one or more
spaces or tabs.
Separate multiple operands with commas. If commas do not separate your operands,
the assembler displays a warning and takes its best guess on the separation of the
operands. For most PIC32 MCU instructions, an operand consists of a core
general-purpose register, label, literal, or basereg+offset.
3.3.5.1 GENERAL-PURPOSE REGISTER OPERANDS
The PIC32 MCU core contains thirty-two 32-bit general purpose registers used for inte-
ger operations and address calculation. Most of the PIC32 MCU instructions require
one or more GPR operands, either for the source, the destination, or both.
Register operands are distinguished with a preceding dollar sign ('$'). The register
number immediately follows the dollar sign. Example 3-1 shows assembly source code
using register number operands.
However, if you use the compilation driver (xc32-gcc) to preprocess the source code
with the CPP-style preprocessor before assembling, you can take advantage of macros
that are provided in the xc.h header file that is provided with the C compiler. These
macros map conventional register names to the corresponding register number.
Example 3-2 shows assembly source code using conventional register names for oper-
ands. See theMPLAB XC32 C/C++ Compiler User’s Guide” (DS51686) for additional
information on PIC32 MCU register conventions and the compiler's runtime
environment.
EXAMPLE 3-1: ASSEMBLY SOURCE CODE WITH REGISTER NUMBER
OPERANDS
.text
# Add Word
li $2, 123
li $3, 456
add $4, $2, $3
MPLAB XC32 Assembly Language
2013 Microchip Technology Inc. DS50002186A-page 45
EXAMPLE 3-2: ASSEMBLY SOURCE CODE WITH CONVENTIONAL
REGISTER NAMES
#include <xc.h>
.text
/* Add Word */
li v0, 123 /* v0 is a return-value register */
li v1, 456 /* v1 is a return-value register */
add a0, v0, v1 /* a0 is an argument register */
3.3.5.2 LITERAL-VALUE OPERANDS
Literal values can be hexadecimal, octal, binary, or decimal format. Hexadecimal num-
bers are distinguished by a leading 0x. Octal numbers are distinguished by a leading
0. Binary numbers are distinguished by a leading 0B or 0b. Decimal numbers require
no special leading or trailing character.
Example:
0xe, 016, 0b1110 and 14 all represent the literal value 14.
-5 represents the literal value -5.
symbol represents the value of symbol.
3.3.5.3 BASEREG+OFFSET OPERANDS
Load and store operations select the memory location using a BaseReg+Offset oper-
and. For an operand of this type, the effective address is formed by adding the 32-bit
signed offset to the contents of a base register. A PIC32 MCU data sheet shows this
type of operand as Mem[R+offset].
EXAMPLE 3-3: USING ASSEMBLY SOURCE CODE WITH
BASEREG+OFFSET OPERANDS
#include <xc.h>
.data
.align 4
MY_WORD_DATA:
.word 0x10203040, 0x8090a0b0
.text
.global example
/* Store Word */
example:
la v0, MY_WORD_DATA
lui v1,0x1111
ori v1,v1,0x4432
lui a0,0x5555
ori a0,a0,0x1123
sw v1, 0(v0) /* Mem[GPR[v0]+0] <- GPR[v1] */
sw a0, 4(v0) /* Mem[GPR[v0]+4] <- GPR[a0] */
lw a1, 0(v0) /* GPR[a1] <- Mem[GPR[v0]+0] */
b .
The C compiler supports global-pointer relative (gp-rel) addressing. Loads and stores
to data lying within 32 KB of either side of the address stored in the gp register (64 KB
total) can be performed in a single instruction using the gp register as the base register.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 46 2013 Microchip Technology Inc.
The C compiler's -Gnum option controls the maximum size of global and static data
items that can be addressed in one instruction instead of two. The compiler's default
gnum value is 8 bytes, which is large enough to hold all simple scalar variables.
EXAMPLE 3-4: ASSEMBLY SOURCE CODE WITH GP-RELATIVE
ADDRESSING
.align 2
.globl foo
.set nomips32
.ent foo
foo:
.set noreorder
.set nomacro
lw $3,%gp_rel(testval)($28)
addiu $2,$3,1
sw $2,%gp_rel(testval)($28)
j $31
nop
.set macro
.set reorder
.end foo
There are a few potential pitfalls to using gp-relative addressing:
You must take special care when writing assembler code to declare global (i.e.,
public or external) data items correctly:
- Writable, initialized data of gnum bytes or less must be put explicitly into the
.sdata section, for example:
.sdata
small: .word 0x12345678
- Global common data must be declared with the correct size, for example:
.comm small, 4
.comm big, 100
- Small external variables must also be declared correctly, for example:
.extern smallext, 4
If your program has a very large number of small data items or constants, the C
compiler's -G8 option may still try to push more than 64 KB of data into the ''small''
region; the symptom will be obscure relocation errors (''relocation truncated'')
when linking. Fix it by disabling gp-relative addressing with the compiler's -G0
option and/or reducing the space reserved in the small data sections (i.e. .sbss
and .sdata) in your assembly code.
3.3.6 Arguments
Each directive takes 0 to 3 arguments. These arguments give additional information to
the directive on how it should carry out the command. Arguments must be separated
from directives by one or more spaces or tabs. Commas must separate multiple argu-
ments. More details on the available directives are provided in Chapter 4. “Assembler
Directives”.
Note: To utilize gp-relative addressing, the compiler and assembler must group all
of the “small” variables and constants into one of the “small” sections. See
the MPLAB® XC32 C/C++ Compiler User's Guide (DS51686) for more
information on the global pointer and the -G option.
MPLAB XC32 Assembly Language
2013 Microchip Technology Inc. DS50002186A-page 47
3.3.7 Comments
Comments can be represented in the assembler in one of two ways described below.
3.3.7.1 SINGLE LINE COMMENT
This type of comment extends from the comment character to the end of the line. For
a single line comment, use a number/hash sign (#).
3.3.7.2 MULTI-LINE COMMENT
This type of comment can span multiple lines. For a multi-line comment, use
/* ... */. These comments cannot be nested.
Example:
/* All
of these
lines
are
comments */
Note: This comment character differs from the character recognized by the
MPASM assembler and the MPLAB Assembler for PIC24 MCUs and dsPIC
DSCs.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 48 2013 Microchip Technology Inc.
3.4 SPECIAL CHARACTERS
A constant is a value written so that its value is known by inspection, without knowing
any context. Examples are:
.byte 74, 0112, 0b01001010, 0x4A, 0x4a, ’J’, ’\J’#All the same value
.ascii "Ring the bell\7" #A string constant
.float 0f-31415926535897932384626433832795028841971.693993751E-40
3.4.1 Numeric Constants
The assembler distinguishes two kinds of numbers according to how they are stored in
the machine. Integers are numbers that would fit into a long in the C language.
Floating-point numbers are IEEE 754 floating-point numbers.
3.4.1.1 INTEGERS
A binary integer is ‘0b’ or ‘0B’ followed by zero or more of the binary digits ‘01’.
An octal integer is ‘0’ followed by zero or more of the octal digits ‘01234567’.
A decimal integer starts with a non-zero digit followed by zero or more decimal digits
‘0123456789’.
A hexadecimal integer is ‘0x’ or ‘0X’ followed by one or more hexadecimal digits
‘0123456789abcdefABCDEF’.
To denote a negative integer, use the prefix operator ‘-’.
3.4.1.2 FLOATING-POINT NUMBERS
A floating-point number is represented in IEEE 754 format. A floating-point number is
written by writing (in order):
An optional prefix, which consists of the digit ‘0’, followed by the letter ‘e’, ‘f’ or ‘d’
in upper or lower case. Because floating point constants are used only with
.float and .double directives, the precision of the binary representation is
independent of the prefix.
An optional sign: either ‘+’ or ‘-’.
An optional integer part: zero or more decimal digits.
An optional fractional part: ‘.’ followed by zero or more decimal digits.
An optional exponent, consisting of:
- An ‘E’ or ‘e’.
- Optional sign: either ‘+’ or ‘-’.
- One or more decimal digits.
At least one of the integer part or fractional part must be present. The floating-point
number has the usual base-10 value.
Floating-point numbers are computed independently of any floating-point hardware in
the computer running the assembler.
MPLAB XC32 Assembly Language
2013 Microchip Technology Inc. DS50002186A-page 49
3.4.2 Character Constants
There are two kinds of character constants. A character stands for one character in one
byte and its value may be used in numeric expressions. A string can contain potentially
many bytes and their values may not be used in arithmetic expressions.
3.4.2.1 CHARACTERS
A single character may be written as a single quote immediately followed by that char-
acter, or as a single quote immediately followed by that character and another single
quote. The assembler accepts the following escape characters to represent special
control characters:
TABLE 3-1: SPECIAL CHARACTERS AND USAGES
The value of a character constant in a numeric expression is the machine’s byte-wide
code for that character. The assembler assumes your character code is ASCII.
3.4.2.2 STRINGS
A string is written between double quotes. It may contain double quotes or null
characters. The way to get special characters into a string is to escape the characters,
preceding them with a backslash ‘\’ character. The same escape sequences that apply
to strings also apply to characters.
3.4.2.3 GENERAL SYNTAX RULES
Table 3-2 summarizes the general syntax rules that apply to the assembler:
Escape Character Description Hex
Value
\a Bell (alert) character 07
\b Backspace character 08
\f Form-feed character 0C
\n New-line character 0A
\r Carriage return character 0D
\t Horizontal tab character 09
\v Vertical tab character 0B
\\ Backslash 5C
\? Question mark character 3F
\" Double quote character 22
\digit digit digit Octal character code. The numeric code is 3 octal digits.
\x hex-digits Hex character code. All trailing hex digits are combined.
Either upper or lower case x works.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 50 2013 Microchip Technology Inc.
TABLE 3-2: SYNTAX RULES
Character Character Description Syntax Usage
.period begins a directive
#number/hash begin single-line comment
/* slash, asterisk begin multiple-line comment
*/ asterisk, slash end multiple-line comment
:colon end a label definition
none required begin a literal value
’c’ character in single quotes specifies single character value
"string" character string in double quotes specifies a character string
MPLAB XC32 Assembly Language
2013 Microchip Technology Inc. DS50002186A-page 51
3.5 SYMBOLS
A symbol is one or more characters chosen from the set composed of all letters, digits,
the underline character (_), and the period (.). Symbols may not begin with a digit. The
case of letters is significant (e.g., foo is a different symbol than Foo). There is no length
limit and all characters are significant.
Each symbol has exactly one name. Each name in an assembly language program
refers to exactly one symbol. You may use that symbol name any number of times in a
program.
Local Symbols
Giving Symbols Other Values
The Special DOT Symbol
Predefined Symbols
3.5.1 Local Symbols
Local symbols are used when temporary scope for a label is needed. There are ten
local symbol names, which can be reused throughout the program. They may be
referred to using the names ‘0’, ‘1’, ..., ‘9’. To define a local symbol, write a label of the
form ‘N’, ‘N’, ..., ‘N’ (where N represents any digit 0-9). To refer to the most recent pre-
vious definition of that symbol, write ‘Nb’, using the same digit as when you defined the
label. To refer to the next definition of a local label, write ‘Nf’. The ‘b’ stands for
“backwards” and the ‘f’ stands for “forwards”.
There is no restriction on how you can use these labels, and you can reuse them too.
You can repeatedly define the same local label (using the same number 'N'), although
you can refer to only the most recently defined local label of that number (for a back-
wards reference) or the next definition of a specific local label for a forward reference.
Also note that the first 10 local labels (‘0:’. . . ‘9:’) are implemented in a slightly more
efficient manner than the others.
Here is an example:
EXAMPLE 3-5: SYMBOL USAGE
1: b 1f
2: b 1b
1: b 2f
2: b 1b
Which is the equivalent of:
label_1: b label_3
label_2: b label_1
label_3: b label_4
label_4: b label_3
Local symbol names are only a notational device. They are immediately transformed
into more conventional symbol names before the assembler uses them. These conven-
tional symbol names are stored in the symbol table and appear in error messages and
optionally emitted to the object file.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 52 2013 Microchip Technology Inc.
3.6 GIVING SYMBOLS OTHER VALUES
A symbol can be given an arbitrary value by writing a symbol, followed by an equals
sign '=', followed by an expression.
Example:
VAR = 4
3.7 THE SPECIAL DOT SYMBOL
The special symbol ‘.’ refers to the current address being processed by the assembler.
Thus, the expression ‘melvin: .long .’ defines melvin to contain its own address.
Assigning a value to . is treated the same as an .org directive. Thus, the expression
.=.+4’ is the same as saying ‘.space 4’.
When used in an executable section, ‘.’ refers to a Program Counter address. On a
PIC32 MCU, the Program Counter increments by 4 for each 32-bit instruction word.
User code should take care to properly align instructions after modifying the dot
symbol.
3.7.1 Giving Symbols Other Values
A symbol can be given an arbitrary value by writing a symbol, followed by an equals
sign ‘=, followed by an expression.
Example:
VAR = 4
3.7.2 The Special DOT Symbol
The special symbol ‘.’ refers to the current address being processed by the assembler.
Thus, the expression ‘melvin: .long .’ defines melvin to contain its own address.
Assigning a value to . is treated the same as an .org directive. Thus, the expression
.=.+4’ is the same as saying ‘.space 4’.
When used in an executable section, ‘.’ refers to a Program Counter address. On a
PIC32 MCU, the Program Counter increments by 4 for each 32-bit instruction word.
User code should take care to properly align instructions after modifying the dot
symbol.
3.7.3 Predefined Symbols
The assembler predefines several symbols which can be tested by conditional
directives in source code.
TABLE 3-3: PREDEFINED SYMBOLS
Symbol Definition
P32MX PIC32MX target device family
P32MZ PIC32MZ target device family
HAS_MIPS32R2 Device supports the MIPS32r2 Instruction Set
HAS_MIPS16 Device supports the MIPS16e Instruction Set
HAS_MICROMIPS Device supports the microMIPS Instruction Set
HAS_DSPR2 Device supports the DSPr2 engine
HAS_MCU Device supports the MIPS MCU extensions
HAS_L1CACHE Device has an L1 data and program cache
HAS_VECTOROFFSETS Device uses configurable offsets for the vector table
MPLAB XC32 Assembly Language
2013 Microchip Technology Inc. DS50002186A-page 53
3.8 EXPRESSIONS
An expression specifies an address or numeric value. White space may precede and/or
follow an expression. The result of an expression must be an absolute number or an
offset into a particular section. When an expression is not absolute and does not pro-
vide enough information for the assembler to know its section, the assembler
terminates and generates an error message.
3.8.1 Empty Expressions
An empty expression has no value: it is just white space or null. Wherever an absolute
expression is required, you may omit the expression, and the assembler assumes a
value of (absolute) 0.
3.8.2 Integer Expressions
An integer expression is one or more arguments delimited by operators. Arguments are
symbols, numbers or subexpressions. Subexpressions are a left parenthesis ‘(’ fol-
lowed by an integer expression, followed by a right parenthesis ‘)’; or a prefix operator
followed by an argument.
Integer expressions involving symbols in program memory are evaluated in Program
Counter (PC) units. In MIPS32 mode, the Program Counter increments by 4 for each
instruction word. For example, to branch to the next instruction after label L, specify L+4
as the destination.
Example:
b L+4
3.9 OPERATORS
Operators are arithmetic functions, like + or %. Prefix operators are followed by an
argument. Infix operators appear between their arguments. Operators may be
preceded and/or followed by white space.
Prefix operators have higher precedence than infix operators. Infix operators have an
order of precedence dependent on their type.
3.9.1 Prefix Operators
The assembler has the following prefix operators. Each takes one argument, which
must be absolute.
TABLE 3-4: PREFIX OPERATORS
Operator Description Example
-Negation. Two’s complement negation. -1
~Bit-wise not. One’s complement. ~flags
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 54 2013 Microchip Technology Inc.
3.9.2 Infix Operators
Infix operators take two arguments, one on either side. Operators have a precedence,
by type, as shown in the table below; but, operations with equal precedence are per-
formed left to right. Apart from + or –, both operators must be absolute, and the result
is absolute.
TABLE 3-5: INFIX OPERATORS
Operator Description Example
Arithmetic
*Multiplication 5 * 4 (=20)
/Division. Truncation is the same as the C operator ‘/’. 23 / 4 (=5)
%Remainder 30 % 4 (=2)
<< Shift Left. Same as the C operator ‘<<’ 2 << 1 (=4)
>> Shift Right. Same as the C operator ‘>>’ 2 >> 1 (=1)
Bit-Wise
&Bit-wise And 4 & 6 (=4)
^Bit-wise Exclusive Or 4 ^ 6 (=2)
!Bit-wise Or Not 0x1010 ! 0x5050
(=0xBFBF)
|Bit-wise Inclusive Or 2 | 4 (=6)
Simple Arithmetic
+Addition. If either argument is absolute, the result has the
section of the other argument. You may not add together
arguments from different sections.
4 + 10 (=14)
-Subtraction. If the right argument is absolute, the result
has the section of the left argument. If both arguments
are in the same section, the result is absolute. You may
not subtract arguments from different sections.
14 - 4 (=10)
Relational
== Equal to .if (x == y)
!= Not equal to (also <>).if (x != y)
<Less than .if (x < 5)
<= Less than or equal to .if (y <= 0)
>Greater than .if (x > a)
>= Greater than or equal to .if (x >= b)
Logical
&& Logical AND .if ((x > 1) &&
(x < 10))
|| Logical OR .if ((y != x)
|| (y < 100))
MPLAB XC32 Assembly Language
2013 Microchip Technology Inc. DS50002186A-page 55
3.10 SPECIAL OPERATORS
The assembler provides a set of special operators for each of the following actions:
Obtaining the Size of a Specific Section
Obtaining the Starting Address of a Specific Section
Obtaining the End Address of a Specific Section
3.10.1 Obtaining the Size of a Specific Section
The .sizeof.(section_name) operator can be used to obtain the size in bytes of
a specific section after the link process has occurred. For example, to find the final size
of the .data section, use:
.word .sizeof.(.data)
3.10.2 Obtaining the Starting Address of a Specific Section
The .startof.(section_name) operator can be used to obtain the starting
address of a specific section after the link process has occurred. For example, to obtain
the starting address of the .data section, use:
.word .sizeof.(.data)
3.10.3 Obtaining the Ending Address of a Specific Section
The .endof.(section_name) operator can be used to obtain the ending address of a
specific section after the link process has occurred. For example, to obtain the starting
address of the .data section, use:
.word .sizeof.(.data)
TABLE 3-6: SPECIAL OPERATORS
Operators Description
.sizeof.(name)Get size of section name in address units
.startof.(name)Get starting address of section name
.endof.(name) Get ending address of section name
DD
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 56 2013 Microchip Technology Inc.
NOTES:
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 57
Chapter 4. Assembler Directives
4.1 INTRODUCTION
Directives are assembler commands that appear in the source code but are not usually
translated directly into opcodes. They are used to control the assembler: its input,
output, and data allocation.
While there are many significant similarities with directives supported by the 16-bit
MPLAB Assembler for PIC24 MCUs and dsPIC DSCs (xc16-as), there are many
differences in the directive set supported by the 32-bit MPLAB XC32 Assembler
(xc32-as).
Topics covered in this chapter are:
Directives that Define Sections
Directives that Initialize Constants
Directives that Declare Symbols
Directives that Define Symbols
Directives that Modify Section Alignment
Directives that Format the Output Listing
Directives that Control Conditional Assembly
Directives for Substitution/Expansion
Directives that Include Other Files
Directives that Control Diagnostic Output
Directives for Debug Information
Directives that Control Code Generation
Note: Assembler directives are not target instructions (ADD, XOR, JAL, etc). For
instruction set information, consult your target-device data sheet
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 58 2013 Microchip Technology Inc.
4.2 DIRECTIVES THAT DEFINE SECTIONS
Sections are locatable blocks of code or data that will occupy contiguous locations in
the 32-bit device memory. Three sections are pre-defined: .text for executable code,
.data for initialized data and .bss for uninitialized data. Other sections may be
defined; the linker defines several that are useful for locating data in specific areas of
32-bit memory.
Section directives are:
.bss
.data
.pushsection name
.popsection
.section name [, “flags”] (deprecated)
.section name [, attr1[,…,attrn]]
.text
.bss
Definition
Assemble the following statements onto the end of the .bss (uninitialized data)
section.
The bss section is used for local common variable storage. You may allocate address
space in the bss section, but you may not dictate data to load into it before your pro-
gram executes. When your program starts running, all the contents of the bss section
are zeroed bytes.
Use the .bss directive to switch into the bss section and then define symbols as usual.
You may assemble only zero values into the section. Typically the section will contain
only symbol definitions and .skip directives
Example
# The following symbols (B1 and B2) will be placed in
# the uninitialized data section.
.bss
B1: .space 4 # 4 bytes reserved for B1
B2: .space 1 # 1 byte reserved for B2
.data
Definition
Assemble the following statements onto the end of the .data (initialized data) section.
Example
# The following symbols (D1 and D2) will be placed in
# the initialized data section.
.data
D1: .long 0x12345678 # 4 bytes
D2: .byte 0xFF # 1 byte
The linker collects initial values for section .data (and other sections defined with the
data attribute) and creates a data initialization template. This template can be pro-
cessed during application start-up to transfer initial values into memory. For C applica-
tions, a library function is called for this purpose automatically. Assembly projects can
utilize this library by linking with the libpic32 library. For more information, see the
discussion of Section 9.5.3 “Run-Time Library Support” in Initialized Data.
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 59
.pushsection name
This directive pushes the current section onto the top of the section stack and then
replaces the current section with name. Every .pushsection should have a matching
.popsection.
.popsection
Replace the current section description with the top section on the section stack. This
section is popped off the stack.
.section name [, “flags”] (deprecated)
.section name [, attr1[,...,attrn]]
Assemble the following code into a section named name. If the character * is specified
for name, the assembler will generate a unique name for the section based on the input
file name in the format filename.s.scnn, where n represents the number of auto-
generated section names.
Sections named * can be used to conserve memory because the assembler will not
add alignment padding to these sections. Sections that are not named * may be com-
bined across several files, so the assembler must add padding in order to guarantee
the requested alignment.
If the optional argument is not present, the section attributes depend on the section
name. A table of reserved section names with implied attributes is given in Reserved
Section Names with Implied Attributes. If the section name matches a reserved name,
the implied attributes will be assigned to that section. If the section name is not recog-
nized as a reserved name, the default attribute will be data (initialized storage in data
memory).
Implied attributes for reserved section names other than [.text, .data, .bss] are
deprecated.
A warning will be issued if implied attributes for these reserved sections are used.
If the first optional argument is quoted, it is taken as one or more flags that describe the
section attributes. Quoted section flags are deprecated. (See Appendix
A. “Deprecated Features”). A warning will be issued if quoted section flags are used.
If the first optional argument is not quoted, it is taken as the first element of an attribute
list. Attributes may be specified in any order, and are case-insensitive. Two categories
of section attributes exist: attributes that represent section types, and attributes that
modify section types.
4.2.1 Attributes That Represent Section Types
Attributes that represent section types are mutually exclusive. At most, one of the attri-
butes listed below may be specified for a given section.
TABLE 4-1: ATTRIBUTES THAT REPRESENT SECTION TYPES
Attribute Description
code Executable code in program memory
data Initialized storage in data memory
bss Uninitialized storage in data memory
persist Persistent storage in data memory
ramfunc Function in data memory
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 60 2013 Microchip Technology Inc.
4.2.2 Attributes that Modify Section Types
Depending on the attribute, all or some section types may be modified by it, as below
Table Table 4-2 in word file
4.2.3 Combining Attributes that Modify Section Types
The following section names are available for user applications:
TABLE 4-2: ATTRIBUTES THAT MODIFY SECTION TYPES
Attribute Description
Attribute applies to:
code data bss persist ramfunc
address(a) Locate at absolute address a x x x x
near Locate in the first 64k of memory x x x
reverse Align the ending address +1 x x x
align(n) Align the starting address x x x x x
noload Allocate, do not load x x x x x
keep Keep section against garbage
collection
xxx x x
TABLE 4-3: COMBINING ATTRIBUTES THAT MODIFY SECTION TYPES
address near reverse align noload keep
address xx xx
near xxxxx
reverse xxx
align xx xx
noload xxx x x
keep xxx xx
TABLE 4-4: RESERVED SECTION NAMES
Section
Name Generated by Mapped in the
linker script to
Implied
Attributes
.text Compiler- or assembler generated instructions code
.text.* Functions when compiled with
-ffunction-sections are output to uniquely named sections of
this form
code
.startup C start-up code/ left in the linker script for backwards compatibility kseg0_boot_mem code
.app_excpt General-Exception handler kseg0_boot_mem code
.reset Reset handler kseg0_boot_mem code
.bev_excpt BEV-Exception handler kseg0_boot_mem code
.vector_n Interrupt Vector n kseg0_boot_mem code
.rodata Strings and C data declared const code
.rodata.* Constant data when compiled with -fdata-sections are output
to uniquely named sections of this form
code
.data Variables >n bytes (compiled -Gn) with an initial value. data
.data.* Large initialized variables compiled with -fdata-sections data
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 61
Section Directive Examples
.section foo ;foo is initialized data memory.
.section bar,bss,align(256) ;bar is uninitialized data memory, aligned.
.section *,data,near ;section is near initialized data memory.
.section buf1,bss,address(0xa0000800);buf1 is uninitialized data memory at 0xa0000800.
.section *, code ;section is in program memory
.text
Definition
Assemble the following statements onto the end of the .text (executable code)
section.
Example
.text
.ent _main_entry
_main_entry:
jal main
nop
jal exit
nop
1:
b 1b
nop
.end _main_entry
.ramfunc RAM-functions data
.bss Uninitialized data bss
.lit4 /
.lit8
Constants (usually floating point) which the assembler decides to
store in memory rather than in the instruction stream. Used for
gp-relative addressing.
data
.sdata Variables <=n bytes (compiled -Gn) with an initial value. Used for
gp-relative addressing.
data
.sdata.* Small variables compiled with -fdata-sections. Used for
gp-relative addressing
data
.sbss Uninitialized variables <=n bytes (compiled -Gn). Used for
gp-relative addressing.
data
.sbss.* Small uninitialized variables compiled with -fdata-sections.
Used for gp-relative addressing.
data
.bss Uninitialized larger variables data
.bss.* Uninitialized variables compiled with -fdata-sections. data
.heap Heap used for dynamic memory data
.stack Minimum space reserved for stack data
.debug* DWARF debug information info
.line DWARF debug information info
.comment #ident/.ident strings info
.reginfo Information section info
TABLE 4-4: RESERVED SECTION NAMES (CONTINUED)
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 62 2013 Microchip Technology Inc.
4.3 DIRECTIVES THAT INITIALIZE CONSTANTS
Constant initialization directives are:
.ascii “string1” [, ..., “stringn”]
.asciz “string1” [, ..., “stringn”]
.byte expr1[, ..., exprn]
.double value1[, ..., valuen]
.float value1[, ..., valuen]
.single value1[, ..., valuen]
.hword expr1[, ..., exprn]
.int expr1[, ..., exprn]
.long expr1[, ..., exprn]
.short expr1[, ..., exprn]
.string “str”
.word expr1[, ..., exprn]
.ascii “string1” [, ..., “stringn”]
.ascii expects zero or more string literals separated by commas. It assembles each
string (with no automatic trailing zero byte) into consecutive addresses.
.asciz “string1” [, ..., “stringn”]
.asciz is just like .ascii, but each string is followed by a zero byte. The "z" in
.asciz stands for "zero". This directive is a synonym for .string.
.byte expr1[, ..., exprn]
.byte expects zero or more expressions, separated by commas. Each expression is
assembled into the next byte in the current section.
.double value1[, ..., valuen]
Assembles one or more double-precision (64-bit) floating-point constants into
consecutive addresses in little-endian format. Floating point numbers are in IEEE
format (see Section 3.4.1.2 “Floating-Point Numbers).
The following statements are equivalent:
.double 12345.67
.double 1.234567e4
.double 1.234567e04
.double 1.234567e+04
.double 1.234567E4
.double 1.234567E04
.double 1.234567E+04
Alternatively, you can specify the hexadecimal encoding of a floating-point constant.
The following statements are equivalent and encode the value 12345.67 as a 64-bit
double-precision number:
.double 0e:40C81CD5C28F5C29
.double 0f:40C81CD5C28F5C29
.double 0d:40C81CD5C28F5C29
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 63
.float value1[, ..., valuen]
Assembles one or more single-precision (32-bit) floating-point constants into
consecutive addresses in little-endian format. It has the same effect as .single.
Floating point numbers are in IEEE format (see Section 3.4.1.2 “Floating-Point
Numbers”).
The following statements are equivalent:
.float 12345.67
.float 1.234567e4
.float 1.234567e04
.float 1.234567e+04
.float 1.234567E4
.float 1.234567E04
.float 1.234567E+04
Alternatively, you can specify the hexadecimal encoding of a floating-point constant.
The following statements are equivalent and encode the value 12345.67 as a 32-bit
double-precision number:
.float 0e:4640E6AE
.float 0f:4640E6AE
.float 0d:4640E6AE
.single value1[, ..., valuen]
Assembles one or more single-precision (32-bit) floating-point constants into
consecutive addresses in little-endian format. This directive is a synonym for .float.
Floating point numbers are in IEEE format (see Section 3.4.1.2 “Floating-Point
Numbers”).
.hword expr1[, ..., exprn]
Assembles one or more 2-byte numbers into consecutive addresses in little-endian
format. This directive is a synonym for .short.
.int expr1[, ..., exprn]
Assembles one or more 4-byte numbers into consecutive addresses in little-endian
format. This directive is a synonym for .long.
.long expr1[, ..., exprn]
Assembles one or more 4-byte numbers into consecutive addresses in little-endian
format. This directive is a synonym for .int.
.short expr1[, ..., exprn]
Assembles one or more 2-byte numbers into consecutive addresses in little-endian
format. This directive is a synonym for .hword.
.string “str
This directive is a synonym for .asciz.
.word expr1[, ..., exprn]
Assembles one or more 4-byte numbers into consecutive addresses in little-endian
format.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 64 2013 Microchip Technology Inc.
4.4 DIRECTIVES THAT DECLARE SYMBOLS
Declare symbol directives are:
.comm symbol, length [, algn]
.extern symbol
.global symbol .globl symbol
.lcomm symbol, length
.weak symbol
.comm symbol, length [, algn]
.comm declares a common symbol named symbol. When linking, a common symbol
in one object file may be merged with a defined or common symbol of the same name
in another object file. If the linker does not see a definition for the symbol - just one or
more common symbols - then it will allocate length bytes of uninitialized memory.
length must be an absolute expression. If the linker sees multiple common symbols
with the same name, and they do not all have the same size, it will allocate space using
the largest size.
The .comm directive takes an optional third argument. If algn is specified, it is the
desired alignment of the symbol, specified as a byte boundary (for example, an align-
ment of 16 means that the least significant 4 bits of the address should be zero). The
alignment must be an absolute expression, and it must be a power of two. If linker allo-
cates uninitialized memory for the common symbol, it will use the alignment when plac-
ing the symbol. If no alignment is specified, the assembler will set the alignment to the
largest power of two less than or equal to the size of the symbol, up to a maximum of 1.
.extern symbol
The .extern directive declares a symbol name that may be used in the current mod-
ule, but it is defined as global in a different module. However, all symbols are extern
by default so this directive is optional.
.global symbol
.globl symbol
The .global directive declares a symbol that is defined in the current module and is
available to other modules. .global makes the symbol visible to the linker. If you
define symbol in your partial program, its value is made available to other partial pro-
grams that are linked with it. Otherwise, symbol takes its attributes from a symbol of the
same name from another file linked into the same program.
Both spellings (.globl and .global) are accepted, for compatibility with other
assemblers.
.lcomm symbol, length
Reserve length bytes for a local common denoted by symbol. The section and value
of symbol are those of the new local common. The addresses are allocated in the .bss
section, so that at run-time, the bytes start off zeroed. symbol is not declared global
so it is normally not visible to the linker.
.weak symbol
Marks the symbol named symbol as weak. When a weak-defined symbol is linked with
a normal-defined symbol, the normal-defined symbol is used with no error. When a
weak-defined symbol is linked and the symbol is not defined, the value of the weak
symbol becomes zero with no error.
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 65
4.5 DIRECTIVES THAT DEFINE SYMBOLS
Define symbol directives are:
.equ symbol, expression
.equiv symbol, expression
.equ symbol, expression
This directive sets the value of symbol to expression. You may set a symbol any
number of times in assembly. If you set a global symbol, the value stored in the object
file is the last value equated to it.
.equiv symbol, expression
Like .equ, except that the assembler will signal an error if symbol is already defined.
Note that a symbol which has been referenced but not actually defined is considered
to be undefined.
Except for the contents of the error message, this directive is roughly equivalent to:
.ifdef SYM
.err
.endif
.equ SYM,VAL
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 66 2013 Microchip Technology Inc.
4.6 DIRECTIVES THAT MODIFY SECTION ALIGNMENT
Directives that explicitly modify section alignment are listed below.
.align [algn[, fill]]
.fill repeat[, size[, value]]
.org new-lc[, fill]
.skip size[, fill]
.space size[, fill]
.struct expression
.align [algn[, fill]]
The .align directive pads the location counter (in the current subsection) to a partic-
ular storage boundary. The first expression (which must be absolute) is the alignment
required specified as the number of low-order zero bits the location counter must have
after advancement.
The assembler accepts algn values from 0 up to 15. A .align 0 turns off the auto-
matic alignment used by the data creating pseudo-ops. You must make sure that data
is properly aligned. Reinstate auto alignment with a .align pseudo instruction.
The second expression (also absolute) gives the fill value to be stored in the pad-
ding bytes. It (and the comma) may be omitted. If it is omitted, the padding bytes are
zero by default. You may wish to use 0xFF for FLASH regions of memory.
.fill repeat[, size[, value]]
Reserve repeat copies of size bytes. repeat may be zero or more. size may be zero
or more, but if it is more than 8, then it is deemed to have the value 8. The content of
each repeat bytes is taken from an 8-byte number. The highest order 4 bytes are zero.
The lowest order 4 bytes are value rendered in the little-endian byte-order. Each size
bytes in a repetition is taken from the lowest order size bytes of this number.
size is optional. If the first comma and following tokens are absent, size is assumed
to be 1.
value is optional. If the second comma and value are absent, value is assumed
zero.
Example:
.text
.fill 0x3, 1, 0xFF
.align 2
mylabel: b .
Note: User code must take care to properly align an instruction following a direc-
tive that modifies the section alignment or location counter.
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 67
.org new-lc[, fill]
The .org directive advances the location counter of the current section to new-lc.
new-lc is either an absolute expression or an expression with the same section as the
current subsection. That is, you can't use .org to cross sections: if new-lc has the
wrong section, the .org directive is ignored. If the section of new-lc is absolute,
xc32-as issues a warning, then pretends the section of new-lc is the same as the
current subsection.
.org may only increase the location counter, or leave it unchanged; you cannot use
.org to move the location counter backwards.
Because the assembler tries to assemble programs in one pass, new-lc may not be
undefined.
Beware that the origin is relative to the start of the section, not to the start of the
subsection.
When the location counter (of the current subsection) is advanced, the intervening
bytes are filled with fill, which should be an absolute expression. If the comma and
fill are omitted, fill defaults to zero.
.skip size[, fill]
.space size[, fill]
These directives emit size bytes, each of value fill. Both size and fill are
absolute expressions. If the comma and fill are omitted, fill is assumed to be
zero.
.struct expression
Switch to the absolute section, and set the section offset to expression, which must
be an absolute expression. You might use this as follows:
.struct 0
field1:
.struct field1 + 4
field2:
.struct field2 + 4
field3:
This would define the symbol field1 to have the value 0, the symbol field2 to have
the value 4, and the symbol field3 to have the value 8. Assembly would be left in the
absolute section, and you would need to use a .section directive of some sort to
change to some other section before further assembly.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 68 2013 Microchip Technology Inc.
4.7 DIRECTIVES THAT FORMAT THE OUTPUT LISTING
Output listing format directives are:
.eject
.list
.nolist
.psize lines[, columns]
.sbttl “subheading”
.title “heading”
.eject
Force a page break at this point when generating assembly listings.
.list
Controls (in conjunction with .nolist) whether assembly listings are generated. This
directive increments an internal counter (which is one initially). Assembly listings are
generated if this counter is greater than zero.
Only functional when listings are enabled with the -a command line option and forms
processing has not been disabled with the -an command line option.
.nolist
Controls (in conjunction with .list) whether assembly listings are generated. This
directive decrements an internal counter (which is one initially). Assembly listings are
generated if this counter is greater than zero.
Only functional when listings are enabled with the -a command line option and forms
processing has not been disabled with the -an command line option.
.psize lines[, columns]
Declares the number of lines, and optionally, the number of columns to use for each
page when generating listings.
If you do not use .psize, listings use a default line count of 60. You may omit the
comma and columns specification; the default width is 200 columns.
The assembler generates formfeeds whenever the specified number of lines is
exceeded (or whenever you explicitly request one, using .eject).
If you specify lines as 0, no formfeeds are generated save those explicitly specified with
.eject.
.sbttl “subheading
Use subheading as a subtitle (third line, immediately after the title line) when generat-
ing assembly listings. This directive affects subsequent pages, as well as the current
page, if it appears within ten lines of the top.
.title “heading
Use heading as the title (second line, immediately after the source file name and page
number) when generating assembly listings.
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 69
4.8 DIRECTIVES THAT CONTROL CONDITIONAL ASSEMBLY
Conditional assembly directives are:
.else
.elseif expr
.endif
.if expr
.else
Used in conjunction with the .if directive to provide an alternative path of assembly
code should the .if evaluate to false.
.elseif expr
Used in conjunction with the .if directive to provide an alternative path of assembly
code should the .if evaluate to false and a second condition exists.
.endif
Marks the end of a block of code that is only assembled conditionally.
.if expr
Marks the beginning of a section of code that is only considered part of the source
program being assembled if the argument expr is non-zero. The end of the conditional
section of code must be marked by an .endif; optionally, you may include code for
the alternative condition, flagged by .else.
The assembler also supports the following variants of .if.
.ifdecl symbol
Assembles the following section of code if the specified symbol has been defined. Note
that a symbol which has been referenced, but not yet defined, is considered to be
undefined.
.ifc string1,string2
This directive assembles the following section of code if the two strings are the same.
The strings may be optionally quoted with single quotes. If they are not quoted, the first
string stops at the first comma, and the second string stops at the end of the line.
Strings which contain whitespace should be quoted. The string comparison is case
sensitive.
.ifeq absolute-expression
This directive assembles the following section of code if the argument is zero.
.ifeqs string1,string2
This directive is another form of .ifc. The strings must be quoted using double
quotes.
.ifge absolute-expression
This directive assembles the following section of code if the argument is greater than
or equal to zero.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 70 2013 Microchip Technology Inc.
.ifgt absolute-expression
This directive assembles the following section of code if the argument is greater than
zero.
.ifle absolute-expression
This directive assembles the following section of code if the argument is less than or
equal to zero.
.iflt absolute-expression
This directive assembles the following section of code if the argument is less than zero.
.ifnc string1,string2
This directive is like .ifc, but the sense of the test is reversed: this assembles the
following section of code if the two strings are not the same.
.ifndef symbol
This directive assembles the following section of code if the specified symbol has not
been defined. Both spelling variants are equivalent. Note a symbol which has been
referenced but not yet defined is considered to be undefined.
.ifnotdef symbol
This directive is the same as .ifndef.
.ifne absolute-expression
This directive assembles the following section of code if the argument is not equal to
zero (in other words, this is equivalent to .if).
.ifnes string1,string2
This directive is like .ifeqs, but the sense of the test is reversed: this assembles the
following section of code if the two strings are not the same.
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 71
4.9 DIRECTIVES FOR SUBSTITUTION/EXPANSION
Substitution/expansion directives are:
.exitm
.irp symbol, value1 [, ..., valuen] ... .endr
.irpc symbol, value ... .endr
.macro
.exitm
Exit early from the current macro definition. See .macro directive.
.irp symbol, value1
[, ..., valuen]
...
.endr
Evaluate a sequence of statements assigning different values to symbol. The
sequence of statements starts at the .irp directive, and is terminated by a .endr
directive. For each value, symbol is set to value, and the sequence of statements is
assembled. If no value is listed, the sequence of statements is assembled once, with
symbol set to the null string. To refer to symbol within the sequence of statements,
use \symbol.
For example, assembling
.irp reg,0,1,2,3
lw $a\reg, 1032+\reg($sp)
.endr
is equivalent to assembling
lw $a0,1032+0($sp)
lw $a1,1032+1($sp)
lw $a2,1032+2($sp)
lw $a3,1032+3($sp)
.irpc symbol, value
...
.endr
Evaluate a sequence of statements assigning different values to symbol. The
sequence of statements starts at the .irpc directive, and is terminated by an .endr
directive. For each character in value, symbol is set to the character, and the
sequence of statements is assembled. If no value is listed, the sequence of statements
is assembled once, with symbol set to the null string. To refer to symbol within the
sequence of statements, use \symbol.
For example, assembling
.irpc reg,0123
lw $a\reg, 1032+\reg($sp)
.endr
is equivalent to assembling
lw $a0,1032+0($sp)
lw $a1,1032+1($sp)
lw $a2,1032+2($sp)
lw $a3,1032+3($sp)
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 72 2013 Microchip Technology Inc.
.macro
The directives .macro and .endm allow you to define macros that generate assembly
output. For example, this definition specifies a macro SUM that puts a sequence of
numbers into memory:
.macro SUM from=0, to=5
.long \from
.if \+o-\from
SUM "(\from+1)", \+o
.endif
.endm
With that definition, 'SUM 0,5' is equivalent to this assembly input:
.long 0
.long 1
.long 2
.long 3
.long 4
.long 5
.macro macname
.macro macname macargs
Begin the definition of a macro called macname. If your macro definition requires argu-
ments, specify their names after the macro name, separated by commas or spaces.
You can supply a default value for any macro argument by following the name with
=deflt. For example, these are all valid .macro statements:
.macro comm
Begin the definition of a macro called comm, which takes no arguments.
.macro plus1 p, p1
.macro plus1 p p1
Either statement begins the definition of a macro called plus1, which takes two
arguments; within the macro definition, write \p or \p1 to evaluate the arguments.
.macro reserve_str p1=0 p2
Begin the definition of a macro called reserve_str, with two arguments. The
first argument has a default value, but not the second. After the definition is com-
plete, you can call the macro either as 'reserve_str a,b' (with \p1 evaluating
to a and \p2 evaluating to b), or as 'reserve_str ,b' (with \p1 evaluating as
the default, in this case '0', and \p2 evaluating to b).
When you call a macro, you can specify the argument values either by position, or by
keyword. For example, 'SUM 9,17' is equivalent to 'sum to=9, from=17'.
.endm
Mark the end of a macro definition.
.exitm
Exit early from the current macro definition.
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 73
\@
The assembler maintains a counter of how many macros it has executed in this
pseudo-variable; you can copy that number to your output with \@, but only within a
macro definition. In the following example, a recursive macro is used to allocate an arbi-
trary number of labeled buffers
.macro make_buffers num,size
BUF\@: .space \size
.if (\num - 1)
make_buffers (\num - 1),\size
.endif
.endm
.bss
# create BUF0..BUF3, 16 bytes each
make_buffers 4,16
This example macro expands as shown in the following listing:
6 make_buffers (\num - 1),\size
7 .endif
8 .endm
9
10 .bss
11 # create BUF0..BUF3, 16 bytes each
12 make_buffers 4,16
12 > BUF0:.space 16
12 0000 > .space 16
12 > .if (4-1)
12 > make_buffers (4-1),16
12 >> BUF1:.space 16
12 0010 >> .space 16
12 >> .if ((4-1)-1)
12 >> make_buffers ((4-1)-1),16
12 >>> BUF2:.space 16
12 0020 >>> .space 16
12 >>> .if (((4-1)-1)-1)
12 >>> make_buffers (((4-1)-1)-1),16
12 >>>> BUF3:.space 16
12 0030 >>>> .space 16
12 >>>> .if ((((4-1)-1)-1)-1)
12 >>>> make_buffers ((((4-1)-1)-1)-1),16
12 >>>> .endif
12 >>> .endif
12 >> .endif
12 > .endif
.purgem "name"
Undefine the macro name, so that later uses of the string will not be expanded. See
.macro directive on the preceding page.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 74 2013 Microchip Technology Inc.
.rept count ... .endr
Repeat the sequence of lines between the .rept directive and the next .endr
directive count times.
For example, assembling
.rept 3
.long 0
.endr
is equivalent to assembling
.long 0
.long 0
.long 0
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 75
4.10 DIRECTIVES THAT INCLUDE OTHER FILES
Directives that include data from other files are:
.incbin "file"[,skip[,count]]
.include "file"
.incbin "file"[,skip[,count]]
The .incbin directive includes file verbatim at the current location. The file is
assumed to contain binary data. The search paths used can be specified with the -I
command-line option (see Chapter 2. “Assembler Command-Line Options”).
Quotation marks are required around file.
The skip argument skips a number of bytes from the start of the file. The count
argument indicates the maximum number of bytes to read. Note that the data is not
aligned in any way, so it is the user's responsibility to make sure that proper alignment
is provided both before and after the .incbin directive.
.include "file"
Provides a way to include supporting files at specified points in your source code. The
code is assembled as if it followed the point of the .include. When the end of the
included file is reached, assembly of the original file continues at the statement
following the .include.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 76 2013 Microchip Technology Inc.
4.11 DIRECTIVES THAT CONTROL DIAGNOSTIC OUTPUT
Miscellaneous directives are:
.abort
.err
.error "string"
.fail expression
.ident "comment"
.print "string"
.version "string"
.warning "string"
.abort
Prints out the message “.abort detected. Abandoning ship.” and exits the program.
.err
If the assembler sees an .err directive, it will print an error message, and unless the
-Z option was used, it will not generate an object file. This directive can be used to
signal an error in conditionally compiled code.
.error "string"
Similar to .err, except that the specified string is printed.
.fail expression
Generates an error or a warning. If the value of the expression is 500 or more,
xc32-as will print a warning message. If the value is less than 500, as will print an
error message. The message will include the value of expression. This can
occasionally be useful inside complex nested macros or conditional assembly.
.ident "comment"
Appends comment to the section named .comment. This section is created if it does
not exist. The linker will ignore this section when allocating memory, but will combine
all.comment sections together, in link order.
.print "string"
Prints string on the standard output during assembly.
.version "string"
This directive creates a .note section and places into it an ELF formatted note of type
NT_VERSION. The note's name is set to string. .version is supported when the
output file format is ELF; otherwise, it is ignored.
.warning "string"
Similar to the directive .error, but emits a warning.
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 77
4.12 DIRECTIVES FOR DEBUG INFORMATION
Debug information directives are:
.ent function
.end
.file fileno "filename"
.fmask mask, offset
.frame framereg, frameoffset, retreg
.loc fileno, lineno [columnno]
.mask mask, offset
.size name, expression
.sleb128 expr1 [, ..., exprn]
.type name, description
.uleb128 expr1[,...,exprn]
.ent function
This directive marks the function symbol as a function similarly to the generic .type
directive.
.end
End program.
.file fileno "filename"
When emitting dwarf2 line-number information .file assigns filenames to the
.debug_line file name table. The fileno operand should be a unique positive inte-
ger to use as the index of the entry in the table. The filename operand is a C string
literal.
The detail of filename indices is exposed to the user because the filename table is
shared with the .debug_info section of the dwarf2 debugging information, and thus
the user must know the exact indices that table entries will have.
.fmask mask, offset
Not used for current PIC32 MCUs. Maintain mask 0x00000000 and offset 0.
.frame framereg, frameoffset, retreg
This directive describes the shape of the stack frame. The virtual frame pointer in use
is framereg; normally this is either $fp or $sp. The frame pointer is frameoffset
bytes below the canonical frame address (CFA), which is the value of the stack pointer
on entry to the function. The return address is initially located in retreg until it is saved
as indicated in .mask.
.loc fileno, lineno [columnno]
The object file's debugging information contains a line-number matrix that correlates an
assembly instruction to a line and column of source code. The .loc directive will add
a matrix row corresponding to the assembly instruction immediately following the direc-
tive. The fileno, lineno, and columnno will be applied to the debug state machine
before the row is added.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 78 2013 Microchip Technology Inc.
.mask mask, offset
Indicate which of the integer registers are saved in the current function's stack frame.
mask is interpreted a bit mask in which bit n set indicates that register n is saved. The
registers are saved in a block located offset bytes from the canonical frame address
(CFA), which is the value of the stack pointer on entry to the function.
.size name, expression
This directive sets the size associated with a symbol name. The size in bytes is com-
puted from expression which can make use of label arithmetic. This directive is
typically used to set the size of function symbols.
.sleb128 expr1 [, ..., exprn]
sleb128 stands for “signed little endian base 128.” This is a compact, variable-length
representation of numbers used by the DWARF symbolic-debugging format.
.type name, description
This sets the type of symbol name to be either a function symbol or an object symbol.
There are five different syntaxes supported for the type description field, in order to
provide compatibility with various other assemblers. The syntaxes supported are:
.type <name>,#function
.type <name>,#object
.type <name>,@function
.type <name>,@object
.type <name>,%function
.type <name>,%object
.type <name>,"function"
.type <name>,"object"
.type <name> STT_FUNCTION
.type <name> STT_OBJECT
.uleb128 expr1[,...,exprn]
uleb128 stands for “unsigned little endian base 128.” This is a compact, variable-length
representation of numbers used by the DWARF symbolic-debugging format.
Assembler Directives
2013 Microchip Technology Inc. DS50002186A-page 79
4.13 DIRECTIVES THAT CONTROL CODE GENERATION
Directives controlling assembler code-generation behavior are:
.set noat
.set at
.set noautoextend
.set autoextend
.set nomacro
.set macro
.set mips16e
.set nomips16e
.set noreorder
.set reorder
.set noat
When synthesizing some address formats, the assembler may require a scratch regis-
ter. By default, the assembler will quietly use the at ($1) register, which is reserved as
an assembler temporary by convention. In some cases, the compiler should not use
that register. The .set noat directive prevents the assembler from quietly using that
register.
.set at
Allow the assembler to quietly use the at ($1) register.
.set noautoextend
By default, MIPS16 instructions are automatically extended to 32 bits when necessary.
The directive .set noautoextend will turn this off. When .set noautoextend is
in effect, any 32-bit instruction must be explicitly extended with the .e modifier (e.g.,
li.e $4,1000). The directive .set autoextend may be used to once again
automatically extend instructions when necessary.
.set autoextend
Enable auto-extension of MIPS16 instructions to 32 bits.
.set nomacro
The assembler supports synthesized instructions, an instruction mnemonic that syn-
thesizes into multiple machine instructions. For instance, the sleu instruction assem-
bles into an sltu instruction and an xori instruction. The .set nomacro directive
causes the assembler to emit a warning message when an instruction expands into
more than one machine instruction.
.set macro
Suppress warnings for synthesized instructions.
.set mips16e
Assemble with the MIPS16e ISA extension.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 80 2013 Microchip Technology Inc.
.set nomips16e
Do not assemble with the MIPS16e ISA extension.
.set noreorder
By default, the assembler attempts to fill a branch or delay slot automatically by
reordering the instructions around it. This feature can be very useful.
Occasionally, you'll want to retain precise control over your instruction ordering. Use
the .set noreorder directive to tell the assembler to suppress this feature until it
encounters a .set reorder directive.
.set reorder
Allow the assembler to reorder instructions to fill a branch or delay slot.
.set micromips
Assemble with the microMIPS ISA mode.
.set nomicromips
Do not assemble with the microMIPS ISA mode.
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 81
Chapter 5. Assembler Errors/Warnings/Messages
5.1 INTRODUCTION
MPLAB Assembler for PIC32 MCUs (xc32-as) generates errors, warnings and mes-
sages. A descriptive list of the most common diagnostic messages from the assembler
is shown here.
Topics covered in this chapter are:
Fatal Errors
• Errors
• Warnings
• Messages
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 82 2013 Microchip Technology Inc.
5.2 FATAL ERRORS
The following errors indicate that an internal error has occurred in the assembler.
Please contact Microchip Technology (http://support.microchip.com) for support if the
assembler generates any of the fatal errors listed below. Be sure to provide full details
about the source code and command-line options causing the error.
Bad char = '%c'
Bad defsym; format is --defsym name=value
Bad return from bfd_install_relocation: %x
Broken assembler. No assembly attempted.
Can't allocate elf private section data: %s
Can't continue
Can't create group: %s
Can't extend frag %u chars
Can't open a bfd on stdout %s
Can't start writing .mdebug section: %s
Cannot write to output file
Could not write .mdebug section: %s
Dwarf2 is not supported for this object file format
Emulations not handled in this configuration
Error constructing %s pseudo-op table: %s
Expr.c(operand): bad atof_generic return val %d
Failed sanity check
Failed to read instruction table %s\n
Failed to set up debugging information: %s
Index into stored_fixups[] out of bounds
Inserting into symbol table failed: %s
Internal: bad mips opcode (bits 0x%lx undefined): %s %s.
Internal: bad mips opcode (mask error): %s %s.
Internal: bad mips opcode (unknown extension operand type `+%c'): %s %s.
Internal: bad mips opcode (unknown operand type `%c'): %s %s.
Internal error, line %d, %s
Internal error: unknown dwarf2 format
Internal: can't hash `%s': %s
Invalid abi -mabi=%s
Invalid listing option `%c'
Macros nested too deeply
Missing emulation mode name
Multiple emulation names specified
No compiled in support for 64 bit object file
No object file generated
Rva not supported
Rva without symbol
Too many fixups
Unrecognized emulation name `%s'
Assembler Errors/Warnings/Messages
2013 Microchip Technology Inc. DS50002186A-page 83
5.3 ERRORS
The errors listed below usually indicate an error in the assembly source code or
command-line options passed to the assembler.
Symbol
.abort detected. Abandoning ship.
User error invoked with the .abort directive.
.else without matching .if
A .else directive was seen without a preceding .if directive.
.elseif after .else
A .elseif directive specified after a .else directive. Modify your code so that the
.elseif directive comes before the .else directive.
.elseif without matching .if
A .elseif directive was seen without a preceding .if directive.
.endfunc missing for previous .func
A .endfunc directive is missing for a previous .func directive.
.endif without .if
A .endif directive was seen without a preceding .if directive.
.err encountered.
User error invoked with the .err directive.
.Ifeqs syntax error
Two comma-separated, double-quoted strings were not passed as arguments to the
.ifeqs directive.
.Set pop with no .set push
Attempting to pop options off of an empty option stack. Use .set push before .set
pop.
.Size expression too complicated to fix up
The .size expression can be constant or use label subtraction.
A
A bignum with underscores may not have more than 8 hex digits in any word.
A bignum constant must not have more than 8 hex digits in a single word.
A bignum with underscores must have exactly 4 words.
A bignum constant using the underscore notation must have exactly four 8-hexdigit
parts.
Absolute sections are not supported.
This assembler does not support the absolute section command.
Alignment not a power of 2.
The alignment value must be a power of 2. Modify the alignment to be a power of 2.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 84 2013 Microchip Technology Inc.
Alignment too large: 15. Assumed.
An alignment greater than 15 was requested. The assembler automatically continues
with a alignment value of 15.
Arg/static registers overlap.
A MIPS32 mode save/restore uses overlapping registers for args and statics.
Argument must be a string.
The argument to a .error or .warning directive must be a double-quoted string.
Attempt to allocate data in common section.
This directive attempts to allocate data to a section that isn't allocatable. Allocate the
data to another section instead.
Attempt to get value of unresolved symbol name
The assembler could not get the value of an unresolved symbol.
Attempt to set value of section symbol.
Assignments to section symbols are not legal.
B
Backward ref to unknown label label:
The referenced label is either not seen or not defined here.
Bad .common segment name
Could not determine an appropriate alignment value for a .comm symbol. A previously
seen .comm symbol may be incorrect.
Bad escaped character in string.
The string uses a non-standard backslash-escaped character.
Bad expression.
The expression type cannot be determined or an operand is not of the correct type for
the expression type.
Bad floating literal: %s.
The token could not be converted to a floating-point value.
Bad floating-point constant: exponent overflow.
The token could not be converted to a floating-point value because of exponent
overflow.
Bad floating-point constant: unknown error code=%d.
The token could not be converted to a floating-point value.
Bad format for ifc or ifnc.
The arguments to the ifc or ifnc directive are incorrect. They must be 2
comma-separated, double-quoted strings.
Bad or irreducible absolute expression.
The absolute expression had an unexpected operator type.
Assembler Errors/Warnings/Messages
2013 Microchip Technology Inc. DS50002186A-page 85
Bad register expression.
The DWARF debugging directive has an invalid register expression.
Bignum invalid.
The bignum value specified in the expression is not valid.
C
Can't parse register list.
In MIPS32 mode, the register list is invalid.
Can't resolve value for symbol `%s'.
The assembler could not get a real value for the symbol.
Constant too large.
When sign extending a constant offset from a base register, the constant was too large.
Could not skip to num in file filename
The skip parameter to the .incbin directive was invalid for the given file.
D
Duplicate else.
Each .if directive can have only up to one corresponding .else directive.
E
End of file inside conditional.
The assembler identified a missing conditional-end directive. Terminate the conditional
before the end of the file.
End of macro inside conditional.
The assembler identified a missing macro-end directive. Terminate the macro before
the end of the file.
Expected address expression.
The expression was illegal, absent, or bignum but it should have been a constant
address.
Expected comma after %s.
The arguments for this directive must be separated by a comma.
Expected comma after name `%s' in .size directive.
The arguments for this directive must be separated by a comma.
Expected quoted string.
The argument should be a quoted string.
Expected simple number.
This argument must be a simple number.
Expected symbol name.
This argument must be a symbol name.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 86 2013 Microchip Technology Inc.
Expression out of range.
The expression is out of range for the directive or instruction (e.g. 32-bit value when a
32-bit value is expected)
Expression too complex.
The expression should be a symbol or constant.
F
File not found: %s.
The file specified to a directive (such as .incbin) could not be opened as specified.
File number %ld already allocated.
The file number passed to a .file directive is already in use.
File number less than one.
The file number passed to a .file directive must be > 1.
Floating point number invalid.
The floating-point number is invalid.
G
Global symbols not supported in common sections.
External symbols are not supported in MRI common sections.
I
Ignoring attempt to redefine symbol name
The symbol being redefined by the .weakext directive has already been defined.
Improper insert size
The width of the field specified to an INS instruction was not valid for the shift position.
Improper extract size
The width of the field specified to an EXT instruction was not valid for the shift position.
Instruction insn requires absolute expression.
This instruction requires a constant expression.
Invalid astatic register list
The aregs field of a MIPS32e extended SAVE/RESTORE instruction specified an
invalid astatic register list.
Invalid arg register list.
The aregs field of a MIPS32e extended SAVE/RESTORE instruction specified an
invalid arg register list.
Invalid coprocessor 0 register number.
An invalid coprocessor 0 register number was passed to this instruction.
Invalid coprocessor sub-selection value (%ld), not in range 0-7.
The coprocessor sub-selection value must be in the range 0-7.
Assembler Errors/Warnings/Messages
2013 Microchip Technology Inc. DS50002186A-page 87
Invalid frame size
The frame size is not valid and could not be encoded.
Invalid identifier for .ifdef.
The specified identifier is not a valid name. It must begin with a legal character.
Invalid register list.
In MIPS32 mode, the register list contained an invalid register.
Invalid segment %s.
Attempting to change the location counter in an invalid segment.
Invalid static register list.
The static register list should include only $s2-$s8
J
Jump to misaligned address (0x%lx).
The jump target address is not aligned.
Junk at end of line, first unrecognized character is char
There are extraneous characters after the expected input.
Junk at end of line, first unrecognized character valued 0xval
There are extraneous characters after the expected input.
L
Load/store address overflow (max 32 bits).
The load/store address is greater than 32 bits wide. Make sure that the label is correct.
Local label is not defined.
A referenced local label was never defined.
Lui expression not in range 0..65535.
The Load Upper Immediate expression should be within the 32-bit range.
N
New line in title.
The title heading string should be enclosed in double quotes.
No such section.
The section name specified in a .global directive does not exist. (e.g. .global foo
.myscn)
Non-constant expression in .elseif statement
The .elseif statement requires a constant expr expression. The argument of the
.elseif directive must be a constant value able to be resolved on the first pass of the
directive. Ensure that any .equ of a symbol used in this argument is located before the
directive. See Section 4.8 “Directives that Control Conditional Assembly” for
more details.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 88 2013 Microchip Technology Inc.
Non-constant expression in .if statement.
The .if statement requires a constant expr expression. The argument of the .if
directive must be a constant value able to be resolved on the first pass of the directive.
Ensure that any .equ of a symbol used in this argument is located before the directive.
See Section 4.8 “Directives that Control Conditional Assembly” for more details.
`Noreorder' must be set before `nomacro'.
Set noreorder before setting nomacro.
Number (0x%lx) larger than 32 bits.
Loading a value greater than 32 bits wide into a register.
Number larger than 64 bits.
Loading a value greater than 64 bits wide into HI/LO registers.
O
Offset too large.
The offset must be within the signed-extended 32-bit range.
Opcode not supported on this processor.
The instruction opcode is not supported on PIC32 MCUs.
Operand overflow.
The operand is not within the allowed range for this instruction.
Operation combines symbols in different segments.
The left-hand side of the expression and the right-hand side of the expression are
located in two different sections. The assembler does not know how to handle this
expression.
R
Register value used as expression.
An expression's operator is a register rather than a valid operator.
Relocation reloc isn't supported by the current ABI.
This relocation isn't supported by the PIC32 little-endian ELF output format.
S
Seek to end of .incbin file failed `%s'.
Could not find the end of the file specified by .incbin
Skip (%ld) + count (%ld) larger than file size (%ld).
The .incbin skip value + count value is greater than the size of the file.
Store insn found in delay slot of noreorder code.
Consider moving the store in front of the branch and using a nop in the delay instead.
Symbol `%s' can not be both weak and common.
Both the .weak directive and .comm directive were used on the same symbol within
the same source file.
Assembler Errors/Warnings/Messages
2013 Microchip Technology Inc. DS50002186A-page 89
Symbol name is already defined.
The symbol cannot be redefined.
Symbol definition loop encountered at `%s'.
The symbol could not be defined because a self-referential loop was encountered. A
symbol's definition cannot depend on its own value.
Syntax error in .startof. Or .sizeof.
The assembler found either .startof. or .sizeof., but did not find the beginning
parenthesis '(' or ending parenthesis ')'.
T
This string may not contain '\0'.
The string must be a valid C string and cannot contain '\0'.
Treating warnings as errors.
The assembler has been instruction to treat all warnings as errors with the
--fatal-warnings command-line option.
U
Unassigned file number num
The .loc directive specifies a file number that is not yet in use.
Unclosed '('.
An open '(' is unmatched with a closing ')'. Add the missing ')'.
Unexpected register in list.
In MIPS32 mode, an invalid register was used. Check the operands for this instruction.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 90 2013 Microchip Technology Inc.
5.4 WARNINGS
The assembler generates warnings when an assumption is made so that the
assembler could continue assembling a flawed program. Warnings should not be
ignored. Each warning should be specifically looked at and corrected to ensure that the
assembler understands what was intended. Warning messages can sometimes point
out bugs in your program.
Symbol
.end directive missing or unknown symbol
The .end function debugging-info directive is missing or the associated symbol is not
defined. Make sure that the .end directive is placed appropriately after the .ent
directive.
.end directive without a preceding .ent directive.
The .end function debugging-info directive does not have an associated .ent directive
to mark the symbol as a function. Make sure that the .end directive is positioned
appropriately after a .ent directive.
.end not in text section
The .end function debugging-info directive must be in a section with executable code.
.end symbol does not match .ent symbol.
The .end function debugging-info directive's function argument does not match the
preceding .ent directive's function argument. Make sure that the .end directive is
positioned appropriately after its corresponding .ent directive.
.endr encountered without preceding .rept, .irc, or .irp
The .endr directive ends a .rept, .irc, or .irp sequence; however this .endr
directive does not have a preceding .rept, .irc, or .irp directive. Make sure that
the .endr directive is positioned correctly in your code.
.ent or .aent not in text section.
The .ent function debugging-info directive must be in a section containing executable
code.
.fail expr encountered
If the value of the your .fail expression is 500 or more, the assembler will print a
warning message. The message will include the value of expression.
.fill size clamped to 8
The .fill size value may be zero or more, but if it is more than 8, then it is deemed
to have the value 8.
.frame outside of .ent
The .frame directive describes the stack frame and therefore must be used within a
function.
.incbin count zero, ignoring filename
The .incbin count should be greater than zero. reading zero bytes from a file has no
effect.
Assembler Errors/Warnings/Messages
2013 Microchip Technology Inc. DS50002186A-page 91
.mask/.fmask outside of .ent
The .mask/.fmask stack-frame information should be defined within a .ent function.
Make sure that the .mask/.fmask directive is positioned correctly within the source
code.
.popsection without corresponding .pushsection; ignored
The assembler cannot pop a section off of the section stack without pushing one onto
the stack first.
.previous without corresponding .section; ignored
There's no previous section swap with the current section. Make sure that the
.previous directive is positioned correctly within the source code.
.space repeat count is negative, ignored.
The .space size argument must be greater than 0.
.space repeat count is zero, ignored.
The .space size argument must be greater than 0.
A
Alignment negative: 0 assumed.
The .align alignment must be a non-negative power-of-two value. .align 0 turns off
the automatic alignment used by the data creating pseudo-ops.
Alignment too large: 15 assumed.
The .align alignment value is greater than 15. The valid range is [0,15].
D
Divide by zero.
DIV instruction with $zero register as RT.
Division by zero.
This expression attempts to divide by zero. Check the operands.
E
Extended instruction in delay slot.
A MIPS32e extended instruction may not be placed in a jump delay slot as it will cause
undefined behavior. Move the instruction out of the delay slot.
F
Floating point constant too large.
The hexadecimal encoding of a floating-point constant is too large. Make sure that your
floating-point value is encoded correctly in the 32-bit or 64-bit IEEE format.
I
Ignoring changed section attributes for name
If section attributes are specified the second time the assembler sees a particular sec-
tion, then they should be the same as the first time the assembler saw the section
attributes. The assembler assumes that the first set of section attributes was correct.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 92 2013 Microchip Technology Inc.
Ignoring changed section entity size for name
The section entity size should be the same the second time the assembler sees a par-
ticular section. The assembler assumes that the section entity size the first time it saw
the section was correct.
Ignoring changed section type for name
The section type should be the same the second time the assembler sees a particular
section. The assembler assumes that the section type the first time it saw the section
was correct.
Ignoring incorrect section type for name
When switching to a special predefined section by name, the section's type should
match the predefined type. The assembler uses the predefined type for the section.
Immediate for %s not in range 0..1023 (%lu).
The debugger Break code was not in the valid range. Normal user code should not use
this instruction reserved for debugger use.
Improper shift amount (%lu).
The shift value for a shift instruction (e.g. SLL, SRA, SRL) is out of range.
Instruction sne: Instruction %s: result is always false.
The result of the condition tested by the SNE instruction is always false. (e.g. The s
operand is the zero register and t is a nonzero constant expression.)
Instruction seq: result is always true.
The result of the condition tested by the SEQ instruction is always false. (e.g. The s
operand is the zero register and t is the constant 0.)
Invalid merge entity size.
The section merge entity size must be non-negative.
Invalid number.
The constant was in an unrecognized format. Check the constant's prefix and radix.
J
Jump address range overflow (0x%lx).
The target address of the jump instruction is outside the 228-byte “page”.
L
Left operand is a bignum; integer 0 assumed.
The left operand in the expression is a bignum rather than an integer. The assembler
performs expression evaluation on only integers so it assumes integer 0 for this
operand.
Left operand is a float; integer 0 assumed.
The left operand in the expression is a float rather than an integer. The assembler
performs expression evaluation on only integers so it assumes integer 0 for this
operand.
Assembler Errors/Warnings/Messages
2013 Microchip Technology Inc. DS50002186A-page 93
Line numbers must be positive; line number %d rejected.
This directive accepts only positive integers for the line number.
M
Missing close quote; (assumed).
The single-character quote is not properly closed.
Missing operand; zero assumed.
An operand (probably the right-size operand) is missing in the expression. The
assembler assumes integer 0 and continues.
O
Operand overflow.
The constant expression used as in the (basereg+offset) operand accepts only 32-bit
signed constants.
R
Repeat < 0; .fill ignored.
The repeat argument to the .fill directive must be non-negative.
Right operand is a bignum; integer 0 assumed.
The right operand in the expression is a bignum rather than an integer. The assembler
performs expression evaluation on only integers so it assumes integer 0 for this
operand.
Right operand is a float; integer 0 assumed.
The right operand in the expression is a float rather than an integer. The assembler
performs expression evaluation on only integers so it assumes integer 0 for this
operand.
S
Setting incorrect section attributes for name
When setting section attributes on a special section, the section's attributes should
match those of the predefined type. The assembler uses the predefined type for the
section.
Setting incorrect section type for name
When setting section attributes on a special section, the section's attributes should
match those of the predefined type. The assembler uses the predefined type for the
section.
Size negative; .fill ignored.
The size argument to the .fill directive must be non-negative.
T
Tried to set unrecognized symbol: name
The symbol in the .set directive was not a recognized PIC32 MCU assembler symbol.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 94 2013 Microchip Technology Inc.
Truncated file filename, num1 of num2 bytes read.
The number of bytes read from the .incbin file was fewer than the number specified
in the counts argument.
U
Unknown escape \escape in string; ignored.
The string contains an unrecognized backslash-escaped character. Check that the
character following the backslash is correct.
Used $at without .set noat.
This code is using the $at (assembler temporary) register, but the assembler may use
it when generating synthesized macro instruction. Use the .set noat directive to tell
the assembler not to quietly use this register
5.5 MESSAGES
The assembler generates messages when a non-critical assumption is made so that
the assembler could continue assembling a flawed program. Messages may be
ignored. However, messages can sometimes point out bugs in your program.
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 95
Part 2 – MPLAB XC32 Object Linker
Chapter 6. Linker Overview......................................................................................... 97
Chapter 7. Linker Command-Line Interface............................................................. 105
Chapter 8. Linker Scripts........................................................................................... 119
Chapter 9. Linker Processing ................................................................................... 147
Chapter 10. Linker Examples .................................................................................... 163
Chapter 11. Linker Errors/Warnings......................................................................... 167
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 96 2013 Microchip Technology Inc.
NOTES:
6‘ MICROCHIP V c Cumpner J, Assemb‘er Arcmver (Lmranam ¢ Linker Cummand Lme
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 97
Chapter 6. Linker Overview
6.1 INTRODUCTION
MPLAB XC32 Object Linker (xc32-ld) produces binary code from relocatable object
code and archives for the PIC32 MCU family of devices. The 32-bit linker is a Windows
console application that provides a platform for developing executable code. The linker
is a part of the GNU linker from the Free Software Foundation.
Topics covered in this chapter are:
Linker and Other Development Tools
Feature Set
Input/Output Files
6.2 LINKER AND OTHER DEVELOPMENT TOOLS
The PIC32 linker translates object files from the PIC32 assembler, and archives files
from the PIC32 archiver/librarian, into an executable file. See Figure 6-1 for an
overview of the tools process flow.
FIGURE 6-1: TOOLS PROCESS FLOW
Object File Libraries
(*.a)
Assembler
Linker
C/C++ Source Files
(*.c, *.cpp)
C Compiler
Source Files (*.s)
Assembly Source
Files (*.S)
Object Files
(*.o)
Executable File
(*.elf)
Archiver (Librarian)
Command Line
Simulator
Compiler
Driver
Program
MPLAB® X IDE
Debug Tool
Linker Script
(*.ld)
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 98 2013 Microchip Technology Inc.
6.3 FEATURE SET
Notable features of the linker include:
User-defined minimum stack allocation
User-defined heap allocation
Available for Windows
Linker scripts for all current PIC32 devices
Command-Line Interface
Integrated component of MPLAB X IDE
6.4 INPUT/OUTPUT FILES
Linker input and output files are listed below.
TABLE 6-1: LINKER FILES
Unlike the Microchip MPLINK™ linker, the 32-bit linker does not generate absolute
listing files. The 32-bit linker is capable of creating a map file and a binary ELF file (that
may or may not contain debugging information). For text output similar to MPLINK's
listing file, run the ELF file through the xc32-objdump binary utility.
6.4.1 Object Files
Relocatable code produced by the assembler. The linker accepts the ELF object file
format.
6.4.2 Library Files
A collection of object files grouped together for convenience.
6.4.3 Linker Script File
Linker scripts, or command files:
Instruct the linker where to locate sections
Specify memory ranges for a given part
Can be customized to locate user-defined sections at specific addresses
For more on linker script files, see Chapter 8. “Linker Scripts”.
Extension Description
Input
.o Object Files
.a Library Files
.ld Linker Script File
Output
.elf, .out Linker Output Files
.map Map File
Linker Overview
2013 Microchip Technology Inc. DS50002186A-page 99
EXAMPLE 6-1: LINKER SCRIPT
OUTPUT_FORMAT("elf32-tradlittlemips")
OUTPUT_ARCH(pic32mx)
ENTRY(_reset)
MEMORY
{
kseg0_program_mem(rx): ORIGIN=0x9D000000, LENGTH=0x8000
kseg0_boot_mem : ORIGIN=0x9FC00490, LENGTH=0x970
exception_mem : ORIGIN=0x9FC01000, LENGTH=0x1000
kseg1_boot_mem : ORIGIN=0xBFC00000, LENGTH=0x490
debug_exec_mem : ORIGIN=0xBFC02000, LENGTH=0xFF0
config3 : ORIGIN=0xBFC02FF0, LENGTH=0x4
config2 : ORIGIN=0xBFC02FF4, LENGTH=0x4
config1 : ORIGIN=0xBFC02FF8, LENGTH=0x4
config0 : ORIGIN=0xBFC02FFC, LENGTH=0x4
kseg1_data_mem (w!x): ORIGIN=0xA0000000, LENGTH=0x2000
sfrs : ORIGIN=0xBF800000, LENGTH=0x100000
}
SECTIONS
{
.text ORIGIN(kseg0_program_mem) :
{
_text_begin = . ;
*(.text .stub .text.* )
*(.mips16.fn.*)
*(.mips16.call.*)
_text_end = . ;
} >kseg0_program_mem =0
.data :
{
_data_begin = . ;
*(.data .data.* .gnu.linkonce.d.*)
KEEP (*(.gnu.linkonce.d.*personality*))
*(.data1)
} >kseg1_data_mem AT>kseg0_program_mem
.bss :
{
*(.dynbss)
*(.bss .bss.* )
*(COMMON)
. = ALIGN(32 / 8) ;
} >kseg1_data_mem
.stack ALIGN(4) :
{
. += _min_stack_size ;
} >kseg1_data_mem
}
Note: This simplified linker-script example is for illustrative purposes only; it is not
a complete, working, linker script.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 100 2013 Microchip Technology Inc.
6.4.4 Linker Output Files
By default, the name of the linker output binary file is a.out. You can override the
default name by specifying the -o option on the command line. The MPLAB X IDE proj-
ect manager uses the -o option to name the output file projectname.elf, where
projectname is the name of your MPLAB X IDE project.
The format of the binary file is an Executable and Linking Format (ELF) file. The Exe-
cutable and Linking Format was originally developed and published by UNIX System
Laboratories (USL) as part of the Application Binary Interface (ABI). The ELF specifi-
cation is the result of the work of the Tool Interface Standards (TIS) Committee, an
association of members of the microcomputer industry formed to work toward
standardization of the software interfaces visible to development tools.
The debugging information within the ELF file is in the DWARF Debugging Information
format. Also a result of the work of the TIS Committee, the DWARF format uses a series
of debugging entries to define a low-level representation of a source program. A
DWARF consumer, such as MPLAB X IDE, can then use the representation to create
an accurate picture of the original source program
6.4.5 Map File
The map files produced by the linker consist of:
Archive Member Table – lists the name of any members from archive files that are
included in the link.
Memory Usage Report – shows the starting address and length of all output
sections in program memory and data memory. It also shows a percent utilization
of memory in the region.
Memory Configuration – lists all of the memory regions defined for the link.
Linker Script and Memory Map – shows modules, sections and symbols that are
included in the link as specified in the linker script.
Outside Cross Reference Table (optional) - shows symbols, sorted by name. For
each symbol, a list of file names is given. If the symbol is defined, the first file
listed is the location of the definition. The remaining files listed contain references
to the symbol.
Linker Overview
2013 Microchip Technology Inc. DS50002186A-page 101
EXAMPLE 6-2: MAP FILE
Archive member included because of file (symbol)
size\libc.a(general-exception.o)
size/crt0.o (_general_exception_context)
size\libc.a(default-general-exception-handler.o)
size\libc.a(general-exception.o) (_general_exception_handler)
size\libc.a(default-bootstrap-exception-handler.o)
size/crt0.o (_bootstrap_exception_handler)
size\libc.a(default-on-reset.o)
size/crt0.o (_on_reset)
size\libc.a(default-on-bootstrap.o)
size/crt0.o (_on_bootstrap)
size\libc.a(default-nmi-handler.o)
size/crt0.o (_nmi_handler)
Microchip PIC32 Memory-Usage Report
kseg0 Program-Memory Usage
section address length (dec) Description
------- ---------- -------------- -----------
.text 0x9d000000 0x678 1656 Application's executable code
.rodata 0x9d000678 0x14 20 Read-only constant data
.data 0x9d00068c 0xf 244 Data-initialization template
.sdata 0x9d000780 0x4 4 Small data-initialization template
Total kseg0_program_mem used:
0x784 1924 0.4% of 0x80000
kseg0 Boot-Memory Usage
section address length (dec) Description
------- ---------- -------------- -----------
.startup 0x9fc00490 0x1e0 480 C startup code
Total kseg0_boot_mem used:
0x1e0 480 19.9% of 0x970
Exception-Memory Usage
section address length (dec) Description
------- ---------- -------------- -----------
.app_excpt 0x9fc01180 0x10 16 General-Exception handler
.vector_1 0x9fc01220 0x8 8 Interrupt Vector 1
Total exception_mem used :
0x18 24 0.6% of 0x1000
kseg1 Boot-Memory Usage
section address length (dec) Description
------- ---------- -------------- -----------
.reset 0xbfc00000 0x10 16 Reset handler
.bev_excpt 0xbfc00380 0x10 16 BEV-Exception handler
Total kseg1_boot_mem used :
0x20 32 2.7% of 0x490
-----------------------------------------------
Total Program Memory used :
0x99c 2460 0.5% of 0x81e00
-----------------------------------------------
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 102 2013 Microchip Technology Inc.
kseg1 Data-Memory Usage
section address length (dec) Description
------- ---------- -------------- -----------
.data 0xa0000000 0xf4 244 Initialized data
.sdata 0xa00000f4 0x4 4 Small initialized data
.sbss 0xa00000f8 0x4 4 Small uninitialized data
.bss 0xa00000fc 0x10c 268 Uninitialized data
.heap 0xa0000208 0x800 2048 Dynamic Memory heap
.stack 0xa0000a08 0x400 1024 Min space reserved for stack
Total kseg1_data_mem used :
0xe08 3592 11.0% of 0x8000
--------------------------------------------------------------
Total Data Memory used :
0xe08 3592 11.0% of 0x8000
--------------------------------------------------------------
Memory Configuration
Name Origin Length Attributes
kseg0_program_mem 0x9d000000 0x00080000 xr
kseg0_boot_mem 0x9fc00490 0x00000970
exception_mem 0x9fc01000 0x00001000
kseg1_boot_mem 0xbfc00000 0x00000490
config0 0xbfc02ffc 0x00000004
kseg1_data_mem 0xa0000000 0x00008000 w !x
sfrs 0xbf800000 0x00100000
*default* 0x00000000 0xffffffff
Linker script and memory map
LOAD size/crt0.o
0x00000800 _min_heap_size = 0x800
START GROUP
LOAD size\libc.a
LOAD size\libm.a
LOAD size\libmchp_peripheral_32MX360F512L.a
END GROUP
LOAD C:/xc32-Tools/bin/../lib/gcc/pic32mx/3.4.4/size\libgcc.a
0x00000400 PROVIDE (_min_stack_size, 0x400)
0x00000000 PROVIDE (_min_heap_size, 0x0)
LOAD ./proc/32MX360F512L\processor.o
0x00000001 PROVIDE (_vector_spacing, 0x1)
0x9fc01000 _ebase_address = 0x9fc01000
0xbfc00000 _RESET_ADDR = 0xbfc00000
0xbfc00380 _BEV_EXCPT_ADDR = 0xbfc00380
0x9fc01180 _GEN_EXCPT_ADDR = (_ebase_address + 0x180)
.reset 0xbfc00000 0x10
*(.reset)
.reset 0xbfc00000 0x10 size/crt0.o
0xbfc00000 _reset
.bev_excpt 0xbfc00380 0x10
*(.bev_handler)
.bev_handler 0xbfc00380 0x10 size/crt0.o
.vector_0 0x9fc01200 0x0
*(.vector_0)
.startup 0x9fc00490 0x1e0
*(.startup)
.startup 0x9fc00490 0x1e0 size/crt0.o
Linker Overview
2013 Microchip Technology Inc. DS50002186A-page 103
.text 0x9d000000 0x678
0x9d000000 _text_begin = .
*(.text .stub .text.* .gnu.linkonce.t.*)
.text 0x9d000000 0x18 size/crt0.o
.text 0x9d000018 0x110 intermediate\object.o
0x9d000089 testfunct
0x9d0000a0 main
0x9d000018 foo
.text 0x9d000128 0xc intermediate est.o
0x9d000128 mylabel
.text.general_exception
0x9d000134 0xd0 size\libc.a(general-exception.o)
0x9d000134 _general_exception_context
.text._general_exception_handler
0x9d0005bc 0x8 size\libc.a(default-general-exception-handler.o)
0x9d0005bc _general_exception_handler
.text._bootstrap_exception_handler
0x9d0005c4 0x8 size\libc.a(default-bootstrap-exception-handler.o)
0x9d0005c4 _bootstrap_exception_handler
.text._on_reset
0x9d0005cc 0x8 size\libc.a(default-on-reset.o)
0x9d0005cc _on_reset
.text._on_bootstrap
0x9d0005d4 0x8 size\libc.a(default-on-bootstrap.o)
0x9d0005d4 _on_bootstrap
.text 0x9d0005dc 0x18 size\libc.a(default-nmi-handler.o)
0x9d0005dc _nmi_handler
.sdata 0xa00000f4 0x4 load address 0x9d000780
0xa00000f4 _sdata_begin = .
.heap 0xa0000208 0x800
0xa0000208 _heap = .
0xa0000a08 . = (. + _min_heap_size)
*fill* 0xa0000208 0x800 00
.stack 0xa0000a08 0x400
0xa0000e08 . = (. + _min_stack_size)
*fill* 0xa0000a08 0x400 00
.ramfunc 0xa0001000 0x0 load address 0x9d000784
0xa0001000 _ramfunc_begin = .
*(.ramfunc .ramfunc.*)
0xa0001000 . = ALIGN (0x4)
0xa0008000 _stack =
(_ramfunc_length >0x0)?
(_ramfunc_begin - 0x4):0xa0008000
OUTPUT(test-2.elf elf32-tradlittlemips)
Cross Reference Table
Symbol File
PORTE ./proc/32MX360F512L\processor.o
size\libc.a(default-nmi-handler.o)
size\libc.a(general-exception.o)
intermediate/test.o
size/crt0.o
foo intermediate\cobject.o
main intermediate\cobject.o
size/crt0.o
mylabel intermediate\asmobject.o
funct intermediate\cobject.o
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 104 2013 Microchip Technology Inc.
NOTES:
6‘ MICROCHIP
MPLAB® XC32 ASSEMBLER,
LINKER AND UTILITIES
USERS GUIDE
2013 Microchip Technology Inc. DS50002186A-page 105
Chapter 7. Linker Command-Line Interface
7.1 INTRODUCTION
MPLAB XC32 Object Linker (xc32-ld) may be used on the command line interface as
well as with MPLAB X IDE.
Topics covered in this chapter are:
Linker Interface Syntax
Compilation-Driver Linker Interface Syntax
Options that Control Output File Creation
Options that Control Run-time Initialization
Options that Control Informational Output
Options that Modify the Link Map Output
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 106 2013 Microchip Technology Inc.
7.2 LINKER INTERFACE SYNTAX
The linker supports a plethora of command-line options, but in actual practice few of
them are used in any particular context.
xc32-ld [options] file...
For instance, a frequent use of xc32-ld is to link object files and archives to produce
a binary file. To link a file hello.o:
xc32-ld -o output hello.o -lpic32
This tells xc32-ld to produce a file called output as the result of linking the file
hello.o with the archive libpic32.a.
When linking a C application, there are typically several archives (also known as “librar-
ies”) which are included in the link command. The list of archives may be specified
within --start-group, --end-group options to help resolve circular references:
xc32-ld -o output hello.o --start-group -lpic32 -lm -lc --end-group
The command-line options to xc32-ld may be specified in any order, and may be
repeated at will. Repeating most options with a different argument will either have no
further effect, or override prior occurrences (those further to the left on the command
line) of that option. Options that may be meaningfully specified more than once are
noted in the descriptions below.
Non-option arguments are object files that are to be linked together. They may follow,
precede or be mixed in with command-line options, except that an object file argument
may not be placed between an option and its argument.
Usually the linker is invoked with at least one object file, but you can specify other forms
of binary input files using -l and the script command language. If no binary input files
are specified, the linker does not produce any output, and issues the message ‘No
input files’.
If the linker cannot recognize the format of an object file, it will assume that it is a linker
script. A script specified in this way augments the main linker script used for the link
(either the default linker script or the one specified by using -T). This feature permits
the linker to link against a file that appears to be an object or an archive, but actually
merely defines some symbol values, or uses INPUT or GROUP to load other objects.
For options whose names are a single letter, option arguments must either follow the
option letter without intervening white space, or be given as separate arguments
immediately following the option that requires them.
For options whose names are multiple letters, either one dash or two can precede the
option name; for example, -trace-symbol and --trace-symbol are equivalent.
There is one exception to this rule. Multiple-letter options that begin with the letter o can
only be preceded by two dashes.
Arguments to multiple-letter options must either be separated from the option name
by an equals sign, or be given as separate arguments immediately following the
option that requires them. For example, --trace-symbol srec and
--trace-symbol=srec are equivalent. Unique abbreviations of the names of
multiple-letter options are accepted.
Note: command-line options are case sensitive.
Linker Command-Line Interface
2013 Microchip Technology Inc. DS50002186A-page 107
7.3 COMPILATION-DRIVER LINKER INTERFACE SYNTAX
In practice, the linker is usually invoked via xc32-gcc, the compilation driver. The basic
form of the compilation-driver command line is:
xc32-gcc [options] files
To pass a linker option from the compilation driver to the linker, use the -Wl,option
option.
EXAMPLE 7-1: COMPILATION-DRIVER COMMAND LINE
xc32-gcc -mprocessor=32MX360F512L "input.o" -o"output.elf"
-Os -Wl,--defsym=_min_heap_size=2048,-Map="mapfile.map",
--cref,--report-mem
Calling the linker via the compilation driver has a few advantages over calling the linker
directly.
The driver's -mprocessor option allows the driver to pass the correct
device-specific include-file and library search paths to the linker. For instance,
when specifying -mprocessor=32MX360F512L, the driver passes the
corresponding device-specific library search path,
pic32mx/lib/proc/32MX360F512L, to the linker. This path allows the linker to
find the correct default linker script and processor library for the target device.
The driver accepts the C compiler's optimization, ISA mode, and floating-point
support options required to select the appropriate multilib permutation. For exam-
ple, when passing the -Os size optimization option, the driver passes
pic32mx/lib/size as a library search path so that the linker uses the
pre-compiled libraries optimized for size. See the “MPLAB XC32 C/C++ Compiler
User’s Guide” (DS51686) for more information on the C compiler's multilib
feature.
Note: Command-line options and filename extensions are case sensitive.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 108 2013 Microchip Technology Inc.
7.4 OPTIONS THAT CONTROL OUTPUT FILE CREATION
Output file creation options are:
-( archives -), --start-group archives, --end-group
-d, -dc, -dp
--defsym sym=expr
--discard-all (-x)
--discard-locals (-X)
• --fill=option
--gc-sections
--library name (-l name)
--library-path <dir> (-L <dir>)
-nodefaultlibs
-nostartfiles
-nostdlib
--output file (-o file)
--p PROC
--relocatable (-r, -i, -Ur)
--retain-symbols-file file
--section-start sectionname=org
--script file (-T file)
--strip-all (-s)
--strip-debug (-S)
-Tbss address
-Tdata address
-Ttext address
--undefined symbol (-u symbol)
--no-undefined
--wrap symbol
7.4.1 -( archives -), --start-group archives,
--end-group
Start and end a group.
The archives should be a list of archive files. They may be either explicit file names, or
-l options. The specified archives are searched repeatedly until no new undefined
references are created. Normally, an archive is searched only once in the order that it
is specified on the command line. If a symbol in that archive is needed to resolve an
undefined symbol referred to by an object in an archive that appears later on the
command line, the linker would not be able to resolve that reference. By grouping the
archives, they will all be searched repeatedly until all possible references are resolved.
Using this option has a significant performance cost. It is best to use it only when there
are unavoidable circular references between two or more archives.
7.4.2 -d, -dc, -dp
Force common symbols to be defined.
Assign space to common symbols even if a relocatable output file is specified (with -r).
The script command FORCE_COMMON_ALLOCATION has the same effect.
Linker Command-Line Interface
2013 Microchip Technology Inc. DS50002186A-page 109
7.4.3 --defsym sym=expr
Define a symbol.
Create a global symbol in the output file, containing the absolute address given by
expr. You may use this option as many times as necessary to define multiple symbols
in the command line. A limited form of arithmetic is supported for the expr in this
context: you may give a hexadecimal constant or the name of an existing symbol, or
use + and - to add or subtract hexadecimal constants or symbols.
7.4.4 --discard-all (-x)
Discard all local symbols.
7.4.5 --discard-locals (-X)
Discard temporary local symbols.
7.4.6 --fill=option
--fill=option
Fill unused program memory. The format is:
--fill=[wn:]expression[@address[:end_address] | unused]
address and end_address will specify the range of program memory addresses to fill.
If end_address is not provided, then the expression will be written to the specific mem-
ory location at address address. The optional literal value unused may be specified to
indicate that all unused memory will be filled. If none of the location parameters are pro-
vided, all unused memory will be filled. expression will describe how to fill the specified
memory. The following options are available:
Single value:
xc32-ld --fill=0x12345678@unused
Range of values:
xc32-ld --fill=1,2,3,4,097@0x9d000650:0x9d000750
Incrementing value:
xc32-ld --fill=7+=711@unused
By default, the linker will fill using data that is instruction-word length. For 32-bit
devices, the default fill width is 32 bits. However, you may specify the value width using
[wn:], where n is the fill value's width and n belongs to [1, 2, 4, 8]. Multiple fill options
may be specified on the command line; the linker will always process fill options at
specific locations first.
7.4.7 --gc-sections
Enable garbage collection of unused input sections. This option is not compatible with
-r. The default behavior (of not performing this garbage collection) can be restored by
specifying --no-gc-sections on the command line.
When link-time garbage collection is in use, marking sections that should not be elimi-
nated is often useful. Mark the section by surrounding an input section's wildcard entry
with KEEP(), as in KEEP(*(.init)) or KEEP(SORT_BY_NAME(*)(.ctors)).
Note: There should be no white space between sym, the equals sign (“=”) and
expr.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 110 2013 Microchip Technology Inc.
7.4.8 --library name (-l name)
Search for library name.
Add archive file name to the list of files to link. This option may be used any number of
times. xc32-ld will search its path-list for occurrences of libname.a for every name
specified. The linker will search an archive only once, at the location where it is speci-
fied on the command line. If the archive defines a symbol that was undefined in some
object that appeared before the archive on the command line, the linker will include the
appropriate file(s) from the archive. However, an undefined symbol in an object appear-
ing later on the command line will not cause the linker to search the archive again. See
the -( option for a way to force the linker to search archives multiple times. You may
list the same archive multiple times on the command line.
If the format of the archive file is not recognized, the linker will ignore it. Therefore, a
version mismatch between libraries and the linker may result in “undefined symbol”
errors.
7.4.9 --library-path <dir> (-L <dir>)
Add <dir> to library search path.
Add path <dir> to the list of paths that xc32-ld will search for archive libraries and
xc32-ld control scripts. You may use this option any number of times. The directories
are searched in the order in which they are specified on the command line. All -L
options apply to all -l options, regardless of the order in which the options appear. The
library paths can also be specified in a link script with the SEARCH_DIR command.
Directories specified this way are searched at the point in which the linker script
appears in the command line.
7.4.10 -nodefaultlibs
Do not use the standard system libraries when linking. Only the libraries you specify
are passed to the linker. The compiler may generate calls to memcmp, memset and
memcpy. These entries are usually resolved by entries in the standard compiler librar-
ies. These entry points should be supplied through some other mechanism when this
option is specified.
7.4.11 -nostartfiles
Do not pass the default prebuilt C startup file (pic32mx/lib/crt0.o) to the linker.
You will provide your own version of the startup code for the application.
7.4.12 -nostdlib
Do not use the standard system startup files or libraries when linking. No startup files
and only the libraries you specify are passed to the linker. The compiler may generate
calls to memcmp, memset and memcpy. These entries are usually resolved by entries
in standard compiler libraries. These entry points should be supplied through some
other mechanism when this option is specified.
7.4.13 --output file (-o file)
Set output ELF file name.
Use file as the name for the program produced by xc32-ld; if this option is not
specified, the name a.out is used by default.
7.4.14 --p PROC
Specify the target processor (e.g., 32MX795F512L).
Specify a target processor for the link.
Linker Command-Line Interface
2013 Microchip Technology Inc. DS50002186A-page 111
7.4.15 --relocatable (-r, -i, -Ur)
Generate relocatable output.
I.e., generate an output file that can in turn serve as input to xc32-ld. This is often
called partial linking. If this option is not specified, an absolute file is produced.
7.4.16 --retain-symbols-file file
Keep only symbols listed in file.
Retain only the symbols listed in the file file, discarding all others. file is simply a
flat file, with one symbol name per line. This option is especially useful in environments
where a large global symbol table is accumulated gradually, to conserve run-time
memory. --retain-symbols-file does not discard undefined symbols, or symbols
needed for relocations. You may only specify --retain-symbols-file once in the
command line. It overrides -s and -S.
7.4.17 --section-start sectionname=org
Locate a section in the output file at the absolute address given by org. You may use
this option as many times as necessary to locate multiple sections in the command line.
org must be a single hexadecimal integer; for compatibility with other linkers, you may
omit the leading ‘0x’ that is usually associated with hexadecimal values.
7.4.18 --script file (-T file)
Read linker script.
Read link commands from the file file. These commands replace xc32-ld’s default
link script (rather than adding to it), so file must specify everything necessary to
describe the target format. If file does not exist, xc32-ld looks for it in the directories
specified by any preceding -L options. Multiple -T options accumulate.
7.4.19 --strip-all (-s)
Strip all symbols. Omit all symbol information from the output file.
7.4.20 --strip-debug (-S)
Strip debugging symbols. Omit debugger symbol information (but not all symbols) from
the output file.
7.4.21 -Tbss address
Set address of .bss section.
Use address as the starting address for the bss segment of the output file. address
must be a single hexadecimal integer; for compatibility with other linkers, you may omit
the leading ‘0x’ that is usually associated with hexadecimal values.
Normally the address of this section is specified in a linker script.
7.4.22 -Tdata address
Set address of .data section.
Use address as the starting address for the data segment of the output file. address
must be a single hexadecimal integer; for compatibility with other linkers, you may omit
the leading ‘0x’ that is usually associated with hexadecimal values.
Normally the address of this section is specified in a linker script.
Note: There should be no white space between sectionname, the equals sign
(=), and org.
XC32 Assembler, Linker and Utilities User’s Guide
DS50002186A-page 112 2013 Microchip Technology Inc.
7.4.23 -Ttext address
Set address of .text section.
Use address as the starting address for the text segment of the output file. address
must be a single hexadecimal integer; for compatibility with other linkers, you may omit
the leading ‘0x’ that is usually associated with hexadecimal values.
Normally the address of this section is specified in a linker script.
7.4.24 --undefined symbol (-u symbol)
Start with undefined reference to symbol.
Force symbol to be entered in the output file as an undefined symbol. Doing this may,
for example, trigger linking of additional modules from standard libraries. -u may be
repeated with different option arguments to enter additional undefined symbols.
7.4.25 --no-undefined
Allow no undefined symbols.
7.4.26 --wrap symbol
Use wrapper functions for symbol
Use a wrapper function for symbol. Any undefined reference to symbol will be resolved
to __wrap_symbol. Any undefined reference to __real_symbol will be resolved to