1PMARS(6) Games Manual PMARS(6)
2
6 pmars - portable corewar system with ICWS'94 extensions
7
9 pmars [ option ... ] file1 [ file(s) ]
10
12 pMARS (portable Memory Array Redcode Simulator) is a corewar inter‐
13 preter with multi-platform support. pMARS currently runs on UNIX sys‐
14 tems, PC/DOS, VMS, Amiga (AmigaDOS command line), and the Mac. pMARS
15 implements the ICWS'94 draft standard, but can also be used in ICWS'88
16 mode. The base system includes a graphical core display for UNIX
17 (curses, X-windows), PC/linux (svgalib), PC/DOS and the Mac (see APPEN‐
18 DIX). A line-oriented debugger is included to help in writing warriors
19 for the ICWS'94 draft standard.
20 pMARS runs one or more warriors written in Redcode that are provided as
22 file(s) on the command line. Running a single warrior is supported for
23 debugging. Two warriors are pitted against each other for standard
24 play, but up to 36 warriors can be named for "multi-warrior" core war.
25 If the warrior(s) assemble without error they are loaded into the core
26 array and executed in round-robin mode starting with the first warrior.
27 Warrior 1 is loaded starting at core position 0, warrior 2, 3, etc., at
28 either a random or fixed position. For fairness the starting order is
29 rotated after each round.
30
32 The score is reported after all rounds have been played. A round ends
33 when either a single surviving warrior remains or when a maximum number
34 of cycles has elapsed. For each round, every surviving warrior is
35 awarded points calculated from a score formula (F). By default, this
36 is (W*W-1)/S, where W is the total number of warriors participating, S
37 is the number of of survivors, and "/" is integer division. Alternative
38 score formulas can be specified with the = option (see below).
39 When two warriors battle, the results are reported as wins1, wins2, and
41 ties, where wins1 and wins2 are the numbers of rounds that each warrior
42 won, and ties are the number of rounds in which both warriors lasted
43 until time-out. The score is then:
44 warrior 1: points = wins1 * F + ties * F
46 warrior 2: points = wins2 * F + ties * F
47 F is a score formula containing the W and S parameters. When more than
49 two warriors (W) participate in a game, results are reported as
50 wins[1], wins[2], .., wins[W], losses for each warrior, where the index
51 indicates the number of warriors that survived until the end (S parame‐
52 ter in the score formula). The total number of points for each warrior
53 is then calculated as:
54 points = sum (S=1..W) (wins[S] * F)
56 A few alternative score formulas:
58 10
59 (W+1)/S
60 (x=W-S+1)*(x+1)/2
61 (S==3)*5 + (S==2)*3 + (S==1)
62 (S == 1)*W + (S != 1)
63
65 Command line options may occur anywhere on the command line. Single-
66 letter options without a parameter can be combined as in -fbe. The spe‐
67 cial argument - (dash) stands for standard input (stdin). It can be
68 combined with the -@ option (see below) to signify reading options from
69 stdin, or the - can take the place of a warrior filename, in which
70 case warrior code starting with a ;redcode line and ending with an END
71 statement is extracted from stdin. The END statement can be omitted if
72 the next ;redcode line immediately follows the last instruction. Sev‐
73 eral warriors, each specified by a separate dash on the command line
74 and bracketed by ;redcode/END can be piped into pMARS. #- (where # is
75 a positive number) is a shorthand for writing this number of dashes on
76 the command line.
77 -r # This options sets the number of rounds to play. The default is
79 1. -r 0 produces assembly output (unless -b is specified), but
80 does not execute the warrior(s). A maximum of 32787 rounds can
81 be specified.
82 -s # The -s option specifies the size of core memory in number of
84 instructions. It defaults to 8000. Maximum core size is plat‐
85 form-dependent, but usually at least 65535.
86 -c # -c sets the maximum number of cycles per round. A cycle con‐
88 sists of one execution of each warrior. A round ends when either
89 a single warrior remains executing or when the maximum number of
90 cycles has elapsed.
91 -p # This option sets the maximum number of processes a warrior can
93 run. The default is 8000.
94 -l # This sets the maximum length of a warrior source file in
96 instructions. It defaults to 100 and can be up to 500.
97 -d # This option specifies the minimum distance between the first
99 instruction of each warrior. It cannot be smaller than the maxi‐
100 mum length (-l option) and defaults to 100 instructions.
101 -S # The -S option sets the size of the P-space to # cells. The
103 default is 1/16th of core size if core size is evenly divisible
104 by sixteen, or the next larger divisible fraction. See also the
105 P-SPACE section below.
106 -f The -f option instructs the loader to use a fixed series of
108 addresses for positioning warriors. This is done by initializing
109 the pseudo random number generator with a checksum value derived
110 from the source of all warriors. Thus, initial placements will
111 still be "random" from round to round, but will be the same if
112 the same warriors are run again. As a consequence, the result of
113 battles run with the -f option will show no statistical fluctua‐
114 tions. This options is useful for validating ports of pMARS to
115 new platforms and for providing an absolute, albeit arbitrary
116 performance measure for warriors.
117 -F # This option server two purposes. It sets the seed value of the
119 pseudo random number generator, and also tells the loader to
120 install warrior 2 at the given address # for round 1. If the
121 number is larger than the core size minus the minimum warrior
122 distance, it will be wrapped around to the range of available
123 starting positions. This option is useful for testing different
124 versions of a warrior with constant initial placement. Warrior
125 1 is always installed at address 0. The -F and -f options are
126 mutually exclusive. If neither option is specified, the pseudo
127 random number generator is initialized with the system time.
128 -P This option makes pMARS use an alternative algorithm for posi‐
130 tioning warriors. This algorithm uses all possible combinations
131 of starting order and position in a random sequence, and will
132 not use the same combination twice unless all the combinations
133 have already been used. If the -r option is not given, the num‐
134 ber of rounds fought will be the number of all possible combina‐
135 tions. Trying to use this option with more (or less) than two
136 warriors causes an error.
137 -e If this option is specified, the cdb debugger is entered immedi‐
139 ately after loading warriors into core.
140 -b This options runs pMARS in brief output mode. -b suppresses war‐
142 rior listings after assembly.
143 -k With the -k option, pMARS uses the same output format as the
145 KotH program. This option enables pMARS to work with scripts
146 written for the KotH server.
147 -8 This options enforces strict compliance with the ICWS'88 stan‐
149 dard and disables all ICWS'94 language extensions, which are
150 flagged as syntax errors by the assembler. Since ICWS'94 is a
151 superset of ICWS'88, this options is not necessary to run
152 ICWS'88 warriors.
153 -o When this option is given, pMARS reports scores in decreasing
155 order rather than in the order warriors were named on the com‐
156 mand line. This is mostly useful for multi-warrior play.
157 -V The assembler generates verbose output with this option. This is
159 only useful for debugging.
160 -v This option sets the display mode for UNIX and DOS display ver‐
162 sions (see APPENDIX).
163 -@ <fn>
165 pMARS continues reading options and filenames from the parameter
166 file <fn>. If <fn> is a - (dash) standard input is parsed. Com‐
167 ments in the parameter file start with a semicolon.
168 -= <string>
170 The = (equal) option allows you to specify a custom score for‐
171 mula (see SCORE). The formula may contain the standard arith‐
172 metic and logical operators (as in the C language), as well as
173 the parameters W (number of warriors participating) and S (num‐
174 ber of warriors surviving this round). You need to enclose the
175 formula string with quotes if it contains spaces or characters
176 interpreted by the operating system.
177 -Q # The "query" option is intended for use in scripts that run pMARS
179 in batch mode. Depending on the number code following -Q, the
180 program returns an informative number as the exit status.
181 "pmars -Q 1000" e.g. will cause pMARS to exit with a code that
182 spells out the program version. More on -Q arguments and exit
183 codes can be found in the ADDENDUM.
184 $ The $ (dollar) parameter is not preceded by a dash and cannot be
186 grouped with other options. It terminates reading command line
187 parameters and is used in parameter files or input streams (-@
188 fn). The $ is necessary if you want to combine two or more of
189 command line parameters, warrior code and cdb commands in the
190 same input stream or file. Below an example of such a combined
191 input file:
192 ;Below the command line parameters:
193 -r 10 -beF 1000 2- $
194 ;redcode
195 ;name Imp 1
196 ;assert 1
197 mov 0,1
198 end
199 ;redcode
200 ;name Imp 2
201 ;assert 1
202 mov 0,2
203 mov 0,2
204 end
205 !! cdb commands follow:
206 sk 1000
207 reg
208 quit
209
211 The X-Windows display version of pMARS has these additional command
212 line options:
213 -display <string>
215 Expects a string specifying the display where the window should
216 appear. Following X standards, this display specification has a
217 format of hostname.domain:display.screen where the part before
218 the colon is the standard internet host specification and dis‐
219 play and screen are integers. The screen specification can be
220 omitted. For an example, consider you are working at an X termi‐
221 nal named ncd13.complang.tuwien.ac.at and remotely logged in at
222 host stud1.tuwien.ac.at where the binary of pmars lies, you can
223 use the following command line
224 stud1$ pmars -display ncd13.complang.tuwien.ac.at:0 -b aeka.red aeka.red
226 and the window will appear at you local screen.
227 -geometry <string>
229 Lets you specify the initial size and position of the window.
230 The format is widthxheight+x+y where width, height, x, y are
231 integers and + may be replaced by -. Either of the two parts
232 (widthxheight or +x+y) may be omitted. This overrides the -v
233 switch concerning the window geometry. As an example, pmars
234 -geometry 600x400+30+100 .... will open a window of 600 by 400
235 pixels at the screen position (30,100). pmars -geometry
236 1024x768 ... creates a window of 1024x768 pixels and pmars
237 -geometry -20+300 ... creates a window with standard size with
238 its left upper corner at position (-20,300), i.e. out of the
239 left side of the screen.
240 -fn <string>
242 The string following this argument specifies the X font to use.
243 By default, a terminal font is used. If this font can't be
244 found, "fixed" is used for a font ("fixed" should be present at
245 every X installation). Use the command 'xlsfonts' to get a
246 listing of fonts that can be used at your X server. 'xfontsel'
247 provides a comfortable way to select a font. "fixed" is the
248 fallback if the specified font can't be found. It is strongly
249 recommended to use a fixed pitch font.
250 The argument of the -v display option has an additional fourth digit in
252 the X-Windows version: 0 (the default) enables the color display, 1 the
253 grayscale, and 2 the black and white display (e.g. -v 1033 for the
254 grayscale display).
255
257 pMARS implements an extension of the proposed ICWS'94 standard. The new
258 instruction modifiers .A,.B,.AB,.F,.X, and .I, the arithmetic instruc‐
259 tions MUL, DIV and MOD, as well as post-increment indirect (>) are sup‐
260 ported. pMARS currently does not implement read/write ranges, although
261 they may be added in future versions.
262 Version 0.5 of pMARS adds support for three experimental opcodes that
264 are currently not included in the ICWS'94 draft:
265 SEQ (Skip if EQual): this is a synonym for CMP and is included mainly
267 for clarity (future versions of pMARS may implement SEQ as a "prede‐
268 fined EQU" rather than a true opcode).
269 SNE (Skip if Not Equal): the opposite of SEQ.
271 NOP (No OPerations): do nothing.
273 Version 0.6 adds three new indirect addressing modes that use the A-
275 field instead of the B-field as the pointer for indirection:
276 * - indirect using A-field
278 { - predrecement indirect using A-field
280 } - postincrement indirect using A-field
282 The new P-space instructions of version 0.8 are discussed under sepa‐
284 rate heading below.
285 The assembler also supports multi-line EQU statements, a feature not
287 included in the current ICWS'94 draft. The format for multi-line
288 EQUates is
289 <label> EQU <line1>
290 EQU <line2>
291 [...]
292 EQU <lineN>
293 <label> in the warrior source is replaced by <line1> <newline> <line2>
294 <newline> [....] lineN. In contrast to KotH, pmars EQUs substitute
295 arbitrary text, and not just expressions. EQU expressions are not
296 implicitly parenthesized.
297 pMARS features the non-standard FOR text-repetition macro. This macro
299 repeats the text between FOR and ROF a specified number of times:
300 <labels> <counter> FOR <times>
301 [..]
302 ROF
303 <times> is an expression specifying the number of expansions; it may
304 contain EQUates and labels as long as they have been defined before the
305 FOR/ROF block. <counter> is the last label before the FOR word, but
306 not necessarily on the same line. It is expanded to 01, 02, ..,
307 <times> in each repetition. The optional <labels> label the first
308 instruction after FOR expansion. An example:
309 ORG start
310 start
311 sp FOR 2
312 a&sp SPL a&sp
313 JMP a&sp
314 ROF
315 becomes after expansion
317 start
319 a01 SPL a01
320 JMP a01
321 a02 SPL a02
322 JMP a02
323 The symbol & concatenates 'a' and 01, 02 to form a valid label. EQU
324 expansion and FOR/ROF processing is done in the same pass. It is
325 therefore possible to write
326 dest01 EQU 500
327 dest02 EQU 1000
328 dest03 EQU 1500
329 idx FOR 3
331 MOV src,dest&idx
332 MOV src+1,dest&idx
333 ROF
334 src MOV <-1,<-1
336 JMP src,<-2
337 Using predefined EQUates (see below) it is possible to define adaptive
338 FOR/ROF blocks. The next example fills the remainder of the warrior (up
339 to MAXLENGTH lines) with decoy instructions:
340 FOR MAXLENGTH-CURLINE
341 DAT 1,1
342 ROF
343 Since true logical expressions have a value of "1" and false expres‐
344 sions a value of "0", you can write conditionally assembled code
345 enclosed by FOR/ROF:
346 FOR CORESIZE == 8000
347 <some code>
348 ROF
349 FOR CORESIZE != 8000
351 <other code>
352 ROF
353 pMARS uses KotH-style ;name and ;author comments to describe warriors.
354 If a line starting with ;redcode is present, all text preceding it is
355 ignored. This makes it possible to run posted warriors without removing
356 mail headers and descriptive text. The ;version, ;strategy and other
357 comments mentioned in the ICWS'94 draft are currently not used.
358 As another "non-standard" extension, the assembler predefines the fol‐
360 lowing run-time variables: CORESIZE, MAXPROCESSES, MAXCYCLES,
361 MAXLENGTH, MINDISTANCE, ROUNDS, and PSPACESIZE. They can be used in
362 your Redcode as though they were defined by EQUs like
363 CORESIZE EQU 55440 ;current value of -s parameter
364 MAXPROCESSES EQU 10000 ;current value of -p parameter
365 [etc.]
366 The run-time variable CURLINE holds the current instruction number off‐
367 set from the first instruction. WARRIORS is initialized with the number
368 of warriors specified on the command line.
369 pMARS supports the ;assert directive as a way of checking whether a
371 warrior is run under the parameters it was designed for. If the expres‐
372 sion following ;assert evaluates to "0" (false), assembly is aborted
373 with an error message. If an ;assert is missing, a warning is issued.
374 Examples:
375 ;assert CORESIZE == 55440 && MAXLENGTH >= 200
376 ;assert !(CORESIZE % 4) ; is multiple of 4
377 ;assert 1 ; if warrior works under all settings
378 The run-time variable VERSION holds the current pMARS version (e.g.
379 "60" is v0.6.0) and is useful in ;assert expressions.
380 With the -8 option, pMARS is fully ICWS'88 compatible, except that a
382 comma is required between operands. Extensions like predefined and
383 multi-line EQUs and FOR/ROF are supported even in ICWS'88 mode.
384 A full treatment of corewar and ICWS'94 in particular is beyond the
386 scope of this document. General information about corewar as well as
387 the ICWS'94 draft is available by anonymous FTP from soda.berkeley.edu
388 in pub/corewar.
389
391 Originating from discussions on rec.games.corewar, P-space is an
392 attempt at making warriors more "intelligent" by giving them a memory.
393 P-space, short for "private", "permanent" or "priviledged" space is a
394 memory area separate from core whose contents is not cleared between
395 rounds. Every warrior has its own P-space for gathering information
396 about the opposing warrior, but there is a provision for sharing P-
397 space in team play (see below).
398 P-space cells contain values in the range 0..CORESIZE-1. The number of
400 P-space cells can be adjusted with the -S command line option; by
401 default, P-space size is 1/16th of CORESIZE. This number is available
402 to warriors as the predefined variable PSPACESIZE. pMARS updates P-
403 space cell 0 at the beginning of each round with the result of the pre‐
404 vious round: 0 signifies a loss in the previous round, a number larger
405 than zero means that the warrior survived until the end of the round,
406 the value indicating the number of surviving warriors. That is, a value
407 of "1" means that the warrior survived by itself (a "win" in a two-war‐
408 rior battle), a value of "2" that two warriors lasted until the end (a
409 "tie" in a two warrior battle), etc.. In the first round, P-cell 0 is
410 set to -1 (actually CORESIZE-1) to indicate that there is no previous
411 result.
412 There are two new instructions for accessing P-space:
414 LDP (Load P-space) loads P-space cell specified by A-value into core
416 at B-address.
417 STP (Store P-space) stores A-value into P-space cell specified by B-
419 value.
420 It is important to note that P-space cells are refered to by A/B-values
422 as opposed to A/B-addresses. As an example, "STP #9,#1" stores number 9
423 in P-cell 1.
424 Since all P-space access is only via these two instructions, it takes
426 too much time and space to use P-space for working variables where they
427 would be safe from the opposing warrior. P-space was made deliberately
428 hard to access, unlike a set of general purpose registers.
429 P-space can also be used for communication between warriors belonging
431 to a team in multi-warrior core war. To allow communication, P-space
432 has to be declared as "shared". You do this by including the PIN
433 pseudo-opcode in your source:
434 PIN (P-space Identification Number) has a single numerical argument.
436 If two or more participating warriors have the same PIN argu‐
437 ment, they share the same P-space. If the PIN pseudo-opcode is
438 missing from a warrior's source, its P-space is strictly pri‐
439 vate. The PIN argument is not normalized to [0..CORESIZE-1]
440 before comparison. "PIN 0" and "PIN CORESIZE" are therefore not
441 the same.
442 P-cell #0 holding the result of the last round is exempt from sharing,
444 i.e. every warrior has its own last round cell even though the rest of
445 its P-space may be shared.
446
448 Cdb is a line-oriented debugger. It is invoked either by specifying the
449 -e option (enter cdb immediately), by including debugging commands in
450 the warrior source, or by hitting Ctrl-C during the simulation. The
451 debugger is also entered whenever a warrior terminates ("post-mortem")
452 if execution was started with the go command. cdb is very powerful and
453 has an overwhelming number of commands. You may want to start with only
454 the most often used commands: step (single step execution), go (execute
455 until breakpoint), list (look at core), trace and untrace (set and
456 remove breakpoints), and go on to more complex ones later.
457 The following commands are available at the cdb prompt; commands can be
459 abbreviated to the first unambiguous substring.
460 <Enter>
462 repeats the last command issued at the cdb prompt.
463 help displays a brief command summary.
465 progress
467 displays the status of the current game in progress.
468 registers
470 displays the current state of the simulator, including program
471 counters and task queues.
472 go runs the simulator until an instruction whose trace bit is set
474 is executed. If there are no traced instructions go returns to
475 the post-mortem debugger.
476 step executes the next instruction in the task queue and returns to
478 the cdb prompt.
479 continue
481 returns to the simulator to complete the game without interrup‐
482 tions.
483 thread is similar to step except that only the current task thread is
485 traced.
486 skip [count]
488 executes the next [count] instructions in the queue silently
489 before returning to the cdb prompt.
490 execute [address]
492 resets the task queue of the current warrior to [address] and
493 executes it. This is useful in conjunction with edit.
494 quit aborts pMARS and returns to the OS prompt.
496 trace [range]
498 sets the trace bit of the specified address or address range.
499 untrace [range]
501 clears the trace bit of the specified address or address range.
502 moveable on|off
504 specifies whether the trace bit is copied by the MOV.I instruc‐
505 tion. The default is on.
506 list [range]
508 displays the specified range of core addresses, a set trace bit
509 is indicated by 'T'. Unmodified addresses (DAT.F 0,0) are shown
510 as blank.
511 edit [range]
513 allows modifying core. The specified addresses are edited by
514 typing in new instructions. Typing one or more spaces leaves the
515 core address unchanged, just hitting <return> repeats the last
516 input, and a syntax error aborts the edit. The full Redcode syn‐
517 tax including labels and (multi-line) EQUates can be used. Label
518 and EQUate definitions remain in effect until the program termi‐
519 nates. The edit command is useful for modifying warriors and
520 trying out single instructions without having to exit and
521 restart pMARS.
522 fill [range]
524 is similar to edit. Instructions in the specified range are
525 replaced by one typed in instruction. Entering DAT.F 0,0 ,e.g.
526 clears the address range.
527 search [pattern]
529 searches core instructions for a text pattern in the forward
530 direction. The next instruction matching [pattern] is displayed.
531 The search includes the address number and trace symbol (T), is
532 case- and space-insensitive and may contain wildcards: * (aster‐
533 iks) matches any number of characters; ? (question mark) matches
534 exactly one character. E.g. "search ," searches for the next
535 non-blank address; "search dat*, ?0t" searches for the next DAT
536 instruction that is traced and has a zero B-operand value,
537 regardless of modifier, A-operand and B-mode.
538 write [file]
540 opens a file for logging subsequent cdb output to. The logfile
541 is closed by issuing write without an argument.
542 echo [string]
544 is used mostly inside macros. [string] is echoed to the screen
545 followed by <newline>.
546 remark [string]
548 is ignored by cdb and can therefore be used to comment macros.
549 cls clears the screen. The no-display UNIX version does this by
551 echoing an ANSI escape sequence; if this doesn't work for you,
552 you need to change the CLRSCR string in config.h and recompile.
553 clear is a synonym for cls .
554 display clear|on|off|nnn
556 (available in display versions only) allows clearing the core
557 display (display clear) or changing the display mode. display
558 on changes the display to the default mode, display off (same as
559 display 0 ) suspends all display updates, and display nnn ,
560 where nnn is a 1 to 3-digit number, sets the display to this
561 mode. "nnn" is interpreted like the parameter to the -v command
562 line option (see APPENDIX).
563 switch [1|2]
565 (available in display versions only) makes the left (1) or right
566 (2) panel the current panel for cdb output. Without a number
567 argument switch changes to the other panel. If the right panel
568 doesn't exist (initially, or after close, see below), it is cre‐
569 ated first.
570 close (available in display versions only) closes the right cdb panel
572 (if it exists) and makes the left panel fullscreen.
573 calc expr1[,expr2]
575 is a command line calculator. Since calc has no side-effects
576 other than echoing the result of expression 1 (and expression 2
577 if provided). In the context of cdb macros it is also used to
578 assign values to the register variables 'c' through 'z'.
579 macro [name][,file]
581 loads, executes or lists macros. A macro expands to one line of
582 cdb commands separated by the tilde character (~) (a so-called
583 command chain, see below). The command macro name executes the
584 macro "name"; if "name" is left out, all currently available
585 macros are listed. macro name,file loads macro definitions from
586 file "file" and executes macro "name"; again, if "name" is miss‐
587 ing, only a listing is produced. Macro definitions are appended
588 to the list of previously loaded definitions or replace a previ‐
589 ously loaded macro definition with the same name. If you are
590 trying to execute or list macros, but no macros have been loaded
591 yet, the default macro file "pmars.mac" is loaded automatically.
592 The special macro file "user" can be specified to input macro
593 definitions directly from the keyboard. Macro definitions con‐
594 sist of a macro name, followed by the equal sign, followed by a
595 command (chain). The macro name can consist of any printable
596 character excluding <space> and comma; the equal sign is only
597 allowed at the end of a macro name. Individual macro lines have
598 a limit of 80 characters, but macro calls inside macro expan‐
599 sions are allowed. Cdb can hold up to 200 macros in memory.
600 See also the section on cdb macro programming below.
601 if <expression>
603 controls execution of commands in macros or command chains. If
604 <expression> evaluates to zero, the next command block is
605 skipped. A command block consists of either a single command or
606 any number of commands bracketed by !! (loop start) and ![e]
607 (loop end, see section on macro programming below). <expres‐
608 sion> may contain C-style comparison and boolean operators (see
609 below). An if immediately preceeding a loop end (![e]) can skip
610 out of the loop.
611 reset is used inside macros in conjunction with if to terminate macro
613 execution, e.g. inside an infinite loop (...~if
614 A==0~reset~...~!).
615 pqueue [1|2|..|off]
617 switches cdb into "process queue mode". In this mode, list, edit
618 and fill operate on the process queue instead of the core array,
619 i.e. you can view and modify the process queue as easily as the
620 core array. This is especially useful for debugging complicated
621 multi-process warriors. pqueue without argument uses the
622 process queue of the current warrior. With argument 1,2,.., uses
623 the process queue of warrior 1,2,.., respectively. pqueue off
624 returns to normal mode.
625 wqueue [off]
627 stands for "warrior queue" and is similar to pqueue, except that
628 numbers provided as arguments for list, edit and fill now refer
629 to warriors: "list 0" now shows the program counter of warrior
630 1, "list 1" that of warrior 2 and so on. wqueue off returns to
631 normal "address mode".
632 pspace [1|2|..|off]
634 complements the pqueue and wqueue commands. If a number is spec‐
635 ified, the P-space of that warrior is selected for viewing/edit‐
636 ing. Without an argument, the P-space of the currently executing
637 warrior is selected. "pspace off" returns to core mode.
638 go, step, continue and thread may have a single address argument. The
640 program counter of the current warrior is set to this address before
641 execution continues.
642 The range argument of the list, trace, etc. commands has the format
644 <start>,<stop>. Addresses <start> and <stop> are numbers, special sym‐
645 bols or C-style expressions including special symbols. If either
646 <start> or <stop> is omitted, it defaults to the current address. If
647 both are omitted, the range of the last cdb command is used. A single
648 address (without the comma) acts on only that address. Addresses start‐
649 ing with a + or - are interpreted relative to the current address.
650 Expressions may contain the arithmetic operators -,+,*,/,% (modulo),
652 the comparison operators ==, !=, <=, >=, and the boolean operators &&
653 (AND), || (OR), and ! (negation). Expressions may also include regis‐
654 ter variables C through Z and the assignment operator =. Operator
655 precedence is like that of the C-language and may be overridden by
656 parentheses. Assignment, comparison and boolean operations are mostly
657 used with calc and if commands in macros, but can also be used in Red‐
658 code operands.
659 Special address symbols used in cdb commands:
661 . (dot) is the current address (displayed last).
663 $ (dollar) is the last core address.
664 A is the A value of the current instruction.
665 B is the B value of the current instruction.
666 PC is the program counter of the currently executing warrior.
667 PC1 is the program counter of warrior 1.
668 PC2 is the program counter of warrior 2.
669 LINES is the number of lines available to the cdb display
670 CYCLE is the current execution cycle (counted down)
671 In process queue (pq), warrior queue (wq) or pspace (ps) mode (see
673 pqueue, wqueue, pspace), most of these symbols have a different mean‐
674 ing:
675 . (dot) is the current process number (pq),
677 warrior (wq), or P-space cell (ps) which was displayed last.
678 $ (dollar) is the last process in the process queue (pq),
679 the last warrior (wq), or the last P-space cell (ps).
680 A is the A value of the instruction of the current process (pq),
681 the next executing process of the current warrior (wq), or
682 the P-space selector (ps, same as warrior number if unshared).
683 B is the B value of the instruction of the current process (pq),
684 the next executing process of the current warrior (wq), or
685 the P-space selector (ps).
686 PC is 0.
687 PC1.. are 0
688 Preceding a command with the character '@' (ampersand) will suppress
690 its screen output, but not output to a logfile. Preceding a command
691 with '&' will suppress both screen and logfile output, which is useful
692 if you are only interested in the "side-effects" of a command. Start‐
693 ing a command with a <Space> character suppresses saving it to the
694 "last-command" buffer that is recalled by <Enter>.
695
697 Several commands can be issued on one line when separated by the tilde
698 character ( ). These "command chains" are useful for repeating long
699 command sequences, since <Enter> recalls the entire chain (see the
700 examples below). Commands requiring user intervaention (list, edit,
701 fill) also read their input from the chain.
702 The "empty command" (two consecutive tildes or a tilde at the end of
704 the chain) repeats the last command in the chain. A command consisting
705 of <Space> is a null command and is used to simulate pressing <Enter>
706 in list, edit and fill.
707 The exclamation mark (!) character is a special "chain repetitor" com‐
709 mand. The optional expression following '!' specifies how many times
710 the command chain starting at the beginning of the line or the last ´!'
711 is executed. '!' without an expression repeats until the program termi‐
712 nates.
713 The symbol '!!' is used for nested loops and marks the start of a com‐
715 mand block to be repeated. The command block is closed by '![expres‐
716 sion]' and may contain other command blocks. A command block immedi‐
717 ately following an if command is executed only if the condition is
718 true.
719 With loops, subroutines (macros calling macros), variables (C..Z),
721 expressions involving comparisons and boolean operations, and condi‐
722 tional execution (if), the cdb command language can be used to con‐
723 struct complicated macros for e.g. executing a warrior until a certain
724 core address has changed, controlling the 2-panel display, automati‐
725 cally finding the right constants for a warrior, etc. See the file
726 "pmars.mac" for examples.
727
729 list ,+20
730 lists the next 20 instructions.
731 trace pc-10,pc+10
733 traces 21 addresses centered around the program counter of the
734 currently executing warrior.
735 untrace 0,$
737 clears all trace bits.
738 go reg l+a,+b
740 chains these commands: execute until the next traced address or
741 end of round, display the simulator status and list addresses in
742 the range A-number to B-number of the current instruction.
743 @fill0,100 dat.f 0,0
745 fills addresses 0 through 100 with 'dat.f 0,0', not echoing the
746 changed addresses to the screen.
747 write trace.log step !
749 produces a continuous execution trace by repeating step until
750 pMARS terminates, saving the output to logfile "trace.log".
751 @l x=5 !! @ed x~dat x,0 if (x=x+1)<$+1 !
753 This command chain could be useful for debugging a stone-type,
754 self-modifying warrior, which is assumed to occupy address 0
755 through 4 in this example. The command fills core starting at
756 address 5 with "dat 5,0", "dat 6,0", a.s.o., so that you can
757 tell where a bomb which overwrites the warrior came from. To
758 save some typing, you can turn this command into a macro (foo=@l
759 x=5~..). This is how it works, step by step: Assign 5 to regis‐
760 ter x and make it the current address (@l x=5). Start a loop
761 (!!) and change address x to "dat x,0" (@ed x~dat x,0). Incre‐
762 ment x, if x is then smaller than the core size ($+1), continue
763 looping (if (x=x+1)<$+1~!). The '@' in front of the list and
764 edit commands suppresses screen output.
765 @s @4 if b<2 || b>=$-3 reset !
767 This command executes a warrior until the B-field of address 4
768 points to address 0 through 5: Step and make address 4 the cur‐
769 rent address (@s~@4). If the B-field is less than 2 or greater
770 than or equal to 7996 (CORESIZE-1-3) stop execution, else con‐
771 tinue looping (if b<2 || b>=$-3~reset~!).
772
774 Trace bits can also be set by including debugging commands in the war‐
775 rior source. A comment format is used to retain compatibility with sim‐
776 ulators that do not support source-embedded debugging commands.
777 ;debug [static/off]
779 This command enables/disables all subsequent source-embedded
780 commands. It is used for commenting out other source comments.
781 ;debug static has the same effect as the command moveable off at
782 the cdb command prompt. ;debug is implicitly added in front of
783 every warrior. The last ;debug or ;debug static encountered
784 specifies whether the trace bit is copied by a MOV.I instruction
785 or not.
786 ;trace [off]
788 ;trace starts setting the trace bit with the next instruction
789 until EOF or a ;trace off command is encountered.
790 ;break sets the trace bit of the next instruction.
792
794 We will be glad to assist in porting pMARS to other, currently unsup‐
795 ported platforms. This program is still under development and we will
796 continue to enhance functionality and speed, as well as adapt to
797 changes in the proposed ICWS'94 standard. If there is demand, future
798 versions of pMARS will also implement read/write ranges
799
801 None whatsoever (right). Contact for bug reports and suggestions is
802 Stefan Strack (stst@vuse.vanderbilt.edu). Please be detailed and
803 include a logfile of the cdb session if applicable. Bug reports and
804 suggestions concerning the Macintosh display and interface should also
805 be directed to Alex MacAulay (macaulay@mundil.cs.mu.oz.au).
806
808 The portable MARS project was initiated after discussing the ICWS'94
809 draft on the rec.games.corewar newsgroup. We realized that we needed a
810 portable system to try out the proposed standard and to accept, modify
811 or reject it. The people who started portable MARS and are responsible
812 for the base code as well as the DOS and UNIX displays are:
813 Albert Ma (ama@athena.mit.edu)
815 Nandor Sieben (nandor.sieben@asu.edu)
816 Stefan Strack (stst@vuse.vanderbilt.edu)
817 Mintardjo Wangsaw (wangsawm@csos.orst.edu)
818 Alex MacAulay (macaulay@mundil.cs.mu.oz.au) wrote the Macintosh display
820 version. Martin Maierhofer (m.maierhofer@ieee.org) contributed the
821 linux SVGA and X windows display. Nathan Summers (00ncsum‐
822 mers@bsuvc.bsu.edu) did the port to VMS.
823
825 We thank Planar (Damien.Doligez@inria.fr) for expert help with debug‐
826 ging and porting pMARS to different UNIX machines. We also appreciate
827 the help of Chris Lindensmith (lind0014@student.tc.umn.edu) and Pierre
828 Baillargeon (dak@info.polymtl.ca) with the initial Mac and Amiga ports
829 respectively. Mark Durham (durham@ricevm.rice.edu) spearheaded devel‐
830 opment of the ICWS'94 draft and we thank him for writing the sample
831 interpreter code included with the draft.
832
835 pMARSv is a DOS version of pMARS with a graphical core display. You can
836 chose between EGA/VGA graphics or text mode with the -v command line
837 options or by pressing 'v' during the game. The -v option takes a three
838 digit argument 'xyz'. Digit 'x' specifies the initial display speed and
839 ranges from 0 (fastest) to 7 (slowest). 'y' is the initial display
840 mode: 0 for text mode, 1 for standard VGA graphics, 2 and 3 for SVGA, 4
841 and 5 for EGA, and 6 for CGA graphics.
842 The display level 'z' specifies how much is displayed:
844 0 Display nothing. This greatly speeds up execution, especially
846 when in graphics mode.
847 1 Display execution of addresses. In text mode, a black '0' on
849 blue background is shown for warrior 1, a black '1' on green for
850 warrior 2, a.s.o.. Numbers blink in white when a DAT instruction
851 is executed. In graphics mode, a blue square represents warrior
852 1, a green square warrior 2, a.s.o.. These colors are also used
853 for other core accesses.
854 2 Also display write accesses. In text mode, they appear as dots;
856 in graphics mode, they appear as two pixels, offset diagonally.
857 3 Also display decrements and increments. They are shown as '+'
859 and '-' in text mode and as two pixels offset vertically or hor‐
860 izontally in graphics mode.
861 4 Also display read accesses, which appear as small dots in text
863 mode and as single pixels in graphics mode.
864 The more is displayed, the slower runs the simulation. The argument
866 for -v defaults to 103, i.e. speed=1, mode=text, level=3.
867 The text mode display is very fast, but contains less on-screen infor‐
869 mation than the graphics display. The core display and the cdb debugger
870 run full-screen on separate display pages.
871 In graphics mode, core and debugger share the same screen. The mouse
873 can be used to navigate around core when debugging is enabled: clicking
874 a mouse button on any core location lists addresses starting there. The
875 mouse cursor follows the current program counter when in single step
876 mode.
877 In both graphics and text mode, the cdb display can be divided into two
879 side-by-side panels. You can switch between panels with the switch com‐
880 mand (or the <Tab> macro) and close the right panel with close (or the
881 <Shft-Tab> macro). Extended (function keys, arrow/page keys, ALT keys,
882 etc.) and control keys generate macro calls at the cdb prompt; some of
883 these "hot key macros" have been defined in "pmars.mac"; you can easily
884 change them or add more with a text editor. E.g. <PgDn> and <PgUp>
885 keys currently invoke macros that scroll through core one screen at a
886 time.
887 A white line at the top of the display, called the time meter, indi‐
889 cates the time required to finish the current simulation. The amount of
890 time depends on the number of warriors still alive in the arena. After
891 a warrior dies it no longer needs simulation time so the required time
892 to finish the simulation becomes less. On the time meter this is indi‐
893 cated by a discontinuity. One can count the number of dead warriors in
894 the arena by counting the number of discontinuities on the time meter.
895 Just below, the length of "process meters" in the color of the warriors
897 they represent show how many processes each warrior has running.
898 The following keys are available at the core display screen:
900 0..4 selects the display level (see above).
902 v switches from text display to graphics display and vice versa.
904 > increases the display speed.
906 < decreases the display speed. The current speed is indicated by a
908 red bar in graphics mode.
909 d enters the cdb debugger. "Debug" on the graphics menu bar is
911 highlighted in red inside cdb.
912 <space>
914 (also 'r') refreshes the core display.
915 <escape>
917 (also 'q') exits to DOS.
918 You can define additional keys and commands associated with them by
920 defining "key-x" macros ("x" is any printable character). E.g.:
921 key-p= progress~registers~continue
922 Function-key and other macros can also be invoked from the core dis‐
923 play.
924
926 The curses display is very similar to the DOS text mode display. There
927 are separate pages for core and debugger. There is a status bar at the
928 bottom of the core display:
929 Rave [0]: 1 Lucky 3 [1]: 3702 Cycle: 72967 R: 2/5 (0 0 1)
931 The display symbol that indicates execution is shown in brackets after
933 the warrior name. The number after the colon shows the number of pro‐
934 cesses active. The "2/5 (0 0 1)" means that this is round 2 of 5; the
935 result so far is one tie. Only cycle and round information is shown if
936 more than two warriors are run.
937 There is no "hot key" user interface during the core display, but you
939 can enter the debugger by hitting Ctrl-C and clearing the display,
940 changing the display mode, etc. from within cdb. Only the first and
941 third digit of the -v option and display command argument, namely the
942 display speed and level, have an effect (see PMARSV above). The display
943 speed setting (0=fastest, 7=slowest) adjusts the screen refresh rate;
944 depending on the size of your display, movement in core may appear
945 "jerky" at fast speeds. Control keys at the cdb prompt generate a
946 macro call like in the DOS versions.
947 If you redirect standard input (by supplying a '-' filename or parame‐
949 ter file), all interactive input is disabled.
950
952 MacpMARS is a Macintosh version of pMARS with a graphical core display
953 and standard Macintosh user interface. It has two windows, the Core
954 window and Text window. The display of the core uses four patterns for
955 each warrior (black and white backgrounds respectively) to show what is
956 happening in the core:
957 ´/' when the core location is written to (including incrementing and
959 decrementing);
960 ´\' when a process has died at the core location;
962 ´-' when a process has executed at the core location;
964 ´|' when a process is waiting to execute at the core location.
966 If you click on a core location in the Core window while a battle is
968 being run, the contents will be displayed in the Text window.
969 Two warriors can be in memory at any one time. To assemble a warrior
971 choose "Choose Warrior n..." from the File menu. To remove the warrior
972 from memory choose "Remove Warrior n...". You can modify the settings
973 used by choosing "Preferences..." (this can only be done when no battle
974 is being run). Alternatively, you can type in a command line in the
975 same way as if you were typing from a unix prompt (if you're used to
976 that sort of thing) by choosing "Command Line...". The Edit menu is
977 just the normal Macintosh Edit menu and can be used to cut and paste
978 text in the Text window and dialogs. The items in the Play menu are
979 fairly self-explanatory: "Go" starts (or continues) a battle; "Step"
980 executes one instruction and enters the debugger; "Halt" halts the bat‐
981 tle and enters the debugger; "Abort" aborts the battle. The Window menu
982 is used to show and bring either of the two windows to the front of the
983 screen.
984 The cdb commands display, switch and close are not available in Macp‐
986 MARS.
987 Note: to use very large core sizes (up to about 65000) and process lim‐
989 its you may need to increase the memory partition for MacpMARS. To do
990 this, choose "Get Info" from the File menu in the Finder and set the
991 preferred memory size to about 1200K.
992
994 The following is mainly useful for people who write scripts or batch
995 files for pMARS. Upon normal exit, the program returns 0. Below is a
996 listing of what the abnormal exit codes mean. Your operating system may
997 not support negative exit codes; in this case you have to convert the
998 value to its unsigned counterpart.
999 -4 graphics error
1001 -3 trying to execute 80386 code on a lesser processor
1002 -2 memory allocation error
1003 -1 serious program logic error, contact developers
1004 1 file not found
1005 2 command line error
1006 3 assembly error
1007 4 user aborted program
1008 The exit codes of the VMS version conform to the VMS standard. The -Q
1009 (Query) command line option (see OPTIONS) allows you to customize the
1010 pMARS exit code. E.g. "pmars -Q 1000" returns the current pMARS ver‐
1011 sion. Below the -Q arguments and what the resulting exit codes mean.
1012 1..W exit code is score of this warrior, 1: first in result output,
1014 2: second, a.s.o.. If the -o option is also given, "1" gives the
1015 score of the highest scoring warrior, etc..
1016 101..1W
1018 returns the number of this warrior in the result output. Usually
1019 -Q 101 returns 1, -Q 102 returns 2 etc., so this is not very
1020 useful. If you also specify the "-o" (order results) option, -Q
1021 101 returns the position of the highest scoring warrior on the
1022 command line, -Q 110 the position of the 10th highest scoring
1023 warrior, etc..
1024 1000 exit code is the pMARS version in the same format as the prede‐
1026 fined VERSION variable.
1027 1001 returns the pMARS "variant": 0 if the program was compiled with
1029 the SERVER option (no debugger), 1 with debugger but without
1030 display, 2 with debugger and core display.
1031 1002 returns a combination of version and variant: 10*variant+ver‐
1033 sion.
1034 1003 the exit code is the core address size in bytes. On a 32-bit
1036 CPU, this is sizeof(int), usually 4. With SMALLMEM compilation,
1037 core address size is sizeof(unsigned short), usually 2.
1038 2000 returns how many warriors share one or more P-spaces. A value of
1040 4, e.g. means that either four warriors share one P-space, or
1041 that two pairs of warriors share two P-spaces.
1042PMARS v0.9.2 December 25, 2000 PMARS(6)