Fungsi CopyDeviceMemory

  • Artikel

Fungsi CopyDeviceMemory menyalin memori dari satu lokasi ke lokasi lain tanpa gangguan dari pengoptimalan pengkompilasi dalam situasi di mana pengembang perlu juga memastikan bahwa kesalahan penyelarasan tidak akan dihasilkan saat mengakses memori perangkat.

Penting

Beberapa informasi berkaitan dengan produk prarilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Parameter

Tujuan Param [keluar]

Penunjuk ke alamat awal tujuan blok yang disalin.

Sumber Param [in]

Penunjuk ke alamat awal blok memori yang akan disalin.

Panjang Param [in]

Ukuran blok memori yang akan disalin, dalam byte.

Sintaks

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

Keterangan

API ini ada untuk menyediakan perilaku CopyVolatileMemory (yaitu, menyalin memori dari satu lokasi ke lokasi lain tanpa gangguan dari pengoptimalan pengkompilasi) dalam situasi di mana pengembang perlu juga memastikan bahwa kesalahan penyelarasan tidak akan dihasilkan saat mengakses memori perangkat. API memiliki properti berikut:

  • API tidak dikenali sebagai kompilator intrinsik sehingga pengkompilasi tidak akan pernah mengoptimalkan panggilan (baik sepenuhnya, atau mengganti panggilan dengan urutan instruksi "setara"). Ini berbeda dari CopyMemory yang tunduk pada berbagai pengoptimalan pengkompilasi.
  • Saat panggilan kembali, data telah disalin dari Sumber ke Tujuan. Fungsi ini mengakses memori ke Sumber dan Tujuan hanya akan dilakukan dalam fungsi (yaitu pengkompilasi tidak dapat memindahkan akses memori dari fungsi ini).
  • API dapat melakukan akses memori yang tidak ditetapkan hanya jika CPU mendukung akses memori yang tidak ditandatangani pada memori perangkat. Jika CPU tidak mendukung akses memori perangkat yang tidak sejajar, hanya akses yang selaras yang akan dilakukan.
  • API dapat mengakses lokasi memori lebih dari sekali sebagai bagian dari operasi penyalinannya.
  • Tidak mendukung operasi penyalinan ketika Sumber dan Tujuan saling tumpang tindih. Jika buffer yang tumpang tindih disediakan, kegagalan cepat dengan kode kesalahan FAST_FAIL_INVALID_ARG.

Catatan

Fungsi ini hanya menjamin bahwa persyaratan CPU untuk mengakses memori yang dipetakan karena memori perangkat dihormati. Jika perangkat tertentu memiliki persyaratan khusus sendiri untuk diakses, fungsi ini tidak boleh digunakan (dan sebagai gantinya, pengembang harus menerapkan fungsi aksesor mereka sendiri). Misalnya, fungsi ini tidak menjamin tentang ukuran akses memori yang dihasilkan (kecuali CPU itu sendiri memberlakukan persyaratan ini).

Catatan

Fungsi ini berfungsi pada semua versi Windows, bukan hanya yang terbaru. Anda perlu menggunakan SDK terbaru untuk mendapatkan deklarasi fungsi dari winbase.h header. Anda juga memerlukan pustaka (volatileaccessu.lib) dari SDK terbaru. Namun, biner yang dihasilkan akan berjalan dengan baik pada versi Windows yang lebih lama.

Contoh

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);

Persyaratan

Klien minimum yang didukung: Windows 11 Insider Preview Build TBD

Header: winbase.h (termasuk Winbase.h)

Pustaka mode kernel: volatileaccessk.lib

Pustaka mode pengguna: volatileaccessu.lib

Baca juga