Función WdfCommonBufferCreateWithConfig (wdfcommonbuffer.h)

Artículo
08/08/2023

[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 de 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 para 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 de trabajo 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.

Comentarios

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 de búfer para el búfer. El requisito de alineación del búfer invalida el requisito de alineación del búfer que el controlador especificó 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 especificado por WdfDeviceSetAlignmentRequirement .

Una vez que el controlador llame a WdfCommonBufferCreateWithConfig, el controlador debe:

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

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, se habilita la memoria almacenada en caché. 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.1
Encabezado	wdfcommonbuffer.h (incluya WdfCommonBuffer.h)
Library	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)