PATH 
ADC Home > Documentation > Hardware > Device Managers and Drivers > PCI Card Services > Designing PCI Cards and Drivers for Power Macintosh Computers


  

Control and Status Routines

Control and status routines are normally used to send and receive driver-specific information. However, you can use these routines for any kind of data transfer as long as you implement the minimum functionality described in this section. Control and status routines can execute synchronously or asynchronously, or immediate.

Listing 8-8 shows a sample control routine, DoControlCommand.

Listing 8-8 Sample driver control routine

MyDriverGlobalsPtr          gStore;

OSErr DoControlCommand (ParamBlkPtr pb)
{
    switch (pb->csCode)
    {
        case kClearAll:
            gStore->byteCount = 0;
            gStore->lastErr = 0;
            return(noErr);
        default:    /* always return controlErr for unknown csCode */
            return(controlErr);
    }
}

The control routine must return controlErr for any csCode values that are not supported. The status routine should work in a similar manner. The Device Manager uses the csCode field to specify the type of status information requested. The status routine should respond to whatever requests are appropriate for the driver and return the error code statusErr for any unsupported csCode value.

The Device Manager interprets a status request with a csCode value of 1 as a special case. When the Device Manager receives such a status request, it returns a handle to the driver's device control entry. The driver's status routine never receives this request.

Listing 8-9 shows a sample status routine, DoStatusCommand.

Listing 8-9 Sample driver status routine

MyDriverGlobalsPtr          gStore;

OSErr DoStatusCommand (ParamBlkPtr pb)
{
    switch (pb->csCode)
    {
        case kByteCount:
            pb->csParam[0] = gStore->byteCount;
            return(noErr);
        case kLastErr:
            pb->csParam[0] = gStore->lastErr;
            return(noErr);
        default:    /* always return statusErr for unknown csCode */
            return(statusErr);
    }
}

You can define driver-specific csCode values if necessary, as long as they are within the range 0x80 through 0x7FFF.


© 1999 Apple Computer, Inc. – (Last Updated 26 March 99)