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

Статья
03/08/2023

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

Синтаксис

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER . Эта структура представляет собой объект адаптера, представляющий master шине драйвера DMA устройства или системного канала DMA. Вызывающий объект получил этот указатель из предыдущего вызова процедуры IoGetDmaAdapter .

[in] DeviceObject

Указатель на структуру DEVICE_OBJECT . Эта структура представляет собой объект физического устройства (PDO), представляющий целевое устройство для запрошенной операции DMA.

[in] DmaTransferContext

Указатель на инициализированный контекст передачи DMA. Этот контекст был инициализирован предыдущим вызовом подпрограммы InitializeDmaTransferContext . Этот контекст должен быть уникальным для всех запросов на выделение адаптера. Чтобы отменить ожидающий запрос на выделение, вызывающий объект должен предоставить контекст передачи DMA для запроса в подпрограмму CancelAdapterChannel .

[in] NumberOfMapRegisters

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

[in] Flags

Флаги выделения канала адаптера. Поддерживается следующий флаг.

Flag	Значение
DMA_SYNCHRONOUS_CALLBACK	Подпрограмма AllocateAdapterChannelEx называется синхронно. Если этот флаг установлен и необходимые ресурсы DMA недоступны сразу, вызов завершается ошибкой и возвращает STATUS_INSUFFICIENT_RESOURCES.

Если установлен флаг DMA_SYNCHRONOUS_CALLBACK , параметр ExecutionRoutine является необязательным и может иметь значение NULL. Дополнительные сведения об этом флаге см. в разделе Примечания.

[in, optional] ExecutionRoutine

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

Если установлен флаг DMA_SYNCHRONOUS_CALLBACK , параметр ExecutionRoutine является необязательным и может иметь значение NULL. В этом случае вызывающий объект может использовать ресурсы, выделенные с помощью AllocateAdapterChannelEx, а затем освободить эти ресурсы, вызвав подпрограмму FreeAdapterObject . Дополнительные сведения см. в разделе «Примечания».

[in, optional] ExecutionContext

Определяемые драйвером контексты управления адаптером. Этот контекст передается подпрограмме AdapterControl в качестве параметра Context .

[out, optional] MapRegisterBase

Указатель на переменную, в которую подпрограмма записывает дескриптор в выделенные регистры карты. Вызывающий объект может предоставить этот дескриптор в качестве параметра в подпрограмму FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters или MapTransferEx .

Если установлен флаг DMA_SYNCHRONOUS_CALLBACK , MapRegisterBase должен быть допустимым указателем, не равным NULL . Если параметр ExecutionRoutine не равен NULL, mapRegisterBase должен иметь значение NULL. Вызов завершается ошибкой, если mapRegisterBase не равно NULL и флаг DMA_SYNCHRONOUS_CALLBACK не задан или если MapRegisterBase и ExecutionRoutine имеют значение NULL.

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

Функция AllocateAdapterChannelEx возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные возвращаемые значения ошибок включают следующие коды состояния.

Код возврата	Описание
STATUS_INVALID_PARAMETERS	Подпрограмма завершилась сбоем из-за недопустимых значений параметров, переданных вызывающим.
STATUS_INSUFFICIENT_RESOURCES	Подпрограмме не удалось выделить ресурсы, необходимые для передачи DMA.

AllocateAdapterChannelEx не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в структуре DMA_OPERATIONS . Драйверы получают адрес этой подпрограммы, вызывая IoGetDmaAdapter с элементом Version параметра DeviceDescription , равным DEVICE_DESCRIPTION_VERSION3. Если IoGetDmaAdapter возвращает значение NULL, подпрограмма недоступна на вашей платформе.

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

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

Если вызывающий драйвер устанавливает флаг DMA_SYNCHRONOUS_CALLBACK , подпрограмма AllocateAdapterChannelEx ведет себя следующим образом:

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

AllocateAdapterChannelEx — это расширенная версия подпрограммы AllocateAdapterChannel . Следующие функции доступны только в расширенной версии:

Требования

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