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

Статья
02/29/2024

Подпрограмма IoGetDmaAdapter возвращает указатель на структуру адаптера DMA для физического объекта устройства.

Синтаксис

_DMA_ADAPTER * IoGetDmaAdapter(
  [in, optional] PDEVICE_OBJECT      PhysicalDeviceObject,
  [in]           _DEVICE_DESCRIPTION *DeviceDescription,
  [out]          PULONG              NumberOfMapRegisters
);

Параметры

[in, optional] PhysicalDeviceObject

Указатель на физический объект устройства для устройства, запрашивающего структуру адаптера DMA.

[in] DeviceDescription

Указатель на структуру DEVICE_DESCRIPTION , которая описывает атрибуты физического устройства. Независимо от версии, заданной в структуре DEVICE_DESCRIPTION, эта функция всегда возвращает DMA_ADAPTER->Version == 1.

[out] NumberOfMapRegisters

Указатель на максимальное число регистров карты, которые драйвер может выделить для любой операции передачи DMA, на выходе.

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

IoGetDmaAdapter возвращает указатель на структуру DMA_ADAPTER , которая содержит указатели на функции, поддерживающие системные операции DMA. Если структура не может быть выделена, подпрограмма возвращает ЗНАЧЕНИЕ NULL. См. комментарий к версии выше в описании параметра DeviceDescription .

Перед вызовом этой подпрограммы драйвер должен инициализировать DEVICE_DESCRIPTION структуру, на которую указывает DeviceDescription , а затем добавить в эту структуру соответствующие сведения о своем устройстве.

При успешном выполнении возвращаемое значение подпрограммы указывает на DMA_ADAPTER структуру. Эта структура содержит указатель на структуру DMA_OPERATIONS , которая представляет собой таблицу указателей на функции, которые впоследствии драйвер может использовать для выполнения операций DMA. Версия этой структуры, возвращаемой подпрограммой, определяется следующим образом:

Если драйвер задает для элемента Version структуры DEVICE_DESCRIPTION значение DEVICE_DESCRIPTION_VERSION или DEVICE_DESCRIPTION_VERSION1, то возвращаемая структура DMA_ADAPTER указывает на версию 1 структуры DMA_OPERATIONS .

Если драйвер задает значение Version = DEVICE_DESCRIPTION_VERSION2, то возвращаемая структура DMA_ADAPTER указывает на версию 2 DMA_OPERATIONS структуры, если поддерживается версия 2; В противном случае подпрограмма возвращает значение NULL. Драйверы должны проверка, чтобы узнать, поддерживается ли версия 2, прежде чем пытаться использовать какую-либо функцию версии 2.

Если драйвер задает значение Version = DEVICE_DESCRIPTION_VERSION3, то возвращаемая структура DMA_ADAPTER указывает на версию 3 DMA_OPERATIONS структуры, если поддерживается версия 3; В противном случае подпрограмма возвращает значение NULL. Драйверы должны проверка, чтобы узнать, поддерживается ли версия 3, прежде чем пытаться использовать какую-либо функцию версии 3. Версия 3 поддерживается начиная с Windows 8.

Драйвер PnP вызывает IoGetDmaAdapter при вызове процедуры AddDevice или при обработке запроса PnP IRP_MN_START_DEVICE для устройства. Этот IRP включает сведения об аппаратных ресурсах устройства, которые драйвер должен предоставить в структуре DeviceDescription .

Вызывающий объект использует элемент MaximumLength в структуре DeviceDescription , чтобы указать оптимальное количество регистров карты, которые он может использовать. Диспетчер операций ввода-вывода попытается выделить достаточно регистров карты для выполнения операции передачи DMA этого максимального размера. В выходных данных диспетчер ввода-вывода возвращает в параметре NumberOfMapRegisters количество выделенных регистров карты. Драйверы должны проверка возвращаемое значение. Нет никакой гарантии, что драйвер получит такое же количество регистров карты, которое он запросил.

Чтобы освободить объект адаптера, драйвер должен вызвать PutDmaAdapter через указатель, возвращенный в структуре DMA_ADAPTER .

Как описано ранее, IoGetDmaAdapter возвращает значение NULL, если не поддерживает версию структуры DMA_ADAPTER, указанную в DeviceDescription-Version>. Вызывающие абоненты должны полагаться на это поведение, чтобы определить, возвращает ли подпрограмма указатель на запрошенную версию структуры DMA_ADAPTER . Когда IoGetDmaAdapter возвращает указатель на версию 1, версию 2 или 3 структуры DMA_ADAPTER , член версии этой структуры всегда имеет значение 1. Таким образом, вызывающий объект не может использовать элемент Version возвращаемой структуры DMA_ADAPTER для различения версий 1, 2 и 3 этой структуры.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)