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.19 by cebix, 2001-03-29T14:20:52Z vs.
Revision 1.25 by nigel, 2002-03-16T05:27:56Z

# Line 2 | Line 2
2    Basilisk II
3    A 68k Macintosh emulator
4  
5 <  Copyright (C) 1997-2001 Christian Bauer et al.
5 >  Copyright (C) 1997-2002 Christian Bauer et al.
6  
7  
8   License
# Line 22 | Line 22 | 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)
29 +  - Mac OS X 10.1
30  
31   Some features of Basilisk II:
32    - Emulates either a Mac Classic (which runs MacOS 0.x thru 7.5)
# Line 68 | Line 69 | The settings are stored in a text file:
69   BeOS:
70    /boot/home/config/settings/BasiliskII_prefs
71  
72 < Unix:
72 > Unix, Mac OS X:
73    ~/.basilisk_ii_prefs
74  
75   AmigaOS:
# Line 94 | Line 95 | disk <volume description>
95    This item describes one MacOS volume to be mounted by Basilisk II.
96    There can be multiple "disk" lines in the preferences file. Basilisk II
97    can handle hardfiles (byte-per-byte images of HFS volumes in a file on
98 <  the host system) as well as HFS partitions on hard disks etc. (but Basilisk
99 <  II doesn't know about MacOS partition tables; it relies on the host OS to
100 <  handle this). The "volume description" is either the pathname of a hardfile
101 <  or a platform-dependant description of an HFS partition or drive. If the
102 <  volume description starts with an asterisk ("*"), the volume is write
103 <  protected for MacOS (and the "*" is discarded).
98 >  the host system), HFS partitions on hard disks etc., and MacOS-partitioned
99 >  disks (it can only access the first partition, though). The "volume
100 >  description" is either the pathname of a hardfile or a platform-dependant
101 >  description of an HFS partition or drive. If the volume description is
102 >  prefixed by an asterisk ("*"), the volume is write protected for MacOS.
103 >
104 >  Basilisk II can also handle some types of Mac "disk image" files directly,
105 >  as long as they are uncompressed and unencoded.
106  
107    BeOS:
108      To specify an HFS partition, simply specify its path (e.g.
109 <    "/dev/disk/scsi/0/1/0/0_3"). If you don't specify any volume, Basilisk II
109 >    "/dev/disk/scsi/0/1/0/0_3"). If you don't specify any volumes, Basilisk II
110      will search for and use all available HFS partitions.
111  
112    Unix:
113 <    To specify an HFS partition, simply specify its path (e.g.
114 <    "/dev/sda5").
113 >    To specify an HFS partition, simply specify its path (e.g. "/dev/sda5").
114 >    If you want to access a MacOS-partitioned hard disk or removable volume
115 >    (Jaz, Zip etc.) and your operating system doesn't understand MacOS
116 >    partition tables, you can specify the block device name (e.g. "/dev/sda")
117 >    to access the first HFS partition on the device. Under Linux, if you
118 >    don't specify any volumes, Basilisk II will search /etc/fstab for
119 >    unmounted HFS partitions and use these.
120  
121    AmigaOS:
122      Partitions/drives are specified in the following format:
# Line 146 | Line 154 | extfs <direcory path>
154    This item specifies the root directory for the "Host Directory Tree"
155    file system (the "Unix/BeOS/Amiga/..." icon on the Finder desktop).
156    All objects contained in that directory are accessible by Mac applications.
157 +
158    This feature is only available when File System Manager V1.2 or later
159    is installed on the Mac side. FSM 1.2 is built-in beginning with MacOS 7.6
160    and can be installed as a system extension (downloadable from Apple, look
# Line 185 | Line 194 | scsi0 <SCSI target> ... scsi6 <SCSI targ
194  
195   screen <video mode>
196  
197 <  This item describes the type of video display to be used by Basilisk II.
198 <  If you are using a Mac Classic ROM, the display is always 1-bit 512x342
199 <  and this item is ignored. The format of the "video mode" is platform
200 <  specific.
197 >  This item describes the type of video display to be used by default for
198 >  Basilisk II. If you are using a Mac Classic ROM, the display is always
199 >  1-bit 512x342 and this item is ignored. The format of the "video mode" is
200 >  platform specific.
201  
202    BeOS:
203      The "video mode" is one of the following:
# Line 208 | Line 217 | screen <video mode>
217    Unix:
218      The "video mode" is one of the following:
219        win/<width>/<height>
220 <        Color display in an X11 window of the given size. The color depth
221 <        (8/15/24 bit) depends on the depth of the underlying X11 screen.
222 <        This is the default.
220 >        Color display in an X11 window of the given size. There are several
221 >        resolutions and color depths available. The set of color depths
222 >        depends on the capabilities of the X11 server, the operating system,
223 >        and Basilisk II compile-time options, but 1 bit and the default depth
224 >        of the X11 screen should always be available.
225        dga/<width>/<height>
226          [if Basilisk II was configured with --enable-xf86-dga]
227          Full-screen display using the XFree86 DGA extension. The color depth
# Line 274 | Line 285 | screen <video mode>
285      application via Alt-Tab, Basilisk II is put in "snooze" mode (i.e. MacOS
286      is frozen).
287  
288 +
289 +  Mac OS X:
290 +    The "video mode" is one of the following:
291 +      win/<width>/<height>
292 +      win/<width>/<height>/<bits per pixel>
293 +        A refreshed (and buffered) [and very slow] Quartz window.
294 +        The default <bits> is 32, which is the only depth currently supported.
295 +      full/<width>/<height>
296 +      full/<width>/<height>/<bits per pixel>
297 +        A CGDirectDisplay full screen mode. <bits> can currently be 8, 16 or 32.
298 +        If not specified, the default is 32. There is currently no way to switch
299 +        between the Mac OS X and Basilisk II display, but Apple-Option-Escape
300 +        instantly and safely terminates the Basilisk II program.
301 +      opengl/<width>/<height>
302 +      opengl/<width>/<height>/<bits per pixel>
303 +        Currently unimplemented, will be a fast windowed mode.
304 +
305 +
306   seriala <serial port description>
307  
308    This item describes the serial port to be used as Port A (Modem Port)
# Line 324 | Line 353 | ether <ethernet card description>
353    is not available and this setting is ignored. The "ethernet card description"
354    is a platform-dependant description of an ethernet card.
355  
356 +  General note: To use TCP/IP from MacOS, you should assign a different IP
357 +  address to the MacOS (entered into the MacOS TCP/IP (or MacTCP) control
358 +  panel). Otherwise there will be confusion about which operating system will
359 +  handle incoming packets.
360 +
361    BeOS:
362      It doesn't matter what you give as "ethernet card description", Basilisk II
363      will always use the first Ethernet card it finds as long an an "ether"
# Line 336 | Line 370 | ether <ethernet card description>
370      The "ethernet card description" is the name of an Ethernet interface.
371      There are two approaches to networking with Basilisk II:
372  
373 <      1. Direct access to an Ethernet card via the "sheep_net" driver.
374 <         In this case, the "ethernet card description" must be the name
375 <         of a real Ethernet card, e.g. "eth0". It also requires the "sheep_net"
376 <         driver to be installed and accessible. This approach will allow you
377 <         to run all networking protocols under MacOS (TCP/IP, AppleTalk, IPX
378 <         etc.) but there is no connection between Linux networking and MacOS
379 <         networking. MacOS will only be able to talk to other machines on
380 <         the Ethernet, but not to other networks that your Linux box routes
381 <         (e.g. a second Ethernet or a PPP connection to the Internet).
373 >      1. Direct access to an Ethernet card via the "sheep_net" kernel module.
374 >         The "ethernet card description" must be the name of a real Ethernet
375 >         card, e.g. "eth0".
376 >
377 >         The sheep_net module is included in the Basilisk II source
378 >         distribution in the directory "src/Unix/Linux/NetDriver". You have
379 >         to compile and install the module yourself:
380 >
381 >           $ su
382 >           [enter root password]
383 >           # make
384 >           # make dev
385 >           [this will create a /dev/sheep_net device node; you should give
386 >            appropriate access rights to the user(s) running Basilisk II]
387 >           # insmod sheep_net.o
388 >
389 >         If you copy the sheep_net.o module to a place where it can be found
390 >         by the kernel module loader ("/lib/modules/<version>/kernel/drivers/net"
391 >         for 2.4 kernels) and add the line
392 >
393 >           alias char-major-10-198 sheep_net
394 >
395 >         to "/etc/modules.conf", the kernel should be able to load the module
396 >         automatically when Basilisk II is started.
397 >
398 >         The sheep_net module will allow you to run all networking protocols
399 >         under MacOS (TCP/IP, AppleTalk, IPX etc.) but there is no connection
400 >         between Linux networking and MacOS networking. MacOS will only be
401 >         able to talk to other machines on the Ethernet, but not to other
402 >         networks that your Linux box routes (e.g. a second Ethernet or a PPP
403 >         connection to the Internet).
404  
405        2. Putting Basilisk II on a virtual Ethernet via the "ethertap" device.
406           In this case, the "ethernet card description" must be the name
407           of an ethertap interface, e.g. "tap0". It also requires that you
408 <         configure your kernel to enable routing and the ethertap device:
408 >         configure your kernel to enable routing and ethertap support:
409           under "Networking options", enable "Kernel/User netlink socket" and
410           "Netlink device emulation", under "Network device support", activate
411           "Ethertap network tap". You also have to modify drivers/net/ethertap.c
# Line 394 | Line 450 | ether <ethernet card description>
450      not an Ethernet device, Basilisk II will display a warning message and
451      disable Ethernet networking.
452  
453 +  See the next item for an alternative way to do networking with Basilisk II.
454 +
455 + udptunnel <"true" or "false">
456 +
457 +  Setting this to "true" enables a special network mode in which all network
458 +  packets sent by MacOS are tunnelled over UDP using the host operating
459 +  system's native TCP/IP stack. This can only be used to connect computers
460 +  running Basilisk II (and not, for example, for connecting to the Internet
461 +  or an AppleShare server running on a real Mac), but it is probably the
462 +  easiest way to set up a network between two instances of Basilisk II
463 +  because the UDP tunnelling doesn't require any special kernel modules or
464 +  network add-ons. It relies on IP broadcasting, however, so its range is
465 +  limited. It should be fine though for doing a little file sharing or
466 +  playing Spectre.
467 +
468 + udpport <IP port number>
469 +
470 +  This item specifies the IP port number to use for the "UDP Tunnel" mode.
471 +  The default is 6066.
472 +
473   rom <ROM file path>
474  
475    This item specifies the file name of the Mac ROM file to be used by
# Line 428 | Line 504 | frameskip <frames to skip>
504  
505   modelid <MacOS model ID>
506  
507 <  Specifies the Model ID that Basilisk II should report to MacOS.
508 <  The default is "5" which corresponds to a Mac IIci. If you want to
509 <  run MacOS 8, you have to set this to "14" (Quadra 900). Other values
510 <  are not officially supported and may result in crashes. MacOS versions
511 <  earlier than 7.5 may only run with the Model ID set to "5". If you are
512 <  using a Mac Classic ROM, the model is always "Mac Classic" and this
513 <  setting is ignored.
507 >  Specifies the Macintosh model ID that Basilisk II should report to MacOS.
508 >  The default is "5" which corresponds to a Mac IIci. If you want to run
509 >  MacOS 8, you have to set this to "14" (Quadra 900). Other values are not
510 >  officially supported and may result in crashes. MacOS versions earlier
511 >  than 7.5 may only run with the Model ID set to "5". If you are using a Mac
512 >  Classic ROM, the model is always "Mac Classic" and this setting is
513 >  ignored.
514  
515   nosound <"true" or "false">
516  
# Line 508 | Line 584 | AmigaOS:
584  
585        ahi/<hexadecimal mode ID>
586  
587 +  scsimemtype <type>
588 +
589 +    This item controls the type of memory to use for SCSI buffers. Possible
590 +    values are:
591 +      0 Chip memory
592 +      1 24-bit DMA capable memory
593 +      2 Any memory
594 +
595 +    Be warned that many SCSI host adapters will not work with the "Any memory"
596 +    setting. Basilisk II has no way of knowing which memory type is supported
597 +    by the host adapter and setting an unsupported type will result in data
598 +    corruption.
599 +
600   Windows:
601  
602    noscsi <"true" or "false">
# Line 518 | Line 607 | Windows:
607      means is that the control is not returned to the application until the
608      command is completely finished. Normally this is not an issue, but when a
609      CDR/CDRW is closed or erased the burner program typically wants to wait in
610 <    some progress dialog The result may be that the application reports a
610 >    some progress dialog the result may be that the application reports a
611      time-out error, but the operation completes all right anyway.
612  
613    nofloppyboot <"true" or "false">
# Line 532 | Line 621 | Windows:
621      This is very useful since many devices have almost identical ATAPI and SCSI
622      versions of their hardware, and MacOS applications usually support the SCSI
623      version only. The example below is typical:
624 <  
624 >
625        replacescsi "HP" "CD-Writer+ 7100" "PHILIPS" "CDD3600"
626 <  
626 >
627      Note the use of quotes.
628  
629    rightmouse <0/1>
# Line 559 | Line 648 | Windows:
648      and some other need it to be turned off. Consult the documentation
649      of your CD software to learn which one is optimal for you.
650  
651 <  framesleepticks <milliseconds>    
651 >  framesleepticks <milliseconds>
652  
653      The amount of time between video frames.
654  
# Line 569 | Line 658 | Windows:
658  
659    stickymenu <true/false>
660  
661 <    If true, the main menu bar is kept open even after the mouse button is released,
662 <    under all OS versions (OS 8 has this feature already). There are extensions to do
663 <    the same thing, but it's faster to handle this in native code.
664 <    Default is "true".
661 >    If true, the main menu bar is kept open even after the mouse button is
662 >    released, under all OS versions (OS 8 has this feature already). There
663 >    are extensions to do the same thing, but it's faster to handle this in
664 >    native code. Default is "true".
665  
666    ntdx5hack <"true" or "false">
667  
668 <    You may need this on NT if your display adapter driver has a bug in DirectX
669 <    palette support. Black and white are reversed. It fixes the palette issue
670 <    by using GDI palette instead of D3D palette. Default is false.
668 >    You may need this on NT if your display adapter driver has a bug in
669 >    DirectX palette support. Black and white are reversed. It fixes the
670 >    palette issue by using GDI palette instead of D3D palette. Default is
671 >    false.
672  
673  
674   Usage
# Line 603 | Line 693 | Keyboard:
693    On PC-style keyboards, "Alt" is the Mac "Command" key, while the "Windows"
694    key is the Mac "Option" key.
695  
696 + Mouse:
697 +  Under Unix, pressing Ctrl-F5 while the Basilisk II window is active will
698 +  grab the mouse. This is needed for compatibility with some MacOS programs,
699 +  especially games such as flight simulators. Press Ctrl-F5 again to return
700 +  to normal mouse operation.
701 +
702   Floppy:
703    Basilisk II can only handle 1.44MB MFM floppies. Depending on your platform,
704 <  flopyy disk changes might not be detected automatically. Under Linux, press
704 >  floppy disk changes might not be detected automatically. Under Unix, press
705    Ctrl-F1 to mount a floppy. Under BeOS, select the appropriate "Mount" menu
706    item or press Ctrl-F1 to mount a floppy. Under Windows, press Ctrl-Shift-F11.
707  
708   HFS partitions:
709    Having HFS partitions mounted for read-write access under Basilisk II while
710    they are also mounted on the host OS will most likely result in volume
711 <  corruption and data losses. Unmount your HFS volumes before starting
711 >  corruption and data loss. Unmount your HFS volumes before starting
712    Basilisk II.
713  
714   ZIP drives:
# Line 631 | Line 727 | Mac Classic emulation:
727    ROM. Also, the video display is fixed to 512x342 in monochrome. The AmigaOS
728    and BeOS/PPC versions of Basilisk II cannot do Mac Classic emulation.
729  
730 + Video resolution switching:
731 +  Run-time switching of video resolutions requires the Display Manager. This
732 +  is included in MacOS versions 7.6 and above, and available as a system
733 +  extension for earlier MacOS versions as a free download from ftp.apple.com
734 +  (look for "Display Software 2.x"). Click on "Options..." in the "Monitors"
735 +  control panel to select the resolution.
736 +
737   Sound output:
738    Sound output under Basilisk II requires Sound Manager 3.0 or later. This
739 <  is included starting with MacOS 7.5 and available as a system extension
740 <  for earlier MacOS versions. Sample rate, bit resolution and mono/stereo
741 <  can be selected in the Sound control panel (section "Sound Out").
739 >  is included in MacOS versions 7.5 and above, and available as a system
740 >  extension for earlier MacOS versions as a free download from ftp.apple.com.
741 >  Sample rate, bit resolution and mono/stereo can be selected in the Sound
742 >  control panel (section "Sound Out").
743  
744   Ethernet:
745    Basilisk II supports all Ethernet protocols. Running a protocol under
746    Basilisk II that already runs within the host operating system on the same
747    network card (e.g. running MacTCP under Basilisk II on a BeOS machine) may
748    or may not work (generally, it should work, but some specific things like
749 <  "ping" may not). If you have problems with FTP, try setting your FTP client
749 >  "ping" may not). If you have problems with FTP, try setting the FTP client
750    to passive mode.
751  
752   LocalTalk:
# Line 652 | Line 756 | LocalTalk:
756  
757   Serial:
758    You can use the serial ports in Basilisk II to connect to the Internet
759 <  with a modem and "MacPPP".
759 >  with a modem and the "MacPPP" or "Open Transport/PPP" software.
760  
761  
762   Technical Documentation
# Line 666 | Line 770 | Acknowledgements
770  
771   Contributions by (in alphabetical order):
772   - Orlando Bassotto <future@powercube.mediabit.net>: FreeBSD support
773 < - Gwenole Beauchesne <gb@dial.oleane.com>: SPARC assembly optimizations and
774 <   fbdev video code
773 > - Gwenolé Beauchesne <gb@dial.oleane.com>: SPARC assembly optimizations,
774 >   lots of work on the Unix video code
775   - Marc Chabanas <Marc.Chabanas@france.sun.com>: Solaris sound support
776   - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
777     and networking
# Line 677 | Line 781 | Contributions by (in alphabetical order)
781   - Jürgen Lachmann <juergen_lachmann@t-online.de>: AmigaOS CyberGraphX support
782   - Samuel Lander <blair_sp@hotmail.com>: tile-based window refresh code
783   - David Lawrence <davidl@jlab.org>: incremental window refresh code
784 + - Nigel Pearson <nigel@ind.tansu.com.au>: Mac OS X port
785   - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
786   - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
787   - and others...
# Line 696 | Line 801 | You found a bug? Well, use the source, f
801    <Christian.Bauer@uni-mainz.de>
802   for inclusion in the next release of Basilisk II.
803  
804 + If you don't have a fix, you should post a bug report using the Source Forge
805 + bug tracker, supplying as much information as possible (operating system and
806 + versions of Basilisk II and MacOS being used, relevant hardware information,
807 + the exact steps to reproduce the bug, etc.):
808 +  http://sourceforge.net/tracker/?group_id=2123&atid=102123
809 +
810 + I also strongly suggest reading this before posting a bug report:
811 +  http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
812 +
813  
814   Author
815   ------
816  
817 < You can contact me at <Christian.Bauer@uni-mainz.de>. Don't send bug
818 < reports, send fixes. Ports to other platforms are also very welcome.
819 < Please contact me before you intend to make major changes to the source.
820 < You might be working on something that I have already done or I may have
821 < different ideas about the Right Way to do it.
822 <
823 < Questions about ROM files will not be answered. There is also no point in
824 < sending me questions etc. that are specific to the Windows port of
825 < Basilisk II. I don't have Windows and can't say anything about that.
826 < Ask Lauri Pesonen instead.
817 > You can contact me at <Christian.Bauer@uni-mainz.de>, but please don't do
818 > so unless absolutely necessary. I'm maintaining Basilisk II in my spare
819 > time and am not able to provide technical support for everyone. If you have
820 > questions, consider posting them to one of the support forums mentioned
821 > below.
822 >
823 > You are encouraged to contact me personally when
824 > - you have bug fixes or small enhancements for the code
825 > - you want to port Basilisk II to another platform
826 > - you want to discuss technical issues
827 > - you intend to make major changes to the source; you might be working on
828 >   something that I have already done, or I may have different ideas about
829 >   the Right Way to do it
830 >
831 > There is no point in sending me questions about
832 > - ROM files and how/where to get them
833 > - versions of Basilisk II that run on operating systems other than Unix,
834 >   BeOS and AmigaOS. If you are using any other operating system, there's
835 >   no point in asking me how to to X or why Y doesn't work because I won't
836 >   know either. Instead, you should look in the "Acknowledgements" section
837 >   of this manual to find the person responsible. For example, if your
838 >   question is specific to the Windows operating system, ask Lauri Pesonen.
839 >   I don't have Windows and can't answer your questions and I'm too lazy to
840 >   forward mail to Lauri myself. In any case, it would probably be better
841 >   to post your questions to a public forum as it will get a much wider
842 >   audience there.
843  
844  
845   Support
# Line 718 | Line 848 | Support
848   The official Basilisk II home page is at
849    http://www.uni-mainz.de/~bauec002/B2Main.html
850  
851 < There is no user-level support for Basilisk II at the moment.
851 > The Basilisk II project page on SourceForge is at
852 >  http://sourceforge.net/projects/basilisk/
853 >
854 > If you have problems, you may want to visit the Basilisk II forums:
855 >  http://sourceforge.net/forum/?group_id=2123
856 >
857 > There is also a mailing list for Basilisk II users:
858 >  http://lists.sourceforge.net/lists/listinfo/basilisk-user
859 >
860 > And another mailing list for Basilisk II developers:
861 >  http://lists.sourceforge.net/lists/listinfo/basilisk-devel
862 >
863 > Some general advice about asking technical support questions can be found at
864 >  http://www.tuxedo.org/~esr/faqs/smart-questions.html
865 >
866 > Keeping this in mind will greatly increase your chances of getting a useful
867 > answer.
868  
869  
870   History

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines