diff --git a/docs/configuration.md b/docs/configuration.md index b7f49dc..eb2d75c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -12,24 +12,21 @@ 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: - /etc/epple2/epple2.conf + /usr/local/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. + C:\\epple2\epple2.conf 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](commands.md). Comments begin with a hash `#` character, and continue to the end of the line. ## Firmware @@ -41,6 +38,23 @@ The firmware available is described in this documentation. Once the firmware image files are installed on your computer, you can use the `import` command in the configuration file to load the image files into the emulator. +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 +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 \]\[). +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, +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. + ## Peripheral Cards Another primary concern for configuring the Epple \]\[ is the insertion of @@ -51,13 +65,25 @@ types of cards available are described in the cards section. You can use the `slot` command in the configuration file to insert them into the Apple's slots. +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 +it from `$C600`-`$C6FF` into a file on the PC), or by downloading it +from the [Apple II Library](http://mosher.mine.nu/apple2/). +(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 cards, you will need to load their firmware as well. + ## 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. +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 diff --git a/docs/screenshots.md b/docs/screenshots.md index 194baa3..c47a93b 100644 --- a/docs/screenshots.md +++ b/docs/screenshots.md @@ -6,6 +6,8 @@ screenshots --- + + ### DOS 3.3 System Master boot image::dos330boot.png[] @@ -29,7 +31,7 @@ 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 +manually press the **RESET** `F6` 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 @@ -101,7 +103,7 @@ RUN image::pinkmystery.png[] Jim Sather's book -[*Understanding the Apple \]\[*](https://archive.org/details/understanding_the_apple_ii/), +[*Understanding the Apple II*](https://archive.org/details/understanding_the_apple_ii/), which is 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. diff --git a/docs/usermanual.md b/docs/usermanual.md index ed48023..819f381 100644 --- a/docs/usermanual.md +++ b/docs/usermanual.md @@ -48,8 +48,7 @@ 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. +Note that the emulated Apple should be *powered off* before inserting or removing cards. @@ -76,6 +75,7 @@ Christopher Espinosa, [*Apple II Reference Manual*](https://archive.org/details/ (Cupertino, Calif.: Apple Computer, 1978), pp. 70-72. In the `motherboard ram` configuration line `(other-models)` of chips are supported, and will produce different bit patterns at power-on time: + ``` conf MM5290 MK4116 @@ -161,12 +161,10 @@ p. 5-26 *The 16K RAM Card*). The `load` command loads a [WOZ 2.0 format](https://applesaucefdc.com/woz/) floppy disk image into one of the emulated disk drives. - ``` conf load slot drive [ ] ``` - `slot` Slot number, 0 through 7, of Disk \]\[ controller card to load the disk image into. `drive` Drive number, 1 or 2, of the disk drive on the controller card to load the disk image into. @@ -202,8 +200,8 @@ unload slot drive 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. +> #### Warning +> If the disk has been modified but not saved, the modifications will be **DISCARDED**. @@ -261,8 +259,7 @@ The `revision` command specifies which revision of Apple \]\[ motherboard to use revision ``` - -`rev` Revision number of the motherboard. Currently, only two values make any difference in behavior: 0 or 1. +`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 @@ -297,7 +294,7 @@ 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. EPPLE \]\['s television mode 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. +of the incoming NTSC video signal using a filter algorithm, and *calculating* the color to display. #### Scan Lines @@ -305,7 +302,7 @@ NTSC displays (TVs or monitors) usually receive signals that are interlaced. How 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. +the `F4` key to toggle between these two modes. #### Resolution @@ -388,7 +385,7 @@ each scan line to the following line, to fill-in the otherwise black line. (as if they had been typed on the keyboard). * `F8` Save a bitmap file of the current EPPLE \]\[ screen. The file will be in the default directory, named `ep2_YYYYMMDDHHMMSS.bmp`. -* `F9` Quit the EPPLE \]\[ program, immediately! +* `F9` Quit the EPPLE \]\[ program, *immediately*! * `F10` Emulates the REPT key. * `F11` Toggles between running the emulator at authentic speed (1.02 MHz CPU), or as fast as possible. @@ -446,7 +443,7 @@ 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_. +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`-`$FFFF`, as well as two banks of RAM at addresses `$D000`-`$DFFF`. A program switches between these RAMs and/or the @@ -524,7 +521,7 @@ 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_. +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*](https://archive.org/details/understanding_the_apple_ii/page/n151), @@ -562,7 +559,6 @@ To verify that the clock card is working correctly, you can run the following Ap program to retrieve the current time from the clock card and print it. This program assumes the card is in slot 4. - ``` visualbasic NEW @@ -578,7 +574,6 @@ NEW RUN ``` - The card returns data (into the `GETLN` input buffer at `$0200`) in the following format: @@ -651,6 +646,7 @@ 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 have the ability to save and load binary @@ -723,7 +719,7 @@ The file must not already exist. The file type should be `.wav` to indicate a WA `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 +an asterisk `*` next to the file name if there are unsaved changes that need to be saved. `cassette eject { in | out }` @@ -760,7 +756,7 @@ image file. command: cassette blank hello.wav ``` -This will create a new, empty tape file image named +hello.wav+ +This will create a new, empty tape file image named `hello.wav` 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.