mirror of https://github.com/GnoConsortium/gno.git
105 lines
4.4 KiB
Plaintext
105 lines
4.4 KiB
Plaintext
Serial Interrupt Manager Tool Set
|
|
---------------------------------
|
|
|
|
The Serial Interrupt Manager (SIM) is a code module that is installed by
|
|
a permanent init (PIF) file residing in the *:System:System.Setup
|
|
directory of an Apple IIGS. SIM arbitrates serial interrupt vector
|
|
'patches' by providing a simple interface for applications and device
|
|
drivers to handle serial interrupts (from the IIGS's built-in SCC 8530)
|
|
in a manner completely consistent with Apple's guidelines on the subject.
|
|
|
|
SIM replaces the first quarter or so of the IIGS' main interrupt handler.
|
|
Most of the code is identical to that found in the ROM, with the
|
|
following notable exception: non-MIDI asynchronous serial interrupts
|
|
are handled by dispatching to routines that can be installed by using
|
|
the SIM tool.
|
|
|
|
SCC interrupt handlers installed through SIM are called, according
|
|
to Apple guidelines, immediately _after_ checking for AppleTalk and MIDI
|
|
interrupts. This prevents AppleTalk or MIDI data loss, and provides the
|
|
lowest allowable overhead in processing asynchronous serial interrupts.
|
|
Data rates of up to 57600 baud are possible with no resulting data loss.
|
|
|
|
Since SIM handles serial interrupts through its own vector, and not
|
|
the $E10024 vector, the IIGS Serial Firmware can be used in combination
|
|
with SIM; SIM always has priority over the standard firmware handlers,
|
|
and if the firmware is used to initialize a port which is already being
|
|
handled by a SIM handler a crash may result. Any suggestions for better
|
|
arbitration of the firmware are welcome. (SIM could possibly check to see
|
|
if the firmware's SerFlag has been set, and automatically uninstall
|
|
the SIM handler and queue a warning dialog in the Scheduler.)
|
|
|
|
------------------------------------------------------------------------
|
|
SIM consists of a number of routines which are accessed via the
|
|
System 6.0 SendRequest IPC mechanism. To reduce development times, SIM
|
|
comes with a library that can be used to access SIM in a language-
|
|
independent manner.
|
|
|
|
The following call descriptions show the various SIM calls in C format.
|
|
The calls expect their arguments in C order (i.e., pushing parameters
|
|
right to left).
|
|
|
|
The return value of the calls is either zero, indicating that no error
|
|
occurred, or a non-zero integer indicating the error number. All of the
|
|
calls can return SIMNotFound in the event the SIM tool could not be located.
|
|
|
|
---------------------
|
|
int SIMVersion(void)
|
|
|
|
Returns the version number (in tool version format) of the SIM tool.
|
|
|
|
Errors:
|
|
SIMNotFound - indicates that the SIM tool could not be located
|
|
($0006) Upon receiving this error, the application should
|
|
terminate attempting to install an interrupt
|
|
handler and should notify the user that the port
|
|
could not be opened.
|
|
|
|
---------------------
|
|
int InstallIntVect(word port, longword address)
|
|
|
|
InstallIntVect installs a serial handler routine into SIM's interrupt
|
|
dispatch code. 'address' is a pointer to an interrupt handler which
|
|
conforms to the serial interrupt handlers described in the Apple IIGS
|
|
Firmware Reference (which are called through the $E10024 vector).
|
|
|
|
The following steps should be taken to install a SIM handler:
|
|
|
|
Initialize SCC, but do not enable interrupts
|
|
call InstallIntVect
|
|
Enable SCC Interrupts
|
|
|
|
Errors:
|
|
SIMInvalidPort An invalid port number was specified. The only port numbers
|
|
($0005) currently supported are SIMModemPort (2) and SIMPrinterPort (1)
|
|
|
|
SIMATalkActive The specified port is already in use by AppleTalk, and thus
|
|
($0003) cannot be used.
|
|
|
|
SIMAlreadyInst Some other system component (a driver or application) already
|
|
($0001) has an interrupt handler installed for that port.
|
|
|
|
In the last two cases, an application should notify the user that the port
|
|
is busy and cannot be used, and drivers should return an error code
|
|
appropriate to the condition.
|
|
|
|
---------------------
|
|
int RemoveIntVect(word port, longword address)
|
|
|
|
RemoveIntVect is used to uninstall a previously installed interrupt handler.
|
|
The port number and address of the handler must be specified. This prevents
|
|
a program from trying to forcibly uninstall some other program's interrupt
|
|
handler, an approach which is not acceptable.
|
|
|
|
The procedure for uninstalling an interrupt handler should be as follows:
|
|
|
|
Turn of SCC interrupts and shutdown SCC chip if desired
|
|
Call RemoveIntVect
|
|
|
|
Errors:
|
|
SIMInvalidAddr The address passed to RemoveIntVect does not match the
|
|
actual address of the handler on the specified port.
|
|
|
|
SIMNotInstalled There is no handler currently installed for the specified
|
|
port.
|