Improved README
This commit is contained in:
Bobbi Webber-Manners
parent
4cb94bb3aa
commit
27ca33361f
120
README.md
120
README.md
|
|
@ -4,6 +4,9 @@ Applecorn is a ProDOS application for the Apple //e Enhanced which provides
|
|||
an environment for Acorn BBC Microcomputer language ROMs to run. This
|
||||
allows BBC BASIC and other Acorn languages to run on the Apple //e.
|
||||
|
||||
The language ROMs run as-is, without any modification required.
|
||||
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
Enhanced (65C02) Apple //e with 128KB of memory.
|
||||
|
|
@ -28,6 +31,11 @@ see the `>` prompt of BBC BASIC.
|
|||
32 Kilobytes of space is available for your programs and variables. `PAGE`
|
||||
is set to `&0E0`.
|
||||
|
||||
## How to Build
|
||||
|
||||
Applecorn is built natively on the Apple //e using the Merlin 8 assembler
|
||||
v2.58.
|
||||
|
||||
## Theory of Operation
|
||||
|
||||
### BBC Micro
|
||||
|
|
@ -61,7 +69,7 @@ On the BBC Micro, the 64K address space looks like this:
|
|||
+----------------------+ $0000
|
||||
```
|
||||
The hatched area at the bottom represents reserved space such as zero page,
|
||||
the stack and pages 2 through 7 which are used by the language ROM for
|
||||
the stack and pages two through seven which are used by the language ROM for
|
||||
various purposes.
|
||||
|
||||
Display memory on the BBC Micro is allocated at the top of user RAM, from
|
||||
|
|
@ -99,9 +107,10 @@ Here there is 48KB of RAM rather than 32KB, and the total ROM is just 12KB,
|
|||
starting at $d000. The 4KB from $c000 to $cfff is all memory mapped I/O.
|
||||
|
||||
An additional 16KB of memory is available, which is referred to as the
|
||||
Language Card. This memory can be banked into the space where the ROM usually
|
||||
resides from $d000 up. Note that this space is only 12KB so the 16KB LC
|
||||
memory is itself banked with the bottom 4KB of LC space having two banks.
|
||||
Language Card (LC henceforth.) This memory can be banked into the space
|
||||
where the ROM usually resides from $d000 up. Note that this address space
|
||||
is only 12KB so the 16KB LC memory is itself banked with the bottom 4KB of
|
||||
LC space having two banks.
|
||||
|
||||
When an Extended 80 Column card is installed in the aux slot of the Apple
|
||||
//e, an additional 64KB of RAM is added, for a total of 128KB. The entire
|
||||
|
|
@ -127,38 +136,121 @@ to $bff.
|
|||
|
||||
### Applecorn Architecture
|
||||
|
||||
```
|
||||
MAIN BANK:
|
||||
|
||||
+----------------------+ $ffff +----------------------+
|
||||
| BASIC/Monitor ROM | | Language Card |
|
||||
| | | ProDOS | +-4K Bank Two----+
|
||||
|###I/O Space (4KB)####| +----------------------+ +-Unused---------+
|
||||
+----------------------+ $c000
|
||||
| |
|
||||
| |
|
||||
| |
|
||||
| |
|
||||
| Applecorn loader & |
|
||||
| Applecorn code to |
|
||||
| interface with |
|
||||
| ProDOS |
|
||||
| |
|
||||
| |
|
||||
|//////////////////////|
|
||||
+----------------------+ $0000
|
||||
|
||||
AUX BANK:
|
||||
|
||||
+----------------------+ $ffff
|
||||
| Language Card |
|
||||
| Applecorn MOS | +-4K Bank Two----+
|
||||
|###I/O Space (4KB)####| +-Unused---------+
|
||||
+----------------------+ $c000
|
||||
| |
|
||||
| Acorn Language ROM |
|
||||
| |
|
||||
+----------------------+
|
||||
| |
|
||||
| Acorn language |
|
||||
| user code/data |
|
||||
| space |
|
||||
| |
|
||||
| |
|
||||
|//////////////////////|
|
||||
+----------------------+ $0000
|
||||
```
|
||||
|
||||
- Applecorn maintains a 'BBC Micro virtual machine' in the Apple //e auxiliary
|
||||
memory. In particular, the 'BBC Micro' has its own zero page and stack in
|
||||
auxiliary memory, so there is no contention with ProDOS or with Applecorn.
|
||||
- Applecorn primarily uses the main memory for servicing ProDOS file system
|
||||
requests for the 'BBC Micro virtual machine'.
|
||||
- An 80 column screen is configured using PAGE2 memory from $800 to $bfff
|
||||
in both main and aux memory. This conveniently just fits in above page 7,
|
||||
which is the highest page used as Acorn language ROM workspace.
|
||||
- The Acorn language ROM is loaded to $8000 in aux memory.
|
||||
- The Language Card memory is enabled and used to store the 'Applecorn MOS'
|
||||
from $d000 up in aux memory. (The main bank LC memory contains ProDOS.)
|
||||
- Applecorn copies its own 'Applecorn MOS' code to $d000 in aux memory and
|
||||
relocates the MOS entry vectors to high memory.
|
||||
- An 80 column screen is configured using PAGE2 memory from $800 to $bfff
|
||||
in both main and aux memory. This conveniently just fits in above page 7,
|
||||
which is the highest page used as Acorn language ROM workspace.
|
||||
- The only real difference between the Apple //e aux memory map and that of
|
||||
the BBC Micro is the Apple //e has a 'hole' from $c000 to $cfff where memory
|
||||
mapped I/O resides. Fortunately this does not really matter because the
|
||||
language only uses well-defined entry points to call into the MOS, so we
|
||||
can simply avoid this address range.
|
||||
|
||||
## Limitations
|
||||
|
||||
...
|
||||
- The memory map for the main and aux banks is illustrated in the diagram
|
||||
above. For the aux bank, the LC is always banked in since no Apple monitor
|
||||
or BASIC ROM routines are called, so this is omitted from the diagram.
|
||||
|
||||
## 'Applecorn MOS' Features
|
||||
|
||||
- In principle any Acorn language ROM should work.
|
||||
- Currently I have verified operation with:
|
||||
- BBC BASIC
|
||||
- Acornsoft COMAL
|
||||
- Acornsoft FORTH
|
||||
|
||||
## Limitations
|
||||
|
||||
Applecorn currently has the following limitations:
|
||||
|
||||
- A number of MOS calls relating to file I/O are not yet implemented including
|
||||
`OSFIND`, `OSGBPB`. `OSBPUT`, `OSBGET`, `OSARGS`. This means that file
|
||||
operations such as the BBC BASIC `OPENIN` and `OPENOUT` do not work in the
|
||||
Acorn languages. `OSFILE` is (partially) implemented however, so BASIC and
|
||||
COMAL can `LOAD` and `SAVE` programs.
|
||||
- The VDU driver is quite primitive at present. In particular it only
|
||||
supports 80 column text mode. There is currently no graphics support.
|
||||
- Only a few `OSBYTE` calls are implemented. More will be added in due
|
||||
course.
|
||||
- The only implemented `OSWORD` call is A=&00, to read a line of input from
|
||||
the console. More will be added as needs arise.
|
||||
- Special BBC Micro functions such as sound, A/D interfaces, programmable
|
||||
function keys and so on are currently not supported.
|
||||
- The Applecorn MOS command line is currently quite limited. More commands
|
||||
will be added in due course (for example `*FX`, `*LOAD`, `*SAVE` etc.).
|
||||
|
||||
### Escape
|
||||
|
||||
...
|
||||
The BBC Micro uses interrupts extensively and the Escape key is handled
|
||||
asynchronously. The language ROM code simply checks an 'escape flag' in
|
||||
zero page ($FF) from time to time to detect if Escape has been pressed.
|
||||
|
||||
### Reset
|
||||
The Apple //e does not use interrupts in its keyboard handling and the basic
|
||||
machine include no sources of interrupts at all (there is no system timer.)
|
||||
This prevents Escape from being handled in the same manner.
|
||||
|
||||
...
|
||||
As a partial workaround, Applecorn checks whether the Escape key is pressed
|
||||
from time to time when it has control, but there are cases where a program
|
||||
can run forever without ever making a MOS call. In these cases the only
|
||||
way to interrupt the program is to press Ctrl-Reset.
|
||||
|
||||
### Ctrl-Reset
|
||||
|
||||
The Ctrl-Reset key combination is the only asynchronously handled keyboard
|
||||
event on the Apple //e. Applecorn sets up a reset handler which will restart
|
||||
the ROM after Ctrl-Reset. Any user program in aux memory will be untouched.
|
||||
|
||||
For ROMs such as BASIC or COMAL, the `OLD` command can be used to recover the
|
||||
program in memory.
|
||||
|
||||
### Star Commands
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue