EvtIoAllocateResourcesForReservedRequest function

[Applies to KMDF only]

A driver's EvtIoAllocateResourcesForReservedRequest callback function allocates request-specific resources that the driver can use to process an I/O request in the future. The framework is pre-allocating the specified request object for future use in low-memory situations.

Syntax


EVT_WDF_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST EvtIoAllocateResourcesForReservedRequest;

NTSTATUS EvtIoAllocateResourcesForReservedRequest(
  _In_  WDFQUEUE Queue,
  _In_  WDFREQUEST Request
)
{ ... }

Parameters

Queue [in]

A handle to an I/O queue object.

Request [in]

A handle to a request object that the framework has created for use during future low-memory situations.

Return value

The EvtIoAllocateResourcesForReservedRequest callback function must return STATUS_SUCCESS or another status value for which NT_SUCCESS(status) equals TRUE if the function encounters no errors. Otherwise, this function must return a status value for which NT_SUCCESS(status) equals FALSE.

Remarks

A driver can register an EvtIoAllocateResourcesForReservedRequest callback function when it calls WdfIoQueueAssignForwardProgressPolicy.

If your driver registers an EvtIoAllocateResourcesForReservedRequest callback function, the framework calls the function immediately after it creates a request object that it reserves for low-memory situations.

The callback function can allocate resources that your driver will require to process a request later, if the framework uses the reserved request because of a low-memory situation.

To allocate memory for request-specific resources, an EvtIoAllocateResourcesForReservedRequest callback function might call WdfObjectAllocateContext, specifying the request object handle that the Request parameter specifies.

Alternatively or additionally, your driver might call WdfDeviceInitSetRequestAttributes before calling WdfDeviceCreate. As a result, the framework will allocate context space for each reserved request object when it creates the object.

If your driver allocates object context space for reserved request objects, the driver must reinitialize the context space when it completes an I/O request that uses a reserved request object. The framework does not reinitialize the context space of reserved request objects after use.

If your driver calls WdfDeviceInitSetRequestAttributes and specifies an EvtCleanupCallback or EvtDestroyCallback callback function for its request objects, the framework calls these callback functions for its reserved request objects only when it deletes the associated I/O queues.

The driver's request handlers can call WdfRequestIsReserved to determine if reserved request objects are being used.

For more information about how to use object context space, see Framework Object Context Space.

If the callback function successfully allocates resources, it should return STATUS_SUCCESS.

If a resource allocation error occurs, such as a low memory situation, the callback function must return an error status value. In this case, the framework stops allocating reserved request objects and uses the callback function's return value as the return value for WdfIoQueueAssignForwardProgressPolicy.

For more information about the EvtIoAllocateResourcesForReservedRequest callback function, see Guaranteeing Forward Progress of I/O Operations.

Examples

To define an EvtIoAllocateResourcesForReservedRequest 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 EvtIoAllocateResourcesForReservedRequest callback function that is named MyIoAllocateResourcesForReservedRequest, use the EVT_WDF_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST type as shown in this code example:


EVT_WDF_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST MyIoAllocateResourcesForReservedRequest;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyIoAllocateResourcesForReservedRequest (
    WDFQUEUE  Queue,
    WDFREQUEST  Request
    )
  {...}

The EVT_WDF_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST function type is defined in the Wdfio.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_IO_ALLOCATE_RESOURCES_FOR_RESERVED_REQUEST 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.9

IRQL

<=DISPATCH_LEVEL

See also

EvtIoAllocateRequestResources
WdfIoQueueAssignForwardProgressPolicy
WdfRequestIsReserved

 

 

Send comments about this topic to Microsoft

표시:
© 2014 Microsoft