Função CopyDeviceMemory

  • Artigo

A função CopyDeviceMemory copia a memória de um local para outro sem interferência das 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 destino do bloco copiado.

Parâmetro Source [entrada]

Um ponteiro para o endereço inicial do bloco de memória que será copiado.

Parâmetro Length [entrada]

O tamanho do bloco de memória a ser copiado, em bytes.

Sintaxe

volatile void*
  __cdecl
  CopyDeviceMemory (
    _Out_writes_bytes_all_(Length) volatile void* Destination,
    _In_reads_bytes_(Length) volatile const void* Source,
    SIZE_T Length
  );

Comentários

Esta API foi criada para oferecer um comportamento CopyVolatileMemory (isto é, copiar a memória de um local para outro sem interferência das otimizações 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 do CopyMemory, que está sujeito a uma variedade de otimizações do compilador.
  • Quando a chamada retorna, os dados foram copiados da Source para o Destination. Os acessos à memória desta função a Source e 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 não alinhados à memória 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 de cópia.
  • Não é compatível com operações de cópia quando Source e Destination se sobrepõem. Se forem fornecidos buffers que se sobrepõem, a operação falhará imediatamente com o código de erro FAST_FAIL_INVALID_ARG.

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, esta função não garante o tamanho dos acessos à 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

UCHAR* CopyBuffer;

// In this scenario we are copying data from 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 mempcy, CopyMemory,
// and even CopyVolatileMemory may perform unaligned memory accesses
// because it is typically faster to do this.
// To ensure only naturally aligned accesses happen, use CopyDeviceMemory.

CopyDeviceMemory(CopyBuffer, DeviceMemoryBuffer, 100);

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