Y6502 Copyright Peter Coghlan 1991-2011. See license.txt for details.

This is a 6502 microprocessor simulator which implements a subset of the
functions of a BBC Microcomputer on the VAX/VMS platform.

This software builds without errors or warnings on VAX/VMS 5.5-2 with
DEC Fortran V6.3-141. It should also run on later versions of VAX/VMS
without any great difficulty.

Y6502_EXECUTE.MAR does not work correctly if compiled on an Alpha using the
VAX Macro compiler for Alpha (or presumably an Itanium - I haven't tried).
The code uses the VAX MOVPSL instruction to extract the VAX N and Z flags and
uses them to simulate the 6502 N and Z flags. The VAX Macro compiler for Alpha
does not implement this instruction the same way it works on a VAX. However,
it is possible to generate an executable on a VAX platform and use Decmigrate
(VEST) to translate it to an Alpha image which will successfully run on an
Alpha.

A copy of a language rom (generally BASIC I or BASIC II for the BBC Micro)
needs to be loaded into the simulator to get most use from it. This is not
included here. It is possible to extract the ROM contents from a real
BBC Micro.

Before certain files can be loaded into the simulator, a little fiddling is
required. BBC Micro files have attributes that do not exist for ordinary
VMS files. These consist of a load address (where the file is loaded by
default in 6502 memory) and an execution address (the address the 6502 starts
execution at after a file is loaded for running). The BBC Micro also keeps
track of the length of files as an exact number of bytes while VMS can be
a bit vague about this, depending on the type of file. VMS allows the
storage of extra file metadata using Application Access Control Lists. In
order to successfully load a language rom image into the simulator, an
application ACL must be set on the file so that the simulator knows how
big it is, where to load it and where to start executing it. Usually
a rom image is 16KB in size and needs to be loaded and run at 8000 hex.
This can be specified for a file such as BASICII.BBC with a DCL command
such as:

$ SET FILE /ACL=(APPLICATION,SIZE=20,DATA=%X00004000,%X00008000,%X00008000) -
  BASICII.BBC

The three numbers after DATA= are 32 bit values representing the file size,
load address and execution address. The ACL size (SIZE=) is always 20.
Use a DCL command such as:

$ DIR /ACL

to view ACLs on files.

To build the simulator, download or unzip the source files into a directory
and give the command @MAKE. If all goes well, a file called BBC.EXE will be
produced.

To run, give the command RUN BBC and you will be prompted for the name of a
file containing 6502 code to run in hex format (use BBCOS.HEX here). If there
are no problems, there should be a banner saying "BBC Computer" and a * prompt.
BBC Micro OS commands can be entered at this prompt but not much will be
possible until what BBC Micro folks refer to as a language is loaded.

At the * prompt, give the command RUN followed by the name of the file
containing a suitable language rom image such as BASICII.BBC above with a
suitable application ACL already applied. The > prompt should be displayed
if BBC BASIC is successfully loaded and BBC BASIC programs can be entered,
run, loaded and saved. Note that BBC BASIC loads and saves programs in
tokenised format.

Use control-C to simulate pressing the ESCAPE key on a real BBC Micro. (Don't
do this at the * prompt as there seems to be a bug (in BBCOS) that I never
noticed before now...)

Pressing control-D toggles a debug display which shows the address just
executed, the 6502 instruction just executed, a disassembly of the instruction,
the memory address of the instruction operand and the 6502 A, X, Y, SP
registers and flags - N V B D I Z and C. (This simulator treats the BRK flag
as a real flag - this is not strictly correct as the BRK flag is not maintained
by a real 6502. This could lead to problems if interrupts were supported but
they aren't so hopefully it won't.)

Control-Z exits normally from the simulator.

Unlike control-C which should work anytime, control-D and control-Z are only
effective when a keyboard read is in progress.

Control-Y can be used to interrupt the simulator if it is put into a state it
cannot otherwise recover from.