!! Please note that this assembler in its current state
is incomplete, suffers from bugs, and should only be used 
at your own risk !!

An understanding of lex/yacc and of the relevant IL and ISA 
documents for 69XX hardware is required before beginning. 

One is well advised to write an il version of one's program 
and to study its disassembly it in order to gain a starting 
point for one's own code.  This is particularly important
for constructing a suitable "info" file that determines the
image's note segment.  The hardware documentation is 
incomplete in this regard and multiple il programs were 
disassembled in order to figure out how this should be
done.  To help with this, in the utils/ directory I have
provided two little programs and a script:

ilimg: This takes 3 arguments.  The first is a text file
holding an il program, the second is the name of the elf
file to be generated and the third is the name of a text 
file to be generated containing the ISA disassembly.

imgdisasm: This takes 2 arguments.  The first is an elf file
to be disassembled, the second is the name of a text file to
be generated containing the ISA disassembly.  

ilisaelfinfo.sh: This takes 1 argument, the root (i.e. no .elf)
part of the filename of an elf file that contains both il and isa
images (the usual type).  It outputs .dump, .text and .load files
to be compared with those coming from asm69.sh itself (see below).

One should have mingw installed and run everything from
a mingw shell.

Enter the src/ directory and build the program using the
buildall.sh script:

sh buildall.sh

Put assembly code in a text file of the form fileroot.gsa, 
with "fileroot" being arbitrary.  Prepare a "setup" file
describing the program's resource requirements, and name it
fileroot.setup .   For now, both files need to be in the 
same directory as asm69.sh.

Assemble the code, generating lots of information, with:

sh asm69.sh fileroot 

As the assembler currently emits a lot of debugging
information, you may wish to pipe its output to a file:

sh asm69.sh fileroot > tmp

The key output file is:

fileroot.elf -- an elf image file, ready to run on the GPU

Other output includes:

fileroot.dump -- a readelf description of the image file
                 followed by an octal dump of it

fileroot.text -- an octal dump of the text segment

fileroot.load -- an octal dump of the program note  

By using the above-mentioned imgdisasm program, one can
often obtain error messages about problems in one's assembly.

At this stage of development full documentation is not
available; a study of the lex/yacc source code files 
(in src/)  by the user is necessary to understand the 
syntax.

In the examples/ directory, there is an example .gsa program 
along with code to run it.  At present there seems to be a 
bug somewhere; the final matrix does not seem to be correct.

Some quick notes about the assembly language:

As of now only pixel shaders are supported.

One can use labels to avoid having to refer explicitly
to addresses in things like loops.  The assembler will
work it all out.  LAB:# marks a position, and ADDRLAB:#
refers to the address of the label.  E.g.

LAB:1
...
LOOPEND ADDRLAB:1

ALU instruction groups are separated from each other 
by a new line; white space is important here.  At present 
the last instruction in each group needs to have a 
trailing "L" to indicate it needs its last bit set;
this inconvenience should shortly be removed.

Integer constants may be used, as can floating point
ones.  The latter should include a decimal point and
be followed by an "f".

Vectorized versions of instructions are available,
including VECMULADD, VECMUL, VECADD, VECMOV and VECZERO,
along with simplified SAMPLE instructions.

While the control flow and ALU side is substantially 
complete (except for extended instructions), only simple 
forms of fetch clause instructions are currently 
implemented.  There is no obstacle in principle to 
lds/gds support, but that has not been done at present.


