Home EmulatorsEmulators EmulatorsEmulators MagiC PC interfaceMagiC PC interface

14.1 MagiC Mac specifics

MagiC Mac is an implementation of MagiC known on the Atari platform for the hardware of the Apple (Power-) Macintosh computers. This section describes the following points:

Those having questions or missing some features for the Atari-Mac interface should first approach the author of the MagiC Mac kernel before tinkering with the internals, since any changes may no longer work in the next MagiC Mac version.

See also: About the GEMDOS   About the BIOS   XBIOS   GEM

14.1.1 General remarks about MagiC Mac

The core of the 'emulation' of the Atari environment on the Macintosh lies in the reprogramming of the PMMU. Both Atari as well as Macintosh programs assume that they will find certain variables (the so-called system variables) in the lowest 2 kB of the address space. However, when an Atari program is running it expects other values there than, say, the Mac operating system. The so-called kernel of MagiC Mac makes sure that - depending on whether a Mac or an Atari routine is running at the time - suitable system variables are present in that lower address space. This is done with appropriate programming of the PMMU, a coprocessor for memory management.

So there are two MMU modes: The Mac- and the Atari-mode. By means of two routines one can switch back and forth between them. Starting from taking the Mac-mode as the normal mode, the following changes occur when switching to the Atari-mode:

See also: Program launch and TPA

14.1.2 MagiC Mac and Power-Macs

MagiC Mac naturally also runs on the new PCI machines from Apple (Power Macintosh 7600, 8200, 8500 and 9500). When using this hardware the following points should be borne in mind:

See also: Program launch and TPA

14.1.3 Cookies under MagiC Mac

MagiC Mac naturally also supports the cookie jar, and creates the following cookies:

Cookie Meaning in MagiC Mac
   
_CPU Contains the value 20, 30 or 40. On 68000 machines MM does not run; on PowerPC machines a 68020 will be indicated
_FDC $014D6163 - The last 3 bytes result in the text 'Mac'
_FPU The usual values; with a 68040 there will only be an 8 here if the associated FPU software is installed as well
_MCH No Atari-compatible hardware present (-1)
_SND 0
_VDO No Atari-compatible video hardware present (-1)
MagX Same as in MagiC
MgMc Points to a MgMcCookie structure
MNAM Pointer to NULL-terminated string with the name of the computer; this only serves as information for the user
PMMU NULL; shows that the MMU is engaged and may not be used by other programs

See also: Cookie and XBRA list

14.1.4 Filesystems under MagiC Mac

MagiC Mac, just like MagiC, permits the incorporation of alternative filesystems. At present the following systems are supported:

The Mac filesystem under MagiC Mac:

As the GEMDOS functions are mapped directly to the Mac filesystem functions for the most part, all file formats usable under MacOS can be used under MagiC Mac as well, i.e. once one can 'mount' a drive on the Mac, it is (or its folder contents are) also installable under MM. Thanks to this one can also use CD-ROMs or network drives without any further drivers in MagiC Mac as a rule. MagiC Mac also allows the Mac- typical ejection of a floppy disk, for instance.

See also: MagiC's XFS-concept   Dpathconf

14.1.5 Restrictions of MagiC Mac

MagiC Mac does not implement all functions that MagiC offers for Ataris. AES, VDI and GEMDOS are implemented completely, but there are restrictions with BIOS and BIOS. However it is possible to restore some of the functionalities with add-ons such as McSTout or a sound driver.

Additionally there are restrictions with some functions, mainly in connection with the filesystem and the devices:

See also: About the GEMDOS   About the BIOS   XBIOS   GEM

14.1.6 Exceptions under MagiC Mac

As on a real Atari, an Atari program running under MagiC Mac can use the exception vectors, namely divert them. Actually the program may use only the exception vectors between $0 and $400 for this, not those to which the VBR points (because that points elsewhere!). Those who do not adhere to this may run into difficulties with later versions of MagiC Mac. Programs that use the PMMU, e.g. OUTSIDE can not run under MagiC Mac.

The following Atari interrupts are simulated by the kernel at present:

Due to the Mac hardware, however, the interrupts may appear with different priorities; consequently the interrupt mask of the SR has other values to that on an Atari in some circumstances. The vector at $400 (etv_timer) will also be jumped to by the MagiC OS, of course, as a subroutine of the interrupt handler for MFP interrupt 5, in just the same way as on an original Atari.

Likewise a program that would like to experience mouse or keyboard events can use the BIOS function Kbdvbase to hook itself into the event vectors in exactly the same way as on the Atari.

Another important note about interrupts: So that the keyboard, mouse and timer work properly on a Mac, the interrupt mask (in CPU register SR) must always be zero. On an Atari, on the other hand, it normally stands at three. Programs containing code such as MOVE #$2300,SR for instance, would put a Macintosh into a sleep state, which only a reset can remedy. Those who want to alter the interrupt mask only occasionally should do it this way (works equally well on an Atari and Mac):

  MOVE SR,-(a7)    ; Store old SR
  ORI  #$0700,SR   ; Block all interrupts for a critical access
  ...
  MOVE (a7)+,SR    ; At end, restore old SR

Those who definitely want to return the computer to its basic state should not use MOVE #$2300,SR but better MOVE #$2000,SR. On the Atari the SR will then be increased to $2300 just before the HBL interrupt routine. In this way the same code achieves te same result on both machines.

If interrupt or other asynchronous routines are installed by means of MacOS functions and then these functions are to switch from the Mac- mode to the Atari-mode, then several things need to be heeded, which are described in greater detail below:

See also: Program launch and TPA   Reset-vector   System variables

14.1.7 Clean programming

Even if the specific implementation of MagiC Mac is not of interest to every Atari programmer, there are some basic rules that one should adhere to on the Atari level to be as certain as possible that the programs can run also under MagiC Mac. Here the following points can be mentioned, amongst others:

See also:
Programming guidelines   Style guidelines   XBRA procedure

14.1.8 The shutdown process in MagiC Mac

Under MagiC Mac the shutdown process will be taken on by the program 'shutdown.prg'; if this was able to terminate all currently active (Atari) programs, then MagiC Mac itself will be terminated as well. Some programmers might find it of interest how one can terminate MagiC Mac without a query. This can be done in two steps:

In Pure-C this could look as follows, for instance:

  static pascal void ExitToShell (void) 0xA9F4;
  MgMcCookie *mgmc;
  ...
  ...
  get_cookie ("MgMc", &mgmc); /* Pointer to MgMc cookie structure    */
  mgmc->modeMac ();           /* Switch to Mac-mode                  */
  ExitToShell ();             /* Terminates MM at once without query */

This information could be important if you want to program your own shutdown.prg.

See also:
General remarks about shutdown   shel_write   Shutdown in MultiTOS   Shutdown in MagiC   Shutdown at the receiver   Shutdown at the initiator  

14.1.9 XCMDs under MagiC Mac

XCMDs are small external code modules for Macintosh applications. As a rule these can be created fairly easily with the development tools under MacOS (e.g. with Metrowerks' CodeWarrior or Symantec C). As of version 1.2.2 MagiC Mac also permits the simple use of such code modules by programs that run under MagiC. This greatly simplifies the development of programs or drivers that want to use the Macintosh functions, as these portions can then be created with a Macintosh compiler, rather than having to recreate the interfaces laboriously under an Atari development system.

An example of such a XCMD can be found in the 'Demo XCMD' folder of the original MagiC Mac documentation. The created module can then just be placed in the MagiC Mac XCMDs folder. This folder must lie in the same directory as the MagiC Mac application. At the launch of MagiC Mac this folder is searched through for files with the filetype 'xCmd' and the XCMD resources contained in it loaded and executed. These XCMDs can then register themselves with MagiC Mac and so become available for MagiC programs.

An application is shown by the Pure-C program in the 'MGMC_API' folder of the original MagiC Mac documentation. This shows how easily an installed XCMD can be opened and called. The functions offered here by the cookie (xcmdMgrPtr) go automatically into the supervisor-mode if required and switch to the Mac environment (with callMacContext), and also control parameter passing. The call of the XCMD functions in this way is therefore permitted only when the Atari-mode is active and if the call is not made from an interrupt.

If the XCMD functions are to be called from interrupts or in Mac-mode, one can use 'xcmdMgrPtr->getAdr' to get the entry address of the XCMD dispatcher and then jump to it directly.

Further information for XCMDs can be found in the source text 'Demo XCMD.c' of the original MagiC Mac documentation.

14.1.10 Cooperation between MagiC and the MacOS

MagiC Mac hooks itself directly into all interrupt vectors that the Macintosh uses. If MagiC is running and a hardware interrupt occurs, MagiC Mac switches the MMU back into the normal Macintosh-mode. At the end of the IntrRoutine one will be switched back into the Atari-mode and the programs running under MagiC will continue. As long as the Mac-mode is active, MagiC Mac does not meddle further with the Intr-processing, but does so only when the Atari-mode is active.

Whenever a switch is made from the Mac-mode back to the Atari-mode, a check is made whether a given amount of time has passed (measured in ticks; a tick is around 1/60s), in order to then perform periodic tasks. These tasks are called Mac-tasks here.

Mac-tasks perform the following, amongst others:

The decision whether to use GetOSEvent or WaitNextEvent (WNE) for polling the events can be set via 'Preferences' and also by a cookie function. Only if WNE is used will CPU time be allocated to other Mac applications as well.

Mac-tasks can be executed only if it is certain that no other MacOS function is being processed at the time, since the MacOS is not reentrant. Mac-tasks are therefore performed only if all of the following conditions apply:

14.1.11 The MagiC Mac cookie

The MagiC Mac operating system [a port of MagiC to the hardware of the Apple (Power) Macintosh] creates a cookie MgMc, which points to the following structure:

typedef struct
{
  SHORT   vers;                 /* Version identifier in BCD format    */
  SHORT   size;                 /* Size of the structure in bytes      */
  LONG    flags1;               /* Various flags:                      */
                                /*  Bit 0: 640*400 emulation active    */
                                /*  Bit 1: Right-[Shift] possible      */
                                /*  Bit 2: 2-button mouse              */
                                /*  Bit 3: 68k emulation on a Power-PC */
                                /*  Bit 4: Upper I/O area not present  */
                                /*  Bit 5: Lower I/O area not present  */
                                /*                                     */
                                /* Note: Bit 2 is only available as of */
                                /* Version 1.01, bit 3 from Version    */
                                /* 1.05 on and the following only as   */
                                /* of Version 1.10                     */
  PixMap  *scrnPMPtr;           /* Pointer to screen description       */
  BOOLEAN *updatePalette;       /* Is to be set to restore the         */
                                /* colour tables                       */
  ProcPtr modeMac;              /* MMU switching to Mac-mode           */
  ProcPtr modeAtari;            /* MMU switching to Atari-mode         */
  ProcPtr getBaseMode;          /* Returns the MMU-mode in d0.W        */
                                /* The following apply:                */
                                /*  0 = Macintosh                      */
                                /*  <> 0 = Atari                       */
  ProcPtr getIntrCount;         /* Returns interrupt semaphore-counter */
                                /* in d0.L (0 = free)                  */
  ProcPtr intrLock;             /* Increments inter. semaphore-counter */
  ProcPtr intrUnlock;           /* Decrements inter. semaphore-counter */
  ProcPtr callMacContext;       /* Executes routine in Mac-context;    */
                                /* Proc-adr. on stack                  */
                                /*                                     */
                                /* Warning: Registers d0-d2/a0/a1/a5   */
                                /* and a7 will be destroyed            */
  Ptr     atariZeroPage;        /* Pointer to Atari memory area,       */
                                /* $0-$800 in Macintosh address space  */
  Ptr     macA5;                /* Value of a5-register in Mac-context */
  ProcPtr macAppSwitch;         /* Called by the MagiC kernel (d0/4(a7)*/
                                /* The following apply:                */
                                /*  0 = Suspend                        */
                                /*  1 = Resume                         */
                                /*  2 = Quit                           */
                                /*  3/4 = atariModePossible alternates */
  ProcPtr controlSwitch;        /* Called by the MagiC kernel (d0/4(a7)*/
                                /* The following apply:                */
                                /*  0 = Hide Atari screen              */
                                /*  1 = Show Atari screen              */
  LONG    hardwareAttr1;        /* Undefined at present                */
  LONG    hardwareAttr2;        /* Undefined at present                */
  Ptr     magiC_BP;             /* BASEPAGE of the MagiC OS            */
  Ptr     auxOutName;           /* Pascal string for AUX-out workstation*/
  Ptr     auxInName;            /* Pascal string for AUX-in workstation */
  ProcPtr auxControl;           /* Called by the MagiC kernel (d0/4(a7)*/
                                /* The following apply:                */
                                /*  0 = Suspend                        */
                                /*  1 = Resume                         */
                                /*  2 = Quit                           */
  PrintDesc *printDescPtr;
  GenProc   configKernel;       /* Call (C-convention) Atari-mode      */
  BOOLEAN   *atariModePossible; /* Pointer to a flag showing whether   */
                                /* the call of modeAtari is permitted  */
                                /* at the time                         */
  MacVersion *versionOfMacAppl; /* Version of the MagiC Mac application*/
                                /* (as of Version 1.06)                */
  VOID       *hwEmulSupport;    /* Internal use (as of Version 1.07)   */
  FlpDrvInfo *floppyDrvInfoPtr; /* Points to information for drives A: */
                                /* and B: (as of Version 1.07)         */
  XCMDgrRec *xcmdMgrPtr;        /* XCMD interface (as of Version 1.08) */
  ProcPtr   giveTimeToMac;      /* Call in Mac-context if idle         */
  LONG      minStackSize;       /* Minimum supervisor stack size       */
  GenProc   ext;                /* Help routines, call from Atari-mode */
  GenProc   extMac;             /* As for 'ext' but call from Mac-mode */
  ProcPtr   stackLoad;          /* (As of 1.11 / MagiC Mac 2.0)        */
  ProcPtr   stackUnload;        /* (As of 1.11 / MagiC Mac 2.0)        */
  LONG      reserved[3];        /* Undefined at present                */
} MgMcCookie;

Notes:

See also:
MagiC Mac type conventions   Cookie and XBRA list

14.1.11.1 MagiC Mac type conventions

Here follows a list of type conventions that play a role in connection with MagiC Mac:

typedef char Boolean;
typedef char *Ptr, **Handle;
typedef unsigned char *StringPtr;
typedef void PixMap;
typedef Handle THPrint;
typedef void (*ProcPtr)(void);

typedef long cdecl (*GenProc) (short function, void *data);
typedef Boolean cdecl (*PrSetupProc) (Boolean alwaysInteractively);

Note: The XCMD structures are contained in the file 'MgMc_API.h' of the original documentation for MagiC Mac.

See also: Type definitions in MagiC

14.1.11.2 mmc_flg1_bit4

The lower I/O area ($00FF8000-$00FFFFFF) is not present as such, i.e. quite normal RAM may reside there, just as in any other place. In that case no distinction will be made between ST-RAM and TT-RAM - the whole of the RAM used by MagiC Mac, even that above 16 MB, will be made available as ST-RAM.

This means, of course, that in this case programs can make no I/O accesses to this area! If this bit is cleared (not set), a program can make accesses there nevertheless and count on a bus error if no Atari-compatible hardware (such as McSTout, say) is installed there.

14.1.11.3 mmc_flg1_bit5

The upper I/O area ($FFFF8000-$FFFFFFFF) is not accessible as such (see MagiC Mac and Power-Macs); on accessing it one does not get a bus error, but data from the Macintosh-ROM.

14.1.11.4 auxControl

This is intended for the HSMODEM driver: The WORD parameter on the stack determines whether the ports are to be released (2 = close completely, 0 = close, but hold DTR if necessary) or if reassignment of the ports is permitted (value = 1). Between value-0 and value-1 the names (auxInPort, auxOutPort) may have changed.

Note: The call should be made in Atari supervisor-mode, the USP is undefined.

See also: The MagiC Mac cookie   Cookie and XBRA list

14.1.11.5 callMacContext

This serves to produce the required Macintosh environment for calling any MacOS routines. The routine must be called in Mac-mode and in supervisor-mode and not from an interrupt.

For this one should pass on the stack the address of the routine that is to be called as a subroutine in the Mac context. The normal user stack of MagiC Mac is used for the called routine; in addition the register a5 is loaded with macA5 and if virtual memory is active, a switch is made to user-mode. As this function alters the stack, it is not possible to pass parameters via the stack. The registers d0-d2/a0/a1/a5/a7 are altered both at the call and also at the return of the subroutine (although a5/a7 after return from 'callMacContext' have the same values as before the call). The other registers are not altered and can be used for parameter passing and returns.

The execution of this subroutine implicitly brings calls of intrLock and intrUnlock with it, meaning that during this no Mac-tasks will be processed, even if one switches into Atari-mode occasionally. To allow processing of Mac-tasks despite of this, one can call the function 'giveTimeToMac'.

See also: The MagiC Mac cookie   Cookie and XBRA list

14.1.11.6 configKernel

This offers access to some settings that are otherwise accessible only interactively from the Macintosh side. For this one passes as a rule a function number in the function parameter and a pointer to a variable in the data parameter, which has to contain the value to be set before the call, or -1 in case no new value is to be set.

After the call the variable contains the current value. The settings will be adopted in the 'Preferences' if nothing else is specified. The functions:

Value Description
   
1 data points to a byte that determines whether the 200Hz timer is to be simulated by the MacOS timer. The following apply:
0 = No
1 = Yes (default)
2 Determines whether Mac background processes are to be called. The following apply:
0 = No
1 = Yes
3 Determines whether the IDLE state for Powerbooks is permitted. The followinng apply:
0 = No
1 = Yes
4 Similar to (1), for the flag 'UnlockMemOnMacSide' (see also under atariModePossible): If this is non-zero, the memory occupied by MagiC Mac for the TPA is released for offloading, as long as virtual memory is active. Otherwise it cannot be offloaded. This is not saved in the 'Preferences' at present.

See also: Program launch and TPA   The MagiC Mac cookie

14.1.11.7 controlSwitch

Here Atari routines can hook themselves in with the XBRA procedure. They are then called in Atari-mode (supervisor-mode) when one of the specified events occurs. This is required, for instance, when an Atari program wants to make use of certain Macintosh routines. For example, a program using the sound routines of the Mac can be told in this way when MagiC Mac has been terminated to close the sound channels and to release the occupied memory.

The following values are passed in d0.W and on the stack (and must also remain there):

Value Description
   
0 Hide
Mouse and keyboard control for MagiC are suspended, because a Mac dialog is opened, for instance; in that case there should be no output to the screen either (e.g. for interrupt routines) as otherwise these could overwrite the Macintosh dialog
1 Show
The opposite of Hide

Note: The routine has to be called in Atari supervisor-mode, the USP is undefined.

See also: The MagiC Mac cookie   Cookie and XBRA list

14.1.11.8 getBaseMode

If getBaseMode is called in an interrupt, the function returns the mode that existed at the instant before the interrupt was handled.

14.1.11.9 intrLock

This must be called before switching to Atari-mode from a Macintosh routine that could run in an interrupt. In addition, one has to count on the fact that before the switch a foreign stack is active which does not belong to the address space of the Atari-mode.

Therefore one has to switch beforehand to a stack (see minStackSize) from the Atari address space. After switching back to the Macinntosh- mode one has to call intrUnlock, of course.

With the aid of these intr-semaphores one can recognize when the CPU executes commands under MagiC in a non-interrupt state. This state has to be recognized, because only then can the Macintosh background processes and other Macintosh routines be called without risk by the MagiC Mac kernel through its interrupt control routines. (While the interrupt routines or Macintosh routines are being processed, no Mac routines may be called by the MagiC Mac kernel, because the MacOS is not reentrant. During this time no Mac events are handled; even [Command]-[W]/[Q] do not function at that time).

See also: The MagiC Mac cookie   System-Cookies

14.1.11.10 macAppSwitch

Here Atari routines can hook themselves in with the XBRA procedure. They are then called in Atari-mode (supervisor-mode) when one of the specified events occurs. This is required, for instance, when an Atari program wants to make use of certain Macintosh routines. For example, a program using the sound routines of the Mac can be told in this way when MagiC Mac has been terminated to close the sound channels and to release the occupied memory.

The following values are passed in d0.W and on the stack (and must also remain there):

Value Description
   
0 Suspend
MagiC Mac is placed in the background - a different Macintosh application comes to the foreground (e.g. the Finder)
1 Resume
MagiC Mac is the foreground application again on the Macintosh side
2 Quit
MagiC Mac is terminated
3 Flag atariModePossible becomes FALSE afterwards
4 Flag atariModePossible is TRUE again

Note: The routine has to be called in Atari supervisor-mode, the USP is undefined.

See also: The MagiC Mac cookie   Cookie and XBRA list

14.1.11.11 atariModePossible

This points to a byte indicating whether a switch from the Mac to the Atari MMU-mode is possible at that instant (0=forbidden, 1=allowed). So long as the Macintosh is running without virtual memory (VM) (also without RAM-doubler), the 'modeAtari' call is always possible; however if VM is active and also the 'UnlockMemOnMacSide' flag is non-zero, then on switching from the MagiC to the Mac screen the memory occupied by MM (MagiC Mac) for the TPA will be released for offloading.

However, as soon as the VM management offloads a block, the MMU tables calculated by MM are no longer valid and must be calculated anew prior to the next switch to the Atari-mode. This is not done automatically, however, but only when switching back to the Atari screen. For this reason interrupt and other asynchronous routines that are installed under MagiC Mac by MacOS functions may not perform Atari-mode switches under the described circumstances.

Atari programs that hook into the Atari vectors (e.g. the VBL vector at $70) need not take all of this into account, since in cases when the MMU tables become invalid the Atari interrupts will not even be simulated any more. In cases where one should take further measures before or after the status of the flags alters one can install also a routine via macAppSwitch that then indicates this event with the values 3 and 4 in d0.W).

See also: Program launch and TPA   The MagiC Mac cookie

14.1.11.12 modeAtari

Before this function can be called the following conditions have to be fulfilled:

See also: The MagiC Mac cookie   Cookie and XBRA list

14.1.11.13 modeMac

This can be called at any time, also in interrupt routines, as long as the program is in the Atari-mode and in supervisor-mode at the time. After the call the whole Mac address space can be accessed.

The memory that starts in Atari-mode at address zero, starts in the Mac-mode at the position to which atariZeroPage points. If a switch was made from a normal Atari application to the Mac-mode with modeMac, then only those MacOS routines may be called that may also be called in an interrupt (see 'Inside Macintosh'); if necessary one also has to place in register a5 the value from macA5. Other routines should be called only with callMacContext, particularly those that use the QuitDraw routines - if appropriate this has to be tried out. If a call of callMacContext is required, this can be recognized often by the fact that bus errors occur otherwise, or no texts appear in dialog boxes etc.

See also: The MagiC Mac cookie   Cookie and XBRA list

14.1.11.14 versionOfMacAppl

With this one obtains the version identifier of the running MagiC Mac application (i.e. the ID that can also be displayed in the Finder). At last programs can adjust themselves to the MM versions!

14.1.11.15 giveTimeToMac

This serves for ceding time to Mac event handling of MagiC Mac if the computer spends too long in Mac-mode (sensible from 1/60s onwards), e.g. while waiting for completion of asynchronous processes.

'giveTimeToMac' can be called as often as desired; the Mac events are in any case only polled as frequently as set in the Preferences (normal: every 1/60s, which is also the maximum frequency). In order to call the routine, the complete Mac context must be fashioned, i.e. the applications stack must be active and a5 set accordingly (this is achieved for instance with callMacContext). The routine performs no other actions that do not happen otherwise as well when the Atari-mode is active and during this the Mac events are polled automatically in turn. A specialty is that the routine does not evaluate a pending Quit command, so that the routine that calls 'giveTimeToMac' can assume that it will be its turn again immediately (as long as a fatal error does not occur).

See also:The MagiC Mac cookie   Cookie and XBRA list

14.1.11.16 minStackSize

This specifies the minimum size for the supervisor stack, in case a program has to reserve such stack space itself (for example when a callback routine is called from MacOS and this then wants to call a routine in Atari-mode, because one has to ensure there that the SP when switching to the Atari-mode lies within the Atari address space and this can only be effected with an own, local stack).

Warning: It is imperative that one keeps to this value, because though 5 kb suffice on the older 68k machines as a rule, on the newer PCI PowerMacs over 12 kb is required when the network (Ether-Talk) is active! However, it is best if one forgoes the creation of one's own supervisor stack completely, to avoid such problems in the future. In case of doubt one should contact the author of the MagiC Mac kernel!

See also:The MagiC Mac cookie   Cookie and XBRA list

14.1.11.17 ext

This offers various help functions of the MagiC Mac kernel. The call has to be made from Atari-mode (user- or supervisor-mode). Calls from interrupts are not permitted.

For this one passes a function number in the function parameter and a pointer to possibly additionally required data in the data parameter. On calling undefined function numbers the return value of the function will always be -1. The functions:

Value Description
   
0 extMax
data is unused (pass NULL!), the return will be the highest implemented function number.
1 extAlert
Displays a generic Mac dialog (alert). data points to a NULL- terminated string (255 characters maximum!) that is displayed in the dialog. Warning: Umlauts and other accented characters must have Mac codings. For newlines simply insert a CR.
Return value: Always zero.
2 extAUXOpenErr
Displays a Mac alert with a text (adapted to the language in use) that the serial port cannot be opened because it is occupied (is required by HSMODEM/MACM1). data is unused. Return value: Always zero.
3 extFSSpecToPath
Converts a Macintosh filepath to a GEMDOS-conform path. data points to the following structure: First an FSSpec (see Mac docs), followed by a buffer with room for 256 characters. This buffer is filled by a C-string that describes a complete pathname, with which the file can be accessed via GEMDOS file functions. It may be a good idea later that this path goes via the pseudo-drive 'u:\', in which all currently present Mac drives are then available. One must also take into account that we are dealing with file and folder names that do not fit into the 8+3 scheme.
If we are dealing with a folder, then the path is terminated with '\' in any case. If a path cannot be obtained, say because none of the configured MagiC drives 'sees' the relevant folder, the function returns the value -2. On success, a 0 is returned.

