|
| 1 | +# A2FPGA Multicard Core |
| 2 | + |
| 3 | +Multicard core for A2FPGA Apple II FPGA co-processor cards. |
| 4 | + |
| 5 | +The A2FPGA consists of an Apple II peripheral card PCB that can be installed in any Apple II |
| 6 | +slot (slot-7 recommended) that interfaces a modern FPGA to the Apple II bus. The |
| 7 | +FPGA interfaces with the Apple II bus to capture all accesses to display memory |
| 8 | +in order to drive a 480p HDMI display as well a providing the functionality of |
| 9 | +a number of popular peripheral cards in a single Apple II slot. The A2FPGA |
| 10 | +has been tested with Apple II, II+, //e, and IIgs models. |
| 11 | + |
| 12 | +Basic functionality provided: |
| 13 | + |
| 14 | +- 720x480 HDMI output supporting all Apple II, //e, & IIgs display modes |
| 15 | + |
| 16 | +- Mockingboard sound compatibility |
| 17 | + |
| 18 | +- Synetix SuperSprite and Ciarcia EZ-Color TMS9918a compatibility |
| 19 | + |
| 20 | +- Super Serial Card compatibility communications over USB for ADTPro |
| 21 | + |
| 22 | +There are several models of A2FPGA cards that are designed to use different types |
| 23 | +of FPGAs from different manufacturers such as Gowin or Xilinx. For ease of design |
| 24 | +and manufacturing as well as cost and availability, these have primarily focused |
| 25 | +on using inexpensive FPGA modules such as the Tang Nano 20K that are readily |
| 26 | +available from AliExpress or Amazon in quantity and often at prices less than |
| 27 | +the FPGA chip alone would cost from a distributor. These modules have the added |
| 28 | +benefit of providing easy USB-based programming. |
| 29 | + |
| 30 | +For enthusiasts looking for an assembled, programmed, and tested A2FPGA board |
| 31 | +that is pre-populated with a Tang Nano 20K FPGA module, we have partnered with |
| 32 | +[ReActiveMicro](https://www.reactivemicro.com/) to make the A2N20 card available |
| 33 | +for easy purchase. |
| 34 | + |
| 35 | +Schematics and Gerbers are available for some of the A2FPGA board models in |
| 36 | +other repos in the A2FPGA org and some boards may be available from time to time |
| 37 | +on Tindie and eBay. |
| 38 | + |
| 39 | +## Getting Started |
| 40 | + |
| 41 | +You will need the following: |
| 42 | + |
| 43 | +- A2FPGA Apple II Fpga Co-Processor Card, A2N20 versions 2 recommended. |
| 44 | + - The A2N20 card uses the [SiPeed Tang Nano 20K FPGA Developer Board](https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html) |
| 45 | + |
| 46 | +- To update the bitstream on the A2FPGA, the most convenient way is to use [OpenFPGALoader](https://github.com/trabucayre/openFPGALoader) |
| 47 | + - Mac users with [Homebrew](https://brew.sh/) can just type `brew install openfpgaloader` in the Terminal to install it |
| 48 | + - Use OpenFPGALoader to program the correct bitstream for your board. For example, for the A2N20v2, use [a2n20v2.fs](boards/a2n20v2/impl/pnr/a2n20v2.fs) and run `openfpgaloader -b tangnano20k -f a2n20v2.fs` |
| 49 | + |
| 50 | +- For rebuilding the project, or developing with the A2FPGA, you will need the Gowin V1.9.9Beta-4 Education Edition IDE (or later) |
| 51 | + - [Windows](https://cdn.gowinsemi.com.cn/Gowin_V1.9.9Beta-4_Education_win.zip) |
| 52 | + - [Linux](https://cdn.gowinsemi.com.cn/Gowin_V1.9.9Beta-4_Education.tar.gz) |
| 53 | + |
| 54 | +Install the A2FPGA card into any slot in your Apple II or //e. Please note that |
| 55 | +the default configuration assumes that slots 1, 3, and 7 are empty as it uses |
| 56 | +the memory addresses for these to support Super Serial, Mockingboard, and |
| 57 | +SuperSprite software. If you already have cards in those slots and plan to |
| 58 | +continue using them, you'll need to build a version of the Multicard core with |
| 59 | +those cards disabled in top.v. |
| 60 | + |
| 61 | +### Using the A2N20 Version 2 |
| 62 | +(Current version, recommended for most users) |
| 63 | + |
| 64 | +- Compatible with the II, II+, //e, and IIgs |
| 65 | +- Supports 40/80 column text, lo-res, hi-res, and super-hires graphics |
| 66 | +- For use with a IIgs, set DIP switch 4 to on. For all other models, DIP switch 4 must be off. |
| 67 | +- Provides video and sound output as well as providing Supersprite compatibility |
| 68 | +- Uses the larger [Tang Nano 20K](https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html) |
| 69 | +- Delays Apple startup until power-up initialization of FPGA is complete (optional) |
| 70 | +- Compatible with most HDMI television sets and monitors |
| 71 | +- Not compatible with HDMI-to-DVI converters |
| 72 | +- Recommended for all users/models |
| 73 | +- General Availability - contact [ReActiveMicro](https://www.reactivemicro.com/) to order |
| 74 | + |
| 75 | +The A2N20v2 has a 4-switch DIP switch that controls the following settings: |
| 76 | + |
| 77 | +1. Enable Scanline effect when set to on |
| 78 | +2. Enable Apple II speaker sounds via HDMI when set to on |
| 79 | +3. Power-on-Reset Hold - Delay Apple II start-up until FPGA is initialized and running |
| 80 | +4. Apple IIgs - Set to on when installed in an Apple IIgs |
| 81 | + |
| 82 | +For ROM 00/01 IIgs models (such as the Woz edition), the A2N20v2 must be placed in Slot 3. For ROM 03 models, it should work in any slot. This is because it requires the M2B0 signal which is only present in Slot 3 of the original IIgs models, but which is present in slots 1 to size of the ROM 03 model. |
| 83 | + |
| 84 | +[A2N20v2 Board Support Project (Schematics, Project Files)](boards/a2n20v2/) |
| 85 | + |
| 86 | +[A2N20v2 Board Support Project (Experimental SDRAM Feature Set)](boards/a2n20v2-SDRAM/) |
| 87 | + |
| 88 | +### Using the A2N9 |
| 89 | + |
| 90 | +- Compatible with the II, II+, and //e |
| 91 | +- Supports 40/80 column text, lo-res, and hi-res graphics |
| 92 | +- Not bus-compatible with the IIgs |
| 93 | +- Provides HDMI video output and Mockingboard sound |
| 94 | +- No SuperSprite support |
| 95 | +- Uses the smaller and cheaper [Tang Nano 9K](https://wiki.sipeed.com/hardware/en/tang/Tang-Nano-9K/Nano-9K.html) |
| 96 | +- Starts instantly on Apple power-up |
| 97 | +- Not compatible with many HDMI televisions although it works fine with most monitors |
| 98 | +- Not compatible with HDMI-to-DVI converters |
| 99 | +- Recommended for hobbyist use and experimentation |
| 100 | +- Open Source Hardware Design, boards available periodically via Tindie and eBay |
| 101 | + |
| 102 | +[A2N9 Board Board Support Project (Schematics, Project Files)](boards/a2n9/) |
| 103 | + |
| 104 | +### Using the A2N20 Version 1 |
| 105 | + |
| 106 | +- Compatible with the II, II+, and //e |
| 107 | +- Supports 40/80 column text, lo-res, hi-res, and super-hires graphics |
| 108 | +- Not bus-compatible with the IIgs |
| 109 | +- Provides video and sound output as well as providing Supersprite compatibility |
| 110 | +- Uses the larger [Tang Nano 20K](https://wiki.sipeed.com/hardware/en/tang/tang-nano-20k/nano-20k.html) |
| 111 | +- Delays Apple startup until power-up initialization of FPGA is complete |
| 112 | +- Compatible with most HDMI television sets and monitors |
| 113 | +- Not compatible with HDMI-to-DVI converters |
| 114 | +- Recommended for all users/models (except IIgs) |
| 115 | +- Limited Production, replaced by V2 |
| 116 | + |
| 117 | +[A2N20v1 Board Support Project (Schematics, Project Files)](boards/a2n20v1/) |
| 118 | + |
| 119 | +## HDMI Apple II Graphics |
| 120 | + |
| 121 | +The Multicard core provides an 720x480 HDMI output of the Apple II, //e, and IIgs |
| 122 | +display. It supports 40 and 80 column text as well as lo-res, hi-res, double-hires, and |
| 123 | +super-hires graphics modes (IIgs modes currently only available on A2N20v2 cards). |
| 124 | + |
| 125 | +The Multicard code has a custom graphics pipeline that attempts to provide |
| 126 | +accurate Apple II artifacts, leveraging insights from many of the other |
| 127 | +Apple II FPGA cores as well as MAME and AppleWin, but in an entirely new |
| 128 | +codebase. Even 40 years later, getting Apple II artifacts right remains |
| 129 | +a challenge, but we've been able to achieve very good results comparable |
| 130 | +to other implementations. |
| 131 | + |
| 132 | +The A2FPGA uses the 720x480 HDMI resolution, centering the Apple II 280/560 |
| 133 | +horizontal resolution and doubling the 192 vertical lines. The goal of the |
| 134 | +display implementation is to not do any blurring or pixel interpolation |
| 135 | +of the display output, so the result is that the display is slightly |
| 136 | +stretched horizontally on a modern widescreen HDMI display. For the IIgs |
| 137 | +320/640 by 240 super hires modes, the display is once again centered |
| 138 | +and vertically line-doubled within the 720x480 HDMI display area. |
| 139 | + |
| 140 | +By default, a scanline effect is provided that dims alternating lines |
| 141 | +to create a CRT-like display appearance. This can be enabled or disabled on the |
| 142 | +A2N20 card using DIP switch 1. |
| 143 | + |
| 144 | +## SuperSprite |
| 145 | + |
| 146 | +The [SuperSprite](https://archive.org/details/CreativeComputing.2-1984_A_New_Way_To_Do_Graphics_On_The_Apple) |
| 147 | +was introduced in 1984 by Synetix and is one of the more rare Apple II cards. |
| 148 | +The SuperSprite used the TMS9918a Video Display Processor, which was originally |
| 149 | +created for the TI 99/4A home computer and was also used within a number of |
| 150 | +other computers and video games, ranging from MSX computers to the ColecoVision. |
| 151 | +Synetix used the video overlay capabilities of the TMS9918a to let sprite |
| 152 | +graphics sit over the Apple II display. The basics of using a TMS9918a in the |
| 153 | +Apple II had been demonstrated by Steve Ciarcia in a Byte magazine article he |
| 154 | +published in August of 1982 titled ["High-Resolution Sprite-Oriented Color |
| 155 | +Graphics"](https://archive.org/details/byte-magazine-1982-08/page/n57/mode/2up). |
| 156 | +The SuperSprite used the same memory-mappings as the Ciarcia design while adding |
| 157 | +an AY-3-8910 sound chip as well as a TMS5220 voice processor. |
| 158 | + |
| 159 | +The Multicard core uses the [F18a TMS9918a](https://github.com/dnotq/f18a) core to |
| 160 | +provide sprite graphics which are overlayed on top of the Apple II display. It is |
| 161 | +designed to be compatible with the Synetix SuperSprite as well as Steve |
| 162 | +Ciarcia's EZ-Color card. SuperSprite compatibility includes AY-3-8910 sound |
| 163 | +although TMS5220 voice support is not currently implemented. |
| 164 | + |
| 165 | +By default, the Multicard core emulates a SuperSprite card in slot 7 although the A2FPGA |
| 166 | +card can physically be in any slot. The slot configuration can be changed |
| 167 | +in the top.v file. |
| 168 | + |
| 169 | +## Mockingboard |
| 170 | + |
| 171 | +The [Mockingboard](https://en.wikipedia.org/wiki/Mockingboard) was the most |
| 172 | +popular sound card for the Apple II. It uses a pair of |
| 173 | +[AY-3-8910](https://en.wikipedia.org/wiki/General_Instrument_AY-3-8910) sound |
| 174 | +chips controled by two [6522 |
| 175 | +VIA](https://en.wikipedia.org/wiki/MOS_Technology_6522) interface chips to |
| 176 | +enable a wide variety of sound effects and musical playback. |
| 177 | + |
| 178 | +The Multicard core implements support for the Sweet Micro Systems Mockingboard, |
| 179 | +providing stereo output over HDMI. Voice support is not currently provided as |
| 180 | +there is no FPGA core yet available for the [Votrax |
| 181 | +SC-01](https://en.wikipedia.org/wiki/Votrax) used on the Mockingboard. |
| 182 | + |
| 183 | +By default, the Multicard emulates a Mockingboard in slot 4 although the A2FPGA |
| 184 | +card can physically be in any slot. Slot position is configurable in the |
| 185 | +top.v file. |
| 186 | + |
| 187 | +## Apple II and IIgs Sound |
| 188 | + |
| 189 | +Apple speaker sounds are generated by the core and played over the HDMI |
| 190 | +audio. If used with the Mockingboard or Supersprite sound generation, the results are |
| 191 | +mixed together. |
| 192 | + |
| 193 | +Apple II sound can be enabled or disabled on the A2N20 card using DIP switch 1. |
| 194 | + |
| 195 | +Apple IIgs sound is currently experimentally provided through an implementation |
| 196 | +of the IIgs GLU chip and the Ensoniq 5503 DOC chip. However, this is still in |
| 197 | +the experimental stage and disabled in the default builds. |
| 198 | + |
| 199 | +## Super Serial Card |
| 200 | + |
| 201 | +The Multicard implements Super Serial Card-compatible serial communications over |
| 202 | +USB to a host computer. This is compatible with [ADTPro](https://adtpro.com/) |
| 203 | +and can bootstrap from it. |
| 204 | + |
| 205 | +By default, the Multicard emulates a Super Serial Card in slot 2 although the A2FPGA |
| 206 | +card can physically be in any slot. Slot position is configurable in the |
| 207 | +software. |
| 208 | + |
| 209 | +Note: The Super Serial Card core has proven to be unstable for some users |
| 210 | +during testing. As a consequence, we disable it in the top.v file by default. |
| 211 | + |
| 212 | +## Code Organization |
| 213 | + |
| 214 | +Specific cards are provided as distinct projects under the [boards/](boards/) subdirectory. Each |
| 215 | +board configuration has a specific subdirectory that includes it's project file as well as any |
| 216 | +project-specific code or resources. Synthesis and PnR output is also in these subdirectories. |
| 217 | + |
| 218 | +Common code is in the [hdl/](hdl/) subdirectory and includes all of the Verilog, SystemVerilog, and |
| 219 | +VHDL code for the A2FPGA codebase that is portable across FPGA hardware. |
| 220 | + |
| 221 | +Other source code is in the [src/](src/) subdirectory and contains Apple II utilities, sample code, |
| 222 | +and the PicoSoC firmware and kernel used by board versions that provide the PicoRV32 co-processor |
| 223 | +for handling FAT32 SD-Card access and other functionality. |
| 224 | + |
| 225 | +## Credits |
| 226 | + |
| 227 | +The A2FPGA core was principally coded by [Ed Anuff](https://github.com/edanuff). Research, design, documentation, |
| 228 | +and extensive testing provided by [Joshua Norrid](https://github.com/jnorrid). Advice and testing was provided by |
| 229 | +[JB Langston](https://github.com/jblang) and [Hans Hübner](https://github.com/hanshuebner) as well as Henry Courbis from |
| 230 | +[ReactiveMicro.com](https://www.reactivemicro.com/). |
| 231 | + |
| 232 | +The Multicard core draws from a number of other open source FPGA cores, including: |
| 233 | + |
| 234 | +- Matthew Hagerty's [F18a TMS9918a](https://github.com/dnotq/f18a) core and |
| 235 | + - [Felipe Antoniosi's port of the F18a to the Tang Nano 9K](https://github.com/lfantoniosi/tn_vdp) |
| 236 | + |
| 237 | +- [MiSTer FPGA Apple IIe core](https://github.com/MiSTer-devel/Apple-II_MiSTer), leveraging: |
| 238 | + - [Stephen A. Edwards' original Apple II core](http://www.cs.columbia.edu/~sedwards/apple2fpga/) |
| 239 | + - [Szombathelyi György's revised Apple //e core](https://github.com/gyurco/apple2efpga) |
| 240 | + - [Alex Steremberg's Verilog port of the MiSTer core](https://github.com/alanswx/Apple-II-Verilog_MiSTer) |
| 241 | + |
| 242 | +- [Sameer Puri's HDMI core](https://github.com/hdl-util/hdmi) |
| 243 | + |
| 244 | +- [MikeJ & Sorgelig's YM2149 core](https://github.com/MiSTer-devel/Apple-II_MiSTer/blob/master/rtl/mockingboard/YM2149.sv) |
| 245 | + |
| 246 | +- [Gideon Zweijtzer's 6522 core](https://github.com/mist-devel/plus_too/blob/master/via6522.vhd) |
| 247 | + |
| 248 | +- [Gary Becker's 6551 core](https://github.com/MiSTer-devel/CoCo3_MiSTer/blob/master/rtl/UART_6551/uart_6551.v) |
| 249 | + |
| 250 | +- [Claire Xenia Wolf's PicoRV32 and PicoSoC](https://github.com/YosysHQ/picorv32) and |
| 251 | + - [Lawrie Griffiths' example of running PicoSoC from BRAM](https://github.com/lawrie/pico_ram_soc) |
| 252 | + |
| 253 | +- [Adam Gastineau's SDRAM controller core](https://github.com/agg23/sdram-controller) |
| 254 | + |
| 255 | +None of this possible without Jim Sather's Understanding the Apple IIe and |
| 256 | +Winston D. Gaylor's The Apple II Circuit Description. |
| 257 | + |
| 258 | +All of this is an homage to Steve Wozniak for creating the Apple II as well as |
| 259 | +to the great chip designers of the 8-bit era, such as Karl Guttag who designed the |
| 260 | +TI9918a video processor at Texas Instruments which was used by the SuperSprite card, |
| 261 | +the emulation of which was the original impetus for this project. |
| 262 | + |
| 263 | +## License(s) |
| 264 | + |
| 265 | +A2FPGA an open source hardware project and the A2FPGA Multicard Core gratefully leverages the work |
| 266 | +of other open source authors. New code that was created specifically for this project |
| 267 | +is made available under the MIT License but many files may have different licenses in their headers |
| 268 | +from the original authors. All open source code from other authors that is reused |
| 269 | +in this project is believed to be used consistently with the licenses such code is provided |
| 270 | +under. If reusing any code from this project, please be sure to check that your intended |
| 271 | +usage is covered by the stated licenses. |
| 272 | + |
| 273 | +## Contact |
| 274 | + |
| 275 | +[info@a2fpga.com](mailto:info@a2fpga.com) |
0 commit comments