WdfCommonBufferCreate method

[Applies to KMDF only]

The WdfCommonBufferCreate method creates a memory buffer that both the driver and a direct memory access (DMA) device can access simultaneously.

Syntax


NTSTATUS WdfCommonBufferCreate(
  [in]           WDFDMAENABLER          DmaEnabler,
  [in]           size_t                 Length,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFCOMMONBUFFER        *CommonBuffer
);

Parameters

DmaEnabler [in]

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

Length [in]

The desired size, in bytes, of the new buffer.

Attributes [in, optional]

A pointer to a WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for the common buffer object. (The structure's ParentObject member must be NULL.) This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

CommonBuffer [out]

A pointer to a WDFCOMMONBUFFER-typed variable that receives a handle to a common buffer object.

Return value

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

Return codeDescription
STATUS_INVALID_PARAMETER

The driver supplied an invalid parameter.

STATUS_INSUFFICIENT_RESOURCES

The framework could not allocate a common buffer object, or the system could not allocate a buffer.

 

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

Remarks

The WdfCommonBufferCreate method allocates memory and maps it so that both the driver and a device can access it simultaneously for DMA operations. After your driver calls WdfCommonBufferCreate, the driver must:

A driver typically calls WdfCommonBufferCreate from within its EvtDriverDeviceAdd callback function.

Before the driver calls WdfDmaEnablerCreate, it can call WdfDeviceSetAlignmentRequirement to set a buffer alignment requirement. If the driver does not call WdfDeviceSetAlignmentRequirement, buffers are aligned on word boundaries. If your driver creates multiple DMA enablers, each with a different buffer alignment requirement, the driver can call WdfDeviceSetAlignmentRequirement before each call to WdfDmaEnablerCreate.

To create a common buffer that has an alignment requirement that is different from the alignment requirement that the driver specified with WdfDeviceSetAlignmentRequirement, the driver can call WdfCommonBufferCreateWithConfig instead of WdfCommonBufferCreate.

If the computer supports buffer caching, the buffer is allocated as cache-enabled.

The DMA enabler object that the DmaEnabler parameter of WdfCommonBufferCreate specifies becomes the parent object for the new common buffer object. The driver cannot change this parent, and the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure must be NULL. The framework deletes each common buffer object when it deletes the parent DMA enabler object.

For more information about common buffers, see Using Common Buffers.

Examples

The following code example shows how to obtain a common buffer. The example stores information about the common buffer in driver-defined context space that is identified by the DevExt pointer.


DevExt->CommonBufferSize = sizeof(COMMON_BUFFER_STRUCT);  // Your structure size
status = WdfCommonBufferCreate(
                               DevExt->DmaEnabler,
                               DevExt->CommonBufferSize,
                               WDF_NO_OBJECT_ATTRIBUTES,
                               &DevExt->CommonBuffer
                               );
if (status == STATUS_SUCCESS) {
    DevExt->CommonBufferBaseVA = 
        WdfCommonBufferGetAlignedVirtualAddress(DevExt->CommonBuffer);
    DevExt->CommonBufferBaseLA =
        WdfCommonBufferGetAlignedLogicalAddress(DevExt->CommonBuffer); 
}

Requirements

Target platform

Universal

Minimum KMDF version

1.0

Header

Wdfcommonbuffer.h (include WdfCommonBuffer.h)

Library

Wdf01000.sys (see Framework Library Versioning.)

IRQL

PASSIVE_LEVEL

DDI compliance rules

DriverCreate, KmdfIrql, KmdfIrql2

See also

EvtDriverDeviceAdd
WDF_OBJECT_ATTRIBUTES
WdfCommonBufferCreateWithConfig
WdfCommonBufferGetAlignedLogicalAddress
WdfCommonBufferGetAlignedVirtualAddress
WdfDeviceSetAlignmentRequirement
WdfDmaEnablerCreate

 

 

Send comments about this topic to Microsoft

Show: