home *** CD-ROM | disk | FTP | other *** search
/ PC World 1999 June / PCWorld_1999-06_cd.bin / software / temacd / basilisk / README < prev    next >
Text File  |  1999-04-15  |  15KB  |  418 lines
  1.  
  2.     Basilisk II, Version 0.4
  3.     A free, portable Mac II emulator
  4.  
  5.     Copyright (C) 1997-1999 Christian Bauer et al.
  6.     Freely distributable
  7.  
  8.  
  9. License
  10. -------
  11.  
  12. Basilisk II is available under the terms of the GNU General Public License.
  13. See the file "COPYING" that is included in this archive for details.
  14.  
  15.  
  16. Overview
  17. --------
  18.  
  19. Basilisk II is an attempt at creating a free, portable 68k Mac emulator.
  20. It requires a copy of a 512K or 1MB Mac ROM and a copy of MacOS 7.x or
  21. 8.x to run. Basilisk II is freeware and distributed under the GNU General
  22. Public License.
  23.  
  24. Basilisk II has currently been ported to the following systems:
  25.   - BeOS R4 (PowerPC and x86)
  26.   - Unix (tested under Linux)
  27.   - AmigaOS 3.x
  28.  
  29. Some features of Basilisk II:
  30.   - Runs MacOS 7.x and 8.x (7.0 not recommended)
  31.   - Color video
  32.   - Floppy disk driver (only 1.44MB disks supported)
  33.   - Driver for HFS partitions and hardfiles
  34.   - CD-ROM driver with basic audio functions
  35.   - Ethernet driver
  36.   - Serial drivers
  37.   - SCSI Manager (old-style) emulation
  38.   - Emulates extended ADB keyboard and 3-button mouse
  39.   - Uses UAE 68k emulation or (under AmigaOS) real 68k processor
  40.  
  41. The emulator is far from being complete. See the file "TODO" for a list
  42. of unimplemented stuff.
  43.  
  44.  
  45. Installation
  46. ------------
  47.  
  48. BeOS:
  49.   The archive contains a precompiled BeOS binary (unless it's a "src"
  50.   archive). On a PowerPC system you also need the "sheep" driver that
  51.   comes with SheepShaver. To use Ethernet, you need the "sheep_net"
  52.   add-on that also comes with SheepShaver (both items are included
  53.   in the SheepShaver Trial Versions). Basilisk II cannot run concurrently
  54.   with SheepShaver. Trying to do so will crash Basilisk II, or SheepShaver,
  55.   or both.
  56.  
  57. Unix:
  58.   You need X11R6. To compile, cd to "src/Unix", and type "./configure"
  59.   followed by "make".
  60.  
  61. AmigaOS:
  62.   The archive contains a precompiled AmigaOS binary (unless it's a "src"
  63.   archive). You need at least a 68020 and AmigaOS 3.0. You must also have
  64.   the "PrepareEmul" utility installed that comes with ShapeShifter (or any
  65.   equivalent PrepareEmul substitute, see the ShapeShifter docs).
  66.  
  67. Basilisk II needs a 512K or 1MB 32-bit clean Macintosh ROM image. For
  68. copyright reasons this is not included in the archive. No, I don't know
  69. where you can download it. No, I won't send you one. The ROM file has to
  70. be named "ROM" and put in the same directory as the Basilisk II executable
  71. but you can specify a different location for the ROM file with the "rom"
  72. option in the preferences file.
  73.  
  74.  
  75. Configuration
  76. -------------
  77.  
  78. Basilisk II is configured via a text file.
  79.  
  80. BeOS:
  81.   /boot/home/config/settings/BasiliskII_prefs
  82.  
  83. Unix:
  84.   ~/.basilisk_ii_prefs
  85.  
  86. AmigaOS:
  87.   ENV:BasiliskII_prefs
  88.  
  89. If no preferences file is present, Basilisk II will create one with the
  90. default settings upon startup.
  91.  
  92. The preferences file is a text file editable with any text editor.
  93. Each line in this file has the format "keyword value" and describes
  94. one preferences item. For each keyword, the meaning of the "value"
  95. string may vary across platforms. The following keywords exist:
  96.  
  97. disk <volume description>
  98.  
  99.   This item describes one MacOS volume to be mounted by Basilisk II.
  100.   There can be multiple "disk" lines in the preferences file. Basilisk II
  101.   can handle hardfiles (byte-per-byte images of HFS volumes in a file on
  102.   the host system) as well as HFS partitions on hard disks etc. The
  103.   "volume description" is either the pathname of a hardfile or a
  104.   platform-dependant description of an HFS partition or drive. If the
  105.   volume description starts with an asterisk ("*"), the volume is write
  106.   protected for MacOS (and the "*" is discarded).
  107.  
  108.   BeOS:
  109.     To specify an HFS partition, simply specify its path (e.g.
  110.     "/dev/disk/scsi/0/1/0/0_3")
  111.  
  112.   Unix:
  113.     To specify an HFS partition, simply specify its path (e.g.
  114.     "/dev/sda5")
  115.  
  116.   AmigaOS:
  117.     Partitions/drives are specified in the following format:
  118.       /dev/<device name>/<unit>/<open flags>/<start byte>/<size>/<block size>
  119.     "start byte", "size" and "block size" are given in bytes.
  120.  
  121. floppy <floppy drive description>
  122.  
  123.   This item describes one floppy drive to be used by Basilisk II. There
  124.   can be multiple "floppy" lines in the preferences file. If no "floppy"
  125.   line is given, Basilisk II will try to automatically detect and use
  126.   installed floppy drives. The format of the "floppy drive description"
  127.   is the same as that of "disk" lines.
  128.  
  129. cdrom <CD-ROM drive description>
  130.  
  131.   This item describes one CD-ROM drive to be used by Basilisk II. There
  132.   can be multiple "cdrom" lines in the preferences file. If no "cdrom"
  133.   line is given, Basilisk II will try to automatically detect and use
  134.   installed CD-ROM drives. The format of the "CD-ROM drive description"
  135.   is the same as that of "disk" lines.
  136.  
  137. scsi0 <SCSI target> ... scsi6 <SCSI target>
  138.  
  139.   These items describe the SCSI target to be used for a given Mac SCSI
  140.   ID by Basilisk II. Basilisk II emulates the old SCSI Manager and allows
  141.   to assign a different SCSI target (they don't even have to be on the
  142.   same SCSI bus) for each SCSI ID (0..6) as seen by the MacOS. "scsi0"
  143.   describes the target for ID 0, "scsi1" the target for ID 1 etc.
  144.   The format of the "SCSI target" is platform specific.
  145.  
  146.   BeOS:
  147.     The "SCSI target" has the format "<bus>/<unit>" (e.g. "0/2").
  148.     Due to a bug in BeOS, using SCSI with Basilisk II may cause the
  149.     SCSI bus to hang. Use with caution.
  150.  
  151.   Unix:
  152.     <not yet implemented>
  153.  
  154.   AmigaOS:
  155.     The "SCSI target" has the format "<device name>/<unit>" (e.g.
  156.     "scsi.device/2").
  157.  
  158. screen <video mode>
  159.  
  160.   This item describes the type of video display to be used by Basilisk II.
  161.   The format of the "video mode" is platform specific.
  162.  
  163.   BeOS:
  164.     The "video mode" is one of the following:
  165.       win/<width>/<height>
  166.         8-bit color display in a window of the given size. This is the
  167.         default.
  168.       scr
  169.         Full-screen display in an 8-bit 640x480 BWindowScreen.
  170.  
  171.   Unix:
  172.     The "video mode" is one of the following:
  173.       win/<width>/<height>
  174.         Color display in an X11 window of the given size. The color depth
  175.         (8/15/24 bit) depends on the depth of the underlying X11 screen.
  176.         This is the default.
  177.       dga
  178.         Full-screen display using the X11 DGA extensions. The color depth
  179.         (8/15/24 bit) depends on the depth of the underlying X11 screen.
  180.         For DGA to work, Basilisk II must be compiled with DGA support
  181.         enabled (set ENABLE_DGA to 1 in Unix/video_x.cpp).
  182.  
  183.   AmigaOS:
  184.     The "video mode" is one of the following:
  185.       win/<width>/<height>
  186.         Black-and-white display in a window of the given size on the
  187.         Workbench screen. This is the default and will also be used when
  188.         one of the other options (PIP/screen) fails to open.
  189.       pip/<width>/<height>
  190.         15-bit truecolor display in a Picasso96 PIP. This requires
  191.         Picasso96 as well as a PIP-capable graphics card (e.g. Picasso IV).
  192.       scr/<hexadecimal mode ID>
  193.         8/15/24-bit fullscreen display on a Picasso96 screen with the given
  194.         mode ID. This requires Picasso96. For 15 and 24 bit, the frame buffer
  195.         format must be QuickDraw-compatible (big-endian, xRGB 1:5:5:5 or
  196.         xRGB 8:8:8:8). The screen size will be the default size for that
  197.         mode ID.
  198.  
  199. seriala <serial port description>
  200.  
  201.   This item describes the serial port to be used as Port A (Modem Port)
  202.   by Basilisk II. If no "seriala" line is given, Basilisk II will try to
  203.   automatically detect and use installed serial ports. The "serial port
  204.   description" is a platform-dependant description of a serial port.
  205.  
  206.   BeOS:
  207.     Either specify the name of a serial port (e.g. "serial1") or one of
  208.     "parallel1", "parallel2" or "parallel3". See below for more information
  209.     about parallel ports.
  210.  
  211.   Unix:
  212.     Specify the device name of a serial port (e.g. "/dev/ttyS0") or a
  213.     parallel "lp" port (e.g. "/dev/lp1"; this only works under Linux).
  214.     See below for more information about parallel ports.
  215.  
  216.   AmigaOS:
  217.     You have to specify the name of the serial device and the device unit
  218.     as "<device name>/<unit>" (e.g. "serial.device/0"). If the given device
  219.     is not compatible to serial.device, Basilisk II will crash. If the
  220.     device name starts with an asterisk (e.g. "*parallel.device/0"), the
  221.     device is treated as a parallel.device compatible device. See below for
  222.     more information about parallel ports.
  223.  
  224.   Parallel ports: If you select a parallel port it will look like a serial
  225.   port to MacOS but Basilisk II will only allow data output and ignore baud
  226.   rate settings etc. You should be able to get some printers to work with
  227.   this method (provided that you have the right printer driver, like
  228.   "PowerPrint").
  229.  
  230. serialb <serial port description>
  231.  
  232.   This item describes the serial port to be used as Port B (Printer Port)
  233.   by Basilisk II. If no "serialb" line is given, Basilisk II will try to
  234.   automatically detect and use installed serial ports. The format of the
  235.   "serial port description" is the same as that of the "seriala" option.
  236.  
  237. ether <ethernet card description>
  238.  
  239.   This item describes the Ethernet card to be used for Ethernet networking
  240.   by Basilisk II. If no "ether" line is given, Ethernet networking is disabled
  241.   (although the Ethernet driver of Basilisk II will behave like a "dummy"
  242.   Ethernet card in this case). The "ethernet card description" is a platform-
  243.   dependant description of an ethernet card.
  244.  
  245.   BeOS:
  246.     It doesn't matter what you give as "ethernet card description", Basilisk II
  247.     will always use the first Ethernet card it finds as long an an "ether"
  248.     line exists (e.g. say "ether yes"). As Basilisk II requires the sheep_net
  249.     net server add-on from SheepShaver, you can only use Ethernet on PowerPC
  250.     machines.
  251.  
  252.   Unix:
  253.     <not implemented>
  254.  
  255.   AmigaOS:
  256.     You have to specify the name of the SANA-II Ethernet device and the device
  257.     unit as "<device name>/<unit>" (e.g. "ariadne.device/0"). If the given
  258.     device is not a SANA-II device, Basilisk II will crash. If the device is
  259.     not an Ethernet device, Basilisk II will display a warning message and
  260.     disable Ethernet networking.
  261.  
  262. rom <ROM file path>
  263.  
  264.   This item specifies the file name of the Mac ROM file to be used by
  265.   Basilisk II. If no "rom" line is given, the ROM file has to be named
  266.   "ROM" and put in the same directory as the Basilisk II executable.
  267.  
  268. bootdrive <drive number>
  269.  
  270.   Specify MacOS drive number of boot volume. "0" (the default) means
  271.   "boot from first bootable volume".
  272.  
  273. bootdriver <driver number>
  274.  
  275.   Specify MacOS driver number of boot volume. "0" (the default) means
  276.   "boot from first bootable volume". Use "-62" to boot from CD-ROM.
  277.  
  278. ramsize <bytes>
  279.  
  280.   Allocate "bytes" bytes of RAM for MacOS system and application memory.
  281.   The value given should be a multiple of 4096. The default is 8MB.
  282.  
  283. frameskip <frames to skip>
  284.  
  285.   For refreshed graphics modes (usually window modes), this specifies
  286.   how many frames to skip after drawing one frame. Higher values make
  287.   the video display more responsive but require more processing power.
  288.   The default is "8".
  289.  
  290. modelid <MacOS model ID>
  291.  
  292.   Specifies the Model ID that Basilisk II should report to MacOS.
  293.   The default is "5" which corresponds to a Mac IIci. If you want to
  294.   run MacOS 8, you have to set this to "14" (Quadra 900). Other values
  295.   are not officially supported and may result in crashes.
  296.  
  297. nocdrom <"true" or "false">
  298.  
  299.   Set this to "true" to disable Basilisk's built-in CD-ROM driver.
  300.   The only reason to do this is if you want to use a third-party CD-ROM
  301.   driver that uses the SCSI Manager. The default is "false".
  302.  
  303. nogui <"true" or "false">
  304.  
  305.   Set this to "true" to disable the GUI preferences editor and GUI
  306.   error alerts. All errors will then be reported to stdout. The default
  307.   is "false".
  308.  
  309. For additional information, consult prefs.cpp, prefs.h, sys_*.cpp,
  310. serial_*.cpp, scsi_*.cpp and video_*.cpp.
  311.  
  312.  
  313. Usage
  314. -----
  315.  
  316. Quitting:
  317.   The right way to quit Basilisk II is to select the "Shut Down" menu item
  318.   from the Finder's "Special" menu. You should not kill it from the shell
  319.   unless it hangs. Under Unix, pressing "q" while holding the F12 key will
  320.   also quit Basilisk II (in case you are using it in DGA mode and it crashed).
  321.  
  322. Floppy:
  323.   Basilisk II can only handle 1.44MB MFM floppies. Depending on your platform,
  324.   flopyy disk changes might not be detected automatically.
  325.  
  326. Hardfiles:
  327.   In addition to plain images of HFS volumes, Basilisk II can also handle
  328.   some types of Mac "disk image" files, as long as they are uncompressed
  329.   and unencoded.
  330.  
  331. Ethernet:
  332.   Basilisk II supports all Ethernet protocols. Running a protocol under
  333.   Basilisk II that already runs within the host operating system on the same
  334.   network card (e.g. running MacTCP under Basilisk II on a BeOS machine) may
  335.   or may not work (generally, it should work, but some specific things like
  336.   "ping" may not).
  337.  
  338. LocalTalk:
  339.   LocalTalk is not supported by Basilisk II. There is no way of getting
  340.   LocalTalk to work with the serial drivers of Basilisk II. Any attempt to
  341.   activate LocalTalk will either result in a crash or revert to Ethernet.
  342.  
  343. Serial:
  344.   You can use the serial ports in Basilisk II to connect to the Internet
  345.   with a modem and "MacPPP".
  346.  
  347.  
  348. MacOS versions supported
  349. ------------------------
  350.  
  351. Basilisk II has been tested (i.e. it booted) with MacOS System 7.1, 7.5
  352. and 8.0. Your Mileage May Vary. Booting from floppy may take several minutes,
  353. so be patient.
  354.  
  355.  
  356. Technical Documentation
  357. -----------------------
  358.  
  359. Please see the included file "TECH" for a technical overview of the emulator.
  360.  
  361.  
  362. Acknowledgements
  363. ----------------
  364.  
  365. Contributions by:
  366.  - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
  367.  - Mac Hellwig <hellwig@iphcip1.physik.uni-mainz.de>: Some BeOS video code
  368.  - Bill Huey <billh@mag.ucsd.edu>: 15/16 bit DGA and 15/16/32 bit X11
  369.    window support
  370.  
  371. Special thanks to:
  372.  - Bernd Schmidt for letting me use his UAE 68k emulation
  373.  - Daniel Bobbert who printed dozens of pages from the THINK Reference for
  374.    me years ago
  375.  - All ShapeShifter users and beta testers
  376.  - Apple Computer Inc., who made writing a Macintosh emulator a child's play
  377.  
  378.  
  379. Bug reports
  380. -----------
  381.  
  382. You found a bug? Well, use the source, fix it and send the fix to
  383.   <cbauer@iphcip1.physik.uni-mainz.de>
  384. for inclusion in the next release of Basilisk II.
  385.  
  386.  
  387. Author
  388. ------
  389.  
  390. You can contact me at <cbauer@iphcip1.physik.uni-mainz.de>. Don't send
  391. bug reports, send fixes. Ports to other platforms are also very welcome.
  392. Please contact me before you intend to make major changes to the source.
  393. You might be working on something that I have already done or I may have
  394. different ideas about the Right Way to do it.
  395.  
  396. There are two things I will NOT do:
  397.  1. Send you Mac ROM files
  398.  2. Explain to you how to use a Macintosh, install printer drivers etc.
  399.  
  400.  
  401. Support
  402. -------
  403.  
  404. The official Basilisk II home page can be found at
  405.   http://www.uni-mainz.de/~bauec002/B2Main.html
  406.  
  407. There is no user-level support for Basilisk II at the moment.
  408.  
  409.  
  410. History
  411. -------
  412.  
  413. Please consult the file "CHANGES" for the release history.
  414.  
  415.  
  416. Christian Bauer
  417. <cbauer@iphcip1.physik.uni-mainz.de>
  418.