CONTENTS

The C64 Emulator

Emulator Documentation

Description

ALEC64 is a Commodore 64 emulator. ALEC64 is written in C.

Following ports exists.

Installation

Linux/Unix:

Choose your installation directory
For example: /usr/games.
Unpack the archive
tar vxzf alec64-x.xx.tar.gz

x.xx is replaced by the version number.

Build rom image
You need the image of the C64 BASIC ROM, C64 KERNEL ROM and C64 CHARACTER ROM to run the emulator. This images must be in the original form, exactly 8192 or 4096 bytes, no extra informations.

If you don't know how to get this images, read the comp.emulators.cbm FAQ.

cat basic kernel character > romimage.c64
-or-
cat original.64b original.64k original.64.c > romimages.c64

basic, kernal and character are the names of your ROM images.

Choose the correct executable
c64-svga-sp
C64 for svgalib with speaker.
c64-svga-vs-sp
C64 for svgalib with video-sync and speaker.
c64-svga-os-vs-sp
C64 for svgalib with overscan, video-sync and speaker.
c64-x11-sp
C64 for X11 with speaker.
c64-x11-vs-sp
C64 for X11 with video-sync and speaker.
c64-x11-os-vs-sp
C64 for X11 with overscan, video-sync and speaker.

ln "selected version" c64
-or-
ln -s "selected version" c64

Test it
You can now start the emulator with

c64

To exit press ALT+PRINT.

DOS:

Choose your installation directory
For example: \games.
Unpack the archive
tar vxzf alec64-x.xx.tar.gz
or
unzip ale64xxx.zip

x.xx or xxx is replaced by the version number.

Build rom image
You need the image of the C64 BASIC ROM, C64 KERNEL ROM and C64 CHARACTER ROM to run the emulator. This images must be in the original form, exactly 8192 or 4096 bytes, no extra informations.

If you don't know how to get this images, read the comp.emulators.cbm FAQ.

copy /b basic+kernel+character romimage.c64
-or-
copy /b original.64b+original.64k+original.64.c romimage.c64

basic, kernal and character are the names of your ROM images.

Choose the correct executable
c64-sp
C64 version with speaker.
c64-vs
C64 version with video-sync and speaker.

copy "selected version" c64

Test it
You can now start the emulator with

c64

To exit press ALT+CTRL+DEL. (This will change in new versions)

Command line options

c64 [-1] [-2] [-a name] [-c dir] [-d disk] [-e name] [-f n] [-F n] [-g geometry] [-h] [-i roms] [-j] [-l lib] [prgid]

Examples

c64 -1

Start c64 and use keypad as joystick 1.

Environment

You can use following environment variables to runtime configure ALEC64.

Examples

SH (Unix)
C64DIR=/usr/games/c64
export C64DIR

CSH (Unix)
setenv C64DIR /usr/games/c64

Use the directory '/usr/games/c64' as start for relative pathes. c64 -c psi-5 changes to the directory '/usr/games/c64/psi-5'.

DOS
C64DIR=\games\c64

Use the directory '\usr\games\c64' as start for relative pathes. c64 -c psi-5 changes to the directory '\games\c64\psi-5'.

Keyboard

Keyboard layout used for emulation. I use a layout very simular to the original layout.

Picture keyboard layout

    <-  1!  2"  3#  4$  5%  6&  7'  8(  9)  0   +   -   __DEL_
   CTRL   q   w   e   r   t   y   u   i   o   p   q   *   RET_
 RUN STOP  a   s   d   f   g   h   j   k   l   :[  ;]  =   RET
 SHIFT  °1  z   x   c   v   b   n   m   ,<  .>  /?  RIGHTSHIFT
 CTRL       C=      |_________SPACE_________|  C=         CTRL
°1 is arrow-up and pi. On 101 keyboards use PAGE-DOWN.

The following keys have a special meaning for ALEC64.

Keys used for C64

F1 F2 F3 F4 F5 F6 F7 F8
The C64 functions keys
Caps-Lock
RUN/STOP
Left shift
LEFT SHIFT
Right shift
RIGHT SHIFT
Left Alt and Right Alt
C=
Left control, Right control and TAB
CONTROL
Home
HOME
End
RESTORE
Delete and Backspace
DEL
Insert
SHIFT DEL
Page up
POUND
Page down
UP-ARROW and PI
Arrow keys
The C64 cursor keys

Keys used for the emulator

F9
Decrements VicFetch
SHIFT + F9
Increments VicFetch
F10
Decrements VicFetchAdd
SHIFT + F10
Increments VicFetchAdd
F11
Toggles the sound emulation on/off
F12
Enters the builtin machine monitor
PRINT
Toggle autofire on/off
SCROLL-LOCK
Change update rate ( 1 ->2 ->3 ->4 ->1 )
SHIFT + SCROLL-LOCK
Change emulation rate ( 1 ->2 ->3 ->4 ->1 )
PAUSE
NUM-LOCK
Toggles emulation of joystick 1 or 2
Keypad 1 2 3 4 6 7 8 9
Joystick direction
Keypad 5 and ESC
Joystick fire (ESC can have Autofire, Keypad-5 never)
Alt-Ctrl-Print, sys-request
Leave emulator. (Linux)
Alt-Ctrl-Delete
Leave emulator. (DOS, will be changed!)
Ctrl-Pause, Intr.
Reset emulator.

Joystick

The joysticks of the C64 are emulated with the keyboard.

You can control the joystick emulation with:

Under X11 the joystick emulations depends of the num-lock state.

6510

The opcodes counts cycles and all hardware timings are calculate at this base.

Supported features

Missing features

SID

The SID is implemented as hook in the vertical retrace, this means the emulation is called 50 or 60 times per second.
(New versions should use a closer timing.) Since sound isn't really needed to play, the SID emulation isn't perfect.

We support emulations for 3 different hardwares.

PC Speaker

This was very easy to implement and makes a good sound. In each vertical retrace the SID emulations is called.

DSP 8bit sampled data

This is only available for the linux port. The SID sound is sampled with 22050 Hz and played using '/dev/dsp'. Currently only the correct wave forms are support, the correct envelope forms are missing.

OPL3 FM synth chip

Be currently developed.

VIC

The VIC is implemented on a rasterline basis. This means every 63-65 cycles the 6510 emulation is stopped and a display line is drawn.

Supported features

Missing features

Internals of VIC emulation

video-sync
The ALEC64 Emulator runs with a virtual cpu clock, all hardware timings depends on the virtual cpu clock. If you have a fast computer (486DX4/100 or above) the emulator is much to fast. To reduce it to the original speed, I use video-sync. This means each video frame is syncronised to 1/50s (PAL) or 1/60s (NTSC).

1541

The 1541 is emulated on the filesystem. The disk image emulation is missing.

The files on the filesystem could be in binary or P00 format.

You can change the directory for the 1541 emulation with

Monitor

ALEC64 has a builtin maschine language monitor. You can disassemble, display and modify the C64 memory.

You can enter the builtin monitor with 'F12'.

This are the builtin commands.

Files

This are the files used by the emulator.
autoload.c64
C64 file loaded by start of the emulator
external.c64
The external cartridge ROM image
lib.c64
The C64 program library base
romimage.c64
Combined ROM images of the C64
snapshot.c64
Snapshot image
dirfile.c64
Contains mapping of operating system file names to C64

File formats

romimage.c64 ROM Images

8192 Bytes Basic ROM $A000-$BFFF
8192 Bytes Kernel ROM $E000-$FFFF
4096 Bytes Character ROM $C000-$DFFF

dirfile.c64 Filename conversion

os-name type "c64-name"

os-name
Is the operating system filename. (for DOS 8 character + 3 extension)
type
Is the C64 type of the file ( prg, seq, usr or del ).
"c64-name"
Is the C64 file name enclosed in double quotes.
Examples
	# Disk 2001
	sprites		prg		"sprites"
	name.c64	prg		"a name with space"

Original C64 Documentation

CPU MOS 6510

VIC II MOS 6567 (NTSC) or 6569 (PAL)

SID MOS 6581 or 8580

SID CONTROL REGISTERS

There are 29 eight-bit registers in SID which control the generation of sound. These registers are either WRITE-only or READ-only and are listed below in Table 1.

Table 1. SID Register Map 

	REG #   DATA                                           REG NAME TYPE
	(Hex)   d7    d6    d5    d4    d3    d2    d1    d0
	- --------------------------------------------------------------------

	Voice 1:
	00     F7    F6    F5    F4    F3    F2    F1    F0    FREQ LO  Write
	01     F15   F14   F13   F12   F11   F10   F9    F8    FREQ HI  Write
	02     PW7   PW6   PW5   PW4   PW3   PW2   PW1   PW0   PW LO    Write
	03     -     -     -     -     PW11  PW10  PW9   PW8   PW HI    Write
	04     NSE   PUL   SAW   TRI   TEST  RING  SYNC  GATE  CONTROL  Write
	05     ATK3  ATK2  ATK1  ATK0  DCY3  DCY2  DCY1  DCY0  ATK/DCY  Write
	06     STN3  STN2  STN1  STN0  RLS3  RLS2  RLS1  RLS0  STN/RLS  Write

	Voice 2:
	07     F7    F6    F5    F4    F3    F2    F1    F0    FREQ LO  Write
	08     F15   F14   F13   F12   F11   F10   F9    F8    FREQ HI  Write
	09     PW7   PW6   PW5   PW4   PW3   PW2   PW1   PW0   PW LO    Write
	0A     -     -     -     -     PW11  PW10  PW9   PW8   PW HI    Write
	0B     NSE   PUL   SAW   TRI   TEST  RING  SYNC  GATE  CONTROL  Write
	0C     ATK3  ATK2  ATK1  ATK0  DCY3  DCY2  DCY1  DCY0  ATK/DCY  Write
	0D     STN3  STN2  STN1  STN0  RLS3  RLS2  RLS1  RLS0  STN/RLS  Write

	Voice 3:
	0E     F7    F6    F5    F4    F3    F2    F1    F0    FREQ LO  Write
	0F     F15   F14   F13   F12   F11   F10   F9    F8    FREQ HI  Write
	10     PW7   PW6   PW5   PW4   PW3   PW2   PW1   PW0   PW LO    Write
	11     -     -     -     -     PW11  PW10  PW9   PW8   PW HI    Write
	12     NSE   PUL   SAW   TRI   TEST  RING  SYNC  GATE  CONTROL  Write
	13     ATK3  ATK2  ATK1  ATK0  DCY3  DCY2  DCY1  DCY0  ATK/DCY  Write
	14     STN3  STN2  STN1  STN0  RLS3  RLS2  RLS1  RLS0  STN/RLS  Write

	Filter:
	15     -     -     -     -     -     FC2   FC1   FC0   FC LO    Write
	16     FC10  FC9   FC8   FC7   FC6   FC5   FC4   FC3   FC HI    Write
	17     RES3  RES2  RES1  RES0  FILEX FILT3 FILT2 FILT1 RES/FILT Write
	18     3 OFF HP    BP    LP    VOL3  VOL2  VOL1  VOL0  MODE/VOL Write

	Misc.:
	19     PX7   PX6   PX5   PX4   PX3   PX2   PX1   PX0   POT X    Read
	1A     PY7   PY6   PY5   PY4   PY3   PY2   PY1   PY0   POT Y    Read
	1B     O7    O6    O5    O4    O3    O2    O1    O0    OSC3/RND Read
	1C     E7    E6    E5    E4    E3    E2    E1    E0    ENV3     Read

Table 2. SID Envelope Rates 

	VALUE   ATTACK RATE     DECAY/RELEASE RATE
		Time/Cycle      Time/Cycle
	- ------------------------------------------
	 0        2 ms            6 ms
	 1        8 ms           24 ms
	 2       16 ms           48 ms
	 3       24 ms           72 ms
	 4       38 ms          114 ms
	 5       56 ms          168 ms
	 6       68 ms          204 ms
	 7       80 ms          240 ms
	 8      100 ms          300 ms
	 9      240 ms          750 ms
	10      500 ms          1.5 s
	11      800 ms          2.4 s
	12        1 s             3 s
	13        3 s             9 s
	14        5 s            15 s
	15        8 s            24 s
NOTE: Envelope rates are based on a 1.0 MHz ø2 clock. For other ø2 frequencies, multiply the given rate by 1 MHz/ø2. The rates refer to the amount of time per cycle. For example, given an ATTACK value of 2, the ATTACK cycle would take 16 ms to rise from zero to peak amplitude. The DECAY/RELEASE rates refer to the amount of time theses cycles would take to fall from peak amplitude to zero.

Picture 3. 6581 Envelope 

		  /|\                          - Reg 18: 0-3
		/  |  \                        ^         Max. volume level
	      /    |    \_____________         | - Reg 06,0D,14: 4-7
	    /      |     |            |\       | ^               Sustain level
	  /        |     |            |  \     v v
	-|---------|-----|------------|---|--  --- 0
	 |         |     |            |   |
	 |<------->|<--->|            |<->|
	      |       | Decay           | Release
	      | Attack
Register description
Voice 1
FREQ LO/FREQ HI (Registers 00,01)
Together these registers form a 16-bit number which linearly controls the frequency of oscillator 1. The frequency is determined by the following equation:

Fout = (Fn * Fclk / 16777216) Hz

Where Fn is the 16-bit number in the frequency registers and Fclk is the system clock applied to the ø2 input (pin 6).
For a standard PAL 0.985 MHz clock, the frequency is given by:

Fout = (Fn * 0.058725357) Hz

For a standard NTSC 1.023 MHz clock, the frequency is given by:

Fout = (Fn * 0.060959279) Hz

It should be noted that the frequency resolution of SID is sufficient for any tuning scale and allows sweeping from note to note (portamento) with no dicernable frequency steps.

PW LO/PW HI (Registers 02,03)
Together these registers form a 12-bit number (bits 4-7 of PW HI are not used) which linearly controls the pulse width (duty cycle) of the pulse waveform on Oscillator 1. The pulse width is determined by the following equation:

PWout = (PWn/40.95) %

Where PWn is the 12-bit number in the Pulse Width registers. The pulse width resolution allows the width to be smoothly swept with no discernable stepping. Note that the pulse waveform on Oscillator 1 must be selected in order for the pulse width registers to have any audible effect. A value of 0 or 4095 ($FFF) in the pulse width registers will produce a constant DC output, while a value of 2048 ($800) will produce a square wave.

*********** FIXME: What is correct ***********

[A value of 4095 will not produce a constant DC output].

CONTROL REGISTER (Register 04)
This register contains eight control bits which select various options on Oscillator 1. One of the output waveforms must be selected for oscillator 1 to be audible, however it is NOT nescessary to de-select waveforms to silence the output of voice 1. The amplitude of voice 1 at the final output is a function of the envelope generator only.

NOTE:
The oscillator output waveforms are NOT additive. If more than one output waveform is selected simultaneously, the result will be a logical ANDing of the waveforms.

[Transcriber's note: This is most probably wrong. Some claim that it is the "min" function that is used, but my experience is that it is more complex than that].

Although this technique can be used to generate additional waveforms beyond the four listed above, it must be used with care. If any other waveform is selected while noise is on, the noise output can "lock up". If this occurs, the noise output will remain silent until reset by the TEST bit or by bringing RES (pin 5) low.

Other informations

FAQs

For more information read the following FAQs.

Bug reports

Send your bug reports, patches, improvements, questions and suggestions to johns@av.rwth-aachen.de.

Copyright

The ALE C64 emulator: Copyright (c) 1992-1996 by Andreas Arens, Lutz Sammer and Edgar Törnig.

Contents