Emulator Universe CD

home *** CD-ROM | disk | FTP | other *** search

/ Emulator Universe CD / emulatoruniversecd1998.iso / Atari_ST / Emus / PCST048 / DOCS / PACIFIST.DOC < prev next >

Wrap

Text File | 1998-01-24 | 57.4 KB | 1,432 lines

▄■▀▀▀▀■▄ █▌ ▒ ▐█ █ ▓ █ ▄■▀▀▀▀■▄ ▄■▀▀▀▀■▄ ▄■▀▀▀▀■▄ ▄■▀■▄█ █ █▄■▀■▄ ▄■▀▀▀▀■▄█▀▀▀▀█ █▌ ▒ ▐▓▌ ▒ ▐▓▌ ▒ ▐▓▌ ▐█ █ █▌ ▐▓▌ ▓ ▐█ █▄▄ █ ▓ █ ▓ █ ▓ █ █ █ █ █ ▀▀▀▀█ █ █ █ █▀▀▀▀▀ █ █▀▀▀█▀▀▀▀▀█ █▀▀▀█▀▀▀▀▀█▀▀▀▀█ █ █▀▀▀█ █ █ █ █ █ █ █ █ █▀▀ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ █ ▐▓▌ █ ▐▓▌ █ ▐▓ █ █ █ ▓▌ █ ▐▓ █ █ █ ▄▄■▀ ▀■▄▄▄▄■▀ ▀■▄▄▄▄■▀█▄▄▄▄▄▓▄▄▄▄▓ █▄▄▄▄▄█▀■▄▄▄▄■▀█ █ █ ------█ █ -------------------------------------------- sns -█▌ █ ▐▓----- ▒ ▒▒▒ █▄▄▄▄▓ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▀■▄▄▄▄■▀ ▒▒▒ PaCifiST v0.48 ~~~~~~~~~~~~~~ written by Frederic Gidouin (frederic.gidouin@hol.fr) YM-emulation & SB driver by Arnaud Carre (leonard@mygale.org) (c) 1996-1998 Last Update: January 24th, 1998 ------------------------------------------------------------------------------- TABLE OF CONTENTS 0. Changes in this Document 1. Introduction 1.1 What is PaCifiST? 1.2 Why should you use it? 1.3 Features 1.4 Future Plans 1.5 How much does it cost? 2. Installation 2.1 Hardware Requirements 2.2 PaCifiST Concepts 2.2.1 A word about the Monitor 2.2.2 Video Emulation 2.2.3 Speed Modes 2.2.4 Drives Emulation 2.2.5 Sound 2.3 Before running it... 3. Configuration 3.1 INI directives reference 3.1.1 System Section 3.1.2 Screen Section 3.1.3 Debug Section 3.1.4 PACIFIST.INI example 3.2 Command line parameters 3.3 Configuration under Monitor 3.4 The Disk Selection Screen 3.5 Joyports Screen 4. Miscellaneous 4.1 Hints 4.2 VBE 2.0 4.3 Disk images 4.4 Keyboard mapping 4.5 Screen Snaphots 4.6 Game saving 4.7 YM soundchip recording 4.7.1 Usage 4.7.2 Technical information 4.8 Detecting & Using PaCifiST 4.9 Freezing/Unfreezing [*NEW*] 5. The Monitor 5.1 Monitor Screen 5.2 Monitor Commands 5.3 Evaluator [*NEW*] 6. Resources & Acknowledgments 6.1 Related programs 6.1.1 Other Emulators 6.1.2 Utilities 6.2 Resources 6.3 Greetings 6.4 Contacting me ------------------------------------------------------------------------------- 0. Changes in this document (since version 0.47) ================================================ New INI directives: vbemode, midi Changes in monitor: commands e,fz,uz,bar,baw expression evaluator mono/color hotkey Freezing/Unfreezing New capabilities: MIDI OUT, STE shifter Important changes in this doc will be marked with [*NEW*]. 1. Introduction =============== 1.1 What is PaCifiST? --------------------- PaCifiST is an Atari ST emulator for PC. This is a SOFTWARE emulator, meaning you don't need a specific extension card with ST components, just your PC. This allows you to run many Atari programs on your PC. 1.2 Why should you use it? -------------------------- If you were an Atari ST owner, the answer is: Nostalgia! It is really cool to be able to run your old programs. Nowadays, there are tons of multi-megabytes games for PC, with incredible graphics & unbelievable sounds, but except for a very few, they are boring, and have no "spirit"... The Atari is not the only machine with great games (I also enjoy C64 & Amiga), but if you have ever played with Super Sprint, Stunt Car Racer, Dungeon Master, Colonial Conquest... I think you get the picture of what GOOD games are. Of course, there are not only games on Atari ST! It was widely used by professional musicians for instance, and about all kind of programs exist. 1.3 Features ------------ PaCifiST emulates the following components of the original Atari ST: Motorola 68000 The 68000 emulation is written in 100% assembly language. All aspects of the processor are respected except for BCD instructions (not correct). Prefetch can now be emulated, using "pref" command in monitor. Because it slows down the whole emulation, you should only use this to bypass tricky routines. 68030 emulation will come in the future Shifter (Video) The 3 standard ST graphics mode are supported. You can choose between a monochrome (hires mode) or a color (lores & medres) emulation. All video emulation is also performed in 100% assembly language. Some special tricks (palette switching, rasters) are handled, provided you use a VBE2.0 driver and toggle the "LINE" video-building mode. Another mode (as of v0.44) is the MIXED mode. It's the same as the LINE mode, but allow also med/hi res mode switching. Since v0.45, PaCifiST is also able to set the ST in extended resolution. This only works with system applications. At this time, only low-border overscans are emulated, you must be in line mode with at least 240 lines. PaCifiST 0.48 emulates an STE shifter (cf ste INI directive). [*NEW*] 6301 (Keyboard) A genuine Atari uses this processor for keyboard, mouse, joystick & clock control. The exact behavior of this chip is not emulated (It is much too time- consuming) but the simulation is better and more accurate with each new version of the emulator. A mouse is needed. If there is no joystick connected to the PC (or you have disabled it in the INI file), a keyboard emulation is proposed. YM-2149 (Sound) This soundchip is emulated if a supported soundcard is detected (SB & GUS as v0.45). The YM emulation is done by Arnaud Carre, author of STSound. Since v0.41, I've started STF samples emulation. MFP (Interrupts) VBL, FDC, ACIA, TIMER C are correct, as well as TIMERs A, B & D in events count mode. HBL is not very accurate, but on a mere ST it's almost the same. FDC / HDC PaCifiST uses 3 levels of disk emulation: Gemdos, BIOS and hardware level. The Gemdos level allows you to use all your harddisks space under emulation. For BIOS & hardware level, disk images are used to reflect real Atari ST floppy disks contents. Since v0.42, you can also use the PC floppy drive (A:) BUT USE IT AT YOUR OWN RISK! With v0.45, formating is possible, but it is FAKED and require that the image have the same geometry as the format. I/O Output to Parallel are sent to the file PARALLEL.OUT The serial is not functional at this time. MIDI [*NEW*] In v0.48, PaCifiST features primitive MIDI OUTPUT emulation via an SB port. You must have "midi" enabled in the INI file, but then sound emulation is disabled. Tested with the game "ECO". Blitter STE blitter is now emulated 1.4 Future Plans ---------------- There are many things left to do, as well as many things to fix. The "to do" list is as follows, in no particular order. - better STF samples - fix the buckets of remaining bugs - STE DMA sound [in progress] - boost the 68000 a little more (I've one idea or two...) B-) - overscans & syncscrolls - working serial communication - Atari<->PC transfer program - a freeze/reload memory option - 68030 emulation Write me if you want another feature... Other neat features would be: - native 6301 emulation - Full MIDI support - FDC-level emulation in PC drives A: & B: (no chances!) But I haven't got enough docs (nor courage!) at this time. 1.5 How much does it cost? -------------------------- Well, before this program was FREEWARE. It is now GIFTWARE. ======== You are free and encouraged to spread it around you, provided you don't charge for this. ...BUT you are highly encouraged ^_^; to contribute. I spend almost all daytime on this project and I'd be really glad to receive any kind of reward for it. Sending me a few amount of money would be very kind, and will allow me to cover the phone bills. If not, you can send me a postcard, an old sci-fi movie, an home-made CD or...a local beer! I HATE crippled shareware programs, I don't want to do this: In return I hope those who can afford it will send some money. Thank you to all contributors! 2. Installation =============== 2.1 Requirements ---------------- PaCifiST is designed to be run in a DOS environment. It works best under plain DOS, but will be happy in a box under Windows 3.11, 95 or NT. I've been reported it was also working under OS/2 (be sure MOUSE_EXCLUSIVE_ACCESS is OFF), but not under DosEmu. The MINIMAL configuration you should run this program under is a 486DX-100. It will work with less, but don't expect it to be pleasant. I develop PaCifiST on an AMD 586-133 (about a P75 power), and the speed is almost always >= 8Mhz Atari ST at FULL FRAME RATE with sound enabled, under most games. Of course if you run a plasma routine with lots of color change, it will be slowed down... PaCifiST takes about 1.5Mb of memory itself, add to this the amount of ST RAM you want to have under emulation. With 8Mb of memory for instance, you can emulate a 6Mb Atari. A mouse is NEEDED. You can choose between the built-in mouse interrupt (SERIAL mouse in COM1 or COM2 only) or a mouse driver you have loaded before. The built-in driver doesn't work under windows 95. It is just a try to fix MANY mice-crashes encountered by several persons. If PaCifiST doesn't detect a joystick, it will use the arrow keys (when NumLock is off) to simulate one. You Can bring the joystick emulation screen with F4 under monitor. A Soundblaster compatible card or GUS is needed if you want to hear something. Apart from these requirements, you need a dump of an Atari ST TOS (The ROM). If you can have at least 2 different TOS versions, you all likely to run more programq, because PaCifiST has different problems with each TOS version. Run the ST program DUMP_TOS.PRG (in STFILES directory) to extract a TOS to disk. PaCifiST must be executed from its directory, which MUST contain PACIFIST.INI (the configuration ASCII file) and PATCH.H68 (some 68000 code needed to use mounted directories). 2.2 PaCifiST Concepts --------------------- This section explains some concepts you must understand to figure out how to configure the emulator options. 2.2.1 A word about the Monitor ------------------------------ By default, when you run PaCifiST, you start in the MONITOR screen. In order to run the emulation, you must type "g" (go) and press enter. You can go back to this screen at any time by typing in the key under ESC and above TAB. You may want to do this to quit, reset the Atari, Choose a video Mode or a Speed mode... Command "x" quits. IMPORTANT: Sometimes, when you come to the Monitor Screen, nothing you type on the keyboard will appear. Just press CTRL, SHIFT and ALT to clear the problem. Read the Monitor Commands Summary section for more information. 2.2.2 Video Emulation --------------------- There are 4 different video emulation methods available. This only concerns the standard low resolution Atari video mode. The first mode (and default) is called the "Screen-Oriented" mode, because all the Atari screen is generated in a single pass. It means you can only have one palette (16 colors) for the whole screen, and no special effects. This is the mode you must use to run Gem applications, because it is faster. The second mode is called "Line-Oriented" mode, and this time, each line of the ST screen is processed separately. This is the mode you should select to run some games and most demos. The third mode is called the "Mixed" mode and requires a 640x400x256 linear VBE mode. It is the same as Line-Oriented, but is also able to render ST screen with resolution switching (in such games as Magnetic Scroll & Level 9 adventure game and in the Calimero demo for instance). The last mode (new in v0.45) is the "custom" mode, and it also requires 640x480x256 linear VBE mode. THIS IS EXPERIMENTAL, use it only under the desktop. It may crash badly with TOS lower than 1.62. 2.06 is the best choice. You cannot switch to this rendering method, you must start the emulator in this mode (RENDER switch or INI directive) Screen-Oriented mode: - don't allow any video tricks + works well under Windows (even windowed) + fast + work on all PC Line-Oriented mode: - slower - VBE2.0 driver recommanded - works ONLY in full screen under Windows + several video modes (320x200, 640x480...) available + able to emulate palette switching, rasters, low-border overscans (with >200 lines)... Mixed-Mode: - *much* slower - requires a VBE2.0 driver with 640x400x256 or else 640x400x256 mode - work only in full screen under Windows + able to emulate (limited) palette tricks & resolution change in the middle of an image. You can switch from one mode to another easily whenever you want. IMPORTANT: Line-Oriented mode is not used when in hires/medres, Mixed one is not used when in hires mode. Custom-Mode: - *very slow* (set refreshrate to 3 or 4) - requires a VBE2.0 driver with 640x480x256 - work only in full screen under Windows - if you start PaCifiST in this mode, you won't be able to switch to another rendering mode. + extend the ST resolution to 640x480x16 under the desktop. Other resolutions will be added when it is more stable. 2.2.3 Speed Modes ----------------- Since v0.4, there are two different speed modes: ST and MAX mode. The default mode is ST-speed: Even with the fastest Pentium-class machine, you won't exceed the speed of a genuine 8Mhz Atari ST: This is necessary for some programs to run properly. The other mode, MAX-Speed will synchronize the emulation to the PC speed. This is fine for all system-compliant applications, but MANY programs won't work in this mode. It is NOT RECOMMENDED to change mode while running a program, it may crash. Change, BEFORE entering emulation. 2.2.4 Drives Emulation ---------------------- PaCifiST provides you three ways to emulate ST drives: - PC DRIVE A: I made this because of MANY requests. This is REALLY NOT RECOMMENDED!!! There are still many problems with disk changing and write-protection handling. If the <pcdrive> directive is enabled at startup and there are no images selected for disk A:, then PaCifiST will boot on disk. This should work with some games, but PLEASE DO USE IMAGES INSTEAD... ^_^; Please repeat: "I know that protected disks won't work. I shall *not* flame Frederic." - DISK IMAGES: This is a file that contains all the sectors of a given disks. For the emulated Atari, they are similar to physical disks inserted in drives A: & B:. Disk images work for all programs, even those that directly use the disk controller. Please use the .ST extension. You can choose two disk images at startup with the "IMAGE=" directive, or during the emulation under the DISK SELECTION screen. Since v0.41, PaCifiST is also able to directly use MSA files. A new Image format will eventually come, but PaCifiST will remain compatible with normal ".ST" files. - MOUNTED DIRECTORIES: This only works for programs that use Gemdos for file access, and there are still some compatibility problems with file-selectors and shell programs. This allows you to mount any directory as an Atari unit. For instance, if you mount "D:\ATARI" on the Atari C: at startup, the emulated machine will see this directory and its subdirectories as its C: drive. You CAN mount a whole partition, but it is NOT RECOMMENDED. You might put all your Atari stuffs in a directory or two, and mount them as units. This way, even if a big crash occurs, your PC system files won't be affected. You can't change the mounted directories on the fly, you must restart the emulator to do so. 2.2.5 Sound ----------- The STF samples are really bad at this time (it also depends on the replayer). You can disable this emulation in the INI file. You can switch this feature with F5 under monitor. Supported Soundcards are Soundblaster & Gravis Ultrasound. Driver for other cards are not planed. The emulator will first try to detect a GUS, then an SB... because if you own both, you'll probably prefer this. SOUNDBLASTER ============ PaCifiST won't try to autodetect the settings by itself, but rely on the BLASTER environment variable. Before running the emulator, be sure it is properly set. Read your soundcard documentation if you don't manage, but if you know for sure the settings, type under DOS: SET BLASTER= Axxx Ix Dx Where Axxx is the Port value. By example A220 Where Ix is the Irq number. By example I7 Where Dx is the DMA channel. By example D1 GRAVIS ULTRASOUND ================= You must have a proper ULTRASND environment string. SET ULTRASND= ppp,d,d',i,i' Where ppp is the Port value (220,240...) Where d is the DMA channel. Where i is the IRQ. 2.3 Before running it... ------------------------ PaCifiST is configured through a normal ASCII file: "PACIFIST.INI". You can edit it with any file editor to change the default behavior of the emulator. Some options can be overridden easily with commandline switches. This document contains a section which explains all the options. Please keep a copy of the original INI file, in case you made something wrong. You can choose an alternative configuration file with the /ini commandline parameter. The first time you will run PaCifiST, there are a few things that must be adjusted that depend of your system. The most important thing is to indicate PaCifiST where to find your TOS image. Load the INI file in a text editor (Edit under DOS or Windows's Notepad) and go to the [system] section (Sections are just intended to group directives by topics). You can comment lines with ";". All text after this will be ignored. Then, indicate the name of your TOS image: tos= tos162.img ;you must specify the path if the file is not in the ;PaCifiST directory. Put as many "TOS=" directives as you have TOS files, this way, once PaCifiST is loaded you'll be able to switch to any of these TOS. The last listed one will be the default. If you want to use this feature, you'd better add a comment to describe each file, for instance giving the version, language, country, whatever... like: tos= tos162.img, "TOS 1.62 (uk)" The default INI file that comes with PaCifiST contain some sample of TOS configuration. You must also be sure that the path specified for all MOUNT directives are valid. If you're unsure of understanding these MOUNT things, just comment the lines (put ";" before the directives) and read the INI directives reference. 3. Configuration ================ There are 3 levels of configuration. The INI files contains global options, while command line switches affect only the current session. Some options can also be changed on the fly. A file called JOY.CFG will also be created in the PACIFIST directory the first time you will run the joystick calibration, and loaded at started. 3.1 INI directives reference ---------------------------- all tabs, spaces and texts after ';' are ignored. 3.1.1 System Section -------------------- TOS = <file>,"comment" Name of a TOS dump file. If several ones are listed, you'll be able to switch from one to another under the monitor. Last listed one is default. AUTORUN = [yes|no] If YES, PaCifiST will jump into emulation when you run it, skipping the monitor screen. RAMSIZE = [n|512k] Specify the RAM amount to emulate in megabytes, (from 1 to 14) or 512k if you want a half meg ST. Since 0.47, you can also indicate half meg multiples, like 2.5. SOUND = [yes|no] Indicates whether or not you want sound. SAMPLES = [yes|no] Do you want *bad* STF samples? VOLUME = <n> Indicates the sound volume. Maximum is 255, and is the default value as you probably will prefer to adjust the sound level externally. MIDI = [yes|no] MIDI OUT Emulation??? You must have a Soundblaster card, and then chip music emulation is disabled. [*NEW*] INTERNALMOUSE=[yes|no] default is no, and tell PaCifiST to use the normal mouse driver given by DOS or Windows. If you have encounter problems with a serial mouse, try "YES" telling the emulator to use its built-in serial handler (not under Win95). SENSITIVITY=[1-10] Mouse sensitivity (only with external driver). Default is 5. MOUSECOM = [1|2] this works with the INTERNALMOUSE directive and indicates on which Com port is your mouse. SERIAL = [yes|no] Disable/enable the serial port emulation. Still buggy anyway. Try no if PaCifiST hangs. JOYSTICK = [yes|no] If disabled, no joystick will be used, but instead an emulation with the numeric pad. LEDS = [yes|no] Default is yes. If disabled, no LEDs blinking will be done. Try to set it to no if your PC hangs without reason. LAPTOP = [yes|no] If yes, the fire button for the joystick emulation will be the other CTRL key. KBDELAY = n Keyboard delay value (1-10) Default 3. You can also change this number under monitor. The 6301 processor send packets to the 68000 to indicate mouse & joystick moves. Some apps can be fooled if the emulator send too much bytes from the IKBD at the time. IMAGE = <file>[,d] This directive gives the name of a file (disk image) to be "inserted" in drive A: & B:. You can put two IMAGE directives in your INI file. You can also add the drive letter (A or B) after the image to force it in a special drive. MOUNT = <absolute path> Indicates to mount the given path (by example C:\PACIFIST\STFILES) to an Atari unit. The first one will be drive C:, you can specify 24 different locations. The specified PATH must be ABSOLUTE, with the letter indicated. PCDRIVE = [yes|no] Default is no - Should PaCifiST use the PC Drive A:? Enabling this feature adds an item in the diskselection screen. PARALLEL = [yes|no] Printer port emulation? STE = [yes|no] Emulate the STE shifter VBEMODE = [?|n] Give the default VBE mode in INI mode. [*NEW*] Please read 4.2 for more information. 3.1.2 Screen Section -------------------- MONOCHROME = [yes|no] Don't you guess? It has something to do with colors... FASTVIDEO = [yes|no] If you choose YES, PaCifiST will only convert modified portions of video memory. This is only used in the Screen-Oriented mode. If your graphics card is very fast, you don't need this option. REFRESHRATE = <n> The default value is 1, meaning that EVERY Atari screen is converted to the PC screen. Try a bigger value if the emulation is too slow on your PC. If you choose 3, only a screen out of 3 is displayed. RENDER = [screen|line|mixed|custom] Start PaCifiST in a specific videomode. 3.1.3 Debug Section ------------------- This is only useful for beta-testers and those who want to examine PaCifiST's behavior, watch interrupts, FDC emulation, mouse events... You need to have a "debug" distribution of PaCifiST for this. LOGFILE = <file> Name of the logfile, where all the information is written into. TRAPIRQ = [all|none|v] tell PaCifiST to stop execution when the given exception occurs. Default is none. If v is positive, it will be added in the list, if it is negative it will be removed from the TRAP list. You can specify several exceptions, separated with comas. LOGIRQ = [all|none|v] same as above, but this won't stop the 68000 but write information about the exception in the logfile. 3.1.4 PACIFIST.INI example -------------------------- [system] tos = c:\pacifist\tos.rom, "a tos" image=c:\pacifist\disks\boot.st ;name of disk image for Atari A: mount=c:\pacifist\stfiles ;C:\PACIFIST\STFILES will be Atari C: mount=c:\pacifist\games ;C:\PACIFIST\GAMES will be Atari D: autorun = yes ; jump directly to emulation mode pcdrive=no ; :) [video] refreshrate = 2 ;only render one screen out of 2. monochrome = no ;emulate an Atari with color monitor render=screen ;use SCREEN rendering mode (default) [debug] ; only with DEBUG compiled PACIFIST logfile = f:\debug.out ; the logfile for debug logirq = none ; erase the LOG irq lists logirq = 0x21 ; log GEMDOS calls logirq = 0x1c,69 ; log VBL & timer C too trapirq = 5 ; Monitor zero divide exceptions 3.2 Command line parameters --------------------------- Some INI directives can be overridden on the command line. Valid options are: /[h(elp)|?] list of options /ini <filename> use this file instead of PACIFIST.INI /refreshrate n same of REFRESHRATE directive /mono [yes|no] same as MONOCHROME directive /autorun [yes|no] same as AUTORUN directive /ramsize [n|512k] same as RAMSIZE directive /sound [yes|no] same as SOUND directive /image <filename> mount an Image BEFORE those in INI file /mount <path> mount a Path BEFORE those in INI file /maxspeed start in maxspeed mode (not recommended) /pcdrive [yes|no] same as PCDRIVE directive /render [screen|line|mixed|custom] same as RENDER directive /ymrecord allocate memory for YM recording. /vbemode [?|n] same as VBEMODE directive 3.3 Configuration under Monitor ------------------------------- Read the Monitor reference section for a complete description of all the commands. If you don't know 68000, the only commands you need are: g go into emulation mode x quit to DOS vol <n> set the volume (0-255) help some help. Yes. Useful keys: [F1] shift between SCREEN, LINE & MIXED mode. You need a VBE2.0 driver in order to be able to have the LINE and MIXED method. [F2] Choose a video mode in the list. 256 colors mode don't work always, but are faster than 32K & 64K colors mode. This affect LINE mode only. You can choose the default resolution & color depth used using the vbemode INI directive & parameter. [*NEW*] (cf 4.2) [F3] Change from ST speed mode to the MAXimum speed mode. Do this BEFORE going into emulation. [F4] Bring the joystick emulation screen. [F5] Enable/Disable the samples emulation. [F10] Change between MONO/COLOR emulation. As with a genuine ST, the emulated machine will reset [*NEW*] [F12] Display the DISK SELECTION screen. Can also be called during emulation. 3.4 The Disk Selection Screen ----------------------------- Use F12 at any time for this disk-selection screen. It can be useful to switch between 2 disks (in a multi-disks game...). I wrote the same kind of interface that Ulrich Doewich does for the Amstrad emulator CPE. It is pretty self-explaining. The file selector doesn't display all files, only .ST, .MSA .ZIP .RAR and directories, as well as all valid units. Use <ESC> to exit the screen. <UP>, <DOWN>, <PAGEUP>, <PAGEDOWN>, <END>, <HOME> to navigate in the file selector. <TAB> <LEFT> <RIGHT> choose disk A or disk B. <ENTER> will insert the selected image disk for the current drive. There is an item in the list to remove the disk. The <*> key allow you to skip bootsectors. When 'KEEP BOOT' is active, every executable will be runned. In 'SKIP BOOT' mode, PaCifiST will force the bootsector checksum wrong. Of course, if the changed disk need to be booted (for a game to start...), you must also perform a reset (Ctrl-Break). Since v0.4, the fileselector will consider .ZIP as normal directories, you can then group disk images in such archives. This is still *experimental*. In order to extract files from archives, PKUNZIP.EXE must be in the PATH. files will be extracted in the TEMP directory if this environment variable exists, or in the PACIFIST directory. The temporary files are called PCSTIMG*.TMP. They are not erased when you quit the emulator (in case you want to keep the changes in it). RAR archives are supported too, as of v0.46. PaCifiST will call RAR.EXE when needed, this program must be in your path of course. Since v0.42, if the PCDRIVE directive is enabled, you can also choose the PC drive A: to emulate a real ST drive. IMPORTANT: Changes in the extracted disk image WON'T BE reflected in the original archive file! It is the same with .MSA files, because they are converted to .ST file. 3.5 Joyports Screen ------------------- This screen allow you to choose between different emulations for both ST joyports. At this time, there are only three choice available: <none>, <PC Joystick #1> and <Numeric Pad>. - PC Joystick #1 is available only when an analog joystick have been detected at startup, of course. You must also calibrate it once, just type "C" under this screen, or "calib" from the monitor - The Numeric Pad can also be used to emulate an ST joystick, NumLock must be disabled for this emulation to be active. The right CTRL key (or the left one if laptop=yes in the INI file) is used as the fire button. 4. Miscellaneous ================ 4.1 Hints --------- - DO NOT USE ANY WRITE-DELAYED DISK CACHING ("smartdrv c+"...) - some GEMDOS function are not well-emulated. for instance, with mounted drives, GFABASIC file selector is trashy (OK with images). - If you're having problems with PaCifiST configuration, you can try a front-end utility: If you run PaCifiST from DOS, there is AssiST, coded by Aengus Jankowsky. For Win95 users, there is PaCiLOAD done by Andrew Knipe. - If you have enough memory, when debugging, put the logfile in a ramdisk. - avoid using PCDRIVE. It is slow, unstable and less powerfull than images. 4.2 VBE2.0 ---------- In order to enable the LINE-building mode and emulate raster effects, you need to install a VBE2.0 driver in memory before running PaCifiST. Perhaps there is such a driver provided in you graphics card package? A very good choice is to have Scitech's Display Doctor. You can download this shareware version on their web page http://www.scitechsoft.com. Alternatively, if you graphics card is based upon a S3 chipset, you should use S3VBE by D.Meschede, as it's freeware. [*NEW*] : You can change the default VBE2.0 mode used in LINE mode on startup, using the "vbemode" INI directive (or commandline parameter). First, create a list of supported mode by having the line "vbemode=?" in the configuration file (or by starting the emulator with /vbemode ?). A file called VBEMODES.LST is then generated, something like: --- PaCifiST authorized VBE Modes --- 0x0163 320 200 8 0x0164 320 240 8 0x014f 400 300 8 0x010d 320 200 15 0x012e 320 240 15 0x0137 320 400 16 0x0138 320 480 16 Of course, this will vary from a system to another. The first colums is the mode number, then the X and Y resolution, and finaly the number of bits per color (8 for 256 colors, 15 for 32000 colors, 16 for 65000) If you want 320x240 with 256 colors to be the default in LINE MODE, just have "vbemode=0x0164" at startup. 4.3 Disk Images --------------- These images just contain all the sectors put together in logical order: for all TRACKS x all SIDES x all SECTORS, there is a 512 bytes block. PaCifiST don't need any special information, because disk parameters can be read on the boot sector. If values seem wrong, PaCifiST tries to deduce it from the image file size. You can create your own images from your ST disks with the little utility IMGBUILD. It permits also to make blank images of standard or non-standard sizes. Read the RESOURCES section to see where to find it. Alternatively, PaCifiST is also able to use MSA file, but in read only. 4.4 Keyboard Mapping -------------------- Since v0.41, the keyboard mapping is similar to the Atari's, except that: - HELP is mapped on PageUp - UNDO is mapped on PageDown - CTRL+Break performs a reset (add SHIFT if the reset vector is trapped by the current program) - If NumLock is on, the arrow keys is the same as on Atari, else it is used for the joystick emulation (CTRL is fire). Also, F12 brings up the disk selection screen, and the key under ESC aborts the emulation and skips to the monitor. 4.5 Screen Snapshots -------------------- This feature appears in v0.44, and allow you to save the screen as a PCX file in the PACIFIST directory. All the files will be called "PCST_xxx.PCX". Just press the ScrollLock key to do so (The PrtScr key being used under Windows), please note that isn't not working in all video modes. The video modes supported so far are: - ST hires - ST lowres in SCREEN MODE - ST lowres in standard LINE MODE (256 & hicolor modes) - MIXED MODE (PaCifiST v0.45) Not supported yet: - ST medium resolution 4.6 Game saving --------------- With v0.45, formating is faked. You can format save disks in some games, BUT you must use a disk image of a similar geometry (same number of sides, same number of sectors per track, enough tracks) Some tips: CARRIER COMMAND - Use a double sided 10 sectors disk [imgbuild /blank /name SAVE.ST /sector 10] DEUTEROS - Use a standard disk (double sided 9 sectors) In my version of the game, the save disk my be inserted in B:...) [imgbuild /blank /name SAVE.ST) 4.7 YM soundchip recording -------------------------- If you know PaCifiST, then you're likely to know STSound as well. STSound (DOS & Win95 version exist) is a software YM2149 emulator. Virtually all ST soundchips (as well as Spectrum & Amstrad CPC ones) can be replayed. This program is written by Arnaud Carre, and you can download the latest version at: http://www.mygale.org/09/leonard/. PaCifiST can now record such soundfiles. You must start the emulator with the /ymrecord switch to allocate the needed extra memory (20 minutes of sound). Use the "record" option under the monitor to start/stop the recording. Files starting from YM_001.BIN will be created. BEWARE: Existing files are overwritten without any warning. Those files are "raw recorded" and huge. You should then use the LHA archiver with a commandline like: lha a -h0 -m <ym file.ym> <raw file.bin> to generate the final YM files - PaCifiST can only record plain soundchips. Not Sampled ones. The YM5! format is now used. - Record only in ST speed. Don't worry if PaCifiST is under the 8Mhz, it doesn't affect the replaying speed of the tune later on. - Don't spread widely unperfect/uncomplete .YM files. Starting the recording exactly when the music starts is not always easy and some knowledge in music ripping may help. With v0.46, you can use the <play> monitor command in order to locate the exact start/end point in the music. A loop point can also be specified. - Read the DOC that comes with STSOUND. 4.7.1 Usage ----------- You start/stop the recording under the monitor: record : display status record on : start/resume recording record off : stop/pause record. You then choose between: (F)ree - free the recording memory, abort current record. (P)ause - pause the recording. (S)ave - save to a file called YM_xxxx.BIN. 4.7.2 Technical information --------------------------- Use a DEBUG build of PaCifiST, to have the ability to set breakpoints,... The best method is to locate the installation & replay routines. Look the VBL & the MFP Timer vectors (command "status"), set a breakaccess at "ff8802", etc... The YM registers are recorded during the first rasterline. You must start the recording just after the replay routines is called for the first time. This will work most of the time: 1) find the installation routine 2) set a breakpoint at its end 3) go till then, remove the breakpoint. 4) use the command "trap 1c" (stop emulation on VBL) 5) "g" - go till the first VBL IRQ since music is installed (repeat this twice in some cases) 6) "trap 1c", remove VBL trapping "record on", start recording 7) if the music ends itself, stop recording, it's done. The end. If it loops, you'd better wait the second complete rolling before stopping. Then use YMTOOL in order to create an *exact* looped YM, but it's not always possible. 4.8 Detecting & Using PaCifiST ------------------------------ Due to some requests, it is now possible for an ST program to detect if he is running under PaCifiST. In the future some extra "hardware" registers might be added... ;-) Just call the Vsync() Xbios function with D6 & D7 registers being "Emu?". If your program is running under PaCifiST, then D6 will be changed to "PaCi" and D7 to "fiST". A0 will also point out the start of the extra-registers memory (probably $FFFF8100). You should be in supervisor mode to access those locations, even if it's not required under this emulator. Other emulator writters may use the same method, by altering D6 & D7 to whatever they want. The TOSBOX emulator by Mark Slagell use the same scheme to show his presence. Check the EMUDTECT.TXT file for more information. 4.9 Freezing/Unfreezing [*NEW*] ----------------------- Since PaCifiST 0.48, two monitor commands ("fz" to FreeZe & "uz" to UnfreeZe) allow to save the emulated computer and its context, and later restore it. Limitations: ============ WARNING!!! BOTH COMMANDS CAN SERIOUSLY HANG PACIFIST AND YOUR SYSTEM IF YOU'RE NOT CAREFULL. In particular, NEVER employ them if PaCifiST is using "mounted" directories. Also, the whole context isn't saved, then used disk images (.ST and .MSA) will not be inserted back in emulated drives when unfreezing, it's YOUR RESPONSABILITY. You must never Freeze while loading/saving from disk. Freezed files won't be compatible from one version of PaCifiST to anothern before the option is more complete. You MUST use the same TOS (version & language) between a freeze and an unfreeze, there is no automatic switching. In 0.48, saved FRZ files are real big. The memory is not compressed, so avoid freezing when you have more than 1 Mb of ST RAM. Usage: ====== Under monitor, the "fz" command use two parameters, only one being absolutely needed: the name of the generated file (8 characters, without extension). You also have the opportunity to enter a comment. For instance: fz sent197 The Sentinel, level 197 Will create a file SENT197.FRZ. To restore it later, type: uz sent197 To display the list of FRZ files (with their comments): uz 5. The Monitor ============== 5.1 Monitor Screen ------------------ The blue bar at the topmost contains a reminder of useful function keys as well as current video-building mode & speed-mode. Right under, a display of the 68000 registers as well as an estimated relative speed and a (not accurate) rasterline counter. On the right: Current Stack (USP or SSP) dump, a list of the breakpoints, breakaccesses & the breakopcode values. The upper windows always show the 68000 instructions around the current PC location. a "*" right before an instruction indicates a breakpoint. You can use CTRL-Z to step into or CTRL-T to trace over, like in the good old MONST2! CTRL-U can be used to trace in trace-mode, without entering the TRACE exception (but of course executing it!) CTRL-G is an alternative for the <g> command. 5.2 Monitor Commands -------------------- Many commands need a "DEBUG" compilation of PaCifiST. Because this slows down the emulation, it is not included in normal distribution of the emulator, but you can find such a version easily: just read the RESOURCES section to see where are the PaCifiST support sites. Arguments between parenthesis are optional. [*NEW*] With v0.48, you can use any mathematical expression instead of plain number in commands. Refer to the proper explanations in this document. h,help,? Quick summary t Trace over. This traces all instructions except for BSR, JSR & TRAP, which are executed till they return. Hit any key to abort if the execution seems in a long loop. z (n) single step. If an IRQ or an exception (Bus Error,...) occurs just after, it will be triggered. This can be annoying with Timers in some programs. TRACE MODE can be traced d (adr) dump a disassembling on a few lines. g (n) go. You can specify a number of rasterlines. m (adr) dump memory (hexa & ascii). bp (adr) Add or remove a breakpoint. A breakpoint doesn't consist in a special opcode, the memory isn't changed but the PC is checked all the time. You can then put breakpoint BEFORE a program is loaded. Breakpoints don't always work when they are on the first instruction of an Exception routine (use TRAP in this case) ba (adr) Add or remove a breakaccess. Any read or write (hopefully) to the given location will break execution. Be careful: A word access at $10000 will do nothing with a breakaccess at $10001. bar/baw (adr) [*NEW*] Allow to make a breakaccess only active on reading or writting memory. bo <msk> <cmp> set the "break opcode". There can be only one! All opcodes are ANDed with the mask and compared to the second parameter. For instance "bo ffff 4e75" will make the execution stop after all RTS. To remove the breakopcode, enter something like "bo 0 1". s reg=<value> Set any 68000 register to a given value. s [adr]=<bytes> change memory (even ROM). Use "s [1230] = 4e 71 4e 71" to nop a longword instruction. Each bytes must be separated by spaces. e <expression> evaluate a mathematical/logical expression nop <adr> <n> fill memory at <adr> with <n> NOPs... :) lb <file> <adr> (size) load a file (or part of it) in memory. sb <file> <adr> <size> save a part of memory to disk. reset (hard) Perform a reset. trap (vector) This command enables you to break execution each time a given exception occurs. Type TRAP alone for a list of the main vectors. animate <n> This will single step n instructions, with a dump of all the registers in the logfile after each of them. status Show some information about MFP & ST drives. disa <start> <end> Disassemble a part of memory in the logfile. FAST! kbd (bytes) Display/Put values in the internal 6301 keyboard buffer. kbdelay [n] Examine or set the KBDVALUE variable. vol (volume) Set the volume from 0 to 255 (dec), or display current value. x eXit. pref [on|off] If on, the 68000 prefetch queue will be emulated. Use this only when necessary because the emulation is slower in this mode. You can single step over prefetch queue, even if an opcode is changed. patch [off|...] Change the behaviour of PaCifiST in order to run more programs. The only patch at this time "joy": Use it when the joystick button seems not to work. calib bring the joystick calibration screen tos change the current TOS. This will reset the ST of course. record [on|off] YM recording. PaCifiST must be started with /ymrecord for this, because extra memory must be allocated. (cf 4.7) If no argument is specified, a status is displayed. If play was used before, the specified parameters are used, you can then save a given range. play <start> <end> <loop> play the current YM buffer. fz <name> [comments] freeze the emulated ST environment [*NEW*] Please take the time to read the paragraph about it (4.9)!!! uz [name] list freezed files/unfreeze the emulated ST [*NEW*] The following commands NEED a debug build of the emulator: bp, ba, bar, baw, bo, trap 5.3 Evaluator [*NEW*] ------------- Instead of typing "d 4000" to unassemble at $4000, you can now use mathematical expressions as parameters, for instance (a0+d0)*2 Supported operators: + * - / == > < && || & | ^ ~ >> << ( ) Default for numbers is hexadecimal, but 68000 registers being evaluated, that is a7 is not the decimal number +167 but the stack pointer. To override this, just use $A7. Decimal values can be passed if numbers are preceded by # or \. Memory references are possible, using [] for a longword. For instance "d [70]" will unassemble the VBL handler. Using [].b or [].w will only return the byte or word. 6. Resources & Acknowledgments =============================== 6.1 Related programs -------------------- 6.1.1 Other Emulators --------------------- - STonX Written by Marinos Yannikos and Martin Griffiths (nino@complang.tuwien.ac.at) & (mgriffiths@ea.com). It's a free emulator for Unix which comes with full sources. A DOS version now also exists, ported by Dirk Jansen. The official website is: http://www.complang.tuwien.ac.at/nino/home.html Nino & Martin are working hard on a new version. The DOS version homepage is on EmuCamp (the great emu website maintained by Zoop!) - Gemulator 96 It' a COMMERCIAL emulator. It is faster than STonX & PaCifisT but can only run 100% system compliant apps. Gemulator Classic is an older (but free) DOS version. official site: http://www.emulators.com - NoSTalgia Written by Philippe Gerin (philippe.gerin@advalvas.be). It runs now on PPC and 68000 MAC and from what I heard, is really great. Homepage: http://users.skynet.be/sky39147/ - TOSBOX A very new ST emulator, running under DOS. Its author, Mark Slagell (bald_soprano@usa.net) makes a brilliant job. This emulator is designed with system emulation in mind, so TOSBOX and PaCifiST are very complementary. - WINSTON The most recent emulator, and as the name implied it runs under Windows. This emulator shows a lot of promises, as the first release was already good. The homepage is hosted by Fatal Design: http://www.winston.fatal-design.com 6.1.2 Utilities --------------- AssiST - who: Aengus Jankowsky (ajankows@iol.ie) where: http://homepages.iol.ie/~ajankows/st/assist/assist.html A DOS front-end configuration program for PaCifiST. This program is very convenient to set up your .INI file. It's not only recommended for beginners, but for all users! Now a Windows95 version replaces it: AssiST97! Aengus done it together with Gerard Butterly. PaCiLOAD - who: Andrew Knipe (alk@bluesky.net.au) where : http://www.labyrinth.net.au/~contact/paciload.zip A Windows front-end interface for PaCifiST. Easy to use, can also convert MSA to ST file before running the emulator. MSAtoST - who: Damien Burke (st@jetman.demon.co.uk) STtoMSA where: http://www.jetman.demon.co.uk/st/index.html two converters to translate MSA files to ST files (the disk image format used in PaCifiST) and backward. Many programs you may find on the Internet (Umich archive...) are in MSA format. PaCifiST can also deal internaly with MSA file, but in read only. IMGBUILD - who Frederic Gidouin (frederic.gidouin@hol.fr) where: http://www.geocities.com/SiliconValley/Lakes/6878/download.html http://wwwperso.hol.fr/~gidouin/download.html A little utility to produce .ST files from floppies. It doesn't handle 11 sectors disks or protected/abnormal format. Can also be used to create blank new images. Sorry, for lack of courage, time & space this list is very incomplete. Other utilities include: Fuji Bar, PaCifiGUI, PaCigo 97 (and now 98!), MSA2ST, MakeDisk, ParaLink, PaCifiST Dragon. Check the PaCifiST homepage for more infos. 6.2 Resources -------------- PaCifiST-Support Sites: ======================= - http://www.pacifist.fatal-design.com/ The PaCifiST official homepage. Latest news, downloads & links. HTML coding & site designing by Rich!! - [Demonburps Emporium] http://ireland.iol.ie/~ajankows/st/pacifist.html Contains many versions of PaCifiST, latest version of AssiST, some disk images (games), TOS and links. Aengus was a pioneer in the ST emulation scene with his website. - The Little Green Desktop [http://www.fatal-design.com/desktop/] Incredible support site, with a bunch of cool ideas. The site is done by Rich(ard) Davey who did a brilliant job for the ST emulation community with site site, FujiBBS and the PaCifiST mailing list. - http://www.geocities.com/SiliconValley/Park/9967/ - http://www.jetman.demon.co.uk/st/index.html - http://www.geocities.com/SiliconValley/Park/5000/index.html - http://www.geocities.com/SiliconValley/Lakes/8711/ - http://users.iol.it/mamo7 - http://home.pages.de/~stefansworld/pacifist/st_page.htm - http://www.geocities.com/area51/corridor/8458/ - http://www.geocities.com/SiliconValley/Way/8264/index.html - http://users.powernet.co.uk/sterling/pacifist/ - http://dspace.dial.pipex.com/chriscox/home.htm - http://hem.passagen.se/win95/index.htm - http://www.ohz.north.de/user/ruediger/home.htm Other Atari ST emulation-Related SITEs: ======================================= - http://www.mygale.org/09/leonard/ Arnaud Carre homepage, with all his great productions. Have a look at his incredible YM-player!!! - http://www.why.net/home/adam/cem/toc.html comp.emulators.misc FAQ, maintained by Adam Roach. - http://www.complang.tuwien.ac.at/nino/stemu.html The STonX project homepage. - http://users.skynet.be/sky39147/ The NoSTalgia Emulator homepage. - http://www.geocities.com/SiliconValley/Vista/4448/ The TOSBOX emulator homepage 6.3 GREETINGS ------------- I wish to thank the following persons for their support & feedback. Darren Birks Damien Burke Arnaud Carre Stuart Campbell Jan Alexander Corsini Chris Cox Richard Davey Ulrich Doewich Laurent Fargues Flix Ben Fozard Peter Fransson Philippe Gerin Carolyn Horn Aengus Jankowsky Johan Klockars Andrew Knipe Patrice Lindivat Bruno Mathieu Jonathan McHugh Mike Mee Stefan Meier Andreas Muegge Ludovic Olivencia Ed Olmos Jamison Pitcher Matthew Prest Alan Reeve Mauro Rossetti Mark Slagell Simone Voltolini Arsene Von Wyss Zoop And of course a BIG THANK to all persons who have send me contributions. The logo used in this doc was drawn by Senser of Nitrophusion. Thanks to Emmanuel Loyon for his expression evaluator, which I only completed with some new operators. 6.4 CONTACTING THE AUTHOR ------------------------- Feel free to send any suggestions, remarks...gifts! e-mail: frederic.gidouin@hol.fr snail mail: Frederic Gidouin 9, Allee du Chevrefeuille 29280 Plouzane FRANCE