Função FillDeviceMemory

  • Artigo

A função FillDeviceMemory define o conteúdo de um buffer sem interferência de otimizações do compilador em situações em que os desenvolvedores precisam ter certeza de que falhas de alinhamento não serão geradas ao acessar a memória do dispositivo.

Importante

Algumas informações referem-se a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Parâmetros

Parâmetro Destination [saída]

Um ponteiro para o endereço inicial do bloco de memória a ser preenchido.

Parâmetro Length [entrada]

O tamanho do bloco de memória a ser preenchido, em bytes. Esse valor deve ser menor que o tamanho do buffer de destino.

Parâmetro Fill [entrada]

O valor em bytes usado para preencher o bloco de memória.

Sintaxe

volatile void*
  FillDeviceMemory (
    _Out_writes_bytes_all_(Length) volatile void* Destination,
    SIZE_T Length,
    INT Fill
  );

Comentários

Esta API foi criada para oferecer um comportamento FillVolatileMemory (isto é, preencher o conteúdo de um buffer sem alterações por parte do compilador) em situações em que os desenvolvedores precisam ter certeza de que não ocorrerão falhas de alinhamento ao acessar a memória do dispositivo. A API possui as seguintes características:

  • A API não é reconhecida como uma função intrínseca do compilador, portanto, o compilador nunca otimizará a chamada (seja totalmente ou substituindo a chamada por uma sequência "equivalente" de instruções). Isso difere de FillMemory, que está sujeito a uma variedade de otimizações do compilador.
  • Após o término da chamada, o buffer é completamente atualizado com o valor desejado. Os acessos à memória desta função a Destination só serão realizados dentro da função (ou seja, o compilador não pode mover acessos à memória para fora desta função).
  • A API pode realizar acessos à memória não alinhados apenas se a CPU for compatível com esse tipo de acesso à memória do dispositivo. Se a CPU não for compatível com acessos não alinhados à memória do dispositivo, apenas acessos alinhados serão realizados.
  • A API pode acessar locais de memória mais de uma vez como parte da operação.

Observação

Esta função apenas garante que os requisitos da CPU para acessar a memória mapeada como memória do dispositivo sejam respeitados. Caso um dispositivo específico tenha requisitos próprios de acesso, esta função não deve ser utilizada (e os desenvolvedores deverão criar suas próprias funções de acesso). Por exemplo, essa função não garante o tamanho dos acessos de memória gerados (a menos que a própria CPU imponha esses requisitos).

Observação

Esta função é compatível com todas as versões do Windows, não apenas as mais recentes. Você precisa utilizar o SDK mais recente para obter a declaração de função do cabeçalho winbase.h. Você também precisa da biblioteca (volatileaccessu.lib) do SDK mais recente. Contudo, o binário resultante funcionará corretamente em versões anteriores do Windows.

Exemplo

// In this scenario we are setting data on memory mapped
// as "device memory" (i.e. memory not backed by RAM). On
// some platforms like ARM64, device memory cannot tolerate
// memory accesses that are not naturally aligned (i.e. a 4-byte
// load must be 4-byte aligned). Functions like memset, FillMemory,
// and even FillVolatileMemory may perform unaligned memory accesses
// because it is typically faster to do this.
// To ensure only naturally aligned accesses happen, use FillDeviceMemory.

FillDeviceMemory(DeviceMemoryBuffer, 100, 0xAA);

Requisitos

Cliente mínimo com suporte: Windows 11 Insider Preview Build TBD

Cabeçalho: winbase.h (inclua Winbase.h)

Biblioteca em modo kernel: volatileaccessk.lib

Biblioteca em modo de usuário: volatileaccessu.lib

Confira também