From 9e413b1df1e9d260940357f94f05d37aa6914d66 Mon Sep 17 00:00:00 2001 From: flowenol Date: Wed, 3 Mar 2021 02:09:08 +0100 Subject: [PATCH] Added customization instructions to README.md --- README.md | 19 +++++-- scripts/bas2bin.py | 2 +- src/rom_content.a65 | 121 +++++++++++++++++++++++++------------------- 3 files changed, 85 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 2195729..052bca9 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,12 @@ This repository contains firmware files for the "Apple-1 RAM/ROM Cartridge" expa This project aims to provide Apple-1 users with a quick way to expand RAM capacity in their systems up to 52 KB and to simultaneously store some 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 which span across non-continuous memory locations. -The A1C expansion card allows via the physical switch to completely disable the loader program functionality which takes up to the 2 KB of memory -and to provide continuous 44KB wide RAM address space. +The A1C expansion card allows via the physical switch to completely disable the ROM/loader program functionality which takes up to the 2 KB of memory (`$4000-$47FF`) +and to provide continuous 44KB wide RAM address space instead. ## Memory map -In ROM mode: +Physical switch in ROM mode: | address | function | | --- | --- | @@ -22,7 +22,7 @@ In ROM mode: | `$4800-$BFFF` | RAM region #2 when ROM banked out | | `$4800-$BFFF` | ROM with program contents when ROM banked in | -In RAM mode: +Physical Switch in RAM mode: | address | function | | --- | --- | @@ -54,6 +54,10 @@ And to clean the build: `make clean` +# How to customise? + +In order to customise your ROM contents you have to edit the `src/rom_content.a65` source file. You can find the entry table structure documentation in the source file. + ## PCB The KiCad project files with board design and schematics can be found here: @@ -66,3 +70,10 @@ The onboard ROM loader program can also automatically load your Applesoft BASIC applesoft-lite project which has been modified to make use of the A1SI expansion card: http://github.com/flowenol/applesoft-lite + +## How to install hardware? + +Just put the board in right orientation (as marked on the PCB) in the Apple-1 expansion slot. +Or you can use the port expander if the on board slot is already occupied: + +https://github.com/flowenol/Apple1ExpanderPcb diff --git a/scripts/bas2bin.py b/scripts/bas2bin.py index aaab8e8..50410ad 100644 --- a/scripts/bas2bin.py +++ b/scripts/bas2bin.py @@ -3,7 +3,7 @@ import binascii import sys """ -This utility transforms CFFA formated BASIC programs to binary, outputting +This utility transforms CFFA formatted Integer BASIC programs to binary, outputting to file name with LOMEM & HIMEM appended """ if __name__ == "__main__": diff --git a/src/rom_content.a65 b/src/rom_content.a65 index 70dc63c..cd7ff76 100644 --- a/src/rom_content.a65 +++ b/src/rom_content.a65 @@ -1,6 +1,8 @@ * = $4800 .dsb (*-loader_end), $FF +; start of loader entry table section + * = $4800 rom_content = $4800 @@ -18,15 +20,12 @@ number_of_entries .byt $08 ; ; jump address - word -; start of configuration section -/* - Integer BASIC - - How to store INTEGER BASIC programs via Apple-1 Serial Interface? - C100R - 004A.00FFW 0800.0FFFW - E2B3R - warm entry point -*/ +; Integer BASIC +; +; How to store INTEGER BASIC programs via ACI/Apple-1 Serial Interface? +; C100R +; 004A.00FFW 0800.0FFFW +; E2B3R - warm entry point basic basic_seg .byt $01 basic_len .word $1000 @@ -35,9 +34,9 @@ basic_cont_start .word basic_cont basic_str .byt $0D,"INTEGER BASIC" basic_jmp_addr .word $e000 -/* - Apple 30th anniversary demo program -*/ +; +; Apple 30th anniversary demo program +; apple30th apple30th_seg .byt $01 apple30th_len .word $0D80 @@ -46,24 +45,26 @@ apple30th_cont_start .word apple30th_cont apple30th_str .byt $13,"APPLE 30TH BIRTHDAY" apple30th_jmp_addr .word $0280 -/* - Mike Willegal's memory test program - - 00: - test address expected actual - - 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 -*/ +; +; Mike Willegal's memory test program +; +; 00: +; 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 +; memorytest memorytest_seg .byt $02 memorytest_1_len .word $0010 @@ -75,12 +76,12 @@ memorytest_2_cont_start .word memorytest_cont+16 memorytest_str .byt $10,"MEMORY TEST 280R" memorytest_jmp_addr .word $FF1F -/* - Disassembler program - - How to use: - 44: - disassembler start address -*/ +; +; Disassembler program +; +; How to use: +; 44: - disassembler start address +; disassembler disassembler_seg .byt $01 disassembler_1_len .word $0200 @@ -89,9 +90,12 @@ disassembler_1_cont_start .word disassembler_cont disassembler_str .byt $11,"DISASSEMBLER 800R" disassembler_jmp_addr .word $FF1F -/* - Applesoft BASIC port -*/ +; +; Applesoft BASIC +; +; A modified version from the following fork: +; https://github.com/flowenol/applesoft-lite +; applesoft applesoft_seg .byt $01 applesoft_len .word $2000 @@ -101,9 +105,16 @@ applesoft_str .byt $15,"APPLESOFT BASIC 6000R" applesoft_jmp_addr .word $6000 -/* - A sample Integer BASIC program with "Matrix" effect -*/ +; +; A sample Integer BASIC program - "Matrix" effect +; +; 3 segments need to be loaded: +; 1. Integer BASIC +; 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 +; matrix matrix_seg .byt $03 matrix_1_len .word $1000 @@ -118,10 +129,16 @@ matrix_3_cont_start .word matrix_cont+$B6 matrix_str .byt $0E,"MATRIX (BASIC)" matrix_jmp_addr .word $E2B3 - -/* - A sample Applesoft BASIC program - lemonade stand simulator -*/ +; +; A sample Applesoft BASIC program - lemonade stand simulator +; +; 3 segments need to be loaded: +; 1. Applesoft BASIC +; 2. lemonade stand program content +; 3. zero page variables for lemonade stand program +; +; Then jump to the STARTFROMCART routine +; lemo lemo_seg .byt $03 lemo_1_len .word $2000 @@ -134,12 +151,12 @@ lemo_3_len .word $000D lemo_3_addr .word $0067 lemo_3_cont_start .word lemo_fix_cont lemo_str .byt $16,"LEMONADE STAND (ASOFT)" -lemo_jmp_addr .word $7DFE +lemo_jmp_addr .word $7DF4 -/* - Another sample Applesoft BASIC program - counts to 10 in a loop -*/ +; +; Another sample Applesoft BASIC program - counts to 10 in a loop +; count10 count10_seg .byt $03 count10_1_len .word $2000 @@ -152,9 +169,9 @@ count10_3_len .word $000D count10_3_addr .word $0067 count10_3_cont_start .word count10_fix_cont count10_str .byt $13,"COUNT TO 10 (ASOFT)" -count10_jmp_addr .word $7DFE +count10_jmp_addr .word $7DF4 -; end of configuration section +; end of loader entry table section ; start of binary content section basic_cont .bin 0,0,"inc/basic.bin"