DMA_CHANNEL_ALLOCATE_HANDLER callback function (netdma.h)

Article
10/21/2021

Note The NetDMA interface is not supported

in Windows 8 and later.

The ProviderAllocateDmaChannel function allocates a DMA channel.

Syntax

DMA_CHANNEL_ALLOCATE_HANDLER DmaChannelAllocateHandler;

NTSTATUS DmaChannelAllocateHandler(
  [in]  PVOID ProviderContext,
  [in]  PNET_DMA_CHANNEL_PARAMETERS ChannelParameters,
  [in]  PVOID NetDmaChannelHandle,
  [out] PVOID *pProviderChannelContext
)
{...}

Parameters

[in] ProviderContext

A pointer that identifies a DMA provider's context area. The DMA provider driver passes this handle to the NetDMA interface in a call to the NetDmaRegisterProvider function.

[in] ChannelParameters

A pointer to a NET_DMA_CHANNEL_PARAMETERS structure that defines the configuration parameters for the DMA channel.

[in] NetDmaChannelHandle

A handle that identifies the DMA channel. Provider drivers pass this handle to NetDmaXxx functions to identify the DMA channel.

[out] pProviderChannelContext

A pointer to a value that is a pointer to a DMA provider's context area for the DMA channel. The DMA provider driver allocates this context area before returning from ProviderAllocateDmaChannel. NetDMA passes the context area pointer to ProviderXxx functions that require a provider channel context.

Return value

ProviderAllocateDmaChannel returns one of the following status values:

Return code	Description
STATUS_SUCCESS	The operation completed successfully.
STATUS_RESOURCES	The operation failed because of insufficient resources.
STATUS_UNSUCCESSFUL	The operation failed for unspecified reasons.

Remarks

The NetDMA interface calls a DMA provider driver's ProviderAllocateDmaChannel function to allocate a DMA channel. The NetDMA interface calls ProviderAllocateDmaChannel before it uses a DMA channel.

The DMA provider driver attempts to allocate a DMA channel with an interrupt CPU affinity that matches a bit that is specified in the ProcessorAffinityMask member of the NET_DMA_CHANNEL_PARAMETERS structure at the ChannelParameters parameter. If MSI-X is not supported or MSI-X is supported but a DMA channel with a matching interrupt CPU affinity is not available, the DMA provider driver allocates any available DMA channel and calls the KeSetTargetProcessorDpc routine to set the target CPU of the interrupt DPC to match one of the specified affinity mask bits.

The DMA provider always driver returns the CPU number that it associated with the interrupt DPC for the DMA channel to the NetDMA interface in the CpuNumber member of the NET_DMA_CHANNEL_PARAMETERS structure.

The DMA provider driver provides a pointer to a block of driver-allocated context information at the pProviderChannelContext parameter of ProviderAllocateDmaChannel. This context area stores information about the DMA channel. The NetDMA interface passes the context information in subsequent calls to ProviderXxx functions that require a DMA channel context.

When the NetDMA interface calls ProviderAllocateDmaChannel, it provides a handle at the NetDmaChannelHandle parameter. The DMA provider driver uses this handle in subsequent calls to NetDmaXxx functions that are associated with the DMA channel.

The NetDMA interface calls the ProviderFreeDmaChannel function to free a previously allocated DMA channel.

NetDMA calls ProviderAllocateDmaChannel at IRQL <= DISPATCH_LEVEL.

Requirements

Requirement	Value
Minimum supported client	Supported for NetDMA 1.0 drivers in Windows Vista.
Target Platform	Windows
Header	netdma.h (include Netdma.h)
IRQL	<= DISPATCH_LEVEL