Assembler version 0.1 Documentation
-----------------------------------

(c) 1994 Ian King

Introduction
------------

This documentation has been rushed to get the tools out onto the internet,
and it shows.  This is one of the first areas to be looked at updating.
If anything is not obvious then 1) Look at the examples in the ./test
directory 2) try something out (and use picdis to look at the results)
3) peruse the source code (parser.c is most likely) 4) mail me and ask.

Also be aware that testing has been short and sweet, so this document is more
what should be possible than what is!  There are still a few bug yet to be
pesticided.  Only simple examples have been properly tested so the more
complex the structures the less likely they are to work in a 0.1 version, sorry.

The assembler has been constructed as a recursive descent compiler for a simple
LL(1) grammar if anyone is interested, and is thus quite a bit more flexible
than the average assembler, but the parser is a bit more complex as a result.

Bug reports
-----------

Send bug reports to the e-mail/snail mail addresses in the README.1st file.
For a quick solution the following is required:

	example.asm that breaks the assembler
	what is wrong
	what you get and what you think you should get
	what you think is wrong

diff's of fixed code can be sent, but will only be included if I understand
what you are doing and they don't break anything else, I will probably rewrite
them to fit in with my coding style, but you will be fully acknowledged in
future versions.

Instructions Variables and Expressions
--------------------------------------

The instructions provided as standard are those defined in the Microchip
Databook 1993 for the 12 and 14bit PICs (i.e. 54,55,56,57 and 71,84,64).

Constants are defined using extended C syntax e.g.
	1234		decimal
	01234		octal (be careful)
	0x12fc		hex
	0b10101011	binary

Variables are defined as:

	fred  =  <expression>
or	sid  equ <expression>

Labels are defined as:

	label2:

Comments are defined as:-
	 ; comment <end of line>

The current code position may be used within expressions referenced as period
e.g.

	goto .+1	; performs a double nop instruction

One extra instruction is the data instruction for example:-

	data 0000	; plants a nop instruction

This is meant to be useful (but I haven't used it yet)

Expressions are defined in infix notation (i.e. like C) and operators have
varying levels of precedence.  The following are the operators included.

Precedence goes from high to low


     unary objects

~		1's complement
!		logical not
++		increment
--		decrement
-		2's complement
+		unary + (meaningless)
.		current location
<id>		identifier value
<number>	value
()		brackets

    binary objects

*		multiply
/		divide
%		mod
>>		shift right
<<		shift left

+		addition
-		subtraction
&		binary and
|		binary or
^		binary xor

==		logical equivalence
>		logical greater
>=		logical greater or equal
<		logical less than
<=		logical you guessed already
&&		logical and
||		logical or
^^		logical xor

Hardware Definitions
--------------------

The pic hardware is the first thing to be defined because is contains the
vital information on whether 12bit or 14bit code is the target.
A typical definition would go along the lines of:

$processor	84		; processor configuration
$watchdog	off
$pwrup		on
$protect	on
$clock		hs, 4000000	; 4MHz
$idwords	0, 0x000e, 0, 1+2+5 ; look our first expression

which should be fairly self explanatory.

Programs
--------

A program may have several sections in the PIC memory defined as org blocks

e.g.
	codestart1 equ 0x000
	codestart2 equ 0xf00

	org codestart1
	; code
	; more code
	; etc etc etc
	end

	org codestart2
	; subroutines
	; and functions
	; etc etc etc
	end

Blocks and Locals
-----------------

A block may be defined, and any definitions within the block are treated as
locals i.e. they disapear at the end of the block (and don't appear in the
symbol table file)

The syntax is as follows:

	begin

local:	; block internals

	variable = 0

	endb

Blocks may be nested.

Macros
------

Macros consist of two parts, the definition and the useage.
The definition is as:

	macro macroname p1,p2,p3,p4, etc

	; macro functions

	endm

The p1,p2,p3,p4 etc are variables defined to be parameters to this macro.
These are defined at the same time as the macro definition.

The macro is "called" as:-

	macroname <expression>, <expression>, <expression>, <expression>, etc

e.g.

; code fragment

macro sid,p1,p2,p3	; this one is legal

	begin		; the use of a block to make loop local

	clrwdt
	clrf p1
	clrf p3

loop:	goto p2

	endb
endm

; and included as


	org 0

label:	sid 0,label+20,3

	end

; end code

Include Files
-------------

Include files are simply implemented with the syntax:

	include "includefilename"

and may be included at any time.  They are included textually i.e.
they are treated as if their text is dropped in at the point of the
include (at whatever level of block scope at that time for example).
Includes may be nested.

Conditional Assembly
--------------------

Conditional assembly is a very powerful feature when combined with the
macros.  The format(s) are as follows:

	if     <expression>
or	ifdef  <variable>
or	ifndef <variable>

optionally

	else

finally

	endif

so possibly

; .. code fragment

	if fred>54
		clrw
	else
		clrwdt
	endif

; or

	fred = 0

	ifdef fred
		;do onething
	endif

; silly example should use else!

	ifndef fred
		;do something else
	endif
; end code example

Like everything else conditional structures may be nested to unreadable levels
of complexity.


... The End ...

