ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/cebix/BasiliskII/TECH
Revision: 1.3
Committed: 2000-04-11T11:44:18Z (24 years, 6 months ago) by cebix
Branch: MAIN
Changes since 1.2: +1 -1 lines
Log Message:
- fixed typo

File Contents

# Content
1 BASILISK II TECHNICAL MANUAL
2 ============================
3
4 0. Table of Contents
5 --------------------
6
7 1. Introduction
8 2. Modes of operation
9 3. Memory access
10 4. Calling native routines from 68k mode and vice-versa
11 5. Interrupts
12 6. Parts of Basilisk II
13 7. Porting Basilisk II
14
15 1. Introduction
16 ---------------
17
18 Basilisk II can emulate two kind of Macs, depending on the ROM being used:
19
20 1. A Mac Classic
21 2. A Mac II series computer ("Mac II series" here means all 68020/30/40
22 based Macs with 32-bit clean ROMs (this excludes the original Mac II,
23 the IIx/IIcx and the SE/030), except PowerBooks; in the following,
24 "Mac II" is used as an abbreviation of "Mac II series computer", as
25 defined above)
26
27 More precisely spoken, MacOS under Basilisk II behaves like on a Mac Classic
28 or Mac II because, apart from the CPU, the RAM and the ROM, absolutely no Mac
29 hardware is emulated. Rather, Basilisk II provides replacements (usually in
30 the form of MacOS drivers) for the parts of MacOS that access hardware. As
31 there are practically no Mac applications that access hardware directly (this
32 is also due to the fact that the hardware of different Mac models is sometimes
33 as different as, say, the hardware of an Atari ST and an Amiga 500), both the
34 compatibility and speed of this approach are very high.
35
36 2. Modes of operation
37 ---------------------
38
39 Basilisk II is designed to run on many different hardware platforms and on
40 many different operating systems. To provide optimal performance under all
41 environments, it can run in three different modes, depending on the features
42 of the underlying environment (the modes are selected with the REAL_ADDRESSING
43 and EMULATED_68K defines in "sysdeps.h"):
44
45 1. Emulated CPU, "virtual" addressing (EMULATED_68K = 1, REAL_ADDRESSING = 0):
46 This mode is designed for non-68k or little-endian systems or systems that
47 don't allow accessing RAM at 0x0000..0x1fff. This is also the only mode that
48 allows 24-bit addressing, and thus the only mode that allows Mac Classic
49 emulation. The 68k processor is emulated with the UAE CPU engine and two
50 memory areas are allocated for Mac RAM and ROM. The memory map seen by the
51 emulated CPU and the host CPU are different. Mac RAM starts at address 0
52 for the emulated 68k, but it may start at a different address for the host
53 CPU. All memory accesses of the CPU emulation go through memory access
54 functions (do_get_mem_long() etc.) that translate addresses. This slows
55 down the emulator, of course.
56
57 2. Emulated CPU, "real" addressing (EMULATED_68K = 1, REAL_ADDRESSING = 1):
58 This mode is intended for big-endian non-68k systems that do allow access to
59 RAM at 0x0000..0x1fff. As in the virtual addressing mode, the 68k processor
60 is emulated with the UAE CPU engine and two areas are set up for RAM and ROM
61 but the emulated CPU lives in the same address space as the host CPU.
62 This means that if something is located at a certain address for the 68k,
63 it is located at the exact same address for the host CPU. Mac addresses
64 and host addresses are the same. The memory accesses of the CPU emulation
65 still go through access functions but the address translation is no longer
66 needed, and if the host CPU uses big-endian data layout and can handle
67 unaligned accesses like the 68k, the memory access functions are replaced
68 by direct, inlined memory accesses, making for the fastest possible speed
69 of the emulator.
70 A usual consequence of the real addressing mode is that the Mac RAM doesn't
71 any longer begin at address 0 for the Mac and that the Mac ROM also is not
72 located where it usually is on a real Mac. But as the Mac ROM is relocatable
73 and the available RAM is defined for MacOS by the start of the system zone
74 (which is relocated to the start of the allocated RAM area) and the MemTop
75 variable (which is also set correctly) this is not a problem. There is,
76 however, one RAM area that must lie in a certain address range. This area
77 contains the Mac "Low Memory Globals" which (on a Mac II) are located at
78 0x0000..0x1fff and which cannot be moved to a different address range.
79 The Low Memory Globals constitute of many important MacOS and application
80 global variables (e.g. the above mentioned "MemTop" variable which is
81 located at 0x0108). For the real addressing mode to work, the host CPU
82 needs access to 0x0000..0x1fff. Under most operating systems, this is a
83 big problem. On some systems, patches (like PrepareEmul on the Amiga or
84 the sheep_driver under BeOS) can be installed to "open up" this area. On
85 other systems, it might be possible to use access exception handlers to
86 emulate accesses to this area. But if the Low Memory Globals area cannot
87 be made available, using the real addressing mode is not possible.
88
89 3. Native CPU (EMULATED_68K = 0, this also requires REAL_ADDRESSING = 1)
90 This mode is designed for systems that use a 68k (68020 or better) processor
91 as host CPU and is the technically most difficult mode to handle. The Mac
92 CPU is no longer emulated (the UAE CPU emulation is not needed) but MacOS
93 and Mac applications run natively on the existing 68k CPU. This means that
94 the emulator has its maximum possible speed (very close to that of a real
95 Mac with the same CPU). As there is no control over the memory accesses of
96 the CPU, real addressing mode is implied, and so the Low Memory area must
97 be accessible (an MMU might be used to set up different address spaces for
98 the Mac and the host, but this is not implemented in Basilisk II). The
99 native CPU mode has some possible pitfalls that might make its
100 implementation difficult on some systems:
101 a) Implied real addressing (this also means that Mac programs that go out
102 of control can crash the emulator or the whole system)
103 b) MacOS and Mac applications assume that they always run in supervisor
104 mode (more precisely, they assume that they can safely use certain
105 priviledged instructions, mostly for interrupt control). So either
106 the whole emulator has to be run in supervisor mode (which usually is
107 not possible on multitasking systems) or priviledged instructions have
108 to be trapped and emulated. The Amiga version of Basilisk II uses the
109 latter approach (it is possible to run supervisor mode tasks under
110 the AmigaOS multitasking kernel (ShapeShifter does this) but it
111 requires modifying the task switcher and makes the emulator more
112 unstable).
113 c) On multitasking systems, interrupts can usually not be handled as on
114 a real Mac (or with the UAE CPU). The interrupt levels of the host
115 will not be the same as on a Mac, and the operating systems might not
116 allow installing hardware interrupt handlers or the interrupt handlers
117 might have different stack frames and run-time environments than 68k
118 hardware interrupts. The usual solution is to use some sort of software
119 interrupts or signals to interrupt the main emulation process and to
120 manually call the Mac 68k interrupt handler with a faked stack frame.
121 d) 68060 systems are a small problem because there is no Mac that ever
122 used the 68060 and MacOS doesn't know about this processor. Basilisk II
123 reports the 68060 as being a 68040 to the MacOS and patches some places
124 where MacOS makes use of certain 68040-specific features such as the
125 FPU state frame layout or the PTEST instruction. Also, Basilisk II
126 requires that all of the Motorola support software for the 68060 to
127 emulate missing FPU and integer instructions and addressing modes is
128 provided by the host operating system (this also applies to the 68040).
129 e) The "EMUL_OP" mechanism described below requires the interception and
130 handling of certain emulator-defined instructions.
131
132 3. Memory access
133 ----------------
134
135 There is often a need to access Mac RAM and ROM inside the emulator. As
136 Basilisk II may run in "real" or "virtual" addressing mode on many different
137 architectures, big-endian or little-endian, certain platform-independent
138 data types and functions are provided:
139
140 a) "sysdeps.h" defines the types int8, uint8, int16, uint16, int32 and uint32
141 for numeric quantities of a certain signedness and bit length
142 b) "cpu_emulation.h" defines the ReadMacInt*() and WriteMacInt*() functions
143 which should always be used to read from or write to Mac RAM or ROM
144 c) "cpu_emulation.h" also defines the Mac2HostAddr() function that translates
145 a Mac memory address to a (uint8 *) in host address space. This allows you
146 to access larger chunks of Mac memory directly, without going through the
147 read/write functions for every access. But doing so you have to perform
148 any needed endianess conversion of the data yourself by using the ntohs()
149 etc. macros which are available on most systems or defined in "sysdeps.h".
150
151 4. Calling native routines from 68k mode and vice-versa
152 -------------------------------------------------------
153
154 An emulator like Basilisk II requires two kinds of cross-platform function
155 calls:
156
157 a) Calling a native routine from the Mac 68k context
158 b) Calling a Mac 68k routine from the native context
159
160 Situation a) arises in nearly all Basilisk drivers and system patches while
161 case b) is needed for the invocation of Mac call-back or interrupt routines.
162 Basilisk II tries to solve both problems in a way that provides the same
163 interface whether it is running on a 68k or a non-68k system.
164
165 4.1. The EMUL_OP mechanism
166 --------------------------
167
168 Calling native routines from the Mac 68k context requires breaking out of the
169 68k emulator or interrupting the current instruction flow and is done via
170 unimplemented 68k opcodes (called "EMUL_OP" opcodes). Basilisk II uses opcodes
171 of the form 0x71xx (these are invalid MOVEQ opcodes) which are defined in
172 "emul_op.h". When such an opcode is encountered, whether by the emulated CPU
173 or a real 68k, the execution is interrupted, all CPU registers saved and the
174 EmulOp() function from "emul_op.cpp" is called. EmulOp() decides which opcode
175 caused the interrupt and performs the required actions (mostly by calling other
176 emulator routines). The EMUL_OP handler routines have access to nearly all of
177 the 68k user mode registers (exceptions being the PC, A7 and SR). So the
178 EMUL_OP opcodes can be thought of as extensions to the 68k instruction set.
179 Some of these opcodes are used to implement ROM or resource patches because
180 they only occupy 2 bytes and there is sometimes not more room for a patch.
181
182 4.2. Execute68k()
183 -----------------
184
185 "cpu_emulation.h" declares the functions Execute68k() and Execute68kTrap() to
186 call Mac 68k routines or MacOS system traps from inside an EMUL_OP handler
187 routine. They allow setting all 68k user mode registers (except PC and SR)
188 before the call and examining all register contents after the call has
189 returned. EMUL_OP and Execute68k() may be nested, i.e. a routine called with
190 Execute68k() may contain EMUL_OP opcodes and the EMUL_OP handlers may in turn
191 call Execute68k() again.
192
193 5. Interrupts
194 -------------
195
196 Various parts of Basilisk II (such as the Time Manager and the serial driver)
197 need an interrupt facility to trigger asynchronous events. The MacOS uses
198 different 68k interrupt levels for different events, but for simplicity
199 Basilisk II only uses level 1 and does it's own interrupt dispatching. The
200 "InterruptFlags" contains a bit mask of the pending interrupts. These are the
201 currently defined interrupt sources (see main.h):
202
203 INTFLAG_60HZ - MacOS 60Hz interrupt (unlike a real Mac, we also handle
204 VBL interrupts, ADB events and the Time Manager here)
205 INTFLAG_SERIAL - Interrupt for serial driver I/O completion
206 INTFLAG_ETHER - Interrupt for Ethernet driver I/O completion and packet
207 reception
208 INTFLAG_AUDIO - Interrupt for audio "next block" requests
209 INTFLAG_TIMER - Reserved for a future implementation of a more precise
210 Time Manager (currently not used)
211
212 An interrupt is triggered by calling SetInterruptFlag() with the desired
213 interrupt flag constant and then TriggerInterrupt(). When the UAE 68k
214 emulator is used, this will signal a hardware interrupt to the emulated 680x0.
215 On a native 68k machine, some other method for interrupting the MacOS thread
216 has to be used (e.g. on AmigaOS, a signal exception is used). Care has to be
217 taken because with the UAE CPU, the interrupt will only occur when Basilisk II
218 is executing MacOS code while on a native 68k machine, the interrupt could
219 occur at any time (e.g. inside an EMUL_OP handler routine). In any case, the
220 MacOS thread will eventually end up in the level 1 interrupt handler which
221 contains an M68K_EMUL_OP_IRQ opcode. The opcode handler in emul_op.cpp will
222 then look at InterruptFlags and decide which routines to call.
223
224 6. Parts of Basilisk II
225 -----------------------
226
227 The conception of Basilisk II is quite modular and consists of many parts
228 which are relatively independent from each other:
229
230 - UAE CPU engine ("uae_cpu/*", not needed on all systems)
231 - ROM patches ("rom_patches.cpp", "slot_rom.cpp" and "emul_op.cpp")
232 - resource patches ("rsrc_patches.cpp" and "emul_op.cpp")
233 - PRAM Utilities replacement ("xpram.cpp")
234 - ADB Manager replacement ("adb.cpp")
235 - Time Manager replacement ("timer.cpp")
236 - SCSI Manager replacement ("scsi.cpp")
237 - video driver ("video.cpp")
238 - audio component ("audio.cpp")
239 - floppy driver ("sony.cpp")
240 - disk driver ("disk.cpp")
241 - CD-ROM driver ("cdrom.cpp")
242 - external file system ("extfs.cpp")
243 - serial drivers ("serial.cpp")
244 - Ethernet driver ("ether.cpp")
245 - system-dependant device access ("sys_*.cpp")
246 - user interface strings ("user_strings.cpp")
247 - preferences management ("prefs.cpp" and "prefs_editor_*.cpp")
248
249 Most modules consist of a platform-independant part (such as video.cpp) and a
250 platform-dependant part (such as video_beos.cpp). The "dummy" directory
251 contains generic "do-nothing" versions of some of the platform-dependant
252 parts to aid in testing and porting.
253
254 6.1. UAE CPU engine
255 -------------------
256
257 All files relating to the UAE 680x0 emulation are kept in the "uae_cpu"
258 directory. The "cpu_emulation.h" header file defines the link between the
259 UAE CPU and the rest of Basilisk II, and "basilisk_glue.cpp" implements the
260 link. It should be possible to replace the UAE CPU with a different 680x0
261 emulation by creating a new "xxx_cpu" directory with an appropriate
262 "cpu_emulation.h" header file (for the inlined memory access functions) and
263 writing glue code between the functions declared in "cpu_emulation.h" and
264 those provided by the 680x0 emulator.
265
266 6.2. ROM and resource patches
267 -----------------------------
268
269 As described above, instead of emulating custom Mac hardware, Basilisk II
270 provides replacements for certain parts of MacOS to redirect input, output
271 and system control functions of the Mac hardware to the underlying operating
272 systems. This is done by applying patches to the Mac ROM ("ROM patches") and
273 the MacOS system file ("resource patches", because nearly all system software
274 is contained in MacOS resources). Unless resources are written back to disk,
275 the system file patches are not permanent (it would cause many problems if
276 they were permanent, because some of the patches vary with different
277 versions of Basilisk II or even every time the emulator is launched).
278
279 ROM patches are contained in "rom_patches.cpp" and resource patches are
280 contained in "rsrc_patches.cpp". The ROM patches are far more numerous because
281 nearly all the software needed to run MacOS is contained in the Mac ROM (the
282 system file itself consists mainly of ROM patches, in addition to pictures and
283 text). One part of the ROM patches involves the construction of a NuBus slot
284 declaration ROM (in "slot_rom.cpp") which is used to add the video and Ethernet
285 drivers. Apart from the CPU emulation, the ROM and resource patches contain
286 most of the "logic" of the emulator.
287
288 6.3. PRAM Utilities
289 -------------------
290
291 MacOS stores certain nonvolatile system parameters in a 256 byte battery
292 backed-up CMOS RAM area called "Parameter RAM", "PRAM" or "XPRAM" (which refers
293 to "Extended PRAM" because the earliest Mac models only had 20 bytes of PRAM).
294 Basilisk II patches the ClkNoMem() MacOS trap which is used to access the XPRAM
295 (apart from some routines which are only used early during system startup)
296 and the real-time clock. The XPRAM is emulated in a 256 byte array which is
297 saved to disk to preserve the contents for the next time Basilisk is launched.
298
299 6.4. ADB Manager
300 ----------------
301
302 For emulating a mouse and a keyboard, Basilisk II patches the ADBOp() MacOS
303 trap. Platform-dependant code reports mouse and keyboard events with the
304 ADBMouseDown() etc. functions which are queued and sent to MacOS inside the
305 ADBInterrupt() function (which is called as a part of the 60Hz interrupt
306 handler) by calling the ADB mouse and keyboard handlers with Execute68k().
307
308 6.5. Time Manager
309 -----------------
310
311 Basilisk II completely replaces the Time Manager (InsTime(), RmvTime(),
312 PrimeTime() and Microseconds() traps). A "TMDesc" structure is associated with
313 each Time Manager task, that contains additional data. The tasks are executed
314 in the TimerInterrupt() function which is currently called inside the 60Hz
315 interrupt handler, thus limiting the resolution of the Time Manager to 16.6ms.
316
317 6.6. SCSI Manager
318 -----------------
319
320 The (old-style) SCSI Manager is also completely replaced and the MacOS
321 SCSIDispatch() trap redirected to the routines in "scsi.cpp". Under the MacOS,
322 programs have to issue multiple calls for all the different phases of a
323 SCSI bus interaction (arbitration, selection, command transfer etc.).
324 Basilisk II maps this API to an atomic API which is used by most modern
325 operating systems. All action is deferred until the call to SCSIComplete().
326 The TIB (Transfer Instruction Block) mini-programs used by the MacOS are
327 translated into a scatter/gather list of data blocks. Operating systems that
328 don't support scatter/gather SCSI I/O will have to use buffering if more than
329 one data block is being transmitted. Some more advanced (but rarely used)
330 aspects of the SCSI Manager (like messaging and compare operations) are not
331 emulated.
332
333 6.7. Video driver
334 -----------------
335
336 The NuBus slot declaration ROM constructed in "slot_rom.cpp" contains a driver
337 definition for a video driver. The Control and Status calls of this driver are
338 implemented in "video.cpp". Run-time video mode and depth switching are
339 currently not supported.
340
341 The host-side initialization of the video system is done in VideoInit().
342 This function must provide access to a frame buffer for MacOS and supply
343 its address, resolution and color depth in a video_desc structure (there
344 is currently only one video_desc structure, called VideoMonitor; this is
345 going to change once multiple displays are supported). In real addressing
346 mode, this frame buffer must be in a MacOS compatible layout (big-endian
347 and 1, 2, 4 or 8 bits paletted chunky pixels, RGB 5:5:5 or xRGB 8:8:8:8).
348 In virtual addressing mode, the frame buffer is located at address
349 0xa0000000 on the Mac side and you have to supply the host address, size
350 and layout (BasiliskII will do an automatic pixel format conversion in
351 virtual addressing mode) in the variables MacFrameBaseHost, MacFrameSize
352 and MacFrameLayout.
353
354 6.8. Audio component
355 --------------------
356
357 Basilisk II provides a Sound Manager 3.x audio component for sound output.
358 Earlier Sound Manager versions that don't use components but 'snth' resources
359 are not supported. Nearly all component functions are implemented in
360 "audio.cpp". The system-dependant modules ("audio_*.cpp") handle the
361 initialization of the audio hardware/driver, volume controls, and the actual
362 sound output.
363
364 The mechanism of sound output varies depending on the platform but usually
365 there will be one "streaming thread" (either a thread that continuously writes
366 data buffers to the audio device or a callback function that provides the
367 next data buffer) that reads blocks of sound data from the MacOS Sound Manager
368 and writes them to the audio device. To request the next data buffer, the
369 streaming thread triggers the INTFLAG_AUDIO interrupt which will cause the
370 MacOS thread to eventually call AudioInterrupt(). Inside AudioInterrupt(),
371 the next data block will be read and the streaming thread is signalled that
372 new audio data is available.
373
374 6.9. Floppy, disk and CD-ROM drivers
375 ------------------------------------
376
377 Basilisk II contains three MacOS drivers that implement floppy, disk and CD-ROM
378 access ("sony.cpp", "disk.cpp" and "cdrom.cpp"). They rely heavily on the
379 functionality provided by the "sys_*.cpp" module. BTW, the name ".Sony" of the
380 MacOS floppy driver comes from the fact that the 3.5" floppy drive in the first
381 Mac models was custom-built for Apple by Sony (this was one of the first
382 applications of the 3.5" floppy format which was also invented by Sony).
383
384 6.10. External file system
385 --------------------------
386
387 Basilisk II also provides a method for accessing files and direcories on the
388 host OS from the MacOS side by means of an "external" file system (henceforth
389 called "ExtFS"). The ExtFS is built upon the File System Manager 1.2 interface
390 that is built into MacOS 7.6 (and later) and available as a system extension
391 for earlier MacOS versions. Unlike other parts of Basilisk II, extfs.cpp
392 requires POSIX file I/O and this is not going to change any time soon, so if
393 you are porting Basilisk II to a system without POSIX file functions, you
394 should emulate them.
395
396 6.11. Serial drivers
397 --------------------
398
399 Similar to the disk drivers, Basilisk II contains replacement serial drivers
400 for the emulation of Mac modem and printer ports. To avoid duplicating code,
401 both ports are handled by the same set of routines. The SerialPrime() etc.
402 functions are mostly wrappers that determine which port is being accessed.
403 All the real work is done by the "SERDPort" class which is subclassed by the
404 platform-dependant code. There are two instances (for port A and B) of the
405 subclasses.
406
407 Unlike the disk drivers, the serial driver must be able to handle asynchronous
408 operations. Calls to SerialPrime() will usually not actually transmit or receive
409 data but delegate the action to an independant thread. SerialPrime() then
410 returns "1" to indicate that the I/O operation is not yet completed. The
411 completion of the I/O request is signalled by calling the MacOS trap "IODone".
412 However, this can't be done by the I/O thread because it's not in the right
413 run-time environment to call MacOS functions. Therefore it will trigger the
414 INTFLAG_SERIAL interrupt which causes the MacOS thread to eventually call
415 SerialInterrupt(). SerialInterrupt(), in turn, will not call IODone either but
416 install a Deferred Task to do the job. The Deferred Task will be called by
417 MacOS when it returns to interrupt level 0. This mechanism sounds complicated
418 but is necessary to ensure stable operation of the serial driver.
419
420 6.12. Ethernet driver
421 ---------------------
422
423 A driver for Ethernet networking is also contained in the NuBus slot ROM.
424 Only one ethernet card can be handled by Basilisk II. For Ethernet to work,
425 Basilisk II must be able to send and receive raw Ethernet packets, including
426 the 14-byte header (destination and source address and type/length field),
427 but not including the 4-byte CRC. This may not be possible on all platforms
428 or it may require writing special net drivers or add-ons or running with
429 superuser priviledges to get access to the raw packets.
430
431 Writing packets works as in the serial drivers. The ether_write() routine may
432 choose to send the packet immediately (e.g. under BeOS) and return noErr or to
433 delegate the sending to a separate thread (e.g. under AmigaOS) and return "1" to
434 indicate that the operation is still in progress. For the latter case, a
435 Deferred Task structure is provided in the ether_data area to call IODone from
436 EtherInterrupt() when the packet write is complete (see above for a description
437 of the mechanism).
438
439 Packet reception is a different story. First of all, there are two methods
440 provided by the MacOS Ethernet driver API to read packets, one of which (ERead/
441 ERdCancel) is not supported by Basilisk II. Basilisk II only supports reading
442 packets by attaching protocol handlers. This shouldn't be a problem because
443 the only network code I've seen so far that uses ERead is some Apple sample
444 code. AppleTalk, MacTCP, MacIPX, OpenTransport etc. all use protocol handlers.
445 By attaching a protocol handler, the user of the Ethernet driver supplies a
446 handler routine that should be called by the driver upon reception of Ethernet
447 packets of a certain type. 802.2 packets (type/length field of 0..1500 in the
448 packet header) are a bit special: there can be only one protocol handler attached
449 for 802.2 packets (by specifying a packet type of "0"). The MacOS LAP Manager
450 will attach a 802.2 handler upon startup and handle the distribution of 802.2
451 packets to sub-protocol handlers, but the Basilisk II Ethernet driver is not
452 concerned with this.
453
454 When the driver receives a packet, it has to look up the protocol handler
455 installed for the respective packet type (if any has been installed at all)
456 and call the packet handler routine. This must be done with Execute68k() from
457 the MacOS thread, so an interrupt (INTFLAG_ETHER) is triggered upon reception
458 of a packet so the EtherInterrupt() routine can call the protocol handler.
459 Before calling the handler, the Ethernet packet header has to be copied to
460 MacOS RAM (the "ed_RHA" field of the ether_data structure is provided for this).
461 The protocol handler will read the packet data by means of the ReadPacket/ReadRest
462 routines supplied by the Ethernet driver. Both routines will eventually end up
463 in EtherReadPacket() which copies the data to Mac address space. EtherReadPacket()
464 requires the host address and length of the packet to be loaded to a0 and d1
465 before calling the protocol handler.
466
467 Does this sound complicated? You are probably right. Here is another description
468 of what happens upon reception of a packet:
469 1. Ethernet card receives packet and notifies some platform-dependant entity
470 inside Basilisk II
471 2. This entity will store the packet in some safe place and trigger the
472 INTFLAG_ETHER interrupt
473 3. The MacOS thread will execute the EtherInterrupt() routine and look for
474 received packets
475 4. If a packet was received of a type to which a protocol handler had been
476 attached, the packet header is copied to ed_RHA, a0/d1 are loaded with
477 the host address and length of the packet data, a3 is loaded with the
478 Mac address of the first byte behing ed_RHA and a4 is loaded with the
479 Mac address of the ed_ReadPacket code inside ether_data, and the protocol
480 handler is called with Execute68k()
481 5. The protocol handler will eventually try to read the packet data with
482 a "jsr (a4)" or "jsr 2(a4)"
483 6. This will execute an M68K_EMUL_OP_ETHER_READ_PACKET opcode
484 7. The EtherReadPacket() opcode handling routine will copy the requested
485 part of the packet data to Mac RAM using the pointer and length which are
486 still in a0/d1
487
488 For a more detailed description of the Ethernet driver, see "Inside AppleTalk".
489
490 6.13. System-dependant device access
491 ------------------------------------
492
493 The method for accessing floppy drives, hard disks, CD-ROM drives and files
494 vary greatly between different operating systems. To make Basilisk II easily
495 portable, all device I/O is made via the functions declared in "sys.h" and
496 implemented by the (system-dependant) "sys_*.cpp" modules which provides a
497 standard, Unix-like interface to all kinds of devices.
498
499 6.14. User interface strings
500 ----------------------------
501
502 To aid in localization, all user interface strings of Basilisk II are collected
503 in "user_strings.cpp" (for common strings) and "user_strings_*.cpp" (for
504 platform-specific strings), and accessed via the GetString() function. This
505 way, Basilisk II may be easily translated to different languages.
506
507 6.15. Preferences management
508 ----------------------------
509
510 The module "prefs.cpp" handles user preferences in a system-independant way.
511 Preferences items are accessed with the PrefsAdd*(), PrefsReplace*() and
512 PrefsFind*() functions and stored in human-readable and editable text files
513 on disk. There are two lists of available preferences items. The first one,
514 common_prefs_items, defines the items which are available on all systems.
515 The second one, platform_prefs_items, is defined in prefs_*.cpp and lists
516 the prefs items which are specific to a certain platform.
517
518 The "prefs_editor_*.cpp" module provides a graphical user interface for
519 setting the preferences so users won't have to edit the preferences file
520 manually.
521
522 7. Porting Basilisk II
523 ----------------------
524
525 Porting Basilisk II to a new platform should not be hard. These are the steps
526 involved in the process:
527
528 1. Create a new directory inside the "src" directory for your platform. If
529 your platform comes in several "flavours" that require adapted files, you
530 should consider creating subdirectories inside the platform directory.
531 All files needed for your port must be placed inside the new directory.
532 Don't scatter platform-dependant files across the "src" hierarchy.
533 2. Decide in which mode (virtual addressing, real addressing or native CPU)
534 Basilisk II will run.
535 3. Create a "sysdeps.h" file which defines the mode and system-dependant
536 data types and memory access functions. Things which are used in Basilisk
537 but missing on your platform (such as endianess macros) should also be
538 defined here.
539 4. Implement the system-specific parts of Basilisk:
540 main_*.cpp, sys_*.cpp, prefs_*.cpp, prefs_editor_*.cpp, xpram_*.cpp,
541 timer_*.cpp, audio_*.cpp, video_*.cpp, serial_*.cpp, ether_*.cpp,
542 scsi_*.cpp and clip_*.cpp
543 You may want to take the skeleton implementations in the "dummy" directory
544 as a starting point and look at the implementation for other platforms
545 before writing your own.
546 5. Important things to remember:
547 - Use the ReadMacInt*() and WriteMacInt*() functions from "cpu_emulation.h"
548 to access Mac memory
549 - Use the ntohs() etc. macros to convert endianess when accessing Mac
550 memory directly
551 - Don't modify any source files outside of your platform directory unless
552 you really, really have to. Instead of adding "#ifdef PLATFORM" blocks
553 to one of the platform-independant source files, you should contact me
554 so that we may find a more elegant and more portable solution.
555 6. Coding style: indent -kr -ts4
556
557
558 Christian Bauer
559 <Christian.Bauer@uni-mainz.de>