PCONFIGURE_ADAPTER_CHANNEL callback function (wdm.h)

Article
02/25/2022

The ConfigureAdapterChannel routine invokes a custom function that is implemented by the DMA controller represented by an adapter object.

Syntax

PCONFIGURE_ADAPTER_CHANNEL PconfigureAdapterChannel;

NTSTATUS PconfigureAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] ULONG FunctionNumber,
  [in] PVOID Context
)
{...}

Parameters

[in] DmaAdapter

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

[in] FunctionNumber

The number of the custom function to select. For more information, see the Remarks section.

[in] Context

A pointer to the configuration parameters for the custom function that is specified by FunctionNumber. The function is implemented by the DMA controller and can be accessed by a device driver through the adapter object. The DMA controller and the device driver must agree on the meaning of these configuration parameters. The data that Context points to is opaque to the operating system.

Return value

ConfigureAdapterChannel returns STATUS_SUCCESS if the call is successful. Possible error return values include the following status code.

Return value	Description
STATUS_NOT_IMPLEMENTED	The DMA extension does not implement the function specified by FunctionNumber.

Remarks

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

Use ConfigureAdapterChannel only for system DMA adapters. Do not use this routine for a bus-master adapter.

A particular system DMA controller might have special hardware features that device drivers can access through a set of one or more custom functions. A controller might implement more than one custom function, in which case each function is identified by a different function number. These functions abstract the DMA hardware features so that the same functions can be supported on different hardware platforms.

Typically, a custom function sets state information in the DMA controller to configure hardware features for use in subsequent DMA transfers.

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