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

Статья
03/08/2023

Подпрограмма AllocateCaptureDmaEngine выделяет подсистему DMA для потока захвата.

Тип указателя функции для AllocateCaptureDmaEngine подпрограммы определяется следующим образом.

Синтаксис

PALLOCATE_CAPTURE_DMA_ENGINE PallocateCaptureDmaEngine;

NTSTATUS PallocateCaptureDmaEngine(
  [in]  PVOID _context,
  [in]  UCHAR CodecAddress,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Параметры

[in] _context

Задает значение контекста из элемента ContextHDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 или HDAUDIO_BUS_INTERFACE_BDL структуры.

[in] CodecAddress

Указывает адрес кодека. Этот параметр определяет последовательные данные в строке (SDI), в которой кодек передает данные записи контроллеру шины HD Audio. Контроллер шины с n контактов SDI может поддерживать до n кодеков с адресами в диапазоне от 0 до n-1.

[in] StreamFormat

Задает запрошенный формат потока. Этот параметр указывает на структуру, выделенную вызывающим объектом, с типом HDAUDIO_STREAM_FORMAT , которая задает формат данных для потока.

[out] Handle

Извлекает дескриптор в подсистему DMA. Этот параметр указывает на выделенную вызывающим объектом переменную HANDLE, в которую подпрограмма записывает дескриптор, идентифицирующий подсистему DMA.

[out] ConverterFormat

Извлекает формат преобразователя. Этот параметр указывает на структуру, выделенную вызывающим объектом, с типом HDAUDIO_CONVERTER_FORMAT , в которую подпрограмма записывает закодированный формат.

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

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

Код возврата	Описание
STATUS_BUFFER_TOO_SMALL	Указывает, что подсистеме DMA не удается выделить достаточное внутреннее хранилище FIFO для поддержки запрошенного формата потока.
STATUS_INSUFFICIENT_RESOURCES	Указывает, что подсистема DMA недоступна или запрос превышает доступные ресурсы пропускной способности.
STATUS_INVALID_PARAMETER	Указывает, что одно из значений параметра неверно (недопустимое значение параметра или неправильный указатель).

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

Подпрограмма AllocateCaptureDmaEngine резервирует аппаратные ресурсы (подсистему DMA), но не настраивает оборудование DMA. После вызова этой подпрограммы для резервирования подсистемы DMA драйвер функции должен назначить буфер DMA подсистеме DMA и настроить подсистему для использования буфера:

При использовании HDAUDIO_BUS_INTERFACE версии HD Audio DDI драйвер функции вызывает подпрограмму AllocateDmaBuffer , чтобы драйвер шины HD Audio выделил буфер данных для передачи DMA и настроил подсистему DMA для использования буфера.
При использовании HDAUDIO_BUS_INTERFACE_BDL версии DDI драйвер функции вызывает Метод AllocateContiguousDmaBuffer для выделения буфера DMA и вызывает подпрограмму SetupDmaEngineWithBdl для настройки подсистемы DMA для использования буфера.

Параметр streamFormat задает формат данных для потока записи. После вызова AllocateCaptureDmaEngineможно изменить формат потока, вызвав ChangeBandwidthAllocation.

С помощью параметра handle подпрограмма выводит дескриптор, который вызывающий объект использует для идентификации выделенного обработчика DMA в последующих вызовах AllocateDmaBuffer, ChangeBandwidthAllocation, FreeDmaBuffer, SetupDmaEngineWithBdl и SetDmaEngineState. Драйвер функции освобождает дескриптор, вызывая FreeDmaEngine.

С помощью параметра converterFormat подпрограмма выводит значение дескриптора потока, которое вызывающий объект может использовать для программирования входных преобразователей. Подпрограмма кодирует сведения из параметра streamFormat в 16-битовое целое число. Дополнительные сведения см. в разделе HDAUDIO_CONVERTER_FORMAT.

Сразу после успешного вызова AllocateCaptureDmaEngineподсистема DMA находится в состоянии сброса потока. Перед вызовом SetDmaEngineState для изменения подсистемы DMA на работающее, приостановленное или остановленное состояние, клиент должен сначала выделить буфер DMA для подсистемы.

Аудиодрайвер модели драйвера Windows (WDM) вызывается AllocateCaptureDmaEngine во время создания пин-кода во время выполнения метода NewStream (например, см. раздел IMiniportWavePci::NewStream).

Требования

Требование	Значение
Целевая платформа	Персональный компьютер
Верхняя часть	hdaudio.h (включая Hdaudio.h)
IRQL	PASSIVE_LEVEL