Inside Macintosh: Devices /

Chapter 2 - Slot Manager

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 and SGetCString functions, return one particular type of data structure. Others, like the SFindStruct function, can return information about any data structure. Functions such as SGetDriver and SExec not only return information from an sResource, they also perform additional operations like loading the sResource's driver or executing the code of an sExecBlock 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. Your PrimaryInit code can disable the card temporarily and the SecondaryInit code can reenable it.

To disable a NuBus card temporarily, the initialization routine in your PrimaryInit record should return in the seStatus field of the SEBlock data structure (described in "Slot Execution Parameter Block" on page 2-27) an error code with a value in the range svTempDisable ($8000) through svDisabled ($8080). The Slot Manager places this code in the siInitStatusV field of the slot information record for the slot, and places the fatal error smInitStatVErr (-316) in the siInitStatusA 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 the SecondaryInit code for the slot, if any. If the value in the siInitStatusA field is smInitStatVErr, the Slot Manager checks the siInitStatusV field. If the value of the siInitStatusV field is in the range svTempDisable through svDisabled, the Slot Manager sets the siInitStatusA field to 0 and runs the SecondaryInit code.

For examples of PrimaryInit and SecondaryInit 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's PrimaryInit 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. The SDeleteSRTRec function deletes sResources; the InsertSRTRec 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 and dCtlDevBase fields in the slot device driver's device control entry. You need to update the dCtlSlotId field if you change the sResource ID. The dCtlDevBase 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's GDevice record (which is described in Inside Macintosh: Imaging With QuickDraw). The InsertSRTRec function updates the dCtlDevBase 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 and SNextTypeSRsrc functions allow you to search for enabled sResources by slot. The SGetSRsrc and SGetTypeSRsrc 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

Function	State of sResources for which it searches	Slots it searches	Which 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 of catDisplay and an sResource type subcategory of typeVideo.

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, and SReadWord functions return information from the offset field of an sResource entry. The SReadLong, SGetCString, and SGetBlock functions return copies of the standard data structures pointed to by the offset field of an sResource entry. The SFindStruct and SReadStruct 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 the SGetCString function allocates memory for a buffer, your application must dispose of the buffer afterward, using the Memory Manager procedure DisposePtr (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 the SIntInstall function, described on page 2-70, to install an interrupt handler in the slot interrupt queue. The SIntRemove 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