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

Подпрограмма 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 . Эта структура — это объект адаптера, представляющий основное устройство DMA драйвера или канал DMA системы. Вызывающий объект получил этот указатель из предыдущего вызова подпрограммы IoGetDmaAdapter .

[in] DeviceObject

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

[in] DmaTransferContext

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

[in] NumberOfMapRegisters

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

[in] Flags

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

Если установлен флаг 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, если вызов выполнен успешно. Возможные значения возвращаемых ошибок включают следующие коды состояния.

Замечания

AllocateAdapterChannelEx не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в DMA_OPERATIONS структуре. Драйверы получают адрес этой подпрограммы путем вызова IoGetDmaAdapterс членом параметра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 после завершения работы с выделенными ресурсами.

Требования

См. также

AdapterControl

AllocateAdapterChannel

CancelAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

FlushAdapterBuffers

FlushAdapterBuffersEx

FreeAdapterObject

FreeMapRegisters

GetDmaTransferInfo

InitializeDmaTransferContext

IoGetDmaAdapter

MapTransferEx