WdfDmaEnablerConfigureSystemProfile function (wdfdmaenabler.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfDmaEnablerConfigureSystemProfile method configures the hardware-specific settings for a system-mode DMA enabler and completes the resource initialization.

Syntax

NTSTATUS WdfDmaEnablerConfigureSystemProfile(
  [in] WDFDMAENABLER                  DmaEnabler,
  [in] PWDF_DMA_SYSTEM_PROFILE_CONFIG ProfileConfig,
  [in] WDF_DMA_DIRECTION              ConfigDirection
);

Parameters

[in] DmaEnabler

A handle to a DMA enabler object.

[in] ProfileConfig

A pointer to a WDF_DMA_SYSTEM_PROFILE_CONFIG structure. Drivers must initialize this structure by calling WDF_DMA_SYSTEM_PROFILE_CONFIG_INIT.

[in] ConfigDirection

A WDF_DMA_DIRECTION-typed value that specifies the direction of the DMA transfer operation. If the WDF_DMA_PROFILE value for this enabler is not WdfDmaProfileSystemDuplex, the framework ignores this parameter.

Return value

WdfDmaEnablerConfigureSystemProfile returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values.

Return code	Description
STATUS_NOT_SUPPORTED	The driver requested a DMA configuration that is not supported on the current operating system.
STATUS_INVALID_PARAMETER	The driver supplied NULL in the ProfileConfig parameter.
STATUS_INFO_LENGTH_MISMATCH	The Size member of the structure pointed to by the ProfileConfig parameter is not equal to the size of the WDF_DMA_SYSTEM_PROFILE_CONFIG structure.
STATUS_INVALID_PARAMETER	The DmaDescriptor member of the structure pointed to by the ProfileConfig parameter is NULL or the ConfigDirection parameter contains an invalid value.

Remarks

Before calling WdfDmaEnablerConfigureSystemProfile, the driver must call WdfDmaEnablerCreate to create the enabler object.

A driver typically calls WdfDmaEnablerConfigureSystemProfile from its EvtDevicePrepareHardware callback function.

If your driver specified a duplex profile when it called WdfDmaEnablerCreate, the WdfDmaEnablerConfigureSystemProfile method's ConfigDirection 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 the DMA enabler is a duplex enabler, the driver must initialize a particular direction before it can use it.

If your driver did not specify a duplex profile, the driver can specify either WdfDmaDirectionReadFromDevice or WdfDmaDirectionWriteToDevice.

Examples

The following code example is from a driver's EvtDevicePrepareHardware callback function. This example initializes a WDF_DMA_SYSTEM_PROFILE_CONFIG structure and calls WdfDmaEnablerConfigureSystemProfile.


WDF_DMA_SYSTEM_PROFILE_CONFIG systemDmaConfig;  
PHYSICAL_ADDRESS pa;  
 
pa.QuadPart = 0;  
  
WDF_DMA_SYSTEM_PROFILE_CONFIG_INIT(&systemDmaConfig,   
                                   pa,  
                                   Width8Bits,  
                                   partial);  
  
systemDmaConfig.DemandMode = true;  
 
ntStatus = WdfDmaEnablerConfigureSystemProfile(fdoExtension->DmaEnabler,   
                                               &systemDmaConfig,   
                                               WdfDmaDirectionReadFromDevice);

Requirements

Requirement	Value
Minimum supported client	Windows 8
Target Platform	Universal
Minimum KMDF version	1.11
Header	wdfdmaenabler.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf)

Share via