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.4 by cebix, 1999-10-03T20:40:05Z vs.
Revision 1.22 by cebix, 2001-07-12T19:48:24Z

# Line 1 | Line 1
1  
2 <        Basilisk II, Version 0.7
3 <        A free, portable Mac II emulator
2 >  Basilisk II
3 >  A 68k Macintosh emulator
4  
5 <        Copyright (C) 1997-1999 Christian Bauer et al.
6 <        Freely distributable
5 >  Copyright (C) 1997-2001 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 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.
# Line 137 | 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 166 | 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
171 <    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 199 | Line 212 | screen <video mode>
212          (8/15/24 bit) depends on the depth of the underlying X11 screen.
213          This is the default.
214        dga/<width>/<height>
215 <        Full-screen display using the X11 DGA extensions. The color depth
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          "width" and "height" specify the maximum width/height to use.
219 <        Saying "dga/0/0" means "complete screen". For DGA to work, Basilisk II
220 <        must be compiled with DGA support enabled (selectable in the configure
221 <        script).
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 216 | 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 307 | Line 327 | ether <ethernet card description>
327    BeOS:
328      It doesn't matter what you give as "ethernet card description", Basilisk II
329      will always use the first Ethernet card it finds as long an an "ether"
330 <    line exists (e.g. say "ether yes"). As Basilisk II requires the sheep_net
331 <    net server add-on from SheepShaver, you can only use Ethernet on PowerPC
332 <    machines.
330 >    line exists (e.g. say "ether yes"). Using Ethernet requires the "sheep_net"
331 >    Net Server add-on to be installed. The first time you start Basilisk II
332 >    with Ethernet enabled you will be asked whether it's OK to make the
333 >    necessary changes to your BeOS network configuration to enable sheep_net.
334  
335    Linux:
336      The "ethernet card description" is the name of an Ethernet interface.
337      There are two approaches to networking with Basilisk II:
338 +
339        1. Direct access to an Ethernet card via the "sheep_net" driver.
340           In this case, the "ethernet card description" must be the name
341           of a real Ethernet card, e.g. "eth0". It also requires the "sheep_net"
# Line 323 | Line 345 | ether <ethernet card description>
345           networking. MacOS will only be able to talk to other machines on
346           the Ethernet, but not to other networks that your Linux box routes
347           (e.g. a second Ethernet or a PPP connection to the Internet).
348 +
349        2. Putting Basilisk II on a virtual Ethernet via the "ethertap" device.
350           In this case, the "ethernet card description" must be the name
351           of an ethertap interface, e.g. "tap0". It also requires that you
352           configure your kernel to enable routing and the ethertap device:
353           under "Networking options", enable "Kernel/User netlink socket" and
354           "Netlink device emulation", under "Network device support", activate
355 <         "Ethertap network tap". Next, see /usr/src/linux/Documentation/
356 <         networking/ethertap.txt for information on how to set up /dev/tap*
357 <         device nodes and activate the ethertap interface. Under MacOS,
358 <         select an IP address that is on the virtual network and set the
359 <         default gateway to the IP address of the ethertap interface. This
360 <         approach will let you access all networks that your Linux box has
361 <         access to (especially, if your Linux box has a dial-up Internet
362 <         connection and is configured for IP masquerading, you can access
363 <         the Internet from MacOS). The drawback is that you can only use
364 <         network protocols that Linux can route, so you have to install and
365 <         configure netatalk if you want to use AppleTalk.
355 >         "Ethertap network tap". You also have to modify drivers/net/ethertap.c
356 >         a bit before compiling the new kernel:
357 >
358 >          - insert "#define CONFIG_ETHERTAP_MC 1" near the top (after the
359 >            #include lines)
360 >          - comment out the line "dev->flags|=IFF_NOARP;" in ethertap_probe()
361 >
362 >         Next, see /usr/src/linux/Documentation/networking/ethertap.txt for
363 >         information on how to set up /dev/tap* device nodes and activate the
364 >         ethertap interface. Under MacOS, select an IP address that is on the
365 >         virtual network and set the default gateway to the IP address of the
366 >         ethertap interface. This approach will let you access all networks
367 >         that your Linux box has access to (especially, if your Linux box has
368 >         a dial-up Internet connection and is configured for IP masquerading,
369 >         you can access the Internet from MacOS). The drawback is that you
370 >         can only use network protocols that Linux can route, so you have to
371 >         install and configure netatalk if you want to use AppleTalk. Here is
372 >         an example /etc/atalk/atalkd.conf for a LAN:
373 >
374 >           eth0 -seed -phase 2 -net 1 -addr 1.47 -zone "Ethernet"
375 >           tap0 -seed -phase 2 -net 2 -addr 2.47 -zone "Basilisknet"
376 >
377 >         (the "47" is an arbitrary node number). This will set up a zone
378 >         "Ethernet" (net 1) for the Ethernet and a zone "Basilisknet" (net 2)
379 >         for the internal network connection of the ethertap interface.
380 >         MacOS should automatically recognize the nets and zones upon startup.
381 >         If you are in an existing AppleTalk network, you should contact
382 >         your network administrator about the nets and zones you can use
383 >         (instead of the ones given in the example above).
384 >
385 >  FreeBSD:
386 >    The "ethertap" method described above also works under FreeBSD, but since
387 >    no-one has found the time to write a section for this manual, you're on
388 >    your own here...
389  
390    AmigaOS:
391      You have to specify the name of the SANA-II Ethernet device and the device
# Line 348 | Line 394 | ether <ethernet card description>
394      not an Ethernet device, Basilisk II will display a warning message and
395      disable Ethernet networking.
396  
397 +  See the next item for an alternative way to do networking with Basilisk II.
398 +
399 + udptunnel <"true" or "false">
400 +
401 +  Setting this to "true" enables a special network mode in which all network
402 +  packets sent by MacOS are tunnelled over UDP using the host operating
403 +  system's native TCP/IP stack. This only works with AppleTalk and can only
404 +  be used to connect computers running Basilisk II (and not, for example, for
405 +  connecting to an AppleShare server running on a real Mac), but it is
406 +  probably the easiest way to set up a network between two instances of
407 +  Basilisk II because the UDP tunnelling doesn't require any special kernel
408 +  modules or network add-ons. It relies on IP broadcasting, however, so
409 +  its range is limited.
410 +
411 + udpport <IP port number>
412 +
413 +  This item specifies the IP port number to use for the "AppleTalk over UDP"
414 +  tunnel mode. The default is 6066.
415 +
416   rom <ROM file path>
417  
418    This item specifies the file name of the Mac ROM file to be used by
# Line 376 | Line 441 | frameskip <frames to skip>
441    For refreshed graphics modes (usually window modes), this specifies
442    how many frames to skip after drawing one frame. Higher values make
443    the video display more responsive but require more processing power.
444 <  The default is "8".
444 >  The default is "8". Under Unix/X11, a value of "0" selects a "dynamic"
445 >  update mode that cuts the display into rectangles and updates each
446 >  rectangle individually, depending on display changes.
447  
448   modelid <MacOS model ID>
449  
# Line 415 | Line 482 | System-specific configuration
482   Unix:
483  
484    keycodes <"true" or "false">
485 <  keycodefile <Keycode file path>
485 >  keycodefile <keycodes file path>
486  
487      By default, the X11 event handler in Basilisk II uses KeySyms to
488      translate keyboard event to Mac keycodes. While this method is very
# Line 426 | Line 493 | Unix:
493      not on the selected keymap. Unfortunately it depends on the X server
494      being used and possibly also on the type of keyboard attached. So
495      Basilisk II needs a table to translate X keycodes to Mac keycodes.
496 <    This table is read by default from /usr/local/lib/basilisk_ii_keycodes
496 >    This table is read by default from /usr/local/share/BasiliskII/keycodes
497      unless you specify a different file with the "keycodefile" item.
498 <    A sample keycode file ("basilisk_ii_keycodes") is included with
499 <    Basilisk II.
498 >    A sample keycode file is included with Basilisk II.
499 >
500 >  fbdevicefile <fbdevices file path>
501 >
502 >    This option specifies the file that contains frame buffer device
503 >    specifications for the fbdev-DGA video mode (when Basilisk II was
504 >    configured with --enable-fbdev-dga). The default location of the file
505 >    is /usr/local/share/BasiliskII/fbdevices. A sample file is included
506 >    with Basilisk II.
507 >
508 >  mousewheelmode <mode>
509 >
510 >    If you have a mouse with a wheel, this option specifies whether moving
511 >    the wheel will be reported to the MacOS as "Page up/down" (mode 0) or
512 >    "Cursor up/down" (mode 1) keys.
513 >
514 >  mousewheellines <number of lines>
515 >
516 >    If "mousewheelmode" is set to mode 1 (Cursor up/down), this option sets
517 >    the number of key events sent to MacOS for each wheel movement (the
518 >    number of lines to scroll).
519  
520   AmigaOS:
521  
# Line 441 | Line 527 | AmigaOS:
527  
528        ahi/<hexadecimal mode ID>
529  
530 +  scsimemtype <type>
531 +
532 +    This item controls the type of memory to use for SCSI buffers. Possible
533 +    values are:
534 +      0 Chip memory
535 +      1 24-bit DMA capable memory
536 +      2 Any memory
537 +
538 +    Be warned that many SCSI host adapters will not work with the "Any memory"
539 +    setting. Basilisk II has no way of knowing which memory type is supported
540 +    by the host adapter and setting an unsupported type will result in data
541 +    corruption.
542 +
543   Windows:
544  
545    noscsi <"true" or "false">
# Line 470 | Line 569 | Windows:
569    
570      Note the use of quotes.
571  
572 <  disablescsi <"Vendor"> <"Model">
572 >  rightmouse <0/1>
573  
574 <    Disables this vendor/model combination. You may need this simply because
575 <    you have more than 6 SCSI devices, or the particular device has problems
576 <    under BasiliskII. E.g.
574 >    Defines what the right mouse button is used for. The default values of 0
575 >    means that it is used to move windowed mode BasiliskII screen.
576 >    Value 1 sends a combination Control and mouse click to the MacOS.
577 >    This may be useful under OS versions 8 and above.
578  
579 <      disablescsi "HP" "CD-Writer+ 7100"
580 <  
581 <    Again, note the use of quotes.
579 >  keyboardfile <path>
580 >
581 >    Defines the path of the customized keyboard code file.
582 >
583 >  pollmedia <"true" or "false">
584 >
585 >    If true (default), tries to automatically detect new media.
586 >    Applies to all "floppy", "cd" or "disk" removable media except
587 >    1.44 MB floppies. May cause modest slow down. If unchecked,
588 >    use Ctrl-Shift-F11 to manually mount new media.
589 >    If you have auto-insert notification (AIN) enabled, you may turn this
590 >    option off. Note that some CD related software require AIN,
591 >    and some other need it to be turned off. Consult the documentation
592 >    of your CD software to learn which one is optimal for you.
593 >
594 >  framesleepticks <milliseconds>    
595 >
596 >    The amount of time between video frames.
597 >
598 >  showfps <true/false>
599 >
600 >    If true, the real frame rate is displayed.
601 >
602 >  stickymenu <true/false>
603 >
604 >    If true, the main menu bar is kept open even after the mouse button is released,
605 >    under all OS versions (OS 8 has this feature already). There are extensions to do
606 >    the same thing, but it's faster to handle this in native code.
607 >    Default is "true".
608  
609    ntdx5hack <"true" or "false">
610  
# Line 509 | Line 635 | Keyboard:
635    On PC-style keyboards, "Alt" is the Mac "Command" key, while the "Windows"
636    key is the Mac "Option" key.
637  
638 + Mouse:
639 +  Under Unix, press Ctrl-F5 while the Basilisk II window is active will grab
640 +  the mouse. This is needed for compatibility with some MacOS programs,
641 +  especially games. Press Ctrl-F5 again to return to normal mouse operation.
642 +
643   Floppy:
644    Basilisk II can only handle 1.44MB MFM floppies. Depending on your platform,
645 <  flopyy disk changes might not be detected automatically. Under Linux, press
645 >  floppy disk changes might not be detected automatically. Under Unix, press
646    Ctrl-F1 to mount a floppy. Under BeOS, select the appropriate "Mount" menu
647    item or press Ctrl-F1 to mount a floppy. Under Windows, press Ctrl-Shift-F11.
648  
# Line 570 | Line 701 | Please see the included file "TECH" for
701   Acknowledgements
702   ----------------
703  
704 < Contributions by:
574 < - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
575 < - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
576 <   and networking
577 < - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
704 > Contributions by (in alphabetical order):
705   - Orlando Bassotto <future@powercube.mediabit.net>: FreeBSD support
706 < - Brian J. Johnson <bjohnson@sgi.com>: IRIX support
706 > - Gwenole Beauchesne <gb@dial.oleane.com>: SPARC assembly optimizations and
707 >   fbdev video code
708   - Marc Chabanas <Marc.Chabanas@france.sun.com>: Solaris sound support
709 + - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
710 +   and networking
711   - Bill Huey <billh@mag.ucsd.edu>: 15/16 bit DGA and 15/16/32 bit X11
712     window support
713 + - Brian J. Johnson <bjohnson@sgi.com>: IRIX support
714 + - Jürgen Lachmann <juergen_lachmann@t-online.de>: AmigaOS CyberGraphX support
715 + - Samuel Lander <blair_sp@hotmail.com>: tile-based window refresh code
716   - David Lawrence <davidl@jlab.org>: incremental window refresh code
717 + - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
718 + - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
719 + - and others...
720  
721   Special thanks to:
722   - Bernd Schmidt for letting me use his UAE 68k emulation

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines