MPASM Assembler, MPLINK Object Linker, MPLIB Librarian User's Guide User

mpasm%20user%20guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 338

DownloadMPASM Assembler, MPLINK Object Linker, MPLIB Librarian User's Guide User
Open PDF In BrowserView PDF
MPASM™ Assembler,
MPLINK™ Object Linker,
MPLIB™ Object Librarian
User’s Guide

 1994-2013 Microchip Technology Inc.

DS33014L

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.

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.

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.
© 1994-2013, Microchip Technology Incorporated, Printed in
the U.S.A., All Rights Reserved.
Printed on recycled paper.
ISBN: 978-1-62077-002-3

QUALITY MANAGEMENT SYSTEM
CERTIFIED BY DNV

== ISO/TS 16949 ==
DS33014L-page 2

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.

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Table of Contents
Preface ........................................................................................................................................ 9
PIC1X MCU Language Tools and MPLAB X IDE ................................................................... 17
PIC1X MCU Language Tools and MPLAB IDE v8 .................................................................. 33

Part 1 – MPASM Assembler
Chapter 1. MPASM Assembler Overview
1.1 Introduction ....................................................................................................................................... 49
1.2 MPASM Assembler Defined ............................................................................................................. 49
1.3 How MPASM Assembler Helps You ................................................................................................. 49
1.4 Assembler Migration Path ................................................................................................................ 49
1.5 Assembler Compatibility Issues ....................................................................................................... 50
1.6 Assembler Operation ........................................................................................................................ 50
1.7 Assembler Input/Output Files ........................................................................................................... 52

Chapter 2. Assembler Interfaces
2.1 Introduction ....................................................................................................................................... 61
2.2 MPLAB X IDE Interface .................................................................................................................... 61
2.3 MPLAB IDE v8 Interface .................................................................................................................. 61
2.4 Windows Interface ............................................................................................................................ 62
2.5 Command Line Interface .................................................................................................................. 63

Chapter 3. Expression Syntax and Operation
3.1 Introduction ....................................................................................................................................... 65
3.2 Text Strings ...................................................................................................................................... 65
3.3 Reserved Words and Section Names .............................................................................................. 67
3.4 Numeric Constants and Radix .......................................................................................................... 67
3.5 Arithmetic Operators and Precedence ............................................................................................. 69

Chapter 4. Directives
4.1 Introduction ....................................................................................................................................... 71
4.2 Directives by Type ............................................................................................................................ 71
4.3 access_ovr - Begin an Object File Overlay Section in Access RAM (PIC18 MCUs) .................... 74
4.4 __badram - Identify Unimplemented RAM ...................................................................................... 75
4.5 __badrom - Identify Unimplemented ROM ...................................................................................... 76
4.6 bankisel - Generate Indirect Bank Selecting Code (PIC12/16 MCUs) ......................................... 77
4.7 banksel - Generate Bank Selecting Code ...................................................................................... 80
4.8 cblock - Define a Block of Constants ............................................................................................. 82
4.9 code - Begin an Object File Code Section ....................................................................................... 84
4.10 code_pack - Begin an Object File Packed Code Section (PIC18 MCUs) .................................... 85
4.11 __config - Set Processor Configuration Bits ............................................................................... 86
4.12 config - Set Processor Configuration Bits (PIC18 MCUs) ........................................................... 88
4.13 constant - Declare Symbol Constant .......................................................................................... 89
4.14 da - Store Strings in Program Memory (PIC12/16 MCUs) ............................................................. 90
4.15 data - Create Numeric and Text Data ........................................................................................... 92
4.16 db - Declare Data of One Byte ....................................................................................................... 94

 1994-2013 Microchip Technology Inc.

DS33014L-page 3

Assembler/Linker/Librarian User’s Guide
4.17 de - Declare EEPROM Data Byte .................................................................................................. 96
4.18 #define - Define a Text Substitution Label .................................................................................. 98
4.19 dt - Define Table (PIC12/16 MCUs) ............................................................................................ 100
4.20 dtm - Define Table (Extended PIC16 MCUs Only) ....................................................................... 100
4.21 dw - Declare Data of One Word .................................................................................................... 101
4.22 else - Begin Alternative Assembly Block to if Conditional ....................................................... 102
4.23 end - End Program Block ............................................................................................................. 103
4.24 endc - End an Automatic Constant Block .................................................................................... 103
4.25 endif - End Conditional Assembly Block .................................................................................... 104
4.26 endm - End a Macro Definition ..................................................................................................... 104
4.27 endw - End a while Loop ............................................................................................................ 105
4.28 equ - Define an Assembler Constant ........................................................................................... 105
4.29 error - Issue an Error Message ................................................................................................. 106
4.30 errorlevel - Set Message Level .............................................................................................. 108
4.31 exitm - Exit from a Macro ........................................................................................................... 111
4.32 expand - Expand Macro Listing ................................................................................................... 113
4.33 extern - Declare an Externally Defined Label ............................................................................ 114
4.34 fill - Specify Program Memory Fill Value ................................................................................. 116
4.35 global - Export a Label .............................................................................................................. 119
4.36 idata - Begin an Object File Initialized Data Section .................................................................. 120
4.37 idata_acs - Begin an Object File Initialized Data Section in Access RAM (PIC18 MCUs) ....... 122
4.38 __idlocs - Set Processor ID Locations ...................................................................................... 123
4.39 if - Begin Conditionally Assembled Code Block ......................................................................... 125
4.40 ifdef - Execute If Symbol Has Been Defined ............................................................................. 127
4.41 ifndef - Execute If Symbol Has Not Been Defined .................................................................... 129
4.42 #include - Include Additional Source File .................................................................................. 130
4.43 list - Listing Options .................................................................................................................. 131
4.44 local - Declare Local Macro Variable ......................................................................................... 132
4.45 macro - Declare Macro Definition ................................................................................................ 134
4.46 __maxram - Define Maximum RAM Location ............................................................................... 136
4.47 __maxrom - Define Maximum ROM Location .............................................................................. 137
4.48 messg - Create User Defined Message ....................................................................................... 138
4.49 noexpand - Turn off Macro Expansion ........................................................................................ 140
4.50 nolist - Turn off Listing Output .................................................................................................. 140
4.51 org - Set Program Origin ............................................................................................................. 141
4.52 page - Insert Listing Page Eject ................................................................................................... 144
4.53 pagesel - Generate Page Selecting Code (PIC10/12/16 MCUs) ............................................... 144
4.54 pageselw - Generate Page Selecting Code Using WREG Commands (PIC10/12/16 MCUs) ... 146
4.55 processor - Set Processor Type ............................................................................................... 147
4.56 radix - Specify Default Radix ..................................................................................................... 148
4.57 res - Reserve Memory ................................................................................................................. 150
4.58 set - Define an Assembler Variable ............................................................................................ 152
4.59 space - Insert Blank Listing Lines ................................................................................................ 153
4.60 subtitle - Specify Program Subtitle .......................................................................................... 153
4.61 title - Specify Program Title ..................................................................................................... 154
4.62 udata - Begin an Object File Uninitialized Data Section ............................................................. 154
4.63 udata_acs - Begin an Object File Access Uninitialized Data Section (PIC18 MCUs) ................ 156
4.64 udata_ovr - Begin an Object File Overlayed Uninitialized Data Section ................................... 158
4.65 udata_shr - Begin an Object File Shared Uninitialized Data Section (PIC12/16 MCUs) ........... 160
4.66 #undefine - Delete a Substitution Label .................................................................................... 162
4.67 variable - Declare Symbol Variable .......................................................................................... 163
4.68 while - Perform Loop While Condition is True ............................................................................ 165
DS33014L-page 4

 1994-2013 Microchip Technology Inc.

Table of Contents
Chapter 5. Assembler Examples, Tips and Tricks
5.1 Introduction ..................................................................................................................................... 169
5.2 Example of Displaying Count on Ports ........................................................................................... 170
5.3 Example of Port B Toggle and Delay Routines .............................................................................. 171
5.4 Example of Calculations with Variables and Constants ................................................................. 178
5.5 Example of a 32-Bit Delay Routine ................................................................................................ 180
5.6 Example of SPI Emulated in Firmware ........................................................................................... 182
5.7 Example of Hexadecimal to ASCII Conversion .............................................................................. 184
5.8 Other Sources of Examples ........................................................................................................... 185
5.9 Tips and Tricks ............................................................................................................................... 186

Chapter 6. Relocatable Objects
6.1 Introduction ..................................................................................................................................... 189
6.2 Header Files ................................................................................................................................... 189
6.3 Program Memory ............................................................................................................................ 190
6.4 Low, High and Upper Operators ..................................................................................................... 191
6.5 RAM Allocation ............................................................................................................................... 194
6.6 Configuration Bits and ID Locations ............................................................................................... 195
6.7 Accessing Labels From Other Modules ......................................................................................... 196
6.8 Paging and Banking Issues ............................................................................................................ 197
6.9 Generating the Object Module ....................................................................................................... 198
6.10 Code Example .............................................................................................................................. 198

Chapter 7. Macro Language
7.1 Introduction ..................................................................................................................................... 201
7.2 Macro Syntax ................................................................................................................................. 201
7.3 Macro Directives Defined ............................................................................................................... 202
7.4 Macro Definition ............................................................................................................................. 202
7.5 Macro Invocation ............................................................................................................................ 203
7.6 Macro Code Examples ................................................................................................................... 204

Chapter 8. Errors, Warnings, Messages, and Limitations
8.1 Introduction ..................................................................................................................................... 207
8.2 Assembler Errors ............................................................................................................................ 208
8.3 Assembler Warnings ...................................................................................................................... 215
8.4 Assembler Messages ..................................................................................................................... 218
8.5 Assembler Limitations .................................................................................................................... 220

Part 2 – MPLINK Object Linker
Chapter 9. MPLINK Linker Overview
9.1 Introduction ..................................................................................................................................... 223
9.2 MPLINK Linker Defined .................................................................................................................. 223
9.3 How MPLINK Linker Works ............................................................................................................ 223
9.4 How MPLINK Linker Helps You ..................................................................................................... 224
9.5 Linker Platforms Supported ............................................................................................................ 224
9.6 Linker Operation ............................................................................................................................. 225
9.7 Linker Input/Output Files ................................................................................................................ 226

Chapter 10. Linker Interfaces
10.1 Introduction ................................................................................................................................... 231
10.2 IDE Interface ................................................................................................................................ 231
10.3 Command Line Interface .............................................................................................................. 232
10.4 Command Line Example .............................................................................................................. 234

 1994-2013 Microchip Technology Inc.

DS33014L-page 5

Assembler/Linker/Librarian User’s Guide
Chapter 11. Linker Scripts
11.1 Introduction ................................................................................................................................... 235
11.2 Standard Linker Scripts ................................................................................................................ 236
11.3 Linker Script Command Line Information ..................................................................................... 237
11.4 Linker Script Caveats ................................................................................................................... 238
11.5 Memory Region Definition ............................................................................................................ 239
11.6 Logical Section Definition ............................................................................................................. 244
11.7 STACK Definition .......................................................................................................................... 244
11.8 Conditional Linker Statements ...................................................................................................... 245

Chapter 12. Linker Processing
12.1 Introduction ................................................................................................................................... 251
12.2 Linker Processing Overview ......................................................................................................... 251
12.3 Linker Allocation Algorithm ........................................................................................................... 252
12.4 Relocation Example ...................................................................................................................... 253
12.5 Initialized Data .............................................................................................................................. 254
12.6 Reserved Section Names ............................................................................................................. 254

Chapter 13. Sample Applications
13.1 Introduction ................................................................................................................................... 255
13.2 How to Build the Sample Applications .......................................................................................... 255
13.3 Sample Application 1 - Templates and Linker Scripts .................................................................. 261
13.4 Sample Application 2 - Placing Code and Setting Config Bits ...................................................... 264
13.5 Sample Application 3 - Using a Boot Loader ................................................................................ 267
13.6 Sample Application 4 - Configuring External Memory .................................................................. 278

Chapter 14. Errors, Warnings and Common Problems
14.1 Introduction ................................................................................................................................... 285
14.2 Linker Parse Errors ....................................................................................................................... 285
14.3 Linker Errors ................................................................................................................................. 287
14.4 Linker Warnings ............................................................................................................................ 292
14.5 COFF File Errors .......................................................................................................................... 293
14.6 Other Errors, Warnings and Messages ........................................................................................ 294
14.7 Common Problems ....................................................................................................................... 294

Part 3 – MPLIB Object Librarian
Chapter 15. MPLIB Librarian Overview
15.1 Introduction ................................................................................................................................... 297
15.2 What is MPLIB Librarian ............................................................................................................... 297
15.3 How MPLIB Librarian Works ........................................................................................................ 297
15.4 How MPLIB Librarian Helps You .................................................................................................. 298
15.5 Librarian Operation ....................................................................................................................... 298
15.6 Librarian Input/Output Files .......................................................................................................... 298

Chapter 16. Librarian Interfaces
16.1 Introduction ................................................................................................................................... 299
16.2 MPLAB X IDE Interface ................................................................................................................ 299
16.3 MPLAB IDE v8 Interface ............................................................................................................... 299
16.4 Command Line Options ................................................................................................................ 300
16.5 Command Line Examples and Tips .............................................................................................. 300

Chapter 17. Errors
17.1 Introduction ................................................................................................................................... 301
17.2 Librarian Parse Errors .................................................................................................................. 301
17.3 Library File Errors ......................................................................................................................... 302
17.4 COFF File Errors .......................................................................................................................... 302

DS33014L-page 6

 1994-2013 Microchip Technology Inc.

Table of Contents
Part 4 – Utilities
Chapter 18. Utilities Overview and Usage
18.1 Introduction ................................................................................................................................... 305
18.2 What are Utilities .......................................................................................................................... 305
18.3 Utilities Operation ......................................................................................................................... 305
18.4 mp2hex.exe Utility ........................................................................................................................ 306
18.5 mp2cod.exe Utility ........................................................................................................................ 306

Chapter 19. Errors and Warnings
19.1 Introduction ................................................................................................................................... 307
19.2 Hex File Errors ............................................................................................................................. 307
19.3 COFF To COD Conversion Errors ................................................................................................ 307
19.4 COFF To COD Converter Warnings ............................................................................................. 307
19.5 COD File Errors ............................................................................................................................ 308

Part 5 – Appendices
Appendix A. Instruction Sets
A.1 Introduction .................................................................................................................................... 311
A.2 Key to 12/14-Bit Instruction Width Instruction Sets ........................................................................ 311
A.3 12-Bit Instruction Width Instruction Set .......................................................................................... 313
A.4 14-Bit Instruction Width Instruction Set .......................................................................................... 315
A.5 14-Bit Instruction Width Extended Instruction Set .......................................................................... 317
A.6 12-Bit/14-Bit Instruction Width Pseudo-Instructions ....................................................................... 320
A.7 Key to PIC18 Device Instruction Set .............................................................................................. 322
A.8 PIC18 Device Instruction Set ......................................................................................................... 324
A.9 PIC18 Device Extended Instruction Set ......................................................................................... 328

Appendix B. Useful Tables
B.1 Introduction .................................................................................................................................... 329
B.2 ASCII Character Set ...................................................................................................................... 329
B.3 Hexadecimal to Decimal Conversion ............................................................................................. 330

Index ........................................................................................................................................ 331
Worldwide Sales and Service ............................................................................................... 337

 1994-2013 Microchip Technology Inc.

DS33014L-page 7

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 8

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Preface
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
“DSXXXXXA”, where “XXXXX” 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® IDE on-line help.
Select the Help menu, and then Topics to open a list of available on-line help files.

INTRODUCTION
This chapter contains general information that will be useful to know before using
Assembler/Linker/Librarian User’s Guide. Items discussed include:
•
•
•
•
•
•

Document Layout
Conventions Used
Recommended Reading
The Microchip Web Site
myMicrochip Personalized Notification Service
Customer Support

DOCUMENT LAYOUT
This document describes how to use the MPASM assembler, the MPLINK object linker,
and the MPLIB object librarian to develop code for PIC® microcontroller (MCU)
applications. All of these tools can work within the MPLAB® Integrated Development
Environment (IDE). For a detailed discussion about basic MPLAB IDE functions, refer
to MPLAB IDE documentation.
PIC1X MCU Language Tools and MPLAB X IDE – provides an overview of how to
use all of the tools in this manual together under the MPLAB X IDE. This is how most
developers will use these tools.
PIC1X MCU Language Tools and MPLAB IDE v.8 – provides an overview of how to
use all of the tools in this manual together under the MPLAB IDE v.8.

 1994-2013 Microchip Technology Inc.

DS33014L-page 9

Assembler/Linker/Librarian User’s Guide
Part 1 – “MPASM Assembler”
• Chapter 1. “MPASM Assembler Overview” – describes what the MPASM
assembler is, what it does and how it works with other tools. Also, gives an
overview of operation and discusses input/output files.
• Chapter 2. “Assembler Interfaces” – reviews how to use the MPASM
assembler with MPLAB IDE and describes how to use the assembler on the
command line or in a Windows shell interface.
• Chapter 3. “Expression Syntax and Operation” – provides guidelines for using
complex expressions in MPASM assembler source files.
• Chapter 4. “Directives” – lists each MPASM assembler directive alphabetically
and describes the directive in detail, with examples.
• Chapter 5. “Assembler Examples, Tips and Tricks” – provides examples of
how to use the MPASM assembler directives together in applications.
• Chapter 6. “Relocatable Objects” – describes how to use the MPASM
assembler in conjunction with MPLINK object linker.
• Chapter 7. “Macro Language” – describes how to use the MPASM assembler’s
built-in macro processor.
• Chapter 8. “Errors, Warnings, Messages, and Limitations” – contains a
descriptive list of the errors, warnings, and messages generated by the MPASM
assembler, as well as tool limitations.
Part 2 – “MPLINK Object Linker”
• Chapter 9. “MPLINK Linker Overview” – describes what the MPLINK object
linker is, what it does and how it works with other tools. Also, gives an overview of
operation and discusses input/output files.
• Chapter 10. “Linker Interfaces” – reviews how to use the MPLINK linker with
MPLAB IDE and describes how to use the linker on the command line.
• Chapter 11. “Linker Scripts” – discusses how to generate and use linker scripts
to control linker operation.
• Chapter 12. “Linker Processing” – describes how the linker processes files.
• Chapter 13. “Sample Applications” – provides examples of how to use the
linker to create applications.
- Sample Application 1 – explains how to find and use template files and
when to modify the generic linker script file.
- Sample Application 2 – explains how to place program code in different
memory regions, how to place data tables in ROM memory and how to set
configuration bits in C.
- Sample Application 3 – explains how to partition memory for a boot loader
and how to compile code that will be loaded into external RAM and executed.
- Sample Application 4 – explains how to create new linker script memory
section, how to declare external memory through #pragma code directive,
and how to access external memories using C pointers.
• Chapter 14. “Errors, Warnings and Common Problems” – contains a
descriptive list of the errors and warnings generated by the MPLINK linker, as well
as common problems and tool limitations.

DS33014L-page 10

 1994-2013 Microchip Technology Inc.

Preface
Part 3 – “MPLIB Object Librarian”
• Chapter 15. “MPLIB Librarian Overview” – decribes what the MPLIB object
librarian is, what it does and how it works with other tools. Also, gives an overview
of operation and discusses input/output files.
• Chapter 16. “Librarian Interfaces” – reviews how to use the MPLIB librarian
with MPLAB IDE and describes how to use the librarian on the command line.
• Chapter 17. “Errors” – contains a descriptive list of the errors generated by the
MPLIB librarian.
Part 4 – “Utilities”
• Chapter 18. “Utilities Overview and Usage” – lists the available utilities and
describes their usage.
• Chapter 19. “Errors and Warnings” – contains a descriptive list of the errors
generated by the utilities.
Part 5 – “Appendices”
• Appendix A. “Instruction Sets” – lists PIC MCU device instruction sets.
• Appendix B. “Useful Tables” – provides some useful tables for code
development.
- ASCII Character Set – lists the ASCII Character Set.
- Hexadecimal to Decimal Conversions – shows how to convert from
hexadecimal to decimal numbers.

 1994-2013 Microchip Technology Inc.

DS33014L-page 11

Assembler/Linker/Librarian User’s Guide
CONVENTIONS USED
The following conventions may appear in this documentation:
DOCUMENTATION CONVENTIONS
Description

Represents

Examples

Arial font:
Italic characters
Initial caps

Referenced books

MPLAB IDE User’s Guide

Emphasized text

...is the only compiler...

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

A key on the keyboard

Press , 

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)
{ ...
}

Text in angle brackets < >
Courier font:
Plain Courier

DS33014L-page 12

 1994-2013 Microchip Technology Inc.

Preface
RECOMMENDED READING
This documentation describes how to use Assembler/Linker/Librarian User’s Guide.
Other useful documents are listed below. The following Microchip documents are
available and recommended as supplemental reference resources.
Readme Files - readme.asm and readme.lkr
For the latest tool information and known issues, see the MPASM assembler readme
file (readme.asm) or the MPLINK object linker/MPLIB object librarian readme file
(readme.lkr). These ASCII text files may be found in the Readme folder of the
MPLAB IDE installation directory.
On-line Help Files
Comprehensive help files are available for MPASM assembler and MPLINK object
linker/MPLIB object librarian. In addition, debug output format (COFF) information is
also available in help.
C Compiler User’s Guides and Libraries
The MPLINK linker and MPLIB librarian also work with the MPLAB C Compiler for
PIC18 MCUs (formerly MPLAB C18). For more information on the compiler, see:
•
•
•
•

MPLAB® C Compiler for PIC18 MCUs Getting Started (DS51295)
MPLAB® C Compiler for PIC18 MCUs User's Guide (DS51288)
MPLAB® C Compiler for PIC18 MCUs Libraries (DS51297)
PIC18 Configuration Settings Addendum (DS51537) or on-line help file

MPLAB IDE Documenation
Information on the intergrated development environment MPLAB IDE may be found in:
• MPLAB® IDE User’s Guide (DS51519) – Comprehensive user’s guide.
• On-line help file – The most up-to-date information on MPLAB IDE.
PIC MCU Data Sheets and Application Notes
Data sheets contain information on device operation, as well as electrical
specifications. Applications notes demonstrate how various PIC MCU’s may be used.
Find both of these types of documents for your device on the Microchip website.

 1994-2013 Microchip Technology Inc.

DS33014L-page 13

Assembler/Linker/Librarian User’s Guide
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 Microchip in-circuit emulators.These
include the MPLAB REAL ICE™ and MPLAB ICE 2000 in-circuit emulators
• In-Circuit Debuggers – The latest information on Microchip in-circuit debuggers.
These include the MPLAB ICD 2 and 3 in-circuit debuggers and PICkit™ 2 and 3
debug express.
• MPLAB® IDE – The latest information on Microchip MPLAB IDE, the Windows®
Integrated Development Environment for development systems tools. This list is
focused on the MPLAB IDE, MPLAB IDE Project Manager, MPLAB Editor and
MPLAB 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 PRO MATE® II and
development (nonproduction) programmers MPLAB ICD 2 in-circuit debugger,
PICSTART® Plus and PICkit 1, 2 and 3.
• Starter/Demo Boards – These include MPLAB Starter Kit boards, PICDEM demo
boards, and various other evaluation boards.

DS33014L-page 14

 1994-2013 Microchip Technology Inc.

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

 1994-2013 Microchip Technology Inc.

DS33014L-page 15

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 16

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
PIC1X MCU Language Tools and MPLAB X IDE
INTRODUCTION
The MPASM™ assembler, the MPLINK™ object linker and the MPLIB™ object
librarian are typically used together under MPLAB® X Integrated Development
Environment (IDE) to provide GUI development of application code for PIC1X MCU
devices (PIC10/12/16/18 MCUs). The operation of these 8-bit language tools with
MPLAB X IDE is discussed here.
Additionally, the MPLAB C Compiler for PIC18 MCUs (MPLAB C18) may be used with
the above tools. For more on this compiler, see the Microchip website
(http://www.microchip.com) for additional information and documentation.
These language tools were initially developed for use in Microsoft Windows® .
However, the MPASMX toolchain does function in Linux and Mac OS (with support
available for the “/” and “-” characters). The C18 toolchain also supports these
operating systems.
Topics covered in this chapter:
•
•
•
•
•

MPLAB X IDE and Tools Installation
MPLAB X IDE Setup
MPLAB X IDE Projects
Project Setup
Project Example

MPLAB X IDE AND TOOLS INSTALLATION
MPLAB IDE includes the MPASM Toolsuite which consists of the MPASM assembler,
MPLINK linker, MPLIB librarian and other 8-bit utilities. Also, MPLAB IDE may be used
with the C18 Toolsuite that consists of the MPLAB C18 Compiler and compiler versions
of tools in the MPASM Toolsuite.

MPASM Toolsuite Installation
In order to use the PIC language tools with MPLAB IDE, you must first install MPLAB
IDE. The latest version of this free software is available at our website
(http://www.microchip.com) or from any sales office (back cover). When you install
MPLAB IDE, you will be installing the MPASM assembler, the MPLINK object linker and
the MPLIB object librarian as well.
The language tools will be installed, by default, in the directory:
• Windows OS - C:\Program Files\Microchip\MPLABX\mpasmx
• Linux OS - /opt/microchip/mplabx/mpasmx
• Mac OS - /Applications/microchip/mplabx/mpasmx
The executables for each tool will be:
•
•
•
•

MPASM Assembler – mpasmx.exe
MPLINK Object Linker – mplink.exe
MPLIB Object Librarian – mplib.exe
Other Utilities

 1994-2013 Microchip Technology Inc.

DS33014L-page 17

Assembler/Linker/Librarian User’s Guide
All device include (.inc) files are also in this directory. For more on these files, see
MPASM assembler documentation.
All device linker script (.lkr) files are in the LKR subdirectory. For more on these files,
see MPLINK object linker documentation.
Template files are also included in the Template subdirectory for your use. Template
files are provided for absolute code (Code) and relocatable code (Object)
development.
Code examples are also included in the Example subdirectory.

C18 Toolsuite Installation
The MPLAB C18 compiler and related tools must be acquired from Microchip
(standard, lite and evaluation versions available). The install includes the MPLAB C18
C compiler and compiler versions of tools in the MPASM Toolsuite.
The language tools will be installed, by default, in the directory:
• Windows OS - C:\Program Files\Microchip\mplabc18\version
• Mac OS - /Applications/microchip/mplabc18/version
• Linux OS - /opt/microchip/mplabc18/version
where version is the version of the compiler.
The executables for each tool will be:
•
•
•
•
•

MPLAB C18 C Compiler - bin\mcc18.exe
MPASM Assembler - mpasm\mpasmx.exe
MPLINK Object Linker - bin\mplink.exe
MPLIB Object Librarian - bin\mplib.exe
Other Utilities - bin subdirectory

All device header (.h) files are in the h subdirectory. For more on these files, see
MPLAB C18 documentation.
All device include (.inc) files are in the mpasm subdirectory. For more on these files,
see MPASM assembler documentation.
All device linker script (.lkr) files are in the bin\LKR subdirectory. For more on these
files, see MPLINK object linker documentation.
All device library (.lib) files and precompiled start-up code (.o) are in the lib
subdirectory. For more on these files, see MPLAB C18 libraries documentation.
Code examples are also included in the example subdirectory.

DS33014L-page 18

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB X IDE
MPLAB X IDE SETUP
Once MPLAB X IDE is installed on your PC, check the settings below to ensure that
the PIC1X language tools are properly recognized under MPLAB X IDE.
1. From the MPLAB X IDE menu bar, select Tools>Options to open the Options dialog. Click on the “Embedded” button and select the “Build Tools” tab.
2. Click on “MPASMX” under “Tool Collection”. Ensure that the paths are correct for
your installation of the MPASM assembler. This will ensure that the paths to the
linker, librarian and utilities are correct as all of these tools are part of the MPASM
Suite.
3. For the optional MPLAB C18 C compiler, click on “C18” under “Tool Collection”.
Ensure that the paths are correct for your installation of the compiler. This will
ensure that the paths to the compiler and related assembler, linker, librarian and
utilities are correct as all of these tools are part of the C18 Suite.
4. Click OK.
FIGURE 1:

 1994-2013 Microchip Technology Inc.

MPASM SUITE TOOL LOCATIONS

DS33014L-page 19

Assembler/Linker/Librarian User’s Guide
MPLAB X IDE PROJECTS
A project in MPLAB X IDE is a group of files needed to build an application, along with
their associations to various build tools. Below is a generic MPLAB X IDE project.
FIGURE 2:

PROJECT RELATIONSHIPS

MPLAB X IDE Project

prog.lst

source
files

prog.asm

main.c

MPASM
assembler

MPLAB C18

prog.o

main.o

ASSEMBLER/
COMPILER

list and object
files

precomp.o

LIBRARIAN &
library file

MPLIB librarian

math.lib

MPLINK linker

prog.cof

device.lkr

prog.map

LINKER &
linker
script file (1)

LINKER output
files

MP2HEX
Utility &
output file
prog.hex

SIMULATORS
EMULATORS
DEBUGGERS
PROGRAMMERS
(1) The linker can choose the correct
linker script file for your project.

DS33014L-page 20

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB X IDE
In this MPLAB X IDE project, an assembly source file (prog.asm) is shown with its
associated assembler (MPASM assembler). MPLAB X IDE will use this information to
generate the object file prog.o for input into the MPLINK object linker. For more
information on the assembler, see the MPASM assembler documentation.
The C source file main.c is also shown with its associated MPLAB C18 C compiler.
MPLAB X IDE will use this information to generate an object file (main.o) for input into
the MPLINK object linker. For more information on the compiler, see the MPLAB C18
C compiler documentation listed in Recommended Reading.
In addition, precompiled object files (precomp.o) may be included in a project, with no
associated tool required. MPLAB C18 requires the inclusion of a precompiled standard
code module c018i.o, for example. For more information on available Microchip
precompiled object files, see the MPLAB C18 C compiler documentation.
Some library files (math.lib) are available with the compiler. Others may be built
using the librarian tool (MPLIB object librarian). For more information on the librarian,
see the MPLIB librarian documentation. For more information on available Microchip
libraries, see the MPLAB C18 C compiler documentation.
The object files, along with library files, are used to generate the project output files via
the linker (MPLINK object linker). MPLAB X IDE will automatically add the correct linker
script file (device.lkr) for your project. For more information on using linker script
files and the linker, see the MPLINK linker documentation.
The main output file generated by the MPLINK linker is the COF file (prog.cof). The
linker then uses the utility MP2HEX to generate the Hex file (prog.hex), used by
simulators, emulators, debuggers and programmers. For more information on linker
output files, see the MPLINK linker documentation. For more information on utilities,
see the related documentation.
For more on projects, see MPLAB X IDE documentation.

 1994-2013 Microchip Technology Inc.

DS33014L-page 21

Assembler/Linker/Librarian User’s Guide
PROJECT SETUP
To set up an MPLAB X IDE project for the first time, use the built-in Project Wizard
(File>New Project). In this wizard, you will be able to select a language toolsuite. For
more on the wizard, and MPLAB X IDE projects, see MPLAB X IDE documentation.
Once you have a project set up, you may then set up properties of the tools in MPLAB
X IDE.
1. From the MPLAB X IDE menu bar, select File>Project Properties to open a dialog
to set/check project build options.
2. MPASM: For “Conf: [default]” > “MPASMX”, select a tool from the tool collection
to set up.
a) MPASM (TOP)
b) MPASM
c) MPLINK
3. MPLAB C18: For “Conf: [default]” > “C18”, select a tool from the tool collection
to set up.
a) C18 (TOP)
b) MPASM
c) MCC18
d) MPLINK

MPASM (TOP)
The top level of the MPASM toolchain contains the following options.
TABLE 1-1:

ALL OPTIONS CATEGORY

Option

Description

Build in absolute mode

TABLE 1-2:

Command Line

For assembly code projects, build using the assembler only, i.e.,
do not invoke the linker.

-ahex-format

ADDITIONAL CONTROLS

Option

Description

Additional Options

Enter additional command-line options. See the tool documentation for more options.

Option Description

Click on option text to see more information in this tab, if available.

Generated Command
Line

For selectable options, click this tab to see the equivalent command line option.

MPASM
Select a category, and then set up assembler options. For additional options, see MPASM assembler
documentation, Chapter 2. “Assembler Interfaces”.
TABLE 1-3:

GENERAL CATEGORY

Option
Enable case sensitivity

Description

Command Line

The assembler will distinguish between upper- and lower-case
letters.
Note: Disabling case sensitivity will make all labels uppercase.

-c+

Default Radix

Set the default radix, either Hexadecimal, Decimal or Octal.

-rradix

Preprocessor Macro
Definitions

Add macro directive definitions.

-dmacro

DS33014L-page 22

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB X IDE
TABLE 1-4:

OUTPUT CATEGORY

Option

Description

Command Line

Cross-reference file

Create an cross-reference file. A cross-reference file contains a
listing of all symbols used in the assembly code.

-x"xrf"

Diagnostic level

Select to display errors only; errors and warnings; or errors,
warnings and messages. These will be shown in the Output
window.

-wvalue

Hex file format (absolute
assembly only)

When assembling a single file, the assembler may be used to
generate a hex file. Choose the format here.
When assembling multiple files, the assembler generates object
files which must be linked with the linker to generate a hex file.
Choose the hex file format for the linker in this case.

-ahex-format

TABLE 1-5:

ADDITIONAL CONTROLS

Option

Description

Additional Options

Enter additional command-line options. See the tool documentation for more options.

Option Description

Click on option text to see more information in this tab, if available.

Generated Command
Line

For selectable options, click this tab to see the equivalent command line option.

MPLINK
Select a category, and then set up linker options. For additional options, see MPLINK object linker
documentation, Chapter 10. “Linker Interfaces”.
TABLE 1-6:

ALL OPTIONS CATEGORY

Option

Description

Command Line

Create a map file. A map file provides information on the

-m"map"

Hex file format

Choose the linker hex file format.

-ahex-format

Library directories

Browse to the path(s) of any libraries you want the linker to include -l"lib"
in the output. Manage the list of paths in the dialog.

Generate map file

absolute location of source code symbols in the final output.
It also provides information on memory use, indicating
used/unused memory.

TABLE 1-7:

ADDITIONAL CONTROLS

Option

Description

Additional Options

Enter additional command-line options. See the tool documentation for more options.

Option Description

Click on option text to see more information in this tab, if available.

Generated Command
Line

For selectable options, click this tab to see the equivalent command line option.

 1994-2013 Microchip Technology Inc.

DS33014L-page 23

Assembler/Linker/Librarian User’s Guide
C18 (TOP)
The top level of the C18 toolchain contains the following options.
TABLE 1-8:

ALL OPTIONS CATEGORY

Option

Description

Command Line

Enable extended
instruction set

Build in extended mode. The selected device must support
--extended
extended mode and the correct configuration bit must be enabled. --no-extended
See “MPLAB C18: Setup for PIC18 Extended Instruction Set Use”.

Enable stack analysis

Generate a stack analysis report for use with third-party application -g
“Understand,” from Scientific Toolworks, Inc. See their web site at
www.scitools.com for more information.
This option is only supported on devices that support extended
mode. The checkbox for Enable extended instruction set must be
checked as well. (See the previous row in this table.)

TABLE 1-9:

ADDITIONAL CONTROLS

Option

Description

Additional Options

Enter additional command-line options. See the tool documentation for more options.

Option Description

Click on option text to see more information in this tab, if available.

Generated Command
Line

For selectable options, click this tab to see the equivalent command line option.

MPLAB C18: Setup for PIC18 Extended Instruction Set Use
To use the PIC18 MCU Extended Instruction set in your MPLAB C18 project, do the following:
• Enable “Extended Instruction Set” in the configuration bits by doing one of the following:
- In code, use CONFIG XINST=ON.
- In the Configurations Bits window, under XINST select “Enabled”.
• Select File>Project Properties, click on C18, and check “Enable extended instruction set. Click OK.
For a list of available instructions in the Extended Instruction set, see Section A.9 “PIC18 Device
Extended Instruction Set”.

MCC18
Although the MPLAB C18 C compiler works with MPLAB X IDE, it must be acquired separately. The
standard version may be purchased, or a free (limited-feature) version may be downloaded. See the
Microchip website (www.microchip.com) for details. This compiler supports PIC18X MCU devices.
A subset of command-line options may be specified in MPLAB X IDE. Select a category, and then set up
compiler options. For additional options, see the MPLAB C Compiler for PIC18 MCUs User’s Guide
(DS51288), also available on the Microchip website.
TABLE 1-10:

MEMORY MODEL CATEGORY

Option

Description

Command Line

Code model

Select a code (program memory/ROM) model. Choose from small
(64K bytes) or large (>64K bytes).

-mmodel

Data model

Select a data (data memory/RAM) model. Choose from large (all RAM
banks) or small (access RAM only).

-Omodel

Enable multi-bank stack
model

Select a stack model. Choose from single bank or multiple bank.

-Lmodel

DS33014L-page 24

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB X IDE
TABLE 1-11:

GENERAL CATEGORY

Option

Description

Command Line

Treat char as unsigned

Select to make ‘char’ types unsigned (0-256) instead of the default
signed (-128 to 127).

-k

Enable integer
promotions

Select to enable integer promotions (ISO-mandated arithmetic
performed at int precision or greater.)

-oi

Enable verbose output

Display all compiler outputs.

--verbose

Default storage class

Select the storage class, either auto (ANSI standard), static (ANSI
standard) or overlay (non-extended mode).

-scclass

Diagnostics level

Select to display errors only; errors and warnings; or errors, warnings
and messages. These will be shown in the Output window.

-wvalue

Preprocessor macro
definitions

Add macro directive definitions.

-Dmacro

Include directories

Enter a path to header (*.h) files.

-I"inc"

TABLE 1-12:

OPTIMIZATION CATEGORY

Option

Description

Command Line

Optimizations

Select to:
Enable/Disable all optimizations below.
Select optimizations that are Debug Friendly.
Customize the optimizations from the selections below.

-Olevel

Enable all optimizations

View whether all options enabled.

N/A

Enable duplicate string
merging

Take two or more identical literal strings and combine them into a single -Om
string table entry with a single instance of the raw data stored in
program memory.

Enable banking optimizer Remove MOVLB instructions in instances where it can be determined
that the Bank Select register already contains the correct value.

-On

Enable unreachable code Attempt to remove any code that can be provably demonstrated to not
removal
execute during normal program flow.

-Ou

Enable code
straightening

Attempt to reorder code sequences so that they appear in the order in
which they will be executed.

-Os

Enable tail merging

Attempt to combine multiple sequences of identical instructions into a
single sequence.

-Ot

Enable branch
optimization

Optimize branching. Some of the branch optimizations save program
space, while others may expose unreachable code.

-Ob

Enable WREG tracking

Remove MOVLW instructions in instances where it can be determined
that the Working register already contains the correct value.

-Ow

Enable copy propagation Replace uses of x with uses of y for x  y, as long as intervening
instructions have not changed the value of either x or y. This
optimization by itself does not save any instructions, but enables dead
code removal.

-Op

Enable redundant store
elimination

Remove redundant assignments of the form x  y when the
assignment appears multiple times in an instruction sequence and the
intervening code has not changed the value of x or y.

-Or

Enable dead code
removal

Remove dead code, i.e., values computed in a function which are not
used on any path to the function's exit or instructions which compute
only dead values.

-Od

Enable procedural
abstraction

Reduce the size of the generated code by creating a procedure
-Opa
containing the repeated code and replacing the copies with a call to the
procedure.

Procedural Abstraction
passes

For “Enable All” and “Custom” optimizations, set the desired number of -pa=pass
passes for procedural abstraction.

 1994-2013 Microchip Technology Inc.

DS33014L-page 25

Assembler/Linker/Librarian User’s Guide
TABLE 1-13:

ADDITIONAL CONTROLS

Option

Description

Additional Options

Enter additional command-line options. See the tool documentation for more options.

Option Description

Click on option text to see more information in this tab, if available.

Generated Command
Line

For selectable options, click this tab to see the equivalent command line option.

DS33014L-page 26

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB X IDE
PROJECT EXAMPLE
In this example, you will create an MPLAB X IDE project with multiple assembly files.
Therefore, you will need to use the MPASM assembler and the MPLINK linker to create
the final output executable (.hex) file.
•
•
•
•
•
•
•

Run the Project Wizard
Add Files to the Project
Set Build Options
Build the Project
Build Errors
Output Files
Further Development

Run the Project Wizard
In MPLAB X IDE, select File>New Project to launch the wizard.
1. Choose Project: Select “Embedded” for the category and “C/ASM Standalone
Project” for the project. Click Next> to continue.
2. Select Device: Select the PIC16F877. Click Next> to continue.
3. Select Header: There is no header for this device so this is skipped.
4. Select Tool: Choose a development tool from the list. Tool support for the
selected device is shown as a colored circle next to the tool. Mouse over the circle to see the support as text. Click Next> to continue.
5. Select Compiler: Choose a version of the MPASMX assembler. Click Next> to
continue.
6. Select Project Name and Folder: Enter a project name, such as
MyAsmProject. Then select a location for the project folder. Click Finish to
complete the project creation and setup.
Once the Project Wizard has completed, the Project window should contain the project
tree. For more on projects, see the MPLAB X IDE documentation.
FIGURE 3:

 1994-2013 Microchip Technology Inc.

NEW PROJECT TREE

DS33014L-page 27

Assembler/Linker/Librarian User’s Guide
Add Files to the Project
Right click on the “Source Files” folder in the project tree. Select “New>Other” to open
the File wizard.
1. Choose File Type: Expand “Microchip Embedded” to see available file types.
Click “MPASM assembler” and select “main.asm”. Click Next> to continue.
2. Name and Location: Enter the name for the new file, in this case
example.asm. The location is the current project by default. Leave this for now.
Click Finish to create file.
Repeat the above steps to add another file, example2.asm, to the project. When you
are done, the project tree should now look as in Figure 4. The code for each file follows.
FIGURE 4:

PROJECT TREE WITH SOURCE FILES

example.asm
; File: example.asm
; This is the main file in the MPASM assembler/MPLINK linker example
; Use with example2.asm
#include p16f877.inc
PROG CODE

; Set the start of code from 16f877.lkr script

main
global main
nop
goto
main

;
;
;
;

Min code entry called from example2.asm
Define as global so can be used in example2.asm
Main does nothing -- Put your code here
Our sample "main" is just an infinite loop

service
; Interrupt routine, called from example2.asm
global service ; Define as global so can be used in example2.asm
nop
; Interrupt code would go here
nop
retfie
IDLOCS CODE
dw 0x0102
dw 0x0304

; ID location data, address is in 16f877.lkr

CONBITS CODE

; Set config bits from defines in p16f877.inc
; Config address for device programmer is
; in 16f877.lkr
dw _LP_OSC & _PWRTE_OFF & _WDT_OFF & _CP_OFF
end

DS33014L-page 28

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB X IDE
example2.asm
; File: example2.asm
; This is the second file in the MPASM assembler/MPLINK linker example
; Use with example.asm
#include p16f877.inc
extern main, service ; These routines are in Example.asm
STARTUP CODE

goto main
nop
nop
nop
goto service

; This area is defined in 16f877.lkr,
; the linker script
; Jump to main code defined in example.asm
; Pad out so interrupt service routine gets
; put at address 0x0004.
; Points to interrupt service routine

end

Set Build Options
Select File>Project Properties or right click on the project name and select “Properties”
to open the Project Properties dialog.
1. Under “default>MPASMX”, select “MPASMX”.
2. Select “General” from the “Option Categories”. Ensure that the “Default Radix” is
“Hex”.
3. Select “Output” from the “Option Categories”. Ensure that the “Diagnostics level”
is set to “Errors Only”. Then enter a file name for a “Cross-reference file”, i.e.,
example.xrf.
4. Under “default>MPASMX”, select “MPLINK”.
5. Ensure that the “Hex File Format” is set to “INHX32”. Then enter a file name to
“Generate map file”, i.e., example.map.
6. Click OK on the bottom of the dialog to accept the build options and close the
dialog.

 1994-2013 Microchip Technology Inc.

DS33014L-page 29

Assembler/Linker/Librarian User’s Guide
Build the Project
Right-click on the project name, “MyASMProject”, in the project tree and select “Build”
from the pop-up menu.
The Output window should appear at the end of the build and display the build results.
FIGURE 5:

OUTPUT WINDOW - BUILD RESULTS

Build Errors
If the build did not complete successfully, check these items:
1. Review the previous steps in this example. Make sure you have set up the language tools correctly and have all the correct project files and build options.
2. If you modified the sample source code, examine the Build results in the Output
window for syntax errors in the source code. If you find any, correct the error, and
then try to build again. Some errors provide links to go to the source code line
that contains that error.

Output Files
View the project output files by opening the files in MPLAB X IDE.
1. Select File>Open File. In the Open dialog, find the project directory.
2. Under “Files of type” select “All Files” to see all project files.
3. Select “example.xrf”. Click Open to view the assembler cross-reference file in an
MPLAB X IDE editor window. For more on this file, see the MPASM assembler
documentation, Section 1.7.6 “Cross Reference File (.xrf)”.
4. Select File>Open File. In the Open dialog, select “example.map”. Click Open to
view the linker map file in an MPLAB X IDE editor window. For more on this file,
see the MPLINK linker documentation, Section 9.7.7 “Map File (.map)”.
5. Select File>Open File. In the Open dialog, go to the build>default>production
directory. Select “example.lst”. Click Open to view the linker listing file in an
MPLAB X IDE editor window. When MPASM assembler is used with MPLINK
linker, this listing file may be generated. For more on this file, see the Utilities documentation, Section 18.3 “Utilities Operation”.
6. Select File>Open File. In the Open dialog, return to the project directory and then
go to the dist>default>production directory. Notice that there is only one hex file,
“example.hex”. This is the primary output file, used by various debug tools. Click
Open to view the hex file in an MPLAB X IDE editor window. For more on this
file, see the Utilities documentation, Section 18.3 “Utilities Operation”.
For this example, we used a multi-file project which requires the use of the linker
(relocatable code). But if you have a project with one assembly file, you could use only
the assembler (absolute code). The assembler is capable of generating its own list and
hex file.

DS33014L-page 30

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB X IDE
Further Development
Usually, your application code will contain errors and not work the first time. Therefore,
you will need a debug tool to help you develop your code. Using the output files
previously discussed, several debug tools exist that work with MPLAB X IDE to help
you do this. You may choose from simulators, in-circuit emulators or in-circuit
debuggers, either manufactured by Microchip Technology or third-party developers.
Please see the documentation for these tools to learn how they can help you. When
debugging, you will use Debug>Debug Project to run and debug your code. Please see
MPLAB X IDE documenation for more information.
Once you have developed your code, you will want to program it into a device. Again,
there are several programmers that work with MPLAB X IDE to help you do this. Please
see the documentation for these tools to see how they can help you. When
programming, you will use “Program Target Project” button on the debug toolbar.
Please see MPLAB X IDE documenation concerning this control.
MPLAB C18 example code that may be used to create a C code project may be found
in the compiler install example subdirectory. See also the MPLAB C Compiler for
PIC18 MCUs User’s Guide (DS51288).

 1994-2013 Microchip Technology Inc.

DS33014L-page 31

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 32

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
PIC1X MCU Language Tools and MPLAB IDE v8
INTRODUCTION
The MPASM assembler, the MPLINK object linker and the MPLIB object librarian are
typically used together under MPLAB IDE to provide GUI development of application
code for PIC1X MCU devices (PIC10/12/16/18 MCUs). The operation of these 8-bit
language tools with MPLAB IDE is discussed here.
Additionally, the MPLAB C Compiler for PIC18 MCUs (MPLAB C18) may be used with
the above tools. For more on this compiler, see the Microchip website
(http://www.microchip.com) for additional information and documentation.
Topics covered in this chapter:
•
•
•
•
•

MPLAB IDE and Tools Installation
MPLAB IDE Setup
MPLAB IDE Projects
Project Setup
Project Example

MPLAB IDE AND TOOLS INSTALLATION
MPLAB IDE includes the MPASM Toolsuite which consists of the MPASM assembler,
MPLINK linker, MPLIB librarian and other 8-bit utilities. Also, MPLAB IDE may be used
with the C18 Toolsuite that consists of the MPLAB C18 C compiler and compiler
versions of tools in the MPASM Toolsuite.

MPASM Toolsuite Installation
In order to use the PIC language tools with MPLAB IDE, you must first install MPLAB
IDE. The latest version of this free software is available at our website
(http://www.microchip.com) or from any sales office (back cover). When you install
MPLAB IDE, you will be installing the MPASM assembler, the MPLINK object linker and
the MPLIB object librarian as well.
The language tools will be installed, by default, in the directory:
• C:\Program Files\Microchip\MPASM Suite
The executables for each tool will be:
•
•
•
•

MPASM Assembler - mpasmwin.exe
MPLINK Object Linker - mplink.exe
MPLIB Object Librarian - mplib.exe
Other Utilities

All device include (.inc) files are also in this directory. For more on these files, see
MPASM assembler documentation.
All device linker script (.lkr) files are in the LKR subdirectory. For more on these files,
see MPLINK object linker documentation.
Code examples and template files are included in the Template subdirectory.
Template files are provided for absolute code (Code) and relocatable code (Object)
development. Code examples are also included in the Example subdirectory.

 1994-2013 Microchip Technology Inc.

DS33014L-page 33

Assembler/Linker/Librarian User’s Guide
C18 Toolsuite Installation
The MPLAB C18 compiler and related tools must be acquired from Microchip
(standard, lite and evaluation versions available). The install includes the MPLAB C18
C compiler and compiler versions of tools in the MPASM Toolsuite.
The language tools will be installed, by default, in the directory:
• C:\Program Files\Microchip\mplabc18\version
where version is the version of the compiler.
The executables for each tool will be:
•
•
•
•
•

MPLAB C18 C Compiler - bin\mcc18.exe
MPASM Assembler - mpasm\mpasmwin.exe
MPLINK Object Linker - bin\mplink.exe
MPLIB Object Librarian - bin\mplib.exe
Other Utilities - bin subdirectory

All device header (.h) files are in the h subdirectory. For more on these files, see
MPLAB C18 documentation.
All device include (.inc) files are in the mpasm subdirectory. For more on these files,
see MPASM assembler documentation.
All device linker script (.lkr) files are in the bin\LKR subdirectory. For more on these
files, see MPLINK object linker documentation.
All device library (.lib) files and precompiled start-up code (.o) are in the lib
subdirectory. For more on these files, see MPLAB C18 libraries documentation.
Code examples are also included in the example subdirectory.

DS33014L-page 34

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB IDE v8
MPLAB IDE SETUP
Once MPLAB IDE is installed on your PC, check the settings below to ensure that the
language tools are properly recognized under MPLAB IDE.
1. From the MPLAB IDE menu bar, select Project>Set Language Tool Locations to
open a dialog to set/check language tool executable location.
FIGURE 1:

SET LANGUAGE TOOL LOCATIONS

2. In the dialog, under “Registered Tools”, select “Microchip MPASM Toolsuite”.
Click the “+” to expand.
3. Select “Executables”. Click the “+” to expand.
4. Select “MPASM Assembler (mpasmwin.exe)”. Under “Location”, a path to the
executable file should be displayed. If no path is displayed, enter one or browse
to the location of this file. The default location is listed in “MPASM Toolsuite
Installation”.
5. Select “MPLINK Object Linker (mplink.exe)”. Under “Location”, a path to the
executable file should be displayed. If no path is displayed, enter one or browse
to the location of this file. The default location is listed in “MPASM Toolsuite
Installation”.
6. Select “MPLIB Object Librarian (mplib.exe)”. Under “Location”, a path to the
executable file should be displayed. If no path is displayed, enter one or browse
to the location of this file. The default location is listed in “MPASM Toolsuite
Installation”.
7. For the optional MPLAB C18 C compiler, select “Microchip C18 Toolsuite” and
expand “Executables”. Select “MPLAB C18 C Compiler (mcc18.exe)” and
check the install path. Ensure the other tools in this toolsuite point to the MPLAB
C18 installation subdirectories and not the directories for the “Microchip MPASM
Toolsuite”. The default location is listed in “C18 Toolsuite Installation”.
8. Click OK.

 1994-2013 Microchip Technology Inc.

DS33014L-page 35

Assembler/Linker/Librarian User’s Guide
MPLAB IDE PROJECTS
A project in MPLAB IDE is a group of files needed to build an application, along with
their associations to various build tools. Below is a generic MPLAB IDE project.
FIGURE 2:

PROJECT RELATIONSHIPS

MPLAB IDE Project

prog.lst

source
files

prog.asm

main.c

MPASM
assembler

MPLAB C18

prog.o

main.o

ASSEMBLER/
COMPILER

list and object
files

precomp.o

LIBRARIAN &
library file

MPLIB librarian

math.lib

MPLINK linker

prog.cof

device.lkr

prog.map

LINKER &
linker
script file(1)

LINKER output
files

MP2HEX
Utility &
output file
prog.hex

SIMULATORS
EMULATORS
DEBUGGERS
PROGRAMMERS
(1)The

linker can choose the correct
linker script file for your project.

DS33014L-page 36

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB IDE v8
In this MPLAB IDE project, an assembly source file (prog.asm) is shown with its
associated assembler (MPASM assembler). MPLAB IDE will use this information to
generate the object file prog.o for input into the MPLINK object linker. For more
information on the assembler, see the MPASM assembler documentation.
The C source file main.c is also shown with its associated MPLAB C18 C compiler.
MPLAB IDE will use this information to generate an object file (main.o) for input into
the MPLINK object linker. For more information on the compiler, see the MPLAB C
Compiler for PIC18 MCUs User’s Guide (DS51288).
In addition, precompiled object files (precomp.o) may be included in a project, with no
associated tool required. MPLAB C18 requires the inclusion of a precompiled standard
code module c018i.o, for example. For more information on available Microchip
precompiled object files, see the MPLAB C18 C compiler documentation.
Some library files (math.lib) are available with the compiler. Others may be built
using the librarian tool (MPLIB object librarian). For more information on the librarian,
see the MPLIB librarian documentation. For more information on available Microchip
libraries, see the MPLAB C18 C compiler documentation.
The object files, along with library files, are used to generate the project output files via
the linker (MPLINK object linker). Depending on your project, you may or may not need
to add a linker script file (device.lkr). For more information on using linker script files
and the linker, see the MPLINK linker documentation.
The main output file generated by the MPLINK linker is the COF file (prog.cof). The
linker then uses the utility MP2HEX to generate the Hex file (prog.hex), used by
simulators, emulators, debuggers and programmers. For more information on linker
output files, see the MPLINK linker documentation. For more information on utilities,
see the related documentation.
For more on projects, and related workspaces, see MPLAB IDE documentation.

 1994-2013 Microchip Technology Inc.

DS33014L-page 37

Assembler/Linker/Librarian User’s Guide
PROJECT SETUP
To set up an MPLAB IDE project for the first time, it is advisable to use the built-in
Project Wizard (Project>Project Wizard.) In this wizard, you will be able to select a
language toolsuite that uses MPASM assembler, e.g., the Microchip MPASM Toolsuite.
For more on the wizard, and MPLAB IDE projects, see MPLAB IDE documentation.
When a project is set up, set up properties of the tools in MPLAB IDE.
1. From the MPLAB IDE menu bar, select Project>Build Options>Project to open a
dialog to set/check project build options.
Note:

MPASM assembler does not recognize include path information
specified in MPLAB IDE.

2. Click on the tool tab to modify tool settings.
- Build Options Dialog, MPASM Assembler Tab
- Build Options Dialog, MPLAB C17 Tab (If Installed)
- Build Options Dialog, MPLAB C18 Tab (If Installed)
- Build Options Dialog, MPLINK Linker Tab
- Build Options Dialog, MPASM/C17/C18 Suite Tab
3. Perform additional setup as required.
- MPLAB C18: Setup for PIC18 Extended Instruction Set Use

Build Options Dialog, MPASM Assembler Tab
Select a category, and then set up assembler options. For additional options, see
MPASM assembler documentation, Chapter 2. “Assembler Interfaces”.
General Category
Generate Command Line
Disable case sensitivity

The assembler accepts upper- and lower-case letters equally.
Note: Disabling case sensitivity will make all labels uppercase.

Extended mode

Enable PIC18F extended instruction support.

Default Radix

Set the default radix, either Hexadecimal, Decimal or Octal.

Macro Definitions

Add macro directive definitions.

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

Enter options in a command-line (non-GUI) format.

Output Category
Generate Command Line
Diagnostics level

Select to display errors only; errors and warnings; or errors,
warnings and messages. These will be shown in the Output
window.

Generate
cross-reference file

Create an cross-reference file. A cross-reference file contains a
listing of all symbols used in the assembly code.

Hex file format (for
single-file assemblies)

When assembling a single file, the assembler may be used to
generate a hex file. Choose the format here.
When assembling multiple files, the assembler generates object
files which must be linked with the linker to generate a hex file.
Choose the hex file format for the linker in this case.

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

DS33014L-page 38

Enter options in a command-line (non-GUI) format.

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB IDE v8
Build Options Dialog, MPLAB C17 Tab (If Installed)
Although the MPLAB C17 C compiler works with MPLAB IDE, it is no longer sold or
supported. See the Microchip website (www.microchip.com) for details.
Note:

PIC17C MCUs are end-of-life devices. Consider migrating to PIC18X MCU
devices.

A subset of command-line options may be specified in MPLAB IDE in the Build Options
dialog, MPLAB C17 tab. Select a category, and then set up compiler options.
General Category
Generate Command Line
Diagnostics level

Select to display errors only; errors and warnings; or errors,
warnings and messages. These will be shown in the Output
window.

Default storage class

Select the storage class, either ANSI-standard auto or static.

Macro Definitions

Add macro directive definitions.

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

Enter options in a command-line (non-GUI) format.

Memory Model Category
Generate Command Line
Small

near rom - program memory 8K,
near ram - data memory 256

Medium

far rom - program memory > 8K,
near ram - data memory  256

Compact

near rom - program memory  8K,
far ram - data memory > 256

Large

far rom - program memory > 8K,
far ram - data memory > 256

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

Enter options in a command-line (non-GUI) format.

Optimization Category
Generate Command Line
Bank Selection Optimiza- Select the level of bank selection optimization. Removes MOVLB
tion
instruction in instances where it can be determined that the Bank
Select register already contains the correct value.
Level 0 - None.
Level 1 - Equivalent to -On1.
Level 2 - Equivalent to -On2.
Other Optimizations

Select individual optimizations.

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

 1994-2013 Microchip Technology Inc.

Enter options in a command-line (non-GUI) format.

DS33014L-page 39

Assembler/Linker/Librarian User’s Guide
Build Options Dialog, MPLAB C18 Tab (If Installed)
Although the MPLAB C18 C compiler works with MPLAB IDE, it must be acquired
separately. The full version may be purchased, or a student (limited-feature) version
may be downloaded for free. See the Microchip website (www.microchip.com) for
details. This compiler supports PIC18X MCU devices.
A subset of command-line options may be specified in MPLAB IDE in the Build Options
dialog, MPLAB C18 tab. Select a category, and then set up compiler options. For
additional options, see the MPLAB C Compiler for PIC18 MCUs User’s Guide
(DS51288), also available on the Microchip website.
General Category
Generate Command Line
Diagnostics level

Select to display errors only; errors and warnings; or errors,
warnings and messages. These will be shown in the Output
window.

Default storage class

Select the storage class, either auto (ANSI standard), static (ANSI
standard) or overlay (non-extended mode).

Enable integer promotions

Select to enable integer promotions (ISO-mandated arithmetic performed at int precision or greater.)

Treat ‘char’ as unsigned

Select to make ‘char’ types unsigned (0-256) instead of the default
signed (-128 to 127).

Extended mode

See MPASM/C17/C18 Suite tab.

Macro Definitions

Add macro directive definitions.

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

Enter options in a command-line (non-GUI) format.

Memory Model Category
Generate Command Line
Code Model

Select a code (program memory/ROM) model. Choose from small
(64K bytes) or large (>64K bytes).

Data Model

Select a data (data memory/RAM) model. Choose from large (all
RAM banks) or small (access RAM only).

Stack Model

Select a stack model. Choose from single bank or multiple bank.

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

Enter options in a command-line (non-GUI) format.

Optimization Category
Generate Command Line
Disable

Disable optimization.

Debug

Enable optimizations for debugging.

Enable All

Enable all optimizations.

Custom

Enable optimization and select individual optimizations.

Procedural Abstraction
passes

For “Enable All” and “Custom” optimizations, set the desired number of passes for procedural abstraction.

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

DS33014L-page 40

Enter options in a command-line (non-GUI) format.

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB IDE v8
Build Options Dialog, MPLINK Linker Tab
Select a category, and then set up linker options. For additional options, see MPLINK
object linker documentation, Chapter 10. “Linker Interfaces”.
All Options Category
Generate Command Line
Hex file format

Choose the linker hex file format or suppress output of the hex file.

Generate map file

Create a map file. A map file provides information on the

absolute location of source code symbols in the final output.
It also provides information on memory use, indicating
used/unused memory.

Output file root

Enter a root directory for saving output files.

Restore Defaults

Restore tab default settings.

Use Alternate Settings
Text Box

Enter options in a command-line (non-GUI) format.

Build Options Dialog, MPASM/C17/C18 Suite Tab
Select a category, and then set up output build options.
All Options Category
Generate Command Line
Library Output
Build normal target
(invoke MPLINK)

The files in the project will be built for normal output using the
MPLINK linker (hex file, etc.)
To set linker options, see Build Options Dialog, MPLINK Linker
Tab.

Build library target
(invoke MPLIB)

The files in the project will be built into a library using the MPLIB
librarian (lib file.)
Check “Build generic library” to build a library with the
generic-device instead of the selected device. This means the
library can be used with any device and not just the one currently
selected.
For more on libraries, see MPLIB object librarian documentation,
Chapter 16. “Librarian Interfaces”.

Single File Assembly Projects
Ask me

Pop up a dialog to ask me, when a project contains a single file,
whether I want to generate absolute or relocatable code.

Generate absolute code

Always generate absolute code, i.e., code generated by the
assembler not requiring a linker.

Generate relocatable
code

Always generate relocatable code, i.e., code generated using a
linker.

Other Controls
Extended mode

Build in extended mode. The selected device must support
extended mode and the correct configuration bit must be enabled.
See “MPLAB C18: Setup for PIC18 Extended Instruction Set Use”.

Generate stack analysis
report

Generate a stack analysis report for use with third-party application
“Understand,” from Scientific Toolworks, Inc. See their web site at
www.scitools.com for more information.
This option is only supported on devices that support extended
mode. The checkbox for Extended mode must be checked as well.
(See the previous row in this table.)

 1994-2013 Microchip Technology Inc.

DS33014L-page 41

Assembler/Linker/Librarian User’s Guide
MPLAB C18: Setup for PIC18 Extended Instruction Set Use
To use the PIC18 MCU Extended Instruction set in your MPLAB C18 project, do the
following:
• Enable “Extended Instruction Set” in the configuration bits.
- In code, use CONFIG XINST=ON.
- In the Configurations Bits window, under XINST select “Enabled”.
• Select Project>Build Options>Project. On the MPASM/C17/C18 Suite tab, check
the “Extended Mode” checkbox.
For a list of available instructions in the Extended Instruction set, see
Section A.9 “PIC18 Device Extended Instruction Set”.

DS33014L-page 42

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB IDE v8
PROJECT EXAMPLE
In this example, you will create an MPLAB IDE project with multiple assembly files.
Therefore, you will need to use the MPASM assembler and the MPLINK linker to create
the final output executable (.hex) file.
•
•
•
•
•
•

Run the Project Wizard
Set Build Options
Build the Project
Build Errors
Output Files
Further Development

Run the Project Wizard
In MPLAB IDE, select Project>Project Wizard to launch the wizard. Click Next> at the
Welcome screen.
1. Select PIC16F84A as the Device. Click Next> to continue.
2. Set up the language tools, if you haven’t already. Refer to “MPLAB IDE Setup”.
Click Next> to continue.
3. Enter “Example” for the name of the project. Then Browse to select a location for
your project. Click Next> to continue.
4. Add files to the project. In the file listing box on the left of the dialog, find the
following directory:
C:\Program Files\Microchip\MPASM Suite\Example
Select Example.asm and Example2.asm. Click Add>> to add these files to the
project. Click Next> to continue.
5. Review the summary of information. If anything is in error, use Build Options>Project to open the Build Options dialog.
1. Click on the MPASM Assembler tab. For “Categories: General”, check that the
“Default Radix” is set to “Hexadecimal”. For “Categories: Output”, check that the
“Diagnostics level” includes all errors, warnings and messages. Then check the
checkbox for “Generate cross-reference file”.
2. Click on the MPLINK Linker tab. For “Categories: (All Options)”, check that the
“Hex File Format” is set to “INHX32”. Then check the checkbox for “Generate
map file”.
3. Click on the MPASM/C17/C18 Suite tab. For “Categories: (All Options)”, check
that the “Build normal target (invoke MPLINK)” is selected.
4. Click OK on the bottom of the dialog to accept the build options and close the
dialog.
5. Select Project>Save Project to save the current configuration of the Example
project.

Build the Project
Select Project>Build All to build the project.
Note:

You also may right-click on the project name, “Example.mcp”, in the project
tree and select “Build All” from the pop-up menu.

The Output window should appear at the end of the build and display the build results.
FIGURE 4:

OUTPUT WINDOW - BUILD TAB

Build Errors
If the build did not complete successfully, check these items:
1. Review the previous steps in this example. Make sure you have set up the language tools correctly and have all the correct project files and build options.
2. If you modified the sample source code, examine the Build tab of the Output window for syntax errors in the source code. If you find any, double-click on the error
to go to the source code line that contains that error. Correct the error, and then
try to build again.

DS33014L-page 44

 1994-2013 Microchip Technology Inc.

PIC1X MCU Language Tools and MPLAB IDE v8
Output Files
View the project output files by opening the files in MPLAB IDE.
1. Select File>Open. In the Open dialog, find the project directory.
2. Under “Files of type” select “All files (*.*)” to see all project files.
3. Select “Example.xrf”. Click Open to view the assembler cross-reference file for
Example.asm in an MPLAB IDE editor window. For more on this file, see the
MPASM assembler documentation, Section 1.7.6 “Cross Reference File
(.xrf)”.
4. Repeat steps 1 and 2. Select “Example.map”. Click Open to view the linker map
file in an MPLAB IDE editor window. For more on this file, see the MPLINK linker
documentation, Section 9.7.7 “Map File (.map)”.
5. Repeat steps 1 and 2. Select “Example.lst”. Click Open to view the linker listing
file in an MPLAB IDE editor window. When MPASM assembler is used with
MPLINK linker, the listing file is generated by the linker. For more on this file, see
the MPLINK linker documentation, Section 9.7.6 “Listing File (.lst)”.
6. Repeat steps 1 and 2. Notice that there is only one hex file, “Example.hex”. This
is the primary output file, used by various debug tools. You do not view this file
for debugging; use View>Program Memory or View>Disassembly Listing.

Further Development
Usually, your application code will contain errors and not build the first time. Therefore,
you will need a debug tool to help you develop your code. Using the output files
previously discussed, several debug tools exist that work with MPLAB IDE to help you
do this. You may choose from simulators, in-circuit emulators or in-circuit debuggers,
either manufactured by Microchip Technology or third-party developers. Please see the
documentation for these tools to determine how they can help you. When debugging,
you will need to set the Build Configuration to “Debug”. Please see MPLAB IDE
documentation concerning this control.
Once you have developed your code, you will want to program it into a device. Again,
there are several programmers that work with MPLAB IDE to help you do this. Please
see the documentation for these tools to see how they can help you. When
programming, you will need to set the Build Configuration to “Release”. Please see
MPLAB IDE documentation concerning this control.
For more information on using MPLAB IDE, consult the on-line help that comes with
this application or download printable documents from our website.
MPLAB C18 example code that may be used to create a C code project may be found
in the MPLAB C Compiler for PIC18 MCUs User’s Guide (DS51288).

 1994-2013 Microchip Technology Inc.

DS33014L-page 45

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 46

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Part 1 – MPASM Assembler
Chapter 1. MPASM Assembler Overview ................................................................... 49
Chapter 2. Assembler Interfaces ................................................................................ 61
Chapter 3. Expression Syntax and Operation ........................................................... 65
Chapter 4. Directives ................................................................................................... 71
Chapter 5. Assembler Examples, Tips and Tricks .................................................. 169
Chapter 6. Relocatable Objects ................................................................................ 189
Chapter 7. Macro Language ...................................................................................... 201
Chapter 8. Errors, Warnings, Messages, and Limitations ...................................... 207

 1994-2013 Microchip Technology Inc.

DS33014L-page 47

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 48

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 1. MPASM Assembler Overview
1.1

INTRODUCTION
An overview of the MPASM assembler and its capabilities is presented.
Topics covered in this chapter:
•
•
•
•
•
•

1.2

MPASM Assembler Defined
How MPASM Assembler Helps You
Assembler Migration Path
Assembler Compatibility Issues
Assembler Operation
Assembler Input/Output Files

MPASM ASSEMBLER DEFINED
The MPASM assembler (the assembler) is a command-line or GUI application that
provides a platform for developing assembly language code for Microchip's PIC1X
microcontroller (MCU) families.
The assembler comes with and is used by MPLAB X IDE (mpasmx.exe) and MPLAB
IDE v8 (mpasmwin.exe). The MPLAB IDE v8 assembler is also available with the
MPLAB C Compiler for PIC18 MCUs (aka MPLAB C18). The assembler may also be
used in a stand-alone application (Windows OS only) or on the command line.
The MPASM assembler supports all PIC1X MCU devices, as well as memory and
KeeLoq® secure data products from Microchip Technology Inc. (Some memory and
KeeLoq devices were not supported in MPLAB IDE after v5.70.40.)

1.3

HOW MPASM ASSEMBLER HELPS YOU
The MPASM assembler provides a universal solution for developing assembly code for
all of Microchip's PIC1X MCUs. Notable features include:
•
•
•
•

1.4

MPLAB X IDE and MPLAB IDE v8 Compatibility
Windows/Command Line Interfaces
Rich Directive Language
Flexible Macro Language

ASSEMBLER MIGRATION PATH
Since the MPASM assembler is a universal assembler for all PIC1X MCU devices,
application code developed for the PIC16F877A can be translated into a program for
the PIC18F452. This may require changing the instruction mnemonics that are not the
same between the devices (assuming that register and peripheral usage were similar).
Also, configuration settings may be different. The __CONFIG syntax with one operand
is not recognized by PIC18 and PIC16F1XXX MCUs. The rest of the directive and
macro language will be the same.

 1994-2013 Microchip Technology Inc.

DS33014L-page 49

Assembler/Linker/Librarian User’s Guide
1.5

ASSEMBLER COMPATIBILITY ISSUES
The MPASM assembler is compatible with the MPLAB X IDE and MPLAB IDE v8
integrated development environments and all Microchip PIC1X MCU development
systems currently in production.
The MPASM assembler supports a clean and consistent method of specifying radix
(see Section 3.4 “Numeric Constants and Radix”). You are encouraged to develop
using the radix and other directive methods described within this document, even
though certain older syntaxes may be supported for compatibility reasons.

1.6

ASSEMBLER OPERATION
The MPASM assembler can be used in two ways:
• To generate absolute code that can be executed directly by a microcontroller.
• To generate relocatable code that can be linked with other separately assembled
or compiled modules.

1.6.1

Generating Absolute Code

Absolute code is the default output from the MPASM assembler. This process is shown
below.

code.asm

MPASM
assembler

code.hex

Programmer

MCU

When a source file is assembled in this manner, all variables and routines used in the
source file must be defined within that source file, or in files that have been explicitly
included by that source file. If assembly proceeds without errors, a hex file will be
generated, containing the executable machine code for the target device. This file can
then be used with a debugger to test code execution or with a device programmer to
program the microcontroller.

1.6.2

Generating Relocatable Code

The MPASM assembler also has the ability to generate a relocatable object module
that can be linked with other modules using Microchip's MPLINK linker to form the final
executable code. This method is very useful for creating reusable modules.

DS33014L-page 50

 1994-2013 Microchip Technology Inc.

MPASM Assembler Overview

units.lib

main.asm

MPLINK linker

MPASM
assembler

main.hex

Programmer

MCU

main.o

more.asm

MPASM
assembler
more.o

Related modules can be grouped and stored together in a library using Microchip's
MPLIB librarian. Required libraries can be specified at link time, and only the routines
that are needed will be included in the final executable.

unit1.asm

MPASM
assembler

MPLIB
librarian

unit1.o

unit2.asm

MPASM
assembler

MPLIB
librarian

units.lib

unit2.o

unit3.asm

MPASM
assembler

MPLIB
librarian
unit3.o

Refer to Chapter 6. “Relocatable Objects” for more information on the differences
between absolute and relocatable object assembly.

 1994-2013 Microchip Technology Inc.

DS33014L-page 51

Assembler/Linker/Librarian User’s Guide
1.7

ASSEMBLER INPUT/OUTPUT FILES
These are the default file extensions used by the assembler and the associated utility
functions.
TABLE 1-1:

INPUT FILES

Source Code (.asm)

Default source file extension input to assembler.

Include File (.inc)

Include (header) file

TABLE 1-2:

OUTPUT FILES

Listing File (.lst)

Default output extension for listing files generated by
assembler.

Error File (.err)

Output extension from assembler for error files.

Hex File Formats (.hex, .hxl, .hxh)

Output extension from assembler for hex files.

Cross Reference File (.xrf)

Output extension from assembler for cross reference
files.

Object File (.o)

Output extension from assembler for object files.

1.7.1

Source Code (.asm)

Assembly is a programming language you may use to develop the source code for your
application. The source code file may be created using any ASCII text file editor.
Note:

Several example source code files are included free with the IDE.

Your source code should conform to the following basic guidelines.
Each line of the source file may contain up to four types of information:
•
•
•
•

Labels
Mnemonics, Directives and Macros
Operands
Comments

The order and position of these are important. For ease of debugging, it is
recommended that labels start in column one and mnemonics start in column two or
beyond. Operands follow the mnemonic. Comments may follow the operands,
mnemonics or labels, and can start in any column. The maximum column width is 255
characters.
White space or a colon must separate the label and the mnemonic, and white space
must separate the mnemonic and the operand(s). Multiple operands must be
separated by commas.
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.

DS33014L-page 52

 1994-2013 Microchip Technology Inc.

MPASM Assembler Overview
EXAMPLE 1-1:

ABSOLUTE MPASM ASSEMBLER SOURCE CODE (SHOWS
MULTIPLE OPERANDS)

Mnemonics
Directives
Labels Macros
Operands
|

Dest

|

|

Comments
|

list
#include

p=18f452
p18f452.inc

equ

0x0B

;Define constant

org

0x0000

;Reset vector

goto

Start

org

0x0020

movlw
movwf

0x0A
Dest

bcf
goto
end

Dest, 3
Start

;Begin program

Start

1.7.1.1

;This line uses 2 operands

LABELS

A label is used to represent a line or group of code, or a constant value. It is needed for
branching instructions (Example 1-1.)
Labels should start in column 1. They may be followed by a colon (:), space, tab or the
end of line. Labels must not begin with number.
Labels may be up to 32 characters long. By default they are case sensitive, but case
sensitivity may be overridden by a command-line option (/c or -c). If a colon is used
when defining a label, it is treated as a label operator and not part of the label itself.
1.7.1.2

MNEMONICS, DIRECTIVES AND MACROS

Mnemonics tell the assembler what machine instructions to assemble. For example,
addition (add), branches (goto) or moves (movwf). Unlike labels that you create
yourself, mnemonics are provided by the assembly language. Mnemonics are not case
sensitive.
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. Directives are not case sensitive.
Macros are user defined sets of instructions and directives that will be evaluated in-line
with the assembler source code whenever the macro is invoked.
Assembler instruction mnemonics, directives and macro calls should begin in column
two or greater. If there is a label on the same line, instructions must be separated from
that label by a colon, or by one or more spaces or tabs.
1.7.1.3

OPERANDS

Operands give information to the instruction on the data that should be used and the
storage location for the instruction.
Operands must be separated from mnemonics by one or more spaces, or tabs. Multiple
operands must be separated by commas.

 1994-2013 Microchip Technology Inc.

DS33014L-page 53

Assembler/Linker/Librarian User’s Guide
1.7.1.4

COMMENTS

Comments are text explaining the operation of a line or lines of code.
The MPASM assembler treats anything after a semicolon as a comment. All characters
following the semicolon are ignored through the end of the line. String constants
containing a semicolon are allowed and are not confused with comments.

1.7.2

Include File (.inc)

An assembler include, or header, file is any file containing valid assembly code.
Usually, the file contains device-specific register and bit assignments. This file may be
“included” in the code so that it may be reused by many programs.
As an example, to add the standard header file for the PIC18F452 device to your
assembly code, use:
#include p18f452.inc

Standard header files are located in:
C:\Program Files\Microchip\MPASM Suite

1.7.3

Listing File (.lst)

An MPASM assembler listing file provides a mapping of source code to object code. It
also provides a list of symbol values, memory usage information, and the number of
errors, warnings and messages generated.
This file may be viewed in MPLAB X IDE by:
1.
2.
3.
4.
5.

selecting File>Open File to launch the Open dialog
selecting “All Files” from the “Files of type” drop-down list
locating the desired list file
clicking on the list file name
clicking Open

This file may be viewed in MPLAB IDE v8 by:
1.
2.
3.
4.
5.

selecting File>Open to launch the Open dialog
selecting “List files (*.lst)” from the “Files of type” drop-down list
locating the desired list file
clicking on the list file name
clicking Open

Both the MPASM assembler and the MPLINK linker can generate listing files. For
information on the MPLINK linker listing file, see 9.7.6 “Listing File (.lst)”.
To prevent assembler list file generation, use the /l- or -l- option or use with
MPLINK linker. (The linker list file overwrites the assembler list file.) Set the size of tabs
in the list file using the /t or -t option.

DS33014L-page 54

 1994-2013 Microchip Technology Inc.

MPASM Assembler Overview
EXAMPLE 1-2:

ABSOLUTE MPASM ASSEMBLER LISTING FILE

The product name and version, the assembly date and time, and the page number
appear at the top of every page.
The first column contains the base address in memory where the code will be placed.
The second column displays the 32-bit value of any symbols created with the set, equ,
variable, constant, or cblock directives. The third column is reserved for the
machine instruction. This is the code that will be executed by the PIC1X MCU. The
fourth column lists the associated source file line number for this line. The remainder
of the line is reserved for the source code line that generated the machine code.
Errors, warnings, and messages are embedded between the source lines and pertain
to the following source line. Also, there is a summary at the end of the listing.
The symbol table lists all symbols defined in the program.
The memory usage map gives a graphical representation of memory usage. 'X' marks
a used location and '-' marks memory that is not used by this object. The map also
displays program memory usage. The memory map is not printed if an object file is
generated.
Note:

Due to page width restrictions, some comments have been shortened, indicated by “..” Also, some symbol table listings have been removed, indicated
by “:” See the standard header, p18f452.inc, for a complete list of
symbols.

 1994-2013 Microchip Technology Inc.

DS33014L-page 55

Assembler/Linker/Librarian User’s Guide
MPASM 03.70 Released
PAGE 1
LOC OBJECT CODE
VALUE

0000000B
000000
000000
000020
000020
000022
000024
000026

EF10 F000
0E0A
6E0B
960B
EF10 F000

SOURCE.ASM

4-5-2004

15:40:00

LINE SOURCE TEXT

00001
list p=18f452
00002
#include p18f452.inc
00001
LIST
00002 ; P18F452.INC Standard Header File, Version 1.4..
00845
LIST
00003 Dest equ
0x0B
00004
00005
org
0x0000
00006
goto
Start
00007
org
0x0020
00008 Start movlw
0x0A
00009
movwf Dest
00010
bcf
Dest, 3 ;This line uses 2 op..
00011
goto
Start
00012
end

MPASM 03.70 Released

SYMBOL TABLE
LABEL

SOURCE.ASM

4-5-2004

15:40:00

PAGE

2

SOURCE.ASM

4-5-2004

15:40:00

PAGE 12

VALUE

A
ACCESS
:
_XT_OSC_1H
__18F452

00000000
00000000
:
000000F9
00000001

MPASM 03.70 Released

MEMORY USAGE MAP ('X' = Used,

'-' = Unused)

0000 : XXXX------------ ---------------- XXXXXXXXXX------ ---------------All other memory blocks unused.
Program Memory Bytes Used:
14
Program Memory Bytes Free: 32754

Errors
:
Warnings :
Messages :

DS33014L-page 56

0
0 reported,
0 reported,

0 suppressed
0 suppressed

 1994-2013 Microchip Technology Inc.

MPASM Assembler Overview
1.7.4

Error File (.err)

The MPASM assembler, by default, generates an error file. This file can be useful when
debugging your code. The IDE will display the error information in the Output window.
The format of the messages in the error file is:
type[number] file line description

For example:
Error[113] C:\PROG.ASM 7 : Symbol not previously defined (start)

The error file may contain any number of MPASM assembler errors, warnings and
messages. For more on these, see Chapter 8. “Errors, Warnings, Messages, and
Limitations”.
To prevent error file generation, use the /e- or -e- option.

1.7.5

Hex File Formats (.hex, .hxl, .hxh)

The MPASM assembler and MPLINK linker are capable of producing ASCII text hex
files in different formats.
Format Name

Format Type

File Extension

Use

Intel Hex Format

INHX8M

.hex

8-bit core device programmers

Intel Split Hex Format

INHX8S

.hxl, .hxh

odd/even programmers

Intel Hex 32 Format

INHX32

.hex

16-bit core device programmers

This file format is useful for transferring PIC1X MCU series code to Microchip
programmers and third party PIC1X MCU programmers.
1.7.5.1

INTEL HEX FORMAT

This format produces one 8-bit hex file with a low byte, high byte combination. Since
each address can only contain 8 bits in this format, all addresses are doubled.
Each data record begins with a 9-character prefix and ends with a 2-character
checksum. Each record has the following format:
:BBAAAATTHHHH....HHHCC

where:
BB

A two digit hexadecimal byte count representing the number of data bytes that will
appear on the line.

AAAA

A four digit hexadecimal address representing the starting address of the data
record.

TT

A two digit record type that will always be '00' except for the end-of-file record, which
will be '01'.

HH

A two digit hexadecimal data byte, presented in low byte/high byte combinations.

CC

A two digit hexadecimal checksum that is the two's complement of the sum of all
preceding bytes in the record.

 1994-2013 Microchip Technology Inc.

DS33014L-page 57

Assembler/Linker/Librarian User’s Guide
EXAMPLE 1-3:

INHX8M

file_name.hex
:1000000000000000000000000000000000000000F0
:0400100000000000EC
:100032000000280040006800A800E800C80028016D
:100042006801A9018901EA01280208026A02BF02C5
:10005200E002E80228036803BF03E803C8030804B8
:1000620008040804030443050306E807E807FF0839
:06007200FF08FF08190A57
:00000001FF

1.7.5.2

INTEL SPLIT HEX FORMAT

The split 8-bit file format produces two output files: .hxl and .hxh. The format is the
same as the normal 8-bit format, except that the low bytes of the data word are stored
in the .hxl file, and the high bytes of the data word are stored in the .hxh file, and the
addresses are divided by two. This is used to program 16-bit words into pairs of 8-bit
EPROMs, one file for low byte, one file for high byte.
EXAMPLE 1-4:

INHX8S

file_name.hxl
:0A0000000000000000000000000000F6
:1000190000284068A8E8C82868A989EA28086ABFAA
:10002900E0E82868BFE8C8080808034303E8E8FFD0
:03003900FFFF19AD
:00000001FF
file_name.hxh
:0A0000000000000000000000000000F6
:1000190000000000000000010101010102020202CA
:100029000202030303030304040404050607070883
:0300390008080AAA
:00000001FF

1.7.5.3

INTEL HEX 32 FORMAT

The extended 32-bit address hex format is similar to the hex 8 format, except that the
extended linear address record is output also to establish the upper 16 bits of the data
address. This is mainly used for 16-bit core devices since their addressable program
memory exceeds 64 kbytes.
Each data record begins with a 9-character prefix and ends with a 2-character
checksum. Each record has the following format:
:BBAAAATTHHHH....HHHCC

where:

DS33014L-page 58

BB

A two digit hexadecimal byte count representing the number of data bytes that will
appear on the line.

AAAA

A four digit hexadecimal address representing the starting address of the data
record.

TT

A two digit record type:
00 - Data record
01 - End of File record
02 - Segment address record
04 - Linear address record

HH

A two digit hexadecimal data byte, presented in low byte/high byte
combinations.

CC

A two digit hexadecimal checksum that is the two's complement of the sum of all
preceding bytes in the record.

 1994-2013 Microchip Technology Inc.

MPASM Assembler Overview
1.7.6

Cross Reference File (.xrf)

A cross reference file contains a listing of all symbols used in the assembly code. The
file has the following format:
• The symbols are listed in the “Label” column, sorted by name.
• The “Type” column defines the type of symbol. A list of “Label Types” is provided
at the end of the file.
• The “File Name” column lists the names of the files that use the symbol.
• The “Source File References” column lists the line number of the corresponding
file in the “File Name” column where the symbol is defined/referenced. An asterisk
means a definition.
To prevent cross-reference file generation, use the /x- or -x- option.

1.7.7

Object File (.o)

The assembler creates a relocatable object file from source code. This object file does
not yet have addresses resolved and must be linked before it can be used as an
executable.
To generate a file that will execute after being programmed into a device, see
1.7.5 “Hex File Formats (.hex, .hxl, .hxh)”.
To prevent object file generation, use the /o- or -o- option.

 1994-2013 Microchip Technology Inc.

DS33014L-page 59

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 60

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 2. Assembler Interfaces
2.1

INTRODUCTION
There are several interfaces with which you may use the MPASM assembler,
depending on the assembler version. These interfaces are discussed here.
When MPLAB X IDE or MPLAB IDE v8 is installed, the MPASM assembler is also
installed. In addition, the assembler may be obtained with the MPLAB C Compiler for
PIC18 MCUs.
Topics covered in this chapter:
•
•
•
•

2.2

MPLAB X IDE Interface
MPLAB IDE v8 Interface
Windows Interface
Command Line Interface

MPLAB X IDE INTERFACE
The MPASM assembler is most commonly used with the MPLINK linker in an MPLAB
X IDE project to generate relocatable code. However, the assembler may be used in
MPLAB X IDE to generate absolute code (without the use of the MPLINK linker). For
more information on this use, see “PIC1X MCU Language Tools and MPLAB X IDE”.

2.3

MPLAB IDE V8 INTERFACE
The MPASM assembler is most commonly used with the MPLINK linker in an MPLAB
IDE project to generate relocatable code. For more information on this use,
see “PIC1X MCU Language Tools and MPLAB IDE v8”.
The assembler may also be used in MPLAB IDE to generate absolute code (without
the use of the MPLINK linker or MPLAB IDE project) by using the QuickBuild feature.
To do this:
1. From the MPLAB IDE menu bar, select Project>Set Language Tool Locations to
open a dialog to set/check language tool executable location.
2. In the dialog, under Registered Tools, select “Microchip MPASM Toolsuite”. Click
the “+” to expand.
3. Select Executables. Click the “+” to expand.
4. Select MPASM Assembler (mpasmwin.exe). Under Location, a path to the
mpasmwin.exe file should be displayed. If no path is displayed, enter one or
browse to the location of this file. By default, it is located at:
C:\Program Files\Microchip\MPASM Suite\mpasmwin.exe
5. Click OK.
6. From the MPLAB IDE menu bar, select Project>Quickbuild to assemble the
specified asm file using the MPASM assembler.

 1994-2013 Microchip Technology Inc.

DS33014L-page 61

Assembler/Linker/Librarian User’s Guide
2.4

WINDOWS INTERFACE
MPASM assembler for Windows provides a graphical interface for setting assembler
options. It is invoked by executing either mpasmx.exe (MPLAB X IDE) or
mpasmwin.exe (MPLAB IDE v8) in Windows Explorer, or from a command prompt.
FIGURE 2-1:

MPASM ASSEMBLER WINDOWS SHELL INTERFACE

Select a source file by typing in the name or using the Browse button. Set the various
options as described below. (Default options are read from the source file.) Then click
Assemble to assemble the source file.
Note:

When MPASM assembler is invoked through an IDE, this options screen is
not available. For MPLAB X IDE, use the project properties dialog
(File>Properties) to set options. For MPLAB IDE v8, use the MPASM
Assembler tab of the Build Options dialog in MPLAB IDE (Project>Build
Options>Project) to set options.

Option

DS33014L-page 62

Description

Radix

Override any source file radix settings.
Reference: Section 4.43 “list - Listing Options”,
Section 4.56 “radix - Specify Default Radix”,
Section 3.4 “Numeric Constants and Radix”

Warning Level

Override any source file message level settings.
Reference: Section 4.48 “messg - Create User Defined
Message”

Hex Output

Override any source file hex file format settings.
Reference: Section 1.7.5 “Hex File Formats (.hex, .hxl, .hxh)”

Generated Files

Enable/disable various output files.
Reference: Section 1.7 “Assembler Input/Output Files”

Case Sensitivity

Enable/disable case sensitivity. If enabled, the assembler will
distinguish between upper- and lower-case letters.

 1994-2013 Microchip Technology Inc.

Assembler Interfaces
Option

2.5

Description

Tab Size

Set the list file tab size.
Reference: Section 1.7.3 “Listing File (.lst)”

Macro Expansion

Override any source file macro expansion settings.
Reference: Section 4.32 “expand - Expand Macro Listing”

Processor

Override any source file processor settings.

Extended Mode

Enable PIC18F extended instruction support.

Extra Options

Any additional command-line options.
Reference: Section 2.5 “Command Line Interface”

Save Settings on Exit

Save these settings in mplab.ini. They will be used the next
time you run the assembler.

COMMAND LINE INTERFACE
MPASM assembler can be invoked through the command line interface (command
prompt). For the assembler included with MPLAB X IDE:
Windows OS: mpasmx [/option1.../optionN] filename
Linux OS and Mac OS: mpasmx [-option1...-optionN] filename
where
option refers to one of the command line options
filename is the file being assembled
For example, if test.asm exists in the current directory, it can be assembled with the
following command:
mpasmx /e /l test.asm

If the source filename is omitted, the appropriate shell interface is invoked, i.e., a
Windows OS interface is displayed, which includes a Help button.
Option (/ or -)

Default

Description

? or h

N/A

Display the assembler help screen.

ahex-format

INHX32*

Generate .hex output directly from assembler,
where hex-format is one of {INHX8M | INHX8S |
INHX32}.
See 1.7.5 “Hex File Formats (.hex, .hxl, .hxh)” for
more information.

c

On

Enable/Disable case sensitivity. If enabled, the
assembler will distiguish between upper- and
lower-case letters.

dlabel[=value]

N/A

Define a text string substitution, i.e., assign value to
label.

e[+|-|path|=CON]

On

Enable/Disable/Set Path for error file.
e
Enable
e+
Enable
eDisable
e path
Enable/specify path
e=CON
Enable to console; no file output
Overrides -q+ option
See Section 1.7.4 “Error File (.err)” for more
information.

* Default is dependent on processor selected.

 1994-2013 Microchip Technology Inc.

DS33014L-page 63

Assembler/Linker/Librarian User’s Guide
Option (/ or -)

Default

Description

l[+|-|path]

On

Enable/Disable/Set Path for list file
l
Enable
l+
Enable
lDisable
l path
Enable/specify path
See Section 1.7.3 “Listing File (.lst)” for more
information.

m[+|-]

On

Enable/Disable macro expansion.
See Section 4.32 “expand - Expand Macro
Listing” for more information.

o[+|-|path]

Off

Enable/Disable/Set Path for object file.
o
Enable
o+
Enable
oDisable
o path
Enable/specify path
See Section 1.7.7 “Object File (.o)” for more
information.

pprocessor_type

None

Set the processor type, where processor_type is
a PIC1X MCU device, e.g., PIC18F452.

q[+|-]

Off

Enable/Disable quiet mode (suppress screen
output.)

rradix

Hex

Defines default radix, where radix is one of {HEX |
DEC | OCT }.
See Section 4.43 “list - Listing Options” or
Section 4.56 “radix - Specify Default Radix” for
more information.

s

On

Show progress window while assembling. For use
only on the command line (not within MPLAB IDE).

t

8

Set the size of tabs in the list file.
See Section 1.7.3 “Listing File (.lst)” for more
information.

wvalue

0

Set message level, where value is one of {0|1|2}.
0
all messages
1
errors and warnings
2
errors only
See Section 4.48 “messg - Create User Defined
Message” for more information.

x[+|-|path]

Off

Enable/Disable/Set Path for cross reference file.
x
Enable
x+
Enable
xDisable
x path
Enable/specify path
See Section 1.7.6 “Cross Reference File (.xrf)” for
more information.

y[+|-]

Disabled

Enable/Disable extended instruction set.
y
Enable
y+
Enable
yDisable
Can only be enabled for processors which support
the extended instruction set and for the generic
processor PIC18CXXX. /y- overrides LIST
PE=type directive (see Section 4.43 “list Listing Options”.)

* Default is dependent on processor selected.

DS33014L-page 64

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 3. Expression Syntax and Operation
3.1

INTRODUCTION
Various expression formats, syntax, and operations used by MPASM assembler are
described here.
Topics covered in this chapter:
•
•
•
•

3.2

Text Strings
Reserved Words and Section Names
Numeric Constants and Radix
Arithmetic Operators and Precedence

TEXT STRINGS
A “string” is a sequence of any valid ASCII character (of the decimal range of 0 to 127)
enclosed by 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.
Strings may be of any length that will fit within a 255 column source line. If a matching
quote mark is found, the string ends. If none is found before the end of the line, the
string will end at the end of the line. While there is no direct provision for continuation
onto a second line, it is generally no problem to use a second dw directive for the next
line.
The dw directive will store the entire string into successive words. If a string has an odd
number of characters (bytes), the dw and data directives will pad the end of the string
with one byte of zero (00).
If a string is used as a literal operand, it must be exactly one character long, or an error
will occur.

 1994-2013 Microchip Technology Inc.

DS33014L-page 65

Assembler/Linker/Librarian User’s Guide
3.2.1

Escape Characters

The assembler accepts the ANSI ‘C’ escape sequences to represent certain special
control characters:
TABLE 3-1:

ANSI ‘C’ ESCAPE SEQUENCES

Escape
Character

Hex
Value

Description

\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

\'

Single quote (apostrophe)

27
22

\”

Double quote character

\0OO

Octal number (zero, Octal digit, Octal digit)

\xHH

Hexadecimal number

3.2.2

Code Examples

See the examples below for the object code generated by different statements
involving strings.
7465
6720
7574
696E
650A

7374
6F75
2073
6720

696E
7470
7472
6F6E

dw

#define
B061
7465
6720
7420
7574
696E

DS33014L-page 66

7374
6669
6F75
2073
6700

696E
7273
7470
7472

“testing output string one\n”

str “testing output string two”
movlw “a”
data “testing first output string”

 1994-2013 Microchip Technology Inc.

Expression Syntax and Operation
3.3

RESERVED WORDS AND SECTION NAMES
You may not use the following words for label, constant or variable names:
• Directives (see Chapter 4. “Directives”).
• Instructions (see Appendix A. “Instruction Sets”).
• The word “main” (when using the assembler with an IDE). Do not use a “main”
label that cannot be reached by a simple reset and run, for example, a data label
named “main” or a routine named “main” that will only be accessed under certain
conditions, as with an interrupt.
In addition, the assembler has the following reserved section names:
TABLE 3-2:

RESERVED SECTION NAMES

Section Name

3.4

Purpose

.access_ovr

Default section name for access_ovr directive.

.code

Default section name for code directive.

.idata
.idata_acs

Default section names for idata and idata_acs directives,
respectively.

.udata
.udata_acs
.udata_ovr
.udata_shr

Default section names for udata, udata_acs, udata_ovr and
udata_shr directives, respectively.

NUMERIC CONSTANTS AND RADIX
MPASM assembler supports the following radix forms for constants: hexadecimal,
decimal, octal, binary, and ASCII. The default radix is hexadecimal; the default radix
determines what value will be assigned to constants in the object file when a radix is
not explicitly specified by a base descriptor.
Note:

The radix for numeric constants can be made different from the default radix
specified with the directives radix or list r=. Also, allowable default
radices are limited to hexadecimal, decimal, and octal.

Constants can be optionally preceded by a plus or minus sign. If unsigned, the value is
assumed to be positive.
Note:

Intermediate values in constant expressions are treated as 32-bit unsigned
integers. Whenever an attempt is made to place a constant in a field for
which it is too large, a truncation warning will be issued.

 1994-2013 Microchip Technology Inc.

DS33014L-page 67

Assembler/Linker/Librarian User’s Guide
The following table presents the various radix specifications:
TABLE 4: RADIX SPECIFICATIONS - MPASM ASSEMBLER/MPLINK LINKER
Note

1.
2.
3.

4.

5.

DS33014L-page 68

Type

Syntax

Example

1

Binary

B’binary_digits’

B’00111001’

2

Octal

O’octal_digits’

O’777’

3

Decimal

D’digits’
.digits

D’100’
.100

4

Hexadecimal

H’hex_digits’
0xhex_digits

H’9f’
0x9f

5

ASCII

A’character’
’character’

A’C’
’C’

A binary integer is ‘b’ or ‘B’ followed by one or more of the binary digits ‘01’ in single
quotes.
An octal integer is ‘o’ or ‘O’ followed by one or more of the octal digits ‘01234567’ in
single quotes.
A decimal integer is ‘d’ or ‘D’ followed by one or more decimal digits ‘0123456789’ in
single quotes. Or, a decimal integer is ‘.’ followed by one or more decimal digits
‘0123456789’.
A hexadecimal integer is ‘h’ or ‘H’ followed by one or more hexadecimal digits
‘0123456789abcdefABCDEF’ in single quotes. Or, a hexadecimal integer is ‘0x’ or ‘0X’
followed by one or more hexadecimal digits ‘0123456789abcdefABCDEF’.
An ASCII character is ‘a’ or ‘A’ followed by one character in single quotes. Or, an ASCII
character is one character in single quotes.

 1994-2013 Microchip Technology Inc.

Expression Syntax and Operation
3.5

ARITHMETIC OPERATORS AND PRECEDENCE
Arithmetic operators may be used with directives and their variables as specified in the
table below.
Note:

These operators cannot be used with program variables. They are for use
with directives only.

The operator order in the table also corresponds to its precedence, where the first
operator has the highest precedence and the last operator has the lowest precedence.
Precedence refers to the order in which operators are executed in a code statement.
TABLE 3-1:
ARITHMETIC OPERATORS IN ORDER OF PRECEDENCE
Example

Operator
$

Current/Return program counter

goto $ + 3

(

Left Parenthesis

1 + (d * 4)

)

Right Parenthesis

(Length + 1) * 256

!

Item NOT (logical complement)

if ! (a == b)

-

Negation (2’s complement)

-1 * Length

~

Complement

flags = ~flags

low1

Return low byte of address

movlw low CTR_Table

high1

Return high byte of address

movlw high CTR_Table

upper1 Return upper byte of address

movlw upper CTR_Table

*

Multiply

a = b * c

/

Divide

a = b / c

%

Modulus

entry_len = tot_len % 16

+

Add

tot_len = entry_len * 8 + 1

-

Subtract

entry_len = (tot - 1) / 8

<<

Left shift

flags = flags << 1

>>

Right shift

flags = flags >> 1

>=

Greater or equal

if entry_idx >= num_entries

>

Greater than

if entry_idx > num_entries

<

Less than

if entry_idx < num_entries

<=

Less or equal

if entry_idx <= num_entries

==

Equal to

if entry_idx == num_entries

!=

Not equal to

if entry_idx != num_entries

&

Bitwise AND

flags = flags & ERROR_BIT

^

Bitwise exclusive OR

flags = flags ^ ERROR_BIT

|

Bitwise inclusive OR

flags = flags | ERROR_BIT

&&

Logical AND

if (len == 512) && (b == c)

||

Logical OR

if (len == 512) || (b == c)

=

Set equal to

entry_index = 0

+=

Add to, set equal

entry_index += 1

-=

Subtract, set equal

entry_index -= 1

*=

Multiply, set equal

entry_index *= entry_length

/=

Divide, set equal

entry_total /= entry_length

%=

Modulus, set equal

entry_index %= 8

<<=

Left shift, set equal

flags <<= 3

>>=

Right shift, set equal

flags >>= 3

&=

AND, set equal

flags &= ERROR_FLAG

 1994-2013 Microchip Technology Inc.

DS33014L-page 69

Assembler/Linker/Librarian User’s Guide
TABLE 3-1:

ARITHMETIC OPERATORS IN ORDER OF PRECEDENCE
Example

Operator
|=

Inclusive OR, set equal

flags |= ERROR_FLAG

^=

Exclusive OR, set equal

flags ^= ERROR_FLAG

++

Increment(2)

i ++

Decrement

-Note 1:

2:

DS33014L-page 70

(2)

i --

This precedence is the same for the low, high and upper operands which apply to
sections. See Section 6.4 “Low, High and Upper Operators” for more
information.
These operators can only be used on a line by themselves; they cannot be
embedded within other expression evaluations.

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 4. 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.
Note:

Directives are not instructions (movlw, btfss, goto, etc.). For instruction set
information, consult your device data sheet.

Many of the assembler directives have alternate names and formats. These may exist
to provide backward compatibility with previous assemblers from Microchip and to be
compatible with individual programming practices. If portable code is desired, it is
recommended that programs be written using the specifications contained here.
Note:

Although MPASM assembler is often used with MPLINK object linker,
MPASM assembler directives are not supported in MPLINK linker scripts.
See MPLINK object linker documentation for more information on linker
options to control listing and hex file output.

Information on individual directives includes syntax, description, usage, and related
directives, as well as simple and, in some cases, expanded examples of use. In most
cases, simple examples may be assembled and run by adding an end statement.
Expanded examples may be assembled and run as-is to give an demonstration of an
application using the directive(s).
Individual directives may be found alphabetically (in the following sections) or by type
(Section 4.2 “Directives by Type”).
Note:

4.2

Directives are not case-sensitive, e.g., cblock may be executed as
CBLOCK, cblock, Cblock, etc

DIRECTIVES BY TYPE
There are six basic types of directives provided by the assembler.
1.
2.
3.
4.
5.
6.

Control Directives
Conditional Assembly Directives
Data Directives
Listing Directives
Macro Directives
Object File Directives

 1994-2013 Microchip Technology Inc.

DS33014L-page 71

Assembler/Linker/Librarian User’s Guide
4.2.1

Control Directives

Control directives control how code is assembled.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•

#define - Define a Text Substitution Label .............................................. p. 98
#include - Include Additional Source File ............................................... p. 130
#undefine - Delete a Substitution Label.................................................. p. 162
bankisel - Generate Indirect Bank Selecting Code (PIC12/16 MCUs) ... p. 77
banksel - Generate Bank Selecting Code ............................................... p. 80
constant - Declare Symbol Constant ...................................................... p. 89
end - End Program Block........................................................................... p. 103
equ - Define an Assembler Constant......................................................... p. 105
org - Set Program Origin........................................................................... p. 141
pagesel - Generate Page Selecting Code (PIC10/12/16 MCUs)............. p. 144
pageselw - Generate Page Selecting Code Using WREG Commands
(PIC10/12/16 MCUs).................................................................................. p. 146
processor - Set Processor Type ............................................................. p. 147
radix - Specify Default Radix ................................................................... p. 148
set - Define an Assembler Variable .......................................................... p. 152
variable - Declare Symbol Variable ....................................................... p. 163

4.2.2

Conditional Assembly Directives

Conditional assembly directives permit sections of conditionally assembled code.
These are not run-time instructions like their C language counterparts. They define
which code is assembled, not how the code executes.
•
•
•
•
•
•
•

else - Begin Alternative Assembly Block to if Conditional ..................... p. 102
endif - End Conditional Assembly Block ................................................. p. 104
endw - End a while Loop ......................................................................... p. 105
if - Begin Conditionally Assembled Code Block....................................... p. 125
ifdef - Execute If Symbol Has Been Defined .......................................... p. 127
ifndef - Execute If Symbol Has Not Been Defined ................................. p. 129
while - Perform Loop While Condition is True ......................................... p. 165

4.2.3

Data Directives

Data directives control the allocation of memory and provide a way to refer to data
items symbolically, i.e., by meaningful names.
•
•
•
•
•
•
•
•
•
•
•
•
•

DS33014L-page 72

__badram - Identify Unimplemented RAM ................................................ p. 75
__badrom - Identify Unimplemented ROM................................................ p. 76
__config - Set Processor Configuration Bits........................................... p. 86
config - Set Processor Configuration Bits (PIC18 MCUs)....................... p. 88
__idlocs - Set Processor ID Locations ................................................... p. 123
__maxram - Define Maximum RAM Location ............................................ p. 136
__maxrom - Define Maximum ROM Location............................................ p. 137
cblock - Define a Block of Constants....................................................... p. 82
da - Store Strings in Program Memory (PIC12/16 MCUs) ......................... p. 90
data - Create Numeric and Text Data ....................................................... p. 92
db - Declare Data of One Byte................................................................... p. 94
de - Declare EEPROM Data Byte .............................................................. p. 96
dt - Define Table (PIC12/16 MCUs) .......................................................... p. 100

 1994-2013 Microchip Technology Inc.

Directives
•
•
•
•
•

dtm - Define Table (Extended PIC16 MCUs Only) ..................................... p. 100
dw - Declare Data of One Word .................................................................. p. 101
endc - End an Automatic Constant Block .................................................. p. 103
fill - Specify Program Memory Fill Value ................................................ p. 116
res - Reserve Memory............................................................................... p. 150

4.2.4

Listing Directives

Listing directives control the MPASM assembler listing file format. These directives
allow the specification of titles, pagination, and other listing control. Some listing
directives also control how code is assembled.
•
•
•
•
•
•
•
•
•

error - Issue an Error Message................................................................ p. 106
errorlevel - Set Message Level ............................................................p. 108
list - Listing Options ................................................................................p. 131
messg - Create User Defined Message ..................................................... p. 138
nolist - Turn off Listing Output ................................................................ p. 140
page - Insert Listing Page Eject ................................................................. p. 144
space - Insert Blank Listing Lines.............................................................. p. 153
subtitle - Specify Program Subtitle........................................................ p. 153
title - Specify Program Title.................................................................... p. 154

4.2.5

Macro Directives

Macro directives control the execution and data allocation within macro body
definitions.
•
•
•
•
•
•

endm - End a Macro Definition.................................................................... p. 104
exitm - Exit from a Macro.......................................................................... p. 111
expand - Expand Macro Listing ................................................................. p. 113
local - Declare Local Macro Variable....................................................... p. 132
macro - Declare Macro Definition .............................................................. p. 134
noexpand - Turn off Macro Expansion ......................................................p. 140

4.2.6

Object File Directives

Object file directives are used only when creating an object file.
• access_ovr - Begin an Object File Overlay Section in Access RAM (PIC18
MCUs)......................................................................................................... p. 74
• code - Begin an Object File Code Section ................................................. p. 84
• code_pack - Begin an Object File Packed Code Section (PIC18 MCUs). p. 85
• extern - Declare an Externally Defined Label .......................................... p. 114
• global - Export a Label ............................................................................ p. 119
• idata - Begin an Object File Initialized Data Section................................ p. 120
• idata_acs - Begin an Object File Initialized Data Section in Access RAM (PIC18
MCUs)......................................................................................................... p. 122
• udata - Begin an Object File Uninitialized Data Section ........................... p. 154
• udata_acs - Begin an Object File Access Uninitialized Data Section (PIC18
MCUs)......................................................................................................... p. 156
• udata_ovr - Begin an Object File Overlayed Uninitialized Data Section . p. 158
• udata_shr - Begin an Object File Shared Uninitialized Data Section (PIC12/16
MCUs)......................................................................................................... p. 160

 1994-2013 Microchip Technology Inc.

DS33014L-page 73

Assembler/Linker/Librarian User’s Guide
4.3

access_ovr - BEGIN AN OBJECT FILE OVERLAY SECTION IN ACCESS
RAM (PIC18 MCUs)
4.3.1

Syntax

[label] access_ovr [RAM_address]

4.3.2

Description

This directive declares the beginning of a section of overlay data in Access RAM. If
label is not specified, the section is named .access_ovr. The starting address is
initialized to the specified address or will be assigned at link time if no address is
specified. The space declared by this section is overlayed by all other access_ovr
sections of the same name. No code can be placed by the user in this segment.

4.3.3

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
access_ovr is similar to udata_acs and udata_ovr, except that it declares a
PIC18 Access-RAM, uninitialized-data section that can be overlayed with other overlay
access sections of the same name. Overlaying access sections allows you to reuse
access-bank data space.

4.3.4

See Also

extern global udata udata_ovr udata_acs

4.3.5

Simple Example

;The 2 identically-named sections are overlayed in PIC18 Access RAM.
;In this example, u16a is overlaid with memory locations used
;by ua8 and u8b. u16b is overlaid with memory locations used
;by u8c and u8d.

DS33014L-page 74

myaoscn
u8a:
u8b:
u8c:
u8d:

access_ovr
res 1
res 1
res 1
res 1

myaoscn
u16a:
u16b:

access_ovr
res 2
res 2

 1994-2013 Microchip Technology Inc.

Directives
4.4

__badram - IDENTIFY UNIMPLEMENTED RAM
Note:

4.4.1

badram is preceded by two underline characters.

Syntax

__badram expr[-expr][, expr[-expr]]

4.4.2

Description

The __maxram and __badram directives together flag accesses to unimplemented
registers. __badram defines the locations of invalid RAM addresses. This directive is
designed for use with the __maxram directive. A __maxram directive must precede
any __badram directive. Each expr must be less than or equal to the value specified
by __maxram. Once the __maxram directive is used, strict RAM address checking is
enabled, using the RAM map specified by __badram. To specify a range of invalid
locations, use the syntax minloc - maxloc.

4.4.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
__badram is not commonly used, as RAM and ROM details are handled by the include
files (*.inc) or linker script files (*.lkr).

4.4.4

See Also

__maxram

4.4.5

Simple Example

#include p16c622.inc
__maxram 0x0BF
__badram 0x07-0x09, 0x0D-0xE
__badram 0x87-0x89, 0x8D, 0x8F-0x9E
movwf 0x07 ; Generates invalid RAM warning
movwf 0x87 ; Generates invalid RAM warning
; and truncation message

 1994-2013 Microchip Technology Inc.

DS33014L-page 75

Assembler/Linker/Librarian User’s Guide
4.5

__badrom - IDENTIFY UNIMPLEMENTED ROM
Note:

4.5.1

badrom is preceded by two underline characters.

Syntax

__badrom expr[-expr][, expr[-expr]]

4.5.2

Description

The __maxrom and __badrom directives together flag accesses to unimplemented
registers. __badrom defines the locations of invalid ROM addresses. This directive is
designed for use with the __maxrom directive. A __maxrom directive must precede
any __badrom directive. Each expr must be less than or equal to the value specified
by __maxrom. Once the __maxrom directive is used, strict ROM address checking is
enabled, using the ROM map specified by __badrom. To specify a range of invalid
locations, use the syntax minloc - maxloc.
Specifically, a warning will be raised in the following circumstances:
• the target of a GOTO or CALL instruction is evaluated by the assembler to a
constant, and falls in a bad ROM region
• the target of an LGOTO or LCALL pseudo-op is evaluated by the assembler to a
constant, and falls in a bad ROM region
• a .hex file is being generated, and part of an instruction falls in a bad ROM region

4.5.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
__badrom is not commonly used, as RAM and ROM details are handled by the include
files (*.inc) or linker script files (*.lkr).

4.5.4

See Also

__maxrom

4.5.5

Simple Example

#include p12c508.inc
__maxrom 0x1FF
__badrom 0x2 - 0x4, 0xA
org 0x5
goto 0x2
; generates a warning
call 0x3
; generates a warning
org 0xA
movlw 5
; generates a warning

DS33014L-page 76

 1994-2013 Microchip Technology Inc.

Directives
4.6

bankisel - GENERATE INDIRECT BANK SELECTING CODE (PIC12/16
MCUs)
4.6.1

Syntax

bankisel label

4.6.2

Description

This directive is an instruction to the assembler or linker to generate the appropriate
bank selecting code for an indirect access of the register address specified by label.
Only one label should be specified. No operations can be performed on label. This
label must have been previously defined.
The linker will generate the appropriate bank selecting code. For 14-bit instruction
width (most PIC12/PIC16) devices, the appropriate bit set/clear instruction on the IRP
bit in the STATUS register will be generated. But for PIC16 extended instructions,
FSR0H is modified instead of IRP bit (as there is no IRP bit). If the indirect address can
be specified without these instructions, no code will be generated.

4.6.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive may be used with 14-bit instruction width PIC1X devices. This excludes
12-bit instruction width devices and PIC18 devices.

4.6.4

See Also

banksel pagesel

4.6.5

Simple Example

movlw Var1
movwf FSR
bankisel Var1
:
movwf INDF

 1994-2013 Microchip Technology Inc.

;Load the address of Var1 info FSR
;Select the correct bank for Var1
;Indirectly write to Var1

DS33014L-page 77

Assembler/Linker/Librarian User’s Guide
4.6.6

Application Example - bankisel

This program demonstrates the bankisel directive. This directive generates the
appropriate code to set/clear the IRP bit of the STATUS register for an indirect access.
#include p16f877a.inc

group1

udata

group1_var1
group1_var2
group2

udata

group2_var1
group2_var2
RST

CODE

pagesel
goto
PGM

0x20
res
res

1
1

0x120
res
res

1
1

0x0

start
start

CODE

start
movlw 0x20
movwf FSR
bankisel group1_var1
clrf INDF
incf FSR,F
clrf INDF

;Include standard header file
;for the selected device.
;group1 data
;starting at
;group1_var1
;group1_var2

stored at locations
0x20 (IRP bit 0).
located at 0x20.
located at 0x21.

;group2 data
;starting at
;group2_var1
;group2_var2

stored at locations
0x120 (IRP bit 1).
located at 0x120.
located at 0x121.

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.

;This part of the code addresses
;variables group1_var1 &
;group1_var2 indirectly.

movwf FSR
bankisel group2_var1
clrf INDF
incf FSR,F
clrf INDF
goto
end

DS33014L-page 78

$

;Go to current line (loop here)

 1994-2013 Microchip Technology Inc.

Directives
4.6.7

Application Example 2 - bankisel

#include p16f877a.inc

;Include standard header file
;for the selected device.

bankisel EEADR

;This register is at location 100h
;in banks 2 or 3 so the IRP bit
;must be set. bankisel will set it
;but only where it is used.
;Put the address of the register to
;be accessed indirectly into W.
;Copy address from W to FSR to set
;up pointer to EEADR.
;Clear EEADR through indirect
;accessing of EEADR through FSR/INDF.
;It would have cleared PIR2 (00Dh)
;if bankisel had not been used to
;set the IRP bit.
;Prevents fall off end of code.
;All code must have an end statement.

movlw

EEADR,W

movwf

FSR

clrf

INDF

goto
end

$

 1994-2013 Microchip Technology Inc.

DS33014L-page 79

Assembler/Linker/Librarian User’s Guide
4.7

banksel - GENERATE BANK SELECTING CODE
4.7.1

Syntax

banksel label

4.7.2

Description

This directive is an instruction to the assembler and linker to generate bank selecting
code to set the bank to the bank containing the designated label. Only one label
should be specified. No operations can be performed on label. This label must have
been previously defined.
The linker will generate the appropriate bank selecting code:
For 12-bit instruction width (PIC10F, some PIC12/PIC16) devices, the appropriate bit
set/clear instructions on the FSR will be generated.
For 14-bit instruction width (most PIC12/PIC16) devices, bit set/clear instructions on
the STATUS register will be generated.
For PIC16 extended and PIC18 devices, a movlb will be generated. If the device
contains only one bank of RAM, no instructions will be generated.

4.7.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive may be used with all PIC1X devices. This directive is not needed for
variables in access RAM (PIC18 devices.)

4.7.4

See Also

bankisel pagesel

4.7.5

Simple Example

banksel Var1
movwf Var1

DS33014L-page 80

;Select the correct bank for Var1
;Write to Var1

 1994-2013 Microchip Technology Inc.

Directives
4.7.6

Application Example - banksel

This program demonstrates the banksel directive. This directive generates the
appropriate code to set/clear the RP0 and RP1 bits of the STATUS register.
#include p16f877a.inc

group1

udata

group1_var1
group1_var2
group2

udata

group2_var1
group2_var2
RST

CODE

pagesel
goto
PGM

res
res

1
1

0xA0
res
res

;group1 data
;starting at
;group1_var1
;group1_var2

stored at locations
0x20 (bank 0).
located at 0x20.
located at 0x21.

;group2 data stored at locations
;starting at 0xA0 (bank 1)
1
1

0x0

start
start

CODE

start
banksel

clrf
clrf

0x20

;Include standard header file
;for the selected device.

group1_var1

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.

;This directive generates code
;to set/clear bank select bits
;RP0 & RP1 of STATUS register
;depending upon the address of
;group1_var1.

group1_var1
group1_var2

banksel

group2_var1

clrf
clrf

group2_var1
group2_var2

goto
end

$

 1994-2013 Microchip Technology Inc.

;This directive generates code
;to set/clear bank select bits
;RP0 & RP1 of STATUS register
;depending upon the address of
;group2_var1.

;Go to current line (loop here)

DS33014L-page 81

Assembler/Linker/Librarian User’s Guide
4.7.7

Application Example 2 - banksel

#include p16f877a.inc

;Include standard header file
;for the selected device.

banksel TRISB

;Since this register is in bank 1,
;not default bank 0, banksel is
;used to ensure bank bits are correct.
;Clear TRISB. Sets PORTB to outputs.
;banksel used to return to bank 0,
;where PORTB is located.
;Set PORTB value.

clrf
TRISB
banksel PORTB
movlw
movwf
goto
end

4.8

0x55
PORTB
$

;All programs must have an end.

cblock - DEFINE A BLOCK OF CONSTANTS
4.8.1

Syntax

cblock [expr]
label[:increment][,label[:increment]]
endc

4.8.2

Description

Defines a list of named sequential symbols. The purpose of this directive is to assign
address offsets to many labels. The list of names end when an endc directive is
encountered.
expr indicates the starting value for the first name in the block. If no expression is
found, the first name will receive a value one higher than the final name in the previous
cblock. If the first cblock in the source file has no expr, assigned values start with
zero.
If increment is specified, then the next label is assigned the value of increment
higher than the previous label.
Multiple names may be given on a line, separated by commas.
cblock is useful for defining constants in program and data memory for absolute code
generation.

4.8.3

Usage

This directive is used in the following types of code: absolute. For information on types
of code, see Section 1.6 “Assembler Operation”.
Use this directive in place of or in addition to the equ directive. When creating
non-relocatable (absolute) code, cblock is often used to define variable address
location names. Do not use cblock or equ to define variable location names for
relocatable code.

4.8.4

See Also

endc equ

DS33014L-page 82

 1994-2013 Microchip Technology Inc.

Directives
4.8.5

Simple Example

cblock 0x20
name_1, name_2
name_3, name_4
endc
cblock 0x30
TwoByteVar: 0,

; name_1 will be assigned 20
; name_2, 21 and so on
; name_4 is assigned 23.

TwoByteHigh, TwoByteLow ;TwoByteVar =0x30
;TwoByteHigh=0x30
;TwoByteLow =0x31
Queue: QUEUE_SIZE
QueueHead, QueueTail
Double1:2, Double2:2
endc

4.8.6

Application Example - cblock/endc

This example shows the usage of CBLOCK and ENDC directives for defining constants
or variables in data memory space. The same directives can be used for program
memory space also.
The program calculates the perimeter of a rectangle. Length and width of the rectangle
will be stored in buffers addressed by length (22H) and width (23H). The calculated
perimeter will be stored in the double-precision buffer addressed by perimeter (i.e.,
20H and 21H).
#include p16f877a.inc
CBLOCK

0x20

perimeter:2

length
width
ENDC
clrf

perimeter+1

movf

length,w

addwf

width,w

movwf

perimeter

rlf

perimeter+1

rlf

perimeter

rlf

perimeter+1

goto
end

$

 1994-2013 Microchip Technology Inc.

;Include standard header file
;for the selected device.
;Define a block of variables
;starting at 20H in data memory.
;The label perimeter is 2 bytes
;wide. Address 20H and 21H is
;assigned to the label perimeter.
;Address 22H is assigned to the
;label length.
;Address 23H is assigned to the
;label width.
;This directive must be supplied
;to terminate the CBLOCK list.
;Clear perimeter high byte
;at address 21H.
;Move the data present in the
;register addressed by 'length'
;to 'w'
;Add data in 'w' with data in the
;register addressed by 'width'.
;STATUS register carry bit C
;may be affected.
;Move 'w' to the perimeter low
;byte at address 20H. Carry bit
;is unaffected.
;Increment register 21H if carry
;was generated. Also clear carry
;if bit was set.
;Multiply register 20H by 2.
;Carry bit may be affected.
;Again, increment register 21H
;if carry was generated.
;Go to current line (loop here)

DS33014L-page 83

Assembler/Linker/Librarian User’s Guide
4.9

code - BEGIN AN OBJECT FILE CODE SECTION
4.9.1

Syntax

[label] code [ROM_address]

4.9.2

Description

This directive declares the beginning of a section of program code. If label is not
specified, the section is named .code. The starting address is initialized to the
specified address or will be assigned at link time if no address is specified.
Note:

4.9.3

Two sections in a source file may not have the same name.

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
There is no “end code” directive. The code of a section ends automatically when
another code or data section is defined or when the end of the file is reached.

4.9.4

See Also

extern code_pack global idata udata udata_acs udata_ovr udata_shr

4.9.5

Simple Example

RESET code 0x01FF
goto START

4.9.6

Application Example - code

This program demonstrates the code directive, which declares the beginning of a
section of program code.
#include p16f877a.inc

RST

CODE

pagesel
goto

0x0

start
start

;Include standard header file
;for the selected device.
;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.

PGM

CODE

;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.

start
clrw
goto

$

;Go to current line (loop here)

CODE

;This is a relocatable code
;section since no address is
;specified. The section name will
;be, by default, .code.

nop

end

DS33014L-page 84

 1994-2013 Microchip Technology Inc.

Directives
4.10

code_pack - BEGIN AN OBJECT FILE PACKED CODE SECTION (PIC18
MCUs)
4.10.1

Syntax

[label] code_pack [ROM_address]

4.10.2

Description

This directive declares the beginning of a section of program code or ROM data where
a padding byte of zero is not appended to an odd number of bytes. If label is not
specified, the section is named .code. The starting address is initialized to
ROM_address or will be assigned at link time if no address is specified. If
ROM_address is specified, it must be word-aligned. If padded data is desired, use db.
Note:

4.10.3

Two sections in a source file may not have the same name.

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
This directive is commonly used when storing data into program memory (use with db)
or the EEPROM data memory (use with de) of a PIC18 device.

4.10.4

See Also

extern code global idata udata udata_acs udata_ovr udata_shr

4.10.5

Simple Example

0001F0 01 02 03
0001F3 04 05

000000 0201 0003
000004 0504

 1994-2013 Microchip Technology Inc.

00001 LIST P=18Cxx
00002
00003 packed code_pack 0x1F0
00004
DB 1, 2, 3
00005
DB 4, 5
00006
00007 padded code
00008
DB 1, 2, 3
00009
DB 4, 5
00010
00011
END

DS33014L-page 85

Assembler/Linker/Librarian User’s Guide
4.11

__config - SET PROCESSOR CONFIGURATION BITS
Note:

4.11.1

config is preceded by two underline characters.

Syntax

Preferred:
__config expr
__config addr, expr

Note:

PIC18FXXJ devices do not support this directive. Use config directive (no
underline characters.)

Supported:
__fuses expr

4.11.2

Description

Sets the processor's configuration bits. Before this directive is used, the processor
must be declared through the command line, the list directive, the processor directive,
a project if using MPLAB X IDE or Configure>Select Device if using MPLAB IDE. Refer
to individual PIC1X microcontroller data sheets for a description of the configuration
bits.
MCUs with a single configuration register
Sets the processor's configuration bits to the value described by expr.
MCUs with multiple configuration registers
For the address of a valid configuration byte specified by addr, sets the configuration
bits to the value described by expr.
Note:

Configuration bits must be listed in ascending order.

Although this directive may be used to set configuration bits for PIC18 MCU devices, it
is recommended that you use the config directive (no underline characters). For
PIC18FXXJ devices, you must use the config directive.
Note:

4.11.3

Do not mix __config and config directives in the same code.

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is placed in source code so that, when the code is assembled into a hex
file, the configuration values are preset to desired values in your application. This is
useful when giving your files to a third-party programming house, as this helps insure
the device is configured correctly when programmed.
Place configuration bit assignments at the beginning of your code. Use the
configuration options (names) in the standard include (*.inc) file. These names can
be bitwise ANDed together using & to declare multiple configuration bits.

4.11.4

See Also

config __idlocs list processor

DS33014L-page 86

 1994-2013 Microchip Technology Inc.

Directives
4.11.5

Simple Examples

Example 1: PIC16 Devices
#include p16f877a.inc
;include file with config bit definitions
__config _HS_OSC & _WDT_OFF & _LVP_OFF ;Set oscillator to HS,
;watchdog time off,
;low-voltage prog. off

Example 2: PIC17X Devices (MPLAB IDE v8 Support Only)
#include p17c42.inc
__config 0xFFFF

;include file with config bit definitions
;default configuration bits

Example 3: PIC18 Devices
#include p18c452.inc

;Include standard header file
;for the selected device.

;code protect disabled.
__CONFIG
_CONFIG0, _CP_OFF_0
;Oscillator switch disabled, RC oscillator with OSC2
;as I/O pin.
__CONFIG
_CONFIG1, _OSCS_OFF_1 & _RCIO_OSC_1
;Brown-OutReset enabled, BOR Voltage is 2.5v
__CONFIG
_CONFIG2, _BOR_ON_2 & _BORV_25_2
;Watch Dog Timer enable, Watch Dog Timer PostScaler
;count - 1:128
__CONFIG
_CONFIG3, _WDT_ON_3 & _WDTPS_128_3
;CCP2 pin Mux enabled
__CONFIG
_CONFIG5, _CCP2MX_ON_5
;Stack over/underflow Reset enabled
__CONFIG
_CONFIG6, _STVR_ON_6

 1994-2013 Microchip Technology Inc.

DS33014L-page 87

Assembler/Linker/Librarian User’s Guide
4.12

config - SET PROCESSOR CONFIGURATION BITS (PIC18 MCUs)
4.12.1
config

4.12.2

Syntax
setting=value [, setting=value]

Description

Defines a list of Configuration bit setting definitions. This list sets the PIC18 processor's
Configuration bits represented by setting to a value described by value. Refer to
individual PIC18 microcontroller data sheets for a description of the Configuration bits.
Available settings and values maybe found in both the standard processor include
(*.inc) files and the PIC18 Configuration Settings Addendum (DS51537).
Multiple settings may be defined on a single line, separated by commas. Settings for a
single Configuration byte may also be defined on separate lines.
Before this directive is used, a PIC18 MCU must be declared through the command
line, the list directive, the processor directive, a project if using MPLAB X IDE or
Configure>Select Device if using MPLAB IDE.
Another directive that may be used to set configuration bits for PIC18 MCU devices is
the __config directive, but this is not recommended for new code.
Note:

4.12.3

Do not mix __config and config directives in the same code.

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is placed in source code so that, when the code is compiled/assembled
into a hex file, the configuration values are preset to desired values in your application.
This is useful when giving your files to a third-party programming house, as this helps
insure the device is configured correctly when programmed.
Place configuration bit assignments at the beginning of your code. Use the
configuration options (setting=value pairs) listed in the standard include (*.inc)
file or the addendum. The config directive can be used multiple times in the source
code, but an error will be generated if the same bit is assigned a value more than once,
i.e.,
CONFIG CP0=OFF, WDT=ON
CONFIG CP0=ON ;(An error will be issued since CP0 is assigned twice)

4.12.4

See Also

__config __idlocs list processor

DS33014L-page 88

 1994-2013 Microchip Technology Inc.

Directives
4.12.5

Simple Example

#include p18f452.inc

;Include standard header file
;for the selected device.

;code protect disabled
CONFIG
CP0=OFF
;Oscillator switch enabled, RC oscillator with OSC2 as I/O pin.
CONFIG
OSCS=ON, OSC=LP
;Brown-OutReset enabled, BOR Voltage is 2.5v
CONFIG
BOR=ON, BORV=25
;Watch Dog Timer enable, Watch Dog Timer PostScaler count - 1:128
CONFIG
WDT=ON, WDTPS=128
;CCP2 pin Mux enabled
CONFIG
CCP2MUX=ON
;Stack over/underflow Reset enabled
CONFIG
STVR=ON

4.13

constant - DECLARE SYMBOL CONSTANT
4.13.1

Syntax

constant label=expr [...,label=expr]

4.13.2

Description

Creates symbols for use in MPASM assembler expressions. Constants may not be
reset after having once been initialized, and the expression must be fully resolvable at
the time of the assignment. This is the principal difference between symbols declared
as constant and those declared as variable, or created by the set directive. Otherwise,
constants and variables may be used interchangeably in absolute code expressions.

4.13.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
Although equ or cblock is more generally used to create constants, the constant
directive also works.

4.13.4

See Also

set variable equ cblock

4.13.5

Examples

See the examples under variable.

 1994-2013 Microchip Technology Inc.

DS33014L-page 89

Assembler/Linker/Librarian User’s Guide
4.14

da - STORE STRINGS IN PROGRAM MEMORY (PIC12/16 MCUs)
4.14.1

Syntax

[label] da expr [, expr2, ..., exprn]

4.14.2

Description

da - Data ASCII.
Generates a packed 14-bit number representing two 7-bit ASCII characters.

4.14.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is useful for storing strings in memory for PIC16 MCU devices.

4.14.4

Simple Examples

• da "abcdef"
will put 30E2 31E4 32E6 into program memory
• da "12345678" ,0
will put 18B2 19B4 1AB6 1BB8 0000 into program memory
• da 0xFFFF
will put 0x3FFF into program memory

4.14.5

Application Example - da

This example shows the usefulness of directive da in storing a character string in the
program memory of 14-bit architecture devices. This directive generates a packed
14-bit number representing two 7-bit ASCII characters.
#include p16f877a.inc

;Include standard header file
;for the selected device.

ORG

0x0000

goto

start

;The following code will be
;programmed in reset address 0.
;Jump to an address labelled
;'start'.

start
goto

$

;Go to current line (loop here)

ORG

0x1000

;Store the string starting from
;1000H.

Ch_stng

DS33014L-page 90

;Write your main program here.

da

"PICmicro"

 1994-2013 Microchip Technology Inc.

Directives
Directive da produces four 14-bit numbers: 2849, 21ED, 34E3, and 396F representing
the ASCII equivalent of PI, Cm, ic, and ro. See below for more information.
Sngl_ch

da

"A"

;7-bit ASCII equivalents of 'A'
;and a NULL character will be packed
;in a 14-bit number.

da

0xff55

;Places 3f55 in program memory.
;No packing.

end

Determining 14-Bit Numbers
For the following statement:
Ch_stng

da

"PICmicro"

directive da produces four 14-bit numbers: 2849, 21ED, 34E3 and 396F representing
the ASCII equivalent of PI, Cm, ic and ro.
To see how the 14-bit numbers are determined, look at the ASCII values of P and I,
which are 50h(01010000) and 49h(01001001) respectively. Each is presented in 7-bit
as (0)1010000 and (0)1001001 respectively. The packed 14-bit number is
101000 01001001, which is stored as (00)101000 01001001 or 2849.

 1994-2013 Microchip Technology Inc.

DS33014L-page 91

Assembler/Linker/Librarian User’s Guide
4.15

data - CREATE NUMERIC AND TEXT DATA
4.15.1

Syntax

[label] data expr,[,expr,...,expr]
[label] data "text_string"[,"text_string",...]

4.15.2

Description

Initialize one or more words of program memory with data. The data may be in the form
of constants, relocatable or external labels, or expressions of any of the above. The
data may also consist of ASCII character strings, text_string, enclosed in single
quotes for one character or double quotes for strings. Single character items are placed
into the low byte of the word, while strings are packed two to a word. If an odd number
of characters are given in a string, the final byte is zero. On all families except the
PIC18 device family, the first character is in the most significant byte of the word. On
the PIC18 device family, the first character is in the least significant byte of the word.

4.15.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
When generating a linkable object file, this directive can also be used to declare
initialized data values. Refer to the idata directive for more information.
db and other data directives are more commonly used than data.

4.15.4

See Also

db de dt dtm dw idata

4.15.5
data
data
data
data
data

Simple Example

reloc_label+10
1,2,ext_label
"testing 1,2,3"
'N'
start_of_program

4.15.6

;
;
;
;
;

constants
constants, externals
text string
single character
relocatable label

PIC16 Application Example - data

This example shows the usefulness of directive data in storing one or more words in
program memory.
#include p16f877a.inc

;Include standard header file
;for the selected device.

ORG

0x0000

goto

start

;The following code will be
;programmed in reset address 0.
;Jump to an address labelled
;’start’.

start
goto

$

;Go to current line (loop here)

ORG

0x1000

;Store the string starting from
;1000H.

Ch_stng

DS33014L-page 92

;Write your main program here.

data

"M","C","U"

;3 program memory locations
;will be filled with ASCII
;equivalent of "M", "C" and
;"U".

 1994-2013 Microchip Technology Inc.

Directives
Directive data produces three 14-bit numbers: 004Dh, 0043h, and 0055h. 4Dh, 43h
and 55h are ASCII equivalents of “M”, “C” and “U”, respectively.
tb1_dta

data

0xffff,0xaa55 ;Places 3fffh and 2a55h in
;two consecutive program
;memory locations. As program
;memory is 14-bit wide,
;the last nibble can store
;a maximum value 3.

end

4.15.7

PIC18 Application Example - data

This example shows the usefulness of directive data in storing one or more words in
program memory.
#include p18f452.inc

;Include standard header file
;for the selected device.

ORG

0x0000

goto

start

;The following code will be
;programmed in reset address 0.
;Jump to an address labelled
;’start’.

start

;Write your main program here.

goto

$

;Go to current line (loop here)

ORG

0x1000

;Store the string starting from
;1000H. In PIC18 devices, the
;first character is in least
;significant byte.

Ch_stng

data

"M","C","U"

;3 program memory locations
;will be filled with ASCII
;equivalent of "M", "C" and
;"U".

Directive data produces three 16-bit numbers: 004Dh, 0043h, and 0055h. 4Dh, 43h
and 55h are ASCII equivalents of “M”, “C” and “U”, respectively. See
Section 4.10 “code_pack - Begin an Object File Packed Code Section (PIC18
MCUs)” for better use of memory.
Ch_stg1

data

"MCU"

;2 program memory locations
;will be filled with two
;words (16-bit numbers),
;each representing ASCI
;equivalent of two
;characters. The last
;character will be taken as
;NULL in case odd number of
;characters are specified.

Directive data produces two words: 434Dh and 0055h. 434Dh represents “C” and “M”.
tb1_dta

data

0xffff,0xaa55

;Places ffff and aa55 in
;two consecutive program
;memory locations.

end

 1994-2013 Microchip Technology Inc.

DS33014L-page 93

Assembler/Linker/Librarian User’s Guide
4.16

db - DECLARE DATA OF ONE BYTE
4.16.1

Syntax

[label] db expr[,expr,...,expr]

4.16.2

Description

db - Data Byte.
Reserve program memory words with 8-bit values. Multiple expressions continue to fill
bytes consecutively until the end of expressions. Should there be an odd number of
expressions, the last byte will be zero unless in a PIC18 code_pack section.

4.16.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
When generating a linkable object file, this directive can also be used to declare
initialized data values. In this case, the values will be padded with 34 (RETLW) instead
of 00 as in examples. Refer to the idata directive for more information.
For PIC18 devices, use code_pack with db, since it is desired to not have bytes
padded with zeroes. See the description of code_pack for more information.

4.16.4

See Also

data de dt dtm dw idata code_pack

4.16.5

Simple Examples

Example1: PIC16 Devices
db 0x0f, "t", 0x0f, "e", 0x0f, "s", 0x0f, "t", "\n"

ASCII: 0x0F74 0x0F65 0x0F73 0x0F74 0x0a00
Example 2: PIC18 Devices
db "t", "e", "s", "t", "\n"

ASCII: 0x6574 0x7473 0x000a

4.16.6

PIC16 Application Example - db

This example shows the usefulness of directive db in storing one or more bytes or
characters in program memory.
#include p16f877a.inc

;Include standard header file
;for the selected device.

ORG

0x0000

goto

start

;The following code will be
;programmed in reset address 0.
;Jump to an address labelled
;’start’.

start

DS33014L-page 94

;Write your main program here.

goto

$

;Go to current line (loop here)

ORG

0x1000

;Store the string starting from
;1000H.

 1994-2013 Microchip Technology Inc.

Directives
Ch_stng

db

tb1_dta

db

0,"M",0,"C",0,"U"

0,0xff

;Ch_strng contains 3 14-bit
;numbers: 004Dh, 0043h, and 0055h.
;These are ASCII equivalents of
;"M", "C" and "U", respectively.

;Places 00ff in program memory
;location.

end

4.16.7

PIC18 Application Example - db

This example shows the usefulness of directive db in storing one or more byte or
character in program memory.
#include p18f452.inc

;Include standard header file
;for the selected device.

ORG

0x0000

goto

start

;The following code will be
;programmed in reset address 0.
;Jump to an address labelled
;’start’.

start

;Write your main program here.

goto

$

;Go to current line (loop here)

ORG

0x1000

;Store the string starting from
;1000H. In PIC18 devices, the
;first character is in least
;significant byte.

Ch_stng

db

tb1_dta

db

"M","C","U" ;Ch_strng contains three 16-bit numbers:
;004Dh, 0043h, and 0055h. These are ASCII
;equivalents of "M”, "C" and "U",
;respectively. Information on storing data
;in both bytes of a program word on the
;PIC18 architecture can be found under the
;code_pack directive*.
0,0xff

;Places ff00 in program memory
;location.

end

* Section 4.10 “code_pack - Begin an Object File Packed Code Section (PIC18
MCUs)”

 1994-2013 Microchip Technology Inc.

DS33014L-page 95

Assembler/Linker/Librarian User’s Guide
4.17

de - DECLARE EEPROM DATA BYTE
4.17.1

Syntax

[label] de expr [, expr, ..., expr]

4.17.2

Description

de - Data EEPROM.
This directive can be used at any location for any processor.
For PIC18 devices, reserve memory word bytes are packed. If an odd number of bytes
is specified, a 0 will be added unless in a code_pack section. See the description for
code_pack for more infomation.
For all other PIC1X MCU devices, reserve memory words with 8-bit data. Each expr
must evaluate to an 8-bit value. The upper bits of the program word are zeroes. Each
character in a string is stored in a separate word.

4.17.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is designed mainly for initializing data in the EE data memory region of
PIC1X MCU devices with EE data FLASH.
Make sure to specify the start of EEPROM data memory in your code. The table below
shows start addresses for different device families. However, always check your device
programming specification for the correct address.
TABLE 4-1:

EEPROM START ADDRESS BY DEVICE
Device

Address

Most PIC1X MCUs

0x2100

PIC18 MCUs

0xF00000

PIC16F19XX MCUs

0xF000

4.17.4

See Also

data db dt dtm dw code_pack

4.17.5

Simple Example

Initialize EEPROM data on a PIC16 device:
org 0x2100
de "My Program, v1.0", 0

DS33014L-page 96

 1994-2013 Microchip Technology Inc.

Directives
4.17.6

PIC16 Application Example - de

#include p16f877a.inc

;Include standard header file
;for the selected device.

org

;The absolue address 2100h is
;mapped to the 0000 location of
;EE data memory.

0x2100

;You can create a data or character table starting from any
;address in EE data memory.
ch_tbl2

de

"PICmicro"

;8 EE data memory locations
;(starting from 0) will be filled
;with 8 ASCII characters.

end

4.17.7

PIC18 Application Example - de

#include p18f452.inc

;Include standard header file
;for the selected device.

org

;The absolue address F00000h is
;mapped to the 0000 location of
;EE data memory for PIC18 devices.

0xF00000

;You can create a data or character table starting from any
;address in EE data memory.
ch_tbl2

de

"PICmicro"

;8 EE data memory locations
;(starting from 0) will be filled
;with 8 ASCII characters.

end

 1994-2013 Microchip Technology Inc.

DS33014L-page 97

Assembler/Linker/Librarian User’s Guide
4.18

#define - DEFINE A TEXT SUBSTITUTION LABEL
4.18.1

Syntax

#define name [string]

4.18.2

Description

This directive defines a text substitution string. Wherever name is encountered in the
assembly code, string will be substituted.
Using the directive with no string causes a definition of name to be noted internally
and may be tested for using the ifdef directive.
This directive emulates the ANSI 'C' standard for #define. Symbols defined with this
method are not available for viewing using MPLAB X IDE or MPLAB IDE v8.

4.18.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
#define is useful for defining values for constants in your program.
Note:

A processor-specific include file exists with predefined SFR names. It is
recommended that you use this file instead of defining the variables
yourself. See #include for how to include a file in your program.

This directive is also useful with the ifdef and ifndef directives, which look for the
presence of an item in the symbol table.

4.18.4

See Also

#undefine #include ifdef ifndef

4.18.5

Simple Example

#define length 20
#define control 0x19,7
#define position(X,Y,Z) (Y-(2 * Z +X))
:
:
test_label dw position(1, length, 512)
bsf control
; set bit 7 in f19

DS33014L-page 98

 1994-2013 Microchip Technology Inc.

Directives
4.18.6

Application Example - #define/#undefine

This example shows the the usage of #define and #undefine directives. A symbol
name previously defined with the #define directive, is removed from the symbol table
if #undefine directive is used. The same symbol may be redefined again.
#include p16f877a.inc

;Include standard header file
;for the selected device.

area

;The label 'area' is assigned
;the value 0.
;Label 'lngth' is assigned
;the value 50H.
;Label 'wdth' is assigned
;the value 25H
;Reassignment of label 'area'.
;So 'area' will be reassigned a
;value equal to 50H*25H.

set

0

#define lngth

50H

#define wdth

25H

area

set

#undefine
#undefine
#define

lngth*wdth

lngth
wdth
lngth

0

;Undefine label 'lngth'.
;Undefine label 'wdth'
;Define label 'lngth' to '0'.

end

By using the above directives, lngth will be reassigned a value '0' and wdth will be
removed from the symbol list in the list (.lst) file. The label lngth must be undefined
before it can be defined as '0'.

 1994-2013 Microchip Technology Inc.

DS33014L-page 99

Assembler/Linker/Librarian User’s Guide
4.19

dt - DEFINE TABLE (PIC12/16 MCUs)
4.19.1

Syntax

[label] dt expr [, expr, ..., expr]

4.19.2

Description

dt - Define data Table.
Generates a series of RETLW instructions, one instruction for each expr. Each expr
must be an 8-bit value. Each character in a string is stored in its own RETLW instruction.

4.19.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is used when generating a table of data for the PIC12/16 device family.
If you are using a PIC18 device, it is recommended that you use the table read/write
(TBLRD/TBLWT) features. See the device data sheet for more information.

4.19.4

See Also

data db de dtm dw

4.19.5

Simple Example

dt "A Message", 0
dt FirstValue, SecondValue, EndOfValues

4.20

dtm - DEFINE TABLE (EXTENDED PIC16 MCUS ONLY)
4.20.1

Syntax

[label] dtm expr [, expr, ..., expr]

4.20.2

Description

dtm - Define data Table using MOVLW.
Generates a series of MOVLW instructions, one instruction for each expr. Each expr
must be an 8-bit value. Each character in a string is stored in its own MOVLW instruction.

4.20.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”. This directive
is used when generating a table of data for the PIC16 extended device family.

4.20.4

See Also

data db de dt dw

4.20.5

Simple Example

dtm "A Message", 0
dtm FirstValue, SecondValue, EndOfValues

DS33014L-page 100

 1994-2013 Microchip Technology Inc.

Directives
4.21

dw - DECLARE DATA OF ONE WORD
4.21.1

Syntax

[label] dw expr[,expr,...,expr]

4.21.2

Description

dw - Data Word.
Reserve program memory words for data, initializing that space to specific values. For
PIC18 devices, dw functions like db. Values are stored into successive memory
locations and the location counter is incremented by one. Expressions may be literal
strings and are stored as described in the db data directive.

4.21.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
When generating a linkable object file, this directive can also be used to declare
initialized data values. Refer to the idata directive for more information.
While db is more common to use, you may use dw to store data in Flash PIC16FXXX
devices, as many of these devices can read all 14 bits of a program memory word at
run-time. See the PIC16F877A data sheet for examples and more information.

4.21.4

See Also

data db idata

4.21.5

Simple Example

dw 39, "diagnostic 39", 0x123
dw diagbase-1

 1994-2013 Microchip Technology Inc.

DS33014L-page 101

Assembler/Linker/Librarian User’s Guide
4.22

else - BEGIN ALTERNATIVE ASSEMBLY BLOCK TO if CONDITIONAL
4.22.1

Syntax

Preferred:
else

Supported:
#else
.else

4.22.2

Description

Used in conjunction with an if directive to provide an alternative path of assembly
code should the if evaluate to false. else may be used inside a regular program block
or macro.

4.22.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not an instruction. It is used to perform conditional assembley of code.

4.22.4

See Also

endif if

4.22.5

Simple Example

if rate < 50
incf speed, F
else
decf speed, F
endif

4.22.6

Application Example - if/else/endif

See this example under if.

DS33014L-page 102

 1994-2013 Microchip Technology Inc.

Directives
4.23

end - END PROGRAM BLOCK
4.23.1

Syntax

end

4.23.2

Description

Indicates the end of the program.

4.23.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
You will need at least one end directive in any assembly program to indicate the end
of a build. In a single assembly file program, one and only one end must be used.
Be careful not to include files which contain end as assembly will be prematurely
stopped.

4.23.4

See Also

org

4.23.5

Simple Example

#include p18f452.inc
:
; executable code
:
;
end ; end of instructions

4.24

endc - END AN AUTOMATIC CONSTANT BLOCK
4.24.1

Syntax

endc

4.24.2

Description

endc terminates the end of a cblock list. It must be supplied to terminate the list.

4.24.3

Usage

This directive is used in the following types of code: absolute. For information on types
of code, see Section 1.6 “Assembler Operation”.
For every cblock directive used, there must be a corresponding endc.

4.24.4

See Also

cblock

4.24.5

Examples

See the examples under cblock.

 1994-2013 Microchip Technology Inc.

DS33014L-page 103

Assembler/Linker/Librarian User’s Guide
4.25

endif - END CONDITIONAL ASSEMBLY BLOCK
4.25.1

Syntax

Preferred:
endif

Supported:
#endif
.endif
.fi

4.25.2

Description

This directive marks the end of a conditional assembly block. endif may be used
inside a regular program block or macro.

4.25.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
For every if directive used, there must be a corresponding endif.
if and endif are not instructions, but used for code assembly only.

4.25.4

See Also

else if

4.25.5

Examples

See the examples under if.

4.26

endm - END A MACRO DEFINITION
4.26.1

Syntax

endm

4.26.2

Description

Terminates a macro definition begun with macro.

4.26.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
For every macro directive used, there must be a corresponding endm.

4.26.4

See Also

macro exitm

4.26.5

Simple Example

make_table macro arg1, arg2
dw arg1, 0 ; null terminate table name
res arg2
; reserve storage
endm

4.26.6

Application Example - macro/endm

See this example under macro.

DS33014L-page 104

 1994-2013 Microchip Technology Inc.

Directives
4.27

endw - END A while LOOP
4.27.1

Syntax

Preferred:
endw

Supported:
.endw

4.27.2

Description

endw terminates a while loop. As long as the condition specified by the while
directive remains true, the source code between the while directive and the endw
directive will be repeatedly expanded in the assembly source code stream. This
directive may be used inside a regular program block or macro.

4.27.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
For every while directive used, there must be a corresponding endw.
while and endw are not instructions, but used for code assembly only.

4.27.4

See Also

while

4.27.5

Examples

See the example under while.

4.28

equ - DEFINE AN ASSEMBLER CONSTANT
4.28.1

Syntax

label equ expr

4.28.2

Description

The value of expr is assigned to label.

4.28.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
In a single assembly file program, equ is commonly used to assign a variable name to
an address location in RAM. Do not use this method for assigning variables when
building a linked project; use a res directive inside a data section directive (idata,
udata).

4.28.4

See Also

set cblock res idata udata udata_acs udata_ovr udata_shr

4.28.5

Simple Example

four equ 4 ; assigned the numeric value of 4 to label four

4.28.6

Application Example - set/equ

See this example under set.
 1994-2013 Microchip Technology Inc.

DS33014L-page 105

Assembler/Linker/Librarian User’s Guide
4.29

error - ISSUE AN ERROR MESSAGE
4.29.1

Syntax

error "text_string"

4.29.2

Description

text_string is printed in a format identical to any MPASM assembler error message.
text_string may be from 1 to 80 characters.

4.29.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
You can use this directive to generate errors for yourself or others who build your code.
You can create any error message you wish, as long as it is no longer than 80
characters.

4.29.4

See Also

messg if

4.29.5

Simple Example

error_checking macro arg1
if arg1 >= 55 ; if arg is out of range
error "error_checking-01 arg out of range"
endif
endm

4.29.6

Application Example - error

This program demonstrates the error assembler directive, which sets an error
message to be printed in the listing file and error file.
#include p16f877a.inc

;Include standard header file
;for the selected device.

variable baudrate

;variable used to define
;required baud rate

baudrate set D'5600'

;Enter the required value of
;baud rate here.

if (baudrate!=D'1200')&&(baudrate!=D'2400')&&
(baudrate!=D'4800')&&(baudrate!=D'9600')&&
(baudrate!=D'19200')
error "Selected baud rate is not supported"
endif

DS33014L-page 106

 1994-2013 Microchip Technology Inc.

Directives
The if-endif code above outputs error if the baud rate selected is other than 1200,
2400, 4800, 9600 or 19200 Hz.
RST

CODE

pagesel
goto
PGM

CODE

start
goto $
end

 1994-2013 Microchip Technology Inc.

0x0

start
start

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.
;Go to current line (loop here)

DS33014L-page 107

Assembler/Linker/Librarian User’s Guide
4.30

errorlevel - SET MESSAGE LEVEL
4.30.1

Syntax

errorlevel {0|1|2|+msgnum|-msgnum} [, ...]

4.30.2

Description

Sets the types of messages that are printed in the listing file and error file.
Setting

Affect

0

Messages, warnings, and errors printed

1

Warnings and errors printed

2

Errors printed

-msgnum

Inhibits printing of message msgnum

+msgnum

Enables printing of message msgnum

4.30.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
Errors cannot be disabled. Warnings may be disabled using setting 2. Messages may
be disabled using settings 1 or 2. Also, messages may be disabled individually.
However, the setting of 0, 1, or 2 overrides individual message disabling or enabling.
Be careful about disabling warnings and messages, as this can make debugging of
your code more difficult.
The most common usage for this directive is to suppress “MESSAGE 302 - Operand
Not in bank 0, check to ensure bank bits are correct”. See the Simple Example for how
to do this.

4.30.4

See Also

list error

4.30.5

Simple Example

errorlevel -302 ;
;
:
errorlevel +302 ;
;
:
end

4.30.6

Turn off banking message
known tested (good) code
Enable banking message
untested code

Application Example - errorlevel

This program demonstrates the errorlevel assembler directive, which sets the type
of messages that are printed in the listing file and error file.
#include p16f877a.inc

;Include standard header file
;for the selected device.

errorlevel 0

;Display/print messages,
;warnings and errors.

messg "CAUTION: This program has errors" ;display on build

DS33014L-page 108

 1994-2013 Microchip Technology Inc.

Directives
This message will display/print for error level 0.
errorlevel 1

;Display/print only warnings
;and errors.

messg "CAUTION: This program has errors" ;display message

This message will NOT display/print for error level 1 or 2.
group1 udata
group1_var1

0x20
res 1

;Label of this directive is not
;at column 1. This will generate
;a warning number 207.

Warning #207 will display/print for error level 0 or 1.
errorlevel

-207

group1_var2

errorlevel

group2

;This disables warning whose
;number is 207.

res 1

+207

;label of this directive is also
;not at column 1, but no warning
;is displayed/printed.
;This enables warning whose
;number is 207

udata

errorlevel 2
group2_var1 res

;Display/print only errors
1

;label of this directive is not
;at column 1. This will generate
;a warning number 207.

Warning #207 will NOT display/print for error level 2.
errorlevel 1

group2_var2 res

RST

CODE

pagesel
goto
INTRT

 1994-2013 Microchip Technology Inc.

1

0x0

start
start

CODE

pagesel
goto

;Display/print warnings
;and errors.

0x4

service_int
service_int

;label of this directive is not
;at column 1. This will generate
;a warning number 207.
;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;The code section named INTRT is
;placed at 0x4. The next two
;instructions are placed in
;code section INTRT
;Label 'service_int' is not
;defined. Hence this generates
;error[113].

DS33014L-page 109

Assembler/Linker/Librarian User’s Guide
Error 113 will always display/print, regardless of error level.
PGM

CODE

start
movwf group1_var1
goto $
end

DS33014L-page 110

;This is the beginning of the code
;section named 'PGM'. It is a
;relocatable code section since
;no absolute address is given along
;with directive CODE.

;Go to current line (loop here)

 1994-2013 Microchip Technology Inc.

Directives
4.31

exitm - EXIT FROM A MACRO
4.31.1

Syntax

exitm

4.31.2

Description

Force immediate return from macro expansion during assembly. The effect is the same
as if an endm directive had been encountered.

4.31.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
Use this directive to prematurely end a macro, usually for a specific condition. This is
similar to the C language command break.

4.31.4

See Also

endm macro

4.31.5

Simple Example

test macro filereg
if filereg == 1 ; check for valid file
exitm
else
error "bad file assignment"
endif
endm

4.31.6

Application Example - exitm

This program demonstrates the exitm assembler directive, which causes an
immediate exit from a macro. It is used in the example to exit from the macro when
certain conditions are met.
#include p16f877a.inc

result

RST

equ

0x20

;Assign value 20H to label
;result.

CODE

0x0

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.

pagesel
goto
add

;Include standard header file
;for the selected device.

MACRO

 1994-2013 Microchip Technology Inc.

start
start
num1,num2

;'add' is a macro. The values of
;'num1' and 'num2' must be passed
;to this macro.

DS33014L-page 111

Assembler/Linker/Librarian User’s Guide
if num1>0xff
exitm
else
if num2>0xff
exitm

;If num1>255 decimal,
;force immediate return from
;macro during assembly.
;If num2>255 decimal,
;force immediate return from
;macro during assembly.

else
movlw

num1

;Load W register with a literal
;value assigned to the label
;'num1'.

movwf

result

;Load W register to an address
;location assigned to the label
;'result'.

movlw

num2

;Load W register with a literal
;value assigned to the label
;'num2'.

addwf

result

;Add W register with the memory
;location addressed by 'result'
;and load the result back to
;'result'.

endif
endif
endm
org

0010

start

add

;End of 'add' MACRO
;My main program starts at 10H.
;The label 'start' is assigned an
;address 10H.

.100,.256

;Call 'add' MACRO with decimal
;numbers 100 and 256 assigned to
;'num1' and 'num2' labels,
;respactively. EXTIM directive in
;macro will force return.
;Remember '.' means decimal, not
;floating point.

end

DS33014L-page 112

 1994-2013 Microchip Technology Inc.

Directives
4.32

expand - EXPAND MACRO LISTING
4.32.1

Syntax

expand

4.32.2

Description

Expand all macros in the listing file. (This is the default behavior.) This directive is
roughly equivalent to the /m or -m- MPASM assembler command line option, but may
be disabled by the occurrence of a subsequent noexpand.

4.32.3

Usage

This directive is used in the following types of code: absolute. For information on types
of code, see Section 1.6 “Assembler Operation”.
This directive may be useful when exploring a small range of code with many macros
in it.

4.32.4

See Also

macro noexpand

4.32.5

Simple Example

Code example:
:
;Define a macro to add two numbers
add macro num1,num2
movlw num1
movwf result
movlw num2
addwf result
endm
:
expand
;Use macro add
add
.100,.90

Resulting listing file:

0010
0011
0012
0013

3064
00A0
305A
07A0

 1994-2013 Microchip Technology Inc.

00029
00030
M
M
M
M
00031

expand
add .100,.90
movlw .100
movwf result
movlw .90
addwf result

DS33014L-page 113

Assembler/Linker/Librarian User’s Guide
4.33

extern - DECLARE AN EXTERNALLY DEFINED LABEL
4.33.1

Syntax

extern label [, label...]

4.33.2

Description

This directive declares symbol names that may be used in the current module but are
defined as global in a different module.
The extern statement must be included before the label is used. At least one label
must be specified on the line. If label is defined in the current module, MPASM
assembler will generate a duplicate label error.

4.33.3

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
As soon as you have more than one file in your project, you may use this directive.
extern will be used in a file when a label (usually a variable) is used by that file.
global will be used in another file so that the label may be seen by other files. You
must use both directives as specified or the label will not be visible to other files.

4.33.4

See Also

global idata udata udata_acs udata_ovr udata_shr

4.33.5

Simple Example

extern Function
:
call Function

4.33.6

Application Example - extern/global

The program main.asm, along with sub.asm, demonstrate the global and extern
directives, which make it possible to use symbols in modules other than where they are
defined. This allows a project to be split up into multiple files (two in this example) for
code reuse.
;*******************************************************
;main.asm
;*******************************************************
#include p16f877a.inc ;Include standard header file
;for the selected device.
UDATA
delay_value

DS33014L-page 114

res

1

GLOBAL

delay_value

;The variable 'delay_value',
;declared GLOBAL in this
;module, is included in an
;EXTERN directive in the module
;sub.asm.

EXTERN

delay

;The variable 'delay', declared
;EXTERN in this module, is
;declared GLOBAL in the module
;sub.asm.

 1994-2013 Microchip Technology Inc.

Directives
RST

CODE

pagesel
goto
PGM

0x0

start
start

CODE

start
movlw
movwf
xorlw
call
goto
end

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.

D'10'
delay_value
0x80
delay
start

;*******************************************************
;sub.asm
;*******************************************************
#include p16f877a.inc ;Include standard header file
;for the selected device.
GLOBAL

delay

;The variable 'delay' declared
;GLOBAL in this module is
;included in an EXTERN directive
;in the module main.asm.

EXTERN

delay_value

;The variable 'delay_value'
;declared EXTERN in this module
;is declared GLOBAL in the
;module main.asm.

PGM

CODE

delay
decfsz delay_value,1
goto
delay
return
end

 1994-2013 Microchip Technology Inc.

DS33014L-page 115

Assembler/Linker/Librarian User’s Guide
4.34

fill - SPECIFY PROGRAM MEMORY FILL VALUE
4.34.1

Syntax

[label] fill expr,count

4.34.2

Description

Generates count occurrences of the program word or byte (PIC18 devices), expr. If
bounded by parentheses, expr can be an assembler instruction.

4.34.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
Note:

For relocatable code, do not use a symbol in another section in the
expression expr.

This directive is often used to force known data into unused program memory. This
helps ensure that if code ever branches to an unused area at run-time, a fail-safe
condition occurs. For example, it is not uncommon to see this used with the watchdog
timer (WDT) on a PIC16 device. Unused program memory would be filled with goto or
branch instructions to prevent execution of the clrwdt instruction in code, which
would cause the device to reset. See the device data sheet for more information on the
WDT.

4.34.4

See Also

data dw org

4.34.5

Simple Examples

Example 1: PIC10/12/16 MCU’s
fill 0x1009, 5 ; fill with a constant
fill (GOTO RESET_VECTOR), NEXT_BLOCK-$

Example 2: PIC18 Devices
#include p18f252.inc
org 0x12
failsafe goto $
org 0x100
fill (goto failsafe), (0x8000-$)/2 ;Divide by 2 for
;2-word instructions
end

DS33014L-page 116

 1994-2013 Microchip Technology Inc.

Directives
4.34.6

PIC16 Application Example - fill

The fill directive is used to specify successive program memory locations with a
constant or an assembly instruction.
#include p16f877a.inc

RST

CODE

pagesel
goto
fill

INTRPT

start
fill
goto

start
start

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.

0, INTRPT-$

;Fill with 0 up to address 3 ;INTRPT addr. minus current addr.

CODE

;The code section named INTRPT
;is placed at program memory
;location 0x4. The next two
;instructions are placed in
;code section INTRPT.
;Jumps to the location labelled
;ISR.

pagesel
goto
fill

0x0000

;Include standard header file
;for the selected device.

0x0004

ISR
ISR

(goto start), start-$ ;Fill up to address 0Fh with
;instruction .
CODE
0x0010
;Write your main program here.
(nop),
$

ISR
retfie
end

 1994-2013 Microchip Technology Inc.

5

;Fill 5 locations with NOPs.
;Go to current line (loop here)
;Write your interrupt service
;routine here.

DS33014L-page 117

Assembler/Linker/Librarian User’s Guide
4.34.7

PIC18 Application Example - fill

The fill directive is used to specify successive program memory locations with a
constant or an assembly instruction. For PIC18 devices, only an even number is
allowed to be specified as a count of locations to be filled.
#include p18f452.inc

RST

CODE

0x0000

goto

start

fill

0, HI_INT-$

HI_INT
goto
fill

CODE 0x0008
INTR_H
(goto start),6

LO_INT
goto
fill

CODE 0x0018
INTR_L
10a9, start-$
CODE

;The code section named RST
;is placed at program memory
;location 0x0. The instruction
;'goto start' is placed in
;code section RST.
;Jumps to the location labelled
;'start'.
;Fills 0 in 2 program memory
;locations: 0004 and 0006 ;HI_INT addr. minus current addr.

;Fills 6 locations (each location
;is 2 bytes wide) with 3 numbers
;of 2 word wide instructions
;

;Fills address 1Ch and 1Eh with
;10a9h

0x0020

start

;Write your main program here

fill

(nop),

goto

$

INTR_H
retfie
INTR_L
retfie
end

DS33014L-page 118

;Include standard header file
;for the selected device.

4

;Fills 2 locations (4 bytes) with
;NOP
;Go to current line (loop here)
;Write your high interrupt ISR here
;Write your low interrupt ISR here

 1994-2013 Microchip Technology Inc.

Directives
4.35

global - EXPORT A LABEL
4.35.1

Syntax

global label [, label...]

4.35.2

Description

This directive declares symbol names that are defined in the current module and
should be available to other modules. At least one label must be specified on the line.

4.35.3

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
When your project uses more than one file, you will be generating linkable object code.
When this happens, you may use the global and extern directives.
global is used to make a label visible to other files. extern must be used in the file
that uses the label to make it visible in that file.

4.35.4

See Also

extern idata udata udata_acs udata_ovr udata_shr

4.35.5

Simple Example
global Var1, Var2
global AddThree

udata
res 1
res 1
code
AddThree
addlw 3
return
Var1
Var2

4.35.6

Application Example - extern/global

See this example under extern.

 1994-2013 Microchip Technology Inc.

DS33014L-page 119

Assembler/Linker/Librarian User’s Guide
4.36

idata - BEGIN AN OBJECT FILE INITIALIZED DATA SECTION
4.36.1

Syntax

[label] idata [RAM_address]

4.36.2

Description

This directive declares the beginning of a section of initialized data. If label is not
specified, the section is named .idata. The starting address is initialized to the
specified address or will be assigned at link time if no address is specified. No code can
be placed by the user in this segment.
The linker will generate a look-up table entry for each byte specified in an idata section.
You must then link or include the appropriate initialization code. Examples of
initialization code that may be used and modified as needed may be found with
MPLINK linker sample application examples.
Note:

This directive is not available for 12-bit instruction width (PIC10, some
PIC12/PIC16) devices.

The res, db and dw directives may be used to reserve space for variables. res will
generate an initial value of zero. db will initialize successive bytes of RAM. dw will
initialize successive bytes of RAM, one word at a time, in low-byte/high-byte order.
Data initialized using db or dw will be padded with 34 (RETLW) instead of 00. This is
because the idata directive reserves space in data memory while putting the
initialization values in program memory and the application code must then copy the
initialization values from program memory to data memory at runtime.

4.36.3

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
Use this directive to initialize your variables, or use a udata directive and then initialize
your variables with values in code. It is recommended that you always initialize your
variables. Relying on RAM initialization can cause problems, especially when using an
emulator, as behavioral differences between the emulator and the actual part may
occur.
This directive cannot be used across banks.

4.36.4

See Also

extern global udata udata_acs udata_ovr udata_shr

4.36.5
LimitL
LimitH
Gain
Flags
String

DS33014L-page 120

Simple Example
idata
dw 0
dw D'300'
dw D'5'
db 0
db 'Hi there!'

 1994-2013 Microchip Technology Inc.

Directives
4.36.6

Application Example - idata

This directive reserves RAM locations for variables and directs the linker to generate a
lookup table that may be used to initialize the variables specified in this section. The
Starting Address of the lookup table can be obtained from the Map (.map) file. If you
don’t specify a value in the idata section, the variables will be initialized with 0.
#include p16f877a.inc

group1

IDATA

0x20

group1_var1

res

1

group1_var2

res

1

group2

IDATA

;Include standard header file
;for the selected device.
;Initialized
;20h.
;group1_var1
;initialized
;group1_var2
;initialized

db

1,2,3,4

group2_var2

dw

0x1234

CODE

pagesel
goto
PGM

CODE

start
goto $
end

 1994-2013 Microchip Technology Inc.

located at 0x20,
with 0.
located at 0x21,
with 0.

;Declaration of group2 data. The
;addresses for variables under
;this data section are allocated
;automatically by the linker.

group2_var1

RST

data at location

0x0

start
start

;4 bytes in RAM are reserved.
;Values will be padded with 34(RETLW).
;1 word in RAM is reserved.
;Values will be padded with 34(RETLW).

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.
;Go to current line (loop here)

DS33014L-page 121

Assembler/Linker/Librarian User’s Guide
4.37

idata_acs - BEGIN AN OBJECT FILE INITIALIZED DATA SECTION IN
ACCESS RAM (PIC18 MCUs)
4.37.1

Syntax

[label] idata_acs [RAM_address]

4.37.2

Description

This directive declares the beginning of a section of initialized data in Access RAM. If
label is not specified, the section is named .idata_acs. The starting address is
initialized to the specified address or will be assigned at link time if no address is
specified. No code can be placed by the user in this segment.
The linker will generate a look-up table entry for each byte specified in an idata section.
You must then link or include the appropriate initialization code. Examples of
initialization code that may be used and modified as needed may be found with
MPLINK linker sample application examples.
The res, db and dw directives may be used to reserve space for variables. res will
generate an initial value of zero. db will initialize successive bytes of RAM. dw will
initialize successive bytes of RAM, one word at a time, in low-byte/high-byte order.

4.37.3

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
Use this directive to initialize your variables, or use a udata directive and then initialize
your variables with values in code. It is recommended that you always initialize your
variables. Relying on RAM initialization can cause problems, especially when using an
emulator, as behavioral differences between the emulator and the actual part may
occur.

4.37.4

See Also

extern global udata udata_acs udata_ovr udata_shr

4.37.5
LimitL
LimitH
Gain
Flags
String

DS33014L-page 122

Simple Example
idata_acs
dw 0
dw D'300'
dw D'5'
db 0
db 'Hi there!'

 1994-2013 Microchip Technology Inc.

Directives
4.38

__idlocs - SET PROCESSOR ID LOCATIONS
Note:

4.38.1

idlocs is preceded by two underline characters.

Syntax

__idlocs expr
__idlocs addr, expr (PIC18 Only)

4.38.2

Description

For PIC12 and PIC16 devices, __idlocs sets the four ID locations to the hexadecimal
value of expr. For example, if expr evaluates to 1AF, the first (lowest address) ID
location is zero, the second is one, the third is ten, and the fourth is fifteen.
For PIC18 devices, __idlocs sets the two-byte device ID at location addr to the
hexadecimal value of expr.
Before this directive is used, the processor must be declared through the command
line, the list directive, or the processor directive.

4.38.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not commonly used, but does provide an easy method of serializing
devices. __idlocs can be read by a programmer. PIC18 devices can read this value
at run-time, but PIC12/16 devices cannot.

4.38.4

See Also

__config config list processor

4.38.5

Simple Example

Example 1: PIC16 Devices
#include p16f877a.inc
__idlocs

 1994-2013 Microchip Technology Inc.

0x1234

;Include standard header file
;for the selected device.
;Sets device ID to 1234.

DS33014L-page 123

Assembler/Linker/Librarian User’s Guide
Example 2: PIC18 Devices
Note:

The most significant nibble of __idlocs is always 0x0, according to the
programming specification.

#include p18f452.inc

DS33014L-page 124

;Include standard header file
;for the selected device.

__idlocs

_IDLOC0, 0x1

__idlocs

_IDLOC1, 0x2

__idlocs

_IDLOC2, 0x3

__idlocs

_IDLOC3, 0x4

__idlocs

_IDLOC4, 0x5

__idlocs

_IDLOC5, 0x6

__idlocs

_IDLOC6, 0x7

__idlocs

_IDLOC7, 0x8

;IDLOC register 0
;programmed to 1.
;IDLOC register 1
;programmed to 2.
;IDLOC register 2
;programmed to 3.
;IDLOC register 3
;programmed to 4.
;IDLOC register 4
;programmed to 5.
;IDLOC register 5
;programmed to 6.
;IDLOC register 6
;programmed to 7.
;IDLOC register 7
;programmed to 8.

will be
will be
will be
will be
will be
will be
will be
will be

 1994-2013 Microchip Technology Inc.

Directives
4.39

if - BEGIN CONDITIONALLY ASSEMBLED CODE BLOCK
4.39.1

Syntax

Preferred:
if expr

Supported:
#if expr
.if expr

4.39.2

Description

Begin execution of a conditional assembly block. If expr evaluates to true, the code
immediately following the if will assemble. Otherwise, subsequent code is skipped until
an else directive or an endif directive is encountered.
An expression that evaluates to zero is considered logically FALSE. An expression that
evaluates to any other value is considered logically TRUE. The if and while
directives operate on the logical value of an expression. A relational TRUE expression
is guaranteed to return a nonzero value, FALSE a value of zero.
if's may be nested up to 16 deep.

4.39.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not an instruction, but used to control how code is assembled, not how
it behaves at run-time. Use this directive for conditional assembly or to check for a
condition, such as to generate an error message.

4.39.4

See Also

else endif

4.39.5

Simple Example

if version == 100; check current version
movlw 0x0a
movwf io_1
else
movlw 0x01a
movwf io_2
endif

 1994-2013 Microchip Technology Inc.

DS33014L-page 125

Assembler/Linker/Librarian User’s Guide
4.39.6

Application Example - if/else/endif

This program demonstrates the utility of if, else and endif assembly directives.
#include p16f877a.inc

;Include standard header file
;for the selected device.

variable cfab

;variable used to define
;required configuration of
;PORTA & PORTB

cfab set

;Set config to decimal .1

RST

.1

CODE

pagesel
goto
PGM

0x0

start
start

CODE

start
banksel TRISA
if cfab==0x0
clrw
movwf TRISA
movlw 0xff
movwf TRISB
else
clrw
movwf TRISB
movlw 0xff
movwf TRISA
endif
goto
end

DS33014L-page 126

$

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.

;If config==0x0 is true,
;assemble the mnemonics up to
;the directive 'else'. Set up PORTA
;as output.

;If config==0x0 is false,
;assemble the mnemonics up to
;the directive 'endif'. Set up PORTB
;as output.

;Go to current line (loop here)

 1994-2013 Microchip Technology Inc.

Directives
4.40

ifdef - EXECUTE IF SYMBOL HAS BEEN DEFINED
4.40.1

Syntax

Preferred:
ifdef label

Supported:
#ifdef label

4.40.2

Description

If label has been previously defined, usually by issuing a #define directive or by
setting the value on the MPASM assembler command line, the conditional path is
taken. Assembly will continue until a matching else or endif directive is encountered.

4.40.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not an instruction, but used to control how code is assembled, not how
it behaves at run-time. Use this directive for removing or adding code during
debugging, without the need to comment out large blocks of code.

4.40.4

See Also

#define #undefine else endif ifndef

4.40.5

Simple Example

#define testing 1
; set testing "on"
:
ifdef testing
 ; this path would be executed.
endif

4.40.6

Application Example - ifdef

#include p16f877a.inc
#define AlternateASM ;Comment out with ; if extra
;features not desired.
#ifdef AlternateASM
MyPort equ PORTC
;Use Port C if AlternateASM defined.
MyTris equ TRISC
;TRISC must be used to set data
;direction for PORTC.
#else
MyPort equ PORTB
MyTris equ TRISB

;Use Port B if AlternateASM not defined.
;TRISB must be used to set data
;direction for PORTB.

#endif
banksel
clrf
banksel
movlw
movwf
end

 1994-2013 Microchip Technology Inc.

MyTris
MyTris
MyPort
55h
MyPort

;Set port to all outputs.
;Return to bank used for port.
;Move arbitrary value to W reg.
;Load port selected with 55h.

DS33014L-page 127

Assembler/Linker/Librarian User’s Guide
4.40.7

Application Example 2 - ifdef

This program uses the control directive #define, along with the ifdef, else and
endif directives to selectively assemble code for use with either an emulator or an
actual part. The control directive #define is used to create a “flag” to indicate how to
assemble the code - for the emulator or for the actual device.
#include p18f452.inc
#define EMULATED
.
.
INIT
#ifdef EMULATED
movlw 0xb0
movwf 0xf9c
#endif
.
.

DS33014L-page 128

;Comment out with ; if actual part

;If emulator used, add lines of
;initialization code to work around
;table read limitation.

 1994-2013 Microchip Technology Inc.

Directives
4.41

ifndef - EXECUTE IF SYMBOL HAS NOT BEEN DEFINED
4.41.1

Syntax

Preferred:
ifndef label

Supported:
#ifndef label

4.41.2

Description

If label has not been previously defined, or has been undefined by issuing an
#undefine directive, then the code following the directive will be assembled.
Assembly will be enabled or disabled until the next matching else or endif directive
is encountered.

4.41.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not an instruction, but used to control how code is assembled, not how
it behaves at run-time. Use this directive for removing or adding code during
debugging, without the need to comment out large blocks of code.

4.41.4

See Also

#define #undefine else endif ifdef

4.41.5

Simple Example

#define

testing1
:
#undefine testing1
ifndef testing
:
endif
end

4.41.6

; set testing on
; set testing off
; if not in testing mode
; execute this path
; end of source

Application Example - ifndef

#include p16f877a.inc
#define UsePORTB
;Comment out with ; to use PORTC
#ifndef UsePORTB
MyPort equ PORTC
MyTris equ TRISC

#else
MyPort equ PORTB
MyTris equ TRISB

;Use Port C if UsePORTB not defined.
;TRISC must be used to set data
;direction for PORTC.

;Use Port B if UsePORTB defined.
;TRISB must be used to set data
;direction for PORTB.

#endif
banksel
clrf
banksel
movlw
movwf
end

 1994-2013 Microchip Technology Inc.

MyTris
MyTris
MyPort
55h
MyPort

;Set port to all outputs.
;Return to bank used for port.
;Move arbitrary value to W reg.
;Load port selected with 55h.

DS33014L-page 129

Assembler/Linker/Librarian User’s Guide
4.42

#include - INCLUDE ADDITIONAL SOURCE FILE
4.42.1

Syntax

Preferred:
#include include_file
#include "include_file"
#include 

Supported:
include include_file
include "include_file"
include 

4.42.2

Description

The specified file is read in as source code. The effect is the same as if the entire text
of the included file were inserted into the file at the location of the include statement.
Upon end-of-file, source code assembly will resume from the original source file. Up to
5 levels of nesting are permitted. Up to 255 include files are allowed.
If include_file contains any spaces, it must be enclosed in quotes or angle
brackets. If a fully qualified path is specified, only that path will be searched. Otherwise,
the search order is:
• current working directory
• source file directory
• MPASM assembler executable directory

4.42.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
You should use the include directive once to include that standard header file for your
selected processor. This file contains defined register, bit and other names for a
specific processor, so there is no need for you to define all of these in your code.

4.42.4

See Also

#define #undefine

4.42.5

Simple Example

#include p18f452.inc ;standard include file
#include "c:\Program Files\mydefs.inc" ;user defines

DS33014L-page 130

 1994-2013 Microchip Technology Inc.

Directives
4.43

list - LISTING OPTIONS
4.43.1

Syntax

list [list_option, ..., list_option]

4.43.2

Description

Occurring on a line by itself, the list directive has the effect of turning listing output on,
if it had been previously turned off. Otherwise, one of a list of options can be supplied
to control the assembly process or format the listing file.

4.43.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
TABLE 4-2:
Option

LIST DIRECTIVE OPTIONS
Default

Description

b=nnn

8

Set tab spaces.

c=nnn

132

Set column width.

f=format

INHX8
M

Set the hex file output. format can be INHX32, INHX8M, or
INHX8S.
Note: Hex file format is set in the IDE (Build Options dialog.)

free

FIXED

Use free-format parser. Provided for backward compatibility.

fixed

FIXED

Use fixed-format parser.

mm={ON|OFF} On

Print memory map in list file.

n=nnn

60

Set lines per page.

p=type

None

Set processor type; for example, PIC16F877. See also
processor.
Note: Processor type is set in MPLAB IDE or MPLAB X IDE
projects.

pe=type

None

Set processor type and enable extended instruction set, for
example; LIST pe=PIC18F4620
Only valid with processors which support the extended instruction
set and the generic processor PIC18XXX. Is overridden by
command-line option /y- or -y- (disable extended instruction set).
Note: Processor type is set in MPLAB IDE or MPLAB X IDE
projects.

r=radix

hex

Set radix: hex, dec, oct. See also radix.

st={ON|OFF} On

Print symbol table in list file.

t={ON|OFF}

Off

Truncate lines of listing (otherwise wrap).

w={0|1|2}

0

Set the message level. See also errorlevel.

x={ON|OFF}

On

Turn macro expansion on or off.

Note:

4.43.4

All list options are evaluated as decimal numbers by default.

See Also

errorlevel expand noexpand nolist processor radix

4.43.5

Simple Example

Set the processor type to PIC18F452, the hex file output format to INHX32 and the
radix to decimal.
list p=18f452, f=INHX32, r=DEC

 1994-2013 Microchip Technology Inc.

DS33014L-page 131

Assembler/Linker/Librarian User’s Guide
4.44

local - DECLARE LOCAL MACRO VARIABLE
4.44.1

Syntax

Preferred:
local label[,label...]

Supported:
.local label[,label...]

4.44.2

Description

Declares that the specified data elements are to be considered in local context to the
macro. label may be identical to another label declared outside the macro definition;
there will be no conflict between the two.
If the macro is called recursively, each invocation will have its own local copy.

4.44.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
If you use a macro more than once and there is a label in it, you will get a “Duplicate
Label” error unless you use this directive.

4.44.4

See Also

endm macro

4.44.5

Simple Example



:
:
len
equ 10
size equ 20

; global version
; note that a local variable
; may now be created and modified

test

macro size
local len, label ; local len and label
len
set size
; modify local len
label res len
; reserve buffer
len
set len-20
endm
; end macro

4.44.6

Application Example - local

This code demonstrates the utility of local directive, which declares that the specified
data elements are to be considered in local context to the macro.
#include p16f877a.inc

incr

equ

2

add_incr macro
local incr

DS33014L-page 132

;Include standard header file
;for the selected device.
;Assembler variable incr is set
;equal to 2.
;Declaration of macro 'add_incr'.
;Local assembler variable 'incr'.

 1994-2013 Microchip Technology Inc.

Directives
The same name incr is used in the main code, where its value is set to 2.
incr

set

clrw
addlw

3

;Local 'incr' is set to 3, in
;contrast to 'incr' value
;of 2 in main code.
;w register is set to zero
;w register is added to incr and
;result placed back
;in w register.

incr

endm
RST

CODE

pagesel
goto
PGM

0x0

start
start

CODE

start
clrw

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.
;W register set to zero.

addlw

incr

;W register is added with the
;value of incr which is now equal
;to 2.

add_incr

;W register is added with the
;value of incr which is now equal
;to 3 (value set locally in the
;macro add_incr).

clrw

;W register is set to zero again.

addlw

goto
end

incr

$

 1994-2013 Microchip Technology Inc.

;incr is added to W register and
;result placed in W register.
;incr value is again 2, not
;affected by the value set in the
;macro.
;Go to current line (loop here)

DS33014L-page 133

Assembler/Linker/Librarian User’s Guide
4.45

macro - DECLARE MACRO DEFINITION
4.45.1

Syntax

label macro [arg, ..., arg]

4.45.2

Description

A macro is a sequence of instructions that can be inserted in the assembly source code
by using a single macro call. The macro must first be defined, then it can be referred to
in subsequent source code.
Arguments are read in from the source line, stored in a linked list and then counted.
The maximum number of arguments would be the number of arguments that would fit
on the source line, after the label and macro terms. Therefore, the maximum source
line length is 200 characters.
A macro can call another macro, or may call itself recursively. The maximum number
of nested macro calls is 16.
Please refer to Chapter 7. “Macro Language” for more information.

4.45.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.

4.45.4

See Also

endm exitm local

4.45.5

Simple Example

;Define macro Read
Read macro device, buffer, count
movlw device
movwf ram_20
movlw buffer ; buffer address
movwf ram_21
movlw count
; byte count
call sys_21
; subroutine call
endm
:
;Use macro Read
Read 0x0, 0x55, 0x05

DS33014L-page 134

 1994-2013 Microchip Technology Inc.

Directives
4.45.6

Application Example - macro/endm

This code demonstrates the utility of macro directive, which is used to define a macro.
#include p16f877a.inc

result

equ

ORG

0x0000

goto

start

add

MACRO

0x20

num1,num2

;Include standard header file
;for the selected device.
;Assign value 20H to label
;result.
;The following code will be placed
;in reset address 0.
;Jump to an address whose label is
;'start'.
;'add' is a macro. The values of
;'num1' and 'num2' must be passed
;to this macro.

movlw

num1

;Load W register with a literal
;value assigned to the label
;'num1'.

movwf

result

;Load W register to an address
;location assigned to the label
;'result'.

movlw

num2

;Load W register with a literal
;value assigned to the label
;'num2'.

addwf

result

;Add W register with the memory
;location addressed by 'result'
;and load the result back to
;'result'.

endm
ORG

;end of 'add' MACRO
0x0010

start

add

;Main program starts at 10H.
;The label 'start' is assigned an
;address 10H.

.100,.90

;Call 'add' MACRO with decimal
;numbers 100 and 90 assigned to
;'num1' and 'num2' labels,
;respectively. 100 and 90 will be
;added and the result will be in
;'result'.

end

 1994-2013 Microchip Technology Inc.

DS33014L-page 135

Assembler/Linker/Librarian User’s Guide
4.46

__maxram - DEFINE MAXIMUM RAM LOCATION
Note:

4.46.1

maxram is preceded by two underline characters.

Syntax

__maxram expr

4.46.2

Description

The __maxram and __badram directives together flag accesses to unimplemented
registers. __maxram defines the absolute maximum valid RAM address and initializes
the map of valid RAM addresses to all addresses valid at and below expr. expr must
be greater than or equal to the maximum page 0 RAM address and less than 1000H.
This directive is designed for use with the __badram directive. Once the
__maxram directive is used, strict RAM address checking is enabled, using the RAM
map specified by __badram.
__maxram can be used more than once in a source file. Each use redefines the
maximum valid RAM address and resets the RAM map to all locations.

4.46.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not commonly used in user code, as RAM and ROM details are
handled by the include files (*.inc) or linker script files (*.lkr).

4.46.4

See Also

__badram

4.46.5

Simple Example

See the examples for badram.

DS33014L-page 136

 1994-2013 Microchip Technology Inc.

Directives
4.47

__maxrom - DEFINE MAXIMUM ROM LOCATION
Note:

4.47.1

maxrom is preceded by two underline characters.

Syntax

__maxrom expr

4.47.2

Description

The __maxrom and __badrom directives together flag accesses to unimplemented
registers. __maxrom defines the absolute maximum valid ROM address and initializes
the map of valid ROM addresses to all addresses valid at and below expr. expr must
be greater than or equal to the maximum ROM address of the target device. This
directive is designed for use with the __badrom directive. Once the __maxrom
directive is used, strict ROM address checking is enabled, using the ROM map
specified by __badrom.
__maxrom can be used more than once in a source file. Each use redefines the
maximum valid ROM address and resets the ROM map to all locations.

4.47.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not commonly used in user code, as RAM and ROM details are
handled by the include files (*.inc) or linker script files (*.lkr).

4.47.4

See Also

__badrom

4.47.5

Simple Example

See the examples for badrom.

 1994-2013 Microchip Technology Inc.

DS33014L-page 137

Assembler/Linker/Librarian User’s Guide
4.48

messg - CREATE USER DEFINED MESSAGE
4.48.1

Syntax

messg "message_text"

4.48.2

Description

Causes an informational message to be printed in the listing file. The message text can
be up to 80 characters. Issuing a messg directive does not set any error return codes.

4.48.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive may be used to generate any desired message. It can be useful with
conditional assembly, to verify in the assembled program which code was built.

4.48.4

See Also

error

4.48.5

Simple Example

mssg_macro macro
messg "mssg_macro-001 invoked without argument"
endm

4.48.6

Application Example - messg

This program demonstrates the messg assembler directive, which sets a message to
be printed in the listing file and error file.
#include p16f877a.inc

;Include standard header file
;for the selected device.

variable baudrate

;variable used to define
;required baud rate

baudrate set D'5600'

;Enter the required value of
;baud rate here.

if (baudrate!=D'1200')&&(baudrate!=D'2400')&&
(baudrate!=D'4800')&&(baudrate!=D'9600')&&
(baudrate!=D'19200')
error "Selected baud rate is not supported"
messg "only baud rates 1200,2400,4800,9600 & 19200 Hz "&&
"are supported"
endif

DS33014L-page 138

 1994-2013 Microchip Technology Inc.

Directives
The if-endif code outputs error and messg if the baud rate selected is other than
1200, 2400, 4800, 9600 or 19200 Hz.
RST

CODE

pagesel
goto
PGM

CODE

start
goto $
end

 1994-2013 Microchip Technology Inc.

0x0

start
start

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.
;Go to current line (loop here)

DS33014L-page 139

Assembler/Linker/Librarian User’s Guide
4.49

noexpand - TURN OFF MACRO EXPANSION
4.49.1

Syntax

noexpand

4.49.2

Description and Usage

Turns off macro expansion in the listing file.
This directive is used in the following types of code: absolute. For information on types
of code, see Section 1.6 “Assembler Operation”.

4.49.3

See Also

expand

4.49.4

Simple Example

Code example:
:
;Define a macro to add two numbers
add macro num1,num2
movlw num1
movwf result
movlw num2
addwf result
endm
:
noexpand
;Use macro add
add
.100,.90

Resulting listing file:
00029
00030
00031

4.50

noexpand
add .100,.90

nolist - TURN OFF LISTING OUTPUT
4.50.1

Syntax

nolist

4.50.2

Description and Usage

Turn off listing file output.
This directive suppresses the information required for the listing file and source-level
debugging. This will prevent the ability to debug the source code.
This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.

4.50.3

See Also

list

DS33014L-page 140

 1994-2013 Microchip Technology Inc.

Directives
4.51

org - SET PROGRAM ORIGIN
4.51.1

Syntax

[label] org expr

4.51.2

Description

Set the program origin for subsequent code at the address defined in expr. If label is
specified, it will be given the value of the expr. If no org is specified, code generation
will begin at address zero.
For PIC18 devices, only even-numbered expr values are allowed.
When generating an object file, the org directive is interpreted as introducing an
absolute CODE section with an internally generated name. For example:
L1: org 0x200

is interpreted as:
.scnname
L1:

CODE 0x200

where .scnname is generated by the assembler, and will be distinct from every name
previously generated in this context.

4.51.3

Usage

This directive is used in the following types of code: absolute. For information on types
of code, see Section 1.6 “Assembler Operation”.
org is commonly used in single-file assembly programs whenever code needs to be
placed at a particular location. Commonly used values are 0x0 (reset), 0x4 (PIC16
device interrupt vector), 0x8 (PIC18 device high-priority interrupt vector) and 0x18
(PIC18 device low-priority interrupt vector).

4.51.4

See Also

fill res end

4.51.5

Simple Example

int_1 org 0x20
; Vector 20 code goes here
int_2 org int_1+0x10
; Vector 30 code goes here

 1994-2013 Microchip Technology Inc.

DS33014L-page 141

Assembler/Linker/Librarian User’s Guide
4.51.6

PIC16 Application Example - org

This example shows the usage of the org directive. Code generation begins at an
address specified by org address. The origin of a data table also can be specified by
this directive. A data table may be placed either in a program memory region or in an
EE data memory region, as in case of a PIC1X device with EE data FLASH.
#include p16f877a.inc

;Include standard header file
;for the selected device.

org

0x0000

goto

Main

;The following code will be
;placed in reset address 0.
;Jump to an address whose label
;is 'Main'.

org

0x0004

goto

int_routine

org

0x0010

Main
;
;
;
goto
org

ch_tbl1

org

ch_tbl2

;The following code section will
;placed starting from address 10H.
;Write your main program here.

Main

;Loop back to 'Main'.

0x0100

;The following code section will
;be placed starting from address
;100H.

int_routine
;
;
;
retfie
org

;The following code will be
;placed in interrupt address 4.
;Jump to an address whose label
;is 'int_routine'.

;Write your interrupt service
;routine here.
;Return from interrupt.

0x1000

da

"PICwithFLASH"

0x2100

de

;You can create a data or
;character table starting from
;any address in program memory.
;In this case the address is
;1000h.
;6 program memory locations
;(starting from 1000h) will
;be filled with six 14-bit
;packed numbers, each
;representing two 7-bit ASCII
;characters.

;The absolute address 2100h is
;mapped to the 0000 location of
;EE data memory in PIC16Fxxx.
;You can create a data or
;character table starting from
;any address in EE data memory.

"PICwithFLASH"

;12 EE data memory locations
;(starting from 0) will be
;filled with 12 ASCII
;characters.

end

DS33014L-page 142

 1994-2013 Microchip Technology Inc.

Directives
4.51.7

PIC18 Application Example - org

This example shows the usage of the org directive. Code generation begins at an
address specified by org address. The origin of a data table also can be specified by
this directive. A data table may be placed either in a program memory region or in an
EE data memory region, as in case of a PIC1X device with EE data FLASH.
#include p18f452.inc

;Include standard header file
;for the selected device.

org

0x0000

goto

Main

;The following code will be
;programmed in reset address 0.
;Jump to an address whose label is
;'Main'.

org

0x0008

goto

int_hi

org

0x0018

goto

int_lo

org

0x0020

Main
;
;
;
goto
org

ch_tbl1

;The following code section will
;be programmed starting from
;address 20H.

Main

;Loop back to 'Main'

0x0100

;The following code section will
;be programmed starting from
;address 100H.

;Write your high priority
;interrupt service routine here.
;Return from interrupt.

0x0200

int_lo
;
;
;
retfie
org

;The following code will be
;programmed in low priority
;interrupt address 18h.
;Jump to an address whose label is
;'int_lo'.

;Write your main program here.

int_hi
;
;
;
retfie
org

;The following code will be
;programmed in high priority
;interrupt address 8.
;Jump to an address whose label is
;'int_hi'.

;The following code section will
;be programmed starting from
;address 200H.

;Write your low priority
;interrupt service routine here.
;Return from interrupt.

0x1000

db

;You can create a data or
;character table starting from any
;address in program memory. In
;this case the address is 1000h.

"PICwithFLASH"

end

 1994-2013 Microchip Technology Inc.

DS33014L-page 143

Assembler/Linker/Librarian User’s Guide
4.52

page - INSERT LISTING PAGE EJECT
4.52.1

Syntax

page

4.52.2

Description and Usage

Inserts a page eject into the listing file.
This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.

4.52.3

See Also

list subtitle title

4.53

pagesel - GENERATE PAGE SELECTING CODE (PIC10/12/16 MCUs)
4.53.1

Syntax

pagesel label

4.53.2

Description

An instruction to the linker to generate page selecting code to set the page bits to the
page containing the designated label. Only one label should be specified. No
operations can be performed on label. label must have been previously defined.
The linker will generate the appropriate page selecting code:
For 12-bit instruction width (PIC10F, some PIC12/PIC16) devices, the appropriate bit
set/clear instructions on the STATUS register will be generated.
For 14-bit instruction width (most PIC12/PIC16) devices, a combination of BSF and
BCF commands will be used to adjust bits 3 and 4 of the PCLATH register. For PIC16
extended devices, a movlp instruction is generated to set the page. If the device
contains only one page of program memory, no code will be generated.
For PIC18 devices, this command will do nothing as these devices do not use paging.

4.53.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive saves you from having to manually code page bit changes. Also, since it
automatically generates code, the code is much more portable.
If you are using relocatable code and your device has more than 2k program memory
(or 0.5K for 12-bit instruction width devices), it is recommended that you use this
directive, especially when code must jump between two or more code sections.
If you wish to indicate the start address of a RETLW table or a jump table for computed
GOTOs, you must use the pageselw directive.

4.53.4

See Also

bankisel banksel

4.53.5

Simple Example

pagesel GotoDest
goto
GotoDest
:
pagesel CallDest
call
CallDest

DS33014L-page 144

 1994-2013 Microchip Technology Inc.

Directives
4.53.6

Application Example - pagesel

This program demonstrates the pagesel directive, which generates the appropriate
code to set/clear PCLATH bits. This allows easier use of paged memory such as found
on PIC16 devices.
#include p16f877a.inc

RST

CODE

pagesel
goto
PGM0

0x0

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.

0x500

;The code section named PGM1 is
;placed at 0x500.

start
start

CODE

start
pagesel

page1_pgm

goto

page1_pgm

PGM1

CODE

page1_pgm
goto $
end

 1994-2013 Microchip Technology Inc.

;Include standard header file
;for the selected device.

0x900

;address bits 12 & 11 of
;page1_pgm are copied to PCLATH
;4 & 3 respectively.

;The code section named PGM1 is
;placed at 0x900. Label
;page1_pgm is located in this
;code section.
;Go to current line (loop here)

DS33014L-page 145

Assembler/Linker/Librarian User’s Guide
4.54

pageselw - GENERATE PAGE SELECTING CODE USING WREG
COMMANDS (PIC10/12/16 MCUs)
4.54.1

Syntax

pageselw label

4.54.2

Description

An instruction to the linker to generate page selecting code to set the page bits to the
page containing the designated label. Only one label should be specified. No
operations can be performed on label. label must have been previously defined.
The linker will generate the appropriate page selecting code. For 12-bit instruction
width (PIC10F, some PIC12/PIC16) devices, the appropriate bit set/clear instructions
on the STATUS register will be generated. For 14-bit instruction width (most
PIC12/PIC16) devices, MOVLW and MOVWF instructions will be generated to modify the
PCLATH. If the device contains only one page of program memory, no code will be
generated.
For PIC18 devices, this command will do nothing as these devices do not use paging.

4.54.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive saves you from having to manually code page bit changes. Also, since it
automatically generates code, the code is much more portable.
If you are using relocatable code and your device has more than 2k program memory
(or 0.5K for 12-bit instruction width devices), it is recommended that you use this
directive, especially when code must jump between two or more code sections.
You must use this directive instead of pagesel if you wish to indicate the start address
of a RETLW table or a jump table for computed GOTOs. Only then will all the 5 top-most
bits of the PC will be loaded with the appropriate value when an 8-bit offset is added to
the PC. The 256-word boundaries will still have to be considered, as discussed in
Application Note AN586.

4.54.4

See Also

bankisel banksel

4.54.5

Simple Example

pageselw CommandTableStart
movlw CommandTableStart
addwf Comm.RxTxByte,w
btfsc STATUS,C
incf PCLATH,f
movwf PCL
CommandTableStart
goto GetVersion
goto GetRTSample
goto Configure
goto Go
goto ReadBuffer
goto AreYouThroughYet
goto CommDone
goto CommDone

DS33014L-page 146

;0x00
;0x01
;0x02
;0x03
;0x04
;0x05
;0x06
;0x07

;Get the byte read and use it to
;index into our jump table. If
;we crossed a 256-byte boundary,
;then increment PCLATH. Then load the
;program counter with computed goto.

-

Get Version
Get Real Time sample
stub
stub
Read Buffer, just sends Vout

 1994-2013 Microchip Technology Inc.

Directives
4.55

processor - SET PROCESSOR TYPE
4.55.1

Syntax

processor processor_type

4.55.2

Description

Sets the processor type to processor_type.

4.55.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not generally used as the processor is set in MPLAB IDE or MPLAB X
IDE projects. If it must be set in code, use processor or the list directive option p=
to set the processor.

4.55.4

See Also

list

4.55.5

Simple Example

processor 16f877a

 1994-2013 Microchip Technology Inc.

;Sets processor to PIC16F877A

DS33014L-page 147

Assembler/Linker/Librarian User’s Guide
4.56

radix - SPECIFY DEFAULT RADIX
4.56.1

Syntax

radix default_radix

4.56.2

Description

Sets the default radix for data expressions. The default radix is hex. Valid radix values
are:
• hex - hexadecimal (base 16)
• dec - decimal (base 10)
• oct - octal (base 8)
You may also specify a radix using the list directive. For specifying the radix of
constants, see Section 3.4 “Numeric Constants and Radix”.

4.56.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
For many programs, the default radix, hex, is used and there is no need to set the radix.
However, if you need to change the radix in your program, you should exercise care,
as all numeric values following the radix declaration will use that radix value. See the
radix example for more on the implications of changing the radix.
Use the radix directive or the list directive option r= to change the radix in your
code.

4.56.4

See Also

list

4.56.5

Simple Example

radix dec

4.56.6

Application Example - radix

This example shows the usage of the radix directive for data presentation. If not
declared, then the default radix is in hex(adecimal).

DS33014L-page 148

list r=dec
#include p16f877a.inc

;Set the radix as decimal.
;Include standard header file
;for the selected device.

movlw
movlw
movlw
movlw

50H
0x50
50O
50

;50 is in hex
;Another way of declaring 50 hex
;50 is in octal
;50 is not declared as hex or
;octal or decimal. So by default
;it is in decimal as default radix
;is declared as decimal.

radix

oct

;Use ’radix’ to declare default
;radix as octal.

movlw
movlw
movlw

50H
0x50
.50

;50 is in hex.
;Another way of declaring 50 hex.
;50 is in decimal.

 1994-2013 Microchip Technology Inc.

Directives
movlw

50

;50 is not declared as hex or
;octal or decimal. So by default
;it is in octal as default radix
;is declared as octal.

radix

hex

;Now default radix is in hex.

movlw
movlw
movlw

.50
50O
50

;50 is declared in decimal.
;50 is declared in octal
;50 is not declared as hex or
;octal or decimal. So by default
;it is in hex as default radix
;is declared as hex.

end

 1994-2013 Microchip Technology Inc.

DS33014L-page 149

Assembler/Linker/Librarian User’s Guide
4.57

res - RESERVE MEMORY
4.57.1

Syntax

[label] res mem_units

4.57.2

Description

Causes the memory location pointer to be advanced from its current location by the
value specified in mem_units. In relocatable code (using MPLINK linker), res can be
used to reserve data storage. In non-relocatable code, label is assumed to be a
program memory address.
Address locations are defined in words for PIC12/16 MCUs, and bytes for PIC18
MCUs.

4.57.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
The most common usage for res is for data storage in relocatable code.

4.57.4

See Also

fill org equ cblock

4.57.5

Simple Example

buffer res 64 ; reserve 64 address locations of storage

4.57.6

Application Example - res

This example shows the advantage of res directive in developing relocatable code.
The program calculates the perimeter of a rectangle. Length and width of the rectangle
will be stored in buffers addressed by length and width. The calculated perimeter
will be stored in the double-precision buffer addressed by perimeter.
#include p18f452.inc

;Include standard header file
;for the selected device.

UDATA

;This directive allows the
;following data to be placed only
;in the data area.

perimeter

res

2

length

res

1

width

res

1

Start

DS33014L-page 150

CODE

0x0000

;Two locations of memory are
;reserved for the label
;'perimeter'. Addresses of the
;memory locations will be
;allocated by the linker.
;One location of memory is
;reserved for the label 'length'.
;Address of the memory location
;will be allocated by the linker.
;One location of memory is
;reserved for the label 'width'.
;Address of the memory location
;will be allocated by the linker.
;Following code will be placed in
;address 0.

 1994-2013 Microchip Technology Inc.

Directives
Here the directive code has the same effect as org. But org is used with MPASM
assembler to generate absolute code and code is used with MPLINK linker to generate
an object file. code is also different in that an address is not normally specified; the
linker handles the allocation of space, both in program Flash and data RAM memory.
goto

PER_CAL
CODE

PER_CAL
clrf perimeter+1
movf

length,w

addwf

width,w

movwf

perimeter

rlf

perimeter+1

rlf

perimeter

rlf

perimeter+1

;Jump to label PER_CAL
;CODE directive here dictates that
;the following lines of code will
;be placed in program memory, but
;the starting address will be
;decided by the linker.

;Clear the high byte of the label
;'perimeter'.
;Move the data present in the
;register addressed by 'length'
;to 'w'.
;Add data in 'w' with data in the
;register addressed by 'width'.
;STATUS register carry bit C
;may be affected.
;Move 'w' to the perimeter low
;byte at address 20H. Carry bit
;is unaffected.
;Increment register 21H if carry
;was generated. Also clear carry
;if bit was set.
;Multiply register 20H by 2.
;Carry bit may be affected.
;Again, increment register 21H
;if carry was generated.

The previous two lines of code will multiply (by left-shifting one bit) the intermediate
result by 2.
goto
end

$

 1994-2013 Microchip Technology Inc.

;Go to current line (loop here)

DS33014L-page 151

Assembler/Linker/Librarian User’s Guide
4.58

set - DEFINE AN ASSEMBLER VARIABLE
4.58.1

Syntax

Preferred:
label set expr

Supported:
label .set expr

4.58.2

Description

label is assigned the value of the valid MPASM assembler expression specified by

expr. The set directive is functionally equivalent to the equ directive except that set
values may be subsequently altered by other set directives.

4.58.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
Because set directive values may be altered by later set directives, set is particularly
useful when defining a variable in a loop (e.g., a while loop.)

4.58.4

See Also

equ variable while

4.58.5
area
width
length
area
length

Simple Example
set
set
set
set
set

4.58.6

0
0x12
0x14
length * width
length + 1

Application Example - set/equ

This example shows the usage of the set directive, used for creating symbols which
may be used in MPASM assembler expressions only. The symbols created with this
directive do not occupy any physical memory location on the microcontroller.
#include p16f877a.inc

;Include standard header file
;for the selected device.

perimeter set

0

area

0

;The label 'perimeter' is
;assigned value 0.
;The label 'area' is assigned
;value 0.

set

The value assigned by the set directive may be reassigned later.
lngth

equ

50H

wdth

equ

25H

;The
;the
;The
;the

label
value
label
value

'lngth' is assigned
50H.
'wdth' is assigned
25H.

The value assigned by the equ directive may not be reassigned later.
perimeter set
area
set

2*(lngth+wdth)
lngth*wdth

;Both 'perimeter' and
;'area' values are
;reassigned.

end

DS33014L-page 152

 1994-2013 Microchip Technology Inc.

Directives
4.59

space - INSERT BLANK LISTING LINES
4.59.1

Syntax

Preferred:
space expr

Supported:
spac expr

4.59.2

Description and Usage

Insert expr number of blank lines into the listing file.
This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.

4.59.3

See Also

list

4.59.4

Simple Example

space 3 ;Inserts three blank lines

4.60

subtitle - SPECIFY PROGRAM SUBTITLE
4.60.1

Syntax

Preferred:
subtitle "sub_text"

Supported:
stitle "sub_text"
subtitl "sub_text"

4.60.2

Description and Usage

sub_text is an ASCII string enclosed in double quotes, 60 characters or less in
length. This directive establishes a second program header line for use as a subtitle in
the listing output.
This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.

4.60.3

See Also

list title

4.60.4

Simple Example

subtitle "diagnostic section"

 1994-2013 Microchip Technology Inc.

DS33014L-page 153

Assembler/Linker/Librarian User’s Guide
4.61

title - SPECIFY PROGRAM TITLE
4.61.1

Syntax

title "title_text"

4.61.2

Description and Usage

title_text is a printable ASCII string enclosed in double quotes. It must be 60
characters or less. This directive establishes the text to be used in the top line of each
page in the listing file.
This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.

4.61.3

See Also

list subtitle

4.61.4

Simple Example

title "operational code, rev 5.0"

4.62

udata - BEGIN AN OBJECT FILE UNINITIALIZED DATA SECTION
4.62.1

Syntax

[label] udata [RAM_address]

4.62.2

Description

This directive declares the beginning of a section of uninitialized data. If label is not
specified, the section is named .udata. The starting address is initialized to the
specified address or will be assigned at link time if no address is specified. No code can
be generated in this segment. The res directive should be used to reserve space for
data.
Note:

4.62.3

Two sections in the same source file are not permitted to have the same
name.

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
For relocatable code, this directive is used to create a data (RAM) section. For absolute
code, do not use this directive. Use directives equ or cblock.
This directive cannot be used across banks.

4.62.4

See Also

extern global idata udata_acs udata_ovr udata_shr

4.62.5

Simple Example

udata
Var1
res 1
Double res 2

DS33014L-page 154

 1994-2013 Microchip Technology Inc.

Directives
4.62.6

Application Example - udata

This program demonstrates the udata directive, which declares the beginning of a
section of uninitialized data. udata does not set (initialize) the starting value of the
variables; you must do this in code.
#include p16f877a.inc

group1

udata

group1_var1
group1_var2
group2

CODE

pagesel
goto
PGM

res
res

1
1

;group1 data
;starting at
;group1_var1
;group1_var2

1
1

;Declaration of group2 data. The
;addresses for variables under
;this data section are allocated
;automatically by the linker.

udata

group2_var1
group2_var2
RST

0x20

res
res

;Include standard header file
;for the selected device.

0x0

start
start

CODE

stored at locations
0x20.
located at 0x20.
located at 0x21.

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.

start
banksel group1_var1
clrf group1_var1
clrf group1_var2
banksel group2_var1
clrf group2_var1
clrf group2_var2
goto
end

$

 1994-2013 Microchip Technology Inc.

;Go to current line (loop here)

DS33014L-page 155

Assembler/Linker/Librarian User’s Guide
4.63

udata_acs - BEGIN AN OBJECT FILE ACCESS UNINITIALIZED DATA
SECTION (PIC18 MCUs)
4.63.1

Syntax

[label] udata_acs [RAM_address]

4.63.2

Description

This directive declares the beginning of a section of access uninitialized data. If label
is not specified, the section is named .udata_acs. The starting address is initialized
to the specified address or will be assigned at link time if no address is specified. This
directive is used to declare variables that are allocated in access RAM of PIC18
devices. No code can be generated in this segment. The res directive should be used
to reserve space for data.
Note:

4.63.3

Two sections in the same source file are not permitted to have the same
name.

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
This directive is similar to udata, except that it is used only for PIC18 devices and will
only place variables in access RAM. PIC18 devices have an area of RAM known as
access RAM. Variables in access memory can be used no matter where the bank
select register (BSR) is pointing. It is very useful for frequently-used and global
variables.

4.63.4

See Also

extern global idata udata udata_ovr udata_shr

4.63.5

Simple Example

udata_acs
Var1
res 1
Double res 2

4.63.6

Application Example - udata_acs

This program demonstrates the udata_acs directive. This directive declares the
beginning of a section of uninitialized data.
#include p18f452.inc

group1

udata_acs

group1_var1
group1_var2
group2

1
1

;group1 data stored at access
;RAM locations starting at 0x20.
;group1_var1 located at 0x20.
;group1_var2 located at 0x21.

1
1

;Declaration of group2 data. The
;addresses for data under this
;section are allocated
;automatically by the linker.
;All addresses be will allocated
;in access RAM space only.

udata_acs

group2_var1
group2_var2

DS33014L-page 156

res
res

0x20

res
res

;Include standard header file
;for the selected device.

 1994-2013 Microchip Technology Inc.

Directives
RST

CODE

goto

PGM

0x0

start

CODE

;The code section named RST
;is placed at program memory
;location 0x0. The instruction
;'goto start' is placed in
;code section RST.
;Jumps to the location labelled
;'start'.
;This is the beginning of the code
;section named PGM. It is a
;relocatable code section
;since no absolute address is
;given along with directive CODE.

start
clrf
clrf

group1_var1,A
group1_var2,A

;group1_var1 initialized to zero
;group1_var2 initialized to zero

clrf
clrf

group2_var1,A
group2_var2,A

;group2_var1 initialized to zero
;group2_var2 initialized to zero

goto
end

$

;Go to current line (loop here)

In the code above, “A” references the access RAM. This A designation can be explicitly
stated by the code, but is not needed since the assembler will automatically locate
variables in access memory, if possible.

 1994-2013 Microchip Technology Inc.

DS33014L-page 157

Assembler/Linker/Librarian User’s Guide
4.64

udata_ovr - BEGIN AN OBJECT FILE OVERLAYED UNINITIALIZED DATA
SECTION
4.64.1

Syntax

[label] udata_ovr [RAM_address]

4.64.2

Description

This directive declares the beginning of a section of overlayed uninitialized data. If
label is not specified, the section is named .udata_ovr. The starting address is
initialized to the specified address or will be assigned at link time if no address is
specified. The space declared by this section is overlayed by all other udata_ovr
sections of the same name. It is an ideal way of declaring temporary variables since it
allows multiple variables to be declared at the same memory location. No code can be
generated in this segment. The res directive should be used to reserve space for data.
Note:

4.64.3

Two sections in the same source file are not permitted to have the same
name.

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
This directive is similar to udata, except that it allows you to reuse data space by
“overlaying” one data area on another. It is used for temporary variables, as each data
section may overwrite (and thus share) the same RAM address locations.

4.64.4

See Also

extern global idata udata udata_acs udata_shr

4.64.5

Simple Example

Temps
Temp1
Temp2
Temp3
Temps
LongTemp1

udata_ovr
res 1
res 1
res 1
udata_ovr
res 2 ; this
; same
LongTemp2 res 2 ; this
; same

DS33014L-page 158

will be a variable at the
location as Temp1 and Temp2
will be a variable at the
location as Temp3

 1994-2013 Microchip Technology Inc.

Directives
4.64.6

Application Example - udata_ovr

This program demonstrates the udata_ovr directive. This directive declares the
beginning of a section of overlayed uninitialized data.
#include p16f877a.inc

same_var

var1
same_var
var2

RST

res

udata_ovr
res

start
banksel var1
movlw 0xFF
movwf var1
comf

1

start
start

CODE

0x20

;Declares an overlayed
;uninitialized data section
;named'same_var' starting at
;location 0x20.

0x20

;Declares an overlayed
;uninitialized data section
;with the same name as the one
;declared above. Thus variables
;var1 and var2 are allocated
;at the same address.

1

CODE

pagesel
goto
PGM

udata_ovr

;Include standard header file
;for the selected device.

0x0

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.
;Any operation on var1 affects
;var2 also since both variables
;are overlaid.

var2

goto $
end

 1994-2013 Microchip Technology Inc.

;Go to current line (loop here)

DS33014L-page 159

Assembler/Linker/Librarian User’s Guide
4.65

udata_shr - BEGIN AN OBJECT FILE SHARED UNINITIALIZED DATA
SECTION (PIC12/16 MCUs)
4.65.1

Syntax

[label] udata_shr [RAM_address]

4.65.2

Description

This directive declares the beginning of a section of shared uninitialized data. If label
is not specified, the section is named .udata_shr. The starting address is initialized
to the specified address or will be assigned at link time if no address is specified. This
directive is used to declare variables that are allocated in RAM that is shared across all
RAM banks (i.e. unbanked RAM). No code can be generated in this segment. The res
directive should be used to reserve space for data.
Note:

4.65.3

Two sections in the same source file are not permitted to have the same
name.

Usage

This directive is used in the following types of code: relocatable. For information on
types of code, see Section 1.6 “Assembler Operation”.
This directive is similar to udata, except that it is only used on parts with memory
accessible from multiple banks. udata_shr sections are used with SHAREBANK
locations in the linker script, where as udata sections are used with DATABANK
locations in the linker script. See the data sheet for the PIC16F873A for a specific
example.

4.65.4

See Also

extern global idata udata udata_acs udata_ovr

4.65.5
Temps
Temp1
Temp2
Temp3

4.65.6

Simple Example
udata_shr
res 1
res 1
res 1

Application Example - udata_shr

This program demonstrates the udata_shr directive. This directive declares the
beginning of a section of shared uninitialized data. This directive is used to declare
variables that are allocated in RAM that is shared across all RAM banks (i.e. unbanked
RAM.)
#include p16f877a.inc

shared_data
var

udata_shr
res

1

bank0_var
udata
var0
res

DS33014L-page 160

0X20
1

;Include standard header file
;for the selected device.
;Declares the beginning of a data
;section named 'shared data',
;which is shared by all banks.
;'var' is the location which can
;be accessed irrespective of
;banksel bits.
;Declares beginning of a data
;section named 'bank0_var',
;which is in bank0. var0 is
;allocated the address 0x20.

 1994-2013 Microchip Technology Inc.

Directives
bank1_var
udata
var1
res

0xa0
1

bank2_var
udata
var2
res

0x120 ;Declares beginning of a data
1 ;section named 'bank2_var',
;which is in bank2. var2 is
;allocated the address 0x120

bank3_var
var3

0x1a0 ;Declares beginning of a data
1 ;section named 'bank3_var',
;which is in bank3. var3 is
;allocated the address 0x1a0

RST

CODE

pagesel
goto
PGM

udata
res

start
start

CODE

start
banksel var0
movlw 0x00
movwf var

0x0

;Declares beginning of a data
;section named 'bank1_var',
;which is in bank1. var1 is
;allocated the address 0xa0

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.
;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.
;Select bank0.
;var is accessible from bank0.

banksel var1
movlw 0x01
movwf var

;Select bank1.

banksel var2
movlw 0x02
movwf var

;Select bank2.

banksel var3
movlw 0x03
movwf var

;Select bank3.

goto
end

;Go to current line (loop here)

$

 1994-2013 Microchip Technology Inc.

;var is accessible from bank1
;also.

;var is accessible from bank2
;also.

;var is accessible from bank3
;also.

DS33014L-page 161

Assembler/Linker/Librarian User’s Guide
4.66

#undefine - DELETE A SUBSTITUTION LABEL
4.66.1

Syntax

#undefine label

4.66.2

Description

label is an identifier previously defined with the #define directive. The symbol

named is removed from the symbol table.

4.66.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is most often used with the ifdef and ifndef directives, which look for
the presence of an item in the symbol table.

4.66.4

See Also

#define #include ifdef ifndef

4.66.5

Simple Example

#define length 20
:
#undefine length

4.66.6

Application Example - #define/#undefine

See this example under #define.

DS33014L-page 162

 1994-2013 Microchip Technology Inc.

Directives
4.67

variable - DECLARE SYMBOL VARIABLE
4.67.1

Syntax

variable label[=expr][,label[=expr]...]

4.67.2

Description

Creates symbols for use in MPASM assembler expressions. Variables and constants
may be used interchangeably in expressions.
The variable directive creates a symbol that is functionally equivalent to those created
by the set directive. The difference is that the variable directive does not require that
symbols be initialized when they are declared.
The variable values cannot be updated within an operand. You must place variable
assignments, increments, and decrements on separate lines.

4.67.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is most used for conditional assembly code.
Note:

4.67.4

variable is not used to declare a run-time variable, but a variable that is
used by the assembler. To create a run-time variable, refer to the directives
res, equ or cblock.

See Also

constant set

4.67.5

Simple Example

variable RecLength=64

; Set Default
; RecLength
constant BufLength=512
; Init BufLength
.
; RecLength may
.
; be reset later
.
; in RecLength=128
.
;
constant MaxMem=RecLength+BufLength ;CalcMaxMem

 1994-2013 Microchip Technology Inc.

DS33014L-page 163

Assembler/Linker/Librarian User’s Guide
4.67.6

Application Example - variable/constant

This example shows the the usage of the variable directive, used for creating
symbols which may be used in MPASM assembler expressions only. The symbols
created with this directive do not occupy any physical memory location of
microcontroller.
#include p16f877a.inc

;Include standard header file
;for the selected device.

variable perimeter=0

;The symbol 'perimeter' is
;initialized to 0
;If a symbol is declared as
;variable, then initialization
;is optional, i.e. it may or may
;not be initialized.

variable area

constant lngth=50H

;The symbol 'lngth' is
;initialized to 50H.
constant wdth=25H
;The symbol 'wdth' is
;initialized to 25H.
;A constant symbol always needs
;to be initialized.
perimeter=2*(lngth+wdth);The value of a CONSTANT cannot
;be reassigned after having been
;initialized once. So 'lngth' and
;'wdth' cannot be reassigned. But
;'perimeter' has been declared
;as variable, and so can be
;reassigned.
area=lngth*wdth
end

DS33014L-page 164

 1994-2013 Microchip Technology Inc.

Directives
4.68

while - PERFORM LOOP WHILE CONDITION IS TRUE
4.68.1

Syntax

Preferred:
while expr
:
endw

Supported:
.while expr
:
.endw

4.68.2

Description

The lines between the while and the endw are assembled as long as expr evaluates
to TRUE. An expression that evaluates to zero is considered logically FALSE. An
expression that evaluates to any other value is considered logically TRUE. A relational
TRUE expression is guaranteed to return a non-zero value; FALSE a value of zero.
A while loop can contain at most 100 lines and be repeated a maximum of 256 times.
while loops can be nested up to 8 deep.

4.68.3

Usage

This directive is used in the following types of code: absolute or relocatable. For
information on types of code, see Section 1.6 “Assembler Operation”.
This directive is not an instruction, but used to control how code is assembled, not how
it behaves at run-time. Use this directive for conditional assembly.

4.68.4

See Also

endw if

4.68.5

Simple Example

while is not executed at run-time, but produces assembly code based on a condition.
View the list file (*.lst) or disassembly window to see the results of this example.
test_mac macro count
variable i
i = 0
while i < count
movlw i
i += 1
endw
endm
start
test_mac 5
end

 1994-2013 Microchip Technology Inc.

DS33014L-page 165

Assembler/Linker/Librarian User’s Guide
4.68.6

Application Example - while/endw

This example shows the usefulness of directive while to perform a loop while a certain
condition is true. This directive is used with the endw directive.
#include p16f877a.inc

;Include standard header file
;for the selected device.

variable i

;Define the symbol 'i' as a
;variable.

mydata udata 0x20
reg_hi res 1
reg_lo res 1

;Allocate RAM for labels
;reg_hi and reg_lo.

RST

;The code section named RST
;is placed at program memory
;location 0x0. The next two
;instructions are placed in
;code section RST.
;Jumps to the location labelled
;’start’.

CODE

pagesel
goto

start
start

shift_right

i=0
while

0x0

macro

i< by_n

by_n

;Beginning of a macro, which
;shifts register data n times.
;Code length generated after
;assembly, varies depending upon
;the value of parameter 'by_n'.
;Initialize variable i.
;Following 3 lines of assembly
;code are repeated as long as
;i< by_n.

Up to 100 lines of codes are allowed inside a while loop.
bcf
rrf
rrf

STATUS,C
reg_hi,F
reg_lo,F

i+=1

;Clear carry bit.
;reg_hi and reg_lo contains
;16-bit data which is rotated
;right through carry.
;Increment loop counter i.

i cannot increment to more than 255 decimal.
endw

;End while loop. The loop will
;break here after i=by_n.
;End of 'shift_right' macro.

endm
PGM

CODE

start
movlw
movwf
movlw
movwf

DS33014L-page 166

0x88
reg_hi
0x44
reg_lo

;This is the beginning of the
;code section named PGM. It is
;a relocatable code section
;since no absolute address is
;given along with directive CODE.

;Initialize reg_hi and
;reg_lo for observation.

 1994-2013 Microchip Technology Inc.

Directives
shift_right

goto
end

$

 1994-2013 Microchip Technology Inc.

3

;Shift right 3 times the 16-bit
;data in reg_hi and reg_lo. This
;is an example. A value 8 will
;shift data 8 times.
;Go to current line (loop here)

DS33014L-page 167

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 168

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 5. Assembler Examples, Tips and Tricks
5.1

INTRODUCTION
The usage of multiple MPASM assembler directives is shown through examples.
Directives are assembler commands that appear in the source code but are not
opcodes. They are used to control the assembler: its input, output, and data allocation.
Many of the assembler directives have alternate names and formats. These may exist
to provide backward compatibility with previous assemblers from Microchip and to be
compatible with individual programming practices. If portable code is desired, it is
recommended that programs be written using the specifications contained within this
document.
For a reference listing of all directives discussed in examples here, please see Chapter
4. “Directives”.
Note:

Although MPASM assembler is often used with MPLINK object linker,
MPASM assembler directives are not supported in MPLINK linker scripts.
See MPLINK object linker documentation for more information on linker
options to control listing and hex file output.

Topics covered are:
•
•
•
•
•
•
•
•

Example of Displaying Count on Ports
Example of Port B Toggle and Delay Routines
Example of Calculations with Variables and Constants
Example of a 32-Bit Delay Routine
Example of SPI Emulated in Firmware
Example of Hexadecimal to ASCII Conversion
Other Sources of Examples
Tips and Tricks

 1994-2013 Microchip Technology Inc.

DS33014L-page 169

Assembler/Linker/Librarian User’s Guide
5.2

EXAMPLE OF DISPLAYING COUNT ON PORTS
Directives highlighted in this example are:
• #include
• end

5.2.1

Program Functional Description

This simple program continually increases the count on PORTA and PORTB. This
count may be displayed in software in the SFR or Watch(es) window of the IDE, or in
hardware on connected LEDs or a scope. The count may be slowed down using a
delay routine (see other examples.)
Once the count has increased to 0xFF, it will roll over to 0x00 and begin again.
The application is written as absolute code, i.e., you use only the assembler to
generate the executable (not the assembler and linker).
The standard header file for the processor selected is included using #include. The
port output data latches are then cleared. Port A must be set up for digital I/O as, on
power-up, several pins are analog. Data direction registers (TRISx) are cleared to set
port pins to outputs. A loop named Loop is entered where the value of each port is
increased indefinitely until the program is halted. Finally, the program is finished with
an end.

5.2.2

Commented Code Listing

;Toggles Port pins with count on PIC18F8720
;PortA pins on POR:
; RA5, RA3:0 = analog inputs
; RA6, RA4 = digital inputs
;PortB pins on POR:
; RB7:0 = digital inputs
#include p18f8720.inc

;Include file needed to reference
;data sheet names.

clrf
clrf

;Clear output data latches on Ports

movlw 0x0F
movwf ADCON1

;Configure Port A for digital I/O

clrf
clrf

TRISA
TRISB

;Set data direction of Ports as outputs

PORTA,F
PORTB,F
Loop

;Read PORTA, add 1 and save back.
;Read PORTB, add 1 and save back.
;Do this repeatedly - count.
;All programs must have an end directive.

Loop
incf
incf
goto
end

DS33014L-page 170

PORTA
PORTB

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
5.3

EXAMPLE OF PORT B TOGGLE AND DELAY ROUTINES
Directives highlighted in this example are:
•
•
•
•

udata, res
equ
code
banksel, pagesel

Items covered in this example are:
•
•
•
•
•
•
•

Program Functional Description
Commented Code Listing
Header Files
Register and Bit Assignments
Program Memory CODE Sections and Paging
Banking
Interrupts

5.3.1

Program Functional Description

This program continually alternates the output on the Port B pins from 1’s to 0’s. Two
delay routines using interrupts provide the timing for the alternating output. If LEDs
were attached to Port B, they would flash (1=on, 0=off).
The type of PIC1X MCU is set in the IDE, so does not need to be set in code. However,
if you wish to specify the MCU, as well as radix, in code, you may do so using the
processor and radix directives, or list command, i.e., list p=16f877a, r=hex.
The application is written as relocatable code, i.e., you must use both the assembler
and linker to generate the executable. See PIC1X MCU Language Tools and MPLAB
X IDE or PIC1X MCU Language Tools and MPLAB IDE v8 for information on how to
set up a project using assembler files and a linker script.
The standard header file for the processor selected is included using #include.
Registers are assigned using the udata, res and equ directives. Sections of code are
created using the code statement. Data memory banking and program memory paging
is accomplished as needed using banksel and pagesel directives. Finally, the
program is finished with an end.

5.3.2

Commented Code Listing

;**************************************
;* MPASM Assembler Control Directives *
;* Example Program 1
*
;* Alternate output on Port B between *
;* 1's and 0's
*
;**************************************
#include p16f877a.inc

 1994-2013 Microchip Technology Inc.

;Include header file

DS33014L-page 171

Assembler/Linker/Librarian User’s Guide
MPLAB X IDE and MPLAB IDE v8 have many header files (*.inc) available for
supported devices. These can be found in the installation directory. See
Section 5.3.3 “Header Files” for more on headers.
udata
DTEMP res 1
DFLAG res 1

;Declare storage of RAM variables
;Reserve 1 address location
;Reserve 1 address location

DFL0

;Set flag bit - 0 bit of DFLAG

equ 0x00

Set DTEMP to be a temporary register at a location in RAM determined at by the linker.
Set DFLAG to be the flag register at a location following the DTEMP register. Set DFL0
to a value to represent a bit in the DFLAG register, in this case 0. See the Additional
Comments section for more information.
rst
code
pagesel Start
goto
Start

0x00

;Reset Vector
;Ensure correct page selected
;Jump to Start code

Place the reset vector at program memory location 0x00. When the program resets, the
program will branch to Start.
intrpt
goto

code
0x04
ServInt

;Interrupt Vector
;Jump to service interrupt

Place interrupt vector code at program memory location 0x04, since this device
automatically goes to this address for interrupts. When an interrupt occurs, the program
will branch to the ServInt routine.
isr
code
ServInt

0x08

;Interrupt Service Routine

banksel OPTION_REG
bsf
OPTION_REG, T0CS

;Select Option Reg Bank (1)
;Stop Timer0

banksel INTCON
bcf
INTCON, T0IF
bcf
DFLAG, DFL0

;Select INTCON Bank (0)
;Clear overflow flag
;Clear flag bit

retfie

;Return from interrupt

For the PIC16F877A, there is not enough memory to add a pagesel ServInt
statement to insure proper paging. Therefore, the ISR code needs to be specifically
placed on page 0. See Section 5.3.7 “Interrupts” for more on the ISR code.
;******************************************
;* Main Program
*
;******************************************
code

DS33014L-page 172

;Start Program

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
Begin program code. Because no address is specified, the program memory location
will be determined by the linker. See Section 5.3.5 “Program Memory CODE
Sections and Paging” for more on code.
Start
clrf

PORTB

;Clear PortB

banksel TRISB
clrf
TRISB

;Select TRISB Bank (1)
;Set all PortB pins as outputs

banksel INTCON
bsf
INTCON, GIE
bsf
INTCON, T0IE

;Select INTCON Bank (0)
;Enable Global Int's
;Enable Timer0 Int

First, set up Port B pins to be all outputs using the data direction (TRISB) register. Then
set up Timer 0 and interrupts for later use.
Loop
movlw
movwf
call

0xFF
PORTB
Delay1

;Set PortB
;Wait

clrf
PORTB
pagesel Delay2
call
Delay2

;Clear PortB
;Select Delay2 Page
;Wait

pagesel Loop
goto
Loop

;Select Loop Page
;Repeat

Set all Port B pins high and wait Delay 1. Then, set all Port B pins low and wait Delay
2. Repeat until program halted. This will have the effect of “flashing” the pins of Port B.
;******************************************
;* Delay 1 Routine - Timer0 delay loop
*
;******************************************
Delay1
movlw
movwf

0xF0
TMR0

clrf
bsf

DFLAG
DFLAG, DFL0

;Set Timer0 value
;0x00-longest delay
;0xFF-shortest delay

;Set flag bit

banksel OPTION_REG
bcf
OPTION_REG, T0CS

;Select Option Reg Bank (1)
;Start Timer0

banksel DFLAG

;Select DFLAG Bank (0)

TLoop
btfsc
goto

DFLAG, DFL0
TLoop

;Wait for overflow: 0xFF->0x00
;After interrupt, DFL0 = 0

return

 1994-2013 Microchip Technology Inc.

DS33014L-page 173

Assembler/Linker/Librarian User’s Guide
Use Timer 0 to create Delay 1. First, give the timer an initial value. Then, enable the
timer and wait for it to overflow from 0xFF to 0x00. This will generate an interrupt, which
will end the delay. See Section 5.3.7 “Interrupts” for more information.
;******************************************
;* Delay 2 Routine - Decrement delay loop *
;******************************************
decdly

code

0x1000

;Page 2

Place Delay2 routine at program memory location 0x1000, on page 2. (See
Section 5.3.5 “Program Memory CODE Sections and Paging” for more on code.)
This code was placed on a page other than 0 to demonstrate how a program functions
across pages.
Delay2
movlw
movwf

DLoop
decfsz
goto

0xFF
DTEMP

DTEMP, F
DLoop

;Set DTEMP value
;0x00-shortest delay
;0xFF-longest delay
;Use a simple countdown to
;create delay.
;End loop when DTEMP=0

return

Use the time it takes to decrement a register DTEMP from an initial value to 0x00 as
Delay 2. This method requires no timers or interrupts.
end

End of the program, i.e., tells the assembler no further code needs to be assembled.

5.3.3

Header Files

A header file is included in the program flow with the #include directive.
#include p16f877a.inc

;Include header file

Angle brackets, quotes or nothing at all may used to enclose the name of the header
file. You may specify the complete path to the included file, or let the assembler search
for it. For more on search order, see the discussion of the #include directive in
Section 4.42 “#include - Include Additional Source File”
A header file is extremely useful for specifying often-used constants, such as register
and pin names. This information can be typed in once, and then the file can be included
in any code using the processor with those registers and pins.

DS33014L-page 174

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
5.3.4

Register and Bit Assignments

You can specify your own registers and bits by using the udata, res and equ
directives, as is done in the following lines.
udata
DTEMP res 1
DFLAG res 1

;Declare storage of RAM variables
;Reserve 1 address location
;Reserve 1 address location

DFL0

;Set flag bit - 0 bit of DFLAG

equ 0x00

DTEMP and DFLAG are assigned one address location in RAM each by the linker. For
illustrative purposes, suppose the locations selected by the linker are the general
purpose registers (GPRs) 0x20 and 0x21. DFL0 is assigned the value 0x00 and will be
used as the name for pin 0 in the DFLAG register.
FIGURE 5-1:
Special
Function
Registers

General
Purpose
Registers

PIC16F877A REGISTER FILE MAP
0x00
:
ADCON0

0x1F

DTEMP

0x20

DFLAG

0x21

DFL0

:

Bank 0

0x7F
Bank 1

Bank 2

Bank 3

The directives udata and res are used in relocatable code to define multiple registers
instead of equ. For more on these directives, see:
• Section 4.62 “udata - Begin an Object File Uninitialized Data Section”
• Section 4.57 “res - Reserve Memory”
• Section 4.28 “equ - Define an Assembler Constant”

5.3.5

Program Memory CODE Sections and Paging

The code directive is used to specify sections of relocatable code. For absolute code,
the org directive is used. See Chapter 6. “Relocatable Objects” for more on the
differences between relocatable and absolute code. For more on these directives, see:
• Section 4.9 “code - Begin an Object File Code Section”
• Section 4.51 “org - Set Program Origin”
If no code directive is used, code generation will begin at address zero. For this
example, code is used to specify code at 0x00 (reset address), 0x04 (interrupt
address), 0x08 (interrupt service routine) and 0x1000 (Delay 2 address). It does not
explicitly set the program start address, but allows the linker to place the code
appropriately. Since the linker places addressed code first, and then attempts to place
the relocatable code, based on size, the likely program memory usage is shown below.

 1994-2013 Microchip Technology Inc.

DS33014L-page 175

Assembler/Linker/Librarian User’s Guide
FIGURE 5-2:

PIC16F877A PROGRAM MEMORY MAP
rst

Page 0

0x0000

:

:

intrpt

0x0004

:

:

isr

0x0008

:

:

.code (Start)

0x0010

:
0x0800

Page 1
Page 2

:
decdly (Delay2)

0x1000

:

:
0x1800

Page 3

:
0x1FFF

Since the actual location of the main code (.code section) is unknown, pagesel
directives must be used to ensure that program branches to other sections are correct.
rst
code
0x00
pagesel Start
goto
Start
:
code
:
pagesel Delay2
call
Delay2
:
pagesel Loop
goto
Loop
:

;Reset Vector

;Start Program
;Select Delay2 Page
;Wait
;Select Loop Page
;Repeat

For more on this directive, see Section 4.53 “pagesel - Generate Page Selecting
Code (PIC10/12/16 MCUs)”

5.3.6

Banking

In this example, Port B must be configured, causing a switch to data memory bank 1 to
access the TRISB register. This change to bank 1, and subsequent return to bank 0, is
easily accomplished using the banksel directive.
banksel TRISB
clrf
TRISB

;Select TRISB Bank (1)
;Set PortB as output

banksel INTCON
bsf
INTCON, GIE
bsf
INTCON, T0IE

;Select INTCON Bank (0)
;Enable Global Int's
;Enable Timer0 Int

Two other routines also use banksel to access the Option register (OPTION_REG).
For more on this directive, see Section 4.7 “banksel - Generate Bank Selecting
Code”

DS33014L-page 176

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
5.3.7

Interrupts

The Delay 1 routine in this program uses the Timer 0 overflow interrupt as a timing
mechanism. Once the interrupt occurs, the program branches to the interrupt vector.
Here code is located to jump to a location where interrupt-handling code is found.
intrpt
goto

code
0x04
ServInt

;Interrupt Vector
;Jump to service interrupt

The interrupt-handling code, also known as the interrupt service routine or ISR, is
generated by the programmer to handle the specific requirements of the peripheral
interrupt and the program. In this case, Timer 0 is stopped and its flag bit is cleared, so
it may be run again. Then, the program-defined flag bit is cleared. Finally, retfie
takes the program back to the instruction that was about to be executed when the
interrupt occurred.
isr
code
ServInt

0x08

;Interrupt Service Routine

banksel OPTION_REG
bsf
OPTION_REG, T0CS

;Select Option Reg Bank (1)
;Stop Timer0

banksel INTCON
bcf
INTCON, T0IF
bcf
DFLAG, DFL0

;Select INTCON Bank (0)
;Clear overflow flag
;Clear flag bit

retfie

;Return from interrupt

When the program code begins to execute again, the cleared flag bit DFL0 now causes
the delay loop TLOOP to end, thus ending Delay 1 routine.

 1994-2013 Microchip Technology Inc.

DS33014L-page 177

Assembler/Linker/Librarian User’s Guide
5.4

EXAMPLE OF CALCULATIONS WITH VARIABLES AND CONSTANTS
Directives highlighted in this example are:
• #define, #undefine
• set
• constant, variable
Items covered in this example are:
• Program Functional Description
• Commented Code Listing
• Using Watch(es) Windows

5.4.1

Program Functional Description

This program performs several calculations using defined constants and variables.
The application is written as relocatable code, i.e., you must use both the assembler
and linker to generate the executable.
The standard header file for the processor selected is included using #include.
Sections of code are created using the code statement.

5.4.2

Commented Code Listing

;**************************************
;* MPASM Assembler Control Directives *
;* Example Program 2
*
;* Perform calculations
*
;**************************************
#include p16f877a.inc
;Include header file
#define

Tdistance1

50

#define

Tdistance2

25

#undefine

Tdistance2

;Define the symbol
;Tdistance1
;Define the symbol
;Tdistance2
;Remove Tdistance2 from
;the symbol table

The #define directive was used to define two substitution strings: Tdistance1 to
substitute for 50 and Tdistance2 to substitute for 25. Then #undefine was used to
remove Tdistance2 from the symbol table, i.e., Tdistance2 can no longer be used
to substitute for 25.
udata 0x20
distance_reg res 1

;Set up distance_reg
;at GPR 0x20

The udata and res directives are used to assign distance_reg to register 0x20. For
more on these directives, see example 1.
rst code 0x00
pagesel Start
goto
Start

;Reset Vector

code
Start
clrf
distance_reg

;Start Program

movlw
movwf

Tdistance1
distance_reg

constant

DS33014L-page 178

distance1=10

;Clear register
;Move value of Tdistance1
;into distance_reg
;Declare distance1
;a constant symbol

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
Declare a constant symbol, distance1, with a value of 10. Once a constant is
declared, its value cannot be altered.
variable

distance2

;Declare distance2
;a variable symbol

Declare a variable symbol, distance2. The variable directive does not require the
symbol to be initialized when declared.
distance3 set 10

;Define a value for
;the symbol distance3

Define symbol distance3 as 10.
distance2=15
distance2=distance1+distance2

;Give distance2 an
;initial value
;Add distance1
;to distance2

Variable assignments, increments and decrements must be placed on separate lines.
distance3 set 15
distance2=distance2+distance3

movlw
movwf

distance2
distance_reg

goto Start
end

5.4.3

;Change value of distance3
;Add distance3
;to distance2
;Move value of distance2
;into distance_reg
;Loop back to Start

Using Watch(es) Windows

Once the program begins, the value of Tdistance1 is placed into distance_reg.
This can be observed in a Watches window in MPLAB X IDE or a Watch window in
MPLAB IDE v8. The value of distance_reg will become 50. The symbol
Tdistance1 will not be found in the Watch(es) window symbol list, as symbols defined
using the #define directive are not available for viewing in the IDE because they are
not RAM variables.
The final lines of the example program write the final value of distance2 to
distance_reg. If you had a Watch(es) window open to see distance_reg loaded
with the value of 50, you will see it change to 3A. Remember that the radix is
hexadecimal, so hex addition was used to determine the distance2 value.

 1994-2013 Microchip Technology Inc.

DS33014L-page 179

Assembler/Linker/Librarian User’s Guide
5.5

EXAMPLE OF A 32-BIT DELAY ROUTINE
Directives highlighted in this example are:
• macro, endm
• banksel

5.5.1

Program Functional Description

A delay routine is needed in many applications. For this example, delay increments are
20 us, with the routine having a range of 40 us to 23.8 hours. (This assumes a 4 MHz
clock.)

5.5.2

Commented Code Listing

;Each loop takes 20 clocks, or 20 us per loop,
;at 4MHz or 1MIPS clock.
;Turn off in config bits WDT for long simulations
#include p16F877A.inc

Dly0
Dly1
Dly2
Dly3

udata
res
res
res
res

0x20
1
;Stores 4 bytes of data for the delay count
1
;Dly0 is the least significant byte
1
;while Dly3 is the most significant byte
1

Dly32 MACRO DLY
goto $+1
goto $+1

;delay 2 cycles
;delay total of 4 cycles

;Take the delay value argument from the macro, precalculate
;the required 4 RAM values and load the The RAM values Dly3
;though Dly0.
BANKSEL Dly3
movlw
(DLY-1) & H'FF'
movwf
Dly0
movlw
(DLY-1) >>D'08' & H'FF'
movwf
Dly1
movlw
(DLY-1) >>D'16' & H'FF'
;Bytes are shifted and anded by the assembler to make user
;calculations easier.
movwf
Dly2
movlw
(DLY-1) >>D'24' & H'FF'
;Call DoDly32 to run the delay loop.
movwf
Dly3
call
DoDly32
ENDM
;End of Macro definition
RST

CODE 0x00
pagesel TestCode
goto
TestCode

CODE
TestCode
Dly32
nop

DS33014L-page 180

;Reset Vector

;Code starts here
D'50000'

;Max 4 billion+ (runs Dly32 Macro,
;1 sec in this case).
;ZERO STOPWATCH, put breakpoint here.

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
goto

TestCode

;Go back to top of program and
;run the delay again.

;Subroutine, called by the Macro Dly32 (20 Tcy per loop)
DoDly32
movlw
H'FF'
;Start with -1 in W
addwf
btfsc
clrw

Dly0,F
STATUS,C

;LSB decrement
;was the carry flag set?
;If so, 0 is put in W

addwf
btfsc
clrw

Dly1,F
STATUS,C

;Else, we continue.

addwf
btfsc
clrw

Dly2,F
STATUS,C

addwf
btfsc
clrw

Dly3,F
STATUS,C

iorwf
iorwf
iorwf
iorwf

Dly0,W
Dly1,W
Dly2,W
Dly3,W

;Inclusive-OR all variables
;together to see if we have reached
;0 on all of them.

btfss
goto
retlw

STATUS,Z
DoDly32
0

;Test if result of Inclusive-OR's is 0
;It was NOT zero, so continue counting
;It WAS zero, so exit this subroutine.

;0 in W

;0 in W

;0 in W

END

 1994-2013 Microchip Technology Inc.

DS33014L-page 181

Assembler/Linker/Librarian User’s Guide
5.6

EXAMPLE OF SPI EMULATED IN FIRMWARE
Directives highlighted in this example are:
•
•
•
•

list
#define
udata, res
global

5.6.1

Program Functional Description

This program is used to emulate SPI function in firmware.
The application is written as relocatable code, i.e., you must use both the assembler
and linker to generate the executable.
The list directive is used to define the processor and set listing file formatting. The
standard header file for the processor selected is included using #include. SPI
variables are declared using #define. Program registers are assigned using the
udata and res directives. Sections of code are created using the code statement.
External code is accessed using global.

5.6.2

Commented Code Listing

;********************************************************************
; Emulates SPI in firmware
; Place byte in Buffer, call SPI_Out - sends MSB first
;********************************************************************
LIST
#include

P=18F4520


;define processor
;include file

list

c=132, n=0

;132 col, no paging

;********************************************************************
#define Clk LATB,0
#define Dat LATB,1
#define Bus LATB,2

; SPI clock output
; SPI data output
; busy indicator

;********************************************************************
;Variable definitions
udata
Buffer
res 1
; SPI transmit data
Counter
res 1
; SPI transmit bit counter
DelayCtr
res 1
;********************************************************************
code
SPI_Out
clrf
Counter
; init bit counter
bsf
Counter,7
bcf
bcf
bsf

DS33014L-page 182

Clk
Dat
Bus

; clear clock
; clear data out
; indicate busy

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
Lup

movf
andwf

Counter,W
Buffer,W

; get mask
; test selected bit

btfss
bsf

STATUS,Z
Dat

; was result zero?
; set data

bsf
bcf

Clk
Clk

; set clock
; clear clock

bcf

Dat

; clear data

rrncf

Counter,F

; test next bit

btfss
bra

Counter,7
Lup

; done with byte?
; no

bcf

Bus

; indicate not busy

return
;********************************************************************
global
end

 1994-2013 Microchip Technology Inc.

SPI_Out, Buffer

DS33014L-page 183

Assembler/Linker/Librarian User’s Guide
5.7

EXAMPLE OF HEXADECIMAL TO ASCII CONVERSION
Directives highlighted in this example are:
• udata, res
• global

5.7.1

Program Functional Description

This program converts a hexadecimal byte into two ASCII bytes.
The application is written as relocatable code, i.e., you must use both the assembler
and linker to generate the executable.
Program registers are assigned using the udata and res directives. Sections of code
are created using the code statement. External code is accessed using global.

5.7.2

Commented Code Listing

;********************************************************************
; get a hex byte in W, convert to 2 ASCII bytes in ASCIIH:ASCIIL
; req 2 stack levels
;
;********************************************************************
Variables
udata
HexTemp
res 1
ASCIIH
res 1
ASCIIL
res 1
;********************************************************************
code
Hex2ASC
movf
HexTemp,W
andlw
0x0F
; get low nibble
call
DecHex
movwf
ASCIIL
swapf
movf
andlw
call
movwf

HexTemp,F
HexTemp,W
0x0F
DecHex
ASCIIH

; get high nibble

return
;********************************************************************
DecHex
sublw
0x09
; 9-WREG
btfss
STATUS,C
; is nibble Dec?
goto
HexC
; no, convert hex
Dec
movf
andlw
addlw
return
HexC
movf
andlw
addlw
return

DS33014L-page 184

HexTemp,W
0x0F
A'0'

; convert DEC nibble to ASCII

HexTemp,W
0x0F
A'A'-0x0A

; convert HEX nibble to ASCII

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
;********************************************************************
global

Hex2ASC, ASCIIH, ASCIIL

END

5.8

OTHER SOURCES OF EXAMPLES
Short examples of use for each directive are listed under each directive topic. See
Chapter 4. “Directives”.
Examples of use for multiple directives are available from the following sources:
• readme.asm - Serial EEPROM Support
• Application Notes, Technical Briefs
- Website - http://www.microchip.com
• Code Examples and Templates
- MPLAB X IDE/MPLAB IDE v8 installation directory
- Website - http://www.microchip.com

 1994-2013 Microchip Technology Inc.

DS33014L-page 185

Assembler/Linker/Librarian User’s Guide
5.9

TIPS AND TRICKS
To reduce costs, designers need to make the most of the available program memory in
MCUs. Program memory is typically a large portion of the MCU cost. Optimizing the
code helps to avoid buying more memory than needed. Here are some ideas that can
help reduce code size. For more information, see Tips ‘n Tricks (DS40040).
•
•
•
•
•
•

TIP #1: Delay Techniques
TIP #2: Optimizing Destinations
TIP #3: Conditional Bit Set/Clear
TIP #4: Swap File Register with W
TIP #5: Bit Shifting Using Carry Bit
TIP #6: Using External Memory

5.9.1

TIP #1: Delay Techniques

• Use GOTO Next Instruction instead of two NOPs.
• Use CALL Rtrn as quad, 1 instruction NOP (where Rtrn is the exit label from
existing subroutine).
;*************************************************
NOP
NOP
;2 instructions, 2 cycles
;*************************************************
GOTO $+1
;1 instruction, 2 cycles
;*************************************************
Call Rtrn
;1 instruction, 4 cycles
:
Rtrn RETURN
;*************************************************

MCUs are commonly used to interface with the “outside world” by means of a data bus,
LED’s, buttons, latches, etc. Because the MCU runs at a fixed frequency, it will often
need delay routines to meet setup/hold times of other devices, pause for a handshake
or decrease the data rate for a shared bus.
Longer delays are well-suited for the DECFSZ and INCFSZ instructions where a
variable is decremented or incremented until it reaches zero when a conditional jump
is executed. For shorter delays of a few cycles, here a few ideas to decrease code size.
For a two cycle delay, it is common to use two NOP instructions which uses two
program memory locations. The same result can be achieved by using GOTO $+1. The
$ represents the current program counter value in MPASM assembler. When this
instruction is encountered, the MCU will jump to the next memory location. This is what
it would have done if two NOP’s were used, but since the GOTO instruction uses two
instruction cycles to execute, a two-cycle delay was created. This created a two-cycle
delay using only one location of program memory.
To create a four cycle delay, add a label to an existing RETURN instruction in the code.
In this example, the label Rtrn was added to the RETURN of subroutine that already
existed somewhere in the code. When executing CALL Rtrn, the MCU delays two
instruction cycles to execute the CALL and two more to execute the RETURN. Instead
of using four NOP instructions to create a four cycle delay, the same result was
achieved by adding a single CALL instruction.

DS33014L-page 186

 1994-2013 Microchip Technology Inc.

Assembler Examples, Tips and Tricks
5.9.2

TIP #2: Optimizing Destinations

• Destination bit determines W or F for result
• Look at data movement and restructure
Example: A + B  A
MOVF
ADDWF
MOVWF

A,WMOVF
B,WADDWF
A

B,W
A,F

3 instructions2 instructions

Careful use of the destination bits in instructions can save program memory. Here,
register A and register B are summed and the result is put into the A register. A
destination option is available for logic and arithmetic operations. In the first example,
the result of the ADDWF instruction is placed in the working register. A MOVWF
instruction is used to move the result from the working register to register A. In the
second example, the ADDWF instruction uses the destination bit to place the result into
the A register saving an instruction.

5.9.3

TIP #3: Conditional Bit Set/Clear

• To move single bit of data from REGA to REGB
• Precondition REGB bit
• Test REGA bit and fix REGB if necessary
BTFSS
BCF
BTFSC
BSF

REGA,2BCF
REGB,5
REGB,5BTFSC REGA,2
REGA,2BSF
REGB,5
REGB,5

4 instructions3 instructions

One technique for moving one bit from the REGA register to REGB is to perform bit
tests. In the first example, the bit in REGA is tested using a BTFSS instruction. If the
bit is clear, the BCF instruction is executed and clears the REGB bit, and if the bit is set,
the instruction is skipped.The second bit test determines if the bit is set, and if so, will
execute the BSF and set the REGB bit, otherwise the instruction is skipped. This
sequence requires four instructions.
A more efficient technique is to assume the bit in REGA is clear, and clear the REGB
bit, and test if the REGA bit is clear. If so, the assumption was correct and the BSF
instruction is skipped, otherwise the REGB bit is set. The sequence in the second
example uses three instructions because one bit test was not needed.
One important point is that the second example will create a two cycle glitch if REGB
is a port outputting a high. This is caused by the BCF and BTFSC instructions that will
be executed regardless of the bit value in REGA.

 1994-2013 Microchip Technology Inc.

DS33014L-page 187

Assembler/Linker/Librarian User’s Guide
5.9.4

TIP #4: Swap File Register with W

The following macro swaps the contents of W and REG without using a second register.
SWAPWF

MACRO
XORWF
XORWF
XORWF
ENDM

REG
REG,F
REG,W
REG,F

Needs: 0 TEMP registers, 3 Instructions, 3 Tcy
An efficient way of swapping the contents of a register with the working register is to
use three XORWF instructions. It requires no temporary registers and three
instructions. Here’s an example:
W
10101100
10101100
01011100
01011100

5.9.5

REG
01011100
11110000
11110000
10101100

Instruction
XORWF REG,F
XORWF REG,W
XORWF REG,F
Result

TIP #5: Bit Shifting Using Carry Bit

Rotate a byte through carry without using RAM variable for loop count:
• Easily adapted to serial interface transmit routines.
• Carry bit is cleared (except last cycle) and the cycle repeats until the zero bit sets
indicating the end.
list p=12f629
#include p12f629.inc
buffer equ 0x20
bsf
STATUS,C
rlf
buffer,F
Send_Loop
bcf
GPIO,Dout
btfsc STATUS,C
bsf
GPIO,Dout
bcf
STATUS,C
rlf
buffer,F
movf buffer,F
btfss STATUS,Z
goto Send_Loop

;Set ‘end of loop’ flag
;Place first bit into C
;Precondition output
;Check data - 0 or 1?
;Clear data in C
;Place next bit into C
;Force Z bit
;Exit?

Related Topic: TIP #3: Conditional Bit Set/Clear

5.9.6

TIP #6: Using External Memory

To use external memory, the maximum allowable address must be redefined by using
the _MAXROM directive. For example, when using the PIC18F87J10 in extended
microcontroller mode, the _MAXROM directive must be used as follows:
#include 
__MAXROM 0x1FFFFF
; 87J10 Configuration for external memory
CONFIG MODE=XM20, EASHFT=OFF, BW = 16, WAIT=OFF
org
goto

0x0000
0x10000

END

DS33014L-page 188

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 6. Relocatable Objects
6.1

INTRODUCTION
MPASM assembler, used with MPLINK object linker, has the ability to generate and link
precompiled object modules. Writing source code that will be assembled to an object
module is slightly different from writing code used to generate an executable (hex) file
directly. MPASM assembler routines designed for absolute address assembly will
require minor modifications to compile correctly into relocatable object modules.
Topics covered in this chapter:
•
•
•
•
•
•
•
•
•

6.2

Header Files
Program Memory
Low, High and Upper Operators
RAM Allocation
Configuration Bits and ID Locations
Accessing Labels From Other Modules
Paging and Banking Issues
Generating the Object Module
Code Example

HEADER FILES
The Microchip-supplied standard header files (e.g., p18f8720.inc) should be used
when generating object modules. These header files define the special function
registers for the target processor.
EXAMPLE 6-1:

INCLUDE HEADER FILE

#include p18f8720.inc
:

See 4.42 “#include - Include Additional Source File” for more information.

 1994-2013 Microchip Technology Inc.

DS33014L-page 189

Assembler/Linker/Librarian User’s Guide
6.3

PROGRAM MEMORY
Program memory code must be organized into a logical code section. To do this, the
code must be preceded by a code section declaration (See 4.9 “code - Begin an
Object File Code Section”) to make it relocatable.
Absolute Code

Equivalent Relocatable Code

Start clrw
option

code

;Address determined
;by the linker.

Start clrw
option
Prog1 org 0x0100
movlw 0x0A
movwf var1

Prog1 code 0x0100 ;Start at 0x0100
movlw 0x0A
movwf var1

If more than one code section is defined in a source file, each section must have a
unique name. If the name is not specified, it will be given the default name .code.
Each program memory section must be contiguous within a single source file. A section
may not be broken into pieces within a singe source file.
The physical address of the code can be fixed by supplying the optional address
parameter of the code directive. Situations where this might be necessary are:
• Specifying Reset and interrupt vectors
• Ensuring that a code segment does not overlap page boundaries
EXAMPLE 6-2:

RELOCATABLE CODE

Reset code 0x0lFF ;Fixed address
goto Start
Pgm code
;Address determined by the linker
clrw
option

DS33014L-page 190

 1994-2013 Microchip Technology Inc.

Relocatable Objects
6.4

LOW, HIGH AND UPPER OPERATORS
Low, high and upper operators are used to return one byte of a multi-byte label value.
If low is used, only bits 0 through 7 of the expression will be used. If high is used, only
bits 8 through 15 of the expression will be used. If upper is used, only bits 16 through
21 of the expression will be used.
Operator

Definition

low

Return low byte of operand.

high

Return high byte of operand.

upper

Return upper byte of operand.

scnsz_low

Return low byte of section size.

scnsz_high

Return high byte of section size.

scnsz_upper

Return upper byte of section size.

scnend_low

Return low byte of section end operand.

scnend_high

Return high byte of section end operand.

scnend_upper

Return upper byte of section end operand.

scnstart_low

Return low byte of section start operand.

scnstart_high

Return high byte of section start operand.

scnstart_upper

Return upper byte of section start operand.

Operator precedence information may be found in 3.5 “Arithmetic Operators and
Precedence”.
There are some restrictions involving these operators with relocatable symbols. For
example, the low, high and upper operators must be of the form:
[low|high|upper] (relocatable_symbol + constant_offset)

where:
• relocatable_symbol is any label that defines a program or data memory
address
• constant_offset is an expression that is resolvable at assembly time to a value
between -32768 and 32767
Either relocatable_symbol or constant_offset may be omitted.
Operands of the form:
relocatable_symbol - relocatable_symbol

will be reduced to a constant value if both symbols are defined in the same code or data
section.
In addition to section operators, there are section pseudo-instructions.
Pseudo-Instruction

Definition

scnend_lfsr

scnend_lfsr n,s, where n is 0, 1, or 2 (as with the LFSR
instruction) and s is a string which is taken to be the name of a
section. This instruction loads LFSR with the end address of the
section.

scnstart_lfsr

scnstart_lfsr n,s, where n is 0, 1, or 2 (as with the LFSR
instruction) and s is a string which is taken to be the name of a
section. This instruction loads LFSR with the start address of the
section.

These operators and instructions only have meaning when an object file is generated;
they cannot be used when generating absolute code.

 1994-2013 Microchip Technology Inc.

DS33014L-page 191

Assembler/Linker/Librarian User’s Guide
EXAMPLE 6-3:

GENERAL OPERATOR USE

The general operators, low, high and upper, may be used to access data in tables.
The following code example was taken the p18demo.asm file provided with PICDEM
2 Plus demo board. The excerpt shows how “Microchip” is read from the table and
displayed on the demo board LCD.
#include p18f452.inc
:
PROG1 CODE
stan_table
;
"XXXXXXXXXXXXXXXX"
;
data
"
Voltmeter
"
data
"
Buzzer
"
data
" Temperature
"
data
"
Clock
"
data
"RA4=Next RB0=Now"
data
"
Microchip
"
data
" PICDEM 2 PLUS "
data
"RA4=Set RB0=Menu"
data
"RA4= --> RBO= ++"
data
"
RB0 = Exit
"
data
"Volts =
"
data
"Prd.=128 DC=128 "
:

;table for standard code
ptr:
;0
;16
;32
;48
;64
;80
;96
;112
;128
;144
;160
;176

;**************** STANDARD CODE MENU SELECTION *******************
movlw
.80
;send "Microchip" to LCD
movwf
ptr_pos
call
stan_char_1
:
;----Standard code, Place characters on line-1---stan_char_1
call
LCDLine_1
;move cursor to line 1
movlw
.16
;1-full line of LCD
movwf
ptr_count
movlw
UPPER stan_table
;use operators to load
movwf
TBLPTRU
;table pointer values
movlw
HIGH stan_table
movwf
TBLPTRH
movlw
LOW stan_table
movwf
TBLPTRL
movf
ptr_pos,W
addwf
TBLPTRL,F
clrf
WREG
addwfc TBLPTRH,F
addwfc TBLPTRU,F

DS33014L-page 192

 1994-2013 Microchip Technology Inc.

Relocatable Objects
stan_next_char_1
tblrd
*+
movff
TABLAT,temp_wr
call
d_write
decfsz
bra
movlw
movwf
btfss
goto
movlw
movwf
btfss
goto

ptr_count,F
stan_next_char_1
"\n"
TXREG
TXSTA,TRMT
$-2
"\r"
TXREG
TXSTA,TRMT
$-2

;send character to LCD
;move pointer to next char

;move data into TXREG
;next line
;wait for data TX
;move data into TXREG
;carriage return
;wait for data TX

return
:

 1994-2013 Microchip Technology Inc.

DS33014L-page 193

Assembler/Linker/Librarian User’s Guide
6.5

RAM ALLOCATION
RAM space must be allocated in a data section. Five types of data sections are
available:
Note:

The ability to use access, overlaid or shared data varies by device. Consult
your device data sheet for more information.

• udata - Uninitialized data. This is the most common type of data section.
Locations reserved in this section are not initialized and can be accessed only by
the labels defined in this section or by indirect accesses. See 4.62 “udata Begin an Object File Uninitialized Data Section”.
• udata_acs - Uninitialized access data. This data section is used for variables that
will be placed in access RAM of PIC18 devices. Access RAM is used as quick
data access for specified instructions. See 4.63 “udata_acs - Begin an Object
File Access Uninitialized Data Section (PIC18 MCUs)”.
• udata_ovr - Uninitialized overlaid data. This data section is used for variables that
can be declared at the same address as other variables in the same module or in
other linked modules. A typical use of this section is for temporary variables. See
4.64 “udata_ovr - Begin an Object File Overlayed Uninitialized Data
Section”.
• udata_shr - Uninitialized shared data. This data section is used for variables that
will be placed in RAM of PIC12/16 devices that is unbanked or shared across all
banks. See 4.65 “udata_shr - Begin an Object File Shared Uninitialized Data
Section (PIC12/16 MCUs)”.
• idata - Initialized data. The linker will generate a lookup table that can be used to
initialize the variables in this section to the specified values. When linked with
MPLAB C17 or C18 code, these locations will be initialized during execution of the
startup code. The locations reserved by this section can be accessed only by the
labels defined in this section or by indirect accesses. See 4.36 “idata - Begin
an Object File Initialized Data Section”.
The following example shows how a data declaration might be created.
EXAMPLE 6-4:

RAM ALLOCATION

Absolute Code
Use cblock to define variable register locations (See 4.8 “cblock - Define a Block
of Constants”.) Variable values will need to be specified in code.
cblock 0x20
HistoryVector
;Must be initialized to 0
InputGain, OutputGain ;Control loop gains
Templ, Temp2, Temp3
;Used for internal calculations
endc

DS33014L-page 194

 1994-2013 Microchip Technology Inc.

Relocatable Objects
Equivalent Relocatable Code
Use data declarations to define register locations and initialize.
idata
HistoryVector db 0
udata
InputGain res 1
OutputGain res 1
udata_ovr
Templ res 1
Temp2 res 1
Temp3 res 1

;Initialized to 0
;Control loop gains

;Used for internal calculations

If necessary, the location of the section may be fixed in memory by supplying the
optional address parameter. If more than one of each section type is specified, each
section must have a unique name. If a name is not provided, the default section names
are: .idata, .udata, .udata_acs, .udata_shr, and .udata_ovr.
When defining initialized data in an idata section, the directives db, dw, and data can
be used. db will define successive bytes of data memory. dw and data will define
successive words of data memory in low-byte/high-byte order. The following example
shows how data will be initialized.
EXAMPLE 6-5:

RELOCATABLE CODE LISTING

00001
0000 01 02 03
00002
0003 34 12 78 56 00003
0007 41 42 43 00 00004

6.6

IDATA
Bytes DB 1,2,3
Words DW 0x1234,0x5678
String DB "ABC", 0

CONFIGURATION BITS AND ID LOCATIONS
Configuration bits and ID locations can still be defined in a relocatable object using the
following directives:
• Section 4.11 “__config - Set Processor Configuration Bits”
• Section 4.12 “config - Set Processor Configuration Bits (PIC18 MCUs)”
• Section 4.38 “__idlocs - Set Processor ID Locations”
Only one linked module can specify these directives. They should be used prior to
declaring any code sections. After using these directives, the current section is
undefined.

 1994-2013 Microchip Technology Inc.

DS33014L-page 195

Assembler/Linker/Librarian User’s Guide
6.7

ACCESSING LABELS FROM OTHER MODULES
Labels that are defined in one module for use in other modules must be exported using
the global directive (see 4.35 “global - Export a Label”.) Modules that use these
labels must use the extern directive (see 4.33 “extern - Declare an Externally
Defined Label”) to declare the existence of these labels. An example of using the
global and extern directives is shown below.
EXAMPLE 6-6:

RELOCATABLE CODE, DEFINING MODULE

udata
InputGain res 1
OutputGain res 1
global InputGain, OutputGain
code
Filter
global Filter
:
; Filter code

EXAMPLE 6-7:

RELOCATABLE CODE, REFERENCING MODULE

extern InputGain, OutputGain, Filter
udata
Reading res 1
code
:
movlw
movwf
movlw
movwf
movf
call

DS33014L-page 196

GAIN1
InputGain
GAIN2
OutputGain
Reading,W
Filter

 1994-2013 Microchip Technology Inc.

Relocatable Objects
6.8

PAGING AND BANKING ISSUES
In many cases, RAM allocation will span multiple banks, and executable code will span
multiple pages. In these cases, it is necessary to perform proper bank and page set-up
to properly access the labels. However, since the absolute addresses of these variable
and address labels may not be known at assembly time, it is not always possible to
place the proper code in the source file. For these situations two directives, banksel
(4.7 “banksel - Generate Bank Selecting Code”) and pagesel (4.53 “pagesel Generate Page Selecting Code (PIC10/12/16 MCUs)”), have been added. These
directives instruct the linker to generate the correct bank or page selecting code for a
specified label. An example of how code should be converted is shown below.
EXAMPLE 6-8:

BANKSEL AND PAGESEL

Hard-Coded Banking and Paging
Use indirect addressing (FSR) and the Status register for banking and paging,
respectively.
#include p12f509.inc
Varl equ 0x10
Var2 equ 0x30
...
movlw InitialValue
bcf
FSR, 5
movwf Varl
bsf
FSR, 5
movwf Var2
bsf
STATUS, PA0
call Subroutine
...
Subroutine clrw
...
retlw 0

;Declare variables

;Data memory Var1 bank (0)
;Data memory Var2 bank (1)
;Program memory page 1

;On Page 1

BANKSEL for Banking and PAGESEL for Paging
Use banksel and pagesel for banking and paging, respectively.
#include p12f509.inc
extern Var1, Var2
code
movlw
InitialValue
banksel Varl
movwf
Varl
banksel Var2
movwf
Var2
pagesel Subroutine
call
Subroutine
...
Subroutine clrw
...
retlw 0

 1994-2013 Microchip Technology Inc.

;Declare variables

;Select data memory Var1 bank
;Select data memory Var2 bank
;Select program memory page

;Page unknown at assembly time

DS33014L-page 197

Assembler/Linker/Librarian User’s Guide
6.9

GENERATING THE OBJECT MODULE
Once the code conversion is complete, the object module is generated automatically
in the IDE or by requesting an object file on the command line or in the shell interface.
When using MPASM assembler for Windows, check the checkbox labeled "Object
File." When using the command line interface, specify the /o or -o- option. The output
file will have a .o extension.

6.10

CODE EXAMPLE
Since an eight-by-eight bit multiply is a useful, generic routine, it would be handy to
break this off into a separate object file that can be linked in when required. The
absolute code file can be broken into two relocatable code files: a calling file
representing an application and a generic routine that could be incorporated in a library.
This code was adapted from application note AN617. Please see the Microchip website
for a downloadable pdf of this app note.
EXAMPLE 6-9:

ABSOLUTE CODE

; Input: fixed point arguments in AARGB0 and BARGB0
; Output: product AARGxBARG in AARGB0:AARGB1
; Other comments truncated. See AN617.
;********************************************************************
#include
p16f877a.inc ;Use any PIC16 device you like
LOOPCOUNT
AARGB0
AARGB1
BARGB0

EQU
EQU
EQU
EQU

TestCode
clrf
movlw
movwf
movlw
movwf
call

AARGB1
D'11'
AARGB0
D'30'
BARGB0
UMUL0808L

goto

$

0x20
0x21
0x22
0x23

;7 loops needed to complete routine
;MSB of result out,
;operand A in (8 bits)
;LSB of result out,
;operand B in (8 bits)

;Clear partial product before testing

;After loading AARGB0 and BARGB0,
;call routine
;Result now in AARGB0:AARGB1,
;where (B0 is MSB)

END
UMUL0808L
movlw
0x08
movwf
LOOPCOUNT
movf
AARGB0,W
LOOPUM0808A
rrf
BARGB0, F
btfsc
STATUS,C
goto
LUM0808NAP
decfsz LOOPCOUNT, F
goto
LOOPUM0808A
clrf
AARGB0
retlw
0x00
LUM0808NAP
bcf
STATUS,C
goto
LUM0808NA

DS33014L-page 198

 1994-2013 Microchip Technology Inc.

Relocatable Objects
LOOPUM0808
rrf
btfsc
addwf
LUM0808NA
rrf
rrf
decfsz
goto
retlw

BARGB0, F
STATUS,C
AARGB0, F
AARGB0, F
AARGB1, F
LOOPCOUNT, F
LOOPUM0808
0

END

EXAMPLE 6-10:

RELOCATABLE CODE, CALLING FILE

; Input: fixed point arguments in AARGB0 and BARGB0
; Output: product AARGxBARG in AARGB0:AARGB1
; Other comments truncated. See AN617.
;********************************************************************
#include
p16f877a.inc ;Use any PIC16 device you like
EXTERN

UMUL0808L, AARGB0, AARGB1, BARGB0

Reset
CODE
0x0
pagesel TestCode
goto
TestCode
CODE
TestCode
banksel
clrf
movlw
movwf
movlw
movwf
pagesel
call
goto

AARGB1
AARGB1
D'11'
AARGB0
D'30'
BARGB0
UMUL0808L
UMUL0808L
$

;Clear partial product before testing
;Load in 2 test values

;After loading AARGB0 and BARGB0,
;call routine
;Result now in AARGB0:AARGB1,
;where (AARGB0 is MSB)

END

EXAMPLE 6-11:

RELOCATABLE CODE, LIBRARY ROUTINE

; Input: fixed point arguments in AARGB0 and BARGB0
; Output: product AARGxBARG in AARGB0:AARGB1
; Other comments truncated. See AN617.
;********************************************************************
#include
p16f877a.inc ;Use any PIC16 device you like
GLOBAL
UDATA
LOOPCOUNT
AARGB0
AARGB1
BARGB0

 1994-2013 Microchip Technology Inc.

UMUL0808L, AARGB0, AARGB1, BARGB0

RES
RES
RES
RES

1
1
1
1

;7 loops needed to complete routine
;MSB of result out,
;operand A in (8 bits)
;LSB of result out,
;operand B in (8 bits)

DS33014L-page 199

Assembler/Linker/Librarian User’s Guide
CODE
UMUL0808L
movlw
0x08
movwf
LOOPCOUNT
movf
AARGB0,W
LOOPUM0808A
rrf
BARGB0, F
btfsc
STATUS,C
goto
LUM0808NAP
decfsz LOOPCOUNT, F
goto
LOOPUM0808A
clrf
AARGB0
retlw
0x00
LUM0808NAP
bcf
STATUS,C
goto
LUM0808NA
LOOPUM0808
rrf
BARGB0, F
btfsc
STATUS,C
addwf
AARGB0, F
LUM0808NA
rrf
AARGB0, F
rrf
AARGB1, F
decfsz LOOPCOUNT, F
goto
LOOPUM0808
retlw
0
END

DS33014L-page 200

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 7. Macro Language
7.1

INTRODUCTION
Macros are user defined sets of instructions and directives that will be evaluated in-line
with the assembler source code whenever the macro is invoked.
Macros consist of sequences of assembler instructions and directives. They can be
written to accept arguments, making them quite flexible. Their advantages are:
•
•
•
•

Higher levels of abstraction, improving readability and reliability.
Consistent solutions to frequently performed functions.
Simplified changes.
Improved testability.

Applications might include creating complex tables, frequently used code, and complex
operations.
Topics covered in this chapter:
•
•
•
•
•

7.2

Macro Syntax
Macro Directives Defined
Macro Definition
Macro Invocation
Macro Code Examples

MACRO SYNTAX
MPASM assembler macros are defined according to the following syntax:
label macro [arg1,arg2 ..., argn]
:
:
endm

where label is a valid assembler label that will be the macro name and arg is any
number of optional arguments supplied to the macro (that will fit on the source line.)
The values assigned to these arguments at the time the macro is invoked will be
substituted wherever the argument name occurs in the body of the macro.
The body of a macro may be comprised of MPASM assembler directives, PIC1X MCU
assembly instructions, or MPASM assembler macro directives (local for example.)
The assembler continues to process the body of the macro until an exitm or endm
directive is encountered.
Note:

Macros must be defined before they are used, i.e., forward references to
macros are not permitted.

 1994-2013 Microchip Technology Inc.

DS33014L-page 201

Assembler/Linker/Librarian User’s Guide
7.3

MACRO DIRECTIVES DEFINED
There are directives that are unique to macro definitions. They cannot be used out of
the macro context.
•
•
•
•
•
•

4.45 “macro - Declare Macro Definition”
4.31 “exitm - Exit from a Macro”
4.26 “endm - End a Macro Definition”
4.32 “expand - Expand Macro Listing”
4.49 “noexpand - Turn off Macro Expansion”
4.44 “local - Declare Local Macro Variable”

When writing macros, you can use any of these directives PLUS any other directives
supported by the assembler.
Note:

7.4

The previous syntax of the “dot” format for macro specific directives is no
longer supported.

MACRO DEFINITION
String replacement and expression evaluation may appear within the body of a macro.
Command

Description

arg

Substitute the argument text supplied as part of the macro invocation.

#v(expr)

Return the integer value of expr. Typically, used to create unique variable
names with common prefixes or suffixes. Cannot be used in conditional
assembly directives (e.g. ifdef, while).

Arguments may be used anywhere within the body of the macro, except as part of
normal expression.
The exitm directive provides an alternate method for terminating a macro expansion.
During a macro expansion, this directive causes expansion of the current macro to stop
and all code between the exitm and the endm directives for this macro to be ignored.
If macros are nested, exitm causes code generation to return to the previous level of
macro expansion.

DS33014L-page 202

 1994-2013 Microchip Technology Inc.

Macro Language
7.5

MACRO INVOCATION
Once the macro has been defined, it can be invoked at any point within the source
module by using a macro call, as described below:
macro_name [arg, ..., arg]

where macro_name is the name of a previously defined macro and arguments are
supplied as required.
The macro call itself will not occupy any locations in memory. However, the macro
expansion will begin at the current memory location. Commas may be used to reserve
an argument position. In this case, the argument will be an empty string. The argument
list is terminated by white space or a semicolon.
EXAMPLE 7-1:

MACRO CODE GENERATION

The following macro:
define_table macro
local a = 0
while a < 3
entry#v(a) dw 0
a += 1
endw
endm

When invoked, would generate:
entry0
entry1
entry2
entry3

dw
dw
dw
dw

 1994-2013 Microchip Technology Inc.

0
0
0
0

DS33014L-page 203

Assembler/Linker/Librarian User’s Guide
7.6

MACRO CODE EXAMPLES
The following are examples of macros:
• Literal to RAM Conversion
• Constant Compare

7.6.1

Literal to RAM Conversion

This code converts any literal of 32 bits to 4 separate RAM data values. In this example,
the literal 0x12345678 is put in the desired 8 bit registers as 0x12, 0x34, 0x56, and
0x78. Any literal can be “unpacked” this way using this macro.
#include

p16F877A.inc

udata 0x20
Out0
res
1
Out1
res
1
Out2
res
1
Out3
res
1

; LSB
; :
; :
; MSB

Unpack32
MACRO Var, Address ;Var = 32 bit literal to be unpacked
BANKSEL Address
;Address specifies the LSB start
movlw
Address
;Use FSR and INDF for indirect
movwf
FSR
;access to desired address
movlw
movwf
movlw
incf
movwf
movlw
incf
movwf
movlw
incf
movwf

Var & H'FF'
;Mask to get LSB
INDF
;Put in first location
Var >>D'08' & H'FF';Mask to get next byte of literal
FSR,F
;Point to next byte
INDF
;Write data to next byte
Var >>D'16' & H'FF';Mask to get next byte of literal
FSR,F
;Point to next byte
INDF
;Write data to next byte
Var >>D'24' & H'FF';Mask to get last byte of literal
FSR,F
;Point to last byte
INDF
;Write data to last byte
ENDM
;End of the Macro Definition

ORG
0
Start
Unpack32 0x12345678,Out0
goto
$
END

DS33014L-page 204

;TEST CODE for Unpack32 MACRO
;Put Unpack Macro here
;Do nothing (loop forever)

 1994-2013 Microchip Technology Inc.

Macro Language
7.6.2

Constant Compare

As another example, if the following macro were written:
#include "pic16f877a.inc"
;
; compare file to constant and jump if file
; >= constant.
;
cfl_jge macro file, con, jump_to
movlw con & 0xff
subwf file, w
btfsc status, carry
goto jump_to
endm

and invoked by:
cfl_jge switch_val, max_switch, switch_on

it would produce:
movlw
subwf
btfsc
goto

max_switch & 0xff
switch_val, w
status, carry
switch_on

 1994-2013 Microchip Technology Inc.

DS33014L-page 205

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 206

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 8. Errors, Warnings, Messages, and Limitations
8.1

INTRODUCTION
Error messages, warning messages and general messages produced by the MPASM
assembler are listed and detailed here. These messages always appear in the listing
file directly above each line in which the error occurred. Limitations of the assembler
tool are also listed.
The messages are stored in the error file (.err) if no MPASM assembler options are
specified. If the /e- or -e- option is used (turns error file off), then the messages will
appear on the screen. If the /q or -q (quiet mode) option is used with the /e- or -e-,
then the messages will not display on the screen or in an error file. The messages will
still appear in the listing file.
Topics covered in this chapter:
•
•
•
•

Assembler Errors
Assembler Warnings
Assembler Messages
Assembler Limitations

 1994-2013 Microchip Technology Inc.

DS33014L-page 207

Assembler/Linker/Librarian User’s Guide
8.2

ASSEMBLER ERRORS
MPASM assembler errors are listed numerically below:

101 ERROR
User error, invoked with the error directive.

102 Out of memory
Not enough memory for macros, #define’s or internal processing.

103 Symbol table full
No more memory available for the symbol table.

104 Temp file creation error
Could not create a temporary file. Check the available disk space.

105 Cannot open file
Could not open a file. If it is a source file, the file may not exist. If it is an output file, the
old version may be write protected.
To check for write-protect, right-click on the file named by MPLAB X IDE or MPLAB IDE
v8 in Windows. Choose “Properties” and see if “read-only” is checked. If it is, it cannot
be modified by the IDE and will generate this error message. This often happens when
you save your project to a CD-R or similar write-once media as a backup, and then
copy the data to your computer. Copying to a CD marks all files as read-only (they
cannot be changed on a CD-R), and when you copy the files, the attributes move with
them making them all read-only on your hard drive. A good way to prevent this is to
archive all of the files in one file, such as a *.ZIP, and then restore them from CD. The
archive will preserve the original file attributes.

106 String substitution too complex
A string substitution was attempted that was too complex. Check for nesting of
#define’s.

107 Illegal digit
An illegal digit in a number. Valid digits are 0-1 for binary, 0-7 for octal, 0-9 for decimal,
and 0-9, a-f, and A-F for hexadecimal.

108 Illegal character
An illegal character in a label. Valid characters for labels are alphabetic (a..f, A..F),
numeric (0-9), the underscore (_), and the question mark (?). Labels may not begin with
a numeric.

109 Unmatched (
An open parenthesis did not have a matching close parenthesis. For example,
DATA (1+2.

110 Unmatched)
An close parenthesis did not have a matching open parenthesis. For example,
DATA 1+2).

111 Missing symbol
An equ or set directive did not have a symbol to which to assign the value.
DS33014L-page 208

 1994-2013 Microchip Technology Inc.

Errors, Warnings, Messages, and Limitations
112 Missing operator
An arithmetic operator was missing from an expression. For example, DATA 1 2.

113 Symbol not previously defined
A symbol was referenced that has not yet been defined. Check the spelling and
location of the declaration of any symbols used in your code. Only addresses may be
used as forward references. Constants and variables must be declared before they are
used.
This sometimes happens when #include files are used in your project. Since the text
from an include file is inserted at the location of the #include statement, and you may
have labels used before that point, you can get this error. Also, the error may occur due
to a typing error, spelling mistake or case change in your label. MyLabel is not the
same as Mylabel unless case sensitivity is turned off (it is on by default). Additionally,
goto MyLabel will never locate the code at Mylabl or Mylable. Check for these
sorts of mistakes first. As a general rule, put your include files at the top of each file. If
this seems to cluttered, you may include files within other include files.

114 Divide by zero
Division by zero encountered during an expression evaluation.

115 Duplicate label
A label was declared as a constant (e.g., with the equ or cblock directive) in more
than one location.

116 Address label duplicated or different in second pass
The same label was used in two locations. Alternately, the label was used only once
but evaluated to a different location on the second pass. This often happens when
users try to write page-bit setting macros that generate different numbers of instructions
based on the destination.

117 Address wrapped around 0
For PIC12/16 devices, the location counter can only advance to 0xFFFF. After that, it
wraps back to 0. Error 117 is followed by error 118.

118 Overwriting previous address contents
Code was previously generated for this address.

119 Code too fragmented
The code is broken into too many pieces. This error is very rare, and will only occur in
source code that references addresses above 32K (including configuration bits).

120 Call or jump not allowed at this address
A call or jump cannot be made to this address. For example, CALL destinations on the
PIC16C5x family must be in the lower half of the page.

121 Illegal label
Labels are not allowed on certain directive lines. Simply put the label on its own line,
above the directive. Also, high, low, page, and bank are not allowed as labels.

122 Illegal opcode
Token is not a valid opcode.

 1994-2013 Microchip Technology Inc.

DS33014L-page 209

Assembler/Linker/Librarian User’s Guide
123 Illegal directive
Directive is not allowed for the selected processor; for example, the __idlocs
directive on devices with ID locations.

124 Illegal argument
An illegal directive argument; for example, list foobar.

125 Illegal condition
A bad conditional assembly. For example, an unmatched endif.

126 Argument out of range
Opcode or directive argument out of the valid range; for example, TRIS 10.

127 Too many arguments
Too many arguments specified for a macro call.

128 Missing argument(s)
Not enough arguments for a macro call or an opcode.

129 Expected
Expected a certain type of argument. The expected list will be provided.

130 Processor type previously defined
A different family of processor is being selected.

131 Processor type is undefined
Code is being generated before the processor has been defined. Note that until the
processor is defined, the opcode set is not known.

132 Unknown processor
The selected processor is not a valid processor.

133 Hex file format INHX32 required
An address above 32K was specified.

134 Illegal hex file format
An illegal hex file format was specified in the list directive.

135 Macro name missing
A macro was defined without a name.

136 Duplicate macro name
A macro name was duplicated.

137 Macros nested too deep
The maximum macro nesting level was exceeded.

138 Include files nested too deep
The maximum include file nesting level was exceeded.

DS33014L-page 210

 1994-2013 Microchip Technology Inc.

Errors, Warnings, Messages, and Limitations
139 Maximum of 100 lines inside WHILE-ENDW
A while-endw can contain at most 100 lines.

140 WHILE must terminate within 256 iterations
A while-endw loop must terminate within 256 iterations. This is to prevent infinite
assembly.

141 WHILEs nested too deep
The maximum while-endw nesting level was exceeded.

142 IFs nested too deep
The maximum if nesting level was exceeded.

143 Illegal nesting
Macros, if's and while's must be completely nested; they cannot overlap. If you have
an if within a while loop, the endif must come before the endw.

144 Unmatched ENDC
endc found without a cblock.

145 Unmatched ENDM
endm found without a macro definition.

146 Unmatched EXITM
exitm found without a macro definition.

147 Directive/operation only allowed when generating an object file
The instruction/operand shown only has meaning when a linkable object file is
generated. It cannot be used when generating absolute code.

148 Expanded source line exceeded 200 characters
The maximum length of a source line, after #define and macro parameter
substitution, is 200 characters. Note that #define substitution does not include
comments, but macro parameter substitution does.

149 Directive only allowed when generating an object file
Certain directives, such as global and extern, only have meaning when a linkable
object file is generated. They cannot be used when generating absolute code.

150 Labels must be defined in a code or data section when making an
object file
When generating a linkable object file, all data and code address labels must be
defined inside a data or code section. Symbols defined by the equ and set directives
can be defined outside of a section.

151 Operand contains unresolvable labels or is too complex
When generating an object file, operands must be of the form [high|low]([relocatable
address label]+[offset]).

 1994-2013 Microchip Technology Inc.

DS33014L-page 211

Assembler/Linker/Librarian User’s Guide
152 Executable code and data must be defined in an appropriate section
When generating a linkable object file, all executable code and data declarations must
be placed within appropriate sections.

153 Page or Bank bits cannot be evaluated for the operand
The operand of a pagesel, banksel or bankisel directive must be a relocatable
address label or a constant.

154 Each object file section must be contiguous
Object file sections, except udata_ovr sections, cannot be stopped and restarted
within a single source file. To resolve this problem, either name each section with its
own name or move the code and data declarations such that each section is
contiguous. This error will also be generated if two sections of different types are given
the same name.

155 All overlaid sections of the same name must have the same starting
address
If multiple udata_ovr sections with the same name are declared, they must all have
the same starting address.

156 Operand must be an address label
When generating object files, only address labels in code or data sections may be
declared global. Variables declared by the set or equ directives may not be exported.

157 ORG at odd address
For PIC18 devices, you cannot place org at an odd address, only even. Consult your
device data sheet.

158 Cannot use RES directive with odd number of bytes
For PIC18 devices, you cannot use res to specify an odd number of bytes, only even.
Consult your device data sheet.

159 Cannot use FILL directive with odd number of bytes
For PIC18 devices, you cannot use fill to fill with data an odd number of bytes, only
even. Consult your device data sheet.

160 CODE_PACK directive not available for this part;substituting CODE
The code_pack directive can only be used with byte-addressable ROM.

161 Non-negative value required for this context.
Some contexts require non-negative values.

162 Expected a section name
Some operators and pseudo-operators take section names as operands. The lexical
form of a section name is that of an identifier, optionally prefixed with a ‘.’.

163 __CONFIG directives must be contiguous
Do not place other code between __config directive declarations.

164 __IDLOC directives must be contiguous
Do not place other code between __idloc directive declarations.
DS33014L-page 212

 1994-2013 Microchip Technology Inc.

Errors, Warnings, Messages, and Limitations
165 extended mode not available for this device
This PIC18 device does not support extended mode.

166 left bracket missing from offset operand
The left bracket is missing from an offset, e.g., [0x55.

167 right bracket missing from offset operand
The right bracket is missing from an offset, e.g., 0x55].

168 square brackets required around offset operand
Square brackets are required around an offset, e.g., [0x55]

169 access bit cannot be specified with indexed mode
When using indexed mode, the access bit cannot be specified.

170 expression within brackets must be constant
The expression specified within brackets is not a constant value.

171 address specified is not in access ram range of [0x60, 0xFF]
When making use of Access RAM, addressing must occur within the specified Access
Bank range.

172 PCL, TOSL, TOSH, or TOSU cannot be destination of MOVFF or
MOVSF
These registers cannot be written to with movff or movsf commands.

174 __CONFIG directives must be listed in ascending order
List config directive configuration registers in ascending order, e.g.,
__CONFIG
__CONFIG
__CONFIG

_CONFIG0, _CP_OFF_0
_CONFIG1, _OSCS_OFF_1 & _RCIO_OSC_1
_CONFIG2, _BOR_ON_2 & _BORV_25_2
:

175 __IDLOCS directives must be listed in ascending order
List __idlocs directive ID registers in ascending order, e.g.,
__idlocs
__idlocs
__idlocs

_IDLOC0, 0x1
_IDLOC1, 0x2
_IDLOC2, 0x3
:

176 CONFIG Directive Error:
An error was found in the config directive syntax.

177 __CONFIG directives cannot be used with CONFIG directives
Do not mix __config directives and config directives when assigning configuration
bits in your code.

178 __CONFIG Directive Error
An error was found in the __config directive syntax.

 1994-2013 Microchip Technology Inc.

DS33014L-page 213

Assembler/Linker/Librarian User’s Guide
179 Instruction is not supported on this device
This error would occur when an instruction is used in code which is not supported on
the particular family/architecture.

180 RES directive cannot reserve odd number of bytes in PIC18 absolute
mode
This error would occur if you try to reserve an odd number of bytes using a PIC18
device and assemble in absolute mode (Quickbuild). For example:
org 0x0
a res 1
end

If you try to Quickbuild the above PIC18 MCU program, you will see error 180 and
warning 231.

### UNKNOWN ERROR
An internal application error has occurred. (### is the value of the last defined error plus
1.)
Contact your Microchip Field Application Engineer (FAE) or Microchip support if you
cannot debug this error.

DS33014L-page 214

 1994-2013 Microchip Technology Inc.

Errors, Warnings, Messages, and Limitations
8.3

ASSEMBLER WARNINGS
MPASM assembler warnings are listed numerically below:

201 Symbol not previously defined
The symbol being #undefined was not previously defined.

202 Argument out of range. Least significant bits used
Argument did not fit in the allocated space. For example, literals must be 8 bits.

203 Found opcode in column 1
An opcode was found in column one, which is reserved for labels.

204 Found pseudo-op in column 1
A pseudo-op was found in column one, which is reserved for labels.

205 Found directive in column 1
A directive was found in column one, which is reserved for labels.

206 Found call to macro in column 1
A macro call was found in column one, which is reserved for labels.

207 Found label after column 1
A label was found after column one, which is often due to a misspelled opcode.

208 Label truncated at 32 characters
Maximum label length is 32 characters.

209 Missing quote
A text string or character was missing a quote. For example, DATA 'a.

210 Extra “,”
An extra comma was found at the end of the line.

211 Extraneous arguments on the line
Extra arguments were found on the line.

212 Expected (ENDIF)
Expected an endif statement, i.e., an if statement was used without an endif.

213 The EXTERN directive should only be used when making a .o file
The extern directive only has meaning if an object file is being created. This warning
has been superseded by Error 149.

214 Unmatched (
An unmatched parenthesis was found. The warning is used if the parenthesis is not
used for indicating order of evaluation.

 1994-2013 Microchip Technology Inc.

DS33014L-page 215

Assembler/Linker/Librarian User’s Guide
215 Processor superseded by command line. Verify processor symbol
The processor was specified on the command line as well as in the source file. The
command line has precedence.
If you are using an IDE with the assembly, set the device to match the source file from
File>Project Properties (MPLAB X IDE) or Configure>Select Device (MPLAB IDE v8).

216 Radix superseded by command line
The radix was specified on the command line as well as in the source file. The
command line has precedence.

217 Hex file format specified on command line
The hex file format was specified on the command line as well as in the source file. The
command line has precedence.

218 Expected DEC, OCT, HEX. Will use HEX
Bad radix specification.

219 Invalid RAM location specified
If the __maxram and __badram directives are used, this warning flags use of any RAM
locations declared as invalid by these directives. Note that the provided header files
include __maxram and __badram for each processor.

220 Address exceeds maximum range for this processor
A ROM location was specified that exceeds the processor's memory size.

221 Invalid message number
The message number specified for displaying or hiding is not a valid message number.

222 Error messages cannot be disabled
Error messages cannot be disabled with the errorlevel command.

223 Redefining processor
The selected processor is being reselected by the list or processor directive.

224 Use of this instruction is not recommended
The instruction is being obsoleted and is not recommended for current use. However,
it is still supported for legacy reasons.

225 Invalid label in operand
Operand was not a valid address. For example, if the user tried to issue a CALL to a
MACRO name.

226 Destination address must be word aligned
The destination address is not aligned with the start of a program memory word. For
this device, use even bytes to specify address.

227 Substituting RETLW 0 for RETURN pseudo-op
Using retlw 0 instead of return to resume program execution.

DS33014L-page 216

 1994-2013 Microchip Technology Inc.

Errors, Warnings, Messages, and Limitations
228 Invalid ROM location specified
The data memory location specified is not valid for the operation specified or is
non-existent.

229 extended mode is not in effect -- overridden by command line
A command-line option has disabled extended mode operation.

230 __CONFIG has been deprecated for PIC18 devices. Use directive
CONFIG.
Although you may still use the __config directive for PIC18 MCU devices, it is
strongly recommended that you use the config directive (no leading underscores)
instead. For PIC18FXXJ MCUs, you must user the config directive.

231 No memory has been reserved by this instruction
This warning would appear if an instruction which is meant to reserve memory cannot
actually reserve that memory. For example:
a

org 0x0
res 1
end

The above PIC18 assembly program is attempting to reserve one byte (a res 1) but
this is not valid for a PIC18 MCU as each word size is two bytes.

232 STATUS register has no IRP or RP1 or RP0 bits
For PIC16 extended instruction devices, you are trying to access a non-existent bit of
the STATUS register (IRP or RP1 or RP0 bits).

### UNKNOWN WARNING
An internal application error has occurred. (### is the value of the last defined warning
plus 1.)
However, it is not severe enough to keep your code from assembling, i.e., it is a
warning, not an error.

 1994-2013 Microchip Technology Inc.

DS33014L-page 217

Assembler/Linker/Librarian User’s Guide
8.4

ASSEMBLER MESSAGES
MPASM assembler messages are listed numerically below:

301 MESSAGE
User-definable message, invoked with the messg directive (see Section 4.48 “messg
- Create User Defined Message”).

302 Register in operand not in bank 0. Ensure that bank bits are correct.
This is a commonly seen reminder message to tell you that a variable that is being
accessed in not in bank 0. This message was added to remind you to check your code,
particularly code in banks other than 0. Review the section on banksel
(Section 4.7 “banksel - Generate Bank Selecting Code”) and bankisel
(Section 4.6 “bankisel - Generate Indirect Bank Selecting Code (PIC12/16
MCUs)”) and ensure that your code uses bank bits whenever changing from ANY bank
to ANY other bank (including bank 0).
Since the assembler or linker can't tell which path your code will take, you will always
get this message for any variable not in bank 0. You can use the errorlevel
command to turn this and other messages on and off, but be careful as you may not
spot a banking problem with this message turned off. For more about errorlevel,
see Section 4.30 “errorlevel - Set Message Level”.
A similar message is 306 for paging.

303 Program word too large. Truncated to core size.
The program word (instruction width) is too large for the selected device’s core
(program memory) size. Therefore the word has been truncated to the proper size.
For example, a 14-bit instruction would be truncated to 12 bits to be used by a
PIC16F54.

304 ID Locations value too large. Last four hex digits used.
Only four hex digits are allowed for the ID locations.

305 Using default destination of 1 (file).
If no destination bit is specified, the default is used. Usually code that causes this
message is missing the ,W or ,F after the register name, but sometimes the bug is due
to typing movf instead of movwf.
It is best to fix any code that is causing this message. The default destination could not
be where you want the value stored, and could cause the code to operate strangely.

306 Crossing page boundary -- ensure page bits are set.
Generated code is crossing a page boundary. This is a reminder message to tell you
that code is being directed to a label that is on a page other than page 0. It is not an
error or warning, but a reminder to check your page bits. Use the pagesel directive
(Section 4.53 “pagesel - Generate Page Selecting Code (PIC10/12/16 MCUs)”)
before this point and remember to use another pagesel if returning to page 0.
The assembler can't tell what path your code will take, so this message is generated
for any label in a page other than 0.You can use the errorlevel command to turn
this and other messages on and off, but be careful as you may not spot a paging
problem with this message turned off. For more about errorlevel, see
Section 4.30 “errorlevel - Set Message Level”.
A similar message is 302 for banking.

DS33014L-page 218

 1994-2013 Microchip Technology Inc.

Errors, Warnings, Messages, and Limitations
307 Setting page bits.
Page bits are being set with the LCALL or LGOTO pseudo-op.

308 Warning level superseded by command line value.
The warning level was specified on the command line as well as in the source file. The
command line has precedence.

309 Macro expansion superseded by command line.
Macro expansion was specified on the command line as well as in the source file. The
command line has precedence.

310 Superseding current maximum RAM and RAM map.
The __maxram directive has been used previously.

311 Operand of HIGH operator was larger than H’FFFF’.
High byte of address returned by high directive was greater than 0xFFFF.

312 Page or Bank selection not needed for this device. No code
generated.
If a device contains only one ROM page or RAM bank, no page or bank selection is
required, and any pagesel, banksel, or bankisel directives will not generate any
code.

313 CBLOCK constants will start with a value of 0.
If the first cblock in the source file has no starting value specified, this message will
be generated.

314 LFSR instruction is not supported on some versions of the 18Cxx2
devices.
See message 315 for more information.

315 Please refer to Microchip document DS80058A for more details
A downloadable pdf of this document, PIC18CXX2 Silicon/Data Sheet Errata, is
available from the Microchip website.

316 W Register modified.
The working (W) register has been modified

317 W Register not modified. BSF/BCF STATUS instructions used
instead.
The working (W) register has not been modified

318 Superseding current maximum ROM and ROM map.
Operation will cause maximum ROM to be exceeded.

### UNKNOWN MESSAGE
An internal application error has occurred. (### is the value of the last defined message
plus 1.)
However, it is not severe enough to keep your code from assembling, i.e., it is a
message, not an error.

 1994-2013 Microchip Technology Inc.

DS33014L-page 219

Assembler/Linker/Librarian User’s Guide
8.5

ASSEMBLER LIMITATIONS
8.5.1

General Limitations

• If a fully qualified path is specified, only that path will be searched. Otherwise, the
search order is: (1) current working directory, (2) source file directory, and (3)
MPASM assembler executable directory.
• There is a source file line limit (expanded) of 200 characters.
• MPLAB X IDE v1.40 and above has a parallel make facility and will attempt to
compile multiple source files simultaneously if your PC has a multi-core
processor. The assembler is not compatible with parallel make and you should
disable parallel make when using the assembler by itself or as part of MPLAB C18
(see Tools>Options, Embedded tab, Project options sub-tab).

8.5.2

Directive Limitations

• Do not use #includes in macros.
• if directive limits
- Maximum nesting depth = 16
• include directive limits
- Maximum nesting depth = 5
- Maximum number of files = 255
• macro directive limits
- Maximum nesting depth = 16
• while directive limits
- Maximum nesting depth = 8
- Maximum number of lines per loop = 100
- Maximum iterations = 256

8.5.3

MPASM Assembler Versions before v5.39 (MPLAB IDE v8)

There is an assembler command-line length limit of 255 characters.

8.5.4

MPASM Assembler Versions before v3.30 (MPLAB IDE v8)

Assembler versions before v3.30 (v3.2x and earlier) have limitations based on the
generation a COD file for debugging and the support of a command-line version,
mpasm.exe.
• There is a 62 character length restriction for file and path names in the debug
(COD) file produced by MPASM assembler. This can cause problems when
assembling single files with long file names and/or path names.
Work-arounds:
- Shorten your file name or move your file into a directory closer to the root
directory (shorten the path name), and try assembling your file again.
- Create a Mapped drive for the long directory chain.
- Use the linker with the assembler, and not the assembler alone, to generate
your output. There is no character restriction with MPLINK linker.
• The command-line version of the assembler (mpasm.exe) has the following
limitations:
- File names are limited to 8.3 format.
- config directive not supported.

DS33014L-page 220

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Part 2 – MPLINK Object Linker
Chapter 9. MPLINK Linker Overview ........................................................................ 223
Chapter 10. Linker Interfaces.................................................................................... 231
Chapter 11. Linker Scripts ......................................................................................... 235
Chapter 12. Linker Processing ................................................................................. 251
Chapter 13. Sample Applications ............................................................................. 255
Chapter 14. Errors, Warnings and Common Problems .......................................... 285

 1994-2013 Microchip Technology Inc.

DS33014L-page 221

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 222

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 9. MPLINK Linker Overview
9.1

INTRODUCTION
An overview of the MPLINK object linker and its capabilities is presented.
Topics covered in this chapter:
•
•
•
•
•
•

9.2

MPLINK Linker Defined
How MPLINK Linker Works
How MPLINK Linker Helps You
Linker Platforms Supported
Linker Operation
Linker Input/Output Files

MPLINK LINKER DEFINED
MPLINK object linker (the linker) combines object modules generated by the MPASM
assembler or the MPLAB C18 C compiler into a single executable (hex) file. The linker
also accepts libraries of object files as input, as generated by the MPLIB object
librarian. The linking process is controlled by a linker script file, which is also input into
MPLINK linker.
For more information on MPASM assembler, see Chapter 1. “MPASM Assembler
Overview”. For more information on MPLAB C18, see C compiler documentation
listed in “Recommended Reading”.

9.3

HOW MPLINK LINKER WORKS
MPLINK linker performs many functions:
• Locates Code and Data. The linker takes as input relocatable object files. Using
the linker script, it decides where the code will be placed in program memory and
where variables will be placed in RAM.
• Resolves Addresses. External references in a source file generate relocation
entries in the object file. After the linker locates code and data, it uses this
relocation information to update all external references with the actual addresses.
• Generates an Executable. Produces a .hex file that can be programmed into a
PIC1X MCU or loaded into an emulator or simulator to be executed.
• Configures Stack Size and Location. Allows MPLAB C18 to set aside RAM space
for dynamic stack usage.
• Identifies Address Conflicts. Checks to ensure that program/data do not get
assigned to space that has already been assigned or reserved.
• Provides Symbolic Debug Information. Outputs a file that the IDE uses to track
address labels, variable locations, and line/file information for source level
debugging.

 1994-2013 Microchip Technology Inc.

DS33014L-page 223

Assembler/Linker/Librarian User’s Guide
9.4

HOW MPLINK LINKER HELPS YOU
MPLINK linker allows you to produce modular, reusable code. Control over the linking
process is accomplished through a linker script file and with command line options. The
linker ensures that all symbolic references are resolved and that code and data fit into
the available PIC1X MCU device.
MPLINK linker can help you with:
• Reusable Source Code. You can build up your application in small, reusable
modules.
• Libraries. You can make libraries of related functions which can be used in
creating efficient, readily compilable applications.
• MPLAB C18. The Microchip compiler for PIC18 devices requires the use of
MPLINK linker and can be used with precompiled libraries and MPASM
assembler.
• Centralized Memory Allocation. By using application-specific linker scripts,
precompiled objects and libraries can be combined with new source modules and
placed efficiently into available memory at link time.
• Accelerated Development. Since tested modules and libraries don't have to be
recompiled each time a change is made in your code, compilation time may be
reduced.

9.5

LINKER PLATFORMS SUPPORTED
MPLINK linker is supported under Windows 2000/XP, Windows Vista, Linux and Mac
platforms.

DS33014L-page 224

 1994-2013 Microchip Technology Inc.

MPLINK Linker Overview
9.6

LINKER OPERATION
The MPLINK linker combines multiple input object modules and library files, per the
linker script file, into a single output COF file. Utilities can be used to generate
executable code (.hex) or a linker listing file (.lst) from the COF file. A map file can
also be generated to aid in debugging.
FIGURE 9-1:
main.o

math.lib

MPLINK LINKER OPERATION
prog1.o

prog2.o

MPLINK linker

precomp.o

object
files

device.lkr

linker
script file*

library file

prog.cof

prog.map

output
files

* The linker will select this file for you.

The linker is executed after assembling or compiling relocatable object modules with
the MPASM assembler and/or MPLAB C18 C compiler. The actual addresses of data
and the location of functions will be assigned when the MPLINK linker is executed. This
means that you may instruct the linker, via a linker script, to place code and data
somewhere within named regions of memory, or, if not specified, to place into any
available memory.
The linker script must also tell the MPLINK linker about the ROM and RAM memory
regions available in the target PIC1X MCU device. Then, it can analyze all the input
files and try to fit the application's routines into ROM and assign its data variables into
available RAM. If there is too much code or too many variables to fit, the linker will give
an error message.
The MPLINK linker also provides flexibility for specifying that certain blocks of data
memory are reusable, so that different routines (which never call each other and which
don't depend upon this data to be retained between execution) can share limited RAM
space.
When using a C compiler, libraries are available for most PIC MCU peripheral functions
as well as for many standard C functions. The linker will only extract and link individual
object files that are needed for the current application from the included libraries. This
means that relatively large libraries can be used in a highly efficient manner.
The MPLINK linker combines all input files and ensure that all addresses are resolved.
Any function in the various input modules that attempts to access data or call a routine
that has not been allocated or created will cause the linker to generate an error.
Finally the linker calls the MP2HEX utility to generate the executable output. The
MPLINK linker also generates symbolic information for debugging your application with
the IDE (.cof and .map files). A list file (.lst) can also be generated by calling the
MP2COD utility.

 1994-2013 Microchip Technology Inc.

DS33014L-page 225

Assembler/Linker/Librarian User’s Guide
9.7

LINKER INPUT/OUTPUT FILES
The MPLINK linker combines multiple object files into one executable hex file.

Input Files
Object File (.o)

Relocatable code produced from a source file.

Library File (.lib)

A collection of object files grouped together for convenience.

Linker Script File (.lkr)

Description of memory layout for a particular
processor/project.

Output Files
COFF Object Module File
(.cof, .out)

Debug file used by MPLAB IDE v6.xx and later.

Hex File Formats (.hex, .hxl,
.hxh)

Hexadecimal file with no debug information. Suitable for use
in programming.
This file is generated by the utility MP2HEX.

Listing File (.lst)

Original source code, side-by-side with final binary code.
Note: Requires linker can find original source files.
This file is generated by the utility MP2COD.

Map File (.map)

Shows the memory layout after linking. Indicates used and
unused memory regions.

9.7.1

Object File (.o)

Object files are the relocatable code produced from source files. The MPLINK linker
combines object files and library files, according to a linker script, into a single output
file.
Object files may be created from source files by MPASM assembler and library files
may be created from object files by MPLIB librarian.

9.7.2

Library File (.lib)

Libraries are a convenient way of grouping related object modules. A library file may
be created from object files by MPLIB librarian. For more on the librarian, see Chapter
15. “MPLIB Librarian Overview”.

9.7.3

Linker Script File (.lkr)

Linker script files are the command files of MPLINK linker. For more information on
linker scripts, see Chapter 11. “Linker Scripts”.
Standard linker script files are located in:
C:\Program Files\Microchip\MPASM Suite\LKR

During the link process, if MPLINK linker is unable to resolve a reference to a symbol,
it will search libraries specified on the command line or in the linker script in an attempt
to resolve the reference. If a definition is found in a library file, the object file containing
that definition will be included in the link.

DS33014L-page 226

 1994-2013 Microchip Technology Inc.

MPLINK Linker Overview
9.7.4

COFF Object Module File (.cof, .out)

MPLINK linker generates a COFF file which provides debugging information to MPLAB
IDE v6.xx or later.

9.7.5

Hex File Formats (.hex, .hxl, .hxh)

Both the MPASM assembler and the MPLINK linker can generate a hex file. For more
information on this format, see Section 1.7.5 “Hex File Formats (.hex, .hxl, .hxh)”.
For MPLINK linker, mp2hex.exe uses the COF file to generate the hex file. To prevent
hex file generation, use the /x or -x option.

9.7.6

Listing File (.lst)

An MPLINK linker listing file provides a mapping of source code to object code. It also
provides a list of symbol values, memory usage information, and the number of errors,
warnings and messages generated.
This file may be viewed in MPLAB X IDE by:
1.
2.
3.
4.
5.

selecting File>Open File to launch the Open dialog
selecting “All Files” from the “Files of type” drop-down list
locating the desired list file
clicking on the list file name
clicking Open

This file may be viewed in MPLAB IDE v8 by:
1.
2.
3.
4.
5.

selecting File>Open to launch the Open dialog
selecting “List files (*.lst)” from the “Files of type” drop-down list
locating the desired list file
clicking on the list file name
clicking Open

Both the MPASM assembler and the MPLINK linker can generate listing files. For
information on the MPASM assembler listing file, see Section 1.7.3 “Listing File
(.lst)”.
An alternative to a listing file would be to use the information in the Disassembly
window, View>Disassembly in MPLAB IDE v8 or Window>Debugging>Disassembly in
MPLAB X IDE.
The MPLINK linker uses the mp2cod.exe utility to generate the linker list file from the
COF file. To prevent linker list file generation, use the /w or -w- option.

 1994-2013 Microchip Technology Inc.

DS33014L-page 227

Assembler/Linker/Librarian User’s Guide
EXAMPLE 9-1:

MPLINK LINKER LISTING FILE

The MP2COD utility version and list file generation data appear at the top of each page.
The first column contains the base address in memory where the code will be placed.
The second column is reserved for the machine instruction. This is the code that will be
executed by the PIC MCU. The third column displays disassembly code. The fourth
column lists the associated source code line. The fifth column lists the file associated
for the source code line.
Note:

Due to page width restrictions, some comments have been shortened, indicated by “..” Also, associated file names have been replaced by numbers,
i.e., (1) and (2). See the end of the listing of the actual file paths and names.

MP2COD 3.80.03, COFF to COD File Converter
Copyright (c) 2004 Microchip Technology Inc.
Listing File Generated: Tue Nov 02 14:33:23 2004

Address
-------

Value
-----

Disassembly
-------------------

000000
000002

ef16
f000

GOTO

Source
--------------------------------------#include p18f452.inc
LIST
; P18F452.INC Standard Header File,...
LIST
udata
Dest res 1
RST

00002c
00002e
000030
000032
000034

0e0a
6f80
9780
ef16
f000

MOVLW
MOVWF
BCF
GOTO

0x2c

0xa
0x80,0x1
0x80,0x3,0x1
0x2c

code
goto

PGM
code
Start movlw
movwf
bcf
goto

0x0
Start

File
---(1)
(2)
(2)
(2)
(1)
(1)
(1)
(1)
(1)

0x0A
Dest
Dest, 3
Start

(1)
(1)
(1)
(1)
(1)
(1)

end

(1)

where:
(1) = D:\Projects32\PIC18F452\SourceReloc.asm
(2) = C:\Program Files\Microchip\MPASM Suite\p18f452.inc

DS33014L-page 228

 1994-2013 Microchip Technology Inc.

MPLINK Linker Overview
9.7.7

Map File (.map)

The map file generated by MPLINK linker can be viewed by selecting File>Open File
in MPLAB X IDE (or File>Open in MPLAB IDE v8) and choosing the file you specified
in the MPLINK linker options. It provides information on the absolute location of source
code symbols in the final output. It also provides information on memory use, indicating
used/unused memory. This window is automatically reloaded after each rebuild.
The map file contains four tables. The first table (Section Info) displays information
about each section. The information includes the name of the section, its type,
beginning address, whether the section resides in program or data memory, and its size
in bytes.
There are four types of sections:
•
•
•
•

code
initialized data (idata)
uninitialized data (udata)
initialized ROM data (romdata)

The following table is an example of the section table in a map file:
Section
--------Reset
.cinit
.code
.udata

Section Info
Type
Address
--------- --------code
0x000000
romdata
0x000021
code
0x000023
udata
0x000020

Location
--------program
program
program
data

Size(Bytes)
--------0x000002
0x000004
0x000026
0x000005

The second table (Program Memory Usage) lists program memory addresses that
were used and provides a total usage statistic. For example:
Program Memory Usage
Start
End
----------------0x000000
0x000005
0x00002a
0x00002b
0x0000bc
0x001174
0x001176
0x002895
10209 out of 32786 program addresses used, program memory utilization is 31%

The third table in the map file (Symbols - Sorted by Name) provides information about
the symbols in the output module. The table is sorted by the symbol name and includes
the address of the symbol, whether the symbol resides in program or data memory,
whether the symbol has external or static linkage, and the name of the file where
defined. The following table is an example of the symbol table sorted by symbol name
in a map file:
Symbols Name
------call_m
loop
main
mpy
start
H_byte
L_byte
count
mulcnd
mulplr

Sorted by Name
Address
Location
--------------0x000026
program
0x00002e
program
0x000024
program
0x000028
program
0x000023
program
0x000022
data
0x000023
data
0x000024
data
0x000020
data
0x000021
data

 1994-2013 Microchip Technology Inc.

Storage
-------static
static
static
extern
static
extern
extern
static
extern
extern

File
--------C:\PROGRA~1\MPLAB\ASMFOO\sampobj.asm
C:\MPASM assemblerV2\MUL8X8.ASM
C:\PROGRA~1\MPLAB\ASMFOO\sampobj.asm
C:\MPASM assemblerV2\MUL8X8.ASM
C:\PROGRA~1\MPLAB\ASMFOO\sampobj.asm
C:\MPASM assemblerV2\MUL8X8.ASM
C:\MPASM assemblerV2\MUL8X8.ASM
C:\MPASM assemblerV2\MUL8X8.ASM
C:\MPASM assemblerV2\MUL8X8.ASM
C:\MPASM assemblerV2\MUL8X8.ASM

DS33014L-page 229

Assembler/Linker/Librarian User’s Guide
The fourth table in the map file (Symbols - Sorted by Address) provides the same
information that the third table provides, but it is sorted by symbol address rather than
symbol name.
If a linker error is generated, a complete map file can not be created. However, if the
/m or -m option was supplied, an error map file will be created. The error map file
contains only section information; no symbol information is provided. The error map file
lists all sections that were successfully allocated when the error occurred. This file, in
conjunction with the error message, should provide enough context to determine why
a section could not be allocated.

DS33014L-page 230

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 10. Linker Interfaces
10.1

INTRODUCTION
MPLINK object linker usage is discussed.
When MPLAB X IDE/MPLAB IDE v8 or MPLAB C18 is installed, the MPLINK linker
(mplink.exe) is also installed.
Topics covered in this chapter:
• IDE Interface
• Command Line Interface
• Command Line Example

10.2

IDE INTERFACE
The MPLINK linker is commonly used with the MPASM assembler in an MPLAB X IDE
or MPLAB IDE v8 project to generate relocatable code. For more information on this
use, see the MPASM assembler on-line Help file.
The linker may also be used in the IDE with the MPLAB C18 C compiler. For more
information on Microchip compilers, see the MPLAB C18 C compiler documentation
listed in “Recommended Reading”.

 1994-2013 Microchip Technology Inc.

DS33014L-page 231

Assembler/Linker/Librarian User’s Guide
10.3

COMMAND LINE INTERFACE
MPLINK linker can be used in the IDE or directly from a command line.
When used in an IDE, all of MPLINK linker's options are available through the Project
Properties dialog (File>Project Properties) for MPLAB X IDE or MPLINK Linker tab,
accessed from the Project>Build Options dialog, in MPLAB IDE v8.
When using MPLINK linker in a batch file, or directly from the command line, the linker
is invoked with the following two syntaxes:
mplink lkrscript partnumber objfiles [libfiles] [options]
mplink partnumber objfiles [libfiles] [options]

lkrscript is the name of a linker script file. All linker script files must have the
extension .lkr. It is not necessary to add the linker script file name to the command
line if you will be using the generic linker script, as described in the next paragraph.
However if you have your own modified script, you must include the name on the
command line.
partnumber indicates the part number for the device, as in 18f4520 for PIC18F4520.
For Windows OS, you specify the part number by /ppartnumber. For Linux or Mac
OS, you specify the part number by -ppartnumber.
If no linker script name is provided, the part number will be used to determine the
generic linker script to build the project. The linker will search the lkr directory to find
the generic linker script for that part. The lkr directory is located at the same location
as the MPLINK linker executable. The linker will construct the name of the generic
linker script by adding an ‘_g.lkr’ to the string value of the part number, as in
18f4520_g.lkr.
As of MPLINK linker v4.38, even is a linker script is provided, the part number must also
be provided.
objfile is the name of an assembler or compiler generated object file. All object files
must have the extension .o.
libfile is the name of a librarian-created library file. All library files must have the
extension .lib.
option is one of the linker command-line options described below. For Windows OS,
use a backslash and then the option. For Linux or Mac OS, use a dash and then the
option.

DS33014L-page 232

 1994-2013 Microchip Technology Inc.

Linker Interfaces
Option (/ or -)

Description

a hexformat

Specify format of hex output file.

d

Do not generate a list file.

g

Generate report file for stack analysis.

h, ?

Display help screen.

i

Generate a list file without a COD file.

k pathlist

Add directories to linker search path.

l pathlist

Add directories to library search path.

m filename

Create map file filename.

n length

Specify number of lines per listing page. (0 = No pagination)

o filename

Specify output file filename. Default is a.out.

q

Quiet mode (no errors or warnings).

u sym[=value]

Specify multiple macros, where sym is a macro with alphanumeric
characters and value is a numerical value. If a value is not
provided, 0 will be used.

v

Verbose mode (all errors and warnings).

w

Suppress the mp2cod.exe utility. Using this option will prevent the
generation of a list file (.lst) and a COD file (.cod).

x

Suppress the mp2hex.exe utility. Using this option will prevent the
generation of a hex file (.hex, .hxl, .hxh).

zsymbol=value

Adds the symbol defined into the symbol table. For example,
/z__ICD2RAM=1 adds __ICD2RAM to the symbol table with a
value of 1.

There is no required order for the command line arguments; however, changing the
order can affect the operation of the linker. Specifically, additions to the
library/object directory search path are appended to the end of the current
library/object directory search path as they are encountered on the command
line and in command files.
Library and object files are searched for in the order in which directories occur in the
library/object directory search path. Therefore, changing the order of directories
may change which file is selected.
The /o or -o option is used to supply the name of the generated output COFF file for
the IDE debugging. Also generated is an Intel format hex file for programming. This file
has the same name as the output COFF file but with the file extension .hex. If this
option is not supplied, the default output COFF file is named a.out and the
corresponding hex file is named a.hex.

 1994-2013 Microchip Technology Inc.

DS33014L-page 233

Assembler/Linker/Librarian User’s Guide
10.4

COMMAND LINE EXAMPLE
An example of an MPLINK linker command line is shown below.
Windows OS:

mplink myscript.lkr /p18f452 main.o funct.o math.lib /m main.map /o main.out

Linux or Mac OS:
mplink myscript.lkr -p18f452 main.o funct.o math.lib -m main.map -o main.out

This instructs MPLINK linker to use the myscript.lkr linker script file to link the input
modules main.o, funct.o, and the precompiled library math.lib. It also instructs
the linker to produce a map file named main.map. main.o and funct.o must have
been previously compiled or assembled. The output files main.cof and main.hex
will be produced if no errors occur during the link process. The project applies to a
PIC18F452 device.

DS33014L-page 234

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 11. Linker Scripts
11.1

INTRODUCTION
Linker script files are used by the linker to generate application code. You no longer
need to add a device-specific linker script file to the command line or your MPLAB X
IDE or MPLAB IDE v8 project; the linker will find the appropriate file for you as long as
a device has been specified. However, if you want to use a non-standard linker script
file, you will have to add that manually.
Depending on the hardware debug tool you want to use, you may need to set certain
conditional symbols on the command line (see Example 11.8.4) or to select the Build
Configuration as “Debug” in MPLAB IDE v8 only.
Linker script files are the command files of the linker. They specify:
• Program and data memory regions for the target part
• Stack size and location (for MPLAB C18)
• A mapping of logical sections in source code into program and data regions
Linker script directives form the command language that controls the linker's behavior.
There are four basic categories of linker script directives. Each of these directives, plus
some useful linker script caveats, are discussed in the topics listed below.
Note:

Linker script comments are specified by '//', i.e., any text between a '//' and
the end of a line is ignored.

Topics covered in this chapter:
•
•
•
•
•
•
•

Standard Linker Scripts
Linker Script Command Line Information
Linker Script Caveats
Memory Region Definition
Logical Section Definition
STACK Definition
Conditional Linker Statements

 1994-2013 Microchip Technology Inc.

DS33014L-page 235

Assembler/Linker/Librarian User’s Guide
11.2

STANDARD LINKER SCRIPTS
Standard linker script files are provided for each device and are located, by default, in
the directory: C:\Program Files\Microchip\MPASM Suite\LKR.
Standard linker scripts are named with the following convention partnumber_g.lkr.
For example, the standard linker script for PIC16F872 is 16F872_g.lkr. The
standard linker scripts contain conditional linker statements and the IDE uses the /u
command line flag to utilize these statements for different builds such as debug or no
debug. You can modify a local copy of the standard linker script and use it in your
project.

DS33014L-page 236

 1994-2013 Microchip Technology Inc.

Linker Scripts
11.3

LINKER SCRIPT COMMAND LINE INFORMATION
The MPLAB Project Manager can set this information directly. You probably only need
to use these if you are linking from the command line.
•
•
•
•

LIBPATH
LKRPATH
FILES
INCLUDE

11.3.1

LIBPATH

Library and object files which do not have a path are searched using the
library/object search path. The following directive appends additional search
directories to the library/object search path:
LIBPATH libpath

where libpath is a semicolon-delimited list of directories.
EXAMPLE 11-1:

LIBPATH EXAMPLE

To append the current directory and the directory C:\PROJECTS\INCLUDE to the
library/object search path, the following line should be added to the linker script
file:
LIBPATH .;C:\PROJECTS\INCLUDE

11.3.2

LKRPATH

Linker script files that are included using a linker script INCLUDE directive are
searched for using the linker script file search path. The following directive appends
additional search directories to the linker script file search path:
LKRPATH lkrpath

where lkrpath is a semicolon-delimited list of directories.
EXAMPLE 11-2:

LKRPATH EXAMPLE

To append the current directory's parent and the directory C:\PROJECTS\SCRIPTS to
the linker script file search path, the following line should be added to the linker script
file:
LKRPATH ..;C:\PROJECTS\SCRIPTS

11.3.3

FILES

The following directive specifies object or library files for linking:
FILES objfile/libfile [objfile/libfile...]

where objfile/libfile is either an object or library file.
Note:

More than one object or library file can be specified in a single FILES
directive.

EXAMPLE 11-3:

FILES EXAMPLE

To specify that the object module main.o be linked with the library file math.lib, the
following line should be added to the linker script file:
FILES main.o math.lib

 1994-2013 Microchip Technology Inc.

DS33014L-page 237

Assembler/Linker/Librarian User’s Guide
11.3.4

INCLUDE

The following directive includes an additional linker script file:
INCLUDE cmdfile

where cmdfile is the name of the linker script file to include.
EXAMPLE 11-4:

INCLUDE EXAMPLE

To include the linker script file named mylink.lkr, the following line should be added
to the linker script file:
INCLUDE mylink.lkr

11.4

LINKER SCRIPT CAVEATS
Some linker script caveats:
• You may need to modify the linker script files included with MPLINK linker before
using them.
• You may wish to reconfigure stack size to use MPLAB C18 with MPLINK linker.
• You will need to split up memory pages if your code contains goto or call
instructions without pagesel pseudo-instructions (directives.)
• You must not combine data memory regions when using MPLINK linker with
MPLAB C18 C compiler. MPLAB C18 requires that any section be located within a
single bank. See MPLAB C18 documentation for directions on creating variables
larger then a single bank.

DS33014L-page 238

 1994-2013 Microchip Technology Inc.

Linker Scripts
11.5

MEMORY REGION DEFINITION
The linker script describes the memory architecture of the PIC1X MCU. This allows the
linker to place code in available ROM space and variables in available RAM space.
Regions that are marked PROTECTED will not be used for general allocation of program
or data. Code or data will only be allocated into these regions if an absolute address is
specified for the section, or if the section is assigned to the region using a SECTION
directive in the linker script file.

11.5.1

Defining RAM Memory Regions

The following directives are used for variable data in internal RAM. The formats for
these directives are as follows.

Banked Registers
DATABANK NAME=memName START=addr END=addr [PROTECTED]

Unbanked Registers
SHAREBANK NAME=memName START=addr END=addr [PROTECTED]

Access Registers (PIC18 devices only)
ACCESSBANK NAME=memName START=addr END=addr [PROTECTED]

Linear Data Memory (PIC16F1xxx devices only)
LINEARMEM NAME=linear0 START=addr END=addr PROTECTED
DATABANK NAME=memName START=addr END=addr SHADOWED=linear0:addr

where:
memName

Any ASCII string used to identify an area in RAM.

addr

A decimal (e.g., .30) or hexadecimal (e.g., 0xFF) number specifying an
address.

[ ]

An optional keyword.

PROTECTED

A keyword that indicates a region of memory that only can be used
when specifically identified in the source code. The linker will not use
the protected area.

SHADOWED

A keyword that maps a data memory range to the specified linear data
region linName at an address in that region.

 1994-2013 Microchip Technology Inc.

DS33014L-page 239

Assembler/Linker/Librarian User’s Guide
EXAMPLE 11-5:

RAM EXAMPLE - DATABANK AND SHAREBANK

Based on the RAM memory layout shown in PIC16F877A Register File Map, the
DATABANK and SHAREBANK entries in the linker script file would appear as shown in
the examples below the map.
FIGURE 11-1:

PIC16F877A REGISTER FILE MAP

Address

Bank 0

Bank 1

Bank 2

00h
01h

Bank 3

INDF0

INDF0

INDF0

INDF0

TMR0

OPTION_REG

TMR0

OPTION_REG

02h

PCL

PCL

PCL

PCL

03h

STATUS

STATUS

STATUS

STATUS

04h

FSR

FSR

FSR

FSR

05h

PORTA

TRISA

—

—

:

:

:

:

:

0Fh

TMR1H

—

EEADRH

—

10h

T1CON

—

:

:

:

1Fh

ADCON0

ADCON1

General Purpose
RAM (Banked)

General Purpose
RAM (Banked)

General Purpose
RAM (Banked)

General Purpose
RAM (Banked)

20h
:
6Fh
70h
:

General Purpose RAM (Unbanked)

7Fh

RAM Memory Declarations for PIC16F877A - Banked Memory
//Special Function Registers in Banks 0-3
DATABANK
NAME=sfr0
START=0x0
END=0x1F
DATABANK
NAME=sfr1
START=0x80
END=0x9F
DATABANK
NAME=sfr2
START=0x100
END=0x10F
DATABANK
NAME=sfr3
START=0x180
END=0x18F
//General Purpose RAM in Banks 0-3
DATABANK
NAME=gpr0
START=0x20
END=0x6F
DATABANK
NAME=gpr1
START=0xA0
END=0xEF
DATABANK
NAME=gpr2
START=0x110
END=0x16F
DATABANK
NAME=gpr3
START=0x190
END=0x1EF

PROTECTED
PROTECTED
PROTECTED
PROTECTED

RAM Memory Declarations for PIC16F877A - Unbanked Memory
//General Purpose RAM - available in all
SHAREBANK NAME=gprnobnk
START=0x70
SHAREBANK NAME=gprnobnk
START=0xF0
SHAREBANK NAME=gprnobnk
START=0x170
SHAREBANK NAME=gprnobnk
START=0x1F0

DS33014L-page 240

banks
END=0x7F
END=0xFF
END=0x17F
END=0x1FF

 1994-2013 Microchip Technology Inc.

Linker Scripts
EXAMPLE 11-6:

RAM EXAMPLE - ACCESSBANK

Based on the RAM memory layout shown in PIC18F8680 Register File Map, the
ACCESSBANK entries in the linker script file would appear as shown in the examples
below the map.
FIGURE 11-2:

PIC18F8680 REGISTER FILE MAP

Address Range

Bank

Data Memory Map

Access Bank

000h-05Fh

Bank 0

Access RAM

Access RAM Low

060h-0FFh

GPRs

100h-1FFh

Bank 1

GPRs

:

:

:

C00h-CFFh

Bank 12

GPRs

D00h-DFFh

Bank 13

CAN SFRs

E00h-EFFh

Bank 14

CAN SFRs

F00h-F5Fh

Bank 15

CAN SFRs

F60h-FFFh

SFRs

Access RAM High

RAM Memory Declarations for PIC18F8680 - Access Memory
ACCESSBANK NAME=accessram
ACCESSBANK NAME=accesssfr

 1994-2013 Microchip Technology Inc.

START=0x0
START=0xF60

END=0x5F
END=0xFFF

PROTECTED

DS33014L-page 241

Assembler/Linker/Librarian User’s Guide
EXAMPLE 11-7:

RAM EXAMPLE - LINEARMEM

Based on the RAM memory layout shown in PIC16F1939 Register File Map, the
LINEARMEM entries in the linker script file would appear as shown in the examples
below the map.
FIGURE 11-3:

PIC16F1939 REGISTER FILE MAP

Address Range General Purpose Registers

Bank

Linear Data Memory Map

20h-6Fh

80 bytes (GPR0)

Bank 0

2000h

A0h-EFh

80 bytes (GPR1)

Bank 1

2050h

120h-16Fh

80 bytes (GPR2)

Bank 2

20A0h

:

:

:

:

5A0h-5EFh

80 bytes (GPR11)

Bank 11

2370h

620h-66Fh

48 bytes and Unimplemented
(GPR12)

Bank 12

|

6A0h-6EFh

Unimplemented (GPR13)

Bank 13

|

:

:

:

|

F20h-F6Fh

Unimplemented (GPR30)

Bank 30

23EFh

RAM Memory Declarations for PIC16F1939 - Linear Memory Region
LINEARMEM
:
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK

NAME=linear0
NAME=gpr0
NAME=gpr1
NAME=gpr2
NAME=gpr3
NAME=gpr4
NAME=gpr5
NAME=gpr6
NAME=gpr7
NAME=gpr8
NAME=gpr9
NAME=gpr10
NAME=gpr11

DS33014L-page 242

START=0x2000
START=0x20
START=0xA0
START=0x120
START=0x1A0
START=0x220
START=0x2A0
START=0x320
START=0x3A0
START=0x420
START=0x4A0
START=0x520
START=0x5A0

END=0x23EF

END=0x6F
END=0xEF
END=0x16F
END=0x1EF
END=0x26F
END=0x2EF
END=0x36F
END=0x3EF
END=0x46F
END=0x4EF
END=0x56F
END=0x5EF

PROTECTED

SHADOW=linear0:0x2000
SHADOW=linear0:0x2050
SHADOW=linear0:0x20A0
SHADOW=linear0:0x20F0
SHADOW=linear0:0x2140
SHADOW=linear0:0x2190
SHADOW=linear0:0x21E0
SHADOW=linear0:0x2230
SHADOW=linear0:0x2280
SHADOW=linear0:0x22D0
SHADOW=linear0:0x2320
SHADOW=linear0:0x2370

 1994-2013 Microchip Technology Inc.

Linker Scripts
11.5.2

Defining ROM Memory Regions

The CODEPAGE directive is used for program code, initialized data values, constant
data values and external memory. It has the following format:
CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

where:
memName

Any ASCII string used to identify a CODEPAGE.

addr

A decimal (e.g., .30) or hexadecimal (e.g., 0xFF) number specifying an
address.

[ ]

An optional keyword.

FILL

A keyword used to specify a value which fills any unused portion of

a memory block. If this value is in decimal notation, it is
assumed to be a 16-bit quantity. If it is in hexadecimal notation
(e.g., 0x2346), it may be any length divisible by full words (16
bits).
A keyword that indicates a region of memory that only can be used
by program code that specifically requests it.

PROTECTED

EXAMPLE 11-8:

ROM EXAMPLE

The program memory layout for a PIC16F877A microcontroller is shown below.
Memory

Address

Reset Vector

Start: 0000h

Interrupt Vector

Start: 0004h

User Memory Space

0005h - 07FFh

User Memory Space

0800h - 0FFFh

User Memory Space

1000h - 17FFh

User Memory Space

1800h - 1FFFh

ID Locations

2000h - 2003h

Reserved

2004h - 2005h

Device ID

2006h

Configuration Memory Space

2007h

Reserved

2008h - 20FFh

EEPROM Data

2100h - 21FFh

Based on this map, the CODEPAGE declarations are:
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE

 1994-2013 Microchip Technology Inc.

NAME=page0
NAME=page1
NAME=page2
NAME=page3
NAME=.idlocs
NAME=.config
NAME=eedata

START=0x0000
START=0x0800
START=0x1000
START=0x1800
START=0x2000
START=0x2007
START=0x2100

END=0x07FF
END=0x0FFF
END=0x17FF
END=0x1FFF
END=0x2003
END=0x2007
END=0x21FF

PROTECTED
PROTECTED
PROTECTED

DS33014L-page 243

Assembler/Linker/Librarian User’s Guide
11.6

LOGICAL SECTION DEFINITION
Logical sections are used to specify which of the defined memory regions should be
used for a portion of source code. LINEARMEM is an example of a logical section.
To use logical sections, define the section in the linker script file with the SECTION
directive and then reference that name in the source file using that language's built-in
mechanism (e.g., #pragma section for MPLAB C18).
The section directive defines a section by specifying its name, and either the block of
program memory in ROM or the block of data memory in RAM which contains the
section:
SECTION NAME=secName { ROM=memName | RAM=memName }

where:
secName is an ASCII string used to identify a section.
memName is a previously defined ACCESSBANK, SHAREBANK, DATABANK, or
CODEPAGE.
The ROM attribute must always refer to program memory previously defined using a
CODEPAGE directive. The RAM attribute must always refer to data memory previously
defined with a ACCESSBANK, DATABANK or SHAREBANK directive.
EXAMPLE 11-9:

LOGICAL SECTION DEFINITION

To specify that a section whose name is filter_coeffs be loaded into the region of
program memory named constants, the following line should be added to the linker
script file:
SECTION NAME=filter_coeffs ROM=constants

EXAMPLE 11-10:

LOGICAL SECTION USAGE

To place MPASM source code into a section named filter_coeffs, use the
following line prior to the desired source code:
filter_coeffs CODE

11.7

STACK DEFINITION
Only MPLAB C18 requires a software stack be set up. The following statement
specifies the stack size and an optional DATABANK where the stack is to be allocated:
STACK SIZE=allocSize [RAM=memName]

where:
allocSize is the size in bytes of the stack and memName is the name of a memory
previously declared using a ACCESSBANK, DATABANK or SHAREBANK statement.
EXAMPLE 11-11:

STACK EXAMPLE

To set the stack size to be 0x20 in the RAM area previously defined by gpr0, the
following line should be added to the linker script file:
STACK SIZE=0x20 RAM=gpr0

DS33014L-page 244

 1994-2013 Microchip Technology Inc.

Linker Scripts
11.8

CONDITIONAL LINKER STATEMENTS
Generic linker scripts contain conditional statements and macros to accommodate
several different methods for linking code:
• Debug vs. Release - MPLAB IDE v8 Only (e.g., for the MPLAB REAL ICE
in-circuit emulator)
• C code vs. Assembly
• PIC18 Extended Microcontroller mode vs. Traditional mode
Being able to use one linker script instead of several simplifies application
development.
MPLINK linker accepts IF/ELSE type conditional statements in the linker scripts, as
discussed below. Several macros are used in support of the conditional statements.
Also, certain directives are useful with these conditional statements.

11.8.1

IFDEF/ELSE/FI

Two syntaxes are accepted for these conditional statements:

Conditional 1
#IFDEF
….
#FI

Conditional 2
#IFDEF
….
#ELSE
….
#FI

11.8.1.1

#IFDEF

Only one macro is allowed after this directive. If the macro is defined before, the if
clause will be parsed by the linker. Complex conditions must be constructed using
nested if-else clauses.
11.8.1.2

#ELSE

No macro is allowed after this directive. The else clause will be parsed only in case that
the if clause is not.
11.8.1.3

#FI

No macro is allowed after this directive. It identifies the end of if or else clause.

 1994-2013 Microchip Technology Inc.

DS33014L-page 245

Assembler/Linker/Librarian User’s Guide
11.8.2

Macros

Depending on what you want to do, macros may be set and used with conditional
statements to determine how the linker script will be interpreted by the linker.
If you are using MPLAB X IDE or MPLAB IDE v8, all macros listed in Table 11-1 will
automatically be set for you. For MPLAB IDE v8, the only exception is Debug vs.
Release, which must be selected under the Build Configuration. See MPLAB IDE
documentation for more on how to set the Build Configuration.
If you are using the command line, you must set the macros yourself. The macros that
are available for you to set are listed below. On the command line, precede the macro
with /u. See Section 11.8.4 “Examples of Use” for some examples.
TABLE 11-1:

LINKER SCRIPT MACROS

Macro

Use

_CRUNTIME

Link C code or mixed C code and assembly.

_EXTENDEDMODE

Use PIC18 extended microcontroller mode.

_DEBUG

Specify debug mode, as opposed to release or production mode.

_DEBUGCODESTART Set the start in program memory of the debug executive. I.e.,
/u_DEBUGCODESTART=address
_DEBUGCODELEN

Set the size of the debug executive. I.e.,
/u_DEBUGCODELEN=hexvalue

_DEBUGDATASTART

Set the start of data memory reserved registers. I.e.,
/u_DEBUGDATASTART=address

_DEBUGDATALEN

Set the amount of data memory reserved. I.e.,
/u_DEBUGCODELEN=hexvalue

11.8.3

Supporting Directives

The #DEFINE directive may be used to define a macro or define it and set its value.
The ERROR directive can be used within an if-else clause.
11.8.3.1

#DEFINE

This directive is used in the generic linker scripts to calculate the beginning and end of
the debug sections in code and data memory.
Through this directive, you can define an macro and associate a numerical value to it.
The value can only be calculated using an ‘+’, ‘-’, ‘/’ or ‘*’ operator over two previously
defined macros. Complex calculations must be constructed using combination of
multiple #DEFINE directives.
The following syntaxes are accepted:
#DEFINE
#DEFINE
#DEFINE
#DEFINE

newmacro
newmacro
newmacro
newmacro

macro1
macro1
macro1
macro1

+
/
*

macro2
macro2
macro2
macro2

newmacro may not be a previously defined macro.
macro1 and macro2 are previously defined macros. The numerical values associated
to these macros will be used to calculate a numerical value for newmacro.
11.8.3.2

ERROR

An ERROR directive has been added to MPLINK linker. This directive allows you to stop
the linker and emit the message in front of it on the standard output. The syntax of this
directive is:
ERROR msg

DS33014L-page 246

 1994-2013 Microchip Technology Inc.

Linker Scripts
11.8.4

Examples of Use

In these examples, the generic linker script for PIC18F6722 is used to demonstrate
how different options for building a project can be selected.
1. Building a C project, Extended mode:
mplink.exe /p18F6722 /u_CRUNTIME /u_EXTENDEDMODE 

2. Building a C project for PIC18F6722 with debug sections for code at 0x1fd80 and
for data at 0xef4, Traditional (non-extended) mode:
mplink.exe /p18F6722 /u_CRUNTIME /u_DEBUG /u_DEBUGCODESTART=0x1fd80
/u_DEBUGCODELEN=0x280 /u_DEBUGDATATART=0xef4 /u_DEBUGDATALEN=0xc


3. Building a Assembly project, no debug:
mplink.exe /p18f6722 

 1994-2013 Microchip Technology Inc.

DS33014L-page 247

Assembler/Linker/Librarian User’s Guide
Generic Linker Script - 18f6722_g.lkr
// File: 18f6722_g.lkr
// Generic linker script for the PIC18F6722 processor
#DEFINE
#DEFINE
#DEFINE
#DEFINE

_CODEEND _DEBUGCODESTART - 1
_CEND _DEBUGCODESTART + _DEBUGCODELEN
_DATAEND _DEBUGDATASTART - 1
_DEND _DEBUGDATASTART + _DEBUGDATALEN

LIBPATH .
#IFDEF _CRUNTIME
#IFDEF _EXTENDEDMODE
FILES c018i_e.o
FILES clib_e.lib
FILES p18f6722_e.lib
#ELSE
FILES c018i.o
FILES clib.lib
FILES p18f6722.lib
#FI
#FI
#IFDEF _DEBUGCODESTART
CODEPAGE
NAME=page
CODEPAGE
NAME=debug
#ELSE
CODEPAGE
NAME=page
#FI
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE

NAME=idlocs
NAME=config
NAME=devid
NAME=eedata

NAME=gpr0
NAME=gpr1
NAME=gpr2
NAME=gpr3
NAME=gpr4
NAME=gpr5
NAME=gpr6
NAME=gpr7
NAME=gpr8
NAME=gpr9
NAME=gpr10
NAME=gpr11
NAME=gpr12
NAME=gpr13

#IFDEF _DEBUGDATASTART
DATABANK
NAME=gpr14

DS33014L-page 248

END=_CODEEND
END=_CEND

START=0x0

END=0x1FFFF

START=0x200000
START=0x300000
START=0x3FFFFE
START=0xF00000

#IFDEF _EXTENDEDMODE
DATABANK
NAME=gpre
#ELSE
ACCESSBANK NAME=accessram
#FI
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK
DATABANK

START=0x0
START=_DEBUGCODESTART

END=0x200007
END=0x30000D
END=0x3FFFFF
END=0xF003FF

START=0x0

END=0x5F

START=0x0

END=0x5F

START=0x60
START=0x100
START=0x200
START=0x300
START=0x400
START=0x500
START=0x600
START=0x700
START=0x800
START=0x900
START=0xA00
START=0xB00
START=0xC00
START=0xD00

START=0xE00

PROTECTED
PROTECTED
PROTECTED
PROTECTED

END=0xFF
END=0x1FF
END=0x2FF
END=0x3FF
END=0x4FF
END=0x5FF
END=0x6FF
END=0x7FF
END=0x8FF
END=0x9FF
END=0xAFF
END=0xBFF
END=0xCFF
END=0xDFF

END=_DATAEND

 1994-2013 Microchip Technology Inc.

Linker Scripts
DATABANK
NAME=dbgspr
#ELSE //no debug
DATABANK
NAME=gpr14
#FI
DATABANK
NAME=gpr15
ACCESSBANK NAME=accesssfr

START=_DEBUGDATASTART

END=_DEND

START=0xE00

END=0xEFF

START=0xF00
START=0xF60

END=0xF5F
END=0xFFF

PROTECTED

PROTECTED

#IFDEF _CRUNTIME
SECTION
NAME=CONFIG
ROM=config
#IFDEF _DEBUGDATASTART
STACK SIZE=0x100 RAM=gpr13
#ELSE
STACK SIZE=0x100 RAM=gpr14
#FI
#FI

 1994-2013 Microchip Technology Inc.

DS33014L-page 249

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 250

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 12. Linker Processing
12.1

INTRODUCTION
Understanding how MPLINK linker processes files and information can be useful to
keep in mind when writing and structuring your application code.
Topics covered in this chapter:
•
•
•
•
•

12.2

Linker Processing Overview
Linker Allocation Algorithm
Relocation Example
Initialized Data
Reserved Section Names

LINKER PROCESSING OVERVIEW
A linker combines multiple input object modules into a single executable output
module. The input object modules may contain relocatable or absolute sections of code
or data which the linker will allocate into target memory. The target memory architecture
is described in a linker script file. This linker script file provides a flexible mechanism
for specifying blocks of target memory and for mapping sections to the specified
memory blocks. If the linker cannot find a block of target memory in which to allocate a
section, an error is generated. The linker combines like-named input sections into a
single output section. The linker allocation algorithm is described in
Section 12.3 “Linker Allocation Algorithm”.
Once the linker has allocated all sections from all input modules into target memory, it
begins the process of symbol relocation. The symbols defined in each input section
have addresses dependent upon the beginning of their sections. The linker adjusts the
symbol addresses based upon the ultimate location of their allocated sections.
After the linker has relocated the symbols defined in each input section, it resolves
external symbols. The linker attempts to match all external symbol references with a
corresponding symbol definition. If any external symbol references do not have a
corresponding symbol definition, an attempt is made to locate the corresponding
symbol definition in the input library files. If the corresponding symbol definition is not
found, an error is generated.
If the resolution of external symbols was successful, the linker then proceeds to patch
each section's raw data. Each section contains a list of relocation entries which
associate locations in a section's raw data with relocatable symbols. The addresses of
the relocatable symbols are patched into the raw data. The process of relocating
symbols and patching section is described in Section 12.4 “Relocation Example”.
After the linker has processed all relocation entries, it generates the executable output
module.

 1994-2013 Microchip Technology Inc.

DS33014L-page 251

Assembler/Linker/Librarian User’s Guide
12.3

LINKER ALLOCATION ALGORITHM
The linker allocates memory areas to allow maximum control over the location of code
and data, called "sections," in target memory. There are four kinds of sections that the
linker handles:
1.
2.
3.
4.

Absolute Assigned
Absolute Unassigned
Relocatable Assigned
Relocatable Unassigned

An absolute section is a section with a fixed (absolute) address that cannot be changed
by the linker. A relocatable section is a section that will be placed in memory based on
the linker allocation algorithm.
An assigned section is a section that has been assigned a target memory block in the
linker script file. An unassigned section is a section that has been left unassigned in this
file.
The linker performs allocation of absolute (assigned and unassigned) sections first,
relocatable assigned sections next, and relocatable unassigned sections last. The
linker also handles stack allocation.

12.3.1

Absolute Allocation

Absolute sections may be assigned to target memory blocks in the linker script file. But,
since the absolute section's address is fixed, the linker can only verify that if there is an
assigned target memory block for an absolute section, the target memory block has
enough space and the absolute section does not overlap other sections. If no target
memory block is assigned to an absolute section, the linker tries to find the one for it.
If one can not be located, an error is generated. Since absolute sections can only be
allocated at a fixed address, assigned and unassigned sections are performed in no
particular order.

12.3.2

Relocatable Allocation

Once all absolute sections have been allocated, the linker allocates relocatable
assigned sections. For relocatable assigned sections, the linker checks the assigned
target memory block to verify that there is space available; otherwise an error is
generated. The allocation of relocatable assigned sections occurs in the order in which
they were specified in the linker script file.
After all relocatable assigned sections have been allocated, the linker allocates
relocatable unassigned sections. The linker starts with the largest relocatable
unassigned section and works its way down to the smallest relocatable unassigned
section. For each allocation, it chooses the target memory block with the smallest
available space that can accommodate the section. By starting with the largest section
and choosing the smallest accommodating space, the linker increases the chances of
being able to allocate all the relocatable unassigned sections.

12.3.3

Stack Allocation

The stack is not a section but gets allocated along with the sections. The linker script
file may or may not assign the stack to a specific target memory block. If the stack is
assigned a target memory block, it gets allocated just before the relocatable assigned
sections are allocated. If the stack is unassigned, then it gets allocated after the
relocatable assigned sections and before the other relocatable unassigned sections
are allocated.

DS33014L-page 252

 1994-2013 Microchip Technology Inc.

Linker Processing
12.4

RELOCATION EXAMPLE
The following example illustrates how the linker relocates sections. Suppose the
following source code fragment occurred in a file:
/* File: ref.c */
char var1;
void setVar1(void)
{
var1 = 0xFF;
}

/* Line 1 */
/* Line 2 */
/* Line 3 */

Suppose this compiles into the following assembly instructions:
Note:

This example deliberately ignores any code generated by MPLAB C18 to
handle the function's entry and exit

0x0000 MOVLW 0xFF
0x0001 MOVLB ?? ; Need to patch with var1's bank
0x0002 MOVWF ?? ; Need to patch with var1's offset

When the compiler processes source line 1, it creates a symbol table entry for the
identifier var1 which has the following information:
Symbol[index] => name=var1, value=0, section=.data, class=extern

When the compiler processes source line 3, it generates two relocation entries in the
code section for the identifier symbol var1 since its final address is unknown until link
time. The relocation entries have the following information:
Reloc[index] => address=0x0001 symbol=var1 type=bank
Reloc[index] => address=0x0002 symbol=var1 type=offset

Once the linker has placed every section into target memory, the final addresses are
known. Once all identifier symbols have their final addresses assigned, the linker must
patch all references to these symbols using the relocation entries. In the example
above, the updated symbol might now be at location 0x125:
Symbol[index] => name=var1, value=0x125, section=.data, class=extern

If the code section above were relocated to begin at address 0x50, the updated
relocation entries would now begin at location 0x51:
Reloc[index] => address=0x0051 symbol=var1 type=bank
Reloc[index] => address=0x0052 symbol=var1 type=offset

The linker will step through the relocation entries and patch their corresponding
sections. The final assembly equivalent output for the above example would be:
0x0050 MOVLW 0xFF
0x0051 MOVLB 0x1
0x0052 MOVWF 0x25

 1994-2013 Microchip Technology Inc.

; Patched with var1's bank
; Patched with var1's offset

DS33014L-page 253

Assembler/Linker/Librarian User’s Guide
12.5

INITIALIZED DATA
MPLINK linker performs special processing for input sections with initialized data.
Initialized data sections contain initial values (initializers) for the variables and
constants defined within them. Because the variables and constants within an
initialized data section reside in RAM, their data must be stored in nonvolatile program
memory (ROM). For each initialized data section, the linker creates a section in
program memory. The data is moved by initializing code (supplied with MPLAB C18
and MPASM assembler) to the proper RAM location(s) at start-up.
The names of the initializer sections created by the linker are the same as the initialized
data sections with a _i appended. For example, if an input object module contains an
initialized data section named .idata_main.o the linker will create a section in
program memory with the name .idata_main.o_i which contains the data.
In addition to creating initializer sections, the linker creates a section named .cinit
in program memory. The .cinit section contains a table with entries for each
initialized data section. Each entry is a triple which specifies where in program memory
the initializer section begins, where in data memory the initialized data section begins,
and how many bytes are in the initialized data section. The boot code accesses this
table and copies the data from ROM to RAM.

12.6

RESERVED SECTION NAMES
Both the MPASM assembler and the MPLAB C18 C compiler have reserved names for
certain types of sections. Please see the documentation for these tools to ensure that
you do not use a reserved name for your own section. The linker will be unable to
generate the application if there is a section naming conflict.

DS33014L-page 254

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 13. Sample Applications
13.1

INTRODUCTION
You can learn the basics of how to use MPLINK linker from the four sample applications
listed below. These sample applications can be used as templates for your own
application.
• How to Build the Sample Applications
• Sample Application 1 - Templates and Linker Scripts
- How to find and use template files
- When to modify the generic linker script file
• Sample Application 2 - Placing Code and Setting Config Bits
- How to place program code in different memory regions
- How to place data tables in ROM memory
- How to set configuration bits in C
• Sample Application 3 - Using a Boot Loader
- How to partition memory for a boot loader
- How to compile code that will be loaded into external RAM and executed
• Sample Application 4 - Configuring External Memory
- How to create new linker script memory section
- How to declare external memory through #pragma code directive
- How to access external memories using C pointers

13.2

HOW TO BUILD THE SAMPLE APPLICATIONS
To build the sample applications, you will need the MPASM assembler, the MPLINK
linker and, for some sample applications, the MPLAB C compiler for PIC18 MCUs
(formerly MPLAB C18) installed on your PC. The assembler and linker are
automatically installed with MPLAB X IDE and MPLAB IDE v8, or may be acquired
separately on the Microchip website or the C compiler CD-ROM. A free demo (student)
version of the C compiler may be obtained on the Microchip website. The full C
compiler must be purchased separately.
By default, the tool executables are located as specified in the tables below.
TABLE 13-1:

ASSEMBLY CODE EXECUTABLES AND PATHS – MPLAB IDE V8

Executables

Default Paths to Executables

mpasmwin.exe

C:\Program Files\Microchip\MPASM Suite

mplink.exe

C:\Program Files\Microchip\MPASM Suite

TABLE 13-2:
Executables

ASSEMBLY CODE EXECUTABLES AND PATHS – MPLAB X IDE
Default Paths to Executables

mpasmx.exe

C:\Program Files\Microchip\MPLABX\mpasmx

mplink.exe

C:\Program Files\Microchip\MPLABX\mpasmx

 1994-2013 Microchip Technology Inc.

DS33014L-page 255

Assembler/Linker/Librarian User’s Guide
TABLE 13-3:

C CODE EXECUTABLES AND PATHS(1)

Executables

Default Paths to Executables

mcc18.exe

C:\mcc18\bin

mpasmwin.exe

C:\mcc18\mpasm

mplink.exe(2)

C:\mcc18\bin

Note 1:
2:

Future C compiler versions may be located at:
C:\Program Files\Microchip\MPLAB C18.
Use mplink.exe and not _mplink.exe. The executable file
_mplink.exe is not a stand-alone program.

To ensure the IDE sees the installed tools:
• For MPLAB X IDE, go to Tools>Options, Embedded button, Build Tools tab to
check the paths.
• For MPLAB IDE v8, go to Project>Set Language Tool Locations, “Microchip
MPASM Toolsuite”, “Executables”, and check the tool paths.
To use the examples, see:
• Using MPLAB X IDE
• Using MPLAB IDE v8
• Using the Command Line

13.2.1

Using MPLAB X IDE

MPLAB X IDE provides a GUI method of developing your code.
13.2.1.1

BUILDING APPLICATIONS

To build an application with MPLAB X IDE:
1. Use the Project wizard to create a project (File>New Project).
a) Choose Project: Select “Embedded” for the category and “C/ASM Standalone Project” for the project. Click Next> to continue.
b) Select Device: Select the device. Click Next> to continue.
c) Select Header: Select the header for this device if used.
d) Select Tool: Choose a development tool from the list. Tool support for the
selected device is shown as a colored circle next to the tool. Mouse over the
circle to see the support as text. Click Next> to continue.
e) Select Compiler: For assembly applications, select “MPASMX”. For C code
applications or combined C code and assembly applications, select “C18”.
Click Next> to continue.
f) Select Project Name and Folder: Enter a project name and then select a
location for the project folder. Click Finish to complete the project creation
and setup.
2. Once the project is created, add the sample files to your project, e.g.,
source1.c, source2.asm and (if customized) script.lkr.
3. Right click on the project name in the project tree and then select “Properties” to
set up language tool options.
- For MPLAB C compiler for PIC18 MCUs sample applications, click “MCC18”
and enter CompilerInstallationPath\lib under “Include Path”, where
CompilerInstallationPath is the location where the C compiler is
installed on your system.
- Select “MPLINK” and then enter a map file name next to “Generate map file”.

DS33014L-page 256

 1994-2013 Microchip Technology Inc.

Sample Applications
4. Right click on the project name in the project tree and select “Build” to build the
application. If your project contains a single assembly file with no linker script file,
you will be asked if you want to build “absolute” code or “relocatable” code. The
sample applications should be built as relocatable code.
5. If the application fails to build, check that the environment variables discussed in
the next section were set correctly during tool installation.
6. If the application build successfully, use Debug>Debug Project to run and debug
your application or Run>Run Project to run your application. To program it into a
device, click the “Program Target Progect” button on the debug toolbar.

13.2.2

Using MPLAB IDE v8

MPLAB IDE provides a GUI method of developing your code.
13.2.2.1

BUILDING APPLICATIONS

To build an application with MPLAB IDE:
1. Use the Project Wizard under the Project menu to create a project.
- Select the device specified in the sample application.
- For assembly applications, select the “Microchip MPASM Toolsuite” as the
active toolsuite. For C code applications or combined C code and assembly
applications, select the “Microchip C18 Toolsuite” as the active toolsuite.
Make sure the executable paths are correct, as per Table 13-1 or Table 13-3,
respectively.
- Name the project and place it in its own folder.
- Add the sample files to your project, e.g., source1.c, source2.asm and (if
customized) script.lkr.
2. Once the project is created, select Project>Build Options>Project to open the
Build Options for Project dialog.
- For MPLAB C compiler for PIC18 MCUs sample applications, click the
Directories tab and enter CompilerInstallationPath\lib under
“Library Path”, where CompilerInstallationPath is the location where
the C compiler is installed on your system.
- Click the MPLINK Linker tab and then click the “Generate map file” checkbox
to select it.
3. Select from the Build Configuration list (see below) whether you will be developing your application (Debug) or are ready to program it into a device (Release).

Setting this control will set the value for the macro _DEBUG found in the linker
script file. Other macros in the linker script (e.g., _CRUNTIME) are automatically
set by MPLAB IDE.
4. Select Project>Build All to build the application. If your project contains a single
assembly file with no linker script file, you will be asked if you want to build
“absolute” code or “relocatable” code. The sample applications should be built as
relocatable code.
5. If the application fails to build, check that the environment variables discussed in
the next section were set correctly during tool installation.

 1994-2013 Microchip Technology Inc.

DS33014L-page 257

Assembler/Linker/Librarian User’s Guide
13.2.2.2

EXAMPLE

As an example, consider Sample Application 3, C code mixed boot loader/application.
To build an application with MPLAB IDE:
1. Use the Project Wizard under the Project menu to create a project.
- Select PIC18F8722 as the device.
- Select the “Microchip C18 Toolsuite” as the active toolsuite. Make sure the
executable paths are correct, as per Table 13-3.
- Name the project and place it in its own folder.
- Add the sample files to your project, i.e., c018i_mod.c, mixed.asm and
mixed.lkr.
- View the Project window (View>Project) to see your project files.

2. Once the project is created, select Project>Build Options>Project to open the
Build Options for Project dialog.
- Click the Directories tab and enter C:\mcc18\lib under “Library Path”.
- Click the MPLINK Linker tab and then click the “Generate map file” checkbox
to select it.
3. Select “Debug“ from the Build Configuration list on the Project Manager toolbar.
4. Select Project>Build All to build the application.

DS33014L-page 258

 1994-2013 Microchip Technology Inc.

Sample Applications
13.2.3

Using the Command Line

The command line provides a platform independent method to develop your code.
13.2.3.1

BUILDING APPLICATIONS

To build an application on the command line:
1. The listed Environment Variables need to be set as specified. To set these variables, go to the Command prompt and type SET to view and set the variables.
In Windows OS, go to Start>Settings>Control Panel>System, Advanced tab,
Environment Variables button. View and edit variables here.
a) PATH - Make sure the executables can be found, as per Table 13-1 and
Table 13-3.
b) MCC_INCLUDE - If MPLAB C Compiler for PIC18 MCUs is used, this should
point to the \h subdirectory of the C compiler installation directory.
2. For C code compilation, use the following:
mcc18 -pdevice source1.c
where device is the device representation (e.g., 18F8772 for the PIC18F8722
device) and source1.c is the C code source file example. For multiple files,
leave a space between each file.
3. For MPASM assembly (with MPLAB X IDE), use the following:
Windows OS: mpasmx /pdevice source2.asm
Linux or Mac OS: mpasmx -pdevice source2.asm
where device is the device representation and source2.asm is the assembly
code source file example. For multiple files, leave a space between each file.
4. For MPLINK linking of files to create an application, use the following. The example is for Windows OS and is shown on two lines, but you should type on one.
mplink /pdevice /u_macro source1.o source2.o
/l c:\mcc18\lib /m app.map
or (for a modified linker script):
mplink modified.lkr /pdevice /u_macro source1.o source2.o
/l c:\mcc18\lib /m app.map
where:
Option

Description

device

The device representation.

modified.lkr

The modified linker script file.

_macro

A conditional macro (e.g., _CRUNTIME). For more details, see
Section 11.8 “Conditional Linker Statements”.

source1.o

A C code object file.

source2.o

An assembly code object file.

c:\mcc18\lib

The library path, only needed if the MPLAB C compiler for PIC18
MCUs was used, as here to generate source1.o from
source1.c.

app.map

The map file.

 1994-2013 Microchip Technology Inc.

DS33014L-page 259

Assembler/Linker/Librarian User’s Guide
13.2.3.2

EXAMPLE

As an example, consider Sample Application 3, C code mixed boot loader/application.
To build an application on the command line:
1. The listed Environment Variables need to be set as specified.
a) PATH - Make sure the executables can be found, as per Table 13-3.
b) MCC_INCLUDE - Point to the c:\mcc18\h subdirectory.
2. For C code compilation, use the following:
mcc18 -p18F8722 c018i_mod.c mixed.c
3. For MPLINK linking of files to create an application, use the following. The example is for Windows OS and is shown on two lines, but you should type on one.
mplink mixed.lkr /pdevice /u_CRUNTIME c018i_mod.o mixed.o
/l c:\mcc18\lib /m mixed.map
If you want to link for debug mode or PIC18 extended mode, see
Section 11.8 “Conditional Linker Statements”.

DS33014L-page 260

 1994-2013 Microchip Technology Inc.

Sample Applications
13.3

SAMPLE APPLICATION 1 - TEMPLATES AND LINKER SCRIPTS
In the MPLAB X IDE or MPLAB IDE v8 installation, assembly source code templates
and generic linker script files are provided for most devices supported by the IDE. The
source code templates give you a starting point from which to begin coding. The
generic linker scripts are used automatically by the linker to simplify application
development. Or you may modify a linker script and then manually add it on the linker
command line or to the project.
This first general example will discuss templates and linker scripts.

13.3.1

Locating Templates and Linker Script Files

For MPLAB X IDE or MPLAB IDE v8 installed in the default location, source code
templates may be found at:
C:\Program Files\Microchip\MPASM Suite\Template

in the following subdirectories:
• Code - Contains absolute assembly code examples by device
• Object - Contains relocatable assembly code examples by device
The relocatable source code template 18F8722TMPO.ASM for the PIC18F8722 may
be found in the Object directory. This template provides oscillator setup, example
variable and EEPROM setup, reset and interrupt handling routines, and a section main
for application code.
For MPLAB X IDE installed in the default location, the generic linker script files may be
found at:
C:\Program Files\Microchip\MPASM Suite\LKR

The generic linker script file for the PIC18F8722 would be 18f8722_g.lkr. This file
defines initialization files, program code sections, GPR sections, and access memory
sections. These definitions are grouped based on debugger or programmer usage, and
regular or extended memory usage.
Program memory sections specified by the template code and linker script are
compared below.
TABLE 13-4: PROGRAM MEMORY MAP - PIC18F8722
Program
Memory
Address
0x0000
0x0007

Linker Script Section
(Not debug or extended)
page - ROM code space

Template Source Code Section
RESET_VECTOR - Reset vector

0x0008
0x0017

HI_INT_VECTOR - High priority interrupt
vector

0x0018

LOW_INT_VECTOR - Low priority
interrupt vector

0x0019
0x01FFFF

High_Int - High priority interrupt handler
Low_Int - Low priority interrupt handler
Main - Main application code

0x200000
0x200007

idlocs - ID locations

0x300000
0x30000D

config - Configuration bits

0x3FFFFE
0x3FFFFF

devid - Device ID

0xF00000
0xF003FF

eedata - EEPROM data

 1994-2013 Microchip Technology Inc.

CONFIG - Configuration settings

DATA_EEPROM - Data EEPROM

DS33014L-page 261

Assembler/Linker/Librarian User’s Guide
13.3.2

Modifying Templates and Linker Script Files

For this sample application, assembly code is added to the template but the generic
linker script is not edited.
In general, you will modify templates to create your own application code but you
should not need to modify the generic linker script file. Still, there are reasons why you
might want to customize a linker script, as shown in the other sample applications.
In addition, a case where you might want to modify the linker script is when you want
to use a C code data object that is larger than 256 bytes, such as a large array. This
application is discussed in the MPLAB C Compiler for PIC18 MCUs Getting Started
(DS51295), FAQ-10.

Modified 18F8722TMPO.ASM
In the template, add the following udata section:
;

Oscillator Selection:
CONFIG OSC = LP

;LP

;Array variables
array
UDATA
element1
RES 1
element2
RES 1
element3
RES 1
element4
RES 1
element5
RES 2
;******************************************************************************
;Variable definitions

Then, in the main code portion, add the following program code:
;******************************************************************************
;Start of main program
; The main program code is placed here.
Main:
; *** main code goes here ***
banksel element1
movlw 0x55
movwf element1,1
movff element1,element2
rrcf element2,1,1
movff element2,WREG
movwf element3
rrcf element3,1,1
movff element3,element4
rrcf element4,1,1
movff element4,element5
rrcf element4,1,1
movff element4,element5+1

;Select element1 bank
;Move literal
;to element1
;Move element1
;to element2, right shift
;element2, move to WREG
;Move WREG to element3,
;right shift and
;move to element4
;Right shift element4
;and move to element5 low byte
;Right shift element4
;again and move to element5 high byte

Loop
goto Loop
;******************************************************************************
;End of program
END

DS33014L-page 262

 1994-2013 Microchip Technology Inc.

Sample Applications
13.3.3

Building the Application

To build the application, see Section 13.2 “How to Build the Sample Applications”.
Then, to continue development with the IDE, you could place the element variables in
a Watch(es) window to see their values, remembering to change element5 to a 16-bit
value (Properties dialog, Watch Properties tab).

 1994-2013 Microchip Technology Inc.

DS33014L-page 263

Assembler/Linker/Librarian User’s Guide
13.4

SAMPLE APPLICATION 2 - PLACING CODE AND SETTING CONFIG BITS
This example is for the PIC18F8720 in extended microcontroller mode.
The file eeprom2.asm places interrupt handling code at 0x20000 (external memory.)
The assembly code directive, INTHAND CODE, places the code that follows into the
INTHAND section. The modified linker script file (eeprom.lkr) maps the INTHAND
section to the CODE region that begins at 0x20000.
The file eeprom1.c has a 0x1000 element data table in program memory in the same
code page with the interrupt handlers. The data table is defined in C using the #pragma
romdata directive to place the table in a section called DATTBL. The modified linker
script file maps the DATTBL section to the CODE region that begins at 0x20000.
Additionally, configuration bits are set in C using the #pragma config directive.
The main function in the C file is placed in the default CODE section because there is
no section directive explicitly assigned.
For additional information, you may wish to reference:
• PIC18F8720 Device Data Sheet (DS39609)
• MPLAB C18 C Compiler User’s Guide (DS51288)
• External Memory Interfacing Techniques for the PIC18F8XXX (AN869)
Program memory sections specified by the code and linker script are compared below.
Specific sections highlighted in this sample application (SA2) are noted.
TABLE 13-5:
SA2





DS33014L-page 264

PROGRAM MEMORY MAP - PIC18F8720

Program
Memory Address

Linker Script Section
(Not debug or extended)

Source Code Section

0x000000
0x01FFFF

page - On-chip Memory

STARTUP
PROG - Main Application Code

0x020000
0x1FFFFF

eeprom - External Memory

INTHAND - Interrupt Handler
DATTBL - Data Table

0x200000
0x200007

idlocs - ID Locations

0x300000
0x30000D

config - Configuration Bits

0x3FFFFE
0x3FFFFF

devid - Device ID

0xF00000
0xF003FF

eedata - EE Data

CONFIG - Configuration Settings

 1994-2013 Microchip Technology Inc.

Sample Applications
13.4.1

C Source Code - eeprom1.c

/* eeprom1.c */
#include 
#define DATA_SIZE 0x1000
/* Data Table Setup */
#pragma romdata DATTBL // Put following romdata into section DATTBL
unsigned rom data[DATA_SIZE];
#pragma romdata
// Set back to default romdata section
/* Configuration Bits Setup
The #pragma config directive specifies the processor-specific
configuration settings (i.e., configuration bits) to be used by
the application. For more on this directive, see the "MPLAB C18
C Compiler User's Guide" (DS51288). */
#pragma
#pragma
#pragma
#pragma
#pragma

config
config
config
config
config

OSCS = ON, OSC = LP // Enable OSC switching and LP
PWRT = ON
// Enable POR
BOR = ON, BORV = 42 // Enable BOR at 4.2v
WDT = OFF
// Disable WDT
MODE = EM
// Use Extended MCU mode

/* Main application code for default CODE section */
void main( void )
{
while( 1 )
{
} // end while
} // end main

13.4.2

Assembler Source Code - eeprom2.asm

; eeprom2.asm
list p=18f8720
#include p18f8720.inc
INTHAND code
; place interrupt handling code in here
end

 1994-2013 Microchip Technology Inc.

DS33014L-page 265

Assembler/Linker/Librarian User’s Guide
13.4.3

Linker Script - eeprom.lkr

The linker script file eeprom.lkr is a modified version of the generic linker script file
18f8720_g.lkr. Modify the generic linker script as follows to create eeprom.lkr.
Add EEPROM codepage information:
#IFDEF _DEBUGCODESTART
CODEPAGE
NAME=page
CODEPAGE
NAME=debug
#ELSE
CODEPAGE
NAME=page
#FI

START=0x0
START=_DEBUGCODESTART

END=_CODEEND
END=_CEND

START=0x0

END=0x1FFFF

PROTECTED

//EEPROM codepage
CODEPAGE
NAME=eeprom

START=0x20000

END=0x1FFFFF

PROTECTED

CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE

START=0x200000
START=0x300000
START=0x3FFFFE
START=0xF00000

END=0x200007
END=0x30000D
END=0x3FFFFF
END=0xF003FF

PROTECTED
PROTECTED
PROTECTED
PROTECTED

NAME=idlocs
NAME=config
NAME=devid
NAME=eedata

Then add section information for the EEPROM sections:
#IFDEF _CRUNTIME
SECTION
NAME=CONFIG
ROM=config
SECTION
NAME=INTHAND
ROM=eeprom
SECTION
NAME=DATTBL
ROM=eeprom
#IFDEF _DEBUGDATASTART
STACK SIZE=0x100 RAM=gpr13
#ELSE
STACK SIZE=0x100 RAM=gpr14
#FI
#FI

13.4.4

// Interrupt handlers
// Data tables

Building the Application

To build the application, see Section 13.2 “How to Build the Sample Applications”.
Then, to continue development with MPLAB IDE v8:
Note:

MPLAB X IDE does not yet support External Memory views.

1. Though the configuration bits in code set the microcontroller mode to external,
you must tell the IDE the range of external memory you wish to use. Select Configure>External Memory. In the dialog, click “Use External Memory” and enter
“0x1FFFFF” as the “Address Range End”. Click OK.
2. Select Project>Build All to build the application again.

13.4.5

Absolute Method

Instead of adding SECTION lines to the linker script, you could add the absolute
address in code, i.e.,
INTHAND code 0x20000

However, if you need to place additional code in the CODEPAGE eeprom area, you
would need to know the disassembly code length of the interrupt handler to determine
the absolute address at which to place this additional code. Also, if you edit the interrupt
handler code, you would need to remember to change the address of the additional
code.
Therefore, it is usually easier not to place code absolutely but to allow the linker script
to place code for you.

DS33014L-page 266

 1994-2013 Microchip Technology Inc.

Sample Applications
13.5

SAMPLE APPLICATION 3 - USING A BOOT LOADER
A boot loader is a special program that, when programmed into the target PIC
microcontroller, is responsible for downloading and programming relocatable
application code into the same target PIC microcontroller. The relocatable application
or "user" code is typically transferred to the boot loader through serial communications,
such as RS232.

13.5.1

C Compiler Usage

This section discusses how to use the MPLAB C Compiler for PIC18 MCUs (the C
compiler) when developing bootloader and related appliation code.
There are three examples showing how to modify the C compiler linker scripts and how
to use the #pragma code directive in the source code for the C compiler boot loader
project. To better understand how the code corresponds to locations in device program
memory, see 13.5.1.1 “C Compiler Memory Map”.
Example 1 shows how to configure the C compiler linker script and suggests how to
use code directives for the C compiler boot loader. See 13.5.1.2 “Example 1: C
Compiler Boot Loader”.
Example 2 shows the C compiler linker script configuration and suggested code
directives for the C compiler application targeted for a microcontroller that is running
the C compiler boot loader. See 13.5.1.3 “Example 2: C Compiler Application”.
Example 3 is a mixed language example using the C compiler application targeted for
a microcontroller, such as the PIC18F8720 with a limited boot block size, running an
MPASM boot loader. A boot loader written in C code will typically require more program
memory than a boot loader written in assembly and therefore requires a microcontroller
with a larger boot block region, such as the PIC18F8722. See 13.5.1.4 “Example 3:
Mixed Language Boot Loader/Application”.
Boot loader and application code written for the C compiler must use the C compiler
linker scripts to command the linker to place the compiled C source code into
appropriate program memory sections. Typically, boot loader code is compiled and
linked for a destination in the "boot" section of the target microcontroller's program
memory. The "application" code is compiled and linked for a destination inside the user
section of program memory.
To build the C compiler sample application, refer to Section 13.2 “How to Build the
Sample Applications”.
13.5.1.1

C COMPILER MEMORY MAP

The first two C compiler boot loader examples are demonstrated using a PIC18F8722
which offers a configurable boot block size of 2K, 4K or 8K bytes. The remaining
program memory is available for the relocatable application code and data tables. For
these two examples it is assumed the boot block is configured for 2K bytes and requires
modification to the C compiler linker script file in order to accommodate the selected
boot block size.
The third example, a mix of an MPASM assembler boot loader and C compiler source
code, uses the PIC18F8720. For the corresponding memory map, see
Section 13.5.2.1 “Assembler Memory Map”.
For the first two examples, program memory sections specified by the code and linker
script are compared below. Specific sections highlighted in these sample application
(SA3) examples are noted.

 1994-2013 Microchip Technology Inc.

DS33014L-page 267

Assembler/Linker/Librarian User’s Guide
TABLE 13-6:
SA3

PROGRAM MEMORY MAP - PIC18F8722

Program
Memory Address



13.5.1.2

Linker Script Section
(Not debug or extended)

Source Code Section

0x000000
0x000029

vectors - Reset, Interrupts

Vectors, IntH, IntL

0x00002A
0x0007FF

boot - Boot Loader

Boot

0x000800
0x1FFFFF

page - Remapped Vectors
and User Code

R_vectors, R_IntH, R_IntL, Boot
Loader Updated Application Code

EXAMPLE 1: C COMPILER BOOT LOADER

This example shows a section of linker script modified to accomodate the boot loader
code.

Boot Loader Linker Script
The partial C compiler linker script file shown below demonstrates the modifications
required to the generic linker script when building the C compiler boot loader source
code files. The MPLINK linker will use this configuration to link the compiled source
code into the boot program memory region starting at 002Ah. The vector locations will
be specified in the boot loader source code using the appropriate #pragma code
directives.
CODEPAGE
CODEPAGE

NAME=vectors
NAME=boot

#IFDEF _DEBUGCODESTART
CODEPAGE
NAME=page
CODEPAGE
NAME=debug
#ELSE
CODEPAGE
NAME=page
#FI
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE

NAME=idlocs
NAME=config
NAME=devid
NAME=eedata

DS33014L-page 268

START=0x0
START=0x2A

END=0x29
END=0x7FF

START=0x800
START=_DEBUGCODESTART

END=_CODEEND
END=_CEND

START=0x800

END=0x1FFFF

START=0x200000
START=0x300000
START=0x3FFFFE
START=0xF00000

END=0x200007
END=0x30000D
END=0x3FFFFF
END=0xF003FF

PROTECTED

PROTECTED
PROTECTED
PROTECTED

 1994-2013 Microchip Technology Inc.

Sample Applications
Boot Loader Source Code
The C compiler boot loader code can be composed of one or more aggregate
relocatable C source files that are compiled and linked together during build time. In
this example, the source code file uses the #pragma code directive to instruct the
linker to place the interrupt vectors at memory locations 0008h and 0018h. A "main"
function must be included, as this is called from the C compiler startup code that is
added during link process.
#include 
#define RM_RESET_VECTOR
#define RM_HIGH_INTERRUPT_VECTOR
#define RM_LOW_INTERRUPT_VECTOR

0x000800 // define relocated vector addresses
0x000808
0x000818

/** VECTOR MAPPING *******************************************/
#pragma code _HIGH_INTERRUPT_VECTOR = 0x000008
void _high_ISR (void)
{
_asm goto RM_HIGH_INTERRUPT_VECTOR _endasm
}
#pragma code _LOW_INTERRUPT_VECTOR = 0x000018
void _low_ISR (void)
{
_asm goto RM_LOW_INTERRUPT_VECTOR _endasm
}
/** BOOT LOADER CODE ******************************************/
#pragma code
void main(void)
{
//Check Bootload Mode Entry Condition
if(PORTBbits.RB4 == 1)
// If not pressed, User Mode
{
_asm goto RM_RESET_VECTOR _endasm
}
//Else continue with bootloader code here ...
}
#pragma code user = RM_RESET_VECTOR
// This address defined as 0x800 above
// or can be defined in header file
/** END OF BOOT LOADER ****************************************/

 1994-2013 Microchip Technology Inc.

DS33014L-page 269

Assembler/Linker/Librarian User’s Guide
13.5.1.3

EXAMPLE 2: C COMPILER APPLICATION

This example shows a section of linker script modified to accomodate the application
code.

Application Linker Script
The boot loader linker script file may be used when building the C compiler application
source code files. The linker will use this configuration to link the compiled source code
into the page1 program memory region above the protected boot loader region.

Application Source Code
The C compiler application code can be composed of one or more aggregate
relocatable C source files that are compiled and linked together during build time. In the
code snippet shown below, the source code file uses the #pragma code directive to
instruct the linker to place the relocated reset and interrupt vectors at the appropriate
memory locations. A main function must be included, as this is called from the C
compiler startup code that is added during the link process. The linker automatically
includes this C compiler initialization code provided in file c018i.c and must be
accessed by the application code through an "in-line" assembly goto instruction
shown below.
#include 
/** VECTOR MAPPING *******************************************/
extern void _startup (void);
// See c018i.c in your C18 compiler dir
#pragma code _RESET_INTERRUPT_VECTOR = 0x000800
void _reset (void)
{
_asm goto _startup _endasm
}
#pragma code _HIGH_INTERRUPT_VECTOR = 0x000808
void _high_ISR (void)
{
;
}
#pragma code _LOW_INTERRUPT_VECTOR = 0x000818
void _low_ISR (void)
{
;
}
/** APPLICATION CODE******************************************/
#pragma code
void main(void)
{
while(1)
{
;
// Main application code here
}
}
/** END OF APPLICATION ***************************************/

DS33014L-page 270

 1994-2013 Microchip Technology Inc.

Sample Applications
13.5.1.4

EXAMPLE 3: MIXED LANGUAGE BOOT LOADER/APPLICATION

This example shows the linker script, startup code, and source code modifications
needed to accommodate a mixed language application which employs a boot loader.

Mixed Language Linker Script
The partial C compiler linker script file shown below demonstrates the required
modifications when building the mixed assembly boot loader/C code application. The
linker will use this configuration to link the compiled source code into the user program
memory region above the protected boot loader. In this linker script example, the C
compiler start-up file c018i.o has been remarked out, preventing the linker from
linking this object file to the project. Instead it will use the modified file in the next
section.
#IFDEF _CRUNTIME
#IFDEF _EXTENDEDMODE
FILES c018i_e.o
FILES clib_e.lib
FILES p18f8722_e.lib
#ELSE
//
FILES c018i.o
<-- Note this line to be ignored by linker
FILES clib.lib
FILES p18f8722.lib
#FI
#FI
CODEPAGE
CODEPAGE

NAME=vectors
NAME=boot

#IFDEF _DEBUGCODESTART
CODEPAGE
NAME=page
CODEPAGE
NAME=debug
#ELSE
CODEPAGE
NAME=page
#FI

START=0x0
START=0x2A

END=0x29
END=0x1FF

START=0x200
START=_DEBUGCODESTART

END=_CODEEND
END=_CEND

START=0x200

END=0x1FFFF

PROTECTED

Mixed Language c018i.c Modifications
For a typical C compiler application, the c018i.c startup code normally specifies
program memory location 0000h as the entry section and is linked into the project by
the linker when specified in the MPLAB C18 linker script. Since the C compiler
application code in this example has been relocated to program memory address
0200h because of the boot loader, it is necessary to change the code section
_entry_scn definition in c018i.c file as shown below and to add the c018i.c
source file to the project for recompiling and linking.
#pragma code _entry_scn=0x000200
void
_entry (void)
{
_asm goto _startup _endasm
}

 1994-2013 Microchip Technology Inc.

DS33014L-page 271

Assembler/Linker/Librarian User’s Guide
Mixed Language Source Code
The C compiler application code can be composed of one or more relocatable C source
files that are compiled and linked together during build time. In the code snippet shown
below, the source code file uses the #pragma code directive to instruct the linker to
place the relocated reset and interrupt vectors at the appropriate memory locations. A
main function must be included, as this is called from the C compiler startup code that
is added during the link process.
#include 
/** VECTOR MAPPING *******************************************/
#pragma code _HIGH_INTERRUPT_VECTOR = 0x000208
void _high_ISR (void)
{
;
// ISR goes here
}
#pragma code _LOW_INTERRUPT_VECTOR = 0x000218
void _low_ISR (void)
{
;
// ISR goes here
}
/** APPLICATION CODE******************************************/
#pragma code
void main(void)
{
while(1)
{
;
// Main application code here
}
}
/** END OF APPLICATION ***************************************/

13.5.2

Assembler Usage

This section discusses how to use the MPASM assembler (the assembler) when
developing bootloader and related appliation code.
There are three assembler examples showing suggested linker script modifications
and appropriate source code directive usage for a boot loader and application project.
To better understand how the code corresponds to locations in device program
memory, see Section 13.5.2.1 “Assembler Memory Map”.
The modified linker script file provided in this example is designed to support all three
of the following examples. See Section 13.5.2.2 “Assembler Linker Script”.
Example 1 shows an assembler boot loader. See Section 13.5.2.3 “Example 1:
Assembler Boot Loader Source Code”.
Example 2 shows a multiple module relocatable assembler application. See
Section 13.5.2.4 “Example 2: Assembler Application Source Code”.
Example 3 incorporates both the assembler boot loader and multiple module
relocatable assembler application as a single program memory image. See
Section 13.5.2.5 “Example 3: Assembler Boot Loader/Application Source Code”.
To build the assembler sample application, refer to Section 13.2 “How to Build the
Sample Applications”.

DS33014L-page 272

 1994-2013 Microchip Technology Inc.

Sample Applications
13.5.2.1

ASSEMBLER MEMORY MAP

The boot loader typically resides in the "boot block" region of the PIC18F8720's
program memory, which is the first 512 bytes of memory, from location 0000h to 01FFh.
The remaining program memory, starting at location 0200h, is available for relocatable
application code and data lookup tables. Other PIC18F microcontrollers offer larger
boot block regions and will require slightly different linker script modifications than what
is represented in this example. However, the concepts shown here can be migrated to
these other PIC microcontrollers.
For this example, program memory sections specified by the code and linker script are
compared below. Specific sections highlighted in this sample application (SA3)
example are noted.
TABLE 13-7:
SA3

PROGRAM MEMORY MAP - PIC18F8720

Program
Memory Address



13.5.2.2

Linker Script Section

Source Code Section

0x000000
0x000029

vectors - Reset, Interrupts

Vectors, IntH, IntL

0x00002A
0x0001FF

boot_code - Boot Loader

Boot

0x000200
0x1FFFFF

page - Remapped Vectors,
User Code, Data Tables

R_vectors, R_IntH, R_IntL,
user_code

ASSEMBLER LINKER SCRIPT

To protect the boot block and vector memory regions, the linker script file uses modified
CODEPAGE directives to establish these memory regions and uses the PROTECTED
modifier to prevent the linker from assigning any relocatable code that is not explicitly
assigned to these regions.
The section of modified generic linker script below shows how the linker can assign the
relocatable application code to the user code memory region (page) that is not
protected. The other program memory regions can only be populated if the CODE
directive used in the source files specifies placement of code within these protected
memory regions. This linker script file is designed to accommodate all three boot loader
design considerations demonstrated in this chapter.
boot.lkr - The linker script file for boot loader and application code example projects.
CODEPAGE
CODEPAGE

NAME=vectors
NAME=boot

#IFDEF _DEBUGCODESTART
CODEPAGE
NAME=page
CODEPAGE
NAME=debug
#ELSE
CODEPAGE
NAME=page
#FI
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE

NAME=idlocs
NAME=config
NAME=devid
NAME=eedata

 1994-2013 Microchip Technology Inc.

START=0x0
START=0x2A

END=0x29
END=0x1FF

START=0x200
START=_DEBUGCODESTART

END=_CODEEND
END=_CEND

START=0x200

END=0x1FFFF

START=0x200000
START=0x300000
START=0x3FFFFE
START=0xF00000

END=0x200007
END=0x30000D
END=0x3FFFFF
END=0xF003FF

PROTECTED
PROTECTED

PROTECTED

PROTECTED
PROTECTED
PROTECTED

DS33014L-page 273

Assembler/Linker/Librarian User’s Guide
13.5.2.3

EXAMPLE 1: ASSEMBLER BOOT LOADER SOURCE CODE

In this example, the boot loader is a single source file that will not be linked with any
other source code at build time. The CODE directives used in the boot loader source
code instructs the linker to place the reset and interrupt vectors at their appropriate
program memory locations for the PIC microcontroller and to place the starting location
of the boot loader executable code just above this region starting at location 002Ah.
The program memory section names Vectors, IntH and IntL are used with the
CODE directive to instruct the linker to place the assembled code that follows each
directive at the specified program memory location. In this case, the boot loader is not
linked with any application code so the relocated reset and interrupt vectors, 0208h,
0218h and 022Ah are assumed and therefore are explicitly coded.
18Fboot.asm - This is an example of how the startup portion of a boot loader could be configured when
designing and programming only the boot loader code into the target PIC microcontroller.
; *****************************************************************************
; 18Fboot.asm
; *****************************************************************************
LIST P=18F8720
#include P18cxxx.inc
; *****************************************************************************
Vectors
code 0x0000
VReset:
bra
Boot_Start
IntH
VIntH:

code
bra

0x0008
0x0208

; Re-map Interrupt vector to app's code space

IntL
VIntL:

code
bra

0x0018
0x0218

; Re-map Interrupt vector to app's code space

; *****************************************************************************
Boot
code
0x002A
; Boot loader executable code starts here
Boot_Start:
; Logic to determine if bootloader executes or branch to user's code
; ...
bra
0x022A
; Branch to user's application code
; ...
; end of boot loader code section
; *****************************************************************************
END

DS33014L-page 274

 1994-2013 Microchip Technology Inc.

Sample Applications
13.5.2.4

EXAMPLE 2: ASSEMBLER APPLICATION SOURCE CODE

In this example the application code is composed of several relocatable source files
that are assembled and linked together during build time. The relocatable reset and
interrupt vector locations are defined in main.asm and are assigned to a specific
program memory location by the CODE directive.
main.asm - This is a sample of the startup portion of a main source code file that contains the relocated
reset and interrupts and is the main entry point into the application.
; *****************************************************************************
; main.asm
; *****************************************************************************
LIST P=18F8720
#include P18cxxx.inc
; *****************************************************************************
R_vectors
code
0x200
RVReset:
;Re-mapped RESET vector
bra
main
R_IntH
code
0x208
;Re-mapped HI-priority interrupt vector
RVIntH:
;High priority interrupt vector code here
;...
retfie
R_IntL
code
0x218
;Re-mapped LOW-priority interrupt vector
RVIntL:
;Low priority interrupt vector code here
;...
retfie
user_code
code
0x22A
main:
; Entry into application code starts here
; ....
; end of main code section
; *****************************************************************************
END

 1994-2013 Microchip Technology Inc.

DS33014L-page 275

Assembler/Linker/Librarian User’s Guide
13.5.2.5

EXAMPLE 3: ASSEMBLER BOOT LOADER/APPLICATION SOURCE
CODE

The final example demonstrates the possibility of combining both the boot loader and
application code into a single program memory image that can be programmed into a
target microcontroller at the same time. Since the boot loader will be assembled and
linked with the application source code files, any references to external labels, defined
in the application code, must be resolved by the linker. To accomplish this, the GLOBAL
directive used in main.asm and the EXTERN directive used in the boot loader source
file allow the linker to resolve the relocated reset and interrupt vector labels defined in
main.asm and referenced in the 18Fboot_r.asm. For this example, the same boot.lkr
linker script file used in the previous examples is used to link the boot loader and
application files together.
18Fboot_r.asm - This sample version of the boot loader allows for relocatable vectors that are defined, not
in the boot loader, but in the application source code.
; *****************************************************************************
; 18Fboot_r.asm
; *****************************************************************************
LIST P=18F8720
#include P18cxxx.inc
; Declare labels used here but defined outside this module
extern RVReset, RVIntH, RVIntL
; *****************************************************************************
Vectors
code 0x0000
VReset:
bra
Boot_Start
IntH
VIntH:

code
bra

0x0008
RVIntH

; Re-map Interrupt vector

IntL
VIntL:

code
bra

0x0018
RVIntL

; Re-map Interrupt vector

; *****************************************************************************
Boot
code
0x002A
; Define explicit Bootloader location
Boot_Start:
; Determine if bootloader should execute or branch to user's code
; ....
bra
RVReset
; Branch to user's application code
; Else Bootloader execution starts here
; ....
; *****************************************************************************
END

DS33014L-page 276

 1994-2013 Microchip Technology Inc.

Sample Applications
main_r.asm - This is a sample version of a main source code file that uses the GLOBAL directive to make
the relocatable reset and interrupt vector labels available to the boot loader.
; *****************************************************************************
; main_r.asm
; *****************************************************************************
LIST P=18F8720
#include P18cxxx.inc
; Define labels here but used outside this module
global
RVReset, RVIntH, RVIntL
; *****************************************************************************
R_vectors
code
0x200
RVReset:
;Re-mapped RESET vector
bra
main
R_IntH
code
0x208
;Re-mapped HI-priority interrupt vector
RVIntH:
;High priority interrupt vector code here
;...
retfie
R_IntL
code
0x218
;Re-mapped LOW-priority interrupt vector
RVIntL:
;Low priority interrupt vector code here
;...
retfie
user_code
code
0x22A
main:
; Entry into application code starts here
; ....
; end of main code section
; *****************************************************************************
END

 1994-2013 Microchip Technology Inc.

DS33014L-page 277

Assembler/Linker/Librarian User’s Guide
13.6

SAMPLE APPLICATION 4 - CONFIGURING EXTERNAL MEMORY
Most of the larger pin count PIC microcontrollers have the ability to interface to external
Note:

MPLAB X IDE does not yet support External Memory views.

8- or 16-bit data FLASH or SRAM memories through the External Memory Bus (EMB).
The PIC18F8722, for example, has 128K bytes of internal program memory (00000h 1FFFFh). But, when configured for Extended Microcontroller mode, external program
memory space from locations 20000h through 1FFFFFh becomes externally
addressable through the EMB created from the I/O pins.
The use of a linker script file can be extended to other external memory-mapped
devices such as programmable I/O peripherals, real-time clocks or any device that has
multiple configuration or control registers that can be accessed through an 8- or 16-bit
data bus.

13.6.1

C Compiler Usage

This section discusses how to use the MPLAB C Compiler for PIC18 MCUs (the C
compiler) when developing external memory appliation code.
The C compiler linker script file for the PIC18F8722 is modified to instruct the linker that
a new memory region is available by adding a CODEPAGE definition as shown below.
The use of the PROTECTED modifier prevents the linker from assigning random
relocatable code to this region. The name xsram is arbitrary and can be any desired
name. What is important are the START and END addresses, which should match the
physical memory address reange of the external memory being used.
CODEPAGE

NAME=xsram

START=0x020000

END=0x01FFFFF

PROTECTED

In addition to the new CODEPAGE, a new logical SECTION is created and assigned to
the program memory region specified in the associated CODEPAGE definition.
SECTION

NAME=SRAM_BASE

ROM=xsram

In the C compiler application's source code file, the #pragma romdata directive
instructs the linker to allocate the SRAM's starting address to the memory region
specified by the SRAM_BASE logical section definition. The physical address is provided
by the xsram codepage directive at 20000h. Since the memory region occupied by the
SRAM is program memory, not data memory, the rom qualifier is required in the
declaration of the char array variable, sram[]. In addition, this memory region is
beyond a 16-bit address range (64Kbyte) and therefore requires the use of the far
qualifier in order for C pointers to correctly access this region.
#pragma romdata SRAM_BASE ;Assigns this romdata space at 0x020000
rom far char sram[];
;Declare an array at starting address

To build the C compiler sample application, refer to Section 13.2 “How to Build the
Sample Applications”.
The large memory model must be used in this project.
• At the end of Step 2, click the MPLAB C18 tab and chose the Category of
“Memory Model” from the drop-down list. Under “Code Model”, click “Large code
mode (>64K)“.
• For the command line, use the -ml option when compiling.

DS33014L-page 278

 1994-2013 Microchip Technology Inc.

Sample Applications
13.6.1.1

C COMPILER MEMORY MAP

The table below shows the memory mapping for the PIC18F8722 when used with the
1Mbyte external SRAM device. Notice that the first 128K bytes of the external memory
region is overlapped with the 128K bytes of internal program memory space and
therefore cannot be accessed using the external memory bus. Without any additional
external memory address decoding, the first 128K bytes of the SRAM are not
accessible and therefore the first addressable location of SRAM is 20000h, as used in
this example (SA4).
TABLE 13-8:
SA4

PROGRAM MEMORY MAP - PIC18F8722 AND 1MB SRAM

Program
Memory
Address
0x000000
0x01FFFF



0x020000
0x0FFFFF

SRAM
Address
0x000000
0x01FFFF
0x020000
0x0FFFFF

LInker Script Section

Source Code Section

page - Reset, Interrupt
vectors and On-chip
Memory
xsram - External Memory

SRAM_BASE - romdata
space

0x100000
0x1FFFFF

13.6.1.2

C COMPILER LINKER SCRIPT

The sections of modifed PIC18F8722 C compiler generic linker script file shown below
demonstrates suggested modifications for external memory applications.
First the CODEPAGE statement is added.
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE

NAME=xsram
NAME=idlocs
NAME=config
NAME=devid
NAME=eedata

START=0x020000
START=0x200000
START=0x300000
START=0x3FFFFE
START=0xF00000

END=0x1FFFFF
END=0x200007
END=0x30000D
END=0x3FFFFF
END=0xF003FF

PROTECTED
PROTECTED
PROTECTED
PROTECTED
PROTECTED

Then the external memory section is added.
#IFDEF _CRUNTIME
SECTION
NAME=CONFIG
ROM=config
SECTION
NAME=SRAM_BASE ROM=xsram
#IFDEF _DEBUGDATASTART
STACK SIZE=0x100 RAM=gpr13
#ELSE
STACK SIZE=0x100 RAM=gpr14
#FI
#FI

 1994-2013 Microchip Technology Inc.

DS33014L-page 279

Assembler/Linker/Librarian User’s Guide
13.6.1.3

C COMPILER SOURCE CODE

This is a simple code example showing the use of #pragma romdata for declaration
of external memory and the use of C pointers for accessing this memory region.
If you are using MPLAB IDE v8 to run this example, remember to enable external
memory (Configure>External Memory) to see this extra memory in the Program
Memory window.
#include 
// Microprocessor mode - a memory mode that supports external memory.
#pragma config MODE = MP
#pragma romdata SRAM_BASE
rom far char sram[];
#pragma code
void main(void)
{
rom far char* dataPtr;
dataPtr = sram;
*dataPtr++ = 0xCC;
*dataPtr = 0x55;
}

DS33014L-page 280

// Assigns this romdata space at 0x20000
// Declare an array at starting address

// Create a "far" pointer
// Assign this pointer to the memory array
// Write low byte of 16-bit word to SRAM
// Write high byte of 16-bit word to SRAM

 1994-2013 Microchip Technology Inc.

Sample Applications
13.6.2

Assembler Usage

This section discusses how to use the MPASM assembler (the assembler) when
developing external memory appliation code.
In an assembler application's source file, using a simple #define or equ directive
provides an easy way to define the SRAM starting address, which can be used to set
up the table pointers prior to a table read or table write operation.
#define SRAM_BASE_ADDRS 0x20000
#define SRAM_END_ADDRS

;Base addrs for external
;memory device
0x1FFFFF ;End addrs (not required)

Accessing the external program memory through table reads and table writes requires
the table pointer register be set up with the appropriate address as shown by the
following example.
movlw
movwf
movlw
movwf
movlw
movwf

upper (SRAM_BASE_ADDRS)
TBLPTRU
high (SRAM_BASE_ADDRS)
TBLPTRH
low (SRAM_BASE_ADDRS)
TBLPTRL

To build the assembler sample application, refer to Section 13.2 “How to Build the
Sample Applications”.
13.6.2.1

ASSEMBLER MEMORY MAP

The figure below shows the memory mapping for the PIC18F8722 when used with the
1Mbyte external SRAM device. Notice that the first 128K bytes of the external memory
region is overlapped with the 128K bytes of internal program memory space and
therefore cannot be accessed using the external memory bus. Without any additional
external memory address decoding, the first 128K bytes of the SRAM are not
accessible and therefore the first addressable location of SRAM is 20000h, as used in
this example (SA4).
TABLE 13-9:
SA4

PROGRAM MEMORY MAP - PIC18F8722 AND 1MB SRAM

Program
Memory
Address
0x000000
0x000029
0x00002A
0x01FFFF



0x020000
0x0FFFFF

SRAM
Address

0x000000
0x01FFFF
0x020000
0x0FFFFF

LInker Script Section

Source Code Section

vectors - Reset, Interrupts

vectors

page - On-chip Memory

prog - Main Program

xsram - External Memory

SRAM_BASE_ADDRS
SRAM_END_ADDRS

0x100000
0x1FFFFF

 1994-2013 Microchip Technology Inc.

DS33014L-page 281

Assembler/Linker/Librarian User’s Guide
13.6.2.2

ASSEMBLER LINKER SCRIPT

The modifed PIC18F8722 assembler linker script file shown below demonstrates
suggested modifications for external memory applications.
First the CODEPAGE statements are added.
CODEPAGE

NAME=vectors

#IFDEF _DEBUGCODESTART
CODEPAGE
NAME=page
CODEPAGE
NAME=debug
#ELSE
CODEPAGE
NAME=page
#FI
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE
CODEPAGE

NAME=xsram
NAME=idlocs
NAME=config
NAME=devid
NAME=eedata

START=0x0

END=0x29

START=0x2A
START=_DEBUGCODESTART

END=_CODEEND
END=_CEND

START=0x2A

END=0x1FFFF

START=0x020000
START=0x200000
START=0x300000
START=0x3FFFFE
START=0xF00000

END=0x1FFFFF
END=0x200007
END=0x30000D
END=0x3FFFFF
END=0xF003FF

PROTECTED

PROTECTED

PROTECTED
PROTECTED
PROTECTED
PROTECTED
PROTECTED

Then the vectors, program, and external memory section is added.
#IFDEF _CRUNTIME
SECTION
NAME=CONFIG
ROM=config
SECTION
NAME=VECTORS
ROM=vectors
SECTION
NAME=PROG
ROM=page
SECTION
NAME=SRAM
ROM=xsram
#IFDEF _DEBUGDATASTART
STACK SIZE=0x100 RAM=gpr13
#ELSE
STACK SIZE=0x100 RAM=gpr14
#FI
#FI

DS33014L-page 282

 1994-2013 Microchip Technology Inc.

Sample Applications
13.6.2.3

ASSEMBLER SOURCE CODE

This is a simple code example showing the definition of the external memory SRAM
address at 20000h and how to write a 16-bit value to two consecutive memory locations
using the table pointer register and table write instruction.
If you are using MPLAB IDE v8 to run this example, remember to enable external
memory (Configure>External Memory) to see this extra memory in the Program
Memory window.
#include 
; Microprocessor mode - a memory mode that supports external memory.
CONFIG MODE = MP
#define SRAM_BASE_ADDRS 0x20000
#define SRAM_END_ADDRS 0x1FFFFF

; Base addrs for external memory device
; End addrs (not required)

vectors code
bra
main
prog
code
main:
; Example - how to write "0x55CC" to first word location in external SRAM memory
movlw
movwf
movlw
movwf
movlw
movwf

upper (SRAM_BASE_ADDRS)
TBLPTRU
high (SRAM_BASE_ADDRS)
TBLPTRH
low (SRAM_BASE_ADDRS)
TBLPTRL

movlw
0xCC
movwf
TABLAT
tblwt*+
movlw
movwf
tblwt*

; Writes "0xCC" to byte location 0x020000;
; Increments table pointer to next location

0x55
TABLAT
; Write "0x55" to byte location 0x020001;

END

 1994-2013 Microchip Technology Inc.

DS33014L-page 283

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 284

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 14. Errors, Warnings and Common Problems
14.1

INTRODUCTION
Error messages and warning messages are produced by the MPLINK linker. These
messages always appear in the listing file directly above each line in which the error
occurred.
Common problems and limitations of the linker tool are also listed here.
Topics covered in this chapter:
•
•
•
•
•
•

14.2

Linker Parse Errors
Linker Errors
Linker Warnings
COFF File Errors
Other Errors, Warnings and Messages
Common Problems

LINKER PARSE ERRORS
MPLINK linker parse errors are listed alphabetically below:

Could not open 'cmdfile'.
A linker script file could not be opened. Check that the file exists, is in the current search
path, and is readable.

Illegal  for FILES in 'cmdfile:line'.
An object or library filename must end with .o or .lib respectively.

Illegal  for INCLUDE in 'cmdfile:line'.
A linker script filename must end with .lkr.

Illegal  for LIBPATH in 'cmdfile:line'.
The libpath must be a semicolon delimited list of directories. Enclose directory name
which have embedded spaces in double quotes.

Illegal  for LKRPATH in 'cmdfile:line'.
The lkrpath must be a semicolon delimited list of directories. Enclose directory names
which have embedded spaces in double quotes.

Invalid attributes for memory in 'cmdfile:line'.
A CODEPAGE, DATABANK, or SHAREBANK directive does not specify a NAME,
START, or END attribute; or another attribute is specified which is not valid.

Invalid attributes for SECTION in 'cmdfile:line'.
A SECTION directive must have a NAME and either a RAM or ROM attribute.

 1994-2013 Microchip Technology Inc.

DS33014L-page 285

Assembler/Linker/Librarian User’s Guide
Invalid attributes for STACK in 'cmdfile:line'.
A STACK directive does not specify a SIZE attribute, or another attribute is specified
which is not valid.

-k switch requires .
A semicolon delimited path must be specified. Enclose directory names containing
embedded spaces with double quotes. For example:
-k ..;c:\mylkr;"c:\program files\microchip\mpasm suite\lkr"

-l switch requires .
A semicolon delimited path must be specified. Enclose directory names containing
embedded spaces with double quotes. For example:
-l ..;c:\mylib;"c:\program files\microchip\mpasm suite"

-m switch requires .
A map filename must be specified. For example: -m main.map.

Multiple inclusion of library file 'filename'.
A library file has been included multiple times either on the command line or with a
FILES directive in a linker script file. Remove the multiple references.

Multiple inclusion of linker script file 'cmdfile'.
A linker script file can only be included once. Remove multiple INCLUDE directives to
the referenced linker script file.

Multiple inclusion of object file 'filename'.
An object file has been included multiple times either on the command line or with a
FILES directive in a linker script file. Remove the multiple references.

-n switch requires .
The number of source lines per listing file page must be specified. A length of zero will
suppress pagination of the listing file.

-o switch requires .
A COFF output filename must be specified. For example: -o main.out

Unknown switch: 'cmdline token'.
An unrecognized command line switch was supplied. Refer to the Usage
documentation for the list of supported switches.

Unrecognized input in 'cmdfile:line'.
All statements in a linker script file must begin with a directive keyword or the comment
Delimiter //.

DS33014L-page 286

 1994-2013 Microchip Technology Inc.

Errors, Warnings and Common Problems
14.3

LINKER ERRORS
MPLINK linker errors are listed alphabetically below:

Absolute code section 'secName' must start at a word-aligned address.
Program code sections will only be allocated at word-aligned addresses. MPLINK will
give this error message if an absolute code section address is specified that is not
word-aligned.

Configuration settings have been specified for address 0x300001 in
more than one object module. Found in 'foo.o' previously found in 'bar.o'
This error is issued when MPLAB C18's #pragma config directive has been used in
two separate .c files (e.g., foo.c and bar.c) with settings specified from the same
configuration byte. Set configuration bits for a given byte in a single .c file.

Conflicting types for symbol ‘symName’.
Symbol symName is defined in different locations as different types.

Could not find definition of symbol 'symName' in file ‘filename’.
A symbol symName is used without being defined in file filename.

Could not find file 'filename'.
An input object or library file was specified which does not exist, or cannot be found in
the linker path.

Could not open map file 'filename' for writing.
Verify that if filename exists, it is not a read-only file.

Could not resolve section reference ‘symName’ in file 'filename'.
The symbol symName is an external reference. No input module defines this symbol.
If the symbol is defined in a library module, ensure that the library module is included
on the command line or in the linker script file using the FILES directive.

Could not resolve symbol 'symName' in file 'filename'.
The symbol symName is an external reference. No input module defines this symbol.
If the symbol is defined in a library module, ensure that the library module is included
on the command line or in the linker script file using the FILES directive.

Device not specified. Use '/p' option to specify a device
If the device is not specified, this error will be generated. For Windows OS, you specify
the device by /pdevice. For Linux or Mac OS, you specify the device by -pdevice.
device represents the device name without a “PIC” or “dsPIC” preface, as in 18F8722
instead of PIC18F8722.

Duplicate definition of memory 'memName'.
All CODEPAGE and DATABANK directives must have unique NAME attributes.

Duplicate definitions of SECTION 'secName'.
Each SECTION directive must have unique NAME attributes. Remove duplicate
definitions.

 1994-2013 Microchip Technology Inc.

DS33014L-page 287

Assembler/Linker/Librarian User’s Guide
File ‘filename’, section ‘secName’, performs a call to symbol ‘symName’
which is not in the lower half of a page.
For 12-bit devices, the program counter (PC), bit 8, is cleared in the CALL instruction
or any modify PCL instruction. Therefore, all subroutine calls or computed jumps are
limited to the first 256 locations of any program memory page (512 words long.)

Inconsistent length definitions of SHAREBANK 'memName'.
All SHAREBANK definitions which have the same NAME attribute must be of equal
length.

Internal Coff output file is corrupt.
The linker cannot write to the COFF file.

Memory 'memName' overlaps memory 'memName'.
All CODEPAGE blocks must specify unique memory ranges which do not overlap.
Similarly DATABANK and SHAREBANK blocks may not overlap.

Mixing extended and non-extended mode modules not allowed
The linker cannot link a mixture of extended mode modules and non-extended mode
modules. Extended and non-extended memory modes apply to PIC18 devices.
When using MPASM to create object file modules, extended memory mode is
enabled/disabled on the command line using the /y or -y option. In the IDE, select
File>Project Properties (MPLAB X IDE) or Project>Build Options, MPASM Assembly
tab (MPLAB IDE v8), and check/uncheck the option “Extended Mode”.
When using MPLAB C18 to create object file modules, extended memory mode is
enabled/disabled on the command line using the --extended option. In the IDE,
select File>Project Properties (MPLAB X IDE) or Project>Build Options, MPLAB C18
tab (MPLAB IDE v8), and check/uncheck the option “Extended Mode”.
When using linker scripts, those with the suffix _e apply to extended mode use.

MPASM's __CONFIG directive (found in 'bar.o') cannot be used with
either MPLAB C18's #pragma config directive or MPASM's CONFIG
directive (found in 'foo.o')
This error message is issued when MPASM assembler's __CONFIG directive is
specified in a .asm file (e.g., bar.asm) and MPLAB C18's #pragma config directive
is specified in a .c file (e.g., foo.c). Set configuration bits using either MPASM
assembler's __CONFIG directive or MPLAB C18's #pragma config directive.

Multiple map files declared: 'filename1', 'filename2'.
The -m  switch was specified more than once.

Multiple output files declared: 'filename1', 'filename2'.
The -o  switch was specified more than once.

Multiple STACK definitions.
A STACK directive occurs more than once in the linker script file or included linker script
files. Remove the multiple STACK directives.

No input object files specified.
No input object or library file was specified to the linker. Enter files to link.

DS33014L-page 288

 1994-2013 Microchip Technology Inc.

Errors, Warnings and Common Problems
Overlapping definitions of SHAREBANK 'memName'.
A SHAREBANK directive specifies a range of addresses that overlap a previous
definition. Overlaps are not permitted.

{PCL | TOSH | TOSU | TOSL} cannot be used as the destination of a
MOVFF or MOVSF instruction.
The MOVFF instruction has unpredictable results when its destination is the PCL,
TOSH, TOSU, or TOSL registers. MPLINK will not allow the destination of a MOVFF
instruction to be replaced with any of these addresses.

Processor types do not agree across all input files.
Each object module and library file specifies a processor type or a processor family. All
input modules processor types or families must match.

Section {absolute|access|overlay|share} types for 'secName' do not
match across input files.
A section with the name secName occurs in more than one input file. However, in some
files it is marked as either an absolute, access, overlay or shared section, and in some
it is not. Change the section's type in the source files and rebuild the object modules.

Section 'secName' can not fit the absolute section. Section 'secName'
start=0xHHHH, length=0xHHHH.
A section which has not been assigned to a memory in the linker script file can not be
allocated. Use the -m  switch to generate an error map file. The error map
will show the sections which were allocated prior to the error. More memory must be
made available by adding a CODEPAGE, SHAREBANK, or DATABANK directive, or
by removing the PROTECTED attribute, or the number of input sections must be
reduced.

Section 'romName' can not have a 'RAM' memory attribute specified in
the linker script file.
Use only the ROM attribute when defining the section in the linker script file.

Section 'secName' can not fit the section. Section 'secName'
length='0xHHHH'.
A section which has not been assigned to a memory in the linker script file can not be
allocated. Use the -m  switch to generate an error map file. The error map
will show the sections which were allocated prior to the error. More memory must be
made available by adding a CODEPAGE, SHAREBANK, or DATABANK directive, or
by removing the PROTECTED attribute, or the number of input sections must be
reduced.

Section 'secName' contains code and can not have a 'RAM' memory
attribute specified in the linker script file.
Use only the ROM attribute when defining the section in the linker script file.

Section 'secName' contains initialized data and can not have a 'ROM'
memory attribute specified in the linker script file.
Use only the RAM attribute when defining the section in the linker script file.

 1994-2013 Microchip Technology Inc.

DS33014L-page 289

Assembler/Linker/Librarian User’s Guide
Section 'secName' contains initialized rom data and can not have a
'RAM' memory attribute specified in the linker script file.
Use only the ROM attribute when defining the section in the linker script file.

Section 'secName' contains uninitialized data and can not have a 'ROM'
memory attribute specified in the linker script file.
Use only the RAM attribute when defining the section in the linker script file.

Section 'secName' has a memory 'memName' which can not fit the
absolute section. Section 'secName' start=0xHHHH, length=0xHHHH.
The memory which was assigned to the section in the linker script file either does not
have space to fit the section, or the section will overlap another section. Use the
-m  switch to generate an error map file. The error map will show the
sections which were allocated prior to the error.

Section 'secName' has a memory 'memName' which can not fit the
section. Section 'secName' length='0xHHHH'.
The memory which was assigned to the section in the linker script file either does not
have space to fit the section, or the section will overlap another section. Use the
-m  switch to generate an error map file. The error map will show the
sections which were allocated prior to the error.

Section 'secName' has a memory 'memName'' which is not defined in the
linker script file.
Add a CODEPAGE, DATABANK, or SHAREBANK directive for the undefined memory
to the linker script file.

Section 'secName' type is non-overlay and absolute but occurs in more
than one input file.
An absolute section with the name secName may only occur in a single input file.
Relocatable sections with the same name may occur in multiple input files. Either
remove the multiple absolute sections in the source files or use relocatable sections
instead.

Starting addresses for absolute overlay section ‘secName’ do not match
across all input files.
A section with the name secName occurs in more than one input file. However, its
absolute overlay starting address varies between files. Change the section's address
in the source files and rebuild the object modules.

Symbol 'symName' has multiple definitions.
A symbol may only be defined in a single input module.

Symbol 'symName' is not word-aligned. It cannot be used as the target of
a {branch | call or goto} instruction.
The target of a branch, call, or goto instruction was at an odd address, but the
instruction encoding cannot reference addresses that are not word-aligned.

DS33014L-page 290

 1994-2013 Microchip Technology Inc.

Errors, Warnings and Common Problems
symbol 'symName' out of range of relative branch instruction.
A relative branch instruction had symName as its target, but a 2’s compliment encoding
of the offset to symName wouldn't fit in the limited number of instruction bits used for
the target of a branch instruction.

The _CONFIG_DECL macro can only be specified in one module. Found
in 'foo.o' previously found in 'bar.o'
This error is issued when MPLAB C18's _CONFIG_DECL macro is specified in two
separate .c files (e.g., foo.c and bar.c). Set configuration bits by using the
_CONFIG_DECL macro in only one .c file.

The _CONFIG_DECL macro (found in 'foo.o') cannot be used with
MPASM's __CONFIG directive (found in 'bar.o')
This error is issued when MPLAB C18's _CONFIG_DECL macro is used in a .c file
(e.g., foo.c) and MPASM assembler's __CONFIG directive is used in a .asm file (e.g.,
bar.asm). Set configuration bits using either the _CONFIG_DECL macro from MPLAB
C18 or the __CONFIG directive in MPASM assembler.

The _CONFIG_DECL macro (found in 'foo.o') cannot be used with either
MPLAB C18's #pragma config directive or MPASM's CONFIG directive
(found in 'bar.o')
This error is issued when MPLAB C18's _CONFIG_DECL macro is used in a .c file
(e.g., foo.c) with either MPLAB C18's #pragma config directive in a second .c file
(e.g., bar.c) or MPASM assembler's __CONFIG directive in a .asm file (e.g.,
bar.asm). Set configuration bits by using only one of _CONFIG_DECL, #pragma
config, or __CONFIG directive.

TRIS argument is out of range '0xHHHH' not between '0xHHHH' and
'0xHHHH'.
Check the device data sheet to determine acceptable hex values for the TRIS register
you are using.

Undefined CODEPAGE 'memName' for SECTION 'secName'.
A SECTION directive with a ROM attribute refers to a memory block which has not
been defined. Add a CODEPAGE directive to the linker script file for the undefined
memory block.

Undefined DATABANK/SHAREBANK 'memName' for SECTION
'secName'.
A SECTION directive with a RAM attribute refers to a memory block that has not been
defined. Add a DATABANK or SHAREBANK directive to the linker script file for the
undefined memory block.

Undefined DATABANK/SHAREBANK 'memName' for STACK.
No input object files specified. At least one object module must be specified either on
the command line or in the linker script file using the FILES directive.

Unknown section type for 'secName'.
The section type for ‘secName’ needs to be defined.

 1994-2013 Microchip Technology Inc.

DS33014L-page 291

Assembler/Linker/Librarian User’s Guide
Unknown section type for 'secName' in file 'filename'.
An input object or library module is not of the proper file type or it may be corrupted.

Unsupported processor type in file ‘filename’.
A processor was specified that is not currently supported by the linker. See the Readme
file for a list of supported devices.

Unsupported relocation type.
A relocation type was specified that is not currently supported by the linker.

14.4

LINKER WARNINGS
MPLINK linker warnings are listed alphabetically below:

Fill pattern for memory 'memName' doesn't divide evenly into unused
section locations. Last value was truncated.
If a fill pattern is specified for a ROM section, but the free space in that section isn't
evenly divisible by the fill pattern size, this warning will be issued to warn of incomplete
patterns.

'/a' command line option ignored with '/x'
/x or -x prevents the generation of a .hex file. Therefore, specifying the format of hex
output file with /a or -a is irrelevant.

'/n' command line option ignored with '/w'
/w or -w prevents the generation of a .lst file. Therefore, specifying the number of lines
per listing page with /n or -n is irrelevant.

DS33014L-page 292

 1994-2013 Microchip Technology Inc.

Errors, Warnings and Common Problems
14.5

COFF FILE ERRORS
All the COFF errors listed below indicate an internal error in the file's contents. Please
contact Microchip support if any of these errors are generated.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•

Coff file 'filename' could not read file header.
Coff file 'filename' could not read line numbers.
Coff file 'filename' could not read optional file header.
Coff file 'filename' could not read raw data.
Coff file 'filename' could not read relocation info.
Coff file 'filename' could not read section header.
Coff file 'filename' could not read string table.
Coff file 'filename' could not read string table length.
Coff file 'filename' could not read symbol table.
Coff file 'filename' could not write file header.
Coff file 'filename' could not write lineinfo.
Coff file 'filename' could not write optional file header.
Coff file 'filename' could not write raw data.
Coff file 'filename' could not write reloc.
Coff file 'filename' could not write section header.
Coff file 'filename' could not write string.
Coff file 'filename' could not write string table length.
Coff file 'filename' could not write symbol.
Coff file 'filename', cScnHdr.size() != cScnNum.size().
Coff file 'filename' does not appear to be a valid COFF file.
Coff file 'filename' has relocation entries but an empty symbol table.
Coff file 'filename' missing optional file header.
Coff file 'filename' section['xx'] has an invalid s_offset.
Coff file 'filename', section 'secName' line['xx'] has an invalid l_fcnndx.
Coff file 'filename', section 'secName' line['xx'] has an invalid l_srcndx.
Coff file 'filename', section 'secName' reloc['xx'] has an invalid r_symndx.
Coff file 'filename' symbol['xx'] has an invalid n_offset.
Coff file 'filename' symbol['xx'] has an invalid n_scnum.
Coff file 'filename', symbol['xx'] has an invalid index.
Could not find section name 'secName' in string table.
Could not find symbol name 'symName' in string table.
Could not open Coff file 'filename' for reading.
Could not open Coff file 'filename' for writing.
Could not read archive magic string in library file 'filename'.
Unable to find aux_file name in string table.
Unable to find section name in string table.
Unable to find symbol name in string table.

 1994-2013 Microchip Technology Inc.

DS33014L-page 293

Assembler/Linker/Librarian User’s Guide
14.6

OTHER ERRORS, WARNINGS AND MESSAGES
If you are using the linker with any of the utilities, i.e., MPLIB librarian or you have not
used the linker options /w or /x (Windows OS) or -w or -x (Linux or Mac OS), then
you may need to look in the utility troubleshooting sections for your error.
• MPLIB Librarian - Chapter 17. “Errors”
• MP2COD and/or MP2HEX - Chapter 19. “Errors and Warnings”

14.7

COMMON PROBLEMS
Although I set up listing file properties with MPASM assembler directives, none
of these properties is appearing in my listing file.
Although MPASM assembler is often used with MPLINK object linker, MPASM
assembler directives are not supported in MPLINK linker scripts. See
Section 10.3 “Command Line Interface” for control of listing and hex file output.
How do I split up linear memory in the linker script file?
Currently the only name linear memory can be is linear0 and nothing else due a
limitation in the linker. This prevents your from splitting the linear memory region
because names other than linear0 cannot be used.

DS33014L-page 294

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Part 3 – MPLIB Object Librarian
Chapter 15. MPLIB Librarian Overview .................................................................... 297
Chapter 16. Librarian Interfaces ............................................................................... 299
Chapter 17. Errors...................................................................................................... 301

 1994-2013 Microchip Technology Inc.

DS33014L-page 295

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 296

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 15. MPLIB Librarian Overview
15.1

INTRODUCTION
An overview of the MPLIB object librarian and its capabilities is presented.
Topics covered in this chapter:
•
•
•
•
•

15.2

What is MPLIB Librarian
How MPLIB Librarian Works
How MPLIB Librarian Helps You
Librarian Operation
Librarian Input/Output Files

WHAT IS MPLIB LIBRARIAN
MPLIB object librarian (the librarian) combines object modules generated by the
MPASM assembler or the MPLAB C18 C compiler into a single library file. This file may
then be inputted into the MPLINK object linker.

15.3

HOW MPLIB LIBRARIAN WORKS
A librarian manages the creation and modification of library files. A library file is simply
a collection of object modules that are stored in a single file. There are several reasons
for creating library files:
• Libraries make linking easier. Since library files can contain many object files, the
name of a library file can be used instead of the names of many separate object
files when linking.
• Libraries help keep code small. Since a linker only uses the required object files
contained in a library, not all object files which are contained in the library
necessarily wind up in the linker's output module.
• Libraries make projects more maintainable. If a library is included in a project, the
addition or removal of calls to that library will not require a change to the link
process.
• Libraries help to convey the purpose of a group of object modules. Since libraries
can group together several related object modules, the purpose of a library file is
usually more understandable than the purpose of its individual object modules.
For example, the purpose of a file named math.lib is more apparent than the
purpose of power.o, ceiling.o, and floor.o.

 1994-2013 Microchip Technology Inc.

DS33014L-page 297

Assembler/Linker/Librarian User’s Guide
15.4

HOW MPLIB LIBRARIAN HELPS YOU
The MPLIB librarian can help you in the following ways:
• The librarian makes linking easier because single libraries can be included
instead of many smaller files.
• The librarian helps keep code maintainable by grouping related modules together.
• The librarian commands allow libraries to be created and modules to be added,
listed, replaced, deleted, or extracted.

15.5

LIBRARIAN OPERATION
The librarian combines multiple input object modules, generated by the MPASM
assembler or MPLAB C18 C compilers, into a single output library (.lib) file. Library
files are used in conjunction with the MPLINK linker to produce executable code.
FIGURE 15-1:

MPLIB LIBRARIAN OPERATION
avg.o

mult.o

add.o

object
files

MPLIB librarian

math.lib

15.6

library file

LIBRARIAN INPUT/OUTPUT FILES
The MPLIB librarian combines multiple object files into one library (.lib) file.

Input Files
Object File (.o)

Relocatable code produced from source files.

Output Files
Library File (.lib)

15.6.1

A collection of object files grouped together for
convenience.

Object File (.o)

Object files are the relocatable code produced from source files. The MPLIB librarian
combines several object files into a single library file.

15.6.2

Library File (.lib)

A library file may be created from object files by the MPLIB librarian or may be an
existing standard library.

DS33014L-page 298

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 16. Librarian Interfaces
16.1

INTRODUCTION
How to use MPLIB librarian is discussed here. For information on how librarian output
can be used with the MPASM assembler and the MPLINK linker, see the
documentation for these tools.
Topics covered in this chapter:
•
•
•
•

16.2

MPLAB X IDE Interface
MPLAB IDE v8 Interface
Command Line Options
Command Line Examples and Tips

MPLAB X IDE INTERFACE
The MPLIB librarian may be used to create library files to be used in an MPLAB X IDE
project.

16.3

MPLAB IDE V8 INTERFACE
The MPLIB librarian may be used with MPLAB IDE to create a library file from project
object files instead of an executable (hex) file.
With your project open in MPLAB IDE, select Project>Build Options>Project. In the
Build Options dialog, click on the MPASM/C17/C18 Suite tab. Click the radio button
next to “Build library target (invoke MPLIB)”. Then click OK. Now when you build your
project, you will be building a library file.

 1994-2013 Microchip Technology Inc.

DS33014L-page 299

Assembler/Linker/Librarian User’s Guide
16.4

COMMAND LINE OPTIONS
MPLIB librarian is invoked with the following syntax:
Windows OS: mplib [/q] /{ctdrx} LIBRARY [MEMBER...]
Linux or Mac OS: mplib [-q] -{ctdrx} LIBRARY [MEMBER...]

Options
Option
(/ or -)

16.5

Description

Detail

c

Create library

creates a new LIBRARY with the listed MEMBER(s)

d

Delete member

deletes MEMBER(s) from the LIBRARY; if no MEMBER is
specified the LIBRARY is not altered

q

Quiet mode

no output is displayed

r

Add/replace member

if MEMBER(s) exist in the LIBRARY, then they are
replaced, otherwise MEMBER is appended to the end of
the LIBRARY

t

List members

prints a table showing the names of the members in the
LIBRARY

x

Extract member

if MEMBER(s) exist in the LIBRARY, then they are
extracted. If no MEMBER is specified, all members will be
extracted

COMMAND LINE EXAMPLES AND TIPS
Example of Use - Windows OS
Suppose you wanted to create a library named dsp.lib from three object modules
named fft.o, fir.o, and iir.o. The following command line would produce the
desired results:
mplib /c dsp.lib fft.o fir.o iir.o

To display the names of the object modules contained in a library file named dsp.lib,
the following command line would be appropriate:
mplib /t dsp.lib

Tips
MPLIB librarian creates library files that may contain only a single external definition for
any symbol. Therefore, if two object modules define the same external symbol, the
librarian will generate an error if both object modules are added to the same library file.
To minimize the code and data space which results from linking with a library file, the
library's member object modules should be as small as possible. Creating object
modules that contain only a single function can significantly reduce code space.

DS33014L-page 300

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 17. Errors
17.1

INTRODUCTION
MPLIB librarian detects the following sources of error and reports them.
Topics covered in this chapter:
• Librarian Parse Errors
• Library File Errors
• COFF File Errors

17.2

LIBRARIAN PARSE ERRORS
MPLIB librarian parse errors are listed alphabetically below:

Invalid Object Filename
All object filenames must end with '.o'.

Invalid Switch
An unsupported switch was specified. For a list of supported switches, refer to
command line options.

Library Filename is Required
All commands require a library filename. All library filenames must end with '.lib'.

 1994-2013 Microchip Technology Inc.

DS33014L-page 301

Assembler/Linker/Librarian User’s Guide
17.3

LIBRARY FILE ERRORS
Library file processing errors are listed alphabetically below:

Could not build member 'memberName' in library file 'filename'.
The file is not a valid library file or it is corrupted.

Could not open library file 'filename' for reading.
Verify that filename exists and can be read.

Could not open library file 'filename' for writing.
Verify that if filename exists, it is not read-only.

Could not write archive magic string in library file 'filename'.
The file may be corrupted.

Could not write member header for 'memberName' in library file
'filename'.
The file may be corrupted.

File 'filename' is not a valid library file.
Library files must end with .lib.

Library file 'filename' has a missing member object file.
The file not a valid object file or it may be corrupted.

'memberName' is not a member of library 'filename'.
memberName can not be extracted or deleted from a library unless it is a member of
the library.

Symbol 'symName' has multiple external definitions.
A symbol may only be defined once in a library file.

17.4

COFF FILE ERRORS
For a list of COFF File Errors, see MPLINK linker Section 14.5 “COFF File Errors”.

DS33014L-page 302

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Part 4 – Utilities
Chapter 18. Utilities Overview and Usage ............................................................... 305
Chapter 19. Errors and Warnings ............................................................................. 307

 1994-2013 Microchip Technology Inc.

DS33014L-page 303

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 304

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 18. Utilities Overview and Usage
18.1

INTRODUCTION
An overview of the 8-bit utilities and their capabilities are presented.
Topics covered in this chapter:
•
•
•
•

18.2

What are Utilities
Utilities Operation
mp2hex.exe Utility
mp2cod.exe Utility

WHAT ARE UTILITIES
Utilities are tools available for use with the assembler and/or linker. The MPLIB object
librarian is a utility that was discussed in the previous sections.
TABLE 18-1:

AVAILABLE UTILITIES

Utility

18.3

Description

mplib.exe

Creates, modifies and extracts files from libraries. See Part 3
– “MPLIB Object Librarian” for more information.

mp2hex.exe

Generates a Hex file from a COF file.

mp2cod.exe

Generates a COD and list file from a COF file.

UTILITIES OPERATION
The utilities MP2HEX and MP2COD work with the MPLINK object linker to generate
executable code (.hex) or a linker listing file (.lst) from the linker COF file. The Hex
file is used by simulators, emulators, debuggers and programmers.
FIGURE 18-1:

UTILITIES OPERATION
MPLINK linker

LINKER
output file

prog.cof

 1994-2013 Microchip Technology Inc.

MP2HEX

MP2COD

prog.hex

prog.lst

Utility
output files

DS33014L-page 305

Assembler/Linker/Librarian User’s Guide
18.4

MP2HEX.EXE UTILITY
Use this utility to take the MPLINK linker output COF file and create a Hex file. A Hex
file contains no debug information but may be programmed directly into a device.
The MPLINK linker /x or -x option will result in the linker not using this utility.

18.5

MP2COD.EXE UTILITY
Use this utility to take the MPLINK linker output COF file and create a COD file and a
list file. A COD file is a legacy debug file that is no longer used. A list file generated by
this utility is specific to the linker (see Section 9.7.6 “Listing File (.lst)”.)
The MPLINK linker /w or -w option will result in the linker not using this utility.

DS33014L-page 306

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Chapter 19. Errors and Warnings
19.1

INTRODUCTION
Error messages and warning messages are produced by the 8-bit utilities. These
messages always appear in the listing file directly above each line in which the error
occurred.
•
•
•
•

19.2

Hex File Errors
COFF To COD Conversion Errors
COFF To COD Converter Warnings
COD File Errors

HEX FILE ERRORS
Selected hex format does not support byte addresses above 64kb; use
INHX32 format!
Your code addresses more than 64 Kbytes of program memory, but your selected hex
format cannot support this. Switch to INHX32 format.

Could not open hex file ‘filename’ for writing.
The hex file was never created due to other errors, or an existing hex file is
write-protected.

19.3

COFF TO COD CONVERSION ERRORS
Source file ‘filename’ name exceeds file format maximum of 63
characters.
The COD file name, including the path, has a 63-character limit.

Coff file 'filename' must contain at least one 'code' or 'romdata' section.
In order to convert a COFF file to a COD file, the COFF file must have either a code or
a romdata section.

Could not open list file 'filename' for writing.
Verify that if filename exists and that it is not a read-only file.

19.4

COFF TO COD CONVERTER WARNINGS
Could not open source file 'filename'. This file will not be present in the
list file.
The referenced source file could not be opened. This can happen if an input
object/library module was built on a machine with a different directory structure. If
source level debugging for the file is desired, rebuild the object or library on the current
machine.

 1994-2013 Microchip Technology Inc.

DS33014L-page 307

Assembler/Linker/Librarian User’s Guide
19.5

COD FILE ERRORS
All the COD file errors listed below indicate an internal error in the file's contents.
Please contact Microchip support if any of these errors are generated.
•
•
•
•
•
•
•
•
•
•
•
•
•
•

DS33014L-page 308

Cod file 'filename' does not have a proper debug message table.
Cod file 'filename' does not have a proper Index.
Cod file 'filename' does not have a proper line info table.
Cod file 'filename' does not have a proper local vars table.
Cod file 'filename' does not have a proper long symbol table.
Cod file 'filename' does not have a proper memory map table.
Cod file 'filename' does not have a proper name table.
Cod file 'filename' does not have a proper symbol table.
Cod file 'filename' does not have a properly formed first directory.
Cod file 'filename' does not have a properly formed linked directory.
Could not open Cod file ‘filename’ for reading.
Could not open Cod file ‘filename’ for writing.
Could not write ‘blockname’ block in Cod file ‘filename’.
Could not write directory in Cod file ‘filename’.

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Part 5 – Appendices
Appendix A. Instruction Sets .................................................................................... 311
Appendix B. Useful Tables ........................................................................................ 329

 1994-2013 Microchip Technology Inc.

DS33014L-page 309

Assembler/Linker/Librarian User’s Guide
NOTES:

DS33014L-page 310

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Appendix A. Instruction Sets
A.1

INTRODUCTION
PIC1X MCU instruction sets are used in developing applications with MPASM
assembler, MPLINK object linker and MPLIB object librarian.
Instructions listed here are grouped either by instruction width or device number.
Instruction
Width

Devices Supported

12 Bit

PIC10F2XX, PIC12C5XX, PIC12CE5XX, PIC16X5X, PIC16C505

14 Bit

PIC12C67X, PIC12CE67X, PIC12F629/675, PIC16X

16 Bit

PIC18X

Topics covered are:
• Key to 12/14-Bit Instruction Width Instruction Sets
- 12-Bit Instruction Width Instruction Set
- 14-Bit Instruction Width Instruction Set
- 14-Bit Instruction Width Extended Instruction Set
- 12-Bit/14-Bit Instruction Width Pseudo-Instructions
• Key to PIC18 Device Instruction Set
- PIC18 Device Instruction Set
- PIC18 Device Extended Instruction Set

A.2

KEY TO 12/14-BIT INSTRUCTION WIDTH INSTRUCTION SETS
Use this key to determine the meaning of abbreviations in the 12- and 14-bit instruction width
instruction sets tables.
Field

Description

Register Files
dest

Destination either the WREG register or the specified register file location. See d.

f

Register file address (5-bit, 7-bit or 8-bit).

n

FSR or INDF number (0 or 1).

p

Peripheral register file address (5-bit).

r

Port for TRIS.

x

Don’t care (‘0’ or ‘1’).
The assembler will generate code with x = 0. It is the recommended form of use for
compatibility with all Microchip software tools.

Literals
k

Literal field, constant data or label.
k
4-bit.
kk 8-bit.
kkk 12-bit.

mm

Pre-post increment-decrement mode selection.

 1994-2013 Microchip Technology Inc.

DS33014L-page 311

Assembler/Linker/Librarian User’s Guide
Field

Description

Bits
b

Bit address within an 8-bit file register (0 to 7).

d

Destination select bit.
d = 0: store result in WREG
d = 1: store result in file register f (default)

i

Table pointer control.
i = 0: do not change.
i = 1: increment after instruction execution.

s

Destination select bit.
s = 0: store result in file register f and WREG
s = 1: store result in file register f (default)

t

Table byte select.
t = 0: perform operation on lower byte.
t = 1: perform operation on upper byte.

' '

Bit values, as opposed to Hex value.

Named Registers
BSR

Bank Select Register. Used to select the current RAM bank.

OPTION

OPTION Register.

PCL

Program Counter Low Byte.

PCH

Program Counter High Byte.

PCLATH

Program Counter High Byte Latch.

PCLATU

Program Counter Upper Byte Latch.

PRODH

Product of Multiply High Byte.

PRODL

Product of Multiply Low Byte.

TBLATH

Table Latch (TBLAT) High Byte.

TBLATL

Table Latch (TBLAT) Low Byte.

TBLPTR

16-bit Table Pointer (TBLPTRH:TBLPTRL). Points to a Program Memory location.

WREG

Working register (accumulator).

Named Bits
C, DC, Z, OV, N

ALU Status bits: Carry, Digit Carry, Zero, Overflow, Negative.

TO

Time-out bit.

PD

Power-down bit.

GIE

Global Interrupt Enable bit(s).

Named Device Features
PC

Program Counter.

TOS

Top-of-Stack.

WDT

Watchdog Timer.

Misc. Descriptors
(

)

Contents.

, 

Assigned to.

< >

Register bit field.

DS33014L-page 312

 1994-2013 Microchip Technology Inc.

Instruction Sets
A.3

12-BIT INSTRUCTION WIDTH INSTRUCTION SET
Microchip’s baseline 8-bit microcontroller family uses a 12-bit wide instruction set. All
instructions execute in a single instruction cycle unless otherwise noted. Any unused
opcode is executed as a NOP.
The instruction set is grouped into the following categories: byte-oriented file register
operations, bit-oriented file register operations, and core literal and control operations.
Instructions. Additionally, instructions that apply to both 12-bit and 14-bit devices are
shown in Section A.6 “12-Bit/14-Bit Instruction Width Pseudo-Instructions”.
Instruction opcode is show in hex by making certain assumptions, either listed in the
key or as a footnote. For more information on the opcode bit values for each instruction,
as well as the number of cycles per instruction, status bits affected and complete
instruction details, see the relevant device data sheet.

TABLE A-1:
Hex
1Ef*

12-BIT BYTE-ORIENTED FILE REGISTER OPERATIONS
Mnemonic

ADDWF

f,d

Description

Function
WREG + f  dest

Add W and f

16f*

ANDWF

f,d

AND W and f

WREG .AND. f  dest

06f

CLRF

f

Clear f

0f

040

CLRW

26f*

COMF

0Ef*
2Ef*
2Af*
3Ef*

Clear W

0  WREG

f,d

Complement f

.NOT. f  dest

DECF

f,d

Decrement f

f - 1  dest

DECFSZ

f,d

Decrement f, skip if zero

f - 1  dest, skip if zero

INCF

f,d

Increment f

f + 1  dest

INCFSZ

f,d

Increment f, skip if zero

f + 1  dest, skip if zero

12f*

IORWF

f,d

Inclusive OR W and f

WREG .OR. f  dest

22f*

MOVF

f,d

Move f

f  dest

02f

MOVWF

f

Move W to f

WREG  f

000

NOP

36f*

RLF

No operation
f,d

Rotate left f

register f
C

32f*

RRF

f,d

7......0

Rotate right f

register f
C

7......0

0Af*

SUBWF

f,d

Subtract W from f

f - WREG  dest

3Af*

SWAPF

f,d

Swap halves f

f(0:3)  f(4:7)  dest

1Af*

XORWF

f,d

Exclusive OR W and f

WREG .XOR. f  dest

* Assuming default bit value for d.

TABLE A-2:
Hex

12-BIT BIT-ORIENTED FILE REGISTER OPERATIONS
Mnemonic

Description

Function

4bf

BCF

f,b

Bit clear f

0  f(b)

5bf

BSF

f,b

Bit set f

1  f(b)

6bf

BTFSC

f,b

Bit test, skip if clear

skip if f(b) = 0

7bf

BTFSS

f,b

Bit test, skip if set

skip if f(b) = 1

 1994-2013 Microchip Technology Inc.

DS33014L-page 313

Assembler/Linker/Librarian User’s Guide
TABLE A-3:
Hex

12-BIT LITERAL AND CONTROL OPERATIONS
Mnemonic

Description

Function

Ekk

ANDLW

kk

AND literal and W

kk .AND. WREG  WREG

9kk

CALL

kk

Call subroutine

PC + 1  TOS, kk  PC

004

CLRWDT

Clear watchdog timer

0  WDT (and Prescaler if assigned)

Akk

GOTO

kk

Goto address (k is nine bits)

kk  PC(9 bits)

Dkk

IORLW

kk

Incl. OR literal and W

kk .OR. WREG  WREG

kk

Ckk

MOVLW

002

OPTION

8kk

RETLW

003

SLEEP

00r

TRIS

Fkk

XORLW

DS33014L-page 314

Move Literal to W

kk  WREG

Load OPTION Register

WREG  OPTION Register

Return with literal in W

kk  WREG, TOS  PC

Go into Standby Mode

0  WDT, stop oscillator

r

Tristate port r

WREG  I/O control reg r

kk

Exclusive OR literal and W

kk .XOR. WREG  WREG

kk

 1994-2013 Microchip Technology Inc.

Instruction Sets
A.4

14-BIT INSTRUCTION WIDTH INSTRUCTION SET
Microchip’s midrange 8-bit microcontroller family uses a 14-bit wide instruction set.
This instruction set consists of 36 instructions, each a single 14-bit wide word. Most
instructions operate on a file register, f, and the working register, WREG (accumulator).
The result can be directed either to the file register or the WREG register or to both in
the case of some instructions. A few instructions operate solely on a file register (BSF,
for example).
The instruction set is grouped into the following categories: byte-oriented file register
operations, bit-oriented file register operations, and core literal and control operations.
Additionally, instructions that apply to both 12-bit and 14-bit devices are shown in
Section A.6 “12-Bit/14-Bit Instruction Width Pseudo-Instructions”.
Instruction opcode is show in hex by making certain assumptions, either listed in the
key or as a footnote. For more information on the opcode bit values for each instruction,
as well as the number of cycles per instruction, status bits affected and complete
instruction details, see the relevant device data sheet.

TABLE A-4:

14-BIT BYTE-ORIENTED FILE REGISTER OPERATIONS

Hex
07df

Mnemonic
ADDWF

Description

f,d

Add W and f

Function
W+fd

05df

ANDWF

f,d

AND W and f

W .AND. f  d

01'1'f

CLRF

f

Clear f

0f

01xx

CLRW

09df

COMF

03df
0Bdf
0Adf
0Fdf

Clear W

0W

f,d

Complement f

.NOT. f  d

DECF

f,d

Decrement f

f-1d

DECFSZ

f,d

Decrement f, skip if zero

f - 1  d, skip if 0

INCF

f,d

Increment f

f+1d

INCFSZ

f,d

Increment f, skip if zero

f + 1  d, skip if 0

04df

IORWF

f,d

Inclusive OR W and f

W .OR. f  d

08df

MOVF

f,d

Move f

fd

00'1'f

MOVWF

f

Move W to f

Wf

0000

NOP

0Ddf

RLF

No operation
f,d

Rotate left f

register f
C

0Cdf

RRF

f,d

7......0

Rotate right f

register f
C

7......0

02df

SUBWF

f,d

Subtract W from f

f-Wd

0Edf

SWAPF

f,d

Swap halves f

f(0:3)  f(4:7)  d

06df

XORWF

f,d

Exclusive OR W and f

W .XOR. f  d

TABLE A-5:

14-BIT BIT-ORIENTED FILE REGISTER OPERATIONS

Hex

Mnemonic

Description

Function

f,b

Bit clear f

0  f(b)

BSF

f,b

Bit set f

1  f(b)

BTFSC

f,b

Bit test, skip if clear

skip if f(b) = 0

BTFSS

f,b

Bit test, skip if set

skip if f(b) = 1

4bf

BCF

5bf
6bf
7bf

 1994-2013 Microchip Technology Inc.

DS33014L-page 315

Assembler/Linker/Librarian User’s Guide
TABLE A-6:

14-BIT LITERAL AND CONTROL OPERATIONS

Hex
3Ekk

Mnemonic
ADDLW

Description

kk

Add literal to W

Function
kk + WREG  WREG

39kk

ANDLW

kk

AND literal and W

kk .AND. WREG  WREG

2'0'kkk

CALL

kkk

Call subroutine

PC + 1  TOS, kk  PC

0064

CLRWDT

Clear watchdog timer

0  WDT (and Prescaler if assigned)

2'1'kkk

GOTO

kkk

Goto address (k is nine bits)

kk  PC(9 bits)

38kk

IORLW

kk

Incl. OR literal and W

kk .OR. WREG  WREG

30kk

MOVLW

kk

Move Literal to W

kk  WREG

0062

OPTION

Load OPTION register

WREG  OPTION Register

0009

RETFIE

Return from Interrupt

TOS  PC, 1  GIE

34kk

RETLW

0008

RETURN

0063

SLEEP

3Ckk

SUBLW

kk

Return with literal in W

kk  WREG, TOS  PC

Return from subroutine

TOS  PC

Go into Standby Mode

0  WDT, stop oscillator

kk

Subtract W from literal

kk - WREG  WREG

006r

TRIS

r

Tristate port r

WREG  I/O control reg r

3Akk

XORLW

kk

Exclusive OR literal and W

kk .XOR. WREG  WREG

DS33014L-page 316

 1994-2013 Microchip Technology Inc.

Instruction Sets
A.5

14-BIT INSTRUCTION WIDTH EXTENDED INSTRUCTION SET
Some of Microchip’s midrange 8-bit microcontroller family use a 14-bit wide extended
instruction set. (Consult your device data sheet to see if you device uses an extended
instruction set.) This instruction set consists of 41 instructions, each a single 14-bit wide
word. Most instructions operate on a file register, f, and the working register, WREG
(accumulator). The result can be directed either to the file register or the WREG register
or to both in the case of some instructions. A few instructions operate solely on a file
register (BSF, for example).
The instruction set is grouped into the following categories: byte-oriented file register
operations, byte-oriented skip operations, bit-oriented file register operations,
bit-oriented skip operations, core literal operations, core control operations, core
inherent operations and C-compiler optimized operations. Additionally, instructions that
apply to both 12-bit and 14-bit devices are shown in Section A.6 “12-Bit/14-Bit
Instruction Width Pseudo-Instructions”.
Instruction opcode is show in hex by making certain assumptions, either listed in the
key or as a footnote. For more information on the opcode bit values for each instruction,
as well as the number of cycles per instruction, status bits affected and complete
instruction details, see the relevant device data sheet.

TABLE A-7:

14-BIT BYTE-ORIENTED FILE REGISTER OPERATIONS

Hex
07df

Mnemonic
ADDWF

f,d

Description
Add W and f

Function
W+fd

3Ddf

ADDWFC*

f,d

Add with Carry W and f

W+f+Cd

05df

ANDWF

f,d

AND W with f

W .AND. f  d

37df

ASRF*

f,d

Arithmetic Right Shift

register f
C

msb
35df

LSLF*

f,d

Logical Left Shift

register f
C

36df

LSRF*

f,d

7......0

Logical Right Shift

register f
7......0

0
Clear f

0f

Clear W

0W

Complement f

.NOT. f  d

f,d

Decrement f

f-1d

f,d

Increment f

f+1d

IORWF

f,d

Inclusive OR W with f

W .OR. f  d

MOVF

f,d

Move f

fd

00'1'f

MOVWF

f

Move W to f

Wf

0Ddf

RLF

f,d

Rotate left f

01'1'f

CLRF

f

01xx

CLRW

09df

COMF

f,d

03df

DECF

0Adf

INCF

04df
08df

RRF

f,d

Rotate right f

7......0
register f

C

 1994-2013 Microchip Technology Inc.

C

register f
C

0Cdf

0

7......0

DS33014L-page 317

Assembler/Linker/Librarian User’s Guide
TABLE A-7:

14-BIT BYTE-ORIENTED FILE REGISTER OPERATIONS (CONTINUED)

Hex
02df

Mnemonic
SUBWF

f,d

Description

Function

Subtract W from f

f-Wd

3Bdf

SUBWFB*

f,d

Subtract with Borrow W from f

f-W-Bd

0Edf

SWAPF

f,d

Swap halves f

f(0:3)  f(4:7)  d

06df

XORWF

f,d

Exclusive OR W and f

W .XOR. f  d

* Operation in 14-bit extended instruction set but not 14-bit instruction set.

TABLE A-8:

14-BIT BYTE-ORIENTED SKIP OPERATIONS

Hex

Mnemonic

Description

Function

0Bdf

DECFSZ

f,d

Decrement f, skip if zero

f - 1  d, skip if 0

0Fdf

INCFSZ

f,d

Increment f, skip if zero

f + 1  d, skip if 0

TABLE A-9:

14-BIT BIT-ORIENTED FILE REGISTER OPERATIONS

Hex

Mnemonic

Description

Function

4bf

BCF

f,b

Bit clear f

0  f(b)

5bf

BSF

f,b

Bit set f

1  f(b)

TABLE A-10:

14-BIT BIT-ORIENTED SKIP OPERATIONS

Hex

Mnemonic

Description

Function

6bf

BTFSC

f,b

Bit test, skip if clear

skip if f(b) = 0

7bf

BTFSS

f,b

Bit test, skip if set

skip if f(b) = 1

TABLE A-11:

14-BIT LITERAL OPERATIONS

Hex

Mnemonic

Description

Function

3Ekk

ADDLW

kk

Add literal to W

kk + WREG  WREG

39kk

ANDLW

kk

AND literal and W

kk .AND. WREG  WREG

38kk

IORLW

kk

Incl. OR literal and W

kk .OR. WREG  WREG

002k

MOVLB*

k

Move literal to BSR

k BSR

31'1'kk

MOVLP*

kk

Move literal to PCLATH

kk PCLATH

30kk

MOVLW

kk

Move Literal to W

kk  WREG

3Ckk

SUBLW

kk

Subtract W from literal

kk - WREG  WREG

3Akk

XORLW

kk

Exclusive OR literal and W

kk .XOR. WREG  WREG

* Operation in 14-bit extended instruction set but not 14-bit instruction set.

TABLE A-12:

14-BIT CONTROL OPERATIONS

Hex
32kk

Mnemonic
BRA*

000B

BRW*

2'0'kkk

CALL

000A

CALLW*

2'1'kkk

GOTO

0009

RETFIE

34kk

RETLW

0008

RETURN

kk
kkk
kkk
kk

Description
Relative branch

Function
PC + kk  PC

Relative branch with W

PC + W  PC

Call subroutine

PC + 1  TOS, kkk  PC

Call subroutine with W

PC + 1  TOS, W  PC

Goto address (k is nine bits)

kk  PC(9 bits)

Return from Interrupt

TOS  PC, 1  GIE

Return with literal in W

kk  WREG, TOS  PC

Return from subroutine

TOS  PC

* Operation in 14-bit extended instruction set but not 14-bit instruction set.

DS33014L-page 318

 1994-2013 Microchip Technology Inc.

Instruction Sets
TABLE A-13:

14-BIT INHERENT OPERATIONS

Hex

Mnemonic

Description
Clear watchdog timer

Function
0  WDT (and Prescaler if assigned)

0064

CLRWDT

0000

NOP

No operation

0062

OPTION

Load OPTION register

0001

RESET*

Software device reset

TOS  PC

0063

SLEEP

Go into Standby Mode

0  WDT, stop oscillator

006r

TRIS

Tristate port r

WREG  I/O control reg r

r

WREG  OPTION Register

* Operation in 14-bit extended instruction set but not 14-bit instruction set.

TABLE A-14:
Hex

14-BIT C-COMPILER OPTIMIZED OPERATIONS
Mnemonic

Description

Function

31'0'nk

ADDFSR*

n, k

Add Literal to FSRn

FSR(n) + k  FSR(n)

001'0'mn
001'0'nm
3F'0'nk

MOVIW*

mm n
n mm
k[n]

Move INDFn to W, with pre/post inc/dec
Move INDFn to W, with pre/post inc/dec
Move INDFn to W, Indexed Indirect.

INDFn  W

001'1'mn
001'1'nm
3F'1'nk

MOVWI*

mm n
n mm
k[n]

Move W to INDFn, with pre/post inc/dec
Move W to INDFn, with pre/post inc/dec
Move W to INDFn, Indexed Indirect.

W  INDFn

* Operation in 14-bit extended instruction set but not 14-bit instruction set.

 1994-2013 Microchip Technology Inc.

DS33014L-page 319

Assembler/Linker/Librarian User’s Guide
A.6

12-BIT/14-BIT INSTRUCTION WIDTH PSEUDO-INSTRUCTIONS
The following pseudo-instructions are applicable to both the 12-bit and 14-bit
instruction word devices. These pseudo-instructions are alternative mnemonics for
standard PIC1X instructions or are macros that generate one or more PIC1X
instructions. Use of these pseudo-instructions is not recommended for new designs.
These are documented mainly for historical purposes.

TABLE A-15:

12-BIT/14-BIT SPECIAL INSTRUCTION MNEMONICS

Mnemonic

Equivalent
Operation(s)

Description

Status

ADDCF

f,d

Add Carry to File

BTFSC
INCF

3,0
f,d

Z

ADDDCF

f,d

Add Digit Carry to File

BTFSC
INCF

3,1
f,d

Z

B

k

Branch

GOTO

k

-

BC

k

Branch on Carry

BTFSC
GOTO

3,0
k

-

BDC

k

Branch on Digit Carry

BTFSC
GOTO

3,1
k

-

BNC

k

Branch on No Carry

BTFSS
GOTO

3,0
k

-

BNDC

k

Branch on No Digit Carry

BTFSS
GOTO

3,1
k

-

BNZ

k

Branch on No Zero

BTFSS
GOTO

3,2
k

-

BZ

k

Branch on Zero

BTFSC
GOTO

3,2
k

-

CLRC

Clear Carry

BCF

3,0

-

CLRDC

Clear Digit Carry

BCF

3,1

-

Clear Zero

BCF

3,2

LCALL

k

Long Call

BCF/BSF
BCF/BSF
CALL

0x0A,3
0x0A,4
k

LGOTO

k

Long GOTO

BCF/BSF
BCF/BSF
GOTO

0x0A,3
0x0A,4
k

MOVFW

f

Move File to W

MOVF

f,0

Z

NEGF

f,d

Negate File

COMF
INCF

f,1
f,d

Z

SETC

Set Carry

BSF

3,0

-

SETDC

Set Digit Carry

BSF

3,1

-

CLRZ

SETZ

Set Zero

BSF

3,2

-

SKPC

Skip on Carry

BTFSS

3,0

-

SKPDC

Skip on Digit Carry

BTFSS

3,1

-

SKPNC

Skip on No Carry

BTFSC

3,0

-

SKPNDC

Skip on No Digit Carry

BTFSC

3,1

-

SKPNZ

Skip on Non Zero

BTFSC

3,2

-

Skip on Zero

BTFSS

3,2

-

Subtract Carry from File

BTFSC
DECF

3,0
f,d

Z

SKPZ
SUBCF

f,d

DS33014L-page 320

 1994-2013 Microchip Technology Inc.

Instruction Sets
TABLE A-15:

12-BIT/14-BIT SPECIAL INSTRUCTION MNEMONICS (CONTINUED)

Mnemonic

Equivalent
Operation(s)

Description

Status

SUBDCF

f,d

Subtract Digit Carry from File

BTFSC
DECF

3,1
f,d

Z

TSTF

f

Test File

MOVF

f,1

Z

 1994-2013 Microchip Technology Inc.

DS33014L-page 321

Assembler/Linker/Librarian User’s Guide
A.7

KEY TO PIC18 DEVICE INSTRUCTION SET
Use this key to determine the meaning of abbreviations in the PIC18 (16-bit instruction width)
instruction sets tables.
Field

Description

Register Files
dest

Destination either the WREG register or the specified register file location. See d.

f

Register file address.
f
8-bit (0x00 to 0xFF).
f' 12-bit (0x000 to 0xFFF). This is the source address.
f” 12-bit (0x000 to 0xFFF). This is the destination address.

r

0, 1 or 2 for FSR number.

x

Don’t care (‘0’ or ‘1’).
The assembler will generate code with x = 0. It is the recommended form of use for
compatibility with all Microchip software tools.

z

Indirect addressing offset.
z' 7-bit offset value for indirect addressing of register files (source).
z” 7-bit offset value for indirect addressing of register files (destination).

Literals
k

Literal field, constant data or label.
k
4-bit.
kk 8-bit.
kkk 12-bit.

Offsets, Increments/Decrements
n

*
*+
*+*

The relative address (2’s complement number) for relative branch instructions, or the direct
address for Call/Branch and Return instructions.
The mode of the TBLPTR register for the table read and table write instructions.
Only used with table read (TBLRD) and table write (TBLWT) instructions:
No Change to register
Post-Increment register
Post-Decrement register
Pre-Increment register

Bits
a

RAM access bit
a = 0: RAM location in Access RAM (BSR register is ignored)
a = 1: RAM bank is specified by BSR register (default)

b

Bit address within an 8-bit file register (0 to 7).

d

Destination select bit
d = 0: store result in WREG
d = 1: store result in file register f (default)

s

Fast Call/Return mode select bit
s = 0: do not update into/from shadow registers (default)
s = 1: certain registers loaded into/from shadow registers (Fast mode)

' '

Bit values, as opposed to Hex value.

Named Registers
BSR

Bank Select Register. Used to select the current RAM bank.

FSR

File Select Register.

PCL

Program Counter Low Byte.

PCH

Program Counter High Byte.

PCLATH

Program Counter High Byte Latch.

PCLATU

Program Counter Upper Byte Latch.

PRODH

Product of Multiply High Byte.

DS33014L-page 322

 1994-2013 Microchip Technology Inc.

Instruction Sets
Field

Description

PRODL

Product of Multiply Low Byte.

STATUS

Status Register

TABLAT

8-bit Table Latch.

TBLPTR

21-bit Table Pointer (points to a Program Memory location).

WREG

Working register (accumulator).

Named Bits
C, DC, Z, OV, N

ALU Status bits: Carry, Digit Carry, Zero, Overflow, Negative.

TO

Time-out bit.

PD

Power-down bit.

PEIE

Peripheral Interrupt Enable bit.

GIE, GIEL/H

Global Interrupt Enable bit(s).

Named Device Features
MCLR

Master clear device reset.

PC

Program Counter.

TOS

Top-of-Stack.

WDT

Watchdog Timer.

Misc. Descriptors
(

)

Contents.



Assigned to.

< >

Register bit field.

 1994-2013 Microchip Technology Inc.

DS33014L-page 323

Assembler/Linker/Librarian User’s Guide
A.8

PIC18 DEVICE INSTRUCTION SET
Microchip's new high-performance 8-bit microcontroller family uses a 16-bit wide
instruction set. This instruction set consists of 76 instructions, each a single 16-bit wide
word (2 bytes). Most instructions operate on a file register, f, and the working register,
WREG (accumulator). The result can be directed either to the file register or the WREG
register or to both in the case of some instructions. A few instructions operate solely on
a file register (BSF, for example).
The instruction set is grouped into the following categories: byte-oriented file register
operations, bit-oriented file register operations, control operations, literal operations
and memory operations. Additionally, extended mode instructions are shown in
Section A.9 “PIC18 Device Extended Instruction Set”.
Instruction opcode is show in hex by making certain assumptions, either listed in the
key or as a footnote. For more information on the opcode bit values for each instruction,
as well as the number of cycles per instruction, status bits affected and complete
instruction details, see the relevant device data sheet.

TABLE A-16:
Hex

PIC18 BYTE-ORIENTED REGISTER OPERATIONS
Mnemonic

Description

Function
WREG+f dest

27f*

ADDWF

f,d,a

ADD WREG to f

23f*

ADDWFC

f,d,a

ADD WREG and Carry bit to f

WREG+f+C dest

17f*

ANDWF

f,d,a

AND WREG with f

WREG .AND. f dest

6Bf*

CLRF

f,a

Clear f

0 f

1Ff*

COMF

f,d,a

Complement f

.NOT. f dest

63f*

CPFSEQ

f,a

Compare f with WREG, skip if
f=WREG

f–WREG, if f=WREG, PC+4 PC
else PC+2 PC

65f*

CPFSGT

f,a

Compare f with WREG, skip if f > f–WREG, if f > WREG, PC+4 PC
WREG
else PC+2 PC

61f*

CPFSLT

f,a

Compare f with WREG, skip if f < f–WREG, if f < WREG, PC+4 PC
WREG
else PC+2 PC

07f*

DECF

f,d,a

Decrement f

f–1 dest

2Ff*

DECFSZ

f,d,a

Decrement f, skip if 0

f–1 dest, if dest=0, PC+4 PC
else PC+2 PC

4Ff*

DCFSNZ

f,d,a

Decrement f, skip if not 0

f–1 dest, if dest 0, PC+4 PC
else PC+2 PC

2Bf*

INCF

f,d,a

Increment f

f+1 dest

3Ff*

INCFSZ

f,d,a

Increment f, skip if 0

f+1 dest, if dest=0, PC+4 PC
else PC+2 PC

4Bf*

INFSNZ

f,d,a

Increment f, skip if not 0

f+1 dest, if dest 0, PC+4 PC
else PC+2 PC

13f*

IORWF

f,d,a

Inclusive OR WREG with f

WREG .OR. f dest

53f*

MOVF

f,d,a

Move f

f dest

Cf'
Ff”

MOVFF

f',f”

Move f' to fd” (second word)

f' f”

6Ff*

MOVWF

f,a

Move WREG to f

WREG f

03f*

MULWF

f,a

Multiply WREG with f

WREG * f PRODH:PRODL

6Df*

NEGF

f,a

Negate f

-f f

37f*

RLCF

f,d,a

Rotate left f through Carry

register f
C

DS33014L-page 324

7......0

 1994-2013 Microchip Technology Inc.

Instruction Sets
TABLE A-16:
Hex
47f*

PIC18 BYTE-ORIENTED REGISTER OPERATIONS (CONTINUED)
Mnemonic

RLNCF

f,d,a

Description

Function

Rotate left f (no carry)

register f
7......0

33f*

RRCF

f,d,a

Rotate right f through Carry

register f
C

43f*

RRNCF

f,d,a

7......0

Rotate right f (no carry)

register f
7......0

69f*

SETF

f,a

Set f

0xFF f

57f*

SUBFWB

f,d,a

Subtract f from WREG with
Borrow

WREG–f–C dest

5Ff*

SUBWF

f,d,a

Subtract WREG from f

f–WREG dest

5Bf*

SUBWFB

f,d,a

Subtract WREG from f with
Borrow

f–WREG–C dest

3Bf*

SWAPF

f,d,a

Swap nibbles of f

f<3:0> dest<7:4>, f<7:4> dest<3:0>

67f*

TSTFSZ

f,a

Test f, skip if 0

PC+4 PC, if f=0, else PC+2 PC

1Bf*

XORWF

f,d,a

Exclusive OR WREG with f

WREG .XOR. f dest

* Assuming default bit values for d and a.

 1994-2013 Microchip Technology Inc.

DS33014L-page 325

Assembler/Linker/Librarian User’s Guide
TABLE A-17:
Hex

PIC18 BIT-ORIENTED REGISTER OPERATIONS
Mnemonic

Description

Function
0 f

f,b,a

Bit Clear f

BSF

f,b,a

Bit Set f

1 f

BTFSC

f,b,a

Bit test f, skip if clear

if f=0, PC+4PC, else PC+2PC

A1f*

BTFSS

f,b,a

Bit test f, skip if set

if f=1, PC+4PC, else PC+2PC

71f*

BTG

f,b,a

Bit Toggle f

f f

91f*

BCF

81f*
B1f*

* Assuming b = 0 and default bit value for a.

TABLE A-18:
Hex

PIC18 CONTROL OPERATIONS
Mnemonic

Description

Function

n

Branch if Carry

if C=1, PC+2+2*nPC, else PC+2PC

BN

n

Branch if Negative

if N=1, PC+2+2*nPC, else PC+2PC

BNC

n

Branch if Not Carry

if C=0, PC+2+2*nPC, else PC+2PC

BNN

n

Branch if Not Negative

if N=0, PC+2+2*nPC, else PC+2PC

BNOV

n

Branch if Not Overflow

if OV=0, PC+2+2*nPC, else PC+2PC

E1n

BNZ

n

Branch if Not Zero

if Z=0, PC+2+2*nPC, else PC+2PC

E4n

BOV

n

Branch if Overflow

if OV=1, PC+2+2*nPC, else PC+2PC

D'0'n BRA

n

Branch Unconditionally

PC+2+2*nPC

E0n

BZ

n

Branch if Zero

if Z=1, PC+2+2*nPC, else PC+2PC

ECkk*
Fkkk

CALL

n,s

Call Subroutine

0004

CLRWDT

Clear Watchdog Timer

0 WDT, 0 WDT postscaler,
1 TO,1 PD

0007

DAW

Decimal Adjust WREG

if WREG<3:0> >9 or DC=1,
WREG<3:0>+6WREG<3:0>,
else WREG<3:0> WREG<3:0>;
if WREG<7:4> >9 or C=1,
WREG<7:4>+6WREG<7:4>,
else WREG<7:4> WREG<7:4>;

EFkk
Fkkk

GOTO

Go to address

n PC<20:1>

0000

NOP

No Operation

No Operation

Fxxx

NOP

No Operation

No Operation (2-word instructions)

0006

POP

Pop top of return stack (TOS)

TOS-1 TOS

0005

PUSH

Push top of return stack (TOS)

PC +2TOS

E2n

BC

E6n
E3n
E7n
E5n

D'1'n RCALL
00FF

n

n

RESET

1st word
2nd word

1st word
2nd word

PC+4 TOS, n PC<20:1>,
if s=1, WREG WREGs,
STATUS STATUSs, BSR BSRs

Relative Call

PC+2 TOS, PC+2+2*nPC

Software device reset

Same as MCLR reset

0010* RETFIE

s

Return from interrupt
(and enable interrupts)

TOS PC, 1 GIE/GIEH or PEIE/GIEL,
if s=1, WREGs WREG, STATUSs STATUS,
BSRs BSR, PCLATU/PCLATH are unchanged.

0012* RETURN

s

Return from subroutine

TOS PC, if s=1, WREGs WREG,
STATUSs STATUS, BSRs BSR,
PCLATU/PCLATH are unchanged

Enter SLEEP Mode

0 WDT, 0 WDT postscaler,
1 TO, 0 PD

0003

SLEEP

* Assuming default bit value for s.

DS33014L-page 326

 1994-2013 Microchip Technology Inc.

Instruction Sets
TABLE A-19:
Hex

PIC18 LITERAL OPERATIONS
Mnemonic

Description

Function
WREG+kk WREG

0Fkk

ADDLW

kk

Add literal to WREG

0Bkk

ANDLW

kk

AND literal with WREG

WREG .AND. kk WREG

09kk

IORLW

kk

Inclusive OR literal with WREG

WREG .OR. kk WREG

EErk
F0kk

LFSR

r,kk

Move literal (12 bit) 2nd word
to FSRr 1st word

kk FSRr

010k

MOVLB

k

Move literal to BSR<3:0>

kk BSR

0Ekk

MOVLW

kk

Move literal to WREG

kk WREG

0Dkk

MULLW

kk

Multiply literal with WREG

WREG * kkPRODH:PRODL

0Ckk

RETLW

kk

Return with literal in WREG

kk WREG

08kk

SUBLW

kk

Subtract WREG from literal

kk–WREG WREG

0Akk

XORLW

kk

Exclusive OR literal with WREG

WREG .XOR. kk WREG

TABLE A-20:
Hex

PIC18 MEMORY OPERATIONS

Mnemonic

Description

Function

0008

TBLRD*

Table Read

Prog Mem (TBLPTR) TABLAT

0009

TBLRD*+

Table Read with post-increment

Prog Mem (TBLPTR) TABLAT
TBLPTR +1 TBLPTR

000A

TBLRD*-

Table Read with post-decrement

Prog Mem (TBLPTR) TABLAT
TBLPTR -1 TBLPTR

000B

TBLRD+*

Table Read with pre-increment

TBLPTR +1 TBLPTR
Prog Mem (TBLPTR) TABLAT

000C

TBLWT*

Table Write

TABLAT Prog Mem(TBLPTR)

000D

TBLWT*+

Table Write with post-increment

TABLAT Prog Mem(TBLPTR)
TBLPTR +1 TBLPTR

000E

TBLWT*-

Table Write with post-decrement

TABLAT Prog Mem(TBLPTR)
TBLPTR -1 TBLPTR

000F

TBLWT+*

Table Write with pre-increment

TBLPTR +1 TBLPTR
TABLAT Prog Mem(TBLPTR)

 1994-2013 Microchip Technology Inc.

DS33014L-page 327

Assembler/Linker/Librarian User’s Guide
A.9

PIC18 DEVICE EXTENDED INSTRUCTION SET
Some PIC18 devices have an extended mode of operation for use with the MPLAB C18
compiler. This mode will change the operation of some instructions listed in
Section A.8 “PIC18 Device Instruction Set” and add the instructions listed in this
section.
In general, you should not need to use the extended instruction set. However, if
needed, the extended mode is set using a special device configuration bit. For more on
extended mode, see the MPLAB C18 C Compiler User’s Guide (DS51288) and your
device data sheet. To set up your IDE project for use with extended mode, see the
MPASM online help for Section “MPLAB C18: Setup for PIC18 Extended
Instruction Set Use” (MPLAB X IDE) or Section “MPLAB C18: Setup for PIC18
Extended Instruction Set Use” (MPLAB IDE v8).
Instruction opcode is shown in hex by making certain assumptions, either listed in the
key or as a footnote. For more information on the opcode bit values for each instruction,
as well as the number of cycles per instruction, status bits affected and complete
instruction details, see the relevant device data sheet.

TABLE A-21:
Hex

PIC18 EXTENDED INSTRUCTIONS
Mnemonic

Description

Function
FSR(f)+k  FSR(f)

E8fk

ADDFSR

f,k

Add literal to FSR

E8Ck

ADDULNK

k

Add literal to FSR2 and return

FSR2+k  FSR2, (TOS) PC

0014

CALLW

Call subroutine using WREG

(PC + 2)  TOS, (W)  PCL,
(PCLATH)  PCH, (PCLATU)  PCU

EB’0’z
Ffff

MOVSF

z’,f”

Move z’ (source) to 1st word,
f” (destination)2nd word

((FSR2)+z’)  f”

EB’1’z
Fxzz

MOVSS

z’,z”

Move z’ (source) to 1st word,
z” (destination)2nd word

((FSR2)+z’)  ((FSR2)+z”)

EAkk

PUSHL

k

Store literal at FSR2,
decrement FSR2

k FSR2),
FSR2-1 FSR2

E9fk

SUBFSR

f,k

Subtract literal from FSR

FSR(f-k) FSR(f)

E9Ck

SUBULNK

k

Subtract literal from FSR2 and return

FSR2-k FSR2, (TOS) PC

DS33014L-page 328

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Appendix B. Useful Tables
B.1

INTRODUCTION
Some useful tables are included for reference here. The tables are:
• ASCII Character Set
• Hexadecimal to Decimal Conversion

B.2

ASCII CHARACTER SET
This table displays the standard ASCII character set in nibbles.
Most Significant Nibble

Least
Significant
Nibble

 1994-2013 Microchip Technology Inc.

HEX

0

1

2

3

4

5

6

7

0

NUL

DLE

Space

0

@

P

`

p

1

SOH

DC1

!

1

A

Q

a

q

2

STX

DC2

"

2

B

R

b

r

3

ETX

DC3

#

3

C

S

c

s

4

EOT

DC4

$

4

D

T

d

t

5

ENQ

NAK

%

5

E

U

e

u

6

ACK

SYN

&

6

F

V

f

v

7

Bell

ETB

'

7

G

W

g

w

8

BS

CAN

(

8

H

X

h

x

9

HT

EM

)

9

I

Y

i

y

A

LF

SUB

*

:

J

Z

j

z

B

VT

ESC

+

;

K

[

k

{

C

FF

FS

,

<

L

\

l

|

D

CR

GS

–

=

M

]

m

}

E

SO

RS

.

>

N

^

n

~

F

SI

US

/

?

O

_

o

DEL

DS33014L-page 329

Assembler/Linker/Librarian User’s Guide
B.3

HEXADECIMAL TO DECIMAL CONVERSION
This table describes how to convert hexadecimal to decimal. For each HEX digit, find
the associated decimal value. Add the numbers together
High Byte

Low Byte

HEX 1000

Dec

HEX 100

Dec

HEX 10

Dec

HEX 1

Dec

0

0

0

0

0

0

0

0

1

4096

1

256

1

16

1

1

2

8192

2

512

2

32

2

2

3

12288

3

768

3

48

3

3

4

16384

4

1024

4

64

4

4

5

20480

5

1280

5

80

5

5

6

24576

6

1536

6

96

6

6

7

28672

7

1792

7

112

7

7

8

32768

8

2048

8

128

8

8

9

36864

9

2304

9

144

9

9

A

40960

A

2560

A

160

A

10

B

45056

B

2816

B

176

B

11

C

49152

C

3072

C

192

C

12

D

53248

D

3328

D

208

D

13

E

57344

E

3584

E

224

E

14

F

61440

F

3840

F

240

F

15

For example, HEX A38F converts to 41871 as follows:
HEX 1000’s Digit HEX 100’s Digit HEX 10’s Digit HEX 1’s Digit
40960

DS33014L-page 330

768

128

15

Result
41871 Decimal

 1994-2013 Microchip Technology Inc.

ASSEMBLER/LINKER/LIBRARIAN
USER’S GUIDE
Index
Symbols
__badram ................................................................. 75
__badrom ................................................................. 76
__config ............................................................86, 195
__fuses .................................................................... 86
__idlocs ...........................................................123, 195
__maxram .............................................................. 136
__maxrom .............................................................. 137
_CRUNTIME .......................................................... 246
_DEBUG ................................................................ 246
_DEBUGCODELEN ............................................... 246
_DEBUGCODESTART .......................................... 246
_DEBUGDATALEN................................................ 246
_DEBUGDATASTART ........................................... 246
_EXTENDEDMODE............................................... 246
_mplink.exe ............................................................ 256
.asm ....................................................................21, 37
.c .........................................................................21, 37
.cof ..............................................................21, 37, 227
.hex .............................................................21, 37, 227
.hxh ........................................................................ 227
.hxl ......................................................................... 227
.lib ...............................................................21, 37, 226
.lkr ...............................................................21, 37, 226
.lst .......................................................................... 227
.map ....................................................................... 229
.o .................................................................21, 37, 226
.out ......................................................................... 227
#define ..................................................................... 98
#include...........................................................130, 189
#undefine ............................................................... 162
$ ............................................................................... 69

A
Absolute Code, Generating...................................... 50
Access Section
Overlayed ......................................................... 74
access_ovr ............................................................... 74
ACCESSBANK ...............................................239, 244
Accessing Labels From Other Modules ................. 196
Allocation
Absolute.......................................................... 252
Relocatable..................................................... 252
Stack ............................................................... 252
AND, logical ............................................................. 69
Arithmatic Operators ................................................ 69
ASCII Character Set .............................................. 329
Assembler Command Line Options
?........................................................................ 63
a........................................................................ 63
c ........................................................................ 63

 1994-2013 Microchip Technology Inc.

d ........................................................................ 63
e ........................................................................ 63
h ........................................................................ 63
l ......................................................................... 64
m ....................................................................... 64
o ........................................................................ 64
p ........................................................................ 64
q ........................................................................ 64
r......................................................................... 64
s ........................................................................ 64
t ......................................................................... 64
w ....................................................................... 64
x ........................................................................ 64
y ........................................................................ 64

B
badram ..................................................................... 75
badrom ..................................................................... 76
Bank Selecting ......................................................... 80
Bank Selecting, Indirect ........................................... 77
Banking .......................................................... 176, 197
bankisel .................................................................... 77
banksel............................................................. 80, 197
Bit Assignments ..................................................... 175
Blank Listing Lines ................................................. 153
Block of Constants ........................................... 82, 103
Boot Loader............................................................ 267
Build Options...................................................... 22, 38
Build Project
Command Line................................................ 259
MPLAB IDE............................................. 256, 257

C
Caveats, Linker Script ............................................ 238
cblock ....................................................................... 82
COD file.................................................................. 220
code ..........................................................84, 190, 195
Code Section.................................................... 84, 175
Code Section, Packed.............................................. 85
code_pack................................................................ 85
Code, Absolute.......................... 50, 190, 194, 197, 198
Code, Relocatable............................. 50, 190, 195, 197
Calling File ...................................................... 199
Defining Module .............................................. 196
Library Routine................................................ 199
Referencing Module........................................ 196
CODEPAGE................................................... 243, 244
COF File............................................................. 21, 37
COFF Object Module File ...................................... 227
Command Line Interface
Assembler ......................................................... 63
Librarian .......................................................... 300

DS33014L-page 331

Assembler/Linker/Librarian User’s Guide
Linker .............................................................. 232
Comments ................................................................ 54
Common Problems
Linker .............................................................. 294
Compiler ............................................ 21, 24, 37, 39, 40
Conditional Assembly Directives .............................. 72
else ................................................................. 102
endif ................................................................ 104
endw ............................................................... 105
fi ...................................................................... 104
if ...................................................................... 125
ifdef ................................................................. 127
ifndef ............................................................... 129
while ................................................................ 165
Conditional Linker Statements ............................... 245
config........................................................................ 88
Config Bits ...................................................86, 88, 195
Configuration Bits ........................................86, 88, 195
constant.................................................................... 89
Constant Compare ................................................. 205
Constants
Block Of .................................................... 82, 103
Declare.............................................................. 89
Define.............................................................. 105
Control Directives ..................................................... 72
#define .............................................................. 98
#include........................................................... 130
#undefine ........................................................ 162
constant ............................................................ 89
end .................................................................. 103
equ .................................................................. 105
org ................................................................... 141
processor ........................................................ 147
radix ................................................................ 148
set ................................................................... 152
variable ........................................................... 163
Create Numeric and Text Data................................. 92
Customer Support .................................................... 15

D
da ............................................................................. 90
Data
Byte ................................................................... 94
EEPROM Byte .................................................. 96
Word ............................................................... 101
data .................................................................... 65, 92
Data Directives ......................................................... 72
__badram .......................................................... 75
__badrom .......................................................... 76
__config ............................................................ 86
__fuses ............................................................. 86
__idlocs ........................................................... 123
__maxram ....................................................... 136
__maxrom ....................................................... 137
cblock ................................................................ 82
config ................................................................ 88
da ...................................................................... 90
data ................................................................... 92
db ...................................................................... 94
de ...................................................................... 96
dt ..................................................................... 100

DS33014L-page 332

dtm .................................................................. 100
dw.................................................................... 101
endc ................................................................ 103
fill..................................................................... 116
res ................................................................... 150
Data Section
Access Uninitialized ........................................ 156
Initialized ......................................................... 120
Initialized Access............................................. 122
Overlayed Uninitialized ................................... 158
Shared Uninitialized ........................................ 160
Uninitialized..................................................... 154
Data, Initialized....................................................... 254
DATABANK .................................................... 239, 244
db ............................................................................. 94
de ............................................................................. 96
Debug
Command Line................................................ 247
MPLAB IDE ..................................................... 235
Decrement................................................................ 70
define........................................................................ 98
Delete a Substitution Label .................................... 162
Directives.................................................................. 53
Directives, Assembler............................................... 71
Directives, Linker.................................................... 237
Documentation
Conventions ...................................................... 12
Layout ................................................................. 9
dt ............................................................................ 100
dtm ......................................................................... 100
dw..................................................................... 65, 101

E
EEPROM ................................................................ 264
Data Byte .......................................................... 96
Start Address .................................................... 96
Eight-by-Eight Multiply............................................ 204
else......................................................................... 102
end ......................................................................... 103
endc........................................................................ 103
endif........................................................................ 104
endm ...................................................................... 104
endw....................................................................... 105
Environment Variables ................................... 259, 260
equ ......................................................................... 105
error........................................................................ 106
Error File........................................................... 57, 207
errorlevel ................................................................ 108
Errors
Assembler ....................................................... 208
COFF .............................................................. 293
COFF to COD Converter................................. 307
Librarian Parse................................................ 301
Linker .............................................................. 287
Linker Parse .................................................... 285
Escape Sequences .................................................. 66
Examples, Application
#define .............................................. 99, 178, 182
#include........................................................... 170
#undefine .................................................. 99, 178
bankisel ....................................................... 78, 79

 1994-2013 Microchip Technology Inc.

Index
banksel ........................................ 81, 82, 171, 180
cblock................................................................ 83
code ...........................................................84, 171
constant ...................................................164, 178
da ...................................................................... 90
data ..............................................................92, 93
db .................................................................94, 95
de ...................................................................... 97
else ................................................................. 126
end .................................................................. 170
endc .................................................................. 83
endif ................................................................ 126
endm ........................................................135, 180
endw ............................................................... 166
equ ...........................................................152, 171
error ................................................................ 106
errorlevel ......................................................... 108
exitm ............................................................... 111
extern .............................................................. 114
fill .............................................................117, 118
global ...............................................114, 182, 184
idata ................................................................ 121
if ...................................................................... 126
ifdef ..........................................................127, 128
list ............................................................148, 182
local ................................................................ 132
macro .......................................................135, 180
messg ............................................................. 138
org............................................................142, 143
pagesel ....................................................145, 171
radix ................................................................ 148
res ............................................ 150, 171, 182, 184
set ............................................................152, 178
udata........................................ 155, 171, 182, 184
udata_acs ....................................................... 156
udata_ovr ........................................................ 159
udata_shr ........................................................ 160
variable ....................................................164, 178
while................................................................ 166
Examples, Simple
__badram.......................................................... 75
__badrom.......................................................... 76
__config ............................................................ 87
__idlocs........................................................... 123
__maxram ......................................................... 75
__maxrom ......................................................... 76
#define .............................................................. 98
#include .......................................................... 130
#undefine ........................................................ 162
bankisel............................................................. 77
banksel ............................................................. 80
cblock................................................................ 83
code .................................................................. 84
code_pack ........................................................ 85
config ................................................................ 89
data ................................................................... 92
db ...................................................................... 94
de ...................................................................... 96
dt ..................................................................... 100
dw ................................................................... 101

 1994-2013 Microchip Technology Inc.

else ................................................................. 102
end .................................................................. 103
endm ............................................................... 104
equ .................................................................. 105
error ................................................................ 106
errorlevel ......................................................... 108
exitm ............................................................... 111
extern .............................................................. 114
fill..................................................................... 116
global .............................................................. 119
idata ........................................................ 120, 122
if ...................................................................... 125
ifdef ................................................................. 127
ifndef ............................................................... 129
list.................................................................... 131
local................................................................. 132
macro ...............................................113, 134, 140
messg ............................................................. 138
org................................................................... 141
pagesel ................................................... 144, 146
processor ........................................................ 147
radix ................................................................ 148
res ................................................................... 150
set ................................................................... 152
space ........................................................ 74, 153
subtitle............................................................. 153
title .................................................................. 154
udata ............................................................... 154
udata_acs ....................................................... 156
udata_ovr ........................................................ 158
udata_shr ........................................................ 160
variable ........................................................... 163
while................................................................ 165
Executable Files................................................. 21, 37
Execute If Symbol Defined..................................... 127
Execute If Symbol Not Defined .............................. 129
exitm....................................................................... 111
expand ................................................................... 113
Export a Label ........................................................ 119
Extended Microcontroller Mode ............................. 264
extern ............................................................. 114, 196
External Label ........................................................ 114
External Memory .................................................... 188

F
fi ............................................................................. 104
File
Error ................................................................ 207
Listing................................................................ 73
FILES ..................................................................... 237
fill............................................................................ 116
Final Frontier .......................................................... 153

G
Generic Linker Script Example............................... 248
Generic Linker Scripts............................................ 261
global...................................................................... 119

H
Header Files............................................130, 174, 189
Hex Files ............................................... 21, 37, 57, 227

DS33014L-page 333

Assembler/Linker/Librarian User’s Guide
Hexadecimal to Decimal Conversion ..................... 330
high .................................................................. 69, 191

I
ID Locations ................................................... 123, 195
idata ............................................................... 120, 194
idata_acs ................................................................ 122
idlocs ...................................................................... 123
if ............................................................................. 125
else ................................................................. 102
end .................................................................. 104
ifdef ........................................................................ 127
IFDEF/ELSE/FI in Linker Scripts ............................ 245
ifndef ...................................................................... 129
INCLUDE ............................................................... 238
include .................................................................... 130
Include Additional Source File................................ 130
Include File ............................................................... 54
Increment ................................................................. 70
Initialized Data........................................................ 254
Input/Output Files
Assembler ......................................................... 52
Librarian .......................................................... 298
Linker .............................................................. 226
Instruction Operands .............................................. 191
Instruction Sets ...................................................... 311
12-Bit Core .............................................. 313, 320
12-Bit/14-Bit Cores.......................................... 320
14-Bit Core ...................................................... 315
PIC18 Device .................................................. 322
Internet Address, Microchip...................................... 14
Interrupt Handling
PIC16 Example ................ 109, 117, 142, 172, 177
PIC18 Example ....................................... 118, 143

L
Labels....................................................................... 53
LIBPATH ................................................................ 237
Librarian Command Line Options
c ...................................................................... 300
d ...................................................................... 300
q ...................................................................... 300
r ....................................................................... 300
t ....................................................................... 300
x ...................................................................... 300
Library File ..........................................21, 37, 226, 298
Library Path .................................................... 257, 258
Limitations
Assembler ....................................................... 220
LINEARMEM .......................................................... 239
Linker Command Line Options
? ...................................................................... 233
a ...................................................................... 233
d ...................................................................... 233
g ...................................................................... 233
h ...................................................................... 233
i ....................................................................... 233
k ...................................................................... 233
l ....................................................................... 233
m ..................................................................... 233
n ...................................................................... 233

DS33014L-page 334

o ...................................................................... 233
q ...................................................................... 233
u ...................................................................... 233
v ...................................................................... 233
w.............................................................. 233, 306
x .............................................................. 233, 306
z ...................................................................... 233
Linker Processing................................................... 251
Linker Scripts.......................................21, 37, 226, 235
Debug Tool...................................................... 235
Standard.......................................................... 236
Linux Support ........................................................... 17
list ........................................................................... 131
Listing Directives ...................................................... 73
error................................................................. 106
errorlevel ......................................................... 108
list.................................................................... 131
messg.............................................................. 138
nolist................................................................ 140
page ................................................................ 144
space............................................................... 153
subtitle............................................................. 153
title................................................................... 154
Listing File .................................................. 54, 73, 227
LKRPATH............................................................... 237
local ........................................................................ 132
Logical Sections ..................................................... 244
low .................................................................... 69, 191

M
Mac Support ............................................................. 17
Macro
Code Examples............................................... 204
End.................................................................. 104
Exit .................................................................. 111
Expand ............................................................ 113
No Expansion.................................................. 140
Text Substitution ............................................. 202
Usage.............................................................. 203
macro ..................................................................... 134
Macro Directives....................................................... 73
Defined............................................................ 202
endm ............................................................... 104
exitm................................................................ 111
expand ............................................................ 113
local................................................................. 132
macro .............................................................. 134
noexpand ........................................................ 140
Macro Language .................................................... 201
Macro Syntax ......................................................... 201
Macros...................................................................... 53
Macros in Linker Scripts ......................................... 246
main.......................................................................... 67
Map File...........................................229, 256, 257, 258
Maximum RAM Location ........................................ 136
Maximum ROM Location........................................ 137
maxram .................................................................. 136
maxrom .................................................................. 137
MCC_INCLUDE ............................................. 259, 260
Memory
Fill.................................................................... 116

 1994-2013 Microchip Technology Inc.

Index
Reserve .......................................................... 150
Memory Regions .................................................... 239
Message ................................................................ 138
Messages
Assembler ....................................................... 218
messg .................................................................... 138
Mnemonics............................................................... 53
mp2cod Utility ........................................................ 306
mp2hex Utiltiy ........................................................ 306
MPASM Assembler .............................................22, 38
MPASM Assembler Overview .................................. 49
mpasm.exe ............................................................ 220
mpasmwin.exe ....................................................33, 34
mpasmx.exe............................................ 17, 18, 49, 61
MPLAB C18 C Compiler ......................... 21, 24, 37, 40
MPLAB IDE Build Options Dialog
MPASM Assembler Tab ................................... 38
MPASM/C17/C18 Suite Tab ............................. 41
MPLAB C17 Tab ............................................... 39
MPLAB C18 Tab ............................................... 40
MPLINK LinkerTab ........................................... 41
MPLIB Librarian Overview ..................................... 297
MPLIB Object Librarian .................................21, 37, 41
mplib.exe................................................. 17, 18, 33, 34
MPLINK Linker Overview ....................................... 223
MPLINK Object Linker ............................ 21, 23, 37, 41
mplink.exe ............................................... 17, 18, 33, 34
myMicrochip Personalized Notification Service ....... 14

org .......................................................................... 141

P
page ....................................................................... 144
Page Eject.............................................................. 144
Page Selection ....................................................... 144
Page Selection - WREG......................................... 146
pagesel........................................................... 144, 197
pageselw ................................................................ 146
Paging ............................................................ 175, 197
PATH.............................................................. 259, 260
Processing, Linker.................................................. 251
processor ............................................................... 147
Processor, Set.........................................131, 147, 171
Program Memory ................................................... 190
Projects .............................................................. 20, 36
PROTECTED ......................................................... 239

R

noexpand ............................................................... 140
nolist....................................................................... 140
NOT, logical ............................................................. 69

Radix ........................................................................ 67
radix ....................................................................... 148
Radix, Set................................................131, 148, 171
RAM Allocation....................................................... 194
RAM Memory Regions, Defining............................ 239
Reading, Recommended ......................................... 13
Register Assignments ............................................ 175
relocatable................................................................ 59
Relocatable Code, Generating................................. 50
Relocatable Objects ............................................... 189
res .......................................................................... 150
Reserved Section Names, Assembler ..................... 67
Reserved Words, Assembler ................................... 67
ROM Memory Regions, Defining ........................... 243

O

S

Object File .................................................59, 226, 298
Object File Directives ............................................... 73
access_ovr........................................................ 74
bankisel............................................................. 77
banksel ............................................................. 80
code .................................................................. 84
code_pack ........................................................ 85
extern .............................................................. 114
global .............................................................. 119
idata ................................................................ 120
idata_acs ........................................................ 122
pagesel ........................................................... 144
pageselw......................................................... 146
udata............................................................... 154
udata_acs ....................................................... 156
udata_ovr ........................................................ 158
udata_shr ........................................................ 160
Object Files, Precompiled ...................................21, 37
Object Module, Generating .................................... 198
Operands ................................................................. 53
Operators, Arithmatic ............................................... 69
Options, Command Line
Assembler ......................................................... 63
Librarian .......................................................... 300
Linker .............................................................. 232
OR, logical ............................................................... 69

Sample Applications, Linker................................... 255
Scripts, Linker ........................................................ 235
Search Order, Include Files ................................... 130
SECTION ....................................................... 239, 244
set .......................................................................... 152
Set Program Origin ................................................ 141
SHAREBANK ................................................. 239, 244
Simple ................................................................ 75, 76
Source Code ...................................................... 21, 37
Source Code File, Assembly.................................... 52
space...................................................................... 153
Stack ...................................................................... 244
STACK SIZE .......................................................... 244
Standard Linker Scripts.......................................... 236
Store Strings in Program Memory............................ 90
subtitle.................................................................... 153
Symbol Constant...................................................... 89
Symbols, In Expressions.......................................... 69

N

 1994-2013 Microchip Technology Inc.

T
Table, Define.......................................................... 100
Templates .............................................................. 261
Text Strings .............................................................. 65
Text Substitution Label............................................. 98
Tips and Tricks
Bit Shifting Using Carry Bit.............................. 188

DS33014L-page 335

Assembler/Linker/Librarian User’s Guide
Conditional Bit Set/Clear ................................. 187
Delay Techniques ........................................... 186
Optimizing Destinations .................................. 187
Swap File Register with W .............................. 188
Using External Memory................................... 188
title.......................................................................... 154
Troubleshooting ..................................................... 207

U
udata .............................................................. 154, 194
udata_acs....................................................... 156, 194
udata_ovr ....................................................... 158, 194
udata_shr ....................................................... 160, 194
undefine ................................................................. 162
Unimplemented RAM ............................................... 75
Unimplemented ROM............................................... 76
upper ................................................................ 69, 191
Utilities Overview and Usage ................................. 305

V
Variable
Declare............................................................ 163
Define.............................................................. 152
Local ............................................................... 132

W
Warnings
Assembler ....................................................... 215
COFF to COD Converter................................. 307
Linker .............................................................. 292
Watch Window ....................................................... 179
Watches Window.................................................... 179
Web Site, Microchip ................................................. 14
while ....................................................................... 165
White Space ............................................................. 52
Windows Shell Interface........................................... 62
Windows Support ..................................................... 17

DS33014L-page 336

 1994-2013 Microchip Technology Inc.

Index
NOTES:

 1994-2013 Microchip Technology Inc.

DS33014L-page 337

Worldwide Sales and Service
AMERICAS

ASIA/PACIFIC

ASIA/PACIFIC

EUROPE

Corporate Office
2355 West Chandler Blvd.
Chandler, AZ 85224-6199
Tel: 480-792-7200
Fax: 480-792-7277
Technical Support:
http://www.microchip.com/
support
Web Address:
www.microchip.com

Asia Pacific Office
Suites 3707-14, 37th Floor
Tower 6, The Gateway
Harbour City, Kowloon
Hong Kong
Tel: 852-2401-1200
Fax: 852-2401-3431

India - Bangalore
Tel: 91-80-3090-4444
Fax: 91-80-3090-4123
India - New Delhi
Tel: 91-11-4160-8631
Fax: 91-11-4160-8632

Austria - Wels
Tel: 43-7242-2244-39
Fax: 43-7242-2244-393
Denmark - Copenhagen
Tel: 45-4450-2828
Fax: 45-4485-2829

India - Pune
Tel: 91-20-2566-1512
Fax: 91-20-2566-1513

France - Paris
Tel: 33-1-69-53-63-20
Fax: 33-1-69-30-90-79

Japan - Osaka
Tel: 81-6-6152-7160
Fax: 81-6-6152-9310

Germany - Munich
Tel: 49-89-627-144-0
Fax: 49-89-627-144-44

Atlanta
Duluth, GA
Tel: 678-957-9614
Fax: 678-957-1455
Boston
Westborough, MA
Tel: 774-760-0087
Fax: 774-760-0088
Chicago
Itasca, IL
Tel: 630-285-0071
Fax: 630-285-0075
Cleveland
Independence, OH
Tel: 216-447-0464
Fax: 216-447-0643
Dallas
Addison, TX
Tel: 972-818-7423
Fax: 972-818-2924
Detroit
Farmington Hills, MI
Tel: 248-538-2250
Fax: 248-538-2260
Indianapolis
Noblesville, IN
Tel: 317-773-8323
Fax: 317-773-5453
Los Angeles
Mission Viejo, CA
Tel: 949-462-9523
Fax: 949-462-9608
Santa Clara
Santa Clara, CA
Tel: 408-961-6444
Fax: 408-961-6445
Toronto
Mississauga, Ontario,
Canada
Tel: 905-673-0699
Fax: 905-673-6509

Australia - Sydney
Tel: 61-2-9868-6733
Fax: 61-2-9868-6755
China - Beijing
Tel: 86-10-8569-7000
Fax: 86-10-8528-2104
China - Chengdu
Tel: 86-28-8665-5511
Fax: 86-28-8665-7889
China - Chongqing
Tel: 86-23-8980-9588
Fax: 86-23-8980-9500

Netherlands - Drunen
Tel: 31-416-690399
Fax: 31-416-690340

Korea - Daegu
Tel: 82-53-744-4301
Fax: 82-53-744-4302

Spain - Madrid
Tel: 34-91-708-08-90
Fax: 34-91-708-08-91

China - Hangzhou
Tel: 86-571-2819-3187
Fax: 86-571-2819-3189

Korea - Seoul
Tel: 82-2-554-7200
Fax: 82-2-558-5932 or
82-2-558-5934

China - Hong Kong SAR
Tel: 852-2943-5100
Fax: 852-2401-3431

Malaysia - Kuala Lumpur
Tel: 60-3-6201-9857
Fax: 60-3-6201-9859

China - Nanjing
Tel: 86-25-8473-2460
Fax: 86-25-8473-2470

Malaysia - Penang
Tel: 60-4-227-8870
Fax: 60-4-227-4068

China - Qingdao
Tel: 86-532-8502-7355
Fax: 86-532-8502-7205

Philippines - Manila
Tel: 63-2-634-9065
Fax: 63-2-634-9069

China - Shanghai
Tel: 86-21-5407-5533
Fax: 86-21-5407-5066

Singapore
Tel: 65-6334-8870
Fax: 65-6334-8850

China - Shenyang
Tel: 86-24-2334-2829
Fax: 86-24-2334-2393

Taiwan - Hsin Chu
Tel: 886-3-5778-366
Fax: 886-3-5770-955

China - Shenzhen
Tel: 86-755-8864-2200
Fax: 86-755-8203-1760

Taiwan - Kaohsiung
Tel: 886-7-213-7828
Fax: 886-7-330-9305

China - Wuhan
Tel: 86-27-5980-5300
Fax: 86-27-5980-5118

Taiwan - Taipei
Tel: 886-2-2508-8600
Fax: 886-2-2508-0102

China - Xian
Tel: 86-29-8833-7252
Fax: 86-29-8833-7256

Thailand - Bangkok
Tel: 66-2-694-1351
Fax: 66-2-694-1350

UK - Wokingham
Tel: 44-118-921-5869
Fax: 44-118-921-5820

China - Xiamen
Tel: 86-592-2388138
Fax: 86-592-2388130
China - Zhuhai
Tel: 86-756-3210040
Fax: 86-756-3210049

DS33014L-page 338

Italy - Milan
Tel: 39-0331-742611
Fax: 39-0331-466781

Japan - Tokyo
Tel: 81-3-6880- 3770
Fax: 81-3-6880-3771

11/29/12

 1994-2013 Microchip Technology Inc.
Source Exif Data: 
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.6
Linearized                      : No
Encryption                      : Standard V1.2 (40-bit)
User Access                     : Print, Copy, Fill forms, Extract, Assemble, Print high-res
Has XFA                         : No
XMP Toolkit                     : Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26
Format                          : application/pdf
Title                           : MPASM Assembler, MPLINK Object Linker, MPLIB Object Librarian User's Guide
Description                     : MPASM Assembler, MPLINK Object Linker, MPLIB Object Librarian User's Guide
Creator                         : Microchip Technology Inc.
Subject                         : MPASM Assembler, MPLINK Object Linker, MPLIB Object Librarian, User's Guide, development tools, MPASM, MPLINK, MPLIB, DS33014L, DS-33014L, 33014L, DS33014K, DS-33014K, 33014K, DS33014J, DS-33014J, 33014J, DS33014H, DS-33014H, 33014H, DS33014G, DS-33014G, 33014G, DS33014F, DS-33014F, 33014F, DS33014E, DS-33014E, 33014E, DS33014D, DS-33014D, 33014D, DS33014C, DS-33014C, 33014C, DS33014B, DS-33014B, 33014B, DS33014A, DS-33014A, 33014A, DS33014, DS-33014, 33014
Create Date                     : 2013:03:01 08:59:31Z
Creator Tool                    : FrameMaker 9.0
Modify Date                     : 2013:03:05 15:32:34-07:00
Metadata Date                   : 2013:03:05 15:32:34-07:00
Producer                        : Acrobat Distiller 10.1.5 (Windows)
Document ID                     : uuid:8df92193-d989-4544-989d-c749505ee7fd
Instance ID                     : uuid:921f971f-7194-42a1-8fbf-719e9697cc31
Page Mode                       : UseOutlines
Page Count                      : 338
Author                          : Microchip Technology Inc.
Keywords                        : MPASM, Assembler;, MPLINK, Object, Linker;, MPLIB, Object, Librarian;, User's, Guide;, development, tools;, MPASM;, MPLINK;, MPLIB;, DS33014L;, DS-33014L;, 33014L;, DS33014K;, DS-33014K;, 33014K;, DS33014J;, DS-33014J;, 33014J;, DS33014H;, DS-33014H;, 33014H;, DS33014G;, DS-33014G;, 33014G;, DS33014F;, DS-33014F;, 33014F;, DS33014E;, DS-33014E;, 33014E;, DS33014D;, DS-33014D;, 33014D;, DS33014C;, DS-33014C;, 33014C;, DS33014B;, DS-33014B;, 33014B;, DS33014A;, DS-33014A;, 33014A;, DS33014;, DS-33014;, 33014;
EXIF Metadata provided by EXIF.tools

Navigation menu