PINITIALIZE_DMA_TRANSFER_CONTEXT callback function (wdm.h)

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

Syntax

PINITIALIZE_DMA_TRANSFER_CONTEXT PinitializeDmaTransferContext;

NTSTATUS PinitializeDmaTransferContext(
  [in]  PDMA_ADAPTER DmaAdapter,
  [out] PVOID DmaTransferContext
)
{...}

Parameters

[in] DmaAdapter

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.

[out] DmaTransferContext

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.

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

See also

AllocateAdapterChannelEx

BuildScatterGatherListEx

CancelAdapterChannel

DMA_ADAPTER

DMA_OPERATIONS

GetScatterGatherListEx

IoGetDmaAdapter