3.4.1 Creating a Controller Object with a Controller Extension

If an NT driver uses a controller object, it must call IoCreateController when the driver initializes. Figure 3.13 illustrates such a call from the DriverEntry routine.

Figure 3.13 Controller Object

Like a driver-created device object, every controller object has an associated controller extension. As Figure 3.13 show, the caller of IoCreateController determines the Size of the controller extension. Its structure and contents are driver-defined.

In addition to whatever device-specific state information the driver maintains about the physical controller (or device with channels), Figure 3.13 shows a representative set of driver-defined data for a controller extension.

The PtrToControllerObject returned by IoCreateController must be passed in the driver's calls to IoAllocateController and IoFreeController, described in Section 3.4.2, next. The DriverEntry routine must store the returned controller object pointer in the device extension(s) of its driver-created device object(s) or in another driver-accessible resident storage area (nonpaged pool, allocated by the driver). If such a driver is unloaded, it also must pass the controller object pointer to IoDeleteController.

Most drivers that set up controller objects find it convenient to store a pointer to the current target device object or device extension in the controller extension. Usually, such a driver stores the controller object pointer in every one of its device extensions so that it can use the ControllerObject->ControllerExtension pointer to access driver-maintained, controller-specific state about I/O operations for every target device object.

If the physical controller represented by a controller object generates interrupts, a driver also can use the controller extension as storage for the PtrToInterruptObject(s) returned by IoConnectInterrupt. For more information about interrupt objects, see Section 3.5, later in this chapter.

IoCreateController allocates resident storage for the controller object and extension, which it initializes with zeros. If it cannot allocate the memory, IoCreateController returns a NULL pointer. If this occurs, the DriverEntry routine must fail the inititialization and should return STATUS_INSUFFICIENT_RESOURCES.