PCALCULATE_SCATTER_GATHER_LIST_SIZE função de retorno de chamada (wdm.h)

Artigo
02/27/2024

A rotina CalculateScatterGatherList calcula o tamanho, em bytes, da lista de dispersão/coleta necessária para manter um determinado buffer.

Sintaxe

PCALCULATE_SCATTER_GATHER_LIST_SIZE PcalculateScatterGatherListSize;

NTSTATUS PcalculateScatterGatherListSize(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in, optional]  PMDL Mdl,
  [in]            PVOID CurrentVa,
  [in]            ULONG Length,
  [out]           PULONG ScatterGatherListSize,
  [out, optional] PULONG pNumberOfMapRegisters
)
{...}

Parâmetros

[in] DmaAdapter

Ponteiro para a estrutura DMA_ADAPTER retornada por IoGetDmaAdapter que representa o adaptador de master de barramento ou o controlador de DMA.

[in, optional] Mdl

NULL ou um ponteiro para o MDL que contém o buffer.

[in] CurrentVa

Ponteiro para o endereço virtual do início do buffer.

[in] Length

Especifica o comprimento do buffer, em bytes.

[out] ScatterGatherListSize

Ponteiro para a variável que a rotina usa para retornar o tamanho da lista de dispersão/coleta, em bytes.

[out, optional] pNumberOfMapRegisters

NULL ou ponteiro para a variável que a rotina usa para retornar o número de registros de mapa necessários para operações de DMA no buffer.

Retornar valor

CalculateScatterGatherList retorna um dos seguintes códigos de status.

Código de retorno	Descrição
STATUS_SUCCESS	Os valores retornados em ScatterGatherListSize e NumberOfMapRegisters são válidos .
STATUS_INSUFFICIENT_RESOURCES	O número de registros de mapa necessários excede o número de registros de mapa disponíveis.
STATUS_BUFFER_TOO_SMALL	O Comprimento especificado é muito grande para caber dentro do buffer.

Comentários

CalculateScatterGatherList não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina só pode ser chamada pelo ponteiro do endereço retornado em uma estrutura DMA_OPERATIONS . Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter com o membro Version do parâmetro DeviceDescription definido como DEVICE_DESCRIPTION_VERSION2. Se IoGetDmaAdapter retornar NULL, a rotina não estará disponível em sua plataforma.

Se o chamador passar NULL para o parâmetro Mdl , a rotina calculará o tamanho máximo possível necessário para manter uma lista de dispersão/coleta para o buffer especificado. Se o chamador especificar o MDL que contém o buffer no parâmetro Mdl , a rotina calculará o tamanho real necessário para manter a lista de dispersão/coleta.

Um driver usa CalculateScatterGatherList para alocar um buffer de lista de dispersão/coleta para passar para BuildScatterGatherList.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows XP e versões posteriores do Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h)
IRQL	Qualquer nível