From 6cb4340be2da71cc870d4db33236e44af86cdc8b Mon Sep 17 00:00:00 2001 From: Bobbi Webber-Manners Date: Fri, 20 Aug 2021 22:31:30 -0400 Subject: [PATCH] Update README.md --- README.md | 154 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 92 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 19a2b52..e5ed35d 100644 --- a/README.md +++ b/README.md @@ -27,10 +27,8 @@ Run `BASIC.SYSTEM` and at the Applesoft BASIC prompt type: ``` BRUN APPLECORN ``` -to start the software. - -For convenience there is an Applesoft BASIC program called `START` which -can be used to launch Applecorn directly from Bitsy Bye. +to start the software. Alternatively, you can simply select `APPLECORN` +in the ProDOS 2.4.2 Bitsy Bye file browser. When first started, Applecorn will display a ROM selection menu. Choose the language ROM you wish to load by pressing the associated number key. @@ -46,6 +44,91 @@ input. You may want to keep Caps Lock enabled most of the time! 32 Kilobytes of space is available for your programs and variables. `PAGE` is set to `&0E0`. +## 'Applecorn MOS' Features + +### Compatible ROMs +- In principle any Acorn language ROM should work. +- Currently I have verified operation with: + - BBC BASIC + - Acornsoft COMAL + - Acornsoft FORTH + - Acornsoft Lisp + - Acornsoft MicroProlog + - Acornsoft BCPL +- I have not yet investigated two-ROM languages such as Logo or + ISO Pascal. It may be possible to support these also. + +### Compatible Apple II Systems + +The minimum requirement for Applecorn is an Apple II system with 128KB +of memory and a 65C02 processor. This includes the following: + +- Apple //e Enhanced (but not the original \]\[e, which has a 6502.) +- Apple //c and //c+ +- Apple IIgs + - You must enable the Alt Text Mode CDA! + - ROM1: Only `MODE 1` (40 cols) works + - ROM3: Both `MODE 0` and `MODE 1` work + +### Video Modes + +Two text video modes are currently supported: +- 80x24 `MODE 0` +- 40x24 `MODE 1` + +We plan to support HGR graphics eventually. + +### Escape Key + +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. + +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 + +`*QUIT` - Terminate Applecorn and quit to ProDOS. Because the 'BBC Micro' +lives in auxiliary memory, you can usually restart Applecorn by running it +again and recover your program with `OLD`. + +`*HELP` - Prints out information similar to the same command on the BBC micro. +Specifically it lists the version of Applecorn MOS and the name of the current +language ROM. + +`*CAT` (or `*.`) - Simple listing of the files in the current directory. + +`*DIR pathname` - Allows the current directory to be changed to any ProDOS +path. For example `*DIR /H1/APPLECORN`. + +`*LOAD filename SSSS` - Load file `filename` into memory at hex address +`SSSS`. If the address `SSSS` is omitted then the file is loaded to the +address stored in its aux filetype. + +`*SAVE filename SSSS EEEE` - Save memory from hex address `SSSS` to hex +address `EEEE` into file `filename`. The start address `SSSS` is +recorded in the aux filetype. + +`*RUN filename` - Load file `filename` into memory at the address stored +in its aux filetype and jump to to it. This is used for loading and +starting machine code programs. + ## How to Build Applecorn is built natively on the Apple //e using the Merlin 8 assembler @@ -56,10 +139,11 @@ In Merlin-8: - Press `D` for disk commands and enter the prefix of the build directory: `PFX /APPLECORN` - Press `L` to load a file and enter the filename `APPLECORN`. -- Press `E` to enter the editor and issue the following command a the `:` - prompt: `asm` -- Once assembly is complete, press `O` to save the object file and - enter the filename `APPLECORN`. +- Merlin will enter the editor automatically (or press `E`). Issue the + following command a the editor's `:` prompt: `asm` +- Once assembly is complete, enter the command `q` to quit the editor, + then select `O` to save the object file and enter the filename + `APPLECORN`. - Press `Q` to quit Merlin-8. ## Theory of Operation @@ -226,17 +310,6 @@ AUX BANK: 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 - - Acornsoft Lisp - - Acornsoft MicroProlog - - Acornsoft BCPL - ## Limitations Applecorn currently has the following limitations: @@ -262,48 +335,5 @@ Applecorn currently has the following limitations: - The Applecorn MOS command line is currently quite limited. More commands will be added in due course. -### 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. - -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 - -`*QUIT` - Terminate Applecorn and quit to ProDOS. Because the 'BBC Micro' -lives in auxiliary memory, you can usually restart Applecorn by running it -again and recover your program with `OLD`. - -`*HELP` - Prints out information similar to the same command on the BBC micro. -Specifically it lists the version of Applecorn MOS and the name of the current -language ROM. - -`*CAT` (or `*.`) - Simple listing of the files in the current directory. - -`*DIR pathname` - Allows the current directory to be changed to any ProDOS -path. For example `*DIR /H1/APPLECORN`. - -`*LOAD filename SSSS` - Load file `filename` into memory at hex address -`SSSS`. Be sure to specify the address otherwise it defaults to 0000! - -`*SAVE filename SSSS EEEE` - Save memory from hex address `SSSS` to hex -address `EEEE` into file `filename`.