Inside Macintosh: Devices /: Chapter 1 - Device Manager

Summary of the Device Manager

C Summary

Constants

enum {
   /* request codes passed by the Device Manager to a driver's 
      prime routine */
   aRdCmd            = 2,     /* read operation requested */
   aWrCmd            = 3      /* write operation requested */
};
enum {
   /* flags used in the driver header and device control entry */
   dNeedLockMask    = 0x4000, /* set if driver must be locked in memory as
                                 soon as it is opened */ 
   dNeedTimeMask    = 0x2000, /* set if driver needs time for performing
                                 periodic tasks */ 
   dNeedGoodByeMask = 0x1000, /* set if driver needs to be called before the
                                 application heap is initialized */ 
   dStatEnableMask  = 0x0800, /* set if driver responds to status requests */ 
   dCtlEnableMask   = 0x0400, /* setifdriverrespondstocontrolrequests */ 
   dWritEnableMask  = 0x0200, /* set if driver responds to write requests */ 
   dReadEnableMask  = 0x0100, /* set if driver responds to read requests */ 

   /* run-time flags used in the device control entry */
   drvrActiveMask   = 0x0080, /* driver is currently processing a request */
   dRAMBasedMask    = 0x0040, /* dCtlDriver is a handle (1) or pointer (0) */ 
   dOpenedMask      = 0x0020  /* driver is open */ 
};
enum {
   /* access permissions */
   fsCurPerm         = 0,     /* retain current permission */
   fsRdPerm          = 1,     /* allow reads only */
   fsWrPerm          = 2,     /* allow writes only */
   fsRdWrPerm        = 3,     /* allow reads and writes */


   /* positioning modes */
   fsAtMark          = 0,     /* at current position */
   fsFromStart       = 1,     /* offset from beginning */
   fsFromMark        = 3,     /* offset from current position */

   /* read modes */
   rdVerify          = 64     /* read-verify mode */
};
enum {
   /* control codes */
   goodbye           = -1,    /* heap being reinitialized */
   killCode          =  1,    /* KillIO requested */
   accEvent          = 64,    /* handle an event */
   accRun            = 65,    /* time for periodic action */
   accCursor         = 66,    /* change cursor shape */
   accMenu           = 67,    /* handle menu item */
   accUndo           = 68,    /* handle undo command */
   accCut            = 70,    /* handle cut command */
   accCopy           = 71,    /* handle copy command */
   accPaste          = 72,    /* handle paste command */
   accClear          = 73     /* handle clear command */
};
enum {
   /* Chooser messages */
   chooserInitMsg    = 11,    /* the user selected this device package */
   newSelMsg         = 12,    /* the user made new device selections */
   fillListMsg       = 13,    /* fill the device list with choices */
   getSelMsg         = 14,    /* mark one or more choices as selected */
   selectMsg         = 15,    /* the user made a selection */
   deselectMsg       = 16,    /* the user canceled a selection */
   terminateMsg      = 17,    /* allows device package to clean up */
   buttonMsg         = 19     /* the user selected a button */
};

Data Types

typedef union ParamBlockRec {
   IOParam        ioParam;
   FileParam      fileParam;
   VolumeParam    volumeParam;
   CntrlParam     cntrlParam;
   SlotDevParam   slotDevParam;
   MultiDevParam  multiDevParam;
} ParamBlockRec;
typedef ParamBlockRec *ParmBlkPtr;
typedef struct IOParam {
   QElemPtr    qLink;         /* next queue entry */
   short       qType;         /* queue type */
   short       ioTrap;        /* routine trap */
   Ptr         ioCmdAddr;     /* routine address */
   ProcPtr     ioCompletion;  /* completion routine address */
   OSErr       ioResult;      /* result code */
   StringPtr   ioNamePtr;     /* pointer to driver name */
   short       ioVRefNum;     /* volume reference or drive number */
   short       ioRefNum;      /* driver reference number */
   char        ioVersNum;     /* not used by the Device Manager */
   char        ioPermssn;     /* read/write permission */
   Ptr         ioMisc;        /* not used by the Device Manager */
   Ptr         ioBuffer;      /* pointer to data buffer */
   long        ioReqCount;    /* requested number of bytes */
   long        ioActCount;    /* actual number of bytes completed */
   short       ioPosMode;     /* positioning mode */
   long        ioPosOffset;   /* positioning offset */
} IOParam;

typedef struct CntrlParam {
   QElemPtr    qLink;         /* next queue entry */
   short       qType;         /* queue type */
   short       ioTrap;        /* routine trap */
   Ptr         ioCmdAddr;     /* routine address */
   ProcPtr     ioCompletion;  /* completion routine address */
   OSErr       ioResult;      /* result code */
   StringPtr   ioNamePtr;     /* pointer to driver name */
   short       ioVRefNum;     /* volume reference or drive number */
   short       ioCRefNum;     /* driver reference number */
   short       csCode;        /* type of control or status request */
   short       csParam[11];   /* control or status information */
} CntrlParam;
typedef struct AuxDCE {
   Ptr         dCtlDriver;    /* pointer or handle to driver */
   short       dCtlFlags;     /* flags */
   QHdr        dCtlQHdr;      /* I/O queue header */
   long        dCtlPosition;  /* current R/W byte position */
   Handle      dCtlStorage;   /* handle to private storage */
   short       dCtlRefNum;    /* driver reference number */
   long        dCtlCurTicks;  /* used internally */
   GrafPtr     dCtlWindow;    /* pointer to driver's window */
   short       dCtlDelay;     /* ticks between periodic actions */
   short       dCtlEMask;     /* desk accessory event mask */
   short       dCtlMenu;      /* desk accessory menu ID */
   char        dCtlSlot;      /* slot */
   char        dCtlSlotId;    /* sResource directory ID */
   long        dCtlDevBase;   /* slot device base address */
   Ptr         dCtlOwner;     /* reserved; must be 0 */
   char        dCtlExtDev;    /* external device ID */
   char        fillByte;      /* reserved */
} AuxDCE;
typedef AuxDCE *AuxDCEPtr, **AuxDCEHandle;

Functions

Opening and Closing Device Drivers

pascal OSErr OpenDriver   (ConstStr255Param name, short *drvrRefNum);
pascal OSErr PBOpen       (ParmBlkPtr paramBlock, Boolean async);
pascal OSErr PBOpenSync   (ParmBlkPtr paramBlock);
pascal OSErr OpenSlot     (ParmBlkPtr paramBlock, Boolean async);
pascal short OpenDeskAcc  (ConstStr255Param deskAccName);
pascal OSErr CloseDriver  (short refNum);
pascal OSErr PBClose      (ParmBlkPtr paramBlock, Boolean async);
pascal OSErr PBCloseSync  (ParmBlkPtr paramBlock);
pascal void  CloseDeskAcc (short refNum);

Communicating With Device Drivers

pascal OSErr FSRead        (short refNum, long *count, void *buffPtr);
pascal OSErr PBRead        (ParmBlkPtr paramBlock, Boolean async);
pascal OSErr PBReadSync    (ParmBlkPtr paramBlock);
pascal OSErr PBReadAsync   (ParmBlkPtr paramBlock);
pascal OSErr FSWrite       (short refNum,long *count,const void *buffPtr);
pascal OSErr PBWrite       (ParmBlkPtr paramBlock, Boolean async);
pascal OSErr PBWriteSync   (ParmBlkPtr paramBlock);
pascal OSErr PBWriteAsync  (ParmBlkPtr paramBlock);

Controlling and Monitoring Device Drivers

pascal OSErr Control          (short refNum, short csCode, const void 
                               *csParamPtr);
pascal OSErr PBControl        (ParmBlkPtr paramBlock, Boolean async);
pascal OSErr PBControlSync    (ParmBlkPtr paramBlock);
pascal OSErr PBControlAsync   (ParmBlkPtr paramBlock);
pascal OSErr Status           (short refNum, short csCode, void *csParamPtr);
pascal OSErr PBStatus         (ParmBlkPtr paramBlock, Boolean async);
pascal OSErr PBStatusSync     (ParmBlkPtr paramBlock);
pascal OSErr PBStatusAsync    (ParmBlkPtr paramBlock);
pascal OSErr KillIO           (short refNum);
pascal OSErr PBKillIO         (ParmBlkPtr paramBlock, Boolean async);
pascal OSErr PBKillIOSync     (ParmBlkPtr paramBlock);
pascal OSErr PBKillIOAsync    (ParmBlkPtr paramBlock);

Driver Support Functions

pascal OSErr DriverInstall              (Ptr drvrPtr, short refNum);
pascal OSErr DriverInstallReserveMem    (Ptr drvrPtr, short refNum);
pascal OSErr DriverRemove               (short refNum);
pascal DCtlHandle GetDCtlEntry          (short refNum);

Pascal Summary

Constants

CONST
   {request codes passed by the Device Manager to a driver's prime routine}
   aRdCmd            = 2;        {read operation requested}
   aWrCmd            = 3;        {write operation requested}
   {flags used in the driver header and device control entry}
   dNeedLockMask     = $4000;    {set if driver must be locked in memory as }
                                 { soon as it is opened}
   dNeedTimeMask     = $2000;    {set if driver needs time for performing }
                                 { periodic tasks}
   dNeedGoodByeMask  = $1000;    {set if driver needs to be called before }
                                 { the application heap is initialized}
   dStatEnableMask   = $0800;    {set if driver responds to status requests}
   dCtlEnableMask    = $0400;    {set if driver responds to control requests}
   dWritEnableMask   = $0200;    {set if driver responds to write requests}
   dReadEnableMask   = $0100;    {set if driver responds to read requests}
   {run-time flags used in the device control entry}
   drvrActiveMask    = $0080;    {driver is currently processing a request}
   dRAMBasedMask     = $0040;    {dCtlDriver is a handle (1) or pointer (0)}
   dOpenedMask       = $0020;    {driver is open}
   {access permissions}
   fsCurPerm         = 0;        {retain current permission}
   fsRdPerm          = 1;        {allow reads only}
   fsWrPerm          = 2;        {allow writes only}
   fsRdWrPerm        = 3;        {allow reads and writes}

   {positioning modes}
   fsAtMark          = 0;        {at current position}
   fsFromStart       = 1;        {offset from beginning}
   fsFromMark        = 3;        {offset from current position}
   {read modes}
   rdVerify          = 64;       {read-verify mode}

   {control codes}
   goodbye           = -1;       {heap being reinitialized}
   killCode          =  1;       {KillIO requested}
   accEvent          = 64;       {handle an event}
   accRun            = 65;       {time for periodic action}
   accCursor         = 66;       {change cursor shape}
   accMenu           = 67;       {handle menu item}
   accUndo           = 68;       {handle undo command}
   accCut            = 70;       {handle cut command}
   accCopy           = 71;       {handle copy command}
   accPaste          = 72;       {handle paste command}
   accClear          = 73;       {handle clear command}
   {Chooser messages}
   chooserInitMsg    = 11;       {the user selected this device package}
   newSelMsg         = 12;       {the user made new device selections}
   fillListMsg       = 13;       {fill the device list with choices}
   getSelMsg         = 14;       {mark one or more choices as selected}
   selectMsg         = 15;       {the user made a selection}
   deselectMsg       = 16;       {the user canceled a selection}
   terminateMsg      = 17;       {allows device package to clean up}
   buttonMsg         = 19;       {the user selected a button}

Data Types

TYPE  ParamBlkType = (IOParam, FileParam, VolumeParam, CntrlParam,
                      SlotDevParam, MultiDevParam);

      ParamBlockRec =
      RECORD
         qLink:         QElemPtr;   {next queue entry}
         qType:         Integer;    {queue type}
         ioTrap:        Integer;    {routine trap}
         ioCmdAddr:     Ptr;        {routine address}
         ioCompletion:  ProcPtr;    {completion routine address}
         ioResult:      OSErr;      {result code}
         ioNamePtr:     StringPtr;  {pointer to driver name}
         ioVRefNum:     Integer;    {volume reference or drive number}
      CASE ParamBlkType OF
      IOParam:
         (ioRefNum:     Integer;    {driver reference number}
         ioVersNum:     SignedByte; {not used}
         ioPermssn:     SignedByte; {read/write permission}
         ioMisc:        Ptr;        {not used}
         ioBuffer:      Ptr;        {pointer to data buffer}
         ioReqCount:    LongInt;    {requested number of bytes}
         ioActCount:    LongInt;    {actual number of bytes}
         ioPosMode:     Integer;    {positioning mode}
         ioPosOffset:   LongInt);   {positioning offset}
      CntrlParam:
         (ioCRefNum:    Integer;    {driver reference number}
         csCode:        Integer;    {type of control or status request}
         csParam:       ARRAY[0..10] OF Integer);  {control or status info}
      END;
      ParmBlkPtr = ^ParamBlockRec;
      AuxDCE = 
      RECORD
         dCtlDriver:    Ptr;        {pointer or handle to driver}
         dCtlFlags:     Integer;    {flags}
         dCtlQHdr:      QHdr;       {driver I/O queue header}
         dCtlPosition:  LongInt;    {byte position}
         dCtlStorage:   Handle;     {handle to private storage}
         dCtlRefNum:    Integer;    {driver reference number}
         dCtlCurTicks:  LongInt;    {used internally}
         dCtlWindow:    GrafPtr;    {pointer to driver's window}
         dCtlDelay:     Integer;    {ticks between periodic actions}
         dCtlEMask:     Integer;    {event mask for desk accessories}
         dCtlMenu:      Integer;    {menu ID for desk accessories}
         dCtlSlot:      Byte;       {slot}
         dCtlSlotId:    Byte;       {sResource directory ID}
         dCtlDevBase:   LongInt;    {slot device base address}
         dCtlOwner:     Ptr;        {reserved; must be 0}
         dCtlExtDev:    Byte;       {external device ID}
         fillByte:      Byte;       {reserved}
      END;
      AuxDCEPtr         = ^AuxDCE;
      AuxDCEHandle      = ^AuxDCEPtr;

Routines

Opening and Closing Device Drivers

FUNCTION OpenDriver     (name: Str255; VAR refNum: Integer): OSErr;
FUNCTION PBOpen         (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
FUNCTION PBOpenSync     (paramBlock: ParmBlkPtr): OSErr;
FUNCTION OpenSlot       (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
FUNCTION OpenDeskAcc    (deskAccName: Str255): INTEGER;
FUNCTION CloseDriver    (refNum: Integer): OSErr;
FUNCTION PBClose        (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
FUNCTION PBCloseSync    (paramBlock: ParmBlkPtr): OSErr;
PROCEDURE CloseDeskAcc  (refNum: INTEGER);

Communicating With Device Drivers

FUNCTION FSRead         (refNum: Integer; VAR count: LongInt; 
                         buffPtr: Ptr): OSErr;
FUNCTION PBRead         (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
FUNCTION PBReadSync     (paramBlock: ParmBlkPtr): OSErr;
FUNCTION PBReadAsync    (paramBlock: ParmBlkPtr): OSErr;
FUNCTION FSWrite        (refNum: Integer: VAR count: LongInt;
                         buffPtr: Ptr): OSErr;
FUNCTION PBWrite        (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
FUNCTION PBWriteSync    (paramBlock: ParmBlkPtr): OSErr;
FUNCTION PBWriteAsync   (paramBlock: ParmBlkPtr): OSErr;

Controlling and Monitoring Device Drivers

FUNCTION Control          (refNum: Integer; csCode: Integer; 
                           csParamPtr: Ptr): OSErr;
FUNCTION PBControl        (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
FUNCTION PBControlSync    (paramBlock: ParmBlkPtr): OSErr;
FUNCTION PBControlAsync   (paramBlock: ParmBlkPtr): OSErr;
FUNCTION Status           (refNum: Integer; csCode: Integer; 
                           csParamPtr: Ptr): OSErr;
FUNCTION PBStatus         (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
FUNCTION PBStatusSync     (paramBlock: ParmBlkPtr): OSErr;
FUNCTION PBStatusAsync    (paramBlock: ParmBlkPtr): OSErr;
FUNCTION KillIO           (refNum: Integer): OSErr;
FUNCTION PBKillIO         (paramBlock: ParmBlkPtr; async: Boolean): OSErr;
FUNCTION PBKillIOSync     (paramBlock: ParmBlkPtr): OSErr;
FUNCTION PBKillIOAsync    (paramBlock: ParmBlkPtr): OSErr;

Driver Support Routines

FUNCTION DriverInstall            (drvrPtr: Ptr; refNum: Integer): OSErr;
FUNCTION DriverInstallReserveMem  (drvrPtr: Ptr; refNum: Integer): OSErr;
FUNCTION DriverRemove             (refNum: Integer): OSErr;
FUNCTION GetDCtlEntry             (refNum: Integer): DCtlHandle;

Assembly-Language Summary

Data Structures

Device Manager Parameter Block Header
0 qLink long used internally by the Device Manager
4 qType word used internally by the Device Manager
6 ioTrap word used internally by the Device Manager
8 ioCmdAddr long used internally by the Device Manager
12 ioCompletion long completion routine
16 ioResult word result code
18 ioNamePtr long driver name
22 ioVRefNum word drive number

0	qLink	long	used internally by the Device Manager
4	qType	word	used internally by the Device Manager
6	ioTrap	word	used internally by the Device Manager
8	ioCmdAddr	long	used internally by the Device Manager
12	ioCompletion	long	completion routine
16	ioResult	word	result code
18	ioNamePtr	long	driver name
22	ioVRefNum	word	drive number

I/O Parameter Structure
24 ioRefNum word driver reference number
26 ioVersNum byte not used
27 ioPermssn byte read/write permission
28 ioMisc long not used
32 ioBuffer long pointer to data buffer
36 ioReqCount long requested number of bytes
40 ioActCount long actual number of bytes
44 ioPosMode word positioning mode
46 ioPosOffset long positioning offset

Control Parameter Structure
24 ioCRefNum word driver reference number
26 csCode word type of control or status request
28 csParam 22 bytes control or status information

Trap Macros

Trap Macro Names
C and Pascal name Trap macro name
PBOpen _Open
OpenSlot _Open
PBClose _Close
PBRead _Read
PBWrite _Write
PBControl _Control
PBStatus _Status
PBKillIO _KillIO
DriverInstall _DrvrInstall
DriverRemove _DrvrRemove

C and Pascal name	Trap macro name
PBOpen	_Open
OpenSlot	_Open
PBClose	_Close
PBRead	_Read
PBWrite	_Write
PBControl	_Control
PBStatus	_Status
PBKillIO	_KillIO
DriverInstall	_DrvrInstall
DriverRemove	_DrvrRemove

Routines Requiring Jump Vectors
Routine Jump vector
Fetch JFetch
Stash JStash
IODone JIODone

Routine	Jump vector
Fetch	JFetch
Stash	JStash
IODone	JIODone

Result Codes
noErr 0 No error
controlErr -17 Driver does not respond to this control request
statusErr -18 Driver does not respond to this status request
readErr -19 Driver does not respond to read requests
writErr -20 Driver does not respond to write requests
badUnitErr -21 Driver reference number does not match unit table
unitEmptyErr -22 Driver reference number specifies a `nil` handle in unit table
openErr -23 Requested read/write permission does not match driver's open permission
closErr -24 Driver unable to complete close request
dRemovErr -25 Attempt to remove an open driver
dInstErr -26 Driver resource not found
abortErr -27 Request aborted by `KillIO`
notOpenErr -28 Driver not open
ioErr -36 Data does not match in read-verify mode

24	ioRefNum	word	driver reference number
26	ioVersNum	byte	not used
27	ioPermssn	byte	read/write permission
28	ioMisc	long	not used
32	ioBuffer	long	pointer to data buffer
36	ioReqCount	long	requested number of bytes
40	ioActCount	long	actual number of bytes
44	ioPosMode	word	positioning mode
46	ioPosOffset	long	positioning offset

24	ioCRefNum	word	driver reference number
26	csCode	word	type of control or status request
28	csParam	22 bytes	control or status information

noErr	0	No error
controlErr	-17	Driver does not respond to this control request
statusErr	-18	Driver does not respond to this status request
readErr	-19	Driver does not respond to read requests
writErr	-20	Driver does not respond to write requests
badUnitErr	-21	Driver reference number does not match unit table
unitEmptyErr	-22	Driver reference number specifies a `nil` handle in unit table
openErr	-23	Requested read/write permission does not match driver's open permission
closErr	-24	Driver unable to complete close request
dRemovErr	-25	Attempt to remove an open driver
dInstErr	-26	Driver resource not found
abortErr	-27	Request aborted by `KillIO`
notOpenErr	-28	Driver not open
ioErr	-36	Data does not match in read-verify mode

Summary of the Device Manager

C Summary

Constants

Data Types

Functions

Opening and Closing Device Drivers

Communicating With Device Drivers

Controlling and Monitoring Device Drivers

Driver Support Functions

Pascal Summary

Constants

Data Types

Routines

Opening and Closing Device Drivers

Communicating With Device Drivers

Controlling and Monitoring Device Drivers

Driver Support Routines

Assembly-Language Summary

Data Structures

Control Parameter Structure 24ioCRefNumworddriver reference number 26csCodewordtype of control or status request 28csParam22 bytescontrol or status information

Trap Macros

Trap Macro Names C and Pascal nameTrap macro name PBOpen_Open OpenSlot_Open PBClose_Close PBRead_Read PBWrite_Write PBControl_Control PBStatus_Status PBKillIO_KillIO DriverInstall_DrvrInstall DriverRemove_DrvrRemove

Routines Requiring Jump Vectors RoutineJump vector FetchJFetch StashJStash IODoneJIODone

Control Parameter Structure
24 ioCRefNum word driver reference number
26 csCode word type of control or status request
28 csParam 22 bytes control or status information

Trap Macro Names
C and Pascal name Trap macro name
PBOpen _Open
OpenSlot _Open
PBClose _Close
PBRead _Read
PBWrite _Write
PBControl _Control
PBStatus _Status
PBKillIO _KillIO
DriverInstall _DrvrInstall
DriverRemove _DrvrRemove

Routines Requiring Jump Vectors
Routine Jump vector
Fetch JFetch
Stash JStash
IODone JIODone