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

Статья
07/27/2023

Подпрограмма SetupDmaEngineWithBdl настраивает подсистему DMA для использования буфера DMA, выделенного вызывающим объектом.

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

Синтаксис

PSETUP_DMA_ENGINE_WITH_BDL PsetupDmaEngineWithBdl;

NTSTATUS PsetupDmaEngineWithBdl(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
  [in]  PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Параметры

[in] _context

Задает значение контекста из элемента Contextструктуры HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

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

[in] BufferLength

Длина буфера.

[in] Lvi

Указывает последний допустимый индекс (LVI). Этот параметр содержит индекс последнего допустимого дескриптора буфера в файле BDL. После того как подсистема DMA обработает этот дескриптор, он возвращается к первому дескриптору в списке и продолжает обработку. Если BDL содержит n дескрипторов, они нумеруются от 0 до n–1. Значение lvi должно быть не менее 1; Другими словами, BDL должен содержать по крайней мере две допустимые записи, прежде чем подсистема DMA сможет начать работу.

[in] Isr

Указатель функции на ISR вызывающего абонента. Если вызывающий объект задает бит прерывания при завершении (IOC) в одном или нескольких дескрипторах буфера в BDL, драйвер шины HD Audio вызывает ISR при каждом прерывании IOC в потоке. Этот параметр является указателем функции типа HDAUDIO_BDL_ISR, который определен в следующем разделе примечаний.

[in] Context

Контекст.

[out] StreamId

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

[out] FifoSize

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

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

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

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

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

Вызывающий объект должен вызвать Метод AllocateContiguousDmaBuffer , чтобы выделить хранилище в системной памяти для буфера DMA и BDL, описывающего страницы физической памяти в буфере. Записи BDL должны находиться в физической непрерывной памяти. BDL и буферная память должны соответствовать требованиям к выравниванию, описанным в спецификации Intel High Definition Audio (см. веб-сайт Intel HD Audio ).

BDL и описываемая в нем буферная память должны оставаться действительными во время операций DMA. После вызова SetupDmaEngineWithBdl BDL и буферная память должны оставаться действительными до тех пор, пока подсистема DMA продолжает использовать буфер. Подсистема DMA использует буфер, пока драйвер функции не заменит буфер путем повторного вызова SetupDmaEngineWithBdl или не освободит подсистему DMA, вызвав FreeDmaEngine. Драйвер функции отвечает за вызов FreeContiguousDmaBuffer для освобождения буфера и BDL, когда они больше не требуются.

При выделении памяти для буфера вызывающий объект должен удовлетворять всем аппаратным ограничениям адреса, длины и выравнивания физически смежных блоков памяти, заданных BDL. Таким образом, только клиенты, имеющие значительные знания о контроллере шины и системном оборудовании, должны использовать подпрограмму SetupDmaEngineWithBdl .

Перед вызовом SetupDmaEngineWithBdl для настройки подсистемы DMA клиент должен вызвать Метод AllocateCaptureDmaEngine или AllocateRenderDmaEngine для выделения подсистемы DMA. Параметр дескриптора — это значение, полученное при предыдущем вызове метода Allocate XxxDmaEngine.

Вызывающий объект отвечает за программирование кодека для управления передачей данных и распознавания идентификатора потока.

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

После вызова SetupDmaEngineWithBdl подсистема DMA находится в состоянии Сброс. Чтобы запустить подсистему DMA, вызовите SetDmaEngineState.

Параметр isr указывает ISR, который драйвер шины HD Audio будет вызывать при каждом прерывании IOC в потоке. Этот параметр является указателем функции типа HDAUDIO_BDL_ISR, который определяется следующим образом:

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

Драйвер шины HD Audio вызывает ISR с тем же значением контекста, которое указано клиентом в параметре контекста предыдущего вызова SetupDmaEngineWithBdl . Параметр interruptBitMask содержит биты из регистра состояния потока устройства контроллера HD Audio, указывающие причину прерывания. В следующей таблице показано значение отдельных битов в элементе interruptBitMask.

Битовые числа	Значение
31:5	Не используется.
4	Ошибка дескриптора (DESE). Если во время выборки дескриптора буфера возникает ошибка, то контроллер HD Audio устанавливает бит DESE в значение 1.
3	Ошибка FIFO (FIFOE). Если возникает ошибка FIFO (переполнение выходного потока или недостаточное выполнение во входном потоке), контроллер HD Audio устанавливает бит FIFOE в значение 1.
2	Состояние прерывания завершения буфера (BCIS). Если бит IOC имеет значение 1 в байте команды дескриптора буфера, то контроллер HD Audio устанавливает бит BCIS в значение 1 после обработки последней выборки буфера.
1:0	Не используется.

Драйвер шины HD Audio устанавливает неиспользуемые биты равным нулю. Вместо того чтобы предполагать, что произошло прерывание IOC, ISR всегда должен проверка параметр interruptBitMask, чтобы определить, произошла ли ошибка потока. Дополнительные сведения о битах состояния прерывания, показанных в предыдущей таблице, см. в описании регистров состояния потока в спецификации Intel High Definition Audio.

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

Вызывающий объект должен выделить буферную память и BDL из непагрегированного пула.

Требования

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