Функция IoGetDmaAdapter (wdm.h)
Подпрограмма 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. Версия этой структуры, возвращаемой подпрограммой, определяется следующим образом:
Если драйвер задает элемент версии структуры DEVICE_DESCRIPTION DEVICE_DESCRIPTION_VERSION или DEVICE_DESCRIPTION_VERSION1, возвращенная структура DMA_ADAPTER указывает на версию 1 структуры DMA_OPERATIONS.
Если драйвер задает версии = DEVICE_DESCRIPTION_VERSION2, возвращенная структура DMA_ADAPTER указывает на версию 2 структуры DMA_OPERATIONS, если поддерживается версия 2; в противном случае подпрограмма возвращает NULL. Драйверы должны проверить, поддерживается ли версия 2, прежде чем пытаться использовать любую функцию версии 2.
Если драйвер задает версии = DEVICE_DESCRIPTION_VERSION3, возвращенная структура DMA_ADAPTER указывает на версию 3 структуры DMA_OPERATIONS, если поддерживается версия 3; в противном случае подпрограмма возвращает NULL. Драйверы должны проверить, поддерживается ли версия 3, прежде чем пытаться использовать любую функцию версии 3. Версия 3 поддерживается начиная с Windows 8.
Драйвер PnP вызывает IoGetDmaAdapter при вызове процедуры AddDevice или при обработке запроса IRP_MN_START_DEVICE PnP на устройство. Этот IRP содержит сведения о аппаратных ресурсах устройства, которые драйвер должен предоставить в структуре DeviceDescription.
Вызывающий объект использует элемент MaximumLength в структуре DeviceDescription, чтобы указать оптимальное количество регистров карты, которые он может использовать. Диспетчер операций ввода-вывода попытается выделить достаточно регистров карты для размещения операции передачи DMA этого максимального размера. В выходных данных диспетчер ввода-вывода возвращается в параметре NumberOfMapRegisters число регистров карты, выделенных им. Драйверы должны проверить возвращаемое значение; Нет гарантии, что драйвер получит то же количество регистров карты, которые он запрашивал.
Чтобы освободить объект адаптера, драйвер должен вызвать PutDmaAdapter через указатель, возвращенный в структуре DMA_ADAPTER.
Как описано ранее, IoGetDmaAdapter возвращает NULL, если она не поддерживает версию структуры DMA_ADAPTER, указанной DeviceDescription->version. Вызывающие пользователи должны полагаться на это поведение, чтобы определить, возвращает ли подпрограмма указатель на запрошенную версию структуры DMA_ADAPTER. Если IoGetDmaAdapter возвращает указатель на версию 1 или версию 2 или версию 3 структуры DMA_ADAPTER, версия этой структуры всегда имеет значение 1. Таким образом, вызывающий объект не может использовать элемент версии возвращаемой структуры DMA_ADAPTER для различения версий 1, 2 и 3 этой структуры.
Требования
| Требование | Ценность |
|---|---|
| целевая платформа | Всеобщий |
| заголовка | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| библиотеки | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| правил соответствия DDI | HwStorPortProhibitedDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |