16.8.3.2 Calling IoAssignResources or HalAssignSlotResources

Figure 16.10 illustrates a device driver's call to IoAssignResources.

Figure 16.10 Claiming Hardware Resources with IoAssignResources

As Figure 16.10 shows, the driver allocates a buffer, usually from paged pool as described in Section 16.4.1.3 but possibly on the stack at RequestedResources and fills it with an IO_RESOURCE_REQUIREMENTS_LIST structure containing sets of preferred and, possibly, alternative hardware resources for its device(s).

Making Calls to IoAssignResources

If an NT driver is claiming hardware resources in common for all its devices, it passes the DriverObject pointer input to the DriverEntry routine when it calls IoAssignResources. If a driver claims device-specific resources for each of its devices, it passes a NULL DriverObject pointer but the DeviceObject pointer representing a particular device in each call to claim device-specific resources.

The AllocatedResources pointer input to IoAssignResources is the address of a variable in which IoAssignResources returns the address of a buffer that it allocates for the caller. On return from a successful call to IoAssignResources, this buffer contains a CM_RESOURCE_LIST describing the set of hardware resources claimed in the registry for the caller. A driver can use these values in subsequent calls to HalTranslateBusAddress, HalGetInterruptVector, and/or HalGetAdapter.

An NT driver that calls HalAssignSlotResources also calls IoAssignResources indirectly. That is, HalAssignSlotResources allocates and sets up RequestedResources and calls IoAssignResources on behalf of its caller.

Note that the IO_RESOURCE_REQUIREMENTS_LIST structure does not have any DeviceSpecificData member as the resource descriptor(s) in the CM_RESOURCE_LIST returned by IoAssignResources or HalAssignSlotResources do. On return from a successful call to either of these routines, these DeviceSpecificData member(s) are empty. The caller can add appropriate DeviceSpecificData configuration information to the CM_RESOURCE_LIST and call IoReportResourceUsage, as described in the preceding section, to add this hardware configuration information to the registry.

As for IoReportResourceUsage, the DriverClassName parameter to IoAssignResources or HalAssignSlotResources is optional, but passing a NULL DriverClassName causes the caller's resource claims to be written under the default key ..\Other. For more information about supplying an appropriate Unicode string at DriverClassName, see Section 16.8.3.1.

Handling Resource Conflicts and Releasing Resources

If IoAssignResources or HalAssignSlotResources does not return STATUS_SUCCESS and a driver cannot carry out I/O operations without the specified hardware resources, the DriverEntry routine must release every system resource it has set up (free memory it has allocated, disconnect its interrupt objects, delete its device objects, and so forth), because that driver will be unloaded when its DriverEntry routine returns control, before the driver's Reinitialize routine, if any, is called.

When an NT driver's Unload routine is called, it must call IoAssignResources with a NULL value for RequestedResources or call IoReportResourceUsage with appropriate parameters, as described in the preceding section. Such a call removes the driver's resource list from the registry, releasing the resource(s) it claimed in its DriverEntry routine. For more information about the Unload routine, see Chapters 4 and 15.