Funzione IoBuildPartialMdl (wdm.h)

Articolo
08/08/2023

La routine IoBuildPartialMdl compila un nuovo elenco di descrittori di memoria (MDL) che rappresenta parte di un buffer descritto da un MDL esistente.

Sintassi

void IoBuildPartialMdl(
  [in]      PMDL  SourceMdl,
  [in, out] PMDL  TargetMdl,
  [in]      PVOID VirtualAddress,
  [in]      ULONG Length
);

Parametri

[in] SourceMdl

Puntatore a un MDL che descrive il buffer originale, di cui eseguire il mapping di un sottorange.

[in, out] TargetMdl

Puntatore a un MDL allocato dal chiamante. Questo MDL deve essere sufficientemente grande per descrivere le pagine nell'intervallo secondario specificato da VirtualAddress e Length.

[in] VirtualAddress

Puntatore all'indirizzo virtuale di base per il sottoinsieme da descrivere da TargetMdl.

[in] Length

Specifica la lunghezza, in byte, di cui eseguire il mapping tramite TargetMdl. Questo valore, in combinazione con VirtualAddress, deve specificare un buffer che sia un sottoinsieme appropriato del buffer descritto da SourceMdl. Se Length è zero, il sottorange di cui eseguire il mapping inizia in VirtualAddress e include l'intervallo rimanente descritto da SourceMdl.

Valore restituito

nessuno

Osservazioni

Questa routine compila un MDL di destinazione che descrive un sottoinsieme del buffer descritto dall'MDL di origine. Questo sottoinsieme viene specificato dai parametri VirtualAddress e Length . I parametri SourceMdl e TargetMdl puntano a MDL di origine e MDL di destinazione.

Un driver può usare IoBuildPartialMdl per suddividere una richiesta di trasferimento di grandi dimensioni in richieste di trasferimento più piccole. Le pagine fisiche descritte dall'MDL di origine devono essere bloccate prima che il driver chiami IoBuildPartialMdl. In genere, il file MDL di origine descrive un buffer nello spazio indirizzi utente e il driver chiama la routine MmProbeAndLockPages per bloccare le pagine in questo buffer. Tuttavia, il driver può compilare il file MDL di origine dalla memoria non di paging chiamando la routine MmBuildMdlForNonPagedPool, MmAllocatePagesForMdlEx o MmAllocatePagesForMdl .

Quando si crea un file MDL parziale:

Se il file MDL originale è già stato mappato nello spazio di sistema, il file MDL parziale condivide tale mapping e non è necessario eseguirne di nuovo il mapping.
Se il file MDL originale non è stato mappato nello spazio di sistema, il file MDL parziale non è neanche . Se è necessario un indirizzo in modalità di sistema, chiamare MmGetSystemAddressForMdlSafe nel file MDL parziale.
Se non si conosce quale delle condizioni precedenti si applica, è possibile chiamare MmGetSystemAddressForMdlSafe indipendentemente. Se un MDL parziale viene compilato da un MDL di origine già mappato nello spazio indirizzi di sistema, MmGetSystemAddressForMdlSafe usa il mapping di origine esistente. In caso contrario, MmGetSystemAddressForMdlSafe crea un nuovo mapping.

Per evitare la perdita di questo nuovo mapping, i driver devono chiamare MmPrepareMdlForReuse prima di riutilizzare un MDL parziale. Inoltre, la routine IoFreeMdl rilascia il mapping dello spazio indirizzi di sistema per un MDL parziale, se tale mapping esiste.

Per altre informazioni sugli mdls, vedere Using MDLs.For more information about MDLs, see Using MDLs.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 2000.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWriteA(kmdf)