Important: The information in this document is obsolete and should not be used for new development.
Using the Slot Manager
The Slot Manager allows you to enable and disable NuBus cards, manipulate the slot resource table, get information from slot information records, get status information, and read and change expansion cards' parameter RAM. However, the majority of Slot Manager routines search for sResources in the slot resource table or provide information from these structures.The Slot Manager provides a variety of methods to find an sResource. These methods include searching for an sResource with a particular sResource ID, searching for an sResource with a particular sResource type, searching through all sResources, searching through only the enabled sResources, and so on.
The Slot Manager also provides a number of routines that return information from sResources. Some of these routines, like the
SReadByte
andSGetCString
functions, return one particular type of data structure. Others, like theSFindStruct
function, can return information about any data structure. Functions such asSGetDriver
andSExec
not only return information from an sResource, they also perform additional operations like loading the sResource's driver or executing the code of ansExecBlock
data structure.You can use the
SVersion
function, described on page 2-30, to determine if the Slot Manager is version 1, version 2, or a version that predates System 7.Enabling and Disabling NuBus Cards
Version 1 and later of the Slot Manager allows you to temporarily disable your NuBus card. You might want to do this if, for example, you are designing a NuBus card that must be addressed in 32-bit mode or that requires RAM-based system software patches to be loaded into memory before the card is initialized. YourPrimaryInit
code can disable the card temporarily and theSecondaryInit
code can reenable it.To disable a NuBus card temporarily, the initialization routine in your
PrimaryInit
record should return in theseStatus
field of theSEBlock
data structure (described in "Slot Execution Parameter Block" on page 2-27) an error code with a value in the rangesvTempDisable
($8000) throughsvDisabled
($8080). The Slot Manager places this code in thesiInitStatusV
field of the slot information record for the slot, and places the fatal errorsmInitStatVErr
(-316) in thesiInitStatusA
field of the slot information record. The card and its sResources are then unavailable for use by the Operating System.After the Operating System loads RAM patches, the Slot Manager checks the value of the
siInitStatusA
field of each slot information record. If this value is greater than or equal to 0, indicating no error, the Slot Manager executes theSecondaryInit
code for the slot, if any. If the value in thesiInitStatusA
field issmInitStatVErr
, the Slot Manager checks thesiInitStatusV
field. If the value of thesiInitStatusV
field is in the rangesvTempDisable
throughsvDisabled
, the Slot Manager sets thesiInitStatusA
field to 0 and runs theSecondaryInit
code.For examples of
PrimaryInit
andSecondaryInit
code, see Designing Cards and Drivers for the Macintosh Family, third edition.Deleting and Restoring sResources
Some NuBus cards have sResources to support a variety of system configurations or modes. The Slot Manager loads all of the sResources during system initialization, and then the card'sPrimaryInit
code can delete from the slot resource table any sResources that are not appropriate for the system as configured. If the user changes the system configuration or selects a different mode of operation, your card can reinstall a deleted sResource. TheSDeleteSRTRec
function deletes sResources; theInsertSRTRec
function reinstalls them.Because none of the Slot Manager functions can search for sResources that have been deleted from the slot resource table, you must keep a record of all sResources you delete so that you will have the appropriate parameter values when you want to reinstall one.
When you reinstall an sResource, it may be necessary to update the
dCtlSlotId
anddCtlDevBase
fields in the slot device driver's device control entry. You need to update thedCtlSlotId
field if you change the sResource ID. ThedCtlDevBase
field holds the base address of the slot device. For a video card this is the base address for the pixel map in the card'sGDevice
record (which is described in Inside Macintosh: Imaging With QuickDraw). TheInsertSRTRec
function updates thedCtlDevBase
field automatically if you supply a valid driver reference number.Enabling and Disabling sResources
Under certain circumstances, you might want to disable an sResource while it remains listed in the slot resource table. For example, a NuBus card might provide several modes of operation, only one of which can be active at a given time. Your application might want to disable the sResources associated with all but the active mode, but still list all available modes in a menu. When the user selects a new mode, your application can then disable the currently active sResource and enable the one the user selected.You use the
SetSRsrcState
function to enable or disable an sResource. Listing 2-1 disables the sResource in slot $A with an sResource ID of 128 and enables the sResource in the same slot with an sResource ID of 131.Listing 2-1 Disabling and enabling an sResource
PROCEDURE MyDisableAndEnableSResource; VAR mySpBlk: SpBlock; myErr: OSErr; BEGIN WITH mySpBlk DO {set required values in parameter block} BEGIN spParamData := 1; {disable} spSlot := $A; {slot number} spID := 128; {sResource ID} spExtDev := 0; {ID of external device} END; myErr := SetSRsrcState(@mySpBlk); IF myErr = noErr THEN BEGIN WITH mySpBlk DO BEGIN spParamData := 0; {enable} spSlot := $A; {slot number} spID := 131; {sResource ID} spExtDev := 0; {ID of external device} END; myErr := SetSRsrcState(@mySpBlk); END; END;Searching for sResources
The Slot Manager provides several functions that search for sResources in the slot resource table. These functions allow you to specify which sResources to search, but each function provides slightly different options.The
SNextSRsrc
andSNextTypeSRsrc
functions allow you to search for enabled sResources by slot. TheSGetSRsrc
andSGetTypeSRsrc
functions, available only with the System 7 Slot Manager (that is, version 1 and version 2 of the Slot Manager), allow you to search for disabled sResources as well as enabled ones. Table 2-3 summarizes the Slot Manager search routines and the options available for each.
Table 2-3 The Slot Manager search routines
FunctionState of sResources for which it searches
Slots it
searchesWhich sResources it searches for Type of sResource it searches for SNextSRsrc
Enabled only Specified slot and higher slots Next sResource only Any type SGetSRsrc[1]
Your choice of enabled only or both enabled and disabled Your choice of one slot only or specified slot and higher slots Your choice of specified sResource or next sResource Any type SNextTypeSRsrc
Enabled only Specified slot and higher slots Next sResource only Specified type only SGetTypeSRsrc*
Your choice of enabled only or both enabled and disabled Your choice of one slot only or specified slot and higher slots Next sResource only Specified type only Listing 2-2 shows how to use the
SGetTypeSRsrc
function to search all slots for both enabled and disabled sResources with an sResource type category ofcatDisplay
and an sResource type subcategory oftypeVideo
.Listing 2-2 Searching for a specified type of sResource
PROCEDURE MySResourceSearch; VAR mySpBlk: SpBlock; myErr: OSErr; BEGIN WITH mySpBlk DO {set required values in parameter block} BEGIN spParamData := fAll; {fAll flag = 1: search all sResources} spCategory := catDisplay; {search for Category catDisplay} spCType := typeVideo; {search for cType typeVideo} spDrvrSW := 0; {this field not being matched} spDrvrHW := 0; {this field not being matched} spTBMask := 3; {match only Category and cType fields} spSlot := 1; {start search from slot 1} spID := 1; {start search from sResource ID 1} spExtDev := 0; {external device ID (card-specific)} END; myErr := noErr; WHILE myErr = noErr DO {loop to search sResources} BEGIN myErr := SGetTypeSRsrc(@mySpBlk); MySRsrcProcess(mySpBlk); {routine to process results} END; IF myErr <> smNoMoresRsrcs THEN {all search functions return this value } MyHandleError(myErr); { when search is complete} END;Obtaining Information From sResources
If you are writing a driver for a card device, you will most likely want access to the information in an sResource.The Slot Manager provides many functions that return information from the entries of an sResource. The
SOffsetData
,SReadByte
, andSReadWord
functions return information from the offset field of an sResource entry. TheSReadLong
,SGetCString
, andSGetBlock
functions return copies of the standard data structures pointed to by the offset field of an sResource entry. TheSFindStruct
andSReadStruct
functions allow access to other data structures pointed to by sResource entries.Listing 2-3 shows an example of searching for a board sResource and obtaining its name. This example starts at a particular slot number and then searches for the board sResource in that slot or, if necessary, in higher slots. Once it finds the board sResource, Listing 2-3 calls the
SGetCString
function, which returns a pointer to a buffer containing the name string for the card.Listing 2-3 Searching for the name of a board sResource
PROCEDURE FindBoardsResource (VAR slotNumber: Integer; VAR finished: Boolean); VAR mySpBlk: SpBlock; myErr: OSErr; BEGIN {First, get a pointer to the board sResource for the slot.} WITH mySpBlk DO BEGIN spSlot := slotNumber; {start searching in this slot, } { and continue until found} spID := 0; spCategory := 1; {sRsrcType values for a board sResource} spCType := 0; spDrvrSw := 0; spDrvrHw := 0; END; myErr := SNextTypeSRsrc(@mySpBlk); IF myErr <> noErr THEN MyHandleError(myErr) {quit searching if no more sResources} ELSE gTheSlot := mySpBlk.spSlot; {the slot in which the sResource was found} {The spsPointer field of mySpBlock now contains a pointer to the } { board sResource list. The SGetCString function uses this field } { as one of two input fields.} mySpBlk.spID := 2; {sRsrcName entry} myErr := SGetCString(@mySpBlk); IF myErr <> noErr THEN MyHandleError(myErr) ELSE BEGIN {The spResult field now points to a copy of the cString.} MyProcessCardName(gTheSlot, Ptr(mySpBlk.spResult)); {Free memory allocated by SGetCString.} DisposePtr(Ptr(mySpBlk.spResult)); END; END;Because theSGetCString
function allocates memory for a buffer, your application must dispose of the buffer afterward, using the Memory Manager procedureDisposePtr
(which is described in Inside Macintosh: Memory).Installing and Removing Slot Interrupt Handlers
If your card generates hardware interrupts, you can install a slot interrupt handler to process interrupts from the card. The Slot Manager maintains an interrupt queue for each slot. You use theSIntInstall
function, described on page 2-70, to install an interrupt handler in the slot interrupt queue. TheSIntRemove
function, described on page 2-71, removes an interrupt handler from the slot interrupt queue.The
SlotIntQElement
data type, described on page 2-28, defines a slot interrupt queue element. The queue elements are ordered by priority and contain pointers to interrupt handlers. When a slot interrupt occurs, the Slot Manager calls the
highest-priority interrupt handler in the slot's interrupt queue. If the interrupt handler returns without servicing the interrupt, the Slot Manager calls the next interrupt handler in the queue, in order of priority, until the interrupt is serviced. If the interrupt is not serviced by any interrupt handler, a system error dialog box is displayed.Before returning to the Slot Manager, your interrupt handler should set a result code in register D0 to indicate whether the interrupt was serviced. If the interrupt was not serviced, your interrupt handler must return 0. Any value other than 0 indicates that the interrupt was serviced.
The Slot Manager returns to the interrupted task when your interrupt handler indicates that the interrupt was serviced; otherwise, it calls the next lower-priority interrupt handler for that slot. A system error is generated if the last interrupt handler returns to the Slot Manager without servicing the interrupt.
[1] Available only with the System 7 Slot Manager (that is, version 1 and version 2 of the Slot Manager)
Subtopics
- Enabling and Disabling NuBus Cards
- Deleting and Restoring sResources
- Enabling and Disabling sResources
- Searching for sResources
- Obtaining Information From sResources
- Installing and Removing Slot Interrupt Handlers