#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 2.16
\textclass book
\language english
\inputencoding default
\fontscheme times
\graphics default
\paperfontsize 10
\spacing single 
\papersize letterpaper
\paperpackage a4
\use_geometry 1
\use_amsmath 0
\paperorientation portrait
\leftmargin 34mm
\rightmargin 34mm
\secnumdepth 2
\tocdepth 2
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title
\added_space_top vfill \added_space_bottom vfill 
gputils 0.12.0
\layout Author

James Bowman and Craig Franklin 
\layout Date

January 20, 2004
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Chapter

Introduction
\layout Standard

gputils is a collection of tools for Microchip (
\shape smallcaps 
TM
\shape default 
) PIC microcontrollers.
 It includes gpal, gpasm, gplink, and gplib.
 Each tool is intended to be an open source replacement for a corresponding
 Microchip (TM) tool.
 This manual covers the basics of running the tools.
 For more details on a microcontroller, consult the manual for the specific
 PICmicro product that you are using.
\layout Standard

This document is part of gputils.
\layout Standard

gputils is free software; you can redistribute it and/or modify it under
 the terms of the 
\begin_inset LatexCommand \index{GNU}

\end_inset 

GNU General Public 
\begin_inset LatexCommand \index{License}

\end_inset 

License as published by the Free Software Foundation; either version 2,
 or (at your option) any later version.
\layout Standard

gputils is distributed in the hope that it will be useful, but WITHOUT ANY
 
\begin_inset LatexCommand \index{NO WARRANTY}

\end_inset 

WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.
 See the GNU General Public License for more details.
\layout Standard

You should have received a copy of the GNU General Public License along
 with gputils; see the file COPYING.
 If not, write to the Free Software Foundation, 59 Temple Place - Suite
 330, Boston, MA 02111-1307, USA.
\layout Section

Tool Flows
\layout Standard

gputils can be used in three different ways: absolute asm mode, relocatable
 asm mode, and HLL mode.
\layout Subsection

Absolute Asm Mode
\layout Standard

In absolute asm mode, an assembly language source file is directly converted
 into a hex file by gpasm.
 This method is absolute because the final addresses are hard coded into
 the source file.
\layout Subsection

Relocatable Asm Mode
\layout Standard

In relocatable asm mode, the microcontroller assembly source code is divided
 into separate modules.
 Each module is assembled into an object using gpasm.
 That object can be placed 
\begin_inset Quotes eld
\end_inset 

anywhere
\begin_inset Quotes erd
\end_inset 

 in microcontroller's memory.
 Then gplink is used to resolve symbols references, assign final address,
 and to patch the machine code with the final addresses.
 The output from gplink is an absolute executable object.
\layout Subsection

HLL Mode
\layout Standard

In HLL (High Level Language) mode, the source code is written in a Ada like
 language.
 gpal then converts that file into a relocatable assembly file.
 It then automatically invokes gpasm and gplink to generate an absolute
 executable object.
\layout Subsection

Which Tool Flow is best?
\layout Standard

Absolute mode is simple to understand and to use.
 It only requires one tool, gpasm.
 Most of the examples on Microchip's website use absolute mode.
 So why use relocatable mode?
\layout Itemize

Code can be written without regard to addresses.
 This makes it easier to write and reuse.
\layout Itemize

The objects can be archived to create a library, which also simplifies reuse.
\layout Itemize

Recompiling a project can be faster, because you only compile the portions
 that have changed.
\layout Itemize

Files can have local name spaces.
 The user chooses what symbols are global.
\layout Standard

Most develpment tools use relocatable objects for these reasons.
 The few that don't are generally microcontroller tools.
 Their applications are so small that absolute mode isn't impractical.
 For PICs, relocatable mode has one big disadvantage.
 The bank and page control is a challenge.
 To overcome that, HLL mode can be used.
 It helps to hide these details from the user.
 
\layout Section

Supported processors 
\layout LyX-Code

gputils currently supports the following processors:
\layout LyX-Code

eeprom8    gen        p12c508    p12c508a   p12c509    p12c509a
\layout LyX-Code

p12c671    p12c672    p12ce518   p12ce519   p12ce673   p12ce674
\layout LyX-Code

p12cr509a  p12f629    p12f675    p14000     p16c5x     p16cxx
\layout LyX-Code

p16c432    p16c433    p16c505    p16c52     p16c54     p16c54a
\layout LyX-Code

p16c54b    p16c54c    p16c55     p16c55a    p16c554    p16c557
\layout LyX-Code

p16c558    p16c56     p16c56a    p16c57     p16c57c    p16c58a
\layout LyX-Code

p16c58b    p16c61     p16c62     p16c62a    p16c62b    p16c620
\layout LyX-Code

p16c620a   p16c621    p16c621a   p16c622    p16c622a   p16c63
\layout LyX-Code

p16c63a    p16c64     p16c64a    p16c642    p16c65     p16c65a
\layout LyX-Code

p16c65b    p16c66     p16c662    p16c67     p16c71     p16c710
\layout LyX-Code

p16c711    p16c712    p16c715    p16c716    p16c717    p16c72
\layout LyX-Code

p16c72a    p16c73     p16c73a    p16c73b    p16c74     p16c745
\layout LyX-Code

p16c747    p16c74a    p16c74b    p16c76     p16c765    p16c77
\layout LyX-Code

p16c770    p16c771    p16c773    p16c774    p16c781    p16c782
\layout LyX-Code

p16c84     p16c923    p16c924    p16c925    p16c926    p16ce623
\layout LyX-Code

p16ce624   p16ce625   p16cr54    p16cr54a   p16cr54b   p16cr54c
\layout LyX-Code

p16cr56a   p16cr57a   p16cr57b   p16cr57c   p16cr58a   p16cr58b
\layout LyX-Code

p16cr62    p16cr620a  p16cr63    p16cr64    p16cr65    p16cr72
\layout LyX-Code

p16cr83    p16cr84    p16f627    p16f627a   p16f628    p16f628a
\layout LyX-Code

p16f630    p16f648a   p16f676    p16f684    p16f716    p16f72
\layout LyX-Code

p16f73     p16f737    p16f74     p16f76     p16f767    p16f77
\layout LyX-Code

p16f777    p16f818    p16f819    p16f83     p16f84     p16f84a
\layout LyX-Code

p16f87     p16f870    p16f871    p16f872    p16f873    p16f873a
\layout LyX-Code

p16f874    p16f874a   p16f876    p16f876a   p16f877    p16f877a
\layout LyX-Code

p16f88     p16hv540   p17cxx     p17c42     p17c42a    p17c43
\layout LyX-Code

p17c44     p17c752    p17c756    p17c756a   p17c762    p17c766
\layout LyX-Code

p17cr42    p17cr43    p18cxx     p18c242    p18c252    p18c442
\layout LyX-Code

p18c452    p18c601    p18c658    p18c801    p18c858    p18f1220
\layout LyX-Code

p18f1320   p18f2220   p18f2320   p18f2331   p18f242    p18f2431
\layout LyX-Code

p18f2439   p18f248    p18f252    p18f2539   p18f258    p18f2620
\layout LyX-Code

p18f4220   p18f4320   p18f4331   p18f442    p18f4431   p18f4439
\layout LyX-Code

p18f448    p18f452    p18f4539   p18f458    p18f4620   p18f6520
\layout LyX-Code

p18f6525   p18f6585   p18f6620   p18f6621   p18f6680   p18f6720
\layout LyX-Code

p18f8520   p18f8525   p18f8585   p18f8620   p18f8621   p18f8680
\layout LyX-Code

p18f8720   rf509af    rf509ag    rf675f     rf675h     rf675k
\layout LyX-Code

sx18       sx20       sx28           
\layout Chapter

gpal
\layout Section

Introduction
\layout Standard

gpal is a compiler for Microchip (
\shape smallcaps 
TM
\shape default 
) PIC microcontrollers.
 Unlike most of the other tools in gputils, there is no corresponding Microchip
 tool that it replaces.
 It is a new tool and language specifically designed to to simplify software
 development for PICs.
 The language to very similar to the Pascal family of languages, specifically
 Ada.
\layout Standard

gpal was inspired by Jal <http://jal.sourceforge.net>.
 That language was created by Wouter Van Ooijen.
\layout Section

Running gpal
\begin_inset LatexCommand \index{gpal options}

\end_inset 


\layout Standard

The general syntax for running gpal is
\layout LyX-Code

gpal [options] input-files
\layout Standard

Where options can be one of:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
17 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
0 0 1 0
1 1 0 0
2 1 0 "" ""
2 1 1 "4in" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 1 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Option
\newline 
Meaning
\newline 
a
\newline 
Compile or assemble, then archive.
\newline 
c
\newline 
Compile or assemble, but don't link.
\newline 
d
\newline 
Output debug messages.
\newline 
h
\newline 
Show the usage message.
\newline 
H
\newline 
Scan the specified processor header file.
\newline 
I <directory>
\newline 
Specify an include directory.
\newline 
k
\begin_inset Quotes erd
\end_inset 

<options>
\begin_inset Quotes erd
\end_inset 


\newline 
Extra link or lib options.
\newline 
l
\newline 
List supported processors.
\newline 
o <file>
\newline 
Alternate name of hex output file.
\newline 
O<level>
\newline 
Optimization level.
\newline 
p<processor> 
\newline 
Select target processor.
\newline 
q
\newline 
Quiet
\newline 
S
\newline 
Compile only, don't assemble or link.
\newline 
t
\newline 
Do not delete intermediate files.
\newline 

\newline 

\newline 
v
\newline 
Print gpal version information and exit.
\layout Subsection

Operations
\layout Standard

gpal only converts .pal source files into .asm files.
 However, as a convience it can automatically invoke gpasm to convert the
 .asm file into an object file with a .o extension.
 It can also invoke gplink to produce a PIC executable or gplib to produce
 an archive of objects.
 The operations are selected using the options -S, -a, and -c.
\layout Standard

gpal will automatically remove any temporary file generated by its operation
 or by an tool it invokes.
 That behavior can be controlled using the -t option.
\layout Standard

Currently there is no difference between invoking gpal with a complete list
 of input files, verses invoking multiple times, once for each file.
 In the future, that will probably change.
\layout Subsection

Input files
\layout Standard

The following tables summarizes the types of input files gpal will accept
 and the operations it performs:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
5 5 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 0 "" ""
8 1 0 "" ""
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

File Extension
\newline 
Description
\newline 
Compile
\newline 
Assembly
\newline 
Link
\newline 
.pal
\newline 
gpal source file
\newline 
Yes
\newline 
Yes
\newline 
Yes
\newline 
.asm
\newline 
relocatable gpasm assembly file
\newline 
No
\newline 
Yes
\newline 
Yes
\newline 
.o
\newline 
COFF object generated by gpasm
\newline 
No
\newline 
No
\newline 
Yes
\newline 
.a
\newline 
COFF archive generated by glib
\newline 
No
\newline 
No
\newline 
Yes
\layout Section

Basics
\layout Subsection

Free-format 
\layout Standard

So this statement:
\layout LyX-Code

if a>b then 
\layout LyX-Code

  timer = 0;
\layout LyX-Code

end if;
\layout Standard

is equivalent to:
\layout LyX-Code

if a>b then timer = 0; end if;
\layout Standard

although not recommended.
\layout Subsection

Statement terminator
\layout Standard

The semicolon is used to terminate all statements and subprograms.
 
\layout Subsection

Comments
\layout Standard

Comments are proceeded by a double minus (--) and continue until the end
 of the current line.
 
\layout Section

Types
\layout Subsection

Builtin Types
\layout Standard

The following table defines the built in types:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
9 4 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 0 "" ""
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

Name
\newline 
Size in bytes
\newline 
Minimum Value
\newline 
Maximum Value
\newline 
uint8
\newline 
1
\newline 
0
\newline 
255
\newline 
int8
\newline 
1
\newline 
-128
\newline 
127
\newline 
uint16
\newline 
2
\newline 
0
\newline 
65,535
\newline 
int16
\newline 
2
\newline 
-32,768
\newline 
32,767
\newline 
uint24
\newline 
3
\newline 
0
\newline 
16,777,215
\newline 
int24
\newline 
3
\newline 
-8,388,608
\newline 
8,388,607
\newline 
uint32
\newline 
4
\newline 
0
\newline 
4,294,967,295
\newline 
int32
\newline 
4
\newline 
-2,147,483,648
\newline 
2,147,483,647
\layout Standard

None of the ranges are checked at run time.
 The user must ensure that any assignment expression won't overflow or underflow
 the type.
 
\layout Subsection

Arrays
\layout LyX-Code

type <name> is array <expression> to <expression> of <type>;
\layout Standard

The following example will create an array type of 10 unsigned bytes:
\layout LyX-Code

type buffer_type is array 1 to 10 of uint8;
\layout LyX-Code

variable buffer : buffer_type;
\layout Subsection

Enumerated
\layout LyX-Code

type <name> is ( <name> [, <name>]*);
\layout Standard

The following code will create and enumerated type: 
\layout LyX-Code

type main_state is (INIT, DELAY, OUTPUT);
\layout Standard

This will create a new type that can take on one of three values.
 Each symbol in the list is assigned a value starting at 0.
 Each symbol value pair is added to the global symbol table.
 All enumerated types use the uint8 size.
 So there for the maximum list size is 256 members.
\layout Subsection

Alias
\layout Standard

Types can be given new names to suit the user's preference.
 
\layout LyX-Code

type <name> is <type>;
\layout Standard

This example will create an alias of int16 with the name short.
\layout LyX-Code

type short is int16;
\layout Section

Expressions
\layout Subsection

Symbols
\layout Standard

Symbols must match the following rule:
\layout LyX-Code

[a-z][_.0-9a-z]*
\layout Standard

All symbols are case insensitive.
 So the following two statements are equivalent.
 
\layout LyX-Code

Timer = 0; 
\layout LyX-Code

tImEr = 0;
\layout Standard

The only exception is symbols that used to generate filenames.
 
\layout LyX-Code

with time;
\layout Standard

This statement will open the file 
\begin_inset Quotes eld
\end_inset 

time.pub
\begin_inset Quotes erd
\end_inset 

.
 If the host operating system uses a case sensitive file system, the case
 of the with is important.
 To maintain portability across different operating systems, it is best
 to keep the with statements and filenames lower case.
\layout Subsection

Numbers
\layout Standard

gpal uses decimal as its default radix.
 The following table summarizes other supported numeric formats.
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
3 3 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

base
\newline 
general syntax
\newline 
21 decimal written as
\newline 
decimal
\newline 
[0-9]*
\newline 
21
\newline 
hex
\newline 
0x[0-F]*
\newline 
0x15
\layout Subsection

Operators
\layout Standard

gpal supports a full set of operators, based on the C operator set.
 The operators in the following table are arranged in groups of equal precedence
, but the groups are arranged in order of increasing precedence.
 When gpal encounters operators of equal precedence, it always evaluates
 from left to right.
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
23 2 0 0 -1 -1 -1 -1
1 1 0 0
1 1 0 0
1 1 0 0
1 1 0 0
1 0 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

Operator
\newline 
Description
\newline 
=
\newline 
assignment
\newline 
||
\newline 
logical or
\newline 
&&
\newline 
logical and
\newline 
&
\newline 
bitwise and
\newline 
|
\newline 
bitwise or
\newline 
^
\newline 
bitwise exclusive-or
\newline 
<
\newline 
less than
\newline 
>
\newline 
greater than
\newline 
==
\newline 
equals
\newline 
!=
\newline 
not equals
\newline 
>=
\newline 
greater than or equal
\newline 
<=
\newline 
less than or equal
\newline 
<<
\newline 
left shift
\newline 
>>
\newline 
right shift
\newline 
+
\newline 
addition
\newline 
-
\newline 
subtraction
\newline 
*
\newline 
multiplication
\newline 
/
\newline 
division
\newline 
%
\newline 
modulo
\newline 
-
\newline 
negation
\newline 
!
\newline 
logical not
\newline 
~
\newline 
bitwise no
\layout Subsection

Assignment
\layout LyX-Code

<name>['[' <expression> ']']? = <expression>;
\layout Standard

Assignment statements can appear in any statement block.
 <name> must be a variable.
 If the bracket enclosed expression is added it must be an array.
\layout Subsection

Test
\layout LyX-Code

<expression> [ <comparison operator> <expression>]*;
\layout Standard

Test statements can only appear in the expressions of if statements and
 while loops.
 They must evaluate to a boolean.
\layout Section

Statements
\layout Subsection

If
\layout LyX-Code

if <expression> then 
\layout LyX-Code

  <statements> 
\layout LyX-Code

[elsif <expression> then 
\layout LyX-Code

  <statements>]*
\layout LyX-Code

[else 
\layout LyX-Code

  <statements>]? 
\layout LyX-Code

end if;
\layout Standard

The statements in each block are executed if the expression is true.
 Here is an example:
\layout LyX-Code

if i < 10 then
\layout LyX-Code

  j = 5;
\layout LyX-Code

elsif i > 12 then
\layout LyX-Code

  j = 10;
\layout LyX-Code

elsif i > 14 then
\layout LyX-Code

  j = 14;
\layout LyX-Code

else 
\layout LyX-Code

  j = 0;
\layout LyX-Code

end if;
\layout Subsection

Case
\layout LyX-Code

case <name> is
\layout LyX-Code

[when <constant> =>
\layout LyX-Code

  <statements>]*
\layout LyX-Code

[when others =>
\layout LyX-Code

  <statements>]?
\layout LyX-Code

end case;
\layout Standard

If <name> equals any of the <constants> the <statements> are executed.
 If none of the constants match and an others is present, the others statements
 are executed.
 Here is an example:
\layout LyX-Code

case input is
\layout LyX-Code

  when MAXIMUM =>
\layout LyX-Code

    output = 8;
\layout LyX-Code

  when 5 =>
\layout LyX-Code

    output = 4;
\layout LyX-Code

  when 1 =>
\layout LyX-Code

    output = 2;
\layout LyX-Code

  when others => 
\layout LyX-Code

    output = 0;
\layout LyX-Code

end case;
\layout Subsection

Loop
\layout LyX-Code

loop 
\layout LyX-Code

  <statements> 
\layout LyX-Code

end loop;
\layout Standard

The statements in the block are executed in an infinite loop.
 Here is an example:
\layout LyX-Code

loop
\layout LyX-Code

  j = j + 1;
\layout LyX-Code

  if j = 100 then
\layout LyX-Code

    return 0;
\layout LyX-Code

  end if;
\layout LyX-Code

end loop;
\layout Subsection

While
\layout LyX-Code

while <expression>
\layout LyX-Code

  loop 
\layout LyX-Code

    <statements> 
\layout LyX-Code

  end loop;
\layout Standard

The statements in the block are executed while <expression> is true.
 Here is an example:
\layout LyX-Code

while j < 10
\layout LyX-Code

  loop
\layout LyX-Code

    j = j + 1;
\layout LyX-Code

  end loop;
\layout Subsection

For
\layout LyX-Code

for <name> in <start_expression> to <end_expression>
\layout LyX-Code

  loop 
\layout LyX-Code

    <statements> 
\layout LyX-Code

  end loop;
\layout Standard

<name> is set to <start_expression>.
 It is then incremented each time the block of statements are executed.
 It continues until <name> reaches <end_expression>.
 Here is an example:
\layout LyX-Code

for i in 0 to 10
\layout LyX-Code

  loop
\layout LyX-Code

    buffer[i] = 0;
\layout LyX-Code

  end loop;
\layout Subsection

Assembly
\layout LyX-Code

asm 
\layout LyX-Code

  <asm statements> 
\layout LyX-Code

end asm;
\layout Standard

Unmodified <asm statements> are copied to the assembly file output.
 The syntax of <asm statements> must be compatible with gpasm.
\layout Subsection

Return
\layout LyX-Code

return <expression>;
\layout Standard

Evaluate the <expression>, place it in the return register, and return from
 the function.
\layout Subsection

Null
\layout LyX-Code

null;
\layout Standard

Execute a NOP.
 This is a little different from NULL statements in most languages.
 It is typically is used in statement block that was intentionally left
 blank and no code is generated.
 
\layout Subsection

Pragma
\layout LyX-Code

pragma <anything>;
\layout Standard

Pragmas provide data to compiler which is outside of its legal syntax.
 The table below summarizes the pragmas available:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
6 3 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

Name
\newline 
Format
\newline 
Description
\newline 
Code Address
\newline 
code_address = <constant>
\newline 
Make the code section absolute at address <constant>.
\newline 
Code Section
\newline 
code_section = 
\begin_inset Quotes eld
\end_inset 

<name>
\begin_inset Quotes eld
\end_inset 


\newline 
Set the code section name to <name>.
\newline 
Processor
\newline 
processor = 
\begin_inset Quotes eld
\end_inset 

<name>
\begin_inset Quotes eld
\end_inset 


\newline 
Set the processor name to <name>.
\newline 
Udata Address
\newline 
udata_address = <constant>
\newline 
Make the udata section absolute at address <constant>.
\newline 
Udata Section
\newline 
udata_section= 
\begin_inset Quotes eld
\end_inset 

<name>
\begin_inset Quotes eld
\end_inset 


\newline 
Set the udata section name to <name>.
\layout Section

Declarations
\layout Subsection

Variables
\layout Standard

Symbols whose values change during runtime are referred to as variables.
 Because variables change value during run time they are stored in data
 memory.
 An expression specifies its initial value.
 A variable is declared as follows:
\layout LyX-Code

<name> : <type> [= <expression>]?;
\layout Standard

Here is an example:
\layout LyX-Code

gain : short = 10;
\layout Subsection

Constants
\layout Standard

Compile time symbols whose values do not change are referred to as constants.
 A constant is declared as follows:
\layout LyX-Code

<name> : constant = <expression>;
\layout Standard

Here is an example:
\layout LyX-Code

filter_offset : constant = 0x1434;
\layout Section

Subprograms
\layout Subsection

Procedure
\layout LyX-Code

procedure <name> ( [<arg name> : [in|out|inout] <type>]* ) is
\layout LyX-Code

  <declarations>
\layout LyX-Code

begin
\layout LyX-Code

  <statements>
\layout LyX-Code

end procedure;
\layout Standard

This creates a block of executable code that starts at <name>.
 The procedure can be called from other subprograms within any statement
 block, but they can not be called from within an expression.
\layout Standard

Permanent storage is allocated for each procedure argument.
 Data is passed to and from the procedure through that storage.
 The calling subprogram puts data into the arguments and reads from the
 arguments based the direction specified in the procedure definition.
 The direction is ignored by the procedure.
 All the arguments can be read from and written to.
 
\layout Standard

Local constants and variables are declared in <declarations>.
 Any variables declared in this region may be permanent or overlayed with
 data from other subprograms.
\layout Subsection

Function
\layout LyX-Code

function <name> ( [<arg name> : [in|out|inout] <type>]* ) return type is
\layout LyX-Code

  <declarations>
\layout LyX-Code

begin
\layout LyX-Code

  <statements>
\layout LyX-Code

end function;
\layout Standard

This creates a block of executable code that starts at <name>.
 The function can only be called from within expressions.
\layout Standard

Like procedures in many respects, except a value is returned.
 This value is used in the expression.
\layout Section

Files
\layout Subsection

Module
\layout LyX-Code

module <name> is
\layout LyX-Code

  <subprogram definitions|variable definitions|constants|types>
\layout LyX-Code

end module;
\layout Standard

The module defines a related group of subprograms and data that will be
 placed in the same page or bank.
 One module is placed in each .pal file.
 Typically the filename will be the same as <name> with the .pal extension
 added.
 Groups of modules are compiled and linked to gather to make the executable.
\layout Subsection

Public
\layout LyX-Code

\layout LyX-Code

public <name> is
\layout LyX-Code

  <subprograms declarations|variable declarations|constants|types>
\layout LyX-Code

end public;
\layout Standard

The public declares which portions of its module will be public.
 It also provides information about the interface to the module's subprograms
 and data.
 One public is placed in each .pub file.
 The filename must be the same as <name> with the .pub extension added.
 The <name> must also match the <name> of its module if one exists.
 When the module is compiled, it will scan its public file to verify that
 the declarations in the file match its subprograms and data.
\layout Subsection

With
\layout LyX-Code

with <name>;
\layout LyX-Code

\layout Standard

The with statement is the only statement allowed outside a module or public.
 It tells the compiler to add the data from the public in the file <name>.pub
 to its symbol tables.
 This will allow access to that module's subprograms and data.
\layout Section

Code Generation
\layout Subsection

Phases
\layout Subsubsection

Parse
\layout Standard

The input files are parsed and stored in memory in a tree format.
 Constructs are replaced with common structures.
 For example for and while loops are converted into conditional loops with
 initialization statements and increment statements.
\layout Subsubsection

Analyze
\layout Standard

The syntax and semantics of the tree are checked.
 Most of the errors are generated during this phase.
\layout Subsubsection

Optimize
\layout Standard

The tree is modified to generate better code.
\layout Subsubsection

Code Generation
\layout Standard

The tree is written to an asm file, so it can be assembled and linked.
 In the future, this stage will generate a low level icode.
 That code will be further optimized before it is written to the asm file.
\layout Subsection

Expression Evaluation
\layout Standard

Most compilers are a stack machine, accumulator machine, or a register machine.
 Not all of the machines are good for every target processor.
 Some options either won't work or aren't optimal.
 Because of the limited resources on PICs, the absence of stack manipulation
 instructions, and the fact that some instructions can only target the Wreg.
 An accumulator machine is the best choice for PICs.
 It is the choice that gpal uses.
 For example:
\layout LyX-Code

i = (x + 3) & 4;
\layout Standard

will generate the following pseudo code:
\layout LyX-Code

Wreg = x;
\layout LyX-Code

Wreg = Wreg + 3;
\layout LyX-Code

Wreg = Wreg & 4;
\layout LyX-Code

i = Wreg;
\layout Standard

If necessary, intermediate values are stored in data memory.
 For byte sized operations the Wreg is used.
 For larger sized operations, a section of data memory is used as the accumulato
r.
 
\layout Subsection

COFF sections
\layout Standard

All the executable code in a module is placed in one COFF section.
 This guarantees that code will be on the same page, so no page switching
 is required.
 the code section name is specified using the code_section pragma.
 If that pragma isn't used a default name is used.
\layout Standard

Similarly all data memory is placed in one COFF section.
 This too reduces the number of bank switches when accessing local data.
\layout Subsection

Name mangling
\layout Standard

gpal uses a hierarchical name space.
 The module name is specified in all inter-module accesses.
 So to write to memory 
\begin_inset Quotes eld
\end_inset 

clock
\begin_inset Quotes erd
\end_inset 

 in the local module: 
\layout LyX-Code

clock = 0;
\layout Standard

to write to memory 
\begin_inset Quotes eld
\end_inset 

clock
\begin_inset Quotes erd
\end_inset 

 in module 
\begin_inset Quotes eld
\end_inset 

time
\begin_inset Quotes erd
\end_inset 

:
\layout LyX-Code

time.clock = 0;
\layout Standard

To prevent collisions when compiling and linking all symbols are mangled
 in the asm output of gpal.
 It takes the form:
\layout LyX-Code

<module>.<subprogram>.<local data>
\layout Standard

So, local data 
\begin_inset Quotes eld
\end_inset 

index
\begin_inset Quotes erd
\end_inset 

 in procedure 
\begin_inset Quotes eld
\end_inset 

pop_stack
\begin_inset Quotes erd
\end_inset 

 in module 
\begin_inset Quotes eld
\end_inset 

stack
\begin_inset Quotes erd
\end_inset 

 is given the name 
\begin_inset Quotes eld
\end_inset 

stack.pop_stack.index
\begin_inset Quotes erd
\end_inset 

.
\layout Section

Coding Suggestions
\layout Standard

The following suggestions will help to generate smaller faster target code.
 
\layout Subsection

Use uint8 types
\layout Standard

PICs are unsigned 8 bit machines.
 To do anything beyond that requires more memory and more instruction cycles.
 So use uint8 for as many arguments and data as possible.
 
\layout Subsection

Keep data private
\layout Standard

Any subprogram or data in the public file will make the corresponding object
 public.
 When an object is public fewer compile time optimizations can be done.
 For example, if public data is defined in a module, but not used in that
 module, it can't be removed.
 Another module may access that data.
 So put as few subprogram and data declarations in the public file as possible.
 
\layout Subsection

Group related subprograms and data in one module
\layout Standard

Any time data is accessed in another module, it could require a bank switch.
 Minimizing switches will help to reduce code size and increase speed.
 
\layout Subsection

Name COFF sections
\layout Standard

Before relocating sections, gplink will combine all like named sections
 into one larger section.
 Sections can not cross page or bank boundaries, so inter section accesses
 don't require bank or page switches.
 To name the sections use the code_section and udata_section pragmas.
 This will group the code together.
 If the code is needed on a specific page or bank, create a logical definition
 in your linker script.
\layout Subsection

Don' t use absolute sections
\layout Standard

gpal provides the ability to specify the address of the code or udata of
 the current module.
 The feature is provided for a limited set of cases were the address must
 be known.
 Unfortunately, it limits the choices the linker can make when relocating
 sections.
 At worst it may make the design not fit in the available memory.
 It also requires extra effort on the part of the user.
\layout Subsection

Use multiple module implementations
\layout Standard

The public file defines the interface to a module.
 The name of the public and its file must match, so it can be found.
 There is no requirement of module name to match the file name.
 This makes it possible for multiple modules with the same interface to
 exist.
 You select the module to use when the project is linked.
 For example you could have math_fast.pal and math_small.pal that both contain
 a math module.
 One written to execute fast and the other written to be small in memory.
\layout Chapter

gpasm
\layout Section

Running gpasm
\begin_inset LatexCommand \index{gpasm options}

\end_inset 


\layout Standard

The general syntax for running gpasm is
\layout LyX-Code

gpasm [options] asm-file
\layout Standard

Where options can be one of:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
19 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
0 0 1 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "4in" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 1 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Option
\newline 
Meaning
\newline 
a <format>
\newline 
Produce 
\begin_inset LatexCommand \index{hex file}

\end_inset 

hex file in one of four formats: inhx8m, inhx8s, inhx16, inhx32 (the default).
\newline 
c
\newline 
Output a relocatable object
\newline 
d symbol[=value] 
\newline 
Equivalent to 
\begin_inset Quotes eld
\end_inset 

#define <symbol> <value>
\begin_inset Quotes erd
\end_inset 

.
\newline 
e [ON|OFF]
\newline 
Expand macros in listing file.
\newline 
h
\newline 
Display the help message.
\newline 
i
\newline 

\begin_inset LatexCommand \index{case}

\end_inset 

Ignore case in source code.
 By default gpasms to treats 
\begin_inset Quotes eld
\end_inset 

fooYa
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

FOOYA
\begin_inset Quotes erd
\end_inset 

 as being different.
\newline 
I <directory>
\newline 
Specify an include directory.
\newline 
l
\newline 
List the supported processors.
\newline 
L
\newline 
Ignore nolist directives.
\newline 
m
\newline 
Memory dump.
\newline 
n
\newline 
Use DOS style newlines (CRLF) in hex file.
 This option is disabled on win32 systems.
\newline 
o <file>
\newline 
Alternate name of hex output file.
\newline 
p<processor> 
\newline 
Select target processor.
\newline 
q
\newline 
Quiet
\newline 
r <radix>
\newline 
Set the 
\begin_inset LatexCommand \index{radix}

\end_inset 

radix, i.e.
 the number base that gpasm uses when interpreting numbers.
\newline 

\newline 
<radix> can be one of 
\begin_inset Quotes eld
\end_inset 

oct
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

dec
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

hex
\begin_inset Quotes erd
\end_inset 

 for bases eight, ten, and sixteen respectively.
 Default is 
\begin_inset Quotes eld
\end_inset 

hex
\begin_inset Quotes erd
\end_inset 

.
\newline 
w [ 0 | 1 | 2]
\newline 
Set the message level.
\newline 
v
\newline 
Print gpasm version information and exit.
\layout Standard

Unless otherwise specified, gpasm removes the 
\begin_inset Quotes eld
\end_inset 

.asm
\begin_inset Quotes erd
\end_inset 

 suffix from its input file, replacing it with 
\begin_inset Quotes eld
\end_inset 

.lst
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

.hex
\begin_inset Quotes erd
\end_inset 

 for the list and hex output files respectively.
 On most modern operating systems case is significant in filenames.
 For this reason you should ensure that filenames are named consistently,
 and that the 
\begin_inset Quotes eld
\end_inset 

.asm
\begin_inset Quotes erd
\end_inset 

 suffix on any source file is in lower case.
\layout Standard

gpasm always produces a 
\begin_inset Quotes eld
\end_inset 

.lst
\begin_inset Quotes erd
\end_inset 

 file.
 If it runs without errors, it also produces a 
\begin_inset Quotes eld
\end_inset 

.hex
\begin_inset Quotes erd
\end_inset 

 file or a 
\begin_inset Quotes eld
\end_inset 

.o
\begin_inset Quotes erd
\end_inset 

 file.
\layout Subsection

Using gpasm with 
\begin_inset Quotes eld
\end_inset 

make
\begin_inset Quotes erd
\end_inset 


\begin_inset LatexCommand \index{make}

\end_inset 


\layout Standard

On most operating systems, you can build a project using the make utility.
 To use gpasm with make, you might have a 
\begin_inset Quotes eld
\end_inset 

makefile
\begin_inset Quotes erd
\end_inset 

 like this:
\layout LyX-Code

tree.hex: tree.asm treedef.inc
\layout LyX-Code

        gpasm tree.asm
\layout Standard

This will rebuild 
\begin_inset Quotes eld
\end_inset 

tree.hex
\begin_inset Quotes erd
\end_inset 

 whenever either of the 
\begin_inset Quotes eld
\end_inset 

tree.asm
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

treedef.inc
\begin_inset Quotes erd
\end_inset 

 files change.
 A more comprehensive example of using gpasm with makefiles is included
 as example1 in the gpasm source distribution.
\layout Subsection

Dealing with errors
\begin_inset LatexCommand \index{error file}

\end_inset 


\layout Standard

gpasm doesn't specifically create an error file.
 This can be a problem if you want to keep a record of errors, or if your
 assembly produces so many errors that they scroll off the screen.
 To deal with this if your shell is 
\begin_inset LatexCommand \index{sh}

\end_inset 


\begin_inset Quotes eld
\end_inset 

sh
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset LatexCommand \index{bash}

\end_inset 


\begin_inset Quotes eld
\end_inset 

bash
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset LatexCommand \index{ksh}

\end_inset 


\begin_inset Quotes eld
\end_inset 

ksh
\begin_inset Quotes erd
\end_inset 

, you can do something like:
\layout LyX-Code

gpasm tree.asm 2>&1 | tee tree.err
\layout Standard

This redirects standard error to standard output (
\begin_inset Quotes eld
\end_inset 

2>&1
\begin_inset Quotes erd
\end_inset 

), then pipes this output into 
\begin_inset Quotes eld
\end_inset 


\begin_inset LatexCommand \index{tee}

\end_inset 

tee
\begin_inset Quotes erd
\end_inset 

, which copies it input to 
\begin_inset Quotes eld
\end_inset 

tree.err
\begin_inset Quotes erd
\end_inset 

, and then displays it.
\layout Section

Syntax
\layout Subsection

File structure
\layout Standard

gpasm source files consist of a series of lines.
 Lines can contain a 
\begin_inset LatexCommand \index{labels}

\end_inset 

label (starting in column 1) or an operation (starting in any column after
 1), both, or neither.
 
\begin_inset LatexCommand \index{comments}

\end_inset 

Comments follow a 
\begin_inset Quotes eld
\end_inset 

;
\begin_inset Quotes erd
\end_inset 

 character, and are treated as a newline.
 Labels may be any series of the letters A-z, digits 0-9, and the underscore
 (
\begin_inset Quotes eld
\end_inset 

_
\begin_inset Quotes erd
\end_inset 

); they may not begin with a digit.
 Labels may be followed by a colon (
\begin_inset Quotes eld
\end_inset 

:
\begin_inset Quotes erd
\end_inset 

).
\layout Standard

An operation is a single identifier (the same rules as for a label above)
 followed by a space, and a comma-separated list of parameters.
 For example, the following are all legal source lines:
\layout LyX-Code

                              ; Blank line
\newline 
loop    sleep                 ; Label and operation
\newline 
        incf    6,1           ; Operation with 2 parameters
\newline 
        goto    loop          ; Operation with 1 parameter
\layout Subsection

Expressions
\layout Standard

gpasm supports a full set of 
\begin_inset LatexCommand \index{operators}

\end_inset 

operators, based on the C operator set.
 The operators in the following table are arranged in groups of equal precedence
, but the groups are arranged in order of increasing precedence.
 When gpasm encounters operators of equal precedence, it always evaluates
 from left to right.
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
26 2 0 0 -1 -1 -1 -1
1 1 0 0
1 1 0 0
1 1 0 0
1 1 0 0
1 0 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 0 0 0
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

Operator
\newline 
Description
\newline 
=
\newline 
assignment
\newline 
||
\newline 
logical or
\newline 
&&
\newline 
logical and
\newline 
&
\newline 
bitwise and
\newline 
|
\newline 
bitwise or
\newline 
^
\newline 
bitwise exclusive-or
\newline 
<
\newline 
less than
\newline 
>
\newline 
greater than
\newline 
==
\newline 
equals
\newline 
!=
\newline 
not equals
\newline 
>=
\newline 
greater than or equal
\newline 
<=
\newline 
less than or equal
\newline 
<<
\newline 
left shift
\newline 
>>
\newline 
right shift
\newline 
+
\newline 
addition
\newline 
-
\newline 
subtraction
\newline 
*
\newline 
multiplication
\newline 
/
\newline 
division
\newline 
%
\newline 
modulo
\newline 
UPPER
\newline 
upper byte
\newline 
HIGH
\newline 
high byte
\newline 
LOW
\newline 
low byte
\newline 
-
\newline 
negation
\newline 
!
\newline 
logical not
\newline 
~
\newline 
bitwise no
\layout Standard
\align left 
Any symbol appearing in column 1 may be assigned a value using the assignment
 operator (=) in the previous table.
 Additionally, any value previously assigned may be modified using one of
 the operators in the table below.
 Each of these operators evaluates the current value of the symbol and then
 assigns a new value based on the operator.
 
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
14 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

Operator
\newline 
Description
\newline 
=
\newline 
assignment
\newline 
++
\newline 
increment by 1
\newline 
--
\newline 
decrement by 1
\newline 
+=
\newline 
increment
\newline 
-=
\newline 
decrement
\newline 
*=
\newline 
multiply
\newline 
/=
\newline 
divide
\newline 
%=
\newline 
modulo
\newline 
<<=
\newline 
left shift
\newline 
>>=
\newline 
right shift
\newline 
&=
\newline 
bitwise and
\newline 
|=
\newline 
bitwise or
\newline 
^=
\newline 
bitwise exclusive-or
\layout Subsection

Numbers
\begin_inset LatexCommand \index{radix}

\end_inset 


\layout Standard


\begin_inset LatexCommand \label{sec:numbers}

\end_inset 

gpasm gives you several ways of specifying numbers.
 You can use a syntax that uses an initial character to indicate the number's
 base.
 The following table summarizes the alternatives.
 Note the C-style option for specifying hexadecimal numbers.
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
6 3 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

base
\newline 
general syntax
\newline 
21 decimal written as
\newline 
binary
\newline 
B'[01]*'
\newline 
B'10101'
\newline 
octal
\newline 
O'[0-7]*'
\newline 
O'25'
\newline 
decimal
\newline 
D'[0-9]*'
\newline 
D'21'
\newline 
hex
\newline 
H'[0-F]*'
\newline 
H'15'
\newline 
hex
\newline 
0x[0-F]*
\newline 
0x15
\layout Standard

When you write a number without a specifying prefix such as 
\begin_inset Quotes eld
\end_inset 

45
\begin_inset Quotes erd
\end_inset 

, gpasm uses the current radix (base) to interpret the number.
 You can change this radix with the RADIX directive, or with the 
\begin_inset Quotes eld
\end_inset 

-r
\begin_inset Quotes erd
\end_inset 

 option on gpasm's command-line.
 If you do not start hexadecimal numbers with a digit, gpasm will attempt
 to interpret what you've written as an identifier.
 For example, instead of writing C2, write either 0C2, 0xC2 or H'C2'.
\layout Standard

Case is not significant when interpreting numbers: 0ca, 0CA, h'CA' and H'ca'
 are all equivalent.
\layout Standard

Several legacy mpasm number formats are also supported.
 These formats have various shortcomings, but are still supported.
 The table below summarizes them.
 
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
8 3 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

base
\newline 
general syntax
\newline 
21 decimal written as
\newline 
binary
\newline 
[01]*b
\newline 
10101b
\newline 
octal
\newline 
q'[0-7]*'
\newline 
q'25'
\newline 
octal
\newline 
[0-7]*o
\newline 
25o
\newline 
octal
\newline 
[0-7]*q
\newline 
25q
\newline 
decimal
\newline 
0-9]*d
\newline 
21d
\newline 
decimal
\newline 
.[0-9]*
\newline 
.21
\newline 
hex
\newline 
[0-F]*h
\newline 
15h
\layout Standard

You can write the 
\begin_inset LatexCommand \index{ASCII}

\end_inset 

ASCII code for a 
\begin_inset LatexCommand \index{character}

\end_inset 

character X using 'X', or A'X'.
 
\layout Subsection

Preprocessor
\layout Standard


\begin_inset LatexCommand \index{include}

\end_inset 

A line such as:
\layout LyX-Code

include foo.inc
\layout Standard

will make gpasm fetch source lines from the file 
\begin_inset Quotes eld
\end_inset 

foo.inc
\begin_inset Quotes erd
\end_inset 

 until the end of the file, and then return to the original source file
 at the line following the include.
\layout Standard

Lines beginning with a 
\begin_inset Quotes eld
\end_inset 

#
\begin_inset Quotes erd
\end_inset 

 are preprocessor directives, and are treated differently by gpasm.
 They may contain a 
\begin_inset Quotes eld
\end_inset 

#define
\begin_inset Quotes erd
\end_inset 

, or a 
\begin_inset Quotes eld
\end_inset 

#undefine
\begin_inset Quotes erd
\end_inset 

 directive.
\layout Standard

Once gpasm has processed a line such as:
\layout LyX-Code

#define X Y
\layout Standard

every subsequent occurrence of X is replaced with Y, until the end of file
 or a line
\layout LyX-Code

#undefine X
\layout Standard

appears.
\layout Standard

The preprocessor will replace an occurance of #v(expression) in a symbol
 with the value of 
\begin_inset Quotes eld
\end_inset 

expression
\begin_inset Quotes erd
\end_inset 

 in decimal.
 In the following expression:
\layout LyX-Code

number equ 5
\layout LyX-Code

label_#v( (number +1) * 5 )_suffix equ 0x10
\layout Standard

gpasm will place the symbol 
\begin_inset Quotes eld
\end_inset 

label_30_suffix
\begin_inset Quotes erd
\end_inset 

 with a value of 0x10 in the symbol table.
\layout Standard

The preprocessor in gpasm is only 
\shape italic 
like
\shape default 
 the C preprocessor; its syntax is rather different from that of the C preproces
sor.
 gpasm uses a simple internal preprocessor to implement 
\begin_inset Quotes eld
\end_inset 

include
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

#define
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

#undefine
\begin_inset Quotes erd
\end_inset 

.
\layout Subsection

Processor header files
\layout Standard

gputils distributes the Microchip processor header files.
 These files contain processor specific data that is helpful in developing
 PIC applications.
 The location of these files is reported in the gpasm help message.
 Use the INCLUDE directive to utilize the appropriate file in your source
 code.
 Only the name of the file is required.
 gpasm will search the default path automatically.
 
\layout Section

Directives
\layout Subsection

Code generation
\layout Standard

In absolute mode, use the ORG directive to set the PIC memory location where
 gpasm will start assembling code.
 If you don't specify an address with ORG, gpasm assumes 0x0000.
 In relocatable mode, use the CODE directive.
\layout Subsection

Configuration
\layout Standard

You can choose the fuse settings for your PIC implementation using the __CONFIG
 directive, so that the hex file set the fuses explicitly.
 Naturally you should make sure that these settings match your PIC hardware
 design.
\layout Standard

The __MAXRAM and __BADRAM directives specify which RAM locations are legal.
 These directives are mostly used in processor-specific configuration files.
\layout Subsection

Conditional assembly
\layout Standard

The IF, IFNDEF, IFDEF, ELSE and ENDIF directives enable you to assemble
 certain sections of code only if a condition is met.
 In themselves, they do not cause gpasm to emit any PIC code.
 The example in section 
\begin_inset LatexCommand \ref{sec:macros}

\end_inset 

 for demonstrates conditional assembly.
\layout Subsection

Macros
\layout Standard


\begin_inset LatexCommand \label{sec:macros}

\end_inset 

gpasm supports a simple macro scheme; you can define and use macros like
 this:
\layout LyX-Code

any     macro parm
\newline 
        movlw parm
\layout LyX-Code

        endm
\layout LyX-Code

...
\layout LyX-Code

        any   33
\layout Standard

A more useful example of some macros in use is:
\layout LyX-Code

; Shift reg left, result (w or f) in 'dst'
\layout LyX-Code

slf     macro   reg,dst
\layout LyX-Code

        clrc
\layout LyX-Code

        rlf     reg,f
\layout LyX-Code

endm
\layout LyX-Code

 
\layout LyX-Code

; Scale W by 
\begin_inset Quotes eld
\end_inset 

factor
\begin_inset Quotes erd
\end_inset 

.
  Result in 
\begin_inset Quotes eld
\end_inset 

reg
\begin_inset Quotes erd
\end_inset 

, W unchanged.
\layout LyX-Code

scale   macro   reg, factor
\layout LyX-Code

        if (factor == 1)
\layout LyX-Code

            movwf reg                 ; 1 X is easy
\layout LyX-Code

        else
\layout LyX-Code

            scale   reg, (factor / 2) ; W * (factor / 2)
\layout LyX-Code

            slf     reg,f             ; double reg
\layout LyX-Code

            if ((factor & 1) == 1)    ; if lo-bit set ..
\layout LyX-Code

                addwf   reg,f         ; ..
 add W to reg
\layout LyX-Code

            endif
\layout LyX-Code

        endif
\layout LyX-Code

endm
\layout Standard

This recursive macro generates code to multiply W by a constant 
\begin_inset Quotes eld
\end_inset 

factor
\begin_inset Quotes erd
\end_inset 

, and stores the result in 
\begin_inset Quotes eld
\end_inset 

reg
\begin_inset Quotes erd
\end_inset 

.
 So writing:
\layout LyX-Code

        scale   tmp,D'10'
\layout Standard

is the same as writing:
\layout LyX-Code

        movwf   tmp      ; tmp = W
\layout LyX-Code

        clrc
\layout LyX-Code

        rlf     tmp,f    ; tmp = 2 * W
\layout LyX-Code

        clrc
\layout LyX-Code

        rlf     tmp,f    ; tmp = 4 * W
\layout LyX-Code

        addwf   tmp,f    ; tmp = (4 * W) + W = 5 * W
\layout LyX-Code

        clrc
\layout LyX-Code

        rlf     tmp,f    ; tmp = 10 * W
\layout Subsection

$
\layout Standard

$ expands to the address of the instruction currently being assembled.
 If it's used in a context other than an instruction, such as a conditional,
 it expands to the address the next instruction would occupy, since the
 assembler's idea of current address is incremented after an instruction
 is assembled.
  $ may be manipulated just like any other number:
\layout LyX-Code

$
\layout LyX-Code

$ + 1
\layout LyX-Code

$ - 2
\layout Standard

and can be used as a shortcut for writing loops without labels.
\layout LyX-Code

LOOP:  BTFSS flag,0x00
\layout LyX-Code

       GOTO LOOP
\layout LyX-Code

\layout LyX-Code

       BTFSS flag,0x00
\layout LyX-Code

       GOTO  $ - 1
\layout Subsection

Suggestions for structuring your code
\layout Standard


\begin_inset LatexCommand \label{sec:structuring}

\end_inset 

Nested IF operations can quickly become confusing.
 Indentation is one way of making code clearer.
 Another way is to add braces on IF, ELSE and ENDIF, like this:
\layout LyX-Code

        IF (this) ; {
\layout LyX-Code

          ...
\layout LyX-Code

        ELSE      ; }{
\layout LyX-Code

          ...
\layout LyX-Code

        ENDIF     ; }
\layout Standard

After you've done this, you can use your text editor's show-matching-brace
 to check matching parts of the IF structure.
 In vi this command is 
\begin_inset Quotes eld
\end_inset 

%
\begin_inset Quotes erd
\end_inset 

, in emacs it's M-C-f and M-C-b.
\layout Subsection

Directive summary
\begin_inset LatexCommand \label{sec:directivesummary}

\end_inset 


\layout Subsection*

__BADRAM
\begin_inset LatexCommand \index{BADRAM}

\end_inset 


\layout LyX-Code

__BADRAM <expression> [, <expression]*
\layout Standard

Instructs gpasm that it should generate an error if there is any use of
 the given RAM locations.
 Specify a range of addresses with <lo>-<hi>.
 See any processor-specific header file for an example.
\layout Standard

See also: __MAXRAM
\layout Subsection*

__CONFIG
\begin_inset LatexCommand \index{CONFIG}

\end_inset 


\layout LyX-Code

__CONFIG <expression>
\layout Standard

Sets the PIC processor's configuration fuses.
\layout Subsection*

__IDLOCS
\begin_inset LatexCommand \index{IDLOCS}

\end_inset 


\layout LyX-Code

__IDLOCS <expression> or __IDLOCS <expression1>,<expression2>
\layout Standard

Sets the PIC processor's identification locations.
 For 12 and 14 bit processors, the four id locations are set to the hexadecimal
 value of expression.
 For 18cxx devices idlocation expression1 is set to the hexadecimal value
 of expression2.
\layout Subsection*

__MAXRAM
\begin_inset LatexCommand \index{MAXRAM}

\end_inset 


\layout LyX-Code

__MAXRAM <expression>
\layout Standard

Instructs gpasm that an attempt to use any RAM location above the one specified
 should be treated as an error.
 See any processor specific header file for an example.
\layout Standard

See also: __BADRAM
\layout Subsection*

BANKISEL
\begin_inset LatexCommand \index{BANKISEL}

\end_inset 


\layout LyX-Code

BANKISEL <label>
\layout Standard

This directive generates bank selecting code for indirect access of the
 address specified by <label>.
 The directive is not available for all devices.
 It is only available for 14 bit and 16 bit devices.
 For 14 bit devices, the bank selecting code will set/clear the IRP bit
 of the STATUS register.
 It will use MOVLB or MOVLR in 16 bit devices.
\layout Standard

See also: BANKSEL, PAGESEL
\layout Subsection*

BANKSEL
\begin_inset LatexCommand \index{BANKSEL}

\end_inset 


\layout LyX-Code

BANKSEL <label>
\layout Standard

This directive generates bank selecting code to set the bank to the bank
 containing <label>.
 The bank selecting code will set/clear bits in the FSR for 12 bit devices.
 It will set/clear bits in the STATUS register for 14 bit devices.
 It will use MOVLB or MOVLR in 16 bit devices.
 MOVLB will be used for enhanced 16 bit devices.
\layout Standard

See also: BANKISEL, PAGESEL
\layout Subsection*

CBLOCK
\begin_inset LatexCommand \index{CBLOCK}

\end_inset 


\layout LyX-Code

CBLOCK [<expression>]
\layout LyX-Code

       <label>[:<increment>][,<label>[:<increment>]]
\layout LyX-Code

ENDC
\layout Standard

Marks the beginning of a block of constants <label>.
 gpasm allocates values for symbols in the block starting at the value <expressi
on> given to CBLOCK.
 An optional <increment> value leaves space after the <label> before the
 next <label>.
\layout Standard

See also: EQU
\layout Subsection*

CODE
\begin_inset LatexCommand \index{CODE}

\end_inset 


\layout LyX-Code

<label> CODE <expression>
\layout Standard

Only for relocatable mode.
 Creates a new machine code section in the output object file.
 <label> specifies the name of the section.
 If <label> is not specified the default name 
\begin_inset Quotes eld
\end_inset 

.code
\begin_inset Quotes erd
\end_inset 

 will be used.
 <expression> is optional and specifies the absolute address of the section.
 
\layout Standard

See also: IDATA, UDATA
\layout Subsection*

CONSTANT
\begin_inset LatexCommand \index{CONSTANT}

\end_inset 


\layout LyX-Code

CONSTANT <label>=<expression> [, <label>=<expression>]*
\layout Standard

Permanently assigns the value obtained by evaluating <expression> to thesymbol
 <label>.
 Similar to SET and VARIABLE, except it can not be changed once assigned.
\layout Standard

See also: EQU, SET, VARIABLE
\layout Subsection*

DA
\begin_inset LatexCommand \index{DA}

\end_inset 


\layout LyX-Code

<label> DA <expression> [, <expression]*
\layout Standard

Stores Strings in program memory.
 The data is stored as one 14 bit word representing two 7 bit ASCII characters.
\layout Standard

See also: DT
\layout Subsection*

DATA
\begin_inset LatexCommand \index{DATA}

\end_inset 


\layout LyX-Code

DATA <expression> [, <expression]*
\layout Standard

Generates the specified data.
\layout Standard

See also: DA, DB, DE, DW
\layout Subsection*

DB
\begin_inset LatexCommand \index{DB}

\end_inset 


\layout LyX-Code

<label> DB <expression> [, <expression]*
\layout Standard

Declare data of one byte.
 The values are packed two per word.
\layout Standard

See also: DA, DATA, DE, DW
\layout Subsection*

DE
\begin_inset LatexCommand \index{DE}

\end_inset 


\layout LyX-Code

<label> DE <expression> [, <expression]*
\layout Standard

Define EEPROM data.
 Each character in a string is stored in a separate word.
\layout Standard

See also: DA, DATA, DB, DW
\layout Subsection*

DT
\begin_inset LatexCommand \index{DT}

\end_inset 


\layout LyX-Code

DT <expression> [, <expression]*
\layout Standard

Generates the specified data as bytes in a sequence of RETLW instructions.
\layout Standard

See also: DATA
\layout Subsection*

DW
\begin_inset LatexCommand \index{DW}

\end_inset 


\layout LyX-Code

<label> DW <expression> [, <expression]*
\layout Standard

Declare data of one word.
\layout Standard

See also: DA, DATA, DB, DW
\layout Subsection*

ELSE
\begin_inset LatexCommand \index{ELSE}

\end_inset 


\layout LyX-Code

ELSE
\layout Standard

Marks the alternate section of a conditional assembly block.
\layout Standard

See also: IF, IFDEF, IFNDEF, ELSE, ENDIF
\layout Subsection*

END
\begin_inset LatexCommand \index{END}

\end_inset 


\layout LyX-Code

END
\layout Standard

Marks the end of the source file.
\layout Subsection*

ENDC
\begin_inset LatexCommand \index{ENDC}

\end_inset 


\layout LyX-Code

ENDC
\layout Standard

Marks the end of a CBLOCK.
\layout Standard

See also: CBLOCK
\layout Subsection*

ENDIF
\begin_inset LatexCommand \index{ENDIF}

\end_inset 


\layout LyX-Code

ENDIF
\layout Standard

Ends a conditional assembly block.
\layout Standard

See also: IFDEF, IFNDEF, ELSE, ENDIF
\layout Subsection*

ENDM
\begin_inset LatexCommand \index{ENDM}

\end_inset 


\layout LyX-Code

ENDM
\layout Standard

Ends a macro definition.
\layout Standard

See also: MACRO
\layout Subsection*

ENDW
\begin_inset LatexCommand \index{ENDW}

\end_inset 


\layout LyX-Code

ENDW
\layout Standard

Ends a while loop.
\layout Standard

See also: WHILE
\layout Subsection*

EQU
\begin_inset LatexCommand \index{EQU}

\end_inset 


\layout LyX-Code

<label> EQU <expression>
\layout Standard

Permanently assigns the value obtained by evaluating <expression> to the
 symbol <label>.
 Similar to SET and VARIABLE, except it can not be changed once assigned.
\layout Standard

See also: CONSTANT, SET
\layout Subsection*

ERROR
\begin_inset LatexCommand \index{ERROR}

\end_inset 


\layout LyX-Code

ERROR <string>
\layout Standard

Issues an error message.
\layout Standard

See also: MESSG
\layout Subsection*

ERRORLEVEL
\begin_inset LatexCommand \index{ERRORLEVEL}

\end_inset 


\layout LyX-Code

ERRORLEVEL {0 | 1 | 2 | +<msgnum> | -<msgnum>}[, ...]
\layout Standard

Sets the types of messages that are printed.
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
6 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

Setting
\newline 
Affect
\newline 
0
\newline 
Messages, warnings and errors printed.
\newline 
1
\newline 
Warnings and error printed.
\newline 
2
\newline 
Errors printed.
\newline 
-<msgnum>
\newline 
Inhibits the printing of message <msgnum>.
\newline 
+<msgnum>
\newline 
Enables the printing of message <msgnum>.
\layout Standard

See also: LIST
\layout Subsection*

EXTERN
\begin_inset LatexCommand \index{EXTERN}

\end_inset 


\layout LyX-Code

EXTERN <symbol> [ , <symbol> ]*
\layout Standard

Only for relocatable mode.
 Delcare a new symbol that is defined in another object file.
\layout Standard

See also: GLOBAL
\layout Subsection*

EXITM
\begin_inset LatexCommand \index{EXITM}

\end_inset 


\layout LyX-Code

EXITM
\layout Standard

Immediately return from macro expansion during assembly.
\layout Standard

See also: ENDM
\layout Subsection*

EXPAND
\begin_inset LatexCommand \index{EXITM}

\end_inset 


\layout LyX-Code

EXPAND
\layout Standard

Expand the macro in the listing file.
\layout Standard

See also: ENDM
\layout Subsection*

FILL
\begin_inset LatexCommand \index{FILL}

\end_inset 


\layout LyX-Code

<label> FILL <expression>,<count>
\layout Standard

Generates <count> occurrences of the program word or byte <expression>.
 If expression is enclosed by parentheses, expression is a line of assembly.
 
\layout Standard

See also: DATA DW ORG
\layout Subsection*

GLOBAL
\begin_inset LatexCommand \index{GLOBAL}

\end_inset 


\layout LyX-Code

GLOBAL <symbol> [ , <symbol> ]*
\layout Standard

Only for relocatable mode.
 Delcare a symbol as global.
\layout Standard

See also: GLOBAL
\layout Subsection*

IDATA
\begin_inset LatexCommand \index{IDATA}

\end_inset 


\layout LyX-Code

<label> IDATA <expression>
\layout Standard

Only for relocatable mode.
 Creates a new initialized data section in the output object file.
 <label> specifies the name of the section.
 If <label> is not specified the default name 
\begin_inset Quotes eld
\end_inset 

.idata
\begin_inset Quotes erd
\end_inset 

 will be used.
 <expression> is optional and specifies the absolute address of the section.
 Data memory is allocated and the initialization data is placed in ROM.
 The user must provide the code to load the data into memory.
 
\layout Standard

See also: CODE, UDATA
\layout Subsection*

IF
\begin_inset LatexCommand \index{IF}

\end_inset 


\layout LyX-Code

IF <expression>
\layout Standard

Begin a conditional assembly block.
 If the value obtained by evaluating <expression> is true (i.e.
 non-zero), code up to the following ELSE or ENDIF is assembled.
 If the value is false (i.e.
 zero), code is not assembled until the corresponding ELSE or ENDIF.
\layout Standard

See also: IFDEF, IFNDEF, ELSE, ENDIF
\layout Subsection*

IFDEF
\begin_inset LatexCommand \index{IFDEF}

\end_inset 


\layout LyX-Code

IFDEF <symbol>
\layout Standard

Begin a conditional assembly block.
 If <symbol> appears in the symbol table, gpasm assembles the following
 code.
\layout Standard

See also: IF, IFNDEF, ELSE, ENDIF
\layout Subsection*

IFNDEF
\begin_inset LatexCommand \index{IFNDEF}

\end_inset 


\layout LyX-Code

IFNDEF <symbol>
\layout Standard

Begin a conditional assembly block.
 If <symbol>does not appear in the symbol table, gpasm assembles the following
 code.
\layout Standard

See also: IF, IFNDEF, ELSE, ENDIF
\layout Subsection*

LIST
\begin_inset LatexCommand \index{LIST}

\end_inset 


\layout LyX-Code

LIST <expression> [ , <expression> ] *
\layout Standard

Enables output to the list (
\begin_inset Quotes eld
\end_inset 

.lst
\begin_inset Quotes erd
\end_inset 

) file.
 All arguments are interpreted as decimal regardless of the current radix
 setting.
 
\begin_inset Quotes eld
\end_inset 

list n=0
\begin_inset Quotes erd
\end_inset 

 may be used to prevent page breaks in the code section of the list file.
 Other options are listed in the table below:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
10 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
8 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

option
\newline 
description
\newline 
b=nnn
\newline 
Sets the tab spaces
\newline 
f=<format>
\newline 
Set the hex file format.
 Can be inhx8m, inhx8s, inhx16, or inhx32.
\newline 
mm=[ON|OFF]
\newline 
Memory Map on or off
\newline 
n=nnn
\newline 
Sets the number of lines per page
\newline 
p = <symbol>
\newline 
Sets the current processor
\newline 
r= [ oct | dec | hex ]
\newline 
Sets the radix
\newline 
st = [ ON | OFF ]
\newline 
Symbol table dump on or off
\newline 
w=[0 | 1| 2]
\newline 
Sets the message level.
\newline 
x=[ON|OFF]
\newline 
Macro expansion on or off
\layout Standard

See also: NOLIST, RADIX, PROCESSOR
\layout Subsection*

LOCAL
\begin_inset LatexCommand \index{LOCAL}

\end_inset 


\layout LyX-Code

LOCAL <symbol>[[=<expression>], [<symbol>[=<expression>]]*]
\layout Standard

Declares <symbol> as local to the macro that's currently being defined.
 This means that further occurrences of <symbol> in the macro definition
 refer to a local variable, with scope and lifetime limited to the execution
 of the macro.
\layout Standard

See also: MACRO, ENDM
\layout Subsection*

MACRO
\begin_inset LatexCommand \index{MACRO}

\end_inset 


\layout LyX-Code

<label> MACRO [ <symbol> [ , <symbol> ]* ]
\layout Standard

Declares a macro with name <label>.
 gpasm replaces any occurrences of <symbol> in the macro definition with
 the parameters given at macro invocation.
\layout Standard

See also: LOCAL, ENDM
\layout Subsection*

MESSG
\begin_inset LatexCommand \index{MESSG}

\end_inset 


\layout LyX-Code

MESSG <string>
\layout Standard

Writes <string> to the list file, and to the standard error output.
\layout Standard

See also: ERROR
\layout Subsection*

NOEXPAND
\begin_inset LatexCommand \index{NOEXPAND}

\end_inset 


\layout LyX-Code

NOEXPAND
\layout Standard

Turn off macro expansion in the list file.
\layout Standard

See also: EXPAND
\layout Subsection*

NOLIST
\begin_inset LatexCommand \index{NOLIST}

\end_inset 


\layout LyX-Code

NOLIST
\layout Standard

Disables list file output.
\layout Standard

See also: LIST
\layout Subsection*

ORG
\begin_inset LatexCommand \index{ORG}

\end_inset 


\layout LyX-Code

ORG <expression>
\layout Standard

Sets the location at which instructions will be placed.
 If the source file does not specify an address with ORG, gpasm assumes
 an ORG of zero.
\layout Subsection*

PAGE
\begin_inset LatexCommand \index{PAGE}

\end_inset 


\layout LyX-Code

PAGE
\layout Standard

Causes the list file to advance to the next page.
\layout Standard

See also: LIST
\layout Subsection*

PAGESEL
\begin_inset LatexCommand \index{PAGESEL}

\end_inset 


\layout LyX-Code

PAGESEL <label>
\layout LyX-Code

GOTO <label>
\layout Standard

This directive will generate page selecting code to set the page bits to
 the page containing the designated <label>.
 The page selecting code will set/clear bits in the STATUS for 12 bit devices.
 For 14 bit and 16 bit devices, it will generate MOVLW and MOVWF to modify
 PCLATH.
 The directive is ignored for enhanced 16 bit devices.
\layout Standard

See also: BANKISEL, BANKSEL
\layout Subsection*

PROCESSOR
\begin_inset LatexCommand \index{PROCESSOR}

\end_inset 


\layout LyX-Code

PROCESSOR <symbol>
\layout Standard

Selects the target processor.
 See section 
\begin_inset LatexCommand \ref{sec:processors}

\end_inset 

 for more details.
\layout Standard

See also: LIST
\layout Subsection*

RADIX
\begin_inset LatexCommand \index{RADIX}

\end_inset 


\layout LyX-Code

RADIX <symbol>
\layout Standard

Selects the default radix from 
\begin_inset Quotes eld
\end_inset 

oct
\begin_inset Quotes erd
\end_inset 

 for octal, 
\begin_inset Quotes eld
\end_inset 

dec
\begin_inset Quotes erd
\end_inset 

 for decimal or 
\begin_inset Quotes eld
\end_inset 

hex
\begin_inset Quotes erd
\end_inset 

 for hexadecimal.
 gpasm uses this radix to interpret numbers that don't have an explicit
 radix.
\layout Standard

See also: LIST
\layout Subsection*

RES
\begin_inset LatexCommand \index{RES}

\end_inset 


\layout LyX-Code

RES <mem_units>
\layout Standard

Causes the memory location pointer to be advanced <mem_units>.
 Can be used to reserve data storage.
\layout Standard

See also: FILL, ORG
\layout Subsection*

SET
\begin_inset LatexCommand \index{SET}

\end_inset 


\layout LyX-Code

<label> SET <expression>
\layout Standard

Temporarily assigns the value obtained by evaluating <expression> to the
 symbol <label>.
\layout Standard

See also: SET
\layout Subsection*

SPACE
\begin_inset LatexCommand \index{SPACE}

\end_inset 


\layout LyX-Code

SPACE <expression>
\layout Standard

Inserts <expression> number of blank lines into the listing file.
\layout Standard

See also: LIST
\layout Subsection*

SUBTITLE
\begin_inset LatexCommand \index{SUBTITLE}

\end_inset 


\layout LyX-Code

SUBTITLE <string>
\layout Standard

This directive establishes a second program header line for use as a subtitle
 in the listing output.
 <string> is an ASCII string enclosed by double quotes, no longer than 60
 characters.
\layout Standard

See also: TITLE
\layout Subsection*

TITLE
\begin_inset LatexCommand \index{TITLE}

\end_inset 


\layout LyX-Code

TITLE <string>
\layout Standard

This directive establishes a program header line for use as a title in the
 listing output.
 <string> is an ASCII string enclosed by double quotes, no longer than 60
 characters.
\layout Standard

See also: SUBTITLE
\layout Subsection*

UDATA
\begin_inset LatexCommand \index{UDATA}

\end_inset 


\layout LyX-Code

<label> UDATA <expression>
\layout Standard

Only for relocatable mode.
 Creates a new uninitialized data section in the output object file.
 <label> specifies the name of the section.
 If <label> is not specified the default name 
\begin_inset Quotes eld
\end_inset 

.udata
\begin_inset Quotes erd
\end_inset 

 will be used.
 <expression> is optional and specifies the absolute address of the section.
 
\layout Standard

See also: CODE, IDATA, UDATA_ACS, UDATA_OVR, UDATA_SHR
\layout Subsection*

UDATA_ACS
\begin_inset LatexCommand \index{UDATA ACS}

\end_inset 


\layout LyX-Code

<label> UDATA_ACS <expression>
\layout Standard

Only for relocatable mode.
 Creates a new uninitialized accessbank data section in the output object
 file.
 <label> specifies the name of the section.
 If <label> is not specified the default name 
\begin_inset Quotes eld
\end_inset 

.udata_acs
\begin_inset Quotes erd
\end_inset 

 will be used.
 <expression> is optional and specifies the absolute address of the section.
 
\layout Standard

See also: CODE, IDATA, UDATA
\layout Subsection*

UDATA_OVR
\begin_inset LatexCommand \index{UDATA OVR}

\end_inset 


\layout LyX-Code

<label> UDATA_OVR <expression>
\layout Standard

Only for relocatable mode.
 Creates a new uninitialized overlaid data section in the output object
 file.
 <label> specifies the name of the section.
 If <label> is not specified the default name 
\begin_inset Quotes eld
\end_inset 

.udata_ovr
\begin_inset Quotes erd
\end_inset 

 will be used.
 <expression> is optional and specifies the absolute address of the section.
 
\layout Standard

See also: CODE, IDATA, UDATA
\layout Subsection*

UDATA_SHR
\begin_inset LatexCommand \index{UDATA SHR}

\end_inset 


\layout LyX-Code

<label> UDATA_SHR <expression>
\layout Standard

Only for relocatable mode.
 Creates a new uninitialized sharebank data section in the output object
 file.
 <label> specifies the name of the section.
 If <label> is not specified the default name 
\begin_inset Quotes eld
\end_inset 

.udata_shr
\begin_inset Quotes erd
\end_inset 

 will be used.
 <expression> is optional and specifies the absolute address of the section.
 
\layout Standard

See also: CODE, IDATA, UDATA
\layout Subsection*

VARIABLE
\begin_inset LatexCommand \index{VARIABLE}

\end_inset 


\layout LyX-Code

VARIABLE <label>[=<expression>, <label>[=<expression>]]*
\layout Standard

Delcares variable with the name <label>.
 The value of <label> may later be reassigned.
 The value of <label> does not have to be assigned at declaration.
\layout Standard

See also: CONSTANT
\layout Subsection*

WHILE
\begin_inset LatexCommand \index{WHILE}

\end_inset 


\layout LyX-Code

WHILE <expression>
\layout Standard

Performs loop while <expression> is true.
\layout Standard

See also: ENDW
\layout Section

Instructions 
\layout LyX-Code

\layout Subsection

