Real Time Clock
The ROM (“Read Only Memory”) contains information needed for the Macintosh Plus to function, and the emulation of the Macintosh Plus also needs this information. A program such as “CopyRoms”, when run on a real Macintosh Plus, will save this information to a file, which can then be transferred to the computer on which you want to run Mini vMac. Note that the ROM image file is copyright Apple Computer, and may not be redistributed. So to legally use Mini vMac, you need to own a real Macintosh Plus. If you don’t have a Macintosh Plus, you could check the “Where to buy an old Macintosh” page.
The ROM image file should be named “vMac.ROM” and placed in the folder containing the Mini vMac application. On a Macintosh, the ROM image file may also be placed elsewhere, with an alias (named “vMac.ROM”) to it placed in Mini vMac’s folder. You can do the same in Windows with a “Shortcut” file. (It must be “vMac.ROM”, not “Shortcut to vMac.ROM”. Actually, the file is really named “vMac.ROM.lnk” internally, but what you see is “vMac.ROM”.) The X version looks for the ROM image file in the current directory when the application launches, unless an argument of the form “-r [rom_file]” is used on the command line.
An exception to the above is that in the Mac OS X version, if you create a folder called “mnvm_dat” inside the “Contents” folder within the application bundle (control click on the application and choose “Show Package Contents”), then Mini vMac will look for the “vMac.ROM” file, and the disk1.dsk, disk2.dsk, etc files, within the “mnvm_dat” folder. This allows you to make a self contained Mac OS X application that runs an application for the Mac Plus (especially when used with the “AutoQuit” software.)
If Mini vMac, on Mac OS X or Windows, doesn't find the ROM in the locations described above, it will also look in a specific central location. In OS X it checks in "/Users/[your_UserName]/Library/Preferences/Gryphel/mnvm_rom/". In Windows XP, "C:\Documents and Settings\[your_UserName]\Application Data\Gryphel\mnvm_rom\". Windows 98, "C:\WINDOWS\Application Data\Gryphel\mnvm_rom\". And in Vista, I think "C:\Users\[your_UserName]\AppData\Roaming\Gryphel\mnvm_rom\". Usually "mnvm_rom" would be an alias (on OS X, on Windows this is called a short cut) to where ever you keep your ROM collection. This avoids having to create an alias to the ROM image for each emulated Mac you use.
Mini vMac will verify the checksum of the ROM on launch. There is code in the ROM to do this when the Macintosh Plus boots, but since Mini vMac patches the ROM to replace the disk driver, it also patches the ROM to disable the checksum verification. So Mini vMac does the check itself, before patching the ROM, and gives a warning message if the checksum is incorrect. Since no harm can be done no matter what is in the ROM, this is only a warning, and Mini vMac will keep running. Mini vMac does not check if the ROM image file is too long (it should be 128K = 131072 bytes).
There are three different versions of the Macintosh Plus ROM. Versions 2 and 3 work with Mini vMac. The original (and rare) version 1 ROM was recently reported not to work, presumably because of problems with SCSI emulation. There are only a few bytes different in version 2 from version 1, to fix a bug where the Macintosh Plus wouldn't boot if an attached SCSI devices was not turned on.
On: Launching the Mini vMac application turns on the power switch of the emulated computer. Double click on the applications icon to launch Mini vMac in Macintosh or Windows. The application can be launched from the command line in Linux and Windows. There are also many other ways of launching applications for each operating system, such as by installing it into the dock of Macintosh OS X, the Apple menu of Macintosh OS 9, or the start Menu of Windows.
Off: Quitting the Mini vMac application is like turning off the power switch of the emulated computer. Just like with the real computer, you should shut down the operating system running within the emulated computer first. Mini vMac can’t tell if the emulated operating system has been properly shut down, but it can tell whether any disk images are currently mounted, and so uses that as the test for warnings.
If no disk images are mounted, Mini vMac can be quit with Control-Q, or by clicking in the close box of the Mini vMac window, or with the quit command in the menu (Macintosh/Windows).
If a disk image is mounted, clicking in the close box or choosing the quit command in the menu will bring up a warning dialog. Choosing Control-Q will display a warning, with the option of typing ‘Y’ to force quit.
It is also possible for software running within the emulation to cause Mini vMac to quit automatically. See “AutoQuit”.
The Macintosh Plus has one internal floppy disk drive, that can use 3.5 inch 800K double sided disks or 400K single sided disks. In addition, an external floppy drive can be attached. Mini vMac does not emulate the floppy drive hardware but instead patches the ROM with a replacement disk driver, which can mount up to 6 “disk image” files. The information on a floppy disk can be transferred to a disk image file. The preferred disk image format for Mini vMac is a file containing just the image data, with no header, trailer, or resource fork (and therefore without checksums or tag data). Mini vMac will accept disk images in formats with trailing information and no header, except that it will pass an incorrect disk size to the emulated computer, which affects programs such as Disk First Aid.
Mini vMac also supports disk images in “Disk Copy 4.2” format, which has an 84 byte header, and usually contains checksums and tag data. These images are mounted read only. The utility CnvtDC42 converts Disk Copy 4.2 format images to a new image without the tags and checksums and header, that Mini vMac can write to. Alternatively, Mini vMac can be compiled with full read/write support for this format.
Compressed disk images are not supported.
Besides 400K or 800K, the replacement disk driver of Mini vMac will also work with disk images of any other size less than 2G. It will pretend to have something more like a hard disk, though not exactly. This is not too authentic, but it is very useful. Mini vMac defines its own icon for these disks (with a ‘v’), which can be seen in the Finder on the emulated computer.
Bootable disk images should use the “Hierarchal Filing System” (HFS, now called HFS standard). The Macintosh Plus doesn’t understand the newer “HFS extended”. The older “Macintosh Filing System” (MFS) will also work, but this mostly is useful only for communicating with the emulation of the Macintosh 128K. Once the Macintosh Plus is booted, some Macintosh system versions will support additional kinds of disks, such as DOS.
Mini vMac can boot with any system version that works on a real Macintosh Plus, that is, up to “7.5.5”.
There are many ways to “mount” a disk image in Mini vMac. (That is, to insert an emulated disk into an emulated floppy drive.) The icon of the disk image file can be dragged on to the Mini vMac window (Then, if the Mini vMac window isn’t in front, it will be automatically activated). In the Macintosh or Windows versions, the icon of the disk image file can be dragged on to the Mini vMac application icon (If Mini vMac is already running, in the Macintosh version the disk image will be opened in the existing process, while in the Windows version a new instance of Mini vMac will be launched). Also in the Macintosh or Windows versions, choosing the “Open Disk Image...” command from the “File” menu, or the ‘O’ command from the Control Mode, will bring up the standard dialog to select a disk image file. In the X and Windows version, disk images can be specified in the command line.
When Mini vMac is launched, it can automatically mount disk images named “disk1.dsk”, “disk2.dsk”, up to “disk6.dsk”. In the Macintosh and Windows version it will look for them in the folder containing the application. (Except that in the Mac OS X version, if the “mnvm_dat” folder exists it will look there, in the same way it looks for the ROM image.) In the X version it will look in the current directory. In the Macintosh version, these files may be aliases. In the Windows version, they may be shortcut files. Mini vMac stops at the first image not found, i.e. if there is no “disk2.dsk”, it won’t open “disk3.dsk”, even if it exists.
A disk image file may be locked. The emulated computer sees this as a disk with the lock tab set. This allows you to use a disk image and be certain the image file won’t be modified. You can also share a single locked image file among multiple running copies of the emulator.
Never mount an unlocked disk image simultaneously in two running copies of the emulator. And never mount a disk image in an emulator and at the same time mount it on the real computer. Such double mounting will usually corrupt the disk image irreparably. Double mounting is not actually possible in Mac OS 9 or in Windows, but one of the worst design decisions in Mac OS X was to allow two programs to open the same file with write access, with no way to prevent it. The Linux version seems to share this flaw.
You can get a new blank disk image from the “Blanks” archive. For information about transferring files on your real computer into the disk image files used by the emulated computer, and transferring files back to your real computer from disk image files, see the page about Disk Images.
The save operation of a program for the Macintosh Plus would normally force changes to be written out to disk (and not just left in RAM caches). When running in Mini vMac the changes will be written to the disk image, but the changes to the disk image may not be written out immediately to the real disk. So if the real computer crashes or loses power, saved changes may be lost. In the Macintosh and Windows versions, changes to a disk image are forced to be saved to the real disk when the image is unmounted.
If you try to mount more than six disk images mounted at once, Mini vMac will display an error alert. This limit can be raised up to 32 disk images, with some memory and time overhead, by recompiling.
The floppy disk drives of the Macintosh Plus have a small hole into which a straightened paper clip can be inserted, which will force the floppy disk to be ejected. Mini vMac doesn’t implement this feature. You can always force Mini vMac to quit, or reset, either of which will unmount all disk image files.
All Mini vMac disk access is currently synchronous, so, for example, mouse movement stops, and sound can be interrupted. This might be changed in some future version.
The Macintosh Plus has a Motorola MC68000 processor, running at 7.8336 MHz. The emulated processor of Mini vMac can run at approximately that speed (1x), but a number of other settings are also available: 2x, 4x, 8x, 16x, 32x, and All out.
The speed setting can be controlled by the ‘S’ command of the Control Mode, that leads to another screen with more options. There is also a command line option for the Windows and X versions to start Mini vMac at 1x speed.
The maximum speed depends on the speed of the real computer on which it is running. Setting Mini vMac to run faster than this maximum is equivalent to setting it to “All out”. Otherwise the percentage of CPU time taken by Mini vMac depends on the speed setting. On some computers the fans will start running very loudly if a high percentage of the CPU time is in use.
So by default Mini vMac is set to run at 8x, instead of “All out”, so as not to stress current modern computers, but still feel reasonably snappy. Setting the speed to 1x makes some older games more playable, which weren’t written with faster computers in mind, and would otherwise play much too fast.
Also a few programs may break in other ways at faster than 1x. When running faster, the emulated computer thinks time is running normally for each sixtieth of a second, but at the end of each sixtieth, a lot of instructions get executed instantaneously. This gives quite good, but not perfect, compatibility. The minimum emulation speed is 1x. If the real computer isn’t fast enough to do 1x, the emulated computer will still think it is running at the normal number of instructions per time, but its sense of time will not match the real time.
The speed setting is only an approximation. Mini vMac estimates execution time using a table of average number of cycles for each of the 65536 primary opcodes. Less or more accurate timing can be selected at compile time.
Mini vMac will automatically shift down to 1x speed if there is no activity for a while. This is called the "AutoSlow" feature. It helps to preserve the battery on portable computers.
If the user types, or clicks or moves the mouse, or the emulated computer draws to the screen, or reads or writes to an emulated disk, that counts as activity that prevents AutoSlow. AutoSlow takes effect after either 0.5 seconds of emulated computer time, or 16 seconds worth of emulated instructions executed (usually about 2 seconds at the default 8x speed), which ever is longer.
It is possible that some software will not draw anything to the screen for longer than that while doing real work, so the AutoSlow feature can be disabled with the “autosloW toggle” in the ‘S’ command of the Control Mode.
Mini vMac finds the smallest rectangle that enclosing the area of the screen that has changed every sixtieth of a second. This makes Mini vMac more efficient, since transfering images to the real screen tends to be expensive. If this rectangle is only a single pixel wide and less than 32 pixels tall, it is assumed to be only a blinking insertion point, that doesn't prevent AutoSlow.
By default, the emulation stops when the Mini vMac window is not front most. But the ‘S’ command of the Control Mode includes a “run in Background toggle”. So you can set some computation going in Mini vMac and then use other programs on your computer. You can set Mini vMac to run in the background with the speed set to “All out”, but this isn’t recommended, except on a dual processor computer (Mini vMac can only use one processor).
The emulation can also be stopped even when the Mini vMac window is front most, by using the “Stopped toggle” in the ‘S’ command of the Control Mode. This can be useful, for example, to pause a game.
In OS X, the emulation will continue running (but only at 1x) while dragging the Mini vMac window, selecting from a menu, or while a dialog is up. In Mac OS 9, the emulation will stop at all of these times. In other operating systems, the emulation may stop at some these times. In Mac OS 9, which uses cooperative multitasking, Mini vMac will only run smoothly if all other running programs are very cooperative.
When in Full Screen Mode, with speed set to “All out”, some versions of Mini vMac will try to prevent other programs from running as much as possible, for the smoothest possible emulation. This is so far implemented in the Mac OS 9 and Windows versions.
A Macintosh Plus can have 1M, 2M, 2.5M, or 4M of “RAM” (Random Access Memory). Mini vMac normally emulates a computer with 4M of RAM, but this can be changed to one of the other 3 values by recompiling.
The Macintosh Plus has a 512 by 342 pixel black and white screen, redrawn 60.15 times per second from one of two “screen buffers” in RAM. Mini vMac examines the current screen buffer 60.15 times per second, and compares it to the previous contents. If something has changed, the current buffer is drawn to the real screen, minus any unchanged lines at the top and bottom. If emulation is lagging (below the speed of a real Mac Plus), it will only redraw a part of the screen each time.
When Mini vMac launches, it creates a 512 by 342 window to display the emulated screen. In the Macintosh and Windows versions, this window is given the same name as the Application. (So if you rename the Mini vMac application, when you launch it the window will have that new name.)
There is an option to double the size of the display. This can be easier to read, since modern screens often have smaller pixels than in the original Mac Plus (about 1/74th inch). Magnify Mode can be toggled with the ‘M’ command of the Control Mode.
Some computer monitors have trouble displaying the 50 percent gray pattern commonly used on old Macintoshes. Magnify Mode helps to alleviate this problem.
Magnify Mode can have performance problems on some computers with some operating systems. While a modern computer has no trouble emulating the processor at ten times the speed of the original if the screen doesn’t need to be redrawn, drawing full screen video at 60.15 frames a second can be a problem.
Mini vMac has a Full Screen Mode, where the menus and other programs are hidden, leaving only the emulated screen. The Magnify option is turned on automatically if your screen has high enough resolution (1024 pixels across or greater). Full Screen Mode can be toggled with the ‘F’ command of the Control Mode.
If the emulated screen is larger than the real screen while in Full Screen Mode, the emulated screen will be scrolled to keep the mouse pointer in view. This may not work well if the software running on the emulated computer hides the mouse pointer.
Toggling Full Screen Mode affects more than just the display. The design idea is that when in the regular mode, Mini vMac should try to behave as much like a normal cooperative application as possible, while in Full Screen mode it will try to take over the entire computer as much as possible. In Full Screen Mode, Mini vMac will try to monopolize the processor, and grab the keyboard. Also, the mouse is emulated differently in Full Screen Mode.
There is not supposed to be any way to leave Full Screen mode except for the ‘F’ command of the control Mode. However, sometimes there is no way to prevent the operating system from bringing up some other program. Mini vMac will detect if it is no longer the active application, and turn off Full Screen mode.
The X version has a command line option, “-display [display_name]” or “--display [display_name]”. XOpenDisplay will be called with [display_name] as the argument. This apparently allows you to choose what screen the Mini vMac window will open onto, even onto a screen of another computer. This has never been tested.
The Macintosh Plus has an external keyboard with its own processor. Mini vMac emulates the protocol used to talk to this keyboard. This protocol deals with keys being pressed and released, so Mini vMac looks at the keys being pressed and released on the real computer, instead of the characters that the real computer would normally translate them into. So Mini vMac may not be affected if the real computer is set to use the Dvorak layout, for example. But you can make the operating system running within Mini vMac use a Dvorak layout if you want it. This low level keyboard emulation has the advantage that all the Macintosh special characters can be typed in the Windows and X versions, and that software such as the debuggers MacsBug and TMON will work.
The keyboard communication protocol will support keys not present on Macintosh Plus keyboard (“Page Down” for example). So Mini vMac goes ahead and transmits the modern keys. One modern key not present on the Mac Plus is the ‘control’ key. Mini vMac provides a way to press the control key of the emulated computer, even though the control key is being used for the Control Mode. “Control-K” presses the emulated control key, and “Control-K” again releases it.
In the Windows or X versions, the ‘alt’ key is used for the emulated command key, and the ‘windows’ key (or the ‘application’ key) is used for the emulated option key.
In all versions, the F1 key can be used as the emulated option key and the F2 key can be used as the emulated command key. This provides a way to type some key combinations that are intercepted by the OS of the real computer. For example, F2-Shift-3 will take a screen shot in the emulated computer, whereas on a Macintosh, Command-Shift-3 takes a screen shot of the real computer at the same time.
When you switch away from Mini vMac, all emulated keys are released (except for the emulated caps lock and control keys). (You can not see the change then unless “run in Background” is on.) When you switch back to Mini vMac, the emulated keys remain released, and the real keys held down at that moment are ignored.
There is an exception to this when you drag a file onto the Mini vMac window, so that Command-Option will work to rebuild the desktop of a disk image. However, the keys that map to command and option can have special meanings in other operating systems. (For example, in OS X, clicking on the window of another application with command and option down will hide all other applications.) So it usually works better to press command-option right before dropping, instead of before dragging.
When in Full Screen Mode, Mini vMac will try to “grab” the keyboard, preventing the operating system from intercepting keys. So in the Windows version, the ‘windows’ key can be used as an ‘option’ key, instead of popping up the “Start” menu. And in the OS X version, Command-Tab won't switch away from Mini vMac. This is also implemented in the X version.
The Macintosh Plus mouse has a ball that turns two rollers as it moves, one for horizontal and one for vertical. The rollers are each connected to a disk with a series of small holes. As the holes pass by a sensor, the Macintosh gets interrupted. There is a second sensor to allow the Macintosh to tell which edge of the hole, and so which direction the mouse is moving. The interrupt handler keeps count of how the mouse is moved. Then 60.15 times a second, it sees how far the mouse has moved and updates the cursor on the screen.
Mini vMac does not emulate the mouse hardware. Instead, it has two different behaviors depending on whether Full Screen Mode is on.
If not in Full Screen Mode, then 60.15 times a second Mini vMac translates the coordinates of the mouse on the real computer to coordinates on the emulated screen, and directly pokes this location into low memory of the emulated computer. This not very authentic mouse emulation is convenient in that you can easily move the mouse from the Mini vMac window, to click in the menu bar or to activate another program. But this emulation is not good enough for some programs (such as Crystal Quest, HeartQuest, Slime Invaders, Arkenoid, MacLanding, Apache Strike, Stepping Out, and Microsoft Flight Simulator), and for other programs (such as Dark Castle) it is preferable to constrain the mouse to the emulated screen, so you don’t deactivate Mini vMac by accident.
When in Full Screen Mode, 60.15 times a second Mini vMac checks how far the mouse has moved, and pokes this into low memory of the emulated computer in the same fashion as the real mouse movement interrupt would do. I don’t know of any program for which this emulation isn’t good enough, so there are no plans for an even lower level emulation of the mouse movement interrupts. The emulated Macintosh Plus is initialized to use “very slow” mouse movement, and the velocity of the real computer’s mouse is passed directly to the emulated computer. So the mouse in the emulated computer behaves like the mouse of the real computer. For a more authentic experience, you can set the real computer’s mouse to slow, and then increase the speed of the emulated computer’s mouse.
The method used to get the velocity (not just absolute location) of the mouse of the real computer may not work on all computers. Mini vMac has code that attempts to detect when this doesn’t work, and then switches to the absolute position mouse emulation. However this check fails to detect problems when running the Windows version of Mini vMac within Microsoft Virtual PC with Pointer Integration turned on, and when running the Mac OS 9 version of Mini vMac in classic environment of OS X.
Because Mini vMac translates the real mouse coordinates to the emulated screen, when in Magnify Mode the mouse moves half as fast.
The Macintosh Plus mouse has a single button. In the Windows version of Mini vMac, if either the left or right mouse buttons are pressed, the emulated mouse button is pressed. In the X version mouse buttons 1, 2, and 3 are equivalent.
The Macintosh Plus can play 8 bit sound at 22255 samples per second from one of two “sound buffers” in RAM. It can also toggle sound output at multiples of 1.2766 microseconds to generate square waves. The sound volume can be set to one of eight levels.
Sound is so far implemented in the Macintosh and Windows versions, and also the X version has an experimental compile time option for sound using ALSA. The volume is initially set to maximum. Square wave sounds are approximated, being forced to fit into the same 22255 samples per second as other sounds.
Sound in the Windows version will only work on computers that can play sound at 22255 samples per second, rather than a more standard value like 22050. If this turns out to a serious problem, perhaps a future version of Mini vMac could be made to just play the sound at 22050 samples per second, on computers that don’t support 22255, making all the pitches off.
If the sound from Mini vMac sounds choppy, you could try to quit other programs running on the real computer. And in Mac OS 9 and in Windows, turning on Full Screen Mode will make Mini vMac try to take more of the real computer’s time. To emulate sound properly, Mini vMac needs to get time each and every sixtieth of a second. If Mini vMac gets interrupted now and then for a few sixtieths of a second, then the generated sound will have gaps, and sound absolutely horrible. A program that simply plays music doesn’t have the same problem as Mini vMac, because it can generate the sound well in advance of when it needs to be played. Mini vMac has to play the sound as soon as possible after generating it, or the sound will lag behind the rest of the action on the emulated computer.
The Macintosh Plus has something called the “vertical retrace interrupt”, which occurs once per screen refresh, 60.15 times per second. Each time it increments a low memory variable called Ticks. This provides the main way the Macintosh controls the speed of user interface elements, such as caret blink time, scrolling speed, and window open/close zooming speed.
Mini vMac tries to maintain the correct value of 60.15 times per second, but it enforces a minimum number of instructions executed per tick. If it notices that the emulation is lagging, it will try to sacrifice the smoothness of video.
Real Time Clock
The Macintosh Plus has a clock (the RTC, for “Real Time Clock”) that counts seconds since midnight January 1, 1904. This count is a four byte value, so it wraps around after February 6, 2040 6:28:15 AM. The RTC keeps this count even when the computer is off, using battery power. The count is loaded from the RTC into low memory after the computer is turned on, and most of the time this copy is used and updated (by incrementing it every second) without referring to the RTC.
Mini vMac sets the emulated RTC from the real computer’s clock 60.15 times a second. This may not affect the count of seconds kept in low memory, so the time displayed on the emulated computer can become inaccurate if its once a second interrupt is missed, such as if the emulation is paused.
One workaround for this problem is to have the Alarm Clock desk accessory open. This apparently forces the count in low memory to be reloaded from the RTC. (I don’t know why. Maybe this is a bug in the desk accessory rather than its intended behavior.) Another alternative is “ClockFix”.
You can set the time of the emulated computer in Mini vMac, such as by using the control panel or the alarm clock desk accessory. This doesn’t change the time of the real computer; the emulated RTC is changed, which then keeps a constant offset from the time of the real computer.
The Macintosh Plus stores various preference settings, such as sound volume, in “Parameter RAM”. This small area of memory is preserved even when the power is off.
Mini vMac emulates the Parameter RAM, but it does not preserve the contents. Every time Mini vMac launches, the Parameter RAM is reset to default values.
These default values are not the same as the default values of a Macintosh Plus. The sound volume is set to 7, instead of 3, if sound is emulated, otherwise it is set to 0. Mouse movement is set to very slow, so that mouse emulation scheme used in Full Screen mode will work nicely, with the cursor moving at the same speed as it does on the real computer. AppleTalk is set to off, since there is nobody to talk to. The Macintosh version will initialize the time zone, latitude, and longitude from the real computer’s information. The Windows version only initializes the time zone. I have some code that can find the time zone for the X version, but I’m not sure how portable it is, so it is disabled.
The Macintosh Plus has a SCSI (Small Computer Standard Interface) port for connecting to peripherals such as hard drives and scanners.
Mini vMac tries to correctly emulate the behavior of the SCSI port with no peripherals attached.
The Macintosh Plus has two serial ports for connecting to peripherals such as modems and printers, and also for connecting to an AppleTalk network.
Mini vMac tries to correctly emulate the behavior of the serial ports with no peripherals attached.
The Macintosh Plus can optionally have installed a “Programmers Switch”, which has two buttons. The Interrupt button will invoke any installed debugger.
The ‘I’ command of the Mini vMac Control Mode presses the Interrupt button of the emulated computer. This action must be confirmed by typing ‘Y’.
The optional “Programmers Switch” for the Macintosh Plus also has a Reset button.
The ‘R’ command of the Mini vMac Control Mode presses the Reset button of the emulated computer. If any disk images are mounted, this action must be confirmed by typing ‘Y’. All unsaved changes are lost.