Legacy Document

Inside Macintosh: Devices /

Chapter 1 - Device Manager / Device Manager Reference

Device Manager Functions

This section describes the functions you use to

• open and close device drivers
• communicate with device drivers
• control and monitor device drivers
• write and install device drivers

The low-level Device Manager functions described in this section (those that use the parameter block structure to pass information) provide two advantages over the corresponding high-level functions:

• These functions can be executed asynchronously, returning control to your application before the operation is completed.
• In most cases, these functions provide more extensive information or perform advanced operations.

All of these functions exchange parameters with your application through a parameter block of type ParamBlockRec. When you call a low-level function, you pass the address of the parameter block to the function.

There are three versions of most low-level functions. The first takes two parameters: a pointer to the parameter block and a Boolean parameter that specifies whether the function is to execute asynchronously (true) or synchronously (false). For example, the first version of the low-level PBRead function has this declaration:

pascal OSErr PBRead(ParmBlkPtr paramBlock, Boolean async); 

The second version does not take a second parameter; instead, it adds the suffix Sync to the name of the function.

pascal OSErr PBReadSync(ParmBlkPtr paramBlock);

Similarly, the third version of the function does not take a second parameter; instead, it adds the suffix Async to the name of the function.

pascal OSErr PBReadAsync(ParmBlkPtr paramBlock);

Only the first version of each function is documented in this section. Note, however, that the second and third versions of these functions do not use the glue code that the first version uses and are therefore more efficient. See "Summary of the Device Manager," beginning on page 1-91, for a listing of all three versions of these functions.

Assembly-Language Note

All Device Manager functions are synchronous by default. If you want a function to be executed asynchronously, set bit 10 of the trap word. To execute a function immediately, set bit 9 of the trap word. You can set these bits by appending the word ASYNC or IMMED as the second argument to the trap macro. For example:

_Read, ASYNC
_Control, IMMED

You can set or test bit 10 of a trap word using the global constant asyncTrpBit. You can set or test bit 9 of the trap word using the global constant noQueueBit.

WARNING

Never call any synchronous Device Manager function at interrupt time. This includes all of the high-level functions and the synchronous versions of the low-level functions.

A synchronous request at interrupt time may block other pending I/O requests. Because the device driver cannot begin processing the synchronous request until it completes the other requests in its queue, this situation can cause the Device Manager to loop indefinitely while it waits for the device driver to complete the synchronous request.

---

Subtopics

Opening and Closing Device Drivers

Communicating With Device Drivers

Controlling and Monitoring Device Drivers

Writing and Installing Device Drivers