Expand Minimize

EvtReserveDma function

[Applies to KMDF only]

The EvtReserveDma event callback function is called when the framework has reserved resources to execute and release a transaction. Reserved resources include map registers and the WDM DMA adapter's lock.

Syntax


EVT_WDF_RESERVE_DMA EvtReserveDma;

VOID EvtReserveDma(
  _In_  WDFDMATRANSACTION DmaTransaction,
  _In_  PVOID Context
)
{ ... }

Parameters

DmaTransaction [in]

A handle to the DMA transaction object that represents the transaction to which DMA resources were assigned.

Context [in]

The context pointer that the driver specified in a previous call to WdfDmaTransactionAllocateResources.

Return value

This function does not return a value.

Remarks

Drivers register an EvtReserveDma event callback function by calling WdfDmaTransactionAllocateResources.

The framework calls a driver's EvtReserveDma event callback function when DMA resources have been assigned for exclusive use with the associated transaction object. The driver can initialize and execute the transaction multiple times while holding this reservation.

A driver typically initializes and then initiates the transaction from within its EvtReserveDma event callback function. For more information about the reservation sequence, see Reserving DMA Resources.

The driver may call WdfDmaTransactionFreeResources from within EvtReserveDma.

On operating systems earlier than Windows 8, EvtReserveDma must be used with an enabler that specifies a packet-mode DMA enabler. Starting with Windows 8, EvtReserveDma can also be used with an enabler that specifies a system-mode DMA enabler.

Examples

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


EVT_WDF_RESERVE_DMA  MyReserveDma;

Then, implement your callback function as follows.


_Use_decl_annotations_
BOOLEAN
 MyReserveDma (
    WDFDMATRANSACTION DmaTransaction,
    PVOID Context
    )
  {...}

The EVT_WDF_RESERVE_DMA function type is defined in the WdfDmaTransaction.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_RESERVE_DMA 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.11

Header

WdfDmaTransaction.h (include Wdf.h)

IRQL

DISPATCH_LEVEL

See also

WdfDmaTransactionAllocateResources
WdfDmaTransactionFreeResources

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.