**************************************************************************
 ****    X-Mame Frecuently asked questions and Installation guide    ****
**************************************************************************

NOTE: This is a short guide extracted from X-Mame Project Home Page
  see at http://drake.dit.upm.es/~mame

Wellcome to X-Mame, the X11/Unix port of the 
MultiArcade Machine Emulator project.

1- X-Mame FAQ
2- Patches and pending jobs
3- Mailing lists
4- Compiler notes


*****************************************************************************
1- Frecuently Asked Questions on X-Mame
*****************************************************************************

     What is X-Mame?

          X-Mame the UNIX/X11 port of Mame project.
          It makes Mame arcade emulator available on *ix machines using the
          X11R6 X-Window system ( and Linux ones using SVGAlib too )

          Mame is a virtual machine emulator: it includes a Z80, 6502 and
          lastly I86 uP emulators, joined to several arcade machine hardware
          emulators. Each arcade emulator contains a full description about
          hardware, mem maps, video, sounds and so, making possible that if
          you have original ROM images of a supported arcade game, you can
          play the game.

          You NEED the rom images to play a game: this is not a game
          emulator, just an arcade machine one.

          Mame is an Idea of Nicola Salmoria
          X-Mame Primary work thanks to Dick the Ridder and Allard Van Der
          Bas

     How to get started?
          
          For starters read readme.dos for some more generic info, afterwards
          read this doc (README.unix) for some unix specific comments.
          http://www.daveclassics.com has a nice mame-resources page.
          So have some other emu-sites out there.

     Differences between Mame and X-Mame

          Ideally none:
          X-Mame is always Mame based. I mean: last revision of Mame is last
          revision of X-Mame too.
          Development series of X-Mame are incorporated to Mame on each new
          release.
          There is no plan to independent development.
          NOTE: Due to several reasons, It may occurs that official Mame
          release does not compile in UNIX. Don't worry, XMame versions
          X.YY.1 are allways the same as official, but tested and patched
          -if needed- to run.

     Which Machines and *IX are supported ?

          At this moment are supported:

                  arch/OS          X11         sound            joystick

               Ix86/linuxSvgalib  console      yes              yes (1)
               Ix86/Linux         yes          yes              yes (1)
               Ix86/FreeBSD       yes          yes              yes (1)
               Ix86/NetBSD        yes           no              yes (1)
	       Alpha/Linux        yes          yes                (3)
               Sparc/SunOs        yes           no                 no
               Sparc/Solaris      yes          yes                (3)
               Ix86/Solaris       yes          yes                (3)
               SGI/Irix           yes          yes               (2)(3)
               IBM/AIX            yes          yes                (3)
               HP-9000/hpux       yes           no                (3)
               ISC/Ultrix         yes           no                 no

           (1) Need to be loaded joystick kernel module, or compiled support
	   into kernel
           (2) There are an analog input channel on some Indy that could be
           used to support a PC-Like joystick. Volunteers asked ...
	   (3) If your X-Server support XInputExtensions, you can use any
	   XPointer device as Joystick ( see joystick notes )

     Which ones are NOT supported ?

          Following machines are not (yet) supported , Mainly due to lack of
          information and/or time to port and test. help wanted ...

          I386/SCO Unix ( Not a specific port, but someone reported me that
	                  a "dummy" compile succed ) 

     My machine is supported, but Mame gives me some strange errors and fail

	  X-Mame (X11 version) should run in 8bpp PseudoColor Displays and
	  8,16,24,32Bpp TrueColor Displays. If your server does not support
	  any of these visuals X-Mame wont run. Use xdpyinfo program to veryfy
	  these item
		Of course, In linux you cannot run SVGALib version in X11 and 
	  viceversa...

     What about non-X11 **IX ports of Mame ?

       	  Starting with 0.27.1 Linux SuperVGA lib based X-Mame is supported
	  and integrated in X-Mame source tree. World thanks Hans de Goede
	  for doing the job. Other direct-console ports are too hardware 
	  dependent to implement it. See references at home page
	
	  Of course HP-UX's StarBase library based Mame is allways granted. :-)

     How to compile and run X-Mame ?

          Follow these steps:
	    0. See COMPILER NOTES in this file
            1. Get and uncompress X-Mame source files
            2. Edit "makefile.unix" and change settings according your
               system
	    3. If compiling X11 Joystick support, 
	       a) type
	       "make -f makefile.unix xlistdev"
	       "./xlistdev" 
		to see available Xdevice list.
	       b) choose desired device and re-edit makefile setting option
		JSNAME with the correct item
            4. Type "make -f makefile.unix" in top of your source tree
            5. It should compile without problems. If not, report to the
               author :-(
            6. Type "make -f makefile.unix install" to install executable 
	       Depending of your destination directory, you may need to
	       become root to do this ( this is mandatory for svgalib )
	    7. Create in your home a directory "xmame". configuration files
	       will be saved and restored there. Copy the file 
	       doc/xmamerc.dist to ${HOME}/xmame/xmamerc
	    8. If desired copy xmamerc.dist to MAMERC makefile's location
	       as "xmamerc"
            9. Edit your newly created ${HOME}/xmame/xmamerc with your
               preferences
            10. Be sure that MAMEDIR , DISPLAY and PATH environment variables
               are correctly set. if needed edit your .profile ( or .login )
            11. Fire up!!. and enjoy...

     If things go wrong...

          If you cannot complete installation steps check these items:
             + Be sure that MAMEDIR points correctly to base directory of
               rom images
             + Be sure that ROM image filenames has correct
               uppercase/lowercase names
             + Did you properly configured your .xmamerc file?
             + Is xmame in your PATH?
	     + remember that SVGALib XMame needs setuid root
	     + See KNOWN.BUGS file

          If things still fail, send email to the author

     Not sure about what is the role of xmamerc file...

	  Very simple. A normal xmame invocation looks like: 
	  "xmame pacman -sound -nojoy -frameskip2 -heightscale 3 \
	  -widthscale 2 -display host.domain.org:0" It's horrible to type 
	  in. Due to the fact that a normal user allways use the same 
	  ( or very similar ) command line, i saved all personal confs in
	  a file that resides in each user's home directory. In this way
	  the user has only to type specific options on specific game, 
	  leaving all other defaults as desired. This is a common way to
	  work in the UNIX World
		Other reason is keyboard remapping. Some unix keyboards
	  are not close to PC ones, and this is the only way to remap
	  extra keys. ( the F8 key available on most of games has no 
	  way to work here... )
    
	  Starting 0.29.1 release every user dependent configuraion, 
	  thas is, xmamerc and *.cfg have been moved to ${HOME}/xmame
          directory
 
     Don't know how to enable XInputExtensions X11 based joystick in my
     XFree86 server....

	Just edit XF86Config and enable XInput section with aproppiate
	parameters. In doubt "man XF86Config"

     My i386 joystick seems not to run correctly in diagonal moving...

	Joystick needs to be correctly calibrated to get this patch run. 
	The X and Y range and center values should be the same... 
	Some time ago I did some work in that, but think that is better to i
	use specific programs to calibrate it ( jscal that comes with joystick 
	module works fine.... )
	  There is also a config/commandline option "joyfilter" that gives you
	the chance of filter "joystick jittering"

     Cannot save/access to High score files and key definitions....

	NOTE: previous configs instructions  become obsolette: with 0.29.1 
        and up, now per-user configuration files resides in 
        ${HOME}/xmame/<game>.cfg and by default hi-scores are stored in 
	/var/games/mame. So only give a drwxrwsr-x root games /var/games/mame 
	permission and setgid xmame to "games" to get it work

     What about directories
     Where should I put the ROM's and config files

	  Since 0.29.2 release, X-Mame supports unzip-on-the fly for ROM's
	  and sample files . So the directory hierachy has slightly changed:

          ${MAMEDIR}/xmamerc    ( default config file )
          ${MAMEDIR}/my_uncompressed_game/uncompressed_game_roms_and_samples
          ${MAMEDIR}/roms/list_of_compressed_roms.zip
          ${MAMEDIR}/samples/compressed_sound_samples.zip

        - HI-Scores will be saved in a separate user "games" writable 
          directory ( supposed that xmame is setuid to "games" ) defined
          in makefile as SPOOLDIR

        - Per-user configuration is stored in ${HOME}/xmame/xmamerc
        - Per-user game configuration is saved in ${HOME}/xmame/game_name.cfg

     Game xxx doesn't have sound ?
      
          First of all make sure your sound is working in other apps.
          Does xmame dtect your sound & make sound with other games.
          Take a look at readme.dos, is the sound for the game emulated?
          Does the game require an opl according to readme.dos?
          Opl is not supported under unix.

     Game xxx doesn't work ?

          Do you have the right roms or did you get checksum failures?
          Take a look at the notes in readme.dos for some games the emulation
          isn't working yet.
          If you don't have a soundcard, or sound isn't supported on your
          unix try -fakesound, some games won't work without sound emulation.

     Xmame is slow ?

          Try -frameskip ar altering the framskip by pressing F8.
          Try disabling throttle with - nothrottle or by pressing F10.
          Hit F11 to see how fast it is running, if it doesn't get 100%,
          You'll just need a faster computer.

     What are the commandline-options for xmame ?

          Xmame supports most dos commandline-options (see readme.dos)
          as wel as a few of its own, type xmame -help for a complete list.

     What keys does xmame use ?

          Xmame uses the same key-bindings as the dos-version see readme.dos.

     Where can I get last release of X-Mame ?

	  The main site is the X-Mame Home Page:
	  http://www.dit.upm.es/~jantonio/mame

     Where can I send fixes, bug reports, suggestions, blames, money :-).. ?

	Mailling list:
          mailto:xmame@acm.csres.utexas.edu
	X-Mame coordinator
          mailto:j.w.r.degoede@et.tudelft.nl

     Legal questions and Copyrights

          The Main question is about ROM images: They are under copyrights
          of their authors, and CANNOT be distributed in the same package as
          Mame. Download them at your responsability

          Mame itself is Copyright of Nicola Salmoria. It should be distributed
	  under terms of following license:

 ===========================================================================
     Legal issues and Copyrights on Mame and X-Mame 

     Due to some restrictions to source code, Mame and X-Mame are no longer under
     GPL. So new conditions apply:

    
     The main purpose of MAME is to be a reference to the inner workings of
     the emulated Arcade Machines. This is done for educational purposes and
     to preserve many historical games from the oblivion they would sink
     into when the hardware they run on will stop working.
     Of course to preserve the games you must also be able to actually play
     them; you can see that as a nice side effect.
     It is not our intention to infringe any copyrights or patents pending on
     the original games. All of the source code is either our own or freely
     available. No portion of the code of the original ROMs is included in
     the executable.

     Some of the following rules might not apply to specific portions of MAME
     (e.g. CPU emulators) which bear different copyright notices.

     MAME is free. The source code is free. If you paid for it, you've been
     ripped off. If you sell it, you are a thief.

     The MAME executables must be distributed only in their original .zip
     archives. You are not allowed to package them together with the original
     ROMs. You are not allowed to distribute them on the same physical medium.
     You ARE allowed to make them available for download on the same site, but
     only if you warn users about the copyright status of the ROMs and the
     legal issues involved.
     You are NOT allowed to make MAME available for download together with one
     giant big file containing all of the supported ROMs, or any files
     containing more than one ROM set each. If you want to distribute such
     files, you are not allowed to distribute MAME.
     You are not allowed to distribute a modified version, nor to remove
     and/or add files to the .zip archive. Adding one text file to advertise
     your site is tolerated only if your site contributes original material
     to the emulation scene.
     If you distribute the executable, you should also distribute the source
     code. If you can't do that, you must provide a pointer to a place where
     the source can be obtained.

     The source code cannot be used in a commercial product without a written
     authorization of the authors. Use in non commercial products is allowed
     and indeed encouraged; however if you use portions of the MAME source
     code in your program, you must make the full source code freely available
     as well.
     Derivative works are allowed (provided source code is available), but
     discouraged: MAME is a project continuously evolving, and you should, in
     your best interest, submit your contributions to the development team, so
     that they are integrated in the main distribution.
     Usage of the _information_ contained in the source code is free for any
     use. However, given the amount of time and energy it took to collect this
     information, we would appreciate if you made the additional information
     you might have freely available as well.

     All trademarks cited in Mame and X-Mame  documents are property of their 
     respective owners.
 ============================================================================

     Some portions of X-Mame source code are copyright of Dept.
     Ingenierma Telematica at Universidad Politicnica of Madrid. This
     copyright should be present in all source distribution in order to
     use them

     XInputExtensions based Joystick support source code is enterely a
     pure hack work. No sample code, no info at all was found ( only
     library reference manual ) and is copyrighted by me. Use it under
     terms of GNU General Public License

     Who is Who in Mame Project ?

     Fathers of the creature:     Nicola Salmoria
                                  Allard van der Bas
                                  Mirko (Mix) Buffoni ( General Mantainer)
     Original UNIX/X11 port:      Dick the Ridder
                                  Juan Antonio Marmnez
     Unix maintainer:             Hans de Goede

     Lots of people helped us giving info, patches, rom images,
     improvements ( see acknowledgements )


*****************************************************************************
2- X-Mame Patches And Pending jobs
*****************************************************************************

     You can retrieve patches and updates from Juan Antonio's ftp site
     ftp://drake.dit.upm.es/xmame/ftpsite

     There Are several jobs pending:

        + Porting to other non-standard **ix is also pending. No machines to
          port and test availables. Help wanted
        + My golden dream: Network support for two players and several
          watch-points. Should not be too difficult: X is network based, and
          working sound jobs too. Little help is needed in order to know
          peeks & pokes for detecting which player is in turn

     If you think you can help in any areas, ( or any other you consider
     interesting ), please mail to X-Mame mail folder

*****************************************************************************
3- Mailing lists:
*****************************************************************************

     There is an "Official"l X-Mame Mail List

     - Every ops related to this list are performed via e-mail to 
       xmame-request@acm.csres.utexas.edu with a proper keyword in the body

       At this moment, recognized commands are:
       "$ubscribe"    To subscribe list
       "un$ubscribe"  To unsubscribe list

     - Of course, the mail list itself is xmame@acm.csres.utexas.edu

     - If you want to send a personal mail to the xmame-coordinator, send mail
       to j.w.r.degoede@et.tudelft.nl, but please, i think it's better that 
       everyone that contributes in X-Mame receives every xmame-related mail.

*****************************************************************************
4- COMPILER NOTES ON SPECIFIC OS'S
*****************************************************************************

GENERAL NOTES
============= 

     - You're encouraged to use GNU development environment gcc, gmake gnu-ar
       Lot's of problems found due to very permissive sintax in gcc so if
       you use strict ANSI C compiler, you'll get lots of warnnings, and
     - if version is not full debugged - compilation errors	

     - Default makefile is prefconfigured  to run under X11/Linux. be carefull i
       with some linux-specific options 

     - Despite first advise: GNU Make is MANDATORY in ALL Systems ( well, if
       you have a gmake compatible one.... )

Joystick and Mouse support
==========================
	
     - In Makefile.unix you should select if support desired for these
       3 devices.

     - If using X11 Joystick in XFree86, you should note that in
       Joystick subsection of XInput section of XF86Config you have a
       value "Delta" that tells you the maximun shift reported to the
       clients. Using Delta=100 works fine in my Linux box

     - Starting with 0.27.2 version if joystick support enabled you should
       select which joystick you want:

       a) In Intel based UNIX you can select native joystick support. To do
	  enable I386_JOYSTICK option
	
       b) There is also provided a patch for FM-TOWN PC's game pad. If desired
	  set apropiate line

       c) Finally, for any UNIX that supports XInputExtensions you can select
	  X11_JOYSTICK. if done, you should define the name of your input
          device name, location of Xi library and polling method (event-driven
	  or query-driven)
          A program "xlistdev" is provided to search all available
          devices. To compile type "make -f makefile.unix xlistdev" and run
          it
