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

Artículo
08/07/2023

La AllocateContiguousDmaBuffer rutina asigna un búfer DMA que consta de un único bloque contiguo de memoria física.

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

Sintaxis

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

Parámetros

[in] _context

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

[in] Handle

Controle la identificación del motor DMA. Este valor de identificador se obtuvo de una llamada anterior a AllocateCaptureDmaEngine o AllocateRenderDmaEngine.

RequestedBufferSize

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

[out] DataBuffer

Recupera el búfer de datos. Este parámetro apunta a una variable PVOID asignada por el autor de la llamada en la que la rutina escribe la dirección virtual del sistema del búfer de datos.

[out] BdlBuffer

Recupera la lista de descriptores de búfer (BDL). Este parámetro apunta a una variable PVOID asignada por el autor de la llamada en la que la rutina escribe la dirección virtual del sistema del BDL. El tamaño de asignación de BDL es exactamente una página de memoria y el BDL comienza en un límite de página.

Valor devuelto

AllocateContiguousDmaBuffer 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 nivel de solicitud de interrupción (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 AllocateContiguousDmaBuffer rutina se usa junto con las rutinas SetupDmaEngineWithBdl 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. Para obtener más información, vea Diferencias entre las dos versiones de DDI.

AllocateContiguousDmaBuffer asigna un búfer de datos para el motor DMA especificado. También asigna una página de memoria para el BDL. Según la arquitectura del procesador host, un tamaño de página típico puede ser de 4096 o 8 192 bytes. El búfer de datos consta de un único bloque contiguo de memoria física.

El parámetro handle especifica el motor DMA que va a usar el búfer de datos y BDL. La rutina asigna almacenamiento que cumple los requisitos de tamaño, alineación y posición del motor DMA.

El almacenamiento que asigna la rutina para el búfer de datos y BDL no está inicializado. El controlador de función es responsable de rellenar el BDL antes de enviarlo a la rutina SetupDmaEngineWithBdl . El controlador de función también es responsable de programar el códec para administrar las transferencias de datos y reconocer el identificador de flujo.

Para generar interrupciones de IOC a intervalos precisos, es posible que sea necesario que el controlador de función divida la asignación del búfer de datos en varios fragmentos de un tamaño determinado. Cada fragmento se describe mediante una entrada BDL. El tamaño del fragmento se puede ajustar para ajustar la velocidad de interrupción. Según la especificación de audio de alta definición de Intel (consulte el sitio web de Audio hd de Intel ), cada fragmento debe comenzar en un límite de 128 bytes, aunque no se aplica este requisito de alineación a la longitud del fragmento. Por lo tanto, podría existir una brecha entre el final de un fragmento y el principio del siguiente. Al llamar a SetupDmaEngineWithBdl, el controlador de función debe especificar un valor para el parámetro bufferSize que representa la suma de los tamaños de los fragmentos individuales que describen las entradas BDL. Este tamaño será menor o igual que el número de bytes especificados en el parámetro requestedBufferSize de la AllocateContiguousDmaBuffer rutina.

Durante la vigencia de un identificador de motor DMA, AllocateContiguousDmaBuffer se puede llamar sucesivamente para asignar nuevos búferes DMA. Sin embargo, antes de llamar a AllocateContiguousDmaBuffer, cualquier búfer DMA asignado anteriormente debe liberarse llamando a FreeContiguousDmaBuffer.

Durante las llamadas a AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl y FreeContiguousDmaBuffer, 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.

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 FreeContiguousDmaBuffer).
La secuencia está en un estado distinto del restablecimiento.