Fonction NdisMAllocateSharedMemoryAsyncEx (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 Miniport appellent la fonction NdisMAllocateSharedMemoryAsyncEx pour allouer une mémoire supplémentaire partagée entre le pilote et sa carte réseau DMA master bus, généralement lorsque le pilote miniport est faible sur les mémoires tampons de réception de carte réseau disponibles.

Syntaxe

NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx(
  [in] NDIS_HANDLE MiniportDmaHandle,
  [in] ULONG       Length,
  [in] BOOLEAN     Cached,
  [in] PVOID       Context
);

Paramètres

[in] MiniportDmaHandle

Handle pour une zone de contexte que NDIS utilise pour gérer une ressource DMA. L’appelant a obtenu ce handle en appelant le NdisMRegisterScatterGatherDma , fonction.

[in] Length

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).

[in] Context

Pointeur vers le contexte déterminé par le pilote à passer à la fonction MiniportSharedMemoryAllocateComplete lorsqu’elle est appelée.

Valeur retournée

NdisMAllocateSharedMemoryAsyncEx peut retourner l’un des éléments suivants :

Code de retour	Description
NDIS_STATUS_PENDING	NDIS appelle la fonction MiniportSharedMemoryAllocateComplete et fournit des informations décrivant la mémoire partagée allouée. Si la tentative d’allocation de mémoire partagée échoue, NDIS appelle MiniportSharedMemoryAllocateComplete et transmet des pointeurs NULL .
NDIS_STATUS_FAILURE	La mémoire demandée n’a pas pu être allouée pour l’instant. Si NdisMAllocateSharedMemoryAsyncEx retourne cette status, un appel suivant avec les mêmes paramètres peut réussir, selon que les ressources système sont ou non disponibles.

Remarques

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

Les pilotes des cartes réseau DMA master bus appellent NdisMAllocateSharedMemoryAsyncEx pour allouer dynamiquement de la mémoire partagée. Ces pilotes allouent également de l’espace mémoire partagé lors de l’initialisation. Ces pilotes utilisent la mémoire partagée allouée dynamiquement pour les opérations de transfert lorsque le trafic réseau élevé impose des demandes excessives sur l’espace de mémoire partagé existant.

Ce pilote miniport gère généralement une ou plusieurs variables d’état pour suivre le nombre de mémoires tampons de mémoire partagée disponibles pour les transferts entrants. Lorsque le nombre de mémoires tampons disponibles atteint un niveau faible déterminé par le pilote, le pilote miniport appelle NdisMAllocateSharedMemoryAsyncEx pour allouer plus d’espace de mémoire tampon dans la mémoire partagée. Lorsque le nombre de mémoires tampons disponibles atteint un niveau élevé déterminé par le pilote, le pilote miniport appelle NdisMFreeSharedMemory une ou plusieurs fois pour libérer ses allocations dynamiques précédentes.

En règle générale, un tel pilote miniport conserve le bloc de mémoire partagée que sa fonction MiniportInitializeEx allouée avec NdisMAllocateSharedMemory jusqu’à ce qu’une carte réseau soit supprimée. Lorsque la carte réseau est supprimée, NDIS appelle la fonction MiniportHaltEx du pilote miniport. Cette allocation est suffisante pour gérer une demande moyenne de transferts via la carte réseau.

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 placez pas une 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.

Tout pilote miniport qui appelle NdisMAllocateSharedMemoryAsyncEx ou NdisMAllocateSharedMemory doit libérer toutes les allocations en suspens avec un ou plusieurs appels à NdisMFreeSharedMemory lorsque sa carte réseau est supprimé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)
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	Irql_Gather_DMA_Function(ndis)