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

*****
This readme is still under construction.
*****


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 test.asm, flanger.asm, delay.asm, and sinewave.asm. (Do not load
the test.asm as it's only used for testing the assembler with all kinds of stuff)

e.g. to load flanger, type:

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

./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 (MAC_S) : R = A + (X * Y >> 31)   ; saturation
   0x1 (MAC_1S) : R = A + (-X * Y >> 31)  ; saturation
   0x2 (MAC_W) : R = A + (X * Y >> 31)   ; wraparound
   0x3 (MAC_1W) : R = A + (-X * Y >> 31)  ; wraparound
   0x4 (MACINT_S) : R = A + X * Y  ; saturation
   0x5 (MACINT_W) : 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 (LIMIT_1): R = (A < Y) ? X : Y
   0xc (LOG) : ...
   0xd (EXP) : ...
   0xe (INTERP) : R = A + (X * (Y - A) >> 31)  ; saturation
   0xf (SKIP) : ...


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>

	
--

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>

--

Symbol as address reference:

Symbols can be used for referencing an address, this will be usefull for the
SKIP opcode. The assembler assigns the symbol the value of the instruction 
line when the opcode field contains an emu opcode (and not a directive). 
Since the skip command is not yet understood, it servers no purpose at this
point in time.

syntax:

<symbol>

or

<symbol> <opcode> <operands>

The first method causes the symbol to have the same address as if it was used
with the next instruction.

example:

 -- --
     mac_s a,b,c,d

abc

xyz  mac_s d,c,b,a
 -- --

==>abc and xyz are assigned the same address.

--
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 can be enclosed in "" or '' or entered directly.

examples:

	include foo.asm
	include 'qwerty.asm'
	include "foo bar with spaces.asm"
	

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

MACRO directive (NOT YET Supported)

Used for defining a macro

syntax:

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

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

and to use the macro:

	<macro nmeumonic> <operands>


--

Arithmetic in operands:(NOT YET Supported)

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

Syntax (example):

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

(I think this will be useful for the SKIP commands, I suspect that one of the
operands in the SKIP instruction is for the number of instructions to skip thus:

foo  skip ..,bar-foo-1,..
	...
	...
	...
bar  macs  ....

bar-foo-1 is the number of instruction to skip.)
	
--
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)
DO (define output)
DD (define delay line)

orgd will be removed

construct output header and file format.

--

Thats about It. Enjoy.