NOTES: 	
       X11 Pointing devices has been a pure hack work: no sample programs
       availables and only library reference to start working... Item more
       the only machine that has been tested is my Linux box (where some
       XInputExtensions calls and functions doesn't work...)

       So please, consider this a beta support. Need further works
       and development, and (most important) reports from other input devices
       and architectures. Every contributions will be wellcomed

       In fact, every XInputExtensions based programs are propietary
       and source code is not available, so X-Mame becomes a development
       reference material...

A Words on AUDIO
================
	
       - Some ARCH's has specific items for use/not use sound. see 
         and set FLAGS according instructions in makefile.unix

       - If you want linear interpolation on mixer, uncomment S_LIN item in
         makefile.unix This feature makes a terrible noise in AIX and Solaris
         so don't use it ( can someone owning one of these studie this ? )

       - In Linux and IRIX audio device are capable to send info about audio
         buffer free space. so you should disable timer. to do this keep
         S_TIM commented in makefile.unix

       - In other systems you'll have to:
         . comment out S_TIM in makefile.unix
         . Evaluate and set propperly AUDIO_TIMER_FREQ

         To get correct value use following formula:
	 
         minimum AUDIO_TIMER_FREQ = 1+(int)(audio_sample_freq/audio_buffer_size)

         For instance:
         In Solaris with chipsets SUNW,am79c30 or SUNW,dbri use AUDIO_TIMER_FREQ=4
         In Solaris with audio chipset SUNW,CS4231 choose AUDIO_TIMER_FREQ=9
         In AIX you should use: AUDIO_TIMER_FREQ=6

         THESE ARE MINIMUM ALLOWED VALUES.. to ensure that audio buffers 
         won't overflow Ideally AUDIO_TIMER_FREQ should be a multiple of 
         the base system timer frecuency ( e.g if CLOCK_TIC on a system is 
         10mseg , you can use 20 or 40 as AUDIO_TIMER_FREQ ). Note than a 
         timer-based sound is very cpu-expensive and slows performance
         so a soundquality vs speed compromise is shown, btw if you choose
         a very low value, sound will be very clicky and slow...  ( most 
         of mame samples are less than 256 bytes, so a value near 50 should
         be acceptable... )

       - In Linux there is an interesting feature: you can select sampling
         output frecuency by using commandline option -samplefreq <freq>
         ( 8000 < freq < 45454 )

BSDi
=====
       - Compile using ARCH=FREEBSD adding -DBSDi to CFLAGS.FREEBSD
	
Linux
=====
       - See Notes on Joystick

       - It has been reported than SoundBlaster AWE32 does not correctly
         manage get_audio_buffer_freespace(). If so, ( you'll get some
         audio_ioctl() calls failed messages in console and no sound )
         just use timer based audio instead ( Still studying the problem )

       - Also I've tested sound using the PC-Speaker driver module !it works!!
         but.... you must use -DUSE_TIMER :-(

       - Corolary: 
       	1) If using SoundBlaster AWE32 or PC-Speaker use -DUSE_TIMER
           else use -DDONT_USE_TIMER
           (Don't blame me: I dont wrote sound drivers)

       - Since version 0.27.1 you can compile to generate a SVGALIB executable
         xmame. Just do:
         set compiler to CC = gcc ( don't use -ansi -pedantic feature )
         disable XPM options.
         select ARCH=svgalib
         when compiling done don't forget to setuid root executable file
         ( remember that SVGALIBS programs need to run as root )
         BEWARE PERMISSIONS OF GAME ROM DIRECTORIES: must be readonly
         for everyone (except root :-) ). Else .... your security become
         broken ( I've advised you. don't blame authors )

       -  A SVGALib specific option is provided: -videomode (also in xmamerc 
          file) :
          . videomode 0   use standard 640x480 x256 mode, safe bet should work
            on all pc's
          . videomode 1   use tweaked vgamodes, with simulated scanlines, 
            might not work on all machines, use with caution
          . videomode 2   tweaked vgamodes without scanlines, might not work 
            on all machines, use with caution

IRIX
====
       - S_TIM option should be set to -DDONTUSE_TIMER

       - Two sets of flags are provided for those machines that has no sound
         sopport installed ( X-Mame uses the dmedia package on IRIX systems )

       - Sillicon Graphics provides several native compilers. X-Mame has been 
         compiled and tested with DCC and it's recommended due to better
         code quality
	
       - Some problems have been reported using GNU linker. it's recommended to
         use native one

HPUX
====
       - In HP-UX gcc and gnu-make is MANDATORY

ULTRIX
======
       ( Notes reeived from Danny <dboxhoor@iso.vilspa.esa.es> )

       - VERY IMPORTANT!!!
          The xmame cpu emulators access memory through pointers which are
          sometimes cast to illegal addresses - as far as the MIPS cpu is
          concerned. The ultrix operating system is aware of that and fixes
          this "unaligned data access".
          Depending on your system setup lots of warnings are generated
          for certain games. Fortunately these messages can be disabled by 
          executing the command "uac p 0" in the same shell where xmame will 
          be running.

       - Use gnu make.

       - Compile with the `c89' compiler. Though `gcc' has no problems with
         compiling and optimizing xmame. The resulting `c89' executable is
         faster on an empty machine (read: xmame can use all cpu & memory
         without competing with other high priority processes), so you can
         set `frameskip' to 1.

       - When compiling with `c89 -O2' don't forget to also use `-Olimit 1000'.
         If the 1000 is not enough the compiler will tell you to increase it.

SunOS & Solaris
===============

       - Solaris sounds horrible, and due to hardware and development
         tools not expected to be much better

       - To Compile under Solaris/ix86 select -DDONTUSE_TIMER in audio
         options 

       - Use "CC = gcc" instead of "CC = gcc -ansi -pedantic"  ( some
         ANSI-POSIX incompatibilities in Solaris include files )

       - In Sun Machines: if using Sun's OpenWindows and SunPRO compiler
         change makefile.unix options to:

LIBS.solaris	= -L/usr/openwin/lib -R/usr/openwin/lib -lX11 -lXext \
		  -lnsl -lsocket -lm

         and add -I/usr/openwin/include to CFLAGS.solaris entry

       - If using Sun's ar program, remove "-" sign in src/unix/Makefile
         from "ar -rcv" to "ar rcv", and add a "ranlib $(OBJDIR)/osdpend.a"
         bellow 

	
-----------------------------------------------------------------------
     Created by jantonio@dit.upm.es on 20 May,1997
     Last Update 21 May,1998
-----------------------------------------------------------------------
