VERSION

  pcode 0.1, released 2004-09-01

ABOUT

  pcode is a C program for executing pcode programs.

  It is derived from pcode2.c by Agnieszka Szczurowska, available at
  <URL:http://trethard.uta.edu./cse3302/CSE3302/pcode2.c>, which in turn is an
  implementation of the language described by Bruce J. MacLennan.

  pcode2.c may work perfectly well, but its source code is difficult to read
  and maintain.  As understanding how an interpreter works may be very useful
  knowledge in a programming languages course, I decided to create a less
  obtuse version of same, one students could read, understand, expand, and
  reuse in their own projects.  I admit my own source is not consistently easy
  to read, but it is a step in the right direction.

  Perhaps most interesting is pcode's debug mode, which allows for interactive
  execution of pcode programs.  The full state of the machine may be inspected
  at any point of the execution.  For larger projects, debug mode will be your
  best friend.  Plus the colorized mode is pretty snazzy.

  Another, lesser debugging benefit of pcode over pcode2.c is the tracking of
  unitialized program text.  If your program jumps past the end of your
  program, you will know immediately.

PREREQUISITES

- C compiler and Make utility    - For compilation, of course.
- Decent terminal emulator       - This is a text-only program at the moment.
- GNU Multiple Precision Library - Required for ten-digit integer mathematics.

  pcode also depends on the vec library contained in Paul Jarc's prjlibs, but
  since vec is bundled with pcode, you need not need to worry about this.

INSTALLATION

  First check your prerequisites.  Next edit the Makefile, following the
  instructions contained therein.  Run "make" to build the executable.
  Optionally copy it to a location in your $PATH.

SYNTAX

  pcode supports a syntax similar to that described in "Principles of
  Programming Languages", Third Edition, by Bruce J. MacLennan (ISBN 0-19-
  511306-3).  For the sake of readability, several enhancements are supported:

  - `.' in the input is converted to `0'.  Use this to mark ignored operands.
  - Everything following a `#' character is ignored.  This is for comments.
  - Spaces within numbers are ignored.  Use spaces for thousands' separators.
  - Extra space at line start is allowed.  I recomment indenting +9999999999's.
  - Blank lines and lines consisting solely of a comment are allowed.

  Of course, the strict style given in the book is also supported.

COMMAND LINE ARGUMENTS

  -iFILE   Read input data from FILE.
  -oFILE   Write output data to FILE.
  -d       Execute program interactively (debug mode).
  -c       Colorize debug display.
  -h       Print this message.
  -V       Display version and copyright information.

  If FILE is `-' or not specified, stdin or stdout is used.

SAMPLE USAGE

  Here pcode's debug mode is used to execute a program for calculating squares. 

  $ pcode -i test/squares.pc -d -c
  @000:+3 000 000 002  [  sqr   $000 .... $002  ]
  --> run
  @001:-8 002 000 000  [  print $002 .... ....  ]
  +0000000001
  @002:+7 000 001 000  [  loop  $000 $001 @000  ]
  @000:+3 000 000 002  [  sqr   $000 .... $002  ]
  @001:-8 002 000 000  [  print $002 .... ....  ]
  +0000000004
  [...]
  @002:+7 000 001 000  [  loop  $000 $001 @000  ]
  @003:+9 000 000 000  [  halt  .... .... ....  ]

DEBUG MODE

  All debug mode I/O is performed with stdin and stdout, so -i and -o options
  must be used rather than </> shell redirection.  Certainly -i must be used,
  since program execution does not begin until after loading is complete, and
  loading completes upon end-of-file.

  Debug mode offers the following commands:

  - quit               - Terminate the program.
  - help               - Display command summary.
  - run                - Disable single-step mode.
  - next               - Execute next instruction.
  - list [addr] [num]  - Display `num' instructions at text address `addr'
                         (defaults to next instruction).
  - break addr         - Pause execution at text address `addr'.
  - unbreak addr       - Cancel breakpoint at text address `addr'.
  - dump addr [num]    - Display `num' values at data address `addr'.
  - watch addr [num]   - Watch `num' values at data address `addr'.
  - unwatch addr [num] - Stop watching `num' values at data address `addr'.

  To execute a command, type its name followed by any arguments.  The `next'
  command can also be executed just by hitting enter.

  In debug mode, you are usually prompted after each instruction is executed,
  and the next instruction and all watched memory addresses are printed just
  above the prompt.  Use `watch' and `unwatch' to adjust the watch list.
  
  You can issue the `run' command to inhibit the prompt and allow the program
  to continue running without having to keep typing `next'.  `run' mode ceases
  whenever a breakpoint is hit.  Set and unset breakpoints using the `break'
  and `unbreak' commands, respectively.

  The `list' command pretty-prints the program text.  When called with no
  arguments, it prints the next instruction to be executed.

URLS

- http://ioioio.net./school/pcode/                  - Project web site.
- http://trethard.uta.edu./cse3302/CSE3302/pcode2.c - Original version.
- http://ioioio.net./misc/getline.c                 - My version of getline().
- http://multivac.cwru.edu./prjlibs/                - Source of vec library.
- http://www.swox.com./gmp/                         - GMP web site.
- http://ioioio.net./school/cse3322/                - Similar project to pcode.

TODO

- More testing and sample code.
- Comment describing the purpose of every function.
- Source cleanups and additional commenting.
- Ask Paul to add BSRCH to vec library, or do it myself.

WISHLIST

- GCC backend to produce pcode.  
  + This would require adding function pointer support to pcode.
- Graphical frontend.
- Profiling.

CHANGELOG

- 1 September 2004 - version 0.1
  + Initial release. 

COPYRIGHT

- Andy Goth <unununium@openverse.com.>

LICENSE

  This program is available under the GPL.  See LICENSE for full details.

  I must place pcode under the GPL because it incorporates Paul Jarc's vec
  library (part of prjlibs) and my getline.c (which derives from the GNU C
  Library), both of which are available only under the GPL.

vim: set ft=man tw=80 et:
