Функция RtlCopyDeviceMemory (wdm.h)

Статья
05/23/2024

Функция RtlCopyDeviceMemory обеспечивает поведение RtlCopyVolatileMemory (например, копирование памяти из одного расположения в другое без вмешательства оптимизации компилятора) в ситуациях, когда разработчику необходимо дополнительно убедиться, что ошибки выравнивания не будут создаваться при доступе к памяти устройства.

Синтаксис

volatile void * RtlCopyDeviceMemory(
  [out] volatile void       *Destination,
  [in]  volatile const void *Source,
  [in]  size_t              Length
);

Параметры

[out] Destination

Указатель на начальный адрес назначения скопированного блока.

[in] Source

Указатель на начальный адрес копируемого блока памяти.

[in] Length

Размер копируемого блока памяти в байтах.

Возвращаемое значение

Возвращает значение Destination.

Функция не распознается как встроенная функция компилятора, поэтому компилятор никогда не будет оптимизировать вызов (полностью или заменить вызов эквивалентной последовательностью инструкций). Это отличается от RtlCopyMemory , для которого применяются различные оптимизации компилятора.
Когда вызов возвращается, данные копируются из источника в назначение. Эти функции обращаются к памяти к источнику и назначению только в пределах функции (например, компилятор не может переместить доступ к памяти из этой функции).
Функция может выполнять незаровненный доступ к памяти только в том случае, если ЦП поддерживает доступ к памяти устройства без привязки к памяти. Если ЦП не поддерживает незаровненный доступ к памяти устройства, будут выполняться только выровненные доступы.
Функция может обращаться к расположениям в памяти несколько раз в рамках операции копирования.
Не поддерживает операции копирования, если источник и назначение перекрывают друг друга. Если предоставляются перекрывающиеся буферы, быстрый сбой с кодом ошибки FAST_FAIL_INVALID_ARG.

Примечание

Эта функция гарантирует только соблюдение требований ЦП для доступа к памяти, сопоставленной как память устройства. Если к определенному устройству предъявляются собственные требования к доступу, эту функцию не следует использовать (и вместо этого разработчик должен реализовать собственные функции доступа). Например, эта функция не дает никаких гарантий относительно размера созданных операций доступа к памяти (если только сам ЦП не применяет эти требования).

Примечание

Эта функция работает во всех версиях Windows, а не только в последней версии. Чтобы получить объявление функции из заголовка wdm.h, необходимо использовать последнюю версию WDK. Вам также потребуется библиотека (volatileaccessk.lib) из последней версии WDK. Однако полученный драйвер будет работать нормально в более старых версиях Windows.

Пример

UCHAR* CopyBuffer;

// In this scenario we are copying data from memory mapped
// as "device memory" (for example, memory not backed by RAM). On
// some platforms like ARM64, device memory cannot tolerate
// memory accesses that are not naturally aligned (for example, a 4-byte
// load must be 4-byte aligned). Functions like memcpy, RtlCopyMemory,
// and even RtlCopyVolatileMemory may perform unaligned memory accesses
// because it is typically faster to do this.
// To ensure only naturally aligned accesses happen, use RtlCopyDeviceMemory.

RtlCopyDeviceMemory(CopyBuffer, DeviceMemoryBuffer, 100);

Требования

Требование	Значение
Заголовок	wdm.h (включая Wdm.h)
Библиотека	volatileaccessk.lib (режим ядра), volatileaccessu.lib (режим пользователя)

См. также раздел

RtlCopyMemory

RtlCopyVolatileMemory

Поделиться через