ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/cebix/BasiliskII/TECH
(Generate patch)

Comparing BasiliskII/TECH (file contents):
Revision 1.5 by gbeauche, 2001-02-10T09:20:54Z vs.
Revision 1.7 by gbeauche, 2002-10-03T15:50:13Z

# Line 106 | Line 106 | DIRECT_ADDRESSING and EMULATED_68K defin
106     be made available, using the real addressing mode is not possible.
107    
108     Note: currently, real addressing mode is known to work only on AmigaOS,
109 <   NetBSD/m68k, and Linux/i386.
109 >   NetBSD/m68k, FreeBSD/i386 and Linux/i386.
110  
111   4. Native CPU (EMULATED_68K = 0, this also requires REAL_ADDRESSING = 1)
112     This mode is designed for systems that use a 68k (68020 or better) processor
# Line 223 | Line 223 | Basilisk II only uses level 1 and does i
223   currently defined interrupt sources (see main.h):
224  
225    INTFLAG_60HZ    - MacOS 60Hz interrupt (unlike a real Mac, we also handle
226 <                    VBL interrupts, ADB events and the Time Manager here)
226 >                    VBL interrupts and the Time Manager here)
227 >  INTFLAG_1HZ     - MacOS 1Hz interrupt (updates system time)
228    INTFLAG_SERIAL  - Interrupt for serial driver I/O completion
229    INTFLAG_ETHER   - Interrupt for Ethernet driver I/O completion and packet
230                      reception
231    INTFLAG_AUDIO   - Interrupt for audio "next block" requests
232    INTFLAG_TIMER   - Reserved for a future implementation of a more precise
233                      Time Manager (currently not used)
234 +  INTFLAG_ADB     - Interrupt for mouse/keyboard input
235 +  INTFLAG_NMI     - NMI for debugging (not supported on all platforms)
236  
237   An interrupt is triggered by calling SetInterruptFlag() with the desired
238   interrupt flag constant and then TriggerInterrupt(). When the UAE 68k
# Line 292 | Line 295 | As described above, instead of emulating
295   provides replacements for certain parts of MacOS to redirect input, output
296   and system control functions of the Mac hardware to the underlying operating
297   systems. This is done by applying patches to the Mac ROM ("ROM patches") and
298 < the MacOS system file ("resource patches", because nearly all system software
299 < is contained in MacOS resources). Unless resources are written back to disk,
300 < the system file patches are not permanent (it would cause many problems if
301 < they were permanent, because some of the patches vary with different
302 < versions of Basilisk II or even every time the emulator is launched).
298 > the MacOS system file ("resource patches", because nearly all system
299 > software is contained in MacOS resources). Unless resources are written back
300 > to disk, the system file patches are not permanent (it would cause many
301 > problems if they were permanent, because some of the patches vary with
302 > different versions of Basilisk II or even every time the emulator is
303 > launched).
304  
305   ROM patches are contained in "rom_patches.cpp" and resource patches are
306 < contained in "rsrc_patches.cpp". The ROM patches are far more numerous because
307 < nearly all the software needed to run MacOS is contained in the Mac ROM (the
308 < system file itself consists mainly of ROM patches, in addition to pictures and
309 < text). One part of the ROM patches involves the construction of a NuBus slot
310 < declaration ROM (in "slot_rom.cpp") which is used to add the video and Ethernet
311 < drivers. Apart from the CPU emulation, the ROM and resource patches contain
312 < most of the "logic" of the emulator.
306 > contained in "rsrc_patches.cpp". The ROM patches are far more numerous
307 > because nearly all the software needed to run MacOS is contained in the Mac
308 > ROM (the system file itself consists mainly of ROM patches, in addition to
309 > pictures and text). One part of the ROM patches involves the construction of
310 > a NuBus slot declaration ROM (in "slot_rom.cpp") which is used to add the
311 > video and Ethernet drivers. Apart from the CPU emulation, the ROM and
312 > resource patches contain most of the "logic" of the emulator.
313  
314   6.3. PRAM Utilities
315   -------------------
316  
317   MacOS stores certain nonvolatile system parameters in a 256 byte battery
318 < backed-up CMOS RAM area called "Parameter RAM", "PRAM" or "XPRAM" (which refers
319 < to "Extended PRAM" because the earliest Mac models only had 20 bytes of PRAM).
320 < Basilisk II patches the ClkNoMem() MacOS trap which is used to access the XPRAM
321 < (apart from some routines which are only used early during system startup)
322 < and the real-time clock. The XPRAM is emulated in a 256 byte array which is
323 < saved to disk to preserve the contents for the next time Basilisk is launched.
318 > backed-up CMOS RAM area called "Parameter RAM", "PRAM" or "XPRAM" (which
319 > refers to "Extended PRAM" because the earliest Mac models only had 20 bytes
320 > of PRAM). Basilisk II patches the ClkNoMem() MacOS trap which is used to
321 > access the XPRAM (apart from some routines which are only used early during
322 > system startup) and the real-time clock. The XPRAM is emulated in a 256 byte
323 > array which is saved to disk to preserve the contents for the next time
324 > Basilisk is launched.
325  
326   6.4. ADB Manager
327   ----------------
328  
329   For emulating a mouse and a keyboard, Basilisk II patches the ADBOp() MacOS
330   trap. Platform-dependant code reports mouse and keyboard events with the
331 < ADBMouseDown() etc. functions which are queued and sent to MacOS inside the
332 < ADBInterrupt() function (which is called as a part of the 60Hz interrupt
333 < handler) by calling the ADB mouse and keyboard handlers with Execute68k().
331 > ADBMouseDown() etc. functions where they are queued, and the INTFLAG_ADB
332 > interrupt is triggered. The ADBInterrupt() handler function sends the input
333 > events to MacOS by calling the ADB mouse and keyboard handlers with
334 > Execute68k().
335  
336   6.5. Time Manager
337   -----------------
338  
339   Basilisk II completely replaces the Time Manager (InsTime(), RmvTime(),
340 < PrimeTime() and Microseconds() traps). A "TMDesc" structure is associated with
341 < each Time Manager task, that contains additional data. The tasks are executed
342 < in the TimerInterrupt() function which is currently called inside the 60Hz
343 < interrupt handler, thus limiting the resolution of the Time Manager to 16.6ms.
340 > PrimeTime() and Microseconds() traps). A "TMDesc" structure is associated
341 > with each Time Manager task, that contains additional data. The tasks are
342 > executed in the TimerInterrupt() function which is currently called inside
343 > the 60Hz interrupt handler, thus limiting the resolution of the Time Manager
344 > to 16.6ms.
345  
346   6.6. SCSI Manager
347   -----------------
348  
349   The (old-style) SCSI Manager is also completely replaced and the MacOS
350 < SCSIDispatch() trap redirected to the routines in "scsi.cpp". Under the MacOS,
351 < programs have to issue multiple calls for all the different phases of a
352 < SCSI bus interaction (arbitration, selection, command transfer etc.).
350 > SCSIDispatch() trap redirected to the routines in "scsi.cpp". Under the
351 > MacOS, programs have to issue multiple calls for all the different phases of
352 > a SCSI bus interaction (arbitration, selection, command transfer etc.).
353   Basilisk II maps this API to an atomic API which is used by most modern
354   operating systems. All action is deferred until the call to SCSIComplete().
355   The TIB (Transfer Instruction Block) mini-programs used by the MacOS are
356   translated into a scatter/gather list of data blocks. Operating systems that
357 < don't support scatter/gather SCSI I/O will have to use buffering if more than
358 < one data block is being transmitted. Some more advanced (but rarely used)
359 < aspects of the SCSI Manager (like messaging and compare operations) are not
360 < emulated.
357 > don't support scatter/gather SCSI I/O will have to use buffering if more
358 > than one data block is being transmitted. Some more advanced (but rarely
359 > used) aspects of the SCSI Manager (like messaging and compare operations)
360 > are not emulated.
361  
362   6.7. Video driver
363   -----------------
364  
365 < The NuBus slot declaration ROM constructed in "slot_rom.cpp" contains a driver
366 < definition for a video driver. The Control and Status calls of this driver are
367 < implemented in "video.cpp". Run-time video mode and depth switching are
361 < currently not supported.
365 > The NuBus slot declaration ROM constructed in "slot_rom.cpp" contains a
366 > driver definition for a video driver. The Control and Status calls of this
367 > driver are implemented in "video.cpp".
368  
369   The host-side initialization of the video system is done in VideoInit().
370 < This function must provide access to a frame buffer for MacOS and supply
371 < its address, resolution and color depth in a video_desc structure (there
372 < is currently only one video_desc structure, called VideoMonitor; this is
373 < going to change once multiple displays are supported). In real addressing
374 < mode, this frame buffer must be in a MacOS compatible layout (big-endian
375 < and 1, 2, 4 or 8 bits paletted chunky pixels, RGB 5:5:5 or xRGB 8:8:8:8).
376 < In virtual addressing mode, the frame buffer is located at address
377 < 0xa0000000 on the Mac side and you have to supply the host address, size
378 < and layout (BasiliskII will do an automatic pixel format conversion in
379 < virtual addressing mode) in the variables MacFrameBaseHost, MacFrameSize
380 < and MacFrameLayout.
370 > This function must fill the VideoModes vector with a list of supported video
371 > modes (combinations of color depth and resolution). It must then call
372 > video_init_depth_list() and setup the VideoMonitor structure with the
373 > default mode information and the address of a frame buffer for MacOS. In
374 > real addressing mode, this frame buffer must be in a MacOS compatible layout
375 > (big-endian and 1, 2, 4 or 8 bits paletted chunky pixels, RGB 5:5:5 or xRGB
376 > 8:8:8:8). In virtual addressing mode, the frame buffer is located at address
377 > 0xa0000000 on the Mac side and you have to supply the host address, size and
378 > layout (BasiliskII will do an automatic pixel format conversion in virtual
379 > addressing mode) in the variables MacFrameBaseHost, MacFrameSize and
380 > MacFrameLayout.
381 >
382 > There are two functions of the platform-dependant video driver code that get
383 > called during runtime: video_set_palette() to update the CLUT (for indexed
384 > modes) or gamma table (for direct color modes), and video_switch_to_mode()
385 > to switch to a different color depth and/or resolution (in this case the
386 > frame buffer base in VideoMonitor must be updated).
387  
388   6.8. Audio component
389   --------------------
390  
391   Basilisk II provides a Sound Manager 3.x audio component for sound output.
392 < Earlier Sound Manager versions that don't use components but 'snth' resources
393 < are not supported. Nearly all component functions are implemented in
394 < "audio.cpp". The system-dependant modules ("audio_*.cpp") handle the
392 > Earlier Sound Manager versions that don't use components but 'snth'
393 > resources are not supported. Nearly all component functions are implemented
394 > in "audio.cpp". The system-dependant modules ("audio_*.cpp") handle the
395   initialization of the audio hardware/driver, volume controls, and the actual
396   sound output.
397  
398   The mechanism of sound output varies depending on the platform but usually
399 < there will be one "streaming thread" (either a thread that continuously writes
400 < data buffers to the audio device or a callback function that provides the
401 < next data buffer) that reads blocks of sound data from the MacOS Sound Manager
402 < and writes them to the audio device. To request the next data buffer, the
403 < streaming thread triggers the INTFLAG_AUDIO interrupt which will cause the
404 < MacOS thread to eventually call AudioInterrupt(). Inside AudioInterrupt(),
405 < the next data block will be read and the streaming thread is signalled that
406 < new audio data is available.
399 > there will be one "streaming thread" (either a thread that continuously
400 > writes data buffers to the audio device or a callback function that provides
401 > the next data buffer) that reads blocks of sound data from the MacOS Sound
402 > Manager and writes them to the audio device. To request the next data
403 > buffer, the streaming thread triggers the INTFLAG_AUDIO interrupt which will
404 > cause the MacOS thread to eventually call AudioInterrupt(). Inside
405 > AudioInterrupt(), the next data block will be read and the streaming thread
406 > is signalled that new audio data is available.
407  
408   6.9. Floppy, disk and CD-ROM drivers
409   ------------------------------------
410  
411 < Basilisk II contains three MacOS drivers that implement floppy, disk and CD-ROM
412 < access ("sony.cpp", "disk.cpp" and "cdrom.cpp"). They rely heavily on the
413 < functionality provided by the "sys_*.cpp" module. BTW, the name ".Sony" of the
414 < MacOS floppy driver comes from the fact that the 3.5" floppy drive in the first
415 < Mac models was custom-built for Apple by Sony (this was one of the first
416 < applications of the 3.5" floppy format which was also invented by Sony).
411 > Basilisk II contains three MacOS drivers that implement floppy, disk and
412 > CD-ROM access ("sony.cpp", "disk.cpp" and "cdrom.cpp"). They rely heavily on
413 > the functionality provided by the "sys_*.cpp" module. BTW, the name ".Sony"
414 > of the MacOS floppy driver comes from the fact that the 3.5" floppy drive in
415 > the first Mac models was custom-built for Apple by Sony (this was one of the
416 > first applications of the 3.5" floppy format which was also invented by
417 > Sony).
418  
419   6.10. External file system
420   --------------------------
421  
422   Basilisk II also provides a method for accessing files and direcories on the
423 < host OS from the MacOS side by means of an "external" file system (henceforth
424 < called "ExtFS"). The ExtFS is built upon the File System Manager 1.2 interface
425 < that is built into MacOS 7.6 (and later) and available as a system extension
426 < for earlier MacOS versions. Unlike other parts of Basilisk II, extfs.cpp
427 < requires POSIX file I/O and this is not going to change any time soon, so if
428 < you are porting Basilisk II to a system without POSIX file functions, you
429 < should emulate them.
423 > host OS from the MacOS side by means of an "external" file system
424 > (henceforth called "ExtFS"). The ExtFS is built upon the File System Manager
425 > 1.2 interface that is built into MacOS 7.6 (and later) and available as a
426 > system extension for earlier MacOS versions. Unlike other parts of Basilisk
427 > II, extfs.cpp requires POSIX file I/O and this is not going to change any
428 > time soon, so if you are porting Basilisk II to a system without POSIX file
429 > functions, you should emulate them.
430  
431   6.11. Serial drivers
432   --------------------
# Line 426 | Line 439 | All the real work is done by the "SERDPo
439   platform-dependant code. There are two instances (for port A and B) of the
440   subclasses.
441  
442 < Unlike the disk drivers, the serial driver must be able to handle asynchronous
443 < operations. Calls to SerialPrime() will usually not actually transmit or receive
444 < data but delegate the action to an independant thread. SerialPrime() then
445 < returns "1" to indicate that the I/O operation is not yet completed. The
446 < completion of the I/O request is signalled by calling the MacOS trap "IODone".
447 < However, this can't be done by the I/O thread because it's not in the right
448 < run-time environment to call MacOS functions. Therefore it will trigger the
449 < INTFLAG_SERIAL interrupt which causes the MacOS thread to eventually call
450 < SerialInterrupt(). SerialInterrupt(), in turn, will not call IODone either but
451 < install a Deferred Task to do the job. The Deferred Task will be called by
452 < MacOS when it returns to interrupt level 0. This mechanism sounds complicated
453 < but is necessary to ensure stable operation of the serial driver.
442 > Unlike the disk drivers, the serial driver must be able to handle
443 > asynchronous operations. Calls to SerialPrime() will usually not actually
444 > transmit or receive data but delegate the action to an independant thread.
445 > SerialPrime() then returns "1" to indicate that the I/O operation is not yet
446 > completed. The completion of the I/O request is signalled by calling the
447 > MacOS trap "IODone". However, this can't be done by the I/O thread because
448 > it's not in the right run-time environment to call MacOS functions.
449 > Therefore it will trigger the INTFLAG_SERIAL interrupt which causes the
450 > MacOS thread to eventually call SerialInterrupt(). SerialInterrupt(), in
451 > turn, will not call IODone either but install a Deferred Task to do the job.
452 > The Deferred Task will be called by MacOS when it returns to interrupt level
453 > 0. This mechanism sounds complicated but is necessary to ensure stable
454 > operation of the serial driver.
455  
456   6.12. Ethernet driver
457   ---------------------
# Line 450 | Line 464 | but not including the 4-byte CRC. This m
464   or it may require writing special net drivers or add-ons or running with
465   superuser priviledges to get access to the raw packets.
466  
467 < Writing packets works as in the serial drivers. The ether_write() routine may
468 < choose to send the packet immediately (e.g. under BeOS) and return noErr or to
469 < delegate the sending to a separate thread (e.g. under AmigaOS) and return "1" to
470 < indicate that the operation is still in progress. For the latter case, a
471 < Deferred Task structure is provided in the ether_data area to call IODone from
472 < EtherInterrupt() when the packet write is complete (see above for a description
473 < of the mechanism).
467 > For situations in which access to raw Ethernet packets is not possible,
468 > Basilisk II implements a special "tunneling" mode in which it sends and
469 > receives packets via UDP, using BSD socket functions. It simply wraps the
470 > Ethernet packets into UDP packets, using dummy Ethernet addresses that are
471 > made up of the IP address of the host. Ethernet broadcast and AppleTalk
472 > multicast packets are sent to the IP broadcast address. Because of this
473 > non-standard way of tunneling, it is only possible to set up a "virtual"
474 > network amongst machines running Basilisk II in this way.
475 >
476 > Writing packets works as in the serial drivers. The ether_write() routine
477 > may choose to send the packet immediately (e.g. under BeOS) and return noErr
478 > or to delegate the sending to a separate thread (e.g. under AmigaOS) and
479 > return "1" to indicate that the operation is still in progress. For the
480 > latter case, a Deferred Task structure is provided in the ether_data area to
481 > call IODone from EtherInterrupt() when the packet write is complete (see
482 > above for a description of the mechanism).
483  
484   Packet reception is a different story. First of all, there are two methods
485 < provided by the MacOS Ethernet driver API to read packets, one of which (ERead/
486 < ERdCancel) is not supported by Basilisk II. Basilisk II only supports reading
487 < packets by attaching protocol handlers. This shouldn't be a problem because
488 < the only network code I've seen so far that uses ERead is some Apple sample
489 < code. AppleTalk, MacTCP, MacIPX, OpenTransport etc. all use protocol handlers.
490 < By attaching a protocol handler, the user of the Ethernet driver supplies a
491 < handler routine that should be called by the driver upon reception of Ethernet
492 < packets of a certain type. 802.2 packets (type/length field of 0..1500 in the
493 < packet header) are a bit special: there can be only one protocol handler attached
494 < for 802.2 packets (by specifying a packet type of "0"). The MacOS LAP Manager
495 < will attach a 802.2 handler upon startup and handle the distribution of 802.2
496 < packets to sub-protocol handlers, but the Basilisk II Ethernet driver is not
497 < concerned with this.
485 > provided by the MacOS Ethernet driver API to read packets, one of which
486 > (ERead/ ERdCancel) is not supported by Basilisk II. Basilisk II only
487 > supports reading packets by attaching protocol handlers. This shouldn't be a
488 > problem because the only network code I've seen so far that uses ERead is
489 > some Apple sample code. AppleTalk, MacTCP, MacIPX, OpenTransport etc. all
490 > use protocol handlers. By attaching a protocol handler, the user of the
491 > Ethernet driver supplies a handler routine that should be called by the
492 > driver upon reception of Ethernet packets of a certain type. 802.2 packets
493 > (type/length field of 0..1500 in the packet header) are a bit special: there
494 > can be only one protocol handler attached for 802.2 packets (by specifying a
495 > packet type of "0"). The MacOS LAP Manager will attach a 802.2 handler upon
496 > startup and handle the distribution of 802.2 packets to sub-protocol
497 > handlers, but the Basilisk II Ethernet driver is not concerned with this.
498  
499   When the driver receives a packet, it has to look up the protocol handler
500   installed for the respective packet type (if any has been installed at all)
501 < and call the packet handler routine. This must be done with Execute68k() from
502 < the MacOS thread, so an interrupt (INTFLAG_ETHER) is triggered upon reception
503 < of a packet so the EtherInterrupt() routine can call the protocol handler.
504 < Before calling the handler, the Ethernet packet header has to be copied to
505 < MacOS RAM (the "ed_RHA" field of the ether_data structure is provided for this).
506 < The protocol handler will read the packet data by means of the ReadPacket/ReadRest
507 < routines supplied by the Ethernet driver. Both routines will eventually end up
508 < in EtherReadPacket() which copies the data to Mac address space. EtherReadPacket()
509 < requires the host address and length of the packet to be loaded to a0 and d1
510 < before calling the protocol handler.
501 > and call the packet handler routine. This must be done with Execute68k()
502 > from the MacOS thread, so an interrupt (INTFLAG_ETHER) is triggered upon
503 > reception of a packet so the EtherInterrupt() routine can call the protocol
504 > handler. Before calling the handler, the Ethernet packet header has to be
505 > copied to MacOS RAM (the "ed_RHA" field of the ether_data structure is
506 > provided for this). The protocol handler will read the packet data by means
507 > of the ReadPacket/ReadRest routines supplied by the Ethernet driver. Both
508 > routines will eventually end up in EtherReadPacket() which copies the data
509 > to Mac address space. EtherReadPacket() requires the host address and length
510 > of the packet to be loaded to a0 and d1 before calling the protocol handler.
511  
512 < Does this sound complicated? You are probably right. Here is another description
513 < of what happens upon reception of a packet:
512 > Does this sound complicated? You are probably right. Here is another
513 > description of what happens upon reception of a packet:
514    1. Ethernet card receives packet and notifies some platform-dependant entity
515       inside Basilisk II
516    2. This entity will store the packet in some safe place and trigger the
# Line 507 | Line 530 | of what happens upon reception of a pack
530       part of the packet data to Mac RAM using the pointer and length which are
531       still in a0/d1
532  
533 < For a more detailed description of the Ethernet driver, see "Inside AppleTalk".
533 > For a more detailed description of the Ethernet driver, see the book "Inside
534 > AppleTalk".
535  
536   6.13. System-dependant device access
537   ------------------------------------
# Line 521 | Line 545 | standard, Unix-like interface to all kin
545   6.14. User interface strings
546   ----------------------------
547  
548 < To aid in localization, all user interface strings of Basilisk II are collected
549 < in "user_strings.cpp" (for common strings) and "user_strings_*.cpp" (for
550 < platform-specific strings), and accessed via the GetString() function. This
551 < way, Basilisk II may be easily translated to different languages.
548 > To aid in localization, all user interface strings of Basilisk II are
549 > collected in "user_strings.cpp" (for common strings) and
550 > "user_strings_*.cpp" (for platform-specific strings), and accessed via the
551 > GetString() function. This way, Basilisk II may be easily translated to
552 > different languages.
553  
554   6.15. Preferences management
555   ----------------------------
# Line 533 | Line 558 | The module "prefs.cpp" handles user pref
558   Preferences items are accessed with the PrefsAdd*(), PrefsReplace*() and
559   PrefsFind*() functions and stored in human-readable and editable text files
560   on disk. There are two lists of available preferences items. The first one,
561 < common_prefs_items, defines the items which are available on all systems.
562 < The second one, platform_prefs_items, is defined in prefs_*.cpp and lists
563 < the prefs items which are specific to a certain platform.
561 > common_prefs_items, is defined in "prefs_items.cpp" and lists items which
562 > are available on all systems. The second one, platform_prefs_items, is
563 > defined in "prefs_*.cpp" and lists the prefs items which are specific to a
564 > certain platform.
565  
566   The "prefs_editor_*.cpp" module provides a graphical user interface for
567   setting the preferences so users won't have to edit the preferences file
# Line 544 | Line 570 | manually.
570   7. Porting Basilisk II
571   ----------------------
572  
573 < Porting Basilisk II to a new platform should not be hard. These are the steps
574 < involved in the process:
573 > Porting Basilisk II to a new platform should not be hard. These are the
574 > steps involved in the process:
575  
576   1. Create a new directory inside the "src" directory for your platform. If
577     your platform comes in several "flavours" that require adapted files, you

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines