Technical Notes
===============

Apple2eROM Image
~~~~~~~~~~~~~~~~
    The Apple2eROM image file should be the same format as used by the AppleWin
emulator (for the IBM PC) and is as follows:

+&0000 External I/O ROM ($C000-$CFFF)
+&1000 Internal I/O ROM ($C000-$CFFF)
+&2000 Monitor ROM      ($D000-$FFFF)

Processor Emulation
~~~~~~~~~~~~~~~~~~~
    The NMOS 6502 had several problems which were rectified in later models in the
series. Virtu accurately emulates the known bugs found in the original:

- jump indirect wraps the effective address at a page boundary
- invalid flags after an arithmetic operation in decimal mode

    Another problem with the NMOS 6502 was the operation of undefined or
'undocumented' opcodes which were executable, but not legal instructions. Most of
these opcodes result in the CPU attempting to effectively execute two legal
instructions at once, and thus produce obscure, and even amusing operations. Virtu
implements these opcodes as multi-byte NOP instructions as per the operand length of
the opcodes in a Rockwell R6502. The cycle time used is the maximum of the times for
each of the two legal instructions that comprise the undefined instruction.

    The 65C02 amends all the problems mentioned above; however some older software
may rely on this erroneous functionality, thus Virtu's capability to switch between
the two processors becomes desirable. In particular, the indirect jump and undefined
instructions were sometimes used to make copy protection routines hard to follow,
and some games may rely on the incorrect decimal arithmetic result flags for score-
keeping. Note also that although the 65C02 defines the 6502's undefined opcodes as
either new instructions or multi-byte NOPs, the number of bytes consumed (ie operand
length) differs.

Sound Emulation
~~~~~~~~~~~~~~~
    Memory accesses in the range $C030 to $C03F, both reads and writes, generate a
speaker click on an Apple ][. Virtu buffers such accesses and the VVoice module uses
this information to generate square-wave pulses (scaled by volume) for the sound
system. Intense speaker activity at access periods of around 48 microseconds or less
would 'bog down' the sound emulation, since this is the output sample period for
the single sound channel used. To prevent this, accesses are ignored if they occur
at intervals of around 48 microseconds or less. Although a smaller output period
would improve sound resolution, it significantly increases overheads; 48us is a
compromise that gives a fuller sound for the average case.

Disk ][ Drive Emulation
~~~~~~~~~~~~~~~~~~~~~~~
    Virtu currently supports only one type of Apple ][ disk image, the DSK (from the
MSDOS ".dsk" suffix), or DOS order (DO) disk. This image format has no header
information but is simply the sector data itself, ordered by DOS sector number. Thus
for track 0 the sectors 0, 1, 2 ... F are found at offsets $000, $100, $200 ... $F00
in the DSK. This ordering comes in handy when editing DOS disks with a hex file
editor. For reference, the following table translates physical (numbering as encoded
in sector address fields) to DOS sectors and vice versa.

Physical:  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
DOS:       0  7  E  6  D  5  C  4  B  3  A  2  9  1  8  F

DOS:       0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
Physical:  0  D  B  9  7  5  3  1  E  C  A  8  6  4  2  F

    The track format emulated is a standard DOS 3.3 16 sector track with 4&4-
encoded sector addressing and 6&2-encoded sector data. Although each sector has its
own volume number in its address field, all sectors on a disk usually have the same
one: Virtu gives each sector the volume number for the disk side it resides on (see
the Virtu "!Help"). DOS usually ignores volume numbers, but some software assigns
unique volume numbers to various disks in order to detect which one is in the drive.
In this case, set the volume number for each disk to that found by cataloging the
original disk or using a sector/nibble editor.

    Disk emulation is performed at the memory-mapped I/O level, not (as in some
emulators) by interception of RWTS (DOS) or MLI (ProDOS) calls. This technique
provides more complete emulation of disk access, though with a performance penalty.
Tracks are 'nibblized' at runtime in a manner analagous to DOS's method of writing
to disk. The resulting nibble data is almost identical to the data stream from a
disk ][ drive and interface card, save for a few changes made to fool the disk up-to-
speed check in RWTS (some emulators patch RWTS instead).

    The nibblizing of a track occurs only when the first nibble is actually
requested, not during disk arm movement. Non-integral track positions are truncated,
so track $11.5 reads track $11, and the maximum track is $22. A track is marked for
flushing when written to, and flushing occurs on:

- reading/writing a new track
- disk flip (A <-> B)
- changing drives (1 <-> 2)
- reset (also sets drive 1, drive motor off, stepper phases off)
- exiting Virtu

    The flush denibblizes the cached track image as DOS does when reading from disk
(except that Virtu ignores sector volume numbers), and if all sectors are error free
writes it back to the disk image. Initializing a disk should work for all DOSs that
use standard sector marks. Problems may occur in the unlikely event of a DOS
requiring unusual track lengths, inter-sector gap lengths or physical sector
orderings. These cases would, however, amount to copy protection anyway.

Video Emulation
~~~~~~~~~~~~~~~
    All standard Apple //e video modes are supported, including text, graphics and
mixed modes. When displaying hires graphics in color Virtu closely emulates the
characteristic odd/even pixel coloring which effectively halves the horizontal
screen resolution from 280 (monochrome) pixels to 140 (colour pair) pixels across.
The bit 7 (delay) half pixel shift and color interference of adjacent delayed and
non-delayed pixels is not emulated due to resolution and performance constraints.
The video modes supported are:

- Lores graphics
- 40 column Text
- 80 column Text
- Lores graphics & 40 column Text
- Lores graphics & 80 column Text
- Hires graphics
- Hires graphics & 40 column Text
- Hires graphics & 80 column Text
- 7M Lores graphics
- Double Lores graphics
- 7M Lores graphics & 40 column Text
- Double Lores graphics & 80 column Text
- ND Hires graphics
- Double Hires graphics
- ND Hires graphics & 40 column Text
- Double Hires graphics & 80 column Text

    7M Lores and ND Hires are little known, and hence little used, video modes which
offer standard modes with reduced color capability. 7M Lores results from viewing
normal Lores then accessing $C05E (DHiresSet). When 80 column mode is not enabled,
this forces normal Hires graphics timing (7Mhz) rather than double Hires timing
(14MHz). The reducton in timing resolution means only black, green, purple and white
colours are available. ND (no delay) Hires can be similarly activated, and because
$C05E disables the colour signal timing delay responsible for 'high bit set' colours
(orange and blue) when not in 80 column mode, the colours available are also only
those in 7M Lores. It seems that the only use for these modes would be to flash on
and off those colours affected for primitive special effects.

Joystick Emulation
~~~~~~~~~~~~~~~~~~
    A memory access in the range $C070 to $C07F starts timers whose pulse widths are
variable from 2 to 3300 microseconds depending on the resistances of the attached
joystick/paddles. The high bit of a paddle address goes low when the timer expires,
and most paddle routines count 11 cycle loops waiting for this change. Some software
may use longer loops to check multiple paddles, and hence the number of accesses is
not a reliable way to emulate these timers. Virtu keeps the signal high for a cycle
count equalling 11 times the paddle value (0 to 255).

Printer Emulation
~~~~~~~~~~~~~~~~~
    Only simple text printer output is supported. Memory writes in the range $C090
to $C09F are output to the printer output file after being ANDed with #$7F to strip
the high bit. Formatting control characters are not filtered out.
