Assembler for Microchip PIC16Cxx microcontrollers

Version 1.14

Timo Rossi
email: trossi@iki.fi
www: 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.