WdfDmaEnablerWdmGetDmaAdapter function (wdfdmaenabler.h)

Article
02/22/2024

[Applies to KMDF only]

The WdfDmaEnablerWdmGetDmaAdapter method returns a pointer to a WDM DMA_ADAPTER structure that is associated with a DMA enabler object.

Syntax

PDMA_ADAPTER WdfDmaEnablerWdmGetDmaAdapter(
  [in] WDFDMAENABLER     DmaEnabler,
  [in] WDF_DMA_DIRECTION DmaDirection
);

Parameters

[in] DmaEnabler

A handle to a DMA enabler object that the driver obtained from a previous call to WdfDmaEnablerCreate.

[in] DmaDirection

A WDF_DMA_DIRECTION-typed value that specifies the direction of the DMA transfer operation. For more information, see the following Remarks section.

Return value

WdfDmaEnablerWdmGetDmaAdapter returns a pointer to a DMA_ADAPTER structure, or NULL if the DmaDirection parameter's value is invalid.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

When your driver calls WdfDmaEnablerCreate, the framework creates a separate adapter object for each direction if the driver specifies a duplex profile, and it creates a single adapter object if the driver does not specify a duplex profile.

If your driver specified a duplex profile when it called WdfDmaEnablerCreate, the WdfDmaEnablerWdmGetDmaAdapter method's DmaDirection parameter's value must be WdfDmaDirectionReadFromDevice to obtain the DMA_ADAPTER structure for read operations and WdfDmaDirectionWriteToDevice to obtain the DMA_ADAPTER structure for write operations. If your driver did not specify a duplex profile, the driver can specify either WdfDmaDirectionReadFromDevice or WdfDmaDirectionWriteToDevice.

The pointer that WdfDmaEnablerWdmGetDmaAdapter returns is valid until the DMA enabler object is deleted. If the driver provides an EvtCleanupCallback function for the DMA enabler object, the pointer is valid until the callback function returns.

Examples

The following code example creates a DMA enabler object and then obtains pointers to the WDM DMA_ADAPTER structures that the framework creates for read and write operations.

NTSTATUS  status = STATUS_SUCCESS;
WDF_DMA_ENABLER_CONFIG  dmaConfig;
WDFDMAENABLER  dmaEnabler;
PDMA_ADAPTER  readAdapter, writeAdapter;

WDF_DMA_ENABLER_CONFIG_INIT(
                            &dmaConfig,
                            WdfDmaProfileScatterGatherDuplex,
                            maxLength
                            );
status = WdfDmaEnablerCreate(
                             Device,
                             &dmaConfig,
                             WDF_NO_OBJECT_ATTRIBUTES,
                             &dmaEnabler
                             );
if (!NT_SUCCESS (status)) {
    return status;
}

readAdapter = WdfDmaEnablerWdmGetDmaAdapter(
                                            dmaEnabler,
                                            WdfDmaDirectionReadFromDevice
                                            );
writeAdapter = WdfDmaEnablerWdmGetDmaAdapter(
                                             dmaEnabler,
                                             WdfDmaDirectionWriteToDevice
                                             );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.5
Header	wdfdmaenabler.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)