ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/cebix/BasiliskII/README
(Generate patch)

Comparing BasiliskII/README (file contents):
Revision 1.12 by cebix, 2000-07-13T17:45:51Z vs.
Revision 1.24 by cebix, 2002-01-15T14:58:31Z

# Line 1 | Line 1
1  
2 <        Basilisk II, Version 0.8
3 <        A free, portable Mac II emulator
2 >  Basilisk II
3 >  A 68k Macintosh emulator
4  
5 <        Copyright (C) 1997-2000 Christian Bauer et al.
6 <        Freely distributable
5 >  Copyright (C) 1997-2002 Christian Bauer et al.
6  
7  
8   License
# Line 16 | Line 15 | See the file "COPYING" that is included
15   Overview
16   --------
17  
18 < Basilisk II is a free, portable, Open Source 68k Mac emulator. It requires
19 < a copy of a Mac ROM and a copy of MacOS to run. Basilisk II is freeware and
20 < distributed under the GNU General Public License.
18 > Basilisk II is an Open Source 68k Macintosh emulator. That is, it enables
19 > you to run 68k MacOS software on you computer, even if you are using a
20 > different operating system. However, you still need a copy of MacOS and
21 > a Macintosh ROM image to use Basilisk II.
22  
23   Basilisk II has currently been ported to the following systems:
24    - BeOS R4 (PowerPC and x86)
25 <  - Unix (tested under Linux, Solaris 2.5, FreeBSD 3.x, NetBSD 1.4.2 and
25 >  - Unix (tested under Linux, Solaris 2.x, FreeBSD 3.x, NetBSD 1.4.x and
26      IRIX 6.5)
27    - AmigaOS 3.x
28    - Windows NT 4.0 (mostly works under Windows 95/98, too)
# Line 94 | Line 94 | disk <volume description>
94    This item describes one MacOS volume to be mounted by Basilisk II.
95    There can be multiple "disk" lines in the preferences file. Basilisk II
96    can handle hardfiles (byte-per-byte images of HFS volumes in a file on
97 <  the host system) as well as HFS partitions on hard disks etc. (but Basilisk
98 <  II doesn't know about MacOS partition tables; it relies on the host OS to
99 <  handle this). The "volume description" is either the pathname of a hardfile
100 <  or a platform-dependant description of an HFS partition or drive. If the
101 <  volume description starts with an asterisk ("*"), the volume is write
102 <  protected for MacOS (and the "*" is discarded).
97 >  the host system), HFS partitions on hard disks etc., and MacOS-partitioned
98 >  disks (it can only access the first partition, though). The "volume
99 >  description" is either the pathname of a hardfile or a platform-dependant
100 >  description of an HFS partition or drive. If the volume description is
101 >  prefixed by an asterisk ("*"), the volume is write protected for MacOS.
102 >
103 >  Basilisk II can also handle some types of Mac "disk image" files directly,
104 >  as long as they are uncompressed and unencoded.
105  
106    BeOS:
107      To specify an HFS partition, simply specify its path (e.g.
108 <    "/dev/disk/scsi/0/1/0/0_3"). If you don't specify any volume, Basilisk II
108 >    "/dev/disk/scsi/0/1/0/0_3"). If you don't specify any volumes, Basilisk II
109      will search for and use all available HFS partitions.
110  
111    Unix:
112 <    To specify an HFS partition, simply specify its path (e.g.
113 <    "/dev/sda5").
112 >    To specify an HFS partition, simply specify its path (e.g. "/dev/sda5").
113 >    If you want to access a MacOS-partitioned hard disk or removable volume
114 >    (Jaz, Zip etc.) and your operating system doesn't understand MacOS
115 >    partition tables, you can specify the block device name (e.g. "/dev/sda")
116 >    to access the first HFS partition on the device. Under Linux, if you
117 >    don't specify any volumes, Basilisk II will search /etc/fstab for
118 >    unmounted HFS partitions and use these.
119  
120    AmigaOS:
121      Partitions/drives are specified in the following format:
# Line 146 | Line 153 | extfs <direcory path>
153    This item specifies the root directory for the "Host Directory Tree"
154    file system (the "Unix/BeOS/Amiga/..." icon on the Finder desktop).
155    All objects contained in that directory are accessible by Mac applications.
156 +
157    This feature is only available when File System Manager V1.2 or later
158    is installed on the Mac side. FSM 1.2 is built-in beginning with MacOS 7.6
159    and can be installed as a system extension (downloadable from Apple, look
# Line 185 | Line 193 | scsi0 <SCSI target> ... scsi6 <SCSI targ
193  
194   screen <video mode>
195  
196 <  This item describes the type of video display to be used by Basilisk II.
197 <  If you are using a Mac Classic ROM, the display is always 1-bit 512x342
198 <  and this item is ignored. The format of the "video mode" is platform
199 <  specific.
196 >  This item describes the type of video display to be used by default for
197 >  Basilisk II. If you are using a Mac Classic ROM, the display is always
198 >  1-bit 512x342 and this item is ignored. The format of the "video mode" is
199 >  platform specific.
200  
201    BeOS:
202      The "video mode" is one of the following:
# Line 208 | Line 216 | screen <video mode>
216    Unix:
217      The "video mode" is one of the following:
218        win/<width>/<height>
219 <        Color display in an X11 window of the given size. The color depth
220 <        (8/15/24 bit) depends on the depth of the underlying X11 screen.
221 <        This is the default.
219 >        Color display in an X11 window of the given size. There are several
220 >        resolutions and color depths available. The set of color depths
221 >        depends on the capabilities of the X11 server, the operating system,
222 >        and Basilisk II compile-time options, but 1 bit and the default depth
223 >        of the X11 screen should always be available.
224        dga/<width>/<height>
225          [if Basilisk II was configured with --enable-xf86-dga]
226          Full-screen display using the XFree86 DGA extension. The color depth
# Line 324 | Line 334 | ether <ethernet card description>
334    is not available and this setting is ignored. The "ethernet card description"
335    is a platform-dependant description of an ethernet card.
336  
337 +  General note: To use TCP/IP from MacOS, you should assign a different IP
338 +  address to the MacOS (entered into the MacOS TCP/IP (or MacTCP) control
339 +  panel). Otherwise there will be confusion about which operating system will
340 +  handle incoming packets.
341 +
342    BeOS:
343      It doesn't matter what you give as "ethernet card description", Basilisk II
344      will always use the first Ethernet card it finds as long an an "ether"
345 <    line exists (e.g. say "ether yes"). As Basilisk II requires the sheep_net
346 <    net server add-on from SheepShaver, you can only use Ethernet on PowerPC
347 <    machines.
345 >    line exists (e.g. say "ether yes"). Using Ethernet requires the "sheep_net"
346 >    Net Server add-on to be installed. The first time you start Basilisk II
347 >    with Ethernet enabled you will be asked whether it's OK to make the
348 >    necessary changes to your BeOS network configuration to enable sheep_net.
349  
350    Linux:
351      The "ethernet card description" is the name of an Ethernet interface.
352      There are two approaches to networking with Basilisk II:
353  
354 <      1. Direct access to an Ethernet card via the "sheep_net" driver.
355 <         In this case, the "ethernet card description" must be the name
356 <         of a real Ethernet card, e.g. "eth0". It also requires the "sheep_net"
357 <         driver to be installed and accessible. This approach will allow you
358 <         to run all networking protocols under MacOS (TCP/IP, AppleTalk, IPX
359 <         etc.) but there is no connection between Linux networking and MacOS
360 <         networking. MacOS will only be able to talk to other machines on
361 <         the Ethernet, but not to other networks that your Linux box routes
362 <         (e.g. a second Ethernet or a PPP connection to the Internet).
354 >      1. Direct access to an Ethernet card via the "sheep_net" kernel module.
355 >         The "ethernet card description" must be the name of a real Ethernet
356 >         card, e.g. "eth0".
357 >
358 >         The sheep_net module is included in the Basilisk II source
359 >         distribution in the directory "src/Unix/Linux/NetDriver". You have
360 >         to compile and install the module yourself:
361 >
362 >           $ su
363 >           [enter root password]
364 >           # make
365 >           # make dev
366 >           [this will create a /dev/sheep_net device node; you should give
367 >            appropriate access rights to the user(s) running Basilisk II]
368 >           # insmod sheep_net.o
369 >
370 >         If you copy the sheep_net.o module to a place where it can be found
371 >         by the kernel module loader ("/lib/modules/<version>/kernel/drivers/net"
372 >         for 2.4 kernels) and add the line
373 >
374 >           alias char-major-10-198 sheep_net
375 >
376 >         to "/etc/modules.conf", the kernel should be able to load the module
377 >         automatically when Basilisk II is started.
378 >
379 >         The sheep_net module will allow you to run all networking protocols
380 >         under MacOS (TCP/IP, AppleTalk, IPX etc.) but there is no connection
381 >         between Linux networking and MacOS networking. MacOS will only be
382 >         able to talk to other machines on the Ethernet, but not to other
383 >         networks that your Linux box routes (e.g. a second Ethernet or a PPP
384 >         connection to the Internet).
385  
386        2. Putting Basilisk II on a virtual Ethernet via the "ethertap" device.
387           In this case, the "ethernet card description" must be the name
388           of an ethertap interface, e.g. "tap0". It also requires that you
389 <         configure your kernel to enable routing and the ethertap device:
389 >         configure your kernel to enable routing and ethertap support:
390           under "Networking options", enable "Kernel/User netlink socket" and
391           "Netlink device emulation", under "Network device support", activate
392 <         "Ethertap network tap". You also have to modify devices/net/ethertap.c
392 >         "Ethertap network tap". You also have to modify drivers/net/ethertap.c
393           a bit before compiling the new kernel:
394  
395            - insert "#define CONFIG_ETHERTAP_MC 1" near the top (after the
# Line 381 | Line 419 | ether <ethernet card description>
419           your network administrator about the nets and zones you can use
420           (instead of the ones given in the example above).
421  
422 +  FreeBSD:
423 +    The "ethertap" method described above also works under FreeBSD, but since
424 +    no-one has found the time to write a section for this manual, you're on
425 +    your own here...
426 +
427    AmigaOS:
428      You have to specify the name of the SANA-II Ethernet device and the device
429      unit as "<device name>/<unit>" (e.g. "ariadne.device/0"). If the given
# Line 388 | Line 431 | ether <ethernet card description>
431      not an Ethernet device, Basilisk II will display a warning message and
432      disable Ethernet networking.
433  
434 +  See the next item for an alternative way to do networking with Basilisk II.
435 +
436 + udptunnel <"true" or "false">
437 +
438 +  Setting this to "true" enables a special network mode in which all network
439 +  packets sent by MacOS are tunnelled over UDP using the host operating
440 +  system's native TCP/IP stack. This can only be used to connect computers
441 +  running Basilisk II (and not, for example, for connecting to the Internet
442 +  or an AppleShare server running on a real Mac), but it is probably the
443 +  easiest way to set up a network between two instances of Basilisk II
444 +  because the UDP tunnelling doesn't require any special kernel modules or
445 +  network add-ons. It relies on IP broadcasting, however, so its range is
446 +  limited. It should be fine though for doing a little file sharing or
447 +  playing Spectre.
448 +
449 + udpport <IP port number>
450 +
451 +  This item specifies the IP port number to use for the "UDP Tunnel" mode.
452 +  The default is 6066.
453 +
454   rom <ROM file path>
455  
456    This item specifies the file name of the Mac ROM file to be used by
# Line 422 | Line 485 | frameskip <frames to skip>
485  
486   modelid <MacOS model ID>
487  
488 <  Specifies the Model ID that Basilisk II should report to MacOS.
489 <  The default is "5" which corresponds to a Mac IIci. If you want to
490 <  run MacOS 8, you have to set this to "14" (Quadra 900). Other values
491 <  are not officially supported and may result in crashes. MacOS versions
492 <  earlier than 7.5 may only run with the Model ID set to "5". If you are
493 <  using a Mac Classic ROM, the model is always "Mac Classic" and this
494 <  setting is ignored.
488 >  Specifies the Macintosh model ID that Basilisk II should report to MacOS.
489 >  The default is "5" which corresponds to a Mac IIci. If you want to run
490 >  MacOS 8, you have to set this to "14" (Quadra 900). Other values are not
491 >  officially supported and may result in crashes. MacOS versions earlier
492 >  than 7.5 may only run with the Model ID set to "5". If you are using a Mac
493 >  Classic ROM, the model is always "Mac Classic" and this setting is
494 >  ignored.
495  
496   nosound <"true" or "false">
497  
# Line 502 | Line 565 | AmigaOS:
565  
566        ahi/<hexadecimal mode ID>
567  
568 +  scsimemtype <type>
569 +
570 +    This item controls the type of memory to use for SCSI buffers. Possible
571 +    values are:
572 +      0 Chip memory
573 +      1 24-bit DMA capable memory
574 +      2 Any memory
575 +
576 +    Be warned that many SCSI host adapters will not work with the "Any memory"
577 +    setting. Basilisk II has no way of knowing which memory type is supported
578 +    by the host adapter and setting an unsupported type will result in data
579 +    corruption.
580 +
581   Windows:
582  
583    noscsi <"true" or "false">
# Line 512 | Line 588 | Windows:
588      means is that the control is not returned to the application until the
589      command is completely finished. Normally this is not an issue, but when a
590      CDR/CDRW is closed or erased the burner program typically wants to wait in
591 <    some progress dialog The result may be that the application reports a
591 >    some progress dialog the result may be that the application reports a
592      time-out error, but the operation completes all right anyway.
593  
594    nofloppyboot <"true" or "false">
# Line 526 | Line 602 | Windows:
602      This is very useful since many devices have almost identical ATAPI and SCSI
603      versions of their hardware, and MacOS applications usually support the SCSI
604      version only. The example below is typical:
605 <  
605 >
606        replacescsi "HP" "CD-Writer+ 7100" "PHILIPS" "CDD3600"
607 <  
607 >
608      Note the use of quotes.
609  
610    rightmouse <0/1>
# Line 553 | Line 629 | Windows:
629      and some other need it to be turned off. Consult the documentation
630      of your CD software to learn which one is optimal for you.
631  
632 <  framesleepticks <milliseconds>    
632 >  framesleepticks <milliseconds>
633  
634      The amount of time between video frames.
635  
# Line 563 | Line 639 | Windows:
639  
640    stickymenu <true/false>
641  
642 <    If true, the main menu bar is kept open even after the mouse button is released,
643 <    under all OS versions (OS 8 has this feature already). There are extensions to do
644 <    the same thing, but it's faster to handle this in native code.
645 <    Default is "true".
642 >    If true, the main menu bar is kept open even after the mouse button is
643 >    released, under all OS versions (OS 8 has this feature already). There
644 >    are extensions to do the same thing, but it's faster to handle this in
645 >    native code. Default is "true".
646  
647    ntdx5hack <"true" or "false">
648  
649 <    You may need this on NT if your display adapter driver has a bug in DirectX
650 <    palette support. Black and white are reversed. It fixes the palette issue
651 <    by using GDI palette instead of D3D palette. Default is false.
649 >    You may need this on NT if your display adapter driver has a bug in
650 >    DirectX palette support. Black and white are reversed. It fixes the
651 >    palette issue by using GDI palette instead of D3D palette. Default is
652 >    false.
653  
654  
655   Usage
# Line 597 | Line 674 | Keyboard:
674    On PC-style keyboards, "Alt" is the Mac "Command" key, while the "Windows"
675    key is the Mac "Option" key.
676  
677 + Mouse:
678 +  Under Unix, pressing Ctrl-F5 while the Basilisk II window is active will
679 +  grab the mouse. This is needed for compatibility with some MacOS programs,
680 +  especially games such as flight simulators. Press Ctrl-F5 again to return
681 +  to normal mouse operation.
682 +
683   Floppy:
684    Basilisk II can only handle 1.44MB MFM floppies. Depending on your platform,
685 <  flopyy disk changes might not be detected automatically. Under Linux, press
685 >  floppy disk changes might not be detected automatically. Under Unix, press
686    Ctrl-F1 to mount a floppy. Under BeOS, select the appropriate "Mount" menu
687    item or press Ctrl-F1 to mount a floppy. Under Windows, press Ctrl-Shift-F11.
688  
689   HFS partitions:
690    Having HFS partitions mounted for read-write access under Basilisk II while
691    they are also mounted on the host OS will most likely result in volume
692 <  corruption and data losses. Unmount your HFS volumes before starting
692 >  corruption and data loss. Unmount your HFS volumes before starting
693    Basilisk II.
694  
695   ZIP drives:
# Line 625 | Line 708 | Mac Classic emulation:
708    ROM. Also, the video display is fixed to 512x342 in monochrome. The AmigaOS
709    and BeOS/PPC versions of Basilisk II cannot do Mac Classic emulation.
710  
711 + Video resolution switching:
712 +  Run-time switching of video resolutions requires the Display Manager. This
713 +  is included in MacOS versions 7.6 and above, and available as a system
714 +  extension for earlier MacOS versions as a free download from ftp.apple.com
715 +  (look for "Display Software 2.x"). Click on "Options..." in the "Monitors"
716 +  control panel to select the resolution.
717 +
718   Sound output:
719    Sound output under Basilisk II requires Sound Manager 3.0 or later. This
720 <  is included starting with MacOS 7.5 and available as a system extension
721 <  for earlier MacOS versions. Sample rate, bit resolution and mono/stereo
722 <  can be selected in the Sound control panel (section "Sound Out").
720 >  is included in MacOS versions 7.5 and above, and available as a system
721 >  extension for earlier MacOS versions as a free download from ftp.apple.com.
722 >  Sample rate, bit resolution and mono/stereo can be selected in the Sound
723 >  control panel (section "Sound Out").
724  
725   Ethernet:
726    Basilisk II supports all Ethernet protocols. Running a protocol under
727    Basilisk II that already runs within the host operating system on the same
728    network card (e.g. running MacTCP under Basilisk II on a BeOS machine) may
729    or may not work (generally, it should work, but some specific things like
730 <  "ping" may not). If you have problems with FTP, try setting your FTP client
730 >  "ping" may not). If you have problems with FTP, try setting the FTP client
731    to passive mode.
732  
733   LocalTalk:
# Line 646 | Line 737 | LocalTalk:
737  
738   Serial:
739    You can use the serial ports in Basilisk II to connect to the Internet
740 <  with a modem and "MacPPP".
740 >  with a modem and the "MacPPP" or "Open Transport/PPP" software.
741  
742  
743   Technical Documentation
# Line 658 | Line 749 | Please see the included file "TECH" for
749   Acknowledgements
750   ----------------
751  
752 < Contributions by:
662 < - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
663 < - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
664 <   and networking
665 < - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
752 > Contributions by (in alphabetical order):
753   - Orlando Bassotto <future@powercube.mediabit.net>: FreeBSD support
754 < - Brian J. Johnson <bjohnson@sgi.com>: IRIX support
754 > - Gwenolé Beauchesne <gb@dial.oleane.com>: SPARC assembly optimizations,
755 >   lots of work on the Unix video code
756   - Marc Chabanas <Marc.Chabanas@france.sun.com>: Solaris sound support
757 + - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
758 +   and networking
759   - Bill Huey <billh@mag.ucsd.edu>: 15/16 bit DGA and 15/16/32 bit X11
760     window support
761 < - David Lawrence <davidl@jlab.org>: incremental window refresh code
761 > - Brian J. Johnson <bjohnson@sgi.com>: IRIX support
762 > - Jürgen Lachmann <juergen_lachmann@t-online.de>: AmigaOS CyberGraphX support
763   - Samuel Lander <blair_sp@hotmail.com>: tile-based window refresh code
764 < - Gwenole Beauchesne <gb@dial.oleane.com>: SPARC assembly optimizations and
765 <   fbdev video code
764 > - David Lawrence <davidl@jlab.org>: incremental window refresh code
765 > - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
766 > - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
767   - and others...
768  
769   Special thanks to:
# Line 689 | Line 781 | You found a bug? Well, use the source, f
781    <Christian.Bauer@uni-mainz.de>
782   for inclusion in the next release of Basilisk II.
783  
784 + If you don't have a fix, you should post a bug report using the Source Forge
785 + bug tracker, supplying as much information as possible (operating system and
786 + versions of Basilisk II and MacOS being used, relevant hardware information,
787 + the exact steps to reproduce the bug, etc.):
788 +  http://sourceforge.net/tracker/?group_id=2123&atid=102123
789 +
790 + I also strongly suggest reading this before posting a bug report:
791 +  http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
792 +
793  
794   Author
795   ------
796  
797 < You can contact me at <Christian.Bauer@uni-mainz.de>. Don't send bug
798 < reports, send fixes. Ports to other platforms are also very welcome.
799 < Please contact me before you intend to make major changes to the source.
800 < You might be working on something that I have already done or I may have
801 < different ideas about the Right Way to do it.
802 <
803 < Questions about ROM files will not be answered. There is also no point in
804 < sending me questions etc. that are specific to the Windows port of
805 < Basilisk II. I don't have Windows and can't say anything about that.
806 < Ask Lauri Pesonen instead.
797 > You can contact me at <Christian.Bauer@uni-mainz.de>, but please don't do
798 > so unless absolutely necessary. I'm maintaining Basilisk II in my spare
799 > time and am not able to provide technical support for everyone. If you have
800 > questions, consider posting them to one of the support forums mentioned
801 > below.
802 >
803 > You are encouraged to contact me personally when
804 > - you have bug fixes or small enhancements for the code
805 > - you want to port Basilisk II to another platform
806 > - you want to discuss technical issues
807 > - you intend to make major changes to the source; you might be working on
808 >   something that I have already done, or I may have different ideas about
809 >   the Right Way to do it
810 >
811 > There is no point in sending me questions about
812 > - ROM files and how/where to get them
813 > - versions of Basilisk II that run on operating systems other than Unix,
814 >   BeOS and AmigaOS. If you are using any other operating system, there's
815 >   no point in asking me how to to X or why Y doesn't work because I won't
816 >   know either. Instead, you should look in the "Acknowledgements" section
817 >   of this manual to find the person responsible. For example, if your
818 >   question is specific to the Windows operating system, ask Lauri Pesonen.
819 >   I don't have Windows and can't answer your questions and I'm too lazy to
820 >   forward mail to Lauri myself. In any case, it would probably be better
821 >   to post your questions to a public forum as it will get a much wider
822 >   audience there.
823  
824  
825   Support
# Line 711 | Line 828 | Support
828   The official Basilisk II home page is at
829    http://www.uni-mainz.de/~bauec002/B2Main.html
830  
831 < There is no user-level support for Basilisk II at the moment.
831 > The Basilisk II project page on SourceForge is at
832 >  http://sourceforge.net/projects/basilisk/
833 >
834 > If you have problems, you may want to visit the Basilisk II forums:
835 >  http://sourceforge.net/forum/?group_id=2123
836 >
837 > There is also a mailing list for Basilisk II users:
838 >  http://lists.sourceforge.net/lists/listinfo/basilisk-user
839 >
840 > And another mailing list for Basilisk II developers:
841 >  http://lists.sourceforge.net/lists/listinfo/basilisk-devel
842 >
843 > Some general advice about asking technical support questions can be found at
844 >  http://www.tuxedo.org/~esr/faqs/smart-questions.html
845 >
846 > Keeping this in mind will greatly increase your chances of getting a useful
847 > answer.
848  
849  
850   History

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines