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

Статья
02/07/2025

Подпрограмма 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, представляющей адаптер шины или контроллер DMA.

[in] DeviceObject

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

[in] NumberOfMapRegisters

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

[in] ExecutionRoutine

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

[in] Context

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

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

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

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

Замечания

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

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

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

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

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 2000.
целевая платформа	Настольный
заголовка	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
правил соответствия DDI	irqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)