Função WdfCommonBufferCreateWithConfig (wdfcommonbuffer.h)

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

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.

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

Confira também

EvtDriverDeviceAdd

WDF_COMMON_BUFFER_CONFIG

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreate

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate