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

Статья
08/08/2023

[Относится только к 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, если операция выполнена успешно. В противном случае этот метод возвращает одно из следующих значений.

Код возврата	Описание
STATUS_INVALID_PARAMETER	Параметр DmaDirection содержит недопустимое значение.
STATUS_INSUFFICIENT_RESOURCES	Количество запросов регистра карты превышает число, назначенное средству включения, или драйвер, ранее называемый 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, установите для элемента WdmDmaVersionOverrideWDF_DMA_ENABLER_CONFIG значение 3.

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1.11
Верхняя часть	wdfdmatransaction.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf)