Fonction NdisMAllocateNetBufferSGList (ndis.h)

Article
02/26/2024

Attention

Pour les processeurs ARM et ARM64, nous recommandons vivement que les enregistreurs de pilotes NDIS utilisent WDF DMA ou WDM DMA au lieu de NDIS Scatter/Gather 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 La gestion des entrées/sorties pour les pilotes.

Les pilotes miniports master bus appellent la fonction NdisMAllocateNetBufferSGList pour obtenir une liste 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 dans une zone de contexte que NDIS utilise 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 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 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 que HAL a créé la liste de points/regroupements. L’appelant peut utiliser cette zone de contexte à ses propres fins.

[in] Flags

Indicateurs NDIS pouvant ê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 défini, indique que le sens du transfert DMA est de la NET_BUFFER vers l’appareil. Si NDIS_SG_LIST_WRITE_TO_DEVICE est clair, le transfert se fait à partir de l’appareil. Les pilotes miniport doivent définir cet indicateur sur le chemin d’envoi lorsque l’opération DMA transfère des données d’un NET_BUFFER vers 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 pour le déchargement de cheminée pendant les opérations de réception, doivent effacer cet indicateur.

[in, optional] ScatterGatherListBuffer

Si ce n’est pas NULL, ScatterGatherListBuffer spécifie un pointeur vers le stockage que l’appelant alloue pour contenir la liste de points/regroupements. Si la valeur est NULL, NDIS alloue le stockage pour la liste de points/regroupements.

[in] ScatterGatherListBufferSize

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

Valeur retournée

NdisMAllocateNetBufferSGList retourne l’un des éléments suivants :

Code de retour	Description
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList a correctement créé la liste de points/regroupements pour la structure NET_BUFFER spécifiée.
NDIS_STATUS_RESOURCES	NdisMAllocateNetBufferSGList a échoué en raison de ressources insuffisantes.

Remarques

Un pilote miniport master bus NDIS appelle NdisMAllocateNetBufferSGList à partir de son Fonction MiniportSendNetBufferLists . 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 points/regroupements. Une fois que HAL a généré la liste de points/regroupements, il appelle la fonction MiniportProcessSGList que le pilote miniport a inscrite 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 points/regroupements tant qu’une fois que HAL a appelé MiniportProcessSGList.

Pour améliorer les performances du système, les pilotes miniport doivent préallouer les mémoires tampons pour les utiliser dans le paramètre ScatterGatherListBuffer de NdisMAllocateNetBufferSGList. NDIS fournit la taille recommandée pour les mémoires tampons dans le membre ScatterGatherListSize 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 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 points/regroupements. HAL transmet le pointeur de liste de points/regroupements correct à la fonction MiniportProcessSGList du pilote miniport .

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 membre CurrentMdl de la structure NET_BUFFER_DATA associée. Le début des données réseau dans la liste SG est décalé par rapport au début de la liste SG par la valeur spécifiée dans le membre CurrentMdlOffset de la structure NET_BUFFER_DATA associée.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.0 et versions ultérieures.
Plateforme cible	Universal
En-tête	ndis.h (inclure Ndis.h)
Bibliothèque	Ndis.lib
IRQL	DISPATCH_LEVEL
Règles de conformité DDI	Irql_Gather_DMA_Function(ndis)