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

Статья
08/07/2023

Подпрограмма AllocateDmaBuffer выделяет буфер данных в системной памяти для подсистемы DMA.

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

Синтаксис

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

NTSTATUS PallocateDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Параметры

[in] _context

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

[in] Handle

Дескриптор идентификации подсистемы DMA. Это значение дескриптора было получено из предыдущего вызова Метода AllocateCaptureDmaEngine или AllocateRenderDmaEngine.

[in] RequestedBufferSize

Указывает запрошенный размер буфера в байтах.

[out] BufferMdl

Извлекает страницы физической памяти, содержащие выделенный буфер. Этот параметр указывает на выделенную вызывающим объектом переменную PMDL, в которую подпрограмма записывает указатель на список дескрипторов памяти (MDL), описывающий буфер.

[out] AllocatedBufferSize

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

[out] StreamId

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

[out] FifoSize

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

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

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

Код возврата	Описание
STATUS_UNSUCCESSFUL	Указывает, что вызывающий объект работает на слишком высоком уровне IRQL.
STATUS_INSUFFICIENT_RESOURCES	Указывает, что выделение буфера завершилось сбоем.
STATUS_INVALID_HANDLE	Указывает, что значение параметра дескриптора недопустимо.
STATUS_INVALID_PARAMETER	Указывает, что одно из значений параметра неверно (неправильный указатель).
STATUS_DEVICE_NOT_READY	Указывает, что истекло время ожидания аппаратного программирования. В этом случае оборудование может находиться в скомпрометированном состоянии.
STATUS_INVALID_DEVICE_REQUEST	Указывает, что поток не находится в состоянии сброса или что буфер уже выделен для подсистемы DMA.

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

Если подсистема DMA не может использовать буфер размера, запрошенного в параметре requestedBufferSize, подпрограмма выделяет буфер, который максимально близок к требуемому размеру.

Драйвер функции для кодека аудио или модема отвечает за программирование кодека для управления передачей данных и распознавания идентификатора потока.

Подпрограмма выводит MDL, который перечисляет страницы физической памяти, содержащие буфер. Базовый адрес буфера совпадает с началом первой физической страницы в списке.

В течение времени существования дескриптора AllocateDmaBuffer обработчика DMA можно последовательно вызывать для выделения новых буферов DMA. Однако перед вызовом AllocateDmaBufferнеобходимо освободить любой ранее выделенный буфер DMA, вызвав FreeDmaBuffer.

Во время вызовов AllocateDmaBuffer и FreeDmaBuffer подсистема DMA должна находиться в состоянии потока сброса. Подсистема DMA находится в состоянии сброса сразу после вызова метода AllocateXxxDmaEngine. Чтобы изменить подсистему DMA на состояние выполнения, вызовите SetDmaEngineState.

Размер FIFO — это максимальное количество байтов, которое подсистема DMA может хранить во внутреннем буфере. В зависимости от реализации оборудования размер FIFO модуля DMA может быть статическим или динамически изменяться в зависимости от изменений формата потока. Дополнительные сведения о размере FIFO см. в спецификации Intel High Definition Audio на веб-сайте Intel HD Audio .

Эта подпрограмма завершается сбоем и возвращает код ошибки STATUS_INVALID_DEVICE_REQUEST в любом из следующих случаев:

Ранее выделенный буфер DMA не был освобожден (путем вызова FreeDmaBuffer).
Поток находится в состоянии, отличном от сброса.

В Windows Server 2003, Windows XP, Windows 2000 и Windows Me/98 звуковой драйвер WDM вызывает эту процедуру во время выполнения метода NewStream (во время создания пин-кода) или метода SetFormat (после вызова одной из подпрограмм AllocateXxxDmaEngine в HD Audio DDI). Дополнительные сведения см. в разделах IMiniportWavePci::NewStream и IMiniportWavePciStream::SetFormat.

Требования

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