PCALCULATE_SCATTER_GATHER_LIST_SIZE fonction de rappel (wdm.h)

Article
03/01/2024

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 master bus ou le contrôleur DMA.

[in, optional] Mdl

NULL ou 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 que la routine utilise pour retourner la taille de la liste de points/regroupements, en octets.

[out, optional] pNumberOfMapRegisters

Null ou pointeur vers la variable que la routine utilise pour renvoyer le nombre de registres de carte nécessaires pour les opérations DMA sur la mémoire tampon.

Valeur retournée

CalculateScatterGatherList retourne l’un des codes status suivants.

Code de retour	Description
STATUS_SUCCESS	Les valeurs retournées dans ScatterGatherListSize et NumberOfMapRegisters sont valides .
STATUS_INSUFFICIENT_RESOURCES	Le nombre de registres de carte requis dépasse le nombre de registres de carte disponibles.
STATUS_BUFFER_TOO_SMALL	La longueur spécifiée est trop grande pour tenir dans 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 un pointeur à partir de l’adresse retournée dans une structure de 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 la valeur NULL pour le paramètre Mdl , la routine calcule la taille maximale possible 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 points/regroupements à passer à BuildScatterGatherList.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows XP et les versions ultérieures de Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wdm.h)
IRQL	N’importe quel niveau