From 0b2ce47d27b2e95118adce43dcf79f26ff2c87e8 Mon Sep 17 00:00:00 2001
From: flowenol <flovenol@gmail.com>
Date: Mon, 1 Mar 2021 18:58:24 +0100
Subject: [PATCH] Add README.md

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cab3da5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# apple1cartridge
+
+This repository contains firmware files for the "Apple-1 RAM/ROM Cartridge" expansion card for the Apple-1 computer.
+
+## Description
+
+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,
+
+## Memory map
+
+In ROM mode:
+
+| address | function |
+| --- | --- |
+| `$1000-$3FFF` | RAM region #1 |
+| `$4000` | the start address of the on-board loader program |
+| `$47F8-$47FF` | write to these memory locations causes ROM to be banked in or out depending on the least significant bit of the address, A0=0 - ROM banked out, A0=1 - ROM banked in  |
+| `$4800-$BFFF` | RAM region #2 when ROM banked out |
+| `$4800-$BFFF` | ROM with program contents when ROM banked in |
+
+In RAM mode:
+
+| address | function |
+| --- | --- |
+| `$1000-$BFFF` | RAM region |
+
+## Contents
+
+The contents of this repository are as following:
+
+* inc/ - contains Apple-1 programs in binary format, the package is downloadable here
+* 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
+* src/ - contains the 6502 assembly sources for the Apple-1 RAM/ROM Cartridge onboard ROM loader program
+
+## Requirements
+
+You need the following to successfully build the firmware:
+
+* [xa](https://www.floodgap.com/retrotech/xa/) cross assembler
+* Some software capable of translating the EQN files into JED's. I used for this purpose the DOS based EQN2JED from OPALjr PLD Development Package. This is only required if you wish to make some changes to the GAL based address decoder. The default JED file should be fine for most users.
+
+## How to build?
+
+To build the firmware just type:
+
+`make`
+
+And to clean the build:
+
+`make clean`
+
+## PCB
+
+The KiCad project files with board design and schematics can be found here:
+
+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 A1SI expansion card:
+
+http://github.com/flowenol/applesoft-lite