diff --git a/doc/80x15.png b/doc/80x15.png new file mode 100644 index 0000000..ed028fe Binary files /dev/null and b/doc/80x15.png differ diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..af6c27d --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,19 @@ +.SUFFIXES: .asciidoc .html + +.asciidoc.html : + asciidoc -b html5 $< + +all : doc + +doc : index.html + +clean : + rm -f index.html + +install : + mkdir -p deploy + cp *.html *.png *.gif deploy + cp -R callouts deploy + +uninstall : + rm -Rf deploy diff --git a/doc/applesplit.png b/doc/applesplit.png new file mode 100644 index 0000000..5c6f85a Binary files /dev/null and b/doc/applesplit.png differ diff --git a/doc/building.asciidoc b/doc/building.asciidoc new file mode 100644 index 0000000..e61f4c4 --- /dev/null +++ b/doc/building.asciidoc @@ -0,0 +1,128 @@ +== Building From Source + + + +The Epple ][ Emulator is written in C+\+, and can be built +using the standard +make+ program. + +The primary dependency is +http://www.libsdl.org/[Simple DirectMedia Layer] (SDL). +Your linux distribution may provide a package. Or else +you can download it directly from SDL's web site. In +either case, be sure to install the ``Development Libraries'' +for your particular platform. + + + +=== Debian Linux Example + +[source,sh] +--------------------------------------------------- +sudo apt-get install build-essential libsdl1.2-dev # <1> +cd +mkdir epple2 +cd epple2 +wget http://mosher.mine.nu/epple2/download/epple2-latest.tar.gz # <2> +tar xzvf epple2-1.0.tar.gz +mkdir build # <3> +cd build +../epple2-1.0/configure # <4> +make # <5> +sudo make install # <6> +--------------------------------------------------- +<1> Install dependencies: gcc, make, SDL +<2> Retrieve the latest Epple ][ source distribution +<3> Use this directory for a VPATH-style build +<4> Run one-time configuration script for your system. Use +--help+ for more information. +<5> Compile and link. Program will be +src/epple2+ +<6> Install into standard system directories + + + +=== Windows/MSYS Example + +==== Install MinGW/MSYS + +Install MSYS into +C:\msys\+ + +Install MinGW into +C:\msys\mingw\+ + +For more information on MinGW and MSYS, see http://www.mingw.org/[]. + +==== Install SDL + +At http://www.libsdl.org/[] find the download page. +Download the ``Development Libraries'' for Win32/mingw, for example: + ++SDL-devel-1.2.13-mingw32.tar.gz+ (Mingw32) + +and save it to your MSYS home directory (for example, +C:\msys\home\Administrator+). +Run MSYS, and at the bash prompt, go to your home directory and +untar the SDL archive to your home directory: + +[source,sh] +-------- +$ cd +$ tar xzvf SDL-devel-1.2.13-mingw32.tar.gz +-------- + +Then follow the instructions to install SDL, for example: + +[source,sh] +-------- +$ cd SDL-1.2.13 +$ make native +-------- + +==== Untar Epple ][ Source + +Download the Epple ][ Source Distribution +and save it to your MSYS home directory (for example, +C:\msys\home\Administrator+). +Run MSYS, and at the bash prompt, go to your home directory and +untar the epple2 source distribution tar file. For example: + +[source,sh] +-------- +$ cd +$ tar xzvf epple2-1.0.tar.gz +-------- + +==== Build Epple ][ + +Then build as follows. I recommend doing a VPATH build, +where you build into a different directory than the source +directory. To accomplish this, create a new directory for +building, somewhere, such as: + +[source,sh] +-------- +$ cd +$ mkdir buildepple2 +$ cd buildepple2 +-------- + +Then run +configure+ from there. For the MSYS build to work, +you need some extra parameters to the build, and you could +also add some compiler options to optimize the build. For +example (from the +buildepple2+ directory you just created): + +[source,sh] +-------- +$ ~/epple2/configure --prefix= \ +CXXFLAGS="-I/usr/include -O4 -msse3" \ +CFLAGS="-I/usr/include" \ +LDFLAGS="-L/usr/lib -mconsole -mthreads -mno-cygwin" +$ make +-------- + +If all goes well, it will build without any errors. +If you get errors about not finding +SDL.h+, make sure +SDL is installed, and make sure the configure command +is correct. (If you just run configure without the +options shown above, you will get this error at build time.) +The result of the build (on Windows platform) is + ++installer/epple2.msi+ + +which is an installable file for Windows. To install +epple2, just double-click on this file from Explorer. diff --git a/doc/callouts/1.png b/doc/callouts/1.png new file mode 100644 index 0000000..7d47343 Binary files /dev/null and b/doc/callouts/1.png differ diff --git a/doc/callouts/10.png b/doc/callouts/10.png new file mode 100644 index 0000000..997bbc8 Binary files /dev/null and b/doc/callouts/10.png differ diff --git a/doc/callouts/11.png b/doc/callouts/11.png new file mode 100644 index 0000000..ce47dac Binary files /dev/null and b/doc/callouts/11.png differ diff --git a/doc/callouts/12.png b/doc/callouts/12.png new file mode 100644 index 0000000..31daf4e Binary files /dev/null and b/doc/callouts/12.png differ diff --git a/doc/callouts/13.png b/doc/callouts/13.png new file mode 100644 index 0000000..14021a8 Binary files /dev/null and b/doc/callouts/13.png differ diff --git a/doc/callouts/14.png b/doc/callouts/14.png new file mode 100644 index 0000000..64014b7 Binary files /dev/null and b/doc/callouts/14.png differ diff --git a/doc/callouts/15.png b/doc/callouts/15.png new file mode 100644 index 0000000..0d65765 Binary files /dev/null and b/doc/callouts/15.png differ diff --git a/doc/callouts/2.png b/doc/callouts/2.png new file mode 100644 index 0000000..5d09341 Binary files /dev/null and b/doc/callouts/2.png differ diff --git a/doc/callouts/3.png b/doc/callouts/3.png new file mode 100644 index 0000000..ef7b700 Binary files /dev/null and b/doc/callouts/3.png differ diff --git a/doc/callouts/4.png b/doc/callouts/4.png new file mode 100644 index 0000000..adb8364 Binary files /dev/null and b/doc/callouts/4.png differ diff --git a/doc/callouts/5.png b/doc/callouts/5.png new file mode 100644 index 0000000..4d7eb46 Binary files /dev/null and b/doc/callouts/5.png differ diff --git a/doc/callouts/6.png b/doc/callouts/6.png new file mode 100644 index 0000000..0ba694a Binary files /dev/null and b/doc/callouts/6.png differ diff --git a/doc/callouts/7.png b/doc/callouts/7.png new file mode 100644 index 0000000..472e96f Binary files /dev/null and b/doc/callouts/7.png differ diff --git a/doc/callouts/8.png b/doc/callouts/8.png new file mode 100644 index 0000000..5e60973 Binary files /dev/null and b/doc/callouts/8.png differ diff --git a/doc/callouts/9.png b/doc/callouts/9.png new file mode 100644 index 0000000..a0676d2 Binary files /dev/null and b/doc/callouts/9.png differ diff --git a/doc/cards.asciidoc b/doc/cards.asciidoc new file mode 100644 index 0000000..4ea8eb5 --- /dev/null +++ b/doc/cards.asciidoc @@ -0,0 +1,263 @@ +[[cards]] + +=== Peripheral Cards + +==== Disk ][ Controller + +The Disk ][ Controller card emulates the floppy disk controller card and associated +disk drives in the original Apple ][ systems. In the emulator, each card has two +drives attached to it, referred to as drive 1 and drive 2. The floppy disks +themselves are represented by a ``nibble'' image of the contents. The +emulator emulates the hardware, but to be of any use, you will need to provide +the firmware ROM code. + +To use a disk card and drives, add these lines to your epple2.conf file, for example: + +-------- +slot 6 disk +import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.ex65 +-------- + +The first line uses the <<_slot,slot>> command to +insert a disk contoller card into slot 6, which is the standard +slot used for disk cards. The next line uses the <<_import,import>> +command to load the card's ROM with the disk controller +firmware. This firmware is known as the ``bootstrap'' or ``P5'' ROM code. +It is seen by the Apple ][ at memory addresses $Cs00-$CsFF, where s is the +slot number (so in the common case of the card being in slot 6, the ROM is +at $C600-$C6FF). The firmware is copyright by Apple, and is available from +the http://mosher.mine.nu/apple2/[Apple II Library]. + +You can also load a floppy disk image (nibble format) into the drive,either by putting +the <<_load,load>> command into the +epple2.conf+ file, or by using the command prompt +in the emulator (+F5+ key). For example, you could load the DOS 3.3 system master into +slot 6, drive 1, with this command + +-------- +load slot 6 drive 1 /usr/lib/apple2/dos3x/16sector/disks/dos330/clean330sysmas.nib +-------- + + + + +==== Language + +The language card emulates an Apple 16K RAM card, commonly called a Language Card. +To use a language card, add this line to your epple2.conf file: + +-------- +slot 0 language +-------- + +Note that DOS and ProDOS will make use of a language card only if it is in slot _zero_. + +The language card has RAM at addresses $E000 through $FFFF, as well as two banks of RAM +at addresses $D000 through $DFFF. A program switches between these RAMs and/or the +motherboard ROM by using the I/O switches at $C080 through $C08F. + +The information area of the Epple ][ will show the current state of the +language card as follows: + +* +R+ Read from card RAM (vs. motherboard ROM) +* +W+ Write to card RAM (vs. write-disabled) +* +B1+ Use $D000 bank 1 +* +B2+ Use $D000 bank 2 + +An overview of the I/O switches that control the language card +is provided by Jim Sather in +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +p. 5-30, Table 5.4, as follows: + +[options="header", style="monospaced"] +|================================================================== +| BANK2 | BANK1 2+| ACTION + +| C080 | C088 .2+| WRTCOUNT = 0*, WRITE DISABLE .2+| READ ENABLE +| C084 | C08C + +| RC081 | RC089 .2+| WRTCOUNT = WRTCOUNT + 1* .2+| READ DISABLE +| RC085 | RC08D + +| WC081 | WC089 .2+| WRTCOUNT = 0* .2+| READ DISABLE +| WC085 | WC08D + +| C082 | C08A .2+| WRTCOUNT = 0*, WRITE DISABLE .2+| READ DISABLE +| C086 | C08E + +| RC083 | RC08B .2+| WRTCOUNT = WRTCOUNT + 1* .2+| READ ENABLE +| RC087 | RC08F + +| WC083 | WC08B .2+| WRTCOUNT = 0* .2+| READ ENABLE +| WC087 | WC08F +|================================================================== + +^*^ Writing to expansion RAM is enabled when WRTCOUNT reaches 2. + + + +==== Firmware + +The firmware card emulates a (modified) Apple Firmware card. +The firmware card is simply an alternate ROM, at addresses +$D000 through $FFFF, that is switched using the I/O switches +at addresses $C080 through $C08F. In order to make use of the +firmware card, you will need to load the ROM with a binary image +from a file on disk. For example, to insert an Integer BASIC +firmware card into the emulator, add these lines to your ++epple2.conf+ file: + +-------- +# Firmware card with Integer BASIC and old Monitor +slot 0 firmware +import slot 0 rombank 1000 /usr/lib/apple2/system/intbasic/intbasic.ex65 +import slot 0 rombank 2425 /usr/lib/apple2/system/other/other.ex65 +import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2/monitor.ex65 +-------- + +For an Applesoft BASIC firmware card, use these: + +-------- +# Firmware card with Applesoft BASIC and Autostart Monitor +slot 0 firmware +import slot 0 rombank 0000 /usr/lib/apple2/system/applesoft/applesoft.ex65 +import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2plus/monitor.ex65 +-------- + +Note that the addresses specified in the +epple2.conf+ file for the +rombank are based on the beginning of the bank ROM itself. For example, specifying ++1000+ (which is 1000 hex) represents the final memory address of $E000, because +the bank ROM is always based at address $D000. + +The idea is that you would load your motherboard with, for +example, Applesoft BASIC and the Autostart Monitor ROM (to emulate +an Apple ][ plus), and then install a firmware card with Integer +BASIC and the old Monitor. Booting with DOS 3.3, then, would allow +you to type +FP+ to use Applesoft BASIC, or +INT+ to switch to Integer BASIC. + +Note that DOS and ProDOS will make use of a firmware card only if it is in slot _zero_. + +Jim Sather, in +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +on pages 6-18 through 6-21, explains +how to modify a firmware card to allow independent switching of the $F800-$FFFF +ROM memory. This area is occupied by the Monitor, so it is primarily +intended to allow the user to switch between the old Monitor and the Autostart +Monitor, independent of switching between Integer and Applesoft BASIC. The EPPLE ][ +firmware card emulates this behavior. + +The information area of the EPPLE ][ will show the current state of the +firmware card as follows: + +* +D+ Read from firmware card $D000-$F7FF (vs. motherboard BASIC ROM) +* +F8+ Read from firmware card $F800-$FFFF (vs. motherboard Monitor ROM) + + + +==== Clock + +The clock card emulates a ProDOS-compatible real-time clock card for the Apple ][. +To use a clock card, you will need to configure the EPPLE ][ to insert one into +a slot, typically slot 4. You will also need to load the card with its ROM code, +which is provided with the emulator in the clock.ex65 file. +For example, add this to your epple2.conf file: + +-------- +slot 4 clock +import slot 4 rom 0 /usr/lib/epple2/cards/clock.ex65 +-------- + +Of course you may need to adjust the path for your particular system. + +To verify that the clock card is working correctly, you can run the following Applesoft +program to retrieve the current time from the clock card and print it. +This program assumes the card is in slot 4. + + +[source,vbs] +------------------------------------------------- +NEW + +10 CALL -15360 : REM $C400 SLOT 4 ENTRY POINT +20 A = 512 : REM $0200 INPUT BUFFER +30 C = PEEK(A) +40 IF C < 160 THEN 99 +50 PRINT CHR$(C); +60 A = A+1 +70 GOTO 30 +99 END + +RUN +------------------------------------------------- + + +The card returns data (into the GETLN input buffer at $200) in +the following format: + ++mm,ww,dd,hh,nn,ss,000,yyyy,Time Zone,v+ + +* +mm+ Month, 01-12 +* +ww+ Weekday, 00=Monday... 06=Saturday +* +dd+ Day, 01-31 +* +hh+ Hour, 00-23 +* +nn+ Minute, 00-59 +* +ss+ Second, 00-61 +* +000+ Milliseconds; always zero +* +yyyy+ Year, e.g., 2008 +* +Time Zone+ time zone string (could contain lower-case characters, + which won't display correctly) +* +v+ Daylight Saving Time in effect, 0=no, 1=yes + +Note that only +mm,ww,dd,hh,nn+ fields are used by ProDOS. The other +fields, +ss,000,yyyy,Time Zone,v+, are an EPPLE ][ extension. Also note +that ProDOS was not designed to work for years past 2007, so +ProDOS will show the incorrect year, but the other fields will be accurate. +I believe patches exist for ProDOS to fix this. + + + +==== Standard Input + +The ``standard input'' card doesn't emulate a real piece of hardware; rather, it +reads characters from standard input (stdin) (of the EPPLE ][ emulator). + +To use a standard input card, add these lines to your +epple2.conf+ file: + +------------------------------------------------- +# IN#2 reads from standard input +slot 2 stdin +import slot 2 rom 0 /usr/lib/epple2/cards/stdin.ex65 +------------------------------------------------- + +That will insert a stdin card into slot 2, and then load its +ROM image into the card. +The stdin ROM is provided with the EPPLE ][ distribution. + +For example, if you have a stdin card installed in slot 2, start +the EPPLE ][ emulator from the command line, and at the Applesoft +prompt, type +IN#2+. Then you can switch back to the +command shell, and whatever you type will be fed into the emulated +Apple. Use RESET or +IN#0+ to go back to normal. + + + +==== Standard Output + +The ``standard output'' card doesn't emulate a real piece of hardware; rather, it acts +similar to a printer card, but instead of sending characters to a printer, it sends +them to standard output (stdout) (of the EPPLE ][ emulator). + +To use a standard output card, add these lines to your +epple2.conf+ file: + +------------------------------------------------- +# PR#1 prints to standard output +slot 1 stdout +import slot 1 rom 0 /usr/lib/epple2/cards/stdout.ex65 +------------------------------------------------- + +This will insert a stdout card into slot 1 (which is the typical +slot for a printer card), and then load its ROM image into the card. +The stdout ROM is provided with the EPPLE ][ distribution. + +For example, if you have a stdout card installed, at the Applesoft +prompt, type +PR#1+. Whatever you type next will be +echoed to standard output. Type +PR#0+ to stop echoing. diff --git a/doc/cassette.asciidoc b/doc/cassette.asciidoc new file mode 100644 index 0000000..8ad770a --- /dev/null +++ b/doc/cassette.asciidoc @@ -0,0 +1,188 @@ +=== Cassette Tape Interface + +The Apple ][ and Apple ][ plus machines had the ability to save and load binary +data to and from cassette tape. The user would attach a standard cassette tape +recorder to the jacks on the back of the Apple ][, and use the monitor +R+ and +W+ +commands, or the Applesoft BASIC commands +LOAD+ and +SAVE+, to read and write data +on the cassette tape. The user would have to press the play and/or record buttons +on the player at the right time. + +The Epple ][ emulates the cassette interface, using a file to hold the +recorded portion of the tape. The file will grow in length as necessary +to hold data that the emulated Apple is writing to the ``tape.'' +The emulator will not overwrite existing data on a tape image. +The emulator will automatically ``press'' the play or record buttons that +would have been necessary when using the original machine. + +==== Commands + ++cassette new + + +This creates a new empty file (on the host computer) that represents a cassette tape image. +The file must not already exist. + ++cassette load + + +This loads an existing file (from the host computer) containing a cassette tape image. +The tape is automatically positioned at its beginning (fully rewound). + ++cassette unload+ + +This removes the file from the cassette tape. Note that you must manually save +the file using the +cassette save+ command (described below). + +[WARNING] +Unloading an unsaved file will lose any changes made to the file, without warning. + ++cassette rewind+ + +This command ``rewinds'' the cassette tape, positioning it at the beginning +of the tape (for subsequent reading). You do not need to rewind the tape +before saving or unloading it, of course. + ++cassette save+ + +This command saves the changed tape to the file. Note that the display will show +an asterisk +*+ next to the file name if there are unsaved changes that need to +be saved. Unsaved changes will be lost without warning if the file is unloaded +or if you quit the program. + +==== Example of Saving to Tape + +Start up the emulator with Applesoft ROMs for this tutorial. +Enter a simple Applesoft program, just as an example, that we +are going to save to a cassette tape image file. + +[source,vbs] +------------------------ +]NEW + +]10 PRINT "HELLO" + +]20 END + +]LIST + +10 PRINT "HELLO" +20 END + +]RUN +HELLO + +] +------------------------ + +We first need to load a tape image file into the cassette machine. +Enter command mode by pressing +F5+, then make a new tape +image file. + +------------------------ +command: cassette new hello.tap +------------------------ + +This will create a new, empty tape file image named +hello.tap+ +in the current default directory. (We could have specified a full path +name for the file if we wanted to place it in a different directory.) +Notice that the emulator now displays the name of the tape image file, +along with the position and length of the tape image, which is now +0/0+. + +Next, we tell Applesoft to save the program to the cassette. For this, +we just use the +SAVE+ command. Note that this is not the +DOS +SAVE+ command; the DOS command has a file name after ++SAVE+. We just use +SAVE+ with no file name. + +------------------------ +]SAVE + +] +------------------------ + +It will take 10 seconds or so for it to save. Notice that the +current position of the tape is counting up as the Apple saves +the program. When it is finished, you need to save the changes +to the file. Press +F5+ and enter the emulator command to save +the tape image file. + +------------------------ +command: cassette save +------------------------ + +We can now unload the file from the emulator (which is like ejecting +the tape from the cassette player). + +------------------------ +command: cassette unload +------------------------ + +==== Example of Loading from Tape + +To load the saved program (from the previous section) into the Apple again, +we will need to first load the tape image file back into the cassette machine. +Press +F5+ to enter command mode and load the image file. + +------------------------ +command: cassette load hello.tap +------------------------ + +This will load hello.tap (in the current default directory). Notice the +emulator now displays the name of the tape image file, along with the +position and length of the tape image, which in this case is +0/33481+. + +Next, we tell Applesoft to load the program from the cassette. For this, +we just use the +LOAD+ command. Note that this is not the +DOS +LOAD+ command; the DOS command has a file name after ++LOAD+. We just use +LOAD+ with no file name. + +------------------------ +]LOAD + +] +------------------------ + +It will take 10 seconds or so for it to load. Notice that the +current position of the tape is counting up as the Apple loads +the program. When it is finished, the program will be loaded. + +[source,vbs] +------------------------ +]LIST + +10 PRINT "HELLO" +20 END + +]RUN +HELLO + +] +------------------------ + +==== Tape Image File Format + +The format of the tape image file is unique to the Epple ][ +It is stored in a low-level format that represents the waveform that the Apple writes +to the cassette tape. + +The file is a binary format. Each byte in the file represents the length of one half of one cycle +(of voltage level variation) written to the tape. The length is in 10-microsecond units. + +For example, a tape image file might have the following binary bytes (in decimal): ++65 65 65 65 65 20 25 50 50 25 25 25 25 50 50+ +Since each byte represents a 10-microsecond unit, these bytes represent the following +half-cycle lengths in microseconds: ++650 650 650 650 650 200 250 500 500 250 250 250 250 500 500+ +The meaning of these half-cycle lengths to the Apple is as follows: + +------------------------ +|-------HEADER------|--sync-|-1-bit-|-0-bit-|-0-bit-|-1-bit-| +| | | | | | | +|650 650 650 650 650|200 250|500 500|250 250|250 250|500 500| +------------------------ + +where +HEADER+ is a header section the Apple writes (to skip any +unrecordable leader section on a real cassette tape); +sync+ is a +synchronization cycle; and the subsequent cycles are the actual +bits of data saved on the tape. A 500-microsecond cycle (which +is stored in the file as two 250 microsecond half-cycles) +represents a *zero* bit, and a 1-millisecond cycle (which is +stored in the file as two 500 microsecond half-cycles) +represents a *one* bit. diff --git a/doc/commands.asciidoc b/doc/commands.asciidoc new file mode 100644 index 0000000..90772ff --- /dev/null +++ b/doc/commands.asciidoc @@ -0,0 +1,202 @@ +=== Commands + ++<<_slot,slot>> <<_import,import>> <<_load,load>> <<_unload,unload>> <<_save,save>> <<_cassette,cassette>> <<_revision,revision>>+ + +==== slot + +The +slot+ command inserts a card into a peripheral slot of the emulated Apple. + +-------- +slot +------- + +++ Slot number, 0 through 7, to insert the card into. + +++ The type of <> to insert into the slot: + +* +language+ +* +firmware+ +* +disk+ +* +clock+ +* +stdout+ +* +stdin+ +* +empty+ + +The +slot+ command inserts a card into a peripheral slot. For example: + +-------- +slot 0 language +-------- + +inserts a language card into slot zero. Use +empty+ to remove a card: + +-------- +slot 0 empty +-------- + +[NOTE] +The emulated Apple should be _powered off_ before inserting or removing cards. + + + +==== import + +The +import+ command imports a binary image file into the emulated Apple's memory. + +-------- +import slot { rom | rom7 | rombank } +import motherboard { rom | ram } +-------- + +++ Slot number, 0 through 7, of peripheral card to import the binary image into. + +++ Base address in hexadecimal within the given memory area at which to start loading the binary image. + +++ Path of the binary image to import. + +The +import+ command reads the binary image byte-for-byte from the given file-path +into an area of memory in the emulated Apple. You can load into either the motherboard or +a card in one of the slots. For the motherboard, you choose the RAM or ROM area. For a card +in a slot, you can choose either the normal ROM, the bank-switched ROM, or the so-called +``seventh ROM'' area. + +You also have to specify the base address within the specific memory +area at which the image file will be loaded. Note that the base address is specified as the offset +within the specific memory area, and not necessarily as the actual memory address as seen +by the Apple. So for motherboard ROM, for example, specifying a base as 2DED will cause the +image to be loaded at offset 2DED in the ROM, which will be addressed by the Apple at +memory address $FDED (because motherboard ROM ``starts'' at address $D000). + +For peripheral cards, the ROM will be seen at locations $Cs00-$CsFF, where s is the slot +number (1 through 7). The ``seventh ROM'' can be seen as locations $C800-$CFFF; Jim Sather +describes this functionality in +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +on page 6-4, section ``The Seventh ROM Chip.'' The EPPLE ][ emulator handles this processing correctly. A card can +also have bank-switched ROM, which will show up at addresses $D000-$FFFF when switched in +(stealing that address range from motherboard ROM... see +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +p. 5-26 ``The 16K RAM Card''). + + + + + +==== load + +The +load+ command loads a (nibble) floppy disk image into one of the emulated disk drives. + + +-------- +load slot drive +-------- + + +++ Slot number, 0 through 7, of Disk ][ controller card to load the nibble image into. + +++ Drive number, 1 or 2, of the disk drive on the controller card to load the nibble image into. + +++ Path of the nibble floppy disk image to import. + +The +load+ command will load a nibble image into a disk drive. Specify the slot that +contains a Disk ][ controller peripheral card, and specify which drive number (1 or 2). + +[NOTE] +The floppy disk image MUST be a NIBBLE DISK IMAGE. +Other formats (for example, DOS order, +.do+, PRODOS order, ++.po+, +.dsk+, or anything else) must first be converted to nibble format. A nibble image contains +all 35 tracks, in order 0-36, each track being 6656 ($1A00) bytes long. Nibble image files +will generally have a filetype of +.nib+. + + +The best floppy disk image conversion tool I've found is http://ciderpress.sourceforge.net/[CiderPress], +for Windows (but it supposedly runs under Wine on Linux, too). Thanks to Andy McFadden. + + + + + +==== unload + +The +unload+ command removes a floppy disk image from one of the emulated disk drives. + +-------- +unload slot drive +-------- + +++ Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached. + +++ Drive number, 1 or 2, of the disk drive on the controller card to remove the floppy disk image from. + +The +unload+ command removes the disk from the specified slot and drive. + +[WARNING] +If the disk has been modified but not saved, the modifications will be DISCARDED. + + + + + +==== save + +The +save+ command saves changes made on an emulated floppy disk back to the original image file. + +-------- +save slot drive +-------- + +++ Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached. + +++ Drive number, 1 or 2, of the disk drive on the controller card to save. + +++ Path of the nibble floppy disk image to import. + +The +save+ command saves any changes that the emulated Apple ][ has made to the floppy +disk image. It is important to note that the emulator operates on the image only in memory, and does +not immediately write changes back to the real file. You need to issue the +save+ command +in order to write changes back to the file. Note that the emulator will display a asterisk +*+ +next to the file-name of a disk image if it has any unsaved changes. + + + + + +==== cassette + +The +cassette+ command performs various operations of the emulated cassette tape. + + +-------- +cassette new +cassette load +cassette unload +cassette rewind +cassette save +-------- + +++ File path of the (special format) cassette tape image file. + +The +cassette+ command allows the user to control the emulated cassette tape player. +See <<_cassette_tape_interface,Cassette>> for more information about operating the emulated +cassette player and cassette tape image files. + + + + + + +==== revision + +The +revision+ command specifies which revision of Apple ][ motherboard to use. + +-------- +revision +-------- + + +++ Revision number of the motherboard. Currently, only two values make any difference in behavior: 0 or 1. + +The +revision+ command chooses which revision of the Apple ][ motherboard to +use. The only revisions that make any difference (for now, at least) are 0 or 1. Zero +is the original (now quite rare) version of the motherboard, that only had two hi-res +colors (green and purple), and always displayed text with green and purple fringes. +Revision 1 and later motherboards are the ones we are more familiar with. diff --git a/doc/configuration.asciidoc b/doc/configuration.asciidoc new file mode 100644 index 0000000..a0b345c --- /dev/null +++ b/doc/configuration.asciidoc @@ -0,0 +1,63 @@ +== 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>>. +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 <>. +Once the firmware image +files are installed on your computer, you can use the <<_import,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 on the <> section. +You can use the <<_slot,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/doc/debian.png b/doc/debian.png new file mode 100644 index 0000000..f6e85d8 Binary files /dev/null and b/doc/debian.png differ diff --git a/doc/deploy/80x15.png b/doc/deploy/80x15.png new file mode 100644 index 0000000..ed028fe Binary files /dev/null and b/doc/deploy/80x15.png differ diff --git a/doc/deploy/applesplit.png b/doc/deploy/applesplit.png new file mode 100644 index 0000000..5c6f85a Binary files /dev/null and b/doc/deploy/applesplit.png differ diff --git a/doc/deploy/callouts/1.png b/doc/deploy/callouts/1.png new file mode 100644 index 0000000..7d47343 Binary files /dev/null and b/doc/deploy/callouts/1.png differ diff --git a/doc/deploy/callouts/10.png b/doc/deploy/callouts/10.png new file mode 100644 index 0000000..997bbc8 Binary files /dev/null and b/doc/deploy/callouts/10.png differ diff --git a/doc/deploy/callouts/11.png b/doc/deploy/callouts/11.png new file mode 100644 index 0000000..ce47dac Binary files /dev/null and b/doc/deploy/callouts/11.png differ diff --git a/doc/deploy/callouts/12.png b/doc/deploy/callouts/12.png new file mode 100644 index 0000000..31daf4e Binary files /dev/null and b/doc/deploy/callouts/12.png differ diff --git a/doc/deploy/callouts/13.png b/doc/deploy/callouts/13.png new file mode 100644 index 0000000..14021a8 Binary files /dev/null and b/doc/deploy/callouts/13.png differ diff --git a/doc/deploy/callouts/14.png b/doc/deploy/callouts/14.png new file mode 100644 index 0000000..64014b7 Binary files /dev/null and b/doc/deploy/callouts/14.png differ diff --git a/doc/deploy/callouts/15.png b/doc/deploy/callouts/15.png new file mode 100644 index 0000000..0d65765 Binary files /dev/null and b/doc/deploy/callouts/15.png differ diff --git a/doc/deploy/callouts/2.png b/doc/deploy/callouts/2.png new file mode 100644 index 0000000..5d09341 Binary files /dev/null and b/doc/deploy/callouts/2.png differ diff --git a/doc/deploy/callouts/3.png b/doc/deploy/callouts/3.png new file mode 100644 index 0000000..ef7b700 Binary files /dev/null and b/doc/deploy/callouts/3.png differ diff --git a/doc/deploy/callouts/4.png b/doc/deploy/callouts/4.png new file mode 100644 index 0000000..adb8364 Binary files /dev/null and b/doc/deploy/callouts/4.png differ diff --git a/doc/deploy/callouts/5.png b/doc/deploy/callouts/5.png new file mode 100644 index 0000000..4d7eb46 Binary files /dev/null and b/doc/deploy/callouts/5.png differ diff --git a/doc/deploy/callouts/6.png b/doc/deploy/callouts/6.png new file mode 100644 index 0000000..0ba694a Binary files /dev/null and b/doc/deploy/callouts/6.png differ diff --git a/doc/deploy/callouts/7.png b/doc/deploy/callouts/7.png new file mode 100644 index 0000000..472e96f Binary files /dev/null and b/doc/deploy/callouts/7.png differ diff --git a/doc/deploy/callouts/8.png b/doc/deploy/callouts/8.png new file mode 100644 index 0000000..5e60973 Binary files /dev/null and b/doc/deploy/callouts/8.png differ diff --git a/doc/deploy/callouts/9.png b/doc/deploy/callouts/9.png new file mode 100644 index 0000000..a0676d2 Binary files /dev/null and b/doc/deploy/callouts/9.png differ diff --git a/doc/deploy/debian.png b/doc/deploy/debian.png new file mode 100644 index 0000000..f6e85d8 Binary files /dev/null and b/doc/deploy/debian.png differ diff --git a/doc/deploy/dos310rev0.png b/doc/deploy/dos310rev0.png new file mode 100644 index 0000000..a393a6a Binary files /dev/null and b/doc/deploy/dos310rev0.png differ diff --git a/doc/deploy/dos330boot.png b/doc/deploy/dos330boot.png new file mode 100644 index 0000000..d8c768e Binary files /dev/null and b/doc/deploy/dos330boot.png differ diff --git a/doc/deploy/epple2logo.png b/doc/deploy/epple2logo.png new file mode 100644 index 0000000..ebaf135 Binary files /dev/null and b/doc/deploy/epple2logo.png differ diff --git a/doc/deploy/gplv3logo.png b/doc/deploy/gplv3logo.png new file mode 100644 index 0000000..b06e043 Binary files /dev/null and b/doc/deploy/gplv3logo.png differ diff --git a/doc/deploy/index.html b/doc/deploy/index.html new file mode 100644 index 0000000..98a2127 --- /dev/null +++ b/doc/deploy/index.html @@ -0,0 +1,2325 @@ + + + + + +Epple ][ + + + + + +
+
+
+
+
+epple2logo.png +
+
+
+
+
+

Introduction

+
+

Epple ][ is an emulator of the original APPLE ][ and APPLE ][ PLUS +computers from Apple, Inc. It +runs on Windows and Linux platforms, and is released under +GPLv3 + +GPLv3 +

+

It is written in C++ and is designed with cross-platform +portability in mind. It uses the SDL graphics library.

+
+
+
+

Features

+
+
    +
  • +

    +Cycle-accurate: emulates all MOS 6502 CPU cycles including “phantom reads” +

    +
    • +
  • +

    +Video display is synchronized with CPU +

    +
    • +
  • +

    +NTSC video signal emulation: all video quirks emulated accurately +

    +
    • +
  • +

    +Revision 0 motherboard (optional) +

    +
    • +
  • +

    +Multiple display types: monitor and TV emulation +

    +
    • +
  • +

    +Can run full-screen or in a window +

    +
    • +
  • +

    +640x480 resolution +

    +
    • +
  • +

    +Floating data bus, and video scanner +

    +
    • +
  • +

    +Cards: Disk ][, language, firmware, clock +

    +
    • +
  • +

    +Paddles (mouse emulates two paddles) +

    +
    • +
  • +

    +Cassette tape interface +

    +
    • +
  • +

    +PR#1 writes to standard output +

    +
    • +
  • +

    +Accurate keyboard emulation, including the repeat key +

    +
    • +
  • +

    +It even emulates the POWER light! +

    +
    • +
+
+
+
+

Screenshots

+
+
+

DOS 3.3 System Master boot

+
+
+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

+
+
+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 HIRES 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 HIRES colors, blue and orange, were also added in +later revisions.

+
+
+

PRODOS 1.1.1 boot

+
+
+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

+
+
+applesplit.png +
+
+

The October 1982 issue of Softalk +featured an article by Bob Bishop entitled +Have an Apple Split, 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 ][.

+
+
+
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

+
+
+pinkmystery.png +
+
+

Jim Sather’s book +Understanding the Apple II, +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.

+
+
+
NEW
+
+10 HGR : HCOLOR = 5 : HPLOT 5,159 TO 5,0 TO 279,0 TO 279,159
+
+RUN
+
+
+

Split Screen HIRES/LORES colors

+
+
+splitcolors.png +
+
+

Jim Sather’s book +Understanding the Apple II, +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.

+
+
+
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
+
+
+
+
+

Download

+
+
+ + + +
+Tip +Usable Apple ROMs (proprietary +
[You must respect the fact that the Apple System Software and Apple Disk Operating System (DOS) Software are proprietary software; they are copyright by Apple and/or others. This web page is not providing any advice as to the legality of any copying or downloading you may perform.]
) +are available at the Apple II Library.
+
+

The following software is licensed under +GPLv3.

+

Epple ][ Program: epple2.tar.gz

+

System ROM (Demo): epple2sys.tar.gz

+

Card ROMs (stdin/stdout/clock): epple2cards.tar.gz

+

See Building to build from sources.

+
+
+
+

What To Download

+
+
+

Epple ][ Program—The Hardware (Emulated)

+

The Epple ][ Program package is the emulator itself, which emulates the +Apple ][ or Apple ][ plus hardware, as well as the +peripheral card hardware. This is the main program, so you will +certainly need to download this package. To have a full functioning emulator, +you will also need System ROMs and Card ROMs, as described in the following +sections.

+
+
+

System ROMs—The Main System Firmware (Demo or Real)

+

Since the Epple ][ program emulates only the hardware, you will also need to download some system software +for it to run. This is commonly called “firmware” or “ROMs,” because it is stored in the +read-only memory area of the emulated system. The original system software on the +Apple ][ machines is copyright by Apple, and is proprietary. If you own an actual +Apple ][ or Apple ][ plus machine, you can copy
[disclaimer]
 the firmware +from it ($D000-$FFFF) (into a file on your PC) and use it. Alternatively, you can +download
[disclaimer]
 the firmware images from the Apple II Library.

+

If you do not want to download the proprietary firmware, you can still use the emulator (albeit +in a restricted manner) with the free (GPLv3) System ROM (Demo) package. Download +the file for your platform and +install as appropriate. You can choose either binary format (ready to run), or source if you want +to assemble it yourself (using the xa Assembler). +The Demo System ROM only provides commands to dump or set memory bytes, +or run a program in memory. It is not compatible with any Apple software, nor can it read from disks. +It’s just a free simple demo system to make the emulator do something reasonable.

+
+
+

Card ROMs—The Peripheral Card Firmware

+

If you are going to use the Disk ][ Controller peripheral card (which you almost certainly will, if +you want to read any floppy disk images), you will need to have to original ROMs from Apple. +No demo of the Disk ROMs are provided here; you will need to +use the original ROMs, which can be obtained from an original machine (by copying
[disclaimer]
 +it from $C600-$C6FF into a file on the PC), or by downloading
[disclaimer]
 it +from the Apple II Library. +(And, of course, you will need the real Apple System ROM, as noted in the previous section, +not the Demo System ROM.)

+

If you are using any of the clock, the standard output, or the +standard input peripheral cards, you will need to download their firmware as well, +which are contained in the Card ROMs package. You can choose either binary format +(ready to run) or source format (to assemble it yourself(using the +xa Assembler). +If you are not going to use the stdin, stdout, or clock +cards, then you do not need to download this package.

+
+
+
+
+

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. +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 above. +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 on the peripheral 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.

+
+
+
+
+

User Manual

+
+
+

Overview

+

Epple ][ (the Emulated Apple ][ is a free (as in GPLv3), cross-platform +(Windows, Linux) emulator of the Apple ][ and Apple ][ plus computers +from Apple, Inc. It strives for accurate emulation of the original machines, +with a few extra features added.

+
+
+

Commands

+

slot import load unload save cassette revision

+
+

slot

+

The slot command inserts a card into a peripheral slot of the emulated Apple.

+
+
+
slot <slot> <card>
+
+

<slot> Slot number, 0 through 7, to insert the card into.

+

<card> The type of card to insert into the slot:

+
    +
  • +

    +language +

    +
    • +
  • +

    +firmware +

    +
    • +
  • +

    +disk +

    +
    • +
  • +

    +clock +

    +
    • +
  • +

    +stdout +

    +
    • +
  • +

    +stdin +

    +
    • +
  • +

    +empty +

    +
    • +
+

The slot command inserts a card into a peripheral slot. For example:

+
+
+
slot 0 language
+
+

inserts a language card into slot zero. Use empty to remove a card:

+
+
+
slot 0 empty
+
+
+ + + +
+Note +The emulated Apple should be powered off before inserting or removing cards.
+
+
+
+

import

+

The import command imports a binary image file into the emulated Apple’s memory.

+
+
+
import slot <slot> { rom | rom7 | rombank } <base> <file-path>
+import motherboard { rom | ram } <base> <file-path>
+
+

<slot> Slot number, 0 through 7, of peripheral card to import the binary image into.

+

<base> Base address in hexadecimal within the given memory area at which to start loading the binary image.

+

<file-path> Path of the binary image to import.

+

The import command reads the binary image byte-for-byte from the given file-path +into an area of memory in the emulated Apple. You can load into either the motherboard or +a card in one of the slots. For the motherboard, you choose the RAM or ROM area. For a card +in a slot, you can choose either the normal ROM, the bank-switched ROM, or the so-called +“seventh ROM” area.

+

You also have to specify the base address within the specific memory +area at which the image file will be loaded. Note that the base address is specified as the offset +within the specific memory area, and not necessarily as the actual memory address as seen +by the Apple. So for motherboard ROM, for example, specifying a base as 2DED will cause the +image to be loaded at offset 2DED in the ROM, which will be addressed by the Apple at +memory address $FDED (because motherboard ROM “starts” at address $D000).

+

For peripheral cards, the ROM will be seen at locations $Cs00-$CsFF, where s is the slot +number (1 through 7). The “seventh ROM” can be seen as locations $C800-$CFFF; Jim Sather +describes this functionality in +Understanding the Apple II, +on page 6-4, section “The Seventh ROM Chip.” The EPPLE ][ emulator handles this processing correctly. A card can +also have bank-switched ROM, which will show up at addresses $D000-$FFFF when switched in +(stealing that address range from motherboard ROM… see +Understanding the Apple II, +p. 5-26 “The 16K RAM Card”).

+
+
+

load

+

The load command loads a (nibble) floppy disk image into one of the emulated disk drives.

+
+
+
load slot <slot> drive <drive> <file-path>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to load the nibble image into.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to load the nibble image into.

+

<file-path> Path of the nibble floppy disk image to import.

+

The load command will load a nibble image into a disk drive. Specify the slot that +contains a Disk ][ controller peripheral card, and specify which drive number (1 or 2).

+
+ + + +
+Note +The floppy disk image MUST be a NIBBLE DISK IMAGE. +Other formats (for example, DOS order, .do, PRODOS order, +.po, .dsk, or anything else) must first be converted to nibble format. A nibble image contains +all 35 tracks, in order 0-36, each track being 6656 ($1A00) bytes long. Nibble image files +will generally have a filetype of .nib.
+
+

The best floppy disk image conversion tool I’ve found is CiderPress, +for Windows (but it supposedly runs under Wine on Linux, too). Thanks to Andy McFadden.

+
+
+

unload

+

The unload command removes a floppy disk image from one of the emulated disk drives.

+
+
+
unload slot <slot> drive <drive>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to remove the floppy disk image from.

+

The unload command removes the disk from the specified slot and drive.

+
+ + + +
+Warning +If the disk has been modified but not saved, the modifications will be DISCARDED.
+
+
+
+

save

+

The save command saves changes made on an emulated floppy disk back to the original image file.

+
+
+
save slot <slot> drive <drive> <file-path>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to save.

+

<file-path> Path of the nibble floppy disk image to import.

+

The save command saves any changes that the emulated Apple ][ has made to the floppy +disk image. It is important to note that the emulator operates on the image only in memory, and does +not immediately write changes back to the real file. You need to issue the save command +in order to write changes back to the file. Note that the emulator will display a asterisk * +next to the file-name of a disk image if it has any unsaved changes.

+
+
+

cassette

+

The cassette command performs various operations of the emulated cassette tape.

+
+
+
cassette new <file-path>
+cassette load <file-path>
+cassette unload
+cassette rewind
+cassette save
+
+

<file-path> File path of the (special format) cassette tape image file.

+

The cassette command allows the user to control the emulated cassette tape player. +See Cassette for more information about operating the emulated +cassette player and cassette tape image files.

+
+
+

revision

+

The revision command specifies which revision of Apple ][ motherboard to use.

+
+
+
revision <rev>
+
+

<rev> Revision number of the motherboard. Currently, only two values make any difference in behavior: 0 or 1.

+

The revision command chooses which revision of the Apple ][ motherboard to +use. The only revisions that make any difference (for now, at least) are 0 or 1. Zero +is the original (now quite rare) version of the motherboard, that only had two hi-res +colors (green and purple), and always displayed text with green and purple fringes. +Revision 1 and later motherboards are the ones we are more familiar with.

+
+
+
+

Display

+

The orignal Apple ][s didn’t come with a display. The user needed to use either a standard +television, or a monitor, to see the computer’s output. The EPPLE ][ emulates a variety of +displays; you can cycle between the different types using F2. +There are two major types of displays: televisions and monitors. Monitors generally have +higher quality (sharper) displays. The displays show the normal visible area of the NTSC +video signal generated by the emulated Apple ][ machine.

+
+

Monitors

+

The emulator provides a color monitor, and three monochrome monitors (white, green, and orange). +These emulate standard, no-frills NTSC monitors. The most noticeable characteristic of monitors +is the horizontal display of pixels. Monitors react faster than TVs, so two adjacent pixels will +not merge together; both will be distinctly visible, with blackness between them. For example, +type in the following Applesoft command, then cycle through the display types. The monitors +will show thin, vertical, green lines; TVs will show continuous horizontal lines.

+
+
+
GR : COLOR=4 : HLIN 10,20 AT 10
+
+
+
+

Televisions

+

There are two types of television displays, referred to as “old” and “new.” Each has color and +monochrome (commonly known as “black and white”) varieties. Televisions react more slowly to +changes in the incoming video signal than monitors do, and as a result, horizontal pixels will +merge together, forming a more uniform appearance. The “new” color TV display uses the pre-defined +color pallette (described below under “Colors”), and the black and white TV uses the same +pallette, but fully desaturated. The “old” color TV is the most interesting. It emulates the +signal decoding circuitry of a real television. This includes separating out the “chroma” portion +of the incoming NTSC video signal using a filter algorithm, and calculating the color to display. +It does not use the pre-defined colors.

+
+ + + +
+Note +This mode is very CPU intensive, so your computer (that is, the one that EPPLE ][ is running on) +may not be able to run fast enough to run at the speed of the original Apple ][. The Apple ][ CPU +runs at about 1 MHz, but the video generator runs at 14 MHz; so the inner-most loop in the +EPPLE ][ must run 14 million times per second to keep up.
+
+
+
+

Colors

+

The color palatte used for the +color monitor and new color TV is pre-defined, and was determined through observation of a real +Apple ][ machine on a standard TV, the colors being matched by eye. The old color TV, however, +uses algorithms to calculate the colors it displays.

+
+
+

Scan Lines

+

NTSC displays (TVs or monitors) usually receive signals that are interlaced. However, the +Apple ][ doesn’t generate interlaced screens. This causes blank rows between each displayed +row of pixels. The EPPLE ][ emulates this behavior, but also allows you to “fill in” these +black rows with a copy of the row above it, for a more continuous display (vertically). Use +the F4 key to toggle between these two modes.

+
+
+

Resolution

+

The Apple ][s are commonly documented as having a resolution of 280x192 pixels, and to an +extent this is true. Vertically there are 192 pixels, but since there is no interlacing, +it is more accurate to display them with one blank space between each. So the EPPLE ][ has +two times 192, or 384, vertical pixels in its display. Horizontally there are 280 pixels, but +each could also be shifted right one-half dot, allowing for two times 280, or 560, different +horizontal displayable positions. To emulate this, the EPPLE ][ shows each emulated pixel as +two pixels wide, and displays an emulated half-dot shift as an actual one pixel shift. So the +display area of the EPPLE ][ is 560x384. There is an informational area below and to the +right of the emulated display that shows various statistics of the emulator. So the total screen +area used by the EPPLE ][ is a standard 640x480 pixels.

+
+
+

Full Screen

+

The EPPLE ][ can run in either full-screen mode, or within a window. Use the F3 key to toggle +between the two.

+
+
+

Informational Area

+

The area at the bottom and the right of the EPPLE ][ display show various information about +the emulator.

+
    +
  • +

    +POWER light +

    +
    • +
  • +

    +current cards in SLOTS +

    +
    • +
  • +

    +CASSETTE tape information +

    +
    • +
  • +

    +emulated CPU speed (MHz) +

    +
    • +
  • +

    +function-keys help +

    +
    • +
+
+
+
+

Keyboard

+

The EPPLE ][ emulates the original Apple ][ keyboard. The original Apple ][ +keyboard had symbols in different places than current common PC keyboards. For +example, Shift-2 on the Apple ][ produces a double quote, but on a PC keyboard +it produces an at-sign. For ease of typing, the EPPLE ][ emulator does not +mimic the positions of the original keys, but rather mimics the symbols on +the current PC keyboard. So, for example, if you type Shift-2 on the PC +keyboard into the EPPLE ][, it produces an at-sign, as you would normally expect.

+

The Apple ][ keyboard didn’t produce lower-case letters; neither does the emulator. +Also, the Apple couldn’t produce an opening square bracket ([), braces, vertical +bar, backslash. There were no up- or down-arrow keys. You cannot type these into +the emulator, either. There are other, unusual, cases that are emulated correctly, +as well, such as typing Control in conjunction with a number key simply produces +that number. So typing a Control-3 is the same as just typing a 3. Also, typing +Shift-Control-2 produces the NUL character (ASCII $80).

+

The Apple ][ keyboards didn’t automatically repeat typing characters when a +key was held down. Instead, the user would hold down the REPT (“repeat”) key +while holding down the key that was to be repeated. On the EPPLE ][, this +behavior is emulated, and the F10 key is used as the REPT key.

+

The Apple ][ had no keyboard buffer (actually, it had a buffer of one character). +So if you typed several characters on the keyboard before the currently running +program had a chance to read them, they would get lost (only the final character +typed would be remembered). This behavior can be +toggled on or off in the EPPLE ][. By default, the EPPLE ][ will buffer up any +characters you type and deliver them to the emulated machine when it asks for +them. However, the Apple program must be written properly to allow this to work. +Some Apple ][ programs (like maybe some games) may not work correctly in this +respect, so you may want to turn off buffering in these cases. With buffering +turned off, the EPPLE ][ accurately emulates the original Apple ][. Use the F12 +key to toggle the keyboard buffering. Note that pasting from the clipboard (with +the Insert key) will most definitely cause keys to be lost if the keyboard +buffer is turned off. So if you have a big Applesoft program in the clipboard +and you want to paste it into the EPPLE ][ correctly, make sure the keyboard +buffer is on.

+
Special Keys
    +
  • +

    +F1 Emulates the POWER switch on the back of the Apple ][. +

    +
    • +
  • +

    +F2 Cycles among different display types (TV, monitor, etc.). +

    +
    • +
  • +

    +F3 Toggles between full-screen or window display. +

    +
    • +
  • +

    +F4 Toggles between showing scan lines on the display, or duplicating +each scan line to the following line, to fill-in the otherwise black line. +

    +
    • +
  • +

    +F5 Go to “command entry” mode. +

    +
    • +
  • +

    +F10 Emulates the REPT key. +

    +
    • +
  • +

    +F11 Toggles between running the emulator at authentic speed +(1.02 MHz CPU), or as fast as possible. +

    +
    • +
  • +

    +F12 Toggles the keyboard buffer. +

    +
    • +
  • +

    +Break Emulates the RESET key. +

    +
    • +
  • +

    +Insert Pastes characters from the clipboard into the emulated Apple +(as if they had been typed on the keyboard). +

    +
    • +
  • +

    +Print Screen Save a bitmap file of the current EPPLE ][ screen. +The file will be in the default directory, named ep2_YYYYMMDDHHMMSS.bmp. +

    +
    • +
  • +

    +End Quit the EPPLE ][ program, immediately! +

    +
    • +
+
+ + + +
+Warning +If you have modification to any floppy images or cassette images, and you +press the End key, you will LOSE all those changes, unless you +save them first. See Commands for the save command.
+
+
+
+

Peripheral Cards

+
+

Disk ][ Controller

+

The Disk ][ Controller card emulates the floppy disk controller card and associated +disk drives in the original Apple ][ systems. In the emulator, each card has two +drives attached to it, referred to as drive 1 and drive 2. The floppy disks +themselves are represented by a “nibble” image of the contents. The +emulator emulates the hardware, but to be of any use, you will need to provide +the firmware ROM code.

+

To use a disk card and drives, add these lines to your epple2.conf file, for example:

+
+
+
slot 6 disk
+import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.ex65
+
+

The first line uses the slot command to +insert a disk contoller card into slot 6, which is the standard +slot used for disk cards. The next line uses the import +command to load the card’s ROM with the disk controller +firmware. This firmware is known as the “bootstrap” or “P5” ROM code. +It is seen by the Apple ][ at memory addresses $Cs00-$CsFF, where s is the +slot number (so in the common case of the card being in slot 6, the ROM is +at $C600-$C6FF). The firmware is copyright by Apple, and is available from +the Apple II Library.

+

You can also load a floppy disk image (nibble format) into the drive,either by putting +the load command into the epple2.conf file, or by using the command prompt +in the emulator (F5 key). For example, you could load the DOS 3.3 system master into +slot 6, drive 1, with this command

+
+
+
load slot 6 drive 1 /usr/lib/apple2/dos3x/16sector/disks/dos330/clean330sysmas.nib
+
+
+
+

Language

+

The language card emulates an Apple 16K RAM card, commonly called a Language Card. +To use a language card, add this line to your epple2.conf file:

+
+
+
slot 0 language
+
+

Note that DOS and ProDOS will make use of a language card only if it is in slot zero.

+

The language card has RAM at addresses $E000 through $FFFF, as well as two banks of RAM +at addresses $D000 through $DFFF. A program switches between these RAMs and/or the +motherboard ROM by using the I/O switches at $C080 through $C08F.

+

The information area of the Epple ][ will show the current state of the +language card as follows:

+
    +
  • +

    +R Read from card RAM (vs. motherboard ROM) +

    +
    • +
  • +

    +W Write to card RAM (vs. write-disabled) +

    +
    • +
  • +

    +B1 Use $D000 bank 1 +

    +
    • +
  • +

    +B2 Use $D000 bank 2 +

    +
    • +
+

An overview of the I/O switches that control the language card +is provided by Jim Sather in +Understanding the Apple II, +p. 5-30, Table 5.4, as follows:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BANK2 BANK1 ACTION

C080

C088

WRTCOUNT = 0*, WRITE DISABLE

READ ENABLE

C084

C08C

RC081

RC089

WRTCOUNT = WRTCOUNT + 1*

READ DISABLE

RC085

RC08D

WC081

WC089

WRTCOUNT = 0*

READ DISABLE

WC085

WC08D

C082

C08A

WRTCOUNT = 0*, WRITE DISABLE

READ DISABLE

C086

C08E

RC083

RC08B

WRTCOUNT = WRTCOUNT + 1*

READ ENABLE

RC087

RC08F

WC083

WC08B

WRTCOUNT = 0*

READ ENABLE

WC087

WC08F

+

* Writing to expansion RAM is enabled when WRTCOUNT reaches 2.

+
+
+

Firmware

+

The firmware card emulates a (modified) Apple Firmware card. +The firmware card is simply an alternate ROM, at addresses +$D000 through $FFFF, that is switched using the I/O switches +at addresses $C080 through $C08F. In order to make use of the +firmware card, you will need to load the ROM with a binary image +from a file on disk. For example, to insert an Integer BASIC +firmware card into the emulator, add these lines to your +epple2.conf file:

+
+
+
# Firmware card with Integer BASIC and old Monitor
+slot 0 firmware
+import slot 0 rombank 1000 /usr/lib/apple2/system/intbasic/intbasic.ex65
+import slot 0 rombank 2425 /usr/lib/apple2/system/other/other.ex65
+import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2/monitor.ex65
+
+

For an Applesoft BASIC firmware card, use these:

+
+
+
# Firmware card with Applesoft BASIC and Autostart Monitor
+slot 0 firmware
+import slot 0 rombank 0000 /usr/lib/apple2/system/applesoft/applesoft.ex65
+import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2plus/monitor.ex65
+
+

Note that the addresses specified in the epple2.conf file for the +rombank are based on the beginning of the bank ROM itself. For example, specifying +1000 (which is 1000 hex) represents the final memory address of $E000, because +the bank ROM is always based at address $D000.

+

The idea is that you would load your motherboard with, for +example, Applesoft BASIC and the Autostart Monitor ROM (to emulate +an Apple ][ plus), and then install a firmware card with Integer +BASIC and the old Monitor. Booting with DOS 3.3, then, would allow +you to type FP to use Applesoft BASIC, or INT to switch to Integer BASIC.

+

Note that DOS and ProDOS will make use of a firmware card only if it is in slot zero.

+

Jim Sather, in +Understanding the Apple II, +on pages 6-18 through 6-21, explains +how to modify a firmware card to allow independent switching of the $F800-$FFFF +ROM memory. This area is occupied by the Monitor, so it is primarily +intended to allow the user to switch between the old Monitor and the Autostart +Monitor, independent of switching between Integer and Applesoft BASIC. The EPPLE ][ +firmware card emulates this behavior.

+

The information area of the EPPLE ][ will show the current state of the +firmware card as follows:

+
    +
  • +

    +D Read from firmware card $D000-$F7FF (vs. motherboard BASIC ROM) +

    +
    • +
  • +

    +F8 Read from firmware card $F800-$FFFF (vs. motherboard Monitor ROM) +

    +
    • +
+
+
+

Clock

+

The clock card emulates a ProDOS-compatible real-time clock card for the Apple ][. +To use a clock card, you will need to configure the EPPLE ][ to insert one into +a slot, typically slot 4. You will also need to load the card with its ROM code, +which is provided with the emulator in the clock.ex65 file. +For example, add this to your epple2.conf file:

+
+
+
slot 4 clock
+import slot 4 rom 0 /usr/lib/epple2/cards/clock.ex65
+
+

Of course you may need to adjust the path for your particular system.

+

To verify that the clock card is working correctly, you can run the following Applesoft +program to retrieve the current time from the clock card and print it. +This program assumes the card is in slot 4.

+
+
+
NEW
+
+10 CALL -15360 : REM $C400 SLOT 4 ENTRY POINT
+20 A = 512 : REM $0200 INPUT BUFFER
+30 C = PEEK(A)
+40 IF C < 160 THEN 99
+50 PRINT CHR$(C);
+60 A = A+1
+70 GOTO 30
+99 END
+
+RUN
+

The card returns data (into the GETLN input buffer at $200) in +the following format:

+

mm,ww,dd,hh,nn,ss,000,yyyy,Time Zone,v

+
    +
  • +

    +mm Month, 01-12 +

    +
    • +
  • +

    +ww Weekday, 00=Monday… 06=Saturday +

    +
    • +
  • +

    +dd Day, 01-31 +

    +
    • +
  • +

    +hh Hour, 00-23 +

    +
    • +
  • +

    +nn Minute, 00-59 +

    +
    • +
  • +

    +ss Second, 00-61 +

    +
    • +
  • +

    +000 Milliseconds; always zero +

    +
    • +
  • +

    +yyyy Year, e.g., 2008 +

    +
    • +
  • +

    +Time Zone time zone string (could contain lower-case characters, + which won’t display correctly) +

    +
    • +
  • +

    +v Daylight Saving Time in effect, 0=no, 1=yes +

    +
    • +
+

Note that only mm,ww,dd,hh,nn fields are used by ProDOS. The other +fields, ss,000,yyyy,Time Zone,v, are an EPPLE ][ extension. Also note +that ProDOS was not designed to work for years past 2007, so +ProDOS will show the incorrect year, but the other fields will be accurate. +I believe patches exist for ProDOS to fix this.

+
+
+

Standard Input

+

The “standard input” card doesn’t emulate a real piece of hardware; rather, it +reads characters from standard input (stdin) (of the EPPLE ][ emulator).

+

To use a standard input card, add these lines to your epple2.conf file:

+
+
+
# IN#2 reads from standard input
+slot 2 stdin
+import slot 2 rom 0 /usr/lib/epple2/cards/stdin.ex65
+
+

That will insert a stdin card into slot 2, and then load its +ROM image into the card. +The stdin ROM is provided with the EPPLE ][ distribution.

+

For example, if you have a stdin card installed in slot 2, start +the EPPLE ][ emulator from the command line, and at the Applesoft +prompt, type IN#2. Then you can switch back to the +command shell, and whatever you type will be fed into the emulated +Apple. Use RESET or IN#0 to go back to normal.

+
+
+

Standard Output

+

The “standard output” card doesn’t emulate a real piece of hardware; rather, it acts +similar to a printer card, but instead of sending characters to a printer, it sends +them to standard output (stdout) (of the EPPLE ][ emulator).

+

To use a standard output card, add these lines to your epple2.conf file:

+
+
+
# PR#1 prints to standard output
+slot 1 stdout
+import slot 1 rom 0 /usr/lib/epple2/cards/stdout.ex65
+
+

This will insert a stdout card into slot 1 (which is the typical +slot for a printer card), and then load its ROM image into the card. +The stdout ROM is provided with the EPPLE ][ distribution.

+

For example, if you have a stdout card installed, at the Applesoft +prompt, type PR#1. Whatever you type next will be +echoed to standard output. Type PR#0 to stop echoing.

+
+
+
+

Cassette Tape Interface

+

The Apple ][ and Apple ][ plus machines had the ability to save and load binary +data to and from cassette tape. The user would attach a standard cassette tape +recorder to the jacks on the back of the Apple ][, and use the monitor R and W +commands, or the Applesoft BASIC commands LOAD and SAVE, to read and write data +on the cassette tape. The user would have to press the play and/or record buttons +on the player at the right time.

+

The Epple ][ emulates the cassette interface, using a file to hold the +recorded portion of the tape. The file will grow in length as necessary +to hold data that the emulated Apple is writing to the “tape.” +The emulator will not overwrite existing data on a tape image. +The emulator will automatically “press” the play or record buttons that +would have been necessary when using the original machine.

+
+

Commands

+

cassette new <file-path>

+

This creates a new empty file (on the host computer) that represents a cassette tape image. +The file must not already exist.

+

cassette load <file-path>

+

This loads an existing file (from the host computer) containing a cassette tape image. +The tape is automatically positioned at its beginning (fully rewound).

+

cassette unload

+

This removes the file from the cassette tape. Note that you must manually save +the file using the cassette save command (described below).

+
+ + + +
+Warning +Unloading an unsaved file will lose any changes made to the file, without warning.
+
+

cassette rewind

+

This command “rewinds” the cassette tape, positioning it at the beginning +of the tape (for subsequent reading). You do not need to rewind the tape +before saving or unloading it, of course.

+

cassette save

+

This command saves the changed tape to the file. Note that the display will show +an asterisk * next to the file name if there are unsaved changes that need to +be saved. Unsaved changes will be lost without warning if the file is unloaded +or if you quit the program.

+
+
+

Example of Saving to Tape

+

Start up the emulator with Applesoft ROMs for this tutorial. +Enter a simple Applesoft program, just as an example, that we +are going to save to a cassette tape image file.

+
+
+
]NEW
+
+]10 PRINT "HELLO"
+
+]20 END
+
+]LIST
+
+10  PRINT "HELLO"
+20  END
+
+]RUN
+HELLO
+
+]
+

We first need to load a tape image file into the cassette machine. +Enter command mode by pressing F5, then make a new tape +image file.

+
+
+
command: cassette new hello.tap
+
+

This will create a new, empty tape file image named hello.tap +in the current default directory. (We could have specified a full path +name for the file if we wanted to place it in a different directory.) +Notice that the emulator now displays the name of the tape image file, +along with the position and length of the tape image, which is now 0/0.

+

Next, we tell Applesoft to save the program to the cassette. For this, +we just use the SAVE command. Note that this is not the +DOS SAVE command; the DOS command has a file name after +SAVE. We just use SAVE with no file name.

+
+
+
]SAVE
+
+]
+
+

It will take 10 seconds or so for it to save. Notice that the +current position of the tape is counting up as the Apple saves +the program. When it is finished, you need to save the changes +to the file. Press F5 and enter the emulator command to save +the tape image file.

+
+
+
command: cassette save
+
+

We can now unload the file from the emulator (which is like ejecting +the tape from the cassette player).

+
+
+
command: cassette unload
+
+
+
+

Example of Loading from Tape

+

To load the saved program (from the previous section) into the Apple again, +we will need to first load the tape image file back into the cassette machine. +Press F5 to enter command mode and load the image file.

+
+
+
command: cassette load hello.tap
+
+

