

  COMMANDS
  --------

 This file details all the valid commands in the REDCODE instruction set
supported by the archimedes version of Corewars. Some vary from the official
specifications, and these originate from a Macintosh computer version of
corewars. PCT is included because I think it is a good extension, and the
others, JMG and DJZ, are included for compatibility reasons. It is advised
that you do not use these last two commands in any new programs that you
write.

 See the file Intro for information about how the instructions are stored and
an explanation about the operand fields etc.


 The compiler directives are as follows:
                            

Addressing modes - there are four different addressing modes possible;
immediate, direct, indirect and post-decremental indirect, the symbols for
which are detailed here:

 # is placed before an expression to indicate that immediate addressing
should be used; ie. 'dat #0'  - puts the actual value 0 in that cell

 @ is placed before an expression to indicate that indirect addressing should
be used; ie. 'mov #0,@bombpt'  - moves a zero into the cell pointed to by the
cell 'bombpt' (offset relative to bombpt, not executing instruction).

 alternatively, @ is also used at the beginning of a line to indicate the
offset to the start of the program; ie. '@-4'  - assemble the following inst-
ructions at the cell four cells behind of the point where the program will
initially be called. There must be a @ used in this way before any instruct-
ions can be compiled, and an error will be generated otherwise.

 < is placed before an expression to indicate that post decremental indirect
addressing should be used; ie. 'mov #33,<bombpt'  - decrements the value
stored at 'bombpt' and moves the immediate value 33 into the cell pointed to
by the new value of 'bombpt'

 $ is placed before an expression to indicate that direct addressing should
be used, although any expression without either a #,@,< or $ will be treated
as direct; ie. 'mov $rubbish,$bin'  - copies cell 'rubbish' into cell 'bin'
(Could be rewritten 'mov rubbish,bin').
                                                                             

There are various other symbols which serve a purpose when compiling REDCODE:


 . is used at the beginning of a line to indicate a label. A label can be
upper or lower case letters, and may contain numbers, except in the first
character. When being matched, case is not considered. An instruction may
follow the label, seperated by a space; ie. '.imp2 mov 0,1'  - this cell can 
be referred to as 'imp2' and contains a simple one-line program. Otherwise,
the label is the only thing on the line; ie. '.start'.

 , is used to seperate operands in a REDCODE instruction;ie 'djn loop,label'.
It is not essential, however, and is ignored by the compiler, so the previous
example could legally be rewritten 'djn   loop  label' (extra spaces in any
part of the line are also ignored).

 >, * and ; are comment characters which tell the compiler to ignore the rest
of the line following any of them. This is so that comments may be included
in REDCODE; ie. '.dwarf1 add #5,bombpt  ; add 5 to bomb pointer'.

 ( and ), brackets, are allowed in expressions, but do not influence the
order of evaluation. They are in fact ignored, but included for compatibil-
ity; ie.  'mov #3-(2-1),datapt' is treated as 'mov #3-2-1,datapt' so the
value stored at datapt is 0 not 2.
                                                      
 + and - can be included in expressions evaluating to a cell location/value,
and used in conjunction with a label if desired (which will usually be the
case); ie. 'mov dwarf+1,@dest' - moves the cell one in front of 'dwarf' to
the cell pointed to by the cell 'dest'. Other operators such as *, / etc. are
not allowed. Also, expressions such as '@ beginning-7' are disallowed (the
variable 'beginning' being assigned a value relative to the current offset
set by @).
    

                                           
REDCODE instructions:-
                      
Syntax = [.label] [,] <MNEMONIC> [,] <operand A> [[,] [<operand B>]]

 The actual REDCODE instructions (case insensitive) are:-

 DAT A       A can be an immediate value (#) or a direct value (treated as an
immediate value)

 (data)

 This instruction reserves a cell of MARS memory for data. The data value is
initialised to the A-value. An attempt to execute it causes the executing
side to lose a line of execution, or split, or in other words, die.
 DAT has two uses: to provide data for your program, and to provide
impediments to your opponent's program. DAT instructions can be MOV'ed wildlyinto core with the hope that the opposing program will try to execute them.
                                      

                          

 MOV A,B     A can be any addressing mode, and B can be any mode except
             immediate (#)
                                        
 (move)

 The cell at the A-location is copied to the B-location, replacing the
B-location's old contents, or, if the B-location is protected, just removing
the protection of that cell, so that the next attempt to write will succeed.
 If the MOV instruction has an immediate A-location, then the immediate value
is copied to the A field of the B-location, and every other field set to
zero, so in effect the B-location becomes a DAT <A-value>. ** NB This is at
variance with the official specifications, which alter different fields. **
 If the A-location is not immediate, then all fields (opcode and both
operands) are copied across.




 ADD A,B     A can be any addressing mode, and B can be any mode except
             immediate.

 (add)

 The value at the A-location is added to the B-location, replacing the B-
location's old contents.

                        


 SUB A,B      A can be any addressing mode, and B can be any mode except
              immediate.

 (subtract)

 The value at the A-location is subtracted from the B-location, replacing the
B-location's old contents.




 JMP A         A can be any addressing mode except immediate.

 (jump)

 The A-location address replaces the program counter for the current split
(line of execution), causing the instruction at that location to be executed
next when that particular split is next executed (if you follow that...)




 JMZ A,B       A and B can be any addressing mode except immediate.
  
 (jump if zero)

 If the A-field value of the B-location is zero, a jump will be done to the
A-location, as described in the JMP instruction, above. Otherwise, execution
continues with the next sequential instruction.




 JMN A,B       A and B can be any addressing mode except immediate.

 (jump if not zero)

 If the A-field value of the B-location is not zero, a jump will be done to
the A-location, as described in the JMP instruction, above. Otherwise, exec-
ution continues with the next sequential instruction.




 JMG A,B       A and B can be any addressing mode except immediate.
 
 (jump if greater than zero)

 This instruction is synonymous with JMN (because there is no negative data
...see section 'intro' for information).  ** NB This is not an official
instruction, and you should use JMN instead **




 DJN A,B       A and B can be any addressing mode except immediate.

 (decrement and jump if not zero)

 The A-field value of the B-location is reduced by one, and then tested. If
it is not zero, a jump will be done to the A-location, as described in the
JMP instruction, above. Otherwise, if it becomes zero, execution continues
with the next sequential instruction. The A-field value of the B-location is
reduced by one whether or not the jump is taken. The value is tested after it
is decremented, so if it was zero before the instruction is executed, it will
be decremented to memory size minus one, and the jump will be taken.




 DJZ A,B       A and B can be any addressing mode except immediate.

 (decrement and jump if zero)

 The A-field value of the B-location is reduced by one, and then tested. If
it is equal to zero, a jump will be done to the A-location, as described in
the JMP instruction, above. Otherwise, if it is unequal to zero, execution
continues with the next sequential instruction. The A-field value of the
B-location is reduced by one whether or not the jump is taken. The value is
tested after it is decremented, so if it was zero before the instruction is
executed, it will be decremented to memory size minus one, and the jump will not be taken. ** NB This is not an official instruction **




 CMP A,B       A and B can be any addressing mode.

 (compare)

 The value or values at the A-location are compared to the value(s) at the B-location. If they are unequal, the next instruction is skipped. If they are
equal, the execution continues with the next sequential instruction. If the
CMP instruction has an immediate operand, then only the A-field value at the
cell referenced by the other operand is compared to the immediate value.
 Otherwise all fields (opcode, operands) are compared to the corresponding
fields of the B-location, and all three fields must be equal for the A-
location value and the B-location value to be considered equal.




 SPL A         A can be any addressing mode except immediate.

 (split)

 This instruction splits the execution of the program between the currently
running program and the program beginning at the B location (the 'sibling'
program). From that point on, a program's execution cycles are divided
among all of its siblings. A program which has split twice with the SPL
instruction will run as three seperate sibling programs, each of which will
execute every sixth machine cycle.
 For the purposes of this explanation, the set of sibling programs will be
known as a 'side'.
 After an SPL, the next split to be executed by this side will be the split
after the new split at the A-location, not the next instruction in the
program that performed the split command, or the new split. For example, if
there is only one split active when an SPL command is issued, the new split
would be created, but ignored until the original split was called once again.
 A maximum of 64 siblings per side, 128 siblings in all, are allowed in MARS.
There is no error indication given if the SPL is unsuccessful, for whatever
reason (eg. 64 tasks already running; A location was not executable etc.).




 PCT A         A can be any addressing mode except immediate.

 (protect)

 This instruction 'protects' the cell at the A-location. Any instruction
which subsequently attempts to write to a protected cell will not alter the
cell, but will remove the protection. The next attempt to write will then
succeed. ** NB This is not an official instruction **
