
        h u g i   s i z e   c o d i n g   c o m p e t i t i o n   # 9

                                 infofile v1.1


Welcome to a new coding competition.
Summer  is  ending, the colder time of the  year  is about to start. At least
this  means  that you will spend less of  your spare time outside and more at
home, perhaps in front of your PC, working on your entry for this compo. This
is  the  4th  Hugi Size Coding Competition  in  this  year. The task, an easy
emulator  for a fictional cpu, has been  established by fair voting. Here are
the  rules,  written  by TAD and Ruud v. Gessel.  I hope  you will  enjoy the
compo.
                                                  Adok/Hugi, August 24, 1999.

--------------------------------- [THE TASK] --------------------------------

Credits for the initial drafts of the rules go to TAD, Ruud.
Credits for the test-suite and programs go to TAD, Ruud, vulture, GreenGhost.

This  task for this compo is to code an emulator for a very simple cpu called
"SPEW" (or "SPU"). It is a purely fictional cpu and doesn't exist in the real
world.  It  was  invented  entirely  for this  compo  so  you  won't find any
reference  to  it  anywhere  else. One  reason  for  creating an entirely new
instruction  set  was to make its emulation  as simple as possible.  Like all
the  previous  Hugi Size Coding Competitions you  must try to make your final
program  as small as possible. In this case it means your final SPEW emulator
must take up as few bytes as possible.

Details:

Given  the filename of a 4Kb (4096 byte) .SPU image on the command-line, load
this  file  into  memory, then decode  and  execute  each SPEW instruction as
explained  elsewhere  in  this document. Each  .SPU  image is a collection of
code,  data,  stack  and buffer bytes. In  short  it  is a self contained 4Kb
program image where addresses only have a 12-bit range (000 to FFF hex).

Your  emulator needs to fetch each  SPEW instruction word, decode it, perform
the  correct  operation(s) and then continue  onto  the next instruction. The
instruction-set  itself contains the necessary termination code. Once this is
decoded and executed your emulator will automatically terminate.

The size of your emulator will be judged, the smaller it is, the better!

-----------------------------------------------------------------------------
                         Basic outline of the SPEW cpu.
-----------------------------------------------------------------------------

It  is  a  simple 4Kb (4096 byte) cpu  so  it  only needs a 12-bit address to
access any byte within its memory. Within this 4Kb of memory are 4 registers.

        A       - 8 bit accumulator (general purpose) register
        STATUS  - 8 bit flags register
        STK     - 16 bit stack pointer
        PC      - 16 bit (program counter) instruction pointer

All 4 registers are mapped within the 4Kb addressing range.

 mem[F00]               A               - accumulator
 mem[F01]               STATUS          - status register
 mem[F02]..[F03]        STK             - stack pointer
 mem[F04]..[F05]        PC              - program counter

This  means  that  mem[F00]  refers to  the  "A"  (accumulator)  register and
likewise  mem[F02]  and mem[F03] refer to the  16-bit value of the STK (stack
pointer).

Although  two-byte memory locations and registers  may contain a 16-bit value
only the lowest 12-bits should be used to access the cpu's 4Kb of memory.

For  example ALL these 16-bit values refer to  the same address in the 4Kb of
SPEW memory:

        0123 hex = mem[123] hex
        1123
        2123
        3123
        4123
        5123       " "
        6123
        7123
        8123
        9123       " "
        A123
        B123
        C123
        D123
        E123
        F123 hex = mem[123] hex

The  SPEW  cpu  is  RISC-like in  the  instruction-set,  there are no complex
addressing   modes,   prefix-bytes,  overrides   or   extension  bytes.  Each
instruction  occupies exactly ONE word of  memory. The normal Intel low, high
byte  ordering is used for double-byte  (word) addresses and values stored in
memory.

It  can only communicate with the outside  world by using a restricted set of
INT  21h  service  calls and by reading  directly  from the first 4Kb of host
PC/system  memory  in order to examine  things like key shift status, current
video mode and so on...

-----------------------------------------------------------------------------
                              SPEW memory details
-----------------------------------------------------------------------------

Memory:
          -  ALL  of the 4 registers  (A, STATUS, STK and PC) are
            held  and manipulated in memory.  The SPEW cpu has no
            external registers, certain memory locations are used
            for this purpose.

          -  ALL  memory addresses are MOD 4096  (i.e. 000 to FFF
            hex). This means 532Eh hex  will become mem[32E] hex.
            Only the lowest 12-bit are used.

          -  A  word access across the  4Kb limit is NOT allowed.
            This  means an address of FFF  hex is illegal for one
            of the double-byte operations like GOSUB, RETURN RDI,
            WRI  and ADDW. Your emulator  does NOT have to handle
            this.  You can assume that all word accessing is done
            on  addresses  000..FFE hex  (ignoring bits 15..12 of
            course).

          -  The  PC and STK register  may contain a 16-bit value
            (such as F123 hex) but only  bits 11..0  will be used
            to access memory (i.e. 123 hex).

          -  The  indirect "RDI"  and  "WRI" instructions require
            that a word (2-bytes) is read from memory and used as
            an address-pointer. Again only bits 11..0 are used to
            to access memory, bits 15..12 are simply ignored.

          -  The  normal low, high byte  ordering is used for all
            double-byte  (word) operations (just like the 80x86).
            So the value 1234 hex is stored as 34h, 12h.

          -  The  Host PC  memory [0000:0000]  to [0000:0FFF] hex
            can be read using the "RDSYS" instruction.

          -  EVERY one of the SPEW cpu's 4096 bytes is r/w. There
            is  _NO_  ROM  or  memory  protection,  every  memory
            location can be read from, or written to.


Input/Ouput:

          -  All communication  is  performed  via  the  "OSCALL"
            (Operating-System CALL)  instruction.   This   is   a
            limited set of the standard INT 21h services.

          -  The only exception is the  "RDSYS" instruction which
            peeks into  the lowest 4Kb of the  host PC memory and
            returns the byte in the A (accumulator) register.

-----------------------------------------------------------------------------
                              The SPEW memory map
-----------------------------------------------------------------------------

Boot up:
          -  A 4Kb  (4096 byte)  .SPU image  is loaded  from disk
            (the  filename  of the image  will be  on the command
            line).

          -  The memory locations mem[000]..[0FF] are loaded with
            the pre-set values of 00..FF hex.

          -  Fetch  the  first instruction  pointed  to by the PC
            register  (mem[F04]..mem[F05]  hex)   and   then  the
            decoding/execution process begins...

          -  You do not have to  initialise any memory registers,
            they  will already  have their correct values defined
            in the 4Kb .SPU image.

12-bit Address
==============
000..0FF hex    = pre-set values 00..FF hex (after boot-up)

100..EFF        = code/data area

F00             = "A" (accumulator) register
F01             = "STATUS" register
F02..F03        = "STK" register (16-bit stack pointer)
F04..F05        = "PC" register (16-bit instruction pointer)

F06..FFF        = default stack area

---------------------------------------------------------------
mem[F00] - the A (accumulator) register
---------------------------------------------------------------
This  is  a general purpose  8-bit  register through which almost
every operation is carried out.

---------------------------------------------------------------
mem[F01] - the STATUS (flags) register
---------------------------------------------------------------

The  STATUS register format is identical  to the 80x86 FLAGS bits
7..0,  except the VF (overflow flag) must be  duplicated into bit
position 3.

Bits 5 and 1 of the 80x86  FLAGS register  are *undefined* but in
the  STATUS  register they MUST  be 0 after a "STATUS<--<--flags"
translation.  This  translation  occurs  after  the OSCALL, ADCA,
SBBA, ORA, ANDA, XORA instructions.

        F E D C B A 9 8 7 6 5 4 3 2 1 0     - 80x86 FLAGS register
        * * * * V * * * S Z - A - P - C
                
                
                Ŀ
                                
                                
                        S Z # A V P # C
                        7 6 5 4 3 2 1 0     - STATUS register

*       - these bits should NOT be modified

#       - these bits MUST be zero in the STATUS reg.
                        7 6 5 4 3 2 1 0     - STATUS register
                        x x 0 x x x 0 x

V       - overflow flag
S       - sign flag
Z       - zero flag
A       - Aux. flag
P       - Parity flag
C       - Carry flag

---------------------------------------------------------------
mem[F02] & mem[F03] - the 16-bit STK register
---------------------------------------------------------------
These 2 locations contain the 16-bit stack pointer register.
Only the lower 12-bits should be used when accessing memory.

The value is stored in the standard Intel (low, high) format.

i.e.
        value = mem[F02] + ( mem[F03] * 256 )

---------------------------------------------------------------
mem[F04]..mem[F05] - the 16-bit PC register
---------------------------------------------------------------
These  2 locations  contain  the  16-bit program-counter register
value.  (The Instruction Pointer). Only the lowest 12-bits should
be used when accessing memory.

The value is stored in the standard Intel (low, high) format.

-----------------------------------------------------------------------------
                            The SPEW instruction set
-----------------------------------------------------------------------------

There  are only 18 instructions in the SPEW cpu and each one occupies exactly
one word (a double-byte) of memory. A much more detailed description of every
instruction can be found in the SPEW.TXT text file.

Hex     Mnemonic                Brief description
                    
00xx    OSCALL xx               Use an OS call (int 21h service)
0xxx    JP xxx                  Jump to new PC address
1000    RETURN                  Return from a GOSUB call
1xxx    GOSUB xxx               Go (call) a sub-routine
2xxx    PUSHB [xxx]             Push a byte onto the stack
3xxx    POPB [xxx]              Pop a byte from the stack
4xxx    LDA [xxx]               Load A (accumulator) from memory
5xxx    STA [xxx]               Store A into memory
6xxx    RDI [(xxx)]             Read an indirect byte using mem-ptr
7xxx    WRI [(xxx)]             Write an indirect byte using mem-ptr
8xxx    RDSYS [0000:0xxx]       Read byte from system ram[0000:0xxx]
9xxx    ADDW [xxx],A            Add sign-extended A to word variable
Acpp    JPcc +pp                Jump if the condition is true
Bxxx    ADCA [xxx]              A + mem[xxx] + CF
Cxxx    SBBA [xxx]              A - mem[xxx] - CF
Dxxx    ORA  [xxx]              A OR mem[xxx]
Exxx    ANDA [xxx]              A AND mem[xxx]
Fxxx    XORA [xxx]              A XOR mem[xxx]

---------------------------------------------------------------

ENTRY.COM:

This MUST do the following in THIS order:

  1. Read the .SPU filename from the command-line.
     (The .SPU file must always  be in the same directory.  Hence, no need to
     handle paths.)

  2. Load this 4Kb .SPU image into memory.

  3. Initialise the following image values:

        mem[000]..mem[0FF]      = 00..FF hex

  4. Begin the emulation at the address in the PC register
     (the mem[F04] and mem[F05] locations).

  5. Continue until the termination instruction is met.
     (The termination will be in the form of a "OSCALL 00"
      or "OSCALL 4C" instruction.)

It must NOT do the following:

   - crash (provided the specified .SPU file is a valid .SPU image)
   - use any external files
     (except the .SPU file specified in the command line)
   - rely on any previously loaded code or data in memory
   - create any new files on disk

ENTRY.COM registers:

You may assume that the registers have these values (all in hex):
(xx - means an unknown value which MUST NOT be assumed)

            AX = 0000
            BX = 0000
            CX = 00FF
            DX = CS = DS = ES = SS = xxxx

            SI = 0100
            DI = FFFE
            BP = 09xx
            SP = FFFE
            IP = 0100

Other rules for the entry:

The execution time of ENTRY.COM using the included test-suite must not exceed
5 minutes on Adok's computer (a standard Pentium 200).

You must not disable interrupts (CLI).

Checking:

The  output from your emulator program will be taken and checked against that
expected  by  the  test suite. If your  emulation  is  100% correct then this
output  will  also be correct. If your  emulator's output does not match then
your emulator is considered as being flawed.

As always, your entry must...
                          ...have the filename entry.com.
                          ...work in Windows95 DOS box.
                          ...work at least on Adok's PC.
                          ...exit without crashing when regular input.
                          ...not depend on its filename.

All instructions till .586 (Pentium) can be used.  (This does NOT include MMX
or any other non-Intel instructions).

Your entry does not have to work with LOADHIGH.

  !! Please check if your program fits to all rules before submitting it !!

The  included  file  testit.bat  tests  whether  your  emulator  program runs
correctly by means of verifying its output. Adok will check your entries with
the same program.

--------------------------------- [EXAMPLE] ---------------------------------

An example program by vulture has been included (example.zip).
An example NASM program by GreenGhost has been included (test2.zip).

-------------------------------- [SUBMISSION] -------------------------------

You have to send

() the sourcecode of your emulator
() the executable of your emulator ("entry.com")

to Adok so that he can analyse and evaluate your entry.

Send your entries to:
                         hugi@netway.at

It  would  be best if you could submit  your entry as early as possible. Then
Adok  can inform you about bugs, if he finds any, and you have enough time to
fix  them.  Attention: if he finds  no  bugs, this doesn't automatically mean
that your entry is bug-free.

You can submit updates to your entries all the time till the deadline.

Entries that do not agree with these rules will be disqualified. Their coders
will be informed about the mistake, and they can re-submit a bugfixed version
unless the compo is over.

If  the  compo  is over and a hidden  flaw  is found in one of the originally
accepted  entries during the public judgement period, the best older entry of
this competitor that fits all the rules will qualify instead.

------------------------------- [PRE-RESULTS] -------------------------------

Preliminary  results of this compo will be released on the compo-web-site and
always  updated  after  receiving  a new entry.  In  this  way the compo will
hopefully be exciting.

Compo-web-site URL:
                     http://home.pages.de/~hugi-compo/

If that URL does not work, try:
                     http://hugi.foxfiber.net/compo/

--------------------------------- [SCHEDULE] --------------------------------

Aug 26, 1999                   Compo starts
Oct 31, 1999, 11:59 pm cet     Deadline for entry submission, compo is over
Nov 01, 1999                   Entries and beta results will be released,
                               Start of public judgement
Nov 07, 1999, 11:59 pm cet     End of public judgement
Nov 08, 1999                   Final results will be released

----------------------------- [PUBLIC JUDGEMENT] ----------------------------

After the deadline for entry submission,  as soon as the entries and the beta
results  are released, the public judgement starts.  During this week you can
discuss  and object to the entries that  seem to break some rule. Please send
your  objections  to  the compo-mailinglist (see  below).  Adok and/or a jury
formed  by  him will check if your  objections are according to the rules. If
they are, the invalid entry will be disqualified.

---------------------------------- [PRIZES] ---------------------------------

I'm  sorry if I disappoint you, but  there are no material prizes. Everything
is  just  a matter of honor and  fame. Moreover, the 30 best competitors will
get  points and be listed in the 'World League Table of Assembly' situated at
the  compo-web-site.  Reaching a good place at  a  compo and even more in the
World League Table of Assembly is a good visiting-card and recommendation for
every competitor!

------------------------------- [MAILINGLIST] -------------------------------

The  purpose of the Hugi Compo Mailinglist  is to inform about new compos and
provide a discussion forum for the competitors. At the moment there are about
150 subscribers.

To  subscribe send a mail  to hugi-compo-subscribe@egroups.com. You'll get an
automatically  generated  mail which confirms  your subscription within a few
hours.  Then  you  start  getting the mails  the  others  have posted to this
mailinglist.

Mails for the list have to be sent to:
        hugi-compo@egroups.com

If you want to unsubscribe, send a mail to:
        hugi-compo-unsubscribe@egroups.com

-------------------------------- [ADDRESSES] --------------------------------

Send your entries to:
                                         hugi@netway.at        [Adok/Hugi]
Compo-homepage
(pre-results, world league table, etc.)
                                         http://home.pages.de/~hugi-compo/
Subscribe to the mailinglist:
                                         hugi-compo-subscribe@egroups.com

-----------------------------------------------------------------------------

Thanks for reading this info file!
