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.1.1.1 by cebix, 1999-10-03T14:16:25Z vs.
Revision 1.13 by cebix, 2000-07-25T15:19:38Z

# Line 1 | Line 1
1  
2 <        Basilisk II, Version 0.7
2 >        Basilisk II, Version 0.8
3          A free, portable Mac II emulator
4  
5 <        Copyright (C) 1997-1999 Christian Bauer et al.
5 >        Copyright (C) 1997-2000 Christian Bauer et al.
6          Freely distributable
7  
8  
# Line 10 | Line 10 | 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.
13 > See the file "COPYING" that is included in the distribution for details.
14  
15  
16   Overview
# Line 22 | Line 22 | distributed under the GNU General Public
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 and IRIX 6.5)
25 >  - Unix (tested under Linux, Solaris 2.5, FreeBSD 3.x, NetBSD 1.4.2 and
26 >    IRIX 6.5)
27    - AmigaOS 3.x
28    - Windows NT 4.0 (mostly works under Windows 95/98, too)
29  
# Line 35 | Line 36 | Some features of Basilisk II:
36    - Floppy disk driver (only 1.44MB disks supported)
37    - Driver for HFS partitions and hardfiles
38    - CD-ROM driver with basic audio functions
39 +  - Easy file exchange with the host OS via a "Host Directory Tree" icon
40 +    on the Mac desktop
41    - Ethernet driver
42    - Serial drivers
43    - SCSI Manager (old-style) emulation
44    - Emulates extended ADB keyboard and 3-button mouse
45 <  - Uses UAE 68k emulation or (under AmigaOS) real 68k processor
45 >  - Uses UAE 68k emulation or (under AmigaOS and NetBSD/m68k) real 68k
46 >    processor
47  
48   The emulator is not yet complete. See the file "TODO" for a list of
49   unimplemented stuff.
50  
51  
52 < Requirements
53 < ------------
50 <
51 < To use Basilisk II, you need either a 512K Mac Classic ROM image or a
52 < 512K or 1MB 32-bit clean Macintosh ROM image. You also need a copy of MacOS
53 < (0.x thru 7.5 for Classic emulation, 7.x or 8.0/8.1 for Mac II emulation).
54 < For copyright reasons, none of these items are included with Basilisk II.
55 < MacOS 7.5.3 and earlier versions can be downloaded from Apple and various
56 < other Internet sites. Mac ROM files are not freely available. You have to
57 < own a real Mac and read out its ROM. No, I don't know where you can download
58 < ROM files. No, I won't send you one.
59 <
60 < Depending on the platform you use, Basilisk II has additional requirements:
61 <
62 < BeOS:
63 <  You need BeOS R4 or better. On a PowerPC system you also need the
64 <  "sheep" driver that comes with SheepShaver. To use Ethernet, you need
65 <  the "sheep_net" add-on that also comes with SheepShaver (both items
66 <  are included in the SheepShaver Trial Versions). The PowerPC version of
67 <  Basilisk II cannot do Mac Classic emulation.
68 <
69 < Unix:
70 <  You need X11R4, pthreads support and GNU make. To use the GUI preferences
71 <  editor, you also need GTK+ version 1.2 or better. On Linux, you need
72 <  glibc 2.0 or better.
73 <
74 < AmigaOS:
75 <  You need at least a 68020 and AmigaOS 3.0 or better. To get the GUI
76 <  preferences editor, you need gtlayout.library V39 or later. To get sound
77 <  output, you need AHI V2 or later. Both items can be found on Aminet. You
78 <  also need the "PrepareEmul" utility that somes with ShapeShifter (or any
79 <  equivalent PrepareEmul substitute). The AmigaOS version of Basilisk II
80 <  cannot do Mac Classic emulation.
81 <
82 < Windows:
83 <  You need at least Windows NT 4.0. Windows 95 and 98 can be used too, with a
84 <  somewhat reduced set of features. Basilisk II supports DirectX version 5 or
85 <  later, but version 3 may also work, depending on your graphics card.
86 <
87 <
88 < Installation
89 < ------------
90 <
91 < BeOS:
92 <  If you have a binary distribution of Basilisk II for BeOS, there are
93 <  executables for BeOS/PPC and BeOS/x86 included. If you have the source
94 <  distribution, cd to "src/BeOS", and type "make". Basilisk II cannot run
95 <  concurrently with SheepShaver. Trying to do so will crash Basilisk II,
96 <  or SheepShaver, or both. On a PowerPC system you must have installed the
97 <  "sheep" driver that comes with SheepShaver. To use Ethernet, you must have
98 <  installed the "sheep_net" add-on that also comes with SheepShaver
99 <
100 < Unix:
101 <  To compile Basilisk II, cd to "src/Unix", and type "./configure" followed
102 <  by "make" and (optionally) "make install". To use Ethernet networking under
103 <  Linux, you either have to configure your kernel for ethertap support or make
104 <  and install the "sheep_net" driver: cd to "src/Unix/Linux/NetDriver" and
105 <  type "make". This should produce a kernel module "sheep_net.o". Now su root
106 <  and type "./MAKEDEV" which will install the device node "/dev/sheep_net".
107 <  Then say "/sbin/insmod sheep_net.o" and the driver should be ready for use.
108 <  You should give appropriate access rights to /dev/sheep_net if you don't
109 <  want to run Basilisk II as root.
110 <
111 <  This is what Brian J. Johnson says about compiling for IRIX:
112 <   "I recommend compiling with "-Ofast".  This requires changing "-g"
113 <    to "-Ofast" in the Makefile, and adding "-ipa" to LDFLAGS.  This
114 <    turns on massive interprocedural optimization, and makes for much
115 <    better performance."
52 > Requirements and Installation
53 > -----------------------------
54  
55 < AmigaOS:
56 <  If you have a binary distribution of Basilisk II for AmigaOS, there is an
119 <  executable included. You must also have the "PrepareEmul" utility installed
120 <  that comes with ShapeShifter (or any equivalent PrepareEmul substitute,
121 <  see the ShapeShifter docs). If you have the source distribution, cd to
122 <  "src/AmigaOS" and type "smake". To recompile Basilisk II, you need SAS/C
123 <  6.58. Earlier versions may not work.
124 <
125 < Windows NT:
126 <  If you have a binary distribution of Basilisk II for Windows, there is a
127 <  Windows NT binary included. To access CD-ROMs under Windows NT, the driver
128 <  "cdenable.sys" must be copied to your "\WinNT\System32\drivers" directory.
129 <  To access CD-ROMs under Windows 9x, the driver "cdenable.vxd" must be copied
130 <  to the "\Windows\System" directory. To recompile Basilisk II, you need
131 <  MS Visual V++ 5.0 or later. Symantec C++ should work, too, with some
132 <  modifications. See the "sysdeps.h" file in the "Windows" directory.
133 <
134 < The ROM file has to be named "ROM" and put in the same directory as the
135 < Basilisk II executable but you can specify a different location for the ROM
136 < file with the "rom" option in the preferences file.
55 > Please consult the file "INSTALL" for a list of system requirements and
56 > installation instructions.
57  
58  
59   Configuration
# Line 221 | Line 141 | cdrom <CD-ROM drive description>
141    installed CD-ROM drives. The format of the "CD-ROM drive description"
142    is the same as that of "disk" lines.
143  
144 + extfs <direcory path>
145 +
146 +  This item specifies the root directory for the "Host Directory Tree"
147 +  file system (the "Unix/BeOS/Amiga/..." icon on the Finder desktop).
148 +  All objects contained in that directory are accessible by Mac applications.
149 +  This feature is only available when File System Manager V1.2 or later
150 +  is installed on the Mac side. FSM 1.2 is built-in beginning with MacOS 7.6
151 +  and can be installed as a system extension (downloadable from Apple, look
152 +  for the FSM SDK in the developer section) for earlier MacOS versions.
153 +
154   scsi0 <SCSI target> ... scsi6 <SCSI target>
155  
156    These items describe the SCSI target to be used for a given Mac SCSI
# Line 250 | Line 180 | scsi0 <SCSI target> ... scsi6 <SCSI targ
180      "scsi.device/2").
181  
182    Windows:
183 <    Ignored. Basilisk II scans for all SCSI devices and the first 6 found
184 <    devices are made visible to the MacOS. You cannot explicitly enable a
255 <    device, but you can disable a device (see the "disablescsi" command).
183 >    The "SCSI target" has the format <"Vendor"> <"Model"> (e.g.
184 >    scsi0 "HP" "CD-Writer+ 7100"). Note the use of quotes.
185  
186   screen <video mode>
187  
# Line 282 | Line 211 | screen <video mode>
211          Color display in an X11 window of the given size. The color depth
212          (8/15/24 bit) depends on the depth of the underlying X11 screen.
213          This is the default.
214 <      dga
215 <        Full-screen display using the X11 DGA extensions. The color depth
214 >      dga/<width>/<height>
215 >        [if Basilisk II was configured with --enable-xf86-dga]
216 >        Full-screen display using the XFree86 DGA extension. The color depth
217          (8/15/24 bit) depends on the depth of the underlying X11 screen.
218 <        For DGA to work, Basilisk II must be compiled with DGA support
219 <        enabled (selectable in the configure script).
218 >        "width" and "height" specify the maximum width/height to use.
219 >        Saying "dga/0/0" means "complete screen".
220 >      dga/<frame buffer name>
221 >        [if Basilisk II was configured with --enable-fbdev-dga]
222 >        Full-screen display using the frame buffer device /dev/fb. The color
223 >        depth (8/15/24 bit) depends on the depth of the underlying X11 screen.
224 >        The "frame buffer name" is looked up in the "fbdevices" file (whose
225 >        path can be specified with the "fbdevicefile" prefs item) to determine
226 >        certain characteristics of the device (doing a "ls -l /dev/fb" should
227 >        tell you what your frame buffer name is).
228  
229    AmigaOS:
230      The "video mode" is one of the following:
# Line 298 | Line 236 | screen <video mode>
236          15-bit truecolor display in a Picasso96 PIP. This requires
237          Picasso96 as well as a PIP-capable graphics card (e.g. Picasso IV).
238        scr/<hexadecimal mode ID>
239 <        8/15/24-bit fullscreen display on a Picasso96 screen with the given
240 <        mode ID. This requires Picasso96. For 15 and 24 bit, the frame buffer
241 <        format must be QuickDraw-compatible (big-endian, xRGB 1:5:5:5 or
242 <        xRGB 8:8:8:8). The screen size will be the default size for that
243 <        mode ID.
239 >        8/15/24-bit fullscreen display on a Picasso96/CyberGraphX screen with
240 >        the given mode ID. This requires Picasso96 or CyberGraphX. For 15 and
241 >        24 bit, the frame buffer format must be QuickDraw-compatible
242 >        (big-endian, xRGB 1:5:5:5 or xRGB 8:8:8:8). The screen size will be
243 >        the default size for that mode ID.
244  
245    Windows:
246      The "video mode" is one of the following:
# Line 396 | Line 334 | ether <ethernet card description>
334    Linux:
335      The "ethernet card description" is the name of an Ethernet interface.
336      There are two approaches to networking with Basilisk II:
337 +
338        1. Direct access to an Ethernet card via the "sheep_net" driver.
339           In this case, the "ethernet card description" must be the name
340           of a real Ethernet card, e.g. "eth0". It also requires the "sheep_net"
# Line 405 | Line 344 | ether <ethernet card description>
344           networking. MacOS will only be able to talk to other machines on
345           the Ethernet, but not to other networks that your Linux box routes
346           (e.g. a second Ethernet or a PPP connection to the Internet).
347 +
348        2. Putting Basilisk II on a virtual Ethernet via the "ethertap" device.
349           In this case, the "ethernet card description" must be the name
350           of an ethertap interface, e.g. "tap0". It also requires that you
351           configure your kernel to enable routing and the ethertap device:
352           under "Networking options", enable "Kernel/User netlink socket" and
353           "Netlink device emulation", under "Network device support", activate
354 <         "Ethertap network tap". Next, see /usr/src/linux/Documentation/
355 <         networking/ethertap.txt for information on how to set up /dev/tap*
356 <         device nodes and activate the ethertap interface. Under MacOS,
357 <         select an IP address that is on the virtual network and set the
358 <         default gateway to the IP address of the ethertap interface. This
359 <         approach will let you access all networks that your Linux box has
360 <         access to (especially, if your Linux box has a dial-up Internet
361 <         connection and is configured for IP masquerading, you can access
362 <         the Internet from MacOS). The drawback is that you can only use
363 <         network protocols that Linux can route, so you have to install and
364 <         configure netatalk if you want to use AppleTalk.
354 >         "Ethertap network tap". You also have to modify devices/net/ethertap.c
355 >         a bit before compiling the new kernel:
356 >
357 >          - insert "#define CONFIG_ETHERTAP_MC 1" near the top (after the
358 >            #include lines)
359 >          - comment out the line "dev->flags|=IFF_NOARP;" in ethertap_probe()
360 >
361 >         Next, see /usr/src/linux/Documentation/networking/ethertap.txt for
362 >         information on how to set up /dev/tap* device nodes and activate the
363 >         ethertap interface. Under MacOS, select an IP address that is on the
364 >         virtual network and set the default gateway to the IP address of the
365 >         ethertap interface. This approach will let you access all networks
366 >         that your Linux box has access to (especially, if your Linux box has
367 >         a dial-up Internet connection and is configured for IP masquerading,
368 >         you can access the Internet from MacOS). The drawback is that you
369 >         can only use network protocols that Linux can route, so you have to
370 >         install and configure netatalk if you want to use AppleTalk. Here is
371 >         an example /etc/atalk/atalkd.conf for a LAN:
372 >
373 >           eth0 -seed -phase 2 -net 1 -addr 1.47 -zone "Ethernet"
374 >           tap0 -seed -phase 2 -net 2 -addr 2.47 -zone "Basilisknet"
375 >
376 >         (the "47" is an arbitrary node number). This will set up a zone
377 >         "Ethernet" (net 1) for the Ethernet and a zone "Basilisknet" (net 2)
378 >         for the internal network connection of the ethertap interface.
379 >         MacOS should automatically recognize the nets and zones upon startup.
380 >         If you are in an existing AppleTalk network, you should contact
381 >         your network administrator about the nets and zones you can use
382 >         (instead of the ones given in the example above).
383  
384    AmigaOS:
385      You have to specify the name of the SANA-II Ethernet device and the device
# Line 458 | Line 416 | frameskip <frames to skip>
416    For refreshed graphics modes (usually window modes), this specifies
417    how many frames to skip after drawing one frame. Higher values make
418    the video display more responsive but require more processing power.
419 <  The default is "8".
419 >  The default is "8". Under Unix/X11, a value of "0" selects a "dynamic"
420 >  update mode that cuts the display into rectangles and updates each
421 >  rectangle individually, depending on display changes.
422  
423   modelid <MacOS model ID>
424  
# Line 497 | Line 457 | System-specific configuration
457   Unix:
458  
459    keycodes <"true" or "false">
460 <  keycodefile <Keycode file path>
460 >  keycodefile <keycodes file path>
461  
462      By default, the X11 event handler in Basilisk II uses KeySyms to
463      translate keyboard event to Mac keycodes. While this method is very
# Line 508 | Line 468 | Unix:
468      not on the selected keymap. Unfortunately it depends on the X server
469      being used and possibly also on the type of keyboard attached. So
470      Basilisk II needs a table to translate X keycodes to Mac keycodes.
471 <    This table is read by default from /usr/local/lib/basilisk_ii_keycodes
471 >    This table is read by default from /usr/local/share/BasiliskII/keycodes
472      unless you specify a different file with the "keycodefile" item.
473 <    A sample keycode file ("basilisk_ii_keycodes") is included with
474 <    Basilisk II.
473 >    A sample keycode file is included with Basilisk II.
474 >
475 >  fbdevicefile <fbdevices file path>
476 >
477 >    This option specifies the file that contains frame buffer device
478 >    specifications for the fbdev-DGA video mode (when Basilisk II was
479 >    configured with --enable-fbdev-dga). The default location of the file
480 >    is /usr/local/share/BasiliskII/fbdevices. A sample file is included
481 >    with Basilisk II.
482 >
483 >  mousewheelmode <mode>
484 >
485 >    If you have a mouse with a wheel, this option specifies whether moving
486 >    the wheel will be reported to the MacOS as "Page up/down" (mode 0) or
487 >    "Cursor up/down" (mode 1) keys.
488 >
489 >  mousewheellines <number of lines>
490 >
491 >    If "mousewheelmode" is set to mode 1 (Cursor up/down), this option sets
492 >    the number of key events sent to MacOS for each wheel movement (the
493 >    number of lines to scroll).
494  
495   AmigaOS:
496  
# Line 552 | Line 531 | Windows:
531    
532      Note the use of quotes.
533  
534 <  disablescsi <"Vendor"> <"Model">
534 >  rightmouse <0/1>
535  
536 <    Disables this vendor/model combination. You may need this simply because
537 <    you have more than 6 SCSI devices, or the particular device has problems
538 <    under BasiliskII. E.g.
536 >    Defines what the right mouse button is used for. The default values of 0
537 >    means that it is used to move windowed mode BasiliskII screen.
538 >    Value 1 sends a combination Control and mouse click to the MacOS.
539 >    This may be useful under OS versions 8 and above.
540  
541 <      disablescsi "HP" "CD-Writer+ 7100"
542 <  
543 <    Again, note the use of quotes.
541 >  keyboardfile <path>
542 >
543 >    Defines the path of the customized keyboard code file.
544 >
545 >  pollmedia <"true" or "false">
546 >
547 >    If true (default), tries to automatically detect new media.
548 >    Applies to all "floppy", "cd" or "disk" removable media except
549 >    1.44 MB floppies. May cause modest slow down. If unchecked,
550 >    use Ctrl-Shift-F11 to manually mount new media.
551 >    If you have auto-insert notification (AIN) enabled, you may turn this
552 >    option off. Note that some CD related software require AIN,
553 >    and some other need it to be turned off. Consult the documentation
554 >    of your CD software to learn which one is optimal for you.
555 >
556 >  framesleepticks <milliseconds>    
557 >
558 >    The amount of time between video frames.
559 >
560 >  showfps <true/false>
561 >
562 >    If true, the real frame rate is displayed.
563 >
564 >  stickymenu <true/false>
565 >
566 >    If true, the main menu bar is kept open even after the mouse button is released,
567 >    under all OS versions (OS 8 has this feature already). There are extensions to do
568 >    the same thing, but it's faster to handle this in native code.
569 >    Default is "true".
570  
571    ntdx5hack <"true" or "false">
572  
# Line 652 | Line 658 | Please see the included file "TECH" for
658   Acknowledgements
659   ----------------
660  
661 < Contributions by:
656 < - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
657 < - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
658 <   and networking
659 < - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
661 > Contributions by (in alphabetical order):
662   - Orlando Bassotto <future@powercube.mediabit.net>: FreeBSD support
663 < - Brian J. Johnson <bjohnson@sgi.com>: IRIX support
663 > - Gwenole Beauchesne <gb@dial.oleane.com>: SPARC assembly optimizations and
664 >   fbdev video code
665   - Marc Chabanas <Marc.Chabanas@france.sun.com>: Solaris sound support
666 + - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
667 +   and networking
668   - Bill Huey <billh@mag.ucsd.edu>: 15/16 bit DGA and 15/16/32 bit X11
669     window support
670 + - Brian J. Johnson <bjohnson@sgi.com>: IRIX support
671 + - Jürgen Lachmann <juergen_lachmann@t-online.de>: AmigaOS CyberGraphX support
672 + - Samuel Lander <blair_sp@hotmail.com>: tile-based window refresh code
673   - David Lawrence <davidl@jlab.org>: incremental window refresh code
674 + - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
675 + - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
676 + - and others...
677  
678   Special thanks to:
679   - Bernd Schmidt for letting me use his UAE 68k emulation
# Line 707 | Line 718 | There is no user-level support for Basil
718   History
719   -------
720  
721 < Please consult the file "CHANGES" for the release history.
721 > Please consult the file "ChangeLog" for the release history.
722  
723  
724   Christian Bauer

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines