                    HUGI SIZE CODING COMPETITION #14
                    (The Unlucky Compo? -- plus one)
                              (hi Boreal)

Rules:  v1.04 (thanks everyone)
 Date:  May 02nd, 2001

Welcome to the Hugi Size Coding Compo #14!  This compo will be a flash
back to compo #09, the SPEW compo. In compo #09, I included a bonus with
my entry of a small assembler that would assemble SPEW source files. (If
any of you remember, it probably would have been better for me to
release it during the compo instead of after the compo! :-) What was I
thinking....)

The object of compo #14 will be to write as small a .com file as
possible to create a .SPU binary image from the given .SAM source file,
ready for the SPEW CPU.

There's more, trust me!

(For those who are new to the hugi-compo or for the rest of us who have
slept since then and have forgotten the SPEW compo, please have a look
at http://home.pages.de/~hugi-compo/ for compo #9.)


COMMAND LINE
~~~~~~~~~~~~
Your program must load the file entered on the command line. The file
name will be a standard 8.3 filename and will start in the normal
position on the command line of 0082h.  You MAY assume anything about
or ignore the extension of the source file name.  However, you must assume
that there will be an extension or atleast the '.' (hi claw)
You may use FCB functions if you see fit.

You may assume that there is a CR (0Dh) char after the extension.


FILE FORMAT
~~~~~~~~~~~
The format of the .SAM files, .SAM being a SPEW assembly source file, is
very similar to x86 assembly source files. Here is part of the included
DEMO.SAM file.

; A test file for SPU.COM
@label1    gosub  @writeit
           db #00D          ; 

@label3    oscall #000

@writeit   popb   @Ptr      ; pop pointer

@Ptr1      db #000
; the end

Notice that the style is the same. There are lables, instructions, a
destination operand and comments. However, notice that there is no
source operand as with most x86 instructions.

Also, notice that each label starts with a '@' char. This is for
simplicity. For this reason, I have required each .SAM source file to
have the following requirements:

  - A basic line format:

       <@label> <instruction> <%register/#literal/@label>

  - Each line will end in a CRLF pair.

  - Each label that is used, must begin with the '@' char and
     START IN COLUMN ONE. Labels will be at least 2 bytes in
     length and can be up to 16 bytes in length which includes
     the '@' char.

  - Tabs are considered illeagal and can be ignored.  Your entry
     does not have to handle tabs.

  - A line may contain only a label if so desired.
     A line may contain only spaces or only a comment.

  - You may assume that a line is not longer than 256 bytes.

  - You may assume that the .SAM source file is less than
      32k in size.

  - If a symbol or operand does not start in column one, you
     may assume it is not a label and most likely is an instruction.

  - Each of the four registers will have a '%' char as the
     first char in the their name.  Again, they will not be
     more than 16 bytes in length. (But they never were :-)
     The following is the initial values of the registers that
       your entry must write to the .SPU file:
            A = #000
       STATUS = #000
          STK = #000
           PC = #100

  - Each immediate used is in HEX form and uses three digits.
     Each should start with the '#' symbol and be no larger
     than 12 bits in value ( 000h <= #symbol <= FFFh ).
       #000 = 000h
       #111 = 111h
       #AAA = AAAh

  - As with x86 assembly source files, a semi-colon (;)
     represents a comment. A comment can be anywhere in the
     file and everything after the semi-colon on that line
     is ignored. You cannot assume that there will be
     a space between an operand and the comment.
     You may not assume that every line will or will not
     have a comment.

  - Your program must allow empty lines, e.g.: a line with only
     the CRLF pair.

  - Your program must account for at most 50 16-byte symbols.

  - If a symbol is found other than the above items, it is
     considered a directive or an instruction.

     - All instructions can be up to 8 bytes long. You may
        assume that all instructions are spelled as COMPO 09
        described them.

     - There is only one directive: The DB directive.
        DB is similar to x86's DB directive, it declares bytes.
        However, there can be only one declaration per line,
        either in the form of an immediate as above, or in
        the form of a string delimited with a single quote
        mark at each end.
          db  #012        ; declare a byte to = 12h
          db  'a string'  ; declare a string of bytes
        Please note that if you need a null terminated string
        (asciz), you must use
           db  'a string'  ; declare a string of bytes
           db  #000        ; make it asciz
        (but this should have nothing to do with your entry :-)

  - You may assume that all symbols and directives will contain
     only the following chars: A-Z, a-z, 0-9, @, %, and #.
     You can assume that if you find a @, %, or #, it will be
     the first char of the operand and it is a legal declaration
     of that specified symbol type.

  - Please note that a comment can contain any char as long as it
     is after the semi colon, not counting the CR or LF chars.

  - You may NOT assume the case of any char in any operand.

  - If any other item is found, you may consider the .SAM file
     in error and ignore it. All .SAM files given for this compo
     should be without errors.

  - EOF defines EOS (End Of Source)  :-)

  - You cannot assume that there will be any given amount
     of spaces between any operand.


OBJECT
~~~~~~
The object of your entry is to take the given .SAM file and create the
binary .SPU file ready for the emulator.

Since most of the competitors here will have taken part in the SPEW
compo some many moons ago, I will not try to explain the detail of the
SPU file. However, I will explain the qualifications for a valid SPU
file:

  (If you are new to the Hugi Compos, please see the Hugi website
   http://home.pages.de/~hugi-compo/ for info about the SPEW CPU,
   located in the compo #9 pack.)

  - You must create a file with the same name as the source file
     given, except that the extention should now be .SPU
     (letter case does not matter).

  - The first 256 bytes of the SPU file must be as follows:
     The first 20 bytes must be:
       ( <space> = char 32 )

       13, 10, 'Hugi<space>Compo<space>#14...', 1Ah

     While the rest of the 236 bytes must be nulls.

  - When you need to add filler to your .SPU image file to make
     it 4k in size, this filler must be null bytes.

  - Other than that, as long as your .SPU image matches byte for byte,
     the included TEST.SPU image, you have a correct entry.
      (As long as the included TEST.SPU file(s) are correct to the
        rules of both this compo and compo #9.)

  - Even though the included SPU.COM file does a little (and I mean
     a little) error checking, your entry does not have to check for
     syntax errors.
     Your entry may assume that the given .SAM file is correct and
     has no errors. Your entry may do as it wishes if the given
     .SAM file has errors.

  PLEASE remember that even though your produced .SPU file matches
   the test.spu file(s), please test it on other .SPU files generated
   with the given SPU.COM program.


TEST PROGRAM
~~~~~~~~~~~~
A test program is also included in this pack. Adok will use it to verify
that your entry executes properly. Your program should be named

"ENTRY.COM"

Please note that passing the test program does not guarantee that your
entry has followed all the rules. It's quite possible that a loop hole
exists. Check the Hugi website (http://home.pages.de/~hugi-compo/) and
the Yahoogroups Hugi-compo mailing list for updated test programs.

Besides the rules described in this document, you must comply with the
general rules that apply to all Hugi Size Coding Competitions. These are
described in the file GENERAL.TXT.

If you are unsure about some detail then please post a question to the
Hugi-compo mailing list (hugi-compo@yahoogroups.com).

After the compo deadline a period of public judgment occurs during which
you and others determine penalties for rule violations.


SCHEDULE
~~~~~~~~
Apr 15, 2001               Compo starts
Jun 15, 2001 11:59 pm CET  Deadline for entry submission
Jun 16, 2001               Entries and beta results released
                           Start of Public Judgment
Jun 22, 2001 11:59 pm CET  End of Public Judgment
Jun 23, 2001               Final results will released


CREDITS
~~~~~~~
Since I pretty much stole some of this text from the previous compo,
most of the thanks and credits go to the previous authors of this file.
:-)

I have attached the source code to SPU and EMU as well as the .COM file
for EMU for your interest.

Use SPU.COM to create *correct* .SPU files for testing your entry.

Use EMU.COM to run you .SPU files. (just for your interest)

The source to SPU and EMU is x86 assembly and assembled with:

  NBASM  at  http://www.cybertrails.com/~fys/newbasic.htm

Thanks,
Sniper

If you have any questions or comments, please feel free to post them
to the hugi-compo mailing list, or flame me personally. :-)
