RUN6502(1)                BSD General Commands Manual               RUN6502(1)

     run6502 - execute a 6502 microprocessor program

     run6502 [option ...]
     run6502 [option ...] -B [file ...]

     The run6502 command emulates the execution of a 6502 microprocessor.  It
     creates a memory image from the contents of one or more files on the com-
     mand line and then simulates a power-on hardware reset to begin execu-

     In its first form, run6502 emulates an embedded 6502 processor with 64
     kilobytes of RAM, no memory-mapped hardware, and no input-output capabil-
     ities.  Limited interaction with the machine is possible only through the
     -G, -M and -P options.

     In its second form (with the -B option) run6502 provides minimal emula-
     tion of Acorn 'BBC Model B' hardware with 32 kilobytes of RAM, 16 kilo-
     bytes of paged language ROMs, and 16 kilobytes of operating system ROM.
     A few MOS calls are intercepted to provide keyboard input and screen out-
     put via stdin and stdout.  Switching between the sixteen paged read-only
     memory banks is also supported by the usual memory-mapped control regis-
     ter.  Any file arguments after the -B are loaded into successive paged
     ROM banks (starting at 15 and working down towards 0) before execution

     -B      enable minimal Acorn 'BBC Model B' hardware emulation:

             o   the contents of memory between addresses 0x8000 and 0xBFFF
                 are copied into paged ROM number 0;

             o   memory between 0x8000 and 0xBFFF becomes bank-switchable
                 between sixteen different ROM images;

             o   the memory-mapped pages ('FRED', 'JIM' and 'SHEILA') between
                 0xFC00 and 0xFEFF are initialised to harmless values;

             o   the upper half of the address space is write-protected; and

             o   callbacks are installed on several OS entry points to provide
                 input-output via stdin and stdout.

             Any remaining non-option arguments on the command line will name
             files to be loaded successively into paged ROMs, starting at 15
             and working downwards towards 0.

     -d addr end
             dump memory from the address addr (given in hexadecimal) up to
             (but not including) end.  The end argument is either an absolute
             address or a relative address specified as a '+' character fol-
             lowed by the number (in hexadecimal) of bytes to dump.  In other
             words, the following two options dump the same region of memory:

                   -d 8000  C000
                   -d 8000 +4000

             The format of the dump cannot currently be modified and consists
             of the current address followed by one, two or three hexadecimal
             bytes, and a symbolic representation of the instruction at that

     -G addr
             arrange that subroutine calls to addr will behave as if there
             were an implementation of getchar(3) at that address, reading a
             character from stdin and returning it in the accumulator.

     -h      print a summary of the available options and then exit.

     -I addr
             set the IRQ (interrupt request) vector (the address to which the
             processor will transfer control upon execution of a BRK instruc-
             tion).  Setting this address to zero will cause execution to halt
             (and the emulator to exit) when a BRK instruction is encountered.

     -i addr file
             Load file into the memory image at the address addr (in hexadeci-
             mal), skipping over any initial '#!' interpreter line.

     -l addr file
             Load file into the memory image at the address addr (in hexadeci-

     -M addrio
             arrange that memory reads from address addrio will return the
             next character on stdin (blocking if necessary), and memory
             writes to addrio will send the value written to stdout.

     -N addr
             set the NMI (non-maskable interrupt) vector to addr.

     -P addr
             arrange that subroutine calls to addr will behave as if there
             were an implementation of putchar(3) at that address, writing the
             contents of the accumulator to stdout.

     -R addr
             set the RST (hardware reset) vector.  The processor will transfer
             control to this address when emulated execution begins.

     -s addr end file
             save the contents of memory from the address addr up to end
             (exclusive) to the given file.  As with the -d option, end can be
             absolute or '+' followed by a byte count.

     -v      print version information and then exit.

     -X addr
             arrange that any transfer of control to the address addr will
             cause an immediate exit with zero exit status.

     -x      exit immediately.  (Useful after -d or when run6502 is being used
             as a trivial 'image editor', with several -l options followed by
             -s and -x.)

     file ...
             following a -B option, load one or more ROM image files into suc-
             cessive paged ROM slots.  Other than the paging aspect, this is
             equivalent to:

                   -l 8000 image

   A Very Simple Program
     The perl(1) command can be used to create a binary file from hexadecimal

         echo a2418a20eeffe8e05bd0f7a90a20eeff00 |
         perl -e 'print pack "H*",<STDIN>' > temp.img

     The file can be loaded and executed with:

         run6502 -l 1000 temp.img -R 1000 -P FFEE -X 0

     The contents of the file can be inspected symbolically with:

         run6502 -l 1000 temp.img -d 1000 +12

     The options passed to run6502 in the above examples have the following

     -l 1000 temp.img
             loads the file temp.img into memory at address 0x8000.

     -R 1000
             sets the reset vector (the address of first instruction to be
             executed after 'power on') to 0x1000.

     -P FFEE
             arranges for calls to address 0xFFEE to behave as if there were
             an implementation of putchar(3) at that address.

     -X 0    arranges for transfers of control to address 0 to exit from the
             emulator.  This works in the above example because the final
             'BRK' instruction causes an implicit subroutine call through an
             uninitialised interrupt vector to location 0.  To see this

     -d 1000 +12
             disassembles 18 bytes of memory at address 0x8000.

   Standalone Images
     The -i option is designed for use in the 'interpreter command' appearing
     on the first line of an executable script.  Adding the line

         #!run6502 -R 1000 -P FFEE -X 0 -i 1000

     (with no leading spaces and a single trailing newline character) to the
     temp.img file from the first example turns it into a script.  If the file
     is made executable with

         chmod +x temp.img

     it can be run like a standalone program:


   A Very Complex Program
     Consider a pair of files named os1.2 and basic2 containing (legally-
     acquired, of course) ROM images of Acorn MOS 1.2 and BBC Basic 2.  The
     following command loads each of the images into memory at the appropriate
     address, cleans up the regions of memory containing memory-mapped i/o on
     the BBC computer, saves a snapshot of the entire memory to the file image
     and then exits:

         run6502 -l C000 os1.2 -l 8000 basic2 -B -s0 +10000 image -x

     Running the generated image with

         run6502 image

     will cold-start the emulated hardware, run the OS for a while, and then
     drop into the language ROM.  Basic programs can then be entered, edited
     and run from the terminal.

     More details are given in the README file available in the examples
     directory of the distribution.

     Create a standalone image (one that can be run as a program, with a '#!'
     interpreter line at the beginning) that contains Basic2 and OS1.2 (as
     described above).  This image should be no larger than 32K (memory below
     0x8000, which would be full of zeroes, should not appear in the image

     If nothing goes wrong, none.  Otherwise lots.  They should be self-
     explanatory.  I'm too lazy to enumerate them.

     See lib6502(3) for a discussion of the emulated instruction set.


     The file examples/README in the lib6502 distribution.  (Depending on your
     system this may be installed in /usr/doc/lib6502, /usr/local/doc/lib6502,
     /usr/share/doc/lib6502, or similar.) for updates and documentation. for lots of 6502-related resources.

     The software and manual pages were written by Ian Piumarta.

     The software is provided as-is, with absolutely no warranty, in the hope
     that you will enjoy and benefit from it.  You may use (entirely at your
     own risk) and redistribute it under the terms of a very liberal license
     that does not seek to restrict your rights in any way (unlike certain so-
     called 'open source' licenses that significantly limit your freedom in
     the name of 'free' software that is, ultimately, anything but free).  See
     the file COPYING for details.

     o   Options must appear one at a time.

     o   Any attempt (in a load or save operation) to transfer data beyond
         0xFFFF is silently truncated at the end of memory.

     o   There is no way to specify the slot into which a ROM image should be
         loaded, other than implicitly according to the order of arguments on
         the command line.

     o   Execution can only be started via the emulated power-up reset.  There
         is no support for 'warm-starting' execution in an image at an arbi-
         trary address.

     o   Even though the emulator fully supports them, there is no way to
         artificially generate a hardware interrupt request, non-maskable
         interrupt, or reset condition.  If you need these, read lib6502(3)
         and write your own shell.

     o   The Acorn 'BBC Model B' hardware emulation is totally lame.

     Please send bug reports (and feature requests) to the author at: first-
     Name (at) lastName (dot) com.  (See AUTHORS above for suitable values of
     firstName and lastName.)

BSD                            October 31, 2005                            BSD