Basilisk II

A 68k Macintosh emulator

Platform	CI Status
AmigaOS	Deprecate 💀
BeOS	Deprecate 💀
FreeBSD	Costs 💰
Linux
OSX	Null ⚠️
Windows

License

Basilisk II is available under the terms of the GNU General Public License. See the file "LICENSE" that is included in the distribution for details.

Overview

Basilisk II is an Open Source 68k Macintosh emulator. That is, it enables you to run 68k MacOS software on you computer, even if you are using a different operating system. However, you still need a copy of MacOS and a Macintosh ROM image to use Basilisk II.

Basilisk II has currently been ported to the following systems:

• BeOS R4 (PowerPC and x86)
• Unix (tested under Linux, Solaris 2.x, FreeBSD 3.x, NetBSD 1.4.x and IRIX 6.5)
• AmigaOS 3.x
• Windows NT 4.0 (mostly works under Windows 95/98 too)
• Mac OS X 10.1 thru 10.4

Some features of Basilisk II:

• Emulates either a Mac Classic (which runs MacOS 0.x thru 7.5) or a Mac II series machine (which runs MacOS 7.x, 8.0 and 8.1), depending on the ROM being used
• colour video display
• CD quality sound output
• Floppy disk driver (only 1.44 MB disks supported)
• Driver for HFS partitions and hardfiles
• CD-ROM driver with basic audio functions
• Easy file exchange with the host OS via a Host Directory Tree icon on the Mac desktop
• Ethernet driver
• Serial drivers
• SCSI Manager (old-style) emulation
• Emulates extended ADB keyboard and 3-button mouse
• Uses UAE 68k emulation or (under AmigaOS and NetBSD/m68k) real 68k processor

The emulator is not yet complete. See the GitHub issues for a list of unimplemented stuff: https://github.com/emaculation/BasiliskII/issues

Requirements and Installation

Please consult the file INSTALL.md for a list of system requirements and installation instructions.

Warning

All text below this line has not been updated in some time and may not reflect current URLs, contact information, markdown formatting, or instructions.

Configuration

Basilisk II is configured via the preferences editor that appears on startup. If you have a version without preferences editor (e.g. because of missing GTK+ under Unix), you have to edit the preferences file manually.

The settings are stored in a text file:

OS	File
BeOS	/boot/home/config/settings/BasiliskII_prefs
Unix, Mac OS X	~/.basilisk_ii_prefs
AmigaOS	ENV:BasiliskII_prefs
Windows	BasiliskII_prefs

(in the same directory as the executable)

If no preferences file is present, Basilisk II will create one with the default settings upon startup.

Preferences File Format

The preferences file is a text file editable with any text editor. Each line in this file has the format keyword value and describes one preferences item. For each keyword, the meaning of the value string may vary across platforms. The following keywords exist:

disk <volume description>

This item describes one MacOS volume to be mounted by Basilisk II. There can be multiple "disk" lines in the preferences file. Basilisk II can handle hardfiles (byte-per-byte images of HFS volumes in a file on the host system), HFS partitions on hard disks etc., and MacOS-partitioned disks (it can only access the first partition, though). The "volume description" is either the pathname of a hardfile or a platform-dependant description of an HFS partition or drive. If the volume description is prefixed by an asterisk (*), the volume is write protected for MacOS.

Basilisk II can also handle some types of Mac "disk image" files directly, as long as they are uncompressed and unencoded.

BeOS

To specify an HFS partition, simply specify its path (e.g. /dev/disk/scsi/0/1/0/0_3). If you don't specify any volumes, Basilisk II will search for and use all available HFS partitions.

Unix

To specify an HFS partition, simply specify its path (e.g. /dev/sda5). If you want to access a MacOS-partitioned hard disk or removable volume (Jaz, Zip etc.) and your operating system doesn't understand MacOS partition tables, you can specify the block device name (e.g. /dev/sda) to access the first HFS partition on the device. Under Linux, if you don't specify any volumes, Basilisk II will search /etc/fstab for unmounted HFS partitions and use these.

AmigaOS

Partitions/drives are specified in the following format: /dev/<device name>/<unit>/<open flags>/<start block>/<size>/<block size> where "start block" and "size" are given in blocks, "block size" is given in bytes.

Windows

To define a logical volume (Windows NT only), specify its path (e.g. c:\). To define a physical volume (NT and 9x), additionally give the physical keyword (e.g. physical c:\). For safety reasons, volumes are mounted as read-only. This is due to the bugs in PC Exchange. If you don't specify any volume, the files *.hfv and *.dsk are searched from the current directory. Note that in this case, Basilisk II tries to boot from the first volume file found, which is random and may not be what you want.

floppy <floppy drive description>

This item describes one floppy drive to be used by Basilisk II. There can be multiple floppy lines in the preferences file. If no floppy line is given, Basilisk II will try to automatically detect and use installed floppy drives. The format of the "floppy drive description" is the same as that of "disk" lines.

cdrom <CD-ROM drive description>

This item describes one CD-ROM drive to be used by Basilisk II. There can be multiple cdrom lines in the preferences file. If no cdrom line is given, Basilisk II will try to automatically detect and use installed CD-ROM drives. The format of the "CD-ROM drive description" is the same as that of disk lines.

extfs <direcory path>

This item specifies the root directory for the "Host Directory Tree" file system (the Unix/BeOS/Amiga/... icon on the Finder desktop). All objects contained in that directory are accessible by Mac applications.

This feature is only available when File System Manager V1.2 or later is installed on the Mac side. FSM 1.2 is built-in beginning with MacOS 7.6 and can be installed as a system extension (downloadable from Apple, look for the FSM SDK in the developer section) for earlier MacOS versions.

scsi0 <SCSI target> ... scsi6 <SCSI target>

These items describe the SCSI target to be used for a given Mac SCSI ID by Basilisk II. Basilisk II emulates the old SCSI Manager and allows to assign a different SCSI target (they don't even have to be on the same SCSI bus) for each SCSI ID (0..6) as seen by the MacOS. scsi0 describes the target for ID 0, scsi1 the target for ID 1, etc. The format of the SCSI target is platform specific.

BeOS

The SCSI target has the format <bus>/<unit> (e.g. 0/2). Due to a bug in BeOS, using SCSI with Basilisk II may cause the SCSI bus to hang. Use with caution.

Linux

The SCSI target has to be the name of a device that complies tothe Generic SCSI driver API. On a standard Linux installation, thesedevices are /dev/sg0, /dev/sg1, etc. Note that you must haveappropriate access rights to these devices and that Generic SCSI support has to be compiled into the kernel.

FreeBSD

The SCSI target has the format <id>/<lun> (e.g. 2/0).

AmigaOS

The SCSI target has the format <device name>/<unit> (e.g. scsi.device/2).

Windows

The SCSI target has the format <"Vendor"> <"Model"> (e.g. scsi0 "HP" "CD-Writer+ 7100"). Note the use of quotes.

screen <video mode>

This item describes the type of video display to be used by default for Basilisk II. If you are using a Mac Classic ROM, the display is always 1-bit 512x342 and this item is ignored. The format of the video mode is platform specific.

BeOS

The video mode is one of the following:

• win/<width>/<height> 8-bit colour display in a window of the given size. This is the default.
• scr/<mode> Full-screen display in BWindowScreen. <mode> is the bit number of the video mode to use (see headers/be/interface/GraphicsDefs.h). E.g. 0 = 640x480x8, 1 = 800x600x8, etc., 10 = 640x480x24, 11 = 800x600x24, etc., 18 = 640x480x15, 19 = 800x600x15, etc. 15-bit modes are preferable to 16-bit modes (which may show false colours on PowerPC machines). When you run in full-screen mode and switch to another Workspace, Basilisk II is put in "suspend" mode (i.e. MacOS will be frozen).

Unix

The video mode is one of the following:

• win/<width>/<height> colour display in an X11 window of the given size. There are several resolutions and colour depths available. The set of colour depths depends on the capabilities of the X11 server, the operating system, and Basilisk II compile-time options, but 1 bit and the default depth of the X11 screen should always be available.
• dga/<width>/<height> [if Basilisk II was configured with --enable-xf86-dga] Full-screen display using the XFree86 DGA extension. The colour depth (8/15/24 bit) depends on the depth of the underlying X11 screen. "width" and "height" specify the maximum width/height to use. Saying "dga/0/0" means "complete screen".
• dga/<frame buffer name> [if Basilisk II was configured with --enable-fbdev-dga] Full-screen display using the frame buffer device /dev/fb. The colour depth (8/15/24 bit) depends on the depth of the underlying X11 screen. The "frame buffer name" is looked up in the "fbdevices" file (whose path can be specified with the "fbdevicefile" prefs item) to determine certain characteristics of the device (doing a ls -l /dev/fb should tell you what your frame buffer name is).

AmigaOS

The video mode is one of the following:

• win/<width>/<height> Black-and-white display in a window of the given size on the Workbench screen. This is the default and will also be used when one of the other options (PIP/screen) fails to open.
• pip/<width>/<height> 15-bit truecolour display in a Picasso96 PIP. This requires Picasso96 as well as a PIP-capable graphics card (e.g. Picasso IV).
• scr/<hexadecimal mode ID> 8/15/24-bit fullscreen display on a Picasso96/CyberGraphX screen with the given mode ID. This requires Picasso96 or CyberGraphX. For 15 and 24 bit, the frame buffer format must be QuickDraw-compatible (big-endian, xRGB 1:5:5:5 or xRGB 8:8:8:8). The screen size will be the default size for that mode ID.

Windows

The video mode is one of the following:

• win/<width>/<height>/<bits per pixel> A refreshed screen mode that uses Windows GDI calls to write to the screen. You may have other windows on top of Basilisk II.
• dx/<width>/<height>/<bits per pixel> A refreshed DirectX mode (minimum version 5.0). There are ways to install DirectX 5 on NT 4. Some new display adapters work fine even with DirectX 3.
• fb/<width>/<height>/<bits per pixel> A non-refreshed video mode that works only on NT. It accesses the linear frame buffer directly (best performance of all three modes). Use the hotkey Control-Shift-F12 to switch between Windows and Mac displays. Fast task switch (Alt-Tab) and Explorer start menu (Control-Esc) are disabled, Control-Alt-Del is enabled.

<width> and <height> can be either zeroes (uses current screen values), or something else. "win" mode can use almost anything, for other modes there must be a corresponding DirectX mode.

<bits> is ignored for mode "win" (uses current screen values).

If the mode is "win" and the dimensions are different than the desktop dimensions, windowed mode is used. The window can be moved around by dragging with the right mouse button. This mode remembers window positions separately for different dimensions.

The supported values are 8, 15, 16, 24 and 32. It is possible that some of them do not work for you. In particular, it may be that only one of the two modes, 15 and 16, is suitable for your card. You need to find out the best solution by experimenting.

Basilisk II checks what display mode you are currently running and uses that mode. The screen is always full screen. When you switch to another application via Alt-Tab, Basilisk II is put in "snooze" mode (i.e. MacOS is frozen).

Mac OS X

The video mode is one of the following:

• win/<width>/<height>
• win/<width>/<height>/<bits per pixel> A refreshed (and buffered) Quartz window.
• full/<width>/<height>
• full/<width>/<height>/<bits per pixel> A CGDirectDisplay full screen mode. <bits> can currently be 8, 16 or 32. If not specified, the default is 32. There is currently no way to switch between the Mac OS X and Basilisk II display, but Apple-Option-Escape instantly and safely terminates the Basilisk II program.

seriala <serial port description>

This item describes the serial port to be used as Port A (Modem Port) by Basilisk II. If no seriala line is given, Basilisk II will try to automatically detect and use installed serial ports. The "serial port description" is a platform-dependant description of a serial port.

BeOS

Either specify the name of a serial port (e.g. serial1) or one of parallel1, parallel2 or parallel3. See below for more information about parallel ports.

Unix

Specify the device name of a serial port (e.g. /dev/ttyS0) or a parallel lp port (e.g. /dev/lp1; this only works under Linux and FreeBSD). See below for more information about parallel ports.

AmigaOS

You have to specify the name of the serial device and the device unit as <device name>/<unit> (e.g. serial.device/0). If the given device is not compatible to serial.device, Basilisk II will crash. If the device name starts with an asterisk (e.g. *parallel.device/0), the device is treated as a parallel.device compatible device. See below for more information about parallel ports.

Windows

Specify COM1 or COM2 for com port 1 or 2, respectively.

Parallel ports: If you select a parallel port it will look like a serial port to MacOS but Basilisk II will only allow data output and ignore baud rate settings etc. You should be able to get some printers to work with this method (provided that you have the right printer driver, like "Power Print" (see www.gdt.com).

serialb <serial port description>

This item describes the serial port to be used as Port B (Printer Port) by Basilisk II. If no serialb line is given, Basilisk II will try to automatically detect and use installed serial ports. The format of the "serial port description" is the same as that of the seriala option.

ether <ethernet card description>

This item describes the Ethernet card to be used for Ethernet networking by Basilisk II. If no "ether" line is given, Ethernet networking is disabled (although the Ethernet driver of Basilisk II will behave like a "dummy" Ethernet card in this case). If you are using a Mac Classic ROM, Ethernet is not available and this setting is ignored. The "ethernet card description" is a platform-dependant description of an ethernet card.

General note: To use TCP/IP from MacOS, you should assign a different IP address to the MacOS (entered into the MacOS TCP/IP (or MacTCP) control panel). Otherwise there will be confusion about which operating system will handle incoming packets.

BeOS

It doesn't matter what you give as "ethernet card description", Basilisk II will always use the first Ethernet card it finds as long an an "ether" line exists (e.g. say ether yes). Using Ethernet requires the sheep_net Net Server add-on to be installed. The first time you start Basilisk II with Ethernet enabled you will be asked whether it's OK to make the necessary changes to your BeOS network configuration to enable sheep_net.

Linux

The "ethernet card description" is the name of an Ethernet interface. There are four approaches to networking with Basilisk II:

1. Direct access to an Ethernet card via the sheep_net kernel module. The "ethernet card description" must be the name of a real Ethernet card, e.g. eth0. The sheep_net module is included in the Basilisk II source distribution in the directory src/Unix/Linux/NetDriver. You have to compile and install the module yourself:

   $ su
   [enter root password]
   # make
   # make dev
   [this will create a `/dev/sheep_net` device node; you should give appropriate access rights to the user(s) running Basilisk II]
   # insmod sheep_net.o

   • If you copy the sheep_net.o module to a place where it can be found by the kernel module loader (/lib/modules/<version>/kernel/drivers/net for 2.4 kernels) and add the line alias char-major-10-198 sheep_net to /etc/modules.conf, the kernel should be able to load the module automatically when Basilisk II is started.

   • The sheep_net module will allow you to run all networking protocols under MacOS (TCP/IP, AppleTalk, IPX etc.) but there is no connection between Linux networking and MacOS networking. MacOS will only be able to talk to other machines on the Ethernet, but not to other networks that your Linux box routes (e.g. a second Ethernet or a PPP connection to the Internet).

2. Putting Basilisk II on a virtual Ethernet via the ethertap device.

   • In this case, the "ethernet card description" must be the name of an ethertap interface, e.g. tap0. It also requires that you configure your kernel to enable routing and ethertap support: under "Networking options", enable "Kernel/User netlink socket" and "Netlink device emulation", under "Network device support", activate "Ethertap network tap". You also have to modify drivers/net/ethertap.c a bit before compiling the new kernel:

     • insert #define CONFIG_ETHERTAP_MC 1 near the top (after the #include lines)
     • comment out the line dev->flags|=IFF_NOARP; in ethertap_probe()

   • Next, see /usr/src/linux/Documentation/networking/ethertap.txt for information on how to set up /dev/tap* device nodes and activate the ethertap interface. Under MacOS, select an IP address that is on the virtual network and set the default gateway to the IP address of the ethertap interface. This approach will let you access all networks that your Linux box has access to (especially, if your Linux box has a dial-up Internet connection and is configured for IP masquerading, you can access the Internet from MacOS). The drawback is that you can only use network protocols that Linux can route, so you have to install and configure netatalk if you want to use AppleTalk. Here is an example /etc/atalk/atalkd.conf for a LAN:

     eth0 -seed -phase 2 -net 1 -addr 1.47 -zone "Ethernet"
     tap0 -seed -phase 2 -net 2 -addr 2.47 -zone "Basilisknet"
     

   • (the 47 is an arbitrary node number). This will set up a zone Ethernet (net 1) for the Ethernet and a zone Basilisknet (net 2) for the internal network connection of the ethertap interface. MacOS should automatically recognise the nets and zones upon startup. If you are in an existing AppleTalk network, you should contact your network administrator about the nets and zones you can use (instead of the ones given in the example above).

3. Access the network through a tuntap interface. The "ethernet card description" must be set to tun.

   • TUN/TAP provides packet reception and transmission for user space programs. It can be viewed as a simple Point-to-Point or Ethernet device, which instead of receiving packets from a physical media, receives them from user space program and instead of sending packets via physical media writes them to the user space program.

   • Prerequisites:

   • Make sure the "tun" kernel module is loaded # modprobe tun

   • If you wish to route IP packets from Basilisk II, make sure IP Forwarding is enabled on your system (not required for bridging) # echo 1 >/proc/sys/net/ipv4/ip_forward

   • A virtual network configuration script is required in order to configure the tunN interface after it is created, and the default is /usr/local/BasiliskII/tunconfig unless you specify a different file with the "etherconfig" item.

   • The default "tunconfig" script configures the tunN interface for IP NAT. It requires that sudo is properly configured so that /sbin/ifconfig and /sbin/iptables can be executed as root. Otherwise, you can still write a helper script which invokes your favourite program to elevate user privileges. e.g. in a KDE environment, kdesu can be used as follows:

     #!/bin/sh
     exec /usr/bin/kdesu -c /path/to/tunconfig $1 $2

   • As an alternative to configuring IP on the tunN interface, you may attach it to a bridge, which will enable AppleTalk frames to be forwarded without Linux needing to route them. No tunconfig-like script is provided to configure bridging, but you may simply configure etherconfig /bin/true to skip the automatic configuration and then configure bridging manually once Basilisk II has started, e.g.:

     # ifconfig tun0 up
     # brctl addif bridge1 tun0

4. Access the network through the user mode network stack. (the code and this documentation come from QEMU)

   • By setting the "ethernet card description" to "slirp", Basilisk II uses a completely user mode network stack (you don't need root privileges to use the virtual network). The virtual network configuration is the following:

     Basilisk II <------> Firewall/DHCP server <-----> Internet
     (10.0.2.x)      |         (10.0.2.2)
                     |
                     ----> DNS server (10.0.2.3)
                     |
                     ----> SMB server (10.0.2.4)
     

   • Basilisk II behaves as if it was behind a firewall which blocks all incoming connections. You can use a DHCP client to automatically configure the network in Basilisk II.

   • In order to check that the user mode network is working, you can ping the address 10.0.2.2 and verify that you got an address in the range 10.0.2.x from the Basilisk II virtual DHCP server.

   • Note that ping is not supported reliably to the internet as it would require root privileges. It means you can only ping the local router (10.0.2.2).

   • When using the built-in TFTP server, the router is also the TFTP server.

FreeBSD

The "ethertap" method described above also works under FreeBSD, but since no-one has found the time to write a section for this manual, you're on your own here...

AmigaOS

You have to specify the name of the SANA-II Ethernet device and the device unit as <device name>/<unit> (e.g. ariadne.device/0). If the given device is not a SANA-II device, Basilisk II will crash. If the device is not an Ethernet device, Basilisk II will display a warning message and disable Ethernet networking.

Mac OS X

The "slirp" method described above now seems to work.

See the next item for an alternative way to do networking with Basilisk II.

udptunnel <"true" or "false">

Setting this to true enables a special network mode in which all network packets sent by MacOS are tunnelled over UDP using the host operating system's native TCP/IP stack. This can only be used to connect computers running Basilisk II (and not, for example, for connecting to the Internet or an AppleShare server running on a real Mac), but it is probably the easiest way to set up a network between two instances of Basilisk II because the UDP tunnelling doesn't require any special kernel modules or network add-ons. It relies on IP broadcasting, however, so its range is limited. It should be fine though for doing a little file sharing or playing Spectre.

udpport <IP port number>

This item specifies the IP port number to use for the "UDP Tunnel" mode. The default is 6066.

redir <port redirection description>

This item defines a port to be forwarded from the host to the client. The format is [protocol]:hostport:[clientaddress]:clientport, where protocol is udp or tcp (default), hostport is the port on your computer to forward to the Mac, clientaddress is the IP address of the Mac in the virtual network (defaults to 10.0.2.15), and clientport is the port on the Mac to be exposed. For example, if you have a web server in MacOS running on port 80, you can expose it as port 8000 with the line below:

redir tcp:8000:10.0.2.15:80

rom <ROM file path>

This item specifies the file name of the Mac ROM file to be used by Basilisk II. If no rom line is given, the ROM file has to be named "ROM" and put in the same directory as the Basilisk II executable.

bootdrive <drive number>

Specify MacOS drive number of boot volume. 0 (the default) means "boot from first bootable volume".

bootdriver <driver number>

Specify MacOS driver number of boot volume. 0 (the default) means "boot from first bootable volume". Use -62 to boot from CD-ROM.

ramsize <bytes>

Allocate "bytes" bytes of RAM for MacOS system and application memory. The value given will be rounded down to the nearest multiple of 1MB. If you are using a Mac Classic ROM, the maximum available value is 4MB and higher values will be ignored. The default is 8MB.

frameskip <frames to skip>

For refreshed graphics modes (usually window modes), this specifies how many frames to skip after drawing one frame. Higher values make the video display more responsive but require more processing power. The default is 8. Under Unix/X11, a value of 0 selects a "dynamic" update mode that cuts the display into rectangles and updates each rectangle individually, depending on display changes.

modelid <MacOS model ID>

Specifies the Macintosh model ID that Basilisk II should report to MacOS. The default is 5 which corresponds to a Mac IIci. If you want to run MacOS 8, you have to set this to 14 (Quadra 900). Other values are not officially supported and may result in crashes. MacOS versions earlier than 7.5 may only run with the Model ID set to 5. If you are using a Mac Classic ROM, the model is always "Mac Classic" and this setting is ignored.

nosound <"true" or "false">

Set this to true to disable all sound output. This is useful if the sound takes too much CPU time on your machine or to get rid of warning messages if Basilisk II can't use your audio hardware.

nocdrom <"true" or "false">

Set this to true to disable Basilisk's built-in CD-ROM driver. The only reason to do this is if you want to use a third-party CD-ROM driver that uses the SCSI Manager. The default is false.

nogui <"true" or "false">

Set this to true to disable the GUI preferences editor and GUI error alerts. All errors will then be reported to stdout. The default is false.

keyboardtype <keyboard-id>

Specifies the keyboard type that Basilisk II should report to the MacOS. The default is 5 which is a "Apple Extended Keyboard II (ISO)", but many other numbers are understood by most versions of the MacOS (e.g. 11 is a "Macintosh Plus Keyboard with keypad", 13 is a "Apple PowerBook Keyboard (ISO)").

For additional information, consult the source.

System-specific configuration

Unix

keycodes <"true" or "false"><br>keycodefile <keycodes file path>

By default, the X11 event handler in Basilisk II uses KeySyms to translate keyboard event to Mac keycodes. While this method is very compatible and ought to work with all X servers, it only works well if your keyboard has a US layout. If you set keycodes to true, Basilisk II will use raw keycodes instead of KeySyms. The keycode depends only on the physical location of a key on the keyboard and not on the selected keymap. Unfortunately it depends on the X server being used and possibly also on the type of keyboard attached. So Basilisk II needs a table to translate X keycodes to Mac keycodes. This table is read by default from /usr/local/share/BasiliskII/keycodes unless you specify a different file with the keycodefile item. A sample keycode file is included with Basilisk II.

fbdevicefile <fbdevices file path>

This option specifies the file that contains frame buffer device specifications for the fbdev-DGA video mode (when Basilisk II was configured with --enable-fbdev-dga). The default location of the file is /usr/local/share/BasiliskII/fbdevices. A sample file is included with Basilisk II.

mousewheelmode <mode>

If you have a mouse with a wheel, this option specifies whether moving the wheel will be reported to the MacOS as Page up/down (mode 0) or Cursor up/down (mode 1) keys.

mousewheellines <number of lines>

If mousewheelmode is set to mode 1 (Cursor up/down), this option sets the number of key events sent to MacOS for each wheel movement (the number of lines to scroll).

ignoresegv <"true" or "false">

Set this to true to ignore illegal memory accesses. The default is false This feature is only implemented on the following platforms: Linux/x86, Linux/ppc, Darwin/ppc.

dsp <device name><br>mixer <device name>

Under Linux and FreeBSD, this specifies the devices to be used for sound output and volume control, respectively. The defaults are /dev/dsp and /dev/mixer.

AmigaOS

sound <sound output description>

This item specifies what method to use for sound output. The only choice is currently AHI, but you can specify the AHI mode ID to be used. The "sound output description" looks like this:

ahi/<hexadecimal mode ID>

scsimemtype <type>

This item controls the type of memory to use for SCSI buffers. Possible values are:

Value	Definition
0	Chip memory
1	24-bit DMA capable memory
2	Any memory

Be warned that many SCSI host adapters will not work with the "Any memory" setting. Basilisk II has no way of knowing which memory type is supported by the host adapter and setting an unsupported type will result in data corruption.

Windows

noscsi <"true" or "false">

Completely disables SCSI Manager support when set to true. Note that currently all SCSI operations are executed synchronously, even if Mac application has requested asynchronous operation. What this means is that the control is not returned to the application until the command is completely finished. Normally this is not an issue, but when a CDR/CDRW is closed or erased the burner program typically wants to wait in some progress dialog the result may be that the application reports a time-out error, but the operation completes all right anyway.

nofloppyboot <"true" or "false">

Set this to true to disable booting from a floppy.

replacescsi <"Vendor1"> <"Model1"> <"Vendor2"> <"Model2">

This command tricks the Mac to believe that you have a SCSI device Model2 from vendor Vendor2, although your real hardware is Model1 from Vendor1. This is very useful since many devices have almost identical ATAPI and SCSI versions of their hardware, and MacOS applications usually support the SCSI version only. The example below is typical:

replacescsi "HP" "CD-Writer+ 7100" "PHILIPS" "CDD3600"

Note the use of quotes.

rightmouse <0/1>

Defines what the right mouse button is used for. The default values of 0 means that it is used to move windowed mode BasiliskII screen. Value 1 sends a combination Control and mouse click to the MacOS. This may be useful under OS versions 8 and above.

keyboardfile <path>

Defines the path of the customized keyboard code file.

pollmedia <"true" or "false">

If true (default), tries to automatically detect new media. Applies to all "floppy", "cd" or "disk" removable media except 1.44 MB floppies. May cause modest slow down. If unchecked, use Ctrl-Shift-F11 to manually mount new media. If you have auto-insert notification (AIN) enabled, you may turn this option off. Note that some CD related software require AIN, and some other need it to be turned off. Consult the documentation of your CD software to learn which one is optimal for you.

framesleepticks <milliseconds>

The amount of time between video frames.

showfps <true/false>

If true, the real frame rate is displayed.

stickymenu <true/false>

If true, the main menu bar is kept open even after the mouse button is released, under all OS versions (OS 8 has this feature already). There are extensions to do the same thing, but it's faster to handle this in native code. Default is true.

ntdx5hack <"true" or "false">

You may need this on NT if your display adapter driver has a bug in DirectX palette support. Black and white are reversed. It fixes the palette issue by using GDI palette instead of D3D palette. Default is false.

JIT-specific configuration

A Just-In-Time (JIT) translation engine is available for x86. This is aimed at translating 68040 instructions to native equivalent code sequences, thus providing faster emulation speeds.

jit <"true" or "false">

Set this to true to enable the JIT compiler. Default value is true if the JIT compiler was compiled in. Besides, this is effective only if Basilisk II is configured to emulate a 68040.

jitfpu <"true" or "false">

Set this to true to enable translation of floating-point (FPU) instructions. Default is true.

jitcachesize <size>

Allocate size kilobytes of RAM for the translation cache. The value given will be rounded down to the nearest multiple of a page size. Minimal value is 2048 (2MB). Default value is 8192 (8MB).

jitlazyflush <"true" or "false">

Set this to true to enable lazy invalidation of the translation cache. This is always recommended as it usually makes the system more responsive and faster, especially while running MacOS 8.X. Default value is true.

jitdebug <"true" or "false">

Set this to true to enable the JIT debugger. This requires a build of Basilisk II with the cxmon debugger. Default is false.

Usage

Quitting

The right way to quit Basilisk II is to select the Shut Down menu item from the Finder's Special menu. You should not kill it from the shell unless it hangs. Under Unix, pressing Esc while holding the Ctrl key will also quit Basilisk II (in case you are using it in DGA mode and it crashed). Under Windows, try Alt-F4 (or Control-Alt-Del to log off and back on again if it crashes really badly).

Suspending

The Unix version of Basilisk II can be suspended while running in DGA mode by pressing Tab while holding the Ctrl key. Pressing Space in the "suspended" window will resume the emulation. Under BeOS, switching to a different Workspace when BasiliskII is in full-screen mode will also suspend the emulation.

Keyboard

On PC-style keyboards, Alt is the Mac Command key, while the Windows key is the Mac Option key.

Mouse

Under Unix, pressing Ctrl-F5 while the Basilisk II window is active will grab the mouse. This is needed for compatibility with some MacOS programs, especially games such as flight simulators. Press Ctrl-F5 again to return to normal mouse operation.

Floppy

Basilisk II can only handle 1.44 MB MFM floppies. Depending on your platform, floppy disk changes might not be detected automatically. Under Unix, press Ctrl-F1 to mount a floppy. Under BeOS, select the appropriate Mount menu item or press Ctrl-F1 to mount a floppy. Under Windows, press Ctrl-Shift-F11.

HFS partitions

Having HFS partitions mounted for read-write access under Basilisk II while they are also mounted on the host OS will most likely result in volume corruption and data loss. Unmount your HFS volumes before starting Basilisk II.

ZIP drives

Iomega ZIP disks can be mounted either with the "disk" prefs item or (on platforms that support the SCSI Manager emulation of Basilisk II) by installing the IomegaWare on the Mac side. Do not use both ways simultaneously!

Hardfiles

In addition to plain images of HFS volumes, Basilisk II can also handle some types of Mac "disk image" files, as long as they are uncompressed and unencoded.

Mac Classic emulation

Sound output and Ethernet are not supported if you are using a Mac Classic ROM. Also, the video display is fixed to 512x342 in monochrome. The AmigaOS and BeOS/PPC versions of Basilisk II cannot do Mac Classic emulation.

Video resolution switching

Run-time switching of video resolutions requires the Display Manager. This is included in MacOS versions 7.6 and above, and available as a system extension for earlier MacOS versions as a free download from ftp.apple.com (look for "Display Software 2.x"). Click on Options... in the Monitors control panel to select the resolution.

Sound output

Sound output under Basilisk II requires Sound Manager 3.0 or later. This is included in MacOS versions 7.5 and above, and available as a system extension for earlier MacOS versions as a free download from ftp.apple.com. Sample rate, bit resolution and mono/stereo can be selected in the Sound control panel (section Sound Out).

Ethernet

Basilisk II supports all Ethernet protocols. Running a protocol under Basilisk II that already runs within the host operating system on the same network card (e.g. running MacTCP under Basilisk II on a BeOS machine) may or may not work (generally, it should work, but some specific things like "ping" may not). If you have problems with FTP, try setting the FTP client to passive mode.

LocalTalk

LocalTalk is not supported by Basilisk II. There is no way of getting LocalTalk to work with the serial drivers of Basilisk II. Any attempt to activate LocalTalk will either result in a crash or revert to Ethernet.

Serial

You can use the serial ports in Basilisk II to connect to the Internet with a modem and the "MacPPP" or "Open Transport/PPP" software.

Technical Documentation

Please see the included file "TECH" for a technical overview of the emulator.

Acknowledgements

Contributions by (in alphabetical order):

• Orlando Bassotto future@powercube.mediabit.net: FreeBSD support
• Gwenolé Beauchesne gb@dial.oleane.com: SPARC assembly optimizations, lots of work on the Unix video code, fixes and improvements to the JIT compiler
• Marc Chabanas Marc.Chabanas@france.sun.com: Solaris sound support
• Marc Hellwig Marc.Hellwig@uni-mainz.de: audio output, BeOS video code and networking
• Bill Huey billh@mag.ucsd.edu: 15/16 bit DGA and 15/16/32 bit X11 window support
• Brian J. Johnson bjohnson@sgi.com: IRIX support
• Jürgen Lachmann juergen_lachmann@t-online.de: AmigaOS CyberGraphX support
• Samuel Lander blair_sp@hotmail.com: tile-based window refresh code
• David Lawrence davidl@jlab.org: incremental window refresh code
• Bernie Meyer bmeyer@csse.monash.edu.au: original UAE-JIT code
• Nigel Pearson nigel@ind.tansu.com.au: Mac OS X port
• Lauri Pesonen lpesonen@nic.fi: Windows NT port
• Bernd Schmidt crux@pool.informatik.rwth-aachen.de: UAE 68k emulation
• Michael Z. Sliczniak msliczniak@comcast.net: Mach memory fault recovery
• and others...

Special thanks to:

• Bernd Schmidt for letting me use his UAE 68k emulation
• Daniel Bobbert who printed dozens of pages from the THINK Reference for me years ago
• All ShapeShifter and SheepShaver users and beta testers
• Apple Computer Inc., who made writing a Macintosh emulator a child's play

Bug reports

You found a bug? Well, use the source, fix it and send the fix to Christian.Bauer@uni-mainz.de> for inclusion in the next release of Basilisk II.

If you don't have a fix, you should post a bug report using the Source Forge bug tracker, supplying as much information as possible (operating system and versions of Basilisk II and MacOS being used, relevant hardware information, the exact steps to reproduce the bug, etc.): http://sourceforge.net/tracker/?group_id=2123&atid=102123

I also strongly suggest reading this before posting a bug report: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

Author

You can contact me at Christian.Bauer@uni-mainz.de, but please don't do so unless absolutely necessary. I'm maintaining Basilisk II in my spare time and am not able to provide technical support for everyone. If you have questions, consider posting them to one of the support forums mentioned below.

You are encouraged to contact me personally when

• you have bug fixes or small enhancements for the code
• you want to port Basilisk II to another platform
• you want to discuss technical issues
• you intend to make major changes to the source; you might be working on something that I have already done, or I may have different ideas about the Right Way to do it

There is no point in sending me questions about

• ROM files and how/where to get them
• versions of Basilisk II that run on operating systems other than Unix, BeOS and AmigaOS. If you are using any other operating system, there's no point in asking me how to to X or why Y doesn't work because I won't know either. Instead, you should look in the "Acknowledgements" section of this manual to find the person responsible. For example, if your question is specific to the Windows operating system, ask Lauri Pesonen. I don't have Windows and can't answer your questions and I'm too lazy to forward mail to Lauri myself. In any case, it would probably be better to post your questions to a public forum as it will get a much wider audience there.

Support

The official Basilisk II home page is at http://www.uni-mainz.de/~bauec002/B2Main.html

The Basilisk II project page on SourceForge is at http://sourceforge.net/projects/basilisk/

If you have problems, you may want to visit the Basilisk II forums: http://sourceforge.net/forum/?group_id=2123

There is also a mailing list for Basilisk II users: http://lists.sourceforge.net/lists/listinfo/basilisk-user

And another mailing list for Basilisk II developers: http://lists.sourceforge.net/lists/listinfo/basilisk-devel

Some general advice about asking technical support questions can be found at http://www.catb.org/~esr/faqs/smart-questions.html

Keeping this in mind will greatly increase your chances of getting a useful answer.

History

Please consult the file "ChangeLog" for the release history.

Christian Bauer Christian.Bauer@uni-mainz.de