Assembler for Microchip PIC16Cxx microcontrollers

Version 1.12c

Copyright 1995-2005 by Timo Rossi. All rights reserved. See the file
"LICENSE" for information about redistribution conditions.

Suggestions and bug reports are welcome.

Timo Rossi
email: trossi@iki.fi
www: http://www.iki.fi/trossi/pic/

WARNING: This is a beta version. It will probably work OK most of the time,
but it has not been extensively tested. Also, this document file has not
been properly updated. There is support for many new PICs (including 16-bit
ones), and some new directives.

The code is (mostly) ANSI-C, and should compile with most platforms (It does
assume that negative integers are stored in two's complement representation)
And it uses the strcasecmp() or stricmp() function)

Command line usage:

picasm [-o<objname>] [-l<listfile>] [-ihx8m] [-ihx16] [-pic<device>]
<filename>

Options:

 -o<filename>   Define output file name. Default is
                <source_without_ext>.hex.
 -l[<listfile>] Enable listing. Default listing file name is
                <source_without_ext>.lst.
 -s             Includes symbol table in listing. Does nothing if listing
                is not enabled.
 -w[<warnlevel>]Give more warnings. If <warnlevel> is omitted, one is
                assumed. Level two warns also about tris/option
                instructions on 14-bit PICs.
 -i<include_dir>Add a directory to the include file search path. Several -i
                -options can be used to add multiple directories.
 -ihx8m         IHX8M output format (default).
 -ihx16         IHX16 output format.
 -pic<device>   Select PIC device. (12c508, 12c509, 12c671, 12c672, 16c52,
                16c54(a), 16c55, 16c56, 16c57, 16c58a, 16c61, 16c62(a),
                16c63, 16c64(a), 16c65(a), 16c66, 16c67, 16c71, 16c710,
                16c711, 16c715, 16c72, 16c73(a), 16c74(a), 16c83, 16c84,
                16f84 16c620, 16c621, 16c622, 16c554(a), 16c556a,
                16c558(a), 14000). THE ABOVE DEVICE LIST IS INCOMPLETE.
                CHECK devices.txt FOR FULL LIST.

Code syntax

The basic syntax that this assembler uses is similar to the syntax of the
Microchip assembler. However, many directives and expressions are different.

Assembler mnemonics and directives must not be located in the very beginning
of a line (tabs or spaces should be used, unless the line begins with a
label). Labels must either end with a colon, or start at the beginning of a
line.

This is a single-pass assembler, forward gotos/calls are patched at the end
of the assembly (only single labels are accepted in that case, otherwise
expressions can be used too)

In current versions forward references can also be used with movlw, addlw
and retlw (only the low 8 bits of an address are used.)

Expressions

Expressions can have the following elements: (from highest precedence to the
lowest).

                           integer constants
                           symbols
(<expression>)
. (or $)                   current location
defined(<symbol>)          TRUE (-1) if symbol is defined else FALSE (0).
streq("str1", "str2")      TRUE if strings are identical.
isstr(<arg>)               TRUE is argument is a quoted string.
chrval("str", <pos>)       Returns ASCII character code from the string.
                           Position range is from 0 to string length-1. If
                           position is out of range, returns -1.

[ expr1 expr2...  expr_n ] The same as (1 << expr1) | (1 << expr2) ...
                           (builds a number by setting individual bits)
-                          unary minus
~                          bitwise not
*                          multiply
/                          divide
%                          modulo/remainder
&                          bitwise and
+                          add
-                          subtract
|                          bitwise or
^                          bitwise exclusive or
<<                         shift left
>>                         shift right
==                         equal
!=, <>                     not equal
<                          less than
<=, =<                     less or equal than
>                          greater than
>=, =>                     greater or equal than

The compare operators return TRUE (-1) or FALSE (0) (they are useful with
conditional assembly).

Expressions are evaluated as 32-bit integers (or whatever size 'long' is).

hex numbers     0x<digits>, h'<digits>', $<digits> or <digits>h (must begin
                with 0..9)
octal numbers   <digits>o, o'<digits>'
binary numbers  0b<digits>, b'<digits>' or <digits>b
decimal numbers without prefix or d'<digits>'.

Directives

(square brackets denote optional parameters)
<label> equ <expr>                             Define a constant
<label> set <expr>                             Define a variable (similar to
                                               equ but can be redefined with
                                               another set-directive)

   org <address>                               Specify origin for program
   org <address>, <mode>                       code, register file or data
   org <mode>                                  EEPROM. <mode> is "code" for
                                               program code, "reg" for
                                               register file and "edata" for
                                               data EEPROM. If mode is not
                                               given, it is determined
                                               automatically from first
                                               instruction that generates
                                               output to the hex file. After
                                               that the mode cannot be
                                               changed without another ORG
                                               statement. When ORG is used
                                               with only the mode parameter,
                                               the address continues from the
                                               last value for that mode.

   include "<filename>"                        Include another source file.
                                               Includes can be nested.

   end                                         End assembly. anything after
                                               this is ignored.

<label> ds <expr>                              Reserve <expr> number of file
                                               register (RAM) locations. ORG
                                               must be set for this to work.

<label> edata <expr> [, <expr>... ]            Define data EEPROM contents
                                               (only with PICs with data
                                               EEPROM)

   if <expr>                                   Conditional assembly. If
<code1>                                        <expr> is non-zero, <code1>
   [ else                                      after the if-directive is
<code2> ]                                      assembled, and the optional
   endif                                       <code2> is skipped. If <expr>
                                               is zero, <code1> is skipped
                                               and optional <code2> is
                                               assembled.

<macroname> macro                              Define a macro.
<macro definition>
   endm                                        Macro parameters are \1...\9,
                                               \# is the number of
                                               parameters. \@ (or \0) is an
                                               number that is different for
                                               each macro expansion (it can
                                               be used to generate unique
                                               labels inside macros). Macros
                                               can be recursive.

   exitm                                       Exit macro (can only be used
                                               inside a macro definition.
                                               Useful with conditional
                                               assembly)

   local                                       Begin and end a local
   endlocal                                    label/symbol block.

                                               Local symbols must be prefixed
                                               with "=" and their name scope
                                               is only the current local
                                               symbol block. Local symbol
                                               blocks can be nested but only
                                               the symbols in the currently
                                               active block can be used (the
                                               symbols in the inner and outer
                                               blocks are not visible)

   config <config_param> [, <config_param>...] Define PIC configuration fuse
                                               data. <config_param> can be:
                                               CP=<on_off>    Code protection
                                                              (default off,
                                                              partial
                                                              protection not
                                                              supported)
                                               PWRTE=<on_off> Powerup timer
                                                              (default varies
                                                              with PIC
                                                              models, not
                                                              valid with
                                                              12-bit PICs).
                                                              Also
                                                              PWRT=<on_off>.
                                               WDTE=<on_off>  Watchdog
                                                              (default on).
                                                              Also
                                                              WDT=<on_off>.
                                               BODEN=<on_off> Brown-out
                                                              detect. only
                                                              valid with some
                                                              PIC models.
                                                              Also
                                                              BOD=<on_off>.
                                               OSC=<osctype>  Oscillator type
                                                              (typically HS,
                                                              XT, LP, RC,
                                                              some PIC models
                                                              have different
                                                              options)
                                               The <on_off> parameter can be:
                                               on, yes, enabled  on
                                               off, no, disabled off
                                               The fuses are located in
                                               address 0xfff with 12-bit PICs
                                               and 0x2007 with 14-bit PICs.

   picid  <id1>,  <id2>,  <id3>,  <id4>        Define PIC ID values.

                                               The ID is located in the hex
                                               file at the address following
                                               program memory end with 12-bit
                                               PICs, and at 0x2000 with
                                               14-bit PICs.

   device <device>                             Select PIC device type. Valid
                                               values are listed in the
                                               command line option section
                                               (the -pic<type> option).

   opt <option>                                Set assembly options.
                                               Currently only implemented:
                                               list or l     turn listing on
                                               nolist or nol turn listing off

   error <error_message>                       Causes an assembly error.

[this text was file semi-automatically generated from picasm.html]
