Función WdfCommonBufferCreateWithConfig (wdfcommonbuffer.h)

Artículo
02/07/2025

[Solo se aplica a KMDF]

El método WdfCommonBufferCreateWithConfig crea un búfer de memoria al que el controlador y un dispositivo de acceso directo a memoria (DMA) pueden acceder simultáneamente y el método también especifica información de configuración del búfer.

Sintaxis

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

Parámetros

[in] DmaEnabler

Identificador de un objeto de habilitador DMA que el controlador obtuvo mediante una llamada anterior a WdfDmaEnablerCreate.

[in] Length

Tamaño deseado, en bytes, del nuevo búfer.

[in] Config

Puntero a una estructura WDF_COMMON_BUFFER_CONFIG que contiene información de configuración sobre el búfer.

[in, optional] Attributes

Puntero a una estructura WDF_OBJECT_ATTRIBUTES que especifica atributos de objeto para el objeto de búfer común. (El miembro ParentObject de la estructura debe ser NULL). Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.

[out] CommonBuffer

Puntero a una variable con tipo WDFCOMMONBUFFER que recibe un identificador de un objeto de búfer común.

Valor devuelto

WdfCommonBufferCreateWithConfig devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	El controlador proporcionó un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	El marco no pudo asignar un objeto de búfer común o el sistema no pudo asignar un búfer.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Observaciones

El método WdfCommonBufferCreateWithConfig asigna memoria y lo asigna para que tanto el controlador como un dispositivo puedan acceder a él simultáneamente para las operaciones DMA.

Además, WdfCommonBufferCreateWithConfig permite al controlador especificar un requisito de alineación del búfer para el búfer. El requisito de alineación del búfer invalida el requisito de alineación del búfer que especificó el controlador cuando llamó a WdfDeviceSetAlignmentRequirement. El controlador puede usar WdfCommonBufferCreateWithConfig, en lugar de WdfCommonBufferCreate, si desea que el controlador cree un búfer que tenga un requisito de alineación diferente al que WdfDeviceSetAlignmentRequirement especificado.

Después de llamar al controlador WdfCommonBufferCreateWithConfig, el controlador debe:

Llame a WdfCommonBufferGetAlignedVirtualAddress para obtener la dirección virtual del búfer, que el controlador puede usar.
Llame a WdfCommonBufferGetAlignedLogicalAddress para obtener la dirección lógica del búfer, que el dispositivo puede usar.

Normalmente, un controlador llama a WdfCommonBufferCreateWithConfig desde su Función de devolución de llamada EvtDriverDeviceAdd.

El sistema operativo determina si se va a habilitar la memoria almacenada en caché en el búfer común que se va a asignar. Esa decisión se basa en la arquitectura del procesador y el bus de dispositivo.

En equipos con procesadores basados en x86, basados en x64 y basados en Itanium, la memoria almacenada en caché está habilitada. En equipos con procesadores basados en ARM o ARM 64, el sistema operativo no habilita automáticamente la memoria almacenada en caché para todos los dispositivos. El sistema se basa en el método ACPI_CCA para cada dispositivo para determinar si el dispositivo es coherente con la memoria caché.

Para obtener más información sobre los búferes comunes, consulte Uso de búferes comunes

Ejemplos

En el ejemplo de código siguiente se inicializa una estructura de WDF_COMMON_BUFFER_CONFIG y, a continuación, se crea un búfer de 10 bytes alineado en un límite de 32 bytes.

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;
}

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.1
encabezado de	wdfcommonbuffer.h (incluya WdfCommonBuffer.h)
biblioteca de	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)