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

Статья
08/08/2023

Подпрограмма AllocateAdapterChannel подготавливает систему к операции DMA от имени целевого объекта устройства, а затем вызывает предоставленную драйвером подпрограмму AdapterControl для выполнения операции DMA.

Синтаксис

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER, возвращаемую IoGetDmaAdapter, которая представляет адаптер master шины или контроллер DMA.

[in] DeviceObject

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

[in] NumberOfMapRegisters

Указывает количество регистров карты, используемых при передаче. Это значение меньше числа регистров карты, необходимых для удовлетворения текущего запроса на передачу, и числа доступных регистров карты, возвращаемых IoGetDmaAdapter.

[in] ExecutionRoutine

Указатель на подпрограмму AdapterControl , предоставляемую драйвером. Подпрограмма вызывается, когда становится доступен системный контроллер DMA или адаптер master шины.

[in] Context

Указатель на определенный драйвером контекст, передаваемый в подпрограмму AdapterControl .

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

Эта подпрограмма может возвращать одно из следующих значений NTSTATUS.

Код возврата	Описание
STATUS_SUCCESS	Канал адаптера выделен. Система вызовет подпрограмму AdapterControl после начала операции DMA.
STATUS_INSUFFICIENT_RESOURCES	NumberOfMapRegisters больше значения, возвращаемого IoGetDmaAdapter. Подпрограмма AdapterControl вызываться не будет.

AllocateAdapterChannel не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в DMA_OPERATIONS структуре. Драйверы получают адрес этой подпрограммы, вызывая IoGetDmaAdapter.

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

Если операция DMA может быть выполнена немедленно, система немедленно вызывает AdapterControl. Если системный контроллер DMA или адаптер master шины в настоящее время используется, AllocateAdapterChannel помещает AdapterControl в очередь до тех пор, пока адаптер не станет доступным. В любом случае функция AllocateAdapterChannel возвращает STATUS_SUCCESS.

Если системе не хватает ресурсов для выполнения операции DMA, функция AllocateAdapterChannel возвращает STATUS_INSUFFICIENT_RESOURCES. В этом случае AdapterControl не помещается в очередь, и драйвер должен завершить текущий IRP с соответствующим кодом ошибки (например, STATUS_INSUFFICIENT_RESOURCES).

Эта подпрограмма резервирует монопольный доступ к каналу контроллера DMA и сопоставляет регистры для одной или нескольких операций DMA, необходимых для удовлетворения текущего запроса на передачу IRP для указанного устройства.

В любой момент времени можно поместить в очередь только один запрос DMA для объекта устройства. Поэтому драйвер не должен снова вызывать AllocateAdapterChannel для другой операции DMA на том же объекте устройства, пока не завершится выполнение подпрограммы AdapterControl . Кроме того, драйвер не должен вызывать AllocateAdapterChannel из подпрограммы AdapterControl .

Система передает значение элемента CurrentIrpобъекта DeviceObject в качестве параметра IrpadapterControl. Если метод AllocateAdapterChannel вызывается из подпрограммы StartIo драйвера, это гарантированно указывает на IRP, который был вызван для обработки StartIo . В противном случае, чтобы использовать параметр Irpдля AdapterControl, драйвер должен задать currentIrp так, чтобы он указывал на текущий IRP, прежде чем вызывать AllocateAdapterChannel.

Требования

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