DRIVER_ADD_DEVICE callback function (wdm.h)

Artikel
02/28/2023

The AddDevice routine is responsible for creating functional device objects (FDO) or filter device objects (filter DO) for devices enumerated by the Plug and Play (PnP) manager.

Syntax

DRIVER_ADD_DEVICE DriverAddDevice;

NTSTATUS DriverAddDevice(
  [in] _DRIVER_OBJECT *DriverObject,
  [in] _DEVICE_OBJECT *PhysicalDeviceObject
)
{...}

Parameters

[in] DriverObject

Caller-supplied pointer to a DRIVER_OBJECT structure. This is the driver's driver object.

[in] PhysicalDeviceObject

Caller-supplied pointer to a DEVICE_OBJECT structure representing a physical device object (PDO) created by a lower-level driver.

Return value

If the routine succeeds, it must return STATUS_SUCCESS. Otherwise, it must return one of the error status values defined in Ntstatus.h.

Remarks

All kernel-mode drivers that support PnP must provide an AddDevice routine.

A driver's AddDevice routine should be named XxxAddDevice, where Xxx is a driver-specific prefix. The driver's DriverEntry routine must store the AddDevice routine's address in DriverObject->DriverExtension->AddDevice.

An AddDevice routine's primary responsibilities are calling IoCreateDevice to create a device object, then calling IoAttachDeviceToDeviceStack to attach the device object to the device stack. For detailed information about implementing a driver's AddDevice routine, see Writing an AddDevice Routine.

An AddDevice routine runs in a system thread context at IRQL = PASSIVE_LEVEL.

Examples

To define an AddDevice callback routine, you must first provide a function declaration that identifies the type of callback routine you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define an AddDevice callback routine that is named MyAddDevice<, use the DRIVER_ADD_DEVICE type as shown in this code example:

DRIVER_ADD_DEVICE MyAddDevice;

Then, implement your callback routine as follows:

_Use_decl_annotations_
NTSTATUS
  MyAddDevice(
    struct _DRIVER_OBJECT  *DriverObject,
    struct _DEVICE_OBJECT  *PhysicalDeviceObject 
    )
  {
      // Function body
  }

The DRIVER_ADD_DEVICE function type is defined in the Wdm.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the DRIVER_ADD_DEVICE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for WDM Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Requirement	Value
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Called at PASSIVE_LEVEL (see Remarks section).

Delen via