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

Artículo
02/29/2024

La rutina SetupDmaEngineWithBdl configura un motor DMA para usar un búfer DMA asignado por el autor de la llamada.

El tipo de puntero de función para una rutina SetupDmaEngineWithBdl se define como se indica a continuación.

Sintaxis

PSETUP_DMA_ENGINE_WITH_BDL PsetupDmaEngineWithBdl;

NTSTATUS PsetupDmaEngineWithBdl(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
  [in]  PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

Parámetros

[in] _context

Especifica el valor de contexto del miembro Context de la estructura HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

Identificador que identifica el motor DMA. Este valor de identificador se obtuvo de una llamada anterior a AllocateCaptureDmaEngine o AllocateRenderDmaEngine.

[in] BufferLength

Longitud del búfer.

[in] Lvi

Especifica el último índice válido (LVI). Este parámetro contiene el índice del último descriptor de búfer válido en el BDL. Una vez que el motor DMA procesa este descriptor, vuelve al primer descriptor de la lista y continúa el procesamiento. Si el BDL contiene n descriptores, se numeran de 0 a n-1. El valor lvi debe ser al menos 1; es decir, el BDL debe contener al menos dos entradas válidas para que el motor DMA pueda comenzar la operación.

[in] Isr

Puntero de función al ISR del autor de la llamada. Si el autor de la llamada establece el bit de interrupción al finalizar (IOC) en uno o varios de los descriptores de búfer del BDL, el controlador de bus de audio HD llama al ISR cada vez que se produce una interrupción de IOC en la secuencia. Este parámetro es un puntero de función de tipo HDAUDIO_BDL_ISR, que se define en la sección Comentarios siguiente.

[in] Context

Contexto.

[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 UINT asignada por el autor de la llamada en la que la rutina escribe el tamaño de FIFO.

Valor devuelto

SetupDmaEngineWithBdl 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_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 o formato de secuencia no válido).
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 el dispositivo DMA o el búfer DMA no se asignan o que la secuencia no está en estado de restablecimiento.

Comentarios

La rutina SetupDmaEngineWithBdl se usa junto con las rutinas AllocateContiguousDmaBuffer y FreeContiguousDmaBuffer . Estas tres rutinas solo están disponibles en la versión HDAUDIO_BUS_INTERFACE_BDL de la DDI de audio HD. Esta DDI no incluye las rutinas AllocateDmaBuffer y FreeDmaBuffer , que nunca se usan junto con AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl y FreeContiguousDmaBuffer. 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.

El autor de la llamada debe llamar a AllocateContiguousDmaBuffer para asignar almacenamiento en la memoria del sistema para el búfer DMA y el BDL que describe las páginas de memoria física del búfer. Las entradas BDL deben residir en la memoria físicamente contigua. El BDL y la memoria del búfer deben cumplir los requisitos de alineación que se describen en la Especificación de audio de alta definición de Intel (consulte el sitio web de Intel HD Audio ).

Tanto el BDL como la memoria del búfer que describe deben permanecer válidos durante las operaciones DMA. Después de la llamada a SetupDmaEngineWithBdl, el BDL y la memoria del búfer deben permanecer válidos siempre que el motor DMA siga usando el búfer. El motor DMA usa el búfer hasta que el controlador de función reemplaza el búfer llamando a SetupDmaEngineWithBdl de nuevo o libera el motor DMA llamando a FreeDmaEngine. El controlador de función es responsable de llamar a FreeContiguousDmaBuffer para liberar el búfer y BDL cuando ya no son necesarios.

Al asignar memoria para el búfer, el autor de la llamada debe satisfacer todas las restricciones de hardware para la dirección, la longitud y la alineación de los bloques de memoria físicamente contiguos que especifica el BDL. Por lo tanto, solo los clientes con conocimientos significativos sobre el controlador de bus y el hardware del sistema deben usar la rutina SetupDmaEngineWithBdl .

Antes de llamar a SetupDmaEngineWithBdl para configurar un motor DMA, el cliente debe llamar a AllocateCaptureDmaEngine o AllocateRenderDmaEngine para asignar el motor DMA. El parámetro handle es el valor obtenido de la llamada anterior a Allocate XxxDmaEngine.

El autor de la llamada es responsable de programar el códec para administrar las transferencias de datos y reconocer el identificador de flujo.

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

Después de la llamada a SetupDmaEngineWithBdl, el motor DMA se encuentra en el estado Reset. Para iniciar el motor DMA, llame a SetDmaEngineState.

Parameter isr especifica el ISR al que el controlador de bus de audio HD debe llamar cada vez que se produce una interrupción de IOC en la secuencia. Este parámetro es un puntero de función de tipo HDAUDIO_BDL_ISR, que se define como:

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

El controlador del bus de audio HD llama al ISR con el mismo valor de contexto que el cliente especificó en el parámetro de contexto de la llamada a SetupDmaEngineWithBdl anterior. El parámetro interruptBitMask contiene los bits del registro de estado de secuencia del dispositivo del controlador de audio HD que indican el motivo de la interrupción. En la tabla siguiente se muestra el significado de los bits individuales en interruptBitMask.

Números de bits	Significado
31:5	Sin usar.
4	Error de descriptor (DESE). Si se produce un error durante la captura de un descriptor de búfer, el controlador de audio HD establece el bit DESE en 1.
3	Error FIFO (FIFOE). Si se produce un error de FIFO (una saturación en un flujo de salida o una ejecución insuficiente en una secuencia de entrada), el controlador de audio HD establece el bit FIFOE en 1.
2	Estado de interrupción de finalización del búfer (BCIS). Si el bit de IOC se establece en 1 en el byte de comando del descriptor de búfer, el controlador de audio HD establece el bit BCIS en 1 después de procesar la última muestra de un búfer.
1:0	Sin usar.

El controlador del bus de audio HD establece los bits sin usar en cero. En lugar de suponer que se ha producido una interrupción del IOC, el ISR siempre debe comprobar el parámetro interruptBitMask para determinar si se ha producido un error de secuencia. Para obtener más información sobre los bits de estado de interrupción que se muestran en la tabla anterior, consulte la descripción de los registros de estado de la secuencia en la Especificación de audio de alta definición de Intel.

El tamaño de FIFO es el número máximo de bytes que el motor DMA puede contener en su búfer interno en cualquier momento. 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.

El autor de la llamada debe asignar la memoria del búfer y BDL del grupo no paginado.