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

Статья
08/07/2023

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

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

Синтаксис

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

Параметры

[in] _context

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

[in] Handle

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

RequestedBufferSize

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

[out] DataBuffer

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

[out] BdlBuffer

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

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

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

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

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

AllocateContiguousDmaBuffer выделяет буфер данных для указанного обработчика DMA. Он также выделяет страницу памяти для BDL. В зависимости от архитектуры процессора узла типичный размер страницы может составлять 4096 или 8 192 байта. Буфер данных состоит из одного непрерывного блока физической памяти.

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

Хранилище, которое подпрограмма выделяет для буфера данных и BDL, не инициализируется. Драйвер функции отвечает за заполнение BDL перед его отправкой в подпрограмму SetupDmaEngineWithBdl . Драйвер функции также отвечает за программирование кодека для управления передачей данных и распознавания идентификатора потока.

Чтобы создавать прерывания IOC через определенные интервалы, драйверу функции может потребоваться разделить выделение буфера данных на несколько фрагментов определенного размера. Каждый фрагмент описывается записью BDL. Размер фрагмента можно настроить для настройки частоты прерываний. Согласно спецификации Intel High Definition Audio (см. веб-сайт Intel HD Audio ), каждый фрагмент должен начинаться с 128-байтовой границы, хотя такое требование выравнивания не применяется к длине фрагмента. Таким образом, между концом одного фрагмента и началом следующего может существовать разрыв. При вызове SetupDmaEngineWithBdl драйвер функции должен указать значение параметра bufferSize , представляющее сумму размеров отдельных фрагментов, описываемых записями BDL. Этот размер будет меньше или равен количеству байтов, указанному в параметре AllocateContiguousDmaBufferrequestedBufferSize подпрограммы .

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

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

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

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

Требования

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