

				 The VICE FAQ
			      for Version 0.11.0

		      (c) 1996 The VICE development team



Contents:

   Section A: Compiling and Configuring VICE
   Section B: Using the VICE emulators
   Section C: Using and converting different CBM formats
   Section D: You still haven't solved my problem: how do I contact you?

   
   
------------------------------------------------------------------------------
Section A: Compiling and Configuring VICE
------------------------------------------------------------------------------


$01. Q: On which machines is VICE known to compile properly?
 
     A: The following systems have been tried successfully:

	  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
	  HP-UX 9.00 (both 700 and 800 PA-RISC series)

        Most of the standard Unix systems should work, since no
        system-specific features are used; the problems reported are often
        caused by non-standard setups. If you happen to have problems, feel
        free to mail the authors, who might probably solve them.


$02. Q: Which is the correct command sequence for compiling VICE?

     A: First of all, you have to configure it. To do so, you just have to
        edit the config.h and follow the instructions you'll find in the
        comments. You basically have to comment out the #defines you don't
        need (by putting them between `/*' and '*/') and uncomment the ones
        you need. If you want further information about what each option
        means, you can use the README file.
	After you have done so, Imakefile file. In this file you will be
        allowed to set the compilation options and the compiler name, by
        simply editing the `CC', 'CCLINK' and `CDEBUGFLAGS' lines. You should
        disable all the debugging options and enable all the possible speed
        optimizations to make the resulting code faster (e.g. -O3 with
        gcc). After you have done such, simply create the Makefile from the
        Imakefile with the X11 `xmkmf' command and compile everything:

		xmkmf -a; make


$03. Q: How can I re-compile with different options?

     A: Edit the config.h file and then type

	        xmkmf -a; make

        Notice that you should use the `-a' option when calling xmkmf in order
	to have all of the required files re-compiled properly. If have not
	used the `-a' option, issue a ``make clean'' before doing ``make''.


$04. Q: How can I compile only the emulators and utilities I need?

     A: To do so, compile the readline library, edit the configuration and the
        Imakefile and build the Makefile (see Question $02). Then you can
        choose to compile one or more of the following targets:

		 x64	    (the C64 emulator)
		 x128	    (the C128 emulator)
		 xpet	    (the PET3032/4032/8032 emulator)
		 xvic	    (the VIC20 emulator)
		 c1541	    (the diskimage handling utility)
		 petcat	    (the PETSCII/CBM BASIC file reader)
		 petlp	    (the Postscript Matrix Printer emulator, still
			     under development)

        To compile each of them, just supply the target name to the `make'
        utility as a parameter. Eg:

	         make x64

        to compile the C64 emulator.
	We suggest you to always compile c1541 at least since it will allow
        you to handle all of the most popular emulator formats.

      
$05. Q: The compilation ends with the following error: undefined reference to
        `XShmCreateImage' (or another similiar XShmxxx error).

     A: Your system does not seem to have the MIT Shared Memory Extensions,
        but your badly configured imake program has told VICE that you have
        it. To fix the problem, edit the Makefile and delete every `-DMITSHM'
        you can find in it. You will usually have a line similiar to the
        following:

         	DEFINES = -DMULTIBUFFER -DMITMISC -DXTEST -DXSYNC \
	        	  -DXCMISC -DPEXEXT -DMITSHM -DXIE -DBIGREQS \
			  -DSCREENSAVER -DXF86VIDMODE

        Just delete the `-DMITSHM' option and it should compile correctly.  You
        will obviously have a worse (much slower) emulation this way, though.


$06. Q: Do I really need the MITSHM extensions, after all?

     A: Yes, you definitely do if you are going to run the program on the
        console with its own display. In this case, the MITSHM extensions
        allow _many_ times faster screen refreshes.  On the contrary, if you
        are using a remote X-terminal connected to the host which runs the
        program via a network, you will not be allowed to use such extension,
        so it will make no difference to compile VICE with that option enabled
        or not; anyway, if you compile with MITSHM enabled and your system
        can't support it (as happens in this case) you will have to disable it
        on the command line with the `+mitshm' option, though, or the program
        will stop with an error.


$07. Q: The compilation stops with the following error: undefined reference to
        `XCreatePixmapFromBitmapData'.

     A: You do not have the XPM library on your machine (many workstation
        vendors, eg. HP, do not supply this). You'll have to edit the config.h
        file and comment out the `#define XPM' line.  This will not affect the
        emulation, since the XPM library is only used to create the window
        icons.

      
$08: Q: The compilation ends with the following error: undefined reference to
        `memmove'.

     A: This has been reported on some SUNs. To fix this, just replace
        `memmove' with `memmov' in memory.c and printer.c. [this will be
        probably better fixed in the future]

      
$09. Q: The compilation ends with the following error: function prototypes are
        an ANSI feature.

     A: You have not told your compiler that VICE is written in ANSI C. Consult
        your system documentation and set the proper options in Imakefile. For
        example, the HP-UX C compiler needs `-Aa' to be added to the `CC' line.

      
$0A. Q: Where can I find the ROMs?

     A: From your Commie, of course. :-) The instructions and BASIC programs
        for transferring them can be found in the README file.
	If you don't want to spend time this way, you can look for the proper
        files in the same ftp sites you have fetched VICE from.
	Anyway, remember that those ROMs are still copyright-protected, so you
        are not supposed to download and use them unless you actually own the
        machines they belong to.


$0B. Q: Which ROMs are supposed to work?

     A: All of the original Commodore ROMs will surely work fine. Anyway, you
        should also be allowed to use customized versions, provided that they
        have the I/O access routines in the right places, since they have to
        be patched by VICE for the emulation to work properly. (just don't
        care about the `wrong checksum' messages: VICE does not know about all
        the ROMs in the world!). FIY, JiffyDOS will not work.
	Notice: as explained in the README file, not all of the ROMs from
        other emulators can be used, since they have often been modified for
        that specific use. For example, ROMCODE.C64 from C64S will not work.


$0C. Q: I have recompiled VICE with TRIPLE_X and TRIPLE_Y enabled. It looks
        cool, but it is as slow as death!

     A: Sorry, but this is due to the huge amount of work required to perform
        this. If you happen to run VICE over a network, it will become
        virtually unusable. (if you wonder why, just make a couple of
        multiplications: one single 1024x768 window refresh requires 786432
        pixels, i.e. 768Kbytes at 8 bits depth... too much for being sent over
        a serial line if you want 50Hz animations!)
	If you use XFree86, you are allowed to configure your system to use
        different resolutions and choose them at runtime by simply using some
        shortcuts (Ctrl-Alt-GrayPlus or Ctrl-Alt-GrayMinus), so it is a good
        idea to configure a lower resolution expressely for VICE instead of
        specifying the DOUBLE_* or TRIPLE_* options in the config.h. 


$0D. Q: I am using gcc 2.7.0 and Compiling x128 with Z80 support enabled gives
        `virtual memory exhausted'. What can I do?

     A: This is a well-known problem, and is known to happen even with 36
        Mbytes of total (virtual + real) memory. Sounds like a bug in this
        version of gcc, and we do not know whether using older or newer
        versions would fix the problem. Anyway, this does not happen if you
        compile the Z80 emulator (which is the part which causes trouble)
        without optimizations. To do so, simply compile x128 as you would
        normally do. When the compilation halts, enter the Z80 directory and
        do a simple:

		    gcc -o Z80.o -c z80.c

        Then go back to the src directory and do a `make x128'.		
       

       
------------------------------------------------------------------------------
Section B: Using the VICE emulators
------------------------------------------------------------------------------
      

$01. Q: I have compiled VICE and I have installed the ROMs, but when I run it
        it locks up and does not even show the BASIC startup message.

     A: Your ROMs are probably corrupt, or maybe you have swapped the BASIC
        with the KERNAL. VICE should be able to recognize bad ROMs by simply
        comparing its Checksums with the known ones, but it will not abort for
        this since it will suppose that you know what you are doing (eg. you
        might want to run a custom ROM)... Look at the VICE startup messages
        to understand what is going on.

      
$02. Q: How can I attach D64 and X64 diskimages?

     A: You can attach them on unit 8 or 9 with the command line options `-8'
        or `-9', e.g:

		x64 -8 mariobros.d64

        The `-floppy' option works exactly as `-8' and is kept for backward
        compatibility with older versions of VICE and x64.
        VICE 0.11.0 can read/write d64 images directly: if it does not find
        the correct x64 header, it assumes that it is a raw D64 image and uses
        it consequently. This applies to c1541 as well.  To attach diskimages
        from the monitor, use the `attach' command:

		attach 8 mariobros.d64

        If you don't specify the unit number, 8 will be the default.

      
$03. Q: How can I attach T64 tape images?

     A: You can use the command-line options `-tape' or `-1':

	        x64 -1 pitfall.t64

        From the monitor, use the `attach' command:

	        attach 1 pitfall.t64


$04. Q: I have attached the tapeimage and issued the LOAD command from x64...
        now it says `FOUND GAME' and then pauses for a really long time. What
        can I do to speed it up?

     A: On the C64, you can skip this by pressing the C= (Commodore) key. You
        can do exactly the same with the emulator: press the `Meta' key, which
        emulates the C= key on VICE (on certain keyboards, the `Meta' key is
        called `Alt' or `Compose Character', but it will work in the same
        way).

      
