README for Orgasm v0.22
-----------------------

Orgasm is a machine code assembler for 6502 microprocessors (and derivatives,
such as the 6510, 8502 and 65C02).

I felt compelled to write an assembler after D65 got too restrictive for me.
Learning C has spoilt me, I've gotten used to using # directives everywhere,
and I wanted to be able to do this in my assembler as well. I was going to make
the necessary changes to D65, but the licence won't let me distribute changes.
So I decided it'd be an interesting project to write my own assembler, since
I relied on one for so many years (the mighty Turbo Assembler :)

Most of the features are implemented. There is now a powerful expression
parser in place that can evaluate arithmetic expressions. There is full support
for symbols in expressions as well.

For full details of changes between this version and previous versions, see the
changelog.

And the name? Well, 'org' is the directive to signal the start of a code block,
and 'asm' means assembler, of course :)

If you find any bugs in this code or have any suggestions, feel free to contact
me at rob@nauseum.org.

Robert Norris
2000-02-02


Installation
------------

Orgasm is developed on an i386 Linux 2.2 system with glibc 2.1. I've also had
it compile on the following systems:

Solaris 2.6	(Sun UltraSPARC 10, 30, Sun Ultra Enterprise 3000, 10000)
OSF/1 4.0	(DEC AlphaServer 2100)
OSF/1 5.0	(DECStation 5100)
Ultrix		(DECStation 3100)
NetBSD 1.4.1	(DECStation 3100)

Installation should be simple, just

	./configure
	make
	make install

Running
-------

To run orgasm, use

	orgasm [OPTIONS] inputfile

OPTIONS are any of the following:

	-b
		Base address for mem8, mem16 and mem32 output formats
	
	-d
		Include debug code in the output file (see the .debug directive)
	
	-e
		Output exported symbols to a file
	
	-f format
		Sets the output file format to one of:

		- cbm (default)
		
			Standard CBM file format:
		
			+---------------------+
			| Org address (lo/hi) |
			+---------------------+
			|                     |
			|    Code segment     |
			|                     |
			+---------------------+

			Space between code segments will be padded with $00's

		- segment

			File format with multiple segments:
			
			+-----------------------+
			|   Org of 1st segment  |
			+-----------------------+
			| Length of 1st segment |
			+-----------------------+
			|                       |
			|    1st code segment   |
			|                       |
			+-----------------------+
			|   Org of 2nd segment  |
			+-----------------------+
			| Length of 2nd segment |
			+-----------------------+
			|                       |
			|    2nd code segment   |
			|                       |
			+-----------------------+
		              :     :     :
		              :     :     :
		              :     :     :
			+-----------------------+
			|   Org of nth segment  |
			+-----------------------+
			| Length of nth segment |
			+-----------------------+
			|                       |
			|    nth code segment   |
			|                       |
			+-----------------------+

		- mem

			Produces an 64K memory image with each code segment
			in its proper position.

		- mem8, mem16 and mem32

			Produces 8K, 16K and 32K memory images. The start
			address of the image is taken from the -b option.

	-h
		Display some help

	-o outputfile
		Sets the name of the output file (default: a.out)
	
	-v
		Be a little more verbose during assembly
	

Programming
-----------

All standard 6502 opcodes are support, eg.

	lda $1000
	tax
	sta $2000
	jmp $3000

Symbols are supported. You can specify a label in the code, eg.

top:
	inc $d020
	jmp top

You can also assign values to symbols, eg.

	colour = 0

	lda #colour
	sta $d020

Volatile symbols can be used. If you do this:

	@temp = 10
	.byte @temp

	@temp = 20
	.byte @temp

the compiled output will be 10,20. You cannot export a volatile symbol.

The assembler can also handle arithmetic:

	lda #$00
	sta data
	lda #$01
	sta data+1

data:	.byte 0 0

Arithmetic operators include + - * /, parentheses ( ), and the lo/hi
operators < and >. Square brackets [ ] can also be used, they have the
same action as parentheses. They are included so you can do something
like:

	ldx [$1000+15]*3

If you tried to do this:

	ldx ($1000+15)*3

the parentheses would be interpreted as indirect addressing mode, which
would fail since ldx does not have an indirect mode.

Expressions can be about as complex as you like, eg:

	lda #< $2000 + (data - 5 * (table + 32))

The expression parser cannot correctly resolve some forward references.
For example:

	lda data
        jmp here

	data = $20

here:
        rts

Will issue a warning, since on the first pass the assembler does not know
whether 'data' is 1 byte or 2 bytes long. It will assume 2 bytes, but if
it gets it wrong, some symbols can be evaluated incorrectly. In the above
case, it would cause the value of 'here' to be one more than it should be.
If you get a warning like this, check your code and make sure its really
what you want to do. The above example would work just as well like this:

	data = $20

	lda data
	jmp here

here:
	rts

The symbol '*', on its own, indicates the current memory location. You
can do things like this:

	ldx #$00
	dex
	bne *-2

instead of this:

	ldx #$00
loop:	dex
	bne loop

Comments can be added by preceding the comment with a semicolon.


The following compiler directives are also recognized:

.org location
	- starts a new code segment at this address

.byte expr [,expr]*
	- inserts raw data bytes

.word expr [,expr]*
	- inserts raw data words (standard lobyte/hibyte format)

.end
	- directs the assembler to ignore the rest of the file

.ascii "string"
	- inserts an ascii string. Escapes '\' can be used.

.include file
	- insert another source file at this point

.debug
	- starts a block of debug code. The code in this block is only
	  compiled with the -d switch on the command line.
	  
.enddebug
	- ends a block of debug code

.export symbol
	- marks a symbol for exporting. If the assembler is invoked with
	  the -e switch, a file 'outputfilename.inc' will be created,
	  with a list of exported symbols and their values. You can use
	  this feature to produce header files which can be .included into
	  other files.

.macro
	- starts a macro definition. Paramaters can be used by using the
	  symbols @Px where x is the paramater number. The macro can later
	  be called as %macroname [param] [, param]* . Example:

	  ; branch always
	  .macro bra
		clc
		bcc @P0
	  .endmacro

loop_forever:	%bra loop_forever

	  Note that the parameter symbols are implemented using temporary
	  variables, so they will override any previous declaration of
	  these variables.

	  Also, at this time, there is no checking on macro parameters. So
	  something like this:

	  .macro move
	  	lda #@P0
		sta @P1
	  .endmacro
	  
	  	%move $00, $1000
		%move $20
	
	  will expand to:

	  	lda #$00
		sta $1000
		lda #$20
		sta $1000
	
	  without error. This will be fixed in later versions.

.endmacro
	- closes a macro definition


Acknowledgements
----------------

Contributors
------------

The Mighty Mike Master - many useful ideas (notably the NES images) and
                         the manpage.
Richard Russo - patch to fix LDY zero-page mode.
Karsten Scheibler - several good bug reports in early versions.
Dan Rench - bug report.

Licence
-------

    Orgasm is copyright (C) 1999-2000 Robert Norris <rob@nauseum.org>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

