Método IPortWavePciStream::GetMapping (portcls.h)

Artículo
08/07/2023

El GetMapping método obtiene una asignación del controlador de puerto y asocia una etiqueta a la asignación.

Sintaxis

NTSTATUS GetMapping(
  [in]  PVOID             Tag,
  [out] PPHYSICAL_ADDRESS PhysicalAddress,
  [out] PVOID             *VirtualAddress,
  [out] PULONG            ByteCount,
  [out] PULONG            Flags
);

Parámetros

[in] Tag

Especifica un valor de etiqueta que se va a asociar a la asignación. El controlador de puerto puede usar esta etiqueta en una llamada IMiniportWavePciStream::RevokeMappings posterior para identificar la asignación en la lista de asignaciones que se van a revocar. El controlador de minipuerto usa la etiqueta para identificar la asignación en la llamada IPortWavePciStream::ReleaseMapping que libera la asignación.

[out] PhysicalAddress

Puntero de salida para la dirección física. Este parámetro apunta a una variable de puntero asignada por el autor de la llamada en la que el método escribe la dirección física de la asignación. Especifique un valor de puntero válido que no sea NULL para este parámetro.

[out] VirtualAddress

Puntero de salida para la dirección virtual. Este parámetro apunta a una variable de puntero asignada por el autor de la llamada en la que el método escribe la dirección virtual de la asignación. Especifique un valor de puntero válido que no sea NULL para este parámetro.

[out] ByteCount

Puntero de salida para el recuento de bytes. Este parámetro apunta a una variable ULONG asignada por el autor de la llamada en la que el método escribe el número de bytes de la asignación. Especifique un valor de puntero válido que no sea NULL para este parámetro.

[out] Flags

Puntero de salida para la marca de estado. Este parámetro apunta a una variable ULONG asignada por el autor de la llamada en la que el método escribe una marca de estado. Especifique un valor de puntero válido que no sea NULL para este parámetro. Un valor de marca distinto de cero indica que la asignación adquirida en esta llamada es la última asignación de un paquete de E/S. Esta marca se puede usar para indicar que el hardware debe interrumpir el controlador de minipuerto cuando se realiza con esta asignación. En respuesta a la interrupción, el controlador de minipuerto puede obtener nuevas asignaciones para entregar al hardware. El controlador de minipuerto no está obligado a usar la bandera de esta manera.

Valor devuelto

GetMapping devuelve STATUS_SUCCESS si la llamada se realizó correctamente. De lo contrario, el método 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_NOT_FOUND	Una asignación no está disponible inmediatamente, pero el controlador de puerto llamará a IMiniportWavePciStream::MappingAvailable cuando una asignación esté disponible.

Comentarios

Las asignaciones obtenidas a través del GetMapping método deben liberarse llamando a IPortWavePciStream::ReleaseMapping a menos que el controlador de puerto los revoque. El controlador de puerto puede revocar asignaciones llamando al método IMiniportWavePciStream::RevokeMappings de la secuencia.

El almacenamiento en búfer de una secuencia que se reproduce a través de una patilla de representación del controlador de minipuerto se adjunta a uno o varios IRP. Cada IRP contiene una parte del almacenamiento en búfer de la secuencia. El almacenamiento en búfer de cada IRP es contiguo en la memoria virtual, pero las páginas de memoria que componen el búfer no se asignan en general a ubicaciones contiguas en memoria física. Aunque un controlador puede usar E/S programada para acceder al búfer a través de su asignación en memoria virtual, un controlador DMA requiere asignaciones físicas en su lugar.

El controlador de puerto WavePci usa el GetMapping método para exponer el búfer al controlador de minipuerto como una secuencia de asignaciones físicas. Una asignación típica es una página de memoria o menos de tamaño, aunque una asignación puede superar el tamaño de página si dos o más páginas ocupan ubicaciones adyacentes en la memoria física.

La llamada inicial a GetMapping genera la asignación al principio del búfer. Cada llamada sucesiva a presenta la siguiente asignación GetMapping secuencial en el búfer. Después de llegar al final del búfer, la siguiente GetMapping llamada genera la asignación al principio del búfer y la secuencia de asignación se repite.

La dirección de memoria virtual del modo kernel de la asignación se genera a través del parámetro VirtualAddress . El controlador de minipuerto usa esta dirección para acceder a la asignación bajo control directo del programa. La página que contiene la asignación está bloqueada y no se puede producir ningún error de página cuando el controlador accede a la asignación. El controlador DMA maestro de bus del dispositivo de audio usa la dirección que se genera a través del parámetro PhysicalAddress para acceder a la asignación.

El parámetro Tag es un valor PVOID que el autor de la llamada elige para identificar de forma única la asignación:

El controlador de puerto puede usar esta etiqueta para identificar la asignación en una llamada posterior a IMiniportWavePciStream::RevokeMappings.
El controlador miniport puede usar esta etiqueta para identificar la asignación en una llamada posterior a IPortWavePciStream::ReleaseMapping.

