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

Статья
02/07/2025

Подпрограмма 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

Указывает значение контекста из контекста члена структуры 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, AllocateDmaBuffer как выделяет буфер DMA, так и настраивает обработчик DMA для использования буфера. Дополнительные сведения см. в разделе Различия между двумя версиями DDI.

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

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

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

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

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

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

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