WdfCommonBufferCreateWithConfig method

[Applies to KMDF only]

The WdfCommonBufferCreateWithConfig method creates a memory buffer that both the driver and a direct memory access (DMA) device can access simultaneously, and the method also specifies buffer configuration information.

Syntax


NTSTATUS WdfCommonBufferCreateWithConfig(
  [in]            WDFDMAENABLER DmaEnabler,
  [in]            size_t Length,
  [in]            PWDF_COMMON_BUFFER_CONFIG Config,
  [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.

Config [in]

A pointer to a WDF_COMMON_BUFFER_CONFIG structure that contains configuration information about the 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

WdfCommonBufferCreateWithConfig 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 WdfCommonBufferCreateWithConfig method allocates memory and maps it so that both the driver and a device can access it simultaneously for DMA operations.

Additionally, WdfCommonBufferCreateWithConfig enables your driver to specify a buffer alignment requirement for the buffer. The buffer alignment requirement overrides the buffer alignment requirement that the driver specified when it called WdfDeviceSetAlignmentRequirement. Your driver can use WdfCommonBufferCreateWithConfig, instead of WdfCommonBufferCreate, if you want the driver to create a buffer that has a different alignment requirement than the one that WdfDeviceSetAlignmentRequirement specified.

After your driver calls WdfCommonBufferCreateWithConfig, the driver must:

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

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

For more information about common buffers, see Using Common Buffers

Examples

The following code example initializes a WDF_COMMON_BUFFER_CONFIG structure and then creates a 10-byte buffer that is aligned on a 32-byte boundary.


WDF_COMMON_BUFFER_CONFIG  commonBufConfig;
WDFCOMMONBUFFER  commonBuffer;

WDF_COMMON_BUFFER_CONFIG_INIT(
                              &commonBufConfig,
                              FILE_32_BYTE_ALIGNMENT
                              );

status = WdfCommonBufferCreateWithConfig(
                                         DmaEnabler,
                                         10,
                                         &commonBufConfig,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &commonBuffer
                                         );
if (!NT_SUCCESS (status)) {
    return status;
}

Requirements

Minimum KMDF version

1.1

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_COMMON_BUFFER_CONFIG
WDF_OBJECT_ATTRIBUTES
WdfCommonBufferCreate
WdfCommonBufferGetAlignedLogicalAddress
WdfCommonBufferGetAlignedVirtualAddress
WdfDeviceSetAlignmentRequirement
WdfDmaEnablerCreate

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft