Функция WdfDmaTransactionAllocateResources (wdfdmatransaction.h)

Статья
2025-03-22

[Применимо только к KMDF]

Метод WdfDmaTransactionAllocateResources резервирует однопакетную или системную функцию включения DMA для монопольного (и повторяющегося) использования с указанным объектом транзакции. Драйвер может инициализировать и инициировать транзакцию несколько раз при удержании зарезервированных ресурсов.

Синтаксис

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

Параметры

[in] DmaTransaction

Дескриптор объекта транзакции DMA, для которого должны быть зарезервированы ресурсы DMA.

[in] DmaDirection

Значение WDF_DMA_DIRECTIONтипа, указывающее направление передачи DMA, для которого зарезервированы ресурсы. Если драйвер не указал дуплексный профиль, платформа игнорирует это значение.

[in] RequiredMapRegisters

Число регистров карты, которые драйвер хочет зарезервировать. Если ноль, платформа наследует необходимое количество регистров карты из инициализированной транзакции.

[in] EvtReserveDmaFunction

Указатель на функцию обратного вызова события драйвера EvtReserveDma.

[in] EvtReserveDmaContext

Указатель на буфер, содержащий контекст, который необходимо предоставить драйвера EvtReserveDma функцию обратного вызова событий.

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

WdfDmaTransactionAllocateResources возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод возвращает одно из следующих значений.

Код возврата	Описание
СТАТУС_НЕДЕЙСТВИТЕЛЬНЫЙ_ПАРАМЕТР	Параметр DmaDirection содержит недопустимое значение.
СТАТУС_НЕДОСТАТОЧНЫЕ_РЕСУРСЫ	Число запросов регистра карты превышает число, назначенное средству включения, или драйвер, ранее называемый WdfDmaTransactionSetImmediateExecution, а ресурсы, необходимые для запроса, недоступны.
STATUS_INVALID_DEVICE_REQUEST	DMA версии 3 или более поздней не включен, или драйвер, называемый этим методом для включения DMA точечной сборки.

Замечания

WdfDmaTransactionAllocateResources отправляет запрос на регистрацию карт в подсистему DMA системы. Когда запрос выполнен, платформа вызывает функцию обратного вызова события драйвера EvtReserveDma. Дополнительные сведения о резервирования ресурсов см. в резервирования ресурсов DMA.

Драйверы на основе платформы обычно вызывают WdfDmaTransactionAllocateResources из обработчика запросов ввода-вывода. Драйвер также может вызывать WdfDmaTransactionAllocateResources из функции обратного вызова EvtDriverDeviceAdd после создания объекта включения DMA.

При вызове с помощью средства включения DMA точечной и сбора WdfDmaTransactionAllocateResources вызывает проверку ошибок проверяющего средства.

Драйвер должен создать транзакцию, указанную DmaTransaction перед вызовом WdfDmaTransactionAllocateResources. После вызова WdfDmaTransactionAllocateResourcesдрайвер инициализирует и инициирует транзакцию. Драйвер может повторно инициализировать и повторно инициализировать один и тот же объект транзакции несколько раз, избегая задержки, которая в противном случае возникает между транзакциями, так как регистры карты были освобождены обратно в HAL, а затем перераспреждены.

Драйвер может вызывать WdfDmaTransactionAllocateResources в следующих ситуациях:

Драйвер получает набор каналов DMA в функции обратного вызова EvtDevicePrepareHardware. В EvtDevicePrepareHardwareдрайвер инициализирует транзакцию DMA и вызывает WdfDmaTransactionAllocateResources, чтобы зарезервировать включение для монопольного использования с этой транзакцией. Кроме того, драйвер может вызывать WdfDmaTransactionAllocateResources из обработчика запросов , а затем инициировать транзакцию несколько раз.
Драйверу необходимо выполнить ряд транзакций в средстве включения. Драйвер резервирует включение, инициализирует и инициирует несколько транзакций с помощью одного объекта транзакции, а затем освобождает включение.

Перед вызовом WdfDmaTransactionAllocateResourcesдрайвер должен определить количество регистров карты, необходимых для любой транзакции, которую он будет инициировать с помощью этого резервирования. Для этого драйвер может вызвать [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.). Макрос /wdm/nf-wdm-address_and_size_to_span_pages.md) или WdfDmaTransactionGetTransferInfo.

При вызове WdfDmaTransactionAllocateResourcesдрайвер не должен запрашивать больше регистров карт, чем запрашивается при создании включения.

Чтобы вызвать WdfDmaTransactionAllocateResources, драйвер должен сначала вызвать WdfDmaTransactionSetImmediateExecution.

WdfDmaTransactionAllocateResources требует DMA версии 3. Чтобы выбрать DMA версии 3, задайте WdmDmaVersionOverride член WDF_DMA_ENABLER_CONFIG 3.

Требования

Требование	Ценность
целевая платформа	универсальный
минимальная версия KMDF	1.11
Заголовок	wdfdmatransaction.h (include Wdf.h)
Библиотека	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	<=DISPATCH_LEVEL
правил соответствия DDI	DriverCreate(kmdf)