
	
				 VICE 0.13.0
				 ~~~~~~~~~~~
				 
			  MSDOS-specific information

			   official VICE home page:
		    http://www.tu-chemnitz.de/~fachat/vice
			  


[There is no real documentation for the MS-DOS version of VICE at the moment.
 Please refer to the Unix manual (doc/MANUAL.html) for the main concepts.  This
 file is only supposed to get you started.

 If you feel like helping us to maintain the MS-DOS version of the
 documentation, you are of course welcome.  Just contact ettore@comm2000.it.]


OVERVIEW
--------

VICE is a set of emulators for the PET, VIC20 and C64 Commodore 8-bit machines
running on MS-DOS, Windows 95 and Unix systems.

The C64 emulator is very advanced, and features a rather complete cycle-exact
emulation of all the chips, including the VIC-II video controller, the two CIA
interface adapters and the SID sound device.

On the other hand, the VIC20 and PET emulators are still under construction.
They emulate the audio and the most important features in the video chips, but
the emulation of the VIAs (Versatile Interface Adaptors) is not very accurate
yet.  Anyway, this should be already enough for running most programs.

When running the VIC20 and C64 emulators, also a hardware-level emulation of
the Commodore 1541 5"1/4 disk drive is available.


SYSTEM REQUIREMENTS
-------------------

This has not been tested thoroughly, but the minimum requirements should be:

 - a Pentium-class machine or better;

 - 8 Mbytes of RAM;

 - a register-compatible VGA graphics card (better if it is also SVGA and 
   VESA-compliant);

 - MS-DOS 5.0 or later (or Windows 95).

Moreover, VICE optionally supports standard PC joysticks and the following 
sound cards:

 - Creative Labs Sound Blaster series (1.0 through SB 16 and AWE32);
 
 - Gravis UltraSound (regular, MAX, and Plug and Play);
   
 - Media Vision Pro Audio Spectrum series (PAS, PAS+ and PAS16);
 
 - Microsoft Windows Sound System and compatible cards using the 
   Crystal/Analog CODEC (most inexpensive 16-bit sound cards sold nowadays 
   are WSS compatible).


INSTALLATION
------------

There is no particular installation procedure for the MS-DOS version of VICE.
Just unzip the archive by keeping the directory structure intact (you need to
use `pkunzip -d' if you use PkZip).

VICE should be able to auto-detect most sound cards by itself, but there might
be problems with some of them (e.g. Windows Sound System cards).  So it is a
good idea to force a sound card setup by running the emulators with the
`-dosoundsetup' option the first time you have installed VICE.  For example,
type `x64 -dosoundsetup' at the DOS prompt, which will run the MIDAS sound
setup before running the C64 emulator.

The only settings that are relevant in the MIDAS sound setup are the sound
card type and IRQ/port settings.  The other ones are automatically set by the
emulator as soon as the emulation is fired up.  The settings are saved in a
`MIDAS.CFG' file in the VICE directory, so you do not have to do this more
than once if you want to keep the same configuration.  Also notice that you do
not have to configure the three emulators separately, as the same `MIDAS.CFG'
file is used by all of them.

The joystick does not require calibration.  Just plug it in.


HOW TO RUN THE EMULATORS
------------------------

There are three executables for the three PET, VIC20 and C64 emulators:

      x64.exe	the C64 emulator
      xpet.exe	the PET emulator
      xvic.exe	the VIC20 emulator

To run them, just type the corresponding name at the DOS prompt.

`xpet.exe' actually emulates 3 PET models (3032, 4032, 8032).  You can select
which machine you want by loading the right kernal ROM image, with the
`-kernal' command-line option.  In fact, `xpet' will compute the ROM checksum
and then select the machine type accordingly, without the need to change other
settings.  So you basically have to do:

      xpet -kernal kern3032	for the PET 3032 emulator
      xpet -kernal kern4032     for the PET 4032 emulator
      xpet -kernal kern8032     for the PET 8032 emulator (80 column)

As soon as the emulator is started (and the sound setup has been finished, if
you have requested it), you should get the bootup screen of the emulated
machine on your screen.

You can access the emulator menu by pressing `ESC'.  By pressing `ESC' again,
you can go back to the emulation screen.


KEYBOARD LAYOUT
---------------

The layout of the VIC20 and C64 keyboard is pretty much the same as the one of
the real machine.  Some keys did not fit too well in the PC keyboard and had
to be moved around.  These keys are:

    Alt		Commodore
    Delete	Arrow Up
    Insert	Pound
    Home	CLR/HOME
    Page Up	RESTORE

The PET keyboard layout is a bit more complicate and varies according to the
model (``graphics'' keyboard for the 3032/4032, ``business'' keyboard for the
8032).

The following keys perform special actions:

    F12		soft reset
    Ctrl-F12	hard reset (wipes out RAM)
    PgUp	Restore

The joystick directions are emulated through the numeric keypad; the right
Ctrl key or the 0 (zero) on the keypad emulate the fire button.


THE EMULATOR MENU
-----------------

In the emulator menu you can select items by using the cursor keys and
pressing Enter or by hitting the corresponding highlighted initial.  If you
move around with the cursor keys, a short description of the command appears
on the bottom line.  Press ESC to exit a sub menu.

Here is a short list of what the various items do:  (for more information,
refer to the Unix documentation)

 - Attach disk/tape image: attaches a disk or tape image for use in the
   virtual cassette/disk drives.

 - Detach disk/tape image: detaches a disk or tape image from the drive.
   Notice that, when a T64 tape image is attached, VICE emulates a pressed
   PLAY button on the cassette recorder.  This should not do any harm in most
   cases, but some programs do not like it; if you experience any weird
   problems, try to detach the tape image after you have loaded it.

 - Change working directory: changes the directory for drive #11 and also
   affects all the following commands.

 - Joystick settings (x64 only): allows you to select in which port the
   emulated joysticks should be plugged in.

 - Video settings: this is a sub-menu from which you can specify the desired
   refresh rate, enable/disable sprite collisions (on the C64) and select the
   VGA mode you want.  The following resolutions are supported:

     320x200 (linear)
     640x480 (linear, requires a VESA-compliant SVGA card)
     360x240, 360x270, 376x282, 400x300 (planar)

   Warning: the planar resolutions might not work on your equipment!  Some
   monitors do not like to be fed with strange frequencies, and although we
   have never heard of any damages resulting from these resolutions, we cannot
   give any warranties about that.

   Moreover, please notice that the mode-X resolutions are _much_ slower than
   the linear ones, so the performance will be worse with them.  If you
   install the Scitech Display Doctor (http://www.scitechsoft.com), also
   360x240 will be linear (which is very useful) and will run nearly as fast
   as 320x200 in many cases.  Unluckily, SDD is shareware and you will have
   to pay for it.

   The VGA mode in the PET emulator is hard-coded: you will get 320x200 for
   the 3032/4032 and 640x480 for the 8032.

   From this menu you can also enable or disable the video cache.  Notice that
   on MS-DOS the video cache is not as useful as on X-Window.  Anyway, it
   should make things faster when you work with text-mode applications (the 
   difference in performance is bigger with the PET and VIC20 emulators).

 - Drive settings (C64/VIC20 only): this sub-menu specifies the parameters for
   the hardware-level emulation of the 1541 disk drive.  If the programs you
   are running do not need accurate emulation of the disk drive, keep the
   ``true'' 1541 emulation turned off as it is much faster this way.  On the 
   other hand, if you run games that require turboloaders or other features 
   that are not supported by the fast disk-drive emulation you should keep it 
   turned on.

   The 1541 ``idle method'' selects the way the 1541 CPU is emulated.  With
   the ``Skip Cycles'' method, each time the serial line is accessed by the
   computer the drive executes all the cycles since the last time it was
   running; if the number of elapsed cycles is larger than a certain value,
   the drive discards part of them.  With the ``Trap Idle'' method, the disk
   drive is still emulated upon serial line accesses as with the previous
   option, but it is also always emulated at least at the end of each screen
   frame.  Moreover, if the drive gets into the DOS idle loop, only pending
   interrupts are emulated to save time.

   The first option (``Skip cycles'') is usually better for performance, as
   the drive is emulated as little as possible; on the other hand, you can
   notice sudden slowdowns (when the drive executes several cycles at once).
   Moreover, if the drive tries to get in sync with the computer in some weird
   way and the computer does not access the serial line for a long time, it is
   possible that some cycles are discarded and the sync is lost.  Notice that
   this hack can have no effect on performance if one program continuously
   reads the CIA ports, as the drive will have to be emulated in any case.

   The second option (``Trap idle'') is usually a bit slower, as at least
   interrupts are always emulated, but always keeps the 1541 and the computer
   in sync.  On the other hand, if a program installs a non-standard idle loop
   in the drive, the 1541 CPU has to be emulated even when not necessary and
   the global emulation speed is then much slower.

   If the ``Trap Idle'' method is enabled, the Scroll Lock LED of the keyboard
   will emulate the 1541 drive LED.

 - Sound settings: specifies the parameters for the sound emulation.  Sound
   playback only works if you have specified a 100% speed limit, and is turned
   off with an error message otherwise.  Moreover, it eats some CPU speed.

 - Special options: allows you to enable the 1750 512K RAM Expansion
   Emulation, the virtual IEEE488 interface and the CPU emulation detection
   (all of these features are C64-only), and to specify a custom speed for the
   emulation.

   Notice that the REU contents are saved in a `REU.C64' file in the same
   directory as `X64.EXE', and are loaded back when you start the emulator
   again.

 - Reset: resets the machine.  The are two types of reset: the ``hard'' one
   which wipes out the RAM as if the machine had been turned off and on, and
   the ``soft'' one which simply emulates a standard reset button and
   preserves the memory contents.  The soft reset can be performed from the
   emulation screen by pressing `F12'; the hard one by pressing `Ctrl-F12'.
   ``Soft'' reset is sometimes not enough for certain games.

 - Monitor: enters a (very) simple machine-language monitor.  Type `x' to go
   back to the emulation.

 - Write settings, Load settings: with these options, the current settings are
   saved in a `VICERC' file in the VICE directory.  The settings for the three
   emulators are saved in separate sections of the file and do not interfere
   with each other.

 - VICE info: displays some information about the authors, the copyright and
   the GNU License;

 - Quit: exits the emulator.


CONTACTS
--------

You can always find the latest news about VICE at the official VICE home
page:

  http://www.tu-chemnitz.de/~fachat/vice

Also the public patches and beta releases will be available there, so you
might want to have a look at it periodically.  If you are going to report a
bug, please check those pages first; it is possible that the problem you
encountered has already been fixed in a more recent version.  Also notice
that, since VICE is released under the GNU General Public License, the sources
are available from the home page too.

If you want to report bugs, make suggestions or contribute to the project,
e-mail one of the following people:

  Teemu Rantanen (tvr@cs.hut.fi)  for the sound stuff;

  Andre' Fachat (fachat@physik.tu-chemnitz.de)  for the PETs;

  Ettore Perazzoli (ettore@comm2000.it)  for everything else.

 
COPYRIGHT
---------

VICE is Copyright (c) 1993-1997 Ettore Perazzoli, Teemu Rantanen,
Andre' Fachat, Jouko Valta, Jarkko Sonninen and Daniel Sladic.

   This program is free software; you can redistribute it and/or modify 
   it under the terms of the GNU General Public License as published by 
   the Free Software Foundation; either version 2 of the License, or 
   (at your option) any later version.
    
   This program is distributed in the hope that it will be useful, 
   but WITHOUT ANY WARRANTY; without even the implied warranty of 
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
   GNU General Public License for more details. 
    
   You should have received a copy of the GNU General Public License 
   along with this program; if not, write to the Free Software 
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 

The MS-DOS version of VICE was made possible by two great libraries:

  - Allegro, a Game Programming Library by Shawn Hargreaves
    (http://talula.demon.co.uk/allegro);

  - MIDAS Digital Audio System, a sound library for MS-DOS/Windows/Linux by
    Petteri Kangaslampi and Jarno Paanen (http://www.s2.org/midas).

There have also been contributions from several people around the world: look
at the Unix documentation or at the ``VICE Info'' command for a complete list.
