Función WdfCommonBufferCreate (wdfcommonbuffer.h)

[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:

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.

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

Consulte también

EvtDriverDeviceAdd

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreateWithConfig

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate