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> |