[ViewVC] Annotation of: cebix/BasiliskII/README


        Basilisk II, Version 0.7
        A free, portable Mac II emulator

        Copyright (C) 1997-1999 Christian Bauer et al.
        Freely distributable


License
-------

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


Overview
--------

Basilisk II is a free, portable, Open Source 68k Mac emulator. It requires
a copy of a Mac ROM and a copy of MacOS to run. Basilisk II is freeware and
distributed under the GNU General Public License.

Basilisk II has currently been ported to the following systems:
  - BeOS R4 (PowerPC and x86)
  - Unix (tested under Linux, Solaris 2.5, FreeBSD 3.x and IRIX 6.5)
  - AmigaOS 3.x
  - Windows NT 4.0 (mostly works under Windows 95/98, too)

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
  - Color video display
  - CD quality sound output
  - Floppy disk driver (only 1.44MB disks supported)
  - Driver for HFS partitions and hardfiles
  - CD-ROM driver with basic audio functions
  - Ethernet driver
  - Serial drivers
  - SCSI Manager (old-style) emulation
  - Emulates extended ADB keyboard and 3-button mouse
  - Uses UAE 68k emulation or (under AmigaOS) real 68k processor

The emulator is not yet complete. See the file "TODO" for a list of
unimplemented stuff.


Requirements and Installation
-----------------------------

Please consult the file "INSTALL" for a list of system requirements and
installation 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:

BeOS:
  /boot/home/config/settings/BasiliskII_prefs

Unix:
  ~/.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) as well as HFS partitions on hard disks etc. (but Basilisk
  II doesn't know about MacOS partition tables; it relies on the host OS to
  handle this). 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 starts with an asterisk ("*"), the volume is write
  protected for MacOS (and the "*" is discarded).

  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 volume, 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").

  AmigaOS:
    Partitions/drives are specified in the following format:
      /dev/<device name>/<unit>/<open flags>/<start block>/<size>/<block size>
    "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.

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 to
    the Generic SCSI driver API. On a standard Linux installation, these
    devices are "/dev/sg0", "/dev/sg1" etc. Note that you must have
    appropriate 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:
    Ignored. Basilisk II scans for all SCSI devices and the first 6 found
    devices are made visible to the MacOS. You cannot explicitly enable a
    device, but you can disable a device (see the "disablescsi" command).

screen <video mode>

  This item describes the type of video display to be used by 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 color 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
        colors 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>
        Color display in an X11 window of the given size. The color depth
        (8/15/24 bit) depends on the depth of the underlying X11 screen.
        This is the default.
      dga/<width>/<height>
        Full-screen display using the X11 DGA extensions. The color 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". For DGA to work, Basilisk II
        must be compiled with DGA support enabled (selectable in the configure
        script).

  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 truecolor 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 screen with the given
        mode ID. This requires Picasso96. 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,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).

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.

  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"). As Basilisk II requires the sheep_net
    net server add-on from SheepShaver, you can only use Ethernet on PowerPC
    machines.

  Linux:
    The "ethernet card description" is the name of an Ethernet interface.
    There are two approaches to networking with Basilisk II:
      1. Direct access to an Ethernet card via the "sheep_net" driver.
         In this case, the "ethernet card description" must be the name
         of a real Ethernet card, e.g. "eth0". It also requires the "sheep_net"
         driver to be installed and accessible. This approach 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 the ethertap device:
         under "Networking options", enable "Kernel/User netlink socket" and
         "Netlink device emulation", under "Network device support", activate
         "Ethertap network tap". 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.

  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.

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".

modelid <MacOS model ID>

  Specifies the 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".

For additional information, consult the source.


System-specific configuration
-----------------------------

Unix:

  keycodes <"true" or "false">
  keycodefile <Keycode 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/lib/basilisk_ii_keycodes
    unless you specify a different file with the "keycodefile" item.
    A sample keycode file ("basilisk_ii_keycodes") is included with
    Basilisk II.

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>

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.

  disablescsi <"Vendor"> <"Model">

    Disables this vendor/model combination. You may need this simply because
    you have more than 6 SCSI devices, or the particular device has problems
    under BasiliskII. E.g.

      disablescsi "HP" "CD-Writer+ 7100"
  
    Again, note the use of quotes.

  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.


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.

Floppy:
  Basilisk II can only handle 1.44MB MFM floppies. Depending on your platform,
  flopyy disk changes might not be detected automatically. Under Linux, 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 losses. 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.

Sound output:
  Sound output under Basilisk II requires Sound Manager 3.0 or later. This
  is included starting with MacOS 7.5 and available as a system extension
  for earlier MacOS versions. 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 your 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 "MacPPP".


Technical Documentation
-----------------------

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


Acknowledgements
----------------

Contributions by:
 - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
 - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
   and networking
 - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
 - Orlando Bassotto <future@powercube.mediabit.net>: FreeBSD support
 - Brian J. Johnson <bjohnson@sgi.com>: IRIX support
 - Marc Chabanas <Marc.Chabanas@france.sun.com>: Solaris sound support
 - Bill Huey <billh@mag.ucsd.edu>: 15/16 bit DGA and 15/16/32 bit X11
   window support
 - David Lawrence <davidl@jlab.org>: incremental window refresh code

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.


Author
------

You can contact me at <Christian.Bauer@uni-mainz.de>. Don't send bug
reports, send fixes. Ports to other platforms are also very welcome.
Please contact me before 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.

Questions about ROM files will not be answered. There is also no point in
sending me questions etc. that are specific to the Windows port of
Basilisk II. I don't have Windows and can't say anything about that.
Ask Lauri Pesonen instead.


Support
-------

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

There is no user-level support for Basilisk II at the moment.


History
-------

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


Christian Bauer
<Christian.Bauer@uni-mainz.de>
Revision:	1.4
Committed:	1999-10-03T20:40:05Z (25 years, 2 months ago) by cebix
Branch:	MAIN
Changes since 1.3:	+5 -3 lines
Log Message:	- updated documentation - building RPMs works now