GEMULATOR SHAREWARE RELEASE 1.00 ================================ Program by Darek Mihocka. Copyright (C) 1992. Branch Always Software. 14150 N.E. 20th Street Suite 302, Bellevue, WA 98007, U.S.A. September 1992. This release consists of 7 files: - GEMUL8R.EXE - the 68000 emulator and Atari ST hardware emulator - DOS4GW.EXE - 32-bit DOS extender - DOS4GW.VM - 32-bit DOS extender with virtual memory support - GEMULDOS.BAT - batch file to run from DOS - GEMULVM.BAT - batch file to run from DOS with virtual memory - GEMULWIN.BAT - batch file to run from Windows - GEMUL8R.DOC - documentation for Gemulator (this file!) Software License ================ Gemulator is a shareware program. It may be freely copied and placed on bulletin boards (BBSs) under the condition that the above listed files are not altered in any way. This documentation file must be distributed along with the executable files. If you use this software you are expected to become a registered user by paying the $59.95 shareware fee, as you would pay for any commercial software.To register, send $59.95 in U.S. funds to: Branch Always Software 14150 N.E. 20th Street Suite 302 Bellevue, WA 98007, U.S.A. VISA and MasterCard accepted. Call 206-885-5893 to register by phone. Once you become a registered user, you receive printed documentation and will receive our newsletters alerting you to newer versions of the Gemulator software. The first update is free. In addition to the Gemulator software, you will also need to purchase the Gemulator ROM Reader board. This board is used to read Atari ST ROM chips on the PC. The board is NOT required for generic 68000 emulation, but is required to run any Atari ST software. The Gemulator board is available from PC dealers for $299.95 or less, and includes a set of TOS 2.06 ROMs, the latest revision of the Atari ST operating system. The board and ROMs are available at an introductory price of $199.95 if ordered by September 14th, 1992 from Purple Mountain Computers in Bellevue, WA. Their phone/FAX number is 206-747-1519. We are distributing the software as shareware in order to keep your cost of this package to a minimum, but it only works if you pay for the software. What is Gemulator? ================== Gemulator is a 68000 CPU simulator (which most people refer to as an emulator) and it includes emulation of Atari ST hardware. Its roots go back to 1986 when we first developed the ST Xformer 6502 emulator to run Atari 400/800 software on the Atari ST. In 1988, ST Xformer was enhanced to make use of the Xformer Cable, which allowed the Atari 400/800 disk drives to be connected directly to the Atari ST. In 1990, Xformer was ported to the PC to allow Atari 400/800 software to run in the MS-DOS environment, and there was born the idea to try to emulate something as complex as the Atari ST. Since the Atari ST's operating system is GEM, it was natural to call the program "GEM-ulator", get it? The Gemulator software, like most other emulators, is really nothing more than an interpreter, taking each individual instruction of 68000 machine language and converting it into 386 code that your PC can understand. For example, an ADD instruction on the 68000 is converted into an ADD instruction on the 386. Due to the similarities of the 68000 and 386, there is almost a one-to-one correspondance in the instruction sets, allowing every 68000 instruction to be emulated on the 386. Certain machine language instructions access the Atari ST's hardware (i.e. screen memory, color registers, mouse and keyboard ports, floppy disk and hard disk controllers, etc), and when the interpreter comes across these instructions it then figures out what hardware location is supposed to be accessed and accesses the appropriate hardware on the PC. As with any interpreter, there is a speed penalty to pay. It takes an interpreter, on average, about 10 steps to execute one instruction. In other words, if machine X wants to emulate machine Y, then machine X needs to be 10 times faster than machine Y to get real-time emulation. That is why, for example, 6502 emulators on the Atari ST or Amiga require a 68030 to get full speed emulation; an 8 Mhz 68000 is not fast enough. Similarly, PC emulators on the ST and Amiga also run slower than a real PC (and we mean the 4.77 Mhz 8088 chip!). When you turn that around, and try to emulate a 68000 chip on the PC, it turns out that you need a 486 machine running at 25 Mhz or faster to get full speed emulation. (Yes, a 486 is almost 100 times faster than the original 8088 chip!). So, for speed reasons, Gemulator has a requirement that you use a fairly fast PC, i.e. one using a 386 or 486 chip. Yes, 386SX and 486SX machines are included. Another reason is that since the 68000 chip uses 32-bit registers, you need a machine that also has 32-bit registers, which rules out the 16-bit 8088, 8086, and 286 chips. Luckily, upgrades are available that allow you to replace your older CPU with a faster one, either by plugging it out and replacing it with a small board containing the faster CPU, or by replacing the motherboard of your computer altogether. You may be asking, "why not just stick a 68000 chip on the board?". Good question, which has two good answers. First of all: cost. Emulating a 68000 chip in software is cheaper than putting a 68000 chip on a board, because not only would you have to put a 68000 chip on the board, but also other chips to allow the 68000 to interface to the 386 or 486. And then you get into engineering problems of how to get the 68000 running at 8 Mhz with 16 data pins to talk to the 33 Mhz 386 with 32 data pins and other messy problems like that. But more importantly, a software based emulator is much more versatile. Changes can be made without having to change any hardware. For example, the 68000 emulator can be updated to a 68020 or 68030 emulator, or the machine being emulated can be changed (i.e. a Mac instead of an Atari ST) by just rewriting part of the emulator. And since most people buying PCs are now getting 486 machines which are capable of full speed 68000 emulation in software, the advantages of the software emulator outweigh the advantages of a hardware emulator. As faster and faster PCs come out (e.g. 66 Mhz 486 DX2, the 586, etc) the speed of the emulator goes up proportionaly without requiring any changes to either the Gemulator board or the software. A hardware emulator would be stuck at a constant speed. Like other emulators, Gemulator requires the use of real Atari ST ROMs in order to emulate the ST. Disk images of the ROMs cannot be used, and that is why it was necessary to develop the ROM Reader board at all. This is similar to the way that the Spectre GCR cartridge works. The ROM Reader board does just that: read the ROM chips into the PC. The board itself doesn't do any 68000 or ST hardware emulation, so future changes to Gemulator WILL NOT require any changes to the board. Just plug the board in once and forget about it. Since the board is a generic ROM reader, it is capable of reading ROM chips other than Atari ST ROMs. So in the future, Mac or Amiga emulation will be possible by using the same board. Note: writing the code to completely emulate the hardware registers of another computer is no easy task, so don't expect a "Maculator" or "Amigulator" any time soon. Running Gemulator ================= The Gemulator software can run on any 386 or 486 based PC compatible running MS-DOS or Windows 3.0 or 3.1. At least 3 megabytes of extended memory (i.e. a total of 4 or more megabytes of RAM) are required. The Gemulator ROM Reader plugs into any 8-bit slot in your PC. If you are using the board, simply plug it in to any unused slot. More detailed installation instructions are supplied with the board. To install the Gemulator files, you need to copy GEMUL8R.ZIP onto your hard disk and unZIP it using PKZip or some other utility. For example, if you have the file on a floppy disk, these are steps you could take: C: MKDIR GEMUL8R CD GEMUL8R COPY A:GEMUL8R.ZIP PKUNZIP GEMUL8R.ZIP Make sure that the files DOS4GW.EXE and GEMUL8R.EXE are in the same directory. If you will be using Gemulator from within Windows, then you may wish to simply copy the files to your Windows directory (usually C:\WIN31). Once the files are installed, just type in the name of the program: GEMUL8R In about 10 to 90 seconds (depending on the speed of your PC) you will get the Gemulator prompt. If you get this far, congratulations, you're up and running, and you can skip ahead to the next section. If for some reason the program did not come up, for example, you get error messages that look something like this: DOS/16M error: [34] DPMI host error (cannot lock stack) or, DOS/4GW Protected Mode Run-time Version 1.8 Copyright (c) Rational Systems, Inc. 1990-1992 DOS/4GW Fatal error: Loader failed -- LINEXE_LOADER then you are probably running out of memory. For as long as your PC has at least 3 megabytes of extended memory, you can get it to work. It gets a little bit technical here, but please read on. DOS4GW.EXE is a 32-bit DOS extender from Rational Systems Inc. What a DOS extender does is make the 386 or 486 chip "kick in" to "protect mode", the 32-bit mode of the CPU. By default, your machine is usually running in what is called "real mode", which is the 8088 compatible 16-bit mode which makes running DOS and all older PC software possible. That is why even on a 486 you still have to worry about things like the 640K limit, because under DOS your 486 is really just running like a very very fast 8088 chip. So to get the full power out of your computer, you have to make it run in protect mode. Windows 3.1, OS/2, and Windows NT all run in protect mode. However, to make a DOS program run in protect mode, you have to run what is called a "DOS extender" such as DOS/4GW. It allows a program to switch the 486 to protect mode, do its stuff in the 32-bit world, and then exit back to the 16-bit DOS world. Unfortunately, 32-bit programs tend to eat up a lot of memory, partly because of the memory required by the DOS extender, partly because 32-bit code is larger than 16-bit code (remember how tiny those 8-bit 6502 programs used to be?), and in the case of Gemulator, because there is a lot of code required to emulate a 68000 chip. That's the problem you're running into. Gemulator uses about 5 megabytes of memory (3 megabytes for the program and data tables, and 2 megabytes which is made available to the 68000 interpreter as Atari ST RAM). So how do we cram this 5 megabyte program into your PC's memory? Let's do this on a case by case basis, first starting with DOS. If you are running on a PC with at least 8 megabytes of RAM or more, you should easily be able to run Gemulator. If not, use the MEM command from DOS to check the amount of memory available. The output will look something like this: (these are just sample numbers!!!) 655360 bytes total conventional memory 655360 bytes available to MS-DOS 580800 largest executable program size 7077888 bytes total contiguous extended memory 0 bytes available contiguous extended memory 5988576 bytes available XMS memory That last line, the one with "bytes available XMS memory" tell you how much available extended memory there is. For as long as that number is larger than 5 meg (roughly 5250000 bytes) you're OK. If the number is smaller, usually because you have a large RAM disk or disk cache set up, either remove or decrease the size of the RAM disk or disk cache. Typically a 512K disk cache is more than adequate. Anything more, and you're wasting memory and not gaining any significant disk speed. Now let's take the case when you have a 4 or 5 megabyte PC, which by itself won't have enough memory to load Gemulator no matter what you do. This is where we take advantage of one of the cool features of protect mode: virtual memory. DOS4/GW can "create" memory by using your hard disk's free disk space for storage. To enable virtual memory, type in the following line from DOS: set DOS4GVM=VIRTUALSIZE#5500 This will set up a 5.5 megabyte virtual memory swap file and allow you to use Gemulator with machines with as little as 3 megabytes of extended memory. Note that the constant disk swapping will cause Gemulator to run slower than if you had all of the memory, so consider upgrading your machine's memory to at least 8 megabytes. Now we come to the case of running Gemulator from within Windows. First of all, because Gemulator is a 32-bit program, Windows MUST be running in Enhanced Mode. Real Mode and Standard Mode are 16-bit modes and won't work with the DOS extender. Once Windows is running, open a DOS window by clicking on the MS-DOS icon in the program manager. When the DOS window opens (or goes to full screen mode, depending on how you have it configured), type in: set DOS16M=:0K and then run Gemulator as you did from DOS by typing GEMUL8R. If you get similar error messages, Windows may be out of memory. Try running it again (as the DOS extender is known to occassionally burp when running under Windows. This is harmless, but annoying). Check the amount of memory available from Windows. From the Program Manager, click on the Help menu and then the About menu item. It will put up a dialog box saying something like: Memory: 7890 KB Free System Resources: 65% Free For as long as the memory number is above 5500K, you should be OK. If the number is smaller, try closing some other windows. If that still doesn't free up enough memory, you will need to resort to using virtual memory again. This can be done either through the DOS extender by using the DOS4GVM line as above, or, preferrably, using Windows' built-in virtual memory. See your Windows manual about setting up swap files. To simplify the setting of these various variables, three batch files are also included with Gemulator: GEMULDOS.BAT, GEMULVM.BAT, and GEMULWIN.BAT. Put them in the same directory as GEMUL8R.EXE, and then type in either GEMULDOS, GEMULVM, or GEMULWIN to run Gemulator from DOS, DOS with virtual memory, or from Windows respectively. Using the 68000 debugger ======================== If your interests lie mainly in running Atari ST software on your PC, and not so much in the 68000 emulation itself, then you may skip ahead to the next section titled "Atari ST Emulation". The 68000 debugger allows you to type in and execute 68000 machine language code. It is based on many similar debuggers, so the commands will probably be familiar to you: D - disassembles memory G - go (execute code) M - dumps memory S - single step code T - trace step code : - edit memory R - edit register All values must be intered in hex, and register dumps are displayed in hex. Single stepping code displays a register dump and a disassembly of the next instruction about to be executed. Tracing just continuously single steps code until a key is pressed. Typing G to execute code will interpret 68000 instructions until the F11 function key is pressed. The number of 68000 instructions executed and an execution speed in terms of IPS is displayed. Use instruction $4AFA to set breakpoints. To edit registers, type R followed by the register name followed by an '=' followed by a value. For example, to set D0 to a value of 12345678 type: RD0=12345678 The debugger at this time has no command to either load or save blocks of memory to disk. If you have a particular object file or executable file format that you would like supported by Gemulator, please contact us with the details. Atari ST Emulation ================== Gemulator emulates a 68000-based Atari ST computer with 2 megabytes of RAM, color and monochrome video output, floppy disk drives, a keyboard, a mouse, and a printer port. Sound, MIDI, the serial port, joysticks, and the blitter are not currently emulated, so this currently rules out the use of some game and music software. Atari ST programs that currenly run with Gemulator include: Pagestream, Calamus, First Word Plus, LDW Power, Avante Vector, Silhouette, Degas Elite, Prism Paint, GFA Basic, GDOS, Word Flair, Neodesk, Hotwire, Multidesk, DC Desktop, Laser C, Mad Mac, Gemini, Tempus, Infocom adventures, A Mind Forever Voyaging, Hero's Quest, Sierra Online games, and Chess Master 2000. Many, many, other ST programs also work with Gemulator. When you run Gemulator, you will get a credit screen followed by something like this: Scanning Gemulator ROM Reader for TOS ROMs... 1: TOS 2.06, 2-chip, dated 11/14/1991 2: TOS 1.04, 6-chip, dated 04/06/1989 GEMULATOR: Enter command or ? for commands: The list contains up to 4 different TOS versions that you may have plugged into the ROM Reader. Since TOS 2.06 is being included with the board, you should get at least the TOS 2.06 line shown. The last line (beginning with GEMULATOR: Enter...), is the Gemulator command prompt. When you see this prompt, Gemulator is waiting for you to give it a command, like QUIT to return to DOS, INSTALL to select and install the TOS ROMs and boot up the ST desktop, or other commands. At this point you may simply type in INSTALL and the emulation will being. Once you see familiar blank Atari ST screen and then the Atari ST desktop, you've turned your PC into an Atari ST. Congratulations! You may use the mouse, keyboard, disk drives, menus, icons, etc, just like you would on the real Atari ST. However, you will probably wish to do some configuring. By default, the emulator boots up in the ST's low resolution color mode. From the GEM desktop you can then switch to medium resolution. On the real ST, to switch to monochrome mode you have to physically change monitors. With Gemulator, you simply type in MONO to do that, or COLOR to switch back. If you are running Gemulator in a DOS window under Windows, you will need to type in WINDOW to let Gemulator know that. When running in a window, the mouse driver needs to communicate with Windows' mouse driver, which is not required when running full screen or from DOS. If you PC has both a 5.25" disk drive and a 3.5" disk drive, chances are that the 5.25" drive is installed as drive A: and the 3.5" drive is installed as drive B:. Not good if you're trying to boot your 3.5" Atari disks! So in this case, type in SWAP. This will treat the 3.5" drive as drive A: and the 5.25" drive as drive B:, in effect, reversing the drives. Use UNSWAP to swap them back. Note that this swapping only affects your ST programs and has no effect on your other DOS or Windows programs! If you have such a 2 disk drive setup, you most likely do not wish to use the 5.25 disk drive at all. By default, Gemulator will only use one disk drive, even when both are present. If you really wish to use both disk drives, type in BOTH. Finally, Gemulator can use some tricks to speed up the 68000 emulation. This option will work with most software but maybe not all, so by default it is disabled. Type QUICK to enable this option, or SLOW to disable it. Once you are configured, type in INSTALL to boot up the ST. At any time while you are running the ST software, you may press the F11 function key to return back to the Gemulator prompt. Do this when you want to exit Gemulator, or when you wish to reconfigure it or re-install TOS. When an ST program crashes, one of several things will happen. For minor crashes, you will see several bombs on the screen (as on a real ST). Some crashes may return you to the Gemulator prompt, in which case type INSTALL to restart the ST. In rare cases the 68000 interpreter itself may be crashed in which case Gemulator itself will lock up. If you are running from DOS, reboot your PC. From Windows, just Terminate the DOS window. Speaking of rebooting, DO NOT, DO NOT, DO NOT use Control+Alt+Delete to reboot TOS! Yes, TOS 1.4 and TOS 2.06 support this, however using this keystroke in Gemulator will still reboot your PC. Instead, use the F12 function key to do the same thing. Notice that the Atari ST and PC keyboards are ALMOST identical. The F11 and F12 keys, which do not exist on an ST keyboard, are used as described above. That leaves two keys on each keyboard that are different: Page Up and Page Down on the PC, Help and Undo on the ST keyboard. So, surprise, surprise, the Page Up key is used as the Atari ST Help key, and Page Down is used as the Undo key. Perfect! If you use F11 to interrupt the emulator to reconfigure it, you may use the G command (G as in GO) to continue where you left off, without having to type INSTALL to reboot the ST. To access the hard disk from ST software, do exactly what you do on a real ST: boot up with a hard disk driver in the AUTO folder of the boot floppy. Other AUTO folder programs, such as Quick ST, Warp 9, Hotwire, DC Desktop, UIS III, etc, can all be used in this way. Supra's SUPBOOT.PRG and Atari's HDX AHDI.PRG drives can be used. Measuring Speed =============== Type in SPEED at the Gemulator prompt, and Gemulator then runs some sample 68000 code which fills up the screen with a pattern. The time that it takes to execute this 68000 code is then used to determine how fast the 68000 interpreter is running, which is expressed in Instructions Per Second (IPS). A millions IPS is, of course, a MIPS. A typical 8 Mhz 68000 runs at between 0.5 MIPS and 2.0 MIPS, depending on the machine language being executed. If Gemulator reports that the test ran at about .8 MIPS (800000 IPS) then you are running at about the speed of an 8 MHz 68000. A 486/25 or 486/33 is required for speeds in this range. Slower machines (such as 386 and 386SX machines) will report speeds slower than .8 MIPs, while faster machines will report faster speeds. For example, a 50 Mhz 486DX machine reports 1.2 MIPS. The speed of Gemulator can be improved by using a 16-bit VGA card instead of an 8-bit card, using a 486 instead of a 386, and by using a faster CPU (for example, 33 Mhz instead of 25 Mhz). The type of VGA card is a very important factor. An 8-bit VGA card (the kind that you see advertised in the $50 range) only allows the CPU to write to screen memory 8 bits (one byte) at a time. That's obviously twice as slow as using a 16-bit VGA card. Even among 16-bit cards, there is a wide variety from brand to brand, resulting in large differences in speed. Gemulator literally runs twice as fast on a 486 machine equipped with a good 16-bit VGA as compared to the same machine equipped with an 8-bit VGA card. Another way to speed up the ST software is, you guessed it, to use a software accelerator such as Quick ST, Turbo ST, Warp 9, or NVDI. Just like on a real ST, these programs speed up the graphics routines in TOS and make your ST software run faster. Some relative speeds of different CPUs are listed below, with a 386/16 (the slowest 386 chip available) being assigned a relative speed of 1.0. The differences between SX and DX chips is fairly small, so those differences are not shown. Keep in mind that other factors such as the VGA card will affect these numbers, so these numbers should be treated strictly as approximate figures: 386/16 1.0 386/20 1.2 386/25 1.5 386/33 2.0 386/40 2.5 486/20 2.5 486/25 3.0 486/33 4.0 486/50 6.0 486/66 8.0 Versions of Gemulator which will be sent to registered users also run faster than the shareware version due to various optimizations to the 68000 emulator that are still being added. Known problems ============== There are several known problems in Gemulator that we are working to fix in future versions of Gemulator. These are not necessarily bugs, but some are. The most serious problem is that right now hard disk is limited to the first 32 megabytes of drive C:. This is because the Atari ST and the PC are SUPPOSED to have identical disk formats. This is true for floppy disks, but not entirely true for hard disks. The partition table sector (the first sector on the hard disk) is completely different on the ST and PC, although Gemulator manages to work around that problem somewhat by allowing the C: partition to be accessed. The next problem is that TOS has a maximum limit of 65536 sectors per hard disk partition. 65536 sectors * 512 bytes per sector equals that magic 32 megabyte number. For hard disk partitions smaller than 32 megabytes, everything is fine. The existing Atari ST hard disk drivers know how to read the disk. For partitions larger than 32 megabytes, Atari hard disks use a different disk format to break the 65536 barrier than PCs do. As a result, the Atari ST hard disk drivers do not recognize the large partitions created by DOS, or at least, nothing past the 65536th sector. This means that right now you have to do one of two things if you want to use the hard disk with your ST software. The first solution is to simply make sure that your C: partition is smaller than 32 megabytes. That may require backing up the files on your hard disk and reformatting the hard disk. The other solution is to use a disk defragment utility such as Norton Speed Disk or PC Tools to put all of your Atari files into the first 65536 sectors. To do that, go to your C: disk and create an ATARIST directory. Copy all of your Atari ST software to that directory (you may put subdirectories within the ATARIST direcotry). Then run the defragment untility. Since ATARIST starts with A, that directory will be put at or near the beginning of the hard disk, and so will the files within it. For as long as you have less than 32 megabytes of Atari ST files, this works. As a safety precaution, the hard disk can only be read from. i.e. you cannot write to, copy to, or delete files from the hard disk from within Gemulator. This is because attempting to do so on large hard disks using existing Atari ST hard disk drivers would trash your hard disk. Our solution to this problem is to write a custom Atari ST hard disk driver that understands the large DOS partitions. A future update of Gemulator will contain this driver built-in to it, eliminating the need for even using AHDI.PRG or SUPBOOT.PRG. The custom driver will also allow any hard disk partition to be accessed, as well as the PC's RAM disks, CD-ROM, and network drives. Similar drivers will also be written to allow Gemulator to work under other operating systems, such as OS/2 and Windows NT. These newer operating systems also use entirely different hard disk formats that makes Gemulator incompatible with them at this time. Other problems. An annoying but harmless bug is that you may notice the mouse drifting once in a while. This will usually happen when the mouse buttons are being clicked, or when using Gemulator in a DOS window. A related problem is that double clicking the mouse is not always detected. Due to the fact that Gemulator does not emulate a constant 8 Mhz 68000 chip, differences in timing may require that you either click slightly slower or slightly faster than you would on a real ST. Of course, you can use the Atari's Control Panel accessory to re-adjust the double click speed. And similarly, programs that are timing dependent will not run correctly. Usually such programs (such as Spectrum 512) also do not run on faster STs or TTs either. Programs that make rapid color pallete changes will also not display properly. The TOS 1.4 "Rainbow" is an example. New features ============ Updates to Gemulator are already in the works. The first update will be mailed to registered users in October. The update, which runs about 10% to 20% faster than this shareware release, includes the ability to emulate a 4 megabyte ST (for running very memory intensive ST programs, or setting up ST RAM disks), and has additional optimizations for 486 computers. Shortly after that we plan to release a version that takes advantage of SuperVGA cards to allow the use of 800x600 screen resolutions with Atari ST software, and a version which has the custom hard disk driver built in. In the 6 to 12 month time frame, features such as joystick support, sound and MIDI support (by using the Sound Blaster card) are planned. Now that you have had a chance to use Gemulator, let us know what you think and what you'd like to see improved or added. If you have any additional questions about using the Gemulator software or the Gemulator ROM Reader board, contact: Purple Mountain Computers 15600 N.E. 8th St. Suite A3-412 Bellevue, WA 98008, U.S.A. phone/FAX: 206-747-1519 To register or get updates to the Gemulator software, contact Darek at: Branch Always Software. 14150 N.E. 20th Street Suite 302 Bellevue, WA 98007, U.S.A. phone: 206-885-5893