Função WdfCommonBufferCreate (wdfcommonbuffer.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

O método WdfCommonBufferCreate cria um buffer de memória que o driver e um dispositivo DMA (acesso direto à memória) podem acessar simultaneamente.

Sintaxe

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

Parâmetros

[in] DmaEnabler

Um identificador para um objeto de habilitador de DMA que o driver obteve por uma chamada anterior para WdfDmaEnablerCreate.

[in] Length

O tamanho desejado, em bytes, do novo buffer. O tamanho máximo permitido do buffer é (MAXULONG - PAGE_SIZE) bytes.

[in, optional] Attributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que especifica atributos de objeto para o objeto buffer comum. (O membro ParentObject da estrutura deve ser NULL.) Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] CommonBuffer

Um ponteiro para uma variável do tipo WDFCOMMONBUFFER que recebe um identificador para um objeto de buffer comum.

Retornar valor

WdfCommonBufferCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O driver forneceu um parâmetro inválido.
STATUS_INSUFFICIENT_RESOURCES	A estrutura não pôde alocar um objeto de buffer comum ou o sistema não pôde alocar um buffer.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

O método WdfCommonBufferCreate aloca memória e a mapeia para que o driver e um dispositivo possam acessá-lo simultaneamente para operações de DMA. Depois que o driver chamar WdfCommonBufferCreate, o driver deverá:

Chame WdfCommonBufferGetAlignedVirtualAddress para obter o endereço virtual do buffer, que o driver pode usar.
Chame WdfCommonBufferGetAlignedLogicalAddress para obter o endereço lógico do buffer, que o dispositivo pode usar.

Um driver normalmente chama WdfCommonBufferCreate de dentro de sua função de retorno de chamada EvtDriverDeviceAdd .

Antes que o driver chame WdfDmaEnablerCreate, ele pode chamar WdfDeviceSetAlignmentRequirement para definir um requisito de alinhamento de buffer. Se o driver não chamar WdfDeviceSetAlignmentRequirement, os buffers serão alinhados nos limites de palavras. Se o driver criar vários habilitadores de DMA, cada um com um requisito de alinhamento de buffer diferente, o driver poderá chamar WdfDeviceSetAlignmentRequirement antes de cada chamada para WdfDmaEnablerCreate.

Para criar um buffer comum que tenha um requisito de alinhamento diferente do requisito de alinhamento especificado pelo driver com WdfDeviceSetAlignmentRequirement, o driver pode chamar WdfCommonBufferCreateWithConfig em vez de WdfCommonBufferCreate.

O sistema operacional determina se a memória armazenada em cache deve ser habilitada no buffer comum a ser alocado. Essa decisão se baseia na arquitetura do processador e no barramento de dispositivo.

Em computadores com processadores baseados em x86, baseados em x64 e itanium, a memória armazenada em cache é habilitada. Em computadores com processadores baseados em ARM ou ARM 64, o sistema operacional não habilita automaticamente a memória armazenada em cache para todos os dispositivos. O sistema depende do método ACPI_CCA para cada dispositivo determinar se o dispositivo é coerente com o cache.

O objeto de habilitador DMA que o parâmetro DmaEnabler de WdfCommonBufferCreate especifica torna-se o objeto pai do novo objeto de buffer comum. O driver não pode alterar esse pai e o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES deve ser NULL. A estrutura exclui cada objeto de buffer comum quando exclui o objeto de habilitador de DMA pai. Como alternativa, você pode excluir o objeto de buffer comum explicitamente chamando WdfObjectDelete.

Para obter mais informações sobre buffers comuns, consulte Usando buffers comuns.

Exemplos

O exemplo de código a seguir mostra como obter um buffer comum. O exemplo armazena informações sobre o buffer comum no espaço de contexto definido pelo driver identificado pelo ponteiro 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	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfcommonbuffer.h (include WdfCommonBuffer.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)