PGET_DMA_TRANSFER_INFO funzione di callback (wdm.h)

Articolo
02/29/2024

La routine GetDmaTransferInfo calcola i requisiti di allocazione per un trasferimento DMA a dispersione/raccolta.

Sintassi

PGET_DMA_TRANSFER_INFO PgetDmaTransferInfo;

NTSTATUS PgetDmaTransferInfo(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      ULONGLONG Offset,
  [in]      ULONG Length,
  [in]      BOOLEAN WriteOnly,
  [in, out] PDMA_TRANSFER_INFO TransferInfo
)
{...}

Parametri

[in] DmaAdapter

Puntatore a una struttura DMA_ADAPTER . Questa struttura è l'oggetto adapter che rappresenta il dispositivo DMA master del driver o il canale DMA del sistema. Il chiamante ha ottenuto questo puntatore da una chiamata precedente alla routine IoGetDmaAdapter .

[in] Mdl

Puntatore alla catena MDL che descrive le pagine di memoria da trasferire. Per altre informazioni, vedere la sezione Osservazioni.

[in] Offset

Offset iniziale per il trasferimento DMA a dispersione/raccolta. Questo parametro è un offset di byte dall'inizio del buffer nella prima MDL della catena MDL. Se gli MDLs nella catena MDL specificano un totale di N byte di spazio buffer, i valori validi di Offset si trovano nell'intervallo da 0 a N-1.

[in] Length

Lunghezza, in byte, del trasferimento DMA. Se la catena MDL specifica un totale di N byte di spazio buffer, i valori validi di Length sono inclusi nell'intervallo 1 a N-Offset.

[in] WriteOnly

Indica se il trasferimento è un'operazione di sola scrittura, ovvero un trasferimento al dispositivo dalla memoria. Se WriteOnly è TRUE, le informazioni restituite sul trasferimento potrebbero non essere valide per una transazione di lettura. Questo parametro potrebbe indicare che sono necessarie operazioni di controllo della cache aggiuntive ai limiti del buffer per applicare la coesistenza della cache.

[in, out] TransferInfo

Puntatore a una struttura DMA_TRANSFER_INFO allocata dal chiamante. Il chiamante deve impostare il membro Version della struttura su DMA_TRANSFER_INFO_VERSION1 prima di chiamare GetDmaTransferInfo.

Valore restituito

GetDmaTransferInfo restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti degli errori possibili includono i codici di stato seguenti.

Codice restituito	Descrizione
STATUS_NOT_SUPPORTED	La routine non supporta la versione specificata della struttura DMA_TRANSFER_INFO_XXX .

Commenti

GetDmaTransferInfo 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.

Usare GetDmaTransferInfo per calcolare le dimensioni del buffer di dispersione/raccolta da allocare per le routine BuildScatterGatherListEx e MapTransferEx .

GetDmaTransferInfo sostituisce la routine CalculateScatterGatherList ed è più pratico da usare con BuildScatterGatherListEx.

I parametri Mdl, Offset e Length specificano insieme una raccolta di aree di memoria fisica da usare come buffer per un trasferimento DMA a dispersione/raccolta. Ogni area di memoria fisica è in genere una pagina o una parte di una pagina. GetDmaTransferInfo determina i requisiti di allocazione per questo trasferimento. Questi requisiti includono quanto segue:

Numero di elementi nell'elenco di dispersione/raccolta. Ogni elemento è una struttura SCATTER_GATHER_ELEMENT che descrive un blocco di memoria fisicamente contiguo.
Quantità di memoria da allocare per contenere l'elenco di dispersione/raccolta specificato. Questa allocazione di memoria include lo spazio necessario per l'elenco di dispersione/raccolta che descrive il buffer di I/O, ma non per il buffer di I/O stesso.
Numero di registri mappa necessari per convertire gli indirizzi fisici nell'elenco di dispersione/raccolta in indirizzi logici.

Per informazioni sulle informazioni di trasferimento DMA fornite dalla versione 1 della struttura DMA_TRANSFER_INFO_XXX, vedere DMA_TRANSFER_INFO_V1.

Un MDL descrive le pagine di memoria fisica che sottoscrivono un blocco di memoria virtuale bloccato e contiguo. In genere, queste pagine di memoria fisica non sono contigue. Una catena MDL è una raccolta ordinata di MDL che descrive la memoria che può essere usata per bufferre i dati di I/O. In genere, le aree di memoria virtuale descritte dagli MDL nella catena non sono contigue. Per altre informazioni sugli MDLs e sulle catene MDL, vedere Uso di MDLs.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL