NdisMAllocateSharedMemory, fonction (ndis.h)

Article
02/29/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.

NdisMAllocateSharedMemory alloue et mappe une plage de mémoire hôte afin que la plage de mémoire soit simultanément accessible à partir du système hôte et d’une carte réseau DMA.

Syntaxe

void NdisMAllocateSharedMemory(
  [in]  NDIS_HANDLE            MiniportAdapterHandle,
  [in]  ULONG                  Length,
  [in]  BOOLEAN                Cached,
  [out] PVOID                  *VirtualAddress,
  [out] PNDIS_PHYSICAL_ADDRESS PhysicalAddress
);

Paramètres

[in] MiniportAdapterHandle

Spécifie l’entrée de handle dans MiniportInitializeEx.

[in] Length

Spécifie le nombre d'octets à allouer.

[in] Cached

Ce paramètre est ignoré (la mémoire mise en cache est toujours utilisée sur les systèmes x86 et x64).

[out] VirtualAddress

Pointeur vers une variable fournie par l’appelant dans laquelle cette fonction retourne l’adresse virtuelle de base de l’allocation pour une utilisation par le pilote miniport. Si NdisMAllocateSharedMemory ne peut pas satisfaire son appelant, il retourne NULL pour indiquer qu’aucune mémoire n’a été allouée.

[out] PhysicalAddress

Pointeur vers une variable fournie par l’appelant dans laquelle cette fonction retourne une adresse physique, adaptée à une utilisation par la carte réseau, qui correspond à celle retournée dans VirtualAddress, ou elle retourne NULL.

Valeur de retour

None

Remarques

Note Un pilote miniport doit déjà avoir appelé NdisMRegisterScatterGatherDma ou NdisMRegisterDmaChannel pour initialiser un canal DMA de nuages de points/de collecte avant d’appeler NdisMAllocateSharedMemory.

Microsoft Windows Server 2003, Windows XP Service Pack 1 et versions ultérieures de Windows autorisent les cartes réseau DMA master bus et les cartes réseau DMA subordonnées à appeler NdisMAllocateSharedMemory. Les versions antérieures autorisent uniquement les cartes réseau DMA master bus à appeler NdisMAllocateSharedMemory. Dans ces versions précédentes, si MiniportInitializeEx n’a pas spécifié que la carte réseau est un bus master lorsqu’elle s’appelait NdisMSetMiniportAttributes, NdisMAllocateSharedMemory retourne simplement le contrôle sans tenter d’effectuer une allocation.

NdisMAllocateSharedMemory fournit à la fois la plage d’adresses virtuelles mappées que le pilote utilise pour accéder au bloc de mémoire partagée et la plage de type NDIS_PHYSICAL_ADDRESS utilisée par la carte réseau. Une valeur retournée dans PhysicalAddress peut être doublement mappée par le système. Autrement dit, une plage d’adresses « physique » décrite par la valeur dans PhysicalAddress et Length peut être une plage d’adresses logiques mappées qui ne correspondent pas aux adresses physiques de l’hôte pour l’allocation dans chaque plateforme possible.

NdisMAllocateSharedMemory peut être appelé uniquement à partir de MiniportInitializeEx. La taille d’une allocation à demander dépend de la façon dont l’enregistreur de pilotes, connaissant les fonctionnalités et les fonctionnalités de la carte réseau, décide de faire le compromis entre le dilemme de performances et de taille suivant :

En période de trafic réseau élevé, un pilote miniport ne peut pas maintenir un débit d’E/S élevé s’il dispose d’un faible espace mémoire partagé pour les mémoires tampons de données accessibles aux appareils.
Par exemple, le pilote miniport peut indiquer que les mémoires tampons de réception dans la mémoire partagée sont plus rapides que ces mémoires tampons sont retournées par les pilotes de protocole lié lorsqu’un flot de réceptions arrive dans une carte réseau. Si tout son espace de mémoire partagée est consommé par les mémoires tampons de réception en attente, le pilote miniport peut avoir à désactiver les interruptions de réception sur une carte réseau jusqu’à ce qu’il dispose d’un espace de mémoire partagé disponible pour les mémoires tampons de réception.
D’autre part, l’appel de NdisMAllocateSharedMemory avec une longueur choisie pour anticiper une demande de transfert maximale rend l’image du pilote plus grande et son utilisation des ressources assez peu rentable, à l’exception de rares périodes de très forte demande d’E/S. En outre, NdisMAllocateSharedMemory peut ne pas donner au pilote un bloc aussi volumineux si la mémoire système est insuffisante, ce qui force le pilote à échouer l’initialisation.

Un pilote miniport qui fournit un La fonction MiniportSharedMemoryAllocateComplete offre beaucoup plus de flexibilité dans la résolution du dilemme précédent entre les performances et la taille. MiniportInitializeEx doit allouer uniquement suffisamment de mémoire partagée avec NdisMAllocateSharedMemory pour une demande modérée d’opérations de transfert réseau via la carte réseau si le pilote a une fonction MiniportSharedMemoryAllocateComplete . Un tel pilote miniport peut appeler NdisMAllocateSharedMemoryAsyncEx de manière dynamique pour allouer plus de mémoire partagée en période de demande de transfert plus importante sur une carte réseau. Lorsque la demande élevée de transferts s’est calmée, un tel pilote appelle NdisMFreeSharedMemory pour libérer la mémoire supplémentaire allouée. Notez que seules les cartes réseau DMA master bus peuvent appeler NdisMAllocateSharedMemoryAsyncEx et exporter MiniportSharedMemoryAllocateComplete. Cette fonctionnalité n’est pas prise en charge pour les cartes réseau DMA subordonnées.

NdisMAllocateSharedMemory et NdisMAllocateSharedMemoryAsyncEx sont les seules fonctions NdisXxx qui peuvent être appelées pour allouer la mémoire de l’hôte partagée entre le pilote, qui utilise des adresses virtuelles, et une carte réseau, qui utilise les adresses logiques correspondantes.

Un pilote miniport doit aligner les mémoires tampons qu’il alloue à partir de la mémoire mise en cache partagée sur une partie intégrante de la limite de ligne de cache de données de l’hôte pour empêcher la déchirure de la ligne de cache pendant L’authentification DMA. La déchirure de ligne de cache peut entraîner des problèmes d’intégrité des données dans le pilote ou dégrader les performances d’E/S du pilote (et du système) en exigeant un vidage excessif du cache des données pour maintenir l’intégrité des données. MiniportInitializeEx peut appeler NdisMGetDmaAlignment pour déterminer la limite d’alignement dans la plateforme actuelle pour les mémoires tampons accessibles aux appareils que le pilote configurera dans une plage de mémoire partagée allouée.

Un pilote miniport doit définir une limite sur la quantité de mémoire partagée qu’il peut allouer. Cette limite est spécifique au pilote et doit être suffisamment élevée pour que le pilote ne soit pas à court de mémoires tampons. Ne définissez pas de limite excessivement élevée, car cela pourrait entraîner un gaspillage de la mémoire partagée qui pourrait réduire les performances du système.

MiniportInitializeEx peut également appeler NdisSystemProcessorCount avant d’appeler NdisMAllocateSharedMemory si l’enregistreur de pilotes décide d’allouer un bloc de mémoire partagée plus important dans les ordinateurs multiprocesseurs en supposant qu’une machine SMP est susceptible d’être un serveur réseau avec des demandes de transfert réseau plus élevées sur la carte réseau qu’une station de travail.

Si son appel à NdisMAllocateSharedMemory échoue, MiniportInitializeEx peut appeler à nouveau en demandant une allocation plus petite. Toutefois, si MiniportInitializeEx ne peut pas allouer suffisamment de mémoire partagée pour la carte réseau, il doit libérer toutes les ressources qu’il a déjà allouées et échouer l’initialisation.

Si le pilote miniport indique par la suite reçoit avec NdisMIndicateReceiveNetBufferLists, il doit allouer un certain nombre de descripteurs de mémoire tampon à partir du pool de mémoires tampons qui mappent les mémoires tampons de réception de la carte réseau dans le bloc de mémoire partagée.

Si la mémoire allouée est mise en cache et, par conséquent, doit être vidée lors des transferts, le pilote miniport doit appeler NdisAllocateMdl pour allouer un descripteur de type NDIS_BUFFER pour la plage de mémoire partagée. Le pilote miniport doit appeler KeFlushIoBuffers avec ce descripteur de mémoire tampon pour effectuer un tel vidage.

Si un pilote miniport appelle NdisMAllocateSharedMemoryAsyncEx ou NdisMAllocateSharedMemory. Il doit libérer toutes les allocations en attente avec un ou plusieurs appels à NdisMFreeSharedMemory lorsqu’une carte réseau est supprimée, c’est-à-dire lorsque sa fonction MiniportHaltEx est appelée.

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