PCREATE_COMMON_BUFFER_FROM_MDL funzione di callback (wdm.h)

Articolo
08/08/2023

La routine CreateCommonBufferFromMdl tenterà di creare un buffer comune da un MDL testando la compatibilità dell'accesso dei dispositivi e potenzialmente eseguendo il mapping della memoria a un intervallo logico contiguo a seconda del tipo di conversione. Analogamente a tutte le altre funzioni comuni di allocazione del buffer, questa funzione non fornisce una garanzia di avanzamento in avanti.

Sintassi

PCREATE_COMMON_BUFFER_FROM_MDL PcreateCommonBufferFromMdl;

NTSTATUS PcreateCommonBufferFromMdl(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  PMDL Mdl,
  [in]  PDMA_COMMON_BUFFER_EXTENDED_CONFIGURATION ExtendedConfigs,
  [in]  ULONG ExtendedConfigsCount,
  [out] PPHYSICAL_ADDRESS LogicalAddress
)
{...}

Parametri

[in] DmaAdapter

Fornisce un puntatore all'adapter DMA che esegue l'operazione.

[in] Mdl

Fornisce il file MDL di cui verrà eseguito il mapping a un buffer comune.

Affinché un MDL sia in grado di eseguire il backup di un buffer comune, è necessario soddisfare le condizioni seguenti:

Il file MDL deve avere pagine che risiedono sempre per la durata del buffer comune e mappate nello spazio indirizzi di sistema. Questa operazione può essere eseguita con gli approcci seguenti:
Il file MDL viene creato da un buffer nel pool non di paging tramite MmBuildMdlForNonPagedPool.
MDL è stato bloccato tramite MmProbeAndLockPages ed è stato mappato allo spazio di sistema tramite MmGetSystemAddressForMdlSafe.
Le pagine fisiche per MDL sono state allocate tramite MmAllocatePagesForMdlEx e mappate allo spazio di sistema tramite MmGetSystemAddressForMdlSafe.
Il linguaggio MDL deve rappresentare un'area allineata alla pagina e essere un multiplo di PAGE_SIZE.
- Se viene usata la configurazione estesa SubSection, la parte del file MDL in uso deve essere allineata a pagina e essere un multiplo di PAGE_SIZE.
MDL non deve essere un MDL concatenato.
- Se viene usata la configurazione estesa subSection, è possibile specificare un MDL concatenato, ma la parte del file MDL in uso deve essere contenuta in un singolo MDL nella catena.
Se il mapping di DMA non viene usato, il file MDL deve rappresentare la memoria fisicamente contigua ed essere accessibile al dispositivo.

[in] ExtendedConfigs

Fornisce una matrice facoltativa di strutture DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION per configurare ulteriormente la creazione del buffer comune supportato da MDL.

Se nella matrice vengono fornite più configurazioni della stessa DMA_COMMON_BUFFER_EXTENDED_CONFIGURATION_TYPE , la creazione avrà esito negativo.

[in] ExtendedConfigsCount

Fornisce il numero di configurazioni estese nella matrice ExtendedConfigs .

[out] LogicalAddress

In caso di esito positivo, fornisce l'indirizzo logico del buffer comune risultante.

Valore restituito

CreateCommonBufferFromMdl restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti di errore possibili includono i codici di stato seguenti.

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il chiamante ha fornito una configurazione MDL o estesa non compatibile.
STATUS_NOT_SUPPORTED	Il chiamante ha fornito una configurazione estesa non supportata nel sistema corrente.
STATUS_INSUFFICIENT_RESOURCES	Il sistema non dispone di memoria sufficiente per creare metadati di conservazione e mapping.

Commenti

CreateCommonBufferFromMdl non è una routine di sistema che può essere chiamata direttamente per nome. Questa routine può essere chiamata solo dal puntatore dall'indirizzo restituito in una struttura DMA_OPERATIONS . I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter con il membro Version del parametro DeviceDescription impostato su DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter restituisce NULL, la routine non è disponibile nella piattaforma.

Un buffer comune creato da CreateCommonBufferFromMdl verrà rimosso tramite FreeCommonBuffer. Il chiamante deve fornire l'indirizzo virtuale di sistema come indirizzo virtuale per garantire che il buffer comune venga rimosso correttamente dalle strutture comuni di memorizzazione nel buffer dell'adapter. Il driver è ancora responsabile dello sblocco e della liberazione del file MDL e delle pagine di supporto.

Per creare un buffer comune in cui HAL è responsabile della gestione della memoria di backup, usare AllocateCommonBufferWithBounds.