
               Assembler for Microchip PIC16Cxx microcontrollers

Version 1.14

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

   Timo Rossi
   email: [2]trossi@iki.fi
   www: [3]http://www.iki.fi/trossi/pic/

   NOTE: 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) ISO-C90, 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).
   The code also uses the so-called "struct hack". Also, the snprintf()
   function (standard in ISO-C99) is used.

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.
   -d<symbol> [ = <value> ] Define an assembler symbol. The value of the
   symbol must be a decimal or hex number (hex uses 0x-prefix). If a
   value is not given, the symbol value becomes 1. Multiple -d- options
   can be used to define multiple symbols.
   -ihx8m IHX8M output format (default).
   -ihx16 IHX16 output format.
   -pic<device> Select PIC device. The PIC types are defined in special
   include files (see the device_definitions directory).

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.
   streqcase("str1", "str2") The same as streq() but ignores case (Only
   for ASCII characters, not ISO-Latin, Unicode etc.).
   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.
   hibyte(label) Return the high byte of the label address. Useful for
   accessing program memory using the eeadr/eeadrh registers. Forward
   reference is allowed when hibyte() is not used as a part of a more
   complex expression.
   [ 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>
      org <address>, <mode>
      org <mode> Specify origin for program code, register file or data
   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. #include is an alternate name for this
      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)
      dt  <value1> [ , <value2>... ] Generate an array retlw instructions
   with the specified return values (typically used for table lookup in
   PIC assembler code. You can also use a list of multiple return values
   with the actual retlw -mnemonic to generate to a list of retlw
   instructions.)
      if <expr>
   <code1>
      [ else
   <code2> ]
      endif Conditional assembly. If <expr> is non-zero, <code1> after
   the if-directive is assembled, and the optional <code2> is skipped. If
   <expr> is zero, <code1> is skipped and optional <code2> is assembled.
   <macroname> macro
   <macro definition>
      endm

   Define a macro.

   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
      endlocal

   Begin and end a local 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. The PIC types are defined
   in special include files. (see the device_definitions directory).
      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.

References

   1. file://localhost/home/trossi/work/pic/picasm114/LICENSE
   2. mailto:trossi@iki.fi
   3. http://www.iki.fi/trossi/pic/