$05. Q: I am loading a program from a Tape image, but the BASIC says ?LOAD
        ERROR and VICE reports `unexpected end of file'... what is going on?

     A: A huge amount of the tapeimages you can find on the popular C64 sites
        and some utilities which produce T64 files do not follow the standard
        T64 specification closely, so they can give this sort of error. Most
        of the times, you can safely ignore this message and the program will
        work perfectly.

	
$06. Q: Help! This game ignores the numpad joystick!

     A: Try to change the Numpad Joystick port, which can be 1 or 2 as in the
        real 64. This can be done both from the Monitor (press the left mouse
        button and then type `set joy n'), or from the command line (`x64 -joy
        n').


$07. Q: The emulator does not seem to handle the function keys properly: when
        I press them, I can only execute Window Manager commands.

     A: Your Window Manager is stealing the key events from VICE. Reconfigure it
        to use different keys as shortcuts for its operations.
	An alternative is to edit the key definitions on the top of x64.c to
	make it use other keys for F1, F2, etc.

      
$08. Q: `Mario Bros' and `Ghost n' Goblins' do not work properly on x64:
        sprites disappear. Can this be fixed?

     A: These programs are correctly emulated by x64, but you have set a
        Refresh Rate value which is too high to display the sprites
        properly. If you tried the game on a real 64, you would see that the
        sprites `flicker' (ie. they are turned on and off quickly); if VICE
        only displays the frames when they are turned off, you won't see
        them. To fix this, use the `set' monitor command to set a proper
        (lower) Refresh Rate value, eg.:

		set refresh 1
		  
        From the command line, you can use the `-refresh' option:

	        x64 -refresh 1

	On x128, different `refresh' values are enabled for the 80 column
	(VDC) and 40 column (VIC-II) windows:

	        x128 -vdcrefresh 4 -vicrefresh 1

		
$09. Q: In `Super Cycle', `Pitstop II' and `Pole Position' the road goes
        backward. Why?

     A: Your `refresh' value is too high, ie. the screen updates are too slow
        for the animation to be displayed properly. Refer to Question $08 to
	set a proper value.


$0A. Q: `Castle Wolfenstein' does not work. Why?

     A: It uses REL (relative) files, which are not supported yet. Sorry.

     
$0B. Q: Are sprite-sprite and sprite-background collisions supported? I have
        infinite lives with most games... and sometimes I can't even shoot the
        enemies!

     A: Yes, they are. You have two ways of enabling them: from the command
        line

		x64 -checkss -checksb	      to enable them (if not default)
		x64 +checkss +checksb	      to disable them (if default)

        or from the monitor:

	        set checkss 1
		set checksb 1		      to enable

		set checkss 0
		set checksb 0		      to disable

		
$0C. Q: I have enabled the sprite-sprite collisions but it still does not detect
        them properly!

     A: Again, the problem might be related to the refresh rate. Since sprite
        collisions are checked each time the screen is recalculated, you have
        to keep that value low for correct operation. Refer to Question $08.
	

$0D. Q: The intro is loaded, but it does not load the main part from the
        diskimage. Why?

     A: This program probably uses a Turbo Loader. Unluckily, VICE does not
        support this yet.


$0E. Q: VICE reports: `UNIMPLEMENTED'. Why?

     A: The program you are running is trying to use features of the 1541 disk
        drive which are not supported by VICE yet. These might be implemented
        in the future versions of the emulator.


$0F. Q: This demo flickers like mad!

     A: Maybe this is a NTSC demo and you have compiled VICE for PAL, or it is
        a PAL demo and you have compiled for NTSC. Try to change this setting
        in config.h. If the problem cannot be fixed this way, you have
        probably found a bug in VICE. Refer to the last section of this
        document for contacting the authors.


$10. Q: I wanted exact speed emulation, so I tried `set speed 100' from the
        monitor, but this stills give me >100% speed. Why?

     A: The Hex Mode is enabled, ie. the numbers you enter are interpreted as
        hexadecimal. So you actually asked to limit performance to 256%, and
        not to 100%! To disable the Hex Mode, you can use the `+hex' option on
        the command line or set the `hex' monitor variable to 0:

	      set hex 0

        Alternatively, you can specify the base of the number using the `#'
        prefix:

	      set speed #100

        `#' stays for `decimal', `$' for `hexadecimal', `%' for `binary' and
        `&' for octal.


$11. Q: How can I make VICE run faster on my machine?

     A: Most of the times, when VICE is too slow for your machine, you'll have
        to raise the refresh rate value, using the `-refresh' option
        (`-vdcrefresh' and `-vicrefresh' on x128) or setting a different
        REFRESH_RATE in config.h and re-compiling the emulators. You can also
        obtain a more speed from the emulator by reducing the size of
        the window (this is particularly important when you have animated
        sprites in the borders).
	Moreover, Sprite-sprite and Sprite-background collision checking slow
        down the emulation too, so they should not be enabled (using the
        `-/+checkss' and `-/+checksb' options) unless strictly necessary (many
        games do not actually need them). Other optional features, such as the
        LED bar (BUS tester) and the `Trace' button on the XDebugger need some
        additional computing power too. 
	On a Pentium 100 machine with Pipeline Burst Cache, VICE will (should)
	run most of the times at 100% speed even with `-refresh 1' and
	collision checking enabled. Anyway, we are constantly working on VICE
	to make it faster and thus suitable for slower machines too. You will
	have already noticed that this 0.11 version is (much) faster than the
	0.10 one... ;-)

	
$12. Q: How do I emulate the different PET machines available
        (i.e. 3032/4032/8032)?

     A: Put the ROM images in the usual place; when you want to emulate one
        specific machine, simply specify the proper ROM name with the
        ``-kernel'' option and VICE will detect it. For example, if you want
        to emulate the CBM/PET 3032 and you have a 3032 ROM called
        ``pet3032'', use:

              xpet -kernel pet3032

	In case you use a 8032 ROM, the screen size will be automatically set
        to 80 columns.


$13. Q: I have crashed VICE and I my keys no longer autorepeat. Why?

     A: To handle the keyboard correctly, the VICE has to turn autorepeat
	off. During normal operation, autorepeat is always turned on when the
	focus goes out of the window, so there are no problems. If you make it
	crash (or kill it with a non-trappable signal), it will not restore
	the keyboard behavior properly, so you'll have to do this by hand. You
	can use the `xset' command which is part of the X11 distribution:

	      xset r
	      

------------------------------------------------------------------------------
Section C: Using and converting different CBM formats
------------------------------------------------------------------------------


$01. Q: How many formats are used for the C64 emulation? Which are their
        differences and pourposes?

     A: For exact information, see the CBM or the CBM Emulation FAQs, which
        provide all the information you might need about this (FIXME). Anyway,
        the most common emulator formats are the following:

	       .d64	      Raw CBM1541 disk image
	       .t64	      C64 tape image
	       .p00	      PC64 program file
	       .x64, .dsk     x64/VICE native format

        The d64 and t64 format were first used in the popular Shareware DOS
        emulator by Miha Peternel, which is called C64S. The first simply
        contains the contents of each block of data of a 1541 single-sided
        disk in sequence, without any other information added, and this is why
        it is exactly 170 Kbytes long. The t64 format can contain a sequence
        of files and is used to emulate the tape recorder (which is also known
        as the `Datassette' among Commodore users).
	The p00 is a very simple format which was first used with the C64NEU
        program (which is the ancestor of PC64) and simply contains the C64
        program code with not much added.
        The x64/dsk format was first introduced with the X64 emulator, which
        is the ancestor of VICE. There are many advantages towards the more
        popular d64 format, since it contains much more information about the
        disk format and is thus more reliable (VICE can immediately realize
        when a diskimage is corrupt) and more easily expandable (1571/1581
        support might be added in the future, for example). We suggest you to
        use this format for storing programs, since it is really not difficult
        to convert the other formats to this one.
        There are other file formats which were originally intended for use
        with the C64 (not just for emulators) and which are quite common on
        the Internet.

	       .lnx	      LYNX archive
	       .sfx           Self-Extracting program file
	       .sda           Self-Extracting program file

        The .lnx format can be depacked with the LYNX program, which runs on
        the 64.
	The .sfx and .sda files are just self-extracting programs: simply run
        them on VICE and they will build the files contained in the package
        automatically.

	
$03. Q: How do I create and use diskimages with VICE?

     A: To create a diskimage, use the `format' command in c1541, eg.:

	       $ c1541

	       C1541 V 2.00  Image 1.02

               c1541 #8> format diskimage.x64 'name,id'

        `id' is the disk ID, which is 2 characters long and should be
        different for each disk image (this is a feature of the Commodore
	DOS).
        To copy files from the filesystem you can use the `read' command; to
        copy files to the filesystem, use the `write' command.
        To use a diskimage with one of the VICE emulators, you have to
        `attach' them, i.e. make the emulated machine think they are in its
        disk drive(s). You can attach disk images at startup by using the
        `-8', `-9' and `-floppy' command-line options, eg.:

	       x64 -8 diskimage.x64

        `-8' and `-floppy' attach the image as drive #8, while `-9' attaches
        it as drive #9.

        You can also attach diskimages from the monitor using the `attach'
        command. For example,

	       attach 8 datadisk.x64

        will attach datadisk.x64 as a floppy in drive 9. This is also useful
        for multi-disk programs.


$04. Q: How can I use .d64 images with VICE?

     A: From version 0.11.0 you can use .d64 files directly, without converting
        them. Simply attach the images as you would do with a c1541-created
        one: since VICE will not find the VICE diskimage header, it will try to
        use it as a .d64. Notice that, since .d64 files have no added
        information in them, VICE cannot verify that the image is really ok, so
        take care...  A better idea is to convert the d64 files into VICE
        format. This can be done with the `create' command in the c1541
        program:

	       create disk.x64 disk.t64

        or, from your favourite shell:
      
	       c1541 -create disk.x64 disk.d64


$05. Q: How can I use .t64 images with VICE?

     A: From version 0.11.0 you can attach T64 images, so that the Tape
        Recorder (also known as the Datassette) can be emulated as well. To do
        so, you can use the `-tape' or `-1' options on the command line:

	       x64 -1 kewlgame.t64

        From the monitor, you can use the `attach' command specifying `1' as the
        device number:

	       attach 1 kewlgame.t64

        (Notice: this won't work with xpet and xvic in the present version of
        VICE)
	To transfer files from tape to disk images, use the tape command in
        c1541 (after attaching a proper disk image file), eg:

	       tape kewlgame.t64


$06. Q: How can I use .p00 files with VICE?

     A: The .p00 files can be simply read from the filesystem. For example
        (from the emulated machine):

	      LOAD"KEWLGAME.P00",11

	Notice that with VICE you have to use the actual name of the Unix FS
	file and not the CBM-DOS name of the program (which is provided in
	the P00 format).
	

$07. Q: I am trying to attach a diskimage and VICE reports `Couldn't open
        file', but the file is there!

     A: Check the file permissions: VICE needs to open the file in read/write
        mode. Future releases will probably allow you to attach diskimages
	read only, but this one will not.

     
------------------------------------------------------------------------------
Section D: You still haven't solved my problem. How do I contact you?
------------------------------------------------------------------------------


The current VICE developers are:

      ettore@comm2000.it		(Ettore Perazzoli, maintainer)
      jopi@stekt.oulu.fi		(Jouko Valta)
      a.fachat@physik.tu-chemnitz.de	(Andre' Fachat)

They will surely help you if possible. :-)
If you are going to report bugs, please remember to include the following
information:

- a detailed description of the bug and how to reproduce it;
	
- architecture of the machine you are using (eg. Intel 486);

- name of the operating system and version (eg. Linux 1.2.13);

- release of the X window system you have installed (eg. X11R6);

- for Linux, version of XFree86 which you have installed and name of the
  graphic card you are using (eg. 3.1.2 with an S3/864 card);

- for the GNU C compiler and libraries, the version of gcc (eg. 2.7.0), and of
  libc (eg. 5.0.9 if you have /lib/libc.so.5.0.9);

- a copy of what VICE reports before showing the bug (if not a compilation
  problem).

If you think you know what the bug might be related to, try to enable the
debugging options in config.h and send the resulting log. This will surely
increase our chances to solve the problem... You might even fix it yourself so
that your fix will be included in the next release. ;) We encourage you to
report all sorts of errors you might encounter, since this will allow us to
provide you (and all the emulator community) with better versions of VICE.
