Apple-2-Tools/Epple-II
1
0
Fork 0
mirror of https://github.com/cmosher01/Epple-II.git synced 2024-12-29 00:31:40 +00:00
Code Issues Projects Releases Wiki Activity

more docs

Browse Source
This commit is contained in:
Christopher Mosher 2019-04-12 19:42:05 -04:00
parent 6967c97a8c
commit 68d9c5f24e
3 changed files with 51 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/configuration.md
View File

@ -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, 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). 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 default configuration file for
the Epple \]\[ emulator is: the Epple \]\[ emulator is:
/etc/epple2/epple2.conf /usr/local/etc/epple2/epple2.conf
For Windows, the file will be: For Windows, the file will be:
C:\Program Files\Epple2\etc\epple2\epple2.conf C:\<Path to>\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 You can specify a different configuration file for the emulator to use by
specifying its name as the argument when running the epple2 program. 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. Comments begin with a hash `#` character, and continue to the end of the line.
## Firmware ## 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` 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. 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 ## Peripheral Cards
Another primary concern for configuring the Epple \]\[ is the insertion of 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 You can use the `slot` command in the configuration file to insert
them into the Apple's slots. 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 ## Sample Configuration Files
There are a number of configuration files provided with the distribution for There are a number of configuration files provided with the distribution for
your convenience. They provide various common configurations of machines. your convenience. They provide various common configurations of machines.
You can use one of these files directly, by specifying its path as the argument 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 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. 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 In this case, you will be able to power on the Apple and see the low-resolution

6
docs/screenshots.md
View File

@ -6,6 +6,8 @@ screenshots
--- ---
### DOS 3.3 System Master boot ### DOS 3.3 System Master boot
image::dos330boot.png[] 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 controller (with 13-sector ROMs) in slot 6. With a
revision 0 motherboard, when the machine is powered-on, revision 0 motherboard, when the machine is powered-on,
the CPU doesn't start actually running until you 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; ROMs do not boot from the disk drives automatically;
you need to type `C600G` to boot. you need to type `C600G` to boot.
We've booted the DOS 3.1 System Master disk and done a We've booted the DOS 3.1 System Master disk and done a
@ -101,7 +103,7 @@ RUN
image::pinkmystery.png[] image::pinkmystery.png[]
Jim Sather's book 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 which is the primary
reference for the internal design of the EPPLE \]\[ emulator, describes the video reference for the internal design of the EPPLE \]\[ emulator, describes the video
generation process of the Apple \]\[, in great detail, in Chapter 8. generation process of the Apple \]\[, in great detail, in Chapter 8.

30
docs/usermanual.md
View File

@ -48,8 +48,7 @@ inserts a language card into slot zero. Use `empty` to remove a card:
slot 0 empty slot 0 empty
``` ```
[NOTE] Note that the emulated Apple should be *powered off* before inserting or removing cards.
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. (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: In the `motherboard ram` configuration line `(other-models)` of chips are supported, and will produce different bit patterns at power-on time:
``` conf ``` conf
MM5290 MM5290
MK4116 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. The `load` command loads a [WOZ 2.0 format](https://applesaucefdc.com/woz/) floppy disk image into one of the emulated disk drives.
``` conf ``` conf
load slot <slot> drive <drive> [ <file-path> ] load slot <slot> drive <drive> [ <file-path> ]
``` ```
`slot` Slot number, 0 through 7, of Disk \]\[ controller card to load the disk image into. `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. `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 <slot> drive <drive>
The `unload` command removes the disk from the specified slot and drive. The `unload` command removes the disk from the specified slot and drive.
[WARNING] > #### Warning
If the disk has been modified but not saved, the modifications will be DISCARDED. > 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 <rev>
``` ```
`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 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 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 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 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 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 #### 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 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 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 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 #### 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). (as if they had been typed on the keyboard).
* `F8` Save a bitmap file of the current EPPLE \]\[ screen. * `F8` Save a bitmap file of the current EPPLE \]\[ screen.
The file will be in the default directory, named `ep2_YYYYMMDDHHMMSS.bmp`. 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. * `F10` Emulates the REPT key.
* `F11` Toggles between running the emulator at authentic speed * `F11` Toggles between running the emulator at authentic speed
(1.02 MHz CPU), or as fast as possible. (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 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 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 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 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. 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 Jim Sather, in
[*Understanding the Apple II*](https://archive.org/details/understanding_the_apple_ii/page/n151), [*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. program to retrieve the current time from the clock card and print it.
This program assumes the card is in slot 4. This program assumes the card is in slot 4.
``` visualbasic ``` visualbasic
NEW NEW
@ -578,7 +574,6 @@ NEW
RUN RUN
``` ```
The card returns data (into the `GETLN` input buffer at `$0200`) in The card returns data (into the `GETLN` input buffer at `$0200`) in
the following format: 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. echoed to standard output. Type `PR#0` to stop echoing.
### Cassette Tape Interface ### Cassette Tape Interface
The Apple \]\[ and Apple \]\[ plus machines have the ability to save and load binary 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` `cassette save`
This command saves the changed tape to the file. Note that the display will show 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. be saved.
`cassette eject { in | out }` `cassette eject { in | out }`
@ -760,7 +756,7 @@ image file.
command: cassette blank hello.wav 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 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.) 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. Notice that the emulator now displays the name of the tape image file.