PALLOCATE_ADAPTER_CHANNEL_EX callback function (wdm.h)

Article
02/25/2022

The AllocateAdapterChannelEx routine allocates the resources that are needed to perform a DMA transfer, and then calls the driver-supplied AdapterControl routine to initiate the DMA transfer.

Syntax

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

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.

[in] DeviceObject

A pointer to a DEVICE_OBJECT structure. This structure is the physical device object (PDO) that represents the target device for the requested DMA operation.

[in] DmaTransferContext

A pointer to an initialized DMA transfer context. This context was initialized by a previous call to the InitializeDmaTransferContext routine. This context must be unique across all adapter allocation requests. To cancel a pending allocation request, the caller must supply the DMA transfer context for the request to the CancelAdapterChannel routine.

[in] NumberOfMapRegisters

The number of map registers to use in the DMA transfer. The calling driver should set this value to the lesser of the number of map registers needed to satisfy the current transfer request, and the number of available map registers. The driver previously called the GetDmaTransferInfo routine to obtain the number of map registers needed for the transfer, and called the IoGetDmaAdapter routine to obtain the number of available map registers.

[in] Flags

The adapter channel allocation flags. The following flag is supported.

Flag	Meaning
DMA_SYNCHRONOUS_CALLBACK	The AllocateAdapterChannelEx routine is called synchronously. If this flag is set, and the required DMA resources are not immediately available, the call fails and returns STATUS_INSUFFICIENT_RESOURCES.

If the DMA_SYNCHRONOUS_CALLBACK flag is set, the ExecutionRoutine parameter is optional and can be NULL. For more information about this flag, see the Remarks section.

[in, optional] ExecutionRoutine

A pointer to the driver-supplied AdapterControl routine that initiates the DMA transfer for the driver. The I/O manager calls the AdapterControl routine after the required resources are allocated for the adapter object. After the AdapterControl routine returns, the I/O manager automatically frees the adapter object. The I/O manager might additionally free the resources that were allocated for this object, depending on the value returned by this routine.

If the DMA_SYNCHRONOUS_CALLBACK flag is set, the ExecutionRoutine is optional and can be NULL. In this case, the caller can use the resources allocated by AllocateAdapterChannelEx, and later free these resources by calling the FreeAdapterObject routine. For more information, see the Remarks section.

[in, optional] ExecutionContext

The driver-determined, adapter-control context. This context is passed to the AdapterControl routine as the Context parameter.

[out, optional] MapRegisterBase

A pointer to a variable into which the routine writes a handle to the allocated map registers. The caller can supply this handle as a parameter to the FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters, or MapTransferEx routine.

If the DMA_SYNCHRONOUS_CALLBACK flag is set, MapRegisterBase must be a valid, non-NULL pointer. If the ExecutionRoutine parameter is non-NULL, MapRegisterBase must be NULL. The call fails if MapRegisterBase is non-NULL and the DMA_SYNCHRONOUS_CALLBACK flag is not set, or if MapRegisterBase and ExecutionRoutine are both NULL.

Return value

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

Return code	Description
STATUS_INVALID_PARAMETERS	The routine failed due to invalid parameter values passed by the caller.
STATUS_INSUFFICIENT_RESOURCES	The routine failed to allocate resources required for the DMA transfer.

Remarks

AllocateAdapterChannelEx 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.

AllocateAdapterChannelEx allocates the resources that are required to perform a DMA operation. These resources include DMA channels and map registers. After all required resources are allocated for use by the DMA adapter, AllocateAdapterChannelEx calls the caller-supplied AdapterControl routine to initiate the DMA operation.

By default, AllocateAdapterChannelEx returns asynchronously, without waiting for the requested resource allocation to complete. After this return, the caller can, if necessary, cancel the pending allocation request by calling the CancelAdapterChannel routine.

If the calling driver sets the DMA_SYNCHRONOUS_CALLBACK flag, the AllocateAdapterChannelEx routine behaves as follows:

If the requested DMA resources are not immediately available, AllocateAdapterChannelEx does not wait for resources and does not call the AdapterControl routine. Instead, AllocateAdapterChannelEx fails and returns STATUS_INSUFFICIENT_RESOURCES.
The driver is not required to supply an AdapterControl routine if the DMA_SYNCHRONOUS_CALLBACK flag is set.
If the driver supplies an AdapterControl routine, the DMA_SYNCHRONOUS_CALLBACK flag indicates that this routine is to be called in the context of the calling thread, before AllocateAdapterChannelEx returns.
If the driver does not supply an AdapterControl routine, the driver can use the allocated resources after AllocateAdapterChannelEx returns. In this case, the driver must call FreeAdapterObject after it finishes using the allocated resources.

AllocateAdapterChannelEx is an extended version of the AllocateAdapterChannel routine. The following features are available only in the extended version:

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL