Epple-II/doc/commands.asciidoc
2015-07-16 20:54:10 -04:00

210 lines
6.5 KiB
Plaintext

anchor:commands[]
=== Commands
+<<slot>> <<import>> <<load>> <<unload>> <<save>> <<cassette>> <<revision>>+
anchor:slot[]
==== 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 (see <<cards>>):
* +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.
anchor:import[]
==== 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
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'').
anchor:load[]
==== 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 http://ciderpress.sourceforge.net/[CiderPress],
for Windows (but it supposedly runs under Wine on Linux, too). Thanks to Andy McFadden.
anchor:unload[]
==== 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.
anchor:save[]
==== 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.
anchor:cassette[]
==== 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_tape>> for more information about operating the emulated
cassette player and cassette tape image files.
anchor:revision[]
==== 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.