Aunque Tag se define como de tipo PVOID, el controlador de puerto nunca intenta usar este valor como puntero y no requiere que sea un puntero válido.

Un controlador de miniporte WavePci típico mantiene un registro de cada asignación que recibe. La etiqueta puede ser un puntero a un registro o a un índice en una matriz de registros, por ejemplo, en función de la implementación. El único requisito de una etiqueta es que sea un valor que se pueda convertir al tipo PVOID.

El parámetro Flags indica si la llamada para GetMapping recuperar la asignación final en la parte del búfer de datos de audio que está asociado al IRP de asignación actual. Cuando Flags indica que una asignación es la última asignación de un IRP, un controlador de minipuerto puede armar una interrupción de hardware para activarse cuando el controlador de miniporte termine de reproducir esa asignación. Cuando se desencadena la interrupción, este evento informa al controlador de minipuerto que necesita adquirir más asignaciones para agregar a su cola DMA. El parámetro Flags se usa normalmente por un controlador de miniporte que administra una única secuencia de reproducción desde el controlador del sistema KMixer. KMixer usa varios IRP de asignación (un mínimo de tres en la implementación actual de KMixer) para almacenar en búfer una sola secuencia de reproducción. Por lo tanto, si el controlador de minipuerto genera una interrupción de hardware cada vez que el controlador DMA finaliza con la asignación final en un IRP, las interrupciones deben producirse con frecuencia suficiente para evitar que la cola DMA deje de morir de hambre.

Normalmente, el parámetro Flags se omite mediante controladores de minipuerto que administran una o varias secuencias aceleradas por hardware de DirectSound (consulta DirectSound Hardware Acceleration in WDM Audio). En el caso de un búfer de DirectSound, todo el búfer se puede conectar a un único IRP. Si el búfer es grande y el controlador de minipuerto programa una interrupción de hardware solo cuando llega al final del búfer, se producirán interrupciones tan lejos de que la cola de DMA pueda morir de hambre. Además, si el controlador administra un gran número de secuencias, programar una interrupción de hardware cada vez que el parámetro Flags señala una condición de asignación final en una secuencia podría generar tantas interrupciones que se puedan degradar. En estas circunstancias, el controlador de minipuerto no debe depender de interrupciones de hardware para adquirir asignaciones. En su lugar, debe programar los DPC del temporizador para que se produzcan a intervalos regulares para adquirir asignaciones.

Es más probable que un controlador de miniporte llame GetMapping durante una llamada al método SetState, Service o MappingAvailable del objeto de secuencia de miniport (vea IMiniportWavePciStream).

Para evitar posibles interbloqueos, el controlador del adaptador debe evitar mantener un bloqueo de número durante su llamada a GetMapping. Consulta el controlador de audio de ejemplo ac97 en el Kit de controladores de Microsoft Windows (WDK) para obtener un ejemplo de código que usa un bloqueo de número para serializar accesos a estructuras de datos compartidas y periféricos en un sistema multiprocesador. El código de ejemplo llama a KeReleaseSpinLock antes de llamar a GetMappingKeAcquireSpinLock después de llamar a GetMapping. Entre las llamadas para liberar y adquirir el bloqueo de número, el subproceso del controlador no debe suponer que tiene acceso exclusivo a los datos o periféricos protegidos por el bloqueo de número. La herramienta Comprobador de controladores comprueba si hay bloqueos de número activos durante las llamadas a GetMapping; si detecta uno, genera una comprobación de errores de 0xC4 (detección de interbloqueos).

Aunque el tamaño de una asignación típica es una página de memoria o menos, una sola asignación puede superar el tamaño de página si una parte de un búfer de audio ocupa dos o más páginas contiguas en memoria física. Las asignaciones más grandes pueden crear problemas para el hardware DMA con defectos de diseño que limitan el tamaño del bloque. Por ejemplo, si un controlador DMA puede controlar un tamaño máximo de bloque de una sola página y GetMapping genera una asignación mayor que una página, el controlador de minipuerto debe dividir la asignación en bloques más pequeños que el hardware DMA puede controlar. Si el número resultante de bloques supera el número de registros de mapa disponibles en el hardware DMA, el controlador no puede poner en cola todos los bloques en una sola operación de dispersión o recopilación de DMA. Cuando esto ocurre, el controlador debe realizar un seguimiento de la parte no puesta en cola de la asignación e iniciar las transferencias de DMA de los bloques restantes más adelante cuando haya registros de mapa adicionales disponibles.

En Windows 98/Me, Windows 2000, Windows XP y Windows Server 2003, el GetMapping método nunca genera una asignación que abarca más de 16 páginas. Este límite puede cambiar en futuras versiones de Windows.

Para obtener más información sobre las asignaciones, consulte WavePci Latency.