функция обратного вызова PGET_DMA_TRANSFER_INFO (wdm.h)

Статья
08/08/2023

Подпрограмма GetDmaTransferInfo вычисляет требования к выделению для передачи DMA точечной и сборной данных.

Синтаксис

PGET_DMA_TRANSFER_INFO PgetDmaTransferInfo;

NTSTATUS PgetDmaTransferInfo(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      ULONGLONG Offset,
  [in]      ULONG Length,
  [in]      BOOLEAN WriteOnly,
  [in, out] PDMA_TRANSFER_INFO TransferInfo
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER . Эта структура представляет собой объект адаптера, представляющий master устройства DMA или системного канала DMA водителя. Вызывающий объект получил этот указатель из предыдущего вызова процедуры IoGetDmaAdapter .

[in] Mdl

Указатель на цепочку MDL, описывающую страницы памяти, которые необходимо передать. Дополнительные сведения см. в разделе «Примечания».

[in] Offset

Начальное смещение для передачи точечной и сборной DMA. Этот параметр представляет собой смещение в байтах от начала буфера в первом MDL-файле в цепочке MDL. Если многомерные списки в цепочке MDL указывают общее количество N байт буферного пространства, допустимые значения Offset находятся в диапазоне от 0 до N–1.

[in] Length

Длина передачи DMA (в байтах). Если в цепочке MDL указано в общей сложности N байт буферного пространства, допустимые значения Length находятся в диапазоне от 1 до N–Offset.

[in] WriteOnly

Указывает, является ли передача операцией только для записи (то есть передачей из памяти на устройство). Если параметр WriteOnly имеет значение TRUE, возвращаемые сведения о передаче могут быть недопустимыми для транзакции чтения. Этот параметр может указывать на то, что для обеспечения когерентности кэша требуются дополнительные операции управления кэшем на границах буфера.

[in, out] TransferInfo

Указатель на структуру DMA_TRANSFER_INFO , выделенную вызывающим объектом. Перед вызовом GetDmaTransferInfo вызывающий объект должен задать для элемента Version структуры значение DMA_TRANSFER_INFO_VERSION1.

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

GetDmaTransferInfo возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные возвращаемые значения ошибок включают следующие коды состояния.

Код возврата	Описание
STATUS_NOT_SUPPORTED	Подпрограмма не поддерживает указанную версию структуры DMA_TRANSFER_INFO_XXX .

GetDmaTransferInfo не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в структуре DMA_OPERATIONS . Драйверы получают адрес этой подпрограммы, вызывая IoGetDmaAdapter с элементом Version параметра DeviceDescription , для DEVICE_DESCRIPTION_VERSION3. Если IoGetDmaAdapter возвращает значение NULL, подпрограмма недоступна на вашей платформе.

Используйте GetDmaTransferInfo , чтобы вычислить размер буфера точечной и сборной, выделяемого для подпрограмм BuildScatterGatherListEx и MapTransferEx .

GetDmaTransferInfo заменяет подпрограмму CalculateScatterGatherList и удобнее использовать с BuildScatterGatherListEx.

Параметры Mdl, Offset и Length вместе указывают коллекцию областей физической памяти, используемых в качестве буфера для передачи точечной или сборной DMA. Каждая область физической памяти обычно является страницей или частью страницы. GetDmaTransferInfo определяет требования к выделению для этой передачи. К этим требованиям относятся следующие:

Количество элементов в списке точечной и собираемой информации. Каждый элемент представляет собой SCATTER_GATHER_ELEMENT структуру, описывающую физически непрерывный блок памяти.
Объем памяти, выделяемый для хранения указанного списка точечной или собираемой информации. (Это выделение памяти включает пространство, необходимое для списка точечной и сборной, описывающего буфер ввода-вывода, но не для самого буфера ввода-вывода.)
Количество регистров карты, необходимых для преобразования физических адресов в списке точечной и собираемой диаграммы в логические адреса.

Сведения о передаче данных DMA, предоставляемые версией 1 структуры DMA_TRANSFER_INFO_XXX, см. в разделе DMA_TRANSFER_INFO_V1.

MDL описывает страницы физической памяти, лежащие в основе заблокированного непрерывного блока виртуальной памяти. Как правило, эти страницы физической памяти являются несмежными. Цепочка MDL — это упорядоченная коллекция многомерных выражений, описывающая память, которую можно использовать для буферизации данных ввода-вывода. Как правило, регионы виртуальной памяти, описанные в многомерных списках в цепочке, являются несмежными. Дополнительные сведения о многомерных и MDL-цепях см. в разделе Использование mdls.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL