Функция IoBuildPartialMdl (wdm.h)

Статья
02/29/2024

Подпрограмма IoBuildPartialMdl создает новый список дескрипторов памяти (MDL), представляющий часть буфера, описываемую существующим языком MDL.

Синтаксис

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

Параметры

[in] SourceMdl

Указатель на MDL, описывающий исходный буфер, для которого необходимо сопоставить поддиапряд.

[in, out] TargetMdl

Указатель на выделенный вызывающим объектом MDL. Этот MDL должен быть достаточно большим, чтобы описать страницы в поддиапапсе, указанные в параметрах VirtualAddress и Length.

[in] VirtualAddress

Указатель на базовый виртуальный адрес для поддиапоряда, описываемого TargetMdl.

[in] Length

Указывает длину в байтах, сопоставляемую targetMdl. Это значение в сочетании с VirtualAddress должно указывать буфер, который является правильным поддиапуном буфера, описанным в SourceMdl. Если длина равна нулю, поддиапраг для сопоставления начинается с VirtualAddress и включает оставшийся диапазон, описанный в SourceMdl.

Возвращаемое значение

None

Remarks

Эта подпрограмма создает целевой MDL, описывающий поддиапряд буфера, который описывается исходным MDL. Этот поддиаг задается параметрами VirtualAddress и Length . Параметры SourceMdl и TargetMdl указывают на исходный MDL и целевой MDL.

Драйвер может использовать IoBuildPartialMdl для разделения большого запроса на передачу на более мелкие запросы на передачу. Физические страницы, описываемые исходным MDL, должны быть заблокированы, прежде чем драйвер вызовет IoBuildPartialMdl. Как правило, исходный MDL описывает буфер в адресном пространстве пользователя, а драйвер вызывает подпрограмму MmProbeAndLockPages для блокировки страниц в этом буфере. Однако драйвер может создать исходный MDL из непагружаемой памяти, вызвав подпрограмму MmBuildMdlForNonPagedPool, MmAllocatePagesForMdlEx или MmAllocatePagesForMdl .

При создании частичного MDL:

Если исходный MDL уже был сопоставлен в системном пространстве, частичный MDL использует это сопоставление, и нет необходимости сопоставлять его снова.
Если исходный MDL не был сопоставлен в системном пространстве, частичный MDL также не будет. Если вам нужен адрес в системном режиме, вызовите MmGetSystemAddressForMdlSafe для частичного MDL.
Если вы не знаете, какое из приведенных выше значений применимо, можно вызвать MmGetSystemAddressForMdlSafe независимо от этого. Если частичный MDL построен из исходного MDL, уже сопоставленного с системным адресным пространством, MmGetSystemAddressForMdlSafe использует существующее сопоставление источника. В противном случае MmGetSystemAddressForMdlSafe создает новое сопоставление.

Чтобы предотвратить утечку этого нового сопоставления, драйверы должны вызвать MmPrepareMdlForReuse перед повторным использованием частичного MDL. Кроме того, подпрограмма IoFreeMdl выпускает сопоставление системного адресного пространства для частичного MDL, если такое сопоставление существует.

Дополнительные сведения о списках MDL см. в разделе Использование многомерных выражений.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWriteA(kmdf)