
AS10k1 Assembler version 0.1
----------------------------

This is an assembler for the emu10k1 DSP chip present in the creative SB
live and PCI 512 sound cards.

Author: Daniel Bertrand <d.bertrand@ieee.ca>

compiler.c and compiler.h were written by Rui Sousa (one of the emu10k1 linux
driver authors).


Installation:
-------------

untar the package, cd into as10k1 directory, type "make" enjoy!

type:
	tar zxfv as10k1-DATE.tgz
	cd as10k1
	make


You'll also want to get the "load" and "dump" programs distributed with the
linux drivers. If you don't have them you can get them at:
opensource.creative.com
	
		
Usage:
------

as10k1 <asm file> <bin output file> [<constants output file>]

The bin file will contain the actual dsp code, the constants file will contain 
constants define using the DC directive. Both files are loaded seperately on to
the emu10k1, use "load" for the dsp code, and "loadconst" for the constants. 

**This annoyance is only temporary and will be rectified once a proper file 
format is defined.


For examples see flanger.asm, delay.asm, and sinewave.asm. 

e.g. to load flanger, type:

./as10k1 blank.asm blank.bin   (assembles a dummy blank file for clearing 
				the emu10k1)		

./load blank.bin      				(removes the digital mixer)
./as10k1 flanger.asm flanger.bin flanger.cst    (assembles the flanger)
./loadconst flanger.cst 		(it's best to load the constants first)
./load flanger.bin		( after this one you should hear the flanger,
				 only applies to the PCM and rec-source)


If you load something and get annoyed, load blank.bin to clear the emu10k1.
 
Loading dsp programs will break the digital mixer, to reset the dm you can 
reload the module ( as root : /sbin/modprobe -r emu10k1 ).   

Assembly Syntax
---------------

Assembly lines generally have four fields seperated by spaces or tabs:


Name_Field   Opcode_field    Operand_Field   Comment_Field
----------   ------------    -------------   -------------
[symbol]      [mnemonic]      [operands]       [text]


With this assembler, each line can have a maximum of 80 characters and each
symbol can be a maximum of 11 characters. Symbols ARE case sensitive, opcodes
ARE NOT.

OPCODES
--------


All instructions require 4 operands, they have the format

	<opcode> R,A,X,Y
	
(note some documentation out there the call the R operand as Z and the A
operand as W).

Here are 16 opcodes.

   0x0 (MACS) : R = A + (X * Y >> 31)   ; saturation
   0x1 (MACS1) : R = A + (-X * Y >> 31)  ; saturation
   0x2 (MACW) : R = A + (X * Y >> 31)   ; wraparound
   0x3 (MACW1) : R = A + (-X * Y >> 31)  ; wraparound
   0x4 (MACINTS) : R = A + X * Y  ; saturation
   0x5 (MACINTW) : R = A + X * Y  ; wraparound (31-bit)
   0x6 (ACC3) : R = A + X + Y  ; saturation
   0x7 (MACMV) : R = A, acc += X * Y >> 31
   0x8 (ANDXOR) : R = (A & X) ^ Y
   0x9 (TSTNEG) : R = (A >= Y) ? X : ~X
   0xa (LIMIT) : R = (A >= Y) ? X : Y
   0xb (LIMIT1): R = (A < Y) ? X : Y
   0xc (LOG) : ...
   0xd (EXP) : ...
   0xe (INTERP) : R = A + (X * (Y - A) >> 31)  ; saturation
   0xf (SKIP) : ?,?,?,<GPR contain # of skips>


For more details on the emu10k1 see the dsp.txt file distributed with the
linux driver.

Operands
--------

Operands can be specified as either a symbol or a value. hex values are
prefixed by $, octal by @.

e.g.:

123 decimal value
$123 hex value
@123 octal value

Note instructions be sure to use commas to seperate your operands, a space
will not work with this assembler.

Features Currently Supported:
=============================

( <> brackets indicate required fields, [] brackets indicate optional fields)

DS  directive:

Defines a storage space from the gpr pool on the emu10k1. The
assembler maintains a pointer to the gpr registers (starting at $100). The
symbol is assigned the value of the address of the gpr pointer. The pointer is
increment by the number following the DS directive.

syntax:

<symbol> DS <number of storage spaces>

--
DC directive:

Similar to DS but places an initial value in the memory location.

Note: A proper file format for storing the compiled programs has not been 
created yet, in the mean time the DC are stored in there own file and are 
loaded seperately using the 'loadconst' utility. 

syntax:

<symbol> DC <initial value>

	
--
**to be obsoleted**
ORGD directive

Sets the assemblers gpr address pointer, the next DS/DC will be located at this
new orgd origin.

syntax:

[symbol] ORGD  <new gpr pointer>

--
EQU directive:

Equates a symbol to a be constant which is substituted at assembly time:

syntax:

<symbol> EQU <Value equated>

--
END directive

The END directive should be placed at the end of the assembly source file. If
the END directive is not found, a warning will be generated. All text located
after the END directive is ignored.

Syntax:

[symbol]  END

--
INCLUDE Directive

The include directive is used to include external asm files into the current 
asm file.

Syntax:

	INCLUDE <"file name">

The file name Must be enclosed in "" or '' .

examples:

	include 'qwerty.asm'
	include "foobar.asm"
	

--	

MACRO directive 

Used for defining a macro

syntax:

<symbol> macro 
	....
	<opcode> /1,/3,/2     ;;for example
	....	
	....
	endm

were the <symbol> used is the nmeumonic representing the macro.

and to use the macro:

	<macro nmeumonic> /1,/2,/3,...

where /1,/2,/3,... are values or symbols.

You don't need to specify how many operands you need when declaring the macro,
However, if you use more in the macro than you specify when using it the
assembler will generate an error.

You can use up to 10 operands.

--

		
Features NOT YET Supported
========================

Arithmetic in operands:

Assembly time arithmetic in the operands (add, sub, div, and mult):

Syntax (example):

	<opcode> foo+bar,foo/bar,bar*foo,(foo-bar)*foo

This will be usefull for the assembly-time FOR statement.

--

Assembly time FOR statement.
name says it all.

--
Patch Manager:

Support for the Patch manager being developed for the emu10k1.
To Do:

DS will be automatic registers
DC will be static

perform a check for "using a gpr without first declaring it"

Introduce DI  (define input) and DO (define output)

introduce method to define delays and tables.

orgd will be removed.

construct output header and file format.

--











