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