PMARS(6)                         Games Manual                         PMARS(6)



NAME
       pmars - portable corewar system with ICWS'94 extensions

SYNOPSIS
       pmars [ option ...  ] file1 [ file(s) ]

DESCRIPTION
       pMARS  (portable  Memory  Array  Redcode Simulator) is a corewar inter-
       preter with multi-platform support.  pMARS currently runs on UNIX  sys-
       tems,  Windows  and  the Mac.  pMARS implements the ICWS'94 draft stan-
       dard, but can also be used in ICWS'88 mode. The base system includes  a
       graphical  core  display  for  UNIX  (curses,  X-windows)  and PC/linux
       (svgalib). A line-oriented debugger is included to help in writing war-
       riors for the ICWS'94 draft standard.

       pMARS runs one or more warriors written in Redcode that are provided as
       file(s) on the command line.  Running a single warrior is supported for
       debugging.  Two  warriors  are  pitted  against each other for standard
       play, but up to 36 warriors can be named for "multi-warrior" core  war.
       If  the warrior(s) assemble without error they are loaded into the core
       array and executed in round-robin mode starting with the first warrior.
       Warrior 1 is loaded starting at core position 0, warrior 2, 3, etc., at
       either a random or fixed position.  For fairness the starting order  is
       rotated after each round.

SCORE
       The  score  is reported after all rounds have been played. A round ends
       when either a single surviving warrior remains or when a maximum number
       of  cycles  has  elapsed.   For  each round, every surviving warrior is
       awarded points calculated from a score formula (F).  By  default,  this
       is  (W*W-1)/S, where W is the total number of warriors participating, S
       is the number of of survivors, and "/" is integer division. Alternative
       score formulas can be specified with the = option (see below).

       When two warriors battle, the results are reported as wins1, wins2, and
       ties, where wins1 and wins2 are the numbers of rounds that each warrior
       won,  and  ties  are the number of rounds in which both warriors lasted
       until time-out.  The score is then:

               warrior 1:  points = wins1 * F + ties * F
               warrior 2:  points = wins2 * F + ties * F

       F is a score formula containing the W and S parameters.  When more than
       two  warriors  (W)  participate  in  a  game,  results  are reported as
       wins[1], wins[2], .., wins[W], losses for each warrior, where the index
       indicates the number of warriors that survived until the end (S parame-
       ter in the score formula). The total number of points for each  warrior
       is then calculated as:

               points =  sum (S=1..W) (wins[S] * F)

       A few alternative score formulas:
               10
               (W+1)/S
               (x=W-S+1)*(x+1)/2
               (S==3)*5 + (S==2)*3 + (S==1)
               (S == 1)*W + (S != 1)

OPTIONS
       Command  line  options  may occur anywhere on the command line. Single-
       letter options without a parameter can be combined as in -fbe. The spe-
       cial  argument  -  (dash)  stands for standard input (stdin). It can be
       combined with the -@ option (see below) to signify reading options from
       stdin,  or  the  -  can take the place of a  warrior filename, in which
       case warrior code starting with a ;redcode line and ending with an  END
       statement  is extracted from stdin. The END statement can be omitted if
       the next ;redcode line immediately follows the last  instruction.  Sev-
       eral  warriors,  each  specified by a separate dash on the command line
       and bracketed by ;redcode/END can be piped into pMARS.  #- (where #  is
       a  positive number) is a shorthand for writing this number of dashes on
       the command line.

       -r #   This options sets the number of rounds to play. The  default  is
              1.  -r  0 produces assembly output (unless -b is specified), but
              does not execute the warrior(s). A maximum of 32767  rounds  can
              be specified.

       -s #   The  -s  option  specifies  the size of core memory in number of
              instructions.  It defaults to 8000. Maximum core size  is  plat-
              form-dependent, but usually at least 65535.

       -c #   -c  sets  the  maximum number of cycles per round.  A cycle con-
              sists of one execution of each warrior. A round ends when either
              a single warrior remains executing or when the maximum number of
              cycles has elapsed.

       -p #   This option sets the maximum number of processes a  warrior  can
              run.  The default is 8000.

       -l #   This  sets  the  maximum  length  of  a  warrior  source file in
              instructions.  It defaults to 100.

       -d #   This option specifies the minimum  distance  between  the  first
              instruction of each warrior. It cannot be smaller than the maxi-
              mum length (-l option) and defaults to 100 instructions.

       -S #   The -S option sets the size of  the  P-space  to  #  cells.  The
              default  is 1/16th of core size if core size is evenly divisible
              by sixteen, or the next larger divisible fraction. See also  the
              P-SPACE section below.

       -R #   The -R option sets the read limit. The read limit must be a fac-
              tor of core size.  The default is core size, i.e. no read limit.

       -W #   The -W option sets the write limit. The write limit  must  be  a
              factor  of  core  size.  The default is core size, i.e. no write
              limit.

       -f     The -f option instructs the loader to  use  a  fixed  series  of
              addresses for positioning warriors. This is done by initializing
              the pseudo random number generator with a checksum value derived
              from  the source of all warriors.  Thus, initial placements will
              still be "random" from round to round, but will be the  same  if
              the same warriors are run again. As a consequence, the result of
              battles run with the -f option will show no statistical fluctua-
              tions.  This  options is useful for validating ports of pMARS to
              new platforms and for providing an  absolute,  albeit  arbitrary
              performance measure for warriors.

       -F #   This  option  server two purposes. It sets the seed value of the
              pseudo random number generator, and also  tells  the  loader  to
              install  warrior  2  at  the given address # for round 1. If the
              number is larger than the core size minus  the  minimum  warrior
              distance,  it  will  be wrapped around to the range of available
              starting positions.  This option is useful for testing different
              versions  of a warrior with constant initial placement.  Warrior
              1 is always installed at address 0.  The -F and -f  options  are
              mutually  exclusive.  If neither option is specified, the pseudo
              random number generator is initialized with the system time.

       -P     This option makes pMARS use an alternative algorithm  for  posi-
              tioning  warriors. This algorithm uses all possible combinations
              of starting order and position in a random  sequence,  and  will
              not  use  the same combination twice unless all the combinations
              have already been used. If the -r option is not given, the  num-
              ber of rounds fought will be the number of all possible combina-
              tions.  Trying to use this option with more (or less)  than  two
              warriors causes an error.

       -e     If this option is specified, the cdb debugger is entered immedi-
              ately after loading warriors into core.

       -b     This options runs pMARS in brief output mode. -b suppresses war-
              rior listings after assembly.

       -A     The  -A  option assembles the input warriors without running any
              fights.  Emits ICWS'94 draft compliant load files.

       -k     With the -k option, pMARS uses the same  output  format  as  the
              KotH  program.  This  option  enables pMARS to work with scripts
              written for the KotH server.

       -8     This options enforces strict compliance with the  ICWS'88  stan-
              dard  and  disables  all  ICWS'94 language extensions, which are
              flagged as syntax errors by the assembler. Since  ICWS'94  is  a
              superset  of  ICWS'88,  this  options  is  not  necessary to run
              ICWS'88 warriors.

       -o     When this option is given, pMARS reports  scores  in  decreasing
              order  rather  than in the order warriors were named on the com-
              mand line. This is mostly useful for multi-warrior play.

       -V     The assembler generates verbose output with this option. This is
              only useful for debugging.

       -v     This  option sets the display mode for UNIX and DOS display ver-
              sions (see APPENDIX).

       -@ <fn>
              pMARS continues reading options and filenames from the parameter
              file <fn>.  If <fn> is a - (dash) standard input is parsed. Com-
              ments in the parameter file start with a semicolon.

       -= <string>
              The = (equal) option allows you to specify a custom  score  for-
              mula  (see  SCORE).  The formula may contain the standard arith-
              metic and logical operators (as in the C language), as  well  as
              the  parameters W (number of warriors participating) and S (num-
              ber of warriors surviving this round). You need to  enclose  the
              formula  string  with quotes if it contains spaces or characters
              interpreted by the operating system.

       -Q #   The "query" option is intended for use in scripts that run pMARS
              in  batch  mode.  Depending on the number code following -Q, the
              program returns  an  informative  number  as  the  exit  status.
              "pmars  -Q  1000" e.g. will cause pMARS to exit with a code that
              spells out the program version. More on -Q  arguments  and  exit
              codes can be found in the ADDENDUM.

       $      The $ (dollar) parameter is not preceded by a dash and cannot be
              grouped with other options. It terminates reading  command  line
              parameters  and  is used in parameter files or input streams (-@
              fn).  The $ is necessary if you want to combine two or  more  of
              command  line  parameters,  warrior code and cdb commands in the
              same input stream or file. Below an example of such  a  combined
              input file:
                  ;Below the command line parameters:
                  -r 10 -beF 1000 2- $
                  ;redcode
                  ;name Imp 1
                  ;assert 1
                  mov 0,1
                  end
                  ;redcode
                  ;name Imp 2
                  ;assert 1
                  mov 0,2
                  mov 0,2
                  end
                  !! cdb commands follow:
                  sk 1000
                  reg
                  quit

X-WINDOWS OPTIONS
       The  X-Windows  display  version  of pMARS has these additional command
       line options:

       -display <string>
              Expects a string specifying the display where the window  should
              appear.  Following X standards, this display specification has a
              format of hostname.domain:display.screen where the  part  before
              the  colon  is the standard internet host specification and dis-
              play and screen are integers.  The screen specification  can  be
              omitted. For an example, consider you are working at an X termi-
              nal named ncd13.complang.tuwien.ac.at and remotely logged in  at
              host  stud1.tuwien.ac.at where the binary of pmars lies, you can
              use the following command line

         stud1$ pmars -display ncd13.complang.tuwien.ac.at:0 -b aeka.red aeka.red
         and the window will appear at you local screen.

       -geometry <string>
              Lets you specify the initial size and position  of  the  window.
              The  format  is  widthxheight+x+y  where width, height, x, y are
              integers and + may be replaced by -. Either  of  the  two  parts
              (widthxheight  or  +x+y)  may  be omitted. This overrides the -v
              switch concerning the window  geometry.  As  an  example,  pmars
              -geometry  600x400+30+100 ....  will open a window of 600 by 400
              pixels  at  the  screen  position  (30,100).   pmars   -geometry
              1024x768  ...  creates  a  window  of  1024x768 pixels and pmars
              -geometry -20+300 ... creates a window with standard  size  with
              its  left  upper  corner  at position (-20,300), i.e. out of the
              left side of the screen.

       -fn <string>
              The string following this argument specifies the X font to  use.
              By  default,  a  terminal  font  is  used. If this font can't be
              found, "fixed" is used for a font ("fixed" should be present  at
              every  X  installation).   Use  the  command 'xlsfonts' to get a
              listing of fonts that can be used at your X  server.  'xfontsel'
              provides  a  comfortable  way  to  select a font. "fixed" is the
              fallback if the specified font can't be found.  It  is  strongly
              recommended to use a fixed pitch font.

       The argument of the -v display option has an additional fourth digit in
       the X-Windows version: 0 (the default) enables the color display, 1 the
       grayscale,  and  2  the  black  and white display (e.g. -v 1033 for the
       grayscale display).

REDCODE
       pMARS implements an extension of the proposed ICWS'94 standard. The new
       instruction  modifiers .A,.B,.AB,.F,.X, and .I, the arithmetic instruc-
       tions MUL, DIV and MOD, as well as post-increment indirect (>) are sup-
       ported.

       Version  0.5  of pMARS adds support for three experimental opcodes that
       are currently not included in the ICWS'94 draft:

       SEQ (Skip if EQual): this is a synonym for CMP and is  included  mainly
       for  clarity  (future  versions of pMARS may implement SEQ as a "prede-
       fined EQU" rather than a true opcode).

       SNE (Skip if Not Equal): the opposite of SEQ.

       NOP (No OPerations): do nothing.

       Version 0.6 adds three new indirect addressing modes that  use  the  A-
       field instead of the B-field as the pointer for indirection:

       * - indirect using A-field

       { - predrecement indirect using A-field

       } - postincrement indirect using A-field

       The  new  P-space instructions of version 0.8 are discussed under sepa-
       rate heading below.

       The assembler also supports multi-line EQU statements,  a  feature  not
       included  in  the  current  ICWS'94  draft.   The format for multi-line
       EQUates is
           <label> EQU <line1>
                   EQU <line2>
                   [...]
                   EQU <lineN>
       <label> in the warrior source is replaced by <line1> <newline>  <line2>
       <newline>  [....]  lineN.  In  contrast  to KotH, pmars EQUs substitute
       arbitrary text, and not just  expressions.   EQU  expressions  are  not
       implicitly parenthesized.

       pMARS  features the non-standard FOR text-repetition macro.  This macro
       repeats the text between FOR and ROF a specified number of times:
       <labels> <counter> FOR <times>
                          [..]
                          ROF
       <times> is an expression specifying the number of  expansions;  it  may
       contain EQUates and labels as long as they have been defined before the
       FOR/ROF block.  <counter> is the last label before the  FOR  word,  but
       not  necessarily  on  the  same  line.   It  is expanded to 01, 02, ..,
       <times> in each repetition.  The  optional  <labels>  label  the  first
       instruction after FOR expansion. An example:
               ORG start
       start
       sp      FOR 2
       a&sp        SPL a&sp
                   JMP a&sp
               ROF

       becomes after expansion

       start
       a01     SPL a01
               JMP a01
       a02     SPL a02
               JMP a02
       The  symbol  &  concatenates 'a' and 01, 02 to form a valid label.  EQU
       expansion and FOR/ROF processing is done  in  the  same  pass.   It  is
       therefore possible to write
       dest01  EQU 500
       dest02  EQU 1000
       dest03  EQU 1500

       idx     FOR 3
                   MOV src,dest&idx
                   MOV src+1,dest&idx
               ROF

       src     MOV <-1,<-1
               JMP src,<-2
       Using  predefined EQUates (see below) it is possible to define adaptive
       FOR/ROF blocks. The next example fills the remainder of the warrior (up
       to MAXLENGTH lines) with decoy instructions:
           FOR MAXLENGTH-CURLINE
               DAT 1,1
           ROF
       Since  true  logical  expressions have a value of "1" and false expres-
       sions a value of  "0",  you  can  write  conditionally  assembled  code
       enclosed by FOR/ROF:
           FOR CORESIZE == 8000
           <some code>
           ROF

           FOR CORESIZE != 8000
           <other code>
           ROF
       pMARS  uses KotH-style ;name and ;author comments to describe warriors.
       If a line starting with ;redcode is present, all text preceding  it  is
       ignored. This makes it possible to run posted warriors without removing
       mail headers and descriptive text.  The ;version, ;strategy  and  other
       comments mentioned in the ICWS'94 draft are currently not used.

       As  another "non-standard" extension, the assembler predefines the fol-
       lowing   run-time   variables:   CORESIZE,   MAXPROCESSES,   MAXCYCLES,
       MAXLENGTH,  MINDISTANCE,  PSPACESIZE, READLIMIT, ROUNDS and WRITELIMIT.
       They can be used in your Redcode as though they were  defined  by  EQUs
       like
           CORESIZE     EQU 55440  ;current value of -s parameter
           MAXPROCESSES EQU 10000  ;current value of -p parameter
           [etc.]
       The run-time variable CURLINE holds the current instruction number off-
       set from the first instruction. WARRIORS is initialized with the number
       of warriors specified on the command line.

       pMARS  supports  the  ;assert  directive as a way of checking whether a
       warrior is run under the parameters it was designed for. If the expres-
       sion  following  ;assert  evaluates to "0" (false), assembly is aborted
       with an error message. If an ;assert is missing, a warning  is  issued.
       Examples:
           ;assert CORESIZE == 55440 && MAXLENGTH >= 200
           ;assert !(CORESIZE % 4)  ; is multiple of 4
           ;assert 1 ; if warrior works under all settings
       The  run-time  variable  VERSION  holds the current pMARS version (e.g.
       "60" is v0.6.0) and is useful in ;assert expressions.

       With the -8 option, pMARS is fully ICWS'88 compatible,  except  that  a
       comma  is  required  between  operands.  Extensions like predefined and
       multi-line EQUs and FOR/ROF are supported even in ICWS'88 mode.

       A full treatment of corewar and ICWS'94 in  particular  is  beyond  the
       scope  of  this  document. General information about corewar as well as
       the ICWS'94 draft is available  by  anonymous  FTP  from  https://core-
       war.co.uk/standards/

P-SPACE
       Originating  from  discussions  on  rec.games.corewar,  P-space  is  an
       attempt at making warriors more "intelligent" by giving them a  memory.
       P-space,  short  for "private", "permanent" or "priviledged" space is a
       memory area separate from core whose contents is  not  cleared  between
       rounds.  Every  warrior  has  its own P-space for gathering information
       about the opposing warrior, but there is a  provision  for  sharing  P-
       space in team play (see below).

       P-space  cells contain values in the range 0..CORESIZE-1. The number of
       P-space cells can be adjusted with  the  -S  command  line  option;  by
       default,  P-space  size is 1/16th of CORESIZE. This number is available
       to warriors as the predefined variable PSPACESIZE.   pMARS  updates  P-
       space cell 0 at the beginning of each round with the result of the pre-
       vious round: 0 signifies a loss in the previous round, a number  larger
       than  zero  means that the warrior survived until the end of the round,
       the value indicating the number of surviving warriors. That is, a value
       of "1" means that the warrior survived by itself (a "win" in a two-war-
       rior battle), a value of "2" that two warriors lasted until the end  (a
       "tie"  in a two warrior battle), etc..  In the first round, P-cell 0 is
       set to -1 (actually CORESIZE-1) to indicate that there is  no  previous
       result.

       There are two new instructions for accessing P-space:

       LDP    (Load P-space) loads P-space cell specified by A-value into core
              at B-address.

       STP    (Store P-space) stores A-value into P-space cell specified by B-
              value.

       It is important to note that P-space cells are refered to by A/B-values
       as opposed to A/B-addresses. As an example, "STP #9,#1" stores number 9
       in P-cell 1.

       Since  all  P-space access is only via these two instructions, it takes
       too much time and space to use P-space for working variables where they
       would  be safe from the opposing warrior. P-space was made deliberately
       hard to access, unlike a set of general purpose registers.

       P-space can also be used for communication between  warriors  belonging
       to  a  team  in multi-warrior core war. To allow communication, P-space
       has to be declared as "shared".  You  do  this  by  including  the  PIN
       pseudo-opcode in your source:

       PIN    (P-space Identification Number) has a single numerical argument.
              If two or more participating warriors have the  same  PIN  argu-
              ment,  they  share the same P-space. If the PIN pseudo-opcode is
              missing from a warrior's source, its P-space  is  strictly  pri-
              vate.  The  PIN  argument  is  not normalized to [0..CORESIZE-1]
              before comparison. "PIN 0" and "PIN CORESIZE" are therefore  not
              the same.

       P-cell  #0 holding the result of the last round is exempt from sharing,
       i.e.  every warrior has its own last round cell even though the rest of
       its P-space may be shared.

CDB DEBUGGER
       Cdb is a line-oriented debugger. It is invoked either by specifying the
       -e option (enter cdb immediately), by including debugging  commands  in
       the  warrior  source,  or by hitting Ctrl-C during the simulation.  The
       debugger is also entered whenever a warrior terminates  ("post-mortem")
       if execution was started with the go command.  cdb is very powerful and
       has an overwhelming number of commands. You may want to start with only
       the most often used commands: step (single step execution), go (execute
       until breakpoint), list (look at core),  trace  and  untrace  (set  and
       remove breakpoints), and go on to more complex ones later.

       The following commands are available at the cdb prompt; commands can be
       abbreviated to the first unambiguous substring.

       <Enter>
              repeats the last command issued at the cdb prompt.

       help   displays a brief command summary.

       progress
              displays the status of the current game in progress.

       registers
              displays the current state of the simulator,  including  program
              counters and task queues.

       go     runs  the  simulator until an instruction whose trace bit is set
              is executed. If there are no traced instructions go  returns  to
              the post-mortem debugger.

       step   executes  the  next instruction in the task queue and returns to
              the cdb prompt.

       continue
              returns to the simulator to complete the game without  interrup-
              tions.

       thread is  similar  to step except that only the current task thread is
              traced.

       skip [count]
              executes the next [count] instructions  in  the  queue  silently
              before returning to the cdb prompt.

       execute [address]
              resets  the  task  queue of the current warrior to [address] and
              executes it. This is useful in conjunction with edit.

       quit   aborts pMARS and returns to the OS prompt.

       trace [range]
              sets the trace bit of the specified address or address range.

       untrace [range]
              clears the trace bit of the specified address or address range.

       moveable on|off
              specifies whether the trace bit is copied by the MOV.I  instruc-
              tion. The default is on.

       list [range]
              displays  the specified range of core addresses, a set trace bit
              is indicated by 'T'.  Unmodified addresses (DAT.F 0,0) are shown
              as blank.

       edit [range]
              allows  modifying  core.  The  specified addresses are edited by
              typing in new instructions. Typing one or more spaces leaves the
              core  address  unchanged, just hitting <return> repeats the last
              input, and a syntax error aborts the edit. The full Redcode syn-
              tax including labels and (multi-line) EQUates can be used. Label
              and EQUate definitions remain in effect until the program termi-
              nates.   The  edit  command is useful for modifying warriors and
              trying out  single  instructions  without  having  to  exit  and
              restart pMARS.

       fill [range]
              is  similar  to  edit.   Instructions in the specified range are
              replaced by one typed in instruction. Entering DAT.F  0,0  ,e.g.
              clears the address range.

       search [pattern]
              searches  core  instructions  for  a text pattern in the forward
              direction. The next instruction matching [pattern] is displayed.
              The  search includes the address number and trace symbol (T), is
              case- and space-insensitive and may contain wildcards: * (aster-
              iks) matches any number of characters; ? (question mark) matches
              exactly one character. E.g. "search ,"  searches  for  the  next
              non-blank  address; "search dat*, ?0t" searches for the next DAT
              instruction that is traced  and  has  a  zero  B-operand  value,
              regardless of modifier, A-operand and B-mode.

       write [file]
              opens  a  file for logging subsequent cdb output to. The logfile
              is closed by issuing write without an argument.

       echo [string]
              is used mostly inside macros. [string] is echoed to  the  screen
              followed by <newline>.

       remark [string]
              is ignored by cdb and can therefore be used to comment macros.

       cls    clears  the  screen.  The  no-display  UNIX version does this by
              echoing an ANSI escape sequence; if this doesn't work  for  you,
              you  need to change the CLRSCR string in config.h and recompile.
              clear is a synonym for cls .

       display clear|on|off|nnn
              (available in display versions only) allows  clearing  the  core
              display  (display  clear) or changing the display mode.  display
              on changes the display to the default mode, display off (same as
              display  0  )  suspends  all  display updates, and display nnn ,
              where nnn is a 1 to 3-digit number, sets  the  display  to  this
              mode.  "nnn" is interpreted like the parameter to the -v command
              line option (see APPENDIX).

       switch [1|2]
              (available in display versions only) makes the left (1) or right
              (2)  panel  the  current  panel for cdb output. Without a number
              argument switch changes to the other panel. If the  right  panel
              doesn't exist (initially, or after close, see below), it is cre-
              ated first.

       close  (available in display versions only) closes the right cdb  panel
              (if it exists) and makes the left panel fullscreen.

       calc expr1[,expr2]
              is  a  command  line  calculator. Since calc has no side-effects
              other than echoing the result of expression 1 (and expression  2
              if  provided).  In  the context of cdb macros it is also used to
              assign values to the register variables 'c' through 'z'.

       macro [name][,file]
              loads, executes or lists macros. A macro expands to one line  of
              cdb  commands  separated by the tilde character (~) (a so-called
              command chain, see below).  The command macro name executes  the
              macro  "name";  if  "name"  is left out, all currently available
              macros are listed.  macro name,file loads macro definitions from
              file "file" and executes macro "name"; again, if "name" is miss-
              ing, only a listing is produced. Macro definitions are  appended
              to the list of previously loaded definitions or replace a previ-
              ously loaded macro definition with the same  name.  If  you  are
              trying to execute or list macros, but no macros have been loaded
              yet, the default macro file "pmars.mac" is loaded automatically.
              The  special  macro  file "user" can be specified to input macro
              definitions directly from the keyboard. Macro  definitions  con-
              sist  of a macro name, followed by the equal sign, followed by a
              command (chain).  The macro name can consist  of  any  printable
              character  excluding  <space>  and comma; the equal sign is only
              allowed at the end of a macro name.  Individual macro lines have
              a  limit  of  80 characters, but macro calls inside macro expan-
              sions are allowed.  Cdb can hold up to  200  macros  in  memory.
              See also the section on cdb macro programming below.

       if <expression>
              controls  execution  of commands in macros or command chains. If
              <expression> evaluates  to  zero,  the  next  command  block  is
              skipped.  A command block consists of either a single command or
              any number of commands bracketed by !!  (loop  start)  and  ![e]
              (loop  end,  see  section on macro programming below).  <expres-
              sion> may contain C-style comparison and boolean operators  (see
              below).  An if immediately preceeding a loop end (![e]) can skip
              out of the loop.

       reset  is used inside macros in conjunction with if to terminate  macro
              execution,    e.g.    inside    an    infinite    loop   (...~if
              A==0~reset~...~!).

       pqueue [1|2|..|off]
              switches cdb into "process queue mode". In this mode, list, edit
              and fill operate on the process queue instead of the core array,
              i.e. you can view and modify the process queue as easily as  the
              core  array. This is especially useful for debugging complicated
              multi-process  warriors.   pqueue  without  argument  uses   the
              process queue of the current warrior. With argument 1,2,.., uses
              the process queue of warrior 1,2,.., respectively.   pqueue  off
              returns to normal mode.

       wqueue [off]
              stands for "warrior queue" and is similar to pqueue, except that
              numbers provided as arguments for list, edit and fill now  refer
              to  warriors:  "list 0" now shows the program counter of warrior
              1, "list 1" that of warrior 2 and so on.  wqueue off returns  to
              normal "address mode".

       pspace [1|2|..|off]
              complements the pqueue and wqueue commands. If a number is spec-
              ified, the P-space of that warrior is selected for viewing/edit-
              ing. Without an argument, the P-space of the currently executing
              warrior is selected. "pspace off" returns to core mode.

       go, step, continue and thread may have a single address  argument.  The
       program  counter  of  the current warrior is set to this address before
       execution continues.

       The range argument of the list, trace, etc.  commands  has  the  format
       <start>,<stop>.  Addresses <start> and <stop> are numbers, special sym-
       bols or C-style  expressions  including  special  symbols.   If  either
       <start>  or  <stop> is omitted, it defaults to the current address.  If
       both are omitted, the range of the last cdb command is used.  A  single
       address (without the comma) acts on only that address. Addresses start-
       ing with a + or - are interpreted relative to the current address.

       Expressions may contain the arithmetic  operators  -,+,*,/,%  (modulo),
       the  comparison  operators ==, !=, <=, >=, and the boolean operators &&
       (AND), || (OR), and ! (negation).  Expressions may also include  regis-
       ter  variables  C  through  Z  and  the assignment operator =. Operator
       precedence is like that of the C-language  and  may  be  overridden  by
       parentheses.  Assignment,  comparison and boolean operations are mostly
       used with calc and if commands in macros, but can also be used in  Red-
       code operands.

       Special address symbols used in cdb commands:

        .     (dot) is the current address (displayed last).
        $     (dollar) is the last core address.
        A     is the A value of the current instruction.
        B     is the B value of the current instruction.
        PC    is the program counter of the currently executing warrior.
        PC1   is the program counter of warrior 1.
        PC2   is the program counter of warrior 2.
        LINES is the number of lines available to the cdb display
        CYCLE is the current execution cycle (counted down)

       In  process  queue  (pq),  warrior  queue (wq) or pspace (ps) mode (see
       pqueue, wqueue, pspace), most of these symbols have a  different  mean-
       ing:

        .     (dot) is the current process number (pq),
              warrior (wq), or P-space cell (ps) which was displayed last.
        $     (dollar) is the last process in the process queue (pq),
              the last warrior (wq), or the last P-space cell (ps).
        A     is the A value of the instruction of the current process (pq),
              the next executing process of the current warrior (wq), or
              the P-space selector (ps, same as warrior number if unshared).
        B     is the B value of the instruction of the current process (pq),
              the next executing process of the current warrior (wq), or
              the P-space selector (ps).
        PC    is 0.
        PC1.. are 0

       Preceding  a  command with the character '@' (ampersand)  will suppress
       its screen output, but not output to a logfile.   Preceding  a  command
       with  '&' will suppress both screen and logfile output, which is useful
       if you are only interested in the "side-effects" of a command.   Start-
       ing  a  command  with  a  <Space> character suppresses saving it to the
       "last-command" buffer that is recalled by <Enter>.

COMMAND CHAINS AND MACRO PROGRAMMING
       Several commands can be issued on one line when separated by the  tilde
       character  (~).  These  "command  chains" are useful for repeating long
       command sequences, since <Enter> recalls  the  entire  chain  (see  the
       examples  below).   Commands  requiring user intervaention (list, edit,
       fill) also read their input from the chain.

       The "empty command" (two consecutive tildes or a tilde at  the  end  of
       the chain) repeats the last command in the chain.  A command consisting
       of <Space> is a null command and is used to simulate  pressing  <Enter>
       in list, edit and fill.

       The  exclamation mark (!) character is a special "chain repetitor" com-
       mand. The optional expression following '!' specifies  how  many  times
       the command chain starting at the beginning of the line or the last '!'
       is executed. '!' without an expression repeats until the program termi-
       nates.

       The  symbol '!!' is used for nested loops and marks the start of a com-
       mand block to be repeated. The command block is  closed  by  '![expres-
       sion]'  and  may  contain other command blocks. A command block immedi-
       ately following an if command is executed  only  if  the  condition  is
       true.

       With  loops,  subroutines  (macros  calling  macros), variables (C..Z),
       expressions involving comparisons and boolean  operations,  and  condi-
       tional  execution  (if),  the  cdb command language can be used to con-
       struct complicated macros for e.g. executing a warrior until a  certain
       core  address  has  changed, controlling the 2-panel display, automati-
       cally finding the right constants for a  warrior,  etc.  See  the  file
       "pmars.mac" for examples.

EXAMPLE CDB COMMANDS
       list ,+20
              lists the next 20 instructions.

       trace pc-10,pc+10
              traces  21  addresses centered around the program counter of the
              currently executing warrior.

       untrace 0,$
              clears all trace bits.

       go   reg   l+a,+b
              chains these commands: execute until the next traced address  or
              end of round, display the simulator status and list addresses in
              the range A-number to B-number of the current instruction.

       @fill0,100 dat.f 0,0
              fills addresses 0 through 100 with 'dat.f 0,0', not echoing  the
              changed addresses to the screen.

       write trace.log step !
              produces  a  continuous  execution trace by repeating step until
              pMARS terminates, saving the output to logfile "trace.log".

       @l x=5 !! @ed x~dat x,0 if (x=x+1)<$+1 !
              This command chain could be useful for debugging  a  stone-type,
              self-modifying  warrior,  which  is  assumed to occupy address 0
              through 4 in this example. The command fills  core  starting  at
              address  5  with  "dat  5,0", "dat 6,0", a.s.o., so that you can
              tell where a bomb which overwrites the  warrior  came  from.  To
              save some typing, you can turn this command into a macro (foo=@l
              x=5~..). This is how it works, step by step: Assign 5 to  regis-
              ter  x  and  make  it the current address (@l x=5). Start a loop
              (!!) and change address x to "dat x,0" (@ed x~dat  x,0).  Incre-
              ment  x, if x is then smaller than the core size ($+1), continue
              looping (if (x=x+1)<$+1~!). The '@' in front  of  the  list  and
              edit commands suppresses screen output.

       @s @4 if b<2 || b>=$-3 reset !
              This  command  executes a warrior until the B-field of address 4
              points to address 0 through 5: Step and make address 4 the  cur-
              rent  address  (@s~@4). If the B-field is less than 2 or greater
              than or equal to 7996 (CORESIZE-1-3) stop execution,  else  con-
              tinue looping (if b<2 || b>=$-3~reset~!).

SOURCE DEBUGGING DIRECTIVES
       Trace  bits can also be set by including debugging commands in the war-
       rior source. A comment format is used to retain compatibility with sim-
       ulators that do not support source-embedded debugging commands.

       ;debug [static/off]
              This  command  enables/disables  all  subsequent source-embedded
              commands.  It is used for commenting out other source  comments.
              ;debug static has the same effect as the command moveable off at
              the cdb command prompt.  ;debug is implicitly added in front  of
              every  warrior.  The  last  ;debug  or ;debug static encountered
              specifies whether the trace bit is copied by a MOV.I instruction
              or not.

       ;trace [off]
              ;trace  starts  setting  the trace bit with the next instruction
              until EOF or a ;trace off command is encountered.

       ;break sets the trace bit of the next instruction.

BUGS
       None whatsoever (right).  Contact for bug reports  and  suggestions  is
       Stefan  Strack  (stst@vuse.vanderbilt.edu).   Please  be  detailed  and
       include a logfile of the cdb session if  applicable.  Bug  reports  and
       suggestions  concerning the Macintosh display and interface should also
       be directed to Alex MacAulay (macaulay@mundil.cs.mu.oz.au).

AUTHORS
       The portable MARS project was initiated after  discussing  the  ICWS'94
       draft  on the rec.games.corewar newsgroup. We realized that we needed a
       portable system to try out the proposed standard and to accept,  modify
       or reject it.  The people who started portable MARS and are responsible
       for the base code as well as the DOS and UNIX displays are:

       Albert Ma (ama@athena.mit.edu)
       Nandor Sieben (nandor.sieben@asu.edu)
       Stefan Strack (stst@vuse.vanderbilt.edu)
       Mintardjo Wangsaw (wangsawm@csos.orst.edu)

       Alex MacAulay (macaulay@mundil.cs.mu.oz.au) wrote the Macintosh display
       version.   Martin  Maierhofer  (m.maierhofer@ieee.org)  contributed the
       linux  SVGA  and  X  windows   display.    Nathan   Summers   (00ncsum-
       mers@bsuvc.bsu.edu) did the port to VMS.

ACKNOWLEDGMENTS
       We  thank  Planar (Damien.Doligez@inria.fr) for expert help with debug-
       ging and porting pMARS to different UNIX machines. We  also  appreciate
       the  help of Chris Lindensmith (lind0014@student.tc.umn.edu) and Pierre
       Baillargeon (dak@info.polymtl.ca) with the initial Mac and Amiga  ports
       respectively.   Mark Durham (durham@ricevm.rice.edu) spearheaded devel-
       opment of the ICWS'94 draft and we thank him  for  writing  the  sample
       interpreter code included with the draft.

APPENDIX
PMARSV
       pMARSv is a DOS version of pMARS with a graphical core display. You can
       chose between EGA/VGA graphics or text mode with the  -v  command  line
       options or by pressing 'v' during the game. The -v option takes a three
       digit argument 'xyz'. Digit 'x' specifies the initial display speed and
       ranges  from  0  (fastest)  to  7 (slowest). 'y' is the initial display
       mode: 0 for text mode, 1 for standard VGA graphics, 2 and 3 for SVGA, 4
       and 5 for EGA, and 6 for CGA graphics.

       The display level 'z' specifies how much is displayed:

       0      Display  nothing.  This  greatly speeds up execution, especially
              when in graphics mode.

       1      Display execution of addresses. In text mode,  a  black  '0'  on
              blue background is shown for warrior 1, a black '1' on green for
              warrior 2, a.s.o.. Numbers blink in white when a DAT instruction
              is  executed. In graphics mode, a blue square represents warrior
              1, a green square warrior 2, a.s.o.. These colors are also  used
              for other core accesses.

       2      Also  display write accesses. In text mode, they appear as dots;
              in graphics mode, they appear as two pixels, offset diagonally.

       3      Also display decrements and increments. They are  shown  as  '+'
              and '-' in text mode and as two pixels offset vertically or hor-
              izontally in graphics mode.

       4      Also display read accesses, which appear as small dots  in  text
              mode and as single pixels in graphics mode.

       The  more  is  displayed, the slower runs the simulation.  The argument
       for -v defaults to 103, i.e. speed=1, mode=text, level=3.

       The text mode display is very fast, but contains less on-screen  infor-
       mation than the graphics display. The core display and the cdb debugger
       run full-screen on separate display pages.

       In graphics mode, core and debugger share the same  screen.  The  mouse
       can be used to navigate around core when debugging is enabled: clicking
       a mouse button on any core location lists addresses starting there. The
       mouse  cursor  follows  the current program counter when in single step
       mode.

       In both graphics and text mode, the cdb display can be divided into two
       side-by-side panels. You can switch between panels with the switch com-
       mand (or the <Tab> macro) and close the right panel with close (or  the
       <Shft-Tab> macro).  Extended (function keys, arrow/page keys, ALT keys,
       etc.) and control keys generate macro calls at the cdb prompt; some  of
       these "hot key macros" have been defined in "pmars.mac"; you can easily
       change them or add more with a text editor.   E.g.  <PgDn>  and  <PgUp>
       keys  currently  invoke macros that scroll through core one screen at a
       time.

       A white line at the top of the display, called the  time  meter,  indi-
       cates the time required to finish the current simulation. The amount of
       time depends on the number of warriors still alive in the arena.  After
       a  warrior dies it no longer needs simulation time so the required time
       to finish the simulation becomes less. On the time meter this is  indi-
       cated  by a discontinuity. One can count the number of dead warriors in
       the arena by counting the number of discontinuities on the time meter.

       Just below, the length of "process meters" in the color of the warriors
       they represent show how many processes each warrior has running.

       The following keys are available at the core display screen:

       0..4   selects the display level (see above).

       v      switches from text display to graphics display and vice versa.

       >      increases the display speed.

       <      decreases the display speed. The current speed is indicated by a
              red bar in graphics mode.

       d      enters the cdb debugger. "Debug" on the  graphics  menu  bar  is
              highlighted in red inside cdb.

       <space>
              (also 'r') refreshes the core display.

       <escape>
              (also 'q') exits to DOS.

       You  can  define  additional  keys and commands associated with them by
       defining "key-x" macros ("x" is any printable character). E.g.:
       key-p= progress~registers~continue
       Function-key and other macros can also be invoked from  the  core  dis-
       play.

CURSES DISPLAY
       The  curses display is very similar to the DOS text mode display. There
       are separate pages for core and debugger.  There is a status bar at the
       bottom of the core display:

       Rave [0]: 1        Lucky 3 [1]: 3702  Cycle: 72967  R: 2/5 (0 0 1)

       The  display symbol that indicates execution is shown in brackets after
       the warrior name. The number after the colon shows the number  of  pro-
       cesses  active.  The "2/5 (0 0 1)" means that this is round 2 of 5; the
       result so far is one tie. Only cycle and round information is shown  if
       more than two warriors are run.

       There  is  no "hot key" user interface during the core display, but you
       can enter the debugger by hitting  Ctrl-C  and  clearing  the  display,
       changing  the  display  mode, etc. from within cdb.  Only the first and
       third digit of the -v option and display command argument,  namely  the
       display speed and level, have an effect (see PMARSV above). The display
       speed setting (0=fastest, 7=slowest) adjusts the screen  refresh  rate;
       depending  on  the  size  of  your display, movement in core may appear
       "jerky" at fast speeds.  Control keys at  the  cdb  prompt  generate  a
       macro call like in the DOS versions.

       If  you redirect standard input (by supplying a '-' filename or parame-
       ter file), all interactive input is disabled.

MACINTOSH DISPLAY
       MacpMARS is a Macintosh version of pMARS with a graphical core  display
       and  standard  Macintosh  user  interface. It has two windows, the Core
       window and Text window. The display of the core uses four patterns  for
       each warrior (black and white backgrounds respectively) to show what is
       happening in the core:

       '/' when the core location is written to  (including  incrementing  and
       decrementing);

       '\' when a process has died at the core location;

       '-' when a process has executed at the core location;

       '|' when a process is waiting to execute at the core location.

       If  you  click  on a core location in the Core window while a battle is
       being run, the contents will be displayed in the Text window.

       Two warriors can be in memory at any one time. To  assemble  a  warrior
       choose  "Choose Warrior n..." from the File menu. To remove the warrior
       from memory choose "Remove Warrior n...". You can modify  the  settings
       used by choosing "Preferences..." (this can only be done when no battle
       is being run). Alternatively, you can type in a  command  line  in  the
       same  way  as  if you were typing from a unix prompt (if you're used to
       that sort of thing) by choosing "Command Line...".  The  Edit  menu  is
       just  the  normal  Macintosh Edit menu and can be used to cut and paste
       text in the Text window and dialogs. The items in  the  Play  menu  are
       fairly  self-explanatory:  "Go"  starts (or continues) a battle; "Step"
       executes one instruction and enters the debugger; "Halt" halts the bat-
       tle and enters the debugger; "Abort" aborts the battle. The Window menu
       is used to show and bring either of the two windows to the front of the
       screen.

       The  cdb  commands display, switch and close are not available in Macp-
       MARS.

       Note: to use very large core sizes (up to about 65000) and process lim-
       its  you may need to increase the memory partition for MacpMARS.  To do
       this, choose "Get Info" from the File menu in the Finder  and  set  the
       preferred memory size to about 1200K.

EXIT CODES
       The  following  is  mainly useful for people who write scripts or batch
       files for pMARS.  Upon normal exit, the program returns 0. Below  is  a
       listing of what the abnormal exit codes mean. Your operating system may
       not support negative exit codes; in this case you have to  convert  the
       value to its unsigned counterpart.

           -4      graphics error
           -3      trying to execute 80386 code on a lesser processor
           -2      memory allocation error
           -1      serious program logic error, contact developers
            1      file not found
            2      command line error
            3      assembly error
            4      user aborted program
       The  exit  codes of the VMS version conform to the VMS standard. The -Q
       (Query) command line option (see OPTIONS) allows you to  customize  the
       pMARS  exit  code.  E.g. "pmars -Q 1000" returns the current pMARS ver-
       sion. Below the -Q arguments and what the resulting exit codes mean.

       1..W   exit code is score of this warrior, 1: first in  result  output,
              2: second, a.s.o.. If the -o option is also given, "1" gives the
              score of the highest scoring warrior, etc..

       101..1W
              returns the number of this warrior in the result output. Usually
              -Q  101  returns  1,  -Q 102 returns 2 etc., so this is not very
              useful. If you also specify the "-o" (order results) option,  -Q
              101  returns  the position of the highest scoring warrior on the
              command line, -Q 110 the position of the  10th  highest  scoring
              warrior, etc..

       1000   exit  code is the pMARS version in the same format as the prede-
              fined VERSION variable.

       1001   returns the pMARS "variant": 0 if the program was compiled  with
              the  SERVER  option  (no  debugger), 1 with debugger but without
              display, 2 with debugger and core display.

       1002   returns a combination of version  and  variant:  10*variant+ver-
              sion.

       1003   the  exit  code  is  the core address size in bytes. On a 32-bit
              CPU, this is sizeof(int), usually 4. With SMALLMEM  compilation,
              core address size is sizeof(unsigned short), usually 2.

       2000   returns how many warriors share one or more P-spaces. A value of
              4, e.g.  means that either four warriors share one  P-space,  or
              that two pairs of warriors share two P-spaces.



PMARS v0.9.4                     July 4, 2022                         PMARS(6)
