RUN6502(1)

NAME
run6502 - execute a 6502 microprocessor program

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

DESCRIPTION
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 command line and then simulates a power-on hardware reset to begin execution.

In its first form, run6502 emulates an embedded 6502 processor with 64 kilobytes of RAM, no memory-mapped hardware, and no input-output capabilities. 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 emulation of Acorn 'BBC Model B' hardware with 32 kilobytes of RAM, 16 kilobytes of paged language ROMs, and 16 kilobytes of operating system ROM. A few MOS calls are intercepted to provide keyboard input and screen output via stdin and stdout. Switching between the sixteen paged read-only memory banks is also supported by the usual memory-mapped control register. Any file arguments after the -B are loaded into successive paged ROM banks (starting at 15 and working down towards 0) before execution begins.

  Options

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

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

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

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

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

    •   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 followed 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 address.

-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 instruction). 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 hexadecimal), skipping over any initial '#!' interpreter line.

-l addr file
    Load file into the memory image at the address addr (in hexadecimal).

-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 successive paged ROM slots. Other than the paging aspect, this is equivalent to:

    -l 8000 image

EXAMPLES

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

        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 effects:

-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 instruction...

-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:

        ./temp.img

  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.

  Exercises
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 file).

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

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

SEE ALSO
lib6502(3)

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.)

http://piumarta.com/software/lib6502 for updates and documentation.

http://6502.org for lots of 6502-related resources.

AUTHORS
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.

BUGS

•   Options must appear one at a time.

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

•   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.

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

•   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.

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

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