# run6502(1)

    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