ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/cebix/BasiliskII/README
Revision: 1.46
Committed: 2008-10-01T10:34:34Z (16 years, 1 month ago) by cebix
Branch: MAIN
CVS Tags: HEAD
Changes since 1.45: +1 -1 lines
Log Message:
fixed the "smart questions" link

File Contents

# Content
1
2 Basilisk II
3 A 68k Macintosh emulator
4
5 Copyright (C) 1997-2008 Christian Bauer et al.
6
7
8 License
9 -------
10
11 Basilisk II is available under the terms of the GNU General Public License.
12 See the file "COPYING" that is included in the distribution for details.
13
14
15 Overview
16 --------
17
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.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 thru 10.4
30
31 Some features of Basilisk II:
32 - Emulates either a Mac Classic (which runs MacOS 0.x thru 7.5)
33 or a Mac II series machine (which runs MacOS 7.x, 8.0 and 8.1),
34 depending on the ROM being used
35 - Color video display
36 - CD quality sound output
37 - Floppy disk driver (only 1.44MB disks supported)
38 - Driver for HFS partitions and hardfiles
39 - CD-ROM driver with basic audio functions
40 - Easy file exchange with the host OS via a "Host Directory Tree" icon
41 on the Mac desktop
42 - Ethernet driver
43 - Serial drivers
44 - SCSI Manager (old-style) emulation
45 - Emulates extended ADB keyboard and 3-button mouse
46 - Uses UAE 68k emulation or (under AmigaOS and NetBSD/m68k) real 68k
47 processor
48
49 The emulator is not yet complete. See the file "TODO" for a list of
50 unimplemented stuff.
51
52
53 Requirements and Installation
54 -----------------------------
55
56 Please consult the file "INSTALL" for a list of system requirements and
57 installation instructions.
58
59
60 Configuration
61 -------------
62
63 Basilisk II is configured via the preferences editor that appears on startup.
64 If you have a version without preferences editor (e.g. because of missing GTK+
65 under Unix), you have to edit the preferences file manually.
66
67 The settings are stored in a text file:
68
69 BeOS:
70 /boot/home/config/settings/BasiliskII_prefs
71
72 Unix, Mac OS X:
73 ~/.basilisk_ii_prefs
74
75 AmigaOS:
76 ENV:BasiliskII_prefs
77
78 Windows:
79 BasiliskII_prefs (in the same directory as the executable)
80
81 If no preferences file is present, Basilisk II will create one with the
82 default settings upon startup.
83
84
85 Preferences File Format
86 -----------------------
87
88 The preferences file is a text file editable with any text editor.
89 Each line in this file has the format "keyword value" and describes
90 one preferences item. For each keyword, the meaning of the "value"
91 string may vary across platforms. The following keywords exist:
92
93 disk <volume description>
94
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), 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 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. "/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:
123 /dev/<device name>/<unit>/<open flags>/<start block>/<size>/<block size>
124 "start block" and "size" are given in blocks, "block size" is given in
125 bytes.
126
127 Windows:
128 To define a logical volume (Windows NT only), specify its path (e.g. "c:\").
129 To define a physical volume (NT and 9x), additionally give the "physical"
130 keyword (E.g. "physical c:\"). For safety reasons, volumes are mounted as
131 read-only. This is due to the bugs in PC Exchange. If you don't specify
132 any volume, the files *.hfv and *.dsk are searched from the current
133 directory. Note that in this case, Basilisk II tries to boot from the first
134 volume file found, which is random and may not be what you want.
135
136 floppy <floppy drive description>
137
138 This item describes one floppy drive to be used by Basilisk II. There
139 can be multiple "floppy" lines in the preferences file. If no "floppy"
140 line is given, Basilisk II will try to automatically detect and use
141 installed floppy drives. The format of the "floppy drive description"
142 is the same as that of "disk" lines.
143
144 cdrom <CD-ROM drive description>
145
146 This item describes one CD-ROM drive to be used by Basilisk II. There
147 can be multiple "cdrom" lines in the preferences file. If no "cdrom"
148 line is given, Basilisk II will try to automatically detect and use
149 installed CD-ROM drives. The format of the "CD-ROM drive description"
150 is the same as that of "disk" lines.
151
152 extfs <direcory path>
153
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
161 for the FSM SDK in the developer section) for earlier MacOS versions.
162
163 scsi0 <SCSI target> ... scsi6 <SCSI target>
164
165 These items describe the SCSI target to be used for a given Mac SCSI
166 ID by Basilisk II. Basilisk II emulates the old SCSI Manager and allows
167 to assign a different SCSI target (they don't even have to be on the
168 same SCSI bus) for each SCSI ID (0..6) as seen by the MacOS. "scsi0"
169 describes the target for ID 0, "scsi1" the target for ID 1 etc.
170 The format of the "SCSI target" is platform specific.
171
172 BeOS:
173 The "SCSI target" has the format "<bus>/<unit>" (e.g. "0/2").
174 Due to a bug in BeOS, using SCSI with Basilisk II may cause the
175 SCSI bus to hang. Use with caution.
176
177 Linux:
178 The "SCSI target" has to be the name of a device that complies to
179 the Generic SCSI driver API. On a standard Linux installation, these
180 devices are "/dev/sg0", "/dev/sg1" etc. Note that you must have
181 appropriate access rights to these devices and that Generic SCSI
182 support has to be compiled into the kernel.
183
184 FreeBSD:
185 The "SCSI target" has the format "<id>/<lun>" (e.g. "2/0").
186
187 AmigaOS:
188 The "SCSI target" has the format "<device name>/<unit>" (e.g.
189 "scsi.device/2").
190
191 Windows:
192 The "SCSI target" has the format <"Vendor"> <"Model"> (e.g.
193 scsi0 "HP" "CD-Writer+ 7100"). Note the use of quotes.
194
195 screen <video mode>
196
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:
204 win/<width>/<height>
205 8-bit color display in a window of the given size. This is the
206 default.
207 scr/<mode>
208 Full-screen display in BWindowScreen. <mode> is the bit number of
209 the video mode to use (see headers/be/interface/GraphicsDefs.h).
210 E.g. 0 = 640x480x8, 1 = 800x600x8 etc., 10 = 640x480x24,
211 11 = 800x600x24 etc., 18 = 640x480x15, 19 = 800x600x15 etc.
212 15 bit modes are preferable to 16 bit modes (which may show false
213 colors on PowerPC machines).
214 When you run in full-screen mode and switch to another Workspace,
215 Basilisk II is put in "suspend" mode (i.e. MacOS will be frozen).
216
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. 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
228 (8/15/24 bit) depends on the depth of the underlying X11 screen.
229 "width" and "height" specify the maximum width/height to use.
230 Saying "dga/0/0" means "complete screen".
231 dga/<frame buffer name>
232 [if Basilisk II was configured with --enable-fbdev-dga]
233 Full-screen display using the frame buffer device /dev/fb. The color
234 depth (8/15/24 bit) depends on the depth of the underlying X11 screen.
235 The "frame buffer name" is looked up in the "fbdevices" file (whose
236 path can be specified with the "fbdevicefile" prefs item) to determine
237 certain characteristics of the device (doing a "ls -l /dev/fb" should
238 tell you what your frame buffer name is).
239
240 AmigaOS:
241 The "video mode" is one of the following:
242 win/<width>/<height>
243 Black-and-white display in a window of the given size on the
244 Workbench screen. This is the default and will also be used when
245 one of the other options (PIP/screen) fails to open.
246 pip/<width>/<height>
247 15-bit truecolor display in a Picasso96 PIP. This requires
248 Picasso96 as well as a PIP-capable graphics card (e.g. Picasso IV).
249 scr/<hexadecimal mode ID>
250 8/15/24-bit fullscreen display on a Picasso96/CyberGraphX screen with
251 the given mode ID. This requires Picasso96 or CyberGraphX. For 15 and
252 24 bit, the frame buffer format must be QuickDraw-compatible
253 (big-endian, xRGB 1:5:5:5 or xRGB 8:8:8:8). The screen size will be
254 the default size for that mode ID.
255
256 Windows:
257 The "video mode" is one of the following:
258 win/<width>/<height>/<bits per pixel>
259 A refreshed screen mode that uses Windows GDI calls to write to the
260 screen. You may have other windows on top of Basilisk II.
261 dx/<width>/<height>/<bits per pixel>
262 A refreshed DirectX mode (minimum version 5.0). There are ways to
263 install DirectX 5 on NT 4. Some new display adapters work fine even
264 with DirectX 3.
265 fb/<width>/<height>/<bits per pixel>
266 A non-refreshed video mode that works only on NT. It accesses the
267 linear frame buffer directly (best performance of all three modes).
268 Use the hotkey Control-Shift-F12 to switch between Windows and Mac
269 displays. Fast task switch (Alt-Tab) and Explorer start menu
270 (Control-Esc) are disabled, Control-Alt-Del is enabled.
271 <width> and <height> can be either zeroes (uses current screen values),
272 or something else. "win" mode can use almost anything, for other modes
273 there must be a corresponding DirectX mode.
274 <bits> is ignored for mode "win" (uses current screen values).
275 If the mode is "win" and the dimensions are different than the desktop
276 dimensions, windowed mode is used. The window can be moved around by
277 dragging with the right mouse button. This mode remembers window positions
278 separately for different dimensions.
279 The supported values are 8,15,16,24,32. It is possible that some of them
280 do not work for you. In particular, it may be that only one of the
281 two modes, 15 and 16, is suitable for your card. You need to find out
282 the best solution by experimenting.
283 Basilisk II checks what display mode you are currently running and uses
284 that mode. The screen is always full screen. When you switch to another
285 application via Alt-Tab, Basilisk II is put in "snooze" mode (i.e. MacOS
286 is frozen).
287
288 Mac OS X:
289 The "video mode" is one of the following:
290 win/<width>/<height>
291 win/<width>/<height>/<bits per pixel>
292 A refreshed (and buffered) Quartz window.
293 full/<width>/<height>
294 full/<width>/<height>/<bits per pixel>
295 A CGDirectDisplay full screen mode. <bits> can currently be 8, 16 or 32.
296 If not specified, the default is 32. There is currently no way to switch
297 between the Mac OS X and Basilisk II display, but Apple-Option-Escape
298 instantly and safely terminates the Basilisk II program.
299
300 seriala <serial port description>
301
302 This item describes the serial port to be used as Port A (Modem Port)
303 by Basilisk II. If no "seriala" line is given, Basilisk II will try to
304 automatically detect and use installed serial ports. The "serial port
305 description" is a platform-dependant description of a serial port.
306
307 BeOS:
308 Either specify the name of a serial port (e.g. "serial1") or one of
309 "parallel1", "parallel2" or "parallel3". See below for more information
310 about parallel ports.
311
312 Unix:
313 Specify the device name of a serial port (e.g. "/dev/ttyS0") or a
314 parallel "lp" port (e.g. "/dev/lp1"; this only works under Linux and
315 FreeBSD). See below for more information about parallel ports.
316
317 AmigaOS:
318 You have to specify the name of the serial device and the device unit
319 as "<device name>/<unit>" (e.g. "serial.device/0"). If the given device
320 is not compatible to serial.device, Basilisk II will crash. If the
321 device name starts with an asterisk (e.g. "*parallel.device/0"), the
322 device is treated as a parallel.device compatible device. See below for
323 more information about parallel ports.
324
325 Windows:
326 Specify "COM1" or "COM2" for com port 1 or 2, respectively.
327
328 Parallel ports: If you select a parallel port it will look like a serial
329 port to MacOS but Basilisk II will only allow data output and ignore baud
330 rate settings etc. You should be able to get some printers to work with
331 this method (provided that you have the right printer driver, like
332 "Power Print" (see www.gdt.com)).
333
334 serialb <serial port description>
335
336 This item describes the serial port to be used as Port B (Printer Port)
337 by Basilisk II. If no "serialb" line is given, Basilisk II will try to
338 automatically detect and use installed serial ports. The format of the
339 "serial port description" is the same as that of the "seriala" option.
340
341 ether <ethernet card description>
342
343 This item describes the Ethernet card to be used for Ethernet networking
344 by Basilisk II. If no "ether" line is given, Ethernet networking is disabled
345 (although the Ethernet driver of Basilisk II will behave like a "dummy"
346 Ethernet card in this case). If you are using a Mac Classic ROM, Ethernet
347 is not available and this setting is ignored. The "ethernet card description"
348 is a platform-dependant description of an ethernet card.
349
350 General note: To use TCP/IP from MacOS, you should assign a different IP
351 address to the MacOS (entered into the MacOS TCP/IP (or MacTCP) control
352 panel). Otherwise there will be confusion about which operating system will
353 handle incoming packets.
354
355 BeOS:
356 It doesn't matter what you give as "ethernet card description", Basilisk II
357 will always use the first Ethernet card it finds as long an an "ether"
358 line exists (e.g. say "ether yes"). Using Ethernet requires the "sheep_net"
359 Net Server add-on to be installed. The first time you start Basilisk II
360 with Ethernet enabled you will be asked whether it's OK to make the
361 necessary changes to your BeOS network configuration to enable sheep_net.
362
363 Linux:
364 The "ethernet card description" is the name of an Ethernet interface.
365 There are four approaches to networking with Basilisk II:
366
367 1. Direct access to an Ethernet card via the "sheep_net" kernel module.
368 The "ethernet card description" must be the name of a real Ethernet
369 card, e.g. "eth0".
370
371 The sheep_net module is included in the Basilisk II source
372 distribution in the directory "src/Unix/Linux/NetDriver". You have
373 to compile and install the module yourself:
374
375 $ su
376 [enter root password]
377 # make
378 # make dev
379 [this will create a /dev/sheep_net device node; you should give
380 appropriate access rights to the user(s) running Basilisk II]
381 # insmod sheep_net.o
382
383 If you copy the sheep_net.o module to a place where it can be found
384 by the kernel module loader ("/lib/modules/<version>/kernel/drivers/net"
385 for 2.4 kernels) and add the line
386
387 alias char-major-10-198 sheep_net
388
389 to "/etc/modules.conf", the kernel should be able to load the module
390 automatically when Basilisk II is started.
391
392 The sheep_net module will allow you to run all networking protocols
393 under MacOS (TCP/IP, AppleTalk, IPX etc.) but there is no connection
394 between Linux networking and MacOS networking. MacOS will only be
395 able to talk to other machines on the Ethernet, but not to other
396 networks that your Linux box routes (e.g. a second Ethernet or a PPP
397 connection to the Internet).
398
399 2. Putting Basilisk II on a virtual Ethernet via the "ethertap" device.
400 In this case, the "ethernet card description" must be the name
401 of an ethertap interface, e.g. "tap0". It also requires that you
402 configure your kernel to enable routing and ethertap support:
403 under "Networking options", enable "Kernel/User netlink socket" and
404 "Netlink device emulation", under "Network device support", activate
405 "Ethertap network tap". You also have to modify drivers/net/ethertap.c
406 a bit before compiling the new kernel:
407
408 - insert "#define CONFIG_ETHERTAP_MC 1" near the top (after the
409 #include lines)
410 - comment out the line "dev->flags|=IFF_NOARP;" in ethertap_probe()
411
412 Next, see /usr/src/linux/Documentation/networking/ethertap.txt for
413 information on how to set up /dev/tap* device nodes and activate the
414 ethertap interface. Under MacOS, select an IP address that is on the
415 virtual network and set the default gateway to the IP address of the
416 ethertap interface. This approach will let you access all networks
417 that your Linux box has access to (especially, if your Linux box has
418 a dial-up Internet connection and is configured for IP masquerading,
419 you can access the Internet from MacOS). The drawback is that you
420 can only use network protocols that Linux can route, so you have to
421 install and configure netatalk if you want to use AppleTalk. Here is
422 an example /etc/atalk/atalkd.conf for a LAN:
423
424 eth0 -seed -phase 2 -net 1 -addr 1.47 -zone "Ethernet"
425 tap0 -seed -phase 2 -net 2 -addr 2.47 -zone "Basilisknet"
426
427 (the "47" is an arbitrary node number). This will set up a zone
428 "Ethernet" (net 1) for the Ethernet and a zone "Basilisknet" (net 2)
429 for the internal network connection of the ethertap interface.
430 MacOS should automatically recognize the nets and zones upon startup.
431 If you are in an existing AppleTalk network, you should contact
432 your network administrator about the nets and zones you can use
433 (instead of the ones given in the example above).
434
435 3. Access the network through a "tuntap" interface.
436 The "ethernet card description" must be set to "tun".
437
438 TUN/TAP provides packet reception and transmission for user
439 space programs. It can be viewed as a simple Point-to-Point
440 or Ethernet device, which instead of receiving packets from a
441 physical media, receives them from user space program and
442 instead of sending packets via physical media writes them to
443 the user space program.
444
445 Prerequesties:
446 - Make sure the "tun" kernel module is loaded
447 # modprobe tun
448 - Make sure IP Fordwarding is enabled on your system
449 # echo 1 >/proc/sys/net/ipv4/ip_forward
450
451 A virtual network configuration script is required and the
452 default is /usr/local/BasiliskII/tunconfig unless you specify
453 a different file with the "etherconfig" item.
454
455 This script requires you that "sudo" is properly configured
456 so that "/sbin/ifconfig" and "/sbin/iptables" can be executed
457 as root. Otherwise, you can still write a helper script which
458 invokes your favorite program to enhance a user priviledges.
459 e.g. in a KDE environment, kdesu can be used as follows:
460
461 #!/bin/sh
462 exec /usr/bin/kdesu -c /path/to/tunconfig $1 $2
463
464 4. Access the network through the user mode network stack.
465 (the code and this documentation come from QEMU)
466
467 By setting the "ethernet card description" to "slirp",
468 Basilisk II uses a completely user mode network stack (you
469 don't need root priviledges to use the virtual network). The
470 virtual network configuration is the following:
471
472 Basilisk II <------> Firewall/DHCP server <-----> Internet
473 (10.0.2.x) | (10.0.2.2)
474 |
475 ----> DNS server (10.0.2.3)
476 |
477 ----> SMB server (10.0.2.4)
478
479 Basilisk II behaves as if it was behind a firewall which
480 blocks all incoming connections. You can use a DHCP client to
481 automatically configure the network in Basilisk II.
482
483 In order to check that the user mode network is working, you
484 can ping the address 10.0.2.2 and verify that you got an
485 address in the range 10.0.2.x from the Basilisk II virtual
486 DHCP server.
487
488 Note that ping is not supported reliably to the internet as
489 it would require root priviledges. It means you can only ping
490 the local router (10.0.2.2).
491
492 When using the built-in TFTP server, the router is also the
493 TFTP server.
494
495 FreeBSD:
496 The "ethertap" method described above also works under FreeBSD, but since
497 no-one has found the time to write a section for this manual, you're on
498 your own here...
499
500 AmigaOS:
501 You have to specify the name of the SANA-II Ethernet device and the device
502 unit as "<device name>/<unit>" (e.g. "ariadne.device/0"). If the given
503 device is not a SANA-II device, Basilisk II will crash. If the device is
504 not an Ethernet device, Basilisk II will display a warning message and
505 disable Ethernet networking.
506
507 Mac OS X:
508 The "slirp" method described above now seems to work.
509
510
511 See the next item for an alternative way to do networking with Basilisk II.
512
513 udptunnel <"true" or "false">
514
515 Setting this to "true" enables a special network mode in which all network
516 packets sent by MacOS are tunnelled over UDP using the host operating
517 system's native TCP/IP stack. This can only be used to connect computers
518 running Basilisk II (and not, for example, for connecting to the Internet
519 or an AppleShare server running on a real Mac), but it is probably the
520 easiest way to set up a network between two instances of Basilisk II
521 because the UDP tunnelling doesn't require any special kernel modules or
522 network add-ons. It relies on IP broadcasting, however, so its range is
523 limited. It should be fine though for doing a little file sharing or
524 playing Spectre.
525
526 udpport <IP port number>
527
528 This item specifies the IP port number to use for the "UDP Tunnel" mode.
529 The default is 6066.
530
531 rom <ROM file path>
532
533 This item specifies the file name of the Mac ROM file to be used by
534 Basilisk II. If no "rom" line is given, the ROM file has to be named
535 "ROM" and put in the same directory as the Basilisk II executable.
536
537 bootdrive <drive number>
538
539 Specify MacOS drive number of boot volume. "0" (the default) means
540 "boot from first bootable volume".
541
542 bootdriver <driver number>
543
544 Specify MacOS driver number of boot volume. "0" (the default) means
545 "boot from first bootable volume". Use "-62" to boot from CD-ROM.
546
547 ramsize <bytes>
548
549 Allocate "bytes" bytes of RAM for MacOS system and application memory.
550 The value given will be rounded down to the nearest multiple of 1MB.
551 If you are using a Mac Classic ROM, the maximum available value is 4MB
552 and higher values will be ignored. The default is 8MB.
553
554 frameskip <frames to skip>
555
556 For refreshed graphics modes (usually window modes), this specifies
557 how many frames to skip after drawing one frame. Higher values make
558 the video display more responsive but require more processing power.
559 The default is "8". Under Unix/X11, a value of "0" selects a "dynamic"
560 update mode that cuts the display into rectangles and updates each
561 rectangle individually, depending on display changes.
562
563 modelid <MacOS model ID>
564
565 Specifies the Macintosh model ID that Basilisk II should report to MacOS.
566 The default is "5" which corresponds to a Mac IIci. If you want to run
567 MacOS 8, you have to set this to "14" (Quadra 900). Other values are not
568 officially supported and may result in crashes. MacOS versions earlier
569 than 7.5 may only run with the Model ID set to "5". If you are using a Mac
570 Classic ROM, the model is always "Mac Classic" and this setting is
571 ignored.
572
573 nosound <"true" or "false">
574
575 Set this to "true" to disable all sound output. This is useful if the
576 sound takes too much CPU time on your machine or to get rid of warning
577 messages if Basilisk II can't use your audio hardware.
578
579 nocdrom <"true" or "false">
580
581 Set this to "true" to disable Basilisk's built-in CD-ROM driver.
582 The only reason to do this is if you want to use a third-party CD-ROM
583 driver that uses the SCSI Manager. The default is "false".
584
585 nogui <"true" or "false">
586
587 Set this to "true" to disable the GUI preferences editor and GUI
588 error alerts. All errors will then be reported to stdout. The default
589 is "false".
590
591 keyboardtype <keyboard-id>
592
593 Specifies the keyboard type that BasiliskII should report to the MacOS.
594 The default is "5" which is a "Apple Extended Keyboard II (ISO)",
595 but many other numbers are understood by most versions of the MacOS
596 (e.g. 11 is a "Macintosh Plus Keyboard with keypad",
597 13 is a "Apple PowerBook Keyboard (ISO)" )
598
599 For additional information, consult the source.
600
601
602 System-specific configuration
603 -----------------------------
604
605 Unix:
606
607 keycodes <"true" or "false">
608 keycodefile <keycodes file path>
609
610 By default, the X11 event handler in Basilisk II uses KeySyms to
611 translate keyboard event to Mac keycodes. While this method is very
612 compatible and ought to work with all X servers, it only works well
613 if your keyboard has a US layout. If you set "keycodes" to "true",
614 Basilisk II will use raw keycodes instead of KeySyms. The keycode
615 depends only on the physical location of a key on the keyboard and
616 not on the selected keymap. Unfortunately it depends on the X server
617 being used and possibly also on the type of keyboard attached. So
618 Basilisk II needs a table to translate X keycodes to Mac keycodes.
619 This table is read by default from /usr/local/share/BasiliskII/keycodes
620 unless you specify a different file with the "keycodefile" item.
621 A sample keycode file is included with Basilisk II.
622
623 fbdevicefile <fbdevices file path>
624
625 This option specifies the file that contains frame buffer device
626 specifications for the fbdev-DGA video mode (when Basilisk II was
627 configured with --enable-fbdev-dga). The default location of the file
628 is /usr/local/share/BasiliskII/fbdevices. A sample file is included
629 with Basilisk II.
630
631 mousewheelmode <mode>
632
633 If you have a mouse with a wheel, this option specifies whether moving
634 the wheel will be reported to the MacOS as "Page up/down" (mode 0) or
635 "Cursor up/down" (mode 1) keys.
636
637 mousewheellines <number of lines>
638
639 If "mousewheelmode" is set to mode 1 (Cursor up/down), this option sets
640 the number of key events sent to MacOS for each wheel movement (the
641 number of lines to scroll).
642
643 ignoresegv <"true" or "false">
644
645 Set this to "true" to ignore illegal memory accesses. The default
646 is "false". This feature is only implemented on the following
647 platforms: Linux/x86, Linux/ppc, Darwin/ppc.
648
649 dsp <device name>
650 mixer <device name>
651
652 Under Linux and FreeBSD, this specifies the devices to be used for sound
653 output and volume control, respectively. The defaults are "/dev/dsp" and
654 "/dev/mixer".
655
656 AmigaOS:
657
658 sound <sound output description>
659
660 This item specifies what method to use for sound output. The only choice
661 is currently AHI, but you can specify the AHI mode ID to be used. The
662 "sound output description" looks like this:
663
664 ahi/<hexadecimal mode ID>
665
666 scsimemtype <type>
667
668 This item controls the type of memory to use for SCSI buffers. Possible
669 values are:
670 0 Chip memory
671 1 24-bit DMA capable memory
672 2 Any memory
673
674 Be warned that many SCSI host adapters will not work with the "Any memory"
675 setting. Basilisk II has no way of knowing which memory type is supported
676 by the host adapter and setting an unsupported type will result in data
677 corruption.
678
679 Windows:
680
681 noscsi <"true" or "false">
682
683 Completely disables SCSI Manager support when set to "true".
684 Note that currently all SCSI operations are executed synchronously,
685 even if Mac application has requested asynchronous operation. What this
686 means is that the control is not returned to the application until the
687 command is completely finished. Normally this is not an issue, but when a
688 CDR/CDRW is closed or erased the burner program typically wants to wait in
689 some progress dialog the result may be that the application reports a
690 time-out error, but the operation completes all right anyway.
691
692 nofloppyboot <"true" or "false">
693
694 Set this to "true" to disable booting from a floppy.
695
696 replacescsi <"Vendor1"> <"Model1"> <"Vendor2"> <"Model2">
697
698 This command tricks the Mac to believe that you have a SCSI device Model2
699 from vendor Vendor2, although your real hardware is Model1 from Vendor1.
700 This is very useful since many devices have almost identical ATAPI and SCSI
701 versions of their hardware, and MacOS applications usually support the SCSI
702 version only. The example below is typical:
703
704 replacescsi "HP" "CD-Writer+ 7100" "PHILIPS" "CDD3600"
705
706 Note the use of quotes.
707
708 rightmouse <0/1>
709
710 Defines what the right mouse button is used for. The default values of 0
711 means that it is used to move windowed mode BasiliskII screen.
712 Value 1 sends a combination Control and mouse click to the MacOS.
713 This may be useful under OS versions 8 and above.
714
715 keyboardfile <path>
716
717 Defines the path of the customized keyboard code file.
718
719 pollmedia <"true" or "false">
720
721 If true (default), tries to automatically detect new media.
722 Applies to all "floppy", "cd" or "disk" removable media except
723 1.44 MB floppies. May cause modest slow down. If unchecked,
724 use Ctrl-Shift-F11 to manually mount new media.
725 If you have auto-insert notification (AIN) enabled, you may turn this
726 option off. Note that some CD related software require AIN,
727 and some other need it to be turned off. Consult the documentation
728 of your CD software to learn which one is optimal for you.
729
730 framesleepticks <milliseconds>
731
732 The amount of time between video frames.
733
734 showfps <true/false>
735
736 If true, the real frame rate is displayed.
737
738 stickymenu <true/false>
739
740 If true, the main menu bar is kept open even after the mouse button is
741 released, under all OS versions (OS 8 has this feature already). There
742 are extensions to do the same thing, but it's faster to handle this in
743 native code. Default is "true".
744
745 ntdx5hack <"true" or "false">
746
747 You may need this on NT if your display adapter driver has a bug in
748 DirectX palette support. Black and white are reversed. It fixes the
749 palette issue by using GDI palette instead of D3D palette. Default is
750 false.
751
752
753 JIT-specific configuration
754 --------------------------
755
756 A Just-In-Time (JIT) translation engine is available for x86. This is
757 aimed at translating 68040 instructions to native equivalent code
758 sequences, thus providing faster emulation speeds.
759
760 jit <"true" or "false">
761
762 Set this to "true" to enable the JIT compiler. Default value is
763 "true" if the JIT compiler was compiled in. Besides, this is
764 effective only if Basilisk II is configured to emulate a 68040.
765
766 jitfpu <"true" or "false">
767
768 Set this to "true" to enable translation of floating-point (FPU)
769 instructions. Default is "true".
770
771 jitcachesize <size>
772
773 Allocate "size" kilobytes of RAM for the translation cache. The
774 value given will be rounded down to the nearest multiple of a page
775 size. Minimal value is "2048" (2MB). Default value is "8192" (8MB).
776
777 jitlazyflush <"true" or "false">
778
779 Set this to "true" to enable lazy invalidation of the translation
780 cache. This is always recommended as it usually makes the system
781 more responsive and faster, especially while running MacOS
782 8.X. Default value is "true".
783
784 jitdebug <"true" or "false">
785
786 Set this to "true" to enable the JIT debugger. This requires a
787 build of Basilisk II with the cxmon debugger. Default is "false".
788
789
790 Usage
791 -----
792
793 Quitting:
794 The right way to quit Basilisk II is to select the "Shut Down" menu item
795 from the Finder's "Special" menu. You should not kill it from the shell
796 unless it hangs. Under Unix, pressing "Esc" while holding the Ctrl key will
797 also quit Basilisk II (in case you are using it in DGA mode and it crashed).
798 Under Windows, try Alt-F4 (or Control-Alt-Del to log off and back on again
799 if it crashes really badly).
800
801 Suspending:
802 The Unix version of Basilisk II can be suspended while running in DGA mode
803 by pressing "Tab" while holding the Ctrl key. Pressing "Space" in the
804 "suspended" window will resume the emulation. Under BeOS, switching to
805 a different Workspace when BasiliskII is in full-screen mode will also
806 suspend the emulation.
807
808 Keyboard:
809 On PC-style keyboards, "Alt" is the Mac "Command" key, while the "Windows"
810 key is the Mac "Option" key.
811
812 Mouse:
813 Under Unix, pressing Ctrl-F5 while the Basilisk II window is active will
814 grab the mouse. This is needed for compatibility with some MacOS programs,
815 especially games such as flight simulators. Press Ctrl-F5 again to return
816 to normal mouse operation.
817
818 Floppy:
819 Basilisk II can only handle 1.44MB MFM floppies. Depending on your platform,
820 floppy disk changes might not be detected automatically. Under Unix, press
821 Ctrl-F1 to mount a floppy. Under BeOS, select the appropriate "Mount" menu
822 item or press Ctrl-F1 to mount a floppy. Under Windows, press Ctrl-Shift-F11.
823
824 HFS partitions:
825 Having HFS partitions mounted for read-write access under Basilisk II while
826 they are also mounted on the host OS will most likely result in volume
827 corruption and data loss. Unmount your HFS volumes before starting
828 Basilisk II.
829
830 ZIP drives:
831 Iomega ZIP disks can be mounted either with the "disk" prefs item or (on
832 platforms that support the SCSI Manager emulation of Basilisk II) by
833 installing the IomegaWare on the Mac side. Do not use both ways
834 simultaneously!
835
836 Hardfiles:
837 In addition to plain images of HFS volumes, Basilisk II can also handle
838 some types of Mac "disk image" files, as long as they are uncompressed
839 and unencoded.
840
841 Mac Classic emulation:
842 Sound output and Ethernet are not supported if you are using a Mac Classic
843 ROM. Also, the video display is fixed to 512x342 in monochrome. The AmigaOS
844 and BeOS/PPC versions of Basilisk II cannot do Mac Classic emulation.
845
846 Video resolution switching:
847 Run-time switching of video resolutions requires the Display Manager. This
848 is included in MacOS versions 7.6 and above, and available as a system
849 extension for earlier MacOS versions as a free download from ftp.apple.com
850 (look for "Display Software 2.x"). Click on "Options..." in the "Monitors"
851 control panel to select the resolution.
852
853 Sound output:
854 Sound output under Basilisk II requires Sound Manager 3.0 or later. This
855 is included in MacOS versions 7.5 and above, and available as a system
856 extension for earlier MacOS versions as a free download from ftp.apple.com.
857 Sample rate, bit resolution and mono/stereo can be selected in the Sound
858 control panel (section "Sound Out").
859
860 Ethernet:
861 Basilisk II supports all Ethernet protocols. Running a protocol under
862 Basilisk II that already runs within the host operating system on the same
863 network card (e.g. running MacTCP under Basilisk II on a BeOS machine) may
864 or may not work (generally, it should work, but some specific things like
865 "ping" may not). If you have problems with FTP, try setting the FTP client
866 to passive mode.
867
868 LocalTalk:
869 LocalTalk is not supported by Basilisk II. There is no way of getting
870 LocalTalk to work with the serial drivers of Basilisk II. Any attempt to
871 activate LocalTalk will either result in a crash or revert to Ethernet.
872
873 Serial:
874 You can use the serial ports in Basilisk II to connect to the Internet
875 with a modem and the "MacPPP" or "Open Transport/PPP" software.
876
877
878 Technical Documentation
879 -----------------------
880
881 Please see the included file "TECH" for a technical overview of the emulator.
882
883
884 Acknowledgements
885 ----------------
886
887 Contributions by (in alphabetical order):
888 - Orlando Bassotto <future@powercube.mediabit.net>: FreeBSD support
889 - Gwenolé Beauchesne <gb@dial.oleane.com>: SPARC assembly optimizations,
890 lots of work on the Unix video code, fixes and improvements to the
891 JIT compiler
892 - Marc Chabanas <Marc.Chabanas@france.sun.com>: Solaris sound support
893 - Marc Hellwig <Marc.Hellwig@uni-mainz.de>: audio output, BeOS video code
894 and networking
895 - Bill Huey <billh@mag.ucsd.edu>: 15/16 bit DGA and 15/16/32 bit X11
896 window support
897 - Brian J. Johnson <bjohnson@sgi.com>: IRIX support
898 - Jürgen Lachmann <juergen_lachmann@t-online.de>: AmigaOS CyberGraphX support
899 - Samuel Lander <blair_sp@hotmail.com>: tile-based window refresh code
900 - David Lawrence <davidl@jlab.org>: incremental window refresh code
901 - Bernie Meyer <bmeyer@csse.monash.edu.au>: original UAE-JIT code
902 - Nigel Pearson <nigel@ind.tansu.com.au>: Mac OS X port
903 - Lauri Pesonen <lpesonen@nic.fi>: Windows NT port
904 - Bernd Schmidt <crux@pool.informatik.rwth-aachen.de>: UAE 68k emulation
905 - Michael Z. Sliczniak <msliczniak@comcast.net>: Mach memory fault recovery
906 - and others...
907
908 Special thanks to:
909 - Bernd Schmidt for letting me use his UAE 68k emulation
910 - Daniel Bobbert who printed dozens of pages from the THINK Reference for
911 me years ago
912 - All ShapeShifter and SheepShaver users and beta testers
913 - Apple Computer Inc., who made writing a Macintosh emulator a child's play
914
915
916 Bug reports
917 -----------
918
919 You found a bug? Well, use the source, fix it and send the fix to
920 <Christian.Bauer@uni-mainz.de>
921 for inclusion in the next release of Basilisk II.
922
923 If you don't have a fix, you should post a bug report using the Source Forge
924 bug tracker, supplying as much information as possible (operating system and
925 versions of Basilisk II and MacOS being used, relevant hardware information,
926 the exact steps to reproduce the bug, etc.):
927 http://sourceforge.net/tracker/?group_id=2123&atid=102123
928
929 I also strongly suggest reading this before posting a bug report:
930 http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
931
932
933 Author
934 ------
935
936 You can contact me at <Christian.Bauer@uni-mainz.de>, but please don't do
937 so unless absolutely necessary. I'm maintaining Basilisk II in my spare
938 time and am not able to provide technical support for everyone. If you have
939 questions, consider posting them to one of the support forums mentioned
940 below.
941
942 You are encouraged to contact me personally when
943 - you have bug fixes or small enhancements for the code
944 - you want to port Basilisk II to another platform
945 - you want to discuss technical issues
946 - you intend to make major changes to the source; you might be working on
947 something that I have already done, or I may have different ideas about
948 the Right Way to do it
949
950 There is no point in sending me questions about
951 - ROM files and how/where to get them
952 - versions of Basilisk II that run on operating systems other than Unix,
953 BeOS and AmigaOS. If you are using any other operating system, there's
954 no point in asking me how to to X or why Y doesn't work because I won't
955 know either. Instead, you should look in the "Acknowledgements" section
956 of this manual to find the person responsible. For example, if your
957 question is specific to the Windows operating system, ask Lauri Pesonen.
958 I don't have Windows and can't answer your questions and I'm too lazy to
959 forward mail to Lauri myself. In any case, it would probably be better
960 to post your questions to a public forum as it will get a much wider
961 audience there.
962
963
964 Support
965 -------
966
967 The official Basilisk II home page is at
968 http://www.uni-mainz.de/~bauec002/B2Main.html
969
970 The Basilisk II project page on SourceForge is at
971 http://sourceforge.net/projects/basilisk/
972
973 If you have problems, you may want to visit the Basilisk II forums:
974 http://sourceforge.net/forum/?group_id=2123
975
976 There is also a mailing list for Basilisk II users:
977 http://lists.sourceforge.net/lists/listinfo/basilisk-user
978
979 And another mailing list for Basilisk II developers:
980 http://lists.sourceforge.net/lists/listinfo/basilisk-devel
981
982 Some general advice about asking technical support questions can be found at
983 http://www.catb.org/~esr/faqs/smart-questions.html
984
985 Keeping this in mind will greatly increase your chances of getting a useful
986 answer.
987
988
989 History
990 -------
991
992 Please consult the file "ChangeLog" for the release history.
993
994
995 Christian Bauer
996 <Christian.Bauer@uni-mainz.de>