Assembler version 0.8 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 ./example
directoies 2) try something out (and use picdis to look at the results)
3) peruse the source code in ./src 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.7 version, sorry.

The assembler is constructed in three passes, pass 1 is cpp the C pre-processor,
this gives #include, #define, #if etc etc.  Pass 2 is the macro exploder and pass3
is the assembler.

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

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>
	 // coment <end of line> (C++ style)
	 /* comment */		 (C style)

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

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

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

This is output to the .cfg file.  An example is as follows:-

config # "Test File For Assembler" ;
config pic	1684 ;
config clk	hs 1000000 ;
config cp	disabled ;
config wdt	enabled ;
config pwrup	enabled ;
config id	0xffff 0xffff 0xffff 0xffff ;
config # "... The End ..." ;

#include "pic14"

Note: this has to be lower case due to the was flex works.  the include file includes
the instruction macros for a 14 bit pic.

Programs
--------

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

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

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

	begin
	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.


The syntax is as follows:

	begin

local:	; block internals

	variable = 0

	goto local

	end

Blocks may be nested.

Macros
------

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

	macro macroname

	; macro functions

	endm

The the arguments are referenced as $1 $2 $3 etc.  See the pic14 macro file for details
These are defined at the same time as the macro definition.

The macro is "called" as:-

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


... The End ...

