Metodo IPortWavePciStream::GetMapping (portcls.h)

Articolo
08/07/2023

Il GetMapping metodo ottiene un mapping dal driver della porta e associa un tag al mapping.

Sintassi

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

Parametri

[in] Tag

Specifica un valore di tag da associare al mapping. Il driver di porta può usare questo tag in una chiamata IMiniportWavePciStream::RevokeMappings per identificare il mapping nell'elenco dei mapping da revocare. Il driver miniport usa il tag per identificare il mapping nella chiamata IPortWavePciStream::ReleaseMapping che rilascia il mapping.

[out] PhysicalAddress

Puntatore di output per l'indirizzo fisico. Questo parametro punta a una variabile puntatore allocata dal chiamante in cui il metodo scrive l'indirizzo fisico del mapping. Specificare un valore puntatore non NULL valido per questo parametro.

[out] VirtualAddress

Puntatore di output per l'indirizzo virtuale. Questo parametro punta a una variabile puntatore allocata dal chiamante in cui il metodo scrive l'indirizzo virtuale del mapping. Specificare un valore puntatore non NULL valido per questo parametro.

[out] ByteCount

Puntatore di output per il conteggio dei byte. Questo parametro punta a una variabile ULONG allocata dal chiamante in cui il metodo scrive il numero di byte nel mapping. Specificare un valore puntatore non NULL valido per questo parametro.

[out] Flags

Puntatore di output per il flag di stato. Questo parametro punta a una variabile ULONG allocata dal chiamante in cui il metodo scrive un flag di stato. Specificare un valore puntatore non NULL valido per questo parametro. Un valore di flag diverso da zero indica che il mapping acquisito in questa chiamata è l'ultimo mapping in un pacchetto di I/O. Questo flag può essere usato per segnalare che l'hardware deve interrompere il driver miniport quando viene eseguito con questo mapping. In risposta all'interruzione, il driver miniport può ottenere nuovi mapping per recapitare all'hardware. Il driver miniport non è obbligato a usare il flag in questo modo.

Valore restituito

GetMapping restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, il metodo restituisce un codice di errore appropriato. La tabella seguente mostra alcuni dei possibili codici di stato restituiti.

Codice restituito	Descrizione
STATUS_NOT_FOUND	Un mapping non è immediatamente disponibile, ma il driver di porta chiamerà IMiniportWavePciStream::MappingAvailable quando un mapping diventa disponibile.

Commenti

I mapping ottenuti tramite il GetMapping metodo devono essere rilasciati chiamando IPortWavePciStream::ReleaseMapping a meno che non vengano revocati dal driver della porta. Il driver di porta può revocare i mapping chiamando il metodo IMiniportWavePciStream::RevokeMappings .

L'archiviazione buffer per un flusso riprodotto tramite il pin di rendering di un driver miniport è collegato a uno o più IRP. Ogni IRP contiene una parte dell'archiviazione buffer per il flusso. Ogni archiviazione buffer di IRP è contigua nella memoria virtuale, ma le pagine di memoria che comprendono il buffer non mappano in generale a posizioni contigue in memoria fisica. Anche se un driver può usare l'I/O programmato per accedere al buffer tramite il mapping nella memoria virtuale, un controller DMA richiede invece mapping fisici.

Il driver di porta WavePci usa il metodo per esporre il GetMapping buffer al driver miniport come sequenza di mapping fisici. Un mapping tipico è una pagina di memoria o minore di dimensioni, anche se un mapping può superare le dimensioni della pagina se due o più pagine si trovano in posizioni adiacenti in memoria fisica.

La chiamata iniziale a GetMapping restituisce il mapping all'inizio del buffer. Ogni chiamata successiva a GetMapping presenta il mapping sequenziale successivo nel buffer. Dopo aver raggiunto la fine del buffer, la chiamata successiva GetMapping restituisce il mapping all'inizio del buffer e la sequenza di mapping si ripete.

L'indirizzo di memoria virtuale in modalità kernel del mapping viene restituito tramite il parametro VirtualAddress . Il driver miniport usa questo indirizzo per accedere al mapping sotto il controllo del programma diretto. La pagina contenente il mapping è bloccata e non può verificarsi alcun errore di pagina quando il driver accede al mapping. Il controller DMA del bus del dispositivo audio usa l'indirizzo restituito tramite il parametro PhysicalAddress per accedere al mapping.

Il parametro Tag è un valore PVOID che il chiamante sceglie di identificare in modo univoco il mapping:

Il driver di porta potrebbe usare questo tag per identificare il mapping in una chiamata successiva a IMiniportWavePciStream::RevokeMappings.
Il driver miniport può usare questo tag per identificare il mapping in una chiamata successiva a IPortWavePciStream::ReleaseMapping.

Sebbene tag sia definito come tipo PVOID, il driver di porta non tenta mai di usare questo valore come puntatore e non richiede che sia un puntatore valido.

Un tipico driver miniport WavePci mantiene un record di ogni mapping ricevuto. Il tag può essere un puntatore a un record o un indice in una matrice di record, ad esempio, a seconda dell'implementazione. L'unico requisito per un tag è che è un valore che può essere eseguito il cast per digitare PVOID.

Il parametro Flags indica se la chiamata per GetMapping recuperare il mapping finale nella parte del buffer dati audio collegato all'IRP di mapping corrente. Quando flag indica che un mapping è l'ultimo mapping in un'istanza di IRP, un driver miniport può armezzare un interruzione hardware per attivare quando il driver miniport termina la riproduzione di tale mapping. Quando l'interruzione viene attivata, questo evento informa il driver miniport che deve acquisire più mapping da aggiungere alla coda DMA. Il parametro Flags viene in genere usato da un driver miniport che gestisce un singolo flusso di riproduzione dal driver di sistema KMixer. KMixer usa diversi irp di mapping (almeno tre nell'implementazione corrente di KMixer) per bufferare un singolo flusso di riproduzione. Pertanto, se il driver miniport genera un interruzione hardware ogni volta che il controller DMA termina con il mapping finale in un'IRP, gli interruzioni devono verificarsi abbastanza frequentemente per mantenere la coda DMA da morire.

Il parametro Flags viene in genere ignorato dai driver miniport che gestiscono uno o più flussi con accelerazione hardware DirectSound (vedere Accelerazione hardware DirectSound in WDM Audio). Nel caso di un buffer DirectSound, l'intero buffer può essere collegato a un singolo IRP. Se il buffer è grande e il driver miniport pianifica un interruzione hardware solo quando raggiunge la fine del buffer, gli interruzioni si verificheranno finora a parte che la coda DMA potrebbe terminare. Inoltre, se il driver gestisce un numero elevato di flussi, la pianificazione di un interruzione hardware ogni volta che il parametro Flags segnala una condizione di mapping finale in un flusso potrebbe generare così tanti interruzioni che le prestazioni possono essere degradate. In queste circostanze, il driver miniport non deve basarsi sugli interruzioni hardware per acquisire mapping. È invece consigliabile pianificare l'esecuzione dei controller di dominio timer a intervalli regolari per acquisire mapping.

Un driver miniport è più probabile chiamare GetMapping durante una chiamata al metodo SetState, Service o MappingAvailable dell'oggetto di flusso miniport (vedere IMiniportWavePciStream).

Per evitare potenziali deadlock, il driver dell'adattatore deve evitare di contenere un blocco di rotazione durante la chiamata a GetMapping. Vedere il driver audio di esempio ac97 in Microsoft Windows Driver Kit (WDK) per un esempio di codice che usa un blocco spin per serializzare gli accessi alle strutture di dati condivise e alle periferiche in un sistema multiprocessore. Il codice di esempio chiama KeReleaseSpinLock prima di chiamare GetMapping e chiamare KeAcquireSpinLock dopo aver chiamato GetMapping. Tra le chiamate al rilascio e l'acquisizione del blocco di rotazione, il thread del driver non deve presumere che abbia accesso esclusivo ai dati o alle periferiche protette dal blocco di spin. Lo strumento Verifica driver controlla i blocchi di spin attivi durante le chiamate a GetMapping; se ne rileva uno, genera un 0xC4 (rilevamento deadlock).

Anche se le dimensioni di un mapping tipico sono una pagina di memoria o meno, un singolo mapping può superare le dimensioni della pagina se una parte di un buffer audio si verifica occupando due o più pagine contigue in memoria fisica. I mapping più grandi possono creare problemi per l'hardware DMA con difetti di progettazione che limitano le dimensioni del blocco. Ad esempio, se un controller DMA può gestire una dimensione massima del blocco di una singola pagina e GetMapping restituisce un mapping maggiore di una pagina, il driver miniport deve suddividere il mapping in blocchi più piccoli che l'hardware DMA può gestire. Se il numero risultante di blocchi supera il numero di registri mappa disponibili nell'hardware DMA, il driver non può accodamento di tutti i blocchi in un'unica operazione DMA a dispersione/raccolta. In questo caso, il driver deve tenere traccia della parte unqueued del mapping e avviare i trasferimenti DMA dei blocchi rimanenti in un secondo momento quando diventano disponibili registri mappa aggiuntivi.

In Windows 98/Me, Windows 2000, Windows XP e Windows Server 2003, il GetMapping metodo non restituisce mai un mapping che si estende su più di 16 pagine. Questo limite potrebbe cambiare nelle versioni future di Windows.

Per altre informazioni sui mapping, vedere WavePci Latency.