From 2fcfdf1052805f0fbfa2524b83152b6d2b46640a Mon Sep 17 00:00:00 2001 From: "Christopher A. Mosher" Date: Fri, 12 Apr 2019 21:44:27 -0400 Subject: [PATCH] more docs --- docs/configuration.md | 18 +++++++----------- docs/screenshots.md | 23 ++++++++++++----------- docs/usermanual.md | 26 +++++++++++++------------- 3 files changed, 32 insertions(+), 35 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index eb2d75c..2ed4f2e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -12,7 +12,7 @@ optionally the peripheral card ROMs you want to use, you will need to configure 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` +## epple2.conf The default configuration file for the Epple \]\[ emulator is: @@ -26,29 +26,24 @@ For Windows, the file will be: You can specify a different configuration file for the emulator to use by specifying its name as the argument when running the epple2 program. -The format of the configuration file is just lines of [commands](commands.md). +The format of the configuration file is just lines of [commands](usermanual.md). Comments begin with a hash `#` character, and continue to the end of the line. ## Firmware Firmware, commonly called ROM images or ROMs, will need to be loaded -into the emulated ROM areas of the emulated Apple -in order for it to be able to boot the emulated Apple machine. -The firmware available is described in this documentation. +into the ROM areas of the emulated Apple in order for it to boot. 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. -Since the Epple \]\[ program emulates only the hardware, you will need to load some _system software_ -into in, in order for it to operate usefully. -This software 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 +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 the firmware from it (`$D000`-`$FFFF`) (into a file on your PC) and use it. Alternatively, you can download the firmware images from the [Apple II Library](https://mosher.mine.nu/apple2/). If you do not want to download the proprietary firmware, you can still use the emulator (albeit -in a rudimentary manner) with the free (GPLv3) _System ROM (Demo)_ package (included with EPPLE \]\[). +in a rudimentary manner) with the free (GPLv3) *System ROM (Demo)* package (included with EPPLE \]\[). The source code is also available; you can assemble it using the [xa Assembler](http://www.floodgap.com/retrotech/xa/). The Demo System ROM only provides commands to dump or set memory bytes, @@ -83,7 +78,8 @@ 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. +files are in the same location as the default `epple2.conf` file, or +on [github](https://github.com/cmosher01/Epple-II/tree/master/conf). 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 diff --git a/docs/screenshots.md b/docs/screenshots.md index c47a93b..18a58ac 100644 --- a/docs/screenshots.md +++ b/docs/screenshots.md @@ -10,7 +10,7 @@ screenshots ### DOS 3.3 System Master boot -image::dos330boot.png[] +![dos330boot](https://mosher.mine.nu/images/computers/apple2/dos330boot.ptif/full/full/0/default.jpg) Here we've configured an Apple \]\[ plus, with a disk controller in slot 6, and a language card in slot 0. @@ -24,7 +24,7 @@ between Applesoft and Integer BASIC by using the `FP` and ### DOS 3.1 System Master on Revision 0 motherboard -image::dos310rev0.png[] +![dos310rev0](https://mosher.mine.nu/images/computers/apple2/dos310rev0.ptif/full/full/0/default.jpg) Here we've configured an Apple \]\[ (Integer BASIC ROMs), with a Revision Zero motherboard, and a disk @@ -47,7 +47,7 @@ later revisions. ### PRODOS 1.1.1 boot -image::prodos.png[] +![prodos](https://mosher.mine.nu/images/computers/apple2/prodos.ptif/full/full/0/default.jpg) Here we've configured an Apple \]\[ plus with language card and disk drive. We're booting a PRODOS 1.1.1 disk. @@ -56,7 +56,7 @@ and disk drive. We're booting a PRODOS 1.1.1 disk. ### Bishop's Apple Split -image::applesplit.png[] +![applesplit](https://mosher.mine.nu/images/computers/apple2/applesplit.ptif/full/full/0/default.jpg) The October 1982 issue of [Softalk](http://en.wikipedia.org/wiki/Softalk) featured an article by Bob Bishop entitled @@ -100,7 +100,7 @@ RUN ### Mysterious Pink Line -image::pinkmystery.png[] +![pinkmystery](https://mosher.mine.nu/images/computers/apple2/pinkmystery.ptif/full/full/0/default.jpg) Jim Sather's book [*Understanding the Apple II*](https://archive.org/details/understanding_the_apple_ii/), @@ -126,7 +126,7 @@ RUN ### Display Aspect Ratio -image::aspectratio.png[] +![aspectratio](https://mosher.mine.nu/images/computers/apple2/aspectratio.ptif/full/full/0/default.jpg) Jim Sather also describes the aspect ratio of the Apple \]\[ when displayed on a TV screen (p. 8-28). Software developers would need @@ -158,8 +158,9 @@ HOME ### Split Screen HIRES/LORES colors -image::splitcolorstv.png[] -image::splitcolorsmon.png[] +![splitcolorstv](https://mosher.mine.nu/images/computers/apple2/splitcolorstv.ptif/full/full/0/default.jpg) + +![splitcolorsmon](https://mosher.mine.nu/images/computers/apple2/splitcolorsmon.ptif/full/full/0/default.jpg) Jim Sather's book also shows an Applesoft BASIC program and assembly language subroutine on pages 3-16 and 3-17 (reproduced @@ -210,14 +211,14 @@ RUN ### Miscellaneous -image::gplrom.png[] +![gplrom](https://mosher.mine.nu/images/computers/apple2/gplrom.ptif/full/full/0/default.jpg) Example of the Demo System ROM provided with the EPPLE \]\[ emulator. -image::static.png[] +![static](https://mosher.mine.nu/images/computers/apple2/static.ptif/full/full/0/default.jpg) Random TV "static" when no video signal is present. -image::apple2.png[] +![apple2](https://mosher.mine.nu/images/computers/apple2/apple2.ptif/full/full/0/default.jpg) Apple System ROM showing the APPLE \]\[ title. diff --git a/docs/usermanual.md b/docs/usermanual.md index 819f381..c4f3d76 100644 --- a/docs/usermanual.md +++ b/docs/usermanual.md @@ -406,7 +406,7 @@ To use a disk card and drives, add these lines to your epple2.conf file, for exa ``` conf slot 6 disk -import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.ex65 +import slot 6 rom 0 /usr/lib/apple2/dos3x/16sector/controller/disk2.a65 ``` The first line uses the `slot` command to @@ -496,9 +496,9 @@ firmware card into the emulator, add these lines to your ``` conf # 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 +import slot 0 rombank 1000 /usr/lib/apple2/system/intbasic/intbasic.a65 +import slot 0 rombank 2425 /usr/lib/apple2/system/other/other.a65 +import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2/monitor.a65 ``` For an Applesoft BASIC firmware card, use these: @@ -506,8 +506,8 @@ For an Applesoft BASIC firmware card, use these: ``` conf # 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 +import slot 0 rombank 0000 /usr/lib/apple2/system/applesoft/applesoft.a65 +import slot 0 rombank 2800 /usr/lib/apple2/system/monitor/apple2plus/monitor.a65 ``` Note that the addresses specified in the `epple2.conf` file for the @@ -545,12 +545,12 @@ firmware card as follows: 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. +which is provided with the emulator in the clock.a65 file. For example, add this to your epple2.conf file: ``` conf slot 4 clock -import slot 4 rom 0 /usr/lib/epple2/cards/clock.ex65 +import slot 4 rom 0 /usr/lib/epple2/cards/clock.a65 ``` Of course you may need to adjust the path for your particular system. @@ -608,7 +608,7 @@ To use a standard input card, add these lines to your `epple2.conf` file: ``` conf # IN#2 reads from standard input slot 2 stdin -import slot 2 rom 0 /usr/lib/epple2/cards/stdin.ex65 +import slot 2 rom 0 /usr/lib/epple2/cards/stdin.a65 ``` That will insert a stdin card into slot 2, and then load its @@ -634,7 +634,7 @@ To use a standard output card, add these lines to your `epple2.conf` file: ``` conf # PR#1 prints to standard output slot 1 stdout -import slot 1 rom 0 /usr/lib/epple2/cards/stdout.ex65 +import slot 1 rom 0 /usr/lib/epple2/cards/stdout.a65 ``` This will insert a stdout card into slot 1 (which is the typical @@ -742,7 +742,7 @@ are going to save to a cassette tape image file. ]LIST 10 PRINT "HELLO" -20 END +20 END ]RUN HELLO @@ -805,7 +805,7 @@ command: cassette load ``` This will bring up the Open File dialog box. Choose -hello.wav file you just saved. Notice the +`hello.wav` file you just saved. Notice the emulator now displays the name of the tape image file, along with the position and length of the tape image. Notice the emulator automatically advances the tape to the first header section. @@ -853,5 +853,5 @@ 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 +send them to the audio device. It generates 8-bit mono sound, with a 20,410 Hz sampling rate.