Legacy Document

Inside Macintosh: Devices /

Chapter 1 - Device Manager / Device Manager Reference

Data Structures

Device Manager Parameter Block

The Device Manager provides both a high-level and a low-level interface for communicating with device drivers. You pass information to the low-level functions in a parameter block structure, defined by the ParamBlockRec union.

typedef union ParamBlockRec {
   IOParam        ioParam;
   FileParam      fileParam;
   VolumeParam    volumeParam;
   CntrlParam     cntrlParam;
   SlotDevParam   slotDevParam;
   MultiDevParam  multiDevParam;
} ParamBlockRec;
typedef ParamBlockRec *ParmBlkPtr;

The Device Manager uses two forms of the parameter block: one for the open, close, read, and write functions (the IOParam structure) and another for the control and status functions (the CntrlParam structure). Other managers use other structures of the ParamBlockRec union.

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;

The first eight fields are common to both structures. Each structure also includes its own unique fields.

Field descriptions for fields common to both structures

qLink

A pointer to the next entry in the driver I/O queue. (This field is used internally by the Device Manager to keep track of asynchronous calls awaiting execution.)

qType

The queue type. (This field is used internally by the Device Manager.)

ioTrap

The trap number of the routine that was called. (This field is used internally by the Device Manager.)

ioCmdAddr

The address of the routine that was called. (This field is used internally by the Device Manager.)

ioCompletion

A pointer to a completion routine. When making asynchronous requests, you must set this field to nil if you are not specifying a completion routine. The Device Manager automatically sets this field to nil when you make a synchronous request.

ioResult

A value indicating whether the routine completed successfully. The Device Manager sets this field to 1 when it queues an asynchronous request. When the driver completes the request, it places the actual result code in this field. You can poll this field to detect when the driver has completed the request and to determine its result code. The Device Manager executes the completion routine after this field receives the result code.

ioNamePtr

A pointer to the name of the driver. You use this field only when opening a driver.

ioVRefNum

The drive number, if any. The meaning of this field depends on the device driver. The Disk Driver uses this field to identify disk devices.

Field descriptions for the IOParam structure

ioRefNum

The driver reference number.

ioVersNum

Not used.

ioPermssn

The read/write permission of the driver. When you open a driver, you must supply one of the following values in this field:

enum {		
	/* access permissions */
	fsCurPerm			 	= 0, /* retain current permission */
	fsRdPerm			 	= 1, /* allow reads only */
	fsWrPerm			 	= 2, /* allow writes only */
	fsRdWrPerm				= 3/* allow reads and writes */
};

The Device Manager compares subsequent read and write requests with the read/write permission of the driver. If the request type is not permitted, the Device Manager returns a result code indicating the error.

ioMisc

Not used.

ioBuffer

A pointer to the data buffer for the driver to use for reads or writes.

ioReqCount

The requested number of bytes for the driver to read or write.

ioActCount

The actual number of bytes the driver reads or writes.

ioPosMode

The positioning mode used by drivers of block devices. Bits 0 and 1 of this field indicate where an operation should begin relative to the physical beginning of the block-formatted medium. You can use the following constants to test or set the value of these bits:

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

The Disk Driver allows you to add the following constant to this field to specify a read-verify operation:

enum {
	rdVerify 			= 64 			/* read-verify mode */
};

See the description of the PBRead function on page 1-70.

ioPosOffset

The byte offset, relative to the position specified by the positioning mode, where the driver should perform the operation. If you specify the fsAtMark positioning mode, the Device Manager ignores this field.

Field descriptions for the CntrlParam structure

ioCRefNum

The driver reference number.

csCode

A value identifying the type of control or status request. Each driver may interpret this number differently.

csParam

The control or status information passed to or from the driver. This field is declared generically as an array of eleven integers. Each driver may interpret the contents of this field differently. Refer to the driver's documentation for specific information.