InitializeDmaTransferContext routine

The InitializeDmaTransferContext routine initializes an opaque DMA transfer context that is used to track pending allocations of DMA resources.

Syntax


NTSTATUS InitializeDmaTransferContext(
  _In_   PDMA_ADAPTER DmaAdapter,
  _Out_  PVOID DmaTransferContext
);

Parameters

DmaAdapter [in]

A pointer to a DMA_ADAPTER structure. This structure is the adapter object that represents the driver's bus-master DMA device or system DMA channel. The caller obtained this pointer from a previous call to the IoGetDmaAdapter routine.

DmaTransferContext [out]

A pointer to a caller-allocated buffer into which InitializeDmaTransferContext writes the initial values for the DMA transfer context. This context is opaque to the caller. The caller must allocate a buffer that is large enough to contain the DMA transfer context. The size, in bytes, of this context is specified by the DMA_TRANSFER_CONTEXT_SIZE_V1 constant in the Wdm.h header file.

Return value

InitializeDmaTransferContext returns STATUS_SUCCESS if the call is successful. Possible error return values include the following status codes.

Return codeDescription
STATUS_INVALID_PARAMETERS

This routine failed due to invalid parameter values passed by the caller.

 

Remarks

InitializeDmaTransferContext is not a system routine that can be called directly by name. This routine can be called only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter with the Version member of the DeviceDescription parameter set to DEVICE_DESCRIPTION_VERSION3. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.

An initialized DMA transfer context must be supplied as a parameter to the AllocateAdapterChannelEx, GetScatterGatherListEx, or BuildScatterGatherListEx routine. Each of these routines writes information about the requested DMA resource allocation to the DMA transfer context. This information is opaque to the caller. To cancel a pending allocation request, the caller must supply the DMA transfer context for the request to the CancelAdapterChannel routine.

The DMA transfer context that is supplied to AllocateAdapterChannelEx, GetScatterGatherListEx, or BuildScatterGatherListEx must be unique across all adapter allocation requests.

Requirements

Version

Available starting with Windows 8.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

IRQL

<= DISPATCH_LEVEL

See also

AllocateAdapterChannelEx
BuildScatterGatherListEx
CancelAdapterChannel
GetScatterGatherListEx
DMA_ADAPTER
DMA_OPERATIONS
IoGetDmaAdapter

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft