LisaEm User's Guide v1.2.
LisaEm User's Guide The World's First Fully Functional Lisa EmulatorTM Copyright (C) 2007, by Ray A. Arachelian http://lisaem.sunder.net “Here's to the crazy ones, the misfits, the rebels, the troublemakers, the round pegs in the square holes... the ones who see things differently -- they're not fond of rules... You can quote them, disagree with them, glorify or vilify them, but the only thing you can't do is ignore them because they change things...
About LisaEm
About LisaEm LisaEm emulates Apple Computer's Lisa 2/5 computer. LisaEm is the world's first Lisa emulator project, started in late 1997, and it is the first to be able to emulate enough of the Lisa hardware accurately enough so as to be run the Lisa Office 7/7. While other emulators for the Lisa exist now, they do so because of the efforts of this project.
License LisaEm is released under the terms of the GNU Public License 2.0. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Requirements
Requirements Host CPU and memory: LisaEm needs a fairly fast machine. It provides decent performance on machines such as a Intel PIII-750MHz with ample free memory. It is able to emulate a 5MHz Lisa on a 500MHz G4 with 512MB of memory on Mac OS X 10.3.9. LisaEm makes extensive use of memory as part of its operation in order to speed up its operations. Its footprint has been noted to rise above 64MB on some environments depending on the options used.
Downloading and building LisaEm
Downloading Binary and Source Versions: LisaEm is available for download from http://lisaem.sunder.net/downloads.html Pre-Compiled versions of LisaEm are available for Mac OS X (intel and PPC), win32, and Ubuntu Linux. Note that due to the variation between Linux distributions, it is recommended to compile your own version for your system from source. Some Linux distributions may provide precompiled packages and binaries for their distribution.
Building LisaEm: From your OS's shell or terminal program (use cygwin on win32), run the following commands: bzip2 -cd lisaem-1.2.5 | tar xvf cd lisaem-1.2.5 ./build.sh clean build sudo ./build.sh install # # # # Extract the archive enter the directory build the software optionally install it. On win32, remove the sudo command. Just issue ./build.sh install by itself. Additional options can be found by running ./build.sh –help. On Mac OS X systems, the –with-rawbitmap option is automatically enabled.
Compatibility
Compatibility If you are unfamiliar with the Apple Lisa computer, reading the LisaFAQ is highly recommended. see: http://lisafaq.sunder.net as it also contains pointers to other Lisa information such as operation manuals and guides. The following software has been reported to work under various versions of the emulator: Lisa Office System 3.x Lisa Pascal Workshop 3.x MacWorks XL MacWorks Plus LisaTest (video timing test fails, the VIA tests pass internally, but lock up LisaTest.
Configuring LisaEm
Configuring LisaEm The screenshots in this documentation come from the Mac OS X version. Your display may vary from these. The screenshots come from various different versions of LisaEm, and because of this, the coloring will vary slightly. If you have a copy of the Lisa Boot ROM that you wish to use, tell the emulator where to find it. To do this, open the Preferences dialog box which can be found under the File Menu, except on Mac OS X, where it can be found under the LisaEm menu.
The Lisa Boot ROM With version 1.2.0 and later, Lisa Boot ROMs are not required. The emulator will work without a boot ROM. If you happen to have a proper boot ROM, you should use it, except if it happens to be the 3A ROM and you wish to run something other than MacWorks. In that case, you should run LisaEm ROMless. The emulator can support several formats for the Lisa boot ROM. If you have extracted the ROMs from your Lisa's CPU board and read them in with a ROM dumper, you should save them as booth.
The Dual Parallel Card ROM One of the more popular expansion cards for the Lisa was the Dual Parallel Card. This card allowed Lisa users to expand the Lisa's storage by adding extra ProFile hard drives and also allowed connections to the Apple Dot Matrix Printer. If you have this card on your Lisa and dumped its ROM, point the emulator at its ROM file. (You do not actually need this ROM to make use of of the dual parallel card emulation.
Running ROMless As of version 1.2.0, LisaEm no longer requires the Lisa Boot ROM in order to start an operating system, such as the Lisa Office System. If you do not have a proper boot ROM file, simply leave the Lisa ROM field underneath the config tab of Preferences empty. If you use a file that cannot be found, or have no access to as a boot ROM, LisaEm will run ROMless, and present the ROMless Boot dialog below.
The Dual Parallel Card in ROMless Mode Note that you cannot boot from Profile drives attached to expansion port slots when running ROMless. To do that, you would need both the Lisa Boot ROM and the Dual Parallel ROM. Even if you have the Lisa Boot ROM, if you do not have an actual Dual Parallel Card ROM, LisaEm will not allow you to boot from ProFile drive images attached to virtual dual parallel boards on expansion slots.
The Lisa Serial Number: To properly make use of existing Lisa Office System disks in the emulator, you'll have to use the same serial number on LisaEm as on your real Lisa, otherwise the Lisa tools will fail to install. LisaEm will offer you the option of deserializing both Office System installation disks and Tool disks, if you do not wish to go through this task.
The I/O ROM version: The Lisa emulator does not actually use the I/O ROM itself, all it needs is the ROM version to report it to the running operating system. The I/O ROM version most commonly used in the Lisa 2/5 is A8. Version 88 is for the Lisa 2/10. The emulator does not support Widget drives, so you should stick to A8. Versions 88, 89, A9 are meant to be used with Xenix to fool it into using the right sized drive.
The ports tab:
Serial Ports: The ports tab allows you to configure LisaEm's connections. At the top are serial ports A, and B. These can be connected to nothing, a loopback plug, an OS pipe, a file, an ImageWriter printer, or on some systems (linux, or OS X) can run a telnet daemon. The loopback plug connects both serial ports together. If you select this plug on either port, both will be connected. For file, the file will be connected to either an actual file, which will be read, or to a device, such as /dev/ttya.
Profile hard drive creation: The first time you power on the emulator, if a specified virtual profile disk image file does not exist, you will be asked what size drive to create. Note that only the 5MB and 10MB Profiles will work with the Lisa Office System. If you use any other size, only the first 5MB will be used, wasting the rest of the space.
The print tab: The print tab in the Preferences dialog box allows you to set the ImageWriter/ADMP's DIP switches. The defaults for the Lisa are automatically selected: The Print to Images check box allows you to redirect printouts to image files. Depending on how wxWidgets or the availability of image libraries in your operating system these may be saved as PNG's, TIF's or BMP's. The text field allows you to chose a directory to save the printouts in.
Running the emulator for the first time Once you have properly configured the emulator's preferences, you should press the Apply button to save your preferences. The Preferences dialog box will then be dismissed. If you forget this step, or wish to discard the changes you've just made, and close the Preferences window using the X button, you will lose your changes. When you are ready, you can power on the virtual Lisa. There are several ways to do this.
Installing the Lisa Office System
Installing the Lisa Office System: Once the Lisa self tests are done, you'll see the boot menu: (If you're running ROMless, you'll see the ROMless Boot dialog instead. Pick the Floppy Diskette option, and you'll be prompted for a Floppy Disk Image to boot from.) Insert the microdiskette labeled Lisa Office System 1, by using the File menu item named Insert Diskette. Alternatively, if you have skins enabled, click on the picture of the floppy drive.
You may need to pull down the Enable menu to select All, Disk Copy 4.2, or DART depending on the type and name of the disk images you have. On some host OS's, such as Linux with GTK and some versions of OS X, you may have to click on a triangle button to get the dialog box to fully open. Select the Lisa Office System 1 of 5 disk image from the file picker dialog box. The LOS installation disk will now boot. In a few seconds you'll see the LOS splash screen.
Once the Lisa Office System installer has loaded, you'll see the installation menu as depicted above. Press the Install button at this screen to start the installation process. The Installer will now search for a ProFile hard drive to install The Lisa Office System onto. Ideally this should be the profile attached to the parallel port. Press the OK button to allow the installer to use this Profile.
Click on the Don't Share button. If you would like to also use MacWorks, or another environment, you should create another Preferences file with its own profile drive instead. Sharing the drive results in limited space, which will cause space issues on a 5MB profile, preventing Lisa Office System from functioning when all of the tools are installed. The installer will now erase the profile.
Once the disk is copied, the installer will then eject Lisa Office System 1/5 and ask for the next disk, disk 2. You do not have to press the Continue button as the installer will recognize that a floppy has been inserted and will be able to tell if it is the disk it wanted. You'll repeat this process until LOS is fully installed. At the end of the installation process, it will ask for the first disk again. You must insert the same disk image you first booted from in order to complete the install.
You'll soon be returned to the main menu. Since you're done installing, click on the Finished button. Select Start Up in order to boot from the freshly installed Lisa Office System on the profile. Lisa Office System has now been installed. If you are returned to the Power On boot menu, click on the Profile icon. Lisa Office System will then boot.
Instaling the Lisa Office System Applications (also known as tools): Once you see the Office System Desktop, you'll want to install some of the applications, which in Lisa speak are known as tools. Next, insert one of the tool (Application) disketters such as LisaCalc. It's icon will show on the Lisa desktop. The disk will show up on the Lisa Office System desktop.
With the Lisa Calc window open, pull down the Edit menu and select the "Select all Icons" item. (Alternatively, you could use the mouse to drag a square around the icons.) This will highlight, the icons so that you can duplicate them to the virtual hard drive.
Do not drag the icons to the hard drive, as this will move them – that is erase them from the floppy once they're copied to the profile hard drive. Instead, once the files are highlighted, pull down the File/Print menu and select the Duplicate item. The selected icons will form “blinking shadows” underneath them.
Drag these blinking “shadows” to the hard drive window or its icon, to start copying them. The Lisa desktop will now copy the files. Note that Lisa tools are serialized: the first time they are used, the Lisa's serial number is written on them to prevent them from being installed on any other Lisa. You should have backup disk images made if you are using original Lisa disks before continuing. You'll be asked if this is what you want. Press Copy to allow the tool to be installed.
Once the copy completes, you can eject the LisaCalc disk by pulling down the Housekeeping menu and selecting the Eject Micro Diskette option. Repeat the installation process with the remaining Lisa tools (applications.) Note that LisaWrite's dictionary file is actually split across onto the second disk and lives on both disks. Don't try to copy it along with the other files, instead once LisaWrite and the examples are copied across, duplicate just the dictionary.
Once the first portion of the dictionary is copied, the diskette will eject, and you'll be prompted to insert the second diskette. Once the copy is completed, you can eject the diskette. NOTE: Be sure to press the power key before quitting the emulator so that you do not corrupt the file system on the virtual profile hard drive.
Installing the MacWorks XL Environment
NOTE: The current version of LisaEm has bugs preventing the use of MacWorks! Presently, the 2007.01.28 Preview version of LisaEm is the only one that works with MacWorks! MacWorks, MacWorks XL, MacWorks Plus aren't real emulators, but rather they are closer to a virtualization program that allow the Lisa to run early Mac OS software. MacWorks consists of two diskettes. A boot diskette containing MacWorks itself named MacWorks Boot, and a copy of the Macintosh System named MacWorks System.
MacWorks is best viewed in the "Raw" display mode, since it will provide the square pixels needed by MacWorks. If you would like to experience the non-square pixels that the Lisa had without the screen modification kit, leave the Display setting to AntiAliased. Once you power on the virtual Lisa, you will be prompted for the size of the profile drive you wish to create since this is a new drive. With MacWorks, you can chose any of the sizes presented.
You'll see the usual Happy Mac icon, followed by the MacWorks splash screen Once it boots up, open up the MacWorks System Disk and run the application titled Hard Disk Install. Either double click on the icon, or use the File menu's Open item to launch it.
Since this is a fresh hard drive, HD Install will say its not readable. Click on the Erase button. If you have Lisa Office System or Pascal Workshop installed, you'll be asked if you'd like to share this disk instead. HD Install is now formatting the virtual Profile hard drive for MacWorks, by erasing all the sectors on it, and installing the MFS file system. When it is done erasing the disk, it will display the above dialog box. Press Ok to continue.
Next, Insert the MacWorks XL diskette when prompted. HD Install is now copying the MacWorks software to your profile hard drive. After the copy completes, the MacWorks XL disk will be ejected, and you'll then be prompted to re-insert the System diskette.
Next, name your profile hard drive. This is the name that will show up on the Desktop. IMPORTANT: The install is complete, but you must copy the system folder to the hard drive, otherwise attempting to boot from it will cause a Sad Mac error, from which you'll not be able to recover except by throwing away the Profile hard drive image and starting over! Use the mouse to drag System folder icon to the Profile hard drive.
The Finder is now copying the System Folder to the Profile hard drive. Once it's done copying, you can use the Special menu item Shutdown to power off your virtual Lisa. Whenever you want to boot up MacWorks, you'll still need to first boot from the MacWorks XL boot floppy, however, once loaded it will see that the ProFile has MacWorks installed and it will boot Mac OS from it from that point. If you attempt to boot from the Profile directly, you'll get error #75.
Managing Multiple LisaEm Preferences files
Managing multiple preferences files The emulator allows you to manage multiple preferences files, each one representing a separate virtual Lisa. You can have a Lisa with the Lisa Office System, another with MacWorks, another with the Lisa Pascal Workshop and so on. You should save the current preferences with a descriptive name indicating what was installed on the Lisa. i.e. “Lisa Office System.lisaem”, “Lisa Pascal Workshop.lisaem”, or “MacWorks XL 3.0.
The LisaEm Menus
The File Menu: Open Preferences: Loads a preferences file Save Preferences As: Saves the current preferences to a new file. Preferences: Brings up the Preferences dialog. (Under LisaEm menu on OS X) Run: Equivalent to the Key menu Power item. Used to turn the virtual Lisa on or off. Pause: Pauses emulation Insert diskette: Inserts a DiskCopy 4.2 or DART image into the Lisa's floppy drive. DART images are converted to dc4.2.
The Key Menu: Power Button: Pushes the power key. Equivalent to the File Menu Run command, or clicking on the skin's power button. Apple + Power Button: Pushes the power key while the Apple key is down. This is useful while Lisa Office System is running as it will allow you to enter the Environments window so that you can reboot your Lisa without powering it off. Apple {key}: Sends the Apple-key combination. NMI Key: Sends a Non Maskable Interrupt key. This is used to enter LisaBug.
The Display Menu: Anti Aliased: This is the normal mode you should use with the Lisa Office System. This corrects the square pixel issues and uses anti-aliasing to fix most artifacts. Anti Aliased with Gray Replacement: As above, but attempts to replace the 50% desktop gray patterns with an actual gray color. The side effect is that some text will become fuzzy. Raw: Uncorrected square pixel display. Will show an incorrect aspect ratio. This is the right mode to use with MacWorks.
The Throttle Menu: The top part of this menu sets the throttle speed attempting to limit the emulator's CPU usage. Normaly at 5MHz. Slower machines will not be able to reach 32MHz. Even fast machines might not reach 32MHz depending on the CPU balancing options on the bottom part of the menu. The bottom part of the Throttle menu allows you to tell the emulator how much time to give to the emulated 68000 CPU versus time spent on drawing the display and other I/O.
The Help Menu: The help menu provides links to the LisaEm project webpage. Future versions may include a help browser. On OS X, the LisaEm menu contains the About LisaEm item which tells you what version of LisaEm you're running. On other operating systems, this option is under the Help menu. On some operating systems, this dialog box will also provide information about the License and the developers.
Glossary
Glossary: ADMP DART Disk Copy 4.2 Disk Image Dual Parallel Card Dual Parallel ROM expansion slots Generator I/O ROM ImageWriter Lisa Lisa Office System Lisa Pascal Workshop LisaEm Apple Dot Matrix Printer. Identical to the ImageWriter I printer, except that it connected on the Parallel Port instead of the serial port. Disk Archive and Transfer program. Like Disk Copy 4.2, this Macintosh program allows you to make disk images of floppies. Apple's Disk Copy 4.2 program for the Macintosh.
MacWorks microdiskette Parallel Port PRAM Profile ROM sector Serial Number Serial Port tags Widget Xenix MacWorks is a Lisa environment that allows Macintosh software to run Macintosh software. It's not quite an emulator, but rather, it's closer to something like virtualization software. Lisa speak for 3.5” floppy. The Lisa used 3.5” SS/DS 400K GCR encoded floppies, which are readble on older Macintosh computers.
Contact and Support Information
Contact and Support Information: http://lisaem.sunder.net This is the LisaEm project's official web site. Please visit this site every month to see if updated versions of the emulator are available. http://lisafaq.sunder.net The Lisa Frequently Asked Questions site provides information about the Lisa computer. It is not specific to the emulator, but can be helpful. lisafaq@sunder.net Please send comments about the LisaFAQ to this address. lisaem-bugs@sunder.net Please send bug reports to this address.
Credits
Credits: My thanks go out to the following people: David T. Craig for providing the wealth of Lisa information which he allowed me to scan in, for the many contacts with Lisa developers and faithfully listening to status reports over the ages.
