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

Статья
02/07/2025

Подпрограмма 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 версиях DDI HD Audio. Этот DDI не включает AllocateContiguousDmaBuffer, SetupDmaEngineWithBdlи подпрограммы FreeContiguousDmaBuffer, которые никогда не используются в сочетании с AllocateDmaBuffer и FreeDmaBuffer. В отличие от SetupDmaEngineWithBdl, который настраивает подсистему DMA для использования ранее выделенного буфера DMA, AllocateDmaBuffer как выделяет буфер DMA, так и настраивает обработчик DMA для использования буфера.

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

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

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

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

Во время вызовов AllocateDmaBuffer и FreeDmaBufferподсистема DMA должна находиться в состоянии потока сброса. Подсистема DMA находится в состоянии сброса сразу после вызова выделенияXxxDmaEngine. Чтобы изменить модуль 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 (после вызова одной из подпрограмм "ВыделитьXxxDmaEngine" в DDI hd Audio). Дополнительные сведения см. в разделе IMiniportWavePci::NewStream и IMiniportWavePciStream::SetFormat.