Instruction set summary
\layout Subsubsection

12 bit Devices (PIC12C5XX)
\layout Standard
\LyXTable
multicol5
33 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Syntax
\newline 
Description
\newline 
ADDWF <f>,<dst>
\newline 
Add W to <f>, result in <dst>
\newline 
ANDLW <f>,<dst>
\newline 
And W and literal, result in W
\newline 
ANDWF <f>,<dst>
\newline 
And W and <f>, result in <dst>
\newline 
BCF <f>,<bit>
\newline 
Clear <bit> of <f>
\newline 
BSF <f>,<bit>
\newline 
Set <bit> of <f>
\newline 
BTFSC <f>,<bit>
\newline 
Skip next instruction if <bit> of <f> is clear
\newline 
BTFSS <f>,<bit>
\newline 
Skip next instruction if <bit> of <f> is set
\newline 
CALL <addr>
\newline 
Call subroutine
\newline 
CLRF <f>,<dst>
\newline 
Write zero to <dst>
\newline 
CLRW
\newline 
Write zero to W
\newline 
CLRWDT
\newline 
Reset watchdog timer
\newline 
COMF <f>,<dst>
\newline 
Complement <f>, result in <dst>
\newline 
DECF <f>,<dst>
\newline 
Decrement <f>, result in <dst>
\newline 
DECFSZ <f>,<dst>
\newline 
Decrement <f>, result in <dst>, skip if zero
\newline 
GOTO <addr>
\newline 
Go to <addr>
\newline 
INCF <f>,<dst>
\newline 
Increment <f>, result in <dst>
\newline 
INCFSZ <f>,<dst>
\newline 
Increment <f>, result in <dst>, skip if zero
\newline 
IORLW <f>,<dst>
\newline 
Or W and <f>, result in <dst>
\newline 
MOVF <f>,<dst>
\newline 
Move <f> to <dst>
\newline 
MOVLW <imm8>
\newline 
Move literal to W
\newline 
MOVWF <f>
\newline 
Move W to <f>
\newline 
NOP
\newline 
No operation
\newline 
OPTION
\newline 

\newline 
RETLW <imm8>
\newline 
Load W with immediate and return
\newline 
RLF <f>,<dst>
\newline 
Rotate <f> left, result in <dst>
\newline 
RRF <f>,<dst>
\newline 
Rotate <f> right, result in <dst>
\newline 
SLEEP
\newline 
Enter sleep mode
\newline 
SUBWF <f>,<dst>
\newline 
Subtract W from <f>, result in <dst>
\newline 
SWAPF <f>,<dst>
\newline 
Swap nibbles of <f>, result in <dst>
\newline 
TRIS
\newline 

\newline 
XORLW
\newline 
Xor W and <f>, result in <dst>
\newline 
XORWF
\newline 
Xor W and immediate
\layout Subsubsection

14 Bit Devices (PIC16CXX)
\layout Standard
\LyXTable
multicol5
36 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Syntax
\newline 
Description
\newline 
ADDLW <imm8>
\newline 
Add immediate to W
\newline 
ADDWF <f>,<dst>
\newline 
Add W to <f>, result in <dst>
\newline 
ANDLW <f>,<dst>
\newline 
And W and <f>, result in <dst>
\newline 
BCF <f>,<bit>
\newline 
Clear <bit> of <f>
\newline 
BSF <f>,<bit>
\newline 
Set <bit> of <f>
\newline 
BTFSC <f>,<bit>
\newline 
Skip next instruction if <bit> of <f> is clear
\newline 
BTFSS <f>,<bit>
\newline 
Skip next instruction if <bit> of <f> is set
\newline 
CALL <addr>
\newline 
Call subroutine
\newline 
CLRF <f>,<dst>
\newline 
Write zero to <dst>
\newline 
CLRW
\newline 
Write zero to W
\newline 
CLRWDT
\newline 
Reset watchdog timer
\newline 
COMF <f>,<dst>
\newline 
Complement <f>, result in <dst>
\newline 
DECF <f>,<dst>
\newline 
Decrement <f>, result in <dst>
\newline 
DECFSZ <f>,<dst>
\newline 
Decrement <f>, result in <dst>, skip if zero
\newline 
GOTO <addr>
\newline 
Go to <addr>
\newline 
INCF <f>,<dst>
\newline 
Increment <f>, result in <dst>
\newline 
INCFSZ <f>,<dst>
\newline 
Increment <f>, result in <dst>, skip if zero
\newline 
IORLW <f>,<dst>
\newline 
Or W and <f>, result in <dst>
\newline 
MOVF <f>,<dst>
\newline 
Move <f> to <dst>
\newline 
MOVLW <imm8>
\newline 
Move literal to W
\newline 
MOVWF <f>
\newline 
Move W to <f>
\newline 
NOP
\newline 
No operation
\newline 
OPTION
\newline 

\newline 
RETFIE
\newline 
Return from interrupt
\newline 
RETLW <imm8>
\newline 
Load W with immediate and return
\newline 
RETURN
\newline 
Return from subroutine
\newline 
RLF <f>,<dst>
\newline 
Rotate <f> left, result in <dst>
\newline 
RRF <f>,<dst>
\newline 
Rotate <f> right, result in <dst>
\newline 
SLEEP
\newline 
Enter sleep mode
\newline 
SUBLW
\newline 
Subtract W from literal
\newline 
SUBWF <f>,<dst>
\newline 
Subtract W from <f>, result in <dst>
\newline 
SWAPF <f>,<dst>
\newline 
Swap nibbles of <f>, result in <dst>
\newline 
TRIS
\newline 

\newline 
XORLW
\newline 
Xor W and <f>, result in <dst>
\newline 
XORWF
\newline 
Xor W and immediate
\layout Subsubsection

Ubicom Processors
\layout Standard

For Ubicom (Scenix) processors, the assembler supports the following instruction
s, in addition to those listed under 
\begin_inset Quotes eld
\end_inset 

12 Bit Devices
\begin_inset Quotes erd
\end_inset 

 above.
\layout Standard
\LyXTable
multicol5
11 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
8 1 1 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""

Syntax
\newline 
Description
\newline 
BANK <imm3>
\newline 

\newline 
IREAD
\newline 

\newline 
MODE <imm4>
\newline 

\newline 
MOVMW
\newline 

\newline 
MOVWM
\newline 

\newline 
PAGE <imm3>
\newline 

\newline 
RETI
\newline 

\newline 
RETIW
\newline 

\newline 
RETP
\newline 

\newline 
RETURN
\newline 

\layout Subsubsection

Special macros
\layout Standard

There are also a number of standard additional macros.
 These macros are:
\layout Standard
\LyXTable
multicol5
19 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Syntax
\newline 
Description
\newline 
ADDCF <f>,<dst>
\newline 
Add carry to <f>, result in <dst>
\newline 
B <addr>
\newline 
Branch
\newline 
BC <addr>
\newline 
Branch on carry
\newline 
BZ <addr>
\newline 
Branch on zero
\newline 
BNC <addr>
\newline 
Branch on no carry
\newline 
BNZ <addr>
\newline 
Branch on not zero
\newline 
CLRC
\newline 
Clear carry
\newline 
CLRZ
\newline 
Clear zero
\newline 
SETC
\newline 
Set carry
\newline 
SETZ
\newline 
Set zero
\newline 
MOVFW <f>
\newline 
Move file to W
\newline 
NEGF <f>
\newline 
Negate <f>
\newline 
SKPC
\newline 
Skip on carry
\newline 
SKPZ 
\newline 
Skip on zero
\newline 
SKPNC
\newline 
Skip on no carry
\newline 
SKPNZ 
\newline 
Skip on not zero
\newline 
SUBCF <f>,<dst>
\newline 
Subtract carry from <f>, result in <dst>
\newline 
TSTF <f>
\newline 
Test <f>
\layout Section

Errors/Warnings/Messages
\layout Standard

gpasm writes every error message to two locations:
\layout Itemize

the standard error output
\layout Itemize

the list file (
\begin_inset Quotes eld
\end_inset 

.lst
\begin_inset Quotes erd
\end_inset 

)
\layout Standard

The format of error messages is:
\layout LyX-Code

Error <src-file> <line> : <code> <description>
\layout Standard

where:
\layout Description

<src-file> is the source file where gpasm encountered the error
\layout Description

<line> is the line number
\layout Description

<code> is the 3-digit code for the error, given in the list below
\layout Description

<description> is a short description of the error.
 In some cases this contains further information about the error.
\layout Standard

Error messages are suitable for parsing by emacs' 
\begin_inset Quotes eld
\end_inset 

compilation mode
\begin_inset Quotes erd
\end_inset 

.
 This chapter lists the error messages that gpasm produces.
 
\layout Subsection

Errors
\layout Description

101 ERROR directive
\layout Standard

A user-generated error.
 See the ERROR directive for more details.
\layout Description

114 Divide by zero
\layout Standard

gpasm encountered a divide by zero.
\layout Description

115 Duplicate Label
\layout Standard

Duplicate label or redefining a symbol that can not be redefined.
\layout Description

124 Illegal Argument
\layout Standard

gpasm encountered an illegal argument in an expression.
 
\layout Description

125 Illegal Condition
\layout Standard

An illegal condition like a missing ENDIF or ENDW has been encountered.
\layout Description

126 Argument out of Range
\layout Standard

The expression has an argument that was out of range.
\layout Description

127 Too many arguments
\layout Standard

gpasm encountered an expression with too many arguments.
\layout Description

128 Missing argument(s)
\layout Standard

gpasm encountered an expression with at least one missing argument.
\layout Description

129 Expected
\layout Standard

Expected a certain type of argument.
 
\layout Description

130 Processor type previously defined
\layout Standard

The processor is being redefined.
 
\layout Description

131 Undefined processor
\layout Standard

The processor type has not been defined.
 
\layout Description

132 Unknown processor
\layout Standard

The selected processor is not valid.
 Check the processors listed in section 
\begin_inset LatexCommand \ref{sec:processors}

\end_inset 

.
\layout Description

133 Hex file format INHX32 required
\layout Standard

An address above 32K was specified.
 
\layout Description

135 Macro name missing
\layout Standard

A macro was defined without a name.
 
\layout Description

136 Duplicate macro name
\layout Standard

A macro name was duplicated.
 
\layout Description

145 Unmatched ENDM
\layout Standard

ENDM found without a macro definition.
 
\layout Description

159 Odd number of FILL bytes
\layout Standard

In PIC18CXX devices the number of bytes must be even.
 
\layout Subsection

Warnings
\layout Description

201 Symbol not previously defined.
\layout Standard

The symbol being #undefined was not previously defined.
\layout Description

202 Argument out of range
\layout Standard

The argument does not fit in the allocated space.
\layout Description

211 Extraneous arguments
\layout Standard

Extra arguments were found on the line.
\layout Description

215 Processor superseded by command line
\layout Standard

The processor was specified on the command line and in the source file.
 The command line has precedence.
\layout Description

216 Radix superseded by command line
\layout Standard

The radix was specified on the command line and in the source file.
 The command line has precedence.
\layout Description

217 Hex format superseded by command line
\layout Standard

The hex file format was specified on the command line and in the source
 file.
 The command line has precedence.
\layout Description

218 Expected DEC, OCT, HEX.
 Will use HEX.
\layout Standard

gpasm encountered an invalid radix.
\layout Description

219 Invalid RAM location specified.
\layout Standard

gpasm encountered an invalid RAM location as specified by the __MAXRAM and
 __BADRAM directives.
\layout Description

222 Error messages can not be disabled
\layout Standard

Error messages can not be disabled using the ERRORLEVEL directive.
\layout Description

223 Redefining processor
\layout Standard

The processor is being reselected by the LIST or PROCESSOR directive.
\layout Description

224 Use of this instruction is not recommanded
\layout Standard

Use of the TRIS and OPTION instructions is not recommended for a PIC16CXX
 device.
\layout Subsection

Messages
\layout Description

301 User Message
\layout Standard

User message, invoked with the MESSG directive.
 
\layout Description

303 Program word too large.
 Truncated to core size.
\layout Standard

gpasm has encounter a program word larger than the core size of the selected
 device.
 
\layout Description

304 ID Locations value too large.
 Last four hex digits used.
\layout Standard

The ID locations value specified is too large.
\layout Description

305 Using default destination of 1 (file).
\layout Standard

No destination was specified so the default location was used.
\layout Description

308 Warning level superseded by command line
\layout Standard

The warning level was specified on the command line and in the source file.
 The command line has precedence.
\layout Description

309 Macro expansion superseded by command line
\layout Standard

Macro expansion was specified on the command line and in the source file.
 The command line has precedence.
\layout Chapter

gplink
\layout Standard

gplink relocates and links gpasm COFF objects and generates an absolute
 executable COFF.
\layout Section

Running gplink
\begin_inset LatexCommand \index{Running gplink}

\end_inset 


\layout Standard

The general syntax for running gplink is
\layout LyX-Code

gplink [options] [objects] [libraries]
\layout Standard

Where options can be one of:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
12 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "4in" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Option
\newline 
Meaning
\newline 
a
\newline 
Produce hex file in one of four formats: inhx8m, inhx8s, inhx16, inhx32
 (the default).
\newline 
c
\newline 
Output an executable object.
\newline 
d
\newline 
Display debug messages
\newline 
f <value>
\newline 
Fill unused unprotected program memory with <value>.
\newline 
h
\newline 
Show the help message
\newline 
I <directory>
\newline 
Specify an include directory.
\newline 
m
\newline 
Output a map file.
\newline 
o <file>
\newline 
Alternate name of hex output file.
\newline 
q
\newline 
Quiet.
\newline 
s <file>
\newline 
Specify linker script.
\newline 
v
\newline 
Print gplib version information and exit
\layout Section

gplink outputs
\layout Standard

gplink creates an absolute executable COFF.
 From this COFF a hex file and cod file are created.
 The executable COFF is only written when the 
\begin_inset Quotes eld
\end_inset 

-c
\begin_inset Quotes erd
\end_inset 

 option is added.
 This file is useful for simulating the design with mpsim.
 The cod file is used for simulating with gpsim.
\layout Standard

gplink can also create a map file.
 The map file reports the final addresses gplink has assigned to the COFF
 sections.
 This is the same data that can be viewed in the executable COFF with gpvo.
\layout Section

Linker scripts
\layout Standard

gplink requires a linker script.
 This script tells gplink what memory is available in the target processor.
 A set of Microchip generated scripts are installed with gputils.
 These scripts were intended as a starting point, but for many applications
 they will work as is.
\layout Standard

If the user does not specify a linker script, gplink will attempt to use
 the default script for the processor reported in the object file.
 The default location of the scripts is reported in the gplink help message.
\layout Chapter

gplib
\layout Standard

gplib creates, modifies and extracts COFF archives.
 This allows a related group of objects to be combined into one file.
 Then this one file is passed to gplink.
 
\layout Section

Running gplib
\begin_inset LatexCommand \index{Running gplib}

\end_inset 


\layout Standard

The general syntax for running gplib is
\layout LyX-Code

gplib [options] library [member]
\layout Standard

Where options can be one of:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
11 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "4in" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Option
\newline 
Meaning
\newline 
c
\newline 
Create a new library
\newline 
d
\newline 
Delete member from library
\newline 
h
\newline 
Show the help message
\newline 
n
\newline 
Don't add the symbol index
\newline 
q
\newline 
Quiet mode.
\newline 
r
\newline 
Add or replace member from library.
\newline 
s
\newline 
List global symbols in libary.
\newline 
t
\newline 
List member in library
\newline 
v
\newline 
Print gplib version information and exit
\newline 
x
\newline 
Extract member from library
\layout Section

Creating an archive
\begin_inset LatexCommand \index{Creating an archive}

\end_inset 


\layout Standard

The most common operation is to create a new archive: 
\layout LyX-Code

gplib -c math.a mult.o add.o sub.o
\layout Standard

This command will create a new archive 
\begin_inset Quotes eld
\end_inset 

math.a
\begin_inset Quotes erd
\end_inset 

 that contains 
\begin_inset Quotes eld
\end_inset 

mult.o add.o sub.o
\begin_inset Quotes erd
\end_inset 

.
 
\layout Standard

The name of the archive 
\begin_inset Quotes eld
\end_inset 

math.a
\begin_inset Quotes erd
\end_inset 

 is arbitrary.
 The tools do not use the file extension to determine file type.
 It could just as easily been 
\begin_inset Quotes eld
\end_inset 

math.lib
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

math
\begin_inset Quotes erd
\end_inset 

.
\layout Standard

When you use the library, simply add it to the list of object passed to
 gplink.
 gplink will scan the library and only extract the archive members that
 are required to resolve external references.
 So the application won't necessarily contain the code of all the archive
 members.
\layout Section

Other gplib operations
\begin_inset LatexCommand \index{Other gplib operations}

\end_inset 


\layout Standard

Most of the other are useful , but will be used much less often.
 For example you can replace individual archive members, but most people
 elect to delete the old archive and create a new one.
\layout Section

Archive format
\begin_inset LatexCommand \index{Archive format}

\end_inset 


\layout Standard

The file format is a standard COFF archive.
 A header is added to each member and the unmodified object is copied into
 the archive.
\layout Standard

Being a standard archive they do include a symbol index.
 It provides a simple why to determine which member should be extract to
 resolve external references.
 This index is not included in mplib archives.
 So using gplib archives with Microchip Tools will probably cause problems
 unles the 
\begin_inset Quotes eld
\end_inset 

-n
\begin_inset Quotes erd
\end_inset 

 option is added when the archive is created.
\layout Chapter

Utilities
\layout Section

gpdasm
\begin_inset LatexCommand \index{gpdasm}

\end_inset 


\layout Standard

gpdasm is a disassembler for gputils.
 It converts hex files generated by gpasm and gplink into disassembled instructi
ons.
\layout Subsection

Running gpdasm
\begin_inset LatexCommand \index{Running gpdasm}

\end_inset 


\layout Standard

The general syntax for running gpdasm is
\layout LyX-Code

gpdasm [options] hex-file
\layout Standard

Where options can be one of:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
8 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "4in" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Option
\newline 
Meaning
\newline 
h
\newline 
Display the help message.
\newline 
i
\newline 
Display hex file information
\newline 
l
\newline 
List supported processors.
\newline 
m
\newline 
Memory dump hex file.
\newline 
p<processor>
\newline 
Select processor.
\newline 
s
\newline 
Print short form output
\newline 
v
\newline 
Print gpasm version information and exit.
\layout Standard

gpdasm doesn't specifically create an output file.
 It dumps its output to the screen.
 This helps to reduce the risk that a good source file will be unintentionally
 overwritten.
 If you want to create an output file and your shell is 
\begin_inset LatexCommand \index{sh}

\end_inset 


\begin_inset Quotes eld
\end_inset 

sh
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset LatexCommand \index{bash}

\end_inset 


\begin_inset Quotes eld
\end_inset 

bash
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset LatexCommand \index{ksh}

\end_inset 


\begin_inset Quotes eld
\end_inset 

ksh
\begin_inset Quotes erd
\end_inset 

, you can do something like:
\layout LyX-Code

gpdasm test.hex > test.dis
\layout Standard

This redirects standard output to the file 
\begin_inset Quotes eld
\end_inset 

test.dis
\begin_inset Quotes erd
\end_inset 

.
\layout Subsection

Comments on Disassembling
\layout Itemize

The gpdasm only uses a hex file as an input.
 Because of this it has no way to distinguish between instructions and data
 in program memory.
 
\layout Itemize

If gpdasm encounters an unknown instruction it uses the DW directive and
 treats it as raw data.
\layout Itemize

There are DON'T CARE bits in the instruction words.
 Normally, this isn't a problem.
 It could be, however, if a file with data in the program memory space is
 disassembled and then reassembled.
 Example: gpdasm will treat 0x0060 in a 14 bit device as a NOP.
 If the output is then reassembled, gpasm will assign a 0x0000 value.
 The value has changed and both tools are behaving correctly.
\layout Section

gpvc
\begin_inset LatexCommand \index{gpvc}

\end_inset 


\layout Standard

gpvc is cod file viewer for gputils.
 It provides an easy way to view the contents of the cod files generated
 by gpasm and gplink.
\layout Subsection

Running gpvc
\begin_inset LatexCommand \index{Running gpvc}

\end_inset 


\layout Standard

The general syntax for running gpvc is
\layout LyX-Code

gpvc [options] cod-file
\layout Standard

Where options can be one of:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
9 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "4in" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Option
\newline 
Meaning
\newline 
a
\newline 
Display all information
\newline 
d
\newline 
Display directory header
\newline 
s
\newline 
Display symbols
\newline 
h
\newline 
Show the help message.
\newline 
r
\newline 
Display ROM
\newline 
l
\newline 
Display source listing
\newline 
m
\newline 
Display debug message area
\newline 
v
\newline 
Print gpvc version information and exit.
\layout Standard

gpvc doesn't specifically create an output file.
 It dumps its output to the screen.
 If you want to create an output file and your shell is 
\begin_inset LatexCommand \index{sh}

\end_inset 


\begin_inset Quotes eld
\end_inset 

sh
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset LatexCommand \index{bash}

\end_inset 


\begin_inset Quotes eld
\end_inset 

bash
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset LatexCommand \index{ksh}

\end_inset 


\begin_inset Quotes eld
\end_inset 

ksh
\begin_inset Quotes erd
\end_inset 

, you can do something like:
\layout LyX-Code

gpvc test.cod > test.dump
\layout Standard

This redirects standard output to the file 
\begin_inset Quotes eld
\end_inset 

test.dump
\begin_inset Quotes erd
\end_inset 

.
\layout Section

gpvo
\begin_inset LatexCommand \index{gpvo}

\end_inset 


\layout Standard

gpvo is COFF object file viewer for gputils.
 It provides an easy way to view the contents of objects generated by gpasm
 and gplink.
\layout Subsection

Running gpvo
\begin_inset LatexCommand \index{Running gpvo}

\end_inset 


\layout Standard

The general syntax for running gpvo is
\layout LyX-Code

gpvo [options] object-file
\layout Standard

Where options can be one of:
\layout Standard
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
multicol5
8 2 0 0 -1 -1 -1 -1
1 1 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 0 0 0
1 1 0 0
2 1 0 "" ""
2 1 1 "4in" ""
0 8 1 0 0 0 0 "" ""
0 8 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""
0 2 1 0 0 0 0 "" ""

Option
\newline 
Meaning
\newline 
b
\newline 
Binary data
\newline 
f
\newline 
File header
\newline 
h
\newline 
Show the help message
\newline 
n
\newline 
Suppress filenames
\newline 
s
\newline 
Section data
\newline 
t
\newline 
Symbol data
\newline 
v
\newline 
Print gpvo version information and exit
\layout Standard

gpvo doesn't specifically create an output file.
 It dumps its output to the screen.
 If you want to create an output file and your shell is 
\begin_inset LatexCommand \index{sh}

\end_inset 


\begin_inset Quotes eld
\end_inset 

sh
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset LatexCommand \index{bash}

\end_inset 


\begin_inset Quotes eld
\end_inset 

bash
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset LatexCommand \index{ksh}

\end_inset 


\begin_inset Quotes eld
\end_inset 

ksh
\begin_inset Quotes erd
\end_inset 

, you can do something like:
\layout LyX-Code

gpvo test.obj > test.dump
\layout Standard

This redirects standard output to the file 
\begin_inset Quotes eld
\end_inset 

test.dump
\begin_inset Quotes erd
\end_inset 

.
\layout Standard


\begin_inset LatexCommand \printindex{}

\end_inset 


\the_end
