[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.
NTSTATUS WdfCommonBufferCreateWithConfig( WDFDMAENABLER DmaEnabler, size_t Length, PWDF_COMMON_BUFFER_CONFIG Config, PWDF_OBJECT_ATTRIBUTES Attributes, WDFCOMMONBUFFER *CommonBuffer );
A handle to a DMA enabler object that the driver obtained by a previous call to WdfDmaEnablerCreate.
The desired size, in bytes, of the new buffer.
A pointer to a WDF_COMMON_BUFFER_CONFIG structure that contains configuration information about the buffer.
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.
A pointer to a WDFCOMMONBUFFER-typed variable that receives a handle to a common buffer object.
WdfCommonBufferCreateWithConfig returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:
||The driver supplied an invalid parameter.|
||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.
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:
- Call WdfCommonBufferGetAlignedVirtualAddress to obtain the buffer's virtual address, which the driver can use.
- Call WdfCommonBufferGetAlignedLogicalAddress to obtain the buffer's logical address, which the device can use.
The operating system determines whether to enable cached memory in the common buffer that is to be allocated. That decision is based on the processor architecture and device bus.
On computers with x86-based, x64-based, and Itanium-based processors, cached memory is enabled. On computers with ARM or ARM 64-based processors, the operating system does not automatically enable cached memory for all devices. The system relies on the ACPI_CCA method for each device to determine whether the device is cache-coherent.
For more information about common buffers, see Using Common Buffers
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;
|Minimum KMDF version||1.1|
|Header||wdfcommonbuffer.h (include WdfCommonBuffer.h)|
|Library||Wdf01000.sys (see Framework Library Versioning.)|
|DDI compliance rules||DriverCreate, KmdfIrql, KmdfIrql2|