From a63abe3a7fe8a89f522ca2924849cd81f72e63d5 Mon Sep 17 00:00:00 2001 From: flowenol Date: Sat, 13 Mar 2021 01:12:05 +0100 Subject: [PATCH] Loading routine bug fixed - one additional byte was erroneously loaded Krusader assembler entry added Applesoft BASIC programs loading HOWTO --- README.md | 25 ++++++--- src/cartridge.a65 | 3 +- src/rom_content.a65 | 130 ++++++++++++++++++++++++++++++++++++++------ 3 files changed, 132 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 2e055da..d3e724e 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,28 @@ # apple1cartridge -This repository contains firmware files for the "Apple-1 RAM/ROM Cartridge" expansion card for the Apple-1 computer. +This repository contains firmware and gerber files for the "Apple-1 RAM/ROM Cartridge" expansion card for the Apple-1 computer. ## Description This project aims to equip Apple-1 users with a quick way to expand RAM capacity in their systems up to 52 KB and to simultaneously store Apple-1 programs in ~30KB of on-board ROM, which can be banked in and out via software. The on-board ROM also contains a loader -program which is capable of loading programs spanning across noncontinuous memory locations. You can either use a default loader program `4000R`, which displays the list of all available program entries, or the fast loader program `4300R`, which loads the +program which is capable of loading programs spanning across noncontinuous memory locations. You can either use a default loader +program `4000R`, which displays the list of all available program entries, or the fast loader program `4300R`, which loads the specific program entry automatically. -The A1C expansion card allows to completely disable the ROM/loader functionality (via physical switch) which takes up to 2 KB of -memory (`$4000-$47FF`) and to provide continuous 44KB wide RAM address space instead (`$1000-$BFFF`). +The A1C expansion card allows to completely disable the ROM/loader functionality (which takes up to 2 KB of memory at `$4000-$47FF`) +via physical switch and to provide continuous 44KB wide RAM address space instead (`$1000-$BFFF`). This can be done while the +system is running, thus after a program is loaded, one can change the switch location disabling ROM banking functionality +and use the entire memory address space as RAM. + +Loader programs in ROM mode copy bytes sequentially from ROM to RAM locations described in the entries table, banking the ROM +in and out. Each entry may consist of several segments that can be loaded to non adjacent memory locations. For obvious reasons +the address space between `$4000-$47FF` cannot be utilised at loading time, because it would require the loader program +to overwrite itself in ROM. + +The A1C expansion card in RAM mode works great in conjunction with [Apple-1 Serial Interface](http://github.com/flowenol/apple11serial) +card or the original ACI, expanding the available address space to load programs. ## Memory map @@ -41,7 +52,7 @@ The contents of this repository are as following: * gerber/ - gerber files needed to manufacture the PCB * inc/ - contains Apple-1 programs in binary format, the package is downloadable [here](https://drive.google.com/file/d/1G0ycKSszlr45RE8Rp6eW-0qxz4MS9qDN/view?usp=sharing) * mapping/ - contains EQN and JED files for GAL22V10 based address decoder -* scripts/ - a bunch of useful python scripts which allow conversion from binary to Woz monitor format and vice versa +* scripts/ - a bunch of useful python scripts which do the conversion between binary and Woz monitor format and vice versa * src/ - contains the 6502 assembly sources for the on-board ROM loader programs ## Requirements @@ -75,8 +86,8 @@ http://github.com/flowenol/Apple1CartridgePcb ## Applesoft BASIC support -The onboard ROM loader program can also automatically load your Applesoft BASIC programs thanks to the branch of the -applesoft-lite project which has been modified to make use of the RAM/ROM expansion card: +The onboard ROM loader program can also automatically load your Applesoft BASIC programs thanks to the dedicated branch of the +applesoft-lite project which has been modified to be compatible with the Apple-1 RAM/ROM Cartridge card: http://github.com/flowenol/applesoft-lite diff --git a/src/cartridge.a65 b/src/cartridge.a65 index 0a27e9b..423455a 100644 --- a/src/cartridge.a65 +++ b/src/cartridge.a65 @@ -229,8 +229,9 @@ skip_entry jmp check_load init_copy - lda #$00 + lda #$01 sta copy_counter + lda #$00 sta copy_counter+1 copy ; load byte from rom diff --git a/src/rom_content.a65 b/src/rom_content.a65 index 9ae114c..e7aa23d 100644 --- a/src/rom_content.a65 +++ b/src/rom_content.a65 @@ -7,7 +7,7 @@ rom_content = $4800 ; define the number of available entries -number_of_entries .byt $08 +number_of_entries .byt $09 ; entry structure ; number of segments - byte @@ -23,8 +23,20 @@ number_of_entries .byt $08 ; Integer BASIC ; ; How to store INTEGER BASIC programs via ACI/Apple-1 Serial Interface? +; +; In Woz monitor: ; C100R +; * ; 004A.00FFW 0800.0FFFW +; +; The above will write the program contents with ZP variables to the ACI/ASI +; +; To read the program back: +; C100R +; * +; 004A.00FFR 0800.0FFFR +; +; And then run INTEGER BASIC ; E2B3R - warm entry point basic basic_seg .byt $01 @@ -52,18 +64,26 @@ apple30th_jmp_addr .word $0280 ; Output format: ; test_case address expected actual ; -; Test case numbers: -; 0 - All zeros - each byte of memory is verified that a 0x00 value can be written and read -; 1 - All ones - each byte of memory is verified that a 0xff value can be written and read -; 2 - Floating ones - eight passes, starting with 0x01 and moving the 1 bit to left each succeeding pass -; 0x02 0x04 0x08 0x10 0x20 0x40 0x80 -; 3 - Floating zeros - eight passes, starting with 0x7f and shifting the 0 bit to the right each succeeding pass -; 0xBF 0xDF 0xEF 0xF7 0xFB 0xFD 0xFE -; 4 - Address in Address 1 - one pass with low eight bits of the locations address is written to that location -; if this fails, you have a problem with one of the low eight address lines (this is pretty unlikely to fail, -; since you need these address lines in order to load and run this program) -; 5 - Address in Address 2 - one pass with high eight bits of the locations address written to that location -; if this fails, you have a problem with one of the eight high address lines +; Test case numbers with description: +; +; 0 - All zeros - each byte of memory is verified that a 0x00 value can be +; written and read +; 1 - All ones - each byte of memory is verified that a 0xff value can be +; written and read +; 2 - Floating ones - eight passes, starting with 0x01 and moving the 1 bit to +; left each succeeding pass: +; 0x02 0x04 0x08 0x10 0x20 0x40 0x80 +; 3 - Floating zeros - eight passes, starting with 0x7f and shifting the 0 bit +; to the right each succeeding pass: +; 0xBF 0xDF 0xEF 0xF7 0xFB 0xFD 0xFE +; 4 - Address in Address 1 - one pass with low eight bits of the locations +; address is written to that location. +; If this fails, you have a problem with one of the low eight address lines +; (this is pretty unlikely to fail, since you need these address lines in +; order to load and run this program) +; 5 - Address in Address 2 - one pass with high eight bits of the locations +; address is written to that location. +; If this fails, you have a problem with one of the eight high address lines ; memorytest memorytest_seg .byt $02 @@ -76,6 +96,39 @@ memorytest_2_cont_start .word memorytest_cont+16 memorytest_str .byt $10,"MEMORY TEST 280R" memorytest_jmp_addr .word $FF1F +; +; Krusader Assembler +; +; The version from the "Ultimate CFFA Software Collection" does not work on the +; Apple-1 - it doesn't register any input. It was probably meant for the +; Replica-1. The version included in the software collection from this project +; has been reassembled to target the Apple-1 computer and high RAM location +; ($7100). +; +; How to save & restore Krusader source using A1SI card? +; +; To save: +; +; 1. Type in your source code +; 2. Press ESC to switch to command mode and then execute M command to lookup +; memory occupied by the program source ( ) +; 3. Drop to A1SI monitor program by typing: R $C100 +; 4. Save the source via A1SI card using command: .W +; +; To load: +; +; 1. Load Krusader binary +; 2. Go to A1SI monitor: C100R +; 3. Load source via A1SI card: .R +; 4. Reenter Krusader via warm entry point ($711C) +krusader +krusader_seg .byt $01 +krusader_1_len .word $0DB9 +krusader_1_addr .word $7100 +krusader_1_cont_start .word krusader_cont +krusader_str .byt $12,"KRUSADER ASSEMBLER" +krusader_jmp_addr .word $7100 + ; ; Disassembler program ; @@ -109,11 +162,12 @@ applesoft_jmp_addr .word $6000 ; A sample Integer BASIC program - "Matrix" effect ; ; 3 segments need to be loaded: -; 1. Integer BASIC +; +; 1. Integer BASIC binary ; 2. zero page variables for "Matrix" program ; 3. program contents between LOMEM and HIMEM ; -; Then a jump to Integer BASIC warm entrpoint has to be made +; Then a jump to Integer BASIC warm entrypoint has to be made ; matrix matrix_seg .byt $03 @@ -129,11 +183,50 @@ matrix_3_cont_start .word matrix_cont+$B6 matrix_str .byt $0E,"MATRIX (BASIC)" matrix_jmp_addr .word $E2B3 +; How to make your Applesoft BASIC programs to be loadable from A1C expansion +; card ROM? +; +; First you have to save your program to a binary file - the best way to do it +; is to use Apple-1 Serial Card and "SAVE" routine from the modified fork of the +; Applesoft BASIC. Just hook the card up to your PC and record the data in any +; of the terminal emulation programs you prefer. +; +; With your BASIC program still loaded in memory, reset to Woz Monitor then +; display and take note of the following 14 ZP locations: +; +; 67.74 +; +; which correspond to the following Applesoft BASIC variables: +; +; TXTTAB = $0067 Start of program text +; VARTAB = $0069 Start of variable storage +; ARYTAB = $006B Start of array storage +; STREND = $006D End of array storage +; FRETOP = $006F Start of string storage +; FRESPC = $0071 Temp pntr, string routines +; MEMSIZ = $0073 End of string space (HIMEM) +; +; These bytes will be used to fix the ZP for the program and will have to be +; loaded as a separate segment. +; +; So to load an Applesoft BASIC program from ROM: +; +; 1. Applesoft BASIC binary must be loaded +; 2. Program content has to be loaded at LOMEM (typically $801) +; location +; 3. ZP fixing bytes specific for the program have to be loaded at location $67 +; 4. STARTFROMCART routine ($7DF4) has to be invoked +; +; The STARTFROMCART routine provides an additional entrypoint which doesn't +; corrupt the required ZP variables. +; + ; ; A sample Applesoft BASIC program - lemonade stand simulator ; ; 3 segments need to be loaded: -; 1. Applesoft BASIC +; +; 1. Applesoft BASIC binary ; 2. lemonade stand program content ; 3. zero page variables for lemonade stand program ; @@ -147,7 +240,7 @@ lemo_1_cont_start .word applesoft_cont lemo_2_len .word $1BF8 lemo_2_addr .word $0801 lemo_2_cont_start .word lemo_cont -lemo_3_len .word $000D +lemo_3_len .word $000E lemo_3_addr .word $0067 lemo_3_cont_start .word lemo_fix_cont lemo_str .byt $16,"LEMONADE STAND (ASOFT)" @@ -165,7 +258,7 @@ count10_1_cont_start .word applesoft_cont count10_2_len .word $0051 count10_2_addr .word $0801 count10_2_cont_start .word count10_cont -count10_3_len .word $000D +count10_3_len .word $000E count10_3_addr .word $0067 count10_3_cont_start .word count10_fix_cont count10_str .byt $13,"COUNT TO 10 (ASOFT)" @@ -178,6 +271,7 @@ count10_jmp_addr .word $7DF4 basic_cont .bin 0,0,"inc/basic.bin" apple30th_cont .bin 0,0,"inc/apple30th.bin" memorytest_cont .bin 0,0,"inc/a1mt.bin" +krusader_cont .bin 0,0,"inc/krusader.bin" disassembler_cont .bin 0,0,"inc/disassembler.bin" applesoft_cont .bin 0,0,"inc/applesoft-lite.bin" matrix_cont .bin 0,0,"inc/basic/matrix-0800-1000.bin"