Epple-II/doc/commands.asciidoc

anchor:commands[]

=== Commands

+<<slot>> <<motherboard>> <<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:motherboard[]

==== motherboard

The +motherboard+ command configures the emulated Apple's motherboard RAM chips and strapping block.

--------
motherboard ram   {C|D|E} { 4K | 4096 | 16K | 4116 | - | (other-models) } [...up to 8]
motherboard strap {C|D|E} { 4K | 16K } <base>
--------

The RAM configuration lines represent the rows of chips on the motherboard. The motherboard labels the
rows as C, D, and E. Each row has 8 chips, one per bit in a byte. The Apple ][ accepts 4K or 16K chips.
You use the +ram+ command to insert (or remove) chips from the sockets.
You configure each row's address range by using a "strapping block" on the original Apple. In the
emulator, use the +strap+ command to perform this function. You should strap 4K rows to a 4K range
of RAM. You should always assign some RAM to the zero address.

For more information about RAM configuration, see
https://archive.org/details/Apple_II_Reference_Manual_1979_Apple/page/n79[Christopher Espinosa, Apple II Reference Manual
(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:
--------
MM5290
MK4116
MCM4116
--------



Example of normal 48K RAM configuration:
--------
ram e 16K
strap e 16K 8000
ram d 16K
strap d 16K 4000
ram c 16K
strap c 16K 0000
--------

Example of 4K, showing how you could specify each chip:
--------
ram e - - - - - - - -
ram d - - - - - - - -
ram c 4K 4K 4K 4K 4K 4K 4K 4K
strap c 4K 0000
--------

Example of 4K at zero address, and 8K at HI-RES page one:
--------
ram e 4K
strap e 4K 3000
ram d 4K
strap d 4K 2000
ram c 4K
strap c 4K 0000
--------



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 <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 ROM in the emulated Apple. You can load into either the motherboard or
a card in one of the slots. 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, and $D000 + $2DED = $FDED.

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 https://applesaucefdc.com/woz/[WOZ 2.0 format] 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 disk image into.

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

+<file-path>+ Optional path of the disk image to import. If omitted, a dialog box will be presented to select the file to load.

The +load+ command will load a WOZ 2.0 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 WOZ 2.0 DISK IMAGE.
Other formats (for example, nibble, +.nib+, DOS order, +.do+, PRODOS order,
+.po+, +.dsk+, or anything else) must first be converted to WOZ 2.0 format.

You can use https://applesaucefdc.com/[Applesauce] to generate such files from original floppy disks. Or you can convert +.dsk+ or +.d13+ images using +to_woz2+ (source: https://github.com/cmosher01/Apple-II-Disk-Tools ).



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

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

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 load [ <file-path> ]
cassette rewind
cassette tone
cassette blank <file-path>
cassette save
cassette eject { in | out }
--------

+<file-path>+ File path of the cassette tape image file, a standard WAVE file.

See <<cassette_tape>> for more information about operating the emulated cassette tape interface.



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 (rare) version of the motherboard, that only had two hi-res
colors (green and purple), and always displayed text with green and purple fringes.