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

Статья
02/07/2025

Подпрограмма 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 bus выделил буфер данных для передачи DMA и настроил обработчик DMA для использования буфера.
При использовании HDAUDIO_BUS_INTERFACE_BDL версии DDI драйвер функции вызывает AllocateContiguousDmaBuffer для выделения буфера DMA и вызывает подпрограмму setupDmaEngineWithBdl, чтобы настроить подсистему DMA для использования буфера.

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

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

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

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

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

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