Развернуть Свернуть

EvtDevicePrepareHardware function

[Applies to KMDF and UMDF]

A driver's EvtDevicePrepareHardware event callback function performs any operations that are needed to make a device accessible to the driver.

Syntax


EVT_WDF_DEVICE_PREPARE_HARDWARE EvtDevicePrepareHardware;

NTSTATUS EvtDevicePrepareHardware(
  _In_  WDFDEVICE Device,
  _In_  WDFCMRESLIST ResourcesRaw,
  _In_  WDFCMRESLIST ResourcesTranslated
)
{ ... }

Parameters

Device [in]

A handle to a framework device object.

ResourcesRaw [in]

A handle to a framework resource-list object that identifies the raw hardware resources that the Plug and Play manager has assigned to the device.

ResourcesTranslated [in]

A handle to a framework resource-list object that identifies the translated hardware resources that the Plug and Play manager has assigned to the device.

Return value

If the EvtDevicePrepareHardware callback function encounters no errors, it must return STATUS_SUCCESS or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise, it must return a status value for which NT_SUCCESS(status) equals FALSE. Do not return STATUS_NOT_SUPPORTED.

If NT_SUCCESS(status) equals FALSE, the framework calls the driver's EvtDeviceReleaseHardware callback function.

For more information about this callback function's return values, see Reporting Device Failures.

Remarks

To register an EvtDevicePrepareHardware callback function, a driver must call WdfDeviceInitSetPnpPowerEventCallbacks.

If the driver has registered an EvtDevicePrepareHardware callback function for a device, the framework calls the function after the Plug and Play manager has assigned hardware resources to the device and after the device has entered its uninitialized D0 state. (The Plug and Play manager always starts a parent device before it starts that device's child devices.)

The framework calls the driver's EvtDevicePrepareHardware callback function before calling the driver's EvtDeviceD0Entry callback function.

The EvtDevicePrepareHardware callback function accesses the device's raw and translated hardware resources by using the ResourcesRaw and ResourcesTranslated handles that it receives. The callback function can call WdfCmResourceListGetCount and WdfCmResourceListGetDescriptor to traverse the resource lists. This callback function cannot modify the resource lists.

For more information about resource lists and the order in which the resources appear, see raw and translated hardware resources.

Typically, your driver's EvtDevicePrepareHardware callback function does the following, if necessary:

  • Maps physical memory addresses to virtual addresses so the driver can access memory that is assigned to the device

  • Determines the device's revision number

  • Configures USB devices

  • Obtains driver-defined interfaces from other drivers

Optionally, your driver's EvtDevicePrepareHardware callback function might queue a work item to complete any other time-intensive configuration tasks. Using a work item for such operations can help ensure that your device's start up time does not increase the system boot time. For more information, see Using Framework Work Items.

Typically, all other hardware initialization operations, including loading firmware, should take place each time that the device enters its working (D0) state and should therefore take place in the driver's EvtDeviceD0Entry callback function.

The ResourcesRaw and ResourcesTranslated handles that the EvtDevicePrepareHardware callback function receives remain valid until the driver's EvtDeviceReleaseHardware callback function returns.

For more information about hardware resources, see Hardware Resources for Framework-Based Drivers.

For more information about when the framework calls this callback function, see PnP and Power Management Scenarios.

For more information about drivers that provide this callback function, see Supporting PnP and Power Management in Function Drivers.

Examples

To define an EvtDevicePrepareHardware callback function, you must first provide a function declaration that identifies the type of callback function 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 EvtDevicePrepareHardware callback function that is named MyDevicePrepareHardware, use the EVT_WDF_DEVICE_PREPARE_HARDWARE type as shown in this code example:


EVT_WDF_DEVICE_PREPARE_HARDWARE  MyDevicePrepareHardware;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyDevicePrepareHardware (
    WDFDEVICE  Device,
    WDFCMRESLIST  ResourcesRaw,
    WDFCMRESLIST  ResourcesTranslated
    )
 {...}

The EVT_WDF_DEVICE_PREPARE_HARDWARE function type is defined in the Wdfdevice.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 EVT_WDF_DEVICE_PREPARE_HARDWARE 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 KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfdevice.h (include Wdf.h)

IRQL

PASSIVE_LEVEL

See also

EvtDeviceReleaseHardware

 

 

Send comments about this topic to Microsoft

Показ:
© 2014 Microsoft