Assembler/Linker/Librarian Users Guide

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

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 Users 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 Users 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 Users 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

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 Users 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