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

Статья
08/07/2023

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

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

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

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

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

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

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

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

Требования

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