Función WdfCommonBufferCreate (wdfcommonbuffer.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfCommonBufferCreate crea un búfer de memoria al que el controlador y un dispositivo de acceso directo a memoria (DMA) pueden acceder simultáneamente.

Sintaxis

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

Parámetros

[in] DmaEnabler

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

[in] Length

Tamaño deseado, en bytes, del nuevo búfer. El tamaño máximo permitido del búfer es (MAXULONG - PAGE_SIZE) bytes.

[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 puede ser 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

WdfCommonBufferCreate 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.

Comentarios

El método WdfCommonBufferCreate asigna memoria y lo asigna para que tanto el controlador como un dispositivo puedan acceder a él simultáneamente para las operaciones DMA. Después de que el controlador llame a WdfCommonBufferCreate, 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 WdfCommonBufferCreate desde su función de devolución de llamada EvtDriverDeviceAdd .

Antes de que el controlador llame a WdfDmaEnablerCreate, puede llamar a WdfDeviceSetAlignmentRequirement para establecer un requisito de alineación del búfer. Si el controlador no llama a WdfDeviceSetAlignmentRequirement, los búferes se alinean en los límites de palabras. Si el controlador crea varios habilitadores DMA, cada uno con un requisito de alineación de búfer diferente, el controlador puede llamar a WdfDeviceSetAlignmentRequirement antes de cada llamada a WdfDmaEnablerCreate.

Para crear un búfer común que tenga un requisito de alineación diferente del requisito de alineación que el controlador especificó con WdfDeviceSetAlignmentRequirement, el controlador puede llamar a WdfCommonBufferCreateWithConfig en lugar de WdfCommonBufferCreate.

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é.

El objeto enabler DMA que el parámetro DmaEnabler de WdfCommonBufferCreate especifica se convierte en el objeto primario del nuevo objeto de búfer común. El controlador no puede cambiar este elemento primario y el miembro ParentObject de la estructura WDF_OBJECT_ATTRIBUTES debe ser NULL. El marco elimina cada objeto de búfer común cuando elimina el objeto de habilitador DMA primario. Como alternativa, puede eliminar el objeto de búfer común explícitamente llamando a WdfObjectDelete.

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 muestra cómo obtener un búfer común. En el ejemplo se almacena información sobre el búfer común en el espacio de contexto definido por el controlador identificado por el puntero DevExt .

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

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
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)