This will load hello.tap (in the current default directory). Notice the +emulator now displays the name of the tape image file, along with the +position and length of the tape image, which in this case is 0/33481.

+

Next, we tell Applesoft to load the program from the cassette. For this, +we just use the LOAD command. Note that this is not the +DOS LOAD command; the DOS command has a file name after +LOAD. We just use LOAD with no file name.

+
+
+
]LOAD
+
+]
+
+

It will take 10 seconds or so for it to load. Notice that the +current position of the tape is counting up as the Apple loads +the program. When it is finished, the program will be loaded.

+
+
+
]LIST
+
+10  PRINT "HELLO"
+20  END
+
+]RUN
+HELLO
+
+]
+
+
+

Tape Image File Format

+

The format of the tape image file is unique to the Epple ][ +It is stored in a low-level format that represents the waveform that the Apple writes +to the cassette tape.

+

The file is a binary format. Each byte in the file represents the length of one half of one cycle +(of voltage level variation) written to the tape. The length is in 10-microsecond units.

+

For example, a tape image file might have the following binary bytes (in decimal): +65 65 65 65 65 20 25 50 50 25 25 25 25 50 50 +Since each byte represents a 10-microsecond unit, these bytes represent the following +half-cycle lengths in microseconds: +650 650 650 650 650 200 250 500 500 250 250 250 250 500 500 +The meaning of these half-cycle lengths to the Apple is as follows:

+
+
+
|-------HEADER------|--sync-|-1-bit-|-0-bit-|-0-bit-|-1-bit-|
+|                   |       |       |       |       |       |
+|650 650 650 650 650|200 250|500 500|250 250|250 250|500 500|
+
+

where HEADER is a header section the Apple writes (to skip any +unrecordable leader section on a real cassette tape); sync is a +synchronization cycle; and the subsequent cycles are the actual +bits of data saved on the tape. A 500-microsecond cycle (which +is stored in the file as two 250 microsecond half-cycles) +represents a zero bit, and a 1-millisecond cycle (which is +stored in the file as two 500 microsecond half-cycles) +represents a one bit.

+
+
+
+

Paddles

+

The Epple ][ provides two paddles to the Apple ][ machine. +One paddle is controlled by moving the mouse left and right; the other +paddle is controlled by moving the mouse up and down. The paddle buttons +are emulated by the mouse buttons (left and right click).

+

In +Understanding the Apple II, +on page 7-33, Jim Sather describes soldering fixed resistors across a game connector +to create two real-time clock references. This is emulated by the Epple ][. Paddle timers 2 and 3 +are 100-microsecond and 1-millisecond references, respectively.

+
+
+

Speaker

+

The Apple ][ could generate sound via a speaker that generated square wave +audio. A program could read memory location $C030 to toggle the speaker and +generate a “click” sound.

+

The Epple ][ emulator will generate sounds from the emulated Apple and +send them to the audio device. It generates 8-bit mono sound, with a 22,050 Hz +sampling rate.

+
+
+
+
+

Building From Source

+
+

The Epple ][ Emulator is written in C++, and can be built +using the standard make program.

+

The primary dependency is +Simple DirectMedia Layer (SDL). +Your linux distribution may provide a package. Or else +you can download it directly from SDL’s web site. In +either case, be sure to install the “Development Libraries” +for your particular platform.

+
+

Debian Linux Example

+
+
+
sudo apt-get install build-essential libsdl1.2-dev  # 1
+cd
+mkdir epple2
+cd epple2
+wget http://mosher.mine.nu/epple2/download/epple2-latest.tar.gz  # 2
+tar xzvf epple2-1.0.tar.gz
+mkdir build  # 3
+cd build
+../epple2-1.0/configure  # 4
+make  # 5
+sudo make install  # 6
+
+ + + + + + +
1 +Install dependencies: gcc, make, SDL +
2 +Retrieve the latest Epple ][ source distribution +
3 +Use this directory for a VPATH-style build +
4 +Run one-time configuration script for your system. Use --help for more information. +
5 +Compile and link. Program will be src/epple2 +
6 +Install into standard system directories +
+
+
+

Windows/MSYS Example

+
+

Install MinGW/MSYS

+

Install MSYS into C:\msys\

+

Install MinGW into C:\msys\mingw\

+

For more information on MinGW and MSYS, see http://www.mingw.org/.

+
+
+

Install SDL

+

At http://www.libsdl.org/ find the download page. +Download the “Development Libraries” for Win32/mingw, for example:

+

SDL-devel-1.2.13-mingw32.tar.gz (Mingw32)

+

and save it to your MSYS home directory (for example, C:\msys\home\Administrator). +Run MSYS, and at the bash prompt, go to your home directory and +untar the SDL archive to your home directory:

+
+
+
$ cd
+$ tar xzvf SDL-devel-1.2.13-mingw32.tar.gz
+

Then follow the instructions to install SDL, for example:

+
+
+
$ cd SDL-1.2.13
+$ make native
+
+
+

Untar Epple ][ Source

+

Download the Epple ][ Source Distribution +and save it to your MSYS home directory (for example, C:\msys\home\Administrator). +Run MSYS, and at the bash prompt, go to your home directory and +untar the epple2 source distribution tar file. For example:

+
+
+
$ cd
+$ tar xzvf epple2-1.0.tar.gz
+
+
+

Build Epple ][

+

Then build as follows. I recommend doing a VPATH build, +where you build into a different directory than the source +directory. To accomplish this, create a new directory for +building, somewhere, such as:

+
+
+
$ cd
+$ mkdir buildepple2
+$ cd buildepple2
+

Then run configure from there. For the MSYS build to work, +you need some extra parameters to the build, and you could +also add some compiler options to optimize the build. For +example (from the buildepple2 directory you just created):

+
+
+
$ ~/epple2/configure --prefix= \
+CXXFLAGS="-I/usr/include -O4 -msse3" \
+CFLAGS="-I/usr/include" \
+LDFLAGS="-L/usr/lib -mconsole -mthreads -mno-cygwin"
+$ make
+

If all goes well, it will build without any errors. +If you get errors about not finding SDL.h, make sure +SDL is installed, and make sure the configure command +is correct. (If you just run configure without the +options shown above, you will get this error at build time.) +The result of the build (on Windows platform) is

+

installer/epple2.msi

+

which is an installable file for Windows. To install +epple2, just double-click on this file from Explorer.

+
+

Copyright © 2009,2012, by +Christopher A. Mosher, +Shelton CT, USA.

+

+Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License +

+

This web site is licensed under the +Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License.

+
+
+
+
+
+
+ + + diff --git a/doc/deploy/make.png b/doc/deploy/make.png new file mode 100644 index 0000000..a995a80 Binary files /dev/null and b/doc/deploy/make.png differ diff --git a/doc/deploy/note.png b/doc/deploy/note.png new file mode 100644 index 0000000..7c1f3e2 Binary files /dev/null and b/doc/deploy/note.png differ diff --git a/doc/deploy/pinkmystery.png b/doc/deploy/pinkmystery.png new file mode 100644 index 0000000..85274da Binary files /dev/null and b/doc/deploy/pinkmystery.png differ diff --git a/doc/deploy/prodos.png b/doc/deploy/prodos.png new file mode 100644 index 0000000..4e6f59a Binary files /dev/null and b/doc/deploy/prodos.png differ diff --git a/doc/deploy/redhat.png b/doc/deploy/redhat.png new file mode 100644 index 0000000..a98a44b Binary files /dev/null and b/doc/deploy/redhat.png differ diff --git a/doc/deploy/splitcolors.png b/doc/deploy/splitcolors.png new file mode 100644 index 0000000..e549342 Binary files /dev/null and b/doc/deploy/splitcolors.png differ diff --git a/doc/deploy/tip.png b/doc/deploy/tip.png new file mode 100644 index 0000000..f087c73 Binary files /dev/null and b/doc/deploy/tip.png differ diff --git a/doc/deploy/warning.png b/doc/deploy/warning.png new file mode 100644 index 0000000..d41edb9 Binary files /dev/null and b/doc/deploy/warning.png differ diff --git a/doc/deploy/windows.gif b/doc/deploy/windows.gif new file mode 100644 index 0000000..626108d Binary files /dev/null and b/doc/deploy/windows.gif differ diff --git a/doc/display.asciidoc b/doc/display.asciidoc new file mode 100644 index 0000000..bebc647 --- /dev/null +++ b/doc/display.asciidoc @@ -0,0 +1,83 @@ +=== Display + +The orignal Apple ][s didn't come with a display. The user needed to use either a standard +television, or a monitor, to see the computer's output. The EPPLE ][ emulates a variety of +displays; you can cycle between the different types using +F2+. +There are two major types of displays: televisions and monitors. Monitors generally have +higher quality (sharper) displays. The displays show the normal visible area of the NTSC +video signal generated by the emulated Apple ][ machine. + +==== Monitors + +The emulator provides a color monitor, and three monochrome monitors (white, green, and orange). +These emulate standard, no-frills NTSC monitors. The most noticeable characteristic of monitors +is the horizontal display of pixels. Monitors react faster than TVs, so two adjacent pixels will +not merge together; both will be distinctly visible, with blackness between them. For example, +type in the following Applesoft command, then cycle through the display types. The monitors +will show thin, vertical, green lines; TVs will show continuous horizontal lines. + +-------- +GR : COLOR=4 : HLIN 10,20 AT 10 +-------- + +==== Televisions + +There are two types of television displays, referred to as ``old'' and ``new.'' Each has color and +monochrome (commonly known as ``black and white'') varieties. Televisions react more slowly to +changes in the incoming video signal than monitors do, and as a result, horizontal pixels will +merge together, forming a more uniform appearance. The ``new'' color TV display uses the pre-defined +color pallette (described below under ``Colors''), and the black and white TV uses the same +pallette, but fully desaturated. The ``old'' color TV is the most interesting. It emulates the +signal decoding circuitry of a real television. This includes separating out the ``chroma'' portion +of the incoming NTSC video signal using a filter algorithm, and _calculating_ the color to display. +It does not use the pre-defined colors. + +[NOTE] +This mode is very CPU intensive, so your computer (that is, the one that EPPLE ][ is running on) +may not be able to run fast enough to run at the speed of the original Apple ][. The Apple ][ CPU +runs at about 1 MHz, but the video generator runs at 14 MHz; so the inner-most loop in the +EPPLE ][ must run 14 million times per second to keep up. + +==== Colors + +The color palatte used for the +color monitor and new color TV is pre-defined, and was determined through observation of a real +Apple ][ machine on a standard TV, the colors being matched by eye. The old color TV, however, +uses _algorithms_ to calculate the colors it displays. + +==== Scan Lines + +NTSC displays (TVs or monitors) usually receive signals that are interlaced. However, the +Apple ][ doesn't generate interlaced screens. This causes blank rows between each displayed +row of pixels. The EPPLE ][ emulates this behavior, but also allows you to ``fill in'' these +black rows with a copy of the row above it, for a more continuous display (vertically). Use +the F4 key to toggle between these two modes. + +==== Resolution + +The Apple ][s are commonly documented as having a resolution of 280x192 pixels, and to an +extent this is true. Vertically there are 192 pixels, but since there is no interlacing, +it is more accurate to display them with one blank space between each. So the EPPLE ][ has +two times 192, or 384, vertical pixels in its display. Horizontally there are 280 pixels, but +each could also be shifted right one-half dot, allowing for two times 280, or 560, different +horizontal displayable positions. To emulate this, the EPPLE ][ shows each emulated pixel as +two pixels wide, and displays an emulated half-dot shift as an actual one pixel shift. So the +display area of the EPPLE ][ is 560x384. There is an informational area below and to the +right of the emulated display that shows various statistics of the emulator. So the total screen +area used by the EPPLE ][ is a standard 640x480 pixels. + +==== Full Screen + +The EPPLE ][ can run in either full-screen mode, or within a window. Use the +F3+ key to toggle +between the two. + +==== Informational Area + +The area at the bottom and the right of the EPPLE ][ display show various information about +the emulator. + +* POWER light +* current cards in SLOTS +* CASSETTE tape information +* emulated CPU speed (MHz) +* function-keys help diff --git a/doc/dos310rev0.png b/doc/dos310rev0.png new file mode 100644 index 0000000..a393a6a Binary files /dev/null and b/doc/dos310rev0.png differ diff --git a/doc/dos330boot.png b/doc/dos330boot.png new file mode 100644 index 0000000..d8c768e Binary files /dev/null and b/doc/dos330boot.png differ diff --git a/doc/download.asciidoc b/doc/download.asciidoc new file mode 100644 index 0000000..eef1548 --- /dev/null +++ b/doc/download.asciidoc @@ -0,0 +1,75 @@ +== Download + +[TIP] +Usable Apple ROMs (proprietary +footnoteref:[disclaimer,You must +respect the fact that the Apple +System Software and +Apple Disk Operating System (DOS) Software are +_proprietary_ software; they are copyright by Apple and/or others. This web page is not +providing any advice as to the legality of any copying or downloading you may perform. +]) +are available at the http://mosher.mine.nu/apple2/[Apple II Library]. + +The following software is licensed under +http://www.gnu.org/licenses/gpl-3.0-standalone.html[GPLv3]. + +Epple ][ Program: http://mosher.mine.nu/epple2/download/epple2-latest.tar.gz[epple2.tar.gz] + +System ROM (Demo): http://mosher.mine.nu/epple2/download/epple2sys-latest.tar.gz[epple2sys.tar.gz] + +Card ROMs (stdin/stdout/clock): http://mosher.mine.nu/epple2/download/epple2cards-latest.tar.gz[epple2cards.tar.gz] + +See <<_building_from_source,Building>> to build from sources. + + + +== What To Download + +=== Epple ][ Program—The Hardware (Emulated) + +The _Epple ][ Program_ package is the emulator itself, which emulates the +Apple ][ or Apple ][ plus _hardware_, as well as the +<> hardware. This is the main program, so you will +certainly need to download this package. To have a full functioning emulator, +you will also need System ROMs and Card ROMs, as described in the following +sections. + +[[firmware]] +=== System ROMs—The Main System Firmware (Demo or Real) + +Since the Epple ][ program emulates only the hardware, you will also need to download some _system software_ +for it to run. This is commonly called ``firmware'' or ``ROMs,'' because it is stored in the +read-only memory area of the emulated system. The original system software on the +Apple ][ machines is copyright by Apple, and is proprietary. If you own an actual +Apple ][ or Apple ][ plus machine, you can copy footnoteref:[disclaimer] the firmware +from it ($D000-$FFFF) (into a file on your PC) and use it. Alternatively, you can +download footnoteref:[disclaimer] the firmware images from the http://mosher.mine.nu/apple2/[Apple II Library]. + +If you do not want to download the proprietary firmware, you can still use the emulator (albeit +in a restricted manner) with the free (GPLv3) _System ROM (Demo)_ package. Download +the file for your platform and +install as appropriate. You can choose either binary format (ready to run), or source if you want +to assemble it yourself (using the http://www.floodgap.com/retrotech/xa/[xa Assembler]). +The Demo System ROM only provides commands to dump or set memory bytes, +or run a program in memory. It is not compatible with any Apple software, nor can it read from disks. +It's just a free simple demo system to make the emulator do something reasonable. + +=== Card ROMs—The Peripheral Card Firmware + +If you are going to use the Disk ][ Controller peripheral card (which you almost certainly will, if +you want to read any floppy disk images), you will need to have to original ROMs from Apple. +No demo of the Disk ROMs are provided here; you will need to +use the original ROMs, which can be obtained from an original machine (by copying footnoteref:[disclaimer] +it from $C600-$C6FF into a file on the PC), or by downloading footnoteref:[disclaimer] it +from the http://mosher.mine.nu/apple2/[Apple II Library]. +(And, of course, you will need the real Apple System ROM, as noted in the previous section, +not the Demo System ROM.) + +If you are using any of the clock, the standard output, or the +standard input <>, you will need to download their firmware as well, +which are contained in the _Card ROMs_ package. You can choose either binary format +(ready to run) or source format (to assemble it yourself(using the +http://www.floodgap.com/retrotech/xa/[xa Assembler]). +If you are _not_ going to use the stdin, stdout, or clock +cards, then you do not need to download this package. diff --git a/doc/epple2logo.png b/doc/epple2logo.png new file mode 100644 index 0000000..ebaf135 Binary files /dev/null and b/doc/epple2logo.png differ diff --git a/doc/gplv3logo.png b/doc/gplv3logo.png new file mode 100644 index 0000000..b06e043 Binary files /dev/null and b/doc/gplv3logo.png differ diff --git a/doc/index.asciidoc b/doc/index.asciidoc new file mode 100644 index 0000000..86ead8c --- /dev/null +++ b/doc/index.asciidoc @@ -0,0 +1,61 @@ +Epple ][ +======== +Chris Mosher +:icons: +:iconsdir: . +:toclevels: 3 +:toc2: + +image::epple2logo.png[] + +== Introduction + +Epple ][ is an emulator of the original APPLE ][ and APPLE ][ PLUS +computers from http://www.apple.com/[Apple, Inc.] It +runs on Windows and Linux platforms, and is released under +http://www.gnu.org/licenses/gpl-3.0-standalone.html[GPLv3] +image:gplv3logo.png[GPLv3] + +It is written in C++ and is designed with cross-platform +portability in mind. It uses the http://www.libsdl.org/[SDL] graphics library. + + + +== Features + +* Cycle-accurate: emulates all MOS 6502 CPU cycles including ``phantom reads'' +* Video display is synchronized with CPU +* NTSC video signal emulation: all video quirks emulated accurately +* Revision 0 motherboard (optional) +* Multiple display types: monitor and TV emulation +* Can run full-screen or in a window +* 640x480 resolution +* Floating data bus, and video scanner +* Cards: Disk ][, language, firmware, clock +* Paddles (mouse emulates two paddles) +* Cassette tape interface +* PR#1 writes to standard output +* Accurate keyboard emulation, including the repeat key +* It even emulates the POWER light! + +include::screenshots.asciidoc[] + +include::download.asciidoc[] + +include::configuration.asciidoc[] + +include::usermanual.asciidoc[] + +include::building.asciidoc[] + + +'''' + +[small]#Copyright (C) 2009,2012, by +mailto:chris-keyword-epple2.4a8db3@mosher.mine.nu[Christopher A. Mosher], +Shelton CT, USA.# + +image:80x15.png[Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License] + +[small]#This web site is licensed under the +http://creativecommons.org/licenses/by-nc-sa/3.0/us/[Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License].# diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..98a2127 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,2325 @@ + + + + + +Epple ][ + + + + + +
+
+
+
+
+epple2logo.png +
+
+
+
+
+

Introduction

+
+

Epple ][ is an emulator of the original APPLE ][ and APPLE ][ PLUS +computers from Apple, Inc. It +runs on Windows and Linux platforms, and is released under +GPLv3 + +GPLv3 +

+

It is written in C++ and is designed with cross-platform +portability in mind. It uses the SDL graphics library.

+
+
+
+

Features

+
+
    +
  • +

    +Cycle-accurate: emulates all MOS 6502 CPU cycles including “phantom reads” +

    +
    • +
  • +

    +Video display is synchronized with CPU +

    +
    • +
  • +

    +NTSC video signal emulation: all video quirks emulated accurately +

    +
    • +
  • +

    +Revision 0 motherboard (optional) +

    +
    • +
  • +

    +Multiple display types: monitor and TV emulation +

    +
    • +
  • +

    +Can run full-screen or in a window +

    +
    • +
  • +

    +640x480 resolution +

    +
    • +
  • +

    +Floating data bus, and video scanner +

    +
    • +
  • +

    +Cards: Disk ][, language, firmware, clock +

    +
    • +
  • +

    +Paddles (mouse emulates two paddles) +

    +
    • +
  • +

    +Cassette tape interface +

    +
    • +
  • +

    +PR#1 writes to standard output +

    +
    • +
  • +

    +Accurate keyboard emulation, including the repeat key +

    +
    • +
  • +

    +It even emulates the POWER light! +

    +
    • +
+
+
+
+

Screenshots

+
+
+

DOS 3.3 System Master boot

+
+
+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

+
+
+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 HIRES 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 HIRES colors, blue and orange, were also added in +later revisions.

+
+
+

PRODOS 1.1.1 boot

+
+
+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

+
+
+applesplit.png +
+
+

The October 1982 issue of Softalk +featured an article by Bob Bishop entitled +Have an Apple Split, 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 ][.

+
+
+
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

+
+
+pinkmystery.png +
+
+

Jim Sather’s book +Understanding the Apple II, +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.

+
+
+
NEW
+
+10 HGR : HCOLOR = 5 : HPLOT 5,159 TO 5,0 TO 279,0 TO 279,159
+
+RUN
+
+
+

Split Screen HIRES/LORES colors

+
+
+splitcolors.png +
+
+

Jim Sather’s book +Understanding the Apple II, +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.

+
+
+
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
+
+
+
+
+

Download

+
+
+ + + +
+Tip +Usable Apple ROMs (proprietary +
[You must respect the fact that the Apple System Software and Apple Disk Operating System (DOS) Software are proprietary software; they are copyright by Apple and/or others. This web page is not providing any advice as to the legality of any copying or downloading you may perform.]
) +are available at the Apple II Library.
+
+

The following software is licensed under +GPLv3.

+

Epple ][ Program: epple2.tar.gz

+

System ROM (Demo): epple2sys.tar.gz

+

Card ROMs (stdin/stdout/clock): epple2cards.tar.gz

+

See Building to build from sources.

+
+
+
+

What To Download

+
+
+

Epple ][ Program—The Hardware (Emulated)

+

The Epple ][ Program package is the emulator itself, which emulates the +Apple ][ or Apple ][ plus hardware, as well as the +peripheral card hardware. This is the main program, so you will +certainly need to download this package. To have a full functioning emulator, +you will also need System ROMs and Card ROMs, as described in the following +sections.

+
+
+

System ROMs—The Main System Firmware (Demo or Real)

+

Since the Epple ][ program emulates only the hardware, you will also need to download some system software +for it to run. This is commonly called “firmware” or “ROMs,” because it is stored in the +read-only memory area of the emulated system. The original system software on the +Apple ][ machines is copyright by Apple, and is proprietary. If you own an actual +Apple ][ or Apple ][ plus machine, you can copy
[disclaimer]
 the firmware +from it ($D000-$FFFF) (into a file on your PC) and use it. Alternatively, you can +download
[disclaimer]
 the firmware images from the Apple II Library.

+

If you do not want to download the proprietary firmware, you can still use the emulator (albeit +in a restricted manner) with the free (GPLv3) System ROM (Demo) package. Download +the file for your platform and +install as appropriate. You can choose either binary format (ready to run), or source if you want +to assemble it yourself (using the xa Assembler). +The Demo System ROM only provides commands to dump or set memory bytes, +or run a program in memory. It is not compatible with any Apple software, nor can it read from disks. +It’s just a free simple demo system to make the emulator do something reasonable.

+
+
+

Card ROMs—The Peripheral Card Firmware

+

If you are going to use the Disk ][ Controller peripheral card (which you almost certainly will, if +you want to read any floppy disk images), you will need to have to original ROMs from Apple. +No demo of the Disk ROMs are provided here; you will need to +use the original ROMs, which can be obtained from an original machine (by copying
[disclaimer]
 +it from $C600-$C6FF into a file on the PC), or by downloading
[disclaimer]
 it +from the Apple II Library. +(And, of course, you will need the real Apple System ROM, as noted in the previous section, +not the Demo System ROM.)

+

If you are using any of the clock, the standard output, or the +standard input peripheral cards, you will need to download their firmware as well, +which are contained in the Card ROMs package. You can choose either binary format +(ready to run) or source format (to assemble it yourself(using the +xa Assembler). +If you are not going to use the stdin, stdout, or clock +cards, then you do not need to download this package.

+
+
+
+
+

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. +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 above. +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 on the peripheral 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.

+
+
+
+
+

User Manual

+
+
+

Overview

+

Epple ][ (the Emulated Apple ][ is a free (as in GPLv3), cross-platform +(Windows, Linux) emulator of the Apple ][ and Apple ][ plus computers +from Apple, Inc. It strives for accurate emulation of the original machines, +with a few extra features added.

+
+
+

Commands

+

slot import load unload save cassette revision

+
+

slot

+

The slot command inserts a card into a peripheral slot of the emulated Apple.

+
+
+
slot <slot> <card>
+
+

<slot> Slot number, 0 through 7, to insert the card into.

+

<card> The type of card to insert into the slot:

+
    +
  • +

    +language +

    +
    • +
  • +

    +firmware +

    +
    • +
  • +

    +disk +

    +
    • +
  • +

    +clock +

    +
    • +
  • +

    +stdout +

    +
    • +
  • +

    +stdin +

    +
    • +
  • +

    +empty +

    +
    • +
+

The slot command inserts a card into a peripheral slot. For example:

+
+
+
slot 0 language
+
+

inserts a language card into slot zero. Use empty to remove a card:

+
+
+
slot 0 empty
+
+
+ + + +
+Note +The emulated Apple should be powered off before inserting or removing cards.
+
+
+
+

import

+

The import command imports a binary image file into the emulated Apple’s memory.

+
+
+
import slot <slot> { rom | rom7 | rombank } <base> <file-path>
+import motherboard { rom | ram } <base> <file-path>
+
+

<slot> Slot number, 0 through 7, of peripheral card to import the binary image into.

+

<base> Base address in hexadecimal within the given memory area at which to start loading the binary image.

+

<file-path> Path of the binary image to import.

+

The import command reads the binary image byte-for-byte from the given file-path +into an area of memory in the emulated Apple. You can load into either the motherboard or +a card in one of the slots. For the motherboard, you choose the RAM or ROM area. For a card +in a slot, you can choose either the normal ROM, the bank-switched ROM, or the so-called +“seventh ROM” area.

+

You also have to specify the base address within the specific memory +area at which the image file will be loaded. Note that the base address is specified as the offset +within the specific memory area, and not necessarily as the actual memory address as seen +by the Apple. So for motherboard ROM, for example, specifying a base as 2DED will cause the +image to be loaded at offset 2DED in the ROM, which will be addressed by the Apple at +memory address $FDED (because motherboard ROM “starts” at address $D000).

+

For peripheral cards, the ROM will be seen at locations $Cs00-$CsFF, where s is the slot +number (1 through 7). The “seventh ROM” can be seen as locations $C800-$CFFF; Jim Sather +describes this functionality in +Understanding the Apple II, +on page 6-4, section “The Seventh ROM Chip.” The EPPLE ][ emulator handles this processing correctly. A card can +also have bank-switched ROM, which will show up at addresses $D000-$FFFF when switched in +(stealing that address range from motherboard ROM… see +Understanding the Apple II, +p. 5-26 “The 16K RAM Card”).

+
+
+

load

+

The load command loads a (nibble) floppy disk image into one of the emulated disk drives.

+
+
+
load slot <slot> drive <drive> <file-path>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to load the nibble image into.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to load the nibble image into.

+

<file-path> Path of the nibble floppy disk image to import.

+

The load command will load a nibble image into a disk drive. Specify the slot that +contains a Disk ][ controller peripheral card, and specify which drive number (1 or 2).

+
+ + + +
+Note +The floppy disk image MUST be a NIBBLE DISK IMAGE. +Other formats (for example, DOS order, .do, PRODOS order, +.po, .dsk, or anything else) must first be converted to nibble format. A nibble image contains +all 35 tracks, in order 0-36, each track being 6656 ($1A00) bytes long. Nibble image files +will generally have a filetype of .nib.
+
+

The best floppy disk image conversion tool I’ve found is CiderPress, +for Windows (but it supposedly runs under Wine on Linux, too). Thanks to Andy McFadden.

+
+
+

unload

+

The unload command removes a floppy disk image from one of the emulated disk drives.

+
+
+
unload slot <slot> drive <drive>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to remove the floppy disk image from.

+

The unload command removes the disk from the specified slot and drive.

+
+ + + +
+Warning +If the disk has been modified but not saved, the modifications will be DISCARDED.
+
+
+
+

save

+

The save command saves changes made on an emulated floppy disk back to the original image file.

+
+
+
save slot <slot> drive <drive> <file-path>
+
+

<slot> Slot number, 0 through 7, of Disk ][ controller card to which the drive is attached.

+

<drive> Drive number, 1 or 2, of the disk drive on the controller card to save.

+

<file-path> Path of the nibble floppy disk image to import.

+

The save command saves any changes that the emulated Apple ][ has made to the floppy +disk image. It is important to note that the emulator operates on the image only in memory, and does +not immediately write changes back to the real file. You need to issue the save command +in order to write changes back to the file. Note that the emulator will display a asterisk * +next to the file-name of a disk image if it has any unsaved changes.

+
+
+

cassette

+

The cassette command performs various operations of the emulated cassette tape.

+
+
+
cassette new <file-path>
+cassette load <file-path>
+cassette unload
+cassette rewind
+cassette save
+
+

<file-path> File path of the (special format) cassette tape image file.

+

The cassette command allows the user to control the emulated cassette tape player. +See Cassette for more information about operating the emulated +cassette player and cassette tape image files.

+
+
+

revision

+

The revision command specifies which revision of Apple ][ motherboard to use.

+
+
+
revision <rev>
+
+

<rev> Revision number of the motherboard. Currently, only two values make any difference in behavior: 0 or 1.

+

The revision command chooses which revision of the Apple ][ motherboard to +use. The only revisions that make any difference (for now, at least) are 0 or 1. Zero +is the original (now quite rare) version of the motherboard, that only had two hi-res +colors (green and purple), and always displayed text with green and purple fringes. +Revision 1 and later motherboards are the ones we are more familiar with.

+
+
+
+

Display

+

The orignal Apple ][s didn’t come with a display. The user needed to use either a standard +television, or a monitor, to see the computer’s output. The EPPLE ][ emulates a variety of +displays; you can cycle between the different types using F2. +There are two major types of displays: televisions and monitors. Monitors generally have +higher quality (sharper) displays. The displays show the normal visible area of the NTSC +video signal generated by the emulated Apple ][ machine.

+
+

Monitors

+

The emulator provides a color monitor, and three monochrome monitors (white, green, and orange). +These emulate standard, no-frills NTSC monitors. The most noticeable characteristic of monitors +is the horizontal display of pixels. Monitors react faster than TVs, so two adjacent pixels will +not merge together; both will be distinctly visible, with blackness between them. For example, +type in the following Applesoft command, then cycle through the display types. The monitors +will show thin, vertical, green lines; TVs will show continuous horizontal lines.

+
+
+
GR : COLOR=4 : HLIN 10,20 AT 10
+
+
+
+

Televisions

+

There are two types of television displays, referred to as “old” and “new.” Each has color and +monochrome (commonly known as “black and white”) varieties. Televisions react more slowly to +changes in the incoming video signal than monitors do, and as a result, horizontal pixels will +merge together, forming a more uniform appearance. The “new” color TV display uses the pre-defined +color pallette (described below under “Colors”), and the black and white TV uses the same +pallette, but fully desaturated. The “old” color TV is the most interesting. It emulates the +signal decoding circuitry of a real television. This includes separating out the “chroma” portion +of the incoming NTSC video signal using a filter algorithm, and calculating the color to display. +It does not use the pre-defined colors.

+
+ + + +
+Note +This mode is very CPU intensive, so your computer (that is, the one that EPPLE ][ is running on) +may not be able to run fast enough to run at the speed of the original Apple ][. The Apple ][ CPU +runs at about 1 MHz, but the video generator runs at 14 MHz; so the inner-most loop in the +EPPLE ][ must run 14 million times per second to keep up.
+
+
+
+

Colors

+

The color palatte used for the +color monitor and new color TV is pre-defined, and was determined through observation of a real +Apple ][ machine on a standard TV, the colors being matched by eye. The old color TV, however, +uses algorithms to calculate the colors it displays.

+
+
+

Scan Lines

+

NTSC displays (TVs or monitors) usually receive signals that are interlaced. However, the +Apple ][ doesn’t generate interlaced screens. This causes blank rows between each displayed +row of pixels. The EPPLE ][ emulates this behavior, but also allows you to “fill in” these +black rows with a copy of the row above it, for a more continuous display (vertically). Use +the F4 key to toggle between these two modes.

+
+
+

Resolution

+

The Apple ][s are commonly documented as having a resolution of 280x192 pixels, and to an +extent this is true. Vertically there are 192 pixels, but since there is no interlacing, +it is more accurate to display them with one blank space between each. So the EPPLE ][ has +two times 192, or 384, vertical pixels in its display. Horizontally there are 280 pixels, but +each could also be shifted right one-half dot, allowing for two times 280, or 560, different +horizontal displayable positions. To emulate this, the EPPLE ][ shows each emulated pixel as +two pixels wide, and displays an emulated half-dot shift as an actual one pixel shift. So the +display area of the EPPLE ][ is 560x384. There is an informational area below and to the +right of the emulated display that shows various statistics of the emulator. So the total screen +area used by the EPPLE ][ is a standard 640x480 pixels.

+
+
+

Full Screen

+

The EPPLE ][ can run in either full-screen mode, or within a window. Use the F3 key to toggle +between the two.

+
+
+

Informational Area

+

The area at the bottom and the right of the EPPLE ][ display show various information about +the emulator.

+
    +
  • +

    +POWER light +

    +
    • +
  • +

    +current cards in SLOTS +

    +
    • +
  • +

    +CASSETTE tape information +

    +
    • +
  • +

    +emulated CPU speed (MHz) +

    +
    • +
  • +

    +function-keys help +

    +
    • +
+
+
+
+

Keyboard

+

The EPPLE ][ emulates the original Apple ][ keyboard. The original Apple ][ +keyboard had symbols in different places than current common PC keyboards. For +example, Shift-2 on the Apple ][ produces a double quote, but on a PC keyboard +it produces an at-sign. For ease of typing, the EPPLE ][ emulator does not +mimic the positions of the original keys, but rather mimics the symbols on +the current PC keyboard. So, for example, if you type Shift-2 on the PC +keyboard into the EPPLE ][, it produces an at-sign, as you would normally expect.

+

The Apple ][ keyboard didn’t produce lower-case letters; neither does the emulator. +Also, the Apple couldn’t produce an opening square bracket ([), braces, vertical +bar, backslash. There were no up- or down-arrow keys. You cannot type these into +the emulator, either. There are other, unusual, cases that are emulated correctly, +as well, such as typing Control in conjunction with a number key simply produces +that number. So typing a Control-3 is the same as just typing a 3. Also, typing +Shift-Control-2 produces the NUL character (ASCII $80).

+

The Apple ][ keyboards didn’t automatically repeat typing characters when a +key was held down. Instead, the user would hold down the REPT (“repeat”) key +while holding down the key that was to be repeated. On the EPPLE ][, this +behavior is emulated, and the F10 key is used as the REPT key.

+

The Apple ][ had no keyboard buffer (actually, it had a buffer of one character). +So if you typed several characters on the keyboard before the currently running +program had a chance to read them, they would get lost (only the final character +typed would be remembered). This behavior can be +toggled on or off in the EPPLE ][. By default, the EPPLE ][ will buffer up any +characters you type and deliver them to the emulated machine when it asks for +them. However, the Apple program must be written properly to allow this to work. +Some Apple ][ programs (like maybe some games) may not work correctly in this +respect, so you may want to turn off buffering in these cases. With buffering +turned off, the EPPLE ][ accurately emulates the original Apple ][. Use the F12 +key to toggle the keyboard buffering. Note that pasting from the clipboard (with +the Insert key) will most definitely cause keys to be lost if the keyboard +buffer is turned off. So if you have a big Applesoft program in the clipboard +and you want to paste it into the EPPLE ][ correctly, make sure the keyboard +buffer is on.

+
Special Keys
    +
  • +

    +F1 Emulates the POWER switch on the back of the Apple ][. +

    +
    • +
  • +

    +F2 Cycles among different display types (TV, monitor, etc.). +

    +
    • +
  • +

    +F3 Toggles between full-screen or window display. +

    +
    • +
  • +

    +F4 Toggles between showing scan lines on the display, or duplicating +each scan line to the following line, to fill-in the otherwise black line. +

    +
    • +
  • +

    +F5 Go to “command entry” mode. +

    +
    • +
  • +

    +F10 Emulates the REPT key. +

    +
    • +
  • +

    +F11 Toggles between running the emulator at authentic speed +(1.02 MHz CPU), or as fast as possible. +

    +
    • +
  • +

    +F12 Toggles the keyboard buffer. +

    +
    • +
  • +

    +Break Emulates the RESET key. +

    +
    • +
  • +

    +Insert Pastes characters from the clipboard into the emulated Apple +(as if they had been typed on the keyboard). +

    +
    • +
  • +

    +Print Screen Save a bitmap file of the current EPPLE ][ screen. +The file will be in the default directory, named ep2_YYYYMMDDHHMMSS.bmp. +

    +
    • +
  • +

    +End Quit the EPPLE ][ program, immediately! +

    +
    • +
+
+ + + +
+Warning +If you have modification to any floppy images or cassette images, and you +press the End key, you will LOSE all those changes, unless you +save them first. See Commands for the save command.
+
+
+
+

Peripheral Cards

+
+

Disk ][ Controller

+

The Disk ][ Controller card emulates the floppy disk controller card and associated +disk drives in the original Apple ][ systems. In the emulator, each card has two +drives attached to it, referred to as drive 1 and drive 2. The floppy disks +themselves are represented by a “nibble” image of the contents. The +emulator emulates the hardware, but to be of any use, you will need to provide +the firmware ROM code.

+

To use a disk card and drives, add these lines to your epple2.conf file, for example:

+
+
+
slot 6 disk
+import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.ex65
+
+

The first line uses the slot command to +insert a disk contoller card into slot 6, which is the standard +slot used for disk cards. The next line uses the import +command to load the card’s ROM with the disk controller +firmware. This firmware is known as the “bootstrap” or “P5” ROM code. +It is seen by the Apple ][ at memory addresses $Cs00-$CsFF, where s is the +slot number (so in the common case of the card being in slot 6, the ROM is +at $C600-$C6FF). The firmware is copyright by Apple, and is available from +the Apple II Library.

+

You can also load a floppy disk image (nibble format) into the drive,either by putting +the load command into the epple2.conf file, or by using the command prompt +in the emulator (F5 key). For example, you could load the DOS 3.3 system master into +slot 6, drive 1, with this command

+
+
+
load slot 6 drive 1 /usr/lib/apple2/dos3x/16sector/disks/dos330/clean330sysmas.nib
+
+
+
+

Language

+

The language card emulates an Apple 16K RAM card, commonly called a Language Card. +To use a language card, add this line to your epple2.conf file:

+
+
+
slot 0 language
+
+

Note that DOS and ProDOS will make use of a language card only if it is in slot zero.

+

The language card has RAM at addresses $E000 through $FFFF, as well as two banks of RAM +at addresses $D000 through $DFFF. A program switches between these RAMs and/or the +motherboard ROM by using the I/O switches at $C080 through $C08F.

+

The information area of the Epple ][ will show the current state of the +language card as follows:

+
    +
  • +

    +R Read from card RAM (vs. motherboard ROM) +

    +
    • +
  • +

    +W Write to card RAM (vs. write-disabled) +

    +
    • +
  • +

    +B1 Use $D000 bank 1 +

    +
    • +
  • +

    +B2 Use $D000 bank 2 +

    +
    • +
+

An overview of the I/O switches that control the language card +is provided by Jim Sather in +Understanding the Apple II, +p. 5-30, Table 5.4, as follows:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BANK2 BANK1 ACTION

C080

C088

WRTCOUNT = 0*, WRITE DISABLE

READ ENABLE

C084

C08C

RC081

RC089

WRTCOUNT = WRTCOUNT + 1*

READ DISABLE

RC085

RC08D

WC081

WC089

WRTCOUNT = 0*

READ DISABLE

WC085

WC08D

C082

C08A

WRTCOUNT = 0*, WRITE DISABLE

READ DISABLE

C086

C08E

RC083

RC08B

WRTCOUNT = WRTCOUNT + 1*

READ ENABLE

RC087

RC08F

WC083

WC08B

WRTCOUNT = 0*

READ ENABLE

WC087

WC08F

+

* Writing to expansion RAM is enabled when WRTCOUNT reaches 2.

+
+
+

Firmware

+

The firmware card emulates a (modified) Apple Firmware card. +The firmware card is simply an alternate ROM, at addresses +$D000 through $FFFF, that is switched using the I/O switches +at addresses $C080 through $C08F. In order to make use of the +firmware card, you will need to load the ROM with a binary image +from a file on disk. For example, to insert an Integer BASIC +firmware card into the emulator, add these lines to your +epple2.conf file:

+
+
+
# Firmware card with Integer BASIC and old Monitor
+slot 0 firmware
+import slot 0 rombank 1000 /usr/lib/apple2/system/intbasic/intbasic.ex65
+import slot 0 rombank 2425 /usr/lib/apple2/system/other/other.ex65
+import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2/monitor.ex65
+
+

For an Applesoft BASIC firmware card, use these:

+
+
+
# Firmware card with Applesoft BASIC and Autostart Monitor
+slot 0 firmware
+import slot 0 rombank 0000 /usr/lib/apple2/system/applesoft/applesoft.ex65
+import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2plus/monitor.ex65
+
+

Note that the addresses specified in the epple2.conf file for the +rombank are based on the beginning of the bank ROM itself. For example, specifying +1000 (which is 1000 hex) represents the final memory address of $E000, because +the bank ROM is always based at address $D000.

+

The idea is that you would load your motherboard with, for +example, Applesoft BASIC and the Autostart Monitor ROM (to emulate +an Apple ][ plus), and then install a firmware card with Integer +BASIC and the old Monitor. Booting with DOS 3.3, then, would allow +you to type FP to use Applesoft BASIC, or INT to switch to Integer BASIC.

+

Note that DOS and ProDOS will make use of a firmware card only if it is in slot zero.

+

Jim Sather, in +Understanding the Apple II, +on pages 6-18 through 6-21, explains +how to modify a firmware card to allow independent switching of the $F800-$FFFF +ROM memory. This area is occupied by the Monitor, so it is primarily +intended to allow the user to switch between the old Monitor and the Autostart +Monitor, independent of switching between Integer and Applesoft BASIC. The EPPLE ][ +firmware card emulates this behavior.

+

The information area of the EPPLE ][ will show the current state of the +firmware card as follows:

+
    +
  • +

    +D Read from firmware card $D000-$F7FF (vs. motherboard BASIC ROM) +

    +
    • +
  • +

    +F8 Read from firmware card $F800-$FFFF (vs. motherboard Monitor ROM) +

    +
    • +
+
+
+

Clock

+

The clock card emulates a ProDOS-compatible real-time clock card for the Apple ][. +To use a clock card, you will need to configure the EPPLE ][ to insert one into +a slot, typically slot 4. You will also need to load the card with its ROM code, +which is provided with the emulator in the clock.ex65 file. +For example, add this to your epple2.conf file:

+
+
+
slot 4 clock
+import slot 4 rom 0 /usr/lib/epple2/cards/clock.ex65
+
+

Of course you may need to adjust the path for your particular system.

+

To verify that the clock card is working correctly, you can run the following Applesoft +program to retrieve the current time from the clock card and print it. +This program assumes the card is in slot 4.

+
+
+
NEW
+
+10 CALL -15360 : REM $C400 SLOT 4 ENTRY POINT
+20 A = 512 : REM $0200 INPUT BUFFER
+30 C = PEEK(A)
+40 IF C < 160 THEN 99
+50 PRINT CHR$(C);
+60 A = A+1
+70 GOTO 30
+99 END
+
+RUN
+

The card returns data (into the GETLN input buffer at $200) in +the following format:

+

mm,ww,dd,hh,nn,ss,000,yyyy,Time Zone,v

+
    +
  • +

    +mm Month, 01-12 +

    +
    • +
  • +

    +ww Weekday, 00=Monday… 06=Saturday +

    +
    • +
  • +

    +dd Day, 01-31 +

    +
    • +
  • +

    +hh Hour, 00-23 +

    +
    • +
  • +

    +nn Minute, 00-59 +

    +
    • +
  • +

    +ss Second, 00-61 +

    +
    • +
  • +

    +000 Milliseconds; always zero +

    +
    • +
  • +

    +yyyy Year, e.g., 2008 +

    +
    • +
  • +

    +Time Zone time zone string (could contain lower-case characters, + which won’t display correctly) +

    +
    • +
  • +

    +v Daylight Saving Time in effect, 0=no, 1=yes +

    +
    • +
+

Note that only mm,ww,dd,hh,nn fields are used by ProDOS. The other +fields, ss,000,yyyy,Time Zone,v, are an EPPLE ][ extension. Also note +that ProDOS was not designed to work for years past 2007, so +ProDOS will show the incorrect year, but the other fields will be accurate. +I believe patches exist for ProDOS to fix this.

+
+
+

Standard Input

+

The “standard input” card doesn’t emulate a real piece of hardware; rather, it +reads characters from standard input (stdin) (of the EPPLE ][ emulator).

+

To use a standard input card, add these lines to your epple2.conf file:

+
+
+
# IN#2 reads from standard input
+slot 2 stdin
+import slot 2 rom 0 /usr/lib/epple2/cards/stdin.ex65
+
+

That will insert a stdin card into slot 2, and then load its +ROM image into the card. +The stdin ROM is provided with the EPPLE ][ distribution.

+

For example, if you have a stdin card installed in slot 2, start +the EPPLE ][ emulator from the command line, and at the Applesoft +prompt, type IN#2. Then you can switch back to the +command shell, and whatever you type will be fed into the emulated +Apple. Use RESET or IN#0 to go back to normal.

+
+
+

Standard Output

+

The “standard output” card doesn’t emulate a real piece of hardware; rather, it acts +similar to a printer card, but instead of sending characters to a printer, it sends +them to standard output (stdout) (of the EPPLE ][ emulator).

+

To use a standard output card, add these lines to your epple2.conf file:

+
+
+
# PR#1 prints to standard output
+slot 1 stdout
+import slot 1 rom 0 /usr/lib/epple2/cards/stdout.ex65
+
+

This will insert a stdout card into slot 1 (which is the typical +slot for a printer card), and then load its ROM image into the card. +The stdout ROM is provided with the EPPLE ][ distribution.

+

For example, if you have a stdout card installed, at the Applesoft +prompt, type PR#1. Whatever you type next will be +echoed to standard output. Type PR#0 to stop echoing.

+
+
+
+

Cassette Tape Interface

+

The Apple ][ and Apple ][ plus machines had the ability to save and load binary +data to and from cassette tape. The user would attach a standard cassette tape +recorder to the jacks on the back of the Apple ][, and use the monitor R and W +commands, or the Applesoft BASIC commands LOAD and SAVE, to read and write data +on the cassette tape. The user would have to press the play and/or record buttons +on the player at the right time.

+

The Epple ][ emulates the cassette interface, using a file to hold the +recorded portion of the tape. The file will grow in length as necessary +to hold data that the emulated Apple is writing to the “tape.” +The emulator will not overwrite existing data on a tape image. +The emulator will automatically “press” the play or record buttons that +would have been necessary when using the original machine.

+
+

Commands

+

cassette new <file-path>

+

This creates a new empty file (on the host computer) that represents a cassette tape image. +The file must not already exist.

+

cassette load <file-path>

+

This loads an existing file (from the host computer) containing a cassette tape image. +The tape is automatically positioned at its beginning (fully rewound).

+

cassette unload

+

This removes the file from the cassette tape. Note that you must manually save +the file using the cassette save command (described below).

+
+ + + +
+Warning +Unloading an unsaved file will lose any changes made to the file, without warning.
+
+

cassette rewind

+

This command “rewinds” the cassette tape, positioning it at the beginning +of the tape (for subsequent reading). You do not need to rewind the tape +before saving or unloading it, of course.

+

cassette save

+

This command saves the changed tape to the file. Note that the display will show +an asterisk * next to the file name if there are unsaved changes that need to +be saved. Unsaved changes will be lost without warning if the file is unloaded +or if you quit the program.

+
+
+

Example of Saving to Tape

+

Start up the emulator with Applesoft ROMs for this tutorial. +Enter a simple Applesoft program, just as an example, that we +are going to save to a cassette tape image file.

+
+
+
]NEW
+
+]10 PRINT "HELLO"
+
+]20 END
+
+]LIST
+
+10  PRINT "HELLO"
+20  END
+
+]RUN
+HELLO
+
+]
+

