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

Статья
02/07/2025

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

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

Синтаксис

PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION PallocateDmaBufferWithNotification;

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

Параметры

[in] _context

Указывает значение контекста из элемента Context структуры HDAUDIO_BUS_INTERFACE_V2.

[in] Handle

Дескриптор, определяющий подсистему DMA. Это значение дескриптора было получено из предыдущего вызова AllocateCaptureDmaEngine или AllocateRenderDmaEngine.

[in] NotificationCount

Указывает количество необходимых уведомлений на основе прогрессирования DMA через звуковой буфер. В настоящее время поддерживается значение 1 или 2. Если значение равно 1, все зарегистрированные события уведомлений сигнализируются каждый раз при завершении циклического звукового буфера, а DMA — обратно в начало. Если значение равно 2, все зарегистрированные события уведомлений уведомляются, так как DMA передает середину звукового буфера, а также в конце (или точке обходного пути).

[in] RequestedBufferSize

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

[out] BufferMdl

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

[out] AllocatedBufferSize

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

OffsetFromFirstPage

[out] StreamId

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

[out] FifoSize

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

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

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

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

Замечания

Подпрограмма AllocateDmaBufferWithNotification используется вместе с подпрограммой FreeDmaBufferWithNotification. Эти две подпрограммы доступны только в HDAUDIO_BUS_INTERFACE_V2 версии DDI HD Audio. В отличие от SetupDmaEngineWithBdl, который настраивает подсистему DMA для использования ранее выделенного буфера DMA, AllocateDmaBufferWithNotification выделяет буфер DMA, а также настраивает обработчик DMA для использования буфера.

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

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

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

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

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

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

В Windows Vista и более поздних версиях Windows драйвер минипорта WaveRT вызывает эту подпрограмму при получении запроса KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION свойств.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Windows Vista и более поздних версиях Windows.
целевая платформа	Настольный
заголовка	hdaudio.h (include Hdaudio.h)
IRQL	PASSIVE_LEVEL.