
  VICE  V 0.11 PL 0						31 July 1996


			      The one and only
		 _______________
		|      ||      ||
		|      ||      ||____________________________
		|      ||      ||    ||         ||          ||
		|      ||      ||    ||    |    ||    ______||
		|      ||      ||    ||    |----||          ||
		|      ||      ||    ||    |    ||    ------||
		|              ||____||_________||__________||
		 \            // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
		  \          //
		   \________//   Versatile Commodore Emulator



		written completely in highly portable C language


  ----------------------------------------------------------------------------


	VICE -- The Versatile Commodore Emulator and Simulator

  This is a Commodore 64/128/VIC20/PET Emulator for XWindow System,
  Version 11 (X11).

   VICE is the one and only versatile CBM 8-bit emulator. It provides you with
   complete emulation of the 6502/6510/7501/8500/8502 CPU as well as Zilog Z80,
   both with undocumented opcodes and single-step capability.
   The 6510 Simulator provided with graphical user interface can even be used
   not dependending on any specific machine.

   Easy to use built-in Machine Language Monitor allows one to freeze and save,
   study, re-run, and debug ML programs on any of the machines emulated.
   Both extensive documentation and on-line help are provided to support anyone
   learning or using the 6510 Machine Language.

   VICE is targeted for C64 enthusiasts and programmers. It's also suitable for
   the average user of other C64 emulators like C64S, PC64, or X64.
   Tools are provided to convert files from other emulators' unsupported file
   formats to the supported ones.

   Unlimited number of emulator processes can be run independent of each other
   on any Unix or Linux system with XLib and color palette support.

  ----------------------------------------------------------------------------


  INDEX
	 1.  Important notice

	 2.  Distribution
		2.1  FTP Sites
		2.2  Contents
		2.3  What else you'll need

	 3.  Hardware requirements
		3.1  Portability
		3.2  Porting
		3.3  Speed

	 4.  Installation

	 5.  Using the Emulators
		5.1 Setting Up Your Environment
		5.2 Command line options

	 6.  Using 1541 Emulation

	 7.  Using Printer Emulation

	 8.  The ROM Images
		8.1 The ROM images:  Where to get those - and how ?
		8.2 Different ROM versions
		8.3 C128 ROMS
		8.4 C64 Basic and Kernel
		8.5 VIC20 / VC20 ROMS
		8.6 PET 30xx/40xx/80xx ROMS

	 9.  Common troubles
		9.0 Setup
		9.1 ROM Images
		9.2 X11
		9.3 Resetting the keyboard
		9.4 Compiling Z80
		9.5 Imake and make
		9.6 Getting more help
		9.7 Manuals, anyone?

	 10.  Copyright
		10.1 The Emulators
		10.2 The Zilog Z80 CPU Emulator
		10.3 Matrix Printer Emulator

	11.  Notes

	12.  Authors



 1. IMPORTANT NOTICE

  One copy of the ROMs of each emulated machine is required to operate. Since
  those ROMs are still copyright-protected, you will have to grab your own
  copy of them and install them as specified in chapter 8, "The ROM Images".
  DO NOT ask us to send them, since we won't do it.

  For further information refer to the VICE homepage:
	    http://stekt.oulu.fi:/~jopi/vice.html

  You can also send e-mails to the current maintainer:
  
	    Ettore Perazzoli (ettore@comm2000.it)



 2. DISTRIBUTION

  2.1  FTP SITES

  The FTP sites where you can look for to fetch VICE are the following
  and their mirrors.
  Note: The newest version (or any of them) is not necessarily on each
  of these sites.

  Primary-site:
	sunsite.unc.edu:/pub/Linux/system/Emulators/

  Alternate sites:
	frodo.hiof.no		  /c64/emulator/
	ccnga.uwaterloo.ca	  /pub/cbm/emulation/
	wilbur.stanford.edu	  /pub/emulators/c64/
	ftp.funet.fi		  /pub/cbm/c64/emulation/
	ftp.giga.or.at		  /pub/cbm/emulation/unix/

  Files
	vice-0.11.0.tar.gz	Full release
	vice-docs.tar.gz	Docs only
	petcat-2.01.tar.gz	petcat only


  ROMs not included. Follow the instructions in the VICE documentation to
  obtain the files required.



  2.2  CONTENTS

   The VICE V0.11 emulates the following machines and peripherals:


					Availability
			 (Unix/PC/Amiga)
	Emulation	     X11/XFree	Sun Console	MS-DOS
	-------------	     ----------------------------------

	 C-64			 x	  -		 -
	 C-128			 x	  -		 -
	 VIC-20/VC-20		 x	  -		 -
	 C-16			 -	  -		 -
	 Plus/4			 -	  -		 -

	 PET 3032/4032/8032	 x	  -		 -
	 PET 4064/8064		 -	  -		 -
	 PET 4096/8096		 -	  -		 -

	 C-1541, Disk Images	 1-3	  1		 1-3
	 C-1541, Filesystem	 1	  1		 1
	 C-1541, Floppy Disk	 -	  -		 -

	 C-1571, Disk Images	 -	  -		 -
	 C-1571, Filesystem	 -	  -		 -
	 C-1571, Floppy Disk	 -	  -		 -

	 C-1581, Disk Images	 -	  -		 -
	 C-1581, Filesystem	 -	  -		 -
	 C-1581, Floppy Disk	 -	  -		 -

	 9-pin Matrix Printer	 2	  1-2		 -


   Additional Tools

	petcat    - convert, tokenize and expand BASIC and text files
	ReComment - versatile 6510/65ce02 disassembler/reassembler
	c1541     - disk image maintenance and conversion tool


   File Formats Supported

			Emulator	c1541		petcat
			------		------		------
