forked from jmthompson/xgs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
INSTALL.txt
353 lines (266 loc) · 13 KB
/
INSTALL.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
XGS: The Portable Apple IIGS(tm) emulator
Version 0.50 -- May 1st, 1997
Written and (C) 1996-97 by Joshua M. Thompson
"Baby's got a master plan...a foolproof master plan." -- Fluke, 'Atom Bomb'
-----------
LEGAL STUFF
-----------
You may distribute this program so long as you do not sell it (selling a CD
of freeware and shareware does not qualify as selling it). All I ask is that
you keep this file intact, and that you include the source code.
Many thanks to Kent Dickey ([email protected]). Kent not only gave me
a hell of a lot of nice ideas (like the memory handling subsystem for the
slow memory banks), but he even donated code to the project. Thanks, Kent!
I'd also like to thank anyone who has done work on porting XGS to non-Unix
platforms. Their names and email addresses are listed in the PORTS file in
the docs/ subdirectory.
Apple, IIGS, Apple IIGS, and GS/OS are registered trademarks of Apple
Computer, Inc. All rights reserved.
------------
CONTACT INFO
------------
I can be reached via Internet email as [email protected], and sometimes on
IRC (EFnet) as LrdRayden.
The latest versions of this code will be made available through the XGS
home page. The URL is "http://www.optera.com/~invid/emulators/XGS/".
There is also a mailing list for discussing XGS issues. You can subscribe
by sending mail to "[email protected]" and including the words
"subscribe xgs-list" on a line by itself in the body of the letter. I
strongly suggest you subscribe to it if you're going to use XGS.
------------
INTRODUCTION
------------
XGS is a program to emulate an Apple IIGS. This is a beta version; many
features are not implemented yet, and many others don't work exactly like
they should.
The following features are currently implemented:
o CPU emulation
o Memory map emulation
o All known video modes
o Ensoniq sound
o ADB keyboard
o ADB mouse
o Joystick (follows mouse movement)
o Clock chip
o Battery RAM
o IWM hardware emulation for drives in slots 5 and 6 (3.5" / 5.25")
o A 14-unit Extended SmartPort device in slot 5
The following features are NOT currently implemented:
o Serial ports
o True ADB hardware emulation
o Many, many other minor things.
-------------------
SYSTEM REQUIREMENTS
-------------------
o A 90 MHz Pentium or better (it will run on slower, but it'll be virtually
unusable.)
o A compatible operating system. Ports are currently available for Unix
systems running an 8-bit X server, Windows 95/NT + DirectX, and MacOS 7.x.
o A copy of the ROMs from a ROM 01 or 03 Apple IIGS (see "How to Use It" below).
----------------------
HOW TO COMPILE (WIN32)
----------------------
Compiling for Win32 is currently supported only on Microsoft Visual C++
Version 4.0 and later. The files in arch/win32/vcplus comprise a Visual
C++ 4.0 project workspace for building the Win32 port of XGS. To use
them you will need to copy them into the main level of the XGS source tree.
The kit assumes you have the DirectX 2 or DirectX 3 SDK installed in
C:\DXSDK. If you have installed it somewhere else you will need to change
the library and include search paths to point to your DirectX includes and
link libraries.
---------------------
HOW TO COMPILE (UNIX)
---------------------
Please read this entire section through at least once before you do anything.
XGS uses the GNU autoconf packages to make configuration quick and painless.
Simply type "./configure" and XGS will (on most systems) configure itself. You
may want to glance over the Makefile and config.h file after doing this, just
to make sure they are correct.
Once XGS is configured, type "make depend" to generate the Makefile
dependancies. You can then type "make install" to build and install XGS. The
default install location is under /usr/local (/usr/local/bin/xgs for the binary
and /usr/local/share/xgs for the fonts and other support files). You can change
this with the --prefix option to configure.
The default configuration generated by the configure program will build a
version of XGS for SVGAlib without sound support. Other configurations are
possible by passing additional parameters to the configure command:
--with-x Enable X11 support. If you _don't_ select this, then
an svgalib version of XGS will be built instead.
--with-oss-sound Enable sound support for systems supporting the Open
Sound System API (the "/dev/dsp" device; Linux and
FreeBSD are in this category).
--with-sparc-sound Enable sound support for systems supporting the
"/dev/audio" device, such as SunOS 4.x and Solaris.
--with-mit-shm Enable support for the MIT shared memory extensions
to X. XGS will then use shared memory to talk to the
X server whenever it can.
--with-debug Enable debugging support, such as the trace mode in
the CPU emulator. You can leave this disabled unless
you're trying to track down a problem in XGS.
There are also some useful support utilities included with XGS. To build and
install them, type "make install-utils". They will be installed in the same
directory as the XGS binary.
-------------
HOW TO USE IT
-------------
You will need a ROM image file to make XGS run. You can get the ROMs from a
IIGS by saving them out in 32 KB chunks in AppleSoft BASIC. Boot a ProDOS 8
disk and get into BASIC, then do the following:
**** For a ROM 01 machine: ****
] CALL -151
* 00/800<FE/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000
* 00/800<FE/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$8000
* 00/800<FF/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$10000
* 00/800<FF/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$18000
**** For a ROM 03 machine: ****
] CALL -151
* 00/800<FC/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000
* 00/800<FC/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$8000
* 00/800<FD/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$10000
* 00/800<FD/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$18000
* 00/800<FE/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$20000
* 00/800<FE/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$28000
* 00/800<FF/0000.7FFFM
* BSAVE XGS.ROM,A$800,L$8000,B$30000
* 00/800<FF/8000.FFFFM
* BSAVE XGS.ROM,A$800,L$8000,B$38000
The resulting XGS.ROM file should be exactly 131,072 bytes long for a ROM 01
image or 262,144 bytes long for a ROM 03 image. If it isn't then you messed up
somewhere...go back and try again.
You now have to get the file over to your machine. If you've got a Mac this is
easy; the Macintosh can read the IIGS floppy directly. Otherwise you're going
to have to use a serial cable or modem to transfer the file from the IIGS to
your machine.
If you don't have a real IIGS to get the ROMs from then you're on your own.
Apple owns the copyrights on the ROMs, so I can't legally give you a copy (nor
can anyone else). As a result you're probably not going to find them on an FTP
site anywhere.
I will repeat this one more time:
*** I CANNOT (AND WILL NOT) GIVE YOU A COPY OF THE IIGS ROM!! ***
*** SO DON'T SEND ME MAIL AND AND ME ABOUT IT. IT WON'T HELP. ***
Now that that's out of the way, let's move on to actually running the program.
The following support files must be in the XGS lib directory (normally this
will be /usr/local/share/xgs on Unix or C:\XGS on Windows):
xgs40.fnt The Apple II 40-column screen font for US systems
xgs80.fnt The Apple II 80-column screen font for US systems
xgs40fr.fnt The Apple II 40-column screen font for French systems (*)
xgs80fr.fnt The Apple II 80-column screen font for French systems (*)
xgs.rom The ROM image
xgs.ram The battery ram save file
(*) Move these files to xgs40.fnt and xgs80.fnt if you want to use them. They
are only needed if you want the IIgs to display the special French
characters.
If everything looks OK then start XGS. For Unix systems, just type "xgs" and
hit RETURN; for Windows systems double-click on the XGS program icon.
If everything goes well, you should see the virtual IIGS boot and dump you
into AppleSoft BASIC (because you don't have any boot disk image yet -- more
on that later). If you don't get the BASIC screen then you have a problem;
refer to the "Troubleshooting" section below.
For the most part, the keyboard is mapped one-to-one with a IIGS keyboard.
However, there are certain exceptions that are designed to get around
limitations of the various systems on which IIGS runs, as well as special
key sequences to control XGS itself. The exceptions are listed below:
F1 (Win32 only). This is the IIGS escape key.
F3 (Win32 only). This is the IIGS command key.
F4 (Win32 only). This is the IIGS option key.
F5 Toggle joystick emulation on/off. Note that
you can't turn on joystick emulation unless
mouse emulation is off!
F6 Toggle mouse emulation on/off. Note that you
can't turn on mouse emulation unless joystick
emulation is off!
F12 (Win32 only). This is the IIGS keypad Enter key.
This is temporary until the Win32 port supports
keypad keys (The X11 port already does this).
Left Alt (X11 only). This is the IIGS command key.
Right Alt (X11 only). This is the IIGS option key.
Control-End Quits XGS.
Control-Home Sends a Control-Reset to the emulator.
Control-PageUp Turns on trace mode (if you conmpiled
with debugging support). Note that on
Windows the trace output goes into the
BOOTLOG.TXT file.
Control-PageDown Turns off trace mode (if you compiled
with debugging support).
Pause Sends a Non-Maskable Interrupt (NMI) to
the emulator. This is a guaranteed way
to get into the monitor and poke around.
This also dumps a copy of banks $00 and $01
into banks $E8 and $E9 for debugging
purposes.
Whenever joystick or mouse emulation is on, the pointer is confined to the XGS
window. Turn off the joystick or mouse emulation to move the pointer to other
windows.
The default for the emulator is to emulate a 2 MB machine. To change this, add
the "-ram #" option to the xgs command line, where # is the number of megabytes
to emulate (must be between 1 and 8).
To disable sound emulation (which signifigantly speeds up XGS), start XGS with
the "-nosound" command line option.
-----------------
USING DISK IMAGES
-----------------
XGS allows you to mount files as Apple IIGS disks. These files (called disk
images) must be in a specific format for XGS to recognize them.
For ports that have a GUI interface (such as XGS-Mac and XGS-Win32) you can
use the program's interface to mount images at boot time. Otherwise, you can
use the following command line options when you start XGS:
-s5d1 <image> Mounts an image on Slot 5, Drive 1 (the first 3.5"
disk drive). The image must be exactly 1600 ProDOS
blocks in size or it will not be loaded.
-s5d2 <image> Same as above, but mounts the image on Slot 5, Drive 2.
-s6d1 <image> Mounts an image on Slot 6, Drive 1 (the first 5.25"
disk drive). The imge must be exactly 280 ProDOS blocks
in size or it will not be loaded.
-s6d2 <image> Same as above, but mounts the image on Slot 6, Drive 2.
-smptX <image> Mounts an image as device number X (where X is between
0 and 13) on the SmartPort in slot 7. Device #0 is the
boot device and is mapped to Slot 7, Drive 1. The
remaining devices are mapped to additional slot/drive
combinations under ProDOS 8 v2.0 and higher (under
GS/OS they will be directly accessible).
XGS supports several image types:
"2IMG" Universal Image Format ("file.2mg")
Raw ProDOS-order images ("file.po" or "file.raw")
Raw DOS 3.3-order 5.25" images ("file.do" or "file.dsk")
Pre-nibblized 5.25" disk images ("file.nib")
Macintosh DiskCopy 4.2 images ("file.dc")
Note that the only format which XGS can reliably detect is the 2IMG format;
all other formats are detected by making a guess based on the filename
extension. In other words, DiskCopy images MUST end in ".dc", nibblized images
MUST end in ".nib", etc. The extensions which XGS uses are the same as are
commonly used for images distributed via the Internet, so this should not be
a problem.
XGS comes with two utilities to make dealing with images easier. They are:
imgconv <source file> <destination file>
If you have any images in the old proprietary XGS format, this will
convert them to the new universal 2IMG format. The proprietary format
is no longer supported by XGS so you _will_ need to convert such
images in order to use them.
imgutil
This is a universal utility for working with 2IMG images. It lets you
create new images, lock/unlock images, and convert other images formats
into 2IMG images.
---------------
TROUBLESHOOTING
---------------
If the XGS screen doesn't appear, then the emulator probably couldn't start,
and you should read the startup output to figure out why. You probably have a
missing file. On Windows systems, the startup output is saved into the file
BOOTLOG.TXT in the same directory as XGS.EXE.
If the screen appears and then disappears, then the emulator probably crashed.
Mail me a bug report. If you're really ambitious you can even try to debug it
yourself.
If XGS crashes while running a certain piece of software, see if you can
reproduce the crash and tell me how you did it. Even better, try to send
me a snippit of XGS debug output that shows the instruction that caused the
crash, along with a hundred or so lines preceding the crash.