RUN6502(1) BSD General Commands Manual 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 com-
mand line and then simulates a power-on hardware reset to begin execu-
tion.
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
begins.
Options
-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
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 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-
mal).
-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
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
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