Warning: This function may take some time under certain circumstances, as all the directories used by MM may have to be searched through; therefore do not airily call it up continuously if you can avoid it!

See also: The MagiC Mac cookie   Cookie and XBRA list

14.1.11.18 extMac

Corresponds to 'ext', though the call must be made in the Mac context (see 'callMacContext'). It is advantageous if, due to call of other Mac functions, the program is already in the Mac-mode. Calls from interrupts are not permitted as a rule.

14.1.11.19 stackLoad

stackLoad activates a new CPU stack (a7).

This is required when one wants to call a routine in the Atari context from a Mac context during which an arbitrary CPU stack is active, i.e. before a mode-change with 'modeAtari' has been performed. A switch to another stack is necessary then, because the memory area that a7 is currently using may be blanked out through the switch to Atari-mode, which could lead to the CPU freezing (see also the relevant parts of 'Exceptions under MagiC Mac').

Instead of simply placing the a7 onto the new stack, one should use 'stackLoad'. Basically this function does the same thing, but it also informs the MacOS about this (by setting some global variables). As a result the MacOS does not check a7 periodically in the meantime. The reason is because otherwise, with certain MacOS versions (prior to 7.5 and again as of 7.5.3), the MacOS would issue a stack overflow message even though this has not occurred.

If virtual memory is active, this call also prevents this stack area being offloaded, which could result in the computer freezing in some circumstances.

Usage: In a0 one should pass a pointer to a MemArea structure (see above). This must contain a pointer to the start (lowest address) of the stack as well as its length (respect 'minStackSize'!). The routine will destroy the registers a0 and a1 and sets a7 to the value of <MemArea.start+MemArea.length>.

14.1.11.20 stackUnload

The inverse of 'stackLoad'. This is to be called if the stack that was active previously is to be used again.

The routine destroys the register a0 (a7 receives again the value it had before the stackLoad call).


Home EmulatorsEmulators EmulatorsEmulators MagiC PC interfaceMagiC PC interface