
    CONTENTS [INLINE]
   
                              THE C64 EMULATOR
                                       
Emulator Documentation

  Description
  
    _ALEC64_ is a Commodore 64 emulator. _ALEC64_ is written in C.
   
   Following ports exists.
     * Linux with XFree86
     * Linux with svgalib
     * SCO Unix with VGA console
     * Solaris 2.4 for i86
     * DOS with GO32 (32Bit DPMI code)
       Runs also under Win 3.01 and Win95 in full screen mode.
       
   _ALEC64_ can be copied and used absolute freely, but the copyright on
   the sources remains by the authors.
   
  Installation
     * Linux/Unix
     * DOS
       
    Linux/Unix:
    
      Choose your installation directory
      
    For example: /usr/games.
   
      Unpack the archive
      
    tar vxzf alec64-x.xx-elfbin.tar.gz
   This is the elf binary archive.
   
   tar vxzf alec64-x.xx-aoutbin.tar.gz
   This is the aout binary archive.
   
   x.xx is replaced by the version number.
   
      Needed shared libraries
      
   I have compiled the binaries with the following shared libraries.
     * Linux X11 ELF
          + libXext.so.6 (tested with 6.0)
          + libX11.so.6 (tested with 6.0)
          + libc.so.5 (tested with 5.2.18)
     * Linux SVGALIB ELF
          + libvga.so.1 (tested with 1.2.10)
          + libc.so.5 (tested with 5.2.18)
     * Linux X11 AOUT
          + libXt.so.6 (tested with 6.0)
          + libX11.so.6 (tested with 6.0)
          + libc.so.4 (tested with 4.7.2)
     * Linux SVGALIB AOUT
          + libvga.so.1 (tested with 1.2.4)
          + libc.so.4 (tested with 4.7.2)
            
      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 long, no extra
   informations.
   
   If you don't know how to get this images, read the comp.emulators.cbm
   FAQ. See also: C64-ROM-IMAGES 
   
   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
      
   _Note: video-sync versions could be get with -v commandline option! _
   
   c64-svga-sp
          C64 for svgalib with speaker.
          
   c64-svga-o3
          C64 for svgalib with opl3 support.
          
   c64-svga-dsp
          C64 for svgalib with dsp (sound-blaster) support.
          
   c64-svga-os-sp
          C64 for svgalib with overscan and speaker.
          
   c64-svga-os-o3
          C64 for svgalib with overscan and opl3 support.
          
   c64-svga-os-dsp
          C64 for svgalib with overscan and dsp (sound-blaster) support.
          
   c64-x11-sp
          C64 for X11 with speaker.
          
   c64-x11-o3
          C64 for X11 with opl3 support.
          
   c64-x11-dsp
          C64 for X11 with dsp (sound-blaster) support.
          
   c64-x11-os-sp
          C64 for x11 with overscan and opl3 support.
          
   c64-x11-os-o3
          C64 for X11 with overscan and opl3 support.
          
   c64-x11-os-dsp
          C64 for X11 with overscan and dsp (sound-blaster) support.
          
   
   
   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 long, no extra
   informations.
   
   If you don't know how to get this images, read the comp.emulators.cbm
   FAQ. See also: C64-ROM-IMAGES 
   
   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
      
   _Note: video-sync versions could be get with -v commandline option! _
   
   c64-sp
          C64 version with speaker.
          
   c64-o3
          C64 version with opl3 support.
          
   c64-sb
          C64 version with dsp (sound-blaster) support. (don't included)
          
   c64-ossp
          C64 version with overscan and speaker.
          
   c64-oso3
          C64 version with overscan and opl3 support.
          
   c64-ossb
          C64 version with overscan and dsp (sound-blaster) support.
          (don't included)
          
   
   
   copy "selected version" c64
   
      Test it
      
    You can now start the emulator with
   
   c64
   
   To exit press _ALT+PRINT_.
   -or- To exit press _ALT+CTRL+DEL_. (obsolete)
   
  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]
     * -1
       Use keypad as Joystick 1. (Not supported under X11)
     * -2
       Use keypad as Joystick 2. (Not supported under X11)
     * -a pathname
       Load the C64 file 'pathname' automatic at startup.
     * -c path
       Change to the directory 'path' for the emulator.
     * -d pathname
       Use floppy disk image 'pathname' as diskette. (not implemented)
     * -e pathname
       Load the C64 image 'pathname' as external ROM.
     * -f n
       Change the VIC fetch irq position to 'n'.
     * -F n
       Change the VIC fetch read position to 'n' relative to irq
       position.
     * -g geometry
       Geometry of the X11 window.
     * -h
       Display a short help for command line options.
     * -i pathname
       Use the ROM image 'pathname' for ROMS.
     * -j
       Enable hardware joystick. (not enabled)
     * -l pathname
       Use library file 'pathname' as database.
     * -q
       Quiet, do no sound emulation.
     * -r n
       Refresh rate, calculate/emulate only 1/n frames.
     * -u n
       Update rate, display only 1/n frames on X11.
     * -v n
       Video sync the emulator to n% of the original c64. (100 or 0 is
       1:1)
       
     * prgid
       Lookup 'prgid' in library database and start it.
       
    Examples
    
    c64 -1
   
   Start c64 and use keypad as joystick 1.
   
  Environment
  
    You can use following environment variables to runtime configure
   _ALEC64_.
   
     * C64LIB
       Use this file 'pathname' as library database.
     * C64IMAGE
       Use this ROM image 'pathname' for ROMS.
     * C64EXROM
       Use this C64 ROM image 'pathname' as external ROM.
     * C64AUTOLOAD
       Load this C64 binary file 'pathname' at startup.
     * C64PRINTCMD
       Use this os program 'pathname' as printer filter.
     * C64DIR
       Use this directory 'pathname' as working directory for C64. All
       releative paths are relative to this directory.
       
    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
   set 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 the VIC fetch irq position.
          
   SHIFT + F9
          Increments VicFetch the VIC fetch irq position.
          
   F10
          Decrements VicFetchAdd the VIC read position relative to irq
          position.
          
   SHIFT + F10
          Increments VicFetchAdd the VIC read position relative to irq
          position.
          
   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
          Pause the emulator
          
   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.
          
   Alt-Ctrl-Delete
          Leave emulator. (DOS, now obsolete!)
          
   Ctrl-Pause, Intr.
          Reset emulator.
          
  Joystick
  
   The joysticks of the C64 are emulated with the keyboard.
     * ESC (Escape)
       Joystick fire (repeated with AUTOFIRE).
     * Keypad 1
       Joystick down and left.
     * Keypad 2
       Joystick down.
     * Keypad 3
       Joystick down and right.
     * Keypad 4
       Joystick left.
     * Keypad 5
       Joystick fire (_not_ repeated with AUTOFIRE).
     * Keypad 6
       Joystick right.
     * Keypad 7
       Joystick up and left.
     * Keypad 8
       Joystick up.
     * Keypad 9
       Joystick up and right.
       
   
   
   You can control the joystick emulation with:
     * Num-lock
       Toggles joystick 1 or 2 emulation.
     * PRINT
       Toggles autofire on or off (PAL: 25Hz or NTSC: 30Hz).
     * Commandline: -1
       Keypad emulates joystick port 1. (not under X11)
     * Commandline: -2
       Keypad emulates joystick port 2. (not under X11)
       
   
   
   Under X11 the joystick emulations depends of the num-lock state.
   
  CPU MOS 6510
  
   The opcodes counts cycles and all hardware timings are calculate at
   this base.
   
    Supported features
     * All opcodes are supported
     * All addressing modes
     * Peripheral port at $0/$1
     * Most used illegal opcodes
     * Memory wrap
     * ($FF),Y and ($FF,X) bug
     * jmp ($xxFF) bug
     * Read-Modify-Write bug: write first unmodified data, then modified
       
    Missing features
     * Correct decimal mode
     * All illegal 6510 opcodes (missing: $2B,$6B,$8B,$93,$9B)
     * Correct cycles for page boundary crossing (AX,AY,IY)
     * Correct cycles for branch boundary crossing
     * Illegal read of indexed addressing
       
  SID MOS 6581 or 8580
  
   We support emulations of the SID for 3 different hardwares.
     * PC Speaker
     * DSP 8bit sampled data
     * OPL2/OPL3 FM synth chip
       
    PC Speaker
    
   This was very easy to implemented and makes a good sound. In each
   vertical retrace the SID emulations is called, 50 or 60 times per
   second. Each frame a different voice is emulated.
   
   LINUX: I need I/O privileges to use the speaker.
   (ALEC64 must be run as root or must have supervisor rights!)
   
      Disadvantage
      
   No exact emulation.
   
    DSP 8bit sampled data
    
   This is only available for the linux port. The DOS version still hangs
   up. The SID sound is sampled with 22050 Hz and played using
   '/dev/dsp'. This gives you an exact emulation of the SID.
   
      Supported features
     * All waveforms:
          + Triangle
          + Sawtooth
          + Pulse
          + Noise
     * Combine of waveforms.
     * Pulse width.
     * Envelops (Attack,Decay,Sustain,Release).
     * Main volume.
     * Digital samples through D41C.
       
      Missing features
     * Synchronize of voices. _Need better docs_
     * Ring modulation. _Need better docs_
     * Filters.
     * Lockup of noise.
       
      Disadvantage
      
   If you have a slow computer, you here clicks. (Use SCROLL-LOCK or
   SHIFT-SCROLL-LOCK)
   
    OPL2/OPL3 FM synth chip
    
   I convert the writes to the SID register to writes to opl2/opl3.
   
   Did anybody know how todo the puls-width-modulation with a opl3? (mail
   to johns@av.rwth-aachen.de)
   
   LINUX: I need I/O privileges to use the opl3 chip.
   (ALEC64 must be run as root or must have supervisor rights!)
   
      Supported features
     * All waveforms. (Only with OPL3)
          + Triangle
          + Sawtooth
          + Pulse (Only pulse width of 50%)
          + Noise
     * Envelops (Attack,Decay,Sustain,Release)
     * Main volume.
     * Digital samples through D41C.
       
      Missing features
     * Synchronize of voices. _Need better docs_
     * Ring modulation. _Need better docs_
     * Filters.
     * Lockup of noise.
     * Correct pulse width.
     * Combine of waveforms.
       
      Disadvantage
      
   The timings (Attack,...) and envelops are not exact emulated.
   
    Control the SID emulation
     * Commandline: -q
       Turns sound emulation off.
     * Keyboard: F11
       Toggles sound emulation on/off.
       
  VIC II MOS 6567 (NTSC) or 6569 (PAL)
  
   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
     * All video modes
          + Normal text mode
          + Multicolor text mode
          + Extended color text mode
          + Normal bitmap mode
          + Multicolor bitmap mode
          + Illegal modes
            Gives a black display.
     * Complete sprite emulation
          + Normal sprites
          + Multicolor sprites
          + X and Y size doubling
          + Sprite-Sprite and Sprite-Background collision and interrupts
          + Sprite priority
          + Multiplexed sprites
     * 38 or 40 columns mode
     * 24 or 25 lines mode
     * Splitscreens
     * Raster interrupts
     * Open vertical borders
     * Blank mode
     * X and Y smooth scroll register
     * Correct cycle stealing for bad-lines and sprites
     * Idle state (VIC displays the contents of $3FFF of the current
       video bank)
     * FLD (flexible line distance)
     * FLI (flexible line interpretation)
     * Linecrunch
     * Dynamic X scrolling (creature 1 use it)
       
    Missing features
     * In line modifies
     * The correct line fetch position
     * Sprite stretching
     * Sprites in the left or right border.
       
    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).
   (Note: If you use the DSP sid emulation this is done by the sound
   driver!)
   
      vic-fetch
      
   The original c64 displays a video line over a long time (63-64us) one
   pixel after the other. The emulator displays the complete line at a
   specified cycle, this position call I vic-fetch. vic-fetch are the
   cycles from the raster-line-irq to the emulator display.
   
      vic-fetch-add
      
   vic-fetch-add are the cycles from the raster-line-irq to the change of
   the VIC rasterline register.
   
    Control the VIC emulation
     * Commandline: -f n
       Change the VIC fetch irq position to 'n'.
     * Commandline: -F n
       Change the VIC fetch read position to 'n' relative to irq
       position.
     * Commandline: -v n
       Video sync the emulator to n% of the original c64. (100 or 0 is
       1:1)
     * Commandline: -r n
       Refresh rate, calculate/emulate only 1/n frames (DOS,SVGALIB,X11).
     * Commandline: -u n
       Update rate, display only 1/n frames on X11.
     * Keyboard: F9
       Decrements the VIC fetch irq position.
     * Keyboard: SHIFT + F9
       Increments the VIC fetch irq position.
     * Keyboard: F10
       Decrements the VIC fetch read position relative to irq position.
     * Keyboard: SHIFT + F10
       Increments the VIC fetch read position relative to irq position.
     * Keyboard: SCROLL-LOCK
       Change update rate ( 1 ->2 ->3 ->4 ->1 )
     * Keyboard: SHIFT + SCROLL-LOCK
       Change calculation/emulation rate ( 1 ->2 ->3 ->4 ->1 )
       
  1541
  
   The 1541 is emulated on the filesystem. The disk image emulation is
   missing.
   
   Many games could be converted to binary (LINUX) or P00 format. I use
   64copy todo this.
   
   The files on the filesystem could be in binary or P00 format.
   
   You can change the directory for the 1541 emulation with
     * 1541 command "G:directory".
     * Commandline: -c directory
     * Monitor: w directory
       
  Extensions
  
   Extensions to the normal C64 hardware.
   
    ALE-RAM
    
   We have build into our C64 1K additional RAM.
     * 512 bytes at $D200-$D3FF.
     * 512 bytes at $D600-$D7FF.
       
   Some programs uses the mirrored register of the VIC ($D000-$3FFF) or
   SID ($D400-$D7FF) to fool the people.
   
   You can disable the extensions with:
     * Commandline: -x
       
  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.
     * ?
       Show all monitor commands.
     * a from to
     * w directory
       Working directory of the 1541 emulation.
     * X
       eXit _ALEC64_ emulator.
     * FIXME: more to document.
       
  Utilties
  
   I have written some utilities to make the life easier.
   
    bin2p00
    
   Converts ALEC64 binary format to p00 format.
   
  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
   
    lib.c64 The ALE program library base
    
    This is an ascii library database for the easy access of C64
   programs.
   
   Each line has 3 entries:

                program-id      directory       command

   Separate the fields with tabs.
   
   program-id
          Name of the program for commandline
          
   directory
          Directory to enter before the start of game (relative to
          C64DIR)
          
   command
          C64 commands (keyboard input) to start the game. (~ can be used
          for RET, and ^? for F7)
          
      Examples

    # My games
    # program-id        directory               command to start it
    BlueMax             games/synapse           load"blue max",8,1~run~
    SuperSprint         tested/super_sprint     load"loader",8,1~run~^?b

   You can now start the games with:
   c64 BlueMax
   or
   c64 SuperSprint
   
   or even shorter:
   Rename c64 or c64.exe to the program-id.
   
    dirfile.c64 Filename conversion (obsolete)
    
    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"

    *.p00, *.s00, *.u00, *.d00, *.r00 Encapsulate C64 File Images.
    
    This are C64 files, encapsulate to can be used on all filesystems.
   The binary C64 file images with load address are preceded by a 26
   bytes header.
   
      Filename convention
      
   *.p00
          PRG program data file
          
   *.s00
          SEQ sequential data file
          
   *.u00
          USR user data file
          
   *.d00
          DEL deleted data file
          
   *.r00
          REL relative data file (Not supported by _ALEC64_)
          
   
   
   00 can be any number, used to prevend the 16 to 8 name conversion from
   duplicates.
   * can be a up to 8 characters long filename, with the characters in
   the range 64 to 95 ('@' - '_') and 48 to 57 ('0' - '9'.
   
      Header format

    Offset      Bytes   Description
    ------      -----   -----------------------------------
     0          8       String "C64File" terminated by 00.
     8          17      Original C64 Filename.
    25          1       Record size for REL files.
    26          varies  Original file image with load address.

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.
          
          + GATE (Bit 0):
            The GATE bit controls the envelope generator for voice 1.
            When this bit is set to one, the envelope generator is gated
            (triggered) and the ATTACK/DECAY/SUSTAIN cycle is initiated.
            When the bit is reset to zero, the RELEASE cycle begins. The
            envelope generator controls the amplitude of Oscillator 1
            appearing at the audio output, therefore, the GATE bit must
            be set (along with suitable envelope parameters) for the
            selceted output of oscillator 1 to be audible.
          + SYNC (Bit 1):
            The SYNC bit, when set to one, synchronizes the fundamental
            frequency of oscillator 1 with the fundamental frequency of
            oscillator 3, producing "Hard Sync" effects. Varying the
            frequency of oscillator 1 with respect to oscillator 3
            produces a wide range of complex harmonic structures from
            voice 1 at the frequency of oscillator 3. In order for sync
            to occur, oscillator 3 must be set to some frequency other
            than zero but preferable lower than the frequency of
            oscillator 1. No other parameters of voice 3 have any effect
            on sync.
          + RING MOD (Bit 2):
            The RING MOD bit, when set to a one, replaces the triangle
            waveform of output of oscillator 1 with a "Ring Modulated"
            combination of oscillators 1 and 3. Varying the frequency of
            oscillator 1 with respect to oscillator 3 produces a wide
            range ofnon-harmonic overtone structures for creating bell or
            gong sounds and for special effects. In order for ring
            modulation to be audible, the triangle waveform of oscillator
            1 must be selected and oscillator 3 must be set to some
            frequency other than zero. No other parameters of voice 3
            have any effect on ring modulation.
          + TEST (Bit 3):
            The TEST bit, when set to one, resets and locks oscillator 1
            at zero until the TEST bit is cleared. The noise waveform
            output of oscillator 1 is also reset and the pulse waveform
            output is held at a DC level. Normally this bit is used for
            testing purposes, however, it can be used to synchronize
            oscillator 1 to external events, allowing the generation of
            highly complex waveforms under real-time software control.
          + TRI (Bit 4):
            When set to a one, the triangle waveform output of oscillator
            1 is selected. The triangle waveform is low in harmonics and
            has a mellow, flute-like quality.
          + SAW (Bit 5):
            When set to one, the sawtooth waveform output of oscillator 1
            is selected. The sawtooth waveform is rich in even and odd
            harmonics and has a bright, brassy quality.
          + PULSE (Bit 6):
            When set to one, the pulse waveform output of oscillator 1 is
            selected. The harmonic content of this waveform can be
            adjusted by the pulse width registers, producing tone
            qualities ranging from a bright, hollow square wave to a
            reedy pulse. Sweeping the pulse width in real-time produces a
            dynamic "phasing" effect which adds a sense of motion to the
            sound. Rapidly jumping between different pulse widths can
            produce interesting harmonic sequences.
          + NOISE (bit 7):
            When set to one, the noise output waveform of oscillator 1 is
            selected. This output is a random signal which changes at the
            frequency of oscillator 1. The sound quality can be varied
            from a low rumbling to hissing white noise via the oscillator
            frequency registers. Noise is useful in creating explosions,
            gunshots, jet engines, wind, surf and other unpitched sounds,
            as well as snare drums and cymbals. Sweeping the oscillator
            frequency with noise selected produces a dramatic rushing
            effect.
            
            [The Noise output is not "true" random, as it is based on a
            23 bit internal register].
            
   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.
          
TODO

   The following things should be done.
     * Floppy disk image support.
     * Support DSP (soundblaster) under DOS.
     * Cleanup of sources.
     * Write more documentation.
     * Enable and test support of hardware joysticks.
     * Use xresources for color configuration.
     * Support the paddles and joystick under X11 with mouse.
     * Screen shot.
     * Record of c64 sound.
     * Snapshot of emulation.
     * Rewrite sprite routines for more speed.
     * Write a real 1541 emulation.
       
Other informations

  News groups
  
    For information, questions and help you can look into following news
   groups:
     * comp.sys.cbm 
     * comp.emulators.cbm 
     * comp.emulators.misc 
       
  FAQs
  
    For more information read the following FAQs.
     * comp.sys.cbm Commodore FTP sites list.
     * comp.sys.cbm General FAQ.
     * comp.emulators.cbm FAQ.
     * comp.emulators.misc FAQ.
       
C64-ROM-IMAGES 

   Information to get original C64 ROM Images.
   
     * ftp.funet.fi
       
        c64-basic.901226-01
                Commodore 64 BASIC V2. The first and only revision.
                
        c64-kernal.901227-01
                Commodore 64 KERNAL ROM Revision 1. The RS-232 timing
                table is designed for exactly 1 MHz system clock
                frequency, although no C64 runs at that clock rate.
                Ripped from a very old American C64.
                
        c64-kernal.901227-02
                Commodore 64 KERNAL ROM Revision 2. Can be found on 1982
                and 1983 models.
                
        c64-kernal.901227-03
                Commodore 64 KERNAL ROM Revision 3. The last revision,
                also used in the C128's C64 mode.
                
        c64-kernal.sx
                Commodore SX64/DX64 KERNAL. With different startup
                colors, and tape routines disabled.
                
        characters-c64
                Commodore 64 character set. Every vertical line is at
                least 2 pixels wide in order to avoid color errors on
                television. Also the C=M and C=G graphic characters have
                been made 2 pixels wide, which is an error.
                
     * If you know more sources let me know.
       
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
   Trnig.
   
   You can use and copy the binaries freely.
   
Contents

     * Emulator Documentation
          + Description
          + Installation
          + Command line options
          + Environment
          + Keyboard
          + Joystick
          + CPU MOS 6510
          + SID MOS 6581 or 8580
          + VIC II MOS 6567 (NTSC) or 6569 (PAL)
          + Extensions
          + Monitor
          + Utilities
          + Files
          + File Formats
     * Original C64 Documentation
          + CPU MOS 6510
          + SID MOS 6581 or 8580
          + VIC II MOS 6567 (NTSC) or 6569 (PAL)
     * TODO
     * Other informations
     * C64-ROM-IMAGES
     * Bug reports
     * Copyright
