IoReportResourceUsage

NTSTATUS
IoReportResourceUsage(
IN PUNICODE_STRING DriverClassName, /* optional */
IN PDRIVER_OBJECT DriverObject,
IN PCM_RESOURCE_LIST DriverList, /* optional */
IN ULONG DriverListSize, /* optional */
IN PDEVICE_OBJECT DeviceObject,
IN PCM_RESOURCE_LIST DeviceList, /* optional */
IN ULONG DeviceListSize, /* optional */
IN BOOLEAN OverrideConflict,
OUT PBOOLEAN ConflictDetected
);

IoReportResourceUsage claims hardware resources, such as an interrupt vector, device memory range or a particular DMA controller channel in the \Registry\Machine\Hardware\ResourceMap tree, so that a subsequently loaded driver cannot attempt to use the same resources.

Parameters

DriverClassName: Points to a buffered Unicode String that describes the class of driver under which the resource information should be stored. A default type Other is used if none is given, and a new key is created in the registry if a unique name is supplied.
DriverObject: Points to the driver object that was input to the DriverEntry routine.
DriverList: Points to the driver’s resource list if the driver claims the same resources for all its devices. This pointer is NULL if the driver claims resources for its devices separately.
DriverListSize: Specifies the size in bytes of the driver’s resource list if the DriverList pointer is nonNULL; otherwise, zero.
DeviceObject: Points to the driver-created device object representing a device for which the driver is attempting to claim resources.
DeviceList: Points to the device’s resource list, if the driver claims resources separately for each of its devices.
DeviceListSize: Specifies the size in bytes of the DeviceList if the DeviceList pointer is nonNULL; otherwise zero.
OverrideConflict: Specifies a Boolean value that indicates whether the information should be written into the registry even if a conflict is found with another driver or device. The default value is FALSE.
ConflictDetected: Points to a Boolean value set to TRUE on return from IoReportResourceUsage if a previously loaded driver has already claimed a resource specified in the caller’s DriverList or DeviceList.

Return Value

IoReportResourceUsage can return one of the following:

STATUS_SUCCESS
STATUS_INSUFFICIENT_RESOURCES

Comments

The values supplied in the CM_RESOURCE_LIST must be identical to those found in the driver’s call to IoQueryDeviceDescription, HalGetBusDataByOffset, or HalGetBusData, not those returned by the driver’s calls to HalTranslateBusAddress, HalGetAdapter, or HalGetInterruptVector.

This routine automatically searches the configuration registry for resource conflicts between resources requested and resources claimed by previously installed drivers. The contents of DriverList or DeviceList are matched against all other resource lists stored in the registry to determine whether a conflict exists.

If no conflict is detected or if OverrideConflict is set to TRUE, this routine creates appropriate entries in the registry ResourceMap that contains the specified resource lists.

If OverrideConflict is set to FALSE, this routine logs an error recording the exact nature of the conflict that is displayed in the Win32 event viewer. If OverrideConflict is reset to TRUE, no such error is reported if a resource conflict exists and the caller’s resource list is written into the registry. However, the caller cannot use any resource for which a conflict was detected.

If a driver claims resources on a device-specific basis for more than one device, the driver must call this routine for each such device.

This routine can be called more than once for a given device or driver. If a new resource list is given, it will replace the previous resource list in the registry. A driver must call IoReportResourceUsage with a DriverList or DeviceList CM_RESOURCE_LIST in which the Count is zero to erase its claim on resources in the registry if the driver is unloaded.

A CM_RESOURCE_LIST contains two variable-sized arrays. Each array has a default size of one. If either array has more than one element, memory must be allocated dynamically to contain the additional elements. A side effect of this definition is that only one CM_PARTIAL_RESOURCE_DESCRIPTOR can be part of each CM_FULL_RESOURCE_DESCRIPTOR in the list, except for the last full resource descriptor in the CM_RESOURCE_LIST, which can have additional partial resource descriptors in its array.

As an alternative, a device driver can call HalGetBusDataByOffset or HalGetBusData to locate its device(s) and to retrieve bus-relative configuration information. Then the driver can call IoAssignResources, which encapsulates most of the functionality of IoReportResourceUsage, allows the caller to specify preferred and alternative resources in a single IO_RESOURCE_REQUIREMENTS_LIST, and returns a CM_RESOURCE_LIST specifying the hardware resources it claimed on behalf of the caller. Drivers of PCI-type devices can call HalAssignSlotResources, rather than IoReportResourceUsage or IoAssignResources.

Callers of IoReportResourceUsage must be running at IRQL PASSIVE_LEVEL.