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

Artículo
08/07/2023

La AllocateRenderDmaEngine rutina asigna un motor DMA para una secuencia de representación.

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

Sintaxis

PALLOCATE_RENDER_DMA_ENGINE PallocateRenderDmaEngine;

NTSTATUS PallocateRenderDmaEngine(
  [in]  PVOID _context,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [in]  BOOLEAN Stripe,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parámetros

[in] _context

Especifica el valor de contexto de los miembros Context de las estructuras HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2 o HDAUDIO_BUS_INTERFACE_BDL.

[in] StreamFormat

Especifica el formato de secuencia solicitado. Este parámetro apunta a una estructura asignada por el autor de la llamada de tipo HDAUDIO_STREAM_FORMAT que especifica un formato de datos para la secuencia.

[in] Stripe

Especifica si se va a habilitar el seccionamiento. Si es TRUE, la rutina habilita el seccionamiento en las transferencias DMA. Si es FALSE, el seccionamiento está deshabilitado.

[out] Handle

Recupera el identificador del motor DMA. Este parámetro apunta a una variable HANDLE asignada por el autor de la llamada en la que la rutina escribe un identificador que identifica el motor DMA.

[out] ConverterFormat

Recupera el formato del convertidor. Este parámetro apunta a una estructura asignada por el autor de la llamada de tipo HDAUDIO_CONVERTER_FORMAT en la que la rutina escribe el formato codificado.

Valor devuelto

AllocateRenderDmaEngine devuelve STATUS_SUCCESS si la llamada se reserva correctamente un motor DMA. 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 error de devolución.

Código devuelto	Descripción
STATUS_BUFFER_TOO_SMALL	Indica que el motor DMA no puede asignar suficiente almacenamiento FIFO interno para admitir el formato de secuencia solicitado.
STATUS_INSUFFICIENT_RESOURCES	Indica que no hay ningún motor DMA disponible o que la solicitud supera los recursos de ancho de banda disponibles.
STATUS_INVALID_PARAMETER	Indica que uno de los valores de parámetro es incorrecto (valor de parámetro no válido o puntero incorrecto).

Comentarios

Esta rutina asigna un motor DMA de representación y especifica el formato de datos de la secuencia. Si se ejecuta correctamente, la rutina genera un identificador que el autor de la llamada usa posteriormente para identificar el motor DMA.

La AllocateRenderDmaEngine rutina reserva recursos de hardware (el motor DMA), pero no configura el hardware DMA. Después de llamar a esta rutina para reservar un motor DMA, un controlador de función debe asignar un búfer DMA al motor DMA y configurar el motor para usar el búfer:

Si usa la versión HDAUDIO_BUS_INTERFACE de la DDI de audio HD, el controlador de función llama a la rutina AllocateDmaBuffer para que el controlador del bus de audio HD asigne un búfer de datos para las transferencias DMA y configure el motor DMA para usar el búfer.
Si usa la versión HDAUDIO_BUS_INTERFACE_BDL de DDI, el controlador de función llama a AllocateContiguousDmaBuffer para asignar el búfer DMA y llama a la rutina SetupDmaEngineWithBdl para configurar el motor DMA para usar el búfer.

El parámetro streamFormat especifica el formato de datos para la secuencia de captura. Después de la llamada a AllocateRenderDmaEngine, el formato de la secuencia se puede cambiar llamando a ChangeBandwidthAllocation.

El parámetro stripe especifica si el motor DMA va a usar el seccionamiento para acelerar las transferencias de datos. Para obtener más información, vea Seccionamiento.

A través del parámetro handle, la rutina genera un identificador que el autor de la llamada usa para identificar el motor DMA asignado en llamadas posteriores a AllocateDmaBuffer, ChangeBandwidthAllocation, FreeDmaBuffer, SetupDmaEngineWithBdl y SetDmaEngineState. El controlador de función libera el identificador mediante una llamada a FreeDmaEngine.

A través del parámetro converterFormat , la rutina genera un valor de descriptor de flujo que el autor de la llamada puede usar para programar los convertidores de salida. La rutina codifica la información del parámetro streamFormat en un entero de 16 bits. Para obtener más información, consulte HDAUDIO_CONVERTER_FORMAT.

Inmediatamente después de una llamada correcta a AllocateRenderDmaEngine, el motor DMA se encuentra en el estado de flujo de restablecimiento. Antes de llamar a SetDmaEngineState para cambiar el motor DMA al estado en ejecución, en pausa o detenido, el cliente debe asignar primero un búfer DMA para el motor.

Un controlador de audio WDM llama AllocateRenderDmaEngine en tiempo de creación de patillas durante la ejecución de su método NewStream (por ejemplo, vea IMiniportWavePci::NewStream).