16.8.3 Claiming Hardware Resources

When a device driver’s ConfigCallback routine returns, its DriverEntry routine can use the configuration information collected from its subkeys under \Registry\Machine\Hardware\Description, from calls to HalGetBusData or HalGetBusDataByOffset, and/or from its Parameters subkey(s) under \Registry\Machine\System\CurrentControlSet\Services\DriverName in calls to one or more of HalTranslateBusAddress, HalGetInterruptVector, and HalGetAdapter. The driver can use the values returned by these HAL support routines as parameters to “higher-level” NT routines such as MmMapIoSpace, IoConnectInterrupt, HalAllocateCommonBuffer, and, after initialization IoAllocateAdapterChannel.

When an NT device driver has set up any NT objects that it needs, such as device objects, but before the driver attempts to access its device(s) registers or I/O ports, the DriverEntry routine must call one of the following support routines one or more times to write configuration information about the hardware resources the driver and its device(s) will be using into the registry:

• IoReportResourceUsage, which returns information about whether the input hardware resources have already been claimed by a previously loaded driver so NT device drivers can determine whether it is possible to initialize their devices.

  Usually, device drivers that call IoQueryDeviceDescription also call IoReportResourceUsage, possibly after supplementing the returned hardware configuration information in a buffered CM_RESOURCE_LIST that includes DeviceSpecificData.

• IoAssignResources with a buffered, driver-constructed IO_RESOURCE_REQUIREMENTS_LIST that specifies set(s) of hardware resources the driver (for all its devices) or a particular device can use, from which IoAssignResources returns a buffered CM_RESOURCE_LIST describing the set of resources it claimed in the registry.

  Usually, device drivers that call HalGetBusData also call IoAssignResources. Such a driver also might call IoReportResourceUsage with the CM_RESOURCE_LIST returned by IoAssignResources to which the driver has appended its DeviceSpecificData before calling IoReportResourceUsage.

• HalAssignSlotResources to build, on behalf of the caller, an IO_RESOURCE_REQUIREMENTS_LIST that specifies sets of hardware resources the driver of a device at a particular slot on a dynamically configurable bus with a published, standard interface, such as PCI, can use and to return a buffered CM_RESOURCE_LIST describing the set of configuration resources it claimed in the registry for the device.

  Device drivers that call HalGetBusDataByOffset or HalGetBusData with an input BusDataType for such a dynamically configurable I/O bus can call HalAssignSlotResources. Such a driver also might call HalSetBusDataByOffset or HalSetBusData to configure its device on the bus.

A successful call to IoReportResourceUsage, IoAssignResources, or HalAssignSlotResources claims a set of hardware resources for the caller in the \Registry\Machine\Hardware\ResourceMap tree. Making such a call prevents device drivers that load later from trying to use the hardware resources already claimed by a loaded driver.

    NT device driver writers should consider the following fact about calls to IoReportResourceUsage, IoAssignResources, or HalAssignSlotResources:

A subsequent call to any of the preceding support routines to claim resources for the same device(s) overwrites the existing resource claims for the driver or for the particular device in the registry ResourceMap.

Any NT device driver can call one or more of these routines more than once to claim resources for itself or for a particular device. If it does, the caller cannot attempt to claim a single resource at a time, assuming that its previously claimed resources remain claimed. Instead, such a caller must augment the list of claimed resources for the driver or for any particular device at each call to these support routines.