Função IoBuildPartialMdl (wdm.h)

Artigo
08/08/2023

A rotina IoBuildPartialMdl cria uma nova lista de descritores de memória (MDL) que representa parte de um buffer descrito por um MDL existente.

Sintaxe

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

Parâmetros

[in] SourceMdl

Um ponteiro para um MDL que descreve o buffer original, do qual um subrange deve ser mapeado.

[in, out] TargetMdl

Um ponteiro para um MDL alocado pelo chamador. Esse MDL deve ser grande o suficiente para descrever as páginas no subrange especificado por VirtualAddress e Length.

[in] VirtualAddress

Um ponteiro para o endereço virtual base para o subrange a ser descrito pelo TargetMdl.

[in] Length

Especifica o comprimento, em bytes, a ser mapeado pelo TargetMdl. Esse valor, em combinação com VirtualAddress, deve especificar um buffer que seja um subintervalo adequado do buffer descrito por SourceMdl. Se Length for zero, o subrange a ser mapeado começará em VirtualAddress e incluirá o intervalo restante descrito pelo SourceMdl.

Retornar valor

Nenhum

Comentários

Essa rotina cria um MDL de destino que descreve um subintervalo do buffer descrito pelo MDL de origem. Esse subrange é especificado pelos parâmetros VirtualAddress e Length . Os parâmetros SourceMdl e TargetMdl apontam para o MDL de origem e o MDL de destino.

Um driver pode usar IoBuildPartialMdl para dividir uma solicitação de transferência grande em solicitações de transferência menores. As páginas físicas que o MDL de origem descreve devem ser bloqueadas antes que o driver chame IoBuildPartialMdl. Normalmente, o MDL de origem descreve um buffer no espaço de endereço do usuário e o driver chama a rotina MmProbeAndLockPages para bloquear as páginas nesse buffer. No entanto, o driver pode criar o MDL de origem de memória nãopagada chamando a rotina MmBuildMdlForNonPagedPool, MmAllocatePagesForMdlEx ou MmAllocatePagesForMdl .

Ao criar um MDL parcial:

Se o MDL original já tiver sido mapeado no espaço do sistema, o MDL parcial compartilhará esse mapeamento e não será necessário mapeá-lo novamente.
Se o MDL original não tiver sido mapeado no espaço do sistema, o MDL parcial também não será. Se você precisar de um endereço de modo de sistema, chame MmGetSystemAddressForMdlSafe no MDL parcial.
Se você não souber qual das opções acima se aplica, é seguro chamar MmGetSystemAddressForMdlSafe independentemente. Se um MDL parcial for criado a partir de um MDL de origem que já esteja mapeado para o espaço de endereço do sistema, MmGetSystemAddressForMdlSafe usará o mapeamento de origem existente. Caso contrário, MmGetSystemAddressForMdlSafe criará um novo mapeamento.

Para evitar que esse novo mapeamento seja vazado, os drivers devem chamar MmPrepareMdlForReuse antes de reutilizar um MDL parcial. Além disso, a rotina IoFreeMdl libera o mapeamento de espaço de endereço do sistema para um MDL parcial, se esse mapeamento existir.

Para obter mais informações sobre MDLs, consulte Usando MDLs.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<=DISPATCH_LEVEL
Regras de conformidade da DDI	MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWriteA(kmdf)