ASCII conversion	-		yes		yes

CBM binaries		yes		yes		yes
P00 File Images		yes		yes		yes
X64 Disk Images		yes		yes		no
.D64 Disk Images	yes		yes		no
.T64 tape Images	yes		import		no
.C64 Game Images	no		no		no



  ----------------------------------------------------------------------------

  The archive contains C-sources for the following programs:

 x64    C64 emulator for X windows.

 x128	C128 emulator for X windows.

 xvic   VIC20 emulator for X Windows.

 xpet   PET 3032/4032/8032 emulator for X Windows.
 
 c1541  Disk drive emulator. In addition to operating in x64 the
        1541 emulator runs as separate program, by which disk images can be
        created and maintained. Supports PRG and SEQ file types and
        disk <-> Un*x copying.

 petcat	 converts text and expands tokenized basic programs into readable
	ascii form, and tokenizes programs from program listings.
	For Unix and Atari ST.

 
  In addition to these programs the archive contains:

 64doc		   Complete documentation of the 65xx/75xx/85xx CPU family
         	   instruction set, including cycle-by-cycle operations.
 cbm_basic_tokens  List of all CBM Basic Keywords supported.
 Emulation	   Extensive reference manual for emulator users.



  2.3  What else you'll need

 Of course, you need the ROM code for each machine emulated. See
 "The ROM Images" for details.

 In addition to programs included in the VICE distribution, you might
 need the following tools:


	fvcbm
		by Dan Fandrich
		FVCBM lists the contents of most Commodore archives.

	cbmconvert
		by Marko Mkel
		CBMCONVERT provides you with a set of programs to dissolve
		Commodore archives.

	GfxConvert
		by Pasi Ojala
		converts Commodore 64 Image formats

	prlink
		by Marko Mkel and Olaf Seibert
		ftp.funet.fi:/pub/cbm/

		It is a set of utilities to transfer data between CBM 8-bitters
		on one side (PET, VIC-20, C=64, C=128) and Linux/i386 or Amiga
		machines on the other side.
		Handles .d64 files, memory contents and files.

	xkeymaped
		by Hannu Helminen
		Interactive proram to create keyboard layout modification file
		for xmodmap(1).



 3. HARDWARE REQUIREMENTS

 In order to run VICE you need either:
   * a Unix machine with XWindows and MIT X11 R5 or R6 support,
   * a 386, 486 or Pentium PC running Linux and XFree 2.1 or higher, or
   * a >586 PC running OS/2 with XWindows emulation. Unlike with Linux,
     at least a 80786 CPU is recommended.

 Colour display is required. Not true color, though.


  3.1  PORTABILITY

  To compile X64, you need an ANSI C compiler or an ANSI C to K&R
  preprocessor.
  For use with old-fashioned K&R compilers there are several
  converters available. For example, one is in the directory
  ftp://ftp.funet.fi/pub/archive/comp.sources.misc/volume27/unproto/.

  The VICE version 0.11 has been successfully tested on:

	IRIX 5.1.1.2,
	Linux 2.0.0 with XFree86 3.1.2 (X11R6) or 2.1 (X11R5),
	SunOs 4.1.1 with X11R5,
	SunOs 4.1.3 with X11R5 and Openwindows 3.0,
	SunOS 5.3, 5.4 with Openwindows 3.2,
	Ultrix 4.3, 4.4
	Amiga Linux 68K

  In case you machine does not have the Xpm and/or MITSHM libraries,
  remember to comment out the appropriate #define lines in config.h.

  MITSHM might still give troubles with some machines (notably on
  Amigas and HPs); if you can't make it work, try to disable it.



  3.2  PORTING

  Here are some hints:

  First of all, check out types.h and change what is needed.

  In cpu.h, mshell.h, serial.h, and types.h:
  Some compilers want
	int    (*funcp) ();
  instead of e.g.
	int    (*funcp) (void);


  xdebug.c includes <X11/StringDefs.h> for standard string definitions.
  Alas, there are X11 set-ups which don't contain declarations for
  "XPointer" or "XtPointer" or neither of them.

		typedef char *XPointer;
		typedef void *XtPointer;

  There are a few defines to ease changing the default set-up:

		EDIT		Enables command line editor.
		X_022		Replaces the new Xdebugger with older one
		XDEBUGGER	Enables the debugger
		X_NOT_STDC_ENV	This was found in <X11/StringDefs.h>

  For readline/ one may #define NO_FORW in the readline/Imakefile if
  forward references cause trouble.

  In Makefile, remove any lines between
	# dependencies generated by makedepend
  and
	# DO NOT DELETE

	
  3.3  SPEED

    VICE 0.11.0 provides a much better performance, since the CPU emulator is
    now >2 times faster and some other parts have been improved too. Anyway,
    its speed is not very high yet and we are still working on the code to
    make it suitable for the slowest machines too.

    The relative speed of the emulation can change quite a lot, depending on
    the configuration, the compiler, the command-line settings and (obviously)
    the computing power on the machine used. The relative speed of the
    emulator is always displayed in the title bar of the emulation window (the
    C128 speed refers to the 1 MHz clock).

    On a Linux PC with a 100 MHz Pentium, you can always have >100% relative
    speed on x64 with the refresh rate option set to 2 (see section 5 for more
    info) if compiled with the suggested optimization options which can be
    found in the Imakefile. On most applications, if your graphic card is fast
    and well supported by XFree, setting refresh rate to 1 will still give you
    100% performance with smoother animation.

    Enabling the sprite-sprite and sprite-background collision register
    emulation will slow down the emulation a bit, and programs with complicate
    raster effects and sprite animations will surely run slower than simple
    text-only programs.

    If you don't want the emulation to be completely unusable, enable MITSHM
    whenever it is possible. Moreover, gcc usually gives better optimized code
    than proprietary compilers.

    We encourage you to send us speed reports of the emulators -- if you want
    to do so, please specify which compiler you used, the options in config.h
    and on the command line and which sort of activity the report refers to
    (eg. the name of the program).


  4. INSTALLATION

	To compile the VICE

	4.0	unshar, untar or do whatever needed and enter the `src'
		subdirectory.

	4.1     edit Imakefile, i.e. choose c-compiler, flags and libraries.

	4.2	edit config.h to define the emulator set up.
		These options are available:

		NO_INLINE
			Be sure to COMMENT OUT this option if your compiler
			supports the __inline__ keyword for function inlining
			(e.g. gcc in all recent versions).
			If it does support inline functions but it needs a
			different keyword, edit raster.h and change the INLINE
			#define.

		SYSINFO
			Comment this out if your system does not have
			sysinfo(2).

		XPM     Comment this out if your system does not have the Xpm
			library (eg. HP workstations)
			You'll have to do without some nice icons, then... ;)
			
		PAL or NTSC
			Adjusts C64 timing according to the display system.
			Only one of the two defines must be activated!
			(the NTSC mode has not been thoroughly tested yet)

		REFRESH_RATE
		        If you want 1/x of the actual frames to be repainted,
 		        set REFRESH_RATE to x.  It is not very important in
 		        text mode (optimizations do their job well there :) but
 		        when running games it is almost fundamental -- setting
 		        it to a low value on a slow machine might make it
 		        unusable...

		DOUBLE_X, DOUBLE_Y, TRIPLE_X, TRIPLE_Y
			For each of the emulated video chips, you can choose
			to increase the window size. This is not a wise idea
			when using an X-Terminal and/or a slow machine.

		PET_CUSTOM_SPEED, C64_CUSTOM_SPEED, VIC20_CUSTOM_SPEED,
		C128_CUSTOM_SPEED
			Forces the emulators to keep the selected speed if
			possible.
						
		AUTOREPEAT
			Enforces the emulators to run without KeyRelease
			events.

		US_KBD  Swaps asciicircum with asciitilde.

		REPEAT_DELAY
			Allows the emulator to filter out excessive key
			events.
			
		DECMAP	Adds DEC specific editing keys to the conversion
			table.

		DEBUG	Enables some debugging information.

		HAS_ZILOG_Z80
			Enables the Z80B CPU on x128.

		CHECK_SS_COLL, CHECK_SB_COLL
			Enable the sprite collision registers in x64 and
			x128 by default.

		USE_VDC	Enables the VDC (80 column) video chip in x128.

		PET_COLS
		        Specifies the default PET model: 40 column (3032,
			4032) or 80 column (8032).

	        ROMPATH Specifies the directory source for the system ROMs.

		PROJECTDIR
			Specifies the directory which contains the ROMs for
			each specific emulator (x64, x128, xvic and xpet).

		KERNELNAME, CHARGENNAME, RAMNAME, BASICNAME, BIOSROM_NAME,
		EXROMNAME
			Specify the names of the ROMs and of the RAM image.

		CBMTAPE
			Enables the T64 tape image support (x64 and x128
			only).

		XCONTROL, XDEBUGGER
			Specifies whether you prefer the new Xaw-based
		        XDebugger (still under construction) or the old
		        Xlib-based XControl.

		IEEE488 Enables the Commodore IEEE488 Interface Adaptor
		        emulator in x64.

		LED_ARRAY
			Enables a Virtual Bus Tester which shows the Bus
			activity of the emulated machine. 

		EDIT    Activates a command line editor with history and file
		        name completion in the monitor and in c1541.

		COPY_TO_LEFT

		        Since the C1541 DOS copies files to the first argument
		        of the `copy' command, whereas they normally go to the
		        last file, you can change the 'c1541' copy syntax via
		        this option.

		REU	Installs the RAM Expander emulator
		REUSIZE Defines the size of the REU

		EMULATOR_ID
			Enables Wolfgang Lorentz' emulator identification
			method, which will allow VICE to be recognized by the
			``Who am I'' program.
			
		KBDBUG, KBDBUD2
			Turns on the keyboard debug mode.

		[In the `Experimental' section you will also find some new
		features which are still being worked on and which are
		unfinished yet. Don't expect them to be really useful...]

		Notice: Since the only thing preventing a C128 from being
		expanded to 256KB is a hardware inadequacy, it can be emulated
		as well.  To expand it, change #define RAMSIZE to 0x40000 in
		memory.h.

	4.3	xmkmf -a
		(Use the `-a' option)

	4.4     Compile VICE with

		make

	4.6	Create the ROM images. See chapter 8 "The ROM Images" for
		details.


	strip(1)'ing the executables is highly recommended.


    Notes:

     Compilation under SCO (untested):
	Include in LOCAL_LIBRARIES the additional library -lx, to get the
	style of directory routines used. Also, include -lx on the CC line
	for $(C1541TARGET).

	

 5. USING THE EMULATOR

  5.1 Setting Up Your Environment

  To select the default X server to connect to:

	setenv DISPLAY "`uname -n`:0"

  For a remote server, use the terminal name instead. Also, use xauth(1) or
  xhost(1) to give the server the needed permissions to make the connection.

  If you have an 8-bit ;) machine, add the following line to your .login:

	setenv LC_CTYPE iso_8859_1


  5.2 Options

    Command line options:

  x64, x128, xvic, xpet
        [-/+40] [-/+80] [-asm] [-basicName <value>]
	[-biosName <value>] [-brevision <value>] [-/+checksb]
        [-/+checkss] [-/+colors] [-debug] [-directory <value>]
        [-display <value>] [-exromName <value>] [-floppy <value>]
	[-fn <value>] [-halt] [-/+hex] [-joyport <value>]
	[-kernelName <value>] [-load <value>] [-module <value>]
	[-/+mitshm] [-name <value>] [-printCommand <value>]
	[-ramName <value>] [-refresh <value>] [-reuName <value>]
	[-revision <value>] [-speed <value>] [-test] 
	[-/+traps]

	-40, -80
	        on x128, these ones activate the VIC-II (40 column) and VDC (80
		column) video chip emulators, which can also run together (each
		video chip will have its own window, as if using two monitors).
		On xpet, this specifies the screen size -- if you don't specify
		any of them, the emulator will auto-detect the kernal used and
		set the screen size properly.

	-asm	enter to Monitor/debugger upon initialization

	-halt	open debug window upon initialization

	-test	enable Monitor debugging information

	-hex	toggle Monitor number base between hex and dec.

	-debug	enable debugging information

	-verbose
		these two commands produce huge amount of
		debugging info, which slows the emulator down.

	-directory 'project directory'
		to search for basic and kernel and dump ram
		otherwise they are searched from project dir which 
		is configurable in compile time (default '.')

	-basicName 'name'
	-kernelName 'name'
		Specify alternate ROM images.

	-revision 'number'
		Causes the loaded kernel to be patched to different revision.
		For  64, the alternatives are: 0, 3, 67, and 100.
		For 128: 1 = Swedish, 2 = German, 3 = American.

	-brevision 'number'
		Patches the C128 Basic between revisions 85 and 86.

	-exrom 'exrom'
		specify the file to be used as cartridge ROM in slot
		selected via -module option.  As default the name is "exrom".

	-module 'n'
		select the memory area where the module is located:
		    1 = 8000-9FFF  2 = A000-BFFF  3 = 8000-BFFF

	-floppy 'diskimage'
	-8 'diskimage'
	-9 'diskimage'
		attaches the specified file containing a floppy disk image in
		unit 8 (-8, -floppy) or 9 (-9).

	-tape 'tape'
	        attaches the specified tape image.

	-reu 'reu'
		If installed in compilation, activates the RAM Expansion Unit
		and specifies the filename for RAM image of the REU.  Existing
		file is loaded to memory upon startup.
		The default filename is "reu".

	-load 'program'
		to load into ram on startup. There has to be the start
		address included in the beginning of the program.

	-start 'address'
		is a hex value which is loaded to program counter in startup.
		The default is RESET (FCE2).  With a BASIC program being
		loaded, better result may be achieved by using the system warm
		start vector (FE66) instead.

	-joyport 'n'
		emulate joystick in port #n via numpad.
		If LINUX_JOYSTICK is enabled in config.h, the `real' joystick
		will be in port 2-n.

		
    The following keys have a special meaning for x64:

     F1 F2 F3 F4 F5 F6 F7 F8
		  The C64 function keys

     asciicircum or asciitilde
		  up arrow (on US and scandinavian keyboards respectively).

     underscore   right arrow

     bar	  Pound Sign

     Backspace	  Inst

     Linefeed	  Shifted Return

     Control_L	  Control

     Alt_L	  CBM Key (Press down Left Shift and then Alt to change
                  character set.)

     Escape	  STOP

     Tab	  Restore

     Shift_R	  The Right Shift key can be used to achieve characters
		  shifted on the actual keyboard but unshifted on the C64 one.

     Numeric Keypad

                  On x128, xvic and x64, it emulates a `virtual' joystick,
		  plugged into the port specified by the -joyport option. The
		  keys operate as follows:

					 8 (up)
					 ^
					 |
			   (left) 4 <----+----> 6 (right)
					 |
					 v	
			                 2 (down)

			          0 (fire)
				  

  Left mouse button enters monitor/debugger

  Right mouse button toggles the X-debugger window (still under construction)

  When the emulator has successfully loaded kernel and basic it tries also to
  load an old ram from file (Reset condition). If it fails, powerup with empty
  RAM takes place.

  In case basic or kernel cannot be found you can still use the machine
  language monitor included.

  When you already have a good ram, a command like "x64 -l c64program fe66"
  might work too. Since it is the Basic warm start, x64 gets confused if a
  demo has messed up your ram.  If ram wasn't loaded, X64 creates it
  automatically to a file called "ram" for later use when exiting the
  emulator.

  You can store the ram for future use by entering the monitor (press left
  mouse button) and using command "dump ram".  Thus, it is possible to use also
  multi part programs.

  If too many keys are pressed very fast X-server may drop out some events and
  C64 keys may be left down. X64 tries release them when pointer is moved out
  of the window.
  It is also best to locate the pointer on the border area of the C64 screen,
  since that way autorepeat is turned off.

  After pondering deeply, thus spake the Oracle,
  saying:
	"Thy, who fulfill what thy are due,
	 and ably put to use tools,
	 which thy shalt have,
	 thy shall be answered."


 6. USING 1541 EMULATION

  The 1541 emulation of x64 uses disk image files as disks. These images can be
  created and maintained with the c1541 emulator program. To get started you
  can create an empty disk:

	c1541 -format x64image.dsk 'x64 diskimage,00'
	x64 -8 x64image.dsk
	(LOAD"$",8)

  Files can be copied between filesystem and disk image with c1541's -r and
  -w options, or using x64 (eg. load from device 11 (fs), save to 8 (image)).

  Data structure of disk image is currently header + 683 blocks. If you 
  have a way to dump your floppydisks block by block to your x64 host machine,
  you can create x64 disk image using c1541's -cr -option. There is no
  support for disk errors, extra tracks or special formats yet.

  NOTE: -cr option also imports the *.d64 disk images for C64S into x64 format.


 7. USING PRINTER EMULATION

  The X64 serial printer -- and just like the disk drive, also its standalone
  version PetLP -- provide options to store data in plaintext or binary format.

  Petlp also provides Postscript lavel 2.0 output, which works with HP LaserJet
  IV series, gs 2.4.1 and 3.33. However, HPLJ III series or earlier and
  gs 2.6.1 cannot be used.

  If you want the output in any non-supported format instead, there are
  Ghostview and Aladdin GostScript (gs) that display the image on screen.
  GhostScript can also send the rendered image onto printer, or GIF images can
  be then grabbed from the screen.

  When using A4 papersize, make sure to set it for ``gs'' as well, i.e.

	gs -sPAPERSIZE=a4 image.ps

  or put in your .cshrc the following alias:

	alias gs 'gs -sPAPERSIZE=a4'



  Options:
	--		Terminate options list.

	-c
	-nc		Suppress control codes in printout.

	-upper		Select graphics character set.

	-lower		Select business character set.
	-business

	-ascii		Select ascii encoding instead of petscii. This option
	-latin		 also selects US-ASCII and overrules -lang option.

	-lang <lang>	Select national 7-bit character encoding.
		commodore		germany
		commodore-din		italy
		denmark-1		norway
		denmark-2		spain
		england			sweden-1
		finland			sweden-2
		france			usa


	-top <row>	Set margins
	-bot <row>
	-left <col>
	-right <col>


	-F <format>	Select output format
		binary
		log
		petcii
		ascii
		Latin/1
		PS


	-o <filename>	Specify output file

	-P <printer>

	-help		Show usage.

	-v		Show Version.

	-test		Perform Selftest.



  Examples:

	petlp -test
	petlp -test -F PS -o test.ps

	petlp -lower -lang finland -left 4

	petlp -ascii -lower

	c1541 -r diskimage filename - | petcat | petlp -f PS -o file.ps
	 Prints a BASIC program filename from disk imagename to postscript
	 file file.ps.



 8. THE ROM IMAGES

  8.1 The ROM images:  Where to get those - and how ?

  In your C64 machine, I think. The programs to copy the ROM code to disk can
  be found below. The way to transfer the files to your unix machine depends on
  the hardware available.

  The ROMs _MUST_ be for the same CBM machine as the program emulates. They
  cannot be interchanged because e.g the memory management and I/O are
  completely different on each machine. 'xpet' runs with kernels from PET 3032,
  4032 and 8032, though, because the hardware is - except for the screen width
  and keyboard mapping - nearly identical.

  ROMs from other emulators -- like romcode.c64 in C64S, A64 ROMs, ... -- are
  usually invalid. Anyway, it is possible to get the ROMs on some FTP sites
  though. For example, have a look at:

	   ftp://ftp.funet.fi/pub/cbm/firmware

  The default paths for the roms are:

	    vice-0.11.0/bin/C64		C64 roms
	    vice-0.11.0/bin/C128        C128 roms
	    vice-0.11.0/bin/PET		PET roms
	    vice-0.11.0/bin/VIC20	VIC20 roms

  The default names for the C64 and VIC20 ROMs are:

            kernel			Kernel (i.e. Kernal) ROM
	    basic			Basic ROM

  For the C128, you'll need:

	    kernel			Kernal (i.e. Kernal) ROM
	    basic			Basic ROM + Editor ROM

  For the PETs, you just need one file called `kernel' which should contain
  the editor, the BASIC and the Kernal ROMs. Refer to section 8.6 for more
  information.

  
  8.2 DIFFERENT ROM VERSIONS

  Part Nr's for the real ROMs on each CBM Computer

		VIC 20		C64		C64c		C128

Chargen		901460-03	901225-01	90122-01	325181-01 /1

Basic		901486-01	901226-01	 -		318018-02
								318019-02

Kernel		901486-07	901227-03	 -		325180-01 /7

64 Basic+Kernel	 -		 -		251913-01	325182-02 /2


The following table summarizes the 128 ROM revisions for the United States.

Version		BAS lo		BAS hi		Kernal
-------		-------		-------		--------
First		318018-02	318019-02	318020-03
Middle upgrade	318018-03	318019-03	318020-04
Final upgrade	318018-04	318019-04	318020-05
128DCR		318022-02 lo	318022-02 hi	318023-02 hi

C128 basic ROMs 318018-02 and 318019-02 contain the 1985 version of the 128
BASIC V7.0.  These ROMs together are identical to the 318022-01 ROM.

Part number 251913-01 is the 16K 64 OS ROM, which is present in both the 64C
and the low-profile 128.  I have confirmed that this ROM is identical to the
first half of 318023-02.  Also, I have confirmed that the final ROM upgrade
(the 1986 release) is the same as the 128DCR version.  The only difference is
that the OS for the low-profile 128 is stored in four 16K x 8 ROMs rather than
two 32K x 8 chips.

-David Gahris	 dgahris@eece.maine.edu




  Disk Drives
 
1541 Drive DOS ROM      901229-05.
1541-II DOS ROM         251968-03.
1541-C DOS ROM          251968-01.
 
1581			318045-01, which is the only 1581 drive ROM revision



 It does not matter which Basic/Kernel revision you have, as long as it's one
 of the originals released by Commodore, and has not beed modified in any way.

 There are currently 5 C64 Kernel versions supported on X64. The X128 in turn,
 accepts total of 3 different C128 Editor/Kernel versions, as well as both of
 the C128 Basic 7 revisions.

 Once loaded successfully, one can change between different revisions using the
 patcher routine built-in.

 XPET should be running any PET ROM version, although this is not tested.
 You might have to specify the correct screen width if the kernel is not
 or incorrectly recognized. Please report any problems.


  8.3 C128 ROMS

  The C128 memory configuration is far more complex than C64's . While the
  other machines have 2 or 3 system ROMs, the C128 has total of 5.
  First, there is again the Chargen, a 8K EPROM containing not only the
  standard but also a national character set. The next one is for C64 mode,
  with both the BASIC 2.0 and the Kernel (like in C64C).
  Two 16K PROMs located next to it implement, of course, the BASIC 7.0 and
  Machine Language Monitor, while the last EPROM, 16K in size as well, has
  the 4K Editor and finally, 8K for the 128 Kernal.
  There is, however, 4K block (BIOS) covered by both the I/O and Character ROM,
  which makes it totally unaccessible.

  That's why a peculiar setup for the x128 was selected.
  The "basic" file contains both 128 basic roms and also the Editor code,
  totaling 36K (36864 bytes) but "kernel" is just the upmost 8K.


	5  REM READ C128 ROMS
	10 BANK 15
	20 OPEN 2,8,2,"BASIC,P,W"
	30 FOR A= 16384 TO 53247: PRINT# 2,CHR$(PEEK(A)); :NEXT
	40 CLOSE 2
	50 OPEN 2,8,2,"KERNEL,P,W"
	60 FOR A= 57344 TO 65535: PRINT# 2,CHR$(PEEK(A)); :NEXT
	70 CLOSE 2


  And while we are at it, here is a program to read the Z80 BIOS.

	begin 640 z80.rommi-imuri
	M`1P+',H'GC<Q.#$```"I/HT`_ZG#C>[_J2N-[_^I'(WP_ZE@C=S_(-#_6&`^
	2/C(`_P$`$!$`0"$``.VPP^#_
	`
	end
 

  8.4 C64 BASIC and KERNEL

  X64 emulator program requires the C64 BASIC and KERNEL in order to run
  your C64 programs. You need the contents of these ROMs in the *original*
  (binary) form, without any extra bytes and load address.
  This version, however, skips the default load addresses automatically.

  They or links to them, named 'basic' and 'kernel' respectively, must be
  located in the project directory you specify on the command line.

  Since both files are copyrighted you need a real C64 or C128 (in 64 mode)
  of your own to get them.

  To get the ROMs to your machine you may, for example, run two basic loops
  which copy them byte by byte to disk and after that use your PC with the
  x1541.exe (e.g. from ftp.funet.fi in /pub/msdos/utilities/diskutil) to
  transfer them.
  When this method is not possible, a modem or RS232 connection to another
  machine can be used. The Comp.sys.cbm General FAQ version 3.0
  (cbm-main-faq.3.0) explains what programs are available for this.

	5  REM READ C64 ROMS
	10 OPEN 2,8,2,"BASIC,P,W"
	20 FOR A= 40960 TO 49151: PRINT# 2,CHR$(PEEK(A)); :NEXT
	30 CLOSE 2
	40 OPEN 2,8,2,"KERNEL,P,W"
	50 FOR A= 57344 TO 65535: PRINT# 2,CHR$(PEEK(A)); :NEXT
	60 CLOSE 2

  Note that both of these files should be exactly 8192 bytes long.


  8.5  VIC20 / VC20 ROMS

  All that was said above, applies to xvic too. However, since the memory is
  differently constructed, another program is required.

  The basic and kernel are named identically with the c64 ones, so don't
  mix them!

	5  REM READ VIC20 ROMS
	10 OPEN 2,8,2,"BASIC,P,W"
	20 FOR A= 49152 TO 57343: PRINT# 2,CHR$(PEEK(A)); :NEXT
	30 CLOSE 2
	40 OPEN 2,8,2,"KERNEL,P,W"
	50 FOR A= 57344 TO 65535: PRINT# 2,CHR$(PEEK(A)); :NEXT
	60 CLOSE 2
	70 OPEN 2,8,2,"CHARGEN,P,W"
	80 FOR A= 32768 TO 36863: PRINT# 2,CHR$(PEEK(A)); :NEXT
	90 CLOSE 2


  8.6  PET 30xx/40xx/80xx ROMS

  To follow the above convention, the PET ROMs must be concatenated for xpet.

	B000 - DFFF	basic  12288 bytes (Basic 4.0)
	E000 - FFFF	kernel  8192 bytes (Includes the Editor ROMs, and I/O)

  The resulting ROM image is 20480 bytes in size and is loaded as the 'kernel'.
  A Basic image is not loaded. The kernel image is always loaded to the
  end of a 32kByte ROM image buffer. So you can also load ROM extension
  images that map between the screen buffer and the start of the system ROM.

  Care must be taken as the same program emulates all of these three PET
  models. One has to select the correct display mode according to the number
  of columns supposed by the ROM used. Default value is 40 columns.

	5  REM READ PET ROMS
	10 OPEN 2,8,2,"KERNEL,P,W"
	20 FOR A= 32768 TO 65535: PRINT# 2,CHR$(PEEK(A)); :NEXT
	30 CLOSE 2


 9. COMMON TROUBLES

  9.0  SET-UP

  It quits saying:
	ld.so.1: x64: fatal: relocation error: symbol not found: xmalloc:
	referenced in x64

    readline/ library did not compile. Try:

	Disable EDIT in config.h and 
	touch mshell.c
	make

  It only has the same old control window. Where is the new Xaw one?

    First, check that you have Athena library installed on your machine.
    Then make sure "X022" is disabled in config.h and try starting all
    over again. That is, run 'xmkmf' and recompile it.
    If you got neither one, enable either X022 (old) or XDEBUGGER (new).


  9.1  ROM IMAGES

  The emulator programs require the appropriate BASIC and KERNEL images for
  each mode in order to run your CBM programs.  You need the contents of these
  ROMs in the original (binary) form, without any extra bytes nor
  modifications. See the section above for details.

  NOTE: The files must be transferred in BINARY mode, since in ASCII (text)
  mode the data will be converted, truncated, or stripped to 7-bit.

  If you try to use rom images from another machine than the program is
  emulating, it will hang or crash. It is best to keep them strictly
  separated in different subdirectories.

  The ROM images, or links to them, named 'basic' and 'kernel' respectively,
  must be located in the project dir you specify on the command line.
  The Character ROM preferred but not required for VIC is known as 'chargen'.

  All of these files should be exactly 8192 bytes long, excluding the
  C128 basic which is 36864 bytes (36K).


  If you get the following message:
        Starting Commodore 64 emulator with PC = FE43
        Illegal instruction.
        PC=FE43 AC= 0 XR= 0 YR= 0 PF=00100000 SP= 0   2   2 JAM

  you have a corrupted 64 kernel rom image. (If you have played with the c64
  you should know that FCE2 is the right boot vector.) Your kernel is probably
  of size 8194 bytes e.g. there are the two bytes address which c64 adds to
  start of a file. You can fix it with emacs or with disk dump

        dd if=kernel of=kernel.fixed bs=1 skip=2
        dd if=basic of=basic.fixed bs=1 skip=2

  Note: x64 does NOT run JiffyDOS, or other third-party products.


  9.2  X11

  VICE can currently support only 8 bit/PseudoColor visuals, so you might
  have problems with 16 or 24 bit X servers.

  Since DECstations don't have Escape key the x64 does not have STOP
  key on DEC. In such situation XK_Escape in x64.c may be replaced by XK_Help
  or one key can be defined as Escape:

        xmodmap -e "keysym F11 = Escape"

  9.3  Compiling Z80

  If you set the optimization to the maximum level, you might have probelms
  when compiling the z80 emulation, since the compiler might exhaust the
  memory on your system (for example, this has been reported to happen on
  Linux 1.2.13 with gcc 2.7.0 and 36 MBytes of total virtual memory -- maybe a
  bug related to the compiler optiomizations?). If you encounter such a
  problem, just turn the optimization option off and retry.


  9.4  Imake and make

  There shouldn't be any problems to create the Makefile with 'xmkmf' or
  'imake' on most systems. If you encounter problems with the Makefile
  generated by imake, it is possible that the configuration of the imake
  program is not set properly for your machine. Check it out, or ask your
  sysadms to do so.
  
  [For Openwindows you may need to patch one of the imake template files
  first. Imake doesn't work properly on vanilla OW installations. This is
  all explained in the "Open Windows FAQ 03/04 - the XView toolkit" in
  alt.sys.sun or in an archive that backups this FAQ.]

  For readline/ you might #define NO_FORW in the readline/Imakefile if
  forward references cause trouble.

  In Makefile, remove any lines between
	# dependencies generated by makedepend
  and
	# DO NOT DELETE


	"make depend", gave this error:
	Makefile:229: *** missing separator.  Stop.

  If you're gettign XCOMM lines in the Makefile, you're probably using an
  R5 version of imake with the R6 configuration files.  Or else you're still
  using the R4 imake/configuration files.  In the former case, replace imake
  with the current one.  In the latter case, your system is quite out of
  date.  Try putting

	#define XCOMM #

  at the top of your Imakefile.
					-- Paul DuBois  dubois@primate.wisc.edu


  9.5  SysV

   dirp->namlen doesn't exist
  
  Either add -DSYSV -DSVR4 to CCOPTIONS in Imakefile, or remove the CCOPTIONS
  line.


  9.6  GETTING MORE HELP


  For further information refer to the VICE homepage:
	    http://stekt.oulu.fi:/~jopi/vice.html

  In case of problems mail the authors:
  
	Ettore Perazzoli (ettore@comm2000.it)

        Jouko Valta      (jopi@stekt.oulu.fi)
	   	         (vice@x2ftp.oulu.fi)

        Andre Fachat     (a.fachat@physik.tu-chemnitz.de)


  If you think you don't really understand the documents, then mail. You have a
  chance to affect in the documentation! Show what things you want clarified
  and what should be explained too.

  If you ask the net for help, *PLEASE* do supply some information about the
  system you're working on (that is which OS, which compiler, which X11 etc.).
  That way someone using similar system can tell what they've done themselves.
  Otherwise they won't be able to help you.

  Here is something to start with:

				E.g. this system:

	VICE VERSION		0.11.0
	    PATCHLEVEL		Generic July1996

	OS name and version
	e.g. 'uname -a'		SunOS stekt13 5.3 Generic_Patch sun4m sparc

	C-compiler		cc or gcc
	X version		X11 R5, Openwindows 3.2
	X11 include path	/usr/local/include

	X terminal              [ ] DEC VT 1300 SPX or similar (bad luck)
				[ ] DECstation (console)
				[x] Sparcstation (console)
				[ ] Linux machine (console)
				[ ] any other (specify)


  It is also fundamental to include the config.h file used for compilation.

  
  9.7  Manuals, anyone?

  Memory maps for most CBM machines and peripherals and some other documents
  are available via ftp.

	x2ftp.oulu.fi  /pub/cbm/maps
	ftp.funet.fi   /pub/cbm/maps (mirror)
	ftp.funet.fi   /pub/cbm/documents
			   /pub/cbm/documents/oc-118.manual
	x2ftp.oulu.fi  /pub/cbm/docs

  Do upload yours if you have better ones.

  There are also several Commodore related WWW sites around, with a wide
  variety of information. Just take a look.


 10. COPYRIGHT

  10.1  The Emulator

    Copyright (c) 1993-1996  Jarkko Sonninen, Teemu Rantanen,
    Jouko Valta, Ettore Perazzoli, and Andre Fachat.

    Video Chip Emulations
    Copyright (C) 1995,1996  Ettore Perazzoli.

    
    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.


  10.2  The Zilog Z80 CPU Emulator

  The Z80 emulator module is independent of the rest of the Emulator, and it
  can be replaced easily with another module according to preference. There
  are currently 2 options available.
  Check the sources to see which one is used.

  Alternate 1:
	Copyright (C) Marat Fayzullin 1994,1995,1996

    This file contains implementation for Z80 CPU. It can be used separately
    to emulate a Z80-based machine which is not MSX.

    You are not allowed to distribute this software commercially.


  Alternate 2:
	Copyright (c) Des Herriott 1993, 1994

   Permission to use, copy, modify, distribute, and sell this software and its
   documentation for any purpose is hereby granted without fee, provided that
   the above copyright notice appear in all copies and that both that
   copyright notice and this permission notice appear in supporting
   documentation, and that the name of the copyright holder not be used in
   advertising or publicity pertaining to distribution of the software without
   specific, written prior permission.  The copyright holder makes no
   representations about the suitability of this software for any purpose.  It
   is provided "as is" without express or implied warranty.

   THE COPYRIGHT HOLDER DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
   INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
   EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR
   CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
   DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
   TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
   PERFORMANCE OF THIS SOFTWARE.



  10.3  Matrix Printer Emulator

  Matrix Printer Emulator,
    Both C and PostScript(R) programs
    Copyright (C) 1995  Jouko Valta and Hannu Helminen.
    All rights reserved.

  Bitmap Font Building from the Blue Book Program program_21.ps
    Copyright (C) 1985  Adobe Systems Incorporated.
    All rights reserved.



 11. NOTES

  The following documents come with VICE:
	x64.{man,cat}		X64 manpage
	petcat.{man,cat}	petcat manpage
	recomment.man		recomment manpage
	README			VICE installation guide (this file)
	README.RUN		x64run front-end information
	Emulation		Details on VICE and different file formats
	DIN_charset		DIN and ASCII charsets for sREerial printers
	Star.codes		Printer control code list
	serial.doc		CBM Serial Bus Protocol
	drive_info		CBM Disk Drives
	cbm_basic_tokens	BASIC token code list
	pal.timing		VIC-II timing revealed
	64doc			Extensive CPU documentation
	PETdoc			Some notes on the PET series
	FAQ  			The Official VICE FAQ


  The program names for x64, xvic, x128 and xpet are built along the Unix/X11
  convention and any resemblance with other products, e.g. "A64" or "x1541", is
  unintended and purely coincidental.

  Names reserved for use in this project are the following:

  	c1541, xc1541, x64, x128, xvic, xpet, petcat and
	VICE, Versatile Commodore Emulator, and Virtual Commodore Environment.


	Trademark Acknowledgements

  Commodore C64, C128:	ESCOM
			(originally Commodore Business Machines, Inc.)

  OC-118:		Oceanic Electronic, Ltd.

  Star LC-10C:		Star Micronics Co., Ltd.


 12. AUTHORS

  The original VICE code:

    Jarkko Sonninen  (sonninen@lut.fi)		http://www.lut.fi:/~sonninen/

    Jouko Valta      (jopi@stekt.oulu.fi)	http://stekt.oulu.fi:/~jopi/

    Teemu Rantanen   (tvr@cs.hut.fi)
			The original 1541 emulator, alarms, and the Serial Bus

    Ettore Perazzoli (ettore@comm2000.it)

    Andre Fachat     (a.fachat@physik.tu-chemnitz.de)
						http://www.tu-chemnitz.de/~fachat


  Development and bug fixes by (in order of appearance):

    Vesa-Matti Puro  (vmp@lut.fi)
			The original 6502 emulator

    Hannu Helminen   (dm@stekt.oulu.fi)
			X11 help and VIC emulation
			PostScript programming

    Richard Hable    (Richard.Hable@jk.uni-linz.ac.at)
			REU information, and debugging & patches
			Serial and disk drive debugging.

    Frank Prindle    (Frank.Prindle@lambada.oit.unc.edu)
			patches

    Peter Weighill   (stuce@csv.warwick.ac.uk)
			Many ideas and ROM patcher

    Marko Makela     (msmakela@nic.funet.fi)
			CPU documentation and patches

    Dan Miner	     (dminer@nyx.cs.du.edu)
			Enhancements in 1541

    Germano Caronni  (caronni@tik.ethz.ch)
			patches, ideas and debugging

    Dominique STRIGL (strigl@sxb.bsf.alcatel.fr)
			patches

    Craig Jackson    (Craig.Jackson@lambada.oit.unc.edu)
			patches

    Ulmer Lionel     (ulmer@poly.polytechnique.fr)
			Linux joystick

    Lasse Jyrkinen   (ljj@stekt.oulu.fi, Lasse.Jyrkinen@uz.kuleuven.ac.be)
			patches

    Daniel Fandrich  (dan@fch.wimsey.bc.ca)
			patches

    Olaf Seibert     (rhialto@mbfys.kun.nl)
			Patches for disk drive

    Heiko Selber     (selber@fhi-berlin.mpg.de)
			VIC-20 I/O patches


    Thanks also to everyone else who has helped via sending suggestions,
    ideas, bug reports, questions and requests.

    In particular, we would like to thank the following people:

	Lutz Sammer       (johns@av.rwth-aachen.de)
	Ralph Mason       (RALPHM@msmail02.liffe.com)
	George Caswell    (timbuktu@the-eye.res.wpi.edu)
	Per Olofsson      (MagerValp@Goth.Org)
	Jasper Phillips   (philljas@newt.CS.ORST.EDU)

     for their invaluable bug reports and suggestions. 
