NdisMAllocateNetBufferSGList, fonction (ndis.h)

2025-02-07

Prudence

Pour les processeurs ARM et ARM64, nous recommandons vivement aux enregistreurs de pilotes NDIS d’utiliser WDF DMA ou WDM DMA au lieu de NDIS Scatter/Collect DMA.

Pour plus d’informations sur WDF DMA, consultez gestion des opérations DMA dans les pilotes KMDF.

Pour plus d’informations sur WDM DMA, consultez les rubriques enfants relatives à DMA de Gestion des entrées/sorties pour les pilotes.

Les pilotes miniport master bus appellent la fonction NdisMAllocateNetBufferSGList pour obtenir une liste de nuages de points/regroupements pour les données réseau associées à une structure NET_BUFFER.

Syntaxe

NDIS_STATUS NdisMAllocateNetBufferSGList(
  [in]           NDIS_HANDLE NdisMiniportDmaHandle,
  [in]           PNET_BUFFER NetBuffer,
  [in]           PVOID       Context,
  [in]           ULONG       Flags,
  [in, optional] PVOID       ScatterGatherListBuffer,
  [in]           ULONG       ScatterGatherListBufferSize
);

Paramètres

[in] NdisMiniportDmaHandle

Handle vers une zone de contexte utilisée par NDIS pour gérer une ressource DMA. L’appelant a obtenu ce handle en appelant le fonction NdisMRegisterScatterGatherDma.

[in] NetBuffer

Pointeur vers une structure NET_BUFFER. NdisMAllocateNetBufferSGList alloue une liste de nuages de points/regroupements pour les données réseau associées à cette structure NET_BUFFER. La liste de points/regroupements est générée à partir des données commençant au début du MDL spécifié au Membre currentMdl de la structure de NET_BUFFER_DATA associée.

[in] Context

Pointeur vers une zone de contexte créée par l’appelant. HAL transmet ce pointeur à MiniportProcessSGList après avoir créé la liste de nuages de points/regroupements. L’appelant peut utiliser cette zone de contexte à ses propres fins.

[in] Flags

Indicateurs NDIS qui peuvent être combinés à une opération OR. Pour effacer tous les indicateurs, définissez ce membre sur zéro. Cette fonction prend en charge l’indicateur NDIS_SG_LIST_WRITE_TO_DEVICE qui ; si la valeur est définie, indique la direction du transfert DMA entre le NET_BUFFER et l’appareil. Si NDIS_SG_LIST_WRITE_TO_DEVICE est clair, le transfert provient de l’appareil. Les pilotes miniport doivent définir cet indicateur sur le chemin d’envoi lorsque l’opération DMA transfère les données d’un NET_BUFFER à l’appareil. Les pilotes miniports qui effectuent des opérations DMA de l’appareil vers un NET_BUFFER pré-alloué, par exemple les cartes réseau compatibles avec la cheminée pendant les opérations de réception, doivent effacer cet indicateur.

[in, optional] ScatterGatherListBuffer

S’il n'NULL, ScatterGatherListBuffer spécifie un pointeur vers le stockage que l’appelant alloue pour contenir la liste de points/regroupements. Si NULL, NDIS alloue du stockage pour la liste de points/regroupements.

[in] ScatterGatherListBufferSize

Si le paramètre ScatterGatherListBuffer n’est pas NULL, ScatterGatherListBufferSize spécifie la taille de la mémoire tampon qui contient la liste de nuages de points/regroupements. Si cette taille est trop petite, NDIS alloue du stockage pour la liste de nuages de points/regroupements. Si le paramètre ScatterGatherListBuffer est NULL, ce paramètre n’est pas utilisé.

Valeur de retour

NdisMAllocateNetBufferSGList retourne l’une des valeurs suivantes :

Retourner le code	Description
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList généré avec succès la liste de nuages/regroupements pour la structure NET_BUFFER spécifiée.
NDIS_STATUS_RESOURCES	NdisMAllocateNetBufferSGList a échoué en raison de ressources insuffisantes.

Remarques

Un pilote miniport maître NDIS appelle NdisMAllocateNetBufferSGList à partir de son MiniportSendNetBufferLists fonction. Le pilote miniport appelle NdisMAllocateNetBufferSGList une fois pour chaque structure NET_BUFFER pour laquelle il doit obtenir une liste de points/regroupements.

Lorsqu’un pilote miniport appelle NdisMAllocateNetBufferSGList, NDIS appelle HAL pour générer la liste de nuages de points/regroupements. Une fois que HAL génère la liste de points/regroupements, il appelle la fonction MiniportProcessSGList que le pilote miniport inscrit en appelant NdisMRegisterScatterGatherDma.

HAL peut appeler MiniportProcessSGList avant ou après le retour de NDIS à partir de NdisMAllocateNetBufferSGList. Les pilotes Miniport ne doivent pas tenter d’accéder à la liste de nuages de points/de collecte tant qu’après les appels HAL MiniportProcessSGList.

Pour améliorer les performances du système, les pilotes miniport doivent préallouer les mémoires tampons pour l’utilisation dans le paramètre ScatterGatherListBuffer de NdisMAllocateNetBufferSGList. NDIS fournit la taille recommandée pour les mémoires tampons dans le ScatterGatherListSize membre du paramètre DmaDescription lorsque le pilote miniport appelle NdisMRegisterScatterGatherDma. Les pilotes miniport spécifient la taille de la mémoire tampon dans le paramètre ScatterGatherListBufferSize lorsqu’ils appellent NdisMAllocateNetBufferSGList.

NDIS peut allouer une mémoire tampon même si le pilote miniport spécifie une mémoire tampon dans le paramètre ScatterGatherListBuffer. Cela peut se produire si la mémoire tampon spécifiée est trop petite pour contenir la liste de nuages de points/regroupements. Par conséquent, les enregistreurs de pilotes ne doivent pas supposer que la mémoire tampon spécifiée dans le paramètre ScatterGatherListBuffer contient la liste de nuages de points/regroupements. HAL transmet le pointeur de liste de nuages/de collecte correct vers la fonction miniport driver MiniportProcessSGList.

Pour améliorer les performances du système, la liste de points/regroupements est générée à partir des données réseau à partir du début du MDL spécifié au CurrentMdl membre de la structure de NET_BUFFER_DATA associée. Le début des données réseau de la liste SG est décalé par rapport au début de la liste SG par la valeur spécifiée dans la CurrentMdlOffset membre de la structure NET_BUFFER_DATA associée.

Les pilotes miniport doivent appeler la fonction NdisMFreeNetBufferSGList pour libérer une liste de nuages de points/regroupements.

Exigences

Exigence	Valeur
client minimum pris en charge	Prise en charge dans NDIS 6.0 et versions ultérieures.
plateforme cible	Universel
d’en-tête	ndis.h (include Ndis.h)
bibliothèque	Ndis.lib
IRQL	DISPATCH_LEVEL
règles de conformité DDI	Irql_Gather_DMA_Function(ndis)