All included files are Copyright 2000 by Ben Lazo.
All rights reserved, etc...Whatever!

While I've tested these programs extensively, I can take no
responsiblity for any damage, intentional or unintentional
that may result from use of these programs.

If you've enjoyed this program, why not drop me a line at
deathlok@uslink.net and tell me what you think?
--------------------------------------------------------------------------------
RCView
   
   
NAME
   RCView - Deathlok's RedCode Viewer
   
SYNOPSIS
   Rcview <input> <start:0000>
   
DESCRIPTION
   RCView (Deathlok's RedCode Viewer) disassembles and displays
   a RedCode object file (*.obj). It will also take advantage of
   a RedCode map file (*.map) if present. If the Map file is present,
   the labels will also be displayed.

OPTIONS
   <input> Filename to disassemble. ".obj" ending is automatically appended.
   <start> Memory address the program is loaded at. Defaults to 0000.

BUGS
	None known.

--------------------------------------------------------------------------------
RCEmu
   
   
NAME
   RCEmu - Deathlok's RedCode Emulator
   
SYNOPSIS
   RCEmu <input> <input:optional> <# of rounds:optional>
   
DESCRIPTION
   RCEmu (Deathlok's RedCode Emulator) loads and emulates
   a RedCode objects file (*.obj).  Any value returned by
   the object file will be displayed at the termination of the emulation.
   Optionally, two programs may be loaded and made to "fight" each
   other. The one that lasts the longest wins, and appropriate scores
   will be output based on each programs win/lose/draw.

OPTIONS
   <input> Filename to emulate. ".obj" ending is automatically appended.
   <input:optional> Filename to emulate. ".obj" ending is automatically
                    appended. Using this option forces both programs to
                    fight each other.
   <# of rounds:optional> The number of rounds the programs should fight.

BUGS
   None known.

ALGORITHMS USED
   Don't know what you'd call it, but the emulation is 
   basically brute forced. It uses plenty of special cases, 
   mainly because of the quirky way that RedCode expects memory 
   addresses to be calculated (i.e. In register versus in 
   memory evaluation) and because of my lack of Modifier support
   (modifiers are included in the instructions, but are ignored).
   The default modifiers are always used.

SHORTCOMINGS
   As far as I can tell, none. As of this version the emulator runs
   RedCode 100% correctly.  If there is a way to break the emulator,
   I haven't run across it, yet. This includes the infamous
   'Validate.red' program used to determine a RedCode Emulator/Simulator's
   correctness. The Validate program runs perfectly with no errors.
   This program has been included.
--------------------------------------------------------------------------------
RCC
 
NAME
   RCC - Deathlok's RedCode Compiler
   
SYNOPSIS
   RCC <input>
   
DESCRIPTION
   RCC (Deathlok's RedCode Compiler) compiles a RedCode C file (*.rcc)
   into a RedCode assembly file (*.red).
 
OPTIONS
   <input> Filename to compile. ".rcc" ending is automatically appended
           to the input and ".red" ending is automatically appended to
           the output.

BUGS
   Errors are sometimes attributed to the wrong line (always 1 line ahead)
   due to how the lexical scanning works. Newlines will advance the line
   count before whatever was just scanned in is processed, giving the
   occasional wrong line number.

NOT BUGS
   An incorrect filename will still result in a correct compilation. Why?
   Because a file consisting of just EOF is considered a valid program.
   It is a 1 statement block, with the statement consisting of a null
   statement.

ALGORITHMS USED
   The parsing algorithm is your basic top down recursive descent compiler
   algorithm. It works very well because it is simple to set up, simple to
   add to, and makes the code easy to browse (the code follows the BNF
   form very closely.)

SHORTCOMINGS
   Well, recursive descent is harder to make big modifications to. For
   example, because of how the if/else declarations worked, it required a
   major hack to get it working...but it is approximately a billion times
   easier to write than the alternative...at least for my first compiler!

   My biggest fault in the compiler is that there is NO support for data
   declarations, so you can only use the pre-defined A,B,C,D,E,F,G variables
   right now. However, partial support for namemangled function/data names
   is in there and it wouldn't be too hard to finish.

   There is no optimization being done to anything right now, however a
   "peephole optimizer" (to perform simple optimizations before the
   assembly was written to the file)wouldn't be too hard to include.
 
GRAMMER
   (...)* = Optional
   '...'  = Terminal Symbols

   <Program>       ::=     <Block>EOF
   <Block>         ::=     <Statement>|'{'<Statements>'}'
   <Statements>    ::=     <Statement>|<Statement> <Statements>
   <Statement>     ::=     (<If>|<WhileDo|<DoWhile>|<For>|<Break>|
                            <Exit>|<Assignment>|';')*
   <If>            ::=     'if'<Condition> <Block> ('else'<Block>)*
   <WhileDo>       ::=     'while'<Condition><Block>
   <DoWhile>       ::=     'do'<Block>'while'<Condition>';'
   <For>           ::=     'for('(<Assignment>)*';'(<Relation>)*';' 
                            (<Assignment>)* ')'<Block>
   <Break>         ::=     'break;'
   <Exit>          ::=     'exit('<Expression>');'
   <Assignment>    ::=     <Ident>'='<Expression>';'
   <Condition>     ::=     '('<Relation>')'
   <Relation>      ::=     <Expression><Relop><Expression>
   <Relop>         ::=     '==' | '!=' | '<' | '>'
   <Expression>    ::=     <FirstTerm><Addop><Term>
   <FirstTerm>     ::=     <SignedFactor><Rest>
   <SignedFactor>  ::=     ( '+' | '-' )* <Factor>
   <Addop>         ::=     '+' | '-'
   <Mulop>         ::=     '*' | '\'
   <Rest>          ::=     (<Mulop><Factor>)*
   <Term>          ::=     <Factor><Rest>
   <Factor>        ::=     '(' <Expression> ')' |<Ident>|<Num>
   <Num>           ::=     INT
   <Ident>         ::=     ID
--------------------------------------------------------------------------------   
RCAsm
   
   
NAME
   RCAsm - Deathlok's RedCode Assembler
   
SYNOPSIS
   RCAsm <input> <coresize:8000>
   
DESCRIPTION
   RCAsm (Deathlok's RedCode Assembler) assembles a RedCode assembly file
   (*.red) into a RedCode object file (*.obj).

OPTIONS
   <input> Filename to assemble. ".red" ending is automatically appended
           to the input and ".obj" ending is automatically appended to
           the output.
   <coresize>      Target memory size to assemble for. Defaults to 8000.

BUGS
   None known.

ALGORITHMS USED
   The math evaluation is a simple precursor to my compiler. It's basically
   a triple pass recursive descent math compiler, but probably a lot
   bulkier than it needs to be.

   The assembler just assembles in a straight line through the file.
   Because RedCode is very strict in what you can write, there is very
   little that actually needs to be done, aside from interpreting each bit
   of the file as it is read.

SHORTCOMINGS
   Everything works perfectly and has succeeded in assembling everything I
   could throw at it, even the 'Validate.red' file which is the "standard"
   program used to determine the correctness of emulators/simulators.

REDCODE
   RCAsm implements a variant of the ICWS'94/ICWS'88 standard.  
   The new arithmetic instructions MUL, DIV and MOD, as well 
   as post-increment indirect (>) are supported. 
   
   The assembler does NOT support EQU statements.

   The assembler supports a non-standard RET command to return values
   from the emulator to the user.

   The assembler supports non-standard negative number evaluation for
   mathmatic and comparison commands.

REDCODE REFERENCE

   Standard: Modified ICWS'94/ICWS'88 variant (Nonstandard)

   ___________________________________
   Opcodes:

     DAT   terminate process
     MOV   move from A to B
     ADD   add A to B, store result in B
     SUB   subtract A from B, store result in B
     JMP   transfer execution to A
     JMZ   transfer execution to A if B is zero
     JMN   transfer execution to A if B is non-zero
     DJN   decrement B, if B is non-zero, transfer execution to A
     SPL   split off process to A
     SLT   skip next instruction if A is less than B
     CMP   skip next instruction if A is equal to B
     MUL   multiply A by B, store result in B
     DIV   divide B by A, store result in B if A<>0, else terminate
     MOD   divide B by A,store remainder in B if A<>0,else terminate
     RET   terminate all processes, return A
   ________________________________________
   Addressing modes:
   
     #     immediate
     $     direct
     @     indirect using B-field
     <     predecrement indirect using B-field
     >     postincrement indirect using B-field
   ________________________________________
   Expression operators:
   
       Arithmetic:
           +   addition or unary plus
           -   subtraction or unary minus
           /   division
           *   multiplication
           %   modulo (remainder of division)
       Logical:
           !   unary negation
   
       Logical operators return 1 for true and 0 for false.
       Parentheses can be used to override this precedence order:
   
       1) ! - + (unary)
       2) * / %
       3) - + (binary)
   ________________________________________
   
   Case sensitivity
   ----------------
   
   Opcode and pseudo-opcode names are case insensitive; labels are
   case sensitive.
   
   Label declaration
   -----------------
   Labels are declared in this way:
   
    o As an offset relative to the current normal statement. If some
      labels appear just before any '88 or '94 opcodes, they are
      automatically declared as constants that are relative to the
      current statement.

      For example:
      first spl first                0000 spl 0
      imp   mov imp, imp + 1  -----> 0001 mov 0, 1

   RCasm parsing background
   ------------------------
   Parsing is done in two steps:
   1. First pass assembly
   2. Second pass assembly

   1)      Information begins begins to be parsed. Information comments are parsed. All labels are collected.  All labels before opcodes are substituted if they have been declared or   declared otherwise.  All labels after opcodes are preserved for the second pass.  This allows forward declaration mechanism for labels after opcode.
   2)      During the second pass, no labels are declared and collected. All labels that have not been substituted are substituted. Syntax checking to meet with '88 or '94 requirement is done in this stage.  Instructions are parsed using a math statement evaluator and encoded into a 64bit (double) format at this time.

--------------------------------------------------------------------------------   
INSTRUCTION CODING
 00000  000  000   000    0000000000000000000000000 0000000000000000000000000
   OP   MOD  MODA  MODB           ARGA                 ARGB

OPcode can take the following values:
00000	DAT		DATa
00001	MOV		MOVe
		00010	ADD		ADD
		00011	SUB		SUBtract
		00100	JMP		JuMP
		00101	JMZ		JuMp if Zero
		00110	JMN		JuMp if Not zero
		00111	DJN		Decrement Jump if Not zero
		01000	SPL		SPLit
		01001	SLT		Skip if Less Than zero
		01010	CMP		CoMPare arga to argb,skip if equal.
		01011	MOD		MODulus
		01100	DIV		DIVide
		01101	MUL		MULtiply
		01111	RET		RETurn

	MODifier can take the following values:
000		None
001		A
010		B
		011		AB
		100		BA
		101		F
		110		X
		111		I

	MODe A and MODe B can take the following values:
		001		IMM		IMMediate
		000		DIR		DIRect
		010		IND		INDirect
		011		PRE		indirect PREdecrement
		100		POST		indirect POSTincrement

ARGument A and ARGument B are (log2(coresize)) bit signed integers in
standard format.

AUTHORS
The RC project was initiated as a project for the
University of North Texas CSCI 3600 System Programming class.
The person responsible for the code is:
	
	Ben Lazo (deathlok@uslink.net)

ACKNOWLEDGMENTS
   I thank 
      Albert Ma (ama@athena.mit.edu)
      Nandor Sieben (nandor.sieben@asu.edu)
      Stefan Strack (stst@vuse.vanderbilt.edu)
      Mintardjo Wangsaw (wangsawm@csos.orst.edu)
for writing the pMARS system and making the source code available to the
general public.  While I did not use any of their source in the RC project,
pMARS was an invaluable tool for debugging my emulator.