We first need to load a tape image file into the cassette machine. +Enter command mode by pressing F5, then make a new tape +image file.

+
+
+
command: cassette new hello.tap
+
+

This will create a new, empty tape file image named hello.tap +in the current default directory. (We could have specified a full path +name for the file if we wanted to place it in a different directory.) +Notice that the emulator now displays the name of the tape image file, +along with the position and length of the tape image, which is now 0/0.

+

Next, we tell Applesoft to save the program to the cassette. For this, +we just use the SAVE command. Note that this is not the +DOS SAVE command; the DOS command has a file name after +SAVE. We just use SAVE with no file name.

+
+
+
]SAVE
+
+]
+
+

It will take 10 seconds or so for it to save. Notice that the +current position of the tape is counting up as the Apple saves +the program. When it is finished, you need to save the changes +to the file. Press F5 and enter the emulator command to save +the tape image file.

+
+
+
command: cassette save
+
+

We can now unload the file from the emulator (which is like ejecting +the tape from the cassette player).

+
+
+
command: cassette unload
+
+
+
+

Example of Loading from Tape

+

To load the saved program (from the previous section) into the Apple again, +we will need to first load the tape image file back into the cassette machine. +Press F5 to enter command mode and load the image file.

+
+
+
command: cassette load hello.tap
+
+

This will load hello.tap (in the current default directory). Notice the +emulator now displays the name of the tape image file, along with the +position and length of the tape image, which in this case is 0/33481.

+

Next, we tell Applesoft to load the program from the cassette. For this, +we just use the LOAD command. Note that this is not the +DOS LOAD command; the DOS command has a file name after +LOAD. We just use LOAD with no file name.

+
+
+
]LOAD
+
+]
+
+

It will take 10 seconds or so for it to load. Notice that the +current position of the tape is counting up as the Apple loads +the program. When it is finished, the program will be loaded.

+
+
+
]LIST
+
+10  PRINT "HELLO"
+20  END
+
+]RUN
+HELLO
+
+]
+
+
+

Tape Image File Format

+

The format of the tape image file is unique to the Epple ][ +It is stored in a low-level format that represents the waveform that the Apple writes +to the cassette tape.

+

The file is a binary format. Each byte in the file represents the length of one half of one cycle +(of voltage level variation) written to the tape. The length is in 10-microsecond units.

+

For example, a tape image file might have the following binary bytes (in decimal): +65 65 65 65 65 20 25 50 50 25 25 25 25 50 50 +Since each byte represents a 10-microsecond unit, these bytes represent the following +half-cycle lengths in microseconds: +650 650 650 650 650 200 250 500 500 250 250 250 250 500 500 +The meaning of these half-cycle lengths to the Apple is as follows:

+
+
+
|-------HEADER------|--sync-|-1-bit-|-0-bit-|-0-bit-|-1-bit-|
+|                   |       |       |       |       |       |
+|650 650 650 650 650|200 250|500 500|250 250|250 250|500 500|
+
+

where HEADER is a header section the Apple writes (to skip any +unrecordable leader section on a real cassette tape); sync is a +synchronization cycle; and the subsequent cycles are the actual +bits of data saved on the tape. A 500-microsecond cycle (which +is stored in the file as two 250 microsecond half-cycles) +represents a zero bit, and a 1-millisecond cycle (which is +stored in the file as two 500 microsecond half-cycles) +represents a one bit.

+
+
+
+

Paddles

+

The Epple ][ provides two paddles to the Apple ][ machine. +One paddle is controlled by moving the mouse left and right; the other +paddle is controlled by moving the mouse up and down. The paddle buttons +are emulated by the mouse buttons (left and right click).

+

In +Understanding the Apple II, +on page 7-33, Jim Sather describes soldering fixed resistors across a game connector +to create two real-time clock references. This is emulated by the Epple ][. Paddle timers 2 and 3 +are 100-microsecond and 1-millisecond references, respectively.

+
+
+

Speaker

+

The Apple ][ could generate sound via a speaker that generated square wave +audio. A program could read memory location $C030 to toggle the speaker and +generate a “click” sound.

+

The Epple ][ emulator will generate sounds from the emulated Apple and +send them to the audio device. It generates 8-bit mono sound, with a 22,050 Hz +sampling rate.

+
+
+
+
+

Building From Source

+
+

The Epple ][ Emulator is written in C++, and can be built +using the standard make program.

+

The primary dependency is +Simple DirectMedia Layer (SDL). +Your linux distribution may provide a package. Or else +you can download it directly from SDL’s web site. In +either case, be sure to install the “Development Libraries” +for your particular platform.

+
+

Debian Linux Example

+
+
+
sudo apt-get install build-essential libsdl1.2-dev  # 1
+cd
+mkdir epple2
+cd epple2
+wget http://mosher.mine.nu/epple2/download/epple2-latest.tar.gz  # 2
+tar xzvf epple2-1.0.tar.gz
+mkdir build  # 3
+cd build
+../epple2-1.0/configure  # 4
+make  # 5
+sudo make install  # 6
+
+ + + + + + +
1 +Install dependencies: gcc, make, SDL +
2 +Retrieve the latest Epple ][ source distribution +
3 +Use this directory for a VPATH-style build +
4 +Run one-time configuration script for your system. Use --help for more information. +
5 +Compile and link. Program will be src/epple2 +
6 +Install into standard system directories +
+
+
+

Windows/MSYS Example

+
+

Install MinGW/MSYS

+

Install MSYS into C:\msys\

+

Install MinGW into C:\msys\mingw\

+

For more information on MinGW and MSYS, see http://www.mingw.org/.

+
+
+

Install SDL

+

At http://www.libsdl.org/ find the download page. +Download the “Development Libraries” for Win32/mingw, for example:

+

SDL-devel-1.2.13-mingw32.tar.gz (Mingw32)

+

and save it to your MSYS home directory (for example, C:\msys\home\Administrator). +Run MSYS, and at the bash prompt, go to your home directory and +untar the SDL archive to your home directory:

+
+
+
$ cd
+$ tar xzvf SDL-devel-1.2.13-mingw32.tar.gz
+

Then follow the instructions to install SDL, for example:

+
+
+
$ cd SDL-1.2.13
+$ make native
+
+
+

Untar Epple ][ Source

+

Download the Epple ][ Source Distribution +and save it to your MSYS home directory (for example, C:\msys\home\Administrator). +Run MSYS, and at the bash prompt, go to your home directory and +untar the epple2 source distribution tar file. For example:

+
+
+
$ cd
+$ tar xzvf epple2-1.0.tar.gz
+
+
+

Build Epple ][

+

Then build as follows. I recommend doing a VPATH build, +where you build into a different directory than the source +directory. To accomplish this, create a new directory for +building, somewhere, such as:

+
+
+
$ cd
+$ mkdir buildepple2
+$ cd buildepple2
+

Then run configure from there. For the MSYS build to work, +you need some extra parameters to the build, and you could +also add some compiler options to optimize the build. For +example (from the buildepple2 directory you just created):

+
+
+
$ ~/epple2/configure --prefix= \
+CXXFLAGS="-I/usr/include -O4 -msse3" \
+CFLAGS="-I/usr/include" \
+LDFLAGS="-L/usr/lib -mconsole -mthreads -mno-cygwin"
+$ make
+

If all goes well, it will build without any errors. +If you get errors about not finding SDL.h, make sure +SDL is installed, and make sure the configure command +is correct. (If you just run configure without the +options shown above, you will get this error at build time.) +The result of the build (on Windows platform) is

+

installer/epple2.msi

+

which is an installable file for Windows. To install +epple2, just double-click on this file from Explorer.

+
+

Copyright © 2009,2012, by +Christopher A. Mosher, +Shelton CT, USA.

+

+Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License +

+

This web site is licensed under the +Creative Commons Attribution-Noncommercial-Share Alike 3.0 USA License.

+
+
+
+
+
+
+ + + diff --git a/doc/keyboard.asciidoc b/doc/keyboard.asciidoc new file mode 100644 index 0000000..351dc3b --- /dev/null +++ b/doc/keyboard.asciidoc @@ -0,0 +1,61 @@ +=== Keyboard + +The EPPLE ][ emulates the original Apple ][ keyboard. The original Apple ][ +keyboard had symbols in different places than current common PC keyboards. For +example, Shift-2 on the Apple ][ produces a double quote, but on a PC keyboard +it produces an at-sign. For ease of typing, the EPPLE ][ emulator does not +mimic the positions of the original keys, but rather mimics the symbols on +the current PC keyboard. So, for example, if you type Shift-2 on the PC +keyboard into the EPPLE ][, it produces an at-sign, as you would normally expect. + +The Apple ][ keyboard didn't produce lower-case letters; neither does the emulator. +Also, the Apple couldn't produce an opening square bracket ([), braces, vertical +bar, backslash. There were no up- or down-arrow keys. You cannot type these into +the emulator, either. There are other, unusual, cases that are emulated correctly, +as well, such as typing Control in conjunction with a number key simply produces +that number. So typing a Control-3 is the same as just typing a 3. Also, typing +Shift-Control-2 produces the NUL character (ASCII $80). + +The Apple ][ keyboards didn't automatically repeat typing characters when a +key was held down. Instead, the user would hold down the REPT (``repeat'') key +while holding down the key that was to be repeated. On the EPPLE ][, this +behavior is emulated, and the F10 key is used as the REPT key. + +The Apple ][ had no keyboard buffer (actually, it had a buffer of one character). +So if you typed several characters on the keyboard before the currently running +program had a chance to read them, they would get lost (only the final character +typed would be remembered). This behavior can be +toggled on or off in the EPPLE ][. By default, the EPPLE ][ will buffer up any +characters you type and deliver them to the emulated machine when it asks for +them. However, the Apple program must be written properly to allow this to work. +Some Apple ][ programs (like maybe some games) may not work correctly in this +respect, so you may want to turn off buffering in these cases. With buffering +turned off, the EPPLE ][ accurately emulates the original Apple ][. Use the F12 +key to toggle the keyboard buffering. Note that pasting from the clipboard (with +the Insert key) will most definitely cause keys to be lost if the keyboard +buffer is turned off. So if you have a big Applesoft program in the clipboard +and you want to paste it into the EPPLE ][ correctly, make sure the keyboard +buffer is on. + +.Special Keys +* +F1+ Emulates the POWER switch on the back of the Apple ][. +* +F2+ Cycles among different display types (TV, monitor, etc.). +* +F3+ Toggles between full-screen or window display. +* +F4+ Toggles between showing scan lines on the display, or duplicating +each scan line to the following line, to fill-in the otherwise black line. +* +F5+ Go to ``command entry'' mode. +* +F10+ Emulates the REPT key. +* +F11+ Toggles between running the emulator at authentic speed +(1.02 MHz CPU), or as fast as possible. +* +F12+ Toggles the keyboard buffer. +* +Break+ Emulates the RESET key. +* +Insert+ Pastes characters from the clipboard into the emulated Apple +(as if they had been typed on the keyboard). +* +Print Screen+ Save a bitmap file of the current EPPLE ][ screen. +The file will be in the default directory, named +ep2_YYYYMMDDHHMMSS.bmp+. +* +End+ Quit the EPPLE ][ program, immediately! + +[WARNING] +If you have modification to any floppy images or cassette images, and you +press the +End+ key, you will LOSE all those changes, unless you +save them first. See <<_commands,Commands>> for the +save+ command. diff --git a/doc/make.png b/doc/make.png new file mode 100644 index 0000000..a995a80 Binary files /dev/null and b/doc/make.png differ diff --git a/doc/note.png b/doc/note.png new file mode 100644 index 0000000..7c1f3e2 Binary files /dev/null and b/doc/note.png differ diff --git a/doc/overview.asciidoc b/doc/overview.asciidoc new file mode 100644 index 0000000..17a90cf --- /dev/null +++ b/doc/overview.asciidoc @@ -0,0 +1,6 @@ +=== Overview + +Epple ][ (the Emulated Apple ][ is a free (as in GPLv3), cross-platform +(Windows, Linux) emulator of the Apple ][ and Apple ][ plus computers +from Apple, Inc. It strives for accurate emulation of the original machines, +with a few extra features added. diff --git a/doc/paddles.asciidoc b/doc/paddles.asciidoc new file mode 100644 index 0000000..e2c07f7 --- /dev/null +++ b/doc/paddles.asciidoc @@ -0,0 +1,12 @@ +=== Paddles + +The Epple ][ provides two paddles to the Apple ][ machine. +One paddle is controlled by moving the mouse left and right; the other +paddle is controlled by moving the mouse up and down. The paddle buttons +are emulated by the mouse buttons (left and right click). + +In +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +on page 7-33, Jim Sather describes soldering fixed resistors across a game connector +to create two real-time clock references. This is emulated by the Epple ][. Paddle timers 2 and 3 +are 100-microsecond and 1-millisecond references, respectively. diff --git a/doc/pinkmystery.png b/doc/pinkmystery.png new file mode 100644 index 0000000..85274da Binary files /dev/null and b/doc/pinkmystery.png differ diff --git a/doc/prodos.png b/doc/prodos.png new file mode 100644 index 0000000..4e6f59a Binary files /dev/null and b/doc/prodos.png differ diff --git a/doc/redhat.png b/doc/redhat.png new file mode 100644 index 0000000..a98a44b Binary files /dev/null and b/doc/redhat.png differ diff --git a/doc/screenshots.asciidoc b/doc/screenshots.asciidoc new file mode 100644 index 0000000..731a8c5 --- /dev/null +++ b/doc/screenshots.asciidoc @@ -0,0 +1,173 @@ +== 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 HIRES 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 HIRES 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 http://en.wikipedia.org/wiki/Softalk[Softalk] +featured an article by Bob Bishop entitled +http://rich12345.tripod.com/aiivideo/softalk.html[Have an Apple Split], 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 ][. + +[source,vbs] +--------------------------------- +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 +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +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. + +[source,vbs] +--------------------------------- +NEW + +10 HGR : HCOLOR = 5 : HPLOT 5,159 TO 5,0 TO 279,0 TO 279,159 + +RUN +--------------------------------- + + + +=== Split Screen HIRES/LORES colors + +image::splitcolors.png[] + +Jim Sather's book +http://www.scribd.com/doc/201423/Understanding-the-Apple-II-by-Jim-Sather-1983Quality-Software[Understanding the Apple II], +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. + +[source,vbs] +--------------------------------- +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 +--------------------------------- diff --git a/doc/speaker.asciidoc b/doc/speaker.asciidoc new file mode 100644 index 0000000..dd72bfa --- /dev/null +++ b/doc/speaker.asciidoc @@ -0,0 +1,9 @@ +=== Speaker + +The Apple ][ could generate sound via a speaker that generated square wave +audio. A program could read memory location $C030 to toggle the speaker and +generate a ``click'' sound. + +The Epple ][ emulator will generate sounds from the emulated Apple and +send them to the audio device. It generates 8-bit mono sound, with a 22,050 Hz +sampling rate. diff --git a/doc/splitcolors.png b/doc/splitcolors.png new file mode 100644 index 0000000..e549342 Binary files /dev/null and b/doc/splitcolors.png differ diff --git a/doc/tip.png b/doc/tip.png new file mode 100644 index 0000000..f087c73 Binary files /dev/null and b/doc/tip.png differ diff --git a/doc/usermanual.asciidoc b/doc/usermanual.asciidoc new file mode 100644 index 0000000..082a1f3 --- /dev/null +++ b/doc/usermanual.asciidoc @@ -0,0 +1,17 @@ +== User Manual + +include::overview.asciidoc[] + +include::commands.asciidoc[] + +include::display.asciidoc[] + +include::keyboard.asciidoc[] + +include::cards.asciidoc[] + +include::cassette.asciidoc[] + +include::paddles.asciidoc[] + +include::speaker.asciidoc[] diff --git a/doc/warning.png b/doc/warning.png new file mode 100644 index 0000000..d41edb9 Binary files /dev/null and b/doc/warning.png differ diff --git a/doc/windows.gif b/doc/windows.gif new file mode 100644 index 0000000..626108d Binary files /dev/null and b/doc/windows.gif differ