Função WdfCommonBufferCreateWithConfig (wdfcommonbuffer.h)

Artigo
03/01/2024

[Aplica-se somente ao KMDF]

O método WdfCommonBufferCreateWithConfig cria um buffer de memória que o driver e um dispositivo DMA (acesso direto à memória) podem acessar simultaneamente, e o método também especifica informações de configuração de buffer.

Sintaxe

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

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.

[in] Config

Um ponteiro para uma estrutura WDF_COMMON_BUFFER_CONFIG que contém informações de configuração sobre o buffer.

[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

WdfCommonBufferCreateWithConfig 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 WdfCommonBufferCreateWithConfig aloca memória e a mapeia para que o driver e um dispositivo possam acessá-lo simultaneamente para operações de DMA.

Além disso, WdfCommonBufferCreateWithConfig permite que o driver especifique um requisito de alinhamento de buffer para o buffer. O requisito de alinhamento do buffer substitui o requisito de alinhamento do buffer especificado pelo driver quando ele chamou WdfDeviceSetAlignmentRequirement. Seu driver pode usar WdfCommonBufferCreateWithConfig, em vez de WdfCommonBufferCreate, se você quiser que o driver crie um buffer que tenha um requisito de alinhamento diferente daquele especificado por WdfDeviceSetAlignmentRequirement .

Depois que o driver chamar WdfCommonBufferCreateWithConfig, 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 WdfCommonBufferCreateWithConfig de dentro de sua função de retorno de chamada EvtDriverDeviceAdd .

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.

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

Exemplos

O exemplo de código a seguir inicializa uma estrutura WDF_COMMON_BUFFER_CONFIG e cria um buffer de 10 bytes alinhado em um limite 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
Plataforma de Destino	Universal
Versão mínima do KMDF	1,1
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)