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

Статья
08/07/2023

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

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

Синтаксис

PALLOCATE_RENDER_DMA_ENGINE PallocateRenderDmaEngine;

NTSTATUS PallocateRenderDmaEngine(
  [in]  PVOID _context,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [in]  BOOLEAN Stripe,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Параметры

[in] _context

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

[in] StreamFormat

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

[in] Stripe

Указывает, следует ли включать чередование. Если задано значение TRUE, подпрограмма включает чередование в передачах DMA. Если задано значение FALSE, чередование отключено.

[out] Handle

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

[out] ConverterFormat

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

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

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

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

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

Подпрограмма AllocateRenderDmaEngine резервирует аппаратные ресурсы (подсистему 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 задает формат данных для потока записи. После вызова AllocateRenderDmaEngineможно изменить формат потока, вызвав ChangeBandwidthAllocation.

Параметр чередование указывает, будет ли подсистема DMA использовать чередование для ускорения передачи данных. Дополнительные сведения см. в разделе Чередование.

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

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

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

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

Требования

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