NDK_FN_BUILD_LAM função de retorno de chamada (ndkpi.h)

Artigo
02/07/2025

A função NdkBuildLam (NDK_FN_BUILD_LAM) obtém um LAM (mapeamento de endereço lógico) do adaptador do provedor NDK para uma região de memória virtualmente contígua.

Sintaxe

NDK_FN_BUILD_LAM NdkFnBuildLam;

NTSTATUS NdkFnBuildLam(
  [in]           NDK_ADAPTER *pNdkAdapter,
  [in]           MDL *Mdl,
  [in]           SIZE_T Length,
  [in]           NDK_FN_REQUEST_COMPLETION RequestCompletion,
  [in, optional] PVOID RequestContext,
                 NDK_LOGICAL_ADDRESS_MAPPING *pNdkLAM,
                 ULONG *pLAMSize,
  [out]          ULONG *pFBO
)
{...}

Parâmetros

[in] pNdkAdapter

Um ponteiro para um objeto do adaptador NDK (NDK_ADAPTER).

[in] Mdl

Uma MDL (lista de descritores de memória) ou uma cadeia de MDLs. A parte da cadeia de MDL do endereço virtual inicial até o número de bytes no parâmetro Length deve representar uma região de memória virtualmente contígua.

[in] Length

O número de bytes a serem mapeados a partir do endereço virtual do primeiro MDL. O endereço virtual MDL pode ser obtido com a macro MmGetMdlVirtualAddress. Comprimento não deve exceder o número total de bytes representados pela cadeia de MDL.

[in] RequestCompletion

Um ponteiro para uma função de retorno de chamada NdkRequestCompletion (NDK_FN_REQUEST_COMPLETION).

[in, optional] RequestContext

Um valor de contexto para o provedor passar de volta para a função de retorno de chamada NdkRequestCompletion especificada no parâmetro RequestCompletion.

pNdkLAM

Um ponteiro para um buffer que conterá uma estrutura de NDK_LOGICAL_ADDRESS_MAPPING que contém uma matriz de páginas do adaptador. A matriz de páginas do adaptador é armazenada no membro AdapterPageArray e o membro AdapterPageCount contém o número de elementos de página do adaptador.

pLAMSize

O tamanho, em bytes, do buffer no parâmetro pNdkLAM para entrada ou o número real de bytes gravados para saída.

[out] pFBO

O primeiro valor de deslocamento de bytes (FBO) é retornado neste local. O FBO é o deslocamento inicial na primeira página do adaptador.

Valor de retorno

A função NdkBuildLam retorna um dos seguintes códigos NTSTATUS.

Código de retorno	Descrição
STATUS_SUCCESS	A operação foi concluída com êxito.
STATUS_PENDING	A solicitação está pendente, a função especificada no parâmetro RequestCompletion(NDK_FN_REQUEST_COMPLETION) será chamada quando a operação de build lam for concluída.
STATUS_INVALID_PARAMETER	A parte da cadeia de MDL do endereço virtual inicial até o número de bytes especificados no parâmetro comprimento não representa uma região de memória virtualmente contígua.
STATUS_INSUFFICIENT_RESOURCES	A solicitação falhou devido a recursos insuficientes. Importante A solicitação pode falhar embutida, bem como de forma assíncrona com esse código de status.
STATUS_BUFFER_TOO_SMALL	O tamanho do buffer indicado pelo parâmetro de pLAMSize é muito pequeno para manter o LAM. Nesse caso, o valor de pLAMSize é atualizado com o tamanho do buffer necessário.
Outros códigos de status	Ocorreu um erro.

Observações

A parte da cadeia de MDL do endereço virtual inicial até o número de bytes especificados no parâmetro comprimento deve representar uma região de memória virtualmente contígua. Caso contrário, o provedor NDK deverá falhar na solicitação. É responsabilidade do consumidor do NDK garantir que a cadeia de MDL esteja bloqueada. Ou seja, as páginas da alteração de MDL são fixadas na memória física.

Importante O consumidor do NDK não deve usar a cadeia de MDL enquanto NdkBuildLam estiver pendente de conclusão.

Um adaptador acessa a memória física com endereços lógicos. Isso é semelhante a uma CPU que acessa a memória física com endereços virtuais. Se um consumidor do NDK usar páginas de memória física diretamente como buffers de dados locais em solicitações de envio, recebimento, leitura ou gravação, ele deverá obter um mapeamento de endereço lógico do adaptador NDK do provedor NDK e usar os endereços lógicos em vez de endereços físicos. Da mesma forma, um consumidor de NDK também deve usar endereços lógicos em solicitações de registro rápido.

Um consumidor do NDK pode chamar a função NdkGetPrivilegedMemoryRegionToken (NDK_FN_GET_PRIVILEGED_MEMORY_REGION_TOKEN) para obter um token de região de memória privilegiada de um provedor NDK.

Todas as páginas do adaptador retornadas por um provedor NDK devem ter PAGE_SIZE bytes de comprimento, em que PAGE_SIZE é o tamanho da página de memória compatível com a plataforma de host, conforme definido em wdm.h.

O provedor deve tratar o valor do endereço virtual que a macro MmGetMdlVirtualAddress retorna para o MDL como um índice para o início da região de memória que está sendo mapeada. O provedor não deve usar o valor do endereço virtual como um endereço virtual válido para ler ou gravar conteúdo de buffer.

Se um provedor tiver um erro ao processar um NdkBuildLam solicitação, o provedor deverá liberar todos os mapeamentos parciais criados internamente até agora antes de concluir a solicitação com falha.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Nenhum com suporte, com suporte no NDIS 6.30 e posterior.
servidor com suporte mínimo	Windows Server 2012
da Plataforma de Destino	Windows
cabeçalho	ndkpi.h (inclua Ndkpi.h)
IRQL	<=DISPATCH_LEVEL