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

# User Rev Content
1 cebix 1.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 cebix 1.3 2. Emulated CPU, "real" addressing (EMULATED_68K = 1, REAL_ADDRESSING = 1):
58 cebix 1.1 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 cebix 1.2 - external file system ("extfs.cpp")
243 cebix 1.1 - 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 cebix 1.2 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 cebix 1.1 --------------------
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 cebix 1.2 6.12. Ethernet driver
421 cebix 1.1 ---------------------
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 cebix 1.2 6.13. System-dependant device access
491 cebix 1.1 ------------------------------------
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 cebix 1.2 6.14. User interface strings
500 cebix 1.1 ----------------------------
501    
502     To aid in localization, all user interface strings of Basilisk II are collected
503 cebix 1.2 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 cebix 1.1
507 cebix 1.2 6.15. Preferences management
508 cebix 1.1 ----------------------------
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>