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

Artículo
02/07/2025

La rutina AllocateDmaBuffer asigna un búfer de datos en la memoria del sistema para un motor DMA.

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

Sintaxis

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

NTSTATUS PallocateDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Parámetros

[in] _context

Especifica el valor de contexto de los miembros de Context de las estructuras HDAUDIO_BUS_INTERFACE y 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.

[in] RequestedBufferSize

Especifica el tamaño del búfer solicitado en bytes.

[out] BufferMdl

Recupera las páginas de memoria física que contiene el búfer asignado. Este parámetro apunta a una variable PMDL asignada por el autor de la llamada en la que la rutina escribe un puntero a una lista de descriptores de memoria (MDL) que describe el búfer.

[out] AllocatedBufferSize

Recupera el tamaño del búfer asignado en bytes. Este parámetro apunta a una variable de SIZE_T asignada por el autor de la llamada en la que la rutina escribe el tamaño del búfer asignado.

[out] StreamId

Recupera el identificador de flujo. Este parámetro apunta a una variable UCHAR asignada por el autor de la llamada en la que la rutina escribe el identificador de flujo que asigna a la secuencia.

[out] FifoSize

Recupera el tamaño FIFO del motor DMA en bytes. Este parámetro apunta a una variable ULONG asignada por el autor de la llamada en la que la rutina escribe el tamaño FIFO.

Valor devuelto

AllocateDmaBuffer 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_INSUFFICIENT_RESOURCES	Indica que se produjo un error en la asignación del búfer.
STATUS_INVALID_HANDLE	Indica que el valor del parámetro handle no es válido.
STATUS_INVALID_PARAMETER	Indica que uno de los valores de parámetro es incorrecto (puntero incorrecto).
STATUS_DEVICE_NOT_READY	Indica que se agota el tiempo de espera de programación de hardware. Si esto ocurre, el hardware podría estar en un estado en peligro.
STATUS_INVALID_DEVICE_REQUEST	Indica que la secuencia no está en el estado de restablecimiento o que ya se ha asignado un búfer para el motor DMA.

Observaciones

La rutina de AllocateDmaBuffer se usa junto con la rutina FreeDmaBuffer. Estas dos rutinas solo están disponibles en el HDAUDIO_BUS_INTERFACE y las versiones HDAUDIO_BUS_INTERFACE_V2 de la DDI de audio HD. 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 que use un búfer DMA asignado anteriormente, AllocateDmaBuffer asigna un búfer DMA y configura el motor DMA para usar el búfer.

Si el motor DMA no puede usar un búfer del tamaño solicitado en el parámetro requestedBufferSize, la rutina asigna un búfer lo más cercano posible al tamaño solicitado.

El controlador de función de un códec de audio o módem es responsable de programar el códec para administrar las transferencias de datos y para reconocer el identificador de flujo.

La rutina genera una MDL que enumera las páginas de memoria física que contienen el búfer. La dirección base del búfer coincide con el inicio de la primera página física de la lista.

Durante la vigencia de un identificador de motor DMA, se puede llamar a AllocateDmaBuffer sucesivamente para asignar nuevos búferes DMA. Sin embargo, antes de llamar a AllocateDmaBuffer, primero se debe liberar cualquier búfer DMA asignado previamente llamando a FreeDmaBuffer.

Durante las llamadas a AllocateDmaBuffer y FreeDmaBuffer, el motor DMA debe estar en estado de flujo de restablecimiento. El motor DMA está en estado de restablecimiento inmediatamente después de la llamada a AsignarXxxDmaEngine. Para cambiar el motor DMA al estado de ejecución, llame a SetDmaEngineState.

El tamaño de FIFO es el número máximo de bytes que el motor DMA puede contener en su búfer interno. Dependiendo de la implementación de hardware, el tamaño FIFO de un motor DMA puede ser estático o variar dinámicamente con cambios en el formato de secuencia. Para obtener más información sobre el tamaño fiFO, consulte la especificación de audio de alta definición de Intel en el sitio web de intel HD Audio.

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

No se ha liberado ningún búfer DMA asignado anteriormente (llamando a FreeDmaBuffer).
La secuencia está en un estado distinto del restablecimiento.

En Windows Server 2003, Windows XP, Windows 2000 y Windows Me/98, un controlador de audio WDM llama a esta rutina durante la ejecución de su método de NewStream (en tiempo de creación de pin) o método SetFormat (después de llamar a una de las rutinas de AllocateXxxDmaEngine en HD Audio DDI). Para obtener más información, vea IMiniportWavePci::NewStream y IMiniportWavePciStream::SetFormat.