____________________

Basic6502 user guide
____________________


Use this patch program to downgrade your BASIC V module to understand 6502
assembler like it used to in the olden days. 'Yes, kids, it had 3 whole 8-bit
registers and could effortlessly add numbers between 0 and 255 !'.

Only really useful (and then literally) if you (still) develop sizable 6502
assembler programs, like I do (65Link, GoMMC, ReCo6502). Monolithic sources of
whatever size possible, no more splitting up and other complications due to the
target machine's tiny memory. All of BASIC V's facilities at your fingertips.
Life is good.

I still remember trying, with increasingly desperate effort, to squeeze the
growing source of Procyon (an 8 KB utility ROM for the Acorn BBC) into the
BBC's memory, back in the early 1980's. Eventually I managed, exploiting the
extra memory of my 6502 Second Processor, and sending the object code 'across
the Tube' (to host memory, after patching HiBASIC). Still hardly any memory
left in the end, despite several compression techniques (shortening variable
names, concatenating lines, etc.) and other trickery. Trying times ...

Basic6502 takes a BASIC V module. And spits out a patched version of it that
understands 6502 assembler. It's that simple.

Three sources:

1) Your local RISC OS ROM
2) A RISC OS ROM image in a file
3) A BASIC module image in a file

Supported versions of BASIC V: 1.05, 1.16, 1.19, 1.20 (2 variations thereof),
1.28, 1.29.

Simply run Basic6502 with your source on the ready. If option 1 doesn't work,
try it 'before !Boot' (since the BASIC you run may have been patched or
replaced beyond recognition by the !Boot sequence).

To use a patched BASIC V module, simply *RMRun it when needed. It has a
different name than the old module, so it can safely be run alongside it.

The instruction syntax mostly matches the one presented in the WDC datasheets.
Note the following features, exceptions and caveats:

- Any hex values are, of course, introduced with '&', not '$'.
- There are no '6502' directives, only the old 'ARM' ones, and they have their
  usual meaning (but OPT, of course, does not support ARM specific bits).
- 'Absolute long addressing' (65C816) is not automatic, it must be forced. See
  next remark.
- Put a '<', '>' or '^' before address operands (where appropriate) to force a
  1-, 2- or 3-byte interpretation, respectively. E.g. 'LDA &12' normally uses
  zero-page addressing, but 'LDA >&12' allows you to force the use of absolute
  addressing. Use of ^ is mandatory for 65C816 absolute long addressing.
- Use '%' instead of '#' to assemble 16-bit immediate values. This supports the
  16-bit modes of accumulator/memory and index registers of the 65C816.

Basic6502 supports the 6502, 65C02 and 65C816:
  Add 16 to OPT for a 65C02 instruction set
  Add 32 to OPT for a 65C816 instruction set

Assembler errors that can be generated:
  ERR 4, instruction not supported for OPT setting
  ERR 3, indexed instruction syntax error
  ERR 2, immediate value too big for instruction
  ERR 1, relative destination out of range

Updates of Basic6502 (if any appear) will be made available by (in order of
preference):

- World Wide Web : visit web.inter.nl.net/users/J.Kortink
- Electronic mail : email kortink@inter.nl.net

Enjoy !


John Kortink