NdisMRegisterScatterGatherDma, fonction (ndis.h)

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 de bus master miniport appellent la fonction NdisMRegisterScatterGatherDma à partir de MiniportInitializeEx pour initialiser un canal DMA de nuages de points/de collecte.

Syntaxe

NDIS_STATUS NdisMRegisterScatterGatherDma(
  [in]      NDIS_HANDLE              MiniportAdapterHandle,
  [in, out] PNDIS_SG_DMA_DESCRIPTION DmaDescription,
  [out]     PNDIS_HANDLE             NdisMiniportDmaHandle
);

Paramètres

[in] MiniportAdapterHandle

Poignée de miniport que NDIS a passée à MiniportInitializeEx.

[in, out] DmaDescription

Pointeur vers une structure NDIS_SG_DMA_DESCRIPTION. Cette structure décrit les propriétés DMA de nuage de points/regroupements du pilote de miniport. La structure est définie comme suit :

typedef struct _NDIS_SG_DMA_DESCRIPTION {
  NDIS_OBJECT_HEADER  Header;
  ULONG  Flags;
  ULONG  MaximumPhysicalMapping;
  MINIPORT_PROCESS_SG_LIST_HANDLER  ProcessSGListHandler;
  MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE_HANDLER  SharedMemAllocateCompleteHandler;
  ULONG  ScatterGatherListSize;
} NDIS_SG_DMA_DESCRIPTION, *PNDIS_SG_DMA_DESCRIPTION;
 

Cette structure comprend les membres suivants :

Structure NDIS_OBJECT_HEADER de la structure NDIS_SG_DMA_DESCRIPTION. Définissez le membre Type de la structure spécifiée par Header sur NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, le membre Revision sur NDIS_SG_DMA_DESCRIPTION_REVISION_1 et le membre Size sur NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1.

Indicateurs

Ensemble d’indicateurs de bits qui définissent des caractéristiques de nuage de points/de collecte. Définissez ce membre sur le ou au niveau du bit de tous les indicateurs requis.

L’indicateur NDIS_SG_DMA_64_BIT_ADDRESS spécifie que la carte réseau peut utiliser l’adressage 64 bits pour les opérations DMA. Sinon, la carte réseau utilise l’adressage 32 bits.

Définissez ce membre sur zéro si l’adressage 64 bits n’est pas nécessaire.

MaximumPhysicalMapping

Nombre maximal d’octets que la carte réseau peut transférer dans une seule opération DMA. NDIS fournit cette valeur à la couche d’abstraction matérielle (HAL) lors de l’allocation d’un canal DMA, et HAL utilise cette valeur pour déterminer le nombre maximal de registres de carte à réserver pour la carte réseau.

ProcessSGListHandler

Fonction MiniportProcessSGList que NDIS appelle lorsque HAL a terminé de générer la liste de points/de regroupement.

SharedMemAllocateCompleteHandler

The Fonction MiniportSharedMemoryAllocateComplete pour les pilotes miniport qui appellent NdisMAllocateSharedMemoryAsyncEx. Ce champ est facultatif et doit être NULL si le pilote miniport n’appelle pas NdisMAllocateSharedMemoryAsyncEx.

ScatterGatherListSize

Taille, en octets, de la mémoire nécessaire pour contenir une liste de points/regroupements. NDIS définit cette valeur avant qu’elle ne retourne à partir de NdisMRegisterScatterGatherDma. Les pilotes miniport doivent utiliser cette taille pour préallouer de la mémoire pour chaque liste de points/regroupements.

[out] NdisMiniportDmaHandle

Pointeur vers une variable que l’appelant fournit et que NDIS remplit avec un handle. Le handle identifie une zone de contexte que NDIS utilise pour gérer cette ressource DMA. Le pilote miniport transmet ce handle à NDIS dans les appels ultérieurs à NDIS qui impliquent cette ressource DMA.

Valeur retournée

NdisMRegisterScatterGatherDma retourne l’une des valeurs suivantes :

Code de retour Description
NDIS_STATUS_SUCCESS
NdisMRegisterScatterGatherDma a correctement alloué des ressources pour les opérations DMA master bus.
NDIS_STATUS_RESOURCES
Échec de NdisMRegisterScatterGatherDma en raison de ressources insuffisantes.
NDIS_STATUS_NOT_SUPPORTED
Échec de NdisMRegisterScatterGatherDma, car le miniport n’a pas spécifié qu’il prend en charge NDIS 6.0 ou versions ultérieures, ou parce que le pilote miniport n’a pas spécifié que sa carte réseau est un périphérique DMA master bus. Un pilote miniport spécifie sa version NDIS lorsqu’il appelle NdisMRegisterMiniportDriver. Un pilote miniport spécifie qu’il prend en charge les appareils DMA master bus lorsqu’il appelle NdisMSetMiniportAttributes.
NDIS_STATUS_BAD_VERSION
La version actuelle de NDIS ne prend pas en charge la version spécifiée dans le membre Revision de la structure d’en-tête de DmaDescription .

Remarques

Un pilote miniport master bus NDIS appelle NdisMRegisterScatterGatherDma dans sa fonction MiniportInitializeEx pour initialiser les ressources pour les opérations DMA de nuage de points/de collecte. Le paramètre DmaDescription que le pilote miniport transmet à NdisMRegisterScatterGatherDma contient les informations que NDIS utilise pour initialiser les ressources DMA de nuages de points/de collecte. Une fois que NdisMRegisterScatterGatherDma est retourné, le membre ScatterGatherListSize de DmaDescription contient une taille de mémoire tampon qui doit être suffisante pour contenir une liste de points/regroupements. Les pilotes miniport doivent utiliser cette taille pour préallouer la mémoire pour les listes de points/regroupements.

Le membre ProcessSGListHandler dans le paramètre DmaDescription définit le point d’entrée dans le pilote miniport pour la fonction MiniportProcessSGList . Quand un pilote miniport appelle NdisMAllocateNetBufferSGList, NDIS appelle HAL pour fournir la liste de points/regroupements au pilote miniport. HAL appelle MiniportProcessSGList une fois que HAL a fini de générer la liste de points/regroupements. NDIS peut appeler MiniportProcessSGList en dehors du contexte de l’appel à NdisMAllocateNetBufferSGList.

NdisMRegisterScatterGatherDma retourne un pointeur vers une zone de contexte opaque pour le pilote miniport. Le pilote miniport doit utiliser ce handle dans les appels suivants aux fonctions DMA de nuage de points/de collecte NDIS.

Les chauffeurs master miniports appellent NdisMAllocateSharedMemoryAsyncEx pour allouer dynamiquement de la mémoire partagée pour les opérations de transfert de données. Cet appel est nécessaire lorsque le trafic réseau élevé entraîne une faible exécution du pilote miniport sur l’espace mémoire partagé alloué par le pilote lors de l’initialisation. Si NdisMAllocateSharedMemoryAsyncEx retourne NDIS_STATUS_PENDING, NDIS appelle le Fonction MiniportSharedMemoryAllocateComplete pour terminer l’opération ultérieurement. Les pilotes Miniport spécifient le point d’entrée de la fonction MiniportSharedMemoryAllocateComplete dans le membre SharedMemAllocateCompleteHandler du paramètre DmaDescription .

Les pilotes miniport appellent le Fonction NdisMDeregisterScatterGatherDma pour libérer les ressources DMA allouées par NdisMRegisterScatterGatherDma .

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 PASSIVE_LEVEL
Règles de conformité DDI Init_RegisterSG(ndis), Irql_Gather_DMA_Function(ndis)

Voir aussi

MiniportInitializeEx

MiniportProcessSGList

MiniportSharedMemoryAllocateComplete

NDIS Scatter/Collect DMA

NDIS_OBJECT_HEADER

NdisMAllocateNetBufferSGList

NdisMAllocateSharedMemoryAsyncEx NdisMDeregisterScatterGatherDma

NdisMRegisterMiniportDriver

NdisMSetMiniportAttributes