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

Artículo
03/08/2023

La AllocateCaptureDmaEngine rutina asigna un motor DMA para una secuencia de captura.

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

Sintaxis

PALLOCATE_CAPTURE_DMA_ENGINE PallocateCaptureDmaEngine;

NTSTATUS PallocateCaptureDmaEngine(
  [in]  PVOID _context,
  [in]  UCHAR CodecAddress,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parámetros

[in] _context

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

[in] CodecAddress

Especifica una dirección de códec. Este parámetro identifica los datos serie en la línea (SDI) en la que el códec proporciona los datos de captura al controlador de bus de audio HD. Un controlador de bus con n patillas SDI puede admitir hasta n códecs con direcciones que van de 0 a n-1.

[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.

[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

AllocateCaptureDmaEngine devuelve STATUS_SUCCESS si la llamada se reserva correctamente un motor DMA. De lo contrario, los posibles valores devueltos incluyen los códigos de error de la tabla siguiente.

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 captura y especifica el formato de datos para 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 AllocateCaptureDmaEngine 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 AllocateCaptureDmaEngine, el formato de la secuencia se puede cambiar llamando a ChangeBandwidthAllocation.

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 entrada. 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 AllocateCaptureDmaEngine, 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 del modelo de controlador de Windows (WDM) llama AllocateCaptureDmaEngine en tiempo de creación de patillas durante la ejecución de su método NewStream (por ejemplo, vea IMiniportWavePci::NewStream).