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

Artículo
02/29/2024

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

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

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 Context de las estructuras de 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 en 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 secuencia. 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 de 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 ejecuta 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.

Comentarios

La AllocateDmaBuffer rutina 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 las rutinas AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl y 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 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 para un códec de audio o módem es responsable de programar el códec para administrar las transferencias de datos y reconocer el identificador de secuencia.

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, AllocateDmaBuffer se puede llamar sucesivamente para asignar nuevos búferes DMA. Sin embargo, antes de llamar a AllocateDmaBuffer, cualquier búfer DMA asignado anteriormente debe liberarse llamando a FreeDmaBuffer.

Durante las llamadas a AllocateDmaBuffer y FreeDmaBuffer, el motor DMA debe estar en el estado de flujo de restablecimiento. El motor DMA está en estado de restablecimiento inmediatamente después de la llamada a AllocateXxxDmaEngine. 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. Según la implementación de hardware, el tamaño de FIFO de un motor DMA puede ser estático o variar dinámicamente con los cambios en el formato de secuencia. Para obtener más información sobre el tamaño de 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 NewStream (en tiempo de creación de pin) o setFormat (después de llamar a una de las rutinas AllocateXxxDmaEngine en la DDI de audio HD). Para obtener más información, vea IMiniportWavePci::NewStream e IMiniportWavePciStream::SetFormat.