NdisMRegisterScatterGatherDma, fonction (ndis.h)
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 principaux de bus appellent la fonction NdisMRegisterScatterGatherDma de MiniportInitializeEx pour initialiser un canal DMA de nuages de points/collecter.
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 passée à MiniportInitializeEx.
[in, out] DmaDescription
Pointeur vers une structure NDIS_SG_DMA_DESCRIPTION. Cette structure décrit les propriétés DMA de nuages/de points du pilote 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 pour la structure NDIS_SG_DMA_DESCRIPTION. Définissez le membre type de la structure spécifiée par -en-tête sur NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, le membre Révision sur NDIS_SG_DMA_DESCRIPTION_REVISION_1 et le membre Size sur NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1.
Drapeaux
Ensemble d’indicateurs de bits qui définissent des caractéristiques de nuage de points/de collecte. Définissez ce membre sur l’or 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
La fonction MiniportProcessSGList que NDIS appelle lorsque HAL génère la liste de nuages de points/regroupements.
SharedMemAllocateCompleteHandler
Le MiniportSharedMemoryAllocateComplete fonction pour les pilotes miniports 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 requise pour contenir une liste de nuages de points/regroupements. NDIS définit cette valeur avant de retourner à partir de NdisMRegisterScatterGatherDma. Les pilotes miniport doivent utiliser cette taille pour préallouer la mémoire pour chaque liste de nuages 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 utilisée par NDIS pour gérer cette ressource DMA. Le pilote miniport transmet ce handle à NDIS dans les appels suivants à NDIS qui impliquent cette ressource DMA.
Valeur de retour
NdisMRegisterScatterGatherDma retourne l’une des valeurs suivantes :
| Retourner le code | Description |
|---|---|
|
NdisMRegisterScatterGatherDma ressources allouées avec succès pour les opérations DMA de bus-master. |
|
NdisMRegisterScatterGatherDma a échoué en raison de ressources insuffisantes. |
|
NdisMRegisterScatterGatherDma a échoué, 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 maître de 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 maître de bus lorsqu’il appelle NdisMSetMiniportAttributes. |
|
La version actuelle de NDIS ne prend pas en charge la version spécifiée dans le membre révision de la structure d’en-tête de DmaDescription . |
Remarques
Un pilote miniport NDIS bus-master appelle NdisMRegisterScatterGatherDma dans sa fonction MiniportInitializeEx pour initialiser les ressources pour les opérations DMA de nuage de points/collecter. Le paramètre DmaDescription que le pilote miniport transmet à NdisMRegisterScatterGatherDma contient les informations utilisées par NDIS pour initialiser les ressources DMA de nuages de points/collecter. Une fois NdisMRegisterScatterGatherDma renvoie, le membre ScatterGatherListSize de DmaDescription contient une taille de mémoire tampon suffisante pour contenir une liste de nuages de points/regroupements. Les pilotes miniport doivent utiliser cette taille pour préallouer la mémoire pour les listes de nuages 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 nuages de points/collecte au pilote miniport. HAL appelle MiniportProcessSGList une fois que HAL a terminé la création de la liste de nuages 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 au pilote miniport. Le pilote miniport doit utiliser ce handle dans les appels suivants aux fonctions DMA de nuage de points/collecte NDIS.
Appel de pilotes miniports bus-master 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 l’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 MiniportSharedMemoryAllocateComplete fonction pour terminer l’opération ultérieurement. Les pilotes Miniport spécifient le point d’entrée de la fonction MiniportSharedMemoryAllocateComplete dans le SharedMemAllocateCompleteHandler membre du paramètre DmaDescription.
Les pilotes miniport appellent le fonction NdisMDeregisterScatterGatherDma pour libérer les ressources DMA qui NdisMRegisterScatterGatherDma allouées.
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 | PASSIVE_LEVEL |
| règles de conformité DDI | Init_RegisterSG(ndis), Irql_Gather_DMA_Function(ndis) |