IoReportRootDevice routine

The IoReportRootDevice routine reports a device that cannot be detected by a PnP bus driver to the PnP Manager. IoReportRootDevice allows only one device per driver to be created.

Syntax


NTSTATUS IoReportRootDevice(
  _In_ PDRIVER_OBJECT DriverObject
);

Parameters

DriverObject [in]

Pointer to the driver object of the driver that detected the device.

Return value

IoReportRootDevice returns STATUS_SUCCESS on success, or the appropriate error code on failure.

Remarks

Drivers for devices that cannot be detected by a PnP bus driver use IoReportRootDevice to report their device to the system. Devices that can be detected by a PnP bus driver should be reported in response to an IRP_MN_QUERY_DEVICE_RELATIONS request.

A driver typically calls this routine from its DriverEntry routine.

IoReportRootDevice marks the device as a root-enumerated device and this identification is persistent across system boots. The PnP manager "detects" the device on the root-enumerated list and configures it like a PnP device: the PnP manager queries for device information, identifies the appropriate drivers and calls their AddDevice routines, and sends all the appropriate PnP IRPs.

The system generates a single Hardware ID string for the device, of the form ROOT\Driver where Driver is the driver's service name. A driver can provide additional hardware IDs or compatible IDs by handling the IRP_MN_QUERY_ID request.

A driver writer must provide an INF file that matches any of the specified hardware IDs or compatible IDs. The INF file should specify the original driver that called IoReportRootDevice as the driver to load for those IDs. The system uses this information to rebuild the driver stack for the device, for example on restart. Callers of IoReportRootDevice must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.

Note  Drivers should use IoReportDetectedDevice to report hardware devices that use resources but cannot be detected by a PnP bus driver instead of IoReportRootDevice.
 

Requirements

Target platform

Universal

Version

Available in Windows 8 and later versions of Windows.

Header

Ntddk.h (include Ntddk.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

PASSIVE_LEVEL (see Remarks section)

See also

AddDevice
DriverEntry
IRP_MN_QUERY_DEVICE_RELATIONS
IRP_MN_QUERY_ID
IRP_MN_START_DEVICE
IoReportDetectedDevice
IoReportResourceForDetection

 

 

Send comments about this topic to Microsoft

Show: