PCALCULATE_SCATTER_GATHER_LIST_SIZE fonction de rappel (wdm.h)

Article
02/07/2025

La routine CalculateScatterGatherList calcule la taille, en octets, de la liste de points/regroupements nécessaire pour contenir une mémoire tampon donnée.

Syntaxe

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
)
{...}

Paramètres

[in] DmaAdapter

Pointeur vers la structure DMA_ADAPTER retournée par IoGetDmaAdapter qui représente l’adaptateur maître de bus ou le contrôleur DMA.

[in, optional] Mdl

Soit NULL, soit un pointeur vers le MDL qui contient la mémoire tampon.

[in] CurrentVa

Pointeur vers l’adresse virtuelle du début de la mémoire tampon.

[in] Length

Spécifie la longueur de la mémoire tampon, en octets.

[out] ScatterGatherListSize

Pointeur vers la variable utilisée par la routine pour retourner la taille de la liste de nuages de points/regroupements, en octets.

[out, optional] pNumberOfMapRegisters

NULL ou pointeur vers la variable utilisée par la routine pour retourner le nombre de registres cartographiques nécessaires pour les opérations DMA sur la mémoire tampon.

Valeur de retour

CalculateScatterGatherList retourne l’un des codes d’état suivants.

Retourner le code	Description
STATUS_SUCCESS	Les valeurs retournées dans ScatterGatherListSize et NumberOfMapRegisters sont valides.
STATUS_INSUFFICIENT_RESOURCES	Le nombre de registres cartographiques requis dépasse le nombre de registres cartographiques disponibles.
STATUS_BUFFER_TOO_SMALL	La longueur spécifiée est trop grande pour s’adapter à la mémoire tampon.

Remarques

CalculateScatterGatherList n’est pas une routine système qui peut être appelée directement par nom. Cette routine peut être appelée uniquement par le pointeur de l’adresse retournée dans une structure DMA_OPERATIONS. Les pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter avec le membre version du paramètre DeviceDescription défini sur DEVICE_DESCRIPTION_VERSION2. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.

Si l’appelant passe NULL pour le paramètre Mdl, la routine calcule la taille maximale nécessaire pour contenir une liste de points/regroupements pour la mémoire tampon spécifiée. Si l’appelant spécifie le MDL qui contient la mémoire tampon dans le paramètre Mdl, la routine calcule la taille réelle nécessaire pour contenir la liste de points/regroupements.

Un pilote utilise CalculateScatterGatherList pour allouer une mémoire tampon de liste de nuages de points/regroupements à passer à BuildScatterGatherList.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans Windows XP et versions ultérieures de Windows.
plateforme cible	Bureau
d’en-tête	wdm.h (include Wdm.h)
IRQL	N’importe quel niveau