función de devolución de llamada PFREE_DMA_BUFFER (hdaudio.h)

Artículo
02/07/2025

La rutina FreeDmaBuffer libera un búfer DMA asignado previamente por una llamada a AllocateDmaBuffer.

El tipo de puntero de función para una rutina de FreeDmaBuffer se define de la manera siguiente.

Sintaxis

PFREE_DMA_BUFFER PfreeDmaBuffer;

NTSTATUS PfreeDmaBuffer(
  [in] PVOID _context,
  [in] HANDLE Handle
)
{...}

Parámetros

[in] _context

Especifica el valor de contexto del miembro Context del HDAUDIO_BUS_INTERFACE o la estructura HDAUDIO_BUS_INTERFACE_V2.

[in] Handle

Controle la identificación del motor DMA. Este valor de identificador se obtuvo de una llamada anterior a AllocateCaptureDmaEngine o AllocateRenderDmaEngine.

Valor devuelto

FreeDmaBuffer devuelve STATUS_SUCCESS si la llamada se realiza correctamente. De lo contrario, la rutina devuelve un código de error adecuado. En la tabla siguiente se muestran algunos de los posibles códigos de estado de retorno.

Código devuelto	Descripción
STATUS_UNSUCCESSFUL	Indica que el autor de la llamada se está ejecutando en un IRQL demasiado alto.
STATUS_INVALID_HANDLE	Indica que el valor del parámetro handle no es válido.
STATUS_INVALID_DEVICE_REQUEST	Indica que la secuencia no está en el estado de restablecimiento o que actualmente no se asigna ningún búfer para el motor DMA.

Observaciones

La rutina FreeDmaBuffer se usa junto con la rutina de AllocateDmaBuffer. Estas dos rutinas solo están disponibles en la versión HDAUDIO_BUS_INTERFACE de hd Audio DDI. Esta DDI no incluye el AllocateContiguousDmaBuffer, SetupDmaEngineWithBdly las rutinas de FreeContiguousDmaBuffer, que nunca se usan junto con AllocateDmaBuffer y FreeDmaBuffer. A diferencia de SetupDmaEngineWithBdl, que configura el motor DMA para usar un búfer DMA asignado previamente, AllocateDmaBuffer asigna un búfer DMA y configura el motor DMA para usar el búfer.

La rutina produce un error y devuelve el código de error STATUS_INVALID_DEVICE_REQUEST en cualquiera de las siguientes circunstancias:

El cliente llama a FreeDmaBuffer cuando no se asigna ningún búfer actualmente para el motor DMA.
La secuencia está en un estado distinto del restablecimiento.