diff --git a/_config.yml b/_config.yml index c741881..f980e76 100644 --- a/_config.yml +++ b/_config.yml @@ -1 +1 @@ -theme: jekyll-theme-slate \ No newline at end of file +theme: jekyll-theme-slate diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..f8ae41a --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,59 @@ +# Configuration + +The Epple \]\[ Emulator is most useful when properly configured. +After downloading and installing the Epple \]\[ Program, some System ROM (demo or real), and +optionally the peripheral card ROMs you want to use, you will need to configure the program. +Configuring is concerned primarily with telling the program what peripheral cards to use, +and where the ROM files are located (and what memory addresses to load them at). + +## epple2.conf + +The default configuration file for +the Epple \]\[ emulator is: + + /etc/epple2/epple2.conf + +For Windows, the file will be: + + C:\Program Files\Epple2\etc\epple2\epple2.conf + +The configuration file could be in a different location depending upon how +the distribution package is built. + +You can specify a different configuration file for the emulator to use by +specifying its name as the argument when running the epple2 program. + +The format of the configuration file is just lines of [commands](commands,.md). +Comments begin with a hash `#` character, and continue to the end of the line. + +## Firmware + +Firmware, commonly called ROM images or ROMs, will need to be loaded +into the emulated ROM areas of the emulated Apple +in order for it to be able to boot the emulated Apple machine. +The firmware available is described in this documentation. +Once the firmware image files are installed on your computer, you can use the `import` +command in the configuration file to load the image files into the emulator. + +## Peripheral Cards + +Another primary concern for configuring the Epple \]\[ is the insertion of +peripheral cards into the Apple's slots. The most useful card is probably the +Disk \]\[ Controller card; you will need to insert one of these cards if you want +to be able to load floppy disk images into the emulated Apple. The various +types of cards available are described in the cards section. +You can use the `slot` command in the configuration file to insert +them into the Apple's slots. + +## Sample Configuration Files + +There are a number of configuration files provided with the distribution for +your convenience. They provide various common configurations of machines. +You can use one of these files directly, by specifying its path as the argument +to the program, or as a starting point for you own configuration file. These sample +files are in the same location as the default +epple2.conf+ file. + +The Epple \]\[ Emulator can actually be run without a configuration file at all. +In this case, you will be able to power on the Apple and see the low-resolution +graphics display showing random RAM data. The system will not run, because +there is no firmware loaded, but the emulator will otherwise be functional. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..08ac63b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,40 @@ +# Epple \]\[ + +The Emulated APPLE \]\[ +(by Chris Mosher). + +--- + +[screenshots](screenshots.md) +[configuration](configuration.md) + +--- + +Epple \]\[ is an emulator of the original APPLE \]\[ and APPLE \]\[ PLUS +computers from [Apple, Inc.](https://www.apple.com/) It +runs on Windows, Mac, and Linux platforms. + +[![GPLv3](https://www.gnu.org/graphics/gplv3-88x31.png)](http://www.gnu.org/licenses/gpl-3.0-standalone.html) +Epple \]\[ is released under the +[GPLv3](http://www.gnu.org/licenses/gpl-3.0-standalone.html) +license. + +It is written in C++ and is designed with cross-platform +portability in mind. It uses the [SDL2](https://www.libsdl.org) graphics library. + +## Features + +* **Cycle-accurate** MOS 6502 CPU including *phantom reads* +* **NTSC** video signal emulation: all video *quirks* emulated accurately +* **Revision Zero** motherboard +* **TV** and **monitor** emulation +* **Floating data bus**, and video scanner +* **Cards**: Disk \]\[, language, firmware, clock +* **Logic State Sequencer** emulation (16 and 13 sector disks) +* **WOZ 2** disk image format, supports all *copy-protected* disks +* **Track arm** accurately writes *quarter-tracks* +* **Paddles** (mouse emulates two paddles) +* **Cassette** tape interface +* **PR#1** writes to standard output +* **Repeat** key +* **POWER** light diff --git a/docs/screenshots.md b/docs/screenshots.md new file mode 100644 index 0000000..f8e35c0 --- /dev/null +++ b/docs/screenshots.md @@ -0,0 +1,217 @@ +# Screenshots + + + +## DOS 3.3 System Master boot + +image::dos330boot.png[] + +Here we've configured an Apple \]\[ plus, with a disk +controller in slot 6, and a language card in slot 0. +We've booted the **DOS 3.3 System Master** disk. It correctly +identifies the machine as an Apple \]\[ plus, and then +loads Integer BASIC into the language card. You can switch +between Applesoft and Integer BASIC by using the `FP` and +`INT` commands. + + + +## DOS 3.1 System Master on Revision 0 motherboard + +image::dos310rev0.png[] + +Here we've configured an Apple \]\[ (Integer BASIC ROMs), +with a Revision Zero motherboard, and a disk +controller (with 13-sector ROMs) in slot 6. With a +revision 0 motherboard, when the machine is powered-on, +the CPU doesn't start actually running until you +manually press the RESET button. Also, the old Monitor +ROMs do not boot from the disk drives automatically; +you need to type `C600G` to boot. +We've booted the DOS 3.1 System Master disk and done a +catalog of it. As you can see, with a revision 0 motherboard, +the text is displayed in green and purple, which are also the +only two Hi-Res colors. Later revisions +of the motherboard added a *color burst killer* which is +active during text mode, so the text would be strictly white. +Two more Hi-Res colors, blue and orange, were also added in +later revisions. + + + +## PRODOS 1.1.1 boot + +image::prodos.png[] + +Here we've configured an Apple \]\[ plus with language card +and disk drive. We're booting a PRODOS 1.1.1 disk. + + + +## Bishop's Apple Split + +image::applesplit.png[] + +The October 1982 issue of [Softalk](http://en.wikipedia.org/wiki/Softalk) +featured an article by Bob Bishop entitled +[Have an Apple Split](http://rich12345.tripod.com/aiivideo/softalk.html), which describes +in some detail the inner workings of the Apple \]\['s video processing. Listings 1 and 2 from that +article show a short Applesoft program and assembly language subroutine that allow the Apple \]\[ +to have a screen split between text and graphics display. To achieve this on the EPPLE \]\[, +copy the following text and paste it into the emulator (at the Applesoft `]` prompt). Since the +EPPLE \]\[ accurately emulates the video scanning and timing of the original Apple \]\[s, this +*split screen* technique works successfully. +The rest of the behavior described in the article (the floating data bus) is also emulated +faithfully by the EPPLE \]\[. + +``` basic +CALL -151 + +300:8D 52 C0 A9 E0 A2 04 CD 51 C0 D0 F9 CA D0 F8 A9 +310:A0 A2 04 CD 50 C0 D0 F9 CA D0 F8 8D 51 C0 60 + +E000G + +100 HOME + +200 FOR K = 0 TO 39 +210 POKE 1448+K, 14*16 +220 POKE 2000+K, 10*16 +230 COLOR = K+4 +240 VLIN 24, 45 AT K +250 NEXT K + +300 VTAB 6 : HTAB 17 +310 PRINT "APPLE II" + +400 CALL 768 +500 GOTO 400 + +RUN +``` + + + +## Mysterious Pink Line + +image::pinkmystery.png[] + +Jim Sather's book +[Understanding the Apple \]\[](http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software), +which was the primary +reference for the internal design of the EPPLE \]\[ emulator, describes the video +generation process of the Apple \]\[, in great detail, in Chapter 8. +On page 8-21 he shows a simple Applesoft BASIC program (shown below) +that shows an example of one of the hi-res idiosyncrasies on the Apple \]\[. +The program would logically draw three orange lines, but due to the +video cutoff and extension of half-dot shifted pixels, instead the right +line is brown, and there is a *mysterious pink line* (actually magenta) +on the far left of the screen. The EPPLE \]\[ faithfully emulates this behavior. + +``` basic +NEW + +10 HGR : HCOLOR = 5 : HPLOT 5,159 TO 5,0 TO 279,0 TO 279,159 + +RUN +``` + + + +## Display Aspect Ratio + +image::aspectratio.png[] + +Jim Sather also describes the aspect ratio of the Apple \]\[ when +displayed on a TV screen (p. 8-28). Software developers would need +to take this into account when trying to draw accurate shapes. +The EPPLE \]\[ emulates the correct aspect ratio. +For example, the following Applesoft BASIC program draws a +rectangle, and a proper square: + +``` basic +NEW + +10 HGR +15 REM +16 REM RECTANGLE (VIOLET) +20 A = 36 : B = 136 +30 HCOLOR = 2 +40 HPLOT A,A TO A,B TO B,B TO B,A TO A,A +45 REM +46 REM SQUARE (GREEN) +50 A = 25 : B = 147 +60 HCOLOR = 1 +70 HPLOT A,A TO A,B TO (B*1.19+.5),B TO (B*1.19+.5),A TO A,A + +RUN +HOME +``` + + + +## Split Screen HIRES/LORES colors + +image::splitcolorstv.png[] +image::splitcolorsmon.png[] + +Jim Sather's book also shows an Applesoft BASIC +program and assembly language subroutine on pages 3-16 and 3-17 (reproduced +below) that produce the display shown here. The screen is split between HIRES +and LORES graphics by a timed loop that manipulates the screen switches. +(Press any key repeatedly to move the position of the split.) + +Notice that the Apple \]\[ can actually produce more HIRES colors than are +documented in the standard Apple reference manuals. White, black, green, +purple, blue, and orange are normally documented, but by careful manipulation +of the high-bit (half-dot shift indicator) of the HIRES display byte, many +other colors can be produced. The additional colors match some LORES colors. +Also notice that the text at the bottom of the screen is colored green and +purple while in mixed text/graphics mode. This is because the *color +burst killer* circuit is not active while displaying graphics on the +Apple \]\[ machines. + +``` basic +CALL -151 +1F00:AC 54 C0 A0 27 20 27 1F +1F08:AC 10 C0 AC 00 C0 30 F3 +1F10:69 01 29 01 AA BC 56 C0 +1F18:A2 08 20 31 1F A0 31 20 +1F20:27 1F 18 90 E6 D0 01 88 +1F28:88 EA D0 F9 60 48 68 EA +1F30:EA A0 62 20 27 1F EA CA +1F38:D0 F3 60 + +E000G + 30 HGR : HOME : VTAB 21 : PRINT "1 7 D 2 8 E B 4 5 A 3 6 C 9 F 8" + 40 DIM COLR(39), X(21) +100 FOR A = 0 TO 39 : READ COLR(A) : COLOR = COLR(A) : VLIN 0, 39 AT A : NEXT A +200 FOR A = 0 TO 21 : READ COLR(A) : READ X(A) : HCOLOR = COLR(A) +210 HPLOT X(A), 0 TO X(A), 159 : NEXT A +220 FOR A = 8319 TO 16383 STEP 128 : POKE A, 64 : NEXT A +300 CALL 7936 +400 REM LORES DATA +410 DATA 1,0,7,7,0,13,13,0,2,2,0,8,8,0,14,14,0,11,11,0 +420 DATA 4,4,0,0,5,0,0,10,0,3,0,6,0,12,0,9,0,15,0,8 +500 REM HIRES DATA +510 DATA 4,0,3,20,4,21,3,41,4,42,7,62,7,83,7,104,3,105,7,125,3,126,7,159,3,161 +520 DATA 7,180,3,182,3,206,7,220,3,233,7,247,3,262,3,263,7,279 + +RUN +``` + + + +## Miscellaneous + +image::gplrom.png[] + +Example of the Demo System ROM provided with the EPPLE \]\[ emulator. + +image::static.png[] + +Random TV "static" when no video signal is present. + +image::apple2.png[] + +Apple System ROM showing the APPLE \]\[ title.