MPLAB XC8 PIC Assembler User's Guide - Microchip …

1 MPLAB XC8 PIC Assembler User's Guide Notice to Development Tools Customers Important: All documentation becomes dated, and Development Tools manuals are no exception. Our 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 website ( ) to obtain the latest version of the PDF document. Documents are identified with a DS number located on the bottom of each page. The DS format is DS<DocumentNumber> <Version>, where <DocumentNumber> is an 8-digit number and <Version> is an uppercase letter. For the most up-to-date information, find help for your tool at 2022 Microchip Technology Inc. User Guide DS50002974C-page 1. and its subsidiaries Table of Contents Notice to Development Tools 1. 1. Conventions Used in This Recommended 2. Assembler 6. Device 6. Compatible Development 3. Assembler Single-step Multi-step 7. Long Command 8.

2 Assembler Option 8. MPLAB X IDE 4. MPLAB XC8 Assembly 27. Assembly Instruction 27. Statement 32. 32. Expressions and Program Assembler 5. Assembler 59. Preprocessor 59. Assembler -provided Default Linker 60. Linker-Defined 62. Using a Compiled 62. Assembly List 6. 66. Psects and Map 7. 80. 81. 8. Error and Warning Messages 0 Thru 2022 Microchip Technology Inc. User Guide DS50002974C-page 2. and its subsidiaries Messages 500 Thru Messages 1000 Thru Messages 1500 Thru Messages 2000 Thru 9. Document Revision The Microchip Product Change Notification Customer 216. Microchip Devices Code Protection 216. Legal 216. 217. Quality Management 217. Worldwide Sales and 2022 Microchip Technology Inc. User Guide DS50002974C-page 3. and its subsidiaries Preface 1. Preface Conventions Used in This Guide The following conventions may appear in this documentation: Table 1-1. Documentation Conventions Description Represents Examples Arial font: Italic characters Referenced books MPLAB XC8 PIC Assembler User's Guide Emphasized text.

3 Is the only Initial caps A window the Output window A dialog the Settings dialog A menu selection Select File and then Save. Quotes A field name in a window or dialog Save project before build . Underlined, italic text with A menu path File>Save right angle bracket Bold characters A dialog button Click OK. A tab Click the Power tab N Rnnnn A number in verilog format, where 4 b0010, 2 hF1. N is the total number of digits, R is the radix and n is a digit. Text in angle brackets < > A key on the keyboard Press <Enter>, <F1>. Courier New font: Plain Courier New Sample source code #define START. Filenames File paths C:\Users\User1\Projects Keywords static, auto, extern Command-line options -Opa+, -Opa- Bit values 0, 1. Constants 0xFF, A'. Italic Courier New A variable argument , where file can be any valid filename Square brackets [ ] Optional arguments xc8 [options] files Curly brackets and pipe Choice of mutually exclusive errorlevel {0|1}.

4 Character: { | } arguments; an OR selection Replaces repeated text var_name [, ]. Represents code supplied by user void main (void). { .. }. 2022 Microchip Technology Inc. User Guide DS50002974C-page 4. and its subsidiaries Preface Recommended Reading This User's Guide describes the use and features of the MPLAB XC8 PIC Assembler . The following Microchip documents are available and recommended as supplemental reference resources. MPLAB XC8 PIC Assembler Migration Guide This Guide is for customers who have MPASM projects and who wish to migrate them to the MPLAB XC8 PIC. Assembler . It describes the nearest equivalent Assembler syntax and directives for MPASM code. MPLAB XC8 PIC Assembler Guide For Embedded Engineers This Guide is a getting started Guide , describing example projects and commonly used coding sequences used by the MPLAB XC8 PIC Assembler . Use this Guide if you need to develop new projects using the Assembler . MPLAB XC8 C Compiler Release Notes for PIC MCU.

5 For the latest information on changes and bug fixes to this Assembler , read the Readme file in the docs subdirectory of the MPLAB XC8 installation directory. Development Tools Release Notes For the latest information on using other development tools, read the tool-specific Readme files in the docs subdirectory of the MPLAB X IDE installation directory. 2022 Microchip Technology Inc. User Guide DS50002974C-page 5. and its subsidiaries Assembler Overview 2. Assembler Overview The MPLAB XC8 PIC Assembler is a free-standing cross Assembler and linker package, supporting all 8-bit PIC . microcontrollers. The internal Assembler application used by the PIC Assembler is the same as that used by the MPLAB XC8 C. Compiler tool, with the assembly language being common between both tools. This document describes the use of the PIC Assembler for writing and building source code written entirely in assembly. If you need assistance with writing assembly code to be linked with C source code, or you are writing assembly code that is to be inserted in-line with C code, refer to MPLAB XC8 C Compiler User's Guide for PIC MCU (DS50002737) for information that is better suited to these tasks.

6 Device Description This Guide describes the MPLAB XC8 PIC Assembler 's support for all 8-bit Microchip PIC devices with baseline, enhanced baseline, mid-range, enhanced mid-range and PIC18 cores. Check the ARCH field in the device's INI file to confirm the core architecture used by the Assembler when building code. The information contained within the INI files typically comes from your selected Device Family Pack (DFP), but the Assembler maintains a default set of INI files in the MPLAB XC8 pic/dat/ini directory. The following descriptions indicate the distinctions within those device cores. The baseline core uses a 12-bit-wide instruction set and is available in PIC10, PIC12 and PIC16 part numbers (ARCH. value of PIC12). The enhanced baseline core also uses a 12-bit instruction set, but this set includes additional instructions. Some of the enhanced baseline chips support interrupts and the additional instructions used by interrupts. These devices are available in PIC12 and PIC16 part numbers (ARCH value of PIC12E, or PIC12IE for those with interrupt support).

7 The mid-range core uses a 14-bit-wide instruction set that includes more instructions than the baseline core. It has larger data memory banks and program memory pages, as well. It is available in PIC12, PIC14 and PIC16 part numbers (ARCH value of PIC14). The Enhanced mid-range core also uses a 14-bit-wide instruction set but incorporates additional instructions and features. There are both PIC12 and PIC16 part numbers that are based on the Enhanced mid-range core (ARCH. value of PIC14E or PIC14EX). The PIC18 core instruction set is 16 bits wide and features additional instructions and an expanded register set. PIC18 core devices have part numbers that begin with PIC18. Some PIC18 devices implement extended data memory and a vectored interrupt controller module with support for one or more interrupt vector tables, rather than fixed-location, dual priority vectors (ARCH value of PIC18, or PIC18XV for those with the extended data memory and the vectored interrupt controller module).

8 See Print-devices for information on finding the full list of devices that are supported by the Assembler . Support for a new device might be possible after downloading an updated Device Family Pack. Compatible Development Tools The Assembler works with many other Microchip tools, including: The MPLAB X IDE ( ) for all 8-bit PIC devices The MPLAB X Simulator The Command-line MDB Simulator see the Microchip Debugger (MDB) User's Guide (DS52102). All Microchip debug tools and programmers ( ). Demonstration boards and Starter kits that support 8-bit PIC devices Check the tool's documentation to verify that it supports the device you plan to use. 2022 Microchip Technology Inc. User Guide DS50002974C-page 6. and its subsidiaries Assembler Driver 3. Assembler Driver The name of the command-line driver used by the MPLAB XC8 PIC Assembler is pic-as. This driver can be invoked to perform both assembly and link steps and is the application called by development environments, such as the MPLAB X IDE, to build assembly projects.

9 The pic-as driver has the following basic command format: pic-as [options] files [libraries]. Throughout this manual, it is assumed that the Assembler applications are in your console's search path or that the full path is specified when executing the application. It is customary to declare options (identified by a leading dash - or double dash -- ) before the files' names;. however, this is not mandatory. The formats of the options are supplied in Assembler Option Descriptions along with corresponding descriptions of the options' function. The files can be an assortment of Assembler source files and precompiled intermediate files. While the order in which these files are listed is not important, it can affect the allocation of code or data and can affect the names of some of the output files. The libraries is a list of user-defined library files that will be searched by the Assembler . The order of these files will determine the order in which they are searched.

10 It is customary to insert the libraries after the list of source files;. however, this is not mandatory. Single-step Assembly Assembly of one or more source files can be performed in just one step using the pic-as driver. The following command will build both the assembly source files, passing these files to the appropriate internal applications, then link the generated code to form the final output. pic-as -mcpu=16F877A The driver will compile all source files, regardless of whether they have changed since the last build. Development environments (such as MPLAB X IDE) and make utilities must be employed to achieve incremental builds (see Multi-step Assembly). Unless otherwise specified, a HEX file and ELF file are produced as the final output. The intermediate files remain after compilation has completed, but most other temporary files are deleted, unless you use the -save-temps option (see Save-temps Option) which preserves all generated files.