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 :
En-tête
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 |
|---|---|
|
NdisMRegisterScatterGatherDma a correctement alloué des ressources pour les opérations DMA master bus. |
|
Échec de NdisMRegisterScatterGatherDma en raison de ressources insuffisantes. |
|
É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. |
|
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) |